Add SLSA source provenance workflow and VSA integration

New source-provenance.yml workflow runs on push to main, creates a
deterministic git archive, and attests it with SLSA build provenance.

Author: claude

.github/workflows/build.yml

@@ -105,6 +105,25 @@ jobs:
           restore-keys: |
             ${{ github.job }}-${{ matrix.platform }}-${{ github.ref_name }}-
 
+      - name: Download canonical source archive
+        id: download-source
+        if: github.event_name != 'pull_request'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v5
+        with:
+          name: source-archive
+      - name: Verify source provenance
+        id: verify-source
+        if: steps.download-source.outcome == 'success'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh attestation verify source.tar.gz \
+            --repo "${{ github.repository }}" \
+            --predicate-type https://slsa.dev/provenance/v1 \
+            --cert-identity-regex "^https://github\.com/${{ github.repository }}/\.github/workflows/source-provenance\.yml@refs/(heads/main|tags/[0-9]+\.[0-9]+\.[0-9]+)$" \
+            --cert-oidc-issuer https://token.actions.githubusercontent.com
+
       - name: Create sbom, binary & package
         env:
           CCACHE_BASEDIR: ${{ github.workspace }}
@@ -175,6 +194,35 @@ jobs:
               --cert-identity "https://github.com/${{ github.repository }}/.github/workflows/build.yml@${{ github.ref }}" \
               --cert-oidc-issuer https://token.actions.githubusercontent.com
           done
+      - name: Generate VSA predicate
+        if: steps.verify-source.outcome == 'success'
+        shell: bash
+        run: |
+          jq -n \
+            --arg verifier "https://github.com/${{ github.repository }}/.github/workflows/build.yml@${{ github.ref }}" \
+            --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --arg resource "pkg:github/${{ github.repository }}@${{ github.sha }}" \
+            --arg policy "https://github.com/${{ github.repository }}/.github/workflows/source-provenance.yml@refs/heads/main" \
+            '{
+              verifier: { id: $verifier },
+              timeVerified: $time,
+              resourceUri: $resource,
+              policy: { uri: $policy },
+              inputAttestations: [],
+              verificationResult: "PASSED",
+              verifiedLevels: ["SLSA_SOURCE_LEVEL_3"]
+            }' > vsa-predicate.json
+      - name: Attest build artifacts with VSA
+        if: steps.verify-source.outcome == 'success'
+        uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0
+        with:
+          subject-path: |
+            build/dfetch-package/*.deb
+            build/dfetch-package/*.rpm
+            build/dfetch-package/*.pkg
+            build/dfetch-package/*.msi
+          predicate-type: 'https://slsa.dev/verification_summary/v1'
+          predicate-path: vsa-predicate.json
       - name: Store the distribution packages
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

.github/workflows/ci.yml

@@ -22,8 +22,17 @@ jobs:
       contents: write
       security-events: write
 
+  source-provenance:
+    if: github.event_name != 'pull_request'
+    uses: ./.github/workflows/source-provenance.yml
+    permissions:
+      contents: read
+      attestations: write
+      id-token: write
+
   build:
-    needs: prep-release
+    needs: [prep-release, source-provenance]
+    if: needs.prep-release.result != 'failure' && needs.source-provenance.result != 'failure'
     uses: ./.github/workflows/build.yml
     permissions:
       contents: write

.github/workflows/source-provenance.yml

@@ -0,0 +1,62 @@
+name: Source Provenance
+
+on:
+  push:
+    branches: ["main"]
+    tags: ['[0-9]*.[0-9]*.[0-9]*']
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  attest-source:
+    name: Generate source provenance
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      attestations: write
+      id-token: write
+
+    steps:
+      - name: "Harden the runner (Block egress traffic: Only allow calls to allowed endpoints)"
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: block
+          allowed-endpoints: >+
+            github.com:443
+            api.github.com:443
+            uploads.github.com:443
+            fulcio.sigstore.dev:443
+            rekor.sigstore.dev:443
+            tuf-repo-cdn.sigstore.dev:443
+            *.blob.core.windows.net:443
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Generate source archive
+        run: git archive HEAD --format=tar.gz -o source.tar.gz
+
+      - name: Attest source provenance
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-path: source.tar.gz
+
+      - name: Verify source provenance
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh attestation verify source.tar.gz \
+            --repo "${{ github.repository }}" \
+            --predicate-type https://slsa.dev/provenance/v1 \
+            --cert-identity-regex "^https://github\.com/${{ github.repository }}/\.github/workflows/source-provenance\.yml@refs/(heads/main|tags/[0-9]+\.[0-9]+\.[0-9]+)$" \
+            --cert-oidc-issuer https://token.actions.githubusercontent.com
+
+      - name: Upload source archive
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: source-archive
+          path: source.tar.gz

doc/tutorials/installation.rst

@@ -100,8 +100,13 @@ complementary kinds:
   workflow, and records the exact inputs used at build time.
 - **SBOM attestation** (CycloneDX) — answers *"what is inside it?"*: lists every
   dependency bundled in the package so you can audit its composition.
+- **Verification Summary Attestation (VSA)** — answers *"was the source
+  independently verified?"*: records that the source archive for this commit was
+  attested and verified before the binary was produced, linking source-level
+  trust to the binary package.
 
-Binary installers carry **both** kinds of attestation (signed by ``build.yml``).
+Binary installers carry **all three** kinds of attestation when source
+provenance verification passes (signed by ``build.yml``).
 Python packages installed from PyPI carry an **SBOM attestation only** (signed by
 ``python-publish.yml``).
 
@@ -132,6 +137,16 @@ To verify, use the `GitHub CLI <https://cli.github.com/>`_. Pass
                 --cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
                 --cert-oidc-issuer https://token.actions.githubusercontent.com
 
+        **Binary installer — verify source provenance summary (VSA):**
+
+        .. code-block:: bash
+
+            $ gh attestation verify dfetch-<version>-nix.deb \
+                --repo dfetch-org/dfetch \
+                --predicate-type https://slsa.dev/verification_summary/v1 \
+                --cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
+                --cert-oidc-issuer https://token.actions.githubusercontent.com
+
         **pip / PyPI wheel — verify SBOM attestation:**
 
         .. code-block:: bash
@@ -164,6 +179,16 @@ To verify, use the `GitHub CLI <https://cli.github.com/>`_. Pass
                 --cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
                 --cert-oidc-issuer https://token.actions.githubusercontent.com
 
+        **Binary installer — verify source provenance summary (VSA):**
+
+        .. code-block:: bash
+
+            $ gh attestation verify dfetch-<version>-osx.pkg \
+                --repo dfetch-org/dfetch \
+                --predicate-type https://slsa.dev/verification_summary/v1 \
+                --cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
+                --cert-oidc-issuer https://token.actions.githubusercontent.com
+
         **pip / PyPI wheel — verify SBOM attestation:**
 
         .. code-block:: bash
@@ -196,6 +221,16 @@ To verify, use the `GitHub CLI <https://cli.github.com/>`_. Pass
                 --cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> `
                 --cert-oidc-issuer https://token.actions.githubusercontent.com
 
+        **Binary installer — verify source provenance summary (VSA):**
+
+        .. code-block:: powershell
+
+            > gh attestation verify dfetch-<version>-win.msi `
+                --repo dfetch-org/dfetch `
+                --predicate-type https://slsa.dev/verification_summary/v1 `
+                --cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> `
+                --cert-oidc-issuer https://token.actions.githubusercontent.com
+
         **pip / PyPI wheel — verify SBOM attestation:**
 
         .. code-block:: powershell
@@ -208,6 +243,12 @@ To verify, use the `GitHub CLI <https://cli.github.com/>`_. Pass
 
 See `GitHub artifact attestations`_ for details.
 
+.. note::
+
+   The VSA is present on releases built from a commit whose source provenance
+   was verified.  If the ``verification_summary`` attestation is absent for a
+   release, fall back to checking build provenance and SBOM independently.
+
 .. note::
 
    ``--cert-oidc-issuer https://token.actions.githubusercontent.com`` pins