@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/status.ts

@@ -20,6 +20,11 @@
  * declaration that can't be read, or an environment name that can't be one,
  * exits 1. The `--json` output is part of the read contract and is described
  * by `status.schema.json` beside this file.
+ *
+ * The JSON also lists each member's gates, read from its gate ledger on the
+ * same branch (#2674, `status-gates.ts`): the state of each, the approvals
+ * that count, and the `chant approve` line that answers it. The text view
+ * doesn't show them.
  */
 
 import { execFileSync } from "node:child_process";
@@ -27,11 +32,13 @@ import { existsSync, realpathSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
+import { GATES_DIR } from "../lifecycle/gate-ledger";
 import { readPathSha } from "../lifecycle/git";
 import { latestPerComponent, readReleaseLedger, type ReleaseRecord } from "../lifecycle/release-ledger";
 import { findWorkspaceRoot } from "../project-root";
 import { readDeclaration, readerVersion, WorkspaceReadError, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
 import { gitTop, workingTree } from "./tree";
 import { handToRootChant } from "./which-chant";
 
@@ -61,6 +68,9 @@ export const STATUS_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type StatusReasonCode = (typeof STATUS_REASON_CODES)[number];
 
+/** Why a member's gates can't be listed (#2674). Closed, like {@link STATUS_REASON_CODES}. */
+export const STATUS_GATE_REASON_CODES = GATE_REASON_CODES;
+
 /**
  * Why the status couldn't be read at all. The declaration's own codes, except
  * the two that only `--at` returns, and one for the environment name.
@@ -129,7 +139,12 @@ export interface StatusMember {
   environments: StatusEnvironment[];
   /** Null without `--compare-to`. */
   compare: StatusCompare | null;
+  /** True when no environment's release ledger has a reason. Gate reasons don't change it. */
   readable: boolean;
+  /** Where the member's gates were read from, and why none are listed when none can be (#2674). */
+  gateLedger: StatusGateLedger;
+  /** Each gate in the member's gate ledger, one per environment asked for, sorted by component then gate. */
+  gates: StatusGate[];
 }
 
 export type StatusDocument =
@@ -160,6 +175,10 @@ export interface StatusQuery {
   compareTo?: string;
   /** Reads one ledger; the lifecycle reader unless a test swaps it. */
   readLedger?: LedgerReader;
+  /** Reads one member's gate ledger directory; git unless a test swaps it. */
+  readGates?: GateLedgerReader;
+  /** The instant a gate's expiry is measured against; now by default. */
+  now?: string;
 }
 
 class StatusError extends Error {
@@ -192,9 +211,14 @@ function lifecycleTip(cwd: string): string | null {
   }
 }
 
+/** Whether the member writes under `_members/<member>/` (#2538). The root member never does. */
+async function hasMemberLedger(member: Member, cwd: string): Promise<boolean> {
+  return member.dir !== "." && (await readPathSha(MEMBERS_DIR, member.name, { cwd })) !== null;
+}
+
 /** Which ledger a member's releases for `env` are in (#2524 D7). */
 async function ledgerFor(member: Member, env: string, cwd: string): Promise<Omit<StatusLedger, "shared">> {
-  if (member.dir !== "." && (await readPathSha(MEMBERS_DIR, member.name, { cwd })) !== null) {
+  if (await hasMemberLedger(member, cwd)) {
     return { layout: "members", path: `${MEMBERS_DIR}/${member.name}/${env}/releases.jsonl` };
   }
   return { layout: "flat", path: `${env}/releases.jsonl` };
@@ -276,10 +300,15 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const read = query.readLedger ?? defaultReader;
     const envs = query.compareTo !== undefined && query.compareTo !== query.env ? [query.env, query.compareTo] : [query.env];
 
+    const commit = lifecycleTip(found.dir);
+    const now = query.now ?? new Date().toISOString();
+
     const members: StatusMember[] = [];
     for (const m of declaration.members) {
       const environments: StatusEnvironment[] = [];
       for (const env of envs) environments.push(await readEnvironment(m, env, found.dir, read));
+      const own = await hasMemberLedger(m, found.dir);
+      const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates);
       members.push({
         name: m.name,
         dir: m.dir,
@@ -287,18 +316,22 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
         environments,
         compare: query.compareTo === undefined ? null : compareEnvironments(environments[0], environments[environments.length - 1]),
         readable: environments.every((e) => e.reason === null),
+        gateLedger: gates.ledger,
+        gates: gates.gates,
       });
     }
     // Several members read from one flat ledger see the same records; say so.
     const readers = new Map<string, number>();
     for (const m of members) for (const e of m.environments) if (e.ledger.layout === "flat") readers.set(e.ledger.path, (readers.get(e.ledger.path) ?? 0) + 1);
     for (const m of members) for (const e of m.environments) e.ledger.shared = e.ledger.layout === "flat" && (readers.get(e.ledger.path) ?? 0) > 1;
+    const flatGates = members.filter((m) => m.gateLedger.layout === "flat").length;
+    for (const m of members) m.gateLedger.shared = m.gateLedger.layout === "flat" && flatGates > 1;
 
     return {
       ...head,
       env: query.env,
       compareTo: query.compareTo ?? null,
-      lifecycle: { ref: LIFECYCLE_REF, commit: lifecycleTip(found.dir) },
+      lifecycle: { ref: LIFECYCLE_REF, commit },
       workspace: { name: declaration.name, root: rootDir === "" ? "." : rootDir, file: declaration.file },
       members,
       summary: {

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

@@ -0,0 +1,232 @@
+/**
+ * #2687: sealed verdicts. A review counts under a signers file at base only
+ * when its reviewer signed it.
+ *
+ * Each case writes verdicts through `records review` and reads them back
+ * through the real `records` query, in a git repository whose base (`main`)
+ * holds the signers file, or doesn't. Every document is checked against its
+ * published schema.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterEach, describe, expect, test } from "vitest";
+import { parseArgs } from "../../cli/main";
+import recordsSchema from "../records.schema.json";
+import reviewSchema from "../records-review.schema.json";
+import { queryRecords, type RecordView } from "../records-cli";
+import { amendRecord, reviewRecord, runRecordsWrite, type ReviewDocument } from "../records-write";
+import type { QuorumVerdict } from "../records";
+import { REVIEW_SEAL_NAMESPACE, reviewSealPayload } from "./seal";
+import { hasSshKeygen, TestRepo, type Key } from "./test-repo";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..", "..");
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const KIND = "decisions/decision.kind.mjs";
+const FILE = "decisions/ws-003-seal-scope.md";
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validateRecords = ajv.compile(recordsSchema);
+const validateReview = ajv.compile(reviewSchema);
+
+const repos: TestRepo[] = [];
+afterEach(() => {
+  while (repos.length) repos.pop()!.cleanup();
+});
+
+/**
+ * A repository whose main holds ws-003 (decided by lex00) and, unless
+ * `signers` is false, a signers file listing alice and bob. The work happens
+ * on a branch, so main stays the base.
+ */
+function workspace(label: string, opts: { signers?: boolean } = {}) {
+  const r = new TestRepo(`seal-${label}`);
+  repos.push(r);
+  const alice = r.key("alice");
+  const bob = r.key("bob");
+  const mallory = r.key("mallory");
+  r.write(KIND, readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8"));
+  r.write("decisions/decision.schema.json", readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"));
+  r.write(FILE, readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+  if (opts.signers !== false) r.write(".chant/allowed_signers", `alice@example.test ${alice.pub}\nbob@example.test ${bob.pub}\n`);
+  r.commit("base", alice);
+  r.git(["checkout", "-q", "-b", "change"]);
+  return { r, alice, bob, mallory };
+}
+
+async function review(r: TestRepo, by: string, sign?: Key | string | true, verdict = "agree"): Promise<ReviewDocument> {
+  const doc = await reviewRecord({ kind: KIND, id: "ws-003", verdict, by, cwd: r.dir, on: "2026-09-24", ...(sign !== undefined ? { sign: typeof sign === "object" ? sign.file : sign } : {}) });
+  expect(validateReview(doc), JSON.stringify(validateReview.errors)).toBe(true);
+  return doc;
+}
+
+async function record(r: TestRepo): Promise<RecordView> {
+  const doc = await queryRecords({ kind: KIND, cwd: r.dir, base: "main" });
+  expect(validateRecords(doc), JSON.stringify(validateRecords.errors)).toBe(true);
+  if ("error" in doc) throw new Error(doc.error.message);
+  const rec = doc.records.find((x) => x.id === "ws-003")!;
+  expect(rec.reasons).toEqual([]);
+  return rec;
+}
+
+/** Every verdict, counted or not, in list order, as `reviewer:reason code:seal code`. */
+function verdicts(rec: RecordView): string[] {
+  const q = rec.quorum!;
+  return [...q.counted, ...q.notCounted]
+    .sort((a, b) => a.index - b.index)
+    .map((v: QuorumVerdict) => `${v.reviewer}:${v.reason?.code ?? "counted"}:${v.attestation.code ?? "attested"}`);
+}
+
+function verdict(rec: RecordView, index: number): QuorumVerdict {
+  const q = rec.quorum!;
+  return [...q.counted, ...q.notCounted].find((v) => v.index === index)!;
+}
+
+describe.skipIf(!hasSshKeygen)("sealed verdicts under a signers file at base", () => {
+  test("a sealed agree counts; an unsealed one, one by an unlisted principal and one signed with another's key do not", async () => {
+    const { r, alice, bob, mallory } = workspace("active");
+    const sealed = await review(r, "alice@example.test", alice);
+    if ("error" in sealed) throw new Error(sealed.error.message);
+    expect(sealed.review.seal).toMatchObject({ signer: "alice@example.test", key: expect.stringMatching(/^SHA256:/) });
+    await review(r, "bob@example.test");
+    await review(r, "mallory@example.test", mallory);
+    // alice's key, claiming to be bob.
+    await review(r, "Bob@Example.test ", alice);
+
+    const rec = await record(r);
+    expect(verdicts(rec)).toEqual([
+      "alice@example.test:counted:attested",
+      "bob@example.test:review-unattested:seal-missing",
+      "mallory@example.test:review-unattested:seal-signer-unlisted",
+      "Bob@Example.test :review-unattested:seal-signature-invalid",
+    ]);
+    const a = verdict(rec, 0);
+    expect(a.attested).toBe(true);
+    expect(a.attestation.key).toBe((sealed.review.seal as { key: string }).key);
+    expect(verdict(rec, 1)).toMatchObject({ attested: false, reason: { message: expect.stringMatching(/carries no seal/) } });
+    expect(verdict(rec, 2).reason!.message).toMatch(/mallory@example\.test has no key in \.chant\/allowed_signers at base/);
+    expect(verdict(rec, 3).reason!.message).toMatch(/does not verify for Bob@Example\.test/);
+    expect(rec.quorum).toMatchObject({ agreed: 1, met: false });
+    expect(bob).toBeDefined();
+  });
+
+  test("two sealed agrees meet the quorum", async () => {
+    const { r, alice, bob } = workspace("met");
+    await review(r, "alice@example.test", alice);
+    await review(r, "bob@example.test", bob);
+    const rec = await record(r);
+    expect(rec.quorum).toMatchObject({ agreed: 2, met: true, notCounted: [] });
+  });
+
+  test("an amendment leaves a sealed verdict on the older digest, and rewriting its digest breaks the seal", async () => {
+    const { r, alice } = workspace("amend");
+    await review(r, "alice@example.test", alice);
+    const before = await record(r);
+    const amended = await amendRecord({ kind: KIND, id: "ws-003", fields: JSON.stringify({ evidence: [] }), cwd: r.dir });
+    expect("error" in amended ? amended.error : null).toBeNull();
+
+    const after = await record(r);
+    expect(after.digest).not.toBe(before.digest);
+    // The seal still verifies over the text it judged; the verdict stops counting because the text moved.
+    expect(verdicts(after)).toEqual(["alice@example.test:review-older-digest:attested"]);
+
+    // Bringing the verdict up to date by hand, without a new signature.
+    const path = join(r.dir, FILE);
+    writeFileSync(path, readFileSync(path, "utf-8").replace(before.digest, after.digest));
+    const forged = await record(r);
+    expect(forged.digest).toBe(after.digest);
+    expect(verdicts(forged)).toEqual(["alice@example.test:review-unattested:seal-signature-invalid"]);
+    expect(verdict(forged, 0).attested).toBe(false);
+  });
+
+  test("attack: a seal lifted from another verdict, or made in the commit namespace, does not verify", async () => {
+    const { r, alice } = workspace("lift");
+    // An abstain, turned into an agree by hand: the seal covers the verdict.
+    await review(r, "alice@example.test", alice, "abstain");
+    const path = join(r.dir, FILE);
+    writeFileSync(path, readFileSync(path, "utf-8").replace('verdict: "abstain"', 'verdict: "agree"'));
+    let rec = await record(r);
+    expect(verdicts(rec)).toEqual(["alice@example.test:review-unattested:seal-signature-invalid"]);
+
+    // A good signature by alice over the right bytes, in the git namespace.
+    const text = readFileSync(path, "utf-8");
+    const payload = reviewSealPayload("ws-003", rec.digest, "agree", "alice@example.test", "2026-09-24");
+    const gitSig = r.sshSign(alice, payload, "git");
+    const current = /signature: ("[^"]*")/.exec(text)![1];
+    writeFileSync(path, text.replace(current, JSON.stringify(gitSig)));
+    rec = await record(r);
+    expect(verdicts(rec)).toEqual(["alice@example.test:review-unattested:seal-signature-invalid"]);
+
+    // The same bytes in the review namespace do verify, which shows it was the namespace.
+    writeFileSync(path, text.replace(current, JSON.stringify(r.sshSign(alice, payload, REVIEW_SEAL_NAMESPACE))));
+    rec = await record(r);
+    expect(verdicts(rec)).toEqual(["alice@example.test:counted:attested"]);
+  });
+
+  test("--sign with no file uses git's ssh user.signingkey", async () => {
+    const { r, bob } = workspace("gitkey");
+    r.git(["config", "gpg.format", "ssh"]);
+    r.git(["config", "user.signingkey", bob.file]);
+    const doc = await review(r, "bob@example.test", true);
+    expect("error" in doc ? doc.error : null).toBeNull();
+    expect(verdicts(await record(r))).toEqual(["bob@example.test:counted:attested"]);
+  });
+
+  test("a key that can't sign is refused with review-sign-failed, and nothing is written", async () => {
+    const { r } = workspace("nokey");
+    const before = readFileSync(join(r.dir, FILE), "utf-8");
+    const doc = await review(r, "alice@example.test", join(r.dir, "no-such-key"));
+    expect("error" in doc && doc.error.code).toBe("review-sign-failed");
+    r.git(["config", "gpg.format", "openpgp"]);
+    const git = await review(r, "alice@example.test", true);
+    expect("error" in git && git.error.message).toMatch(/gpg\.format openpgp/);
+    expect(readFileSync(join(r.dir, FILE), "utf-8")).toBe(before);
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("sealed verdicts with no signers file at base", () => {
+  test("an unsealed verdict counts, and a seal is checked for integrity and reported without gating", async () => {
+    const { r, alice, bob } = workspace("inactive", { signers: false });
+    await review(r, "carol");
+    await review(r, "alice@example.test", alice);
+    await review(r, "bob@example.test", bob, "abstain");
+    const path = join(r.dir, FILE);
+    // bob's abstain turned into an agree by hand: its seal no longer covers it.
+    writeFileSync(path, readFileSync(path, "utf-8").replace('verdict: "abstain"', 'verdict: "agree"'));
+    const rec = await record(r);
+    expect(verdicts(rec)).toEqual([
+      "carol:counted:seal-missing",
+      "alice@example.test:counted:seal-unverifiable",
+      "bob@example.test:counted:seal-signature-invalid",
+    ]);
+    expect(verdict(rec, 0).attested).toBeNull();
+    expect(verdict(rec, 1)).toMatchObject({ attested: null, attestation: { key: expect.stringMatching(/^SHA256:/), message: expect.stringMatching(/intact/) } });
+    expect(verdict(rec, 2).attested).toBe(false);
+    expect(rec.quorum).toMatchObject({ agreed: 3, met: true });
+  });
+});
+
+describe("--sign on the command line", () => {
+  test("takes a key file, or nothing for git's key", () => {
+    expect(parseArgs(["workspace", "records", "review", "ws-003", "--sign", "~/.ssh/id_ed25519", "--by", "a"]).sign).toBe("~/.ssh/id_ed25519");
+    expect(parseArgs(["workspace", "records", "review", "ws-003", "--sign", "--by", "a"]).sign).toBe(true);
+    expect(parseArgs(["workspace", "records", "review", "ws-003", "--by", "a", "--sign"]).sign).toBe(true);
+    expect(parseArgs(["workspace", "records", "review", "ws-003", "--by", "a"]).sign).toBeUndefined();
+  });
+
+  test("records new and amend refuse it: author seals are #2688", async () => {
+    const lines: string[] = [];
+    const log = console.log;
+    console.log = (s: string) => lines.push(s);
+    try {
+      for (const verb of ["new", "amend"]) {
+        const code = await runRecordsWrite({ args: { ...parseArgs(["workspace", "records", verb, "x", "--sign"]), extraPositional: verb, extraPositional2: "x" } } as never);
+        expect(code).toBe(1);
+      }
+    } finally {
+      console.log = log;
+    }
+    for (const l of lines) expect(JSON.parse(l).error).toMatchObject({ code: "write-usage-invalid", message: expect.stringMatching(/#2688/) });
+  });
+});

package/src/workspace/trust/seal.ts

@@ -0,0 +1,195 @@
+/**
+ * Sealed verdicts (#2687, part of #2547): a review entry signed by the
+ * principal it names, so the quorum counts it only when that principal
+ * signed it.
+ *
+ * A seal is a detached ssh signature, the same mechanism as the ssh-commit
+ * attestor (./ssh-commit.ts): `ssh-keygen -Y sign` to make it, and
+ * `ssh-keygen -Y verify` against the signers read at base to check it. It is
+ * made in its own namespace, `chant-review`, so neither a commit signature
+ * nor a signer-set signature can stand in for one.
+ *
+ * The signed bytes are the record id, the verdict's digest, the verdict, the
+ * reviewer and the date, each on its own line with no final newline. The
+ * digest is the record's text digest (`recordTextDigest`), so the seal binds
+ * the verdict to the text it judged. The seal lives inside the reviews block,
+ * which the digest leaves out, so sealing a verdict never moves the digest.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import type { SealCode } from "../records";
+import { type TrustPolicy } from "./policy";
+import { sshKeygen, verifySshSignature } from "./ssh-commit";
+
+/** The ssh signature namespace of a verdict seal. */
+export const REVIEW_SEAL_NAMESPACE = "chant-review";
+
+/** A seal as a review entry holds it. */
+export interface VerdictSeal {
+  /** The principal who signed: the reviewer, as the signers file names them. */
+  signer: string;
+  /** The signing key's fingerprint, such as `SHA256:...`. Reported, never trusted: the signature is the proof. */
+  key: string;
+  /** The armored ssh signature. */
+  signature: string;
+}
+
+/** What a verdict's seal establishes. */
+export interface SealCheck {
+  /** true: the seal verifies for the reviewer against the signers at base. false: it is missing under an active policy, or it fails. null: nothing here can say. */
+  attested: boolean | null;
+  /** Why it is not attested. Absent when `attested` is true. */
+  code?: SealCode;
+  message: string;
+  /** The fingerprint of the key that made the signature, when the signature was checked. */
+  key?: string;
+}
+
+/** The verdict a seal covers. */
+export interface SealedVerdict {
+  record: string | null;
+  reviewer: string;
+  verdict: string;
+  on: unknown;
+  digest: string | null;
+  seal: unknown;
+}
+
+/** The bytes a verdict seal signs. */
+export function reviewSealPayload(record: string, digest: string, verdict: string, reviewer: string, on: string): Buffer {
+  return Buffer.from(`${record}\n${digest}\n${verdict}\n${reviewer}\n${on}`, "utf-8");
+}
+
+const normalise = (name: string): string => name.normalize("NFKC").trim().toLowerCase();
+
+const FINGERPRINT = /key (SHA256:[A-Za-z0-9+/=]+)/;
+
+/**
+ * Check a verdict's seal. With a signers file active at base, it verifies
+ * against the keys listed there for the reviewer. With none, a seal present
+ * is checked for integrity only (`ssh-keygen -Y check-novalidate`): nothing
+ * says whose key it is.
+ */
+export function checkVerdictSeal(policy: TrustPolicy, v: SealedVerdict): SealCheck {
+  const where = `${policy.signersPath} at base`;
+  if (v.seal === undefined || v.seal === null) {
+    return policy.active
+      ? { attested: false, code: "seal-missing", message: `the verdict by ${v.reviewer} carries no seal` }
+      : { attested: null, code: "seal-missing", message: `the verdict by ${v.reviewer} carries no seal; there is no signers file at base, so none is needed` };
+  }
+  const seal = v.seal as Partial<Record<keyof VerdictSeal, unknown>>;
+  if (typeof seal !== "object" || Array.isArray(seal) || typeof seal.signer !== "string" || typeof seal.signature !== "string") {
+    return { attested: false, code: "seal-signature-invalid", message: `the seal on the verdict by ${v.reviewer} is malformed: it needs signer and signature` };
+  }
+  if (normalise(seal.signer) !== normalise(v.reviewer)) {
+    return { attested: false, code: "seal-signature-invalid", message: `the seal is by ${seal.signer}, and the verdict is ${v.reviewer}'s` };
+  }
+  if (v.record === null || v.digest === null || typeof v.on !== "string") {
+    return { attested: false, code: "seal-signature-invalid", message: `a seal covers the record id, the verdict's digest and on, and the verdict by ${v.reviewer} lacks one` };
+  }
+  const payload = reviewSealPayload(v.record, v.digest, v.verdict, v.reviewer, v.on);
+  if (!policy.active) return checkIntegrity(v.reviewer, payload, seal.signature);
+  const listed = policy.signers.filter((s) => normalise(s.principal) === normalise(v.reviewer));
+  if (listed.length === 0) {
+    return { attested: false, code: "seal-signer-unlisted", message: `${v.reviewer} has no key in ${where}, so the seal can't count` };
+  }
+  const r = verifySshSignature(listed, payload, seal.signature, REVIEW_SEAL_NAMESPACE);
+  if (r.ok) return { attested: true, message: `sealed by ${r.principal}${r.key ? ` with ${r.key}` : ""}, a signer ${where} lists`, ...(r.key ? { key: r.key } : {}) };
+  if (r.missing) return { attested: null, code: "seal-unverifiable", message: `the seal by ${v.reviewer} can't be checked here: ${r.reason}` };
+  return { attested: false, code: "seal-signature-invalid", message: `the seal does not verify for ${v.reviewer} against ${where}: ${r.reason}` };
+}
+
+/** A seal checked with no signers file: is the signature over these bytes intact? */
+function checkIntegrity(reviewer: string, payload: Buffer, signature: string): SealCheck {
+  const dir = mkdtempSync(join(tmpdir(), "chant-seal-"));
+  try {
+    const sigFile = join(dir, "signature");
+    writeFileSync(sigFile, signature);
+    const r = sshKeygen(["-Y", "check-novalidate", "-n", REVIEW_SEAL_NAMESPACE, "-s", sigFile], payload);
+    if (r.missing) return { attested: null, code: "seal-unverifiable", message: `the seal by ${reviewer} can't be checked here: ssh-keygen is not installed` };
+    if (r.status !== 0) {
+      return { attested: false, code: "seal-signature-invalid", message: `the seal by ${reviewer} does not verify over this verdict, even without a signers file` };
+    }
+    const key = FINGERPRINT.exec(r.stdout + r.stderr)?.[1];
+    return {
+      attested: null,
+      code: "seal-unverifiable",
+      message: `the signature is intact${key ? ` (${key})` : ""}, and there is no signers file at base to say whose key it is`,
+      ...(key ? { key } : {}),
+    };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Why a seal could not be made. */
+export class SealError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SealError";
+  }
+}
+
+/**
+ * The key `--sign` names: the file given, or with none, git's
+ * `user.signingkey` when `gpg.format` is `ssh`, as `git commit -S` reads it.
+ * A literal public key (`key::ssh-...`, or `ssh-...`) signs through the ssh
+ * agent holding its private half. Returns the file to pass to ssh-keygen,
+ * and a cleanup for a temporary one.
+ */
+export function resolveSigningKey(sign: string | true, cwd: string): { file: string; cleanup: () => void } {
+  const none = { cleanup: () => {} };
+  if (sign !== true) return { file: resolve(cwd, expandHome(sign)), ...none };
+  const config = (key: string): string | undefined => {
+    try {
+      return execFileSync("git", ["config", "--get", key], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    } catch {
+      return undefined;
+    }
+  };
+  const format = config("gpg.format");
+  const key = config("user.signingkey");
+  if (format !== "ssh" || key === undefined) {
+    throw new SealError(
+      `--sign with no key file uses git's user.signingkey when gpg.format is ssh, and git has ${format === "ssh" ? "no user.signingkey" : `gpg.format ${format ?? "unset"}`}; pass --sign <key file>`,
+    );
+  }
+  const literal = key.startsWith("key::") ? key.slice(5) : key.startsWith("ssh-") || key.startsWith("ecdsa-") || key.startsWith("sk-") ? key : undefined;
+  if (literal === undefined) return { file: resolve(cwd, expandHome(key)), ...none };
+  const dir = mkdtempSync(join(tmpdir(), "chant-sign-"));
+  const file = join(dir, "key.pub");
+  writeFileSync(file, `${literal}\n`);
+  return { file, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+function expandHome(path: string): string {
+  return path === "~" ? homedir() : path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+
+/**
+ * Seal a verdict with the key in `keyFile` (a private key, or a public key
+ * whose private half the ssh agent holds). Throws a {@link SealError}.
+ */
+export function sealVerdict(keyFile: string, v: { record: string; digest: string; verdict: string; reviewer: string; on: string }): VerdictSeal {
+  const payload = reviewSealPayload(v.record, v.digest, v.verdict, v.reviewer, v.on);
+  const signed = sshKeygen(["-q", "-Y", "sign", "-n", REVIEW_SEAL_NAMESPACE, "-f", keyFile], payload);
+  if (signed.missing) throw new SealError("--sign needs ssh-keygen, and it is not installed here");
+  if (signed.status !== 0 || !signed.stdout.startsWith("-----BEGIN SSH SIGNATURE-----")) {
+    throw new SealError(`ssh-keygen could not sign with ${keyFile}: ${signed.stderr.trim() || `exit ${signed.status}`}`);
+  }
+  // The fingerprint, read back from the signature itself.
+  const dir = mkdtempSync(join(tmpdir(), "chant-seal-"));
+  try {
+    const sigFile = join(dir, "signature");
+    writeFileSync(sigFile, signed.stdout);
+    const check = sshKeygen(["-Y", "check-novalidate", "-n", REVIEW_SEAL_NAMESPACE, "-s", sigFile], payload);
+    const key = FINGERPRINT.exec(check.stdout + check.stderr)?.[1];
+    if (check.status !== 0 || !key) throw new SealError(`the signature ssh-keygen made with ${keyFile} does not check: ${check.stderr.trim()}`);
+    return { signer: v.reviewer, key, signature: signed.stdout };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/workspace/trust/ssh-commit.ts

@@ -65,8 +65,8 @@ function objectFormat(repo: string): string {
   }
 }
 
-/** Run ssh-keygen; `missing` is true when it is not installed. */
-function sshKeygen(args: string[], input?: Buffer): { status: number | null; stdout: string; stderr: string; missing: boolean } {
+/** Run ssh-keygen; `missing` is true when it is not installed. Shared with the verdict seals (./seal.ts). */
+export function sshKeygen(args: string[], input?: Buffer): { status: number | null; stdout: string; stderr: string; missing: boolean } {
   const r = spawnSync("ssh-keygen", args, { input, encoding: "buffer", timeout: 30_000 });
   const missing = (r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
   return { status: r.status, stdout: r.stdout?.toString("utf-8") ?? "", stderr: r.stderr?.toString("utf-8") ?? "", missing };