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
- func Denied(name string) bool
- func Digest(s Snapshot) string
- func HeaderFunc(static map[string]string) transport.HTTPHeaderFunc
- func NormalizeNames(names []string) (kept []string, dropped []string)
- func RecordOutbound(ctx context.Context, s Snapshot)
- func Scrub(text string, s Snapshot, allow []string) string
- func ScrubError(err error, s Snapshot, allow []string) error
- func ScrubRecord(text string, s Snapshot) string
- func ValidateNames(names []string, static map[string]string) []error
- func WithOutbound(ctx context.Context, s Snapshot) context.Context
- func WithSnapshot(ctx context.Context, s Snapshot) context.Context
- type Policy
- type Sink
- type Snapshot
- func (s Snapshot) Format(f fmt.State, _ rune)
- func (s Snapshot) GoString() string
- func (s Snapshot) Has(name string) bool
- func (s Snapshot) IsEmpty() bool
- func (s Snapshot) Len() int
- func (s Snapshot) LogValue() slog.Value
- func (s Snapshot) MarshalJSON() ([]byte, error)
- func (s Snapshot) MarshalLogObject(enc zapcore.ObjectEncoder) error
- func (s Snapshot) Names() []string
- func (s Snapshot) String() string
- type TextScrubber
Constants ¶
const ( MaxValueBytes = 4 << 10 MaxTotalBytes = 16 << 10 MaxAllowNames = 32 )
Size limits (FR-012).
Variables ¶
This section is empty.
Functions ¶
func Denied ¶
Denied reports whether name must never be forwarded (FR-004). The comparison is case-insensitive.
func Digest ¶
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 ¶
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 ¶
RecordOutbound stores the call's outbound set in the Sink carried by ctx, if any. It is a no-op without one.
func Scrub ¶
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 ¶
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 ¶
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 ¶
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 ¶
WithOutbound stores the per-server outbound set under key B. Only core.Client.CallTool should call this.
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 (*Sink) Merge ¶
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.
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 ¶
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 OutboundFrom ¶
OutboundFrom reads key B.
func SnapshotFrom ¶
SnapshotFrom reads key A.
func (Snapshot) MarshalJSON ¶
MarshalJSON emits names and count only.
func (Snapshot) MarshalLogObject ¶
func (s Snapshot) MarshalLogObject(enc zapcore.ObjectEncoder) error
MarshalLogObject implements zapcore.ObjectMarshaler.
type TextScrubber ¶
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.