Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

25.4 KB
Raw Blame
"""Route-level proof of the encrypted-DB password gate on the two research
entry points that had no test for it.

``web/auth/password_utils.resolve_user_password(username)`` returns
``(password, session_expired)``; ``session_expired`` is True only when the
database is encrypted and this session's password can no longer be
resolved. A research run needs that password to write token/search metrics
into the user's encrypted database from a background thread, so the entry
points must refuse the request outright — otherwise the run appears to
start while every metric write is silently dropped (issue #4457).

Three routes share the guard. Only the chat one was covered
(``tests/chat/test_chat_research_triggering.py``); the other two were not:

* ``POST /api/start_research``   — ``web/routers/research.py``
* ``POST /api/followup/start``   — ``web/routers/followup.py``

``tests/security/test_auth_credential_lifetime_fastapi.py`` pins the helper
itself, but a helper test cannot prove the *wiring*: that each route calls
it, refuses on its flag, and refuses BEFORE any row is written or thread
spawned. Every existing test that touches these paths patches
``resolve_user_password`` out entirely, so the real function had never run
on either route ("session has expired" had zero hits in the suite).

HOW THE EXPIRED STATE IS PRODUCED HERE
--------------------------------------
``resolve_user_password`` and ``get_user_password`` run for real. The store
entry the caller's session resolves through is genuinely deleted, either
before authentication or immediately before the route resolves its password.
The latter simulates eviction after authentication has already succeeded:
a wrapper controls the timing, then calls the real resolver. Both the shared
authentication gate and the route's later credential check must reject the
request. The thread-spawning entry point is replaced so no research runs.

The caller keeps a *second*, live session (a different browser/device), for
a mechanical reason that also makes the assertion stronger:
``get_user_db_session(username)`` is called by both handlers before the
guard and falls back to ``get_any_session_password(username)``, so with no
password anywhere for that user the database cannot be opened. Keeping a
live sibling session preserves the database while testing that neither
authentication layer accepts that sibling's credential on this session's
behalf. An already-expired session is now refused by ``require_auth``;
eviction during the request must still be refused by the route's own guard.

Each refusal test issues the identical request from the live sibling client
FIRST and requires a 200 from it. That rules out the vacuity trap: a 4xx
for an unrelated reason (bad body, CSRF, rate limit) would make "no
research was started" pass trivially, so the route is proven reachable with
this exact payload in this exact state before the refusal is asserted.
"""

from __future__ import annotations

import itertools
import uuid
from datetime import datetime, timezone
from unittest.mock import MagicMock, patch

import pytest

from local_deep_research.database import encrypted_db
from local_deep_research.database.models import (
    QueuedResearch,
    ResearchHistory,
    UserActiveResearch,
)
from local_deep_research.database.session_context import get_user_db_session
from local_deep_research.database.session_passwords import (
    session_password_store,
)

# The suite's autouse ``_legacy_bare_username_auth`` shim makes
# ``_server_session_valid`` accept unconditionally so legacy bare-username
# route tests keep working. These tests log in for real and depend on the
# session identity being the real one, so opt out of the relaxed gate.
pytestmark = pytest.mark.real_session_check


START_RESEARCH_PATH = "/api/start_research"
FOLLOWUP_START_PATH = "/api/followup/start"

CALLER_PW = "Caller-Correct-Horse-1!"  # noqa: S105
OTHER_PW = "Other-Battery-Staple-2!"  # noqa: S105

# Only ``query`` is strictly required; the rest are supplied explicitly so
# the request never depends on whatever defaults happen to be in the user's
# settings database. The same body is used for the positive control and for
# the refusal, so the password state is the only variable.
START_RESEARCH_BODY = {
    "query": "password gate probe",
    "model_provider": "ollama",
    "model": "test-model",
    "search_engine": "wikipedia",
    "iterations": 1,
    "questions_per_iteration": 1,
    "strategy": "source-based",
}

# Rate limiting is keyed per client IP and the limiter's enabled flag is
# resolved at import time (so a fixture-set env var cannot turn it off).
# A monotonic counter gives every client a unique peer: random addresses
# collide in a long session and produce 429s that have nothing to do with
# the guard under test.
_peer_counter = itertools.count(1)


@pytest.fixture
def live_app(tmp_path, monkeypatch):
    """The real assembled app on a temp data dir.

    Same shape as ``tests/security/test_auth_credential_lifetime_fastapi.py``
    and ``test_login_cached_connection_password_lockout.py``: the routes read
    module-level singletons (``db_manager``, ``session_password_store``), so
    the app must run against those exact instances and the data dir has to be
    repointed on the singleton itself.

    Usernames created through ``_new_user`` are tracked and their store
    entries dropped afterwards — ``session_password_store`` is a process-wide
    singleton that ``reset_all_singletons`` does not touch, so a leaked entry
    would be visible to every later test in the same worker.
    """
    monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path))
    monkeypatch.setenv("LDR_TESTING_WITH_MOCKS", "true")
    monkeypatch.setenv("LDR_DISABLE_RATE_LIMITING", "true")
    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.fastapi_app import app as fastapi_app
    import local_deep_research.web.routers.auth as auth_routes

    original_data_dir = db_manager.data_dir
    created_users: list[str] = []
    try:
        db_manager.data_dir = tmp_path / "encrypted_databases"
        init_auth_database()
        # Keep the synchronous test off the real post-login worker threads.
        monkeypatch.setattr(
            auth_routes,
            "_perform_post_login_tasks",
            lambda _u, _p, _sid=None: None,
        )
        yield _Harness(fastapi_app, created_users)
    finally:
        for username in created_users:
            session_password_store.clear_all_for_user(username)
        db_manager.close_all_databases()
        db_manager.data_dir = original_data_dir


class _Harness:
    """The app plus the bookkeeping the helpers below need."""

    def __init__(self, app, created_users):
        self.app = app
        self.created_users = created_users


def _client(app):
    """A TestClient with its own, monotonically assigned peer address."""
    from fastapi.testclient import TestClient

    peer = next(_peer_counter)
    client = TestClient(app, raise_server_exceptions=False)
    client.headers.update(
        {"X-Forwarded-For": f"10.{peer // 254 % 254 + 1}.{peer % 254 + 1}.7"}
    )
    return client


def _csrf(client):
    """A CSRF token bound to this client's session (middleware-enforced)."""
    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, username, password):
    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, username, password):
    token = _csrf(client)
    return client.post(
        "/auth/login",
        data={
            "username": username,
            "password": password,
            "csrf_token": token,
        },
        headers={"X-CSRFToken": token},
        follow_redirects=False,
    )


def _stored_session_ids(username):
    """The session ids that currently hold a password for ``username``."""
    with session_password_store._lock:
        return {
            key[1]
            for key in session_password_store._store
            if key[0] == username
        }


def _settle(client):
    """Consume the one-shot post-login temp-auth token.

    ``ensure_user_database`` re-writes the password into the store when it
    consumes that token, so a store entry cleared while the token is still
    in the cookie is silently restored by the next request — the expired
    state would evaporate before the POST under test.
    """
    assert client.get("/auth/check").status_code == 200, (
        "the client must be authenticated after login/registration"
    )


def _new_user(harness, prefix, password=CALLER_PW):
    """Register a fresh user; return ``(client, username, session_id)``."""
    username = f"{prefix}_{uuid.uuid4().hex[:8]}"
    harness.created_users.append(username)
    client = _client(harness.app)
    resp = _register(client, username, password)
    assert resp.status_code in (200, 302), (
        f"registration failed: {resp.status_code} / {resp.text[:400]}"
    )
    _settle(client)
    session_ids = _stored_session_ids(username)
    assert len(session_ids) == 1, (
        f"expected exactly one stored session for the new user, got {session_ids}"
    )
    return client, username, next(iter(session_ids))


def _extra_session(harness, username, password=CALLER_PW):
    """Log the same user in again from a second client (another device)."""
    before = _stored_session_ids(username)
    client = _client(harness.app)
    resp = _login(client, username, password)
    assert resp.status_code == 302, (
        f"second login failed: {resp.status_code} / {resp.text[:400]}"
    )
    _settle(client)
    new = _stored_session_ids(username) - before
    assert len(new) == 1, f"expected one new session, got {new}"
    return client, next(iter(new))


def _expire_session_password(username, session_id):
    """Delete this session's stored password, as the 24h TTL would."""
    session_password_store.clear_session(username, session_id)
    assert session_id not in _stored_session_ids(username)


def _observe_password_resolution(target, username, session_id, expire_late):
    """Optionally evict just before the real route-level credential lookup."""
    from local_deep_research.web.auth.password_utils import (
        resolve_user_password,
    )

    def resolve(request_username):
        if expire_late:
            _expire_session_password(username, session_id)
        return resolve_user_password(request_username)

    return patch(target, side_effect=resolve)


def _configure_model(username, password=CALLER_PW):
    """Set ``llm.model`` in the user's settings database.

    The follow-up route reads the model from settings (it takes no model
    field in the request body) and 400s when it is empty. That check sits
    AFTER the password guard, so it cannot mask a refusal — but it would
    stop the positive control, so the model is configured for every test in
    that class, keeping the password state the only variable.
    """
    from local_deep_research.settings import SettingsManager

    with get_user_db_session(username, password=password) as db_session:
        assert SettingsManager(db_session).set_setting(
            "llm.model", "test-model"
        )


def _run_record_counts(username, password=CALLER_PW):
    """Every table a started/queued research writes a row into."""
    with get_user_db_session(username, password=password) as db_session:
        return {
            "history": db_session.query(ResearchHistory).count(),
            "active": db_session.query(UserActiveResearch).count(),
            "queued": db_session.query(QueuedResearch).count(),
        }


def _post_json(client, path, body):
    token = _csrf(client)
    return client.post(path, json=body, headers={"X-CSRFToken": token})


def _seed_parent_research(username, password=CALLER_PW):
    """Write a completed ``ResearchHistory`` row owned by ``username`` and
    return its id.

    ``web/routers/followup.py``'s ownership gate (hand-ported from main's
    #5600 cross-user isolation fix) 404s before the password gate runs
    whenever ``service.load_parent_research(parent_id)`` comes back empty,
    which it always does for an id with no matching row in the caller's own
    DB. A real, owned parent row is required to get past that check and
    reach the password guard these tests target.
    """
    now = datetime.now(timezone.utc).isoformat()
    research_id = str(uuid.uuid4())
    with get_user_db_session(username, password=password) as db_session:
        db_session.add(
            ResearchHistory(
                id=research_id,
                query="password gate parent",
                mode="quick_summary",
                status="completed",
                created_at=now,
                completed_at=now,
                duration_seconds=1,
                progress=100,
                title="password gate parent",
                report_content="body",
            )
        )
        db_session.commit()
    return research_id


def _followup_body(parent_research_id):
    return {
        "parent_research_id": parent_research_id,
        "question": "password gate follow-up probe",
    }


class TestStartResearchPasswordGate:
    """``POST /api/start_research`` — ``web/routers/research.py``.

    The guard lives just before the ``ResearchHistory`` insert and returns
    ``{"status": "error", "message": ...}`` with HTTP 401.
    """

    SPAWN_TARGET = (
        "local_deep_research.web.routers.research.start_research_process"
    )

    def test_live_session_starts_the_run(self, live_app):
        """Positive control. Without it every assertion in this class would
        also hold for a route that refused unconditionally."""
        client, username, _sid = _new_user(live_app, "gate_pos")

        with patch(self.SPAWN_TARGET) as spawn:
            spawn.return_value = MagicMock(ident=4242)
            resp = _post_json(client, START_RESEARCH_PATH, START_RESEARCH_BODY)

        assert resp.status_code == 200, (
            f"a live session must start a research run: {resp.text[:400]}"
        )
        assert resp.json()["status"] == "success"
        assert resp.json()["research_id"]
        assert spawn.called, "the research thread entry point was never reached"
        assert spawn.call_args.kwargs["user_password"] == CALLER_PW
        assert _run_record_counts(username)["history"] == 1

    @pytest.mark.parametrize("expire_late", [False, True])
    def test_expired_session_is_refused_and_starts_no_research(
        self, live_app, expire_late
    ):
        """Encrypted DB + this session's password gone -> 401, nothing started.

        A second user is logged in and live throughout, and the caller's own
        second session is live too: neither may satisfy the guard for the
        session making the call.
        """
        _decoy_client, _decoy_user, _decoy_sid = _new_user(
            live_app, "gate_decoy", OTHER_PW
        )
        client, username, session_id = _new_user(live_app, "gate_exp")
        sibling, _sibling_sid = _extra_session(live_app, username)

        # Positive control on the SAME state, from the still-live sibling
        # session: proves the payload, CSRF and rate-limit budget are all
        # fine, so the refusal below cannot be a disguised 4xx for an
        # unrelated reason.
        with patch(self.SPAWN_TARGET) as spawn:
            spawn.return_value = MagicMock(ident=4242)
            ok = _post_json(sibling, START_RESEARCH_PATH, START_RESEARCH_BODY)
        assert ok.status_code == 200, (
            f"the control request must be accepted: {ok.text[:400]}"
        )
        assert spawn.called

        if not expire_late:
            _expire_session_password(username, session_id)
        before = _run_record_counts(username)

        with (
            patch(self.SPAWN_TARGET) as spawn,
            _observe_password_resolution(
                "local_deep_research.web.routers.research.resolve_user_password",
                username,
                session_id,
                expire_late,
            ) as resolver,
        ):
            spawn.return_value = MagicMock(ident=4242)
            resp = _post_json(client, START_RESEARCH_PATH, START_RESEARCH_BODY)

        assert resp.status_code == 401, (
            "an encrypted database with no password for THIS session must "
            "refuse the run with 401 — starting it produces a research whose "
            "every metric write is silently dropped (#4457). Got "
            f"{resp.status_code}: {resp.text[:400]}"
        )
        body = resp.json()
        if expire_late:
            resolver.assert_called_once_with(username)
            assert body["status"] == "error"
            assert "log out" in body["message"].lower()
        else:
            resolver.assert_not_called()
            assert body == {"detail": "Authentication required"}

        spawn.assert_not_called()
        assert _run_record_counts(username) == before, (
            "the refusal must leave no research record behind: the guard runs "
            "before the ResearchHistory / UserActiveResearch inserts"
        )

    def test_run_uses_the_callers_own_password(self, live_app):
        """The password handed to the run must be the CALLER's.

        Two users are logged in with different passwords at the same time.
        ``get_user_db_session`` resolves "any live session's password for
        this username", so a guard that reached for a process-wide live
        credential instead of the caller's own would still return 200 here —
        only the value passed to the spawn distinguishes the two.
        """
        _other_client, _other_user, _other_sid = _new_user(
            live_app, "gate_other", OTHER_PW
        )
        client, username, _sid = _new_user(live_app, "gate_self", CALLER_PW)

        with patch(self.SPAWN_TARGET) as spawn:
            spawn.return_value = MagicMock(ident=4242)
            resp = _post_json(client, START_RESEARCH_PATH, START_RESEARCH_BODY)

        assert resp.status_code == 200, resp.text[:400]
        assert spawn.called
        assert spawn.call_args.kwargs["username"] == username
        assert spawn.call_args.kwargs["user_password"] == CALLER_PW, (
            "the run was started with a password that is not the caller's"
        )

    def test_unencrypted_db_starts_the_run_with_no_password(self, live_app):
        """PINNED CURRENT BEHAVIOUR (not a fix).

        On an unencrypted install ``session_expired`` is always False and a
        missing password is legitimate, so the route proceeds and spawns the
        run with ``user_password=None``. Metrics writing then relies on the
        unencrypted-DB path rather than on a credential.
        """
        client, username, session_id = _new_user(live_app, "gate_plain")
        _sibling, _sibling_sid = _extra_session(live_app, username)
        _expire_session_password(username, session_id)

        with patch.object(encrypted_db.db_manager, "has_encryption", False):
            with patch(self.SPAWN_TARGET) as spawn:
                spawn.return_value = MagicMock(ident=4242)
                resp = _post_json(
                    client, START_RESEARCH_PATH, START_RESEARCH_BODY
                )

        assert resp.status_code == 200, (
            "an unencrypted database must never be blocked by the password "
            f"guard: {resp.text[:400]}"
        )
        assert spawn.called
        assert spawn.call_args.kwargs["user_password"] is None


class TestFollowupStartPasswordGate:
    """``POST /api/followup/start`` — ``web/routers/followup.py``.

    Same guard, different response shape: this router answers
    ``{"success": false, "error": ...}`` because its frontend reads
    ``data.error``. ``start_research_process`` is imported inside
    ``_start_followup_sync``, so the patch target is the service module the
    name is looked up on, not the router.
    """

    SPAWN_TARGET = (
        "local_deep_research.web.services.research_service."
        "start_research_process"
    )

    def test_live_session_starts_the_run(self, live_app):
        """Positive control for the follow-up route."""
        client, username, _sid = _new_user(live_app, "fup_pos")
        _configure_model(username)
        parent_id = _seed_parent_research(username)

        with patch(self.SPAWN_TARGET) as spawn:
            spawn.return_value = MagicMock(ident=4243)
            resp = _post_json(
                client, FOLLOWUP_START_PATH, _followup_body(parent_id)
            )

        assert resp.status_code == 200, (
            f"a live session must start a follow-up run: {resp.text[:400]}"
        )
        body = resp.json()
        assert body["success"] is True
        assert body["research_id"]
        assert spawn.called, "the research thread entry point was never reached"
        assert spawn.call_args.kwargs["user_password"] == CALLER_PW
        # +1: the seeded parent, +1: the follow-up run just started.
        assert _run_record_counts(username)["history"] == 2

    @pytest.mark.parametrize("expire_late", [False, True])
    def test_expired_session_is_refused_and_starts_no_research(
        self, live_app, expire_late
    ):
        """Encrypted DB + this session's password gone -> 401, nothing started."""
        _decoy_client, _decoy_user, _decoy_sid = _new_user(
            live_app, "fup_decoy", OTHER_PW
        )
        client, username, session_id = _new_user(live_app, "fup_exp")
        _configure_model(username)
        parent_id = _seed_parent_research(username)
        sibling, _sibling_sid = _extra_session(live_app, username)

        with patch(self.SPAWN_TARGET) as spawn:
            spawn.return_value = MagicMock(ident=4243)
            ok = _post_json(
                sibling, FOLLOWUP_START_PATH, _followup_body(parent_id)
            )
        assert ok.status_code == 200, (
            f"the control request must be accepted: {ok.text[:400]}"
        )
        assert spawn.called

        if not expire_late:
            _expire_session_password(username, session_id)
        before = _run_record_counts(username)

        with (
            patch(self.SPAWN_TARGET) as spawn,
            _observe_password_resolution(
                "local_deep_research.web.routers.followup.resolve_user_password",
                username,
                session_id,
                expire_late,
            ) as resolver,
        ):
            spawn.return_value = MagicMock(ident=4243)
            resp = _post_json(
                client, FOLLOWUP_START_PATH, _followup_body(parent_id)
            )

        assert resp.status_code == 401, (
            "an encrypted database with no password for THIS session must "
            "refuse the follow-up with 401. Got "
            f"{resp.status_code}: {resp.text[:400]}"
        )
        body = resp.json()
        if expire_late:
            resolver.assert_called_once_with(username)
            assert body["success"] is False
            assert "log out" in body["error"].lower()
        else:
            resolver.assert_not_called()
            assert body == {"detail": "Authentication required"}

        spawn.assert_not_called()
        assert _run_record_counts(username) == before, (
            "the refusal must leave no ResearchHistory / UserActiveResearch "
            "row behind — the guard runs before both inserts"
        )

    def test_run_uses_the_callers_own_password(self, live_app):
        """The password handed to the follow-up run must be the CALLER's."""
        _other_client, _other_user, _other_sid = _new_user(
            live_app, "fup_other", OTHER_PW
        )
        client, username, _sid = _new_user(live_app, "fup_self", CALLER_PW)
        _configure_model(username)
        parent_id = _seed_parent_research(username)

        with patch(self.SPAWN_TARGET) as spawn:
            spawn.return_value = MagicMock(ident=4243)
            resp = _post_json(
                client, FOLLOWUP_START_PATH, _followup_body(parent_id)
            )

        assert resp.status_code == 200, resp.text[:400]
        assert spawn.called
        assert spawn.call_args.kwargs["username"] == username
        assert spawn.call_args.kwargs["user_password"] == CALLER_PW, (
            "the follow-up was started with a password that is not the caller's"
        )

    def test_unencrypted_db_starts_the_run_with_no_password(self, live_app):
        """PINNED CURRENT BEHAVIOUR (not a fix): unencrypted installs spawn
        the follow-up with ``user_password=None``."""
        client, username, session_id = _new_user(live_app, "fup_plain")
        _configure_model(username)
        parent_id = _seed_parent_research(username)
        _sibling, _sibling_sid = _extra_session(live_app, username)
        _expire_session_password(username, session_id)

        with patch.object(encrypted_db.db_manager, "has_encryption", False):
            with patch(self.SPAWN_TARGET) as spawn:
                spawn.return_value = MagicMock(ident=4243)
                resp = _post_json(
                    client, FOLLOWUP_START_PATH, _followup_body(parent_id)
                )

        assert resp.status_code == 200, (
            "an unencrypted database must never be blocked by the password "
            f"guard: {resp.text[:400]}"
        )
        assert spawn.called
        assert spawn.call_args.kwargs["user_password"] is None