@verax-ai/body 0.3.0 → 0.4.0

package/dist/verify-cli.js

@@ -15,16 +15,33 @@
  */
 import { readFileSync } from "node:fs";
 import { verifyLedger } from "@verax-ai/proxy";
+import { directoryAccess, unreadableSentence } from "./install.js";
 export const EX_VERIFY_FAILED = 1;
 function usage() {
     return [
-        "usage: verax verify <stateDir> [--key <public.pem>] [--json]",
+        "usage: verax verify <stateDir> [--key <public.pem>] [--effect-key <public.pem>] [--witness-key <public.pem>] [--checkpoint-key <public.pem>] [--json]",
         "",
         "  <stateDir>        the directory holding decisions.jsonl and effects.jsonl",
-        "  --key <file>      verify against a public key you hold, instead of the one",
-        "                    the records carry. This is the difference between",
-        "                    'these files agree with each other' and 'these files",
-        "                    were signed by the key I was given'.",
+        "  --key <file>      verify decision records against a public key you hold,",
+        "                    instead of the one the records carry. This is the",
+        "                    difference between 'these files agree with each other'",
+        "                    and 'these files were signed by the key I was given'.",
+        "  --effect-key <file>",
+        "                    verify self effect rows against a public key you hold,",
+        "                    instead of one key taken from the first self row. Same",
+        "                    distinction as --key, for the effect signer. When this",
+        "                    is set and the ledger has a same-org row, --witness-key",
+        "                    is required too.",
+        "  --witness-key <file>",
+        "                    verify same-org effect rows against a public key you",
+        "                    hold, instead of one key taken from the first same-org",
+        "                    row. Agreement is not trust, the same as --key. When",
+        "                    this is set and the ledger has a self row, --effect-key",
+        "                    is required too.",
+        "  --checkpoint-key <file>",
+        "                    verify every checkpoint row against a public key you",
+        "                    hold, instead of one key taken from the checkpoint",
+        "                    file. Same distinction as --key, for the witness.",
         "  --json            machine-readable result on stdout",
         "",
         "Exit code is 0 when the ledger verifies and 1 when it does not.",
@@ -44,6 +61,44 @@ export function renderVerify(r) {
             ? "the key carried in these files"
             : "no key"}`);
     lines.push(`              ${r.trust.note}`);
+    lines.push(`effects with ${r.effectTrust.source === "pinned"
+        ? "a key you supplied"
+        : r.effectTrust.source === "in-ledger"
+            ? "the key carried in these files"
+            : "no key"}`);
+    lines.push(`              ${r.effectTrust.note}`);
+    const witnessTrust = r.witnessTrust ?? {
+        source: "none",
+        publicKeyPem: null,
+        note: "no same-org effects, so no witness key was used",
+    };
+    lines.push(`same-org with ${witnessTrust.source === "pinned"
+        ? "a key you supplied"
+        : witnessTrust.source === "in-ledger"
+            ? "the key carried in these files"
+            : "no key"}`);
+    lines.push(`              ${witnessTrust.note}`);
+    lines.push(`checkpoints with ${r.checkpointTrust.source === "pinned"
+        ? "a key you supplied"
+        : r.checkpointTrust.source === "in-ledger"
+            ? "the key carried in these files"
+            : "no key"}`);
+    lines.push(`              ${r.checkpointTrust.note}`);
+    lines.push(r.index.line);
+    lines.push(r.effectCompleteness);
+    if (r.tail.checkpoint) {
+        const head = r.tail.checkpoint.chainHeadHash ?? "(no head hash)";
+        const holds = r.tail.checkpoint.ledgerHoldsRecord === null
+            ? "no head hash to look up"
+            : r.tail.checkpoint.ledgerHoldsRecord
+                ? "ledger holds that record"
+                : "ledger does not hold that record";
+        const covered = r.tail.checkpoint.receiptCount === null
+            ? "no record count"
+            : `${r.tail.checkpoint.receiptCount} record(s)`;
+        lines.push(`checkpoint    newest covers ${covered}, head ${head}, ${holds}`);
+    }
+    lines.push(r.tail.line);
     if (r.problems.length > 0) {
         lines.push("");
         lines.push("problems:");
@@ -64,28 +119,93 @@ export async function runVerify(argv, out = (s) => process.stdout.write(`${s}\n`
     }
     const json = args.includes("--json");
     let publicKeyPem;
-    const keyAt = args.indexOf("--key");
-    if (keyAt !== -1) {
-        const path = args[keyAt + 1];
+    let effectPublicKeyPem;
+    let witnessPublicKeyPem;
+    let checkpointPublicKeyPem;
+    const readKeyFlag = (flag) => {
+        const at = args.indexOf(flag);
+        if (at === -1)
+            return { ok: true };
+        const path = args[at + 1];
         if (!path || path.startsWith("-")) {
-            out("verify: --key needs a file path");
-            return EX_VERIFY_FAILED;
+            out(`verify: ${flag} needs a file path`);
+            return { ok: false };
         }
         try {
-            publicKeyPem = readFileSync(path, "utf8");
+            const pem = readFileSync(path, "utf8");
+            if (pem.trim() === "") {
+                out(`verify-key-empty: ${flag}`);
+                return { ok: false };
+            }
+            args.splice(at, 2);
+            return { ok: true, pem };
         }
         catch {
             out(`verify: cannot read key file ${path}`);
-            return EX_VERIFY_FAILED;
+            return { ok: false };
         }
-        args.splice(keyAt, 2);
-    }
+    };
+    const recordKey = readKeyFlag("--key");
+    if (!recordKey.ok)
+        return EX_VERIFY_FAILED;
+    publicKeyPem = recordKey.pem;
+    const effectKey = readKeyFlag("--effect-key");
+    if (!effectKey.ok)
+        return EX_VERIFY_FAILED;
+    effectPublicKeyPem = effectKey.pem;
+    const witnessKey = readKeyFlag("--witness-key");
+    if (!witnessKey.ok)
+        return EX_VERIFY_FAILED;
+    witnessPublicKeyPem = witnessKey.pem;
+    const checkpointKey = readKeyFlag("--checkpoint-key");
+    if (!checkpointKey.ok)
+        return EX_VERIFY_FAILED;
+    checkpointPublicKeyPem = checkpointKey.pem;
     const dir = args.find((a) => !a.startsWith("-"));
     if (!dir) {
         out(usage());
         return EX_VERIFY_FAILED;
     }
-    const result = await verifyLedger(dir, publicKeyPem ? { publicKeyPem } : {});
+    if (directoryAccess(dir) === "unreadable") {
+        out(unreadableSentence(dir, "verify"));
+        return 77;
+    }
+    let result;
+    try {
+        result = await verifyLedger(dir, {
+            ...(publicKeyPem ? { publicKeyPem } : {}),
+            ...(effectPublicKeyPem ? { effectPublicKeyPem } : {}),
+            ...(witnessPublicKeyPem ? { witnessPublicKeyPem } : {}),
+            ...(checkpointPublicKeyPem ? { checkpointPublicKeyPem } : {}),
+        });
+    }
+    catch (err) {
+        const problem = err instanceof Error ? err.message : "ledger could not be read";
+        const failed = {
+            ok: false,
+            directory: dir,
+            decisions: 0,
+            effects: 0,
+            signaturesValid: 0,
+            signaturesInvalid: 0,
+            chainBreakAt: null,
+            effectsBound: 0,
+            effectsOrphaned: 0,
+            trust: { source: "none", publicKeyPem: null, note: problem },
+            effectTrust: { source: "none", publicKeyPem: null, note: problem },
+            witnessTrust: { source: "none", publicKeyPem: null, note: problem },
+            checkpointTrust: { source: "none", publicKeyPem: null, note: problem },
+            index: { present: false, missing: 0, line: "index: none (cannot check for removed records)" },
+            effectCompleteness: "effect completeness was not checked",
+            tail: {
+                line: "tail: no checkpoint; removing the newest records with their effects is not detectable from these files",
+                checkpoint: null,
+            },
+            problems: [problem],
+        };
+        out(json ? JSON.stringify(failed, null, 2) : renderVerify(failed));
+        return EX_VERIFY_FAILED;
+    }
     out(json ? JSON.stringify(result, null, 2) : renderVerify(result));
     return result.ok ? 0 : EX_VERIFY_FAILED;
 }

package/dist/wiring.js

@@ -66,7 +66,7 @@ export function createBodyServices(opts) {
                 : {}),
         };
     };
-    registry.set("audit.explain", async (call) => auditExplain(call, ledger, await explainOpts()));
+    registry.set("audit.explain", async (call, principal) => auditExplain(call, ledger, await explainOpts(), { principal, stateDir: opts.stateDir }));
     registry.set("message.read", (call, principal) => messageRead(call, opts.stateDir, principal));
     registry.set("message.send", (call, principal, ref) => messageSend(call, opts.stateDir, ref ?? "", principal));
     registry.set("spend", (call, _principal, ref) => spendAuthorize(call, ref ?? ""));

package/dist/witness.js

@@ -3,9 +3,12 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync } from
 import { createServer } from "node:http";
 import { join } from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
-import { buildCheckpointClaims, checkpointHash, signCheckpoint, totalsFromDecisionRecords, } from "@cedulon/checkpoint";
-import { decisionRecordHash } from "@cedulon/core";
+import { buildCheckpointClaims, checkpointHash, signCheckpoint, totalsFromDecisionRecords, verifyCheckpoint, verifyCheckpointUnderPin, } from "@cedulon/checkpoint";
+import { canonical, decisionRecordHash } from "@cedulon/core";
+import { coseFromHex, decodeCoseSign1, verifyCoseSign1 } from "@cedulon/cose";
+import { verifyEffectExtract } from "@cedulon/effect-extract";
 import { checkpointsPath, listPieceFiles, signEffectAttestation } from "@verax-ai/proxy";
+import { assertEd25519PublicKey } from "./keys.js";
 import { pidAlive } from "./unlock.js";
 const WITNESS_CLASS = "same-org";
 function listenPath(stateDir) {
@@ -24,19 +27,23 @@ export function loadOrCreateWitnessKeys(stateDir) {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const priv = join(dir, "witness.private.pem");
     const pub = join(dir, "witness.public.pem");
-    if (existsSync(priv) && existsSync(pub)) {
-        return { privateKeyPem: readFileSync(priv, "utf8"), publicKeyPem: readFileSync(pub, "utf8") };
-    }
-    if (existsSync(priv) || existsSync(pub)) {
+    const pair = existsSync(priv) && existsSync(pub)
+        ? { privateKeyPem: readFileSync(priv, "utf8"), publicKeyPem: readFileSync(pub, "utf8") }
+        : existsSync(priv) || existsSync(pub)
+            ? null
+            : (() => {
+                const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+                const created = {
+                    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+                    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+                };
+                writePemAtomic(priv, created.privateKeyPem);
+                writePemAtomic(pub, created.publicKeyPem);
+                return created;
+            })();
+    if (!pair)
         throw new Error("witness-keys-partial");
-    }
-    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
-    const pair = {
-        publicKeyPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
-        privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
-    };
-    writePemAtomic(priv, pair.privateKeyPem);
-    writePemAtomic(pub, pair.publicKeyPem);
+    assertEd25519PublicKey(pair.publicKeyPem, "witness");
     return pair;
 }
 export function readWitnessListen(stateDir) {
@@ -122,21 +129,61 @@ function loadDecisions(stateDir) {
     }
     return out;
 }
+/** Last checkpoint hash this process recorded. A truncated file is compared with it. */
+function recordedCheckpointHash(stateDir) {
+    let text;
+    try {
+        text = readFileSync(statusPath(stateDir), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let found = null;
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (typeof row.checkpointHash === "string" && row.checkpointHash !== "")
+                found = row.checkpointHash;
+        }
+        catch {
+            // A torn status line is not a hash.
+        }
+    }
+    return found;
+}
 function lastCheckpointHash(stateDir) {
+    const path = checkpointsPath(stateDir);
+    let text;
     try {
-        const text = readFileSync(checkpointsPath(stateDir), "utf8").trim();
-        if (text === "")
-            return null;
-        const lines = text.split("\n").filter((l) => l !== "");
-        const last = JSON.parse(lines[lines.length - 1] ?? "{}");
-        if (typeof last.coseHex !== "string" || !last.claims)
-            return null;
-        return checkpointHash(last);
+        text = readFileSync(path, "utf8");
     }
     catch (err) {
         if (err.code === "ENOENT")
             return null;
-        return null;
+        throw new Error("checkpoint-unreadable");
+    }
+    const trimmed = text.trim();
+    if (trimmed === "") {
+        // A missing file starts a chain. Zero bytes or whitespace are not that file.
+        // They also are not the hash recorded when the last checkpoint was written.
+        const recorded = recordedCheckpointHash(stateDir);
+        if (recorded === null || !trimmed.includes(recorded))
+            throw new Error("checkpoint-unreadable");
+    }
+    const lines = trimmed.split("\n").filter((line) => line !== "");
+    try {
+        const last = JSON.parse(lines[lines.length - 1] ?? "");
+        if (!last || typeof last !== "object" || typeof last.coseHex !== "string" || !last.claims) {
+            throw new Error("checkpoint-unreadable");
+        }
+        return checkpointHash(last);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === "checkpoint-unreadable")
+            throw err;
+        throw new Error("checkpoint-unreadable");
     }
 }
 function signWindowCheckpoint(stateDir, window, keys) {
@@ -146,6 +193,11 @@ function signWindowCheckpoint(stateDir, window, keys) {
     const claims = buildCheckpointClaims(window.epoch, inWindow, startMs, endMs, lastCheckpointHash(stateDir), totalsFromDecisionRecords, (row) => decisionRecordHash(row));
     const signed = signCheckpoint(claims, keys.privateKeyPem, keys.publicKeyPem);
     appendFileSync(checkpointsPath(stateDir), `${JSON.stringify(signed)}\n`, { encoding: "utf8" });
+    appendStatus(stateDir, {
+        atMs: Date.now(),
+        result: "checkpoint",
+        checkpointHash: checkpointHash(signed),
+    });
     return signed;
 }
 export async function requestWitnessCheckpoint(stateDir, window) {
@@ -167,12 +219,75 @@ export async function requestWitnessCheckpoint(stateDir, window) {
         const body = (await res.json());
         if (typeof body.coseHex !== "string" || !body.claims)
             return null;
+        if (!checkpointMatchesListenKey(body, listen.publicKeyPem)) {
+            appendStatus(stateDir, {
+                atMs: Date.now(),
+                result: "checkpoint-refused",
+                reason: "witness-key-mismatch",
+            });
+            return null;
+        }
         return body;
     }
     catch {
         return null;
     }
 }
+/** The listen file's key, not whichever key answered on the port. */
+function checkpointMatchesListenKey(body, publicKeyPem) {
+    if (typeof body.coseHex !== "string" || body.coseHex === "" || !body.claims)
+        return false;
+    if (typeof body.publicKeyPem !== "string" || !pemSame(body.publicKeyPem, publicKeyPem))
+        return false;
+    try {
+        return verifyCheckpointUnderPin(body, publicKeyPem) && verifyCheckpoint(body, publicKeyPem);
+    }
+    catch {
+        return false;
+    }
+}
+function pemSame(left, right) {
+    return left.replace(/\r\n/g, "\n").trim() === right.replace(/\r\n/g, "\n").trim();
+}
+/** The listen file's key, not whichever key answered on the port. */
+function answerMatchesListenKey(body, row, resultHash, publicKeyPem) {
+    const receipt = body.receipt;
+    const coseHex = body.attestation?.coseHex;
+    if (!receipt || typeof coseHex !== "string" || coseHex === "")
+        return false;
+    if (typeof receipt.publicKeyPem !== "string" || !pemSame(receipt.publicKeyPem, publicKeyPem))
+        return false;
+    const clean = {
+        ref: row.ref,
+        effectHash: row.effectHash,
+        effectClass: row.effectClass,
+        timestampMs: row.timestampMs,
+        ...(row.actor !== undefined ? { actor: row.actor } : {}),
+    };
+    const expected = canonical({
+        ref: clean.ref,
+        effectHash: clean.effectHash,
+        witnessClass: WITNESS_CLASS,
+        resultHash: resultHash ?? null,
+    });
+    try {
+        const decoded = decodeCoseSign1(coseFromHex(coseHex));
+        const payload = JSON.parse(Buffer.from(decoded.payload).toString("utf8"));
+        if (canonical(payload) !== expected)
+            return false;
+        if (!verifyCoseSign1(coseFromHex(coseHex), publicKeyPem, "application/json"))
+            return false;
+        if (!verifyEffectExtract(receipt, publicKeyPem))
+            return false;
+        const signedRow = receipt.body.effects[0];
+        if (signedRow == null || canonical(signedRow) !== canonical(clean))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
 export async function requestWitnessSign(stateDir, row, resultHash) {
     const listen = readWitnessListen(stateDir);
     if (!listen || !pidAlive(listen.pid)) {
@@ -213,6 +328,15 @@ export async function requestWitnessSign(stateDir, row, resultHash) {
             });
             return null;
         }
+        if (!answerMatchesListenKey(body, row, resultHash, listen.publicKeyPem)) {
+            appendStatus(stateDir, {
+                atMs: Date.now(),
+                ref: row.ref,
+                result: "self-fallback",
+                reason: "witness-key-mismatch",
+            });
+            return null;
+        }
         appendStatus(stateDir, { atMs: Date.now(), ref: row.ref, result: "signed", pid: listen.pid });
         return {
             witnessClass: WITNESS_CLASS,
@@ -283,7 +407,13 @@ export async function runWitness(stateDir) {
                 }
                 send(res, 404, { error: "not-found" });
             }
-            catch {
+            catch (err) {
+                const reason = err instanceof Error ? err.message : "";
+                if (reason === "checkpoint-unreadable") {
+                    appendStatus(stateDir, { atMs: Date.now(), result: "checkpoint-refused", reason });
+                    send(res, 409, { error: reason });
+                    return;
+                }
                 send(res, 400, { error: "bad-request" });
             }
         })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verax-ai/body",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -21,9 +21,13 @@
     "dist"
   ],
   "dependencies": {
+    "@cedulon/checkpoint": "0.13.1",
+    "@cedulon/core": "0.13.1",
+    "@cedulon/cose": "0.13.1",
+    "@cedulon/effect-extract": "0.13.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@verax-ai/inventory": "^0.3.0",
-    "@verax-ai/proxy": "^0.3.0",
+    "@verax-ai/inventory": "^0.4.0",
+    "@verax-ai/proxy": "^0.4.0",
     "jose": "^6.2.11"
   },
   "description": "VERAX body: an MCP server that decides, records and proves what an agent did.",