From d5bebfabb2742d72867ef98d98bbc7d2f64ef59a Mon Sep 17 00:00:00 2001 From: Dave Thompson Date: Wed, 19 Aug 2026 17:29:14 -0400 Subject: [PATCH] docs: describe the signed two-phase provenance walk The landing-page provenance story still said the tool should eventually dogfood signed releases. It now matches the shipping cut: tag then host sign, pins from the fingerprint emitter, reviewer path without hand-typed hex. Generated by Grok 4.6 via Grok Build under supervision of @3leapsdave Co-Authored-By: Grok 4.6 Role: cxotech Committer-of-Record: Dave Thompson [@3leapsdave] --- CHANGELOG.md | 5 ++++ README.md | 76 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 52 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e8742d1..ce91183 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +### Changed + +- README provenance story describes the signed two-phase cut and the + fingerprint-pin reviewer path. + ## [0.1.3] - 2026-08-18 First **signed** private cut. Fingerprint pins are generated by diff --git a/README.md b/README.md index 9b951a5..58a4658 100644 --- a/README.md +++ b/README.md @@ -200,40 +200,58 @@ Example: ## Provenance Story -The tool should eventually dogfood the same trust practices it encourages. - -Release artifacts should include: - -- binaries -- `SHA256SUMS` -- `SHA512SUMS` -- signatures over checksum manifests, preferably minisign primary and optional PGP -- exported public signing keys -- release notes -- verification instructions +Decernor dogfoods the same trust practices it encourages. It fingerprints +its own release-signing publics and pins those values into the signed set. +The assets this tool scans are the same class of assets used to sign its +releases. + +A cut is two phases: + +1. Tag `vX.Y.Z`. CI packages unsigned archives and opens a GitHub release. +2. On an operator host, `make release` downloads those archives, stages + committed fingerprint pins and notes, checksums, signs the SUMS + (minisign required; PGP optional), exports publics, verifies, and + uploads onto the same release. + +The signed payload is archives + notes + +`expected-fingerprints.{txt,ndjson}`. Exported `.pub` / `.asc` files ride +beside it; they do not vouch for themselves. Pins are generated by +`decernor fingerprint` on those exported publics +(`make release-insert-anchors`), never hand-typed. Bindings are +environment-variable identifiers only. + +Reviewers: + +1. Inspect the source, including `keys/expected-fingerprints.txt`. +2. Download archives, signed SUMS, exported publics, and the staged pin pair. +3. Verify the signatures over the checksum manifests. +4. Verify archive checksums. The pin files must be members of SUMS. +5. Run `decernor fingerprint` on the exported publics and compare to the + pin file (see below). +6. Run the tool locally and consume structured findings, not key files. + +Layout and signed-set membership: +[`docs/decisions/PDR-0001-committed-signing-anchors.md`](docs/decisions/PDR-0001-committed-signing-anchors.md). +Inserter: [`keys/README.md`](keys/README.md). -Users should be able to: +## Verify a signed release -1. Inspect the source. -2. Download the binary and provenance assets. -3. Verify the signature over the checksum manifest. -4. Verify the binary checksum. -5. Run the tool locally and consume structured findings without exposing key files. +Consume fingerprints, not secrets. Per-cut commands live in +[`docs/releases/v0.1.3.md`](docs/releases/v0.1.3.md). -This matters because the assets being scanned by this tool are often the same class of assets used to sign its releases. +Download the release assets (archives, signed SUMS, exported publics, +staged pin pair). Verify SUMS signatures, then: -## Verify a signed release - -Consume fingerprints, not secrets. Per-cut steps live in -[`docs/releases/v0.1.3.md`](docs/releases/v0.1.3.md). Committed pins and -the inserter are documented in [`keys/README.md`](keys/README.md). How -those pins enter the signed set is -[`docs/decisions/PDR-0001-committed-signing-anchors.md`](docs/decisions/PDR-0001-committed-signing-anchors.md). +```sh +decernor fingerprint decernor-release-signing-key.asc \ + --class public --kind gpg --format json --path-mode none --gpg-role primary +decernor fingerprint decernor-minisign.pub \ + --class public --kind minisign --format json --path-mode none +``` -Download the draft (archives, signed SUMS, exported publics, staged pin -pair). Verify SUMS signatures, then run `decernor fingerprint` on the -exported publics and compare to `expected-fingerprints.txt`. Never -hand-type hex into notes or a README. +The GPG primary fingerprint and the minisign public-blob SHA-256 must +match the `gpg` and `minisign` lines in `expected-fingerprints.txt`. +Never hand-type hex into notes or a README. ## Build