configx

type AuditConfig struct {
	Enabled bool `json:"enabled"`
	// SignKeyID is the security.signer.keys[].id used to sign each
	// envelope under FIPS profiles (AU-9 integrity). Required when
	// security.fips=true.
	SignKeyID string            `json:"sign_key_id,omitempty"`
	Sinks     []AuditSinkConfig `json:"sinks,omitempty"`
}

type AuditSinkConfig struct {
	// Kind selects the sink implementation. Only "file" is implemented
	// today (pkg/obsx/auditx.FileSink); "syslog" and "cef" are reserved
	// future kinds and are rejected by the config validator until a real
	// sink exists, so they cannot silently no-op at runtime (GAP-0081).
	Kind   string         `json:"kind"` // "file" (implemented); "syslog"/"cef" reserved
	Config map[string]any `json:"config,omitempty"`
}

type AuthConfig struct {
	APIKey bool `json:"api_key"`
	JWT    bool `json:"jwt"`
	// Cookie is true when at least one REST route resolves to auth:"cookie".
	// Derived from resolved route modes (see applyAuthDefaults) and used to
	// emit the top-level cookieAuth entry in the generated OpenAPI security
	// list, mirroring the APIKey/JWT bools.
	Cookie      bool   `json:"cookie"`
	JWTIssuer   string `json:"jwt_issuer,omitempty"`
	JWTAudience string `json:"jwt_audience,omitempty"`
	// Default is the fallback auth mode applied to any REST or WebSocket
	// route that omits `auth`. Recognized: "api_key", "jwt",
	// "mtls" (REST only), "webhook" (REST only), or "public" (explicitly
	// unauthenticated). Empty means NO default: under default-deny a route
	// that omits auth and is not explicitly public is a configuration error.
	Default string `json:"default,omitempty"`
	// DefaultRequiredRoles is the minimum RBAC role set applied to any
	// authenticated route (resolved mode != public) that declares no
	// required_roles of its own. Role hierarchy: admin > manager > user.
	DefaultRequiredRoles []string `json:"default_required_roles,omitempty"`
	// DefaultRequiredScopes is the scope set applied to any authenticated
	// route that declares no required_scopes of its own.
	DefaultRequiredScopes []string `json:"default_required_scopes,omitempty"`
	// CookieName is the name of the HttpOnly cookie that carries the session
	// JWT for routes using auth:"cookie". Empty defaults to "session" (see
	// AuthCookieName). Used by the generated cookie-auth extraction, the CSRF
	// auth-source check, and the emitted OpenAPI cookie security scheme.
	CookieName string `json:"cookie_name,omitempty"`
}

type CORSConfig struct {
	Enabled bool     `json:"enabled"`
	Origins []string `json:"origins"`
}

type CSRFConfig struct {
	// Enabled is the master switch. When false the generator emits no CSRF
	// middleware and no /csrf endpoint.
	Enabled bool `json:"enabled"`
	// SecretRef names the environment variable holding the HMAC signing key
	// (>=32 bytes). Required when Enabled; resolution fails closed at boot.
	SecretRef string `json:"secret_ref"`
	// CookieName is the non-HttpOnly cookie carrying the token. Default
	// "csrf_token".
	CookieName string `json:"cookie_name,omitempty"`
	// HeaderName is the request header echoing the token. Default
	// "X-CSRF-Token".
	HeaderName string `json:"header_name,omitempty"`
	// EndpointPath is the GET issuance route. Default "/csrf" (joined under
	// the API prefix by the generator).
	EndpointPath string `json:"endpoint_path,omitempty"`
	// TTLSeconds is the token lifetime. Default 43200 (12h).
	TTLSeconds int `json:"ttl_seconds,omitempty"`
	// SecureCookies sets the Secure attribute on the CSRF cookie. Nil
	// defaults to TRUE; set explicit false ONLY for local-dev over plain
	// HTTP (otherwise the browser drops the cookie and every write 403s).
	SecureCookies *bool `json:"secure_cookies,omitempty"`
	// SameSite is the cookie SameSite mode: "Strict" (default), "Lax", or
	// "None".
	SameSite string `json:"same_site,omitempty"`
	// ExemptPaths are additional paths exempt from enforcement. The issuance
	// endpoint and any *_login / *_logout / health routes are auto-exempt.
	ExemptPaths []string `json:"exempt_paths,omitempty"`
}

type HeadersConfig struct {
	ContentSecurityPolicy     string `json:"content_security_policy,omitempty"`
	CrossOriginOpenerPolicy   string `json:"cross_origin_opener_policy,omitempty"`
	CrossOriginEmbedderPolicy string `json:"cross_origin_embedder_policy,omitempty"`
	CrossOriginResourcePolicy string `json:"cross_origin_resource_policy,omitempty"`
	PermissionsPolicy         string `json:"permissions_policy,omitempty"`
	DisableAll                bool   `json:"disable_all,omitempty"`
}

type LimitConfig struct {
	MaxHeaderBytes int   `json:"max_header_bytes"`
	MaxBodyBytes   int64 `json:"max_body_bytes"`
}

type MCPConfig struct {
	Transport []string `json:"transport"`
	// Tools is carried in runtime.json (the full config) but consumed only
	// at generate time -- the tool surface is baked into the generated MCP
	// handlers. Declared, accepted, and ignored so the strict runtime
	// decode of the full-config superset succeeds (see DecodeRuntimeConfig).
	// The generator's MCPConfigSection models it with a richer type.
	Tools any `json:"tools,omitempty"`
}

type ObservabilityConfig struct {
	EnableDebug bool `json:"enable_debug"`
}

type PasswordHashConfig struct {
	// Default algorithm for fields that declare hash:"default".
	Default string `json:"default,omitempty"`
	// PepperEnv names an environment variable holding a server-side pepper
	// (optional defense-in-depth; applied via HMAC-SHA-256 before hashing).
	PepperEnv string `json:"pepper_env,omitempty"`
}

type PathRateLimit struct {
	PathPrefix string  `json:"path_prefix"`
	PerIPRPS   float64 `json:"per_ip_rps"`
	PerIPBurst int     `json:"per_ip_burst"`
	// TrustedProxyCIDRs lists the reverse-proxy networks whose forwarded
	// headers (X-Forwarded-For / X-Real-IP) this path's limiter honors when
	// the global PerIPSource selects a proxy-header source. Empty (the
	// default) INHERITS the global RateLimitConfig.TrustedProxyCIDRs set, so a
	// forwarded PerIPSource keys the same way at every layer; set this field
	// to override the global set for this path only. (Only an empty GLOBAL set
	// trusts no proxy — see RateLimitConfig.TrustedProxyCIDRs.) Threaded into
	// httpx.PathLimit at generation. T-06 / GAP-0094 / GAP-0095.
	TrustedProxyCIDRs []string `json:"trusted_proxy_cidrs,omitempty"`
}

type RateLimitConfig struct {
	GlobalRPS   int     `json:"global_rps"`
	Burst       int     `json:"burst"`
	PerIPRPS    float64 `json:"per_ip_rps,omitempty"`
	PerIPBurst  int     `json:"per_ip_burst,omitempty"`
	PerIPSource string  `json:"per_ip_source,omitempty"`
	// TrustedProxyCIDRs lists the reverse-proxy networks whose forwarded
	// headers (X-Forwarded-For / X-Real-IP) the global per-IP limiter honors
	// when PerIPSource is a proxy-header source. Empty (the default) trusts no
	// proxy. Each entry must be a valid CIDR (e.g. "10.0.0.0/8"); malformed
	// entries are rejected at config validation. T-06 / GAP-0094.
	TrustedProxyCIDRs []string `json:"trusted_proxy_cidrs,omitempty"`
	// PathOverrides install stricter per-IP buckets for matching path
	// prefixes, checked before the route handler. Longest-prefix match wins.
	PathOverrides []PathRateLimit `json:"path_overrides,omitempty"`
}

type RuntimeConfig struct {
	Server        ServerConfig        `json:"server"`
	Security      SecurityConfig      `json:"security"`
	MCP           MCPConfig           `json:"mcp"`
	Observability ObservabilityConfig `json:"observability"`

	// The following members are present in runtime.json (the full
	// generator config) but are consumed only at generate time -- the
	// runtime behaviour they describe is already baked into the generated
	// handlers/types. They are declared here, accepted, and ignored so the
	// strict DecodeRuntimeConfig decode of the full-config superset
	// succeeds while still rejecting genuinely unknown members. The
	// generator's Config type shadows each with its richly-typed
	// equivalent (the same embedded-vs-outer pattern already used for
	// MCP), so this raw view is used only by the runtime decoder.
	API       any `json:"api,omitempty"`
	Websocket any `json:"websocket,omitempty"`
	Schemas   any `json:"schemas,omitempty"`
	GraphQL   any `json:"graphql,omitempty"`
}

type SecurityConfig struct {
	Auth      AuthConfig      `json:"auth"`
	CORS      CORSConfig      `json:"cors"`
	RateLimit RateLimitConfig `json:"rate_limit"`
	Roles     []string        `json:"roles,omitempty"`
	// FIPS, when true, requires the generated binary to operate inside
	// the Go 1.26 FIPS 140-3 Cryptographic Module. The apic generator
	// rejects HS256-only JWT operations under this mode (NIST 800-53
	// SC-13). Hardware-backed JWT signing comes from the security.signer
	// block (see Plan 04). Default false preserves backward compatibility.
	FIPS bool `json:"fips,omitempty"`
	// UnsafeAllowSymmetricOIDCAlg, when true, suppresses the generator
	// hard-error that fires when any route in an OIDC profile (oidc_*)
	// declares auth: "jwt" with a symmetric algorithm (HS* family) or
	// with no jwt_alg at all (legacy HS256 default). The classic
	// "OIDC capability gap" footgun — the resource-server verifier
	// defaults to HS256 against an IdP that publishes a JWKS and signs
	// with RS256, producing either a silent functional regression or
	// (in deployments where the symmetric secret leaks) an alg-confusion
	// forgery primitive. Defaults to false so the generator fails closed.
	// Mirrors the OIDCRefreshTokenPolicy.UnsafeAllowStatelessJWT
	// "explicit opt-in for known-unsafe configurations" pattern.
	UnsafeAllowSymmetricOIDCAlg bool `json:"unsafe_allow_symmetric_oidc_alg,omitempty"`
	// Signer configures the hardware- or KMS-backed crypto.Signer used
	// for TLS server certs and JWT signing (Plan 04). When nil, the
	// generator emits HS256 (forbidden under FIPS) or relies on the
	// listener's PEM-loaded key.
	Signer *SignerConfig `json:"signer,omitempty"`
	// Webauthn configures the Plan 06 WebAuthn ceremony surface when any
	// operation references a profileWebauthn* profile.
	Webauthn *WebauthnRuntimeConfig `json:"webauthn,omitempty"`
	// Audit configures the FedRAMP audit pipeline (Plan 05). Nil means
	// "no audit emit"; legacy obsx.LogAudit slog records continue to
	// flow unconditionally.
	Audit *AuditConfig `json:"audit,omitempty"`
	// Session configures AC-7 / AC-11 / AC-12 enforcement (Plan 05).
	// Nil means "no session policy enforced"; the runtime falls back to
	// stateless JWT semantics.
	Session *SessionConfig `json:"session,omitempty"`
	// Webhooks resolves named webhook secrets at boot. Keyed by the
	// WebhookContract.SecretRef value the generator emits per-route.
	// Entries with an empty SecretEnv are rejected by the runtime
	// helper at startup (fail-closed).
	Webhooks map[string]WebhookSecretRef `json:"webhooks,omitempty"`
	// CSRF configures generated CSRF protection (signed double-submit,
	// session-bound). Nil or Enabled=false means no CSRF enforcement.
	CSRF *CSRFConfig `json:"csrf,omitempty"`
	// PasswordHash configures default password-hashing policy for fields that
	// declare hash:"default". Optional; when absent the generator uses the
	// FIPS-aware built-in default (argon2id, or pbkdf2-sha256 under FIPS).
	PasswordHash *PasswordHashConfig `json:"password_hash,omitempty"`
	// Headers configures per-deployment overrides for the SEC-0023 hardened
	// response-header set that httpx applies by default
	// (Content-Security-Policy, Cross-Origin-Opener/Embedder/Resource-Policy,
	// Permissions-Policy). Nil (the default) applies the httpx secure
	// defaults unmodified -- a pure-JSON API gets `default-src 'none'`. A
	// browser-facing service (an HTML SPA's same-origin API) sets this block
	// to publish a working CSP instead of being stuck on the hardened
	// default. GENERATOR_BUGS.md L-35.
	Headers *HeadersConfig `json:"headers,omitempty"`
}

type ServerConfig struct {
	Bind              string        `json:"bind"`
	TLS               TLSConfig     `json:"tls"`
	Timeouts          TimeoutConfig `json:"timeouts"`
	Limits            LimitConfig   `json:"limits"`
	EnableCompression bool          `json:"enable_compression,omitempty"`
}

type SessionConfig struct {
	MaxFailures             int `json:"max_failures,omitempty"`              // AC-7
	LockoutDurationSeconds  int `json:"lockout_duration_seconds,omitempty"`  // AC-7
	InactivitySeconds       int `json:"inactivity_seconds,omitempty"`        // AC-11
	AbsoluteLifetimeSeconds int `json:"absolute_lifetime_seconds,omitempty"` // AC-12
}

type SignerConfig struct {
	// Backend is the registered backend name (e.g. "softfile", "pkcs11",
	// "awskms", "azurekv"). Each backend lives behind its own build tag
	// in pkg/securex/signerx/<backend>.
	Backend string `json:"backend"`
	// Config is the raw backend-specific config blob (path, region,
	// vault_url, library_path, etc.).
	Config map[string]any `json:"config,omitempty"`
	// Keys are the keys this binary will open. Each entry pairs a
	// signerx.KeyRef.ID with a "use" tag ("tls", "jwt", "client-assertion").
	Keys []SignerKey `json:"keys,omitempty"`
}

type SignerKey struct {
	ID  string `json:"id"`
	Use string `json:"use,omitempty"` // "tls" | "jwt" | "client-assertion"
	Alg string `json:"alg,omitempty"` // "RS256" | "ES256" | "PS256"
	// PINEnv names the env var the PKCS#11 PIN is read from at boot
	// (e.g. "APIC_HSM_PIN"). SEC-0032: production-safe path that keeps
	// the secret out of config files. When set it takes precedence over
	// PIN and a literal PIN alongside it is rejected.
	PINEnv string `json:"pin_env,omitempty"`
	// PIN is a literal PKCS#11 PIN. SEC-0032: accepted only for local
	// dev/test; ResolvePIN rejects it when strict (FIPS/prod) is requested.
	PIN string `json:"pin,omitempty"`
}

type TLSConfig struct {
	CertPath string `json:"cert_path"`
	KeyPath  string `json:"key_path"`
	// Mode is the listener TLS mode. The empty string (default) means TLS
	// is required: the generated server refuses to boot without a cert.
	// "off" is the EXPLICIT opt-in to serve plain HTTP for deployments that
	// terminate TLS upstream (ingress/mesh); it is the config-driven
	// equivalent of server.WithInsecureHTTP(). Any other value is treated
	// as TLS-required (secure by default).
	Mode       string  `json:"mode,omitempty"`
	MTLSCAPath *string `json:"mtls_ca_path"`
}

type TimeoutConfig struct {
	ReadHeaderMS int `json:"read_header_ms"`
	ReadMS       int `json:"read_ms"`
	WriteMS      int `json:"write_ms"`
	IdleMS       int `json:"idle_ms"`
}

type WebauthnRuntimeConfig struct {
	RPID                  string   `json:"rp_id"`
	RPDisplayName         string   `json:"rp_display_name"`
	Origins               []string `json:"origins"`
	AAGUIDAllowList       []string `json:"aaguid_allow_list,omitempty"` // hex strings
	AttestationPreference string   `json:"attestation_preference,omitempty"`
	UserVerification      string   `json:"user_verification,omitempty"`
	RequireResidentKey    bool     `json:"require_resident_key,omitempty"`
}

type WebhookSecretRef struct {
	// SecretEnv is the env var name (e.g. "APIC_WEBHOOK_STRIPE_SECRET")
	// the runtime reads. Required; the boot helper refuses to start
	// with an empty value when any route references this entry.
	SecretEnv string `json:"secret_env"`
	// SecretFileEnv is an optional env var pointing at a file path
	// the runtime reads instead of taking the secret from an env var
	// directly. Use for FIPS / k8s-secrets-volume deployments where
	// the secret must live on disk under operator-controlled ACLs.
	// When both SecretEnv and SecretFileEnv are set the file wins.
	SecretFileEnv string `json:"secret_file_env,omitempty"`
}