~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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