~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
"""``create_user_database`` must never follow a symlink at the DB path.
``Path.exists()`` follows links and is False for a dangling one, so a link
planted at ``data_dir/ldr_user_<hash>.db`` pointing outside the data dir
passed the guard and the database was written at the link target (#6354).
The path is now refused when it is a link, and the file is materialized
with ``O_CREAT | O_EXCL`` (plus ``O_NOFOLLOW``) so a link planted after the
guard cannot redirect the create either.
"""
import errno
import os
from pathlib import Path
from unittest.mock import patch
import pytest
from local_deep_research.database import encrypted_db
from local_deep_research.database.encrypted_db import (
DatabaseManager,
_create_private_file,
)
from local_deep_research.database.sqlcipher_utils import get_salt_file_path
PASSWORD = "CorrectHorse1!"
@pytest.fixture
def manager(tmp_path, monkeypatch):
monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path / "data"))
mgr = DatabaseManager()
mgr.data_dir = tmp_path / "data"
mgr.data_dir.mkdir(mode=0o700, exist_ok=True)
yield mgr
mgr.close_all_databases()
@pytest.fixture
def victim(tmp_path):
outside = tmp_path / "outside"
outside.mkdir()
return outside / "victim.db"
def _plant_dangling_link(manager, username, victim):
db_path = manager._get_user_db_path(username)
os.symlink(victim, db_path)
assert db_path.is_symlink() and not db_path.exists()
return db_path
class _RecordingConnection:
"""Stand-in for the raw SQLCipher connection that records close()."""
def __init__(self):
self.closed = False
def close(self):
self.closed = True
def test_dangling_symlink_at_db_path_is_refused(manager, victim):
db_path = _plant_dangling_link(manager, "linked_user", victim)
with pytest.raises(ValueError, match="symlink"):
manager.create_user_database("linked_user", PASSWORD)
assert not victim.exists()
assert not get_salt_file_path(db_path).exists()
assert db_path.is_symlink() # the planted link is left for forensics
def test_symlink_planted_after_the_guard_is_not_followed(
manager, victim, monkeypatch
):
if not manager.has_encryption:
pytest.skip("SQLCipher not available; the salt hook is encrypted-only")
username = "raced_user"
db_path = manager._get_user_db_path(username)
real_create_salt = encrypted_db.create_database_salt
def plant_then_create_salt(path):
# Runs after the is_symlink()/exists() guards and before the
# SQLCipher open: the classic check-then-create window.
os.symlink(victim, db_path)
return real_create_salt(path)
monkeypatch.setattr(
encrypted_db, "create_database_salt", plant_then_create_salt
)
with pytest.raises(FileExistsError):
manager.create_user_database(username, PASSWORD)
assert not victim.exists()
# The failure path removed this call's partial artifacts (salt + link).
assert not get_salt_file_path(db_path).exists()
assert not db_path.is_symlink()
def test_unencrypted_fallback_refuses_dangling_symlink(
tmp_path, victim, monkeypatch
):
monkeypatch.setenv("LDR_BOOTSTRAP_ALLOW_UNENCRYPTED", "true")
with (
patch(
"local_deep_research.database.encrypted_db.get_sqlcipher_module",
side_effect=ImportError("No module named 'sqlcipher3'"),
),
patch(
"local_deep_research.database.encrypted_db.get_data_directory",
return_value=tmp_path,
),
):
manager = DatabaseManager()
assert manager.has_encryption is False
db_path = _plant_dangling_link(manager, "plain_user", victim)
with pytest.raises(ValueError, match="symlink"):
manager.create_user_database("plain_user", PASSWORD)
assert not victim.exists()
assert db_path.is_symlink()
def test_file_swapped_after_reservation_is_refused(
manager, victim, monkeypatch
):
"""The window between reserving the file and the library's own open.
_create_private_file cannot hold its descriptor across the database
open: SQLCipher and SQLite take a pathname, and neither binding can ask
for SQLITE_OPEN_NOFOLLOW. A pathname swapped in that window is
therefore caught by the identity of the reserved file rather than
prevented, and the half-created database is refused instead of adopted.
"""
username = "swapped_user"
db_path = manager._get_user_db_path(username)
real_create_private_file = encrypted_db._create_private_file
def reserve_then_swap(path):
reserved = real_create_private_file(path)
if Path(path) == db_path:
# The classic swap: the reserved file is replaced by a link to a
# file outside the data dir, after the reservation and before the
# database open that uses the pathname.
os.unlink(path)
os.symlink(victim, path)
return reserved
monkeypatch.setattr(encrypted_db, "_create_private_file", reserve_then_swap)
with pytest.raises(ValueError, match="was replaced"):
manager.create_user_database(username, PASSWORD)
# Nothing of this attempt is left behind for a retry to adopt.
assert not db_path.exists() and not db_path.is_symlink()
assert not get_salt_file_path(db_path).exists()
assert username not in manager.connections
# Documented residual: the library had already created a database at the
# link target by the time the swap was detected, so for a target that did
# not exist this is detection, not prevention -- the attempt is refused
# and never registered, but the write happened. Preventing it needs the
# database built under a private name and linked into place, a larger
# change than this guard. A target that already holds a non-database
# file is refused by SQLCipher itself ("file is not a database") and
# stays untouched.
assert victim.exists()
def test_reservation_refusal_closes_the_raw_sqlcipher_connection(
manager, victim, monkeypatch
):
"""The identity check must not leak the raw connection it refuses.
The reservation check used to run before the ``try/finally`` that owns
the connection ``create_sqlcipher_connection`` returned, so a refusal
propagated with that connection still open (#6608). It now runs inside
the block, and the refusal closes it before re-raising.
"""
username = "leaked_conn_user"
db_path = manager._get_user_db_path(username)
real_create_private_file = encrypted_db._create_private_file
conn = _RecordingConnection()
# Drive the encrypted branch with a recording stub instead of the real
# SQLCipher binding, so the connection's lifecycle is what is asserted.
manager.has_encryption = True
def reserve_then_swap(path):
reserved = real_create_private_file(path)
if Path(path) == db_path:
os.unlink(path)
os.symlink(victim, path)
return reserved
monkeypatch.setattr(encrypted_db, "_create_private_file", reserve_then_swap)
monkeypatch.setattr(
encrypted_db, "create_sqlcipher_connection", lambda *a, **kw: conn
)
with pytest.raises(ValueError, match="was replaced"):
manager.create_user_database(username, PASSWORD)
# The leaked-connection half of the fix.
assert conn.closed
# The refusal still cleans up after itself, as before.
assert not db_path.exists() and not db_path.is_symlink()
assert not get_salt_file_path(db_path).exists()
assert username not in manager.connections
def test_unencrypted_swap_is_refused_before_the_migrations_write(
tmp_path, victim, monkeypatch
):
"""SQLAlchemy opens the unencrypted database lazily, so the first real
open used to be the migrations' own. A pathname replaced after the
reservation therefore received the whole schema before the identity check
ran. The check now runs on that first open, before anything is written.
"""
import sqlite3
monkeypatch.setenv("LDR_BOOTSTRAP_ALLOW_UNENCRYPTED", "true")
real_create_private_file = encrypted_db._create_private_file
with (
patch(
"local_deep_research.database.encrypted_db.get_sqlcipher_module",
side_effect=ImportError("No module named 'sqlcipher3'"),
),
patch(
"local_deep_research.database.encrypted_db.get_data_directory",
return_value=tmp_path,
),
):
manager = DatabaseManager()
username = "plain_swapped_user"
db_path = manager._get_user_db_path(username)
def reserve_then_swap(path):
reserved = real_create_private_file(path)
if Path(path) == db_path:
os.unlink(path)
os.symlink(victim, path)
return reserved
monkeypatch.setattr(
encrypted_db, "_create_private_file", reserve_then_swap
)
with pytest.raises(ValueError, match="was replaced"):
manager.create_user_database(username, PASSWORD)
assert not db_path.exists() and not db_path.is_symlink()
assert username not in manager.connections
# The open itself may have created the target, as a plain SQLite open
# does; no migration may have written a table into it.
if victim.exists():
with sqlite3.connect(victim) as conn:
tables = conn.execute(
"SELECT count(*) FROM sqlite_master WHERE type = 'table'"
).fetchone()[0]
assert tables == 0
def test_assert_reserved_file_accepts_the_file_it_reserved(tmp_path):
path = tmp_path / "ldr_user_reserved.db"
reserved = _create_private_file(path)
encrypted_db._assert_reserved_file(path, reserved)
def test_assert_reserved_file_rejects_a_missing_path(tmp_path):
path = tmp_path / "ldr_user_gone.db"
reserved = _create_private_file(path)
os.unlink(path)
with pytest.raises(ValueError, match="disappeared"):
encrypted_db._assert_reserved_file(path, reserved)
def test_regular_create_still_works(manager):
engine = manager.create_user_database("plain_create", PASSWORD)
db_path = manager._get_user_db_path("plain_create")
assert db_path.is_file() and not db_path.is_symlink()
assert oct(db_path.stat().st_mode & 0o777) == oct(0o600)
engine.dispose()
manager.close_all_databases()
assert manager.open_user_database("plain_create", PASSWORD) is not None
def test_create_private_file_reports_a_symlink_as_existing(
tmp_path, monkeypatch
):
"""O_NOFOLLOW may answer ELOOP before O_EXCL answers EEXIST; callers see one type."""
def open_with_eloop(*_args, **_kwargs):
raise OSError(errno.ELOOP, "Too many levels of symbolic links")
monkeypatch.setattr(os, "open", open_with_eloop)
with pytest.raises(FileExistsError):
_create_private_file(tmp_path / "ldr_user_x.db")
def test_unencrypted_fallback_cleans_up_when_the_engine_cannot_be_built(
tmp_path, monkeypatch
):
monkeypatch.setenv("LDR_BOOTSTRAP_ALLOW_UNENCRYPTED", "true")
with (
patch(
"local_deep_research.database.encrypted_db.get_sqlcipher_module",
side_effect=ImportError("No module named 'sqlcipher3'"),
),
patch(
"local_deep_research.database.encrypted_db.get_data_directory",
return_value=tmp_path,
),
patch(
"local_deep_research.database.encrypted_db.create_engine",
side_effect=RuntimeError("engine unavailable"),
),
):
manager = DatabaseManager()
db_path = manager._get_user_db_path("engineless_user")
with pytest.raises(RuntimeError):
manager.create_user_database("engineless_user", PASSWORD)
assert not db_path.exists()