Skip to content

Commit de7a57a

Browse files
docs(tutorial): the verifier checks signatures, and needs no clone
Step 4 told a reader to pip install trace-verify and run it, then the limits section said "It does not validate the signature ... Signature verification against a trusted producer key is a separate step". The tool has verified the producer's Ed25519 signature by default for as long as the signature extra has existed, and refuses rather than skipping when it cannot. A reader following this page was told exit 0 meant less than it does, which is the direction of error that matters here: it invites treating an unverified record as checked. Exit 0 now says what it covers, both halves. --no-verify-signature is named as the way to get inclusion alone, with the reason it warns. The page also said nothing about verifying without a clone, and the append-only question it raises in "what this does not prove" has had an answer since trace-verify 0.4.0: trace-verify chain. Both are now shown. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X2GDChXjA7BAdDNzCAmBJv
1 parent 1151ad1 commit de7a57a

1 file changed

Lines changed: 18 additions & 2 deletions

File tree

docs/tutorials/anchoring-to-the-registry.md

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,15 @@ trace-verify \
9999
--batch-id 2026-06-12-001
100100
```
101101

102-
Exit code 0 means the record is proven included in that batch. Exit code 1 means it is not, and there is no partial result between the two.
102+
Exit code 0 means the record is proven included in that batch **and** its producer's signature verified. Exit code 1 means one of those failed, and there is no partial result between the two.
103+
104+
You do not need a clone of the registry for this. Swap `--entry` for `--entry-url` and both the entry and the producer key that signed the record are fetched over https, from an allowlisted host only:
105+
106+
```bash
107+
trace-verify --claim your-record.json --proof your-record.proof.json --entry-url https://raw.githubusercontent.com/agentrust-io/trace-registry/main/registry/2026/06/12.ndjson
108+
```
109+
110+
Needs `trace-verify` 0.4.1 or later. The command reports which producer key it used and where it came from, because a key fetched from a host is a different trust statement from one you already held.
103111

104112
The verifier is standard library only and small enough to read in one sitting. Read it, or reimplement it from [Anchor Format v1 §5.1](../../spec/registry-anchor-v1.md), which is written so you can. Verifying with a tool the registry operator wrote is better than nothing, and weaker than verifying with one you wrote.
105113

@@ -115,7 +123,15 @@ Keep the signed object unchanged with its proof and registry entry. Adding `tran
115123

116124
Inclusion verifies the exact signed object against the supplied batch root. Authenticity and timing depend on the separately trusted registry entry or checkpoint.
117125

118-
It does not validate the signature or establish that the record's contents are true. Signature verification against a trusted producer key is a separate step (spec §3.3). Inclusion alone does not establish complete logging, a trustworthy timestamp, or an append-only history.
126+
Signature verification is a separate question from inclusion, and `trace-verify` answers both: it verifies the producer's Ed25519 signature against the registered key unless you pass `--no-verify-signature`, which warns loudly, because inclusion alone does not prove the named producer signed anything. Exit code 0 means both passed.
127+
128+
Neither says the record's contents are true. Inclusion alone does not establish complete logging, a trustworthy timestamp, or an append-only history either. For the last of those, ask the registry's own history the question directly:
129+
130+
```bash
131+
trace-verify chain registry/2026/09/01.ndjson
132+
```
133+
134+
That checks the checkpoint chain is internally consistent and that it still matches the entries stored under it. The second half is what catches an entry edited after it was anchored.
119135

120136
---
121137

0 commit comments

Comments
 (0)