Documentation
¶
Overview ¶
Package origin provides HTTP middleware that enforces MCP Origin header validation (DNS-rebinding protection) per MCP 2025-11-25 §"Security Warning" (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#security-warning).
When the Origin header is present on an inbound request, it MUST exactly match one of the configured allowed origins. Otherwise the middleware responds with HTTP 403 and a JSON-RPC error body. Requests without an Origin header (typical for non-browser clients) are permitted through.
Index ¶
Constants ¶
const (
// MiddlewareType is the type identifier registered in the middleware factory map.
MiddlewareType = "origin"
)
Variables ¶
This section is empty.
Functions ¶
func CreateMiddleware ¶
func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
CreateMiddleware is the factory function registered in runner.GetSupportedMiddlewareFactories.
If params.AllowedOrigins is empty the factory still registers a pass-through handler so the middleware slot is occupied, but logs at Warn level to make the security-disabled state visible in operator logs. Callers that want to avoid registration entirely should skip calling this factory (see pkg/runner.prependOriginMiddleware).
func NewHandler ¶
func NewHandler(allowedOrigins []string) types.MiddlewareFunction
NewHandler returns a middleware function that enforces Origin header validation against the provided allowlist. It is the single entry point used by both the factory path (CreateMiddleware) and callers that build their middleware chain directly (e.g. `thv proxy`).
What this solves: DNS-rebinding protection per MCP 2025-11-25 §"Security Warning" — requests whose Origin header is present and not in allowedOrigins receive HTTP 403 with a JSON-RPC error body.
What this does NOT solve: CORS, CSRF token validation, authentication, or Origin-header injection via trusted reverse proxies (the caller's reverse proxy must deduplicate Origin headers upstream).
An empty allowedOrigins slice produces a pass-through handler — the caller is responsible for deciding whether that is acceptable (e.g. when bind is loopback-only and the caller derived an allowlist via ResolveAllowedOrigins).
Matching rules: exact match on byte representation except that the scheme and host portions of the Origin value are lowercased (RFC 6454 §4: scheme and host are ASCII-case-insensitive). Configured allowlist entries are canonicalized once at construction time.
func ResolveAllowedOrigins ¶
ResolveAllowedOrigins picks the effective Origin allowlist for a proxy listener. Resolution order:
- If explicit is non-empty, use it verbatim.
- Otherwise, if host is a loopback IP or the string "localhost", and port is valid, return loopback-only defaults (http://localhost:PORT, http://127.0.0.1:PORT, http://[::1]:PORT).
- Otherwise, return nil — operators exposing the proxy publicly must configure an explicit allowlist.
Shared by the runner middleware-config helper (pkg/runner) and the standalone `thv proxy` command to keep the default-derivation logic in one place; exported because the `thv proxy` call site is outside the runner package and cannot reach an internal helper.
What this does NOT solve: it does not validate that `explicit` entries are well-formed Origin values. Callers that pass operator-supplied slices must rely on the middleware's canonical matching to either accept or reject malformed entries at request time (they will simply fail to match).
Types ¶
type FactoryMiddleware ¶
type FactoryMiddleware struct {
// contains filtered or unexported fields
}
FactoryMiddleware wraps origin-validation as a factory-pattern middleware.
func (*FactoryMiddleware) Close ¶
func (*FactoryMiddleware) Close() error
Close releases any resources held by the middleware.
func (*FactoryMiddleware) Handler ¶
func (m *FactoryMiddleware) Handler() types.MiddlewareFunction
Handler returns the middleware function used by the proxy.
type MiddlewareParams ¶
type MiddlewareParams struct {
// AllowedOrigins is the exact-match allowlist of acceptable Origin values.
// An empty list disables the middleware (requests pass through unchanged).
AllowedOrigins []string `json:"allowed_origins"`
}
MiddlewareParams holds the parameters for the origin middleware factory.
Source Files