Nautilus/ledgerdock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Harden auth and security controls with session auth and docs

Browse Source
This commit is contained in:
Beda Schmid
2026-03-01 15:29:09 -03:00
parent 7a19f22f41
commit 0242e061c2
36 changed files with 1794 additions and 505 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
doc/README.md
View File

@@ -6,7 +6,8 @@ This directory contains technical documentation for DMS.
- `../README.md` - project overview, setup, and quick operations
- `architecture-overview.md` - backend, frontend, and infrastructure architecture
- `api-contract.md` - API endpoint contract grouped by route module, including token auth roles, upload limits, and settings or processing-log security constraints
- `api-contract.md` - API endpoint contract grouped by route module, including session auth, role and ownership scope, upload limits, and settings or processing-log security constraints
- `data-model-reference.md` - database entity definitions and lifecycle states
- `operations-and-configuration.md` - runtime operations, hardened compose defaults, security environment variables, and persisted settings configuration and read-sanitization behavior
- `frontend-design-foundation.md` - frontend visual system, tokens, UI implementation rules, authenticated media delivery under API token auth, processing-log timeline behavior, and settings helper-copy guidance
- `operations-and-configuration.md` - runtime operations, hardened compose defaults, DEV and LIVE security values, and persisted settings configuration behavior
- `frontend-design-foundation.md` - frontend visual system, tokens, UI implementation rules, authenticated media delivery under session auth, processing-log timeline behavior, and settings helper-copy guidance
- `../.env.example` - repository-level environment template with local defaults and production override guidance

67
doc/api-contract.md
View File

@@ -4,6 +4,7 @@ Base URL prefix: `/api/v1`
Primary implementation modules:
- `backend/app/api/router.py`
- `backend/app/api/routes_auth.py`
- `backend/app/api/routes_health.py`
- `backend/app/api/routes_documents.py`
- `backend/app/api/routes_search.py`
@@ -12,15 +13,32 @@ Primary implementation modules:
## Authentication And Authorization
- Protected endpoints require `Authorization: Bearer <token>` in production.
- Development deployments can allow tokenless user-role access for `documents/*` and `search/*` when `ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS=true`.
- `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
- Authentication is session-based bearer auth.
- Clients authenticate with `POST /auth/login` using username and password.
- Backend issues per-user bearer session tokens and stores hashed session state server-side.
- Clients send issued tokens as `Authorization: Bearer <token>`.
- `GET /auth/me` returns current identity and role.
- `POST /auth/logout` revokes current session token.
Role matrix:
- `documents/*`: `admin` or `user`
- `search/*`: `admin` or `user`
- `settings/*`: `admin` only
- `processing/logs/*`: `admin` only
Ownership rules:
- `user` role is restricted to its own documents.
- `admin` role can access all documents.
## Auth
- `POST /auth/login`
- Body model: `AuthLoginRequest`
- Response model: `AuthLoginResponse`
- `GET /auth/me`
- Response model: `AuthSessionResponse`
- `POST /auth/logout`
- Response model: `AuthLogoutResponse`
## Health
@@ -30,9 +48,6 @@ Primary implementation modules:
## Documents
- Access: admin or user token required (production)
- Access: admin or user token, or development tokenless user fallback when enabled
### Collection and metadata helpers
- `GET /documents`
@@ -50,6 +65,11 @@ Primary implementation modules:
- `POST /documents/content-md/export`
- Body model: `ContentExportRequest`
- Response: ZIP stream containing one markdown file per matched document
- Limits:
- hard cap on matched document count (`CONTENT_EXPORT_MAX_DOCUMENTS`)
- hard cap on cumulative markdown bytes (`CONTENT_EXPORT_MAX_TOTAL_BYTES`)
- per-user rate limit (`CONTENT_EXPORT_RATE_LIMIT_PER_MINUTE`)
- Behavior: archive is streamed from spool file instead of unbounded in-memory buffer
### Per-document operations
@@ -89,7 +109,7 @@ Primary implementation modules:
- `conflict_mode` (`ask`, `replace`, `duplicate`)
- Response model: `UploadResponse`
- Behavior:
- `ask`: returns `conflicts` if duplicate checksum is detected
- `ask`: returns `conflicts` if duplicate checksum is detected for caller-visible documents
- `replace`: creates new document linked to replaced document id
- `duplicate`: creates additional document record
- upload `POST` request rejected with `411` when `Content-Length` is missing
@@ -98,16 +118,14 @@ Primary implementation modules:
## 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`
- Behavior: PostgreSQL full-text and metadata ranking
- Behavior: PostgreSQL full-text and metadata ranking with role-based ownership scope
## Processing Logs
- Access: admin token required
- Access: admin only
- `GET /processing/logs`
- Query: `offset`, `limit`, `document_id`
@@ -122,9 +140,13 @@ Primary implementation modules:
- `POST /processing/logs/clear`
- Response: clear counters
Persistence mode:
- default is metadata-only logging (`PROCESSING_LOG_STORE_MODEL_IO_TEXT=false`, `PROCESSING_LOG_STORE_PAYLOAD_TEXT=false`)
- full prompt/response or payload content storage requires explicit operator opt-in
## Settings
- Access: admin token required
- Access: admin only
- `GET /settings`
- Response model: `AppSettingsResponse`
@@ -145,6 +167,13 @@ Primary implementation modules:
## Schema Families
Auth schemas in `backend/app/schemas/auth.py`:
- `AuthLoginRequest`
- `AuthUserResponse`
- `AuthSessionResponse`
- `AuthLoginResponse`
- `AuthLogoutResponse`
Document schemas in `backend/app/schemas/documents.py`:
- `DocumentResponse`
- `DocumentDetailResponse`
@@ -160,4 +189,4 @@ Processing log schemas in `backend/app/schemas/processing_logs.py`:
- `ProcessingLogListResponse`
Settings schemas in `backend/app/schemas/settings.py`:
- Provider, task, upload-default, display, processing-log retention, predefined paths or tags, handwriting-style, and legacy handwriting models grouped under `AppSettingsResponse` and `AppSettingsUpdateRequest`.
- provider, task, upload-default, display, processing-log retention, predefined paths or tags, handwriting-style, and legacy handwriting models grouped under `AppSettingsResponse` and `AppSettingsUpdateRequest`.

16
doc/architecture-overview.md
View File

@@ -16,16 +16,16 @@ Backend source root: `backend/app/`
Main boundaries:
- `api/` route handlers and HTTP contract
- `services/` domain logic (storage, extraction, routing, settings, processing logs, Typesense)
- `services/` domain logic (authentication, storage, extraction, routing, settings, processing logs, Typesense)
- `db/` SQLAlchemy base, engine, and session lifecycle
- `models/` persistence entities (`Document`, `ProcessingLogEntry`)
- `models/` persistence entities (`AppUser`, `AuthSession`, `Document`, `ProcessingLogEntry`)
- `schemas/` Pydantic response and request schemas
- `worker/` RQ queue integration and background processing tasks
Application bootstrap in `backend/app/main.py`:
- mounts routers under `/api/v1`
- configures CORS from settings
- initializes storage, settings, database schema, and Typesense collection on startup
- initializes storage, database schema, bootstrap users, settings, and Typesense collection on startup
## Processing Lifecycle
@@ -48,11 +48,12 @@ Core structure:
- `design-foundation.css` and `styles.css` define design tokens and global/component styling
Main user flows:
- Login and role-gated navigation (`admin` and `user`)
- Upload and conflict resolution
- Search and filtered document browsing
- Metadata editing and lifecycle actions (trash, restore, delete, reprocess)
- Settings management for providers, tasks, and UI defaults
- Processing log review
- Settings management for providers, tasks, and UI defaults (admin only)
- Processing log review (admin only)
## Persistence and State
@@ -66,6 +67,11 @@ Transient runtime state:
- frontend local component state drives active filters, selection, and modal flows
Security-sensitive runtime behavior:
- API access is session-based with per-user server-issued bearer tokens and role checks.
- Document and search reads for `user` role are owner-scoped via `owner_user_id`; `admin` can access global scope.
- Redis connection URLs are validated by backend queue helpers with environment-aware auth and TLS policy enforcement.
- Worker startup runs through `python -m app.worker.run_worker`, which validates Redis URL policy before queue consumption.
- Inline preview is limited to safe MIME types and script-capable content is served as attachment-only.
- Archive fan-out processing propagates root and depth lineage metadata and enforces depth and per-root descendant caps.
- Markdown export applies per-user rate limits, hard document-count and total-byte caps, and spool-file streaming.
- Processing logs default to metadata-only persistence, with explicit operator toggles required to store model IO text.

45
doc/data-model-reference.md
View File

@@ -2,6 +2,38 @@
Primary SQLAlchemy models are defined in `backend/app/models/`.
## app_users
Model: `AppUser` in `backend/app/models/auth.py`
Purpose:
- Stores authenticatable user identities for session-based API access.
Core fields:
- Identity and credentials: `id`, `username`, `password_hash`
- Authorization and lifecycle: `role`, `is_active`
- Audit timestamps: `created_at`, `updated_at`
Enum `UserRole`:
- `admin`
- `user`
## auth_sessions
Model: `AuthSession` in `backend/app/models/auth.py`
Purpose:
- Stores issued bearer sessions linked to user identities.
Core fields:
- Identity and linkage: `id`, `user_id`, `token_hash`
- Session lifecycle: `expires_at`, `revoked_at`
- Request context: `user_agent`, `ip_address`
- Audit timestamps: `created_at`, `updated_at`
Foreign keys:
- `user_id` references `app_users.id` with `ON DELETE CASCADE`.
## documents
Model: `Document` in `backend/app/models/document.py`
@@ -12,7 +44,7 @@ Purpose:
Core fields:
- Identity and source: `id`, `original_filename`, `source_relative_path`, `stored_relative_path`
- File attributes: `mime_type`, `extension`, `sha256`, `size_bytes`
- Organization: `logical_path`, `suggested_path`, `tags`, `suggested_tags`
- Ownership and organization: `owner_user_id`, `logical_path`, `suggested_path`, `tags`, `suggested_tags`
- Processing outputs: `extracted_text`, `image_text_type`, `handwriting_style_id`, `preview_available`
- Lifecycle and relations: `status`, `is_archive_member`, `archived_member_path`, `parent_document_id`, `replaces_document_id`
- Metadata and timestamps: `metadata_json`, `created_at`, `processed_at`, `updated_at`
@@ -24,8 +56,12 @@ Enum `DocumentStatus`:
- `error`
- `trashed`
Foreign keys:
- `owner_user_id` references `app_users.id` with `ON DELETE SET NULL`.
Relationships:
- Self-referential `parent_document` relationship for archive extraction trees.
- `owner_user` relationship to `AppUser`.
## processing_logs
@@ -47,7 +83,10 @@ Foreign keys:
## Model Lifecycle Notes
- Upload inserts a `Document` row in `queued` state and enqueues background processing.
- Worker updates extraction results and final status (`processed`, `unsupported`, or `error`).
- API startup initializes schema and creates or refreshes bootstrap users from auth environment variables.
- `POST /auth/login` validates `AppUser` credentials, creates `AuthSession` with hashed token, and returns bearer token once.
- Upload inserts `Document` row in `queued` state, assigns `owner_user_id`, and enqueues background processing.
- Worker updates extraction results and final status (`processed`, `unsupported`, or `error`), preserving ownership on archive descendants.
- User-role queries are owner-scoped; admin-role queries can access all documents.
- Trash and restore operations toggle `status` while preserving source files until permanent delete.
- Permanent delete removes the document tree (including archive descendants) and associated stored files.

3
doc/frontend-design-foundation.md
View File

@@ -52,7 +52,8 @@ Do not hardcode new palette or spacing values in component styles when a token a
## Authenticated Media Delivery
- Document previews and thumbnails must load through authenticated fetch flows in `frontend/src/lib/api.ts`, then render via temporary object URLs.
- Runtime auth should prefer per-user token resolution (`setApiTokenResolver` and `setRuntimeApiToken`) rather than static build-time token distribution, with `VITE_API_TOKEN` used only as fallback compatibility.
- Runtime auth uses server-issued per-user session tokens persisted with `setRuntimeApiToken` and read by `getRuntimeApiToken`.
- Static build-time token distribution is not supported.
- Direct `window.open` calls for protected media endpoints are not allowed because browser navigation requests do not include the API token header.
- Download actions for original files and markdown exports must use authenticated blob fetches plus controlled browser download triggers.
- Revoke all temporary object URLs after replacement, unmount, or completion to prevent browser memory leaks.

222
doc/operations-and-configuration.md
View File

@@ -2,15 +2,13 @@
## Runtime Services
`docker-compose.yml` defines the runtime stack:
- `db` (Postgres 16, internal network only)
- `redis` (Redis 7, internal network only, password-protected)
- `typesense` (Typesense 29, internal network only)
- `api` (FastAPI backend, host-bound port `8000`)
- `worker` (RQ background worker)
- `frontend` (Vite UI, host-bound port `5173`)
## Named Volumes
`docker-compose.yml` defines:
- `db` (Postgres 16)
- `redis` (Redis 7)
- `typesense` (Typesense 29)
- `api` (FastAPI backend)
- `worker` (RQ worker via `python -m app.worker.run_worker`)
- `frontend` (Vite React UI)
Persistent volumes:
- `db-data`
@@ -24,15 +22,15 @@ Reset all persisted runtime data:
docker compose down -v
```
## Operational Commands
## Core Commands
Start or rebuild stack:
Start or rebuild:
```bash
docker compose up --build -d
```
Stop stack:
Stop:
```bash
docker compose down
@@ -44,151 +42,81 @@ Tail logs:
docker compose logs -f
```
Before running compose, provide required credentials in your shell or project `.env` file:
## Authentication Model
```bash
export POSTGRES_USER="dcm"
export POSTGRES_PASSWORD="<random-postgres-password>"
export POSTGRES_DB="dcm"
export DATABASE_URL="postgresql+psycopg://<user>:<password>@db:5432/<db>"
export REDIS_PASSWORD="<random-redis-password>"
export REDIS_URL="redis://:<password>@redis:6379/0"
export ADMIN_API_TOKEN="<random-admin-token>"
export USER_API_TOKEN="<random-user-token>"
export APP_SETTINGS_ENCRYPTION_KEY="<random-settings-encryption-key>"
export TYPESENSE_API_KEY="<random-typesense-key>"
```
- Legacy shared build-time frontend token behavior was removed.
- API now uses server-issued per-user bearer sessions.
- Bootstrap users are provisioned from environment:
- `AUTH_BOOTSTRAP_ADMIN_USERNAME`
- `AUTH_BOOTSTRAP_ADMIN_PASSWORD`
- optional `AUTH_BOOTSTRAP_USER_USERNAME`
- optional `AUTH_BOOTSTRAP_USER_PASSWORD`
- Frontend signs in through `/api/v1/auth/login` and stores issued session token in browser session storage.
Compose fails fast when required credential variables are missing.
## DEV And LIVE Configuration Matrix
## Backend Configuration
Use `.env.example` as baseline. The table below documents user-managed settings and recommended values.
Settings source:
- Runtime settings class: `backend/app/core/config.py`
- API settings persistence: `backend/app/services/app_settings.py`
| Variable | Local DEV (HTTP, docker-only) | LIVE (HTTPS behind reverse proxy) |
| --- | --- | --- |
| `APP_ENV` | `development` | `production` |
| `HOST_BIND_IP` | `127.0.0.1` or local LAN bind if needed | `127.0.0.1` (publish behind proxy only) |
| `PUBLIC_BASE_URL` | `http://localhost:8000` | `https://api.example.com` |
| `VITE_API_BASE` | empty for host-derived `http://<frontend-host>:8000/api/v1`, or explicit local URL | `https://api.example.com/api/v1` |
| `CORS_ORIGINS` | `["http://localhost:5173","http://localhost:3000"]` | exact frontend origins only, for example `["https://app.example.com"]` |
| `CORS_ALLOW_CREDENTIALS` | `false` | `false` (Authorization header flow does not need credentialed CORS) |
| `REDIS_URL` | `redis://:<password>@redis:6379/0` in isolated local network | `rediss://:<password>@redis.internal:6379/0` |
| `REDIS_SECURITY_MODE` | `compat` or `auto` | `strict` |
| `REDIS_TLS_MODE` | `allow_insecure` or `auto` | `required` |
| `PROVIDER_BASE_URL_ALLOW_HTTP` | `true` only when intentionally testing local HTTP provider endpoints | `false` |
| `PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK` | `true` only for trusted local development targets | `false` |
| `PROVIDER_BASE_URL_ALLOWLIST` | allow needed test hosts | explicit production allowlist, for example `["api.openai.com"]` |
| `PROCESSING_LOG_STORE_MODEL_IO_TEXT` | `false` by default; temporary `true` only for controlled debugging | `false` |
| `PROCESSING_LOG_STORE_PAYLOAD_TEXT` | `false` by default; temporary `true` only for controlled debugging | `false` |
| `CONTENT_EXPORT_MAX_DOCUMENTS` | default `250` or lower based on host memory | tuned to production capacity |
| `CONTENT_EXPORT_MAX_TOTAL_BYTES` | default `52428800` (50 MiB) or lower | tuned to production capacity |
| `CONTENT_EXPORT_RATE_LIMIT_PER_MINUTE` | default `6` | tuned to API throughput and abuse model |
Key environment variables used by `api` and `worker` in compose:
- `APP_ENV`
- `DATABASE_URL`
- `REDIS_URL`
- `REDIS_SECURITY_MODE`
- `REDIS_TLS_MODE`
- `ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS`
- `STORAGE_ROOT`
- `ADMIN_API_TOKEN`
- `USER_API_TOKEN`
- `APP_SETTINGS_ENCRYPTION_KEY`
- `PUBLIC_BASE_URL`
- `CORS_ORIGINS` (API service)
- `PROVIDER_BASE_URL_ALLOWLIST`
- `PROVIDER_BASE_URL_ALLOW_HTTP`
- `PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK`
- `TYPESENSE_PROTOCOL`
- `TYPESENSE_HOST`
- `TYPESENSE_PORT`
- `TYPESENSE_API_KEY`
- `TYPESENSE_COLLECTION_NAME`
## HTTPS Proxy Deployment Notes
Selected defaults from `Settings` (`backend/app/core/config.py`):
- `upload_chunk_size = 4194304`
- `max_upload_files_per_request = 50`
- `max_upload_file_size_bytes = 26214400`
- `max_upload_request_size_bytes = 104857600`
- `max_zip_members = 250`
- `max_zip_depth = 2`
- `max_zip_descendants_per_root = 1000`
- `max_zip_member_uncompressed_bytes = 26214400`
- `max_zip_total_uncompressed_bytes = 157286400`
- `max_zip_compression_ratio = 120.0`
- `max_text_length = 500000`
- `processing_log_max_document_sessions = 20`
- `processing_log_max_unbound_entries = 400`
- `default_openai_model = "gpt-4.1-mini"`
- `default_openai_timeout_seconds = 45`
- `default_summary_model = "gpt-4.1-mini"`
- `default_routing_model = "gpt-4.1-mini"`
- `typesense_timeout_seconds = 120`
- `typesense_num_retries = 0`
This application supports both:
- local HTTP-only operation (no TLS termination in containers)
- HTTPS deployment behind a reverse proxy that handles TLS
## Frontend Configuration
Frontend runtime API target:
- `VITE_API_BASE` in `docker-compose.yml` frontend service (optional override)
- `VITE_API_TOKEN` in `docker-compose.yml` frontend service (optional compatibility fallback only)
When `VITE_API_BASE` is unset, frontend API helpers resolve to:
- `http://<current-frontend-hostname>:8000/api/v1`
Frontend API authentication behavior:
- `frontend/src/lib/api.ts` resolves bearer tokens at request time in this order:
- custom runtime resolver (`setApiTokenResolver`)
- runtime global token (`window.__DCM_API_TOKEN__`)
- session token (`setRuntimeApiToken`)
- legacy `VITE_API_TOKEN` fallback
- requests are sent without authorization only when no runtime or fallback token source is available
Frontend container runtime behavior:
- the container runs as non-root `node`
- `/app` is owned by `node` in `frontend/Dockerfile` so Vite can create runtime temp config files under `/app`
Frontend local commands:
```bash
cd frontend && npm run dev
cd frontend && npm run build
cd frontend && npm run preview
```
## Settings Persistence
Application-level settings managed from the UI are persisted by backend settings service:
- file path: `<STORAGE_ROOT>/settings.json`
- endpoints: `/api/v1/settings`, `/api/v1/settings/reset`, `/api/v1/settings/handwriting`
Settings include:
- upload defaults
- display options
- processing-log retention options (`keep_document_sessions`, `keep_unbound_entries`)
- provider configuration
- OCR, summary, and routing task settings
- predefined paths and tags
- handwriting-style clustering settings
Read sanitization is resilient to corrupt persisted provider rows. If a persisted provider entry fails URL validation, the entry is skipped and defaults are used when no valid provider remains. This prevents unrelated read endpoints from failing due to stale invalid provider data.
Provider API keys are persisted as encrypted payloads (`api_key_encrypted`) and plaintext `api_key` values are no longer written to disk.
Retention settings are used by worker cleanup and by `POST /api/v1/processing/logs/trim` when trim query values are not provided.
Recommended LIVE pattern:
1. Proxy terminates TLS and forwards to `api` and `frontend` internal HTTP endpoints.
2. Keep container published ports bound to localhost or internal network.
3. Set `PUBLIC_BASE_URL` and `VITE_API_BASE` to final HTTPS URLs.
4. Set `CORS_ORIGINS` to exact HTTPS frontend origins.
5. Keep `CORS_ALLOW_CREDENTIALS=false` for bearer header flow.
## Security Controls
- Privileged APIs are token-gated with bearer auth:
- `documents` endpoints: user token or admin token
- `settings` and `processing/logs` endpoints: admin token only
- Development environments can allow tokenless user-role access for document/search routes via `ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS=true`; production remains token-enforced.
- CORS allows HTTP and HTTPS origins by regex in addition to explicit `CORS_ORIGINS`, so LAN and public-domain frontend origins are accepted.
- Authentication fails closed when `ADMIN_API_TOKEN` is not configured and admin access is requested.
- Document preview endpoint blocks inline rendering for script-capable MIME types and forces attachment responses for active content.
- Provider base URLs are validated on settings updates and before outbound model calls:
- optional allowlist enforcement (`PROVIDER_BASE_URL_ALLOWLIST`)
- optional scheme restrictions (`PROVIDER_BASE_URL_ALLOW_HTTP`)
- optional private-network restrictions (`PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK`)
- per-request DNS revalidation checks for outbound runtime calls, including OCR provider path
- Upload and archive safety guards are enforced:
- `POST /api/v1/documents/upload` requires `Content-Length` and enforces file-count, per-file size, and total request size limits
- `OPTIONS /api/v1/documents/upload` CORS preflight is excluded from `Content-Length` enforcement
- ZIP member count, per-member uncompressed size, total decompressed size, compression-ratio guards, max depth, and per-root descendant fan-out cap
- Redis queue security checks enforce URL scheme/auth/TLS policy at runtime with production fail-closed defaults.
- Processing logs redact sensitive payload and text fields, and trim endpoints enforce retention caps from runtime config.
- Compose hardening defaults:
- only `api` and `frontend` publish host ports; `db`, `redis`, and `typesense` stay internal-only
- `api`, `worker`, and `frontend` drop all Linux capabilities and set `no-new-privileges`
- backend and frontend containers run as non-root users by default
- CORS uses explicit origin allowlist only; broad origin regex matching is removed.
- Worker Redis startup validates URL auth and TLS policy before consuming jobs.
- Provider API keys are encrypted at rest with standard AEAD (`cryptography` Fernet).
- legacy `enc-v1` payloads are read for backward compatibility
- new writes use `enc-v2`
- Processing logs default to metadata-only persistence.
- Markdown export enforces:
- max document count
- max total markdown bytes
- per-user Redis-backed rate limit
- spool-file streaming to avoid unbounded memory archives
- User-role document access is owner-scoped for non-admin accounts.
## Frontend Runtime
- Frontend no longer consumes `VITE_API_TOKEN`.
- Session token storage key is `dcm.access_token` in browser session storage.
- Protected media and file download flows still use authenticated fetch plus blob/object URL handling.
## Validation Checklist
After operational or configuration changes, verify:
- `GET /api/v1/health` is healthy
- frontend can list, upload, and search documents
- processing worker logs show successful task execution
- settings save or reset works and persists after restart
After configuration changes:
- `GET /api/v1/health` returns healthy response
- login succeeds for bootstrap admin user
- admin can upload, search, open preview, download, and export markdown
- user account can only access its own documents
- admin-only settings and processing logs are not accessible by user role
- `docker compose logs -f api worker` shows no startup validation failures