feat: sign GitHub Release files with Sigstore (#478)

PyPI attestations cover the PyPI copy only, so files downloaded from a
GitHub Release had nothing to verify against and Scorecard's
Signed-Releases check scored 0 on every generated repo. create-release
now signs each distribution and the SBOM keylessly and uploads the
.sigstore.json bundles next to them.

Author: gtauzin

template/.github/{% if include_actions %}workflows{% endif %}/publish-release.yml.jinja

@@ -123,6 +123,10 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      # Keyless Sigstore signing below exchanges this job's OIDC token for a
+      # short-lived certificate naming this workflow. Granted here rather than in
+      # `build`, which runs the project's own build hooks.
+      id-token: write
     steps:
       # Check out main (not the tag): main carries the CHANGELOG entry the merged
       # changelog PR just added, which the tag does not yet have.
@@ -174,6 +178,21 @@ jobs:
           name: {% raw %}${{ env.sbom-artifact-name }}{% endraw %}
           path: sbom/
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          # renovate: datasource=github-releases depName=astral-sh/uv
+          version: "0.13.1"
+
+      # One `<file>.sigstore.json` bundle per release file, attached to the release
+      # next to it. PyPI already carries attestations for the distributions, but a
+      # download from the GitHub Release had nothing to verify against, which is what
+      # Scorecard's Signed-Releases check reports. Verify a download with
+      # `sigstore verify github <file> --bundle <file>.sigstore.json --repository <owner>/<repo>`.
+      - name: Sign the release artifacts with Sigstore
+        # renovate: datasource=pypi depName=sigstore
+        run: uvx sigstore==4.5.0 sign dist/* sbom/sbom.cdx.json
+
       # Created as a draft: a draft release is visible to maintainers only, so nothing
       # is public until the `pypi` environment gate has been approved and the upload
       # has succeeded. `finalize-release` undrafts it. If the gate is rejected or the
@@ -198,14 +217,14 @@ jobs:
           # decision, taken only after a successful upload.
           if gh release view "$VERSION" >/dev/null 2>&1; then
             echo "Release $VERSION already exists; refreshing its notes and artifacts"
-            gh release upload "$VERSION" dist/* sbom/sbom.cdx.json --clobber
+            gh release upload "$VERSION" dist/* sbom/* --clobber
             gh release edit "$VERSION" --notes "$RELEASE_NOTES"
           else
             gh release create "$VERSION" \
               --draft \
               --title "$VERSION" \
               --notes "$RELEASE_NOTES" \
-              dist/* sbom/sbom.cdx.json
+              dist/* sbom/*
           fi
 
   pypi-publish:

template/docs/pages/explanation/security.md.jinja

@@ -14,7 +14,9 @@ audited release workflow.
 **Signed artifacts (PEP 740 attestations).** Every published distribution carries a
 cryptographic attestation, produced with Sigstore, binding the artifact to the exact
 workflow run that built it. You can verify that what you install is what this project
-actually released, not a tampered copy.
+actually released, not a tampered copy. The same holds for files downloaded from a GitHub
+Release: each one sits next to a `.sigstore.json` bundle, checked with
+`sigstore verify github <file> --bundle <file>.sigstore.json --repository {{ github_username }}/{{ project_slug }}`.
 
 **A software bill of materials (SBOM).** Each release ships a CycloneDX SBOM enumerating
 every dependency it resolves. When a vulnerability is disclosed in a transitive

tests/test_security_hardening.py

@@ -217,6 +217,33 @@ def test_publish_flow_is_self_contained_with_sbom(copie):
     assert "sbom" in publish.lower()
 
 
+def test_release_files_are_signed_with_sigstore(copie):
+    """Every GitHub Release file gets a Sigstore bundle attached next to it.
+
+    PyPI attestations cover the PyPI copy only, so a download from the GitHub Release
+    had nothing to verify against and Scorecard's Signed-Releases check scored 0 on
+    every generated repo. Signing runs in `create-release`, the job that uploads, which
+    is the one that needs `id-token: write`; `build` runs the project's own build hooks
+    and must not hold it.
+    """
+    import yaml
+
+    result = copie.copy(extra_answers={"include_actions": True})
+    publish = _read(result.project_dir, ".github/workflows/publish-release.yml")
+    jobs = yaml.safe_load(publish)["jobs"]
+
+    assert jobs["create-release"]["permissions"].get("id-token") == "write"
+    assert "id-token" not in (jobs["build"].get("permissions") or {})
+    runs = [step.get("run", "") for step in jobs["create-release"]["steps"]]
+    assert any("sigstore" in run and " sign dist/* sbom/sbom.cdx.json" in run for run in runs), (
+        "the release files are no longer signed before upload"
+    )
+    # The bundles land next to the files they sign, so both upload paths must take the
+    # whole directories rather than naming the unsigned files one by one.
+    assert publish.count("dist/* sbom/*") == 2
+    assert "sbom/sbom.cdx.json --clobber" not in publish
+
+
 def test_changelog_uses_app_token_not_pat(copie):
     """The changelog PR is opened with a short-lived GitHub App token, not a long-lived PAT."""
     result = copie.copy(extra_answers={"include_actions": True})