PREQ-3880 Introduce JS credential guard to resolve AWS authentication issues

Author: mikolaj-matuszny-ext-sonarsource

.github/workflows/test-action.yml

@@ -120,3 +120,174 @@ jobs:
       run: go mod download
     - name: Build
       run: go build -o hello main.go
+
+  test-s3-cache-with-credential-interference:
+    runs-on: github-ubuntu-latest-s
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4
+        with:
+          version: 2025.7.12
+
+      # Step 1: Use our cache action (should restore and later save)
+      - name: Cache with S3
+        id: cache-test
+        uses: ./
+        with:
+          path: ~/.cache/pip
+          key: interference-test-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: interference-test-${{ runner.os }}-
+          environment: dev
+          backend: s3
+
+      # Step 2: Simulate user overwriting AWS credentials
+      # This is the scenario that caused production failures
+      - name: Overwrite AWS credentials (simulating user workflow)
+        run: |
+          echo "AWS_ACCESS_KEY_ID=FAKE_KEY_TO_OVERRIDE" >> "$GITHUB_ENV"
+          echo "AWS_SECRET_ACCESS_KEY=FAKE_SECRET_TO_OVERRIDE" >> "$GITHUB_ENV"
+          echo "AWS_SESSION_TOKEN=FAKE_TOKEN_TO_OVERRIDE" >> "$GITHUB_ENV"
+          echo "Simulated credential override via GITHUB_ENV"
+
+      # Step 3: Create something to cache
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest requests
+
+      # Post-step: credential-guard restores real creds, then runs-on/cache saves
+      # If this job succeeds, the credential guard is working correctly
+
+  # Reproduces: "Unable to parse config file C:\Users\runneradmin/.aws/config"
+  # https://github.com/SonarSource/peachee-cfamily/actions/runs/21646222381/job/62398839588#step:26:263
+  test-s3-cache-windows:
+    runs-on: github-windows-latest-s
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Cache with S3 on Windows
+        id: cache-test
+        uses: ./
+        with:
+          path: ~\AppData\Local\pip\Cache
+          key: windows-test-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: windows-test-${{ runner.os }}-
+          environment: dev
+          backend: s3
+
+      - name: Create something to cache
+        run: |
+          python -m pip install --upgrade pip
+          pip install requests
+
+  # Reproduces: ~/.aws/config corruption from multiple credential_process entries
+  test-s3-cache-multiple-invocations:
+    runs-on: github-ubuntu-latest-s
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4
+        with:
+          version: 2025.7.12
+
+      # First cache invocation
+      - name: Cache pip dependencies
+        id: cache-pip
+        uses: ./
+        with:
+          path: ~/.cache/pip
+          key: multi-pip-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: multi-pip-${{ runner.os }}-
+          environment: dev
+          backend: s3
+
+      # Second cache invocation in same job
+      # Old approach would append duplicate profile to ~/.aws/config
+      - name: Cache npm dependencies
+        id: cache-npm
+        uses: ./
+        with:
+          path: ~/.npm
+          key: multi-npm-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: multi-npm-${{ runner.os }}-
+          environment: dev
+          backend: s3
+
+      - name: Create something to cache
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          npm init -y
+
+  # Reproduces: pre-existing AWS config from configure-aws-credentials
+  # https://github.com/SonarSource/sonarsource-iam/actions/runs/21951781857/job/63404298650#step:5:9
+  test-s3-cache-with-preset-aws-config:
+    runs-on: github-ubuntu-latest-s
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4
+        with:
+          version: 2025.7.12
+
+      # Simulate pre-existing AWS config (as if configure-aws-credentials ran before)
+      - name: Create pre-existing AWS config
+        run: |
+          mkdir -p ~/.aws
+          cat <<'AWSCONFIG' > ~/.aws/config
+          [default]
+          region = us-east-1
+          output = json
+          [profile some-other-profile]
+          region = us-west-2
+          AWSCONFIG
+          cat <<'AWSCREDS' > ~/.aws/credentials
+          [default]
+          aws_access_key_id = AKIAFAKEDEFAULT
+          aws_secret_access_key = fakesecretdefault
+          [some-other-profile]
+          aws_access_key_id = AKIAFAKEOTHER
+          aws_secret_access_key = fakesecretother
+          AWSCREDS
+          echo "Pre-existing AWS config created"
+          cat ~/.aws/config
+
+      - name: Set conflicting AWS env vars
+        run: |
+          echo "AWS_ACCESS_KEY_ID=AKIAFAKEENV" >> "$GITHUB_ENV"
+          echo "AWS_SECRET_ACCESS_KEY=fakesecretenv" >> "$GITHUB_ENV"
+          echo "AWS_SESSION_TOKEN=faketokenenv" >> "$GITHUB_ENV"
+          echo "AWS_PROFILE=some-other-profile" >> "$GITHUB_ENV"
+          echo "AWS_DEFAULT_PROFILE=some-other-profile" >> "$GITHUB_ENV"
+
+      # Cache action should override the conflicting credentials
+      - name: Cache with S3
+        id: cache-test
+        uses: ./
+        with:
+          path: ~/.cache/pip
+          key: preset-aws-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: preset-aws-${{ runner.os }}-
+          environment: dev
+          backend: s3
+
+      - name: Re-override with fake credentials (simulating mid-job auth change)
+        run: |
+          echo "AWS_ACCESS_KEY_ID=AKIAFAKEOVERRIDE" >> "$GITHUB_ENV"
+          echo "AWS_SECRET_ACCESS_KEY=fakesecretoverride" >> "$GITHUB_ENV"
+          echo "AWS_SESSION_TOKEN=faketokenoverride" >> "$GITHUB_ENV"
+
+      - name: Create something to cache
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest requests

.github/workflows/test-credential-isolation.yml

@@ -0,0 +1,36 @@
+---
+name: Test Credential Isolation
+run-name: Test credential isolation (${{ github.head_ref || github.ref_name }})
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  credential-isolation-tests:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Vault
+        id: secrets
+        uses: SonarSource/vault-action-wrapper@545e7cfbb5528e7009a1edcc83e073898d292627 # 3.2.0
+        with:
+          secrets: |
+            development/github/token/{REPO_OWNER_NAME_DASH}-sonar-dummy-workflows token | GITHUB_TOKEN;
+
+      - name: Trigger and wait for credential isolation tests
+        uses: convictional/trigger-workflow-and-wait@f69fa9eedd3c62a599220f4d5745230e237904be # v1.6.5
+        with:
+          owner: SonarSource
+          repo: sonar-dummy
+          github_token: ${{ fromJSON(steps.secrets.outputs.vault).GITHUB_TOKEN }}
+          ref: master
+          workflow_file_name: test-cache-isolation.yaml
+          client_payload: |
+            {
+              "cache_action_ref": "${{ github.head_ref || github.ref_name }}"
+            }

.gitignore

@@ -1 +1,4 @@
 .claude
+node_modules/
+lib/
+*.js.map

.pre-commit-config.yaml

@@ -12,6 +12,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-added-large-files
+        exclude: ^(credential-setup/dist/|credential-guard/dist/)
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: f295829140d25717bc79368d3f966fc1f67a824f  # frozen: v0.41.0
     hooks:

README.md

@@ -10,8 +10,42 @@ Adaptive cache action that automatically chooses the appropriate caching backend
 
 ## Requirements
 
-- `aws` (AWS CLI)
-- `jq`
+- `jq` (used by the cache key preparation script)
+- `id-token: write` permission (required for OIDC authentication with S3 backend)
+
+## Development
+
+### Prerequisites
+
+- Node.js 20+
+- npm
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Run tests
+
+```bash
+npm test              # single run
+npm run test:watch    # watch mode
+```
+
+### Build
+
+The JS sub-actions (`credential-setup`, `credential-guard`) are bundled with
+`@vercel/ncc` into self-contained dist files. Rebuild after changing TypeScript source:
+
+```bash
+npm run build         # build all sub-actions
+npm run build:setup   # build credential-setup only
+npm run build:guard-main  # build credential-guard main only
+npm run build:guard-post  # build credential-guard post only
+```
+
+Bundled output goes to `credential-setup/dist/` and `credential-guard/dist/`. These must be committed since GitHub Actions runs them directly.
 
 ## Usage
 
@@ -112,35 +146,46 @@ Each environment has its own preconfigured S3 bucket and AWS Cognito pool for is
 
 ### AWS Credential Isolation
 
-This action configures a dedicated AWS profile (`gh-action-cache`) backed by `credential_process`.
-Credentials are fetched on demand using GitHub OIDC + Cognito and never exported to `GITHUB_ENV`.
-This ensures cache operations work correctly even when you configure your own AWS credentials later in the workflow.
+This action uses a JS-based credential guard to ensure cache operations work correctly even when
+other steps in your workflow configure different AWS credentials.
+
+**How it works:**
+
+1. `credential-setup` obtains temporary AWS credentials via GitHub OIDC + Cognito
+2. Credentials are saved to a protected temp file and passed to the cache step via outputs
+3. The cache restore step uses step-level `env:` from outputs — isolated from GITHUB_ENV
+4. `credential-guard` post-step re-exports credentials to GITHUB_ENV for cache save (LIFO ordering)
 
-**Why this matters**: The cache save operation happens in a GitHub Actions post-step (after your job completes).
-If you use `aws-actions/configure-aws-credentials` during your job, it would normally override the cache action's credentials,
-causing cache save to fail. The cache profile stays isolated and is only used by the cache step.
+**This protects against:**
 
-**Example workflow that works correctly**:
+- `aws-actions/configure-aws-credentials` overwriting credentials mid-job
+- `aws-actions/configure-aws-credentials` cleanup clearing credentials
+- Any step writing to `GITHUB_ENV` with different AWS credential values
+- Pre-existing `AWS_PROFILE` or `AWS_DEFAULT_PROFILE` in the environment
+- Users configuring AWS credentials before or after the cache action
+
+**Works regardless of credential ordering** — you can configure your AWS credentials
+before or after the cache action:
 
 ```yaml
 jobs:
   build:
     steps:
-      # Cache action authenticates and uses isolated profile
-      - uses: SonarSource/gh-action_cache@v1
-        with:
-          path: ~/.cache
-          key: my-cache-${{ hashFiles('**/lockfile') }}
-
-      # Your own AWS authentication - does NOT affect cache credentials
+      # Your own AWS authentication — order does not matter
       - uses: aws-actions/configure-aws-credentials@v4
         with:
           role-to-assume: arn:aws:iam::123456789:role/my-role
           aws-region: us-east-1
 
-      - run: aws s3 ls  # Uses YOUR credentials
+      # Cache action authenticates independently via OIDC + Cognito
+      - uses: SonarSource/gh-action-cache@v2
+        with:
+          path: ~/.cache
+          key: my-cache-${{ hashFiles('**/lockfile') }}
+
+      - run: aws s3 ls  # Uses YOUR credentials (cache never touches GITHUB_ENV)
 
-      # Post-step: Cache save uses isolated profile - works correctly!
+      # Post-step: credential-guard restores cache creds, then cache saves!
 ```
 
 ### Cleanup Policy