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.

46.9 KB
Raw Blame
"""Per-request credential cleanup, peer-trust classification, and the
proxy-trust wiring that decides whether forwarded headers are believed.

ADR-0010 records the historical migration measurement. This file provides
committed evidence for three behavior-level coverage areas.

COVERAGE AREA 1 — ``DatabaseMiddleware`` cleanup call site
--------------------------------------------------
``fastapi_app.py``'s ``DatabaseMiddleware.__call__`` ends with a ``finally``
block that calls ``cleanup_dead_threads()`` then ``cleanup_current_thread()``.
Those two functions are unit-tested (``tests/database/test_thread_local_session*``,
``tests/database/test_thread_metrics.py``). At the review snapshot, no test
asserted that the middleware invokes them; this file now pins the call site.
That matters because the app serves requests from a long-lived pool of
threads: the thread-local SQLAlchemy session and the
plaintext SQLCipher password cached beside it (``ThreadLocalSessionManager.
_thread_credentials`` and ``thread_metrics.metrics_writer``) belong to whoever
made the *previous* request on that thread. If the call site is dropped, the
next user's request inherits them.

VACUITY GUARD. "The leftover is gone" is satisfied by a thread that never had
anything on it. Every cleanup assertion below therefore establishes the state
POSITIVELY first — the inner ASGI app plants a session + credential + metrics
password on the request thread and the test asserts they are really there
mid-request — before asserting they are gone once the middleware returns.

MODEL, AND WHAT IT DOES NOT CLAIM. The requests here run on a single
``ThreadPoolExecutor`` worker that outlives them, which is the pooled-worker
hazard in its simplest honest form: handler and ``finally`` on one thread,
thread reused for the next request. Production is messier — a ``def`` route
handler runs on an AnyIO worker while the middleware's ``finally`` runs on the
event-loop thread, so the request path cannot pop another thread's entry. That
split is documented in ``thread_local_session.clear_credentials_for_user`` and
is the reason logout has its own ``clear_user_credentials`` sweep; these tests
pin the call site, not that split.

COVERAGE AREA 2 — ``is_private_ip`` mapped-IPv6 and multicast
--------------------------------------------------------
``security/network_utils.is_private_ip`` is the base of
``is_private_peer_ip`` (which additionally unwraps IPv4-mapped addresses
and rejects the 6to4/Teredo/NAT64 transition ranges), and that feeds
``web/dependencies/rate_limit._is_trusted_peer``, which decides whether
``X-Forwarded-For`` from a given direct peer is honoured — i.e. whether a
client may choose its own rate-limit bucket and apparent source address. An
IPv6 socket accepting an IPv4 client reports the peer as ``::ffff:a.b.c.d``,
so the mapped form is a real production input, not a curiosity.

The policy asserted here is READ OFF THE IMPLEMENTATION (``ip.is_private or
ip.is_loopback or ip.is_link_local``), not invented: mapped addresses inherit
the classification of the IPv4 address they wrap, and multicast is neither
private nor loopback nor link-local, so it is untrusted. Both are the safe
direction. Cases where the current classification is *wider* than a reader
might expect (RFC 5737 documentation ranges, 6to4) are pinned as CURRENT
BEHAVIOUR and called out in their docstrings rather than "fixed" here.

Not duplicated: ``tests/security/test_network_utils.py`` already covers
loopback, the RFC 1918 blocks, ULA/link-local IPv6, plain public v4/v6,
hostnames and malformed input. Only the mapped/multicast/other-class rows the
audit flagged, plus their consequence at ``_is_trusted_peer`` /
``_get_client_ip``, are added.

COVERAGE AREA 3 — ``TRUST_PROXY_HEADERS`` → uvicorn ``proxy_headers``
------------------------------------------------------------
Flask's ``ProxyFix`` was WSGI middleware *inside* the app object. uvicorn's
``ProxyHeadersMiddleware`` is configured at server start in
``web/app.py::_run_with_uvicorn`` — outside the ASGI object ``TestClient``
wraps — so it is unreachable over HTTP from a test, exactly as the audit says.
These tests drive the WIRING: the env var is read, and translated into the
``uvicorn.run`` kwargs, on and off.

Not duplicated:
* ``tests/security/test_cookie_security.py::...::test_forwarded_proto_alone_
  does_not_add_secure`` pins the app-side half (the app must NOT believe a raw
  ``X-Forwarded-Proto`` unaided).
* ``tests/web/dependencies/test_rate_limit_keys.py::TestTrustProxyHeadersOverride``
  pins the rate-limiter's use of the same flag by monkeypatching the module
  global ``_TRUST_PROXY_HEADERS`` — it never exercises the env var name or the
  accepted-value set. The name/value parsing is covered here for ``web/app.py``
  behaviourally, and cross-checked against ``rate_limit``'s source so the two
  halves of the trust decision cannot drift apart into a split brain.
"""

from __future__ import annotations

import asyncio
import inspect
import re
import threading
from concurrent.futures import ThreadPoolExecutor

import pytest

from local_deep_research.database.thread_local_session import (
    get_current_thread_session,
    thread_session_manager,
)
from local_deep_research.database.thread_metrics import metrics_writer
from local_deep_research.security.network_utils import is_private_ip
from local_deep_research.utilities.request_context import get_current_username
from local_deep_research.web.fastapi_app import DatabaseMiddleware

# Stand-ins for the two things a real request leaves on its thread. Distinct,
# searchable values so an assertion can name exactly whose credential leaked.
ALICE = "alice_row23"
ALICE_PASSWORD = "alice-plaintext-sqlcipher-key"
BOB = "bob_row23"
BOB_PASSWORD = "bob-plaintext-sqlcipher-key"


# ---------------------------------------------------------------------------
# Row 23 — DatabaseMiddleware per-request cleanup call site
# ---------------------------------------------------------------------------


@pytest.fixture(autouse=True)
def _isolate_process_global_credentials():
    """Restore ``_thread_credentials`` around every test in this module.

    The dict is process-global and shared with the rest of the suite. It also
    has to be repaired explicitly rather than left to the middleware, because
    the whole point of some tests here (and of the negative control) is a run
    in which cleanup does NOT happen.
    """
    manager = thread_session_manager
    with manager._lock:
        before = dict(manager._thread_credentials)
    try:
        yield
    finally:
        with manager._lock:
            manager._thread_credentials.clear()
            manager._thread_credentials.update(before)


@pytest.fixture()
def worker():
    """One long-lived worker thread, reused across requests.

    This IS the hazard being tested: the thread survives the request, so
    anything the request leaves in ``threading.local`` storage is visible to
    whoever is served next.
    """
    with ThreadPoolExecutor(
        max_workers=1, thread_name_prefix="ldr-pooled-worker"
    ) as pool:
        yield pool


class _RecordingSession:
    """Stand-in for the thread-local SQLAlchemy ``Session``.

    ``_cleanup_thread_session`` only ever calls ``rollback()`` then
    ``close()`` on it, so recording those is enough to prove the session was
    actually released rather than merely dereferenced.
    """

    def __init__(self, owner: str):
        self.owner = owner
        self.rolled_back = False
        self.closed = False

    def rollback(self) -> None:
        self.rolled_back = True

    def close(self) -> None:
        self.closed = True


def _snapshot_thread_state() -> dict:
    """Everything a request can leave behind on its own thread."""
    thread_id = threading.get_ident()
    with thread_session_manager._lock:
        credentials = dict(thread_session_manager._thread_credentials)
    return {
        "thread_id": thread_id,
        "session": get_current_thread_session(),
        "cached_username": getattr(
            thread_session_manager._local, "username", None
        ),
        "credential_for_this_thread": credentials.get(thread_id),
        "all_credentials": credentials,
        "metrics_passwords": dict(
            getattr(metrics_writer._thread_local, "passwords", None) or {}
        ),
    }


class _CredentialPlantingApp:
    """Inner ASGI app modelling a handler that opened the user's database.

    On each call it records what the thread looked like on ENTRY (the
    cross-request leak check), plants a session + tracked credential +
    metrics password exactly the way the real code paths do, records that
    they are present (the anti-vacuity positive control), and responds.
    """

    def __init__(self, users, raise_after_planting: bool = False):
        self._users = list(users)
        self._raise = raise_after_planting
        self.calls = 0
        self.on_entry: list[dict] = []
        self.mid_request: list[dict] = []
        self.usernames_seen: list[str | None] = []
        self.planted_sessions: list[_RecordingSession] = []

    async def __call__(self, scope, receive, send):
        username, password = self._users[min(self.calls, len(self._users) - 1)]
        self.calls += 1
        self.on_entry.append(_snapshot_thread_state())
        self.usernames_seen.append(get_current_username())

        session = _RecordingSession(username)
        thread_session_manager._local.session = session
        thread_session_manager._local.username = username
        with thread_session_manager._lock:
            thread_session_manager._thread_credentials[
                threading.get_ident()
            ] = (username, password)
        metrics_writer.set_user_password(username, password)
        self.planted_sessions.append(session)

        self.mid_request.append(_snapshot_thread_state())

        if self._raise:
            raise RuntimeError("handler blew up after opening the database")

        await send(
            {"type": "http.response.start", "status": 200, "headers": []}
        )
        await send({"type": "http.response.body", "body": b"ok"})


class _ContextVarProbe:
    """Outer ASGI app: reads the request-user contextvar AFTER the middleware
    has returned, which is the only place a failure to reset it is visible."""

    def __init__(self, app):
        self.app = app
        self.username_after_middleware = "<never ran>"

    async def __call__(self, scope, receive, send):
        try:
            await self.app(scope, receive, send)
        finally:
            self.username_after_middleware = get_current_username()


def _asgi_scope(path: str = "/history/api", session: dict | None = None):
    """A plain authenticated-app HTTP scope.

    ``path`` deliberately avoids ``DatabaseMiddleware._skip_prefixes``. The
    ``session`` key is omitted by default so the middleware does not try to
    open a real SQLCipher database; the one test that needs that branch
    supplies a session and stubs ``ensure_user_database``.
    """
    scope = {
        "type": "http",
        "asgi": {"version": "3.0", "spec_version": "2.3"},
        "http_version": "1.1",
        "method": "GET",
        "scheme": "http",
        "path": path,
        "raw_path": path.encode(),
        "root_path": "",
        "query_string": b"",
        "headers": [],
        "client": ("127.0.0.1", 51234),
        "server": ("testserver", 80),
    }
    if session is not None:
        scope["session"] = session
    return scope


def _drive(app, scope) -> dict:
    """Run one request to completion on the CURRENT thread and report what
    the thread looks like afterwards."""
    messages: list[dict] = []

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

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

    error = None
    try:
        asyncio.run(app(scope, receive, send))
    except BaseException as exc:  # noqa: BLE001 - re-reported to the test
        error = exc
    return {
        "messages": messages,
        "error": error,
        "after": _snapshot_thread_state(),
    }


class TestDatabaseMiddlewareCleanupCallSite:
    """Coverage area 1: ``DatabaseMiddleware.__call__`` cleanup."""

    def test_middleware_invokes_both_cleanup_functions_once_each(
        self, worker, monkeypatch
    ):
        """The call site exists, runs both sweeps, and runs them in order.

        ``cleanup_dead_threads()`` first (drop credentials of threads that
        exited without cleaning up), then ``cleanup_current_thread()`` (drop
        this thread's session, tracked credential, and cached metrics
        passwords). Patched at the definition module because the middleware
        imports them lazily inside the ``finally``.
        """
        from local_deep_research.database import thread_local_session

        calls: list[str] = []
        monkeypatch.setattr(
            thread_local_session,
            "cleanup_dead_threads",
            lambda: calls.append("cleanup_dead_threads"),
        )
        monkeypatch.setattr(
            thread_local_session,
            "cleanup_current_thread",
            lambda: calls.append("cleanup_current_thread"),
        )

        inner = _CredentialPlantingApp([(ALICE, ALICE_PASSWORD)])
        result = worker.submit(
            _drive, DatabaseMiddleware(inner), _asgi_scope()
        ).result(timeout=10)

        assert result["error"] is None
        assert inner.calls == 1, "the inner app never ran"
        assert calls == ["cleanup_dead_threads", "cleanup_current_thread"], (
            "DatabaseMiddleware did not perform the per-request credential "
            f"cleanup; observed calls: {calls}"
        )

    def test_session_and_password_are_present_mid_request_and_gone_after(
        self, worker
    ):
        """Anti-vacuity: prove the leftover EXISTS before proving it is gone.

        Mid-request the thread carries a live session, an entry in the
        process-global credential map holding the plaintext SQLCipher
        password, and the same password cached on ``metrics_writer``. After
        the middleware returns, all three must be gone and the session must
        have been closed — not merely dropped on the floor, which would leave
        its pooled connection checked out.
        """
        inner = _CredentialPlantingApp([(ALICE, ALICE_PASSWORD)])
        result = worker.submit(
            _drive, DatabaseMiddleware(inner), _asgi_scope()
        ).result(timeout=10)

        assert result["error"] is None
        mid = inner.mid_request[0]
        planted = inner.planted_sessions[0]

        # Positive control — the state really was established.
        assert mid["session"] is planted
        assert mid["cached_username"] == ALICE
        assert mid["credential_for_this_thread"] == (ALICE, ALICE_PASSWORD)
        assert mid["metrics_passwords"] == {ALICE: ALICE_PASSWORD}

        after = result["after"]
        assert after["thread_id"] == mid["thread_id"], (
            "the after-snapshot was taken on a different thread than the "
            "request ran on; it would say nothing about the leak"
        )
        assert after["session"] is None, (
            "the thread-local DB session survived the request"
        )
        assert after["credential_for_this_thread"] is None, (
            "the plaintext SQLCipher password survived the request: "
            f"{after['credential_for_this_thread']}"
        )
        assert ALICE_PASSWORD not in str(after["all_credentials"]), (
            "the password is still reachable through the process-global "
            "credential map"
        )
        assert after["metrics_passwords"] == {}, (
            "metrics_writer still caches the plaintext password: "
            f"{after['metrics_passwords']}"
        )
        assert planted.closed, (
            "the session was discarded without close(); its pooled "
            "connection is never returned"
        )

    def test_next_request_on_the_same_worker_sees_none_of_the_previous_user(
        self, worker
    ):
        """The cross-user case the call site exists for.

        Two requests, same pooled thread, different users. Alice's request
        genuinely leaves a session and a plaintext password on the thread
        (asserted, so this cannot pass vacuously); Bob's request must find
        the thread clean on entry.
        """
        inner = _CredentialPlantingApp(
            [(ALICE, ALICE_PASSWORD), (BOB, BOB_PASSWORD)]
        )
        app = DatabaseMiddleware(inner)

        first = worker.submit(_drive, app, _asgi_scope()).result(timeout=10)
        second = worker.submit(_drive, app, _asgi_scope()).result(timeout=10)

        assert first["error"] is None and second["error"] is None
        assert inner.calls == 2

        # Positive control: request 1 really did put Alice's credential on
        # this thread, and request 2 really did run on the same thread.
        assert inner.mid_request[0]["credential_for_this_thread"] == (
            ALICE,
            ALICE_PASSWORD,
        )
        assert inner.mid_request[0]["metrics_passwords"] == {
            ALICE: ALICE_PASSWORD
        }
        assert (
            inner.on_entry[1]["thread_id"] == inner.on_entry[0]["thread_id"]
        ), "the two requests did not share a worker thread"

        entry = inner.on_entry[1]
        assert entry["session"] is None, (
            "Bob's request started with Alice's DB session already on the "
            "thread"
        )
        assert entry["cached_username"] is None
        assert entry["credential_for_this_thread"] is None, (
            "Bob's request started holding Alice's cached credential: "
            f"{entry['credential_for_this_thread']}"
        )
        assert ALICE not in entry["metrics_passwords"], (
            "Alice's plaintext SQLCipher password was still cached on the "
            "thread when Bob's request began"
        )
        assert ALICE_PASSWORD not in str(entry["all_credentials"])

    def test_cleanup_still_runs_when_the_handler_raises(self, worker):
        """It is a ``finally``: a 500-producing handler must not be able to
        strand its user's credential on the pooled thread."""
        inner = _CredentialPlantingApp(
            [(ALICE, ALICE_PASSWORD)], raise_after_planting=True
        )
        result = worker.submit(
            _drive, DatabaseMiddleware(inner), _asgi_scope()
        ).result(timeout=10)

        assert isinstance(result["error"], RuntimeError), (
            "the handler exception was swallowed by the middleware"
        )
        assert inner.mid_request[0]["credential_for_this_thread"] == (
            ALICE,
            ALICE_PASSWORD,
        )
        after = result["after"]
        assert after["session"] is None
        assert after["credential_for_this_thread"] is None, (
            "a failed request left the plaintext password on the thread"
        )
        assert after["metrics_passwords"] == {}

    def test_request_sweeps_credentials_left_by_threads_that_have_exited(
        self, worker
    ):
        """Pins ``cleanup_dead_threads()`` specifically.

        ``cleanup_current_thread()`` only ever pops the *current* thread's id,
        so an entry keyed to a thread that has already exited can be removed
        by nothing else. Those are the entries of workers that died without
        running their cleanup handler — each one a plaintext SQLCipher
        password with no owner left to drop it.

        The pool is warmed up BEFORE the ghost thread is started, on purpose:
        thread idents are recycled by the OS, and if the ghost's id were
        handed to the request-serving worker the entry would be the worker's
        own live credential and ``cleanup_current_thread()`` would remove it —
        silently turning this into a duplicate of the tests above. Asserted
        below rather than assumed.
        """
        worker_thread_id = worker.submit(threading.get_ident).result(timeout=10)
        dead_thread_id = None

        def _die_holding_a_credential():
            nonlocal dead_thread_id
            dead_thread_id = threading.get_ident()
            with thread_session_manager._lock:
                thread_session_manager._thread_credentials[dead_thread_id] = (
                    "ghost_user",
                    "ghost-plaintext-key",
                )

        ghost = threading.Thread(target=_die_holding_a_credential)
        ghost.start()
        ghost.join()

        # Positive control: the orphaned credential is really there, and its
        # thread is really gone.
        with thread_session_manager._lock:
            assert thread_session_manager._thread_credentials.get(
                dead_thread_id
            ) == ("ghost_user", "ghost-plaintext-key")
        assert dead_thread_id not in {t.ident for t in threading.enumerate()}
        assert dead_thread_id != worker_thread_id, (
            "the ghost thread's id was recycled onto the pool worker; this "
            "test would no longer isolate cleanup_dead_threads()"
        )

        inner = _CredentialPlantingApp([(BOB, BOB_PASSWORD)])
        result = worker.submit(
            _drive, DatabaseMiddleware(inner), _asgi_scope()
        ).result(timeout=10)

        assert result["error"] is None
        assert result["after"]["thread_id"] == worker_thread_id
        assert dead_thread_id not in result["after"]["all_credentials"], (
            "a dead thread's cached plaintext password survived the request; "
            "cleanup_dead_threads() is not being called from the middleware"
        )

    def test_cleanup_failure_cannot_break_the_response(
        self, worker, monkeypatch
    ):
        """The ``except Exception`` around the cleanup block.

        A cleanup error must be logged and swallowed, not turned into a
        failed response — otherwise a transient DB error during teardown
        becomes a user-visible outage.
        """
        from local_deep_research.database import thread_local_session

        def _boom():
            raise RuntimeError("cleanup exploded")

        monkeypatch.setattr(thread_local_session, "cleanup_dead_threads", _boom)

        inner = _CredentialPlantingApp([(ALICE, ALICE_PASSWORD)])
        result = worker.submit(
            _drive, DatabaseMiddleware(inner), _asgi_scope()
        ).result(timeout=10)

        assert result["error"] is None, (
            f"a cleanup failure escaped the middleware: {result['error']!r}"
        )
        starts = [
            m for m in result["messages"] if m["type"] == "http.response.start"
        ]
        assert starts and starts[0]["status"] == 200

    def test_authenticated_path_cleans_up_and_releases_the_user_contextvar(
        self, worker, monkeypatch
    ):
        """The branch that actually opens a database.

        With a session in scope the middleware opens the user DB and publishes
        the username to a contextvar. Both the credential sweep and the
        contextvar reset must happen on the way out; a surviving
        ``request_user`` would make service-layer code attribute the next
        caller's work to the previous user.
        """
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )
        from local_deep_research.web.dependencies import auth as auth_dep

        opened: list[str] = []
        monkeypatch.setattr(
            auth_dep,
            "ensure_user_database",
            lambda request: opened.append(request.session.get("username")),
        )

        # A real server-side session record: the middleware's revocation
        # check clears an unrecognised session_id before the DB branch, so a
        # made-up one would silently take the anonymous path and make the
        # assertions below vacuous.
        # Swap in a copy of the registry first so monkeypatch's teardown
        # removes this session from the process-global manager.
        monkeypatch.setattr(
            session_manager, "sessions", dict(session_manager.sessions)
        )
        session_id = session_manager.create_session(ALICE)

        inner = _CredentialPlantingApp([(ALICE, ALICE_PASSWORD)])
        probe = _ContextVarProbe(DatabaseMiddleware(inner))
        scope = _asgi_scope(
            session={"username": ALICE, "session_id": session_id}
        )
        result = worker.submit(_drive, probe, scope).result(timeout=10)

        assert result["error"] is None
        assert opened == [ALICE], (
            "the authenticated branch of the middleware did not run"
        )
        # Positive control on the contextvar: it WAS set during the request.
        assert inner.usernames_seen == [ALICE]
        assert probe.username_after_middleware is None, (
            "the request-user contextvar outlived the request: "
            f"{probe.username_after_middleware!r}"
        )
        assert inner.mid_request[0]["credential_for_this_thread"] == (
            ALICE,
            ALICE_PASSWORD,
        )
        after = result["after"]
        assert after["session"] is None
        assert after["credential_for_this_thread"] is None
        assert after["metrics_passwords"] == {}


# ---------------------------------------------------------------------------
# Row 24 — is_private_ip classification edges that gate proxy-header trust
# ---------------------------------------------------------------------------


class TestIsPrivateIpMappedIPv4:
    """IPv4-mapped IPv6 (``::ffff:a.b.c.d``).

    A dual-stack listener accepting an IPv4 client reports the peer in this
    form, so ``_is_trusted_peer`` sees it routinely. The classification must
    follow the wrapped IPv4 address in BOTH directions: private stays trusted
    (or a legitimate reverse proxy silently stops being believed), and public
    stays untrusted (or wrapping is a one-line spoof bypass).
    """

    @pytest.mark.parametrize(
        "mapped",
        [
            "::ffff:10.0.0.1",
            "::ffff:172.16.0.1",
            "::ffff:192.168.1.1",
            "::ffff:127.0.0.1",
            "::ffff:169.254.1.1",
        ],
    )
    def test_mapped_private_ipv4_is_private(self, mapped):
        assert is_private_ip(mapped) is True

    @pytest.mark.parametrize(
        "mapped",
        [
            "::ffff:8.8.8.8",
            "::ffff:1.1.1.1",
            "::ffff:93.184.216.34",
        ],
    )
    def test_mapped_public_ipv4_is_not_private(self, mapped):
        """The bypass that must not exist: wrapping a public address in the
        IPv4-mapped prefix must not buy it private (=trusted) status."""
        assert is_private_ip(mapped) is False

    def test_bracketed_mapped_forms_agree_with_unbracketed(self):
        """The ``[...]`` strip runs before parsing, so a URL-authority-shaped
        peer classifies identically."""
        assert is_private_ip("[::ffff:10.0.0.1]") is True
        assert is_private_ip("[::ffff:8.8.8.8]") is False

    def test_classification_is_by_address_not_by_text_prefix(self):
        """Same addresses, alternative spellings.

        ``::ffff:0a00:0001`` is 10.0.0.1 and ``::ffff:0808:0808`` is 8.8.8.8
        written in hextets, and the mapped prefix is case-insensitive. A guard
        implemented as a string prefix test rather than a parse would get these
        wrong in whichever direction it was written.
        """
        assert is_private_ip("::FFFF:10.0.0.1") is True
        assert is_private_ip("::ffff:0a00:0001") is True
        assert is_private_ip("::ffff:0808:0808") is False

    def test_deprecated_ipv4_compatible_form_is_not_private(self):
        """CURRENT BEHAVIOUR. ``::10.0.0.1`` is the deprecated RFC 4291
        IPv4-*compatible* form — a different prefix from ``::ffff:``, and
        Python does not map it back to 10.0.0.1. It classifies as public, so
        it is NOT a trusted peer. Recorded because the two forms look alike
        and only one of them inherits the wrapped address's status."""
        assert is_private_ip("::10.0.0.1") is False
        assert is_private_ip("::8.8.8.8") is False

    def test_nat64_wrapped_addresses_are_not_private(self):
        """``64:ff9b::/96`` NAT64 wrapping does not confer private status
        either. ``security/egress/policy.py`` relies on this (plus its own
        ``_is_nat64_wrapped_metadata`` check) so a NAT64-wrapped cloud
        metadata address cannot pose as a local host."""
        assert is_private_ip("64:ff9b::8.8.8.8") is False
        assert is_private_ip("64:ff9b::169.254.169.254") is False


class TestIsPrivateIpMulticast:
    """Multicast is not private, not loopback and not link-local, so it is
    untrusted — which is right for a peer address: a multicast group is never
    a legitimate TCP source, so a peer claiming one is malformed input."""

    @pytest.mark.parametrize(
        "address",
        [
            "224.0.0.1",  # all-hosts
            "224.0.0.251",  # mDNS
            "239.255.255.250",  # SSDP
            "232.0.0.1",  # source-specific
        ],
    )
    def test_ipv4_multicast_is_not_private(self, address):
        assert is_private_ip(address) is False

    @pytest.mark.parametrize(
        "address",
        [
            "ff02::1",  # all-nodes, link-local scope
            "ff02::fb",  # mDNS
            "ff05::1",  # all-nodes, site-local scope
        ],
    )
    def test_ipv6_multicast_is_not_private(self, address):
        """Note ``ff02::`` is *link-LOCAL SCOPE* multicast, which reads like
        it should hit the ``is_link_local`` clause — it does not.
        ``is_link_local`` is ``fe80::/10`` only."""
        assert is_private_ip(address) is False

    def test_bracketed_ipv6_multicast_is_not_private(self):
        assert is_private_ip("[ff02::1]") is False

    def test_mapped_ipv4_multicast_is_not_private(self):
        assert is_private_ip("::ffff:224.0.0.1") is False


class TestIsPrivateIpOtherClasses:
    """CURRENT BEHAVIOUR for the remaining classes the implementation reaches
    through ``ipaddress``. None of these are asserted as *desirable*; they are
    pinned so a change to the classification rule is visible in the diff."""

    @pytest.mark.parametrize(
        "address",
        ["192.0.2.1", "198.51.100.1", "203.0.113.1", "2001:db8::1"],
    )
    def test_documentation_ranges_count_as_private(self, address):
        """WIDER THAN THE DOCSTRING SAYS. Python's ``ipaddress`` marks the
        RFC 5737 / RFC 3849 documentation ranges non-globally-reachable, so
        ``is_private_ip`` returns True and a peer in one of them would be
        trusted to set ``X-Forwarded-For``. Harmless in practice (nobody
        routes them) but it is a real widening of the trusted set, and
        ``tests/web/dependencies/test_rate_limit_keys.py`` already documents
        having to avoid them when picking an "attacker" address."""
        assert is_private_ip(address) is True

    @pytest.mark.parametrize(
        "address", ["198.18.0.1", "240.0.0.1", "255.255.255.255"]
    )
    def test_benchmark_reserved_and_broadcast_count_as_private(self, address):
        """Same widening: RFC 2544 benchmarking, the 240/4 reserved block and
        the limited-broadcast address all classify private."""
        assert is_private_ip(address) is True

    def test_6to4_wrapping_a_private_address_counts_as_private(self):
        """CURRENT BEHAVIOUR: this helper follows the running interpreter.
        On a CPython build whose table lists 2002::/16 as
        non-globally-reachable, every 6to4 address is private regardless
        of what it wraps; older builds that lack that entry report this
        address as not private (the test name describes the former). The
        proxy-trust decision does not inherit either answer:
        ``_is_trusted_peer`` goes through ``is_private_peer_ip``, which
        rejects 6to4 peers (``tests/web/dependencies/test_rate_limit_keys.py``)."""
        import ipaddress

        expected = ipaddress.ip_address("2002:0a00:0001::1").is_private
        assert is_private_ip("2002:0a00:0001::1") is expected

    @pytest.mark.parametrize("address", ["100.64.0.1", "100.127.255.255"])
    def test_carrier_grade_nat_is_not_private(self, address):
        """CURRENT BEHAVIOUR, and the safe direction: RFC 6598 shared address
        space is NOT trusted, so a peer arriving through an ISP-grade NAT
        cannot set its own forwarded address."""
        assert is_private_ip(address) is False

    def test_dot_local_suffix_match_is_case_sensitive(self):
        """CURRENT BEHAVIOUR — an asymmetry, pinned not endorsed.

        The mDNS fallback is ``hostname.endswith(".local")`` with no case
        folding, so ``printer.local`` is private and ``printer.LOCAL`` is not.
        DNS names are case-insensitive, so these are the same host. Irrelevant
        to ``_is_trusted_peer`` (peers are IPs), but ``is_private_ip`` is also
        used by ``security/egress/policy.py`` and ``utilities/url_utils.py``,
        where the classification decides local-vs-public for an attacker-
        influenced URL host.
        """
        assert is_private_ip("printer.local") is True
        assert is_private_ip("printer.LOCAL") is False
        assert is_private_ip("Printer.Local") is False


class TestTrustedPeerConsequences:
    """The reason row 24 is a security row: what these classifications do.

    ``_is_trusted_peer`` -> ``_get_client_ip`` decides whether the peer may
    name its own address, which is the slowapi rate-limit key for
    ``/auth/login`` and ``/auth/register``. A peer that can rotate that value
    gets an unlimited supply of fresh brute-force budgets.
    """

    @pytest.fixture()
    def rl(self):
        from local_deep_research.web.dependencies import rate_limit

        return rate_limit

    @staticmethod
    def _request(peer: str, headers: dict | None = None):
        from starlette.requests import Request

        return Request(
            {
                "type": "http",
                "method": "GET",
                "path": "/auth/login",
                "query_string": b"",
                "headers": [
                    (k.lower().encode(), v.encode())
                    for k, v in (headers or {}).items()
                ],
                "client": (peer, 51234),
            }
        )

    @pytest.mark.parametrize(
        ("peer", "trusted"),
        [
            ("::ffff:10.0.0.1", True),
            ("::ffff:192.168.1.1", True),
            ("::ffff:8.8.8.8", False),
            ("::ffff:1.1.1.1", False),
            ("224.0.0.1", False),
            ("ff02::1", False),
        ],
    )
    def test_mapped_and_multicast_peers_reach_the_right_trust_decision(
        self, rl, peer, trusted
    ):
        assert rl._is_trusted_peer(peer) is trusted

    def test_mapped_public_peer_cannot_choose_its_rate_limit_bucket(
        self, rl, monkeypatch
    ):
        """The spoof attempt, end to end through ``_get_client_ip``.

        ``TRUST_PROXY_HEADERS`` is forced off so this measures the peer
        classification and nothing else.
        """
        monkeypatch.setattr(rl, "_TRUST_PROXY_HEADERS", False)
        request = self._request(
            "::ffff:8.8.8.8", {"X-Forwarded-For": "10.0.0.99"}
        )
        assert rl._get_client_ip(request) == "::ffff:8.8.8.8", (
            "a public IPv4 client wrapped in the IPv4-mapped IPv6 prefix was "
            "allowed to pick its own rate-limit bucket"
        )

    def test_multicast_peer_cannot_choose_its_rate_limit_bucket(
        self, rl, monkeypatch
    ):
        monkeypatch.setattr(rl, "_TRUST_PROXY_HEADERS", False)
        request = self._request("224.0.0.1", {"X-Forwarded-For": "10.0.0.99"})
        assert rl._get_client_ip(request) == "224.0.0.1"

    def test_mapped_private_peer_is_still_believed(self, rl, monkeypatch):
        """Positive control. Without this the two tests above would also pass
        against an ``is_private_ip`` that returned False for everything."""
        monkeypatch.setattr(rl, "_TRUST_PROXY_HEADERS", False)
        request = self._request(
            "::ffff:10.0.0.1", {"X-Forwarded-For": "203.0.113.9"}
        )
        assert rl._get_client_ip(request) == "203.0.113.9"


# ---------------------------------------------------------------------------
# Row 25 — TRUST_PROXY_HEADERS -> uvicorn proxy_headers wiring
# ---------------------------------------------------------------------------

_TRUST_ENV = "TRUST_PROXY_HEADERS"

# Whitespace-insensitive grab of the accepted-value tuple in either module, so
# the cross-module comparison below is not a formatting test.
_TRUST_EXPR_RE = re.compile(
    r'os\.environ\.get\(\s*"TRUST_PROXY_HEADERS"\s*,\s*""\s*,?\s*\)'
    r"\s*\.lower\(\)\s*in\s*\(([^)]*)\)",
    re.S,
)


def _accepted_truthy_values(source: str) -> set[str]:
    match = _TRUST_EXPR_RE.search(source)
    assert match, (
        "could not find the TRUST_PROXY_HEADERS env read in this module; "
        "the trust flag was renamed or restructured"
    )
    return set(re.findall(r'"([^"]*)"', match.group(1)))


@pytest.fixture()
def uvicorn_run_kwargs(monkeypatch):
    """Launch ``_run_with_uvicorn`` with a given env and capture the kwargs.

    ``web/app.py`` does ``import uvicorn`` inside the function, so patching
    the attribute on the already-imported module is what the call resolves.

    The two proxy-trust variables are cleared first: ``web/app.py`` now
    derives ``forwarded_allow_ips`` from ``LDR_SERVER_FORWARDED_ALLOW_IPS``
    rather than hard-coding ``"*"``, so a value exported ambiently by CI or
    a dev shell would silently change what every assertion below observes.
    Each test that cares sets its own value.
    """
    import uvicorn

    for name in (
        "LDR_SERVER_FORWARDED_ALLOW_IPS",
        "LDR_SERVER_TRUSTED_PROXY_COUNT",
    ):
        monkeypatch.delenv(name, raising=False)

    calls: list[tuple[tuple, dict]] = []
    monkeypatch.setattr(uvicorn, "run", lambda *a, **kw: calls.append((a, kw)))

    def _launch(env_value, host="127.0.0.1", port=5000, debug=False):
        from local_deep_research.web.app import _run_with_uvicorn

        if env_value is None:
            monkeypatch.delenv(_TRUST_ENV, raising=False)
        else:
            monkeypatch.setenv(_TRUST_ENV, env_value)
        calls.clear()
        _run_with_uvicorn(host, port, debug)
        assert len(calls) == 1, (
            f"_run_with_uvicorn made {len(calls)} uvicorn.run call(s)"
        )
        return calls[0]

    return _launch


class TestTrustProxyHeadersUvicornWiring:
    """Coverage area 3: the replacement for Flask's in-app ``ProxyFix``.

    Deliberately not driven over HTTP: uvicorn's ``ProxyHeadersMiddleware`` is
    installed by the SERVER around the ASGI app, so ``TestClient(app)`` can
    never exercise it. The testable contract is that the operator's opt-in
    reaches ``uvicorn.run``.
    """

    def test_unset_means_forwarded_headers_are_not_trusted(
        self, uvicorn_run_kwargs
    ):
        """Default deny. With this on by default any internet-facing
        deployment would let a client rewrite its own source address and
        scheme via ``X-Forwarded-*``."""
        _, kwargs = uvicorn_run_kwargs(None)
        assert kwargs["proxy_headers"] is False
        assert kwargs["forwarded_allow_ips"] is None

    @pytest.mark.parametrize(
        "value", ["true", "True", "TRUE", "1", "yes", "YES", "Yes"]
    )
    def test_opt_in_values_enable_proxy_headers(
        self, uvicorn_run_kwargs, value
    ):
        _, kwargs = uvicorn_run_kwargs(value)
        assert kwargs["proxy_headers"] is True, (
            f"TRUST_PROXY_HEADERS={value!r} did not reach uvicorn"
        )
        # The backward-compatible DEFAULT, not a coupling: with
        # LDR_SERVER_FORWARDED_ALLOW_IPS unset (the fixture clears it) the
        # opt-in still launches uvicorn with its own "*" default, exactly
        # as it did before that variable existed.
        assert kwargs["forwarded_allow_ips"] == "*"

    def test_restricted_forwarded_allow_ips_reaches_uvicorn(
        self, monkeypatch, uvicorn_run_kwargs
    ):
        """The two kwargs are deliberately INDEPENDENT.

        ``proxy_headers`` is the operator's on/off switch; the allow-list
        is a separate axis that narrows which direct peers uvicorn honours
        forwarded headers from. Pinned together here so the pairing cannot
        silently regress to the old "``proxy_headers`` implies ``*``"
        equivalence, which is exactly the spoofable configuration the
        rate limiter's startup guard now refuses.
        """
        configured_allow_ips = "10.0.0.5,2001:db8::/64"
        monkeypatch.setenv(
            "LDR_SERVER_FORWARDED_ALLOW_IPS", configured_allow_ips
        )

        _, kwargs = uvicorn_run_kwargs("true")

        assert kwargs["proxy_headers"] is True
        assert kwargs["forwarded_allow_ips"] == configured_allow_ips
        assert kwargs["forwarded_allow_ips"] != "*"

    @pytest.mark.parametrize(
        "value",
        ["", "false", "False", "0", "no", "off", "maybe", " true ", "true "],
    )
    def test_everything_else_fails_closed(self, uvicorn_run_kwargs, value):
        """Only the three documented spellings count. Note ``" true "`` is
        rejected — the value is not stripped — which is CURRENT BEHAVIOUR and
        the safe direction (a typo disables trust rather than enabling it)."""
        _, kwargs = uvicorn_run_kwargs(value)
        assert kwargs["proxy_headers"] is False, (
            f"TRUST_PROXY_HEADERS={value!r} was treated as an opt-in"
        )
        assert kwargs["forwarded_allow_ips"] is None

    @pytest.mark.parametrize(
        "value", [None, "", "true", "1", "yes", "false", "0", "nonsense"]
    )
    def test_forwarded_allow_ips_never_widens_without_proxy_headers(
        self, uvicorn_run_kwargs, value
    ):
        """An allow-list is only ever passed together with the opt-in.

        The two kwargs are no longer one decision -- ``forwarded_allow_ips``
        is now operator-configurable and can be narrower than ``"*"`` while
        ``proxy_headers`` is on (see
        ``test_restricted_forwarded_allow_ips_reaches_uvicorn``). What must
        still hold in BOTH directions is the gating: ``forwarded_allow_ips``
        is ``None`` -- uvicorn's middleware is not installed at all --
        exactly when ``proxy_headers`` is False, so no allow-list can widen
        anything without the explicit opt-in, and the opt-in never arrives
        without one. With ``LDR_SERVER_FORWARDED_ALLOW_IPS`` unset (the
        fixture clears it), the value passed on the opt-in side is uvicorn's
        own backward-compatible ``"*"``.
        """
        _, kwargs = uvicorn_run_kwargs(value)
        assert (kwargs["forwarded_allow_ips"] is None) is (
            kwargs["proxy_headers"] is False
        )
        if kwargs["proxy_headers"]:
            assert kwargs["forwarded_allow_ips"] == "*"

    def test_ldr_prefixed_variable_does_not_enable_proxy_trust(
        self, monkeypatch, uvicorn_run_kwargs
    ):
        """The name is unprefixed on purpose (it is read before
        ``SettingsManager`` exists) and both readers must agree on it. A
        rename to the project's usual ``LDR_`` prefix in one place only would
        leave uvicorn rewriting the client address while the rate limiter
        still refused to believe forwarded headers, or vice versa.
        """
        monkeypatch.setenv("LDR_TRUST_PROXY_HEADERS", "true")
        _, kwargs = uvicorn_run_kwargs(None)
        assert kwargs["proxy_headers"] is False
        assert kwargs["forwarded_allow_ips"] is None

    def test_app_and_rate_limiter_gate_on_the_same_name_and_values(self):
        """Cross-check of the two independent readers of the flag.

        Scope note: this is a source-level comparison, because
        ``rate_limit``'s half is a module-level constant evaluated at import
        and cannot be re-derived without reloading the module (which would
        rebuild the shared limiter). It proves the variable name and the
        accepted-value set match; the runtime effect of each half is covered
        behaviourally above and in ``test_rate_limit_keys.py``.
        """
        from local_deep_research.web import app as web_app
        from local_deep_research.web.dependencies import rate_limit

        app_source = inspect.getsource(web_app._run_with_uvicorn)
        rl_source = inspect.getsource(rate_limit)

        assert _accepted_truthy_values(app_source) == _accepted_truthy_values(
            rl_source
        ), (
            "web/app.py and rate_limit.py accept different values for "
            "TRUST_PROXY_HEADERS — the server would trust forwarded headers "
            "that the rate limiter refuses, or vice versa"
        )
        assert 'os.environ.get("LDR_TRUST_PROXY_HEADERS"' not in app_source
        assert 'os.environ.get("LDR_TRUST_PROXY_HEADERS"' not in rl_source

    @pytest.mark.parametrize(
        "raw",
        ["*,", ",", " 10.0.0.5 , ", "", "*", "10.0.0.5,,10.0.0.6", "   "],
    )
    def test_app_and_rate_limit_normalise_identically(self, raw):
        """Both halves must hand uvicorn, and describe, the same string.

        ``web/app.py`` sets ``--forwarded-allow-ips``; ``rate_limit.py``
        classifies the same variable and quotes its own resolved value in
        the RuntimeError, the startup warning and the info line. When the
        two normalised differently, those messages described an allow-list
        uvicorn was never given: ``","`` reached uvicorn verbatim (one
        literal entry matching no peer, so every client shared a bucket)
        while the rate limiter read it as unset.

        Duplicated rather than shared because ``web/app.py`` must not
        import ``rate_limit`` before uvicorn starts -- that would run its
        import-time startup guard and freeze its allow-list early. This
        test is what keeps the twins in step.
        """
        from local_deep_research.web import app as web_app
        from local_deep_research.web.dependencies import rate_limit

        assert web_app._normalise_forwarded_allow_ips(
            raw
        ) == rate_limit._normalise_forwarded_allow_ips(raw)

    def test_normalised_allow_list_is_what_reaches_uvicorn(
        self, monkeypatch, uvicorn_run_kwargs
    ):
        """Execution-verified end of the same contract."""
        monkeypatch.setenv("LDR_SERVER_FORWARDED_ALLOW_IPS", " 10.0.0.5 , ")
        _, kwargs = uvicorn_run_kwargs("true")
        assert kwargs["forwarded_allow_ips"] == "10.0.0.5"

        monkeypatch.setenv("LDR_SERVER_FORWARDED_ALLOW_IPS", ",")
        _, kwargs = uvicorn_run_kwargs("true")
        assert kwargs["forwarded_allow_ips"] == "*", (
            "a comma-only value used to reach uvicorn verbatim as a single "
            "literal entry matching no peer"
        )

    def test_other_security_relevant_server_kwargs_are_forwarded(
        self, uvicorn_run_kwargs
    ):
        """The rest of the server-start contract that has no in-app analogue.

        ``server_header=False`` restores the suppression Flask/werkzeug gave
        for free (uvicorn advertises itself by default), and the app import
        string is what guarantees the server runs the middleware-wrapped app
        rather than some bare object.
        """
        args, kwargs = uvicorn_run_kwargs(None, host="0.0.0.0", port=5123)
        assert args == ("local_deep_research.web.fastapi_app:app",)
        assert kwargs["host"] == "0.0.0.0"
        assert kwargs["port"] == 5123
        assert kwargs["server_header"] is False
        assert kwargs["access_log"] is False
        assert kwargs["workers"] == 1