server

type AssignmentRow struct {
	Experiment string `json:"experiment"`
	Status     string `json:"status"`
	Variant    string `json:"variant,omitempty"`
	Control    bool   `json:"control,omitempty"`
}

type AuditConfig struct {
	Rotation AuditRotation `json:"rotation"`
	Export   AuditExport   `json:"export"`
}

type AuditEntry struct {
	Seq       uint64            `json:"seq"`
	Time      time.Time         `json:"time"`
	Actor     string            `json:"actor"`
	Action    string            `json:"action"`
	Target    string            `json:"target,omitempty"`
	IP        string            `json:"ip,omitempty"`
	RequestID string            `json:"requestId,omitempty"`
	Details   map[string]string `json:"details,omitempty"`
	Redacted  bool              `json:"redacted,omitempty"`
	Prev      string            `json:"prev"`
	Hash      string            `json:"hash"`
}

type AuditExport struct {
	Sinks               []AuditSink `json:"sinks,omitempty"`
	BatchSize           int         `json:"batchSize,omitempty"`           // entries per delivery; default 100, max 1000
	PollIntervalSeconds int         `json:"pollIntervalSeconds,omitempty"` // idle re-check; appends wake sinks at once; default 5
	MaxBackoffSeconds   int         `json:"maxBackoffSeconds,omitempty"`   // retry backoff cap; default 300
}

type AuditResponse struct {
	Entries     []AuditEntry `json:"entries"`
	Next        uint64       `json:"next"` // pass as ?since= to get entries after these
	Total       int          `json:"total"`
	Verified    bool         `json:"verified"` // whole chain, every segment, not just this page
	VerifyError string       `json:"verifyError,omitempty"`
	Head        string       `json:"head"`
	// ADR-0041: Signed is true when checkpoint signing is on; Checkpoints
	// counts the checkpoints that verified (their signatures too when Signed),
	// LastCheckpoint is the seq of the newest one whose signature verified.
	Signed         bool   `json:"signed,omitempty"`
	Checkpoints    int    `json:"checkpoints,omitempty"`
	LastCheckpoint uint64 `json:"lastCheckpoint,omitempty"`
}

type AuditRotation struct {
	MaxBytes      int64 `json:"maxBytes,omitempty"`
	MaxAgeSeconds int64 `json:"maxAgeSeconds,omitempty"`
}

type AuditSink struct {
	Name   string `json:"name"`             // [a-z0-9-], unique: names the cursor file and the metrics label
	Type   string `json:"type"`             // webhook | splunk-hec | syslog
	Format string `json:"format,omitempty"` // native (default: the stored entry, byte for byte) | ocsf

	URL        string               `json:"url,omitempty"`        // webhook, splunk-hec: https only
	Headers    map[string]SecretRef `json:"headers,omitempty"`    // webhook: e.g. DD-API-KEY
	HMACSecret *SecretRef           `json:"hmacSecret,omitempty"` // webhook: X-Halo-Signature over timestamp.body
	Token      *SecretRef           `json:"token,omitempty"`      // splunk-hec (required)
	Index      string               `json:"index,omitempty"`      // splunk-hec
	SourceType string               `json:"sourceType,omitempty"` // splunk-hec; default halo:audit

	Address  string `json:"address,omitempty"`  // syslog: host:port, RFC 5425 (TLS, octet counting)
	Facility int    `json:"facility,omitempty"` // syslog: 0 = 13 (log audit)

	CAFile         string `json:"caFile,omitempty"`   // trust this CA bundle instead of the system roots
	CertFile       string `json:"certFile,omitempty"` // client certificate (mTLS), with KeyFile
	KeyFile        string `json:"keyFile,omitempty"`
	TimeoutSeconds int    `json:"timeoutSeconds,omitempty"` // per delivery; default 10
}

type AuditVerifyOptions struct {
	// Verifier checks checkpoint signatures (ADR-0041); nil checks links only.
	Verifier bundle.Verifier
	// Anchor is a checkpoint entry held outside the log (the newest one your
	// SIEM received): the log must still hold it unchanged, so cutting entries
	// from the end, or recomputing the chain, is caught.
	Anchor *AuditEntry
	// Export is the SIEM's copy (LoadExport): every seq both hold must have
	// the same hash and content, unless the log's entry is a vouched-for
	// redaction, and the log must reach the export's last seq. Unlike Anchor,
	// this compares content, not just the newest checkpoint.
	Export map[uint64]ExportedEntry
	// RequireCurrentKey: the newest verified checkpoint must be signed by the
	// Verifier's first key (the current one): a leaked previous key cannot
	// rewrite the tail after a rotation.
	RequireCurrentKey bool
}

type AuditVerifyResult struct {
	Entries        uint64 `json:"entries"`
	Segments       int    `json:"segments"` // files read, the active one included
	Head           string `json:"head"`
	Error          string `json:"error,omitempty"`
	First          uint64 `json:"first,omitempty"` // seq of the oldest entry, when retention removed older ones
	Checkpoints    int    `json:"checkpoints,omitempty"`
	LastCheckpoint uint64 `json:"lastCheckpoint,omitempty"`
	UnsignedTail   uint64 `json:"unsignedTail,omitempty"`
	Anchored       bool   `json:"anchored,omitempty"` // the anchor was found unchanged
	// RedactedSinceExport counts entries that differ from the SIEM export only
	// because an erasure redacted them (each vouched for).
	RedactedSinceExport int `json:"redactedSinceExport,omitempty"`
}

type AuthMethods struct {
	OIDC bool `json:"oidc"`
	SAML bool `json:"saml"`
}

type Backend interface {
	storage.Opener // device, request, session-revocation, SCIM logs
	storage.KV     // enrollment tokens, login states, server-side sessions, claims, workload jti
	// AppendAudit chains e after the current head under a lock held across
	// replicas, filling Seq, Prev and Hash.
	AppendAudit(ctx context.Context, e AuditEntry) error
	// EachAudit streams entries with seq >= from, oldest first, with their
	// stored bytes, until fn returns false. A row that does not decode is
	// passed zero-valued, so verification breaks there.
	EachAudit(ctx context.Context, from uint64, fn func(raw []byte, e AuditEntry) bool) error
	// EachAuditDesc streams entries newest first until fn returns false,
	// reading only as many rows as it is given (paged ORDER BY seq DESC).
	EachAuditDesc(ctx context.Context, fn func(raw []byte, e AuditEntry) bool) error
	// AuditHead is the newest entry's seq and hash.
	AuditHead(ctx context.Context) (uint64, string, error)
	// RolloutStates is where the controller's rollout state lives.
	RolloutStates() rollout.StateStore
	// Docs lists every document of kind (verdicts: one per experiment).
	Docs(ctx context.Context, kind string) ([][]byte, error)
	// Leased runs fn on exactly one replica at a time (lease name) until ctx
	// ends; docs writes through the view fn gets are fenced by that lease.
	Leased(ctx context.Context, name string, fn func(ctx context.Context, docs rollout.Docs))
	// ApplyBudget adds usage unless batch was applied before (atomic, any replica).
	ApplyBudget(ctx context.Context, batch string, incs []pgstore.BudgetCounter) (duplicate bool, err error)
	// PruneBudgets drops buckets older than retention and stale batch ids,
	// on the store's clock and independent of any replica's policy.
	PruneBudgets(ctx context.Context, retention time.Duration) (int64, error)
	// BudgetCounters reads the given (budget, key) counters; nil = all.
	BudgetCounters(ctx context.Context, keys [][2]string) ([]pgstore.BudgetCounter, error)
	// ClaimPending makes requestID the one pending access request for dedupe
	// (atomic across replicas; see pgstore.DB.ClaimPending). ReleasePending drops it.
	ClaimPending(ctx context.Context, dedupe, requestID string, holder func(id string) (known, pending bool)) (bool, error)
	ReleasePending(ctx context.Context, dedupe, requestID string) error

	// Ping fails when the backend is unreachable (/readyz).
	Ping(ctx context.Context) error
	// contains filtered or unexported methods
}

type BreakGlass struct {
	Enabled      bool
	User         string
	Hash         string
	AllowedCIDRs []netip.Prefix
}

type BreakGlassLogin struct {
	User     string `json:"user"`
	Password string `json:"password"`
}

type BudgetsResponse struct {
	Budgets []budget.Status `json:"budgets"`
	At      time.Time       `json:"at"`
}

type Capabilities struct {
	KillSwitch bool `json:"killSwitch"`
	// Roles and Permissions are the caller's (ADR-0015), so the console hides
	// actions the server would refuse. The server enforces regardless.
	Roles       []string `json:"roles"`
	Permissions []string `json:"permissions"`
	// Bindings say over which rings and units each role holds (ADR-0037);
	// a permission may hold only for some resources.
	Bindings []policy.Grant `json:"bindings"`
}

type Catalog struct {
	Harnesses []HarnessPin  `json:"harnesses"`
	Launchers []string      `json:"launchers"`
	Items     []CatalogItem `json:"items"`
}

type CatalogItem struct {
	Kind string `json:"kind"`
	Item string `json:"item"`
	Desc string `json:"desc,omitempty"`
	// Ticket lists the patterns (regular expressions, matched whole) a change
	// ticket must match when this caller requests this item: the approval
	// rules (ADR-0030) covering what approving it changes. Empty: none needed.
	Ticket []string `json:"ticket,omitempty"`
}

type ChannelRelease struct {
	Channel    string     `json:"channel"`
	Published  bool       `json:"published"`
	Digest     string     `json:"digest,omitempty"`
	Seq        uint64     `json:"seq,omitempty"`
	ExpiresAt  *time.Time `json:"expiresAt,omitempty"`
	Expired    bool       `json:"expired"`
	Stale      bool       `json:"stale"`
	Suspicious bool       `json:"suspicious"`
	Error      string     `json:"error,omitempty"`
	Devices    int        `json:"devices"` // ring hosts reporting this channel's digest
}

type CloudAgentsView struct {
	Tasks  []cloudagents.Task  `json:"tasks"`
	Alerts []cloudagents.Alert `json:"alerts"`
	// Configured reports what halo-server can see and do: the webhook
	// receiver and each vendor API client.
	Configured map[string]bool `json:"configured"`
}

type CloudKillRequest struct {
	Scope  string `json:"scope"`
	Name   string `json:"name"`
	Reason string `json:"reason"`
	DryRun *bool  `json:"dryRun,omitempty"`
}

type CloudKillResponse struct {
	DryRun       bool                 `json:"dryRun"`
	Actions      []cloudagents.Action `json:"actions"`
	Unattributed int                  `json:"unattributed"`
	NextSteps    []string             `json:"next_steps"`
}

type Config struct {
	PolicyDir    string
	Token        string // bearer token required by POST /api/v1/fleet/report; must be non-empty
	VerdictsPath string // optional JSON file written by `halo exp analyze`
	Store        Store
	Log          *slog.Logger
	Now          func() time.Time
	Web          fs.FS // nil = placeholder page (defaults to the embedded console)
	// TrustedProxies are the reverse proxies whose X-Forwarded-For is believed
	// for per-client rate limiting. Empty = use the TCP peer address only.
	TrustedProxies []netip.Prefix
	// APIRate and APIBurst are each authenticated principal's request budget
	// on console/API routes (requests per second and burst); 0 = unlimited.
	APIRate  float64
	APIBurst int

	// Portal auth/self-service. SessionKey signs cookies (>=32 bytes); required unless DevUser is set.
	SessionKey       []byte
	OIDCClientSecret string
	Portal           Portal
	DataDir          string // request/device/session-revocation logs ("" = in-memory)
	// Backend, when set, replaces DataDir and in-process state with shared
	// state so several replicas can serve (ADR-0021).
	Backend   Backend
	DeviceTTL time.Duration // device token lifetime after enrollment (0 = DefaultDeviceTTL)
	Writer    PolicyWriter  // nil: approvals are recorded but need manual policy changes

	// Kill switch. KillStore nil = opened from DataDir. GET
	// /api/v1/gateway/killswitch is served only when both KillKey (signs the
	// list) and GatewayToken (gateways' bearer token) are set; GET
	// /api/v1/fleet/killswitch (device token) whenever KillKey is set.
	KillStore *controller.KillStore
	// KillKey signs the kill list: a file key, or a KMS / external signer
	// (internal/signer, ADR-0038), whose signatures are cached briefly.
	KillKey      bundle.Signer
	GatewayToken string
	// Optional per-capability gateway tokens. When one is set it is the only
	// token that capability accepts (the shared GatewayToken no longer does);
	// empty falls back to GatewayToken. Each also enables its endpoint alone.
	GatewayKillswitchToken string
	GatewayPostureToken    string
	GatewayBudgetToken     string
	GatewayDirectoryToken  string
	GatewayDLPToken        string // POST /api/v1/gateway/dlp/events (ADR-0033)
	// GatewayDLPTokens maps a gateway name to its own DLP token. An event
	// batch sent with one is attributed to that gateway (a gateway name in the
	// body that differs is refused); one sent with GatewayDLPToken or the
	// shared token is recorded as gateway:unverified with the name it claims.
	// Setting any enables the endpoint.
	GatewayDLPTokens map[string]string

	// PostureMaxAge: a device whose last report is older is stale (GET
	// /api/v1/gateway/posture, served whenever GatewayToken is set). 0 = DefaultPostureMaxAge.
	PostureMaxAge time.Duration

	// Audit: log rotation and SIEM export (ADR-0016). Both need DataDir.
	// Export runs only while RunAuditExport does.
	Audit AuditConfig
	// Retention bounds the unbounded stores (ADR-0040); the zero value keeps
	// everything. The sweep runs only while RunMaintenance does.
	Retention Retention
	// AuditSigner signs audit checkpoints (ADR-0041): a file key, or a KMS /
	// external signer (internal/signer). nil leaves the chain unsigned.
	// Checkpoints are appended every AuditCheckpointInterval (0 =
	// DefaultCheckpointInterval) while RunMaintenance runs, and at rotation.
	AuditSigner             bundle.KeySigner
	AuditCheckpointInterval time.Duration
	// AuditPreviousKeys are earlier audit keys' public halves: checkpoints and
	// vouches they signed keep verifying after a rotation (ADR-0041).
	AuditPreviousKeys []bundle.PublicKeyVerifier
	// AuditSigningEnableHead allows writing the audit.signing.enabled marker
	// over a log that holds entries but was never signed (first-ever enable),
	// or recreating a missing signing record over a signed log, but only when
	// it equals the log's head seq at that moment (a stale value is refused),
	// and only once per process (ADR-0041). 0 = off.
	AuditSigningEnableHead uint64

	// SCIM 2.0 provisioning at /scim/v2 (ADR-0022). SCIMTokenSHA256 holds the
	// hex SHA-256 of each accepted bearer token (two while rotating); empty =
	// SCIM off. SCIMAuthoritative: the directory, not the login's groups claim
	// or a device's enrollment groups, decides who is active and their groups.
	// SCIMStore nil = opened from DataDir.
	SCIMTokenSHA256   []string
	SCIMAuthoritative bool
	SCIMStore         SCIMStore
	// WorkloadKey signs workload credentials minted by POST
	// /api/v1/token/exchange (ADR-0023); nil disables the endpoint.
	WorkloadKey ed25519.PrivateKey

	// Cloud agents (ADR-0034). CloudWebhookSecrets verify GitHub deliveries
	// to POST /api/v1/cloud-agents/webhooks/github (two while rotating; none =
	// 404). CloudClients cancel and pause tasks; a nil client is not attempted.
	CloudWebhookSecrets []string
	CloudClients        cloudagents.Clients

	// Admin access (ADR-0036). Session bounds console sessions (absolute TTL
	// and sliding idle timeout). ServiceTokenMaxTTL caps service-account token
	// lifetimes (0 = DefaultServiceTokenMaxTTL). BreakGlass is the sealed local
	// admin account. EntraGraphURL is where identity.groupsOverage: graph
	// resolves groups ("" = DefaultGraphURL).
	Session            SessionPolicy
	ServiceTokenMaxTTL time.Duration
	BreakGlass         BreakGlass
	EntraGraphURL      string
	// SAML turns on SAML 2.0 login next to OIDC (ADR-0039); nil = off.
	SAML *SAMLConfig

	// DevUser disables authentication and acts as this user. INSECURE: local demos only.
	// DevRoles are its roles (ADR-0015); DevAdmin adds RoleAdmin.
	DevUser   string
	DevGroups []string
	DevRoles  []string
	DevAdmin  bool
	// contains filtered or unexported fields
}

type ConvergenceView struct {
	Total    int            `json:"total"`
	OnDigest int            `json:"onDigest"`
	Other    int            `json:"other"`
	Digests  map[string]int `json:"digests"`
}

type CreateServiceTokenRequest struct {
	Name        string          `json:"name"`
	Role        string          `json:"role"`
	Scope       json.RawMessage `json:"scope,omitempty"`
	Description string          `json:"description,omitempty"`
	Owner       string          `json:"owner,omitempty"`
	TTL         string          `json:"ttl,omitempty"`
}

type CreateServiceTokenResponse struct {
	Token        string           `json:"token"`
	ServiceToken ServiceTokenInfo `json:"serviceToken"`
}

type Device struct {
	ID        string    `json:"id"` // uuid
	Hash      string    `json:"hash,omitempty"`
	UserID    string    `json:"userID"`
	Groups    []string  `json:"groups,omitempty"` // IdP groups at enrollment; ring is otherwise resolved live
	CreatedAt time.Time `json:"createdAt"`
	LastSeen  time.Time `json:"lastSeen"`
	// LastAuth is when the user last authenticated for this device (enrollment);
	// Groups date from then. The token stops working at ExpiresAt: re-enroll.
	LastAuth  time.Time `json:"lastAuth,omitzero"`
	ExpiresAt time.Time `json:"expiresAt,omitzero"`
	Revoked   bool      `json:"revoked"`
}

type DeviceDetail struct {
	Device  Device `json:"device"`
	Last    *Host  `json:"last,omitempty"`
	History []Host `json:"history"` // newest first, at most MaxHistory
}

type EgressRequest struct {
	Agent string `json:"agent,omitempty"`
	URL   string `json:"url,omitempty"`
	Skill string `json:"skill,omitempty"`
}

type EraseReport struct {
	// Pseudonym replaced the subject in the records kept (audit entries,
	// requests the subject decided); it is random, so it cannot be linked back.
	Pseudonym string            `json:"pseudonym,omitempty"`
	DryRun    bool              `json:"dryRun,omitempty"`
	Erased    map[string]int    `json:"erased"`
	Retained  map[string]string `json:"retained"`
	Errors    map[string]string `json:"errors,omitempty"`
}

type EraseRequest struct {
	User string `json:"user"`
	// Aliases are other identifiers of the same person to erase with User: an
	// OS user name or hostname fleet-token reports carry.
	Aliases []string `json:"aliases,omitempty"`
	Reason  string   `json:"reason"`
	DryRun  bool     `json:"dryRun,omitempty"`
}

type ExperimentDetail struct {
	ExperimentView
	Verdict *Verdict `json:"verdict,omitempty"`
}

type ExperimentView struct {
	Name     string                `json:"name"`
	Type     policy.ExperimentType `json:"type"`
	Axis     policy.Axis           `json:"axis"`
	Status   string                `json:"status"`
	Rings    []string              `json:"rings"`
	Variants []policy.Variant      `json:"variants"`
	Sample   float64               `json:"sampleRate,omitempty"`
	Metrics  policy.Metrics        `json:"metrics"`
	Stopping policy.Stopping       `json:"stopping"`
}

type ExportedEntry struct{ Hash, Digest string }

type FleetResponse struct {
	Hosts []Host      `json:"hosts"`
	Rings []RingStats `json:"rings"`
	Total int         `json:"total"`
	Drift int         `json:"driftHosts"`
}

type FreezeView struct {
	Incident *policy.ActiveFreeze           `json:"incident"`
	Rings    map[string]policy.FreezeStatus `json:"rings"`
}

type GitPolicyWriter struct {
	RepoDir   string
	ServedDir string // the served policy dir; Propose refuses if it overlaps RepoDir
	Subdir    string // policy root inside the repo ("" = repo root)
	Base      string // base branch, default "main"
	Opener    promote.PROpener
	// Git runs git in RepoDir and returns trimmed stdout (default: os/exec); injectable for tests.
	Git func(ctx context.Context, args ...string) (string, error)
	// contains filtered or unexported fields
}

type GuardrailVerdict struct {
	Metric string `json:"metric"`
	Result struct {
		Status        string  `json:"status"` // pass | fail | inconclusive
		Regression    float64 `json:"regression"`
		Lower         float64 `json:"lower"`
		Upper         float64 `json:"upper"`
		MaxRegression float64 `json:"maxRegression"`
	} `json:"result"`
}

type HarnessPin struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type HarnessStatus struct {
	Want      string `json:"want"`
	Installed string `json:"installed"`
}

type Host struct {
	Report
	LastSeen time.Time `json:"lastSeen"`
}

type ImportReport struct {
	Copied  map[string]int64 // e.g. "journal/devices", "audit", "reports", "docs/rollout-state"
	Skipped map[string]int   // torn or undecodable source lines, per file
	Head    string           // audit chain head hash after the copy
}

type IssueView struct {
	Severity string `json:"severity"`
	Path     string `json:"path"`
	Message  string `json:"message"`
}

type Launch struct {
	Launcher   string     `json:"launcher"`
	Filename   string     `json:"filename,omitempty"` // devcontainer
	Snippet    string     `json:"snippet,omitempty"`  // devcontainer
	URL        string     `json:"url,omitempty"`      // codespaces, coder
	Token      string     `json:"token,omitempty"`    // laptop
	ExpiresAt  *time.Time `json:"expiresAt,omitempty"`
	TTLSeconds int        `json:"ttlSeconds,omitempty"`
	Bash       string     `json:"bash,omitempty"`
	PowerShell string     `json:"powershell,omitempty"`
}

type LauncherSetup struct {
	Launcher string `json:"launcher"`
	Missing  string `json:"missing"` // what the operator must change in the portal config
}

type Me struct {
	Principal
	Permissions []string        `json:"permissions"` // the console hides what these do not allow
	Ring        string          `json:"ring"`
	Release     string          `json:"release,omitempty"`
	Variants    []AssignmentRow `json:"variants"`
	Profile     *profileSummary `json:"profile,omitempty"`
	SelfService bool            `json:"selfService"`
	Launchers   []string        `json:"launchers"` // enabled in policy AND configured on this server
	// LauncherSetup lists enabled launchers this server cannot run yet (admins only).
	LauncherSetup []LauncherSetup `json:"launcherSetup,omitempty"`
	Requestable   []string        `json:"requestable"`
	OptInRings    []string        `json:"optInRings"` // rings the user may still ask to join
	SupportURL    string          `json:"supportURL,omitempty"`
	DevInsecure   bool            `json:"devInsecure,omitempty"`
}

type MyDevice struct {
	Device  Device `json:"device"`
	Last    *Host  `json:"last,omitempty"`
	Expired bool   `json:"expired"` // the token no longer works: re-enroll
}

type MyDevices struct {
	Devices []MyDevice             `json:"devices"`
	Posture gateway.PostureVerdict `json:"posture"`
}

type PGBackend struct {
	*pgstore.DB
	LeaseTTL time.Duration // Leased lease length; 0 = 15s
}

type PatchSummary struct {
	MCPServers []string `json:"mcpServers,omitempty"` // "name url"
	Hooks      []string `json:"hooks,omitempty"`      // "event matcher"
	Env        []string `json:"env,omitempty"`        // variable names
	Overrides  []string `json:"overrides,omitempty"`  // top-level keys
}

type PendingErasure struct {
	ID          string    `json:"id"`
	RequestedBy string    `json:"requestedBy"`
	ExpiresAt   time.Time `json:"expiresAt"`
	Confirm     string    `json:"confirm"` // the route a different admin calls
	User        string    `json:"user,omitempty"`
	Aliases     []string  `json:"aliases,omitempty"`
	Reason      string    `json:"reason,omitempty"`
}

type PolicyView struct {
	Org         string           `json:"org"`
	Gateway     *policy.Gateway  `json:"gateway,omitempty"`
	Rings       []RingView       `json:"rings"`
	Profiles    []string         `json:"profiles"`
	Experiments []ExperimentView `json:"experiments"`
	Issues      []IssueView      `json:"issues"`
}

type PolicyWriter interface {
	Propose(ctx context.Context, org *policy.Org, req Request, approver string) (prURL string, err error)
}

type Portal struct {
	// BaseURL is the externally visible URL of this server; baked into launch artifacts and enroll scripts.
	BaseURL string `json:"baseURL"`
	// Registry is the OCI repository halod pulls releases from.
	Registry string `json:"registry"`
	// RegistryPlainHTTP reads the registry over http (local/dev registries only).
	RegistryPlainHTTP bool `json:"registryPlainHTTP"`
	// PubKeyFile is the release-verification public key (PEM); served at /enroll/release.pub.
	PubKeyFile string `json:"pubKeyFile"`
	// DevcontainerFeature is the OCI ref of the halos Dev Container Feature.
	DevcontainerFeature string `json:"devcontainerFeature"`
	DevcontainerImage   string `json:"devcontainerImage"`
	// CodespacesURL / CoderURL are URL templates; {ring} and {user} are query-escaped.
	CodespacesURL string `json:"codespacesURL"`
	CoderURL      string `json:"coderURL"`
	// HalodURL is the halod download template with {os} and {arch}; HalodSHA256 pins each "<os>-<arch>" build.
	HalodURL    string            `json:"halodURL"`
	HalodSHA256 map[string]string `json:"halodSHA256"`
	// PolicyRepoDir is a dedicated git clone the PolicyWriter branches from (never the served policy dir).
	PolicyRepoDir string `json:"policyRepoDir"`
	PolicySubdir  string `json:"policySubdir"`
	PolicyBase    string `json:"policyBase"`
	// PolicyForge (gh|github|gitlab; empty = autodetect from the clone's origin) and PolicyForgeBaseURL
	// (GitHub Enterprise Server / self-managed GitLab API root) choose where the writer opens its PRs/MRs.
	PolicyForge        string `json:"policyForge"`
	PolicyForgeBaseURL string `json:"policyForgeBaseURL"`
	// SupportURL is where developers go when something breaks (a Slack channel, a ticket queue); shown on the kiosk.
	SupportURL string `json:"supportURL"`
	// Secrets are referenced by file path so they never sit in the JSON itself.
	SessionKeyFile       string `json:"sessionKeyFile"`
	OIDCClientSecretFile string `json:"oidcClientSecretFile"`

	PubKeyPEM string `json:"-"` // loaded from PubKeyFile by the caller
}

type Principal struct {
	ID     string   `json:"id"`
	Groups []string `json:"groups"`
	Roles  []string `json:"roles"`
	Admin  bool     `json:"admin"` // holds RoleAdmin globally (a scoped admin shows in Bindings only, ADR-0037); kept for API clients that predate roles
	// Kind is empty for a human console session, else KindServiceAccount or
	// KindBreakGlass (ADR-0036).
	Kind string `json:"kind,omitempty"`
	// OnBehalfOf is the human who created a service token: separation-of-
	// duties checks treat the token as that person (ADR-0036).
	OnBehalfOf string `json:"onBehalfOf,omitempty"`
	// Bindings are the roles p holds and over which scope (ADR-0037); Roles
	// is their distinct role names. Authorization reads Bindings only.
	Bindings []policy.Grant `json:"bindings"`
}

type ReleasesResponse struct {
	Rings    []RingRelease `json:"rings"`
	Stale    bool          `json:"stale"` // some ring shows cached state because the registry could not be read
	Registry string        `json:"registry"`
}

type Report struct {
	Time      time.Time                `json:"time"`
	Hostname  string                   `json:"hostname"`
	User      string                   `json:"user"`
	Device    string                   `json:"device,omitempty"` // set by the server for device-token reports
	Ring      string                   `json:"ring"`
	Digest    string                   `json:"digest"`
	Harnesses map[string]HarnessStatus `json:"harnesses"`
	Drift     []string                 `json:"drift"`
	LastError string                   `json:"lastError,omitempty"`
	ErrorCode string                   `json:"errorCode,omitempty"` // classifies LastError, e.g. untrusted_owner, sandbox_unavailable, no_subject_for_experiment
	// Experiment/Variant: the client-axis experiment variant the host applied.
	Experiment string `json:"experiment,omitempty"`
	Variant    string `json:"variant,omitempty"`
	Killed     bool   `json:"killed,omitempty"` // Experiment is kill-switched; the host runs the ring release
}

type Request struct {
	ID            string     `json:"id"`
	User          string     `json:"user"`
	Kind          string     `json:"kind"` // mcp-server | model | ring-opt-in | harness
	Item          string     `json:"item"`
	Justification string     `json:"justification"`
	Ring          string     `json:"ring,omitempty"` // requester's ring at request time
	Status        string     `json:"status"`
	CreatedAt     time.Time  `json:"createdAt"`
	DecidedBy     string     `json:"decidedBy,omitempty"`
	DecidedAt     *time.Time `json:"decidedAt,omitempty"`
	PRURL         string     `json:"prURL,omitempty"`
	Note          string     `json:"note,omitempty"`
	// Ticket is the change ticket reference (Jira, ServiceNow, ...), required
	// when an approval rule covering the requester asks for one (ADR-0030).
	Ticket string `json:"ticket,omitempty"`
	// Target is the requester's ring and unit chain when filed: what the
	// approval rules are matched against.
	Target *policy.ChangeTarget `json:"target,omitempty"`
	// Approvals recorded so far; the request is decided when they meet every
	// covering rule's quorum (one approval when no rule covers it).
	Approvals []policy.Approval `json:"approvals,omitempty"`
}

type Retention struct {
	FleetReports time.Duration // reporters not seen for this long, with their history
	Requests     time.Duration // decided access requests, from the decision
	Devices      time.Duration // revoked devices from their last use, expired ones from expiry
	Audit        time.Duration // audit entries; whole rotated segments on the file backend
	Interval     time.Duration // how often the sweep runs; 0 = DefaultRetentionInterval
}

type Revocation struct {
	JTI     string `json:"jti,omitempty"`
	Subject string `json:"subject,omitempty"`
	// RevokedBefore: a subject's credentials issued at or before it are dead.
	RevokedBefore *time.Time `json:"revokedBefore,omitempty"`
	Expires       time.Time  `json:"expires"` // the row is dropped then: nothing it matches can still be valid
	By            string     `json:"by"`
	Reason        string     `json:"reason"`
	At            time.Time  `json:"at"`
}

type RevocationsResponse struct {
	Revocations []Revocation `json:"revocations"`
}

type RevokeRequest struct {
	JTI     string `json:"jti,omitempty"`
	Subject string `json:"subject,omitempty"`
	Reason  string `json:"reason"`
}

type RevokeServiceTokenRequest struct {
	Reason string `json:"reason"`
}

type RingRelease struct {
	Ring         string           `json:"ring"`
	Published    bool             `json:"published"` // a verified pointer exists
	Org          string           `json:"org,omitempty"`
	Digest       string           `json:"digest,omitempty"`
	Seq          uint64           `json:"seq,omitempty"`
	IssuedAt     *time.Time       `json:"issuedAt,omitempty"`
	ExpiresAt    *time.Time       `json:"expiresAt,omitempty"`
	ExpiresInSec int64            `json:"expiresInSeconds,omitempty"`
	Expired      bool             `json:"expired"`
	ExpiringSoon bool             `json:"expiringSoon"` // <48h left (and not yet expired)
	Stale        bool             `json:"stale"`
	Suspicious   bool             `json:"suspicious"` // registry served a foreign-org or regressed pointer; last good shown
	Error        string           `json:"error,omitempty"`
	Channels     []ChannelRelease `json:"channels"`    // client-axis experiment channels the ring's release routes to
	Convergence  ConvergenceView  `json:"convergence"` // hosts on the ring digest or one of its channels' digests are converged
	Drift        int              `json:"driftHosts"`
}

type RingStats struct {
	Ring     string                    `json:"ring"`
	Hosts    int                       `json:"hosts"`
	Percent  float64                   `json:"percent"` // of fleet
	Drift    int                       `json:"driftHosts"`
	Digests  map[string]int            `json:"digests"`
	Versions map[string]map[string]int `json:"versions"` // harness -> installed version -> hosts
}

type RingView struct {
	Name       string            `json:"name"`
	Order      int               `json:"order"`
	Profile    string            `json:"profile"`
	Release    string            `json:"release,omitempty"`
	Membership policy.Membership `json:"membership"`
	Resolved   *policy.Profile   `json:"resolved,omitempty"`
	Error      string            `json:"error,omitempty"`
}

type RolloutApprovals struct {
	Rollout   string               `json:"rollout"`
	Step      string               `json:"step"`
	Target    policy.ChangeTarget  `json:"target"`
	Approvals []policy.Approval    `json:"approvals"`
	Quorum    *policy.QuorumResult `json:"quorum,omitempty"` // nil = no rule covers the next step
	Freeze    policy.FreezeStatus  `json:"freeze"`
}

type RolloutView struct {
	Rollout    *policy.Rollout  `json:"rollout"`
	Timeline   rollout.Timeline `json:"timeline"`
	State      *rollout.State   `json:"state,omitempty"`
	StateError string           `json:"stateError,omitempty"`
}

type SAMLConfig struct {
	// IdPMetadata is the IdP's SAML metadata XML (EntityDescriptor, or an
	// EntitiesDescriptor holding exactly one IdP).
	IdPMetadata []byte
	// Key and Cert are the SP key pair (RSA or ECDSA): AuthnRequests are
	// signed with it and EncryptedAssertions decrypted with it.
	Key  crypto.Signer
	Cert *x509.Certificate
	// EntityID is the SP entity id and the audience assertions must name;
	// "" = <baseURL>/auth/saml/metadata.
	EntityID string
	// UserAttribute is the Name of the attribute holding the user id; "" = the
	// NameID. It must be an identifier the user cannot edit at the IdP.
	UserAttribute string
	// GroupsAttributes are the Names of the attributes holding groups; empty =
	// DefaultSAMLGroupsAttributes.
	GroupsAttributes []string
	// AllowIdPInitiated accepts unsolicited responses (no AuthnRequest).
	// Off by default: they cannot be bound to the browser that logs in.
	AllowIdPInitiated bool
}

type SCIMEmail struct {
	Value   string `json:"value"`
	Type    string `json:"type,omitempty"`
	Primary bool   `json:"primary,omitempty"`
}

type SCIMGroup struct {
	ID          string    `json:"id"`
	ExternalID  string    `json:"externalId,omitempty"`
	DisplayName string    `json:"displayName"`
	Members     []string  `json:"members,omitempty"`
	Created     time.Time `json:"created"`
	Modified    time.Time `json:"lastModified"`
}

type SCIMName struct {
	Formatted  string `json:"formatted,omitempty"`
	GivenName  string `json:"givenName,omitempty"`
	FamilyName string `json:"familyName,omitempty"`
}

type SCIMStore interface {
	Users() []SCIMUser   // sorted by userName
	Groups() []SCIMGroup // sorted by displayName
	User(id string) (SCIMUser, bool)
	Group(id string) (SCIMGroup, bool)
	PutUser(SCIMUser) error
	// DeleteUser also removes the user from every group.
	DeleteUser(id string) error
	PutGroup(SCIMGroup) error
	DeleteGroup(id string) error
	// Lookup resolves a login identity (userName, case-insensitive) to the
	// user and the displayNames of the groups they are a member of.
	Lookup(userName string) (u SCIMUser, groups []string, ok bool)
	Close() error
}

type SCIMUser struct {
	ID          string      `json:"id"`
	ExternalID  string      `json:"externalId,omitempty"`
	UserName    string      `json:"userName"`
	DisplayName string      `json:"displayName,omitempty"`
	Name        *SCIMName   `json:"name,omitempty"`
	Emails      []SCIMEmail `json:"emails,omitempty"`
	Active      bool        `json:"active"`
	Created     time.Time   `json:"created"`
	Modified    time.Time   `json:"lastModified"`
}

type SecretRef struct {
	Env  string `json:"env,omitempty"`
	File string `json:"file,omitempty"`
}

type Server struct {
	// contains filtered or unexported fields
}

type ServiceTokenInfo struct {
	ID           string           `json:"id"`
	Principal    string           `json:"principal"` // the audit actor its requests carry
	Name         string           `json:"name"`
	Role         string           `json:"role"`
	Scope        policy.RoleScope `json:"scope"` // {} = global (ADR-0037)
	Description  string           `json:"description,omitempty"`
	Owner        string           `json:"owner,omitempty"`
	CreatedBy    string           `json:"createdBy"`
	CreatedAt    time.Time        `json:"createdAt"`
	ExpiresAt    time.Time        `json:"expiresAt"`
	Expired      bool             `json:"expired"`
	Revoked      bool             `json:"revoked"`
	RevokedBy    string           `json:"revokedBy,omitempty"`
	RevokedAt    *time.Time       `json:"revokedAt,omitempty"`
	RevokeReason string           `json:"revokeReason,omitempty"`
}

type ServiceTokensResponse struct {
	Tokens []ServiceTokenInfo `json:"tokens"`
}

type SessionPolicy struct {
	TTL  time.Duration
	Idle time.Duration
}

type SessionsIngest struct {
	Records []ledger.Record `json:"records"`
}

type SessionsResponse struct {
	Sessions    []ledger.Stored `json:"sessions"`
	Total       int             `json:"total"` // matching sessions before limit
	Verified    bool            `json:"verified"`
	VerifyError string          `json:"verifyError,omitempty"`
	Head        string          `json:"head"`
}

type Store interface {
	Put(Host) error
	All() []Host // sorted by hostname
	// History returns up to MaxHistory recent reports for key (see Host.key), newest first.
	History(key string) []Host
}

type ToggleKill struct {
	By     string    `json:"by"`
	Reason string    `json:"reason,omitempty"`
	At     time.Time `json:"at"`
}

type TogglePayload struct {
	Harnesses map[string]PatchSummary `json:"harnesses,omitempty"`
	Routes    map[string]string       `json:"routes,omitempty"` // alias -> "upstream/model" (or its targets)
}

type TogglePreview struct {
	Subject  toggle.Subject  `json:"subject"`
	Decision toggle.Decision `json:"decision"`
}

type ToggleView struct {
	Name        string              `json:"name"`
	Description string              `json:"description,omitempty"`
	Owner       string              `json:"owner"`
	Expires     string              `json:"expires,omitempty"`
	Stale       bool                `json:"stale"`
	Axis        policy.Axis         `json:"axis"`
	Default     bool                `json:"default"`
	Rules       []policy.ToggleRule `json:"rules"`
	Payload     TogglePayload       `json:"payload"`
	// Kill is set while the toggle is on the signed kill list.
	Kill *ToggleKill `json:"kill,omitempty"`
}

type TokenExchangeResponse struct {
	AccessToken     string   `json:"access_token"`
	IssuedTokenType string   `json:"issued_token_type"`
	TokenType       string   `json:"token_type"`
	ExpiresIn       int      `json:"expires_in"`
	Subject         string   `json:"subject"`
	Groups          []string `json:"groups,omitempty"`
	Rule            string   `json:"rule,omitempty"`
	Ring            string   `json:"ring,omitempty"`
	GatewayURL      string   `json:"gateway_url,omitempty"`
	// Actors (delegated credentials, ADR-0024) is the act chain, root-side
	// first; Models the credential's model scope (absent = not narrowed).
	Actors []string `json:"actors,omitempty"`
	Models []string `json:"models,omitempty"`
}

type Verdict struct {
	Experiment  string             `json:"experiment"`
	Verdict     string             `json:"verdict"` // promote | rollback | continue | expired
	Reason      string             `json:"reason"`
	Control     string             `json:"control"`
	Treatment   string             `json:"treatment"`
	NControl    int                `json:"nControl"`
	NTreatment  int                `json:"nTreatment"`
	PValue      float64            `json:"pValue"`
	Effect      float64            `json:"effect"`
	EffectLower *float64           `json:"effectLower,omitempty"`
	EffectUpper *float64           `json:"effectUpper,omitempty"`
	Guardrails  []GuardrailVerdict `json:"guardrails"`
	EvaluatedAt *time.Time         `json:"evaluatedAt,omitempty"`
}

type WhoAmI struct {
	User        string          `json:"user"`
	Groups      []string        `json:"groups"`
	Ring        string          `json:"ring"`
	Profile     string          `json:"profile,omitempty"`
	Release     string          `json:"release,omitempty"`
	Assignments []AssignmentRow `json:"assignments"`
}