~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
"""Hostile-input matrix for the highest-value FastAPI endpoints.
The Flask -> FastAPI port moved every request body from ``request.json``
(Werkzeug) to ``await request.json()`` (Starlette). Both hand the handler a
raw ``json.loads`` result, so the *validation* the routes do is entirely
hand-rolled ``data.get(...)`` code — there is no Pydantic request model on
any of the routes covered here. That makes type confusion, not schema
rejection, the live failure mode, and it is what this file drives at:
* ``POST /api/start_research`` research submission
* ``PUT /settings/api/{key}`` settings write
* ``POST /api/chat/sessions`` chat
* ``POST /api/followup/prepare`` follow-up research
* ``POST /library/api/collections`` collection create
* ``POST /library/api/collections/{id}/upload`` file upload
* ``POST /api/v1/research/{id}/export/{fmt}`` export (filename header)
* ``POST /news/api/subscribe`` news subscription
Categories driven: type confusion (int/float/bool/null/list/dict where a
str is expected), enormous values (10 MB strings, 20 MB bodies, 100 000-level
nested JSON), null bytes / CRLF / path traversal / template syntax in fields
that reach filenames, DB keys and response headers, and numeric edges
(0, negative, MAXINT, float-for-int, NaN).
ANTI-VACUITY CONTRACT
---------------------
Every test in this file pairs each rejection assertion with a *benign
control driven through the identical code path*, and asserts on the
CONSEQUENCE (what got persisted, what filename came back, what the
Content-Disposition header actually contains, whether a row was created)
rather than on a bare status code. Where a rejection is asserted, the
control proves the harness can observe acceptance; where acceptance is
asserted, the hostile case proves it can observe rejection. No assertion
in this file is guarded by ``if status == 200``.
Any remaining ``xfail(strict=True)`` tests are real defects reproduced
against the running app. Each reason records whether it also reproduces on
``origin/main`` or is a port regression. They stay strict so a fix turns the
test red and forces the pin to become a permanent regression test.
Request budget: ~60 sequential TestClient requests per user exhausts the
DB pool, so every test gets a FRESH registered and auto-authenticated user via
the ``client`` fixture and keeps its own request count in the low teens.
"""
import io
import itertools
import json
import os
import re
import threading
import uuid
from contextlib import suppress
from datetime import timedelta
import pytest
from fastapi.testclient import TestClient
# The app's docs_url toggle reads PYTEST_CURRENT_TEST at app-import time;
# pytest only sets that per-test, not at collection.
os.environ.setdefault("TESTING", "1")
# Imported at module scope so this file fails loudly if a symbol is renamed
# instead of silently asserting against a 404.
from local_deep_research.settings.manager import is_valid_setting_key
from local_deep_research.web.routes.research_validation import (
ALLOWED_TIME_PERIODS,
MAX_RESULTS_MAX,
MAX_RESULTS_MIN,
)
PASSWORD = "HostileMatrix!Pass123" # noqa: S105 - test-only credential
# MONOTONIC, not random: rate limiting is keyed per client IP for
# /auth/register, and random octets collide inside a file
# this size, producing 429s that have nothing to do with the guard under
# test.
_IP_COUNTER = itertools.count(1)
def _next_forwarded_for() -> str:
n = next(_IP_COUNTER)
return f"10.221.{(n // 250) % 250}.{(n % 250) + 1}"
def _fresh_client(app):
return TestClient(app, raise_server_exceptions=False)
def _csrf(client) -> str:
"""CSRF is enforced by ASGI middleware — fetch a real token."""
client.get("/auth/login")
return client.get("/auth/csrf-token").json()["csrf_token"]
def _cleanup_client(client, username):
try:
with suppress(Exception):
client.post("/auth/logout", follow_redirects=False)
with suppress(Exception):
from local_deep_research.web.auth.session_manager import (
session_manager,
)
session_manager.destroy_all_user_sessions(username)
with suppress(Exception):
from local_deep_research.database.session_passwords import (
session_password_store,
)
session_password_store.clear_all_for_user(username)
with suppress(Exception):
from local_deep_research.database.thread_local_session import (
clear_user_credentials,
)
clear_user_credentials(username)
finally:
client.close()
def _register_and_authenticate(client, username: str):
resp = client.post(
"/auth/register",
data={
"username": username,
"password": PASSWORD,
"confirm_password": PASSWORD,
"acknowledge": "true",
"csrf_token": _csrf(client),
},
follow_redirects=False,
)
assert resp.status_code == 302, (
f"registration of {username!r} failed: "
f"{resp.status_code} / {resp.text[:400]}"
)
client.headers.update(
{"X-CSRFToken": client.get("/auth/csrf-token").json()["csrf_token"]}
)
who = client.get("/auth/check")
assert (
who.status_code == 200
and who.json().get("authenticated") is True
and who.json().get("username") == username
), f"session did not bind to {username!r}: {who.text[:300]}"
client.ldr_username = username
def _user(prefix: str) -> str:
return f"{prefix}_{uuid.uuid4().hex[:10]}"
@pytest.fixture
def client(app, request):
"""A freshly registered and auto-authenticated user, one per test."""
username = _user(request.node.name[:20])
test_client = _fresh_client(app)
request.addfinalizer(lambda: _cleanup_client(test_client, username))
test_client.headers.update({"X-Forwarded-For": _next_forwarded_for()})
_register_and_authenticate(test_client, username)
return test_client
def _nested_json(depth: int, inner: str = '"x"') -> bytes:
return ('{"query":' + "[" * depth + inner + "]" * depth + "}").encode()
def _depth_the_json_scanner_refuses() -> int:
"""A nesting depth this interpreter's ``json`` scanner will not parse.
CPython's C scanner recurses on the C stack, so the depth at which it
raises ``RecursionError`` is a function of the running thread's stack
size, not a language constant: roughly 58 000 under the usual 8 MB
stack, several times that under a larger one. A hardcoded depth is
therefore not portable, and the failure is silent in the dangerous
direction — a body that was meant to be unparseable instead parses into
a perfectly valid JSON *object*, sails past the boundary check this test
is about, and the assertion fails somewhere much deeper in the handler.
(That is exactly what the previous hardcoded 100 000 did on CI, whose
container has more stack headroom than an 8 MB desktop.)
Probed on a plain thread because that is where the app parses the body:
Starlette hands the request to a portal thread whose stack is the OS
default for threads, which need not match the stack pytest itself runs
on. The returned depth is quadrupled so the margin survives any
remaining difference between the two; even on an implausibly roomy
64 MB thread stack the resulting body is ~5 MB, well inside the app's
16 MB JSON-body cap, so this cannot turn into a 413.
"""
refused: list[int] = []
def probe() -> None:
depth = 10_000
for _ in range(8):
try:
json.loads(_nested_json(depth))
except RecursionError:
refused.append(depth)
return
depth *= 2
thread = threading.Thread(target=probe)
thread.start()
thread.join()
assert refused, (
"no nesting depth up to 1 280 000 made this interpreter's json "
"scanner raise RecursionError, so the probe below would no longer "
"exercise the boundary guard it exists for"
)
return refused[0] * 4
def _seed_research(username: str, title: str, report="# Body\n\ntext") -> str:
"""Insert a completed ResearchHistory row into the caller's own DB.
Test *setup* only — this is the state a finished research leaves
behind; the code under test is the route that reads it back. No
production logic is re-implemented here.
"""
from local_deep_research.database.models.research import ResearchHistory
from local_deep_research.database.session_context import (
get_user_db_session,
)
rid = str(uuid.uuid4())
with get_user_db_session(username) as session:
session.add(
ResearchHistory(
id=rid,
query="seed query",
mode="quick",
status="completed",
created_at="2026-01-01T00:00:00",
title=title,
report_content=report,
)
)
session.commit()
return rid
START = "/api/start_research"
# ===========================================================================
# A. POST /api/start_research — the research submission endpoint
# ===========================================================================
#
# The handler's body gate is:
# non-JSON Content-Type -> 400 "Request body must be valid JSON"
# data = await request.json() -> 400 "Request body must be JSON"
# if not isinstance(data, dict) -> 400 "Request body must be a JSON object"
# and only then does _start_research_sync run.
#
# CONTROL used throughout this section: the test user has no configured LLM
# model, so any payload that survives the whole handler bottoms out at
# 400 "Model is required. Please configure a model in the settings." That
# string is emitted ~200 lines INTO _start_research_sync (research.py, after
# _extract_research_params, the egress precheck and the query-length cap),
# so seeing it proves the payload traversed the full handler rather than
# being turned away at the boundary. It is a strictly different observable
# outcome from every rejection asserted below.
_MODEL_REQUIRED = "Model is required"
_QUERY_REQUIRED = "Query is required"
def test_start_research_rejects_non_object_and_unparseable_bodies(client):
"""A non-object JSON body must be refused at the boundary, not fed to
``data.get(...)``.
Also covers the ENORMOUS-VALUE axis for nesting depth: a nested list
deep enough to make CPython's ``json`` scanner raise ``RecursionError``
inside ``await request.json()``. The route's ``except Exception`` around
that single await converts it to a clean 400 and the server survives —
without it a RecursionError on the event-loop thread would escape to
the 500 handler. The depth is discovered at run time rather than
hardcoded; see ``_depth_the_json_scanner_refuses``.
"""
# CONTROL: a well-formed JSON *object* traverses the whole handler.
control = client.post(START, json={})
assert control.status_code == 400, control.text[:300]
assert _QUERY_REQUIRED in control.json()["message"], control.text[:300]
# Valid JSON, wrong top-level type. Sent as raw bytes rather than via
# httpx's json= so that `null` is a real JSON body and not an omitted
# one (for json=None httpx sends no body and no Content-Type, which the
# media-type check rejects first: "Request body must be valid JSON").
for raw in (b"[1, 2]", b'"a string"', b"123", b"null", b"true"):
resp = client.post(
START, content=raw, headers={"Content-Type": "application/json"}
)
assert resp.status_code == 400, f"{raw!r} -> {resp.status_code}"
assert "must be a JSON object" in resp.json()["message"], (
f"{raw!r} -> {resp.text[:200]}"
)
# Unparseable body.
resp = client.post(
START,
content=b"{not json",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["message"] == "Request body must be JSON"
# Nesting deep enough that json.loads raises RecursionError on THIS
# interpreter (see the helper: the threshold is stack-size dependent, so
# it cannot be hardcoded without going vacuous on a machine with a
# roomier stack).
resp = client.post(
START,
content=_nested_json(_depth_the_json_scanner_refuses()),
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["message"] == "Request body must be JSON"
# ... and the app is still serving afterwards (no worker death).
assert client.get("/auth/check").status_code == 200
def test_start_research_moderately_nested_json_is_accepted_not_rejected(
client,
):
"""Control for the depth test above: 1 000 levels still parses.
Pins the boundary as "RecursionError", not "any nesting is refused" —
a guard that rejected all nested JSON would pass the previous test
while breaking every legitimate structured field.
"""
nested = "[" * 1_000 + '"x"' + "]" * 1_000
body = ('{"query":"hi","metadata":{"nested":' + nested + "}}").encode()
resp = client.post(
START, content=body, headers={"Content-Type": "application/json"}
)
assert resp.status_code == 400, resp.text[:200]
# Reached the END of the handler, not the body gate.
assert _MODEL_REQUIRED in resp.json()["message"], resp.text[:250]
def test_start_research_search_override_numeric_edges_are_rejected(client):
"""``validate_search_overrides`` is the only typed gate on this route.
Numeric-edge axis: 0, above-max, float-for-int, bool-for-int (``bool``
is an ``int`` subclass, so ``isinstance`` would have let ``true`` coerce
to 1), str-for-int, and JSON ``NaN`` (which Python's ``json`` accepts
where the spec does not — it arrives as a ``float`` and must be refused
by the exact-type check).
"""
# CONTROL: legitimate values traverse the whole handler.
control = client.post(
START,
json={
"query": "hi",
"max_results": MAX_RESULTS_MAX,
"time_period": "d",
},
)
assert control.status_code == 400, control.text[:300]
assert _MODEL_REQUIRED in control.json()["message"], control.text[:300]
assert "d" in ALLOWED_TIME_PERIODS # the control really is allow-listed
bad_max_results = [
True, # bool -> would be 1 under isinstance()
"5", # str
MAX_RESULTS_MIN - 1, # 0
MAX_RESULTS_MAX + 1, # 51
5.0, # float
]
for value in bad_max_results:
resp = client.post(START, json={"query": "hi", "max_results": value})
assert resp.status_code == 400, f"{value!r} -> {resp.status_code}"
assert (
resp.json()["message"]
== "max_results must be an integer between 1 and 50"
), f"{value!r} -> {resp.text[:200]}"
# JSON NaN — Python's json.loads accepts the bare literal.
resp = client.post(
START,
content=b'{"query": "hi", "max_results": NaN}',
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:200]
assert (
resp.json()["message"]
== "max_results must be an integer between 1 and 50"
), resp.text[:200]
for value in (5, ["d"], "not-a-period"):
resp = client.post(START, json={"query": "hi", "time_period": value})
assert resp.status_code == 400, f"{value!r} -> {resp.status_code}"
assert (
resp.json()["message"]
== "time_period must be one of: d, w, m, y, all"
), f"{value!r} -> {resp.text[:200]}"
def test_start_research_query_length_cap(client):
"""Enormous-value axis: a 10 MB query is refused by the explicit cap.
Under the 16 MB per-route JSON body cap, so this reaches the handler's
own ``_MAX_QUERY_LENGTH`` check rather than being turned away by
BodySizeLimitMiddleware — the cap under test is the route's, not the
middleware's.
"""
# CONTROL: 9 999 characters (one under the cap) traverses the handler.
control = client.post(START, json={"query": "A" * 9_999})
assert control.status_code == 400, control.text[:200]
assert _MODEL_REQUIRED in control.json()["message"], control.text[:250]
resp = client.post(START, json={"query": "A" * (10 * 1024 * 1024)})
assert resp.status_code == 400, resp.text[:200]
assert (
resp.json()["message"]
== "Query exceeds maximum length of 10000 characters"
), resp.text[:200]
def test_start_research_hostile_query_strings_are_inert(client):
"""Null bytes, CRLF and template syntax in ``query`` reach the logger
and the DB, and must not change the handler's control flow.
All four traverse to the same end-of-handler outcome as a plain
English query — i.e. none of them is silently dropped, truncated at
the null byte into a different branch, or evaluated.
"""
benign = client.post(START, json={"query": "capital of france"})
assert benign.status_code == 400, benign.text[:200]
assert _MODEL_REQUIRED in benign.json()["message"]
for payload in (
"abc\x00def",
"abc\r\nInjected-Header: 1",
"{{7*7}} ${7*7} <%= 7*7 %>",
"../../../../etc/passwd",
):
resp = client.post(START, json={"query": payload})
assert resp.status_code == 400, f"{payload!r} -> {resp.status_code}"
assert _MODEL_REQUIRED in resp.json()["message"], (
f"{payload!r} -> {resp.text[:200]}"
)
# No template evaluation anywhere on the path back to the client.
assert "49" not in resp.text
def test_start_research_non_string_query_is_rejected_not_500(client):
# CONTROL: the same value as a STRING traverses the whole handler, so
# the only difference between the two calls is the JSON type.
control = client.post(START, json={"query": "12345"})
assert control.status_code == 400, control.text[:200]
assert _MODEL_REQUIRED in control.json()["message"], control.text[:250]
for wrong_type in (12345, 1.5, True, [12345], {"a": 1}):
resp = client.post(START, json={"query": wrong_type})
# CONSEQUENCE CHECK: whatever the status, nothing is persisted --
# validation happens before any ResearchHistory row is written.
history = client.get("/api/history")
assert history.status_code == 200, history.text[:200]
assert history.json()["items"] == [], history.text[:300]
assert resp.status_code == 400, (
f"{wrong_type!r} -> {resp.status_code} {resp.text[:200]}"
)
assert resp.json() == {
"status": "error",
"message": "query must be a string",
}
def test_start_research_non_dict_metadata_is_rejected_not_500(client):
# CONTROL: a dict metadata (and an absent one) traverse the handler.
for ok in ({"metadata": {"is_news_search": False}}, {}):
control = client.post(START, json={"query": "hi", **ok})
assert control.status_code == 400, control.text[:200]
assert _MODEL_REQUIRED in control.json()["message"], control.text[:250]
for bad in ("not a dict", [1, 2], 5, True, None):
resp = client.post(START, json={"query": "hi", "metadata": bad})
assert resp.status_code == 400, (
f"metadata={bad!r} -> {resp.status_code} {resp.text[:200]}"
)
assert resp.json() == {
"status": "error",
"message": "metadata must be an object",
}
# ===========================================================================
# B. PUT /settings/api/{key} — settings write
# ===========================================================================
SETTING_TEXT = "llm.model" # ui_element="text"
SETTING_NUM = "search.iterations" # ui_element="number", min 1
def _put_setting(client, key, value):
return client.put(f"/settings/api/{key}", json={"value": value})
def _get_setting(client, key):
return client.get(f"/settings/api/{key}")
def test_settings_json_body_cap_cannot_be_bypassed_by_content_type(client):
"""Enormous-value axis + the Content-Type spoof the middleware exists
to close.
``BodySizeLimitMiddleware`` grants the ~600 GB upload cap on PATH, never
on the client's declared Content-Type, precisely because
``Request.json()`` never inspects Content-Type — a body labelled
``multipart/form-data`` is still parsed as JSON by any route that asks
for JSON. Both the honest and the mislabelled 20 MB body must hit the
16 MB per-route JSON cap.
"""
big = b'{"value":"' + b"A" * (20 * 1024 * 1024) + b'"}'
small = b'{"value":"' + b"A" * 1024 + b'"}'
# CONTROL: a small body on the identical route/method is accepted.
resp = client.put(
f"/settings/api/{SETTING_TEXT}",
content=small,
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 200, resp.text[:200]
assert "updated successfully" in resp.json()["message"], resp.text[:200]
for content_type in (
"application/json",
"multipart/form-data; boundary=x", # the spoof
):
resp = client.put(
f"/settings/api/{SETTING_TEXT}",
content=big,
headers={"Content-Type": content_type},
)
assert resp.status_code == 413, (
f"{content_type} -> {resp.status_code} {resp.text[:200]}"
)
assert resp.json()["error"] == "Request too large", resp.text[:200]
# CONSEQUENCE: the rejected 20 MB payload never reached the DB.
assert _get_setting(client, SETTING_TEXT).json()["value"] == "A" * 1024
def test_settings_new_key_namespace_allowlist_holds_under_unicode(client):
"""Path-parameter axis: ``{key}`` becomes a row in the settings DB.
``_is_allowed_new_setting_key`` lower-cases and prefix-matches, so this
checks the obvious case-variation bypasses AND the Unicode ones
(LATIN SMALL LETTER LONG S, FULLWIDTH S, ANGSTROM SIGN) that would
slip through only if the comparison were casefold/NFKC-normalising.
"""
# CONTROL: a brand-new key under an allow-listed namespace is created.
fresh = f"llm.matrixprobe_{uuid.uuid4().hex[:8]}"
resp = _put_setting(client, fresh, "x")
assert resp.status_code == 201, resp.text[:200]
assert resp.json()["setting"]["key"] == fresh, resp.text[:200]
assert _get_setting(client, fresh).json()["value"] == "x"
for key in (
"security.foo",
"SECURITY.foo",
"SeCuRiTy.foo",
"ſecurity.foo", # LATIN SMALL LETTER LONG S
"security.foo", # FULLWIDTH LATIN SMALL LETTER S
"auth.Koo", # KELVIN SIGN (NFKC/casefold-folds to "k")
"bootstrap.x",
"db_config.x",
):
resp = _put_setting(client, key, "x")
assert resp.status_code == 400, f"{key!r} -> {resp.status_code}"
assert "not allowed" in resp.json()["error"], (
f"{key!r} -> {resp.text[:200]}"
)
# CONSEQUENCE: no row was created for it.
assert _get_setting(client, key).status_code == 404, key
def test_settings_text_value_type_confusion_coerces_and_round_trips(client):
"""Type-confusion axis on the VALUE of a ``text`` setting.
A dict/list/int/bool sent where the UI sends a string is not rejected —
``coerce_setting_for_write`` -> ``get_typed_setting_value`` stringifies
it. Pin the exact coercion (``str()``, i.e. Python repr for containers,
NOT ``json.dumps``) because a future switch to json.dumps would silently
change every stored value's shape. Also pins that null bytes, CRLF and
template syntax survive the round-trip byte-for-byte: no C-string
truncation at the null byte, and no Jinja evaluation.
"""
# CONTROL: a plain string round-trips unchanged.
assert _put_setting(client, SETTING_TEXT, "llama3").status_code == 200
assert _get_setting(client, SETTING_TEXT).json()["value"] == "llama3"
for sent, expected in (
({"a": 1}, "{'a': 1}"), # Python repr, not JSON
([1, 2], "[1, 2]"),
(5, "5"),
(True, "True"),
("a\x00b", "a\x00b"), # not truncated at the NUL
("a\r\nX-Evil: 1", "a\r\nX-Evil: 1"), # CRLF preserved verbatim
("{{7*7}} ${7*7}", "{{7*7}} ${7*7}"), # not evaluated
):
resp = _put_setting(client, SETTING_TEXT, sent)
assert resp.status_code == 200, f"{sent!r} -> {resp.text[:200]}"
got = _get_setting(client, SETTING_TEXT)
assert got.status_code == 200, got.text[:200]
assert got.json()["value"] == expected, (
f"{sent!r} stored as {got.json()['value']!r}, want {expected!r}"
)
assert "49" not in _get_setting(client, SETTING_TEXT).text
def test_settings_uncoercible_number_is_rejected_not_silently_nulled(client):
from local_deep_research.database.session_context import (
get_user_db_session,
)
from local_deep_research.settings.manager import SettingsManager
username = client.ldr_username
# CONTROL 1: a real integer is stored and read back as that integer.
assert _put_setting(client, SETTING_NUM, 3).status_code == 200
assert _get_setting(client, SETTING_NUM).json()["value"] == 3
with get_user_db_session(username) as session:
assert (
SettingsManager(db_session=session).get_setting(SETTING_NUM, 5) == 3
)
# CONTROL 2: an out-of-range integer IS rejected, proving this route
# can and does return 400 for a bad value on this very key.
resp = _put_setting(client, SETTING_NUM, -1)
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["error"] == f"Invalid value for setting {SETTING_NUM}"
assert _get_setting(client, SETTING_NUM).json()["value"] == 3 # unchanged
# The defect: an uncoercible string.
resp = _put_setting(client, SETTING_NUM, "abc")
# CONSEQUENCE, asserted regardless of how the route is fixed: the
# stored value must never become NULL while the caller is told the
# write succeeded.
stored = _get_setting(client, SETTING_NUM).json()["value"]
assert stored is not None, (
f"PUT returned {resp.status_code} {resp.text[:120]} but the stored "
f"value is now {stored!r}"
)
assert resp.status_code == 400, f"{resp.status_code} {resp.text[:200]}"
def test_settings_key_control_characters_are_rejected(client):
# CONTROL 1 (validator unit level): the characters the validator DOES
# know about are refused, so the predicate is live.
assert is_valid_setting_key("llm.model") is True
assert is_valid_setting_key("llm.mo del") is False
assert is_valid_setting_key("llm.model\r\nx") is False
assert is_valid_setting_key("llm.mo\tdel") is False
# CONTROL 2 (HTTP level): the same rejections are visible on the route.
for key, encoded in (
("llm.mo del", "llm.mo%20del"),
("llm.model\r\nx", "llm.model%0d%0ax"),
("llm.mo\tdel", "llm.mo%09del"),
):
resp = client.put(f"/settings/api/{encoded}", json={"value": "x"})
assert resp.status_code == 400, f"{key!r} -> {resp.status_code}"
assert "malformed" in resp.json()["error"], f"{key!r} -> {resp.text}"
# Every ASCII control character is refused at the shared validator.
for codepoint in [*range(0x20), 0x7F]:
assert not is_valid_setting_key(f"llm.model{chr(codepoint)}x")
for encoded in ("%00", "%07", "%1b", "%7f"):
key = f"llm.model{encoded}x"
resp = client.put(f"/settings/api/{key}", json={"value": "x"})
assert resp.status_code == 400, f"{encoded} -> {resp.text[:200]}"
assert "malformed" in resp.json()["error"]
# Rejection happens before creating a setting row.
assert client.get(f"/settings/api/{key}").status_code == 404
# The HTTP guard accepts an ordinary new key and preserves its value.
resp = client.put(
"/settings/api/llm.release_review_key_2", json={"value": "retained"}
)
assert resp.status_code == 201, resp.text[:200]
assert (
client.get("/settings/api/llm.release_review_key_2").json()["value"]
== "retained"
)
# ===========================================================================
# C. POST /api/chat/sessions — chat
# ===========================================================================
def test_chat_create_session_type_confusion_is_rejected(client):
"""``initial_query``/``title`` are hand-validated (no Pydantic model).
This is the shape start_research is missing (see the xfail above), so
it is pinned here to stop the guard being "simplified" away.
"""
# CONTROL: a string initial_query creates a real session.
resp = client.post("/api/chat/sessions", json={"initial_query": "hello"})
assert resp.status_code == 200, resp.text[:300]
body = resp.json()
assert body["success"] is True and body["session_id"], resp.text[:300]
assert body["session"]["title"] == "hello", resp.text[:300]
created_id = body["session_id"]
for bad in (5, ["a"], {"a": 1}, 1.5, True):
resp = client.post("/api/chat/sessions", json={"initial_query": bad})
assert resp.status_code == 400, f"{bad!r} -> {resp.status_code}"
assert resp.json()["error"] == "initial_query must be a string", (
f"{bad!r} -> {resp.text[:200]}"
)
for bad in ({"a": 1}, 7, [1]):
resp = client.post("/api/chat/sessions", json={"title": bad})
assert resp.status_code == 400, f"title={bad!r} -> {resp.status_code}"
assert resp.json()["success"] is False, f"{bad!r} -> {resp.text[:200]}"
# Non-object body.
resp = client.post(
"/api/chat/sessions",
content=b"[1,2]",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["error"] == "Request body must be a JSON object"
# CONSEQUENCE: exactly one session exists — none of the seven rejected
# payloads created a row.
listing = client.get("/api/chat/sessions")
assert listing.status_code == 200, listing.text[:200]
ids = [s["id"] for s in listing.json()["sessions"]]
assert ids == [created_id], listing.text[:400]
# ===========================================================================
# D. POST /api/followup/prepare — follow-up research
# ===========================================================================
def test_followup_prepare_hostile_parent_id_never_500s(client):
"""``parent_research_id`` is forwarded to a SQLAlchemy filter and to
``FollowUpResearchService.load_parent_research`` untyped.
A dict/list/int/traversal string must come back as a clean 404, not a
500 with a logged stack trace (the router carries an explicit comment
about that regression for the non-object-body case).
"""
username = client.ldr_username
# CONTROL: a real parent research resolves and returns its summary.
rid = _seed_research(username, "Parent title")
resp = client.post(
"/api/followup/prepare",
json={"parent_research_id": rid, "question": "and then?"},
)
assert resp.status_code == 200, resp.text[:300]
body = resp.json()
assert body["success"] is True, resp.text[:300]
assert body["parent_research"]["id"] == rid, resp.text[:300]
# Non-object body and missing fields are distinguishable 400s.
resp = client.post(
"/api/followup/prepare",
content=b"[1,2]",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["error"] == "Request body must be a JSON object"
resp = client.post("/api/followup/prepare", json={})
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["error"] == "Missing parent_research_id or question"
for bad in (
{"a": 1},
[1],
99999,
"../../../../etc/passwd",
"a\x00b",
"' OR 1=1 --",
):
resp = client.post(
"/api/followup/prepare",
json={"parent_research_id": bad, "question": "q"},
)
assert resp.status_code == 404, (
f"{bad!r} -> {resp.status_code} {resp.text[:200]}"
)
assert resp.json()["error"] == "Parent research not found", (
f"{bad!r} -> {resp.text[:200]}"
)
# SQLi control: the tautology did NOT match the row the control proved
# is reachable — the filter is parameterised, not string-built.
resp = client.post(
"/api/followup/prepare",
json={"parent_research_id": rid, "question": 5},
)
assert resp.status_code == 200, resp.text[:200]
# ===========================================================================
# E. Collections: create + upload
# ===========================================================================
COLLECTIONS = "/library/api/collections"
def test_create_collection_type_confusion_and_type_allowlist(client):
"""``name``/``description``/``type`` are hand-validated; ``type`` is
additionally allow-listed so a user cannot forge a system collection
(``notes``, ``default_library``, ``research_history``) that would be
undeletable and could shadow the real notes corpus.
"""
# CONTROL: a legitimate create returns a collection id.
resp = client.post(
COLLECTIONS, json={"name": "Legit", "type": "user_uploads"}
)
assert resp.status_code == 200, resp.text[:300]
assert resp.json()["collection"]["name"] == "Legit", resp.text[:300]
for bad in (5, None, {"a": 1}, [1], True):
resp = client.post(COLLECTIONS, json={"name": bad})
assert resp.status_code == 400, f"name={bad!r} -> {resp.status_code}"
assert resp.json()["error"] == "Name must be a string", (
f"{bad!r} -> {resp.text[:200]}"
)
resp = client.post(COLLECTIONS, json={"name": "d", "description": 5})
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["error"] == "Description must be a string"
resp = client.post(COLLECTIONS, json={"name": "t", "type": 3})
assert resp.status_code == 400, resp.text[:200]
assert resp.json()["error"] == "Collection type must be a string"
for forged in ("notes", "default_library", "research_history"):
resp = client.post(COLLECTIONS, json={"name": forged, "type": forged})
assert resp.status_code == 400, f"{forged} -> {resp.status_code}"
assert "Invalid collection type" in resp.json()["error"], (
f"{forged} -> {resp.text[:200]}"
)
# CONSEQUENCE: only the control collection was created.
listing = client.get(COLLECTIONS)
assert listing.status_code == 200, listing.text[:200]
names = {c["name"] for c in listing.json()["collections"]}
assert "Legit" in names, listing.text[:400]
assert names.isdisjoint({"notes", "default_library", "research_history"}), (
listing.text[:400]
)
def test_collection_upload_filename_traversal_is_flattened(client, tmp_path):
"""Filename axis: the multipart ``filename`` reaches ``sanitize_filename``
and then the document row / on-disk store.
Asserts the CONSEQUENCE on the filesystem (nothing is written outside
the data dir) as well as the sanitised name that comes back.
"""
escape_a = tmp_path / "pwned_rel.txt"
escape_b = tmp_path / "pwned_abs.txt"
assert not escape_a.exists() and not escape_b.exists()
cid = client.post(COLLECTIONS, json={"name": "Uploads"}).json()[
"collection"
]["id"]
def _upload(filename, payload):
return client.post(
f"{COLLECTIONS}/{cid}/upload",
files={"files": (filename, io.BytesIO(payload), "text/plain")},
)
# CONTROL: an ordinary filename is accepted and keeps its name.
resp = _upload("notes.txt", b"control body")
assert resp.status_code == 200, resp.text[:300]
entry = resp.json()["uploaded"][0]
assert entry["filename"] == "notes.txt", resp.text[:300]
assert entry["status"] == "uploaded", resp.text[:300]
# Traversal / absolute paths are FLATTENED, not rejected: every path
# separator and dot-segment is gone, so the stored name cannot address
# a parent directory.
for filename, payload in (
(f"../../../..{escape_a}", b"escape rel"),
(str(escape_b), b"escape abs"),
("a\r\nb.txt", b"crlf body"),
):
resp = _upload(filename, payload)
assert resp.status_code == 200, f"{filename!r} -> {resp.text[:200]}"
stored = resp.json()["uploaded"][0]["filename"]
assert "/" not in stored and "\\" not in stored, (
f"{filename!r} -> {stored!r}"
)
assert ".." not in stored, f"{filename!r} -> {stored!r}"
assert "\r" not in stored and "\n" not in stored, (
f"{filename!r} -> {stored!r}"
)
# A NUL-spliced extension resolves to the REAL trailing extension and
# is then refused by the format allow-list — it does not smuggle
# ".txt" past the check.
resp = _upload("ok.txt\x00.exe", b"nul body")
assert resp.status_code == 200, resp.text[:300]
assert resp.json()["uploaded"] == [], resp.text[:300]
assert resp.json()["errors"][0]["error"] == "Unsupported format: .exe", (
resp.text[:300]
)
# Names that sanitise to nothing are refused outright.
for filename in ("...", "../.."):
resp = _upload(filename, b"empty name %s" % filename.encode())
assert resp.status_code == 200, resp.text[:200]
assert resp.json()["uploaded"] == [], f"{filename!r} {resp.text[:200]}"
assert (
resp.json()["errors"][0]["error"] == "Invalid or unsafe filename"
), f"{filename!r} -> {resp.text[:250]}"
# CONSEQUENCE: nothing was written to either escape target.
assert not escape_a.exists(), f"{escape_a} was created"
assert not escape_b.exists(), f"{escape_b} was created"
# ===========================================================================
# F. POST /api/v1/research/{id}/export/{format} — user text -> HTTP header
# ===========================================================================
def test_export_content_disposition_cannot_be_injected_by_title(client):
"""The download filename is derived from the research TITLE, which is
user-supplied text, and is interpolated into ``Content-Disposition``.
Under Flask this was ``send_file``; the port hand-builds the header, so
a raw CR/LF or a non-latin-1 character in the title is the classic
response-splitting / header-encoding-crash pair. The route uses
a quoted ASCII fallback plus RFC 5987 ``filename*=UTF-8''`` with
``quote(filename, safe="")``.
"""
from local_deep_research.exporters import ExporterRegistry
assert "ris" in ExporterRegistry.get_available_formats(), (
"the pure-python RIS exporter is gone; pick another dependency-free "
"format for this test"
)
username = client.ldr_username
def _export(title):
rid = _seed_research(username, title)
return client.post(f"/api/v1/research/{rid}/export/ris")
# CONTROL: a benign title produces a readable, unencoded filename.
resp = _export("My Report")
assert resp.status_code == 200, resp.text[:200]
assert (
resp.headers["content-disposition"]
== 'attachment; filename="My_Report.ris"; '
"filename*=UTF-8''My_Report.ris"
), resp.headers["content-disposition"]
for title, must_not_contain, must_contain in (
("a\r\nX-Evil: 1", ("\r", "\n"), ("%0D%0A",)),
("../../../../etc/passwd", ("/", ".."), ("etcpasswd",)),
("a\x00b", ("\x00", "%00"), ("ab.ris",)),
# Non-latin-1 text would raise at header encoding if interpolated
# raw; RFC 5987 percent-encodes it. (The en-dash is separately
# replaced by the filename sanitiser, so only the CJK/accented
# characters that DO survive sanitisation are asserted on.)
("報告書 café", ("報", "é"), ("%E5%A0%B1%E5%91%8A%E6%9B%B8", "%C3%A9")),
):
resp = _export(title)
assert resp.status_code == 200, f"{title!r} -> {resp.text[:200]}"
header = resp.headers["content-disposition"]
plain, encoded = header.split("; filename*=UTF-8''")
assert re.fullmatch(r'attachment; filename="[A-Za-z0-9._() -]+"', plain)
assert ";" not in encoded, header
for bad in must_not_contain:
assert bad not in header, (
f"{title!r} -> {header!r} contains {bad!r}"
)
for good in must_contain:
assert good in header, f"{title!r} -> {header!r} lacks {good!r}"
# No injected header materialised on the response.
assert "x-evil" not in {k.lower() for k in resp.headers}
# And an unsupported format never reaches the exporter.
rid = _seed_research(username, "ok")
resp = client.post(f"/api/v1/research/{rid}/export/notaformat")
assert resp.status_code == 400, resp.text[:200]
assert "Invalid format" in resp.json()["error"], resp.text[:200]
# ===========================================================================
# G. POST /news/api/subscribe — news subscription
# ===========================================================================
SUBSCRIBE = "/news/api/subscribe"
def _subscriptions(username):
from local_deep_research.database.models.news import NewsSubscription
from local_deep_research.database.session_context import (
get_user_db_session,
)
with get_user_db_session(username) as session:
return {
sub.query_or_topic: (
sub.refresh_interval_minutes,
sub.created_at,
sub.next_refresh,
sub.status,
)
for sub in session.query(NewsSubscription).all()
}
def test_news_subscribe_rejects_nonpositive_refresh_interval(client):
username = client.ldr_username
# CONTROL: a sane interval is accepted and schedules into the FUTURE.
resp = client.post(
SUBSCRIBE, json={"query": "control", "refresh_minutes": 60}
)
assert resp.status_code == 200, resp.text[:300]
assert resp.json()["refresh_minutes"] == 60, resp.text[:300]
rows = _subscriptions(username)
interval, created, nxt, status = rows["control"]
assert interval == 60 and status == "active", rows["control"]
assert nxt > created, f"control next_refresh {nxt} not after {created}"
# Regression cases. Both assertions below are UNCONDITIONAL: the first reads
# "either no row was persisted, or the persisted row is schedulable",
# so it cannot be skipped by the route happening to return 200.
for label, minutes in (("zero", 0), ("negative", -100)):
resp = client.post(
SUBSCRIBE, json={"query": label, "refresh_minutes": minutes}
)
row = _subscriptions(username).get(label)
assert row is None or (
row[0] >= 1 and row[2] - row[1] >= timedelta(minutes=1)
), (
f"refresh_minutes={minutes} was persisted as interval={row[0]} "
f"with next_refresh={row[2]}, only {row[2] - row[1]} after "
f"created_at={row[1]} -- the subscription is due immediately "
f"and, via scheduler/background.py:628 (`refresh_minutes <= 60`"
f" -> interval trigger), gets an APScheduler interval trigger "
f"of {row[0]} minutes."
)
assert resp.status_code == 400, (
f"refresh_minutes={minutes} -> {resp.status_code} {resp.text[:200]}"
)
def test_news_subscribe_type_confusion_is_rejected_not_500(client):
# CONTROL: the benign form of each field is accepted through the same
# code path.
resp = client.post(
SUBSCRIBE,
json={
"query": "control",
"refresh_minutes": 240,
"folder_id": None,
"search_iterations": 2,
},
)
assert resp.status_code == 200, resp.text[:300]
assert resp.json()["subscription_id"], resp.text[:300]
for field, value in (
("refresh_minutes", "abc"),
("refresh_minutes", 2**63),
("folder_id", {"a": 1}),
("query", {"a": 1}),
):
resp = client.post(SUBSCRIBE, json={"query": "x", field: value})
assert resp.status_code == 400, (
f"{field}={value!r} -> {resp.status_code} {resp.text[:220]}"
)
@pytest.mark.parametrize(
"key",
["llm.model", "custom.key-with_dash_2", "custom.模型", "custom.modèle"],
)
def test_setting_keys_preserve_printable_names(key):
assert is_valid_setting_key(key)