Tighten HeaderForward test coverage and docs

Fix the inverted chain-ordering comments on mcp_session.go's transport
chain assembly and on headerForwardRoundTripper.RoundTrip. The outermost
wrapper runs FIRST on the outbound request, so header-forward injects
onto a request without auth/identity headers and the inner stages then
overwrite with Set(). The previous wording claimed the opposite. The
production behaviour is unchanged; only the doc text moved.

Replace headerCapturingBackend with the shared fakeBackend by adding
headersByMethod / headersFor and a tools/call handler. This removes a
near-duplicate fake server in the session backend tests.

Extend the header-forward test to cover overlap precedence (an inner
auth stage's value wins on the wire when both sides set the same name)
and AddHeadersFromSecret end-to-end via t.Setenv against the env-backed
secrets provider. Add a restricted-name rejection case to prove the
resolveHeaderForward guard is wired into the session-side connector.

Trim diff-narrating comments from the test file: drop the past-tense
narrative about which PR fixed what and describe the assertions
instead. The issue reference (#5289) is kept on the test docstring.

Author: lorr1

pkg/vmcp/headerforward/transport.go

@@ -35,9 +35,13 @@ type headerForwardRoundTripper struct {
 }
 
 // RoundTrip injects the pre-resolved headers onto a clone of the request and
-// delegates to the wrapped transport. Headers already present on the request
-// are left untouched so inner transports (auth, identity, trace) can always
-// override user-supplied values for the same name.
+// delegates to the wrapped transport. Names already present on the inbound
+// request are skipped — this preserves any header the *caller* set on the
+// request before invoking the round-tripper chain. Inner (closer to the wire)
+// transports run AFTER this one and use Set() unconditionally, so on any
+// overlapping name those stages still win on the wire. Restricted names are
+// blocked at resolve time, so user-supplied config cannot reach this point
+// for Host, hop-by-hop, or X-Forwarded-* anyway.
 func (h *headerForwardRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
 	if len(h.headers) == 0 {
 		return h.base.RoundTrip(req)

pkg/vmcp/session/internal/backend/mcp_session.go

@@ -273,10 +273,15 @@ func createMCPClient(
 
 	slog.Debug("Applied authentication strategy", "strategy", strategy.Name(), "backendID", target.WorkloadID)
 
-	// Build shared transport chain: auth → identity propagation → header forward.
-	// HeaderForward is the outermost stage so inner stages (auth, identity) win
-	// on any overlapping header name — matching the ordering in
-	// headerForwardRoundTripper.RoundTrip, which skips names already set.
+	// Build shared transport chain (innermost first → outermost):
+	//   http.DefaultTransport → authRoundTripper → identityRoundTripper → headerForwardRoundTripper
+	// On an outbound request, the outermost stage runs first: header-forward
+	// injects its headers onto a request that does not yet carry auth/identity
+	// headers, then inner stages run and call Set() unconditionally so any
+	// overlapping name they care about (Authorization, identity headers) wins on
+	// the wire. Restricted header names (Host, hop-by-hop, X-Forwarded-*) are
+	// rejected at resolve time by resolveHeaderForward, so user-supplied
+	// HeaderForward cannot inject them in the first place.
 	// The per-transport sections below may add a size-limiting wrapper on top.
 	base := http.RoundTripper(http.DefaultTransport)
 	base = &authRoundTripper{

pkg/vmcp/session/internal/backend/mcp_session_capabilities_test.go

@@ -54,6 +54,11 @@ type fakeBackend struct {
 	// resources/list failure.
 	mu          sync.Mutex
 	methodCalls map[string]int
+
+	// headersByMethod records the inbound request headers keyed by JSON-RPC
+	// method name. Tests asserting transport-chain behavior (e.g. HeaderForward)
+	// use headersFor(method) to inspect the headers a backend actually saw.
+	headersByMethod map[string]http.Header
 }
 
 type jsonRPCError struct {
@@ -68,6 +73,7 @@ func newFakeBackend(t *testing.T, fb *fakeBackend) string {
 	t.Helper()
 	fb.t = t
 	fb.methodCalls = make(map[string]int)
+	fb.headersByMethod = make(map[string]http.Header)
 
 	mux := http.NewServeMux()
 	mux.HandleFunc("/mcp", fb.handle)
@@ -83,6 +89,19 @@ func (f *fakeBackend) callCount(method string) int {
 	return f.methodCalls[method]
 }
 
+// headersFor returns a clone of the inbound HTTP headers recorded for the most
+// recent JSON-RPC request with the given method, or nil if no such request was
+// seen. Cloning under the mutex keeps the caller safe from concurrent writes.
+func (f *fakeBackend) headersFor(method string) http.Header {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	h := f.headersByMethod[method]
+	if h == nil {
+		return nil
+	}
+	return h.Clone()
+}
+
 // handle implements the JSON-RPC subset needed for backend init. The
 // streamable-HTTP transport sends POST requests with Accept:
 // application/json, text/event-stream — we always reply with
@@ -117,6 +136,7 @@ func (f *fakeBackend) handle(w http.ResponseWriter, r *http.Request) {
 
 	f.mu.Lock()
 	f.methodCalls[msg.Method]++
+	f.headersByMethod[msg.Method] = r.Header.Clone()
 	f.mu.Unlock()
 
 	// Notifications (no id, e.g. notifications/initialized) get an empty 202.
@@ -148,6 +168,16 @@ func (f *fakeBackend) handle(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		f.writeResult(w, msg.ID, map[string]any{"prompts": f.prompts})
+	case string(mcp.MethodToolsCall):
+		// Minimal CallToolResult with a single text content. Tests that exercise
+		// the post-initialize transport chain (e.g. HeaderForward) need a method
+		// they can invoke after Initialize completes; tools/call is the cheapest.
+		f.writeResult(w, msg.ID, map[string]any{
+			"content": []map[string]any{
+				{"type": "text", "text": "ok"},
+			},
+			"isError": false,
+		})
 	default:
 		f.writeError(w, msg.ID, &jsonRPCError{code: mcp.METHOD_NOT_FOUND, message: "Method not found"})
 	}