@verax-ai/body 0.1.4 → 0.2.0

package/README.md

@@ -35,7 +35,7 @@ Bearer token the configured issuer did not sign.
 | `VERAX_POLICY_FILE` | yes | Policy the gate applies. `@verax-ai/proxy` ships `policy/default.json`, which denies what it does not name. |
 | `VERAX_BIND` | no | `host:port` to listen on. Default `127.0.0.1:8787`; anything but loopback needs `VERAX_TLS_TERMINATED=1`. |
 | `VERAX_INVENTORY_FILE` | no | Roster document the body serves. The format is `@verax-ai/inventory`. |
-| `VERAX_DOWNSTREAM` | no | Path to a JSON document naming MCP servers to put behind this gate: one `{ prefix, command?, args?, cwd?, env?, url?, headers?, timeoutMs? }` or an array of them. Each child names exactly one way in — `command` to spawn it over stdio, or `url` to reach one already running over Streamable HTTP, with `headers` for its own bearer. A path and not the JSON itself, because the document may name a key in `env` or `headers`. Their tools are served as `prefix.childName` and need an exact policy rule under that name; a named child that cannot be opened stops the body. |
+| `VERAX_DOWNSTREAM` | no | Path to a JSON document naming MCP servers to put behind this gate: one `{ prefix, command?, args?, cwd?, env?, url?, headers?, timeoutMs?, trust? }` or an array of them. Each child names exactly one way in — `command` to spawn it over stdio, or `url` to reach one already running over Streamable HTTP, with `headers` for its own bearer. A stdio child requires `"trust": "same-user"` (it runs as the same user as the body and can read the signing keys); an HTTP child does not ask for that field and must not carry it. This is a breaking change: existing stdio documents do not open until the field is added. A path and not the JSON itself, because the document may name a key in `env` or `headers`. Their tools are served as `prefix.childName` and need an exact policy rule under that name; a named child that cannot be opened stops the body. |
 
 `verax doctor` names what is missing. A misconfigured body exits with code 78
 before it listens.

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { indexCoverage, listPieceFiles } from "@verax-ai/proxy";
 import { loadConfig, isLoopbackHost } from "./config.js";
+import { parseDownstreamDocument } from "./downstream.js";
 import { pidAlive, readLockFile } from "./unlock.js";
 const SECRET_RE = /sk-|-----BEGIN|Bearer |eyJ[A-Za-z0-9_-]{10,}\./;
 const SECRET_NAME = /^(VERAX_DEV_TOKEN|.*_(TOKEN|SECRET|KEY))$/;
@@ -184,6 +185,33 @@ export function runDoctor(env, argv) {
             });
         }
     }
+    const downstreamPath = env.VERAX_DOWNSTREAM?.trim() ?? "";
+    if (downstreamPath !== "") {
+        try {
+            const specs = parseDownstreamDocument(readFileSync(downstreamPath, "utf8"));
+            const stdio = specs.filter((s) => s.command !== undefined);
+            const http = specs.filter((s) => s.url !== undefined);
+            checks.push({
+                id: "downstream-document",
+                level: "ok",
+                detail: `${specs.length} child(ren): ${stdio.length} stdio, ${http.length} http`,
+            });
+            for (const spec of stdio) {
+                checks.push({
+                    id: `downstream-stdio:${spec.prefix}`,
+                    level: "warn",
+                    detail: `stdio child ${spec.prefix} runs as the same user as the body and can read the body's signing keys (keys/*.pem). An untrusted child should be reached over HTTP, ideally on a separate machine or under a separate operating-system user.`,
+                });
+            }
+        }
+        catch (err) {
+            checks.push({
+                id: "downstream-document",
+                level: "fail",
+                detail: err instanceof Error ? err.message : "downstream-document-unreadable",
+            });
+        }
+    }
     return checks;
 }
 const DEFAULT_REDIRECTS = ["http://127.0.0.1:5173/", "http://127.0.0.1:4173/"];

package/dist/downstream.d.ts

@@ -18,6 +18,12 @@ export type DownstreamSpec = {
     /** HTTP: headers the operator sends to the child, such as its own bearer. */
     headers?: Record<string, string>;
     timeoutMs?: number;
+    /**
+     * stdio only. The operator wrote that this child runs as the same user
+     * as the body and can read the body's signing keys. Required on stdio;
+     * forbidden on HTTP.
+     */
+    trust?: "same-user";
 };
 export type DownstreamTool = {
     name: string;

package/dist/downstream.js

@@ -29,6 +29,18 @@ export function prefixedName(prefix, childName) {
 export function extraToolNameOk(name) {
     return EXTRA_NAME_RE.test(name);
 }
+/**
+ * The operator wrote `"trust": "same-user"` on a stdio child. Missing ack
+ * refuses start. One rule, two call sites — do not duplicate the predicate.
+ */
+function assertStdioTrusted(spec) {
+    if (spec.command !== undefined && spec.trust !== "same-user") {
+        // The prefix is the operator's own name for the child and names WHICH entry
+        // to fix in a document with several. Nothing else about the child goes in:
+        // not the command, the arguments or the environment.
+        throw new Error(`downstream-stdio-trust-required:${spec.prefix}`);
+    }
+}
 export function parseDownstreamJson(raw) {
     let parsed;
     try {
@@ -117,6 +129,16 @@ export function parseDownstreamJson(raw) {
         }
         spec.timeoutMs = rec.timeoutMs;
     }
+    if (rec.trust !== undefined) {
+        // HTTP + any trust, or a value other than "same-user", is the same
+        // refusal: the field is not a claim about a remote host, and it is
+        // not a free-form string.
+        if (spec.url !== undefined || rec.trust !== "same-user") {
+            throw new Error("downstream-trust-invalid");
+        }
+        spec.trust = "same-user";
+    }
+    assertStdioTrusted(spec);
     return spec;
 }
 /**
@@ -175,6 +197,8 @@ function stdioTransport(spec) {
     if (spec.command === undefined || spec.command.trim() === "") {
         throw new Error("downstream-command-invalid");
     }
+    // Last check before the spawn: openDownstream can be called without parse.
+    assertStdioTrusted(spec);
     // Safe inherit + operator overlay. Not process.env: that would copy
     // VERAX_* tokens the body already holds.
     const env = { ...getDefaultEnvironment(), ...(spec.env ?? {}) };

package/package.json

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