~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
"""What ``open_user_database`` proves, and when it refuses to prove it.
``capture_login_proof`` records the durable epoch a successful open
verified the password against under the rekey sidecar lock; the login
route binds its session to that epoch. These tests pin the recorded
epoch on each success path, that nothing is recorded outside a capture
block, that the outer open wins over the phase-2 re-entry, and two
refusals the proof relies on: a cold open whose epoch re-read does not
find the epoch it ran under (the committed epoch moved, went missing or
is pending, or the read fails) is discarded and fails closed instead of
reading as a wrong password, and
pending-rekey recovery verifies the candidate key before it finalizes
the epoch.
"""
from __future__ import annotations
from pathlib import Path
from unittest.mock import MagicMock, patch
import pytest
from local_deep_research.database import encrypted_db
from local_deep_research.database import rekey_lock as rekey_lock_module
from local_deep_research.database.encrypted_db import (
DatabaseManager,
LoginProof,
MissingLoginProofError,
_RekeyVerificationError,
capture_login_proof,
)
from local_deep_research.database.rekey_lock import (
RekeyEpochUnreadableError,
RekeyRecoveryRequiredError,
acquire_rekey_lock,
)
def _new_manager(data_dir: Path) -> DatabaseManager:
with patch.object(
DatabaseManager, "_check_encryption_available", return_value=True
):
manager = DatabaseManager()
manager.data_dir = data_dir
return manager
@pytest.fixture
def manager(tmp_path: Path) -> DatabaseManager:
return _new_manager(tmp_path)
def _existing_db(manager: DatabaseManager, username: str) -> Path:
db_path = manager._get_user_db_path(username)
db_path.touch()
return db_path
def _initialize_epoch(db_path: Path) -> str:
with acquire_rekey_lock(db_path):
return rekey_lock_module.read_or_initialize_rekey_epoch(db_path)
def test_cold_open_records_the_epoch_it_ran_under(
manager: DatabaseManager,
) -> None:
epoch = _initialize_epoch(_existing_db(manager, "alice"))
engine = MagicMock()
with (
patch.object(manager, "_open_user_database_cold", return_value=engine),
patch.object(manager, "_run_phase2_rekey"),
capture_login_proof() as proof,
):
opened = manager.open_user_database("alice", "password")
assert opened is engine
assert (proof.username, proof.epoch) == ("alice", epoch)
def test_cache_claim_records_the_claimed_generation_epoch(
manager: DatabaseManager,
) -> None:
epoch = _initialize_epoch(_existing_db(manager, "alice"))
engine = MagicMock()
manager._cache_connection(
"alice", manager._make_connection_cache_entry(engine, "password", epoch)
)
with (
patch.object(manager, "_open_user_database_cold") as cold_open,
capture_login_proof() as proof,
):
opened = manager.open_user_database("alice", "password")
assert opened is engine
cold_open.assert_not_called()
assert (proof.username, proof.epoch) == ("alice", epoch)
def test_nothing_is_recorded_outside_a_capture_block(
manager: DatabaseManager,
) -> None:
_initialize_epoch(_existing_db(manager, "alice"))
with (
patch.object(
manager, "_open_user_database_cold", return_value=MagicMock()
),
patch.object(manager, "_run_phase2_rekey"),
):
manager.open_user_database("alice", "password")
with capture_login_proof() as proof:
pass
assert (proof.username, proof.epoch) == (None, None)
def test_outer_open_wins_over_the_phase2_reentry(
manager: DatabaseManager,
) -> None:
epoch = _initialize_epoch(_existing_db(manager, "alice"))
def failed_reentry(username: str, _password: str) -> None:
# Phase 2 re-enters open_user_database on this thread; a failed
# re-entry records "no proof" before the outer call returns.
encrypted_db._record_login_proof(username, None)
with (
patch.object(
manager, "_open_user_database_cold", return_value=MagicMock()
),
patch.object(manager, "_run_phase2_rekey", side_effect=failed_reentry),
capture_login_proof() as proof,
):
manager.open_user_database("alice", "password")
assert proof.epoch == epoch
def test_cold_open_is_discarded_when_the_epoch_moves_underneath_it(
manager: DatabaseManager,
) -> None:
db_path = _existing_db(manager, "alice")
_initialize_epoch(db_path)
engine = MagicMock()
def cold_open_racing_a_publisher(*_args, **_kwargs) -> MagicMock:
# The sidecar is held by this open; a publisher that bypasses it
# (or a durable write this process cannot see coming) moves the
# committed epoch while the engine is being built.
rekey_lock_module.advance_rekey_epoch(db_path)
return engine
with (
patch.object(
manager,
"_open_user_database_cold",
side_effect=cold_open_racing_a_publisher,
),
patch.object(manager, "_run_phase2_rekey") as phase2,
capture_login_proof() as proof,
):
# The password opened the database, so this is not a wrong
# password: the open fails closed with the error the login route
# answers with 503 (lockout counter untouched), never the None a
# wrong password returns (401, counted toward lockout).
with pytest.raises(RekeyRecoveryRequiredError):
manager.open_user_database("alice", "password")
# The engine built under the superseded epoch is never published.
engine.dispose.assert_called_once_with()
assert "alice" not in manager.connections
phase2.assert_not_called()
assert proof.epoch is None
def _make_epoch_file_unreadable(db_path: Path) -> None:
# A directory where the epoch file should be: read_text raises
# IsADirectoryError, an OSError other than FileNotFoundError and not
# a PermissionError, so the reader raises RekeyEpochUnreadableError
# on the first attempt (the same outcome as EMFILE or EIO).
epoch_file = db_path.with_name(f"{db_path.name}.rekey.epoch")
epoch_file.unlink()
epoch_file.mkdir()
def _remove_committed_epoch(db_path: Path) -> None:
# No committed and no pending epoch: the state is read, and does not
# vouch for the epoch the open ran under.
db_path.with_name(f"{db_path.name}.rekey.epoch").unlink()
@pytest.mark.parametrize(
("disturb", "expected_error"),
[
pytest.param(
_make_epoch_file_unreadable,
RekeyEpochUnreadableError,
id="epoch-file-unreadable",
),
pytest.param(
rekey_lock_module.begin_rekey_epoch,
RekeyRecoveryRequiredError,
id="pending-epoch-appeared",
),
pytest.param(
_remove_committed_epoch,
RekeyRecoveryRequiredError,
id="committed-epoch-removed",
),
],
)
def test_post_open_epoch_recheck_that_cannot_vouch_fails_closed(
manager: DatabaseManager, disturb, expected_error
) -> None:
# The cold open proved the password. If the re-read of the epoch
# right after it fails, or finds durable state that does not vouch,
# nothing is known about the credential: the open must raise the
# RekeyOperationalError the login route answers with 503 (lockout
# counter untouched), never return the (None, ...) a wrong password
# returns (401, counted toward lockout).
db_path = _existing_db(manager, "alice")
_initialize_epoch(db_path)
engine = MagicMock()
def cold_open_then_disturb(*_args, **_kwargs) -> MagicMock:
disturb(db_path)
return engine
with (
patch.object(
manager,
"_open_user_database_cold",
side_effect=cold_open_then_disturb,
),
patch.object(manager, "_run_phase2_rekey") as phase2,
capture_login_proof() as proof,
):
with pytest.raises(expected_error):
manager.open_user_database("alice", "password")
# The engine is still discarded unpublished.
engine.dispose.assert_called_once_with()
assert "alice" not in manager.connections
phase2.assert_not_called()
assert proof.epoch is None
def test_pending_recovery_verifies_the_candidate_before_finalizing(
manager: DatabaseManager,
) -> None:
db_path = _existing_db(manager, "alice")
committed = _initialize_epoch(db_path)
with acquire_rekey_lock(db_path):
pending = rekey_lock_module.begin_rekey_epoch(db_path)
connection = MagicMock()
with (
patch.object(
manager, "_make_sqlcipher_connection", return_value=connection
),
patch.object(
manager,
"_verify_rekey_candidate",
side_effect=_RekeyVerificationError("quick check"),
) as verify,
patch.object(
manager, "_open_user_database_cold", return_value=MagicMock()
) as cold_open,
patch.object(manager, "_run_phase2_rekey"),
):
# A password that opens the file but whose candidate key fails
# verification must not finalize the pending epoch.
with pytest.raises(RekeyRecoveryRequiredError):
manager.open_user_database("alice", "password")
verify.assert_called_once_with(connection, db_path)
cold_open.assert_not_called()
state = rekey_lock_module.read_rekey_epoch_state(db_path)
assert (state.committed_epoch, state.pending_epoch) == (committed, pending)
def test_concurrent_first_login_records_the_epoch_of_the_engine_it_joins(
manager: DatabaseManager,
) -> None:
# Two first logins race: this one's cache probe missed (nothing cached
# yet), then it waited on the per-user init lock while the other login
# cold-opened and cached the engine. Inside the lock it finds that
# engine, verifies the password against it, and returns it -- the
# proof must carry the epoch it verified under, like every other path.
epoch = _initialize_epoch(_existing_db(manager, "alice"))
engine = MagicMock()
real_init_lock = manager._get_init_lock("alice")
class _OtherLoginFinishesFirst:
def acquire(self, *args, **kwargs):
acquired = real_init_lock.acquire(*args, **kwargs)
if acquired:
manager._cache_connection(
"alice",
manager._make_connection_cache_entry(
engine, "password", epoch
),
)
return acquired
def release(self):
real_init_lock.release()
with (
patch.object(
manager, "_get_init_lock", return_value=_OtherLoginFinishesFirst()
),
patch.object(manager, "_open_user_database_cold") as cold_open,
patch.object(manager, "_run_phase2_rekey") as phase2,
capture_login_proof() as proof,
):
opened = manager.open_user_database("alice", "password")
assert opened is engine
cold_open.assert_not_called()
phase2.assert_not_called()
assert (proof.username, proof.epoch) == ("alice", epoch)
# The autouse epoch shim relaxes proven_epoch_for for test doubles; these
# two pin the real method.
@pytest.mark.real_durable_epoch
def test_proven_epoch_for_returns_the_epoch_proved_for_that_user() -> None:
proof = LoginProof()
proof.username = "alice"
proof.epoch = "e1"
assert proof.proven_epoch_for("alice") == "e1"
@pytest.mark.real_durable_epoch
@pytest.mark.parametrize(
("recorded_user", "recorded_epoch"),
[(None, None), ("mallory", "e1"), ("alice", None)],
)
def test_proven_epoch_for_refuses_a_missing_or_foreign_proof(
recorded_user: str | None, recorded_epoch: str | None
) -> None:
# A proof for another user (or none at all) must refuse, not quietly
# let the session skip the straddle check.
proof = LoginProof()
proof.username = recorded_user
proof.epoch = recorded_epoch
with pytest.raises(MissingLoginProofError):
proof.proven_epoch_for("alice")