release: harden supply chain with CGO=0, SLSA provenance, cosign (#250)

* release: harden supply chain with CGO=0, SLSA provenance, cosign

- Pin CGO_ENABLED=0 on the build matrix so the native
  linux/amd64 binary stays statically linked. Cross-compiles
  already auto-disable CGO; the native build would otherwise
  link glibc-resolved net/os-user resolvers and break the
  manylinux_2_17 wheel and the @mdsmith/linux-x64 npm package
  on Alpine/musl and old-glibc systems.
- Generate SLSA build provenance attestations for the 5
  binaries and the .vsix via actions/attest-build-provenance.
  Verifiable with `gh attestation verify <file> -R jeduden/mdsmith`.
- Sign checksums.txt with cosign keyless (Sigstore + GitHub OIDC).
  Defeats the case where an attacker who rewrites the binary
  on the release page also rewrites checksums.txt; forging a
  matching signature would require compromising release.yml.
- Document both verification paths in docs/guides/install.md.

* release: address Copilot review on CGO comment + asset filename

- Reword the CGO_ENABLED=0 comment to describe the
  concrete portability goal (avoid glibc-resolved
  net/os/user on linux/amd64) rather than overstating
  it as full static linking, which doesn't apply on
  macOS (libSystem) or Windows (kernel32).
- Download the binary under its release-asset name
  (mdsmith-linux-amd64) so both `sha256sum -c` (which
  matches the local filename against the entry in
  checksums.txt) and `gh attestation verify` (which
  needs the attested asset name) work without
  renaming. install -m 0755 still places the binary
  on $PATH as mdsmith, leaving the source file in
  place for the cosign verify step that follows.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

.github/workflows/release.yml

@@ -36,6 +36,17 @@ jobs:
         env:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
+          # Disable cgo so the native linux/amd64 build resolves
+          # net and os/user purely in Go. Cross-compiles already
+          # auto-disable CGO; the native build would otherwise
+          # bind glibc's resolver into the binary, breaking the
+          # manylinux_2_17 wheel and the @mdsmith/linux-x64 npm
+          # package on Alpine/musl and on systems whose glibc is
+          # older than the wheel tag claims. macOS and Windows
+          # binaries still link the platform syscall layer
+          # (libSystem, kernel32) — this knob is about avoiding
+          # glibc on Linux, not achieving full static linkage.
+          CGO_ENABLED: "0"
           VERSION: ${{ github.ref_name }}
         run: |
           ext=""
@@ -278,14 +289,56 @@ jobs:
   release:
     needs: [build, vscode]
     runs-on: ubuntu-latest
+    # `id-token: write` mints the OIDC token that
+    # `actions/attest-build-provenance` and `cosign sign-blob`
+    # exchange for a short-lived Sigstore credential. No
+    # long-lived secrets. `attestations: write` is the dedicated
+    # scope the GitHub attestations API gates the
+    # provenance upload on.
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           merge-multiple: true
       - name: Create checksums
         run: sha256sum mdsmith-* > checksums.txt
+      - name: Generate SLSA build provenance
+        # Attests every binary the build matrix produced (and the
+        # .vsix the vscode job uploaded — `mdsmith-*` matches both).
+        # Each attestation ties the file's SHA-256 back to this
+        # workflow run and the commit it was built from. Consumers
+        # verify with:
+        #   gh attestation verify mdsmith-<plat> -R jeduden/mdsmith
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-path: "mdsmith-*"
+      - name: Install cosign
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+      - name: Sign checksums with cosign
+        # Keyless Sigstore signature on the checksum file. The
+        # GitHub OIDC token binds the signature to this exact
+        # workflow file at this exact tag, so an attacker who
+        # rewrites checksums.txt on the release page can't also
+        # forge a matching signature without compromising
+        # release.yml on this repo. Verify with:
+        #   cosign verify-blob \
+        #     --certificate checksums.txt.pem \
+        #     --signature checksums.txt.sig \
+        #     --certificate-identity-regexp \
+        #       "^https://github.com/jeduden/mdsmith/.github/workflows/release.yml@" \
+        #     --certificate-oidc-issuer \
+        #       https://token.actions.githubusercontent.com \
+        #     checksums.txt
+        env:
+          COSIGN_YES: "true"
+        run: |
+          cosign sign-blob \
+            --output-signature checksums.txt.sig \
+            --output-certificate checksums.txt.pem \
+            checksums.txt
       - name: Create release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -295,6 +348,8 @@ jobs:
           files: |
             mdsmith-*
             checksums.txt
+            checksums.txt.sig
+            checksums.txt.pem
 
   smoke-test:
     # Wait until every channel is on the new version before checking

docs/guides/install.md

@@ -130,12 +130,49 @@ move the binary onto `$PATH`:
 
 ```bash
 base="https://github.com/jeduden/mdsmith/releases/latest/download"
-curl -L -o mdsmith       "$base/mdsmith-linux-amd64"
-curl -L -o checksums.txt "$base/checksums.txt"
+curl -L -o mdsmith-linux-amd64 "$base/mdsmith-linux-amd64"
+curl -L -o checksums.txt       "$base/checksums.txt"
 sha256sum -c <(grep mdsmith-linux-amd64 checksums.txt)
-install -m 0755 mdsmith /usr/local/bin/mdsmith
+install -m 0755 mdsmith-linux-amd64 /usr/local/bin/mdsmith
 ```
 
+Keep the binary saved under its release-asset name
+(`mdsmith-linux-amd64`) until verification is done —
+both `sha256sum -c` and `gh attestation verify` below
+match local files against that exact name. `install`
+copies the file rather than moving it, so the original
+remains for the verification steps.
+
+For supply-chain-sensitive deployments, the release
+also ships a SLSA build provenance attestation per
+binary and a Sigstore signature on `checksums.txt`.
+Verify the provenance with `gh`:
+
+```bash
+gh attestation verify mdsmith-linux-amd64 \
+  -R jeduden/mdsmith
+```
+
+Verify the checksums-file signature with `cosign`:
+
+```bash
+curl -L -o checksums.txt.sig "$base/checksums.txt.sig"
+curl -L -o checksums.txt.pem "$base/checksums.txt.pem"
+cosign verify-blob \
+  --certificate checksums.txt.pem \
+  --signature   checksums.txt.sig \
+  --certificate-identity-regexp \
+    "^https://github.com/jeduden/mdsmith/.github/workflows/release.yml@" \
+  --certificate-oidc-issuer \
+    https://token.actions.githubusercontent.com \
+  checksums.txt
+```
+
+Both verifications resolve through the workflow's
+GitHub OIDC identity, so a forged binary or rewritten
+checksums file fails verification unless the attacker
+also controls `release.yml` on `jeduden/mdsmith`.
+
 This path is also the documented fallback if any of
 the package channels above is unavailable on a given
 day.