Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

154 KB
Raw Blame
"""
FastAPI application factory for Local Deep Research.

This replaces Flask's app_factory.py as the primary web application entry point.
It mounts Socket.IO as an ASGI sub-app, configures middleware, templates,
static files, and background services.
"""

import ipaddress
import json
import logging
import os
import re
import secrets
import sys
import time
from contextlib import asynccontextmanager
from importlib import resources as importlib_resources
from pathlib import Path

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import (
    HTMLResponse,
    JSONResponse,
    PlainTextResponse,
    RedirectResponse,
)
from loguru import logger
from starlette.middleware.sessions import SessionMiddleware
from starlette.requests import ClientDisconnect

from ..__version__ import __version__
from ..security import get_security_default
from ..security.network_utils import is_ipv6_transition_address
from ..utilities.type_utils import to_bool
from ..utilities.log_utils import InterceptHandler

# ---------------------------------------------------------------------------
# Directories
# ---------------------------------------------------------------------------

try:
    _PACKAGE_DIR = importlib_resources.files("local_deep_research") / "web"
    with importlib_resources.as_file(_PACKAGE_DIR) as _pkg:
        STATIC_DIR = (_pkg / "static").as_posix()
        TEMPLATE_DIR = (_pkg / "templates").as_posix()
except Exception:
    STATIC_DIR = str(Path("static").resolve())
    TEMPLATE_DIR = str(Path("templates").resolve())

# Templates shared across all routers (defined in template_config to avoid circular imports)
from .template_config import (
    templates,
)

# ---------------------------------------------------------------------------
# Branded error pages (404 / 413)
# ---------------------------------------------------------------------------

#: Title/message copy for each status code the branded error page covers.
#: Ports the copy from PR #5424 (Flask's ``app_factory.py::
#: register_error_handlers``, retired by the FastAPI migration in #3299).
_BRANDED_ERROR_COPY: dict[int, tuple[str, str]] = {
    404: (
        "Page not found",
        "The page you're looking for doesn't exist or may have moved.",
    ),
    413: (
        "Request too large",
        "The file or request you sent is larger than the allowed limit.",
    ),
    # Only ``/`` renders this one (``_database_unavailable_page``): the
    # retryable 503 of ``database_unavailable_exception``.
    503: (
        "Temporarily unavailable",
        "Your database is temporarily unavailable. "
        "Please try again in a moment.",
    ),
}


def _render_branded_error_page(
    request: Request,
    status_code: int,
    *,
    title: str | None = None,
    message: str | None = None,
):
    """Render ``templates/pages/error.html`` for a browser-facing error.

    Ports the defensive design of the Flask handler this replaces (PR
    #5424): rendering depends on session data, CSRF token generation, and
    Jinja globals (``url_for``, the frontend-constants injection in
    ``template_config.py``'s ``_LDRTemplates.TemplateResponse``) that are
    not guaranteed to be populated in every environment this can run in —
    most notably, a minimal test harness may not populate ``scope["app"]``
    at all (no ``url_for``), or may not install ``SessionMiddleware`` at
    all (no ``scope["session"]``). A template that itself raises must
    never turn a 404/413 into an unhandled 500, so any failure here is
    swallowed and logged at debug; callers fall back to the previous
    plain-text/JSON response.

    ``title`` and ``message`` replace the copy for ``status_code``. The
    template escapes both.

    Returns the rendered ``Response`` on success, or ``None`` on any
    failure.
    """
    default_title, default_message = _BRANDED_ERROR_COPY.get(
        status_code, ("Something went wrong", "Please try again.")
    )
    title = default_title if title is None else title
    message = default_message if message is None else message
    from ..security.egress.policy import DEFAULT_EGRESS_SCOPE

    # If a session is present -- real or a caller-supplied placeholder
    # dict (see BodySizeLimitMiddleware._send_413) -- render against a
    # *copy* of the scope with a snapshotted "session", never the live
    # SessionMiddleware ``Session`` object. `_LDRTemplates.
    # TemplateResponse` (template_config.py:41) does
    # `getattr(request, "session", None)` unconditionally, and
    # Starlette's `Request.session` property calls
    # `session.mark_accessed()` purely by being *read* -- which alone
    # makes SessionMiddleware add `Vary: Cookie` to the response, before
    # any of the "not in context" guards below even run. A plain dict
    # has no `mark_accessed`, so touching the copy here can never mark
    # the real session accessed or modified, which is what keeps this
    # from ever adding Set-Cookie/Vary either.
    #
    # If there is no session at all (no key in scope -- SessionMiddleware
    # never ran on this scope, e.g. a minimal test harness, or a caller
    # that has not populated one), leave `request` untouched: the
    # `getattr` above then raises the same ``AssertionError`` it always
    # did, caught by this function's own `except` below, and rendering
    # falls back to the plain-text/JSON response exactly as before this
    # session-copy was introduced -- there is no live session object to
    # protect in that case, so there is nothing to fix.
    real_session = request.scope.get("session")
    if hasattr(real_session, "get"):
        scope = dict(request.scope)
        scope["session"] = dict(real_session)
        render_request = Request(scope)
    else:
        render_request = request

    try:
        return templates.TemplateResponse(
            request=render_request,
            name="pages/error.html",
            context={
                "request": render_request,
                "status_code": status_code,
                "error_title": title,
                "error_message": message,
                # error.html is a standalone page (does not extend
                # base.html) and never reads any of these four keys, so
                # any value satisfies the template — but *_LDRTemplates.
                # TemplateResponse* treats a missing key as "go compute
                # the real one": CSRF-token generation (:51, mutates the
                # session copy above -- harmless, but would still cost a
                # `secrets.token_hex` call), a flash-message pop (:58,
                # would drain the *copy*, which is why the real pending
                # flashes still reach the next real page), and — worst —
                # an egress-scope DB lookup for any logged-in user (:145)
                # on every 404/413, including ones DatabaseMiddleware
                # never opens a session for (the session copy still has
                # ``username``, so only supplying this explicitly avoids
                # the DB round trip). Supplying all four here
                # short-circuits every "not in context" guard so none of
                # that work ever runs for an error page.
                "csrf_token": "",
                "get_flashed_messages": lambda *_a, **_k: [],
                "egress_scope": DEFAULT_EGRESS_SCOPE,
                "has_encryption": False,
            },
            status_code=status_code,
        )
    except Exception:
        logger.opt(exception=True).debug(
            "Failed to render branded error page for status {}; falling "
            "back to a plain response",
            status_code,
        )
        return None


def _database_unavailable_page(request: Request, exc: HTTPException):
    """The branded page for ``/``'s retryable 503, or None for the JSON one.

    ``exc`` is ``database_unavailable_exception()``: the user's database
    cannot be checked or opened right now (a rekey sidecar fault such as
    an fd-exhaustion spike). ``/`` is where a browser lands after login,
    and ``/auth/login`` sends every signed-in cookie back to it, so a fault
    that lasts would otherwise leave the browser on a raw JSON body. The
    branded page keeps the status and ``Retry-After``, and its button
    retries ``/``. It renders without a database read and from a copy of
    the session (see ``_render_branded_error_page``), so the session stays
    exactly as the 503 promises. Returns None, so that the caller raises
    ``exc`` for the usual JSON answer, for a caller that asked for JSON or
    when the page cannot be rendered.
    """
    if _is_api_request(request):
        return None
    page = _render_branded_error_page(request, exc.status_code)
    if page is None:
        return None
    for name, value in (exc.headers or {}).items():
        page.headers[name] = value
    return page


# ---------------------------------------------------------------------------
# Secret key (same logic as Flask app_factory)
# ---------------------------------------------------------------------------


def _load_secret_key() -> str:
    """Load or generate a persistent SECRET_KEY for session signing.

    Falling back to an in-memory key on read errors silently invalidates
    every existing session on restart and produces no operator alert,
    so this raises a hard error instead.
    """
    from ..config.paths import get_data_directory

    secret_key_file = Path(get_data_directory()) / ".secret_key"

    from ..security.directory_creation import create_directory

    create_directory(
        secret_key_file.parent, context="secret key file directory"
    )
    new_key = secrets.token_hex(32)
    try:
        fd = os.open(
            # nosemgrep: semgrep.rules.path-traversal-risk, reason: Fixed .secret_key below the operator data root; creation is exclusive with mode 0600
            str(secret_key_file),
            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
            0o600,
        )
        try:
            os.write(fd, new_key.encode())
        finally:
            os.close(fd)
        logger.info("Generated new SECRET_KEY for this installation")
        return new_key
    except FileExistsError:
        # File exists — read it. Any error here is fatal: an ephemeral
        # in-memory key would silently invalidate every existing session
        # on restart and prevent any future restart from being consistent.
        try:
            # nosemgrep: semgrep.rules.path-traversal-risk, reason: Fixed .secret_key below the operator data root; requests cannot select this filename
            with open(secret_key_file, "r", encoding="utf-8") as f:
                key = f.read().strip()
        except Exception as e:
            raise RuntimeError(
                f"Cannot read SECRET_KEY file at {secret_key_file}: {e}. "
                "Fix the file permissions/contents or remove the file to "
                "regenerate (this will invalidate all sessions)."
            ) from e
        # Empty / whitespace-only file is also fatal — itsdangerous would
        # accept it and derive a deterministic signing key from no secret,
        # silently breaking session integrity.
        if not key:
            raise RuntimeError(
                f"SECRET_KEY file at {secret_key_file} is empty. "
                "Delete the file to regenerate a new key (this will "
                "invalidate all existing sessions)."
            )
        return key
    except OSError as e:
        # Cannot write the key file. Same reasoning — refuse rather than
        # silently fall back to a non-persistent key.
        raise RuntimeError(
            f"Cannot write SECRET_KEY file at {secret_key_file}: {e}. "
            "Fix the data directory permissions and retry."
        ) from e


SECRET_KEY = _load_secret_key()


def warn_if_threadpool_exceeds_db_pool(worker_threads: int) -> bool:
    """Warn when the AnyIO worker pool is larger than a user's DB pool.

    Raising ``web.threadpool_max_threads`` above the per-user pool capacity is
    not merely a tuning choice. ``WorkerCleanupAPIRoute`` returns each sync
    route's connections when that request finishes, but every concurrently
    active DB-touching worker can still hold one pool slot. More workers than
    slots therefore permit a burst from one user to exhaust the pool before
    any request reaches its cleanup boundary.

    Below the pool capacity that is harmless, which is why this warns instead
    of failing. Above it, one user's concurrent requests can exhaust their own
    pool, after which every further request waits out ``pool_timeout``.

    Returns True when the warning fired, so it can be tested directly rather
    than only through a lifespan startup.
    """
    from ..database.pool_config import MAX_OVERFLOW, POOL_SIZE

    pool_capacity = POOL_SIZE + MAX_OVERFLOW
    if worker_threads <= pool_capacity:
        return False
    logger.warning(
        "web.threadpool_max_threads ({}) exceeds the per-user database pool "
        "capacity ({} = pool_size {} + max_overflow {}). Concurrent "
        "synchronous routes can each hold one connection, so a single user's "
        "concurrent requests can exhaust their pool and then block for "
        "pool_timeout. Keep this at or below {}.",
        worker_threads,
        pool_capacity,
        POOL_SIZE,
        MAX_OVERFLOW,
        pool_capacity,
    )
    return True


# ---------------------------------------------------------------------------
# Lifespan: startup / shutdown
# ---------------------------------------------------------------------------


@asynccontextmanager
async def lifespan(app: FastAPI):
    """Manage application lifecycle — start/stop background services."""
    # --- Startup ---
    from ..security.process_dump_policy import enforce_process_dump_policy

    # Direct ASGI launches also need the policy before workers or requests.
    enforce_process_dump_policy()
    logger.info(f"Starting Local Deep Research v{__version__}")

    # Capture uvicorn's running event loop so background threads can
    # dispatch Socket.IO emits via run_coroutine_threadsafe. Without
    # this, emits from research workers / log queue silently no-op
    # (asyncio.get_event_loop() in a worker thread doesn't return uvicorn's loop).
    import asyncio as _asyncio
    from .services.socketio_asgi import (
        init_lock,
        log_socketio_cors_policy,
        set_main_loop,
    )

    set_main_loop(_asyncio.get_running_loop())
    # Eagerly create the Socket.IO subscription lock now that the loop is
    # running, so the first connect/subscribe events don't race on lazy init.
    init_lock()
    # Report the WebSocket origin policy here rather than at socketio_asgi
    # import time: that import happens while package logging is still
    # disabled (before config_logger() runs), which silently dropped the
    # allow-all INFO/WARNING. Logging-only, so never let it block startup.
    try:
        log_socketio_cors_policy()
    except Exception:
        logger.exception("Failed to log the Socket.IO CORS policy")

    # Size the AnyIO worker pool that serves every plain `def` route.
    #
    # Starlette runs sync handlers via `anyio.to_thread.run_sync`, whose
    # default CapacityLimiter is 40 threads — and that pool is SHARED with
    # async dependency solving and response validation, so exhausting it
    # degrades async routes too. This app has ~248 sync routes against 65
    # async ones, each sync request holding a worker for its full duration
    # (including a first-call SQLCipher open), and it runs with workers=1,
    # so there is no second process to absorb the overflow. Measured
    # symptom: /api/v1/health went 0.8ms -> 9.8s at 80 concurrent requests,
    # past the 8s Docker healthcheck timeout — i.e. the container reports
    # unhealthy under load rather than merely slow.
    #
    # Left at AnyIO's default unless an operator opts in, so this changes
    # nothing by default: raising it is not free (context-switch overhead,
    # and more threads contend for the same per-user QueuePool), and the
    # right value depends on the deployment's core count and workload. The
    # point is to make an invisible framework default into a deliberate,
    # tunable decision — the migration hazard here is not the number, it is
    # that nobody knows the number exists.
    try:
        from ..settings.env_registry import (
            get_env_setting as _get_env_setting,
        )

        configured = _get_env_setting("web.threadpool_max_threads")
        if configured:
            import anyio.to_thread

            limiter = anyio.to_thread.current_default_thread_limiter()
            previous = limiter.total_tokens
            limiter.total_tokens = int(configured)
            logger.info(
                "AnyIO worker pool resized: {} -> {} threads "
                "(LDR_WEB_THREADPOOL_MAX_THREADS)",
                previous,
                limiter.total_tokens,
            )

            warn_if_threadpool_exceeds_db_pool(limiter.total_tokens)
    except Exception:
        # Never let a tuning knob stop the server from starting.
        logger.exception(
            "Could not apply web.threadpool_max_threads; "
            "continuing with the AnyIO default"
        )

    # Route stdlib loggers through loguru
    for name in ("uvicorn", "uvicorn.access", "uvicorn.error"):
        uv_logger = logging.getLogger(name)
        uv_logger.setLevel(logging.WARNING)
        if not any(isinstance(h, InterceptHandler) for h in uv_logger.handlers):
            uv_logger.addHandler(InterceptHandler())

    ap_logger = logging.getLogger("apscheduler")
    ap_logger.setLevel(logging.WARNING)
    if not any(isinstance(h, InterceptHandler) for h in ap_logger.handlers):
        ap_logger.addHandler(InterceptHandler())

    # Log data location
    from ..config.paths import get_data_directory
    from ..database.encrypted_db import db_manager

    data_dir = get_data_directory()
    logger.info("=" * 60)
    logger.info("DATA STORAGE INFORMATION")
    logger.info("=" * 60)
    logger.info(f"Data directory: {data_dir}")
    logger.info(
        "Databases: Per-user encrypted databases in encrypted_databases/"
    )
    if db_manager.has_encryption:
        logger.info("SECURITY: Databases are encrypted with SQLCipher.")
    else:
        logger.warning(
            "SECURITY NOTICE: SQLCipher is not available - databases are NOT encrypted."
        )
    logger.info("=" * 60)

    # Restrict research_outputs/ (optional plaintext report backups) to this
    # OS account, so a directory left at 0755 by an older release becomes
    # 0700 whether or not any user has report file backups enabled. The
    # function logs its own failure and remedy; FileReportStorage refuses a
    # directory that is not private, so a failure here only disables file
    # backups. Wrapped so it can never block server boot.
    try:
        from ..config.paths import restrict_research_outputs_directory

        restrict_research_outputs_directory()
    except Exception:
        logger.exception("Research outputs directory startup check failed")

    # Surface a cipher misconfiguration that otherwise only shows up as
    # affected users getting "Invalid username or password": a relaxed
    # SQLCipher KDF (test mode) on a deployment that already holds real user
    # databases. No-op on fresh installs and when the effective KDF is at the
    # production floor. Wrapped so a check failure can never block server boot.
    try:
        from ..database.sqlcipher_utils import (
            warn_if_weak_kdf_with_existing_databases,
        )

        if db_manager.has_encryption:
            warn_if_weak_kdf_with_existing_databases(db_manager.data_dir)
    except Exception:
        logger.exception("Weak-KDF startup configuration check failed")

    # Initialize Theme helper
    from .themes import theme_registry

    try:
        static_dir = Path(STATIC_DIR)
        themes_css_path = static_dir / "css" / "themes.css"
        combined_css = theme_registry.get_combined_css()
        # nosemgrep: semgrep.rules.path-traversal-risk, reason: Fixed css/themes.css below the installed package static directory at startup
        themes_css_path.write_text(combined_css, encoding="utf-8")
        logger.debug(
            f"Generated themes.css with {len(theme_registry.themes)} themes"
        )
    except Exception:
        logger.warning("Error generating combined themes.css")

    # Start log queue processor (drains background-thread DB log entries).
    #
    # Wrapped like every other optional startup step in this lifespan (the
    # AnyIO threadpool knob, the weak-KDF check, themes.css). The lifespan is
    # two-tier and an UNGUARDED step that raises produces
    # `lifespan.startup.failed`, so uvicorn never serves at all -- pinned by
    # tests/web/test_lifespan_startup_shutdown.py.
    # `start_log_queue_processor` ends in `threading.Thread(...).start()`,
    # which raises `RuntimeError: can't start new thread` under a container
    # pids / RLIMIT_NPROC ceiling; a best-effort logging daemon must never be
    # the reason the server fails to boot. main guards the same call in
    # `web/app.py::main()` (PR #3488) and the guard was lost in the port.
    # The matching `stop_log_queue_processor()` on the shutdown path is
    # itself wrapped and is a no-op when no daemon ever started, so it stays
    # reachable either way; logging degrades to the shutdown flush.
    from ..utilities.log_utils import start_log_queue_processor

    try:
        start_log_queue_processor()
    except Exception:
        logger.exception(
            "Failed to start log queue processor; continuing without the "
            "background log drain (queued entries flush at shutdown instead)"
        )

    # Start research queue processor — enabled by default in normal app runs,
    # but default-off under pytest so app fixtures don't each spawn a daemon
    # thread. An explicit web.queue_processor.enabled env override still wins
    # (tests that need the processor opt in). Ports #5055 from the retired
    # Flask app_factory to the FastAPI lifespan. The singleton is imported
    # unconditionally (cheap — only .start() spawns the thread) so the
    # shutdown path below can always call .stop().
    from ..settings.env_registry import get_env_setting, registry
    from .queue.processor_v2 import queue_processor

    queue_processor_enabled = get_env_setting(
        "web.queue_processor.enabled", True
    )
    _qp_setting = registry.get_setting_object("web.queue_processor.enabled")
    _qp_env_set = bool(_qp_setting and _qp_setting.is_set)
    if os.getenv("PYTEST_CURRENT_TEST") and not _qp_env_set:
        queue_processor_enabled = False

    if queue_processor_enabled:
        queue_processor.start()
        logger.info("Started research queue processor v2")
    else:
        # Disabling the processor also disables the ONLY drain path for
        # ``pending_operations``: research worker threads that cannot reach
        # the DB directly (e.g. password lookup failed) fall back to
        # ``queue_progress_update`` / ``queue_error_update``, and the only
        # consumer of that queue is ``_drain_pending_operations``, which runs
        # inside the loop started just above. Under Flask a second, always-on
        # ``before_request`` hook drained it too; the FastAPI port has no
        # equivalent. Directly-dispatched research still runs while the
        # processor is off, so a terminal FAILED status raised on that
        # fallback path would be queued and then silently dropped by TTL
        # eviction. Warn rather than start a thread the operator turned off.
        logger.warning(
            "Queue processor v2 disabled — not starting. Queued researches "
            "will not be dispatched, and progress/terminal-status updates "
            "that fall back to the pending-operations queue will not be "
            "persisted (they expire via TTL)."
        )

    # Start news scheduler
    news_scheduler = None
    try:
        from ..settings.env_registry import get_env_setting

        scheduler_enabled = get_env_setting("news.scheduler.enabled", True)
        if scheduler_enabled:
            from ..scheduler.background import get_background_job_scheduler
            from ..settings.manager import SettingsManager

            # Startup-only: lifespan runs once before the server accepts
            # traffic, so blocking here cannot stall in-flight requests.
            settings_manager = SettingsManager()  # allow: sync-in-async
            news_scheduler = get_background_job_scheduler()
            news_scheduler.initialize_with_settings(settings_manager)
            news_scheduler.start()
            logger.info("News scheduler started")
    except Exception:
        logger.exception("Failed to initialize news scheduler")

    # Start connection cleanup scheduler
    cleanup_scheduler = None
    try:
        from .auth.connection_cleanup import start_connection_cleanup_scheduler
        from .auth.session_manager import session_manager

        cleanup_scheduler = start_connection_cleanup_scheduler(
            session_manager, db_manager
        )
    except Exception:
        logger.warning("Failed to start cleanup scheduler")

    # Uvicorn drains requests before entering lifespan shutdown. Its
    # timeout_graceful_shutdown (10s) drain timeout cancels request tasks,
    # then still sends the lifespan shutdown event; it does not cancel
    # this generator at the yield.
    # Compose allows 60s for both phases. Scheduler shutdown can still wait
    # for an in-flight job, so this is an outer grace period, not a bound on
    # each cleanup step. SIGKILL or cancellation of the lifespan itself can
    # skip the code below. An atexit handler cannot recover from SIGKILL and
    # would double-close databases on normal exit.

    yield  # --- App is running ---

    # --- Shutdown ---
    logger.info("Shutting down Local Deep Research...")

    if news_scheduler:
        try:
            news_scheduler.stop()
            logger.info("News scheduler stopped")
        except Exception:
            logger.exception("Error stopping news scheduler")

    if cleanup_scheduler:
        try:
            # wait=True so in-flight cleanup jobs finish before we close
            # the DB below — otherwise they hit a closed pool.
            cleanup_scheduler.shutdown(wait=True)
        except Exception:
            logger.debug("Error stopping cleanup scheduler")

    # Stop the research queue processor so a uvicorn reload doesn't leave
    # an old daemon thread holding locks while the new process starts.
    try:
        queue_processor.stop()
    except Exception:
        logger.debug("Error stopping queue processor")

    try:
        from ..embeddings.model_cache import clear_sentence_transformer_cache

        # This lock attempt never waits for inference. Queueing it on the
        # default executor would still wait when inference occupies that pool,
        # delaying log/database cleanup. Traffic has drained at this point.
        clear_sentence_transformer_cache(wait=False)
    except Exception:
        logger.debug("Error clearing embedding model cache during shutdown")

    # Flush pending DB log writes BEFORE closing databases; `database_sink`
    # swallows errors silently, so anything flushed after close is just
    # dropped.
    from ..utilities.log_utils import (
        flush_log_queue,
        stop_log_queue_processor,
    )

    try:
        flush_log_queue()
        stop_log_queue_processor()
    except Exception:
        logger.debug("Error flushing log queue during shutdown")

    try:
        db_manager.close_all_databases()
        logger.info("Database connections closed")
    except Exception:
        logger.exception("Error closing databases")


# ---------------------------------------------------------------------------
# ASGI Middleware (pure ASGI — NOT BaseHTTPMiddleware)
# ---------------------------------------------------------------------------


def _is_private_ip(ip_str: str) -> bool:
    """Check if IP is a private/local network address.

    Returns True for private IPs (RFC 1918), localhost, and non-parseable
    strings (e.g. 'testclient' from TestClient). Non-parseable strings
    are treated as private to avoid adding Secure flag in test/dev contexts.

    A 6to4, Teredo or NAT64 peer is NOT private, whatever ``ipaddress``
    says: such an address reaches this server through a relay or
    translator from somewhere else entirely. Both consumers depend on
    that -- the forwarded-proto advice must not be plantable by a remote
    client arriving over a tunnel, and the "serving HTTP to a public
    client" warning must not stay silent for one. The ranges are the
    shared ``network_utils.IPV6_TRANSITION_NETWORKS``, the same ones the
    rate limiter's proxy-trust decision excludes.

    An IPv4-mapped address (``::ffff:a.b.c.d``, how an IPv4 client appears
    on a dual-stack listener) is judged by the IPv4 address it wraps,
    unwrapped here as ``network_utils.is_private_peer_ip`` does. CPython
    3.12.0 to 3.12.3 answer from their IPv6 table instead, which lists
    ``::ffff:0:0/96`` as private, so a public IPv4 client would read as
    private on those versions.
    """
    if not ip_str:
        return True
    try:
        ip = ipaddress.ip_address(ip_str)
    except ValueError:
        return True  # Non-IP strings (e.g. "testclient") treated as private
    if ip.version == 6 and ip.ipv4_mapped is not None:
        ip = ip.ipv4_mapped
    if is_ipv6_transition_address(ip):
        return False
    return ip.is_private or ip.is_loopback


class SecurityHeadersMiddleware:
    """Pure ASGI middleware for security headers.

    Ports Flask's SecurityHeaders + ServerHeaderMiddleware to ASGI.
    """

    # Style attributes support math rendering and browser-driven layout.
    # Inline script and style elements require a per-response nonce.
    CSP = (
        "default-src 'self'; "
        "connect-src 'self'; "
        "script-src 'self'; "
        "script-src-attr 'none'; "
        "style-src 'self'; "
        "style-src-attr 'unsafe-inline'; "
        "font-src 'self' data:; "
        "img-src 'self' data:; "
        "media-src 'self'; "
        "worker-src blob:; "
        "child-src 'self' blob:; "
        "frame-src 'self'; "
        "frame-ancestors 'self'; "
        "manifest-src 'self'; "
        "object-src 'none'; "
        "base-uri 'self'; "
        "form-action 'self';"
    )
    PERMISSIONS = (
        "geolocation=(), midi=(), camera=(), usb=(), "
        "magnetometer=(), accelerometer=(), gyroscope=(), "
        "microphone=(), payment=(), sync-xhr=(), document-domain=()"
    )

    @classmethod
    def unconditional_headers(cls, scope=None) -> list[tuple[bytes, bytes]]:
        """The security headers stamped on every HTTP response.

        Exposed separately because this middleware cannot cover every
        response. Starlette's ``ServerErrorMiddleware`` sits OUTSIDE every
        middleware added via ``app.add_middleware`` — it is installed by
        ``build_middleware_stack`` itself — and when an exception handler
        is registered for the bare ``Exception`` class, Starlette wires it
        in as that middleware's handler. Its response is written to the raw
        ASGI ``send``, bypassing this middleware entirely, so a 500 from an
        unregistered exception type would otherwise carry NO security
        headers at all. The catch-all handler reuses this list to stamp
        them itself; keeping one source stops the two copies drifting.

        Excludes the two conditional headers (HSTS, which needs a secure
        scheme, and cache-control, which is skipped for static asset routes).
        """
        policy = cls.CSP
        if scope is not None:
            from .utils.csp import template_security_context

            nonce = template_security_context(scope).nonce
            policy = policy.replace(
                "script-src 'self'", f"script-src 'self' 'nonce-{nonce}'"
            ).replace("style-src 'self'", f"style-src 'self' 'nonce-{nonce}'")
        return [
            (b"content-security-policy", policy.encode()),
            (b"x-frame-options", b"SAMEORIGIN"),
            (b"x-content-type-options", b"nosniff"),
            (b"cross-origin-opener-policy", b"same-origin"),
            (b"cross-origin-embedder-policy", b"credentialless"),
            (b"cross-origin-resource-policy", b"same-origin"),
            (b"permissions-policy", cls.PERMISSIONS.encode()),
            (b"referrer-policy", b"strict-origin-when-cross-origin"),
        ]

    @classmethod
    def cache_headers(cls) -> list[tuple[bytes, bytes]]:
        """No-store cache headers stamped on responses outside static routes.

        Split out from ``unconditional_headers()`` (Cache-Control/Pragma/
        Expires are conditional on path, not truly unconditional) so the
        catch-all 500 handler below can reuse the exact same values
        instead of hand-copying them — main's Flask ``after_request``
        (``security/security_headers.py``) set all three:
        ``Cache-Control``, ``Pragma`` (HTTP/1.0 compatibility), and
        ``Expires: 0``. The ASGI port originally dropped ``Expires``;
        restored here for parity. Impact of the omission was low
        (``Cache-Control: no-store`` already dominates for any HTTP/1.1
        cache) but it's a free one-line fix once the two are split out.
        """
        return [
            (
                b"cache-control",
                b"no-store, no-cache, must-revalidate, max-age=0",
            ),
            (b"pragma", b"no-cache"),
            (b"expires", b"0"),
        ]

    def __init__(self, app):
        self.app = app

    @classmethod
    def response_headers(
        cls, *, path: str, scheme: str, status: int, scope=None
    ) -> list[tuple[bytes, bytes]]:
        """Apply the same header policy inside and outside the middleware."""
        headers = cls.unconditional_headers(scope)
        if scheme == "https":
            headers.append(
                (
                    b"strict-transport-security",
                    b"max-age=31536000; includeSubDomains",
                )
            )
        legacy_asset = path.startswith("/redirect-static/") and status in (
            200,
            206,
            304,
        )
        if not path.startswith("/static/") and not legacy_asset:
            headers.extend(cls.cache_headers())
        return headers

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        from .utils.csp import template_security_context

        # Error rendering and other inner adapters may copy the scope.
        # Share its immutable authorization before those copies are made.
        template_security_context(scope)
        path = scope.get("path", "")

        async def send_wrapper(message):
            if message["type"] == "http.response.start":
                additions = self.response_headers(
                    path=path,
                    scheme=scope.get("scheme", "http"),
                    status=message["status"],
                    scope=scope,
                )
                # Keep the route's streaming directive while replacing its
                # caching policy. SSE must remain untransformed by proxies,
                # and dynamic responses must still be no-store.
                if any(
                    name.lower() == b"cache-control"
                    and any(
                        directive.strip().lower() == b"no-transform"
                        for directive in value.split(b",")
                    )
                    for name, value in message.get("headers", [])
                ):
                    additions = [
                        (
                            name,
                            value + b", no-transform"
                            if name == b"cache-control"
                            else value,
                        )
                        for name, value in additions
                    ]
                replaced = {name for name, _ in additions} | {b"server"}
                headers = [
                    (name, value)
                    for name, value in message.get("headers", [])
                    if name.lower() not in replaced
                ]
                headers.extend(additions)
                message = {**message, "headers": headers}

            await send(message)

        await self.app(scope, receive, send_wrapper)


class _RequestBodyTooLarge(Exception):
    """Raised by BodySizeLimitMiddleware's receive wrapper on overflow."""


#: Separate, much smaller cap applied to non-multipart bodies (JSON and
#: everything else that isn't a file upload) by ``BodySizeLimitMiddleware``.
#:
#: ``await request.json()`` -> ``json.loads`` is synchronous and runs on
#: the single uvicorn event loop this app is served with (workers=1), so
#: one caller's oversized body stalls every concurrent user. Measured on
#: this branch: a 104 MB JSON body stalled the loop for 637 ms, during
#: which 12 concurrent GETs spiked from ~3 ms to 184 ms latency. The only
#: prior bound was the general ``max_body_size`` cap below
#: (MAX_FILES_PER_REQUEST(200) x MAX_FILE_SIZE(3GB) ~= 600 GB) — sized for
#: multipart file uploads, not a practical limit for a single JSON body.
#:
#: 100 MB matches the existing precedent in
#: ``web/routers/notes.py::_MAX_JSON_BODY_BYTES``
#: (``2 * NOTE_CONTENT_MAX_BYTES``, i.e. 2x the 50 MB note-content cap),
#: which already accepts this order-of-magnitude stall for its own
#: pre-parse JSON body gate. No other JSON endpoint in the app needs
#: anywhere near this: research/chat/benchmark/settings JSON bodies are
#: small query/config/message payloads (KB, not MB) — see PR review notes
#: for the survey of ``await request.json()`` call sites. The two routes
#: that genuinely need multi-hundred-MB bodies (``/api/upload/pdf`` and
#: ``/library/api/collections/{id}/upload``) are multipart file uploads,
#: not JSON, and keep the large ``max_body_size`` cap below.
_DEFAULT_MAX_JSON_BODY_SIZE = 100 * 1024 * 1024  # 100 MB

#: The cap every OTHER JSON route gets. 100 MB above is what the notes
#: route needs, but it is a weak mitigation for the defect this cap exists
#: to address: ``json.loads`` runs synchronously on the single uvicorn
#: event loop (workers=1), so body size translates directly into a stall
#: that freezes EVERY concurrent user, not just the caller. Measured on
#: this branch: 104 MB -> 498-637 ms, 34 MB -> ~128 ms, 8 MB -> ~38 ms.
#: A 100 MB cap therefore still permits a ~600 ms full-service stall,
#: repeatable at will by any authenticated caller.
#:
#: 16 MB holds the worst case to roughly 60 ms while leaving ~4x headroom
#: over the largest realistic legitimate body found in a survey of every
#: ``await request.json()`` call site (~4 MB). Routes that genuinely need
#: more are listed in _LARGE_JSON_BODY_PREFIXES and keep the 100 MB cap.
_DEFAULT_MAX_SMALL_JSON_BODY_SIZE = 16 * 1024 * 1024  # 16 MB

#: Path prefixes allowed the full ``_DEFAULT_MAX_JSON_BODY_SIZE``. Keep
#: this list as short as possible: every entry is a route that can stall
#: the event loop for hundreds of ms. ``notes`` earns it because
#: NOTE_CONTENT_MAX_BYTES is 50 MB and its handler already does its own
#: bounded pre-parse read (notes.py::_notes_json_body).
_LARGE_JSON_BODY_PREFIXES = ("/notes/",)

#: The only two routes that genuinely consume a multipart upload body
#: (both do ``await request.form()`` and pull ``UploadFile``s out of it).
#: The large ``max_body_size`` cap is granted on PATH, never on the
#: client's declared Content-Type. Starlette's ``Request.json()`` is
#: ``json.loads(await self.body())`` -- it never inspects Content-Type --
#: so a body labelled ``multipart/form-data`` is still parsed as JSON by
#: any route that asks for JSON. Choosing the cap from the header alone
#: therefore handed every one of the app's ``request.json()`` routes the
#: ~600 GB upload cap (200 files x 3 GB) for the cost of one mislabelled
#: header, while the route went on parsing the body as JSON.
_MULTIPART_UPLOAD_PATHS = frozenset({"/api/upload/pdf"})
_MULTIPART_UPLOAD_RE = re.compile(r"^/library/api/collections/[^/]+/upload$")


def _is_multipart_upload_path(path: str) -> bool:
    """True for the two routes allowed to carry an upload-sized body."""
    return path in _MULTIPART_UPLOAD_PATHS or bool(
        _MULTIPART_UPLOAD_RE.match(path)
    )


class BodySizeLimitMiddleware:
    """Pure ASGI middleware enforcing a global request-body size cap.

    Ports Flask's ``MAX_CONTENT_LENGTH`` (app_factory set it to
    ``MAX_FILES_PER_REQUEST * MAX_FILE_SIZE``; Werkzeug rejected any
    larger body with 413) plus the ``@app.errorhandler(413)`` content
    negotiation. Without it every body-reading code path — including the
    CSRF middleware, which buffers form bodies to extract the token —
    would buffer arbitrarily large request bodies into memory.

    The declared Content-Length is checked before the app runs; bodies
    streamed without one (chunked transfer) are counted chunk by chunk so
    the cap cannot be bypassed.

    On top of that global cap, non-multipart requests (JSON bodies, but
    also anything with a missing/spoofed Content-Type — a route can call
    ``await request.json()`` regardless of what Content-Type the client
    sent, so gating strictly on ``application/json`` would leave that as
    a bypass) are additionally capped at the much smaller
    ``max_json_body_size``. Multipart requests (the two real upload
    routes) are exempt from that smaller cap and still enforce only
    ``max_body_size`` — see ``_DEFAULT_MAX_JSON_BODY_SIZE`` above for the
    justification and measurements.
    """

    def __init__(
        self,
        app,
        max_body_size: int | None = None,
        max_json_body_size: int | None = None,
        max_large_json_body_size: int | None = None,
    ):
        self.app = app
        if max_body_size is None:
            from ..security.file_upload_validator import FileUploadValidator

            max_body_size = (
                FileUploadValidator.MAX_FILES_PER_REQUEST
                * FileUploadValidator.MAX_FILE_SIZE
            )
        self.max_body_size = max_body_size
        # `max_json_body_size` is the cap for ORDINARY JSON routes, i.e.
        # almost everything. `max_large_json_body_size` applies only to the
        # few prefixes in _LARGE_JSON_BODY_PREFIXES that legitimately carry
        # a big body. Keeping the ordinary case as the injectable default
        # means a caller passing a small cap gets it applied where it
        # matters, rather than silently only affecting notes.
        if max_json_body_size is None:
            max_json_body_size = _DEFAULT_MAX_SMALL_JSON_BODY_SIZE
        self.max_json_body_size = max_json_body_size
        if max_large_json_body_size is None:
            max_large_json_body_size = _DEFAULT_MAX_JSON_BODY_SIZE
        self.max_large_json_body_size = max(
            max_large_json_body_size, max_json_body_size
        )

    async def _send_413(self, scope, receive, send):
        path = scope.get("path", "")
        # Same negotiation as main's 413 errorhandler (_is_api_path).
        if "/api/" in path or path.endswith("/api"):
            body = b'{"error": "Request too large"}'
            content_type = b"application/json"
            await send(
                {
                    "type": "http.response.start",
                    "status": 413,
                    "headers": [
                        (b"content-type", content_type),
                        (b"content-length", str(len(body)).encode()),
                    ],
                }
            )
            await send({"type": "http.response.body", "body": body})
            return

        # Only the declared-length rejection (the fast path in __call__,
        # before `self.app` — and therefore SessionMiddleware — ever
        # runs) reaches this with no "session" key in `scope` at all;
        # `setdefault` supplies an empty placeholder there, without
        # adding keys to the original scope, so the branded page still
        # renders instead of falling back to plain text for that path.
        # On the streamed (chunked) path, this runs from `__call__`'s
        # `except _RequestBodyTooLarge` handler AFTER `self.app(...)`
        # was entered, so SessionMiddleware has already populated
        # `scope["session"]` with the real, live ``Session`` and
        # `setdefault` is a no-op — `_render_branded_error_page` renders
        # against its own detached copy of that live session either way,
        # so nothing here needs to know which case it is.
        # `_render_branded_error_page` already catches every exception
        # itself and returns ``None`` on failure — `dict(scope)` and
        # `Request(...)` do no work that can raise — so there is nothing
        # left here to catch; rendering failures keep the plain-text
        # fallback via that ``None`` return. Unmatched and decorated
        # routes can skip the outer global rate-limit check, so rendering
        # here must not rely on an endpoint's rate-limit decorator having
        # run.
        req_scope = dict(scope)
        req_scope.setdefault("session", {})
        response = _render_branded_error_page(Request(req_scope), 413)
        if response is not None:
            # Response.__call__ never reads `receive` for a non-streaming
            # response (only sends http.response.start/body), so the real
            # `receive` is safe to pass through unused.
            await response(scope, receive, send)
            return

        body = b"Request too large"
        content_type = b"text/plain; charset=utf-8"
        await send(
            {
                "type": "http.response.start",
                "status": 413,
                "headers": [
                    (b"content-type", content_type),
                    (b"content-length", str(len(body)).encode()),
                ],
            }
        )
        await send({"type": "http.response.body", "body": body})

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        # Multipart ON one of the two real upload paths keeps the large
        # cap; everything else — JSON, a mislabelled multipart body, and
        # anything with a missing/other Content-Type, since a route can
        # call `request.json()` no matter what Content-Type was sent — is
        # additionally bounded by
        # the much smaller JSON cap. `min()` also means an explicit,
        # smaller `max_body_size` passed to the constructor (as tests
        # do) still wins, so this never widens an existing caller's cap.
        content_type = b""
        for name, value in scope.get("headers", []):
            if name == b"content-type":
                content_type = value
                break
        # Both conditions are required: a multipart *label* is not enough,
        # because it is client-supplied and costs nothing to forge (see
        # _MULTIPART_UPLOAD_PATHS). Only the real upload routes get the
        # upload-sized cap; a mislabelled body on any other path falls
        # through to the JSON cap below, exactly as an honestly-labelled
        # one does.
        is_multipart = content_type.lower().startswith(
            b"multipart/"
        ) and _is_multipart_upload_path(scope.get("path", ""))
        if is_multipart:
            effective_max = self.max_body_size
        else:
            # Routes that legitimately carry a large JSON body keep the
            # larger cap. Only notes qualifies: NOTE_CONTENT_MAX_BYTES is
            # 50 MB, and notes.py::_MAX_JSON_BODY_BYTES doubles that to
            # allow for JSON escaping. Every other `request.json()` call
            # site in the app carries a small query/config/message payload
            # — the largest realistic one is library_delete's bulk
            # `document_ids`, ~4 MB even at 100k UUIDs.
            json_cap = (
                self.max_large_json_body_size
                if scope.get("path", "").startswith(_LARGE_JSON_BODY_PREFIXES)
                else self.max_json_body_size
            )
            effective_max = min(self.max_body_size, json_cap)

        # Fast path: client declared an over-cap Content-Length.
        for name, value in scope.get("headers", []):
            if name == b"content-length":
                try:
                    declared = int(value)
                except ValueError:
                    break
                if declared > effective_max:
                    await self._send_413(scope, receive, send)
                    return
                break

        received = 0
        response_started = False

        async def recv_limited():
            nonlocal received
            message = await receive()
            if message["type"] == "http.request":
                received += len(message.get("body", b""))
                if received > effective_max:
                    raise _RequestBodyTooLarge()
            return message

        async def send_tracking(message):
            nonlocal response_started
            if message["type"] == "http.response.start":
                response_started = True
            await send(message)

        try:
            await self.app(scope, recv_limited, send_tracking)
        except _RequestBodyTooLarge:
            if response_started:
                # Too late for a 413 — let the server tear the
                # connection down.
                raise
            from .routers.notes import _log_value_preview

            # (#6938: the path is client-chosen and this runs before
            # authentication, so it is bounded.)
            logger.warning(
                "Rejected over-limit request body on {} (> {} bytes)",
                _log_value_preview(scope.get("path", "")),
                effective_max,
            )
            await self._send_413(scope, receive, send)


class SecureCookieMiddleware:
    """Pure ASGI middleware to add Secure flag to cookies based on client IP.

    Ports Flask's SecureCookieMiddleware to ASGI.
    """

    def __init__(self, app, testing: bool = False):
        self.app = app
        self.testing = testing
        self._warned_insecure_public = False
        self._warned_untrusted_forwarded_proto = False
        self._warned_noncanonical_forwarded_proto = False

    def _maybe_warn_untrusted_forwarded_proto(
        self, scope, remote_addr: str
    ) -> None:
        """One-shot warning for the reverse-proxy misconfiguration that is
        otherwise completely silent.

        ``_maybe_warn_insecure_public`` below only fires for a NON-private
        client IP, so the most common broken upgrade never trips it: nginx (or
        caddy/traefik) terminating TLS on 127.0.0.1 with TRUST_PROXY_HEADERS
        unset. The peer address is loopback, so that warning takes the
        private-IP branch and says nothing, while uvicorn — not being told to
        honour forwarded headers — reports scheme "http". The session cookie
        then silently loses ``Secure`` and HSTS is silently withheld, on a
        deployment the operator believes is HTTPS.

        The tell is a request that carries ``X-Forwarded-Proto: https`` while
        the connection is not being treated as HTTPS. Cheap: this only runs on
        the not-https path (a correctly configured deployment never reaches
        it), and logs each distinct misconfiguration once. Until both warnings
        have been emitted, each request must be checked: a headerless health
        check or an untrusted direct client must not conceal a later proxy
        request.
        """
        if (
            self._warned_untrusted_forwarded_proto
            and self._warned_noncanonical_forwarded_proto
        ):
            return

        # Mirror uvicorn's ProxyHeadersMiddleware exactly (0.52.x): it reads
        # the LAST X-Forwarded-Proto header line, decodes it as latin-1,
        # strips it, and honours it only on an exact match against
        # {"http", "https", "ws", "wss"}. A value LDR would read as https
        # but uvicorn would not ("HTTPS", "https, https" from a proxy that
        # appends, "https,http") is a different misconfiguration from an
        # untrusted proxy and needs different advice -- in that case
        # uvicorn may well trust the proxy and have rewritten
        # scope["client"] from X-Forwarded-For already.
        proto_value = None
        for name, value in scope.get("headers", []):
            if name == b"x-forwarded-proto":
                proto_value = value
        if proto_value is None:
            return
        uvicorn_view = proto_value.decode("latin-1").strip()

        # No client address is ever interpolated into this advice. The
        # address in scope["client"] is not necessarily the proxy: with
        # TRUST_PROXY_HEADERS=true uvicorn may already have replaced it with
        # an X-Forwarded-For entry (under "*" the client-forgeable left-most
        # one, unvalidated -- "8.8.8.8/32" or free text), and even when it
        # is the raw socket peer, that peer may be an unlisted co-tenant
        # rather than the operator's proxy. Naming it as "the address to
        # allow-list" would let a client plant its own address into the
        # operator's forwarding trust.
        if uvicorn_view == "https":
            if self._warned_untrusted_forwarded_proto:
                return
            # uvicorn would have honoured this exact value had it trusted
            # the peer, so it did not: TRUST_PROXY_HEADERS is off, or the
            # peer is outside LDR_SERVER_FORWARDED_ALLOW_IPS. This header is
            # untrusted client input, and the advice here widens forwarding
            # trust, so give it only for a loopback/private peer: any remote
            # client could otherwise send `X-Forwarded-Proto: https` once
            # and plant a log line telling the operator to set
            # TRUST_PROXY_HEADERS=true -- advice that, followed on a host
            # NOT behind a proxy, would hand that same client control of the
            # scheme and therefore of the Secure-cookie and HSTS decisions.
            if not remote_addr or not _is_private_ip(remote_addr):
                return
            self._warned_untrusted_forwarded_proto = True
            logger.warning(
                "Received X-Forwarded-Proto: https but this connection is "
                "not being treated as HTTPS, so session cookies will NOT "
                "get the Secure flag and HSTS will NOT be sent. If this "
                "server sits behind a TLS-terminating reverse proxy, set "
                "TRUST_PROXY_HEADERS=true so forwarded headers are "
                "honoured. If it is already set, uvicorn does not trust the "
                "proxy that sent this request: add your reverse proxy's own "
                "address as LDR sees it (the address the proxy connects "
                "from, not a client address; with LDR in Docker behind a "
                "proxy on the host, the Docker network's gateway, not "
                "127.0.0.1) to LDR_SERVER_FORWARDED_ALLOW_IPS, which must "
                "list every proxy hop in front of LDR."
            )
        elif uvicorn_view.split(",")[0].strip().lower() == "https":
            if self._warned_noncanonical_forwarded_proto:
                return
            # uvicorn ignores this value whether or not it trusts the peer,
            # so neither TRUST_PROXY_HEADERS nor the allow-list is the fix,
            # and the advice (reconfigure the proxy) widens no trust -- it
            # is safe to give for any peer, including one uvicorn has
            # already rewritten to a public client address.
            self._warned_noncanonical_forwarded_proto = True
            logger.warning(
                "Received an X-Forwarded-Proto header claiming https in a "
                "form uvicorn does not accept, so this connection is not "
                "being treated as HTTPS: session cookies will NOT get the "
                "Secure flag and HSTS will NOT be sent. uvicorn honours "
                "only a single exact lower-case value (http, https, ws or "
                "wss) in the last X-Forwarded-Proto header, so 'HTTPS' or "
                "a comma-separated list such as 'https, https' is "
                "ignored. If a TLS-terminating reverse proxy sets this "
                "header, configure it to overwrite X-Forwarded-Proto with "
                "exactly 'https' rather than appending to it (nginx: "
                "proxy_set_header X-Forwarded-Proto $scheme;)."
            )

    def _maybe_warn_insecure_public(self, remote_addr: str) -> None:
        """One-shot warning when serving HTTP to a non-private client IP —
        a likely missing HTTPS proxy. Mirrors main's operator signal."""
        if self._warned_insecure_public:
            return
        if remote_addr and not _is_private_ip(remote_addr):
            self._warned_insecure_public = True
            from ..security.log_sanitizer import redact_and_bound_for_log

            logger.warning(
                "Serving HTTP to a public client ({}). Session/CSRF cookies "
                "are NOT marked Secure (marking them Secure over HTTP would "
                "make the browser drop them). Put LDR behind HTTPS, and if "
                "using a TLS proxy set TRUST_PROXY_HEADERS=true.",
                # remote_addr parsed as an IP (non-IPs count as private),
                # but ipaddress accepts an IPv6 zone id of arbitrary text
                # ("2001:db8::1%any words"), and with TRUST_PROXY_HEADERS
                # uvicorn may have copied it from X-Forwarded-For. Log the
                # address alone.
                redact_and_bound_for_log(remote_addr.partition("%")[0], 64),
            )

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        # Add the Secure flag ONLY when the connection is actually HTTPS.
        # Matches Flask's SecureCookieMiddleware (#3849): setting Secure on a
        # cookie served over plain HTTP makes the browser DROP the cookie
        # (RFC6265bis), so a deployment reachable over HTTP from a public IP
        # would hit an unbreakable login loop. A previous version here added
        # Secure for "public IP over HTTP" too, reintroducing exactly that
        # bug. For a deployment behind a TLS-terminating proxy, honor
        # X-Forwarded-Proto by starting uvicorn with TRUST_PROXY_HEADERS=true
        # so scope["scheme"] reflects https (see web/app.py). We still warn
        # once when serving HTTP to a non-private client so a missing HTTPS
        # proxy is visible.
        client = scope.get("client")
        remote_addr = client[0] if client else ""
        is_https = scope.get("scheme") == "https"
        if not is_https and not self.testing:
            self._maybe_warn_insecure_public(remote_addr)
            self._maybe_warn_untrusted_forwarded_proto(scope, remote_addr)
        should_add_secure = not self.testing and is_https

        if not should_add_secure:
            await self.app(scope, receive, send)
            return

        async def send_wrapper(message):
            if message["type"] == "http.response.start":
                headers = []
                for k, v in message.get("headers", []):
                    if k.lower() == b"set-cookie":
                        v_str = v.decode("latin-1")
                        if "; Secure" not in v_str and "; secure" not in v_str:
                            v_str += "; Secure"
                        v = v_str.encode("latin-1")
                    headers.append((k, v))
                message = {**message, "headers": headers}
            await send(message)

        await self.app(scope, receive, send_wrapper)


class RememberMeMiddleware:
    """Strip session-cookie Max-Age/Expires unless `_remember_me` is True.

    Starlette's SessionMiddleware accepts a single `max_age` applied to
    every session cookie. Without this middleware, every login gets a
    30-day persistent cookie regardless of whether the user ticked
    "Remember me" — which is the usual UX complaint, and would be a
    privacy regression vs. the Flask app that honored the flag (Flask
    defaulted `session.permanent = False`, i.e. a browser-session
    cookie, and only made it persistent when "remember me" was
    checked).

    The login handler stores `_remember_me` inside the session dict.
    On every response we inspect it and, unless it is explicitly
    `True`, strip `Max-Age` and `Expires` attributes from the outbound
    `session=...` Set-Cookie so the browser treats it as a session
    cookie (discarded on browser close). Anonymous visitors (no login
    yet) and requests right after logout also read back as "not True"
    here — `_remember_me` is either absent (never logged in) or wiped
    by `request.session.clear()` at logout (routers/auth.py), so it
    reads back as `None`, not `False`. Both must get the same
    non-persistent cookie as an explicit `_remember_me=False` login;
    checking `remember_me is False` instead of `is not True` would miss
    both cases and hand every anonymous visitor and every just-logged-out
    user a persistent 30-day cookie.

    This ONLY relaxes the client-side (browser) cap. The itsdangerous
    signature backing the cookie is still valid for the full
    `security.session_remember_me_days` window (SessionMiddleware has a
    single `max_age` shared by every session — see its construction
    below) regardless of this flag, so a raw non-remember-me cookie value
    copied out of the browser (XSS exfiltration, proxy log, devtools)
    would replay successfully for up to 30 days even though the browser
    itself was told to discard it on close. `_enforce_session_expiry` /
    `_stamp_session_expiry` (used by `DatabaseMiddleware` below) close
    that gap by enforcing the shorter `security.session_timeout_hours`
    window server-side, independent of the browser-facing cookie
    attributes this middleware controls.

    EXCEPTION — the deletion cookie must survive untouched. When a session
    is cleared server-side (idle-timeout revocation in
    `_enforce_session_revocation`, or logout), Starlette's SessionMiddleware
    does not write a normal data cookie: it writes the literal
    `session=null; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT; ...`
    (see `starlette.middleware.sessions.SessionMiddleware.send_wrapper`,
    the `session.modified and not initial_session_was_empty` branch) — an
    explicit "delete this cookie now" instruction, not persistent session
    data. Stripping `Expires`/`Max-Age` from THAT header, the same as any
    other non-remember-me cookie, downgrades it to `session=null; path=/;
    httponly; samesite=lax`: no expiry in the past, so the browser does
    not delete the cookie at all — it just keeps sending the literal string
    "null" back as the session value for the rest of the browser session.
    A revoked/logged-out session would then never actually leave the
    client. `session=null;` is the exact, fixed marker Starlette emits for
    a cleared session (never a signed payload), so matching it precisely
    identifies the deletion cookie without needing to duplicate
    SessionMiddleware's own emptiness bookkeeping.
    """

    # Name of the cookie Starlette's SessionMiddleware sets.
    _SESSION_COOKIE_NAME = b"session"

    # The literal value Starlette's SessionMiddleware writes when a session
    # is cleared (see the class docstring's EXCEPTION section). Distinct by
    # construction from every real session cookie, which carries a base64
    # itsdangerous-signed payload, never the bare string "null".
    _DELETED_COOKIE_PREFIX = _SESSION_COOKIE_NAME + b"=null;"

    def __init__(self, app) -> None:
        self.app = app

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        async def send_wrapper(message):
            if message["type"] != "http.response.start":
                await send(message)
                return

            # Resolve remember_me preference from the session. Treat
            # anything other than an explicit True (missing/None for
            # anonymous or just-logged-out sessions, or False for an
            # explicit non-remember-me login) as "strip the persistent
            # cookie attributes" — only an explicit opt-in keeps them.
            session = scope.get("session", {}) or {}
            remember_me = session.get("_remember_me")
            if remember_me is not True:
                rewritten = []
                for k, v in message.get("headers", []):
                    if (
                        k.lower() == b"set-cookie"
                        and v.lower().startswith(
                            self._SESSION_COOKIE_NAME + b"="
                        )
                        and not v.lower().startswith(
                            self._DELETED_COOKIE_PREFIX
                        )
                    ):
                        v_str = v.decode("latin-1")
                        # Drop Max-Age=... and Expires=... attributes.
                        parts = [
                            part
                            for part in v_str.split(";")
                            if not part.strip()
                            .lower()
                            .startswith(("max-age=", "expires="))
                        ]
                        v = ";".join(parts).encode("latin-1")
                    rewritten.append((k, v))
                message = {**message, "headers": rewritten}
            await send(message)

        await self.app(scope, receive, send_wrapper)


# ---------------------------------------------------------------------------
# Exception handlers
# ---------------------------------------------------------------------------


def _is_api_request(request: Request) -> bool:
    """Check if this is an API/JSON request (vs browser HTML request)."""
    path = request.url.path
    # Match paths containing /api/ segment or ending with /api
    if "/api/" in path or path.endswith("/api"):
        return True
    accept = request.headers.get("accept", "")
    if "application/json" in accept and "text/html" not in accept:
        return True
    return False


def _http_exception_content(path: str, detail) -> dict:
    """JSON body for an ``HTTPException`` answered as JSON on ``path``."""
    if path == "/api/v1" or path.startswith("/api/v1/"):
        # /api/v1 is the documented programmatic API for external clients,
        # and main returned {"error": ...} for its auth failures
        # (web/api.py's `jsonify({"error": "Authentication required"})` /
        # `{"error": "API access is disabled"}`). Routing those through
        # HTTPException here would silently change the envelope to
        # {"detail": ...} for every existing script.
        #
        # Both keys are emitted rather than swapping: the frontend's
        # api.js reads `detail`, and tests/web/test_exception_handler_
        # contract.py deliberately pins the {"detail": ...} shape for the
        # rest of the app. This restores main's contract for the external
        # API without disturbing either.
        return {"error": detail, "detail": detail}
    return {"detail": detail}


def _register_exception_handlers(app: FastAPI) -> None:
    """Register custom exception handlers (ports Flask's error handlers)."""

    from fastapi.exceptions import HTTPException, RequestValidationError

    from .exceptions import WebAPIException

    # Pydantic's ``msg`` can contain submitted values when a validator raises
    # ValueError or PydanticCustomError. Build the browser summary and the
    # structured detail from fixed messages keyed by error type instead.
    safe_validation_messages = {
        "missing": "Field required",
        "extra_forbidden": "Unexpected field",
        "json_invalid": "Invalid JSON",
        "int_parsing": "Enter a valid integer",
        "int_type": "Enter a valid integer",
        "float_parsing": "Enter a valid number",
        "float_type": "Enter a valid number",
        "bool_parsing": "Enter true or false",
        "bool_type": "Enter true or false",
        "string_type": "Enter text",
        "string_too_short": "Text is too short",
        "string_too_long": "Text is too long",
        "greater_than": "Value is too small",
        "greater_than_equal": "Value is too small",
        "less_than": "Value is too large",
        "less_than_equal": "Value is too large",
        "literal_error": "Choose an allowed value",
        "list_type": "Enter a list",
        "dict_type": "Enter an object",
    }

    @app.exception_handler(RequestValidationError)
    async def handle_request_validation_error(
        request: Request, exc: RequestValidationError
    ):
        # Keep ``loc``/``type`` for API clients, replace every ``msg`` with
        # fixed text, drop ``input``/``ctx``/``url``, and add the ``error``
        # string consumed by the browser. Validator messages and submitted
        # values are never forwarded. ``loc`` is copied as-is, so it can still
        # echo submitted dict keys (no current route has a dict-typed or
        # extra=forbid body); for json_invalid it ends in a parser offset.
        errors = [
            {
                "loc": error["loc"],
                "msg": safe_validation_messages.get(
                    error["type"], "Invalid value"
                ),
                "type": error["type"],
            }
            for error in exc.errors()
        ]
        messages = []
        for error in errors[:3]:
            location = error["loc"]
            if location and location[0] in (
                "body",
                "query",
                "path",
                "header",
                "cookie",
            ):
                location = location[1:]
            field = ".".join(str(part) for part in location)
            if error["type"] == "json_invalid" and location:
                # nosemgrep: semgrep.rules.sql-string-concatenation, reason: JSON error position is a response label and never reaches SQL
                field = f"position {location[-1]}"
            messages.append(
                f"{field}: {error['msg']}" if field else error["msg"]
            )
        message = "Invalid request"
        if messages:
            message += ": " + "; ".join(messages)
        if len(errors) > 3:
            message += f"; and {len(errors) - 3} more validation errors"
        return JSONResponse(
            {"error": message, "detail": errors}, status_code=422
        )

    @app.exception_handler(HTTPException)
    async def handle_http_exception(request: Request, exc: HTTPException):
        """Redirect 401s for browser requests to login page (Flask parity)."""
        if exc.status_code == 401 and not _is_api_request(request):
            login_url = "/auth/login"
            # Path AND query. main used Werkzeug's `request.url` (the full
            # URL) as `next`, so a deep link survived the login bounce; the
            # port truncated it to the path, silently dropping the query.
            # That is not cosmetic: a signed-out user following a link such
            # as /settings/?tab=llm lost everything after the `?`. A chat
            # page's `q` survives this bounce too, but not the login: the
            # login page drops it from `next` (routers/auth.py:
            # _drop_chat_query), because after login the browser follows
            # our own redirect and the chat page cannot tell that another
            # site supplied the text. (The chat route also drops `q` before
            # this bounce when Sec-Fetch-Site marks the link as coming from
            # another origin.) The consumer side already
            # handles this -- URLValidator.get_safe_redirect_path()
            # explicitly re-appends query and fragment, and is byte-identical
            # to main. quote(safe="/") below encodes the `?` and `&` so the
            # embedded value stays a single well-formed query parameter.
            next_url = str(request.url.path)
            if request.url.query:
                next_url += "?" + request.url.query
            if next_url and next_url != "/":
                # URL-encode the path before embedding as a query value.
                # Without quote(), characters like `?` or `&` in the path
                # break the resulting URL; downstream code that treats
                # ?next= as untrusted input must still validate it's a
                # local path, but at minimum the encoding here keeps the
                # redirect target well-formed.
                from urllib.parse import quote

                login_url += f"?next={quote(next_url, safe='/')}"
            return RedirectResponse(
                url=login_url,
                status_code=302,
                headers=exc.headers,
            )
        return JSONResponse(
            _http_exception_content(request.url.path, exc.detail),
            status_code=exc.status_code,
            headers=exc.headers,
        )

    @app.exception_handler(404)
    async def not_found(request: Request, exc):
        # Browser navigations get HTML; only API callers get JSON. Without
        # the branch, a user who mistypes a URL is shown a raw
        # ``{"error": "Not found"}`` body in the browser's JSON viewer.
        # Flask branched the same way — the retired app_factory.py's
        # ``@app.errorhandler(404)`` returned ``make_response("Not found",
        # 404)``, which Flask serves as text/html — and the 401 handler
        # directly above already makes this distinction. This one did not.
        if _is_api_request(request):
            return JSONResponse({"error": "Not found"}, status_code=404)
        # Branded page (PR #5424), falling back to the old fixed plain-text
        # body if rendering fails for any reason — see
        # _render_branded_error_page's docstring.
        page = _render_branded_error_page(request, 404)
        if page is not None:
            return page
        return HTMLResponse("Not found", status_code=404)

    # Catch-all so unhandled exceptions get logged with traceback rather than
    # silently disappearing into Starlette's default 500 path. (The Exception
    # handler takes precedence over status-code 500 via MRO, so a separate
    # 500 handler would be unreachable.)
    @app.exception_handler(Exception)
    async def unhandled_exception(request: Request, exc):
        from fastapi import HTTPException

        # Let HTTPException pass through to FastAPI's default handler.
        if isinstance(exc, HTTPException):
            raise exc from None
        from .routers.notes import _log_value_preview

        # (#6938: the path is client-chosen, so it is bounded.)
        logger.opt(exception=exc).error(
            "Unhandled exception: {} {}",
            request.method,
            _log_value_preview(request.url.path),
        )
        # Stamp the security headers here rather than relying on
        # SecurityHeadersMiddleware. Registering a handler for the bare
        # ``Exception`` class makes Starlette wire it into
        # ``ServerErrorMiddleware``, which is installed OUTSIDE every
        # ``add_middleware`` layer and writes to the raw ASGI ``send`` —
        # so this response never passes through that middleware and would
        # otherwise ship with no CSP, no nosniff, no frame-options — and,
        # same reasoning, no Cache-Control/Pragma/Expires either (main's
        # Flask ``after_request`` covered every response including
        # unhandled 500s; this reuses SecurityHeadersMiddleware.
        # cache_headers() so the two can't drift apart).
        # Preserve the fixed JSON 500 response for both browser and API
        # callers. Branding 404/413 does not change this error envelope.
        return JSONResponse(
            {"error": "Server error"},
            status_code=500,
            headers={
                name.decode(): value.decode()
                for name, value in SecurityHeadersMiddleware.response_headers(
                    path=request.url.path,
                    scheme=request.url.scheme,
                    status=500,
                    scope=request.scope,
                )
            },
        )

    # Flask parity: request.get_json() returned 400 on malformed JSON and on
    # request bodies that could not be decoded as UTF-8. Without these two
    # registrations a bare `await request.json()` surfaced either exception
    # as a 500 via the catch-all above.
    import json

    @app.exception_handler(UnicodeDecodeError)
    @app.exception_handler(json.JSONDecodeError)
    async def handle_json_decode_error(request: Request, exc):
        # Log it: this handler also catches a JSONDecodeError raised deeper
        # in a handler (e.g. parsing a downstream response), which is a
        # server-side fault wearing a 400. Without this line those would
        # vanish silently — the catch-all above logs everything it takes.
        #
        # Bounded fields only, never `exc` itself and never `exc.doc`.
        # JSONDecodeError carries the ENTIRE offending document on `.doc`,
        # so interpolating the exception is one __str__ change away from
        # putting a request body — or a downstream provider's response — in
        # the log. `.msg` is the parser's own text ("Expecting value"),
        # `.lineno`/`.colno` are ints. This also matches how every sibling
        # handler here logs (error_code / status_code / reason), and closes
        # a real blind spot in check-sensitive-logging, which tracks
        # exception variables via `except ... as e` and therefore cannot
        # see one arriving as an exception-handler parameter.
        from .routers.notes import _log_value_preview

        # (#6938: the path is client-chosen, so it is bounded.)
        logger.warning(
            "JSON decode error handling {} {}: {} (line {} column {})",
            request.method,
            _log_value_preview(request.url.path),
            getattr(exc, "msg", "invalid JSON"),
            getattr(exc, "lineno", "?"),
            getattr(exc, "colno", "?"),
        )
        return JSONResponse({"error": "Invalid JSON body"}, status_code=400)

    # A client that hangs up before its request body is complete surfaces
    # from ``await request.json()`` (and ``body()``/``stream()``/``form()``)
    # as ``ClientDisconnect``. ``read_json_dict`` lets it through on purpose
    # (its docstring has the reasoning), so without a handler here the
    # catch-all above reports it as a backend outage: an error-level log
    # with a traceback and a 500, for something that is the client's doing.
    #
    # Info level, no traceback, and a 4xx. 499 is nginx's "Client Closed
    # Request", the de-facto status for exactly this: unlike a 5xx it is not
    # counted as a server fault, and unlike 400 it cannot be mistaken for a
    # malformed body. The client is gone, so uvicorn drops whatever is sent
    # after the disconnect (and writes no access-log line for it); the
    # status is only ever seen in-process.
    #
    # Registered for ``ClientDisconnect`` alone. The over-cap exception
    # ``BodySizeLimitMiddleware`` raises is a different class and still
    # reaches that middleware, which logs the rejection and answers 413.
    @app.exception_handler(ClientDisconnect)
    async def handle_client_disconnect(request: Request, exc):
        from .routers.notes import _log_value_preview

        # Bounded fields only, as the decode-error handler above does. The
        # path is client-chosen (#6938), so it is bounded too.
        logger.info(
            "Client disconnected before the request body was complete: {} {}",
            request.method,
            _log_value_preview(request.url.path),
        )
        return JSONResponse({"error": "Client disconnected"}, status_code=499)

    @app.exception_handler(WebAPIException)
    async def handle_web_api_exception(request: Request, exc: WebAPIException):
        logger.error(
            "Web API error: {} (status {})", exc.error_code, exc.status_code
        )
        return JSONResponse(exc.to_dict(), status_code=exc.status_code)

    # A rekey operational fault that a route leaves unhandled: the user's
    # database could not be checked or opened because the rekey sidecar or
    # an epoch file could not be read (an fd-exhaustion spike, EACCES, EIO),
    # or its durable rekey state needs recovery first. get_user_db_session
    # raises it as DatabaseSessionUnavailableError; a db_manager call made
    # directly raises the RekeyOperationalError itself, and so does a
    # settings read through get_settings_manager without a session (it
    # reaches db_manager.get_session). Neither error is a verdict on the
    # session, so both get require_auth's retryable 503
    # (same body and Retry-After, through the HTTPException handler above)
    # instead of the catch-all's 500, and the session is left alone. Logged
    # by type name only: the frames the fault was raised through hold the
    # plaintext password, so no traceback is rendered.
    from ..database.rekey_lock import RekeyOperationalError
    from ..database.session_context import DatabaseSessionUnavailableError

    @app.exception_handler(DatabaseSessionUnavailableError)
    @app.exception_handler(RekeyOperationalError)
    async def handle_database_unavailable(request: Request, exc: Exception):
        from .dependencies.auth import database_unavailable_exception
        from .routers.notes import _log_value_preview

        # (#6938: the path is client-chosen, so it is bounded.)
        logger.warning(
            "Database unavailable while handling {} {} ({}); answering 503",
            request.method,
            _log_value_preview(request.url.path),
            exc.reason
            if isinstance(exc, DatabaseSessionUnavailableError)
            else type(exc).__name__,
        )
        return await handle_http_exception(
            request, database_unavailable_exception()
        )

    try:
        from ..news.exceptions import NewsAPIException

        @app.exception_handler(NewsAPIException)
        async def handle_news_api_exception(
            request: Request, exc: NewsAPIException
        ):
            logger.error(
                "News API error: {} (status {})",
                exc.error_code,
                exc.status_code,
            )
            return JSONResponse(exc.to_dict(), status_code=exc.status_code)
    except ImportError:
        pass

    # PolicyDeniedError can escape any synchronous request-path PEP
    # (LLM, embeddings, URL fetch) that wasn't caught at the call site.
    # Without this handler it surfaces as a 500 — turn it into a clean
    # 400 with the decision reason so the user (and the operator
    # audit log) sees a policy-shaped error instead of a stack trace.
    try:
        from ..security.egress.policy import PolicyDeniedError

        @app.exception_handler(PolicyDeniedError)
        async def handle_policy_denied(
            request: Request, exc: PolicyDeniedError
        ):
            reason = getattr(getattr(exc, "decision", None), "reason", "denied")
            target = getattr(exc, "target", "")
            logger.bind(policy_audit=True).warning(
                "PolicyDeniedError surfaced at FastAPI exception handler",
                reason=reason,
                target=target,
            )
            return JSONResponse(
                {
                    "status": "error",
                    "message": (
                        f"Egress policy refused this request: {reason}"
                    ),
                },
                status_code=400,
            )
    except ImportError:
        # egress_policy is in-tree; skipping the handler is only useful
        # for partial test builds without the security package.
        pass

    # Strict settings reads raise SettingsValueError for an invalid
    # configured value. One that reaches the app gets its diagnostic, which
    # names the key, its source and a fixed reason but never the value, so
    # the operator can find the setting. Without this handler the catch-all
    # above would answer with a generic "Server error".
    from ..settings.exceptions import SettingsValueError

    @app.exception_handler(SettingsValueError)
    async def handle_settings_value_error(
        request: Request, exc: SettingsValueError
    ):
        from .routers.notes import _log_value_preview

        diagnostic = exc.diagnostic
        logger.error(
            "Invalid setting on {} {}: {}",
            request.method,
            _log_value_preview(request.url.path),
            diagnostic,
        )
        if _is_api_request(request):
            return JSONResponse({"error": diagnostic}, status_code=500)
        page = _render_branded_error_page(
            request,
            500,
            title="Invalid setting",
            message=(
                f"{diagnostic}. Correct the setting in the settings page "
                "or the deployment environment, or remove it, then reload."
            ),
        )
        if page is not None:
            return page
        return PlainTextResponse(diagnostic, status_code=500)


# ---------------------------------------------------------------------------
# Database middleware (before each request)
# ---------------------------------------------------------------------------

# Regression #1 fix — see _enforce_session_expiry's docstring for the full
# mechanism. Read once at import time, matching how SessionMiddleware's own
# `max_age` below is computed: an operator change to
# security.session_timeout_hours takes effect on the next restart, not live.
_NON_REMEMBER_ME_SESSION_SECONDS = (
    get_security_default("security.session_timeout_hours", 2) * 3600
)

_SESSION_EXPIRES_AT_KEY = "_session_expires_at"


def _now_ts() -> float:
    """Wall-clock now, as epoch seconds.

    A thin wrapper around ``time.time()`` purely so tests can monkeypatch
    session-expiry time (``local_deep_research.web.fastapi_app._now_ts``)
    without touching the process-global stdlib clock.
    """
    return time.time()


def _enforce_session_expiry(session) -> None:
    """Clear `session` in place if its server-side deadline has passed.

    Regression #1: Starlette's ``SessionMiddleware`` verifies the
    itsdangerous signature with a single ``max_age`` shared by every
    session (see its construction below) — the signer has no notion of
    "this particular session should expire sooner." That means a
    non-remember-me login's raw cookie value stays independently
    replayable for the FULL ``security.session_remember_me_days`` window
    (30 days) purely because that's what SessionMiddleware was built
    with, even though the browser is told (by ``RememberMeMiddleware``)
    to discard the cookie on close. The intended lifetime for a
    non-remember-me session is the much shorter
    ``security.session_timeout_hours`` (default 2h).

    Mechanism chosen: stamp an expiry deadline into the session payload
    itself (`_stamp_session_expiry` below) and enforce it here, in
    application code, independent of itsdangerous's own signature check.

    Alternatives considered and rejected:
    * Two ``SessionMiddleware`` instances (short/long ``max_age``),
      dispatched by ``_remember_me`` — the dispatch decision itself
      requires reading the session, i.e. doing the same "peek before you
      verify" work this function already does, for substantially more
      code (two secrets or cookie names to keep in sync, or a
      request-splitting wrapper ASGI app in front of both).
    * A custom itsdangerous signer with a variable ``max_age`` — ``max_age``
      is a verification-time argument to ``signer.unsign()``, not part of
      the signed payload, so "vary the signer" still needs some per-session
      signal to pick which ``max_age`` to verify with BEFORE verification
      succeeds. That signal is exactly the deadline stamped here — no
      simpler, and itsdangerous's own timestamp isn't readable without a
      successful unsign first (chicken-and-egg).
    * Enforce the same shorter deadline on remember-me sessions too
      (uniform handling, less code) — rejected: their itsdangerous-level
      cap already matches ``security.session_remember_me_days`` exactly,
      so adding a second, redundant deadline only risks the two drifting
      apart if an operator changes one setting and not the other.

    Called from ``DatabaseMiddleware.__call__`` after CSRFMiddleware and
    before Starlette's router. CSRF can still inspect a signed but expired
    session, but no route handler (including ``require_auth`` / ``/auth/check``)
    can act on one whose intended lifetime has passed. Clearing the dict
    here makes an expired session indistinguishable from "never logged in"
    to downstream handlers without touching those call sites.

    Existing sessions: does NOT force-log-out non-remember-me sessions
    that predate this fix. Their cookie has no stamped deadline yet
    (`_session_expires_at` absent is treated as "not yet due", not
    "expired"), so this is a no-op for them on their first request after
    deploy — `_stamp_session_expiry` gives them a fresh deadline on that
    same response instead. The one residual gap this leaves: a
    non-remember-me cookie captured (XSS/log/devtools) in the narrow
    window between deploy and that session's next request keeps its old,
    unbounded-until-30-days replay property for one more grant of
    ``security.session_timeout_hours``. A hard cutover (immediate mass
    logout of every non-remember-me session) would close that but was
    rejected per this task's explicit instruction not to log everyone out
    unnecessarily.
    """
    if session.get("_remember_me") is not False:
        return
    expires_at = session.get(_SESSION_EXPIRES_AT_KEY)
    if expires_at is not None and _now_ts() >= expires_at:
        session.clear()


def _stamp_session_expiry(session) -> None:
    """(Re)stamp the non-remember-me deadline `_enforce_session_expiry`
    checks, sliding it forward on every response for an authenticated,
    non-remember-me session. No-op for anonymous or remember-me sessions.

    Runs from `DatabaseMiddleware`'s response-phase `send_wrapper` — i.e.
    after any route handler (including the login handler itself) has
    already run — so the very first Set-Cookie a non-remember-me login
    produces already carries a deadline, not just its second response
    onward. Sliding (refreshed on every authenticated response, like
    ``session_manager.SessionManager``'s ``last_access``-based timeout)
    rather than a fixed deadline from login time, matching
    ``security.session_timeout_hours``'s documented meaning: "Session
    timeout ... for sessions without 'Remember Me' checked" — an idle
    timeout, not a hard cap on total session length.
    """
    if session.get("username") and session.get("_remember_me") is False:
        session[_SESSION_EXPIRES_AT_KEY] = (
            _now_ts() + _NON_REMEMBER_ME_SESSION_SECONDS
        )


def _enforce_session_revocation(session, state: dict | None = None) -> None:
    """Clear `session` in place if its server-side record is gone.

    `require_auth` rejects a cookie whose `session_id` no longer resolves
    to the claimed username, which is what makes logout actually revoke a
    session rather than merely ask the browser to forget it. When this was
    added, two GET routes bypassed `require_auth` — `/` and `/auth/check` —
    because they must render/answer for anonymous visitors too, and both
    read `request.session["username"]` directly. A sweep of all 110 GET
    routes found exactly those two granting a revoked session strictly
    more than an anonymous one: after logout, a replayed cookie still
    rendered the authenticated index and still got `authenticated: true`,
    for the full remaining itsdangerous window. Both now call
    `require_auth` themselves (catching its 401), which also applies the
    per-session credential check this function does not perform.

    Enforcing revocation here as well means the property holds for every
    route by construction — including any future handler that reads the
    session without going through `require_auth`, which is precisely how
    these two got missed. Same placement rationale
    as `_enforce_session_expiry`: clearing the dict makes a revoked
    session indistinguishable from "never logged in" to everything
    downstream, so no call site needs to know about revocation.

    Anonymous sessions return immediately, so the cost on the hot path is
    one dict lookup; for authenticated ones it is `validate_session`: a
    dict read under a lock plus a re-projection of the user's durable
    rekey epoch (two small sidecar-file reads, `.rekey.pending` and
    `.rekey.epoch`), which is what lets a password change in another
    worker fence this session. That call also refreshes
    `last_access`, which is why this runs unconditionally rather than
    behind `_skip_prefixes` — same reasoning as the expiry check above.

    Note `session_manager.sessions` is in-memory, so a server restart
    invalidates every session. That is pre-existing `require_auth`
    behaviour, not something this widens: it already applied to every
    authenticated route. The only change is that `/` and `/auth/check`
    now agree with the rest of the app about who is logged in.

    A validated ``(session_id, username)`` is recorded in ``state`` (the
    request's ``scope["state"]``) under ``VALIDATED_SESSION_STATE_KEY`` so
    ``require_auth`` can skip an identical second epoch projection in the
    same request.

    Raises ``SessionValidationUnavailableError`` (session left untouched)
    when the durable epoch cannot be read; the caller answers 503, except
    for ``POST /auth/logout``, which it lets through unvalidated.
    """
    username = session.get("username")
    if not username:
        return

    from .auth.session_manager import (
        VALIDATED_SESSION_STATE_KEY,
        session_manager,
    )

    session_id = session.get("session_id")
    if not session_id or session_manager.validate_session(session_id) != (
        username
    ):
        session.clear()
    elif state is not None:
        state[VALIDATED_SESSION_STATE_KEY] = (session_id, username)


async def _send_session_validation_unavailable(scope, receive, send) -> None:
    """503 for a request whose session could not be validated right now.

    The session (and its cookie) is left alone: the epoch read failed
    transiently (e.g. EMFILE), which proves nothing about the session, so
    clearing it would log the user out. The request itself is refused,
    with the body ``require_auth``'s 503 gets from the HTTPException
    handler, so a client sees one shape whichever of the two refused it.
    """
    from .auth.session_manager import SESSION_VALIDATION_UNAVAILABLE_DETAIL

    response = JSONResponse(
        _http_exception_content(
            scope.get("path", ""), SESSION_VALIDATION_UNAVAILABLE_DETAIL
        ),
        status_code=503,
        headers={"Retry-After": "5"},
    )
    await response(scope, receive, send)


class DatabaseMiddleware:
    """Pure ASGI middleware to ensure user database is open for authenticated requests.

    Runs INSIDE SessionMiddleware so request.session is available. Also
    enforces/refreshes the non-remember-me session deadline (regression
    #1 — see `_enforce_session_expiry` / `_stamp_session_expiry` above)
    since this is the innermost app-level middleware: the last point to
    act on the session before any route handler runs. CSRFMiddleware runs
    outside it and reads the session first.
    """

    _skip_prefixes = (
        "/static/",
        "/favicon.ico",
        "/api/v1/health",
        "/auth/login",
        "/auth/register",
        "/auth/csrf-token",
        "/ws/",
    )

    def __init__(self, app):
        self.app = app

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        # One scope per request around everything below: the reopen of the
        # user's database, require_auth's probes and the route's own
        # database opens share a give-up flag for their waits on the user's
        # rekey sidecar (a wait that gives up sets it, and each later claim
        # then tries once without waiting, until one of them gets the
        # sidecar again; it is not a running total of the time waited), and
        # require_auth sees whether the reopen met a rekey fault (a 503
        # that keeps the session, not a 401). See request_database_scope.
        from .dependencies.auth import request_database_scope

        with request_database_scope():
            await self._call_http(scope, receive, send)

    async def _call_http(self, scope, receive, send):
        path = scope.get("path", "")
        method = scope.get("method", "GET")

        from ..utilities.request_context import (
            reset_request_user,
            set_request_user,
        )

        # Regression #1: enforce the shorter non-remember-me deadline
        # BEFORE the route handler can act on a session whose itsdangerous
        # signature is still valid but whose intended lifetime has passed.
        # CSRFMiddleware already read the session before this point. Runs
        # unconditionally (not gated by _skip_prefixes below) — it's a
        # cheap in-memory check/clear, not a DB open, and skipping it for
        # e.g. static-asset requests would let an idle-but-signature-valid
        # session's deadline silently stop advancing/enforcing whenever
        # the user's tab is only pulling static assets.
        unvalidated_logout = False
        session = scope.get("session")
        if session is not None:
            _enforce_session_expiry(session)
            # Same placement, same reason, different property: expiry is
            # "this session has been idle too long", revocation is "this
            # session was destroyed server-side (logout, password change)
            # but its signed cookie is still replayable". `require_auth`
            # covers the latter for the routes that use it; this covers
            # the ones that deliberately don't. See the docstring.
            from .auth.session_manager import (
                UNVALIDATED_LOGOUT_STATE_KEY,
                SessionValidationUnavailableError,
            )

            try:
                _enforce_session_revocation(
                    session, scope.setdefault("state", {})
                )
            except SessionValidationUnavailableError as unavailable:
                # Transient epoch-read failure: fail THIS request closed
                # without touching the session (no logout). Only the
                # errno number is logged.
                unreadable_errno = unavailable.errno
                if method == "POST" and path == "/auth/logout":
                    # Except logout: it only destroys (the caller's own
                    # session, its credentials, its cookie), so refusing it
                    # would only stop a user from revoking their session
                    # during the fault. It runs unvalidated: the flag tells
                    # the route to scope its teardown, and the database
                    # open below is skipped, so nothing is opened, stored
                    # or published for this cookie.
                    logger.warning(
                        "Letting logout through unvalidated: session "
                        f"epoch unreadable (errno={unreadable_errno})"
                    )
                    scope["state"][UNVALIDATED_LOGOUT_STATE_KEY] = True
                    unvalidated_logout = True
                else:
                    logger.warning(
                        "Refusing request with 503: session epoch "
                        f"unreadable (errno={unreadable_errno})"
                    )
                    await _send_session_validation_unavailable(
                        scope, receive, send
                    )
                    return

        ctx_tokens = None
        # Run the inner app first to let SessionMiddleware populate scope
        # Then ensure database is open
        if (
            method != "OPTIONS"
            and not unvalidated_logout
            and not any(path.startswith(p) for p in self._skip_prefixes)
        ):
            # Session data is in scope["session"] after SessionMiddleware
            session_data = scope.get("session", {})
            if session_data:
                from .dependencies.auth import ensure_user_database
                from .dependencies.threadpool import run_db_sync

                # Create a minimal request-like object for ensure_user_database
                class _MinimalRequest:
                    def __init__(self, session):
                        self.session = session

                # ensure_user_database opens a SQLCipher connection (PBKDF2
                # key derivation, file I/O) which would block the event loop
                # for hundreds of ms on first call after login. Offload to a
                # threadpool so concurrent requests don't serialize behind it.
                #
                # Use run_db_sync, not bare asyncio.to_thread: a cold
                # open_user_database() call runs the phase-2 rekey path
                # (_run_phase2_rekey -> rekey_user_indexes), which opens a
                # get_user_db_session() unconditionally, before its own
                # marker check (vector_stores/legacy_rekey.py). That leaves a
                # thread-local session on whichever asyncio default-executor
                # thread served this call, with no cleanup boundary --
                # asyncio.to_thread's executor is not drained by
                # DatabaseMiddleware (event-loop thread only) or by any
                # per-worker cleanup, only ever replaced when that pooled
                # thread later serves a different username.  run_db_sync
                # exists for exactly this: it runs the sync call on the same
                # default executor, then cleans up the thread-local DB
                # session (and other ambient thread-local state) on that
                # worker before returning.
                await run_db_sync(
                    ensure_user_database, _MinimalRequest(session_data)
                )

                # Publish username/session_id to a contextvar so service-layer
                # code that historically read flask_session can fall back
                # without requiring a Flask request context.
                ctx_tokens = set_request_user(
                    session_data.get("username"),
                    session_data.get("session_id"),
                )

        async def send_wrapper(message):
            if message["type"] == "http.response.start":
                # Regression #1: (re)stamp the non-remember-me deadline on
                # the way out, after the route handler (including a fresh
                # login) has had a chance to set username/_remember_me.
                # See _stamp_session_expiry's docstring.
                current_session = scope.get("session")
                if current_session is not None:
                    _stamp_session_expiry(current_session)
            await send(message)

        try:
            await self.app(scope, receive, send_wrapper)
        finally:
            if ctx_tokens is not None:
                reset_request_user(ctx_tokens)

            # Cleanup after request.
            #
            # Keep the two sweeps independent so one failure cannot skip the
            # other. This async middleware can clean event-loop-owned state;
            # WorkerCleanupAPIRoute already reclaimed a synchronous
            # endpoint's AnyIO-worker state before control returned here.
            # Pinned by tests/web/test_teardown_cleanup_asgi.py and
            # tests/web/test_db_session_lifecycle_asgi.py.
            try:
                from ..database.thread_local_session import (
                    cleanup_dead_threads,
                )

                cleanup_dead_threads()
            except Exception:
                logger.debug("Error during post-request dead-thread cleanup")

            try:
                from ..database.thread_local_session import (
                    cleanup_current_thread,
                )

                cleanup_current_thread()
            except Exception:
                logger.debug("Error during post-request current-thread cleanup")


# ---------------------------------------------------------------------------
# Request-arrival/duration forensics (CI/TESTING only) — issue #4431
# ---------------------------------------------------------------------------


class RequestTimingASGIMiddleware:
    """Pure ASGI port of ``web/utils/request_timing.RequestTimingMiddleware``.

    Named ``...ASGIMiddleware`` rather than reusing the original's name on
    purpose: both classes live in the same package, and one of them is a
    WSGI callable that would fail silently and confusingly if handed to
    ``add_middleware``.

    That module is a plain WSGI callable (``__call__(environ,
    start_response)``) — main installed it by wrapping ``app.wsgi_app`` in
    ``app_factory.create_app`` under CI/TESTING (#4536), and the FastAPI
    migration deleted ``app_factory.py`` and lost the wiring with it (#5959).
    A WSGI callable cannot be handed to ``app.add_middleware``, so the
    transport half is re-expressed here while the *policy* half — the log
    format the CI log-grep keys on, the slow-completion threshold, and the
    faulthandler freeze dead-man's switch — is imported from the original
    module so there is exactly one definition of each.

    Pure ASGI rather than ``BaseHTTPMiddleware`` for the same reason as
    ``BodySizeLimitMiddleware`` / ``_PathScopedCORSMiddleware``: this sits
    outside the streaming SSE routes and ``BaseHTTPMiddleware`` buffers
    ``StreamingResponse`` bodies.

    One deliberate difference from the WSGI original: the duration here
    covers the whole downstream ASGI call, i.e. arrival through the final
    response body — which is what #4431 actually wants to measure — rather
    than WSGI view execution with response streaming excluded. The arrival
    line, whose *absence* during a navigation timeout is the real signal,
    is byte-identical.
    """

    def __init__(self, app):
        self.app = app
        from .utils.request_timing import _arm_freeze_dump

        # Arm the freeze thread-dump dead-man's switch (no-op under pytest).
        _arm_freeze_dump()

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            # CORS-style scoping: the forensics are about HTTP request
            # arrival. lifespan/websocket scopes pass straight through.
            await self.app(scope, receive, send)
            return

        from .utils.request_timing import (
            SLOW_REQUEST_SECONDS,
            _arm_freeze_dump,
        )

        # Re-arm the dead-man's switch: as long as requests keep arriving the
        # dump never fires; a freeze (no arrivals) lets it fire and capture
        # the stuck thread stacks.
        _arm_freeze_dump()

        method = scope.get("method", "-")
        path = scope.get("path", "-")
        # engine.io transport/sid make poll churn correlatable. (sid is
        # logged on purpose for correlation; logs are CI-only artifacts.)
        if path.startswith("/socket.io"):
            query = scope.get("query_string", b"").decode("latin-1", "replace")
            path = f"{path}?{query}" if query else path
        # Strip CR/LF so a crafted path/query cannot inject fake log lines
        # (the forensics output is grep'd downstream).
        path = path.replace("\r", "\\r").replace("\n", "\\n")
        logger.info(f"[req] > {method} {path}")
        start = time.monotonic()
        try:
            await self.app(scope, receive, send)
        finally:
            elapsed = time.monotonic() - start
            if elapsed >= SLOW_REQUEST_SECONDS:
                logger.warning(f"[req] < {method} {path} {elapsed:.1f}s SLOW")
            else:
                logger.info(f"[req] < {method} {path} {elapsed:.2f}s")


def _request_timing_enabled() -> bool:
    """Whether to install :class:`RequestTimingASGIMiddleware` on this process.

    main's gate was ``os.environ.get("CI") or os.environ.get("TESTING")``,
    kept verbatim, plus one addition: never inside a pytest process.

    The diagnostic exists for the long-running UI-shard server, which CI
    starts as its own process (``python -m local_deep_research.web.app``)
    with ``CI`` set — pytest is not imported there, so the gate still arms
    exactly where #4431 needs it. The pytest exclusion mirrors
    ``request_timing._should_arm_freeze_dump``'s own reasoning (that module
    already refuses to arm the faulthandler timer under pytest) and keeps
    the in-process middleware stack that
    ``tests/web/test_middleware_order_and_headers.py`` pins byte-identical
    on a CI runner, where ``CI=true`` is set for the unit-test job too.
    """
    if "pytest" in sys.modules:
        return False
    return bool(os.environ.get("CI") or os.environ.get("TESTING"))


# ---------------------------------------------------------------------------
# Rate limiting
# ---------------------------------------------------------------------------


def _setup_rate_limiting(app: FastAPI) -> None:
    """Configure slowapi rate limiting on the app."""
    from slowapi.errors import RateLimitExceeded
    from slowapi.middleware import SlowAPIMiddleware

    from ..security.log_sanitizer import sanitize_for_log
    from .dependencies.rate_limit import _get_client_ip, limiter

    app.state.limiter = limiter

    # Deliberately `def`, not `async def`. slowapi's SlowAPIMiddleware handles
    # the global default limits through `sync_check_limits`, which cannot await
    # and therefore DISCARDS an async handler outright:
    #
    #   # cannot execute asynchronous code in a synchronous middleware,
    #   # -> fallback on default exception handler
    #   if inspect.iscoroutinefunction(exception_handler):
    #       exception_handler = _rate_limit_exceeded_handler
    #                                       (slowapi/middleware.py)
    #
    # While this was `async def`, every 429 raised by the middleware path — i.e.
    # every undecorated route hitting the global default — silently used
    # slowapi's stock handler instead of this one, losing the audit warning
    # below, the Retry-After headers, and main's {"error", "message"} body
    # contract. Only routes carrying an explicit @limiter.limit decorator
    # (the async path) ever reached this function. Nothing here awaits, so
    # making it sync costs nothing and covers both paths.
    def _rate_limit_exceeded(request: Request, exc: RateLimitExceeded):
        # Audit logging for security monitoring — port of main's 429
        # errorhandler. _get_client_ip resolves the real IP behind
        # trusted proxies (raw request.client would log the proxy).
        # Every field is client-influenced, so each goes through
        # sanitize_for_log (control, format and line-break characters
        # stripped, length capped). The line is space-delimited
        # ``field=value``, so the free-text fields are also JSON-quoted:
        # json.dumps always double-quotes and escapes ``"`` and ``\``, so a
        # key=value reader cannot find a field boundary inside the value
        # (repr() would switch to single quotes for a value containing
        # ``"``, which such a reader does not honour). The ip value is
        # always a validated address or a fixed token (_get_client_ip), so
        # it stays unquoted.
        path = sanitize_for_log(request.url.path, max_length=200)
        user_agent = sanitize_for_log(
            request.headers.get("User-Agent", "unknown"), max_length=200
        )
        logger.warning(
            "Rate limit exceeded: "
            f"endpoint={json.dumps(path)} "
            f"ip={sanitize_for_log(_get_client_ip(request), max_length=64)} "
            f"user_agent={json.dumps(user_agent)}"
        )
        response = JSONResponse(
            {
                "error": "Too many requests",
                "message": "Too many attempts. Please try again later.",
            },
            status_code=429,
            # Stamp the security headers here, the same way the catch-all 500
            # handler does. `_setup_rate_limiting` runs AFTER
            # `add_middleware(SecurityHeadersMiddleware)`, and Starlette's
            # add_middleware is LIFO, so SlowAPIMiddleware ends up OUTSIDE
            # SecurityHeadersMiddleware — a 429 it generates never passes
            # through it and would otherwise ship with no CSP, no nosniff, no
            # X-Frame-Options and no Cache-Control. Reordering the stack would
            # be the alternative, but the order is deliberately pinned by
            # tests/web/test_middleware_order_and_headers.py.
            headers={
                name.decode(): value.decode()
                for name, value in SecurityHeadersMiddleware.response_headers(
                    path=request.url.path,
                    scheme=request.url.scheme,
                    status=429,
                    scope=request.scope,
                )
            },
        )
        # Restore Retry-After / X-RateLimit-* on 429s. `headers_enabled=True`
        # on the Limiter (dependencies/rate_limit.py) alone does not add
        # them — slowapi only injects headers when a caller invokes
        # `_inject_headers` itself, which its own default
        # `_rate_limit_exceeded_handler` (slowapi/extension.py) does; this
        # app registers a custom handler instead (for the audit log line
        # above and main's ``{"error", "message"}`` body contract) and,
        # before this fix, never called it, so live 429s carried none of
        # these headers even with the flag on. Flask-Limiter added them on
        # main via its own ``after_request`` hook — no direct FastAPI
        # equivalent exists, so it has to happen here, per-handler.
        #
        # Uses the `limiter` closed over above (same object as
        # `app.state.limiter`) rather than going through
        # `request.app.state.limiter` — the two are identical for the real
        # app, but the latter forces every caller of this handler to have
        # a real `request.app`, and tests/web/test_rate_limit_coverage.py
        # ::TestRateLimitExceededHandler calls this handler directly with
        # a bare ``Mock()`` request (pinning the audit-log/body contract in
        # isolation, unrelated to this fix). Going through `request.app`
        # there silently replaces `response` with an auto-generated Mock
        # instead of exercising real header-injection logic.
        #
        # `request.state.view_rate_limit` is set by slowapi's
        # `Limiter.__evaluate_limits` (private method) immediately before
        # it raises `RateLimitExceeded` — verified against the installed
        # slowapi source (`.venv/lib/*/site-packages/slowapi/__init__.py`)
        # rather than assumed, since both the attribute and
        # `_inject_headers` are private slowapi API that could rename
        # across versions. The whole call is wrapped in a try/except
        # (rather than trusting `_inject_headers`'s own internal
        # swallow_errors — this Limiter is built with
        # `swallow_errors=False`, i.e. it re-raises) so nothing about this
        # best-effort header injection — a missing `view_rate_limit`, a
        # storage hiccup, or (as in the Mock-request test above) a
        # request.state that doesn't behave like a real one — can ever
        # turn a 429 into a 500. On any failure `response` simply keeps
        # its original value, assigned before the `try`.
        #
        # tests/web/test_rate_limit_headers_on_429.py pins this against a
        # real 429 from a real rate-limited route so a future slowapi
        # rename of either private symbol fails loudly here instead of
        # silently dropping the headers again.
        # Set the headers directly rather than calling
        # `limiter._inject_headers`. That method is gated on the Limiter's
        # `_headers_enabled`, and this app deliberately leaves that flag OFF
        # — turning it on makes slowapi wrap EVERY rate-limited route and
        # raise on any handler that returns a plain dict instead of a
        # Response, turning ordinary 200s into 500s (see the comment on
        # `_limiter_kwargs` in dependencies/rate_limit.py). So calling
        # `_inject_headers` here would silently no-op; the values have to be
        # computed here instead.
        try:
            current_limit = getattr(request.state, "view_rate_limit", None)
            if current_limit is not None:
                item, key_parts = current_limit
                reset_at, remaining = limiter.limiter.get_window_stats(
                    item, *key_parts
                )
                response.headers["Retry-After"] = str(
                    max(0, int(reset_at - time.time()))
                )
                response.headers["X-RateLimit-Limit"] = str(item.amount)
                response.headers["X-RateLimit-Remaining"] = str(remaining)
                response.headers["X-RateLimit-Reset"] = str(int(reset_at))
        except Exception:
            logger.debug(
                "Could not attach Retry-After/X-RateLimit-* headers to the "
                "429 response; returning it without them."
            )
        return response

    app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded)

    # Enforce the global DEFAULT_RATE_LIMIT on every route without an
    # explicit limit decorator (decorated routes are exempt here — their
    # decorators handle their own checks; mounts like /ws have no route
    # handler and are skipped). Flask-Limiter's default_limits behaved
    # the same way on main.
    app.add_middleware(SlowAPIMiddleware)


# ---------------------------------------------------------------------------
# Static file serving
# ---------------------------------------------------------------------------


def _add_static_routes(app: FastAPI) -> None:
    """Add static file serving routes with cache control."""
    from .static_files import static_file_response

    static_dir = Path(STATIC_DIR)

    # Static assets must not share the API's default per-IP bucket: base.html
    # alone pulls ~29 assets, served must-revalidate, so a few page loads
    # could exhaust a user's whole hourly budget. main exempted these.
    from .dependencies.rate_limit import limiter as _limiter

    @app.get("/favicon.ico", include_in_schema=False)
    @_limiter.exempt
    async def favicon():
        from fastapi.responses import FileResponse

        favicon_path = static_dir / "favicon.ico"
        if favicon_path.exists():
            return FileResponse(str(favicon_path), media_type="image/x-icon")
        return JSONResponse({"error": "Not found"}, status_code=404)

    @app.get("/static/{path:path}", include_in_schema=False)
    @_limiter.exempt
    async def serve_static(path: str):
        response = static_file_response(path)
        if response is not None:
            return response
        return JSONResponse({"error": "Not found"}, status_code=404)


# ---------------------------------------------------------------------------
# Template helpers (replaces Flask's context_processor / jinja_env.globals)
# ---------------------------------------------------------------------------

# Matches url_for('name') / url_for("name") usages in templates. Shared by
# _validate_url_for_bindings (below) and
# tests/web/templates/test_url_for_links.py, which independently extracts
# the same names to fence dead links.
_URL_FOR_NAME_RE = re.compile(r"url_for\(\s*['\"]([^'\"]+)['\"]")


def _setup_template_globals() -> None:
    """Register template globals for Jinja2 (CSRF, url_for, flash, vite, themes, etc.)."""
    env = templates.env

    # Vite asset helpers (must be registered at module level, not in lifespan)
    from .utils.vite_helper import vite

    vite.init_for_fastapi(STATIC_DIR, templates)

    # CSRF token — needs request, so we provide a callable that reads from
    # the template context (where request is passed per-render).
    # Templates call {{ csrf_token() }} which reads _csrf_request from context.

    def csrf_token_factory():
        """Returns empty string by default. Overridden per-request via context."""
        return ""

    env.globals["csrf_token"] = csrf_token_factory

    # Flash messages — same pattern: needs request.
    env.globals["get_flashed_messages"] = lambda with_categories=False: []

    # Theme helpers
    from ..defaults import get_default_theme
    from .themes import get_theme_metadata, get_themes, get_themes_json

    # Hashed is the registered dark palette, preferred while light themes
    # need refinement. Export the shared setting for HTML and browser startup.
    env.globals["default_theme"] = get_default_theme()
    env.globals["get_themes"] = get_themes
    env.globals["get_themes_json"] = get_themes_json
    env.globals["get_theme_metadata"] = get_theme_metadata

    # Session — default empty dict, overridden per-request via context
    env.globals["session"] = {}

    # Egress scope — default to the registered fallback so templates
    # rendered WITHOUT render_template() (e.g. the index route's direct
    # TemplateResponse) can still reference egress_scope on
    # <body data-scope=…> without raising an UndefinedError. render_template()
    # overrides this per-render with the user's resolved scope.
    from ..security.egress.policy import DEFAULT_EGRESS_SCOPE

    env.globals["egress_scope"] = DEFAULT_EGRESS_SCOPE

    # Kept INSIDE this function as a single direct dict literal, not hoisted
    # to module scope: .pre-commit-hooks/check-url-for-targets.py parses this
    # function statically and requires exactly one literal map here ("Expected
    # one direct literal map"). _validate_url_for_bindings does not need the
    # dict — it resolves names through templates.env.globals["url_for"], the
    # same closure the templates use.
    # url_for wrapper map (Flask-style blueprint.endpoint -> path).
    _URL_MAP = {
        # Auth
        "auth.login": "/auth/login",
        "auth.login_page": "/auth/login",
        "auth.register": "/auth/register",
        "auth.register_page": "/auth/register",
        "auth.logout": "/auth/logout",
        "auth.change_password": "/auth/change-password",
        "auth.change_password_page": "/auth/change-password",
        # Pages
        "index": "/",
        "static": "/static",
        "history.history_page": "/history/",
        "chat.chat_page": "/chat/",
        # Library / RAG
        "library.library_page": "/library/",
        "library.download_manager_page": "/library/download-manager",
        "rag.collections_page": "/library/collections",
        "rag.embedding_settings_page": "/library/embedding-settings",
        # Zotero page lives under the /library prefix; without this the
        # dot-to-slash fallback yields a dead /zotero/zotero_page link.
        "zotero.zotero_page": "/library/zotero",
        # Notes + unified-search pages (the dot-to-slash fallback would
        # otherwise produce /notes/notes_page and
        # /unified_search/unified_search_page dead links).
        "notes.notes_page": "/notes/",
        "unified_search.unified_search_page": "/library/search/",
        # News
        "news.news_page": "/news/",
        "news.subscriptions_page": "/news/subscriptions",
        # Metrics
        "metrics.metrics_dashboard": "/metrics/",
        "metrics.journal_quality": "/metrics/journals",
        # Benchmark
        "benchmark.index": "/benchmark/",
        # Currently also produced by the dot-to-slash fallback, but pin it
        # so a rename of the route function can't silently break the
        # sidebar link.
        "benchmark.results": "/benchmark/results",
        # Settings (page + form action)
        "settings.settings_page": "/settings/",
        "settings.save_settings": "/settings/save_settings",
        "settings.save_all_settings": "/settings/save_all_settings",
        "settings.main_config_page": "/settings/main",
        "settings.collections_config_page": "/settings/collections",
        "settings.api_keys_config_page": "/settings/api_keys",
        "settings.llm_config_page": "/settings/llm",
        "settings.search_engines_config_page": "/settings/search_engines",
    }

    def url_for(name, **kwargs):
        path = _URL_MAP.get(name, f"/{name.replace('.', '/')}")
        if name == "static" and "filename" in kwargs:
            path = f"/static/{kwargs['filename']}"
        elif name == "static" and "path" in kwargs:
            path = f"/static/{kwargs['path']}"
        # Append query params
        query_params = {
            k: v for k, v in kwargs.items() if k not in ("filename", "path")
        }
        if query_params:
            from urllib.parse import urlencode

            path += "?" + urlencode(query_params)
        return path

    env.globals["url_for"] = url_for


# ---------------------------------------------------------------------------
# Create the FastAPI application
# ---------------------------------------------------------------------------

# Deliberately does NOT check the generic `CI` / `TESTING` variables, which an
# earlier version did. This flag suppresses the `Secure` attribute on session
# cookies (SecureCookieMiddleware) *and* both operator warnings about serving
# a public instance over plain HTTP, so any CD pipeline or PaaS that exports
# CI=true would have shipped session cookies without `Secure` over HTTPS, and
# silenced the warning that would have said so.
#
# This is the same reasoning already written down in
# database/sqlcipher_utils.py::_get_min_kdf_iterations, which refuses to relax
# the KDF floor on CI/TESTING for exactly this reason. The cookie path had not
# been given that treatment.
#
# Only the explicit operator switch controls cookie test mode. Pytest's
# per-test marker changes between collection and execution, so consulting it
# here would make cookie protection and docs exposure depend on import order.
# Keep the production cookie behavior by default, including under pytest.
# LDR_TEST_MODE is parsed as a boolean, so "0" and "false" do not enable it.
is_testing = to_bool(os.getenv("LDR_TEST_MODE"))

# Public API docs are disabled by default — a multi-user deployment
# shouldn't expose the full schema unauthenticated. Set LDR_EXPOSE_DOCS=true
# to re-enable (useful for internal/dev instances).
_expose_docs = os.getenv("LDR_EXPOSE_DOCS", "").lower() in ("true", "1", "yes")
_docs_enabled = _expose_docs and not is_testing

app = FastAPI(
    title="Local Deep Research",
    version=__version__,
    docs_url="/api/docs" if _docs_enabled else None,
    # Gate the OpenAPI schema endpoint together with the Swagger UI:
    # /openapi.json IS the full API schema, so leaving it on its default
    # "/openapi.json" while disabling docs_url still exposes the entire
    # surface unauthenticated. app.openapi() remains callable in-process.
    openapi_url="/openapi.json" if _docs_enabled else None,
    redoc_url=None,
    lifespan=lifespan,
)

# FastAPI runs plain ``def`` endpoints on AnyIO workers, whereas ASGI
# middleware teardown runs on the event-loop thread.  Install an endpoint
# wrapper so thread-local DB sessions are released on the worker that owns
# them. Populated module routers receive the same dispatch wrapper in
# ``_mount_all`` without replacing their registered endpoint objects.
from .dependencies.threadpool import WorkerCleanupAPIRoute  # noqa: E402

app.router.route_class = WorkerCleanupAPIRoute

# ASGI middleware stack.
# Starlette add_middleware is LIFO: last added = outermost.
# Desired order (outer→inner): SecureCookie → SecurityHeaders → Session → CSRF → Database → app
#
# So we add in reverse: Database first, then CSRF, then Session, etc.

app.add_middleware(DatabaseMiddleware)

# CSRF runs after Session populates scope["session"] and rejects state-changing
# requests with a missing/invalid X-CSRFToken header before they reach handlers.
from .dependencies.csrf import CSRFMiddleware  # noqa: E402

app.add_middleware(CSRFMiddleware)

app.add_middleware(
    SessionMiddleware,
    secret_key=SECRET_KEY,
    session_cookie="session",
    max_age=get_security_default("security.session_remember_me_days", 30)
    * 24
    * 3600,
    # Include the login cookie on safe top-level navigation from other sites.
    # Lax still withholds it from cross-site unsafe requests, and
    # CSRFMiddleware requires the session token on unsafe methods. But Lax
    # lets another site's link open any page signed in, so GET routes must
    # not change state (indexing and model discovery use POST), and a
    # page-load script must not turn URL parameters into a state-changing
    # request, which would carry the page's own CSRF token. chat.js only
    # pre-fills `?q=` into a chat without messages, without focus, and never
    # sends it by itself; the chat page also redirects `?q=` away from links
    # that Sec-Fetch-Site marks as coming from another origin
    # (web/routers/chat.py), and the login page drops it from a chat `next`
    # (web/routers/auth.py). The main form submits its chat message through
    # the protected API before opening the chat, without browser staging.
    same_site="lax",
    https_only=False,  # Handled dynamically by SecureCookieMiddleware
)

# Runs just outside SessionMiddleware so it sees the Set-Cookie
# header SessionMiddleware just wrote, and can strip Max-Age/Expires
# for non-remember-me logins. See the class docstring.
app.add_middleware(RememberMeMiddleware)

# Body cap sits inside SecurityHeaders so its 413 responses still get
# security headers, but outside Session/CSRF so over-limit bodies are
# rejected before anything buffers them.
app.add_middleware(BodySizeLimitMiddleware)

app.add_middleware(SecurityHeadersMiddleware)
app.add_middleware(SecureCookieMiddleware, testing=is_testing)


# Prefixes that carried CORS headers on main. `SecurityHeaders._is_api_route`
# (security/security_headers.py, deleted by the FastAPI migration) gated CORS to
# exactly these three, so an operator who whitelisted an origin for API access
# did not thereby grant it cross-origin reads of every HTML page. Restored here.
_CORS_API_PREFIXES = ("/api/", "/research/api/", "/history/api")


class _PathScopedCORSMiddleware:
    """Apply Starlette's CORSMiddleware only to API paths.

    Starlette's CORSMiddleware has no path predicate: mounted app-wide it
    answers preflights and stamps `Access-Control-Allow-Origin` on every route,
    HTML pages included. main scoped that to three prefixes and the migration
    dropped the scoping along with `_is_api_route`.

    Pure ASGI rather than BaseHTTPMiddleware, deliberately: this sits in front
    of the streaming SSE routes, and BaseHTTPMiddleware buffers
    StreamingResponse bodies (the defect already tracked for
    SlowAPIMiddleware). Non-matching paths are handed to the inner app
    untouched, so the pass-through case adds one string comparison and no
    wrapping at all.

    Non-HTTP scopes (websocket, lifespan) bypass CORS entirely — the CORS
    protocol is HTTP-only, and the Socket.IO mount does its own origin check.
    """

    def __init__(self, app, prefixes, cors_factory):
        self.app = app
        self.prefixes = tuple(prefixes)
        # Build the real CORSMiddleware once, wrapping the inner app, so a
        # matching request gets Starlette's full preflight/origin handling.
        self.cors_app = cors_factory(app)

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return
        path = scope.get("path", "")
        if path.startswith(self.prefixes):
            await self.cors_app(scope, receive, send)
        else:
            await self.app(scope, receive, send)


def _configure_cors(app: FastAPI) -> None:
    """Restore configurable cross-origin access for API clients.

    Ports the CORS support main applied in security_headers.py from
    ``security.cors.allowed_origins`` (env: LDR_SECURITY_CORS_ALLOWED_ORIGINS),
    which the FastAPI migration dropped — the setting was live config on
    main but reached no code on this branch. Uses Starlette's
    CORSMiddleware (correct preflight/OPTIONS handling, origin matching)
    rather than hand-injecting headers.

    Fail closed: with the setting empty (the default) no CORS middleware
    is registered, so the app stays same-origin only — exactly main's
    empty-default behavior. Same-origin requests carry no Origin header
    and never receive CORS headers regardless, so this is effectively
    scoped to genuine cross-origin API calls. A separator-only value
    (e.g. ``","``) parses to no origins at all and is treated the same
    way — no middleware registered — rather than as an allowlist that
    can never match anything.
    """
    from ..settings.env_registry import get_env_setting

    configured = get_env_setting("security.cors.allowed_origins")
    if not configured:
        return

    if configured.strip() == "*":
        # Credentials with a wildcard origin is forbidden by the CORS spec
        # (and was a startup error on main). Allow the wildcard for
        # non-credentialed access only.
        origins = ["*"]
        allow_credentials = False
    else:
        origins = [o.strip() for o in configured.split(",") if o.strip()]
        allow_credentials = False
        if not origins:
            # Every entry was empty (e.g. "," or " , "): the same intent
            # as unset. Registering middleware here would produce an
            # allowlist that can never match any Origin and a "CORS
            # enabled for API origins: []" log that misleadingly claims
            # CORS is on, so treat it exactly like the unset case above.
            return

    from starlette.middleware.cors import CORSMiddleware

    app.add_middleware(
        _PathScopedCORSMiddleware,
        prefixes=_CORS_API_PREFIXES,
        cors_factory=lambda inner: CORSMiddleware(
            inner,
            allow_origins=origins,
            allow_credentials=allow_credentials,
            allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
            allow_headers=[
                "Content-Type",
                "Authorization",
                "X-Requested-With",
                "X-HTTP-Method-Override",
                "X-CSRFToken",
            ],
            max_age=3600,
        ),
    )
    logger.info(
        f"CORS enabled for API origins: {origins} "
        f"(scoped to {', '.join(_CORS_API_PREFIXES)})"
    )


# Rate limiting via slowapi + exception handlers
_setup_rate_limiting(app)
_register_exception_handlers(app)

# Registered last of the request-handling middleware, so it is the outermost
# of them: a preflight OPTIONS is answered before auth, CSRF, or rate limiting
# ever run. (The CI-only request-timing layer below is added after it and so
# sits further out still, but it only logs and passes every scope through, so
# it changes nothing about that ordering.)
_configure_cors(app)

# CI/test-only request forensics for the #4431 navigation-stall hunts: logs
# every request's arrival + duration so a silent log window can be attributed
# to "request never arrived" vs "request hung in the app". Ports #4536, which
# merge 5ad5f5a1b reverted along with app_factory.py (#5959). Added LAST of
# all `add_middleware` calls because that list is LIFO — last added is
# outermost — which is the only position from which it measures true
# arrival-to-response time.
if _request_timing_enabled():
    app.add_middleware(RequestTimingASGIMiddleware)
    logger.info("Request-timing forensics middleware enabled (CI/TESTING)")

# Static file routes
_add_static_routes(app)

# Template globals
_setup_template_globals()

# ---------------------------------------------------------------------------
# Mount routers and Socket.IO (deferred imports to avoid E402)
# ---------------------------------------------------------------------------


def _mount_all(app: FastAPI) -> None:
    """Mount all routers and Socket.IO on the app."""
    from ..database.session_context import (
        DatabaseSessionUnavailableError,
        get_user_db_session,
    )
    from ..settings.logger import log_settings
    from ..utilities.db_utils import get_settings_manager
    from .dependencies.threadpool import prepare_router_for_worker_cleanup
    from .routers.api_v1 import router as api_v1_router
    from .services.socketio_asgi import socket_app

    # Mount Socket.IO
    app.mount("/ws", socket_app)

    # Include all routers — error-tolerant loading during migration.
    # Routers with unresolved import issues will be skipped with a warning.
    _routers = {
        "api_v1": api_v1_router,
    }

    # Phase 2+ routers — Phase 2-7 is complete; an import error here is a
    # production-class regression, not a migration-in-progress signal. Fail
    # loud at startup instead of silently serving 404 for the whole router.
    _router_modules = [
        ("auth", ".routers.auth"),
        ("research", ".routers.research"),
        ("history", ".routers.history"),
        ("settings", ".routers.settings"),
        ("metrics", ".routers.metrics"),
        ("api", ".routers.api"),
        ("context_overflow", ".routers.context_overflow_api"),
        ("news_api", ".routers.news_flask_api"),
        ("news_pages", ".routers.news_pages"),
        ("benchmark", ".routers.benchmark"),
        ("followup", ".routers.followup"),
        ("library", ".routers.library"),
        ("rag", ".routers.rag"),
        ("library_delete", ".routers.library_delete"),
        ("library_search", ".routers.library_search"),
        ("zotero", ".routers.zotero"),
        ("notes", ".routers.notes"),
        ("unified_search", ".routers.unified_search"),
        ("scheduler", ".routers.scheduler"),
        ("chat", ".routers.chat"),
    ]

    import importlib

    for name, module_path in _router_modules:
        mod = importlib.import_module(module_path, package=__package__)
        if not hasattr(mod, "router"):
            raise RuntimeError(
                f"Router module '{module_path}' has no 'router' attribute"
            )
        _routers[name] = mod.router

    for name, r in _routers.items():
        app.include_router(r)

    # include_router() preserves the source APIRoute class rather than using
    # app.router.route_class for already-populated module routers. Apply the
    # cleanup to the copied dispatch targets after every router is mounted;
    # route.endpoint remains the original handler for introspection, SlowAPI,
    # and route-identity security checks.
    prepare_router_for_worker_cleanup(app.router)

    @app.get("/", include_in_schema=False)
    def index(request: Request):
        """Root route - redirect to login if not authenticated."""
        if not request.session.get("username"):
            return RedirectResponse(url="/auth/login", status_code=302)

        # Same gate as every protected route. Reading the username from the
        # cookie alone would let a session that lost its own credential render
        # the user's saved settings: without a session-scoped password,
        # get_user_db_session falls back to a sibling session's password.
        # require_auth rejects that session (and revokes it) instead.
        from .dependencies.auth import (
            database_unavailable_exception,
            end_rejected_session,
            require_auth,
        )

        try:
            username = require_auth(request)
        except HTTPException as exc:
            if exc.status_code == 503:
                # The retryable 503 of a database that cannot be checked
                # right now: for a browser, the branded page that retries
                # here; for a JSON caller, or if it cannot render, the
                # 503 itself. The session is kept either way.
                page = _database_unavailable_page(request, exc)
                if page is None:
                    raise
                return page
            if exc.status_code != 401:
                raise
            # One require_auth 401 keeps the cookie (database not connected
            # but still recoverable). /auth/login sends any cookie with a
            # username back here, so redirecting without ending the session
            # would loop. Every protected page's 401 funnels through here.
            end_rejected_session(request)
            return RedirectResponse(url="/auth/login", status_code=302)

        from ..constants import get_available_strategies
        from ..security.egress.policy import (
            DEFAULT_EGRESS_SCOPE,
            effective_scope_for_display,
            unprotected_egress_allowed,
        )
        from ..settings.exceptions import SettingsValueError
        from ..settings.manager import check_env_setting

        settings = {}
        try:
            with get_user_db_session(
                username, session_id=request.session.get("session_id")
            ) as db_session:
                if db_session:
                    sm = get_settings_manager(db_session, username)
                    # Operator-gated escape hatch (#5148 / 87537d9ec): the
                    # raw stored scope may be a legacy/invalid value or an
                    # "unprotected" selection the operator has since
                    # disabled — normalise what we DISPLAY through the same
                    # helper the policy engine uses so the UI never shows a
                    # scope the run-time layer would reject. allow_
                    # unprotected_egress gates the <option value="unprotected">
                    # entry in research.html's select; the *_env_locked flags
                    # let it grey out controls the operator pinned via env
                    # vars (server-side overrides are enforced independently
                    # in routers/research.py::_apply_policy_overrides).
                    raw_egress_scope = sm.get_setting(
                        "policy.egress_scope", DEFAULT_EGRESS_SCOPE
                    )
                    effective_egress_scope = effective_scope_for_display(
                        raw_egress_scope
                    )
                    settings = {
                        "llm_provider": sm.get_setting(
                            "llm.provider", "ollama"
                        ),
                        "llm_model": sm.get_setting("llm.model", ""),
                        "llm_openai_endpoint_url": sm.get_setting(
                            "llm.openai_endpoint.url", ""
                        ),
                        "llm_ollama_url": sm.get_setting("llm.ollama.url"),
                        "llm_lmstudio_url": sm.get_setting("llm.lmstudio.url"),
                        "llm_local_context_window_size": sm.get_setting(
                            "llm.local_context_window_size"
                        ),
                        "search_tool": sm.get_setting("search.tool", ""),
                        "search_iterations": sm.get_setting(
                            "search.iterations", 3
                        ),
                        "search_questions_per_iteration": sm.get_setting(
                            "search.questions_per_iteration", 2
                        ),
                        "search_strategy": sm.get_setting(
                            "search.search_strategy", "source-based"
                        ),
                        # Egress-policy controls (Stage 1c UI) — main loads
                        # these so the research page reflects the saved policy
                        # instead of silently defaulting (fail-open).
                        "policy_egress_scope": effective_egress_scope,
                        "egress_scope_env_locked": check_env_setting(
                            "policy.egress_scope"
                        )
                        is not None,
                        "allow_unprotected_egress": unprotected_egress_allowed(),
                        "llm_local_env_locked": check_env_setting(
                            "llm.require_local_endpoint"
                        )
                        is not None,
                        "embeddings_local_env_locked": check_env_setting(
                            "embeddings.require_local"
                        )
                        is not None,
                        "llm_require_local_endpoint": sm.get_setting(
                            "llm.require_local_endpoint", False
                        ),
                        "embeddings_require_local": sm.get_setting(
                            "embeddings.require_local", False
                        ),
                    }
        except DatabaseSessionUnavailableError:
            # require_auth's probe succeeded, but opening the session for the
            # settings read then met a rekey sidecar or epoch fault: an
            # fd-exhaustion spike can clear and come back between the two
            # probes. It says nothing about this session, so answer
            # require_auth's own retryable 503 and keep the cookie, the
            # server-side session and the stored password, rather than the
            # logout below (a browser gets it as the branded page that
            # retries here). get_user_db_session already logged the fault's
            # type name.
            logger.warning(
                "Root route could not open the database for user {}; "
                "answering 503 and keeping the session",
                username,
            )
            unavailable = database_unavailable_exception()
            page = _database_unavailable_page(request, unavailable)
            if page is None:
                raise unavailable from None
            return page
        except SettingsValueError:
            # An invalid configured setting is not the password case below.
            # Clearing the session would only send the user back here after
            # the next login, where the same read fails again: a login
            # loop. The app's SettingsValueError handler shows the
            # diagnostic instead, and the session is kept.
            raise
        except Exception:
            # Password not available (e.g. server restarted) — force re-login.
            #
            # Log before redirecting. This handler wraps ~70 lines (session
            # acquisition, settings manager, egress scope, and 18 get_setting
            # calls) on the app's ROOT route, so it catches far more than the
            # documented password case — a bug in any of those reads presents
            # to the user as "I keep getting randomly logged out" and left no
            # trace at any log level. Flask had no try/except here at all
            # (web/app_factory.py's index()), so the same fault produced a
            # logged 500; swallowing it silently is a diagnosability
            # regression, not a behaviour improvement. The redirect itself is
            # correct for the case named above and is kept.
            logger.exception(
                "Root route failed to load settings for user {} — clearing "
                "session and redirecting to login",
                request.session.get("username"),
            )
            request.session.clear()
            return RedirectResponse(url="/auth/login", status_code=302)

        log_settings(settings, "Research page settings loaded")

        return templates.TemplateResponse(
            request=request,
            name="pages/research.html",
            context={
                "settings": settings,
                "strategies": get_available_strategies(),
            },
        )


_mount_all(app)


# ---------------------------------------------------------------------------
# Startup validation: every url_for() name used by a template must resolve
# to a route actually mounted on the app.
# ---------------------------------------------------------------------------


def _validate_url_for_bindings(app: "FastAPI") -> None:
    """Fail loudly at import/startup time if the Flask-compat ``url_for``
    shim would silently hand any template a dead link.

    ``url_for``'s fallback (``f"/{name.replace('.', '/')}"``) produces a
    plausible-looking but wrong URL for any name missing from ``_URL_MAP``
    — that already shipped one dead link (``chat.chat_page`` ->
    ``/chat/chat_page``, see ``tests/web/templates/test_url_for_links.py``).
    Rather than raise inside ``url_for()`` at render time (which would turn
    one cosmetic bad link into a 500 for an otherwise-working page — a worse
    failure mode for a self-hosted app), this scans every template for
    ``url_for("name")`` usages, resolves each one exactly as the real shim
    would, and checks the RESOLVED path against the live route table. This
    must run AFTER ``_mount_all(app)`` -- ``app.routes`` is empty at the
    point ``_setup_template_globals()`` runs (before routers are mounted),
    so validating there would trivially "pass" with an unpopulated table.

    Deliberately does NOT restrict itself to `_URL_MAP` keys: the
    `chat.chat_page` bug was a MISSING entry falling through to the
    dot-to-slash guess, which key-only validation would never have caught.

    Matching strategy: a resolved path is valid if EITHER
      (a) it exactly equals the ``path`` of some plain (parameter-free)
          ``Route`` — with a trailing-slash-tolerant comparison, since pages
          are linked both with and without one, or
      (b) it falls under the prefix of something that is *designed* to
          swallow an arbitrary nested sub-path: an ``app.mount(...)``
          (``Mount`` — e.g. the Socket.IO ASGI app at ``/ws``) or a ``Route``
          using Starlette's catch-all ``{name:path}`` converter (e.g.
          ``serve_static``'s ``/static/{path:path}``, which is exactly how
          ``url_for("static", filename=...)`` is validated without a special
          case).

    Every OTHER parameterized route (e.g. ``/chat/{session_id}``, a plain
    string converter bound to one specific, known value) is intentionally
    EXCLUDED from matching, even though Starlette's own ``Route.matches()``
    would happily match any string there. That was tried first and
    rejected: ``/chat/{session_id}`` matches literally any string under
    ``/chat/``, including ``/chat/totally-wrong-path`` — the exact shape of
    wrong path a missing ``_URL_MAP`` entry produces — so a
    ``Route.matches()``-based check would NOT have caught the
    ``chat.chat_page`` regression this validator exists to prevent.
    """
    from starlette.routing import Mount, Route

    url_for = templates.env.globals["url_for"]

    template_dir = Path(TEMPLATE_DIR)
    names: set[str] = set()
    # nosemgrep: semgrep.rules.path-traversal-risk, reason: Startup link validation enumerates only the installed package HTML templates
    for tpl_path in template_dir.rglob("*.html"):
        names.update(
            _URL_FOR_NAME_RE.findall(
                # nosemgrep: semgrep.rules.path-traversal-risk, reason: Template path comes from the installed package HTML glob above
                tpl_path.read_text(encoding="utf-8", errors="replace")
            )
        )

    if not names:
        # Deliberately NOT fatal. An empty scan is indistinguishable from a
        # packaging shape: TEMPLATE_DIR is computed from
        # importlib_resources.as_file(), whose temp directory is removed when
        # its context manager exits, so a zip-imported / pex / frozen install
        # can legitimately have no readable templates directory here.
        # Jinja2Templates itself tolerates that (FileSystemLoader never checks
        # the directory exists), so the pre-existing behaviour is "HTML pages
        # fail, the API keeps serving". Raising here would escalate that to
        # "the process does not import at all", which is strictly worse and is
        # exactly the trade this function's own docstring rejects.
        logger.warning(
            "url_for startup validation found no url_for() usages under "
            f"{template_dir}; skipping link validation. If this is a normal "
            "source install the templates directory has moved, and HTML "
            "rendering is already broken."
        )
        return

    static_paths: set[str] = set()
    wildcard_prefixes: set[str] = set()
    _catchall_re = re.compile(r"\{[^{}:]+:path\}")
    for route in app.routes:
        path = getattr(route, "path", None)
        if not path:
            continue
        if isinstance(route, Mount):
            wildcard_prefixes.add(path.rstrip("/"))
        elif isinstance(route, Route):
            if "{" not in path:
                static_paths.add(path)
                static_paths.add(path.rstrip("/") or "/")
            elif _catchall_re.search(path):
                wildcard_prefixes.add(path.split("{", 1)[0].rstrip("/"))
            # else: parameterized on a specific value (e.g. {session_id}) --
            # not a wildcard bucket url_for is allowed to land in.

    def _under_wildcard_prefix(lookup: str) -> bool:
        return any(
            lookup == prefix or lookup.startswith(prefix + "/")
            for prefix in wildcard_prefixes
        )

    dead: list[str] = []
    for name in sorted(names):
        path = (
            url_for(name, filename="x") if name == "static" else url_for(name)
        )
        # Normalise BOTH sides. static_paths stores stripped and
        # unstripped forms, but without stripping the lookup the
        # tolerance was one-directional: nine _URL_MAP values end in "/"
        # and pass only because each of those routers happens to declare
        # @router.get("/"). Changing one to @router.get("") — invisible
        # at runtime thanks to redirect_slashes — would have bricked boot.
        lookup = path.split("?", 1)[0]
        lookup = lookup.rstrip("/") or "/"
        if lookup in static_paths or _under_wildcard_prefix(lookup):
            continue
        dead.append(f"{name!r} -> {path!r}")

    if dead:
        detail = (
            "the following template url_for() names resolve to paths that "
            "are not mounted on the app. Add/fix an entry in _URL_MAP "
            "(web/fastapi_app.py) for each:\n  " + "\n  ".join(dead)
        )
        # Strict only when asked. A dead nav link is a cosmetic defect; making
        # it un-bootable turns one broken link into total unavailability,
        # which is a worse failure mode than the render-time raise this
        # function already rejects for the same reason. CI and developers get
        # the hard failure via LDR_STRICT_TEMPLATE_LINKS and via
        # tests/web/templates/test_url_for_links.py, which asserts the same
        # property offline; a running deployment gets a loud log and keeps
        # serving.
        if os.environ.get("LDR_STRICT_TEMPLATE_LINKS", "").lower() in (
            "1",
            "true",
            "yes",
        ):
            raise RuntimeError("url_for() startup validation failed: " + detail)
        logger.error("url_for() startup validation failed: " + detail)


_validate_url_for_bindings(app)