~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
"""
Thorough tests for the Settings API endpoints.
Covers GET/PUT operations on /settings/api/* with response
format validation.
"""
import uuid
import pytest
from fastapi.testclient import TestClient
@pytest.fixture(scope="module")
def auth_client():
"""Authenticated test client."""
from local_deep_research.web.fastapi_app import app
c = TestClient(app, raise_server_exceptions=False)
user = f"test_settings_{uuid.uuid4().hex[:8]}"
pw = "TestPassword123!" # noqa: S105
# Fetch CSRF tokens before register/login — Wave 9 made these
# endpoints fail-closed on missing tokens.
def _csrf():
c.get("/auth/login")
r = c.get("/auth/csrf-token")
return r.json().get("csrf_token", "") if r.status_code == 200 else ""
c.post(
"/auth/register",
data={
"username": user,
"password": pw,
"confirm_password": pw,
"acknowledge": "true",
"csrf_token": _csrf(),
},
follow_redirects=False,
)
resp = c.post(
"/auth/login",
data={"username": user, "password": pw, "csrf_token": _csrf()},
follow_redirects=False,
)
if resp.status_code != 302:
pytest.fail(
f"Login bootstrap failed: expected 302, got {resp.status_code}: "
f"{resp.text[:500]}"
)
# Attach CSRF token so PUT/DELETE/POST tests pass CSRFMiddleware.
csrf_resp = c.get("/auth/csrf-token")
if csrf_resp.status_code == 200:
token = csrf_resp.json().get("csrf_token")
if token:
c.headers.update({"X-CSRFToken": token})
yield c
c.post("/auth/logout", follow_redirects=False)
@pytest.mark.timeout(120)
class TestSettingsAPI:
"""Tests for /settings/api endpoints."""
def test_get_all_settings(self, auth_client):
"""GET /settings/api returns JSON with 'settings' key."""
resp = auth_client.get("/settings/api")
assert resp.status_code == 200
data = resp.json()
assert "settings" in data
assert isinstance(data["settings"], dict)
assert len(data["settings"]) > 0
def test_get_settings_filtered_by_category(self, auth_client):
"""GET /settings/api?category=llm filters correctly."""
resp = auth_client.get("/settings/api?category=llm")
assert resp.status_code == 200
data = resp.json()
assert "settings" in data
# All returned setting keys should start with "llm."
for key in data["settings"]:
assert key.startswith("llm.")
def test_get_categories(self, auth_client):
"""GET /settings/api/categories returns a list of categories."""
resp = auth_client.get("/settings/api/categories")
assert resp.status_code == 200
data = resp.json()
assert "categories" in data
assert isinstance(data["categories"], list)
assert len(data["categories"]) > 0
def test_get_types(self, auth_client):
"""GET /settings/api/types returns a list of types."""
resp = auth_client.get("/settings/api/types")
assert resp.status_code == 200
data = resp.json()
assert "types" in data
assert isinstance(data["types"], list)
assert len(data["types"]) > 0
def test_get_ui_elements(self, auth_client):
"""GET /settings/api/ui_elements returns a list of UI elements."""
resp = auth_client.get("/settings/api/ui_elements")
assert resp.status_code == 200
data = resp.json()
assert "ui_elements" in data
assert isinstance(data["ui_elements"], list)
def test_get_single_setting(self, auth_client):
"""GET /settings/api/llm.provider returns a setting with key and value."""
resp = auth_client.get("/settings/api/llm.provider")
assert resp.status_code == 200
data = resp.json()
assert "key" in data
assert "value" in data
assert data["key"] == "llm.provider"
def test_put_setting(self, auth_client):
"""PUT /settings/api/llm.model updates a setting."""
# First read the current value so we can restore it
get_resp = auth_client.get("/settings/api/llm.model")
assert get_resp.status_code == 200
original_value = get_resp.json().get("value")
# Update the setting
put_resp = auth_client.put(
"/settings/api/llm.model",
json={"value": "test-model-name"},
)
assert put_resp.status_code == 200
# Verify the update took effect
verify_resp = auth_client.get("/settings/api/llm.model")
assert verify_resp.status_code == 200
assert verify_resp.json()["value"] == "test-model-name"
# Restore original value
if original_value is not None:
auth_client.put(
"/settings/api/llm.model",
json={"value": original_value},
)
def test_false_api_setting_blocks_authenticated_api(self, auth_client):
"""A boolean PUT must reach the API gate as False, not a string."""
setting_url = "/settings/api/app.enable_api"
previous = auth_client.get(setting_url)
original_value = (
previous.json().get("value")
if previous.status_code == 200
else None
)
assert auth_client.get("/api/v1/").status_code == 200
try:
written = auth_client.put(setting_url, json={"value": False})
assert written.status_code in (200, 201), written.text
stored = auth_client.get(setting_url)
assert stored.status_code == 200
assert stored.json()["value"] is False
assert stored.json()["ui_element"] == "checkbox"
disabled = auth_client.get("/api/v1/")
assert disabled.status_code == 403, disabled.text
finally:
if previous.status_code == 200:
auth_client.put(setting_url, json={"value": original_value})
else:
auth_client.delete(setting_url)
assert auth_client.get("/api/v1/").status_code == 200
def test_legacy_text_api_toggle_is_retyped(self, auth_client):
"""Updating a legacy text row must repair its boolean metadata."""
setting_url = "/settings/api/app.enable_api"
assert auth_client.get("/api/v1/").status_code == 200
try:
created = auth_client.put(
setting_url, json={"value": "False", "ui_element": "text"}
)
assert created.status_code == 201, created.text
assert auth_client.get(setting_url).json()["ui_element"] == "text"
assert auth_client.get("/api/v1/").status_code == 403
updated = auth_client.put(setting_url, json={"value": False})
assert updated.status_code == 200, updated.text
stored = auth_client.get(setting_url).json()
assert stored["value"] is False
assert stored["ui_element"] == "checkbox"
assert auth_client.get("/api/v1/").status_code == 403
finally:
auth_client.delete(setting_url)
assert auth_client.get("/api/v1/").status_code == 200
def test_sensitive_setting_get_is_redacted_and_roundtrip_safe(
self, auth_client
):
"""Secret values are REDACTED on GET, and re-saving the sentinel is a
no-op that preserves the stored credential (main's PR #3947 contract).
Main redacts api_key/password/OAuth values on both the per-key and the
bulk GET as defense in depth (this JSON is cached by clients, logged by
proxies, pasted into bug reports). It is safe to round-trip because the
save path's write-back guard skips the '[REDACTED]' sentinel, so the
dashboard re-saving a redacted dump never overwrites stored secrets;
the frontend (settings.js) seeds password baselines from the sentinel.
"""
key = "llm.openai.api_key"
secret = "sk-test-roundtrip-12345" # noqa: S105
redacted = "[REDACTED]"
original_value = (
auth_client.get(f"/settings/api/{key}").json().get("value")
)
try:
put_resp = auth_client.put(
f"/settings/api/{key}", json={"value": secret}
)
assert put_resp.status_code == 200
# Per-key + bulk GET redact the secret — never the plaintext key.
single = auth_client.get(f"/settings/api/{key}").json()
assert single["value"] == redacted
bulk = auth_client.get("/settings/api").json()
assert bulk["status"] == "success"
assert bulk["settings"][key]["value"] == redacted
# Dashboard round-trip: saving the redacted sentinel back is a
# no-op (does NOT corrupt the stored secret) and still 200s.
save_resp = auth_client.post(
"/settings/save_all_settings",
json={key: bulk["settings"][key]["value"]},
)
assert save_resp.status_code == 200
# Still redacted on read afterwards — the sentinel save did not
# clobber the setting into a plaintext leak.
after = auth_client.get(f"/settings/api/{key}").json()
assert after["value"] == redacted
finally:
if original_value not in (None, redacted):
auth_client.put(
f"/settings/api/{key}", json={"value": original_value}
)
def test_get_warnings(self, auth_client):
"""GET /settings/api/warnings returns a list."""
resp = auth_client.get("/settings/api/warnings")
assert resp.status_code == 200
data = resp.json()
assert "warnings" in data
assert isinstance(data["warnings"], list)
def test_get_available_search_engines(self, auth_client):
"""GET /settings/api/available-search-engines returns data."""
resp = auth_client.get("/settings/api/available-search-engines")
assert resp.status_code == 200
data = resp.json()
assert isinstance(data, (dict, list))
def test_get_bulk_settings(self, auth_client):
"""GET /settings/api/bulk returns bulk settings."""
resp = auth_client.get("/settings/api/bulk")
assert resp.status_code == 200
data = resp.json()
assert isinstance(data, dict)
assert "settings" in data
def test_bulk_settings_redacts_secrets(self, auth_client):
"""GET /settings/api/bulk redacts secret values — it is an
exfiltration channel (?keys[]=llm.openai.api_key) that main redacts."""
key = "llm.openai.api_key"
secret = "sk-bulk-leak-test-123" # noqa: S105
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
assert (
auth_client.put(
f"/settings/api/{key}", json={"value": secret}
).status_code
== 200
)
data = auth_client.get(f"/settings/api/bulk?keys[]={key}").json()
assert data["settings"][key]["value"] == "[REDACTED]"
assert data["settings"][key]["exists"] is True
finally:
if original not in (None, "[REDACTED]"):
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_put_empty_secret_is_noop(self, auth_client):
"""PUT '' or '[REDACTED]' to a password-typed setting is a no-op
(never clears the stored secret) — main's write-back guard, now on the
single-key PUT path."""
key = "llm.openai.api_key"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
assert (
auth_client.put(
f"/settings/api/{key}", json={"value": "sk-keep-me"}
).status_code
== 200
)
for sentinel in ("[REDACTED]", ""):
resp = auth_client.put(
f"/settings/api/{key}", json={"value": sentinel}
)
assert resp.status_code == 200
assert "unchanged" in resp.json().get("message", "").lower()
finally:
if original not in (None, "[REDACTED]"):
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_put_egress_public_host_rejected(self, auth_client):
"""PUT a PUBLIC host into llm.allowed_local_hostnames is rejected
(400) — main's cross-field egress validation, now on the single-key
PUT path (was a per-key SSRF/egress bypass)."""
key = "llm.allowed_local_hostnames"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
resp = auth_client.put(
f"/settings/api/{key}", json={"value": ["8.8.8.8"]}
)
assert resp.status_code == 400
assert "8.8.8.8" in resp.json().get("error", "")
# Allow counterpart: a private (RFC1918) host is accepted.
assert (
auth_client.put(
f"/settings/api/{key}", json={"value": ["10.0.0.1"]}
).status_code
== 200
)
finally:
if original is not None and original != "[REDACTED]":
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_put_private_searxng_instance_url_rejected(self, auth_client):
"""PUT a PRIVATE SearXNG instance_url is rejected (400) naming the
operator gate.
Main covers this at the route in ``test_egress_settings_save_validators``
via a mocked Flask harness; that harness died with the Flask routes, so
pin it against the real FastAPI route instead. The validator itself is
unit-tested elsewhere -- this is the *wiring*: without it, a validated
helper sits behind a route that never calls it, which is precisely the
defect class this guard exists to prevent.
"""
key = "search.engine.web.searxng.default_params.instance_url"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
resp = auth_client.put(
f"/settings/api/{key}", json={"value": "http://10.0.0.1:8080"}
)
assert resp.status_code == 400
error = resp.json().get("error", "")
assert "LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLS" in error, (
"the 400 must name the operator gate so the remedy is "
f"discoverable; got: {error!r}"
)
finally:
if original is not None and original != "[REDACTED]":
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_put_public_searxng_instance_url_accepted(self, auth_client):
"""Allow counterpart: a PUBLIC instance_url saves (200).
Without this, the guard above could be satisfied by a route that
rejects every URL -- the feature would be "secure" and useless.
"""
key = "search.engine.web.searxng.default_params.instance_url"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
resp = auth_client.put(
f"/settings/api/{key}", json={"value": "http://8.8.8.8"}
)
assert resp.status_code == 200, resp.text[:300]
assert "error" not in resp.json()
finally:
if original is not None and original != "[REDACTED]":
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_put_private_searxng_url_accepted_with_operator_gate(
self, auth_client, monkeypatch
):
"""With the env-only operator gate set, the private URL saves (200).
The gate is read from the environment at validation time, so setting
it here exercises the same branch an operator hits in production.
"""
monkeypatch.setenv("LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLS", "true")
key = "search.engine.web.searxng.default_params.instance_url"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
resp = auth_client.put(
f"/settings/api/{key}", json={"value": "http://10.0.0.1:8080"}
)
assert resp.status_code == 200, resp.text[:300]
finally:
if original is not None and original != "[REDACTED]":
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_put_strict_scope_with_concrete_engine_accepted(self, auth_client):
"""Allow counterpart for the scope validator: STRICT with a concrete
stored engine saves (200) rather than tripping cross-field validation.
"""
key = "policy.egress_scope"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
try:
auth_client.put(
"/settings/api/search.tool", json={"value": "arxiv"}
)
resp = auth_client.put(
f"/settings/api/{key}", json={"value": "strict"}
)
assert resp.status_code == 200, resp.text[:300]
assert "error" not in resp.json()
finally:
if original is not None and original != "[REDACTED]":
auth_client.put(
f"/settings/api/{key}", json={"value": original}
)
def test_get_search_favorites(self, auth_client):
"""GET /settings/api/search-favorites returns data."""
resp = auth_client.get("/settings/api/search-favorites")
assert resp.status_code == 200
data = resp.json()
assert isinstance(data, dict)
assert "favorites" in data
assert isinstance(data["favorites"], list)
def test_get_data_location(self, auth_client):
"""GET /settings/api/data-location returns location info."""
resp = auth_client.get("/settings/api/data-location")
assert resp.status_code == 200
data = resp.json()
assert isinstance(data, dict)
assert "data_directory" in data
def test_put_rejects_trailing_dot_under_allowed_prefix_with_400(
self, auth_client
):
"""A trailing-dot key under an ALLOWED prefix (the #4840 shape) is
rejected with 400 — the malformed-key guard runs ahead of the
namespace allow-list, so ``local_search_chunk_size.`` never
persists (#4935)."""
for key in ("local_search_chunk_size.", "llm."):
resp = auth_client.put(f"/settings/api/{key}", json={"value": 1000})
assert resp.status_code == 400, key
# The error must name the real problem (malformed key), not
# misdirect to namespaces — the prefix here IS allowed.
assert "malformed" in resp.json()["error"].lower(), key
class TestIsAllowedNewSettingKey:
"""Unit coverage for the write-side key guard (#4935)."""
def test_rejects_trailing_and_leading_dot(self):
"""Trailing-/leading-dot keys are malformed even under an allowed
prefix — these are the rows that corrupt prefix lookups (#4840)."""
from local_deep_research.web.routers.settings import (
_is_allowed_new_setting_key,
)
# Trailing dot: passes the prefix allow-list but is malformed.
assert _is_allowed_new_setting_key("llm.") is False
assert _is_allowed_new_setting_key("search.max_results.") is False
assert _is_allowed_new_setting_key("local_search_chunk_size.") is False
# Leading dot and stray whitespace.
assert _is_allowed_new_setting_key(".llm.model") is False
assert _is_allowed_new_setting_key(" llm.model") is False
assert _is_allowed_new_setting_key("llm.model ") is False
class TestNoJsSaveSettingsFeedback:
"""The no-JS /settings/save_settings fallback must give the user visible
feedback (a flash), not a silent redirect — Flask flashed success/error
and the migration had dropped it."""
def test_save_settings_flashes_success(self, auth_client):
# A valid setting write should redirect and then show a success flash
# on the settings page.
csrf = auth_client.get("/auth/csrf-token").json()["csrf_token"]
resp = auth_client.post(
"/settings/save_settings",
data={"llm.temperature": "0.5", "csrf_token": csrf},
follow_redirects=False,
)
assert resp.status_code in (302, 303), resp.text
assert resp.headers["location"].startswith("/settings/")
page = auth_client.get("/settings/")
assert page.status_code == 200
assert "Settings saved" in page.text, (
"no-JS save must flash a visible confirmation on /settings/"
)
def test_manual_corruption_repair_endpoint_is_removed(auth_client):
"""Migration 0031 replaces the authenticated manual repair operation."""
response = auth_client.post("/settings/fix_corrupted_settings")
assert response.status_code == 404
def test_library_storage_path_is_operator_only_over_http(auth_client):
key = "research_library.storage_path"
before = auth_client.get(f"/settings/api/{key}")
assert before.status_code == 200
assert before.json()["editable"] is False
# The bulk read goes through get_setting(), which folds child rows.
bulk_url = f"/settings/api/bulk?keys[]={key}"
bulk_before = auth_client.get(bulk_url).json()["settings"][key]["value"]
assert isinstance(bulk_before, str)
# SQLite's LIKE finds child rows regardless of ASCII case, so case
# variants of the key and of its children are refused as well.
case_variants = (
"Research_Library.storage_path.x",
"RESEARCH_LIBRARY.STORAGE_PATH.x",
"Research_Library.Storage_Path",
)
for attempted_key in (key, f"{key}.child", *case_variants):
response = auth_client.put(
f"/settings/api/{attempted_key}", json={"value": "/tmp/redirected"}
)
assert response.status_code == 403, attempted_key
for attempted_key in (key, *case_variants):
response = auth_client.delete(f"/settings/api/{attempted_key}")
assert response.status_code == 403, attempted_key
for attempted_key in case_variants:
response = auth_client.get(f"/settings/api/{attempted_key}")
assert response.status_code == 404, attempted_key
after = auth_client.get(f"/settings/api/{key}")
assert after.json()["value"] == before.json()["value"]
bulk_after = auth_client.get(bulk_url).json()["settings"][key]["value"]
assert bulk_after == bulk_before