config

type ArtifactStoreSpec struct {
	Type      string `json:"type" yaml:"type"`
	Endpoint  string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	Bucket    string `json:"bucket,omitempty" yaml:"bucket,omitempty"`
	Path      string `json:"path,omitempty" yaml:"path,omitempty"`
	Region    string `json:"region,omitempty" yaml:"region,omitempty"`
	PathStyle bool   `json:"path_style,omitempty" yaml:"path_style,omitempty"`
	AccessKey string `json:"access_key,omitempty" yaml:"access_key,omitempty"`
	SecretKey string `json:"secret_key,omitempty" yaml:"secret_key,omitempty"`
}

type Config struct {
	Providers      []providersdk.Instance           `json:"providers" yaml:"providers"`
	Pools          []PoolSpec                       `json:"pools,omitempty" yaml:"pools,omitempty"`
	Templates      map[string]TemplateSpec          `json:"templates,omitempty" yaml:"templates,omitempty"`
	Sources        map[string]SourceSpec            `json:"sources,omitempty" yaml:"sources,omitempty"`
	ArtifactStores map[string]ArtifactStoreSpec     `json:"artifact_stores,omitempty" yaml:"artifact_stores,omitempty"`
	Packages       map[string]resourcepack.Manifest `json:"packages,omitempty" yaml:"packages,omitempty"`

	Server ServerSpec `json:"server,omitzero" yaml:"server,omitempty"`
}

type DebugPolicySpec struct {
	RetainFailedResources bool `json:"retain_failed_resources,omitempty" yaml:"retain_failed_resources,omitempty"`
}

type OIDCSpec struct {
	// Issuer is the provider's issuer URL (e.g.
	// "https://keycloak.example.invalid/realms/boxy"), used both as the
	// discovery-document base and the expected "iss" claim value.
	Issuer string `json:"issuer,omitempty" yaml:"issuer,omitempty"`
	// ClientID is the OAuth2 client ID registered with the provider for
	// this boxy daemon.
	ClientID string `json:"client_id,omitempty" yaml:"client_id,omitempty"`
	// ClientSecret must be an "env:NAME" reference (see
	// pkg/providersdk.ResolveSecretRef), never a literal value -- the raw
	// secret must not live in a config file that might be committed or
	// copied around. Resolved once at daemon startup.
	ClientSecret string `json:"client_secret,omitempty" yaml:"client_secret,omitempty"`
	// RedirectURL is this daemon's own callback URL (e.g.
	// "https://boxy.example.invalid/auth/callback"), registered with the
	// provider as an allowed redirect target.
	RedirectURL string `json:"redirect_url,omitempty" yaml:"redirect_url,omitempty"`
	// RoleClaim names the ID token claim (e.g. "groups", "roles") whose
	// value(s) are looked up in RoleMapping to resolve a Boxy role. The
	// claim may be a single string or an array of strings (e.g. a
	// "groups" claim); every matching value's mapped role is considered
	// and the most-privileged one wins (admin > auditor > user) so a
	// principal in multiple groups isn't order-dependent on the
	// provider's own claim ordering.
	RoleClaim string `json:"role_claim,omitempty" yaml:"role_claim,omitempty"`
	// RoleMapping maps a RoleClaim value to a Boxy role
	// (user/auditor/admin).
	RoleMapping map[string]string `json:"role_mapping,omitempty" yaml:"role_mapping,omitempty"`
	// DefaultRole is used when no RoleClaim value matches RoleMapping.
	// Empty (the default) fails closed: a login with no mapped role is
	// rejected rather than silently granted the lowest role, since "IdP
	// claims drifted" and "this person genuinely has no boxy role" must
	// not look the same as a working login.
	DefaultRole string `json:"default_role,omitempty" yaml:"default_role,omitempty"`

	// CLIClientID, if set, enables `boxy login --oidc`: a public
	// (no-secret) OAuth2 client registered with the provider for the
	// RFC 8628 device-authorization grant, distinct from ClientID (the
	// confidential web client) since a CLI binary cannot safely hold a
	// client secret. Empty means CLI OIDC login is unavailable; the web
	// UI login above is unaffected either way.
	CLIClientID string `json:"cli_client_id,omitempty" yaml:"cli_client_id,omitempty"`
	// PersonalKeyMaxTTL bounds how long a self-service personal API key
	// (minted via CLI device-code login) may live, as a Go duration
	// string (e.g. "12h"). Empty defaults to 12h.
	PersonalKeyMaxTTL string `json:"personal_key_max_ttl,omitempty" yaml:"personal_key_max_ttl,omitempty"`
	// SessionTTL bounds how long a web-UI login session lasts before its
	// cookie is rejected, as a Go duration string (e.g. "12h"). Empty
	// defaults to 12h. Applies to every session regardless of how it was
	// established (OIDC or the bootstrapped local-admin account) -- there
	// is only one session mechanism (see ADR-0016), even though this knob
	// lives under server.oidc for parity with PersonalKeyMaxTTL.
	SessionTTL string `json:"session_ttl,omitempty" yaml:"session_ttl,omitempty"`
	// LoginLabel customizes the browser login button for the configured SSO
	// provider. Empty uses "Log in with single sign-on".
	LoginLabel string `json:"login_label,omitempty" yaml:"login_label,omitempty"`
	// LoginIcon is an optional URL or same-origin path to an image shown in
	// the browser login button.
	LoginIcon string `json:"login_icon,omitempty" yaml:"login_icon,omitempty"`
	// HideLocalLogin removes the local username/password form from the browser
	// login page. It is valid only when OIDC is configured.
	HideLocalLogin bool `json:"hide_local_login,omitempty" yaml:"hide_local_login,omitempty"`
}

type PoolPolicySpec struct {
	Preheat PreheatPolicySpec `json:"preheat,omitempty" yaml:"preheat,omitempty"`
	Recycle RecyclePolicySpec `json:"recycle,omitempty" yaml:"recycle,omitempty"`
	Debug   DebugPolicySpec   `json:"debug,omitempty" yaml:"debug,omitempty"`
}

type PoolSpec struct {
	Name string `json:"name" yaml:"name"`

	// Type is the pool type as expressed in config.
	//
	// Examples: "container", "vm", and (for docker-based container pools) "docker".
	Type string `json:"type" yaml:"type"`

	// Provider is an optional provider instance name (e.g. "docker-local").
	// Some pool types (like "docker") may imply a default provider.
	Provider string `json:"provider,omitempty" yaml:"provider,omitempty"`

	// Config is provider/pool-type-specific configuration.
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`

	// Agent optionally pins this pool to a specific agent instance ID
	// (embedded or remote), for when more than one agent supports the
	// same provider type. Empty means "resolve by provider type across
	// all available agents" (the only behavior possible before remote
	// agents existed).
	Agent string `json:"agent,omitempty" yaml:"agent,omitempty"`

	// Template references a reusable resource template. Empty preserves the
	// legacy inline pool configuration.
	Template string `json:"template,omitempty" yaml:"template,omitempty"`

	// Source and Packages are the optional inline resource configuration for a
	// pool. Template values are inherited before these pool values are applied.
	Source   string   `json:"source,omitempty" yaml:"source,omitempty"`
	Packages []string `json:"packages,omitempty" yaml:"packages,omitempty"`

	// Policy is the pool policy surface in config (examples use `policy:`).
	Policy PoolPolicySpec `json:"policy,omitempty" yaml:"policy,omitempty"`

	// Policies is accepted as an alias for Policy.
	Policies PoolPolicySpec `json:"policies,omitempty" yaml:"policies,omitempty"`
	// contains filtered or unexported fields
}

type PreheatPolicySpec struct {
	MinReady int `json:"min_ready,omitempty" yaml:"min_ready,omitempty"`
	MaxTotal int `json:"max_total,omitempty" yaml:"max_total,omitempty"`
	// contains filtered or unexported fields
}

type RecyclePolicySpec struct {
	MaxAge string `json:"max_age,omitempty" yaml:"max_age,omitempty"`
}

type SandboxResource struct {
	// Name is an optional label for the resource group.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	Pool  string `json:"pool" yaml:"pool"`
	Count int    `json:"count" yaml:"count"`

	// Packages are allocation-scoped resource package references applied to
	// each resource selected for this request.
	Packages []string `json:"packages,omitempty" yaml:"packages,omitempty"`
}

type SandboxSpec struct {
	Name      string            `json:"name" yaml:"name"`
	Resources []SandboxResource `json:"resources" yaml:"resources"`
	Policies  map[string]any    `json:"policies,omitempty" yaml:"policies,omitempty"`
	Metadata  map[string]any    `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type SecretSpec struct {
	Backend string `json:"backend,omitempty" yaml:"backend,omitempty"`
	Path    string `json:"path,omitempty" yaml:"path,omitempty"`
	Service string `json:"service,omitempty" yaml:"service,omitempty"`
}

type ServerSpec struct {
	Listen    string   `json:"listen,omitempty" yaml:"listen,omitempty"`
	Providers []string `json:"providers,omitempty" yaml:"providers,omitempty"`

	// UI controls whether the web dashboard is served alongside the API.
	// Pointer so nil = default (enabled). Set to false to disable.
	UI *bool `json:"ui,omitempty" yaml:"ui,omitempty"`

	// GRPCListen is the address the agent-transport gRPC server listens
	// on (see docs/adr/0005-remote-agent-transport-and-registration.md).
	// Empty means the default (":9091").
	GRPCListen string `json:"grpc_listen,omitempty" yaml:"grpc_listen,omitempty"`

	// AgentHeartbeatInterval is how often connected remote agents send
	// heartbeats, as a Go duration string (e.g. "15s"). Empty means the
	// default (15s). Note: --insecure/--dev is deliberately a CLI flag
	// only, never a config field, so a stale or copy-pasted config file
	// can't silently disable mTLS in a real deployment.
	AgentHeartbeatInterval string `json:"agent_heartbeat_interval,omitempty" yaml:"agent_heartbeat_interval,omitempty"`

	// DiagnosticsRetention controls how long the bounded server diagnostics
	// store retains events. Empty means the 14-day default.
	DiagnosticsRetention string `json:"diagnostics_retention,omitempty" yaml:"diagnostics_retention,omitempty"`

	// GRPCCertSANs are extra DNS names/IPs to include in the agent gRPC
	// server certificate's Subject Alternative Names, on top of the
	// always-included localhost/127.0.0.1/listen-host entries. Needed when
	// remote agents connect through a passthrough route or load balancer
	// using an external DNS name that doesn't match the literal
	// --grpc-listen host. Unlike --insecure above, this is safe to expose
	// as a config field: adding a SAN never weakens TLS/mTLS verification,
	// it only widens which hostname a client may present. Equivalent
	// repeatable CLI flag: --grpc-cert-san (fully overrides this value
	// when passed, does not merge with it).
	GRPCCertSANs []string `json:"grpc_cert_sans,omitempty" yaml:"grpc_cert_sans,omitempty"`

	// Secrets selects the server-owned credential backend. It is required when
	// a provider admission policy needs guest credentials; it is intentionally
	// not defaulted so deployment posture is explicit.
	Secrets SecretSpec `json:"secrets,omitzero" yaml:"secrets,omitempty"`

	// OIDC configures browser login against an external OpenID Connect
	// provider. Not configured by default: the web UI's bootstrapped local
	// admin account (see internal/cli/serve.go's bootstrapLocalAdmin) is
	// always available as a fallback/break-glass login regardless of this
	// setting. See docs/superpowers/specs/2026-08-28-oidc-ui-and-cli-auth-design.md.
	OIDC OIDCSpec `json:"oidc,omitzero" yaml:"oidc,omitempty"`
}

type SourceSpec struct {
	Store    string            `json:"store" yaml:"store"`
	Path     string            `json:"path" yaml:"path"`
	Digest   string            `json:"digest" yaml:"digest"`
	Format   string            `json:"format,omitempty" yaml:"format,omitempty"`
	OS       string            `json:"os,omitempty" yaml:"os,omitempty"`
	Provider string            `json:"provider,omitempty" yaml:"provider,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type TemplateSpec struct {
	Extends  string         `json:"extends,omitempty" yaml:"extends,omitempty"`
	Type     string         `json:"type,omitempty" yaml:"type,omitempty"`
	Provider string         `json:"provider,omitempty" yaml:"provider,omitempty"`
	Agent    string         `json:"agent,omitempty" yaml:"agent,omitempty"`
	Source   string         `json:"source,omitempty" yaml:"source,omitempty"`
	Config   map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
	Packages []string       `json:"packages,omitempty" yaml:"packages,omitempty"`
}