~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
"""Multi-step authentication attack scenarios, driven end to end over HTTP.
Unit-level auth is covered thoroughly on this branch. What was missing is
the COMPOSITION of steps: the states an attacker actually reaches are
built out of two or three legitimate operations, and each of the guards
below is correct in isolation while the interesting failure only shows up
once another operation has restored the precondition the guard's siblings
rely on.
The recurring shape: of the checks that stand between a replayed cookie
and the account, most are USER-scoped — ``is_user_connected`` is true
whenever ANY session for that user has the database open, and the
password resolver falls back to ``get_any_session_password``. Exactly one
is SESSION-scoped: the server-side ``session_id`` lookup, enforced for
every HTTP route by ``fastapi_app._enforce_session_revocation`` (called
from ``DatabaseMiddleware.__call__``, which empties the session dict so a
revoked cookie is indistinguishable from anonymous to everything
downstream) and, redundantly, by ``require_auth`` ->
``_server_session_valid`` on the routes that use it.
The consequence for tests: a revocation test that does not first RE-OPEN
the account passes for the wrong reason. It observes the DB-closed
refusal, and the DB-closed refusal evaporates the moment anyone, on any
device, logs in again. Each scenario here therefore reopens the account
(a later login, or a second live device) before replaying the revoked
cookie, and pins the refusal's ``detail`` string, which distinguishes:
"Database connection required" -> only the DB-closed check fired
"Authentication required" -> revocation fired
VERIFIED, not asserted from reading. With
``_enforce_session_revocation`` stubbed to a no-op (and ``require_auth``'s
own gate left fully intact), all three revocation scenarios below FAIL,
while ``tests/web/test_long_integration_flows_followup.py::
TestPasswordChangeLifecycle`` — the nearest existing coverage, which
asserts a bare ``401`` on the other device after a password change —
still PASSES, because it never reopens the account and so is satisfied by
the DB-closed 401. That is the gap this module closes.
The ``real_session_check`` marker below is still required: without it the
autouse ``_legacy_bare_username_auth`` shim would relax ``require_auth``'s
second gate, and these tests must never run against a relaxed one even by
accident.
WHAT IS COVERED
---------------
1. ``TestPasswordChangeRevokesTheOtherDevice`` — A and B logged in, B
changes the password, then the account is REOPENED by a third login
under the new password. A's captured cookie must still be refused, and
refused by the session gate.
2. ``TestRevokedSessionCannotReplayItsBootstrapToken`` — the
``temp_auth_token`` question. It is a plaintext SQLCipher password
sitting in a process-global store, addressed by a token that lives in
the client's cookie. Nothing in ``logout`` or ``change_password``
purges ``temp_auth_store``; the ONLY thing standing between a revoked
cookie and a freshly decrypted database is the ordering inside
``DatabaseMiddleware`` (``_enforce_session_revocation`` clears the
session dict BEFORE ``ensure_user_database`` reads
``temp_auth_token`` out of it). This pins the ordering as an
observable property — with a positive control proving the token
really can bootstrap a closed database, so the negative half cannot
pass by the token being dead.
3. ``TestRequestAlreadyInFlightWhenTheSessionIsDestroyed`` — the "is
there a window?" question, answered without any wall-clock timing: a
request is parked INSIDE the handler (past ``require_auth``) on a
real ``threading.Event``, the session is destroyed from the test
thread, and only then is the handler released.
4. ``TestLookalikeUsernamesGetSeparateDatabases`` — the collision
question. ``get_user_database_filename`` is
``sha256(username)[:16]`` — 64 bits, and the username is fed in
RAW (no case folding, no NFKC). Both halves are asserted: the raw
feed is what keeps lookalikes apart (a normalising layer added
"for convenience" would merge them), and end to end two accounts
differing by one character's case must not share a database file
or a key.
5. ``TestConcurrentRegistrationOfTheSameUsername`` — two clients racing
the same username through ``POST /auth/register``. The check
(``user_exists``) and the act (the ``User`` INSERT) are not atomic;
the ``IntegrityError`` branch is what makes the loser lose. Asserted
on effects: one auth row, one database file, and only the WINNER's
password opens it.
6. ``TestThereIsNoPasswordResetPath`` — "does password reset invalidate
what it should?" has an architectural answer: there is no reset,
because the password IS the SQLCipher key and nothing derived from it
is stored. Pinned so a future "forgot password" route cannot be added
without this failing and forcing the design question.
DELIBERATELY NOT DUPLICATED (surveyed, already covered)
------------------------------------------------------
* Registration charset / path-safety corpus, including NUL, traversal
and trailing whitespace, and the accepted-Unicode control:
``tests/security/test_logout_and_registration_policy_fastapi.py``.
Homoglyph confusability is documented there as a known non-goal of the
charset check; item 4 here asks the different question of whether it
can produce a shared DATABASE.
* Forged / truncated / bit-flipped session cookies, the server-side idle
deadline, and logout's single-session scope (three of which are strict
xfails recording the deliberate multi-device trade-off):
``tests/web/test_auth_session_lifecycle.py``.
* ``require_auth``'s destroyed-session rejection as a unit, and the
``temp_auth_token`` CROSS-USER binding (``stored_username ==
username``): ``tests/web/dependencies/test_session_revocation.py``,
``tests/security/test_auth_credential_lifetime_fastapi.py``.
* Wrong-current-password change refusal, and socket teardown scope on
logout vs change-password:
``tests/security/test_logout_and_registration_policy_fastapi.py``.
HARNESS
-------
The ``live_app`` idiom is copied from
``tests/security/test_auth_credential_lifetime_fastapi.py`` /
``tests/web/test_auth_session_lifecycle.py``: the routes read module-level
singletons (``db_manager``, ``session_manager``, ``temp_auth_store``), so
the app must run against those exact instances and the data dir has to be
repointed on the singleton itself.
"""
from __future__ import annotations
import base64
import hashlib
import json
import re
import threading
import unicodedata
import uuid
import pytest
from fastapi.testclient import TestClient
# Every rejection asserted in this module is the server-side-session gate
# doing its job. The autouse ``_legacy_bare_username_auth`` fixture in
# tests/conftest.py patches ``dependencies.auth._server_session_valid`` to
# accept unconditionally so the many legacy bare-username route tests keep
# working — which is exactly the gate under test here. Opt out wholesale;
# without this marker the negative halves below would be unprovable and
# several would pass while the gate was deleted.
pytestmark = pytest.mark.real_session_check
OLD_PASSWORD = "AttackScenarioPass1" # noqa: S105
NEW_PASSWORD = "AttackScenarioPass2" # noqa: S105
OTHER_PASSWORD = "AttackScenarioPass3" # noqa: S105
# How long a helper thread may block before the test gives up. Only ever
# used as a deadlock guard (an expired wait fails the test loudly); no
# assertion below is a statement ABOUT elapsed time.
TRIP_TIMEOUT = 30.0
# The auth templates render flashes into ``alert`` divs. Matching on the
# raw page text is useless — register.html embeds the same validation
# strings in its client-side JS, so ``"..." in resp.text`` matches on any
# render of the page. See the same note in
# tests/security/test_logout_and_registration_policy_fastapi.py.
_FLASH_RE = re.compile(r'<div class="alert[^"]*"[^>]*>\s*([^<]+?)\s*<')
def _flashed(html: str) -> list[str]:
return [m.strip() for m in _FLASH_RE.findall(html)]
# ---------------------------------------------------------------------------
# Harness
# ---------------------------------------------------------------------------
@pytest.fixture
def live_app(tmp_path, monkeypatch):
"""The real assembled FastAPI app on a throwaway data directory."""
monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path))
monkeypatch.setenv("LDR_TESTING_WITH_MOCKS", "true")
monkeypatch.setenv("LDR_DISABLE_RATE_LIMITING", "true")
# Production PBKDF2 rounds (256000) would dominate wall-clock: this
# module creates several real SQLCipher databases. sqlcipher_utils
# declares MIN_KDF_ITERATIONS_TESTING=1 specifically to allow this.
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
from local_deep_research.web.dependencies.rate_limit import limiter
import local_deep_research.web.routers.auth as auth_routes
from local_deep_research.web.fastapi_app import app as fastapi_app
# The env var above is read at import time, so a module imported by an
# earlier test keeps its old flag. Force it here: several scenarios log
# in more times than the 5-per-15-minutes /auth/login cap allows, and a
# 429 would masquerade as the refusal each test is asserting.
original_limiter_enabled = limiter.enabled
limiter.enabled = False
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),
# which would otherwise open the user database concurrently with
# the assertions below.
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
limiter.enabled = original_limiter_enabled
@pytest.fixture
def store_cleanup():
"""Drop this module's entries from the process-global credential
singletons afterwards.
``session_password_store`` and ``temp_auth_store`` are module-level
singletons that ``reset_all_singletons`` does not touch, so a leaked
plaintext password would be visible to every later test in the same
worker.
"""
usernames: list[str] = []
yield usernames.append
from local_deep_research.database.session_passwords import (
session_password_store,
)
from local_deep_research.web.auth.session_manager import session_manager
for username in usernames:
session_password_store.clear_all_for_user(username)
session_manager.destroy_all_user_sessions(username)
def _client(app) -> TestClient:
"""A TestClient with its own cookie jar and its own peer address."""
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}.7"
)
}
)
return client
def _csrf(client: TestClient) -> 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: TestClient, username: str, password: str):
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: TestClient, username: str, password: str):
token = _csrf(client)
return client.post(
"/auth/login",
data={
"username": username,
"password": password,
"remember": "false",
"csrf_token": token,
},
headers={"X-CSRFToken": token},
follow_redirects=False,
)
def _change_password(client: TestClient, current: str, new: str):
token = _csrf(client)
return client.post(
"/auth/change-password",
data={
"current_password": current,
"new_password": new,
"confirm_password": new,
"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.
Read-only observation of what the server put in the cookie. The
signature is deliberately not verified here — the server's own
acceptance of the cookie is what the assertions are about.
"""
raw = client.cookies.get("session")
# "null" is Starlette's deletion sentinel for a cleared session.
if not raw or raw == "null":
return {}
head = raw.split(".")[0]
return json.loads(base64.b64decode(head + "=" * (-len(head) % 4)))
def _probe(client: TestClient):
"""``GET /auth/integrity-check`` as an API caller.
``/auth/integrity-check`` is a real ``Depends(require_auth)`` route
that opens the user's encrypted database and echoes the username
back, so a 200 is proof of genuine authenticated access rather than
of a page rendering. Sending ``Accept: application/json`` makes
``_is_api_request`` true, so a 401 comes back as JSON carrying
``require_auth``'s ``detail`` instead of being rewritten into a 302
to the login page — and that detail string is the only thing that
distinguishes the session gate from the DB-connection gate.
"""
return client.get(
"/auth/integrity-check",
headers={"Accept": "application/json"},
follow_redirects=False,
)
def _assert_authenticated(client: TestClient, username: str, why: str) -> None:
"""Positive control: this client has real authenticated access."""
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 = _probe(client)
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_refused_by_the_session_gate(
client: TestClient, username: str, why: str
) -> None:
"""The specific refusal: 401 ``Authentication required``.
Two probes, because the two routes are guarded by different things
and a regression can take out either one:
* ``/auth/check`` must answer anonymous callers with JSON, so it calls
``require_auth`` itself and converts the 401. A revoked cookie is
refused there first by ``fastapi_app._enforce_session_revocation``.
* ``/auth/integrity-check`` does use ``require_auth``, and reaches
the encrypted database.
NOT a bare ``!= 200``. ``require_auth`` has two distinct 401s and
only one of them means revocation worked:
* ``"Database connection required"`` — the username-scoped
``is_user_connected`` check fired. That refusal evaporates the
moment anyone, on any device, logs in again, so a test that
accepts it proves nothing about revocation.
* ``"Authentication required"`` — the cookie's ``session_id`` no
longer resolves to this username, so either
``_enforce_session_revocation`` already emptied the session dict
upstream or ``_server_session_valid`` rejected it. This is the
refusal that survives the account being reopened.
"""
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 = _probe(client)
assert probe.status_code == 401, (
f"{why}: /auth/integrity-check answered {probe.status_code}, "
f"expected 401 — {probe.text[:300]}"
)
assert probe.json() == {"detail": "Authentication required"}, (
f"{why}: refused, but not by the server-side session gate — "
f"{probe.json()!r}. A 'Database connection required' detail here "
"means the only thing refusing this cookie is that the database "
"happens to be closed, which stops being true as soon as anyone "
"logs in again"
)
assert username not in probe.text
def _auth_rows(username: str) -> int:
from local_deep_research.database.auth_db import auth_db_session
from local_deep_research.database.models.auth import User
with auth_db_session() as db:
return db.query(User).filter_by(username=username).count()
def _db_file(username):
from local_deep_research.config.paths import get_user_database_filename
from local_deep_research.database.encrypted_db import db_manager
return db_manager.data_dir / get_user_database_filename(username)
def _unique(prefix: str) -> str:
return f"{prefix}{uuid.uuid4().hex[:10]}"
@pytest.fixture
def registered_user(live_app, store_cleanup):
"""A registered user whose bootstrap client has been discarded.
Returns ``(app, username)``. The registering client is simply dropped
rather than logged out: ``logout`` calls ``clear_all_for_user`` and
closes the database, and several scenarios below need to control that
teardown themselves.
"""
app = live_app
username = _unique("atk")
store_cleanup(username)
bootstrap = _client(app)
resp = _register(bootstrap, username, OLD_PASSWORD)
assert resp.status_code == 302, (
f"registration bootstrap failed: {resp.status_code} {resp.text[:400]}"
)
return app, username
# ---------------------------------------------------------------------------
# 1. Credential change while another session is live
# ---------------------------------------------------------------------------
class TestPasswordChangeRevokesTheOtherDevice:
"""Change the password on device B; device A must lose access — and
must stay locked out after the account is reopened.
The second half is the part with no equivalent anywhere on this
branch. The route runs ``destroy_all_user_sessions`` +
``clear_all_for_user`` after a rekey that has already detached the
user's cached engine, and a test that stops there cannot tell
which of those three produced the 401. Two of them are undone by the
very next login — including the legitimate one the user performs
thirty seconds later with their new password. Only the destroyed
server-side session record is permanent, so that is what has to be
observed.
"""
def test_the_other_device_is_refused_by_the_session_gate(
self, registered_user
):
from local_deep_research.database.encrypted_db import db_manager
app, username = registered_user
client_a = _client(app)
assert _login(client_a, username, OLD_PASSWORD).status_code == 302
client_b = _client(app)
assert _login(client_b, username, OLD_PASSWORD).status_code == 302
# Positive controls: BOTH devices genuinely work first, so every
# refusal below is caused by the password change and not by a
# broken fixture.
_assert_authenticated(client_a, username, "device A before the change")
_assert_authenticated(client_b, username, "device B before the change")
# The cookie an attacker would have captured from device A: taken
# in steady state, after the one-shot bootstrap token has already
# been consumed, so nothing below depends on that token.
stolen = client_a.cookies.get("session")
assert stolen and stolen != "null"
assert "temp_auth_token" not in _session_payload(client_a), (
"premise: the bootstrap token must already be consumed, or "
"this scenario would be testing token replay instead"
)
change = _change_password(client_b, OLD_PASSWORD, NEW_PASSWORD)
assert change.status_code == 302, (
f"password change failed: {change.status_code} {change.text[:400]}"
)
assert change.headers.get("location") == "/auth/login"
# Device A, still holding a perfectly valid signed cookie.
_assert_refused_by_the_session_gate(
client_a, username, "device A immediately after the change"
)
# --- The state that defeats every username-scoped check: the
# account is REOPENED. This is not contrived — it is what the
# user does next, and it restores `is_user_connected` and
# repopulates the session password store, which is exactly what
# the other two teardowns in change_password relied on.
client_c = _client(app)
assert _login(client_c, username, NEW_PASSWORD).status_code == 302
_assert_authenticated(client_c, username, "the user's new session")
assert db_manager.is_user_connected(username), (
"premise: the account must be reopened, or the replay below "
"would be refused by the DB-closed check and prove nothing"
)
_assert_refused_by_the_session_gate(
client_a,
username,
"device A after the account was reopened under the new password",
)
replay = _client(app)
replay.cookies.set("session", stolen)
_assert_refused_by_the_session_gate(
replay,
username,
"device A's captured cookie replayed from a fresh client after "
"the account was reopened",
)
# And the credential itself is dead: the old password no longer
# opens the rekeyed database.
stale = _client(app)
assert _login(stale, username, OLD_PASSWORD).status_code == 401, (
"the pre-change password still logs in — the SQLCipher rekey "
"did not take"
)
# ---------------------------------------------------------------------------
# 2. The temp_auth_token bootstrap credential
# ---------------------------------------------------------------------------
class TestRevokedSessionCannotReplayItsBootstrapToken:
"""``temp_auth_token`` is a live plaintext SQLCipher password behind a
token that rides in the client's cookie.
``POST /auth/login`` mints one and puts it in the session; it is
consumed by ``ensure_user_database`` on the first request that is not
under ``DatabaseMiddleware._skip_prefixes`` (``/auth/login``,
``/auth/register`` and ``/auth/csrf-token`` all are, so a cookie
captured straight after login still carries an UNSPENT one).
Nothing revokes it. ``logout`` and ``change_password`` clear
``session_password_store`` and ``thread_local_session``; neither
touches ``temp_auth_store``, and ``session_manager.destroy_session``
obviously cannot. The only thing preventing a revoked cookie from
spending its token is the ORDER of two calls inside
``DatabaseMiddleware.__call__``: ``_enforce_session_revocation``
empties the session dict before ``ensure_user_database`` gets to read
``temp_auth_token`` out of it. Reverse those two lines and a revoked
cookie decrypts the user's database and promotes a 10-second
credential into a 24-hour one.
Both halves are asserted, because either alone is worthless: the
positive control proves the token really can bootstrap a CLOSED
database (so the negative half is not passing because the token was
already dead), and the negative half proves the revoked cookie
cannot, while the token is still demonstrably live in the store.
"""
def test_a_destroyed_session_cannot_spend_its_token(
self, registered_user, monkeypatch
):
from local_deep_research.database.encrypted_db import db_manager
from local_deep_research.database.session_passwords import (
session_password_store,
)
from local_deep_research.database.temp_auth import temp_auth_store
from local_deep_research.web.auth.session_manager import (
session_manager,
)
app, username = registered_user
# The store's 10s TTL is a wall clock this test must not race.
# Widen it: nothing here is a statement about the TTL, and a
# token that quietly expired mid-test would turn the negative
# assertion below into a tautology.
monkeypatch.setattr(temp_auth_store, "ttl", 3600)
# Two logins => two independent, unspent bootstrap tokens. One is
# spent by the positive control; the other is the one replayed
# after revocation.
control = _client(app)
assert _login(control, username, OLD_PASSWORD).status_code == 302
control_payload = _session_payload(control)
control_cookie = control.cookies.get("session")
victim = _client(app)
assert _login(victim, username, OLD_PASSWORD).status_code == 302
victim_payload = _session_payload(victim)
victim_cookie = victim.cookies.get("session")
control_token = control_payload.get("temp_auth_token")
victim_token = victim_payload.get("temp_auth_token")
victim_sid = victim_payload.get("session_id")
assert control_token and victim_token and victim_sid
assert control_token != victim_token
assert temp_auth_store.peek_auth(control_token) == (
username,
OLD_PASSWORD,
)
assert temp_auth_store.peek_auth(victim_token) == (
username,
OLD_PASSWORD,
)
def _strip_every_other_credential() -> None:
"""Leave the bootstrap token as the ONLY way back in."""
db_manager.close_user_database(username)
session_password_store.clear_all_for_user(username)
assert not db_manager.is_user_connected(username)
# --- POSITIVE CONTROL. Database closed, password store empty:
# the token alone must be able to reopen the encrypted database
# and authenticate. If this stops holding, the negative half
# below stops meaning anything.
_strip_every_other_credential()
control_replay = _client(app)
control_replay.cookies.set("session", control_cookie)
_assert_authenticated(
control_replay,
username,
"a cookie carrying an unspent bootstrap token, database closed",
)
assert db_manager.is_user_connected(username), (
"the bootstrap token did not actually reopen the database, so "
"the negative case below would prove nothing"
)
assert (
session_password_store.get_session_password(
username, control_payload["session_id"]
)
== OLD_PASSWORD
), (
"the token was consumed but its password was not promoted into "
"the session store — the control is not exercising the path "
"the negative case must be blocked from"
)
assert temp_auth_store.peek_auth(control_token) is None, (
"a spent bootstrap token is still retrievable from the store"
)
# --- NEGATIVE. Revoke the victim's session server-side (what
# logout, a password change, or the idle sweeper each do), then
# strip the other credentials again so the token is once more the
# only way in — and replay.
session_manager.destroy_session(victim_sid)
assert session_manager.validate_session(victim_sid) is None
_strip_every_other_credential()
assert temp_auth_store.peek_auth(victim_token) == (
username,
OLD_PASSWORD,
), (
"premise: revocation left the token live in temp_auth_store "
"(nothing purges it), which is why the middleware ordering is "
"load-bearing. If this ever fails because a purge was added, "
"delete this assertion — do not relax the ones below"
)
attacker = _client(app)
attacker.cookies.set("session", victim_cookie)
replayed = attacker.get("/auth/check")
# SIDE EFFECTS FIRST, deliberately. The status code is the least
# interesting thing about this request: refusing to ANSWER while
# having already decrypted the database and promoted the
# credential would still be the vulnerability. Asserting these
# before the status code means a regression is reported as "the
# database was reopened" rather than as "expected 401, got 200".
assert not db_manager.is_user_connected(username), (
"SECURITY: replaying a revoked session cookie re-opened the "
"user's encrypted database. _enforce_session_revocation must "
"clear the session dict BEFORE ensure_user_database reads "
"temp_auth_token out of it"
)
assert (
session_password_store.get_session_password(username, victim_sid)
is None
), (
"SECURITY: a revoked session cookie promoted its 10-second "
"bootstrap credential into the 24-hour session password store"
)
assert temp_auth_store.peek_auth(victim_token) == (
username,
OLD_PASSWORD,
), "the revoked replay consumed the token, so it reached the store"
# ...and only then, the answer the attacker got.
assert replayed.status_code == 401, (
"a revoked cookie carrying an unspent bootstrap token was "
f"answered {replayed.status_code}: {replayed.text[:300]}"
)
assert replayed.json() == {"authenticated": False}
assert username not in replayed.text
# The same replay against a route that DOES use require_auth, from
# a client whose cookie has not yet been cleared by a response
# (the probe above cleared ``attacker``'s).
second = _client(app)
second.cookies.set("session", victim_cookie)
probe = _probe(second)
assert probe.status_code == 401, (
"a revoked cookie carrying an unspent bootstrap token reached "
f"/auth/integrity-check: {probe.status_code} {probe.text[:300]}"
)
assert probe.json() == {"detail": "Authentication required"}
assert username not in probe.text
assert not db_manager.is_user_connected(username), (
"SECURITY: the second replay re-opened the user's encrypted "
"database"
)
# ---------------------------------------------------------------------------
# 3. Revocation while a request is already in flight
# ---------------------------------------------------------------------------
class TestRequestAlreadyInFlightWhenTheSessionIsDestroyed:
"""Is there a window where a destroyed session still gets served?
Answered structurally rather than by timing. ``require_auth`` runs
once, at dependency resolution; the handler then proceeds with no
further checks. This parks a request INSIDE
``/auth/integrity-check``'s handler — past the gate, before the
response — on a real ``threading.Event``, destroys the session from
the test thread, and only then releases it.
The recorded behaviour (the in-flight request completes with full
authority) is CHARACTERISATION, not an endorsement: it is inherent to
a per-request gate and matches how the Flask original behaved. What
matters, and what is asserted as a security property, is that the
window closes at the response boundary — the very next request on the
same cookie is refused by the session gate — and that the window
cannot be held open by simply not finishing.
"""
def test_the_window_closes_at_the_response_boundary(
self, registered_user, monkeypatch
):
from local_deep_research.database.encrypted_db import db_manager
from local_deep_research.web.auth.session_manager import (
session_manager,
)
app, username = registered_user
client = _client(app)
assert _login(client, username, OLD_PASSWORD).status_code == 302
_assert_authenticated(client, username, "before anything is destroyed")
session_id = _session_payload(client)["session_id"]
assert session_manager.validate_session(session_id) == username
entered = threading.Event()
release = threading.Event()
real_check = db_manager.check_database_integrity
def _parked(target_username):
entered.set()
# A blown deadline surfaces as a 500 from the handler, which
# the assertions below report — never as a silent hang.
assert release.wait(TRIP_TIMEOUT), "handler was never released"
return real_check(target_username)
monkeypatch.setattr(db_manager, "check_database_integrity", _parked)
captured: dict = {}
def _drive():
try:
captured["resp"] = _probe(client)
except BaseException as exc: # noqa: BLE001 - reported below
captured["exc"] = exc
thread = threading.Thread(target=_drive, name="in-flight-probe")
thread.start()
try:
assert entered.wait(TRIP_TIMEOUT), (
"the request never reached the handler, so it was never "
"actually in flight"
)
# It is past require_auth and blocked. Revoke it now.
session_manager.destroy_session(session_id)
assert session_manager.validate_session(session_id) is None
finally:
release.set()
thread.join(TRIP_TIMEOUT)
assert not thread.is_alive(), "the in-flight request never completed"
assert "exc" not in captured, f"probe raised: {captured.get('exc')!r}"
resp = captured["resp"]
# CHARACTERISATION: authorisation is decided once, on entry.
assert resp.status_code == 200, (
"a request that had already passed require_auth did not "
f"complete: {resp.status_code} {resp.text[:300]}"
)
assert resp.json()["username"] == username
# SECURITY PROPERTY: the window is exactly one request wide.
monkeypatch.setattr(db_manager, "check_database_integrity", real_check)
assert db_manager.is_user_connected(username), (
"premise: the database is still open, so the refusal below "
"cannot be the DB-closed one"
)
_assert_refused_by_the_session_gate(
client,
username,
"the same client's next request after its session was destroyed "
"mid-flight",
)
# ---------------------------------------------------------------------------
# 4. Two accounts, one database file?
# ---------------------------------------------------------------------------
# Pairs of usernames a human reads as the same string. Each is accepted by
# registration's charset guard (``str.isalnum()`` is Unicode-aware, and
# nothing lowercases), so each pair CAN exist as two accounts at once.
_LOOKALIKE_PAIRS = [
pytest.param(lambda s: (f"twin{s}", f"Twin{s}"), id="ascii-case"),
pytest.param(
# U+0430 CYRILLIC SMALL LETTER A in place of ASCII "a".
lambda s: (f"admin{s}", f"аdmin{s}"),
id="cyrillic-homoglyph",
),
pytest.param(
# U+FF41 FULLWIDTH LATIN SMALL LETTER A; NFKC folds it to "a".
lambda s: (f"admin{s}", f"admin{s}"),
id="fullwidth-nfkc",
),
]
class TestLookalikeUsernamesGetSeparateDatabases:
"""``sha256(username)[:16]`` is 64 bits, and the username goes in RAW.
Two things could merge two accounts onto one database file: a hash
collision (64 bits — not reachable, and not what this tests), or a
normalisation step upstream of the hash. The second is the real
hazard, and it is a plausible future "convenience" change: case-fold
usernames so ``Alice`` can log in as ``alice``, or NFKC-normalise
them to defeat homoglyph registration. Either one, applied at the
hash without also being applied at the auth-DB uniqueness check,
silently points two DISTINCT accounts at one SQLCipher file — and
then the second account's password fails to open the first's data,
or worse, succeeds.
"""
@pytest.mark.parametrize("pair", _LOOKALIKE_PAIRS)
def test_the_filename_hash_sees_the_raw_username(self, pair):
"""Free (no database): the digest must not be normalised."""
from local_deep_research.config.paths import (
get_user_database_filename,
)
left, right = pair("x1")
assert left != right
left_name = get_user_database_filename(left)
right_name = get_user_database_filename(right)
assert left_name != right_name, (
f"{left!r} and {right!r} resolve to the SAME database file "
f"({left_name}) — two accounts would share one SQLCipher "
"database"
)
# Pin WHY they differ, so a normalising layer added later fails
# here rather than silently merging the pair: the digest is over
# the raw UTF-8 bytes, and the folded forms would collide.
assert left_name == "ldr_user_{}.db".format(
hashlib.sha256(left.encode()).hexdigest()[:16]
)
folded_left = unicodedata.normalize("NFKC", left).casefold()
folded_right = unicodedata.normalize("NFKC", right).casefold()
if folded_left == folded_right:
assert get_user_database_filename(
folded_left
) == get_user_database_filename(folded_right), (
"sanity: the folded forms are equal, so they must hash "
"equal — this is the collision the raw hash avoids"
)
def test_the_hash_is_truncated_to_64_bits(self):
"""Document the truncation the filename scheme relies on.
Not a defect on its own — the digest is over a value the auth
database already guarantees is unique, so a collision needs a
deliberate second-preimage against a 64-bit prefix rather than a
birthday search over registered users. It is pinned because the
blast radius if it ever DID collide is two users sharing one
encrypted database, so a future change to this scheme should be
a conscious one.
"""
from local_deep_research.config.paths import (
get_user_database_filename,
)
name = get_user_database_filename("some_user")
digest = re.fullmatch(r"ldr_user_([0-9a-f]+)\.db", name)
assert digest, name
assert len(digest.group(1)) == 16, (
"the user database filename no longer carries a 16-hex-char "
"(64-bit) truncated digest"
)
def test_case_differing_accounts_do_not_share_a_database(
self, live_app, store_cleanup
):
"""End to end: register both, prove the files and keys are apart.
The strongest available proof that the two accounts do not share
a database is the encryption itself — each account's password is
its SQLCipher key, so if they shared a file, one account's
password would open the other's. Asserted in both directions,
each with the matching positive control.
"""
from local_deep_research.database.encrypted_db import db_manager
app = live_app
suffix = uuid.uuid4().hex[:8]
lower = f"twin{suffix}"
upper = f"Twin{suffix}"
store_cleanup(lower)
store_cleanup(upper)
first = _client(app)
assert _register(first, lower, OLD_PASSWORD).status_code == 302, (
"registering the lowercase username failed"
)
second = _client(app)
resp = _register(second, upper, OTHER_PASSWORD)
assert resp.status_code == 302, (
f"the case-differing username was refused as a duplicate "
f"({resp.status_code}) — flashed {_flashed(resp.text)!r}. If "
"registration became case-insensitive this test should be "
"rewritten to assert THAT, not deleted"
)
# Two accounts, two files.
assert _auth_rows(lower) == 1 and _auth_rows(upper) == 1
lower_file, upper_file = _db_file(lower), _db_file(upper)
assert lower_file != upper_file, (
f"SECURITY: {lower!r} and {upper!r} share one database file "
f"({lower_file})"
)
assert lower_file.exists() and upper_file.exists()
# Each client is who it says it is.
_assert_authenticated(first, lower, "the lowercase account")
_assert_authenticated(second, upper, "the uppercase account")
# The keys are separate: neither password opens the other's
# database, and each still opens its own (the positive control
# that stops a blanket login failure from passing this).
for username, own, foreign in (
(lower, OLD_PASSWORD, OTHER_PASSWORD),
(upper, OTHER_PASSWORD, OLD_PASSWORD),
):
cross = _client(app)
assert _login(cross, username, foreign).status_code == 401, (
f"SECURITY: the other lookalike account's password opened "
f"{username!r}'s database — the two share one SQLCipher key"
)
good = _client(app)
assert _login(good, username, own).status_code == 302, (
f"control: {username!r} can no longer log in with its own "
"password, so the cross-login refusal above proves nothing"
)
assert db_manager.is_user_connected(username)
# ---------------------------------------------------------------------------
# 5. Two clients racing one username
# ---------------------------------------------------------------------------
class TestConcurrentRegistrationOfTheSameUsername:
"""``user_exists()`` and the ``User`` INSERT are not one atomic step.
``POST /auth/register`` checks ``db_manager.user_exists(username)``,
then — several validation branches later — inserts the row. Two
requests can both pass the check. The unique index on
``users.username`` is what actually decides, and the
``except IntegrityError`` branch is what turns the loser's crash into
a 400 without provisioning anything.
The security question is not who wins but whether BOTH can partially
succeed: the winner's row plus the loser's ``create_user_database``
would mean the account exists with the LOSER's password as its
SQLCipher key. Asserted on effects — one row, one file, and only the
winner's password opens it.
"""
def test_exactly_one_registration_takes_effect(
self, live_app, store_cleanup
):
app = live_app
username = _unique("race")
store_cleanup(username)
first = _client(app)
second = _client(app)
# CSRF tokens are fetched BEFORE the barrier so the race is over
# the register POST itself and not over two GETs.
tokens = {
"first": _csrf(first),
"second": _csrf(second),
}
assert tokens["first"] and tokens["second"]
barrier = threading.Barrier(2, timeout=TRIP_TIMEOUT)
results: dict = {}
def _attempt(label: str, client: TestClient, password: str) -> None:
token = tokens[label]
try:
barrier.wait()
results[label] = client.post(
"/auth/register",
data={
"username": username,
"password": password,
"confirm_password": password,
"acknowledge": "true",
"csrf_token": token,
},
headers={"X-CSRFToken": token},
follow_redirects=False,
)
except BaseException as exc: # noqa: BLE001 - reported below
results[label] = exc
threads = [
threading.Thread(
target=_attempt, args=("first", first, OLD_PASSWORD)
),
threading.Thread(
target=_attempt, args=("second", second, OTHER_PASSWORD)
),
]
for thread in threads:
thread.start()
for thread in threads:
thread.join(TRIP_TIMEOUT)
assert not thread.is_alive(), "a registration thread hung"
assert set(results) == {"first", "second"}, results
for label, result in results.items():
assert not isinstance(result, BaseException), (
f"the {label} registration raised: {result!r}"
)
passwords = {"first": OLD_PASSWORD, "second": OTHER_PASSWORD}
winners = [
label for label, resp in results.items() if resp.status_code == 302
]
assert len(winners) == 1, (
"SECURITY: both concurrent registrations of the same username "
"reported success — "
f"{ {k: v.status_code for k, v in results.items()} }"
)
winner = winners[0]
loser = "second" if winner == "first" else "first"
assert results[loser].status_code == 400, (
"the losing registration was not refused by the duplicate-"
f"username branch: {results[loser].status_code}. A 500 here "
"means the IntegrityError raised by the unique index reached "
"the generic handler instead of the branch written for it"
)
assert any(
"Registration failed" in message
for message in _flashed(results[loser].text)
), (
"the loser's 400 did not come from the duplicate-username "
f"branch — flashed {_flashed(results[loser].text)!r}"
)
# Exactly one account, exactly one database file.
assert _auth_rows(username) == 1, (
f"the race left {_auth_rows(username)} auth rows for one username"
)
assert _db_file(username).exists()
# And the file is keyed to the WINNER. This is the assertion that
# would catch both halves partially succeeding: if the loser's
# create_user_database had also run, its password would open the
# account the winner believes it owns.
loser_client = _client(app)
assert (
_login(loser_client, username, passwords[loser]).status_code == 401
), (
"SECURITY: the losing registration's password opens the "
"account. Both requests provisioned, and the loser's "
"SQLCipher key is live on the winner's account"
)
winner_client = _client(app)
assert (
_login(winner_client, username, passwords[winner]).status_code
== 302
), (
"control: the winning registration's password does not log in, "
"so the refusal above proves nothing"
)
_assert_authenticated(winner_client, username, "the winning account")
# ---------------------------------------------------------------------------
# 6. There is no password reset, by design
# ---------------------------------------------------------------------------
class TestThereIsNoPasswordResetPath:
"""Password reset: there is nothing to reset, by design.
The password IS the SQLCipher key. ``User`` stores no hash, no salt
and no recovery token (its docstring says so explicitly), and
registration makes the user acknowledge that recovery is impossible.
A reset route could therefore only work by re-keying the database,
which needs the old password — i.e. it would be
``/auth/change-password`` — or by discarding the user's data.
Pinned as a route-table and schema assertion so that adding a
"forgot password" flow fails here and forces the design question,
rather than shipping something that mints access without the old key.
"""
def test_no_route_offers_a_reset_or_recovery_flow(self, live_app):
forbidden = ("reset", "forgot", "recover")
offenders = sorted(
{
path
for path in (
getattr(route, "path", "") for route in live_app.routes
)
if "password" in path.lower()
and any(word in path.lower() for word in forbidden)
}
)
assert not offenders, (
f"a password reset/recovery route appeared: {offenders}. The "
"password is the SQLCipher key and nothing derived from it is "
"stored, so such a route can only work by re-keying with the "
"OLD password (that is /auth/change-password) or by destroying "
"the user's data. Decide which, deliberately"
)
# Control: the route table really was inspected and does contain
# the credential-change route this is asserting is the only one.
paths = {getattr(route, "path", "") for route in live_app.routes}
assert "/auth/change-password" in paths, (
"the route table scan found no /auth/change-password, so the "
"negative assertion above was made against the wrong object"
)
def test_the_auth_database_stores_nothing_that_could_verify_a_password(
self,
):
from local_deep_research.database.models.auth import User
columns = {column.name for column in User.__table__.columns}
assert columns == {
"id",
"username",
"created_at",
"last_login",
"database_version",
}, (
f"the users table grew columns: {sorted(columns)}. Anything "
"password-derived stored here would be a second, weaker "
"authentication path alongside the SQLCipher decrypt"
)
assert not hasattr(User, "set_password")
assert not hasattr(User, "check_password")