@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/trust/rotation.test.ts

@@ -0,0 +1,258 @@
+/**
+ * #2553: signer rotation, verified from history, with revocation by position.
+ *
+ * The attacker controls the change and its commit dates: a rotation signed by
+ * the key it adds, too few signatures, a replayed or rolled-back set, a commit
+ * signature passed off as a rotation signature, a main branch whose set was
+ * changed without a rotation, and a revoked key's commit backdated to before
+ * the revocation.
+ */
+
+import { afterEach, describe, expect, test } from "vitest";
+import { queryRecords, type RecordView } from "../records-cli";
+import { activeAttestors } from "./attestor";
+import { policyAtBase, resolveBase } from "./provenance";
+import { distinctHolders, signerHistory } from "./rotation";
+import { parseAllowedSigners } from "./policy";
+import { SIGNERS_OUTPUT_SCHEMA_ID, signersDocument } from "./signers-cli";
+import { contract } from "../__fixtures__/contract-repo";
+import signersSchema from "../signers.schema.json";
+import { verifyChange } from "./verify";
+import { hasSshKeygen, note, TestRepo, writeRecordKind, writeRotation, type Key } from "./test-repo";
+
+const repos: TestRepo[] = [];
+afterEach(() => {
+  while (repos.length) repos.pop()!.cleanup();
+});
+
+function signers(...entries: Array<[string, Key]>): string {
+  return entries.map(([p, k]) => `${p} ${k.pub}`).join("\n") + "\n";
+}
+
+async function verify(r: TestRepo, require?: "attested") {
+  return verifyChange({ repo: r.dir, base: "main", require, attestors: await activeAttestors() });
+}
+
+async function records(r: TestRepo, kind: string): Promise<RecordView[]> {
+  const doc = await queryRecords({ kind, cwd: r.dir, base: "main" });
+  if ("error" in doc) throw new Error(doc.error.message);
+  return doc.records;
+}
+
+function level(rs: RecordView[], id: string): string {
+  return rs.find((x) => x.id === id)!.provenance.level;
+}
+
+/** main holds version 1: alice and bob, with `threshold`. */
+function setup(label: string, threshold = 1) {
+  const r = new TestRepo(label);
+  repos.push(r);
+  const alice = r.key("alice");
+  const bob = r.key("bob");
+  const carol = r.key("carol");
+  const kind = writeRecordKind(r);
+  const v1 = signers(["alice@example.test", alice], ["bob@example.test", bob]);
+  r.write(".chant/allowed_signers", v1);
+  if (threshold !== 1) {
+    r.write(".chant/allowed_signers.rotation.json", JSON.stringify({ schema: 1, version: 1, previous: null, threshold, signatures: [] }));
+  }
+  r.commit("signers v1", alice);
+  return { r, alice, bob, carol, kind, v1 };
+}
+
+describe.skipIf(!hasSshKeygen)("signer rotation", () => {
+  test("a new set signed by the old one is accepted, and history shows both versions", async () => {
+    const { r, alice, bob, carol, v1 } = setup("rotate");
+    r.git(["checkout", "-q", "-b", "change"]);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob], ["carol@example.test", carol]));
+    writeRotation(r, { previousText: v1, version: 2, by: [["alice@example.test", alice]] });
+    r.commit("add carol", alice);
+    const report = await verify(r);
+    expect(report.failures).toEqual([]);
+    expect(report.rotation).toEqual({ from: 1, to: 2, signedBy: ["alice@example.test"] });
+
+    r.git(["checkout", "-q", "main"]);
+    r.git(["merge", "-q", "--ff-only", "change"]);
+    const h = signerHistory(r.dir, r.head(), ".chant/allowed_signers");
+    expect(h.broken).toBeUndefined();
+    expect(h.versions.map((v) => [v.version, v.signedBy])).toEqual([
+      [1, []],
+      [2, ["alice@example.test"]],
+    ]);
+  });
+
+  test("attack: the change's new signer signs her own admission", async () => {
+    const { r, alice, bob, carol, v1 } = setup("self-admit");
+    r.git(["checkout", "-q", "-b", "change"]);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob], ["carol@example.test", carol]));
+    writeRotation(r, { previousText: v1, version: 2, by: [["carol@example.test", carol]] });
+    r.commit("add carol", alice);
+    const report = await verify(r);
+    expect(report.ok).toBe(false);
+    expect(report.failures.join("\n")).toMatch(/signed by 0 of the 1 signers of version 1/);
+    expect(report.rotation).toMatchObject({ from: 1, code: "rotation-threshold-not-met" });
+  });
+
+  test("a threshold of 2 needs two distinct keys; one key under two names counts once", async () => {
+    const { r, alice, bob, carol, v1 } = setup("threshold", 2);
+    r.git(["checkout", "-q", "-b", "change"]);
+    const v2 = signers(["alice@example.test", alice], ["bob@example.test", bob], ["carol@example.test", carol]);
+    r.write(".chant/allowed_signers", v2);
+    writeRotation(r, { previousText: v1, version: 2, threshold: 2, by: [["alice@example.test", alice]] });
+    r.commit("one signature", alice);
+    expect((await verify(r)).failures.join("\n")).toMatch(/signed by 1 of the 2/);
+
+    // alice's key listed twice at base would still be one key.
+    writeRotation(r, { previousText: v1, version: 2, threshold: 2, by: [["alice@example.test", alice], ["alice@example.test", alice]] });
+    r.commit("same key twice", alice);
+    expect((await verify(r)).failures.join("\n")).toMatch(/signed by 1 of the 2/);
+
+    writeRotation(r, { previousText: v1, version: 2, threshold: 2, by: [["alice@example.test", alice], ["bob@example.test", bob]] });
+    r.commit("two signatures", alice);
+    const report = await verify(r);
+    expect(report.failures).toEqual([]);
+    expect(report.rotation && "to" in report.rotation && report.rotation.signedBy.sort()).toEqual(["alice@example.test", "bob@example.test"]);
+  });
+
+  test("attack: a commit signature, in the git namespace, is not a rotation signature", async () => {
+    const { r, alice, bob, carol, v1 } = setup("namespace");
+    r.git(["checkout", "-q", "-b", "change"]);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob], ["carol@example.test", carol]));
+    writeRotation(r, { previousText: v1, version: 2, by: [["alice@example.test", alice]], namespace: "git" });
+    r.commit("add carol", alice);
+    const report = await verify(r);
+    expect(report.ok).toBe(false);
+    expect(report.rotation).toMatchObject({ code: "rotation-threshold-not-met" });
+  });
+
+  test("attack: rolling back to an older set, or replaying an old rotation, is refused", async () => {
+    const { r, alice, bob, v1 } = setup("rollback");
+    // version 2 removes bob, and is merged.
+    const v2 = signers(["alice@example.test", alice]);
+    r.write(".chant/allowed_signers", v2);
+    writeRotation(r, { previousText: v1, version: 2, by: [["alice@example.test", alice]] });
+    r.commit("remove bob", alice);
+    const replay = r.git(["show", "HEAD:.chant/allowed_signers.rotation.json"]);
+
+    // Restore v1 and bob, keeping version 2's rotation file.
+    r.git(["checkout", "-q", "-b", "rollback"]);
+    r.write(".chant/allowed_signers", v1);
+    r.write(".chant/allowed_signers.rotation.json", replay);
+    r.commit("bring bob back", alice);
+    expect((await verify(r)).failures.join("\n")).toMatch(/\(rotation-version-skew\).*the next version is 3/);
+
+    // Or claim to be version 3 with version 1's digest as previous.
+    writeRotation(r, { previousText: v1, version: 3, by: [["alice@example.test", alice], ["bob@example.test", bob]] });
+    r.commit("claim v3", alice);
+    expect((await verify(r)).failures.join("\n")).toMatch(/\(rotation-previous-mismatch\).*names previous/);
+  });
+
+  test("attack: a signer set changed on main without a rotation breaks the history, and nothing verifies", async () => {
+    const { r, alice, bob, carol, kind } = setup("broken");
+    r.write("records/n1.md", note("n1"));
+    r.commit("n1", alice);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob], ["carol@example.test", carol]));
+    r.commit("pushed straight to main", alice);
+    const policy = policyAtBase(r.dir, resolveBase(r.dir, "main"));
+    expect(policy.problems[0]).toMatch(/signer history .* is broken/);
+    expect(signerHistory(r.dir, "main", ".chant/allowed_signers").broken).toMatchObject({ code: "rotation-missing" });
+    expect(level(await records(r, kind), "n1")).toBe("unattested");
+    r.git(["checkout", "-q", "-b", "change"]);
+    expect((await verify(r)).ok).toBe(false);
+  });
+
+  test("attack: a revoked key keeps what was merged before its revocation, and nothing after, whatever the dates say", async () => {
+    const { r, alice, bob, v1, kind } = setup("position");
+    r.write("records/early.md", note("early"));
+    r.commit("bob, before revocation", bob);
+    r.git(["branch", "fork-before-revocation"]);
+
+    const v2 = signers(["alice@example.test", alice]);
+    r.write(".chant/allowed_signers", v2);
+    writeRotation(r, { previousText: v1, version: 2, by: [["alice@example.test", alice]] });
+    r.commit("revoke bob", alice);
+
+    // bob, after revocation, backdates a commit onto a branch forked before it...
+    r.git(["checkout", "-q", "fork-before-revocation"]);
+    r.write("records/late.md", note("late"));
+    const old = "2001-01-01T00:00:00Z";
+    r.commit("bob, backdated", bob, { GIT_AUTHOR_DATE: old, GIT_COMMITTER_DATE: old });
+    // ...and it is merged after the revocation, by a signer in good standing.
+    r.git(["checkout", "-q", "main"]);
+    r.git(["-c", "gpg.format=ssh", "-c", `user.signingkey=${alice.file}`, "merge", "-q", "--no-ff", "-S", "-m", "merge", "fork-before-revocation"]);
+
+    // And straight onto main, backdated too.
+    r.write("records/direct.md", note("direct"));
+    r.commit("bob, backdated, on main", bob, { GIT_AUTHOR_DATE: old, GIT_COMMITTER_DATE: old });
+
+    const rs = await records(r, kind);
+    expect(level(rs, "early")).toBe("attested");
+    expect(rs.find((x) => x.id === "early")!.provenance.principal).toBe("bob@example.test");
+    expect(level(rs, "late")).toBe("unattested");
+    expect(level(rs, "direct")).toBe("unattested");
+  });
+
+  test("the commit that adds the first signer set is judged by the set before it, which is none", async () => {
+    const r = new TestRepo("genesis");
+    repos.push(r);
+    const alice = r.key("alice");
+    const kind = writeRecordKind(r);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice]));
+    r.write("records/n1.md", note("n1"));
+    r.commit("signers and a record together", alice);
+    r.write("records/n2.md", note("n2"));
+    r.commit("n2", alice);
+    const rs = await records(r, kind);
+    expect(level(rs, "n1")).toBe("unattested");
+    expect(level(rs, "n2")).toBe("attested");
+  });
+
+  test("attack: one person with two keys signs twice, and counts once", async () => {
+    const r = new TestRepo("two-keys");
+    repos.push(r);
+    const a1 = r.key("alice1");
+    const a2 = r.key("alice2");
+    const bob = r.key("bob");
+    const v1 = signers(["alice@example.test", a1], ["alice@example.test", a2], ["bob@example.test", bob]);
+    r.write(".chant/allowed_signers", v1);
+    r.write(".chant/allowed_signers.rotation.json", JSON.stringify({ schema: 1, version: 1, previous: null, threshold: 2, signatures: [] }));
+    r.commit("v1, threshold 2", a1);
+    r.git(["checkout", "-q", "-b", "change"]);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", a1], ["bob@example.test", bob]));
+    writeRotation(r, { previousText: v1, version: 2, threshold: 2, by: [["alice@example.test", a1], ["alice@example.test", a2]] });
+    r.commit("alice twice", a1);
+    const report = await verify(r);
+    expect(report.rotation).toMatchObject({ code: "rotation-threshold-not-met" });
+    expect(report.failures.join("\n")).toMatch(/signed by 1 of the 2/);
+  });
+
+  test("a threshold the new set cannot meet is refused, so the set can never be frozen", async () => {
+    const { r, alice, v1 } = setup("unsatisfiable");
+    r.git(["checkout", "-q", "-b", "change"]);
+    // Two lines, one principal: one distinct signer for a threshold of 2.
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["alice@example.test", r.key("alice-laptop")]));
+    writeRotation(r, { previousText: v1, version: 2, threshold: 2, by: [["alice@example.test", alice]] });
+    r.commit("threshold 2", alice);
+    const report = await verify(r);
+    expect(report.rotation).toMatchObject({ code: "rotation-threshold-unsatisfiable" });
+    expect(distinctHolders(parseAllowedSigners(signers(["a", alice], ["b", alice])).signers)).toBe(1);
+  });
+
+  test("signers --json prints a document signers.schema.json accepts, intact or broken", async () => {
+    const { r, alice, carol, v1 } = setup("contract");
+    const { expectValid } = contract(signersSchema);
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["carol@example.test", carol]));
+    writeRotation(r, { previousText: v1, version: 2, by: [["alice@example.test", alice]] });
+    r.commit("v2", alice);
+    const base = r.head();
+    let doc = signersDocument(r.dir, base, ".chant/allowed_signers", signerHistory(r.dir, base, ".chant/allowed_signers"));
+    expect(doc).toMatchObject({ $schema: SIGNERS_OUTPUT_SCHEMA_ID, broken: null, versions: [{ version: 1 }, { version: 2, principals: ["alice@example.test", "carol@example.test"], signedBy: ["alice@example.test"] }] });
+    expectValid(doc);
+    r.write(".chant/allowed_signers", v1);
+    r.commit("rolled back by hand", alice);
+    doc = signersDocument(r.dir, r.head(), ".chant/allowed_signers", signerHistory(r.dir, r.head(), ".chant/allowed_signers"));
+    expect("broken" in doc && doc.broken).toMatchObject({ code: "rotation-version-skew" });
+    expectValid(doc);
+    expectValid({ $schema: SIGNERS_OUTPUT_SCHEMA_ID, contract: 1, chant: "0.0.0", error: { code: "signers-file-missing", message: "m" } });
+  });
+});

package/src/workspace/trust/rotation.ts

@@ -0,0 +1,336 @@
+/**
+ * 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";
+import type { ReasonCode } from "../reason-codes";
+import { sshFingerprint } from "./dsse";
+import { parseAllowedSigners, type ExcludedSigner, type Signer } from "./policy";
+import { verifySshSignature } from "./ssh-commit";
+
+/** 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",
+] as const satisfies readonly ReasonCode[];
+export type RotationRefusalCode = (typeof ROTATION_REFUSAL_CODES)[number];
+
+/** A refused version: the code and a sentence for people. */
+export interface RotationRefusal {
+  code: RotationRefusalCode;
+  reason: string;
+}
+
+/** 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: string): string {
+  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: string): string {
+  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();
+export type RotationFile = z.infer<typeof rotationFileSchema>;
+
+/** The bytes each rotation signature covers. */
+export function rotationStatement(r: { version: number; previous: string | null; threshold: number }, signers: string): Buffer {
+  return Buffer.from(
+    canonicalJson({ type: "chant-signer-set", version: r.version, previous: r.previous, signers, threshold: r.threshold }),
+    "utf8",
+  );
+}
+
+/** One version of the signer set, as history established it. */
+export interface SignerVersion {
+  /** 1 and up; 0 marks where the signers file was removed and nothing was in effect. */
+  version: number;
+  /** The first-parent commit that made this version, or null for a set not yet merged. */
+  commit: string | null;
+  digest: string;
+  threshold: number;
+  signers: Signer[];
+  excluded: ExcludedSigner[];
+  /** The principals whose signatures made this version valid; empty for the first version. */
+  signedBy: string[];
+}
+
+export interface SignerHistory {
+  versions: SignerVersion[];
+  /** Where the chain broke, when it did. Nothing verifies then. */
+  broken?: { commit: string | null } & RotationRefusal;
+}
+
+/** The state of the signer files at one point, as text. */
+export interface SignerFiles {
+  signers?: string;
+  rotation?: string;
+}
+
+/**
+ * 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: SignerVersion | undefined, next: SignerFiles, commit: string | null): SignerVersion | RotationRefusal {
+  if (next.signers === undefined) return { code: "signers-removed", reason: "the signers file was removed" };
+  const digest = signersDigest(next.signers);
+  let rotation: RotationFile | undefined;
+  if (next.rotation !== undefined) {
+    let raw: unknown;
+    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<string>();
+  const signedBy: string[] = [];
+  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: readonly Signer[]): number {
+  const keysOf = new Map<string, Set<string>>();
+  for (const s of signers) {
+    const set = keysOf.get(s.principal) ?? new Set<string>();
+    set.add(s.key);
+    keysOf.set(s.principal, set);
+  }
+  const owner = new Map<string, string>();
+  const tryAssign = (p: string, seen: Set<string>): boolean => {
+    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: string, args: string[]): string {
+  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: string, commit: string, path: string): string | undefined {
+  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: string, base: string, signersPath: string): SignerHistory {
+  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: SignerVersion[] = [];
+  let prev: SignerVersion | undefined;
+  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 {
+  private line: string[] | undefined;
+  private index = new Map<string, number>();
+  private memo = new Map<string, SignerVersion | null>();
+
+  constructor(
+    private readonly repo: string,
+    private readonly base: string,
+    private readonly history: SignerHistory,
+  ) {}
+
+  private isAncestor(a: string, b: string): boolean {
+    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. */
+  private firstParents(): string[] {
+    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: string): SignerVersion | null {
+    const hit = this.memo.get(commit);
+    if (hit !== undefined) return hit;
+    const answer = this.lookup(commit);
+    this.memo.set(commit, answer);
+    return answer;
+  }
+
+  private lookup(commit: string): SignerVersion | null {
+    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: SignerVersion | null = 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;
+  }
+}

package/src/workspace/trust/seal.ts

@@ -176,6 +176,17 @@ function checkSeal(policy: TrustPolicy, s: SealSubject): SealCheck {
   if (typeof s.payload === "string") return { attested: false, code: "seal-signature-invalid", message: s.payload };
   if (!policy.active) return checkIntegrity(s.principal, s.payload, seal.signature, s.namespace);
   const listed = policy.signers.filter((x) => normalise(x.principal) === normalise(s.principal));
+  if (listed.length === 0 && policy.returnedFrom !== undefined) {
+    // Returned work (#2552, ws-004): a signer the service never saw is unverifiable until an admin admits them.
+    const intact = checkIntegrity(s.principal, s.payload, seal.signature, s.namespace);
+    if (intact.attested === false) return intact;
+    return {
+      attested: null,
+      code: "seal-unverifiable",
+      message: `${s.what} came back in return ${policy.returnedFrom}, sealed by ${s.principal}${intact.key ? ` with ${intact.key}` : ""}, whom neither ${where} nor an admission for that return lists; it counts once an admin admits the signer (chant workspace admit ${policy.returnedFrom})`,
+      ...(intact.key ? { key: intact.key } : {}),
+    };
+  }
   if (listed.length === 0) {
     return { attested: false, code: "seal-signer-unlisted", message: `${s.principal} has no key in ${where}, so the seal can't count` };
   }