@codapult/guard 0.10.0 → 0.11.0

package/docs/guard-trusted-pr-attestation.yml

@@ -0,0 +1,213 @@
+name: Guard Trusted PR Attestation
+
+on:
+  workflow_run:
+    workflows: [Guard]
+    types: [completed]
+
+permissions: {}
+
+jobs:
+  inspect:
+    if: github.event.workflow_run.event == 'pull_request'
+    runs-on: ubuntu-latest
+    outputs:
+      number: ${{ steps.pr.outputs.number }}
+      head_sha: ${{ steps.pr.outputs.head_sha }}
+      base_sha: ${{ steps.pr.outputs.base_sha }}
+      fork: ${{ steps.pr.outputs.fork }}
+    steps:
+      - name: Read the associated pull request context
+        id: pr
+        env:
+          EVENT_PATH: ${{ github.event_path }}
+        run: |
+          node --input-type=module <<'NODE'
+          import { appendFileSync, readFileSync } from 'node:fs';
+          const event = JSON.parse(readFileSync(process.env.EVENT_PATH, 'utf8'));
+          const pullRequests = event.workflow_run?.pull_requests ?? [];
+          const isRepository = (value) => typeof value === 'string' && /^[^/\s]+\/[^/\s]+$/.test(value);
+          if (pullRequests.length === 0) {
+            const runHeadRepository = event.workflow_run?.head_repository?.full_name;
+            const eventBaseRepository = event.repository?.full_name;
+            if (!isRepository(runHeadRepository) || !isRepository(eventBaseRepository) || runHeadRepository.toLowerCase() === eventBaseRepository.toLowerCase()) {
+              throw new Error('Expected exactly one associated pull request; could not safely identify an unattached fork run.');
+            }
+            appendFileSync(process.env.GITHUB_OUTPUT, 'fork=true\n');
+          } else {
+            if (pullRequests.length !== 1) throw new Error('Expected exactly one associated pull request.');
+            const pullRequest = pullRequests[0];
+            const number = pullRequest.number;
+            const headSha = pullRequest.head?.sha;
+            const baseSha = pullRequest.base?.sha;
+            const headRepository = pullRequest.head?.repo?.full_name;
+            const baseRepository = pullRequest.base?.repo?.full_name;
+            if (!Number.isSafeInteger(number) || number < 1 || !/^[a-f0-9]{40}$/i.test(headSha ?? '') || !/^[a-f0-9]{40}$/i.test(baseSha ?? '') || !isRepository(headRepository) || !isRepository(baseRepository)) {
+              throw new Error('Pull request number, repository, head SHA, or base SHA is missing or invalid.');
+            }
+            const fork = headRepository.toLowerCase() !== baseRepository.toLowerCase();
+            appendFileSync(process.env.GITHUB_OUTPUT, `number=${number}\nhead_sha=${headSha}\nbase_sha=${baseSha}\nfork=${fork}\n`);
+          }
+          NODE
+
+  verify:
+    needs: inspect
+    if: needs.inspect.result == 'success' && needs.inspect.outputs.fork != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      attestation: ${{ steps.result.outputs.attestation }}
+    steps:
+      - name: Check out the PR head from the base repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/pull/${{ needs.inspect.outputs.number }}/head
+          fetch-depth: 0
+
+      - name: Fetch the exact base commit and verify the checkout
+        env:
+          BASE_SHA: ${{ needs.inspect.outputs.base_sha }}
+          HEAD_SHA: ${{ needs.inspect.outputs.head_sha }}
+        run: |
+          git fetch --no-tags origin "$BASE_SHA"
+          actual_head=$(git rev-parse HEAD)
+          if [ "$actual_head" != "$HEAD_SHA" ]; then
+            echo "Checked out $actual_head, expected PR head $HEAD_SHA" >&2
+            exit 1
+          fi
+
+      - name: Set up Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+
+      - name: Fetch the pinned Guard source revision
+        working-directory: ${{ runner.temp }}
+        env:
+          GUARD_VERSION: ${{ vars.CODAPULT_GUARD_VERSION }}
+          GUARD_COMMIT: ${{ vars.CODAPULT_GUARD_COMMIT }}
+        run: |
+          if ! [[ "$GUARD_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+            echo "Set CODAPULT_GUARD_VERSION to an exact Guard release version." >&2
+            exit 1
+          fi
+          if ! [[ "$GUARD_COMMIT" =~ ^[a-f0-9]{40}$ ]]; then
+            echo "Set CODAPULT_GUARD_COMMIT to the full 40-character commit SHA for that Guard release tag." >&2
+            exit 1
+          fi
+          git init codapult-guard-source
+          git -C codapult-guard-source remote add origin https://github.com/codapult/codapult-guard.git
+          git -C codapult-guard-source fetch --depth=1 origin "refs/tags/v$GUARD_VERSION:refs/tags/guard-release"
+          fetched_commit=$(git -C codapult-guard-source rev-parse 'refs/tags/guard-release^{commit}')
+          if [ "$fetched_commit" != "$GUARD_COMMIT" ]; then
+            echo "Guard release tag resolved to $fetched_commit, expected $GUARD_COMMIT." >&2
+            exit 1
+          fi
+          git -C codapult-guard-source checkout --detach "$GUARD_COMMIT"
+          if [ "$(node -p "require('./codapult-guard-source/package.json').version")" != "$GUARD_VERSION" ]; then
+            echo "Guard source package version does not match CODAPULT_GUARD_VERSION." >&2
+            exit 1
+          fi
+
+      - name: Build pinned Guard with its frozen dependency graph
+        working-directory: ${{ runner.temp }}/codapult-guard-source
+        run: |
+          corepack enable
+          corepack pnpm install --frozen-lockfile --ignore-scripts
+          corepack pnpm --filter @codapult/guard build
+
+      - name: Verify PR with trusted Guard and base policy
+        env:
+          BASE_SHA: ${{ needs.inspect.outputs.base_sha }}
+          GUARD_RESULT_FILE: ${{ runner.temp }}/guard-verification.json
+          GUARD_STATEMENT_FILE: ${{ runner.temp }}/guard-verification.intoto.json
+        run: |
+          node "$RUNNER_TEMP/codapult-guard-source/dist/cli/index.js" verify \
+            --no-project-checks \
+            --tools off \
+            --policy-base "$BASE_SHA" \
+            --fail-on-policy-change \
+            --fail-on-protected-changes \
+            --json \
+            --attestation-out "$GUARD_STATEMENT_FILE" \
+            > "$GUARD_RESULT_FILE"
+
+      - name: Confirm the receipt matches this PR
+        id: result
+        env:
+          BASE_SHA: ${{ needs.inspect.outputs.base_sha }}
+          HEAD_SHA: ${{ needs.inspect.outputs.head_sha }}
+          GUARD_RESULT_FILE: ${{ runner.temp }}/guard-verification.json
+          GUARD_STATEMENT_FILE: ${{ runner.temp }}/guard-verification.intoto.json
+        run: |
+          node --input-type=module <<'NODE'
+          import { appendFileSync, readFileSync } from 'node:fs';
+          const result = JSON.parse(readFileSync(process.env.GUARD_RESULT_FILE, 'utf8'));
+          const statement = JSON.parse(readFileSync(process.env.GUARD_STATEMENT_FILE, 'utf8'));
+          const receipt = result.run?.receipt;
+          const scope = receipt?.verificationScope;
+          const statementReceipt = statement?.predicate?.receipt;
+          if (result.outcome !== 'pass' || receipt?.outcome !== 'pass') throw new Error('Guard did not pass.');
+          if (receipt.version !== 1 || receipt.kind !== 'verification-receipt' || typeof receipt.runId !== 'string' || receipt.runId.length === 0) {
+            throw new Error('Guard receipt has an unsupported schema or no run ID.');
+          }
+          if (receipt.subject?.headSha !== process.env.HEAD_SHA || receipt.subject?.baseSha !== process.env.BASE_SHA) {
+            throw new Error('Guard receipt does not match the triggering PR head and base SHAs.');
+          }
+          if (scope?.algorithm !== 'sha256' || scope.complete !== true || scope.stable !== true || !/^[a-f0-9]{64}$/.test(scope.fingerprint ?? '')) {
+            throw new Error('Guard receipt has no complete, stable verification scope.');
+          }
+          if (statement?._type !== 'https://in-toto.io/Statement/v1' || statement.predicateType !== 'https://codapult.dev/attestations/guard-verification/v1') {
+            throw new Error('in-toto statement or Guard predicate type is invalid.');
+          }
+          if (!Array.isArray(statement.subject) || statement.subject.length !== 1 || statement.subject[0]?.name !== 'codapult-guard:verification-context' || statement.subject[0]?.digest?.sha256 !== scope.fingerprint) {
+            throw new Error('in-toto statement subject does not match the verified scope.');
+          }
+          if (JSON.stringify(statementReceipt) !== JSON.stringify(receipt)) {
+            throw new Error('in-toto statement does not match the verified receipt and scope.');
+          }
+          appendFileSync(process.env.GITHUB_OUTPUT, 'attestation=true\n');
+          NODE
+
+      - name: Upload the independently verified statement
+        if: steps.result.outcome == 'success'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: guard-trusted-pr-attestation
+          path: ${{ runner.temp }}/guard-verification.intoto.json
+          if-no-files-found: error
+
+  fork-pr-summary:
+    needs: inspect
+    if: needs.inspect.result == 'success' && needs.inspect.outputs.fork == 'true'
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Explain why this fork PR has no attestation
+        run: |
+          cat >> "$GITHUB_STEP_SUMMARY" <<'SUMMARY'
+          ## Guard attestation skipped
+
+          This pull request comes from a fork. The trusted workflow did not check out or inspect fork-controlled code, and it did not create a signed attestation. Checkout's fork protection remains enabled. The ordinary Guard pull request check still reports its own result.
+          SUMMARY
+
+  attest:
+    needs: [inspect, verify]
+    if: needs.inspect.result == 'success' && needs.inspect.outputs.fork != 'true' && needs.verify.result == 'success' && needs.verify.outputs.attestation == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+      artifact-metadata: write
+    steps:
+      - name: Download the trusted verifier output
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: guard-trusted-pr-attestation
+
+      - name: Sign the in-toto statement file
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-path: guard-verification.intoto.json