refactor: apply least privilege principle to workflow permissions

.github/workflows/build-pull-requests.yml

@@ -29,14 +29,17 @@ on:
       - '.github/workflows/build-pull-requests.yml'
 
 permissions:
-  pull-requests: write
-  checks: write
   contents: read
-  packages: read
-
+
 jobs:
   run-tests:
     name: Run tests
+    # Requires write permissions to publish test results and coverage reports to PR
+    permissions:
+      pull-requests: write  # Required to comment on PRs with test results
+      checks: write         # Required to create check runs for test results
+      contents: read
+      packages: read
     uses: ./.github/workflows/test.yml
     with:
       build-coverage-report: true

.github/workflows/build.yml

@@ -54,11 +54,12 @@ permissions:
 jobs:
   run-tests:
     name: Run tests
+    # Requires write permissions to publish test results
     permissions:
-      checks: write
+      checks: write         # Required to create check runs for test results
+      pull-requests: write  # Required to comment on PRs with test results
       contents: read
       packages: read
-      pull-requests: write
     uses: ./.github/workflows/test.yml
     with:
       build-coverage-report: false
@@ -67,11 +68,12 @@ jobs:
     name: Build artifacts
     runs-on: windows-2022
     needs: run-tests
+    # Requires write permissions to generate artifact attestations
     permissions:
-      id-token: write
+      id-token: write       # Required for OIDC token generation
+      attestations: write   # Required to attest build provenance
       contents: read
       packages: read
-      attestations: write
     outputs:
       docs-log-id: ${{ steps.docs-log-upload.outputs.artifact-id }}
       docs-id: ${{ steps.docs-upload.outputs.artifact-id }}
@@ -180,8 +182,9 @@ jobs:
   upload-docs:
     name: Upload docs
     if: ${{ github.event.inputs.push-to-docs == 'true' }}
+    # Requires write permission for OIDC authentication to GCP
     permissions:
-      id-token: write
+      id-token: write       # Required for OIDC token generation
       contents: read
     uses: ./.github/workflows/upload-docs.yml
     needs: build-artifacts
@@ -191,9 +194,10 @@ jobs:
     runs-on: windows-2022
     needs: build-artifacts
     if: ${{ github.event.inputs.push-to-dev == 'true' }}
+    # Requires write permission to publish NuGet packages
     permissions:
+      packages: write       # Required to publish to GitHub Packages
       contents: read
-      packages: write
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0

.github/workflows/claude.yml

@@ -21,12 +21,13 @@ jobs:
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
     runs-on: ubuntu-latest
+    # Requires write permissions for Claude Code to interact with repository
     permissions:
-      contents: write
-      pull-requests: write
-      issues: write
-      id-token: write
-      actions: read # Required for Claude to read CI results on PRs
+      contents: write       # Required for Claude to commit/push changes
+      pull-requests: write  # Required to comment on and manage PRs
+      issues: write         # Required to comment on and manage issues
+      id-token: write       # Required for OIDC token generation
+      actions: read         # Required for Claude to read CI results on PRs
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0

.github/workflows/codeql-analysis.yml

@@ -40,18 +40,18 @@ on:
       - '.github/workflows/*.yml'
 
 permissions:
-  # required for all workflows
-  security-events: write
-
-  # only required for workflows in private repositories
-  actions: read
   contents: read
-  packages: read
 
 jobs:
   analyze:
     name: Analyze
     runs-on: windows-2022
+    # Requires write permission to upload CodeQL security scan results
+    permissions:
+      security-events: write  # Required for CodeQL to upload scan results
+      actions: read           # Required for workflows in private repositories
+      contents: read
+      packages: read
 
     steps:
       - name: Harden the runner (Audit all outbound calls)

.github/workflows/scorecard.yml

@@ -49,11 +49,11 @@ jobs:
         with:
           results_file: results.sarif
           results_format: sarif
-          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
-          # - you want to enable the Branch-Protection check on a *public* repository, or
-          # - you are installing Scorecard on a *private* repository
-          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
-          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+          # Fine-grained PAT token required to enable Branch-Protection check.
+          # The token must have "Administration: Read-only" permission.
+          # To create the PAT, follow: https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional
+          # Add the token as a repository secret named SCORECARD_TOKEN.
+          repo_token: ${{ secrets.SCORECARD_TOKEN }}
 
           # Public repositories:
           #   - Publish results to OpenSSF REST API for easy access by consumers

.github/workflows/test.yml

@@ -59,11 +59,8 @@ on:
 #      - '.github/workflows/test.yml'
 
 permissions:
-  pull-requests: write
   contents: read
-  checks: write
-  packages: read
-
+
 jobs:
   test-windows:
     name: Tests
@@ -119,10 +116,14 @@ jobs:
           name: CoverageResults
           path: code-coverage-results.md
 
-  pr-comment-coverage-results: 
+  pr-comment-coverage-results:
     name: "Add PR Comment: Coverage Results"
     runs-on: ubuntu-latest
-    needs: build-coverage-report 
+    needs: build-coverage-report
+    # Requires write permission to comment on PRs with coverage results
+    permissions:
+      pull-requests: write  # Required to add/update PR comments
+      contents: read
 
     if: github.event_name == 'pull_request'
     steps:
@@ -142,10 +143,15 @@ jobs:
           recreate: true
           path: code-coverage-results.md
 
-  pr-comment-test-results: 
+  pr-comment-test-results:
     name: "Add PR Comment: Test Results"
     runs-on: ubuntu-latest
-    needs: [test-windows, test-ubuntu, test-macos] 
+    needs: [test-windows, test-ubuntu, test-macos]
+    # Requires write permissions to publish test results to PR
+    permissions:
+      checks: write         # Required to create check runs for test results
+      pull-requests: write  # Required to add/update PR comments
+      contents: read
 
     if: github.event_name == 'pull_request' 
     steps: