~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
"""Cross-user isolation of the retriever and LLM registries.
These are integration-level checks over the seams that previously let a
process-global registration made by one user shadow built-ins or leak into
another user's engine/provider resolution:
* ``search_engines_config.search_config`` must only surface the requesting
user's retrievers (plus shared ones), never another user's names.
* ``config.llm_config.get_llm`` must resolve a per-user registered LLM only
for its owner.
* The egress helper ``_is_user_registered_llm`` must scope its
user-registered-LLM exemption to the owning user.
"""
from unittest.mock import MagicMock, patch
import pytest
from langchain_core.language_models import BaseChatModel
from langchain_core.messages import AIMessage
from langchain_core.outputs import ChatGeneration, ChatResult
class _MockLLM(BaseChatModel):
"""Minimal in-process LLM used as a user-registered provider."""
name: str = "mock"
def _generate(self, messages, **kwargs):
message = AIMessage(content=f"mock:{self.name}")
return ChatResult(generations=[ChatGeneration(message=message)])
@property
def _llm_type(self):
return "mock"
def _p(value, ui="text"):
return {"value": value, "ui_element": ui}
def _snapshot(username):
"""A minimal snapshot: public primary engine, offline-friendly."""
return {
"search.tool": _p("searxng"),
"search.engine.web": {},
"search.engine.library.enabled": _p(False, "checkbox"),
"llm.model": _p("test-model"),
"llm.temperature": _p(0.7, "number"),
"rate_limiting.llm_enabled": _p(False, "checkbox"),
"_username": username,
}
def _private_primary_snapshot(username, primary):
"""Snapshot whose PRIMARY engine is a per-user private retriever, under
the DEFAULT ADAPTIVE egress scope. ADAPTIVE must classify the primary as
private and resolve PRIVATE_ONLY.
"""
return {
# The run's primary IS the private retriever (not a public engine).
"search.tool": _p(primary),
# Default protective scope (adaptive follows the primary).
"policy.egress_scope": _p("adaptive"),
"search.engine.web": {},
"search.engine.library.enabled": _p(False, "checkbox"),
"llm.model": _p("gpt-4o-mini"),
"llm.temperature": _p(0.7, "number"),
"rate_limiting.llm_enabled": _p(False, "checkbox"),
"_username": username,
}
class TestRetrieverConfigLeak:
"""search_config must not leak one user's retrievers to another."""
def test_engine_list_scoped_to_requesting_user(self):
from local_deep_research.web_search_engines.retriever_registry import (
retriever_registry,
)
from local_deep_research.web_search_engines.search_engines_config import (
search_config,
)
try:
retriever_registry.register(
"sec_alice_ret", MagicMock(), username="sec_alice"
)
retriever_registry.register(
"sec_bob_ret", MagicMock(), username="sec_bob"
)
retriever_registry.register("sec_shared_ret", MagicMock())
bob_engines = search_config(settings_snapshot=_snapshot("sec_bob"))
# Bob sees his own + the shared retriever, never Alice's.
assert "sec_bob_ret" in bob_engines
assert "sec_shared_ret" in bob_engines
assert "sec_alice_ret" not in bob_engines
alice_engines = search_config(
settings_snapshot=_snapshot("sec_alice")
)
assert "sec_alice_ret" in alice_engines
assert "sec_shared_ret" in alice_engines
assert "sec_bob_ret" not in alice_engines
finally:
retriever_registry.clear(username="sec_alice")
retriever_registry.clear(username="sec_bob")
retriever_registry.unregister("sec_shared_ret")
class TestGetLlmUserScoping:
"""get_llm resolves a per-user registered LLM only for its owner."""
def test_registered_llm_invisible_to_other_user(self):
from local_deep_research.llm import register_llm, unregister_llm
from local_deep_research.config.llm_config import get_llm
alice_llm = _MockLLM(name="alice")
try:
register_llm("sec_userllm", alice_llm, username="sec_alice")
# Owner resolves her own LLM (wrapper patched to return as-is).
with patch(
"local_deep_research.config.llm_config."
"wrap_llm_without_think_tags",
side_effect=lambda llm, **kw: llm,
):
resolved = get_llm(
provider="sec_userllm",
username="sec_alice",
settings_snapshot=_snapshot("sec_alice"),
)
assert resolved is alice_llm
# A different user does not see it: the name is not a valid
# provider for Bob, so resolution fails closed.
with pytest.raises(ValueError, match="Invalid provider"):
get_llm(
provider="sec_userllm",
username="sec_bob",
settings_snapshot=_snapshot("sec_bob"),
)
finally:
unregister_llm("sec_userllm", username="sec_alice")
def test_username_derived_from_snapshot(self):
"""When no explicit username is passed, get_llm uses the snapshot."""
from local_deep_research.llm import register_llm, unregister_llm
from local_deep_research.config.llm_config import get_llm
alice_llm = _MockLLM(name="alice")
try:
register_llm("sec_snapllm", alice_llm, username="sec_alice")
with patch(
"local_deep_research.config.llm_config."
"wrap_llm_without_think_tags",
side_effect=lambda llm, **kw: llm,
):
resolved = get_llm(
provider="sec_snapllm",
settings_snapshot=_snapshot("sec_alice"),
)
assert resolved is alice_llm
finally:
unregister_llm("sec_snapllm", username="sec_alice")
class TestEgressUserRegisteredLlmScoping:
"""The egress exemption for user-registered LLMs is per-user."""
def test_is_user_registered_llm_scoped(self):
from local_deep_research.llm import register_llm, unregister_llm
from local_deep_research.security.egress.policy import (
_is_user_registered_llm,
)
try:
register_llm("sec_egressllm", _MockLLM(), username="sec_alice")
assert _is_user_registered_llm(
"sec_egressllm", username="sec_alice"
)
# Not registered for Bob -> not exempt on his behalf.
assert not _is_user_registered_llm(
"sec_egressllm", username="sec_bob"
)
# And not visible in the shared namespace.
assert not _is_user_registered_llm("sec_egressllm")
finally:
unregister_llm("sec_egressllm", username="sec_alice")
class TestAdaptivePrivateRetrieverPrimaryNoCloudLeak:
"""Regression: a per-user PRIVATE retriever as the run's primary under
ADAPTIVE must resolve PRIVATE_ONLY and block a cloud LLM/embedder.
Per-user registry keying made ``get_metadata`` username-sensitive; if a
scope-resolution call site omits ``username`` the retriever is invisible
(shared namespace only), ADAPTIVE falls back to the permissive BOTH,
``require_local_*`` stays False, and a cloud model runs over the private
corpus. This asserts the seam threads username so that fail-open is shut.
"""
RET = "sec_private_kb"
USER = "sec_alice"
def _register_private_retriever(self):
from local_deep_research.web_search_engines.retriever_registry import (
retriever_registry,
)
retriever_registry.register(
self.RET, MagicMock(), is_local=True, username=self.USER
)
return retriever_registry
def test_adaptive_resolves_private_only_with_username(self):
from local_deep_research.security.egress.policy import (
EgressScope,
context_from_snapshot,
)
reg = self._register_private_retriever()
try:
snap = _private_primary_snapshot(self.USER, self.RET)
# With the owner's username, ADAPTIVE sees the private retriever
# primary and resolves PRIVATE_ONLY -> local inference forced.
ctx = context_from_snapshot(snap, self.RET, username=self.USER)
assert ctx.scope == EgressScope.PRIVATE_ONLY
assert ctx.require_local_llm is True
assert ctx.require_local_embeddings is True
# Witness the fail-open the fix closes: WITHOUT the username the
# retriever is invisible (shared namespace only), so ADAPTIVE
# falls back to the permissive BOTH and drops the local-only
# requirement. This is exactly why every scope-resolution call
# site must thread username.
leaked = context_from_snapshot(snap, self.RET, username=None)
assert leaked.scope != EgressScope.PRIVATE_ONLY
assert leaked.require_local_llm is False
finally:
reg.clear(username=self.USER)
def test_get_llm_refuses_cloud_under_private_retriever_primary(self):
from local_deep_research.security.egress.policy import (
PolicyDeniedError,
)
from local_deep_research.config.llm_config import get_llm
reg = self._register_private_retriever()
try:
snap = _private_primary_snapshot(self.USER, self.RET)
# username is derived from the snapshot's _username; a cloud LLM
# (openai) must be refused for this private-corpus run.
with pytest.raises(PolicyDeniedError):
get_llm(provider="openai", settings_snapshot=snap)
finally:
reg.clear(username=self.USER)
def test_get_embeddings_refuses_cloud_under_private_retriever_primary(
self,
):
from local_deep_research.security.egress.policy import (
PolicyDeniedError,
)
from local_deep_research.embeddings.embeddings_config import (
get_embeddings,
)
reg = self._register_private_retriever()
try:
snap = _private_primary_snapshot(self.USER, self.RET)
# The private retriever primary forces require_local_embeddings;
# a cloud embedder (openai) must be refused before instantiation.
with pytest.raises(PolicyDeniedError):
get_embeddings(provider="openai", settings_snapshot=snap)
finally:
reg.clear(username=self.USER)
def _cloud_private_primary_snapshot_without_username(primary):
"""A private-retriever-primary snapshot that names a CLOUD llm.provider
but omits ``_username`` — modelling the bare snapshots that call sites
like the metrics/domain-classify route and the news scheduler build
directly from ``SettingsManager`` (no ``_username`` injected). The call
site must supply the username itself (explicit arg or by scoping the
snapshot) or the private retriever is invisible and a cloud LLM fires.
"""
return {
"search.tool": _p(primary),
"policy.egress_scope": _p("adaptive"),
"search.engine.web": {},
"search.engine.library.enabled": _p(False, "checkbox"),
"llm.provider": _p("openai"),
"llm.model": _p("gpt-4o-mini"),
"llm.temperature": _p(0.7, "number"),
"rate_limiting.llm_enabled": _p(False, "checkbox"),
# NB: no "_username" key — the snapshot alone cannot scope the run.
}
class TestFailOpenCallSitesThreadUsername:
"""Regression for the three call sites that reached ``get_llm`` with a
``_username``-less snapshot and no explicit ``username=``.
Each fed user content (resource titles, news findings, or a whole
research run) to an LLM whose provider could resolve to cloud even
though the user's primary was a private retriever, because the private
retriever is only visible in the user's own registry namespace. The fix
threads the user at each seam.
"""
RET = "sec_failopen_kb"
USER = "sec_alice"
def _register_private_retriever(self):
from local_deep_research.web_search_engines.retriever_registry import (
retriever_registry,
)
retriever_registry.register(
self.RET, MagicMock(), is_local=True, username=self.USER
)
return retriever_registry
def test_domain_classifier_threads_username(self):
"""``DomainClassifier._get_llm`` must pass ``username=self.username``
so the classify route's bare snapshot still forces local-only."""
from local_deep_research.security.egress.policy import (
PolicyDeniedError,
)
from local_deep_research.domain_classifier.classifier import (
DomainClassifier,
)
reg = self._register_private_retriever()
try:
snap = _cloud_private_primary_snapshot_without_username(self.RET)
classifier = DomainClassifier(
username=self.USER, settings_snapshot=snap
)
with pytest.raises(PolicyDeniedError):
classifier._get_llm()
finally:
reg.clear(username=self.USER)
def test_scheduler_style_snapshot_scoping_blocks_cloud(self):
"""The news scheduler builds a bare snapshot and now scopes it with
``ensure_snapshot_username`` before the headline/topic LLM calls.
Prove that scoping is what closes the fail-open: the bare snapshot
resolves a cloud LLM, the scoped one is refused."""
from local_deep_research.security.egress.policy import (
PolicyDeniedError,
)
from local_deep_research.config.llm_config import get_llm
from local_deep_research.search_system import (
ensure_snapshot_username,
)
reg = self._register_private_retriever()
try:
bare = _cloud_private_primary_snapshot_without_username(self.RET)
# Witness the fail-open: without a username the private retriever
# is invisible, ADAPTIVE stays permissive, and the egress PEP does
# NOT block the cloud provider. (Instantiation still fails for an
# unrelated reason — no API key in the test snapshot — but that is
# not the policy stopping it.)
with pytest.raises(Exception) as bare_exc:
get_llm(settings_snapshot=bare)
assert not isinstance(bare_exc.value, PolicyDeniedError)
# The scheduler fix scopes the snapshot to its owner; the egress
# PEP now refuses the cloud LLM for the private-corpus run.
scoped = ensure_snapshot_username(bare, self.USER)
with pytest.raises(PolicyDeniedError):
get_llm(settings_snapshot=scoped)
finally:
reg.clear(username=self.USER)