Skip to content

~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.

40.4 KB
Raw Blame
"""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