identitywire

package
v0.6.11 Latest Latest
Warning

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

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

Documentation

Overview

Package identitywire holds the identity formats that sandboxd and the aerolvm CLI must agree on byte for byte (plans/identity-and-access.md, eng review D2): the avm_ API token format with its checksum, the names and lifetimes a token request carries, the sign-in discovery document (GET /.well-known/aerolvm-auth) the CLI and the dashboard read before they hold any credential, the team-selection header, and the answer of `whoami --explain`.

It is the one identity package the CLI may import. It depends only on the standard library, so it never drags a server package (containerd, Raft, SQLite) into the CGO-free CLI build, and cmd/aerolvm/deps_test.go keeps it that way. Everything here is pure: parsing and formatting, no I/O and no clock.

Index

Constants

View Source
const (
	IssuerKindOIDC   = "oidc"
	IssuerKindGoogle = "google"
)

Issuer kinds. IssuerKindGoogle switches the dashboard to Google Identity Services (§5.7); every other provider is a generic OIDC issuer.

View Source
const (
	// APITokenPrefix starts every API token; secret scanners key on it.
	APITokenPrefix = "avm_"
	// APITokenIDPrefix starts every token's public id.
	APITokenIDPrefix = "tok_"
	// APITokenLength is the length of every well-formed token.
	APITokenLength = len(APITokenPrefix) + idLen + 1 + secretLen + 1 + crcLen
)

An API token (plans/identity-and-access.md §5.4) is

avm_<id:12>_<secret:43>_<crc:6>

id is 12 base62 characters: the lookup key, and with the tok_ prefix the token's public id (the audit caller id, the id GET /v1/tokens lists and DELETE /v1/tokens/{id} takes). secret is 32 random bytes in unpadded base64url: 256 bits, so a fast hash is enough and only SHA-256(secret) is ever stored. crc is CRC-32 (IEEE) of everything before it, in 6 base62 characters. It lets sandboxd refuse a mistyped or forged token before any lookup, and lets secret scanners confirm a match offline (the GitHub token pattern).

The secret's alphabet contains '_', so the token is parsed by position, never by splitting on '_'.

View Source
const (
	MaxTokenNameLen = 64
	MaxTeamNameLen  = 63
)

Name rules (plans/identity-and-access.md §5.4, CEO review finding 3.6). They keep names out of the way of logs, 403 hints and the access-review report, which print them verbatim.

View Source
const APITokenPattern = `avm_[0-9A-Za-z]{12}_[0-9A-Za-z_-]{43}_[0-9A-Za-z]{6}`

APITokenPattern matches a well-formed token, for secret scanners. A match is a real token only if its checksum also holds (ParseAPIToken).

View Source
const AuthDiscoveryPath = "/.well-known/aerolvm-auth"

AuthDiscoveryPath is where sandboxd serves AuthDiscovery. Caddy's @api matcher forwards it (scripts/install.sh, packaging/Caddyfile.template).

View Source
const AuthDiscoveryVersion = 1

AuthDiscoveryVersion is the document shape this build writes.

View Source
const TeamHeader = "X-AerolVM-Team"

TeamHeader selects which of a credential's teams a request acts for. It picks among the bindings the verified credential already matches and never grants one (§5.3). sandboxd's internal/cluster.HeaderTeam is the same string.

View Source
const WhoAmIExplainQuery = "explain"

WhoAmIExplainQuery is the query parameter that asks GET /v1/whoami to explain its answer: GET /v1/whoami?explain=1. A sandboxd that predates it ignores the parameter and sends no Explain, and the CLI then explains from the caller's own token alone.

Variables

View Source
var ErrMalformedAPIToken = errors.New("identitywire: malformed API token")

ErrMalformedAPIToken is any bearer with the avm_ prefix that is not a well-formed token: wrong length, a character outside its alphabet, or a checksum that does not hold.

Functions

func APITokenIDFrom

func APITokenIDFrom(s string) (string, bool)

APITokenIDFrom returns the public id a revoke should name, given either the id itself or a whole token (people paste the token they want gone).

func HashAPITokenSecret

func HashAPITokenSecret(secret string) [32]byte

HashAPITokenSecret is SHA-256 of a token secret.

func LooksLikeAPIToken

func LooksLikeAPIToken(bearer string) bool

LooksLikeAPIToken reports whether bearer claims to be an API token. Any bearer with the prefix is decided by the token authenticator, malformed or not, so a mistyped token gets the token's own refusal reason.

func ParseTokenTTL

func ParseTokenTTL(s string) (time.Duration, error)

ParseTokenTTL reads a token lifetime: a Go duration ("720h", "1h30m") or a whole number of days ("90d"). It must be positive.

func UIURL

func UIURL(domain string) string

UIURL returns the dashboard URL for domain, or "" when there is none.

func ValidAPITokenID

func ValidAPITokenID(id string) bool

ValidAPITokenID reports whether id is a well-formed public token id ("tok_" and 12 base62 characters).

func ValidTeamName

func ValidTeamName(team string) bool

ValidTeamName reports whether team is 1 to 63 characters of a-z, 0-9 and '-'. "*" (every team) is not a team name; callers check it separately.

func ValidTokenName

func ValidTokenName(name string) bool

ValidTokenName reports whether name is 1 to 64 characters of A-Z, a-z, 0-9, '.', '_' and '-'.

Types

type APIToken

type APIToken struct {
	// ID is the public id: "tok_" and the token's 12-character id.
	ID string
	// Secret is the 43-character secret. Only SecretHash is ever stored.
	Secret string
}

APIToken is one token, split into its public id and its secret.

String redacts the secret, so a token printed by accident (a %v in a log line) never leaks it. Plaintext is the only way to get the whole token.

func NewAPIToken

func NewAPIToken(r io.Reader) (APIToken, error)

NewAPIToken mints a token from r (crypto/rand when nil).

func ParseAPIToken

func ParseAPIToken(s string) (APIToken, error)

ParseAPIToken checks a token's shape and checksum. It does no lookup: a token it accepts may still be unknown, revoked or expired.

func (APIToken) GoString

func (t APIToken) GoString() string

GoString redacts too, so %#v is as safe as %v.

func (APIToken) Plaintext

func (t APIToken) Plaintext() string

Plaintext is the whole token, checksum included: what the caller sends as its bearer. sandboxd returns it once, at create, and never stores it.

func (APIToken) SecretHash

func (t APIToken) SecretHash() [32]byte

SecretHash is SHA-256 of the secret, the only form sandboxd keeps.

func (APIToken) String

func (t APIToken) String() string

String is the token with its secret redacted.

type AuthDiscovery

type AuthDiscovery struct {
	Version int `json:"version"`
	// IdentityEnabled reports whether this server accepts named
	// credentials (avm_ tokens, SSO) at all (SB_IDENTITY_ENABLED). With it
	// off the operator token is the only credential and Issuers is empty.
	IdentityEnabled bool `json:"identity_enabled"`
	// Issuers lists the providers a person can sign in with, in
	// identity-file order. Only issuers with a CLI or dashboard client id
	// are listed: a workload issuer (GitHub Actions, a Kubernetes cluster)
	// has no browser or CLI sign-in, and its URL is nobody's business.
	Issuers []DiscoveryIssuer `json:"issuers"`
	// UIURL is the dashboard's HTTPS address, https://<SB_DOMAIN>/ui (DR9).
	// The dashboard points a plain-HTTP visitor at it, since providers only
	// accept sign-in redirects to HTTPS or localhost. Omitted when the
	// server has no domain.
	UIURL string `json:"ui_url,omitempty"`
}

AuthDiscovery is the body of GET /.well-known/aerolvm-auth.

type DiscoveryClients

type DiscoveryClients struct {
	CLI       string `json:"cli,omitempty"`
	Dashboard string `json:"dashboard,omitempty"`
}

DiscoveryClients are an issuer's public client ids.

type DiscoveryIssuer

type DiscoveryIssuer struct {
	// Name is the issuer's stable identity-file name. It is the <issuer>
	// in oidc:<issuer>:<sub> principal ids and the `issuer` field of a
	// "no binding" 403.
	Name string `json:"name"`
	// DisplayName labels the sign-in button ("Sign in with Acme Okta").
	// It falls back to Name, so it is never empty.
	DisplayName string `json:"display_name"`
	// Kind is IssuerKindOIDC or IssuerKindGoogle.
	Kind string `json:"kind"`
	// URL is the issuer URL: the token's `iss`, and the base of the
	// provider's own OIDC discovery.
	URL string `json:"url"`
	// Clients holds the public client ids the CLI and the dashboard sign
	// in with. Neither is a secret (both are PKCE public clients).
	Clients DiscoveryClients `json:"clients"`
}

DiscoveryIssuer is one identity provider.

type ExplainBinding

type ExplainBinding struct {
	// Index is the binding's 1-based position in the identity file's
	// bindings list, so "binding 3" is the third entry.
	Index int `json:"index"`
	// Text is the binding's canonical line, the form identity_config audit
	// records use: `okta group="payments-eng" -> runner/payments`.
	Text string `json:"text"`
	// InEffect marks the binding this request acts under: the first match,
	// or the one X-AerolVM-Team selected.
	InEffect bool `json:"in_effect,omitempty"`
}

ExplainBinding is one identity-file binding.

type ExplainClaims

type ExplainClaims struct {
	// Issuer is the identity-file name of the issuer that signed the token.
	Issuer string `json:"issuer"`
	// Username is the value of the issuer's username claim.
	Username string   `json:"username,omitempty"`
	Groups   []string `json:"groups,omitempty"`
	Roles    []string `json:"roles,omitempty"`
	// GroupOverage is set when the provider left the groups out and sent an
	// overage pointer instead (Entra above 200 groups).
	GroupOverage bool `json:"group_overage,omitempty"`
}

ExplainClaims are the claims a binding is matched against.

type WhoAmIExplain

type WhoAmIExplain struct {
	// BindingsApply is true for an identity-provider token, whose role
	// comes from identity-file bindings. It is false for a credential that
	// carries its own role (the operator token, an API token, a managed
	// account), and Note then says where the role comes from.
	BindingsApply bool   `json:"bindings_apply"`
	Note          string `json:"note,omitempty"`
	// Matched lists every identity-file binding the caller's claims
	// matched, in file order, one per role and team granted. Empty when
	// bindings don't apply.
	Matched []ExplainBinding `json:"matched"`
	// Claims are the caller's own claims the bindings were matched against.
	// Absent for a credential that is not an identity-provider token.
	Claims *ExplainClaims `json:"claims,omitempty"`
}

WhoAmIExplain is the `explain` object of an explained whoami. It describes only the caller: the bindings its own claims matched and the claims that were considered, never another principal's (D22).

Jump to

Keyboard shortcuts

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