Harden auth, redaction, upload size checks, and compose token requirements

doc/api-contract.md

@@ -10,6 +10,17 @@ Primary implementation modules:
 - `backend/app/api/routes_processing_logs.py`
 - `backend/app/api/routes_settings.py`
 
+## Authentication And Authorization
+
+- Protected endpoints require `Authorization: Bearer <token>`.
+- `ADMIN_API_TOKEN` is required for all privileged access and acts as fail-closed root credential.
+- `USER_API_TOKEN` is optional and, when configured, grants access to document endpoints only.
+- Authorization matrix:
+  - `documents/*`: `admin` or `user`
+  - `search/*`: `admin` or `user`
+  - `settings/*`: `admin` only
+  - `processing/logs/*`: `admin` only
+
 ## Health
 
 - `GET /health`
@@ -18,6 +29,8 @@ Primary implementation modules:
 
 ## Documents
 
+- Access: admin or user token required
+
 ### Collection and metadata helpers
 
 - `GET /documents`
@@ -76,9 +89,13 @@ Primary implementation modules:
   - `ask`: returns `conflicts` if duplicate checksum is detected
   - `replace`: creates new document linked to replaced document id
   - `duplicate`: creates additional document record
+  - request rejected with `411` when `Content-Length` is missing
+  - request rejected with `413` when file count, per-file size, or total request size exceeds configured limits
 
 ## Search
 
+- Access: admin or user token required
+
 - `GET /search`
 - Query: `query` (min length 2), `offset`, `limit`, `include_trashed`, `only_trashed`, `path_filter`, `tag_filter`, `type_filter`, `processed_from`, `processed_to`
 - Response model: `SearchResponse`
@@ -86,23 +103,31 @@ Primary implementation modules:
 
 ## Processing Logs
 
+- Access: admin token required
+
 - `GET /processing/logs`
   - Query: `offset`, `limit`, `document_id`
   - Response model: `ProcessingLogListResponse`
+  - `limit` is capped by runtime configuration
+  - sensitive fields are redacted in API responses
 - `POST /processing/logs/trim`
   - Query: optional `keep_document_sessions`, `keep_unbound_entries`
   - Behavior: omitted query values fall back to persisted `/settings.processing_log_retention`
+  - query values are capped by runtime retention limits
   - Response: trim counters
 - `POST /processing/logs/clear`
   - Response: clear counters
 
 ## Settings
 
+- Access: admin token required
+
 - `GET /settings`
   - Response model: `AppSettingsResponse`
 - `PATCH /settings`
   - Body model: `AppSettingsUpdateRequest`
   - Response model: `AppSettingsResponse`
+  - rejects invalid provider base URLs with `400` when scheme, allowlist, or network safety checks fail
 - `POST /settings/reset`
   - Response model: `AppSettingsResponse`
 - `PATCH /settings/handwriting`