feat(ci): add release sbom and provenance

  attestations

Author: alexandreteles

.github/workflows/release.yml

@@ -31,6 +31,13 @@ jobs:
         run: uv run --python 3.14 mkdocs build --strict
       - name: Build package
         run: uv build
+      - name: Download Syft
+        id: syft
+        uses: anchore/sbom-action/download-syft@v0
+      - name: Generate release integrity artifacts
+        env:
+          SYFT: ${{ steps.syft.outputs.cmd }}
+        run: bash scripts/generate-release-integrity-artifacts.sh dist .release-integrity.env
       - name: Coveralls
         if: github.event_name == 'push'
         env:
@@ -122,6 +129,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      attestations: write
+      id-token: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -135,6 +144,51 @@ jobs:
         run: uv sync --python 3.14
       - name: Build package
         run: uv build
+      - name: Download Syft
+        id: syft
+        uses: anchore/sbom-action/download-syft@v0
+      - name: Generate release integrity artifacts
+        env:
+          SYFT: ${{ steps.syft.outputs.cmd }}
+        run: bash scripts/generate-release-integrity-artifacts.sh dist .release-integrity.env
+      - name: Load release integrity metadata
+        id: integrity
+        run: |
+          source .release-integrity.env
+          {
+            printf 'wheel=%s\n' "$wheel"
+            printf 'wheel_name=%s\n' "$wheel_name"
+            printf 'wheel_sbom=%s\n' "$wheel_sbom"
+            printf 'wheel_sbom_name=%s\n' "$wheel_sbom_name"
+            printf 'sdist=%s\n' "$sdist"
+            printf 'sdist_name=%s\n' "$sdist_name"
+            printf 'sdist_sbom=%s\n' "$sdist_sbom"
+            printf 'sdist_sbom_name=%s\n' "$sdist_sbom_name"
+            printf 'checksums=%s\n' "$checksums"
+            printf 'checksums_name=%s\n' "$checksums_name"
+          } >> "$GITHUB_OUTPUT"
+      - name: Attest build provenance
+        id: attest-provenance
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-path: |
+            ${{ steps.integrity.outputs.wheel }}
+            ${{ steps.integrity.outputs.sdist }}
+          show-summary: false
+      - name: Attest wheel SBOM
+        id: attest-wheel-sbom
+        uses: actions/attest-sbom@v3
+        with:
+          subject-path: ${{ steps.integrity.outputs.wheel }}
+          sbom-path: ${{ steps.integrity.outputs.wheel_sbom }}
+          show-summary: false
+      - name: Attest source distribution SBOM
+        id: attest-sdist-sbom
+        uses: actions/attest-sbom@v3
+        with:
+          subject-path: ${{ steps.integrity.outputs.sdist }}
+          sbom-path: ${{ steps.integrity.outputs.sdist_sbom }}
+          show-summary: false
       - name: Upload workflow artifact
         uses: actions/upload-artifact@v4
         with:
@@ -144,6 +198,77 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh release upload "${{ needs.release.outputs.tag }}" dist/* --clobber
+      - name: Publish verification summary
+        env:
+          RELEASE_TAG: ${{ needs.release.outputs.tag }}
+          RELEASE_COMMIT_SHA: ${{ needs.release.outputs.commit_sha }}
+          PROVENANCE_URL: ${{ steps.attest-provenance.outputs.attestation-url }}
+          WHEEL_SBOM_URL: ${{ steps.attest-wheel-sbom.outputs.attestation-url }}
+          SDIST_SBOM_URL: ${{ steps.attest-sdist-sbom.outputs.attestation-url }}
+        run: |
+          source .release-integrity.env
+          wheel_sha="$(awk -v file="$wheel_name" '$2 == file { print $1 }' "$checksums")"
+          sdist_sha="$(awk -v file="$sdist_name" '$2 == file { print $1 }' "$checksums")"
+
+          cat > dist/release-verification.md <<EOF
+          <!-- release-verification:start -->
+          ## Verification
+
+          Release commit: \`$RELEASE_COMMIT_SHA\`
+
+          | Artifact | SHA256 | SPDX SBOM | Provenance | SBOM attestation |
+          | --- | --- | --- | --- | --- |
+          | \`$wheel_name\` | \`$wheel_sha\` | \`$wheel_sbom_name\` | [build provenance]($PROVENANCE_URL) | [SBOM attestation]($WHEEL_SBOM_URL) |
+          | \`$sdist_name\` | \`$sdist_sha\` | \`$sdist_sbom_name\` | [build provenance]($PROVENANCE_URL) | [SBOM attestation]($SDIST_SBOM_URL) |
+
+          Release assets also include \`$checksums_name\`, \`$wheel_sbom_name\`, and \`$sdist_sbom_name\`.
+
+          \`\`\`bash
+          gh release verify "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY"
+          gh release verify-asset "$RELEASE_TAG" "./$wheel_name" --repo "$GITHUB_REPOSITORY"
+          gh release verify-asset "$RELEASE_TAG" "./$sdist_name" --repo "$GITHUB_REPOSITORY"
+          gh attestation verify "./$wheel_name" --repo "$GITHUB_REPOSITORY" --signer-workflow .github/workflows/release.yml
+          gh attestation verify "./$wheel_name" --repo "$GITHUB_REPOSITORY" --signer-workflow .github/workflows/release.yml --predicate-type https://spdx.dev/Document/v2.3
+          \`\`\`
+
+          Install from Git with an immutable ref, not \`master\`. Example:
+
+          \`\`\`bash
+          pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@$RELEASE_TAG"
+          \`\`\`
+
+          \`pip\` and \`uv\` record VCS origin metadata in \`direct_url.json\`, but mutable branch installs cannot be strongly verified after the fact. Prefer a signed tag or commit hash and verify the matching release artifacts.
+          <!-- release-verification:end -->
+          EOF
+
+          cat dist/release-verification.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Update release notes with verification details
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ needs.release.outputs.tag }}
+        run: |
+          gh release view "$RELEASE_TAG" --json body --jq .body > dist/release-body.md
+          python - <<'PY'
+          from pathlib import Path
+
+          start_marker = "<!-- release-verification:start -->"
+          end_marker = "<!-- release-verification:end -->"
+          body_path = Path("dist/release-body.md")
+          section = Path("dist/release-verification.md").read_text(encoding="utf-8").strip()
+          body = body_path.read_text(encoding="utf-8").strip()
+
+          if start_marker in body and end_marker in body:
+            prefix, remainder = body.split(start_marker, 1)
+            _, suffix = remainder.split(end_marker, 1)
+            body = prefix.rstrip()
+            suffix = suffix.lstrip()
+            merged = "\n\n".join(part for part in [body, section, suffix] if part)
+          else:
+            merged = "\n\n".join(part for part in [body, section] if part)
+
+          body_path.write_text(f"{merged}\n", encoding="utf-8")
+          PY
+          gh release edit "$RELEASE_TAG" --notes-file dist/release-body.md
 
   build-release-docs:
     if: needs.release.outputs.released == 'true'

README.md

@@ -69,5 +69,32 @@ latest docs to GitHub Pages.
 The first automated release should start from a bootstrap tag that matches the
 current project version.
 
+## Supply Chain Security
+Each automated release publishes the wheel, source distribution, `SHA256SUMS`,
+and SPDX JSON SBOM files as GitHub Release assets and workflow artifacts. The
+release workflow also creates keyless GitHub artifact attestations for both
+build provenance and SPDX SBOMs.
+
+To verify a release locally with the GitHub CLI:
+
+```bash
+gh release verify vX.Y.Z --repo Raze-Systems/fastapi-paseto
+gh release verify-asset vX.Y.Z ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto
+gh attestation verify ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto --signer-workflow .github/workflows/release.yml
+gh attestation verify ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto --signer-workflow .github/workflows/release.yml --predicate-type https://spdx.dev/Document/v2.3
+```
+
+If you install directly from Git, pin an immutable tag or commit hash instead
+of `master`:
+
+```bash
+pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@vX.Y.Z"
+```
+
+`pip` and `uv` record VCS origin metadata in `direct_url.json`, which helps
+with auditing later, but mutable branch installs cannot be strongly verified
+after the fact. Use a signed commit or tag plus the matching release assets if
+you need a verifiable supply-chain trail.
+
 ## License
 This project is licensed under the terms of the MIT license.

docs/contributing.md

@@ -105,17 +105,19 @@ The release workflow only publishes when validation succeeds:
 - tests must pass
 - `uv build` must pass
 - `uv run --python 3.14 mkdocs build --strict` must pass
+- release SBOM generation must pass
 
 The workflow updates `pyproject.toml`, stamps the package fallback version in
 `src/fastapi_paseto/_version.py`, regenerates `CHANGELOG.md`, creates the Git
-tag and GitHub release, uploads the distributions with Twine, and deploys the
-latest documentation to GitHub Pages.
+tag and GitHub release, uploads the distributions with `SHA256SUMS` and SPDX
+SBOM files, creates GitHub artifact attestations for build provenance and SBOM
+verification, and deploys the latest documentation to GitHub Pages.
 
-This repository currently has release tags through `v0.5.4`, while the project
-metadata is already at `0.6.0`. Before relying on the automated release job,
-create and push a bootstrap tag that matches the current version:
+If release automation is being enabled for the first time on a repository with
+existing versions, create and push a bootstrap tag that matches the current
+version before relying on automated semantic version bumps:
 
 ```bash
-git tag v0.6.0
-git push origin v0.6.0
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```

docs/supply-chain-security.md

@@ -0,0 +1,66 @@
+# Supply Chain Security
+
+FastAPI PASETO release artifacts are built in GitHub Actions and published as
+GitHub Release assets. Each release includes:
+
+- the wheel
+- the source distribution
+- `SHA256SUMS`
+- one SPDX JSON SBOM for the wheel
+- one SPDX JSON SBOM for the source distribution
+- GitHub artifact attestations for build provenance
+- GitHub artifact attestations for the SPDX SBOM predicates
+
+The release job writes the same verification details into the workflow summary
+and the GitHub Release description so consumers can verify what they downloaded
+without reading the workflow source first.
+
+## Verifying a release
+
+Install the <a href="https://cli.github.com/" target="_blank">GitHub CLI</a>,
+download the release asset you want to inspect, and run:
+
+```bash
+gh release verify vX.Y.Z --repo Raze-Systems/fastapi-paseto
+gh release verify-asset vX.Y.Z ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto
+gh attestation verify ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto --signer-workflow .github/workflows/release.yml
+gh attestation verify ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto --signer-workflow .github/workflows/release.yml --predicate-type https://spdx.dev/Document/v2.3
+```
+
+Swap the wheel path for the source distribution if you prefer to verify the
+sdist instead.
+
+## Installing from the repository
+
+Most supply-chain guarantees depend on immutable inputs. For Git installs, that
+means you should install from a tag or a commit hash:
+
+```bash
+pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@vX.Y.Z"
+pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@<commit-sha>"
+```
+
+Avoid installs from `master`. A mutable branch reference can change after you
+install it, which makes later verification weak even if the branch tip was
+signed at the time.
+
+Python installers record VCS origin metadata in `direct_url.json` as described
+by PEP 610. That metadata helps downstream auditing tools understand where the
+package came from, but it does not replace artifact verification. The strongest
+path is:
+
+1. Pin a tag or commit hash.
+2. Verify that ref in GitHub.
+3. Verify the matching release asset, provenance attestation, and SPDX SBOM.
+
+## Trust model
+
+This repository uses GitHub's keyless OIDC signing flow for attestations. The
+trust decision is therefore based on:
+
+- the repository identity
+- the release workflow identity
+- the artifact digest you downloaded
+
+No long-lived signing key is required for release assets, which reduces manual
+key management overhead for maintainers.

mkdocs.yml

@@ -43,13 +43,14 @@ nav:
     - Token Purpose: advanced-usage/purpose.md
     - Bigger Applications: advanced-usage/bigger-app.md
     - Generate Documentation: advanced-usage/generate-docs.md
-  - Configuration Options:
-    - General Options: configuration/general.md
-    - Headers Options: configuration/headers.md
-    - Denylist Options: configuration/denylist.md
-  - API Documentation: api-doc.md
-  - Development - Contributing: contributing.md
-  - Release Notes: release-notes.md
+  - Configuration Options:
+    - General Options: configuration/general.md
+    - Headers Options: configuration/headers.md
+    - Denylist Options: configuration/denylist.md
+  - API Documentation: api-doc.md
+  - Supply Chain Security: supply-chain-security.md
+  - Development - Contributing: contributing.md
+  - Release Notes: release-notes.md
 
 extra_css:
   - 'css/custom.css'

scripts/generate-release-integrity-artifacts.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+dist_dir="${1:-dist}"
+metadata_path="${2:-$dist_dir/release-integrity.env}"
+syft_cmd="${SYFT:-syft}"
+python_cmd="${PYTHON:-python3}"
+
+if [[ ! -d "$dist_dir" ]]; then
+  printf 'Distribution directory not found: %s\n' "$dist_dir" >&2
+  exit 1
+fi
+
+mapfile -t package_info < <("$python_cmd" - <<'PY'
+from pathlib import Path
+import tomllib
+
+pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+distribution = pyproject["project"]["name"].replace("-", "_")
+version = pyproject["project"]["version"]
+print(distribution)
+print(version)
+PY
+)
+
+distribution_name="${package_info[0]}"
+version="${package_info[1]}"
+
+mapfile -t wheels < <(find "$dist_dir" -maxdepth 1 -type f -name "${distribution_name}-${version}-*.whl" | LC_ALL=C sort)
+mapfile -t sdists < <(find "$dist_dir" -maxdepth 1 -type f -name "${distribution_name}-${version}.tar.gz" | LC_ALL=C sort)
+
+if [[ ${#wheels[@]} -ne 1 ]]; then
+  printf 'Expected exactly one wheel in %s, found %s\n' "$dist_dir" "${#wheels[@]}" >&2
+  exit 1
+fi
+
+if [[ ${#sdists[@]} -ne 1 ]]; then
+  printf 'Expected exactly one source distribution in %s, found %s\n' "$dist_dir" "${#sdists[@]}" >&2
+  exit 1
+fi
+
+wheel="${wheels[0]}"
+sdist="${sdists[0]}"
+checksums_path="$dist_dir/SHA256SUMS"
+wheel_sbom="$dist_dir/$(basename "$wheel").spdx.json"
+sdist_sbom="$dist_dir/$(basename "$sdist").spdx.json"
+
+(cd "$dist_dir" && sha256sum "$(basename "$wheel")" "$(basename "$sdist")") > "$checksums_path"
+"$syft_cmd" "$wheel" -o "spdx-json=$wheel_sbom"
+"$syft_cmd" "$sdist" -o "spdx-json=$sdist_sbom"
+
+cat > "$metadata_path" <<EOF
+wheel=$wheel
+wheel_name=$(basename "$wheel")
+wheel_sbom=$wheel_sbom
+wheel_sbom_name=$(basename "$wheel_sbom")
+sdist=$sdist
+sdist_name=$(basename "$sdist")
+sdist_sbom=$sdist_sbom
+sdist_sbom_name=$(basename "$sdist_sbom")
+checksums=$checksums_path
+checksums_name=$(basename "$checksums_path")
+EOF