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.

39.2 KB
Raw Blame
"""Authentication + session lifecycle under Starlette's signed-cookie session.

MOTIVATING BUG — logout on one device logged you out everywhere
----------------------------------------------------------------
``POST /auth/logout`` destroys exactly one server-side session
(``session_manager.destroy_session(session_id)``) but then reaches for two
USER-scoped teardowns: ``session_password_store.clear_all_for_user(username)``
and ``db_manager.close_user_database(username)``. A user logged in on a phone
and a laptop who logs out of one has the other's SQLCipher credential wiped
and the shared connection closed underneath it, so every DB-touching route on
the surviving session starts failing — and while a research run was in flight
those failures were 500s, not 401s. That defect is the reason this module
exists — and it is **still live on this branch**: ``routers/auth.py`` calls
``clear_all_for_user`` deliberately (the comment there argues it is needed
because ``get_any_session_password`` would otherwise let an orphaned
credential resurrect a logged-out cookie), so the multi-device cost was
traded away rather than fixed. Three of the four tests in
``TestLogoutIsScopedToTheSessionThatRequestedIt`` therefore carry
``xfail(strict=True)``: they state the CORRECT contract, they are red for
exactly the reason described, and the day someone fixes it strict-xfail
turns the XPASS into a failure that forces the marker off. The fourth
(``destroy_session`` is per-session, not per-user) passes today and is a
plain regression fence.

WHY THE REST OF THIS MODULE
---------------------------
Flask's server-side session was replaced by Starlette's ``SessionMiddleware``:
a **signed, unencrypted, client-side cookie**. The server cannot revoke,
shorten or invalidate a cookie it has already handed out — every such property
now has to be re-established in application code, and each of those is a place
the migration could have silently lost a guarantee. This module pins the ones
whose absence is not observable from the cookie's own attributes:

* **Logout scope** (the bug above) — one session out must leave the user's
  other sessions fully usable, server-side session record, credential and DB
  connection included.
* **Session fixation, behaviourally** — ``tests/web/routers/test_auth_flow_gaps.py``
  already pins that the pre-login ``_csrf_token`` VALUE does not survive
  ``request.session.clear()`` at login. What nothing pinned is the property
  that actually matters to an attacker who planted that token: presenting it
  after login must be **rejected**, not merely different.
* **Signature integrity** — a truncated / bit-flipped / forged session cookie
  must be treated as anonymous, never as a trusted claim. A forged payload is
  the interesting case: the session id inside it can be a REAL, live one.
* **The second server-side deadline.** ``tests/web/test_migration_regression_fixes.py``
  covers ``_enforce_session_expiry`` (the ``_session_expires_at`` stamp,
  driven by the ``fastapi_app._now_ts`` seam). It is not the only one:
  ``session_manager.validate_session`` enforces its own idle timeout, and for
  a **remember-me** session — which ``_enforce_session_expiry`` deliberately
  skips — it is the ONLY server-side deadline standing between a captured
  cookie and the account for the rest of the 30-day itsdangerous window.
  Nothing exercised it through HTTP.
* **Registration auto-login gets the SHORT deadline.**
  ``tests/web/test_registration_session_cookie.py`` pins the browser-facing
  half (no ``Max-Age``). The server-side half — ``_remember_me = False``, so
  the 2h ``security.session_timeout_hours`` deadline applies rather than the
  30-day one — is the half a stolen cookie cares about.

DELIBERATELY NOT DUPLICATED (surveyed, already covered)
-------------------------------------------------------
``SameSite=lax`` / ``HttpOnly`` on the session cookie, and the
remember-me ``Max-Age`` in both directions:
``tests/web/test_session_cookie_behavior.py``,
``tests/web/test_remember_me_and_json_body_cap.py``.
``Secure`` present iff the scheme is genuinely https, in both directions:
``tests/web/test_secure_cookie_middleware.py``,
``tests/security/test_cookie_security.py``.
Revoked-cookie replay on the two ``require_auth``-free GET routes:
``tests/security/test_auth_credential_lifetime_fastapi.py``.
The all-routes anonymous sweep: ``tests/security/test_auth_dependencies_fastapi.py``.

Everything here drives the REAL assembled app over TestClient against the
real ``db_manager`` / ``session_manager`` singletons. Nothing recomputes what
the SUT computes: expected values are either constants of the contract, or
observations taken from a positive control BEFORE the property is broken.

Every expectation below was derived by compiling the relevant node out of
``src/`` with ``ast`` and executing it verbatim (``SessionManager``,
``_enforce_session_expiry`` / ``_stamp_session_expiry`` /
``_enforce_session_revocation``, ``require_auth`` /
``clear_session_if_unrecoverable`` / ``ensure_user_database``, the ``logout``
route handler, ``CSRFMiddleware``, and Starlette's own ``SessionMiddleware``),
not by running this file. CI is the first place these assertions execute
against the assembled app.
"""

from __future__ import annotations

import base64
import datetime
import json
import uuid

import pytest

# The autouse ``_legacy_bare_username_auth`` shim in tests/conftest.py patches
# ``dependencies.auth._server_session_valid`` to accept unconditionally, which
# is exactly the gate that makes a destroyed or idle-expired server-side
# session stop authenticating. Every rejection asserted below would be
# unprovable under that shim, so this module opts out wholesale.
pytestmark = pytest.mark.real_session_check


TEST_PASSWORD = "S3ssion-Lifecycle!"  # noqa: S105


# ---------------------------------------------------------------------------
# Fixtures / helpers
# ---------------------------------------------------------------------------


@pytest.fixture
def live_app(tmp_path, monkeypatch):
    """The real assembled app on a throwaway data dir.

    Idiom copied from
    ``tests/security/test_auth_credential_lifetime_fastapi.py::live_app``:
    the routes read module-level singletons (``db_manager``,
    ``session_manager``), so the app has to run against those exact
    instances and the data dir must be repointed on the singleton itself.
    """
    monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path))
    monkeypatch.setenv("LDR_TESTING_WITH_MOCKS", "true")
    # The HTTP limiter guarding /auth/login (5/15min/IP), not the
    # search-engine knob — several tests below log in three times.
    monkeypatch.setenv("LDR_DISABLE_RATE_LIMITING", "true")
    monkeypatch.setenv("LDR_DB_CONFIG_KDF_ITERATIONS", "1000")

    from local_deep_research.database.auth_db import init_auth_database
    from local_deep_research.database.encrypted_db import db_manager
    import local_deep_research.web.routers.auth as auth_routes
    from local_deep_research.web.fastapi_app import app as fastapi_app

    original_data_dir = db_manager.data_dir
    try:
        db_manager.data_dir = tmp_path / "encrypted_databases"
        init_auth_database()
        # Keep these synchronous tests off the real post-login worker
        # threads (settings migration, library init, backup scheduling).
        monkeypatch.setattr(
            auth_routes,
            "_perform_post_login_tasks",
            lambda _u, _p, _sid=None: None,
        )
        yield fastapi_app
    finally:
        db_manager.close_all_databases()
        db_manager.data_dir = original_data_dir


def _client(app):
    """A TestClient with its own cookie jar and its own peer address.

    slowapi buckets by client IP, so every client in a test needs a
    distinct X-Forwarded-For or they share a bucket.
    """
    from fastapi.testclient import TestClient

    client = TestClient(app, raise_server_exceptions=False)
    octets = uuid.uuid4().int
    client.headers.update(
        {
            "X-Forwarded-For": (
                f"10.{octets % 254 + 1}.{octets // 254 % 254 + 1}.9"
            )
        }
    )
    return client


def _csrf(client) -> str:
    client.get("/auth/login")
    resp = client.get("/auth/csrf-token")
    return resp.json().get("csrf_token", "") if resp.status_code == 200 else ""


def _register(client, username, password=TEST_PASSWORD):
    token = _csrf(client)
    return client.post(
        "/auth/register",
        data={
            "username": username,
            "password": password,
            "confirm_password": password,
            "acknowledge": "true",
            "csrf_token": token,
        },
        headers={"X-CSRFToken": token},
        follow_redirects=False,
    )


def _login(client, username, password=TEST_PASSWORD, remember="false"):
    token = _csrf(client)
    return client.post(
        "/auth/login",
        data={
            "username": username,
            "password": password,
            "remember": remember,
            "csrf_token": token,
        },
        headers={"X-CSRFToken": token},
        follow_redirects=False,
    )


def _logout(client):
    token = _csrf(client)
    return client.post(
        "/auth/logout",
        data={"csrf_token": token},
        headers={"X-CSRFToken": token},
        follow_redirects=False,
    )


def _session_payload(client) -> dict:
    """Decode the signed-but-unencrypted Starlette session cookie body.

    Read-only observation of what the server put in the cookie; the
    signature is not checked here because the server's acceptance of the
    cookie is what the tests assert on.
    """
    raw = client.cookies.get("session")
    # "null" is Starlette's deletion sentinel: SessionMiddleware answers a
    # cleared session with `session=null; expires=Thu, 01 Jan 1970 ...`.
    if not raw or raw == "null":
        return {}
    head = raw.split(".")[0]
    return json.loads(base64.b64decode(head + "=" * (-len(head) % 4)))


def _assert_authenticated(client, username, why):
    """Positive control: this client is fully logged in as ``username``.

    Probes both gates: ``/auth/check`` (calls ``require_auth`` itself and
    turns its 401 into a JSON answer, behind the
    ``_enforce_session_revocation`` / ``_enforce_session_expiry``
    middleware checks) and ``/auth/integrity-check`` (a real
    ``Depends(require_auth)`` route that opens the user's encrypted database
    and echoes the username back).
    """
    check = client.get("/auth/check")
    assert check.status_code == 200, (
        f"{why}: /auth/check answered {check.status_code} — {check.text[:300]}"
    )
    assert check.json() == {"authenticated": True, "username": username}

    probe = client.get("/auth/integrity-check", follow_redirects=False)
    assert probe.status_code == 200, (
        f"{why}: /auth/integrity-check answered {probe.status_code} — "
        f"{probe.text[:300]}"
    )
    body = probe.json()
    assert body["username"] == username
    assert body["integrity"] == "valid", (
        f"{why}: the user's database did not open cleanly: {body}"
    )


def _assert_anonymous(client, username, why):
    """This client is not authenticated as ``username`` on either gate.

    ``/auth/integrity-check`` is an HTML-ish route, so its 401 is turned
    into a 302 to the login page by the global exception handler; both
    shapes are a refusal, and anything else (200, or a 5xx that would mean
    the request reached the database) is not.
    """
    check = client.get("/auth/check")
    assert check.status_code == 401, (
        f"{why}: /auth/check still authenticated — {check.status_code} "
        f"{check.text[:300]}"
    )
    assert check.json() == {"authenticated": False}
    assert username not in check.text

    probe = client.get("/auth/integrity-check", follow_redirects=False)
    assert probe.status_code in (401, 302), (
        f"{why}: /auth/integrity-check answered {probe.status_code} "
        f"(expected 401 or a 302 to login) — {probe.text[:300]}"
    )
    if probe.status_code == 302:
        assert probe.headers.get("location", "").startswith("/auth/login")
    assert username not in probe.text


@pytest.fixture
def registered_user(live_app):
    """A freshly registered user, with the registering client logged out.

    Returns ``(app, username)``.
    """
    app = live_app
    username = f"lifecycle_{uuid.uuid4().hex[:8]}"
    bootstrap = _client(app)
    resp = _register(bootstrap, username)
    assert resp.status_code == 302, (
        f"registration bootstrap failed: {resp.status_code} {resp.text[:400]}"
    )
    assert _logout(bootstrap).status_code == 302
    return app, username


# ---------------------------------------------------------------------------
# 1. Logout scope — the motivating bug
# ---------------------------------------------------------------------------


class TestLogoutIsScopedToTheSessionThatRequestedIt:
    """Logging out on one device must not log the user out on another.

    Two independent clients (= two devices) authenticate as the SAME user.
    One logs out. The other must be untouched at every layer logout
    reaches into: the server-side session record, the session-password
    store entry, the shared SQLCipher connection, and end-to-end HTTP.
    """

    @pytest.fixture
    def two_devices(self, registered_user):
        """(app, username, phone, laptop) — both logged in and PROVEN live.

        The positive control is inside the fixture on purpose: every
        assertion in this class is of the form "the laptop still works",
        which is worthless unless the laptop demonstrably worked first.
        """
        app, username = registered_user

        phone = _client(app)
        assert _login(phone, username).status_code == 302
        laptop = _client(app)
        assert _login(laptop, username).status_code == 302

        sid_phone = _session_payload(phone).get("session_id")
        sid_laptop = _session_payload(laptop).get("session_id")
        assert sid_phone and sid_laptop and sid_phone != sid_laptop, (
            "the two clients must hold two distinct server-side sessions; "
            f"got {sid_phone!r} and {sid_laptop!r}"
        )

        _assert_authenticated(phone, username, "before any logout, phone")
        _assert_authenticated(laptop, username, "before any logout, laptop")

        return app, username, phone, laptop

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "LIVE DEFECT — logout is only session-scoped in its "
            "session_manager.destroy_session call. It then wipes the user's "
            "WHOLE credential store (clear_all_for_user) and closes the "
            "shared per-user SQLCipher connection, so the surviving session "
            "cannot resolve a password on its next request and "
            "clear_session_if_unrecoverable wipes its cookie too. Remove "
            "this marker with the fix."
        ),
    )
    def test_the_other_device_stays_logged_in_over_http(self, two_devices):
        from local_deep_research.database.encrypted_db import db_manager

        if not db_manager.has_encryption:
            # Without SQLCipher every database opens with the dummy
            # password, so ensure_user_database's third source silently
            # repairs the connection logout tore down and the defect is
            # invisible from HTTP. The store- and connection-level tests
            # below still show it. CI installs libsqlcipher-dev, so this
            # branch is not the normal path.
            pytest.skip("needs an encrypted deployment to be observable")

        app, username, phone, laptop = two_devices

        assert _logout(phone).status_code == 302

        _assert_anonymous(phone, username, "the device that logged out")
        _assert_authenticated(
            laptop,
            username,
            "the OTHER device after a single-session logout — logout is "
            "scoped to one session_id, so this one must survive it",
        )

    def test_the_other_sessions_server_side_record_survives(self, two_devices):
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        app, username, phone, laptop = two_devices
        sid_phone = _session_payload(phone)["session_id"]
        sid_laptop = _session_payload(laptop)["session_id"]

        assert _logout(phone).status_code == 302

        assert session_manager.validate_session(sid_phone) is None, (
            "logout must destroy the server-side session of the device "
            "that asked for it"
        )
        assert session_manager.validate_session(sid_laptop) == username, (
            "logout destroyed the OTHER device's server-side session — it "
            "must call destroy_session(session_id), never "
            "destroy_all_user_sessions(username)"
        )

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "LIVE DEFECT — logout is only session-scoped in its "
            "session_manager.destroy_session call. It then wipes the user's "
            "WHOLE credential store (clear_all_for_user) and closes the "
            "shared per-user SQLCipher connection, so the surviving session "
            "cannot resolve a password on its next request and "
            "clear_session_if_unrecoverable wipes its cookie too. Remove "
            "this marker with the fix."
        ),
    )
    def test_the_other_sessions_credential_is_not_wiped(self, two_devices):
        """``clear_all_for_user`` is the exact call that caused the bug.

        Every DB-touching route on the surviving session resolves its
        SQLCipher password through this store; dropping the user's whole
        store on a single-session logout is what turned the other device's
        requests into failures.
        """
        from local_deep_research.database.session_passwords import (
            session_password_store,
        )

        app, username, phone, laptop = two_devices
        sid_phone = _session_payload(phone)["session_id"]
        sid_laptop = _session_payload(laptop)["session_id"]
        assert (
            session_password_store.get_session_password(username, sid_laptop)
            is not None
        ), "premise: the laptop's credential must be in the store to start"

        assert _logout(phone).status_code == 302

        assert (
            session_password_store.get_session_password(username, sid_phone)
            is None
        ), "logout must drop the credential of the session it logged out"
        assert (
            session_password_store.get_session_password(username, sid_laptop)
            is not None
        ), (
            "logout wiped the OTHER session's stored SQLCipher password — "
            "this is the multi-device logout bug: clear_all_for_user() is "
            "username-scoped, so one device logging out strands every other "
            "device of the same user"
        )

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "LIVE DEFECT — logout is only session-scoped in its "
            "session_manager.destroy_session call. It then wipes the user's "
            "WHOLE credential store (clear_all_for_user) and closes the "
            "shared per-user SQLCipher connection, so the surviving session "
            "cannot resolve a password on its next request and "
            "clear_session_if_unrecoverable wipes its cookie too. Remove "
            "this marker with the fix."
        ),
    )
    def test_the_shared_database_connection_stays_open(self, two_devices):
        """A user-scoped ``close_user_database`` is the second half of it."""
        from local_deep_research.database.encrypted_db import db_manager

        app, username, phone, laptop = two_devices
        assert db_manager.is_user_connected(username), (
            "premise: both logins must leave the user's database open"
        )

        assert _logout(phone).status_code == 302

        assert db_manager.is_user_connected(username), (
            "logout closed the shared per-user database connection while "
            "another session of the same user was still live — that session "
            "then 500s (not 401s) on every DB-touching route"
        )


# ---------------------------------------------------------------------------
# 2. Session fixation, behaviourally
# ---------------------------------------------------------------------------


class TestPreLoginSessionStateIsNotHonouredAfterLogin:
    """``request.session.clear()`` at login must invalidate, not just rotate.

    ``tests/web/routers/test_auth_flow_gaps.py::TestSessionFixation`` pins
    that the pre-login ``_csrf_token`` value differs from the post-login
    one. That is the observable, not the guarantee: an attacker who fixed
    a token into the victim's pre-auth session cares whether the token he
    knows is ACCEPTED on the authenticated session.
    """

    def test_a_token_minted_before_login_is_refused_after_login(
        self, registered_user
    ):
        app, username = registered_user
        client = _client(app)

        planted = _csrf(client)
        assert planted, "the mint endpoint must issue a pre-auth token"
        assert _session_payload(client).get("_csrf_token") == planted

        assert _login(client, username).status_code == 302
        _assert_authenticated(client, username, "after login")

        # The planted token, replayed on a state-changing request. Logout
        # is used as the probe because it is CSRF-guarded, cheap, and its
        # success/failure is directly observable in the auth state below.
        refused = client.post(
            "/auth/logout",
            data={"csrf_token": planted},
            headers={"X-CSRFToken": planted},
            follow_redirects=False,
        )
        assert refused.status_code == 403, (
            "a CSRF token minted BEFORE authentication was still accepted "
            "on the authenticated session — the session-fixation fence "
            f"(request.session.clear() in the login handler) regressed; got "
            f"{refused.status_code}"
        )
        _assert_authenticated(
            client,
            username,
            "the refused request must have changed nothing",
        )

    def test_the_current_token_is_accepted_on_the_same_request(
        self, registered_user
    ):
        """Positive control for the test above.

        Without this, "403" would be equally explained by logout being
        unreachable, the route being gone, or CSRF rejecting everything.
        """
        app, username = registered_user
        client = _client(app)

        _csrf(client)  # plant a pre-auth token, exactly as above
        assert _login(client, username).status_code == 302

        current = _csrf(client)
        accepted = client.post(
            "/auth/logout",
            data={"csrf_token": current},
            headers={"X-CSRFToken": current},
            follow_redirects=False,
        )
        assert accepted.status_code == 302, (
            f"the session's own CSRF token was rejected: "
            f"{accepted.status_code} {accepted.text[:300]}"
        )
        _assert_anonymous(client, username, "after a real logout")


# ---------------------------------------------------------------------------
# 3. Cookie integrity
# ---------------------------------------------------------------------------


class TestForgedSessionCookiesAreRejected:
    """The session is a signed client-side cookie; the signature is the
    ONLY thing separating a claim from a fact.

    Each variant must land the caller in the anonymous state — not
    authenticated, and not a 5xx either (a crash reaching the database
    with attacker-shaped session data would be its own finding).
    """

    @pytest.fixture
    def victim(self, registered_user):
        """(app, username, session_id, valid_cookie) for a live session."""
        app, username = registered_user
        client = _client(app)
        assert _login(client, username).status_code == 302
        _assert_authenticated(client, username, "the victim's own session")
        payload = _session_payload(client)
        cookie = client.cookies.get("session")
        assert cookie
        return app, username, payload["session_id"], cookie

    @staticmethod
    def _replay(app, cookie_value):
        client = _client(app)
        client.cookies.set("session", cookie_value)
        return client

    def test_the_untouched_cookie_replays_successfully(self, victim):
        """Positive control: the cookie IS transferable while intact.

        Every rejection below is only meaningful because a byte-identical
        cookie in a byte-identical fresh client is accepted.
        """
        app, username, _sid, cookie = victim

        _assert_authenticated(
            self._replay(app, cookie),
            username,
            "an unmodified session cookie in a fresh client",
        )

    def test_a_truncated_cookie_is_rejected(self, victim):
        app, username, _sid, cookie = victim

        _assert_anonymous(
            self._replay(app, cookie[:-8]),
            username,
            "a cookie with the last 8 characters of its signature cut off",
        )

    def test_a_bit_flipped_signature_is_rejected(self, victim):
        app, username, _sid, cookie = victim

        prefix, encoded_signature = cookie.rsplit(".", 1)
        signature = base64.urlsafe_b64decode(
            encoded_signature + "=" * (-len(encoded_signature) % 4)
        )
        assert signature, "premise: the signed cookie has a signature"

        # Mutating the final Base64 character is not reliable: for an
        # unpadded SHA-1 digest, most of that character is unused padding.
        # Flip a bit in the decoded digest so the signature bytes must differ.
        flipped_signature = bytes([signature[0] ^ 0x01]) + signature[1:]
        flipped = (
            prefix
            + "."
            + base64.urlsafe_b64encode(flipped_signature).decode().rstrip("=")
        )
        assert flipped != cookie

        _assert_anonymous(
            self._replay(app, flipped),
            username,
            "a cookie whose decoded signature has one bit flipped",
        )

    def test_a_forged_payload_claiming_a_real_live_session_is_rejected(
        self, victim
    ):
        """The strongest form: every CLAIM in the payload is true.

        The username exists, the session id is a real one that
        ``session_manager.validate_session`` resolves to that username
        right now, and the database is open. Only the signature is
        missing. If the app ever fell back to "unsigned but well-formed
        is good enough", this is what it would let through.
        """
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        app, username, sid, _cookie = victim
        assert session_manager.validate_session(sid) == username, (
            "premise: the forged payload must name a session that is "
            "genuinely live, or this test proves nothing about signatures"
        )

        body = json.dumps(
            {"username": username, "session_id": sid, "_remember_me": False}
        ).encode()
        forged = (
            base64.b64encode(body).decode().rstrip("=")
            + ".ZmFrZQ.bm90LWEtc2lnbmF0dXJl"
        )

        _assert_anonymous(
            self._replay(app, forged),
            username,
            "an unsigned cookie asserting a real, live session id",
        )

    @pytest.mark.parametrize(
        "junk",
        [
            "",
            "not-a-cookie",
            "...",
            "eyJ1c2VybmFtZSI6ICJhZG1pbiJ9",  # bare b64, no timestamp/sig
        ],
        ids=["empty", "plain-text", "dots-only", "unsigned-b64"],
    )
    def test_structurally_invalid_cookies_are_rejected(self, victim, junk):
        app, username, _sid, _cookie = victim

        _assert_anonymous(
            self._replay(app, junk),
            username,
            f"a structurally invalid session cookie ({junk!r})",
        )


# ---------------------------------------------------------------------------
# 4. The server-side deadline the signed cookie cannot express
# ---------------------------------------------------------------------------


def _age_server_session(session_id: str, delta: datetime.timedelta) -> None:
    """Push a live server-side session's ``last_access`` into the past.

    Moves ONLY server state: the client's cookie bytes are untouched and
    stay cryptographically valid for the full ``max_age`` SessionMiddleware
    was built with. That is precisely the property under test — the server
    must be able to end a session it can no longer un-issue.

    Reaches into ``session_manager.sessions`` rather than monkeypatching a
    clock because ``SessionManager`` reads ``datetime.datetime.now(UTC)``
    directly, with no seam; and because ageing the record is what really
    happens when a user idles.
    """
    from local_deep_research.web.auth.session_manager import session_manager

    with session_manager._lock:
        record = session_manager.sessions[session_id]
        record["last_access"] = record["last_access"] - delta


class TestServerSideIdleDeadlineOutlivesTheCookieSignature:
    """``session_manager``'s idle timeout, enforced through HTTP.

    ``tests/web/test_migration_regression_fixes.py`` covers the OTHER
    server-side deadline (``_session_expires_at`` / ``_enforce_session_expiry``,
    driven via the ``fastapi_app._now_ts`` seam). This one is independent of
    it and is reached through ``_server_session_valid`` / ``require_auth``
    and ``_enforce_session_revocation`` — and for a remember-me session it
    is the ONLY server-side deadline there is, because
    ``_enforce_session_expiry`` returns early unless ``_remember_me is False``.
    """

    def test_an_idle_non_remember_me_session_stops_authenticating(
        self, registered_user
    ):
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        app, username = registered_user
        client = _client(app)
        assert _login(client, username, remember="false").status_code == 302
        sid = _session_payload(client)["session_id"]

        _assert_authenticated(client, username, "immediately after login")

        # Captured AFTER the first authenticated request, not right after
        # login: the login response's session still carries the one-time
        # `temp_auth_token` bootstrap credential (see
        # web/dependencies/auth.py), which the first authenticated request
        # legitimately consumes and pops from the session -- mutating the
        # cookie for a reason that has nothing to do with the idle timeout
        # under test. `_session_expires_at` also slides forward on every
        # authenticated response. Grabbing the "before" snapshot here, once
        # that natural per-request churn has settled, isolates the ONLY
        # remaining mutation between here and the assertion below to
        # `_age_server_session`'s direct, cookie-bytes-untouched edit of the
        # server-side record.
        cookie_before = client.cookies.get("session")

        _age_server_session(
            sid, session_manager.session_timeout + datetime.timedelta(minutes=1)
        )

        # Same client, same cookie bytes: only the server's record moved.
        assert client.cookies.get("session") == cookie_before, (
            "premise: the cookie must be unchanged, or the rejection below "
            "could be the client's doing rather than the server's"
        )
        _assert_anonymous(
            client,
            username,
            "a session idle past security.session_timeout_hours",
        )

    def test_an_idle_remember_me_session_stops_authenticating_too(
        self, registered_user
    ):
        """The 30-day window is a bound, not a blank cheque.

        A remember-me session is exempt from ``_enforce_session_expiry``,
        so if ``session_manager``'s own timeout were not consulted on the
        request path a captured remember-me cookie would authenticate for
        the entire itsdangerous window with no server-side say in it.
        """
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        app, username = registered_user
        client = _client(app)
        assert _login(client, username, remember="true").status_code == 302
        sid = _session_payload(client)["session_id"]
        assert _session_payload(client)["_remember_me"] is True

        _assert_authenticated(client, username, "immediately after login")

        # Well past the short timeout but inside the remember-me window:
        # this session must NOT be dropped yet, or the test below would
        # pass for the wrong reason (i.e. both timeouts collapsed into one).
        _age_server_session(
            sid, session_manager.session_timeout + datetime.timedelta(hours=1)
        )
        _assert_authenticated(
            client,
            username,
            "a remember-me session idle past the SHORT timeout — it is "
            "entitled to security.session_remember_me_days, not "
            "security.session_timeout_hours",
        )

        _age_server_session(
            sid,
            session_manager.remember_me_timeout + datetime.timedelta(hours=1),
        )
        _assert_anonymous(
            client,
            username,
            "a remember-me session idle past security.session_remember_me_days",
        )

    def test_the_expired_cookie_is_cleared_not_merely_refused(
        self, registered_user
    ):
        """The refusal must be terminal for that cookie, on that client.

        ``require_auth`` / ``_enforce_session_revocation`` clear the session
        dict in place, so SessionMiddleware answers with a cookie-deletion
        header and the client stops presenting a dead session instead of
        retrying it on every request forever.
        """
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        app, username = registered_user
        client = _client(app)
        assert _login(client, username).status_code == 302
        sid = _session_payload(client)["session_id"]
        _assert_authenticated(client, username, "immediately after login")

        _age_server_session(
            sid,
            session_manager.session_timeout + datetime.timedelta(minutes=1),
        )

        rejected = client.get("/auth/check")
        assert rejected.status_code == 401
        set_cookies = [
            v
            for k, v in rejected.headers.multi_items()
            if k.lower() == "set-cookie" and v.startswith("session=")
        ]
        assert set_cookies, (
            "the response that rejected the session issued no Set-Cookie — "
            "the client will keep presenting the dead cookie on every "
            "subsequent request"
        )
        assert any("session=null" in v and "1970" in v for v in set_cookies), (
            "the rejecting response must tell the browser to DROP the "
            f"session cookie, not re-issue it; got {set_cookies}"
        )

        _assert_anonymous(client, username, "on the request after the first")


# ---------------------------------------------------------------------------
# 5. Registration auto-login is bound by the SHORT deadline
# ---------------------------------------------------------------------------


class TestRegistrationAutoLoginGetsTheShortServerDeadline:
    """``tests/web/test_registration_session_cookie.py`` pins that the
    registration cookie carries no ``Max-Age``. That is a request to the
    browser; a cookie lifted out of the browser ignores it.

    What bounds the lifted cookie is ``_remember_me = False`` in the
    session payload, which is what makes ``_enforce_session_expiry`` stamp
    and enforce the 2h ``security.session_timeout_hours`` deadline rather
    than leaving the session on the 30-day itsdangerous window. Registration
    sets that flag in its own code path, separate from login's.
    """

    def test_the_auto_login_session_expires_on_the_short_deadline(
        self, live_app, monkeypatch
    ):
        from local_deep_research.web import fastapi_app as fastapi_app_module

        app = live_app
        username = f"lifecycle_{uuid.uuid4().hex[:8]}"
        client = _client(app)
        assert _register(client, username).status_code == 302

        _assert_authenticated(
            client, username, "auto-login straight after registration"
        )
        assert _session_payload(client).get("_remember_me") is False, (
            "registration auto-login must mark the session non-remember-me; "
            "without the flag _enforce_session_expiry returns early and the "
            "session rides the full 30-day signature window"
        )

        # Only the server's clock moves; the cookie bytes are untouched and
        # its itsdangerous signature stays valid for ~30 days.
        cookie_before = client.cookies.get("session")
        future = (
            fastapi_app_module._now_ts()
            + fastapi_app_module._NON_REMEMBER_ME_SESSION_SECONDS
            + 1
        )
        monkeypatch.setattr(fastapi_app_module, "_now_ts", lambda: future)

        assert client.cookies.get("session") == cookie_before
        _assert_anonymous(
            client,
            username,
            "a registration auto-login session past "
            "security.session_timeout_hours",
        )


class TestSessionTeardownEvictsCollectionEngineCache:
    """Every session teardown path must evict the user's collection-engine
    cache entry (#6609): logout and password change here, the idle sweeper
    in ``tests/web/auth/test_connection_cleanup.py``.

    The cache holds the user's collection names/descriptions for up to the
    30 s TTL (longer under stale-serve after a DB error); it is the same
    per-user residue class as the lock dicts these paths already drop.
    """

    def test_logout_evicts_the_users_cache_entry(
        self, registered_user, monkeypatch
    ):
        from local_deep_research.web_search_engines import (
            search_engines_config as sec,
        )

        app, username = registered_user
        client = _client(app)
        assert _login(client, username).status_code == 302

        evicted = []
        monkeypatch.setattr(
            sec, "evict_collection_engines_cache", lambda u: evicted.append(u)
        )

        assert _logout(client).status_code == 302

        assert evicted == [username]

    def test_password_change_evicts_the_users_cache_entry(
        self, registered_user, monkeypatch
    ):
        """A successful password change ends every session of the user,
        so it is a teardown path too."""
        from local_deep_research.web_search_engines import (
            search_engines_config as sec,
        )

        app, username = registered_user
        client = _client(app)
        assert _login(client, username).status_code == 302

        evicted = []
        monkeypatch.setattr(
            sec, "evict_collection_engines_cache", lambda u: evicted.append(u)
        )

        new_password = "N3w-Lifecycle-Pass!"  # noqa: S105
        token = _csrf(client)
        resp = client.post(
            "/auth/change-password",
            data={
                "current_password": TEST_PASSWORD,
                "new_password": new_password,
                "confirm_password": new_password,
                "csrf_token": token,
            },
            headers={"X-CSRFToken": token},
            follow_redirects=False,
        )
        assert resp.status_code == 302, resp.text[:300]
        assert resp.headers.get("location") == "/auth/login"

        assert evicted == [username]