@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/trust/run-commits.js

@@ -0,0 +1,101 @@
+/**
+ * Which commits of a change agent runs made, and which of those a signed run
+ * statement covers (#3192), for `chant workspace verify`.
+ *
+ * A commit names its run by the `Chant-Run` trailer (ws-075), or a run's end
+ * lists it (ws-076). A run statement verified against the runner keys at
+ * base names the commits it covers as its subjects. Every `_agent-runs`
+ * directory on `chant/lifecycle` is read, the flat one and each member's,
+ * from the local branch or, when there is none, from `origin`'s copy. Nothing
+ * is fetched: CI fetches `chant/lifecycle` before it verifies.
+ */
+import { execFileSync } from "node:child_process";
+import { AGENT_RUNS_DIR, LEDGER_BRANCH, foldRun, parseRunFile, readRunFiles } from "../runs.js";
+import { RUN_TRAILER } from "../trailers.js";
+import { attestRun } from "./run-statement.js";
+function git(repo, args) {
+    try {
+        return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every run on the ledger, in every member's `_agent-runs`, and the ref and tip read. */
+export function readLedgerRuns(repo) {
+    for (const ref of [`refs/heads/${LEDGER_BRANCH}`, `refs/remotes/origin/${LEDGER_BRANCH}`]) {
+        const tip = git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])?.trim();
+        if (!tip)
+            continue;
+        const dirs = new Set();
+        for (const path of (git(repo, ["ls-tree", "-r", "--name-only", tip]) ?? "").split("\n")) {
+            const at = path.lastIndexOf(`${AGENT_RUNS_DIR}/`);
+            if (at >= 0 && (at === 0 || path[at - 1] === "/") && path.endsWith(".jsonl"))
+                dirs.add(path.slice(0, at + AGENT_RUNS_DIR.length));
+        }
+        const runs = [];
+        for (const dir of dirs) {
+            for (const [id, f] of readRunFiles(repo, dir, ref).files) {
+                const view = foldRun(id, f.path, parseRunFile(f.content, id).lines);
+                if (view)
+                    runs.push(view);
+            }
+        }
+        return { ref, tip, runs };
+    }
+    return { ref: null, tip: null, runs: [] };
+}
+/**
+ * Judge `commits` (the change, oldest first) against the run ledger: which
+ * ones runs made, and which of those a verified statement covers.
+ */
+export function changeRuns(repo, commits, runners) {
+    const { ref, runs } = readLedgerRuns(repo);
+    const out = { ledger: ref, runners: runners.map((r) => r.principal), commits: [] };
+    if (commits.length === 0)
+        return out;
+    const inChange = new Set(commits);
+    const naming = new Map();
+    const name = (sha, id) => (naming.get(sha) ?? naming.set(sha, new Set()).get(sha)).add(id);
+    // Trailers on the change's own commits.
+    const log = git(repo, ["log", "--no-walk=unsorted", `--format=%x00%H%x1f%(trailers:key=${RUN_TRAILER},valueonly,separator=%x1e)`, ...commits]) ?? "";
+    for (const rec of log.split("\0")) {
+        if (!rec.trim())
+            continue;
+        const [sha, values] = rec.split("\x1f");
+        for (const v of (values ?? "").split("\x1e").map((x) => x.trim()).filter(Boolean))
+            name(sha.trim(), v);
+    }
+    const covered = new Map();
+    for (const run of runs) {
+        for (const c of run.commits)
+            if (inChange.has(c.sha))
+                name(c.sha, run.id);
+        const a = attestRun(run, runners);
+        if (a.status !== "signed")
+            continue;
+        for (const sha of a.commits)
+            if (inChange.has(sha) && !covered.has(sha))
+                covered.set(sha, { run: run.id, signer: a.signer, class: a.class });
+    }
+    const byId = new Map(runs.map((r) => [r.id, r]));
+    for (const commit of commits) {
+        const ids = [...(naming.get(commit) ?? [])].sort();
+        const cover = covered.get(commit);
+        if (ids.length === 0 && !cover)
+            continue;
+        if (cover) {
+            out.commits.push({ commit, runs: ids, attested: true, run: cover.run, signer: cover.signer, class: cover.class, reason: `agent run ${cover.run}'s statement, signed by ${cover.signer} (${cover.class}), names this commit` });
+            continue;
+        }
+        const why = ids.map((id) => {
+            const r = byId.get(id);
+            if (!r)
+                return `${id} is not in the run ledger${ref ? "" : " (there is no chant/lifecycle branch here; fetch it)"}`;
+            const a = attestRun(r, runners);
+            return a.status === "signed" ? `${id}'s statement, signed by ${a.signer}, does not name this commit` : `${id}: ${a.reason}`;
+        });
+        out.commits.push({ commit, runs: ids, attested: false, reason: why.join("; ") });
+    }
+    return out;
+}

package/dist/workspace/trust/run-statement.js

@@ -0,0 +1,182 @@
+/**
+ * The agent-run statement (#3192, ws-090): a runner's or steward's signed
+ * word that an agent run happened as its record says.
+ *
+ * The run record (#3033, ws-076) is written by whatever ran the agent, so on
+ * its own it is as trustworthy as that writer. A statement is an in-toto
+ * Statement v1 in a DSSE envelope (./dsse.ts), signed with an Ed25519 key the
+ * trust policy at base lists under `runners` in `.chant/trust.json`, the same
+ * keys runner evidence uses (#2553, ws-069). A person's key, one the signers
+ * file lists, is never a runner key.
+ *
+ * - `subject`: each commit the run made, by its id (`digest.gitCommit`), with
+ *   its `git patch-id --stable` as an annotation when it has a patch.
+ * - `predicate`: the signer's principal, the run's id and the SHA-256 of its
+ *   record (the start and end lines), the work item, the harness, the model
+ *   and provider, and the principal the run worked for (studio-036 b).
+ *
+ * The statement is stored as a run-ledger fact: a `statement` line in the
+ * run's own file on `chant/lifecycle`, after its end. Verifying needs only
+ * the envelope, the run's record and the runner keys at base, so it works
+ * offline, and a verifier re-checks every stored statement rather than
+ * trusting that it was checked when written.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt.js";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope } from "./dsse.js";
+import { STATEMENT_TYPE } from "./evidence.js";
+export const AGENT_RUN_PREDICATE = "https://intentius.io/chant/agent-run/v1";
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+const fullCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const patchId = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const text = z.string().min(1);
+/** The statement a runner signs for a run. Strict, so a verifier never acts on a field it does not know. */
+export const runStatementSchema = z
+    .object({
+    _type: z.literal(STATEMENT_TYPE),
+    subject: z.array(z
+        .object({
+        name: fullCommit,
+        digest: z.object({ gitCommit: fullCommit }).strict(),
+        annotations: z.object({ patchId }).strict().optional(),
+    })
+        .strict()
+        .refine((s) => s.name === s.digest.gitCommit, "a commit subject is named by its own id")),
+    predicateType: z.literal(AGENT_RUN_PREDICATE),
+    predicate: z
+        .object({
+        signer: text,
+        run: z.object({ id: text, record: z.object({ sha256: sha256Hex }).strict() }).strict(),
+        unit: z.object({ id: text, kind: text.nullable() }).strict().nullable(),
+        harness: z.object({ name: text, version: text.nullable() }).strict(),
+        model: text.nullable(),
+        provider: text.nullable(),
+        by: text.nullable(),
+    })
+        .strict(),
+})
+    .strict();
+/**
+ * The SHA-256 of a run's record: the canonical JSON (keys sorted, no
+ * whitespace) of the array `[start line, end line]` as the ledger holds them.
+ * Statement lines are not part of it, so storing a statement never changes
+ * the hash it signs.
+ */
+export function runRecordDigest(start, end) {
+    return createHash("sha256").update(canonicalJson([start, end]), "utf8").digest("hex");
+}
+/** The statement for an ended run, as `signer` would sign it. The run's commits are its subjects, sorted by id. */
+export function buildRunStatement(run, signer) {
+    if (!run.record)
+        throw new Error(`agent run ${run.id} has not ended, so it has no record to sign`);
+    const commits = [...new Map(run.commits.map((c) => [c.sha, c])).values()].sort((a, b) => (a.sha < b.sha ? -1 : a.sha > b.sha ? 1 : 0));
+    return {
+        _type: STATEMENT_TYPE,
+        subject: commits.map((c) => ({ name: c.sha, digest: { gitCommit: c.sha }, ...(c.patchId ? { annotations: { patchId: c.patchId } } : {}) })),
+        predicateType: AGENT_RUN_PREDICATE,
+        predicate: {
+            signer,
+            run: { id: run.id, record: { sha256: run.record.sha256 } },
+            unit: run.unit ? { id: run.unit.id, kind: run.unit.kind } : null,
+            harness: { name: run.harness.name, version: run.harness.version },
+            model: run.model,
+            provider: run.provider,
+            by: run.by,
+        },
+    };
+}
+/** The payload bytes a signer signs: the statement's canonical JSON. Any serialization verifies; this one is reproducible. */
+export function runStatementPayload(statement) {
+    return Buffer.from(canonicalJson(statement), "utf8");
+}
+export function signRunStatement(statement, key, publicKey) {
+    return signEnvelope(IN_TOTO_PAYLOAD_TYPE, runStatementPayload(statement), key, publicKey);
+}
+// ── Verifying ────────────────────────────────────────────────────────────────
+/**
+ * Why a stored statement does not verify. Each is in `reason-codes.ts`.
+ * `envelope-invalid` and `envelope-untrusted` are runner evidence's codes:
+ * the envelope is the same, and so is the rule for its keys.
+ */
+export const RUN_STATEMENT_FAILURE_CODES = ["envelope-invalid", "envelope-untrusted", "run-statement-invalid", "run-statement-signer-mismatch", "run-statement-mismatch"];
+const same = (a, b) => canonicalJson(a ?? null) === canonicalJson(b ?? null);
+/**
+ * Verify one envelope for `run`: a signature by a runner key at base, a
+ * well-formed statement whose signer is that key's principal, for this run,
+ * and agreeing with its record. Never throws.
+ */
+export function verifyRunStatement(envelope, runners, run) {
+    const v = verifyEnvelope(envelope, runners);
+    if (!v.ok)
+        return { status: v.code === "envelope-untrusted" ? "untrusted" : "invalid", code: v.code, reason: v.reason };
+    const runner = runners.find((r) => r.principal === v.principal);
+    const signed = { signer: v.principal, class: runner.class, keyid: v.keyid };
+    if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE) {
+        return { status: "invalid", code: "run-statement-invalid", reason: `payload type ${v.payloadType} is not ${IN_TOTO_PAYLOAD_TYPE}`, ...signed };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(v.payload.toString("utf8"));
+    }
+    catch {
+        return { status: "invalid", code: "run-statement-invalid", reason: "the payload is not JSON", ...signed };
+    }
+    const parsed = runStatementSchema.safeParse(raw);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+        return { status: "invalid", code: "run-statement-invalid", reason: `the payload is not a ${AGENT_RUN_PREDICATE} statement: ${detail}`, ...signed };
+    }
+    const statement = parsed.data;
+    const p = statement.predicate;
+    // A runner cannot speak for another: the principal inside is the one whose key signed.
+    if (p.signer !== v.principal) {
+        return { status: "invalid", code: "run-statement-signer-mismatch", reason: `the statement names signer ${JSON.stringify(p.signer)}, but ${v.principal}'s key signed it`, ...signed };
+    }
+    const differs = [];
+    if (p.run.id !== run.id)
+        differs.push(`it is for run ${p.run.id}`);
+    else if (!run.record)
+        differs.push("the run has no end in the ledger");
+    else if (p.run.record.sha256 !== run.record.sha256)
+        differs.push(`the record hashed ${p.run.record.sha256.slice(0, 12)} when signed and ${run.record.sha256.slice(0, 12)} now`);
+    if (!same(p.unit, run.unit))
+        differs.push(`unit ${JSON.stringify(p.unit?.id ?? null)}, the record says ${JSON.stringify(run.unit?.id ?? null)}`);
+    if (!same(p.harness, run.harness))
+        differs.push(`harness ${JSON.stringify(p.harness.name)}, the record says ${JSON.stringify(run.harness.name)}`);
+    if (p.model !== run.model)
+        differs.push(`model ${JSON.stringify(p.model)}, the record says ${JSON.stringify(run.model)}`);
+    if (p.provider !== run.provider)
+        differs.push(`provider ${JSON.stringify(p.provider)}, the record says ${JSON.stringify(run.provider)}`);
+    if (p.by !== run.by)
+        differs.push(`by ${JSON.stringify(p.by)}, the record says ${JSON.stringify(run.by)}`);
+    if (differs.length > 0) {
+        return { status: "mismatch", code: "run-statement-mismatch", reason: `signed by ${v.principal}, but the statement does not match run ${run.id}'s record: ${differs.join("; ")}`, ...signed };
+    }
+    const n = statement.subject.length;
+    return { status: "verified", ...signed, statement, reason: `signed by ${v.principal} (${runner.class}) over the run's record and ${n} commit${n === 1 ? "" : "s"}` };
+}
+const RANK = { mismatch: 0, untrusted: 1, invalid: 2 };
+/** Judge every statement the ledger holds for `run`. */
+export function attestRun(run, runners) {
+    const verdicts = run.statements.map((s) => verifyRunStatement(s.envelope, runners, run));
+    const good = verdicts.find((v) => v.status === "verified");
+    if (good) {
+        return { status: "signed", signer: good.signer, class: good.class, keyid: good.keyid, code: null, reason: good.reason, commits: good.statement.subject.map((s) => s.name), statements: verdicts };
+    }
+    if (verdicts.length === 0) {
+        const reason = run.state === "running" ? "the run has not ended, and a statement is signed over an ended run" : "the ledger holds no statement for this run";
+        return { status: "unsigned", signer: null, class: null, keyid: null, code: null, reason, commits: [], statements: verdicts };
+    }
+    const worst = [...verdicts].sort((a, b) => RANK[a.status] - RANK[b.status])[0];
+    return {
+        status: worst.status,
+        signer: worst.signer ?? null,
+        class: worst.class ?? null,
+        keyid: worst.keyid ?? null,
+        code: worst.code,
+        reason: worst.reason,
+        commits: [],
+        statements: verdicts,
+    };
+}

package/dist/workspace/trust/seal.js

@@ -0,0 +1,272 @@
+/**
+ * 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.
+ *
+ * A record's author seal (#2688) works the same way, in its own namespace,
+ * `chant-record`. It sits in the record's top-level `seal` field, which the
+ * digest also leaves out, and signs the record id, the digest, the author
+ * (the kind's `reviews.decider` field, `decided_by` for decisions) and the
+ * state. An amendment moves the digest, so it has to be signed again.
+ */
+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 { sshKeygen, verifySshSignature } from "./ssh-commit.js";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshSignatureKey, verifySshSignatureWith } from "./gate-seal.js";
+export { GATE_SEAL_NAMESPACE, gateSealPayload } from "./gate-seal.js";
+/** The ssh signature namespace of a verdict seal. */
+export const REVIEW_SEAL_NAMESPACE = "chant-review";
+/** The ssh signature namespace of a record's author seal (#2688). */
+export const RECORD_SEAL_NAMESPACE = "chant-record";
+/** The bytes a verdict seal signs. */
+export function reviewSealPayload(record, digest, verdict, reviewer, on) {
+    return Buffer.from(`${record}\n${digest}\n${verdict}\n${reviewer}\n${on}`, "utf-8");
+}
+/**
+ * The bytes a record's author seal signs (#2688): the id, the digest, the
+ * author and the state, joined by LF with no final newline. A kind without
+ * states signs an empty last line.
+ */
+export function recordSealPayload(record, digest, author, state) {
+    return Buffer.from(`${record}\n${digest}\n${author}\n${state ?? ""}`, "utf-8");
+}
+const normalise = (name) => 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, v) {
+    const covered = v.record === null || v.digest === null || typeof v.on !== "string";
+    return checkSeal(policy, {
+        principal: v.reviewer,
+        what: `the verdict by ${v.reviewer}`,
+        role: "reviewer",
+        namespace: REVIEW_SEAL_NAMESPACE,
+        seal: v.seal,
+        payload: covered
+            ? `a seal covers the record id, the verdict's digest and on, and the verdict by ${v.reviewer} lacks one`
+            : reviewSealPayload(v.record, v.digest, v.verdict, v.reviewer, v.on),
+    });
+}
+/**
+ * Check a record's author seal (#2688), as a verdict's is checked, over
+ * {@link recordSealPayload} in the `chant-record` namespace. A record that
+ * names no author and carries no seal is `seal-missing` with `attested`
+ * null even under an active policy: it claims no author to attest.
+ */
+export function checkRecordSeal(policy, r) {
+    const what = r.record ?? "the record";
+    if (r.author === null && (r.seal === undefined || r.seal === null)) {
+        return { attested: null, code: "seal-missing", message: `${what} names no ${r.authorField}, so it claims no author to seal` };
+    }
+    return checkSeal(policy, {
+        principal: r.author ?? "",
+        what,
+        role: r.authorField,
+        namespace: RECORD_SEAL_NAMESPACE,
+        seal: r.seal,
+        payload: r.record === null || r.author === null
+            ? `a record's seal covers its id and its ${r.authorField}, and ${what} lacks one`
+            : recordSealPayload(r.record, r.digest, r.author, r.state),
+    });
+}
+/**
+ * Check a gate approval's seal (#3163), as a verdict's is checked, over
+ * {@link gateSealPayload} in the `chant-gate` namespace: it verifies only
+ * when the signers file at base lists a key for the approver.
+ */
+export function checkGateSeal(policy, a) {
+    return checkSeal(policy, {
+        principal: a.resolvedBy,
+        what: `the approval of gate ${a.gate} by ${a.resolvedBy}`,
+        role: "approver",
+        namespace: GATE_SEAL_NAMESPACE,
+        seal: a.seal,
+        payload: gateSealPayload(a),
+    });
+}
+function checkSeal(policy, s) {
+    const where = `${policy.signersPath} at base`;
+    if (s.seal === undefined || s.seal === null) {
+        return policy.active
+            ? { attested: false, code: "seal-missing", message: `${s.what} carries no seal` }
+            : { attested: null, code: "seal-missing", message: `${s.what} carries no seal; there is no signers file at base, so none is needed` };
+    }
+    const seal = s.seal;
+    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 ${s.what} is malformed: it needs signer and signature` };
+    }
+    if (normalise(seal.signer) !== normalise(s.principal)) {
+        return {
+            attested: false,
+            code: "seal-signature-invalid",
+            message: s.role === "reviewer" ? `the seal is by ${seal.signer}, and the verdict is ${s.principal}'s` : `the seal on ${s.what} is by ${seal.signer}, and its ${s.role} is ${s.principal || "empty"}`,
+        };
+    }
+    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` };
+    }
+    const r = s.namespace === GATE_SEAL_NAMESPACE ? verifyGate(listed, s.payload, seal.signature) : verifySshSignature(listed, s.payload, seal.signature, s.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 ${s.principal} can't be checked here: ${r.reason}` };
+    return { attested: false, code: "seal-signature-invalid", message: `the seal does not verify for ${s.principal} against ${where}: ${r.reason}` };
+}
+/** A gate seal checked with node:crypto (#3785) against the keys `listed` for the approver in the gate namespace. */
+function verifyGate(listed, payload, signature) {
+    const keys = listed.filter((x) => namespaceAllowed(x.namespaces, GATE_SEAL_NAMESPACE)).map((x) => Buffer.from(x.key.split(" ")[1] ?? "", "base64"));
+    const r = verifySshSignatureWith(signature, payload, GATE_SEAL_NAMESPACE, keys);
+    return r.ok ? { ok: true, principal: listed[0].principal, key: r.key } : { ok: false, reason: r.reason };
+}
+/** A seal checked with no signers file: is the signature over these bytes intact? */
+function checkIntegrity(principal, payload, signature, namespace) {
+    if (namespace === GATE_SEAL_NAMESPACE) {
+        // A gate seal is checked with node:crypto (#3785), against the key it carries.
+        const pk = sshSignatureKey(signature);
+        const r = pk ? verifySshSignatureWith(signature, payload, namespace, [pk]) : { ok: false, reason: "it is not an SSHSIG" };
+        if (!r.ok)
+            return { attested: false, code: "seal-signature-invalid", message: `the seal by ${principal} does not verify over this approval, even without a signers file` };
+        return { attested: null, code: "seal-unverifiable", message: `the signature is intact (${r.key}), and there is no signers file at base to say whose key it is`, key: r.key };
+    }
+    const dir = mkdtempSync(join(tmpdir(), "chant-seal-"));
+    try {
+        const sigFile = join(dir, "signature");
+        writeFileSync(sigFile, signature);
+        const r = sshKeygen(["-Y", "check-novalidate", "-n", namespace, "-s", sigFile], payload);
+        if (r.missing)
+            return { attested: null, code: "seal-unverifiable", message: `the seal by ${principal} 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 ${principal} does not verify over ${namespace === RECORD_SEAL_NAMESPACE ? "this record" : namespace === GATE_SEAL_NAMESPACE ? "this approval" : "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) {
+        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, cwd) {
+    const none = { cleanup: () => { } };
+    if (sign !== true)
+        return { file: resolve(cwd, expandHome(sign)), ...none };
+    const config = (key) => {
+        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) {
+    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, v) {
+    return sign(keyFile, reviewSealPayload(v.record, v.digest, v.verdict, v.reviewer, v.on), REVIEW_SEAL_NAMESPACE, v.reviewer);
+}
+/**
+ * Seal a record's author (#2688) with the key in `keyFile`, over
+ * {@link recordSealPayload}. Throws a {@link SealError}.
+ */
+export function sealRecord(keyFile, r) {
+    return sign(keyFile, recordSealPayload(r.record, r.digest, r.author, r.state), RECORD_SEAL_NAMESPACE, r.author);
+}
+/**
+ * Seal a gate approval (#3163) with the key in `keyFile`, over
+ * {@link gateSealPayload}. Throws a {@link SealError}.
+ */
+export function sealGateApproval(keyFile, a) {
+    return sign(keyFile, gateSealPayload(a), GATE_SEAL_NAMESPACE, a.resolvedBy);
+}
+function sign(keyFile, payload, namespace, signer) {
+    const signed = sshKeygen(["-q", "-Y", "sign", "-n", 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", 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, key, signature: signed.stdout };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}