@verax-ai/body 0.1.3 → 0.2.0

package/README.md

@@ -35,7 +35,7 @@ Bearer token the configured issuer did not sign.
 | `VERAX_POLICY_FILE` | yes | Policy the gate applies. `@verax-ai/proxy` ships `policy/default.json`, which denies what it does not name. |
 | `VERAX_BIND` | no | `host:port` to listen on. Default `127.0.0.1:8787`; anything but loopback needs `VERAX_TLS_TERMINATED=1`. |
 | `VERAX_INVENTORY_FILE` | no | Roster document the body serves. The format is `@verax-ai/inventory`. |
-| `VERAX_DOWNSTREAM` | no | Path to a JSON document naming MCP servers to put behind this gate: one `{ prefix, command?, args?, cwd?, env?, url?, headers?, timeoutMs? }` or an array of them. Each child names exactly one way in — `command` to spawn it over stdio, or `url` to reach one already running over Streamable HTTP, with `headers` for its own bearer. A path and not the JSON itself, because the document may name a key in `env` or `headers`. Their tools are served as `prefix.childName` and need an exact policy rule under that name; a named child that cannot be opened stops the body. |
+| `VERAX_DOWNSTREAM` | no | Path to a JSON document naming MCP servers to put behind this gate: one `{ prefix, command?, args?, cwd?, env?, url?, headers?, timeoutMs?, trust? }` or an array of them. Each child names exactly one way in — `command` to spawn it over stdio, or `url` to reach one already running over Streamable HTTP, with `headers` for its own bearer. A stdio child requires `"trust": "same-user"` (it runs as the same user as the body and can read the signing keys); an HTTP child does not ask for that field and must not carry it. This is a breaking change: existing stdio documents do not open until the field is added. A path and not the JSON itself, because the document may name a key in `env` or `headers`. Their tools are served as `prefix.childName` and need an exact policy rule under that name; a named child that cannot be opened stops the body. |
 
 `verax doctor` names what is missing. A misconfigured body exits with code 78
 before it listens.

package/dist/cli.js

@@ -9,6 +9,7 @@ import { runHalt } from "./halt.js";
 import { main } from "./main.js";
 import { runOperator } from "./operator-cli.js";
 import { runReconcile } from "./reconcile-cli.js";
+import { runVerify } from "./verify-cli.js";
 import { runUnlock } from "./unlock.js";
 import { runWitness } from "./witness.js";
 const HELP = `verax - the body an agent asks before it acts, and the ledger it answers from.
@@ -20,6 +21,8 @@ Usage: verax <command> [options]
   approve <args>       approve a waiting request from this machine
   operator <args>      enrol an operator and manage their passkeys
   reconcile <args>     compare the ledger against a statement
+  verify <stateDir>    read a ledger back without a body: signatures, chain,
+                       effect binding, and which key answered
   witness <stateDir>   run the witness alongside a body
   halt <stateDir>      stop the body from allowing anything further
   unlock [--force] <stateDir>   clear a stale ledger lock
@@ -98,6 +101,9 @@ if (argv[0] === "doctor") {
 if (argv[0] === "reconcile") {
     process.exit(runReconcile(argv));
 }
+if (argv[0] === "verify") {
+    process.exit(await runVerify(argv.slice(1)));
+}
 if (argv[0] === "desktop") {
     process.exit(await desktopMain(argv));
 }

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { indexCoverage, listPieceFiles } from "@verax-ai/proxy";
 import { loadConfig, isLoopbackHost } from "./config.js";
+import { parseDownstreamDocument } from "./downstream.js";
 import { pidAlive, readLockFile } from "./unlock.js";
 const SECRET_RE = /sk-|-----BEGIN|Bearer |eyJ[A-Za-z0-9_-]{10,}\./;
 const SECRET_NAME = /^(VERAX_DEV_TOKEN|.*_(TOKEN|SECRET|KEY))$/;
@@ -184,6 +185,33 @@ export function runDoctor(env, argv) {
             });
         }
     }
+    const downstreamPath = env.VERAX_DOWNSTREAM?.trim() ?? "";
+    if (downstreamPath !== "") {
+        try {
+            const specs = parseDownstreamDocument(readFileSync(downstreamPath, "utf8"));
+            const stdio = specs.filter((s) => s.command !== undefined);
+            const http = specs.filter((s) => s.url !== undefined);
+            checks.push({
+                id: "downstream-document",
+                level: "ok",
+                detail: `${specs.length} child(ren): ${stdio.length} stdio, ${http.length} http`,
+            });
+            for (const spec of stdio) {
+                checks.push({
+                    id: `downstream-stdio:${spec.prefix}`,
+                    level: "warn",
+                    detail: `stdio child ${spec.prefix} runs as the same user as the body and can read the body's signing keys (keys/*.pem). An untrusted child should be reached over HTTP, ideally on a separate machine or under a separate operating-system user.`,
+                });
+            }
+        }
+        catch (err) {
+            checks.push({
+                id: "downstream-document",
+                level: "fail",
+                detail: err instanceof Error ? err.message : "downstream-document-unreadable",
+            });
+        }
+    }
     return checks;
 }
 const DEFAULT_REDIRECTS = ["http://127.0.0.1:5173/", "http://127.0.0.1:4173/"];

package/dist/downstream.d.ts

@@ -18,6 +18,12 @@ export type DownstreamSpec = {
     /** HTTP: headers the operator sends to the child, such as its own bearer. */
     headers?: Record<string, string>;
     timeoutMs?: number;
+    /**
+     * stdio only. The operator wrote that this child runs as the same user
+     * as the body and can read the body's signing keys. Required on stdio;
+     * forbidden on HTTP.
+     */
+    trust?: "same-user";
 };
 export type DownstreamTool = {
     name: string;

package/dist/downstream.js

@@ -6,6 +6,10 @@ const PREFIX_RE = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
 const CHILD_TOOL_RE = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
 /** Prefixed name a caller may put on extraTools: `prefix.childName`. */
 const EXTRA_NAME_RE = /^[A-Za-z][A-Za-z0-9_-]{0,31}\.[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+// Sanity bound, not a capacity claim. A child that lists more than this is
+// hostile or broken; the body is not a registry for thousands of names.
+const MAX_CHILD_TOOLS = 256;
+const MAX_TOOL_BYTES = 64 * 1024;
 export class DownstreamCallError extends Error {
     prefix;
     tool;
@@ -25,6 +29,18 @@ export function prefixedName(prefix, childName) {
 export function extraToolNameOk(name) {
     return EXTRA_NAME_RE.test(name);
 }
+/**
+ * The operator wrote `"trust": "same-user"` on a stdio child. Missing ack
+ * refuses start. One rule, two call sites — do not duplicate the predicate.
+ */
+function assertStdioTrusted(spec) {
+    if (spec.command !== undefined && spec.trust !== "same-user") {
+        // The prefix is the operator's own name for the child and names WHICH entry
+        // to fix in a document with several. Nothing else about the child goes in:
+        // not the command, the arguments or the environment.
+        throw new Error(`downstream-stdio-trust-required:${spec.prefix}`);
+    }
+}
 export function parseDownstreamJson(raw) {
     let parsed;
     try {
@@ -113,6 +129,16 @@ export function parseDownstreamJson(raw) {
         }
         spec.timeoutMs = rec.timeoutMs;
     }
+    if (rec.trust !== undefined) {
+        // HTTP + any trust, or a value other than "same-user", is the same
+        // refusal: the field is not a claim about a remote host, and it is
+        // not a free-form string.
+        if (spec.url !== undefined || rec.trust !== "same-user") {
+            throw new Error("downstream-trust-invalid");
+        }
+        spec.trust = "same-user";
+    }
+    assertStdioTrusted(spec);
     return spec;
 }
 /**
@@ -171,6 +197,8 @@ function stdioTransport(spec) {
     if (spec.command === undefined || spec.command.trim() === "") {
         throw new Error("downstream-command-invalid");
     }
+    // Last check before the spawn: openDownstream can be called without parse.
+    assertStdioTrusted(spec);
     // Safe inherit + operator overlay. Not process.env: that would copy
     // VERAX_* tokens the body already holds.
     const env = { ...getDefaultEnvironment(), ...(spec.env ?? {}) };
@@ -196,9 +224,47 @@ function httpTransport(spec) {
     if (spec.url === undefined)
         throw new Error("downstream-url-invalid");
     return new StreamableHTTPClientTransport(new URL(spec.url), {
-        ...(spec.headers ? { requestInit: { headers: spec.headers } } : {}),
+        requestInit: {
+            // The child's address is the operator's document, not a place the
+            // child may name. Following a redirect would rewrite that document
+            // at run time. The egress list does not see it: egress is for hosts
+            // the brain picks.
+            redirect: "error",
+            ...(spec.headers ? { headers: spec.headers } : {}),
+        },
     });
 }
+/**
+ * `connect` does not take a timeout option. Race it, close the transport
+ * when the clock wins, and drop the timer so a settled attach cannot keep
+ * the process alive.
+ */
+async function connectWithDeadline(client, transport, timeoutMs, prefix) {
+    let timer;
+    try {
+        await new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                void shut(client, transport);
+                reject(new Error(`downstream-attach-timeout:${prefix}`));
+            }, timeoutMs);
+            client.connect(transport).then(resolve, reject);
+        });
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function attachTimeoutError(err, prefix) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.startsWith("downstream-attach-timeout:")) {
+        return err instanceof Error ? err : new Error(`downstream-attach-timeout:${prefix}`);
+    }
+    if (/timed?\s*out|timeout/i.test(msg)) {
+        return new Error(`downstream-attach-timeout:${prefix}`);
+    }
+    return err instanceof Error ? err : new Error(msg);
+}
 export async function openDownstream(spec) {
     if (!PREFIX_RE.test(spec.prefix)) {
         throw new Error("downstream-prefix-invalid");
@@ -214,12 +280,16 @@ export async function openDownstream(spec) {
     const client = new Client({ name: "verax-downstream", version: "0.0.0" });
     let listed;
     try {
-        await client.connect(transport);
-        listed = await client.listTools();
+        await connectWithDeadline(client, transport, timeoutMs, spec.prefix);
+        listed = await client.listTools(undefined, { timeout: timeoutMs });
     }
     catch (err) {
         await shut(client, transport);
-        throw err;
+        throw attachTimeoutError(err, spec.prefix);
+    }
+    if (listed.tools.length > MAX_CHILD_TOOLS) {
+        await shut(client, transport);
+        throw new Error(`downstream-too-many-tools:${spec.prefix}:${listed.tools.length}`);
     }
     const tools = [];
     const seen = new Set();
@@ -228,6 +298,15 @@ export async function openDownstream(spec) {
             await shut(client, transport);
             throw new Error(`downstream-child-name-invalid:${tool.name}`);
         }
+        const toolBytes = JSON.stringify({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }).length;
+        if (toolBytes > MAX_TOOL_BYTES) {
+            await shut(client, transport);
+            throw new Error(`downstream-tool-too-large:${spec.prefix}.${tool.name}:${toolBytes}`);
+        }
         const name = prefixedName(spec.prefix, tool.name);
         if (seen.has(name)) {
             await shut(client, transport);

package/dist/verify-cli.d.ts

@@ -0,0 +1,5 @@
+import { type VerifyResult } from "@verax-ai/proxy";
+export declare const EX_VERIFY_FAILED = 1;
+/** Lines a person reads. The trust line is never omitted. */
+export declare function renderVerify(r: VerifyResult): string;
+export declare function runVerify(argv: readonly string[], out?: (s: string) => void): Promise<number>;

package/dist/verify-cli.js

@@ -0,0 +1,91 @@
+/**
+ * `verax verify <stateDir>` — read a ledger back without a body.
+ *
+ * The command exists for the moment a customer stops being a customer. A
+ * ledger that only the vendor's running service can read is not evidence a
+ * buyer holds; it is evidence they rent. This reads the directory on its own,
+ * with nothing listening and nothing on the network, and says what still
+ * holds together.
+ *
+ * It refuses to flatten four separate questions into one word. Signatures,
+ * the chain, the binding between effects and decisions, and — the one worth
+ * the most — **which key** answered. Verifying against the key lying in the
+ * same directory proves the files agree with each other and nothing else;
+ * that line is printed every time, not buried in a flag.
+ */
+import { readFileSync } from "node:fs";
+import { verifyLedger } from "@verax-ai/proxy";
+export const EX_VERIFY_FAILED = 1;
+function usage() {
+    return [
+        "usage: verax verify <stateDir> [--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'.",
+        "  --json            machine-readable result on stdout",
+        "",
+        "Exit code is 0 when the ledger verifies and 1 when it does not.",
+    ].join("\n");
+}
+/** Lines a person reads. The trust line is never omitted. */
+export function renderVerify(r) {
+    const lines = [];
+    lines.push(`ledger        ${r.directory}`);
+    lines.push(`decisions     ${r.decisions}`);
+    lines.push(`effects       ${r.effects} (${r.effectsBound} bound to a decision, ${r.effectsOrphaned} with none)`);
+    lines.push(`signatures    ${r.signaturesValid} verify, ${r.signaturesInvalid} do not`);
+    lines.push(`chain         ${r.chainBreakAt === null ? "unbroken" : `breaks at record ${r.chainBreakAt}`}`);
+    lines.push(`verified with ${r.trust.source === "pinned"
+        ? "a key you supplied"
+        : r.trust.source === "in-ledger"
+            ? "the key carried in these files"
+            : "no key"}`);
+    lines.push(`              ${r.trust.note}`);
+    if (r.problems.length > 0) {
+        lines.push("");
+        lines.push("problems:");
+        for (const p of r.problems.slice(0, 50))
+            lines.push(`  - ${p}`);
+        if (r.problems.length > 50)
+            lines.push(`  … and ${r.problems.length - 50} more`);
+    }
+    lines.push("");
+    lines.push(r.ok ? "VERIFIED" : "NOT VERIFIED");
+    return lines.join("\n");
+}
+export async function runVerify(argv, out = (s) => process.stdout.write(`${s}\n`)) {
+    const args = [...argv];
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        out(usage());
+        return args.length === 0 ? EX_VERIFY_FAILED : 0;
+    }
+    const json = args.includes("--json");
+    let publicKeyPem;
+    const keyAt = args.indexOf("--key");
+    if (keyAt !== -1) {
+        const path = args[keyAt + 1];
+        if (!path || path.startsWith("-")) {
+            out("verify: --key needs a file path");
+            return EX_VERIFY_FAILED;
+        }
+        try {
+            publicKeyPem = readFileSync(path, "utf8");
+        }
+        catch {
+            out(`verify: cannot read key file ${path}`);
+            return EX_VERIFY_FAILED;
+        }
+        args.splice(keyAt, 2);
+    }
+    const dir = args.find((a) => !a.startsWith("-"));
+    if (!dir) {
+        out(usage());
+        return EX_VERIFY_FAILED;
+    }
+    const result = await verifyLedger(dir, publicKeyPem ? { publicKeyPem } : {});
+    out(json ? JSON.stringify(result, null, 2) : renderVerify(result));
+    return result.ok ? 0 : EX_VERIFY_FAILED;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verax-ai/body",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -22,8 +22,8 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@verax-ai/inventory": "^0.1.0",
-    "@verax-ai/proxy": "^0.1.0",
+    "@verax-ai/inventory": "^0.2.0",
+    "@verax-ai/proxy": "^0.2.0",
     "jose": "^6.2.11"
   },
   "description": "VERAX body: an MCP server that decides, records and proves what an agent did.",