Skip to content

docs(tutorial): the verifier checks signatures, and needs no clone - #337

Merged
imran-siddique merged 1 commit into
mainfrom
tutorial-verify-defaults
Sep 12, 2026
Merged

docs(tutorial): the verifier checks signatures, and needs no clone#337
imran-siddique merged 1 commit into
mainfrom
tutorial-verify-defaults

Conversation

@imran-siddique

Copy link
Copy Markdown
Member

Two corrections to docs/tutorials/anchoring-to-the-registry.md, both found by running the tool the page tells the reader to install.

The one that matters

The page said:

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

trace-verify 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: it invites treating an unverified record as checked, or repeating a check that already ran.

Exit 0 now says what it covers, both halves, and --no-verify-signature is named as the way to get inclusion alone, with the reason it warns.

No clone needed

The page showed --entry registry/2026/06/12.ndjson, a local path, with no mention that the registry need not be cloned. As of trace-verify 0.4.1, --entry-url fetches both the entry and the producer key that signed the record, from an allowlisted host, and reports which key it used and where it came from. The tutorial now shows that invocation and names the minimum version.

One addition

The "what this does not prove" section correctly says inclusion does not establish an append-only history. That question has had an answer since trace-verify 0.4.0, so the section now points at it:

trace-verify chain registry/2026/09/01.ndjson

No normative text changes. Tutorial only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X2GDChXjA7BAdDNzCAmBJv

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
@imran-siddique
imran-siddique requested review from a team and lywinged as code owners September 12, 2026 04:51
@imran-siddique
imran-siddique merged commit c04d938 into main Sep 12, 2026
6 checks passed
@imran-siddique
imran-siddique deleted the tutorial-verify-defaults branch September 12, 2026 04:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant