Documentation
¶
Overview ¶
Package sign is the pure trust-contract core of StageFreight signing. It owns the neutral IR (SignPlan) and the total Compile lowering — the stable model that insulates the rest of the system from cosign. It imports config (which owns the policy structs + validation) and NEVER imports cosign: the cosign renderer (src/sign/cosign) is an edge that satisfies these requirements, not a participant in the model. See docs/architecture/signing-trust-model.md.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DerefKeyRef ¶
DerefKeyRef resolves a key reference to its concrete value WITHOUT existence checking: "env:VAR" → the environment value; otherwise the path verbatim. The one canonical place the "env:VAR vs path" grammar is parsed — shared by Enabled (which adds an existence check) and the renderer's witness resolution, so the two can never diverge.
func Enabled ¶
Enabled reports whether a plan should actually sign. It preserves today's no-key-no-signing for the implicit `legacy` key path: a key-class plan whose key reference does not resolve is disabled (no signature, not an error). This is the only env-dependent function here; Compile stays pure.
Types ¶
type IdentityConstraints ¶
IdentityConstraints expresses an expected signer identity (oidc/keyless). Both fields optional; empty = no constraint (record-only at v1).
type Op ¶
type Op string
Op is a signing operation; the renderer maps each to a concrete invocation.
type SignOptions ¶
type SignOptions struct {
MultiArch bool
PredicatePath string
PredicateType string // attestation predicate type (e.g. "slsaprovenance"); caller-set, never executor-defaulted
}
SignOptions carry per-invocation inputs that are not trust requirements.
type SignPlan ¶
type SignPlan struct {
// ── Trust requirements (what must be true) ──
TrustClass Class
TransparencyRequired bool // the signature must be recorded in a transparency log
RequiresPhysicalPresence bool // the signer must demonstrate physical presence
RequiresNonExportableKey bool // the signing key must be hardware-bound / non-exportable
Identity IdentityConstraints
// ── Logical references (bound to keys/URIs only at render time) ──
KeyRef string // key class: "path" or "env:VAR"
KMSRef string // kms class: a logical ref, bound to a URI by the renderer
PKCS11Ref string // hardware class: a logical ref → pkcs11: URI via SF_PKCS11_<REF> (absent = FIDO2 --sk)
// ── Execution modifier (kept distinct so policy logic never leaks here) ──
Attestation bool // also emit a provenance attestation
}
SignPlan is the insulation boundary AS DATA — a declarative trust CONTRACT ("what must be true for a signature to be acceptable"), never an execution plan. It deliberately carries NO cosign vocabulary (no --sk/--key/mode/URI): the only code that turns these requirements into an invocation is the renderer, by satisfying them against a declared capability Env. Renderer-shaped fields (UseKeyless, CosignMode, UploadTlog, …) must never appear here — that erosion is exactly what collapses the "cosign as edge renderer" invariant.
func Compile ¶
func Compile(p *config.ResolvedSigningProfile) SignPlan
Compile lowers a validated, resolved profile to its trust contract. It is a deterministic, TOTAL transform: config.ValidateSigningProfiles is the single validation layer, so Compile has no error path and never re-validates. Purity is over the LOGICAL policy — refs stay logical (KeyRef/KMSRef are resolved to concrete keys/URIs only at render time, never here).
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package anchordoc generates the canonical signing-anchor documentation — a managed, idempotent section embedded in an operator-owned file (conventionally SECURITY.md).
|
Package anchordoc generates the canonical signing-anchor documentation — a managed, idempotent section embedded in an operator-owned file (conventionally SECURITY.md). |
|
Package autosign resolves the effective signer for a target, applying Tier-0 auto-provision ONLY when the operator has consented (enabled && auto_provision && a configured state_dir).
|
Package autosign resolves the effective signer for a target, applying Tier-0 auto-provision ONLY when the operator has consented (enabled && auto_provision && a configured state_dir). |
|
Package cosign is the ONLY cosign-aware code in StageFreight signing — the edge renderer that satisfies a sign.SignPlan (a declarative trust contract) against a declared capability Env, emitting a concrete cosign invocation.
|
Package cosign is the ONLY cosign-aware code in StageFreight signing — the edge renderer that satisfies a sign.SignPlan (a declarative trust contract) against a declared capability Env, emitting a concrete cosign invocation. |
|
Package provision manages StageFreight's auto-provisioned Tier-0 signing identity — a persistent software cosign keypair living in the operator's signing state dir.
|
Package provision manages StageFreight's auto-provisioned Tier-0 signing identity — a persistent software cosign keypair living in the operator's signing state dir. |