feat: verify cached SAM CLI archive integrity

.github/workflows/test.yml

@@ -40,8 +40,9 @@ jobs:
           version: "1.104.0"
       - run: sam --version | grep -F 1.104.0
 
-      - name: Test official installer (pinned version; should use cache)
+      - name: Test official installer (pinned version; no published digest, so uncached)
         uses: ./
+        id: installer-pinned-cached
         with:
           use-installer: true
           version: "1.104.0"
@@ -56,6 +57,36 @@ jobs:
           sam --version | grep -F "$version"
         shell: bash
 
+      # A version with a published SHA256 digest can be cached, so the second
+      # invocation must restore it and pass integrity verification. This is the
+      # only coverage of the verified cache-hit path against the real cache
+      # service; unit tests mock @actions/cache and cannot exercise it.
+      - name: Test verified cache (cold)
+        uses: ./
+        id: cache-cold
+        with:
+          use-installer: true
+          version: "1.166.2"
+      - run: sam --version | grep -F 1.166.2
+
+      - name: Test verified cache (warm; must hit cache)
+        uses: ./
+        id: cache-warm
+        with:
+          use-installer: true
+          version: "1.166.2"
+      - run: sam --version | grep -F 1.166.2
+      - name: Assert cache was used
+        run: |
+          echo "cold cache-hit=${{ steps.cache-cold.outputs.cache-hit }}"
+          echo "warm cache-hit=${{ steps.cache-warm.outputs.cache-hit }}"
+          test "${{ steps.cache-warm.outputs.cache-hit }}" = "true"
+
+      # 1.104.0 predates published asset digests, so it cannot be verified and
+      # must therefore never be served from the cache.
+      - name: Assert unverifiable version does not use the cache
+        run: test "${{ steps.installer-pinned-cached.outputs.cache-hit }}" != "true"
+
   integ:
     strategy:
       fail-fast: false

README.md

@@ -24,7 +24,6 @@ jobs:
       - uses: aws-actions/setup-sam@v3
         with:
           use-installer: true
-          token: ${{ secrets.GITHUB_TOKEN }}
       - uses: aws-actions/configure-aws-credentials@v6
         with:
           role-to-assume: ${{ secrets.ASSUME_ROLE_ARN }}
@@ -65,13 +64,11 @@ You can use [`actions/setup-python`](https://github.com/actions/setup-python) to
 
 ### `token`
 
-> **Note**
->
-> It is recommended to use token to have higher rate limit. Default [unauthenticated users](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-unauthenticated-users) without a token will have a lesser rate limit enforced.
+The GITHUB Authentication token used to call the GITHUB release APIs, which `use-installer: true` reads to resolve the version to install and to obtain the published archive digest it verifies against.
 
-The GITHUB Authentication token to use for calling the GITHUB [Get the latest release](https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#get-the-latest-release) API. Defaults to call the API as unauthenticated request if not specified.
+On `github.com` this defaults to the job's [`GITHUB_TOKEN`](https://docs.github.com/en/actions/security-guides/automatic-token-authentication), so the per-repository rate limit applies rather than the much smaller [unauthenticated limit](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-unauthenticated-users), which is shared per IP across runners. You do not normally need to set it.
 
-The parameter can accept either [`GITHUB_TOKEN`](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) or [`PAT(Personal Access Token)`](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) tokens.
+The parameter can accept either `GITHUB_TOKEN` or a [PAT (Personal Access Token)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
 
 ## Security
 

action.yml

@@ -17,6 +17,16 @@ inputs:
   token:
     description: "Authentication token to be used to call GITHUB Apis"
     required: false
+    # The installer path reads the published archive digest from the release
+    # API on every run, so an unauthenticated request (60/hour per IP, shared
+    # across runners) can be exhausted by unrelated jobs and leave nothing to
+    # verify against. Default to the job's token so the limit is per repository
+    # instead. api.github.com is hardcoded, so a GitHub Enterprise Server token
+    # would be both useless here and sent off-instance - send nothing there.
+    default: ${{ github.server_url == 'https://github.com' && github.token || '' }}
+outputs:
+  cache-hit:
+    description: "Whether AWS SAM CLI was restored from the GitHub Actions cache and passed integrity verification"
 runs:
   using: node24
   main: dist/index.js