vMCP: fail loud when a passthrough header collides with a backend's outgoing-auth strategy

[juancarlosm]

Follow-up to #5466. That PR makes mergeForwardedHeaders fail loud when a passthroughHeaders name collides with a backend's static HeaderForward config (plaintext or secret). This issue covers the other half of the original Authorization footgun: a passthrough header whose canonical name is also managed by the backend's outgoing-auth strategy.

Problem

The transport chain runs header-forward (outer) → authRoundTripper (inner). The strategy's Authenticate calls Header.Set(...) and silently overwrites any forwarded value with the same name:

• upstream_inject / token_exchange / aws_sts / obo → set Authorization
• header_injection → sets its configured HeaderName

So forwarding Authorization (or a header_injection name) to such a backend is silently clobbered — no error, no warning.

The legitimate LiteLLM Zero Trust case is unaffected: those backends run the unauthenticated strategy, which manages no headers, so there is no collision.

Desired

Detect — at config validation or session creation — that a passthroughHeaders name collides with a header the backend's resolved outgoing strategy manages, and fail loud with a clear message. Same philosophy as the static-config collision check already in #5466.

Sketch

Add a way for a strategy to declare the header names it manages (e.g. ManagedHeaders() on the outgoing Strategy interface — header_injection returns its configured name; the bearer strategies return Authorization; unauthenticated returns none). Cross-check against cfg.PassthroughHeaders where the backend strategy is resolved.

Ref: #5466 discussion.

[juancarlosm]

Sketching an approach here before anyone picks this up — feedback welcome.

Goal: fail loud when a passthroughHeaders name is also managed by a backend's resolved outgoing-auth strategy (the strategy's authRoundTripper runs inner and silently Sets over the forwarded value).

Managed-header mapping (what each strategy Sets):

Strategy	Manages
unauthenticated	—
upstream_inject / token_exchange / aws_sts / obo	Authorization
header_injection	its configured HeaderName

Proposed approach:

1. Add ManagedHeaders(strategy *BackendAuthStrategy) []string to the outgoing Strategy interface, returning canonical names the strategy will set. Keeps the knowledge next to each Authenticate impl (single source of truth) instead of a map that drifts.
2. Cross-check at session creation (createMCPClient), right alongside the existing static-HeaderForward collision check from Add passthroughHeaders to VirtualMCPServer for header forwarding #5466 — that's where the strategy is resolved and the forwarded headers are in scope. Error: forwarded header X collides with backend Y's <strategy> outgoing-auth strategy.
3. Regenerate the strategy mock; add per-strategy ManagedHeaders unit tests + a collision-error test.

Open questions for discussion:

• Where to check — session creation (runtime, consistent with Add passthroughHeaders to VirtualMCPServer for header forwarding #5466) vs config validation. Backend strategies are resolved at runtime (discovered/inline), so the static validator doesn't have them — leaning session-creation. Acceptable that it fails on first session per misconfigured backend?
• Interface vs static map — adding an interface method touches every strategy impl + the mock. Worth it for type-safety / no-drift, or prefer a small lookup keyed by strategy type (with header_injection special-cased since it's config-dependent)?
• header_injection scope — collision only when its configured HeaderName canonical-matches a passthrough name; a backend injecting X-API-Key shouldn't block an Authorization passthrough. The interface approach handles this naturally.
• Error vs warn — keeping it a hard error (fail-loud) per the Add passthroughHeaders to VirtualMCPServer for header forwarding #5466 direction; flagging in case a warn is preferred for backwards-compat on existing configs.

[jerm-dro]

Thanks @juancarlosm for sketching this out — the ManagedHeaders() interface is the right call. One suggestion on the "where to check" open question.

I'd argue we can detect this at startup without waiting for session creation. Discovery already resolves AuthConfig for every backend up front (applyAuthConfigToBackend, discoverer.go:200/:287), so the full set of (backend, resolved strategy) pairs is in scope once aggregation completes — before any session is created.

So rather than checking in createMCPClient, I'd run the cross-check once in the post-discovery aggregation step:

• Catches both inline and discovered modes (in discovered, strategies come from the backend's MCPServer and aren't in vMCP config, so a pure config.Validate() check can't see them — but they are resolved by the time discovery finishes).
• Fails loud at startup instead of on the first session per misconfigured backend.
• Uses your ManagedHeaders() design unchanged — just called from the aggregation loop instead of createMCPClient.

Do you want to pick this up? Happy to assign you the issue.