config

type AllowOnlyPolicy struct {
	Repos                interface{}    `toml:"repos" json:"repos"`
	MinIntegrity         string         `toml:"min-integrity" json:"min-integrity"`
	ToolCallLimits       map[string]int `toml:"tool-call-limits" json:"tool-call-limits,omitempty"`
	BlockedUsers         []string       `toml:"blocked-users" json:"blocked-users,omitempty"`
	RefusalLabels        []string       `toml:"refusal-labels" json:"refusal-labels,omitempty"`
	ApprovalLabels       []string       `toml:"approval-labels" json:"approval-labels,omitempty"`
	TrustedUsers         []string       `toml:"trusted-users" json:"trusted-users,omitempty"`
	EndorsementReactions []string       `toml:"endorsement-reactions" json:"endorsement-reactions,omitempty"`
	DisapprovalReactions []string       `toml:"disapproval-reactions" json:"disapproval-reactions,omitempty"`
	DisapprovalIntegrity string         `toml:"disapproval-integrity" json:"disapproval-integrity,omitempty"`
	EndorserMinIntegrity string         `toml:"endorser-min-integrity" json:"endorser-min-integrity,omitempty"`
	PromotionLabel       string         `toml:"promotion-label" json:"promotion-label,omitempty"`
	DemotionLabel        string         `toml:"demotion-label" json:"demotion-label,omitempty"`
}

type AuthConfig struct {
	// Type is the authentication type. Currently only "github-oidc" is supported.
	Type string `toml:"type" json:"type"`

	// Audience is the intended audience for the OIDC token.
	// If empty, defaults to the server URL.
	Audience string `toml:"audience" json:"audience,omitempty"`
}

type Config struct {
	// Servers maps server names to their configurations
	Servers map[string]*ServerConfig `toml:"servers" json:"servers"`

	// Guards maps guard names to their configurations
	Guards map[string]*GuardConfig `toml:"guards" json:"guards,omitempty"`

	// Gateway holds global gateway settings
	Gateway *GatewayConfig `toml:"gateway" json:"gateway,omitempty"`

	// DIFCMode specifies the guards enforcement mode: strict (default), filter, or propagate
	// strict: deny access that violates guards rules
	// filter: silently remove tools/resources that violate guards rules
	// propagate: auto-adjust agent labels on reads to allow access
	DIFCMode string `toml:"guards_mode" json:"guards_mode,omitempty"`

	// SequentialLaunch launches servers sequentially instead of in parallel
	SequentialLaunch bool `toml:"sequential_launch" json:"sequential_launch,omitempty"`

	// GuardPolicy optionally overrides per-guard policy via CLI/environment precedence.
	GuardPolicy *GuardPolicy `toml:"-" json:"-"`

	// GuardPolicySource describes where GuardPolicy was resolved from (cli|env|config|legacy).
	GuardPolicySource string `toml:"-" json:"-"`
}

type DefaultsSetter func(cfg *Config)

type EnvValidationResult struct {
	IsContainerized    bool
	ContainerID        string
	DockerAccessible   bool
	MissingEnvVars     []string
	PortMapped         bool
	StdinInteractive   bool
	LogDirMounted      bool
	ValidationErrors   []string
	ValidationWarnings []string
}

type FeatureConfig interface {
	// FeatureName returns the name of the feature for logging
	FeatureName() string
}

type GatewayConfig struct {
	// Port is the HTTP port to listen on
	Port int `toml:"port" json:"port,omitempty"`

	// AgentID is the gateway agent/session identifier.
	AgentID string `toml:"agent_id" json:"agent_id,omitempty"`

	// APIKey is a deprecated alias for AgentID.
	APIKey string `toml:"api_key" json:"api_key,omitempty"`

	// Domain is the gateway domain for external access
	Domain string `toml:"domain" json:"domain,omitempty"`

	// StartupTimeout is the maximum time (seconds) to wait for server startup
	StartupTimeout int `toml:"startup_timeout" json:"startup_timeout,omitempty"`

	// ToolTimeout is the maximum time (seconds) to wait for tool execution
	ToolTimeout int `toml:"tool_timeout" json:"tool_timeout,omitempty"`

	// KeepaliveInterval is the interval (seconds) for sending keepalive pings to HTTP
	// backends. This prevents long-running sessions from being expired by the remote
	// server's idle timeout (typically 30 minutes). Set to -1 to disable keepalive
	// pings entirely (useful when higher-level timeouts manage session lifecycle).
	// Default: 1500 (25 minutes)
	KeepaliveInterval int `toml:"keepalive_interval" json:"keepalive_interval,omitempty"`

	// PayloadDir is the directory for storing large payloads
	PayloadDir string `toml:"payload_dir" json:"payload_dir,omitempty"`

	// PayloadPathPrefix is the path prefix to use when returning payloadPath to clients.
	// This allows remapping the host filesystem path to a path accessible in the client/agent container.
	// If empty, the actual filesystem path (PayloadDir) is returned.
	// Example: If PayloadDir="/tmp/jq-payloads" and PayloadPathPrefix="/workspace/payloads",
	// then payloadPath will be "/workspace/payloads/{sessionID}/{queryID}/payload.json"
	PayloadPathPrefix string `toml:"payload_path_prefix" json:"payload_path_prefix,omitempty"`

	// PayloadSizeThreshold is the size threshold (in bytes) for storing payloads to disk.
	// Payloads larger than this threshold are stored to disk, smaller ones are returned inline.
	// Default: 524288 bytes (512KB)
	PayloadSizeThreshold int `toml:"payload_size_threshold" json:"payload_size_threshold,omitempty"`

	// URLDomainAudit enables URL domain observation in middleware/guard logging.
	// This is currently toggled via CLI/environment and not loaded from config files.
	URLDomainAudit bool `toml:"-" json:"-"`

	// TrustedBots is an optional list of additional bot usernames that should be treated
	// as trusted. Objects authored by these bots receive "approved" integrity regardless
	// of their author_association. This list is merged with the guard's built-in trusted
	// bot list and is purely additive (it cannot remove built-in trusted bots).
	// Example values: "copilot-swe-agent[bot]", "my-org-bot[bot]"
	TrustedBots []string `toml:"trusted_bots" json:"trusted_bots,omitempty"`

	// ForcePublicRepos controls whether the gateway automatically overrides the
	// allow-only policy to repos="public" when the GITHUB_REPOSITORY repo is public.
	// nil / omitted → enabled by default (auto-force when repo is public)
	// true  → explicitly enabled
	// false → disabled (opt-out via private-to-public-flows: allow)
	// Corresponds to env var MCP_GATEWAY_FORCE_PUBLIC_REPOS.
	ForcePublicRepos *bool `toml:"force_public_repos" json:"forcePublicRepos,omitempty"`

	// SinkVisibilityExemptServers lists server IDs that are exempt from the
	// default sink-visibility="public" enforcement. By default, all non-safe-outputs
	// write-sink servers are assigned sink-visibility="public" (security-by-default).
	// Servers in this list retain their configured (or omitted) sink-visibility as-is.
	// Use ["*"] to exempt all servers (equivalent to disabling the default).
	// Set by the compiler when private-to-public-flows is configured in frontmatter.
	SinkVisibilityExemptServers []string `toml:"sink_visibility_exempt_servers" json:"sinkVisibilityExemptServers,omitempty"`

	// Tracing holds OpenTelemetry OTLP tracing configuration (legacy TOML key).
	// New configurations should use the opentelemetry key (spec §4.1.3.6).
	// When Endpoint is set, traces are exported to the specified OTLP endpoint.
	// When omitted or Endpoint is empty, a noop tracer is used (zero overhead).
	Tracing *TracingConfig `toml:"tracing" json:"tracing,omitempty"`

	// Opentelemetry holds OpenTelemetry OTLP tracing configuration per spec §4.1.3.6.
	// This key takes precedence over the legacy tracing key when both are present.
	// MUST use an HTTPS endpoint when configured.
	Opentelemetry *TracingConfig `toml:"opentelemetry" json:"opentelemetry,omitempty"`
	// contains filtered or unexported fields
}

type GuardConfig struct {
	// Type is the guard type: "wasm", "noop", etc.
	Type string `toml:"type" json:"type"`

	// Path is the path to the guard implementation (e.g., WASM file)
	Path string `toml:"path" json:"path,omitempty"`

	// Config holds guard-specific configuration
	Config map[string]interface{} `toml:"config" json:"config,omitempty"`

	// Policy holds guard policy configuration for label_agent lifecycle initialization
	Policy *GuardPolicy `toml:"policy" json:"policy,omitempty"`
}

type GuardPolicy struct {
	// Hyphenated keys intentionally match the policy schema field names.
	AllowOnly *AllowOnlyPolicy `toml:"allow-only" json:"allow-only,omitempty"`
	WriteSink *WriteSinkPolicy `toml:"write-sink" json:"write-sink,omitempty"`
}

type NormalizedGuardPolicy struct {
	ScopeKind            string         `json:"scope_kind"`
	ScopeValues          []string       `json:"scope_values,omitempty"`
	MinIntegrity         string         `json:"min-integrity"`
	ToolCallLimits       map[string]int `json:"tool-call-limits,omitempty"`
	BlockedUsers         []string       `json:"blocked-users,omitempty"`
	RefusalLabels        []string       `json:"refusal-labels,omitempty"`
	ApprovalLabels       []string       `json:"approval-labels,omitempty"`
	TrustedUsers         []string       `json:"trusted-users,omitempty"`
	EndorsementReactions []string       `json:"endorsement-reactions,omitempty"`
	DisapprovalReactions []string       `json:"disapproval-reactions,omitempty"`
	DisapprovalIntegrity string         `json:"disapproval-integrity,omitempty"`
	EndorserMinIntegrity string         `json:"endorser-min-integrity,omitempty"`
	PromotionLabel       string         `json:"promotion-label,omitempty"`
	DemotionLabel        string         `json:"demotion-label,omitempty"`
}

type ServerConfig struct {
	// Type is the server type: "stdio" or "http"
	Type string `toml:"type" json:"type,omitempty"`

	// Command is the executable command (for stdio servers)
	Command string `toml:"command" json:"command,omitempty"`

	// Args are the command arguments (for stdio servers)
	Args []string `toml:"args" json:"args,omitempty"`

	// Env holds environment variables for the server
	Env map[string]string `toml:"env" json:"env,omitempty"`

	// WorkingDirectory is the working directory for the server
	WorkingDirectory string `toml:"working_directory" json:"working_directory,omitempty"`

	// URL is the HTTP endpoint (for http servers)
	URL string `toml:"url" json:"url,omitempty"`

	// Headers are HTTP headers to send (for http servers)
	Headers map[string]string `toml:"headers" json:"headers,omitempty"`

	// Auth configures upstream authentication for HTTP MCP servers.
	Auth *AuthConfig `toml:"auth" json:"auth,omitempty"`

	// Tools is an optional list of tools to filter/expose
	Tools []string `toml:"tools" json:"tools,omitempty"`

	// ToolResponseFilters configures per-tool jq expressions that transform tool
	// response data before it is returned to the agent and before large-payload
	// preview/schema processing runs.
	ToolResponseFilters map[string]string `toml:"tool_response_filters" json:"tool_response_filters,omitempty"`

	// Registry is the URI to the installation location in an MCP registry (informational)
	Registry string `toml:"registry" json:"registry,omitempty"`

	// GuardPolicies holds guard policies for access control at the MCP gateway level.
	// The structure is server-specific. For GitHub MCP server, see the GitHub guard policy schema.
	GuardPolicies map[string]interface{} `toml:"guard_policies" json:"guard-policies,omitempty"`

	// Guard is the name of the guard to use for this server (requires DIFC)
	Guard string `toml:"guard" json:"guard,omitempty"`

	// ConnectTimeout is the timeout (in seconds) used for SDK-managed HTTP transport connect attempts.
	// The gateway tries multiple transports in sequence (streamable HTTP → SSE → plain JSON-RPC).
	// This timeout applies to the streamable HTTP and SSE connection attempts; the plain JSON-RPC
	// fallback uses the HTTP client's request timeout instead. Increase this for backends that are
	// slow to initialize. Only applies to HTTP server types. Default: 30 seconds.
	ConnectTimeout int `toml:"connect_timeout" json:"connect_timeout,omitempty"`

	// ToolTimeout is the per-server maximum time (seconds) to wait for a single tool invocation.
	// When set, this overrides the global gateway.tool_timeout for calls to this server only.
	// Minimum: 10. When 0 (unset), the global gateway.tool_timeout is used.
	ToolTimeout int `toml:"tool_timeout" json:"tool_timeout,omitempty"`

	// RateLimitThreshold is the number of consecutive rate-limit errors from this backend
	// that will trip the circuit breaker (transition CLOSED → OPEN). When OPEN, requests
	// are immediately rejected until the cooldown period elapses. Default: 3.
	// Supported in TOML config only; the JSON stdin config does not currently accept this field.
	RateLimitThreshold int `toml:"rate_limit_threshold" json:"-"`

	// RateLimitCooldown is the number of seconds the circuit breaker stays OPEN before
	// allowing a single probe request (transition OPEN → HALF-OPEN). If the probe
	// succeeds the circuit closes; if rate-limited again it re-opens. Default: 60.
	// Supported in TOML config only; the JSON stdin config does not currently accept this field.
	RateLimitCooldown int `toml:"rate_limit_cooldown" json:"-"`
}

type StdinConfig struct {
	// MCPServers maps server names to their configurations
	MCPServers map[string]*StdinServerConfig `json:"mcpServers"`

	// Gateway holds global gateway settings
	Gateway *StdinGatewayConfig `json:"gateway,omitempty"`

	// Guards holds guard configurations for DIFC enforcement
	Guards map[string]*StdinGuardConfig `json:"guards,omitempty"`

	// CustomSchemas defines custom server types
	CustomSchemas map[string]interface{} `json:"customSchemas,omitempty"`
}

type StdinConverter func(cfg *Config, stdinCfg *StdinConfig)

type StdinGatewayConfig struct {
	Port                        *int                      `json:"port,omitempty"`
	AgentID                     string                    `json:"agentId,omitempty"`
	APIKey                      string                    `json:"apiKey,omitempty"`
	Domain                      string                    `json:"domain,omitempty"`
	StartupTimeout              *int                      `json:"startupTimeout,omitempty"`
	ToolTimeout                 *int                      `json:"toolTimeout,omitempty"`
	KeepaliveInterval           *int                      `json:"keepaliveInterval,omitempty"`
	PayloadDir                  string                    `json:"payloadDir,omitempty"`
	PayloadPathPrefix           *string                   `json:"payloadPathPrefix,omitempty"`
	PayloadSizeThreshold        *int                      `json:"payloadSizeThreshold,omitempty"`
	TrustedBots                 []string                  `json:"trustedBots,omitempty"`
	ForcePublicRepos            *bool                     `json:"forcePublicRepos,omitempty"`
	SinkVisibilityExemptServers []string                  `json:"sinkVisibilityExemptServers,omitempty"`
	OpenTelemetry               *StdinOpenTelemetryConfig `json:"opentelemetry,omitempty"`
	// contains filtered or unexported fields
}

type StdinGuardConfig struct {
	// Type is the guard type: "wasm", "noop", etc.
	Type string `json:"type"`

	// Path is the path to the guard implementation (e.g., WASM file)
	Path string `json:"path,omitempty"`

	// Config holds guard-specific configuration
	Config map[string]interface{} `json:"config,omitempty"`

	// Policy holds guard policy configuration for label_agent lifecycle initialization
	Policy *GuardPolicy `json:"policy,omitempty"`
}

type StdinOpenTelemetryConfig struct {
	// Endpoint is the OTLP/HTTP collector URL. MUST be HTTPS. Supports ${VAR} expansion.
	Endpoint string `json:"endpoint"`

	// TraceID is the parent trace ID (32-char lowercase hex, W3C format). Supports ${VAR}.
	TraceID string `json:"traceId,omitempty"`

	// SpanID is the parent span ID (16-char lowercase hex, W3C format). Ignored without TraceID. Supports ${VAR}.
	SpanID string `json:"spanId,omitempty"`

	// ServiceName is the service.name resource attribute. Default: "mcp-gateway".
	ServiceName string `json:"serviceName,omitempty"`
}

type StdinServerConfig struct {
	// Type is the server type: "stdio", "local", or "http"
	Type string `json:"type"`

	// Container is the Docker image for stdio servers
	Container string `json:"container,omitempty"`

	// Entrypoint overrides the container entrypoint
	Entrypoint string `json:"entrypoint,omitempty"`

	// EntrypointArgs are additional arguments to the entrypoint
	EntrypointArgs []string `json:"entrypointArgs,omitempty"`

	// Args are additional Docker runtime arguments (passed before container image)
	Args []string `json:"args,omitempty"`

	// Mounts are volume mounts for the container
	Mounts []string `json:"mounts,omitempty"`

	// Env holds environment variables
	Env map[string]string `json:"env,omitempty"`

	// URL is the HTTP endpoint (for http servers)
	URL string `json:"url,omitempty"`

	// Headers are HTTP headers to send (for http servers)
	Headers map[string]string `json:"headers,omitempty"`

	// Tools is an optional list of tools to filter/expose
	Tools []string `json:"tools,omitempty"`

	// ToolResponseFilters configures per-tool jq expressions that transform tool
	// response data before it is returned to the agent.
	ToolResponseFilters map[string]string `json:"tool_response_filters,omitempty"`

	// Registry is the URI to the installation location in an MCP registry (informational)
	Registry string `json:"registry,omitempty"`

	// GuardPolicies holds guard policies for access control at the MCP gateway level.
	// The structure is server-specific. For GitHub MCP server, see the GitHub guard policy schema.
	GuardPolicies map[string]interface{} `json:"guard-policies,omitempty"`

	// Guard is the name of the guard to use for this server (requires DIFC)
	Guard string `json:"guard,omitempty"`

	// Auth configures upstream authentication for HTTP MCP servers.
	Auth *AuthConfig `json:"auth,omitempty"`

	// ConnectTimeout is the per-transport timeout (in seconds) for connecting to HTTP backends.
	// Only applies to HTTP server types. Default: 30 seconds.
	ConnectTimeout *int `json:"connectTimeout,omitempty"`

	// ToolTimeout is the per-server maximum time (seconds) to wait for a single tool invocation.
	// When set to a positive value, this overrides the global gateway.toolTimeout for calls to
	// this server only. Minimum: 10. Omit the field (or set to 0) to fall back to the global
	// gateway.toolTimeout (or MCP_GATEWAY_TOOL_TIMEOUT env fallback).
	ToolTimeout *int `json:"toolTimeout,omitempty"`

	// AdditionalProperties stores any extra fields for custom server types
	// This allows custom schemas to define their own fields beyond the standard ones
	AdditionalProperties map[string]interface{} `json:"-"`
	// contains filtered or unexported fields
}

type TracingConfig struct {
	// Endpoint is the OTLP HTTP endpoint to export traces to.
	// When using the opentelemetry section (spec §4.1.3.6), this MUST be an HTTPS URL.
	// If empty, tracing is disabled and a noop tracer is used.
	Endpoint string `toml:"endpoint" json:"endpoint,omitempty"`

	// Headers is a comma-separated list of key=value HTTP headers sent with every OTLP
	// export request (e.g. "Authorization=Bearer ${OTEL_TOKEN},X-Custom=value").
	// Supports ${VAR} variable expansion (expanded at config load time).
	Headers string `toml:"headers" json:"headers,omitempty"`

	// TraceID is an optional W3C trace ID (32-char lowercase hex) used to construct the
	// parent traceparent header, linking gateway spans into a pre-existing trace.
	// Supports ${VAR} variable expansion (expanded at config load time).
	// Must be 32 lowercase hex characters and must not be all zeros.
	TraceID string `toml:"trace_id" json:"traceId,omitempty"`

	// SpanID is an optional W3C span ID (16-char lowercase hex) paired with TraceID
	// to construct the parent traceparent header. Ignored when TraceID is absent.
	// Supports ${VAR} variable expansion (expanded at config load time).
	// Must be 16 lowercase hex characters and must not be all zeros.
	SpanID string `toml:"span_id" json:"spanId,omitempty"`

	// ServiceName is the service name reported in traces.
	// Defaults to "mcp-gateway".
	ServiceName string `toml:"service_name" json:"serviceName,omitempty"`

	// SampleRate controls the fraction of traces that are sampled and exported.
	// Valid range: 0.0 (no sampling) to 1.0 (sample everything).
	// Defaults to 1.0 (100% sampling).
	// Uses a pointer so that 0.0 can be distinguished from "unset".
	// Note: SampleRate is a gateway extension field not present in spec §4.1.3.6.
	SampleRate *float64 `toml:"sample_rate" json:"sampleRate,omitempty"`

	// SignalPath is the OTLP signal path appended to the base endpoint URL.
	// Defaults to "/v1/traces" per the OpenTelemetry specification.
	// Override this only if your collector uses a non-standard ingest path.
	SignalPath string `toml:"signal_path" json:"signalPath,omitempty"`
}

type ValidationError struct {
	Field      string
	Message    string
	JSONPath   string
	Suggestion string
}

type WriteSinkPolicy struct {
	Accept         []string `toml:"accept" json:"accept"`
	SinkVisibility string   `toml:"sink-visibility" json:"sink-visibility,omitempty"`
}