identity

package
v0.6.13 Latest Latest
Warning

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

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

Documentation

Overview

Package identity is sandboxd's own named-credential layer (plans/identity-and-access.md §5.4, §5.5): the server-side half of identity that the CLI never imports.

Task T3 puts the scoped API token (avm_…) here:

  • TokenRecord, the replicated row: id, name, role, team, creator, expiry and SHA-256 of the secret. Never the secret itself.
  • TokenLookup, the one question the request path asks ("is this id a live token, and can I vouch for my answer?"), answered from memory only: TokenSet on a single node, the Raft FSM on a server, and TokenMirror on every other cluster node.
  • TokenAuthenticator, the apiToken link in pkg/api's authenticator chain: checksum, local lookup, constant-time hash compare, expiry, and the stale-mirror rule (CEO review D16).

Task T6 puts SSO through OIDC here. sandboxd is a resource server, the same model as the Kubernetes API server with --oidc-issuer-url (§5.0, L1–L8): the company's identity provider logs the person in, and every node verifies the provider's token itself from the provider's published keys. There is no login service and no session.

  • Config and Watcher: the identity file (SB_IDENTITY_FILE) with its issuers, bindings and deny list, strictly loaded and hot-reloaded.
  • Verifier, the jwt link in the same chain: offline signature and claim checks, the bindings a token matches, and a verified-token cache that holds the binding set, never a selected team (eng review E7).
  • Summary and Diff: the identity_config evidence a file change writes (CEO review D20).

Task T13 adds OAuth for remote MCP (§5.14). An issuer's mcp_audiences are OAuth access-token audiences: the Verifier accepts such a token offline like an ID token and marks its Access MCPOnly, and the API edge accepts it only on /mcp and on a peer's forward marked X-Cluster-Surface: mcp. The file's mcp: section (resource, scopes) and its mcp: true issuers are what /mcp publishes as RFC 9728 metadata. An Entra v1 access token for a trusted tenant is refused with a hint naming the manifest setting.

Nothing on the request path makes a network call or touches SQLite (L2, D21): an unknown or malformed token is a local miss. The verifier's only traffic is the issuer's JWKS, fetched at start, hourly, and at most once a minute per issuer on an unknown key id.

The package is a leaf of the server tree. internal/cluster and internal/store import it for the record type; it imports neither.

Index

Constants

View Source
const (
	MaxFileBytes = 1 << 20

	// DefaultMaxTokenLifetime refuses long-lived workload tokens unless an
	// operator raises it per issuer, while fitting provider ID tokens
	// (~1 h), GitHub Actions tokens (minutes) and projected service-account
	// tokens (1 h) (CEO review finding 9.1).
	DefaultMaxTokenLifetime = 24 * time.Hour
)

Size and length caps. A 1 MiB file is roughly 10k bindings, the worst case the verified-token cache is sized for (eng review E8).

View Source
const (
	DefaultSyncInterval     = 5 * time.Second
	DefaultMaxStale         = 60 * time.Second
	DefaultResnapshotSpread = 30 * time.Second
)

Mirror defaults (setup/config-defaults.md).

View Source
const (
	DefaultRefetchGap      = time.Minute
	DefaultRefreshInterval = time.Hour
	DefaultKeyWait         = 2 * time.Second
	DefaultFetchTimeout    = 10 * time.Second
)

Defaults for VerifierOptions.

View Source
const (
	DefaultCacheEntries = 10_000
	DefaultCacheBytes   = 16 << 20
)

Cache bounds.

View Source
const (

	// EntraV1Hint is that refusal's hint. It names a provider setting,
	// never a claim value, so it is safe to send next to the D17 reason.
	EntraV1Hint = "Entra issued a v1 access token; set accessTokenAcceptedVersion: 2 on the API app"
)

Entra's two access-token formats (§5.14). A custom API's access tokens come in the v1 format, iss https://sts.windows.net/<tenant>/, unless the API app's manifest sets accessTokenAcceptedVersion: 2. An issuer written with the tenant's v2 URL then never matches, and a bare unknown_issuer would leave the admin guessing.

View Source
const FilePollInterval = 10 * time.Second

FilePollInterval is how often a changed identity file is noticed without a SIGHUP: a deny_subjects entry applies within one poll of the file reaching the node (§5.5).

View Source
const FileVersion = 1

FileVersion is the only identity-file format this build reads.

View Source
const MaxDocumentBytes = 1 << 20

MaxDocumentBytes caps a discovery or JWKS document (finding 5.5): a misbehaving provider cannot make a node buffer an unbounded body.

View Source
const MaxJWTBytes = 16 << 10

MaxJWTBytes caps a bearer the verifier will parse (finding 5.5): ID tokens and workload tokens are 1–2 KB, even with a long groups claim.

View Source
const MaxMirrorPageBytes = 12 << 20

MaxMirrorPageBytes caps one feed response: the FSM read budget (internal/cluster placementPageByteBudget). The server pages well under it; anything larger is a misbehaving server and is refused undecoded.

Variables

View Source
var (
	// ErrEmptyFile refuses a file with no document (CEO review finding
	// 4.3). Tokens-only mode is SB_IDENTITY_FILE unset, not an empty file,
	// so an empty file is a broken deploy, never a quiet "no SSO".
	ErrEmptyFile = errors.New("identity file is empty: unset SB_IDENTITY_FILE for tokens-only mode")
	// ErrFileTooLarge refuses a file over MaxFileBytes (finding 5.5).
	ErrFileTooLarge = fmt.Errorf("identity file is larger than %d bytes", MaxFileBytes)
)
View Source
var (
	// ErrTokensUnchanged is a 304 from the feed: the cursor is current.
	ErrTokensUnchanged = errors.New("identity: no token changes since the cursor")
	// ErrMirrorPageTooLarge refuses a feed response over MaxMirrorPageBytes
	// (CEO review finding 5.5).
	ErrMirrorPageTooLarge = errors.New("identity: token mirror page exceeds the size cap")
)
View Source
var ErrInvalidAtBoot = errors.New("identity file invalid at boot")

ErrInvalidAtBoot marks an identity file that was missing or invalid when the daemon started. OIDC tokens get 503 until a good file loads; the PAT and avm_ tokens are unaffected (§11).

View Source
var ErrInvalidTokenRecord = errors.New("identity: invalid token record")

ErrInvalidTokenRecord is a record no store accepts.

Functions

func Diff

func Diff(old, new Summary) *auditlog.IdentityConfig

Diff is the identity_config record body for a change from old to new. old is the zero Summary for the first file a node records.

func ExplainClaims

func ExplainClaims(bearer string, names *controlplane.ClaimNames) *identitywire.ExplainClaims

ExplainClaims reads the claims identity-file bindings match on (the username, groups and roles claims, by the names its issuer gives them) out of bearer, for `whoami --explain` (CEO review D22, §5.15).

It does not check the signature, and need not: names is the Access.ClaimNames this node built for this very bearer on this request, so the token was verified moments ago; and the answer goes back to the caller who presented the token, so it holds nothing the caller couldn't already read. Reading the claims here, on the rare explain call, keeps every caller's groups out of the verified-token cache. Names and groups are sanitized as the "no binding" 403 sanitizes them.

func OwnerRefForTeam

func OwnerRefForTeam(team string) string

OwnerRefForTeam is the owner ref a token bound to team carries.

func RecordChanges

func RecordChanges(ctx context.Context, w *Watcher, record func(Summary) bool, retry time.Duration)

RecordChanges writes the identity_config evidence (D20) until ctx ends: after every change the watcher signals, and at start for the file it loaded at boot, it hands the file in force to record. record reports whether it is done; while it is not (the cluster audit gate is closed, or a durable write failed) it is retried every retry interval. One goroutine records, always with the current file, so a slow retry can never write an older file over a newer one.

func SortTokenRecords

func SortTokenRecords(recs []TokenRecord)

SortTokenRecords orders records by team, then name, then id: the order every list answers in.

Types

type Binding

type Binding struct {
	Issuer  string
	Group   string
	AppRole string
	// Claim requires every listed claim to equal its value (a list claim
	// must contain it). claimKeys is Claim's keys in sorted order.
	Claim map[string]string

	Role controlplane.Role
	Team string
	// contains filtered or unexported fields
}

Binding grants Role on Team (or every team, controlplane.FleetTeam) to a token whose claims match it. Bindings are tried top to bottom and every match is kept: the first is the default, X-AerolVM-Team picks another.

func (*Binding) String

func (b *Binding) String() string

String is the binding's canonical line: "<issuer> <match> -> <role>/<team>", for example `okta group="platform-admins" -> admin/*`.

type Config

type Config struct {
	Issuers  []*Issuer
	Bindings []*Binding
	// MCPResource is the one protected-resource URL for /mcp (RFC 9728).
	MCPResource string
	// MCPScopes are the scopes an MCP connector asks its provider for, sent
	// as RFC 9728 scopes_supported and in the /mcp 401 challenge. Optional:
	// Okta and Keycloak mint a token for the configured audience without
	// one, but Entra mints a custom-API token only for a requested scope
	// ("api://<app>/<scope>"), and a connector has no other way to learn
	// it. They decide nothing about which tokens are accepted.
	MCPScopes []string
	// contains filtered or unexported fields
}

Config is a validated identity file. It is immutable once Parse returns: the verifier, the discovery document and the reload diff all read it concurrently.

func Load

func Load(path string) (*Config, error)

Load reads and validates path, refusing a file over MaxFileBytes before it is fully read.

func Parse

func Parse(raw []byte) (*Config, error)

Parse validates an identity document.

func (*Config) Denied

func (c *Config) Denied(issuer, sub string) bool

Denied reports whether "<issuer>:<sub>" is on the emergency deny list.

func (*Config) DiscoveryIssuers

func (c *Config) DiscoveryIssuers() []identitywire.DiscoveryIssuer

DiscoveryIssuers is the issuer list GET /.well-known/aerolvm-auth publishes: issuers with a CLI or dashboard client id, in file order. A nil Config (no good file loaded yet) publishes none.

func (*Config) Hash

func (c *Config) Hash() string

Hash is the SHA-256 of the file's bytes, hex: the value the aerolvm_identity_file_info metric and identity_config records carry, and what `sha256sum` prints for the same file.

func (*Config) IssuerByName

func (c *Config) IssuerByName(name string) (*Issuer, bool)

IssuerByName returns the issuer named name.

func (*Config) MCPAuthorizationServers

func (c *Config) MCPAuthorizationServers() []string

MCPAuthorizationServers is RFC 9728's authorization_servers for /mcp: the URLs of the issuers that set mcp: true, in file order. A nil Config (no good file loaded yet) publishes none.

func (*Config) Summary

func (c *Config) Summary() Summary

Summary returns c's canonical lines: issuers and bindings in file order, deny subjects sorted.

type File

type File struct {
	Version      int           `yaml:"version"`
	Issuers      []FileIssuer  `yaml:"issuers"`
	Bindings     []FileBinding `yaml:"bindings"`
	DenySubjects []string      `yaml:"deny_subjects"`
	MCP          *FileMCP      `yaml:"mcp"`
}

File is the YAML document as written.

type FileBinding

type FileBinding struct {
	Issuer  string            `yaml:"issuer"`
	Group   string            `yaml:"group"`
	AppRole string            `yaml:"app_role"`
	Claim   map[string]string `yaml:"claim"`
	Role    string            `yaml:"role"`
	Team    string            `yaml:"team"`
}

FileBinding is one binding as written: exactly one matcher (group, app_role or claim), the role it grants and the team it grants it on.

type FileIssuer

type FileIssuer struct {
	Name         string   `yaml:"name"`
	DisplayName  string   `yaml:"display_name"`
	Kind         string   `yaml:"kind"`
	URL          string   `yaml:"url"`
	JWKSFile     string   `yaml:"jwks_file"`
	Audiences    []string `yaml:"audiences"`
	MCPAudiences []string `yaml:"mcp_audiences"`
	Clients      struct {
		CLI       string `yaml:"cli"`
		Dashboard string `yaml:"dashboard"`
	} `yaml:"clients"`
	Claims struct {
		Username string `yaml:"username"`
		Groups   string `yaml:"groups"`
		Roles    string `yaml:"roles"`
	} `yaml:"claims"`
	MaxTokenLifetime string `yaml:"max_token_lifetime"`
	MCP              bool   `yaml:"mcp"`
}

FileIssuer is one identity provider as written.

type FileMCP

type FileMCP struct {
	Resource string   `yaml:"resource"`
	Scopes   []string `yaml:"scopes"`
}

FileMCP is the remote-MCP section (§5.14, task T13).

type Issuer

type Issuer struct {
	// Name is stable: it is part of every principal id this issuer mints
	// (oidc:<name>:<sub>).
	Name string
	// DisplayName is the dashboard button label; it falls back to Name and
	// is never used in principal ids or audit records (DR3).
	DisplayName string
	Kind        string
	// URL must equal the token's iss exactly, so it is kept as written.
	URL      string
	JWKSFile string
	// Audiences are the ID-token and workload-token audiences accepted on
	// every route. MCPAudiences are OAuth access-token audiences accepted
	// only on /mcp (T13); the two never overlap.
	Audiences        []string
	MCPAudiences     []string
	ClientCLI        string
	ClientDashboard  string
	UsernameClaim    string
	GroupsClaim      string
	RolesClaim       string
	MaxTokenLifetime time.Duration
	MCP              bool
	// contains filtered or unexported fields
}

Issuer is one trusted identity provider.

func (*Issuer) String

func (iss *Issuer) String() string

String is the issuer's canonical line: everything that decides which tokens it accepts. The display name and client ids are left out: they change labels, not trust (the client ids must already be audiences).

type MirrorConfig

type MirrorConfig struct {
	SyncInterval     time.Duration
	MaxStale         time.Duration
	ResnapshotSpread time.Duration
	PageLimit        int
	Logger           *slog.Logger
	Now              func() time.Time
	// Rand returns a uniform float in [0, 1).
	Rand func() float64
	// Sleep waits d or until ctx ends; false means ctx ended.
	Sleep func(ctx context.Context, d time.Duration) bool
}

MirrorConfig tunes a TokenMirror. Zero values take the defaults; tests inject the clock, the random source and the sleep.

type Summary

type Summary struct {
	Hash     string   `json:"hash"`
	Issuers  []string `json:"issuers"`
	Bindings []string `json:"bindings"`
	Deny     []string `json:"deny"`
}

Summary is the part of a Config an identity_config record diffs. Lines are canonical and never carry a secret (the file holds none).

type TokenAuthenticator

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

TokenAuthenticator is the apiToken link of pkg/api's authenticator chain (plans/identity-and-access.md §5.2, step 3). It claims every bearer with the avm_ prefix, so a mistyped token gets a token refusal reason instead of falling through to the managed provider.

avm_… ─► checksum ── bad ──────────────────────────► 401 malformed (no lookup)
        └► lookup (memory) ── stale, route ≠ metrics.read ─► 503 stale
           └► SHA-256(secret) vs stored hash ── miss ──────► 401 unknown_or_revoked
              └► expiry ── past ─────────────────────────► 401 expired
                 └► Access{token principal, role, team}

Every step is local: a checksum, a map read, one SHA-256 of 43 bytes and a constant-time compare. A spray of malformed or unknown tokens costs no server-tier call (CEO review D21).

func NewTokenAuthenticator

func NewTokenAuthenticator(lookup TokenLookup, logger *slog.Logger) *TokenAuthenticator

NewTokenAuthenticator builds the authenticator over lookup.

func (*TokenAuthenticator) Authenticate

func (a *TokenAuthenticator) Authenticate(r *http.Request, bearer string) (controlplane.Access, bool, error)

Authenticate decides a bearer. matched is false only for a bearer without the avm_ prefix.

type TokenChange

type TokenChange struct {
	// Index is the Raft index of the newest change to this id in the
	// served range. A delete removes a mirror's row only if the row's
	// Version is not above Index.
	Index   uint64       `json:"index"`
	ID      string       `json:"id"`
	Deleted bool         `json:"deleted,omitempty"`
	Token   *TokenRecord `json:"token,omitempty"`
}

TokenChange is one token's latest state since a cursor.

type TokenChanges

type TokenChanges struct {
	Changes []TokenChange `json:"changes"`
	// Next is the cursor to send as since on the next poll.
	Next uint64 `json:"next"`
	// More means the byte budget cut the response short: poll again now.
	More bool `json:"more,omitempty"`
	// Resnapshot means the server's change ring no longer covers since.
	Resnapshot bool   `json:"resnapshot,omitempty"`
	Floor      uint64 `json:"floor"`
}

TokenChanges answers GET /v1/cluster/internal/tokens?since=N.

type TokenFeed

type TokenFeed interface {
	// FetchTokenChanges returns a TokenChanges body, or ErrTokensUnchanged
	// when nothing changed since the cursor (a 304).
	FetchTokenChanges(ctx context.Context, since uint64) ([]byte, error)
	// FetchTokenPage returns a TokenPage body.
	FetchTokenPage(ctx context.Context, after string, limit int) ([]byte, error)
}

TokenFeed fetches the server tier's token feed (cluster.Agent implements it with its control-plane client). It returns raw JSON so the mirror can refuse an oversized page before decoding it.

type TokenLookup

type TokenLookup interface {
	LookupToken(id string) (rec TokenRecord, found, fresh bool)
}

TokenLookup is what the request path asks about a token id. It answers from memory only, never with a network call or a disk read.

found reports whether id is a stored token. fresh reports whether this node can vouch for that answer: false only on a mirror that has not synced within SB_IDENTITY_MAX_STALE, where a revoked token might still look live (or a new one not yet appear).

type TokenMirror

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

TokenMirror is a non-Raft node's copy of the token list.

func NewTokenMirror

func NewTokenMirror(feed TokenFeed, cfg MirrorConfig) *TokenMirror

NewTokenMirror builds a mirror over feed. It holds nothing until Run (or Sync) completes its first page walk, and is never fresh before that.

func (*TokenMirror) Age

func (m *TokenMirror) Age() time.Duration

Age is how long since the copy was last known current. Before the first sync it is the time since the mirror started.

func (*TokenMirror) Cursor

func (m *TokenMirror) Cursor() uint64

Cursor is the feed position the copy is current to.

func (*TokenMirror) Len

func (m *TokenMirror) Len() int

Len is the number of tokens in the copy.

func (*TokenMirror) LookupToken

func (m *TokenMirror) LookupToken(id string) (TokenRecord, bool, bool)

LookupToken answers from the copy. fresh is false before the first sync and once the copy is older than MaxStale.

func (*TokenMirror) ResnapshotDelay

func (m *TokenMirror) ResnapshotDelay() time.Duration

ResnapshotDelay is how long a mirror the server told to resnapshot waits before its page walk: uniform over ResnapshotSpread, so a ring overflow that hits every mirror at once spreads their walks over 30 s (7.3).

func (*TokenMirror) Run

func (m *TokenMirror) Run(ctx context.Context)

Run keeps the copy current until ctx ends.

func (*TokenMirror) Sync

func (m *TokenMirror) Sync(ctx context.Context) error

Sync runs one step: the page walk if one is due, otherwise one poll.

type TokenPage

type TokenPage struct {
	Tokens []TokenRecord `json:"tokens"`
	// Next is the id to send as after for the following page; "" at the end.
	Next string `json:"next,omitempty"`
	// Version is the serving server's token version when it read the page.
	Version uint64 `json:"version"`
}

TokenPage is one page of the full token list, in id order.

type TokenRecord

type TokenRecord struct {
	// ID is the public id (tok_…): the lookup key and the audit caller id.
	ID   string            `json:"id"`
	Name string            `json:"name"`
	Role controlplane.Role `json:"role"`
	// OwnerRef is team:<team> for a team-bound token and "" for a token
	// bound to every team, which is unscoped like the PAT.
	OwnerRef string `json:"owner_ref,omitempty"`
	// CreatedBy is the principal id of whoever minted it.
	CreatedBy  string    `json:"created_by"`
	CreatedAt  time.Time `json:"created_at"`
	ExpiresAt  time.Time `json:"expires_at"`
	SecretHash []byte    `json:"secret_hash"`
	// Version is the Raft log index of the write that created it, in a
	// cluster; 0 on a single node. Mirrors merge on it, so a delete at a
	// higher index always wins over a stale copy of the row.
	Version uint64 `json:"version,omitempty"`
}

TokenRecord is one API token as sandboxd stores and replicates it: about 200 bytes. The plaintext secret is never in it; SecretHash is SHA-256 of the secret. Records are immutable once created (a token is revoked, never edited), so a copy may share SecretHash's backing array.

func (TokenRecord) Access

func (r TokenRecord) Access() controlplane.Access

Access is the caller a request presenting this token acts as.

func (TokenRecord) Clone

func (r TokenRecord) Clone() TokenRecord

Clone copies r with its own SecretHash, for a store that keeps it.

func (TokenRecord) Expired

func (r TokenRecord) Expired(now time.Time) bool

Expired reports whether the token no longer authenticates at now.

func (TokenRecord) NameKey

func (r TokenRecord) NameKey() string

NameKey is the uniqueness key: names are unique per team (§5.4).

func (TokenRecord) Team

func (r TokenRecord) Team() string

Team is the token's team name, or "*" for a token bound to every team.

func (TokenRecord) Validate

func (r TokenRecord) Validate() error

Validate checks a record before it is stored. Every store runs it, so a cluster's FSM refuses the same records a single node's SQLite does.

type TokenSet

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

TokenSet is the single-node token index: every stored token in memory, loaded once at boot and updated on every write, so a request never reads SQLite. One process owns the store, so it is never stale.

func (*TokenSet) CountAPITokens

func (s *TokenSet) CountAPITokens(now time.Time) map[controlplane.Role]int

CountAPITokens counts the unexpired tokens by role, for the aerolvm_api_tokens gauge.

func (*TokenSet) Delete

func (s *TokenSet) Delete(id string)

Delete forgets id. A missing id is a no-op.

func (*TokenSet) Len

func (s *TokenSet) Len() int

Len is the number of stored tokens.

func (*TokenSet) LookupToken

func (s *TokenSet) LookupToken(id string) (TokenRecord, bool, bool)

LookupToken answers from memory; a single node is always fresh.

func (*TokenSet) Put

func (s *TokenSet) Put(rec TokenRecord)

Put stores rec, replacing any record with its id.

func (*TokenSet) Replace

func (s *TokenSet) Replace(recs []TokenRecord)

Replace swaps the whole set, as at boot.

type Verifier

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

Verifier checks identity-provider JWTs against the identity file in force. It implements the API edge's authenticator interface (pkg/api), so the daemon appends it to the chain with WithCredentialAuthenticator.

func NewVerifier

func NewVerifier(source func() *Config, opts VerifierOptions) *Verifier

NewVerifier verifies against whatever source returns at each request: the identity-file watcher's last good file, or nil while none has loaded (every JWT then gets 503).

func (*Verifier) Authenticate

func (v *Verifier) Authenticate(r *http.Request, bearer string) (controlplane.Access, bool, error)

Authenticate implements the API edge's Authenticator. A bearer that is not shaped like a JWT is not this authenticator's (matched=false). A JWT is always decided here: an Access, a *controlplane.CredentialError with a D17 reason, a *controlplane.NoBindingError (403), or controlplane.ErrIdentityUnavailable (503).

An OAuth access token for one of the issuer's mcp_audiences (§5.14) comes back with Access.MCPOnly set; the API edge's surface rule then refuses it everywhere but /mcp and a peer's MCP forward. That rule runs per request after this, so the cache can hold MCP-only tokens like any other: whether a token is MCP-only is a property of its aud, never of the route it was first seen on.

func (*Verifier) Bootstrap

func (v *Verifier) Bootstrap(ctx context.Context)

Bootstrap fetches every issuer's keys, waiting up to the fetch timeout. The daemon calls it at start in the background; a provider that is down leaves its tokens at 503 until a later fetch succeeds, and the PAT and avm_ tokens are unaffected.

func (*Verifier) RefetchKeys

func (v *Verifier) RefetchKeys()

RefetchKeys starts a fetch of every issuer's keys in the identity file in force, whatever the refetch gap, and returns without waiting. The daemon runs it after every identity-file reload (Watcher.OnReload): a SIGHUP, including one that changes nothing in the file, or an edit the poll noticed. That is what lets a SIGHUP drop a key the provider withdrew (the runbook's KeyCompromise entry) instead of trusting it until the hourly refresh. Requests never wait on it: they verify against the keys held until the fetch lands, a failed fetch keeps those keys (logged, and counted in aerolvm_identity_jwks_fetch_total as an error), and a cached token verified with a key the fetch withdrew is checked again (keySet.gen).

func (*Verifier) Run

func (v *Verifier) Run(ctx context.Context, tick time.Duration)

Run keeps keys fresh until ctx ends: every tick it retries an issuer that has none yet and refreshes one whose keys are older than the refresh interval. Both go through the refetch gap.

type VerifierOptions

type VerifierOptions struct {
	HTTPClient *http.Client
	Logger     *slog.Logger
	Now        func() time.Time
	// RefetchGap is the least time between two JWKS fetches for one
	// issuer, whatever triggers them (an unknown kid, a failed boot).
	RefetchGap time.Duration
	// RefreshInterval re-fetches a healthy issuer's keys.
	RefreshInterval time.Duration
	// KeyWait is how long a request waits for a fetch it triggered.
	KeyWait time.Duration
	// FetchTimeout bounds one discovery + JWKS round trip.
	FetchTimeout time.Duration
	CacheEntries int
	CacheBytes   int
}

VerifierOptions tunes a Verifier. The zero value is production: the system trust store, the CLAUDE.md lazy-bootstrap timings and the §5.5 cache bounds. Tests inject an *http.Client that trusts their httptest issuer and a clock; there is no insecure-issuer switch (finding 5.4).

type Watcher

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

Watcher keeps the last good identity file, the same machinery as the egress operator file: strict load, last good kept in an atomic pointer, an mtime poll plus Reload (SIGHUP), and a hash metric for drift between nodes. An invalid reload keeps the last good file and counts an error.

func NewWatcher

func NewWatcher(path string, log *slog.Logger) *Watcher

NewWatcher loads path once. A file that is missing or invalid leaves BootError set; the poll picks up the fix.

func (*Watcher) BootError

func (w *Watcher) BootError() error

BootError reports a missing or invalid file at startup, until a good one loads.

func (*Watcher) Current

func (w *Watcher) Current() *Config

Current returns the last good file, or nil when none has loaded yet.

func (*Watcher) OnReload

func (w *Watcher) OnReload(fn func())

OnReload registers fn to run after every later Reload, a SIGHUP or an edit the poll noticed, whether or not the file changed and whether or not it was valid. The daemon registers Verifier.RefetchKeys here before it starts the poll and the SIGHUP handler: the keys belong to the file in force, and a SIGHUP with an unchanged file is exactly how an operator asks for them to be fetched again after a key compromise. fn must not block; it runs on the reloading goroutine, after the reload lock is released.

func (*Watcher) Reload

func (w *Watcher) Reload() error

Reload re-reads the file now. An unchanged hash swaps nothing and signals no change; an invalid file keeps the last good one. Either way the OnReload hook runs afterwards.

func (*Watcher) Run

func (w *Watcher) Run(ctx context.Context, interval time.Duration)

Run polls the file's mtime every interval until ctx ends.

Directories

Path Synopsis
Package identitytest is an in-process OIDC identity provider for tests: an httptest TLS server publishing a discovery document and a JWKS, and a minting helper.
Package identitytest is an in-process OIDC identity provider for tests: an httptest TLS server publishing a discovery document and a JWKS, and a minting helper.

Jump to

Keyboard shortcuts

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