feat(mcp): mint gateway-bound envelope at the token endpoint for dcr_bridge oauth_delegate

[tin-berri]

Relevant issues

Linear ticket

Resolves LIT-4338 (final PR of the delegate-bridge stack; completes the mint -> admit loop)

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

The producer -> consumer loop is proven as a unit contract: the token endpoint mints a gateway-bound envelope, and opening it back through the consumer recovers the sealed key reference and the upstream Authorization exactly, with the raw upstream token never appearing in the bearer the client receives. The full interactive proof (a real client signing in, receiving the envelope, and calling tools that attribute to the litellm identity) exercises this producer together with the admission consumer in the PR below it, and is the recommended combined-stack validation on a live proxy before merge; I did not want to claim run logs this PR does not yet have

pytest tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py -q
164 passed

Type

🆕 New Feature

Changes

Completes the DCR-bridge oauth_delegate flow: at the OAuth token endpoint, a bridge oauth_delegate server now returns a gateway-bound envelope instead of the raw upstream token, so the client holds one bearer that both admits it (via the consumer PR) and forwards the upstream token, with nothing stored server-side

The mint is modeled as three phases inside exchange_token_with_server, whose failures are values rather than raised exceptions. _prepare_bridge_mint runs before the upstream exchange, fires only when the server is both is_oauth_delegate and is_dcr_bridge, checks every precondition once (master_key set, then a resolvable active litellm key), and returns either a frozen _BridgeMintReady carrying the resolved key hash and the master-key-derived envelope keys, or a _BridgeMintError. Because every precondition lives in prepare and prepare runs before the exchange, a missing master_key or an unresolvable identity fails closed without ever consuming the single-use upstream code or rotating a refresh token, for both grant types, by construction rather than by a guard kept in sync by hand. _finish_bridge_mint runs after the exchange and has no preconditions left that can fail; it seals the upstream grant plus an EnvelopeIdentity bound to that key hash and this server_id via build_bridge_token_response and returns the envelope as the access_token with the envelope's own short expires_in. Its only failure values are properties of the upstream response itself, a missing usable access_token or a token too large to seal

Every resolution step the mint depends on returns a precise tagged value rather than a bare None, because a None that meant several different things is what let the wrong status be reported. Identity resolution returns a _ResolvedKey or one of no_active_key / unavailable / unresolvable, classified the way admission's _reload_admitted_key classifies the same conditions; upstream-lifetime classification returns a positive number of seconds, "unspecified" (absent or unparseable, which the envelope caps), or "expired" (a parseable non-positive value, i.e. an already-dead token); and upstream-grant validation returns a typed grant or one of no_access_token / expired_lifetime. Thin exhaustive mappers (match plus assert_never) lift each vocabulary into one _BridgeMintError taxonomy of eight named failures, and a single _bridge_mint_error_response gives each its truthful RFC 6749 section 5.2 status: 400 invalid_request for a missing litellm credential, 400 unsupported_grant_type for a refresh_token grant, 503 temporarily_unavailable for a transient auth-DB outage, 500 server_error for a gateway that cannot resolve identity or has no master_key, and 502 for an upstream response with no usable token, an already-expired lifetime, or one too large to seal. Because the status is chosen by an exhaustive match over the union, a new failure mode cannot be added without a matching status, and a DB outage can no longer read as a client 400 (mint and admission now agree on the same outage)

Three consequences follow from modelling those outcomes precisely. A database outage during identity resolution is a retryable 503 rather than a 400 that blames the caller. An upstream token whose reported lifetime is already elapsed is rejected with 502 rather than sealed into an hour-long envelope around a dead bearer, while an absent or unparseable lifetime still mints a capped envelope as before. And the refresh_token grant, which a bridge server can never legitimately receive (it seals no upstream refresh_token, so the client holds none to present), is rejected in _prepare_bridge_mint before the exchange, so a stray refresh request can never rotate or consume the client's upstream refresh credential; renewal is re-running authorization_code. Every other server, including true_passthrough bridges and non-bridge oauth_delegate servers, keeps returning the raw upstream token, so flag-off behavior is byte-identical

Sealing the key hash rather than a bare user_id is what lets the consumer reload the live key at admission and enforce the key's current team, org, and tool restrictions plus revocation, instead of admitting under a frozen identity. The hash is a one-way digest, not a usable credential (the edge rejects a bare hash presented as a bearer), and it is the same value get_key_object and the cache/DB layer key the record by, so the sealed reference resolves back to the key at admission. The token endpoint's key resolution is extracted into a shared _resolve_active_litellm_key so the per-user token store (which needs the user_id) and this mint (which needs the key hash) derive from one active-key-gated path

The upstream token response is validated field by field into a typed grant before sealing, so nothing untyped from the provider flows into the envelope, and the raw upstream token never appears in the bearer the client receives. Tests cover the mint-and-open round-trip through the consumer asserting the sealed key hash, the fail-closed path without an active key, both raw-token paths (true_passthrough bridge and non-bridge oauth_delegate), and the shared resolver returning the hash for an active key while rejecting a blocked key

---

Note

High Risk
Changes OAuth token issuance, API key validation, and master-key-derived credential sealing on a security-sensitive path; misclassification of DB outages or lifetime handling could break clients or admit bad tokens, though behavior is heavily tested and scoped to bridge oauth_delegate.

Overview
For DCR-bridge oauth_delegate MCP servers, the OAuth token endpoint now returns a gateway-bound envelope (llm_env_…) instead of the raw upstream access_token, so one client bearer binds LiteLLM key identity and forwards upstream authorization.

exchange_token_with_server gains a three-phase mint: _prepare_bridge_mint (before upstream POST) checks authorization_code only, master_key, and an active LiteLLM key via _resolve_active_litellm_key; _finish_bridge_mint (after exchange) validates the upstream JSON into a typed grant, seals with build_bridge_token_response, and omits upstream refresh_token from the response. Failures are tagged values mapped through _bridge_mint_error_response to RFC 6749 §5.2 statuses (400 vs 503 vs 500 vs 502), including no upstream call when identity or config fails so single-use codes are not burned.

Key resolution is refactored: _key_is_active (team keys without user_id allowed; bad expiry → inactive), distinct no_active_key / unavailable / unresolvable outcomes, and expires_in handling that rejects already-dead upstream lifetimes while capping unknown ones. Non-bridge and true_passthrough paths still return the raw upstream token.

Extensive tests cover mint/open round-trip, fail-closed pre-exchange paths, grant/lifetime edge cases, and resolver behavior.

^{Reviewed by Cursor Bugbot for commit 55ff3a2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

For DCR-bridge oauth_delegate MCP servers the OAuth token endpoint now returns a gateway-bound envelope (llm_env_…) instead of the raw upstream access token, completing the mint → admission loop. Every other server mode (true_passthrough, non-bridge oauth_delegate) keeps returning the raw token unchanged.

• Three-phase mint in exchange_token_with_server: _prepare_bridge_mint runs before the upstream code exchange, validating grant type, master_key, and litellm identity (via the new _resolve_active_litellm_key) so no single-use code is ever burned on a precondition failure; _finish_bridge_mint runs after, sealing the typed upstream grant into a SealedEnvelope whose expires_in is derived from the JWT's own exp to avoid over-promising lifetime.
• Tagged failure vocabulary: _KeyResolutionFailure / _BridgeMintError replace bare None returns, and exhaustive match + assert_never mappers route each failure to its RFC 6749 §5.2 status (400 / 503 / 500 / 502), so a DB outage now correctly yields 503 rather than 400.
• Previous inline comments addressed: the eager access_token = token_response["access_token"] extraction that preceded the bridge check was removed; the non-bridge path extracts it inline after the bridge early-return, so neither path can KeyError on the bridge code path.

Confidence Score: 5/5

Safe to merge: the bridge mint is flag-gated behind both is_oauth_delegate and is_dcr_bridge, so no existing server mode is affected, and the three-phase architecture guarantees single-use codes are never consumed on precondition failures.

The change is well-isolated to the new bridge path and backed by 18 new mock unit tests covering all failure modes, the mint-and-open round-trip, and the flag-off paths. The two inline-comment issues flagged in the previous review iteration (eager access_token extraction before the bridge check, and the companion non-bridge extraction) are both correctly resolved in this diff. No pre-existing tests were weakened. The exhaustive match/assert_never pattern enforces that adding a failure mode requires a matching status, and the _key_is_active malformed-expiry guard prevents an unhandled ValueError from surfacing as a 500.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py	Adds DCR-bridge oauth_delegate mint in a three-phase pipeline (prepare → exchange → finish); introduces tagged failure vocabulary, replaces bare-None key resolution with _ResolvedKey/_KeyResolutionFailure, and removes the pre-existing eager access_token extraction that blocked the bridge path. No new defects identified.
tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py	Adds 18 new mock-only tests covering: mint-and-open round-trip, fail-closed paths (no identity, no master_key, DB outage, unresolvable), refresh_token rejection before exchange, upstream lifetime edge cases (expired, sub-second, unknown, float), too-large token 502, and the resolver's team-key / blocked-key / malformed-expiry behaviours. No existing tests modified.

_{Reviews (12): Last reviewed commit: "fix(mcp): treat a positive sub-second up..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 93.24324% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
..._experimental/mcp_server/discoverable_endpoints.py	93.24%	10 Missing ⚠️

📢 Thoughts on this report? Let us know!

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 2 · PR risk: 0/10

[tin-berri]

Fixed in d8a927a. The eager access_token = token_response["access_token"] extraction ran before the dcr_bridge branch, so a missing upstream access_token raised an unhandled KeyError and _bridge_grant_from_token_response's nil guard (which maps to a clean 502) was dead code. The extraction now lives only on the non-bridge result path, after the bridge early-return, so the bridge branch reaches its 502 guard; _validate_token_response and the per-user storage step both take the full token_response dict and never used the extracted variable, so moving it changes nothing else. Regression test drives a bridge oauth_delegate exchange whose upstream response omits access_token and asserts 502; without the fix it raises KeyError

[tin-berri]

@greptileai

[tin-berri]

Rebased onto the merged #32824 (staging), and addressed the 4/5 finding in d95b4b2. _resolve_active_litellm_key gated on _active_key_user_id, which returns None both for blocked/expired keys and for valid keys that simply have no user_id, so a team-scoped or service-account key was wrongly rejected with invalid_request at the bridge token exchange. Split the active-state gate (_key_is_active: blocked and expiry only) from the user_id extraction: the mint seals the key hash rather than the user, and admission already reloads and enforces the key's live team/blocked/expiry state for a keyless-user key, so those keys can now mint. The per-user token store still resolves no user for such a key, since there is none to key a stored credential by, so that path is unchanged. Regression test caches an active key with user_id=None and asserts it resolves to hash_token(key) while the per-user extractor still returns None; before the fix the resolver returned None and no envelope could be minted

The earlier P1 (eager access_token extraction masking the 502 nil-guard) stays fixed

[tin-berri]

@greptileai

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_lit4338_delegate_token_mint (55ff3a2) with litellm_internal_staging (5fc1a3c)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (053e64e) during the generation of this report, so 5fc1a3c was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

[tin-berri]

Addressed all three of the latest findings together in bd243fa, by changing the resolvers' return types rather than adding a branch per finding. All three were the same defect: a resolution step collapsed distinct outcomes into one None or a silent default, so the error mapper could not assign a truthful status.

Each resolution step now returns a precise tagged value. Identity resolution returns a _ResolvedKey or one of no_active_key / unavailable / unresolvable, classified the way admission's _reload_admitted_key classifies the same conditions. Upstream-lifetime classification returns positive seconds, "unspecified" (absent or unparseable, which the envelope caps), or "expired" (a parseable non-positive value). Upstream-grant validation returns a typed grant or no_access_token / expired_lifetime. Thin exhaustive mappers (match plus assert_never) lift each into one eight-member _BridgeMintError taxonomy, and one _bridge_mint_error_response assigns each its RFC 6749 section 5.2 status.

Finding "infra failures mapped as client errors": a DB outage during identity resolution now returns 503 temporarily_unavailable and a missing prisma_client returns 500, matching how admission statuses the same conditions on the egress side; only a genuinely absent or invalid credential is 400. Mint and admit no longer disagree under one outage.

Finding "zero lifetime becomes one-hour envelope": an explicit non-positive expires_in is now "expired" and rejected with 502 rather than sealed into a 1h envelope around a dead bearer. An absent or unparseable lifetime stays "unspecified" and still mints a capped envelope, since that is the by-design behaviour for an upstream that omits the field.

Finding "refresh grant discards rotated tokens": the refresh_token grant is rejected in _prepare_bridge_mint with unsupported_grant_type before any exchange, so it can never rotate or consume the client's upstream refresh credential. A bridge server seals no upstream refresh_token, so the client never holds one to present; renewal is re-running authorization_code.

Because the status is chosen by an exhaustive match over each union, a new failure mode cannot be added without a matching status, so this class of wrong-status bug cannot recur silently. Each of the three fixes is mutation-checked: reverting it turns its regression test red. Full unit file green at 164 passed, and pre-commit gates (ruff, ruff-strict budget, type-discipline, basedpyright budget, e2e basedpyright, circular imports) are green.

@greptileai

[tin-berri]

bugbot run

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

[tin-berri]

Fixed in f4298dc. _classify_upstream_lifetime decided expired from int(float(expires_in)), which truncates toward zero, so a positive fractional lifetime in (0, 1) became 0 and read as elapsed. It now decides expired on the parsed numeric value, so only a genuinely non-positive lifetime is expired; a positive sub-second value clamps up to the envelope's 1s floor (whole-second granularity) rather than being rejected, and values >= 1 still truncate toward zero so the envelope never claims more life than the upstream stated. Regression covers the classifier (0.5 and 0.001 clamp to 1, -0.5 stays expired) and the mint (a 0.5s upstream lifetime mints a 200 envelope, not a 502); reverting the fix reddens both.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f4298dc. Configure here.}

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 55ff3a2. Configure here.}

[mateo-berri]

LGTM; thanks!