~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
"""FastAPI successors to the Flask-era auth-enforcement suites.
Provenance
----------
The FastAPI migration deleted three Flask test files. This module ports the
behaviour that is still applicable and documents (in the classifications
below) what genuinely cannot exist any more:
``tests/security/test_session_username_hardening.py`` (deleted)
A STATIC source-analysis suite asserting that every ``@login_required``
Flask handler read ``session["username"]`` (bracket access, KeyError if
the decorator were ever dropped) rather than ``session.get("username")``
(silently None). There is no Flask session and no decorator any more, so
the literal check is obsolete — but its INTENT is not: *a route must not
silently proceed with an absent username*. Under FastAPI that intent is
enforced by a dependency (``Depends(require_auth)``), so the faithful
successor is a sweep of the REAL route table asserting every route either
declares that dependency or is a justified public route — plus a
behavioural sweep proving an anonymous caller is actually rejected.
Note that ``tests/web/routers/test_router_sibling_consistency.py::
test_every_mutating_route_requires_auth_or_is_allowlisted`` already
pins the static half for POST/PUT/PATCH/DELETE only. The deleted suite
was dominated by READ routes (news feed, history, research details/
logs/status/report, library stats/documents, metrics, benchmark
history/results, RAG stats/collections, deletion previews) — i.e.
exactly the half that sibling test does not cover, and where a missing
gate leaks another user's data rather than corrupting it. The sweeps
here cover every method, and add the behavioural dimension no existing
test has: a static check cannot see a route that declares the
dependency but is reached anyway, nor one that re-derives the username
from ``request.session.get(...)`` in its own body.
``tests/auth_tests/test_auth_decorators.py`` (deleted)
``login_required`` / ``current_user`` / ``inject_current_user``.
``inject_current_user`` (a ``before_request`` hook populating
``g.current_user`` / ``g.db_session``) has no successor — there is no
``g``, and its database half is now ``ensure_user_database`` (covered by
``tests/web/test_ensure_user_database_token_ordering.py``). The
redirect / allow / disconnected-DB branches are covered by
``tests/security/test_login_required_boundaries.py`` and
``tests/web/dependencies/test_session_revocation.py``. What was left
uncovered is ``current_user()``'s successor,
``dependencies.auth.get_session_username`` — the OPTIONAL-auth
dependency, whose whole contract is returning ``None`` instead of
raising. It is wired to a real route (``GET /api/v1/health``) and only
ever exercised through ``dependency_overrides`` elsewhere, so nothing
tested the real function.
``tests/security/test_decorators.py`` (deleted)
``security.decorators.require_json_body``, a Flask decorator that
rejected any non-``dict`` JSON body with one of three response
envelopes. The decorator is gone; the response half survives as
``web.dependencies.json_body.json_body_error`` and is applied by hand at
56 call sites. The per-route application is well covered by the
``test_*_hostile_input.py`` family — but every one of those tests derives
its expected envelope FROM ``json_body_error`` itself
(``_envelope_from_sut``), deliberately, so the helper's own contract is
the one thing they cannot pin. The front end branches on these exact
keys, so they are pinned here.
Everything below runs against the REAL assembled app
(``local_deep_research.web.fastapi_app.app``) rather than a synthetic one,
because the defect class being guarded is "this production route forgot the
dependency", which a synthetic app cannot express.
"""
from __future__ import annotations
import inspect
import json
import re
import uuid
import pytest
from fastapi import Depends, FastAPI, Request
from fastapi.routing import APIRoute
from fastapi.testclient import TestClient
from starlette.middleware.sessions import SessionMiddleware
from local_deep_research.web.dependencies.auth import (
get_session_username,
require_auth,
)
from local_deep_research.web.dependencies.json_body import (
DEFAULT_MESSAGE,
json_body_error,
)
# The autouse ``_legacy_bare_username_auth`` shim in tests/conftest.py patches
# ``_server_session_valid`` to accept unconditionally. Nothing here
# authenticates, so the shim is inert — but this suite exists precisely to
# prove the auth gate is real, and it must never be able to run against a
# relaxed gate.
pytestmark = pytest.mark.real_session_check
# ---------------------------------------------------------------------------
# Route-table helpers
# ---------------------------------------------------------------------------
_PATH_PARAM_RE = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)(?::[^}]+)?\}")
_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
_MUTATING_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
# Nonexistent-but-syntactically-valid path-param fillers. Every swept route is
# expected to reject before its handler runs, so these are never looked up —
# they exist so the URL routes at all.
_MISSING_UUID = uuid.uuid4().hex
_MISSING_INT = "999999999"
def _live_app():
from local_deep_research.web.fastapi_app import app
return app
def _is_test_probe_route(path: str) -> bool:
"""Routes other test modules bolt onto the live ``app`` singleton.
``tests/web/test_middleware_order_and_headers.py`` and
``tests/security/test_security_headers_fastapi.py`` register probe routes
(``/__mw_order_probe__/*``, ``/__sec_hdr_probe__/*``) on the shared app at
import time. Whether they are present in this sweep depends purely on
whether those modules were imported first, which is decided by pytest's
file ordering — so they must be filtered out or this suite goes red for
routes no product code serves. ``test_all_endpoints.py`` filters the same
``/__`` prefix for the same reason.
"""
return path.startswith("/__")
def _iter_app_routes() -> list[tuple[str, str, APIRoute]]:
"""Every (method, path, route) pair the real app serves.
Restricted to ``APIRoute`` on purpose: that excludes the ``/ws`` Mount and
FastAPI's own ``/docs`` / ``/openapi.json`` built-ins (plain Starlette
``Route`` objects), none of which are application endpoints with an auth
contract of their own.
"""
pairs: list[tuple[str, str, APIRoute]] = []
for route in _live_app().routes:
if not isinstance(route, APIRoute):
continue
if _is_test_probe_route(route.path):
continue
for method in sorted(route.methods & _HTTP_METHODS):
pairs.append((method, route.path, route))
return sorted(pairs, key=lambda item: (item[1], item[0]))
def _fill_path_params(path: str, endpoint) -> str:
"""Replace each ``{param}`` with a valid-but-nonexistent value: a big
integer for params annotated ``int`` on the endpoint's own signature, a
UUID hex otherwise (covers ``str``, untyped, and ``{path:path}``)."""
try:
sig = inspect.signature(endpoint)
except (TypeError, ValueError):
sig = None
def _replace(match: re.Match[str]) -> str:
param = sig.parameters.get(match.group(1)) if sig else None
annotation = param.annotation if param is not None else inspect._empty
return _MISSING_INT if annotation is int else _MISSING_UUID
return _PATH_PARAM_RE.sub(_replace, path)
def _dependant_calls(dependant) -> set:
"""Every dependency callable reachable from *dependant*, walked
recursively (cycle-safe via identity dedup)."""
seen: set[int] = set()
calls: set = set()
def _walk(node) -> None:
if id(node) in seen:
return
seen.add(id(node))
if node.call is not None:
calls.add(node.call)
for sub in node.dependencies:
_walk(sub)
_walk(dependant)
return calls
def _requires_auth(route: APIRoute) -> bool:
"""True if ``require_auth`` is anywhere in this route's dependency tree.
Transitive on purpose: ``/api/v1/*`` routes declare
``Depends(require_api_access)``, and ``require_api_access`` itself takes
``username: str = Depends(require_auth)`` — strictly more gating, not
less. The news scheduler routes layer ``require_scheduler_control`` on
top of a direct ``require_auth`` the same way.
"""
return require_auth in _dependant_calls(route.dependant)
def _label(method: str, path: str, route: APIRoute) -> str:
return (
f"{method} {path} "
f"({route.endpoint.__module__}.{route.endpoint.__name__})"
)
# ---------------------------------------------------------------------------
# The public-route allowlist
# ---------------------------------------------------------------------------
#
# Derived by enumerating the live route table and reading, in full, every
# route that has no ``require_auth`` in its dependency tree — there are
# exactly 13 of 317, and all 13 appear below. Adding a NEW unauthenticated
# route without an entry here fails ``test_every_route_declares_require_auth_
# or_is_allowlisted`` by name.
# (method, path) -> why this route must work with no session at all.
PUBLIC_ROUTES: dict[tuple[str, str], str] = {
("GET", "/auth/login"): (
"the login form itself — requiring a session to reach it would make "
"logging in impossible."
),
("POST", "/auth/login"): (
"creates the session being authenticated against; same "
"chicken-and-egg as the form above."
),
("GET", "/auth/register"): (
"the registration form — reachable before any account exists."
),
("POST", "/auth/register"): (
"creates the account the session will belong to."
),
("POST", "/auth/logout"): (
"reads request.session directly and is a no-op when already logged "
"out. POST-only specifically so a CSRF-triggered GET (e.g. "
"<img src=/auth/logout>) cannot log a user out; there is no session "
"to require before clearing one."
),
("POST", "/auth/validate-password"): (
"stateless password-strength check the register / change-password "
"forms call on every keystroke, before a session exists. Guarded by "
"its own VALIDATE_PASSWORD_RATE_LIMIT bucket rather than a session, "
"documented in its docstring as preventing use as a complexity "
"oracle."
),
("GET", "/auth/csrf-token"): (
"the login and registration forms must obtain a CSRF token before "
"they can POST, i.e. before any session exists. Hands out a token "
"only, never user data."
),
("GET", "/api/v1/health"): (
"liveness/readiness probe for the documented external API. Takes the "
"OPTIONAL `Depends(get_session_username)`, not require_auth, and "
"widens its payload for a recognised session rather than gating on "
"one — see TestOptionalSessionUsernameDependency below."
),
(
"GET",
"/favicon.ico",
): "static asset; served before login by every browser.",
("GET", "/static/{path:path}"): (
"the static-asset handler — CSS/JS for the login page itself."
),
("GET", "/redirect-static/{path:path}"): (
"compatibility shim that serves static assets at legacy URLs; no user data."
),
}
# (method, path) -> why this route is safe WITHOUT the dependency.
# These have no ``require_auth`` in their dependency tree but are NOT public:
# each performs the anonymous-caller rejection itself, in its own body. They
# are excused from the STATIC sweep only, and are deliberately left in the
# BEHAVIOURAL sweep, which proves the hand-rolled rejection actually happens.
SELF_ENFORCING_ROUTES: dict[tuple[str, str], str] = {
("GET", "/"): (
"index() redirects an anonymous caller to /auth/login itself, then "
"calls require_auth(request) in its body and turns its 401 into the "
"same redirect, first ending any session require_auth left in place "
"(fastapi_app.py). Not a Depends(require_auth): the "
"global handler would answer that 401 differently from the redirect "
"this page has always returned."
),
("GET", "/auth/check"): (
"the AJAX 'am I logged in?' probe. Not a Depends(require_auth): the "
"global exception handler would rewrite that 401 into an HTML login "
"redirect for this non-/api/ path, breaking every XHR caller. It "
"calls require_auth(request) in its body and answers its 401 as "
"JSON 401 {'authenticated': false} instead."
),
}
_STATIC_ALLOWLIST = {**PUBLIC_ROUTES, **SELF_ENFORCING_ROUTES}
# Floors for the vacuity guards below. Set well under today's numbers (317
# route-method pairs: 180 GET, 137 mutating, 13 unauthenticated) so ordinary
# churn does not trip them, but high enough that a broken enumeration — the
# failure mode that would make every assertion in this file pass trivially —
# cannot slip through.
_MIN_TOTAL_ROUTES = 250
_MIN_GET_ROUTES = 140
_MIN_MUTATING_ROUTES = 100
_MIN_PROTECTED_ROUTES = 230
# ---------------------------------------------------------------------------
# Vacuity guards — these must fail before any sweep can pass on an empty set
# ---------------------------------------------------------------------------
class TestRouteTableEnumerationIsNotVacuous:
"""A sweep over an empty route table passes every assertion it makes.
That is the single most dangerous failure mode for this file, so the size
of the enumeration is pinned as its own test rather than being an
incidental property of the sweeps.
"""
def test_route_table_is_plausibly_sized(self):
pairs = _iter_app_routes()
assert len(pairs) >= _MIN_TOTAL_ROUTES, (
f"Only {len(pairs)} route-method pairs enumerated from the live "
f"app (expected >= {_MIN_TOTAL_ROUTES}). Either the app failed to "
"assemble its routers or _iter_app_routes() is broken — every "
"auth sweep in this file would be silently vacuous."
)
def test_both_read_and_mutating_routes_are_present(self):
pairs = _iter_app_routes()
gets = [p for p in pairs if p[0] == "GET"]
mutating = [p for p in pairs if p[0] in _MUTATING_METHODS]
assert len(gets) >= _MIN_GET_ROUTES, (
f"Only {len(gets)} GET routes enumerated (expected >= "
f"{_MIN_GET_ROUTES}). The deleted session-hardening suite was "
"dominated by read routes; a collapsed GET enumeration removes "
"exactly the coverage this file exists to restore."
)
assert len(mutating) >= _MIN_MUTATING_ROUTES, (
f"Only {len(mutating)} mutating routes enumerated (expected >= "
f"{_MIN_MUTATING_ROUTES})."
)
def test_most_routes_are_actually_protected(self):
"""The allowlist must stay a rounding error, not a loophole."""
pairs = _iter_app_routes()
protected = [p for p in pairs if _requires_auth(p[2])]
assert len(protected) >= _MIN_PROTECTED_ROUTES, (
f"Only {len(protected)} of {len(pairs)} routes declare "
f"require_auth (expected >= {_MIN_PROTECTED_ROUTES}). Either the "
"dependency-tree walk broke or a large family of routes lost "
"their auth gate."
)
def test_allowlist_entries_all_resolve_to_real_routes(self):
"""Stale allowlist entries are silent coverage loss.
A renamed or deleted route leaves behind an entry that would excuse
some future route that happens to reuse the path. Fail on the dead
entry instead.
"""
live = {(method, path) for method, path, _ in _iter_app_routes()}
stale = sorted(set(_STATIC_ALLOWLIST) - live)
assert not stale, (
"Allowlisted route(s) no longer exist on the app — remove the "
"entries from PUBLIC_ROUTES / SELF_ENFORCING_ROUTES:\n"
+ "\n".join(f" {method} {path}" for method, path in stale)
)
class TestAuthDetectorSelfTest:
"""The dependency-tree walk is the thing every static assertion below
rests on. Prove it distinguishes "has require_auth somewhere" from
"doesn't" against real FastAPI ``Dependant`` objects — a walker that
always returned True would make the static sweep vacuous in the other
direction."""
def _probe_route(self, *, use_auth: bool, nested: bool) -> APIRoute:
probe = FastAPI()
def _unrelated() -> str:
return "anonymous"
def _wrapper(username: str = Depends(require_auth)) -> str:
return username
if use_auth and nested:
dep = _wrapper
elif use_auth:
dep = require_auth
else:
dep = _unrelated
def handler(value: str = Depends(dep)) -> dict:
return {"value": value}
probe.get("/probe")(handler)
route = next(r for r in probe.routes if isinstance(r, APIRoute))
return route
def test_detects_direct_dependency(self):
assert _requires_auth(self._probe_route(use_auth=True, nested=False))
def test_detects_transitive_dependency(self):
assert _requires_auth(self._probe_route(use_auth=True, nested=True))
def test_rejects_route_with_only_unrelated_dependency(self):
assert not _requires_auth(
self._probe_route(use_auth=False, nested=False)
)
# ---------------------------------------------------------------------------
# 1. Static sweep — the direct successor of the deleted session-hardening
# suite, which was itself a static source-analysis suite.
# ---------------------------------------------------------------------------
def test_every_route_declares_require_auth_or_is_allowlisted():
"""Every route on the real app must have ``require_auth`` in its
dependency tree unless it is one of the verified public / self-enforcing
routes above.
This is the FastAPI-native form of "no ``@login_required`` handler may
read the username in a way that silently tolerates its absence": under
dependency injection the username cannot be absent, because the
dependency raises before the handler is entered. What CAN happen — and
is what this catches — is a route that never declares the dependency at
all.
"""
pairs = _iter_app_routes()
# Self-guard: this is the one sweep whose assertion passes trivially on
# an empty enumeration (TestRouteTableEnumerationIsNotVacuous also
# covers it, but a sweep that can go vacuous on its own is worth making
# self-checking).
assert len(pairs) >= _MIN_TOTAL_ROUTES, (
f"Only {len(pairs)} route-method pairs enumerated — this sweep "
"would pass trivially."
)
violations = []
for method, path, route in pairs:
if (method, path) in _STATIC_ALLOWLIST:
continue
if _requires_auth(route):
continue
violations.append(
f" {_label(method, path, route)} has no require_auth anywhere "
"in its dependency tree and is not allowlisted. Add "
"`username: str = Depends(require_auth)`, or — if it is "
"genuinely meant to be reachable without a session — add it to "
"PUBLIC_ROUTES with a justification (and to SELF_ENFORCING_"
"ROUTES instead if it enforces auth in its own body)."
)
assert not violations, (
f"{len(violations)} route(s) reachable without authentication:\n"
+ "\n".join(violations)
)
# ---------------------------------------------------------------------------
# 2. Behavioural sweeps — what no static check can see
# ---------------------------------------------------------------------------
@pytest.fixture(scope="module")
def anon_client():
"""A client that has never logged in.
Module-scoped so the sweeps below pay the app-import cost once. It holds
a cookie jar (the CSRF middleware is double-submit, so the token below is
bound to it) but never a ``username``.
"""
with TestClient(_live_app(), raise_server_exceptions=False) as client:
yield client
@pytest.fixture(scope="module")
def anon_csrf_token(anon_client):
"""A CSRF token issued to the anonymous client, plus a live control.
``CSRFMiddleware`` is installed with ``add_middleware``, so it runs
BEFORE routing: without a token every POST/PUT/PATCH/DELETE is rejected
with 403 by the middleware and no dependency ever runs. A mutating sweep
that accepted 403 as "rejected" would therefore pass even if every route
on the app lost its auth gate — the exact vacuous-pass trap.
So the token is obtained first and its usefulness is asserted here
against a route that is public but CSRF-protected. If that control ever
stops returning 200, this fixture fails loudly rather than letting the
sweep degrade into a CSRF test wearing an auth test's name.
"""
anon_client.get("/auth/login")
response = anon_client.get("/auth/csrf-token")
assert response.status_code == 200, (
f"GET /auth/csrf-token returned {response.status_code} for an "
"anonymous client; the mutating sweep cannot isolate auth from CSRF "
"without it."
)
token = response.json().get("csrf_token") or ""
assert token, "No csrf_token in the /auth/csrf-token payload."
control = anon_client.post(
"/auth/validate-password",
json={"password": "x"},
headers={"X-CSRFToken": token},
)
assert control.status_code == 200, (
"CONTROL FAILED: POST /auth/validate-password (public, "
"CSRF-protected) returned "
f"{control.status_code} with the anonymous CSRF token, so the token "
"is not passing the CSRF middleware. Every mutating request in the "
"sweep below would be rejected by CSRF rather than by auth, making "
"the sweep vacuous."
)
return token
def _rejection_reason(response) -> str | None:
"""``None`` if the response is an auth rejection, else why it is not.
Accepts the two shapes the app produces for an anonymous caller, and
only those:
* ``401`` — what ``require_auth`` raises, kept as JSON for ``/api/``
paths and for ``Accept: application/json`` callers.
* a redirect whose ``Location`` points at ``/auth/login`` — what the
global HTTPException handler rewrites that 401 into for browser-shaped
requests.
A bare ``403`` is deliberately NOT accepted: on mutating routes that is
the CSRF middleware answering before routing, which says nothing about
authentication.
"""
status = response.status_code
if status == 401:
return None
if 300 <= status < 400:
location = response.headers.get("location", "")
if "/auth/login" in location:
return None
return f"redirected to {location!r}, not to /auth/login"
if status == 403:
return (
"403 — that is the CSRF middleware rejecting before routing, "
"not the auth dependency"
)
if 200 <= status < 300:
return f"{status} — served a real response to an anonymous caller"
return f"{status} (expected 401 or a redirect to /auth/login)"
def test_unauthenticated_get_requests_are_rejected(anon_client):
"""Fire a real anonymous GET at every read route on the app.
The behavioural half of the session-hardening intent. A route that
declares the dependency correctly but re-derives the username from
``request.session.get("username")`` in its own body, or one whose gate
is bypassed by middleware ordering, is invisible to the static sweep and
visible here.
Safe to run against production routes: ``require_auth`` raises during
dependency resolution, so no handler body is entered for any protected
route. A route for which a handler DOES run is, by definition, the bug
being looked for.
"""
swept = 0
violations = []
for method, path, route in _iter_app_routes():
if method != "GET" or (method, path) in PUBLIC_ROUTES:
continue
swept += 1
url = _fill_path_params(path, route.endpoint)
response = anon_client.get(url, follow_redirects=False)
reason = _rejection_reason(response)
if reason is not None:
violations.append(
f" {_label(method, path, route)}: {reason}. "
f"Body: {response.text[:160]!r}"
)
assert swept >= _MIN_GET_ROUTES - len(PUBLIC_ROUTES), (
f"Only {swept} GET routes were actually requested — the sweep is "
"not covering the app."
)
assert not violations, (
f"{len(violations)} of {swept} GET route(s) did not reject an "
"anonymous request:\n" + "\n".join(violations)
)
def test_unauthenticated_mutating_requests_are_rejected(
anon_client, anon_csrf_token
):
"""Same sweep for POST/PUT/PATCH/DELETE, with a valid CSRF token.
The token is what makes this an auth test rather than a CSRF test: it
carries each request past ``CSRFMiddleware`` so that ``require_auth`` is
the thing that rejects it. ``_rejection_reason`` refuses to accept a
plain 403 for the same reason.
``tests/web/routers/test_router_sibling_consistency.py`` pins the static
half of this for mutating routes; this is the behavioural half, and it
is what proves the declared dependency actually fires.
"""
swept = 0
violations = []
for method, path, route in _iter_app_routes():
if method not in _MUTATING_METHODS or (method, path) in PUBLIC_ROUTES:
continue
swept += 1
url = _fill_path_params(path, route.endpoint)
response = anon_client.request(
method,
url,
json={},
headers={"X-CSRFToken": anon_csrf_token},
follow_redirects=False,
)
reason = _rejection_reason(response)
if reason is not None:
violations.append(
f" {_label(method, path, route)}: {reason}. "
f"Body: {response.text[:160]!r}"
)
assert swept >= _MIN_MUTATING_ROUTES - len(PUBLIC_ROUTES), (
f"Only {swept} mutating routes were actually requested — the sweep "
"is not covering the app."
)
assert not violations, (
f"{len(violations)} of {swept} mutating route(s) did not reject an "
"anonymous request:\n" + "\n".join(violations)
)
def test_self_enforcing_routes_reject_anonymous_callers(anon_client):
"""The two routes excused from the STATIC sweep must still reject.
``SELF_ENFORCING_ROUTES`` is the only way a route can lack
``require_auth`` without being public, so it is the obvious place to
quietly park an unprotected route. Both are swept behaviourally above;
asserting them here as well means the excuse is checked against the
thing it claims, by name, in a test that fails with the route's name in
it.
"""
for method, path in SELF_ENFORCING_ROUTES:
assert method == "GET", f"unexpected method in allowlist: {method}"
response = anon_client.get(path, follow_redirects=False)
reason = _rejection_reason(response)
assert reason is None, (
f"{method} {path} is excused from the static require_auth sweep "
f"on the grounds that it enforces auth itself, but {reason}. "
f"Body: {response.text[:200]!r}"
)
def test_public_get_routes_are_actually_reachable_anonymously(anon_client):
"""Positive control for the allowlist.
Without this, an allowlist entry for a route that 404s or 500s for
everyone would look like healthy coverage. Only the GET entries are
probed: the public MUTATING entries are the login/register/logout flow
itself, which has its own end-to-end tests and should not be driven from
a sweep.
Asserted as "not an auth rejection and not a server error" rather than
"200", because ``/favicon.ico`` and ``/static/{path}`` legitimately 404
in a test data directory that has no static files.
"""
probed = 0
for (method, path), reason in PUBLIC_ROUTES.items():
if method != "GET":
continue
probed += 1
route = next(
r for m, p, r in _iter_app_routes() if (m, p) == (method, path)
)
response = anon_client.get(
_fill_path_params(path, route.endpoint), follow_redirects=False
)
assert response.status_code != 401, (
f"{method} {path} is allowlisted as public ({reason}) but "
"returned 401 to an anonymous caller — the allowlist entry is "
"wrong or obsolete."
)
location = response.headers.get("location", "")
assert "/auth/login" not in location, (
f"{method} {path} is allowlisted as public ({reason}) but "
f"redirected to the login page ({location!r})."
)
assert response.status_code < 500, (
f"{method} {path} is allowlisted as public but returned "
f"{response.status_code}: {response.text[:200]!r}"
)
assert probed >= 5, (
f"Only {probed} public GET routes probed — PUBLIC_ROUTES is not "
"being iterated."
)
# ---------------------------------------------------------------------------
# 3. get_session_username — successor of Flask's current_user()
# ---------------------------------------------------------------------------
class TestOptionalSessionUsernameDependency:
"""``dependencies.auth.get_session_username`` replaces Flask's
``current_user()``: the OPTIONAL-auth dependency that answers ``None``
for an anonymous caller instead of raising.
``GET /api/v1/health`` is wired to it, so "returns None" is a real
contract, not a helper detail — a version that raised, or that returned
a truthy sentinel, would turn the liveness probe into a 401 or leak a
fake identity into its payload. Every other test of it in the tree goes
through ``dependency_overrides``, i.e. never runs the function.
"""
@pytest.fixture
def probe_client(self):
app = FastAPI()
app.add_middleware(SessionMiddleware, secret_key="test-secret-key")
@app.post("/_seed")
def seed(request: Request, payload: dict):
request.session.update(payload)
return {"ok": True}
@app.post("/_clear")
def clear(request: Request):
request.session.clear()
return {"ok": True}
@app.get("/whoami")
def whoami(username: str | None = Depends(get_session_username)):
return {"username": username, "is_none": username is None}
return TestClient(app, raise_server_exceptions=False)
def test_returns_none_without_a_session(self, probe_client):
response = probe_client.get("/whoami")
assert response.status_code == 200
assert response.json() == {"username": None, "is_none": True}
def test_returns_the_username_when_present(self, probe_client):
probe_client.post("/_seed", json={"username": "alice"})
response = probe_client.get("/whoami")
assert response.status_code == 200
assert response.json()["username"] == "alice"
def test_returns_none_again_after_the_session_is_cleared(
self, probe_client
):
probe_client.post("/_seed", json={"username": "alice"})
assert probe_client.get("/whoami").json()["username"] == "alice"
probe_client.post("/_clear")
assert probe_client.get("/whoami").json() == {
"username": None,
"is_none": True,
}
def test_does_not_raise_where_require_auth_would(self, probe_client):
"""The whole point of the split: the same anonymous request that
``require_auth`` turns into a 401 must be a plain 200 here."""
app = probe_client.app
@app.get("/gated")
def gated(username: str = Depends(require_auth)):
return {"username": username}
assert probe_client.get("/whoami").status_code == 200
assert probe_client.get("/gated").status_code == 401
def test_health_route_uses_the_optional_dependency_not_require_auth(self):
"""Pin the wiring the tests above are about.
Swapping ``get_session_username`` for ``require_auth`` on the health
probe would break every unauthenticated monitoring client, and
swapping it the other way on a data route would silently open it.
"""
route = next(
r
for m, p, r in _iter_app_routes()
if (m, p) == ("GET", "/api/v1/health")
)
calls = _dependant_calls(route.dependant)
assert get_session_username in calls
assert require_auth not in calls
# ---------------------------------------------------------------------------
# 4. json_body_error — response half of Flask's @require_json_body
# ---------------------------------------------------------------------------
class TestJsonBodyErrorEnvelopes:
"""The three response shapes ``@require_json_body`` produced.
Ported from the deleted ``TestErrorFormatStructure`` /
``TestCustomMessages`` / ``TestEmptyBody`` classes. The per-route
application of the guard is covered by the ``test_*_hostile_input.py``
family, but those files deliberately derive the expected envelope from
``json_body_error`` itself so that they test the ROUTE and not a copy of
the helper — which leaves the helper's own contract unpinned. The front
end branches on these exact keys (``success`` drives the chat, RAG and
library-search views; ``status`` drives settings and ratings), so a
silent change of shape turns a handled validation error into an
unhandled one in the browser.
"""
@staticmethod
def _payload(response) -> dict:
return json.loads(bytes(response.body))
def test_simple_format_keys(self):
response = json_body_error()
assert response.status_code == 400
assert self._payload(response) == {"error": DEFAULT_MESSAGE}
def test_status_format_keys(self):
response = json_body_error("status")
assert response.status_code == 400
assert self._payload(response) == {
"status": "error",
"message": DEFAULT_MESSAGE,
}
def test_success_format_keys(self):
response = json_body_error("success")
assert response.status_code == 400
assert self._payload(response) == {
"success": False,
"error": DEFAULT_MESSAGE,
}
def test_default_message_matches_flask_contract(self):
"""main's ``require_json_body`` default, verbatim."""
assert DEFAULT_MESSAGE == "Request body must be valid JSON"
@pytest.mark.parametrize(
("error_format", "message_key"),
[("simple", "error"), ("status", "message"), ("success", "error")],
)
def test_custom_message_replaces_the_default(
self, error_format, message_key
):
response = json_body_error(error_format, "Query parameter is required")
payload = self._payload(response)
assert payload[message_key] == "Query parameter is required"
assert DEFAULT_MESSAGE not in json.dumps(payload)
def test_unknown_format_falls_back_to_simple(self):
"""Defensive: a typo'd format must not produce an empty body or
raise. ``json_body_error`` branches with a trailing ``else``, so an
unrecognised value yields the simple envelope."""
response = json_body_error("not-a-format") # type: ignore[arg-type]
assert response.status_code == 400
assert self._payload(response) == {"error": DEFAULT_MESSAGE}
def test_json_body_error_is_still_the_shared_helper():
"""Tripwire against the coverage above being orphaned.
If ``json_body_error`` stops being what the routers call, these envelope
tests keep passing while pinning nothing. Assert it is still imported
across the router package.
"""
from pathlib import Path
import local_deep_research.web.routers as routers_pkg
routers_dir = Path(routers_pkg.__file__).parent
importers = [
path.name
for path in sorted(routers_dir.glob("*.py"))
if "json_body_error" in path.read_text(encoding="utf-8")
]
assert len(importers) >= 5, (
"json_body_error is referenced by only "
f"{len(importers)} router module(s) ({importers}) — it was the "
"shared 400 for non-dict JSON bodies across the router package. If "
"it has been replaced, move TestJsonBodyErrorEnvelopes onto the "
"successor rather than leaving it testing dead code."
)