~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
"""A transient epoch-read failure refuses the request but keeps the session.
``validate_session`` raises ``SessionValidationUnavailableError`` when the
durable epoch files cannot be read at all (EMFILE, EIO, ...). Every caller
must fail THIS request closed without clearing the session or its cookie:
clearing it would log out every active user during an fd-exhaustion spike,
including on static-file requests (``DatabaseMiddleware`` validates on every
request). Only durable state that was read and does not vouch for the
session ends it; that is covered in ``test_session_epoch.py``.
Logout is the one exception: it only destroys, so ``POST /auth/logout``
goes through unvalidated (no database open), and the route tears down the
user's credentials only for a cookie whose record still binds it to that
user.
Also pins the per-request memo: ``DatabaseMiddleware`` records the session
it validated in ``scope["state"]`` and ``require_auth`` reuses it instead of
re-projecting the epoch a second time in the same request.
Marked ``real_session_check`` so the autouse ``_legacy_bare_username_auth``
shim does not replace ``_server_session_valid``.
"""
import asyncio
import json
from unittest.mock import AsyncMock, MagicMock
import pytest
from fastapi import FastAPI, HTTPException
from starlette.requests import Request
from local_deep_research.web.auth.session_manager import (
SESSION_VALIDATION_UNAVAILABLE_DETAIL,
UNVALIDATED_LOGOUT_STATE_KEY,
VALIDATED_SESSION_STATE_KEY,
SessionManager,
SessionValidationUnavailableError,
)
from local_deep_research.web.dependencies import auth as auth_dep
from local_deep_research.web.services import socketio_asgi as sio_mod
pytestmark = pytest.mark.real_session_check
USER = "transient_user"
SID = "session-id-1"
def _unavailable(*_args, **_kwargs):
raise SessionValidationUnavailableError(USER, 24) # EMFILE
@pytest.fixture
def fake_session_manager(monkeypatch):
"""Replace the singleton's validate_session where each caller looks it up.
Only ``validate_session`` is replaced: the singleton's ``sessions`` dict
is left as it is, and no record for ``SID`` is seeded. A test that
reaches the cookie-clearing teardown (``_revoke_server_session``) must
seed one itself (``_seed_server_record``): the teardown looks the owner
up with ``session_owner``, which reads the record directly, not through
``validate_session``, and tears down nothing for an id it cannot find.
"""
from local_deep_research.web.auth import session_manager as sm_module
manager = MagicMock()
monkeypatch.setattr(
sm_module.session_manager, "validate_session", manager.validate_session
)
return manager
def _seed_server_record(monkeypatch, username: str = USER) -> None:
"""Give the real singleton a live record for SID (restored afterwards)."""
import datetime
from local_deep_research.web.auth import session_manager as sm_module
now = datetime.datetime.now(datetime.UTC)
monkeypatch.setitem(
sm_module.session_manager.sessions,
SID,
{
"username": username,
"created_at": now,
"last_access": now,
"remember_me": False,
"rekey_epoch": "test-epoch",
},
)
def _request(
session: dict, state: dict | None = None, path: str = "/api/whatever"
) -> Request:
scope = {
"type": "http",
"method": "GET",
"path": path,
"headers": [],
"session": session,
}
if state is not None:
scope["state"] = state
return Request(scope)
# --- _enforce_session_revocation / DatabaseMiddleware ----------------------
def test_revocation_check_raises_and_leaves_the_session(fake_session_manager):
from local_deep_research.web.fastapi_app import (
_enforce_session_revocation,
)
fake_session_manager.validate_session.side_effect = _unavailable
session = {"username": USER, "session_id": SID}
state: dict = {}
with pytest.raises(SessionValidationUnavailableError):
_enforce_session_revocation(session, state)
assert session == {"username": USER, "session_id": SID}
assert VALIDATED_SESSION_STATE_KEY not in state
def test_revocation_check_records_the_validated_session(fake_session_manager):
from local_deep_research.web.fastapi_app import (
_enforce_session_revocation,
)
fake_session_manager.validate_session.return_value = USER
state: dict = {}
_enforce_session_revocation({"username": USER, "session_id": SID}, state)
assert state[VALIDATED_SESSION_STATE_KEY] == (SID, USER)
def test_revoked_session_is_cleared_and_not_recorded(fake_session_manager):
from local_deep_research.web.fastapi_app import (
_enforce_session_revocation,
)
fake_session_manager.validate_session.return_value = None
session = {"username": USER, "session_id": SID}
state: dict = {}
_enforce_session_revocation(session, state)
assert session == {}
assert VALIDATED_SESSION_STATE_KEY not in state
@pytest.mark.parametrize("path", ["/static/css/app.css", "/", "/auth/check"])
def test_middleware_answers_503_without_touching_the_session(
fake_session_manager, path
):
from local_deep_research.web.fastapi_app import DatabaseMiddleware
fake_session_manager.validate_session.side_effect = _unavailable
inner = AsyncMock()
middleware = DatabaseMiddleware(inner)
session = {"username": USER, "session_id": SID}
scope = {
"type": "http",
"method": "GET",
"path": path,
"headers": [],
"session": session,
}
sent: list[dict] = []
async def send(message):
sent.append(message)
async def receive():
return {"type": "http.request", "body": b"", "more_body": False}
asyncio.run(middleware(scope, receive, send))
inner.assert_not_called()
assert sent[0]["type"] == "http.response.start"
assert sent[0]["status"] == 503
assert json.loads(sent[1]["body"]) == {
"detail": SESSION_VALIDATION_UNAVAILABLE_DETAIL
}
# Not a logout: the session is exactly as it came in.
assert session == {"username": USER, "session_id": SID}
def _run_middleware(fake_session_manager, monkeypatch, method, path):
from local_deep_research.web import fastapi_app
from local_deep_research.web.dependencies import auth as auth_module
fake_session_manager.validate_session.side_effect = _unavailable
ensure = MagicMock()
monkeypatch.setattr(auth_module, "ensure_user_database", ensure)
inner = AsyncMock()
middleware = fastapi_app.DatabaseMiddleware(inner)
session = {"username": USER, "session_id": SID}
scope = {
"type": "http",
"method": method,
"path": path,
"headers": [],
"session": session,
}
sent: list[dict] = []
async def send(message):
sent.append(message)
async def receive():
return {"type": "http.request", "body": b"", "more_body": False}
asyncio.run(middleware(scope, receive, send))
return inner, ensure, scope, session, sent
def test_middleware_lets_logout_through_unvalidated(
fake_session_manager, monkeypatch
):
inner, ensure, scope, session, sent = _run_middleware(
fake_session_manager, monkeypatch, "POST", "/auth/logout"
)
inner.assert_called_once()
assert sent == []
# Nothing is opened (or stored) for the unvalidated cookie, and it is
# not recorded as validated for require_auth.
ensure.assert_not_called()
assert scope["state"][UNVALIDATED_LOGOUT_STATE_KEY] is True
assert VALIDATED_SESSION_STATE_KEY not in scope["state"]
assert session == {"username": USER, "session_id": SID}
@pytest.mark.parametrize(
("method", "path"),
[
("GET", "/auth/logout"),
("POST", "/auth/logout/"),
("POST", "/auth/logoutx"),
("POST", "/auth/change-password"),
],
)
def test_only_post_logout_bypasses_the_503(
fake_session_manager, monkeypatch, method, path
):
inner, ensure, scope, session, sent = _run_middleware(
fake_session_manager, monkeypatch, method, path
)
inner.assert_not_called()
ensure.assert_not_called()
assert sent[0]["status"] == 503
assert UNVALIDATED_LOGOUT_STATE_KEY not in scope["state"]
# --- logout during a fault ------------------------------------------------
def test_session_belongs_to_only_reads_the_record():
manager = SessionManager()
manager.sessions[SID] = {"username": USER}
assert manager.session_belongs_to(SID, USER) is True
assert manager.session_belongs_to(SID, "other-user") is False
assert manager.session_belongs_to("other-session", USER) is False
assert manager.session_belongs_to(None, USER) is False
assert manager.session_belongs_to("", USER) is False
@pytest.fixture
def logout_env(monkeypatch):
from local_deep_research.database import session_passwords
from local_deep_research.database import thread_local_session
from local_deep_research.scheduler import background
from local_deep_research.web.routers import auth as auth_router
manager = SessionManager()
monkeypatch.setattr(auth_router, "session_manager", manager)
env = MagicMock()
env.manager = manager
monkeypatch.setattr(auth_router, "db_manager", env.db_manager)
monkeypatch.setattr(
auth_router, "_disconnect_session_sockets", env.disconnect_sockets
)
monkeypatch.setattr(
session_passwords.session_password_store,
"clear_all_for_user",
env.clear_passwords,
)
monkeypatch.setattr(
thread_local_session, "clear_user_credentials", env.clear_credentials
)
monkeypatch.setattr(
background, "get_background_job_scheduler", env.get_scheduler
)
env.logout = auth_router.logout
return env
def _logout_request(session: dict) -> Request:
return Request(
{
"type": "http",
"method": "POST",
"path": "/auth/logout",
"headers": [],
"session": session,
"state": {UNVALIDATED_LOGOUT_STATE_KEY: True},
}
)
def test_unvalidated_logout_revokes_the_callers_own_session(logout_env):
logout_env.manager.sessions[SID] = {"username": USER}
other = "session-id-2"
logout_env.manager.sessions[other] = {"username": "someone-else"}
request = _logout_request({"username": USER, "session_id": SID})
response = logout_env.logout(request)
assert response.status_code == 302
assert SID not in logout_env.manager.sessions
assert other in logout_env.manager.sessions
logout_env.clear_passwords.assert_called_once_with(USER)
logout_env.clear_credentials.assert_called_once_with(USER)
logout_env.disconnect_sockets.assert_called_once_with(SID)
assert "username" not in request.session
assert "session_id" not in request.session
@pytest.mark.parametrize(
"record", [None, {"username": "someone-else"}], ids=["gone", "foreign"]
)
def test_unvalidated_logout_with_an_unbound_cookie_only_drops_the_cookie(
logout_env, record
):
# A cookie whose record is already gone (or not this user's) must not
# reach the user-wide teardown while nothing validated it: it only
# loses itself, as the validating middleware would have done.
if record is not None:
logout_env.manager.sessions[SID] = record
request = _logout_request({"username": USER, "session_id": SID})
response = logout_env.logout(request)
assert response.status_code == 302
assert request.session == {}
if record is not None:
assert logout_env.manager.sessions[SID] == record
logout_env.clear_passwords.assert_not_called()
logout_env.clear_credentials.assert_not_called()
logout_env.disconnect_sockets.assert_not_called()
logout_env.get_scheduler.assert_not_called()
logout_env.db_manager.close_user_database.assert_not_called()
# --- require_auth ---------------------------------------------------------
@pytest.fixture
def connected(monkeypatch):
db = MagicMock()
db.is_user_connected.return_value = True
monkeypatch.setattr(auth_dep, "db_manager", db)
return db
def test_require_auth_answers_503_and_keeps_the_session(
fake_session_manager, connected
):
fake_session_manager.validate_session.side_effect = _unavailable
request = _request({"username": USER, "session_id": SID})
with pytest.raises(HTTPException) as raised:
auth_dep.require_auth(request)
assert raised.value.status_code == 503
assert raised.value.detail == SESSION_VALIDATION_UNAVAILABLE_DETAIL
assert raised.value.headers == {"Retry-After": "5"}
assert request.session == {"username": USER, "session_id": SID}
def _render_http_exception(request: Request, exc: HTTPException):
"""Answer ``exc`` through the app's real HTTPException handler."""
from local_deep_research.web.fastapi_app import (
_register_exception_handlers,
)
app = FastAPI()
_register_exception_handlers(app)
return asyncio.run(app.exception_handlers[HTTPException](request, exc))
@pytest.mark.parametrize(
("path", "body"),
[
("/api/whatever", {"detail": SESSION_VALIDATION_UNAVAILABLE_DETAIL}),
(
"/api/v1/quick_summary",
{
"error": SESSION_VALIDATION_UNAVAILABLE_DETAIL,
"detail": SESSION_VALIDATION_UNAVAILABLE_DETAIL,
},
),
],
)
def test_middleware_and_require_auth_send_the_same_503(
fake_session_manager, connected, monkeypatch, path, body
):
# One condition, one envelope: a client must not have to tell which of
# the two refused it. /api/v1 keeps its legacy "error" key.
_inner, _ensure, _scope, _session, sent = _run_middleware(
fake_session_manager, monkeypatch, "GET", path
)
request = _request({"username": USER, "session_id": SID}, path=path)
with pytest.raises(HTTPException) as raised:
auth_dep.require_auth(request)
response = _render_http_exception(request, raised.value)
assert sent[0]["status"] == response.status_code == 503
assert json.loads(sent[1]["body"]) == json.loads(response.body) == body
assert dict(sent[0]["headers"])[b"retry-after"] == b"5"
assert response.headers["retry-after"] == "5"
def test_require_auth_still_rejects_an_invalid_session(
fake_session_manager, connected
):
fake_session_manager.validate_session.return_value = None
request = _request({"username": USER, "session_id": SID})
with pytest.raises(HTTPException) as raised:
auth_dep.require_auth(request)
assert raised.value.status_code == 401
assert request.session == {}
def test_require_auth_reuses_the_middleware_validation(
fake_session_manager, connected, monkeypatch
):
monkeypatch.setattr(
auth_dep.session_password_store,
"get_session_password",
lambda username, session_id: "available-credential",
)
request = _request(
{"username": USER, "session_id": SID},
state={VALIDATED_SESSION_STATE_KEY: (SID, USER)},
)
assert auth_dep.require_auth(request) == USER
fake_session_manager.validate_session.assert_not_called()
def test_validation_memo_does_not_preserve_a_lost_credential(
fake_session_manager, connected, monkeypatch
):
from local_deep_research.database.session_passwords import (
SessionPasswordStore,
)
store = SessionPasswordStore()
store.store_session_password(USER, SID, "available-credential")
monkeypatch.setattr(auth_dep, "session_password_store", store)
connected.has_encryption = True
fake_session_manager.validate_session.return_value = USER
_seed_server_record(monkeypatch)
destroy = MagicMock()
disconnect = MagicMock()
monkeypatch.setattr(auth_dep.session_manager, "destroy_session", destroy)
monkeypatch.setattr(sio_mod, "disconnect_session", disconnect)
request = _request(
{"username": USER, "session_id": SID},
state={VALIDATED_SESSION_STATE_KEY: (SID, USER)},
)
assert auth_dep.require_auth(request) == USER
fake_session_manager.validate_session.assert_not_called()
# Losing the credential after middleware validation must still revoke
# this session, even though its user's database remains connected.
store.clear_session(USER, SID)
with pytest.raises(HTTPException) as raised:
auth_dep.require_auth(request)
assert raised.value.status_code == 401
assert request.session == {}
destroy.assert_called_once_with(SID)
disconnect.assert_called_once_with(SID)
@pytest.mark.parametrize(
"memo", [("other-session", USER), (SID, "other-user"), None]
)
def test_require_auth_validates_when_the_memo_does_not_match(
fake_session_manager, connected, memo
):
fake_session_manager.validate_session.return_value = None
state = {} if memo is None else {VALIDATED_SESSION_STATE_KEY: memo}
request = _request({"username": USER, "session_id": SID}, state=state)
with pytest.raises(HTTPException) as raised:
auth_dep.require_auth(request)
assert raised.value.status_code == 401
fake_session_manager.validate_session.assert_called_once_with(SID)
# --- socket gates ---------------------------------------------------------
@pytest.fixture
def socket_state(monkeypatch):
monkeypatch.setattr(sio_mod, "_sid_users", {"sock-1": USER})
monkeypatch.setattr(sio_mod, "_sid_sessions", {"sock-1": SID})
monkeypatch.setattr(sio_mod, "_subscriptions", {})
monkeypatch.setattr(sio_mod, "_main_loop", sio_mod._main_loop)
monkeypatch.setattr(sio_mod, "_lock", None)
sio_mod.init_lock()
def test_socket_revalidation_reports_unknown_not_invalid(
fake_session_manager, socket_state
):
fake_session_manager.validate_session.side_effect = _unavailable
result = asyncio.run(sio_mod._socket_session_still_valid("sock-1", USER))
assert result == (SID, None)
def test_subscribe_is_refused_without_severing_the_session(
fake_session_manager, socket_state, monkeypatch
):
fake_session_manager.validate_session.side_effect = _unavailable
emit = AsyncMock()
disconnect = AsyncMock()
monkeypatch.setattr(sio_mod.sio, "emit", emit)
monkeypatch.setattr(sio_mod.sio, "disconnect", disconnect)
severed = MagicMock()
monkeypatch.setattr(sio_mod, "disconnect_session", severed)
owns = AsyncMock(return_value=True)
monkeypatch.setattr(sio_mod, "_user_owns_research", owns)
asyncio.run(sio_mod.on_subscribe("sock-1", {"research_id": "r-1"}))
severed.assert_not_called()
disconnect.assert_not_called()
owns.assert_not_called()
assert sio_mod._subscriptions == {}
event, payload = emit.call_args.args[:2]
assert event == "subscribe_error"
assert payload["error"] == "Temporarily unavailable"
assert sio_mod._sid_sessions == {"sock-1": SID}
def test_connect_is_refused_when_the_session_cannot_be_validated(
fake_session_manager, socket_state, monkeypatch
):
fake_session_manager.validate_session.side_effect = _unavailable
monkeypatch.setattr(
sio_mod,
"_decode_session_cookie",
lambda _cookie: {"username": USER, "session_id": SID},
)
accepted = asyncio.run(
sio_mod.connect("sock-2", {"HTTP_COOKIE": "session=whatever"})
)
assert accepted is False
assert "sock-2" not in sio_mod._sid_users