api

type AuthConfig interface {
	// contains filtered or unexported methods
}

type AuthConfigs []AuthConfig

type ClickHouseConfig struct {
	// URL is the ClickHouse connection string for the shared analytics cluster.
	// When empty, analytics writes are silently discarded.
	// Example: "clickhouse://default:password@clickhouse:9000?secure=false&skip_verify=true"
	URL string `toml:"url"`

	// AnalyticsURL is the base URL for workspace-specific analytics connections.
	// Unlike URL, this endpoint receives per-workspace credentials injected at
	// connection time by the analytics service. Only used when both this field
	// and a [VaultConfig] are configured.
	// Example: "http://clickhouse:8123/default"
	AnalyticsURL string `toml:"analytics_url"`
}

type Config struct {
	// InstanceID identifies this particular API server instance. Used in log
	// attribution, Kafka consumer group membership, and cache invalidation
	// messages so that a node can ignore its own broadcasts.
	InstanceID string `toml:"instance_id"`

	// Platform identifies the cloud platform where this node runs. Examples
	// include "aws", "gcp", "hetzner", and "kubernetes". Appears in structured
	// logs and metrics labels for filtering by infrastructure.
	Platform string `toml:"platform"`

	// Image is the container image identifier, such as "unkey/api:v1.2.3".
	// Logged at startup for correlating deployments with behavior changes.
	Image string `toml:"image"`

	// HttpPort is the TCP port the API server binds to. Ignored when
	// [TestConfig.Listener] is set, which is the case in test harnesses that
	// use ephemeral ports.
	HttpPort int `toml:"http_port" config:"default=7070,min=1,max=65535"`

	// Region is the geographic region identifier, such as "us-east-1" or "eu-west-1".
	// Included in structured logs and used by the key service when recording
	// which region served a verification request.
	Region string `toml:"region" config:"default=unknown"`

	// RedisURL is the connection string for the Redis instance backing
	// distributed rate limiting counters and usage tracking.
	// Example: "redis://redis:6379"
	RedisURL string `toml:"redis_url" config:"required,nonempty"`

	Observability config.Observability `toml:"observability"`

	// MaxRequestBodySize caps incoming request bodies at this many bytes.
	// The zen server rejects requests exceeding this limit with a 413 status.
	// Set to 0 or negative to disable the limit. Defaults to 10 MiB.
	MaxRequestBodySize int64 `toml:"max_request_body_size" config:"default=10485760"`

	// Database configures MySQL connections. See [config.DatabaseConfig].
	Database config.DatabaseConfig `toml:"database"`

	// ClickHouse configures analytics storage. See [ClickHouseConfig].
	ClickHouse ClickHouseConfig `toml:"clickhouse"`

	// TLS provides filesystem paths for HTTPS certificate and key.
	// See [config.TLSFiles].
	TLS config.TLS `toml:"tls"`

	// Vault configures the encryption/decryption service. See [config.VaultConfig].
	Vault config.VaultConfig `toml:"vault"`

	// Control configures the deployment management service. See [config.ControlConfig].
	Control config.ControlConfig `toml:"control"`

	// PortalBaseURL is the base URL for the customer portal.
	// Example: "https://portal.unkey.com"
	// Used to construct session redirect URLs in portal.createSession responses.
	// When a customer has a verified custom domain, that domain is used instead.
	PortalBaseURL string `toml:"portal_base_url" config:"default=https://portal.unkey.com"`

	// Auth configures the ordered authentication resolver chain.
	Auth AuthConfigs `toml:"auth"`

	// Pprof configures Go profiling endpoints. See [config.PprofConfig].
	// When nil (section omitted), pprof endpoints are not registered.
	Pprof *config.PprofConfig `toml:"pprof"`

	// Clock provides time operations and is injected for testability. Production
	// callers set this to [clock.New]; tests can substitute a fake clock to
	// control time progression.
	Clock clock.Clock `toml:"-"`

	// TLSConfig is the resolved [tls.Config] built from [TLSFiles.CertFile]
	// and [TLSFiles.KeyFile] at startup. This field is populated by the CLI
	// entrypoint after loading the config file and must not be set in TOML.
	TLSConfig *tls.Config `toml:"-"`

	// Test groups runtime-only overrides for integration tests. All fields are
	// zero in production and cannot be set from TOML.
	Test TestConfig `toml:"-"`
}

type JWTAuthConfig struct {
	// Issuer is the expected JWT iss claim for this auth entry.
	Issuer string `toml:"issuer"`

	// Audience is the optional JWT aud claim required for this auth entry.
	Audience string `toml:"audience"`

	// Secrets configures HS256 verification. Dashboard proxy routes sign tokens
	// with the first configured secret. The API verifies incoming tokens against
	// every secret in the ordered list so a new secret can be added before
	// removing an old one.
	Secrets []string `toml:"secrets"`

	// JWKSURL configures RS256 verification. The API fetches the JSON Web Key
	// Set from this URL on first use, verifies incoming tokens against the
	// returned RSA signing keys, and refetches the set when a token fails
	// verification against every cached key so key rotations are picked up
	// without a restart.
	JWKSURL string `toml:"jwks_url"`

	// Provider names the permission dialect carried by this entry's tokens.
	// Empty means tokens already carry canonical Unkey permissions. "workos"
	// means tokens carry WorkOS slugs that the resolver translates into Unkey
	// permissions after verification. This is an explicit opt-in rather than
	// an inference from the issuer, so any issuer (including custom auth
	// domains) can be configured without changing how translation is selected.
	Provider string `toml:"provider"`
}

type PortalSessionAuthConfig struct{}

type RootKeyAuthConfig struct {
	// Enabled may be set to true for explicitness. Setting it to false is a
	// configuration error; remove the auth entry instead.
	Enabled *bool `toml:"enabled"`
}

type TestConfig struct {
	// Enabled relaxes certain security checks and trusts client-supplied
	// headers like X-Test-Time that would normally be rejected.
	Enabled bool

	// Counter overrides the distributed counter backend. Multi-node tests
	// share one in-memory counter across all nodes so replays sync in
	// microseconds rather than blocking on real Redis I/O.
	Counter counter.Counter

	// Listener is a pre-created net.Listener for the HTTP server. When set,
	// the server uses this listener instead of binding to HttpPort. Tests
	// use ephemeral ports (":0") to avoid conflicts when running in parallel.
	Listener net.Listener
}