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.

52.2 KB
Raw Blame
"""Regression evidence for Socket.IO security-edge branches.

Socket.IO ownership itself is already well covered on this branch, and
materially stronger than ``main``: ``_subscriptions`` is keyed per
``(username, research_id)``, the ownership gate runs on BOTH subscribe and
unsubscribe, and both handlers re-validate the originating session. See
``tests/web/services/test_socketio_handshake_auth.py``,
``::test_socket_connect_session_gate.py``,
``::test_subscription_owner_scoping.py`` and
``::test_socketio_real_websocket_transport.py``. None of that is re-litigated
here.

What is covered here are three branches those tests did not reach at the
historical ADR-0010 snapshot:

COVERAGE AREA 1 -- the ownership gate's FAIL-CLOSED behaviour.
    ``_user_owns_research`` wraps the lookup in ``except Exception: return
    False`` (``socketio_asgi.py``). Every existing test drives the gate with a
    *working* database, so at the review snapshot they did not execute the
    branch that decides what happens when the lookup itself fails. This file
    now pins fail-closed behavior. It also pins both directions of the
    ``BenchmarkRun`` numeric-id fallback in ``_owns_research_sync``.

COVERAGE AREA 2 -- the WebSocket allowed-origins policy.
    ``grep -rl "cors_allowed_origins" tests/`` was empty. The source itself
    flags the trap: ``None`` means "derive a same-origin whitelist", while
    ``[]`` makes engine.io skip origin validation ENTIRELY (``handle_request``
    guards it with ``if self.cors_allowed_origins != []``). One character
    apart and opposite security postures. At the snapshot neither was pinned;
    this file now covers both. The pre-auth origin-dedup cap in
    ``_install_origin_rejection_logging`` is pinned here too: ``Origin`` is
    caller-controlled at a handshake that
    has not authenticated anybody yet, so an uncapped set is a memory-growth
    and log-amplification sink.

COVERAGE AREA 3 -- ``emit_socket_event`` room targeting.
    At the review snapshot, other tests patched the function at both call sites
    and did not assert that ``room=`` was honored. The cases below now pin both
    the targeted and roomless branches.

MECHANISM NOTES for anyone extending this file:

* Concurrency in this layer is coroutine interleaving on ONE event loop, not
  threads: ``AsyncServer`` runs ``connect``/``on_subscribe``/``on_unsubscribe``
  as coroutines. Races are provoked with ``asyncio.gather``, never with
  ``threading``.
* ``emit_socket_event`` schedules ``_async_emit`` through
  ``run_coroutine_threadsafe`` and returns BEFORE the coroutine runs. Its
  return value therefore reports whether the emit could be *scheduled*, never
  whether it was delivered -- so delivery is asserted by reading the packets
  back off the real Engine.IO transport, not from that boolean.
* Every "user B received nothing" assertion in here is preceded by the
  matching positive control: with no connected socket, "B got nothing" passes
  for free.
"""

import asyncio
import ast
import base64
import contextlib
import importlib.util
import inspect
import json
import os
import threading
from pathlib import Path
from unittest.mock import AsyncMock, Mock, patch

import itsdangerous
import pytest
import socketio as socketio_lib
from fastapi.testclient import TestClient
from loguru import logger
from sqlalchemy import create_engine, event
from sqlalchemy.exc import OperationalError
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool
from starlette.applications import Starlette
from starlette.routing import Mount

import local_deep_research
from local_deep_research.database.models import Base, ResearchHistory
from local_deep_research.database.models.benchmark import BenchmarkRun
from local_deep_research.web.services import socketio_asgi
from local_deep_research.web.services.socketio_asgi import (
    _install_origin_rejection_logging,
    _owns_research_sync,
    _user_owns_research,
    emit_socket_event,
    on_subscribe,
    on_unsubscribe,
)

SOCKETIO_ASGI_PATH = Path(socketio_asgi.__file__)
WS_ORIGINS_ENV = "LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS"


# ---------------------------------------------------------------------------
# Shared harness
# ---------------------------------------------------------------------------


@pytest.fixture(autouse=True)
def _isolated_socketio_state():
    """Snapshot/restore the module's global socket state.

    ``socketio_asgi`` keeps ``_sid_users`` / ``_sid_sessions`` /
    ``_subscriptions`` as module globals shared with every other socket test
    file, and ``_lock`` must be unbound to any closed loop at the start of
    each test.
    """
    saved_users = dict(socketio_asgi._sid_users)
    saved_sessions = dict(socketio_asgi._sid_sessions)
    saved_subs = {k: set(v) for k, v in socketio_asgi._subscriptions.items()}
    saved_lock = socketio_asgi._lock
    socketio_asgi._sid_users.clear()
    socketio_asgi._sid_sessions.clear()
    socketio_asgi._subscriptions.clear()
    socketio_asgi._lock = None
    yield
    socketio_asgi._sid_users.clear()
    socketio_asgi._sid_users.update(saved_users)
    socketio_asgi._sid_sessions.clear()
    socketio_asgi._sid_sessions.update(saved_sessions)
    socketio_asgi._subscriptions.clear()
    socketio_asgi._subscriptions.update(saved_subs)
    socketio_asgi._lock = saved_lock


@pytest.fixture
def warning_sink():
    """Capture loguru WARNING records emitted by the package under test.

    ``local_deep_research/__init__.py`` calls ``logger.disable(...)``, so the
    package's own records are dropped unless re-enabled -- the same dance
    ``tests/conftest.py::loguru_caplog`` performs. A dedicated sink is used
    instead of that fixture because these tests count records exactly.
    """
    records: list[str] = []
    logger.enable("local_deep_research")
    sink_id = logger.add(
        lambda message: records.append(message.record["message"]),
        level="WARNING",
        format="{message}",
    )
    try:
        yield records
    finally:
        logger.remove(sink_id)
        logger.disable("local_deep_research")


# ---------------------------------------------------------------------------
# COVERAGE AREA 1 -- fail-closed ownership and numeric IDs
# ---------------------------------------------------------------------------


class _OwnershipDB:
    """A real (in-memory SQLite) stand-in for one user's encrypted database.

    ``_owns_research_sync`` runs two genuinely different SQLAlchemy queries --
    ``ResearchHistory.filter_by(id=...)`` and, only for a numeric id,
    ``BenchmarkRun.id``. A ``MagicMock`` session answers both from the same
    stub and so cannot tell the two branches apart; a real session can, and
    also records which tables were actually touched.
    """

    def __init__(self):
        # StaticPool + check_same_thread=False: ``_user_owns_research``
        # offloads through ``run_db_sync`` to a worker thread, and SQLite's
        # default pool would hand that thread a fresh (empty) in-memory
        # database -- every ownership check would then answer False and the
        # deny assertions would all pass for the wrong reason.
        self.engine = create_engine(
            "sqlite://",
            poolclass=StaticPool,
            connect_args={"check_same_thread": False},
        )
        Base.metadata.create_all(
            self.engine,
            tables=[ResearchHistory.__table__, BenchmarkRun.__table__],
        )
        self.Session = sessionmaker(bind=self.engine)
        self.statements: list[str] = []
        self.usernames: list[str] = []

        @event.listens_for(self.engine, "before_cursor_execute")
        def _record(conn, cursor, statement, *args):  # noqa: ANN001
            self.statements.append(statement)

    def add_research(self, research_id: str) -> None:
        with self.Session() as s:
            s.add(
                ResearchHistory(
                    id=research_id,
                    query="q",
                    mode="quick",
                    status="completed",
                    created_at="2026-01-01T00:00:00+00:00",
                )
            )
            s.commit()

    def add_benchmark_run(self, run_id: int) -> None:
        with self.Session() as s:
            s.add(
                BenchmarkRun(
                    id=run_id,
                    run_name=f"run-{run_id}",
                    config_hash="h",
                    query_hash_list=[],
                    search_config={},
                    evaluation_config={},
                    datasets_config={},
                )
            )
            s.commit()

    def touched(self, table: str) -> bool:
        return any(table in stmt for stmt in self.statements)

    def patch(self, fail_for: dict[str, Exception] | None = None):
        """Patch ``get_user_db_session`` to hand out this database.

        ``fail_for`` maps a username to the exception its lookup must raise,
        which is how the fail-closed branch is driven: the gate has to answer
        "not owned" without the caller ever seeing the exception.
        """
        failures = fail_for or {}
        db = self
        # Only statements issued inside this window count; seeding the
        # fixture also touches both tables.
        self.statements.clear()
        self.usernames.clear()

        @contextlib.contextmanager
        def _fake(username=None, *_a, **_kw):
            db.usernames.append(username)
            if username in failures:
                raise failures[username]
            with db.Session() as session:
                yield session

        return patch(
            "local_deep_research.database.session_context.get_user_db_session",
            _fake,
        )


@pytest.fixture
def ownership_db():
    return _OwnershipDB()


def _db_error() -> Exception:
    """A realistic DB-layer failure: a locked/corrupt SQLCipher file."""
    return OperationalError("SELECT 1", {}, Exception("database is locked"))


class TestOwnershipGateFailsClosed:
    """A failed ownership lookup must answer "not owned", never "owned".

    ``_user_owns_research``'s ``except Exception: return False`` is the only
    thing standing between a database hiccup and one user subscribing to
    another user's live research stream. At the review snapshot, other socket
    tests drove only healthy lookups; this class now pins the failure branch.
    """

    def test_positive_control_a_healthy_lookup_still_grants_ownership(
        self, ownership_db
    ):
        """Vacuity guard for every deny assertion below: prove this harness
        CAN return True before trusting it when it returns False."""
        ownership_db.add_research("rid-owned")

        with ownership_db.patch():
            assert (
                asyncio.run(_user_owns_research("alice", "rid-owned")) is True
            )
        assert ownership_db.usernames == ["alice"], (
            "the gate did not query the caller's own database: "
            f"{ownership_db.usernames!r}"
        )

    @pytest.mark.parametrize(
        "failure",
        [
            pytest.param(_db_error(), id="query-fails"),
            pytest.param(
                RuntimeError("no authenticated user"), id="session-open-fails"
            ),
            pytest.param(MemoryError("out of memory"), id="non-Exception-ish"),
        ],
    )
    def test_a_failed_lookup_denies_ownership(self, ownership_db, failure):
        """The row EXISTS -- so a gate that leaked the row's existence past
        a broken lookup would answer True. It must answer False."""
        ownership_db.add_research("rid-owned")

        with ownership_db.patch(fail_for={"alice": failure}):
            result = asyncio.run(_user_owns_research("alice", "rid-owned"))

        assert result is False, (
            "the ownership gate did NOT fail closed: a failing database "
            f"lookup returned {result!r} instead of False, which would let a "
            "DB error authorise a subscription to someone else's research"
        )

    def test_a_failed_lookup_never_propagates_the_exception(self, ownership_db):
        """Fail-closed also means fail-quiet: an exception escaping the gate
        would tear down the socket handler rather than deny the request."""
        with ownership_db.patch(fail_for={"alice": _db_error()}):
            # Would raise here rather than returning if the guard were gone.
            assert (
                asyncio.run(_user_owns_research("alice", "anything")) is False
            )

    def test_subscribe_is_refused_when_the_ownership_lookup_fails(
        self, ownership_db
    ):
        """End-to-end fail-closed at the authorization boundary itself.

        ``mallory`` asks for a research id that really does exist in the
        database she is querying; the lookup blows up. She must get
        ``Not authorized`` and must NOT land in ``_subscriptions``.
        """
        rid = "rid-exists-but-lookup-broke"
        ownership_db.add_research(rid)
        emitted: list[tuple] = []

        async def _capture(event_name, data, room=None):
            emitted.append((room, event_name, data))

        async def _run():
            socketio_asgi.init_lock()
            socketio_asgi._sid_users["sid-mallory"] = "mallory"
            socketio_asgi._sid_sessions["sid-mallory"] = "sess-mallory"
            with (
                patch.object(socketio_asgi.sio, "emit", _capture),
                patch.object(
                    socketio_asgi,
                    "_socket_session_still_valid",
                    AsyncMock(return_value=("sess-mallory", True)),
                ),
                ownership_db.patch(fail_for={"mallory": _db_error()}),
            ):
                await on_subscribe("sid-mallory", {"research_id": rid})

        asyncio.run(_run())

        assert socketio_asgi._subscriptions == {}, (
            "a subscription was registered even though the ownership lookup "
            f"failed: {socketio_asgi._subscriptions!r}"
        )
        assert emitted, "the refused subscribe sent no subscribe_error at all"
        rooms = {room for room, _, _ in emitted}
        assert rooms == {"sid-mallory"}, (
            f"subscribe_error was not addressed only to the caller: {rooms!r}"
        )
        assert emitted[0][1] == "subscribe_error"
        assert emitted[0][2]["error"] == "Not authorized"

    def test_a_broken_lookup_for_one_user_cannot_deny_a_concurrent_owner(
        self, ownership_db
    ):
        """Interleaving check, coroutine-style.

        ``on_subscribe`` awaits the ownership gate, which offloads to a
        thread -- a real suspension point at which another socket's handler
        runs. Two subscribes are driven concurrently with ``asyncio.gather``:
        the owner's must still succeed, and the failing one must still be
        refused. A gate that cached its verdict anywhere shared (or that
        attributed one socket's outcome to another) fails here.
        """
        rid = "rid-shared"
        ownership_db.add_research(rid)
        emitted: list[tuple] = []

        async def _capture(event_name, data, room=None):
            emitted.append((room, event_name, data))

        async def _run():
            socketio_asgi.init_lock()
            socketio_asgi._sid_users.update(
                {"sid-alice": "alice", "sid-bob": "bob"}
            )
            socketio_asgi._sid_sessions.update(
                {"sid-alice": "s-alice", "sid-bob": "s-bob"}
            )
            with (
                patch.object(socketio_asgi.sio, "emit", _capture),
                patch.object(
                    socketio_asgi,
                    "_socket_session_still_valid",
                    AsyncMock(
                        side_effect=lambda sid, user: (f"s-{user}", True)
                    ),
                ),
                ownership_db.patch(fail_for={"bob": _db_error()}),
            ):
                await asyncio.gather(
                    on_subscribe("sid-alice", {"research_id": rid}),
                    on_subscribe("sid-bob", {"research_id": rid}),
                )

        asyncio.run(_run())

        # Positive control first: without it, "bob got nothing" is free.
        assert socketio_asgi._subscriptions.get(("alice", rid)) == {
            "sid-alice"
        }, (
            "the owner's concurrent subscribe did not register: "
            f"{socketio_asgi._subscriptions!r}"
        )
        assert ("bob", rid) not in socketio_asgi._subscriptions, (
            "a user whose ownership lookup failed was subscribed anyway"
        )
        assert [room for room, _, _ in emitted] == ["sid-bob"], (
            "the refusal was not addressed to exactly the failing socket: "
            f"{emitted!r}"
        )

    def test_unsubscribe_with_a_broken_lookup_does_not_mutate_or_raise(
        self, ownership_db
    ):
        """``on_unsubscribe`` shares the same gate.

        The caller is given a subscription of her OWN under the same id: a
        gate that treated the failed lookup as "owned" would fall through and
        prune it, so the surviving entry is what distinguishes "denied" from
        "allowed" here. (``subs.discard(sid)`` can only ever remove the
        caller's own sid, so a foreign entry alone proves nothing -- see
        ``test_socketio_real_websocket_transport.py`` for the same caveat.)
        The handler must also not let the exception escape: that would
        surface as a socket error frame instead of a quiet denial.
        """
        rid = "rid-unsub"
        socketio_asgi._subscriptions[("victim", rid)] = {"victim-sid"}
        socketio_asgi._subscriptions[("mallory", rid)] = {"sid-mallory"}

        async def _run():
            socketio_asgi.init_lock()
            socketio_asgi._sid_users["sid-mallory"] = "mallory"
            socketio_asgi._sid_sessions["sid-mallory"] = "sess-mallory"
            with (
                # `on_unsubscribe` re-validates the originating session BEFORE
                # it reaches the ownership gate, and severs the socket if that
                # fails — the same order `on_subscribe` uses. Without this
                # patch the handler returns at the session check and never
                # consults the ownership gate at all, so the assertion below
                # would be measuring the wrong denial. The two `on_subscribe`
                # siblings above patch it for exactly this reason.
                patch.object(
                    socketio_asgi,
                    "_socket_session_still_valid",
                    AsyncMock(return_value=("sess-mallory", True)),
                ),
                ownership_db.patch(fail_for={"mallory": _db_error()}),
            ):
                await on_unsubscribe("sid-mallory", {"research_id": rid})

        asyncio.run(_run())

        assert ownership_db.usernames == ["mallory"], (
            "on_unsubscribe never consulted the ownership gate: "
            f"{ownership_db.usernames!r}"
        )
        assert socketio_asgi._subscriptions == {
            ("victim", rid): {"victim-sid"},
            ("mallory", rid): {"sid-mallory"},
        }, (
            "a failed ownership lookup was treated as authorisation and the "
            f"handler mutated the map anyway: {socketio_asgi._subscriptions!r}"
        )


class TestBenchmarkRunNumericIdBranch:
    """``_owns_research_sync``'s ``str(research_id).isdigit()`` fallback.

    The benchmark page subscribes with a numeric ``BenchmarkRun.id``, which
    has no matching ``ResearchHistory`` row. Both directions of that branch
    were unexercised: the positive case (dropping it silently kills benchmark
    live progress) and the negative case (the authz denial for a numeric id
    the caller does not own).
    """

    def test_a_numeric_id_matching_a_benchmark_run_is_owned(self, ownership_db):
        ownership_db.add_benchmark_run(1)

        with ownership_db.patch():
            assert _owns_research_sync("alice", "1") is True

        assert ownership_db.touched("research_history"), (
            "the ResearchHistory lookup was skipped -- the benchmark branch "
            "is a FALLBACK and must not shadow the primary check"
        )
        assert ownership_db.touched("benchmark_runs"), (
            "the BenchmarkRun fallback never queried benchmark_runs"
        )

    def test_a_numeric_id_with_no_benchmark_run_is_not_owned(
        self, ownership_db
    ):
        """The authz negative case: a numeric id nobody owns must be denied,
        not waved through because it merely looks like a benchmark id."""
        ownership_db.add_benchmark_run(1)

        with ownership_db.patch():
            assert _owns_research_sync("alice", "7") is False

        assert ownership_db.touched("benchmark_runs"), (
            "the negative case never reached the benchmark table, so it "
            "proves nothing about that branch"
        )

    def test_an_integer_research_id_takes_the_same_branch_as_its_string_form(
        self, ownership_db
    ):
        """``str(research_id).isdigit()`` -- not ``research_id.isdigit()``.
        The benchmark client can send the id as a JSON number."""
        ownership_db.add_benchmark_run(3)

        with ownership_db.patch():
            assert _owns_research_sync("alice", 3) is True

    def test_a_non_numeric_unknown_id_never_reaches_the_benchmark_table(
        self, ownership_db
    ):
        """The isdigit() guard is load-bearing: a UUID-shaped id that is not
        in ResearchHistory must be denied outright, not probed against
        another user-scoped autoincrementing table."""
        ownership_db.add_benchmark_run(1)

        with ownership_db.patch():
            assert _owns_research_sync("alice", "rid-not-a-number") is False

        assert ownership_db.touched("research_history")
        assert not ownership_db.touched("benchmark_runs"), (
            "a non-numeric research id was probed against benchmark_runs; "
            "the str(...).isdigit() guard is not doing its job"
        )

    def test_benchmark_ownership_is_asked_of_the_callers_own_database(
        self, ownership_db
    ):
        """The numeric branch is only safe because the query is scoped to the
        caller's own encrypted DB -- run 1 exists in EVERY user's database."""
        ownership_db.add_benchmark_run(1)

        with ownership_db.patch():
            asyncio.run(_user_owns_research("mallory", "1"))

        assert ownership_db.usernames == ["mallory"], (
            "the benchmark ownership query was not scoped to the caller: "
            f"{ownership_db.usernames!r}"
        )

    def test_a_numeric_id_subscribe_is_refused_when_the_run_is_not_owned(
        self, ownership_db
    ):
        """The branch, end to end at the socket boundary."""
        emitted: list[tuple] = []

        async def _capture(event_name, data, room=None):
            emitted.append((room, event_name, data))

        async def _drive(rid):
            socketio_asgi.init_lock()
            socketio_asgi._sid_users["sid-u"] = "alice"
            socketio_asgi._sid_sessions["sid-u"] = "s-alice"
            with (
                patch.object(socketio_asgi.sio, "emit", _capture),
                patch.object(
                    socketio_asgi,
                    "_socket_session_still_valid",
                    AsyncMock(return_value=("s-alice", True)),
                ),
                ownership_db.patch(),
            ):
                await on_subscribe("sid-u", {"research_id": rid})

        ownership_db.add_benchmark_run(1)

        # Positive control: the owned numeric id DOES subscribe.
        # ``_subscription_key`` normalizes a numeric id to ``int`` (see its
        # docstring) so subscribe-time ("1", from the socket payload) and
        # emit-time (1, from the database) land on the same key -- the
        # stored key is ("alice", 1), not ("alice", "1").
        asyncio.run(_drive("1"))
        assert socketio_asgi._subscriptions.get(("alice", 1)) == {"sid-u"}, (
            "an owned benchmark run could not be subscribed to -- benchmark "
            "live progress is broken"
        )
        assert emitted == []

        socketio_asgi._subscriptions.clear()
        asyncio.run(_drive("9999"))
        assert socketio_asgi._subscriptions == {}, (
            "a benchmark run the caller does not own was subscribed to"
        )
        assert [e[2]["error"] for e in emitted] == ["Not authorized"]


# ---------------------------------------------------------------------------
# COVERAGE AREA 2 -- WebSocket allowed-origins policy
# ---------------------------------------------------------------------------


def _load_socketio_asgi_fresh():
    """Execute ``socketio_asgi`` again as a SEPARATE module object.

    The origin policy is derived at import time, so re-deriving it requires
    re-executing the module. ``importlib.reload`` is not usable: it mutates
    the live module in place, replacing the ``sio`` the app's handlers are
    registered on and the ``socket_app`` object the FastAPI route table holds
    by identity. Loading under a distinct name leaves the real module and
    every other socket test untouched.
    """
    spec = importlib.util.spec_from_file_location(
        "local_deep_research.web.services._socketio_asgi_origin_probe",
        SOCKETIO_ASGI_PATH,
    )
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def _build_probe_client(cors_allowed_origins) -> TestClient:
    """A throwaway Socket.IO server mounted exactly like the real one."""
    server = socketio_lib.AsyncServer(
        async_mode="asgi",
        cors_allowed_origins=cors_allowed_origins,
        logger=False,
        engineio_logger=False,
    )
    app = Starlette(
        routes=[
            Mount(
                "/ws",
                socketio_lib.ASGIApp(server, socketio_path="/ws/socket.io"),
            )
        ]
    )
    return TestClient(app, raise_server_exceptions=False)


def _handshake(client: TestClient, origin: str | None):
    headers = {"Origin": origin} if origin is not None else {}
    return client.get("/ws/socket.io/?EIO=4&transport=polling", headers=headers)


class TestWebSocketOriginPolicyDerivation:
    """``LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS`` -> ``cors_allowed_origins``.

    Pinned against the REAL env var name (auto-derived by
    ``EnvSetting`` as ``"LDR_" + key.upper().replace(".", "_")``), so a rename
    on either side is caught, not just the parse.
    """

    @pytest.mark.parametrize(
        ("env_value", "expected"),
        [
            pytest.param(None, None, id="unset->same-origin-only"),
            pytest.param("", None, id="empty->same-origin-only"),
            pytest.param("*", "*", id="star->allow-all"),
            pytest.param(
                "https://app.example.com",
                ["https://app.example.com"],
                id="single-origin",
            ),
            pytest.param(
                "https://a.example.com, https://b.example.com",
                ["https://a.example.com", "https://b.example.com"],
                id="csv-is-stripped",
            ),
            pytest.param(
                "https://a.example.com,*",
                "*",
                id="star-within-a-list-is-allow-all",
            ),
        ],
    )
    def test_policy_derivation(self, monkeypatch, env_value, expected):
        if env_value is None:
            monkeypatch.delenv(WS_ORIGINS_ENV, raising=False)
        else:
            monkeypatch.setenv(WS_ORIGINS_ENV, env_value)

        module = _load_socketio_asgi_fresh()

        assert module._socketio_cors == expected
        assert module.sio.eio.cors_allowed_origins == expected, (
            "the derived policy did not reach the engine.io server"
        )

    def test_a_star_within_a_list_logs_allow_all_not_a_restricted_list(
        self, monkeypatch
    ):
        """``_resolve_socketio_cors`` collapses a `*`-containing list to
        the bare allow-all value, and the startup policy log must follow: it
        must not claim the policy is "restricted to [...]" when it is
        actually allow-all.

        The log is emitted by ``log_socketio_cors_policy()`` (called from
        the FastAPI lifespan), not at import: the import happens while the
        package logger is still disabled, so an import-time line is lost.
        """
        monkeypatch.setenv(WS_ORIGINS_ENV, "https://a.example.com,*")

        import_records: list[str] = []
        records: list[str] = []
        logger.enable("local_deep_research")
        sink_id = logger.add(
            lambda message: import_records.append(message.record["message"]),
            level="DEBUG",
        )
        try:
            module = _load_socketio_asgi_fresh()
        finally:
            logger.remove(sink_id)
        sink_id = logger.add(
            lambda message: records.append(message.record["message"]),
            level="DEBUG",
        )
        try:
            module.log_socketio_cors_policy()
        finally:
            logger.remove(sink_id)
            logger.disable("local_deep_research")

        assert module._socketio_cors == "*"
        assert not any("Socket.IO CORS" in r for r in import_records), (
            "the origin policy must not be logged at import time (package "
            f"logging is still disabled then): {import_records!r}"
        )
        assert not any("restricted to" in r for r in records), (
            f"log claimed a restricted allowlist for an allow-all policy: {records!r}"
        )
        assert any("all origins allowed" in r for r in records), (
            f"log did not report the allow-all policy: {records!r}"
        )

    @pytest.mark.parametrize(
        "env_value", [None, "", "*", "https://a.test", "https://a.test,", ","]
    )
    def test_no_env_value_can_ever_produce_the_validation_disabling_empty_list(
        self, monkeypatch, env_value
    ):
        """``[]`` is the one value that must be unreachable.

        ``None`` and ``[]`` differ by one character and read as the same
        "nothing configured" intent, but engine.io skips origin validation
        ENTIRELY for ``[]`` (see
        ``TestNoneVersusEmptyListAreNotInterchangeable``). No operator input
        may reach it -- in particular the empty-string case, which is the one
        an operator writes when they mean "no cross-origin access".
        """
        if env_value is None:
            monkeypatch.delenv(WS_ORIGINS_ENV, raising=False)
        else:
            monkeypatch.setenv(WS_ORIGINS_ENV, env_value)

        module = _load_socketio_asgi_fresh()

        assert module._socketio_cors != [], (
            f"{WS_ORIGINS_ENV}={env_value!r} derived the empty list, which "
            "turns engine.io's WebSocket origin validation OFF entirely"
        )
        assert module.sio.eio.cors_allowed_origins != []


class TestNoneVersusEmptyListAreNotInterchangeable:
    """Prove, against the installed engine.io, that ``None`` and ``[]`` are
    opposite security postures -- so the derivation test above is pinning a
    real distinction rather than a stylistic one.

    engine.io's ``AsyncServer.handle_request`` guards the whole origin check
    with ``if self.cors_allowed_origins != []``. If a future engine.io
    dropped or inverted that guard, the source comment in ``socketio_asgi.py``
    would become false and this test says so.
    """

    def test_none_rejects_a_foreign_origin_at_the_handshake(self):
        client = _build_probe_client(None)

        # Positive control: the same-origin handshake must succeed, otherwise
        # "foreign origin rejected" would just mean "everything is rejected".
        allowed = _handshake(client, "http://testserver")
        assert allowed.status_code == 200, allowed.text

        refused = _handshake(client, "http://evil.test")
        assert refused.status_code == 400, (
            "cors_allowed_origins=None accepted a cross-origin WebSocket "
            f"handshake: {refused.status_code} {refused.text!r}"
        )
        assert "not an accepted origin" in refused.text

    def test_empty_list_disables_origin_validation_entirely(self):
        """Documents the failure mode, so a future maintainer who "tidies"
        ``None`` into ``[]`` can see exactly what it costs."""
        client = _build_probe_client([])

        refused = _handshake(client, "http://evil.test")
        assert refused.status_code == 200, (
            "engine.io no longer treats [] as 'origin validation disabled'. "
            "The comment in socketio_asgi.py explaining why None (not []) is "
            "load-bearing is now stale and must be re-checked against "
            f"engine.io: {refused.status_code} {refused.text!r}"
        )

    def test_an_explicit_allowlist_still_rejects_everything_else(self):
        client = _build_probe_client(["https://app.example.com"])

        assert _handshake(client, "https://app.example.com").status_code == 200
        assert _handshake(client, "http://evil.test").status_code == 400


class TestLiveServerOriginPolicy:
    """What the shipped app actually passes, and what it actually does."""

    def test_the_live_server_received_the_derived_policy_object(self):
        assert (
            socketio_asgi.sio.eio.cors_allowed_origins
            is socketio_asgi._socketio_cors
        ), (
            "the AsyncServer was not constructed with the derived origin "
            "policy -- the whole derivation above would be dead code"
        )

    def test_the_live_server_never_has_origin_validation_disabled(self):
        assert socketio_asgi.sio.eio.cors_allowed_origins != [], (
            "the live Socket.IO server has cors_allowed_origins=[], which "
            "disables engine.io's WebSocket origin check for every handshake"
        )

    def test_the_shipped_default_is_same_origin_only(self):
        if os.environ.get(WS_ORIGINS_ENV):
            pytest.skip(
                f"{WS_ORIGINS_ENV} is set in this environment; the shipped "
                "default cannot be observed"
            )
        assert socketio_asgi._socketio_cors is None, (
            "with no origin env var set the policy must be None "
            "(same-origin only), not a list and not '*'"
        )

    def test_a_cross_origin_handshake_is_refused_by_the_real_mounted_app(
        self, app
    ):
        """The whole policy, through the real app's middleware stack and the
        real ``/ws`` mount -- not a throwaway server."""
        # Guarded on the ENV VAR, not on the derived value: skipping when
        # the derived value is not None would silently skip this -- the
        # strongest assertion in the file -- exactly when the derivation has
        # been broken to [].
        if os.environ.get(WS_ORIGINS_ENV):
            pytest.skip(f"{WS_ORIGINS_ENV} is set in this environment")

        client = TestClient(app, raise_server_exceptions=False)

        same_origin = _handshake(client, "http://testserver")
        assert same_origin.status_code == 200, (
            "the app refused its OWN origin -- every following assertion "
            f"would pass vacuously: {same_origin.status_code} "
            f"{same_origin.text!r}"
        )

        foreign = _handshake(client, "https://attacker.example")
        assert foreign.status_code == 400, (
            "the real app accepted a cross-origin WebSocket handshake "
            f"({foreign.status_code}); Cross-Site WebSocket Hijacking is "
            "only blocked by the session cookie's SameSite attribute now"
        )


class TestOriginRejectionLoggingHook:
    """``_install_origin_rejection_logging`` -- the pre-auth dedup cap.

    engine.io runs with ``logger=False``, so its own "not an accepted origin"
    message never surfaces and a misconfigured origin is a silently frozen
    progress UI. The hook re-emits it through loguru, deduped per origin and
    CAPPED: ``Origin`` is caller-controlled at a handshake that has not
    authenticated anybody, so an unbounded dedup set is a memory-growth and
    log-amplification vector.
    """

    @staticmethod
    def _stub_server():
        class _Eio:
            def __init__(self):
                self.calls: list[tuple[str, str]] = []

            def _log_error_once(self, message, message_key):
                self.calls.append((message, message_key))

        class _Sio:
            def __init__(self):
                self.eio = _Eio()

        return _Sio()

    def test_a_rejected_origin_is_re_emitted_as_a_warning(self, warning_sink):
        server = self._stub_server()
        assert _install_origin_rejection_logging(server) is True

        server.eio._log_error_once(
            "http://evil.test is not an accepted origin.", "bad-origin"
        )

        assert len(warning_sink) == 1, warning_sink
        assert "http://evil.test" in warning_sink[0]
        assert WS_ORIGINS_ENV in warning_sink[0], (
            "the warning does not name the env var that fixes it, which is "
            "the entire reason the hook exists"
        )

    def test_the_same_origin_warns_only_once(self, warning_sink):
        server = self._stub_server()
        _install_origin_rejection_logging(server)
        message = "http://repeat.test is not an accepted origin."

        for _ in range(5):
            server.eio._log_error_once(message, "bad-origin")

        assert len(warning_sink) == 1
        assert len(server.eio.calls) == 5, (
            "the wrapper swallowed calls instead of delegating; engine.io's "
            "own bookkeeping must be untouched"
        )

    def test_other_engineio_error_keys_are_not_re_emitted(self, warning_sink):
        server = self._stub_server()
        _install_origin_rejection_logging(server)

        server.eio._log_error_once(
            "The WebSocket transport is not available.", "no-websocket"
        )

        assert warning_sink == []
        assert len(server.eio.calls) == 1

    def test_the_dedup_set_is_capped_so_a_hostile_origin_flood_cannot_grow_it(
        self, warning_sink
    ):
        """The security property: 250 distinct attacker-chosen origins must
        produce a bounded number of warnings and a bounded tracking set.

        The handshake is PRE-AUTH, so anyone on the network can pick these
        strings. Without the cap this is unbounded memory growth plus
        unbounded log volume, both from an unauthenticated request.
        """
        server = self._stub_server()
        _install_origin_rejection_logging(server)

        for i in range(250):
            server.eio._log_error_once(
                f"http://flood-{i}.test is not an accepted origin.",
                "bad-origin",
            )

        assert len(warning_sink) == 100, (
            "the origin-dedup cap is not being enforced: 250 distinct "
            f"attacker-controlled origins produced {len(warning_sink)} "
            "warnings (and grew the tracking set by the same amount)"
        )
        assert len(server.eio.calls) == 250, (
            "the cap must throttle OUR logging only, never engine.io's own "
            "handling of the rejection"
        )

    def test_installation_is_a_best_effort_no_op_when_internals_change(self):
        """A future engine.io that renames these internals must not break
        startup -- the hook is diagnostics, not a security control."""

        class _NoEio:
            pass

        class _NoHook:
            eio = object()

        assert _install_origin_rejection_logging(_NoEio()) is False
        assert _install_origin_rejection_logging(_NoHook()) is False

    def test_the_live_server_has_the_rejection_hook_installed(
        self, warning_sink
    ):
        """Otherwise a misconfigured origin is undiagnosable in production."""
        eio = socketio_asgi.sio.eio
        hook = eio._log_error_once
        assert getattr(hook, "__self__", None) is None, (
            "socketio_asgi.sio.eio._log_error_once is still engine.io's own "
            "bound method -- the loguru rejection hook was never installed, "
            "so a rejected WebSocket origin is silent in production"
        )

        saved_keys = set(eio.log_message_keys)
        try:
            hook(
                "http://live-hook-probe.test is not an accepted origin.",
                "bad-origin",
            )
        finally:
            eio.log_message_keys.clear()
            eio.log_message_keys.update(saved_keys)

        assert any(
            "live-hook-probe.test" in message for message in warning_sink
        ), f"the live hook emitted no warning: {warning_sink!r}"


# ---------------------------------------------------------------------------
# COVERAGE AREA 3 -- emit_socket_event room targeting
# ---------------------------------------------------------------------------


def _make_session_cookie(session_data: dict, secret_key: str) -> str:
    """Mint a cookie the way Starlette's SessionMiddleware does, backed by a
    REAL server-side session (the handshake validates ``session_id``)."""
    from local_deep_research.web.auth.session_manager import session_manager

    session_data = dict(session_data)
    session_data["session_id"] = session_manager.create_session(
        session_data["username"]
    )
    payload = base64.b64encode(json.dumps(session_data).encode("utf-8"))
    return (
        itsdangerous.TimestampSigner(secret_key).sign(payload).decode("utf-8")
    )


def _connect_real_socket(
    client: TestClient, username: str, secret_key: str
) -> tuple[str, str]:
    """One real Engine.IO polling handshake. Returns (eio_sid, socketio_sid)."""
    client.cookies.set(
        "session",
        _make_session_cookie({"username": username}, secret_key),
    )
    r_open = client.get("/ws/socket.io/?EIO=4&transport=polling")
    assert r_open.status_code == 200, r_open.text
    eio_sid = json.loads(r_open.text[1:])["sid"]
    r_connect = client.post(
        f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_sid}",
        content="40",
        headers={"Content-Type": "text/plain"},
    )
    assert r_connect.status_code == 200
    ack = client.get(
        f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_sid}"
    ).text
    assert ack.startswith("40"), f"{username}'s handshake was refused: {ack!r}"
    return eio_sid, json.loads(ack[2:])["sid"]


def _poll(client: TestClient, eio_sid: str) -> str:
    response = client.get(
        f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_sid}"
    )
    assert response.status_code == 200
    return response.text


@pytest.fixture
def secret_key(app) -> str:
    """The real app SECRET_KEY. Depends on ``app`` so ``fastapi_app`` is
    imported only after LDR_DATA_DIR points at an isolated temp dir."""
    from local_deep_research.web.fastapi_app import SECRET_KEY

    return SECRET_KEY


@pytest.fixture
def emit_loop():
    """A real running loop on a background thread, installed as the module's
    captured main loop -- exactly how a research worker thread reaches
    ``emit_socket_event``."""
    loop = asyncio.new_event_loop()
    thread = threading.Thread(target=loop.run_forever, daemon=True)
    thread.start()
    with patch.object(socketio_asgi, "_get_main_loop", return_value=loop):
        yield loop
    loop.call_soon_threadsafe(loop.stop)
    thread.join(timeout=5)
    loop.close()


def _drain(loop: asyncio.AbstractEventLoop) -> None:
    """Block until everything already scheduled on ``loop`` has run.

    ``emit_socket_event`` returns as soon as the coroutine is *scheduled*, so
    the emit has not happened yet when it returns. This is the deterministic
    barrier, not a sleep.
    """
    asyncio.run_coroutine_threadsafe(asyncio.sleep(0), loop).result(timeout=5)


class TestAsyncEmitRoomBranch:
    """Regression contract for ``_async_emit`` room forwarding."""

    def test_a_room_is_forwarded_to_sio_emit(self):
        mock_sio = Mock()
        mock_sio.emit = AsyncMock()

        with patch.object(socketio_asgi, "sio", mock_sio):
            asyncio.run(
                socketio_asgi._async_emit("progress", {"p": 1}, "room-42")
            )

        mock_sio.emit.assert_awaited_once_with(
            "progress", {"p": 1}, room="room-42"
        )

    def test_no_room_means_a_broadcast_to_every_connected_socket(self):
        """Pinned as the DOCUMENTED behaviour of the roomless branch, so the
        room-targeting tests below are testing a real distinction."""
        mock_sio = Mock()
        mock_sio.emit = AsyncMock()

        with patch.object(socketio_asgi, "sio", mock_sio):
            asyncio.run(socketio_asgi._async_emit("progress", {"p": 1}))

        mock_sio.emit.assert_awaited_once_with("progress", {"p": 1})
        assert "room" not in mock_sio.emit.await_args.kwargs

    @pytest.mark.parametrize("falsy_room", ["", None])
    def test_a_falsy_room_broadcasts(self, falsy_room):
        """``if room:`` -- not ``if room is not None:``. A call site that
        computed an empty room string gets a full broadcast, so pin it rather
        than let a future reader assume ``room=""`` is targeted."""
        mock_sio = Mock()
        mock_sio.emit = AsyncMock()

        with patch.object(socketio_asgi, "sio", mock_sio):
            asyncio.run(socketio_asgi._async_emit("progress", {}, falsy_room))

        assert "room" not in mock_sio.emit.await_args.kwargs


class TestEmitSocketEventRoomTargetingOverTheRealTransport:
    """``room=`` honoured, proven by reading packets off the real wire.

    Two independently authenticated users are connected through the real
    mounted ASGI app and the real (unmocked) ``AsyncServer``. Nothing about
    the emit path is stubbed except the captured main loop, which is what
    ``set_main_loop`` supplies in production.
    """

    def test_a_room_targeted_event_reaches_only_that_room(
        self, app, secret_key, emit_loop
    ):
        socketio_asgi.init_lock()
        dbm = Mock()
        dbm.is_user_connected.return_value = True

        with patch("local_deep_research.database.encrypted_db.db_manager", dbm):
            client_alice = TestClient(app, raise_server_exceptions=False)
            client_bob = TestClient(app, raise_server_exceptions=False)
            eio_alice, sid_alice = _connect_real_socket(
                client_alice, "alice", secret_key
            )
            eio_bob, _sid_bob = _connect_real_socket(
                client_bob, "bob", secret_key
            )
            assert set(socketio_asgi._sid_users.values()) == {"alice", "bob"}

            assert (
                emit_socket_event(
                    "benchmark_progress",
                    {"secret": "alice-only"},
                    room=sid_alice,
                )
                is True
            )
            # bob's own event doubles as a fence: if his poll returns it, the
            # earlier alice-only emit had already been dispatched by then.
            assert emit_socket_event("bob_marker", {"for": "bob"}) is True
            _drain(emit_loop)

            alice_packets = _poll(client_alice, eio_alice)
            bob_packets = _poll(client_bob, eio_bob)

        # Positive control FIRST: without it "bob got nothing" is free.
        assert "benchmark_progress" in alice_packets, (
            "the room-targeted event never reached its own room -- every "
            f"isolation assertion below would be vacuous: {alice_packets!r}"
        )
        assert '"secret":"alice-only"' in alice_packets.replace(" ", "")
        assert "bob_marker" in bob_packets, (
            f"bob's socket received nothing at all: {bob_packets!r}"
        )
        assert "benchmark_progress" not in bob_packets, (
            "CROSS-USER WS LEAK: an event emitted to alice's room reached "
            f"bob's socket. bob's poll body: {bob_packets!r}"
        )

    def test_the_roomless_branch_really_does_reach_every_connected_socket(
        self, app, secret_key, emit_loop
    ):
        """The other half of the branch, and the reason ``room=`` matters.

        This is not an endorsement: it pins that omitting ``room`` hands the
        payload to every connected client regardless of who owns it, which is
        exactly why the call-site test below requires the argument to be
        passed explicitly.
        """
        socketio_asgi.init_lock()
        dbm = Mock()
        dbm.is_user_connected.return_value = True

        with patch("local_deep_research.database.encrypted_db.db_manager", dbm):
            client_alice = TestClient(app, raise_server_exceptions=False)
            client_bob = TestClient(app, raise_server_exceptions=False)
            eio_alice, _ = _connect_real_socket(
                client_alice, "alice", secret_key
            )
            eio_bob, _ = _connect_real_socket(client_bob, "bob", secret_key)

            assert (
                emit_socket_event("roomless_event", {"seen_by": "everyone"})
                is True
            )
            _drain(emit_loop)

            alice_packets = _poll(client_alice, eio_alice)
            bob_packets = _poll(client_bob, eio_bob)

        assert "roomless_event" in alice_packets
        assert "roomless_event" in bob_packets, (
            "the roomless branch no longer broadcasts. If that is deliberate "
            "the source comment describing it as reaching every connected "
            f"socket is stale: {bob_packets!r}"
        )


class TestEmitSocketEventCallSites:
    """Where the roomless branch may and may not be used.

    ``emit_socket_event`` is patched out at both of its references under
    ``tests/``, so nothing has ever looked at how ``src/`` calls it. Every
    shipped call site must name ``room`` explicitly: the roomless broadcast
    must be a decision somebody wrote down, never the default a caller gets
    by forgetting an argument.
    """

    @staticmethod
    def _call_sites() -> list[tuple[str, int, bool]]:
        src_root = Path(local_deep_research.__file__).parent
        sites = []
        for path in src_root.rglob("*.py"):
            try:
                tree = ast.parse(path.read_text(encoding="utf-8"))
            except SyntaxError:  # pragma: no cover - defensive
                continue
            for node in ast.walk(tree):
                if not isinstance(node, ast.Call):
                    continue
                func = node.func
                name = (
                    func.attr
                    if isinstance(func, ast.Attribute)
                    else getattr(func, "id", None)
                )
                if name != "emit_socket_event":
                    continue
                names_room = (
                    any(kw.arg == "room" for kw in node.keywords)
                    or len(node.args) >= 3
                )
                sites.append(
                    (
                        str(path.relative_to(src_root)),
                        node.lineno,
                        names_room,
                    )
                )
        return sites

    def test_every_shipped_call_site_names_its_room_explicitly(self):
        sites = self._call_sites()

        assert sites, (
            "no emit_socket_event call site found in src/ -- this sweep has "
            "stopped matching anything and is passing vacuously"
        )
        roomless = [(f, line) for f, line, has_room in sites if not has_room]
        assert roomless == [], (
            "these call sites emit with no room, i.e. to EVERY connected "
            f"socket regardless of owner: {roomless}"
        )

    def test_the_benchmark_adapter_forwards_its_room_argument(self):
        """The one real call site, checked behaviourally rather than by AST:
        an earlier port turned this adapter into a no-op stub that silently
        dropped every benchmark WebSocket event."""
        from local_deep_research.benchmarks.web_api.benchmark_service import (
            SocketIOService,
        )

        with patch.object(
            socketio_asgi, "emit_socket_event", return_value=True
        ) as spy:
            result = SocketIOService().emit_to_room(
                "benchmark_progress", {"p": 1}, room="run-room"
            )

        assert result is True
        spy.assert_called_once_with(
            "benchmark_progress", {"p": 1}, room="run-room"
        )

    def test_the_wrapper_reports_scheduling_failure_not_delivery(self):
        """Contract note, pinned so nobody writes a delivery assertion on
        this return value: the emit runs on another loop AFTER the wrapper
        has returned, so only a failure to schedule is observable here."""
        with patch.object(socketio_asgi, "_get_main_loop", return_value=None):
            assert emit_socket_event("e", {}, room="r") is False

        stopped = asyncio.new_event_loop()
        try:
            with patch.object(
                socketio_asgi, "_get_main_loop", return_value=stopped
            ):
                assert emit_socket_event("e", {}, room="r") is False
        finally:
            stopped.close()

        source = inspect.getsource(socketio_asgi.emit_socket_event)
        assert "run_coroutine_threadsafe" in source