config

type APIKey struct {
	HashingAlgorithms []string `koanf:"hashing_algorithms"`
}

type Auth struct {
	// Mode selects the active authentication mode: "internal_token", "file", or "idp".
	Mode string `koanf:"mode"`
	// Authorization holds every authorization setting — whether it is enforced,
	// how (scope or role), and the role-to-scope mapping file. It is deliberately
	// its own section rather than living under [auth.idp]: authorization applies
	// in every auth mode, because a token minted by an enterprise IDP carries the
	// same roles claim whether the platform verifies it via JWKS or with a local
	// public key.
	Authorization Authorization `koanf:"authorization"`
	// SkipPaths are the path prefixes that bypass authentication and scope
	// enforcement — health/metrics probes, the login endpoint, and the internal
	// routes authenticated by a gateway token instead of a user JWT. It is not
	// operator-configurable (koanf:"-"): the list is a property of the product's
	// own routing, and a wrong entry here is an auth bypass, so it comes from
	// DefaultConfig plus the prefixes plugins declare. Operators turn
	// authorization on and off with auth.authorization.enabled instead.
	SkipPaths []string `koanf:"-"`
	IDP       IDP      `koanf:"idp"`
	// JWT is shared by two modes — "internal_token" mode only verifies
	// tokens minted elsewhere with the public key, "file" mode both signs (with
	// the private key) and verifies (with the public key) using the RSA key pair.
	JWT  JWT       `koanf:"jwt"`
	File FileBased `koanf:"file"`
	// ClaimMappings names the JWT claims that carry each identity field. It is
	// shared by all three auth modes: "idp" reads incoming claims by these
	// names, "file" mode's login endpoint signs tokens using these names, and
	// "internal_token" mode reads tokens minted elsewhere by these names too
	// — one mapping, so issuance and validation can never drift apart. Every
	// field accepts either a flat top-level claim name ("org_id") or a
	// dot-separated path into a nested claim ("realm_access.org_id") — see
	// resolveClaimPath in internal/middleware/auth.go.
	ClaimMappings ClaimMappings `koanf:"claim_mappings"`
}

type Authorization struct {
	// Enabled enforces per-endpoint OAuth2 scopes on validated tokens.
	// Disable only to temporarily bypass authorization during development.
	Enabled bool `koanf:"enabled"`
	// Mode selects how authorization is enforced: "scope" (default) or "role".
	Mode string `koanf:"mode"`
	// RoleToScopeMapping is the path to a YAML file mapping IDP roles to platform
	// scopes. Required in "role" mode (validateAuthorizationConfig rejects an
	// empty path there); unused in "scope" mode.
	RoleToScopeMapping string `koanf:"role_to_scope_mapping"`
}

type CORS struct {
	// AllowedOrigins lists the exact origins permitted to make credentialed
	// cross-origin requests. Must never be ["*"] — wildcard
	// origins cannot be combined with credentialed requests.
	AllowedOrigins []string `koanf:"allowed_origins"`
}

type ClaimMappings struct {
	Organization string `koanf:"organization"`
	OrgName      string `koanf:"org_name"`
	OrgHandle    string `koanf:"org_handle"`
	UserID       string `koanf:"user_id"`
	Username     string `koanf:"username"`
	Email        string `koanf:"email"`
	Scope        string `koanf:"scope"`
	Roles        string `koanf:"roles"`
}

type Database struct {
	// Driver supports: sqlite3, postgres/postgresql/pgx, sqlserver/mssql.
	Driver string `koanf:"driver"`
	// Path is the file path for SQLite databases.
	Path     string `koanf:"path"`
	Host     string `koanf:"host"`
	Port     int    `koanf:"port"`
	Name     string `koanf:"name"`
	User     string `koanf:"user"`
	Password string `koanf:"password"`
	SSLMode  string `koanf:"ssl_mode"`
	// SSLRootCert is the CA certificate file path used to verify the server's
	// certificate. Required when SSLMode is "verify-ca" or "verify-full".
	SSLRootCert string `koanf:"ssl_root_cert"`
	// SSLCert and SSLKey are the client certificate/key pair used for mutual
	// TLS. Optional; both must be set together or not at all.
	SSLCert         string `koanf:"ssl_cert"`
	SSLKey          string `koanf:"ssl_key"`
	MaxOpenConns    int    `koanf:"max_open_conns"`
	MaxIdleConns    int    `koanf:"max_idle_conns"`
	ConnMaxLifetime int    `koanf:"conn_max_lifetime"`
}

type Deployments struct {
	MaxPerAPIGateway          int  `koanf:"max_per_api_gateway"`
	TransitionalStatusEnabled bool `koanf:"transitional_status_enabled"`
	TimeoutEnabled            bool `koanf:"timeout_enabled"`
	TimeoutInterval           int  `koanf:"timeout_interval"`
	TimeoutDuration           int  `koanf:"timeout_duration"`
}

type EventHub struct {
	PollInterval    time.Duration `koanf:"poll_interval"`
	CleanupInterval time.Duration `koanf:"cleanup_interval"`
	RetentionPeriod time.Duration `koanf:"retention_period"`
}

type FileBased struct {
	Organization FileBasedOrg   `koanf:"organization"`
	Users        FileBasedUsers `koanf:"users"`
}

type FileBasedOrg struct {
	// ID is the organization handle (URL-safe slug), e.g. "default".
	ID string `koanf:"id"`

	// DisplayName is the human-readable name of the organization.
	DisplayName string `koanf:"display_name"`

	// Region is the deployment region for the organization.
	Region string `koanf:"region"`

	// UUID is the platform organization UUID. File-based auth has no external
	// IDP, so this value is stored as idp_organization_ref_uuid and emitted as
	// the `organization` claim in issued tokens.
	UUID string `koanf:"uuid"`
}

type FileBasedUser struct {
	Username     string `json:"username"     koanf:"username"`
	PasswordHash string `json:"password_hash" koanf:"password_hash"`
	// Roles names one or more of the roles in the
	// auth.authorization.role_to_scope_mapping file and is the user's entire
	// grant: the login endpoint expands them into the scope claim of the token it
	// issues, unioning what each role grants — most-permissive wins, the same way
	// a token carrying several roles is expanded in role authorization mode. It is
	// the only way to grant a file-mode user, so a user's privileges are expressed
	// exactly the way an IDP expresses them — as roles — and changing what a role
	// grants is a single edit to the mapping file rather than a per-user scope
	// string to keep in sync.
	Roles []string `json:"roles" koanf:"roles"`
}

type FileBasedUsers []FileBasedUser

type Gateway struct {
	EnableVersionVerification           bool `koanf:"enable_version_verification"`
	EnableFunctionalityTypeVerification bool `koanf:"enable_functionality_type_verification"`
}

type HTTPListener struct {
	Enabled bool `koanf:"enabled"`
	Port    int  `koanf:"port"`
}

type HTTPSListener struct {
	Enabled  bool   `koanf:"enabled"`
	Port     int    `koanf:"port"`
	CertFile string `koanf:"cert_file"`
	KeyFile  string `koanf:"key_file"`
}

type IDP struct {
	Name     string   `koanf:"name"`
	JWKSUrl  string   `koanf:"jwks_url"`
	Issuer   []string `koanf:"issuer"`
	Audience []string `koanf:"audience"`
}

type JWT struct {
	// PublicKeyFile is the path to a mounted PEM-encoded RSA public key file,
	// used to verify token signatures. Required in both "internal_token" and
	// "file" modes. The key is read from disk at the point of use rather than
	// being interpolated into config at load time, so the PEM content is never
	// held in the config struct.
	PublicKeyFile string `koanf:"public_key_file"`
	// PrivateKeyFile is the path to a mounted PEM-encoded RSA private key file,
	// used to sign tokens. Required only in "file" mode, whose login endpoint
	// mints tokens; unused (and not required) in verify-only "internal_token"
	// mode. Read from disk at the point of use, never cached as content.
	PrivateKeyFile string        `koanf:"private_key_file"`
	Issuer         string        `koanf:"issuer"`
	TokenTTL       time.Duration `koanf:"token_ttl"`
}

type Logging struct {
	Level  string `koanf:"level"`
	Format string `koanf:"format"`
}

type Security struct {
	// EncryptionKey is the single 32-byte key used for ALL at-rest encryption
	// (secrets, subscription tokens, WebSub HMAC secrets).
	EncryptionKey string `koanf:"encryption_key"`
	APIKey        APIKey `koanf:"api_key"`
}

type Server struct {
	Logging Logging `koanf:"logging"`

	DBSchemaPath               string `koanf:"db_schema_path"`
	OpenAPISpecPath            string `koanf:"openapi_spec_path"`
	LLMTemplateDefinitionsPath string `koanf:"llm_template_definitions_path"`
	OpenAPISpecMaxFetchBytes   int64  `koanf:"openapi_spec_max_fetch_bytes"`

	Database    Database        `koanf:"database"`
	Auth        Auth            `koanf:"auth"`
	Deployments Deployments     `koanf:"deployments"`
	Listeners   ServerListeners `koanf:"server"`
	Security    Security        `koanf:"security"`
	Gateway     Gateway         `koanf:"gateway"`
	EventHub    EventHub        `koanf:"event_hub"`
	Webhook     Webhook         `koanf:"webhook"`
}

type ServerListeners struct {
	HTTP      HTTPListener  `koanf:"http"`
	HTTPS     HTTPSListener `koanf:"https"`
	Timeouts  Timeouts      `koanf:"timeouts"`
	CORS      CORS          `koanf:"cors"`
	WebSocket WebSocket     `koanf:"websocket"`
}

type Timeouts struct {
	// ReadHeader bounds how long a client may take to send request headers.
	ReadHeader time.Duration `koanf:"read_header"`
	// Read bounds the whole request read, including bodies such as uploaded API
	// definitions. Must be >= ReadHeader when both are set.
	Read time.Duration `koanf:"read"`
	// Write bounds handler execution plus the response write. Keep it generous:
	// some handlers proxy slow upstreams (LLM completions, deployments).
	Write time.Duration `koanf:"write"`
	// Idle bounds how long a keep-alive connection may sit unused between
	// requests.
	Idle time.Duration `koanf:"idle"`
}

type WebSocket struct {
	MaxConnections     int  `koanf:"max_connections"`
	ConnectionTimeout  int  `koanf:"connection_timeout"`
	RateLimitPerMin    int  `koanf:"rate_limit_per_min"`
	MetricsLogEnabled  bool `koanf:"metrics_log_enabled"`
	MetricsLogInterval int  `koanf:"metrics_log_interval"`
}

type Webhook struct {
	// Enabled controls whether the webhook endpoint is registered.
	Enabled bool `koanf:"enabled"`
	// Secret is the shared secret with the API Portal. It serves two purposes: verifying
	// the HMAC-SHA256 request signature, and deriving (via HKDF-SHA3-256) the AES key that decrypts
	// encrypted payload fields such as an API key secret.
	Secret string `koanf:"secret"`
	// SignatureTolerance bounds how old a signed request may be (replay protection).
	SignatureTolerance time.Duration `koanf:"signature_tolerance"`
	// MaxBodySize caps the request body size in bytes.
	MaxBodySize int64 `koanf:"max_body_size"`
	// SignatureHeader is the header carrying the "t=...,v1=..." signature.
	SignatureHeader string `koanf:"signature_header"`
}