From bdd97d1c62295af23fa4273bc28d366dc5c1b2b4 Mon Sep 17 00:00:00 2001 From: Beda Schmid Date: Sun, 1 Mar 2026 13:32:08 -0300 Subject: [PATCH] Harden security controls from REPORT findings --- README.md | 25 +- backend/.env.example | 9 +- backend/app/api/auth.py | 10 +- backend/app/api/routes_documents.py | 14 +- backend/app/core/config.py | 112 ++++- backend/app/services/app_settings.py | 220 ++++++++- backend/app/services/extractor.py | 15 +- backend/app/services/handwriting.py | 10 +- backend/app/worker/queue.py | 7 +- backend/app/worker/tasks.py | 152 +++++- .../test_app_settings_provider_resilience.py | 81 ++++ backend/tests/test_security_controls.py | 449 +++++++++++++++++- doc/api-contract.md | 11 +- doc/architecture-overview.md | 11 +- doc/frontend-design-foundation.md | 2 + doc/operations-and-configuration.md | 50 +- docker-compose.yml | 50 +- frontend/src/components/DocumentViewer.tsx | 96 +++- frontend/src/lib/api.test.ts | 116 ++++- frontend/src/lib/api.ts | 112 ++++- 20 files changed, 1455 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 7bce91f..d16df97 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,9 @@ The default `docker compose` stack includes: - `frontend` - React UI (`http://localhost:5173`) - `api` - FastAPI backend (`http://localhost:8000`, docs at `/docs`) - `worker` - background processing jobs -- `db` - PostgreSQL (`localhost:5432`) -- `redis` - queue backend (`localhost:6379`) -- `typesense` - search index (`localhost:8108`) +- `db` - PostgreSQL (internal service network) +- `redis` - queue backend (internal service network) +- `typesense` - search index (internal service network) ## Requirements @@ -42,6 +42,19 @@ From repository root: docker compose up --build -d ``` +Before first run, set required secrets and connection values in `.env` (or your shell): + +- `POSTGRES_USER` +- `POSTGRES_PASSWORD` +- `POSTGRES_DB` +- `DATABASE_URL` +- `REDIS_PASSWORD` +- `REDIS_URL` +- `ADMIN_API_TOKEN` +- `USER_API_TOKEN` +- `APP_SETTINGS_ENCRYPTION_KEY` +- `TYPESENSE_API_KEY` + Open: - Frontend: `http://localhost:5173` @@ -102,13 +115,15 @@ cd frontend && npm run preview Main runtime variables are defined in `docker-compose.yml`: -- API and worker: `DATABASE_URL`, `REDIS_URL`, `STORAGE_ROOT`, `PUBLIC_BASE_URL`, `CORS_ORIGINS`, `TYPESENSE_*` -- Frontend: `VITE_API_BASE` +- API and worker: `DATABASE_URL`, `REDIS_URL`, `REDIS_SECURITY_MODE`, `REDIS_TLS_MODE`, `STORAGE_ROOT`, `PUBLIC_BASE_URL`, `CORS_ORIGINS`, `ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS`, `TYPESENSE_*`, `APP_SETTINGS_ENCRYPTION_KEY` +- Frontend: `VITE_API_BASE`, optional `VITE_API_TOKEN` compatibility fallback Application settings saved from the UI persist at: - `/settings.json` (inside the storage volume) +Provider API keys are persisted encrypted at rest (`api_key_encrypted`) and are no longer written as plaintext values. + Settings endpoints: - `GET/PUT /api/v1/settings` diff --git a/backend/.env.example b/backend/.env.example index d67fc6a..edf8edb 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -1,15 +1,20 @@ APP_ENV=development DATABASE_URL=postgresql+psycopg://dcm:dcm@db:5432/dcm -REDIS_URL=redis://redis:6379/0 +REDIS_URL=redis://:replace-with-redis-password@redis:6379/0 +REDIS_SECURITY_MODE=auto +REDIS_TLS_MODE=auto +ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS=true STORAGE_ROOT=/data/storage ADMIN_API_TOKEN=replace-with-random-admin-token USER_API_TOKEN=replace-with-random-user-token +APP_SETTINGS_ENCRYPTION_KEY=replace-with-random-settings-encryption-key MAX_UPLOAD_FILES_PER_REQUEST=50 MAX_UPLOAD_FILE_SIZE_BYTES=26214400 MAX_UPLOAD_REQUEST_SIZE_BYTES=104857600 MAX_ZIP_MEMBER_UNCOMPRESSED_BYTES=26214400 MAX_ZIP_TOTAL_UNCOMPRESSED_BYTES=157286400 MAX_ZIP_COMPRESSION_RATIO=120 +MAX_ZIP_DESCENDANTS_PER_ROOT=1000 PROVIDER_BASE_URL_ALLOWLIST=["api.openai.com"] PROVIDER_BASE_URL_ALLOW_HTTP=false PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK=false @@ -23,6 +28,6 @@ DEFAULT_ROUTING_MODEL=gpt-4.1-mini TYPESENSE_PROTOCOL=http TYPESENSE_HOST=typesense TYPESENSE_PORT=8108 -TYPESENSE_API_KEY=dcm-typesense-key +TYPESENSE_API_KEY=replace-with-random-typesense-api-key TYPESENSE_COLLECTION_NAME=documents PUBLIC_BASE_URL=http://localhost:8000 diff --git a/backend/app/api/auth.py b/backend/app/api/auth.py index a06ef06..c128f07 100644 --- a/backend/app/api/auth.py +++ b/backend/app/api/auth.py @@ -59,13 +59,21 @@ def get_request_role( credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer_auth)], settings: Annotated[Settings, Depends(get_settings)], ) -> str: - """Authenticates request token and returns its authorization role.""" + """Authenticates request token and returns its authorization role. + + Development environments can optionally allow tokenless user access for non-admin routes to + preserve local workflow compatibility while production remains token-enforced. + """ if credentials is None: + if settings.allow_development_anonymous_user_access and settings.app_env.strip().lower() in {"development", "dev"}: + return AuthRole.USER _raise_unauthorized() token = credentials.credentials.strip() if not token: + if settings.allow_development_anonymous_user_access and settings.app_env.strip().lower() in {"development", "dev"}: + return AuthRole.USER _raise_unauthorized() return _resolve_token_role(token=token, settings=settings) diff --git a/backend/app/api/routes_documents.py b/backend/app/api/routes_documents.py index 0b52d17..abf4758 100644 --- a/backend/app/api/routes_documents.py +++ b/backend/app/api/routes_documents.py @@ -14,7 +14,7 @@ from fastapi.responses import FileResponse, Response, StreamingResponse from sqlalchemy import or_, func, select from sqlalchemy.orm import Session -from app.core.config import get_settings +from app.core.config import get_settings, is_inline_preview_mime_type_safe from app.db.base import get_session from app.models.document import Document, DocumentStatus from app.schemas.documents import ( @@ -448,14 +448,22 @@ def download_document(document_id: UUID, session: Session = Depends(get_session) @router.get("/{document_id}/preview") def preview_document(document_id: UUID, session: Session = Depends(get_session)) -> FileResponse: - """Streams the original document inline when browser rendering is supported.""" + """Streams trusted-safe MIME types inline and forces attachment for active script-capable types.""" document = session.execute(select(Document).where(Document.id == document_id)).scalar_one_or_none() if document is None: raise HTTPException(status_code=404, detail="Document not found") original_path = absolute_path(document.stored_relative_path) - return FileResponse(path=original_path, media_type=document.mime_type) + common_headers = {"X-Content-Type-Options": "nosniff"} + if not is_inline_preview_mime_type_safe(document.mime_type): + return FileResponse( + path=original_path, + filename=document.original_filename, + media_type="application/octet-stream", + headers=common_headers, + ) + return FileResponse(path=original_path, media_type=document.mime_type, headers=common_headers) @router.get("/{document_id}/thumbnail") diff --git a/backend/app/core/config.py b/backend/app/core/config.py index 0362c4d..e454004 100644 --- a/backend/app/core/config.py +++ b/backend/app/core/config.py @@ -19,6 +19,9 @@ class Settings(BaseSettings): app_env: str = "development" database_url: str = "postgresql+psycopg://dcm:dcm@db:5432/dcm" redis_url: str = "redis://redis:6379/0" + redis_security_mode: str = "auto" + redis_tls_mode: str = "auto" + allow_development_anonymous_user_access: bool = True storage_root: Path = Path("/data/storage") upload_chunk_size: int = 4 * 1024 * 1024 max_upload_files_per_request: int = 50 @@ -26,6 +29,7 @@ class Settings(BaseSettings): max_upload_request_size_bytes: int = 100 * 1024 * 1024 max_zip_members: int = 250 max_zip_depth: int = 2 + max_zip_descendants_per_root: int = 1000 max_zip_member_uncompressed_bytes: int = 25 * 1024 * 1024 max_zip_total_uncompressed_bytes: int = 150 * 1024 * 1024 max_zip_compression_ratio: float = 120.0 @@ -44,12 +48,13 @@ class Settings(BaseSettings): default_openai_timeout_seconds: int = 45 default_openai_handwriting_enabled: bool = True default_openai_api_key: str = "" + app_settings_encryption_key: str = "" default_summary_model: str = "gpt-4.1-mini" default_routing_model: str = "gpt-4.1-mini" typesense_protocol: str = "http" typesense_host: str = "typesense" typesense_port: int = 8108 - typesense_api_key: str = "dcm-typesense-key" + typesense_api_key: str = "" typesense_collection_name: str = "documents" typesense_timeout_seconds: int = 120 typesense_num_retries: int = 0 @@ -58,6 +63,111 @@ class Settings(BaseSettings): LOCAL_HOSTNAME_SUFFIXES = (".local", ".internal", ".home.arpa") +SCRIPT_CAPABLE_INLINE_MIME_TYPES = frozenset( + { + "application/ecmascript", + "application/javascript", + "application/x-javascript", + "application/xhtml+xml", + "image/svg+xml", + "text/ecmascript", + "text/html", + "text/javascript", + } +) +SCRIPT_CAPABLE_XML_MIME_TYPES = frozenset({"application/xml", "text/xml"}) +REDIS_SECURITY_MODES = frozenset({"auto", "strict", "compat"}) +REDIS_TLS_MODES = frozenset({"auto", "required", "allow_insecure"}) + + +def _is_production_environment(app_env: str) -> bool: + """Returns whether the runtime environment should enforce production-only security gates.""" + + normalized = app_env.strip().lower() + return normalized in {"production", "prod"} + + +def _normalize_redis_security_mode(raw_mode: str) -> str: + """Normalizes Redis security mode values into one supported mode.""" + + normalized = raw_mode.strip().lower() + if normalized not in REDIS_SECURITY_MODES: + return "auto" + return normalized + + +def _normalize_redis_tls_mode(raw_mode: str) -> str: + """Normalizes Redis TLS mode values into one supported mode.""" + + normalized = raw_mode.strip().lower() + if normalized not in REDIS_TLS_MODES: + return "auto" + return normalized + + +def validate_redis_url_security( + redis_url: str, + *, + app_env: str | None = None, + security_mode: str | None = None, + tls_mode: str | None = None, +) -> str: + """Validates Redis URL security posture with production fail-closed defaults.""" + + settings = get_settings() + resolved_app_env = app_env if app_env is not None else settings.app_env + resolved_security_mode = ( + _normalize_redis_security_mode(security_mode) + if security_mode is not None + else _normalize_redis_security_mode(settings.redis_security_mode) + ) + resolved_tls_mode = ( + _normalize_redis_tls_mode(tls_mode) + if tls_mode is not None + else _normalize_redis_tls_mode(settings.redis_tls_mode) + ) + + candidate = redis_url.strip() + if not candidate: + raise ValueError("Redis URL must not be empty") + + parsed = urlparse(candidate) + scheme = parsed.scheme.lower() + if scheme not in {"redis", "rediss"}: + raise ValueError("Redis URL must use redis:// or rediss://") + if not parsed.hostname: + raise ValueError("Redis URL must include a hostname") + + strict_security = ( + resolved_security_mode == "strict" + or (resolved_security_mode == "auto" and _is_production_environment(resolved_app_env)) + ) + require_tls = ( + resolved_tls_mode == "required" + or (resolved_tls_mode == "auto" and strict_security) + ) + has_password = bool(parsed.password and parsed.password.strip()) + uses_tls = scheme == "rediss" + + if strict_security and not has_password: + raise ValueError("Redis URL must include authentication when security mode is strict") + if require_tls and not uses_tls: + raise ValueError("Redis URL must use rediss:// when TLS is required") + + return candidate + + +def is_inline_preview_mime_type_safe(mime_type: str) -> bool: + """Returns whether a MIME type is safe to serve inline from untrusted document uploads.""" + + normalized = mime_type.split(";", 1)[0].strip().lower() if mime_type else "" + if not normalized: + return False + if normalized in SCRIPT_CAPABLE_INLINE_MIME_TYPES: + return False + if normalized in SCRIPT_CAPABLE_XML_MIME_TYPES or normalized.endswith("+xml"): + return False + return True def _normalize_allowlist(allowlist: object) -> tuple[str, ...]: diff --git a/backend/app/services/app_settings.py b/backend/app/services/app_settings.py index 8fa4702..96b4bb5 100644 --- a/backend/app/services/app_settings.py +++ b/backend/app/services/app_settings.py @@ -1,7 +1,13 @@ """Persistent single-user application settings service backed by host-mounted storage.""" +import base64 +import binascii +import hashlib +import hmac import json +import os import re +import secrets from pathlib import Path from typing import Any @@ -57,6 +63,172 @@ DEFAULT_ROUTING_PROMPT = ( "Confidence must be between 0 and 1." ) +PROVIDER_API_KEY_CIPHERTEXT_PREFIX = "enc-v1" +PROVIDER_API_KEY_KEYFILE_NAME = ".settings-api-key" +PROVIDER_API_KEY_STREAM_CONTEXT = b"dcm-provider-api-key-stream" +PROVIDER_API_KEY_AUTH_CONTEXT = b"dcm-provider-api-key-auth" +PROVIDER_API_KEY_NONCE_BYTES = 16 +PROVIDER_API_KEY_TAG_BYTES = 32 + + +def _settings_api_key_path() -> Path: + """Returns the storage path used for local symmetric encryption key persistence.""" + + return settings.storage_root / PROVIDER_API_KEY_KEYFILE_NAME + + +def _write_private_text_file(path: Path, content: str) -> None: + """Writes text files with restrictive owner-only permissions for local secret material.""" + + path.parent.mkdir(parents=True, exist_ok=True) + file_descriptor = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + with os.fdopen(file_descriptor, "w", encoding="utf-8") as handle: + handle.write(content) + os.chmod(path, 0o600) + + +def _urlsafe_b64encode_no_padding(data: bytes) -> str: + """Encodes bytes to URL-safe base64 without padding for compact JSON persistence.""" + + return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=") + + +def _urlsafe_b64decode_no_padding(data: str) -> bytes: + """Decodes URL-safe base64 values that may omit trailing padding characters.""" + + padded = data + "=" * (-len(data) % 4) + return base64.urlsafe_b64decode(padded.encode("ascii")) + + +def _derive_provider_api_key_key() -> bytes: + """Resolves the master key used to encrypt provider API keys for settings storage.""" + + configured_key = settings.app_settings_encryption_key.strip() + if configured_key: + try: + decoded = _urlsafe_b64decode_no_padding(configured_key) + if len(decoded) >= 32: + return decoded[:32] + except (binascii.Error, ValueError): + pass + return hashlib.sha256(configured_key.encode("utf-8")).digest() + + key_path = _settings_api_key_path() + if key_path.exists(): + try: + persisted = key_path.read_text(encoding="utf-8").strip() + decoded = _urlsafe_b64decode_no_padding(persisted) + if len(decoded) >= 32: + return decoded[:32] + except (OSError, UnicodeDecodeError, binascii.Error, ValueError): + pass + + generated = secrets.token_bytes(32) + _write_private_text_file(key_path, _urlsafe_b64encode_no_padding(generated)) + return generated + + +def _xor_bytes(left: bytes, right: bytes) -> bytes: + """Applies byte-wise XOR for equal-length byte sequences.""" + + return bytes(first ^ second for first, second in zip(left, right)) + + +def _derive_stream_cipher_bytes(master_key: bytes, nonce: bytes, length: int) -> bytes: + """Derives deterministic stream bytes from HMAC-SHA256 blocks for payload masking.""" + + stream = bytearray() + counter = 0 + while len(stream) < length: + counter_bytes = counter.to_bytes(4, "big") + block = hmac.new( + master_key, + PROVIDER_API_KEY_STREAM_CONTEXT + nonce + counter_bytes, + hashlib.sha256, + ).digest() + stream.extend(block) + counter += 1 + return bytes(stream[:length]) + + +def _encrypt_provider_api_key(value: str) -> str: + """Encrypts one provider API key for at-rest JSON persistence.""" + + normalized = value.strip() + if not normalized: + return "" + + plaintext = normalized.encode("utf-8") + master_key = _derive_provider_api_key_key() + nonce = secrets.token_bytes(PROVIDER_API_KEY_NONCE_BYTES) + keystream = _derive_stream_cipher_bytes(master_key, nonce, len(plaintext)) + ciphertext = _xor_bytes(plaintext, keystream) + tag = hmac.new( + master_key, + PROVIDER_API_KEY_AUTH_CONTEXT + nonce + ciphertext, + hashlib.sha256, + ).digest() + payload = nonce + ciphertext + tag + encoded = _urlsafe_b64encode_no_padding(payload) + return f"{PROVIDER_API_KEY_CIPHERTEXT_PREFIX}:{encoded}" + + +def _decrypt_provider_api_key(value: str) -> str: + """Decrypts provider API key ciphertext while rejecting tampered payloads.""" + + normalized = value.strip() + if not normalized: + return "" + if not normalized.startswith(f"{PROVIDER_API_KEY_CIPHERTEXT_PREFIX}:"): + return normalized + + encoded_payload = normalized.split(":", 1)[1] + if not encoded_payload: + raise AppSettingsValidationError("Provider API key ciphertext is missing payload bytes") + try: + payload = _urlsafe_b64decode_no_padding(encoded_payload) + except (binascii.Error, ValueError) as error: + raise AppSettingsValidationError("Provider API key ciphertext is not valid base64") from error + + minimum_length = PROVIDER_API_KEY_NONCE_BYTES + PROVIDER_API_KEY_TAG_BYTES + if len(payload) < minimum_length: + raise AppSettingsValidationError("Provider API key ciphertext payload is truncated") + + nonce = payload[:PROVIDER_API_KEY_NONCE_BYTES] + ciphertext = payload[PROVIDER_API_KEY_NONCE_BYTES:-PROVIDER_API_KEY_TAG_BYTES] + received_tag = payload[-PROVIDER_API_KEY_TAG_BYTES:] + master_key = _derive_provider_api_key_key() + expected_tag = hmac.new( + master_key, + PROVIDER_API_KEY_AUTH_CONTEXT + nonce + ciphertext, + hashlib.sha256, + ).digest() + if not hmac.compare_digest(received_tag, expected_tag): + raise AppSettingsValidationError("Provider API key ciphertext integrity check failed") + + keystream = _derive_stream_cipher_bytes(master_key, nonce, len(ciphertext)) + plaintext = _xor_bytes(ciphertext, keystream) + try: + return plaintext.decode("utf-8").strip() + except UnicodeDecodeError as error: + raise AppSettingsValidationError("Provider API key ciphertext is not valid UTF-8") from error + + +def _read_provider_api_key(provider_payload: dict[str, Any]) -> str: + """Reads provider API key values from encrypted or legacy plaintext settings payloads.""" + + encrypted_value = provider_payload.get("api_key_encrypted") + if isinstance(encrypted_value, str) and encrypted_value.strip(): + try: + return _decrypt_provider_api_key(encrypted_value) + except AppSettingsValidationError: + return "" + + plaintext_value = provider_payload.get("api_key") + if plaintext_value is None: + return "" + return str(plaintext_value).strip() + def _default_settings() -> dict[str, Any]: """Builds default settings including providers and model task bindings.""" @@ -243,8 +415,17 @@ def _normalize_provider( if provider_type != "openai_compatible": provider_type = "openai_compatible" - api_key_value = payload.get("api_key", fallback_values.get("api_key", defaults["api_key"])) - api_key = str(api_key_value).strip() if api_key_value is not None else "" + payload_api_key = _read_provider_api_key(payload) + fallback_api_key = _read_provider_api_key(fallback_values) + default_api_key = _read_provider_api_key(defaults) + if "api_key" in payload and payload.get("api_key") is not None: + api_key = str(payload.get("api_key")).strip() + elif payload_api_key: + api_key = payload_api_key + elif fallback_api_key: + api_key = fallback_api_key + else: + api_key = default_api_key raw_base_url = str(payload.get("base_url", fallback_values.get("base_url", defaults["base_url"]))).strip() if not raw_base_url: @@ -266,6 +447,7 @@ def _normalize_provider( ) ), "api_key": api_key, + "api_key_encrypted": _encrypt_provider_api_key(api_key), } @@ -653,6 +835,26 @@ def _sanitize_settings(payload: dict[str, Any]) -> dict[str, Any]: } +def _serialize_settings_for_storage(payload: dict[str, Any]) -> dict[str, Any]: + """Converts sanitized runtime payload into storage-safe form without plaintext provider keys.""" + + storage_payload = dict(payload) + providers_storage: list[dict[str, Any]] = [] + for provider in payload.get("providers", []): + if not isinstance(provider, dict): + continue + provider_storage = dict(provider) + plaintext_api_key = str(provider_storage.pop("api_key", "")).strip() + encrypted_api_key = str(provider_storage.get("api_key_encrypted", "")).strip() + if plaintext_api_key: + encrypted_api_key = _encrypt_provider_api_key(plaintext_api_key) + provider_storage["api_key_encrypted"] = encrypted_api_key + providers_storage.append(provider_storage) + + storage_payload["providers"] = providers_storage + return storage_payload + + def ensure_app_settings() -> None: """Creates a settings file with defaults when no persisted settings are present.""" @@ -662,7 +864,7 @@ def ensure_app_settings() -> None: return defaults = _sanitize_settings(_default_settings()) - path.write_text(json.dumps(defaults, indent=2), encoding="utf-8") + _write_private_text_file(path, json.dumps(_serialize_settings_for_storage(defaults), indent=2)) def _read_raw_settings() -> dict[str, Any]: @@ -682,7 +884,8 @@ def _write_settings(payload: dict[str, Any]) -> None: path = _settings_path() path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(json.dumps(payload, indent=2), encoding="utf-8") + storage_payload = _serialize_settings_for_storage(payload) + _write_private_text_file(path, json.dumps(storage_payload, indent=2)) def read_app_settings() -> dict[str, Any]: @@ -879,16 +1082,21 @@ def update_app_settings( def read_handwriting_provider_settings() -> dict[str, Any]: - """Returns OCR settings in legacy shape for the handwriting transcription service.""" + """Returns OCR settings in legacy shape with DNS-revalidated provider base URL safety checks.""" runtime = read_task_runtime_settings(TASK_OCR_HANDWRITING) provider = runtime["provider"] task = runtime["task"] + raw_base_url = str(provider.get("base_url", settings.default_openai_base_url)) + try: + normalized_base_url = normalize_and_validate_provider_base_url(raw_base_url, resolve_dns=True) + except ValueError as error: + raise AppSettingsValidationError(str(error)) from error return { "provider": provider["provider_type"], "enabled": bool(task.get("enabled", True)), - "openai_base_url": str(provider.get("base_url", settings.default_openai_base_url)), + "openai_base_url": normalized_base_url, "openai_model": str(task.get("model", settings.default_openai_model)), "openai_timeout_seconds": int(provider.get("timeout_seconds", settings.default_openai_timeout_seconds)), "openai_api_key": str(provider.get("api_key", "")), diff --git a/backend/app/services/extractor.py b/backend/app/services/extractor.py index cf73e89..b5987c3 100644 --- a/backend/app/services/extractor.py +++ b/backend/app/services/extractor.py @@ -299,17 +299,24 @@ def extract_text_content(filename: str, data: bytes, mime_type: str) -> Extracti ) -def extract_archive_members(data: bytes, depth: int = 0) -> list[ArchiveMember]: - """Extracts processable ZIP members within configured decompression safety budgets.""" +def extract_archive_members(data: bytes, depth: int = 0, max_members: int | None = None) -> list[ArchiveMember]: + """Extracts processable ZIP members with depth-aware and decompression safety guardrails.""" members: list[ArchiveMember] = [] - if depth > settings.max_zip_depth: + normalized_depth = max(0, depth) + if normalized_depth >= settings.max_zip_depth: + return members + + member_limit = settings.max_zip_members + if max_members is not None: + member_limit = max(0, min(settings.max_zip_members, int(max_members))) + if member_limit <= 0: return members total_uncompressed_bytes = 0 try: with zipfile.ZipFile(io.BytesIO(data)) as archive: - infos = [info for info in archive.infolist() if not info.is_dir()][: settings.max_zip_members] + infos = [info for info in archive.infolist() if not info.is_dir()][:member_limit] for info in infos: if info.file_size <= 0: continue diff --git a/backend/app/services/handwriting.py b/backend/app/services/handwriting.py index 968476e..0fae554 100644 --- a/backend/app/services/handwriting.py +++ b/backend/app/services/handwriting.py @@ -10,6 +10,7 @@ from typing import Any from openai import APIConnectionError, APIError, APITimeoutError, OpenAI from PIL import Image, ImageOps +from app.core.config import normalize_and_validate_provider_base_url from app.services.app_settings import DEFAULT_OCR_PROMPT, read_handwriting_provider_settings MAX_IMAGE_SIDE = 2000 @@ -151,12 +152,17 @@ def _normalize_image_bytes(image_data: bytes) -> tuple[bytes, str]: def _create_client(provider_settings: dict[str, Any]) -> OpenAI: - """Creates an OpenAI client configured for compatible endpoints and timeouts.""" + """Creates an OpenAI client configured with DNS-revalidated endpoint and request timeout controls.""" api_key = str(provider_settings.get("openai_api_key", "")).strip() or "no-key-required" + raw_base_url = str(provider_settings.get("openai_base_url", "")).strip() + try: + normalized_base_url = normalize_and_validate_provider_base_url(raw_base_url, resolve_dns=True) + except ValueError as error: + raise HandwritingTranscriptionError(f"invalid_provider_base_url:{error}") from error return OpenAI( api_key=api_key, - base_url=str(provider_settings["openai_base_url"]), + base_url=normalized_base_url, timeout=int(provider_settings["openai_timeout_seconds"]), ) diff --git a/backend/app/worker/queue.py b/backend/app/worker/queue.py index 717e7d5..bf6f3f7 100644 --- a/backend/app/worker/queue.py +++ b/backend/app/worker/queue.py @@ -3,16 +3,17 @@ from redis import Redis from rq import Queue -from app.core.config import get_settings +from app.core.config import get_settings, validate_redis_url_security settings = get_settings() def get_redis() -> Redis: - """Creates a Redis connection from configured URL.""" + """Creates a Redis connection after enforcing URL security policy checks.""" - return Redis.from_url(settings.redis_url) + secure_redis_url = validate_redis_url_security(settings.redis_url) + return Redis.from_url(secure_redis_url) def get_processing_queue() -> Queue: diff --git a/backend/app/worker/tasks.py b/backend/app/worker/tasks.py index f5295e4..07b35d3 100644 --- a/backend/app/worker/tasks.py +++ b/backend/app/worker/tasks.py @@ -7,6 +7,7 @@ from pathlib import Path from sqlalchemy import select from sqlalchemy.orm import Session +from app.core.config import get_settings from app.db.base import SessionLocal from app.models.document import Document, DocumentStatus from app.services.app_settings import ( @@ -37,6 +38,13 @@ from app.services.storage import absolute_path, compute_sha256, store_bytes, wri from app.worker.queue import get_processing_queue +settings = get_settings() + +ARCHIVE_ROOT_ID_METADATA_KEY = "archive_root_document_id" +ARCHIVE_DEPTH_METADATA_KEY = "archive_depth" +ARCHIVE_DESCENDANT_COUNT_METADATA_KEY = "archive_descendant_count" + + def _cleanup_processing_logs_with_settings(session: Session) -> None: """Applies configured processing log retention while trimming old log entries.""" @@ -48,13 +56,80 @@ def _cleanup_processing_logs_with_settings(session: Session) -> None: ) +def _metadata_non_negative_int(value: object, fallback: int = 0) -> int: + """Parses metadata values as non-negative integers with safe fallback behavior.""" + + try: + parsed = int(value) + except (TypeError, ValueError): + return fallback + return max(0, parsed) + + +def _metadata_uuid(value: object) -> uuid.UUID | None: + """Parses metadata values as UUIDs while tolerating malformed legacy values.""" + + if not isinstance(value, str) or not value.strip(): + return None + try: + return uuid.UUID(value.strip()) + except ValueError: + return None + + +def _resolve_archive_lineage(session: Session, document: Document) -> tuple[uuid.UUID, int]: + """Resolves archive root document id and depth for metadata propagation compatibility.""" + + metadata_json = dict(document.metadata_json) + metadata_root = _metadata_uuid(metadata_json.get(ARCHIVE_ROOT_ID_METADATA_KEY)) + metadata_depth = _metadata_non_negative_int(metadata_json.get(ARCHIVE_DEPTH_METADATA_KEY), fallback=0) + if metadata_root is not None: + return metadata_root, metadata_depth + + if not document.is_archive_member: + return document.id, 0 + + depth = 0 + root_document_id = document.id + parent_document_id = document.parent_document_id + visited: set[uuid.UUID] = {document.id} + while parent_document_id is not None and parent_document_id not in visited: + visited.add(parent_document_id) + parent_document = session.execute(select(Document).where(Document.id == parent_document_id)).scalar_one_or_none() + if parent_document is None: + break + depth += 1 + root_document_id = parent_document.id + parent_document_id = parent_document.parent_document_id + + return root_document_id, depth + + +def _merge_archive_metadata(document: Document, **updates: object) -> None: + """Applies archive metadata updates while preserving unrelated document metadata keys.""" + + metadata_json = dict(document.metadata_json) + metadata_json.update(updates) + document.metadata_json = metadata_json + + +def _load_archive_root_for_update(session: Session, root_document_id: uuid.UUID) -> Document | None: + """Loads archive root row with write lock to serialize descendant-count budget updates.""" + + return session.execute( + select(Document).where(Document.id == root_document_id).with_for_update() + ).scalar_one_or_none() + + def _create_archive_member_document( parent: Document, member_name: str, member_data: bytes, mime_type: str, + archive_root_document_id: uuid.UUID, + archive_depth: int, ) -> Document: - """Creates a child document entity for a file extracted from an uploaded archive.""" + """Creates child document entities with lineage metadata for recursive archive processing.""" extension = Path(member_name).suffix.lower() stored_relative_path = store_bytes(member_name, member_data) @@ -68,7 +143,12 @@ def _create_archive_member_document( size_bytes=len(member_data), logical_path=parent.logical_path, tags=list(parent.tags), - metadata_json={"origin": "archive", "parent": str(parent.id)}, + metadata_json={ + "origin": "archive", + "parent": str(parent.id), + ARCHIVE_ROOT_ID_METADATA_KEY: str(archive_root_document_id), + ARCHIVE_DEPTH_METADATA_KEY: archive_depth, + }, is_archive_member=True, archived_member_path=member_name, parent_document_id=parent.id, @@ -110,16 +190,46 @@ def process_document_task(document_id: str) -> None: if document.extension == ".zip": child_ids: list[str] = [] + archive_root_document_id, archive_depth = _resolve_archive_lineage(session=session, document=document) + _merge_archive_metadata( + document, + **{ + ARCHIVE_ROOT_ID_METADATA_KEY: str(archive_root_document_id), + ARCHIVE_DEPTH_METADATA_KEY: archive_depth, + }, + ) + root_document = _load_archive_root_for_update(session=session, root_document_id=archive_root_document_id) + if root_document is None: + root_document = document + + root_metadata_json = dict(root_document.metadata_json) + existing_descendant_count = _metadata_non_negative_int( + root_metadata_json.get(ARCHIVE_DESCENDANT_COUNT_METADATA_KEY), + fallback=0, + ) + max_descendants_per_root = max(0, int(settings.max_zip_descendants_per_root)) + remaining_descendant_budget = max(0, max_descendants_per_root - existing_descendant_count) + extraction_member_cap = remaining_descendant_budget + log_processing_event( session=session, stage="archive", event="Archive extraction started", level="info", document=document, - payload_json={"size_bytes": len(data)}, + payload_json={ + "size_bytes": len(data), + "archive_root_document_id": str(archive_root_document_id), + "archive_depth": archive_depth, + "remaining_descendant_budget": remaining_descendant_budget, + }, ) try: - members = extract_archive_members(data) + members = extract_archive_members( + data, + depth=archive_depth, + max_members=extraction_member_cap, + ) for member in members: mime_type = sniff_mime(member.data) child = _create_archive_member_document( @@ -127,6 +237,8 @@ def process_document_task(document_id: str) -> None: member_name=member.name, member_data=member.data, mime_type=mime_type, + archive_root_document_id=archive_root_document_id, + archive_depth=archive_depth + 1, ) session.add(child) session.flush() @@ -142,8 +254,27 @@ def process_document_task(document_id: str) -> None: "member_name": member.name, "member_size_bytes": len(member.data), "mime_type": mime_type, + "archive_root_document_id": str(archive_root_document_id), + "archive_depth": archive_depth + 1, }, ) + + updated_root_metadata = dict(root_document.metadata_json) + updated_root_metadata[ARCHIVE_ROOT_ID_METADATA_KEY] = str(archive_root_document_id) + updated_root_metadata[ARCHIVE_DEPTH_METADATA_KEY] = 0 + updated_root_metadata[ARCHIVE_DESCENDANT_COUNT_METADATA_KEY] = existing_descendant_count + len(child_ids) + root_document.metadata_json = updated_root_metadata + + limit_flags: dict[str, object] = {} + if archive_depth >= settings.max_zip_depth: + limit_flags["max_depth_reached"] = True + if remaining_descendant_budget <= 0: + limit_flags["max_descendants_reached"] = True + elif len(child_ids) >= remaining_descendant_budget: + limit_flags["max_descendants_reached"] = True + if limit_flags: + _merge_archive_metadata(document, **limit_flags) + document.status = DocumentStatus.PROCESSED document.extracted_text = f"archive with {len(members)} files" log_processing_event( @@ -152,7 +283,13 @@ def process_document_task(document_id: str) -> None: event="Archive extraction completed", level="info", document=document, - payload_json={"member_count": len(members)}, + payload_json={ + "member_count": len(members), + "archive_root_document_id": str(archive_root_document_id), + "archive_depth": archive_depth, + "descendant_count": existing_descendant_count + len(child_ids), + "remaining_descendant_budget": max(0, remaining_descendant_budget - len(child_ids)), + }, ) except Exception as exc: document.status = DocumentStatus.ERROR @@ -231,7 +368,10 @@ def process_document_task(document_id: str) -> None: event="Archive child job enqueued", level="info", document_id=uuid.UUID(child_id), - payload_json={"parent_document_id": str(document.id)}, + payload_json={ + "parent_document_id": str(document.id), + "archive_root_document_id": str(archive_root_document_id), + }, ) session.commit() return diff --git a/backend/tests/test_app_settings_provider_resilience.py b/backend/tests/test_app_settings_provider_resilience.py index a2c98e2..8f6bac7 100644 --- a/backend/tests/test_app_settings_provider_resilience.py +++ b/backend/tests/test_app_settings_provider_resilience.py @@ -144,6 +144,87 @@ class AppSettingsProviderResilienceTests(unittest.TestCase): app_settings.update_app_settings(providers=[provider_update]) write_settings_mock.assert_not_called() + def test_sanitize_settings_migrates_legacy_plaintext_api_key_to_encrypted_field(self) -> None: + """Legacy plaintext API keys are still readable and emitted with encrypted storage representation.""" + + payload = { + "providers": [ + { + "id": "secure-provider", + "label": "Secure Provider", + "provider_type": "openai_compatible", + "base_url": "https://api.openai.com/v1", + "timeout_seconds": 45, + "api_key": "legacy-plaintext-secret", + } + ], + "tasks": { + app_settings.TASK_OCR_HANDWRITING: {"provider_id": "secure-provider"}, + app_settings.TASK_SUMMARY_GENERATION: {"provider_id": "secure-provider"}, + app_settings.TASK_ROUTING_CLASSIFICATION: {"provider_id": "secure-provider"}, + }, + } + + with patch.object(app_settings, "_derive_provider_api_key_key", return_value=b"k" * 32): + sanitized = app_settings._sanitize_settings(payload) + + provider = sanitized["providers"][0] + self.assertEqual(provider["api_key"], "legacy-plaintext-secret") + self.assertTrue( + str(provider.get("api_key_encrypted", "")).startswith( + f"{app_settings.PROVIDER_API_KEY_CIPHERTEXT_PREFIX}:" + ) + ) + + def test_serialize_settings_for_storage_excludes_plaintext_api_key(self) -> None: + """Storage payload serialization persists encrypted provider API keys only.""" + + payload = _sample_current_payload() + payload["providers"][0]["api_key"] = "storage-secret" + payload["providers"][0]["api_key_encrypted"] = "" + + with patch.object(app_settings, "_derive_provider_api_key_key", return_value=b"s" * 32): + storage_payload = app_settings._serialize_settings_for_storage(payload) + + provider_storage = storage_payload["providers"][0] + self.assertNotIn("api_key", provider_storage) + self.assertTrue( + str(provider_storage.get("api_key_encrypted", "")).startswith( + f"{app_settings.PROVIDER_API_KEY_CIPHERTEXT_PREFIX}:" + ) + ) + + def test_read_handwriting_provider_settings_revalidates_dns(self) -> None: + """OCR runtime provider settings enforce DNS revalidation before creating outbound clients.""" + + runtime_payload = { + "provider": { + "id": "openai-default", + "provider_type": "openai_compatible", + "base_url": "https://api.openai.com/v1", + "timeout_seconds": 45, + "api_key": "runtime-secret", + }, + "task": { + "enabled": True, + "model": "gpt-4.1-mini", + "prompt": "prompt", + }, + } + with ( + patch.object(app_settings, "read_task_runtime_settings", return_value=runtime_payload), + patch.object( + app_settings, + "normalize_and_validate_provider_base_url", + return_value="https://api.openai.com/v1", + ) as normalize_mock, + ): + runtime_settings = app_settings.read_handwriting_provider_settings() + + normalize_mock.assert_called_once_with("https://api.openai.com/v1", resolve_dns=True) + self.assertEqual(runtime_settings["openai_base_url"], "https://api.openai.com/v1") + self.assertEqual(runtime_settings["openai_api_key"], "runtime-secret") + if __name__ == "__main__": unittest.main() diff --git a/backend/tests/test_security_controls.py b/backend/tests/test_security_controls.py index e47431b..d868838 100644 --- a/backend/tests/test_security_controls.py +++ b/backend/tests/test_security_controls.py @@ -3,12 +3,15 @@ from __future__ import annotations from datetime import UTC, datetime +import io import socket import sys +import uuid from pathlib import Path from types import ModuleType, SimpleNamespace import unittest from unittest.mock import patch +import zipfile BACKEND_ROOT = Path(__file__).resolve().parents[1] @@ -83,6 +86,191 @@ if "fastapi.security" not in sys.modules: fastapi_security_stub.HTTPBearer = _HTTPBearer sys.modules["fastapi.security"] = fastapi_security_stub +if "magic" not in sys.modules: + magic_stub = ModuleType("magic") + + def _from_buffer(_data: bytes, mime: bool = True) -> str: + """Returns deterministic fallback MIME values for extractor import stubs.""" + + return "application/octet-stream" if mime else "" + + magic_stub.from_buffer = _from_buffer + sys.modules["magic"] = magic_stub + +if "docx" not in sys.modules: + docx_stub = ModuleType("docx") + + class _DocxDocument: + """Minimal docx document stub for extractor import compatibility.""" + + def __init__(self, *_args: object, **_kwargs: object) -> None: + self.paragraphs: list[SimpleNamespace] = [] + + docx_stub.Document = _DocxDocument + sys.modules["docx"] = docx_stub + +if "openpyxl" not in sys.modules: + openpyxl_stub = ModuleType("openpyxl") + + class _Workbook: + """Minimal workbook stub for extractor import compatibility.""" + + worksheets: list[SimpleNamespace] = [] + + def _load_workbook(*_args: object, **_kwargs: object) -> _Workbook: + """Returns deterministic workbook placeholder for extractor import stubs.""" + + return _Workbook() + + openpyxl_stub.load_workbook = _load_workbook + sys.modules["openpyxl"] = openpyxl_stub + +if "PIL" not in sys.modules: + pil_stub = ModuleType("PIL") + + class _Image: + """Minimal PIL.Image replacement for extractor and handwriting import stubs.""" + + class Resampling: + """Minimal enum-like namespace used by handwriting image resize path.""" + + LANCZOS = 1 + + @staticmethod + def open(*_args: object, **_kwargs: object) -> "_Image": + """Raises for unsupported image operations in dependency-light tests.""" + + raise RuntimeError("Image.open is not available in stub") + + class _ImageOps: + """Minimal PIL.ImageOps replacement for import compatibility.""" + + @staticmethod + def exif_transpose(image: object) -> object: + """Returns original image object unchanged in dependency-light tests.""" + + return image + + pil_stub.Image = _Image + pil_stub.ImageOps = _ImageOps + sys.modules["PIL"] = pil_stub + +if "pypdf" not in sys.modules: + pypdf_stub = ModuleType("pypdf") + + class _PdfReader: + """Minimal PdfReader replacement for extractor import compatibility.""" + + def __init__(self, *_args: object, **_kwargs: object) -> None: + self.pages: list[SimpleNamespace] = [] + + pypdf_stub.PdfReader = _PdfReader + sys.modules["pypdf"] = pypdf_stub + +if "pymupdf" not in sys.modules: + pymupdf_stub = ModuleType("pymupdf") + + class _Matrix: + """Minimal matrix placeholder for extractor import compatibility.""" + + def __init__(self, *_args: object, **_kwargs: object) -> None: + pass + + def _open(*_args: object, **_kwargs: object) -> object: + """Raises when preview rendering is invoked in dependency-light tests.""" + + raise RuntimeError("pymupdf is not available in stub") + + pymupdf_stub.Matrix = _Matrix + pymupdf_stub.open = _open + sys.modules["pymupdf"] = pymupdf_stub + +if "app.services.handwriting" not in sys.modules: + handwriting_stub = ModuleType("app.services.handwriting") + + class _HandwritingError(Exception): + """Minimal base error class for extractor import compatibility.""" + + class _HandwritingNotConfiguredError(_HandwritingError): + """Minimal not-configured error class for extractor import compatibility.""" + + class _HandwritingTimeoutError(_HandwritingError): + """Minimal timeout error class for extractor import compatibility.""" + + def _classify_image_text_bytes(*_args: object, **_kwargs: object) -> SimpleNamespace: + """Returns deterministic image text classification fallback.""" + + return SimpleNamespace(label="unknown", confidence=0.0, provider="stub", model="stub") + + def _transcribe_handwriting_bytes(*_args: object, **_kwargs: object) -> SimpleNamespace: + """Returns deterministic handwriting transcription fallback.""" + + return SimpleNamespace(text="", uncertainties=[], provider="stub", model="stub") + + handwriting_stub.IMAGE_TEXT_TYPE_NO_TEXT = "no_text" + handwriting_stub.IMAGE_TEXT_TYPE_UNKNOWN = "unknown" + handwriting_stub.IMAGE_TEXT_TYPE_HANDWRITING = "handwriting" + handwriting_stub.HandwritingTranscriptionError = _HandwritingError + handwriting_stub.HandwritingTranscriptionNotConfiguredError = _HandwritingNotConfiguredError + handwriting_stub.HandwritingTranscriptionTimeoutError = _HandwritingTimeoutError + handwriting_stub.classify_image_text_bytes = _classify_image_text_bytes + handwriting_stub.transcribe_handwriting_bytes = _transcribe_handwriting_bytes + sys.modules["app.services.handwriting"] = handwriting_stub + +if "app.services.handwriting_style" not in sys.modules: + handwriting_style_stub = ModuleType("app.services.handwriting_style") + + def _assign_handwriting_style(*_args: object, **_kwargs: object) -> SimpleNamespace: + """Returns deterministic style assignment payload for worker import compatibility.""" + + return SimpleNamespace( + style_cluster_id="cluster-1", + matched_existing=False, + similarity=0.0, + vector_distance=0.0, + compared_neighbors=0, + match_min_similarity=0.0, + bootstrap_match_min_similarity=0.0, + ) + + def _delete_handwriting_style_document(*_args: object, **_kwargs: object) -> None: + """No-op style document delete stub for worker import compatibility.""" + + return None + + handwriting_style_stub.assign_handwriting_style = _assign_handwriting_style + handwriting_style_stub.delete_handwriting_style_document = _delete_handwriting_style_document + sys.modules["app.services.handwriting_style"] = handwriting_style_stub + +if "app.services.routing_pipeline" not in sys.modules: + routing_pipeline_stub = ModuleType("app.services.routing_pipeline") + + def _apply_routing_decision(*_args: object, **_kwargs: object) -> None: + """No-op routing application stub for worker import compatibility.""" + + return None + + def _classify_document_routing(*_args: object, **_kwargs: object) -> dict[str, object]: + """Returns deterministic routing decision payload for worker import compatibility.""" + + return {"chosen_path": None, "chosen_tags": []} + + def _summarize_document(*_args: object, **_kwargs: object) -> str: + """Returns deterministic summary text for worker import compatibility.""" + + return "summary" + + def _upsert_semantic_index(*_args: object, **_kwargs: object) -> None: + """No-op semantic index update stub for worker import compatibility.""" + + return None + + routing_pipeline_stub.apply_routing_decision = _apply_routing_decision + routing_pipeline_stub.classify_document_routing = _classify_document_routing + routing_pipeline_stub.summarize_document = _summarize_document + routing_pipeline_stub.upsert_semantic_index = _upsert_semantic_index + sys.modules["app.services.routing_pipeline"] = routing_pipeline_stub + from fastapi import HTTPException from fastapi.security import HTTPAuthorizationCredentials @@ -90,6 +278,8 @@ from app.api.auth import AuthRole, get_request_role, require_admin from app.core import config as config_module from app.models.processing_log import sanitize_processing_log_payload_value, sanitize_processing_log_text from app.schemas.processing_logs import ProcessingLogEntryResponse +from app.services import extractor as extractor_module +from app.worker import tasks as worker_tasks_module def _security_settings( @@ -113,7 +303,12 @@ class AuthDependencyTests(unittest.TestCase): def test_get_request_role_accepts_admin_token(self) -> None: """Admin token resolves admin role.""" - settings = SimpleNamespace(admin_api_token="admin-token", user_api_token="user-token") + settings = SimpleNamespace( + admin_api_token="admin-token", + user_api_token="user-token", + allow_development_anonymous_user_access=False, + app_env="production", + ) credentials = HTTPAuthorizationCredentials(scheme="Bearer", credentials="admin-token") role = get_request_role(credentials=credentials, settings=settings) self.assertEqual(role, AuthRole.ADMIN) @@ -121,11 +316,28 @@ class AuthDependencyTests(unittest.TestCase): def test_get_request_role_rejects_missing_credentials(self) -> None: """Missing bearer credentials return 401.""" - settings = SimpleNamespace(admin_api_token="admin-token", user_api_token="user-token") + settings = SimpleNamespace( + admin_api_token="admin-token", + user_api_token="user-token", + allow_development_anonymous_user_access=False, + app_env="production", + ) with self.assertRaises(HTTPException) as context: get_request_role(credentials=None, settings=settings) self.assertEqual(context.exception.status_code, 401) + def test_get_request_role_allows_tokenless_user_access_in_development(self) -> None: + """Development mode can allow tokenless user role for compatibility.""" + + settings = SimpleNamespace( + admin_api_token="admin-token", + user_api_token="user-token", + allow_development_anonymous_user_access=True, + app_env="development", + ) + role = get_request_role(credentials=None, settings=settings) + self.assertEqual(role, AuthRole.USER) + def test_require_admin_rejects_user_role(self) -> None: """User role cannot access admin-only endpoints.""" @@ -202,6 +414,239 @@ class ProviderBaseUrlValidationTests(unittest.TestCase): self.assertEqual(getaddrinfo_mock.call_count, 2) +class RedisQueueSecurityTests(unittest.TestCase): + """Verifies Redis URL security policy behavior for compatibility and strict environments.""" + + def test_auto_mode_allows_insecure_redis_url_in_development(self) -> None: + """Development mode stays backward-compatible with local unauthenticated redis URLs.""" + + normalized = config_module.validate_redis_url_security( + "redis://redis:6379/0", + app_env="development", + security_mode="auto", + tls_mode="auto", + ) + self.assertEqual(normalized, "redis://redis:6379/0") + + def test_auto_mode_rejects_missing_auth_in_production(self) -> None: + """Production auto mode fails closed when Redis URL omits authentication.""" + + with self.assertRaises(ValueError): + config_module.validate_redis_url_security( + "rediss://redis:6379/0", + app_env="production", + security_mode="auto", + tls_mode="auto", + ) + + def test_auto_mode_rejects_plaintext_redis_in_production(self) -> None: + """Production auto mode requires TLS transport for Redis URLs.""" + + with self.assertRaises(ValueError): + config_module.validate_redis_url_security( + "redis://:password@redis:6379/0", + app_env="production", + security_mode="auto", + tls_mode="auto", + ) + + def test_strict_mode_enforces_auth_and_tls_outside_production(self) -> None: + """Strict mode enforces production-grade Redis controls in all environments.""" + + with self.assertRaises(ValueError): + config_module.validate_redis_url_security( + "redis://redis:6379/0", + app_env="development", + security_mode="strict", + tls_mode="auto", + ) + + normalized = config_module.validate_redis_url_security( + "rediss://:password@redis:6379/0", + app_env="development", + security_mode="strict", + tls_mode="auto", + ) + self.assertEqual(normalized, "rediss://:password@redis:6379/0") + + def test_compat_mode_allows_insecure_redis_in_production_for_safe_migration(self) -> None: + """Compatibility mode keeps legacy production Redis URLs usable during migration windows.""" + + normalized = config_module.validate_redis_url_security( + "redis://redis:6379/0", + app_env="production", + security_mode="compat", + tls_mode="allow_insecure", + ) + self.assertEqual(normalized, "redis://redis:6379/0") + + +class PreviewMimeSafetyTests(unittest.TestCase): + """Verifies inline preview MIME safety checks for uploaded document responses.""" + + def test_preview_blocks_script_capable_html_and_svg_types(self) -> None: + """HTML and SVG MIME types are rejected for inline preview responses.""" + + self.assertFalse(config_module.is_inline_preview_mime_type_safe("text/html")) + self.assertFalse(config_module.is_inline_preview_mime_type_safe("image/svg+xml")) + + def test_preview_allows_pdf_and_safe_image_types(self) -> None: + """PDF and raster image MIME types stay eligible for inline preview responses.""" + + self.assertTrue(config_module.is_inline_preview_mime_type_safe("application/pdf")) + self.assertTrue(config_module.is_inline_preview_mime_type_safe("image/png")) + + +def _build_zip_bytes(entries: dict[str, bytes]) -> bytes: + """Builds in-memory ZIP bytes for archive extraction guardrail tests.""" + + output = io.BytesIO() + with zipfile.ZipFile(output, mode="w", compression=zipfile.ZIP_DEFLATED) as archive: + for filename, payload in entries.items(): + archive.writestr(filename, payload) + return output.getvalue() + + +class ArchiveExtractionGuardrailTests(unittest.TestCase): + """Verifies depth-aware archive extraction and per-call member cap enforcement.""" + + def test_extract_archive_members_rejects_depth_at_configured_limit(self) -> None: + """Archive member extraction is disabled at or beyond configured depth ceiling.""" + + archive_bytes = _build_zip_bytes({"sample.txt": b"sample"}) + patched_settings = SimpleNamespace( + max_zip_depth=2, + max_zip_members=250, + max_zip_member_uncompressed_bytes=25 * 1024 * 1024, + max_zip_total_uncompressed_bytes=150 * 1024 * 1024, + max_zip_compression_ratio=120.0, + ) + with patch.object(extractor_module, "settings", patched_settings): + members = extractor_module.extract_archive_members(archive_bytes, depth=2) + self.assertEqual(members, []) + + def test_extract_archive_members_respects_member_cap_argument(self) -> None: + """Archive extraction truncates results when caller-provided member cap is lower than archive size.""" + + archive_bytes = _build_zip_bytes( + { + "one.txt": b"1", + "two.txt": b"2", + "three.txt": b"3", + } + ) + patched_settings = SimpleNamespace( + max_zip_depth=3, + max_zip_members=250, + max_zip_member_uncompressed_bytes=25 * 1024 * 1024, + max_zip_total_uncompressed_bytes=150 * 1024 * 1024, + max_zip_compression_ratio=120.0, + ) + with patch.object(extractor_module, "settings", patched_settings): + members = extractor_module.extract_archive_members(archive_bytes, depth=0, max_members=1) + self.assertEqual(len(members), 1) + + +class ArchiveLineagePropagationTests(unittest.TestCase): + """Verifies archive lineage metadata propagation helpers used by worker descendant queueing.""" + + def test_create_archive_member_document_persists_lineage_metadata(self) -> None: + """Child archive documents include root id and incremented depth metadata.""" + + parent_id = uuid.uuid4() + parent = SimpleNamespace( + id=parent_id, + source_relative_path="uploads/root.zip", + logical_path="Inbox", + tags=["finance"], + ) + + with ( + patch.object(worker_tasks_module, "store_bytes", return_value="stored/path/child.zip"), + patch.object(worker_tasks_module, "compute_sha256", return_value="deadbeef"), + ): + child = worker_tasks_module._create_archive_member_document( + parent=parent, + member_name="nested/child.zip", + member_data=b"zip-bytes", + mime_type="application/zip", + archive_root_document_id=parent_id, + archive_depth=1, + ) + + self.assertEqual(child.parent_document_id, parent_id) + self.assertEqual(child.metadata_json.get(worker_tasks_module.ARCHIVE_ROOT_ID_METADATA_KEY), str(parent_id)) + self.assertEqual(child.metadata_json.get(worker_tasks_module.ARCHIVE_DEPTH_METADATA_KEY), 1) + self.assertTrue(child.is_archive_member) + + def test_resolve_archive_lineage_prefers_existing_metadata(self) -> None: + """Existing archive lineage metadata is reused without traversing parent relationships.""" + + root_id = uuid.uuid4() + document = SimpleNamespace( + id=uuid.uuid4(), + metadata_json={ + worker_tasks_module.ARCHIVE_ROOT_ID_METADATA_KEY: str(root_id), + worker_tasks_module.ARCHIVE_DEPTH_METADATA_KEY: 3, + }, + is_archive_member=True, + parent_document_id=uuid.uuid4(), + ) + + class _SessionShouldNotBeUsed: + """Fails test if lineage helper performs unnecessary parent traversals.""" + + def execute(self, _statement: object) -> object: + raise AssertionError("session.execute should not be called when metadata is present") + + resolved_root, resolved_depth = worker_tasks_module._resolve_archive_lineage( + session=_SessionShouldNotBeUsed(), + document=document, + ) + self.assertEqual(resolved_root, root_id) + self.assertEqual(resolved_depth, 3) + + def test_resolve_archive_lineage_walks_parent_chain_when_metadata_missing(self) -> None: + """Lineage fallback traverses parent references to recover root id and depth.""" + + root_id = uuid.uuid4() + parent_id = uuid.uuid4() + root_document = SimpleNamespace(id=root_id, parent_document_id=None) + parent_document = SimpleNamespace(id=parent_id, parent_document_id=root_id) + document = SimpleNamespace( + id=uuid.uuid4(), + metadata_json={}, + is_archive_member=True, + parent_document_id=parent_id, + ) + + class _ScalarResult: + """Wraps scalar ORM results for deterministic worker helper tests.""" + + def __init__(self, value: object) -> None: + self._value = value + + def scalar_one_or_none(self) -> object: + return self._value + + class _SequenceSession: + """Returns predetermined parent rows in traversal order.""" + + def __init__(self, values: list[object]) -> None: + self._values = values + + def execute(self, _statement: object) -> _ScalarResult: + next_value = self._values.pop(0) if self._values else None + return _ScalarResult(next_value) + + resolved_root, resolved_depth = worker_tasks_module._resolve_archive_lineage( + session=_SequenceSession([parent_document, root_document]), + document=document, + ) + self.assertEqual(resolved_root, root_id) + self.assertEqual(resolved_depth, 2) + + class ProcessingLogRedactionTests(unittest.TestCase): """Verifies sensitive processing-log values are redacted for persistence and responses.""" diff --git a/doc/api-contract.md b/doc/api-contract.md index 0b5ac8d..694ac79 100644 --- a/doc/api-contract.md +++ b/doc/api-contract.md @@ -12,7 +12,8 @@ Primary implementation modules: ## Authentication And Authorization -- Protected endpoints require `Authorization: Bearer `. +- Protected endpoints require `Authorization: Bearer ` 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: @@ -29,7 +30,8 @@ Primary implementation modules: ## Documents -- Access: admin or user token required +- Access: admin or user token required (production) +- Access: admin or user token, or development tokenless user fallback when enabled ### Collection and metadata helpers @@ -56,7 +58,8 @@ Primary implementation modules: - `GET /documents/{document_id}/download` - Response: original file bytes - `GET /documents/{document_id}/preview` - - Response: inline preview stream where browser-supported + - Response: inline preview stream only for safe MIME types + - Behavior: script-capable MIME types are forced to attachment responses with `X-Content-Type-Options: nosniff` - `GET /documents/{document_id}/thumbnail` - Response: generated thumbnail image when available - `GET /documents/{document_id}/content-md` @@ -126,10 +129,12 @@ Primary implementation modules: - `GET /settings` - Response model: `AppSettingsResponse` - persisted providers with invalid base URLs are ignored during read sanitization; response falls back to remaining valid providers or secure defaults + - provider API keys are exposed only as `api_key_set` and `api_key_masked` - `PATCH /settings` - Body model: `AppSettingsUpdateRequest` - Response model: `AppSettingsResponse` - rejects invalid provider base URLs with `400` when scheme, allowlist, or network safety checks fail + - provider API keys are persisted encrypted at rest (`api_key_encrypted`) and plaintext keys are not written to storage - `POST /settings/reset` - Response model: `AppSettingsResponse` - `PATCH /settings/handwriting` diff --git a/doc/architecture-overview.md b/doc/architecture-overview.md index 99b51f4..71472a7 100644 --- a/doc/architecture-overview.md +++ b/doc/architecture-overview.md @@ -6,9 +6,9 @@ DMS runs as a multi-service application defined in `docker-compose.yml`: - `frontend` serves the React UI on port `5173` - `api` serves FastAPI on port `8000` - `worker` executes asynchronous extraction and indexing jobs -- `db` provides PostgreSQL persistence on port `5432` -- `redis` backs queueing on port `6379` -- `typesense` stores search index and vector-adjacent metadata on port `8108` +- `db` provides PostgreSQL persistence on the internal compose network +- `redis` backs queueing on the internal compose network +- `typesense` stores search index and vector-adjacent metadata on the internal compose network ## Backend Architecture @@ -64,3 +64,8 @@ Persistent data: Transient runtime state: - Redis queues processing tasks and worker execution state - frontend local component state drives active filters, selection, and modal flows + +Security-sensitive runtime behavior: +- Redis connection URLs are validated by backend queue helpers with environment-aware auth and TLS policy enforcement. +- 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. diff --git a/doc/frontend-design-foundation.md b/doc/frontend-design-foundation.md index 48c5897..6aff357 100644 --- a/doc/frontend-design-foundation.md +++ b/doc/frontend-design-foundation.md @@ -52,9 +52,11 @@ 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. - 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. +- `DocumentViewer` iframe previews must be restricted to safe MIME types and rendered with `sandbox`, restrictive `allow`, and `referrerPolicy="no-referrer"` attributes. Active or script-capable formats must not be embedded inline. ## Extension Checklist diff --git a/doc/operations-and-configuration.md b/doc/operations-and-configuration.md index bf19a35..44feb77 100644 --- a/doc/operations-and-configuration.md +++ b/doc/operations-and-configuration.md @@ -3,12 +3,12 @@ ## Runtime Services `docker-compose.yml` defines the runtime stack: -- `db` (Postgres 16, localhost-bound port `5432`) -- `redis` (Redis 7, localhost-bound port `6379`) -- `typesense` (Typesense 29, localhost-bound port `8108`) -- `api` (FastAPI backend, localhost-bound port `8000`) +- `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, localhost-bound port `5173`) +- `frontend` (Vite UI, host-bound port `5173`) ## Named Volumes @@ -44,14 +44,22 @@ Tail logs: docker compose logs -f ``` -Before running compose, provide explicit API tokens in your shell or project `.env` file: +Before running compose, provide required credentials in your shell or project `.env` file: ```bash +export POSTGRES_USER="dcm" +export POSTGRES_PASSWORD="" +export POSTGRES_DB="dcm" +export DATABASE_URL="postgresql+psycopg://:@db:5432/" +export REDIS_PASSWORD="" +export REDIS_URL="redis://:@redis:6379/0" export ADMIN_API_TOKEN="" export USER_API_TOKEN="" +export APP_SETTINGS_ENCRYPTION_KEY="" +export TYPESENSE_API_KEY="" ``` -Compose now fails fast if either token variable is missing. +Compose fails fast when required credential variables are missing. ## Backend Configuration @@ -63,9 +71,13 @@ 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` @@ -84,6 +96,7 @@ Selected defaults from `Settings` (`backend/app/core/config.py`): - `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` @@ -101,11 +114,15 @@ Selected defaults from `Settings` (`backend/app/core/config.py`): Frontend runtime API target: - `VITE_API_BASE` in `docker-compose.yml` frontend service -- `VITE_API_TOKEN` in `docker-compose.yml` frontend service (defaults to `USER_API_TOKEN` in compose, override to `ADMIN_API_TOKEN` when admin-only routes are needed) +- `VITE_API_TOKEN` in `docker-compose.yml` frontend service (optional compatibility fallback only) Frontend API authentication behavior: -- `frontend/src/lib/api.ts` adds `Authorization: Bearer ` for all API requests only when `VITE_API_TOKEN` is non-empty -- requests are still sent without authorization when `VITE_API_TOKEN` is unset, which keeps unauthenticated endpoints such as `/api/v1/health` backward-compatible +- `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` @@ -136,6 +153,8 @@ Settings include: 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. ## Security Controls @@ -143,18 +162,21 @@ Retention settings are used by worker cleanup and by `POST /api/v1/processing/lo - Privileged APIs are token-gated with bearer auth: - `documents` endpoints: user token or admin token - `settings` and `processing/logs` endpoints: admin token only -- Authentication fails closed when `ADMIN_API_TOKEN` is not configured. +- Development environments can allow tokenless user-role access for document/search routes via `ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS=true`; production remains token-enforced. +- 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: - allowlist enforcement (`PROVIDER_BASE_URL_ALLOWLIST`) - scheme restrictions (`https` by default) - - local/private-network blocking and per-request DNS revalidation checks for outbound runtime calls + - local/private-network blocking and 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, and compression-ratio guards + - 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: - - host ports bind to `127.0.0.1` unless `HOST_BIND_IP` override is set + - 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 diff --git a/docker-compose.yml b/docker-compose.yml index 2254284..a3b8d40 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,23 +2,25 @@ services: db: image: postgres:16-alpine environment: - POSTGRES_USER: dcm - POSTGRES_PASSWORD: dcm - POSTGRES_DB: dcm - ports: - - "${HOST_BIND_IP:-127.0.0.1}:5432:5432" + POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER must be set} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set} + POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB must be set} volumes: - db-data:/var/lib/postgresql/data healthcheck: - test: ["CMD-SHELL", "pg_isready -U dcm -d dcm"] + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:?POSTGRES_USER must be set} -d ${POSTGRES_DB:?POSTGRES_DB must be set}"] interval: 10s timeout: 5s retries: 10 redis: image: redis:7-alpine - ports: - - "${HOST_BIND_IP:-127.0.0.1}:6379:6379" + command: + - "redis-server" + - "--appendonly" + - "yes" + - "--requirepass" + - "${REDIS_PASSWORD:?REDIS_PASSWORD must be set}" volumes: - redis-data:/data @@ -26,10 +28,8 @@ services: image: typesense/typesense:29.0 command: - "--data-dir=/data" - - "--api-key=dcm-typesense-key" + - "--api-key=${TYPESENSE_API_KEY:?TYPESENSE_API_KEY must be set}" - "--enable-cors" - ports: - - "${HOST_BIND_IP:-127.0.0.1}:8108:8108" volumes: - typesense-data:/data @@ -37,12 +37,16 @@ services: build: context: ./backend environment: - APP_ENV: development - DATABASE_URL: postgresql+psycopg://dcm:dcm@db:5432/dcm - REDIS_URL: redis://redis:6379/0 + APP_ENV: ${APP_ENV:-development} + DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set} + REDIS_URL: ${REDIS_URL:?REDIS_URL must be set} + REDIS_SECURITY_MODE: ${REDIS_SECURITY_MODE:-auto} + REDIS_TLS_MODE: ${REDIS_TLS_MODE:-auto} + ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS: ${ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS:-true} STORAGE_ROOT: /data/storage ADMIN_API_TOKEN: ${ADMIN_API_TOKEN:?ADMIN_API_TOKEN must be set} USER_API_TOKEN: ${USER_API_TOKEN:?USER_API_TOKEN must be set} + APP_SETTINGS_ENCRYPTION_KEY: ${APP_SETTINGS_ENCRYPTION_KEY:?APP_SETTINGS_ENCRYPTION_KEY must be set} PROVIDER_BASE_URL_ALLOWLIST: '${PROVIDER_BASE_URL_ALLOWLIST:-["api.openai.com"]}' PROVIDER_BASE_URL_ALLOW_HTTP: ${PROVIDER_BASE_URL_ALLOW_HTTP:-false} PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK: ${PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK:-false} @@ -52,7 +56,7 @@ services: TYPESENSE_PROTOCOL: http TYPESENSE_HOST: typesense TYPESENSE_PORT: 8108 - TYPESENSE_API_KEY: dcm-typesense-key + TYPESENSE_API_KEY: ${TYPESENSE_API_KEY:?TYPESENSE_API_KEY must be set} TYPESENSE_COLLECTION_NAME: documents ports: - "${HOST_BIND_IP:-127.0.0.1}:8000:8000" @@ -74,14 +78,18 @@ services: worker: build: context: ./backend - command: ["rq", "worker", "dcm", "--url", "redis://redis:6379/0"] + command: ["sh", "-c", "rq worker dcm --url \"$REDIS_URL\""] environment: - APP_ENV: development - DATABASE_URL: postgresql+psycopg://dcm:dcm@db:5432/dcm - REDIS_URL: redis://redis:6379/0 + APP_ENV: ${APP_ENV:-development} + DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set} + REDIS_URL: ${REDIS_URL:?REDIS_URL must be set} + REDIS_SECURITY_MODE: ${REDIS_SECURITY_MODE:-auto} + REDIS_TLS_MODE: ${REDIS_TLS_MODE:-auto} + ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS: ${ALLOW_DEVELOPMENT_ANONYMOUS_USER_ACCESS:-true} STORAGE_ROOT: /data/storage ADMIN_API_TOKEN: ${ADMIN_API_TOKEN:?ADMIN_API_TOKEN must be set} USER_API_TOKEN: ${USER_API_TOKEN:?USER_API_TOKEN must be set} + APP_SETTINGS_ENCRYPTION_KEY: ${APP_SETTINGS_ENCRYPTION_KEY:?APP_SETTINGS_ENCRYPTION_KEY must be set} PROVIDER_BASE_URL_ALLOWLIST: '${PROVIDER_BASE_URL_ALLOWLIST:-["api.openai.com"]}' PROVIDER_BASE_URL_ALLOW_HTTP: ${PROVIDER_BASE_URL_ALLOW_HTTP:-false} PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK: ${PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK:-false} @@ -90,7 +98,7 @@ services: TYPESENSE_PROTOCOL: http TYPESENSE_HOST: typesense TYPESENSE_PORT: 8108 - TYPESENSE_API_KEY: dcm-typesense-key + TYPESENSE_API_KEY: ${TYPESENSE_API_KEY:?TYPESENSE_API_KEY must be set} TYPESENSE_COLLECTION_NAME: documents volumes: - ./backend/app:/app/app @@ -112,7 +120,7 @@ services: context: ./frontend environment: VITE_API_BASE: ${VITE_API_BASE:-http://localhost:8000/api/v1} - VITE_API_TOKEN: ${VITE_API_TOKEN:-${USER_API_TOKEN:-}} + VITE_API_TOKEN: ${VITE_API_TOKEN:-} ports: - "${HOST_BIND_IP:-127.0.0.1}:5173:5173" volumes: diff --git a/frontend/src/components/DocumentViewer.tsx b/frontend/src/components/DocumentViewer.tsx index b19936a..ea37a5e 100644 --- a/frontend/src/components/DocumentViewer.tsx +++ b/frontend/src/components/DocumentViewer.tsx @@ -19,6 +19,47 @@ import type { DmsDocument, DmsDocumentDetail } from '../types'; import PathInput from './PathInput'; import TagInput from './TagInput'; +const SAFE_IMAGE_PREVIEW_MIME_TYPES = new Set([ + 'image/bmp', + 'image/gif', + 'image/jpeg', + 'image/jpg', + 'image/png', + 'image/webp', +]); + +const SAFE_IFRAME_PREVIEW_MIME_TYPES = new Set([ + 'application/json', + 'application/pdf', + 'text/csv', + 'text/markdown', + 'text/plain', +]); + +/** + * Normalizes MIME values by stripping parameters and lowercasing for stable comparison. + */ +function normalizeMimeType(mimeType: string | null | undefined): string { + if (!mimeType) { + return ''; + } + return mimeType.split(';')[0]?.trim().toLowerCase() ?? ''; +} + +/** + * Resolves whether a MIME type is safe to render as an image preview. + */ +function isSafeImagePreviewMimeType(mimeType: string): boolean { + return SAFE_IMAGE_PREVIEW_MIME_TYPES.has(mimeType); +} + +/** + * Resolves whether a MIME type is safe to render inside a sandboxed iframe preview. + */ +function isSafeIframePreviewMimeType(mimeType: string): boolean { + return SAFE_IFRAME_PREVIEW_MIME_TYPES.has(mimeType); +} + /** * Defines props for the selected document viewer panel. */ @@ -60,6 +101,30 @@ export default function DocumentViewer({ const [error, setError] = useState(null); const previewObjectUrlRef = useRef(null); + /** + * Resolves normalized MIME type used by preview safety checks. + */ + const previewMimeType = useMemo(() => normalizeMimeType(document?.mime_type), [document?.mime_type]); + + /** + * Resolves whether selected document should render as a safe image element in preview. + */ + const isImageDocument = useMemo(() => { + return isSafeImagePreviewMimeType(previewMimeType); + }, [previewMimeType]); + + /** + * Resolves whether selected document should render in sandboxed iframe preview. + */ + const canRenderIframePreview = useMemo(() => { + return isSafeIframePreviewMimeType(previewMimeType); + }, [previewMimeType]); + + /** + * Resolves whether selected document supports any inline preview mode. + */ + const canRenderInlinePreview = isImageDocument || canRenderIframePreview; + /** * Syncs editable metadata fields whenever selection changes. */ @@ -100,6 +165,12 @@ export default function DocumentViewer({ setIsLoadingPreview(false); return; } + if (!canRenderInlinePreview) { + revokePreviewObjectUrl(); + setPreviewObjectUrl(null); + setIsLoadingPreview(false); + return; + } let cancelled = false; setIsLoadingPreview(true); @@ -131,7 +202,7 @@ export default function DocumentViewer({ cancelled = true; revokePreviewObjectUrl(); }; - }, [document?.id]); + }, [document?.id, canRenderInlinePreview]); /** * Refreshes editable metadata from list updates only while form is clean. @@ -183,16 +254,6 @@ export default function DocumentViewer({ }; }, [document?.id]); - /** - * Resolves whether selected document should render as an image element in preview. - */ - const isImageDocument = useMemo(() => { - if (!document) { - return false; - } - return document.mime_type.startsWith('image/'); - }, [document]); - /** * Extracts provider/transcription errors from document metadata for user visibility. */ @@ -482,11 +543,22 @@ export default function DocumentViewer({ {previewObjectUrl ? ( isImageDocument ? ( {document.original_filename} + ) : canRenderIframePreview ? ( +