headerfwd

package
v0.75.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package headerfwd implements Spec 112 client header forwarding: capturing an allowlisted subset of the inbound MCP client HTTP headers into an immutable, value-redacting Snapshot, filtering it per upstream server, and exposing the result to the streamable-HTTP transport header func.

Two private context keys gate forwarding (FR-009). Key A carries the edge snapshot captured from the inbound request. Key B carries the per-server outbound set and is set only by core.Client.CallTool; the header func reads key B only, so connect/list/refresh paths can never forward.

Forwarded values are unverified client assertions (FR-022). This package never exposes values through formatting, JSON or logging.

Index

Constants

View Source
const (
	MaxValueBytes = 4 << 10
	MaxTotalBytes = 16 << 10
	MaxAllowNames = 32
)

Size limits (FR-012).

Variables

This section is empty.

Functions

func Denied

func Denied(name string) bool

Denied reports whether name must never be forwarded (FR-004). The comparison is case-insensitive.

func Digest

func Digest(s Snapshot) string

Digest is HMAC-SHA256 (per-process random key) over the sorted canonical name=value pairs (FR-017). The empty snapshot yields "". Never log it.

func HeaderFunc

func HeaderFunc(static map[string]string) transport.HTTPHeaderFunc

HeaderFunc returns the transport header func. It reads key B only and re-applies the deny list and static-name collision (defense in depth). It returns a fresh map on every call, or nil when there is nothing to forward.

func NormalizeNames

func NormalizeNames(names []string) (kept []string, dropped []string)

NormalizeNames is the lenient load-time counterpart of ValidateNames (FR-005b): it returns the usable names in canonical form and the names it dropped (invalid, wildcard, denied, duplicate, or beyond the 32-entry cap).

func RecordOutbound

func RecordOutbound(ctx context.Context, s Snapshot)

RecordOutbound stores the call's outbound set in the Sink carried by ctx, if any. It is a no-op without one.

func Scrub

func Scrub(text string, s Snapshot, allow []string) string

Scrub removes forwarded values from upstream-echoed text (FR-016). It is best-effort: transformed echoes (base64, URL-encoding, hashing) are not caught. allow lists additional allowlisted names; names present in s are always used.

func ScrubError

func ScrubError(err error, s Snapshot, allow []string) error

ScrubError returns err unchanged when s is empty or nothing matched; otherwise an error whose text is scrubbed. errors.Is keeps working, and errors.As returns scrubbed copies of text-carrying typed errors.

func ScrubRecord

func ScrubRecord(text string, s Snapshot) string

ScrubRecord is Scrub for recording sinks. Response truncation cuts text at a raw offset, so a forwarded value straddling the cut survives as a prefix that Scrub cannot match; ScrubRecord additionally masks such prefixes (FR-016.3).

func ValidateNames

func ValidateNames(names []string, static map[string]string) []error

ValidateNames returns one error per problem in an allowlist (FR-005a). Errors mention header names only, never values. static is the server's static headers, used for the case-insensitive collision check.

func WithOutbound

func WithOutbound(ctx context.Context, s Snapshot) context.Context

WithOutbound stores the per-server outbound set under key B. Only core.Client.CallTool should call this.

func WithSnapshot

func WithSnapshot(ctx context.Context, s Snapshot) context.Context

WithSnapshot stores the edge snapshot under key A.

Types

type Policy

type Policy struct {
	Enabled   bool
	Allow     []string
	Static    map[string]string
	Transport string // resolved: "http" or "streamable-http" forward; anything else does not
}

Policy is the live per-server forwarding policy (FR-010).

type Sink

type Sink struct {
	// contains filtered or unexported fields
}

Sink is a per-call out-parameter. The server layer creates one for a single upstream call, core.Client.CallTool records that call's outbound set into it, and the recording code reads it back to scrub the result copies it writes to activity and tool-call records (FR-016.3). It is owned by exactly one call, never stored on a long-lived object (FR-011), and prints names only.

func SinkFrom

func SinkFrom(ctx context.Context) *Sink

SinkFrom returns the Sink carried by ctx, or nil.

func WithSink

func WithSink(ctx context.Context) (context.Context, *Sink)

WithSink returns a context carrying a fresh Sink for one upstream call.

func (*Sink) Merge

func (k *Sink) Merge(o Snapshot)

Merge unions o into the Sink. code_execution uses it to fold every nested sub-call's outbound set into one execution-level set, so the execution's own records can be scrubbed with everything any sub-call forwarded.

func (*Sink) Outbound

func (k *Sink) Outbound() Snapshot

Outbound returns the recorded outbound set (empty when nothing was forwarded or the call never reached core.Client.CallTool). Nil-safe.

func (*Sink) String

func (k *Sink) String() string

String never prints values.

type Snapshot

type Snapshot struct {
	// contains filtered or unexported fields
}

Snapshot is an immutable set of canonical header name -> value. Every formatting path prints names and a count only (FR-007).

func Capture

func Capture(r *http.Request, union map[string]struct{}) Snapshot

Capture copies from r the headers whose canonical name is in union (the union of live allowlists), minus the deny list and any name the request lists in Connection. Values are cloned; r.Header is never aliased and the body is never read (FR-006, FR-012). Callers must skip Capture when forwarding is disabled.

func Outbound

func Outbound(s Snapshot, p Policy) Snapshot

Outbound computes the per-server outbound set from the edge snapshot (FR-010).

func OutboundFrom

func OutboundFrom(ctx context.Context) (Snapshot, bool)

OutboundFrom reads key B.

func SnapshotFrom

func SnapshotFrom(ctx context.Context) (Snapshot, bool)

SnapshotFrom reads key A.

func (Snapshot) Format

func (s Snapshot) Format(f fmt.State, _ rune)

Format implements fmt.Formatter so no verb can print the values.

func (Snapshot) GoString

func (s Snapshot) GoString() string

GoString implements fmt.GoStringer.

func (Snapshot) Has

func (s Snapshot) Has(name string) bool

Has reports whether name (any case) is present.

func (Snapshot) IsEmpty

func (s Snapshot) IsEmpty() bool

IsEmpty reports whether the snapshot holds no headers.

func (Snapshot) Len

func (s Snapshot) Len() int

Len is the number of headers in the snapshot.

func (Snapshot) LogValue

func (s Snapshot) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (Snapshot) MarshalJSON

func (s Snapshot) MarshalJSON() ([]byte, error)

MarshalJSON emits names and count only.

func (Snapshot) MarshalLogObject

func (s Snapshot) MarshalLogObject(enc zapcore.ObjectEncoder) error

MarshalLogObject implements zapcore.ObjectMarshaler.

func (Snapshot) Names

func (s Snapshot) Names() []string

Names returns the sorted canonical names.

func (Snapshot) String

func (s Snapshot) String() string

type TextScrubber

type TextScrubber interface {
	ScrubbedCopy(scrub func(string) string) error
}

TextScrubber is implemented by typed errors that carry upstream text (for example transport.HTTPError's Body). ScrubbedCopy returns a copy with every text field passed through scrub; it must not modify the receiver.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL