~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
"""Unit coverage for the password-verifier PRIMITIVE used by the
cached-connection fix in PR #5596.
Companion to ``test_login_cached_connection_password.py`` /
``test_login_cached_connection_password_extra.py``, which exercise the
verifier through the full ``DatabaseManager.open_user_database`` /
``create_user_database`` flow (real SQLCipher opens). This file instead pins
down the primitive itself -- ``_compute_verifier_digest``, ``_make_verifier``,
``_verifier_matches``, ``_password_matches_cached``,
``_record_password_verifier`` and ``_cached_engine_trusted`` -- in isolation,
with no database I/O and no SQLCipher dependency, so it runs fast and stays
green in environments without SQLCipher installed.
Each ``DatabaseManager`` under test is built via ``__new__`` so
``DatabaseManager.__init__`` (which probes for SQLCipher and can raise
``RuntimeError`` when it isn't installed and unencrypted mode isn't
explicitly allowed) never runs. The fixture initializes the verifier, durable
epoch, and isolated data-directory state those methods touch.
"""
import hmac
import secrets
import threading
from pathlib import Path
from unittest.mock import MagicMock, patch
import pytest
from local_deep_research.database.encrypted_db import DatabaseManager
from local_deep_research.database.rekey_lock import (
acquire_rekey_lock,
read_or_initialize_rekey_epoch,
)
def make_manager(
data_dir: Path, has_encryption: bool = True
) -> DatabaseManager:
"""Build a bare ``DatabaseManager`` with only the verifier-related state
initialised, bypassing ``__init__`` (and therefore the SQLCipher probe)
entirely."""
mgr = DatabaseManager.__new__(DatabaseManager)
mgr.connections = {}
mgr._password_verifiers = {}
mgr._connection_epochs = {}
mgr._rekey_locks = {}
mgr._verifier_key = secrets.token_bytes(32)
mgr._connections_lock = threading.RLock()
mgr._data_dir_override = data_dir
mgr._initialized_data_dirs = set()
mgr.has_encryption = has_encryption
return mgr
# ---------------------------------------------------------------------------
# 1. A recorded verifier matches its own password and rejects any other.
# ---------------------------------------------------------------------------
def test_verifier_matches_own_password_and_rejects_others(tmp_path: Path):
mgr = make_manager(tmp_path)
username = "user_own_password"
password = "CorrectHorseBattery1!" # noqa: S105
mgr._record_password_verifier(username, password)
with mgr._connections_lock:
assert mgr._verifier_matches(username, password) is True
assert mgr._verifier_matches(username, "totally-wrong") is False
# A single trailing/near-miss character must still be rejected.
assert mgr._verifier_matches(username, password[:-1]) is False
assert mgr._verifier_matches(username, password + "x") is False
assert mgr._verifier_matches(username, "") is False
# ---------------------------------------------------------------------------
# 2. Same password, different usernames -> different (salt, digest) pairs,
# each still matches its own password (unlinkability).
# ---------------------------------------------------------------------------
def test_same_password_different_usernames_are_unlinkable(tmp_path: Path):
mgr = make_manager(tmp_path)
password = "SharedPassword1!" # noqa: S105
mgr._record_password_verifier("alice", password)
mgr._record_password_verifier("bob", password)
salt_a, digest_a = mgr._password_verifiers["alice"]
salt_b, digest_b = mgr._password_verifiers["bob"]
assert isinstance(salt_a, bytes) and len(salt_a) == 16
assert isinstance(salt_b, bytes) and len(salt_b) == 16
assert salt_a != salt_b, "per-entry salts must differ (unlinkability)"
assert digest_a != digest_b, (
"digests for the same password must differ across users because "
"the salts differ"
)
with mgr._connections_lock:
assert mgr._verifier_matches("alice", password) is True
assert mgr._verifier_matches("bob", password) is True
# Cross-check: neither entry is somehow tied to the other's salt.
cross = hmac.new(
mgr._verifier_key, salt_b + password.encode("utf-8"), "sha256"
).digest()
assert cross == digest_b
assert cross != digest_a
def test_make_verifier_produces_fresh_salt_each_call(tmp_path: Path):
mgr = make_manager(tmp_path)
salt1, digest1 = mgr._make_verifier("SamePassword1!")
salt2, digest2 = mgr._make_verifier("SamePassword1!")
assert salt1 != salt2, "two calls must not reuse a salt"
assert digest1 != digest2
# ---------------------------------------------------------------------------
# 3. Unicode, very long, whitespace- and case-distinct passwords are treated
# as DISTINCT and each still matches correctly.
# ---------------------------------------------------------------------------
UNUSUAL_PASSWORDS = {
"accented": "pässwörd Ñoño Café",
"emoji": "correct-horse-battery-staple🔒🐴🔋📎",
"cjk": "正确马电池订书机安全密码",
"mixed_script": "Пароль123密码🔥",
"very_long": "x" * 100_000,
"long_unicode": "é" * 20_000,
"case_lower": "password1!",
"case_title": "Password1!",
"case_upper": "PASSWORD1!",
"no_trailing_ws": "Password1!",
"trailing_space": "Password1! ",
"leading_space": " Password1!",
"trailing_tab": "Password1!\t",
"trailing_newline": "Password1!\n",
"empty": "",
"whitespace_only": " ",
}
def test_unusual_passwords_each_match_only_their_own_username(tmp_path: Path):
mgr = make_manager(tmp_path)
for name, password in UNUSUAL_PASSWORDS.items():
mgr._record_password_verifier(f"user_{name}", password)
with mgr._connections_lock:
# Every password matches its own recorded verifier.
for name, password in UNUSUAL_PASSWORDS.items():
assert mgr._verifier_matches(f"user_{name}", password) is True, (
f"{name!r} should match its own verifier"
)
# Passwords that differ only by case, or only by leading/trailing
# whitespace, must be treated as fully distinct -- no verifier for
# one should match another's password.
confusable_groups = [
["case_lower", "case_title", "case_upper"],
[
"no_trailing_ws",
"trailing_space",
"leading_space",
"trailing_tab",
"trailing_newline",
],
["empty", "whitespace_only"],
]
for group in confusable_groups:
for owner in group:
for other in group:
if owner == other:
continue
assert (
mgr._verifier_matches(
f"user_{owner}", UNUSUAL_PASSWORDS[other]
)
is False
), (
f"user_{owner}'s verifier must not accept "
f"{other}'s password ({UNUSUAL_PASSWORDS[other]!r})"
)
# A very long password with a single trailing character changed must
# not match (rules out any truncation in the digest computation).
truncated_long = UNUSUAL_PASSWORDS["very_long"][:-1]
assert mgr._verifier_matches("user_very_long", truncated_long) is False
appended_long = UNUSUAL_PASSWORDS["very_long"] + "y"
assert mgr._verifier_matches("user_very_long", appended_long) is False
# ---------------------------------------------------------------------------
# 4. Fail-closed: no verifier recorded (or popped) -> False, never True.
# ---------------------------------------------------------------------------
def test_fail_closed_when_no_verifier_was_ever_recorded(tmp_path: Path):
mgr = make_manager(tmp_path)
with mgr._connections_lock:
assert mgr._verifier_matches("never_registered", "anything") is False
assert mgr._verifier_matches("never_registered", "") is False
assert mgr._password_matches_cached("never_registered", "anything") is False
def test_fail_closed_after_verifier_is_popped(tmp_path: Path):
mgr = make_manager(tmp_path)
username = "user_popped"
password = "CorrectHorseBattery1!" # noqa: S105
db_path = mgr._get_user_db_path(username)
db_path.touch()
with acquire_rekey_lock(db_path):
epoch = read_or_initialize_rekey_epoch(db_path)
mgr.connections[username] = MagicMock()
mgr._record_password_verifier(username, password)
assert mgr._connection_epochs[username] == epoch
# Sanity: it matches before the pop.
assert mgr._password_matches_cached(username, password) is True
mgr._password_verifiers.pop(username, None)
with mgr._connections_lock:
assert mgr._verifier_matches(username, password) is False
assert mgr._password_matches_cached(username, password) is False
# ---------------------------------------------------------------------------
# 5. Re-recording replaces the verifier: new salt/digest, old password no
# longer matches once re-recorded under a new password.
# ---------------------------------------------------------------------------
def test_rerecording_replaces_verifier_and_invalidates_old_password(
tmp_path: Path,
):
mgr = make_manager(tmp_path)
username = "user_rerecord"
old_password = "OldPassword1!" # noqa: S105
new_password = "NewPassword2!" # noqa: S105
mgr._record_password_verifier(username, old_password)
old_salt, old_digest = mgr._password_verifiers[username]
mgr._record_password_verifier(username, new_password)
new_salt, new_digest = mgr._password_verifiers[username]
assert (new_salt, new_digest) != (old_salt, old_digest), (
"re-recording must produce a fresh salt/digest pair"
)
with mgr._connections_lock:
assert mgr._verifier_matches(username, new_password) is True
assert mgr._verifier_matches(username, old_password) is False
def test_rerecording_same_password_still_rotates_salt(tmp_path: Path):
"""Even re-recording the SAME password must not silently keep the old
salt/digest -- _record_password_verifier always calls _make_verifier."""
mgr = make_manager(tmp_path)
username = "user_same_pw_rerecord"
password = "SamePassword1!" # noqa: S105
mgr._record_password_verifier(username, password)
salt1, digest1 = mgr._password_verifiers[username]
mgr._record_password_verifier(username, password)
salt2, digest2 = mgr._password_verifiers[username]
assert salt1 != salt2
assert digest1 != digest2
assert mgr._verifier_matches(username, password) is True
# ---------------------------------------------------------------------------
# 6. _cached_engine_trusted: unencrypted mode always trusts; encrypted mode
# defers to the verifier (including its fail-closed behaviour).
# ---------------------------------------------------------------------------
def test_cached_engine_trusted_unencrypted_mode_ignores_password(
tmp_path: Path,
): # DevSkim: ignore DS101155 - "trusted" is a test-name word; no TLS/certificate code here
mgr = make_manager(tmp_path, has_encryption=False)
username = "user_unencrypted"
current_epoch = "current-epoch"
mgr._connection_epochs[username] = current_epoch
mgr._connection_epochs["some-other-user"] = current_epoch
# No verifier is ever recorded in this test -- unencrypted mode must not
# need one.
with mgr._connections_lock:
assert (
mgr._cached_engine_trusted(username, "any-password", current_epoch)
is True
)
assert mgr._cached_engine_trusted(username, "", current_epoch) is True
assert (
mgr._cached_engine_trusted(
username, "unencrypted-mode", current_epoch
)
is True
)
assert (
mgr._cached_engine_trusted(
"some-other-user", "dummy", current_epoch
)
is True
)
def test_cached_engine_trusted_encrypted_mode_defers_to_verifier(
tmp_path: Path,
):
mgr = make_manager(tmp_path, has_encryption=True)
username = "user_encrypted"
password = "CorrectHorseBattery1!" # noqa: S105
mgr._record_password_verifier(username, password)
current_epoch = "current-epoch"
mgr._connection_epochs[username] = current_epoch
with mgr._connections_lock:
assert (
mgr._cached_engine_trusted(username, password, current_epoch)
is True
)
assert (
mgr._cached_engine_trusted(
username, "wrong-password", current_epoch
)
is False
)
# And fails closed once the verifier is gone, same as _verifier_matches.
mgr._password_verifiers.pop(username, None)
with mgr._connections_lock:
assert (
mgr._cached_engine_trusted(username, password, current_epoch)
is False
)
# ---------------------------------------------------------------------------
# 7. _verifier_matches compares digests with hmac.compare_digest
# (constant-time), not a short-circuiting `==`.
# ---------------------------------------------------------------------------
def test_verifier_matches_uses_hmac_compare_digest(tmp_path: Path):
mgr = make_manager(tmp_path)
username = "user_constant_time"
password = "CorrectHorseBattery1!" # noqa: S105
mgr._record_password_verifier(username, password)
salt, expected_digest = mgr._password_verifiers[username]
with patch.object(hmac, "compare_digest", wraps=hmac.compare_digest) as spy:
with mgr._connections_lock:
match_result = mgr._verifier_matches(username, password)
mismatch_result = mgr._verifier_matches(username, "wrong")
assert match_result is True
assert mismatch_result is False
# Called exactly once per _verifier_matches invocation -- both the
# matching and the mismatching comparison must go through
# hmac.compare_digest rather than a data-dependent `==`.
assert spy.call_count == 2
match_args = spy.call_args_list[0].args
computed_for_match = mgr._compute_verifier_digest(salt, password)
assert match_args[0] == computed_for_match
assert match_args[1] == expected_digest
mismatch_args = spy.call_args_list[1].args
computed_for_mismatch = mgr._compute_verifier_digest(salt, "wrong")
assert mismatch_args[0] == computed_for_mismatch
assert mismatch_args[1] == expected_digest
def test_verifier_matches_never_uses_plain_equality_shortcut(tmp_path: Path):
"""Guard against a regression to `computed == expected`: patch
hmac.compare_digest to always return False and confirm the verifier
result follows the patched function rather than the underlying bytes
equality (which would still be True for a genuinely matching password).
"""
mgr = make_manager(tmp_path)
username = "user_forced_false"
password = "CorrectHorseBattery1!" # noqa: S105
mgr._record_password_verifier(username, password)
with patch.object(hmac, "compare_digest", return_value=False):
with mgr._connections_lock:
assert mgr._verifier_matches(username, password) is False
# ---------------------------------------------------------------------------
# Extra: independence between test cases / fresh manager per test is assumed
# throughout via the `make_manager()` factory (no shared fixture state).
# ---------------------------------------------------------------------------
@pytest.mark.parametrize("has_encryption", [True, False])
def test_fresh_managers_do_not_share_verifier_keys(
has_encryption, tmp_path: Path
):
"""Sanity check that each manager gets its own random verifier key, so
a digest computed by one manager is meaningless to another."""
mgr1 = make_manager(tmp_path / "first", has_encryption=has_encryption)
mgr2 = make_manager(tmp_path / "second", has_encryption=has_encryption)
assert mgr1._verifier_key != mgr2._verifier_key
username = "user_cross_manager"
password = "CorrectHorseBattery1!" # noqa: S105
mgr1._record_password_verifier(username, password)
salt, digest = mgr1._password_verifiers[username]
mgr2._password_verifiers[username] = (salt, digest)
with mgr2._connections_lock:
assert mgr2._verifier_matches(username, password) is False, (
"a verifier recorded under one manager's key must not validate "
"under another manager's key"
)