feat(ci): add cdk diff job before deploy approval gate (B2 compensating control)

Adds a `diff` job that runs immediately after resolve-targets (no
environment gate). It downloads the same CDK artifact, assumes AWS
credentials, and runs `cdk diff` — surfacing all CloudFormation
changes in the GitHub step summary. The reviewer can inspect the
diff before clicking "Approve" on the deploy environment gate.

The deploy job now `needs: [resolve-targets, diff]` ensuring the
diff completes before approval is requested. `--require-approval never`
is retained on the deploy step because CDK hard-fails without TTY
in CI; the GitHub environment approval gate is the human checkpoint.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: scottschreckengaust

.github/workflows/deploy.yml

@@ -122,10 +122,85 @@ jobs:
               ;;
           esac
 
-  deploy:
+  # Surfaces CloudFormation changes in the step summary BEFORE the deploy
+  # approval gate. Uses a read-only IAM role (no deploy/mutate permissions).
+  # Configure the 'diff' environment with no required reviewers so it auto-runs;
+  # gate it later if read-access to stack templates needs approval.
+  diff:
     needs: resolve-targets
     if: needs.resolve-targets.outputs.has_targets == 'true'
     runs-on: ubuntu-latest
+    environment: diff
+    strategy:
+      matrix:
+        compute_type: ${{ fromJson(needs.resolve-targets.outputs.matrix) }}
+    permissions:
+      id-token: write
+      contents: read
+      actions: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Download CDK artifact (${{ matrix.compute_type }})
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: cdk-${{ matrix.compute_type }}-out
+          path: cdk/
+          run-id: ${{ needs.resolve-targets.outputs.run_id }}
+          github-token: ${{ github.token }}
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4.3.1
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
+          aws-region: ${{ vars.AWS_REGION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.x
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: CDK Diff (full)
+        env:
+          COMPUTE_TYPE: ${{ matrix.compute_type }}
+        run: |
+          # --method=template: read-only comparison against deployed template;
+          # no change-set creation, no S3 asset publishing, no deploy role needed.
+          npx cdk diff --app cdk/cdk.out --all --method=template --no-color 2>&1 | tee cdk-diff-full.txt || true
+
+      - name: CDK Diff (security only)
+        env:
+          COMPUTE_TYPE: ${{ matrix.compute_type }}
+        run: |
+          echo "## Security Changes (\`$COMPUTE_TYPE\`)" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          npx cdk diff --app cdk/cdk.out --all --method=template --security-only --no-color 2>&1 | tee cdk-diff-security.txt
+          if [ -s cdk-diff-security.txt ]; then
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+            cat cdk-diff-security.txt >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No security-relevant changes detected." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload diff artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: cdk-diff-${{ matrix.compute_type }}
+          path: |
+            cdk-diff-full.txt
+            cdk-diff-security.txt
+
+  deploy:
+    needs: [resolve-targets, diff]
+    if: needs.resolve-targets.outputs.has_targets == 'true'
+    runs-on: ubuntu-latest
     environment: deploy
     concurrency:
       group: deploy-${{ matrix.compute_type }}
@@ -174,4 +249,14 @@ jobs:
       - name: Deploy
         env:
           COMPUTE_TYPE: ${{ matrix.compute_type }}
+        # --require-approval never: CDK hard-fails in non-TTY CI without this
+        # (throws "terminal (TTY) is not attached"). The approval mechanism is the
+        # GitHub 'deploy' environment gate above — a human must approve before this
+        # job starts. The 'diff' job surfaces all CloudFormation and security changes
+        # in the step summary (visible before approval), and the full diff is
+        # downloadable as an artifact. Defense in depth:
+        #   1. diff environment (read-only role) → surfaces changes pre-approval
+        #   2. deploy environment (required reviewers) → human gate
+        #   3. fork guard (line 14) → blocks untrusted repositories
+        #   4. OIDC federation → no stored credentials, request-scoped tokens
         run: npx cdk deploy --app cdk/cdk.out --all --require-approval never