config

type APIConfig struct {
	// RateLimit is the default rate limit applied to every operation that does
	// not declare its own via api.OperationSpec.RateLimit.
	RateLimit APIRateLimitConfig `config:"rate_limit"`
}

type APIRateLimitConfig struct {
	// Max is the number of requests admitted per window; 0 resolves to the
	// default. Default: 100.
	Max int `config:"max"`
	// Period is the sliding-window length; 0 resolves to the default.
	// Default: 5m.
	Period time.Duration `config:"period"`
}

type AppConfig struct {
	Name      string `config:"name"`
	Port      uint16 `config:"port"`
	BodyLimit string `config:"body_limit"`
	// TrustedProxies lists proxy IPs or CIDR ranges allowed to set
	// X-Forwarded-For. When empty, the client IP is the direct connection peer
	// and a forwarded header from an untrusted client is ignored.
	TrustedProxies []string `config:"trusted_proxies"`
}

type ApprovalBindingConsistency string

type ApprovalBusinessBindingConfig struct {
	// Consistency defaults to synchronous so business projection failures abort
	// the approval action unless eventual consistency is explicitly enabled.
	Consistency ApprovalBindingConsistency `config:"consistency"`
	// ScanInterval is the eventual projection worker cadence. Default: 10 seconds.
	ScanInterval time.Duration `config:"scan_interval"`
	// BatchSize bounds the number of pending projections processed per scan.
	// Default: 100.
	BatchSize int `config:"batch_size"`
}

type ApprovalConfig struct {
	// AutoMigrate runs the approval DDL migration on application start.
	AutoMigrate bool `config:"auto_migrate"`

	// TimeoutScanInterval is the polling cadence for the timeout scanner
	// that finds tasks past their deadline. Default: 1 minute.
	TimeoutScanInterval time.Duration `config:"timeout_scan_interval"`

	// PreWarningScanInterval is the polling cadence for the pre-warning
	// scanner that notifies before a task hits its deadline. Default: 5 minutes.
	PreWarningScanInterval time.Duration `config:"pre_warning_scan_interval"`

	// CleanupScanInterval is the cadence of the retention cleanup job
	// that prunes form snapshots, urge records, and CC records past
	// their retention window. Default: 24 hours.
	CleanupScanInterval time.Duration `config:"cleanup_scan_interval"`

	// DelegationMaxDepth caps how deep a delegation chain (A→B→C…) can
	// be resolved before short-circuiting. Default: 10.
	DelegationMaxDepth int `config:"delegation_max_depth"`

	// FormSnapshotRetention is the retention window for apv_form_snapshot
	// rows; older snapshots are deleted by the cleanup job. Default: 90 days.
	FormSnapshotRetention time.Duration `config:"form_snapshot_retention"`

	// UrgeRecordRetention is the retention window for apv_urge_record rows.
	// Default: 30 days.
	UrgeRecordRetention time.Duration `config:"urge_record_retention"`

	// CCRecordRetention is the retention window for apv_cc_record rows
	// (only records that have been read are pruned). Default: 90 days.
	CCRecordRetention time.Duration `config:"cc_record_retention"`

	// BusinessBinding controls approval-to-business-table state projection.
	BusinessBinding ApprovalBusinessBindingConfig `config:"business_binding"`
}

type CORSConfig struct {
	Enabled      bool     `config:"enabled"`
	AllowOrigins []string `config:"allow_origins"`
}

type Config interface {
	// Unmarshal decodes configuration at the given key into target.
	Unmarshal(key string, target any) error
}

type DBKind string

type DataSourceConfig struct {
	Kind           DBKind `config:"type"`
	Host           string `config:"host"`
	Port           uint16 `config:"port"`
	User           string `config:"user"`
	Password       string `config:"password"`
	Database       string `config:"database"`
	Schema         string `config:"schema"`
	Path           string `config:"path"`
	EnableSQLGuard bool   `config:"enable_sql_guard"`

	// SSLMode selects the TLS posture for network dialects (Postgres, MySQL).
	// It defaults to SSLDisable (plaintext) when omitted, so TLS is opt-in
	// and existing zero-config deployments are unaffected. SQLite ignores it.
	SSLMode SSLMode `config:"ssl_mode"`
	// SSLRootCert is an optional path to a PEM file holding the CA
	// certificate(s) used to verify the server in the verify-ca / verify-full
	// modes. When empty, the host's system certificate pool is used.
	SSLRootCert string `config:"ssl_root_cert"`
}

type DataSourcesConfig struct {
	Map map[string]DataSourceConfig
}

type EventConfig struct {
	// DefaultTransport is the route fallback when no rule matches.
	DefaultTransport string `config:"default_transport"`
	// AsyncQueueSize is the capacity of the async fan-in queue used
	// by WithAsync publishes.
	AsyncQueueSize int `config:"async_queue_size"`
	// AsyncWorkers is the number of goroutines draining the async
	// fan-in queue.
	AsyncWorkers int `config:"async_workers"`
	// PublishTimeout caps an individual transport.Publish call.
	PublishTimeout time.Duration `config:"publish_timeout"`

	Transports EventTransportsConfig `config:"transports"`
	Middleware EventMiddlewareConfig `config:"middleware"`
	Inbox      EventInboxConfig      `config:"inbox"`
	// Routing is matched top-to-bottom; the first rule whose Pattern
	// matches via path.Match wins. fan-out is expressed by listing
	// multiple transports in Transports.
	Routing []EventRoutingRule `config:"routing"`
}

type EventInboxConfig struct {
	Retention       time.Duration `config:"retention"`
	ProcessingLease time.Duration `config:"processing_lease"`
	CleanupInterval time.Duration `config:"cleanup_interval"`
}

type EventMemoryTransportConfig struct {
	QueueSize      int           `config:"queue_size"`
	FullPolicy     string        `config:"full_policy"` // error | block | drop_oldest
	PublishTimeout time.Duration `config:"publish_timeout"`
}

type EventMiddlewareConfig struct {
	Logging bool `config:"logging"`
	Tracing bool `config:"tracing"`
	// TracingStrict, when true, switches the Tracing middleware to
	// strict mode: incoming TraceIDs from cross-process transports are
	// treated as untrusted and parked under IncomingTraceIDFromContext;
	// a fresh ID is generated for log correlation. Default (false) is
	// W3C / OpenTelemetry-compatible propagation suitable for intra-
	// cluster pub/sub. Toggle this on at the edge between trust zones.
	TracingStrict bool `config:"tracing_strict"`
	Metrics       bool `config:"metrics"`
	Recover       bool `config:"recover"`
	// Inbox controls whether the consume-side idempotency middleware
	// is enabled. It only activates on transports whose Capabilities
	// declare AtLeastOnce regardless of this flag.
	Inbox bool `config:"inbox"`
}

type EventOutboxTransportConfig struct {
	Enabled         bool          `config:"enabled"`
	RelayInterval   time.Duration `config:"relay_interval"`
	MaxRetries      int           `config:"max_retries"`
	BatchSize       int           `config:"batch_size"`
	LeaseMultiplier int           `config:"lease_multiplier"`
	MinLease        time.Duration `config:"min_lease"`
	SinkName        string        `config:"sink"`
	CleanupInterval time.Duration `config:"cleanup_interval"`
	CompletedTTL    time.Duration `config:"completed_ttl"`
}

type EventRedisStreamTransportConfig struct {
	Enabled           bool          `config:"enabled"`
	StreamPrefix      string        `config:"stream_prefix"`
	MaxLenApprox      int64         `config:"max_len_approx"`
	BlockTimeout      time.Duration `config:"block_timeout"`
	ClaimIdle         time.Duration `config:"claim_idle"`
	ClaimInterval     time.Duration `config:"claim_interval"`
	ClaimBatchSize    int64         `config:"claim_batch_size"`
	ReaperConcurrency int           `config:"reaper_concurrency"`
	// HandlerTimeout bounds each delivery so a hung handler cannot pin a worker.
	// Zero disables the deadline — but the deadline is also the ONLY thing that
	// frees a wedged reaper slot before shutdown: a reclaimed handler that blocks
	// forever holds its bounded slot until Stop, so with HandlerTimeout=0 a few
	// stuck reclaims can starve reaper failover for all other streams. Operators
	// who disable it should size ReaperConcurrency with that risk in mind.
	HandlerTimeout time.Duration `config:"handler_timeout"`
	SetupTimeout   time.Duration `config:"setup_timeout"`
	ConsumerID     string        `config:"consumer_id"`
	StartID        string        `config:"start_id"`
	// IdleGroupRetention enables reclamation of orphaned consumer groups
	// (a decommissioned subscriber's leftovers): a group with no pending
	// entries whose every consumer record has been idle beyond this window
	// is destroyed. Zero (default) disables the sweep.
	IdleGroupRetention time.Duration `config:"idle_group_retention"`
	// IdleGroupSweepInterval is the sweep period when IdleGroupRetention
	// is enabled. Defaults to 10m.
	IdleGroupSweepInterval time.Duration `config:"idle_group_sweep_interval"`
}

type EventRoutingRule struct {
	Pattern    string   `config:"pattern"`
	Transports []string `config:"transports"`
}

type EventTransportsConfig struct {
	Memory      EventMemoryTransportConfig      `config:"memory"`
	Outbox      EventOutboxTransportConfig      `config:"outbox"`
	RedisStream EventRedisStreamTransportConfig `config:"redis_stream"`
}

type FilesystemConfig struct {
	Root string `config:"root"`
}

type LockoutConfig struct {
	// Enabled toggles lockout. A nil pointer resolves to enabled, so brute-force
	// protection is on by default; set it to false to switch the feature off.
	Enabled *bool `config:"enabled"`
	// MaxFailures is the number of failed attempts tolerated before the strategy
	// engages. Default: 10.
	MaxFailures int `config:"max_failures"`
	// Window is how long failed attempts are remembered; a spell of no failures
	// this long resets the counter. Default: 15m.
	Window time.Duration `config:"window"`
	// LockDuration is how long attempts are blocked once the threshold is
	// reached under the "lock" strategy. Default: 15m.
	LockDuration time.Duration `config:"lock_duration"`
	// Strategy selects "lock" (hard block) or "backoff" (escalating delay).
	// Default: "lock".
	Strategy LockoutStrategy `config:"strategy"`
	// BackoffBase is the first delay imposed past the threshold under the
	// "backoff" strategy; it doubles per further failure. Default: 1s.
	BackoffBase time.Duration `config:"backoff_base"`
	// BackoffMax caps the per-attempt backoff delay. Default: 15m.
	BackoffMax time.Duration `config:"backoff_max"`
	// Key selects the identity dimension the counter is keyed by. Default:
	// "user_ip".
	Key LockoutKey `config:"key"`
}

type LockoutKey string

type LockoutStrategy string

type MCPConfig struct {
	Enabled bool `config:"enabled"`
	// RequireAuth gates the MCP HTTP endpoint behind bearer-token authentication.
	// It is a pointer so an unset value defaults to secure (auth required); set it
	// to false explicitly to allow anonymous access.
	RequireAuth *bool `config:"require_auth"`
}

type MinIOConfig struct {
	Endpoint  string `config:"endpoint"`
	AccessKey string `config:"access_key"`
	SecretKey string `config:"secret_key"`
	Bucket    string `config:"bucket"`
	Region    string `config:"region"`
	UseSSL    bool   `config:"use_ssl"`
}

type MonitorConfig struct {
	SampleInterval time.Duration `config:"sample_interval"` // Interval between samples (default: 10s)
	SampleDuration time.Duration `config:"sample_duration"` // Sampling window duration (default: 2s)
}

type PasswordPolicyConfig struct {
	// MinLength requires at least this many characters when > 0.
	MinLength int `config:"min_length"`
	// MaxLength requires at most this many characters when > 0.
	MaxLength int `config:"max_length"`
	// RequireUpper requires at least one uppercase letter.
	RequireUpper bool `config:"require_upper"`
	// RequireLower requires at least one lowercase letter.
	RequireLower bool `config:"require_lower"`
	// RequireDigit requires at least one digit.
	RequireDigit bool `config:"require_digit"`
	// RequireSymbol requires at least one symbol (non-space, non-letter,
	// non-digit; caseless letters such as CJK do not count).
	RequireSymbol bool `config:"require_symbol"`
	// MinCharClasses requires at least this many distinct character classes
	// (uppercase, lowercase, digit, symbol) when > 0.
	MinCharClasses int `config:"min_char_classes"`
	// DisallowUsername rejects a password that contains the account id or name.
	DisallowUsername bool `config:"disallow_username"`
	// Blocklist rejects passwords matching any listed entry (case-insensitive).
	Blocklist []string `config:"blocklist"`
	// HistoryDepth rejects a new password that repeats any of the subject's last
	// N passwords when > 0. Enforcement requires a security.PasswordHistoryStore.
	HistoryDepth int `config:"history_depth"`
	// MaxAge forces a password change once the password is older than this.
	// Zero disables expiry. Enforcement requires a security.PasswordMetadataLoader
	// and a security.ExpiryPasswordChangeChecker wired into the login flow.
	MaxAge time.Duration `config:"max_age"`
}

type RedisConfig struct {
	// Enabled gates the Redis client construction. When false (default) the
	// framework provides a nil *redis.Client into the fx graph and skips the
	// connection PING during start-up; downstream modules that ask for the
	// client via `optional:"true"` therefore stay dormant. Set this to true
	// only when the application actually depends on Redis (cache, redis_stream
	// transport, nonce store, etc.).
	Enabled  bool   `config:"enabled"`
	Host     string `config:"host"`
	Port     uint16 `config:"port"`
	User     string `config:"user"`
	Password string `config:"password"`
	Database uint8  `config:"database"` // Database number (0-15)
	Network  string `config:"network"`  // "tcp" or "unix" (default: "tcp")
}

type SSLMode string

type SecurityConfig struct {
	// Secret is the hex-encoded key used to sign and verify JWT tokens.
	// Leave empty in development to have the framework generate an ephemeral
	// key at startup; set a stable per-deployment value in production.
	Secret           string        `config:"secret"`
	TokenExpires     time.Duration `config:"token_expires"`
	RefreshNotBefore time.Duration `config:"refresh_not_before"`
	LoginRateLimit   int           `config:"login_rate_limit"`
	RefreshRateLimit int           `config:"refresh_rate_limit"`
	// IPWhitelists names the source-IP whitelists served by the framework's
	// default security.IPWhitelistLoader; the built-in "ip" auth strategy
	// resolves api.IPAuth(name) against them, and the no-arg api.IPAuth()
	// targets the "default" key. Each entry is a single IP address or CIDR
	// range. Note: the config layer lowercases TOML keys, so whitelist names
	// are effectively lowercase.
	IPWhitelists map[string][]string `config:"ip_whitelists"`
	// Lockout configures brute-force protection on the login endpoint.
	Lockout LockoutConfig `config:"lockout"`
	// PasswordPolicy configures strength rules enforced when a password is set.
	PasswordPolicy PasswordPolicyConfig `config:"password_policy"`
	// TokenType selects the login token mechanism: stateless "jwt_token"
	// (default) or stateful "opaque_token". Session control (concurrency limits,
	// force-offline, renewal) is only available with opaque tokens.
	TokenType TokenType `config:"token_type"`
	// Session configures opaque-token session behavior; it has no effect under
	// the jwt_token mechanism.
	Session SessionConfig `config:"session"`
}

type SessionConfig struct {
	// MaxConcurrent bounds simultaneous sessions per account; 0 is unlimited.
	// Enforcement is best-effort under concurrent logins: a burst of simultaneous
	// logins for one account may briefly exceed the limit by the number of racing
	// requests before it settles.
	MaxConcurrent int `config:"max_concurrent"`
	// OnExceed selects reject vs. evict-oldest when the limit is hit.
	// Default: evict_oldest (a new login kicks the earliest device offline).
	OnExceed SessionExceedPolicy `config:"on_exceed"`
	// IdleTTL is the inactivity timeout and the sliding renewal window applied on
	// each authenticated request. Default: 30m.
	IdleTTL time.Duration `config:"idle_ttl"`
	// MaxLifetime caps a session's total age regardless of renewal; 0 is
	// uncapped. Default: 7 days.
	MaxLifetime time.Duration `config:"max_lifetime"`
	// Sliding enables idle-timeout renewal on each request. A nil pointer
	// resolves to enabled.
	Sliding *bool `config:"sliding"`
}

type SessionExceedPolicy string

type StorageConfig struct {
	Provider    StorageProvider  `config:"provider"`
	AutoMigrate bool             `config:"auto_migrate"`
	MinIO       MinIOConfig      `config:"minio"`
	Filesystem  FilesystemConfig `config:"filesystem"`

	// MaxUploadSize is the hard upper bound (in bytes) on a single object
	// uploaded through the storage RPC, regardless of declared mode.
	// Default: 1 GiB.
	MaxUploadSize int64 `config:"max_upload_size"`

	// ClaimTTL is how long an upload claim stays valid before being swept.
	// Default: 24h.
	ClaimTTL time.Duration `config:"claim_ttl"`

	// MaxPendingClaims caps the number of in-flight (status='pending')
	// upload claims a single principal may hold simultaneously. Prevents
	// a single user from exhausting backend resources by opening
	// thousands of multipart sessions. Enforcement is best-effort: the
	// init-upload check is a count-then-insert, so a concurrent burst from
	// one principal may briefly overshoot the cap by the number of
	// in-flight requests before settling. This is a DoS-hygiene limit, not
	// a hard security boundary. Default: 100.
	MaxPendingClaims int `config:"max_pending_claims"`

	// AllowPublicUploads controls whether clients may set public=true on
	// init_upload. When false (default), all uploads land under priv/
	// regardless of the client's request. Set to true only when the
	// business explicitly needs user-initiated public uploads.
	AllowPublicUploads bool `config:"allow_public_uploads"`

	// SweepInterval is how often the claim sweeper polls for expired
	// upload claims. Default: 5m.
	SweepInterval time.Duration `config:"sweep_interval"`
	// SweepBatchSize bounds how many expired claims one sweep tick processes.
	// Default: 200.
	SweepBatchSize int `config:"sweep_batch_size"`

	// DeleteWorkerInterval is how often the delete worker polls for due
	// pending-delete rows. Default: 5m.
	DeleteWorkerInterval time.Duration `config:"delete_worker_interval"`
	// DeleteBatchSize bounds how many rows the delete worker leases per tick.
	// Default: 100.
	DeleteBatchSize int `config:"delete_batch_size"`
	// DeleteConcurrency caps the number of in-flight object deletions
	// per worker tick. Default: 8.
	DeleteConcurrency int `config:"delete_concurrency"`
	// DeleteMaxAttempts is the retry budget after which a pending-delete
	// row is parked as dead-letter. Default: 12.
	DeleteMaxAttempts int `config:"delete_max_attempts"`
	// DeleteLeaseWindow is the visibility timeout applied when leasing
	// rows. Should comfortably exceed expected per-item processing time.
	// Default: 5m.
	DeleteLeaseWindow time.Duration `config:"delete_lease_window"`
}

type StorageProvider string

type TokenType string