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.

17.7 KB
Raw Blame
"""Socket.IO handshake authentication with REAL session-cookie crypto.

tests/web/services/test_socketio_connect_gate.py pins the connect
handler's branch logic but patches ``_decode_session_cookie`` out, so
nothing verifies the actual itsdangerous signature path — the piece that
makes the handshake an authentication boundary. These tests drive the
real decode/verify code (signed with the app's real SECRET_KEY):

- a validly-signed session cookie for a logged-in user is accepted and
  the username from the *cookie* becomes the socket's identity;
- missing / garbage / tampered-signature / wrong-key / expired cookies
  are all rejected at the handshake;
- a client-supplied Socket.IO ``auth`` payload can never forge or
  override the cookie-verified identity;
- the verified username (never anything in the client's subscribe
  payload) scopes the subscribe ownership check;
- the full Engine.IO polling handshake through the mounted ASGI app
  enforces the same gate.

Only true boundaries are mocked (encrypted DB manager, user DB session).
The cookie signing/verification, connect/subscribe handlers, and the
ASGI transport are all real.
"""

import asyncio
import base64
import json
import time
import uuid
from contextlib import contextmanager
from unittest.mock import AsyncMock, MagicMock, Mock, patch

import itsdangerous
import pytest
from fastapi.testclient import TestClient

from local_deep_research.security import get_security_default
from local_deep_research.web.fastapi_app import SECRET_KEY, app
from local_deep_research.web.services import socketio_asgi
from local_deep_research.web.services.socketio_asgi import (
    _decode_session_cookie,
    connect,
    disconnect,
    on_subscribe,
)


def _remember_me_max_age() -> int:
    """Mirror the max_age SessionMiddleware and the WS decode both use."""
    return (
        get_security_default("security.session_remember_me_days", 30)
        * 24
        * 3600
    )


def make_session_cookie(
    session_data: dict,
    key: str | bytes | None = None,
    timestamp: int | None = None,
    real_session: bool = True,
) -> str:
    """Build a session cookie value exactly like Starlette's
    SessionMiddleware: base64(json(session)) signed with an
    itsdangerous TimestampSigner over the app SECRET_KEY."""

    # The WebSocket handshake now validates session_id against the
    # server-side store (the revocation gate main's #5535 added and this
    # branch was missing). These helpers used to fabricate a session_id
    # like "s1", which no longer authenticates -- correctly. Mint a REAL
    # session for the username so these tests exercise the gate instead
    # of depending on its absence. Pass real_session=False to build a
    # deliberately-unauthenticated cookie.
    if real_session and session_data.get("username"):
        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"))
    signer = itsdangerous.TimestampSigner(
        key if key is not None else SECRET_KEY
    )
    if timestamp is not None:
        signer.get_timestamp = lambda: timestamp  # type: ignore[method-assign]
    return signer.sign(payload).decode("utf-8")


@pytest.fixture
def socket_state():
    """Snapshot and restore the module's identity/subscription state.

    ``_lock`` is reset to None; tests (or the async runner below)
    re-create it so it binds to the loop actually awaiting on it.
    """
    saved_users = dict(socketio_asgi._sid_users)
    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._subscriptions.clear()
    socketio_asgi._lock = None
    yield
    socketio_asgi._sid_users.clear()
    socketio_asgi._sid_users.update(saved_users)
    socketio_asgi._subscriptions.clear()
    socketio_asgi._subscriptions.update(saved_subs)
    socketio_asgi._lock = saved_lock


def run_handshake_coro(coro_fn):
    """asyncio.run a coroutine function with a fresh lock bound to its loop."""

    async def _wrapper():
        socketio_asgi._lock = None
        socketio_asgi.init_lock()
        return await coro_fn()

    return asyncio.run(_wrapper())


def _connected_db_manager() -> Mock:
    dbm = Mock()
    dbm.is_user_connected.return_value = True
    return dbm


class TestDecodeSessionCookieCrypto:
    """Real signature verification in _decode_session_cookie."""

    def test_validly_signed_cookie_decodes_session(self):
        # real_session=False: this asserts the payload round-trips, so the
        # helper must not substitute a freshly-minted session id.
        value = make_session_cookie(
            {"username": "alice", "session_id": "s1"}, real_session=False
        )
        decoded = _decode_session_cookie(f"session={value}")
        assert decoded == {"username": "alice", "session_id": "s1"}

    def test_fresh_but_old_cookie_within_max_age_still_valid(self):
        """A cookie almost (but not quite) at the remember-me horizon must
        still verify — the WS gate mirrors the HTTP session lifetime."""
        ts = int(time.time()) - (_remember_me_max_age() - 3600)
        value = make_session_cookie(
            {"username": "alice"}, timestamp=ts, real_session=False
        )
        decoded = _decode_session_cookie(f"session={value}")
        assert decoded == {"username": "alice"}

    def test_tampered_signature_is_rejected(self):
        value = make_session_cookie({"username": "alice"})
        suffix = "AAAA" if not value.endswith("AAAA") else "BBBB"
        tampered = value[:-4] + suffix
        assert tampered != value
        assert _decode_session_cookie(f"session={tampered}") is None

    def test_tampered_payload_with_original_signature_is_rejected(self):
        """Swapping the session payload (e.g. to claim another username)
        while keeping the signature must fail verification."""
        alice = make_session_cookie({"username": "alice"})
        mallory_payload = base64.b64encode(
            json.dumps({"username": "mallory"}).encode("utf-8")
        ).decode("utf-8")
        # itsdangerous format: <payload>.<timestamp>.<signature>
        _, timestamp, signature = alice.rsplit(".", 2)
        forged = f"{mallory_payload}.{timestamp}.{signature}"
        assert _decode_session_cookie(f"session={forged}") is None

    def test_cookie_signed_with_wrong_key_is_rejected(self):
        value = make_session_cookie(
            {"username": "alice"}, key="attacker-guessed-key"
        )
        assert _decode_session_cookie(f"session={value}") is None

    def test_expired_cookie_is_rejected(self):
        """Older than the remember-me horizon: the HTTP path would have
        rejected it, so the WS path must too (revocation parity)."""
        ts = int(time.time()) - _remember_me_max_age() - 3600
        value = make_session_cookie(
            {"username": "alice"}, timestamp=ts, real_session=False
        )
        assert _decode_session_cookie(f"session={value}") is None

    def test_garbage_cookie_value_is_rejected(self):
        assert _decode_session_cookie("session=garbage") is None

    def test_signed_non_json_payload_is_rejected(self):
        signer = itsdangerous.TimestampSigner(SECRET_KEY)
        value = signer.sign(b"@@@@").decode("utf-8")
        assert _decode_session_cookie(f"session={value}") is None

    def test_missing_session_cookie_returns_none(self):
        assert _decode_session_cookie("other=1; theme=dark") is None

    def test_empty_cookie_header_returns_none(self):
        assert _decode_session_cookie("") is None


class TestConnectHandshakeRealCookie:
    """connect() driven with the REAL cookie decode; only the encrypted
    DB manager (a true boundary) is mocked."""

    def _connect(self, environ, auth=None, dbm=None):
        dbm = dbm or _connected_db_manager()

        async def _run():
            with patch(
                "local_deep_research.database.encrypted_db.db_manager", dbm
            ):
                return await connect("sid-hs", environ, auth)

        return run_handshake_coro(_run), dbm

    def test_valid_cookie_accepted_and_cookie_username_recorded(
        self, socket_state
    ):
        value = make_session_cookie({"username": "alice", "session_id": "s1"})
        result, dbm = self._connect({"HTTP_COOKIE": f"session={value}"})

        assert result is True
        assert socketio_asgi._sid_users == {"sid-hs": "alice"}
        # The DB scoping used the cookie-verified username.
        assert dbm.is_user_connected.call_args[0][0] == "alice"

    def test_tampered_cookie_rejected_at_handshake(self, socket_state):
        value = make_session_cookie({"username": "alice", "session_id": "s1"})
        suffix = "AAAA" if not value.endswith("AAAA") else "BBBB"
        result, _ = self._connect(
            {"HTTP_COOKIE": f"session={value[:-4]}{suffix}"}
        )

        assert result is False
        assert socketio_asgi._sid_users == {}

    def test_missing_cookie_header_rejected(self, socket_state):
        result, _ = self._connect({})

        assert result is False
        assert socketio_asgi._sid_users == {}

    def test_auth_payload_cannot_forge_identity_without_cookie(
        self, socket_state
    ):
        """A client claiming a username via the Socket.IO auth payload
        (no valid cookie) must be refused — auth data is untrusted."""
        result, dbm = self._connect(
            {"HTTP_COOKIE": "session=garbage"},
            auth={"username": "mallory", "session_id": "s1"},
        )

        assert result is False
        assert socketio_asgi._sid_users == {}
        dbm.is_user_connected.assert_not_called()

    def test_auth_payload_cannot_override_cookie_identity(self, socket_state):
        """With a valid alice cookie, an auth payload claiming mallory
        must not change the socket's recorded identity."""
        value = make_session_cookie({"username": "alice", "session_id": "s1"})
        result, _ = self._connect(
            {"HTTP_COOKIE": f"session={value}"},
            auth={"username": "mallory"},
        )

        assert result is True
        assert socketio_asgi._sid_users == {"sid-hs": "alice"}


def _patch_user_db_session(captured: list, row):
    """Patch get_user_db_session (true DB boundary) to record the
    username the ownership check runs as and yield a session whose
    .query(...).first() returns `row`."""

    @contextmanager
    def fake(*args, **kwargs):
        captured.append(args[0] if args else kwargs.get("username"))
        db = MagicMock()
        db.query.return_value.filter_by.return_value.first.return_value = row
        db.query.return_value.filter.return_value.first.return_value = row
        yield db

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


class TestVerifiedUsernameScopesSubscriptions:
    """The cookie-verified identity — never client-supplied payload data —
    scopes the subscribe ownership check."""

    def test_ownership_check_runs_as_cookie_identity_not_payload(
        self, socket_state
    ):
        rid = f"rid-{uuid.uuid4().hex[:8]}"
        value = make_session_cookie({"username": "alice", "session_id": "s1"})
        captured: list = []

        async def _run():
            with patch(
                "local_deep_research.database.encrypted_db.db_manager",
                _connected_db_manager(),
            ):
                assert (
                    await connect(
                        "sid-owner", {"HTTP_COOKIE": f"session={value}"}
                    )
                    is True
                )
            with _patch_user_db_session(captured, row=("found",)):
                # Attacker-style payload: names another user explicitly.
                await on_subscribe(
                    "sid-owner",
                    {"research_id": rid, "username": "mallory"},
                )

        run_handshake_coro(_run)

        assert captured == ["alice"], (
            "ownership must be checked against the cookie-verified user"
        )
        assert socketio_asgi._subscriptions.get(("alice", rid)) == {"sid-owner"}

    def test_non_owner_gets_not_authorized_and_no_subscription(
        self, socket_state
    ):
        rid = f"rid-{uuid.uuid4().hex[:8]}"
        value = make_session_cookie({"username": "alice", "session_id": "s1"})
        captured: list = []
        emit_mock = AsyncMock()

        async def _run():
            with patch(
                "local_deep_research.database.encrypted_db.db_manager",
                _connected_db_manager(),
            ):
                await connect("sid-na", {"HTTP_COOKIE": f"session={value}"})
            with (
                _patch_user_db_session(captured, row=None),
                patch.object(socketio_asgi.sio, "emit", emit_mock),
            ):
                await on_subscribe("sid-na", {"research_id": rid})

        run_handshake_coro(_run)

        assert captured == ["alice"]
        assert ("alice", rid) not in socketio_asgi._subscriptions
        emit_mock.assert_awaited_once()
        event, payload = emit_mock.await_args.args
        assert event == "subscribe_error"
        assert payload["error"] == "Not authorized"
        assert emit_mock.await_args.kwargs["room"] == "sid-na"

    def test_unauthenticated_sid_gets_auth_required_error(self, socket_state):
        """A sid that never passed the handshake gets subscribe_error
        (Authentication required) addressed only to itself, and the DB
        is never consulted."""
        rid = f"rid-{uuid.uuid4().hex[:8]}"
        captured: list = []
        emit_mock = AsyncMock()

        async def _run():
            with (
                _patch_user_db_session(captured, row=("found",)),
                patch.object(socketio_asgi.sio, "emit", emit_mock),
            ):
                await on_subscribe("sid-ghost", {"research_id": rid})

        run_handshake_coro(_run)

        assert captured == []  # ownership check never ran
        assert ("alice", rid) not in socketio_asgi._subscriptions
        emit_mock.assert_awaited_once()
        event, payload = emit_mock.await_args.args
        assert event == "subscribe_error"
        assert payload["error"] == "Authentication required"
        assert emit_mock.await_args.kwargs["room"] == "sid-ghost"

    def test_disconnect_clears_verified_identity_and_subscriptions(
        self, socket_state
    ):
        """After disconnect the sid must lose its authenticated identity
        and all subscriptions — a stale mapping would let a later socket
        with a recycled sid inherit another user's auth."""
        rid = f"rid-{uuid.uuid4().hex[:8]}"
        value = make_session_cookie({"username": "alice", "session_id": "s1"})

        async def _run():
            with patch(
                "local_deep_research.database.encrypted_db.db_manager",
                _connected_db_manager(),
            ):
                await connect("sid-bye", {"HTTP_COOKIE": f"session={value}"})
            with _patch_user_db_session([], row=("found",)):
                await on_subscribe("sid-bye", {"research_id": rid})
            assert socketio_asgi._sid_users == {"sid-bye": "alice"}
            assert socketio_asgi._subscriptions.get(("alice", rid)) == {
                "sid-bye"
            }
            await disconnect("sid-bye")

        run_handshake_coro(_run)

        assert socketio_asgi._sid_users == {}
        assert ("alice", rid) not in socketio_asgi._subscriptions


class TestEndToEndPollingHandshake:
    """Full Engine.IO polling handshake through the mounted ASGI app:
    open session, send the Socket.IO CONNECT packet ('40'), read back
    acceptance ('40{"sid":...}') or refusal ('44...')."""

    def _handshake(self, cookie_value):
        client = TestClient(app, raise_server_exceptions=False)
        if cookie_value is not None:
            client.cookies.set("session", cookie_value)
        r_open = client.get("/ws/socket.io/?EIO=4&transport=polling")
        assert r_open.status_code == 200
        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
        r_poll = client.get(
            f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_sid}"
        )
        assert r_poll.status_code == 200
        return r_poll.text

    def test_valid_cookie_completes_connect_and_maps_identity(
        self, socket_state
    ):
        socketio_asgi.init_lock()
        dbm = _connected_db_manager()
        cookie = make_session_cookie({"username": "alice", "session_id": "s1"})

        with patch("local_deep_research.database.encrypted_db.db_manager", dbm):
            body = self._handshake(cookie)

        assert body.startswith("40"), body
        sio_sid = json.loads(body[2:])["sid"]
        assert socketio_asgi._sid_users.get(sio_sid) == "alice"
        assert dbm.is_user_connected.call_args[0][0] == "alice"

    def test_garbage_cookie_connect_refused(self, socket_state):
        socketio_asgi.init_lock()
        with patch(
            "local_deep_research.database.encrypted_db.db_manager",
            _connected_db_manager(),
        ):
            body = self._handshake("garbage")

        assert body.startswith("44"), body
        assert socketio_asgi._sid_users == {}

    def test_missing_cookie_connect_refused(self, socket_state):
        socketio_asgi.init_lock()
        with patch(
            "local_deep_research.database.encrypted_db.db_manager",
            _connected_db_manager(),
        ):
            body = self._handshake(None)

        assert body.startswith("44"), body
        assert socketio_asgi._sid_users == {}