@letthembuild/run-receipts 0.0.0-stage → 0.2.0

package/sign.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Copyright 2026 GPULogy AI LLC
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Sign a run receipt, and make the key to sign with.
+ *
+ * A signature says one thing: whoever holds this key put their name to this
+ * receipt, and it has not changed since. It does not say the commands were
+ * run. What a signature is worth is what the key is worth: who holds it, and
+ * how hard it is for anyone else to.
+ *
+ * No dependencies: Node 18 or later, and verify.mjs beside this file.
+ */
+import { readFileSync, writeFileSync, realpathSync, existsSync } from "node:fs";
+import { generateKeyPairSync, createPrivateKey, sign as signBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { digestOf, signedBytes, verifyReceipt, publicKeyOf } from "./verify.mjs";
+
+/** A new key pair: `key` is public and goes in receipts and trust lists; `secret` signs and goes nowhere. */
+export function generateKey() {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = privateKey.export({ format: "jwk" });
+  return { key: `ed25519:${jwk.x}`, secret: jwk.d };
+}
+
+/** The signing key Node needs, from a { key, secret } pair. Throws when they are not a pair. */
+function privateKeyOf(pair) {
+  const x = /^ed25519:([A-Za-z0-9_-]{43})$/.exec(String(pair?.key ?? ""))?.[1];
+  if (!x || !/^[A-Za-z0-9_-]{43}$/.test(String(pair?.secret ?? ""))) throw new Error("not a signing key");
+  if (!publicKeyOf(pair.key)) throw new Error("not a signing key");
+  try { return createPrivateKey({ key: { kty: "OKP", crv: "Ed25519", x, d: pair.secret }, format: "jwk" }); }
+  catch { throw new Error("not a signing key"); }
+}
+
+/**
+ * The receipt, signed: its digest retaken, and this key's signature added in
+ * place of any earlier one from the same key. Other keys' signatures are kept
+ * only while they still hold. Refuses a receipt that does not verify: a
+ * signature on a broken receipt would put a name to nothing.
+ */
+export function signReceipt(receipt, pair) {
+  const key = privateKeyOf(pair);
+  const { signatures: before = [], ...rest } = receipt;
+  const unsigned = { ...rest, digest: digestOf(rest) };
+  const check = verifyReceipt(unsigned);
+  if (!check.valid) throw new Error(`the receipt does not verify, so it is not signed:\n${check.errors.join("\n")}`);
+  const sig = signBytes(null, signedBytes(unsigned.digest), key).toString("base64url");
+  const kept = before.filter((s) => s.key !== pair.key && verifyReceipt({ ...unsigned, signatures: [s] }).valid);
+  const signed = { ...unsigned, signatures: [...kept, { key: pair.key, sig }] };
+  const after = verifyReceipt(signed);
+  if (!after.valid) throw new Error("the key's two halves do not belong together");
+  return signed;
+}
+
+/* ── Command line ────────────────────────────────────────────────────── */
+
+const USAGE = `Usage:
+  sign.mjs keygen <key-file>                  make a signing key; prints the public half
+  sign.mjs sign --key <key-file> <receipt>    print the receipt, signed
+  sign.mjs sign --key <key-file> --write <receipt>   sign it where it is
+
+The key can also come from the environment, for a build server:
+  RUN_RECEIPT_SIGNING_KEY   the contents of a key file`;
+
+function readPair(file, env) {
+  const text = file ? readFileSync(file, "utf8") : env.RUN_RECEIPT_SIGNING_KEY;
+  if (!text) throw new Error("no signing key: pass --key <key-file> or set RUN_RECEIPT_SIGNING_KEY");
+  return JSON.parse(text);
+}
+
+export function main(argv, env = process.env) {
+  const [command, ...rest] = argv;
+  if (command === "keygen") {
+    if (rest.length !== 1 || rest[0].startsWith("--")) { console.error(USAGE); return 2; }
+    if (existsSync(rest[0])) { console.error(`${rest[0]} exists. A key is not overwritten: receipts signed with it would have nobody to answer for them.`); return 2; }
+    const pair = generateKey();
+    writeFileSync(rest[0], JSON.stringify(pair, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+    console.log(pair.key);
+    console.error(`The signing key is in ${rest[0]}. Keep it out of your repository. Give readers the line above.`);
+    return 0;
+  }
+  if (command === "sign") {
+    const args = [...rest];
+    let keyFile = null;
+    const at = args.indexOf("--key");
+    if (at !== -1) { keyFile = args[at + 1] ?? null; args.splice(at, 2); if (!keyFile) { console.error(USAGE); return 2; } }
+    const write = args.includes("--write");
+    const files = args.filter((a) => !a.startsWith("--"));
+    if (files.length !== 1 || args.some((a) => a.startsWith("--") && a !== "--write")) { console.error(USAGE); return 2; }
+    let receipt, pair;
+    try { receipt = JSON.parse(readFileSync(files[0], "utf8")); }
+    catch (e) { console.error(`Cannot read ${files[0]}: ${e.message}`); return 2; }
+    try { pair = readPair(keyFile, env); }
+    catch (e) { console.error(`Cannot read the signing key: ${e.message}`); return 2; }
+    let signed;
+    try { signed = signReceipt(receipt, pair); }
+    catch (e) { console.error(e.message); return 1; }
+    const text = JSON.stringify(signed, null, 2) + "\n";
+    if (write) { writeFileSync(files[0], text); console.error(`Signed ${files[0]} as ${pair.key}`); }
+    else process.stdout.write(text);
+    return 0;
+  }
+  console.error(USAGE);
+  return 2;
+}
+
+function isMain() {
+  if (!process.argv[1]) return false;
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+}
+
+if (isMain()) process.exit(main(process.argv.slice(2)));

package/verify.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * Run-receipt verifier, for format 0.1.
+ *
+ * Answers one question about a receipt file: does it hold together? First
+ * against the schema (shape, bounds), then against itself (the rules in
+ * SPEC.md: a grade that follows from the totals, a verdict that follows from
+ * where each reviewer ended, checks whose state matches their exit code).
+ *
+ * It does not prove the run happened. A receipt is the producer's account;
+ * this proves the account is well-formed, internally consistent and, when it
+ * carries a digest, unaltered since the digest was taken. When it is signed,
+ * it also says which keys signed it, and whether you listed them as trusted.
+ *
+ * No dependencies: Node 18 or later and this file, with the schema beside it.
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { createHash, createPublicKey, verify as verifyBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const SCHEMA_URL = new URL("./receipt.schema.json", import.meta.url);
+let cachedSchema = null;
+export function loadSchema() {
+  return (cachedSchema ??= JSON.parse(readFileSync(SCHEMA_URL, "utf8")));
+}
+
+/* ── Schema: the subset of JSON Schema that receipt.schema.json uses ───── */
+
+const typeOf = (v) => (v === null ? "null" : Array.isArray(v) ? "array" : Number.isInteger(v) ? "integer" : typeof v);
+const isType = (v, t) => typeOf(v) === t || (t === "number" && typeof v === "number");
+
+/** Every way `value` fails `schema`, as "path: what is wrong". Empty when it passes. */
+export function validateSchema(value, schema, root = schema, path = "$") {
+  if (schema.$ref) {
+    const target = schema.$ref.replace(/^#\//, "").split("/").reduce((o, k) => o?.[k], root);
+    if (!target) return [`${path}: schema reference ${schema.$ref} not found`];
+    return validateSchema(value, target, root, path);
+  }
+  if (schema.anyOf) {
+    return schema.anyOf.some((s) => validateSchema(value, s, root, path).length === 0) ? [] : [`${path}: matches none of the allowed forms`];
+  }
+  const out = [];
+  if ("const" in schema && value !== schema.const) return [`${path}: must be ${JSON.stringify(schema.const)}`];
+  if (schema.enum && !schema.enum.includes(value)) return [`${path}: must be one of ${schema.enum.join(", ")}`];
+  if (schema.type) {
+    const types = [].concat(schema.type);
+    if (!types.some((t) => isType(value, t))) return [`${path}: must be ${types.join(" or ")}, found ${typeOf(value)}`];
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) out.push(`${path}: must be a finite number`);
+    if (schema.minimum !== undefined && value < schema.minimum) out.push(`${path}: must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) out.push(`${path}: must be at most ${schema.maximum}`);
+  }
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) out.push(`${path}: must be at least ${schema.minLength} characters`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) out.push(`${path}: must be at most ${schema.maxLength} characters`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) out.push(`${path}: does not have the required form`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) out.push(`${path}: needs at least ${schema.minItems} item(s)`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) out.push(`${path}: allows at most ${schema.maxItems} items`);
+    if (schema.items) value.forEach((v, i) => out.push(...validateSchema(v, schema.items, root, `${path}[${i}]`)));
+  }
+  if (typeOf(value) === "object") {
+    const props = schema.properties ?? {};
+    for (const key of schema.required ?? []) if (!(key in value)) out.push(`${path}.${key}: is required`);
+    for (const [key, v] of Object.entries(value)) {
+      if (key in props) out.push(...validateSchema(v, props[key], root, `${path}.${key}`));
+      else if (schema.additionalProperties === false) out.push(`${path}.${key}: is not part of the format`);
+    }
+  }
+  return out;
+}
+
+/* ── Digest ──────────────────────────────────────────────────────────── */
+
+/** The receipt as bytes to hash: keys sorted, no whitespace, `digest` and `signatures` left out. */
+export function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+}
+
+export function digestOf(receipt) {
+  const { digest: _left_out, signatures: _nor_these, ...rest } = receipt;
+  return `sha256:${createHash("sha256").update(canonical(rest), "utf8").digest("hex")}`;
+}
+
+/* ── Signatures ──────────────────────────────────────────────────────── */
+
+/** What a signature is made over: these words, then the receipt's digest. The words keep a signature made for a receipt from being one for anything else. */
+export const SIGNATURE_CONTEXT = "run-receipt-signature-v1\n";
+export const signedBytes = (digest) => Buffer.from(SIGNATURE_CONTEXT + digest, "utf8");
+
+const KEY_FORM = /^ed25519:([A-Za-z0-9_-]{43})$/;
+
+/** A public key as Node holds it, from its written form, or null when it is not one. */
+export function publicKeyOf(key) {
+  const m = KEY_FORM.exec(String(key ?? ""));
+  if (!m) return null;
+  try { return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: m[1] }, format: "jwk" }); }
+  catch { return null; }
+}
+
+/** True when `signature` is its key's signature over this receipt as it stands. */
+export function signatureHolds(receipt, signature) {
+  const key = publicKeyOf(signature?.key);
+  if (!key || typeof signature.sig !== "string") return false;
+  try { return verifyBytes(null, signedBytes(digestOf(receipt)), key, Buffer.from(signature.sig, "base64url")); }
+  catch { return false; }
+}
+
+/**
+ * A list of keys somebody trusts, from text: either JSON,
+ * { "keys": [{ "key": "ed25519:…", "name": "…" }] }, or one key to a line with
+ * an optional name after it. Lines starting with # are comments. The names are
+ * the reader's own words for each key; a receipt never supplies them.
+ */
+export function parseKeys(text) {
+  const src = String(text ?? "").trim();
+  const keys = [], problems = [];
+  const add = (key, name, where) => {
+    if (!publicKeyOf(key)) problems.push(`${where}: not a key`);
+    else if (!keys.some((k) => k.key === key)) keys.push({ key, name: String(name ?? "").trim().slice(0, 80) });
+  };
+  if (src.startsWith("{")) {
+    let doc;
+    try { doc = JSON.parse(src); } catch { return { keys, problems: ["the key list is not readable as JSON"] }; }
+    if (!Array.isArray(doc?.keys)) return { keys, problems: ["the key list has no keys"] };
+    doc.keys.forEach((k, i) => add(k?.key, k?.name, `keys[${i}]`));
+  } else {
+    src.split(/\r?\n/).forEach((raw, i) => {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) return;
+      const [key, ...name] = line.split(/\s+/);
+      add(key, name.join(" "), `line ${i + 1}`);
+    });
+  }
+  return { keys, problems };
+}
+
+/** Who signed a receipt: each key whose signature holds, with the reader's name for it when they listed it. */
+export function signersOf(receipt, trustedKeys = []) {
+  return (receipt.signatures ?? []).filter((s) => signatureHolds(receipt, s)).map((s) => {
+    const known = trustedKeys.find((k) => k.key === s.key);
+    return { key: s.key, trusted: Boolean(known), name: known?.name ?? "" };
+  });
+}
+
+/* ── Consistency: the rules of SPEC.md, by number ────────────────────── */
+
+/** The grade the totals earn (SPEC rule G). */
+export function gradeOf(t) {
+  if (t.failingNow > 0 || t.contradicted > 0) return "failed";
+  if (t.ran > 0) return t.verifiers >= t.reviewers ? "verified" : "partial";
+  if (t.filesChanged === 0) return "reviewed";
+  if (t.reviewers > 0 && (t.notVisible ?? 0) >= t.reviewers) return "not-visible";
+  return "unverified";
+}
+
+/** Errors and warnings from a receipt that already passed the schema. */
+export function checkConsistency(r) {
+  const errors = [], warnings = [];
+  const err = (rule, msg) => errors.push(`${rule}: ${msg}`);
+  const t = r.totals;
+
+  // S — seats.
+  const names = r.seats.map((s) => s.name);
+  if (new Set(names).size !== names.length) err("S1", "two seats share a name");
+  if (!r.seats.some((s) => s.role === "lead")) err("S2", "no seat is the lead");
+  const reviewers = r.seats.filter((s) => s.role === "reviewer");
+  for (const s of r.seats) {
+    if (s.timeouts > s.errors) err("S3", `${s.name}: more timeouts than errors`);
+    if (s.role === "reviewer" && !s.stance) err("S4", `${s.name}: a reviewer needs a stance`);
+    if (s.role === "lead" && s.stance) err("S4", `${s.name}: the lead has no stance`);
+    if (s.costBasis && s.costBasis !== "metered" && s.costUsd > 0) err("S5", `${s.name}: a ${s.costBasis} seat cannot carry a metered cost`);
+  }
+
+  // V — verdict.
+  const agreed = reviewers.filter((s) => s.stance === "agreed");
+  const answered = reviewers.filter((s) => s.stance !== "unavailable");
+  const out = reviewers.filter((s) => s.stance && s.stance !== "agreed");
+  if (reviewers.length === 0) {
+    if (r.verdict !== null) err("V1", "nobody reviewed, so there can be no verdict");
+  } else if (r.verdict === null) {
+    err("V1", "reviewers took part, so a verdict is required");
+  } else {
+    const v = r.verdict;
+    if (v.agreed !== agreed.length) err("V2", `verdict counts ${v.agreed} agreeing; the seats show ${agreed.length}`);
+    const key = (h) => `${h.name}\u0000${h.stance}`;
+    const want = out.map(key).sort().join("\n"), got = v.holdouts.map(key).sort().join("\n");
+    if (want !== got) err("V3", "holdouts are not exactly the reviewers that did not agree");
+    if (v.outcome === "agreed") {
+      const allWhoAnsweredAgreed = answered.length > 0 && answered.every((s) => s.stance === "agreed");
+      const someoneMissing = answered.length < reviewers.length;
+      if (!allWhoAnsweredAgreed) err("V4", "outcome is agreed while a reviewer that answered did not agree");
+      else if (someoneMissing && t.failingNow > 0) err("V4", "outcome is agreed without a reviewer while a check is still failing");
+      if (v.reviewers !== answered.length) err("V5", `an agreed verdict counts the reviewers that answered (${answered.length}), not ${v.reviewers}`);
+    } else {
+      const expected = agreed.length * 2 > reviewers.length ? "majority" : "none";
+      if (v.outcome !== expected) err("V4", `outcome should be ${expected}: ${agreed.length} of ${reviewers.length} agree`);
+      if (v.reviewers !== reviewers.length) err("V5", `verdict counts ${v.reviewers} reviewers; the seats show ${reviewers.length}`);
+    }
+  }
+
+  // T — totals.
+  if (t.reviewers !== answered.length) err("T1", `totals count ${t.reviewers} reviewers; ${answered.length} answered`);
+  if (t.verifiers > t.reviewers) err("T2", "more verifiers than reviewers");
+  if ((t.notVisible ?? 0) > t.reviewers) err("T2", "more not-visible seats than reviewers");
+  if (t.contradicted > t.reviewers) err("T2", "more contradicted seats than reviewers");
+  const hidden = reviewers.filter((s) => s.commandsVisible === false).length;
+  if ((t.notVisible ?? 0) > hidden) err("T2", `totals count ${t.notVisible} not-visible seats; ${hidden} reviewer(s) are marked so`);
+  if (t.passed + t.failed + (t.expected ?? 0) > t.ran) err("T3", "passed, failed and expected add up to more than ran");
+  if (t.failingNow > t.failed) err("T4", "more checks failing now than ever failed");
+  if ((t.resolved ?? 0) > t.failed - t.failingNow) err("T4", "more checks resolved than stopped failing");
+  if (t.ran > 0 && t.verifiers === 0) err("T5", "commands were run, but no reviewer is counted as running any");
+  if (t.ran === 0 && t.verifiers > 0) err("T5", "a reviewer is counted as running commands, but none were run");
+
+  // G — grade.
+  const grade = gradeOf(t);
+  if (r.grade !== grade) err("G1", `grade is ${r.grade}; the totals earn ${grade}`);
+
+  // C — checks.
+  r.checks.forEach((c, i) => {
+    const at = `checks[${i}]`;
+    for (const who of [c.by, ...(c.alsoBy ?? [])]) if (who !== null && !names.includes(who)) err("C1", `${at}: ${who} is not a seat in this run`);
+    if (c.exitCode === 0 && c.state !== "checked") err("C2", `${at}: exited 0, so its state is checked, not ${c.state}`);
+    if ((c.state === "blocked") !== (c.missingSetup !== null)) err("C3", `${at}: blocked and missing setup go together`);
+    if ((c.state === "unknown" || c.state === "untested") && c.exitCode !== null) err("C4", `${at}: a state of ${c.state} has no exit code`);
+  });
+  const ranHere = r.checks.filter((c) => c.state !== "untested").length;
+  if (ranHere > t.ran) warnings.push(`C5: ${ranHere} checks are listed as run, but the totals count ${t.ran}`);
+
+  // M — money and time.
+  const seatCost = r.seats.reduce((n, s) => n + s.costUsd, 0);
+  if (Math.abs(seatCost - r.costUsd) > 0.01) warnings.push(`M1: seats add up to $${seatCost.toFixed(4)}; the run says $${r.costUsd.toFixed(4)}`);
+  if (r.firstReplyMs !== undefined && r.firstReplyMs > r.durationMs) err("M2", "the first reply came after the run ended");
+  if (Number.isNaN(Date.parse(r.endedAt))) err("M3", "endedAt is not a real date");
+
+  // D — digest.
+  if (r.digest && r.digest !== digestOf(r)) err("D1", "digest does not match the receipt's contents");
+  if (!r.digest) warnings.push("D2: no digest, so a copy cannot be told from an edited one");
+
+  // K — signatures.
+  const signed = r.signatures ?? [];
+  if (new Set(signed.map((s) => s.key)).size !== signed.length) err("K2", "one key signed twice");
+  signed.forEach((s, i) => { if (!signatureHolds(r, s)) err("K1", `signatures[${i}]: is not that key's signature over this receipt`); });
+
+  return { errors, warnings };
+}
+
+/** Schema first; the consistency rules only run on a receipt with the right shape. */
+/**
+ * `signers` lists the keys whose signatures hold, and is empty for a receipt
+ * that is not valid. Pass `trustedKeys` (as parseKeys returns them) to have
+ * each marked as one you listed. With `requireSignature`, a receipt no listed
+ * key has signed is not valid.
+ */
+export function verifyReceipt(receipt, { trustedKeys = [], requireSignature = false } = {}) {
+  const schemaErrors = validateSchema(receipt, loadSchema());
+  if (schemaErrors.length) return { valid: false, errors: schemaErrors.map((e) => `schema: ${e}`), warnings: [], signers: [] };
+  const { errors, warnings } = checkConsistency(receipt);
+  const signers = errors.length ? [] : signersOf(receipt, trustedKeys);
+  if (requireSignature && !errors.length && !signers.some((s) => s.trusted)) {
+    errors.push(signers.length ? "K3: signed, but by no key on the trusted list" : "K3: not signed, and a signature from a trusted key is required");
+  }
+  return { valid: errors.length === 0, errors, warnings, signers: errors.length ? [] : signers };
+}
+
+/* ── Command line ────────────────────────────────────────────────────── */
+
+const USAGE = `Usage:
+  verify.mjs <receipt.json>            check a receipt; exit 0 valid, 1 invalid
+  verify.mjs --json <receipt.json>     the same, as JSON
+  verify.mjs --digest <receipt.json>   print the digest the receipt should carry
+
+Signatures:
+  --keys <file>          the keys you trust: JSON, or one "ed25519:… name" to a line
+  --require-signature    not valid unless a key from --keys signed it`;
+
+/** A key as people read it: enough of it to tell two apart. */
+export const shortKey = (key) => `${String(key).slice(0, 16)}…`;
+
+function main(argv) {
+  const args = [...argv];
+  let keysFile = null;
+  const at = args.indexOf("--keys");
+  if (at !== -1) { keysFile = args[at + 1] ?? null; args.splice(at, 2); if (!keysFile || keysFile.startsWith("--")) { console.error(USAGE); return 2; } }
+  const flags = args.filter((a) => a.startsWith("--"));
+  const files = args.filter((a) => !a.startsWith("--"));
+  if (files.length !== 1 || flags.some((f) => !["--json", "--digest", "--require-signature"].includes(f))) { console.error(USAGE); return 2; }
+  const requireSignature = flags.includes("--require-signature");
+  let trustedKeys = [];
+  if (keysFile) {
+    let parsed;
+    try { parsed = parseKeys(readFileSync(keysFile, "utf8")); }
+    catch (e) { console.error(`Cannot read ${keysFile}: ${e.message}`); return 2; }
+    if (parsed.problems.length) { console.error(`${keysFile}: ${parsed.problems.join("; ")}`); return 2; }
+    trustedKeys = parsed.keys;
+  }
+  if (requireSignature && !trustedKeys.length) { console.error("--require-signature needs --keys: a signature only means something from a key you trust."); return 2; }
+  let receipt;
+  try { receipt = JSON.parse(readFileSync(files[0], "utf8")); }
+  catch (e) { console.error(`Cannot read ${files[0]}: ${e.message}`); return 2; }
+  if (flags.includes("--digest")) {
+    if (typeOf(receipt) !== "object") { console.error("Not a receipt."); return 2; }
+    console.log(digestOf(receipt));
+    return 0;
+  }
+  const result = verifyReceipt(receipt, { trustedKeys, requireSignature });
+  if (flags.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(result.valid ? `VALID    ${files[0]}` : `INVALID  ${files[0]}`);
+    for (const e of result.errors) console.log(`  error    ${e}`);
+    for (const w of result.warnings) console.log(`  warning  ${w}`);
+    for (const s of result.signers) console.log(s.trusted ? `  signed   ${s.name || "a trusted key"} (${shortKey(s.key)})` : `  signed   ${shortKey(s.key)}, which ${keysFile ? "is not on your list" : "nothing here vouches for (pass --keys)"}`);
+  }
+  return result.valid ? 0 : 1;
+}
+
+/** Run as a program, and not imported: true through a symlink too, which is how an installed command arrives. */
+function isMain() {
+  if (!process.argv[1]) return false;
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+}
+
+if (isMain()) process.exit(main(process.argv.slice(2)));