@verax-ai/body 0.2.1 → 0.3.0

package/README.md

@@ -29,7 +29,8 @@ Bearer token the configured issuer did not sign.
 | Variable | Required | Meaning |
 | --- | --- | --- |
 | `VERAX_ISSUER` | yes | Issuer the agent's token must carry. |
-| `VERAX_JWKS_URL` | yes | Where the body fetches the keys that verify that token. |
+| `VERAX_JWKS_URL` | one of | Where the body fetches the keys that verify that token. Set this or `VERAX_JWKS_FILE`, not both. |
+| `VERAX_JWKS_FILE` | one of | Path to a JWKS JSON file read once at start, instead of fetching `VERAX_JWKS_URL`. Accepted only with a loopback bind. |
 | `VERAX_AUDIENCE` | yes | Audience the token must name, so a token minted for something else is refused. |
 | `VERAX_STATE_DIR` | yes | Directory the ledger, keys and approvals live in. It stays on this machine. |
 | `VERAX_POLICY_FILE` | yes | Policy the gate applies. `@verax-ai/proxy` ships `policy/default.json`, which denies what it does not name. |

package/dist/auth.d.ts

@@ -6,5 +6,9 @@ export type VerifiedBearer = {
 };
 export declare function resourceMetadataUrl(audience: string): string;
 export declare function wwwAuthenticate(audience: string): string;
-export declare function createVerifier(jwksUrl: string, issuer: string, audience: string): (token: string) => Promise<VerifiedBearer>;
+export declare class JwksFileError extends Error {
+    readonly code = 78;
+    constructor(message?: string);
+}
+export declare function createVerifier(jwksUrl: string, issuer: string, audience: string, jwksFile?: string | null): (token: string) => Promise<VerifiedBearer>;
 export declare function readBearer(header: string | undefined): string | null;

package/dist/auth.js

@@ -1,4 +1,5 @@
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { readFileSync } from "node:fs";
+import { createLocalJWKSet, createRemoteJWKSet, jwtVerify } from "jose";
 const ALGS = ["ES256", "EdDSA"];
 export function resourceMetadataUrl(audience) {
     const u = new URL(audience);
@@ -11,8 +12,31 @@ export function resourceMetadataUrl(audience) {
 export function wwwAuthenticate(audience) {
     return `Bearer resource_metadata="${resourceMetadataUrl(audience)}"`;
 }
-export function createVerifier(jwksUrl, issuer, audience) {
-    const jwks = createRemoteJWKSet(new URL(jwksUrl));
+function localJwks(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new JwksFileError();
+    }
+    if (parsed === null ||
+        typeof parsed !== "object" ||
+        !Array.isArray(parsed.keys) ||
+        parsed.keys.length === 0) {
+        throw new JwksFileError();
+    }
+    return createLocalJWKSet(parsed);
+}
+export class JwksFileError extends Error {
+    code = 78;
+    constructor(message = "VERAX_JWKS_FILE is missing or unparsable") {
+        super(message);
+        this.name = "JwksFileError";
+    }
+}
+export function createVerifier(jwksUrl, issuer, audience, jwksFile) {
+    const jwks = jwksFile ? localJwks(jwksFile) : createRemoteJWKSet(new URL(jwksUrl));
     return async (token) => {
         const { payload } = await jwtVerify(token, jwks, {
             issuer,

package/dist/cli.js

@@ -6,6 +6,7 @@ import { runApprove } from "./approve-cli.js";
 import { runDemo } from "./demo.js";
 import { desktopMain } from "./desktop.js";
 import { doctorExit, runDoctor } from "./doctor.js";
+import { loadEnvFile, runInitLocal } from "./init-local.js";
 import { runHalt } from "./halt.js";
 import { main } from "./main.js";
 import { runOperator } from "./operator-cli.js";
@@ -18,8 +19,12 @@ const HELP = `verax - the body an agent asks before it acts, and the ledger it a
 Usage: verax <command> [options]
 
   (no command)         serve MCP over Streamable HTTP at /mcp on VERAX_BIND (default 127.0.0.1:8787)
+  serve [--env-file <file>]  same as serving, after loading KEY=VALUE lines from that file
+  init --local <stateDir> [--force] [--days N] [--port N]
+                       write a loopback key, one agent token, and verax.env
   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
+       [--with-conarium]  also fetch Conarium with npx, attach it as a child, and put a masked read through the gate
   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
@@ -33,9 +38,9 @@ Usage: verax <command> [options]
   --help, -h           print this
   --version, -v        print the version
 
-Serving needs VERAX_ISSUER, VERAX_JWKS_URL, VERAX_AUDIENCE, VERAX_STATE_DIR and
-VERAX_POLICY_FILE; \`verax doctor\` names what is missing. Records stay on this
-machine, under VERAX_STATE_DIR.
+Serving needs VERAX_ISSUER, one of VERAX_JWKS_URL or VERAX_JWKS_FILE, VERAX_AUDIENCE,
+VERAX_STATE_DIR and VERAX_POLICY_FILE; \`verax doctor\` names what is missing.
+Records stay on this machine, under VERAX_STATE_DIR.
 `;
 function version() {
     // The published package answers with its own version, not a copy of it.
@@ -95,6 +100,28 @@ if (argv[0] === "unlock") {
     }
     process.exit(runUnlock(stateDir, (s) => process.stderr.write(s), { force }));
 }
+if (argv[0] === "init") {
+    process.exit(await runInitLocal(argv.slice(1)));
+}
+if (argv[0] === "serve") {
+    const fileFlag = argv.indexOf("--env-file");
+    if (fileFlag !== -1) {
+        const file = argv[fileFlag + 1];
+        if (!file || file.startsWith("-")) {
+            process.stderr.write("verax serve --env-file <file>\n");
+            process.exit(78);
+        }
+        const loaded = loadEnvFile(file);
+        if (!loaded.ok) {
+            process.stderr.write(`${loaded.reason}\n`);
+            process.exit(78);
+        }
+    }
+    await main();
+    // main() returns once the server is listening. The open socket keeps the
+    // process up; this promise stops the rest of the dispatcher from running.
+    await new Promise(() => { });
+}
 if (argv[0] === "doctor") {
     const json = argv.includes("--json");
     const checks = runDoctor(process.env, process.argv);

package/dist/config.d.ts

@@ -8,6 +8,11 @@ export type BodyConfig = {
     bindPort: number;
     policyFile: string;
     tlsTerminated: boolean;
+    /**
+     * Path to a JWKS file read once at start. Set instead of `jwksUrl`.
+     * Loopback binds only.
+     */
+    jwksFile?: string | null;
     /** Path to an inventory JSON file. Missing file is absence, not a fault. */
     inventoryFile?: string | null;
     /**

package/dist/config.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 export const EX_CONFIG = 78;
 const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
 function parseBind(raw) {
@@ -14,11 +15,28 @@ export function isLoopbackHost(host) {
     const stripped = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
     return LOOPBACK.has(stripped);
 }
+function jwksFileParses(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Array.isArray(parsed.keys) && parsed.keys.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 export function loadConfig(env) {
     const issuer = env.VERAX_ISSUER?.trim() ?? "";
     const jwksUrl = env.VERAX_JWKS_URL?.trim() ?? "";
+    const jwksFile = env.VERAX_JWKS_FILE?.trim() ?? "";
     const audience = env.VERAX_AUDIENCE?.trim() ?? "";
-    if (issuer === "" || jwksUrl === "" || audience === "") {
+    if (jwksUrl !== "" && jwksFile !== "") {
+        return {
+            ok: false,
+            code: EX_CONFIG,
+            reason: "both VERAX_JWKS_URL and VERAX_JWKS_FILE",
+        };
+    }
+    if (issuer === "" || audience === "" || (jwksUrl === "" && jwksFile === "")) {
         return {
             ok: false,
             code: EX_CONFIG,
@@ -27,6 +45,13 @@ export function loadConfig(env) {
     }
     const bind = parseBind(env.VERAX_BIND);
     const tlsTerminated = env.VERAX_TLS_TERMINATED === "1";
+    if (jwksFile !== "" && !isLoopbackHost(bind.host)) {
+        return {
+            ok: false,
+            code: EX_CONFIG,
+            reason: "VERAX_JWKS_FILE needs a loopback bind",
+        };
+    }
     if (!isLoopbackHost(bind.host) && !tlsTerminated) {
         return {
             ok: false,
@@ -34,6 +59,13 @@ export function loadConfig(env) {
             reason: "non-loopback bind without VERAX_TLS_TERMINATED=1",
         };
     }
+    if (jwksFile !== "" && !jwksFileParses(jwksFile)) {
+        return {
+            ok: false,
+            code: EX_CONFIG,
+            reason: "VERAX_JWKS_FILE is missing or unparsable",
+        };
+    }
     const stateDir = env.VERAX_STATE_DIR?.trim() ?? "";
     if (stateDir === "") {
         return { ok: false, code: EX_CONFIG, reason: "missing VERAX_STATE_DIR" };
@@ -49,6 +81,7 @@ export function loadConfig(env) {
         value: {
             issuer,
             jwksUrl,
+            jwksFile: jwksFile === "" ? null : jwksFile,
             audience,
             stateDir,
             bindHost: bind.host,

package/dist/demo.d.ts

@@ -8,4 +8,11 @@ export type DemoIo = {
     stdin: NodeJS.ReadableStream;
     isTTY: boolean;
 };
-export declare function runDemo(argv: string[], env: NodeJS.ProcessEnv, io: DemoIo): Promise<number>;
+/** Test injection. The CLI never passes this; it is not read from argv or env. */
+export type DemoOpts = {
+    conariumChild?: {
+        command: string;
+        args: string[];
+    };
+};
+export declare function runDemo(argv: string[], env: NodeJS.ProcessEnv, io: DemoIo, opts?: DemoOpts): Promise<number>;

package/dist/demo.js

@@ -11,6 +11,16 @@ 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 NOT_SHOWN_WITH_CONARIUM = "Not shown here: a real database (these are Conarium's sample rows); statement reconciliation needs a real statement (verax reconcile).";
+const NPX_DOWNLOAD_LINE = "npx will download @conarium-ai/core from npm and run it as a child process; a cold download takes longer.\n";
+const CONARIUM_NPX = {
+    command: "npx",
+    args: ["-y", "--package=@conarium-ai/core@^0.2.51", "conarium", "--demo"],
+};
+const CONARIUM_TIMEOUT_MS = 120_000;
+const CUSTOMERS_SQL = "SELECT name, email, card FROM public.customers";
+const SECRETS_SQL = "SELECT * FROM public.secrets";
+const MASKED_PII = "[MASKED_PII]";
 const AUDIENCE = "http://127.0.0.1/verax-demo";
 const KID = "demo";
 const TOKEN_TTL_SEC = 5 * 60;
@@ -48,7 +58,7 @@ function shippedPolicyPath() {
     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) {
+function writeDemoPolicy(stateDir, withConarium) {
     const shipped = JSON.parse(readFileSync(shippedPolicyPath(), "utf8"));
     const document = {
         ...shipped,
@@ -75,12 +85,34 @@ function writeDemoPolicy(stateDir) {
                     dailyMaxMinor: 10_000,
                 },
             },
+            ...(withConarium
+                ? [
+                    {
+                        id: "conarium-query",
+                        tool: "conarium.query",
+                        requires: ["verax:read"],
+                        text: "A data read through Conarium needs the read scope.",
+                    },
+                ]
+                : []),
         ],
     };
     const path = join(stateDir, "policy.json");
     writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
     return path;
 }
+function writeConariumDownstream(stateDir, child) {
+    const path = join(stateDir, "downstream.json");
+    const document = {
+        prefix: "conarium",
+        command: child.command,
+        args: [...child.args],
+        trust: "same-user",
+        timeoutMs: CONARIUM_TIMEOUT_MS,
+    };
+    writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return path;
+}
 function closeHttp(server) {
     if (!server)
         return Promise.resolve();
@@ -142,6 +174,49 @@ function parseTagged(text, kind) {
     const m = new RegExp(`^${kind}:([^:]+):(.+)$`).exec(text.trim());
     return m ? { code: m[1], ref: m[2] } : null;
 }
+async function callToolCaught(client, name, args) {
+    try {
+        const result = await client.callTool({ name, arguments: args });
+        return { isError: result.isError === true, text: toolText(result) };
+    }
+    catch (err) {
+        return { isError: true, text: err instanceof Error ? err.message : "fault" };
+    }
+}
+function customerRowsMasked(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return false;
+    const rows = parsed.rows;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return false;
+    for (const row of rows) {
+        if (row === null || typeof row !== "object")
+            return false;
+        const rec = row;
+        if (rec.email !== MASKED_PII || rec.card !== MASKED_PII)
+            return false;
+    }
+    return true;
+}
+/**
+ * The body passes on that a downstream tool answered with an error, not what it
+ * said: the detail is the fixed word `call-failed`. A child that died or timed
+ * out carries the transport's own message there instead, and that is not an
+ * answer from Conarium.
+ */
+function childAnsweredWithError(text, tool) {
+    return text.trim().endsWith(`downstream-call-failed:${tool}:call-failed`);
+}
+function attachFailedDetail(detail) {
+    return /downstream-attach-failed|downstream-attach-timeout/.test(detail);
+}
 async function readAnswer(stdin) {
     const ended = stdin.readableEnded;
     if (ended)
@@ -165,18 +240,21 @@ async function readAnswer(stdin) {
             stdin.resume();
     });
 }
-export async function runDemo(argv, env, io) {
+export async function runDemo(argv, env, io, opts) {
     if (env.NODE_ENV === "production") {
         io.stderr.write("demo refuses NODE_ENV=production\n");
         return 1;
     }
     const keep = argv.includes("--keep");
+    const withConarium = argv.includes("--with-conarium");
     let stateDir = null;
     let jwks = null;
     let body = null;
     let client = null;
     let token = "";
     let cleaned = false;
+    let discardState = false;
+    let failed = false;
     const writeOut = (s) => {
         io.stdout.write(redact(s, token));
     };
@@ -196,7 +274,7 @@ export async function runDemo(argv, env, io) {
         body = null;
         await closeHttp(jwks);
         jwks = null;
-        if (stateDir && !keep) {
+        if (stateDir && (!keep || discardState)) {
             try {
                 rmSync(stateDir, { recursive: true, force: true });
             }
@@ -212,13 +290,21 @@ export async function runDemo(argv, env, io) {
     process.once("SIGTERM", onStop);
     try {
         stateDir = mkdtempSync(join(tmpdir(), "verax-demo-"));
-        const policyFile = writeDemoPolicy(stateDir);
+        const policyFile = writeDemoPolicy(stateDir, withConarium);
         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`;
+        let downstreamFile;
+        if (withConarium) {
+            const child = opts?.conariumChild ?? CONARIUM_NPX;
+            downstreamFile = writeConariumDownstream(stateDir, child);
+            if (!opts?.conariumChild) {
+                writeErr(NPX_DOWNLOAD_LINE);
+            }
+        }
         body = await listen({
             issuer,
             jwksUrl,
@@ -228,6 +314,7 @@ export async function runDemo(argv, env, io) {
             bindPort: 0,
             policyFile,
             tlsTerminated: false,
+            ...(downstreamFile !== undefined ? { downstreamFile } : {}),
         });
         const addr = body.address();
         if (!addr || typeof addr === "string")
@@ -298,6 +385,49 @@ export async function runDemo(argv, env, io) {
             writeOut("  no terminal to ask, so it stays held (run this in a terminal to be asked)\n");
         }
         writeOut("\n");
+        if (withConarium) {
+            const customers = await callToolCaught(client, "conarium.query", { sql: CUSTOMERS_SQL });
+            if (customers.isError)
+                throw new Error(`demo: conarium.query customers ${customers.text}`);
+            writeOut("conarium.query customers\n");
+            if (customerRowsMasked(customers.text)) {
+                writeOut("  allowed; masked by Conarium before the rows left it\n");
+                writeOut("  measured [MASKED_PII] on every email and card\n");
+            }
+            else {
+                writeOut("  allowed; did not come out masked\n");
+                failed = true;
+            }
+            writeOut("\n");
+            const secrets = await callToolCaught(client, "conarium.query", { sql: SECRETS_SQL });
+            const secretsDenied = parseTagged(secrets.text, "denied");
+            writeOut("conarium.query public.secrets\n");
+            if (secretsDenied) {
+                writeOut(`  refused ${secretsDenied.code} (signed)\n`);
+                failed = true;
+            }
+            else if (childAnsweredWithError(secrets.text, "conarium.query")) {
+                writeOut("  allowed by this gate; Conarium answered with an error and no rows\n");
+                writeOut("  recorded as a failed call\n");
+            }
+            else if (secrets.isError) {
+                writeOut("  allowed by this gate; the call to Conarium failed before it answered\n");
+                failed = true;
+            }
+            else {
+                writeOut("  allowed; Conarium did not refuse public.secrets\n");
+                failed = true;
+            }
+            writeOut("\n");
+            const listed = await callToolCaught(client, "conarium.list_tables", {});
+            const listedDenied = parseTagged(listed.text, "denied");
+            writeOut("conarium.list_tables\n");
+            if (!listedDenied)
+                throw new Error(`demo: conarium.list_tables ${listed.text}`);
+            writeOut(`  refused ${listedDenied.code} (signed)\n`);
+            writeOut("  refused by this gate; the downstream server never saw the call\n");
+            writeOut("\n");
+        }
         const explained = await client.callTool({
             name: "audit.explain",
             arguments: { ref: denied.ref },
@@ -343,13 +473,19 @@ export async function runDemo(argv, env, io) {
             writeOut("ledger   removed on exit (run with --keep to keep it and check it with verax verify)\n");
         }
         writeOut("\n");
-        writeOut(`${NOT_SHOWN}\n`);
+        writeOut(`${withConarium ? NOT_SHOWN_WITH_CONARIUM : NOT_SHOWN}\n`);
         await cleanup();
-        return 0;
+        return failed ? 1 : 0;
     }
     catch (err) {
         const detail = err instanceof Error ? err.message : "fault";
-        writeErr(`demo: ${detail}\n`);
+        if (withConarium && attachFailedDetail(detail)) {
+            discardState = true;
+            writeErr(`could not start the Conarium child (${detail}). run without --with-conarium\n`);
+        }
+        else {
+            writeErr(`demo: ${detail}\n`);
+        }
         await cleanup();
         return 1;
     }

package/dist/desktop.d.ts

@@ -1,3 +1,6 @@
+export declare function resolveRepoRoot(): string;
+export declare const DESKTOP_CLONE_ONLY = "verax desktop runs from a clone of github.com/verax-ai/verax; it is not in the npm package\n";
+export declare function desktopCloneError(root: string): string | null;
 export type DesktopOpts = {
     stateDir: string;
     panelPort: number;

package/dist/desktop.js

@@ -6,7 +6,16 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { pidAlive, readLockFile } from "./unlock.js";
 const here = dirname(fileURLToPath(import.meta.url));
-const repoRoot = join(here, "..", "..", "..");
+export function resolveRepoRoot() {
+    return join(here, "..", "..", "..");
+}
+export const DESKTOP_CLONE_ONLY = "verax desktop runs from a clone of github.com/verax-ai/verax; it is not in the npm package\n";
+export function desktopCloneError(root) {
+    if (!existsSync(join(root, "scripts", "dev-issuer.mjs")) || !existsSync(join(root, "apps", "panel"))) {
+        return DESKTOP_CLONE_ONLY;
+    }
+    return null;
+}
 /** Newest modification time under a file or directory, ignoring build output. */
 function newestUnder(path, since) {
     let entry;
@@ -228,6 +237,12 @@ function collectOutput(child, sink) {
     child.stderr?.on("data", feed);
 }
 export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)) {
+    const repoRoot = resolveRepoRoot();
+    const cloneOnly = desktopCloneError(repoRoot);
+    if (cloneOnly) {
+        writeErr(cloneOnly);
+        return 78;
+    }
     mkdirSync(opts.stateDir, { recursive: true });
     const tokenPath = join(opts.stateDir, "dev-token");
     const issuerScript = join(repoRoot, "scripts", "dev-issuer.mjs");

package/dist/doctor.js

@@ -9,13 +9,18 @@ const SECRET_NAME = /^(VERAX_DEV_TOKEN|.*_(TOKEN|SECRET|KEY))$/;
 export function runDoctor(env, argv) {
     const checks = [];
     const issuer = Boolean(env.VERAX_ISSUER?.trim());
-    const jwks = Boolean(env.VERAX_JWKS_URL?.trim());
+    const jwksUrl = Boolean(env.VERAX_JWKS_URL?.trim());
+    const jwksFileSet = Boolean(env.VERAX_JWKS_FILE?.trim());
+    const jwks = jwksUrl || jwksFileSet;
     const audience = Boolean(env.VERAX_AUDIENCE?.trim());
+    const tripleReady = issuer && jwks && audience;
     checks.push({
         id: "issuer-jwks-audience",
-        level: issuer && jwks && audience ? "ok" : "fail",
-        detail: issuer && jwks && audience
-            ? "VERAX_ISSUER, VERAX_JWKS_URL, and VERAX_AUDIENCE are set"
+        level: tripleReady ? "ok" : "fail",
+        detail: tripleReady
+            ? jwksFileSet && !jwksUrl
+                ? "VERAX_ISSUER, VERAX_JWKS_FILE, and VERAX_AUDIENCE are set"
+                : "VERAX_ISSUER, VERAX_JWKS_URL, and VERAX_AUDIENCE are set"
             : "one of VERAX_ISSUER, VERAX_JWKS_URL, VERAX_AUDIENCE is missing",
     });
     const loaded = loadConfig({
@@ -43,7 +48,7 @@ export function runDoctor(env, argv) {
             });
         }
     }
-    else if (loaded.reason.includes("non-loopback")) {
+    else if (loaded.reason.includes("non-loopback") || loaded.reason.includes("loopback bind")) {
         checks.push({ id: "bind", level: "fail", detail: loaded.reason });
     }
     else {
@@ -212,8 +217,61 @@ export function runDoctor(env, argv) {
             });
         }
     }
+    checks.push(...jwksFileChecks(env, stateDir));
     return checks;
 }
+function jwksFileChecks(env, stateDir) {
+    const file = env.VERAX_JWKS_FILE?.trim() ?? "";
+    if (file === "")
+        return [];
+    const out = [];
+    let kid = "";
+    let parses = false;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        const first = parsed.keys?.[0];
+        if (first && typeof first.kid === "string" && first.kid !== "") {
+            parses = true;
+            kid = first.kid;
+        }
+    }
+    catch {
+        parses = false;
+    }
+    out.push({
+        id: "jwks-file",
+        level: parses ? "ok" : "fail",
+        detail: parses ? `VERAX_JWKS_FILE ${file} parses kid ${kid}` : `VERAX_JWKS_FILE ${file} does not parse`,
+    });
+    if (stateDir === "")
+        return out;
+    const tokenPath = join(stateDir, "local-issuer", "agent.token");
+    if (!existsSync(tokenPath))
+        return out;
+    const exp = expFromToken(readFileSync(tokenPath, "utf8"));
+    const weekSec = 7 * 24 * 60 * 60;
+    if (exp !== null && exp <= Math.floor(Date.now() / 1000) + weekSec) {
+        out.push({
+            id: "local-agent-token",
+            level: "warn",
+            detail: `${tokenPath} expires within 7 days`,
+        });
+    }
+    return out;
+}
+function expFromToken(raw) {
+    const parts = raw.trim().split(".");
+    if (parts.length < 2)
+        return null;
+    try {
+        const json = Buffer.from(parts[1], "base64url").toString("utf8");
+        const payload = JSON.parse(json);
+        return typeof payload.exp === "number" ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
 const DEFAULT_REDIRECTS = ["http://127.0.0.1:5173/", "http://127.0.0.1:4173/"];
 function stripSlash(s) {
     return s.replace(/\/$/, "");

package/dist/init-local.d.ts

@@ -0,0 +1,15 @@
+export type InitIo = {
+    stdout: {
+        write(s: string): unknown;
+    };
+    stderr: {
+        write(s: string): unknown;
+    };
+};
+export declare function loadEnvFile(path: string, env?: NodeJS.ProcessEnv): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function runInitLocal(argv: readonly string[], io?: InitIo): Promise<number>;

package/dist/init-local.js

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { calculateJwkThumbprint, exportJWK, exportPKCS8, generateKeyPair, importPKCS8, SignJWT, } from "jose";
+import { EX_CONFIG } from "./config.js";
+const ISSUER = "verax-local";
+const SUBJECT = "local-agent";
+const SCOPE = "verax:read verax:memory";
+const DEFAULT_DAYS = 30;
+const MAX_DAYS = 90;
+const DEFAULT_PORT = 8787;
+const MIN_PORT = 1024;
+const MAX_PORT = 65535;
+export function loadEnvFile(path, env = process.env) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return { ok: false, reason: "env file is missing or unreadable" };
+    }
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let value = trimmed.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+            (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return { ok: true };
+}
+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;
+    }
+    return null;
+}
+function ownerOnly(path) {
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // The platform does not honour the mode bit.
+    }
+}
+function slashPath(path) {
+    return path.replaceAll("\\", "/");
+}
+function shQuote(path) {
+    return `'${slashPath(path).replaceAll("'", "'\\''")}'`;
+}
+function psQuote(path) {
+    return `'${slashPath(path).replaceAll("'", "''")}'`;
+}
+function parseInitArgs(argv) {
+    let stateDir = "";
+    let force = false;
+    let days = DEFAULT_DAYS;
+    let port = DEFAULT_PORT;
+    let sawDays = false;
+    let sawPort = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === "--local") {
+            stateDir = argv[i + 1] ?? "";
+            i += 1;
+            continue;
+        }
+        if (a === "--force") {
+            force = true;
+            continue;
+        }
+        if (a === "--days") {
+            sawDays = true;
+            const raw = argv[i + 1] ?? "";
+            i += 1;
+            if (!/^[0-9]+$/.test(raw))
+                return { error: "--days wants an integer from 1 to 90" };
+            days = Number(raw);
+            continue;
+        }
+        if (a === "--port") {
+            sawPort = true;
+            const raw = argv[i + 1] ?? "";
+            i += 1;
+            if (!/^[0-9]+$/.test(raw))
+                return { error: "--port wants an integer from 1024 to 65535" };
+            port = Number(raw);
+            continue;
+        }
+        return { error: `flag-unknown:${a}` };
+    }
+    if (stateDir === "" || stateDir.startsWith("-")) {
+        return { error: "verax init --local <stateDir> [--force] [--days N] [--port N]" };
+    }
+    if (sawDays && (!Number.isInteger(days) || days < 1 || days > MAX_DAYS)) {
+        return { error: "--days wants an integer from 1 to 90" };
+    }
+    if (sawPort && (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT)) {
+        return { error: "--port wants an integer from 1024 to 65535" };
+    }
+    return { stateDir: resolve(stateDir), force, days, port };
+}
+export async function runInitLocal(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+    const parsed = parseInitArgs(argv);
+    if ("error" in parsed) {
+        io.stderr.write(`${parsed.error}\n`);
+        return EX_CONFIG;
+    }
+    const stateDir = parsed.stateDir;
+    const issuerDir = join(stateDir, "local-issuer");
+    if (existsSync(issuerDir) && !parsed.force) {
+        io.stderr.write(`refusing: ${issuerDir} already exists\n`);
+        return EX_CONFIG;
+    }
+    const policyDest = join(stateDir, "policy.json");
+    const policySrc = existsSync(policyDest) ? null : shippedPolicyPath();
+    if (!existsSync(policyDest) && !policySrc) {
+        io.stderr.write("shipped policy file not found\n");
+        return EX_CONFIG;
+    }
+    const { privateKey, publicKey } = await generateKeyPair("ES256", { extractable: true });
+    const pem = await exportPKCS8(privateKey);
+    const jwk = await exportJWK(publicKey);
+    const thumb = await calculateJwkThumbprint(jwk, "sha256");
+    const hex = Buffer.from(thumb, "base64url").toString("hex").slice(0, 8);
+    const kid = `verax-local-${hex}`;
+    const publicJwk = { ...jwk, alg: "ES256", use: "sig", kid };
+    const key = await importPKCS8(pem, "ES256");
+    const now = Math.floor(Date.now() / 1000);
+    const origin = `http://127.0.0.1:${parsed.port}`;
+    const token = await new SignJWT({ scope: SCOPE })
+        .setProtectedHeader({ alg: "ES256", kid })
+        .setIssuer(ISSUER)
+        .setAudience(origin)
+        .setSubject(SUBJECT)
+        .setJti(randomUUID())
+        .setIssuedAt(now)
+        .setExpirationTime(now + parsed.days * 24 * 60 * 60)
+        .sign(key);
+    mkdirSync(issuerDir, { recursive: true, mode: 0o700 });
+    const keyPath = join(issuerDir, "key.pem");
+    const jwksPath = join(issuerDir, "jwks.json");
+    const tokenPath = join(issuerDir, "agent.token");
+    const envPath = join(stateDir, "verax.env");
+    writeFileSync(keyPath, pem, { encoding: "utf8", mode: 0o600 });
+    ownerOnly(keyPath);
+    writeFileSync(jwksPath, `${JSON.stringify({ keys: [publicJwk] })}\n`, { encoding: "utf8", mode: 0o600 });
+    writeFileSync(tokenPath, token, { encoding: "utf8", mode: 0o600 });
+    ownerOnly(tokenPath);
+    const wrote = [keyPath, jwksPath, tokenPath];
+    if (!existsSync(policyDest) && policySrc) {
+        writeFileSync(policyDest, readFileSync(policySrc));
+        wrote.push(policyDest);
+    }
+    const envBody = [
+        `VERAX_ISSUER=${ISSUER}`,
+        `VERAX_JWKS_FILE=${jwksPath}`,
+        `VERAX_AUDIENCE=${origin}`,
+        `VERAX_STATE_DIR=${stateDir}`,
+        `VERAX_POLICY_FILE=${policyDest}`,
+        `VERAX_BIND=127.0.0.1:${parsed.port}`,
+        "",
+    ].join("\n");
+    writeFileSync(envPath, envBody, { encoding: "utf8" });
+    wrote.push(envPath);
+    const lines = [
+        ...wrote.map((p) => `wrote ${p}`),
+        "",
+        "Start the body:",
+        `verax serve --env-file ${shQuote(envPath)}`,
+        "",
+        "Claude Code (sh):",
+        `claude mcp add --transport http verax ${origin}/mcp --header "Authorization: Bearer $(cat ${shQuote(tokenPath)})"`,
+        "",
+        "Claude Code (PowerShell):",
+        `claude mcp add --transport http verax ${origin}/mcp --header "Authorization: Bearer $(Get-Content -Raw ${psQuote(tokenPath)})"`,
+        "",
+        "Cursor / generic mcp.json:",
+        `{
+  "mcpServers": {
+    "verax": {
+      "url": "${origin}/mcp",
+      "headers": { "Authorization": "Bearer <token from your issuer>" }
+    }
+  }
+}`,
+        `The token is the content of ${tokenPath}.`,
+        "",
+        "A held call is approved on this machine with: verax approve",
+        "",
+    ];
+    io.stdout.write(lines.join("\n"));
+    return 0;
+}

package/dist/main.js

@@ -1,3 +1,4 @@
+import { JwksFileError } from "./auth.js";
 import { EX_CONFIG, loadConfig, overlayInventoryArg } from "./config.js";
 import { KeysPartialError } from "./keys.js";
 import { listen } from "./server.js";
@@ -25,6 +26,10 @@ export async function main(env = process.env, argv = process.argv) {
             process.stderr.write("keys-partial\n");
             process.exit(err.code);
         }
+        if (err instanceof JwksFileError) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(err.code);
+        }
         throw err;
     }
 }

package/dist/server.js

@@ -308,7 +308,7 @@ export async function listen(config) {
         throw err;
     }
     const toolMeta = [...TOOL_META, ...extraTools.map(downstreamMeta)];
-    const verify = createVerifier(config.jwksUrl, config.issuer, config.audience);
+    const verify = createVerifier(config.jwksUrl, config.issuer, config.audience, config.jwksFile);
     const attachHandlers = (mcp) => {
         mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolMeta }));
         mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {

package/package.json

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