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
- func FetchEnvelope(ctx context.Context, hc *http.Client, ...) ([]byte, error)
- func PinAtLogin(ctx context.Context, hc *http.Client, registryURL string) string
- func PinnedKeysPath(registryURL string) (string, error)
- func SameKeyIDs(a, b KeySet) bool
- func SavePinned(registryURL string, set KeySet) error
- type AttestationResult
- type KeyChange
- type KeySet
- type LoginPinResult
- type SigningKey
Constants ¶
const ( KeyStatusActive = "active" KeyStatusRetired = "retired" )
Key statuses the registry advertises.
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.
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 ¶
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 ¶
PinnedKeysPath is where TOFU-pinned keys live, per registry: the one named by AGENTRY_PIN_REGISTRY when set, else registryURL's own.
func SameKeyIDs ¶
SameKeyIDs reports whether two key sets advertise the same key ids.
func SavePinned ¶
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.
type KeySet ¶
type KeySet struct {
Keys []SigningKey `json:"keys" yaml:"keys"`
}
KeySet is a registry's advertised (or pinned) signing key set.
func LoadPinned ¶
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 ¶
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.