~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""Composition contracts for the eight-middleware ASGI stack.
``web/fastapi_app.py`` registers eight middleware and Starlette applies them
LIFO, so the file reads bottom-up: the *last* ``app.add_middleware`` call is
the OUTERMOST layer. The resulting outer -> inner order is
SlowAPI -> SecureCookie -> SecurityHeaders -> BodySizeLimit
-> RememberMe -> Session -> CSRF -> Database
(plus ``_PathScopedCORSMiddleware`` in front of all of it, but only when
``security.cors.allowed_origins`` is configured — the default is fail-closed,
so the live app carries eight, not nine).
That order is load-bearing and, in the source, pinned mostly by comments.
The canonical example: ``CSRFMiddleware`` reads ``scope["session"]``, a key
only ``SessionMiddleware`` ever writes. CSRF must therefore run *inside*
Session. Swap those two ``add_middleware`` calls and nothing breaks at import
time, nothing raises, no type checker complains — CSRF simply observes an
empty session on every request and answers *every* state-changing request
with "CSRF token missing", valid cookie and valid token included. The app is
then 100% broken for logged-in users and 0% broken for anything a smoke test
looks at. ``TestCsrfSeesTheSessionThatSessionMiddlewareDecoded`` below builds
that exact inverted stack out of the two real middleware classes and shows the
403, next to the correct order returning 200.
WHAT IS ALREADY COVERED ELSEWHERE (deliberately not repeated here):
* ``tests/web/test_middleware_order_and_headers.py`` pins the exact
``app.user_middleware`` sequence and cross-checks it against the built ASGI
object graph, and asserts security headers on 200/404/405/422/CSRF-403 and
on the catch-all 500.
* ``tests/security/test_security_headers_fastapi.py`` adds the JSON-404,
``/favicon.ico``, SSE and both 413 content-negotiation branches, plus CORS
``Vary``/max-age/credentials hygiene on *successful* responses.
* ``tests/web/test_cors_config.py`` / ``test_cors_path_scoping.py`` pin
fail-closed CORS registration and API-prefix scoping.
WHAT THIS FILE ADDS — all of it about *composition and interaction*, none of
it re-asserting a header on a happy path:
1. A premise guard on the stack itself: exactly eight middleware, each one
named in this file's coverage map. A ninth middleware fails here, loudly,
until someone decides what it means for ordering.
2. Execution-order proof rather than structural proof: the request is
instrumented at every seam of the *live, already-built* chain, so the
outer -> inner order is read off a real request instead of a bookkeeping
list.
3. Short-circuit semantics: a 413 from ``BodySizeLimitMiddleware`` must skip
every middleware inside it (that is the entire point of putting the cap
outside Session/CSRF) while still climbing back out through the ones
outside it as a well-formed, fully-stamped response.
4. Exit-path uniformity: the five structurally distinct response producers in
this app (router, exception handler, BodySizeLimit short-circuit, CSRF
short-circuit, and the ``ServerErrorMiddleware`` catch-all that bypasses
every registered middleware) must all carry the *same* security headers
with the *same* values — not merely "present somewhere".
5. CORS on error responses, including a pinned known gap: the catch-all 500
restamps security headers but NOT CORS headers.
"""
import asyncio
from unittest.mock import patch
import pytest
from fastapi import FastAPI, HTTPException, Request
from fastapi.testclient import TestClient
from slowapi.middleware import SlowAPIMiddleware
from starlette.middleware.sessions import SessionMiddleware
from local_deep_research.web.dependencies.csrf import (
CSRFMiddleware,
generate_csrf_token,
)
from local_deep_research.web.fastapi_app import (
BodySizeLimitMiddleware,
DatabaseMiddleware,
RememberMeMiddleware,
SecureCookieMiddleware,
SecurityHeadersMiddleware,
_configure_cors,
_register_exception_handlers,
)
from local_deep_research.web.fastapi_app import app as _live_app
from tests.web.test_security_headers import _normalise_header
# ---------------------------------------------------------------------------
# Test-only probe route on the live `app` singleton, registered once at
# collection time. Same technique and same `/__` prefix convention 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). It runs through the exact production middleware stack —
# nothing here is re-created or mocked.
# ---------------------------------------------------------------------------
class _StackProbeError(RuntimeError):
"""An exception type no handler in `_register_exception_handlers` binds.
Not HTTPException, WebAPIException, NewsAPIException, PolicyDeniedError or
json.JSONDecodeError — so it matches only the bare ``Exception`` handler,
which Starlette wires into ``ServerErrorMiddleware`` (installed OUTSIDE
every ``add_middleware`` call) rather than into ``ExceptionMiddleware``.
That is what makes it the one response class produced outside the whole
registered stack.
"""
@_live_app.get("/__mw_stack__/boom", include_in_schema=False)
async def _mw_stack_probe_boom():
raise _StackProbeError("probe: unregistered exception type")
# Test-owned header-name literals (NOT read from SecurityHeadersMiddleware's
# own constants — see tests/web/test_security_headers.py for why: deriving
# them from the code under test means weakening the code also weakens the
# test). Values are never compared to a literal here; this file compares them
# ACROSS exit paths, which is the composition property it is about.
_UNCONDITIONAL_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",
)
# Stamped on every non-`/static/` response; none of the exit paths driven in
# this file is under `/static/`, so all of them must carry these too.
_CACHE_HEADERS = ("cache-control", "pragma", "expires")
_ALL_STAMPED_HEADERS = _UNCONDITIONAL_SECURITY_HEADERS + _CACHE_HEADERS
# Any Content-Length above BodySizeLimitMiddleware's smallest cap (16 MB for
# non-multipart bodies). Declared, not sent: the middleware's fast path
# rejects on the declared Content-Length before a byte of body is read, which
# is the short-circuit this file is about.
_OVER_CAP_CONTENT_LENGTH = "999999999"
@pytest.fixture
def client(app):
"""TestClient on the real, fully-wired app.
``raise_server_exceptions=False`` so the catch-all 500 comes back as a
Response instead of re-raising into the test. The ``app`` parameter is
conftest's fixture (per-test data dir / env) and is the same singleton
object as the module-level ``_live_app`` import above.
"""
return TestClient(app, raise_server_exceptions=False)
def _live_order(app):
"""Outer -> inner middleware class names, read off the live app."""
return [m.cls.__name__ for m in app.user_middleware]
# ---------------------------------------------------------------------------
# 1. HTTP-only middleware must leave other ASGI protocols completely alone
# ---------------------------------------------------------------------------
@pytest.mark.parametrize(
"middleware_cls",
[
SecurityHeadersMiddleware,
BodySizeLimitMiddleware,
SecureCookieMiddleware,
RememberMeMiddleware,
DatabaseMiddleware,
],
ids=lambda cls: cls.__name__,
)
@pytest.mark.parametrize(
("scope_type", "incoming", "outgoing"),
[
(
"websocket",
{"type": "websocket.connect"},
{"type": "websocket.accept"},
),
(
"lifespan",
{"type": "lifespan.startup"},
{"type": "lifespan.startup.complete"},
),
],
ids=("websocket", "lifespan"),
)
def test_http_only_middleware_passes_non_http_scopes_through_unchanged(
middleware_cls, scope_type, incoming, outgoing
):
"""The HTTP stack also wraps the Socket.IO and lifespan scope paths.
Each layer must hand non-HTTP calls straight to the inner app with the
original scope and callables. Checking object identity makes this more
than a response-shape test: a future wrapper that consumes a WebSocket
event, rewrites a lifespan message, or expects HTTP-only keys fails at the
middleware responsible instead of surfacing as a distant live-server
handshake failure.
"""
scope = {"type": scope_type, "probe": object()}
sent = []
observed = {}
async def receive():
return incoming
async def send(message):
sent.append(message)
async def inner(inner_scope, inner_receive, inner_send):
observed["scope"] = inner_scope
observed["receive"] = inner_receive
observed["send"] = inner_send
observed["incoming"] = await inner_receive()
await inner_send(outgoing)
middleware = middleware_cls(inner)
asyncio.run(middleware(scope, receive, send))
assert observed["scope"] is scope
assert observed["receive"] is receive
assert observed["send"] is send
assert observed["incoming"] is incoming
assert len(sent) == 1
assert sent[0] is outgoing
# ---------------------------------------------------------------------------
# 2. Premise: the stack under test really is the eight-layer production stack
# ---------------------------------------------------------------------------
# Every middleware the app registers, mapped to how THIS file exercises it.
# Keys are asserted to equal the live roster exactly, so adding a ninth
# middleware to fastapi_app.py fails here until someone states what it is and
# how the ordering tests below reach it.
_COVERAGE_MAP = {
SlowAPIMiddleware: (
"Outermost. Entered on every request driven below; recorded first in "
"`test_a_normal_200_traverses_every_registered_middleware_outer_to_"
"inner`. The only BaseHTTPMiddleware in the stack, so it is also the "
"only layer whose seam is a `call_next` rather than a raw ASGI call."
),
SecureCookieMiddleware: (
"Entered on every request below; must stay outside Session/RememberMe "
"so it can rewrite the Set-Cookie headers they wrote."
),
SecurityHeadersMiddleware: (
"Its stamping is compared across all five exit paths in "
"`TestSecurityHeadersIdenticalOnEveryExitPath`, including the 413 and "
"CSRF-403 produced by middleware INSIDE it."
),
BodySizeLimitMiddleware: (
"Drives the short-circuit tests: its 413 must skip every middleware "
"inside it and still come back stamped and CORS-carrying."
),
RememberMeMiddleware: (
"Entered on the 200 path and on the CSRF-403 path; proven NOT entered "
"on the 413 path (it sits inside BodySizeLimit)."
),
SessionMiddleware: (
"`TestCsrfSeesTheSessionThatSessionMiddlewareDecoded` proves CSRF "
"reads a session THIS middleware decoded, and the inverted-order "
"control shows what happens when it does not run first."
),
CSRFMiddleware: (
"Its 403 short-circuit is proven to skip DatabaseMiddleware and only "
"DatabaseMiddleware."
),
DatabaseMiddleware: (
"Innermost: entered on the 200 path, proven skipped on both "
"short-circuit paths (413 and CSRF-403) — the point of it being last."
),
}
class TestStackCompositionPremise:
def test_the_live_stack_is_exactly_the_eight_expected_middleware(self, app):
"""Guard: everything below assumes this specific eight-layer stack.
CORS is deliberately absent — ``_configure_cors`` is fail-closed and
``security.cors.allowed_origins`` is unset by default, so the live app
carries eight. The CORS tests in this file therefore compose the real
``_configure_cors`` onto a throwaway app; see that class's docstring.
"""
actual = _live_order(app)
assert len(actual) == 8, (
"the live middleware stack no longer has eight layers, so every "
"ordering/short-circuit assertion in this file is now about a "
f"different stack than the one it was written for:\n {actual}"
)
def test_every_registered_middleware_is_named_in_this_files_coverage_map(
self, app
):
"""A ninth middleware must not silently arrive uncovered.
The whole file is premised on knowing what each layer is for. If
``fastapi_app.py`` gains (or loses) a middleware, this fails with both
rosters named rather than the new layer quietly never being exercised.
"""
live = {m.cls for m in app.user_middleware}
mapped = set(_COVERAGE_MAP)
assert live == mapped, (
"the middleware roster and this file's coverage map disagree.\n"
f" registered but uncovered: "
f"{sorted(c.__name__ for c in live - mapped)}\n"
f" covered but not registered: "
f"{sorted(c.__name__ for c in mapped - live)}\n"
"Add the new middleware to _COVERAGE_MAP together with a note on "
"what its position in the chain is load-bearing for."
)
assert all(_COVERAGE_MAP.values()), (
"every entry in _COVERAGE_MAP must say how the middleware is "
"exercised; an empty note makes the guard cosmetic"
)
def test_add_middleware_is_lifo_so_the_registration_list_reads_backwards(
self,
):
"""Executable proof of the premise the whole file (and
``fastapi_app.py``'s comments) rest on.
``app.add_middleware`` prepends, so ``user_middleware`` is the
registration order reversed and a request traverses it in that
reversed order. Pinned on a throwaway app with three marker
middleware, so a future Starlette change to this rule fails here —
visibly, with a one-line explanation — instead of silently inverting
the real stack while every list-shaped assertion elsewhere keeps
passing.
"""
traversed = []
def _marker(name):
class _Marker:
def __init__(self, app):
self.app = app
async def __call__(self, scope, receive, send):
if scope["type"] == "http":
traversed.append(name)
await self.app(scope, receive, send)
_Marker.__name__ = f"_Marker{name}"
return _Marker
first, second, third = _marker("A"), _marker("B"), _marker("C")
probe = FastAPI()
@probe.get("/ping")
def ping():
return {"ok": True}
# Registration order: A, then B, then C.
probe.add_middleware(first)
probe.add_middleware(second)
probe.add_middleware(third)
assert [m.cls for m in probe.user_middleware] == [
third,
second,
first,
], (
"user_middleware is no longer the reverse of the registration "
"order; fastapi_app.py's whole 'add in reverse' comment block "
"(and every ordering test on this branch) assumes it is"
)
resp = TestClient(probe).get("/ping")
assert resp.status_code == 200
assert traversed == ["C", "B", "A"], (
"a request must traverse middleware last-registered-first; got "
f"{traversed}"
)
# ---------------------------------------------------------------------------
# 2. Live-chain instrumentation
# ---------------------------------------------------------------------------
class _Traversal:
"""Records which registered middleware a real request actually entered."""
def __init__(self, entered, order):
self._entered = entered
self.order = order
def send(self, call):
"""Run ``call()`` and return ``(response, entered_middleware_names)``."""
self._entered.clear()
response = call()
return response, list(self._entered)
@pytest.fixture
def traversal(app, client):
"""Instrument every seam of the LIVE, already-built middleware chain.
Walks the real object graph ``build_middleware_stack()`` produced and
replaces each parent's ``.app`` reference with a recorder that notes the
child layer's name before delegating to the untouched original. This
observes the chain that actually serves requests rather than rebuilding
one — a rebuilt stack would be a different object graph and could not
prove anything about the live one — and it is what makes "every middleware
is exercised" and "the short-circuit skips the inner ones" directly
observable instead of inferred.
Everything is restored in ``finally``; the recorders add a list append and
change nothing about the request or response.
"""
# Force Starlette to build the stack (it does so lazily on first call).
client.get("/api/v1/health")
stack = app.middleware_stack
assert stack is not None, (
"app.middleware_stack was not built by a real request; this fixture "
"must instrument the live chain, not a freshly built copy"
)
registered = {m.cls for m in app.user_middleware}
entered = []
restore = []
seen = set()
def _recorder(inner, name):
async def _record(scope, receive, send):
if scope["type"] == "http":
entered.append(name)
await inner(scope, receive, send)
return _record
layer = stack
while layer is not None and id(layer) not in seen:
seen.add(id(layer))
child = getattr(layer, "app", None)
if type(child) in registered:
restore.append((layer, child))
layer.app = _recorder(child, type(child).__name__)
layer = child
assert len(restore) == len(registered), (
"could not instrument every registered middleware in the live chain: "
f"instrumented {len(restore)} of {len(registered)}"
)
try:
yield _Traversal(entered, _live_order(app))
finally:
for parent, original in restore:
parent.app = original
class TestEveryMiddlewareRunsOnARealRequest:
def test_a_normal_200_traverses_every_registered_middleware_outer_to_inner(
self, traversal, client
):
"""Positive control for every short-circuit test below, and the
execution-order counterpart to the structural pin in
``test_middleware_order_and_headers.py``.
The expected sequence is read off ``app.user_middleware`` rather than
hardcoded, so this asserts the *live chain agrees with the live
registration list on a real request* — the two could diverge only via
a Starlette internals change, which is exactly what would make every
list-shaped ordering assertion on this branch meaningless.
"""
resp, entered = traversal.send(lambda: client.get("/api/v1/health"))
assert resp.status_code == 200
assert entered == traversal.order, (
"a plain 200 did not pass through the registered middleware in "
"the registered order.\n"
f" registered (outer->inner): {traversal.order}\n"
f" actually entered: {entered}"
)
def test_an_unregistered_exception_500_still_traverses_the_whole_stack(
self, traversal, client
):
"""The ``ServerErrorMiddleware`` bypass is response-side only.
Worth pinning explicitly because it is easy to read the bypass as
"the 500 path skips the middleware". It does not: the *request* runs
all the way in (DatabaseMiddleware opened a connection, CSRF ran,
the session was decoded) and the exception then unwinds back out as a
live Python exception through every layer, none of which wraps its
downstream call in try/except — so no response-rewriting ``send``
wrapper ever fires. That asymmetry is why the catch-all handler has to
restamp the headers itself, and why it can only restamp what it knows
about (see the CORS gap pinned further down).
"""
resp, entered = traversal.send(lambda: client.get("/__mw_stack__/boom"))
assert resp.status_code == 500
assert resp.json() == {"error": "Server error"}
assert entered == traversal.order, (
"the inbound leg of an unregistered-exception request must still "
"pass through every middleware; only the response leg is "
"bypassed.\n"
f" registered (outer->inner): {traversal.order}\n"
f" actually entered: {entered}"
)
class TestShortCircuitSkipsInnerMiddleware:
"""A middleware that answers by itself must skip everything inside it —
that is the entire reason BodySizeLimit sits outside Session/CSRF and CSRF
sits outside Database — while still producing a response that climbs back
out through everything outside it."""
def _oversized(self, client):
return client.post(
"/auth/login",
content=b"x",
headers={
"Content-Length": _OVER_CAP_CONTENT_LENGTH,
"Content-Type": "application/json",
},
)
def test_body_size_limit_413_skips_every_middleware_inside_it(
self, traversal, client
):
"""The cap exists so an oversized body is rejected before anything
buffers or parses it. If the 413 still ran Session, CSRF and Database,
the placement would buy nothing: CSRFMiddleware buffers urlencoded
bodies to read the token, and DatabaseMiddleware opens a per-user
encrypted connection.
"""
resp, entered = traversal.send(lambda: self._oversized(client))
cut = traversal.order.index("BodySizeLimitMiddleware")
assert entered == traversal.order[: cut + 1], (
"the 413 short-circuit entered the wrong set of layers.\n"
f" registered (outer->inner): {traversal.order}\n"
f" expected (down to and including BodySizeLimitMiddleware): "
f"{traversal.order[: cut + 1]}\n"
f" actually entered: {entered}"
)
for skipped in (
"RememberMeMiddleware",
"SessionMiddleware",
"CSRFMiddleware",
"DatabaseMiddleware",
):
assert skipped not in entered, (
f"{skipped} ran for a request rejected as too large; the body "
"cap is placed outside it precisely so it does not"
)
assert resp.status_code == 413
def test_body_size_limit_413_is_still_a_well_formed_stamped_response(
self, client
):
"""Skipping inward must not mean skipping outward.
``BodySizeLimitMiddleware._send_413`` writes onto the ``send`` it was
handed, which is the wrapped ``send`` from SecurityHeaders,
SecureCookie and SlowAPI — so the short-circuit response still climbs
out through them. Positive control is in
``TestSecurityHeadersIdenticalOnEveryExitPath``, which compares this
exact response's header values against a 200's.
"""
resp = self._oversized(client)
assert resp.status_code == 413
# This is the declared-length path -- SessionMiddleware never runs
# here at all (see the skip-list assertion above). `_send_413`
# (fastapi_app.py) fabricates its own empty-session scope
# regardless, so `request.session` doesn't raise, and the
# standalone `pages/error.html` page (PR #5424) renders
# successfully here rather than falling back to the plain-text
# body used when rendering isn't possible.
assert "data-error-page" in resp.text
assert resp.headers["content-type"].startswith("text/html")
missing = [h for h in _ALL_STAMPED_HEADERS if h not in resp.headers]
assert missing == [], (
"the 413 produced by BodySizeLimitMiddleware lost headers that "
f"SecurityHeadersMiddleware stamps outside it: {missing!r}"
)
assert "server" not in resp.headers
def test_csrf_rejection_skips_only_the_database_middleware(
self, traversal, client
):
"""CSRF is registered directly outside Database so a forged or
token-less mutation is rejected before a per-user encrypted DB
connection is opened for it — and directly inside Session so it has a
decoded session to check against. Both halves of that sandwich are
asserted here: everything down to and including CSRF ran, and only
Database did not.
"""
resp, entered = traversal.send(lambda: client.post("/auth/logout"))
assert resp.status_code == 403
assert resp.json()["error"].startswith("CSRF token missing")
cut = traversal.order.index("CSRFMiddleware")
assert entered == traversal.order[: cut + 1], (
"a CSRF rejection entered the wrong set of layers.\n"
f" registered (outer->inner): {traversal.order}\n"
f" expected (down to and including CSRFMiddleware): "
f"{traversal.order[: cut + 1]}\n"
f" actually entered: {entered}"
)
assert "DatabaseMiddleware" not in entered, (
"a CSRF-rejected request opened a user database connection; CSRF "
"is registered outside DatabaseMiddleware to prevent exactly that"
)
assert "SessionMiddleware" in entered, (
"SessionMiddleware did not run before CSRFMiddleware, so CSRF "
"cannot have had a decoded session to check"
)
# ---------------------------------------------------------------------------
# 3. Exit-path uniformity
# ---------------------------------------------------------------------------
class TestSecurityHeadersIdenticalOnEveryExitPath:
"""Five structurally distinct response producers, one header contract.
Each of these responses is built by a different layer, and each could lose
or diverge on the headers independently:
* 200 — the router, response leg through all eight middleware.
* 404 — an exception handler, inside ExceptionMiddleware (innermost).
* 413 — BodySizeLimitMiddleware answering on its own, mid-stack.
* 403 — CSRFMiddleware answering on its own, one layer deeper.
* 500 — the catch-all handler wired into ``ServerErrorMiddleware``, which
sits OUTSIDE every registered middleware and writes to the raw
ASGI ``send``. That response never passes through
SecurityHeadersMiddleware at all; the handler restamps by hand.
Sibling suites already assert that individual paths carry the headers.
What is asserted here is stronger and is a composition property: the
values must be IDENTICAL across all five. Hand-restamping on the 500 path
is a copy of the middleware's behaviour living in a different function —
the failure mode is not "absent", it is "drifted".
"""
def _producers(self, client):
return {
"200 (router)": client.get("/api/v1/health"),
"404 (exception handler)": client.get(
"/no-such-route-mw-stack-contracts"
),
"413 (BodySizeLimit short-circuit)": client.post(
"/auth/login",
content=b"x",
headers={
"Content-Length": _OVER_CAP_CONTENT_LENGTH,
"Content-Type": "application/json",
},
),
"403 (CSRF short-circuit)": client.post("/auth/logout"),
"500 (ServerErrorMiddleware catch-all)": client.get(
"/__mw_stack__/boom"
),
}
def test_the_same_headers_with_the_same_values_on_every_exit_path(
self, client
):
responses = self._producers(client)
# Prove each response really is the one intended, so nothing below can
# pass against a response that never happened.
expected_status = {
"200 (router)": 200,
"404 (exception handler)": 404,
"413 (BodySizeLimit short-circuit)": 413,
"403 (CSRF short-circuit)": 403,
"500 (ServerErrorMiddleware catch-all)": 500,
}
for label, resp in responses.items():
assert resp.status_code == expected_status[label], (
f"{label}: expected status {expected_status[label]}, got "
f"{resp.status_code} — the probe no longer produces this "
f"response class"
)
# Positive control: the baseline itself must really carry them, or
# "identical everywhere" would be satisfiable by "absent everywhere".
baseline = responses["200 (router)"]
missing_on_200 = [
h for h in _ALL_STAMPED_HEADERS if h not in baseline.headers
]
assert missing_on_200 == [], (
"the 200 baseline is missing headers, so this test cannot "
f"distinguish 'stamped everywhere' from 'stamped nowhere': "
f"{missing_on_200!r}"
)
assert baseline.headers["content-security-policy"].startswith(
"default-src "
), (
"the baseline CSP is not a CSP; comparing the other exit paths "
"against it would prove nothing"
)
for label, resp in responses.items():
drift = {
name: (
baseline.headers.get(name),
resp.headers.get(name),
)
for name in _ALL_STAMPED_HEADERS
if _normalise_header(name, baseline.headers.get(name))
!= _normalise_header(name, resp.headers.get(name))
}
assert drift == {}, (
f"{label} does not carry the same stamped headers as the 200 "
f"baseline. Each entry is (200 value, {label} value):\n"
f" {drift!r}"
)
def test_no_exit_path_leaks_a_server_header(self, client):
"""``SecurityHeadersMiddleware`` strips ``Server`` unconditionally,
but two of these five responses never pass through it. Asserted
alongside the header comparison because it is the same question — does
a response produced outside the stack still meet the stack's contract.
"""
leaked = {
label: resp.headers["server"]
for label, resp in self._producers(client).items()
if "server" in resp.headers
}
assert leaked == {}, f"Server header leaked on: {leaked!r}"
# ---------------------------------------------------------------------------
# 4. CORS on error responses
# ---------------------------------------------------------------------------
_ENV_SETTING = "local_deep_research.settings.env_registry.get_env_setting"
_CORS_ORIGIN = "https://api-client.example"
class _CorsProbeError(RuntimeError):
"""Unregistered exception type — same role as ``_StackProbeError``."""
def _cors_probe_app():
"""Throwaway app composed from the REAL pieces, in the real order.
The live app reads ``security.cors.allowed_origins`` once at import and
the default is empty (fail-closed, pinned by
``tests/web/test_cors_config.py``), so there is no CORS middleware on the
singleton to test against. Like ``test_cors_config.py`` and
``tests/security/test_security_headers_fastapi.py``, this patches the
setting and composes a fresh app — but out of the real
``_configure_cors``, the real ``_register_exception_handlers``, the real
``SecurityHeadersMiddleware`` and the real ``BodySizeLimitMiddleware``,
registered in the same relative order fastapi_app.py uses:
BodySizeLimit added first -> SecurityHeaders -> CORS added last
which yields outer -> inner ``CORS -> SecurityHeaders -> BodySizeLimit``,
exactly their relative positions in the production stack. Nothing here is
a reimplementation; the only thing omitted is the five middleware that
have no bearing on where CORS headers come from.
"""
app = FastAPI()
@app.get("/api/v1/ok")
def ok():
return {"status": "ok"}
@app.post("/api/v1/ok-post")
def ok_post():
return {"status": "ok"}
@app.get("/api/v1/unavailable")
def unavailable():
raise HTTPException(status_code=503, detail="upstream down")
@app.get("/api/v1/boom")
def boom():
raise _CorsProbeError("probe: unregistered exception type")
app.add_middleware(BodySizeLimitMiddleware)
app.add_middleware(SecurityHeadersMiddleware)
_register_exception_handlers(app)
with patch(_ENV_SETTING, return_value=_CORS_ORIGIN):
_configure_cors(app)
return app
@pytest.fixture(scope="module")
def cors_client():
return TestClient(_cors_probe_app(), raise_server_exceptions=False)
class TestCorsOnErrorResponses:
"""CORS is the outermost layer, so in principle every response climbing
back out should carry its headers. In practice that depends on which layer
built the response — and one class of response is built outside CORS
entirely.
This matters to a real client: a browser that cannot read the
``Access-Control-Allow-Origin`` on a 500 does not see "500", it sees an
opaque network failure with a CORS console error. A cross-origin API
client therefore cannot distinguish a server fault from being blocked.
"""
def test_cors_headers_on_a_successful_api_response(self, cors_client):
"""Positive control. Without it, every "CORS header present on an
error" assertion below could pass on an app where CORS was never
wired up, and every "absent" assertion could pass vacuously."""
resp = cors_client.get("/api/v1/ok", headers={"Origin": _CORS_ORIGIN})
assert resp.status_code == 200
assert resp.json() == {"status": "ok"}
assert (
resp.headers.get("access-control-allow-origin") == _CORS_ORIGIN
), "CORS is not wired up on the probe app; nothing below is meaningful"
assert "content-security-policy" in resp.headers
def test_cors_headers_survive_an_http_exception_error_response(
self, cors_client
):
"""A 5xx raised as ``HTTPException`` is answered by
``ExceptionMiddleware``, which Starlette installs INNERMOST — inside
every registered middleware. That response therefore climbs out
through SecurityHeaders and then CORS like any 200, and must carry
both header families.
"""
resp = cors_client.get(
"/api/v1/unavailable", headers={"Origin": _CORS_ORIGIN}
)
assert resp.status_code == 503
assert resp.json()["detail"] == "upstream down"
assert (
resp.headers.get("access-control-allow-origin") == _CORS_ORIGIN
), (
"a 503 lost its CORS headers; a cross-origin client would see an "
"opaque failure instead of the error"
)
assert "content-security-policy" in resp.headers
def test_cors_headers_survive_the_body_size_limit_short_circuit(
self, cors_client
):
"""A middleware short-circuit is answered mid-stack, never reaching a
route — but it is still inside CORS, so it must come back with both
the CORS headers and the security headers.
"""
resp = cors_client.post(
"/api/v1/ok-post",
content=b"x",
headers={
"Origin": _CORS_ORIGIN,
"Content-Length": _OVER_CAP_CONTENT_LENGTH,
"Content-Type": "application/json",
},
)
assert resp.status_code == 413
assert resp.json() == {"error": "Request too large"}
assert (
resp.headers.get("access-control-allow-origin") == _CORS_ORIGIN
), (
"the 413 short-circuit lost its CORS headers even though "
"BodySizeLimitMiddleware sits inside CORSMiddleware"
)
assert "content-security-policy" in resp.headers
def test_KNOWN_GAP_cors_headers_are_absent_on_the_catch_all_500(
self, cors_client
):
"""PINNED CURRENT BEHAVIOUR, not an endorsement.
Registering a handler for the bare ``Exception`` class makes Starlette
wire it into ``ServerErrorMiddleware``, which is installed outside
every ``add_middleware`` call — outside CORS included. The handler in
``fastapi_app.py`` restamps the SECURITY headers itself (via
``SecurityHeadersMiddleware.unconditional_headers()`` +
``cache_headers()``), which is why those survive. It does NOT restamp
the CORS headers, and it structurally cannot do so the same way: the
correct value depends on the request's ``Origin`` and on the
configured allow-list, which lives inside the ``CORSMiddleware``
instance the handler has no reference to.
Consequence: a cross-origin API client sees an opaque CORS failure
rather than the 500. Both halves are asserted here — security headers
PRESENT, CORS headers ABSENT — so this test fails in either direction:
if someone fixes the gap it fails and gets updated deliberately, and
if someone breaks the security-header restamp it fails too.
"""
resp = cors_client.get("/api/v1/boom", headers={"Origin": _CORS_ORIGIN})
assert resp.status_code == 500
assert resp.json() == {"error": "Server error"}
missing_security = [
h for h in _ALL_STAMPED_HEADERS if h not in resp.headers
]
assert missing_security == [], (
"the catch-all 500 handler stopped restamping security headers: "
f"{missing_security!r}"
)
assert "access-control-allow-origin" not in resp.headers, (
"CORS headers are now present on the catch-all 500. That is an "
"IMPROVEMENT over the behaviour this test pinned — update this "
"test to assert the header equals the request Origin, and say in "
"the docstring how the handler learned the allow-list."
)
# ---------------------------------------------------------------------------
# 5. CSRF genuinely reads the session SessionMiddleware decoded
# ---------------------------------------------------------------------------
def _csrf_session_app(csrf_inside_session):
"""Two real middleware, one real token generator, order as the parameter.
``csrf_inside_session=True`` reproduces production (Session outside CSRF).
``False`` is the inverted stack — the single line-swap in fastapi_app.py
that this file's docstring is about. Both apps are otherwise identical and
both use the unmodified ``CSRFMiddleware``, ``SessionMiddleware`` and
``generate_csrf_token`` from src, so the ONLY variable is registration
order.
"""
app = FastAPI()
@app.get("/auth/csrf-token")
def mint(request: Request):
# Annotated: FastAPI injects the Request by TYPE, not by name — an
# unannotated `request` parameter would be read as a query parameter
# and `generate_csrf_token` would get a string.
return {"csrf_token": generate_csrf_token(request)}
@app.post("/mutate")
def mutate():
return {"ok": True}
if csrf_inside_session:
app.add_middleware(CSRFMiddleware)
app.add_middleware(
SessionMiddleware, secret_key="k" * 32, session_cookie="session"
)
else:
app.add_middleware(
SessionMiddleware, secret_key="k" * 32, session_cookie="session"
)
app.add_middleware(CSRFMiddleware)
return app
class TestCsrfSeesTheSessionThatSessionMiddlewareDecoded:
"""Positional proof that Session is outside CSRF is not enough — a list
index says nothing about whether the session CSRF reads is *populated*.
These drive the distinction behaviourally, using the two error messages
``CSRFMiddleware`` itself distinguishes:
* "CSRF token missing: fetch /auth/csrf-token first" — ``scope['session']``
had no ``_csrf_token``, i.e. CSRF saw an EMPTY session.
* "CSRF token missing or invalid" — the session HAD a token and it did not
match the one presented, i.e. CSRF saw a POPULATED session and compared
against its contents.
The second message is only reachable if SessionMiddleware really decoded
the cookie before CSRF ran. That is the behavioural evidence a positional
assertion cannot give.
"""
def test_a_valid_token_with_its_own_session_is_accepted(self, client):
"""Positive control on the real app: the session round-trips and the
token is honoured, so the two rejection tests below are about the
session, not about the route being unreachable."""
token = client.get("/auth/csrf-token").json()["csrf_token"]
assert token
resp = client.post(
"/auth/logout",
headers={"X-CSRFToken": token},
follow_redirects=False,
)
assert resp.status_code == 302
assert resp.headers["location"] == "/auth/login"
def test_a_token_replayed_without_its_session_cookie_is_rejected_as_missing(
self, app
):
"""Same token, no session cookie. CSRF must see an empty session and
say so — proving the token alone is not what it checks."""
minter = TestClient(app, raise_server_exceptions=False)
token = minter.get("/auth/csrf-token").json()["csrf_token"]
cookieless = TestClient(app, raise_server_exceptions=False)
resp = cookieless.post(
"/auth/logout",
headers={"X-CSRFToken": token},
follow_redirects=False,
)
assert resp.status_code == 403
assert resp.json() == {
"error": "CSRF token missing: fetch /auth/csrf-token first"
}, (
"a token presented with no session was not rejected as a missing "
"SESSION token; CSRF may be checking the header in isolation"
)
def test_a_token_replayed_against_a_different_session_is_rejected(
self, app
):
"""The load-bearing case. Session B's cookie plus session A's token
must produce the *invalid* rejection, not the *missing* one.
Reaching that branch at all requires ``scope['session']`` to have been
populated with B's own ``_csrf_token`` before CSRF ran — so this is a
direct behavioural observation that SessionMiddleware decoded the
cookie first. If CSRF ran outside Session, every request would take
the "missing" branch instead and this assertion would fail.
"""
alice = TestClient(app, raise_server_exceptions=False)
bob = TestClient(app, raise_server_exceptions=False)
alice_token = alice.get("/auth/csrf-token").json()["csrf_token"]
bob_token = bob.get("/auth/csrf-token").json()["csrf_token"]
assert alice_token != bob_token, (
"two independent clients received the same CSRF token; the token "
"is not session-bound and this test proves nothing"
)
resp = bob.post(
"/auth/logout",
headers={"X-CSRFToken": alice_token},
follow_redirects=False,
)
assert resp.status_code == 403
assert resp.json() == {"error": "CSRF token missing or invalid"}, (
"presenting another session's token did not reach the "
"compare-against-the-session branch, which means CSRF did not see "
"a populated session — check that SessionMiddleware is still "
"registered OUTSIDE CSRFMiddleware"
)
def test_NEGATIVE_CONTROL_csrf_outside_session_rejects_every_request(self):
"""The reorder, executed.
Two throwaway apps, identical except for the order of two
``add_middleware`` calls, both using the real middleware classes.
Correct order: mint a token, present it, get 200. Inverted order: mint
a token (the mint route itself still works — the session cookie is
written on the way out), present it, and get a 403 saying the session
had no token at all, because CSRF ran before SessionMiddleware had
decoded the cookie.
This is the failure the production ordering exists to prevent, and it
is why the assertions above are worth having: nothing about the
inverted app raises, logs an error, or fails to start.
"""
correct = TestClient(_csrf_session_app(csrf_inside_session=True))
assert [m.cls for m in correct.app.user_middleware] == [
SessionMiddleware,
CSRFMiddleware,
]
token = correct.get("/auth/csrf-token").json()["csrf_token"]
ok = correct.post("/mutate", headers={"X-CSRFToken": token})
assert ok.status_code == 200, (
"the CORRECT ordering rejected a valid token; the control below "
f"would be meaningless: {ok.status_code} {ok.text}"
)
assert ok.json() == {"ok": True}
inverted = TestClient(_csrf_session_app(csrf_inside_session=False))
assert [m.cls for m in inverted.app.user_middleware] == [
CSRFMiddleware,
SessionMiddleware,
]
token = inverted.get("/auth/csrf-token").json()["csrf_token"]
assert token, "the inverted app still mints tokens — it looks healthy"
broken = inverted.post("/mutate", headers={"X-CSRFToken": token})
assert broken.status_code == 403, (
"CSRF registered OUTSIDE SessionMiddleware accepted a request; "
"the ordering constraint this file pins would then be unfounded"
)
assert broken.json() == {
"error": "CSRF token missing: fetch /auth/csrf-token first"
}, (
"the inverted stack failed for some reason other than an empty "
f"session: {broken.json()!r}"
)