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 96.66667% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.27%. Comparing base (87fa2ac) to head (508a72a).

Files with missing lines	Patch %	Lines
pkg/vmcp/cli/serve.go	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5466      +/-   ##
==========================================
+ Coverage   69.23%   69.27%   +0.04%     
==========================================
  Files         636      637       +1     
  Lines       64724    64821      +97     
==========================================
+ Hits        44810    44905      +95     
- Misses      16605    16607       +2     
  Partials     3309     3309              

☔ 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.