~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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}"
)