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.

20.8 KB
Raw Blame
"""Session-cookie *semantics* under Starlette's ``SessionMiddleware``.

Flask signed its session with itsdangerous and handed it to the browser
as one cookie; the port does the same through Starlette's
``SessionMiddleware``. The signing story is therefore unchanged — but
the *guardrails around it* are not, and that is what this module fences.

Covered here (each uncovered elsewhere in the suite):

* **No 4 KB guard at all.** Werkzeug's ``dump_cookie`` carries
  ``max_size=4093`` and emits a ``UserWarning`` when a session cookie
  outgrows what browsers will store. Starlette's ``SessionMiddleware``
  formats the ``Set-Cookie`` header by hand with no size check
  whatsoever, so the same overflow is now completely silent.
* **``_flashes`` is an unbounded accumulator** that feeds precisely that
  overflow: ``dependencies/flash.py`` appends and never caps, and the
  backlog is only drained by a template that actually renders
  ``get_flashed_messages``.
* **Session survival across a redirect chain** (login → 302 → landing
  page), which no existing test follows end to end — every other test
  passes ``follow_redirects=False``.
* **Concurrent writes clobber each other**, because the cookie is the
  only store and the browser keeps exactly one.
* **Logout reissues a live cookie rather than deleting it.**

Deliberately NOT duplicated — these are already well fenced:

* Max-Age/Expires for remember-me vs. browser-session cookies —
  ``tests/web/test_session_cookie_behavior.py``,
  ``tests/web/test_remember_me_and_json_body_cap.py``,
  ``tests/web/test_registration_session_cookie.py``.
* ``Secure`` flag by scheme — ``tests/web/test_secure_cookie_middleware.py``.
* Truncated / bit-flipped / forged signatures —
  ``tests/web/test_auth_session_lifecycle.py``
  (``TestForgedSessionCookiesAreRejected``).
* Replaying a captured cookie after logout —
  ``tests/web/test_long_integration_flows.py`` (``TestSessionLifecycle``).
"""

import base64
import binascii
import json
import uuid
import warnings

import pytest
from fastapi.testclient import TestClient
from starlette.middleware.sessions import SessionMiddleware
from starlette.requests import Request
from starlette.responses import PlainTextResponse

from local_deep_research.web.dependencies.flash import flash

TEST_PASSWORD = "TestPassword123!"  # noqa: S105

# The largest cookie a browser is required to store (RFC 6265 asks for
# 4096 bytes per cookie including the name and separators). Werkzeug uses
# 4093 as the header-value budget it warns above; we reuse that number so
# the two stacks are compared on identical terms.
BROWSER_COOKIE_LIMIT = 4093

# `security.rate_limit_settings` — /settings/save_settings is capped at
# "30 per minute" (dependencies/rate_limit.py). Stay well under it so every
# request in the accumulation tests is actually served; 12 is already more
# than any sane cap on a flash backlog would allow.
UNREAD_SAVES = 12


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def _fresh_client(app, base_url="http://testserver"):
    """TestClient with a unique X-Forwarded-For so each client lands in its
    own slowapi bucket (registration is rate limited per client IP)."""
    client = TestClient(app, base_url=base_url, raise_server_exceptions=False)
    fwd = f"10.{uuid.uuid4().int % 254 + 1}.{uuid.uuid4().int % 254 + 1}.1"
    client.headers.update({"X-Forwarded-For": fwd})
    return client


def _set_cookie_headers(resp):
    """Every ``Set-Cookie`` value for the ``session`` cookie."""
    return [
        v
        for k, v in resp.headers.multi_items()
        if k.lower() == "set-cookie" and v.lower().startswith("session=")
    ]


def _cookie_value(resp):
    """The raw signed ``session`` cookie value from a response, or None.

    Read off the response headers rather than the client jar: the jar can
    hold same-named cookies for several domains and then refuses an
    unqualified lookup.
    """
    headers = _set_cookie_headers(resp)
    if not headers:
        return None
    return headers[-1].split(";")[0].split("=", 1)[1]


def _cookie_attr(cookie, name):
    """Value of a cookie attribute, "" for a valueless one, None if absent."""
    for part in cookie.split(";")[1:]:
        attr, sep, value = part.strip().partition("=")
        if attr.lower() == name.lower():
            return value if sep else ""
    return None


def _payload(cookie_value):
    """Decode the (signed, *unencrypted*) session payload to a dict.

    Starlette stores ``urlsafe_b64encode(json)`` before the itsdangerous
    signature, so the payload is readable without the secret key. We only
    read it here — never re-sign — so this is an observation of the wire
    format, not a re-implementation of the middleware.
    """
    data = cookie_value.split(".")[0]
    data += "=" * (-len(data) % 4)
    try:
        return json.loads(base64.urlsafe_b64decode(data))
    except (ValueError, binascii.Error) as exc:  # pragma: no cover
        raise AssertionError(
            f"session cookie payload was not decodable JSON: {exc}"
        ) from exc


def _csrf(client):
    """Stamp the session with a CSRF token and return it."""
    client.get("/auth/login")
    resp = client.get("/auth/csrf-token")
    assert resp.status_code == 200, (
        f"could not mint a CSRF token: {resp.status_code} {resp.text[:200]}"
    )
    return resp.json()["csrf_token"]


def _register(client, username):
    return client.post(
        "/auth/register",
        data={
            "username": username,
            "password": TEST_PASSWORD,
            "confirm_password": TEST_PASSWORD,
            "acknowledge": "true",
            "csrf_token": _csrf(client),
        },
        follow_redirects=False,
    )


@pytest.fixture
def logged_in(app):
    """Register (which auto-logs in) and hand back the client + username."""
    client = _fresh_client(app)
    username = f"sesssem_{uuid.uuid4().hex[:8]}"
    resp = _register(client, username)
    assert resp.status_code == 302, (
        f"registration failed: {resp.status_code} {resp.text[:300]}"
    )
    return client, username


def _production_session_kwargs(app):
    """The exact kwargs ``fastapi_app`` builds SessionMiddleware with.

    Pulled off the live middleware stack instead of being restated here,
    so this test cannot drift away from production configuration.
    """
    for mw in app.user_middleware:
        if mw.cls is SessionMiddleware:
            return dict(mw.kwargs)
    raise AssertionError(
        "SessionMiddleware is not on the application middleware stack"
    )


# ---------------------------------------------------------------------------
# 1. The 4 KB cookie limit
# ---------------------------------------------------------------------------


class TestOversizedSessionCookie:
    """A session larger than a browser will store.

    Browsers do not error on an over-limit ``Set-Cookie`` — they drop it.
    The next request then arrives with no session at all, so the user is
    silently signed out and loses whatever the session was carrying. The
    only defence is server-side detection at the moment the cookie is
    written, and that is what the migration dropped.
    """

    def _emit_oversized(self, app, flashes=60):
        """Drive a real session over the limit through the real stack.

        Uses the production ``SessionMiddleware`` class with the production
        kwargs and the production ``flash()`` helper; only the innermost
        endpoint is a stub, so the cookie-writing path under test is
        entirely production code.
        """
        message = "Settings saved; 1 unrecognized key(s) were ignored."

        async def endpoint(scope, receive, send):
            request = Request(scope, receive)
            for _ in range(flashes):
                flash(request, message, "warning")
            await PlainTextResponse("ok")(scope, receive, send)

        wrapped = SessionMiddleware(endpoint, **_production_session_kwargs(app))
        with warnings.catch_warnings(record=True) as caught:
            warnings.simplefilter("always")
            resp = TestClient(wrapped).get("/")
            messages = [str(w.message) for w in caught]
        return resp, messages

    def test_an_over_limit_session_cookie_is_emitted_at_full_size(self, app):
        """The stack really will hand the browser an unusable cookie."""
        resp, _ = self._emit_oversized(app)
        headers = _set_cookie_headers(resp)
        assert headers, "no session cookie was written at all"
        assert len(headers[-1]) > BROWSER_COOKIE_LIMIT, (
            "test no longer drives the session past the browser limit; "
            f"header was only {len(headers[-1])} bytes"
        )
        # Nothing truncated or split it — it goes out whole and unusable.
        assert len(headers) == 1, (
            f"expected one session cookie, got {len(headers)}: {headers}"
        )

    def test_werkzeug_would_have_warned_about_the_same_value(self, app):
        """Baseline: main's stack had a guard for exactly this.

        Pins the *regression*, not merely the current behaviour — if
        Werkzeug's guard is what we lost, it has to be shown to exist.
        """
        from werkzeug.http import dump_cookie

        resp, _ = self._emit_oversized(app)
        oversized_value = _cookie_value(resp)
        with warnings.catch_warnings(record=True) as caught:
            warnings.simplefilter("always")
            dump_cookie("session", oversized_value)
            werkzeug_warnings = [str(w.message) for w in caught]
        assert any("too large" in w for w in werkzeug_warnings), (
            "Werkzeug no longer warns on an oversized cookie, so the "
            "Flask-vs-Starlette comparison this module rests on is stale: "
            f"{werkzeug_warnings}"
        )

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "DEFECT: starlette.middleware.sessions builds the Set-Cookie "
            "header with a bare str.format() and never compares its length "
            "to the ~4093-byte browser limit, unlike werkzeug.http."
            "dump_cookie(max_size=4093) which main used. An over-limit "
            "session is emitted silently, the browser discards it, and the "
            "user is signed out with nothing logged server-side."
        ),
    )
    def test_an_oversized_session_cookie_is_reported(self, app):
        """The contract we WANT: overflow must not be silent.

        Warning, log line or error — any of them would satisfy this. The
        day the stack grows a size check, this flips to pass.
        """
        _, messages = self._emit_oversized(app)
        assert any(
            "too large" in m.lower() or "cookie" in m.lower() for m in messages
        ), (
            "the session cookie overflowed the browser limit and nothing "
            f"was reported; warnings seen: {messages}"
        )


# ---------------------------------------------------------------------------
# 2. What drives the session over the limit
# ---------------------------------------------------------------------------


class TestFlashBacklogGrowsWithoutBound:
    """``_flashes`` is the session's only unbounded key.

    ``dependencies/flash.py`` appends to ``_flashes`` and never trims it.
    The backlog is drained only by ``get_flashed_messages``, which is
    reached only when a template that renders the flash block is actually
    returned. ``POST /settings/save_settings`` flashes and then answers
    ``302`` — so a fetch()-driven client that does not follow the redirect
    into the HTML page never drains anything, and every save adds another
    entry to the cookie for the life of the session.
    """

    def _save(self, client, token, value="1"):
        return client.post(
            "/settings/save_settings",
            data={"a.bogus.key": value},
            headers={"X-CSRFToken": token},
            follow_redirects=False,
        )

    def test_every_unread_save_adds_an_entry_and_grows_the_cookie(
        self, logged_in
    ):
        """One flash per save, forever, with the cookie growing each time."""
        client, _ = logged_in
        token = _csrf(client)

        sizes = []
        latest = None
        saves = UNREAD_SAVES
        for _ in range(saves):
            resp = self._save(client, token)
            assert resp.status_code == 302, (
                f"save was not served: {resp.status_code} {resp.text[:200]}"
            )
            value = _cookie_value(resp)
            assert value is not None, "save did not rewrite the session"
            latest = value
            sizes.append(len(value))

        backlog = _payload(latest).get("_flashes", [])
        assert len(backlog) == saves, (
            "flash backlog is not 1:1 with unread saves — expected "
            f"{saves} entries, found {len(backlog)}"
        )
        assert sizes == sorted(sizes) and sizes[-1] > sizes[0], (
            f"cookie did not grow monotonically across saves: {sizes}"
        )

    def test_the_backlog_survives_a_request_that_renders_no_flashes(
        self, logged_in
    ):
        """Only a flash-rendering template drains it; JSON routes do not."""
        client, _ = logged_in
        token = _csrf(client)
        self._save(client, token)
        self._save(client, token)

        resp = client.get("/auth/check")
        assert resp.status_code == 200, resp.text
        after = _cookie_value(resp)
        if after is not None:
            assert len(_payload(after).get("_flashes", [])) == 2, (
                "a JSON route unexpectedly drained the flash backlog"
            )

        # And the backlog is still there for the next save to build on.
        resp = self._save(client, token)
        assert len(_payload(_cookie_value(resp)).get("_flashes", [])) == 3, (
            "flash backlog did not carry across an intervening JSON request"
        )

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "DEFECT: dependencies/flash.py:11 flash() does "
            "`messages.append(...)` with no cap, so an AJAX client that "
            "never renders the flash block accumulates one entry per save "
            "until the cookie passes the browser limit and is dropped. "
            "At ~92 bytes per entry a single minute at the 30/min settings "
            "rate limit already spends ~3 KB of the ~4 KB budget."
        ),
    )
    def test_the_flash_backlog_is_capped(self, logged_in):
        """The contract we WANT: a bounded backlog."""
        client, _ = logged_in
        token = _csrf(client)
        latest = None
        for _ in range(UNREAD_SAVES):
            latest = _cookie_value(self._save(client, token)) or latest
        backlog = _payload(latest).get("_flashes", [])
        assert len(backlog) <= 10, (
            f"flash backlog is unbounded: grew to {len(backlog)} entries"
        )


# ---------------------------------------------------------------------------
# 3. Redirect chains
# ---------------------------------------------------------------------------


def test_session_survives_a_redirect_chain(app):
    """A session written before a 302 is still readable after following it.

    Every other session test in the suite uses ``follow_redirects=False``,
    so nothing pins that the cookie actually rides through the bounce that
    real login performs. SameSite=Lax permits this same-site redirect;
    a stricter value, or a Path that did not cover the target, would strand
    the session on the hop.
    """
    client = _fresh_client(app)
    username = f"sessredir_{uuid.uuid4().hex[:8]}"

    resp = _register(client, username)
    assert resp.status_code == 302, resp.text
    landing = resp.headers["location"]

    followed = client.get(landing, follow_redirects=True)
    assert followed.status_code == 200, (
        f"redirect target did not render: {followed.status_code}"
    )

    # The session is still authoritative after the bounce.
    check = client.get("/auth/check")
    assert check.status_code == 200, check.text
    body = check.json()
    assert body.get("authenticated") is True, (
        f"session did not survive the redirect chain: {body}"
    )
    assert body.get("username") == username, (
        f"session identified the wrong user after redirect: {body}"
    )


def test_the_session_cookie_is_scoped_to_the_whole_site(logged_in):
    """Path=/ — otherwise the redirect above would land outside its scope."""
    client, _ = logged_in
    resp = client.get("/auth/csrf-token")
    cookie = _set_cookie_headers(resp)
    if not cookie:
        pytest.skip("no session cookie rewritten on this request")
    assert _cookie_attr(cookie[-1], "path") == "/", (
        f"session cookie is not site-wide: {cookie[-1]}"
    )


# ---------------------------------------------------------------------------
# 4. Concurrent writes
# ---------------------------------------------------------------------------


def test_a_concurrent_session_write_discards_the_other_tabs_token(app):
    """Two tabs, one cookie: the later response wins and the other is lost.

    Both tabs load the same session, each mutates it, and each sends back a
    full ``Set-Cookie`` built from its own snapshot. The browser keeps only
    the last one, so the first tab's write is gone — there is no
    server-side session to merge into. Pinned through its user-visible
    consequence: the CSRF token tab A was issued no longer validates.
    """
    client = _fresh_client(app)
    username = f"sessrace_{uuid.uuid4().hex[:8]}"
    reg = _register(client, username)
    assert reg.status_code == 302, reg.text
    start = _cookie_value(reg)
    assert start, "no session cookie after registration"

    # Tab A mints a CSRF token; that token lives in tab A's session copy.
    tab_a = _fresh_client(app)
    tab_a.cookies.set("session", start)
    resp_a = tab_a.get("/auth/csrf-token")
    assert resp_a.status_code == 200, resp_a.text
    token_a = resp_a.json()["csrf_token"]

    # Tab B started from the SAME cookie and mints its own.
    tab_b = _fresh_client(app)
    tab_b.cookies.set("session", start)
    resp_b = tab_b.get("/auth/csrf-token")
    assert resp_b.status_code == 200, resp_b.text
    cookie_b = _cookie_value(resp_b)
    assert cookie_b, "tab B did not rewrite the session"

    assert _payload(cookie_b).get("_csrf_token") != token_a, (
        "tab B's cookie carries tab A's token, so this is no longer a "
        "lost-update scenario and the test proves nothing"
    )

    # Tab B's response reached the browser last, so its cookie is the one
    # on disk. Tab A now posts with the token it was legitimately issued.
    browser = _fresh_client(app)
    browser.cookies.set("session", cookie_b)
    replay = browser.post(
        "/settings/save_settings",
        data={"a.bogus.key": "1"},
        headers={"X-CSRFToken": token_a},
        follow_redirects=False,
    )
    assert replay.status_code == 403, (
        "expected tab A's token to be rejected against tab B's session "
        f"(lost update); got {replay.status_code}"
    )


# ---------------------------------------------------------------------------
# 5. Logout
# ---------------------------------------------------------------------------


def test_logout_reissues_a_live_cookie_instead_of_deleting_it(logged_in):
    """Logout leaves a valid cookie behind rather than expiring it.

    ``routers/auth.py`` calls ``request.session.clear()`` and then
    ``flash(...)``. Starlette deletes the cookie only when the session ends
    the request *empty*; the flash re-populates it, so the browser is
    instead handed a fresh, non-expiring, still-signed cookie whose payload
    is just the goodbye message.

    That is not an authentication hole — the credential keys are gone and
    the server-side session is torn down (covered by
    test_long_integration_flows.TestSessionLifecycle). It is pinned because
    the flash-vs-delete interaction is load-bearing and easy to break: drop
    the flash and the cookie is deleted instead, changing what every
    logged-out browser stores.
    """
    client, _ = logged_in
    resp = client.post(
        "/auth/logout",
        headers={"X-CSRFToken": _csrf(client)},
        follow_redirects=False,
    )
    assert resp.status_code == 302, resp.text

    headers = _set_cookie_headers(resp)
    assert headers, "logout wrote no session cookie at all"
    cookie = headers[-1]

    # Not a deletion: no zero Max-Age and no epoch Expires.
    assert _cookie_attr(cookie, "max-age") in (None, ""), (
        f"logout cookie unexpectedly carries Max-Age: {cookie}"
    )
    assert _cookie_attr(cookie, "expires") is None, (
        f"logout cookie unexpectedly carries Expires: {cookie}"
    )

    payload = _payload(_cookie_value(resp))
    assert payload.get("_flashes"), (
        f"logout cookie carries no flash payload: {payload}"
    )
    # Every credential-bearing key is gone.
    for key in ("username", "session_id", "temp_auth_token"):
        assert key not in payload, (
            f"logout left {key!r} in the client-side session: {payload}"
        )