fix(mcp): resolve session-token sub UUID to email in streamable-HTTP auth

[msureshkumar88]

Closes #5215
Closes #5750

Problem

Session tokens issued by /admin/login carry sub as the EmailUser.id UUID (mcpgateway/admin.py:4273), while legacy/API tokens carry the email. The MCP streamable-HTTP auth path treated sub as an email unconditionally:

• streamablehttp_transport.py:5089 — _auth_jwt()
• streamablehttp_transport.py:2221 — _normalize_jwt_payload() (stateful-session fallback)

So the EmailUser lookup missed for every session token, with two different symptoms depending on configuration:

• LLM Chat cannot connect to a Virtual Server on the same gateway — forwarded session token rejected (401) by /servers/{id}/mcp #5215 — with require_user_in_db enabled, 401 {"detail": "User not found in database"} on /servers/{id}/mcp. LLM Chat could not connect to a virtual server hosted by the same gateway.
• [BUG]: MCP streamable-HTTP transport treats session-JWT UUID sub as an email — non-admin session tokens see 0 tools and fail tools.execute RBAC #5750 — on the unified /mcp endpoint the miss resolved empty teams instead, giving public-only visibility (tools/list returns 0) and a UUID-keyed RBAC check that denied tools/call. This affected every external agent runtime using a real session token, not just LLM Chat.

The failure was also sticky: the transport writes back to the auth cache (:5153, :5164, :5206) under the same unresolved key, so it cached CachedAuthContext(user=None) against the UUID. Subsequent requests took the cache-hit branch and returned the same 401 without re-querying.

Fix

Add _resolve_subject_email() and call it in both sites, before any cache lookup or DB query. This mirrors resolution the rest of the codebase already does — mcpgateway/auth.py:1581 (get_current_user) and auth.py:553 (resolve_session_teams) — reusing the existing _get_email_by_id_sync() helper. The MCP transport was the one path that never got it.

Notes on the approach:

• Fixed at the root rather than in llmchat_router. The issue proposed minting a fresh loopback token in connect(). That resolves this one call site but leaves every external MCP client on a session token broken, so llmchat_router is unchanged — it keeps forwarding the session cookie, and the loopback call now authenticates as the real user, correctly scoped to their teams and RBAC.
• No extra DB read on the hot path. A UUID() parse guard short-circuits legacy/API tokens before any lookup. Net effect is a reduction: session tokens currently miss the cache on every request and re-run the full fallback path.
• Fails closed. An unresolvable subject returns the raw value so the existing require_user_in_db checks still deny, rather than downgrading to anonymous. A DB failure raises SQLAlchemyError, which the existing handler at :5344 turns into 503 — deliberately unlike the fail-open revocation/user lookups at :5183/:5194, since an unresolvable subject means we don't know who the caller is.
• All MCP transports (/mcp, /servers/{id}/mcp, /mcp/sse, /mcp/message) share _auth_jwt, so all are fixed together.

Behaviour change worth a look during review

The three deny branches read elif settings.require_user_in_db and user_email != platform_admin_email. Previously a platform-admin session token carried a UUID that never equalled platform_admin_email, so the admin escape hatch could not apply. It now does. That is the intended semantics of the hatch, but it is a widening on a security branch, so it has a dedicated test (test_auth_jwt_session_token_platform_admin_escape_hatch).

Related, not included

mcpgateway/routers/reverse_proxy.py:450/:481 use the same sub-or-email shape for session ownership. It is not broken the same way — _validate_session_ownership compares sub against sub, so both forms match. The only divergence is a session created under one token type and accessed under the other, which yields 403 (fail-closed). Left alone here; happy to file separately if it's worth normalizing.

Tests

Added to tests/unit/mcpgateway/transports/test_streamablehttp_transport.py, covering the resolver directly, both patched call sites, and the deny paths: unknown user still 401s, legacy tokens perform no subject lookup, DB errors propagate to 503, and cache/lookup calls are keyed by email rather than UUID.

Verified the behavioural tests fail against the unpatched transport and pass with the fix.

[Lang-Akshay]

Thanks for the PR @msureshkumar88

Please address following blocking Changes

#	Area	File	Line	Blocking reason	Required change
1	Security / Quality	mcpgateway/transports/streamablehttp_transport.py	2237 (also consumed at 5140)	_resolve_subject_email() uses payload.get("sub") or payload.get("email"). The repository security invariant requires canonical email-over-sub precedence when both claims exist. Selecting sub first can make cache keys, team visibility, and RBAC evaluate a different principal than the canonical email, causing identity/authz confusion. The security specialist classified this as Critical, CWE-287/CWE-863.	Validate a non-empty string email first, fall back to sub, then UUID-resolve only the selected subject. Add deny-path coverage for conflicting email/sub claims.

[msureshkumar88]

Thanks for the catch, @Lang-Akshay — good call flagging the precedence order.

Fixed in 5688ee8: _resolve_subject_email() now validates a non-empty string email claim first and only falls back to sub when it's absent/malformed, matching the canonical email-over-sub precedence in get_user_email() (mcpgateway/auth_context.py).

Added deny-path coverage:

• conflicting email/sub claims → email wins, no UUID lookup performed
• non-string email claim → falls back to sub
• empty-string email claim → falls back to sub

Full transport suite (563 tests) still green. Ready for another look.

[Lang-Akshay]

✅ LGTM

[ja8zyjits]

⚠️ Warnings (Can be a followup)

Session token sub claim structure undocumented

Context: PR fixes bug where MCP transport treated sub as email unconditionally. Session tokens carry sub as EmailUser.id UUID (admin.py:4273), legacy/API tokens carry email directly.

Files:

• mcpgateway/transports/streamablehttp_transport.py:2203-2260 (new _resolve_subject_email())
• mcpgateway/admin.py:4273 (session token minting)
• docs/docs/architecture/multitenancy.md:323-363 (session token behavior)
• docs/docs/architecture/oauth-design.md:250 (session-semantics payload)

Gap: Docs describe session token team resolution but never document sub claim structure differs between token types.

Impact: Medium — developers integrating MCP clients or debugging auth lack visibility. Fix correct and well-tested.

Recommendation: Add subsection to docs/docs/architecture/multitenancy.md under "Session Tokens" (L343-363):

#### JWT Payload Structure by Token Type

**Session tokens** (`token_use: "session"`):
- `sub`: `EmailUser.id` (UUID) — resolved to email via DB lookup
- Minted by `/admin/login` and SSO flows
- Example: `{"sub": "387e3345-7996-4496-aa2d-09729ec8b3be", "token_use": "session", ...}`

**API/Legacy tokens** (`token_use: "api"` or absent):
- `sub`: User email address (string)
- Minted by `create_jwt_token()` utility
- Example: `{"sub": "user@example.com", "token_use": "api", ...}`

MCP transport resolves session token UUIDs to emails before cache lookups and RBAC checks (`_resolve_subject_email()` in `streamablehttp_transport.py`), ensuring consistent identity keying.

---

[ja8zyjits]

LGTM