@verax-ai/body 0.1.0

package/dist/approve-cli.d.ts

@@ -0,0 +1,12 @@
+export declare function resolveApproveRef(pending: {
+    ref: string;
+    status?: string;
+}[], given: string): {
+    ok: true;
+    ref: string;
+} | {
+    ok: false;
+    reason: "unknown-ref" | "ambiguous-ref";
+    candidates: string[];
+};
+export declare function runApprove(argv: string[], writeErr?: (s: string) => void, writeOut?: (s: string) => void): Promise<number>;

package/dist/approve-cli.js

@@ -0,0 +1,93 @@
+import { userInfo } from "node:os";
+import { approvePending, approvalsLogFor, enqueueApprovalCommand, FileLedger, loadApprovalsFromDir } from "@verax-ai/proxy";
+import { loadOrCreateSigners } from "./keys.js";
+function operatorName() {
+    try {
+        const name = userInfo().username;
+        return name.length > 0 ? name : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function resolveApproveRef(pending, given) {
+    const open = pending.filter((r) => r.status === "pending" || r.status === undefined);
+    const exact = open.find((r) => r.ref === given);
+    if (exact)
+        return { ok: true, ref: exact.ref };
+    const suffix = `:${given}`;
+    const hits = open.filter((r) => r.ref.endsWith(suffix)).map((r) => r.ref);
+    const unique = [...new Set(hits)].sort();
+    if (unique.length === 1)
+        return { ok: true, ref: unique[0] };
+    if (unique.length > 1)
+        return { ok: false, reason: "ambiguous-ref", candidates: unique };
+    return { ok: false, reason: "unknown-ref", candidates: [] };
+}
+export async function runApprove(argv, writeErr = (s) => process.stderr.write(s), writeOut = (s) => process.stdout.write(s)) {
+    const rest = argv.slice(1);
+    const stateDir = rest[0];
+    const given = rest[1];
+    if (!stateDir || !given || rest.length !== 2) {
+        writeErr("verax approve <stateDir> <ref>\n");
+        return 78;
+    }
+    const resolved = resolveApproveRef(loadApprovalsFromDir(stateDir), given);
+    if (!resolved.ok) {
+        if (resolved.reason === "ambiguous-ref") {
+            writeErr(`ambiguous-ref\n${resolved.candidates.join("\n")}\n`);
+            return 78;
+        }
+        writeErr("approve-unknown-ref\n");
+        return 78;
+    }
+    const ref = resolved.ref;
+    let ledger;
+    try {
+        ledger = new FileLedger(stateDir);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : "";
+        if (msg.startsWith("ledger-locked")) {
+            enqueueApprovalCommand(stateDir, { ref, approverId: operatorName(), atMs: Date.now() });
+            writeOut("approve-queued\n");
+            return 0;
+        }
+        writeErr(`approve-failed:${msg.split("\n")[0] ?? "unknown"}\n`);
+        return 1;
+    }
+    try {
+        const signers = loadOrCreateSigners(stateDir);
+        const approvals = approvalsLogFor(ledger);
+        const decisions = await ledger.decisions();
+        const defer = decisions.find((d) => d.claims.ref === ref && d.claims.decision === "defer");
+        if (!defer) {
+            writeErr("approve-unknown-ref\n");
+            return 78;
+        }
+        const result = await approvePending({
+            ledger,
+            recordSigner: signers.recordSigner,
+            now: () => Date.now(),
+            nonce: () => crypto.randomUUID(),
+            ref,
+            approverId: operatorName(),
+            via: "cli",
+            policyHash: defer.claims.policyHash,
+            approvals,
+        });
+        if (!result.ok) {
+            writeErr(`approve-${result.reason}\n`);
+            return result.reason === "expired" ? 2 : 1;
+        }
+        writeOut(`approved:${result.allowRef}\n`);
+        return 0;
+    }
+    catch (err) {
+        writeErr(`approve-failed:${err instanceof Error ? err.message : "unknown"}\n`);
+        return 1;
+    }
+    finally {
+        ledger.close();
+    }
+}

package/dist/atomic-write.d.ts

@@ -0,0 +1 @@
+export declare function writeFileAtomic(path: string, text: string): void;

package/dist/atomic-write.js

@@ -0,0 +1,65 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Replace a file's contents in one step, so a reader sees the old bytes or the
+ * new ones and never a half-written file.
+ *
+ * Writing in place is not that: measured on 11 Sep 2026, a reader polling this
+ * path every 20 ms while the file was rewritten 60 times got 12 unparseable
+ * reads. The listen file is read by another process - that is its whole job -
+ * and a torn read becomes `null`, which the caller cannot tell from "nothing
+ * is running".
+ *
+ * The rename needs the retry. On Windows it fails with EPERM while a reader
+ * holds the destination open, and in the same measurement 26 of 60 plain
+ * renames failed that way. Retrying briefly lost none of them and still let no
+ * torn read through.
+ *
+ * The temporary name carries this process and a random suffix. A fixed `.tmp`
+ * next to the destination is what two writers, or a crashed writer, collide
+ * on.
+ */
+const napper = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Sleep without spinning. The first version of the retry below burned the
+ * processor between attempts, which is the worst thing to do while waiting for
+ * another process to let go of a file: under the unit suite's own load the
+ * spin starved the reader it was waiting on, the retries ran out in 200 ms,
+ * and the write threw EPERM. Atomics.wait yields the core instead.
+ */
+function napSync(ms) {
+    Atomics.wait(napper, 0, 0, ms);
+}
+export function writeFileAtomic(path, text) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    writeFileSync(tmp, text, { encoding: "utf8", mode: 0o600 });
+    try {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                renameSync(tmp, path);
+                chmodSync(path, 0o600);
+                return;
+            }
+            catch (err) {
+                const code = err.code;
+                // Two seconds of patience. A reader holds this file for microseconds
+                // when the machine is idle; the budget is for the machine that is not.
+                if (attempt >= 100 || (code !== "EPERM" && code !== "EACCES" && code !== "EBUSY")) {
+                    throw err;
+                }
+                napSync(20);
+            }
+        }
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // rename may already have moved it
+        }
+        throw err;
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,10 @@
+import { type JWTPayload } from "jose";
+import type { Principal } from "@verax-ai/proxy";
+export type VerifiedBearer = {
+    principal: Principal;
+    payload: JWTPayload;
+};
+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 function readBearer(header: string | undefined): string | null;

package/dist/auth.js

@@ -0,0 +1,59 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+const ALGS = ["ES256", "EdDSA"];
+export function resourceMetadataUrl(audience) {
+    const u = new URL(audience);
+    const path = u.pathname.replace(/\/+$/, "").replace(/^\/+/, "");
+    if (path === "") {
+        return `${u.origin}/.well-known/oauth-protected-resource`;
+    }
+    return `${u.origin}/.well-known/oauth-protected-resource/${path}`;
+}
+export function wwwAuthenticate(audience) {
+    return `Bearer resource_metadata="${resourceMetadataUrl(audience)}"`;
+}
+export function createVerifier(jwksUrl, issuer, audience) {
+    const jwks = createRemoteJWKSet(new URL(jwksUrl));
+    return async (token) => {
+        const { payload } = await jwtVerify(token, jwks, {
+            issuer,
+            audience,
+            algorithms: [...ALGS],
+            requiredClaims: ["exp", "iat", "sub"],
+            clockTolerance: 60,
+        });
+        const nowSec = Math.floor(Date.now() / 1000);
+        if (typeof payload.iat === "number" && payload.iat > nowSec + 60) {
+            throw new Error("iat-in-future");
+        }
+        const sub = typeof payload.sub === "string" ? payload.sub : "";
+        if (sub === "") {
+            throw new Error("missing-sub");
+        }
+        const scopes = new Set();
+        if (typeof payload.scope === "string") {
+            for (const part of payload.scope.split(/\s+/)) {
+                if (part !== "")
+                    scopes.add(part);
+            }
+        }
+        const iss = typeof payload.iss === "string" ? payload.iss : undefined;
+        const tenant = typeof payload.tenant === "string" && payload.tenant !== "" ? payload.tenant : undefined;
+        const org = typeof payload.org === "string" && payload.org !== "" ? payload.org : undefined;
+        return {
+            principal: {
+                brain: sub,
+                scopes,
+                ...(iss ? { iss } : {}),
+                ...(tenant ? { tenant } : {}),
+                ...(org ? { org } : {}),
+            },
+            payload,
+        };
+    };
+}
+export function readBearer(header) {
+    if (!header)
+        return null;
+    const match = /^Bearer\s+(\S+)/i.exec(header);
+    return match ? match[1] : null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runApprove } from "./approve-cli.js";
+import { desktopMain } from "./desktop.js";
+import { doctorExit, runDoctor } from "./doctor.js";
+import { runHalt } from "./halt.js";
+import { main } from "./main.js";
+import { runOperator } from "./operator-cli.js";
+import { runReconcile } from "./reconcile-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.
+
+Usage: verax <command> [options]
+
+  (no command)         serve the body over MCP stdio, or HTTP when VERAX_PORT is set
+  doctor [--json]      check the configuration this process would run with
+  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
+  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
+
+  --help, -h           print this
+  --version, -v        print the version
+
+Serving needs VERAX_ISSUER, VERAX_JWKS_URL and VERAX_AUDIENCE; \`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.
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const path of [join(here, "..", "package.json"), join(here, "..", "..", "package.json")]) {
+        try {
+            const raw = JSON.parse(readFileSync(path, "utf8"));
+            if (raw.name === "@verax-ai/body" && typeof raw.version === "string")
+                return raw.version;
+        }
+        catch {
+            // try the next candidate: the file layout differs between src and dist.
+        }
+    }
+    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] === "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);
+    }
+    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] === "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] === "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);
+}
+await main();

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+export declare const EX_CONFIG = 78;
+export type BodyConfig = {
+    issuer: string;
+    jwksUrl: string;
+    audience: string;
+    stateDir: string;
+    bindHost: string;
+    bindPort: number;
+    policyFile: string;
+    tlsTerminated: boolean;
+    /** Path to an inventory JSON file. Missing file is absence, not a fault. */
+    inventoryFile?: string | null;
+};
+export type ConfigResult = {
+    ok: true;
+    value: BodyConfig;
+} | {
+    ok: false;
+    reason: string;
+    code: typeof EX_CONFIG;
+};
+export declare function isLoopbackHost(host: string): boolean;
+export declare function loadConfig(env: NodeJS.ProcessEnv): ConfigResult;
+/** `--inventory <file>` wins over VERAX_INVENTORY_FILE. */
+export declare function overlayInventoryArg(env: NodeJS.ProcessEnv, argv: readonly string[]): NodeJS.ProcessEnv | {
+    error: string;
+};

package/dist/config.js

@@ -0,0 +1,71 @@
+export const EX_CONFIG = 78;
+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";
+    const idx = text.lastIndexOf(":");
+    if (idx <= 0) {
+        return { host: text, port: 8787 };
+    }
+    const host = text.slice(0, idx);
+    const port = Number(text.slice(idx + 1));
+    return { host, port: Number.isInteger(port) ? port : 8787 };
+}
+export function isLoopbackHost(host) {
+    const stripped = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    return LOOPBACK.has(stripped);
+}
+export function loadConfig(env) {
+    const issuer = env.VERAX_ISSUER?.trim() ?? "";
+    const jwksUrl = env.VERAX_JWKS_URL?.trim() ?? "";
+    const audience = env.VERAX_AUDIENCE?.trim() ?? "";
+    if (issuer === "" || jwksUrl === "" || audience === "") {
+        return {
+            ok: false,
+            code: EX_CONFIG,
+            reason: "missing VERAX_ISSUER, VERAX_JWKS_URL, or VERAX_AUDIENCE",
+        };
+    }
+    const bind = parseBind(env.VERAX_BIND);
+    const tlsTerminated = env.VERAX_TLS_TERMINATED === "1";
+    if (!isLoopbackHost(bind.host) && !tlsTerminated) {
+        return {
+            ok: false,
+            code: EX_CONFIG,
+            reason: "non-loopback bind without VERAX_TLS_TERMINATED=1",
+        };
+    }
+    const stateDir = env.VERAX_STATE_DIR?.trim() ?? "";
+    if (stateDir === "") {
+        return { ok: false, code: EX_CONFIG, reason: "missing VERAX_STATE_DIR" };
+    }
+    const policyFile = env.VERAX_POLICY_FILE?.trim() ?? "";
+    if (policyFile === "") {
+        return { ok: false, code: EX_CONFIG, reason: "missing VERAX_POLICY_FILE" };
+    }
+    const inventoryRaw = env.VERAX_INVENTORY_FILE?.trim() ?? "";
+    return {
+        ok: true,
+        value: {
+            issuer,
+            jwksUrl,
+            audience,
+            stateDir,
+            bindHost: bind.host,
+            bindPort: bind.port,
+            policyFile,
+            tlsTerminated,
+            inventoryFile: inventoryRaw === "" ? null : inventoryRaw,
+        },
+    };
+}
+/** `--inventory <file>` wins over VERAX_INVENTORY_FILE. */
+export function overlayInventoryArg(env, argv) {
+    const i = argv.indexOf("--inventory");
+    if (i === -1)
+        return env;
+    const path = argv[i + 1];
+    if (!path || path.startsWith("-")) {
+        return { error: "missing --inventory path" };
+    }
+    return { ...env, VERAX_INVENTORY_FILE: path };
+}

package/dist/desktop.d.ts

@@ -0,0 +1,29 @@
+export type DesktopOpts = {
+    stateDir: string;
+    panelPort: number;
+    issuerPort: number;
+    bodyPort: number;
+    browser?: string;
+    inventoryFile?: string;
+};
+/**
+ * True when the panel has no build, or when a watched source is newer than the
+ * one it has. The launcher used to skip the build whenever `dist/index.html`
+ * existed, so a session served whatever had been built once: editing the panel
+ * and reopening it showed the previous app, with no sign that it was stale.
+ */
+export declare function panelBuildNeeded(distIndex: string, sourceRoots: readonly string[]): boolean;
+export declare function parseDesktopArgs(argv: string[]): DesktopOpts | {
+    error: string;
+};
+export declare function portOpen(port: number, host?: string): Promise<boolean>;
+export declare function killTree(pid: number | undefined): void;
+/** The panel's redirect is its own origin, so the issuer has to be told which port
+ *  this run put it on: the allow-list default only holds 5173 and 4173. */
+export declare function issuerEnv(base: NodeJS.ProcessEnv, opts: {
+    stateDir: string;
+    issuerPort: number;
+    panelPort: number;
+}, audience: string, issuerUrl: string): NodeJS.ProcessEnv;
+export declare function runDesktop(opts: DesktopOpts, writeErr?: (s: string) => void): Promise<number>;
+export declare function desktopMain(argv: string[]): Promise<number>;