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.

35.1 KB
Raw Blame
"""Security-header MULTIPLICITY and out-of-band-response coverage.

Sibling suites already pin, thoroughly, that the stamped headers are
PRESENT with the right VALUES on the ordinary response classes:

* ``tests/web/test_security_headers.py`` — exact values on HTML/API/
  static/404, HSTS gated on scheme, the ``/static/`` cache carve-out.
* ``tests/security/test_security_headers_fastapi.py`` — the JSON 404
  branch, ``/favicon.ico``, an SSE ``StreamingResponse``, both 413
  branches, CORS hygiene.
* ``tests/web/test_middleware_order_and_headers.py`` — 200/404/405/422/
  CSRF-403/unhandled-500 all carry the headers.
* ``tests/web/test_middleware_stack_contracts.py`` — the values are
  IDENTICAL across five structurally different exit paths.
* ``tests/web/test_session_cookie_behavior.py``,
  ``tests/web/test_secure_cookie_middleware.py``,
  ``tests/security/test_cookie_security.py`` — Secure/HttpOnly/SameSite
  and the remember-me Max-Age rules on the session cookie.

These tests cover header multiplicity, responses built outside the
security middleware, and cookie handling.

1. HOW MANY TIMES does each header appear?
   Handler-stamped streaming responses must still carry each managed
   header once. Raw header assertions detect duplicate fields that a
   joined header lookup could overlook.

2. Do responses built OUTSIDE the middleware follow the same policy?
   The catch-all exception and rate-limit handlers bypass the security
   middleware. Their HTTPS responses need HSTS, and their cache behavior
   must follow the same static-route rules as ordinary responses.

3. Which cookies exist at all, and can one appear on a response that
   never passes ``SecureCookieMiddleware``?

Header-name literals below are test-owned on purpose (same rule as
``tests/web/test_security_headers.py``): deriving them from the code
under test would mean weakening the code also weakens the test.
"""

import ast
import asyncio
import inspect
import json
import os
import subprocess
import sys
from pathlib import Path

import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from slowapi.errors import RateLimitExceeded
from starlette.requests import Request
from starlette.responses import StreamingResponse

from local_deep_research.web import fastapi_app as _fastapi_app
from local_deep_research.web.fastapi_app import (
    SecureCookieMiddleware,
    SecurityHeadersMiddleware,
    _register_exception_handlers,
)
from local_deep_research.web.fastapi_app import app as _live_app

# ---------------------------------------------------------------------------
# Test-owned header names (never read from the middleware's constants).
# ---------------------------------------------------------------------------

_SECURITY_HEADERS = (
    "content-security-policy",
    "x-frame-options",
    "x-content-type-options",
    "cross-origin-opener-policy",
    "cross-origin-embedder-policy",
    "cross-origin-resource-policy",
    "permissions-policy",
    "referrer-policy",
)
_CACHE_HEADERS = ("cache-control", "pragma", "expires")
_HSTS = "strict-transport-security"

# Above BodySizeLimitMiddleware's smallest cap (16 MB). Declared, never
# sent: the middleware rejects on the declared Content-Length.
_OVER_CAP_CONTENT_LENGTH = "999999999"


# ---------------------------------------------------------------------------
# Probe routes on the live `app` singleton, registered at import time.
# Same technique and same `/__` prefix as
# tests/web/test_middleware_order_and_headers.py and
# tests/security/test_security_headers_fastapi.py; the route sweeps in
# tests/web/routers/test_all_endpoints.py and test_full_surface_smoke.py
# skip `/__` paths explicitly.
# ---------------------------------------------------------------------------


class _MatrixProbeError(RuntimeError):
    """Unregistered exception type -> the catch-all ``Exception`` handler."""


@_live_app.get("/__sec_matrix__/boom", include_in_schema=False)
async def _matrix_probe_boom():
    raise _MatrixProbeError("probe: unregistered exception type")


@_live_app.get("/__sec_matrix__/plain-sse", include_in_schema=False)
async def _matrix_probe_plain_sse():
    """A stream that sets NO headers of its own — the baseline for the
    multiplicity contract."""

    async def _generate():
        yield "data: one\n\n"

    return StreamingResponse(_generate(), media_type="text/event-stream")


# The header dict below is copied verbatim from
# routers/research.py::export_research_logs (see
# _PRODUCTION_SELF_STAMPING_SITES, which asserts that route still does
# this). The point of the probe is the RESPONSE SHAPE — a handler that
# stamps two headers the middleware also stamps — not this particular
# route, which needs an authenticated session and a populated user DB.
@_live_app.get("/__sec_matrix__/self-stamped", include_in_schema=False)
async def _matrix_probe_self_stamped():
    async def _generate():
        yield '{"probe": 1}\n'

    return StreamingResponse(
        _generate(),
        media_type="application/x-ndjson",
        headers={
            "Cache-Control": "no-store",
            "X-Content-Type-Options": "nosniff",
        },
    )


# ---------------------------------------------------------------------------
# Helpers / fixtures
# ---------------------------------------------------------------------------


def _raw(resp, name):
    """Every value for ``name``, unjoined.

    ``resp.headers[name]`` collapses duplicates into one comma-joined
    string, which is precisely what hides the append-vs-replace defect
    this file is about.
    """
    wanted = name.lower().encode("latin-1")
    return [
        value.decode("latin-1")
        for key, value in resp.headers.raw
        if key.lower() == wanted
    ]


@pytest.fixture
def http_client(app):
    """Plain-HTTP client on the real, fully-wired app."""
    return TestClient(app, raise_server_exceptions=False)


@pytest.fixture
def https_client(app):
    """Same app, ``scope["scheme"] == "https"`` (drives HSTS)."""
    return TestClient(
        app, base_url="https://testserver", raise_server_exceptions=False
    )


#: label -> (how to produce it, expected status). Every entry is proven
#: to produce that status before anything is asserted about its headers,
#: so no test here can pass against a response that never happened.
_RESPONSE_CLASSES = {
    "200 HTML page": (lambda c: c.get("/auth/login"), 200),
    "200 JSON api": (lambda c: c.get("/api/v1/health"), 200),
    "200 SSE stream": (
        lambda c: c.get("/__sec_matrix__/plain-sse"),
        200,
    ),
    "302 redirect": (
        lambda c: c.get("/settings/", follow_redirects=False),
        302,
    ),
    "200 static asset (legacy shim)": (
        lambda c: c.get("/redirect-static/css/styles.css"),
        200,
    ),
    "404 HTML branch": (lambda c: c.get("/no-such-route-sec-matrix"), 404),
    "404 JSON branch": (lambda c: c.get("/api/no-such-route-sec-matrix"), 404),
    "403 CSRF short-circuit": (lambda c: c.post("/auth/logout"), 403),
    "413 BodySizeLimit short-circuit": (
        lambda c: c.post(
            "/api/v1/quick_summary",
            content=b"x",
            headers={
                "Content-Length": _OVER_CAP_CONTENT_LENGTH,
                "Content-Type": "application/json",
            },
        ),
        413,
    ),
    "500 catch-all handler": (lambda c: c.get("/__sec_matrix__/boom"), 500),
}

#: Served by ``serve_static``, which sets its OWN ``Cache-Control`` and is
#: exempted from the middleware's cache stamping by the ``/static/``
#: carve-out. Kept apart from the table above because the cache-header
#: expectation is inverted for it.
_STATIC_PATH = "/static/favicon.png"


def _produce(client, label):
    make, expected = _RESPONSE_CLASSES[label]
    resp = make(client)
    assert resp.status_code == expected, (
        f"{label}: expected status {expected}, got {resp.status_code} — "
        f"the probe no longer produces this response class, so nothing "
        f"below would be asserting about it"
    )
    return resp


# ---------------------------------------------------------------------------
# 1. Multiplicity: exactly one of each, on every response class
# ---------------------------------------------------------------------------


class TestStampedHeadersAppearExactlyOnce:
    """Presence is not enough; a security header must appear ONCE.

    A duplicated ``X-Frame-Options`` with disagreeing values is treated
    as a framing failure by browsers rather than as either value, and a
    duplicated ``Content-Security-Policy`` is enforced as the
    INTERSECTION of the two policies — so a second copy arriving from
    the middleware silently changes what a handler-declared policy
    means. Sibling suites read ``resp.headers[name]``, which joins
    duplicates, and so cannot see any of this.
    """

    @pytest.mark.parametrize("label", sorted(_RESPONSE_CLASSES))
    def test_each_security_header_exactly_once(self, label, http_client):
        resp = _produce(http_client, label)
        counts = {name: len(_raw(resp, name)) for name in _SECURITY_HEADERS}
        assert counts == dict.fromkeys(_SECURITY_HEADERS, 1), (
            f"{label}: every security header must appear exactly once; "
            f"got {counts!r}"
        )

    @pytest.mark.parametrize("label", sorted(_RESPONSE_CLASSES))
    def test_each_cache_header_exactly_once(self, label, http_client):
        """Successful legacy assets cache; dynamic/error responses do not."""
        resp = _produce(http_client, label)
        counts = {name: len(_raw(resp, name)) for name in _CACHE_HEADERS}
        expected = (
            {"cache-control": 1, "pragma": 0, "expires": 0}
            if label == "200 static asset (legacy shim)"
            else dict.fromkeys(_CACHE_HEADERS, 1)
        )
        assert counts == expected, (
            f"{label}: unexpected cache header multiplicity; got {counts!r}"
        )

    @pytest.mark.parametrize("prefix", ["static", "redirect-static"])
    def test_static_keeps_only_its_own_single_cache_control(
        self, http_client, prefix
    ):
        """The carve-out's job is to leave ``serve_static``'s own
        caching policy intact. If the middleware appended its no-store
        here, the asset would carry two ``Cache-Control`` headers whose
        union is no-store, quietly destroying static caching — the
        append-vs-replace failure with a real cost attached."""
        resp = http_client.get(_STATIC_PATH.replace("/static/", f"/{prefix}/"))
        assert resp.status_code == 200, (
            f"{_STATIC_PATH} did not serve; this test needs a real static "
            f"asset to be meaningful (got {resp.status_code})"
        )
        cache_control = _raw(resp, "cache-control")
        assert len(cache_control) == 1, (
            f"static asset carries {len(cache_control)} Cache-Control "
            f"headers: {cache_control!r}"
        )
        assert "no-store" not in cache_control[0], (
            f"the /static/ carve-out failed: {cache_control[0]!r}"
        )
        assert _raw(resp, "pragma") == []
        assert _raw(resp, "expires") == []
        # The security headers are NOT part of the carve-out.
        assert {
            name: len(_raw(resp, name)) for name in _SECURITY_HEADERS
        } == dict.fromkeys(_SECURITY_HEADERS, 1)

    @pytest.mark.parametrize("label", sorted(_RESPONSE_CLASSES))
    def test_hsts_exactly_once_over_https(self, label, https_client):
        """Include the catch-all response built outside the middleware."""
        resp = _produce(https_client, label)
        assert len(_raw(resp, _HSTS)) == 1, (
            f"{label}: expected exactly one {_HSTS} over https, got "
            f"{_raw(resp, _HSTS)!r}"
        )

    @pytest.mark.parametrize("label", sorted(_RESPONSE_CLASSES))
    def test_no_hsts_over_plain_http(self, label, http_client):
        """HSTS on a plain-HTTP response is ignored by browsers but is a
        misconfiguration signal; main gated it on ``request.is_secure``
        and the port must keep the gate on every response class."""
        resp = _produce(http_client, label)
        assert _raw(resp, _HSTS) == [], (
            f"{label}: HSTS leaked onto a plain-HTTP response: "
            f"{_raw(resp, _HSTS)!r}"
        )

    @pytest.mark.parametrize("label", sorted(_RESPONSE_CLASSES))
    def test_no_server_header_on_any_response_class(self, label, http_client):
        resp = _produce(http_client, label)
        assert _raw(resp, "server") == [], (
            f"{label}: Server header leaked: {_raw(resp, 'server')!r}"
        )


# ---------------------------------------------------------------------------
# 2. Append vs replace, where a handler stamps the same header
# ---------------------------------------------------------------------------

#: (module path relative to the package, header literal, why it is there).
#: The probe route ``/__sec_matrix__/self-stamped`` stands in for these,
#: so this table is asserted against the real source: if every one of
#: these routes stops stamping its own headers, the probe is fiction and
#: this suite should be deleted rather than left passing.
_PRODUCTION_SELF_STAMPING_SITES = {
    "web/routers/research.py": ("Cache-Control", "X-Content-Type-Options"),
    "web/routers/rag.py": ("Cache-Control",),
    "web/routers/library.py": ("Cache-Control",),
}


def _package_root():
    import local_deep_research

    return Path(local_deep_research.__file__).parent


class TestHandlerStampedHeadersAreNotDuplicated:
    """``headers.extend(...)`` vs main's ``headers[name] = ...``."""

    def test_production_routes_really_stamp_these_headers_themselves(self):
        """Premise check for the probe route below."""
        root = _package_root()
        missing = {}
        for rel, header_names in _PRODUCTION_SELF_STAMPING_SITES.items():
            source = (root / rel).read_text(encoding="utf-8")
            absent = [
                name
                for name in header_names
                if f'"{name}"' not in source and f"'{name}'" not in source
            ]
            if absent:
                missing[rel] = absent
        assert missing == {}, (
            "the routes this suite's probe stands in for no longer set "
            f"these headers themselves: {missing!r}. Either the probe is "
            "now fiction (delete this class) or the header moved."
        )

    def test_the_probe_response_really_is_handler_stamped(self, http_client):
        """Positive control: without this, the two regression tests below could
        'fail' for the boring reason that the probe stopped stamping."""
        resp = http_client.get("/__sec_matrix__/self-stamped")
        assert resp.status_code == 200
        assert resp.headers["content-type"].startswith(
            "application/x-ndjson"
        ), resp.headers.get("content-type")
        assert resp.text == '{"probe": 1}\n', (
            "the stream did not run; this is some other response"
        )
        # The handler's own values must still be in there somewhere.
        assert "no-store" in ", ".join(_raw(resp, "cache-control"))
        assert "nosniff" in ", ".join(_raw(resp, "x-content-type-options"))

    def test_x_content_type_options_not_duplicated(self, http_client):
        resp = http_client.get("/__sec_matrix__/self-stamped")
        assert resp.status_code == 200
        values = _raw(resp, "x-content-type-options")
        assert len(values) == 1, (
            f"handler-stamped response carries {len(values)} "
            f"X-Content-Type-Options headers: {values!r}"
        )

    def test_cache_control_not_duplicated(self, http_client):
        resp = http_client.get("/__sec_matrix__/self-stamped")
        assert resp.status_code == 200
        values = _raw(resp, "cache-control")
        assert len(values) == 1, (
            f"handler-stamped response carries {len(values)} Cache-Control "
            f"headers: {values!r}"
        )


# ---------------------------------------------------------------------------
# 3. HSTS on responses built outside the middleware
# ---------------------------------------------------------------------------


def _request_scope(*, scheme="https", path="/api/v1/health"):
    """A realistic HTTPS ASGI scope for the live app."""
    return {
        "type": "http",
        "http_version": "1.1",
        "method": "GET",
        "scheme": scheme,
        "path": path,
        "raw_path": path.encode(),
        "query_string": b"",
        "root_path": "",
        "headers": [(b"host", b"testserver")],
        "client": ("10.9.9.9", 41234),
        "server": ("testserver", 443 if scheme == "https" else 80),
        "app": _live_app,
        "state": {},
    }


def _call_rate_limit_handler(*, scheme="https", path="/api/v1/health"):
    """Invoke the app's REGISTERED RateLimitExceeded handler.

    Driven directly rather than by exhausting a real bucket: the
    question is only what headers the handler puts on the response it
    builds, and slowapi's machinery contributes none of them.
    ``tests/web/test_rate_limit_coverage.py::TestRateLimitExceededHandler``
    already calls this handler directly for the same reason.
    """
    handler = _live_app.exception_handlers[RateLimitExceeded]
    request = Request(_request_scope(scheme=scheme, path=path))
    exc = RateLimitExceeded.__new__(RateLimitExceeded)
    exc.limit = None
    result = handler(request, exc)
    if inspect.isawaitable(result):
        result = asyncio.run(_await(result))
    return result


async def _await(value):
    return await value


class TestHstsOnOutOfBandResponses:
    def test_hsts_is_really_stamped_on_the_paths_that_do_pass_the_middleware(
        self, https_client
    ):
        """Positive control for the two regression tests below: if HSTS were absent
        app-wide, 'the 500 has no HSTS' would prove nothing."""
        resp = _produce(https_client, "404 JSON branch")
        assert _raw(resp, _HSTS) == ["max-age=31536000; includeSubDomains"], (
            "no HSTS on an ordinary error response over https, so this "
            "class cannot distinguish an out-of-band gap from a global one"
        )

    def test_catch_all_500_carries_hsts_over_https(self, https_client):
        resp = _produce(https_client, "500 catch-all handler")
        assert resp.json() == {"error": "Server error"}
        assert _raw(resp, _HSTS) == ["max-age=31536000; includeSubDomains"], (
            f"unhandled 500 over https carries HSTS {_raw(resp, _HSTS)!r}"
        )

    def test_rate_limit_429_carries_hsts_over_https(self):
        response = _call_rate_limit_handler()
        assert response.status_code == 429, (
            f"the registered RateLimitExceeded handler did not build a 429: "
            f"{response.status_code}"
        )
        names = [key.decode("latin-1") for key, _ in response.raw_headers]
        # Positive control: it really does stamp the other headers here.
        assert "content-security-policy" in names, names
        assert _HSTS in names, (
            f"429 built for an https request carries no HSTS: {names!r}"
        )


# ---------------------------------------------------------------------------
# 4. The /static/ cache carve-out on error responses
# ---------------------------------------------------------------------------


class _StaticProbeError(RuntimeError):
    pass


@pytest.fixture
def static_error_client():
    """Real ``SecurityHeadersMiddleware`` + real exception handlers on a
    throwaway app whose only route lives under ``/static/``.

    Nothing is reimplemented: both pieces are imported from
    ``fastapi_app`` and registered the way it registers them. The live
    app's ``serve_static`` cannot be made to raise on demand (it catches
    ValueError/OSError), which is the only reason this is not driven
    through the singleton.
    """
    probe = FastAPI()

    @probe.get("/static/{tail:path}")
    async def _static(tail: str):
        if tail == "boom":
            raise _StaticProbeError("probe")
        return {"ok": True}

    probe.add_middleware(SecurityHeadersMiddleware)
    _register_exception_handlers(probe)
    with TestClient(
        probe, base_url="https://testserver", raise_server_exceptions=False
    ) as client:
        yield client


class TestStaticCarveOutAppliesToErrorResponsesToo:
    def test_static_200_is_not_stamped_no_store(self, static_error_client):
        """Positive control: the carve-out is live in this stack."""
        resp = static_error_client.get("/static/ok")
        assert resp.status_code == 200
        assert _raw(resp, "cache-control") == []
        assert len(_raw(resp, "content-security-policy")) == 1

    def test_static_500_is_not_stamped_no_store(self, static_error_client):
        resp = static_error_client.get("/static/boom")
        assert resp.status_code == 500
        assert _raw(resp, "cache-control") == [], (
            f"500 under /static/ was stamped {_raw(resp, 'cache-control')!r} "
            f"even though the 200 for the same prefix is not"
        )


# ---------------------------------------------------------------------------
# 5. The cookie surface
# ---------------------------------------------------------------------------


class TestCookieSurface:
    def test_the_app_hand_rolls_no_cookies_at_all(self):
        """Every ``Secure``/``HttpOnly``/``SameSite`` guarantee this app
        makes rests on ONE fact: the only cookie it emits is the one
        Starlette's ``SessionMiddleware`` writes, which
        ``SecureCookieMiddleware`` and ``RememberMeMiddleware`` then
        rewrite. A hand-rolled ``response.set_cookie(...)`` anywhere in
        the web package would get ``Secure`` from SecureCookieMiddleware
        but nothing else — no HttpOnly, no SameSite — and every cookie
        test in this repo drives the session cookie, so it would land
        unnoticed. Fails the moment one appears.
        """
        web_root = _package_root() / "web"
        offenders = []
        for path in sorted(web_root.rglob("*.py")):
            tree = ast.parse(path.read_text(encoding="utf-8"), str(path))
            for node in ast.walk(tree):
                if not isinstance(node, ast.Call):
                    continue
                func = node.func
                name = getattr(func, "attr", None) or getattr(func, "id", None)
                if name in ("set_cookie", "delete_cookie"):
                    offenders.append(
                        f"{path.relative_to(web_root)}:{node.lineno}: {name}()"
                    )
        assert offenders == [], (
            "hand-rolled cookie writes found in the web package. Each one "
            "must be reviewed for HttpOnly / SameSite / Secure and given "
            "its own test before this assertion is relaxed:\n  "
            + "\n  ".join(offenders)
        )

    def test_session_cookie_attributes_on_the_page_that_sets_it(
        self, http_client
    ):
        """GET /auth/login stamps a CSRF token into a fresh session, which
        is the app's only anonymous Set-Cookie. Asserted here on the
        attributes the sibling cookie suites do NOT pin: ``Path=/`` (so
        the cookie is not scoped away from most of the app) and the
        ABSENCE of ``Domain`` (a Domain attribute would widen the cookie
        to every sibling subdomain)."""
        resp = http_client.get("/auth/login")
        assert resp.status_code == 200
        cookies = _raw(resp, "set-cookie")
        assert len(cookies) == 1, (
            f"expected exactly one Set-Cookie on GET /auth/login, got "
            f"{cookies!r}"
        )
        cookie = cookies[0]
        assert cookie.startswith("session="), cookie
        attrs = [part.strip().lower() for part in cookie.split(";")[1:]]
        assert "httponly" in attrs, cookie
        assert "samesite=lax" in attrs, cookie
        assert "path=/" in attrs, cookie
        assert not any(a.startswith("domain=") for a in attrs), (
            f"session cookie carries a Domain attribute, widening it to "
            f"sibling subdomains: {cookie}"
        )

    @pytest.mark.parametrize(
        "label",
        [
            "500 catch-all handler",
            "403 CSRF short-circuit",
            "413 BodySizeLimit short-circuit",
        ],
    )
    def test_short_circuit_responses_emit_no_cookie(self, label, https_client):
        """``SecureCookieMiddleware`` is the outermost app middleware but
        still sits INSIDE ``ServerErrorMiddleware``, so a cookie riding
        out on the catch-all 500 would never get ``Secure``. The 403 and
        413 short-circuit before ``SessionMiddleware`` runs at all. None
        of these may carry a cookie; if one ever does, it is unflagged.
        """
        resp = _produce(https_client, label)
        assert _raw(resp, "set-cookie") == [], (
            f"{label} carried a Set-Cookie that never passed "
            f"SecureCookieMiddleware/SessionMiddleware: "
            f"{_raw(resp, 'set-cookie')!r}"
        )

    def test_secure_flag_is_wired_to_the_ldr_test_mode_toggle(self):
        """``SecureCookieMiddleware(testing=True)`` disables the Secure
        flag outright, and the live app passes ``testing=is_testing``,
        which fastapi_app computes from the explicit operator-facing
        ``LDR_TEST_MODE`` env var. That makes
        ``LDR_TEST_MODE`` a production-affecting security toggle: setting
        it on an HTTPS deployment silently drops ``Secure`` from every
        session cookie. Pinned so the wiring cannot be changed — in
        either direction — without this being restated.
        """
        entries = [
            m
            for m in _live_app.user_middleware
            if m.cls is SecureCookieMiddleware
        ]
        assert len(entries) == 1, (
            f"expected exactly one SecureCookieMiddleware registration, "
            f"got {len(entries)}"
        )
        assert entries[0].kwargs == {"testing": _fastapi_app.is_testing}, (
            f"SecureCookieMiddleware is no longer wired to is_testing: "
            f"{entries[0].kwargs!r}"
        )

    def test_session_middleware_cookie_options_are_the_documented_ones(self):
        """The app emits exactly one cookie and every attribute on it
        except ``Secure`` comes from this registration. ``https_only``
        must stay False: SessionMiddleware would otherwise add ``Secure``
        unconditionally, and a Secure cookie over plain HTTP is DROPPED
        by the browser (the #3849 login loop) — the scheme decision is
        SecureCookieMiddleware's, per request. ``same_site`` must stay
        strict; Starlette hardcodes HttpOnly.
        """
        entries = [
            m
            for m in _live_app.user_middleware
            if m.cls.__name__ == "SessionMiddleware"
        ]
        assert len(entries) == 1, (
            f"expected exactly one SessionMiddleware registration, got "
            f"{len(entries)}"
        )
        kwargs = entries[0].kwargs
        assert kwargs.get("session_cookie") == "session", kwargs
        assert kwargs.get("same_site") == "lax", kwargs
        assert kwargs.get("https_only") is False, (
            "https_only=True would make SessionMiddleware stamp Secure on "
            "every session cookie, including over plain HTTP, where "
            f"browsers drop it: {kwargs!r}"
        )

    @pytest.mark.parametrize(
        ("test_env", "expected_testing"),
        [
            ({}, False),
            ({"PYTEST_CURRENT_TEST": "test_probe.py::case (call)"}, False),
            (
                {
                    "PYTEST_CURRENT_TEST": "test_probe.py::case (call)",
                    "CI": "true",
                    "TESTING": "1",
                },
                False,
            ),
            (
                {
                    "LDR_TEST_MODE": "0",
                    "PYTEST_CURRENT_TEST": "test_probe.py::case (call)",
                },
                False,
            ),
            (
                {
                    "LDR_TEST_MODE": "false",
                    "PYTEST_CURRENT_TEST": "test_probe.py::case (call)",
                },
                False,
            ),
            ({"LDR_TEST_MODE": "true"}, True),
            (
                {
                    "LDR_TEST_MODE": "1",
                    "PYTEST_CURRENT_TEST": "test_probe.py::case (call)",
                },
                True,
            ),
        ],
        ids=[
            "collection",
            "during-test",
            "ci-during-test",
            "explicit-zero",
            "explicit-false",
            "explicit-true",
            "explicit-one-during-test",
        ],
    )
    def test_only_explicit_test_mode_changes_cookie_and_docs_policy(
        self, tmp_path, test_env, expected_testing
    ):
        """A fresh app import has the same policy before and during a test."""
        env = os.environ.copy()
        for key in ("LDR_TEST_MODE", "PYTEST_CURRENT_TEST", "CI", "TESTING"):
            env.pop(key, None)
        env.update(
            LDR_DATA_DIR=str(tmp_path),
            LDR_EXPOSE_DOCS="true",
            LDR_BOOTSTRAP_ALLOW_UNENCRYPTED="true",
            **test_env,
        )
        probe = """
import json
from fastapi.testclient import TestClient
from local_deep_research.web.fastapi_app import app, is_testing

client = TestClient(app, base_url="https://testserver")
try:
    response = client.get("/auth/csrf-token")
    print(json.dumps({
        "testing": is_testing,
        "status": response.status_code,
        "cookies": response.headers.get_list("set-cookie"),
        "docs_url": app.docs_url,
        "openapi_url": app.openapi_url,
    }))
finally:
    client.close()
"""
        result = subprocess.run(
            [sys.executable, "-c", probe],
            env=env,
            capture_output=True,
            text=True,
            timeout=90,
        )
        assert result.returncode == 0, result.stderr[-3000:]
        observed = json.loads(result.stdout.strip().splitlines()[-1])
        assert observed["status"] == 200
        assert observed["testing"] is expected_testing
        cookies = [
            value
            for value in observed["cookies"]
            if value.lower().startswith("session=")
        ]
        assert len(cookies) == 1, observed
        attributes = {
            part.strip().lower() for part in cookies[0].split(";")[1:]
        }
        assert ("secure" in attributes) is (not expected_testing), observed
        assert "httponly" in attributes
        assert observed["docs_url"] == (
            None if expected_testing else "/api/docs"
        )
        assert observed["openapi_url"] == (
            None if expected_testing else "/openapi.json"
        )


@pytest.mark.parametrize("scheme", ["http", "https"])
def test_header_replacement_preserves_repeated_cookie_fields(scheme):
    """ASGI headers are case-insensitive; Set-Cookie remains multi-valued."""
    messages = []
    cookies = [
        (b"set-cookie", b"first=one; HttpOnly"),
        (b"set-cookie", b"second=two; HttpOnly"),
    ]

    async def downstream(scope, receive, send):
        await send(
            {
                "type": "http.response.start",
                "status": 200,
                "headers": [
                    (b"X-Content-Type-Options", b"incorrect"),
                    (b"x-content-type-options", b"incorrect-again"),
                    (b"Cache-Control", b"public"),
                    (b"SERVER", b"probe"),
                    *cookies,
                ],
            }
        )
        await send({"type": "http.response.body", "body": b"body-control"})

    async def send(message):
        messages.append(message)

    async def receive():
        return {"type": "http.request", "body": b"", "more_body": False}

    asyncio.run(
        SecurityHeadersMiddleware(downstream)(
            _request_scope(scheme=scheme), receive, send
        )
    )
    headers = messages[0]["headers"]
    assert [(k, v) for k, v in headers if k.lower() == b"set-cookie"] == cookies
    assert [
        v for k, v in headers if k.lower() == b"x-content-type-options"
    ] == [b"nosniff"]
    assert [v for k, v in headers if k.lower() == b"cache-control"] == [
        b"no-store, no-cache, must-revalidate, max-age=0"
    ]
    assert not any(k.lower() == b"server" for k, _ in headers)
    assert [
        v for k, v in headers if k.lower() == b"strict-transport-security"
    ] == ([b"max-age=31536000; includeSubDomains"] if scheme == "https" else [])
    assert messages[1] == {
        "type": "http.response.body",
        "body": b"body-control",
    }


@pytest.mark.parametrize("scheme", ["http", "https"])
@pytest.mark.parametrize(
    "path,cache_expected",
    [
        ("/api/v1/health", True),
        ("/static/probe.css", False),
        ("/redirect-static/probe.js", True),
    ],
)
def test_rate_limit_handler_uses_the_scheme_and_static_cache_policy(
    scheme, path, cache_expected
):
    response = _call_rate_limit_handler(scheme=scheme, path=path)
    assert response.status_code == 429
    assert _raw(response, _HSTS) == (
        ["max-age=31536000; includeSubDomains"] if scheme == "https" else []
    )
    assert len(_raw(response, "content-security-policy")) == 1
    assert len(_raw(response, "cache-control")) == int(cache_expected)
    if cache_expected:
        assert "no-store" in _raw(response, "cache-control")[0]


@pytest.mark.parametrize(
    "route_headers,no_transform",
    [
        pytest.param([], False, id="no-route-policy"),
        pytest.param(
            [(b"Cache-Control", b"no-cache, no-transform")],
            True,
            id="sse-policy",
        ),
        pytest.param(
            [(b"CACHE-CONTROL", b" public, max-age=600, \tNO-TRANSFORM ")],
            True,
            id="mixed-case",
        ),
        pytest.param(
            [
                (b"Cache-Control", b"public, max-age=600"),
                (b"cache-control", b"s-maxage=300, no-transform"),
            ],
            True,
            id="repeated-fields",
        ),
        pytest.param(
            [(b"cache-control", b"no-transform, NO-TRANSFORM, public")],
            True,
            id="repeated-directive",
        ),
        pytest.param(
            [(b"cache-control", b'public, x-no-transform, ext="no-transform"')],
            False,
            id="unrelated-directives",
        ),
    ],
)
def test_cache_replacement_preserves_only_no_transform(
    route_headers, no_transform
):
    """The stream directive survives; cacheable policy and duplicates do not."""
    messages = []

    async def downstream(scope, receive, send):
        await send(
            {
                "type": "http.response.start",
                "status": 200,
                "headers": route_headers,
            }
        )
        await send({"type": "http.response.body", "body": b"stream-control"})

    async def send(message):
        messages.append(message)

    async def receive():
        return {"type": "http.request", "body": b"", "more_body": False}

    asyncio.run(
        SecurityHeadersMiddleware(downstream)(_request_scope(), receive, send)
    )
    assert len(messages) == 2
    assert messages[0]["status"] == 200
    cache_control = [
        value
        for name, value in messages[0]["headers"]
        if name.lower() == b"cache-control"
    ]
    expected = b"no-store, no-cache, must-revalidate, max-age=0"
    if no_transform:
        expected += b", no-transform"
    assert cache_control == [expected]
    assert messages[1] == {
        "type": "http.response.body",
        "body": b"stream-control",
    }