controlplane

package
v0.6.12 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package controlplane is the neutral seam between sandboxd and an optional managed control plane. It declares small capability interfaces — caller-token validation, usage-sample reporting, and standing-driven fleet enforcement — and ships a no-op implementation that is the default in the open-source build.

The open-source daemon links only against this package. A managed build wires a concrete Provider (backed by a private client) at startup; nothing about that client's behavior lives here. With the no-op Provider, sandboxd behaves byte-for-byte as it did before this seam existed: user tokens are rejected (leaving only the operator PAT path), usage reporting is discarded, and the enforcement loop does nothing.

Index

Constants

View Source
const (
	NoBindingReason    = "no_binding"
	GroupOverageReason = "group_overage"
)

NoBinding reasons: the `reason` of a v1 "no binding" 403 (design review DR8).

View Source
const FleetTeam = "*"

FleetTeam is how a fleet-wide binding names its team: every team.

View Source
const SystemDaemon = "daemon"

SystemDaemon is the subsystem an audit record names when background work reached it through an entry point nobody tagged. Seeing it in a record means an entry point should be given its own name.

View Source
const SystemPrincipalPrefix = string(PrincipalSystem) + ":"

SystemPrincipalPrefix starts every system principal id.

View Source
const TeamOwnerPrefix = "team:"

TeamOwnerPrefix marks an owner ref that names an open-source team. The prefix keeps teams out of the managed build's account namespace, so a team called "acme" can never collide with a managed account "acme" (§5.1).

Variables

View Source
var ErrAdmissionDenied = errors.New("controlplane: admission denied")

ErrAdmissionDenied is returned by Admitter.Admit when the caller's account is not permitted to create a sandbox right now (e.g. its access has been suspended or terminated by the control plane). It is a definite "no": the API edge maps it to 403. Distinct from ErrAdmissionUnavailable, which is a retryable "ask again later".

View Source
var ErrAdmissionUnavailable = errors.New("controlplane: admission temporarily unavailable")

ErrAdmissionUnavailable is returned by Admitter.Admit when the control plane cannot vouch for the caller right now (standing data is not yet known and the contract's grace window has elapsed). It is retryable; the API edge maps it to 503 with a Retry-After hint.

View Source
var ErrIdentityNoOwner = fmt.Errorf("%w: identity has no owner", ErrTokenRejected)

ErrIdentityNoOwner is returned for a managed identity with an empty OwnerRef. Scoped to owner "", it would see every operator-created sandbox and snapshot, so a validator answering that is broken and the caller is refused rather than failing open (unchanged from before T1).

View Source
var ErrIdentityRole = fmt.Errorf("%w: managed identity role must be viewer or runner", ErrTokenRejected)

ErrIdentityRole is returned when a managed provider names a role other than viewer or runner. A provider may narrow a caller, never grant fleet powers (CEO review finding 1.4), so anything else is refused, not clamped.

View Source
var ErrIdentityStale = errors.New("controlplane: identity data is stale")

ErrIdentityStale refuses a named credential this node cannot check because its copy of the replicated token list is older than SB_IDENTITY_MAX_STALE (§5.4). The API edge answers 503 with Retry-After: the credential may be perfectly good, the node just cannot vouch for it.

View Source
var ErrIdentityUnavailable = errors.New("controlplane: OIDC sign-in is unavailable on this node")

ErrIdentityUnavailable refuses a JWT this node cannot check right now: the identity file was invalid at boot, or the issuer's signing keys could not be fetched (§5.5, §11). The API edge answers 503 with Retry-After. The PAT and avm_ tokens are unaffected, since neither needs the provider.

View Source
var ErrTokenRejected = errors.New("controlplane: token rejected")

ErrTokenRejected is returned by Validator.Validate for any token the control plane declines (or for every token under the no-op Provider). The API edge maps it to 401.

Functions

func ContextWithAccess

func ContextWithAccess(ctx context.Context, a Access) context.Context

ContextWithAccess returns a child context carrying a. The auth middleware calls this after authenticating; downstream service methods read it back via AccessFromContext.

func ContextWithRoutePermission added in v0.6.8

func ContextWithRoutePermission(ctx context.Context, p Permission) context.Context

ContextWithRoutePermission records the permission the request's route needs, before authentication runs (apihttp.Router stamps it). Only one authenticator reads it: a token mirror that cannot sync still accepts a request whose route needs nothing but metrics.read (CEO review D16), so it has to know the route's permission at authentication time.

func ContextWithSystemCaller added in v0.6.8

func ContextWithSystemCaller(ctx context.Context, subsystem string) context.Context

ContextWithSystemCaller marks ctx as background work done by subsystem. A request's caller always wins over it: SystemCallerFromContext is consulted only when ctx carries no Access, so tagging a shared helper can never re-attribute an API call to the daemon.

func DenyHint added in v0.6.8

func DenyHint(a Access, p Permission) string

DenyHint is the D9 hint for a refused permission: the caller's own role and team, and the role that would allow the call. It names only what `whoami` already shows the caller, never another principal, team or binding. It is "" for principals that get no hint (HintPrincipal).

role viewer on team payments cannot sandbox.exec; ask an admin for role runner on team payments

func HintPrincipal added in v0.6.8

func HintPrincipal(kind PrincipalKind) bool

HintPrincipal reports whether a refusal for this principal kind carries the D9 hint. Only the new identity kinds (avm_ tokens, OIDC) get one; the PAT, a cluster node and a managed caller keep today's 403 bodies byte for byte (L8).

func HostCapable added in v0.6.8

func HostCapable(ctx context.Context) bool

HostCapable is Access.HostCapable for a request context. A context with no Access is an internal call that never crossed the API edge (failover recreate, background loops), so it keeps the host powers it always had.

func IsNoopValidator added in v0.6.8

func IsNoopValidator(v Validator) bool

IsNoopValidator reports whether v rejects every token: nil or the no-op validator. The API edge uses it to label refusals "unknown" rather than "controlplane" when no provider is wired.

func SanitizeDisplayName added in v0.6.8

func SanitizeDisplayName(s string) string

SanitizeDisplayName strips control characters and truncates to 256 runes. Display names come from outside (provider identities, token names, JWT claims) and end up in logs and audit records, so a newline or terminal escape must not survive.

func TeamOwnerRef added in v0.6.8

func TeamOwnerRef(team string) string

TeamOwnerRef is the owner ref a credential bound to team carries.

Types

type Access

type Access struct {
	Identity Identity
	Fleet    bool
	Role     Role
	// Principal is who made the request; its ID is what audit records and
	// trace attributes name.
	Principal Principal
	// Via is the edge node's id when a peer forwarded the request over mTLS.
	// It comes from the verified peer certificate, never from a header.
	Via string
	// ExpiresAt is when the presented credential stops working; zero for
	// credentials that do not expire (the PAT, managed provider tokens).
	ExpiresAt time.Time
	// MCPOnly marks a credential that is valid only on /mcp or on a forward a
	// peer marked X-Cluster-Surface: mcp (an OAuth access token whose audience
	// is one of an issuer's mcp_audiences, §5.14). The API edge refuses it
	// everywhere else. No T1 authenticator sets it.
	MCPOnly bool
	// Bindings is every role binding the credential matched, first match
	// first (an OIDC token can match several identity-file bindings, §5.3).
	// Role, Fleet and Identity.OwnerRef describe the one team selection
	// picked: the first, unless X-AerolVM-Team names another. Empty for a
	// credential with exactly one binding (the PAT, a node, a managed
	// account, an avm_ token). The slice is shared with the verified-token
	// cache: read it, never write it.
	Bindings []TeamBinding
	// ClaimNames, for an OIDC caller, names its issuer's claims, for
	// `whoami --explain` (D22). nil for every other credential.
	ClaimNames *ClaimNames
	// SandboxToken is the verified claims of a sandbox token caller
	// (PrincipalSandboxToken): the one sandbox, port, path prefix and
	// methods it covers. The API edge refuses the token on every request
	// they do not cover, and Can grants it sandbox.exec only. nil for every
	// other credential.
	SandboxToken *sandboxtoken.Claims
}

Access is the authenticated caller context attached by the API auth middleware and read by the service layer to enforce owner scoping (plans/identity-and-access.md §5.1: who, what, where).

Fleet is scope, not power: true means the caller is unscoped and sees every owner (the PAT, a cluster peer, later a role bound to "*"); false means Identity.OwnerRef is the one owner the request is fenced to. Fleet was named Operator before roles existed, when the one bit meant both "unscoped" and "operator powers"; an auditor needs the first without the second, so the powers move to Role and Principal (task T2's permission checks).

Background loops and internal calls run with no Access in context. The service layer treats "no Access present" as unscoped (fleet-wide) so those paths are never accidentally constrained — only an explicit non-fleet Access narrows visibility.

func AccessFromContext

func AccessFromContext(ctx context.Context) (Access, bool)

AccessFromContext returns the Access attached to ctx, if any. ok is false for background loops and internal calls that never went through the auth edge — callers must treat that as unscoped (operator-equivalent) access.

func ControlPlaneAccess added in v0.6.8

func ControlPlaneAccess(id Identity) (Access, error)

ControlPlaneAccess maps a managed provider's Identity onto Access: scoped to its OwnerRef, role Identity.Role or runner when unset, principal controlplane:<ExternalID>. runner is today's owner-scoped verb set, so a provider that sets no role sees no change (L8).

func NodeAccess added in v0.6.8

func NodeAccess(nodeID string) Access

NodeAccess is the PAT presented by a cluster peer over mTLS on its own behalf. It has the operator's powers (as today); only the name differs, so audit records say which node acted instead of "operator".

func OIDCAccess added in v0.6.8

func OIDCAccess(p Principal, bindings []TeamBinding, expiresAt time.Time) Access

OIDCAccess is an identity provider's verified token (§5.5): principal p, scoped by its first binding until team selection picks another. bindings must not be empty: a token that matched none is refused with a NoBindingError, never given an Access.

func OperatorAccess added in v0.6.8

func OperatorAccess() Access

OperatorAccess is the PAT on the public listener (and, with Via set by the API edge, a PAT request a peer forwarded): fleet-wide, admin, "operator". It is exactly today's Access{Operator: true} under its new names.

func TokenAccess added in v0.6.8

func TokenAccess(id, name string, role Role, team string, expiresAt time.Time) Access

TokenAccess is a scoped API token (avm_…, plans/identity-and-access.md §5.4): the token's role, bound to one team or, for team FleetTeam, to every team. A team-bound token is fenced to owner team:<team>; a fleet token is unscoped and creates sandboxes with owner "", exactly as the PAT does. The principal id is the token's public id (tok_…), which is also the audit caller id; the name is the token's name, for people only.

func (Access) Can added in v0.6.8

func (a Access) Can(p Permission) bool

Can reports whether the caller holds p. It answers "may this caller use this verb", never "on which owner": that is Fleet's job (ownerScope), so a runner bound to team payments Can(sandbox.exec) and is still fenced to payments' sandboxes by the service layer.

func (Access) EffectiveRole added in v0.6.8

func (a Access) EffectiveRole() Role

EffectiveRole is the role a caller's permissions come from.

A pre-roles Access literal keeps the meaning it had then: Fleet was the PAT (admin; on an internal route, the peer node), anything else an owner-scoped caller (runner, the verb set every managed caller has always had). A caller that names a principal but carries no role holds nothing: a broken authenticator fails closed, never open.

func (Access) HostCapable added in v0.6.8

func (a Access) HostCapable() bool

HostCapable reports whether the caller may use host-side powers: raw host mounts, file:// bundle refs read off the host, and custom domains on the operator's trusted DNS path (eng review D3, D7). True for the PAT (operator), a cluster peer (node:), a system loop, and the admin role. False for viewer, runner (team or fleet), auditor and managed identities: fleet scope is which owners a caller sees, never host power.

func (Access) Team added in v0.6.8

func (a Access) Team() string

Team is the team a caller acts for: FleetTeam for an unscoped (fleet) caller, the team name for a `team:` owner, and "" for a managed account (its owner ref is an account key, not a team).

type Admitter

type Admitter interface {
	Admit(ctx context.Context, ownerRef string) error
}

Admitter is the create-admission gate. The daemon consults it before reserving capacity for a new sandbox: a non-nil error refuses the create (e.g. the owner's account is suspended, or fleet standing is unknown beyond the contract grace). The no-op Admitter admits everything, so the open-source build never gates creates.

type AuditEventBatch added in v0.6.1

type AuditEventBatch struct {
	NodeID string
	Offset string
	// BatchID is deterministic for node + local offset + payload. Including the
	// payload digest prevents retention rewrites from reusing an old offset's
	// idempotency key.
	BatchID   string
	Events    []json.RawMessage
	ShippedAt time.Time
}

AuditEventBatch is a JSONL-oriented batch of audit event payloads for off-node export. Payloads are already-redacted JSON objects (never plaintext secrets). Offset is an opaque exporter cursor.

type AuditExporter added in v0.6.1

type AuditExporter interface {
	ExportEvents(ctx context.Context, batch AuditEventBatch) (nextOffset string, err error)
}

AuditExporter ships full audit event batches off-node (SIEM / object store). Distinct from Witness (heads only). Optional; when unset, disk loss loses events that were never exported.

type AuditHead added in v0.6.1

type AuditHead struct {
	NodeID   string
	HeadHex  string
	EventID  string
	Observed time.Time
}

AuditHead is a hash-chain head shipped to an off-node witness so retroactive tampering of a node's local audit log is detectable. Hex digest only — never plaintext audit payloads.

type ClaimNames added in v0.6.8

type ClaimNames struct {
	// Issuer is the issuer's identity-file name.
	Issuer   string
	Username string
	Groups   string
	Roles    string
}

ClaimNames is how one identity-file issuer names the claims its bindings match on (§5.5 `claims:`), so `whoami --explain` can read the caller's own claims back out of the token the caller presented (D22). One value per loaded issuer, shared by every Access it verifies: read it, never write it.

type CredentialError added in v0.6.8

type CredentialError struct {
	Kind   PrincipalKind
	Reason RejectReason
	// Hint, when set, is a fixed sentence naming the setting that would make
	// this credential work (an Entra v1 access token: "set
	// accessTokenAcceptedVersion: 2 on the API app", §5.14). The 401 body
	// carries it after the surface's text. Like Reason it must never carry a
	// claim value, a key id or anything from the credential itself.
	Hint string
}

CredentialError is what an authenticator returns when it recognised a named credential (Kind PrincipalToken or PrincipalOIDC) and refused it. The API edge turns it into a 401 that names Reason. Any other refusal (the PAT, the managed provider, an unrecognised bearer) keeps today's bare 401.

func AsCredentialError added in v0.6.8

func AsCredentialError(err error) (*CredentialError, bool)

AsCredentialError returns the CredentialError in err's chain, if any.

func (*CredentialError) Error added in v0.6.8

func (e *CredentialError) Error() string

func (*CredentialError) Unwrap added in v0.6.8

func (e *CredentialError) Unwrap() error

Unwrap makes errors.Is(err, ErrTokenRejected) hold for every refusal.

type Enforcement

type Enforcement interface {
	Start(ctx context.Context)
}

Enforcement is the background standing loop. Start is called once at daemon boot by the managed build; the no-op Start returns immediately.

type FleetController

type FleetController interface {
	StopByOwner(ctx context.Context, ownerRef string) error
	RestoreByOwner(ctx context.Context, ownerRef string) error
	DeleteByOwner(ctx context.Context, ownerRef string) error
	FireWebhook(ctx context.Context, ownerRef, level string) error
}

FleetController is implemented by the service layer so the managed build can converge the fleet to a standing directive without the control-plane client knowing any orchestration internals. Every method must be idempotent.

type Identity

type Identity struct {
	ExternalID string
	OwnerRef   string
	Role       Role
	Name       string
}

Identity is the account a caller token resolves to. OwnerRef is the stable account key stamped onto sandboxes and usage samples; ExternalID is the provider's subject, used as the principal id (controlplane:<ExternalID>).

Role and Name are optional. A managed provider may set Role to viewer or runner only, never a fleet role; empty means runner, which is exactly the owner-scoped verb set every managed caller had before roles existed (plans/identity-and-access.md §5.1, CEO review finding 1.4).

type NoBindingError added in v0.6.8

type NoBindingError struct {
	Principal Principal
	Issuer    string
	Name      string
	Groups    []string
	Overage   bool
}

NoBindingError refuses a verified OIDC token whose claims match no identity-file binding (§5.5, D9, DR8). Every field is the caller's own: the issuer they signed in through (its identity-file name), their display name, and the groups their token carried, so they can tell their admin what is missing. Overage means the provider left the groups out (Entra sends an overage pointer instead above 200 groups); Groups is then empty. Principal is who the verified token names (oidc:<issuer>:<sub>): they hold no role, but they are known, so the refusal is an api record naming them rather than an anonymous auth_denied (§5.5, finding 2.3).

func AsNoBindingError added in v0.6.8

func AsNoBindingError(err error) (*NoBindingError, bool)

AsNoBindingError returns the NoBindingError in err's chain, if any.

func (*NoBindingError) Error added in v0.6.8

func (e *NoBindingError) Error() string

func (*NoBindingError) Reason added in v0.6.8

func (e *NoBindingError) Reason() string

Reason is the DR8 reason: group_overage or no_binding.

type OptionalExportEvents added in v0.6.1

type OptionalExportEvents interface {
	ExportEvents(ctx context.Context, batch AuditEventBatch) (nextOffset string, err error)
}

OptionalExportEvents is implemented by Witness backends that also accept full event batches. Detected via type assertion at boot.

type Permission added in v0.6.8

type Permission string

Permission is one verb a route requires (plans/identity-and-access.md §5.3). Every API route is registered with exactly one (or, for a route whose verb depends on the request, a classifier that returns one), and a caller's Role decides whether it holds it. The values are the names audit records, 403 bodies and `whoami` print, so they are a wire contract.

const (
	// PermSandboxRead: get and list sandboxes (no env), mounts, network
	// usage, custom domains, snapshots, egress profiles, WASM modules and JS
	// bundles, capacity.
	PermSandboxRead Permission = "sandbox.read"
	// PermSandboxSecrets: include_env reads (the audited secret_open path).
	PermSandboxSecrets Permission = "sandbox.secrets"
	// PermSandboxWrite: create, start, stop, delete, resize, lifecycle,
	// ports, custom domains, network limits and policy, snapshots, image
	// build, egress profiles, JS bundles and WASM modules.
	PermSandboxWrite Permission = "sandbox.write"
	// PermSandboxExec: the whole toolbox proxy (exec, files, sessions,
	// terminals). Files can hold secrets, so a viewer gets none of it.
	PermSandboxExec Permission = "sandbox.exec"
	// PermAuditRead: GET /v1/sandboxes/{id}/audit.
	PermAuditRead Permission = "audit.read"
	// PermAuditVerify: POST /v1/audit/verify.
	PermAuditVerify Permission = "audit.verify"
	// PermTokenRead and PermTokenWrite: list, and create or revoke, API
	// tokens (task T3).
	PermTokenRead  Permission = "token.read"
	PermTokenWrite Permission = "token.write"
	// PermMetricsRead: GET /v1/metrics. The counters describe the whole
	// fleet, so only a role bound to every team holds it (CEO review D6).
	PermMetricsRead Permission = "metrics.read"
	// PermFleetAdmin: templates, /v1/cluster/*, admin reconcile, ingress
	// DNS, /debug/vars.
	PermFleetAdmin Permission = "fleet.admin"
	// PermClusterInternal: /v1/cluster/internal/*. Held only by the node:
	// principal (a peer's PAT over mTLS, on its own behalf), never by a role.
	PermClusterInternal Permission = "cluster.internal"
	// PermAuthenticated is the pseudo-permission of the two routes that need
	// only a valid principal: GET /v1/whoami (it describes the caller) and
	// /mcp (each tool's inner API call is authorized by its own route).
	PermAuthenticated Permission = "authenticated"
)

func RoutePermissionFromContext added in v0.6.8

func RoutePermissionFromContext(ctx context.Context) (Permission, bool)

RoutePermissionFromContext returns the permission the request's route needs. ok is false for a request that did not come through a Router (an unknown route must be treated as needing more than metrics.read).

func (Permission) RequiresFleet added in v0.6.8

func (p Permission) RequiresFleet() bool

RequiresFleet reports whether p is granted only through a binding to every team, whatever the role. metrics.read is: the counters are fleet-wide.

type Principal added in v0.6.8

type Principal struct {
	Kind PrincipalKind
	ID   string
	Name string
}

Principal is who made the request. ID is stable and safe for audit records and trace attributes ("operator", "node:n3", "controlplane:<external id>", later "tok_…" and "oidc:<issuer>:<sub>"). Name is for people and logs only: it can change (an email rename) and is never a trace attribute.

func SystemCallerFromContext added in v0.6.8

func SystemCallerFromContext(ctx context.Context) (Principal, bool)

SystemCallerFromContext returns the system principal ContextWithSystemCaller attached, if any.

func SystemPrincipal added in v0.6.8

func SystemPrincipal(subsystem string) Principal

SystemPrincipal is the principal for subsystem: kind system, id system:<subsystem>. An empty subsystem names the daemon as a whole.

type PrincipalKind added in v0.6.8

type PrincipalKind string

PrincipalKind names the credential family a caller authenticated with (plans/identity-and-access.md §5.1). It is the `kind` of the audit caller and of the aerolvm_auth_* metrics, so the values are a wire contract.

const (
	// PrincipalOperator is the shared operator token (PAT) from outside the
	// cluster, or forwarded by a peer on a user's behalf.
	PrincipalOperator PrincipalKind = "operator"
	// PrincipalToken is a scoped API token (avm_…, task T3).
	PrincipalToken PrincipalKind = "token"
	// PrincipalOIDC is an identity provider's signed token (task T6).
	PrincipalOIDC PrincipalKind = "oidc"
	// PrincipalControlPlane is a caller the managed provider's Validator
	// resolved.
	PrincipalControlPlane PrincipalKind = "controlplane"
	// PrincipalNode is a cluster peer calling with the PAT over mTLS on its
	// own behalf (control calls), not forwarding a user's request.
	PrincipalNode PrincipalKind = "node"
	// PrincipalSystem is a background loop with no request (task T4 names
	// them system:<subsystem> in audit records).
	PrincipalSystem PrincipalKind = "system"
	// PrincipalSandboxKey is an SSH session authenticated by a sandbox's
	// Ed25519 key (task T5).
	PrincipalSandboxKey PrincipalKind = "sandbox_key"
	// PrincipalSandboxToken is a signed per-sandbox token (pkg/sandboxtoken,
	// A1): its id is the token's public id (stk_…), never the token. It
	// holds sandbox.exec on one sandbox's toolbox and nothing else.
	PrincipalSandboxToken PrincipalKind = "sandbox_token"
)

type Provider

type Provider struct {
	Validator      Validator
	Reporter       Reporter
	Admitter       Admitter
	Witness        Witness
	AuditExporter  AuditExporter
	EnforcementFor func(FleetController) Enforcement
}

Provider bundles the capabilities a build supplies to the daemon. The open-source build uses Noop(); a managed build constructs one backed by the private client. Passed explicitly into the API server and background wiring — there is no global registry, so the dependency stays visible and testable.

EnforcementFor is a factory rather than a ready Enforcement because the FleetController it drives is the service layer, which only exists partway through daemon boot. The daemon calls EnforcementFor(svc).Start(ctx) once the service is constructed. A nil factory (or one returning the no-op) means no enforcement loop runs.

func Noop

func Noop() Provider

Noop returns a Provider whose capabilities do nothing: every token is rejected, every report is dropped, every create is admitted, and enforcement never runs. This is the open-source default and the safe fallback whenever the feature is disabled.

func (Provider) HasAuditExporter added in v0.6.1

func (p Provider) HasAuditExporter() bool

HasAuditExporter reports whether p.AuditExporter is a non-noop implementation.

func (Provider) HasExternalValidator added in v0.6.8

func (p Provider) HasExternalValidator() bool

HasExternalValidator reports whether p.Validator is a non-noop implementation, i.e. whether the provider brings its own caller login. sandboxd's own identity (SB_IDENTITY_ENABLED) refuses to boot next to one: two identity sources would have to share one owner namespace.

func (Provider) HasExternalWitness added in v0.6.1

func (p Provider) HasExternalWitness() bool

HasExternalWitness reports whether p.Witness is a non-noop implementation.

func (Provider) WithDefaults

func (p Provider) WithDefaults() Provider

WithDefaults fills any nil capability on p with its no-op equivalent, so a managed build can supply only the pieces it has wired without risking a nil dereference on the others.

type RejectReason added in v0.6.8

type RejectReason string

RejectReason is the coarse, standard reason a named credential (an avm_ token or a JWT) was refused (CEO review D17). It is sent to the caller as the RFC 6750 error_description and the JSON body's `reason`. It must never carry claim values, key ids, which signature check failed, or whether an avm_ id exists.

const (
	RejectExpired          RejectReason = "expired"
	RejectNotYetValid      RejectReason = "not_yet_valid"
	RejectUnknownIssuer    RejectReason = "unknown_issuer"
	RejectWrongAudience    RejectReason = "wrong_audience"
	RejectTooLongLived     RejectReason = "too_long_lived"
	RejectInvalidSignature RejectReason = "invalid_signature"
	RejectMalformed        RejectReason = "malformed"
	// RejectUnknownOrRevoked covers both an unknown and a revoked avm_ token:
	// telling them apart would disclose whether an id exists.
	RejectUnknownOrRevoked RejectReason = "unknown_or_revoked"
)

func (RejectReason) Valid added in v0.6.8

func (r RejectReason) Valid() bool

Valid reports whether r is one of the D17 reasons. The API edge sends only valid reasons to a caller, so a typo in an authenticator can never leak an arbitrary string into a response.

type Reporter

type Reporter interface {
	Report(ctx context.Context, batch []Sample) error
}

Reporter ships usage samples toward the managed ingest. Implementations must be non-blocking enough to sit on the daemon's background loops without stalling them.

type Role added in v0.6.8

type Role string

Role is the built-in role a principal holds (§5.3). T1 only carries it; T2 turns roles into route permissions.

const (
	RoleViewer  Role = "viewer"
	RoleRunner  Role = "runner"
	RoleAuditor Role = "auditor"
	RoleAdmin   Role = "admin"
)

func LeastRoleFor added in v0.6.8

func LeastRoleFor(p Permission) (role Role, fleetOnly bool, ok bool)

LeastRoleFor returns the least powerful role that would let a caller hold p, and whether that role (or p itself) must be bound to every team. ok is false when no role grants p (cluster.internal, authenticated).

func (Role) Grants added in v0.6.8

func (r Role) Grants(p Permission) bool

Grants reports whether the role table gives r the permission p at all. It ignores the binding: use Access.Can for a caller.

func (Role) RequiresFleet added in v0.6.8

func (r Role) RequiresFleet() bool

RequiresFleet reports whether r may only be bound to every team (FleetTeam). auditor and admin see the whole fleet by definition (§5.3); a token or an identity-file binding that names one team for them is invalid (T3, T6).

func (Role) Valid added in v0.6.8

func (r Role) Valid() bool

Valid reports whether r is one of the four built-in roles.

type Sample

type Sample struct {
	EventID     string
	OwnerRef    string
	SandboxID   string
	Kind        string
	Value       float64
	Unit        string
	WindowStart time.Time
	WindowEnd   time.Time
}

Sample is one neutral usage record. It carries units, never money — the managed side is solely responsible for any interpretation of these values.

type TeamBinding added in v0.6.8

type TeamBinding struct {
	Role Role
	Team string
	// Index and Rule name the identity-file binding that granted it, for
	// `whoami --explain` (CEO review D22): its 1-based position in the
	// file's bindings list and its canonical line
	// (`okta group="payments-eng" -> runner/payments`). Rule shares the
	// loaded file's string, so carrying it costs a pointer, not a copy.
	// Zero for a binding no identity file granted.
	Index int
	Rule  string
}

TeamBinding is one role a credential holds: on one team, or on every team (FleetTeam). An identity-file binding resolves to one (§5.5), and an OIDC token carries every one its claims match, in file order.

func (TeamBinding) Apply added in v0.6.8

func (b TeamBinding) Apply(a Access) Access

Apply returns a narrowed to binding b: its role, and its team as the owner scope (or fleet scope for FleetTeam). Principal, Via, ExpiresAt and Bindings are kept, so team selection can apply any of a's bindings.

type Validator

type Validator interface {
	Validate(ctx context.Context, token string) (Identity, error)
}

Validator resolves a caller token to an Identity. Implementations are expected to cache internally; the daemon calls this per authenticated request for non-PAT tokens.

type Witness added in v0.6.1

type Witness interface {
	WitnessHeads(ctx context.Context, heads []AuditHead) (WitnessReceipt, error)
	// LastWitnessedHead returns the most recent head the witness recorded for
	// nodeID. ok is false when the witness has never recorded a head for that
	// node (distinct from a transport error).
	LastWitnessedHead(ctx context.Context, nodeID string) (headHex string, ok bool, err error)
}

Witness records audit-chain heads off-node. No-op unless a provider or SB_AUDIT_WITNESS_BACKEND supplies one (pkg/auditwitness: an S3 bucket with Object Lock); a provider's witness wins. Enterprise mode requires a real Witness (see SB_SECRET_AUDIT_EXTERNAL_WITNESS).

type WitnessReceipt added in v0.6.1

type WitnessReceipt struct {
	RecordedAt time.Time
	ReceiptID  string
}

WitnessReceipt is the witness's acknowledgment that a head was recorded.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL