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 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 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 (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.