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.

48.3 KB
Raw Blame
"""What runs — and what it *does* — before ``require_auth`` answers.

``tests/web/dependencies/test_dependency_contracts.py`` pins the shape of
FastAPI's dependency solver: signature order, caching, override plumbing,
``yield`` teardown. This module pins the layer underneath it — the part
that decides whether "auth is declared first" is actually a gate.

The distinction matters because the notes body-gate bug was never really
about parameter order. It was about a *side effect that a 401 cannot
undo*: the body had already been pulled off the wire and ``json.loads``-ed
by the time ``require_auth`` said no. Swapping two parameters fixed that
one instance. It does not, and cannot, fix the general case — because
FastAPI reads the request body **before** ``solve_dependencies`` is
called at all (``fastapi/routing.py``: body at ~line 404, dependencies at
~line 457, fastapi 0.136.3). No parameter ordering reaches earlier than
that.

So the questions this module answers are the ones ordering alone cannot:

1. **Body** — which routes still hand an anonymous caller's bytes to a
   parser before auth runs, and what does the client learn from it.
2. **Rate-limit slots** — a slot consumed by a request that then 401s is
   a side effect a later auth failure cannot undo. Two different answers
   here depending on whether the limit is a decorator or the middleware
   default.
3. **``get_db_session_dep``** — whether a database is opened before auth
   is decided, whether the session can be another session's, and what its
   ``try/except`` does to an exception that came from the *route*, not
   from the dependency.
4. **Divergence** — ``Depends`` caches per callable, so two dependencies
   that both "resolve the username" are two independent answers. They do
   disagree, on the same request, today.
5. **Error paths** — what the client sees when a dependency fails in a
   way that is not an ``HTTPException``.

Every ordering claim here is asserted against an observed side effect (a
byte count pulled through ``receive``, a rate-limit counter, a recorded
``get_user_db_session`` call, a ``Set-Cookie``), never against a status
code alone.
"""

from __future__ import annotations

import ast
import contextlib
import pathlib
import threading
from typing import Any
from unittest import mock

import pytest
from fastapi import Body, Depends, FastAPI, Form, HTTPException, Request
from fastapi.testclient import TestClient
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.errors import RateLimitExceeded
from slowapi.middleware import SlowAPIMiddleware
from starlette.middleware.sessions import SessionMiddleware

from local_deep_research.database.session_context import (
    DatabaseSessionError,
)
from local_deep_research.web.dependencies import auth as auth_module
from local_deep_research.web.dependencies import rate_limit as rl_module

SECRET = "unit-test-session-secret-key-0123456789"

_DEPS_DIR = pathlib.Path(auth_module.__file__).parent
_WEB_DIR = _DEPS_DIR.parent
_ROUTERS_DIR = _WEB_DIR / "routers"


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


class ReceiveSpy:
    """ASGI wrapper counting body bytes the inner app pulls off the wire.

    The only honest way to ask "was the body consumed before the 401?" —
    a status code cannot tell you, and ``Request.body()`` caches, so
    inspecting it after the fact proves nothing about *when*.
    """

    def __init__(self, app):
        self.app = app
        self.body_bytes = 0
        self.receive_calls = 0

    def reset(self) -> None:
        self.body_bytes = 0
        self.receive_calls = 0

    async def __call__(self, scope, receive, send):
        async def spy():
            message = await receive()
            self.receive_calls += 1
            if message["type"] == "http.request":
                self.body_bytes += len(message.get("body", b""))
            return message

        await self.app(scope, spy, send)


def _denying_gate(log: list[str]):
    """A stand-in for ``require_auth`` that always refuses.

    Used where the point is the solver's ordering, not ``require_auth``'s
    internals; the real dependency is exercised directly further down.
    """

    def gate(request: Request) -> str:
        log.append("auth")
        raise HTTPException(status_code=401, detail="Authentication required")

    return gate


def _make_recording_db_session(calls: list[tuple]):
    """Replacement for ``get_user_db_session`` that records how it was
    called: which username, which ``session_id``, and on which thread.
    """

    @contextlib.contextmanager
    def fake(username=None, password=None, session_id=None, **kwargs):
        calls.append(("open", username, session_id, threading.get_ident()))
        try:
            yield object()
        finally:
            calls.append(("close", threading.get_ident()))

    return fake


class _AlwaysConnected:
    @staticmethod
    def is_user_connected(username):  # noqa: ARG004
        return True


@contextlib.contextmanager
def _authenticated_auth_module():
    """Patch ``require_auth``'s two collaborators so it accepts a session
    carrying ``username`` + ``session_id``. Both are patched at the seams
    the module itself documents; nothing about the ordering under test is
    faked.
    """
    with (
        mock.patch.object(
            auth_module.db_manager,
            "is_user_connected",
            _AlwaysConnected.is_user_connected,
        ),
        mock.patch.object(
            auth_module, "_server_session_valid", lambda request, user: True
        ),
    ):
        yield


def _session_app() -> FastAPI:
    app = FastAPI()
    app.add_middleware(
        SessionMiddleware, secret_key=SECRET, session_cookie="session"
    )
    return app


def _add_login_stub(app: FastAPI, session_id: str = "sid-1") -> None:
    @app.post("/_stub-login")
    def _stub_login(request: Request):
        request.session["username"] = "alice"
        request.session["session_id"] = session_id
        return {"ok": True}


def _route_functions(path: pathlib.Path):
    """Yield ``(func_node, is_route)`` for every ``@router.<verb>`` def."""
    tree = ast.parse(path.read_text(encoding="utf-8"), str(path))
    for node in ast.walk(tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
        for dec in node.decorator_list:
            if (
                isinstance(dec, ast.Call)
                and isinstance(dec.func, ast.Attribute)
                and isinstance(dec.func.value, ast.Name)
                and dec.func.value.id == "router"
            ):
                yield node
                break


def _params_with_defaults(node):
    args = node.args
    positional = list(args.posonlyargs) + list(args.args)
    pad = [None] * (len(positional) - len(args.defaults))
    pairs = list(zip(positional, pad + list(args.defaults)))
    pairs += list(zip(args.kwonlyargs, args.kw_defaults))
    return pairs


def _annotated_metadata(annotation):
    """Yield each metadata expression inside ``Annotated[T, meta, ...]``.

    Handles both the bare-name (``Annotated[...]``) and qualified
    (``typing.Annotated[...]``) spellings. ``ast.Subscript.slice`` is the
    expression directly on the Python versions this project targets (3.9+),
    so a multi-element subscript is an ``ast.Tuple``.
    """
    if not isinstance(annotation, ast.Subscript):
        return
    head = annotation.value
    is_annotated = (isinstance(head, ast.Name) and head.id == "Annotated") or (
        isinstance(head, ast.Attribute) and head.attr == "Annotated"
    )
    if not is_annotated:
        return
    sl = annotation.slice
    elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]
    # elts[0] is the wrapped type; everything after it is metadata.
    yield from elts[1:]


def _declared_body_params(node) -> list[tuple[str, str]]:
    """Body-bound parameters: ``Form()`` / ``File()`` / ``Body()`` defaults
    and ``UploadFile`` annotations. These are the ones FastAPI resolves
    from the request body, i.e. the ones that force a pre-dependency read.

    A parameter may spell its body binding either the legacy way
    (``x: T = Form()``) or via ``Annotated``
    (``x: Annotated[T, Form()]``) -- both must be detected or this scan
    silently blinds itself to every ``Annotated``-spelled route (which is
    exactly what the FAST002 conversion produced for every ``Form``
    parameter in this router directory).
    """
    found = []
    for arg, default in _params_with_defaults(node):
        candidates = [default] if default is not None else []
        candidates += list(_annotated_metadata(arg.annotation))
        for candidate in candidates:
            if (
                isinstance(candidate, ast.Call)
                and isinstance(candidate.func, ast.Name)
                and candidate.func.id in {"Form", "File", "Body"}
            ):
                found.append((arg.arg, candidate.func.id))
        if arg.annotation is not None:
            rendered = ast.unparse(arg.annotation)
            if "UploadFile" in rendered:
                found.append((arg.arg, "UploadFile"))
    return found


def _depends_target(default):
    if (
        isinstance(default, ast.Call)
        and isinstance(default.func, ast.Name)
        and default.func.id == "Depends"
        and default.args
    ):
        target = default.args[0]
        return (
            target.id
            if isinstance(target, ast.Name)
            else getattr(target, "attr", "")
        )
    return None


def _declares_require_auth(node) -> bool:
    for arg, default in _params_with_defaults(node):
        candidates = [default] if default is not None else []
        candidates += list(_annotated_metadata(arg.annotation))
        for candidate in candidates:
            if _depends_target(candidate) == "require_auth":
                return True
    return False


# ---------------------------------------------------------------------------
# 1. The body is read before any dependency, so ordering cannot gate it
# ---------------------------------------------------------------------------


class TestBodyArrivesBeforeAnyDependency:
    """The notes fix works because its gate is a ``Depends``.

    A *declared* body parameter is not a dependency: FastAPI resolves it
    from a body it has already read, before ``solve_dependencies`` runs.
    So for those routes the notes remedy (put auth first) is unavailable
    by construction, and the tests below measure exactly how much work an
    anonymous caller gets out of the process anyway.
    """

    @staticmethod
    def _app(log: list[str]):
        gate = _denying_gate(log)
        app = FastAPI()

        @app.post("/with-form")
        def with_form(
            username: str = Depends(gate),
            payload: str = Form(""),
        ):
            log.append("handler")
            return {"ok": True}

        @app.post("/no-body-field")
        def no_body_field(username: str = Depends(gate)):
            log.append("handler")
            return {"ok": True}

        @app.post("/with-json")
        def with_json(
            username: str = Depends(gate),
            data: dict = Body(...),
        ):
            log.append("handler")
            return {"ok": True}

        return app

    def test_a_declared_form_body_is_fully_read_before_auth_refuses(self):
        log: list[str] = []
        spy = ReceiveSpy(self._app(log))
        client = TestClient(spy)
        raw = b"payload=" + b"x" * 5000

        response = client.post(
            "/with-form",
            content=raw,
            headers={"content-type": "application/x-www-form-urlencoded"},
        )

        assert response.status_code == 401
        # The gate ran and the handler did not — ordering is intact.
        assert log == ["auth"]
        # And yet every byte was pulled through ``receive`` and handed to
        # Starlette's form parser first. That is the side effect the 401
        # cannot undo.
        assert spy.body_bytes == len(raw)

    def test_a_route_without_a_body_field_reads_nothing(self):
        """Negative control for the test above.

        Same client, same method, same bytes on the wire. The only
        difference is the declared ``Form`` parameter — so the 5008 bytes
        measured above are attributable to it and not to the transport,
        the TestClient, or ``Content-Length`` handling.
        """
        log: list[str] = []
        spy = ReceiveSpy(self._app(log))
        client = TestClient(spy)
        raw = b"payload=" + b"x" * 5000

        response = client.post(
            "/no-body-field",
            content=raw,
            headers={"content-type": "application/x-www-form-urlencoded"},
        )

        assert response.status_code == 401
        assert log == ["auth"]
        assert spy.body_bytes == 0

    def test_unparseable_json_422s_without_running_the_auth_dependency(self):
        """The strongest form of the ordering problem.

        A body that will not parse raises ``RequestValidationError`` from
        the body-reading block, i.e. before ``solve_dependencies`` is
        entered. ``require_auth`` never executes. An anonymous caller
        therefore gets a 422 that describes the route's body contract —
        including the byte offset of their syntax error — from a route
        they are not authorised to call.
        """
        log: list[str] = []
        client = TestClient(self._app(log))

        response = client.post(
            "/with-json",
            content=b"{not json",
            headers={"content-type": "application/json"},
        )

        assert response.status_code == 422
        assert log == []
        detail = response.json()["detail"]
        assert detail[0]["type"] == "json_invalid"

    def test_a_parseable_but_wrongly_shaped_body_still_loses_to_auth(self):
        """Positive control: body *validation* does happen after
        dependencies, which is why only the parse failure escapes the
        gate. Without this the test above would read as "422 always wins",
        which is not the contract.
        """
        log: list[str] = []
        client = TestClient(self._app(log))

        response = client.post(
            "/with-json",
            json=[1, 2],
        )

        assert response.status_code == 401
        assert log == ["auth"]
        assert response.json()["detail"] == "Authentication required"

    def test_change_password_is_the_only_authed_route_with_a_body_field(self):
        """Census, and the guard the notes ordering test cannot provide.

        ``tests/web/routers/test_notes_body_gate_ordering.py`` pins that
        the notes ``Depends`` gate stays after ``require_auth``. That
        remedy is unavailable to any route with a *declared* body field,
        so the only durable guard is to keep such routes off the
        authenticated surface.

        Today exactly one authenticated route has one:
        ``POST /auth/change-password``. Its three ``Form`` parameters are
        parsed from an anonymous caller's body before ``require_auth``
        runs, and reordering the signature would not change that. The
        exposure is bounded — urlencoded, under ``BodySizeLimitMiddleware``
        and behind ``CSRFMiddleware`` — but it is the same shape as the
        notes bug, and this list must not grow.

        The three unauthenticated ``/auth`` form routes are listed too, so
        that a new one is noticed rather than silently absorbed.
        """
        rows = {}
        for path in sorted(_ROUTERS_DIR.glob("*.py")):
            for node in _route_functions(path):
                body_params = _declared_body_params(node)
                if body_params:
                    rows[(path.name, node.name)] = (
                        _declares_require_auth(node),
                        tuple(sorted(body_params)),
                    )

        assert set(rows) == {
            ("auth.py", "login"),
            ("auth.py", "validate_password"),
            ("auth.py", "register"),
            ("auth.py", "change_password"),
        }, (
            "a router route grew a declared body field; FastAPI reads the "
            "body before any dependency, so Depends(require_auth) cannot "
            f"gate it. Current census: {rows}"
        )

        authed = {name for name, (is_authed, _) in rows.items() if is_authed}
        assert authed == {("auth.py", "change_password")}
        assert rows[("auth.py", "change_password")][1] == (
            ("confirm_password", "Form"),
            ("current_password", "Form"),
            ("new_password", "Form"),
        )

    def test_no_authenticated_route_declares_an_upload_parameter(self):
        """The severe version of the same problem, currently absent.

        A declared ``UploadFile`` / ``File()`` parameter makes FastAPI run
        Starlette's multipart parser before dependencies, which spools
        parts to disk. That would be an anonymous, pre-auth *disk* write.
        The two real upload routes (``rag``, ``research``) avoid it by
        calling ``await request.form()`` inside the handler, i.e. after
        ``require_auth`` has already resolved.
        """
        offenders = []
        for path in sorted(_ROUTERS_DIR.glob("*.py")):
            for node in _route_functions(path):
                kinds = {kind for _n, kind in _declared_body_params(node)}
                if kinds & {"File", "UploadFile"}:
                    offenders.append((path.name, node.name))

        assert offenders == [], (
            "declared upload parameters are parsed to disk before "
            f"require_auth runs: {offenders}"
        )


# ---------------------------------------------------------------------------
# 2. Rate-limit slots: consumed before or after auth?
# ---------------------------------------------------------------------------


def _probe_limiter(default_limits: list[str] | None = None) -> Limiter:
    """A private in-memory limiter.

    Deliberately not the module-level ``rate_limit.limiter`` singleton:
    these tests read and would otherwise pollute its shared counters. The
    key functions ARE the production ones — the contract under test is
    *when* slowapi hits the store relative to the dependency solver, which
    is a slowapi/FastAPI property, not a value this module re-implements.
    """
    return Limiter(
        key_func=rl_module._get_client_ip,
        strategy="moving-window",
        enabled=True,
        default_limits=default_limits or [],
    )


def _events(limiter: Limiter) -> dict[str, int]:
    """Moving-window hits recorded in the in-memory store, per bucket."""
    return {k: len(v) for k, v in limiter._storage.events.items()}


class TestRateLimitSlotsAndTheAuthGate:
    @staticmethod
    def _app(limiter: Limiter, *, allow: bool, with_middleware: bool):
        app = FastAPI()
        app.state.limiter = limiter
        app.add_exception_handler(
            RateLimitExceeded, _rate_limit_exceeded_handler
        )
        if with_middleware:
            app.add_middleware(SlowAPIMiddleware)
        app.add_middleware(SessionMiddleware, secret_key=SECRET)

        shared = limiter.shared_limit(
            "5 per minute", scope="probe", key_func=rl_module._user_key
        )
        ran: list[int] = []

        def gate(request: Request) -> str:
            if not allow:
                raise HTTPException(
                    status_code=401, detail="Authentication required"
                )
            return "alice"

        @app.post("/_stub-login")
        def _stub_login(request: Request):
            request.session["username"] = "alice"
            return {"ok": True}

        @app.post("/decorated")
        @shared
        def decorated(request: Request, username: str = Depends(gate)):
            ran.append(1)
            return {"ok": True}

        @app.post("/undecorated")
        def undecorated(request: Request, username: str = Depends(gate)):
            ran.append(1)
            return {"ok": True}

        return app, ran

    def test_a_401_consumes_no_slot_on_a_decorated_route(self):
        """``settings_limit`` / ``upload_rate_limit_user`` /
        ``api_rate_limit`` / the notes write limit are all
        ``shared_limit`` decorators, which wrap the *endpoint*. The
        endpoint is only called once every dependency has resolved, so a
        401 from ``require_auth`` short-circuits before slowapi touches
        the store.

        Security-relevant in the good direction: those buckets are keyed
        ``user:<name>`` by ``_user_key``, so if the slot were taken first
        an anonymous attacker who knew a username could exhaust that
        user's settings/upload quota. Asserted on the store, not on the
        status code.
        """
        limiter = _probe_limiter()
        app, ran = self._app(limiter, allow=False, with_middleware=False)
        client = TestClient(app)

        codes = [client.post("/decorated").status_code for _ in range(4)]

        assert codes == [401, 401, 401, 401]
        assert ran == []
        assert _events(limiter) == {}

    def test_the_same_route_does_consume_a_slot_once_auth_passes(self):
        """Positive control for the test above: the limiter is live and
        the bucket is the per-user one, so "no events" there means "not
        reached", not "not configured".
        """
        limiter = _probe_limiter()
        app, ran = self._app(limiter, allow=True, with_middleware=False)
        client = TestClient(app)
        client.post("/_stub-login")

        codes = [client.post("/decorated").status_code for _ in range(3)]

        assert codes == [200, 200, 200]
        assert ran == [1, 1, 1]
        events = _events(limiter)
        assert [k for k in events if "user:alice" in k], events
        assert sum(events.values()) == 3

    def test_the_global_default_limit_is_consumed_before_auth_decides(self):
        """The one slot an anonymous caller does take.

        ``SlowAPIMiddleware`` enforces ``DEFAULT_RATE_LIMIT`` from outside
        the router — outside ``SessionMiddleware``'s consumers and before
        any dependency — so every request that later 401s has already
        counted against the per-IP default bucket. That is intended (a
        default limit that only counted authenticated traffic would be
        useless), but it is a real pre-auth side effect and the asymmetry
        with the decorated case above is worth pinning: the two answers
        come from two different enforcement points.
        """
        limiter = _probe_limiter(default_limits=["50 per minute"])
        app, ran = self._app(limiter, allow=False, with_middleware=True)
        client = TestClient(app)

        codes = [client.post("/undecorated").status_code for _ in range(3)]

        assert codes == [401, 401, 401]
        assert ran == []
        events = _events(limiter)
        assert sum(events.values()) == 3, events
        assert all("user:" not in key for key in events), (
            "the middleware ran before the session was consulted, so the "
            f"bucket must be per-IP, not per-user: {events}"
        )


# ---------------------------------------------------------------------------
# 3. get_db_session_dep: what it opens, when, and for whom
# ---------------------------------------------------------------------------


class TestGetDbSessionDep:
    """The dependency ``auth.py`` says not to wire.

    It is unwired today (pinned elsewhere), but it is the only DB-session
    dependency in the layer and ``get_settings_manager_dep`` already
    composes it, so its behaviour is a live contract. Two things here are
    findings rather than confirmations; both are marked in place.
    """

    @staticmethod
    def _app(*, raises: BaseException | None, is_async: bool):
        app = _session_app()
        _add_login_stub(app)
        seen: list[str] = []

        if is_async:

            @app.get("/r")
            async def route_async(
                request: Request,
                db_session: Any = Depends(auth_module.get_db_session_dep),
            ):
                seen.append("handler")
                if raises is not None:
                    raise raises
                return {"ok": True}
        else:

            @app.get("/r")
            def route_sync(
                request: Request,
                db_session: Any = Depends(auth_module.get_db_session_dep),
            ):
                seen.append("handler")
                if raises is not None:
                    raise raises
                return {"ok": True}

        return app, seen

    def test_an_anonymous_request_never_opens_a_database(self):
        """``require_auth`` is a sub-dependency of ``get_db_session_dep``,
        so it resolves first and its 401 short-circuits the parent. The
        assertion is on the recorded ``get_user_db_session`` calls: no
        connection is opened, no password is resolved, nothing needs
        undoing.
        """
        calls: list[tuple] = []
        app, seen = self._app(raises=None, is_async=False)

        with mock.patch.object(
            auth_module,
            "get_user_db_session",
            _make_recording_db_session(calls),
        ):
            client = TestClient(app)
            response = client.get("/r")

        assert response.status_code == 401
        assert seen == []
        assert calls == []

    def test_the_requests_own_session_id_is_threaded_through(self):
        """Guards the cross-session fallback.

        ``get_user_db_session`` resolves the password from ``session_id``
        when given one and otherwise falls back to
        ``get_any_session_password(username)`` — "whichever of this user's
        live sessions happens to have a password". ``get_db_session_dep``
        passes the request's own ``session_id``, so that fallback is not
        reachable through it. Asserted on the recorded call arguments.
        """
        calls: list[tuple] = []
        app, seen = self._app(raises=None, is_async=False)

        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module,
                "get_user_db_session",
                _make_recording_db_session(calls),
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            response = client.get("/r")

        assert response.status_code == 200
        opens = [c for c in calls if c[0] == "open"]
        assert len(opens) == 1
        assert opens[0][1] == "alice"
        assert opens[0][2] == "sid-1", (
            "session_id must reach get_user_db_session, or the password "
            "resolver falls back to any live session for this user"
        )
        # The open strictly precedes the handler and the close strictly
        # follows it: the yield really does bracket the request.
        assert seen == ["handler"]
        assert [c[0] for c in calls] == ["open", "close"]

    def test_database_session_error_while_entering_forces_reauthentication(
        self,
    ):
        """A setup failure is an expired-login failure, not a route error.

        ``get_user_db_session`` can raise from the context manager's
        ``__enter__`` before ``get_db_session_dep`` reaches its yield.  The
        dependency must still invalidate the browser session and the route
        handler must never run.
        """
        app, seen = self._app(raises=None, is_async=False)
        failing_context = mock.MagicMock()
        failing_context.__enter__.side_effect = DatabaseSessionError(
            "password unavailable"
        )
        get_db_session = mock.Mock(return_value=failing_context)

        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module, "get_user_db_session", get_db_session
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            assert client.cookies.get("session")
            response = client.get("/r")

        assert response.status_code == 401
        assert response.json() == {
            "detail": "Session expired — please log in again"
        }
        assert seen == []
        get_db_session.assert_called_once_with("alice", session_id="sid-1")
        failing_context.__enter__.assert_called_once_with()
        failing_context.__exit__.assert_not_called()

        cleared = [
            value.decode()
            for key, value in response.headers.raw
            if key.lower() == b"set-cookie"
            and value.decode().startswith("session=")
        ]
        assert len(cleared) == 1, response.headers.raw
        assert "expires=Thu, 01 Jan 1970" in cleared[0]
        assert dict(client.cookies) == {}

    def test_none_from_database_context_is_500_without_clearing_session(self):
        """A context that enters but has no session is not an auth expiry.

        The dependency emits its explicit 500 contract before yielding, so
        the handler stays gated.  Because no ``DatabaseSessionError`` was
        raised, the authenticated browser session must remain usable.
        """
        app, seen = self._app(raises=None, is_async=False)
        null_context = mock.MagicMock()
        null_context.__enter__.return_value = None
        get_db_session = mock.Mock(return_value=null_context)

        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module, "get_user_db_session", get_db_session
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            assert client.cookies.get("session")

            response = client.get("/r")

            assert response.status_code == 500
            assert response.json() == {
                "detail": "Failed to get database session"
            }
            assert seen == []
            assert client.cookies.get("session")
            assert not any(
                b"expires=Thu, 01 Jan 1970" in value
                for key, value in response.headers.raw
                if key.lower() == b"set-cookie"
            )

            # A second request with a working database context proves that
            # the first response left the authenticated session usable.
            live_context = mock.MagicMock()
            live_context.__enter__.return_value = object()
            get_db_session.return_value = live_context
            follow_up = client.get("/r")

        assert follow_up.status_code == 200
        assert follow_up.json() == {"ok": True}
        assert seen == ["handler"]
        assert get_db_session.call_args_list == [
            mock.call("alice", session_id="sid-1"),
            mock.call("alice", session_id="sid-1"),
        ]
        null_context.__enter__.assert_called_once_with()
        assert null_context.__exit__.call_count == 1

    def test_a_route_raised_database_error_becomes_a_forced_logout(self):
        """FINDING. The ``try/except`` wraps the ``yield``, not just the
        setup, so FastAPI's teardown ``throw()`` lands inside it.

        A ``DatabaseSessionError`` raised by the *route handler* — a
        failed query, an expired password mid-request, anything from the
        business logic — is therefore caught by the dependency, converted
        into ``401 "Session expired"``, and, critically,
        ``request.session.clear()`` destroys the user's session. The
        client is logged out by an error that had nothing to do with
        their credentials.

        Asserted on the ``Set-Cookie``, not the status: the session cookie
        comes back emptied and expired, and the client's jar is empty
        afterwards.
        """
        app, seen = self._app(
            raises=DatabaseSessionError("query blew up"), is_async=False
        )
        calls: list[tuple] = []

        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module,
                "get_user_db_session",
                _make_recording_db_session(calls),
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            assert client.cookies.get("session")
            response = client.get("/r")

        assert seen == ["handler"], "the route did run; this is its error"
        assert response.status_code == 401
        assert response.json()["detail"].startswith("Session expired")

        cleared = [
            value.decode()
            for key, value in response.headers.raw
            if key.lower() == b"set-cookie"
            and value.decode().startswith("session=")
        ]
        assert len(cleared) == 1, response.headers.raw
        assert "expires=Thu, 01 Jan 1970" in cleared[0]
        assert dict(client.cookies) == {}

    def test_an_unrelated_route_exception_leaves_the_session_alone(self):
        """Negative control for the finding above.

        Same app, same dependency, same teardown path — only the
        exception type differs. A ``ValueError`` propagates as a 500 and
        the session cookie is untouched, which is what makes the
        ``DatabaseSessionError`` behaviour a conversion by this dependency
        rather than something FastAPI does to every failing request.
        """
        app, seen = self._app(raises=ValueError("unrelated"), is_async=False)
        calls: list[tuple] = []

        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module,
                "get_user_db_session",
                _make_recording_db_session(calls),
            ),
        ):
            client = TestClient(app, raise_server_exceptions=False)
            client.post("/_stub-login")
            response = client.get("/r")

        assert seen == ["handler"]
        assert response.status_code == 500
        session_cookies = [
            value
            for key, value in response.headers.raw
            if key.lower() == b"set-cookie"
        ]
        assert session_cookies == []
        assert client.cookies.get("session")

    def test_the_forced_logout_happens_on_async_routes_too(self):
        """``get_db_session_dep`` is a *sync* generator, so on an
        ``async def`` route FastAPI still drives it through
        ``contextmanager_in_threadpool``. The conversion — and the
        ``request.session.clear()`` that goes with it — therefore runs on
        a pooled worker thread while the event loop waits, and still
        reaches the response. Same outcome, different thread.
        """
        app, seen = self._app(
            raises=DatabaseSessionError("query blew up"), is_async=True
        )
        calls: list[tuple] = []

        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module,
                "get_user_db_session",
                _make_recording_db_session(calls),
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            response = client.get("/r")

        assert seen == ["handler"]
        assert response.status_code == 401
        assert response.json()["detail"].startswith("Session expired")
        assert dict(client.cookies) == {}
        # The dependency was driven off the event loop: the recorded
        # thread ids are not the loop's.
        opens = [c for c in calls if c[0] == "open"]
        assert opens and opens[0][3] != threading.get_ident()

    def test_settings_manager_dep_opens_nothing_before_auth_decides(self):
        """``get_settings_manager_dep`` declares ``db_session`` *before*
        ``username``, which reads like the notes ordering bug. It is not:
        ``require_auth`` is a sub-dependency of ``get_db_session_dep``, so
        depth-first resolution still puts it first. Pinned on the call
        log, because the signature alone does not say so.
        """
        app = _session_app()
        _add_login_stub(app)

        @app.get("/settings")
        def settings_route(
            manager: Any = Depends(auth_module.get_settings_manager_dep),
        ):
            return {"ok": True}

        calls: list[tuple] = []
        with mock.patch.object(
            auth_module,
            "get_user_db_session",
            _make_recording_db_session(calls),
        ):
            client = TestClient(app)
            anonymous = client.get("/settings")

        assert anonymous.status_code == 401
        assert calls == []

        made: list[tuple] = []
        with (
            _authenticated_auth_module(),
            mock.patch.object(
                auth_module,
                "get_user_db_session",
                _make_recording_db_session(calls),
            ),
            mock.patch.object(
                auth_module,
                "get_settings_manager",
                lambda db, user: made.append((db, user)) or object(),
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            allowed = client.get("/settings")

        assert allowed.status_code == 200
        assert [c[0] for c in calls if c[0] == "open"] == ["open"]
        assert [user for _db, user in made] == ["alice"]

    def test_render_template_opens_a_db_without_the_request_session_id(self):
        """FINDING (static). The sibling helper does what
        ``get_db_session_dep``'s docstring forbids.

        ``get_db_session_dep`` threads ``session_id`` through precisely to
        avoid ``get_any_session_password``. ``template_helpers.
        render_template`` — reached by every HTML route, including the
        unauthenticated ``GET /auth/login`` and ``GET /auth/register`` —
        calls ``get_user_db_session(username)`` with a bare positional
        username and no ``session_id``, off an unvalidated
        ``request.session["username"]``, to read ``policy.egress_scope``.

        The password resolver then falls back to *any* live session for
        that user. The residual exposure is same-user-cross-session rather
        than cross-user (``DatabaseMiddleware._enforce_session_revocation``
        clears a revoked cookie before the router is reached), but it is a
        database open driven by a session the auth layer never validated,
        and it is exactly the pattern the neighbouring docstring calls a
        leak risk.

        Asserted structurally so the two helpers cannot drift further
        apart: within ``web/dependencies/``, ``render_template`` is the
        only ``get_user_db_session`` call site that omits ``session_id``.
        """
        omissions = []
        for path in sorted(_DEPS_DIR.glob("*.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 = (
                    func.id
                    if isinstance(func, ast.Name)
                    else getattr(func, "attr", "")
                )
                if name != "get_user_db_session":
                    continue
                passes_sid = any(kw.arg == "session_id" for kw in node.keywords)
                if not passes_sid:
                    omissions.append(path.name)

        assert omissions == ["template_helpers.py"], (
            "a dependency-layer call to get_user_db_session dropped "
            "session_id, re-enabling the get_any_session_password "
            f"fallback: {omissions}"
        )


# ---------------------------------------------------------------------------
# 4. Two dependencies, one username, two answers
# ---------------------------------------------------------------------------


class _DeadSessionManager:
    """Every session id is unknown — logout, password change, restart."""

    @staticmethod
    def validate_session(session_id):  # noqa: ARG004
        return None

    @staticmethod
    def session_owner(session_id):  # noqa: ARG004
        return None


@pytest.mark.real_session_check
class TestUsernameReadersDiverge:
    """``Depends`` caches by callable, so "the username" is not one value.

    ``get_session_username`` returns the raw cookie claim.
    ``require_auth`` additionally requires an open database *and* a live
    server-side session. (Marked ``real_session_check`` so
    ``tests/conftest.py``'s autouse ``_legacy_bare_username_auth`` does not
    relax the very gate that produces the divergence.) Both live in ``auth.py``, both take only
    ``Request``, and both are wired to real routes
    (``api_v1.health_check`` uses the former). On a session whose
    server-side record is gone they return different things on the same
    request — and the cache cannot reconcile them, because it is keyed on
    the callable.
    """

    @staticmethod
    def _app(log: list):
        app = _session_app()
        _add_login_stub(app, session_id="destroyed-sid")

        def recording_soft(
            username: str | None = Depends(auth_module.get_session_username),
        ) -> str | None:
            # A thin recorder around the real dependency: it can only
            # append once ``get_session_username`` has already resolved,
            # so an entry here proves that resolution happened.
            log.append(("soft", username))
            return username

        @app.get("/soft")
        def soft(username: str | None = Depends(recording_soft)):
            return {"username": username}

        @app.get("/both")
        def both(
            soft_name: str | None = Depends(recording_soft),
            hard_name: str = Depends(auth_module.require_auth),
        ):
            log.append(("handler", soft_name, hard_name))
            return {"soft": soft_name, "hard": hard_name}

        return app

    def test_the_soft_reader_accepts_what_require_auth_rejects(self):
        log: list = []
        app = self._app(log)

        with (
            mock.patch.object(
                auth_module.db_manager,
                "is_user_connected",
                _AlwaysConnected.is_user_connected,
            ),
            mock.patch.object(
                auth_module, "session_manager", _DeadSessionManager()
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            soft = client.get("/soft")

        assert soft.status_code == 200
        assert soft.json() == {"username": "alice"}
        assert log == [("soft", "alice")]

    def test_the_earlier_reader_still_observes_the_session_after_the_401(
        self,
    ):
        """The divergence is order-visible, which is the notes bug's shape
        applied to dependencies rather than to the body.

        ``get_session_username`` is declared first, so it resolves,
        records "alice", and only then does ``require_auth`` refuse. Its
        observation stands: a dependency placed before the gate has
        already run and anything it did is not rolled back by the 401.
        Here that is only an append to a list; the point is that the
        solver offers no mechanism that would make it anything less.
        """
        log: list = []
        app = self._app(log)

        with (
            mock.patch.object(
                auth_module.db_manager,
                "is_user_connected",
                _AlwaysConnected.is_user_connected,
            ),
            mock.patch.object(
                auth_module, "session_manager", _DeadSessionManager()
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            both = client.get("/both")

        assert both.status_code == 401
        # The soft reader resolved "alice"; the handler never ran.
        assert log == [("soft", "alice")]

    def test_require_auth_really_does_clear_the_cookie_end_to_end(self):
        """``require_auth``'s docstring promises the client is "sent back
        to login instead of 401-ing on every request". That promise
        depends on ``request.session.clear()`` surviving an
        ``HTTPException`` raised from *inside the dependency solver* —
        i.e. on ``SessionMiddleware`` sitting outside the exception
        handling that turns the raise into a response.

        Every existing test of this calls the function with a fake request
        object, which cannot show that. Asserted here through the real
        ASGI stack: the 401 carries an emptied, expired session cookie and
        the next request is anonymous.
        """
        log: list = []
        app = self._app(log)

        with (
            mock.patch.object(
                auth_module.db_manager,
                "is_user_connected",
                _AlwaysConnected.is_user_connected,
            ),
            mock.patch.object(
                auth_module, "session_manager", _DeadSessionManager()
            ),
        ):
            client = TestClient(app)
            client.post("/_stub-login")
            assert client.cookies.get("session")

            response = client.get("/both")
            cleared = [
                value.decode()
                for key, value in response.headers.raw
                if key.lower() == b"set-cookie"
                and value.decode().startswith("session=")
            ]
            assert len(cleared) == 1, response.headers.raw
            assert "expires=Thu, 01 Jan 1970" in cleared[0]
            assert dict(client.cookies) == {}

            follow_up = client.get("/soft")

        assert follow_up.json() == {"username": None}


# ---------------------------------------------------------------------------
# 5. Error paths: what the client sees when auth itself breaks
# ---------------------------------------------------------------------------


class _ExplodingDbManager:
    @staticmethod
    def is_user_connected(username):  # noqa: ARG004
        raise RuntimeError("connection registry unavailable")


class TestErrorPathsInsideTheAuthDependencies:
    def test_a_non_http_exception_from_require_auth_is_a_500_not_a_401(self):
        """``require_auth`` calls out to ``db_manager`` and
        ``session_manager``; neither call is guarded. Anything other than
        an ``HTTPException`` escapes as a 500.

        That matters for the browser branch specifically: the app converts
        a dependency's *401* into a 302 to ``/auth/login``
        (``fastapi_app.handle_http_exception``), keyed on
        ``HTTPException.status_code``. A RuntimeError from inside auth
        therefore cannot take that path — the user gets a server error
        page instead of a login page, and the failure is indistinguishable
        from a backend outage.
        """
        app = _session_app()
        _add_login_stub(app)

        @app.get("/protected")
        def protected(username: str = Depends(auth_module.require_auth)):
            return {"username": username}

        with mock.patch.object(
            auth_module.db_manager,
            "is_user_connected",
            _ExplodingDbManager.is_user_connected,
        ):
            client = TestClient(app, raise_server_exceptions=False)
            client.post("/_stub-login")
            response = client.get("/protected", headers={"accept": "text/html"})

        assert response.status_code == 500

    def test_require_auth_500s_without_session_middleware(self):
        """``require_auth`` reads ``request.session`` unguarded.

        Starlette raises ``AssertionError`` when ``SessionMiddleware`` is
        not installed, so on any mount that lacks it — or from anything
        running outside it — the auth dependency produces a 500 rather
        than a 401. It fails closed, but it fails as an outage.
        """
        app = FastAPI()

        @app.get("/protected")
        def protected(username: str = Depends(auth_module.require_auth)):
            return {"username": username}

        client = TestClient(app, raise_server_exceptions=False)
        response = client.get("/protected")

        assert response.status_code == 500

    def test_the_rate_limit_key_funcs_degrade_in_the_same_scope(self):
        """Contrast, and the reason the asymmetry above is worth pinning.

        ``_user_key`` and ``_api_user_key`` guard the same access with
        ``"session" in request.scope`` and fall back to the client IP,
        because ``SlowAPIMiddleware`` runs outside ``SessionMiddleware``.
        ``require_auth`` has no such guard. Same module family, same
        hazard, two different treatments.
        """
        app = FastAPI()

        @app.get("/keys")
        def keys(request: Request):
            return {
                "user": rl_module._user_key(request),
                "api": rl_module._api_user_key(request),
            }

        client = TestClient(app)
        response = client.get("/keys")

        assert response.status_code == 200
        assert response.json() == {
            "user": "testclient",
            "api": "api_ip:testclient",
        }