From f6db05b27cf9e12dab1c76b9053bba32d52b8243 Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Sat, 31 Oct 2026 09:21:57 -0400 Subject: [PATCH 1/2] docs: pin signer workflow and tag on the runbook's attestation verify Step 1 of the root-custody upgrade runbook ran `gh attestation verify` with `--repo` only, which accepts an attestation from any workflow in the repo, built from any ref. Pin `--signer-workflow` to release.yml, `--source-ref` to the version tag and `--source-digest` to the tag's commit, verify SHA256SUMS the same way, and check the archive with `shasum -c`. Co-Authored-By: Claude Opus 5.5 --- docs/custody-upgrade-runbook.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/custody-upgrade-runbook.md b/docs/custody-upgrade-runbook.md index 3d4d5eaa..2e584ce8 100644 --- a/docs/custody-upgrade-runbook.md +++ b/docs/custody-upgrade-runbook.md @@ -4,13 +4,28 @@ Use this to upgrade a `facet` binary installed under a root-owned prefix (` --repo Hedronite/facet` must pass. After you extract the archive, record `shasum -a 256 facet` and check it against the attested release digest (`SHA256SUMS`, which is attested too). +1. **Verify the release.** Before you extract anything, check that the release workflow built the archive and `SHA256SUMS` from the tag you mean to install (block below). Both `gh attestation verify` runs must exit 0, and `shasum -c` must print `OK`. After you extract the archive, record `shasum -a 256 facet`: that is the sha the allowlist pins. 2. **Install under the root prefix.** Put the binary at `$D/facet//facet` (root-owned) and stage the allowlist that matches the version. 3. **Lock and switch** (block below). 4. **Post-checks** (below). Do not go on until every check passes. 5. **Smokes and QA.** Run `facet --version`, `facet doctor --json`, and your usual smoke runs against the live path. 6. **Announce downstream.** Tell dependent hosts or users that `` is live. +## Verify the release + +```bash +V= # e.g. 0.8.0 +T=$(gh api repos/Hedronite/facet/commits/v$V --jq .sha) # the commit the tag points at +for f in facet-cli-$V-macos-arm64.tar.gz SHA256SUMS; do + gh attestation verify $f --repo Hedronite/facet \ + --signer-workflow Hedronite/facet/.github/workflows/release.yml \ + --source-ref refs/tags/v$V --source-digest $T +done +shasum -a 256 -c SHA256SUMS --ignore-missing # the archive matches the attested digest list +``` + +`--repo` alone accepts an attestation from any workflow in the repo, built from any ref. The three pins tie it to `release.yml`, the `v` tag and that tag's commit, so an archive built from a branch or another workflow fails here. + ## Lock and switch ```bash From 145fe0eb2479638eed56202224ad4d7a825ab1ad Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Sat, 31 Oct 2026 10:33:03 -0400 Subject: [PATCH 2/2] docs: pin signer workflow and tag on install.md's attestation verify The install guide's provenance check ran `gh attestation verify` with `--repo` only. Use the same pins as the custody runbook (`--signer-workflow` release.yml, `--source-ref` the v0.8.0 tag, `--source-digest` its commit), verify SHA256SUMS too, and check the archive with `shasum -c` (`sha256sum -c` on Linux). Co-Authored-By: Claude Opus 5.5 --- docs/install.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/install.md b/docs/install.md index ba9f4212..319a0e9f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -99,14 +99,19 @@ facet --version ### Release archive provenance -Release archives from 0.8.0 on carry a signed build provenance attestation (keyless, via GitHub and Sigstore), and so does `SHA256SUMS`. Before you extract an archive, check that the release workflow in `Hedronite/facet` built it: +Release archives from 0.8.0 on carry a signed build provenance attestation (keyless, via GitHub and Sigstore), and so does `SHA256SUMS`. Before you extract an archive, check that `release.yml` in `Hedronite/facet` built it from the `v0.8.0` tag: ```bash -gh attestation verify facet-cli-0.8.0-macos-arm64.tar.gz --repo Hedronite/facet -gh attestation verify facet-cli-0.8.0-linux-x64.tar.gz --repo Hedronite/facet +T=$(gh api repos/Hedronite/facet/commits/v0.8.0 --jq .sha) # the commit the tag points at +for f in facet-cli-0.8.0-macos-arm64.tar.gz SHA256SUMS; do # linux: facet-cli-0.8.0-linux-x64.tar.gz + gh attestation verify $f --repo Hedronite/facet \ + --signer-workflow Hedronite/facet/.github/workflows/release.yml \ + --source-ref refs/tags/v0.8.0 --source-digest $T +done +shasum -a 256 -c SHA256SUMS --ignore-missing # linux: sha256sum -c SHA256SUMS --ignore-missing ``` -It needs the [GitHub CLI](https://cli.github.com/), logged in. It exits non-zero when the file has no valid attestation from this repo, so do not run that binary. Releases before 0.8.0 have no attestation. +It needs the [GitHub CLI](https://cli.github.com/), logged in. `--repo` alone accepts an attestation from any workflow in the repo, built from any ref; the other three flags tie it to the release workflow and the tag. Each command exits non-zero when the file has no matching attestation, so do not run that binary. Releases before 0.8.0 have no attestation. ### Installed binary