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
- Variables
- func ContextWithAccess(ctx context.Context, a Access) context.Context
- func ContextWithRoutePermission(ctx context.Context, p Permission) context.Context
- func ContextWithSystemCaller(ctx context.Context, subsystem string) context.Context
- func DenyHint(a Access, p Permission) string
- func HintPrincipal(kind PrincipalKind) bool
- func HostCapable(ctx context.Context) bool
- func IsNoopValidator(v Validator) bool
- func SanitizeDisplayName(s string) string
- func TeamOwnerRef(team string) string
- type Access
- func AccessFromContext(ctx context.Context) (Access, bool)
- func ControlPlaneAccess(id Identity) (Access, error)
- func NodeAccess(nodeID string) Access
- func OIDCAccess(p Principal, bindings []TeamBinding, expiresAt time.Time) Access
- func OperatorAccess() Access
- func TokenAccess(id, name string, role Role, team string, expiresAt time.Time) Access
- type Admitter
- type AuditEventBatch
- type AuditExporter
- type AuditHead
- type ClaimNames
- type CredentialError
- type Enforcement
- type FleetController
- type Identity
- type NoBindingError
- type OptionalExportEvents
- type Permission
- type Principal
- type PrincipalKind
- type Provider
- type RejectReason
- type Reporter
- type Role
- type Sample
- type TeamBinding
- type Validator
- type Witness
- type WitnessReceipt
Constants ¶
const ( NoBindingReason = "no_binding" GroupOverageReason = "group_overage" )
NoBinding reasons: the `reason` of a v1 "no binding" 403 (design review DR8).
const FleetTeam = "*"
FleetTeam is how a fleet-wide binding names its team: every team.
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.
const SystemPrincipalPrefix = string(PrincipalSystem) + ":"
SystemPrincipalPrefix starts every system principal id.
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 ¶
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".
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.
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).
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.
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.
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.
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 ¶
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
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
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
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
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
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 ¶
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
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
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
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
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
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.
type Admitter ¶
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
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 ¶
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 ¶
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
SystemCallerFromContext returns the system principal ContextWithSystemCaller attached, if any.
func SystemPrincipal ¶ added in v0.6.8
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
HasAuditExporter reports whether p.AuditExporter is a non-noop implementation.
func (Provider) HasExternalValidator ¶ added in v0.6.8
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
HasExternalWitness reports whether p.Witness is a non-noop implementation.
func (Provider) WithDefaults ¶
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 ¶
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.
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
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).
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 ¶
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
WitnessReceipt is the witness's acknowledgment that a head was recorded.