veriskit 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.1 — 2026-07-10
+
+### Added
+- Signed evidence. `veris evidence keygen` creates an Ed25519 keypair (via Node's built-in crypto, no new dependency); `veris evidence sign <evidence.json>` writes a detached signature; `veris evidence verify` checks a sibling signature automatically and can assert the signer with `--pubkey` or `--key-id`. Bundles carry the signature. Signing is opt-in; unsigned evidence still verifies for integrity. `VERISKIT_SIGNING_KEY` supplies the key in CI.
+
+### Changed
+- `veris init` now gitignores `keys/`.
+
 ## 0.4.0 — 2026-07-10
 
 ### Added

package/README.md

@@ -190,7 +190,7 @@ veris evidence verify .veris/runs/<run-id>/evidence.json
 This recomputes the digest and reports whether the record was edited or
 corrupted since it was written. An integrity digest is not forgery-proof on its
 own. To prove authorship, publish the digest separately (a CI log or PR) or sign
-it. Cryptographic signing is planned for a later release.
+the record with an Ed25519 key (see Signing below).
 
 Package a run as a single portable file (the record, its report, and its logs,
 each with a digest, plus a bundle digest over everything):
@@ -202,6 +202,28 @@ veris evidence verify <bundle> # checks the record, every log, and the report
 
 `veris evidence show` prints the latest record's key facts.
 
+### Signing (optional)
+
+An integrity digest proves a record was not edited. A signature proves a
+specific key vouched for it. VerisKit signs with Ed25519 from Node's built-in
+crypto, so signing adds no dependency and works offline.
+
+```bash
+veris evidence keygen                         # writes .veris/keys/veriskit-signing.key(.pub)
+veris evidence sign .veris/runs/<id>/evidence.json --key .veris/keys/veriskit-signing.key
+veris evidence verify .veris/runs/<id>/evidence.json --pubkey .veris/keys/veriskit-signing.key.pub
+```
+
+`sign` writes a detached `<evidence.json>.sig` next to the record. `verify`
+picks it up automatically and checks it. In CI, pass the key through the
+`VERISKIT_SIGNING_KEY` environment variable instead of a file.
+
+A signature proves that whoever holds the private key signed the record. It
+does not prove who that is. VerisKit prints the key fingerprint; to bind it to
+a person or system, compare that fingerprint to one you already trust, or
+assert it with `--pubkey` or `--key-id`. Keep the private key secret; `keygen`
+writes it into `.veris/keys/`, which `veris init` gitignores.
+
 Commit `.veris/config.json` and `.veris/.gitignore`. `veris init` keeps `runs/`,
 `reports/`, `cache/`, `graph.json`, and `evidence/` out of your history.
 
@@ -213,7 +235,7 @@ VerisKit says what it cannot do as plainly as what it can:
 - **No test generation.** `plan` tells you what to test. Writing the tests is a later release.
 - **One project root.** A monorepo with several `tsconfig.json` files is not modeled yet. Resolution runs against the root project.
 - **Scanner fallback on plain-JS or TS 7.x-native projects.** The accurate resolver needs the classic TypeScript compiler API. Without it you get the labeled, relative-imports-only graph described above, and no dependency is added to paper over the gap.
-- **No cryptographic signing.** Evidence carries an integrity digest, not a signature. Keyless signing is planned.
+- **No keyless or identity-bound signing.** Evidence can be signed with a local Ed25519 key (see Signing), but sigstore-style keyless signing that ties a signature to an identity is not built yet.
 
 ## Part of Baseframe Labs
 

package/dist/index.js

@@ -849,6 +849,7 @@ var init_init = __esm({
       "cache/",
       "graph.json",
       "evidence/",
+      "keys/",
       ""
     ].join("\n");
   }
@@ -1897,7 +1898,84 @@ var init_plan = __esm({
   }
 });
 
+// src/evidence/signing.ts
+import {
+  createHash as createHash2,
+  createPrivateKey,
+  createPublicKey,
+  sign as cryptoSign,
+  verify as cryptoVerify,
+  generateKeyPairSync
+} from "crypto";
+function derOf(publicKey) {
+  return publicKey.export({ type: "spki", format: "der" });
+}
+function keyId(publicKey) {
+  const key = typeof publicKey === "string" ? createPublicKey(publicKey) : publicKey;
+  return createHash2("sha256").update(derOf(key)).digest("hex").slice(0, 8);
+}
+function signatureKeyId(sig) {
+  const key = createPublicKey({
+    key: Buffer.from(sig.publicKey, "base64"),
+    format: "der",
+    type: "spki"
+  });
+  return keyId(key);
+}
+function generateKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  return {
+    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }),
+    privateKeyPem: privateKey.export({
+      type: "pkcs8",
+      format: "pem"
+    }),
+    keyId: keyId(publicKey)
+  };
+}
+function signDigest(digest, privateKeyPem) {
+  const privateKey = createPrivateKey(privateKeyPem);
+  const publicKey = createPublicKey(
+    privateKey
+  );
+  const sig = cryptoSign(null, Buffer.from(digest, "utf8"), privateKey);
+  return {
+    schema: SIGNATURE_SCHEMA,
+    alg: "ed25519",
+    keyId: keyId(publicKey),
+    publicKey: derOf(publicKey).toString("base64"),
+    digest,
+    signature: sig.toString("base64"),
+    signedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function verifySignature(sig) {
+  try {
+    const publicKey = createPublicKey({
+      key: Buffer.from(sig.publicKey, "base64"),
+      format: "der",
+      type: "spki"
+    });
+    return cryptoVerify(
+      null,
+      Buffer.from(sig.digest, "utf8"),
+      publicKey,
+      Buffer.from(sig.signature, "base64")
+    );
+  } catch {
+    return false;
+  }
+}
+var SIGNATURE_SCHEMA;
+var init_signing = __esm({
+  "src/evidence/signing.ts"() {
+    "use strict";
+    SIGNATURE_SCHEMA = "veriskit/signature@1";
+  }
+});
+
 // src/evidence/verify-evidence.ts
+import { existsSync as existsSync5 } from "fs";
 import { readFile as readFile3 } from "fs/promises";
 function verifyRecord(record) {
   const recomputed = computeDigest(
@@ -1911,20 +1989,71 @@ function verifyRecord(record) {
       detail: ok ? "matches the canonical record" : `recomputed ${recomputed}, record claims ${record.digest}`
     }
   ];
-  return { ok, kind: "record", record, checks };
+  return { ok, kind: "record", record, checks, signed: false };
+}
+function signatureChecks(recordDigest, sig, opts = {}) {
+  const checks = [];
+  const kid = signatureKeyId(sig);
+  const validSig = verifySignature(sig) && sig.digest === recordDigest;
+  checks.push({
+    name: "signature",
+    ok: validSig,
+    detail: validSig ? `valid ed25519 signature by key ${kid}` : "signature does not match this record"
+  });
+  if (opts.expectedKeyId || opts.expectedPubKeyPem) {
+    let matches = false;
+    if (opts.expectedPubKeyPem) {
+      try {
+        matches = keyId(opts.expectedPubKeyPem) === kid;
+      } catch {
+        matches = false;
+      }
+    } else if (opts.expectedKeyId) {
+      matches = opts.expectedKeyId.toLowerCase() === kid.toLowerCase();
+    }
+    checks.push({
+      name: "signer",
+      ok: matches,
+      detail: matches ? `signer matches the expected key ${kid}` : `signer ${kid} does not match the expected key`
+    });
+  }
+  return checks;
 }
-async function verifyEvidenceFile(path) {
+async function verifyEvidenceFile(path, opts = {}) {
   const parsed = JSON.parse(await readFile3(path, "utf8"));
   if (parsed?.schema === "veriskit/bundle@1") {
     const { verifyBundle: verifyBundle2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
-    return verifyBundle2(parsed);
+    return verifyBundle2(parsed, opts);
+  }
+  const result = verifyRecord(parsed);
+  const assertedSigner = Boolean(
+    opts.expectedKeyId || opts.expectedPubKeyPem || opts.sigPath
+  );
+  const sigPath = opts.sigPath ?? `${path}.sig`;
+  if (existsSync5(sigPath)) {
+    const sig = JSON.parse(await readFile3(sigPath, "utf8"));
+    result.checks.push(
+      ...signatureChecks(result.record.digest, sig, {
+        expectedKeyId: opts.expectedKeyId,
+        expectedPubKeyPem: opts.expectedPubKeyPem
+      })
+    );
+    result.signed = true;
+  } else if (assertedSigner) {
+    result.checks.push({
+      name: "signature",
+      ok: false,
+      detail: "a signature was required (--pubkey/--key-id/--sig) but none was found"
+    });
   }
-  return verifyRecord(parsed);
+  result.ok = result.checks.every((c) => c.ok);
+  return result;
 }
 var init_verify_evidence = __esm({
   "src/evidence/verify-evidence.ts"() {
     "use strict";
     init_record();
+    init_signing();
   }
 });
 
@@ -1935,7 +2064,7 @@ __export(bundle_exports, {
   buildBundle: () => buildBundle,
   verifyBundle: () => verifyBundle
 });
-function buildBundle(record, report, logs) {
+function buildBundle(record, report, logs, signature) {
   const manifest = {
     record: record.digest,
     report: sha256(report),
@@ -1943,10 +2072,10 @@ function buildBundle(record, report, logs) {
       Object.entries(logs).map(([k, v]) => [k, sha256(v)])
     )
   };
-  const base = { schema: BUNDLE_SCHEMA, record, report, logs, manifest };
+  const base = signature ? { schema: BUNDLE_SCHEMA, record, report, logs, manifest, signature } : { schema: BUNDLE_SCHEMA, record, report, logs, manifest };
   return { ...base, bundleDigest: sha256(canonicalize(base)) };
 }
-function verifyBundle(bundle) {
+function verifyBundle(bundle, opts = {}) {
   const checks = [];
   const recordResult = verifyRecord(bundle.record);
   checks.push(...recordResult.checks);
@@ -1971,11 +2100,28 @@ function verifyBundle(bundle) {
     ok: recomputed === bundle.bundleDigest,
     detail: recomputed === bundle.bundleDigest ? "matches" : "mismatch"
   });
+  let signed = false;
+  if (bundle.signature) {
+    signed = true;
+    checks.push(
+      ...signatureChecks(bundle.record.digest, bundle.signature, {
+        expectedKeyId: opts.expectedKeyId,
+        expectedPubKeyPem: opts.expectedPubKeyPem
+      })
+    );
+  } else if (opts.expectedKeyId || opts.expectedPubKeyPem) {
+    checks.push({
+      name: "signature",
+      ok: false,
+      detail: "a signature was required (--pubkey/--key-id) but the bundle is unsigned"
+    });
+  }
   return {
     ok: checks.every((c) => c.ok),
     kind: "bundle",
     record: bundle.record,
-    checks
+    checks,
+    signed
   };
 }
 var BUNDLE_SCHEMA;
@@ -1992,17 +2138,33 @@ var init_bundle = __esm({
 var evidence_exports = {};
 __export(evidence_exports, {
   runEvidenceBundle: () => runEvidenceBundle,
+  runEvidenceKeygen: () => runEvidenceKeygen,
   runEvidenceShow: () => runEvidenceShow,
+  runEvidenceSign: () => runEvidenceSign,
   runEvidenceVerify: () => runEvidenceVerify
 });
-import { readFileSync as readFileSync5 } from "fs";
+import { chmodSync, existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync } from "fs";
 import { writeFile as writeFile4 } from "fs/promises";
-import { basename as basename3, join as join12 } from "path";
+import { basename as basename3, dirname as dirname2, join as join12 } from "path";
 import pc5 from "picocolors";
-async function runEvidenceVerify(path) {
+async function runEvidenceVerify(path, opts = {}) {
+  let expectedPubKeyPem;
+  if (opts.pubkey) {
+    try {
+      expectedPubKeyPem = readFileSync5(opts.pubkey, "utf8");
+    } catch {
+      process.stderr.write(`veris: cannot read public key at ${opts.pubkey}
+`);
+      return 1;
+    }
+  }
   let result;
   try {
-    result = await verifyEvidenceFile(path);
+    result = await verifyEvidenceFile(path, {
+      sigPath: opts.sig,
+      expectedKeyId: opts.keyId,
+      expectedPubKeyPem
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`veris: cannot read evidence at ${path}: ${msg}
@@ -2027,8 +2189,93 @@ ${result.ok ? "digest OK" : "TAMPERED"} \xB7 verdict ${result.record.verdict.sta
   process.stdout.write(`
 ${HONESTY}
 `);
+  if (result.signed && !opts.pubkey && !opts.keyId) {
+    process.stdout.write(
+      "\nThis record is signed. Confirm you trust the signing key by comparing its\nkey id above to one you already trust, or re-run with --pubkey / --key-id.\n"
+    );
+  }
   return result.ok ? 0 : 1;
 }
+async function runEvidenceKeygen(root, opts = {}) {
+  const out = opts.out ?? join12(root, ".veris", "keys", "veriskit-signing.key");
+  const pub = `${out}.pub`;
+  if (existsSync6(out) || existsSync6(pub)) {
+    process.stderr.write(
+      `veris: a key already exists at ${out}. Refusing to overwrite it.
+`
+    );
+    return 1;
+  }
+  const { mkdir: mkdir2 } = await import("fs/promises");
+  await mkdir2(dirname2(out), { recursive: true });
+  const kp = generateKeyPair();
+  writeFileSync(out, kp.privateKeyPem, { mode: 384 });
+  chmodSync(out, 384);
+  writeFileSync(pub, kp.publicKeyPem, "utf8");
+  process.stdout.write(
+    [
+      `Wrote signing key ${out} (keep this secret; do not commit it)`,
+      `Wrote public key ${pub}`,
+      `Key id ${kp.keyId}`,
+      ""
+    ].join("\n")
+  );
+  return 0;
+}
+async function runEvidenceSign(evidencePath, opts = {}) {
+  let privateKeyPem;
+  if (process.env.VERISKIT_SIGNING_KEY) {
+    privateKeyPem = process.env.VERISKIT_SIGNING_KEY;
+  } else if (opts.key) {
+    try {
+      privateKeyPem = readFileSync5(opts.key, "utf8");
+    } catch {
+      process.stderr.write(`veris: cannot read signing key at ${opts.key}
+`);
+      return 1;
+    }
+  } else {
+    process.stderr.write(
+      "veris: no signing key. Pass --key <path> or set VERISKIT_SIGNING_KEY.\n"
+    );
+    return 1;
+  }
+  let record;
+  try {
+    record = JSON.parse(readFileSync5(evidencePath, "utf8"));
+  } catch {
+    process.stderr.write(`veris: cannot read evidence at ${evidencePath}
+`);
+    return 1;
+  }
+  const recomputed = computeDigest(
+    record
+  );
+  if (recomputed !== record.digest) {
+    process.stderr.write(
+      "veris: refusing to sign, the record digest does not match its contents.\n"
+    );
+    return 1;
+  }
+  let sig;
+  try {
+    sig = signDigest(record.digest, privateKeyPem);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`veris: signing failed: ${msg}
+`);
+    return 1;
+  }
+  const out = opts.out ?? `${evidencePath}.sig`;
+  writeFileSync(out, `${JSON.stringify(sig, null, 2)}
+`, "utf8");
+  process.stdout.write(
+    `Signed ${evidencePath}
+Wrote ${out} (key ${sig.keyId})
+`
+  );
+  return 0;
+}
 async function runEvidenceBundle(root, opts = {}) {
   const runDir = latestRunDir(root);
   if (!runDir) {
@@ -2055,7 +2302,15 @@ async function runEvidenceBundle(root, opts = {}) {
   }
   const logIds = record.checks.filter((c) => c.logDigest).map((c) => c.id);
   const logs = await readRunLogs(runDir, logIds);
-  const bundle = buildBundle(record, report, logs);
+  let signature;
+  const sigPath = join12(runDir, "evidence.json.sig");
+  if (existsSync6(sigPath)) {
+    try {
+      signature = JSON.parse(readFileSync5(sigPath, "utf8"));
+    } catch {
+    }
+  }
+  const bundle = buildBundle(record, report, logs, signature);
   const outDir = await ensureEvidenceDir(root);
   const out = opts.out ?? join12(outDir, `${record.id}.bundle.json`);
   await writeFile4(out, `${JSON.stringify(bundle, null, 2)}
@@ -2101,10 +2356,12 @@ var init_evidence = __esm({
   "src/cli/commands/evidence.ts"() {
     "use strict";
     init_bundle();
+    init_record();
+    init_signing();
     init_store();
     init_verify_evidence();
     init_tty();
-    HONESTY = "An integrity digest confirms the record was not edited or corrupted since it was written.\nIt is not forgery-proof on its own: publish the digest separately (CI log, PR) or sign it (planned) to prove authorship.";
+    HONESTY = "An integrity digest confirms the record was not edited or corrupted since it was written.\nIt is not forgery-proof on its own: publish the digest separately (CI log, PR) or sign it (veris evidence sign) to prove authorship.";
   }
 });
 
@@ -2164,8 +2421,8 @@ function buildCli() {
   });
   cli.command(
     "evidence <action> [file]",
-    "Evidence tools: verify <file> | bundle | show [file]"
-  ).option("--out <file>", "For bundle: write to a specific path").action(
+    "Evidence: verify <file> | bundle | show [file] | keygen | sign <file>"
+  ).option("--out <file>", "For bundle/keygen/sign: output path").option("--key <file>", "For sign: the private signing key (PEM)").option("--pubkey <file>", "For verify: assert the signer's public key").option("--key-id <id>", "For verify: assert the signer's key id").option("--sig <file>", "For verify: signature path (default <file>.sig)").action(
     async (action, file, opts) => {
       const mod = await Promise.resolve().then(() => (init_evidence(), evidence_exports));
       if (action === "verify") {
@@ -2174,16 +2431,34 @@ function buildCli() {
           process.exitCode = 1;
           return;
         }
-        process.exitCode = await mod.runEvidenceVerify(file);
+        process.exitCode = await mod.runEvidenceVerify(file, {
+          pubkey: opts.pubkey,
+          keyId: opts.keyId,
+          sig: opts.sig
+        });
       } else if (action === "bundle") {
         process.exitCode = await mod.runEvidenceBundle(process.cwd(), {
           out: opts.out
         });
       } else if (action === "show") {
         process.exitCode = await mod.runEvidenceShow(process.cwd(), file);
+      } else if (action === "keygen") {
+        process.exitCode = await mod.runEvidenceKeygen(process.cwd(), {
+          out: opts.out
+        });
+      } else if (action === "sign") {
+        if (!file) {
+          process.stderr.write("veris: evidence sign needs a <file>\n");
+          process.exitCode = 1;
+          return;
+        }
+        process.exitCode = await mod.runEvidenceSign(file, {
+          key: opts.key,
+          out: opts.out
+        });
       } else {
         process.stderr.write(
-          `veris: unknown evidence action '${action}' (use verify | bundle | show)
+          `veris: unknown evidence action '${action}' (use verify | bundle | show | keygen | sign)
 `
         );
         process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veriskit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "The fastest way to prove your software works — a zero-config verification CLI.",
   "scripts": {
     "test": "vitest run",