Add passthroughHeaders to VirtualMCPServer for header forwarding

[juancarlosm]

Summary

When a client calls vMCP with a header its backend needs — e.g. x-mcp-api-key that the backend resolves to a specific user — vMCP silently drops it. vMCP opens a fresh request to each backend and sends only its own headers, so the caller's header never arrives. Backends that authenticate per-user from a header therefore can't be used through vMCP today — only by hitting the backend directly.

This adds spec.passthroughHeaders: an allowlist of incoming header names that vMCP forwards, unchanged, to every backend it calls.

spec:
  passthroughHeaders:
    - x-mcp-api-key

A listed header is read from the client request and attached to that session's backend requests. Headers not listed are ignored. Restricted names (Host, Authorization, X-Forwarded-*, hop-by-hop) are rejected.

Approach discussed and agreed with @jerm-dro on #3958 (assigned to me there).

Closes #3958

Type of change

• New feature

Test plan

• Unit tests across all layers (identity redaction, header merge, validation, capture middleware, converter precedence)
• Integration test (test/integration/vmcp/passthrough_headers_test.go): real client → capture → backend; asserts allowlisted header forwarded, non-allowlisted dropped
• golangci-lint clean; CRD/deepcopy/docs regenerated (no drift)

Does this introduce a user-facing change?

Yes:

spec:
  passthroughHeaders: [x-litellm-api-key]

Special notes for reviewers

• Implementation: the header is captured onto the per-request *auth.Identity at the incoming-auth boundary (cloned, not mutated) and injected by the per-session backend client — it flows as an explicit parameter, not a context value, so no vmcp-anti-patterns §1/§7 coupling and the round-tripper is unchanged. This is the no-context-plumbing path discussed in vMCP: add header_passthrough outgoing auth strategy to forward dynamic incoming headers to backends #3958 once the session refactor landed; the vmcp-review audit was clean.
• Limitation: on session restore (HA), only the (iss, sub) tuple is persisted — forwarded headers aren't, same as bearer tokens. Low impact with sessionAffinity: ClientIP.

Large PR Justification

Most of the diff is required tests (~700 lines: unit + an in-process e2e) and generated code that can't be split (CRD manifests in two API versions × two chart copies, deepcopy, API docs). Hand-written source is ~240 lines. Already trimmed from ~1157 to ~1030 added lines by de-duplicating tests (coverage unchanged); the remainder is cohesive single-feature code that wouldn't be safe to split.

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

[codecov]

Codecov Report

❌ Patch coverage is 97.27273% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.74%. Comparing base (b672d82) to head (7ad9e91).

Files with missing lines	Patch %	Lines
pkg/vmcp/session/internal/backend/mcp_session.go	93.75%	1 Missing and 1 partial ⚠️
pkg/vmcp/cli/serve.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5466      +/-   ##
==========================================
+ Coverage   69.72%   69.74%   +0.01%     
==========================================
  Files         645      646       +1     
  Lines       65598    65697      +99     
==========================================
+ Hits        45737    45818      +81     
- Misses      16517    16531      +14     
- Partials     3344     3348       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Large PR justification has been provided. Thank you!

[github-actions]

✅ Large PR justification has been provided. The size review has been dismissed and this PR can now proceed with normal review.

[jerm-dro]

New direction LGTM — just a few minor notes inline.

[juancarlosm]

Thanks for the review — pushed a round addressing all the notes:

• Headers on Identity (blocker): moved to a typed unexported context key in pkg/vmcp/headerforward; added an inline note on why this is request-scoped transport plumbing, not the context-coupling anti-pattern.
• mergeForwardedHeaders precedence: now fails loud — a forwarded header that collides with a backend's static HeaderForward (plaintext or secret) returns an error at session creation instead of silently picking a winner. Propagated through createMCPClient.
• Authorization: kept allowable (the LiteLLM Zero Trust case needs it) and folded into the fail-loud-on-collision approach we agreed on. The strategy-side check (passthrough vs upstream_inject/token_exchange) is tracked as a follow-up.
• Session stability: added a second CallTool with a changed caller header, asserting the backend still sees the value captured at session creation.
• Doc + scope: reworded the PassthroughHeaders doc to match the capture/consume flow; reverted the unrelated incoming.go auth-middleware comment to its pre-PR form.

Also merged latest main (resolved serve.go/server.go — authfactory alias + both PassthroughHeaders and RateLimitMiddleware) and fixed the resulting Handler gocyclo + CRD codegen regen. CI is green.

Follow-up (separate PR): fail loud when a passthrough header collides with a backend's outgoing-auth strategy that manages the same header.