trust

package
v0.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package trust is the shared client-side provenance layer: fetch a registry's signing keys, pin them on first use (TOFU) with key-id continuity warnings, and verify DSSE envelopes offline against an archive digest. Verification uses the same library code the server signs with (pkg/attest), so the formats cannot drift — and every client (CLI, desktop) shares the SAME pin store under ~/.config/agentry/keys/<host>.yaml, so a registry pinned by one client is pinned for all of them.

Index

Constants

View Source
const (
	KeyStatusActive  = "active"
	KeyStatusRetired = "retired"
)

Key statuses the registry advertises.

View Source
const (
	StateVerified     = "verified"
	StateUnsigned     = "unsigned"
	StateUnverifiable = "unverifiable"
	StateMismatch     = "mismatch"
	// StateUnscanned is a version the registry admitted without a scan
	// (an organization's private agent its administrator took off the
	// pipeline): no findings, no report and no attestation, because
	// nothing was attested. It is its own outcome — not unsigned (a
	// registry that signs nothing), and not a scan with a known gap.
	StateUnscanned = "unscanned"
	// StateBuiltin is a package this binary embeds, run as part of the
	// application: not a release, so it has no registry attestation and
	// needs none, and it is never verified — a client shows it as the
	// application's own, never as a verified release. Only localrun's
	// Materialize of an embedded package sets it, in memory; no record on
	// disk carries it into a run.
	StateBuiltin = "builtin"
	// StateLocal is a package from a folder on this machine: a `run
	// --local` directory, or a QuickAgent installed from one and never
	// published. Nothing attests to it, so every client gates it as it
	// gates unsigned.
	StateLocal = "local"
)

Attestation states reported by VerifyAttestation, and one the registry reports before any attestation is looked for.

View Source
const EnvPinRegistry = "AGENTRY_PIN_REGISTRY"

EnvPinRegistry names the registry whose pinned keys verify attestations in place of the one being talked to. A driver that points --registry at a run-scoped prefix of a registry keeps the pins it made at login against the registry itself, instead of trusting whatever the prefix serves on first use under a pin file named after the prefix.

Variables

This section is empty.

Functions

func FetchEnvelope added in v0.6.1017

func FetchEnvelope(ctx context.Context, hc *http.Client, registryURL, token, attestationURL string) ([]byte, error)

FetchEnvelope reads the attestation envelope at attestationURL as it is, for a driver that hands the release on to a machine that verifies it again (a remote runhost). nil with no error means the registry recorded none. The token goes to the registry's own origin only, as for VerifyAttestation.

func PinAtLogin

func PinAtLogin(ctx context.Context, hc *http.Client, registryURL string) string

PinAtLogin pins the registry's signing keys at login (TOFU). Pinning at login rather than at first verify is the whole point — login is the moment a human deliberately chose this registry and typed a credential for it, which is exactly when trust-on-first-use should be established. Pinning later, at the first `verify` or `install`, silently moves that decision to whichever download happens to come first.

It returns a human-readable note describing what happened, and never fails the login: a registry with signing switched off publishes an empty key set, and that is a legitimate self-host configuration, not a login error.

func PinnedKeysPath

func PinnedKeysPath(registryURL string) (string, error)

PinnedKeysPath is where TOFU-pinned keys live, per registry: the one named by AGENTRY_PIN_REGISTRY when set, else registryURL's own.

func SameKeyIDs

func SameKeyIDs(a, b KeySet) bool

SameKeyIDs reports whether two key sets advertise the same key ids.

func SavePinned

func SavePinned(registryURL string, set KeySet) error

SavePinned writes the pinned set (0600).

Types

type AttestationResult

type AttestationResult struct {
	// State is one of: verified, unsigned, unverifiable, mismatch, unscanned.
	State string `json:"state"`
	// Detail explains the state in one line.
	Detail string `json:"detail"`
	// KeyID that produced the accepted signature (when verified).
	KeyID string `json:"keyId,omitempty"`
	// Predicate summary fields (when verified).
	Agent        string `json:"agent,omitempty"`
	Version      string `json:"version,omitempty"`
	RulesetVer   string `json:"rulesetVersion,omitempty"`
	ReportDigest string `json:"reportDigest,omitempty"`
	JudgeModel   string `json:"judgeModel,omitempty"`
	Source       string `json:"source,omitempty"`
	// FirstUse is true when the key set was pinned by this invocation.
	FirstUse bool `json:"firstUse,omitempty"`
	// KeyRotated is true when the registry presented a key id we had not
	// pinned (a continuity warning, not necessarily an attack).
	KeyRotated bool `json:"keyRotated,omitempty"`
	// KeyChange says how the registry's advertised key set differs from
	// the pinned one, when a signature no pinned key verifies made us
	// look.
	KeyChange *KeyChange `json:"keyChange,omitempty"`
	// KeyRetired is true when the key that verified the signature is one
	// the registry records as retired, and KeyRetiredAt is the date it
	// gives. Shown, not judged: a retired key's signature verifies
	// exactly as before.
	KeyRetired   bool   `json:"keyRetired,omitempty"`
	KeyRetiredAt string `json:"keyRetiredAt,omitempty"`
}

AttestationResult is what verify/install report about provenance.

func Unscanned

func Unscanned() AttestationResult

Unscanned is the result for a version the registry says was admitted without a scan: the resolve answer carries `scanStatus: skipped`, and no attestation is asked for, because the absence is the fact and not a missing signature.

func VerifyAttestation

func VerifyAttestation(ctx context.Context, hc *http.Client, registryURL, token, attestationURL, archiveDigest string) AttestationResult

VerifyAttestation fetches and verifies the attestation for a version. archiveDigest is the digest the client computed from the downloaded bytes, so a verified attestation binds the signature to what is actually on disk. token, when non-empty, is attached as a bearer credential, but only to an attestation URL on the registry's own origin: never to a CDN, another port, or the registry's host over plain http, and a redirect off that origin drops it too.

func VerifyEnvelope added in v0.6.1017

func VerifyEnvelope(raw []byte, set KeySet, archiveDigest string) AttestationResult

VerifyEnvelope verifies an attestation envelope already in hand against set, and binds it to archiveDigest. It fetches nothing and pins nothing: the caller chooses the key set.

func (AttestationResult) RetiredNote

func (r AttestationResult) RetiredNote() string

RetiredNote is the one line a client shows for a signature a retired key made, or "" when the accepting key is not retired.

type KeyChange

type KeyChange struct {
	// Added are key ids the registry advertises that are not pinned.
	Added []string `json:"added,omitempty"`
	// Removed are pinned key ids the registry no longer advertises.
	Removed []string `json:"removed,omitempty"`
	// Replaced are key ids advertised with a public key other than the
	// pinned one.
	Replaced []string `json:"replaced,omitempty"`
}

KeyChange is how a registry's advertised key set differs from the pinned one. A rotation adds the new key and keeps every earlier one listed as retired, so an advertised set that is a strict superset of the pinned one is what a rotation looks like; a pinned key that disappears, or an id that now carries a different public key, is not.

func DiffKeys

func DiffKeys(pinned, advertised KeySet) KeyChange

DiffKeys compares the pinned set with the advertised one.

func (KeyChange) Rotation

func (c KeyChange) Rotation() bool

Rotation reports the shape of a rotation: keys added, every pinned key still advertised with the same public key.

func (KeyChange) Same

func (c KeyChange) Same() bool

Same reports no difference at all.

func (KeyChange) String

func (c KeyChange) String() string

String names what changed, e.g. "added key id(s) k2; removed key id(s) k1".

type KeySet

type KeySet struct {
	Keys []SigningKey `json:"keys" yaml:"keys"`
}

KeySet is a registry's advertised (or pinned) signing key set.

func FetchKeys

func FetchKeys(ctx context.Context, hc *http.Client, registryURL string) (KeySet, error)

FetchKeys reads the registry's key set.

func LoadPinned

func LoadPinned(registryURL string) (KeySet, error)

LoadPinned reads the pinned set (empty when nothing is pinned yet).

type LoginPinResult

type LoginPinResult struct {
	// Status is pinned, unchanged, unsigned, rotation, mismatch or unavailable.
	Status string
	Note   string
}

LoginPinResult reports pinning without putting remote errors or key material into a machine client's output. Note retains the terminal explanation.

func PinAtLoginResult

func PinAtLoginResult(ctx context.Context, hc *http.Client, registryURL string) LoginPinResult

PinAtLoginResult is PinAtLogin's structured counterpart for machine clients.

type SigningKey

type SigningKey struct {
	KeyID     string `json:"keyId" yaml:"keyId"`
	Algorithm string `json:"algorithm" yaml:"algorithm"`
	PublicKey string `json:"publicKeyPem" yaml:"publicKeyPem"`
	Status    string `json:"status,omitempty" yaml:"status,omitempty"`
	RetiredAt string `json:"retiredAt,omitempty" yaml:"retiredAt,omitempty"`
}

SigningKey is one entry from /.well-known/agentry/signing-keys.json. Status and RetiredAt are the registry's own record of the key: "active" for the key that signs today, "retired" (with the date) for one it signed with before and no longer does, empty for a verification-only key the registry never signed with. They are shown, never trusted: which keys verify is decided by the pinned PEMs alone.

func (SigningKey) Retired

func (k SigningKey) Retired() bool

Retired reports whether the registry recorded the key as retired.

Jump to

Keyboard shortcuts

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