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.

25.5 KB
Raw Blame
"""Auth-flow contracts the rest of the suite states but never proves.

WHY THIS FILE EXISTS
--------------------
The register / login / logout / change-password flows are heavily
covered on this branch (survey below), but three properties are asserted
*nowhere*, and each of them is the kind that stays green while the
behaviour it protects rots:

1. **Login failures must be indistinguishable.** Every existing test
   checks a failed login is ``401`` — separately for a wrong password and
   for an unknown username. Nothing ever compares the two. A handler that
   answered "no such user" for one and "wrong password" for the other
   would satisfy every one of those tests individually while handing an
   attacker a username oracle. ``routers/auth.py`` funnels both into a
   single ``engine is None`` branch, so the two responses are supposed to
   be *the same response*, and that is what is asserted here — byte for
   byte after checking and normalizing per-response template authorizations,
   off one client so the CSRF token in the rendered form is identical.

   The same equality also pins, for free, that the submitted username is
   never echoed into the 401 body (the two probes use different
   usernames), and the lockout arm is checked the same way: a nonexistent
   account must lock out exactly like a real one, because
   ``record_failure`` is called before anyone knows whether the user
   exists. Skipping it for unknown users — a plausible "optimisation" —
   turns the 429/401 split into the oracle the 401 body no longer is.

   Timing is deliberately NOT asserted: a wall-clock comparison flakes in
   CI. ``_open_user_database_cold`` derives the key *before* the file
   existence check precisely to flatten it (encrypted_db.py:1003), and
   the observable shape is what this file pins instead.

2. **A failed login for an unknown user must leave nothing behind.**
   ``open_user_database`` runs a real PBKDF2 over ``db_path`` for a user
   that does not exist. If that path ever started materialising a
   ``.salt`` (or anything else) the way ``create_user_database`` does,
   an attacker could squat every interesting username with nothing but
   login attempts — and the victim's later registration would hit the
   orphaned-salt path instead of a clean create. Asserted as: the data
   directory is byte-identically unchanged, no auth row appears, and the
   username is still registerable afterwards.

3. **The strict string flags the handlers compare against must be the
   ones the rendered forms actually ship.** ``login`` computes
   ``remember == "true"`` and ``register`` computes
   ``acknowledge == "true"`` — exact string equality, with no truthiness
   fallback. Every test in the suite hard-codes ``"true"`` in the POST
   body, so all of them keep passing if ``value="true"`` is dropped from
   the checkbox in ``auth/login.html`` — at which point a real browser
   submits ``remember=on``, the comparison is False, and remember-me
   silently degrades to a 2-hour session for every user with no error
   anywhere. These tests take the value out of the **rendered page** and
   feed it to the **real handler**, so the two halves can no longer drift
   apart unnoticed.

DELIBERATELY NOT DUPLICATED (surveyed, already covered)
-------------------------------------------------------
* Session fixation (cookie value + server-side session id rotate across
  login, pre-auth session content does not survive), logout destroying
  the server-side session / password-store entry, and change-password
  destroying the user's OTHER sessions:
  ``tests/web/routers/test_auth_flow_gaps.py``.
* The full change-password lifecycle with a REAL SQLCipher rekey (old
  password dead, new password works, both sessions locked out, data
  preserved): ``tests/web/test_long_integration_flows_followup.py
  ::TestPasswordChangeLifecycle``.
* Registration input validation — empty/short/non-alnum username,
  mismatched confirmation, missing acknowledgement, weak password, and
  the duplicate-username rejection including its generic
  no-enumeration copy and the no-account-takeover property:
  ``tests/security/test_auth_routes_fastapi.py``.
* Lockout mechanics through the route (threshold boundary, success
  clears the counter, lockout is per-username):
  ``tests/web/routers/test_account_lockout_route.py``. This file adds
  only the real-vs-nonexistent *parity*, which that file does not
  compare.
* Remember-me as a cookie ``Max-Age`` in both directions:
  ``tests/web/test_session_cookie_behavior.py``,
  ``tests/web/test_remember_me_and_json_body_cap.py``. The server-side
  30-day idle window: ``tests/web/test_auth_session_lifecycle.py``.
* Forged / truncated cookies, the server-side idle deadline, pre-login
  CSRF token rejection, and multi-device logout (a pinned strict-xfail
  trade-off): ``tests/web/test_auth_session_lifecycle.py``.

HARNESS
-------
The function-scoped ``app`` fixture from ``tests/conftest.py`` (points
``LDR_DATA_DIR`` at a throwaway directory, drops the KDF iteration count,
and stubs the post-login background worker). CSRF is ASGI middleware with
no off switch, so every POST carries a real token. slowapi is forced off
per test: these tests need more login POSTs than the 5/15min per-IP limit
allows and none of them is *about* rate limiting, so a limiter 429 here
would be pure noise. Each client still gets its own ``X-Forwarded-For``.
"""

from __future__ import annotations

import base64
import json
import re
import uuid

import pytest
from fastapi.testclient import TestClient

TEST_PASSWORD = "AuthContract123"  # noqa: S105
WRONG_PASSWORD = "AuthContract999"  # noqa: S105
LOCKOUT_MESSAGE = "Account is temporarily locked"
INVALID_CREDENTIALS_MESSAGE = "Invalid username or password"


# ---------------------------------------------------------------------------
# Harness
# ---------------------------------------------------------------------------


@pytest.fixture(autouse=True)
def _slowapi_off():
    """Take the per-IP HTTP rate limiter out of the picture.

    ``LOGIN_RATE_LIMIT`` is 5/15min/IP; several tests below need more
    login POSTs than that from one client. Nothing here is about rate
    limiting (``tests/web/routers/test_auth_rate_limits.py`` owns that),
    so a slowapi 429 would only mask the 401/429/302 under test. It also
    means every 429 observed below can only be account lockout.
    """
    from local_deep_research.web.dependencies.rate_limit import limiter

    original = limiter.enabled
    limiter.enabled = False
    try:
        yield
    finally:
        limiter.enabled = original


def _client(app) -> TestClient:
    """Fresh client with its own cookie jar and its own peer address."""
    client = TestClient(app, raise_server_exceptions=False)
    n = uuid.uuid4().int
    client.headers.update(
        {"X-Forwarded-For": f"10.{n % 254 + 1}.{n // 254 % 254 + 1}.7"}
    )
    return client


def _csrf(client: TestClient) -> str:
    """Mint (or re-read) this session's CSRF token.

    ``generate_csrf_token`` stores the token in the session and returns
    the stored one on every later call, so this is stable for the life of
    a session — which is what lets the byte-for-byte comparisons below
    work on a single client.
    """
    client.get("/auth/login")
    resp = client.get("/auth/csrf-token")
    assert resp.status_code == 200, (
        f"CSRF bootstrap failed: {resp.status_code} {resp.text[:200]}"
    )
    return resp.json()["csrf_token"]


def _login(client: TestClient, username: str, password: str, **extra):
    token = _csrf(client)
    data = {
        "username": username,
        "password": password,
        "csrf_token": token,
    }
    data.update(extra)
    return client.post(
        "/auth/login",
        data=data,
        headers={"X-CSRFToken": token},
        follow_redirects=False,
    )


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


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


def _session_payload(client: TestClient) -> dict:
    """Decode the signed-but-unencrypted Starlette session cookie body."""
    raw = client.cookies.get("session")
    if not raw or raw == "null":
        return {}
    head = raw.split(".")[0]
    return json.loads(base64.b64decode(head + "=" * (-len(head) % 4)))


def _unique(prefix: str) -> str:
    return f"{prefix}_{uuid.uuid4().hex[:10]}"


def _register_then_logout(app, username: str) -> None:
    """Create a real account and close its cached DB connection.

    Registration auto-logs-in AND leaves the user's engine cached in
    ``db_manager.connections``. Logging out is what evicts it, so a later
    wrong-password login genuinely re-derives the key and fails through
    the same cold path an unknown user takes — without this, the two
    probes in the enumeration tests would not be comparing like with
    like.
    """
    boot = _client(app)
    resp = _register(boot, username, TEST_PASSWORD)
    assert resp.status_code == 302, (
        f"registration bootstrap failed: {resp.status_code} {resp.text[:400]}"
    )
    assert _logout(boot).status_code == 302


def _auth_row_exists(username: str) -> bool:
    from local_deep_research.database.auth_db import get_auth_db_session
    from local_deep_research.database.models.auth import User

    auth_db = get_auth_db_session()
    try:
        row = auth_db.query(User).filter_by(username=username).first()
        return row is not None
    finally:
        auth_db.close()


# ---------------------------------------------------------------------------
# 1. Login failures must not distinguish "no such user" from "wrong password"
# ---------------------------------------------------------------------------


def _auth_page_without_response_tokens(response):
    """Validate template authorizations and normalize only their values."""
    policy = response.headers["content-security-policy"]
    nonces = set(re.findall(r"'nonce-([^']+)'", policy))
    assert len(nonces) == 1
    nonce = nonces.pop()
    assert re.fullmatch(r"[A-Za-z0-9_-]{43}", nonce)
    assert set(re.findall(r'\bnonce="([^"]*)"', response.text)) == {nonce}

    tokens = re.findall(r'data-template-token="([^"]*)"', response.text)
    assert len(tokens) == 1
    token = tokens[0]
    assert re.fullmatch(r"[A-Za-z0-9_-]{43}", token)
    assert set(
        re.findall(r'data-ldr-template-token="([^"]*)"', response.text)
    ) <= {token}
    return response.content.replace(
        nonce.encode("ascii"), b"<template-nonce>"
    ).replace(token.encode("ascii"), b"<template-event-token>")


class TestLoginFailuresAreIndistinguishable:
    """The 401 an attacker sees must carry no signal about the account.

    Both failure modes reach the same ``engine is None`` branch of
    ``routers/auth.py::login``, which flashes one fixed message and
    re-renders ``auth/login.html`` with a context that does NOT include
    the submitted username. So the two responses are supposed to be the
    identical response after normalizing the checked template nonce and
    event token. One client keeps the session and CSRF token the same.
    """

    def test_unknown_user_and_wrong_password_are_byte_identical(self, app):
        """A username oracle would show up as a difference here.

        Would fail if the handler branched on ``user_exists`` for the
        message, the status, or the flash category; if it echoed the
        submitted username back into the form; or if only one of the two
        arms rendered the login page.
        """
        real_user = _unique("enum_real")
        _register_then_logout(app, real_user)
        ghost_user = _unique("enum_ghost")

        # One client keeps the session and CSRF token stable.
        probe = _client(app)

        ghost = _login(probe, ghost_user, TEST_PASSWORD)
        wrong = _login(probe, real_user, WRONG_PASSWORD)

        assert ghost.status_code == 401, (
            f"login for a nonexistent user should be 401, got "
            f"{ghost.status_code}: {ghost.text[:300]}"
        )
        assert wrong.status_code == 401, (
            f"login with a wrong password should be 401, got "
            f"{wrong.status_code}: {wrong.text[:300]}"
        )
        assert INVALID_CREDENTIALS_MESSAGE in wrong.text, (
            "the 401 must carry the generic credentials message; got: "
            f"{wrong.text[:300]}"
        )
        assert ghost.headers.get("content-type") == wrong.headers.get(
            "content-type"
        )
        assert _auth_page_without_response_tokens(
            ghost
        ) == _auth_page_without_response_tokens(wrong), (
            "the response to a nonexistent user differs from the response "
            "to a wrong password — that difference is a username oracle. "
            "Both must come out of the same generic branch."
        )
        # ...and neither body names the account that was tried.
        assert real_user not in wrong.text
        assert ghost_user not in ghost.text

        # POSITIVE CONTROL: 401 is not simply what /auth/login always
        # answers. The same account, with the right password, logs in.
        good = _client(app)
        ok = _login(good, real_user, TEST_PASSWORD)
        assert ok.status_code == 302, (
            "control failed: correct credentials did not authenticate "
            f"({ok.status_code}) — the two 401s above prove nothing if "
            f"login is broken outright. {ok.text[:300]}"
        )
        assert _session_payload(good).get("username") == real_user

    def test_lockout_treats_a_nonexistent_account_like_a_real_one(self, app):
        """``record_failure`` runs before anyone knows the user exists.

        If it were skipped for unknown usernames, a real account would
        start answering 429 while a nonexistent one kept answering 401 —
        a cleaner oracle than the one the 401 body was made to hide. The
        two lockout responses are compared byte for byte off one client,
        the same way as above.
        """
        from local_deep_research.security import account_lockout
        from local_deep_research.security.account_lockout import (
            AccountLockoutManager,
        )

        real_user = _unique("lock_real")
        _register_then_logout(app, real_user)
        ghost_user = _unique("lock_ghost")
        untouched_user = _unique("lock_untouched")

        # The real manager class, configured low so this costs 6 POSTs
        # instead of 21. The singleton is reset by the autouse
        # ``reset_all_singletons`` fixture in tests/conftest.py.
        account_lockout._manager = AccountLockoutManager(
            threshold=2, lockout_minutes=15
        )

        probe = _client(app)
        for attempt in range(2):
            for user in (real_user, ghost_user):
                resp = _login(probe, user, WRONG_PASSWORD)
                assert resp.status_code == 401, (
                    f"attempt {attempt + 1} for {user!r} should still be a "
                    f"plain 401 (the threshold is only reached ON this "
                    f"attempt, and is enforced from the next one): "
                    f"{resp.status_code} {resp.text[:300]}"
                )

        locked_real = _login(probe, real_user, WRONG_PASSWORD)
        locked_ghost = _login(probe, ghost_user, TEST_PASSWORD)

        for label, resp in (
            ("the real account", locked_real),
            ("the nonexistent account", locked_ghost),
        ):
            assert resp.status_code == 429, (
                f"{label} was not locked out after passing the threshold: "
                f"{resp.status_code} {resp.text[:300]}"
            )
            assert LOCKOUT_MESSAGE in resp.text, (
                f"{label} got a 429 without the lockout copy — this looks "
                f"like a rate-limiter 429, not account lockout: "
                f"{resp.text[:300]}"
            )
        assert _auth_page_without_response_tokens(
            locked_real
        ) == _auth_page_without_response_tokens(locked_ghost), (
            "a locked real account and a locked nonexistent account answer "
            "differently — the lockout arm leaks whether the username "
            "exists, which is exactly what the generic 401 prevents"
        )

        # NEGATIVE CONTROL: 429 is not simply what this client now gets
        # for everything. A username that was never hammered is still a
        # plain 401, so the two 429s above are caused by the failures.
        fresh = _login(probe, untouched_user, WRONG_PASSWORD)
        assert fresh.status_code == 401, (
            "control failed: an un-hammered username also answered "
            f"{fresh.status_code}; lockout is not keyed to the username "
            "that accumulated the failures"
        )

    def test_a_failed_login_for_an_unknown_user_leaves_nothing_behind(
        self, app
    ):
        """No squatting: a login attempt must not materialise the account.

        ``_open_user_database_cold`` derives a key over the (absent)
        database path *before* checking whether the file exists, to
        flatten the timing difference. That derivation reads the salt
        file; the moment it starts creating one, an attacker can brick
        or fingerprint any username with unauthenticated POSTs. Pinned
        three ways: the data directory is unchanged, no auth row is
        created, and the username still registers cleanly afterwards.
        """
        from local_deep_research.database.encrypted_db import db_manager

        ghost_user = _unique("squat")
        root = db_manager.data_dir

        def _snapshot() -> list[tuple[str, int]]:
            return sorted(
                (str(p.relative_to(root)), p.stat().st_size)
                for p in root.rglob("*")
                if p.is_file()
            )

        before = _snapshot()
        resp = _login(_client(app), ghost_user, TEST_PASSWORD)
        assert resp.status_code == 401, (
            f"expected a 401 for an unknown user: {resp.status_code}"
        )

        assert _snapshot() == before, (
            "a failed login for a nonexistent user wrote into the "
            f"encrypted-database directory {root} — an unauthenticated "
            "caller must not be able to create on-disk state for a "
            "username that does not exist"
        )
        assert not _auth_row_exists(ghost_user), (
            "a failed login created an auth-DB row for a username that "
            "was never registered"
        )
        assert not db_manager.user_exists(ghost_user)

        # And the username is still genuinely usable: the failed attempt
        # did not leave a half-state that registration trips over.
        owner = _client(app)
        created = _register(owner, ghost_user, TEST_PASSWORD)
        assert created.status_code == 302, (
            "a username that was merely guessed at the login form can no "
            f"longer be registered: {created.status_code} "
            f"{created.text[:400]}"
        )
        assert _session_payload(owner).get("username") == ghost_user


# ---------------------------------------------------------------------------
# 2. The forms and the handlers must agree on the literal flag values
# ---------------------------------------------------------------------------


_CHECKBOX_RE_TEMPLATE = r"<input\b[^>]*\bname=[\"']{name}[\"'][^>]*>"
_VALUE_RE = re.compile(r"\bvalue=[\"']([^\"']*)[\"']", re.IGNORECASE)


def _shipped_checkbox_value(html: str, name: str) -> str:
    """The value a browser would submit for checkbox *name* in *html*.

    An HTML checkbox with no ``value`` attribute submits the literal
    ``"on"``, so that is the fallback — which makes a dropped
    ``value="true"`` surface as a real failure of the tests below rather
    than as a parse error that could be mistaken for test rot.
    """
    tag_re = re.compile(
        _CHECKBOX_RE_TEMPLATE.format(name=re.escape(name)), re.IGNORECASE
    )
    match = tag_re.search(html)
    assert match, (
        f"no <input name={name!r}> in the rendered page — the form no "
        f"longer submits this field at all"
    )
    tag = match.group(0)
    assert 'type="checkbox"' in tag or "type='checkbox'" in tag, (
        f"the {name!r} field is no longer a checkbox: {tag}"
    )
    value = _VALUE_RE.search(tag)
    return value.group(1) if value else "on"


class TestRenderedFormsShipTheValuesTheHandlersCompareAgainst:
    """``remember == "true"`` / ``acknowledge == "true"`` are exact string
    comparisons with no truthiness fallback. Every other test in the
    suite hard-codes ``"true"`` in the POST body and therefore cannot
    see the template drifting away from it. These take the value out of
    the page the server actually renders.
    """

    def test_the_login_forms_remember_value_is_the_one_that_persists(self, app):
        """Remember-me degrades SILENTLY when this coupling breaks.

        Drop ``value="true"`` from the checkbox and browsers submit
        ``remember=on``; ``remember == "true"`` is then False, every user
        quietly gets the 2h session instead of the 30-day one, and no
        error is raised anywhere. Observed on the server-side session
        record — the thing that actually decides which idle deadline
        applies (``SessionManager.validate_session``) — rather than on
        the cookie's ``Max-Age``, which has its own coverage.
        """
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        username = _unique("remember")
        _register_then_logout(app, username)

        page = _client(app).get("/auth/login")
        assert page.status_code == 200, page.status_code
        shipped = _shipped_checkbox_value(page.text, "remember")

        client = _client(app)
        resp = _login(client, username, TEST_PASSWORD, remember=shipped)
        assert resp.status_code == 302, (
            f"login failed: {resp.status_code} {resp.text[:300]}"
        )
        sid = _session_payload(client).get("session_id")
        assert sid, "authenticated session must carry a session_id"

        assert session_manager.sessions[sid]["remember_me"] is True, (
            f"the login form ships remember={shipped!r}, but the handler "
            f"did not treat that as remember-me. The checkbox value in "
            f'auth/login.html and the `remember == "true"` comparison '
            f"in routers/auth.py have drifted apart: every real browser "
            f"now silently gets the short session instead of the 30-day "
            f"one, with no error to notice."
        )

        # CONTROL: the comparison really is exact, so the value above is
        # load-bearing and not merely one of many accepted spellings.
        for near_miss in ("on", "1", "True", "yes", ""):
            other = _client(app)
            assert (
                _login(
                    other, username, TEST_PASSWORD, remember=near_miss
                ).status_code
                == 302
            )
            other_sid = _session_payload(other).get("session_id")
            assert (
                session_manager.sessions[other_sid]["remember_me"] is False
            ), (
                f"remember={near_miss!r} was accepted as remember-me. The "
                f"handler compares for exact equality with one literal; "
                f"if that is no longer true, the assertion above stops "
                f"proving the template and the handler agree."
            )

    def test_the_register_forms_acknowledge_value_is_the_one_accepted(
        self, app
    ):
        """The register form's checkbox value gates account creation.

        Same coupling, louder failure mode: if the shipped value stops
        matching, registration becomes impossible from a browser (every
        submission comes back 400 "You must acknowledge"), even though
        every test that hard-codes ``"true"`` still passes.
        """
        page = _client(app).get("/auth/register")
        assert page.status_code == 200, page.status_code
        shipped = _shipped_checkbox_value(page.text, "acknowledge")

        username = _unique("ack")
        client = _client(app)
        resp = _register(client, username, TEST_PASSWORD, acknowledge=shipped)
        assert resp.status_code == 302, (
            f"the register form ships acknowledge={shipped!r}, but the "
            f"handler rejected it ({resp.status_code}) — the checkbox in "
            f'auth/register.html and the `acknowledge == "true"` '
            f"comparison in routers/auth.py no longer agree, so no "
            f"browser can complete registration: {resp.text[:400]}"
        )
        assert _auth_row_exists(username)
        assert _session_payload(client).get("username") == username

        # CONTROL: the value is genuinely checked. The browser default
        # for a checkbox with no `value` attribute is refused, so the
        # assertion above is about the shipped literal and not about the
        # field merely being present.
        other = _client(app)
        refused = _register(
            other, _unique("ack_bad"), TEST_PASSWORD, acknowledge="on"
        )
        assert refused.status_code == 400, (
            "control failed: acknowledge='on' was accepted, so the "
            "handler is not comparing against a specific literal at all "
            f"({refused.status_code})"
        )
        assert "You must acknowledge" in refused.text