Documentation
¶
Overview ¶
Package provision manages StageFreight's auto-provisioned Tier-0 signing identity — a persistent software cosign keypair living in the operator's signing state dir. Its defining property is TRUST CONTINUITY: the identity is generated exactly once, then reused forever; it is NEVER silently regenerated.
Once signing is automatic and "always on," continuity of identity matters more than convenience — a silently-rotated key would quietly invalidate every previously published trust anchor. So every ambiguous state is FATAL, never papered over by regeneration:
- identity record present but private key missing → fatal
- identity record present but public key missing → fatal (partial state)
- public-key fingerprint drifted from the record → fatal
- identity record corrupt/unparseable → fatal
- key material present with no identity record → fatal (orphan; refuse to provision over it)
Recovery from any of these is a deliberate operator act (restore the material, or reset the state dir on purpose), never an automatic side effect. Tier-0 optimizes persistence + frictionless adoption, not maximum assurance — harden by climbing the custody ladder. See docs/architecture/signing-trust-model.md (O.3).
Index ¶
Constants ¶
const ( // TierSoftware is the assurance tier of an auto-provisioned software key — // recorded so a consumer can always discover the tier they actually operate // under (never implying stronger trust than exists). TierSoftware = "tier0-software" )
Variables ¶
This section is empty.
Functions ¶
func GuardStateDir ¶
GuardStateDir refuses a signing state dir that lives inside the repository / build context (repoRoot). Persisting a private signing key in the source tree risks it being committed, baked into a docker image layer, or swept into a published artifact — the key MUST live on a durable volume outside the repo. Callers invoke this before provisioning. SYMLINK-SAFE: both paths are symlink-resolved, so a symlinked state-dir (or symlinked parent) cannot smuggle the key inside the repo.
func IsPrivateKeyPath ¶
IsPrivateKeyPath reports whether path looks like signing key material — a defensive tripwire so a private key (or the identity record) is never accidentally uploaded/published as an artifact. Belt-and-suspenders: structurally, only public signatures/anchors are ever added to asset lists, but this guards future mistakes. Errs toward over-blocking (a rare false positive is loud; a published key is not).
Types ¶
type Identity ¶
type Identity struct {
Tier string `json:"tier"`
AutoProvisioned bool `json:"auto_provisioned"`
CreatedAt string `json:"created_at"`
KeyFile string `json:"key_file"`
PubFile string `json:"pub_file"`
Fingerprint string `json:"fingerprint"` // sha256:<hex> of the public-key bytes
}
Identity is the persisted record of the signing identity — the source of truth for trust continuity, written as identity.json in the state dir.
func EnsureIdentity ¶
func EnsureIdentity(ctx context.Context, stateDir string, gen KeyGenerator, now string) (*Identity, error)
EnsureIdentity returns the Tier-0 signing identity in stateDir, provisioning it on first use and validating continuity on every use thereafter. `now` is recorded as the provision timestamp (injected for deterministic tests). Any continuity violation is returned as an error — the caller MUST treat it as fatal.
func LoadIdentity ¶
LoadIdentity reads the persisted identity record (read-only; no provisioning) so the publish phase can obtain the public anchor + fingerprint to attach and disclose. Returns (nil, nil) when the state dir has no identity, and validates the same continuity invariants as the provisioning path (a partial/drifted identity must not be published as if intact).
Source Files