@secureci/cli 0.3.0 → 0.5.0

package/README.md

@@ -71,7 +71,8 @@ secureci inventory --check    # fail on drift (use in CI)
   is checked against it, locally and in CI.
 - **Supply-chain visibility** — [`secureci inventory`](DOCS.md#action-inventory-and-drift-secureci-inventory)
   with a committed lockfile turns a silently moved action tag into a failing
-  check.
+  check, including tags inside the actions you use, and catches a locked
+  repository that was deleted and re-created.
 - **Machine-readable output** — `--format json|sarif` drops straight into CI and
   GitHub code scanning.
 - **Audit evidence** — the contract, `secureci.lock` and reports are plain files

package/dist/cli.js

@@ -38,6 +38,7 @@ const commander_1 = require("commander");
 const dry_run_1 = require("./runner/dry-run");
 const executor_1 = require("./runner/executor");
 const action_fetcher_1 = require("./runner/action-fetcher");
+const contract_source_1 = require("./contract-source");
 const validator_1 = require("./parser/validator");
 const workflow_parser_1 = require("./parser/workflow-parser");
 const pipeline_contract_parser_1 = require("./parser/pipeline-contract-parser");
@@ -190,7 +191,7 @@ program
 });
 program
     .command('inventory')
-    .description('List the actions and reusable workflows a workflow uses (resolved into called workflows/actions), with their commit SHAs; track supply-chain drift with a committed secureci.lock')
+    .description('List the actions and reusable workflows a workflow uses (including the actions those actions use), with their commit SHAs; track supply-chain drift with a committed secureci.lock')
     .argument('[file...]', 'Workflow files (default: every file in .github/workflows)')
     .option('--offline', 'Do not resolve tags to commit SHAs over the network (already-pinned refs still resolve)')
     .option('--dry-run', `Print the resolved inventory as JSON without writing or checking ${LOCKFILE_NAME}`)
@@ -271,11 +272,71 @@ async function runInventory(files, options) {
             process.exit(1);
         }
     }
-    const actions = [...byUses.values()].sort((a, b) => a.uses.localeCompare(b.uses));
+    // Download progress would corrupt --dry-run's JSON on stdout; warnings
+    // still go to stderr.
+    if (options.dryRun)
+        logger_1.logger.setLevel(logger_1.LogLevel.WARN);
+    // Follow remote composite actions and reusable workflows into the
+    // actions they use, downloaded at the resolved commit.
+    const actions = (await (0, inventory_1.addTransitive)([...byUses.values()], {
+        resolveSha: resolver,
+        fetch: (uses, kind) => kind === 'action'
+            ? (0, action_fetcher_1.fetchAction)(uses, { offline: options.offline })
+            : (0, action_fetcher_1.fetchRepoFile)(uses, { offline: options.offline }),
+        warn: (message) => logger_1.logger.warn(message)
+    })).sort((a, b) => a.uses.localeCompare(b.uses));
+    const lockPath = path.join(process.cwd(), LOCKFILE_NAME);
+    // secureci.lock is first-class; GitHub's actions.lock is used only when
+    // it is the lockfile the repository provides.
+    const source = (0, github_lockfile_1.findLockfile)(process.cwd());
+    // `--update-lock`, or bare `inventory` when no lockfile exists yet,
+    // writes the lock; otherwise (`--check`, or bare `inventory` with a
+    // lockfile) compares against it.
+    const writing = update || (!check && !source);
+    let lock;
+    const github = source?.kind === 'github';
+    const lockName = github ? 'actions.lock' : LOCKFILE_NAME;
+    if (!writing && !options.dryRun) {
+        if (!source) {
+            logger_1.logger.error(`No ${LOCKFILE_NAME} found (or GitHub's ${github_lockfile_1.GITHUB_LOCKFILE}). Create one with: secureci inventory --update-lock`);
+            process.exit(1);
+        }
+        try {
+            lock = (0, github_lockfile_1.readLockfile)(source);
+        }
+        catch (error) {
+            logger_1.logger.error(`Could not read ${lockName}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            process.exit(1);
+        }
+    }
+    // Repository identity: recorded when writing; when checking, looked up
+    // only for repositories the lock has an identity for.
+    if (!options.offline) {
+        const lookups = new Map();
+        for (const action of actions) {
+            if (!action.resolvedSha)
+                continue;
+            if (lock && lock.actions[action.uses]?.repoId === undefined)
+                continue;
+            const key = `${action.owner}/${action.repo}`.toLowerCase();
+            if (!lookups.has(key)) {
+                lookups.set(key, (0, action_fetcher_1.resolveRepoIdentity)(action.owner, action.repo));
+            }
+            const identity = await lookups.get(key);
+            if (identity)
+                Object.assign(action, identity);
+        }
+    }
     const current = {};
     for (const action of actions) {
-        if (action.resolvedSha)
-            current[action.uses] = action.resolvedSha;
+        if (!action.resolvedSha)
+            continue;
+        current[action.uses] = {
+            commit: action.resolvedSha,
+            ...(action.ownerId !== undefined ? { ownerId: action.ownerId } : {}),
+            ...(action.repoId !== undefined ? { repoId: action.repoId } : {}),
+            ...(action.via ? { via: action.via } : {})
+        };
     }
     // --dry-run: print the resolved inventory as JSON, touching nothing.
     if (options.dryRun) {
@@ -283,50 +344,35 @@ async function runInventory(files, options) {
         console.log(JSON.stringify({ actions }, null, 2));
         return;
     }
-    const lockPath = path.join(process.cwd(), LOCKFILE_NAME);
-    // secureci.lock is first-class; GitHub's actions.lock is used only when
-    // it is the lockfile the repository provides.
-    const source = (0, github_lockfile_1.findLockfile)(process.cwd());
-    const writeLock = () => {
-        const updated = { version: 1, actions: current };
-        fs.writeFileSync(lockPath, JSON.stringify(updated, null, 2) + '\n');
-        logger_1.logger.success(`Wrote ${Object.keys(current).length} action(s) to ${LOCKFILE_NAME}. Commit it to track supply-chain drift.`);
-    };
-    // `--update-lock`, or bare `inventory` when no lockfile exists yet: write it.
-    if (update || (!check && !source)) {
-        writeLock();
+    if (writing) {
+        fs.writeFileSync(lockPath, (0, github_lockfile_1.serializeSecureciLockfile)(current));
+        const transitive = Object.values(current).filter((e) => e.via).length;
+        logger_1.logger.success(`Wrote ${Object.keys(current).length} action(s) to ${LOCKFILE_NAME}` +
+            (transitive > 0 ? ` (${transitive} used by other actions)` : '') +
+            '. Commit it to track supply-chain drift.');
         return;
     }
-    // Otherwise compare (explicit `--check`, or bare `inventory` with a lockfile).
-    if (!source) {
-        logger_1.logger.error(`No ${LOCKFILE_NAME} found (or GitHub's ${github_lockfile_1.GITHUB_LOCKFILE}). Create one with: secureci inventory --update-lock`);
-        process.exit(1);
-    }
-    const github = source.kind === 'github';
-    const lockName = github ? 'actions.lock' : LOCKFILE_NAME;
     const fixHint = github
         ? 'run `gh actions-lock` to update actions.lock'
         : 'run with --update-lock to accept it';
-    let lock;
-    try {
-        const text = fs.readFileSync(source.file, 'utf-8');
-        lock = github ? (0, github_lockfile_1.parseGitHubLockfile)(text) : JSON.parse(text);
-    }
-    catch (error) {
-        logger_1.logger.error(`Could not read ${lockName}: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        process.exit(1);
-    }
     logger_1.logger.info(`Checking against ${github ? github_lockfile_1.GITHUB_LOCKFILE : LOCKFILE_NAME}`);
     const diff = (0, inventory_1.diffLock)(current, lock);
     for (const d of diff.drifted) {
         logger_1.logger.error(`Drift: ${d.uses} now resolves to ${d.to.slice(0, 12)} (was ${d.from.slice(0, 12)})`);
     }
+    for (const d of diff.identity) {
+        logger_1.logger.error(`Repository changed: ${d.uses} ${d.field} is now ${d.to} (was ${d.from}). The name now points at a different ${d.field === 'repo_id' ? 'repository (deleted and re-created?)' : 'owner (transferred, or the account re-registered?)'}.`);
+    }
     diff.added.forEach((u) => logger_1.logger.warn(`New action not in ${lockName}: ${u}`));
-    // actions.lock also records transitive dependencies, which SecureCI
-    // doesn't scan, so "no longer used" only means something for secureci.lock.
+    // actions.lock is written by `gh actions-lock`, which may record entries
+    // SecureCI doesn't follow, so "no longer used" is only for secureci.lock.
     if (!github) {
         diff.removed.forEach((u) => logger_1.logger.info(`In ${lockName} but no longer used: ${u}`));
     }
+    if (diff.identity.length > 0) {
+        logger_1.logger.error(`A locked repository is no longer the one that was locked. Verify it before trusting it, then ${fixHint}.`);
+        process.exit(1);
+    }
     if (diff.drifted.length > 0) {
         logger_1.logger.error(`Action commits drifted from ${lockName}. Review the change, then ${fixHint}.`);
         process.exit(1);
@@ -384,10 +430,42 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
         if (!quiet)
             fn();
     };
+    // A contract may be a local file or `owner/repo/path@ref` in another
+    // repository; resolve it once and record which version was enforced.
+    let contractPath = contractFile;
+    let contract;
+    let contractError;
+    if (contractFile) {
+        try {
+            const source = await (0, contract_source_1.resolveContractSource)(contractFile, {
+                fetchFile: (uses) => (0, action_fetcher_1.fetchRepoFile)(uses),
+                resolveSha: (uses) => (0, action_fetcher_1.resolveActionSha)(uses),
+                warn: (message) => logger_1.logger.warn(message)
+            });
+            contractPath = source.file;
+            const remote = source.remote;
+            contract = remote
+                ? {
+                    source: remote.uses,
+                    ref: remote.ref,
+                    commit: remote.commit,
+                    pinned: remote.pinned
+                }
+                : { source: contractFile };
+            if (remote) {
+                say(() => logger_1.logger.info(`Using contract ${remote.uses}${remote.commit ? ` at commit ${remote.commit.slice(0, 12)}` : ''}`));
+            }
+        }
+        catch (error) {
+            contractError = error instanceof Error ? error.message : 'Unknown error';
+        }
+    }
     const entries = [];
     for (const filePath of files) {
         try {
-            const result = await validateOneFile(filePath, contractFile, recurse, say);
+            if (contractError)
+                throw new Error(contractError);
+            const result = await validateOneFile(filePath, contractPath, recurse, say);
             entries.push({ file: filePath, result });
         }
         catch (error) {
@@ -409,7 +487,7 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
     const allValid = entries.every((e) => e.result.valid);
     if (quiet) {
         // eslint-disable-next-line no-console
-        console.log((0, report_1.formatReport)(entries, format));
+        console.log((0, report_1.formatReport)(entries, format, { contract }));
         if (!allValid)
             process.exit(1);
         return;

package/dist/contract-source.js

@@ -0,0 +1,63 @@
+"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.resolveContractSource = resolveContractSource;
+const fs = __importStar(require("fs"));
+// owner/repo/path/to/file@ref: the same form as a remote reusable workflow.
+const REMOTE_CONTRACT = /^[^/.][^/]*\/[^/@]+\/[^@]+@([^@]+)$/;
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/**
+ * Where to read `--contract` from. An existing local file always wins;
+ * otherwise `owner/repo/path@ref` is fetched like a remote reusable workflow.
+ * A ref that isn't a commit SHA can change under you, so it warns.
+ */
+async function resolveContractSource(value, deps) {
+    if (fs.existsSync(value))
+        return { file: value };
+    const match = REMOTE_CONTRACT.exec(value);
+    if (!match)
+        throw new Error(`Contract file not found: ${value}`);
+    const ref = match[1];
+    const pinned = FULL_SHA.test(ref);
+    if (!pinned) {
+        deps.warn(`Contract ${value} uses the moving ref "${ref}": its owner can change the standard without a change in this repository. Pin it to a commit SHA to control when it changes.`);
+    }
+    const file = await deps.fetchFile(value);
+    if (!file)
+        throw new Error(`Could not fetch contract ${value}`);
+    const commit = pinned ? ref : await deps.resolveSha(value);
+    return { file, remote: { uses: value, ref, commit, pinned } };
+}
+//# sourceMappingURL=contract-source.js.map

package/dist/github-lockfile.js

@@ -36,6 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GITHUB_LOCKFILE = exports.SECURECI_LOCKFILE = void 0;
 exports.findLockfile = findLockfile;
 exports.parseGitHubLockfile = parseGitHubLockfile;
+exports.parseSecureciLockfile = parseSecureciLockfile;
+exports.serializeSecureciLockfile = serializeSecureciLockfile;
+exports.readLockfile = readLockfile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const YAML = __importStar(require("yaml"));
@@ -66,10 +69,23 @@ function findLockfile(repoRoot) {
         return { kind: 'github', file: github };
     return undefined;
 }
+/** A positive integer id, or undefined. */
+function id(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0
+        ? value
+        : undefined;
+}
+function entry(commit, ownerId, repoId, via) {
+    return {
+        commit,
+        ...(ownerId !== undefined ? { ownerId } : {}),
+        ...(repoId !== undefined ? { repoId } : {}),
+        ...(via && via.length > 0 ? { via } : {})
+    };
+}
 /**
- * Read GitHub's `actions.lock` as a `uses -> commit` map, the same shape as
- * `secureci.lock`. It includes transitive dependencies (actions that your
- * actions use), which SecureCI doesn't scan.
+ * Read GitHub's `actions.lock`: each dependency's commit and repository
+ * identity (`owner_id`, `repo_id`). It includes transitive dependencies.
  */
 function parseGitHubLockfile(text) {
     const doc = YAML.parse(text);
@@ -83,8 +99,62 @@ function parseGitHubLockfile(text) {
         if (!match) {
             throw new Error(`actions.lock entry ${uses} has no sha1 commit (got "${String(dep?.commit)}").`);
         }
-        actions[uses] = match[1];
+        actions[uses] = entry(match[1], id(dep?.owner_id), id(dep?.repo_id));
     }
-    return { version: 1, actions };
+    return { version: 2, actions };
+}
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/**
+ * Read `secureci.lock`. Version 1 maps each reference to a commit; version
+ * 2 maps it to `{ commit, owner_id?, repo_id?, via? }`.
+ */
+function parseSecureciLockfile(text) {
+    const doc = JSON.parse(text);
+    const raw = (doc?.actions ?? {});
+    const actions = {};
+    const bad = (uses) => new Error(`${exports.SECURECI_LOCKFILE} entry ${uses} has no valid commit.`);
+    if (doc?.version === 1) {
+        for (const [uses, commit] of Object.entries(raw)) {
+            if (typeof commit !== 'string' || !FULL_SHA.test(commit))
+                throw bad(uses);
+            actions[uses] = { commit };
+        }
+        return { version: 1, actions };
+    }
+    if (doc?.version === 2) {
+        for (const [uses, value] of Object.entries(raw)) {
+            const e = (value ?? {});
+            if (typeof e.commit !== 'string' || !FULL_SHA.test(e.commit)) {
+                throw bad(uses);
+            }
+            const via = Array.isArray(e.via)
+                ? e.via.filter((v) => typeof v === 'string')
+                : undefined;
+            actions[uses] = entry(e.commit, id(e.owner_id), id(e.repo_id), via);
+        }
+        return { version: 2, actions };
+    }
+    throw new Error(`Unsupported ${exports.SECURECI_LOCKFILE} version "${String(doc?.version)}". Update @secureci/cli.`);
+}
+/** `secureci.lock` (version 2) for these entries, keys sorted. */
+function serializeSecureciLockfile(actions) {
+    const out = {};
+    for (const uses of Object.keys(actions).sort()) {
+        const e = actions[uses];
+        out[uses] = {
+            commit: e.commit,
+            ...(e.ownerId !== undefined ? { owner_id: e.ownerId } : {}),
+            ...(e.repoId !== undefined ? { repo_id: e.repoId } : {}),
+            ...(e.via && e.via.length > 0 ? { via: e.via } : {})
+        };
+    }
+    return JSON.stringify({ version: 2, actions: out }, null, 2) + '\n';
+}
+/** Read whichever lockfile `findLockfile` found. */
+function readLockfile(source) {
+    const text = fs.readFileSync(source.file, 'utf-8');
+    return source.kind === 'github'
+        ? parseGitHubLockfile(text)
+        : parseSecureciLockfile(text);
 }
 //# sourceMappingURL=github-lockfile.js.map

package/dist/inventory.js

@@ -35,8 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectReferences = collectReferences;
 exports.buildInventory = buildInventory;
+exports.addTransitive = addTransitive;
 exports.diffLock = diffLock;
-exports.lockEntries = lockEntries;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const workflow_parser_1 = require("./parser/workflow-parser");
@@ -70,8 +70,13 @@ function classify(uses, kind) {
  * actions (`./path`) and local reusable workflows (`jobs.<id>.uses: ./x.yml`)
  * so wrapped references are still listed. Remote references are listed but
  * not followed. Order is the walk order; each carries its call path.
+ *
+ * Also takes a composite action (its steps). `localActions: false` lists
+ * but doesn't follow `./` actions: in a downloaded action or workflow they
+ * resolve against whatever the caller checked out, which isn't known here.
  */
-function collectReferences(parsed) {
+function collectReferences(parsed, options = {}) {
+    const followLocalActions = options.localActions ?? true;
     const root = (0, repository_1.repositoryRoot)(parsed.path);
     const refs = [];
     const resolveLocal = (uses, names) => {
@@ -92,7 +97,7 @@ function collectReferences(parsed) {
             return;
         const ref = classify(step.uses, 'action');
         refs.push({ ...ref, path: at });
-        if (!isLocal(step.uses))
+        if (!isLocal(step.uses) || !followLocalActions)
             return;
         const file = resolveLocal(step.uses, ['action.yml', 'action.yaml']);
         if (!file || stack.includes(file) || stack.length >= MAX_DEPTH)
@@ -137,7 +142,12 @@ function collectReferences(parsed) {
             (job.steps ?? []).forEach((step, i) => addStep(step, `${jobPath}.steps[${i}]`, stack));
         }
     };
-    addWorkflow(parsed.file, '', [path.resolve(parsed.path)]);
+    if (parsed.type === 'workflow') {
+        addWorkflow(parsed.file, '', [path.resolve(parsed.path)]);
+    }
+    else if (parsed.file.runs.using === 'composite') {
+        (parsed.file.runs.steps ?? []).forEach((s, i) => addStep(s, `steps[${i}]`, [path.resolve(parsed.path)]));
+    }
     return refs;
 }
 /**
@@ -150,22 +160,10 @@ async function buildInventory(parsed, resolveSha) {
     const remote = references.filter((r) => r.kind === 'action' || r.kind === 'reusable-workflow');
     const byUses = new Map();
     for (const ref of remote) {
-        if (!ref.owner || !ref.repo)
+        const action = byUses.get(ref.uses) ?? toAction(ref);
+        if (!action)
             continue;
-        let action = byUses.get(ref.uses);
-        if (!action) {
-            action = {
-                uses: ref.uses,
-                owner: ref.owner,
-                repo: ref.repo,
-                subpath: ref.subpath,
-                ref: ref.ref,
-                pinned: ref.pinned,
-                resolvedSha: ref.ref && FULL_SHA.test(ref.ref) ? ref.ref.toLowerCase() : undefined,
-                paths: []
-            };
-            byUses.set(ref.uses, action);
-        }
+        byUses.set(ref.uses, action);
         action.paths.push(ref.path);
     }
     if (resolveSha) {
@@ -181,32 +179,117 @@ async function buildInventory(parsed, resolveSha) {
         references
     };
 }
-/** Compare current `uses -> sha` against a lockfile's recorded commits. */
+/** A remote reference as an inventory entry (no paths yet), or null. */
+function toAction(ref) {
+    if (!ref.owner || !ref.repo)
+        return null;
+    if (ref.kind !== 'action' && ref.kind !== 'reusable-workflow')
+        return null;
+    return {
+        uses: ref.uses,
+        kind: ref.kind,
+        owner: ref.owner,
+        repo: ref.repo,
+        subpath: ref.subpath,
+        ref: ref.ref,
+        pinned: ref.pinned,
+        resolvedSha: ref.ref && FULL_SHA.test(ref.ref) ? ref.ref.toLowerCase() : undefined,
+        paths: []
+    };
+}
+/**
+ * The inventory plus every transitive dependency: remote composite actions
+ * and remote reusable workflows are downloaded at their resolved commit
+ * (so what's read is what's locked) and their own `uses:` added, up to
+ * MAX_DEPTH levels. A dependency records `via`, the references that pull it
+ * in. Node and Docker actions have no `uses:` to follow.
+ */
+async function addTransitive(direct, deps) {
+    const byUses = new Map(direct.map((a) => [a.uses, a]));
+    const queue = direct.map((action) => ({ action, depth: 1 }));
+    while (queue.length > 0) {
+        const { action, depth } = queue.shift();
+        const at = action.resolvedSha ?? action.ref;
+        if (!at || depth > MAX_DEPTH)
+            continue;
+        const name = [action.owner, action.repo, action.subpath]
+            .filter(Boolean)
+            .join('/');
+        const file = await deps.fetch(`${name}@${at}`, action.kind);
+        let parsed;
+        try {
+            parsed = file ? (0, workflow_parser_1.parseFile)(file) : undefined;
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!parsed) {
+            deps.warn(`Could not read ${action.uses}, so the actions it uses are not listed.`);
+            continue;
+        }
+        for (const ref of collectReferences(parsed, { localActions: false })) {
+            const refPath = `${action.uses} > ${ref.path}`;
+            const known = byUses.get(ref.uses);
+            if (known) {
+                known.paths.push(refPath);
+                if (known.via && !known.via.includes(action.uses)) {
+                    known.via = [...known.via, action.uses].sort();
+                }
+                continue;
+            }
+            const dep = toAction(ref);
+            if (!dep)
+                continue;
+            dep.paths.push(refPath);
+            dep.via = [action.uses];
+            if (!dep.resolvedSha && deps.resolveSha) {
+                dep.resolvedSha = await deps.resolveSha(dep.uses);
+            }
+            byUses.set(dep.uses, dep);
+            queue.push({ action: dep, depth: depth + 1 });
+        }
+    }
+    return [...byUses.values()];
+}
+/**
+ * Compare the current entries against a lockfile: moved commits, new and
+ * removed refs, and repositories whose identity changed (compared only
+ * when both sides know it).
+ */
 function diffLock(current, lock) {
     const drifted = [];
+    const identity = [];
     const added = [];
-    for (const [uses, sha] of Object.entries(current)) {
+    for (const [uses, entry] of Object.entries(current)) {
         const known = lock.actions[uses];
-        if (known === undefined)
+        if (known === undefined) {
             added.push(uses);
-        else if (known !== sha)
-            drifted.push({ uses, from: known, to: sha });
+            continue;
+        }
+        if (known.commit !== entry.commit) {
+            drifted.push({ uses, from: known.commit, to: entry.commit });
+        }
+        for (const [field, key] of [
+            ['owner_id', 'ownerId'],
+            ['repo_id', 'repoId']
+        ]) {
+            const from = known[key];
+            const to = entry[key];
+            if (from !== undefined && to !== undefined && from !== to) {
+                identity.push({ uses, field, from, to });
+            }
+        }
     }
     const removed = Object.keys(lock.actions).filter((uses) => !(uses in current));
     return {
-        changed: drifted.length > 0 || added.length > 0 || removed.length > 0,
+        changed: drifted.length > 0 ||
+            added.length > 0 ||
+            removed.length > 0 ||
+            identity.length > 0,
         drifted,
         added: added.sort(),
-        removed: removed.sort()
+        removed: removed.sort(),
+        identity
     };
 }
-/** The `uses -> resolvedSha` map an inventory contributes to a lockfile. */
-function lockEntries(inv) {
-    const entries = {};
-    for (const action of inv.actions) {
-        if (action.resolvedSha)
-            entries[action.uses] = action.resolvedSha;
-    }
-    return entries;
-}
 //# sourceMappingURL=inventory.js.map

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

@@ -96,6 +96,21 @@ function parsePipelineContract(filePath) {
             result.pins.allow = parseStringList(pins.allow, 'pins.allow');
         }
     }
+    if (spec.lockfile !== undefined) {
+        if (typeof spec.lockfile !== 'object' ||
+            spec.lockfile === null ||
+            Array.isArray(spec.lockfile)) {
+            throw new Error('Contract "lockfile" must be a mapping');
+        }
+        const lockfile = spec.lockfile;
+        result.lockfile = {};
+        if (lockfile.required !== undefined) {
+            if (typeof lockfile.required !== 'boolean') {
+                throw new Error('Contract "lockfile.required" must be true or false');
+            }
+            result.lockfile.required = lockfile.required;
+        }
+    }
     if (spec['allowed-owners'] !== undefined) {
         result.allowedOwners = parseStringList(spec['allowed-owners'], 'allowed-owners');
     }

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

@@ -40,6 +40,7 @@ const job_plan_1 = require("../runner/job-plan");
 const workflow_parser_1 = require("./workflow-parser");
 const repository_1 = require("../utils/repository");
 const action_fetcher_1 = require("../runner/action-fetcher");
+const github_lockfile_1 = require("../github-lockfile");
 /** Maximum nesting of composite actions / reusable workflows. */
 const MAX_DEPTH = 10;
 /**
@@ -195,11 +196,55 @@ async function validatePipelineContract(parsed, spec, options = {}) {
             }
         }
     }
+    if (spec.lockfile?.required) {
+        errors.push(...checkLockfile(parsed, sequence.filter(isRemote)));
+    }
     return {
         valid: errors.every((e) => e.severity !== 'error'),
         errors
     };
 }
+/**
+ * `lockfile.required`: the repository commits a lockfile (secureci.lock,
+ * else GitHub's actions.lock) and it lists every remote reference used.
+ * Offline: whether the locked commits still match is `inventory --check`.
+ */
+function checkLockfile(parsed, remote) {
+    const source = (0, github_lockfile_1.findLockfile)((0, repository_1.repositoryRoot)(parsed.path));
+    if (!source) {
+        return [
+            {
+                path: 'lockfile',
+                message: 'The contract requires a lockfile, but the repository has no secureci.lock (or .github/workflows/actions.lock). Create one with: secureci inventory --update-lock',
+                severity: 'error'
+            }
+        ];
+    }
+    const name = path.basename(source.file);
+    let locked;
+    try {
+        locked = new Set(Object.keys((0, github_lockfile_1.readLockfile)(source).actions).map((uses) => {
+            const { name: n, version } = splitActionRef(uses);
+            return version === undefined ? n : `${n}@${version}`;
+        }));
+    }
+    catch (error) {
+        return [
+            {
+                path: 'lockfile',
+                message: `Could not read ${name}: ${error instanceof Error ? error.message : String(error)}`,
+                severity: 'error'
+            }
+        ];
+    }
+    return remote
+        .filter((u) => !locked.has(`${u.name}@${u.version}`))
+        .map((u) => ({
+        path: u.path,
+        message: `Action "${u.name}${u.version ? '@' + u.version : ''}" is not in ${name}; lock it with ${source.kind === 'github' ? '`gh actions-lock`' : '`secureci inventory --update-lock`'}`,
+        severity: 'error'
+    }));
+}
 /** Whether job `from` (transitively) needs job `to`. */
 function needsTransitively(nodes, from, to) {
     const seen = new Set();

package/dist/report.js

@@ -41,13 +41,15 @@ function sarifResults(entry) {
  * carrying every file's findings, suitable for GitHub code scanning (upload
  * with `github/codeql-action/upload-sarif`).
  */
-function formatReport(entries, format) {
+function formatReport(entries, format, meta = {}) {
+    const contract = meta.contract ? { contract: meta.contract } : {};
     if (format === 'json') {
         const body = entries.length === 1
-            ? jsonForFile(entries[0])
+            ? { ...jsonForFile(entries[0]), ...contract }
             : {
                 valid: entries.every((e) => e.result.valid),
-                files: entries.map(jsonForFile)
+                files: entries.map(jsonForFile),
+                ...contract
             };
         return JSON.stringify(body, null, 2);
     }
@@ -63,7 +65,8 @@ function formatReport(entries, format) {
                         rules: Object.entries(RULES).map(([id, name]) => ({ id, name }))
                     }
                 },
-                results: entries.flatMap(sarifResults)
+                results: entries.flatMap(sarifResults),
+                ...(meta.contract ? { properties: contract } : {})
             }
         ]
     }, null, 2);

package/dist/runner/action-fetcher.js

@@ -42,6 +42,7 @@ exports.fetchAction = fetchAction;
 exports.fetchRepoFile = fetchRepoFile;
 exports.clearActionCache = clearActionCache;
 exports.resolveActionSha = resolveActionSha;
+exports.resolveRepoIdentity = resolveRepoIdentity;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const http = __importStar(require("http"));
@@ -428,4 +429,34 @@ async function resolveActionSha(uses, options = {}) {
     }
     return undefined;
 }
+/**
+ * GitHub's numeric ids for a repository and its owner, from the REST API,
+ * or undefined if they can't be looked up (offline, rate-limited, gone).
+ * The ids survive a rename but not a delete-and-recreate, so a changed id
+ * means a different repository now answers to the same name.
+ */
+async function resolveRepoIdentity(owner, repo, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DOWNLOAD_TIMEOUT_MS;
+    const token = options.token === undefined ? githubToken() : options.token;
+    const lookup = async (auth) => {
+        try {
+            const body = JSON.parse(await getText(`${apiUrl()}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`, { ...requestHeaders(auth), Accept: 'application/vnd.github+json' }, timeoutMs));
+            const repoId = body.id;
+            const ownerId = body.owner?.id;
+            return typeof repoId === 'number' && typeof ownerId === 'number'
+                ? { identity: { ownerId, repoId } }
+                : {};
+        }
+        catch (error) {
+            return { unauthorized: error.status === 401 };
+        }
+    };
+    const first = await lookup(token);
+    if (first.identity)
+        return first.identity;
+    // A rejected token shouldn't block the lookup: retry anonymously.
+    if (token && first.unauthorized)
+        return (await lookup(null)).identity;
+    return undefined;
+}
 //# sourceMappingURL=action-fetcher.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secureci/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SecureCI: validate, check against pipeline standards, and run GitHub Actions workflows locally",
   "main": "dist/index.js",
   "bin": {