@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/trust/evidence-cli.js

@@ -0,0 +1,175 @@
+/**
+ * `chant workspace evidence sign|verify` (#2553): runner evidence over the
+ * records a kind locates, in a DSSE envelope. See ./evidence.ts.
+ *
+ * `sign` runs in CI or in a service, with a runner key the policy at base
+ * lists. It refuses a key the signers file lists: evidence is a machine's
+ * statement, and a developer's key cannot make one. `verify` needs no
+ * network and no key, only the envelope and the repository.
+ *
+ * With `--json`, `verify` prints the `evidence.schema.json` document, and a
+ * refused `sign` prints its failure branch.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { formatError, formatSuccess } from "../../cli/format.js";
+import { readerVersion } from "../declaration.js";
+import { gitRevisionSource, gitRoot } from "../record-source.js";
+import { loadRecordKind, readRecords, RecordReadError } from "../records.js";
+import { loadRunnerKey } from "./dsse.js";
+import { buildStatement, signEvidence, verifyEvidence, EVIDENCE_ERROR_CODES } from "./evidence.js";
+import { policyAtBase, resolveBase } from "./provenance.js";
+export const EVIDENCE_CONTRACT_VERSION = 1;
+export const EVIDENCE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json";
+const USAGE = "chant workspace evidence sign --kind <kind file> --key <runner key.pem> --check-id <id> [--claim <file>] [--environment <file>] [--at <rev>] [--base <rev>] [--output <file>] [--json]\n" +
+    "  chant workspace evidence verify --envelope <file> [--at <rev>] [--base <rev>] [--json]";
+function head() {
+    return { $schema: EVIDENCE_OUTPUT_SCHEMA_ID, contract: EVIDENCE_CONTRACT_VERSION, chant: readerVersion() };
+}
+function report(json, at, error, usage = false) {
+    if (json)
+        console.log(JSON.stringify({ ...head(), at, error }, null, 2));
+    else
+        console.error(formatError({ message: `${error.message} (${error.code})`, ...(usage ? { hint: USAGE } : {}) }));
+    return 1;
+}
+function usage(message) {
+    console.error(formatError({ message, hint: USAGE }));
+    return 1;
+}
+function commitOf(repo, rev) {
+    return resolveBase(repo, rev).commit ?? undefined;
+}
+export async function runWorkspaceEvidence(ctx) {
+    const { args } = ctx;
+    const sub = args.extraPositional;
+    if (sub !== "sign" && sub !== "verify")
+        return usage(sub ? `Unknown evidence subcommand: ${sub}` : "chant workspace evidence needs sign or verify");
+    const repo = gitRoot(process.cwd());
+    if (!repo)
+        return report(args.json, null, { code: "not-a-git-repository", message: "runner evidence is bound to git commits, and this directory is not in a git repository" });
+    return sub === "sign" ? sign(ctx, repo) : verify(ctx, repo);
+}
+/**
+ * Build and sign evidence, or say why not. Refuses a key the signers file
+ * lists, and a key the policy at base does not list as a runner.
+ */
+export async function signRecordsEvidence(req) {
+    const { repo } = req;
+    const at = commitOf(repo, req.at ?? "HEAD");
+    if (!at)
+        return { error: { code: "revision-unknown", message: `--at ${req.at ?? "HEAD"} names no commit` } };
+    const policy = policyAtBase(repo, resolveBase(repo, req.base));
+    if (policy.problems.length > 0)
+        return { error: { code: "trust-policy-unreadable", message: `the policy at base cannot be read: ${policy.problems.join("; ")}` } };
+    let runner;
+    try {
+        runner = loadRunnerKey(req.keyPem);
+    }
+    catch (err) {
+        return { error: { code: "runner-key-invalid", message: `the key is not an Ed25519 private key in PEM: ${err instanceof Error ? err.message : String(err)}` } };
+    }
+    if (policy.signers.some((s) => s.key === runner.publicKey)) {
+        return {
+            error: {
+                code: "runner-key-is-signer",
+                message: `this is a signer's key in ${policy.signersPath}. Runner evidence is signed by a service or CI identity, never by a person's key`,
+            },
+        };
+    }
+    const listed = policy.runners.find((r) => r.key === runner.publicKey);
+    if (!listed) {
+        return { error: { code: "runner-key-unlisted", message: `the policy at base lists no runner with this key. Add it to .chant/trust.json "runners" first:\n  ${runner.publicKey}` } };
+    }
+    let paths;
+    try {
+        const loaded = await loadRecordKind(req.kind, req.cwd);
+        const read = await readRecords(loaded, { root: repo, source: gitRevisionSource(repo, at) });
+        paths = read.records.map((r) => r.path);
+    }
+    catch (err) {
+        if (err instanceof RecordReadError && EVIDENCE_ERROR_CODES.includes(err.code)) {
+            return { error: { code: err.code, message: err.message } };
+        }
+        throw err;
+    }
+    const statement = buildStatement({
+        repo,
+        commit: at,
+        paths,
+        runner: listed.principal,
+        check: req.checkId,
+        ...(req.claim ? { claim: req.claim } : {}),
+        ...(req.environment ? { environment: req.environment } : {}),
+    });
+    return { envelope: signEvidence(statement, runner.key, runner.publicKey), statement, runner: listed.principal };
+}
+async function sign(ctx, repo) {
+    const { args } = ctx;
+    if (!args.kind || !args.key || !args.checkId)
+        return usage("--kind, --key and --check-id are required");
+    const r = await signRecordsEvidence({
+        repo,
+        kind: args.kind,
+        cwd: process.cwd(),
+        keyPem: readFileSync(args.key, "utf-8"),
+        checkId: args.checkId,
+        at: args.at,
+        base: args.base,
+        ...(args.claim ? { claim: readFileSync(args.claim) } : {}),
+        ...(args.environment ? { environment: readFileSync(args.environment) } : {}),
+    });
+    if ("error" in r)
+        return report(args.json, null, r.error);
+    const envelope = JSON.stringify(r.envelope, null, 2) + "\n";
+    if (args.output) {
+        writeFileSync(args.output, envelope);
+        console.error(formatSuccess(`signed evidence for ${r.statement.subject.length} records at ${r.statement.predicate.commit.slice(0, 8)} as ${r.runner}: ${args.output}`));
+    }
+    else {
+        process.stdout.write(envelope);
+    }
+    return 0;
+}
+/** Verify an envelope file at `at` against the runner keys at base, as the document `--json` prints. */
+export function verifyEvidenceFile(repo, envelopePath, opts = {}) {
+    const at = commitOf(repo, opts.at ?? "HEAD");
+    if (!at)
+        return { ...head(), at: null, error: { code: "revision-unknown", message: `--at ${opts.at ?? "HEAD"} names no commit` } };
+    const policy = policyAtBase(repo, resolveBase(repo, opts.base));
+    if (policy.problems.length > 0) {
+        return { ...head(), at, error: { code: "trust-policy-unreadable", message: `the policy at base cannot be read: ${policy.problems.join("; ")}` } };
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(readFileSync(envelopePath, "utf-8"));
+    }
+    catch (err) {
+        return { ...head(), at, error: { code: "envelope-unreadable", message: `--envelope ${envelopePath} could not be read as JSON: ${err instanceof Error ? err.message : String(err)}` } };
+    }
+    const verdict = verifyEvidence(envelope, policy.runners, repo, at);
+    if (!verdict.ok)
+        return { ...head(), at, error: { code: verdict.code, message: verdict.reason } };
+    return { ...head(), at, ...verdict };
+}
+async function verify(ctx, repo) {
+    const { args } = ctx;
+    if (!args.envelope)
+        return usage("--envelope <file> is required");
+    const doc = verifyEvidenceFile(repo, args.envelope, { at: args.at, base: args.base });
+    if ("error" in doc)
+        return report(args.json, doc.at, doc.error);
+    if (args.json) {
+        console.log(JSON.stringify(doc, null, 2));
+    }
+    else {
+        for (const s of doc.subjects)
+            console.log(`  ${s.matches ? "same   " : "changed"}  ${s.name}`);
+        const p = doc.statement.predicate;
+        const line = `evidence from ${doc.runner} (${doc.class}) for check ${p.check} at ${p.commit.slice(0, 8)}: ${doc.status} at ${doc.at.slice(0, 8)}`;
+        if (doc.status === "current")
+            console.log(formatSuccess(line));
+        else
+            console.error(formatError({ message: line, hint: "evidence is not reused for records that changed; run the check again" }));
+    }
+    return doc.status === "current" ? 0 : 1;
+}

package/dist/workspace/trust/evidence.js

@@ -0,0 +1,161 @@
+/**
+ * Runner evidence (#2553, #2524 D5 "Evidence").
+ *
+ * A runner, meaning a CI job or a service, states that a check ran over a
+ * set of records at one commit. The statement is an in-toto Statement v1:
+ * each record is a subject, named by its path and hashed, and the predicate
+ * binds the commit, its tree, the check, and the digests of the claim and of
+ * the environment when given. The runner signs it in a DSSE envelope with its
+ * own Ed25519 key.
+ *
+ * Verifying needs only the envelope, the repository's objects and the runner
+ * keys the policy at base lists, so it works offline. Evidence is never
+ * reused on trust: a verdict reports, subject by subject, whether the records
+ * still hash the same, and evidence for records that changed is `stale`.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt.js";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope } from "./dsse.js";
+export const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+export const RUNNER_EVIDENCE_PREDICATE = "https://intentius.io/chant/runner-evidence/v1";
+/**
+ * Why evidence is refused, by `evidence sign` or `evidence verify` (#2553).
+ * Each is in `reason-codes.ts` and in `evidence.schema.json`. A sign or verify
+ * that can't read the record kind fails with the records read's own code.
+ */
+export const EVIDENCE_ERROR_CODES = [
+    "not-a-git-repository",
+    "revision-unknown",
+    "trust-policy-unreadable",
+    "envelope-unreadable",
+    "envelope-invalid",
+    "envelope-untrusted",
+    "evidence-payload-type",
+    "evidence-statement-invalid",
+    "evidence-runner-mismatch",
+    "runner-key-invalid",
+    "runner-key-is-signer",
+    "runner-key-unlisted",
+    "kind-unreadable",
+    "kind-invalid",
+    "schema-unreadable",
+    "schema-id-mismatch",
+    "schema-invalid",
+    "location-missing",
+];
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+const fullCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+/** The statement a runner signs. Strict, so a verifier never acts on a field it does not know. */
+export const evidenceStatementSchema = z
+    .object({
+    _type: z.literal(STATEMENT_TYPE),
+    subject: z
+        .array(z
+        .object({
+        name: z
+            .string()
+            .min(1)
+            .refine((n) => !n.startsWith("/") && !n.split("/").includes(".."), "a path inside the repository"),
+        digest: z.object({ sha256: sha256Hex }).strict(),
+    })
+        .strict()),
+    predicateType: z.literal(RUNNER_EVIDENCE_PREDICATE),
+    predicate: z
+        .object({
+        runner: z.string().min(1),
+        commit: fullCommit,
+        tree: fullCommit,
+        check: z.string().min(1),
+        claim: z.object({ sha256: sha256Hex }).strict().optional(),
+        environment: z.object({ sha256: sha256Hex }).strict().optional(),
+    })
+        .strict(),
+})
+    .strict();
+/** SHA-256 of a record's text, line endings normalised as seals do (#2524 D4). */
+export function recordHash(text) {
+    return createHash("sha256").update(text.replace(/\r\n?/g, "\n"), "utf8").digest("hex");
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function git(repo, args) {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+function blobAt(repo, commit, path) {
+    try {
+        return git(repo, ["cat-file", "blob", `${commit}:${path}`]);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildStatement(input) {
+    const subject = [...input.paths].sort().map((name) => {
+        const text = blobAt(input.repo, input.commit, name);
+        if (text === undefined)
+            throw new Error(`${name} is not in commit ${input.commit.slice(0, 8)}`);
+        return { name, digest: { sha256: recordHash(text) } };
+    });
+    return {
+        _type: STATEMENT_TYPE,
+        subject,
+        predicateType: RUNNER_EVIDENCE_PREDICATE,
+        predicate: {
+            runner: input.runner,
+            commit: input.commit,
+            tree: git(input.repo, ["rev-parse", `${input.commit}^{tree}`]).trim(),
+            check: input.check,
+            ...(input.claim ? { claim: { sha256: sha256(input.claim) } } : {}),
+            ...(input.environment ? { environment: { sha256: sha256(input.environment) } } : {}),
+        },
+    };
+}
+export function signEvidence(statement, key, publicKey) {
+    return signEnvelope(IN_TOTO_PAYLOAD_TYPE, Buffer.from(canonicalJson(statement), "utf8"), key, publicKey);
+}
+/**
+ * Verify an envelope against the runner keys at base, then compare each
+ * subject with the record as committed at `at`.
+ */
+export function verifyEvidence(envelope, runners, repo, at) {
+    const v = verifyEnvelope(envelope, runners);
+    if (!v.ok)
+        return v;
+    if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE)
+        return { ok: false, code: "evidence-payload-type", reason: `payload type ${v.payloadType} is not ${IN_TOTO_PAYLOAD_TYPE}` };
+    let raw;
+    try {
+        raw = JSON.parse(v.payload.toString("utf8"));
+    }
+    catch {
+        return { ok: false, code: "evidence-statement-invalid", reason: "the payload is not JSON" };
+    }
+    const parsed = evidenceStatementSchema.safeParse(raw);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+        return { ok: false, code: "evidence-statement-invalid", reason: `the payload is not a ${RUNNER_EVIDENCE_PREDICATE} statement: ${detail}` };
+    }
+    const statement = parsed.data;
+    // The runner named inside must be the one whose key signed: a runner cannot speak for another.
+    if (statement.predicate.runner !== v.principal) {
+        return { ok: false, code: "evidence-runner-mismatch", reason: `the statement names runner ${JSON.stringify(statement.predicate.runner)}, but ${v.principal}'s key signed it` };
+    }
+    const subjects = statement.subject.map((s) => {
+        const text = blobAt(repo, at, s.name);
+        const now = text === undefined ? null : recordHash(text);
+        return { name: s.name, signed: s.digest.sha256, now, matches: now !== null && now === s.digest.sha256 };
+    });
+    const runner = runners.find((r) => r.principal === v.principal);
+    return {
+        ok: true,
+        status: subjects.every((s) => s.matches) ? "current" : "stale",
+        runner: v.principal,
+        class: runner.class,
+        keyid: v.keyid,
+        statement,
+        subjects,
+    };
+}

package/dist/workspace/trust/gate-seal.js

@@ -0,0 +1,226 @@
+/**
+ * A gate approval's seal (#3163, ws-080), checked with node:crypto (#3763).
+ *
+ * `chant approve --sign` seals an approval with `ssh-keygen -Y sign` in the
+ * `chant-gate` namespace, over {@link gateSealPayload}. Signing shells to
+ * ssh-keygen; checking does not. This module checks a seal with node:crypto
+ * and no zod, and `checkGateSeal` (`./seal.ts`) and `sealedApprovalRule` use
+ * it, so an apply job needs no ssh-keygen. A tool that decides a gate from one bundled file
+ * (terragucci's apply job) runs the same rule: `@intentius/chant/gate-decision`
+ * exports it.
+ *
+ * An SSHSIG (OpenSSH's PROTOCOL.sshsig) holds the public key, the namespace,
+ * the hash algorithm and the signature over `"SSHSIG"`, the namespace, the
+ * reserved field, the algorithm and the message's hash. Ed25519, ECDSA (P-256,
+ * P-384, P-521), RSA with SHA-2, and the security-key forms of Ed25519 and
+ * P-256 verify, with the touch flag required, as ssh-keygen requires it for a
+ * signers line with no `no-touch-required` option (which the signers parser
+ * does not accept). An RSA signature over SHA-1 does not verify.
+ */
+import { createHash, createPublicKey, verify } from "node:crypto";
+/**
+ * The ssh signature namespace of a gate approval's seal (#3163, ws-080), so a
+ * verdict, record or commit signature can't stand in for one.
+ */
+export const GATE_SEAL_NAMESPACE = "chant-gate";
+/**
+ * The bytes a gate approval's seal signs (#3163): the op (or component), the
+ * gate, the environment, the plan digest, the approver and the time, joined
+ * by LF with no final newline. An approval that binds no environment or plan
+ * signs an empty line for it. A relayed approval (#3402) signs a seventh line,
+ * `relayed-by <principal>`, so the relay can't be added, changed or removed
+ * after sealing; an approval nobody relayed signs the six lines it always did,
+ * so seals made before #3402 still verify.
+ */
+export function gateSealPayload(a) {
+    const relay = a.relayedBy !== undefined ? `\nrelayed-by ${a.relayedBy}` : "";
+    return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}${relay}`, "utf-8");
+}
+// ── SSHSIG ───────────────────────────────────────────────────────────────
+/** A reader over ssh wire format: `take(n)` bytes, or `take()` one length-prefixed string. */
+function reader(buf) {
+    let at = 0;
+    const take = (n) => {
+        const len = n ?? take(4).readUInt32BE(0);
+        if (at + len > buf.length)
+            throw new Error("the signature is truncated");
+        return buf.subarray(at, (at += len));
+    };
+    return take;
+}
+const wire = (b) => {
+    const v = Buffer.from(b);
+    const n = Buffer.alloc(4);
+    n.writeUInt32BE(v.length);
+    return Buffer.concat([n, v]);
+};
+const hash = (alg, b) => createHash(alg).update(b).digest();
+const b64url = (b) => b.toString("base64url");
+/** An mpint without its sign byte, left-padded to `size` bytes when given. */
+const unsigned = (b, size) => {
+    let v = b;
+    while (v.length > 1 && v[0] === 0)
+        v = v.subarray(1);
+    return size === undefined || v.length >= size ? v : Buffer.concat([Buffer.alloc(size - v.length), v]);
+};
+/** `SHA256:<base64>`, the fingerprint ssh-keygen prints for a public key blob. */
+export function sshKeyFingerprint(blob) {
+    return `SHA256:${hash("sha256", blob).toString("base64").replace(/=+$/, "")}`;
+}
+const CURVES = {
+    nistp256: { crv: "P-256", size: 32, hash: "sha256" },
+    nistp384: { crv: "P-384", size: 48, hash: "sha384" },
+    nistp521: { crv: "P-521", size: 66, hash: "sha512" },
+};
+/** The key a public key blob holds, what it signs with, and the security key's application when it is one. */
+function publicKey(blob) {
+    const take = reader(blob);
+    const type = take().toString();
+    if (type === "ssh-ed25519" || type === "sk-ssh-ed25519@openssh.com") {
+        const key = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: b64url(take()) }, format: "jwk" });
+        return { type, key, ...(type.startsWith("sk-") ? { application: take() } : {}) };
+    }
+    if (type.startsWith("ecdsa-sha2-") || type === "sk-ecdsa-sha2-nistp256@openssh.com") {
+        const curve = CURVES[take().toString()];
+        if (!curve)
+            throw new Error(`unsupported curve in ${type}`);
+        const q = take();
+        if (q[0] !== 4 || q.length !== 1 + 2 * curve.size)
+            throw new Error("the ECDSA key is not an uncompressed point");
+        const key = createPublicKey({
+            key: { kty: "EC", crv: curve.crv, x: b64url(q.subarray(1, 1 + curve.size)), y: b64url(q.subarray(1 + curve.size)) },
+            format: "jwk",
+        });
+        return { type, key, ecdsa: curve, ...(type.startsWith("sk-") ? { application: take() } : {}) };
+    }
+    if (type === "ssh-rsa") {
+        const e = unsigned(take());
+        const n = unsigned(take());
+        return { type, key: createPublicKey({ key: { kty: "RSA", e: b64url(e), n: b64url(n) }, format: "jwk" }) };
+    }
+    throw new Error(`unsupported key type ${type}`);
+}
+/**
+ * Whether `armored`, an SSHSIG as `ssh-keygen -Y sign` writes it, signs
+ * `message` in `namespace` with one of `keys` (public key blobs, ssh wire
+ * format). Never throws. On success, `key` is the signing key's fingerprint.
+ */
+export function verifySshSignatureWith(armored, message, namespace, keys) {
+    try {
+        const body = /-----BEGIN SSH SIGNATURE-----([^-]*)-----END SSH SIGNATURE-----/.exec(armored)?.[1];
+        if (body === undefined)
+            return { ok: false, reason: "it is not an armored ssh signature" };
+        const take = reader(Buffer.from(body.replace(/\s+/g, ""), "base64"));
+        if (take(6).toString() !== "SSHSIG" || take(4).readUInt32BE(0) !== 1)
+            return { ok: false, reason: "it is not an SSHSIG, version 1" };
+        const pk = take();
+        const ns = take();
+        const reserved = take();
+        const alg = take().toString();
+        const sigWire = take();
+        if (ns.toString() !== namespace)
+            return { ok: false, reason: `it is signed in the ${ns.toString()} namespace, not ${namespace}` };
+        if (alg !== "sha256" && alg !== "sha512")
+            return { ok: false, reason: `it hashes with ${alg}, and only sha256 and sha512 are accepted` };
+        if (!keys.some((k) => k.equals(pk)))
+            return { ok: false, reason: "signed by a key the policy at base does not list for the approver" };
+        let data = Buffer.concat([Buffer.from("SSHSIG"), wire(ns), wire(reserved), wire(alg), wire(hash(alg, message))]);
+        const { type, key, ecdsa, application } = publicKey(pk);
+        const sig = reader(sigWire);
+        const sigType = sig().toString();
+        const raw = sig();
+        const fingerprint = sshKeyFingerprint(pk);
+        const answer = (ok) => (ok ? { ok: true, key: fingerprint } : { ok: false, reason: "the signature does not match the signed fields" });
+        if (type === "ssh-rsa") {
+            if (sigType !== "rsa-sha2-256" && sigType !== "rsa-sha2-512")
+                return { ok: false, reason: `an RSA signature of type ${sigType} is not accepted` };
+            return answer(verify(`sha${sigType.slice(9)}`, data, key, raw));
+        }
+        if (sigType !== type)
+            return { ok: false, reason: `a ${sigType} signature from a ${type} key` };
+        if (application !== undefined) {
+            // A security key signs its application, its flags and counter, then the data's hash; ssh-keygen requires the touch flag.
+            const flags = sig(1);
+            if (!(flags[0] & 1))
+                return { ok: false, reason: "the security key was not touched (the user-presence flag is unset)" };
+            data = Buffer.concat([hash("sha256", application), flags, sig(4), hash("sha256", data)]);
+        }
+        if (ecdsa) {
+            const rs = reader(raw);
+            const r = unsigned(rs(), ecdsa.size);
+            const s = unsigned(rs(), ecdsa.size);
+            return answer(verify(application !== undefined ? "sha256" : ecdsa.hash, data, { key, dsaEncoding: "ieee-p1363" }, Buffer.concat([r, s])));
+        }
+        return answer(verify(null, data, key, raw));
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * The key blob an armored SSHSIG carries, or null when it is not one. For
+ * `ssh-keygen -Y check-novalidate`'s question, whether the signature is
+ * intact whoever's key it is: verify against this key.
+ */
+export function sshSignatureKey(armored) {
+    try {
+        const body = /-----BEGIN SSH SIGNATURE-----([^-]*)-----END SSH SIGNATURE-----/.exec(armored)?.[1];
+        if (body === undefined)
+            return null;
+        const take = reader(Buffer.from(body.replace(/\s+/g, ""), "base64"));
+        if (take(6).toString() !== "SSHSIG" || take(4).readUInt32BE(0) !== 1)
+            return null;
+        return Buffer.from(take());
+    }
+    catch {
+        return null;
+    }
+}
+const normalise = (name) => name.normalize("NFKC").trim().toLowerCase();
+/** Whether ssh-keygen's `namespaces="..."` pattern list admits `namespace`: a `*`/`?` pattern matches, and a `!` pattern that matches refuses. */
+export function namespaceAllowed(list, namespace) {
+    if (list === undefined)
+        return true;
+    let allowed = false;
+    for (const raw of list.split(",")) {
+        const negated = raw.startsWith("!");
+        const pattern = negated ? raw.slice(1) : raw;
+        const re = new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+        if (!re.test(namespace))
+            continue;
+        if (negated)
+            return false;
+        allowed = true;
+    }
+    return allowed;
+}
+/**
+ * Why this approval does not count toward a sealed gate, or null when it
+ * does: its seal verifies, for the approver it names, against a key `signers`
+ * lists for that approver in the `chant-gate` namespace. With no signers file
+ * at base, nothing counts. The same rule as `sealedApprovalRule` in
+ * `../../op/gate-review.ts`, which checks with ssh-keygen.
+ */
+export function gateSealRefusal(signers, a) {
+    const where = `${signers.signersPath} at base`;
+    if (!signers.active) {
+        const why = signers.problems.length > 0 ? `: ${signers.problems.join("; ")}` : "";
+        return `the gate is sealed, and there is no signers file (${signers.signersPath}) at base ${signers.base?.slice(0, 12) ?? ""}`.trim() + why;
+    }
+    const what = `the approval of gate ${a.gate} by ${a.resolvedBy}`;
+    if (a.seal === undefined || a.seal === null)
+        return `${what} carries no seal`;
+    const seal = a.seal;
+    if (typeof seal !== "object" || Array.isArray(seal) || typeof seal.signer !== "string" || typeof seal.signature !== "string") {
+        return `the seal on ${what} is malformed: it needs signer and signature`;
+    }
+    if (normalise(seal.signer) !== normalise(a.resolvedBy))
+        return `the seal on ${what} is by ${seal.signer}, and its approver is ${a.resolvedBy || "empty"}`;
+    const keys = signers.signers
+        .filter((s) => normalise(s.principal) === normalise(a.resolvedBy) && namespaceAllowed(s.namespaces, GATE_SEAL_NAMESPACE))
+        .map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
+    if (keys.length === 0)
+        return `${a.resolvedBy} has no key in ${where}, so the seal can't count`;
+    const r = verifySshSignatureWith(seal.signature, gateSealPayload(a), GATE_SEAL_NAMESPACE, keys);
+    return r.ok ? null : `the seal does not verify for ${a.resolvedBy} against ${where}: ${r.reason}`;
+}