feat: path validation for restored caches

Wires the new path validation from @actions/cache into the action so workflows are protected against some forms of cache poisoning that plant archive entries (or symlink/hardlink targets) resolving outside the declared path inputs — e.g. ../../etc/..., absolute paths, UNC paths, or symlinks pointing into the runner's workspace.

The actions/cache action defaults to strict-paths: warn for now, so existing workflows get logging automatically without any risk of change to cache extraction. Switching to error opts into pre-extraction rejection of poisoned archives. We should plan to change the default to error in a future major-version update to the action.

New inputs (on both cache and cache/restore)

Implementation

• src/utils/actionUtils.ts — getPathValidationInput() parses and normalizes the input (case-insensitive, typo-safe fallback to warn).
• src/restoreImpl.ts — forwards pathValidation in the DownloadOptions object passed to cache.restoreCache(...), and wraps the call in a try/catch:
  • Errors are detected by err.name === "CacheIntegrityError" + .code read off the error object (intentionally not instanceof, so the check survives the CJS/ESM stub seam between Jest and the bundled runtime).
  • If fail-on-cache-invalid: true → rethrow as a decorated error.
  • Otherwise → logWarning and return; cache-hit is deliberately left unset so the discard is indistinguishable from a normal cache miss.
• src/constants.ts — two new Inputs enum entries.
• src/utils/testUtils.ts — setInputs plumbed for the new inputs.
• action.yml, restore/action.yml, README.md, restore/README.md, RELEASES.md — documented.

Dependency / version

• @actions/cache: ^5.0.5 → ^6.1.0 (introduces the validation surface; brings in tar@^7.5.15).
• Action version: 5.0.4 → 5.1.0 (additive — no behavior change for any cache that doesn't contain off-root entries).

Tests

• tests/actionUtils.test.ts — 9 cases covering getPathValidationInput (defaults, case folding, unknown-value fallback, env-var resolution).
• tests/restoreImpl.test.ts — 9 new cases covering: forwarding the option to the toolkit for each mode, integrity-error → cache-miss default, integrity-error + fail-on-cache-invalid → rethrow, non-integrity errors propagate unchanged, parse-error and missing-.code variants, and the assertion that cache-hit is never set when an integrity error is rethrown.
• tests/restore.test.ts, tests/restoreOnly.test.ts — updated to assert the option is forwarded, with getPathValidationInput spied via jest.requireActual (the default auto-mock returns undefined, which would silently pass thanks to deep-equality quirks).
• @actions/cache@6 is ESM-only and Jest's CJS resolver can't load it directly. Production builds are fine (bundled by @vercel/ncc, which handles ESM deps), but tests need a CJS-compatible surface, so the PR adds tests/mocks/actions-cache.ts — a CJS stub wired up via moduleNameMapper in jest.config.js. All types are re-exported from the real @actions/cache package via import type, and every runtime value is annotated typeof Cache.X, so any signature drift in the real package fails the build.

E2E workflow

Added .github/workflows/path-validation-e2e.yml — a matrix that saves a legitimate cache, saves a poisoned one via the toolkit's internal APIs, and exercises all three strict-paths values across Ubuntu / macOS / Windows runners. Trigger is workflow_dispatch only, since the 39-job matrix is too expensive to run on every PR.

Bundled dist

All four ncc bundles (restore, save, restore-only, save-only) regenerated against the new toolkit. Diff is large but mechanical.

Depends on

@actions/[email protected] from actions/toolkit#2414

• ⚠️ Builds of this PR will fail until that PR is merged and the package is published.

Follow-ups (not in this PR)

• Flip strict-paths default from warn to error in a future major version.
• Publish strict-paths: error adoption guide for high-trust workflows.