feat(auth): release-validation pass for 2.0-rc — 12 blockers + simplify follow-ups (#2008)

* feat(auth): introduce backend auth module Port RFC-001 authentication core from PR #1728: - JWT token handling (create_access_token, decode_token, TokenPayload) - Password hashing (bcrypt) with verify_password - SQLite UserRepository with base interface - Provider Factory pattern (LocalAuthProvider) - CLI reset_admin tool - Auth-specific errors (AuthErrorCode, TokenError, AuthErrorResponse) Deps: - bcrypt>=4.0.0 - pyjwt>=2.9.0 - email-validator>=2.0.0 - backend/uv.toml pins public PyPI index Tests: 12 pure unit tests (test_auth_config.py, test_auth_errors.py). Scope note: authz.py, test_auth.py, and test_auth_type_system.py are deferred to commit 2 because they depend on middleware and deps wiring that is not yet in place. Commit 1 stays "pure new files only" as the spec mandates. * feat(auth): wire auth end-to-end (middleware + frontend replacement) Backend: - Port auth_middleware, csrf_middleware, langgraph_auth, routers/auth - Port authz decorator (owner_filter_key defaults to 'owner_id') - Merge app.py: register AuthMiddleware + CSRFMiddleware + CORS, add _ensure_admin_user lifespan hook, _migrate_orphaned_threads helper, register auth router - Merge deps.py: add get_local_provider, get_current_user_from_request, get_optional_user_from_request; keep get_current_user as thin str|None adapter for feedback router - langgraph.json: add auth path pointing to langgraph_auth.py:auth - Rename metadata['user_id'] -> metadata['owner_id'] in langgraph_auth (both metadata write and LangGraph filter dict) + test fixtures Frontend: - Delete better-auth library and api catch-all route - Remove better-auth npm dependency and env vars (BETTER_AUTH_SECRET, BETTER_AUTH_GITHUB_*) from env.js - Port frontend/src/core/auth/* (AuthProvider, gateway-config, proxy-policy, server-side getServerSideUser, types) - Port frontend/src/core/api/fetcher.ts - Port (auth)/layout, (auth)/login, (auth)/setup pages - Rewrite workspace/layout.tsx as server component that calls getServerSideUser and wraps in AuthProvider - Port workspace/workspace-content.tsx for the client-side sidebar logic Tests: - Port 5 auth test files (test_auth, test_auth_middleware, test_auth_type_system, test_ensure_admin, test_langgraph_auth) - 176 auth tests PASS After this commit: login/logout/registration flow works, but persistence layer does not yet filter by owner_id. Commit 4 closes that gap. * feat(auth): account settings page + i18n - Port account-settings-page.tsx (change password, change email, logout) - Wire into settings-dialog.tsx as new "account" section with UserIcon, rendered first in the section list - Add i18n keys: - en-US/zh-CN: settings.sections.account ("Account" / "账号") - en-US/zh-CN: button.logout ("Log out" / "退出登录") - types.ts: matching type declarations * feat(auth): enforce owner_id across 2.0-rc persistence layer Add request-scoped contextvar-based owner filtering to threads_meta, runs, run_events, and feedback repositories. Router code is unchanged — isolation is enforced at the storage layer so that any caller that forgets to pass owner_id still gets filtered results, and new routes cannot accidentally leak data. Core infrastructure ------------------- - deerflow/runtime/user_context.py (new): - ContextVar[CurrentUser | None] with default None - runtime_checkable CurrentUser Protocol (structural subtype with .id) - set/reset/get/require helpers - AUTO sentinel + resolve_owner_id(value, method_name) for sentinel three-state resolution: AUTO reads contextvar, explicit str overrides, explicit None bypasses the filter (for migration/CLI) Repository changes ------------------ - ThreadMetaRepository: create/get/search/update_*/delete gain owner_id=AUTO kwarg; read paths filter by owner, writes stamp it, mutations check ownership before applying - RunRepository: put/get/list_by_thread/delete gain owner_id=AUTO kwarg - FeedbackRepository: create/get/list_by_run/list_by_thread/delete gain owner_id=AUTO kwarg - DbRunEventStore: list_messages/list_events/list_messages_by_run/ count_messages/delete_by_thread/delete_by_run gain owner_id=AUTO kwarg. Write paths (put/put_batch) read contextvar softly: when a request-scoped user is available, owner_id is stamped; background worker writes without a user context pass None which is valid (orphan row to be bound by migration) Schema ------ - persistence/models/run_event.py: RunEventRow.owner_id = Mapped[ str | None] = mapped_column(String(64), nullable=True, index=True) - No alembic migration needed: 2.0 ships fresh, Base.metadata.create_all picks up the new column automatically Middleware ---------- - auth_middleware.py: after cookie check, call get_optional_user_from_ request to load the real User, stamp it into request.state.user AND the contextvar via set_current_user, reset in a try/finally. Public paths and unauthenticated requests continue without contextvar, and @require_auth handles the strict 401 path Test infrastructure ------------------- - tests/conftest.py: @pytest.fixture(autouse=True) _auto_user_context sets a default SimpleNamespace(id="test-user-autouse") on every test unless marked @pytest.mark.no_auto_user. Keeps existing 20+ persistence tests passing without modification - pyproject.toml [tool.pytest.ini_options]: register no_auto_user marker so pytest does not emit warnings for opt-out tests - tests/test_user_context.py: 6 tests covering three-state semantics, Protocol duck typing, and require/optional APIs - tests/test_thread_meta_repo.py: one test updated to pass owner_id= None explicitly where it was previously relying on the old default Test results ------------ - test_user_context.py: 6 passed - test_auth*.py + test_langgraph_auth.py + test_ensure_admin.py: 127 - test_run_event_store / test_run_repository / test_thread_meta_repo / test_feedback: 92 passed - Full backend suite: 1905 passed, 2 failed (both @requires_llm flaky integration tests unrelated to auth), 1 skipped * feat(auth): extend orphan migration to 2.0-rc persistence tables _ensure_admin_user now runs a three-step pipeline on every boot: Step 1 (fatal): admin user exists / is created / password is reset Step 2 (non-fatal): LangGraph store orphan threads → admin Step 3 (non-fatal): SQL persistence tables → admin - threads_meta - runs - run_events - feedback Each step is idempotent. The fatal/non-fatal split mirrors PR #1728's original philosophy: admin creation failure blocks startup (the system is unusable without an admin), whereas migration failures log a warning and let the service proceed (a partial migration is recoverable; a missing admin is not). Key helpers ----------- - _iter_store_items(store, namespace, *, page_size=500): async generator that cursor-paginates across LangGraph store pages. Fixes PR #1728's hardcoded limit=1000 bug that would silently lose orphans beyond the first page. - _migrate_orphaned_threads(store, admin_user_id): Rewritten to use _iter_store_items. Returns the migrated count so the caller can log it; raises only on unhandled exceptions. - _migrate_orphan_sql_tables(admin_user_id): Imports the 4 ORM models lazily, grabs the shared session factory, runs one UPDATE per table in a single transaction, commits once. No-op when no persistence backend is configured (in-memory dev). Tests: test_ensure_admin.py (8 passed) * test(auth): port AUTH test plan docs + lint/format pass - Port backend/docs/AUTH_TEST_PLAN.md and AUTH_UPGRADE.md from PR #1728 - Rename metadata.user_id → metadata.owner_id in AUTH_TEST_PLAN.md (4 occurrences from the original PR doc) - ruff auto-fix UP037 in sentinel type annotations: drop quotes around "str | None | _AutoSentinel" now that from __future__ import annotations makes them implicit string forms - ruff format: 2 files (app/gateway/app.py, runtime/user_context.py) Note on test coverage additions: - conftest.py autouse fixture was already added in commit 4 (had to be co-located with the repository changes to keep pre-existing persistence tests passing) - cross-user isolation E2E tests (test_owner_isolation.py) deferred — enforcement is already proven by the 98-test repository suite via the autouse fixture + explicit _AUTO sentinel exercises - New test cases (TC-API-17..20, TC-ATK-13, TC-MIG-01..07) listed in AUTH_TEST_PLAN.md are deferred to a follow-up PR — they are manual-QA test cases rather than pytest code, and the spec-level coverage is already met by test_user_context.py + the 98-test repository suite. Final test results: - Auth suite (test_auth*, test_langgraph_auth, test_ensure_admin, test_user_context): 186 passed - Persistence suite (test_run_event_store, test_run_repository, test_thread_meta_repo, test_feedback): 98 passed - Lint: ruff check + ruff format both clean * test(auth): add cross-user isolation test suite 10 tests exercising the storage-layer owner filter by manually switching the user_context contextvar between two users. Verifies the safety invariant: After a repository write with owner_id=A, a subsequent read with owner_id=B must not return the row, and vice versa. Covers all 4 tables that own user-scoped data: TC-API-17 threads_meta — read, search, update, delete cross-user TC-API-18 runs — get, list_by_thread, delete cross-user TC-API-19 run_events — list_messages, list_events, count_messages, delete_by_thread (CRITICAL: raw conversation content leak vector) TC-API-20 feedback — get, list_by_run, delete cross-user Plus two meta-tests verifying the sentinel pattern itself: - AUTO + unset contextvar raises RuntimeError - explicit owner_id=None bypasses the filter (migration escape hatch) Architecture note ----------------- These tests bypass the HTTP layer by design. The full chain (cookie → middleware → contextvar → repository) is covered piecewise: - test_auth_middleware.py: middleware sets contextvar from cookies - test_owner_isolation.py: repositories enforce isolation when contextvar is set to different users Together they prove the end-to-end safety property without the ceremony of spinning up a full TestClient + in-memory DB for every router endpoint. Tests pass: 231 (full auth + persistence + isolation suite) Lint: clean * refactor(auth): migrate user repository to SQLAlchemy ORM Move the users table into the shared persistence engine so auth matches the pattern of threads_meta, runs, run_events, and feedback — one engine, one session factory, one schema init codepath. New files --------- - persistence/user/__init__.py, persistence/user/model.py: UserRow ORM class with partial unique index on (oauth_provider, oauth_id) - Registered in persistence/models/__init__.py so Base.metadata.create_all() picks it up Modified -------- - auth/repositories/sqlite.py: rewritten as async SQLAlchemy, identical constructor pattern to the other four repositories (def __init__(self, session_factory) + self._sf = session_factory) - auth/config.py: drop users_db_path field — storage is configured through config.database like every other table - deps.py/get_local_provider: construct SQLiteUserRepository with the shared session factory, fail fast if engine is not initialised - tests/test_auth.py: rewrite test_sqlite_round_trip_new_fields to use the shared engine (init_engine + close_engine in a tempdir) - tests/test_auth_type_system.py: add per-test autouse fixture that spins up a scratch engine and resets deps._cached_* singletons * refactor(auth): remove SQL orphan migration (unused in supported scenarios) The _migrate_orphan_sql_tables helper existed to bind NULL owner_id rows in threads_meta, runs, run_events, and feedback to the admin on first boot. But in every supported upgrade path, it's a no-op: 1. Fresh install: create_all builds fresh tables, no legacy rows 2. No-auth → with-auth (no existing persistence DB): persistence tables are created fresh by create_all, no legacy rows 3. No-auth → with-auth (has existing persistence DB from #1930): NOT a supported upgrade path — "有 DB 到有 DB" schema evolution is out of scope; users wipe DB or run manual ALTER So the SQL orphan migration never has anything to do in the supported matrix. Delete the function, simplify _ensure_admin_user from a 3-step pipeline to a 2-step one (admin creation + LangGraph store orphan migration only). LangGraph store orphan migration stays: it serves the real "no-auth → with-auth" upgrade path where a user's existing LangGraph thread metadata has no owner_id field and needs to be stamped with the newly-created admin's id. Tests: 284 passed (auth + persistence + isolation) Lint: clean * security(auth): write initial admin password to 0600 file instead of logs CodeQL py/clear-text-logging-sensitive-data flagged 3 call sites that logged the auto-generated admin password to stdout via logger.info(). Production log aggregators (ELK/Splunk/etc) would have captured those cleartext secrets. Replace with a shared helper that writes to .deer-flow/admin_initial_credentials.txt with mode 0600, and log only the path. New file -------- - app/gateway/auth/credential_file.py: write_initial_credentials() helper. Takes email, password, and a "initial"/"reset" label. Creates .deer-flow/ if missing, writes a header comment plus the email+password, chmods 0o600, returns the absolute Path. Modified -------- - app/gateway/app.py: both _ensure_admin_user paths (fresh creation + needs_setup password reset) now write to file and log the path - app/gateway/auth/reset_admin.py: rewritten to use the shared ORM repo (SQLiteUserRepository with session_factory) and the credential_file helper. The previous implementation was broken after the earlier ORM refactor — it still imported _get_users_conn and constructed SQLiteUserRepository() without a session factory. No tests changed — the three password-log sites are all exercised via existing test_ensure_admin.py which checks that startup succeeds, not that a specific string appears in logs. CodeQL alerts 272, 283, 284: all resolved. * security(auth): strict JWT validation in middleware (fix junk cookie bypass) AUTH_TEST_PLAN test 7.5.8 expects junk cookies to be rejected with 401. The previous middleware behaviour was "presence-only": check that some access_token cookie exists, then pass through. In combination with my Task-12 decision to skip @require_auth decorators on routes, this created a gap where a request with any cookie-shaped string (e.g. access_token=not-a-jwt) would bypass authentication on routes that do not touch the repository (/api/models, /api/mcp/config, /api/memory, /api/skills, …). Fix: middleware now calls get_current_user_from_request() strictly and catches the resulting HTTPException to render a 401 with the proper fine-grained error code (token_invalid, token_expired, user_not_found, …). On success it stamps request.state.user and the contextvar so repository-layer owner filters work downstream. The 4 old "_with_cookie_passes" tests in test_auth_middleware.py were written for the presence-only behaviour; they asserted that a junk cookie would make the handler return 200. They are renamed to "_with_junk_cookie_rejected" and their assertions flipped to 401. The negative path (no cookie → 401 not_authenticated) is unchanged. Verified: no cookie → 401 not_authenticated junk cookie → 401 token_invalid (the fixed bug) expired cookie → 401 token_expired Tests: 284 passed (auth + persistence + isolation) Lint: clean * security(auth): wire @require_permission(owner_check=True) on isolation routes Apply the require_permission decorator to all 28 routes that take a {thread_id} path parameter. Combined with the strict middleware (previous commit), this gives the double-layer protection that AUTH_TEST_PLAN test 7.5.9 documents: Layer 1 (AuthMiddleware): cookie + JWT validation, rejects junk cookies and stamps request.state.user Layer 2 (@require_permission with owner_check=True): per-resource ownership verification via ThreadMetaStore.check_access — returns 404 if a different user owns the thread The decorator's owner_check branch is rewritten to use the SQL thread_meta_repo (the 2.0-rc persistence layer) instead of the LangGraph store path that PR #1728 used (_store_get / get_store in routers/threads.py). The inject_record convenience is dropped — no caller in 2.0 needs the LangGraph blob, and the SQL repo has a different shape. Routes decorated (28 total): - threads.py: delete, patch, get, get-state, post-state, post-history - thread_runs.py: post-runs, post-runs-stream, post-runs-wait, list_runs, get_run, cancel_run, join_run, stream_existing_run, list_thread_messages, list_run_messages, list_run_events, thread_token_usage - feedback.py: create, list, stats, delete - uploads.py: upload (added Request param), list, delete - artifacts.py: get_artifact - suggestions.py: generate (renamed body parameter to avoid conflict with FastAPI Request) Test fixes: - test_suggestions_router.py: bypass the decorator via __wrapped__ (the unit tests cover parsing logic, not auth — no point spinning up a thread_meta_repo just to test JSON unwrapping) - test_auth_middleware.py 4 fake-cookie tests: already updated in the previous commit (745bf432) Tests: 293 passed (auth + persistence + isolation + suggestions) Lint: clean * security(auth): defense-in-depth fixes from release validation pass Eight findings caught while running the AUTH_TEST_PLAN end-to-end against the deployed sg_dev stack. Each is a pre-condition for shipping release/2.0-rc that the previous PRs missed. Backend hardening - routers/auth.py: rate limiter X-Real-IP now requires AUTH_TRUSTED_PROXIES whitelist (CIDR/IP allowlist). Without nginx in front, the previous code honored arbitrary X-Real-IP, letting an attacker rotate the header to fully bypass the per-IP login lockout. - routers/auth.py: 36-entry common-password blocklist via Pydantic field_validator on RegisterRequest + ChangePasswordRequest. The shared _validate_strong_password helper keeps the constraint in one place. - routers/threads.py: ThreadCreateRequest + ThreadPatchRequest strip server-reserved metadata keys (owner_id, user_id) via Pydantic field_validator so a forged value can never round-trip back to other clients reading the same thread. The actual ownership invariant stays on the threads_meta row; this closes the metadata-blob echo gap. - authz.py + thread_meta/sql.py: require_permission gains a require_existing flag plumbed through check_access(require_existing=True). Destructive routes (DELETE/PATCH/state-update/runs/feedback) now treat a missing thread_meta row as 404 instead of "untracked legacy thread, allow", closing the cross-user delete-idempotence gap where any user could successfully DELETE another user's deleted thread. - repositories/sqlite.py + base.py: update_user raises UserNotFoundError on a vanished row instead of silently returning the input. Concurrent delete during password reset can no longer look like a successful update. - runtime/user_context.py: resolve_owner_id() coerces User.id (UUID) to str at the contextvar boundary so SQLAlchemy String(64) columns can bind it. The whole 2.0-rc isolation pipeline was previously broken end-to-end (POST /api/threads → 500 "type 'UUID' is not supported"). - persistence/engine.py: SQLAlchemy listener enables PRAGMA journal_mode=WAL, synchronous=NORMAL, foreign_keys=ON on every new SQLite connection. TC-UPG-06 in the test plan expects WAL; previous code shipped with the default 'delete' journal. - auth_middleware.py: stamp request.state.auth = AuthContext(...) so @require_permission's short-circuit fires; previously every isolation request did a duplicate JWT decode + users SELECT. Also unifies the 401 payload through AuthErrorResponse(...).model_dump(). - app.py: _ensure_admin_user restructure removes the noqa F821 scoping bug where 'password' was referenced outside the branch that defined it. New _announce_credentials helper absorbs the duplicate log block in the fresh-admin and reset-admin branches. * fix(frontend+nginx): rollout CSRF on every state-changing client path The frontend was 100% broken in gateway-pro mode for any user trying to open a specific chat thread. Three cumulative bugs each silently masked the next. LangGraph SDK CSRF gap (api-client.ts) - The Client constructor took only apiUrl, no defaultHeaders, no fetch interceptor. The SDK's internal fetch never sent X-CSRF-Token, so every state-changing /api/langgraph-compat/* call (runs/stream, threads/search, threads/{tid}/history, ...) hit CSRFMiddleware and got 403 before reaching the auth check. UI symptom: empty thread page with no error message; the SPA's hooks swallowed the rejection. - Fix: pass an onRequest hook that injects X-CSRF-Token from the csrf_token cookie per request. Reading the cookie per call (not at construction time) handles login / logout / password-change cookie rotation transparently. The SDK's prepareFetchOptions calls onRequest for both regular requests AND streaming/SSE/reconnect, so the same hook covers runs.stream and runs.joinStream. Raw fetch CSRF gap (7 files) - Audit: 11 frontend fetch sites, only 2 included CSRF (login/setup + account-settings change-password). The other 7 routed through raw fetch() with no header — suggestions, memory, agents, mcp, skills, uploads, and the local thread cleanup hook all 403'd silently. - Fix: enhance fetcher.ts:fetchWithAuth to auto-inject X-CSRF-Token on POST/PUT/DELETE/PATCH from a single shared readCsrfCookie() helper. Convert all 7 raw fetch() callers to fetchWithAuth so the contract is centrally enforced. api-client.ts and fetcher.ts share readCsrfCookie + STATE_CHANGING_METHODS to avoid drift. nginx routing + buffering (nginx.local.conf) - The auth feature shipped without updating the nginx config: per-API explicit location blocks but no /api/v1/auth/, /api/feedback, /api/runs. The frontend's client-side fetches to /api/v1/auth/login/local 404'd from the Next.js side because nginx routed /api/* to the frontend. - Fix: add catch-all `location /api/` that proxies to the gateway. nginx longest-prefix matching keeps the explicit blocks (/api/models, /api/threads regex, /api/langgraph/, ...) winning for their paths. - Fix: disable proxy_buffering + proxy_request_buffering for the frontend `location /` block. Without it, nginx tries to spool large Next.js chunks into /var/lib/nginx/proxy (root-owned) and fails with Permission denied → ERR_INCOMPLETE_CHUNKED_ENCODING → ChunkLoadError. * test(auth): release-validation test infra and new coverage Test fixtures and unit tests added during the validation pass. Router test helpers (NEW: tests/_router_auth_helpers.py) - make_authed_test_app(): builds a FastAPI test app with a stub middleware that stamps request.state.user + request.state.auth and a permissive thread_meta_repo mock. TestClient-based router tests (test_artifacts_router, test_threads_router) use it instead of bare FastAPI() so the new @require_permission(owner_check=True) decorators short-circuit cleanly. - call_unwrapped(): walks the __wrapped__ chain to invoke the underlying handler without going through the authz wrappers. Direct-call tests (test_uploads_router) use it. Typed with ParamSpec so the wrapped signature flows through. Backend test additions - test_auth.py: 7 tests for the new _get_client_ip trust model (no proxy / trusted proxy / untrusted peer / XFF rejection / invalid CIDR / no client). 5 tests for the password blocklist (literal, case-insensitive, strong password accepted, change-password binding, short-password length-check still fires before blocklist). test_update_user_raises_when_row_concurrently_deleted: closes a shipped-without-coverage gap on the new UserNotFoundError contract. - test_thread_meta_repo.py: 4 tests for check_access(require_existing=True) — strict missing-row denial, strict owner match, strict owner mismatch, strict null-owner still allowed (shared rows survive the tightening). - test_ensure_admin.py: 3 tests for _migrate_orphaned_threads / _iter_store_items pagination, covering the TC-UPG-02 upgrade story end-to-end via mock store. Closes the gap where the cursor pagination was untested even though the previous PR rewrote it. - test_threads_router.py: 5 tests for _strip_reserved_metadata (owner_id removal, user_id removal, safe-keys passthrough, empty input, both-stripped). - test_auth_type_system.py: replace "password123" fixtures with Tr0ub4dor3a / AnotherStr0ngPwd! so the new password blocklist doesn't reject the test data. * docs(auth): refresh TC-DOCKER-05 + document Docker validation gap - AUTH_TEST_PLAN.md TC-DOCKER-05: the previous expectation ("admin password visible in docker logs") was stale after the simplify pass that moved credentials to a 0600 file. The grep "Password:" check would have silently failed and given a false sense of coverage. New expectation matches the actual file-based path: 0600 file in DEER_FLOW_HOME, log shows the path (not the secret), reverse-grep asserts no leaked password in container logs. - NEW: docs/AUTH_TEST_DOCKER_GAP.md documents the only un-executed block in the test plan (TC-DOCKER-01..06). Reason: sg_dev validation host has no Docker daemon installed. The doc maps each Docker case to an already-validated bare-metal equivalent (TC-1.1, TC-REENT-01, TC-API-02 etc.) so the gap is auditable, and includes pre-flight reproduction steps for whoever has Docker available. --------- Co-authored-by: greatmengqi <chenmengqi.0376@bytedance.com>
2026-05-21 15:36:48 +00:00 · 2026-04-09 11:29:32 +08:00
parent d8ecaf46c9
commit 94eee95fe0
92 changed files with 9154 additions and 441 deletions
@@ -0,0 +1,134 @@
+"""Helpers for router-level tests that need a stubbed auth context.
+
+The production gateway runs ``AuthMiddleware`` (validates the JWT cookie)
+ahead of every router, plus ``@require_permission(owner_check=True)``
+decorators that read ``request.state.auth`` and call
+``thread_meta_repo.check_access``. Router-level unit tests construct
+**bare** FastAPI apps that include only one router — they have neither
+the auth middleware nor a real thread_meta_repo, so the decorators raise
+401 (TestClient path) or ValueError (direct-call path).
+
+This module provides two surfaces:
+
+1. :func:`make_authed_test_app` — wraps ``FastAPI()`` with a tiny
+   ``BaseHTTPMiddleware`` that stamps a fake user / AuthContext on every
+   request, plus a permissive ``thread_meta_repo`` mock on
+   ``app.state``. Use from TestClient-based router tests.
+
+2. :func:`call_unwrapped` — invokes the underlying function bypassing
+   the ``@require_permission`` decorator chain by walking ``__wrapped__``.
+   Use from direct-call tests that previously imported the route
+   function and called it positionally.
+
+Both helpers are deliberately permissive: they never deny a request.
+Tests that want to verify the *auth boundary itself* (e.g.
+``test_auth_middleware``, ``test_auth_type_system``) build their own
+apps with the real middleware — those should not use this module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+from fastapi import FastAPI, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+from app.gateway.auth.models import User
+from app.gateway.authz import AuthContext, Permissions
+
+# Default permission set granted to the stub user. Mirrors `_ALL_PERMISSIONS`
+# in authz.py — kept inline so the tests don't import a private symbol.
+_STUB_PERMISSIONS: list[str] = [
+    Permissions.THREADS_READ,
+    Permissions.THREADS_WRITE,
+    Permissions.THREADS_DELETE,
+    Permissions.RUNS_CREATE,
+    Permissions.RUNS_READ,
+    Permissions.RUNS_CANCEL,
+]
+
+
+def _make_stub_user() -> User:
+    """A deterministic test user — same shape as production, fresh UUID."""
+    return User(
+        email="router-test@example.com",
+        password_hash="x",
+        system_role="user",
+        id=uuid4(),
+    )
+
+
+class _StubAuthMiddleware(BaseHTTPMiddleware):
+    """Stamp a fake user / AuthContext onto every request.
+
+    Mirrors what production ``AuthMiddleware`` does after the JWT decode
+    + DB lookup short-circuit, so ``@require_permission`` finds an
+    authenticated context and skips its own re-authentication path.
+    """
+
+    def __init__(self, app: ASGIApp, user_factory: Callable[[], User]) -> None:
+        super().__init__(app)
+        self._user_factory = user_factory
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        user = self._user_factory()
+        request.state.user = user
+        request.state.auth = AuthContext(user=user, permissions=list(_STUB_PERMISSIONS))
+        return await call_next(request)
+
+
+def make_authed_test_app(
+    *,
+    user_factory: Callable[[], User] | None = None,
+    owner_check_passes: bool = True,
+) -> FastAPI:
+    """Build a FastAPI test app with stub auth + permissive thread_meta_repo.
+
+    Args:
+        user_factory: Override the default test user. Must return a fully
+            populated :class:`User`. Useful for cross-user isolation tests
+            that need a stable id across requests.
+        owner_check_passes: When True (default), ``thread_meta_repo.check_access``
+            returns True for every call so ``@require_permission(owner_check=True)``
+            never blocks the route under test. Pass False to verify that
+            permission failures surface correctly.
+
+    Returns:
+        A ``FastAPI`` app with the stub middleware installed and
+        ``app.state.thread_meta_repo`` set to a permissive mock. The
+        caller is still responsible for ``app.include_router(...)``.
+    """
+    factory = user_factory or _make_stub_user
+    app = FastAPI()
+    app.add_middleware(_StubAuthMiddleware, user_factory=factory)
+
+    repo = MagicMock()
+    repo.check_access = AsyncMock(return_value=owner_check_passes)
+    app.state.thread_meta_repo = repo
+
+    return app
+
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def call_unwrapped(decorated: Callable[_P, _R], /, *args: _P.args, **kwargs: _P.kwargs) -> _R:
+    """Invoke the underlying function of a ``@require_permission``-decorated route.
+
+    ``functools.wraps`` sets ``__wrapped__`` on each layer; we walk all
+    the way down to the original handler, bypassing every authz +
+    require_auth wrapper. Use from tests that need to call route
+    functions directly (without TestClient) and don't want to construct
+    a fake ``Request`` just to satisfy the decorator. The ``ParamSpec``
+    propagates the wrapped route's signature so call sites still get
+    parameter checking despite the unwrapping.
+    """
+    fn: Callable = decorated
+    while hasattr(fn, "__wrapped__"):
+        fn = fn.__wrapped__  # type: ignore[attr-defined]
+    return fn(*args, **kwargs)
@@ -7,6 +7,7 @@ issues when unit-testing lightweight config/registry code in isolation.
 import importlib.util
 import sys
 from pathlib import Path
+from types import SimpleNamespace
 from unittest.mock import MagicMock

 import pytest
@@ -53,3 +54,44 @@ def provisioner_module():
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module
+
+
+# ---------------------------------------------------------------------------
+# Auto-set user context for every test unless marked no_auto_user
+# ---------------------------------------------------------------------------
+#
+# Repository methods read ``owner_id`` from a contextvar by default
+# (see ``deerflow.runtime.user_context``). Without this fixture, every
+# pre-existing persistence test would raise RuntimeError because the
+# contextvar is unset. The fixture sets a default test user on every
+# test; tests that explicitly want to verify behaviour *without* a user
+# context should mark themselves ``@pytest.mark.no_auto_user``.
+
+
+@pytest.fixture(autouse=True)
+def _auto_user_context(request):
+    """Inject a default ``test-user-autouse`` into the contextvar.
+
+    Opt-out via ``@pytest.mark.no_auto_user``. Uses lazy import so that
+    tests which don't touch the persistence layer never pay the cost
+    of importing runtime.user_context.
+    """
+    if request.node.get_closest_marker("no_auto_user"):
+        yield
+        return
+
+    try:
+        from deerflow.runtime.user_context import (
+            reset_current_user,
+            set_current_user,
+        )
+    except ImportError:
+        yield
+        return
+
+    user = SimpleNamespace(id="test-user-autouse", email="test@local")
+    token = set_current_user(user)
+    try:
+        yield
+    finally:
+        reset_current_user(token)
@@ -3,7 +3,7 @@ import zipfile
 from pathlib import Path

 import pytest
-from fastapi import FastAPI
+from _router_auth_helpers import call_unwrapped, make_authed_test_app
 from fastapi.testclient import TestClient
 from starlette.requests import Request
 from starlette.responses import FileResponse
@@ -36,7 +36,7 @@ def test_get_artifact_reads_utf8_text_file_on_windows_locale(tmp_path, monkeypat
    monkeypatch.setattr(artifacts_router, "resolve_thread_virtual_path", lambda _thread_id, _path: artifact_path)

    request = _make_request()
-    response = asyncio.run(artifacts_router.get_artifact("thread-1", "mnt/user-data/outputs/note.txt", request))
+    response = asyncio.run(call_unwrapped(artifacts_router.get_artifact, "thread-1", "mnt/user-data/outputs/note.txt", request))

    assert bytes(response.body).decode("utf-8") == text
    assert response.media_type == "text/plain"
@@ -49,7 +49,7 @@ def test_get_artifact_forces_download_for_active_content(tmp_path, monkeypatch,

    monkeypatch.setattr(artifacts_router, "resolve_thread_virtual_path", lambda _thread_id, _path: artifact_path)

-    response = asyncio.run(artifacts_router.get_artifact("thread-1", f"mnt/user-data/outputs/{filename}", _make_request()))
+    response = asyncio.run(call_unwrapped(artifacts_router.get_artifact, "thread-1", f"mnt/user-data/outputs/{filename}", _make_request()))

    assert isinstance(response, FileResponse)
    assert response.headers.get("content-disposition", "").startswith("attachment;")
@@ -63,7 +63,7 @@ def test_get_artifact_forces_download_for_active_content_in_skill_archive(tmp_pa

    monkeypatch.setattr(artifacts_router, "resolve_thread_virtual_path", lambda _thread_id, _path: skill_path)

-    response = asyncio.run(artifacts_router.get_artifact("thread-1", f"mnt/user-data/outputs/sample.skill/{filename}", _make_request()))
+    response = asyncio.run(call_unwrapped(artifacts_router.get_artifact, "thread-1", f"mnt/user-data/outputs/sample.skill/{filename}", _make_request()))

    assert response.headers.get("content-disposition", "").startswith("attachment;")
    assert bytes(response.body) == content.encode("utf-8")
@@ -75,7 +75,7 @@ def test_get_artifact_download_false_does_not_force_attachment(tmp_path, monkeyp

    monkeypatch.setattr(artifacts_router, "resolve_thread_virtual_path", lambda _thread_id, _path: artifact_path)

-    app = FastAPI()
+    app = make_authed_test_app()
    app.include_router(artifacts_router.router)

    with TestClient(app) as client:
@@ -93,7 +93,7 @@ def test_get_artifact_download_true_forces_attachment_for_skill_archive(tmp_path

    monkeypatch.setattr(artifacts_router, "resolve_thread_virtual_path", lambda _thread_id, _path: skill_path)

-    app = FastAPI()
+    app = make_authed_test_app()
    app.include_router(artifacts_router.router)

    with TestClient(app) as client:
@@ -0,0 +1,654 @@
+"""Tests for authentication module: JWT, password hashing, AuthContext, and authz decorators."""
+
+from datetime import timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+
+from app.gateway.auth import create_access_token, decode_token, hash_password, verify_password
+from app.gateway.auth.models import User
+from app.gateway.authz import (
+    AuthContext,
+    Permissions,
+    get_auth_context,
+    require_auth,
+    require_permission,
+)
+
+# ── Password Hashing ────────────────────────────────────────────────────────
+
+
+def test_hash_password_and_verify():
+    """Hashing and verification round-trip."""
+    password = "s3cr3tP@ssw0rd!"
+    hashed = hash_password(password)
+    assert hashed != password
+    assert verify_password(password, hashed) is True
+    assert verify_password("wrongpassword", hashed) is False
+
+
+def test_hash_password_different_each_time():
+    """bcrypt generates unique salts, so same password has different hashes."""
+    password = "testpassword"
+    h1 = hash_password(password)
+    h2 = hash_password(password)
+    assert h1 != h2  # Different salts
+    # But both verify correctly
+    assert verify_password(password, h1) is True
+    assert verify_password(password, h2) is True
+
+
+def test_verify_password_rejects_empty():
+    """Empty password should not verify."""
+    hashed = hash_password("nonempty")
+    assert verify_password("", hashed) is False
+
+
+# ── JWT ─────────────────────────────────────────────────────────────────────
+
+
+def test_create_and_decode_token():
+    """JWT creation and decoding round-trip."""
+    user_id = str(uuid4())
+    # Set a valid JWT secret for this test
+    import os
+
+    os.environ["AUTH_JWT_SECRET"] = "test-secret-key-for-jwt-testing-minimum-32-chars"
+    token = create_access_token(user_id)
+    assert isinstance(token, str)
+
+    payload = decode_token(token)
+    assert payload is not None
+    assert payload.sub == user_id
+
+
+def test_decode_token_expired():
+    """Expired token returns TokenError.EXPIRED."""
+    from app.gateway.auth.errors import TokenError
+
+    user_id = str(uuid4())
+    # Create token that expires immediately
+    token = create_access_token(user_id, expires_delta=timedelta(seconds=-1))
+    payload = decode_token(token)
+    assert payload == TokenError.EXPIRED
+
+
+def test_decode_token_invalid():
+    """Invalid token returns TokenError."""
+    from app.gateway.auth.errors import TokenError
+
+    assert isinstance(decode_token("not.a.valid.token"), TokenError)
+    assert isinstance(decode_token(""), TokenError)
+    assert isinstance(decode_token("completely-wrong"), TokenError)
+
+
+def test_create_token_custom_expiry():
+    """Custom expiry is respected."""
+    user_id = str(uuid4())
+    token = create_access_token(user_id, expires_delta=timedelta(hours=1))
+    payload = decode_token(token)
+    assert payload is not None
+    assert payload.sub == user_id
+
+
+# ── AuthContext ────────────────────────────────────────────────────────────
+
+
+def test_auth_context_unauthenticated():
+    """AuthContext with no user."""
+    ctx = AuthContext(user=None, permissions=[])
+    assert ctx.is_authenticated is False
+    assert ctx.has_permission("threads", "read") is False
+
+
+def test_auth_context_authenticated_no_perms():
+    """AuthContext with user but no permissions."""
+    user = User(id=uuid4(), email="test@example.com", password_hash="hash")
+    ctx = AuthContext(user=user, permissions=[])
+    assert ctx.is_authenticated is True
+    assert ctx.has_permission("threads", "read") is False
+
+
+def test_auth_context_has_permission():
+    """AuthContext permission checking."""
+    user = User(id=uuid4(), email="test@example.com", password_hash="hash")
+    perms = [Permissions.THREADS_READ, Permissions.THREADS_WRITE]
+    ctx = AuthContext(user=user, permissions=perms)
+    assert ctx.has_permission("threads", "read") is True
+    assert ctx.has_permission("threads", "write") is True
+    assert ctx.has_permission("threads", "delete") is False
+    assert ctx.has_permission("runs", "read") is False
+
+
+def test_auth_context_require_user_raises():
+    """require_user raises 401 when not authenticated."""
+    ctx = AuthContext(user=None, permissions=[])
+    with pytest.raises(HTTPException) as exc_info:
+        ctx.require_user()
+    assert exc_info.value.status_code == 401
+
+
+def test_auth_context_require_user_returns_user():
+    """require_user returns user when authenticated."""
+    user = User(id=uuid4(), email="test@example.com", password_hash="hash")
+    ctx = AuthContext(user=user, permissions=[])
+    returned = ctx.require_user()
+    assert returned == user
+
+
+# ── get_auth_context helper ─────────────────────────────────────────────────
+
+
+def test_get_auth_context_not_set():
+    """get_auth_context returns None when auth not set on request."""
+    mock_request = MagicMock()
+    # Make getattr return None (simulating attribute not set)
+    mock_request.state = MagicMock()
+    del mock_request.state.auth
+    assert get_auth_context(mock_request) is None
+
+
+def test_get_auth_context_set():
+    """get_auth_context returns the AuthContext from request."""
+    user = User(id=uuid4(), email="test@example.com", password_hash="hash")
+    ctx = AuthContext(user=user, permissions=[Permissions.THREADS_READ])
+
+    mock_request = MagicMock()
+    mock_request.state.auth = ctx
+
+    assert get_auth_context(mock_request) == ctx
+
+
+# ── require_auth decorator ──────────────────────────────────────────────────
+
+
+def test_require_auth_sets_auth_context():
+    """require_auth sets auth context on request from cookie."""
+    from fastapi import Request
+
+    app = FastAPI()
+
+    @app.get("/test")
+    @require_auth
+    async def endpoint(request: Request):
+        ctx = get_auth_context(request)
+        return {"authenticated": ctx.is_authenticated}
+
+    with TestClient(app) as client:
+        # No cookie → anonymous
+        response = client.get("/test")
+        assert response.status_code == 200
+        assert response.json()["authenticated"] is False
+
+
+def test_require_auth_requires_request_param():
+    """require_auth raises ValueError if request parameter is missing."""
+    import asyncio
+
+    @require_auth
+    async def bad_endpoint():  # Missing `request` parameter
+        pass
+
+    with pytest.raises(ValueError, match="require_auth decorator requires 'request' parameter"):
+        asyncio.run(bad_endpoint())
+
+
+# ── require_permission decorator ─────────────────────────────────────────────
+
+
+def test_require_permission_requires_auth():
+    """require_permission raises 401 when not authenticated."""
+    from fastapi import Request
+
+    app = FastAPI()
+
+    @app.get("/test")
+    @require_permission("threads", "read")
+    async def endpoint(request: Request):
+        return {"ok": True}
+
+    with TestClient(app) as client:
+        response = client.get("/test")
+        assert response.status_code == 401
+        assert "Authentication required" in response.json()["detail"]
+
+
+def test_require_permission_denies_wrong_permission():
+    """User without required permission gets 403."""
+    from fastapi import Request
+
+    app = FastAPI()
+    user = User(id=uuid4(), email="test@example.com", password_hash="hash")
+
+    @app.get("/test")
+    @require_permission("threads", "delete")
+    async def endpoint(request: Request):
+        return {"ok": True}
+
+    mock_auth = AuthContext(user=user, permissions=[Permissions.THREADS_READ])
+
+    with patch("app.gateway.authz._authenticate", return_value=mock_auth):
+        with TestClient(app) as client:
+            response = client.get("/test")
+            assert response.status_code == 403
+            assert "Permission denied" in response.json()["detail"]
+
+
+# ── Weak JWT secret warning ──────────────────────────────────────────────────
+
+
+# ── User Model Fields ──────────────────────────────────────────────────────
+
+
+def test_user_model_has_needs_setup_default_false():
+    """New users default to needs_setup=False."""
+    user = User(email="test@example.com", password_hash="hash")
+    assert user.needs_setup is False
+
+
+def test_user_model_has_token_version_default_zero():
+    """New users default to token_version=0."""
+    user = User(email="test@example.com", password_hash="hash")
+    assert user.token_version == 0
+
+
+def test_user_model_needs_setup_true():
+    """Auto-created admin has needs_setup=True."""
+    user = User(email="admin@example.com", password_hash="hash", needs_setup=True)
+    assert user.needs_setup is True
+
+
+def test_sqlite_round_trip_new_fields():
+    """needs_setup and token_version survive create → read round-trip.
+
+    Uses the shared persistence engine (same one threads_meta, runs,
+    run_events, and feedback use). The old separate .deer-flow/users.db
+    file is gone.
+    """
+    import asyncio
+    import tempfile
+
+    from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
+
+    async def _run() -> None:
+        from deerflow.persistence.engine import (
+            close_engine,
+            get_session_factory,
+            init_engine,
+        )
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            url = f"sqlite+aiosqlite:///{tmpdir}/scratch.db"
+            await init_engine("sqlite", url=url, sqlite_dir=tmpdir)
+            try:
+                repo = SQLiteUserRepository(get_session_factory())
+                user = User(
+                    email="setup@test.com",
+                    password_hash="fakehash",
+                    system_role="admin",
+                    needs_setup=True,
+                    token_version=3,
+                )
+                created = await repo.create_user(user)
+                assert created.needs_setup is True
+                assert created.token_version == 3
+
+                fetched = await repo.get_user_by_email("setup@test.com")
+                assert fetched is not None
+                assert fetched.needs_setup is True
+                assert fetched.token_version == 3
+
+                fetched.needs_setup = False
+                fetched.token_version = 4
+                await repo.update_user(fetched)
+                refetched = await repo.get_user_by_id(str(fetched.id))
+                assert refetched is not None
+                assert refetched.needs_setup is False
+                assert refetched.token_version == 4
+            finally:
+                await close_engine()
+
+    asyncio.run(_run())
+
+
+def test_update_user_raises_when_row_concurrently_deleted(tmp_path):
+    """Concurrent-delete during update_user must hard-fail, not silently no-op.
+
+    Earlier the SQLite repo returned the input unchanged when the row was
+    missing, making a phantom success path that admin password reset
+    callers (`reset_admin`, `_ensure_admin_user`) would happily log as
+    'password reset'. The new contract: raise ``UserNotFoundError`` so
+    a vanished row never looks like a successful update.
+    """
+    import asyncio
+    import tempfile
+
+    from app.gateway.auth.repositories.base import UserNotFoundError
+    from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
+
+    async def _run() -> None:
+        from deerflow.persistence.engine import (
+            close_engine,
+            get_session_factory,
+            init_engine,
+        )
+        from deerflow.persistence.user.model import UserRow
+
+        with tempfile.TemporaryDirectory() as d:
+            url = f"sqlite+aiosqlite:///{d}/scratch.db"
+            await init_engine("sqlite", url=url, sqlite_dir=d)
+            try:
+                sf = get_session_factory()
+                repo = SQLiteUserRepository(sf)
+                user = User(
+                    email="ghost@test.com",
+                    password_hash="fakehash",
+                    system_role="user",
+                )
+                created = await repo.create_user(user)
+
+                # Simulate "row vanished underneath us" by deleting the row
+                # via the raw ORM session, then attempt to update.
+                async with sf() as session:
+                    row = await session.get(UserRow, str(created.id))
+                    assert row is not None
+                    await session.delete(row)
+                    await session.commit()
+
+                created.needs_setup = True
+                with pytest.raises(UserNotFoundError):
+                    await repo.update_user(created)
+            finally:
+                await close_engine()
+
+    asyncio.run(_run())
+
+
+# ── Token Versioning ───────────────────────────────────────────────────────
+
+
+def test_jwt_encodes_ver():
+    """JWT payload includes ver field."""
+    import os
+
+    from app.gateway.auth.errors import TokenError
+
+    os.environ["AUTH_JWT_SECRET"] = "test-secret-key-for-jwt-testing-minimum-32-chars"
+    token = create_access_token(str(uuid4()), token_version=3)
+    payload = decode_token(token)
+    assert not isinstance(payload, TokenError)
+    assert payload.ver == 3
+
+
+def test_jwt_default_ver_zero():
+    """JWT ver defaults to 0."""
+    import os
+
+    from app.gateway.auth.errors import TokenError
+
+    os.environ["AUTH_JWT_SECRET"] = "test-secret-key-for-jwt-testing-minimum-32-chars"
+    token = create_access_token(str(uuid4()))
+    payload = decode_token(token)
+    assert not isinstance(payload, TokenError)
+    assert payload.ver == 0
+
+
+def test_token_version_mismatch_rejects():
+    """Token with stale ver is rejected by get_current_user_from_request."""
+    import asyncio
+    import os
+
+    os.environ["AUTH_JWT_SECRET"] = "test-secret-key-for-jwt-testing-minimum-32-chars"
+
+    user_id = str(uuid4())
+    token = create_access_token(user_id, token_version=0)
+
+    mock_user = User(id=user_id, email="test@example.com", password_hash="hash", token_version=1)
+
+    mock_request = MagicMock()
+    mock_request.cookies = {"access_token": token}
+
+    with patch("app.gateway.deps.get_local_provider") as mock_provider_fn:
+        mock_provider = MagicMock()
+        mock_provider.get_user = AsyncMock(return_value=mock_user)
+        mock_provider_fn.return_value = mock_provider
+
+        from app.gateway.deps import get_current_user_from_request
+
+        with pytest.raises(HTTPException) as exc_info:
+            asyncio.run(get_current_user_from_request(mock_request))
+        assert exc_info.value.status_code == 401
+        assert "revoked" in str(exc_info.value.detail).lower()
+
+
+# ── change-password extension ──────────────────────────────────────────────
+
+
+def test_change_password_request_accepts_new_email():
+    """ChangePasswordRequest model accepts optional new_email."""
+    from app.gateway.routers.auth import ChangePasswordRequest
+
+    req = ChangePasswordRequest(
+        current_password="old",
+        new_password="newpassword",
+        new_email="new@example.com",
+    )
+    assert req.new_email == "new@example.com"
+
+
+def test_change_password_request_new_email_optional():
+    """ChangePasswordRequest model works without new_email."""
+    from app.gateway.routers.auth import ChangePasswordRequest
+
+    req = ChangePasswordRequest(current_password="old", new_password="newpassword")
+    assert req.new_email is None
+
+
+def test_login_response_includes_needs_setup():
+    """LoginResponse includes needs_setup field."""
+    from app.gateway.routers.auth import LoginResponse
+
+    resp = LoginResponse(expires_in=3600, needs_setup=True)
+    assert resp.needs_setup is True
+    resp2 = LoginResponse(expires_in=3600)
+    assert resp2.needs_setup is False
+
+
+# ── Rate Limiting ──────────────────────────────────────────────────────────
+
+
+def test_rate_limiter_allows_under_limit():
+    """Requests under the limit are allowed."""
+    from app.gateway.routers.auth import _check_rate_limit, _login_attempts
+
+    _login_attempts.clear()
+    _check_rate_limit("192.168.1.1")  # Should not raise
+
+
+def test_rate_limiter_blocks_after_max_failures():
+    """IP is blocked after 5 consecutive failures."""
+    from app.gateway.routers.auth import _check_rate_limit, _login_attempts, _record_login_failure
+
+    _login_attempts.clear()
+    ip = "10.0.0.1"
+    for _ in range(5):
+        _record_login_failure(ip)
+    with pytest.raises(HTTPException) as exc_info:
+        _check_rate_limit(ip)
+    assert exc_info.value.status_code == 429
+
+
+def test_rate_limiter_resets_on_success():
+    """Successful login clears the failure counter."""
+    from app.gateway.routers.auth import _check_rate_limit, _login_attempts, _record_login_failure, _record_login_success
+
+    _login_attempts.clear()
+    ip = "10.0.0.2"
+    for _ in range(4):
+        _record_login_failure(ip)
+    _record_login_success(ip)
+    _check_rate_limit(ip)  # Should not raise
+
+
+# ── Client IP extraction ─────────────────────────────────────────────────
+
+
+def test_get_client_ip_direct_connection_no_proxy(monkeypatch):
+    """Direct mode (no AUTH_TRUSTED_PROXIES): use TCP peer regardless of X-Real-IP."""
+    monkeypatch.delenv("AUTH_TRUSTED_PROXIES", raising=False)
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client.host = "203.0.113.42"
+    req.headers = {}
+    assert _get_client_ip(req) == "203.0.113.42"
+
+
+def test_get_client_ip_x_real_ip_ignored_when_no_trusted_proxy(monkeypatch):
+    """X-Real-IP is silently ignored if AUTH_TRUSTED_PROXIES is unset.
+
+    This closes the bypass where any client could rotate X-Real-IP per
+    request to dodge per-IP rate limits in dev / direct mode.
+    """
+    monkeypatch.delenv("AUTH_TRUSTED_PROXIES", raising=False)
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client.host = "127.0.0.1"
+    req.headers = {"x-real-ip": "203.0.113.42"}
+    assert _get_client_ip(req) == "127.0.0.1"
+
+
+def test_get_client_ip_x_real_ip_honored_from_trusted_proxy(monkeypatch):
+    """X-Real-IP is honored when the TCP peer matches AUTH_TRUSTED_PROXIES."""
+    monkeypatch.setenv("AUTH_TRUSTED_PROXIES", "10.0.0.0/8")
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client.host = "10.5.6.7"  # in trusted CIDR
+    req.headers = {"x-real-ip": "203.0.113.42"}
+    assert _get_client_ip(req) == "203.0.113.42"
+
+
+def test_get_client_ip_x_real_ip_rejected_from_untrusted_peer(monkeypatch):
+    """X-Real-IP is rejected when the TCP peer is NOT in the trusted list."""
+    monkeypatch.setenv("AUTH_TRUSTED_PROXIES", "10.0.0.0/8")
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client.host = "8.8.8.8"  # NOT in trusted CIDR
+    req.headers = {"x-real-ip": "203.0.113.42"}  # client trying to spoof
+    assert _get_client_ip(req) == "8.8.8.8"
+
+
+def test_get_client_ip_xff_never_honored(monkeypatch):
+    """X-Forwarded-For is never used; only X-Real-IP from a trusted peer."""
+    monkeypatch.setenv("AUTH_TRUSTED_PROXIES", "10.0.0.0/8")
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client.host = "10.0.0.1"
+    req.headers = {"x-forwarded-for": "198.51.100.5"}  # no x-real-ip
+    assert _get_client_ip(req) == "10.0.0.1"
+
+
+def test_get_client_ip_invalid_trusted_proxy_entry_skipped(monkeypatch, caplog):
+    """Garbage entries in AUTH_TRUSTED_PROXIES are warned and skipped."""
+    monkeypatch.setenv("AUTH_TRUSTED_PROXIES", "not-an-ip,10.0.0.0/8")
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client.host = "10.5.6.7"
+    req.headers = {"x-real-ip": "203.0.113.42"}
+    assert _get_client_ip(req) == "203.0.113.42"  # valid entry still works
+
+
+def test_get_client_ip_no_client_returns_unknown(monkeypatch):
+    """No request.client → 'unknown' marker (no crash)."""
+    monkeypatch.delenv("AUTH_TRUSTED_PROXIES", raising=False)
+    from app.gateway.routers.auth import _get_client_ip
+
+    req = MagicMock()
+    req.client = None
+    req.headers = {}
+    assert _get_client_ip(req) == "unknown"
+
+
+# ── Common-password blocklist ────────────────────────────────────────────────
+
+
+def test_register_rejects_literal_password():
+    """Pydantic validator rejects 'password' as a registration password."""
+    from pydantic import ValidationError
+
+    from app.gateway.routers.auth import RegisterRequest
+
+    with pytest.raises(ValidationError) as exc:
+        RegisterRequest(email="x@example.com", password="password")
+    assert "too common" in str(exc.value)
+
+
+def test_register_rejects_common_password_case_insensitive():
+    """Case variants of common passwords are also rejected."""
+    from pydantic import ValidationError
+
+    from app.gateway.routers.auth import RegisterRequest
+
+    for variant in ["PASSWORD", "Password1", "qwerty123", "letmein1"]:
+        with pytest.raises(ValidationError):
+            RegisterRequest(email="x@example.com", password=variant)
+
+
+def test_register_accepts_strong_password():
+    """A non-blocklisted password of length >=8 is accepted."""
+    from app.gateway.routers.auth import RegisterRequest
+
+    req = RegisterRequest(email="x@example.com", password="Tr0ub4dor&3-Horse")
+    assert req.password == "Tr0ub4dor&3-Horse"
+
+
+def test_change_password_rejects_common_password():
+    """The same blocklist applies to change-password."""
+    from pydantic import ValidationError
+
+    from app.gateway.routers.auth import ChangePasswordRequest
+
+    with pytest.raises(ValidationError):
+        ChangePasswordRequest(current_password="anything", new_password="iloveyou")
+
+
+def test_password_blocklist_keeps_short_passwords_for_length_check():
+    """Short passwords still fail the min_length check (not the blocklist)."""
+    from pydantic import ValidationError
+
+    from app.gateway.routers.auth import RegisterRequest
+
+    with pytest.raises(ValidationError) as exc:
+        RegisterRequest(email="x@example.com", password="abc")
+    # the length check should fire, not the blocklist
+    assert "at least 8 characters" in str(exc.value)
+
+
+# ── Weak JWT secret warning ──────────────────────────────────────────────────
+
+
+def test_missing_jwt_secret_generates_ephemeral(monkeypatch, caplog):
+    """get_auth_config() auto-generates an ephemeral secret when AUTH_JWT_SECRET is unset."""
+    import logging
+
+    import app.gateway.auth.config as config_module
+
+    config_module._auth_config = None
+    monkeypatch.delenv("AUTH_JWT_SECRET", raising=False)
+
+    with caplog.at_level(logging.WARNING):
+        config = config_module.get_auth_config()
+
+    assert config.jwt_secret  # non-empty ephemeral secret
+    assert any("AUTH_JWT_SECRET" in msg for msg in caplog.messages)
+
+    # Cleanup
+    config_module._auth_config = None
@@ -0,0 +1,54 @@
+"""Tests for AuthConfig typed configuration."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+from app.gateway.auth.config import AuthConfig
+
+
+def test_auth_config_defaults():
+    config = AuthConfig(jwt_secret="test-secret-key-123")
+    assert config.token_expiry_days == 7
+
+
+def test_auth_config_token_expiry_range():
+    AuthConfig(jwt_secret="s", token_expiry_days=1)
+    AuthConfig(jwt_secret="s", token_expiry_days=30)
+    with pytest.raises(Exception):
+        AuthConfig(jwt_secret="s", token_expiry_days=0)
+    with pytest.raises(Exception):
+        AuthConfig(jwt_secret="s", token_expiry_days=31)
+
+
+def test_auth_config_from_env():
+    env = {"AUTH_JWT_SECRET": "test-jwt-secret-from-env"}
+    with patch.dict(os.environ, env, clear=False):
+        import app.gateway.auth.config as cfg
+
+        old = cfg._auth_config
+        cfg._auth_config = None
+        try:
+            config = cfg.get_auth_config()
+            assert config.jwt_secret == "test-jwt-secret-from-env"
+        finally:
+            cfg._auth_config = old
+
+
+def test_auth_config_missing_secret_generates_ephemeral(caplog):
+    import logging
+
+    import app.gateway.auth.config as cfg
+
+    old = cfg._auth_config
+    cfg._auth_config = None
+    try:
+        with patch.dict(os.environ, {}, clear=True):
+            os.environ.pop("AUTH_JWT_SECRET", None)
+            with caplog.at_level(logging.WARNING):
+                config = cfg.get_auth_config()
+            assert config.jwt_secret
+            assert any("AUTH_JWT_SECRET" in msg for msg in caplog.messages)
+    finally:
+        cfg._auth_config = old
@@ -0,0 +1,75 @@
+"""Tests for auth error types and typed decode_token."""
+
+from datetime import UTC, datetime, timedelta
+
+import jwt as pyjwt
+
+from app.gateway.auth.config import AuthConfig, set_auth_config
+from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse, TokenError
+from app.gateway.auth.jwt import create_access_token, decode_token
+
+
+def test_auth_error_code_values():
+    assert AuthErrorCode.INVALID_CREDENTIALS == "invalid_credentials"
+    assert AuthErrorCode.TOKEN_EXPIRED == "token_expired"
+    assert AuthErrorCode.NOT_AUTHENTICATED == "not_authenticated"
+
+
+def test_token_error_values():
+    assert TokenError.EXPIRED == "expired"
+    assert TokenError.INVALID_SIGNATURE == "invalid_signature"
+    assert TokenError.MALFORMED == "malformed"
+
+
+def test_auth_error_response_serialization():
+    err = AuthErrorResponse(
+        code=AuthErrorCode.TOKEN_EXPIRED,
+        message="Token has expired",
+    )
+    d = err.model_dump()
+    assert d == {"code": "token_expired", "message": "Token has expired"}
+
+
+def test_auth_error_response_from_dict():
+    d = {"code": "invalid_credentials", "message": "Wrong password"}
+    err = AuthErrorResponse(**d)
+    assert err.code == AuthErrorCode.INVALID_CREDENTIALS
+
+
+# ── decode_token typed failure tests ──────────────────────────────
+
+_TEST_SECRET = "test-secret-for-jwt-decode-token-tests"
+
+
+def _setup_config():
+    set_auth_config(AuthConfig(jwt_secret=_TEST_SECRET))
+
+
+def test_decode_token_returns_token_error_on_expired():
+    _setup_config()
+    expired_payload = {"sub": "user-1", "exp": datetime.now(UTC) - timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(expired_payload, _TEST_SECRET, algorithm="HS256")
+    result = decode_token(token)
+    assert result == TokenError.EXPIRED
+
+
+def test_decode_token_returns_token_error_on_bad_signature():
+    _setup_config()
+    payload = {"sub": "user-1", "exp": datetime.now(UTC) + timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(payload, "wrong-secret", algorithm="HS256")
+    result = decode_token(token)
+    assert result == TokenError.INVALID_SIGNATURE
+
+
+def test_decode_token_returns_token_error_on_malformed():
+    _setup_config()
+    result = decode_token("not-a-jwt")
+    assert result == TokenError.MALFORMED
+
+
+def test_decode_token_returns_payload_on_valid():
+    _setup_config()
+    token = create_access_token("user-123")
+    result = decode_token(token)
+    assert not isinstance(result, TokenError)
+    assert result.sub == "user-123"
@@ -0,0 +1,222 @@
+"""Tests for the global AuthMiddleware (fail-closed safety net)."""
+
+import pytest
+from starlette.testclient import TestClient
+
+from app.gateway.auth_middleware import AuthMiddleware, _is_public
+
+# ── _is_public unit tests ─────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/health",
+        "/health/",
+        "/docs",
+        "/docs/",
+        "/redoc",
+        "/openapi.json",
+        "/api/v1/auth/login/local",
+        "/api/v1/auth/register",
+        "/api/v1/auth/logout",
+        "/api/v1/auth/setup-status",
+    ],
+)
+def test_public_paths(path: str):
+    assert _is_public(path) is True
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/api/models",
+        "/api/mcp/config",
+        "/api/memory",
+        "/api/skills",
+        "/api/threads/123",
+        "/api/threads/123/uploads",
+        "/api/agents",
+        "/api/channels",
+        "/api/runs/stream",
+        "/api/threads/123/runs",
+        "/api/v1/auth/me",
+        "/api/v1/auth/change-password",
+    ],
+)
+def test_protected_paths(path: str):
+    assert _is_public(path) is False
+
+
+# ── Trailing slash / normalization edge cases ─────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/api/v1/auth/login/local/",
+        "/api/v1/auth/register/",
+        "/api/v1/auth/logout/",
+        "/api/v1/auth/setup-status/",
+    ],
+)
+def test_public_auth_paths_with_trailing_slash(path: str):
+    assert _is_public(path) is True
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/api/models/",
+        "/api/v1/auth/me/",
+        "/api/v1/auth/change-password/",
+    ],
+)
+def test_protected_paths_with_trailing_slash(path: str):
+    assert _is_public(path) is False
+
+
+def test_unknown_api_path_is_protected():
+    """Fail-closed: any new /api/* path is protected by default."""
+    assert _is_public("/api/new-feature") is False
+    assert _is_public("/api/v2/something") is False
+    assert _is_public("/api/v1/auth/new-endpoint") is False
+
+
+# ── Middleware integration tests ──────────────────────────────────────────
+
+
+def _make_app():
+    """Create a minimal FastAPI app with AuthMiddleware for testing."""
+    from fastapi import FastAPI
+
+    app = FastAPI()
+    app.add_middleware(AuthMiddleware)
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok"}
+
+    @app.get("/api/v1/auth/me")
+    async def auth_me():
+        return {"id": "1", "email": "test@test.com"}
+
+    @app.get("/api/v1/auth/setup-status")
+    async def setup_status():
+        return {"needs_setup": False}
+
+    @app.get("/api/models")
+    async def models_get():
+        return {"models": []}
+
+    @app.put("/api/mcp/config")
+    async def mcp_put():
+        return {"ok": True}
+
+    @app.delete("/api/threads/abc")
+    async def thread_delete():
+        return {"ok": True}
+
+    @app.patch("/api/threads/abc")
+    async def thread_patch():
+        return {"ok": True}
+
+    @app.post("/api/threads/abc/runs/stream")
+    async def stream():
+        return {"ok": True}
+
+    @app.get("/api/future-endpoint")
+    async def future():
+        return {"ok": True}
+
+    return app
+
+
+@pytest.fixture
+def client():
+    return TestClient(_make_app())
+
+
+def test_public_path_no_cookie(client):
+    res = client.get("/health")
+    assert res.status_code == 200
+
+
+def test_public_auth_path_no_cookie(client):
+    """Public auth endpoints (login/register) pass without cookie."""
+    res = client.get("/api/v1/auth/setup-status")
+    assert res.status_code == 200
+
+
+def test_protected_auth_path_no_cookie(client):
+    """/auth/me requires cookie even though it's under /api/v1/auth/."""
+    res = client.get("/api/v1/auth/me")
+    assert res.status_code == 401
+
+
+def test_protected_path_no_cookie_returns_401(client):
+    res = client.get("/api/models")
+    assert res.status_code == 401
+    body = res.json()
+    assert body["detail"]["code"] == "not_authenticated"
+
+
+def test_protected_path_with_junk_cookie_rejected(client):
+    """Junk cookie → 401. Middleware strictly validates the JWT now
+    (AUTH_TEST_PLAN test 7.5.8); it no longer silently passes bad
+    tokens through to the route handler."""
+    res = client.get("/api/models", cookies={"access_token": "some-token"})
+    assert res.status_code == 401
+
+
+def test_protected_post_no_cookie_returns_401(client):
+    res = client.post("/api/threads/abc/runs/stream")
+    assert res.status_code == 401
+
+
+# ── Method matrix: PUT/DELETE/PATCH also protected ────────────────────────
+
+
+def test_protected_put_no_cookie(client):
+    res = client.put("/api/mcp/config")
+    assert res.status_code == 401
+
+
+def test_protected_delete_no_cookie(client):
+    res = client.delete("/api/threads/abc")
+    assert res.status_code == 401
+
+
+def test_protected_patch_no_cookie(client):
+    res = client.patch("/api/threads/abc")
+    assert res.status_code == 401
+
+
+def test_put_with_junk_cookie_rejected(client):
+    """Junk cookie on PUT → 401 (strict JWT validation in middleware)."""
+    client.cookies.set("access_token", "tok")
+    res = client.put("/api/mcp/config")
+    assert res.status_code == 401
+
+
+def test_delete_with_junk_cookie_rejected(client):
+    """Junk cookie on DELETE → 401 (strict JWT validation in middleware)."""
+    client.cookies.set("access_token", "tok")
+    res = client.delete("/api/threads/abc")
+    assert res.status_code == 401
+
+
+# ── Fail-closed: unknown future endpoints ─────────────────────────────────
+
+
+def test_unknown_endpoint_no_cookie_returns_401(client):
+    """Any new /api/* endpoint is blocked by default without cookie."""
+    res = client.get("/api/future-endpoint")
+    assert res.status_code == 401
+
+
+def test_unknown_endpoint_with_junk_cookie_rejected(client):
+    """New endpoints are also protected by strict JWT validation."""
+    client.cookies.set("access_token", "tok")
+    res = client.get("/api/future-endpoint")
+    assert res.status_code == 401
@@ -0,0 +1,701 @@
+"""Tests for auth type system hardening.
+
+Covers structured error responses, typed decode_token callers,
+CSRF middleware path matching, config-driven cookie security,
+and unhappy paths / edge cases for all auth boundaries.
+"""
+
+import os
+import secrets
+from datetime import UTC, datetime, timedelta
+from unittest.mock import patch
+
+import jwt as pyjwt
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+
+from app.gateway.auth.config import AuthConfig, set_auth_config
+from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse, TokenError
+from app.gateway.auth.jwt import decode_token
+from app.gateway.csrf_middleware import (
+    CSRF_COOKIE_NAME,
+    CSRF_HEADER_NAME,
+    CSRFMiddleware,
+    is_auth_endpoint,
+    should_check_csrf,
+)
+
+# ── Setup ────────────────────────────────────────────────────────────
+
+_TEST_SECRET = "test-secret-for-auth-type-system-tests-min32"
+
+
+@pytest.fixture(autouse=True)
+def _persistence_engine(tmp_path):
+    """Initialise a per-test SQLite engine + reset cached provider singletons.
+
+    The auth tests call real HTTP handlers that go through
+    ``SQLiteUserRepository`` → ``get_session_factory``. Each test gets
+    a fresh DB plus a clean ``deps._cached_*`` so the cached provider
+    does not hold a dangling reference to the previous test's engine.
+    """
+    import asyncio
+
+    from app.gateway import deps
+    from deerflow.persistence.engine import close_engine, init_engine
+
+    url = f"sqlite+aiosqlite:///{tmp_path}/auth_types.db"
+    asyncio.run(init_engine("sqlite", url=url, sqlite_dir=str(tmp_path)))
+    deps._cached_local_provider = None
+    deps._cached_repo = None
+    try:
+        yield
+    finally:
+        deps._cached_local_provider = None
+        deps._cached_repo = None
+        asyncio.run(close_engine())
+
+
+def _setup_config():
+    set_auth_config(AuthConfig(jwt_secret=_TEST_SECRET))
+
+
+# ── CSRF Middleware Path Matching ────────────────────────────────────
+
+
+class _FakeRequest:
+    """Minimal request mock for CSRF path matching tests."""
+
+    def __init__(self, path: str, method: str = "POST"):
+        self.method = method
+
+        class _URL:
+            def __init__(self, p):
+                self.path = p
+
+        self.url = _URL(path)
+        self.cookies = {}
+        self.headers = {}
+
+
+def test_csrf_exempts_login_local():
+    """login/local (actual route) should be exempt from CSRF."""
+    req = _FakeRequest("/api/v1/auth/login/local")
+    assert is_auth_endpoint(req) is True
+
+
+def test_csrf_exempts_login_local_trailing_slash():
+    """Trailing slash should also be exempt."""
+    req = _FakeRequest("/api/v1/auth/login/local/")
+    assert is_auth_endpoint(req) is True
+
+
+def test_csrf_exempts_logout():
+    req = _FakeRequest("/api/v1/auth/logout")
+    assert is_auth_endpoint(req) is True
+
+
+def test_csrf_exempts_register():
+    req = _FakeRequest("/api/v1/auth/register")
+    assert is_auth_endpoint(req) is True
+
+
+def test_csrf_does_not_exempt_old_login_path():
+    """Old /api/v1/auth/login (without /local) should NOT be exempt."""
+    req = _FakeRequest("/api/v1/auth/login")
+    assert is_auth_endpoint(req) is False
+
+
+def test_csrf_does_not_exempt_me():
+    req = _FakeRequest("/api/v1/auth/me")
+    assert is_auth_endpoint(req) is False
+
+
+def test_csrf_skips_get_requests():
+    req = _FakeRequest("/api/v1/auth/me", method="GET")
+    assert should_check_csrf(req) is False
+
+
+def test_csrf_checks_post_to_protected():
+    req = _FakeRequest("/api/v1/some/endpoint", method="POST")
+    assert should_check_csrf(req) is True
+
+
+# ── Structured Error Response Format ────────────────────────────────
+
+
+def test_auth_error_response_has_code_and_message():
+    """All auth errors should have structured {code, message} format."""
+    err = AuthErrorResponse(
+        code=AuthErrorCode.INVALID_CREDENTIALS,
+        message="Wrong password",
+    )
+    d = err.model_dump()
+    assert "code" in d
+    assert "message" in d
+    assert d["code"] == "invalid_credentials"
+
+
+def test_auth_error_response_all_codes_serializable():
+    """Every AuthErrorCode should be serializable in AuthErrorResponse."""
+    for code in AuthErrorCode:
+        err = AuthErrorResponse(code=code, message=f"Test {code.value}")
+        d = err.model_dump()
+        assert d["code"] == code.value
+
+
+# ── decode_token Caller Pattern ──────────────────────────────────────
+
+
+def test_decode_token_expired_maps_to_token_expired_code():
+    """TokenError.EXPIRED should map to AuthErrorCode.TOKEN_EXPIRED."""
+    _setup_config()
+    from datetime import UTC, datetime, timedelta
+
+    import jwt as pyjwt
+
+    expired = {"sub": "u1", "exp": datetime.now(UTC) - timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(expired, _TEST_SECRET, algorithm="HS256")
+    result = decode_token(token)
+    assert result == TokenError.EXPIRED
+
+    # Verify the mapping pattern used in route handlers
+    code = AuthErrorCode.TOKEN_EXPIRED if result == TokenError.EXPIRED else AuthErrorCode.TOKEN_INVALID
+    assert code == AuthErrorCode.TOKEN_EXPIRED
+
+
+def test_decode_token_invalid_sig_maps_to_token_invalid_code():
+    """TokenError.INVALID_SIGNATURE should map to AuthErrorCode.TOKEN_INVALID."""
+    _setup_config()
+    from datetime import UTC, datetime, timedelta
+
+    import jwt as pyjwt
+
+    payload = {"sub": "u1", "exp": datetime.now(UTC) + timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(payload, "wrong-key", algorithm="HS256")
+    result = decode_token(token)
+    assert result == TokenError.INVALID_SIGNATURE
+
+    code = AuthErrorCode.TOKEN_EXPIRED if result == TokenError.EXPIRED else AuthErrorCode.TOKEN_INVALID
+    assert code == AuthErrorCode.TOKEN_INVALID
+
+
+def test_decode_token_malformed_maps_to_token_invalid_code():
+    """TokenError.MALFORMED should map to AuthErrorCode.TOKEN_INVALID."""
+    _setup_config()
+    result = decode_token("garbage")
+    assert result == TokenError.MALFORMED
+
+    code = AuthErrorCode.TOKEN_EXPIRED if result == TokenError.EXPIRED else AuthErrorCode.TOKEN_INVALID
+    assert code == AuthErrorCode.TOKEN_INVALID
+
+
+# ── Login Response Format ────────────────────────────────────────────
+
+
+def test_login_response_model_has_no_access_token():
+    """LoginResponse should NOT contain access_token field (RFC-001)."""
+    from app.gateway.routers.auth import LoginResponse
+
+    resp = LoginResponse(expires_in=604800)
+    d = resp.model_dump()
+    assert "access_token" not in d
+    assert "expires_in" in d
+    assert d["expires_in"] == 604800
+
+
+def test_login_response_model_fields():
+    """LoginResponse has expires_in and needs_setup."""
+    from app.gateway.routers.auth import LoginResponse
+
+    fields = set(LoginResponse.model_fields.keys())
+    assert fields == {"expires_in", "needs_setup"}
+
+
+# ── AuthConfig in Route ──────────────────────────────────────────────
+
+
+def test_auth_config_token_expiry_used_in_login_response():
+    """LoginResponse.expires_in should come from config.token_expiry_days."""
+    from app.gateway.routers.auth import LoginResponse
+
+    expected_seconds = 14 * 24 * 3600
+    resp = LoginResponse(expires_in=expected_seconds)
+    assert resp.expires_in == expected_seconds
+
+
+# ── UserResponse Type Preservation ───────────────────────────────────
+
+
+def test_user_response_system_role_literal():
+    """UserResponse.system_role should only accept 'admin' or 'user'."""
+    from app.gateway.auth.models import UserResponse
+
+    # Valid roles
+    resp = UserResponse(id="1", email="a@b.com", system_role="admin")
+    assert resp.system_role == "admin"
+
+    resp = UserResponse(id="1", email="a@b.com", system_role="user")
+    assert resp.system_role == "user"
+
+
+def test_user_response_rejects_invalid_role():
+    """UserResponse should reject invalid system_role values."""
+    from app.gateway.auth.models import UserResponse
+
+    with pytest.raises(ValidationError):
+        UserResponse(id="1", email="a@b.com", system_role="superadmin")
+
+
+# ══════════════════════════════════════════════════════════════════════
+# UNHAPPY PATHS / EDGE CASES
+# ══════════════════════════════════════════════════════════════════════
+
+
+# ── get_current_user structured 401 responses ────────────────────────
+
+
+def test_get_current_user_no_cookie_returns_not_authenticated():
+    """No cookie → 401 with code=not_authenticated."""
+    import asyncio
+
+    from fastapi import HTTPException
+
+    from app.gateway.deps import get_current_user_from_request
+
+    mock_request = type("MockRequest", (), {"cookies": {}})()
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(get_current_user_from_request(mock_request))
+    assert exc_info.value.status_code == 401
+    detail = exc_info.value.detail
+    assert detail["code"] == "not_authenticated"
+
+
+def test_get_current_user_expired_token_returns_token_expired():
+    """Expired token → 401 with code=token_expired."""
+    import asyncio
+
+    from fastapi import HTTPException
+
+    from app.gateway.deps import get_current_user_from_request
+
+    _setup_config()
+    expired = {"sub": "u1", "exp": datetime.now(UTC) - timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(expired, _TEST_SECRET, algorithm="HS256")
+
+    mock_request = type("MockRequest", (), {"cookies": {"access_token": token}})()
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(get_current_user_from_request(mock_request))
+    assert exc_info.value.status_code == 401
+    detail = exc_info.value.detail
+    assert detail["code"] == "token_expired"
+
+
+def test_get_current_user_invalid_token_returns_token_invalid():
+    """Bad signature → 401 with code=token_invalid."""
+    import asyncio
+
+    from fastapi import HTTPException
+
+    from app.gateway.deps import get_current_user_from_request
+
+    _setup_config()
+    payload = {"sub": "u1", "exp": datetime.now(UTC) + timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(payload, "wrong-secret", algorithm="HS256")
+
+    mock_request = type("MockRequest", (), {"cookies": {"access_token": token}})()
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(get_current_user_from_request(mock_request))
+    assert exc_info.value.status_code == 401
+    detail = exc_info.value.detail
+    assert detail["code"] == "token_invalid"
+
+
+def test_get_current_user_malformed_token_returns_token_invalid():
+    """Garbage token → 401 with code=token_invalid."""
+    import asyncio
+
+    from fastapi import HTTPException
+
+    from app.gateway.deps import get_current_user_from_request
+
+    _setup_config()
+    mock_request = type("MockRequest", (), {"cookies": {"access_token": "not-a-jwt"}})()
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(get_current_user_from_request(mock_request))
+    assert exc_info.value.status_code == 401
+    detail = exc_info.value.detail
+    assert detail["code"] == "token_invalid"
+
+
+# ── decode_token edge cases ──────────────────────────────────────────
+
+
+def test_decode_token_empty_string_returns_malformed():
+    _setup_config()
+    result = decode_token("")
+    assert result == TokenError.MALFORMED
+
+
+def test_decode_token_whitespace_returns_malformed():
+    _setup_config()
+    result = decode_token("   ")
+    assert result == TokenError.MALFORMED
+
+
+# ── AuthConfig validation edge cases ─────────────────────────────────
+
+
+def test_auth_config_missing_jwt_secret_raises():
+    """AuthConfig requires jwt_secret — no default allowed."""
+    with pytest.raises(ValidationError):
+        AuthConfig()
+
+
+def test_auth_config_token_expiry_zero_raises():
+    """token_expiry_days must be >= 1."""
+    with pytest.raises(ValidationError):
+        AuthConfig(jwt_secret="secret", token_expiry_days=0)
+
+
+def test_auth_config_token_expiry_31_raises():
+    """token_expiry_days must be <= 30."""
+    with pytest.raises(ValidationError):
+        AuthConfig(jwt_secret="secret", token_expiry_days=31)
+
+
+def test_auth_config_token_expiry_boundary_1_ok():
+    config = AuthConfig(jwt_secret="secret", token_expiry_days=1)
+    assert config.token_expiry_days == 1
+
+
+def test_auth_config_token_expiry_boundary_30_ok():
+    config = AuthConfig(jwt_secret="secret", token_expiry_days=30)
+    assert config.token_expiry_days == 30
+
+
+def test_get_auth_config_missing_env_var_generates_ephemeral(caplog):
+    """get_auth_config() auto-generates ephemeral secret when AUTH_JWT_SECRET is unset."""
+    import logging
+
+    import app.gateway.auth.config as cfg
+
+    old = cfg._auth_config
+    cfg._auth_config = None
+    try:
+        with patch.dict(os.environ, {}, clear=True):
+            os.environ.pop("AUTH_JWT_SECRET", None)
+            with caplog.at_level(logging.WARNING):
+                config = cfg.get_auth_config()
+            assert config.jwt_secret
+            assert any("AUTH_JWT_SECRET" in msg for msg in caplog.messages)
+    finally:
+        cfg._auth_config = old
+
+
+# ── CSRF middleware integration (unhappy paths) ──────────────────────
+
+
+def _make_csrf_app():
+    """Create a minimal FastAPI app with CSRFMiddleware for testing."""
+    from fastapi import HTTPException as _HTTPException
+    from fastapi.responses import JSONResponse as _JSONResponse
+
+    app = FastAPI()
+
+    @app.exception_handler(_HTTPException)
+    async def _http_exc_handler(request, exc):
+        return _JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+    app.add_middleware(CSRFMiddleware)
+
+    @app.post("/api/v1/test/protected")
+    async def protected():
+        return {"ok": True}
+
+    @app.post("/api/v1/auth/login/local")
+    async def login():
+        return {"ok": True}
+
+    @app.get("/api/v1/test/read")
+    async def read_endpoint():
+        return {"ok": True}
+
+    return app
+
+
+def test_csrf_middleware_blocks_post_without_token():
+    """POST to protected endpoint without CSRF token → 403 with structured detail."""
+    client = TestClient(_make_csrf_app())
+    resp = client.post("/api/v1/test/protected")
+    assert resp.status_code == 403
+    assert "CSRF" in resp.json()["detail"]
+    assert "missing" in resp.json()["detail"].lower()
+
+
+def test_csrf_middleware_blocks_post_with_mismatched_token():
+    """POST with mismatched CSRF cookie/header → 403 with mismatch detail."""
+    client = TestClient(_make_csrf_app())
+    client.cookies.set(CSRF_COOKIE_NAME, "token-a")
+    resp = client.post(
+        "/api/v1/test/protected",
+        headers={CSRF_HEADER_NAME: "token-b"},
+    )
+    assert resp.status_code == 403
+    assert "mismatch" in resp.json()["detail"].lower()
+
+
+def test_csrf_middleware_allows_post_with_matching_token():
+    """POST with matching CSRF cookie/header → 200."""
+    client = TestClient(_make_csrf_app())
+    token = secrets.token_urlsafe(64)
+    client.cookies.set(CSRF_COOKIE_NAME, token)
+    resp = client.post(
+        "/api/v1/test/protected",
+        headers={CSRF_HEADER_NAME: token},
+    )
+    assert resp.status_code == 200
+
+
+def test_csrf_middleware_allows_get_without_token():
+    """GET requests bypass CSRF check."""
+    client = TestClient(_make_csrf_app())
+    resp = client.get("/api/v1/test/read")
+    assert resp.status_code == 200
+
+
+def test_csrf_middleware_exempts_login_local():
+    """POST to login/local is exempt from CSRF (no token yet)."""
+    client = TestClient(_make_csrf_app())
+    resp = client.post("/api/v1/auth/login/local")
+    assert resp.status_code == 200
+
+
+def test_csrf_middleware_sets_cookie_on_auth_endpoint():
+    """Auth endpoints should receive a CSRF cookie in response."""
+    client = TestClient(_make_csrf_app())
+    resp = client.post("/api/v1/auth/login/local")
+    assert CSRF_COOKIE_NAME in resp.cookies
+
+
+# ── UserResponse edge cases ──────────────────────────────────────────
+
+
+def test_user_response_missing_required_fields():
+    """UserResponse with missing fields → ValidationError."""
+    from app.gateway.auth.models import UserResponse
+
+    with pytest.raises(ValidationError):
+        UserResponse(id="1")  # missing email, system_role
+
+    with pytest.raises(ValidationError):
+        UserResponse(id="1", email="a@b.com")  # missing system_role
+
+
+def test_user_response_empty_string_role_rejected():
+    """Empty string is not a valid role."""
+    from app.gateway.auth.models import UserResponse
+
+    with pytest.raises(ValidationError):
+        UserResponse(id="1", email="a@b.com", system_role="")
+
+
+# ══════════════════════════════════════════════════════════════════════
+# HTTP-LEVEL API CONTRACT TESTS
+# ══════════════════════════════════════════════════════════════════════
+
+
+def _make_auth_app():
+    """Create FastAPI app with auth routes for contract testing."""
+    from app.gateway.app import create_app
+
+    return create_app()
+
+
+def _get_auth_client():
+    """Get TestClient for auth API contract tests."""
+    return TestClient(_make_auth_app())
+
+
+def test_api_auth_me_no_cookie_returns_structured_401():
+    """/api/v1/auth/me without cookie → 401 with {code: 'not_authenticated'}."""
+    _setup_config()
+    client = _get_auth_client()
+    resp = client.get("/api/v1/auth/me")
+    assert resp.status_code == 401
+    body = resp.json()
+    assert body["detail"]["code"] == "not_authenticated"
+    assert "message" in body["detail"]
+
+
+def test_api_auth_me_expired_token_returns_structured_401():
+    """/api/v1/auth/me with expired token → 401 with {code: 'token_expired'}."""
+    _setup_config()
+    expired = {"sub": "u1", "exp": datetime.now(UTC) - timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(expired, _TEST_SECRET, algorithm="HS256")
+
+    client = _get_auth_client()
+    client.cookies.set("access_token", token)
+    resp = client.get("/api/v1/auth/me")
+    assert resp.status_code == 401
+    body = resp.json()
+    assert body["detail"]["code"] == "token_expired"
+
+
+def test_api_auth_me_invalid_sig_returns_structured_401():
+    """/api/v1/auth/me with bad signature → 401 with {code: 'token_invalid'}."""
+    _setup_config()
+    payload = {"sub": "u1", "exp": datetime.now(UTC) + timedelta(hours=1), "iat": datetime.now(UTC)}
+    token = pyjwt.encode(payload, "wrong-key", algorithm="HS256")
+
+    client = _get_auth_client()
+    client.cookies.set("access_token", token)
+    resp = client.get("/api/v1/auth/me")
+    assert resp.status_code == 401
+    body = resp.json()
+    assert body["detail"]["code"] == "token_invalid"
+
+
+def test_api_login_bad_credentials_returns_structured_401():
+    """Login with wrong password → 401 with {code: 'invalid_credentials'}."""
+    _setup_config()
+    client = _get_auth_client()
+    resp = client.post(
+        "/api/v1/auth/login/local",
+        data={"username": "nonexistent@test.com", "password": "wrongpassword"},
+    )
+    assert resp.status_code == 401
+    body = resp.json()
+    assert body["detail"]["code"] == "invalid_credentials"
+
+
+def test_api_login_success_no_token_in_body():
+    """Successful login → response body has expires_in but NOT access_token."""
+    _setup_config()
+    client = _get_auth_client()
+    # Register first
+    client.post(
+        "/api/v1/auth/register",
+        json={"email": "contract-test@test.com", "password": "securepassword123"},
+    )
+    # Login
+    resp = client.post(
+        "/api/v1/auth/login/local",
+        data={"username": "contract-test@test.com", "password": "securepassword123"},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+    assert "expires_in" in body
+    assert "access_token" not in body
+    # Token should be in cookie, not body
+    assert "access_token" in resp.cookies
+
+
+def test_api_register_duplicate_returns_structured_400():
+    """Register with duplicate email → 400 with {code: 'email_already_exists'}."""
+    _setup_config()
+    client = _get_auth_client()
+    email = "dup-contract-test@test.com"
+    # First register
+    client.post("/api/v1/auth/register", json={"email": email, "password": "Tr0ub4dor3a"})
+    # Duplicate
+    resp = client.post("/api/v1/auth/register", json={"email": email, "password": "AnotherStr0ngPwd!"})
+    assert resp.status_code == 400
+    body = resp.json()
+    assert body["detail"]["code"] == "email_already_exists"
+
+
+# ── Cookie security: HTTP vs HTTPS ────────────────────────────────────
+
+
+def _unique_email(prefix: str) -> str:
+    return f"{prefix}-{secrets.token_hex(4)}@test.com"
+
+
+def _get_set_cookie_headers(resp) -> list[str]:
+    """Extract all set-cookie header values from a TestClient response."""
+    return [v for k, v in resp.headers.multi_items() if k.lower() == "set-cookie"]
+
+
+def test_register_http_cookie_httponly_true_secure_false():
+    """HTTP register → access_token cookie is httponly=True, secure=False, no max_age."""
+    _setup_config()
+    client = _get_auth_client()
+    resp = client.post(
+        "/api/v1/auth/register",
+        json={"email": _unique_email("http-cookie"), "password": "Tr0ub4dor3a"},
+    )
+    assert resp.status_code == 201
+    cookie_header = resp.headers.get("set-cookie", "")
+    assert "access_token=" in cookie_header
+    assert "httponly" in cookie_header.lower()
+    assert "secure" not in cookie_header.lower().replace("samesite", "")
+
+
+def test_register_https_cookie_httponly_true_secure_true():
+    """HTTPS register (x-forwarded-proto) → access_token cookie is httponly=True, secure=True, has max_age."""
+    _setup_config()
+    client = _get_auth_client()
+    resp = client.post(
+        "/api/v1/auth/register",
+        json={"email": _unique_email("https-cookie"), "password": "Tr0ub4dor3a"},
+        headers={"x-forwarded-proto": "https"},
+    )
+    assert resp.status_code == 201
+    cookie_header = resp.headers.get("set-cookie", "")
+    assert "access_token=" in cookie_header
+    assert "httponly" in cookie_header.lower()
+    assert "secure" in cookie_header.lower()
+    assert "max-age" in cookie_header.lower()
+
+
+def test_login_https_sets_secure_cookie():
+    """HTTPS login → access_token cookie has secure flag."""
+    _setup_config()
+    client = _get_auth_client()
+    email = _unique_email("https-login")
+    client.post("/api/v1/auth/register", json={"email": email, "password": "Tr0ub4dor3a"})
+    resp = client.post(
+        "/api/v1/auth/login/local",
+        data={"username": email, "password": "Tr0ub4dor3a"},
+        headers={"x-forwarded-proto": "https"},
+    )
+    assert resp.status_code == 200
+    cookie_header = resp.headers.get("set-cookie", "")
+    assert "access_token=" in cookie_header
+    assert "httponly" in cookie_header.lower()
+    assert "secure" in cookie_header.lower()
+
+
+def test_csrf_cookie_secure_on_https():
+    """HTTPS register → csrf_token cookie has secure flag but NOT httponly."""
+    _setup_config()
+    client = _get_auth_client()
+    resp = client.post(
+        "/api/v1/auth/register",
+        json={"email": _unique_email("csrf-https"), "password": "Tr0ub4dor3a"},
+        headers={"x-forwarded-proto": "https"},
+    )
+    assert resp.status_code == 201
+    csrf_cookies = [h for h in _get_set_cookie_headers(resp) if "csrf_token=" in h]
+    assert csrf_cookies, "csrf_token cookie not set on HTTPS register"
+    csrf_header = csrf_cookies[0]
+    assert "secure" in csrf_header.lower()
+    assert "httponly" not in csrf_header.lower()
+
+
+def test_csrf_cookie_not_secure_on_http():
+    """HTTP register → csrf_token cookie does NOT have secure flag."""
+    _setup_config()
+    client = _get_auth_client()
+    resp = client.post(
+        "/api/v1/auth/register",
+        json={"email": _unique_email("csrf-http"), "password": "Tr0ub4dor3a"},
+    )
+    assert resp.status_code == 201
+    csrf_cookies = [h for h in _get_set_cookie_headers(resp) if "csrf_token=" in h]
+    assert csrf_cookies, "csrf_token cookie not set on HTTP register"
+    csrf_header = csrf_cookies[0]
+    assert "secure" not in csrf_header.lower().replace("samesite", "")
@@ -0,0 +1,319 @@
+"""Tests for _ensure_admin_user() in app.py.
+
+Covers: first-boot admin creation, auto-reset on needs_setup=True,
+no-op on needs_setup=False, migration, and edge cases.
+"""
+
+import asyncio
+import os
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+os.environ.setdefault("AUTH_JWT_SECRET", "test-secret-key-ensure-admin-testing-min-32")
+
+from app.gateway.auth.config import AuthConfig, set_auth_config
+from app.gateway.auth.models import User
+
+_JWT_SECRET = "test-secret-key-ensure-admin-testing-min-32"
+
+
+@pytest.fixture(autouse=True)
+def _setup_auth_config():
+    set_auth_config(AuthConfig(jwt_secret=_JWT_SECRET))
+    yield
+    set_auth_config(AuthConfig(jwt_secret=_JWT_SECRET))
+
+
+def _make_app_stub(store=None):
+    """Minimal app-like object with state.store."""
+    app = SimpleNamespace()
+    app.state = SimpleNamespace()
+    app.state.store = store
+    return app
+
+
+def _make_provider(user_count=0, admin_user=None):
+    p = AsyncMock()
+    p.count_users = AsyncMock(return_value=user_count)
+    p.create_user = AsyncMock(
+        side_effect=lambda **kw: User(
+            email=kw["email"],
+            password_hash="hashed",
+            system_role=kw.get("system_role", "user"),
+            needs_setup=kw.get("needs_setup", False),
+        )
+    )
+    p.get_user_by_email = AsyncMock(return_value=admin_user)
+    p.update_user = AsyncMock(side_effect=lambda u: u)
+    return p
+
+
+# ── First boot: no users ─────────────────────────────────────────────────
+
+
+def test_first_boot_creates_admin():
+    """count_users==0 → create admin with needs_setup=True."""
+    provider = _make_provider(user_count=0)
+    app = _make_app_stub()
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        with patch("app.gateway.auth.password.hash_password_async", new_callable=AsyncMock, return_value="hashed"):
+            from app.gateway.app import _ensure_admin_user
+
+            asyncio.run(_ensure_admin_user(app))
+
+    provider.create_user.assert_called_once()
+    call_kwargs = provider.create_user.call_args[1]
+    assert call_kwargs["email"] == "admin@deerflow.dev"
+    assert call_kwargs["system_role"] == "admin"
+    assert call_kwargs["needs_setup"] is True
+    assert len(call_kwargs["password"]) > 10  # random password generated
+
+
+def test_first_boot_triggers_migration_if_store_present():
+    """First boot with store → _migrate_orphaned_threads called."""
+    provider = _make_provider(user_count=0)
+    store = AsyncMock()
+    store.asearch = AsyncMock(return_value=[])
+    app = _make_app_stub(store=store)
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        with patch("app.gateway.auth.password.hash_password_async", new_callable=AsyncMock, return_value="hashed"):
+            from app.gateway.app import _ensure_admin_user
+
+            asyncio.run(_ensure_admin_user(app))
+
+    store.asearch.assert_called_once()
+
+
+def test_first_boot_no_store_skips_migration():
+    """First boot without store → no crash, migration skipped."""
+    provider = _make_provider(user_count=0)
+    app = _make_app_stub(store=None)
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        with patch("app.gateway.auth.password.hash_password_async", new_callable=AsyncMock, return_value="hashed"):
+            from app.gateway.app import _ensure_admin_user
+
+            asyncio.run(_ensure_admin_user(app))
+
+    provider.create_user.assert_called_once()
+
+
+# ── Subsequent boot: needs_setup=True → auto-reset ───────────────────────
+
+
+def test_needs_setup_true_resets_password():
+    """Existing admin with needs_setup=True → password reset + token_version bumped."""
+    admin = User(
+        email="admin@deerflow.dev",
+        password_hash="old-hash",
+        system_role="admin",
+        needs_setup=True,
+        token_version=0,
+        created_at=datetime.now(UTC) - timedelta(seconds=30),
+    )
+    provider = _make_provider(user_count=1, admin_user=admin)
+    app = _make_app_stub()
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        with patch("app.gateway.auth.password.hash_password_async", new_callable=AsyncMock, return_value="new-hash"):
+            from app.gateway.app import _ensure_admin_user
+
+            asyncio.run(_ensure_admin_user(app))
+
+    # Password was reset
+    provider.update_user.assert_called_once()
+    updated = provider.update_user.call_args[0][0]
+    assert updated.password_hash == "new-hash"
+    assert updated.token_version == 1
+
+
+def test_needs_setup_true_consecutive_resets_increment_version():
+    """Two boots with needs_setup=True → token_version increments each time."""
+    admin = User(
+        email="admin@deerflow.dev",
+        password_hash="hash",
+        system_role="admin",
+        needs_setup=True,
+        token_version=3,
+        created_at=datetime.now(UTC) - timedelta(seconds=30),
+    )
+    provider = _make_provider(user_count=1, admin_user=admin)
+    app = _make_app_stub()
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        with patch("app.gateway.auth.password.hash_password_async", new_callable=AsyncMock, return_value="new-hash"):
+            from app.gateway.app import _ensure_admin_user
+
+            asyncio.run(_ensure_admin_user(app))
+
+    updated = provider.update_user.call_args[0][0]
+    assert updated.token_version == 4
+
+
+# ── Subsequent boot: needs_setup=False → no-op ──────────────────────────
+
+
+def test_needs_setup_false_no_reset():
+    """Admin with needs_setup=False → no password reset, no update."""
+    admin = User(
+        email="admin@deerflow.dev",
+        password_hash="stable-hash",
+        system_role="admin",
+        needs_setup=False,
+        token_version=2,
+    )
+    provider = _make_provider(user_count=1, admin_user=admin)
+    app = _make_app_stub()
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        from app.gateway.app import _ensure_admin_user
+
+        asyncio.run(_ensure_admin_user(app))
+
+    provider.update_user.assert_not_called()
+    assert admin.password_hash == "stable-hash"
+    assert admin.token_version == 2
+
+
+# ── Edge cases ───────────────────────────────────────────────────────────
+
+
+def test_no_admin_email_found_no_crash():
+    """Users exist but no admin@deerflow.dev → no crash, no reset."""
+    provider = _make_provider(user_count=3, admin_user=None)
+    app = _make_app_stub()
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        from app.gateway.app import _ensure_admin_user
+
+        asyncio.run(_ensure_admin_user(app))
+
+    provider.update_user.assert_not_called()
+    provider.create_user.assert_not_called()
+
+
+def test_migration_failure_is_non_fatal():
+    """_migrate_orphaned_threads exception is caught and logged."""
+    provider = _make_provider(user_count=0)
+    store = AsyncMock()
+    store.asearch = AsyncMock(side_effect=RuntimeError("store crashed"))
+    app = _make_app_stub(store=store)
+
+    with patch("app.gateway.deps.get_local_provider", return_value=provider):
+        with patch("app.gateway.auth.password.hash_password_async", new_callable=AsyncMock, return_value="hashed"):
+            from app.gateway.app import _ensure_admin_user
+
+            # Should not raise
+            asyncio.run(_ensure_admin_user(app))
+
+    provider.create_user.assert_called_once()
+
+
+# ── Section 5.1-5.6 upgrade path: orphan thread migration ────────────────
+
+
+def test_migrate_orphaned_threads_stamps_owner_id_on_unowned_rows():
+    """First boot finds Store-only legacy threads → stamps admin's id.
+
+    Validates the **TC-UPG-02 upgrade story**: an operator running main
+    (no auth) accumulates threads in the LangGraph Store namespace
+    ``("threads",)`` with no ``metadata.owner_id``. After upgrading to
+    feat/auth-on-2.0-rc, the first ``_ensure_admin_user`` boot should
+    rewrite each unowned item with the freshly created admin's id.
+    """
+    from app.gateway.app import _migrate_orphaned_threads
+
+    # Three orphan items + one already-owned item that should be left alone.
+    items = [
+        SimpleNamespace(key="t1", value={"metadata": {"title": "old-thread-1"}}),
+        SimpleNamespace(key="t2", value={"metadata": {"title": "old-thread-2"}}),
+        SimpleNamespace(key="t3", value={"metadata": {}}),
+        SimpleNamespace(key="t4", value={"metadata": {"owner_id": "someone-else", "title": "preserved"}}),
+    ]
+    store = AsyncMock()
+    # asearch returns the entire batch on first call, then an empty page
+    # to terminate _iter_store_items.
+    store.asearch = AsyncMock(side_effect=[items, []])
+    aput_calls: list[tuple[tuple, str, dict]] = []
+
+    async def _record_aput(namespace, key, value):
+        aput_calls.append((namespace, key, value))
+
+    store.aput = AsyncMock(side_effect=_record_aput)
+
+    migrated = asyncio.run(_migrate_orphaned_threads(store, "admin-id-42"))
+
+    # Three orphan rows migrated, one preserved.
+    assert migrated == 3
+    assert len(aput_calls) == 3
+    rewritten_keys = {call[1] for call in aput_calls}
+    assert rewritten_keys == {"t1", "t2", "t3"}
+    # Each rewrite carries the new owner_id; titles preserved where present.
+    by_key = {call[1]: call[2] for call in aput_calls}
+    assert by_key["t1"]["metadata"]["owner_id"] == "admin-id-42"
+    assert by_key["t1"]["metadata"]["title"] == "old-thread-1"
+    assert by_key["t3"]["metadata"]["owner_id"] == "admin-id-42"
+    # The pre-owned item must NOT have been rewritten.
+    assert "t4" not in rewritten_keys
+
+
+def test_migrate_orphaned_threads_empty_store_is_noop():
+    """A store with no threads → migrated == 0, no aput calls."""
+    from app.gateway.app import _migrate_orphaned_threads
+
+    store = AsyncMock()
+    store.asearch = AsyncMock(return_value=[])
+    store.aput = AsyncMock()
+
+    migrated = asyncio.run(_migrate_orphaned_threads(store, "admin-id-42"))
+
+    assert migrated == 0
+    store.aput.assert_not_called()
+
+
+def test_iter_store_items_walks_multiple_pages():
+    """Cursor-style iterator pulls every page until a short page terminates.
+
+    Closes the regression where the old hardcoded ``limit=1000`` could
+    silently drop orphans on a large pre-upgrade dataset. The migration
+    code path uses the default ``page_size=500``; this test pins the
+    iterator with ``page_size=2`` so it stays fast.
+    """
+    from app.gateway.app import _iter_store_items
+
+    page_a = [SimpleNamespace(key=f"t{i}", value={"metadata": {}}) for i in range(2)]
+    page_b = [SimpleNamespace(key=f"t{i + 2}", value={"metadata": {}}) for i in range(2)]
+    page_c: list = []  # short page → loop terminates
+
+    store = AsyncMock()
+    store.asearch = AsyncMock(side_effect=[page_a, page_b, page_c])
+
+    async def _collect():
+        return [item.key async for item in _iter_store_items(store, ("threads",), page_size=2)]
+
+    keys = asyncio.run(_collect())
+    assert keys == ["t0", "t1", "t2", "t3"]
+    # Three asearch calls: full batch, full batch, empty terminator
+    assert store.asearch.await_count == 3
+
+
+def test_iter_store_items_terminates_on_short_page():
+    """A short page (len < page_size) ends the loop without an extra call."""
+    from app.gateway.app import _iter_store_items
+
+    page = [SimpleNamespace(key=f"t{i}", value={}) for i in range(3)]
+    store = AsyncMock()
+    store.asearch = AsyncMock(return_value=page)
+
+    async def _collect():
+        return [item.key async for item in _iter_store_items(store, ("threads",), page_size=10)]
+
+    keys = asyncio.run(_collect())
+    assert keys == ["t0", "t1", "t2"]
+    # Only one call — no terminator probe needed because len(batch) < page_size
+    assert store.asearch.await_count == 1
@@ -0,0 +1,312 @@
+"""Tests for LangGraph Server auth handler (langgraph_auth.py).
+
+Validates that the LangGraph auth layer enforces the same rules as Gateway:
+  cookie → JWT decode → DB lookup → token_version check → owner filter
+"""
+
+import asyncio
+import os
+from datetime import timedelta
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+from uuid import uuid4
+
+import pytest
+
+os.environ.setdefault("AUTH_JWT_SECRET", "test-secret-key-for-langgraph-auth-testing-min-32")
+
+from langgraph_sdk import Auth
+
+from app.gateway.auth.config import AuthConfig, set_auth_config
+from app.gateway.auth.jwt import create_access_token, decode_token
+from app.gateway.auth.models import User
+from app.gateway.langgraph_auth import add_owner_filter, authenticate
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+
+_JWT_SECRET = "test-secret-key-for-langgraph-auth-testing-min-32"
+
+
+@pytest.fixture(autouse=True)
+def _setup_auth_config():
+    set_auth_config(AuthConfig(jwt_secret=_JWT_SECRET))
+    yield
+    set_auth_config(AuthConfig(jwt_secret=_JWT_SECRET))
+
+
+def _req(cookies=None, method="GET", headers=None):
+    return SimpleNamespace(cookies=cookies or {}, method=method, headers=headers or {})
+
+
+def _user(user_id=None, token_version=0):
+    return User(email="test@example.com", password_hash="fakehash", system_role="user", id=user_id or uuid4(), token_version=token_version)
+
+
+def _mock_provider(user=None):
+    p = AsyncMock()
+    p.get_user = AsyncMock(return_value=user)
+    return p
+
+
+# ── @auth.authenticate ───────────────────────────────────────────────────
+
+
+def test_no_cookie_raises_401():
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req()))
+    assert exc.value.status_code == 401
+    assert "Not authenticated" in str(exc.value.detail)
+
+
+def test_invalid_jwt_raises_401():
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req({"access_token": "garbage"})))
+    assert exc.value.status_code == 401
+    assert "Token error" in str(exc.value.detail)
+
+
+def test_expired_jwt_raises_401():
+    token = create_access_token("user-1", expires_delta=timedelta(seconds=-1))
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req({"access_token": token})))
+    assert exc.value.status_code == 401
+
+
+def test_user_not_found_raises_401():
+    token = create_access_token("ghost")
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=_mock_provider(None)):
+        with pytest.raises(Auth.exceptions.HTTPException) as exc:
+            asyncio.run(authenticate(_req({"access_token": token})))
+        assert exc.value.status_code == 401
+        assert "User not found" in str(exc.value.detail)
+
+
+def test_token_version_mismatch_raises_401():
+    user = _user(token_version=2)
+    token = create_access_token(str(user.id), token_version=1)
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=_mock_provider(user)):
+        with pytest.raises(Auth.exceptions.HTTPException) as exc:
+            asyncio.run(authenticate(_req({"access_token": token})))
+        assert exc.value.status_code == 401
+        assert "revoked" in str(exc.value.detail).lower()
+
+
+def test_valid_token_returns_user_id():
+    user = _user(token_version=0)
+    token = create_access_token(str(user.id), token_version=0)
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=_mock_provider(user)):
+        result = asyncio.run(authenticate(_req({"access_token": token})))
+    assert result == str(user.id)
+
+
+def test_valid_token_matching_version():
+    user = _user(token_version=5)
+    token = create_access_token(str(user.id), token_version=5)
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=_mock_provider(user)):
+        result = asyncio.run(authenticate(_req({"access_token": token})))
+    assert result == str(user.id)
+
+
+# ── @auth.authenticate edge cases ────────────────────────────────────────
+
+
+def test_provider_exception_propagates():
+    """Provider raises → should not be swallowed silently."""
+    token = create_access_token("user-1")
+    p = AsyncMock()
+    p.get_user = AsyncMock(side_effect=RuntimeError("DB down"))
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=p):
+        with pytest.raises(RuntimeError, match="DB down"):
+            asyncio.run(authenticate(_req({"access_token": token})))
+
+
+def test_jwt_missing_ver_defaults_to_zero():
+    """JWT without 'ver' claim → decoded as ver=0, matches user with token_version=0."""
+    import jwt as pyjwt
+
+    uid = str(uuid4())
+    raw = pyjwt.encode({"sub": uid, "exp": 9999999999, "iat": 1000000000}, _JWT_SECRET, algorithm="HS256")
+    user = _user(user_id=uid, token_version=0)
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=_mock_provider(user)):
+        result = asyncio.run(authenticate(_req({"access_token": raw})))
+    assert result == uid
+
+
+def test_jwt_missing_ver_rejected_when_user_version_nonzero():
+    """JWT without 'ver' (defaults 0) vs user with token_version=1 → 401."""
+    import jwt as pyjwt
+
+    uid = str(uuid4())
+    raw = pyjwt.encode({"sub": uid, "exp": 9999999999, "iat": 1000000000}, _JWT_SECRET, algorithm="HS256")
+    user = _user(user_id=uid, token_version=1)
+    with patch("app.gateway.langgraph_auth.get_local_provider", return_value=_mock_provider(user)):
+        with pytest.raises(Auth.exceptions.HTTPException) as exc:
+            asyncio.run(authenticate(_req({"access_token": raw})))
+        assert exc.value.status_code == 401
+
+
+def test_wrong_secret_raises_401():
+    """Token signed with different secret → 401."""
+    import jwt as pyjwt
+
+    raw = pyjwt.encode({"sub": "user-1", "exp": 9999999999, "ver": 0}, "wrong-secret-that-is-long-enough-32chars!", algorithm="HS256")
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req({"access_token": raw})))
+    assert exc.value.status_code == 401
+
+
+# ── @auth.on (owner filter) ──────────────────────────────────────────────
+
+
+class _FakeUser:
+    """Minimal BaseUser-compatible object without langgraph_api.config dependency."""
+
+    def __init__(self, identity: str):
+        self.identity = identity
+        self.is_authenticated = True
+        self.display_name = identity
+
+
+def _make_ctx(user_id):
+    return Auth.types.AuthContext(resource="threads", action="create", user=_FakeUser(user_id), permissions=[])
+
+
+def test_filter_injects_user_id():
+    value = {}
+    asyncio.run(add_owner_filter(_make_ctx("user-a"), value))
+    assert value["metadata"]["owner_id"] == "user-a"
+
+
+def test_filter_preserves_existing_metadata():
+    value = {"metadata": {"title": "hello"}}
+    asyncio.run(add_owner_filter(_make_ctx("user-a"), value))
+    assert value["metadata"]["owner_id"] == "user-a"
+    assert value["metadata"]["title"] == "hello"
+
+
+def test_filter_returns_user_id_dict():
+    result = asyncio.run(add_owner_filter(_make_ctx("user-x"), {}))
+    assert result == {"owner_id": "user-x"}
+
+
+def test_filter_read_write_consistency():
+    value = {}
+    filter_dict = asyncio.run(add_owner_filter(_make_ctx("user-1"), value))
+    assert value["metadata"]["owner_id"] == filter_dict["owner_id"]
+
+
+def test_different_users_different_filters():
+    f_a = asyncio.run(add_owner_filter(_make_ctx("a"), {}))
+    f_b = asyncio.run(add_owner_filter(_make_ctx("b"), {}))
+    assert f_a["owner_id"] != f_b["owner_id"]
+
+
+def test_filter_overrides_conflicting_user_id():
+    """If value already has a different user_id in metadata, it gets overwritten."""
+    value = {"metadata": {"owner_id": "attacker"}}
+    asyncio.run(add_owner_filter(_make_ctx("real-owner"), value))
+    assert value["metadata"]["owner_id"] == "real-owner"
+
+
+def test_filter_with_empty_metadata():
+    """Explicit empty metadata dict is fine."""
+    value = {"metadata": {}}
+    result = asyncio.run(add_owner_filter(_make_ctx("user-z"), value))
+    assert value["metadata"]["owner_id"] == "user-z"
+    assert result == {"owner_id": "user-z"}
+
+
+# ── Gateway parity ───────────────────────────────────────────────────────
+
+
+def test_shared_jwt_secret():
+    token = create_access_token("user-1", token_version=3)
+    payload = decode_token(token)
+    from app.gateway.auth.errors import TokenError
+
+    assert not isinstance(payload, TokenError)
+    assert payload.sub == "user-1"
+    assert payload.ver == 3
+
+
+def test_langgraph_json_has_auth_path():
+    import json
+
+    config = json.loads((Path(__file__).parent.parent / "langgraph.json").read_text())
+    assert "auth" in config
+    assert "langgraph_auth" in config["auth"]["path"]
+
+
+def test_auth_handler_has_both_layers():
+    from app.gateway.langgraph_auth import auth
+
+    assert auth._authenticate_handler is not None
+    assert len(auth._global_handlers) == 1
+
+
+# ── CSRF in LangGraph auth ──────────────────────────────────────────────
+
+
+def test_csrf_get_no_check():
+    """GET requests skip CSRF — should proceed to JWT validation."""
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req(method="GET")))
+    # Rejected by missing cookie, NOT by CSRF
+    assert exc.value.status_code == 401
+    assert "Not authenticated" in str(exc.value.detail)
+
+
+def test_csrf_post_missing_token():
+    """POST without CSRF token → 403."""
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req(method="POST", cookies={"access_token": "some-jwt"})))
+    assert exc.value.status_code == 403
+    assert "CSRF token missing" in str(exc.value.detail)
+
+
+def test_csrf_post_mismatched_token():
+    """POST with mismatched CSRF tokens → 403."""
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(
+            authenticate(
+                _req(
+                    method="POST",
+                    cookies={"access_token": "some-jwt", "csrf_token": "real-token"},
+                    headers={"x-csrf-token": "wrong-token"},
+                )
+            )
+        )
+    assert exc.value.status_code == 403
+    assert "mismatch" in str(exc.value.detail)
+
+
+def test_csrf_post_matching_token_proceeds_to_jwt():
+    """POST with matching CSRF tokens passes CSRF check, then fails on JWT."""
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(
+            authenticate(
+                _req(
+                    method="POST",
+                    cookies={"access_token": "garbage", "csrf_token": "same-token"},
+                    headers={"x-csrf-token": "same-token"},
+                )
+            )
+        )
+    # Past CSRF, rejected by JWT decode
+    assert exc.value.status_code == 401
+    assert "Token error" in str(exc.value.detail)
+
+
+def test_csrf_put_requires_token():
+    """PUT also requires CSRF."""
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req(method="PUT", cookies={"access_token": "jwt"})))
+    assert exc.value.status_code == 403
+
+
+def test_csrf_delete_requires_token():
+    """DELETE also requires CSRF."""
+    with pytest.raises(Auth.exceptions.HTTPException) as exc:
+        asyncio.run(authenticate(_req(method="DELETE", cookies={"access_token": "jwt"})))
+    assert exc.value.status_code == 403
@@ -0,0 +1,465 @@
+"""Cross-user isolation tests — non-negotiable safety gate.
+
+Mirrors TC-API-17..20 from backend/docs/AUTH_TEST_PLAN.md. A failure
+here means users can see each other's data; PR must not merge.
+
+Architecture note
+-----------------
+These tests bypass the HTTP layer and exercise the storage-layer
+owner filter directly by switching the ``user_context`` contextvar
+between two users. The safety property under test is:
+
+  After a repository write with owner_id=A, a subsequent read with
+  owner_id=B must not return the row, and vice versa.
+
+The HTTP layer is covered by test_auth_middleware.py, which proves
+that a request cookie reaches the ``set_current_user`` call. Together
+the two suites prove the full chain:
+
+  cookie → middleware → contextvar → repository → isolation
+
+Every test in this file opts out of the autouse contextvar fixture
+(``@pytest.mark.no_auto_user``) so it can set the contextvar to the
+specific users it cares about.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from deerflow.runtime.user_context import (
+    reset_current_user,
+    set_current_user,
+)
+
+USER_A = SimpleNamespace(id="user-a", email="a@test.local")
+USER_B = SimpleNamespace(id="user-b", email="b@test.local")
+
+
+async def _make_engines(tmp_path):
+    """Initialize the shared engine against a per-test SQLite DB.
+
+    Returns a cleanup coroutine the caller should await at the end.
+    """
+    from deerflow.persistence.engine import close_engine, init_engine
+
+    url = f"sqlite+aiosqlite:///{tmp_path / 'isolation.db'}"
+    await init_engine("sqlite", url=url, sqlite_dir=str(tmp_path))
+    return close_engine
+
+
+def _as_user(user):
+    """Context manager-like helper that set/reset the contextvar."""
+
+    class _Ctx:
+        def __enter__(self):
+            self._token = set_current_user(user)
+            return user
+
+        def __exit__(self, *exc):
+            reset_current_user(self._token)
+
+    return _Ctx()
+
+
+# ── TC-API-17 — threads_meta isolation ────────────────────────────────────
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_thread_meta_cross_user_isolation(tmp_path):
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.thread_meta import ThreadMetaRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = ThreadMetaRepository(get_session_factory())
+
+        # User A creates a thread.
+        with _as_user(USER_A):
+            await repo.create("t-alpha", display_name="A's private thread")
+
+        # User B creates a thread.
+        with _as_user(USER_B):
+            await repo.create("t-beta", display_name="B's private thread")
+
+        # User A must see only A's thread.
+        with _as_user(USER_A):
+            a_view = await repo.get("t-alpha")
+            assert a_view is not None
+            assert a_view["display_name"] == "A's private thread"
+
+            # CRITICAL: User A must NOT see B's thread.
+            leaked = await repo.get("t-beta")
+            assert leaked is None, f"User A leaked User B's thread: {leaked}"
+
+            # Search should only return A's threads.
+            results = await repo.search()
+            assert [r["thread_id"] for r in results] == ["t-alpha"]
+
+        # User B must see only B's thread.
+        with _as_user(USER_B):
+            b_view = await repo.get("t-beta")
+            assert b_view is not None
+            assert b_view["display_name"] == "B's private thread"
+
+            leaked = await repo.get("t-alpha")
+            assert leaked is None, f"User B leaked User A's thread: {leaked}"
+
+            results = await repo.search()
+            assert [r["thread_id"] for r in results] == ["t-beta"]
+    finally:
+        await cleanup()
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_thread_meta_cross_user_mutation_denied(tmp_path):
+    """User B cannot update or delete a thread owned by User A."""
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.thread_meta import ThreadMetaRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = ThreadMetaRepository(get_session_factory())
+
+        with _as_user(USER_A):
+            await repo.create("t-alpha", display_name="original")
+
+        # User B tries to rename A's thread — must be a no-op.
+        with _as_user(USER_B):
+            await repo.update_display_name("t-alpha", "hacked")
+
+        # Verify the row is unchanged from A's perspective.
+        with _as_user(USER_A):
+            row = await repo.get("t-alpha")
+            assert row is not None
+            assert row["display_name"] == "original"
+
+        # User B tries to delete A's thread — must be a no-op.
+        with _as_user(USER_B):
+            await repo.delete("t-alpha")
+
+        # A's thread still exists.
+        with _as_user(USER_A):
+            row = await repo.get("t-alpha")
+            assert row is not None
+    finally:
+        await cleanup()
+
+
+# ── TC-API-18 — runs isolation ────────────────────────────────────────────
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_runs_cross_user_isolation(tmp_path):
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.run import RunRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = RunRepository(get_session_factory())
+
+        with _as_user(USER_A):
+            await repo.put("run-a1", thread_id="t-alpha")
+            await repo.put("run-a2", thread_id="t-alpha")
+
+        with _as_user(USER_B):
+            await repo.put("run-b1", thread_id="t-beta")
+
+        # User A must see only A's runs.
+        with _as_user(USER_A):
+            r = await repo.get("run-a1")
+            assert r is not None
+            assert r["run_id"] == "run-a1"
+
+            leaked = await repo.get("run-b1")
+            assert leaked is None, "User A leaked User B's run"
+
+            a_runs = await repo.list_by_thread("t-alpha")
+            assert {r["run_id"] for r in a_runs} == {"run-a1", "run-a2"}
+
+            # Listing B's thread from A's perspective: empty
+            empty = await repo.list_by_thread("t-beta")
+            assert empty == []
+
+        # User B must see only B's runs.
+        with _as_user(USER_B):
+            leaked = await repo.get("run-a1")
+            assert leaked is None, "User B leaked User A's run"
+
+            b_runs = await repo.list_by_thread("t-beta")
+            assert [r["run_id"] for r in b_runs] == ["run-b1"]
+    finally:
+        await cleanup()
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_runs_cross_user_delete_denied(tmp_path):
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.run import RunRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = RunRepository(get_session_factory())
+
+        with _as_user(USER_A):
+            await repo.put("run-a1", thread_id="t-alpha")
+
+        # User B tries to delete A's run — no-op.
+        with _as_user(USER_B):
+            await repo.delete("run-a1")
+
+        # A's run still exists.
+        with _as_user(USER_A):
+            row = await repo.get("run-a1")
+            assert row is not None
+    finally:
+        await cleanup()
+
+
+# ── TC-API-19 — run_events isolation (CRITICAL: content leak) ─────────────
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_run_events_cross_user_isolation(tmp_path):
+    """run_events holds raw conversation content — most sensitive leak vector."""
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.runtime.events.store.db import DbRunEventStore
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        store = DbRunEventStore(get_session_factory())
+
+        with _as_user(USER_A):
+            await store.put(
+                thread_id="t-alpha",
+                run_id="run-a1",
+                event_type="human_message",
+                category="message",
+                content="User A private question",
+            )
+            await store.put(
+                thread_id="t-alpha",
+                run_id="run-a1",
+                event_type="ai_message",
+                category="message",
+                content="User A private answer",
+            )
+
+        with _as_user(USER_B):
+            await store.put(
+                thread_id="t-beta",
+                run_id="run-b1",
+                event_type="human_message",
+                category="message",
+                content="User B private question",
+            )
+
+        # User A must see only A's events — CRITICAL.
+        with _as_user(USER_A):
+            msgs = await store.list_messages("t-alpha")
+            contents = [m["content"] for m in msgs]
+            assert "User A private question" in contents
+            assert "User A private answer" in contents
+            # CRITICAL: User B's content must not appear.
+            assert "User B private question" not in contents
+
+            # Attempt to read B's thread by guessing thread_id.
+            leaked = await store.list_messages("t-beta")
+            assert leaked == [], f"User A leaked User B's messages: {leaked}"
+
+            leaked_events = await store.list_events("t-beta", "run-b1")
+            assert leaked_events == [], "User A leaked User B's events"
+
+            # count_messages must also be zero for B's thread from A's view.
+            count = await store.count_messages("t-beta")
+            assert count == 0
+
+        # User B must see only B's events.
+        with _as_user(USER_B):
+            msgs = await store.list_messages("t-beta")
+            contents = [m["content"] for m in msgs]
+            assert "User B private question" in contents
+            assert "User A private question" not in contents
+            assert "User A private answer" not in contents
+
+            count = await store.count_messages("t-alpha")
+            assert count == 0
+    finally:
+        await cleanup()
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_run_events_cross_user_delete_denied(tmp_path):
+    """User B cannot delete User A's event stream."""
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.runtime.events.store.db import DbRunEventStore
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        store = DbRunEventStore(get_session_factory())
+
+        with _as_user(USER_A):
+            await store.put(
+                thread_id="t-alpha",
+                run_id="run-a1",
+                event_type="human_message",
+                category="message",
+                content="hello",
+            )
+
+        # User B tries to wipe A's thread events.
+        with _as_user(USER_B):
+            removed = await store.delete_by_thread("t-alpha")
+            assert removed == 0, f"User B deleted {removed} of User A's events"
+
+        # A's events still exist.
+        with _as_user(USER_A):
+            count = await store.count_messages("t-alpha")
+            assert count == 1
+    finally:
+        await cleanup()
+
+
+# ── TC-API-20 — feedback isolation ────────────────────────────────────────
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_feedback_cross_user_isolation(tmp_path):
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.feedback import FeedbackRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = FeedbackRepository(get_session_factory())
+
+        # User A submits positive feedback.
+        with _as_user(USER_A):
+            a_feedback = await repo.create(
+                run_id="run-a1",
+                thread_id="t-alpha",
+                rating=1,
+                comment="A liked this",
+            )
+
+        # User B submits negative feedback.
+        with _as_user(USER_B):
+            b_feedback = await repo.create(
+                run_id="run-b1",
+                thread_id="t-beta",
+                rating=-1,
+                comment="B disliked this",
+            )
+
+        # User A must see only A's feedback.
+        with _as_user(USER_A):
+            retrieved = await repo.get(a_feedback["feedback_id"])
+            assert retrieved is not None
+            assert retrieved["comment"] == "A liked this"
+
+            # CRITICAL: cannot read B's feedback by id.
+            leaked = await repo.get(b_feedback["feedback_id"])
+            assert leaked is None, "User A leaked User B's feedback"
+
+            # list_by_run for B's run must be empty.
+            empty = await repo.list_by_run("t-beta", "run-b1")
+            assert empty == []
+
+        # User B must see only B's feedback.
+        with _as_user(USER_B):
+            leaked = await repo.get(a_feedback["feedback_id"])
+            assert leaked is None, "User B leaked User A's feedback"
+
+            b_list = await repo.list_by_run("t-beta", "run-b1")
+            assert len(b_list) == 1
+            assert b_list[0]["comment"] == "B disliked this"
+    finally:
+        await cleanup()
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_feedback_cross_user_delete_denied(tmp_path):
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.feedback import FeedbackRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = FeedbackRepository(get_session_factory())
+
+        with _as_user(USER_A):
+            fb = await repo.create(run_id="run-a1", thread_id="t-alpha", rating=1)
+
+        # User B tries to delete A's feedback — must return False (no-op).
+        with _as_user(USER_B):
+            deleted = await repo.delete(fb["feedback_id"])
+            assert deleted is False, "User B deleted User A's feedback"
+
+        # A's feedback still retrievable.
+        with _as_user(USER_A):
+            row = await repo.get(fb["feedback_id"])
+            assert row is not None
+    finally:
+        await cleanup()
+
+
+# ── Regression: AUTO sentinel without contextvar must raise ───────────────
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_repository_without_context_raises(tmp_path):
+    """Defense-in-depth: calling repo methods without a user context errors."""
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.thread_meta import ThreadMetaRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = ThreadMetaRepository(get_session_factory())
+        # Contextvar is explicitly unset under @pytest.mark.no_auto_user.
+        with pytest.raises(RuntimeError, match="no user context is set"):
+            await repo.get("anything")
+    finally:
+        await cleanup()
+
+
+# ── Escape hatch: explicit owner_id=None bypasses filter (for migration) ──
+
+
+@pytest.mark.anyio
+@pytest.mark.no_auto_user
+async def test_explicit_none_bypasses_filter(tmp_path):
+    """Migration scripts pass owner_id=None to see all rows regardless of owner."""
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.thread_meta import ThreadMetaRepository
+
+    cleanup = await _make_engines(tmp_path)
+    try:
+        repo = ThreadMetaRepository(get_session_factory())
+
+        # Seed data as two different users.
+        with _as_user(USER_A):
+            await repo.create("t-alpha")
+        with _as_user(USER_B):
+            await repo.create("t-beta")
+
+        # Migration-style read: no contextvar, explicit None bypass.
+        all_rows = await repo.search(owner_id=None)
+        thread_ids = {r["thread_id"] for r in all_rows}
+        assert thread_ids == {"t-alpha", "t-beta"}
+
+        # Explicit get with None does not apply the filter either.
+        row_a = await repo.get("t-alpha", owner_id=None)
+        assert row_a is not None
+        row_b = await repo.get("t-beta", owner_id=None)
+        assert row_b is not None
+    finally:
+        await cleanup()
@@ -46,7 +46,9 @@ def test_generate_suggestions_parses_and_limits(monkeypatch):
    fake_model.ainvoke = AsyncMock(return_value=MagicMock(content='```json\n["Q1", "Q2", "Q3", "Q4"]\n```'))
    monkeypatch.setattr(suggestions, "create_chat_model", lambda **kwargs: fake_model)

-    result = asyncio.run(suggestions.generate_suggestions("t1", req))
+    # Bypass the require_permission decorator (which needs request +
+    # thread_meta_repo) — these tests cover the parsing logic.
+    result = asyncio.run(suggestions.generate_suggestions.__wrapped__("t1", req, request=None))

    assert result.suggestions == ["Q1", "Q2", "Q3"]
    fake_model.ainvoke.assert_awaited_once()
@@ -66,7 +68,9 @@ def test_generate_suggestions_parses_list_block_content(monkeypatch):
    fake_model.ainvoke = AsyncMock(return_value=MagicMock(content=[{"type": "text", "text": '```json\n["Q1", "Q2"]\n```'}]))
    monkeypatch.setattr(suggestions, "create_chat_model", lambda **kwargs: fake_model)

-    result = asyncio.run(suggestions.generate_suggestions("t1", req))
+    # Bypass the require_permission decorator (which needs request +
+    # thread_meta_repo) — these tests cover the parsing logic.
+    result = asyncio.run(suggestions.generate_suggestions.__wrapped__("t1", req, request=None))

    assert result.suggestions == ["Q1", "Q2"]
    fake_model.ainvoke.assert_awaited_once()
@@ -86,7 +90,9 @@ def test_generate_suggestions_parses_output_text_block_content(monkeypatch):
    fake_model.ainvoke = AsyncMock(return_value=MagicMock(content=[{"type": "output_text", "text": '```json\n["Q1", "Q2"]\n```'}]))
    monkeypatch.setattr(suggestions, "create_chat_model", lambda **kwargs: fake_model)

-    result = asyncio.run(suggestions.generate_suggestions("t1", req))
+    # Bypass the require_permission decorator (which needs request +
+    # thread_meta_repo) — these tests cover the parsing logic.
+    result = asyncio.run(suggestions.generate_suggestions.__wrapped__("t1", req, request=None))

    assert result.suggestions == ["Q1", "Q2"]
    fake_model.ainvoke.assert_awaited_once()
@@ -103,6 +109,8 @@ def test_generate_suggestions_returns_empty_on_model_error(monkeypatch):
    fake_model.ainvoke = AsyncMock(side_effect=RuntimeError("boom"))
    monkeypatch.setattr(suggestions, "create_chat_model", lambda **kwargs: fake_model)

-    result = asyncio.run(suggestions.generate_suggestions("t1", req))
+    # Bypass the require_permission decorator (which needs request +
+    # thread_meta_repo) — these tests cover the parsing logic.
+    result = asyncio.run(suggestions.generate_suggestions.__wrapped__("t1", req, request=None))

    assert result.suggestions == []
@@ -104,10 +104,51 @@ class TestThreadMetaRepository:
    @pytest.mark.anyio
    async def test_check_access_no_owner_allows_all(self, tmp_path):
        repo = await _make_repo(tmp_path)
-        await repo.create("t1")  # owner_id=None
+        # Explicit owner_id=None to bypass the new AUTO default that
+        # would otherwise pick up the test user from the autouse fixture.
+        await repo.create("t1", owner_id=None)
        assert await repo.check_access("t1", "anyone") is True
        await _cleanup()

+    @pytest.mark.anyio
+    async def test_check_access_strict_missing_row_denied(self, tmp_path):
+        """require_existing=True flips the missing-row case to *denied*.
+
+        Closes the delete-idempotence cross-user gap: after a thread is
+        deleted, the row is gone, and the permissive default would let any
+        caller "claim" it as untracked. The strict mode demands a row.
+        """
+        repo = await _make_repo(tmp_path)
+        assert await repo.check_access("never-existed", "user1", require_existing=True) is False
+        await _cleanup()
+
+    @pytest.mark.anyio
+    async def test_check_access_strict_owner_match_allowed(self, tmp_path):
+        repo = await _make_repo(tmp_path)
+        await repo.create("t1", owner_id="user1")
+        assert await repo.check_access("t1", "user1", require_existing=True) is True
+        await _cleanup()
+
+    @pytest.mark.anyio
+    async def test_check_access_strict_owner_mismatch_denied(self, tmp_path):
+        repo = await _make_repo(tmp_path)
+        await repo.create("t1", owner_id="user1")
+        assert await repo.check_access("t1", "user2", require_existing=True) is False
+        await _cleanup()
+
+    @pytest.mark.anyio
+    async def test_check_access_strict_null_owner_still_allowed(self, tmp_path):
+        """Even in strict mode, a row with NULL owner_id stays shared.
+
+        The strict flag tightens the *missing row* case, not the *shared
+        row* case — legacy pre-auth rows that survived a clean migration
+        without an owner are still everyone's.
+        """
+        repo = await _make_repo(tmp_path)
+        await repo.create("t1", owner_id=None)
+        assert await repo.check_access("t1", "anyone", require_existing=True) is True
+        await _cleanup()
+
    @pytest.mark.anyio
    async def test_update_status(self, tmp_path):
        repo = await _make_repo(tmp_path)
@@ -1,7 +1,8 @@
 from unittest.mock import patch

 import pytest
-from fastapi import FastAPI, HTTPException
+from _router_auth_helpers import make_authed_test_app
+from fastapi import HTTPException
 from fastapi.testclient import TestClient

 from app.gateway.routers import threads
@@ -54,7 +55,7 @@ def test_delete_thread_route_cleans_thread_directory(tmp_path):
    paths.sandbox_work_dir("thread-route").mkdir(parents=True, exist_ok=True)
    (paths.sandbox_work_dir("thread-route") / "notes.txt").write_text("hello", encoding="utf-8")

-    app = FastAPI()
+    app = make_authed_test_app()
    app.include_router(threads.router)

    with patch("app.gateway.routers.threads.get_paths", return_value=paths):
@@ -69,7 +70,7 @@ def test_delete_thread_route_cleans_thread_directory(tmp_path):
 def test_delete_thread_route_rejects_invalid_thread_id(tmp_path):
    paths = Paths(tmp_path)

-    app = FastAPI()
+    app = make_authed_test_app()
    app.include_router(threads.router)

    with patch("app.gateway.routers.threads.get_paths", return_value=paths):
@@ -82,7 +83,7 @@ def test_delete_thread_route_rejects_invalid_thread_id(tmp_path):
 def test_delete_thread_route_returns_422_for_route_safe_invalid_id(tmp_path):
    paths = Paths(tmp_path)

-    app = FastAPI()
+    app = make_authed_test_app()
    app.include_router(threads.router)

    with patch("app.gateway.routers.threads.get_paths", return_value=paths):
@@ -107,3 +108,34 @@ def test_delete_thread_data_returns_generic_500_error(tmp_path):
    assert exc_info.value.detail == "Failed to delete local thread data."
    assert "/secret/path" not in exc_info.value.detail
    log_exception.assert_called_once_with("Failed to delete thread data for %s", "thread-cleanup")
+
+
+# ── Server-reserved metadata key stripping ──────────────────────────────────
+
+
+def test_strip_reserved_metadata_removes_owner_id():
+    """Client-supplied owner_id is dropped to prevent reflection attacks."""
+    out = threads._strip_reserved_metadata({"owner_id": "victim-id", "title": "ok"})
+    assert out == {"title": "ok"}
+
+
+def test_strip_reserved_metadata_removes_user_id():
+    """user_id is also reserved (defense in depth for any future use)."""
+    out = threads._strip_reserved_metadata({"user_id": "victim-id", "title": "ok"})
+    assert out == {"title": "ok"}
+
+
+def test_strip_reserved_metadata_passes_through_safe_keys():
+    """Non-reserved keys are preserved verbatim."""
+    md = {"title": "ok", "tags": ["a", "b"], "custom": {"x": 1}}
+    assert threads._strip_reserved_metadata(md) == md
+
+
+def test_strip_reserved_metadata_empty_input():
+    """Empty / None metadata returns same object — no crash."""
+    assert threads._strip_reserved_metadata({}) == {}
+
+
+def test_strip_reserved_metadata_strips_both_simultaneously():
+    out = threads._strip_reserved_metadata({"owner_id": "x", "user_id": "y", "keep": "me"})
+    assert out == {"keep": "me"}
@@ -4,6 +4,7 @@ from io import BytesIO
 from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock, patch

+from _router_auth_helpers import call_unwrapped
 from fastapi import UploadFile

 from app.gateway.routers import uploads
@@ -25,7 +26,7 @@ def test_upload_files_writes_thread_storage_and_skips_local_sandbox_sync(tmp_pat
        patch.object(uploads, "get_sandbox_provider", return_value=provider),
    ):
        file = UploadFile(filename="notes.txt", file=BytesIO(b"hello uploads"))
-        result = asyncio.run(uploads.upload_files("thread-local", files=[file]))
+        result = asyncio.run(call_unwrapped(uploads.upload_files, "thread-local", request=MagicMock(), files=[file]))

    assert result.success is True
    assert len(result.files) == 1
@@ -107,7 +108,7 @@ def test_upload_files_syncs_non_local_sandbox_and_marks_markdown_file(tmp_path):
        patch.object(uploads, "convert_file_to_markdown", AsyncMock(side_effect=fake_convert)),
    ):
        file = UploadFile(filename="report.pdf", file=BytesIO(b"pdf-bytes"))
-        result = asyncio.run(uploads.upload_files("thread-aio", files=[file]))
+        result = asyncio.run(call_unwrapped(uploads.upload_files, "thread-aio", request=MagicMock(), files=[file]))

    assert result.success is True
    assert len(result.files) == 1
@@ -146,7 +147,7 @@ def test_upload_files_makes_non_local_files_sandbox_writable(tmp_path):
        patch.object(uploads, "_make_file_sandbox_writable") as make_writable,
    ):
        file = UploadFile(filename="report.pdf", file=BytesIO(b"pdf-bytes"))
-        result = asyncio.run(uploads.upload_files("thread-aio", files=[file]))
+        result = asyncio.run(call_unwrapped(uploads.upload_files, "thread-aio", request=MagicMock(), files=[file]))

    assert result.success is True
    make_writable.assert_any_call(thread_uploads_dir / "report.pdf")
@@ -170,7 +171,7 @@ def test_upload_files_does_not_adjust_permissions_for_local_sandbox(tmp_path):
        patch.object(uploads, "_make_file_sandbox_writable") as make_writable,
    ):
        file = UploadFile(filename="notes.txt", file=BytesIO(b"hello uploads"))
-        result = asyncio.run(uploads.upload_files("thread-local", files=[file]))
+        result = asyncio.run(call_unwrapped(uploads.upload_files, "thread-local", request=MagicMock(), files=[file]))

    assert result.success is True
    make_writable.assert_not_called()
@@ -221,13 +222,13 @@ def test_upload_files_rejects_dotdot_and_dot_filenames(tmp_path):
        # These filenames must be rejected outright
        for bad_name in ["..", "."]:
            file = UploadFile(filename=bad_name, file=BytesIO(b"data"))
-            result = asyncio.run(uploads.upload_files("thread-local", files=[file]))
+            result = asyncio.run(call_unwrapped(uploads.upload_files, "thread-local", request=MagicMock(), files=[file]))
            assert result.success is True
            assert result.files == [], f"Expected no files for unsafe filename {bad_name!r}"

        # Path-traversal prefixes are stripped to the basename and accepted safely
        file = UploadFile(filename="../etc/passwd", file=BytesIO(b"data"))
-        result = asyncio.run(uploads.upload_files("thread-local", files=[file]))
+        result = asyncio.run(call_unwrapped(uploads.upload_files, "thread-local", request=MagicMock(), files=[file]))
        assert result.success is True
        assert len(result.files) == 1
        assert result.files[0]["filename"] == "passwd"
@@ -243,7 +244,7 @@ def test_delete_uploaded_file_removes_generated_markdown_companion(tmp_path):
    (thread_uploads_dir / "report.md").write_text("converted", encoding="utf-8")

    with patch.object(uploads, "get_uploads_dir", return_value=thread_uploads_dir):
-        result = asyncio.run(uploads.delete_uploaded_file("thread-aio", "report.pdf"))
+        result = asyncio.run(call_unwrapped(uploads.delete_uploaded_file, "thread-aio", "report.pdf", request=MagicMock()))

    assert result == {"success": True, "message": "Deleted report.pdf"}
    assert not (thread_uploads_dir / "report.pdf").exists()
@@ -0,0 +1,69 @@
+"""Tests for runtime.user_context — contextvar three-state semantics.
+
+These tests opt out of the autouse contextvar fixture (added in
+commit 6) because they explicitly test the cases where the contextvar
+is set or unset.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from deerflow.runtime.user_context import (
+    CurrentUser,
+    get_current_user,
+    require_current_user,
+    reset_current_user,
+    set_current_user,
+)
+
+
+@pytest.mark.no_auto_user
+def test_default_is_none():
+    """Before any set, contextvar returns None."""
+    assert get_current_user() is None
+
+
+@pytest.mark.no_auto_user
+def test_set_and_reset_roundtrip():
+    """set_current_user returns a token that reset restores."""
+    user = SimpleNamespace(id="user-1")
+    token = set_current_user(user)
+    try:
+        assert get_current_user() is user
+    finally:
+        reset_current_user(token)
+    assert get_current_user() is None
+
+
+@pytest.mark.no_auto_user
+def test_require_current_user_raises_when_unset():
+    """require_current_user raises RuntimeError if contextvar is unset."""
+    assert get_current_user() is None
+    with pytest.raises(RuntimeError, match="without user context"):
+        require_current_user()
+
+
+@pytest.mark.no_auto_user
+def test_require_current_user_returns_user_when_set():
+    """require_current_user returns the user when contextvar is set."""
+    user = SimpleNamespace(id="user-2")
+    token = set_current_user(user)
+    try:
+        assert require_current_user() is user
+    finally:
+        reset_current_user(token)
+
+
+@pytest.mark.no_auto_user
+def test_protocol_accepts_duck_typed():
+    """CurrentUser is a runtime_checkable Protocol matching any .id-bearing object."""
+    user = SimpleNamespace(id="user-3")
+    assert isinstance(user, CurrentUser)
+
+
+@pytest.mark.no_auto_user
+def test_protocol_rejects_no_id():
+    """Objects without .id do not satisfy CurrentUser Protocol."""
+    not_a_user = SimpleNamespace(email="no-id@example.com")
+    assert not isinstance(not_a_user, CurrentUser)