~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
"""The research-status, details, and report endpoints must not disclose
server-side file paths.
Five endpoints return a research row's data to an authenticated user:
``GET /history/status/{research_id}``,
``GET /research/api/status/{research_id}``,
``GET /api/research/{research_id}/status`` (the endpoint the frontend
polls), ``GET /api/research/{research_id}`` (details), and
``GET /api/report/{research_id}`` (report). All five used to return the
row's ``report_path`` — the absolute server-side filesystem path of the
generated report file — either at the top level or nested inside
``metadata``. The codebase already treats exactly this class of
disclosure as a bug: ``/library/api/check-downloads`` deliberately
withholds ``document.file_path`` because it "leaks directory layout to
any authenticated user". No client reads ``report_path`` from any of
the five. Each test also asserts the sentinel path is absent from the
whole response body, not only that the key is missing, and a
router-wide AST guard below fails on any dict literal in
``web/routers/`` that carries the key; non-literal shapes (a subscript
assignment, ``dict(report_path=...)``) are what the body assertions
cover.
A second channel exists on ``GET /history/status/{research_id}``: the
``progress_log`` column. Rows written by <=v0.4.4 embed the completion
entry's ``metadata.report_path`` — the absolute server-side report
path — inside that column, and the endpoint used to return the raw
column verbatim as well as parsing it into ``log``. No client reads the
raw field, so it is now omitted and the parsed entries are scrubbed.
"""
import ast
import json
from contextlib import contextmanager
from pathlib import Path
from unittest.mock import patch
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool
_HISTORY = "local_deep_research.web.routers.history"
_API = "local_deep_research.web.routers.api"
_RESEARCH = "local_deep_research.web.routers.research"
_ENGINE_KW = {
"connect_args": {"check_same_thread": False},
"poolclass": StaticPool,
}
@pytest.fixture
def db():
"""A real in-memory database with the full schema; yields a session."""
from local_deep_research.database.models import Base
engine = create_engine("sqlite:///:memory:", **_ENGINE_KW)
Base.metadata.create_all(engine)
session = sessionmaker(bind=engine)()
try:
yield session
finally:
session.close()
engine.dispose()
def _patch_session(module, session):
@contextmanager
def _ctx(*_args, **_kwargs):
yield session
return patch(f"{module}.get_user_db_session", _ctx)
def _add_research(session, rid, report_path=None, **extra):
from local_deep_research.database.models import ResearchHistory
row = ResearchHistory(
id=rid,
query="q",
mode="quick",
status="completed",
created_at="2025-01-01T00:00:00+00:00",
report_path=report_path,
**extra,
)
session.add(row)
session.commit()
return row
def test_history_status_omits_report_path(authenticated_client, db):
sentinel = "/var/lib/ldr-private/reports/abc123.md"
_add_research(db, "leaky-1", report_path=sentinel)
with (
_patch_session(_HISTORY, db),
patch(f"{_HISTORY}.get_active_research_snapshot", return_value=None),
):
response = authenticated_client.get("/history/status/leaky-1")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "report_path" not in data, (
"history status discloses the absolute server-side report_path"
)
# The useful fields stay.
assert data["id"] == "leaky-1"
assert data["status"] == "completed"
def test_legacy_api_status_omits_report_path(authenticated_client, db):
sentinel = "/var/lib/ldr-private/reports/abc123.md"
_add_research(db, "leaky-2", report_path=sentinel)
with _patch_session(_API, db):
response = authenticated_client.get("/research/api/status/leaky-2")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "report_path" not in data, (
"legacy api status discloses the absolute server-side report_path"
)
assert data["status"] == "completed"
def test_research_status_omits_report_path(authenticated_client, db):
"""``GET /api/research/{id}/status`` — the endpoint the frontend polls."""
sentinel = "/var/lib/ldr-private/reports/abc123.md"
_add_research(db, "leaky-3", report_path=sentinel)
with _patch_session(_RESEARCH, db):
response = authenticated_client.get("/api/research/leaky-3/status")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "report_path" not in data, (
"research status discloses the absolute server-side report_path"
)
assert data["status"] == "completed"
def test_research_details_omits_report_path(authenticated_client, db):
sentinel = "/var/lib/ldr-private/reports/abc123.md"
_add_research(db, "leaky-4", report_path=sentinel)
with _patch_session(_RESEARCH, db):
response = authenticated_client.get("/api/research/leaky-4")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "report_path" not in data, (
"research details discloses the absolute server-side report_path"
)
assert data["id"] == "leaky-4"
assert data["status"] == "completed"
def test_research_report_omits_report_path(authenticated_client, db):
sentinel = "/var/lib/ldr-private/reports/abc123.md"
_add_research(
db, "leaky-5", report_path=sentinel, report_content="The answer."
)
with _patch_session(_RESEARCH, db):
response = authenticated_client.get("/api/report/leaky-5")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "report_path" not in data["metadata"], (
"research report discloses the absolute server-side report_path"
)
# The useful field stays.
assert data["content"] == "The answer."
@pytest.mark.parametrize(
"module,url",
[
(_API, "/research/api/status/legacy-error"),
(_RESEARCH, "/api/research/legacy-error"),
(_RESEARCH, "/api/research/legacy-error/status"),
(_RESEARCH, "/api/report/legacy-error"),
],
)
@pytest.mark.parametrize(
"json_encoded", [False, True], ids=["dict", "json-string"]
)
@pytest.mark.parametrize("error_kind", ["legacy", "known", "appended-detail"])
def test_error_metadata_preserves_only_safe_messages(
authenticated_client, db, module, url, json_encoded, error_kind
):
private_path = "/var/lib/ldr-private/reports/legacy-error.md"
known = "Authentication with the configured LLM provider failed."
errors = {
"legacy": f"[Errno 13] Permission denied: '{private_path}'",
"known": known,
"appended-detail": f"{known} | Details: {private_path}",
}
research_meta = {
"phase": "error",
"error": errors[error_kind],
}
row = _add_research(
db,
"legacy-error",
report_content="The answer.",
research_meta=json.dumps(research_meta)
if json_encoded
else research_meta,
)
row.status = "failed"
db.commit()
with _patch_session(module, db):
response = authenticated_client.get(url)
assert response.status_code == 200, response.text[:300]
assert private_path not in response.text
metadata = response.get_json()["metadata"]
assert metadata["error"] == (
known
if error_kind == "known"
else "Research failed. Check the server logs for details."
)
assert metadata["phase"] == "error"
def test_history_status_sanitizes_legacy_text_progress_log(
authenticated_client, db
):
"""A progress_log stored as a JSON string: the shape json.loads parses.
The <=v0.4.4 writer persisted the completion entry as
``{"time": ..., "message": ..., "progress": 100, "metadata":
{"phase": "complete", "report_path": <absolute path>}}``. This case
seeds ``progress_log`` as a JSON string — the one shape whose
``json.loads`` in the handler succeeds, so the parsed entries reach
the scrub. The raw column is omitted regardless of shape; see
``test_history_status_omits_production_shaped_progress_log`` below
for the list shape every writer actually produces (production rows,
and legacy rows too once read back through today's JSON-typed
column), where the parse raises instead and only the field removal
protects the row.
"""
sentinel = "/var/lib/ldr-private/reports/legacy123.md"
_add_research(
db,
"leaky-6",
progress_log=json.dumps(
[
{
"time": "2025-01-01T00:00:01+00:00",
"message": "Research completed successfully",
"progress": 100,
"metadata": {
"phase": "complete",
"report_path": sentinel,
},
},
{
"time": "2025-01-01T00:00:02+00:00",
"message": "path at entry top level",
"progress": 100,
"report_path": sentinel,
},
]
),
)
with (
_patch_session(_HISTORY, db),
patch(f"{_HISTORY}.get_active_research_snapshot", return_value=None),
):
response = authenticated_client.get("/history/status/leaky-6")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "progress_log" not in data, (
"history status returns the raw progress_log column, which "
"leaks the legacy completion entry's report_path"
)
assert "report_path" not in json.dumps(data["log"]), (
"history status discloses report_path inside parsed log entries"
)
# The sanitized log still serves the UI.
assert len(data["log"]) == 2
assert data["log"][0]["metadata"] == {"phase": "complete"}
assert data["id"] == "leaky-6"
assert data["status"] == "completed"
def test_history_status_omits_production_shaped_progress_log(
authenticated_client, db
):
"""The shape every writer actually produces: a list, not a string.
``research.py``, ``chat.py`` and ``followup.py`` all persist
``progress_log`` as a Python list through the ORM's JSON column, so
``research.progress_log`` reads back as a list — a legacy row is no
different, since SQLAlchemy's JSON column deserializes whatever
valid JSON is stored regardless of which version wrote it.
``json.loads`` in the handler raises ``TypeError`` on a list, so the
parsed ``log`` degrades to ``[]`` before the scrub ever runs on it.
The field removal, not the scrub, is what keeps this — the real,
shipped — shape safe.
"""
sentinel = "/var/lib/ldr-private/reports/legacy789.md"
_add_research(
db,
"leaky-7",
progress_log=[
{
"time": "2025-01-01T00:00:01+00:00",
"message": "Research completed successfully",
"progress": 100,
"metadata": {
"phase": "complete",
"report_path": sentinel,
},
}
],
)
with (
_patch_session(_HISTORY, db),
patch(f"{_HISTORY}.get_active_research_snapshot", return_value=None),
):
response = authenticated_client.get("/history/status/leaky-7")
assert response.status_code == 200, response.text[:300]
assert sentinel not in response.text, "server path leaked in the body"
data = response.get_json()
assert "progress_log" not in data, (
"history status returns the raw progress_log column, which "
"leaks the legacy completion entry's report_path"
)
assert data["id"] == "leaky-7"
assert data["status"] == "completed"
def test_no_router_response_returns_report_path():
"""AST guard: no router response dict may carry a ``report_path`` key.
Pins the literal-key form of the invariant for every handler in
``web/routers/``, not just the five exercised by name above. It
catches a ``"report_path": ...`` entry at any nesting depth; the
value assertions in the tests above cover the non-literal shapes.
"""
routers_dir = (
Path(__file__).resolve().parents[2]
/ "src"
/ "local_deep_research"
/ "web"
/ "routers"
)
files = sorted(routers_dir.glob("*.py"))
assert len(files) >= 20, f"router sweep found too few files: {files}"
offenders = []
for path in files:
tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
for node in ast.walk(tree):
if isinstance(node, ast.Dict):
offenders.extend(
f"{path.name}:{k.lineno}"
for k in node.keys
if isinstance(k, ast.Constant) and k.value == "report_path"
)
assert not offenders, f"report_path key found in: {offenders}"