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.

test(security): pin untested security seams from the FastAPI migration (#3299) (#6084)

LearningCircuit62d655ac9f97
diff --git a/tests/security/test_auth_db_session_dependency_error_paths.py b/tests/security/test_auth_db_session_dependency_error_paths.py
new file mode 100644
index 0000000000..02fae219b1
--- /dev/null
+++ b/tests/security/test_auth_db_session_dependency_error_paths.py
@@ -0,0 +1,165 @@
+"""Error-path pins for ``web.dependencies.auth::get_db_session_dep``.
+
+This dependency is deliberately NOT wired to any route (the thread-affinity
+hazard on its ``with get_user_db_session(...)`` block is documented at
+length in its own docstring, and pinned against
+``fastapi.concurrency.contextmanager_in_threadpool`` in
+``tests/web/dependencies/test_dependency_contracts.py``). But "not wired
+today" is not "dead code": its single consumer
+(``get_settings_manager_dep``) is one ``Depends()`` away from any future
+route, and the error paths below are the ones that decide whether a broken
+credential state produces a clean re-login prompt or a stuck client.
+
+These paths are already pinned end-to-end at route level in
+``tests/web/dependencies/test_dependency_resolution_contracts.py``
+(real generator wired into FastAPI: open-time ``DatabaseSessionError``
+-> clear/401, ``None`` -> 500 without clear, handler-time
+``DatabaseSessionError`` -> forced logout, unrelated handler error ->
+500 with session retained). What this file adds is the same real
+generator driven DIRECTLY — no app/route/TestClient wiring — with the
+throw point under explicit fixture control:
+
+1. ``DatabaseSessionError`` -> ``request.session.clear()`` -> 401
+ "Session expired". This is the revocation behavior that makes a
+ dead password store self-heal: without the clear, the browser keeps
+ presenting a cookie that can never work again and every request 401s
+ forever (the exact "stale session" failure mode
+ ``clear_session_if_unrecoverable`` exists to prevent on the auth path).
+2. A ``None`` session from the context manager -> 500, not a silent
+ success that hands the handler ``None`` where a ``Session`` was typed.
+3. ONLY ``DatabaseSessionError`` maps to 401. A generic exception must
+ propagate untouched — if the ``except`` ever widens to ``Exception``
+ (a favourite "robustness" refactor), bug signals would disappear into
+ 401s and login loops, so that widening must fail this pin.
+
+Both entry routes into the ``except`` are covered: the error raised while
+*opening* the session (``__enter__``), and the error thrown *back into the
+yield* (handler-time), since FastAPI delivers handler exceptions into
+generator dependencies exactly that way.
+"""
+
+import pytest
+from fastapi import HTTPException
+from starlette.requests import Request
+
+from local_deep_research.database.session_context import DatabaseSessionError
+from local_deep_research.web.dependencies.auth import get_db_session_dep
+
+
+class _FakeSessionContext:
+ """Stand-in for the ``get_user_db_session(...)`` context manager.
+
+ ``enter_exc`` raises from ``__enter__`` (credential resolution /
+ open failure); ``yield_exc`` is thrown into the generator at yield
+ time (handler-time failure). ``__exit__`` never swallows.
+ """
+
+ def __init__(self, session=None, enter_exc=None, yield_exc=None):
+ self._session = session
+ self._enter_exc = enter_exc
+ self._yield_exc = yield_exc
+ self.exited = False
+
+ def __enter__(self):
+ if self._enter_exc is not None:
+ raise self._enter_exc
+ return self._session
+
+ def __exit__(self, exc_type, exc, tb):
+ self.exited = True
+ return False
+
+
+def _request_with_session(session_dict):
+ scope = {
+ "type": "http",
+ "method": "GET",
+ "path": "/",
+ "headers": [],
+ "session": session_dict,
+ }
+ return Request(scope)
+
+
+def _patch_ctx(monkeypatch, ctx):
+ monkeypatch.setattr(
+ "local_deep_research.web.dependencies.auth.get_user_db_session",
+ lambda username, session_id=None: ctx,
+ )
+ return ctx
+
+
+class TestHappyPath:
+ def test_yields_the_resolved_session(self, monkeypatch):
+ sentinel = object()
+ _patch_ctx(monkeypatch, _FakeSessionContext(session=sentinel))
+ request = _request_with_session(
+ {"username": "alice", "session_id": "sid-1"}
+ )
+
+ gen = get_db_session_dep(request, "alice")
+ assert next(gen) is sentinel
+ gen.close()
+
+
+class TestDatabaseSessionErrorPaths:
+ def test_open_failure_clears_session_and_raises_401(self, monkeypatch):
+ _patch_ctx(
+ monkeypatch,
+ _FakeSessionContext(enter_exc=DatabaseSessionError("gone")),
+ )
+ session_dict = {"username": "alice", "session_id": "sid-1"}
+ request = _request_with_session(session_dict)
+
+ with pytest.raises(HTTPException) as excinfo:
+ next(get_db_session_dep(request, "alice"))
+
+ assert excinfo.value.status_code == 401
+ assert excinfo.value.detail == "Session expired — please log in again"
+ # The revocation half of the contract: the cookie payload is wiped
+ # so the client stops presenting a credential that can never
+ # resolve again.
+ assert session_dict == {}
+
+ def test_handler_time_failure_clears_session_and_raises_401(
+ self, monkeypatch
+ ):
+ # FastAPI delivers a handler exception into a yield-dependency via
+ # gen.throw(); a DatabaseSessionError taking that route must land
+ # in the same 401+clear bucket as an open-time failure.
+ ctx = _patch_ctx(monkeypatch, _FakeSessionContext(session=object()))
+ session_dict = {"username": "alice", "session_id": "sid-2"}
+ request = _request_with_session(session_dict)
+
+ gen = get_db_session_dep(request, "alice")
+ next(gen)
+ with pytest.raises(HTTPException) as excinfo:
+ gen.throw(DatabaseSessionError("revoked mid-request"))
+
+ assert excinfo.value.status_code == 401
+ assert session_dict == {}
+ assert ctx.exited
+
+
+class TestNonCredentialFailures:
+ def test_none_session_raises_500_not_silent_success(self, monkeypatch):
+ _patch_ctx(monkeypatch, _FakeSessionContext(session=None))
+ request = _request_with_session({"username": "alice"})
+
+ with pytest.raises(HTTPException) as excinfo:
+ next(get_db_session_dep(request, "alice"))
+
+ assert excinfo.value.status_code == 500
+
+ def test_generic_exception_is_not_masked_as_401(self, monkeypatch):
+ # Only DatabaseSessionError may map to the "log in again" bucket.
+ # A bare/broadened except here would convert real bugs (driver
+ # errors, programming errors) into login loops and hide them from
+ # logs and monitors alike.
+ _patch_ctx(
+ monkeypatch, _FakeSessionContext(enter_exc=RuntimeError("boom"))
+ )
+ request = _request_with_session({"username": "alice"})
+
+ with pytest.raises(RuntimeError, match="boom"):
+ next(get_db_session_dep(request, "alice"))
diff --git a/tests/security/test_csrf_token_match_helper.py b/tests/security/test_csrf_token_match_helper.py
new file mode 100644
index 0000000000..04f4f1a0bb
--- /dev/null
+++ b/tests/security/test_csrf_token_match_helper.py
@@ -0,0 +1,288 @@
+"""Direct pins for ``web.dependencies.csrf._tokens_match``.
+
+This is the single comparison primitive under every CSRF check in the
+FastAPI port: header tokens, urlencoded form-field tokens, both compared
+against the session token through this function. Its behavioral envelope
+was only ever pinned INDIRECTLY — through full-middleware 403 tests
+(``tests/web/test_csrf_middleware_edges.py`` covers non-ASCII operands
+arriving over header/form) — meaning a refactor of the helper itself had
+no direct net. The properties worth pinning at unit level:
+
+1. ASCII equality and inequality are decided by ``secrets.compare_digest``
+ — the timing-safe comparator, not ``==`` and not a hand-rolled loop.
+ A swap to either is invisible to result assertions (they agree with
+ the comparator on every operand pair), so the delegation itself is
+ pinned directly, in two shapes:
+ ``TestDelegatesToCompareDigest.test_operand_pairs_reach_the_comparator``
+ wraps the real comparator in a pass-through spy and requires the
+ helper's own two operands, in order, to reach it, over pairs that
+ differ at index 0, at the last index, and in length only. What
+ actually catches a reimplementation short-circuiting on the first
+ differing byte (the classic timing oracle) is the delegation
+ assertion itself (``calls == [(session_token, provided_token)]``,
+ which comes back ``[]`` for anything that never calls the comparator)
+ — that holds regardless of which pair is used; the pair variety
+ instead exercises that the helper's own operands, in that order,
+ reach the spy under each shape of mismatch; and
+ ``test_the_comparators_return_value_is_handed_back`` swaps in a
+ sentinel verdict, which pins that the comparator's answer is what the
+ helper returns rather than merely something it consulted.
+2. Non-string operands fail closed instead of raising:
+ ``compare_digest`` raises on non-ASCII strings and mismatched operand
+ types, and both operands here are untrusted runtime state (header
+ bytes latin-1-decoded, form values possibly containing U+FFFD, stale
+ or forged session payloads possibly non-string). A 500 from the CSRF
+ check would be a denial-of-service primitive on every mutating route.
+3. A wholly non-ASCII operand — 64 repetitions of Cyrillic 'а' (U+0430,
+ the visual lookalike for ASCII 'a'), not an ASCII token with one
+ character substituted in — fails CLOSED on the same ``isascii`` gate
+ as point 2. No comparator is fooled by anything here; nothing in
+ this helper compares glyph shapes. What the gate buys is the
+ fail-closed 403 rather than the ``TypeError``-turned-500 that point 2
+ already describes.
+
+One deliberate oddity is pinned as a fact, not endorsed: two EMPTY
+strings compare equal. That result is unreachable from ``CSRFMiddleware``,
+which never reaches ``_tokens_match`` with an empty operand on either
+side. Both guards are ordering properties of the middleware source, read
+at the lines cited, not something a status-code test can distinguish:
+
+* ``csrf.py:276`` — ``if not session_token:`` returns 403 before the
+ token is read off the request at all, so an absent OR empty session
+ token never reaches the comparison.
+* ``csrf.py:374`` — ``if not provided or not _tokens_match(session_token,
+ provided):`` short-circuits on the left operand, so an empty provided
+ token is a 403 without ``_tokens_match`` being called.
+
+``tests/security/test_csrf_protection.py`` covers the OUTCOME of the
+first guard from the request side, not this ordering:
+``test_post_request_without_session_token_rejected`` (:147) posts with no
+session at all and ``test_post_request_without_csrf_token_rejected``
+(:167) posts with a stamped session but no token; each asserts a bare
+403. Neither sends an EMPTY token, and neither can tell "403 before
+comparing" apart from "403 after comparing two empties and getting True,
+then rejecting for some other reason" — which is exactly why the
+helper-level fact is pinned here rather than inferred there. It is
+pinned so that any refactor making it REACHABLE (e.g. moving either
+presence check out of the middleware) trips a named test and forces the
+empties question to be answered consciously.
+"""
+
+import pytest
+
+from local_deep_research.web.dependencies import csrf as csrf_mod
+from local_deep_research.web.dependencies.csrf import _tokens_match
+
+
+ASCII_TOKEN = "a" * 64
+# Operand pairs that a first-differing-byte short circuit would rank
+# differently from a constant-time comparison. Position 0 and
+# length-only are the two shapes the rest of this file never produced.
+DIFFERS_AT_INDEX_0 = "b" + ASCII_TOKEN[1:]
+DIFFERS_AT_LAST_INDEX = ASCII_TOKEN[:-1] + "b"
+SHORTER_PREFIX = ASCII_TOKEN[:-1]
+
+
+class TestAsciiOperands:
+ def test_equal_ascii_tokens_match(self):
+ assert _tokens_match(ASCII_TOKEN, ASCII_TOKEN)
+
+ def test_single_character_difference_fails(self):
+ assert not _tokens_match(ASCII_TOKEN, DIFFERS_AT_LAST_INDEX)
+
+ def test_first_character_difference_fails(self):
+ # Differing at index 0 rather than the last index: the pair a
+ # prefix-comparing reimplementation rejects fastest.
+ assert not _tokens_match(ASCII_TOKEN, DIFFERS_AT_INDEX_0)
+
+ def test_different_lengths_fail(self):
+ assert not _tokens_match(ASCII_TOKEN, ASCII_TOKEN + "x")
+ assert not _tokens_match(ASCII_TOKEN, SHORTER_PREFIX)
+ assert not _tokens_match(SHORTER_PREFIX, ASCII_TOKEN)
+
+ def test_both_empty_strings_match_but_are_unreachable_from_middleware(
+ self,
+ ):
+ # Inert today: the middleware 403s on a falsy session token
+ # (csrf.py:276) and short-circuits on a falsy provided token
+ # (csrf.py:374, ``if not provided or not _tokens_match(...)``),
+ # so neither operand can be empty by the time this helper is
+ # called. Named test so a refactor that makes this reachable is a
+ # conscious decision.
+ #
+ # INVERTED PIN: this test FAILS if the code is hardened to reject
+ # empty operands (e.g. an explicit "both non-empty" precondition
+ # added to ``_tokens_match`` itself). That is deliberate — update
+ # this test then, it is not a regression.
+ assert _tokens_match("", "")
+
+
+class TestNonStringOperands:
+ def test_none_session_token_fails_closed(self):
+ assert not _tokens_match(None, ASCII_TOKEN)
+
+ def test_none_provided_token_fails_closed(self):
+ assert not _tokens_match(ASCII_TOKEN, None)
+
+ def test_bytes_operands_fail_closed(self):
+ # Header/form bytes that never got decoded must not raise from
+ # compare_digest's type check.
+ assert not _tokens_match(ASCII_TOKEN, ASCII_TOKEN.encode())
+ assert not _tokens_match(ASCII_TOKEN.encode(), ASCII_TOKEN)
+
+ def test_int_operands_fail_closed(self):
+ assert not _tokens_match(12345, ASCII_TOKEN)
+ assert not _tokens_match(ASCII_TOKEN, 12345)
+
+
+class TestNonAsciiOperands:
+ def test_non_ascii_session_token_fails_closed(self):
+ # e.g. a stale/forge-resistant payload corruption: any non-ASCII
+ # session-side string must not raise from compare_digest.
+ assert not _tokens_match("tökén-" + "a" * 58, ASCII_TOKEN)
+
+ def test_non_ascii_provided_token_fails_closed(self):
+ # Form values may contain U+FFFD from lossy decoding.
+ assert not _tokens_match(ASCII_TOKEN, "token\ufffd" + "a" * 58)
+
+ def test_cyrillic_homoglyph_substitution_fails_closed(self):
+ # 'а' here is U+0430, not ASCII 'a'. The isascii gate rejects the
+ # whole string regardless of how similar it looks.
+ lookalike = "а" * 64
+ assert not _tokens_match(ASCII_TOKEN, lookalike)
+
+ def test_matching_non_ascii_pair_still_fails_closed(self):
+ # Even a "successful" match on non-ASCII operands must not pass:
+ # the ASCII gate is a precondition, not a best-effort filter.
+ non_ascii = "é" * 64
+ assert not _tokens_match(non_ascii, non_ascii)
+
+
+class TestDelegatesToCompareDigest:
+ """The delegation pin: the comparator itself must decide.
+
+ Every result assertion in the classes above survives rewriting the
+ helper's last line as ``session_token == provided_token``, or as a
+ hand-rolled length-then-byte loop — all three agree on every operand
+ pair, so no black-box result can tell them apart. What distinguishes
+ them is WHO decides, so both tests here patch ``compare_digest`` on
+ the ``secrets`` module object the production module bound at import
+ time (the helper resolves ``secrets.compare_digest`` at call time).
+
+ ``test_operand_pairs_reach_the_comparator`` uses a pass-through spy —
+ the real comparator still answers, so the helper's verdict stays
+ honest — and asserts the spy saw exactly ``(session_token,
+ provided_token)``, over pairs differing at index 0, at the last
+ index, and in length only. A ``==`` rewrite or a byte loop never
+ consults the spy at all, so ``calls`` stays empty and the pin trips.
+
+ ``test_the_comparators_return_value_is_handed_back`` goes further: it
+ substitutes a sentinel object as the verdict and requires the helper
+ to return that exact object, which pins that the comparator's answer
+ IS the helper's answer rather than something the helper consulted and
+ then re-derived (``compare_digest(a, b); return a == b`` passes the
+ spy test and fails this one).
+
+ DISCLOSED NARROWNESS of the sentinel test, deliberate on both counts:
+
+ * it FAILS on ``return bool(secrets.compare_digest(...))``, because a
+ sentinel object is not the object ``bool()`` returns. That rewrite
+ is behaviourally equivalent today (``compare_digest`` already
+ returns ``bool``), so this is a strictness the pin buys on purpose:
+ wrapping the comparator's result is how a "just normalise it"
+ refactor starts, and the next step — normalising with something
+ that is not ``bool`` — would not be equivalent. Update this test
+ consciously if the wrapper is ever wanted; it is not a regression.
+ * it FAILS on ``hmac.compare_digest(...)``, which is the same
+ function object (``secrets`` imports it from ``hmac``) reached
+ through a different module attribute, so patching ``secrets`` does
+ not intercept it. Also deliberate: the spy in
+ ``tests/security/test_csrf_coverage.py``
+ (``test_constant_time_compare_is_on_the_enforcement_path``) patches
+ the same attribute, so keeping the helper on ``secrets`` is what
+ keeps that middleware-level pin observing anything at all.
+ """
+
+ OPERAND_PAIRS = [
+ pytest.param(ASCII_TOKEN, ASCII_TOKEN, True, id="identical"),
+ pytest.param(
+ ASCII_TOKEN, DIFFERS_AT_INDEX_0, False, id="differs-at-index-0"
+ ),
+ pytest.param(
+ ASCII_TOKEN, DIFFERS_AT_LAST_INDEX, False, id="differs-at-last"
+ ),
+ pytest.param(
+ ASCII_TOKEN, SHORTER_PREFIX, False, id="provided-is-a-prefix"
+ ),
+ pytest.param(
+ SHORTER_PREFIX, ASCII_TOKEN, False, id="session-is-a-prefix"
+ ),
+ ]
+
+ @pytest.mark.parametrize(
+ ("session_token", "provided_token", "expected"), OPERAND_PAIRS
+ )
+ def test_operand_pairs_reach_the_comparator(
+ self, session_token, provided_token, expected, monkeypatch
+ ):
+ calls = []
+ real = csrf_mod.secrets.compare_digest
+
+ def spy(a, b):
+ calls.append((a, b))
+ return real(a, b)
+
+ monkeypatch.setattr(csrf_mod.secrets, "compare_digest", spy)
+
+ result = _tokens_match(session_token, provided_token)
+
+ # `is` on purpose: the helper is annotated `-> bool`, and a
+ # truthy non-bool (e.g. returning the operand itself) would
+ # satisfy a bare assert while breaking any caller that
+ # serialises or identity-checks the verdict.
+ assert result is expected, (
+ f"expected {expected!r}, got {result!r} — the verdict must be "
+ "the comparator's own bool, not a truthy stand-in"
+ )
+ assert calls == [(session_token, provided_token)], (
+ "the decision must go through secrets.compare_digest with the "
+ "helper's operands in (session_token, provided_token) order — "
+ f"the spy saw {calls!r}; a plain '==' or a hand-rolled "
+ "byte-by-byte loop never consults the timing-safe comparator "
+ "and leaks the session token one position at a time"
+ )
+
+ @pytest.mark.parametrize(
+ ("session_token", "provided_token"),
+ [
+ pytest.param(ASCII_TOKEN, ASCII_TOKEN, id="equal-operands"),
+ pytest.param(
+ ASCII_TOKEN, DIFFERS_AT_INDEX_0, id="unequal-operands"
+ ),
+ ],
+ )
+ def test_the_comparators_return_value_is_handed_back(
+ self, session_token, provided_token, monkeypatch
+ ):
+ verdict = object()
+ calls = []
+
+ def fixed_verdict(a, b):
+ calls.append((a, b))
+ return verdict
+
+ monkeypatch.setattr(csrf_mod.secrets, "compare_digest", fixed_verdict)
+
+ # Sentinel verdict: no comparison operator can produce this
+ # object, in either direction (``==`` would answer True on the
+ # equal pair and False on the unequal one).
+ assert _tokens_match(session_token, provided_token) is verdict, (
+ "the helper must return the comparator's own result; see this "
+ "class's docstring for the two equivalent rewrites this pin "
+ "deliberately rejects"
+ )
+ assert calls == [(session_token, provided_token)], (
+ "the comparator must be called with the helper's operands in "
+ f"(session_token, provided_token) order — the sentinel saw "
+ f"{calls!r}"
+ )
diff --git a/tests/security/test_expired_session_socket_teardown_import_failure.py b/tests/security/test_expired_session_socket_teardown_import_failure.py
new file mode 100644
index 0000000000..779009df9c
--- /dev/null
+++ b/tests/security/test_expired_session_socket_teardown_import_failure.py
@@ -0,0 +1,119 @@
+"""Import-resolution failure in expired-session socket teardown.
+
+``SessionManager.cleanup_expired_sessions`` deletes expired sessions and
+then calls ``_disconnect_expired_sockets`` to sever the sockets still
+authorised by them — a socket is authenticated once at handshake and frozen
+afterwards, so without the teardown an idle-expired session's tab keeps
+receiving that user's events (including ``settings_changed``, which carries
+plaintext secrets). That per-session disconnect behavior, and its
+per-session exception isolation, are already pinned in
+``tests/web/auth/test_session_manager.py::TestExpiredSessionSocketTeardown``.
+
+The FIRST failure mode this function has — resolving the socket layer
+itself — is not new ground:
+``tests/web/auth/test_session_manager.py::test_socket_layer_import_failure_is_best_effort``
+(:511) already drives the same ``sys.modules[...] = None`` condition
+through ``cleanup_expired_sessions`` and asserts deletion plus the
+warning, and the same class pins the resolvable path's per-session
+dispatch and isolation. What this file adds is that failure driven at
+the narrowest seam: ``TestSocketLayerResolutionFailure`` calls the
+teardown static method DIRECTLY in both directions, unresolvable and
+resolvable, side by side — so an ``ImportError`` swallowed in the wrong
+place, or a lookup result quietly discarded, is caught without a
+SessionManager instance or an expiry clock in the way.
+
+The middle test here,
+``test_cleanup_still_deletes_sessions_when_socket_layer_unresolvable``,
+is deliberately NOT at that seam: it goes through
+``cleanup_expired_sessions``, which makes it a narrower restatement of
+the existing :511 test: same condition, same entry point, with the
+logger assertion dropped. It asserts ``session_id not in
+manager.sessions`` and ``manager.get_user_sessions("alice") == []``, but
+the second assertion adds nothing on its own: ``get_user_sessions``
+(``session_manager.py:219-233``) has no per-user index, it just
+linearly scans ``self.sessions``, so its emptiness for this user is
+already entailed by the first assertion. The real delta against the
+:511 test — which already asserts ``expired_sid not in
+manager.sessions`` at :529 — is the dropped logger assertion. It is
+kept as the end-to-end anchor for the two seam-level tests around it,
+not as new coverage of a new failure mode.
+
+The lazy import exists to break an import cycle and to tolerate the
+socket layer's absence in non-web contexts (CLI, narrow test
+environments). Its Flask ancestor raised ``ModuleNotFoundError`` into
+a bare ``except`` and silently disconnected nothing — the exact
+regression class the docstring on the function records. This file
+pins the ASGI successor against repeating it in either direction:
+
+1. An unresolvable socket layer must not break session cleanup — the
+ sessions are already deleted by the time the teardown runs, so a raise
+ here would abort ``cleanup_expired_sessions`` after the mutation but
+ before its callers' remaining work. Its two callers are
+ ``SessionManager.get_active_sessions_count``
+ (``session_manager.py:215``) and ``cleanup_idle_connections``
+ (``connection_cleanup.py:158``, an APScheduler job every ~300s that
+ goes on to close idle DB connections). ``validate_session`` does NOT
+ call it — it expires one session inline instead
+ (``session_manager.py:89-95``) — so this is not on the per-request auth
+ path; what a raise here breaks is the periodic connection reclaim and
+ the session count, forever, for one missing import.
+2. Nor may it silently return SUCCESS-shaped behavior forever: pinned
+ alongside (1) is that when the layer IS resolvable, the same call
+ reaches ``disconnect_session`` for every expired id (guarding against a
+ future "defensive" try/except that swallows the lookup result).
+"""
+
+import sys
+
+from local_deep_research.web.auth.session_manager import SessionManager
+
+_SOCKET_MODULE = "local_deep_research.web.services.socketio_asgi"
+
+
+class TestSocketLayerResolutionFailure:
+ def test_unresolvable_socket_layer_is_survived(self, monkeypatch):
+ # ``sys.modules[...] = None`` makes ``from ... import ...`` raise
+ # ImportError ("import halted; None in sys.modules"), which is the
+ # closest deterministic stand-in for "socket layer unresolvable"
+ # without uninstalling real modules.
+ monkeypatch.setitem(sys.modules, _SOCKET_MODULE, None)
+
+ # Must not raise — session cleanup depends on this surviving.
+ SessionManager._disconnect_expired_sockets(["sess-1", "sess-2"])
+
+ def test_cleanup_still_deletes_sessions_when_socket_layer_unresolvable(
+ self, monkeypatch
+ ):
+ monkeypatch.setitem(sys.modules, _SOCKET_MODULE, None)
+
+ manager = SessionManager()
+ session_id = manager.create_session("alice")
+ # Force expiry without waiting out the timeout: age the last_access
+ # past both the normal and remember-me windows.
+ manager.sessions[session_id]["last_access"] -= (
+ manager.remember_me_timeout * 2
+ )
+
+ manager.cleanup_expired_sessions()
+
+ # Observed WITHOUT calling validate_session: that method expires a
+ # stale session inline (session_manager.py:89-95), so asking it
+ # would delete the session itself and the assertion would pass
+ # even if cleanup_expired_sessions had done nothing at all. Read
+ # the store directly instead, so what is observed is the SUT's own
+ # deletion surviving the failed socket-layer import.
+ assert session_id not in manager.sessions
+ assert manager.get_user_sessions("alice") == []
+
+ def test_resolvable_layer_still_disconnects_every_session(
+ self, monkeypatch
+ ):
+ disconnected = []
+ monkeypatch.setattr(
+ f"{_SOCKET_MODULE}.disconnect_session",
+ lambda sid: disconnected.append(sid),
+ )
+
+ SessionManager._disconnect_expired_sockets(["sess-1", "sess-2"])
+
+ assert disconnected == ["sess-1", "sess-2"]
diff --git a/tests/security/test_fastapi_app_ip_classification_edges.py b/tests/security/test_fastapi_app_ip_classification_edges.py
new file mode 100644
index 0000000000..1262ffe689
--- /dev/null
+++ b/tests/security/test_fastapi_app_ip_classification_edges.py
@@ -0,0 +1,295 @@
+"""Edge classification of ``fastapi_app._is_private_ip`` — the warning-path copy.
+
+The repo carries three private-IP classifiers. The two that matter here
+differ in fallback behaviour — this is not a hardened/unhardened pair:
+
+- ``local_deep_research.security.network_utils.is_private_ip`` — it first
+ short-circuits ``return True`` (``network_utils.py:39``) on a small set
+ of known localhost spellings (``localhost``, ``127.0.0.1``, ``[::1]``,
+ ``0.0.0.0``) checked at ``:38``, BEFORE any bracket handling; only then does
+ it strip the brackets off a ``[...]``-wrapped literal (``:42``) and
+ hand everything else straight to ``ipaddress``'s own ``is_private`` /
+ ``is_loopback`` / ``is_link_local``, falling back to a ``.local``-suffix
+ check when the string does not parse as an IP at all. It does no
+ unwrapping of its own: IPv4-mapped, NAT64 (``64:ff9b::/96``) and 6to4
+ (``2002::/16``) forms get whatever the running CPython's ``ipaddress``
+ module says about the address as presented — and for the two tunnel
+ prefixes, which ``ipaddress`` answers from its network table rather
+ than from the embedded IPv4, that answer is not always right. A
+ NAT64-wrapped RFC1918/link-local address (e.g. ``64:ff9b::c0a8:1``, or
+ the metadata-address case) is classified public, while every 6to4
+ address is classified private regardless of what it wraps, because
+ ``2002::/16`` is an entry in Python's private-networks table with no
+ matching exception. Both classes are covered by the deep classification
+ suite in ``tests/security/test_middleware_and_proxy_trust_fastapi.py``,
+ but not on the same footing:
+ ``test_6to4_wrapping_a_private_address_counts_as_private`` (:752) is
+ explicitly labelled CURRENT BEHAVIOUR, not desired behaviour, while
+ ``test_nat64_wrapped_addresses_are_not_private`` (:678) is framed as
+ load-bearing — its docstring says ``security/egress/policy.py`` relies
+ on this classification (plus its own ``_is_nat64_wrapped_metadata``
+ check) so a NAT64-wrapped cloud metadata address cannot pose as a local
+ host. That test asserts ``64:ff9b::8.8.8.8`` and
+ ``64:ff9b::169.254.169.254`` (the metadata address); the RFC1918
+ example above, ``64:ff9b::c0a8:1``, is not itself asserted there — the
+ public class is pinned via a link-local metadata address instead. For
+ IPv4-mapped inputs — the one of these three shapes whose answer CPython
+ changed inside the supported version range — this function is exactly as
+ version-dependent as the copy below; see the CGNAT ``xfail`` keyed to
+ this same function in ``tests/security/test_guard_internals.py``.
+- ``web.fastapi_app._is_private_ip`` — a local copy that does the same kind
+ of non-unwrapping delegation, but with different edges: no bracket
+ stripping, no localhost-string shortcut, and "non-parseable (including
+ empty string) counts as private" so TestClient peers behave like
+ loopback — where the module above instead falls back to a
+ ``.local``-suffix check and would *not* treat an empty string as
+ private. It also omits the other copy's ``is_link_local`` clause, but
+ that difference is textual only: on every CPython this project supports
+ (``requires-python = ">=3.12,<3.15"``) ``169.254.0.0/16`` and
+ ``fe80::/10`` are both entries in ``ipaddress``'s own private-networks
+ table, so ``is_private`` already covers them and no input can tell the
+ two clause lists apart. Before this file, no test imported *this* copy
+ at all (a comment in ``tests/web/test_forwarded_proto_warning.py`` was
+ its only reference).
+
+The third classifier, ``NotificationURLValidator._is_private_ip``
+(``security/notification_validator.py:460``), is a different animal: it
+resolves a hostname and screens the resolved addresses as an SSRF gate
+on the notification egress path, with its own knobs
+(``allow_private_ips``, ``allow_nat64``, ``block_link_local``) and its
+own suite. It is named here only so that "the two classifiers" above is
+not read as a repo-wide count.
+
+This copy is reach-restricted, which is why untested edges are a pinning
+concern rather than a fix-me bug: it feeds exactly the two operator-warning
+paths inside ``SecureCookieMiddleware`` —
+
+- ``_maybe_warn_insecure_public`` (one-shot "serving HTTP to a public peer")
+- ``_maybe_warn_untrusted_forwarded_proto`` (one-shot proxy-misconfig hint)
+
+— and never the ``Secure``-flag decision itself: that decision is
+``should_add_secure = not self.testing and is_https`` where ``is_https``
+is ``scope.get("scheme") == "https"`` (``fastapi_app.py:938-942``). It is
+gated on the testing flag as well as the scheme, and the peer address is
+not an input to it at all; it is pinned in
+``tests/web/test_secure_cookie_middleware.py``. A misclassification here
+therefore costs an operator a log line, not a cookie its ``Secure`` flag.
+
+What this file pins:
+
+1. The honest classification table (RFC 1918, loopback, IPv6 ULA/link-local,
+ public v4/v6, empty, non-parseable).
+2. The CPython dependence this copy shares with
+ ``network_utils.is_private_ip`` (neither unwraps IPv4-mapped forms
+ itself): for IPv4-mapped peers this copy inherits whatever
+ ``ipaddress`` says — CPython before 3.12.4 classified
+ ``::ffff:8.8.8.8`` as PRIVATE (the ``::ffff:0:0/96``-is-private era),
+ and gh-113171 (landed in 3.12.4 / 3.13) made ``is_private`` delegate
+ to the embedded IPv4 instead. Both interpreters are inside this
+ project's ``>=3.12,<3.15`` range, so the secure direction (mapped
+ public stays public) is pinned under a runtime-probed ``strict=True``
+ xfail — the same guard shape ``tests/security/test_guard_internals.py``
+ uses for the CGNAT half of that same CPython change — and a runtime
+ flip fails loudly instead of silently degrading the operator warnings
+ this feeds.
+3. NAT64 (``64:ff9b::/96``) peers never get mapped-address treatment
+ from CPython: a NAT64-wrapped public IPv4 classifies public.
+4. 6to4 (``2002::/16``) peers, in the INSECURE direction: a 6to4-wrapped
+ PUBLIC IPv4 classifies PRIVATE here, because ``2002::/16`` is a
+ private-networks entry and nothing unwraps the embedded IPv4. That is
+ the direction that costs an operator the "serving HTTP to a public
+ client" warning (``_maybe_warn_insecure_public`` warns only when the
+ peer is NOT private), so it is pinned as an explicitly inverted pin —
+ see the disclosure on the test itself.
+
+Deliberately NOT pinned: the ``or ip.is_loopback`` half of the classifier.
+It is unreachable as a *decision* — ``127.0.0.0/8`` and ``::1/128`` are
+literal entries in ``ipaddress``'s private-networks table on every
+supported CPython (and IPv4-mapped loopback delegates to the embedded
+IPv4, which is private), with no overlapping entry in the
+private-networks EXCEPTIONS table — so ``is_private`` is already true
+everywhere ``is_loopback`` is. Deleting the clause changes the verdict
+for no input, which means no assertion can catch its removal and any
+test claiming to do so would be pinning something else. The loopback rows
+below are therefore honest coverage of loopback *inputs*, not a pin on
+that clause.
+
+Same disclosure for the ``if not ip_str: return True`` guard on the
+empty string: ``ipaddress.ip_address("")`` raises ``ValueError``, which
+the ``except ValueError: return True`` arm already answers True, so
+deleting the guard changes no verdict either. ``_is_private_ip("")``
+below is honest coverage of the empty *input*, not a pin on the guard.
+
+If this copy ever grows a non-warning caller (rate-limit keying, proxy
+trust, access control), these pins are the tripwire that forces the
+IPv4-mapped question to be re-answered first.
+"""
+
+import ipaddress
+
+import pytest
+
+from local_deep_research.web.fastapi_app import _is_private_ip
+
+#: True on interpreters that still answer IPv4-mapped addresses from the
+#: IPv6 network table (``::ffff:0:0/96`` listed private outright) instead
+#: of delegating to the embedded IPv4 — i.e. CPython before gh-113171
+#: (3.12.4 / 3.13). Probed at import time rather than compared against
+#: ``sys.version_info`` so a backport or a vendored ``ipaddress`` is
+#: judged by what it actually does.
+_MAPPED_ADDRESSES_ARE_BLANKET_PRIVATE = ipaddress.ip_address(
+ "::ffff:8.8.8.8"
+).is_private
+
+
+class TestPrivateClassification:
+ def test_rfc1918_blocks_are_private(self):
+ assert _is_private_ip("10.0.0.1")
+ assert _is_private_ip("172.16.0.1")
+ assert _is_private_ip("192.168.1.1")
+
+ def test_loopback_is_private(self):
+ # Loopback INPUTS, not a pin on the ``or ip.is_loopback`` clause:
+ # these stay True with that clause deleted, because 127.0.0.0/8
+ # and ::1/128 are private-networks entries in their own right.
+ # See the "Deliberately NOT pinned" note in the module docstring.
+ assert _is_private_ip("127.0.0.1")
+ assert _is_private_ip("127.255.255.254")
+ assert _is_private_ip("::1")
+
+ def test_ipv6_unique_local_and_link_local_are_private(self):
+ assert _is_private_ip("fc00::1")
+ assert _is_private_ip("fd12:3456:789a::1")
+ assert _is_private_ip("fe80::1")
+
+ def test_public_ipv4_is_not_private(self):
+ assert not _is_private_ip("8.8.8.8")
+ assert not _is_private_ip("1.1.1.1")
+
+ def test_public_ipv6_is_not_private(self):
+ assert not _is_private_ip("2001:4860:4860::8888")
+
+ def test_empty_and_non_parseable_are_private(self):
+ # "" and "testclient" (the Starlette TestClient peer) classify
+ # private. The SUT docstring (fastapi_app.py:462-464) gives the
+ # reason as "Non-parseable strings are treated as private to
+ # avoid adding Secure flag in test/dev contexts" — quoted here
+ # exactly because that rationale is STALE: this classifier is not
+ # an input to the Secure-flag decision at all (that decision is
+ # `not self.testing and is_https`, fastapi_app.py:938-942, as the
+ # module docstring above records). What the fallback actually
+ # buys today is quiet operator-warning paths. Tracked in #6263.
+ #
+ # The "" row is coverage of the empty INPUT, not a pin on the
+ # `if not ip_str: return True` guard: ip_address("") raises
+ # ValueError, so the except arm returns True anyway and deleting
+ # the guard changes no verdict. Same disclosure shape as the
+ # `or ip.is_loopback` note in the module docstring.
+ assert _is_private_ip("")
+ assert _is_private_ip("testclient")
+ assert _is_private_ip("not-an-ip")
+
+
+class TestMappedAddressSemantics:
+ @pytest.mark.xfail(
+ _MAPPED_ADDRESSES_ARE_BLANKET_PRIVATE,
+ strict=True,
+ reason=(
+ "CPython before gh-113171 (landed in 3.12.4 / 3.13) listed "
+ "::ffff:0:0/96 among the IPv6 private networks outright, so "
+ "EVERY mapped address — including one wrapping a public IPv4 "
+ "— reported is_private=True; that interpreter is inside this "
+ "project's requires-python >=3.12,<3.15 range. The change "
+ "made is_private delegate to the embedded IPv4 instead. This "
+ "local copy does no unwrapping of its own and inherits "
+ "whichever semantics the running CPython has, so the "
+ "assertion below is xfailed rather than dropped on the older "
+ "interpreters — same guard shape as the CGNAT half of the "
+ "same CPython change in tests/security/test_guard_internals.py"
+ ),
+ )
+ def test_ipv4_mapped_public_peer_classifies_public(self):
+ # The SECURE direction, pinned: on an interpreter that derives
+ # the answer from the embedded IPv4, a mapped PUBLIC peer must
+ # classify public. strict=True on the xfail above means this also
+ # fails loudly if an interpreter reports blanket-private yet this
+ # assertion somehow passes, so neither direction can drift
+ # silently and degrade the operator warnings this feeds. (The
+ # other copy, security.network_utils.is_private_ip, does no
+ # unwrapping either and shares this exact CPython dependence for
+ # the mapped case — see the CGNAT xfail keyed to that function in
+ # tests/security/test_guard_internals.py.)
+ assert not _is_private_ip("::ffff:8.8.8.8")
+
+ def test_ipv4_mapped_loopback_classifies_private(self):
+ assert _is_private_ip("::ffff:127.0.0.1")
+
+ def test_ipv4_mapped_rfc1918_peer_classifies_private(self):
+ assert _is_private_ip("::ffff:192.168.1.10")
+
+ def test_nat64_embedded_public_ipv4_classifies_public(self):
+ # 64:ff9b::/96 (NAT64 well-known prefix) is NOT in CPython's IPv6
+ # private-networks table, and — unlike ::ffff:0:0/96 — CPython
+ # does not treat it as a wrapper either, so the embedded IPv4 is
+ # never consulted. A NAT64-wrapped PUBLIC peer therefore
+ # classifies public.
+ #
+ # This is NOT where the asymmetry with the mapped range lives —
+ # at least on CPython >= 3.12.4 (gh-113171): there, a mapped
+ # public peer also classifies public
+ # (test_ipv4_mapped_public_peer_classifies_public above, xfailed
+ # on the older interpreters where the mapped range is
+ # blanket-private regardless of what it wraps — see the
+ # strict=True xfail on that test). The asymmetry is on the
+ # PRIVATE-wrapped side —
+ # `::ffff:192.168.1.10` and `::ffff:127.0.0.1` classify private
+ # via the embedded IPv4, while `64:ff9b::c0a8:1` (RFC1918
+ # 192.168.0.1 wrapped for NAT64) classifies PUBLIC. That
+ # NAT64-wrapped-private case is pinned as current behaviour in
+ # tests/security/test_middleware_and_proxy_trust_fastapi.py
+ # (test_nat64_wrapped_addresses_are_not_private), against the
+ # other classifier; the module docstring above records it.
+ assert not _is_private_ip("64:ff9b::808:808")
+
+ def test_6to4_wrapping_a_public_ipv4_classifies_private(self):
+ # 2002:808:808::1 is 8.8.8.8 wrapped in the 6to4 prefix. Unlike
+ # both cases above this is the INSECURE direction: 2002::/16 is a
+ # plain entry in CPython's IPv6 private-networks table with no
+ # matching exception, and nothing here unwraps the embedded
+ # IPv4 — so a PUBLIC peer arriving over a 6to4 tunnel is
+ # classified PRIVATE. The cost is exactly one lost operator
+ # warning: _maybe_warn_insecure_public warns only when the peer
+ # is NOT private (fastapi_app.py:910), so a 6to4 public peer
+ # served over plain HTTP silently gets no "serving HTTP to a
+ # public client" line. (The other warning path runs the test the
+ # other way round — _maybe_warn_untrusted_forwarded_proto
+ # proceeds only for a private peer, fastapi_app.py:886 — so there
+ # the same misclassification merely widens who can plant that
+ # one-shot hint.)
+ #
+ # INVERTED PIN: this test FAILS if the classifier is ever
+ # hardened to unwrap 6to4 (or to drop 2002::/16 from whatever
+ # table it consults). That is deliberate — update this test then,
+ # it is not a regression. It exists so the hardening is a
+ # conscious edit rather than an unnoticed behaviour change.
+ assert _is_private_ip("2002:808:808::1")
+
+
+class TestConsumerBoundary:
+ @pytest.mark.parametrize(
+ ("peer", "expected"),
+ [
+ ("127.0.0.1", True),
+ ("8.8.8.8", False),
+ ("::ffff:8.8.8.8", False),
+ ],
+ )
+ def test_classification_is_pure_for_warning_consumers(self, peer, expected):
+ # The function is a pure classifier over a string: same input,
+ # same answer, no process state (the one-shot warning dedup lives
+ # on the middleware instance, not here). This repeated-call pin
+ # fails on any change that alters the return value between the
+ # two calls with the same input, whatever the source of that
+ # change turns out to be.
+ assert _is_private_ip(peer) == expected
+ assert _is_private_ip(peer) == expected
diff --git a/tests/security/test_multipart_upload_path_scoping.py b/tests/security/test_multipart_upload_path_scoping.py
new file mode 100644
index 0000000000..448b79ba8f
--- /dev/null
+++ b/tests/security/test_multipart_upload_path_scoping.py
@@ -0,0 +1,150 @@
+"""Direct path table for ``fastapi_app._is_multipart_upload_path``.
+
+``BodySizeLimitMiddleware`` grants an upload-sized body cap (~600 GB by
+default: 200 files x 3 GB) only when BOTH conditions hold
+(``fastapi_app.py:772-776``): the request carries a ``multipart/``
+Content-Type label AND the path returns True here. Neither half alone is
+enough: an honestly ``multipart/``-labelled body on a non-upload path
+falls through to the JSON cap, and so does an honestly JSON-labelled
+body on a real upload path. Those negative controls are already pinned
+in ``tests/web/test_body_size_limit.py`` (forged-label on a JSON route,
+traversal- and lookalike-shaped paths such as
+``/library/api/collections/42/upload/../../evil`` and
+``/library/api/collections/42/uploadx``, plus the label-matters case at
+``test_honest_json_on_an_upload_path_still_gets_the_json_cap``, :317).
+What a forged ``multipart/`` label DOES buy is the upload cap on a path
+this predicate accepts — the label costs nothing to fake, so on the label
+side the boundary is entirely this path table. Every path that does not
+get the upload cap falls to the JSON cap, and that cap is not uniform:
+``/notes/`` gets the larger 100 MB ``_LARGE_JSON_BODY_PREFIXES`` cap
+(``fastapi_app.py:648``, consumed at ``:785-789``) rather than the 16 MB
+cap every other path gets.
+
+What was never pinned directly is the predicate itself as an
+authorization table: which exact path shapes carry the large-cap grant.
+It is a security boundary expressed as string matching, so its edges
+deserve a unit-level net independent of the middleware's streaming
+behavior:
+
+- exact-match entry (``/api/upload/pdf``) and the anchored regex for
+ collection uploads (single ``[^/]+`` segment id);
+- near-misses that must NOT match: trailing slash, extra path segments,
+ a missing id segment and a present-but-empty one, prefix lookalikes,
+ junk BEFORE the upload prefix, case variants;
+- the empty path.
+
+One property of the anchors is worth stating rather than pinning: Python's
+``$`` also matches immediately before a trailing newline, so
+``"/library/api/collections/abc123/upload\n"`` satisfies this predicate.
+That is not a hole in the grant table, because Starlette's own routing
+shares it — ``compile_path`` builds ``"^" + ... + "$"`` and matches with
+``.match()`` (starlette 1.3.1, the version this project pins via
+``starlette>=1.3.1,<1.4`` — ``routing.py:124``, ``:159``, ``:242``) — so a
+newline-suffixed path that this predicate accepts is routed to the same
+upload endpoint the cap is meant for. Tightening one side without the
+other is what would create a mismatch, which is why the note is here
+rather than as an assertion.
+
+The two anchors and the single-segment property are the load-bearing
+ones: an unanchored or multi-segment-tolerant regex would silently widen
+the multi-hundred-MB event-loop-stall grant (see the stall measurements
+on ``_DEFAULT_MAX_JSON_BODY_SIZE`` in ``fastapi_app.py``) to whatever new
+routes happen to share the prefix.
+"""
+
+import pytest
+
+from local_deep_research.web.fastapi_app import _is_multipart_upload_path
+
+
+class TestLargeCapGrantPaths:
+ @pytest.mark.parametrize(
+ "path",
+ [
+ "/api/upload/pdf",
+ "/library/api/collections/abc123/upload",
+ "/library/api/collections/550e8400-e29b-41d4-a716-446655440000/upload",
+ ],
+ )
+ def test_exact_upload_routes_get_the_large_cap(self, path):
+ assert _is_multipart_upload_path(path)
+
+
+class TestNearMisses:
+ @pytest.mark.parametrize(
+ "path",
+ [
+ # The two rows the trailing ``$`` is load-bearing for.
+ # Measured against the ``$``-stripped regex over all 17
+ # negative rows in this list: exactly these two start
+ # matching, and the other 15 are rejected for reasons ``$``
+ # has nothing to do with (not the ``/api/upload/pdf``
+ # frozenset member, not the ``/library/api/collections/``
+ # literal prefix, ``[^/]+`` unable to span a ``/``, or case).
+ # So dropping ``$`` is invisible to every row but these.
+ "/library/api/collections/abc123/upload/",
+ "/library/api/collections/abc123/upload/extra",
+ # Extra segments after the exact-match entry (this one is a
+ # frozenset non-member, not a regex-anchor case).
+ "/api/upload/pdf/extra",
+ # Two segments where the id should be: [^/]+ must not span /.
+ "/library/api/collections/a/b/upload",
+ # Missing id segment entirely.
+ "/library/api/collections/upload",
+ # Present-but-EMPTY id segment. Distinct from the row above:
+ # this one still has both slashes, so it is what catches a
+ # ``[^/]+`` -> ``[^/]*`` slip, which the missing-segment row
+ # alone would not (verified: it matches under ``[^/]*``).
+ "/library/api/collections//upload",
+ # Prefix lookalikes.
+ "/api/upload/pdfx",
+ "/api/upload/pd",
+ "/xapi/upload/pdf",
+ # Junk BEFORE the upload prefix. ``.match()`` anchors at the
+ # start by itself, so a bare match->search swap changes
+ # nothing and these rows stay green; what they catch is the
+ # regex rewritten WITHOUT the leading ``^`` and applied with
+ # ``.search()``. These two rows are the ONLY ones here that
+ # such a rewrite would widen — measured by driving all 17
+ # negative rows against ``/library/api/collections/[^/]+/upload$``
+ # with ``.search()``.
+ "/evil/library/api/collections/abc123/upload",
+ "/redirect/library/api/collections/abc123/upload",
+ # Case variants — path matching is case-sensitive.
+ "/API/UPLOAD/PDF",
+ "/Library/API/Collections/abc/upload",
+ # Non-upload routes that merely share a prefix with the API.
+ "/api/upload",
+ "/api/news/upload/pdf",
+ # Degenerate input.
+ "",
+ "/",
+ ],
+ )
+ def test_lookalikes_do_not_get_the_large_cap(self, path):
+ assert not _is_multipart_upload_path(path)
+
+
+class TestGrantShapeProperties:
+ def test_id_segment_matches_raw_percent_encoding_without_slashes(self):
+ # [^/]+ is intentionally permissive within ONE segment (ids are
+ # caller-generated); the boundary pin is "no literal slashes", not
+ # a charset. Pinned so tightening to a uuid charset is deliberate.
+ # NOTE: pinned at the STRING level only. To this predicate %2F is
+ # three opaque characters inside one segment, so these literal
+ # fixture strings match. On the wire, Uvicorn percent-DECODES
+ # scope["path"] (undecoded bytes live in scope["raw_path"]), so a
+ # request's %2F arrives at the predicate as a LITERAL slash and
+ # splits the segment — these assertions pin the predicate's own
+ # text handling, not the ASGI decoding layer above it.
+ #
+ # INVERTED PIN: this test FAILS if the predicate is ever hardened
+ # to reject raw %2F within a segment (e.g. by rejecting or
+ # decoding percent-escapes itself). That is deliberate — update
+ # this test then, it is not a regression.
+ assert _is_multipart_upload_path(
+ "/library/api/collections/collection%20name/upload"
+ )
+ assert _is_multipart_upload_path(
+ "/library/api/collections/col%2Flection/upload"
+ )
diff --git a/tests/security/test_socketio_coroutine_scheduling_hygiene.py b/tests/security/test_socketio_coroutine_scheduling_hygiene.py
new file mode 100644
index 0000000000..c5446bb130
--- /dev/null
+++ b/tests/security/test_socketio_coroutine_scheduling_hygiene.py
@@ -0,0 +1,126 @@
+"""Coroutine-ownership hygiene in ``socketio_asgi._schedule_coroutine_threadsafe``.
+
+Every Socket.IO emit/disconnect from a background thread (research workers,
+the log queue, the scheduler) funnels through this wrapper. It exists for
+one narrow failure window: during shutdown, ``asyncio.run_coroutine_
+threadsafe`` can raise SYNCHRONOUSLY (``loop.call_soon_threadsafe`` on a
+closed loop) after the caller has already constructed the coroutine.
+
+Ownership has not transferred at that point — ``run_coroutine_threadsafe``
+only takes ownership once the callback is queued — so the coroutine is
+orphaned with nobody left to close it. An unclosed coroutine is at
+best a ``RuntimeWarning`` ("never awaited") plus a frame held until
+GC. Note the coroutines this wrapper receives have never STARTED, so
+any ``finally`` cleanup in their bodies was never entered — nothing
+of it can "leak"; what leaks is the warning and the frame.
+
+The scheduling-FAILURE routing around this wrapper (best-effort emits,
+no-raise) is pinned in ``tests/web/services/test_socketio_asgi_scheduling_
+failures.py`` by monkeypatching ``run_coroutine_threadsafe``, and that file
+already pins — six times, via its ``_assert_one_closed_coroutine`` helper —
+that a synchronously rejected coroutine is CLOSED. What that file does NOT
+pin, because it only exercises the emit/disconnect wrappers' best-effort,
+no-raise contract, is the ownership contract of this wrapper itself, at the
+seam where the exception is still live:
+
+1. the ORIGINAL exception type propagates unwrapped OUT of
+ ``_schedule_coroutine_threadsafe``, so a direct caller sees e.g.
+ ``RuntimeError`` rather than a generic wrapper error — the higher-level
+ wrappers in the other file catch and swallow this before it can
+ surface, so it is untested there; and
+2. on the SUCCESS path the coroutine is NOT closed — ownership has
+ transferred to the loop, and closing it here would surface as a
+ spurious shutdown error once the loop tries to drive it. The other
+ file never exercises the success path at all.
+"""
+
+import asyncio
+
+import pytest
+
+from local_deep_research.web.services.socketio_asgi import (
+ _schedule_coroutine_threadsafe,
+)
+
+
+def _pending_coroutine():
+ # A coroutine in the state the wrapper actually receives: created,
+ # never started. (``close()`` on a never-started coroutine does NOT
+ # run its body — the try/finally was never entered — so "finally
+ # ran" cannot be the observable. The leak being prevented is the
+ # "coroutine ... was never awaited" GC report; ``cr_frame is None``
+ # below is what closing actually looks like from the outside.)
+ async def coro():
+ await asyncio.sleep(3600)
+
+ return coro()
+
+
+class TestSynchronousRejection:
+ def test_rejected_coroutine_is_closed(self, monkeypatch):
+ scheduled = []
+
+ def rejecting(coro, loop):
+ scheduled.append((coro, loop))
+ raise RuntimeError("loop is closed")
+
+ monkeypatch.setattr(asyncio, "run_coroutine_threadsafe", rejecting)
+
+ coro = _pending_coroutine()
+ loop = object() # identity sentinel: no real loop is needed here
+ with pytest.raises(RuntimeError, match="loop is closed"):
+ _schedule_coroutine_threadsafe(coro, loop)
+
+ # The caller's loop must be the one handed to the scheduler —
+ # falling back to a global/ambient loop would schedule background
+ # emits onto the wrong loop, which is exactly the shutdown-race
+ # bug this wrapper sits in the middle of.
+ assert scheduled == [(coro, loop)]
+ # Closed == frame released; without the close, GC would later
+ # emit "coroutine ... was never awaited" — the exact warning
+ # this wrapper exists to prevent during shutdown races. (A
+ # gc.collect()-and-assert-no-warning block used to follow this
+ # assertion; it is documentation, not a guard — once cr_frame is
+ # None the coroutine is already closed, so that warning can never
+ # fire independently of the assertion above failing first.)
+ assert coro.cr_frame is None
+
+ def test_original_exception_type_propagates_unwrapped(self, monkeypatch):
+ class ShutdownRace(Exception):
+ """Distinctive type: proves no re-wrapping occurs."""
+
+ def rejecting(coro, loop):
+ raise ShutdownRace
+
+ monkeypatch.setattr(asyncio, "run_coroutine_threadsafe", rejecting)
+
+ with pytest.raises(ShutdownRace):
+ _schedule_coroutine_threadsafe(_pending_coroutine(), object())
+
+ def test_success_path_does_not_close_the_coroutine(self, monkeypatch):
+ # Ownership mirror-image: once scheduling is ACCEPTED, the
+ # coroutine belongs to the event loop. The wrapper must not
+ # close it (closing a coroutine the loop will drive would
+ # surface as spurious shutdown errors).
+ scheduled = []
+
+ def accepting(coro, loop):
+ scheduled.append((coro, loop))
+ return object() # caller-discarded future stand-in
+
+ monkeypatch.setattr(asyncio, "run_coroutine_threadsafe", accepting)
+
+ coro = _pending_coroutine()
+ loop = object()
+ _schedule_coroutine_threadsafe(coro, loop)
+
+ # Both operands, in order: the caller's coroutine AND the caller's
+ # loop reach the scheduler unchanged.
+ assert scheduled == [(coro, loop)]
+ assert coro.cr_frame is not None # still open: owned by the loop
+ # Clean up what the stand-in future never will. (A close() +
+ # gc.collect() + assert-no-warning block used to follow here; it
+ # is documentation, not a guard — it only pins CPython's own
+ # coroutine-close semantics on cleanup code this test wrote
+ # itself, not anything the wrapper under test does.)
+ coro.close()