@verax-ai/body 0.3.0 → 0.4.0

package/dist/doctor.d.ts

@@ -5,4 +5,6 @@ export type DoctorCheck = {
     detail: string;
 };
 export declare function runDoctor(env: NodeJS.ProcessEnv, argv: readonly string[]): DoctorCheck[];
+/** Last 20 lines of `<stateDir>/body.log`, or a missing-file sentence. */
+export declare function doctorBodyLog(stateDir: string): string;
 export declare function doctorExit(checks: readonly DoctorCheck[]): number;

package/dist/doctor.js

@@ -1,5 +1,8 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
+import { readWindowsMachineRoots, SystemToolError, windowsAgentTokenPath } from "./install.js";
+import { readLogTail } from "./body-log.js";
 import { indexCoverage, listPieceFiles } from "@verax-ai/proxy";
 import { loadConfig, isLoopbackHost } from "./config.js";
 import { parseDownstreamDocument } from "./downstream.js";
@@ -172,24 +175,32 @@ export function runDoctor(env, argv) {
     }
     const tokenScope = scopeFromDevToken(env.VERAX_DEV_TOKEN);
     const mintScope = env.VERAX_DEV_SCOPE?.trim() ?? "";
-    const seenScope = tokenScope ?? (mintScope !== "" ? mintScope : null);
-    if (seenScope !== null) {
-        const parts = seenScope.split(/\s+/).filter((s) => s !== "");
+    // VERAX_DEV_SCOPE cannot put verax:audit on the agent file or on a session
+    // that has not passed a passkey. The panel reads the ledger with that session.
+    if (tokenScope !== null) {
+        const parts = tokenScope.split(/\s+/).filter((s) => s !== "");
         if (parts.includes("verax:audit")) {
             checks.push({
                 id: "dev-token-audit",
-                level: "ok",
-                detail: "development token scope includes verax:audit",
+                level: "warn",
+                detail: "development token carries verax:audit; that scope belongs on the passkey session, not the agent token. The panel reads /api/ledger only after a passkey sign-in",
             });
         }
         else {
             checks.push({
                 id: "dev-token-audit",
-                level: "warn",
-                detail: "development token scope lacks verax:audit; the panel cannot read /api/ledger or /healthz counts",
+                level: "ok",
+                detail: "development token does not carry verax:audit",
             });
         }
     }
+    else if (mintScope !== "") {
+        checks.push({
+            id: "dev-token-audit",
+            level: "ok",
+            detail: "VERAX_DEV_SCOPE does not mint verax:audit onto the agent token or a session without a passkey; the panel reads /api/ledger with the passkey session",
+        });
+    }
     const downstreamPath = env.VERAX_DOWNSTREAM?.trim() ?? "";
     if (downstreamPath !== "") {
         try {
@@ -245,8 +256,9 @@ function jwksFileChecks(env, stateDir) {
     });
     if (stateDir === "")
         return out;
-    const tokenPath = join(stateDir, "local-issuer", "agent.token");
-    if (!existsSync(tokenPath))
+    const candidates = [agentTokenOnDisk(env), join(stateDir, "local-issuer", "agent.token")].filter((file) => file !== null);
+    const tokenPath = candidates.find((file) => existsSync(file));
+    if (!tokenPath)
         return out;
     const exp = expFromToken(readFileSync(tokenPath, "utf8"));
     const weekSec = 7 * 24 * 60 * 60;
@@ -259,6 +271,26 @@ function jwksFileChecks(env, stateDir) {
     }
     return out;
 }
+/** Install token: ProgramData on Windows, `~/.verax/agent.token` on Linux and macOS. */
+function agentTokenOnDisk(env) {
+    if (process.platform === "win32") {
+        const sid = env.VERAX_USER_SID?.trim().replace(/^\*/, "") ?? "";
+        if (!/^S-1-[0-9-]+$/i.test(sid))
+            return null;
+        try {
+            return windowsAgentTokenPath(env, sid, readWindowsMachineRoots());
+        }
+        catch (err) {
+            if (err instanceof SystemToolError)
+                return null;
+            throw err;
+        }
+    }
+    const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
+    if (home === "")
+        return null;
+    return join(home, ".verax", "agent.token");
+}
 function expFromToken(raw) {
     const parts = raw.trim().split(".");
     if (parts.length < 2)
@@ -318,6 +350,14 @@ function scopeFromDevToken(raw) {
         return null;
     }
 }
+/** Last 20 lines of `<stateDir>/body.log`, or a missing-file sentence. */
+export function doctorBodyLog(stateDir) {
+    const file = join(stateDir, "body.log");
+    const tail = readLogTail(file, 20);
+    if (tail === null)
+        return `body.log missing: ${file}\n`;
+    return tail;
+}
 export function doctorExit(checks) {
     return checks.some((c) => c.level === "fail") ? 1 : 0;
 }
@@ -348,6 +388,8 @@ function heartbeatMaxMs(env) {
     const n = Number(env.VERAX_HEARTBEAT_MAX_MS ?? "30000");
     return Number.isFinite(n) && n > 0 ? n : 30_000;
 }
+/** A pulse this far ahead of the clock is still treated as now. */
+const HEARTBEAT_FUTURE_SKEW_MS = 60_000;
 function evidenceChecks(stateDir, env) {
     const checks = [];
     let pieces;
@@ -360,7 +402,24 @@ function evidenceChecks(stateDir, env) {
     }
     const srcLines = pieces.reduce((s, p) => s + countJsonl(p.decisions).lines, 0);
     const decisionN = pieces.reduce((s, p) => s + (p.closed ? p.n : countJsonl(p.decisions).lines), 0);
-    if (decisionN > 0) {
+    let closedOff = null;
+    for (const piece of pieces) {
+        if (!piece.closed)
+            continue;
+        const lines = countJsonl(piece.decisions).lines;
+        if (lines !== piece.n) {
+            closedOff = { id: piece.id, lines, n: piece.n };
+            break;
+        }
+    }
+    if (closedOff) {
+        checks.push({
+            id: "ledger-index",
+            level: "fail",
+            detail: `piece ${closedOff.id} has ${closedOff.lines} decision line(s), the manifest says ${closedOff.n}`,
+        });
+    }
+    else if (decisionN > 0) {
         const known = new Set(pieces.map((p) => p.id));
         const cov = indexCoverage(stateDir);
         if (cov === null) {
@@ -413,6 +472,13 @@ function evidenceChecks(stateDir, env) {
                 detail: "ledger has rows but no readable heartbeat; the evidence service looks silent",
             });
         }
+        else if (!Number.isFinite(hb.atMs) || hb.atMs > Date.now() + HEARTBEAT_FUTURE_SKEW_MS) {
+            checks.push({
+                id: "heartbeat",
+                level: "fail",
+                detail: "heartbeat time is in the future",
+            });
+        }
         else if (Date.now() - hb.atMs > heartbeatMaxMs(env)) {
             checks.push({
                 id: "heartbeat",
@@ -445,6 +511,8 @@ function evidenceChecks(stateDir, env) {
             srcEffects.lines > 0 ||
             copy.lines > 0 ||
             copyEffects.lines > 0 ||
+            src.corrupt ||
+            srcEffects.corrupt ||
             copy.corrupt ||
             copyEffects.corrupt;
         if (!pieceAnything)
@@ -452,7 +520,15 @@ function evidenceChecks(stateDir, env) {
         anything = true;
         if (fail)
             continue;
-        if (copy.corrupt || copyEffects.corrupt) {
+        if (src.corrupt || srcEffects.corrupt) {
+            const file = src.corrupt ? "decisions.jsonl" : "effects.jsonl";
+            fail = {
+                id: "evidence-copy",
+                level: "fail",
+                detail: `source ${file} on piece ${piece.id} is corrupt`,
+            };
+        }
+        else if (copy.corrupt || copyEffects.corrupt) {
             fail = {
                 id: "evidence-copy",
                 level: "fail",
@@ -473,6 +549,13 @@ function evidenceChecks(stateDir, env) {
                 detail: `evidence copy is stale on piece ${piece.id} effects: ${copyEffects.lines} effect line(s) behind source ${srcEffects.lines}`,
             };
         }
+        else if (copy.lines > src.lines || copyEffects.lines > srcEffects.lines) {
+            fail = {
+                id: "evidence-copy",
+                level: "fail",
+                detail: `source is shorter than its evidence copy on piece ${piece.id}`,
+            };
+        }
     }
     if (anything) {
         checks.push(fail ?? {

package/dist/health-extras.d.ts

@@ -1,3 +1,7 @@
+/** Written by `verax install` before the service starts. `/healthz` echoes it. */
+export declare const INSTALL_HEALTH_NONCE = "install-health-nonce";
+/** Hex nonce from this install, or null when the file is absent or not that shape. */
+export declare function readInstallHealthNonce(stateDir: string): string | null;
 export type HealthHeartbeat = {
     atMs: number;
     lastDecisionN: number;

package/dist/health-extras.js

@@ -1,5 +1,19 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+/** Written by `verax install` before the service starts. `/healthz` echoes it. */
+export const INSTALL_HEALTH_NONCE = "install-health-nonce";
+/** Hex nonce from this install, or null when the file is absent or not that shape. */
+export function readInstallHealthNonce(stateDir) {
+    try {
+        const text = readFileSync(join(stateDir, INSTALL_HEALTH_NONCE), "utf8").trim();
+        if (!/^[0-9a-f]{64}$/i.test(text))
+            return null;
+        return text.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
 export function readHeartbeat(stateDir) {
     const path = join(stateDir, "heartbeat.json");
     if (!existsSync(path))

package/dist/init-local.d.ts

@@ -12,4 +12,28 @@ export declare function loadEnvFile(path: string, env?: NodeJS.ProcessEnv): {
     ok: false;
     reason: string;
 };
-export declare function runInitLocal(argv: readonly string[], io?: InitIo): Promise<number>;
+/**
+ * Drop every `VERAX_*` name before an env file is applied. Comparison is
+ * case-insensitive because Windows environment names are.
+ */
+export declare function clearVeraxEnv(env: NodeJS.ProcessEnv): void;
+/** `serve --env-file` refuses a file that names neither JWKS source. */
+export declare function envFileJwksMissing(env: NodeJS.ProcessEnv): string | null;
+export type InitLocalOpts = {
+    /** Write the agent token here and leave no copy under the state directory. */
+    tokenPath?: string;
+    /** Installed body prints its own summary. Skip this command's user-facing text. */
+    quiet?: boolean;
+    /**
+     * Install mode. State files inherit the state directory ACL (svc, Administrators, SYSTEM).
+     * Do not grant the invoking user and do not call `restrictToOwnerWin32`.
+     * Elevated install does not pass a token path under the invoking user's home.
+     * `tokenPath` remains for a non-elevated `verax init --local`.
+     */
+    noOwnerGrant?: boolean;
+    /** Install mode. Defaults to process.env. SUDO_USER names the POSIX owner. */
+    env?: NodeJS.ProcessEnv;
+    /** Test hook. A throw here runs the rollback after the issuer directory exists and before any file is written. */
+    beforeWrite?: () => void;
+};
+export declare function runInitLocal(argv: readonly string[], io?: InitIo, opts?: InitLocalOpts): Promise<number>;

package/dist/init-local.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { beginWinOwnerRun, endWinOwnerRun, ensureTokenParent, mkdirLeaf, restrictToOwnerWin32, SystemToolError } from "./install.js";
 import { calculateJwkThumbprint, exportJWK, exportPKCS8, generateKeyPair, importPKCS8, SignJWT, } from "jose";
 import { EX_CONFIG } from "./config.js";
 const ISSUER = "verax-local";
@@ -20,25 +21,50 @@ export function loadEnvFile(path, env = process.env) {
     catch {
         return { ok: false, reason: "env file is missing or unreadable" };
     }
+    const parsed = [];
     for (const line of text.split(/\r?\n/)) {
-        const trimmed = line.trim();
+        let trimmed = line.trim();
         if (trimmed === "" || trimmed.startsWith("#"))
             continue;
+        if (trimmed.startsWith("export "))
+            trimmed = trimmed.slice("export ".length).trim();
         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;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || !key.startsWith("VERAX_")) {
+            return { ok: false, reason: `env file refuses ${key}` };
+        }
         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;
+        parsed.push([key, value]);
     }
+    clearVeraxEnv(env);
+    for (const [key, value] of parsed)
+        env[key] = value;
     return { ok: true };
 }
+/**
+ * Drop every `VERAX_*` name before an env file is applied. Comparison is
+ * case-insensitive because Windows environment names are.
+ */
+export function clearVeraxEnv(env) {
+    for (const key of Object.keys(env)) {
+        if (key.toUpperCase().startsWith("VERAX_"))
+            delete env[key];
+    }
+}
+/** `serve --env-file` refuses a file that names neither JWKS source. */
+export function envFileJwksMissing(env) {
+    const file = env.VERAX_JWKS_FILE?.trim() ?? "";
+    const url = env.VERAX_JWKS_URL?.trim() ?? "";
+    if (file === "" && url === "")
+        return "env file sets neither VERAX_JWKS_FILE nor VERAX_JWKS_URL";
+    return null;
+}
 function shippedPolicyPath() {
     const here = dirname(fileURLToPath(import.meta.url));
     let resolved = null;
@@ -59,7 +85,13 @@ function shippedPolicyPath() {
     }
     return null;
 }
-function ownerOnly(path) {
+/** POSIX keeps owner-only mode. Windows grants the current user only outside install mode. */
+function ownerOnly(path, grantOwner) {
+    if (process.platform === "win32") {
+        if (grantOwner)
+            restrictToOwnerWin32(path);
+        return;
+    }
     try {
         chmodSync(path, 0o600);
     }
@@ -125,7 +157,25 @@ function parseInitArgs(argv) {
     }
     return { stateDir: resolve(stateDir), force, days, port };
 }
-export async function runInitLocal(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+function pathExists(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runInitLocal(argv, io = { stdout: process.stdout, stderr: process.stderr }, opts = {}) {
+    beginWinOwnerRun();
+    try {
+        return await runInitLocalBody(argv, io, opts);
+    }
+    finally {
+        endWinOwnerRun();
+    }
+}
+async function runInitLocalBody(argv, io, opts) {
     const parsed = parseInitArgs(argv);
     if ("error" in parsed) {
         io.stderr.write(`${parsed.error}\n`);
@@ -162,46 +212,82 @@ export async function runInitLocal(argv, io = { stdout: process.stdout, stderr:
         .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:",
-        `{
+    const createdState = !pathExists(stateDir);
+    const issuerExisted = pathExists(issuerDir);
+    const wrote = [];
+    const createdFiles = new Set();
+    const rollback = () => {
+        if (createdState) {
+            rmSync(stateDir, { recursive: true, force: true });
+            return;
+        }
+        for (const p of [...createdFiles].reverse())
+            rmSync(p, { force: true });
+        if (!issuerExisted)
+            rmSync(issuerDir, { recursive: true, force: true });
+    };
+    const writeNew = (target, contents, mode) => {
+        if (!pathExists(target))
+            createdFiles.add(target);
+        writeFileSync(target, contents, mode === undefined ? { encoding: "utf8" } : { encoding: "utf8", mode });
+        wrote.push(target);
+    };
+    const grantOwner = opts.noOwnerGrant !== true;
+    try {
+        if (createdState)
+            mkdirLeaf(stateDir, 0o700);
+        if (process.platform === "win32" && grantOwner)
+            restrictToOwnerWin32(stateDir);
+        // --force keeps the existing issuer directory and rewrites what is in it.
+        mkdirLeaf(issuerDir, 0o700, { existingOk: parsed.force === true });
+        opts.beforeWrite?.();
+        const keyPath = join(issuerDir, "key.pem");
+        const jwksPath = join(issuerDir, "jwks.json");
+        const insideToken = join(issuerDir, "agent.token");
+        const external = opts.tokenPath !== undefined && resolve(opts.tokenPath) !== resolve(insideToken);
+        const tokenPath = external ? resolve(opts.tokenPath) : insideToken;
+        if (external)
+            ensureTokenParent(dirname(tokenPath), opts.env ?? process.env);
+        const envPath = join(stateDir, "verax.env");
+        writeNew(keyPath, pem, 0o600);
+        ownerOnly(keyPath, grantOwner);
+        writeNew(jwksPath, `${JSON.stringify({ keys: [publicJwk] })}\n`, 0o600);
+        ownerOnly(jwksPath, grantOwner);
+        writeNew(tokenPath, token, 0o600);
+        ownerOnly(tokenPath, grantOwner);
+        if (external && existsSync(insideToken))
+            unlinkSync(insideToken);
+        if (!existsSync(policyDest) && policySrc) {
+            writeNew(policyDest, readFileSync(policySrc, "utf8"));
+            ownerOnly(policyDest, grantOwner);
+        }
+        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");
+        writeNew(envPath, envBody);
+        ownerOnly(envPath, grantOwner);
+        const lines = [
+            ...wrote.map((p) => `wrote ${p}`),
+            "",
+            "A shell as the same user can read this directory and approve its own calls, so for anything that matters run the body as another OS user or in a container, or keep the agent in a sandbox that cannot read the state directory.",
+            "",
+            "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",
@@ -209,11 +295,22 @@ export async function runInitLocal(argv, io = { stdout: process.stdout, stderr:
     }
   }
 }`,
-        `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;
+            `The token is the content of ${tokenPath}.`,
+            "",
+            "A held call is approved on this machine with: verax approve",
+            "",
+        ];
+        if (!opts.quiet)
+            io.stdout.write(lines.join("\n"));
+        return 0;
+    }
+    catch (err) {
+        const externalToken = wrote.find((p) => !p.startsWith(stateDir));
+        rollback();
+        if (externalToken && createdFiles.has(externalToken))
+            rmSync(externalToken, { force: true });
+        const detail = err instanceof Error ? err.message : "owner-only failed";
+        io.stderr.write(`${detail}\n`);
+        return err instanceof SystemToolError ? EX_CONFIG : 1;
+    }
 }