runtime

type ClientCertMode uint8

type Config struct {
	Gateway    ListenerConfig
	Management ListenerConfig
	Deps       Deps
}

type Deps struct {
	Registry     *registry.Registry
	Catalog      *catalog.Catalog
	Keys         authn.KeyResolver
	Introspector authn.Introspector
	Replay       *senderconstraint.ReplayCache
	// Sink receives sanitized observe records. A nil sink drops records (still
	// bounded). Sink failure NEVER permits a denied request or a decision-point
	// operation, and must not block shutdown.
	Sink Sink
	// Policy is the OPTIONAL capability-local policy provider (PR-6). When nil, the
	// listener keeps the PR-5 observe-only disposition for decision-point methods.
	// When set, decision-point methods are evaluated against the capability-local
	// policy snapshot (decision-only — never an upstream/credential/broker call); a
	// missing snapshot fails closed with MCP.POLICY.SNAPSHOT_UNAVAILABLE, never a
	// permissive fall-back.
	Policy PolicyProvider
	// Inspection is the OPTIONAL capability-local inspection provider (PR-7). When
	// nil, decision-point methods keep the pre-inspection path (byte-identical). When
	// set, a Gateway tools/call is semantically inspected (schema/DLP/destination)
	// BEFORE policy evaluation; a hard security failure blocks regardless of the
	// policy action, and an ALLOW_WITH_REDACTION obligation is satisfied by a
	// re-validated transform — still decision-only (no upstream/credential/broker
	// call, execution_state stays not_implemented).
	Inspection InspectionProvider
	// Events is the OPTIONAL capability-scoped PR-8 durable decision-event provider.
	// When nil, the pipeline keeps the PR-7 decision-only path byte-identically (no
	// event committed, no denial routed). When set, an ALLOW-class decision-point
	// outcome durably commits a sanitized decision event before the (still
	// not-implemented) response — a critical operation whose event cannot commit
	// fails closed — and auth/authorization denials are routed into the isolated
	// denial lane. It never causes an upstream/credential/broker call.
	Events EventProvider
	// Executor is the OPTIONAL capability-local guarded-execution provider (PR-11).
	// When nil, the pipeline keeps the PR-8 decision-only path byte-identically
	// (execution_state stays not_implemented). When set — only for the Gateway
	// capability, and only after rollout distribution arms it — a decision-point
	// outcome is handed to the rollout-mode executor AFTER inspection + policy have
	// run, which resolves the effective mode disposition (record-only / execute /
	// block) and, for an in-scope executing mode, performs the real guarded upstream
	// tools/call (credential broker + PR-8 commit-before-materialization + upstream
	// client + response DLP). A nil executor is the disabled-by-default posture.
	Executor ExecutionProvider
	// Clock is injected for deterministic tests; nil ⇒ time.Now.
	Clock func() time.Time
}

type Disposition uint8

type EventProvider interface {
	CommitDecision(f events.DecisionFacts) (spool.CommitReceipt, error)
	ObserveDenial(in events.DenialInput)
	WriteAllowedCritical(cap evmodel.Capability) bool
}

type ExecInput struct {
	Capability   protocol.Capability
	Method       string
	MessageID    jsonrpc.ID
	RawParams    []byte
	Decision     policy.Decision
	Input        policy.DecisionInput
	Inspection   *inspection.Result // nil when inspection did not run
	Identity     *identity.ResolvedContext
	Server       *registry.ServerRecord // resolved server record (nil for tools/list on management)
	SnapshotHash string
	Now          time.Time

	// ToolStillCurrent re-resolves the decision's tool against the LIVE catalog and
	// reports whether it still carries the fingerprint the decision was computed
	// against. It is called by the executor at the LAST moment before the
	// irreversible upstream call.
	//
	// The check at the top of dispatchExecute NARROWS the decision/execution TOCTOU
	// window (OVN-09); it does not close it. After that check the executor still
	// commits durable evidence, plans credentials and fetches provider material —
	// all of which can block — while a concurrent execution.Discovery -> catalog
	// Ingest publishes a new snapshot. Only a re-check adjacent to the side effect
	// makes "the tool the decision was about" and "the tool being called" the same
	// tool.
	//
	// nil ⇒ no re-check (a caller with no catalog seam); the entry check still
	// applies. It returns a bool rather than an error so the executor maps it to
	// exactly one reason and cannot mistake a drift refusal for a transport fault.
	ToolStillCurrent func() bool
}

type ExecOutput struct {
	Status          int
	Disposition     Disposition
	Reason          mcperr.Reason
	ResponseBody    []byte
	ExecutionState  string // "executed" | "not_implemented" | "blocked" | "shadow_recorded"
	EvaluatedAction string
	EffectiveAction string
	ShadowOverride  bool
	HardFailure     bool
	Executed        bool
}

type ExecutionProvider interface {
	// Execute runs the guarded rollout-mode path and returns the terminal result +
	// the observation fields to record. It performs its OWN durable
	// commit-before-side-effect; the runtime does not pre-commit for this path.
	Execute(ctx context.Context, in ExecInput) ExecOutput
}

type HealthSnapshot struct {
	Capability         string
	ListenerID         string
	Phase              Phase
	AcceptedConns      int64
	RejectedConns      int64
	RequestsTotal      int64
	RequestsRejected   int64
	KernelTerminal     int64
	ObserveOnly        int64
	RequestsExecuted   int64
	ActiveSessions     int64
	Queued             int64
	InFlight           int64
	Timeouts           int64
	AuthFailures       int64
	AmbiguousHeaders   int64
	HostOriginFailures int64
	AdmissionRejected  int64
	ShutdownCancels    int64
	ObserveDrops       int64
}

type InspectionProvider interface {
	InspectionProfile(capNS protocol.Capability) (inspection.Profile, bool)
}

type LimitConfig struct {
	MaxConns      int // accepted connections
	MaxConcurrent int // concurrent in-flight requests (worker pool size)
	QueueDepth    int // admission queue depth beyond the workers
	// MaxSessions mirrors the kernel bound for the listener-facing config; the cap
	// is ENFORCED by internal/mcp/session.Manager via ListenerConfig.SessionLimits.
	MaxSessions int
	// MaxOutstanding mirrors the kernel bound; outstanding-request accounting is
	// ENFORCED per (session, direction) in internal/mcp/session/ops.go.
	MaxOutstanding int
	MaxHeaderBytes int // request header bytes
	MaxBodyBytes   int // request body bytes
	// MaxResponseBytes: the observe runtime generates every response itself from
	// bounded internal values, so the attacker-sized case is the UPSTREAM leg,
	// where internal/mcp/upstreamclient enforces its own bound.
	MaxResponseBytes int
	AuthConcurrency  int // concurrent authentications
	DPoPConcurrency  int // concurrent DPoP verifications
	// MaxObservations is RESERVED: observe records are emitted synchronously on the
	// request goroutine, so in-flight records cannot exceed MaxConcurrent. It
	// becomes meaningful only if the sink becomes asynchronous.
	MaxObservations int
	// AdmissionBudget is RESERVED AND UNENFORCED (RISK-026). It is documented as a
	// per-source budget, but admission has no source identity and runs before
	// authentication, so nothing consumes it. Wiring it requires a
	// deployment-topology decision — see
	// docs/design/mcp/ADR-PROPOSAL-mcp-admission-fairness.md. The Limits ownership
	// wall (limits_ownership_test.go) fails the build if this is silently read.
	AdmissionBudget int
	// CleanupPerOp is RESERVED: the sweeper walks sessions the manager already caps
	// at MaxSessions, so the scan is bounded without it. (The credential broker's
	// MaxCleanupPerOp is a DIFFERENT, enforced bound.)
	CleanupPerOp      int
	ReadHeaderTimeout time.Duration // slowloris: header read deadline
	ReadTimeout       time.Duration // full request read deadline
	WriteTimeout      time.Duration // response write deadline
	IdleTimeout       time.Duration // idle keep-alive deadline
	// HandshakeTimeout: net/http bounds the TLS handshake itself from
	// max(ReadHeaderTimeout, ReadTimeout), which are set from this same set.
	HandshakeTimeout time.Duration
	RequestDeadline  time.Duration // absolute per-request deadline
	SessionTTL       time.Duration // idle session expiry
	ShutdownTimeout  time.Duration // graceful-shutdown budget
}

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

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

type ListenerConfig struct {
	Enabled        bool
	Capability     protocol.Capability
	BindAddress    string // interface/IP to bind (e.g. "127.0.0.1"); empty ⇒ invalid unless AllowWildcard
	Port           int
	TLS            *tls.Config // caller-supplied server TLS config (certs already loaded); never mutated
	ClientCertMode ClientCertMode
	AllowedHosts   []string // Host/:authority allowlist (mandatory, non-empty when enabled)
	AllowedOrigins []string
	RequireOrigin  bool
	AuthConfig     authn.CapabilityAuthConfig // this capability's immutable PR-3 config
	Limits         Limits                     // this capability's immutable runtime bounds (listener/HTTP bounds)
	// SessionLimits are the PR-1 kernel session/wire bounds for this capability's
	// dedicated session.Manager (distinct from the listener HTTP bounds above). A
	// zero value (MaxSessions()==0) is resolved to the capability default at
	// construction so an operator need not restate the kernel bounds.
	SessionLimits limits.Limits
	// AllowWildcard permits a 0.0.0.0/:: bind. Off by default — a wildcard bind is
	// rejected unless explicitly allowed by the accepted config.
	AllowWildcard bool
	// AllowInsecure permits a non-TLS listener. It is a TEST/loopback seam only
	// (httptest supplies its own TLS); a non-test deployment requires TLS. It never
	// weakens an enabled TLS config and is documented as the ownership boundary for
	// the (later-slice) production TLS wiring.
	AllowInsecure bool
	// Metadata is the OPTIONAL published OAuth 2.0 Protected Resource Metadata (RFC
	// 9728) for this capability. When set, the listener serves the bounded PUBLIC
	// document at its well-known path and advertises it in the WWW-Authenticate
	// challenge on a 401. Nil ⇒ no metadata document and no challenge header (the
	// pre-QUAL-1 behavior, byte-identical). It never carries a secret — only the
	// public resource identifier and authorization-server issuer URLs.
	Metadata *ProtectedResourceMetadata
}

type MessageClass uint8

type ObserveRecord struct {
	ObservationID string              // listener-generated, monotonic
	Capability    protocol.Capability // Gateway / Management
	ListenerID    string              // stable listener identity
	ProtocolVer   string              // negotiated protocol version, if any
	Class         MessageClass        // request / notification / response
	Method        string              // admitted method name (from the closed allow-list only)
	PrincipalHash string              // one-way digest of the resolved principal, if authenticated
	ClientID      string              // OAuth client id (safe), if present
	AgentID       string              // agent id (safe), if present
	ServerID      string              // Gateway server id from the route, if present
	ToolRefHash   string              // one-way hash of the tool ref (never the raw name)
	CatalogState  string              // catalog eligibility label (carried, never promoted)
	AuthResult    string              // "ok" / stable failure reason code
	Disposition   Disposition         // terminal disposition
	Reason        mcperr.Reason       // stable rejection/observe reason (ReasonNone on success)
	HostReason    string              // hostcheck reason (stable string), if host/origin failed
	SessionDigest string              // digest of the session id (never raw attacker input)
	Start         time.Time           // request start
	DurationMS    int64               // bounded duration in ms
	RequestBytes  int                 // bounded body-byte count
	RuntimeRev    uint64              // runtime configuration revision

	// PR-6 policy-decision fields (set only for a decision-point method evaluated
	// against a policy snapshot). They carry safe metadata only — the policy action,
	// stable reason code, matched rule id, policy revision and the execution state.
	PolicyAction   string // policy action (e.g. "ALLOW", "DENY", "QUARANTINE"), if evaluated
	PolicyReason   string // stable policy reason code (e.g. "MCP.POLICY.NO_MATCH_DEFAULT_DENY")
	MatchedRule    string // matched rule id, if any
	PolicyRevision uint64 // policy snapshot revision that produced the decision
	ExecutionState string // "not_implemented" for an ALLOW-class decision in PR-6

	// PR-7 inspection fields (set only for an inspected Gateway tools/call). Safe
	// metadata only — never arguments, output, secrets, URLs or credentials.
	InspectionRevision  uint64 // inspection profile revision
	InspectionSchema    string // schema status label ("valid"/"invalid"/"unsupported"/…)
	InspectionDestClass string // destination class label ("public"/"private"/"metadata"/…)
	InspectionDisp      string // worst inspection disposition ("pass"/"label"/"redact"/"block")
	SecretFound         bool   // a secret classification was found
	PIIFound            bool   // a PII/financial classification was found
	InjectionSuspected  bool   // injection labeling flagged content
	RedactionApplied    bool   // an ALLOW_WITH_REDACTION transform was produced
	RedactionProfile    string // opaque redaction-profile ref, if applied
	TransformedHash     string // transformed canonical hash, if redaction applied
}

type Outcome struct {
	Status       int
	Disposition  Disposition
	Reason       mcperr.Reason
	HostReason   string
	RetainStream bool // always false
	ResponseBody []byte
	SessionID    string // set on a successful initialize (MCP-Session-Id to return)
	NewSession   bool
	Record       ObserveRecord
}

type Phase uint32

type PolicyProvider interface {
	PolicySnapshot(capNS protocol.Capability) *policy.Snapshot
}

type ProtectedResourceMetadata struct {
	// Resource is the exact canonical resource identifier a client must request a
	// token audience for (identical to the capability's CapabilityAuthConfig
	// CanonicalResource — the audience validator enforces the same string).
	Resource string
	// AuthorizationServers are the issuer identifiers (URLs) whose tokens this
	// resource accepts.
	AuthorizationServers []string
	// WellKnownPath is the exact request path this listener serves the document at
	// (e.g. "/.well-known/oauth-protected-resource/mcp/gateway").
	WellKnownPath string
	// MetadataURL is the absolute URL of WellKnownPath, advertised verbatim in the
	// WWW-Authenticate challenge's resource_metadata parameter.
	MetadataURL string
	// ResourceName is an optional human-readable label (safe, non-secret).
	ResourceName string
}

type Request struct {
	HTTPMethod       string              // GET / POST / DELETE / ...
	Capability       protocol.Capability // the capability the route resolved to
	Host             string              // Host or HTTP/2 :authority (re-extracted per request/stream)
	OriginPresent    bool
	Origin           string
	Path             string // request path (capability/server routing)
	ServerID         string // Gateway: opaque server id extracted from the route
	SessionID        string // MCP-Session-Id (may be empty)
	HasSession       bool
	ProtocolVersion  string // MCP-Protocol-Version header value (may be empty)
	HasVersionHeader bool

	// Credential material — headers ONLY.
	AuthorizationHeaders []string // every Authorization header value (duplicates rejected)
	BearerInQuery        bool     // a bearer credential was seen in the query string (forbidden)
	DPoPProof            string
	HasDPoP              bool

	// mTLS — the thumbprint is derived by the listener from the VERIFIED peer
	// certificate; a client-supplied thumbprint header is never trusted.
	PeerCertThumbprint string
	CanonicalURI       string // absolute request URI for the DPoP htu binding

	// Body carries a pre-read request body (unit-test path). The live listener leaves
	// Body nil and supplies BodyReader instead, so the pipeline reads the body LAZILY
	// — only after Host/Origin (per request/stream), method dispatch, path/capability
	// and registry resolution have passed. A cross-origin/foreign-route/unsupported-
	// method request is therefore rejected WITHOUT ever buffering its body.
	Body       []byte
	BodyReader io.Reader // bounded reader (live path); read at step 9 only for an admitted POST route
}

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

type Sink interface {
	Observe(rec ObserveRecord) error
}