@verax-ai/body 0.3.0 → 0.4.0

package/dist/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync, realpathSync } from "node:fs";
+import path, { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runApprove } from "./approve-cli.js";
+import { attachBodyLog } from "./body-log.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 { doctorBodyLog, doctorExit, runDoctor } from "./doctor.js";
+import { clearVeraxEnv, envFileJwksMissing, loadEnvFile, runInitLocal } from "./init-local.js";
+import { clearCliCodeCheckPassed, defaultElevated, directoryAccess, doctorStateTarget, elevatedCommandCodeRefusal, linuxNodeLabelCheck, linuxSelinuxCheck, liveInstalledChecks, markCliCodeCheckPassed, runInstall, runUninstall, SystemToolError, unreadableSentence } from "./install.js";
 import { runHalt } from "./halt.js";
 import { main } from "./main.js";
 import { runOperator } from "./operator-cli.js";
@@ -19,13 +20,31 @@ 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
+  serve [--env-file <file>] [--log-file <file>]
+                       same as serving, after loading KEY=VALUE lines from that file.
+                       --log-file appends this process's stdout and stderr
   init --local <stateDir> [--force] [--days N] [--port N]
                        write a loopback key, one agent token, and verax.env
+  install [--port N] [--days N] [--force]
+                       copy this body to an administrator-owned directory and run it
+                       as another account. Needs an elevated shell, and this program
+                       must live in a directory only an administrator can change.
+                       On Windows the agent token is under %ProgramData%\\Verax\\agent-token\\<SID>\\.
+                       On Linux and macOS a process running as the invoking user writes ~/.verax/agent.token.
+  uninstall [--keep-state]
+                       stop that body and remove its code. Needs an elevated shell
+                       and the same administrator-owned copy.
   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
+  approve <args>       approve a waiting request from this machine.
+                       On Windows the panel with a passkey is how a held call is approved.
+                       An elevated CLI approve is a fallback from a separate administrator
+                       account, not this account elevated:
+                       "%ProgramFiles%\\verax-cli\\verax.cmd" approve.
+                       Linux and macOS the root-owned Node, for example
+                       sudo /opt/verax-node/<dir>/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js approve
+                       or sudo /usr/bin/node with that same cli.js.
   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,
@@ -33,7 +52,6 @@ Usage: verax <command> [options]
   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
-  desktop <args>       open the local panel, joining the body that holds the ledger if one is up
 
   --help, -h           print this
   --version, -v        print the version
@@ -57,100 +75,215 @@ function version() {
     }
     return "unknown";
 }
-const argv = process.argv.slice(2);
-// Asking what this is must work before it is configured. Without this, the
-// first thing a published `verax --help` said was that three environment
-// variables were missing.
-if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
-    process.stdout.write(HELP);
-    process.exit(0);
-}
-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));
-}
-if (argv[0] === "operator") {
-    process.exit(await runOperator(argv));
-}
-if (argv[0] === "halt") {
-    const stateDir = argv[1];
-    if (!stateDir) {
-        process.stderr.write("verax halt <stateDir>\n");
-        process.exit(78);
+function isCliEntry() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    // npm starts the CLI through a symbolic link (`bin/verax`, `node_modules/.bin/verax`): compare
+    // real paths, or a linked start runs nothing and exits 0.
+    try {
+        return realpathSync(path.resolve(entry)) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
     }
-    process.exit(runHalt(stateDir));
-}
-if (argv[0] === "unlock") {
-    const force = argv.includes("--force");
-    const stateDir = argv.slice(1).find((a) => a !== "--force");
-    if (!stateDir) {
-        process.stderr.write("verax unlock [--force] <stateDir>\n");
-        process.exit(78);
-    }
-    process.exit(runUnlock(stateDir, (s) => process.stderr.write(s), { force }));
 }
-if (argv[0] === "init") {
-    process.exit(await runInitLocal(argv.slice(1)));
+/**
+ * One gate for every command except `--help` and `--version`. An elevated
+ * process refuses code the invoking user can change before the command runs.
+ * Install and approve keep their own check for direct callers; the flag stops
+ * a second check in this process.
+ */
+export async function runCli(argv, hooks = {}) {
+    const stdout = hooks.stdout ?? process.stdout;
+    const stderr = hooks.stderr ?? process.stderr;
+    const platform = hooks.platform ?? process.platform;
+    const env = hooks.env ?? process.env;
+    if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+        stdout.write(HELP);
+        return 0;
+    }
+    if (argv[0] === "--version" || argv[0] === "-v") {
+        stdout.write(`${version()}\n`);
+        return 0;
+    }
+    let isElevated = false;
+    try {
+        isElevated = hooks.elevated ? hooks.elevated() : defaultElevated(platform);
+    }
+    catch (err) {
+        if (err instanceof SystemToolError) {
+            stderr.write(`${err.message}\n`);
+            return 78;
+        }
+        throw err;
+    }
+    if (isElevated) {
+        const refusal = elevatedCommandCodeRefusal(platform, env, hooks.codeProbe, {
+            execPathProbe: hooks.execPathProbe,
+            execArgv: hooks.execArgv,
+        });
+        if (refusal) {
+            stderr.write(refusal.endsWith("\n") ? refusal : `${refusal}\n`);
+            return 78;
+        }
+        markCliCodeCheckPassed();
+    }
+    try {
+        if (isElevated && argv[0] === "demo" && argv.includes("--with-conarium")) {
+            stderr.write("refusing: demo --with-conarium fetches and runs code with npx; run it from a terminal that is not elevated\n");
+            return 78;
+        }
+        return await dispatchCli(argv, stdout, stderr, env);
+    }
+    finally {
+        clearCliCodeCheckPassed();
+    }
 }
-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);
+async function dispatchCli(argv, stdout, stderr, env) {
+    if (argv[0] === "demo") {
+        return runDemo(argv, env, {
+            stdout,
+            stderr,
+            stdin: process.stdin,
+            isTTY: Boolean(process.stdin.isTTY),
+        });
+    }
+    if (argv[0] === "approve") {
+        return runApprove(argv);
+    }
+    if (argv[0] === "operator") {
+        return runOperator(argv);
+    }
+    if (argv[0] === "halt") {
+        const stateDir = argv[1];
+        if (!stateDir) {
+            stderr.write("verax halt <stateDir>\n");
+            return 78;
+        }
+        return runHalt(stateDir, (s) => stderr.write(s));
+    }
+    if (argv[0] === "unlock") {
+        const force = argv.includes("--force");
+        const stateDir = argv.slice(1).find((a) => a !== "--force");
+        if (!stateDir) {
+            stderr.write("verax unlock [--force] <stateDir>\n");
+            return 78;
         }
-        const loaded = loadEnvFile(file);
-        if (!loaded.ok) {
-            process.stderr.write(`${loaded.reason}\n`);
-            process.exit(78);
+        return runUnlock(stateDir, (s) => stderr.write(s), { force });
+    }
+    if (argv[0] === "init") {
+        return runInitLocal(argv.slice(1));
+    }
+    if (argv[0] === "install") {
+        return runInstall(argv);
+    }
+    if (argv[0] === "uninstall") {
+        return runUninstall(argv);
+    }
+    if (argv[0] === "serve") {
+        const logFlag = argv.indexOf("--log-file");
+        if (logFlag !== -1) {
+            const logPath = argv[logFlag + 1];
+            if (!logPath || logPath.startsWith("-")) {
+                stderr.write("verax serve --log-file <file>\n");
+                return 78;
+            }
+            const attached = attachBodyLog(logPath);
+            if (!attached.ok) {
+                stderr.write(`${attached.reason}\n`);
+                return 78;
+            }
+            stderr.write("verax serve starting\n");
+        }
+        const fileFlag = argv.indexOf("--env-file");
+        if (fileFlag !== -1) {
+            const file = argv[fileFlag + 1];
+            if (!file || file.startsWith("-")) {
+                stderr.write("verax serve --env-file <file>\n");
+                return 78;
+            }
+            clearVeraxEnv(process.env);
+            const loaded = loadEnvFile(file);
+            if (!loaded.ok) {
+                stderr.write(`${loaded.reason}\n`);
+                return 78;
+            }
+            const missingJwks = envFileJwksMissing(process.env);
+            if (missingJwks) {
+                stderr.write(`${missingJwks}\n`);
+                return 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 target = doctorStateTarget(env);
+        if (target && directoryAccess(target) === "unreadable") {
+            stderr.write(`${unreadableSentence(target, "doctor")}\n`);
+            return 77;
+        }
+        const nodeLabel = process.platform === "linux" ? linuxNodeLabelCheck() : null;
+        const checks = [
+            ...runDoctor(env, process.argv),
+            ...liveInstalledChecks(),
+            ...(process.platform === "linux" ? [linuxSelinuxCheck()] : []),
+            ...(nodeLabel ? [nodeLabel] : []),
+        ];
+        const bodyLog = target ? doctorBodyLog(target) : "";
+        if (json) {
+            stdout.write(`${JSON.stringify(target ? { checks, bodyLog } : { checks })}\n`);
+        }
+        else {
+            for (const c of checks) {
+                stdout.write(`${c.level}\t${c.id}\t${c.detail}\n`);
+            }
+            if (bodyLog !== "")
+                stdout.write(bodyLog);
+        }
+        return doctorExit(checks);
+    }
+    if (argv[0] === "reconcile") {
+        return runReconcile(argv, (s) => stderr.write(s));
+    }
+    if (argv[0] === "verify") {
+        return runVerify(argv.slice(1), (s) => stdout.write(`${s}\n`));
+    }
+    if (argv[0] === "desktop") {
+        stderr.write("desktop-not-in-0.4.0: the desktop panel ships in 0.4.1\n");
+        return 64;
+    }
+    if (argv[0] === "witness") {
+        const stateDir = argv[1];
+        if (!stateDir) {
+            stderr.write("verax witness <stateDir>\n");
+            return 78;
         }
+        await runWitness(stateDir);
+        return 0;
+    }
+    const head = argv[0];
+    if (head !== undefined && !head.startsWith("--")) {
+        stderr.write(`unknown command: ${head}\n`);
+        stderr.write(HELP);
+        return 64;
+    }
+    // `main()` reads `--inventory`. Any other leading flag is not a serve option.
+    if (head !== undefined && head.startsWith("--") && head !== "--inventory") {
+        stderr.write(`unknown option: ${head}\n`);
+        stderr.write(HELP);
+        return 64;
     }
     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.
+    // process up, the same way as `serve`.
     await new Promise(() => { });
+    return 0;
 }
-if (argv[0] === "doctor") {
-    const json = argv.includes("--json");
-    const checks = runDoctor(process.env, process.argv);
-    if (json) {
-        process.stdout.write(`${JSON.stringify({ checks })}\n`);
-    }
-    else {
-        for (const c of checks) {
-            process.stdout.write(`${c.level}\t${c.id}\t${c.detail}\n`);
-        }
-    }
-    process.exit(doctorExit(checks));
-}
-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));
-}
-if (argv[0] === "witness") {
-    const stateDir = argv[1];
-    if (!stateDir) {
-        process.stderr.write("verax witness <stateDir>\n");
-        process.exit(78);
-    }
-    await runWitness(stateDir);
-    process.exit(0);
+if (isCliEntry()) {
+    process.exit(await runCli(process.argv.slice(2)));
 }
-await main();

package/dist/config.d.ts

@@ -13,6 +13,14 @@ export type BodyConfig = {
      * Loopback binds only.
      */
     jwksFile?: string | null;
+    /**
+     * JWKS captured once at desktop start. Verification uses this set and does
+     * not refetch `jwksUrl`. Null when the body should use the remote set.
+     * Not a substitute for `jwksFile` (that mode refuses operator scopes).
+     */
+    jwksPin?: {
+        keys: Record<string, unknown>[];
+    } | null;
     /** Path to an inventory JSON file. Missing file is absence, not a fault. */
     inventoryFile?: string | null;
     /**
@@ -22,7 +30,25 @@ export type BodyConfig = {
      * no downstream; a named file that cannot be attached stops the body.
      */
     downstreamFile?: string | null;
+    /** Origins allowed to call this HTTP server. Empty means no browser origin. */
+    allowedOrigins?: readonly string[];
+    /**
+     * Bytes one tenant may keep under `memory/`, summed across stored versions.
+     * Default is 1 MiB. `VERAX_MEMORY_QUOTA_BYTES` overrides it.
+     */
+    memoryQuotaBytes?: number;
+    /**
+     * Bytes one tenant may append to `outbox.jsonl`.
+     * Default is 1 MiB. `VERAX_MESSAGE_QUOTA_BYTES` overrides it.
+     */
+    messageQuotaBytes?: number;
 };
+/** Per-tenant `memory.put` cap. The HTTP body cap does not reset this total. */
+export declare const DEFAULT_MEMORY_QUOTA_BYTES: number;
+/** Per-tenant `message.send` cap. The HTTP body cap does not reset this total. */
+export declare const DEFAULT_MESSAGE_QUOTA_BYTES: number;
+export declare function memoryQuotaBytes(env?: NodeJS.ProcessEnv): number;
+export declare function messageQuotaBytes(env?: NodeJS.ProcessEnv): number;
 export type ConfigResult = {
     ok: true;
     value: BodyConfig;

package/dist/config.js

@@ -1,5 +1,24 @@
 import { readFileSync } from "node:fs";
 export const EX_CONFIG = 78;
+/** Per-tenant `memory.put` cap. The HTTP body cap does not reset this total. */
+export const DEFAULT_MEMORY_QUOTA_BYTES = 1024 * 1024;
+/** Per-tenant `message.send` cap. The HTTP body cap does not reset this total. */
+export const DEFAULT_MESSAGE_QUOTA_BYTES = 1024 * 1024;
+function positiveIntQuota(raw, fallback) {
+    const text = raw?.trim() ?? "";
+    if (text === "")
+        return fallback;
+    const n = Number(text);
+    if (!Number.isInteger(n) || n <= 0)
+        return fallback;
+    return n;
+}
+export function memoryQuotaBytes(env = process.env) {
+    return positiveIntQuota(env.VERAX_MEMORY_QUOTA_BYTES, DEFAULT_MEMORY_QUOTA_BYTES);
+}
+export function messageQuotaBytes(env = process.env) {
+    return positiveIntQuota(env.VERAX_MESSAGE_QUOTA_BYTES, DEFAULT_MESSAGE_QUOTA_BYTES);
+}
 const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
 function parseBind(raw) {
     const text = raw && raw.trim() !== "" ? raw.trim() : "127.0.0.1:8787";
@@ -15,6 +34,19 @@ export function isLoopbackHost(host) {
     const stripped = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
     return LOOPBACK.has(stripped);
 }
+function jwksPinParses(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.keys) || parsed.keys.length === 0)
+            return null;
+        if (!parsed.keys.every((key) => key !== null && typeof key === "object" && !Array.isArray(key)))
+            return null;
+        return { keys: parsed.keys };
+    }
+    catch {
+        return null;
+    }
+}
 function jwksFileParses(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -28,7 +60,15 @@ 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 jwksPinRaw = env.VERAX_JWKS_PIN?.trim() ?? "";
     const audience = env.VERAX_AUDIENCE?.trim() ?? "";
+    let jwksPin = null;
+    if (jwksPinRaw !== "") {
+        jwksPin = jwksPinParses(jwksPinRaw);
+        if (!jwksPin) {
+            return { ok: false, code: EX_CONFIG, reason: "VERAX_JWKS_PIN is unparsable" };
+        }
+    }
     if (jwksUrl !== "" && jwksFile !== "") {
         return {
             ok: false,
@@ -82,6 +122,7 @@ export function loadConfig(env) {
             issuer,
             jwksUrl,
             jwksFile: jwksFile === "" ? null : jwksFile,
+            jwksPin,
             audience,
             stateDir,
             bindHost: bind.host,
@@ -90,6 +131,12 @@ export function loadConfig(env) {
             tlsTerminated,
             inventoryFile: inventoryRaw === "" ? null : inventoryRaw,
             downstreamFile: downstreamRaw === "" ? null : downstreamRaw,
+            allowedOrigins: (env.VERAX_ALLOWED_ORIGINS ?? "")
+                .split(",")
+                .map((item) => item.trim())
+                .filter((item) => item !== ""),
+            memoryQuotaBytes: memoryQuotaBytes(env),
+            messageQuotaBytes: messageQuotaBytes(env),
         },
     };
 }

package/dist/demo.d.ts

@@ -14,5 +14,7 @@ export type DemoOpts = {
         command: string;
         args: string[];
     };
+    /** mkdtemp prefix. Tests pass a unique one so parallel files do not share verax-demo-. */
+    statePrefix?: string;
 };
 export declare function runDemo(argv: string[], env: NodeJS.ProcessEnv, io: DemoIo, opts?: DemoOpts): Promise<number>;

package/dist/demo.js

@@ -229,6 +229,8 @@ async function readAnswer(stdin) {
             resolve(value);
         };
         const onData = (chunk) => {
+            if (typeof stdin.pause === "function")
+                stdin.pause();
             done(String(chunk).split(/\r?\n/)[0] ?? "");
         };
         const onEnd = () => done("");
@@ -289,7 +291,8 @@ export async function runDemo(argv, env, io, opts) {
     process.once("SIGINT", onStop);
     process.once("SIGTERM", onStop);
     try {
-        stateDir = mkdtempSync(join(tmpdir(), "verax-demo-"));
+        const statePrefix = opts?.statePrefix && opts.statePrefix.length > 0 ? opts.statePrefix : "verax-demo-";
+        stateDir = mkdtempSync(join(tmpdir(), statePrefix));
         const policyFile = writeDemoPolicy(stateDir, withConarium);
         const { privateKey, publicKey } = await generateKeyPair("ES256");
         const jwk = { ...(await exportJWK(publicKey)), alg: "ES256", use: "sig", kid: KID };
@@ -369,7 +372,10 @@ export async function runDemo(argv, env, io, opts) {
             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);
+                const code = await runApprove(["approve", stateDir, held.ref], writeErr, () => undefined, {
+                    isTTY: io.isTTY,
+                    ask: async () => readAnswer(io.stdin),
+                }, { elevated: () => false });
                 if (code !== 0)
                     throw new Error("demo: approve failed");
                 approved = true;

package/dist/desktop-parent.d.ts

@@ -0,0 +1,19 @@
+/** Env the desktop launcher sets on the issuer and the body. Absent outside that launch. */
+export declare const DESKTOP_PARENT_PID = "VERAX_DESKTOP_PARENT_PID";
+export type DesktopParentWatch = {
+    env?: NodeJS.ProcessEnv;
+    /** True when `pid` is still a process. Default is `process.kill(pid, 0)`. */
+    pidAlive?: (pid: number) => boolean;
+    exit?: (code: number) => void;
+    schedule?: (fn: () => void, ms: number) => {
+        unref?: () => void;
+    };
+};
+/** `process.kill(pid, 0)` — EPERM means the process exists. */
+export declare function desktopParentAlive(pid: number): boolean;
+/**
+ * When `VERAX_DESKTOP_PARENT_PID` is set, exit once that pid is gone.
+ * Polls every 2s. No-op when the variable is unset, so a normal body or issuer
+ * start does not watch anything.
+ */
+export declare function watchDesktopParent(hooks?: DesktopParentWatch): void;

package/dist/desktop-parent.js

@@ -0,0 +1,44 @@
+/** Env the desktop launcher sets on the issuer and the body. Absent outside that launch. */
+export const DESKTOP_PARENT_PID = "VERAX_DESKTOP_PARENT_PID";
+/** `process.kill(pid, 0)` — EPERM means the process exists. */
+export function desktopParentAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * When `VERAX_DESKTOP_PARENT_PID` is set, exit once that pid is gone.
+ * Polls every 2s. No-op when the variable is unset, so a normal body or issuer
+ * start does not watch anything.
+ */
+export function watchDesktopParent(hooks = {}) {
+    const env = hooks.env ?? process.env;
+    const raw = env[DESKTOP_PARENT_PID]?.trim() ?? "";
+    if (raw === "")
+        return;
+    const exit = hooks.exit ?? ((code) => process.exit(code));
+    const pid = Number(raw);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        exit(1);
+        return;
+    }
+    const alive = hooks.pidAlive ?? desktopParentAlive;
+    if (!alive(pid)) {
+        exit(1);
+        return;
+    }
+    const schedule = hooks.schedule ??
+        ((fn, ms) => {
+            const timer = setInterval(fn, ms);
+            timer.unref();
+            return timer;
+        });
+    schedule(() => {
+        if (!alive(pid))
+            exit(1);
+    }, 2_000);
+}