trust

Documentation

Overview

Package trust implements the deterministic parts of docs/spec/trust-and-signing.md that need no Git or key material: promotion tag naming and monotonic sequence selection, coordination authority policy validation, and the detached-signature envelope for canonical Release digests. Signature verification itself shells out to git / ssh-keygen in a later stage; this package decides *what* would be verified.

Index

• Constants
• Variables
• func Floor(local, desired domain.CoordinationTrust) (domain.CoordinationTrust, error)
• func PromotionTagPrefix(target string) (string, error)
• func SignedPayload(releaseDigest string) []byte
• func TargetFromPrefix(prefix string) (string, error)
• func ValidatePolicy(p domain.CoordinationTrust) error
• type Candidate
  • func SelectDesired(cands []Candidate) (Candidate, error)
• type PromotionTag
  • func ParsePromotionTag(target, ref string) (PromotionTag, error)
• type ReleaseSignatureEnvelope
• type Signer
• type ThresholdPolicy
  • func (p ThresholdPolicy) Satisfied(verified []Signer) (bool, string)

Constants

const (
	AuthoritySignedCommitTip    = "signed-commit-tip"
	AuthoritySignedPromotionTag = "signed-promotion-tag"

	SignaturesRequired = "required"
	SignaturesOptional = "optional"
	SignaturesOff      = "off"

	// PromotionTagRoot is the fixed namespace under which promotion tags live.
	PromotionTagRoot = "refs/tags/fxvcs/promote/"
)

const (
	ProfileSSHv1     = "ssh-v1"
	NamespaceRelease = "fxvcs-release"
)

Variables

var (
	ErrInvalidPolicy       = errors.New("trust: invalid coordination trust policy")
	ErrNotPromotionTag     = errors.New("trust: not a promotion tag for this target")
	ErrNonCanonicalSeq     = errors.New("trust: non-canonical promotion sequence")
	ErrDuplicateSeq        = errors.New("trust: duplicate promotion sequence")
	ErrNoValidPromotion    = errors.New("trust: no valid promotion tag")
	ErrDesiredStateRelaxes = errors.New("trust: desired state cannot relax agent-local trust")
)

Errors.

Functions

func Floor

func Floor(local, desired domain.CoordinationTrust) (domain.CoordinationTrust, error)

Floor enforces "desired state cannot relax agent-local policy": the effective policy is the agent-local one; a Git/Cloud-supplied policy may only tighten. Returns ErrDesiredStateRelaxes if desired is weaker in any respect.

func PromotionTagPrefix

func PromotionTagPrefix(target string) (string, error)

PromotionTagPrefix returns "refs/tags/fxvcs/promote/<target>/".

func SignedPayload

func SignedPayload(releaseDigest string) []byte

SignedPayload returns the exact bytes a signer signs for a release digest.

func TargetFromPrefix

func TargetFromPrefix(prefix string) (string, error)

TargetFromPrefix validates a configured prefix and extracts the target.

func ValidatePolicy

func ValidatePolicy(p domain.CoordinationTrust) error

ValidatePolicy checks an agent-local coordination trust policy.

Types

type Candidate

type Candidate struct {
	Tag PromotionTag
	// Commit the annotated tag points at (after peeling).
	Commit string
	// Valid is true only when the tag is annotated, its single signature
	// verifies against agent-local allowed signers (when required), and it was
	// not retargeted since first observation.
	Valid bool
	// Reason explains invalidity for audit.
	Reason string
}

Candidate is a promotion tag together with the agent's verification result.

func SelectDesired

func SelectDesired(cands []Candidate) (Candidate, error)

SelectDesired implements the promotion-tag authority: the highest sequence among valid candidates wins. Duplicate sequences (which can only occur when non-canonical encodings slipped past provider protection or the ref list was tampered with) fail closed. Branch commits newer than the selected tag are irrelevant; there is no fallback to branch-tip authority.

type PromotionTag

type PromotionTag struct {
	Ref    string
	Target string
	Seq    uint64
}

PromotionTag is a parsed refs/tags/fxvcs/promote/<target>/<seq> ref.

func ParsePromotionTag

func ParsePromotionTag(target, ref string) (PromotionTag, error)

ParsePromotionTag parses a full ref name for the given target. The sequence must be canonical decimal (no leading zeros, no sign, no padding) so that "01" and "1" cannot both exist and be treated as distinct authorities.

type ReleaseSignatureEnvelope

type ReleaseSignatureEnvelope struct {
	Profile       string   `json:"profile"`       // "ssh-v1"
	Namespace     string   `json:"namespace"`     // "fxvcs-release"
	ReleaseDigest string   `json:"releaseDigest"` // sha256:...
	Signatures    []Signer `json:"signatures"`
}

ReleaseSignatureEnvelope is the detached signature format over a canonical Release digest. Signatures cover exactly the ASCII bytes of SignedPayload(digest); the profile pins the algorithm and namespace so a signature cannot be replayed as another kind of statement.

type Signer

type Signer struct {
	Role      string `json:"role"`      // creator | cloud | builder
	KeyID     string `json:"keyID"`     // SHA256:... fingerprint of the public key
	Signature string `json:"signature"` // armored ssh signature
}

type ThresholdPolicy

type ThresholdPolicy struct {
	RequiredRoles []string `json:"requiredRoles"` // every listed role must have >=1 valid signature
	Threshold     int      `json:"threshold"`     // total distinct valid signers required
	RevokedKeyIDs []string `json:"revokedKeyIDs"`
}

ThresholdPolicy is the agent-local requirement for portable Release signatures.

func (ThresholdPolicy) Satisfied

func (p ThresholdPolicy) Satisfied(verified []Signer) (bool, string)

Satisfied reports whether the set of verified (keyID, role) pairs meets policy. verified must contain only signatures already cryptographically checked.