@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/trust/policy.js

@@ -0,0 +1,190 @@
+/**
+ * Trust policy, always read from the base revision (#2524 D5, Threat model;
+ * ws-001, ws-002).
+ *
+ * A check reads who may sign, and who holds which role, from the target
+ * branch tip or `--base <rev>`, never from the change under review. A change
+ * can edit its own copy of these files, and those edits have no effect until
+ * they are merged: the change is still judged by the policy at base. Editing
+ * the policy is itself a protected write (see ./verify.ts).
+ *
+ * Two files, both optional:
+ *
+ * - `.chant/allowed_signers` holds the signers, in ssh-keygen's
+ *   allowed_signers format, so `git log --show-signature` can use the same
+ *   file. `trust.json` may name another path.
+ * - `.chant/trust.json` holds the override for the signers path, the role
+ *   grants and the adopted commit ranges. Role grants move into
+ *   `chant.workspace.json` once the declaration exists (#2534).
+ *
+ * Attestation is opt-in (#2525 rule 6). Without a signers file at base,
+ * nothing is verified and every record is `unattested`.
+ */
+import { posix } from "node:path";
+import { z } from "zod";
+import { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners } from "./trust-files.js";
+export { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners, renderAllowedSigners, } from "./trust-files.js";
+// ── trust.json ───────────────────────────────────────────────────────────────
+const fullCommit = z.string().regex(/^[0-9a-f]{40}([0-9a-f]{24})?$/, "a full commit id");
+/** A repository-relative path: no `..`, not absolute, `/` separators. */
+const repoPath = z
+    .string()
+    .min(1)
+    .refine((p) => !p.startsWith("/") && !p.includes("\\") && posix.normalize(p) === p && !p.split("/").includes(".."), {
+    message: "a path inside the repository, with / separators and no ..",
+});
+export const trustConfigSchema = z
+    .object({
+    schema: z.literal(1),
+    /** Where the signers file is, instead of `.chant/allowed_signers`. */
+    signers: repoPath.optional(),
+    /**
+     * Role name to the principals holding it. Until #2534 these live here;
+     * then they move into the declaration.
+     */
+    roles: z.record(z.string().regex(/^[a-z][a-z0-9-]*$/), z.array(z.string().min(1))).optional(),
+    /**
+     * Commit ranges admitted without signatures (#2524 D5, adoption). Each is
+     * exact: `to` and, when given, `from` are full commit ids, and the range is
+     * the commits `from..to`.
+     */
+    adopted: z.array(z.object({ from: fullCommit.optional(), to: fullCommit, note: z.string().optional() }).strict()).optional(),
+    /**
+     * Keys that sign runner evidence (#2553). Each belongs to a service or a CI
+     * identity, never to a person: a key or principal the signers file lists
+     * is refused here.
+     */
+    runners: z
+        .array(z
+        .object({
+        principal: z.string().min(1),
+        class: z.enum(["runner", "service"]),
+        key: z.string().regex(/^ssh-ed25519 [A-Za-z0-9+/]+={0,2}$/, "an ssh-ed25519 public key, with no comment"),
+    })
+        .strict())
+        .optional(),
+    /**
+     * Signers admitted for the work one return brought back (#2552, D10,
+     * ws-004). Each entry names the return by its id (the file
+     * `.chant/returns/<id>.json` the import wrote) and the keys it admits.
+     * An admitted key verifies only the returned commits and seals of that
+     * return, never a commit made in this repository.
+     */
+    admitted: z
+        .array(z
+        .object({
+        return: z.string().regex(/^ret-[0-9a-f]{12}$/, "a return id, ret-<12 hex>"),
+        signers: z
+            .array(z
+            .object({
+            principal: z.string().min(1),
+            key: z.string().regex(/^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]+={0,2}$/, "an ssh public key, with no comment"),
+        })
+            .strict())
+            .min(1),
+        note: z.string().optional(),
+    })
+        .strict())
+        .optional(),
+})
+    .strict();
+/** The role whose holders may change the policy. Without any grant of it, every signer may. */
+export const ADMIN_ROLE = "admin";
+/** Paths whose change is a protected write under `policy`: the config, the signers file and its rotation file (#2553). */
+export function protectedPaths(policy) {
+    const s = policy.signersPath;
+    return [...new Set([TRUST_CONFIG_PATH, s, posix.join(posix.dirname(s), `${posix.basename(s)}.rotation.json`)])].sort();
+}
+/** Principals allowed to change the policy: the admins when any are granted, otherwise every signer. */
+export function policyWriters(policy) {
+    const admins = policy.roles[ADMIN_ROLE];
+    if (admins && admins.length > 0)
+        return new Set(admins);
+    return new Set(policy.signers.map((s) => s.principal));
+}
+/** A policy with nothing in it: attestation off. */
+export function emptyPolicy(base, problems = []) {
+    return { base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], excluded: [], roles: {}, adopted: [], runners: [], excludedRunners: [], admitted: {}, problems };
+}
+/**
+ * Read the policy through `source`, which must read the base revision.
+ * Never throws: a policy that cannot be read yields an inactive policy with
+ * its problems listed, so nothing is attested (fail closed).
+ */
+export function readTrustPolicy(source, base) {
+    let config = { schema: 1 };
+    const configText = readOptional(source, TRUST_CONFIG_PATH);
+    if (configText !== undefined) {
+        let raw;
+        try {
+            raw = JSON.parse(configText);
+        }
+        catch (err) {
+            return emptyPolicy(base, [`${TRUST_CONFIG_PATH} is not JSON: ${err instanceof Error ? err.message : String(err)}`]);
+        }
+        const parsed = trustConfigSchema.safeParse(raw);
+        if (!parsed.success) {
+            const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+            return emptyPolicy(base, [`${TRUST_CONFIG_PATH} is invalid: ${detail}`]);
+        }
+        config = parsed.data;
+    }
+    const signersPath = config.signers ?? DEFAULT_SIGNERS_PATH;
+    const text = readOptional(source, signersPath);
+    const set = text === undefined ? { signers: [], excluded: [] } : parseAllowedSigners(text);
+    // A runner key is a machine's, never a person's (#2553).
+    const humanKeys = new Set(set.signers.map((s) => s.key));
+    const humanNames = new Set(set.signers.map((s) => s.principal));
+    const runners = [];
+    const excludedRunners = [];
+    const all = config.runners ?? [];
+    for (const r of all) {
+        if (humanKeys.has(r.key) || humanNames.has(r.principal)) {
+            excludedRunners.push({ principal: r.principal, reason: `${signersPath} lists this ${humanKeys.has(r.key) ? "key" : "principal"}; runner keys belong to a service or CI identity, never to a signer` });
+        }
+        else if (all.filter((o) => o.key === r.key || o.principal === r.principal).length > 1) {
+            // One key under two names, or one name with two entries, would leave it unclear who signed.
+            excludedRunners.push({ principal: r.principal, reason: "another runner entry has the same key or principal; each runner is one principal with one key" });
+        }
+        else {
+            runners.push(r);
+        }
+    }
+    return {
+        base,
+        signersPath,
+        active: text !== undefined,
+        signers: set.signers,
+        excluded: set.excluded,
+        roles: config.roles ?? {},
+        adopted: config.adopted ?? [],
+        runners,
+        excludedRunners,
+        admitted: admittedOf(config),
+        problems: [],
+    };
+}
+/** The admitted signers, by return id. Two entries for one return add up. */
+function admittedOf(config) {
+    const out = {};
+    for (const a of config.admitted ?? []) {
+        out[a.return] = [...(out[a.return] ?? []), ...a.signers.map((s) => ({ principal: s.principal, key: s.key, line: 0 }))];
+    }
+    return out;
+}
+/**
+ * The policy for work that came back in return `id` (#2552): the signers at
+ * base plus the ones admitted for that return, marked with the return so a
+ * seal by an unknown signer reads as unverifiable.
+ */
+export function returnedPolicy(policy, id) {
+    return { ...policy, signers: [...policy.signers, ...(policy.admitted[id] ?? [])], returnedFrom: id };
+}
+/** A file's text through `source`, or undefined when it is not there. */
+export function readOptional(source, path) {
+    const dir = posix.dirname(path);
+    const names = source.list(dir);
+    if (!names || !names.includes(posix.basename(path)))
+        return undefined;
+    return source.read(path);
+}

package/dist/workspace/trust/provenance.js

@@ -0,0 +1,180 @@
+/**
+ * The provenance level of each record (#2524 D5, Threat model).
+ *
+ * A record's content comes from the last commit that changed its file. That
+ * commit is asked of each attestor, with the policy read at base. A file with
+ * uncommitted changes is `unattested`: its bytes are in no commit, so nothing
+ * vouches for them.
+ *
+ * On a developer machine this detects; it does not enforce (ws-002). An agent
+ * running as the developer can use an unlocked signing agent or skip the check.
+ * Enforcement is CI running the same check against base.
+ */
+import { execFileSync } from "node:child_process";
+import { gitRevisionSource } from "../record-source.js";
+import { attestCommit } from "./attestor.js";
+import { emptyPolicy, readTrustPolicy } from "./policy.js";
+import { SignerPositions, signerHistory } from "./rotation.js";
+function git(repo, args) {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+function tryCommit(repo, rev) {
+    try {
+        return git(repo, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The base revision: `--base <rev>` when given, otherwise the target branch
+ * tip, taken as `origin/HEAD`, then a local `main`, then `master`. Never
+ * `HEAD`, which is the change under review.
+ */
+export function resolveBase(repo, explicit) {
+    if (explicit !== undefined) {
+        const c = explicit.startsWith("-") ? undefined : tryCommit(repo, explicit);
+        return c ? { commit: c, from: "flag" } : { commit: null, from: null, problem: `--base ${explicit} names no commit in this repository` };
+    }
+    for (const [rev, from] of [
+        ["refs/remotes/origin/HEAD", "origin/HEAD"],
+        ["refs/heads/main", "main"],
+        ["refs/heads/master", "master"],
+    ]) {
+        const c = tryCommit(repo, rev);
+        if (c)
+            return { commit: c, from };
+    }
+    return { commit: null, from: null, problem: "no base revision: pass --base <rev> (there is no origin/HEAD, main or master)" };
+}
+/**
+ * The policy at `base`, or an inactive one when there is no base. With a
+ * signers file, its history is verified too (#2553): every version must be
+ * signed by a threshold of the one before, or nothing verifies.
+ */
+export function policyAtBase(repo, base) {
+    if (!base.commit)
+        return emptyPolicy(null, base.problem ? [base.problem] : []);
+    const policy = readTrustPolicy(gitRevisionSource(repo, base.commit), base.commit);
+    if (!policy.active || policy.problems.length > 0)
+        return policy;
+    const history = signerHistory(repo, base.commit, policy.signersPath);
+    if (history.broken) {
+        const at = history.broken.commit ? ` at ${history.broken.commit.slice(0, 8)}` : "";
+        return { ...policy, problems: [`the signer history of ${policy.signersPath} is broken${at}: ${history.broken.reason}`] };
+    }
+    const positions = new SignerPositions(repo, base.commit, history);
+    return { ...policy, signersAt: (commit) => positions.versionFor(commit) };
+}
+/**
+ * The last commit reachable from `rev` that changed each path. Merges are
+ * diffed against all their parents (`-c`), so a merge that changes a file
+ * beyond what either side brought is the commit that file comes from, and a
+ * merge that only takes one side's version is passed through to that side.
+ */
+export function lastCommits(repo, rev, paths) {
+    const out = new Map();
+    if (paths.length === 0)
+        return out;
+    const log = git(repo, ["--literal-pathspecs", "log", "-c", "--name-only", "--no-renames", "--format=%x00%H", rev, "--", ...paths]);
+    const wanted = new Set(paths);
+    let commit = "";
+    for (const line of log.split("\n")) {
+        if (line.startsWith("\0"))
+            commit = line.slice(1).trim();
+        else if (line && wanted.has(line) && !out.has(line))
+            out.set(line, commit);
+    }
+    return out;
+}
+/** Paths with staged, unstaged or untracked changes in the working tree. */
+export function dirtyPaths(repo, paths) {
+    if (paths.length === 0)
+        return new Set();
+    const status = git(repo, ["--literal-pathspecs", "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ...paths]);
+    const dirty = new Set();
+    const parts = status.split("\0");
+    for (let i = 0; i < parts.length; i++) {
+        const p = parts[i];
+        if (p.length < 4)
+            continue;
+        dirty.add(p.slice(3));
+        if (p[0] === "R" || p[0] === "C")
+            i++;
+    }
+    return dirty;
+}
+function isAncestor(repo, a, b) {
+    try {
+        execFileSync("git", ["merge-base", "--is-ancestor", a, b], { cwd: repo, stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether `commit` lies in a range the policy adopts (`from..to`, exact). */
+export function isAdopted(repo, policy, commit) {
+    return policy.adopted.some((r) => isAncestor(repo, commit, r.to) && (r.from === undefined || !isAncestor(repo, commit, r.from)));
+}
+/** A commit's provenance level under `policy`. */
+export function commitProvenance(repo, policy, commit, attestors) {
+    // Judge the commit by the signer set in effect where it entered the base's history (#2553).
+    let judged = policy;
+    if (policy.signersAt) {
+        const v = policy.signersAt(commit);
+        judged = { ...policy, signers: v?.signers ?? [] };
+        if (!v || v.version === 0) {
+            const none = "no signer set was in effect where this commit entered the base's history";
+            if (isAdopted(repo, policy, commit))
+                return { level: "adopted", commit, reason: `in a commit range the policy at base adopts; ${none}` };
+            return { level: "unattested", commit, reason: none };
+        }
+    }
+    const a = attestCommit({ repo, policy: judged }, commit, attestors);
+    if (a.level === "unattested" && isAdopted(repo, policy, commit)) {
+        return { level: "adopted", commit, attestor: a.attestor, reason: `in a commit range the policy at base adopts; ${a.reason}` };
+    }
+    return {
+        level: a.level,
+        commit,
+        attestor: a.attestor,
+        ...(a.principal ? { principal: a.principal } : {}),
+        ...(a.key ? { key: a.key } : {}),
+        reason: a.reason,
+    };
+}
+/**
+ * The provenance of each path. With attestation off (no signers file at
+ * base) nothing is checked and every path is `unattested`.
+ */
+export function recordProvenance(q) {
+    const out = new Map();
+    const all = (reason) => {
+        for (const p of q.paths)
+            out.set(p, { level: "unattested", commit: null, reason });
+        return out;
+    };
+    if (!q.repo)
+        return all("not in a git repository");
+    if (q.policy.problems.length > 0)
+        return all(q.policy.problems.join("; "));
+    if (!q.policy.active)
+        return all(`no signers file (${q.policy.signersPath}) at base ${q.policy.base?.slice(0, 8)}; attestation is off`);
+    const dirty = q.at === null ? dirtyPaths(q.repo, q.paths) : new Set();
+    const commits = lastCommits(q.repo, q.at ?? "HEAD", q.paths.filter((p) => !dirty.has(p)));
+    for (const p of q.paths) {
+        if (dirty.has(p)) {
+            out.set(p, { level: "unattested", commit: null, reason: "the working tree has uncommitted changes to this file" });
+            continue;
+        }
+        const c = commits.get(p);
+        if (!c) {
+            out.set(p, { level: "unattested", commit: null, reason: "no commit holds this file" });
+            continue;
+        }
+        const host = commitProvenance(q.repo, q.policy, c, q.attestors);
+        out.set(p, q.revisit?.(p, host) ?? host);
+    }
+    return out;
+}

package/dist/workspace/trust/rotation.js

@@ -0,0 +1,298 @@
+/**
+ * Signer rotation, verified from history (#2553, #2524 D5, ws-001).
+ *
+ * A signer set is the signers file plus a threshold. A new set is valid only
+ * when a threshold of the previous set signed it, as in TUF's root rotation.
+ * The signatures live beside the signers file, in `<signers>.rotation.json`:
+ *
+ * ```json
+ * { "schema": 1, "version": 2, "previous": "sha256:…", "threshold": 1,
+ *   "signatures": [{ "principal": "alice@example.com", "signature": "-----BEGIN SSH SIGNATURE-----…" }] }
+ * ```
+ *
+ * Each signature is `ssh-keygen -Y sign -n chant-signers` over the statement
+ * {@link rotationStatement} returns: the new version, the digest of the
+ * previous signers file, the digest of the new one and the new threshold. The
+ * version number and the previous digest together stop an old, once-valid set
+ * from being replayed, and the namespace stops a commit signature from
+ * standing in for a rotation signature.
+ *
+ * ## Revocation by position
+ *
+ * Dates prove nothing: whoever makes a commit sets its date. So a commit is
+ * judged by where it sits in the base's history. Walking the base's
+ * first-parent line from the oldest commit, each commit that changes the
+ * signer set starts a version, and each version must be signed by a threshold
+ * of the one before. A commit already in the base's history is judged by the
+ * version in effect just before the first-parent commit that brought it in. A
+ * key removed at version N therefore still vouches for what was merged before
+ * N, and for nothing merged after, however the later commit is dated. A commit
+ * not yet in the base's history is judged by the latest version.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { posix } from "node:path";
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt.js";
+import { sshFingerprint } from "./dsse.js";
+import { parseAllowedSigners } from "./policy.js";
+import { verifySshSignature } from "./ssh-commit.js";
+/** Why a signer set is not a valid next version (#2553). Each is in `reason-codes.ts` and in `signers.schema.json`. */
+export const ROTATION_REFUSAL_CODES = [
+    "signers-removed",
+    "rotation-unparseable",
+    "rotation-invalid",
+    "rotation-first-version",
+    "rotation-missing",
+    "rotation-version-skew",
+    "rotation-previous-mismatch",
+    "rotation-threshold-unsatisfiable",
+    "rotation-threshold-not-met",
+];
+/** The ssh-keygen namespace rotation signatures are made in. Never `git`. */
+export const ROTATION_NAMESPACE = "chant-signers";
+/** The rotation file for a signers file. */
+export function rotationPath(signersPath) {
+    return posix.join(posix.dirname(signersPath), `${posix.basename(signersPath)}.rotation.json`);
+}
+/** `sha256:<hex>` of a signers file's bytes, line endings normalised. */
+export function signersDigest(text) {
+    return `sha256:${createHash("sha256").update(text.replace(/\r\n?/g, "\n"), "utf8").digest("hex")}`;
+}
+export const rotationFileSchema = z
+    .object({
+    schema: z.literal(1),
+    version: z.number().int().min(1),
+    previous: z.string().regex(/^sha256:[0-9a-f]{64}$/).nullable(),
+    threshold: z.number().int().min(1),
+    signatures: z.array(z.object({ principal: z.string().min(1), signature: z.string().min(1) }).strict()),
+})
+    .strict();
+/** The bytes each rotation signature covers. */
+export function rotationStatement(r, signers) {
+    return Buffer.from(canonicalJson({ type: "chant-signer-set", version: r.version, previous: r.previous, signers, threshold: r.threshold }), "utf8");
+}
+/**
+ * Check `next` against the version before it. Returns the new version, or
+ * the reason it is not valid. `prev` undefined means there was no signer set,
+ * so `next` is a first version and needs no signatures.
+ */
+export function nextVersion(prev, next, commit) {
+    if (next.signers === undefined)
+        return { code: "signers-removed", reason: "the signers file was removed" };
+    const digest = signersDigest(next.signers);
+    let rotation;
+    if (next.rotation !== undefined) {
+        let raw;
+        try {
+            raw = JSON.parse(next.rotation);
+        }
+        catch (err) {
+            return { code: "rotation-unparseable", reason: `the rotation file is not JSON: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        const parsed = rotationFileSchema.safeParse(raw);
+        if (!parsed.success)
+            return { code: "rotation-invalid", reason: `the rotation file is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ")}` };
+        rotation = parsed.data;
+    }
+    const set = parseAllowedSigners(next.signers);
+    const threshold = rotation?.threshold ?? 1;
+    // A threshold no future rotation could meet would freeze the set for good.
+    const holders = distinctHolders(set.signers);
+    if (threshold > holders) {
+        return {
+            code: "rotation-threshold-unsatisfiable",
+            reason: `the threshold is ${threshold}, and the set has ${holders} distinct signer${holders === 1 ? "" : "s"} to meet it`,
+        };
+    }
+    if (!prev) {
+        if (rotation && (rotation.version !== 1 || rotation.previous !== null)) {
+            return { code: "rotation-first-version", reason: `a first signer set must be version 1 with no previous digest, not version ${rotation.version}` };
+        }
+        return { version: 1, commit, digest, threshold, signers: set.signers, excluded: set.excluded, signedBy: [] };
+    }
+    if (digest === prev.digest && threshold === prev.threshold)
+        return prev;
+    if (!rotation)
+        return { code: "rotation-missing", reason: `the signer set changed from version ${prev.version} with no rotation file signed by the set before it` };
+    if (rotation.version !== prev.version + 1)
+        return { code: "rotation-version-skew", reason: `the rotation says version ${rotation.version}; the next version is ${prev.version + 1}` };
+    if (rotation.previous !== prev.digest)
+        return { code: "rotation-previous-mismatch", reason: `the rotation names previous ${rotation.previous}, but version ${prev.version} is ${prev.digest}` };
+    const statement = rotationStatement(rotation, digest);
+    // Each signature counts once per key and once per principal: one key listed
+    // under two names is one signer, and so is one person with two keys.
+    const keys = new Set();
+    const signedBy = [];
+    for (const s of rotation.signatures) {
+        if (signedBy.includes(s.principal))
+            continue;
+        const mine = prev.signers.filter((x) => x.principal === s.principal);
+        const r = verifySshSignature(mine, statement, s.signature, ROTATION_NAMESPACE);
+        if (!r.ok)
+            continue;
+        const key = r.key ?? (mine.length === 1 ? sshFingerprint(mine[0].key) : `principal:${r.principal}`);
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        signedBy.push(r.principal);
+    }
+    if (keys.size < prev.threshold) {
+        return {
+            code: "rotation-threshold-not-met",
+            reason: `version ${rotation.version} is signed by ${keys.size} of the ${prev.threshold} signers of version ${prev.version} it needs${signedBy.length ? ` (${signedBy.join(", ")})` : ""}`,
+        };
+    }
+    return { version: rotation.version, commit, digest, threshold, signers: set.signers, excluded: set.excluded, signedBy };
+}
+/**
+ * How many signers could each give a counted signature: principals and keys
+ * are both distinct, so this is the size of a largest matching between them.
+ */
+export function distinctHolders(signers) {
+    const keysOf = new Map();
+    for (const s of signers) {
+        const set = keysOf.get(s.principal) ?? new Set();
+        set.add(s.key);
+        keysOf.set(s.principal, set);
+    }
+    const owner = new Map();
+    const tryAssign = (p, seen) => {
+        for (const k of keysOf.get(p) ?? []) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            const o = owner.get(k);
+            if (o === undefined || tryAssign(o, seen)) {
+                owner.set(k, p);
+                return true;
+            }
+        }
+        return false;
+    };
+    let n = 0;
+    for (const p of keysOf.keys())
+        if (tryAssign(p, new Set()))
+            n++;
+    return n;
+}
+function git(repo, args) {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+/** A file's text at `commit`, or undefined when it is not there. */
+export function fileAt(repo, commit, path) {
+    try {
+        return git(repo, ["cat-file", "blob", `${commit}:${path}`]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Walk the signer set's history along the first-parent line of `base`,
+ * oldest first. A removal ends the chain; a later signers file starts a new
+ * one, which only the protected-write check in CI could have admitted.
+ */
+export function signerHistory(repo, base, signersPath) {
+    const paths = [signersPath, rotationPath(signersPath)];
+    const commits = git(repo, ["--literal-pathspecs", "log", "--first-parent", "--reverse", "--format=%H", base, "--", ...paths])
+        .split("\n")
+        .filter(Boolean);
+    const versions = [];
+    let prev;
+    for (const commit of commits) {
+        const files = { signers: fileAt(repo, commit, paths[0]), rotation: fileAt(repo, commit, paths[1]) };
+        if (files.signers === undefined) {
+            // Earlier versions still judge what was merged under them; from here on, nothing verifies.
+            if (prev)
+                versions.push({ version: 0, commit, digest: "", threshold: 0, signers: [], excluded: [], signedBy: [] });
+            prev = undefined;
+            continue;
+        }
+        const next = nextVersion(prev, files, commit);
+        if ("code" in next)
+            return { versions, broken: { commit, code: next.code, reason: next.reason } };
+        if (next !== prev)
+            versions.push(next);
+        prev = next;
+    }
+    return { versions };
+}
+/**
+ * Finds the signer set in effect for a commit, by its position in the base's
+ * history. Built once per base; the first-parent line is read once and
+ * each lookup is a binary search.
+ */
+export class SignerPositions {
+    constructor(repo, base, history) {
+        this.repo = repo;
+        this.base = base;
+        this.history = history;
+        this.index = new Map();
+        this.memo = new Map();
+    }
+    isAncestor(a, b) {
+        try {
+            execFileSync("git", ["merge-base", "--is-ancestor", a, b], { cwd: this.repo, stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The base's first-parent line, newest first. */
+    firstParents() {
+        if (!this.line) {
+            this.line = git(this.repo, ["rev-list", "--first-parent", this.base]).split("\n").filter(Boolean);
+            this.line.forEach((c, i) => this.index.set(c, i));
+        }
+        return this.line;
+    }
+    /**
+     * The version that judges `commit`, or null when no signer set was in
+     * effect there (before the first one, or the chain is broken).
+     */
+    versionFor(commit) {
+        const hit = this.memo.get(commit);
+        if (hit !== undefined)
+            return hit;
+        const answer = this.lookup(commit);
+        this.memo.set(commit, answer);
+        return answer;
+    }
+    lookup(commit) {
+        if (this.history.broken)
+            return null;
+        const latest = this.history.versions.at(-1) ?? null;
+        if (!this.isAncestor(commit, this.base))
+            return latest;
+        const line = this.firstParents();
+        // The oldest first-parent commit that contains `commit` is where it came in.
+        let lo = 0;
+        let hi = line.length - 1;
+        let at = 0;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            if (this.isAncestor(commit, line[mid])) {
+                at = mid;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        // The newest version made strictly before that commit.
+        let best = null;
+        let bestIndex = Infinity;
+        for (const v of this.history.versions) {
+            const i = v.commit ? this.index.get(v.commit) : undefined;
+            if (i === undefined || i <= at)
+                continue;
+            if (i < bestIndex) {
+                best = v;
+                bestIndex = i;
+            }
+        }
+        return best;
+    }
+}