Add bulk delete and OAuth 2.0 enhancements

Author: ujibang

docs/mongodb-rest/files.adoc

@@ -472,6 +472,8 @@ NOTE: Update operators and aggregation pipelines cannot be used with file metada
 
 === Deleting Files
 
+==== DELETE - Single File
+
 To delete a file and all its chunks:
 
 ==== cURL
@@ -510,6 +512,59 @@ fetch('[RESTHEART-URL]/mybucket.files/my-custom-id', {
 .catch(error => console.error('Error:', error));
 ----
 
+==== DELETE - Bulk Delete by Filter
+
+NOTE: Bulk delete for file buckets is available from RESTHeart v9.2.0.
+
+To delete multiple files at once, use the wildcard `*` path with a `filter` query parameter. This atomically removes both the `.files` metadata documents and their associated `.chunks` data for each matching file.
+
+==== cURL
+
+[source,bash]
+----
+curl -i -X DELETE "[RESTHEART-URL]/mybucket.files/*?filter={\"metadata.todelete\":true}" \
+  -H "Authorization: Basic [BASIC-AUTH]"
+----
+
+==== HTTPie
+
+[source,bash]
+----
+http DELETE [RESTHEART-URL]/mybucket.files/'*' \
+  Authorization:"Basic [BASIC-AUTH]" \
+  filter=='{"metadata.todelete":true}'
+----
+
+==== JavaScript
+
+[source,javascript]
+----
+const filter = encodeURIComponent(JSON.stringify({"metadata.todelete": true}));
+fetch(`[RESTHEART-URL]/mybucket.files/*?filter=${filter}`, {
+  method: 'DELETE',
+  headers: {
+    'Authorization': 'Basic [BASIC-AUTH]'
+  }
+})
+.then(response => response.json())
+.then(data => {
+  console.log(`Deleted ${data.deleted} files`);
+})
+.catch(error => console.error('Error:', error));
+----
+
+[source,http]
+----
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{"deleted": 42}
+----
+
+The response returns the count of deleted files. Omitting the `filter` parameter deletes all files in the bucket.
+
+IMPORTANT: The `filter` applies to the `.files` collection, including `metadata.*` sub-fields (e.g., `{"metadata.category":"temp"}`).
+
 === Important Notes
 
 1. RESTHeart automatically detects and sets the file's content type

docs/security/how-clients-authenticate.adoc

@@ -19,7 +19,8 @@ In this guide, you'll learn how to:
 
 . Authenticate using Basic Authentication with username and password
 . Understand how the Authorization header works
-. Use authentication tokens for subsequent requests
+. Use authentication tokens for subsequent requests (password and client_credentials grant types)
+. Auto-discover server metadata via the RFC 8414 discovery endpoint
 . Manage authentication tokens (retrieve and invalidate)
 . Check user credentials and roles
 . Avoid browser authentication popups
@@ -110,8 +111,9 @@ RESTHeart v9 introduces dedicated OAuth 2.0-compatible token endpoints for secur
 
 **Available Endpoints:**
 
-* `POST /token` - Returns JWT token in response body (OAuth 2.0 Resource Owner Password Credentials Grant)
+* `POST /token` - Returns JWT token in response body (supports `password` and `client_credentials` grant types)
 * `POST /token/cookie` - Sets JWT token as HttpOnly cookie (enhanced security for browser-based apps)
+* `GET /.well-known/oauth-authorization-server` - Returns server metadata for client auto-discovery (RFC 8414)
 
 **Benefits:**
 
@@ -173,9 +175,9 @@ fetch('[RESTHEART-URL]/token', {
 }
 ----
 
-===== OAuth 2.0 Form Data Method
+===== OAuth 2.0 Form Data Method (Resource Owner Password Credentials)
 
-Send credentials using OAuth 2.0 form data (application/x-www-form-urlencoded):
+Send credentials using OAuth 2.0 form data (application/x-www-form-urlencoded) with `grant_type=password` (RFC 6749 §4.3):
 
 ==== cURL
 [source,bash]
@@ -218,6 +220,70 @@ fetch('[RESTHEART-URL]/token', {
 .catch(error => console.error('Error:', error));
 ----
 
+===== Client Credentials Grant
+
+NOTE: `client_credentials` grant type support is available from RESTHeart v9.2.0.
+
+For machine-to-machine or service-account authentication, use `grant_type=client_credentials` (RFC 6749 §4.4).
+Pass `client_id` and `client_secret` in the request body instead of `username` and `password`.
+This is the recommended approach for API gateways, CLI tools, and MCP clients.
+
+==== cURL
+[source,bash]
+----
+curl -i -X POST [RESTHEART-URL]/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=client_credentials&client_id=myapp&client_secret=s3cret"
+----
+
+==== HTTPie
+[source,bash]
+----
+http -f POST [RESTHEART-URL]/token \
+  grant_type=client_credentials \
+  client_id=myapp \
+  client_secret=s3cret
+----
+
+==== JavaScript
+[source,javascript]
+----
+const formData = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: 'your-client-id',
+    client_secret: 'your-client-secret'
+});
+
+fetch('[RESTHEART-URL]/token', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/x-www-form-urlencoded'
+    },
+    body: formData
+})
+.then(response => response.json())
+.then(data => {
+    console.log('Access token:', data.access_token);
+    console.log('Expires in:', data.expires_in, 'seconds');
+})
+.catch(error => console.error('Error:', error));
+----
+
+The response format is identical to the password grant:
+
+[source,json]
+----
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 900,
+  "username": "myapp",
+  "roles": ["service"]
+}
+----
+
+NOTE: `client_id` and `client_secret` are mapped to the user credentials in the configured authenticator (e.g., `mongoRealmAuthenticator`). The client account must exist in the user store just like a regular user account.
+
 ===== Using the Token
 
 Once you have the token, use it as a Bearer token in the Authorization header:
@@ -360,6 +426,47 @@ jwtTokenManager:
 
 IMPORTANT: Always change the `key` value in production to a strong, random secret.
 
+===== OAuth 2.0 Authorization Server Metadata Discovery (RFC 8414)
+
+NOTE: The authorization server metadata discovery endpoint is available from RESTHeart v9.2.0.
+
+RESTHeart exposes a standards-compliant metadata discovery endpoint at `GET /.well-known/oauth-authorization-server` (RFC 8414).
+This allows OAuth 2.0 clients to auto-configure themselves without hardcoded URLs.
+
+==== cURL
+[source,bash]
+----
+curl -i [RESTHEART-URL]/.well-known/oauth-authorization-server
+----
+
+==== HTTPie
+[source,bash]
+----
+http GET [RESTHEART-URL]/.well-known/oauth-authorization-server
+----
+
+**Response:**
+
+[source,json]
+----
+{
+  "issuer": "http://localhost:8080",
+  "token_endpoint": "http://localhost:8080/token",
+  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
+  "grant_types_supported": ["password", "client_credentials"],
+  "response_types_supported": ["token"]
+}
+----
+
+The endpoint is publicly accessible (no authentication required) and the base URL is derived from the request `Host` header by default.
+You can override it with the `base-url` configuration option:
+
+[source,yml]
+----
+oauthAuthorizationServerMetadataService:
+  base-url: https://api.example.com  # optional, falls back to request Host header
+----
+
 ==== Legacy Token Management (Automatic Injection)
 
 NOTE: This is the legacy token management approach. For new applications, use the OAuth 2.0 `/token` endpoint described above.