@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/trust/signers-cli.ts

@@ -0,0 +1,178 @@
+/**
+ * `chant workspace signers [rotate [--threshold <n>] | sign --key <file>]`
+ * (#2553): show the signer history, and propose a new signer set.
+ *
+ * Rotating is three steps: edit the signers file, run `rotate` to write the
+ * rotation file for the next version, and have a threshold of the current
+ * signers each run `sign` with their own key. `chant workspace verify` then
+ * checks the result against the set at base.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { formatError, formatSuccess } from "../../cli/format";
+import type { CommandContext } from "../../cli/registry";
+import { readerVersion } from "../declaration";
+import type { ReasonCode } from "../reason-codes";
+import { gitRoot } from "../record-source";
+import { parseAllowedSigners, readTrustPolicy } from "./policy";
+import { resolveBase } from "./provenance";
+import { gitRevisionSource } from "../record-source";
+import {
+  distinctHolders,
+  rotationFileSchema,
+  rotationPath,
+  rotationStatement,
+  ROTATION_NAMESPACE,
+  signerHistory,
+  signersDigest,
+  type RotationFile,
+  type RotationRefusalCode,
+  type SignerHistory,
+} from "./rotation";
+import { verifySshSignature } from "./ssh-commit";
+
+const USAGE = "chant workspace signers [--base <rev>] [--json] | signers rotate [--threshold <n>] | signers sign --key <ssh private key>";
+
+export const SIGNERS_CONTRACT_VERSION = 1;
+export const SIGNERS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/signers/v1/signers.schema.json";
+
+/** Why `chant workspace signers` prints no history. Each is in `reason-codes.ts` and `signers.schema.json`. */
+export const SIGNERS_ERROR_CODES = ["not-a-git-repository", "revision-unknown", "signers-file-missing"] as const satisfies readonly ReasonCode[];
+export type SignersErrorCode = (typeof SIGNERS_ERROR_CODES)[number];
+
+/** What `chant workspace signers --json` prints. */
+export type SignersDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      base: string;
+      signersPath: string;
+      versions: Array<{ version: number; commit: string | null; digest: string | null; threshold: number; principals: string[]; signedBy: string[] }>;
+      broken: { commit: string | null; code: RotationRefusalCode; message: string } | null;
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: SignersErrorCode; message: string } };
+
+function head() {
+  return { $schema: SIGNERS_OUTPUT_SCHEMA_ID, contract: SIGNERS_CONTRACT_VERSION, chant: readerVersion() };
+}
+
+/** The signer history at `base` as the `--json` document. */
+export function signersDocument(repo: string, base: string, signersPath: string, history: SignerHistory): SignersDocument {
+  return {
+    ...head(),
+    base,
+    signersPath,
+    versions: history.versions.map((v) => ({
+      version: v.version,
+      commit: v.commit,
+      digest: v.version === 0 ? null : v.digest,
+      threshold: v.threshold,
+      principals: [...new Set(v.signers.map((s) => s.principal))].sort(),
+      signedBy: v.signedBy,
+    })),
+    broken: history.broken ? { commit: history.broken.commit, code: history.broken.code, message: history.broken.reason } : null,
+  };
+}
+
+function fail(message: string): number {
+  console.error(formatError({ message, hint: USAGE }));
+  return 1;
+}
+
+export async function runWorkspaceSigners(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const sub = args.extraPositional;
+  const refuse = (code: SignersErrorCode, message: string): number => {
+    if (args.json && !sub) console.log(JSON.stringify({ ...head(), error: { code, message } }, null, 2));
+    else console.error(formatError({ message, hint: USAGE }));
+    return 1;
+  };
+  const repo = gitRoot(process.cwd());
+  if (!repo) return refuse("not-a-git-repository", "signer history is read from git, and this directory is not in a git repository");
+  const base = resolveBase(repo, args.base);
+  if (!base.commit) return refuse("revision-unknown", base.problem ?? "no base revision");
+  // The policy as written at base; its history is checked below, not taken on trust.
+  const policy = readTrustPolicy(gitRevisionSource(repo, base.commit), base.commit);
+  if (!policy.active) return refuse("signers-file-missing", `there is no signers file (${policy.signersPath}) at base ${base.commit.slice(0, 8)}`);
+  const history = signerHistory(repo, base.commit, policy.signersPath);
+  const latest = history.versions.at(-1);
+
+  if (!sub) {
+    if (args.json) {
+      console.log(JSON.stringify(signersDocument(repo, base.commit, policy.signersPath, history), null, 2));
+      return history.broken ? 1 : 0;
+    }
+    for (const v of history.versions) {
+      if (v.version === 0) {
+        console.log(`  ${v.commit?.slice(0, 8)}  signers file removed`);
+        continue;
+      }
+      const by = v.signedBy.length ? `, signed by ${v.signedBy.join(", ")}` : ", the first version";
+      console.log(`  ${v.commit?.slice(0, 8)}  version ${v.version}: ${new Set(v.signers.map((s) => s.principal)).size} signers, threshold ${v.threshold}${by}`);
+    }
+    if (history.broken) return fail(`the history breaks at ${history.broken.commit?.slice(0, 8)} (${history.broken.code}): ${history.broken.reason}`);
+    return 0;
+  }
+  if (history.broken || !latest || latest.version === 0) return fail("the signer history at base is not valid, so there is no version to rotate from");
+
+  const signersFile = join(repo, policy.signersPath);
+  const rotationFile = join(repo, rotationPath(policy.signersPath));
+  const text = readFileSync(signersFile, "utf-8");
+
+  if (sub === "rotate") {
+    const threshold = args.threshold !== undefined ? Number(args.threshold) : latest.threshold;
+    if (!Number.isInteger(threshold) || threshold < 1) return fail("--threshold takes a whole number of at least 1");
+    const holders = distinctHolders(parseAllowedSigners(text).signers);
+    if (threshold > holders) return fail(`--threshold ${threshold} is more than the ${holders} distinct signers in the new set`);
+    const rotation: RotationFile = { schema: 1, version: latest.version + 1, previous: latest.digest, threshold, signatures: [] };
+    writeFileSync(rotationFile, JSON.stringify(rotation, null, 2) + "\n");
+    console.log(
+      formatSuccess(
+        `wrote ${rotationPath(policy.signersPath)} for version ${rotation.version}; ${latest.threshold} of the version ${latest.version} signers must now run chant workspace signers sign --key <their key>`,
+      ),
+    );
+    return 0;
+  }
+
+  if (sub === "sign") {
+    if (!args.key) return fail("--key <ssh private key> is required");
+    if (!existsSync(rotationFile)) return fail(`there is no ${rotationPath(policy.signersPath)}; run chant workspace signers rotate first`);
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(rotationFile, "utf-8"));
+    } catch {
+      return fail(`${rotationPath(policy.signersPath)} is not JSON`);
+    }
+    const parsed = rotationFileSchema.safeParse(raw);
+    if (!parsed.success) return fail(`${rotationPath(policy.signersPath)} is invalid`);
+    if (parsed.data.version !== latest.version + 1 || parsed.data.previous !== latest.digest) {
+      return fail(`${rotationPath(policy.signersPath)} is not the next version after version ${latest.version} at base; run chant workspace signers rotate again`);
+    }
+    const rotation = parsed.data;
+    const statement = rotationStatement(rotation, signersDigest(text));
+    let pub: string;
+    try {
+      pub = execFileSync("ssh-keygen", ["-y", "-f", args.key], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim().split(/\s+/).slice(0, 2).join(" ");
+    } catch (err) {
+      return fail(`ssh-keygen could not read ${args.key}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);
+    }
+    const me = latest.signers.find((s) => s.key === pub);
+    if (!me) return fail(`this key is not in version ${latest.version} of the signer set, so its signature would not count`);
+    let sig: string;
+    try {
+      sig = execFileSync("ssh-keygen", ["-q", "-Y", "sign", "-n", ROTATION_NAMESPACE, "-f", args.key], { input: statement, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    } catch (err) {
+      return fail(`ssh-keygen could not sign with ${args.key}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);
+    }
+    const check = verifySshSignature([me], statement, sig, ROTATION_NAMESPACE);
+    if (!check.ok) return fail(`the signature did not verify: ${check.reason}`);
+    rotation.signatures = [...rotation.signatures.filter((s) => s.principal !== me.principal), { principal: me.principal, signature: sig }];
+    writeFileSync(rotationFile, JSON.stringify(rotation, null, 2) + "\n");
+    console.log(formatSuccess(`signed version ${rotation.version} as ${me.principal} (${rotation.signatures.length} of ${latest.threshold} needed)`));
+    return 0;
+  }
+  return fail(`Unknown signers subcommand: ${sub}`);
+}

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

@@ -116,15 +116,19 @@ export const sshCommitAttestor: CommitAttestor = {
     const memo = `${ctx.repo}\0${commit}\0${renderAllowedSigners(signers)}`;
     const hit = cache.get(memo);
     if (hit) return hit;
-    const answer = attest(ctx.repo, commit, signers);
+    const raw = execFileSync("git", ["cat-file", "commit", commit], { cwd: ctx.repo, maxBuffer: 64 * 1024 * 1024 });
+    const answer = judgeRaw(raw, objectFormat(ctx.repo) === "sha256" ? "gpgsig-sha256" : "gpgsig", signers);
     cache.set(memo, answer);
     return answer;
   },
+  attestRaw(ctx: AttestorContext, raw: Buffer): CommitAttestation {
+    // A commit from another repository: its object format shows in its tree line.
+    const tree = /^tree ([0-9a-f]+)$/m.exec(raw.subarray(0, 200).toString("latin1"))?.[1];
+    return judgeRaw(raw, tree?.length === 64 ? "gpgsig-sha256" : "gpgsig", ctx.policy.signers);
+  },
 };
 
-function attest(repo: string, commit: string, signers: Signer[]): CommitAttestation {
-  const raw = execFileSync("git", ["cat-file", "commit", commit], { cwd: repo, maxBuffer: 64 * 1024 * 1024 });
-  const header = objectFormat(repo) === "sha256" ? "gpgsig-sha256" : "gpgsig";
+function judgeRaw(raw: Buffer, header: string, signers: Signer[]): CommitAttestation {
   const { payload, signature } = splitSignedCommit(raw, header);
   if (!signature) return { level: "unattested", attestor: NAME, reason: "the commit is not signed" };
   if (!signature.startsWith("-----BEGIN SSH SIGNATURE-----")) {
@@ -136,3 +140,48 @@ function attest(repo: string, commit: string, signers: Signer[]): CommitAttestat
   if (r.missing) return { level: "attested-unverifiable-here", attestor: NAME, reason: r.reason };
   return { level: "unattested", attestor: NAME, reason: r.reason };
 }
+
+/**
+ * The public key inside an armored ssh signature (the SSHSIG format), as
+ * `<type> <base64>`, or undefined when the text is not one. The key is what
+ * made the signature; whether anyone trusts it is a separate question.
+ */
+export function sshSignatureKey(signature: string): string | undefined {
+  const body = signature
+    .replace(/-----BEGIN SSH SIGNATURE-----/, "")
+    .replace(/-----END SSH SIGNATURE-----/, "")
+    .replace(/\s+/g, "");
+  let buf: Buffer;
+  try {
+    buf = Buffer.from(body, "base64");
+  } catch {
+    return undefined;
+  }
+  if (buf.length < 14 || buf.subarray(0, 6).toString("latin1") !== "SSHSIG") return undefined;
+  const len = buf.readUInt32BE(10);
+  const blob = buf.subarray(14, 14 + len);
+  if (blob.length !== len || len < 4) return undefined;
+  const typeLen = blob.readUInt32BE(0);
+  const type = blob.subarray(4, 4 + typeLen).toString("latin1");
+  if (!/^[a-z0-9@.-]+$/.test(type)) return undefined;
+  return `${type} ${blob.toString("base64")}`;
+}
+
+/**
+ * Whether an ssh signature over `payload` in `namespace` is intact, whoever
+ * made it (`ssh-keygen -Y check-novalidate`). Returns the key's fingerprint,
+ * false when it does not check, or null when ssh-keygen is not installed.
+ */
+export function sshSignatureIntact(payload: Buffer, signature: string, namespace: string): string | false | null {
+  const dir = mkdtempSync(join(tmpdir(), "chant-intact-"));
+  try {
+    const sigFile = join(dir, "signature");
+    writeFileSync(sigFile, signature);
+    const r = sshKeygen(["-Y", "check-novalidate", "-n", namespace, "-s", sigFile], payload);
+    if (r.missing) return null;
+    if (r.status !== 0) return false;
+    return /key (SHA256:[A-Za-z0-9+/=]+)/.exec(r.stdout + r.stderr)?.[1] ?? "";
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/workspace/trust/test-repo.ts

@@ -8,6 +8,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { ROTATION_NAMESPACE, rotationStatement, signersDigest } from "./rotation";
 
 export const hasSshKeygen = spawnSync("ssh-keygen", ["-Y"], { stdio: "ignore" }).error === undefined;
 
@@ -109,6 +110,23 @@ export class TestRepo {
   }
 }
 
+/**
+ * Write `<signers>.rotation.json` for the signers file now in the working
+ * tree, as the next version after `previousText`, signed by `by` in the
+ * rotation namespace (#2553).
+ */
+export function writeRotation(
+  repo: TestRepo,
+  opts: { previousText: string; version: number; threshold?: number; by: Array<[string, Key]>; namespace?: string; signersPath?: string },
+): void {
+  const path = opts.signersPath ?? ".chant/allowed_signers";
+  const text = readFileSync(join(repo.dir, path), "utf-8");
+  const rotation = { version: opts.version, previous: signersDigest(opts.previousText), threshold: opts.threshold ?? 1 };
+  const statement = rotationStatement(rotation, signersDigest(text));
+  const signatures = opts.by.map(([principal, key]) => ({ principal, signature: repo.sshSign(key, statement, opts.namespace ?? ROTATION_NAMESPACE) }));
+  repo.write(`${path}.rotation.json`, JSON.stringify({ schema: 1, ...rotation, signatures }, null, 2));
+}
+
 /** A record kind reading `records/*.md`, and its schema, written into `repo`. */
 export function writeRecordKind(repo: TestRepo): string {
   repo.write(

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

@@ -15,7 +15,7 @@ import { queryRecords, type RecordsDocument, type RecordView } from "../records-
 import { activeAttestors } from "./attestor";
 import { parseAllowedSigners } from "./policy";
 import { verifyChange } from "./verify";
-import { hasSshKeygen, note, TestRepo, writeRecordKind, type Key } from "./test-repo";
+import { hasSshKeygen, note, TestRepo, writeRecordKind, writeRotation, type Key } from "./test-repo";
 
 const repos: TestRepo[] = [];
 function repo(label: string): TestRepo {
@@ -90,8 +90,11 @@ describe.skipIf(!hasSshKeygen)("the ssh-commit attestor, against the policy at b
     const kind = writeRecordKind(r);
     r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob]));
     if (opts.admin) r.write(".chant/trust.json", JSON.stringify({ schema: 1, roles: { admin: ["alice@example.test"] } }));
+    r.commit("policy", alice);
+    // A separate commit: the one that adds the signers file is judged by the
+    // set before it, which is none (#2553), so it attests nothing itself.
     r.write("records/n1.md", note("n1"));
-    r.commit("policy and first record", alice);
+    r.commit("first record", alice);
     r.git(["checkout", "-q", "-b", "change"]);
     return { r, alice, bob, mallory, kind };
   }
@@ -181,7 +184,9 @@ describe.skipIf(!hasSshKeygen)("the ssh-commit attestor, against the policy at b
   test("attack: a backdated commit by a key removed from the signers before base", async () => {
     const { r, alice, bob, kind } = baseline("backdated-revoked");
     r.git(["checkout", "-q", "main"]);
+    const v1 = r.git(["show", "main:.chant/allowed_signers"]);
     r.write(".chant/allowed_signers", signers(["alice@example.test", alice]));
+    writeRotation(r, { previousText: v1, version: 2, by: [["alice@example.test", alice]] });
     r.commit("remove bob", alice);
     r.git(["checkout", "-q", "-b", "late"]);
     r.write("records/n2.md", note("n2"));
@@ -299,6 +304,7 @@ describe.skipIf(!hasSshKeygen)("the ssh-commit attestor, against the policy at b
 
     r.git(["reset", "-q", "--hard", "main"]);
     r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob], ["carol@example.test", r.key("carol2")]));
+    writeRotation(r, { previousText: r.git(["show", "main:.chant/allowed_signers"]), version: 2, by: [["alice@example.test", alice]] });
     r.commit("add carol", alice);
     report = await verify(r);
     expect(report.ok).toBe(true);

package/src/workspace/trust/verify-cli.ts

@@ -49,6 +49,7 @@ function printReport(r: ChangeReport): void {
     lines.push(`  ${c.commit.slice(0, 8)}  ${c.level}${who}  ${c.subject}${note}`);
   }
   for (const w of r.protectedWrites) lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
+  if (r.rotation && "to" in r.rotation) lines.push(`  signer set: version ${r.rotation.from} to ${r.rotation.to}, signed by ${r.rotation.signedBy.join(", ")}`);
   for (const n of r.notes) lines.push(n);
   console.log(lines.join("\n"));
   if (r.ok) console.log(formatSuccess(`verified ${r.commits.length} commits against the policy at base`));

package/src/workspace/trust/verify.ts

@@ -16,6 +16,7 @@ import { execFileSync } from "node:child_process";
 import { type CommitAttestor, type ProvenanceLevel } from "./attestor";
 import { policyAtBase, commitProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./provenance";
 import { policyWriters, protectedPaths, type ExcludedSigner, type TrustPolicy } from "./policy";
+import { fileAt, nextVersion, rotationPath, signerHistory, type RotationRefusalCode } from "./rotation";
 
 export interface CommitVerdict extends RecordProvenance {
   commit: string;
@@ -51,6 +52,12 @@ export interface ChangeReport {
   /** Protected paths whose content differs between the merge base and head. */
   protectedChanged: string[];
   protectedWrites: ProtectedWrite[];
+  /**
+   * When the change edits the signer set (#2553): the version it proposes and
+   * who signed it, or, when the new set is refused, the version it had to
+   * follow and why.
+   */
+  rotation: { from: number; to: number; signedBy: string[] } | { from: number; code: RotationRefusalCode; reason: string } | null;
   notes: string[];
   failures: string[];
   ok: boolean;
@@ -111,6 +118,7 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     protectedPaths: protectedPaths(policy),
     protectedChanged: [],
     protectedWrites: [],
+    rotation: null,
     notes: [],
     failures: [],
     ok: false,
@@ -183,6 +191,20 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     }
   }
 
+  // A new signer set must be signed by a threshold of the set at base (#2553).
+  const rotation = rotationPath(policy.signersPath);
+  if (changedPaths.includes(policy.signersPath) || changedPaths.includes(rotation)) {
+    const next = { signers: fileAt(repo, head, policy.signersPath), rotation: fileAt(repo, head, rotation) };
+    const latest = signerHistory(repo, base.commit, policy.signersPath).versions.at(-1);
+    if (next.signers !== undefined && latest && latest.version > 0) {
+      const v = nextVersion(latest, next, null);
+      if ("code" in v) {
+        report.rotation = { from: latest.version, code: v.code, reason: v.reason };
+        report.failures.push(`the signer set at head is not a valid rotation of the set at base (${v.code}): ${v.reason}`);
+      } else if (v !== latest) report.rotation = { from: latest.version, to: v.version, signedBy: v.signedBy };
+    }
+  }
+
   if (opts.require) {
     for (const v of report.commits) {
       if (v.skipped || v.level === opts.require) continue;

package/src/workspace/work-evidence.schema.json

@@ -182,11 +182,15 @@
                 "amend-supersede-instead",
                 "record-sign-failed",
                 "ratify-quorum-not-met",
+                "write-scope-member",
+                "write-scope-kind",
+                "agent-unknown",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",
                 "record-supersedes-unknown",
                 "record-supersedes-conflict",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record",
                 "work-kind-missing",