🐛 Bug-fix PR

Closes #3019

📌 Summary

The stateful session fallback path in _get_request_context_or_default() resolved user identity through require_auth_override() -> require_auth(), which reads cookie tokens before Authorization headers. The primary ASGI middleware (streamable_http_auth) resolves identity using the Authorization header only. This asymmetry caused identity drift: a request carrying both a valid Authorization: Bearer <token-A> header and a jwt_token=<token-B> cookie would authenticate as user-A through the middleware but as user-B through the stateful session fallback, silently producing two different identities within the same request lifecycle.

🔁 Reproduction Steps

1. Set USE_STATEFUL_SESSIONS=true
2. Send a request to /servers/{id}/mcp/ with both:
   • Authorization: Bearer <token-for-user-A>
   • Cookie jwt_token=<token-for-user-B>
3. streamable_http_auth middleware sets ContextVar identity to user A (header-only path)
4. In any code path where _get_request_context_or_default() fires its fallback (ContextVar stale / not yet set), user identity resolves to user B (cookie wins in require_auth)

The practical trigger — both a valid header and a different valid cookie on the same request — is uncommon in normal operation (MCP SDK clients use headers; Admin UI uses cookies, not both). However, it is a correctness and security issue whenever it does occur.

🐞 Root Cause

Three layers interact to produce the bug.

Layer 1 - ASGI middleware (streamable_http_auth, streamablehttp_transport.py:2200-2209)
Extracts the token from the Authorization header only. If no Bearer token is present the middleware raises immediately; cookies are never consulted.

token: str | None = None
if authorization:
    scheme, credentials = get_authorization_scheme_param(authorization)
    if scheme.lower() == "bearer" and credentials:
        token = credentials

Layer 2 - Fallback (_get_request_context_or_default, streamablehttp_transport.py:996-1002)
Called when ContextVars are stale. Passed both the Authorization header value and the jwt_token cookie value to require_auth_override().

Layer 3 - require_auth token resolution (verify_credentials.py:389-401)
require_auth_override delegates to require_auth, whose token resolution order is:

1. request.cookies.get("jwt_token") ← COOKIE WINS (highest priority)
2. credentials.credentials ← Authorization header (only if no cookie)
3. jwt_token parameter ← cookie param fallback

The cookie always beats the Authorization header, the exact inverse of the middleware.

A wrong comment in the fallback (# In stateful session, cookie might be more reliable) made this look intentional.

💡 Fix Description

New function: require_auth_header_first() (verify_credentials.py)

A dedicated variant of require_auth_override() with reversed token precedence matching the middleware:

1. Authorization Bearer header ← header wins (highest priority)
2. request.cookies jwt_token ← cookie fallback
3. jwt_token keyword argument ← parameter fallback

All other behaviour is identical to require_auth_override: proxy auth, Basic auth (docs_allow_basic_auth), anonymous when auth not required, and 401 when required but no token is found. require_auth itself is not changed — its cookie-first ordering is intentional for browser/Admin UI routes and protected by explicit API/browser checks in rbac.py.

Call-site change (streamablehttp_transport.py)

_get_request_context_or_default() now calls require_auth_header_first() instead of require_auth_override(), and the misleading comment is replaced with an accurate one explaining the precedence alignment:

# Use require_auth_header_first to match streamable_http_auth token precedence:
# Authorization header > request cookies > jwt_token parameter
raw_payload = await require_auth_header_first(auth_header=auth_header, jwt_token=cookie_token, request=request)

Tests

• test_verify_credentials.py - 15 new tests for require_auth_header_first: header beats request.cookies, header beats jwt_token param, cookie fallback when no header, jwt_token param fallback, anonymous/401 modes, proxy auth path, Basic auth path, and edge cases (auth_header="", "Bearer " with empty token, request.cookies wins over jwt_token param)
• test_streamablehttp_transport.py - 1 new test (test_get_request_context_header_wins_over_cookie) that intercepts at verify_credentials_cached to assert the header token is passed when both header and cookie are present; 5 existing tests updated to mock require_auth_header_first instead of the now-removed require_auth_override import

🧪 Verification

📐 MCP Compliance (if relevant)

• Matches current MCP spec
• No breaking change to MCP clients

✅ Checklist

• Code formatted (make black isort pre-commit)
• No secrets/credentials committed