refactor(mcp): extract the dcr_bridge token flow into bridge_token_flow.py

[tin-berri]

Relevant issues

Linear ticket

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

Screenshots / Proof of Fix

This is a pure move-refactor with zero behavior change, so there is no runtime behavior to demonstrate; the proof is that nothing that moved changed. Verified at commit a30c25a

• the relocated code is byte-verbatim against the pre-refactor file for 25 of the 26 moved symbols; the only delta is one annotation quoted as a forward reference (bridge_identity: _BridgeAuthorizationCode | None becomes "_BridgeAuthorizationCode | None"), because _BridgeAuthorizationCode is now imported under TYPE_CHECKING to avoid a cycle
• python -c "import ...discoverable_endpoints, ...bridge_token_flow" succeeds, so there is no circular import; the new module imports nothing from discoverable_endpoints at runtime
• the full existing suite passes unchanged (566 tests across test_discoverable_endpoints, the faults suite, and outbound_credentials)
• the test patch targets for the moved internals were repointed to the new module and independently verified to still apply: flipping every repointed patch back to discoverable_endpoints fails the suite (32 tests), so no mock is silently inert

Type

🧹 Refactoring

Changes

discoverable_endpoints.py had grown to 2695 lines mixing the FastAPI OAuth route handlers with the dcr_bridge token-flow logic, against the repo's no-monster-files and deliberate-file-structure conventions. This extracts the bridge token flow into a dedicated bridge_token_flow.py

Moved: the litellm-key and user resolution (_resolve_active_litellm_key, _reload_active_key_by_hash, _reload_active_user_by_id, _key_is_active, _ResolvedKey), the SCIM revalidation gate (_key_owner_scim_deactivated, _revalidate_active_subject), and the mint and refresh envelope flow (_prepare_bridge_mint, _prepare_bridge_refresh, _finish_bridge_mint, _bridge_grant_from_token_response, _upstream_refresh_credential, _mint_refresh_envelope_value, _classify_upstream_lifetime) with their _Bridge* types and error mappers, 26 symbols in all. The original extraction moved 27; the rebase onto the fault-taxonomy work from #33113 drops _upstream_oauth_error, which that work deleted in favor of classify_upstream_token_rejection

Stayed: the @router OAuth handlers (authorize, token, callback, register, discovery), the shared exchange_token_with_server orchestrator, and the fault-taxonomy helpers it uses (_token_credential_source and the faults module imports). The handlers import the 7 bridge helpers they still use from the new module. The envelope crypto was already separated under outbound_credentials/

Net: discoverable_endpoints.py drops ~690 lines and the bridge flow becomes a cohesive, separately-testable module

QA runbook

The test-file change is mechanical only: from ...discoverable_endpoints import <moved> and patch("...discoverable_endpoints.<moved>") were repointed to bridge_token_flow for the relocated symbols. This now includes the direct imports of _extract_user_id_from_request, which the Greptile review flagged as the one symbol left importing from the old module. No test assertions or coverage changed, so there is nothing new to reproduce by hand; the existing suite is the behavioral contract this refactor is checked against

---

Note

Low Risk
Structural move with no intended behavior change; OAuth token mint/refresh paths are auth-sensitive but the PR description claims byte-verbatim relocation and full test suite pass.

Overview
Moves the DCR-bridge oauth_delegate token pipeline out of discoverable_endpoints.py into a new bridge_token_flow.py (~690 lines), so route handlers stay separate from identity resolution and mint/refresh logic.

What moved: LiteLLM key/user resolution (_resolve_active_litellm_key, _reload_active_*, _key_is_active), SCIM revalidation on refresh (_revalidate_active_subject, _key_owner_scim_deactivated), upstream grant parsing (_classify_upstream_lifetime, _bridge_grant_from_token_response), and the three-phase mint flow (_prepare_bridge_mint, _prepare_bridge_refresh, _finish_bridge_mint, refresh envelope helpers) plus _Bridge* types and OAuth error mapping.

What stayed in discoverable_endpoints: FastAPI OAuth routes and exchange_token_with_server, which now imports seven bridge helpers from the new module. _BridgeAuthorizationCode is only referenced under TYPE_CHECKING in the new file to avoid a runtime import cycle.

Tests repoint imports and patch(...) targets from discoverable_endpoints to bridge_token_flow for the relocated symbols; assertions are unchanged.

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

[greptile-apps]

Greptile Summary

This PR extracts the DCR-bridge token flow (~690 lines) from the oversized discoverable_endpoints.py into a new focused module bridge_token_flow.py, with no behavior change. The seven symbols still needed by discoverable_endpoints are re-imported from the new module, and the test file is mechanically repointed.

• bridge_token_flow.py receives the litellm key and user resolution helpers, SCIM revalidation gate, and the three-phase mint/refresh pipeline (26 symbols). The only non-verbatim delta is the _BridgeAuthorizationCode annotation on _prepare_bridge_mint being quoted as a forward reference to avoid a circular import.
• All moved patch targets in the test are correctly redirected to bridge_token_flow.*; the one patch that still targets discoverable_endpoints._extract_user_id_from_request (line 5654) is intentionally correct — exchange_token_with_server calls that name from the discoverable_endpoints namespace, so patching there is the right place.

Confidence Score: 5/5

Pure code-move refactor with no logic changes; the new module is byte-verbatim from the original except for one intentional forward-reference annotation, and the test suite is mechanically repointed with no weakened assertions.

Every moved symbol is functionally identical to its pre-refactor counterpart. The circular-import handling is correct and well-justified. The mock patch targets in the test file are correctly resolved.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/bridge_token_flow.py	New module: 694-line extraction of the DCR-bridge token flow from discoverable_endpoints.py; code is byte-verbatim from the source except the _BridgeAuthorizationCode forward-reference annotation, which is intentional to break a circular import.
litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py	~690 lines removed (the bridge flow), replaced with seven named imports from bridge_token_flow; the remaining handlers and exchange_token_with_server are unchanged.
tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py	Mechanical repointing of direct imports and patch targets for moved symbols to bridge_token_flow; the _extract_user_id_from_request patch at line 5654 correctly remains in the discoverable_endpoints namespace since exchange_token_with_server calls it from there.

_{Reviews (2): Last reviewed commit: "refactor(mcp): extract the dcr_bridge to..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 87.59124% with 34 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...roxy/_experimental/mcp_server/bridge_token_flow.py	87.54%	34 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_bridge_token_flow_module (a30c25a) with litellm_internal_staging (b200d66)}

[tin-berri]

@greptileai

[tin-berri]

bugbot run

[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 a30c25a. Configure here.}

[mateo-berri]

LGTM; thanks!