@secureci/cli 0.5.1 → 0.6.0

package/dist/parser/pipeline-contract-validator.js

@@ -38,9 +38,11 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const job_plan_1 = require("../runner/job-plan");
 const workflow_parser_1 = require("./workflow-parser");
+const dangerous_triggers_1 = require("./dangerous-triggers");
 const repository_1 = require("../utils/repository");
 const action_fetcher_1 = require("../runner/action-fetcher");
 const github_lockfile_1 = require("../github-lockfile");
+const permissions_1 = require("./permissions");
 /** Maximum nesting of composite actions / reusable workflows. */
 const MAX_DEPTH = 10;
 /**
@@ -51,13 +53,13 @@ const MAX_DEPTH = 10;
  * Composite actions (`uses: ./path`) and reusable workflows
  * (`jobs.<id>.uses: ./path.yml`) are resolved recursively, so wrapping an
  * action doesn't hide it: local ones by default, remote ones too with
- * `recurse: 'all'`. Ordering follows
+ * `recurse: 'all'` (`offline`: only from the cache). Ordering follows
  * what GitHub guarantees: steps of a job run in order, and a job runs after
  * the jobs it (transitively) `needs:`; jobs with no such relationship may
  * run in parallel, so neither is "before" the other.
  */
 async function validatePipelineContract(parsed, spec, options = {}) {
-    const graph = await buildGraph(parsed, options.recurse ?? 'local');
+    const graph = await buildGraph(parsed, options.recurse ?? 'local', options.offline ?? false);
     const { sequence, nodes } = graph;
     const errors = [...graph.errors];
     const ordering = spec.ordering ?? 'relative';
@@ -199,6 +201,16 @@ async function validatePipelineContract(parsed, spec, options = {}) {
     if (spec.lockfile?.required) {
         errors.push(...checkLockfile(parsed, sequence.filter(isRemote)));
     }
+    // The workflow file's own permissions; called workflows are validated as
+    // files of their own.
+    if (spec.permissions) {
+        errors.push(...(0, permissions_1.contractPermissionErrors)(parsed.file, spec.permissions));
+    }
+    // Only the workflow's own on: matters: a called reusable workflow runs
+    // under its caller's event.
+    if (spec.forbiddenTriggers) {
+        errors.push(...(0, dangerous_triggers_1.forbiddenTriggerErrors)(parsed.file, spec.forbiddenTriggers));
+    }
     return {
         valid: errors.every((e) => e.severity !== 'error'),
         errors
@@ -260,7 +272,7 @@ function needsTransitively(nodes, from, to) {
     }
     return false;
 }
-async function buildGraph(parsed, recurse) {
+async function buildGraph(parsed, recurse, offline) {
     const graph = { sequence: [], nodes: new Map(), errors: [] };
     const root = (0, repository_1.repositoryRoot)(parsed.path);
     const isLocal = (uses) => uses.startsWith('./') || uses.startsWith('../');
@@ -295,7 +307,9 @@ async function buildGraph(parsed, recurse) {
         }
         if (recurse !== 'all' || uses.startsWith('docker://'))
             return undefined;
-        const file = kind === 'action' ? await (0, action_fetcher_1.fetchAction)(uses) : await (0, action_fetcher_1.fetchRepoFile)(uses);
+        const file = kind === 'action'
+            ? await (0, action_fetcher_1.fetchAction)(uses, { offline })
+            : await (0, action_fetcher_1.fetchRepoFile)(uses, { offline });
         if (!file) {
             graph.errors.push({
                 path: at,

package/dist/parser/validator.js

@@ -3,9 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.workflowExpressionErrors = workflowExpressionErrors;
 exports.actionExpressionErrors = actionExpressionErrors;
 exports.validateWorkflow = validateWorkflow;
+exports.mergeValidationResults = mergeValidationResults;
 exports.validateAction = validateAction;
 const workflow_parser_1 = require("./workflow-parser");
 const expression_1 = require("../runner/expression");
+const injection_1 = require("./injection");
+const permissions_1 = require("./permissions");
+const dangerous_triggers_1 = require("./dangerous-triggers");
 /**
  * Invalid `if:` expressions in a workflow: syntax errors, or contexts and
  * functions not available where they're used. GitHub rejects such a
@@ -120,6 +124,9 @@ function validateWorkflow(filePath) {
             });
         }
         errors.push(...workflowExpressionErrors(workflow));
+        errors.push(...(0, injection_1.workflowInjectionErrors)(workflow, filePath));
+        errors.push(...(0, permissions_1.workflowPermissionErrors)(workflow));
+        errors.push(...(0, dangerous_triggers_1.dangerousTriggerErrors)(workflow));
     }
     catch (error) {
         errors.push({
@@ -129,10 +136,27 @@ function validateWorkflow(filePath) {
         });
     }
     return {
-        valid: errors.length === 0,
+        valid: errors.every((e) => e.severity !== 'error'),
         errors
     };
 }
+/**
+ * Combine validation results (e.g. syntax checks and a contract). A warning
+ * is dropped when an error with the same rule and path supersedes it, such
+ * as a default permissions warning the contract turns into an error.
+ */
+function mergeValidationResults(...results) {
+    const all = results.flatMap((r) => r.errors);
+    const superseding = new Set(all
+        .filter((e) => e.severity === 'error' && e.rule)
+        .map((e) => `${e.rule}\0${e.path}`));
+    return {
+        valid: results.every((r) => r.valid),
+        errors: all.filter((e) => e.severity !== 'warning' ||
+            !e.rule ||
+            !superseding.has(`${e.rule}\0${e.path}`))
+    };
+}
 /**
  * Validate an action file
  */
@@ -201,6 +225,7 @@ function validateAction(filePath) {
                         }
                     });
                     errors.push(...actionExpressionErrors(action));
+                    errors.push(...(0, injection_1.actionInjectionErrors)(action, filePath));
                 }
             }
         }

package/dist/pin.js

@@ -0,0 +1,311 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findUsesSites = findUsesSites;
+exports.isPinAllowed = isPinAllowed;
+exports.pinContent = pinContent;
+exports.localPinTargets = localPinTargets;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const YAML = __importStar(require("yaml"));
+const repository_1 = require("./utils/repository");
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+/**
+ * Every `uses:` a runner reads: `jobs.<id>.uses` (reusable workflows),
+ * `jobs.<id>.steps[*].uses` and a composite action's `runs.steps[*].uses`.
+ * Read from the YAML syntax tree, so `uses:` inside a script or an input
+ * isn't mistaken for one, with source offsets for in-place edits.
+ */
+function findUsesSites(content) {
+    const doc = parseYaml(content);
+    const root = doc.contents;
+    if (!YAML.isMap(root))
+        return [];
+    const nodes = [];
+    const usesOf = (node) => {
+        if (!YAML.isMap(node))
+            return;
+        const uses = node.get('uses', true);
+        if (YAML.isScalar(uses))
+            nodes.push(uses);
+    };
+    const stepsOf = (node) => {
+        if (!YAML.isMap(node))
+            return;
+        const steps = node.get('steps', true);
+        if (YAML.isSeq(steps))
+            steps.items.forEach(usesOf);
+    };
+    const jobs = root.get('jobs', true);
+    if (YAML.isMap(jobs)) {
+        for (const pair of jobs.items) {
+            usesOf(pair.value);
+            stepsOf(pair.value);
+        }
+    }
+    stepsOf(root.get('runs', true));
+    return nodes
+        .filter((node) => node.range && typeof node.value === 'string')
+        .map((node) => {
+        const [start, end] = node.range;
+        return {
+            line: content.slice(0, start).split('\n').length,
+            uses: node.value,
+            start,
+            end,
+            style: scalarStyle(node.type)
+        };
+    })
+        .sort((a, b) => a.start - b.start);
+}
+function parseYaml(content) {
+    const doc = YAML.parseDocument(content);
+    if (doc.errors.length > 0) {
+        throw new Error(`File is not valid YAML: ${doc.errors[0].message}`);
+    }
+    return doc;
+}
+function scalarStyle(type) {
+    if (type === 'QUOTE_SINGLE')
+        return 'single';
+    if (type === 'QUOTE_DOUBLE')
+        return 'double';
+    if (type === 'BLOCK_LITERAL' || type === 'BLOCK_FOLDED')
+        return 'block';
+    return 'plain';
+}
+/**
+ * Whether a contract's `pins.allow` exempts a reference from pinning: an
+ * owner, or the exact action name, case-insensitively for owner and repo.
+ * This mirrors the contract's own pins check, so `pin` never leaves a
+ * reference on a tag that `validate --contract` would then reject.
+ */
+function isPinAllowed(uses, allow) {
+    const at = uses.lastIndexOf('@');
+    const name = normalizeName(at === -1 ? uses : uses.slice(0, at));
+    const owner = name.split('/')[0];
+    const allowed = new Set(allow.map(normalizeName));
+    return allowed.has(name) || allowed.has(owner);
+}
+function normalizeName(name) {
+    const parts = name.split('/');
+    return [
+        ...parts.slice(0, 2).map((p) => p.toLowerCase()),
+        ...parts.slice(2)
+    ].join('/');
+}
+/**
+ * Pin every remote `uses:` reference in a workflow or action file to the
+ * commit SHA `resolve` returns, keeping the tag in a trailing comment
+ * (`owner/repo@<sha> # v4`) so Dependabot and Renovate can still update
+ * it. The text is edited in place (only the value and its comment change),
+ * never re-serialised, so formatting and other comments survive.
+ *
+ * Left alone: local (`./`) and `docker://` references, references already
+ * pinned to a full SHA, and those `allow` exempts. A reference that can't
+ * be resolved is reported in `unresolved` and not changed.
+ */
+async function pinContent(content, resolve, options = {}) {
+    const sites = findUsesSites(content);
+    const result = {
+        content,
+        changes: [],
+        unresolved: [],
+        allowed: []
+    };
+    const lineCounts = new Map();
+    sites.forEach((s) => lineCounts.set(s.line, (lineCounts.get(s.line) ?? 0) + 1));
+    const resolved = new Map();
+    const edits = [];
+    for (const site of sites) {
+        const { uses, line } = site;
+        if (/^(\.\.?\/|docker:\/\/)/.test(uses))
+            continue;
+        const at = uses.lastIndexOf('@');
+        const name = at === -1 ? '' : uses.slice(0, at);
+        const ref = uses.slice(at + 1);
+        const parts = name.split('/');
+        if (at === -1 || !ref || parts.length < 2 || parts.some((p) => !p)) {
+            result.unresolved.push({
+                line,
+                uses,
+                reason: 'is not an owner/repo@ref reference'
+            });
+            continue;
+        }
+        if (FULL_SHA.test(ref))
+            continue;
+        if (isPinAllowed(uses, options.allow ?? [])) {
+            result.allowed.push({ line, uses });
+            continue;
+        }
+        if (site.style === 'block') {
+            result.unresolved.push({
+                line,
+                uses,
+                reason: 'is written as a block scalar; pin it by hand'
+            });
+            continue;
+        }
+        if (!resolved.has(uses))
+            resolved.set(uses, resolve(uses));
+        const sha = (await resolved.get(uses))?.toLowerCase();
+        if (!sha || !FULL_SHA.test(sha)) {
+            result.unresolved.push({
+                line,
+                uses,
+                reason: 'could not be resolved to a commit'
+            });
+            continue;
+        }
+        const pinned = `${name}@${sha}`;
+        const quote = site.style === 'single' ? "'" : site.style === 'double' ? '"' : '';
+        edits.push({
+            start: site.start,
+            end: site.end,
+            text: `${quote}${pinned}${quote}`
+        });
+        // Several references on one line (a flow sequence) can't each have a
+        // trailing comment, so none is written rather than a wrong one.
+        if (lineCounts.get(line) === 1) {
+            edits.push(commentEdit(content, site.end, ref));
+        }
+        result.changes.push({ line, uses, ref, sha, pinned });
+    }
+    result.content = edits
+        .sort((a, b) => b.start - a.start)
+        .reduce((text, e) => text.slice(0, e.start) + e.text + text.slice(e.end), content);
+    return result;
+}
+/**
+ * The edit that leaves `# <ref>` as the comment of the line a value ends
+ * on: an old version comment is replaced, any other comment kept after
+ * the ref, and with no comment one is added at the end of the line.
+ */
+function commentEdit(content, valueEnd, ref) {
+    let lineEnd = content.indexOf('\n', valueEnd);
+    if (lineEnd === -1)
+        lineEnd = content.length;
+    if (content[lineEnd - 1] === '\r')
+        lineEnd--;
+    const tail = content.slice(valueEnd, lineEnd);
+    const hash = commentStart(tail);
+    if (hash === -1) {
+        const at = valueEnd + tail.trimEnd().length;
+        return { start: at, end: at, text: ` # ${ref}` };
+    }
+    const body = tail.slice(hash + 1).trim();
+    return {
+        start: valueEnd + hash,
+        end: lineEnd,
+        text: `# ${ref}${commentRest(body, ref)}`
+    };
+}
+/** Where a YAML comment starts in the rest of a line, or -1. */
+function commentStart(tail) {
+    let quote;
+    for (let i = 0; i < tail.length; i++) {
+        const c = tail[i];
+        if (quote) {
+            if (c === '\\' && quote === '"')
+                i++;
+            else if (c === quote)
+                quote = undefined;
+        }
+        else if (c === "'" || c === '"') {
+            quote = c;
+        }
+        else if (c === '#' && i > 0 && /\s/.test(tail[i - 1])) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * What to keep of an existing comment after the new `# <ref>`: the text
+ * after an old version (`v3`, `3.2.1`, `tag=v3`, `pin @v3`, or the old
+ * ref itself), else the whole comment.
+ */
+function commentRest(body, ref) {
+    if (!body)
+        return '';
+    const version = body.match(/^(?:tag\s*=\s*|pin\s*@?\s*)?@?v?\d[\w.+-]*(.*)$/i);
+    const rest = version
+        ? version[1]
+        : body === ref || body.startsWith(`${ref} `)
+            ? body.slice(ref.length)
+            : undefined;
+    if (rest === undefined)
+        return ` - ${body}`;
+    return rest.trim() ? ` ${rest.trim()}` : '';
+}
+/**
+ * The given files plus the local composite actions (`./path`) and local
+ * reusable workflows they use, recursively, so a whole repository is
+ * pinned in one go. `./` resolves against the repository root, as on
+ * GitHub. Files are listed once; one that can't be read is kept (for the
+ * caller to report) but not followed.
+ */
+function localPinTargets(files) {
+    const seen = new Set(files.map((f) => path.resolve(f)));
+    const result = [...files];
+    const follow = (file, root) => {
+        let sites;
+        try {
+            sites = findUsesSites(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            return;
+        }
+        for (const { uses } of sites) {
+            if (!uses.startsWith('./') && !uses.startsWith('../'))
+                continue;
+            const target = path.resolve(root, uses);
+            const local = [
+                target,
+                ...['action.yml', 'action.yaml'].map((n) => path.join(target, n))
+            ].find((c) => fs.existsSync(c) && fs.statSync(c).isFile());
+            if (!local || seen.has(local))
+                continue;
+            seen.add(local);
+            result.push(local);
+            follow(local, root);
+        }
+    };
+    for (const file of files)
+        follow(file, (0, repository_1.repositoryRoot)(file));
+    return result;
+}
+//# sourceMappingURL=pin.js.map

package/dist/report.js

@@ -4,6 +4,8 @@ exports.formatReport = formatReport;
 exports.formatValidation = formatValidation;
 /** A SARIF rule id per error, so code-scanning can group findings. */
 function ruleIdFor(error) {
+    if (error.rule)
+        return error.rule;
     if (/^required\[|^forbidden\[/.test(error.path))
         return 'secureci/contract';
     if (/\.if$|\bif:/.test(error.path))
@@ -13,7 +15,11 @@ function ruleIdFor(error) {
 const RULES = {
     'secureci/validation': 'Workflow or action structure',
     'secureci/contract': 'Pipeline contract',
-    'secureci/expression': 'Expression / if: condition'
+    'secureci/expression': 'Expression / if: condition',
+    'secureci/injection': 'Untrusted input in a shell or script',
+    'secureci/permissions': 'GITHUB_TOKEN permissions',
+    'secureci/dangerous-trigger': 'Privileged trigger with untrusted code',
+    'secureci/vulnerable-action': 'Action with a known security advisory'
 };
 function jsonForFile(entry) {
     return {

package/dist/runner/action-fetcher.js

@@ -37,10 +37,16 @@ exports.parseActionReference = parseActionReference;
 exports.getActionCacheDir = getActionCacheDir;
 exports.githubToken = githubToken;
 exports._resetGithubTokenForTests = _resetGithubTokenForTests;
+exports.serverUrl = serverUrl;
+exports.apiUrl = apiUrl;
 exports.lsRemoteSha = lsRemoteSha;
+exports.parseLsRemoteTags = parseLsRemoteTags;
+exports.lsRemoteTags = lsRemoteTags;
+exports.getText = getText;
 exports.fetchAction = fetchAction;
 exports.fetchRepoFile = fetchRepoFile;
 exports.clearActionCache = clearActionCache;
+exports.cachedActionSha = cachedActionSha;
 exports.resolveActionSha = resolveActionSha;
 exports.resolveRepoIdentity = resolveRepoIdentity;
 exports.lsRemoteReachable = lsRemoteReachable;
@@ -110,9 +116,14 @@ function githubToken() {
 function _resetGithubTokenForTests() {
     discoveredToken = undefined;
 }
+/** The GitHub server ($GITHUB_SERVER_URL, default https://github.com). */
 function serverUrl() {
     return (process.env.GITHUB_SERVER_URL || 'https://github.com').replace(/\/+$/, '');
 }
+/**
+ * The GitHub REST API base: $GITHUB_API_URL, else api.github.com, or
+ * `<server>/api/v3` for GitHub Enterprise Server.
+ */
 function apiUrl() {
     if (process.env.GITHUB_API_URL) {
         return process.env.GITHUB_API_URL.replace(/\/+$/, '');
@@ -155,7 +166,51 @@ async function lsRemoteSha(url, ref) {
         refs.get(`refs/tags/${ref}`) ??
         refs.get(`refs/heads/${ref}`));
 }
-/** GET a small text response (the API commit lookup). */
+/**
+ * Tag name -> commit SHA from `git ls-remote --tags` output. An annotated
+ * tag's peeled entry (`refs/tags/x^{}`) wins, so every SHA is a commit.
+ */
+function parseLsRemoteTags(output) {
+    const tags = new Map();
+    const peeled = new Set();
+    for (const line of output.split('\n')) {
+        const [sha, ref] = line.trim().split(/\s+/);
+        if (!sha || !FULL_SHA.test(sha) || !ref?.startsWith('refs/tags/'))
+            continue;
+        let name = ref.slice('refs/tags/'.length);
+        const isPeeled = name.endsWith('^{}');
+        if (isPeeled)
+            name = name.slice(0, -3);
+        if (isPeeled || !peeled.has(name))
+            tags.set(name, sha.toLowerCase());
+        if (isPeeled)
+            peeled.add(name);
+    }
+    return tags;
+}
+/**
+ * Every tag of the repository at `url` and the commit it points at, via
+ * anonymous `git ls-remote --tags` (no API rate limit), or undefined if
+ * the repository can't be read.
+ */
+async function lsRemoteTags(url) {
+    try {
+        const { stdout } = await execFileAsync('git', ['ls-remote', '--tags', url], {
+            encoding: 'utf8',
+            timeout: 15000,
+            maxBuffer: 16 * 1024 * 1024,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+        });
+        return parseLsRemoteTags(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * GET a small text response (API lookups). Rejects on a non-200 status
+ * with an error carrying `status`.
+ */
 function getText(url, headers, timeoutMs) {
     return new Promise((resolve, reject) => {
         const client = url.startsWith('http://') ? http : https;
@@ -278,7 +333,27 @@ function writeRefIndex(dir, refs) {
  * picked up. If the ref can't be resolved (offline, rate-limited), the
  * last commit cached for it is used. Returns the repository root.
  */
-async function fetchRepository(ref, uses, options) {
+const inflight = new Map();
+/**
+ * fetchRepositoryOnce, shared by concurrent callers asking for the same
+ * repository and ref (jobs running in parallel), so it is downloaded and
+ * written into the cache once.
+ */
+function fetchRepository(ref, uses, options) {
+    const key = JSON.stringify([
+        repoCacheDir(ref),
+        ref.ref,
+        !!options.offline,
+        options.token === undefined ? 'discovered' : options.token
+    ]);
+    let pending = inflight.get(key);
+    if (!pending) {
+        pending = fetchRepositoryOnce(ref, uses, options).finally(() => inflight.delete(key));
+        inflight.set(key, pending);
+    }
+    return pending;
+}
+async function fetchRepositoryOnce(ref, uses, options) {
     const dir = repoCacheDir(ref);
     const refs = readRefIndex(dir);
     const cachedSha = FULL_SHA.test(ref.ref)
@@ -334,8 +409,12 @@ async function fetchRepository(ref, uses, options) {
         const [top] = fs.readdirSync(extractDir);
         if (!top)
             throw new Error('No files extracted from tarball');
-        fs.rmSync(target, { recursive: true, force: true });
-        fs.renameSync(path.join(extractDir, top), target);
+        // A commit's content never changes: keep a copy another job (asking
+        // by another ref) put there meanwhile, as it may be in use.
+        if (!sha || !fs.existsSync(target)) {
+            fs.rmSync(target, { recursive: true, force: true });
+            fs.renameSync(path.join(extractDir, top), target);
+        }
         if (sha) {
             writeRefIndex(dir, { ...readRefIndex(dir), [ref.ref]: sha });
         }
@@ -410,6 +489,23 @@ function clearActionCache() {
         logger_1.logger.info('Action cache cleared');
     }
 }
+/**
+ * The commit a ref resolved to when it was last downloaded into the action
+ * cache, without touching the network (for offline use), or undefined when
+ * that commit isn't cached. An already-pinned SHA is returned as is. For a
+ * moving ref (`@main`) this is the last commit seen, not necessarily the
+ * current one.
+ */
+function cachedActionSha(uses) {
+    const ref = parseActionReference(uses);
+    if (!ref)
+        return undefined;
+    if (FULL_SHA.test(ref.ref))
+        return ref.ref.toLowerCase();
+    const dir = repoCacheDir(ref);
+    const sha = readRefIndex(dir)[ref.ref];
+    return sha && fs.existsSync(path.join(dir, sha)) ? sha : undefined;
+}
 /**
  * Resolve a `uses:` action reference to its current commit SHA, for the
  * inventory and lockfile. Returns undefined if the ref can't be resolved

package/dist/runner/builtin-actions.js

@@ -435,14 +435,24 @@ async function saveCache(fsys, scope, key, paths) {
             warning: 'Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved.'
         };
     }
-    const staging = `${dir}.tmp-${process.pid}`;
-    fs.rmSync(staging, { recursive: true, force: true });
+    // Unique per save: jobs running at once may save the same key.
+    const staging = `${dir}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
     for (const file of files) {
         copyFile(file.host, path.join(staging, 'files', ...cachedLocation(fsys, file.logical).split('/')));
     }
     fs.writeFileSync(path.join(staging, 'meta.json'), JSON.stringify({ key, version, created: Date.now() }));
     fs.mkdirSync(path.dirname(dir), { recursive: true });
-    fs.renameSync(staging, dir);
+    try {
+        fs.renameSync(staging, dir);
+    }
+    catch (error) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        // Another job saved this key meanwhile; cache entries are immutable.
+        if (fs.existsSync(path.join(dir, 'meta.json'))) {
+            return ok(`Cache for key "${key}" already exists; not saving`);
+        }
+        throw error;
+    }
     return ok(`Cache saved with key: ${key} (${files.length} file(s))`);
 }
 /** `actions/cache`, `actions/cache/restore` and `actions/cache/save`. */