From 9936ae15b6d9b62e4f9b439e71b07911c281466c Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Thu, 19 Nov 2026 05:32:18 -0500 Subject: [PATCH 1/3] ci: sign releases with build provenance and an attested SBOM The release workflow now writes a CycloneDX SBOM of the module (cyclonedx-gomod v1.12.0, pinned through the Go checksum database), adds it to checksums.txt and the release, and attests build provenance and the SBOM for every archive (actions/attest-build-provenance v4.2.2 and actions/attest-sbom v4.1.0, SHA-pinned, subject-checksums). Keyless: Sigstore signs with the job's OIDC token. Permissions move to the job (contents, id-token, attestations write); the workflow grants nothing at the top level. README shows how to verify a download. P5c of the program. --- .github/workflows/release.yml | 37 +++++++++++++++++++++++++++++------ README.md | 11 ++++++++++- TECHNICAL.md | 2 +- 3 files changed, 42 insertions(+), 8 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index cc7835a..ef3a018 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,21 +1,27 @@ name: Release # Fires when a version tag is pushed (e.g. `v0.4.0`). Cross-compiles static -# binaries (CGO_ENABLED=0; the SQLite driver is pure Go), writes SHA-256 -# checksums, and publishes them as a GitHub Release with generated notes. +# binaries (CGO_ENABLED=0; the SQLite driver is pure Go), writes a CycloneDX +# SBOM and SHA-256 checksums, attests build provenance and the SBOM for every +# archive (keyless, through Sigstore with this workflow's OIDC token), and +# publishes them as a GitHub Release with generated notes. # The tag is the single source of the version: it is stamped into the binary # with -ldflags, so `codeshot --version` can never disagree with the release. +# Verify a download: `gh attestation verify --repo inth3shadows/codeshot`. on: push: tags: - "v*" -permissions: - contents: write # create the GitHub Release + upload assets; nothing more +permissions: {} jobs: release: name: Build + publish GitHub Release runs-on: ubuntu-latest + permissions: + contents: write # create the GitHub Release + upload assets + id-token: write # the OIDC token Sigstore signs the attestations with + attestations: write # store the provenance and SBOM attestations steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 with: @@ -29,8 +35,10 @@ jobs: run: sudo apt-get update && sudo apt-get install -y graphviz && go test ./... - name: Cross-compile + id: build run: | version="${GITHUB_REF_NAME#v}" + echo "version=${version}" >> "$GITHUB_OUTPUT" mkdir -p dist for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do os="${target%/*}"; arch="${target#*/}" @@ -47,9 +55,26 @@ jobs: tar -C dist -czf "dist/$name.tar.gz" "$name" fi done - (cd dist && sha256sum *.tar.gz *.zip > checksums.txt) + # One SBOM for the module (all six builds share its dependencies), + # pinned through the Go checksum database. The tag checkout gives it + # the version. + go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.12.0 \ + mod -licenses -json -output "dist/codeshot_${version}.cdx.json" + (cd dist && sha256sum *.tar.gz *.zip *.cdx.json > checksums.txt) + + # Provenance for every archive and the SBOM, in one attestation over the + # checksums file; then the SBOM itself, bound to the same subjects. + - name: Attest build provenance + uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 + with: + subject-checksums: dist/checksums.txt + - name: Attest the SBOM + uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0 + with: + subject-checksums: dist/checksums.txt + sbom-path: dist/codeshot_${{ steps.build.outputs.version }}.cdx.json - name: Publish GitHub Release env: GH_TOKEN: ${{ github.token }} - run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/checksums.txt --generate-notes --title "${GITHUB_REF_NAME}" + run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/*.cdx.json dist/checksums.txt --generate-notes --title "${GITHUB_REF_NAME}" diff --git a/README.md b/README.md index 8335103..025823b 100644 --- a/README.md +++ b/README.md @@ -58,12 +58,21 @@ Generated diagrams are easy; trusted ones aren't. Tools like madge, pyan and go- ## Install -Download a binary for your platform from [Releases](https://github.com/inth3shadows/codeshot/releases) (checksums in `checksums.txt`), or build from source with Go 1.26+: +Download a binary for your platform from [Releases](https://github.com/inth3shadows/codeshot/releases), or build from source with Go 1.26+: ```bash go install github.com/inth3shadows/codeshot/cmd/codeshot@latest ``` +From v0.5.0 on, every release archive comes with a signed record of the workflow run that built it ([build provenance](https://slsa.dev/provenance/), keyless through Sigstore) and a [CycloneDX](https://cyclonedx.org/) SBOM, `codeshot_.cdx.json`, attested for the same archives. To check a download with the [GitHub CLI](https://cli.github.com/): + +```bash +sha256sum -c checksums.txt --ignore-missing # the archive is the one published +gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot +gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \ + --predicate-type https://cyclonedx.org/bom # the SBOM attestation +``` + Codeshot is a single static binary; it needs no Node of its own. `codeshot --version` prints the release version for release binaries and `go install ...@vX.Y.Z`, and `dev` for any other build. **Requirements:** diff --git a/TECHNICAL.md b/TECHNICAL.md index 529a78b..3e8379d 100644 --- a/TECHNICAL.md +++ b/TECHNICAL.md @@ -263,7 +263,7 @@ codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embe codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md ``` -CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes `checksums.txt`, and publishes them as a GitHub Release. +CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module (`cyclonedx-gomod` v1.12.0 through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, attests build provenance for everything in `checksums.txt` (`actions/attest-build-provenance`, `subject-checksums`) and the SBOM for the same subjects (`actions/attest-sbom`), and publishes them as a GitHub Release. The attestations are keyless: Sigstore signs them with the job's OIDC token, so the job needs `id-token: write` and `attestations: write` beside `contents: write`, and the workflow grants nothing at the top level. `gh attestation verify --repo inth3shadows/codeshot` checks a download. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating. There is no service to restart, no rollback beyond installing a prior release or git ref, and no other services, logs, or scheduled jobs to maintain — see [README.md](README.md#install) for the install command itself. From bc6061405295d6df4db764026b2f855d51639cd2 Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Thu, 19 Nov 2026 06:02:57 -0500 Subject: [PATCH 2/3] ci: release review round 1 (separate signing job, stdlib in the SBOM) - F1: the build job (tests, builds, SBOM tool) has contents: read only and hands the files over as an artifact; a publish job that runs no build or test code holds id-token/attestations and attests and publishes, so build-time code can't mint the signing token. - F2: the SBOM includes the Go standard library (-std). - F5: actions/attest v4.2.2 directly for both attestations (the wrappers pulled two inner versions; attest-sbom is deprecated). - F4: the SBOM is attested for the six archives, not for itself. - F6: a tag that isn't v fails the build before anything is made. - F7/A2: README verification pins the release workflow and tag, and shows the macOS checksum command. --- .github/workflows/release.yml | 81 +++++++++++++++++++++++++++-------- README.md | 12 ++++-- TECHNICAL.md | 2 +- 3 files changed, 74 insertions(+), 21 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ef3a018..b31c7c7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,12 +1,14 @@ name: Release # Fires when a version tag is pushed (e.g. `v0.4.0`). Cross-compiles static -# binaries (CGO_ENABLED=0; the SQLite driver is pure Go), writes a CycloneDX -# SBOM and SHA-256 checksums, attests build provenance and the SBOM for every -# archive (keyless, through Sigstore with this workflow's OIDC token), and -# publishes them as a GitHub Release with generated notes. +# binaries (CGO_ENABLED=0; the SQLite driver is pure Go) and writes a CycloneDX +# SBOM and SHA-256 checksums in one job; a second job, which runs no build or +# test code, attests build provenance and the SBOM for every archive (keyless, +# through Sigstore with its OIDC token) and publishes them as a GitHub Release +# with generated notes. # The tag is the single source of the version: it is stamped into the binary # with -ldflags, so `codeshot --version` can never disagree with the release. -# Verify a download: `gh attestation verify --repo inth3shadows/codeshot`. +# Verify a download: `gh attestation verify --repo inth3shadows/codeshot +# --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml`. on: push: tags: @@ -15,13 +17,16 @@ on: permissions: {} jobs: - release: - name: Build + publish GitHub Release + # Runs the tests, the build and the SBOM tool, so it gets no signing + # permission: code here can't mint the OIDC token the attestations are + # signed with (F1). It hands the release files to the publish job. + build: + name: Test, build + SBOM runs-on: ubuntu-latest permissions: - contents: write # create the GitHub Release + upload assets - id-token: write # the OIDC token Sigstore signs the attestations with - attestations: write # store the provenance and SBOM attestations + contents: read + outputs: + version: ${{ steps.build.outputs.version }} steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 with: @@ -38,6 +43,12 @@ jobs: id: build run: | version="${GITHUB_REF_NAME#v}" + # A release tag is v: anything else would name the archives + # one way and give the SBOM a pseudo-version (F6). + if ! [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then + echo "::error::tag ${GITHUB_REF_NAME} is not v..[-
]"
+            exit 1
+          fi
           echo "version=${version}" >> "$GITHUB_OUTPUT"
           mkdir -p dist
           for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
@@ -58,23 +69,59 @@ jobs:
           # One SBOM for the module (all six builds share its dependencies),
           # pinned through the Go checksum database. The tag checkout gives it
           # the version.
+          # -std lists the Go standard library compiled into every binary (F2).
           go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.12.0 \
-            mod -licenses -json -output "dist/codeshot_${version}.cdx.json"
+            mod -licenses -std -json -output "dist/codeshot_${version}.cdx.json"
           (cd dist && sha256sum *.tar.gz *.zip *.cdx.json > checksums.txt)
 
+      - name: Hand the release files to the publish job
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-files
+          path: |
+            dist/*.tar.gz
+            dist/*.zip
+            dist/*.cdx.json
+            dist/checksums.txt
+          if-no-files-found: error
+          retention-days: 1
+
+  # Signs and publishes; runs no build, test or third-party build code.
+  publish:
+    name: Attest + publish GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the GitHub Release + upload assets
+      id-token: write # the OIDC token Sigstore signs the attestations with
+      attestations: write # store the provenance and SBOM attestations
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-files
+          path: dist
+      - name: Check the files arrived intact
+        run: cd dist && sha256sum -c checksums.txt
+
       # Provenance for every archive and the SBOM, in one attestation over the
-      # checksums file; then the SBOM itself, bound to the same subjects.
+      # checksums file; then the SBOM, attested for the archives it describes.
+      # actions/attest directly: attest-build-provenance and attest-sbom are
+      # wrappers around it, and attest-sbom is deprecated (F5).
       - name: Attest build provenance
-        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-checksums: dist/checksums.txt
+          create-storage-record: false
       - name: Attest the SBOM
-        uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
-          subject-checksums: dist/checksums.txt
-          sbom-path: dist/codeshot_${{ steps.build.outputs.version }}.cdx.json
+          subject-path: |
+            dist/*.tar.gz
+            dist/*.zip
+          sbom-path: dist/codeshot_${{ needs.build.outputs.version }}.cdx.json
+          create-storage-record: false
 
       - name: Publish GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/*.cdx.json dist/checksums.txt --generate-notes --title "${GITHUB_REF_NAME}"
+        run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/*.cdx.json dist/checksums.txt --repo "${GITHUB_REPOSITORY}" --generate-notes --title "${GITHUB_REF_NAME}"
diff --git a/README.md b/README.md
index 025823b..e6ad91d 100644
--- a/README.md
+++ b/README.md
@@ -67,12 +67,18 @@ go install github.com/inth3shadows/codeshot/cmd/codeshot@latest
 From v0.5.0 on, every release archive comes with a signed record of the workflow run that built it ([build provenance](https://slsa.dev/provenance/), keyless through Sigstore) and a [CycloneDX](https://cyclonedx.org/) SBOM, `codeshot_.cdx.json`, attested for the same archives. To check a download with the [GitHub CLI](https://cli.github.com/):
 
 ```bash
-sha256sum -c checksums.txt --ignore-missing    # the archive is the one published
-gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot
+sha256sum -c checksums.txt --ignore-missing   # Linux; on macOS: shasum -a 256 -c checksums.txt --ignore-missing
 gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
-  --predicate-type https://cyclonedx.org/bom   # the SBOM attestation
+  --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0
+gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
+  --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0 \
+  --predicate-type https://cyclonedx.org/bom    # the SBOM attestation
 ```
 
+`--signer-workflow` and `--source-ref` accept only an attestation made by the
+release workflow for that tag, not one any other workflow in the repo could
+make.
+
 Codeshot is a single static binary; it needs no Node of its own. `codeshot --version` prints the release version for release binaries and `go install ...@vX.Y.Z`, and `dev` for any other build.
 
 **Requirements:**
diff --git a/TECHNICAL.md b/TECHNICAL.md
index 3e8379d..0c7c0cb 100644
--- a/TECHNICAL.md
+++ b/TECHNICAL.md
@@ -263,7 +263,7 @@ codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embe
 codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md
 ```
 
-CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git  && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module (`cyclonedx-gomod` v1.12.0 through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, attests build provenance for everything in `checksums.txt` (`actions/attest-build-provenance`, `subject-checksums`) and the SBOM for the same subjects (`actions/attest-sbom`), and publishes them as a GitHub Release. The attestations are keyless: Sigstore signs them with the job's OIDC token, so the job needs `id-token: write` and `attestations: write` beside `contents: write`, and the workflow grants nothing at the top level. `gh attestation verify  --repo inth3shadows/codeshot` checks a download. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating.
+CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git  && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml` in two jobs. `build` (`contents: read` only) refuses a tag that isn't `v`, runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module including the Go standard library (`cyclonedx-gomod` v1.12.0 `mod -licenses -std` through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, and uploads them as a one-day artifact. `publish` (`contents`, `id-token` and `attestations: write`) runs no build, test or third-party build code: it downloads the files, checks them against `checksums.txt`, attests build provenance for everything in `checksums.txt` and the SBOM for the six archives (`actions/attest` v4.2.2 both times, SHA-pinned; `attest-build-provenance` and the deprecated `attest-sbom` are wrappers around it; no storage record), and publishes the GitHub Release. Splitting the jobs keeps the OIDC token away from the tests and the SBOM tool's dependencies, which could otherwise mint it and attest arbitrary files as built here. The attestations are keyless: Sigstore signs them with that token, and the workflow grants nothing at the top level. `gh attestation verify  --repo inth3shadows/codeshot --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml` checks a download. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating.
 
 There is no service to restart, no rollback beyond installing a prior release or git ref, and no other services, logs, or scheduled jobs to maintain — see [README.md](README.md#install) for the install command itself.
 

From 35af16f3aebea8cd3d275e92df0fa914842aca25 Mon Sep 17 00:00:00 2001
From: Eric Minish 
Date: Thu, 19 Nov 2026 06:23:11 -0500
Subject: [PATCH 3/3] ci: release review round 2 (expected files only, strict
 semver)

- V1/V6: publish refuses unless checksums.txt lists, and the artifact
  holds, exactly the seven expected files for the version, so a
  compromised build job can't add a file to be attested and published.
- A1: the tag check is strict semver (no leading zeros), so v01.2.3 no
  longer gives the SBOM a pseudo-version.
- V2/V3/V5: README and TECHNICAL say what each check proves: checksums
  are integrity only; --signer-workflow/--source-ref trust release.yml
  at the tagged commit, so they are as strong as v* tag protection.
- V7: the artifact is kept seven days, so publish can be re-run alone.
- V8/V9: no review IDs in comments; no redundant storage-record input.
---
 .github/workflows/release.yml | 46 ++++++++++++++++++++++++++---------
 README.md                     | 11 ++++++---
 TECHNICAL.md                  |  2 +-
 3 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b31c7c7..6d648d5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -8,7 +8,8 @@ name: Release
 # The tag is the single source of the version: it is stamped into the binary
 # with -ldflags, so `codeshot --version` can never disagree with the release.
 # Verify a download: `gh attestation verify  --repo inth3shadows/codeshot
-#   --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml`.
+#   --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml
+#   --source-ref refs/tags/`.
 on:
   push:
     tags:
@@ -19,7 +20,7 @@ permissions: {}
 jobs:
   # Runs the tests, the build and the SBOM tool, so it gets no signing
   # permission: code here can't mint the OIDC token the attestations are
-  # signed with (F1). It hands the release files to the publish job.
+  # signed with. It hands the release files to the publish job.
   build:
     name: Test, build + SBOM
     runs-on: ubuntu-latest
@@ -43,9 +44,12 @@ jobs:
         id: build
         run: |
           version="${GITHUB_REF_NAME#v}"
-          # A release tag is v: anything else would name the archives
-          # one way and give the SBOM a pseudo-version (F6).
-          if ! [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+          # A release tag is v (no leading zeros, optional pre-release):
+          # anything else would name the archives one way and give the SBOM a
+          # pseudo-version.
+          num='(0|[1-9][0-9]*)'
+          pre='(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)'
+          if ! [[ "$version" =~ ^$num\.$num\.$num(-$pre(\.$pre)*)?$ ]]; then
             echo "::error::tag ${GITHUB_REF_NAME} is not v..[-
]"
             exit 1
           fi
@@ -69,7 +73,7 @@ jobs:
           # One SBOM for the module (all six builds share its dependencies),
           # pinned through the Go checksum database. The tag checkout gives it
           # the version.
-          # -std lists the Go standard library compiled into every binary (F2).
+          # -std lists the Go standard library compiled into every binary.
           go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.12.0 \
             mod -licenses -std -json -output "dist/codeshot_${version}.cdx.json"
           (cd dist && sha256sum *.tar.gz *.zip *.cdx.json > checksums.txt)
@@ -84,7 +88,7 @@ jobs:
             dist/*.cdx.json
             dist/checksums.txt
           if-no-files-found: error
-          retention-days: 1
+          retention-days: 7 # long enough to re-run publish on its own
 
   # Signs and publishes; runs no build, test or third-party build code.
   publish:
@@ -100,18 +104,37 @@ jobs:
         with:
           name: release-files
           path: dist
-      - name: Check the files arrived intact
-        run: cd dist && sha256sum -c checksums.txt
+      # The build job could add or swap files; only the expected release files,
+      # listed in checksums.txt and nothing else, get attested and published.
+      - name: Check the release files are exactly the expected ones
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          cd dist
+          expected=$(
+            for t in linux_amd64 linux_arm64 darwin_amd64 darwin_arm64; do echo "codeshot_${VERSION}_${t}.tar.gz"; done
+            for t in windows_amd64 windows_arm64; do echo "codeshot_${VERSION}_${t}.zip"; done
+            echo "codeshot_${VERSION}.cdx.json"
+          )
+          expected=$(echo "$expected" | LC_ALL=C sort)
+          listed=$(awk '{ sub(/^\*/, "", $2); print $2 }' checksums.txt | LC_ALL=C sort)
+          present=$(ls -1A | grep -vx 'checksums.txt' | LC_ALL=C sort)
+          if [ "$listed" != "$expected" ] || [ "$present" != "$expected" ]; then
+            echo "::error::the release files are not exactly the expected seven"
+            diff <(echo "$expected") <(echo "$listed") || true
+            diff <(echo "$expected") <(echo "$present") || true
+            exit 1
+          fi
+          sha256sum -c checksums.txt
 
       # Provenance for every archive and the SBOM, in one attestation over the
       # checksums file; then the SBOM, attested for the archives it describes.
       # actions/attest directly: attest-build-provenance and attest-sbom are
-      # wrappers around it, and attest-sbom is deprecated (F5).
+      # wrappers around it, and attest-sbom is deprecated.
       - name: Attest build provenance
         uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-checksums: dist/checksums.txt
-          create-storage-record: false
       - name: Attest the SBOM
         uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
@@ -119,7 +142,6 @@ jobs:
             dist/*.tar.gz
             dist/*.zip
           sbom-path: dist/codeshot_${{ needs.build.outputs.version }}.cdx.json
-          create-storage-record: false
 
       - name: Publish GitHub Release
         env:
diff --git a/README.md b/README.md
index e6ad91d..e3c84c6 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ go install github.com/inth3shadows/codeshot/cmd/codeshot@latest
 From v0.5.0 on, every release archive comes with a signed record of the workflow run that built it ([build provenance](https://slsa.dev/provenance/), keyless through Sigstore) and a [CycloneDX](https://cyclonedx.org/) SBOM, `codeshot_.cdx.json`, attested for the same archives. To check a download with the [GitHub CLI](https://cli.github.com/):
 
 ```bash
-sha256sum -c checksums.txt --ignore-missing   # Linux; on macOS: shasum -a 256 -c checksums.txt --ignore-missing
+sha256sum -c checksums.txt --ignore-missing   # download intact (Linux; macOS: shasum -a 256 -c ...)
 gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
   --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0
 gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
@@ -75,9 +75,12 @@ gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/code
   --predicate-type https://cyclonedx.org/bom    # the SBOM attestation
 ```
 
-`--signer-workflow` and `--source-ref` accept only an attestation made by the
-release workflow for that tag, not one any other workflow in the repo could
-make.
+The checksum line only shows the download is intact: `checksums.txt` comes from
+the same release and isn't signed itself. The attestation is the proof of
+origin. `--signer-workflow` and `--source-ref` require it to come from
+`release.yml` running for that tag, not from any other workflow in the repo;
+they trust whatever `release.yml` was at the tagged commit, so they are as
+strong as the protection on `v*` tags.
 
 Codeshot is a single static binary; it needs no Node of its own. `codeshot --version` prints the release version for release binaries and `go install ...@vX.Y.Z`, and `dev` for any other build.
 
diff --git a/TECHNICAL.md b/TECHNICAL.md
index 0c7c0cb..3b66942 100644
--- a/TECHNICAL.md
+++ b/TECHNICAL.md
@@ -263,7 +263,7 @@ codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embe
 codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md
 ```
 
-CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git  && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml` in two jobs. `build` (`contents: read` only) refuses a tag that isn't `v`, runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module including the Go standard library (`cyclonedx-gomod` v1.12.0 `mod -licenses -std` through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, and uploads them as a one-day artifact. `publish` (`contents`, `id-token` and `attestations: write`) runs no build, test or third-party build code: it downloads the files, checks them against `checksums.txt`, attests build provenance for everything in `checksums.txt` and the SBOM for the six archives (`actions/attest` v4.2.2 both times, SHA-pinned; `attest-build-provenance` and the deprecated `attest-sbom` are wrappers around it; no storage record), and publishes the GitHub Release. Splitting the jobs keeps the OIDC token away from the tests and the SBOM tool's dependencies, which could otherwise mint it and attest arbitrary files as built here. The attestations are keyless: Sigstore signs them with that token, and the workflow grants nothing at the top level. `gh attestation verify  --repo inth3shadows/codeshot --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml` checks a download. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating.
+CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git  && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml` in two jobs. `build` (`contents: read` only) refuses a tag that isn't `v` (no leading zeros; an optional pre-release), runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module including the Go standard library (`cyclonedx-gomod` v1.12.0 `mod -licenses -std` through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, and uploads them as a one-day artifact. `publish` (`contents`, `id-token` and `attestations: write`) runs no build, test or third-party build code: it downloads the files, checks them against `checksums.txt`, refuses unless `checksums.txt` lists, and the artifact holds, exactly the seven expected files for the version (six archives and the SBOM), attests build provenance for them and the SBOM for the six archives (`actions/attest` v4.2.2 both times, SHA-pinned; `attest-build-provenance` and the deprecated `attest-sbom` are wrappers around it), and publishes the GitHub Release. Splitting the jobs keeps the OIDC token away from the tests and the SBOM tool's dependencies, which could otherwise mint it and attest any file as built here; a compromised build job can still change the bytes of the seven files it hands over, which no signing step can tell apart from a real build. The artifact is kept seven days, so `publish` can be re-run on its own. The attestations are keyless: Sigstore signs them with that token, and the workflow grants nothing at the top level. `gh attestation verify  --repo inth3shadows/codeshot --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/` checks a download; it trusts whatever `release.yml` was at the tagged commit, so it is as strong as the protection on `v*` tags. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating.
 
 There is no service to restart, no rollback beyond installing a prior release or git ref, and no other services, logs, or scheduled jobs to maintain — see [README.md](README.md#install) for the install command itself.