~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-route coverage the Flask -> FastAPI migration dropped on the floor.
The migration deleted ``tests/auth_tests/test_auth_routes.py`` (22 tests) and
``tests/auth_tests/test_auth_integration.py`` (5 tests). Most of what they
pinned was re-established elsewhere on this branch (see the SURVEY below).
This file restores the remainder — the assertions with no branch equivalent
at all.
SURVEY — already covered on this branch, deliberately NOT duplicated here
------------------------------------------------------------------------
* ``tests/web/routers/test_fastapi_migration.py`` — ``/`` redirects an
unauthenticated caller to ``/auth/login``; ``GET /auth/login`` and
``GET /auth/register`` render.
* ``tests/security/test_login_cached_connection_password_lockout.py`` /
``..._route.py`` — register -> logout -> re-login end to end, the warm-cache
wrong-password rejection, and lockout accounting.
* ``tests/web/routers/test_account_lockout_route.py`` — a wrong password is a
plain 401 up to the lockout threshold.
* ``tests/web/routers/test_auth_flow_gaps.py`` — logout destroys the
server-side session and clears the cookie; login rotates the session id.
* ``tests/web/test_registration_orphan_cleanup.py`` /
``test_registration_session_rollback.py`` — the two registration failure
paths that touch the AUTH-DB row and the half-built session.
* ``tests/web/test_session_cookie_behavior.py`` — "remember me" as a cookie
Max-Age (Flask's ``session.permanent`` has no Starlette analogue).
* ``tests/web/test_long_integration_flows_followup.py`` — the whole
change-password lifecycle (rekey, other sessions killed, old password
dead, new password works).
* ``tests/security/test_login_required_boundaries.py`` — unauthenticated API
endpoints answer JSON 401.
WHAT IS RESTORED HERE
---------------------
1. Registration input validation. Nothing on this branch asserts that a bad
username / mismatched password / missing acknowledgement is rejected at
all, let alone that it creates no account. A regression here mints
accounts from malformed input.
2. Duplicate-username handling — including the account-enumeration defence
(a generic message) and, more importantly, that a colliding registration
cannot take over the incumbent's account.
3. The ``allow_registrations = False`` gate on both ``GET`` and ``POST``
``/auth/register``. Branch tests cover the *config loader* that produces
the flag; nothing covered the route that is supposed to honour it.
4. On-disk cleanup when ``create_user_database()`` dies mid-flight, at all
three failure sites, plus recovery from an orphaned ``.salt``. The
``_remove_partial_user_db_files`` helper has a unit test, but nothing
proved the create path actually calls it — and the orphaned-salt recovery
branch (``except FileExistsError``) had no test at all. Both failure
modes brick a username permanently.
HARNESS NOTES
-------------
* ``TestClient(app, raise_server_exceptions=False)`` over the ``app`` fixture
from ``tests/conftest.py`` (function-scoped; points ``LDR_DATA_DIR`` at a
throwaway directory *before* ``fastapi_app`` is imported, and stubs the
post-login background worker).
* CSRF is ASGI middleware, not a config flag — there is no "disable CSRF"
switch, so every POST carries a real token fetched from
``GET /auth/csrf-token`` after ``GET /auth/login`` stamps the session.
* Flask's ``session_transaction()`` has no Starlette equivalent. "Who does
the app think I am?" is answered by ``GET /auth/check`` (``_whoami``),
which is the app's own answer and therefore a stronger check than poking
at session internals. ``_whoami`` returns ``None`` for *any* failure, so
every security-relevant use below asserts POSITIVELY
(``_whoami(c) == expected``) — a bare ``!= victim`` would pass even with
authentication completely broken.
"""
import uuid
import pytest
from fastapi.testclient import TestClient
TEST_PASSWORD = "AuthRoutePass123" # noqa: S105
# ---------------------------------------------------------------------------
# Harness
# ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
def _slowapi_off():
"""Take the per-IP HTTP rate limiter out of the picture for this module.
``REGISTRATION_RATE_LIMIT`` is a per-IP limit, and the validation tests
below issue many register POSTs from one client IP to cover every branch. None of these tests are ABOUT rate limiting (that is
``tests/web/routers/test_auth_rate_limits.py``'s job), so a 429 here is
pure noise that would mask the 400/302 each test actually asserts.
The flag is restored afterwards so no other module inherits the change.
"""
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:
"""A TestClient with its own cookie jar and its own forwarded IP.
Even with slowapi disabled the account-lockout counter is per-username
and some middleware keys off the client IP, so keeping each client on a
distinct peer stops separate test users from sharing a bucket.
"""
client = TestClient(app, raise_server_exceptions=False)
client.headers.update(
{
"X-Forwarded-For": (
f"10.{uuid.uuid4().int % 254 + 1}."
f"{uuid.uuid4().int % 254 + 1}.11"
)
}
)
return client
def _csrf(client: TestClient) -> str:
"""Stamp the session with a CSRF token and hand it back."""
client.get("/auth/login")
resp = client.get("/auth/csrf-token")
return resp.json().get("csrf_token", "") if resp.status_code == 200 else ""
def _whoami(client: TestClient):
"""The username the app believes this client is, or ``None``."""
resp = client.get("/auth/check")
if resp.status_code != 200:
return None
return resp.json().get("username")
def _register(client: TestClient, form: dict):
"""POST /auth/register with `form` plus a live CSRF token."""
data = dict(form)
data["csrf_token"] = _csrf(client)
return client.post("/auth/register", data=data, follow_redirects=False)
def _register_ok(client: TestClient, username: str, password: str):
return _register(
client,
{
"username": username,
"password": password,
"confirm_password": password,
"acknowledge": "true",
},
)
def _login(client: TestClient, username: str, password: str):
return client.post(
"/auth/login",
data={
"username": username,
"password": password,
"csrf_token": _csrf(client),
},
follow_redirects=False,
)
def _logout(client: TestClient):
return client.post(
"/auth/logout",
headers={"X-CSRFToken": _csrf(client)},
follow_redirects=False,
)
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:
return (
auth_db.query(User).filter_by(username=username).first() is not None
)
finally:
auth_db.close()
def _unique(prefix: str) -> str:
return f"{prefix}_{uuid.uuid4().hex[:10]}"
# ---------------------------------------------------------------------------
# 1. Registration input validation
# ---------------------------------------------------------------------------
# (case id, form overrides, expected message fragment)
_INVALID_REGISTRATIONS = [
pytest.param(
{
"username": "",
"password": "",
"confirm_password": "",
"acknowledge": "",
},
"Username is required",
id="empty-form",
),
pytest.param(
{"username": ""},
"Username is required",
id="empty-username",
),
pytest.param(
{"username": " "},
"Username is required",
id="whitespace-username",
),
pytest.param(
{"username": "x"},
"Username must be at least 3 characters",
id="single-char-username",
),
pytest.param(
{"username": "@invalid!user"},
"Username can only contain",
id="invalid-username-characters",
),
pytest.param(
{"confirm_password": "SomethingElse456"},
"Passwords do not match",
id="password-mismatch",
),
pytest.param(
{"acknowledge": "false"},
"You must acknowledge",
id="missing-acknowledgement",
),
pytest.param(
{"password": "short", "confirm_password": "short"},
"Password must be at least 8 characters",
id="weak-password",
),
]
@pytest.mark.parametrize("overrides,expected_message", _INVALID_REGISTRATIONS)
def test_invalid_registration_is_rejected_and_creates_no_account(
app, overrides, expected_message
):
"""Malformed registration input must be refused with HTTP 400 and the
specific reason, and must NOT mint an account.
The status code alone is not enough: a handler that rejected the request
*after* committing the auth row (or after creating the encrypted DB)
would still return 400 while leaving a usable account behind. So each
case also asserts the username is absent from the auth database, absent
from ``user_exists()``, and cannot be logged into.
"""
from local_deep_research.database.encrypted_db import db_manager
username = _unique("badreg")
form = {
"username": username,
"password": TEST_PASSWORD,
"confirm_password": TEST_PASSWORD,
"acknowledge": "true",
}
form.update(overrides)
# Cases that override the username to a fixed bad value keep it; the rest
# keep the unique one so parallel cases can't collide.
attempted_username = form.get("username", "").strip()
client = _client(app)
resp = _register(client, form)
assert resp.status_code == 400, (
f"expected 400 for {overrides!r}, got {resp.status_code}: "
f"{resp.text[:300]}"
)
assert expected_message in resp.text, (
f"the 400 body must say why it was rejected; expected "
f"{expected_message!r} in: {resp.text[:600]}"
)
# Nothing was created: no auth row, no encrypted DB, no session.
if attempted_username:
assert not _auth_row_exists(attempted_username), (
"a rejected registration left an auth-DB row behind — the "
"username is now taken by an account that cannot log in"
)
assert not db_manager.user_exists(attempted_username), (
"a rejected registration created a user database"
)
assert _whoami(client) is None, (
"a rejected registration must not log anybody in"
)
def test_valid_registration_still_succeeds(app):
"""Control for the parametrized rejections above.
Without this, a handler that 400'd on *every* registration would pass
all eight negative cases. This pins that the same form, with nothing
wrong with it, is accepted end to end: 302, an auth row, a real
encrypted database, and an authenticated session.
"""
from local_deep_research.database.encrypted_db import db_manager
username = _unique("goodreg")
client = _client(app)
resp = _register_ok(client, username, TEST_PASSWORD)
assert resp.status_code == 302, (
f"a well-formed registration must be accepted: {resp.status_code} "
f"{resp.text[:400]}"
)
assert _auth_row_exists(username)
assert db_manager.user_exists(username)
assert _whoami(client) == username, (
"registration must also log the new user in"
)
# ---------------------------------------------------------------------------
# 2. Duplicate usernames
# ---------------------------------------------------------------------------
def test_duplicate_username_rejected_without_hijacking_the_account(app):
"""A second registration for an existing username must be refused with a
generic message, and must leave the incumbent account untouched.
Two distinct properties, both security-relevant:
* account enumeration — the rejection must not confirm the username
exists ("already taken" / "already registered" would); and
* account takeover — the far worse failure — a colliding registration
must not re-key the incumbent's encrypted database to the attacker's
password. That is asserted POSITIVELY (the original password still
authenticates and ``/auth/check`` reports the original user) rather
than by the weaker "the attacker isn't logged in".
"""
username = _unique("dupe")
attacker_password = "AttackerPass456" # noqa: S105
owner = _client(app)
assert _register_ok(owner, username, TEST_PASSWORD).status_code == 302
assert _whoami(owner) == username
# Log out so the incumbent's DB connection is cold; the re-login below
# must therefore go through a real decrypt, not a cached engine.
_logout(owner)
# `is None` on its own would pass even with auth entirely broken; it is
# meaningful here only because the same helper is asserted POSITIVELY
# against a real session at the end of this test (and logout's
# server-side teardown has its own coverage in
# tests/web/routers/test_auth_flow_gaps.py).
assert _whoami(owner) is None, "logout must end the incumbent's session"
attacker = _client(app)
dupe = _register_ok(attacker, username, attacker_password)
assert dupe.status_code == 400, (
f"a duplicate username must be refused: {dupe.status_code} "
f"{dupe.text[:400]}"
)
assert "Registration failed. Please try a different username" in dupe.text
lowered = dupe.text.lower()
for leak in ("already exists", "already taken", "already registered"):
assert leak not in lowered, (
f"the duplicate-username rejection leaks account existence "
f"({leak!r}) — it must stay generic to block enumeration"
)
assert _whoami(attacker) is None, (
"a refused registration must not open a session"
)
# The attacker's chosen password must NOT work: the collision did not
# re-key or replace the incumbent's database.
hijack = _login(_client(app), username, attacker_password)
assert hijack.status_code == 401, (
"the duplicate registration's password authenticated — a colliding "
f"registration took over an existing account ({hijack.status_code})"
)
# ...and the original owner's credentials still work.
back = _client(app)
relogin = _login(back, username, TEST_PASSWORD)
assert relogin.status_code == 302, (
f"the incumbent can no longer log in after a duplicate registration "
f"attempt: {relogin.status_code} {relogin.text[:400]}"
)
assert _whoami(back) == username
# ---------------------------------------------------------------------------
# 3. Registrations disabled (allow_registrations = False)
# ---------------------------------------------------------------------------
@pytest.fixture
def registrations_disabled(monkeypatch):
"""Make ``load_server_config()`` report registrations as closed.
Patched on ``web.routers.auth`` — the router imports the symbol into its
own namespace, so patching the definition site would not be seen.
"""
monkeypatch.setattr(
"local_deep_research.web.routers.auth.load_server_config",
lambda: {"allow_registrations": False},
)
def test_register_page_redirects_when_registrations_disabled(
app, registrations_disabled
):
"""GET /auth/register must bounce to the login page when the operator has
closed registrations."""
resp = _client(app).get("/auth/register", follow_redirects=False)
assert resp.status_code == 302
assert "/auth/login" in resp.headers.get("location", "")
def test_register_post_creates_no_user_when_registrations_disabled(
app, registrations_disabled
):
"""POST /auth/register must be refused when registrations are closed —
and, critically, must create nothing.
A redirect that still provisioned the account would look correct to a
browser while completely defeating the setting, so the assertions are on
the auth row, the encrypted database and the session, not just on the
302.
"""
from local_deep_research.database.encrypted_db import db_manager
username = _unique("blocked")
client = _client(app)
resp = _register_ok(client, username, TEST_PASSWORD)
assert resp.status_code == 302
assert "/auth/login" in resp.headers.get("location", "")
assert not _auth_row_exists(username), (
"registration was disabled but an auth-DB row was still created"
)
assert not db_manager.user_exists(username), (
"registration was disabled but a user database was still created"
)
assert _whoami(client) is None, (
"registration was disabled but a session was still opened"
)
# ---------------------------------------------------------------------------
# 4. Half-created databases must never brick a username
# ---------------------------------------------------------------------------
def _requires_sqlcipher():
from local_deep_research.database.encrypted_db import db_manager
if not db_manager.has_encryption:
pytest.skip("salt files only exist on the encrypted (SQLCipher) path")
def _inject_sqlcipher_failure(monkeypatch, calls):
"""Fail the first raw SQLCipher connect — i.e. AFTER the real ``.salt``
has been written by ``create_database_salt()`` but before the ``.db`` is
usable. Exercises the structure-creation cleanup block."""
import local_deep_research.database.encrypted_db as encrypted_db
real = encrypted_db.create_sqlcipher_connection
def _flaky(*args, **kwargs):
calls["n"] += 1
if calls["n"] == 1:
raise RuntimeError("simulated SQLCipher failure")
return real(*args, **kwargs)
monkeypatch.setattr(encrypted_db, "create_sqlcipher_connection", _flaky)
def _inject_engine_failure(monkeypatch, calls):
"""Fail the first SQLAlchemy engine build — the step BETWEEN the
structure-creation and migration cleanup blocks. Unlike the salt path
this one is NOT self-healing: without its own cleanup the orphaned
``.db`` trips ``create_user_database``'s ``db_path.exists()`` guard on
every retry and the username is bricked for good."""
import local_deep_research.database.encrypted_db as encrypted_db
real = encrypted_db.create_engine
def _flaky(*args, **kwargs):
calls["n"] += 1
if calls["n"] == 1:
raise RuntimeError("simulated engine build failure")
return real(*args, **kwargs)
monkeypatch.setattr(encrypted_db, "create_engine", _flaky)
def _inject_migration_failure(monkeypatch, calls):
"""Fail the first alembic run — after BOTH the real ``.db`` and ``.salt``
exist. Exercises the second cleanup call site, the historically realistic
one (a world-writable migrations dir).
Patched on the source module: ``create_user_database`` does a
function-level ``from .initialize import initialize_database`` that
re-reads the attribute at call time.
"""
import local_deep_research.database.initialize as initialize_mod
real = initialize_mod.initialize_database
def _flaky(*args, **kwargs):
calls["n"] += 1
if calls["n"] == 1:
raise RuntimeError("simulated migration failure")
return real(*args, **kwargs)
monkeypatch.setattr(initialize_mod, "initialize_database", _flaky)
@pytest.mark.parametrize(
"inject",
[
pytest.param(_inject_sqlcipher_failure, id="sqlcipher-structure-step"),
pytest.param(_inject_engine_failure, id="engine-build-step"),
pytest.param(_inject_migration_failure, id="alembic-migration-step"),
],
)
def test_registration_failure_leaves_username_reusable(
app, monkeypatch, inject
):
"""``create_user_database()`` has three failure sites between writing the
``.salt`` and returning a usable engine. A failure at ANY of them must
leave no on-disk residue, or the username becomes permanently
un-registerable:
* a leftover ``.salt`` makes ``create_database_salt()`` raise
``FileExistsError`` on every retry; and
* a leftover ``.db`` trips the ``db_path.exists()`` guard.
Either way the user can neither register (name taken) nor log in (no
working database) — a self-inflicted denial of service on their own
account. This drives a genuine failure at each site through the real
``POST /auth/register`` route and asserts the retry works end to end.
"""
_requires_sqlcipher()
from local_deep_research.database.encrypted_db import db_manager
from local_deep_research.database.sqlcipher_utils import get_salt_file_path
username = _unique("failreg")
db_path = db_manager._get_user_db_path(username)
calls = {"n": 0}
inject(monkeypatch, calls)
first = _register_ok(_client(app), username, TEST_PASSWORD)
assert first.status_code == 500, (
f"the injected failure should surface as a 500: {first.status_code} "
f"{first.text[:400]}"
)
assert calls["n"] >= 1, (
"the injected failure never fired — this 500 came from somewhere "
"else and the test proves nothing"
)
# Both artifacts must be gone. (The auth-DB row cleanup for this same
# failure is pinned by tests/web/test_registration_orphan_cleanup.py.)
assert not db_path.exists(), (
"a failed create left the partial .db behind — the retry below "
"would hit the 'Database already exists' guard forever"
)
assert not get_salt_file_path(db_path).exists(), (
"a failed create left the .salt behind — the retry below would hit "
"create_database_salt()'s FileExistsError forever"
)
assert not _auth_row_exists(username)
# The username is genuinely reusable: the retry (no longer failing)
# succeeds all the way to an authenticated session over a real DB.
retry_client = _client(app)
second = _register_ok(retry_client, username, TEST_PASSWORD)
assert second.status_code == 302, (
f"retry after a cleaned-up failure must succeed: "
f"{second.status_code} {second.text[:400]}"
)
assert db_manager.user_exists(username)
assert db_path.exists()
assert _whoami(retry_client) == username
def test_registration_recovers_from_orphaned_salt(app):
"""A ``.salt`` with no matching ``.db`` must not block registration.
A create killed mid-flight (SIGKILL/OOM/power loss), or the pre-#4934
cleanup that removed only the ``.db``, leaves exactly this orphan.
``create_database_salt()`` refuses to overwrite it, so without the
recovery branch in ``create_user_database`` the username is permanently
un-registerable. Nothing else on this branch exercises that
``except FileExistsError`` path.
The 302 alone proves the DB opens with the FRESH salt (migrations run
against the newly-keyed database and 500 if salt and key disagree); the
byte comparison additionally proves the salt was regenerated rather than
reused.
"""
_requires_sqlcipher()
from local_deep_research.database.encrypted_db import db_manager
from local_deep_research.database.sqlcipher_utils import (
create_database_salt,
get_salt_file_path,
)
username = _unique("saltorphan")
db_path = db_manager._get_user_db_path(username)
db_path.parent.mkdir(parents=True, exist_ok=True)
create_database_salt(db_path)
salt_path = get_salt_file_path(db_path)
assert salt_path.exists()
assert not db_path.exists()
planted_salt = salt_path.read_bytes()
client = _client(app)
resp = _register_ok(client, username, TEST_PASSWORD)
assert resp.status_code == 302, (
f"registration must heal an orphaned salt rather than 500 on it: "
f"{resp.status_code} {resp.text[:400]}"
)
assert db_manager.user_exists(username)
assert db_path.exists()
assert salt_path.exists()
assert salt_path.read_bytes() != planted_salt, (
"the orphaned salt was reused instead of regenerated"
)
assert _whoami(client) == username