feat: Accept a 'cache_key' input

Author: smockle

.github/actions/gh-cache/restore/README.md

@@ -8,7 +8,7 @@ Checkout a file or directory from an orphaned 'gh-cache' branch.
 
 #### `path`
 
-**Required** Relative path to a file or directory to restore. For example: `findings.json`.
+**Required** Relative path to a file or directory to restore. Allowed characters are `A-Za-z0-9._/-`. For example: `findings.json`.
 
 #### `token`
 

.github/actions/gh-cache/restore/action.yml

@@ -3,7 +3,7 @@ description: "Checkout a file or directory from an orphaned 'gh-cache' branch"
 
 inputs:
   path:
-    description: "Relative path to a file or directory to restore"
+    description: "Relative path to a file or directory to restore."
     required: true
   token:
     description: "Token with fine-grained permissions 'contents: read'"
@@ -16,6 +16,33 @@ inputs:
 runs:
   using: "composite"
   steps:
+    - name: Validate path
+      shell: bash
+      run: |
+        # Check for empty
+        if [[ -z "${{ inputs.path }}" ]]; then
+          echo "Invalid 'path' input (empty)"
+          exit 1
+        fi
+        # Check for absolute paths
+        if [[ "${{ inputs.path }}" == /* ]]; then
+          echo "Invalid 'path' input (absolute path): ${{ inputs.path }}"
+          exit 1
+        fi
+        # Check for directory traversal
+        if [[
+          "${{ inputs.path }}" == "~"* ||
+          "${{ inputs.path }}" =~ (^|/)\.\.(/|$)
+        ]]; then
+          echo "Invalid 'path' input (directory traversal): ${{ inputs.path }}"
+          exit 1
+        fi
+        # Check for disallowed characters (to ensure portability)
+        if [[ ! "${{ inputs.path }}" =~ ^[A-Za-z0-9._/-]+$ ]]; then
+          echo "Invalid 'path' input (disallowed characters): ${{ inputs.path }}"
+          exit 1
+        fi
+
     - name: Checkout repository to temporary directory
       uses: actions/checkout@v5
       with:

.github/actions/gh-cache/save/README.md

@@ -8,7 +8,7 @@ Commit a file or directory to an orphaned 'gh-cache' branch.
 
 #### `path`
 
-**Required** Relative path to a file or directory to save. For example: `findings.json`.
+**Required** Relative path to a file or directory to save. Allowed characters are `A-Za-z0-9._/-`. For example: `findings.json`.
 
 #### `token`
 

.github/actions/gh-cache/save/action.yml

@@ -12,6 +12,33 @@ inputs:
 runs:
   using: "composite"
   steps:
+    - name: Validate path
+      shell: bash
+      run: |
+        # Check for empty
+        if [[ -z "${{ inputs.path }}" ]]; then
+          echo "Invalid 'path' input (empty)"
+          exit 1
+        fi
+        # Check for absolute paths
+        if [[ "${{ inputs.path }}" == /* ]]; then
+          echo "Invalid 'path' input (absolute path): ${{ inputs.path }}"
+          exit 1
+        fi
+        # Check for directory traversal
+        if [[
+          "${{ inputs.path }}" == "~"* ||
+          "${{ inputs.path }}" =~ (^|/)\.\.(/|$)
+        ]]; then
+          echo "Invalid 'path' input (directory traversal): ${{ inputs.path }}"
+          exit 1
+        fi
+        # Check for disallowed characters (to ensure portability)
+        if [[ ! "${{ inputs.path }}" =~ ^[A-Za-z0-9._/-]+$ ]]; then
+          echo "Invalid 'path' input (disallowed characters): ${{ inputs.path }}"
+          exit 1
+        fi
+
     - name: Checkout repository to temporary directory
       uses: actions/checkout@v5
       with:

README.md

@@ -23,6 +23,10 @@ https://primer.style/octicons/
 
 **Required** Personal access token (PAT) with fine-grained permissions 'contents: write', 'issues: write', and 'pull_requests: write'.
 
+#### `cache_key`
+
+**Optional** Custom key for caching findings across runs. Allowed characters are `A-Za-z0-9._/-`. For example: `cached_findings-main-primer.style.json`.
+
 ### Example workflow
 
 ```YAML

action.yml

@@ -12,15 +12,28 @@ inputs:
   token:
     description: "Personal access token (PAT) with fine-grained permissions 'contents: write', 'issues: write', and 'pull_requests: write'"
     required: true
+  cache_key:
+    description: "Custom key for caching findings across runs"
+    required: false
 
 runs:
   using: "composite"
   steps:
+    - name: Generate cache key
+      id: cache_key
+      shell: bash
+      run: |
+        CACHE_KEY="${{ inputs.cache_key }}"
+        if [[ -z "$CACHE_KEY" ]]; then
+          # If cache_key is not provided, generate a default one using the branch name, replacing characters (e.g. `/`) which would create unexpected paths.
+          CACHE_KEY=$(printf 'cached_findings-%s' "${{ github.ref_name }}" | tr -cs 'A-Za-z0-9._-' '_')
+        fi
+        echo "cache_key=$CACHE_KEY" >> $GITHUB_OUTPUT
     - name: Restore cached_findings
       id: restore
       uses: github/continuous-ai-for-accessibility-scanner/.github/actions/gh-cache/cache@main
       with:
-        key: cached_findings-${{ github.ref_name }}
+        key: ${{ steps.cache_key.outputs.cache_key }}
         token: ${{ inputs.token }}
     - name: Find
       id: find
@@ -45,7 +58,7 @@ runs:
     - name: Save cached_findings
       uses: github/continuous-ai-for-accessibility-scanner/.github/actions/gh-cache/cache@main
       with:
-        key: cached_findings-${{ github.ref_name }}
+        key: ${{ steps.cache_key.outputs.cache_key }}
         value: ${{ steps.file.outputs.findings }}
         token: ${{ inputs.token }}