@verax-ai/body 0.1.4 → 0.2.1

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

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runApprove } from "./approve-cli.js";
+import { runDemo } from "./demo.js";
 import { desktopMain } from "./desktop.js";
 import { doctorExit, runDoctor } from "./doctor.js";
 import { runHalt } from "./halt.js";
@@ -18,6 +19,7 @@ Usage: verax <command> [options]
 
   (no command)         serve MCP over Streamable HTTP at /mcp on VERAX_BIND (default 127.0.0.1:8787)
   doctor [--json]      check the configuration this process would run with
+  demo [--keep]        run a loopback body against a temporary ledger and print what it recorded
   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
@@ -62,6 +64,14 @@ if (argv[0] === "--version" || argv[0] === "-v") {
     process.stdout.write(`${version()}\n`);
     process.exit(0);
 }
+if (argv[0] === "demo") {
+    process.exit(await runDemo(argv, process.env, {
+        stdout: process.stdout,
+        stderr: process.stderr,
+        stdin: process.stdin,
+        isTTY: Boolean(process.stdin.isTTY),
+    }));
+}
 if (argv[0] === "approve") {
     process.exit(await runApprove(argv));
 }

package/dist/demo.d.ts

@@ -0,0 +1,11 @@
+export type DemoIo = {
+    stdout: {
+        write(s: string): unknown;
+    };
+    stderr: {
+        write(s: string): unknown;
+    };
+    stdin: NodeJS.ReadableStream;
+    isTTY: boolean;
+};
+export declare function runDemo(argv: string[], env: NodeJS.ProcessEnv, io: DemoIo): Promise<number>;

package/dist/demo.js

@@ -0,0 +1,356 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { exportJWK, generateKeyPair, SignJWT } from "jose";
+import { verifyLedger } from "@verax-ai/proxy";
+import { runApprove } from "./approve-cli.js";
+import { listen } from "./server.js";
+const NOT_SHOWN = "Not shown here: data masking arrives with a downstream server such as Conarium; statement reconciliation needs a real statement (verax reconcile).";
+const AUDIENCE = "http://127.0.0.1/verax-demo";
+const KID = "demo";
+const TOKEN_TTL_SEC = 5 * 60;
+const DENY_HOST = "blocked.test";
+const EGRESS_HOST = "example.com";
+const SPEND = {
+    amountMinor: 100,
+    currency: "USD",
+    payee: "sample-merchant",
+    reference: "demo-1",
+};
+function redact(text, token) {
+    if (token === "" || !text.includes(token))
+        return text;
+    return text.split(token).join("[token]");
+}
+function shippedPolicyPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    let resolved = null;
+    try {
+        resolved = join(dirname(fileURLToPath(import.meta.resolve("@verax-ai/proxy/package.json"))), "policy", "default.json");
+    }
+    catch {
+        resolved = null;
+    }
+    const candidates = [
+        resolved,
+        join(here, "..", "..", "proxy", "policy", "default.json"),
+        join(here, "..", "..", "@verax-ai", "proxy", "policy", "default.json"),
+    ];
+    for (const path of candidates) {
+        if (path && existsSync(path))
+            return path;
+    }
+    throw new Error("demo: shipped policy file not found");
+}
+/** Shipped default plus message.send egress and a spend rule, written under the temp dir. */
+function writeDemoPolicy(stateDir) {
+    const shipped = JSON.parse(readFileSync(shippedPolicyPath(), "utf8"));
+    const document = {
+        ...shipped,
+        egress: [EGRESS_HOST],
+        rules: [
+            ...shipped.rules,
+            {
+                id: "message-send",
+                tool: "message.send",
+                requires: ["verax:memory"],
+                egress: true,
+                text: "Queueing a message needs the memory scope and a recipient host on the egress list.",
+            },
+            {
+                id: "spend",
+                tool: "spend",
+                requires: ["verax:pay"],
+                mode: "approve",
+                text: "A payment is held for an operator.",
+                spend: {
+                    maxAmountMinor: 5000,
+                    currency: "USD",
+                    payees: [SPEND.payee],
+                    dailyMaxMinor: 10_000,
+                },
+            },
+        ],
+    };
+    const path = join(stateDir, "policy.json");
+    writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return path;
+}
+function closeHttp(server) {
+    if (!server)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        if (typeof server.closeAllConnections === "function")
+            server.closeAllConnections();
+        server.close(() => resolve());
+    });
+}
+async function serveJwks(jwk) {
+    const server = createServer((req, res) => {
+        if (req.method === "GET" && (req.url === "/.well-known/jwks.json" || req.url === "/.well-known/jwks.json/")) {
+            const body = JSON.stringify({ keys: [jwk] });
+            res.writeHead(200, {
+                "content-type": "application/json",
+                "content-length": Buffer.byteLength(body),
+            });
+            res.end(body);
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === "string") {
+        server.close();
+        throw new Error("demo: jwks bind failed");
+    }
+    return { server, issuer: `http://127.0.0.1:${addr.port}` };
+}
+async function mintToken(privateKey, issuer, audience) {
+    const nowSec = Math.floor(Date.now() / 1000);
+    return new SignJWT({ scope: "verax:read verax:memory verax:pay" })
+        .setProtectedHeader({ alg: "ES256", kid: KID })
+        .setSubject("demo-brain")
+        .setIssuer(issuer)
+        .setAudience(audience)
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + TOKEN_TTL_SEC)
+        .setJti(randomUUID())
+        .sign(privateKey);
+}
+function toolText(result) {
+    const content = result && typeof result === "object" ? result.content : undefined;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => part && typeof part === "object" && "text" in part && typeof part.text === "string"
+        ? part.text
+        : "")
+        .filter((s) => s !== "")
+        .join("\n");
+}
+function parseTagged(text, kind) {
+    const m = new RegExp(`^${kind}:([^:]+):(.+)$`).exec(text.trim());
+    return m ? { code: m[1], ref: m[2] } : null;
+}
+async function readAnswer(stdin) {
+    const ended = stdin.readableEnded;
+    if (ended)
+        return "";
+    return await new Promise((resolve) => {
+        const done = (value) => {
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.off("error", onErr);
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            done(String(chunk).split(/\r?\n/)[0] ?? "");
+        };
+        const onEnd = () => done("");
+        const onErr = () => done("");
+        stdin.once("data", onData);
+        stdin.once("end", onEnd);
+        stdin.once("error", onErr);
+        if (typeof stdin.resume === "function")
+            stdin.resume();
+    });
+}
+export async function runDemo(argv, env, io) {
+    if (env.NODE_ENV === "production") {
+        io.stderr.write("demo refuses NODE_ENV=production\n");
+        return 1;
+    }
+    const keep = argv.includes("--keep");
+    let stateDir = null;
+    let jwks = null;
+    let body = null;
+    let client = null;
+    let token = "";
+    let cleaned = false;
+    const writeOut = (s) => {
+        io.stdout.write(redact(s, token));
+    };
+    const writeErr = (s) => {
+        io.stderr.write(redact(s, token));
+    };
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        process.off("SIGINT", onStop);
+        process.off("SIGTERM", onStop);
+        if (client)
+            await client.close().catch(() => undefined);
+        client = null;
+        await closeHttp(body);
+        body = null;
+        await closeHttp(jwks);
+        jwks = null;
+        if (stateDir && !keep) {
+            try {
+                rmSync(stateDir, { recursive: true, force: true });
+            }
+            catch {
+                // OS temp cleanup
+            }
+        }
+    };
+    const onStop = () => {
+        void cleanup();
+    };
+    process.once("SIGINT", onStop);
+    process.once("SIGTERM", onStop);
+    try {
+        stateDir = mkdtempSync(join(tmpdir(), "verax-demo-"));
+        const policyFile = writeDemoPolicy(stateDir);
+        const { privateKey, publicKey } = await generateKeyPair("ES256");
+        const jwk = { ...(await exportJWK(publicKey)), alg: "ES256", use: "sig", kid: KID };
+        const jwksBind = await serveJwks(jwk);
+        jwks = jwksBind.server;
+        const issuer = jwksBind.issuer;
+        const jwksUrl = `${issuer}/.well-known/jwks.json`;
+        body = await listen({
+            issuer,
+            jwksUrl,
+            audience: AUDIENCE,
+            stateDir,
+            bindHost: "127.0.0.1",
+            bindPort: 0,
+            policyFile,
+            tlsTerminated: false,
+        });
+        const addr = body.address();
+        if (!addr || typeof addr === "string")
+            throw new Error("demo: body bind failed");
+        const mcpUrl = `http://127.0.0.1:${addr.port}/mcp`;
+        token = await mintToken(privateKey, issuer, AUDIENCE);
+        client = new Client({ name: "verax-demo", version: "0.0.0" });
+        await client.connect(new StreamableHTTPClientTransport(new URL(mcpUrl), {
+            requestInit: { headers: { authorization: `Bearer ${token}` } },
+        }));
+        writeOut("verax demo\n");
+        writeOut("\n");
+        const put = await client.callTool({
+            name: "memory.put",
+            arguments: {
+                id: "demo-note",
+                body: { text: "loopback demo" },
+                source: { kind: "demo" },
+                validUntilMs: Date.now() + 60 * 60 * 1000,
+            },
+        });
+        if (put.isError)
+            throw new Error(`demo: memory.put ${toolText(put)}`);
+        const got = await client.callTool({ name: "memory.get", arguments: { id: "demo-note" } });
+        if (got.isError)
+            throw new Error(`demo: memory.get ${toolText(got)}`);
+        writeOut("memory.put / memory.get\n");
+        writeOut("  allowed; two signed records\n");
+        writeOut("\n");
+        const sent = await client.callTool({
+            name: "message.send",
+            arguments: { to: `ops@${DENY_HOST}`, text: "demo" },
+        });
+        const denied = parseTagged(toolText(sent), "denied");
+        if (!denied)
+            throw new Error(`demo: message.send ${toolText(sent)}`);
+        writeOut(`message.send -> ops@${DENY_HOST}\n`);
+        writeOut(`  refused ${denied.code} (signed)\n`);
+        writeOut(`  ref ${denied.ref}\n`);
+        writeOut("\n");
+        const spent = await client.callTool({
+            name: "spend",
+            arguments: { ...SPEND },
+        });
+        const held = parseTagged(toolText(spent), "deferred");
+        if (!held)
+            throw new Error(`demo: spend ${toolText(spent)}`);
+        writeOut(`spend ${SPEND.amountMinor} minor ${SPEND.currency} ${SPEND.payee}\n`);
+        writeOut("  held\n");
+        let approved = false;
+        if (io.isTTY) {
+            writeOut("Approve this payment as the operator on this machine? [y/N]\n");
+            const answer = await readAnswer(io.stdin);
+            if (answer.trim().toLowerCase() === "y") {
+                const code = await runApprove(["approve", stateDir, held.ref], (s) => writeErr(s), () => undefined);
+                if (code !== 0)
+                    throw new Error("demo: approve failed");
+                approved = true;
+            }
+        }
+        if (approved) {
+            writeOut("  approved; operator id bound on the record\n");
+        }
+        else if (io.isTTY) {
+            writeOut("  left held\n");
+        }
+        else {
+            writeOut("  no terminal to ask, so it stays held (run this in a terminal to be asked)\n");
+        }
+        writeOut("\n");
+        const explained = await client.callTool({
+            name: "audit.explain",
+            arguments: { ref: denied.ref },
+        });
+        if (explained.isError)
+            throw new Error(`demo: audit.explain ${toolText(explained)}`);
+        let findingCode = "none";
+        let trust = "unread";
+        try {
+            const parsed = JSON.parse(toolText(explained));
+            if (typeof parsed.finding?.code === "string")
+                findingCode = parsed.finding.code;
+            if (typeof parsed.trustRoot?.source === "string")
+                trust = parsed.trustRoot.source;
+        }
+        catch {
+            findingCode = "unparsed";
+        }
+        writeOut("audit.explain of the refuse\n");
+        writeOut(`  finding ${findingCode}\n`);
+        writeOut(`  trust-root ${trust}\n`);
+        if (findingCode === "none" && trust !== "unread") {
+            writeOut("  chain and signatures read back\n");
+        }
+        else {
+            writeOut("  the read-back did not come out clean; see the finding above\n");
+        }
+        writeOut("\n");
+        await client.close().catch(() => undefined);
+        client = null;
+        await closeHttp(body);
+        body = null;
+        await closeHttp(jwks);
+        jwks = null;
+        const counted = await verifyLedger(stateDir);
+        writeOut(`records  ${counted.decisions}\n`);
+        writeOut(`effects  ${counted.effects}\n`);
+        if (keep) {
+            writeOut(`ledger   ${stateDir}\n`);
+            writeOut(`verax verify ${stateDir}\n`);
+        }
+        else {
+            writeOut("ledger   removed on exit (run with --keep to keep it and check it with verax verify)\n");
+        }
+        writeOut("\n");
+        writeOut(`${NOT_SHOWN}\n`);
+        await cleanup();
+        return 0;
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : "fault";
+        writeErr(`demo: ${detail}\n`);
+        await cleanup();
+        return 1;
+    }
+}

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

@@ -29,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 {
@@ -117,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;
 }
 /**
@@ -175,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 ?? {}) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verax-ai/body",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "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.1",
+    "@verax-ai/proxy": "^0.2.1",
     "jose": "^6.2.11"
   },
   "description": "VERAX body: an MCP server that decides, records and proves what an agent did.",