@secureci/cli 0.4.0 → 0.5.1

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 progress_1 = require("./utils/progress");
 const contract_source_1 = require("./contract-source");
 const validator_1 = require("./parser/validator");
 const workflow_parser_1 = require("./parser/workflow-parser");
@@ -191,7 +192,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}`)
@@ -248,9 +249,6 @@ async function runInventory(files, options) {
         process.exit(1);
     }
     targets.forEach(requireFile);
-    const resolver = options.offline
-        ? undefined
-        : (uses) => (0, action_fetcher_1.resolveActionSha)(uses);
     // Merge every file's remote actions by `uses`.
     const byUses = new Map();
     for (const file of targets) {
@@ -258,7 +256,11 @@ async function runInventory(files, options) {
             const parsed = (0, workflow_parser_1.parseFile)(file);
             if (parsed.type !== 'workflow')
                 continue;
-            const inv = await (0, inventory_1.buildInventory)({ type: 'workflow', path: file, file: parsed.file }, resolver);
+            const inv = await (0, inventory_1.buildInventory)({
+                type: 'workflow',
+                path: file,
+                file: parsed.file
+            });
             for (const action of inv.actions) {
                 const existing = byUses.get(action.uses);
                 if (existing)
@@ -272,11 +274,119 @@ async function runInventory(files, options) {
             process.exit(1);
         }
     }
-    const actions = [...byUses.values()].sort((a, b) => a.uses.localeCompare(b.uses));
+    const direct = [...byUses.values()];
+    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);
+    const comparing = !writing && !options.dryRun;
+    let lock;
+    const github = source?.kind === 'github';
+    const lockName = github ? 'actions.lock' : LOCKFILE_NAME;
+    if (comparing) {
+        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);
+        }
+    }
+    // Download messages would corrupt --dry-run's JSON on stdout and clash
+    // with the progress lines; warnings and errors still go to stderr.
+    const level = logger_1.logger.getLevel();
+    if (level === logger_1.LogLevel.INFO)
+        logger_1.logger.setLevel(logger_1.LogLevel.WARN);
+    const online = !options.offline;
+    if (online && direct.length > 0) {
+        process.stderr.write(`Resolving ${direct.length} action(s) over the network, and reading the actions they use. This can take a while (--offline uses only what is cached).\n`);
+    }
+    // 1. Resolve each tag or branch to the commit it points at.
+    const toResolve = online ? direct.filter((a) => !a.resolvedSha) : [];
+    const resolving = new progress_1.Progress('Resolving tags', toResolve.length);
+    for (const action of toResolve) {
+        resolving.tick(action.uses);
+        action.resolvedSha = await (0, action_fetcher_1.resolveActionSha)(action.uses);
+    }
+    resolving.done(`Resolved ${toResolve.length} tag(s)`);
+    // 2. Follow remote composite actions and reusable workflows into the
+    // actions they use, downloaded at the resolved commit.
+    const reading = new progress_1.Progress('Reading actions', online ? direct.length : 0);
+    let read = 0;
+    const actions = (await (0, inventory_1.addTransitive)(direct, {
+        resolveSha: online ? (uses) => (0, action_fetcher_1.resolveActionSha)(uses) : undefined,
+        fetch: (uses, kind) => {
+            if (online)
+                reading.tick(uses.replace(/@([0-9a-f]{12})[0-9a-f]{28}$/, '@$1'));
+            read++;
+            return 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),
+        onQueue: () => reading.grow()
+    })).sort((a, b) => a.uses.localeCompare(b.uses));
+    reading.done(`Read ${read} action(s) for the actions they use`);
+    const repos = new Map();
+    if (online) {
+        for (const action of actions) {
+            if (!action.resolvedSha)
+                continue;
+            const identity = !lock || lock.actions[action.uses]?.repoId !== undefined;
+            const existence = comparing && action.pinned;
+            if (!identity && !existence)
+                continue;
+            const key = `${action.owner}/${action.repo}`.toLowerCase();
+            const entry = repos.get(key) ?? {
+                owner: action.owner,
+                repo: action.repo,
+                identity: false,
+                existence: false
+            };
+            entry.identity || (entry.identity = identity);
+            entry.existence || (entry.existence = existence);
+            repos.set(key, entry);
+        }
+    }
+    const identities = new Map();
+    const missingRepos = new Set();
+    const checking = new progress_1.Progress('Checking repositories', repos.size);
+    for (const [key, r] of repos) {
+        checking.tick(`${r.owner}/${r.repo}`);
+        const identity = r.identity
+            ? await (0, action_fetcher_1.resolveRepoIdentity)(r.owner, r.repo)
+            : undefined;
+        if (identity)
+            identities.set(key, identity);
+        else if (r.existence && !(await (0, action_fetcher_1.repoExists)(r.owner, r.repo))) {
+            missingRepos.add(key);
+        }
+    }
+    checking.done(`Checked ${repos.size} repositor${repos.size === 1 ? 'y' : 'ies'}`);
+    for (const action of actions) {
+        const identity = identities.get(`${action.owner}/${action.repo}`.toLowerCase());
+        if (identity && action.resolvedSha)
+            Object.assign(action, identity);
+    }
+    logger_1.logger.setLevel(level);
     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) {
@@ -284,49 +394,64 @@ 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();
+    // Used references that couldn't be resolved to a commit now.
+    const unresolved = actions.filter((a) => !a.resolvedSha);
+    if (writing) {
+        if (online) {
+            unresolved.forEach((a) => logger_1.logger.warn(`Not locked: could not resolve ${a.uses} (repository deleted, renamed or private, or the network is unavailable?)`));
+        }
+        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?)'}.`);
+    }
+    for (const a of actions) {
+        if (missingRepos.has(`${a.owner}/${a.repo}`.toLowerCase())) {
+            logger_1.logger.error(`Repository gone: ${a.uses} can no longer be read (deleted, renamed or made private?). The locked commit can't be fetched, and the name could be re-registered by someone else.`);
+        }
+    }
+    // Online, a used reference that doesn't resolve is a failure (its
+    // repository may be gone); offline, tags can't resolve, so it's a warning.
+    for (const a of unresolved) {
+        const locked = lock?.actions[a.uses];
+        const at = locked ? ` (locked at ${locked.commit.slice(0, 12)})` : '';
+        if (online) {
+            logger_1.logger.error(`Could not resolve ${a.uses}${at}: the repository or ref may have been deleted, renamed or made private, or the network is unavailable.`);
+        }
+    }
+    if (!online && unresolved.length > 0) {
+        logger_1.logger.warn(`Not checked offline (tags need the network): ${unresolved.map((a) => a.uses).join(', ')}`);
+    }
     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.
+    // A reference still in use but unresolved isn't "no longer used".
     if (!github) {
-        diff.removed.forEach((u) => logger_1.logger.info(`In ${lockName} but no longer used: ${u}`));
+        const used = new Set(unresolved.map((a) => a.uses));
+        diff.removed
+            .filter((u) => !used.has(u))
+            .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 (missingRepos.size > 0 || (online && unresolved.length > 0)) {
+        logger_1.logger.error(`Locked actions could not be verified. Check that each repository and ref still exists and is readable${(0, action_fetcher_1.githubToken)() ? '' : ' (set GITHUB_TOKEN for private repositories)'}.`);
+        process.exit(1);
     }
     if (diff.drifted.length > 0) {
         logger_1.logger.error(`Action commits drifted from ${lockName}. Review the change, then ${fixHint}.`);

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,118 @@ 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 });
+            deps.onQueue?.(dep);
+        }
+    }
+    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/runner/action-fetcher.js

@@ -42,6 +42,9 @@ exports.fetchAction = fetchAction;
 exports.fetchRepoFile = fetchRepoFile;
 exports.clearActionCache = clearActionCache;
 exports.resolveActionSha = resolveActionSha;
+exports.resolveRepoIdentity = resolveRepoIdentity;
+exports.lsRemoteReachable = lsRemoteReachable;
+exports.repoExists = repoExists;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const http = __importStar(require("http"));
@@ -428,4 +431,69 @@ 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;
+}
+/** Whether `git ls-remote` can read the repository at `url`. */
+async function lsRemoteReachable(url) {
+    try {
+        await execFileAsync('git', ['ls-remote', url, 'HEAD'], {
+            encoding: 'utf8',
+            timeout: 15000,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `owner/repo` can still be read: via the API when a token is
+ * available (404 means no), otherwise (or if the API can't answer) via
+ * anonymous `git ls-remote`. False also when the network is down.
+ */
+async function repoExists(owner, repo, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DOWNLOAD_TIMEOUT_MS;
+    const token = options.token === undefined ? githubToken() : options.token;
+    if (token) {
+        try {
+            await getText(`${apiUrl()}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`, { ...requestHeaders(token), Accept: 'application/vnd.github+json' }, timeoutMs);
+            return true;
+        }
+        catch (error) {
+            if (error.status === 404)
+                return false;
+            // 401, rate limit or network: fall back to anonymous git.
+        }
+    }
+    return lsRemoteReachable(`${serverUrl()}/${owner}/${repo}.git`);
+}
 //# sourceMappingURL=action-fetcher.js.map

package/dist/utils/logger.js

@@ -17,6 +17,16 @@ class Logger {
     setLevel(level) {
         this.level = level;
     }
+    getLevel() {
+        return this.level;
+    }
+    /**
+     * Run `hook` before each message is written (e.g. to clear an in-place
+     * progress line); undefined removes it.
+     */
+    setBeforeWrite(hook) {
+        this.beforeWrite = hook;
+    }
     /**
      * Register secret values so they get masked (replaced with `***`) in any
      * subsequent log output, mirroring GitHub Actions' own secret masking.
@@ -48,35 +58,42 @@ class Logger {
     }
     debug(message, ...args) {
         if (this.level <= LogLevel.DEBUG) {
+            this.beforeWrite?.();
             console.log(ansi_1.colors.gray(`[DEBUG] ${this.mask(message)}`), ...args.map((a) => this.maskArg(a)));
         }
     }
     info(message, ...args) {
         if (this.level <= LogLevel.INFO) {
+            this.beforeWrite?.();
             console.log(ansi_1.colors.blue(`[INFO] ${this.mask(message)}`), ...args.map((a) => this.maskArg(a)));
         }
     }
     success(message, ...args) {
         if (this.level <= LogLevel.INFO) {
+            this.beforeWrite?.();
             console.log(ansi_1.colors.green(`✓ ${this.mask(message)}`), ...args.map((a) => this.maskArg(a)));
         }
     }
     warn(message, ...args) {
         if (this.level <= LogLevel.WARN) {
+            this.beforeWrite?.();
             console.warn(ansi_1.colors.yellow(`[WARN] ${this.mask(message)}`), ...args.map((a) => this.maskArg(a)));
         }
     }
     error(message, ...args) {
         if (this.level <= LogLevel.ERROR) {
+            this.beforeWrite?.();
             console.error(ansi_1.colors.red(`[ERROR] ${this.mask(message)}`), ...args.map((a) => this.maskArg(a)));
         }
     }
     step(message) {
+        this.beforeWrite?.();
         console.log(ansi_1.colors.cyan(`\n→ ${this.mask(message)}`));
     }
     result(message, success) {
         const icon = success ? '✓' : '✗';
         const color = success ? ansi_1.colors.green : ansi_1.colors.red;
+        this.beforeWrite?.();
         console.log(color(`${icon} ${this.mask(message)}`));
     }
 }

package/dist/utils/progress.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Progress = void 0;
+const logger_1 = require("./logger");
+const CLEAR_LINE = '\r\x1b[K';
+/**
+ * Progress for a slow phase, e.g. resolving actions over the network. On a
+ * terminal it updates one line in place (`Label [3/10] item`); elsewhere
+ * (CI logs) it prints a line per item. The total can grow as work is found.
+ */
+class Progress {
+    constructor(label, total, out = process.stderr) {
+        this.label = label;
+        this.total = total;
+        this.out = out;
+        this.count = 0;
+        this.drawn = false;
+        this.tty = !!out.isTTY;
+        // A log line would otherwise be appended to the half-drawn line.
+        if (this.tty)
+            logger_1.logger.setBeforeWrite(() => this.clear());
+    }
+    /** More items were found to process. */
+    grow(n = 1) {
+        this.total += n;
+    }
+    tick(item) {
+        this.count++;
+        if (this.count > this.total)
+            this.total = this.count;
+        const line = `${this.label} [${this.count}/${this.total}] ${item}`;
+        if (this.tty) {
+            this.out.write(CLEAR_LINE + line);
+            this.drawn = true;
+        }
+        else {
+            this.out.write(line + '\n');
+        }
+    }
+    /** End the phase, leaving `summary` (if any work was done). */
+    done(summary) {
+        if (this.tty)
+            logger_1.logger.setBeforeWrite(undefined);
+        if (this.count === 0)
+            return;
+        this.clear();
+        if (summary)
+            this.out.write(summary + '\n');
+    }
+    clear() {
+        if (this.drawn) {
+            this.out.write(CLEAR_LINE);
+            this.drawn = false;
+        }
+    }
+}
+exports.Progress = Progress;
+//# sourceMappingURL=progress.js.map

package/package.json

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