feat(workflows): publish SLSA provenance + SBOM attestations on every release tag (closes #58) (#94)

Co-authored-by: chrisleekr-bot[bot] <2890262+chrisleekr-bot[bot]@users.noreply.github.com>
Co-authored-by: chrisleekr-bot[bot] <chrisleekr-bot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: 3 people

.github/workflows/docker-build.yml

@@ -54,6 +54,11 @@ on:
 permissions:
   contents: read
   security-events: write
+  # Read-only attestations grant lets the `scan` job verify SLSA / SBOM
+  # attestations via `gh attestation verify` before scanning. The `merge`
+  # job overrides locally to add the `id-token: write` + `attestations: write`
+  # scopes required to publish Sigstore-signed attestations.
+  attestations: read
 
 env:
   IMAGE_NAME: chrisleekr/github-app-playground
@@ -152,6 +157,16 @@ jobs:
             }},push-by-digest=true,name-canonical=true,push=true
           cache-from: type=gha,scope=${{ matrix.arch }}-${{ matrix.variant }}
           cache-to: type=gha,mode=max,scope=${{ matrix.arch }}-${{ matrix.variant }}
+          # SLSA v1 provenance (full BuildKit invocation) + SPDX SBOM.
+          # build-push-action defaults `provenance` to false when
+          # `push-by-digest=true` (the leaf-attestation problem), so set both
+          # explicitly. BuildKit emits an attestation-manifest descriptor
+          # alongside each leaf image; the merge step's index digest
+          # references both, so `imagetools create` carries the descriptors
+          # into the published manifest list automatically.
+          # https://docs.docker.com/build/ci/github-actions/multi-platform/
+          provenance: mode=max
+          sbom: true
           build-args: |
             PACKAGE_VERSION=${{ steps.meta.outputs.package_version }}
             GIT_HASH=${{ steps.meta.outputs.git_hash }}
@@ -176,7 +191,15 @@ jobs:
     name: Merge manifest (${{ matrix.variant }})
     needs: build
     runs-on: ubuntu-24.04
-    timeout-minutes: 10
+    timeout-minutes: 15
+    # Least-privilege override: this job is the only one that publishes
+    # Sigstore-signed attestations, so it gets `id-token: write` (Sigstore
+    # OIDC) + `attestations: write` (GitHub Attestations API). Build / scan
+    # keep the top-level read-only set.
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
     strategy:
       fail-fast: false
       matrix:
@@ -223,16 +246,56 @@ jobs:
         env:
           IMAGE: ${{ env.IMAGE_NAME }}
         run: |
+          # The leaf digests below are *index* digests emitted by BuildKit
+          # when `provenance: mode=max` + `sbom: true` are set on the build
+          # step — each index references both the per-arch image manifest
+          # AND its `vnd.docker.reference.type=attestation-manifest`
+          # sibling. `imagetools create` walks each index and copies all
+          # descriptors into the merged list, so SBOM + provenance survive
+          # the merge without any extra CLI plumbing here.
           # shellcheck disable=SC2046
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             $(printf "${IMAGE}@sha256:%s " *)
 
-      - name: Inspect image
+      - name: Inspect merged image and capture digest
+        id: inspect
         env:
           IMAGE: ${{ env.IMAGE_NAME }}
           TAG: ${{ steps.tag.outputs.variant_tag }}
-        run: docker buildx imagetools inspect "${IMAGE}:${TAG}"
+        run: |
+          docker buildx imagetools inspect "${IMAGE}:${TAG}"
+          DIGEST=$(docker buildx imagetools inspect "${IMAGE}:${TAG}" \
+            --format '{{ .Manifest.Digest }}')
+          if ! [[ "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+            echo "ERROR: failed to parse merged manifest digest: $DIGEST" >&2
+            exit 1
+          fi
+          echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate CycloneDX SBOM for merged image
+        uses: anchore/sbom-action@v0
+        with:
+          image: ${{ env.IMAGE_NAME }}@${{ steps.inspect.outputs.digest }}
+          format: cyclonedx-json
+          output-file: "sbom-${{ matrix.variant }}.cyclonedx.json"
+          upload-artifact: false
+          upload-release-assets: false
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@v4
+        with:
+          subject-name: ${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.inspect.outputs.digest }}
+          push-to-registry: true
+
+      - name: Attest SBOM
+        uses: actions/attest-sbom@v4
+        with:
+          subject-name: ${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.inspect.outputs.digest }}
+          sbom-path: "sbom-${{ matrix.variant }}.cyclonedx.json"
+          push-to-registry: true
 
   scan:
     name: Trivy scan (${{ matrix.variant }} / ${{ matrix.arch }})
@@ -263,6 +326,22 @@ jobs:
           PACKAGE_VERSION="${TAG_NAME#v}"
           echo "tag=${PACKAGE_VERSION}-${VARIANT}" >> "$GITHUB_OUTPUT"
 
+      # Regression gate: fail the workflow if the published image is missing
+      # its Sigstore-signed SLSA provenance + SBOM attestations. Catches
+      # silent drops from future refactors of the build / merge jobs.
+      - name: Verify image attestations
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          IMAGE_REF: oci://${{ env.IMAGE_NAME }}:${{ steps.imgtag.outputs.tag }}
+          REPO: ${{ github.repository }}
+        run: |
+          # Two separate calls: each fails if the requested predicate type is
+          # absent, so this catches a regression that drops EITHER attestation.
+          gh attestation verify "$IMAGE_REF" --repo "$REPO" \
+            --predicate-type https://slsa.dev/provenance/v1
+          gh attestation verify "$IMAGE_REF" --repo "$REPO" \
+            --predicate-type https://cyclonedx.org/bom
+
       - name: Scan image with Trivy
         uses: aquasecurity/trivy-action@v0.35.0
         env:

CLAUDE.md

@@ -92,13 +92,13 @@ The scheduled research workflow in `.github/workflows/research.yml` also uses `C
 
 Five workflow files form the pipeline; each owns one responsibility.
 
-| Workflow                             | Trigger                                                   | Owns                                                                                                               |
-| ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `.github/workflows/ci.yml`           | `pull_request` + `push: main` + `workflow_call`           | Quality gates only: typecheck, lint, format, audit:ci, test, build                                                 |
-| `.github/workflows/secrets-scan.yml` | `push: branches-ignore: [gh-pages]` + `workflow_dispatch` | Standalone gitleaks secret scan — decoupled from ci.yml so every push (incl. chore/docs/ci/test branches) is gated |
-| `.github/workflows/dev-release.yml`  | `push: branches-ignore: [main, v*]` + `workflow_dispatch` | Calls `ci.yml` → semantic-release dev (pre-release tag) → calls `docker-build.yml`                                 |
-| `.github/workflows/release.yml`      | `workflow_dispatch` only (manual)                         | Calls `ci.yml` → semantic-release prod → calls `docker-build.yml`                                                  |
-| `.github/workflows/docker-build.yml` | `workflow_call` + `workflow_dispatch`                     | Reusable image builder: matrix split-and-merge (amd64 on `ubuntu-24.04` + arm64 on `ubuntu-24.04-arm`), Trivy scan |
+| Workflow                             | Trigger                                                   | Owns                                                                                                                                                                                                                      |
+| ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.github/workflows/ci.yml`           | `pull_request` + `push: main` + `workflow_call`           | Quality gates only: typecheck, lint, format, audit:ci, test, build                                                                                                                                                        |
+| `.github/workflows/secrets-scan.yml` | `push: branches-ignore: [gh-pages]` + `workflow_dispatch` | Standalone gitleaks secret scan — decoupled from ci.yml so every push (incl. chore/docs/ci/test branches) is gated                                                                                                        |
+| `.github/workflows/dev-release.yml`  | `push: branches-ignore: [main, v*]` + `workflow_dispatch` | Calls `ci.yml` → semantic-release dev (pre-release tag) → calls `docker-build.yml`                                                                                                                                        |
+| `.github/workflows/release.yml`      | `workflow_dispatch` only (manual)                         | Calls `ci.yml` → semantic-release prod → calls `docker-build.yml`                                                                                                                                                         |
+| `.github/workflows/docker-build.yml` | `workflow_call` + `workflow_dispatch`                     | Reusable image builder: matrix split-and-merge (amd64 on `ubuntu-24.04` + arm64 on `ubuntu-24.04-arm`), SLSA v1 provenance + SBOM attestations (BuildKit + Sigstore), `gh attestation verify` regression gate, Trivy scan |
 
 - **Bun version is single-sourced** via `.tool-versions` (`bun 1.3.12`). All workflows use `oven-sh/setup-bun@v2` with `bun-version-file: .tool-versions`.
 - **`audit:ci` (`scripts/audit-ci.ts`)** wraps `bun audit --json` to gate on severity: blocks on high+critical, warns on moderate+low, with an inline `IGNORED` GHSA allowlist (each entry must carry an `expires` date). Required because `bun audit` exits 1 on **any** finding regardless of `--audit-level`.
@@ -151,6 +151,7 @@ The `docs.yml` `pull_request:` trigger has no `paths:` filter, so these gates ru
 
 ## Recent Changes
 
+- 20260502-supply-chain-attestations: `.github/workflows/docker-build.yml` now publishes SLSA v1 provenance + SBOM attestations on every release tag. The build step sets `provenance: mode=max` + `sbom: true` (overriding `docker/build-push-action`'s default of off-when-`push-by-digest=true`), so BuildKit emits per-arch attestation manifests that survive `imagetools create` via the index-digest references. The merge job additionally runs `anchore/sbom-action` + `actions/attest-build-provenance` + `actions/attest-sbom` to publish Sigstore-signed CycloneDX SBOM and SLSA provenance bound to the merged manifest digest, surfaced via the GitHub Attestations API and Docker Hub's "Build attestations" badge. The merge job carries scoped `id-token: write` + `attestations: write`; build/scan stay read-only via the new top-level `attestations: read`. The scan job calls `gh attestation verify` for both predicate types (`https://slsa.dev/provenance/v1` + `https://cyclonedx.org/bom`) before Trivy — a hard regression gate that fails the workflow if either attestation is silently dropped by a future refactor. Consumer-side `gh attestation verify` and `docker buildx imagetools inspect` recipes documented in `docs/operate/deployment.md` (Verifying image attestations) and the registry / API storage matrix is in `docs/operate/observability.md` (Supply-chain attestations). Closes #58.
 - 20260416-pipeline-redesign: CI/CD pipeline restructured for single-responsibility separation. Replaced `push.yml` + `semantic-release.yml` (which entangled lint-and-test, dev release, and docker build) with four single-purpose workflows: `ci.yml` (quality gates only), `dev-release.yml` (feature-branch orchestrator: ci → semrel-dev → docker), `release.yml` (manual prod orchestrator: ci → semrel-prod → docker), and a rewritten reusable `docker-build.yml` (matrix split-and-merge native amd64+arm64, no QEMU). Bun version single-sourced via `.tool-versions` (resolved drift between 1.3.8 in push.yml/semrel.yml and 1.3.12 in docker-build.yml/Dockerfile/package.json). `audit:ci` script (`scripts/audit-ci.ts`) wraps `bun audit --json` to restore severity-based gating (block high+critical, warn moderate+low, time-boxed GHSA allowlist) — `bun audit` itself exits 1 on any finding regardless of `--audit-level`. Single env-switched `release.config.mjs` (`SEMREL_CHANNEL=dev|prod`) replaces the file-swap hack. Prod release is now manual (`gh workflow run release.yml`); push-to-main only runs `ci.yml`. Job-spawner pod entrypoint moved from `src/k8s/job-entrypoint.ts` (TS source absent from production image) to `dist/k8s/job-entrypoint.js` (built by `scripts/build.ts`) — fixes a latent isolated-job-target bug. Defense-in-depth: every dynamic workflow input passes through `env:` before reaching any `run:` block.
 - 20260410-164348-scheduled-research-workflow: Config-only (no `src/` changes) — adds `.github/workflows/research.yml` invoking `anthropics/claude-code-action@v1` once daily (`cron: "0 5 * * *"` = 3pm AEST / 4pm AEDT) and on `workflow_dispatch` with an optional `focus_area` input. Hard 1-hour wall-clock budget (`timeout-minutes: 60`), at most one labelled GitHub issue per run, agent restricted to read + `WebSearch`/`WebFetch` + `gh issue/label create`, two repo secrets (`CLAUDE_CODE_OAUTH_TOKEN`, `PERSONAL_ACCESS_TOKEN`), `permissions: contents:read + issues:write + id-token:write`, `concurrency: research-workflow / cancel-in-progress: false`. 10 fixed focus areas mapped to `src/` subsystems. Two-label scheme (`research` + `area: <name>`). Inherits documented workarounds from `chrisleekr/personal-claw` `research.yml` (`allowed_bots: '*'`, `--disallowedTools ""`, PAT instead of OIDC). **Defense-in-depth against workflow injection**: every GitHub-context value (including `github.event.inputs.focus_area`) is passed via `env:` blocks rather than interpolated into `run:` scripts; the user-supplied `focus_area` is additionally validated against `^[a-z][a-z0-9-]{0,31}$` BEFORE being used (rejected values fall back to a random pick and log only their length, never the value itself) — satisfies Constitution Principle IV. **Failure surfacing**: relies on GitHub Actions' built-in workflow-failure email; no custom alerting. **Cost observability**: per Constitution Principle VI bullet 2, `claude-code-action`'s own per-turn cost output is captured by GitHub Actions stdout and retrieved post-mortem via `gh run view <run-id> --log | grep -iE 'cost|tokens|duration|usage'` (see `specs/.../research.md` §19 and `quickstart.md` Day-2 ops). **Test coverage gap** (Constitution Principle V) justified in `plan.md` Complexity Tracking; mitigated via `actionlint` static check + mandatory manual smoke test before merge (see `quickstart.md`).
 - 20260409-081113-project-housekeeping: Housekeeping — test coverage raised to 90% per-file threshold (lines + functions; Bun's `coverageThreshold` is applied per-file, not aggregated), ESLint migrated to unified `typescript-eslint` with `strictTypeChecked` preset, CI security scanning added (`bun audit`, `trivy` container scan with blocking `exit-code: "1"`, `gitleaks` full-history scan with `fetch-depth: 0`), Docker HEALTHCHECK on `/healthz`, gitleaks pre-commit hook, retry.ts input validation (maxAttempts/initialDelayMs/maxDelayMs/backoffFactor all reject NaN/Infinity/below-min with descriptive errors), `package.json` security overrides converted to exact version pins.