~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
"""Cold-path artifact hygiene and edge-password depth at real SQLCipher level.
Incident context (PR #5596): the fix made every cache hit fall through to a
key-validating cold open when the verifier does not match. That moves the
cold open onto the hot path of every WRONG-password attempt (an attacker's
guess is now a full PBKDF2 derivation + SQLCipher verify every time), so
the cold path's on-disk hygiene is now part of the security boundary:
* a rejected cold attempt must leave the filesystem exactly as it found it
(no -wal/-shm/-journal droppings, no byte changes, no permission drift,
nothing a forensic or a subsequent open could trip over);
* it must leave the manager exactly as it found it (no engine, no verifier
cached from a FAILED attempt -- a cached verifier matching a wrong
password would re-arm the original incident);
* repeated failures must not poison the next CORRECT open;
* passwords that are byte-distinct but "look equivalent" (NFC vs NFD
unicode, embedded NUL, 4096 chars) must be treated as fully distinct
keys, cold AND warm.
``test_login_cached_connection_password.py::test_wrong_password_rejected_
when_connection_is_cold`` pins only the None return value.
``test_password_verifier_primitive.py`` pins unicode/case/whitespace
distinctness of the verifier DIGEST; this file pins the same distinctness
against real PBKDF2+SQLCipher keys and real files. ``test_db_file_
permissions.py`` pins 0600 on the unencrypted CREATE path only.
"""
import hashlib
import os
import unicodedata
import uuid
from pathlib import Path
import pytest
from sqlalchemy import text
from local_deep_research.database.encrypted_db import DatabaseManager
# Module-level gate. Without a working SQLCipher build every test below
# is a no-op, and the dozens of in-body ``pytest.skip`` calls let a CI
# lane report this whole battery green having executed nothing. Skipping
# at import time makes the missing dependency one visible, uniform signal
# per module instead.
pytest.importorskip("sqlcipher3", reason="requires SQLCipher (encrypted mode)")
@pytest.fixture
def manager(tmp_path, monkeypatch):
"""A DatabaseManager writing to an isolated data directory.
Same self-contained pattern as the incident tests; KDF iterations are
lowered via the sanctioned test-mode knob (see tests/conftest.py's
``app`` fixture) so the many wrong-password derivations below stay fast.
"""
monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path))
monkeypatch.setenv("LDR_DB_CONFIG_KDF_ITERATIONS", "1000")
mgr = DatabaseManager()
mgr.data_dir = tmp_path
yield mgr
mgr.close_all_databases()
def _dir_fingerprint(root: Path) -> dict:
"""name -> (size, sha256, mode) for every file under root."""
fingerprint = {}
for path in sorted(root.rglob("*")):
if path.is_file():
data = path.read_bytes()
fingerprint[path.name] = (
len(data),
hashlib.sha256(data).hexdigest(),
os.stat(path).st_mode,
)
return fingerprint
def _dir_mode(root: Path) -> int:
return os.stat(root).st_mode
def test_wrong_password_cold_open_leaves_no_new_artifacts(manager):
"""A rejected cold attempt must not create or mutate ANY file.
Snapshot (names, sizes, digests, modes) before vs after must be
identical: no new -wal/-shm/-journal sidecars, no touched header bytes,
no permission drift. The DB directory must stay owner-only (0o700 --
the defense that covers any sidecar SQLite would recreate with umask
perms, see ``_ensure_data_dir``).
"""
if not manager.has_encryption:
pytest.skip("requires SQLCipher (encrypted mode) to be meaningful")
username = f"cold_artifact_{uuid.uuid4().hex[:8]}"
password = "ColdArtifactPassword1!" # noqa: S105
manager.create_user_database(username, password)
manager.close_user_database(username)
before = _dir_fingerprint(manager.data_dir)
dir_mode_before = _dir_mode(manager.data_dir)
db_path = manager._get_user_db_path(username)
assert db_path.exists(), "setup: the closed DB file must exist"
for wrong in ("totally-wrong", "ColdArtifactPassword1! ", "x" * 4096):
assert manager.open_user_database(username, wrong) is None, (
f"wrong password {wrong[:16]!r}... opened the cold database"
)
after = _dir_fingerprint(manager.data_dir)
assert set(after) == set(before), (
f"failed cold attempts changed the file set: "
f"new={sorted(set(after) - set(before))} "
f"gone={sorted(set(before) - set(after))}"
)
changed = [name for name in before if before[name] != after[name]]
assert not changed, (
f"failed cold attempts mutated artifacts: {changed} "
f"(before={ {n: before[n] for n in changed} }, "
f"after={ {n: after[n] for n in changed} })"
)
assert _dir_mode(manager.data_dir) == dir_mode_before
# The owner-only directory must still be owner-only, and the two files
# that exist since creation must still be owner-only (0o600).
assert os.stat(manager.data_dir).st_mode & 0o777 == 0o700
assert os.stat(db_path).st_mode & 0o777 == 0o600
# And the manager kept no trace of the failed attempts.
assert manager.connections == {}
assert manager._password_verifiers == {}
def test_failed_wrong_attempts_do_not_poison_subsequent_correct_open(manager):
"""Several wrong cold attempts (varied shapes) must not poison the next
correct open: the engine opens, reads real data, arms the verifier for
the CORRECT password only, and a subsequent wrong attempt against the
now-warm cache still fails."""
if not manager.has_encryption:
pytest.skip("requires SQLCipher (encrypted mode) to be meaningful")
username = f"poison_{uuid.uuid4().hex[:8]}"
password = "PoisonProofPassword1!" # noqa: S105
engine = manager.create_user_database(username, password)
with engine.begin() as conn:
conn.execute(
text(
"CREATE TABLE gap_d_canary (id INTEGER PRIMARY KEY, note TEXT)"
)
)
conn.execute(
text("INSERT INTO gap_d_canary (id, note) VALUES (1, :note)"),
{"note": "gap-D"},
)
manager.close_user_database(username)
for wrong in ("nope-1", "PoisonProofPassword1!x", "\x00embedded-nul"):
assert manager.open_user_database(username, wrong) is None
reopened = manager.open_user_database(username, password)
assert reopened is not None, "correct open poisoned by earlier failures"
with reopened.connect() as conn:
assert (
conn.execute(
text("SELECT note FROM gap_d_canary WHERE id = 1")
).scalar()
== "gap-D"
)
assert manager._password_matches_cached(username, password) is True
assert manager._password_matches_cached(username, "nope-1") is False
# Warm-cache control after the recovery: still fail-closed.
assert manager.open_user_database(username, "still-wrong") is None
assert manager.connections[username] is reopened
def test_edge_passwords_rejected_cold_and_warm(manager):
"""Byte-distinct but confusable passwords must behave as fully distinct
keys against the real SQLCipher file, both cold and warm:
* NFC vs NFD unicode forms of the same visible string;
* a password with an embedded NUL byte;
* a 4096-character password;
* the empty string is rejected upstream with ValueError and must leave
the filesystem untouched.
Complements test_password_verifier_primitive.py (digest-level
distinctness) by proving the end-to-end key path agrees: PBKDF2 over
the UTF-8 bytes, so any normalization/truncation regression anywhere in
the chain shows up here as an unexpected engine.
"""
if not manager.has_encryption:
pytest.skip("requires SQLCipher (encrypted mode) to be meaningful")
nfc = unicodedata.normalize("NFC", "Cafe\u0301-Contrasenya-1!")
nfd = unicodedata.normalize("NFD", "Cafe\u0301-Contrasenya-1!")
assert nfc != nfd, "setup: NFC and NFD forms must be byte-distinct"
nul_password = "Pass\x00w0rd-With-Nul!"
long_password = "L" * 4096
families = [
(
f"edge_nfc_{uuid.uuid4().hex[:8]}",
nfc,
[nfd, nul_password, long_password],
),
(
f"edge_nfd_{uuid.uuid4().hex[:8]}",
nfd,
[nfc, nul_password, long_password],
),
]
for username, canonical, wrongs in families:
engine = manager.create_user_database(username, canonical)
assert engine is not None
# Warm phase: cache holds an engine opened with the canonical form.
warm_engine = manager.open_user_database(username, canonical)
assert warm_engine is engine
for wrong in wrongs:
assert manager.open_user_database(username, wrong) is None, (
f"warm cache accepted a byte-distinct variant for "
f"{username}: {wrong[:20]!r}..."
)
# The rejections must not have disturbed the legitimate entry.
assert manager.connections[username] is engine
assert manager._password_matches_cached(username, canonical) is True
# Cold phase: no cache, real key validation each time.
manager.close_user_database(username)
for wrong in wrongs:
assert manager.open_user_database(username, wrong) is None, (
f"cold open accepted a byte-distinct variant for "
f"{username}: {wrong[:20]!r}..."
)
assert username not in manager.connections, (
"a rejected variant left an engine cached"
)
assert username not in manager._password_verifiers, (
"a rejected variant left a verifier cached"
)
# Recovery: the canonical form still works after all the rejects.
recovered = manager.open_user_database(username, canonical)
assert recovered is not None
# Empty password: rejected by the key-validity guard with ValueError,
# BEFORE any path resolution or file access.
fingerprint_before = _dir_fingerprint(manager.data_dir)
with pytest.raises(ValueError, match="Invalid encryption key"):
manager.open_user_database(f"edge_empty_{uuid.uuid4().hex[:8]}", "")
assert _dir_fingerprint(manager.data_dir) == fingerprint_before, (
"the empty-password rejection must not touch the filesystem"
)