@verax-ai/body 0.3.0 → 0.4.0

package/README.md

@@ -54,8 +54,13 @@ your issuer. The tools the body offers are `memory.get`, `memory.put`,
 decides which of them a token's scopes may call, and a call can be held
 until an operator on this machine approves it.
 
-Other commands: `approve`, `operator`, `reconcile`, `witness`, `halt`,
-`unlock`, `desktop`. `verax --help` lists them.
+Other commands: `install`, `uninstall`, `approve`, `operator`, `reconcile`,
+`witness`, `halt`, `unlock`, `desktop`. `verax install` and an elevated
+`verax approve` need an administrator-owned copy of this program (Windows,
+Administrator PowerShell: `npm install -g --prefix "$env:ProgramFiles\verax-cli" @verax-ai/body`;
+Linux and macOS: `sudo npm install -g --prefix /opt/verax-cli @verax-ai/body`). That
+install is the boundary against an agent that has a shell as your user;
+`verax init --local` is not that boundary. `verax --help` lists them.
 
 ## License
 

package/dist/approve-cli.d.ts

@@ -1,3 +1,4 @@
+import { type ToolExec, type WindowsMachineRoots } from "./install.ts";
 export declare function resolveApproveRef(pending: {
     ref: string;
     status?: string;
@@ -9,4 +10,24 @@ export declare function resolveApproveRef(pending: {
     reason: "unknown-ref" | "ambiguous-ref";
     candidates: string[];
 };
-export declare function runApprove(argv: string[], writeErr?: (s: string) => void, writeOut?: (s: string) => void): Promise<number>;
+export type ApproveIo = {
+    isTTY: boolean;
+    ask: (prompt: string) => Promise<string>;
+};
+export type ApproveHooks = {
+    elevated?: () => boolean;
+    codeProbe?: (dir: string) => boolean;
+    execPathProbe?: (file: string) => boolean;
+    execArgv?: readonly string[];
+    /**
+     * True when the invoking user can change that state directory.
+     * Absent means the real ACL or mode check. Ignored when the process is not elevated.
+     */
+    stateProbe?: (dir: string) => boolean;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    exec?: ToolExec;
+    /** Machine ProgramData and Program Files. When omitted, approve reads HKLM. */
+    windowsMachineRoots?: WindowsMachineRoots;
+};
+export declare function runApprove(argv: string[], writeErr?: (s: string) => void, writeOut?: (s: string) => void, io?: ApproveIo, hooks?: ApproveHooks): Promise<number>;

package/dist/approve-cli.js

@@ -1,28 +1,46 @@
 import { existsSync, readFileSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
-import { approvePending, approvalsLogFor, createApprovalBudgetGuard, enqueueApprovalCommand, FileLedger, loadApprovalsFromDir, loadPolicy, } from "@verax-ai/proxy";
+import { createInterface } from "node:readline";
+import { approvePending, approvalsLogFor, createApprovalBudgetGuard, enqueueApprovalCommand, FileLedger, loadApprovalsFromDir, loadPolicy, TERMINAL_CONTROL_CLASS, } from "@verax-ai/proxy";
+import { EX_CONFIG } from "./config.js";
+import { cliCodeCheckPassedAlready, defaultElevated, directoryAccess, elevatedCommandCodeRefusal, elevatedStateDirRefusal, readWindowsMachineRoots, stateDirFor, SystemToolError, unreadableSentence, windowsProgramDataRefusal } from "./install.js";
 import { loadOrCreateSigners } from "./keys.js";
-function policyForApprove(stateDir, policyHash) {
-    const fromEnv = process.env.VERAX_POLICY_FILE?.trim();
-    if (fromEnv) {
-        try {
-            return loadPolicy(readFileSync(fromEnv, "utf8"));
-        }
-        catch {
-            // Fall through to the snapshot the body wrote for this hash.
-        }
-    }
+function policyFromSnapshot(stateDir, policyHash) {
     const snap = join(stateDir, "policies", `${policyHash}.json`);
     if (!existsSync(snap))
         return null;
     try {
-        return loadPolicy(JSON.parse(readFileSync(snap, "utf8")));
+        const loaded = loadPolicy(JSON.parse(readFileSync(snap, "utf8")));
+        if (loaded.hash !== policyHash)
+            return null;
+        return loaded;
     }
     catch {
         return null;
     }
 }
+function policyForApprove(stateDir, policyHash, env, elevated) {
+    // An elevated approve inherits the user's environment. The snapshot the body
+    // wrote is the policy that held the call. The environment is not.
+    // When not elevated, the environment file is that policy only when its
+    // canonical hash is the defer's policyHash. Any other file falls through
+    // to the snapshot.
+    if (!elevated) {
+        const fromEnv = env.VERAX_POLICY_FILE?.trim();
+        if (fromEnv) {
+            try {
+                const loaded = loadPolicy(readFileSync(fromEnv, "utf8"));
+                if (loaded.hash === policyHash)
+                    return loaded;
+            }
+            catch {
+                // Fall through to the snapshot the body wrote for this hash.
+            }
+        }
+    }
+    return policyFromSnapshot(stateDir, policyHash);
+}
 function operatorName() {
     try {
         const name = userInfo().username;
@@ -46,15 +64,146 @@ export function resolveApproveRef(pending, given) {
         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) {
+const NEEDS_TERMINAL = "verax approve needs a terminal: it shows what is waiting and asks you to type the amount back\n";
+function integerMinor(value) {
+    return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+/** An integer minor-unit amount, or null when the stored amount cannot be read as one. */
+function minorUnits(row) {
+    if (typeof row.amount === "number")
+        return integerMinor(row.amount);
+    return integerMinor(row.args.amountMinor);
+}
+const HELD_CONTROL = new RegExp(`[${TERMINAL_CONTROL_CLASS}]`, "gu");
+/**
+ * One argument per line, name and value both JSON-quoted, so neither can look like another field.
+ * JSON leaves U+0085, U+FEFF, U+2028 and U+2029 as they are, so every terminal-control code point
+ * is written as a \u escape as well.
+ */
+function escapeHeld(text) {
+    return text.replace(HELD_CONTROL, (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, "0")}`);
+}
+function quotedField(name, value) {
+    const text = typeof value === "string" ? value : value === undefined || value === null ? "" : JSON.stringify(value);
+    const quotedName = escapeHeld(JSON.stringify(name));
+    const quoted = escapeHeld(JSON.stringify(text));
+    return `${quotedName}: ${quoted}\n`;
+}
+function spendPrompt(row, amount) {
+    const payee = typeof row.payee === "string" ? row.payee : String(row.args.payee ?? "");
+    const currency = typeof row.currency === "string" ? row.currency : String(row.args.currency ?? "");
+    const reference = typeof row.args.reference === "string" ? row.args.reference : "";
+    return [
+        quotedField("tool", row.subject),
+        quotedField("payee", payee),
+        quotedField("amount", String(amount)),
+        quotedField("currency", currency),
+        quotedField("reference", reference),
+        quotedField("requestHash", row.requestHash.slice(0, 12)),
+    ].join("");
+}
+function argumentPrompt(row) {
+    const lines = [quotedField("tool", row.subject)];
+    for (const key of Object.keys(row.args).sort())
+        lines.push(quotedField(key, row.args[key]));
+    return lines.join("");
+}
+function readTypedAmount() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.once("line", (line) => {
+            rl.close();
+            resolve(line);
+        });
+    });
+}
+function defaultApproveIo() {
+    return {
+        isTTY: Boolean(process.stdin.isTTY),
+        ask: () => readTypedAmount(),
+    };
+}
+export async function runApprove(argv, writeErr = (s) => process.stderr.write(s), writeOut = (s) => process.stdout.write(s), io, hooks) {
+    const platform = hooks?.platform ?? process.platform;
+    const env = hooks?.env ?? process.env;
+    let isElevated = false;
+    try {
+        isElevated = hooks?.elevated ? hooks.elevated() : defaultElevated(platform);
+    }
+    catch (err) {
+        if (err instanceof SystemToolError) {
+            writeErr(`${err.message}\n`);
+            return EX_CONFIG;
+        }
+        throw err;
+    }
+    if (isElevated && !cliCodeCheckPassedAlready()) {
+        const refusal = elevatedCommandCodeRefusal(platform, env, hooks?.codeProbe, {
+            execPathProbe: hooks?.execPathProbe,
+            execArgv: hooks?.execArgv,
+        });
+        if (refusal) {
+            writeErr(refusal.endsWith("\n") ? refusal : `${refusal}\n`);
+            return EX_CONFIG;
+        }
+    }
+    const terminal = io ?? defaultApproveIo();
+    const rest = argv.slice(1).filter((a) => a !== "--from-script");
+    const fromScript = argv.includes("--from-script");
+    let stateDir = rest[0];
+    let given = rest[1];
+    if (rest.length === 1 && stateDir) {
+        let installed;
+        try {
+            let machine = hooks?.windowsMachineRoots;
+            if (platform === "win32" && !machine)
+                machine = readWindowsMachineRoots(hooks?.exec);
+            if (platform === "win32") {
+                const rootRefusal = windowsProgramDataRefusal(env, hooks?.exec, machine);
+                if (rootRefusal) {
+                    writeErr(`${rootRefusal}\n`);
+                    return 78;
+                }
+            }
+            installed = stateDirFor(platform, env, undefined, machine);
+        }
+        catch (err) {
+            writeErr(`${err instanceof SystemToolError ? err.message : "refusing install root"}\n`);
+            return 78;
+        }
+        const access = directoryAccess(installed);
+        if (access === "unreadable") {
+            writeErr(`${unreadableSentence(installed, "approve")}\n`);
+            return 77;
+        }
+        if (access === "ok") {
+            given = stateDir;
+            stateDir = installed;
+        }
+    }
+    if (!stateDir || !given || (rest.length !== 2 && !(rest.length === 1 && stateDir && given))) {
         writeErr("verax approve <stateDir> <ref>\n");
         return 78;
     }
-    const resolved = resolveApproveRef(loadApprovalsFromDir(stateDir), given);
+    if (isElevated) {
+        const owned = elevatedStateDirRefusal(stateDir, platform, env, hooks?.stateProbe);
+        if (owned) {
+            writeErr(`${owned}\n`);
+            return 78;
+        }
+    }
+    if (directoryAccess(stateDir) === "unreadable") {
+        writeErr(`${unreadableSentence(stateDir, "approve")}\n`);
+        return 77;
+    }
+    // A non-interactive shell can read the state directory. Without a person
+    // at a terminal, or an explicit --from-script, nothing is approved.
+    if (!fromScript && !terminal.isTTY) {
+        writeErr(NEEDS_TERMINAL);
+        return 78;
+    }
+    const rows = loadApprovalsFromDir(stateDir);
+    const resolved = resolveApproveRef(rows, given);
     if (!resolved.ok) {
         if (resolved.reason === "ambiguous-ref") {
             writeErr(`ambiguous-ref\n${resolved.candidates.join("\n")}\n`);
@@ -64,6 +213,39 @@ export async function runApprove(argv, writeErr = (s) => process.stderr.write(s)
         return 78;
     }
     const ref = resolved.ref;
+    const via = fromScript ? "cli-script" : "cli";
+    // The amount is checked before the ledger is opened. A running body holds
+    // the lock, and queueing first would approve without the person ever typing it.
+    if (!fromScript) {
+        const waiting = rows.find((row) => row.ref === ref);
+        if (!waiting) {
+            writeErr("approve-unknown-ref\n");
+            return 78;
+        }
+        if (waiting.subject === "spend") {
+            const expected = minorUnits(waiting);
+            if (expected === null) {
+                writeErr("approve-amount-unreadable\n");
+                return 1;
+            }
+            writeOut(spendPrompt(waiting, expected));
+            writeOut("Type the amount in minor units:\n");
+            const typed = (await terminal.ask("Type the amount in minor units:\n")).trim();
+            if (typed !== String(expected)) {
+                writeErr("approve-amount-mismatch\n");
+                return 1;
+            }
+        }
+        else {
+            writeOut(argumentPrompt(waiting));
+            writeOut("Type yes:\n");
+            const typed = (await terminal.ask("Type yes:\n")).trim();
+            if (typed !== "yes") {
+                writeErr("approve-confirm-mismatch\n");
+                return 1;
+            }
+        }
+    }
     let ledger;
     try {
         ledger = new FileLedger(stateDir);
@@ -71,7 +253,7 @@ export async function runApprove(argv, writeErr = (s) => process.stderr.write(s)
     catch (err) {
         const msg = err instanceof Error ? err.message : "";
         if (msg.startsWith("ledger-locked")) {
-            enqueueApprovalCommand(stateDir, { ref, approverId: operatorName(), atMs: Date.now() });
+            enqueueApprovalCommand(stateDir, { ref, approverId: operatorName(), atMs: Date.now(), via });
             writeOut("approve-queued\n");
             return 0;
         }
@@ -87,7 +269,12 @@ export async function runApprove(argv, writeErr = (s) => process.stderr.write(s)
             writeErr("approve-unknown-ref\n");
             return 78;
         }
-        const policy = policyForApprove(stateDir, defer.claims.policyHash);
+        const policy = policyForApprove(stateDir, defer.claims.policyHash, env, isElevated);
+        const waitingSubject = rows.find((row) => row.ref === ref)?.subject;
+        if (!policy && waitingSubject === "spend") {
+            writeErr("approve-policy-missing\n");
+            return 1;
+        }
         const result = await approvePending({
             ledger,
             recordSigner: signers.recordSigner,
@@ -95,11 +282,11 @@ export async function runApprove(argv, writeErr = (s) => process.stderr.write(s)
             nonce: () => crypto.randomUUID(),
             ref,
             approverId: operatorName(),
-            via: "cli",
+            via,
             policyHash: defer.claims.policyHash,
             approvals,
             ...(policy
-                ? { budgetGuard: createApprovalBudgetGuard({ policy, approvals, now: () => Date.now() }) }
+                ? { budgetGuard: createApprovalBudgetGuard({ policy, approvals, now: () => Date.now(), ledger }) }
                 : {}),
         });
         if (!result.ok) {

package/dist/auth.d.ts

@@ -10,5 +10,13 @@ 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 createVerifier(jwksUrl: string, issuer: string, audience: string, jwksFile?: string | null, 
+/**
+ * Keys fetched once, before this process started accepting tokens.
+ * `createLocalJWKSet` does not refetch. A `kid` that was not in this set
+ * fails closed. This is not `VERAX_JWKS_FILE`: that mode refuses operator scopes.
+ */
+jwksPin?: {
+    keys: Record<string, unknown>[];
+} | null): (token: string) => Promise<VerifiedBearer>;
 export declare function readBearer(header: string | undefined): string | null;

package/dist/auth.js

@@ -35,8 +35,18 @@ export class JwksFileError extends Error {
         this.name = "JwksFileError";
     }
 }
-export function createVerifier(jwksUrl, issuer, audience, jwksFile) {
-    const jwks = jwksFile ? localJwks(jwksFile) : createRemoteJWKSet(new URL(jwksUrl));
+export function createVerifier(jwksUrl, issuer, audience, jwksFile, 
+/**
+ * Keys fetched once, before this process started accepting tokens.
+ * `createLocalJWKSet` does not refetch. A `kid` that was not in this set
+ * fails closed. This is not `VERAX_JWKS_FILE`: that mode refuses operator scopes.
+ */
+jwksPin) {
+    const jwks = jwksFile
+        ? localJwks(jwksFile)
+        : jwksPin
+            ? createLocalJWKSet(jwksPin)
+            : createRemoteJWKSet(new URL(jwksUrl));
     return async (token) => {
         const { payload } = await jwtVerify(token, jwks, {
             issuer,

package/dist/body-log.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Append this process's stdout and stderr to `file`.
+ * POSIX: the file is mode 0600 (umask cannot widen it).
+ * Windows: CreateFile sets no explicit DACL, so the new file inherits the
+ * parent directory ACL. The state directory's service ACL is that parent.
+ */
+export declare function attachBodyLog(file: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Last `n` lines, or null when the file cannot be read. A trailing newline is not an extra line. */
+export declare function readLogTail(file: string, n: number): string | null;

package/dist/body-log.js

@@ -0,0 +1,61 @@
+import { chmodSync, openSync, readFileSync, writeSync } from "node:fs";
+/**
+ * Append this process's stdout and stderr to `file`.
+ * POSIX: the file is mode 0600 (umask cannot widen it).
+ * Windows: CreateFile sets no explicit DACL, so the new file inherits the
+ * parent directory ACL. The state directory's service ACL is that parent.
+ */
+export function attachBodyLog(file) {
+    let fd;
+    try {
+        fd = openSync(file, "a", 0o600);
+    }
+    catch (err) {
+        return { ok: false, reason: `cannot open log file ${file}: ${err.message}` };
+    }
+    if (process.platform !== "win32") {
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch {
+            // The platform does not honour the mode bit.
+        }
+    }
+    const append = (chunk, encoding) => {
+        try {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, encoding ?? "utf8") : Buffer.from(chunk);
+            writeSync(fd, buf);
+        }
+        catch {
+            // A full disk must not hide the line already going to the console.
+        }
+    };
+    tee(process.stdout, append);
+    tee(process.stderr, append);
+    return { ok: true };
+}
+function tee(stream, append) {
+    const original = stream.write.bind(stream);
+    stream.write = ((chunk, encoding, cb) => {
+        if (typeof encoding === "function") {
+            append(chunk);
+            return original(chunk, encoding);
+        }
+        append(chunk, encoding);
+        return original(chunk, encoding, cb);
+    });
+}
+/** Last `n` lines, or null when the file cannot be read. A trailing newline is not an extra line. */
+export function readLogTail(file, n) {
+    try {
+        const text = readFileSync(file, "utf8");
+        const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        const tail = lines.slice(-n).join("\n");
+        return tail === "" ? "" : `${tail}\n`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli.d.ts

@@ -1,2 +1,24 @@
 #!/usr/bin/env node
-export {};
+export type CliHooks = {
+    elevated?: () => boolean;
+    codeProbe?: (dir: string) => boolean;
+    /** True when that Node path can be changed by the invoking user. See `NodeTrustProbe`. */
+    execPathProbe?: (file: string) => boolean;
+    /** Defaults to `process.execArgv` for the elevated preload check. */
+    execArgv?: readonly string[];
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    stdout?: {
+        write(s: string): unknown;
+    };
+    stderr?: {
+        write(s: string): unknown;
+    };
+};
+/**
+ * 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 declare function runCli(argv: string[], hooks?: CliHooks): Promise<number>;