Try a unified api endpoint

.env.example

@@ -4,6 +4,9 @@
 # Development defaults (HTTP local stack)
 APP_ENV=development
 HOST_BIND_IP=127.0.0.1
+# Optional host directory for persistent bind mounts in docker-compose.yml.
+# Defaults to ./data when unset.
+# DCM_DATA_DIR=./data
 
 POSTGRES_USER=dcm
 POSTGRES_PASSWORD=ChangeMe-Postgres-Secret
@@ -24,6 +27,8 @@ AUTH_LOGIN_FAILURE_WINDOW_SECONDS=900
 AUTH_LOGIN_LOCKOUT_BASE_SECONDS=30
 AUTH_LOGIN_LOCKOUT_MAX_SECONDS=900
 # Optional cookie controls for split frontend/api hosts:
+# Leave AUTH_COOKIE_DOMAIN empty unless you explicitly need a parent-domain CSRF cookie mirror.
+# Host-only auth cookies are issued automatically for the API host.
 # AUTH_COOKIE_DOMAIN=docs.lan
 # AUTH_COOKIE_SAMESITE=auto
 
@@ -42,8 +47,11 @@ PROVIDER_BASE_URL_ALLOWLIST=[]
 
 PUBLIC_BASE_URL=http://localhost:8000
 CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]
-# Used at build time for production frontend image, and at runtime in development.
+# Leave empty to use same-origin /api/v1 through the frontend proxy.
+# Set an absolute URL only when you intentionally want split-origin frontend/API traffic.
 VITE_API_BASE=
+# Development-only Vite proxy target. Docker compose sets this to http://api:8000 automatically.
+VITE_API_PROXY_TARGET=http://localhost:8000
 # Development-only Vite host allowlist override.
 VITE_ALLOWED_HOSTS=
 

.gitignore

@@ -20,9 +20,8 @@ build/
 !.env.example
 
 # Data and generated artifacts (runtime only)
-data/postgres/
-data/redis/
-data/storage/
+data/
+typesense-data/
 
 # OS / IDE
 .DS_Store

AGENTS.md

@@ -3,7 +3,7 @@
 ## Stack Snapshot
 - DMS monorepo with FastAPI API + RQ worker (`backend/`) and React + Vite + TypeScript frontend (`frontend/`).
 - Services in `docker-compose.yml`: `api`, `worker`, `frontend`, `db` (Postgres), `redis`, `typesense`.
-- Runtime persistence uses Docker named volumes (`db-data`, `redis-data`, `dcm-storage`, `typesense-data`).
+- Runtime persistence uses host bind mounts under `${DCM_DATA_DIR:-./data}` (`db-data`, `redis-data`, `storage`, `typesense-data`).
 
 ## Project Layout
 - Backend app code: `backend/app/` (`api/`, `services/`, `db/`, `models/`, `schemas/`, `worker/`).
@@ -25,7 +25,7 @@ If required to run the docker image, follow these steps:
 - Frontend dev only: `cd frontend && npm run dev`
 - Frontend production build: `cd frontend && npm run build`
 
-## Validation
+## Validation 
 - No automated test suite is currently committed.
 - Manual checks for code changes inside VM: `GET /api/v1/health`, upload + processing flow, search, document preview/download, and clean `docker compose logs -f` output for `api` and `worker`.
 

README.md

@@ -113,17 +113,26 @@ docker compose logs -f api worker
 
 ## Where Your Data Is Stored
 
-LedgerDock stores data in Docker volumes so it survives container restarts:
+LedgerDock stores persistent runtime data in host bind mounts. By default the host root is `./data`, or set `DCM_DATA_DIR` to move it:
 
-- `db-data` for PostgreSQL data
-- `redis-data` for Redis data
-- `dcm-storage` for uploaded files and app storage
-- `typesense-data` for the search index
+- `${DCM_DATA_DIR:-./data}/db-data` for PostgreSQL data
+- `${DCM_DATA_DIR:-./data}/redis-data` for Redis data
+- `${DCM_DATA_DIR:-./data}/storage` for uploaded files and app storage
+- `${DCM_DATA_DIR:-./data}/typesense-data` for the search index
+
+On startup, Compose runs a one-shot `storage-init` service that creates the storage tree and applies write access for the backend runtime user `uid=10001`. If you want to inspect or repair it manually, use:
+
+```bash
+mkdir -p ${DCM_DATA_DIR:-./data}/storage
+sudo chown -R 10001:10001 ${DCM_DATA_DIR:-./data}/storage
+sudo chmod -R u+rwX,g+rwX ${DCM_DATA_DIR:-./data}/storage
+```
 
 To remove everything, including data:
 
 ```bash
-docker compose down -v
+docker compose down
+rm -rf ${DCM_DATA_DIR:-./data}
 ```
 
 Warning: this permanently deletes your LedgerDock data on this machine.

backend/app/api/auth.py

@@ -54,6 +54,28 @@ def _requires_csrf_validation(method: str) -> bool:
     return method.upper() in CSRF_PROTECTED_METHODS
 
 
+def _extract_cookie_values(request: Request, cookie_name: str) -> tuple[str, ...]:
+    """Extracts all values for one cookie name from raw Cookie header order."""
+
+    request_headers = getattr(request, "headers", None)
+    raw_cookie_header = request_headers.get("cookie", "") if request_headers is not None else ""
+    if not raw_cookie_header:
+        return ()
+
+    extracted_values: list[str] = []
+    for cookie_pair in raw_cookie_header.split(";"):
+        normalized_pair = cookie_pair.strip()
+        if not normalized_pair or "=" not in normalized_pair:
+            continue
+        key, value = normalized_pair.split("=", 1)
+        if key.strip() != cookie_name:
+            continue
+        normalized_value = value.strip()
+        if normalized_value:
+            extracted_values.append(normalized_value)
+    return tuple(extracted_values)
+
+
 def _raise_unauthorized() -> None:
     """Raises a 401 challenge response for missing or invalid auth sessions."""
 
@@ -85,24 +107,39 @@ def get_request_auth_context(
 
     token = credentials.credentials.strip() if credentials is not None and credentials.credentials else ""
     using_cookie_session = False
+    session_candidates: list[str] = []
 
     if not token:
-        token = (session_cookie or "").strip()
         using_cookie_session = True
-    if not token:
-        _raise_unauthorized()
+        session_candidates = [candidate for candidate in _extract_cookie_values(request, SESSION_COOKIE_NAME) if candidate]
+        normalized_session_cookie = (session_cookie or "").strip()
+        if normalized_session_cookie and normalized_session_cookie not in session_candidates:
+            session_candidates.append(normalized_session_cookie)
+        if not session_candidates:
+            _raise_unauthorized()
 
     if _requires_csrf_validation(request.method) and using_cookie_session:
         normalized_csrf_header = (csrf_header or "").strip()
+        csrf_candidates = [candidate for candidate in _extract_cookie_values(request, CSRF_COOKIE_NAME) if candidate]
         normalized_csrf_cookie = (csrf_cookie or "").strip()
+        if normalized_csrf_cookie and normalized_csrf_cookie not in csrf_candidates:
+            csrf_candidates.append(normalized_csrf_cookie)
         if (
-            not normalized_csrf_cookie
+            not csrf_candidates
             or not normalized_csrf_header
-            or not hmac.compare_digest(normalized_csrf_cookie, normalized_csrf_header)
+            or not any(hmac.compare_digest(candidate, normalized_csrf_header) for candidate in csrf_candidates)
         ):
             _raise_csrf_rejected()
 
-    resolved_session = resolve_auth_session(session, token=token)
+    resolved_session = None
+    if token:
+        resolved_session = resolve_auth_session(session, token=token)
+    else:
+        for candidate in session_candidates:
+            resolved_session = resolve_auth_session(session, token=candidate)
+            if resolved_session is not None and resolved_session.user is not None:
+                break
+
     if resolved_session is None or resolved_session.user is None:
         _raise_unauthorized()
 

backend/app/api/routes_auth.py

@@ -30,9 +30,14 @@ from app.services.auth_login_throttle import (
 )
 
 try:
-    from fastapi import Response
+    from fastapi import Cookie, Response
 except (ImportError, AttributeError):
     from fastapi.responses import Response
+
+    def Cookie(_default=None, **_kwargs):  # type: ignore[no-untyped-def]
+        """Compatibility fallback for environments that stub fastapi without request params."""
+
+        return None
 from app.services.authentication import authenticate_user, issue_user_session, revoke_auth_session
 
 router = APIRouter(prefix="/auth", tags=["auth"])
@@ -85,12 +90,49 @@ def _resolve_cookie_domain() -> str | None:
     return configured_domain
 
 
-def _resolve_cookie_samesite(secure_cookie: bool) -> str:
-    """Returns cookie SameSite mode with secure-aware defaults for browser compatibility."""
+def _resolve_cookie_domains() -> tuple[str | None, ...]:
+    """Returns cookie domain variants with a host-only cookie first for browser compatibility."""
+
+    configured_domain = _resolve_cookie_domain()
+    if configured_domain is None:
+        return (None,)
+    return (None, configured_domain)
+
+
+def _request_matches_cookie_domain(request: Request) -> bool:
+    """Returns whether request and origin hosts both sit under the configured cookie domain."""
+
+    configured_domain = _resolve_cookie_domain()
+    if configured_domain is None:
+        return False
+
+    origin_header = request.headers.get("origin", "").strip()
+    origin_host = urlparse(origin_header).hostname.strip().lower() if origin_header else ""
+    if not origin_host:
+        return False
+
+    request_url = getattr(request, "url", None)
+    request_host = str(getattr(request_url, "hostname", "")).strip().lower() if request_url is not None else ""
+    if not request_host:
+        parsed_public_base_url = urlparse(get_settings().public_base_url.strip())
+        request_host = parsed_public_base_url.hostname.strip().lower() if parsed_public_base_url.hostname else ""
+    if not request_host:
+        return False
+
+    def _matches(candidate: str) -> bool:
+        return candidate == configured_domain or candidate.endswith(f".{configured_domain}")
+
+    return _matches(origin_host) and _matches(request_host)
+
+
+def _resolve_cookie_samesite(request: Request, secure_cookie: bool) -> str:
+    """Returns cookie SameSite mode with same-site subdomain compatibility defaults."""
 
     configured_mode = get_settings().auth_cookie_samesite.strip().lower()
-    if configured_mode in {"strict", "lax", "none"}:
+    if configured_mode in {"strict", "lax"}:
         return configured_mode
+    if configured_mode == "none":
+        return "lax" if _request_matches_cookie_domain(request) else "none"
     return "none" if secure_cookie else "lax"
 
 
@@ -102,30 +144,39 @@ def _session_cookie_ttl_seconds(expires_at: datetime) -> int:
     return max(1, ttl)
 
 
-def _set_session_cookie(response: Response, session_token: str, *, expires_at: datetime, secure: bool) -> None:
+def _set_session_cookie(
+    response: Response,
+    session_token: str,
+    *,
+    request: Request,
+    expires_at: datetime,
+    secure: bool,
+) -> None:
     """Stores the issued session token in a browser HttpOnly auth cookie."""
 
     if response is None or not hasattr(response, "set_cookie"):
         return
     expires_seconds = _session_cookie_ttl_seconds(expires_at)
-    cookie_domain = _resolve_cookie_domain()
-    same_site_mode = _resolve_cookie_samesite(secure)
-    response.set_cookie(
-        SESSION_COOKIE_NAME,
-        value=session_token,
-        max_age=expires_seconds,
-        httponly=True,
-        secure=secure,
-        samesite=same_site_mode,
-        path="/",
-        domain=cookie_domain,
-    )
+    same_site_mode = _resolve_cookie_samesite(request, secure)
+    for cookie_domain in _resolve_cookie_domains():
+        cookie_kwargs = {
+            "value": session_token,
+            "max_age": expires_seconds,
+            "httponly": True,
+            "secure": secure,
+            "samesite": same_site_mode,
+            "path": "/",
+        }
+        if cookie_domain is not None:
+            cookie_kwargs["domain"] = cookie_domain
+        response.set_cookie(SESSION_COOKIE_NAME, **cookie_kwargs)
 
 
 def _set_csrf_cookie(
     response: Response,
     csrf_token: str,
     *,
+    request: Request,
     expires_at: datetime,
     secure: bool,
 ) -> None:
@@ -133,18 +184,19 @@ def _set_csrf_cookie(
 
     if response is None or not hasattr(response, "set_cookie"):
         return
-    cookie_domain = _resolve_cookie_domain()
-    same_site_mode = _resolve_cookie_samesite(secure)
-    response.set_cookie(
-        CSRF_COOKIE_NAME,
-        value=csrf_token,
-        max_age=_session_cookie_ttl_seconds(expires_at),
-        httponly=False,
-        secure=secure,
-        samesite=same_site_mode,
-        path="/",
-        domain=cookie_domain,
-    )
+    same_site_mode = _resolve_cookie_samesite(request, secure)
+    for cookie_domain in _resolve_cookie_domains():
+        cookie_kwargs = {
+            "value": csrf_token,
+            "max_age": _session_cookie_ttl_seconds(expires_at),
+            "httponly": False,
+            "secure": secure,
+            "samesite": same_site_mode,
+            "path": "/",
+        }
+        if cookie_domain is not None:
+            cookie_kwargs["domain"] = cookie_domain
+        response.set_cookie(CSRF_COOKIE_NAME, **cookie_kwargs)
 
 
 def _clear_session_cookies(response: Response) -> None:
@@ -152,9 +204,12 @@ def _clear_session_cookies(response: Response) -> None:
 
     if response is None or not hasattr(response, "delete_cookie"):
         return
-    cookie_domain = _resolve_cookie_domain()
-    response.delete_cookie(SESSION_COOKIE_NAME, path="/", domain=cookie_domain)
-    response.delete_cookie(CSRF_COOKIE_NAME, path="/", domain=cookie_domain)
+    for cookie_domain in _resolve_cookie_domains():
+        delete_kwargs = {"path": "/"}
+        if cookie_domain is not None:
+            delete_kwargs["domain"] = cookie_domain
+        response.delete_cookie(SESSION_COOKIE_NAME, **delete_kwargs)
+        response.delete_cookie(CSRF_COOKIE_NAME, **delete_kwargs)
 
 
 @router.post("/login", response_model=AuthLoginResponse)
@@ -236,12 +291,14 @@ def login(
     _set_session_cookie(
         response,
         issued_session.token,
+        request=request,
         expires_at=issued_session.expires_at,
         secure=secure_cookie,
     )
     _set_csrf_cookie(
         response,
         csrf_token,
+        request=request,
         expires_at=issued_session.expires_at,
         secure=secure_cookie,
     )
@@ -255,9 +312,13 @@ def login(
 
 
 @router.get("/me", response_model=AuthSessionResponse)
-def me(context: AuthContext = Depends(require_user_or_admin)) -> AuthSessionResponse:
+def me(
+    context: AuthContext = Depends(require_user_or_admin),
+    csrf_cookie: str | None = Cookie(None, alias=CSRF_COOKIE_NAME),
+) -> AuthSessionResponse:
     """Returns current authenticated session identity and expiration metadata."""
 
+    normalized_csrf_cookie = (csrf_cookie or "").strip() or None
     return AuthSessionResponse(
         expires_at=context.expires_at,
         user=AuthUserResponse(
@@ -265,6 +326,7 @@ def me(context: AuthContext = Depends(require_user_or_admin)) -> AuthSessionResp
             username=context.username,
             role=context.role,
         ),
+        csrf_token=normalized_csrf_cookie,
     )
 
 

backend/app/schemas/auth.py

@@ -33,6 +33,7 @@ class AuthSessionResponse(BaseModel):
 
     user: AuthUserResponse
     expires_at: datetime
+    csrf_token: str | None = None
 
 
 class AuthLoginResponse(AuthSessionResponse):

backend/tests/test_security_controls.py

@@ -364,6 +364,7 @@ if "app.services.routing_pipeline" not in sys.modules:
 from fastapi import HTTPException
 
 from app.api.auth import AuthContext, require_admin
+from app.api import auth as auth_dependency_module
 from app.api import routes_auth as auth_routes_module
 from app.api import routes_documents as documents_routes_module
 from app.core import config as config_module
@@ -420,6 +421,96 @@ class AuthDependencyTests(unittest.TestCase):
         resolved = require_admin(context=auth_context)
         self.assertEqual(resolved.role, UserRole.ADMIN)
 
+    def test_csrf_validation_accepts_matching_token_among_duplicate_cookie_values(self) -> None:
+        """PATCH CSRF validation accepts header token matching any duplicate csrf cookie value."""
+
+        request = SimpleNamespace(
+            method="PATCH",
+            headers={"cookie": "dcm_session=session-token; dcm_csrf=stale-token; dcm_csrf=fresh-token"},
+        )
+        resolved_session = SimpleNamespace(
+            id=uuid.uuid4(),
+            expires_at=datetime.now(UTC),
+            user=SimpleNamespace(
+                id=uuid.uuid4(),
+                username="admin",
+                role=UserRole.ADMIN,
+            ),
+        )
+        with patch.object(auth_dependency_module, "resolve_auth_session", return_value=resolved_session):
+            context = auth_dependency_module.get_request_auth_context(
+                request=request,
+                credentials=None,
+                csrf_header="fresh-token",
+                csrf_cookie="stale-token",
+                session_cookie="session-token",
+                session=SimpleNamespace(),
+            )
+        self.assertEqual(context.username, "admin")
+        self.assertEqual(context.role, UserRole.ADMIN)
+
+    def test_csrf_validation_rejects_when_header_does_not_match_any_cookie_value(self) -> None:
+        """PATCH CSRF validation rejects requests when header token matches no csrf cookie values."""
+
+        request = SimpleNamespace(
+            method="PATCH",
+            headers={"cookie": "dcm_session=session-token; dcm_csrf=stale-token; dcm_csrf=fresh-token"},
+        )
+        resolved_session = SimpleNamespace(
+            id=uuid.uuid4(),
+            expires_at=datetime.now(UTC),
+            user=SimpleNamespace(
+                id=uuid.uuid4(),
+                username="admin",
+                role=UserRole.ADMIN,
+            ),
+        )
+        with patch.object(auth_dependency_module, "resolve_auth_session", return_value=resolved_session):
+            with self.assertRaises(HTTPException) as raised:
+                auth_dependency_module.get_request_auth_context(
+                    request=request,
+                    credentials=None,
+                    csrf_header="unknown-token",
+                    csrf_cookie="stale-token",
+                    session_cookie="session-token",
+                    session=SimpleNamespace(),
+                )
+        self.assertEqual(raised.exception.status_code, 403)
+        self.assertEqual(raised.exception.detail, "Invalid CSRF token")
+
+    def test_cookie_auth_accepts_matching_session_among_duplicate_cookie_values(self) -> None:
+        """Cookie auth accepts the first valid session token among duplicate cookie values."""
+
+        request = SimpleNamespace(
+            method="GET",
+            headers={"cookie": "dcm_session=stale-token; dcm_session=fresh-token"},
+        )
+        resolved_session = SimpleNamespace(
+            id=uuid.uuid4(),
+            expires_at=datetime.now(UTC),
+            user=SimpleNamespace(
+                id=uuid.uuid4(),
+                username="admin",
+                role=UserRole.ADMIN,
+            ),
+        )
+        with patch.object(
+            auth_dependency_module,
+            "resolve_auth_session",
+            side_effect=[None, resolved_session],
+        ) as resolve_mock:
+            context = auth_dependency_module.get_request_auth_context(
+                request=request,
+                credentials=None,
+                csrf_header=None,
+                csrf_cookie=None,
+                session_cookie="stale-token",
+                session=SimpleNamespace(),
+            )
+        self.assertEqual(context.username, "admin")
+        self.assertEqual(context.role, UserRole.ADMIN)
+        self.assertEqual(resolve_mock.call_count, 2)
+
 
 class DocumentCatalogVisibilityTests(unittest.TestCase):
     """Verifies predefined tag and path discovery visibility by caller role."""
@@ -784,22 +875,44 @@ class AuthLoginRouteThrottleTests(unittest.TestCase):
 
             self.commit_count += 1
 
-    @staticmethod
-    def _response_stub() -> SimpleNamespace:
+    class _ResponseStub:
+        """Captures response cookie calls for direct route invocation tests."""
+
+        def __init__(self) -> None:
+            self.set_cookie_calls: list[tuple[tuple[object, ...], dict[str, object]]] = []
+            self.delete_cookie_calls: list[tuple[tuple[object, ...], dict[str, object]]] = []
+
+        def set_cookie(self, *args: object, **kwargs: object) -> None:
+            """Records one set-cookie call."""
+
+            self.set_cookie_calls.append((args, kwargs))
+
+        def delete_cookie(self, *args: object, **kwargs: object) -> None:
+            """Records one delete-cookie call."""
+
+            self.delete_cookie_calls.append((args, kwargs))
+
+    @classmethod
+    def _response_stub(cls) -> "AuthLoginRouteThrottleTests._ResponseStub":
         """Builds a minimal response object for direct route invocation."""
 
-        return SimpleNamespace(
-            set_cookie=lambda *_args, **_kwargs: None,
-            delete_cookie=lambda *_args, **_kwargs: None,
-        )
+        return cls._ResponseStub()
 
     @staticmethod
-    def _request_stub(ip_address: str = "203.0.113.2", user_agent: str = "unit-test") -> SimpleNamespace:
+    def _request_stub(
+        ip_address: str = "203.0.113.2",
+        user_agent: str = "unit-test",
+        origin: str | None = None,
+    ) -> SimpleNamespace:
         """Builds request-like object containing client host and user-agent header fields."""
 
+        headers = {"user-agent": user_agent}
+        if origin:
+            headers["origin"] = origin
         return SimpleNamespace(
             client=SimpleNamespace(host=ip_address),
-            headers={"user-agent": user_agent},
+            headers=headers,
+            url=SimpleNamespace(hostname="api.docs.lan"),
         )
 
     def test_login_rejects_when_precheck_reports_active_throttle(self) -> None:
@@ -912,6 +1025,57 @@ class AuthLoginRouteThrottleTests(unittest.TestCase):
         self.assertEqual(raised.exception.detail, auth_routes_module.LOGIN_RATE_LIMITER_UNAVAILABLE_DETAIL)
         self.assertEqual(session.commit_count, 0)
 
+    def test_login_sets_host_only_and_parent_domain_cookie_variants(self) -> None:
+        """Successful login sets a host-only cookie and an optional parent-domain mirror."""
+
+        payload = auth_routes_module.AuthLoginRequest(username="admin", password="correct-password")
+        session = self._SessionStub()
+        response_stub = self._response_stub()
+        fake_user = SimpleNamespace(
+            id=uuid.uuid4(),
+            username="admin",
+            role=UserRole.ADMIN,
+        )
+        fake_session = SimpleNamespace(
+            token="session-token",
+            expires_at=datetime.now(UTC),
+        )
+        fake_settings = SimpleNamespace(
+            auth_cookie_domain="docs.lan",
+            auth_cookie_samesite="none",
+            public_base_url="https://api.docs.lan",
+        )
+        with (
+            patch.object(
+                auth_routes_module,
+                "check_login_throttle",
+                return_value=auth_login_throttle_module.LoginThrottleStatus(
+                    is_throttled=False,
+                    retry_after_seconds=0,
+                ),
+            ),
+            patch.object(auth_routes_module, "authenticate_user", return_value=fake_user),
+            patch.object(auth_routes_module, "clear_login_throttle"),
+            patch.object(auth_routes_module, "issue_user_session", return_value=fake_session),
+            patch.object(auth_routes_module, "get_settings", return_value=fake_settings),
+            patch.object(auth_routes_module.secrets, "token_urlsafe", return_value="csrf-token"),
+        ):
+            auth_routes_module.login(
+                payload=payload,
+                request=self._request_stub(origin="https://docs.lan"),
+                response=response_stub,
+                session=session,
+            )
+
+        session_cookie_calls = [call for call in response_stub.set_cookie_calls if call[0][0] == auth_routes_module.SESSION_COOKIE_NAME]
+        csrf_cookie_calls = [call for call in response_stub.set_cookie_calls if call[0][0] == auth_routes_module.CSRF_COOKIE_NAME]
+        self.assertEqual(len(session_cookie_calls), 2)
+        self.assertEqual(len(csrf_cookie_calls), 2)
+        self.assertFalse(any("domain" in kwargs and kwargs["domain"] is None for _args, kwargs in session_cookie_calls))
+        self.assertIn("domain", session_cookie_calls[1][1])
+        self.assertEqual(session_cookie_calls[1][1]["domain"], "docs.lan")
+        self.assertEqual(session_cookie_calls[0][1]["samesite"], "lax")
+
 
 class ProviderBaseUrlValidationTests(unittest.TestCase):
     """Verifies allowlist, scheme, and private-network SSRF protections."""

doc/api-contract.md

@@ -19,7 +19,7 @@ Primary implementation modules:
 - Login brute-force protection enforces Redis-backed throttle checks keyed by username and source IP.
 - State-changing requests from browser clients must send `x-csrf-token: <dcm_csrf>` in request headers (double-submit pattern).
 - For non-browser API clients, the optional `Authorization: Bearer <token>` path remains supported when the token is sent explicitly.
-- `GET /auth/me` returns current identity and role.
+- `GET /auth/me` returns current identity, role, and current CSRF token.
 - `POST /auth/logout` revokes current session token.
 
 Role matrix:

doc/operations-and-configuration.md

@@ -10,16 +10,17 @@
 - `worker` (RQ worker via `python -m app.worker.run_worker`)
 - `frontend` (Vite React UI)
 
-Persistent volumes:
-- `db-data`
-- `redis-data`
-- `dcm-storage`
-- `typesense-data`
+Persistent host bind mounts (default root `./data`, overridable with `DCM_DATA_DIR`):
+- `${DCM_DATA_DIR:-./data}/db-data`
+- `${DCM_DATA_DIR:-./data}/redis-data`
+- `${DCM_DATA_DIR:-./data}/storage`
+- `${DCM_DATA_DIR:-./data}/typesense-data`
 
 Reset all persisted runtime data:
 
 ```bash
-docker compose down -v
+docker compose down
+rm -rf ${DCM_DATA_DIR:-./data}
 ```
 
 ## Core Commands
@@ -42,6 +43,22 @@ Tail logs:
 docker compose logs -f
 ```
 
+## Host Bind Mounts
+
+Compose is configured with host bind mounts for persistent data. Ensure host directories exist and are writable by the backend runtime user.
+
+Backend and worker run as non-root user `uid=10001` inside containers. Compose bootstraps the storage bind mount through the one-shot `storage-init` service before either process starts. For manual inspection or repair of host-mounted storage paths:
+
+```bash
+mkdir -p ${DCM_DATA_DIR:-./data}/storage
+sudo chown -R 10001:10001 ${DCM_DATA_DIR:-./data}/storage
+sudo chmod -R u+rwX,g+rwX ${DCM_DATA_DIR:-./data}/storage
+```
+
+If permissions are incorrect, API startup fails with errors similar to:
+- `PermissionError: [Errno 13] Permission denied: '/data/storage'`
+- `FileNotFoundError` for `/data/storage/originals`
+
 ## Frontend Build Baseline
 
 The frontend Dockerfile uses `node:22-slim` with a standard `npm ci --no-audit` install step and no npm-specific build tuning flags.
@@ -70,8 +87,8 @@ Use `.env.example` as baseline. The table below documents user-managed settings
 | --- | --- | --- |
 | `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` (build-time value for production frontend image) |
+| `PUBLIC_BASE_URL` | `http://localhost:8000` or same-origin frontend host when proxying API through frontend | `https://app.example.com` when frontend proxies `/api`, or dedicated API origin if you intentionally keep split-origin routing |
+| `VITE_API_BASE` | empty to use same-origin `/api/v1` through frontend proxy, or explicit local URL when bypassing proxy | empty or `/api/v1` for same-origin production routing; only use `https://api.example.com/api/v1` when you intentionally keep split-origin frontend/API traffic |
 | `VITE_ALLOWED_HOSTS` | optional comma-separated hostnames, for example `localhost,docs.lan` | optional comma-separated public frontend hostnames, for example `app.example.com` |
 | `CORS_ORIGINS` | `["http://localhost:5173","http://localhost:3000"]` | exact frontend origins only, for example `["https://app.example.com"]` |
 | `REDIS_URL` | `redis://:<password>@redis:6379/0` in isolated local network | `rediss://:<password>@redis.internal:6379/0` |
@@ -81,8 +98,8 @@ Use `.env.example` as baseline. The table below documents user-managed settings
 | `AUTH_LOGIN_FAILURE_WINDOW_SECONDS` | default `900` | tune to identity-protection policy and support requirements |
 | `AUTH_LOGIN_LOCKOUT_BASE_SECONDS` | default `30` | tune to identity-protection policy and support requirements |
 | `AUTH_LOGIN_LOCKOUT_MAX_SECONDS` | default `900` | tune to identity-protection policy and support requirements |
-| `AUTH_COOKIE_DOMAIN` | empty (host-only cookies) | parent frontend/API domain for split hosts, for example `docs.lan` |
-| `AUTH_COOKIE_SAMESITE` | `auto` | `none` for cross-origin frontend/API deployments, `lax` or `strict` for same-origin |
+| `AUTH_COOKIE_DOMAIN` | empty (recommended; API always issues a host-only auth cookie) | optional parent domain only when you explicitly need a mirrored domain cookie, for example `docs.lan` |
+| `AUTH_COOKIE_SAMESITE` | `auto` | `none` only for truly cross-site frontend/API deployments; keep `auto` for same-site subdomains such as `docs.lan` and `api.docs.lan` |
 | `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"]` |
@@ -137,6 +154,7 @@ Recommended LIVE pattern:
 - `VITE_ALLOWED_HOSTS` only affects development mode where Vite is running.
 - API auth cookies support optional domain and SameSite configuration through `AUTH_COOKIE_DOMAIN` and `AUTH_COOKIE_SAMESITE`.
 - HTTPS cookie security detection falls back to `PUBLIC_BASE_URL` scheme when proxy headers are missing.
+- CSRF validation accepts header matches against any `dcm_csrf` cookie value in the request, covering stale plus fresh duplicate-cookie transitions.
 - Session authentication is cookie-based; browser reloads and new tabs can reuse an active session until it expires or is revoked.
 - Protected media and file download flows still use authenticated fetch plus blob/object URL handling.
 

docker-compose.yml

@@ -1,4 +1,19 @@
 services:
+  storage-init:
+    build:
+      context: ./backend
+    user: "0:0"
+    command:
+      - "sh"
+      - "-c"
+      - >
+        mkdir -p /data/storage/originals /data/storage/derived/previews /data/storage/tmp &&
+        chown -R 10001:10001 /data/storage &&
+        chmod -R u+rwX,g+rwX /data/storage
+    volumes:
+      - ${DCM_DATA_DIR:-./data}/storage:/data/storage
+    restart: "no"
+
   db:
     image: postgres:16-alpine
     environment:
@@ -6,7 +21,7 @@ services:
       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
+      - ${DCM_DATA_DIR:-./data}/db-data:/var/lib/postgresql/data
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:?POSTGRES_USER must be set} -d ${POSTGRES_DB:?POSTGRES_DB must be set}"]
       interval: 10s
@@ -25,18 +40,18 @@ services:
       - "--requirepass"
       - "${REDIS_PASSWORD:?REDIS_PASSWORD must be set}"
     volumes:
-      - redis-data:/data
+      - ${DCM_DATA_DIR:-./data}/redis-data:/data
     networks:
       - internal
 
   typesense:
-    image: typesense/typesense:29.0
+    image: typesense/typesense:30.2.rc6
     command:
       - "--data-dir=/data"
       - "--api-key=${TYPESENSE_API_KEY:?TYPESENSE_API_KEY must be set}"
       - "--enable-cors"
     volumes:
-      - typesense-data:/data
+      - ${DCM_DATA_DIR:-./data}/typesense-data:/data
     restart: unless-stopped
     networks:
       - internal
@@ -76,20 +91,22 @@ services:
       TYPESENSE_PORT: 8108
       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"
+    # ports:
+    #   - "${HOST_BIND_IP:-127.0.0.1}:8000:8000"
     security_opt:
       - no-new-privileges:true
     cap_drop:
       - ALL
     volumes:
       - ./backend/app:/app/app
-      - dcm-storage:/data
+      - ${DCM_DATA_DIR:-./data}/storage:/data/storage
     depends_on:
       db:
         condition: service_healthy
       redis:
         condition: service_started
+      storage-init:
+        condition: service_completed_successfully
       typesense:
         condition: service_started
     networks:
@@ -124,7 +141,7 @@ services:
       TYPESENSE_COLLECTION_NAME: documents
     volumes:
       - ./backend/app:/app/app
-      - dcm-storage:/data
+      - ${DCM_DATA_DIR:-./data}/storage:/data/storage
     security_opt:
       - no-new-privileges:true
     cap_drop:
@@ -134,6 +151,8 @@ services:
         condition: service_healthy
       redis:
         condition: service_started
+      storage-init:
+        condition: service_completed_successfully
       typesense:
         condition: service_started
     restart: unless-stopped
@@ -148,10 +167,11 @@ services:
         VITE_API_BASE: ${VITE_API_BASE:-}
     environment:
       VITE_API_BASE: ${VITE_API_BASE:-}
+      VITE_API_PROXY_TARGET: ${VITE_API_PROXY_TARGET:-http://api:8000}
       CORS_ORIGINS: '${CORS_ORIGINS:-["http://localhost:5173","http://localhost:3000"]}'
       VITE_ALLOWED_HOSTS: ${VITE_ALLOWED_HOSTS:-}
-  #  ports:
- #    - "${HOST_BIND_IP:-127.0.0.1}:5173:5173"
+    # ports:
+    #   - "${HOST_BIND_IP:-127.0.0.1}:5173:5173"
     volumes:
       - ./frontend/src:/app/src
       - ./frontend/index.html:/app/index.html
@@ -169,12 +189,6 @@ services:
       internal:
     restart: unless-stopped
 
-volumes:
-  db-data:
-  redis-data:
-  dcm-storage:
-  typesense-data:
-
 networks:
   internal:
     driver: bridge

frontend/nginx.conf

@@ -2,10 +2,20 @@ server {
     listen 5173;
     listen [::]:5173;
     server_name _;
+    client_max_body_size 100m;
 
     root /usr/share/nginx/html;
     index index.html;
 
+    location /api/ {
+        proxy_pass http://api:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
     location / {
         try_files $uri $uri/ /index.html;
     }

frontend/src/lib/api.ts

@@ -16,7 +16,7 @@ import type {
 } from '../types';
 
 /**
- * Resolves backend base URL from environment with host-derived HTTP fallback.
+ * Resolves backend base URL from environment with same-origin proxy fallback.
  */
 function resolveApiBase(): string {
   const envValue = import.meta.env?.VITE_API_BASE;
@@ -27,8 +27,8 @@ function resolveApiBase(): string {
     }
   }
 
-  if (typeof window !== 'undefined' && window.location?.hostname) {
-    return `${window.location.protocol}//${window.location.hostname}:8000/api/v1`;
+  if (typeof window !== 'undefined' && window.location?.origin) {
+    return '/api/v1';
   }
   return 'http://localhost:8000/api/v1';
 }
@@ -41,6 +41,7 @@ const API_BASE = resolveApiBase();
 const CSRF_COOKIE_NAME = "dcm_csrf";
 const CSRF_HEADER_NAME = "x-csrf-token";
 const CSRF_SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const CSRF_SESSION_STORAGE_KEY = "dcm_csrf_token";
 
 type ApiRequestInit = Omit<RequestInit, 'headers'> & { headers?: HeadersInit };
 
@@ -65,7 +66,38 @@ function getCookieValue(name: string): string | undefined {
  * Resolves the runtime CSRF token from browser cookie storage for API requests.
  */
 function resolveCsrfToken(): string | undefined {
-  return getCookieValue(CSRF_COOKIE_NAME);
+  const cookieToken = getCookieValue(CSRF_COOKIE_NAME);
+  if (cookieToken) {
+    return cookieToken;
+  }
+  return loadStoredCsrfToken();
+}
+
+/**
+ * Loads the runtime CSRF token from browser session storage.
+ */
+function loadStoredCsrfToken(): string | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+  const rawValue = window.sessionStorage.getItem(CSRF_SESSION_STORAGE_KEY);
+  const normalizedValue = rawValue?.trim();
+  return normalizedValue ? normalizedValue : undefined;
+}
+
+/**
+ * Persists or clears a runtime CSRF token in browser session storage.
+ */
+function persistCsrfToken(token: string | undefined | null): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const normalizedValue = typeof token === "string" ? token.trim() : "";
+  if (!normalizedValue) {
+    window.sessionStorage.removeItem(CSRF_SESSION_STORAGE_KEY);
+    return;
+  }
+  window.sessionStorage.setItem(CSRF_SESSION_STORAGE_KEY, normalizedValue);
 }
 
 /**
@@ -181,7 +213,9 @@ export async function loginWithPassword(username: string, password: string): Pro
     }
     throw new Error('Login failed');
   }
-  return response.json() as Promise<AuthLoginResponse>;
+  const payload = await (response.json() as Promise<AuthLoginResponse>);
+  persistCsrfToken(payload.csrf_token);
+  return payload;
 }
 
 /**
@@ -196,7 +230,9 @@ export async function getCurrentAuthSession(): Promise<AuthSessionInfo> {
     }
     throw new Error('Failed to load authentication session');
   }
-  return response.json() as Promise<AuthSessionInfo>;
+  const payload = await (response.json() as Promise<AuthSessionInfo>);
+  persistCsrfToken(payload.csrf_token);
+  return payload;
 }
 
 /**
@@ -206,6 +242,7 @@ export async function logoutCurrentSession(): Promise<void> {
   const response = await apiRequest(`${API_BASE}/auth/logout`, {
     method: 'POST',
   });
+  persistCsrfToken(undefined);
   if (!response.ok && response.status !== 401) {
     const detail = await responseErrorDetail(response);
     if (detail) {

frontend/src/types.ts

@@ -73,6 +73,7 @@ export interface AuthUser {
 export interface AuthSessionInfo {
   user: AuthUser;
   expires_at: string;
+  csrf_token?: string;
 }
 
 /**

frontend/vite.config.ts

@@ -74,11 +74,19 @@ function buildAllowedHosts(env: Record<string, string>): string[] | undefined {
 export default defineConfig(({ mode }) => {
   const env = loadEnv(mode, process.cwd(), '');
   const allowedHosts = buildAllowedHosts(env);
+  const apiProxyTarget = env.VITE_API_PROXY_TARGET?.trim() || 'http://localhost:8000';
 
   return {
     server: {
       host: '0.0.0.0',
       port: 5173,
+      proxy: {
+        '/api': {
+          target: apiProxyTarget,
+          changeOrigin: false,
+          secure: false,
+        },
+      },
       ...(allowedHosts ? { allowedHosts } : {}),
     },
   };