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.

23.6 KB
Raw Blame
"""HTTP contract of the FastAPI exception handlers.

Covers ``_register_exception_handlers`` / ``_is_api_request`` in
``web/fastapi_app.py`` plus ``web/exceptions.py`` rendered over HTTP —
the pieces the Flask-era ``register_error_handlers`` provided:

- 404 returns a fixed body, never a traceback or internal path: JSON for
  API paths, ``text/html`` for browser navigations (Flask parity — see
  ``Test404Contract``).
- 405 keeps FastAPI's JSON detail AND the ``Allow`` header (405 from
  routing is a Starlette ``HTTPException``, which the custom
  ``handle_http_exception`` — registered for *fastapi*'s subclass —
  must not intercept, or the header would be dropped).
- 401: browser-Accept requests are redirected to ``/auth/login`` with a
  URL-encoded ``next=``; API-path or JSON-Accept requests get JSON, no
  redirect.
- Unhandled exceptions become a scrubbed, fixed-shape 500.
- ``WebAPIException`` / ``AuthenticationRequiredError`` render their
  sanitized ``to_dict()`` with the exception's own status code.
- ``PolicyDeniedError`` maps to a 400 carrying the decision reason only.
- Malformed JSON body on an endpoint that reads ``await request.json()``
  returns 400 (Flask ``request.get_json()`` parity). This 500'd before
  the ``json.JSONDecodeError`` handler was added alongside these tests.

Unit-level ``to_dict()`` sanitization is covered in
``test_exceptions_behavior.py`` — not repeated here; these tests drive
the registered handlers through real ASGI request/response cycles.
"""

import importlib

import pytest
from fastapi import FastAPI, HTTPException, Request
from fastapi.testclient import TestClient
from starlette.requests import Request as StarletteRequest

from local_deep_research.web.exceptions import (
    AuthenticationRequiredError,
    WebAPIException,
)
from local_deep_research.web.fastapi_app import (
    _is_api_request,
    _register_exception_handlers,
)

SECRET_MARKER = "sekrit-internal-detail-xyzzy"
BEARER_TOKEN = "sk-abc123DEF456ghi789"  # noqa: S105 - fake credential shape


# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------


@pytest.fixture(scope="module")
def real_client():
    """TestClient on the real app — full middleware + handler stack."""
    from local_deep_research.web.fastapi_app import app

    return TestClient(app, raise_server_exceptions=False)


@pytest.fixture(scope="module")
def handler_client():
    """Minimal app wired through the REAL ``_register_exception_handlers``.

    Routes raise on demand so each handler branch can be driven without
    depending on which real endpoints happen to be able to fail.
    """
    mini = FastAPI()
    _register_exception_handlers(mini)

    @mini.post("/api/echo")
    async def echo(request: Request):
        return {"ok": await request.json()}

    @mini.get("/api/boom")
    async def boom():
        raise ValueError(f"{SECRET_MARKER} in /srv/ldr/private/app.py")

    @mini.get("/browser-boom")
    async def browser_boom():
        raise RuntimeError(SECRET_MARKER)

    @mini.get("/api/webapi")
    async def webapi():
        raise WebAPIException(
            f"upstream auth failed: Authorization: Bearer {BEARER_TOKEN}",
            status_code=418,
            error_code="TEAPOT",
        )

    @mini.get("/api/authreq")
    async def authreq():
        raise AuthenticationRequiredError(username="alice")

    @mini.get("/api/policy")
    async def policy():
        from local_deep_research.security.egress.policy import (
            Decision,
            PolicyDeniedError,
        )

        raise PolicyDeniedError(
            Decision(allowed=False, reason="scope_mismatch"),
            target=f"https://internal.example/{SECRET_MARKER}",
        )

    @mini.get("/")
    async def root():
        raise HTTPException(status_code=401, detail="Authentication required")

    @mini.get("/account/{item}")
    async def account(item: str):
        raise HTTPException(status_code=401, detail="Authentication required")

    return TestClient(mini, raise_server_exceptions=False)


def _assert_scrubbed(response):
    """No traceback frames, internal paths, or raise-site text leak out."""
    assert SECRET_MARKER not in response.text
    assert "Traceback" not in response.text
    assert "/home/" not in response.text
    assert ".py" not in response.text


# ---------------------------------------------------------------------------
# 404 — real app
# ---------------------------------------------------------------------------


class Test404Contract:
    def test_api_404_returns_fixed_json_body(self, real_client):
        resp = real_client.get(
            "/api/v1/definitely-not-a-route-xyzzy",
            headers={"Accept": "application/json"},
        )
        assert resp.status_code == 404
        assert resp.headers["content-type"].startswith("application/json")
        assert resp.json() == {"error": "Not found"}

    def test_browser_404_returns_html_matching_flask(self, real_client):
        # This assertion previously pinned a bare "Not found" text/html
        # body, itself a deliberate step up from the original JSON-for-
        # everyone behavior. PR #5424 goes one step further: instead of
        # unstyled "Not found", browser navigations now get a branded,
        # STANDALONE `pages/error.html` page (a way back to the app) --
        # it deliberately does NOT extend base.html, so it carries no
        # sidebar/route map and no {{ version }} for an unauthenticated
        # caller to read off a mistyped URL — the plain-text body was
        # itself only a fallback for when rendering that page fails (see
        # fastapi_app.py::_render_branded_error_page). Serving
        # `{"error": "Not found"}` — or bare "Not found" — to a top-level
        # browser navigation is what a user sees after a typo or a stale
        # bookmark; this asserts on the stable `data-error-page` /
        # `data-status-code` markers from error.html rather than prose,
        # matching how PR #5424's own test suite pinned it.
        resp = real_client.get(
            "/definitely-not-a-page-xyzzy", headers={"Accept": "text/html"}
        )
        assert resp.status_code == 404
        assert resp.headers["content-type"].startswith("text/html")
        assert "data-error-page" in resp.text
        assert 'data-status-code="404"' in resp.text

    def test_browser_404_body_does_not_reflect_request_path(self, real_client):
        # The HTML branch must stay a fixed constant. A reflected path in an
        # HTML response body is a live XSS channel, not merely a leak as it
        # would be in JSON. Check for the request-path fragment itself
        # rather than the bare words "script"/"alert" -- the branded,
        # standalone pages/error.html page (PR #5424) legitimately contains
        # "<script" (its own Vite/HMR bootstrap tags), so a bare-word check
        # would be a false positive independent of any real reflection.
        resp = real_client.get(
            "/not-a-page-<script>alert(1)</script>",
            headers={"Accept": "text/html"},
        )
        assert resp.status_code == 404
        assert "not-a-page" not in resp.text
        assert "<script>alert(1)</script>" not in resp.text

    def test_404_body_does_not_reflect_request_path(self, real_client):
        # Reflected-path 404 pages are an XSS/leak channel; body is fixed.
        resp = real_client.get("/api/xyzzy-<script>-payload")
        assert resp.status_code == 404
        assert "xyzzy" not in resp.text
        assert "script" not in resp.text


# ---------------------------------------------------------------------------
# 405 — real app
# ---------------------------------------------------------------------------


@pytest.mark.parametrize("status_code", [404, 413])
def test_branded_error_pages_omit_app_version(
    real_client, monkeypatch, status_code
):
    """Shared template context must not leak through rendered HTML comments."""
    version_module = importlib.import_module("local_deep_research.__version__")
    private_version = "private-build-marker-for-error-page"
    monkeypatch.setattr(version_module, "__version__", private_version)
    headers = {"Accept": "text/html"}
    if status_code == 413:
        # Only a declared size: no oversized body is allocated or sent.
        headers["Content-Length"] = str(1 << 40)

    response = real_client.get(
        "/missing-branded-version-probe", headers=headers
    )

    assert response.status_code == status_code
    assert response.headers["content-type"].startswith("text/html")
    assert "data-error-page" in response.text
    assert f'data-status-code="{status_code}"' in response.text
    assert private_version not in response.text


class Test405Contract:
    def test_405_json_detail_and_allow_header(self, real_client):
        # GET on a POST-only route; GET is CSRF-safe so the request
        # reaches routing. The Allow header is REQUIRED on 405 — it
        # survives only because Starlette's routing-raised HTTPException
        # falls through to FastAPI's default handler (the custom
        # handle_http_exception would drop exc.headers).
        resp = real_client.get(
            "/auth/logout", headers={"Accept": "application/json"}
        )
        assert resp.status_code == 405
        assert resp.json() == {"detail": "Method Not Allowed"}
        assert "POST" in resp.headers.get("allow", "")

    def test_405_browser_accept_same_shape(self, real_client):
        resp = real_client.get("/auth/logout", headers={"Accept": "text/html"})
        assert resp.status_code == 405
        assert resp.json() == {"detail": "Method Not Allowed"}


# ---------------------------------------------------------------------------
# 401 routing: browser redirect vs API JSON — real app
# ---------------------------------------------------------------------------


class Test401Contract:
    def test_browser_401_redirects_to_login_with_next(self, real_client):
        resp = real_client.get(
            "/settings/",
            headers={"Accept": "text/html"},
            follow_redirects=False,
        )
        assert resp.status_code == 302
        assert resp.headers["location"] == "/auth/login?next=/settings/"

    def test_json_accept_401_gets_json_not_redirect(self, real_client):
        resp = real_client.get(
            "/settings/",
            headers={"Accept": "application/json"},
            follow_redirects=False,
        )
        assert resp.status_code == 401
        assert resp.json() == {"detail": "Authentication required"}
        assert "location" not in resp.headers

    def test_api_path_401_is_json_even_with_browser_accept(self, real_client):
        # The /api/ path prefix alone must force the JSON branch: an API
        # client sending Accept: text/html must never get a 302 HTML flow.
        resp = real_client.get(
            "/api/history",
            headers={"Accept": "text/html"},
            follow_redirects=False,
        )
        assert resp.status_code == 401
        assert resp.json() == {"detail": "Authentication required"}
        assert "location" not in resp.headers


class Test401RedirectShape:
    """next= construction details, driven through the real handler on the
    mini app (routes crafted to hit the edge cases)."""

    def test_root_path_omits_next_param(self, handler_client):
        resp = handler_client.get(
            "/", headers={"Accept": "text/html"}, follow_redirects=False
        )
        assert resp.status_code == 302
        assert resp.headers["location"] == "/auth/login"

    def test_next_param_percent_encodes_special_chars(self, handler_client):
        # Path segment containing '&' (arrives percent-encoded, ASGI
        # decodes it). Without quote() the redirect URL would smuggle a
        # bare '&' into the query string, truncating next= at 'a'.
        resp = handler_client.get(
            "/account/a%26b",
            headers={"Accept": "text/html"},
            follow_redirects=False,
        )
        assert resp.status_code == 302
        assert resp.headers["location"] == "/auth/login?next=/account/a%26b"

    def test_api_accept_401_not_redirected(self, handler_client):
        resp = handler_client.get(
            "/account/x",
            headers={"Accept": "application/json"},
            follow_redirects=False,
        )
        assert resp.status_code == 401
        assert resp.json() == {"detail": "Authentication required"}


# ---------------------------------------------------------------------------
# 500 — scrubbed fixed-shape body
# ---------------------------------------------------------------------------


class Test500Contract:
    def test_unhandled_exception_returns_scrubbed_500(self, handler_client):
        resp = handler_client.get(
            "/api/boom", headers={"Accept": "application/json"}
        )
        assert resp.status_code == 500
        assert resp.json() == {"error": "Server error"}
        _assert_scrubbed(resp)

    def test_browser_path_500_same_fixed_body(self, handler_client):
        # Flask served plain text "Server error" to browsers; the port
        # serves the same JSON everywhere. Pin as implemented.
        resp = handler_client.get(
            "/browser-boom", headers={"Accept": "text/html"}
        )
        assert resp.status_code == 500
        assert resp.json() == {"error": "Server error"}
        _assert_scrubbed(resp)


# ---------------------------------------------------------------------------
# WebAPIException / AuthenticationRequiredError over HTTP
# ---------------------------------------------------------------------------


class TestWebAPIExceptionOverHTTP:
    def test_status_code_and_error_code_honored(self, handler_client):
        resp = handler_client.get("/api/webapi")
        assert resp.status_code == 418
        body = resp.json()
        assert body["status"] == "error"
        assert body["error_code"] == "TEAPOT"

    def test_message_is_credential_scrubbed(self, handler_client):
        resp = handler_client.get("/api/webapi")
        assert BEARER_TOKEN not in resp.text
        assert "REDACTED" in resp.json()["message"]

    def test_authentication_required_error_maps_to_401(self, handler_client):
        resp = handler_client.get("/api/authreq")
        assert resp.status_code == 401
        body = resp.json()
        assert body["error_code"] == "AUTHENTICATION_REQUIRED"
        assert body["details"]["username"] == "alice"


# ---------------------------------------------------------------------------
# PolicyDeniedError over HTTP
# ---------------------------------------------------------------------------


class TestPolicyDeniedOverHTTP:
    def test_maps_to_400_with_reason(self, handler_client):
        resp = handler_client.get("/api/policy")
        assert resp.status_code == 400
        body = resp.json()
        assert body["status"] == "error"
        assert "scope_mismatch" in body["message"]

    def test_denied_target_not_echoed(self, handler_client):
        # The target URL may embed user/query content — reason only.
        resp = handler_client.get("/api/policy")
        assert SECRET_MARKER not in resp.text
        assert "internal.example" not in resp.text


# ---------------------------------------------------------------------------
# Malformed JSON body → 400 (Flask request.get_json() parity)
# ---------------------------------------------------------------------------


class TestMalformedJSONBody:
    """Regression for the FastAPI-migration divergence: a bare
    ``await request.json()`` on a malformed body raised JSONDecodeError
    into the catch-all and returned 500 where Flask returned 400. Fixed
    by the ``json.JSONDecodeError`` handler in
    ``_register_exception_handlers``, which the ``handler_client`` tests
    drive. The real-endpoint test uses a route that parses its own body,
    so it pins that route's 400 envelope rather than the registered
    handler."""

    def test_malformed_json_returns_400_via_registered_handler(
        self, handler_client
    ):
        resp = handler_client.post(
            "/api/echo",
            content=b"{not valid json",
            headers={"Content-Type": "application/json"},
        )
        assert resp.status_code == 400
        assert resp.json() == {"error": "Invalid JSON body"}

    def test_empty_body_returns_400_not_500(self, handler_client):
        resp = handler_client.post(
            "/api/echo",
            content=b"",
            headers={"Content-Type": "application/json"},
        )
        assert resp.status_code == 400
        assert resp.json() == {"error": "Invalid JSON body"}

    def test_valid_json_still_reaches_endpoint(self, handler_client):
        # Guard against the handler over-matching: well-formed bodies
        # must be untouched.
        resp = handler_client.post("/api/echo", json={"a": 1})
        assert resp.status_code == 200
        assert resp.json() == {"ok": {"a": 1}}

    def test_real_endpoint_malformed_json_returns_400(
        self, authenticated_client
    ):
        # End-to-end on the real app: an authenticated endpoint that
        # uses the route's status-envelope JSON parser (api.py
        # api_add_resource). CSRF token header is attached by the
        # fixture; the parse failure happens before any DB work.
        resp = authenticated_client.post(
            "/research/api/resources/some-research-id",
            content=b"{definitely not json",
            headers={"Content-Type": "application/json"},
        )
        assert resp.status_code == 400
        assert resp.json() == {
            "status": "error",
            "message": "Request body must be valid JSON",
        }


# ---------------------------------------------------------------------------
# _is_api_request branch behavior
# ---------------------------------------------------------------------------


def _request(path: str, accept: str = None) -> StarletteRequest:
    headers = []
    if accept is not None:
        headers.append((b"accept", accept.encode()))
    return StarletteRequest(
        {
            "type": "http",
            "method": "GET",
            "path": path,
            "raw_path": path.encode(),
            "query_string": b"",
            "headers": headers,
            "server": ("testserver", 80),
            "scheme": "http",
        }
    )


class TestIsApiRequest:
    def test_api_segment_in_path_wins_regardless_of_accept(self):
        assert _is_api_request(_request("/api/v1/foo", accept="text/html"))
        assert _is_api_request(_request("/settings/api/bar"))

    def test_path_ending_in_api_counts(self):
        assert _is_api_request(_request("/settings/api"))

    def test_json_only_accept_is_api(self):
        assert _is_api_request(_request("/foo", accept="application/json"))

    def test_mixed_accept_with_html_is_browser(self):
        # A browser sends "application/json, text/html, ..." style values
        # from fetch(); presence of text/html keeps it on the HTML branch.
        assert not _is_api_request(
            _request("/foo", accept="application/json, text/html")
        )

    def test_plain_browser_request_is_not_api(self):
        assert not _is_api_request(_request("/foo", accept="text/html"))
        assert not _is_api_request(_request("/foo"))


class TestApiV1ErrorEnvelope:
    """/api/v1 is the documented programmatic API for external clients.

    main built its auth failures inline as ``jsonify({"error": ...})``
    (web/api.py). Routing them through HTTPException here would silently
    change the envelope to ``{"detail": ...}``, breaking every existing
    script that reads ``error`` -- a contract break invisible to the UI,
    because the frontend's api.js reads ``detail`` too.

    Both keys are emitted rather than swapped, so main's contract is restored
    without disturbing the ``{"detail": ...}`` shape the rest of this file
    deliberately pins.
    """

    def test_api_v1_401_carries_the_error_key_main_clients_expect(
        self, real_client
    ):
        resp = real_client.get(
            "/api/v1/", headers={"Accept": "application/json"}
        )

        assert resp.status_code == 401
        assert resp.json()["error"] == "Authentication required"

    def test_api_v1_401_still_carries_detail_for_the_frontend(
        self, real_client
    ):
        resp = real_client.get(
            "/api/v1/", headers={"Accept": "application/json"}
        )

        assert resp.json()["detail"] == "Authentication required"

    def test_non_api_v1_paths_keep_the_detail_only_shape(self, real_client):
        """The scoping is the point: widening this to every path would break
        the exact-dict assertions elsewhere in this file."""
        resp = real_client.get("/auth/logout", headers={"Accept": "text/html"})

        assert resp.status_code == 405
        assert resp.json() == {"detail": "Method Not Allowed"}


# ---------------------------------------------------------------------------
# A rekey operational fault left unhandled -> retryable 503
# ---------------------------------------------------------------------------


def _session_unavailable():
    # Imported when the route runs, so this module still collects against
    # a tree that predates the subclass (the fail-on-old run).
    from local_deep_research.database.session_context import (
        DatabaseSessionUnavailableError,
    )

    return DatabaseSessionUnavailableError("RekeySidecarIOError")


def _raw_sidecar_fault():
    import errno
    from pathlib import Path

    from local_deep_research.database.rekey_lock import (
        RekeySidecarIOError,
        RekeySidecarOperation,
    )

    return RekeySidecarIOError(
        Path(f"{SECRET_MARKER}.db"), RekeySidecarOperation.OPEN, errno.EMFILE
    )


@pytest.fixture(scope="module")
def database_fault_client():
    """Routes that leave a rekey operational fault unhandled.

    ``get_user_db_session`` raises ``DatabaseSessionUnavailableError`` when
    the database cannot be opened or claimed because of one (an
    fd-exhaustion spike on the rekey sidecar, say), and a direct
    ``db_manager`` call raises the ``RekeyOperationalError`` itself.
    """
    mini = FastAPI()
    _register_exception_handlers(mini)
    faults = {"session": _session_unavailable, "raw": _raw_sidecar_fault}

    @mini.get("/page/{kind}")
    def page(kind: str):
        raise faults[kind]()

    @mini.get("/api/v1/data/{kind}")
    def api_v1_data(kind: str):
        raise faults[kind]()

    return TestClient(mini, raise_server_exceptions=False)


class TestDatabaseUnavailableOverHTTP:
    """Not a verdict on the session, so not the catch-all's 500 either.

    Same retryable 503 and ``Retry-After`` that ``require_auth`` answers
    when its own probe meets the fault, through the HTTPException handler
    (so ``/api/v1`` keeps its ``error`` key). The fault's own text (it names
    the database file and the errno) never reaches the body.
    """

    DETAIL = "Your database is temporarily unavailable. Please try again in a moment."

    @pytest.mark.parametrize("kind", ["session", "raw"])
    def test_page_answers_retryable_503(self, database_fault_client, kind):
        resp = database_fault_client.get(
            f"/page/{kind}", headers={"Accept": "text/html"}
        )

        assert resp.status_code == 503, resp.text[:300]
        assert resp.headers["retry-after"] == "5"
        assert resp.json() == {"detail": self.DETAIL}
        _assert_scrubbed(resp)
        assert "errno" not in resp.text

    @pytest.mark.parametrize("kind", ["session", "raw"])
    def test_api_v1_keeps_its_error_envelope(self, database_fault_client, kind):
        resp = database_fault_client.get(
            f"/api/v1/data/{kind}", headers={"Accept": "application/json"}
        )

        assert resp.status_code == 503, resp.text[:300]
        assert resp.headers["retry-after"] == "5"
        assert resp.json() == {"error": self.DETAIL, "detail": self.DETAIL}