Evidence and receipts
Signed receipts, lifecycle checkpoints, publisher signatures, checking them offline
Months after a release, someone asks: who published this version, when, and is the copy we have the one that was published? Or a security team wants to know that the hub has not quietly forgotten a yank. A hub that keeps signed evidence can answer both, and you can check the answers yourself, on another machine, without trusting the network you are on. This chapter shows what the hub signs, how to save it, and how to check it offline.
What you will be able to do
- fetch the keys a hub signs with, and keep them for later;
- download the signed receipt for a publication and verify it offline;
- save the hub's signed list of every version's state, and notice if a hub ever shows you an older one;
- see the publisher signatures on a version, and know how a hub that requires them works.
What evidence is, and is not
A package file's digest proves which bytes you have. Evidence adds signed statements about those bytes:
- a receipt says that a given account committed a given publication, with these exact files, at this time, on this hub;
- a lifecycle checkpoint lists every version the hub holds and its state (deprecated, yanked) at one moment, numbered so that a newer one always has a higher number;
- a publisher signature (an attestation) says that a key belonging to the publisher signed these exact bytes.
None of these says the software is safe or good. They say who published what, and that nobody changed it since. That is the question they answer well.
The hub signs receipts and checkpoints automatically for every publication; there is nothing to turn on. Whether publisher signatures are required is the hub's choice.
The hub's keys
$ gritpack evidence root
repository: 550e8400-e29b-41d4-a716-446655440000
RepositoryRoot: 8cd83f905e06e0c46575d06922e603792746c5c296768afb43cb44da31350f32 threshold=1
RepositoryReceipt: 5a1837e232e9831000040a4800b3ab7d67b58c69e8d24539d833c2eba7f59d84 threshold=1
RepositorySnapshot: c03db4ff1f13b4ca45f19c0214daaba388e928808e553b8de9b07a0be1a23178 threshold=1
The repository is the hub's permanent identity. Each line is a key, named by
its fingerprint: the receipt key signs receipts, the snapshot key signs
lifecycle checkpoints. To check evidence later without the hub, you need these
keys saved in a file. Save them while connected to the hub over its normal,
authenticated connection, and keep the file with the project or in your CI
configuration:
$ gritpack evidence lifecycle --save-root root.json --save-checkpoint checkpoint.json --save-state state.json
repository=550e8400-e29b-41d4-a716-446655440000 version=32 records=23 created_at=1794900602 expires_at=1795505402 observed_at=1794900611 offline=false expired=false signers=c03db4ff1f13b4ca45f19c0214daaba388e928808e553b8de9b07a0be1a23178
That one command fetched the keys (root.json), the newest checkpoint
(checkpoint.json) and recorded which checkpoint you have now accepted
(state.json). The checkpoint is explained below; the root file is what every
offline check needs.
Careful. A root file is only as trustworthy as the way you got it. Fetch it yourself from the hub, or receive it from someone you trust over a channel you trust. A root file that arrives next to the evidence it is meant to check proves nothing.
Receipts
Every publication ends with a line like this:
committed publication transaction=01a1e869-1090-71d1-adfe-70e59c6d7d4d plan=sha256:37598609... generation=sha256:0c72b79f... nodes=3
The transaction ID is also the receipt's ID. Download the signed receipt:
$ gritpack evidence receipt 01a1e869-1090-71d1-adfe-70e59c6d7d4d --output receipt.json
saved signed receipt to receipt.json
and check it, with no hub involved:
$ gritpack evidence verify-receipt receipt.json --root root.json
verified receipt=01a1e869-1090-71d1-adfe-70e59c6d7d4d transaction=01a1e869-1090-71d1-adfe-70e59c6d7d4d repository=550e8400-e29b-41d4-a716-446655440000 committed_at=1794900562 signers=5a1837e232e9831000040a4800b3ab7d67b58c69e8d24539d833c2eba7f59d84
The signer is the hub's receipt key from root.json. With --json you get the
whole receipt: the account and credential that published, the plan, and every
package with its digest, size and outcome (new or already there). Keep receipts
for releases you may need to account for; they are small.
Change anything in a receipt, even one number, and it no longer verifies:
$ gritpack evidence verify-receipt tampered.json --root root.json
invalid portable evidence: signed envelope does not meet signature threshold 1
That is exit code 7, "integrity". The same happens if the root file is from a different hub.
From npm.
npmshows provenance for packages built on certain CI services. A Gritpack receipt is different: the hub itself signs what it accepted and from whom, for every publication, whatever built it.
Lifecycle checkpoints
Versions change state after they are published: they are deprecated, yanked,
or quarantined by an administrator. A lifecycle checkpoint is the hub's signed
list of every version and its state. With --json you can read it:
$ gritpack evidence lifecycle --json
{
"accepted_key_ids": [
"c03db4ff1f13b4ca45f19c0214daaba388e928808e553b8de9b07a0be1a23178"
],
"checkpoint": {
"created_at": 1794900602,
"expires_at": 1795505402,
"policy_version": "managed-evidence@1",
"records": [
{
"attestation_set_sha256": "d7431b585457be1a3871b31a27bbd0027bb2a49219f33d67244a759705ed2093",
"lifecycle": {
"deprecation": {
"deprecated_at": 1794900112,
"message": "Use 0.2 or later"
}
},
"subject": {
...
"dialect": "c/c23",
"name": "@ada/greet",
"version": "0.1.0"
}
...
Two numbers matter. The version (32 in the summary line earlier) goes up every
time anything on the hub changes state. expires_at is a week after
created_at: a checkpoint is a statement about now, and an old one should not
be taken as current.
Checking offline, and noticing a rollback
Verify a saved checkpoint against the saved keys and your accepted state:
$ gritpack evidence verify-lifecycle checkpoint.json --root root.json --state state.json
repository=550e8400-e29b-41d4-a716-446655440000 version=32 records=23 created_at=1794900602 expires_at=1795505402 observed_at=1794900626 offline=true expired=false signers=c03db4ff1f13b4ca45f19c0214daaba388e928808e553b8de9b07a0be1a23178
The state file is your memory of the newest checkpoint you have accepted. Each time you fetch a new one, pass the state in and save it back:
gritpack evidence lifecycle --state state.json --save-state state.json --save-checkpoint checkpoint.json
From then on Gritpack refuses any checkpoint older than the one you have seen. After a deprecation moved the hub on to version 35, showing Gritpack the earlier checkpoint again fails:
$ gritpack evidence verify-lifecycle old-checkpoint.json --root root.json --state state.json
invalid portable evidence: lifecycle checkpoint is older than the highest accepted generation
That is the protection against a hub, or anything pretending to be one, showing you an old view in which a yanked version was still fine. Gritpack also refuses two different checkpoints with the same number, a checkpoint for another hub, and, when connected, an expired one.
For automation. A nightly job that runs
evidence lifecycle --state ... --save-state ...and keeps the state file is a cheap tripwire: if it ever fails with exit code 7, something is wrong with the hub you are talking to.
Publisher signatures
Receipts prove what the hub accepted. A publisher signature goes one step
further: it proves that a key held by the publisher, not just a login, signed
the exact bytes. Hubs that want this set a threshold: how many valid publisher
signatures each new version needs. The publish report shows it on the
verification line; attestation_threshold=0 means the hub does not require any.
On a hub that does, the flow is:
-
Register a key. You make an Ed25519 key pair and keep the private seed in your secret store. The hub's administrator registers only the public key for your account or scope, with
gritpack admin signing-key add(Licence rules, quarantine and the audit log). Package signing keys are separate from your login: a stolen laptop login cannot sign, and a signing key cannot log in. -
Sign each package file. The signature is a small JSON file in the
gritpack/signed-envelope@1format over the exact package file. -
Publish with it. Name the plan node each signature belongs to:
gritpack publish --attestation "native:@bea/core@0.1.1:c/c23:-:-=core.sig.json"Repeat
--attestationfor several. The node IDs are thenative:@bea/...names the plan prints. The same flag works ongritpack publication publish, andgritpack evidence attachadds a signature to a publication that has started but not yet committed.
The hub checks every signature against the registered keys, their validity dates and any revocations immediately before it commits, and refuses the whole publication if a package falls short.
Maturity. Requiring and checking publisher signatures is Available. In Gritpack 1.2.63 the command line has no command that makes the signature file in step 2; it is made with the Gritpack Rust library, so this suits teams that build their own release tooling.
gritpack evidence public-key(below) covers the key pair's public half.
Anyone can see the signatures on a published version:
$ gritpack evidence attestations @bea/report@0.1.0
verified 0 attestations set=... subject=@bea/report@0.1.0 bindings=0 revocations=0 threshold=0/0
On a hub without a threshold this is usually empty, as here; the line says how
many signatures were found and verified, and the threshold they were checked
against. --json gives the full records, and gritpack evidence inspect <sha256> shows any single signed record by the digest the other commands
print.
Making a public key
Several Gritpack features sign with a key whose private half you keep: bundles and static repositories (Offline bundles and slices), and publisher signatures. The private half is a seed: 32 random bytes. Make one with any good random source and keep it secret:
openssl rand -out bundle.seed 32
chmod 600 bundle.seed
Then derive the public key you can share:
$ gritpack evidence public-key --signing-seed bundle.seed --output bundle-public.key
public key=4b03790910e059ca675622bc0db2721d130fa483cf79cc1f07d43211005eb3e0 output=bundle-public.key
The output file holds the public key in base64url; the key= value is its
fingerprint, the same form evidence root uses. Gritpack never overwrites an
existing file here, so you cannot replace a key you already handed out by
accident. Keep each seed for one purpose only.
What just happened
- The hub signs a receipt for every publication and a numbered checkpoint of every version's state, with keys you can fetch and save.
evidence receiptandverify-receiptprove, offline, what was published, by whom and when.evidence lifecycleandverify-lifecycle, with a saved state, catch a hub that shows you an older view.- A hub can require publisher signatures; you register a public key, sign package files, and pass the signatures when publishing.
You can stop here
If you publish and consume on one hub and are content to trust it, you can skip this chapter's commands until someone asks for proof. When they do, the receipts are there.
Next
- Offline bundles and slices: carrying packages, and their evidence, to machines that cannot reach the hub.
- Optional: Scripting with JSON, to keep receipts and checkpoints automatically in CI.