~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
"""Static-asset serving on the FastAPI port.
Flask's ``send_from_directory``-based ``/static/<path:path>`` route
(``git show origin/main:src/local_deep_research/web/app_factory.py``,
``app_serve_static`` at ~line 905, ``favicon`` at ~line 891) became two
hand-written FastAPI handlers in
``web/fastapi_app.py::_add_static_routes`` -- ``favicon()`` and
``serve_static()`` -- each returning a bare Starlette ``FileResponse``.
Starlette's own ``StaticFiles`` app is NOT used for ``/static/``; only
the hand-written handlers are. That matters for two of the behaviours
pinned below (symlink containment and conditional GET), because
``StaticFiles`` implements both and a bare ``FileResponse`` implements
neither.
What is covered here
--------------------
* path traversal: ``..`` segments, percent-encoded ``..``, a literal
(post-decode) ``%2e%2e``, absolute paths, NUL bytes, unicode
look-alike dots, over-long segments, and symlink escape;
* ``Content-Type`` per extension, checked against werkzeug's own
``send_from_directory`` -- i.e. against the exact library call main
made -- so a silent mimetype drift shows up as a parity failure;
* ``ETag`` / ``Last-Modified`` and conditional GET
(``If-None-Match`` / ``If-Modified-Since``);
* ``Accept-Ranges`` / 206 / 416 / multipart byteranges / ``If-Range``;
* the 404 path (missing asset, directory, empty path) and the
``dist/`` cache-control branches;
* the ``/redirect-static/<path>`` legacy shim serves the same asset,
content type and cache policy without a redirect.
Two test styles are used:
``isolated_static``
Builds the REAL production handlers (``_add_static_routes``) over a
throwaway ``STATIC_DIR`` in ``tmp_path``. This is production code,
not a re-implementation -- pointing ``STATIC_DIR`` elsewhere is the
only change. It buys a genuine escape target: a readable sentinel
file that sits just outside the served root, so a traversal test
fails loudly by *serving the secret* if the guard is removed, rather
than passing vacuously because there was nothing to reach.
``app`` (the real singleton)
Full middleware stack over the real packaged ``web/static``
directory, for the parity-visible headers and for traversal aimed at
real source files on disk.
``validator_spy`` records every ``PathValidator.validate_safe_path``
call the handler makes and the exception it raised, so each traversal
test asserts the *specific* refusal reason rather than merely "not 200"
-- a 404 alone cannot distinguish "guard fired" from "no such file".
"""
import errno
import mimetypes
import os
import re
import stat
from email.utils import parsedate_to_datetime
from pathlib import Path
from types import SimpleNamespace
import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from werkzeug.test import EnvironBuilder
from werkzeug.utils import send_from_directory as wz_send_from_directory
from local_deep_research.security.path_validator import PathValidator
from local_deep_research.web import fastapi_app as fastapi_app_module
SENTINEL = "SENTINEL_STATIC_ESCAPE_a1b2c3"
# httpx decodes the URL once while building the request and
# starlette's ASGITransport unquotes ``scope["path"]`` again, so the
# handler sees the path after TWO decodes. Chains used below:
# "%2e%2e" -> ".." (one decode is enough)
# "%25252e" -> "%252e" -> "%2e" (a LITERAL "%2e" at the handler)
DOTDOT = "%2e%2e"
LITERAL_PCT_DOT = "%25252e"
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
@pytest.fixture
def validator_spy(monkeypatch):
"""Record every ``validate_safe_path`` call and its outcome.
Delegates to the real implementation -- the wrapper changes nothing
about the decision, it only observes it.
"""
real = PathValidator.validate_safe_path
records: list[SimpleNamespace] = []
def _wrapper(user_input, base_dir, *args, **kwargs):
try:
result = real(user_input, base_dir, *args, **kwargs)
except BaseException as exc:
records.append(
SimpleNamespace(
arg=user_input, base=str(base_dir), exc=exc, result=None
)
)
raise
records.append(
SimpleNamespace(
arg=user_input, base=str(base_dir), exc=None, result=result
)
)
return result
monkeypatch.setattr(
PathValidator, "validate_safe_path", staticmethod(_wrapper)
)
return records
@pytest.fixture
def isolated_static(tmp_path, monkeypatch):
"""Production ``_add_static_routes`` handlers over a tmp STATIC_DIR."""
static_dir = tmp_path / "static"
(static_dir / "css").mkdir(parents=True)
(static_dir / "css" / "site.css").write_text("body{color:red}\n")
(static_dir / "favicon.ico").write_bytes(b"\x00\x00\x01\x00icodata")
(static_dir / "blob.bin").write_bytes(bytes(range(256)) * 40)
(static_dir / "js").mkdir()
(static_dir / "js" / "plain.js").write_text("var unbuilt=3;\n")
(static_dir / "js" / "source.abcdef123456.js").write_text("var source=4;\n")
dist = static_dir / "dist"
(dist / "js").mkdir(parents=True)
(dist / "js" / "app.abcdef123456.js").write_text("var hashed=1;\n")
(dist / "js" / "plain.js").write_text("var plain=2;\n")
(dist / "fonts").mkdir()
(dist / "fonts" / "inter.woff2").write_bytes(b"woff2-payload")
outside = tmp_path / "outside"
outside.mkdir()
secret = outside / "secret.txt"
secret.write_text(SENTINEL + "\n")
monkeypatch.setattr(fastapi_app_module, "STATIC_DIR", str(static_dir))
sub = FastAPI()
fastapi_app_module._add_static_routes(sub)
from local_deep_research.web.routers.research import redirect_static
sub.add_api_route("/redirect-static/{path:path}", redirect_static)
sub.add_middleware(fastapi_app_module.SecurityHeadersMiddleware)
@sub.get("/private-cache-probe")
def private_cache_probe():
return {"private": "fixture"}
return SimpleNamespace(
client=TestClient(sub, raise_server_exceptions=False),
static_dir=static_dir,
outside=outside,
secret=secret,
)
@pytest.fixture
def real_static_dir() -> Path:
return Path(fastapi_app_module.STATIC_DIR)
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _refusals(records, needle):
"""The recorded calls that were refused with `needle` in the reason."""
return [r for r in records if r.exc is not None and needle in str(r.exc)]
def _assert_refused(records, sent_as, reason, resp, forbidden):
"""One place for the four things every traversal test must show."""
assert resp.status_code == 404, (
f"{sent_as!r} returned {resp.status_code}, so the guard did not "
f"refuse it: {resp.text[:400]}"
)
assert forbidden not in resp.text, (
f"{sent_as!r} LEAKED content that lives outside the served root"
)
hits = _refusals(records, reason)
assert hits, (
f"no validate_safe_path call was refused with {reason!r}; "
f"recorded calls were "
f"{[(r.arg, str(r.exc)) for r in records]!r}. A 404 on its own "
f"does not prove the traversal guard ran."
)
def _werkzeug_response(directory: Path, rel: str, headers=None):
"""What main's Flask route produced for the same file.
``flask.send_from_directory`` is a thin wrapper over
``werkzeug.utils.send_from_directory(directory, path,
environ=request.environ)``, and werkzeug's ``send_file`` defaults to
``conditional=True``. Calling werkzeug directly reproduces main's
response without needing Flask installed.
"""
environ = EnvironBuilder(
path=f"/static/{rel}", headers=headers or {}
).get_environ()
return wz_send_from_directory(str(directory), rel, environ)
# ---------------------------------------------------------------------------
# Path traversal -- the security-critical half
# ---------------------------------------------------------------------------
class TestTraversalAgainstARealEscapeTarget:
"""Every case here aims at ``<tmp>/outside/secret.txt``, a file that
really exists and really is readable. Each test first proves that
(the negative control is inside the test), so a passing assertion
means the guard refused a reachable target -- not that the target
was missing."""
def test_sentinel_is_actually_reachable_on_disk(self, isolated_static):
"""Control for the whole class: without the guard, the traversal
below resolves to a readable file holding the sentinel."""
naive = isolated_static.static_dir / ".." / "outside" / "secret.txt"
assert naive.is_file()
assert SENTINEL in naive.read_text()
def test_dotdot_escape_is_refused(self, isolated_static, validator_spy):
resp = isolated_static.client.get(
f"/static/{DOTDOT}/outside/secret.txt"
)
assert any(r.arg == "../outside/secret.txt" for r in validator_spy), (
"the handler never saw a '..' segment -- the encoding chain "
f"changed; recorded: {[r.arg for r in validator_spy]!r}"
)
_assert_refused(
validator_spy,
"%2e%2e/outside/secret.txt",
"potential traversal attempt",
resp,
SENTINEL,
)
def test_nested_dotdot_escape_is_refused(
self, isolated_static, validator_spy
):
"""``css/../../outside/...`` -- normalises back out of the root
only after a legitimate-looking first segment."""
resp = isolated_static.client.get(
f"/static/css/{DOTDOT}/{DOTDOT}/outside/secret.txt"
)
assert any(
r.arg == "css/../../outside/secret.txt" for r in validator_spy
), f"recorded: {[r.arg for r in validator_spy]!r}"
_assert_refused(
validator_spy,
"css/%2e%2e/%2e%2e/outside/secret.txt",
"potential traversal attempt",
resp,
SENTINEL,
)
def test_absolute_path_is_refused(self, isolated_static, validator_spy):
"""``/static//abs/path`` delivers a leading-slash absolute path to
the handler; ``safe_join`` must reject it rather than let
``posixpath.join`` discard the base directory."""
abs_target = str(isolated_static.secret)
resp = isolated_static.client.get(f"/static/{abs_target}")
assert any(r.arg == abs_target for r in validator_spy), (
f"handler did not receive the absolute path; recorded: "
f"{[r.arg for r in validator_spy]!r}"
)
_assert_refused(
validator_spy,
abs_target,
"potential traversal attempt",
resp,
SENTINEL,
)
@pytest.mark.parametrize("prefix", ["static", "redirect-static"])
def test_symlink_escape_is_refused(self, isolated_static, prefix):
"""Both routes reject a symlink to a readable file outside the root."""
link = isolated_static.static_dir / "escape"
link.symlink_to(isolated_static.outside, target_is_directory=True)
# Control: the link really does resolve outside the root.
assert (link / "secret.txt").resolve() == isolated_static.secret
resp = isolated_static.client.get(f"/{prefix}/escape/secret.txt")
assert SENTINEL not in resp.text, (
f"symlink escape served the out-of-root file with status "
f"{resp.status_code}"
)
assert resp.status_code == 404, resp.status_code
class TestTraversalEncodings:
"""Encoding-level bypasses. These cannot reach the sentinel even
unguarded (``safe_join`` or the filesystem stops them), so each one
asserts the *specific* refusal recorded by the validator spy."""
def test_null_byte_is_refused(self, isolated_static, validator_spy):
resp = isolated_static.client.get("/static/css/site.css%00.png")
assert any("\x00" in r.arg for r in validator_spy), (
f"handler never saw a NUL byte; recorded: "
f"{[r.arg for r in validator_spy]!r}"
)
assert resp.status_code == 404
assert _refusals(validator_spy, "Null bytes are not allowed"), (
f"NUL byte was not refused by the null-byte guard; recorded: "
f"{[(r.arg, str(r.exc)) for r in validator_spy]!r}"
)
def test_literal_percent_encoded_dotdot_is_refused(
self, isolated_static, validator_spy
):
"""A literal ``%2e%2e`` that survives both decodes.
Nothing in this handler unquotes again, so this cannot escape
here -- but ``_has_encoded_traversal`` exists precisely so a
downstream decoder can never turn it into ``..``. Without this
test that guard has no HTTP-level coverage at all.
"""
resp = isolated_static.client.get(
f"/static/{LITERAL_PCT_DOT}{LITERAL_PCT_DOT}/outside/secret.txt"
)
assert any("%2e%2e" in r.arg for r in validator_spy), (
"handler did not receive a literal '%2e%2e'; the httpx/ASGI "
f"decode chain changed. recorded: "
f"{[r.arg for r in validator_spy]!r}"
)
_assert_refused(
validator_spy,
"%25252e%25252e/outside/secret.txt",
"encoded traversal pattern detected",
resp,
SENTINEL,
)
def test_unicode_fullwidth_dots_are_refused(
self, isolated_static, validator_spy
):
"""U+FF0E FULLWIDTH FULL STOP NFKC-normalises to '.'."""
resp = isolated_static.client.get("/static/../outside/secret.txt")
assert any("." in r.arg for r in validator_spy), (
f"recorded: {[r.arg for r in validator_spy]!r}"
)
_assert_refused(
validator_spy,
"../outside/secret.txt",
"unicode traversal pattern detected",
resp,
SENTINEL,
)
def test_dot_stuffing_does_not_escape(self, isolated_static):
"""``....//`` collapses to ``..../`` under ``posixpath.normpath``,
i.e. a plain (nonexistent) directory name -- not an escape. Pins
that it stays a 404 rather than becoming a traversal."""
resp = isolated_static.client.get("/static/....//outside/secret.txt")
assert resp.status_code == 404
assert SENTINEL not in resp.text
def test_overlong_segment_is_404_not_500(self, isolated_static):
"""A path segment longer than NAME_MAX makes the underlying
``stat`` raise ``OSError(ENAMETOOLONG)``, not ``ValueError``.
``serve_static`` catches ``(ValueError, OSError)`` for exactly
this; the route is unauthenticated AND rate-limit exempt, so a
missed ``OSError`` is an anonymous 500 generator.
Which layer absorbs it is interpreter-dependent -- on 3.12
``Path.is_file()`` re-raises ENAMETOOLONG (``_ignore_error``
covers only ENOENT/ENOTDIR/EBADF/ELOOP), while on 3.13+ it
delegates to ``os.path.isfile``, which swallows OSError and
ValueError itself. The project supports both
(``requires-python = ">=3.12,<3.15"``), so the handler's own
``except OSError`` is load-bearing on the low end. This test
pins the observable contract on every supported interpreter:
404, never 500.
"""
long_name = "a" * 300 + ".css"
# Control: the stat syscall behind is_file() genuinely fails with
# ENAMETOOLONG for this path, so the 404 below is the error branch
# and not an ordinary miss.
with pytest.raises(OSError) as excinfo:
os.stat(str(isolated_static.static_dir / long_name))
assert excinfo.value.errno == errno.ENAMETOOLONG
resp = isolated_static.client.get(f"/static/{long_name}")
assert resp.status_code == 404, (
f"over-long segment produced {resp.status_code}, not 404: "
f"{resp.text[:300]}"
)
class TestTraversalAgainstTheRealPackage:
"""Same attacks against the real app and the real packaged
``web/static`` directory, aimed at real source files."""
@pytest.mark.parametrize(
("attack", "rel_target", "marker"),
[
(
f"{DOTDOT}/fastapi_app.py",
"../fastapi_app.py",
"_add_static_routes",
),
(
f"{DOTDOT}/{DOTDOT}/security/path_validator.py",
"../../security/path_validator.py",
"validate_safe_path",
),
(
f"css/{DOTDOT}/{DOTDOT}/templates/base.html",
"../templates/base.html",
"<html",
),
],
)
def test_source_files_outside_static_are_not_served(
self, app, real_static_dir, attack, rel_target, marker
):
target = (real_static_dir / rel_target).resolve()
# Control: the file the traversal aims at exists and is readable.
assert target.is_file(), f"traversal target {target} is missing"
body = target.read_text(errors="replace")
assert marker in body, f"{target} no longer contains {marker!r}"
client = TestClient(app, raise_server_exceptions=False)
resp = client.get(f"/static/{attack}")
assert resp.status_code == 404, (
f"/static/{attack} returned {resp.status_code}"
)
assert marker not in resp.text, f"/static/{attack} LEAKED {target}"
# ---------------------------------------------------------------------------
# Content-Type
# ---------------------------------------------------------------------------
class TestContentType:
#: (path under web/static, expected Content-Type)
CASES = [
("css/styles.css", "text/css; charset=utf-8"),
("js/app.js", "text/javascript; charset=utf-8"),
("favicon.png", "image/png"),
("sounds/success.mp3", "audio/mpeg"),
("templates/followup_modal.html", "text/html; charset=utf-8"),
]
@pytest.mark.parametrize(("rel", "expected"), CASES)
def test_content_type_per_extension(self, app, rel, expected):
client = TestClient(app, raise_server_exceptions=False)
resp = client.get(f"/static/{rel}")
assert resp.status_code == 200, f"{rel}: {resp.status_code}"
assert resp.headers["content-type"] == expected, (
f"{rel} served as {resp.headers['content-type']!r}; the app "
f"sends X-Content-Type-Options: nosniff, so a wrong type is a "
f"broken asset, not a cosmetic issue"
)
@pytest.mark.parametrize(
"rel",
[c[0] for c in CASES] + ["sounds/README.md"],
)
def test_content_type_matches_main(self, app, real_static_dir, rel):
"""Parity with main: same header werkzeug's
``send_from_directory`` (what Flask called) produces."""
client = TestClient(app, raise_server_exceptions=False)
resp = client.get(f"/static/{rel}")
assert resp.status_code == 200
main_resp = _werkzeug_response(real_static_dir, rel)
assert (
resp.headers["content-type"] == main_resp.headers["Content-Type"]
), (
f"{rel}: FastAPI sends {resp.headers['content-type']!r}, "
f"main sent {main_resp.headers['Content-Type']!r}"
)
def test_unknown_extension_falls_back_to_octet_stream(
self, isolated_static
):
assert mimetypes.guess_type("blob.bin")[0] in (
None,
"application/octet-stream",
)
resp = isolated_static.client.get("/static/blob.bin")
assert resp.status_code == 200
assert resp.headers["content-type"] == "application/octet-stream"
def test_favicon_success_path_serves_ico(self, isolated_static):
"""The real package ships ``favicon.png``, not ``favicon.ico``,
so ``/favicon.ico`` always takes the miss branch there and the
FileResponse branch has no coverage. Exercise it here."""
resp = isolated_static.client.get("/favicon.ico")
assert resp.status_code == 200, resp.text[:200]
assert resp.headers["content-type"] == "image/x-icon"
assert (
resp.content
== (isolated_static.static_dir / "favicon.ico").read_bytes()
)
# ---------------------------------------------------------------------------
# Validators and conditional GET
# ---------------------------------------------------------------------------
class TestValidators:
def test_etag_and_last_modified_present_and_consistent(
self, app, real_static_dir
):
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/static/css/styles.css")
assert resp.status_code == 200
etag = resp.headers.get("etag")
assert etag and re.fullmatch(r'"[0-9a-f]{32}"', etag), (
f"missing/odd ETag: {etag!r}"
)
last_modified = resp.headers.get("last-modified")
assert last_modified, "no Last-Modified on a static asset"
served = parsedate_to_datetime(last_modified).timestamp()
on_disk = (real_static_dir / "css" / "styles.css").stat().st_mtime
# HTTP-date has one-second resolution.
assert abs(served - on_disk) < 2, (
f"Last-Modified {last_modified!r} ({served}) does not match the "
f"file mtime ({on_disk})"
)
again = client.get("/static/css/styles.css")
assert again.headers.get("etag") == etag, (
"ETag is unstable across requests for an unchanged file"
)
def test_etag_changes_when_the_file_changes(self, isolated_static):
css = isolated_static.static_dir / "css" / "site.css"
first = isolated_static.client.get("/static/css/site.css")
assert first.status_code == 200
original = first.headers["etag"]
css.write_text("body{color:blue}\nbody{padding:0}\n")
os.utime(css, (1_700_000_000, 1_700_000_000))
second = isolated_static.client.get("/static/css/site.css")
assert second.status_code == 200
assert second.headers["etag"] != original, (
"ETag did not change after the file changed -- clients holding "
"the old validator would never see the new bytes"
)
def test_main_returned_304_for_conditional_get(self, real_static_dir):
"""Baseline for the two strict-xfails below.
Not a re-implementation: this calls the very function main's
route called (``werkzeug.utils.send_from_directory``, which
Flask's ``send_from_directory`` wraps) with
``conditional=True`` left at its default.
"""
full = _werkzeug_response(real_static_dir, "css/styles.css")
assert full.status_code == 200
for header, value in (
("If-None-Match", full.headers["ETag"]),
("If-Modified-Since", full.headers["Last-Modified"]),
):
conditional = _werkzeug_response(
real_static_dir, "css/styles.css", headers={header: value}
)
assert conditional.status_code == 304, (
f"main's own dependency did not 304 on {header}"
)
@pytest.mark.xfail(
strict=True,
reason=(
"serve_static returns a bare starlette FileResponse, which "
"implements neither If-None-Match nor If-Modified-Since "
"(starlette handles those in StaticFiles.is_not_modified, "
"which this route does not use). Main's Flask route used "
"send_from_directory -> send_file(conditional=True) and "
"returned 304. Every asset is served "
"'public, max-age=0, must-revalidate', so browsers "
"revalidate on every page load and now get a full 200 body "
"back each time instead of an empty 304."
),
)
def test_if_none_match_returns_304(self, app):
client = TestClient(app, raise_server_exceptions=False)
first = client.get("/static/css/styles.css")
assert first.status_code == 200
etag = first.headers["etag"]
second = client.get(
"/static/css/styles.css", headers={"If-None-Match": etag}
)
assert second.status_code == 304, (
f"If-None-Match with the server's own ETag returned "
f"{second.status_code} and {len(second.content)} bytes of body"
)
assert second.content == b""
@pytest.mark.xfail(
strict=True,
reason=(
"Same defect as test_if_none_match_returns_304, via the "
"Last-Modified validator."
),
)
def test_if_modified_since_returns_304(self, app):
client = TestClient(app, raise_server_exceptions=False)
first = client.get("/static/css/styles.css")
assert first.status_code == 200
second = client.get(
"/static/css/styles.css",
headers={"If-Modified-Since": first.headers["last-modified"]},
)
assert second.status_code == 304, (
f"If-Modified-Since returned {second.status_code}"
)
# ---------------------------------------------------------------------------
# Range requests
# ---------------------------------------------------------------------------
class TestRangeRequests:
def test_accept_ranges_advertised_on_a_full_response(self, app):
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/static/sounds/success.mp3")
assert resp.status_code == 200
assert resp.headers.get("accept-ranges") == "bytes"
def test_single_range_returns_206_with_the_right_bytes(
self, app, real_static_dir
):
asset = real_static_dir / "sounds" / "success.mp3"
raw = asset.read_bytes()
assert len(raw) > 1024, "test asset is too small to range over"
client = TestClient(app, raise_server_exceptions=False)
resp = client.get(
"/static/sounds/success.mp3", headers={"Range": "bytes=100-599"}
)
assert resp.status_code == 206, resp.status_code
assert resp.headers["content-range"] == f"bytes 100-599/{len(raw)}"
assert resp.headers["content-length"] == "500"
assert resp.content == raw[100:600], (
"206 body is not the requested slice of the file"
)
def test_suffix_range_returns_the_tail(self, app, real_static_dir):
raw = (real_static_dir / "sounds" / "success.mp3").read_bytes()
client = TestClient(app, raise_server_exceptions=False)
resp = client.get(
"/static/sounds/success.mp3", headers={"Range": "bytes=-64"}
)
assert resp.status_code == 206
assert resp.content == raw[-64:]
def test_unsatisfiable_range_returns_416(self, app, real_static_dir):
size = (real_static_dir / "sounds" / "success.mp3").stat().st_size
client = TestClient(app, raise_server_exceptions=False)
resp = client.get(
"/static/sounds/success.mp3",
headers={"Range": f"bytes={size + 10}-{size + 20}"},
)
assert resp.status_code == 416, resp.status_code
assert resp.headers.get("content-range") == f"bytes */{size}"
def test_multiple_ranges_return_multipart_byteranges(self, isolated_static):
resp = isolated_static.client.get(
"/static/blob.bin", headers={"Range": "bytes=0-9, 100-109"}
)
assert resp.status_code == 206
assert resp.headers["content-type"].startswith(
"multipart/byteranges; boundary="
)
raw = (isolated_static.static_dir / "blob.bin").read_bytes()
assert raw[0:10] in resp.content
assert raw[100:110] in resp.content
def test_if_range_with_stale_validator_returns_the_whole_file(
self, isolated_static
):
"""A client whose cached copy is stale must get 200 + the full
body, not a 206 splice onto stale bytes."""
raw = (isolated_static.static_dir / "blob.bin").read_bytes()
resp = isolated_static.client.get(
"/static/blob.bin",
headers={
"Range": "bytes=0-9",
"If-Range": '"0000000000000000000000000000dead"',
},
)
assert resp.status_code == 200, resp.status_code
assert resp.content == raw
def test_if_range_with_current_etag_returns_206(self, isolated_static):
full = isolated_static.client.get("/static/blob.bin")
resp = isolated_static.client.get(
"/static/blob.bin",
headers={
"Range": "bytes=0-9",
"If-Range": full.headers["etag"],
},
)
assert resp.status_code == 206
assert resp.content == full.content[0:10]
# ---------------------------------------------------------------------------
# Misses, and the dist/ cache-control branches
# ---------------------------------------------------------------------------
class TestMisses:
def test_missing_asset_is_404_and_carries_no_validators(self, app):
"""A miss must not be cacheable and must not look like a hit.
(That the body is JSON rather than main's plain ``Not found`` is
already tracked separately; asserted here only so this test fails
loudly if the miss branch starts returning something else.)
"""
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/static/css/definitely-not-here.css")
assert resp.status_code == 404
assert "etag" not in resp.headers
assert "last-modified" not in resp.headers
assert "public" not in resp.headers.get("cache-control", "")
def test_directory_path_is_404_not_a_listing(self, app, real_static_dir):
assert (real_static_dir / "css").is_dir()
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/static/css")
assert resp.status_code == 404, resp.status_code
assert "styles.css" not in resp.text, (
"a directory request produced something listing its contents"
)
def test_empty_path_is_404_not_500(self, app):
"""``/static/`` reaches the handler with ``path == ''``;
``validate_safe_path`` raises ``ValueError('Invalid path input')``
for it, which must be caught."""
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/static/")
assert resp.status_code == 404, (
f"/static/ returned {resp.status_code}: {resp.text[:200]}"
)
class TestDistBranches:
"""``static/dist`` does not exist in the repo (Vite builds it), so
both ``dist/`` branches of ``serve_static`` are dead in every other
test. ``isolated_static`` creates one."""
def test_explicit_dist_prefix_is_not_doubled(self, isolated_static):
resp = isolated_static.client.get("/static/dist/js/plain.js")
assert resp.status_code == 200, resp.text[:200]
assert resp.text == "var plain=2;\n"
def test_hashed_dist_asset_is_immutable(self, isolated_static):
resp = isolated_static.client.get("/static/dist/js/app.abcdef123456.js")
assert resp.status_code == 200
assert resp.headers["cache-control"] == (
"public, max-age=31536000, immutable"
)
def test_unhashed_dist_asset_must_revalidate(self, isolated_static):
resp = isolated_static.client.get("/static/dist/js/plain.js")
assert resp.status_code == 200
assert resp.headers["cache-control"] == (
"public, max-age=0, must-revalidate"
)
def test_vite_base_rewrite_finds_fonts_under_dist(self, isolated_static):
"""Vite emits ``base: '/static/'`` so built CSS references
``/static/fonts/...`` while the file lives at
``static/dist/fonts/...``. The second branch bridges that."""
assert not (isolated_static.static_dir / "fonts").exists()
resp = isolated_static.client.get("/static/fonts/inter.woff2")
assert resp.status_code == 200, resp.text[:200]
assert resp.content == b"woff2-payload"
def test_dist_prefix_traversal_cannot_climb_out_of_dist(
self, isolated_static, validator_spy
):
resp = isolated_static.client.get(
f"/static/dist/{DOTDOT}/{DOTDOT}/outside/secret.txt"
)
assert any(
r.arg == "../../outside/secret.txt" for r in validator_spy
), f"recorded: {[r.arg for r in validator_spy]!r}"
_assert_refused(
validator_spy,
"dist/%2e%2e/%2e%2e/outside/secret.txt",
"potential traversal attempt",
resp,
SENTINEL,
)
def test_plain_static_asset_must_revalidate(self, app):
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/static/css/styles.css")
assert resp.status_code == 200
assert resp.headers["cache-control"] == (
"public, max-age=0, must-revalidate"
)
def test_static_file_response_can_only_serve_static_dir(isolated_static):
"""The shared helper takes no directory, so no caller can point it at
another tree (e.g. research outputs) and bypass that directory's fence.
Its fixed theme CSS response comes from bundled theme sources only."""
import inspect
from local_deep_research.web.static_files import static_file_response
assert list(inspect.signature(static_file_response).parameters) == ["path"]
assert static_file_response("css/site.css") is not None
assert static_file_response("../outside/secret.txt") is None
@pytest.mark.parametrize("prefix", ["static", "redirect-static"])
def test_theme_css_works_without_a_writable_package_directory(
isolated_static, prefix
):
"""A clean wheel has no generated CSS, and installed code may be read-only."""
from local_deep_research.web.themes import theme_registry
css_path = isolated_static.static_dir / "css" / "themes.css"
assert not css_path.exists()
css_dir = css_path.parent
original_mode = stat.S_IMODE(css_dir.stat().st_mode)
css_dir.chmod(0o555)
try:
response = isolated_static.client.get(f"/{prefix}/css/themes.css")
finally:
css_dir.chmod(original_mode)
assert response.status_code == 200
assert response.text == theme_registry.get_combined_css()
assert response.headers["content-type"] == "text/css; charset=utf-8"
assert response.headers["cache-control"] == (
"public, max-age=0, must-revalidate"
)
assert not css_path.exists()
# ---------------------------------------------------------------------------
# Legacy /redirect-static shim
# ---------------------------------------------------------------------------
def test_legacy_redirect_static_serves_the_real_asset(app):
"""``tests/web/routers/test_redirect_static.py`` pins the response; this
proves the served bytes are the real asset the /static/ mount serves."""
client = TestClient(app, raise_server_exceptions=False)
legacy = client.get("/redirect-static/css/styles.css")
assert legacy.status_code == 200, legacy.status_code
assert legacy.headers["content-type"] == "text/css; charset=utf-8"
direct = client.get("/static/css/styles.css")
assert direct.status_code == 200, direct.status_code
assert legacy.content == direct.content
class TestLegacyStaticAssetParity:
@pytest.mark.parametrize(
"path, expected, cache_control",
[
(
"css/site.css",
b"body{color:red}\n",
"public, max-age=0, must-revalidate",
),
(
"fonts/inter.woff2",
b"woff2-payload",
"public, max-age=0, must-revalidate",
),
(
"dist/fonts/inter.woff2",
b"woff2-payload",
"public, max-age=0, must-revalidate",
),
(
"js/plain.js",
b"var plain=2;\n",
"public, max-age=0, must-revalidate",
),
(
"dist/js/plain.js",
b"var plain=2;\n",
"public, max-age=0, must-revalidate",
),
(
"js/app.abcdef123456.js",
b"var hashed=1;\n",
"public, max-age=31536000, immutable",
),
(
"dist/js/app.abcdef123456.js",
b"var hashed=1;\n",
"public, max-age=31536000, immutable",
),
(
"js/source.abcdef123456.js",
b"var source=4;\n",
"public, max-age=0, must-revalidate",
),
],
)
def test_assets_and_cache_policy_match(
self, isolated_static, path, expected, cache_control
):
direct = isolated_static.client.get(f"/static/{path}")
legacy = isolated_static.client.get(
f"/redirect-static/{path}", follow_redirects=False
)
assert direct.status_code == legacy.status_code == 200
assert direct.content == legacy.content == expected
for response in (direct, legacy):
assert response.headers.get_list("cache-control") == [cache_control]
assert "pragma" not in response.headers
assert "expires" not in response.headers
assert response.headers["x-content-type-options"] == "nosniff"
assert "location" not in response.headers
assert direct.headers["content-type"] == legacy.headers["content-type"]
@pytest.mark.parametrize("prefix", ["static", "redirect-static"])
@pytest.mark.parametrize(
"path",
[
"css/site.css%00ignored",
"css/" + "x" * 300 + ".css",
"%2e%2e/outside/secret.txt",
"css/%2e%2e/%2e%2e/outside/secret.txt",
"dist/%2e%2e/%2e%2e/outside/secret.txt",
"loop.css",
],
)
def test_invalid_paths_are_404(self, isolated_static, prefix, path):
root = isolated_static.static_dir
(root / "loop.css").symlink_to(root / "loop.css")
response = isolated_static.client.get(
f"/{prefix}/{path}", follow_redirects=False
)
assert response.status_code == 404
assert SENTINEL not in response.text
assert "location" not in response.headers
@pytest.mark.parametrize("prefix", ["static", "redirect-static"])
@pytest.mark.parametrize("path", ["escape.txt", "dist/escape.txt"])
def test_built_asset_symlinks_cannot_escape(
self, isolated_static, prefix, path
):
link = isolated_static.static_dir / "dist" / "escape.txt"
link.symlink_to(isolated_static.secret)
assert link.read_text().strip() == SENTINEL
response = isolated_static.client.get(f"/{prefix}/{path}")
assert response.status_code == 404
assert SENTINEL not in response.text
@pytest.mark.parametrize("prefix", ["static", "redirect-static"])
def test_internal_symlinks_keep_the_asset_content_type(
self, isolated_static, prefix
):
root = isolated_static.static_dir
(root / "styles.bin").write_text("body{color:blue}")
(root / "alias.css").symlink_to(root / "styles.bin")
response = isolated_static.client.get(f"/{prefix}/alias.css")
assert response.status_code == 200
assert response.text == "body{color:blue}"
assert response.headers["content-type"].startswith("text/css")
assert (
response.headers["cache-control"]
== "public, max-age=0, must-revalidate"
)
@pytest.mark.parametrize(
"path, status",
[("/private-cache-probe", 200), ("/redirect-static/missing.css", 404)],
)
def test_non_asset_responses_remain_uncacheable(
self, isolated_static, path, status
):
response = isolated_static.client.get(path)
assert response.status_code == status
assert response.headers.get_list("cache-control") == [
"no-store, no-cache, must-revalidate, max-age=0"
]
assert response.headers.get_list("pragma") == ["no-cache"]
assert response.headers.get_list("expires") == ["0"]
@pytest.mark.parametrize("prefix", ["static", "redirect-static"])
def test_partial_assets_keep_the_same_cache_policy(
self, isolated_static, prefix
):
response = isolated_static.client.get(
f"/{prefix}/js/app.abcdef123456.js",
headers={"Range": "bytes=0-2"},
)
assert response.status_code == 206
assert response.content == b"var"
assert response.headers.get_list("cache-control") == [
"public, max-age=31536000, immutable"
]
assert "pragma" not in response.headers
assert "expires" not in response.headers