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
- Variables
- func APITokenIDFrom(s string) (string, bool)
- func HashAPITokenSecret(secret string) [32]byte
- func LooksLikeAPIToken(bearer string) bool
- func ParseTokenTTL(s string) (time.Duration, error)
- func UIURL(domain string) string
- func ValidAPITokenID(id string) bool
- func ValidTeamName(team string) bool
- func ValidTokenName(name string) bool
- type APIToken
- type AuthDiscovery
- type DiscoveryClients
- type DiscoveryIssuer
- type ExplainBinding
- type ExplainClaims
- type WhoAmIExplain
Constants ¶
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.
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 '_'.
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.
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).
const AuthDiscoveryPath = "/.well-known/aerolvm-auth"
AuthDiscoveryPath is where sandboxd serves AuthDiscovery. Caddy's @api matcher forwards it (scripts/install.sh, packaging/Caddyfile.template).
const AuthDiscoveryVersion = 1
AuthDiscoveryVersion is the document shape this build writes.
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.
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 ¶
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 ¶
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 ¶
HashAPITokenSecret is SHA-256 of a token secret.
func LooksLikeAPIToken ¶
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 ¶
ParseTokenTTL reads a token lifetime: a Go duration ("720h", "1h30m") or a whole number of days ("90d"). It must be positive.
func ValidAPITokenID ¶
ValidAPITokenID reports whether id is a well-formed public token id ("tok_" and 12 base62 characters).
func ValidTeamName ¶
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 ¶
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 ¶
NewAPIToken mints a token from r (crypto/rand when nil).
func ParseAPIToken ¶
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) Plaintext ¶
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 ¶
SecretHash is SHA-256 of the secret, the only form sandboxd keeps.
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).