@verax-ai/body 0.1.2 → 0.1.3

package/README.md

@@ -35,6 +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 doctor` names what is missing. A misconfigured body exits with code 78
 before it listens.

package/dist/config.d.ts

@@ -10,6 +10,13 @@ export type BodyConfig = {
     tlsTerminated: boolean;
     /** Path to an inventory JSON file. Missing file is absence, not a fault. */
     inventoryFile?: string | null;
+    /**
+     * Path to the `VERAX_DOWNSTREAM` document. A path, not the JSON itself: the
+     * document may name a key in `env`, and a secret does not belong in the
+     * process environment of every child the operator later starts. Unset means
+     * no downstream; a named file that cannot be attached stops the body.
+     */
+    downstreamFile?: string | null;
 };
 export type ConfigResult = {
     ok: true;

package/dist/config.js

@@ -43,6 +43,7 @@ export function loadConfig(env) {
         return { ok: false, code: EX_CONFIG, reason: "missing VERAX_POLICY_FILE" };
     }
     const inventoryRaw = env.VERAX_INVENTORY_FILE?.trim() ?? "";
+    const downstreamRaw = env.VERAX_DOWNSTREAM?.trim() ?? "";
     return {
         ok: true,
         value: {
@@ -55,6 +56,7 @@ export function loadConfig(env) {
             policyFile,
             tlsTerminated,
             inventoryFile: inventoryRaw === "" ? null : inventoryRaw,
+            downstreamFile: downstreamRaw === "" ? null : downstreamRaw,
         },
     };
 }

package/dist/downstream.d.ts

@@ -1,15 +1,30 @@
 import type { Principal, ToolCall, ToolResult } from "@verax-ai/proxy";
 export type DownstreamToolFn = (call: ToolCall, principal: Principal, ref?: string) => Promise<ToolResult>;
+/**
+ * One child, reached one of two ways. `command` spawns it over stdio;
+ * `url` speaks Streamable HTTP to one already running. Exactly one of the
+ * two: a document naming both does not say which the operator meant, and a
+ * document naming neither says nothing at all.
+ */
 export type DownstreamSpec = {
     prefix: string;
-    command: string;
+    /** stdio: the process to start. */
+    command?: string;
     args?: string[];
     cwd?: string;
     env?: Record<string, string>;
+    /** HTTP: the MCP endpoint of a server already running. */
+    url?: string;
+    /** HTTP: headers the operator sends to the child, such as its own bearer. */
+    headers?: Record<string, string>;
     timeoutMs?: number;
 };
 export type DownstreamTool = {
     name: string;
+    /** The child's own description, as `tools/list` gave it. */
+    description?: string;
+    /** The child's own input schema, republished unchanged. */
+    inputSchema?: unknown;
     fn: DownstreamToolFn;
 };
 export type DownstreamSession = {
@@ -25,4 +40,10 @@ export declare class DownstreamCallError extends Error {
 export declare function prefixedName(prefix: string, childName: string): string;
 export declare function extraToolNameOk(name: string): boolean;
 export declare function parseDownstreamJson(raw: string): DownstreamSpec;
+/**
+ * The `VERAX_DOWNSTREAM` document: one child, or an array of them. An empty
+ * array is a document that attaches nothing, which is not the same as no
+ * document at all — the operator wrote it, so it is honoured.
+ */
+export declare function parseDownstreamDocument(raw: string): DownstreamSpec[];
 export declare function openDownstream(spec: DownstreamSpec): Promise<DownstreamSession>;

package/dist/downstream.js

@@ -1,6 +1,7 @@
 import { Readable } from "node:stream";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 const PREFIX_RE = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
 const CHILD_TOOL_RE = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
 /** Prefixed name a caller may put on extraTools: `prefix.childName`. */
@@ -39,10 +40,49 @@ export function parseDownstreamJson(raw) {
     if (typeof rec.prefix !== "string" || !PREFIX_RE.test(rec.prefix)) {
         throw new Error("downstream-prefix-invalid");
     }
-    if (typeof rec.command !== "string" || rec.command.trim() === "") {
-        throw new Error("downstream-command-invalid");
+    const cmdVar = rec.command !== undefined;
+    const urlVar = rec.url !== undefined;
+    if (cmdVar && urlVar)
+        throw new Error("downstream-transport-ambiguous");
+    if (!cmdVar && !urlVar)
+        throw new Error("downstream-transport-missing");
+    const spec = { prefix: rec.prefix };
+    if (cmdVar) {
+        if (typeof rec.command !== "string" || rec.command.trim() === "") {
+            throw new Error("downstream-command-invalid");
+        }
+        spec.command = rec.command;
+    }
+    else {
+        if (typeof rec.url !== "string" || rec.url.trim() === "") {
+            throw new Error("downstream-url-invalid");
+        }
+        let parsed;
+        try {
+            parsed = new URL(rec.url);
+        }
+        catch {
+            throw new Error("downstream-url-invalid");
+        }
+        // Only the two schemes the SDK transport speaks. A `file:` or `ftp:` URL
+        // would be read as a fetch target by something later, so it is refused here.
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new Error("downstream-url-invalid");
+        }
+        spec.url = rec.url;
+        if (rec.headers !== undefined) {
+            if (rec.headers === null || typeof rec.headers !== "object" || Array.isArray(rec.headers)) {
+                throw new Error("downstream-headers-invalid");
+            }
+            const headers = {};
+            for (const [k, v] of Object.entries(rec.headers)) {
+                if (typeof v !== "string")
+                    throw new Error("downstream-headers-invalid");
+                headers[k] = v;
+            }
+            spec.headers = headers;
+        }
     }
-    const spec = { prefix: rec.prefix, command: rec.command };
     if (rec.args !== undefined) {
         if (!Array.isArray(rec.args) || rec.args.some((a) => typeof a !== "string")) {
             throw new Error("downstream-args-invalid");
@@ -75,6 +115,32 @@ export function parseDownstreamJson(raw) {
     }
     return spec;
 }
+/**
+ * The `VERAX_DOWNSTREAM` document: one child, or an array of them. An empty
+ * array is a document that attaches nothing, which is not the same as no
+ * document at all — the operator wrote it, so it is honoured.
+ */
+export function parseDownstreamDocument(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("downstream-json-invalid");
+    }
+    const items = Array.isArray(parsed) ? parsed : [parsed];
+    const specs = [];
+    const prefixes = new Set();
+    for (const item of items) {
+        const spec = parseDownstreamJson(JSON.stringify(item));
+        if (prefixes.has(spec.prefix)) {
+            throw new Error(`downstream-prefix-duplicate:${spec.prefix}`);
+        }
+        prefixes.add(spec.prefix);
+        specs.push(spec);
+    }
+    return specs;
+}
 // The SDK result is a union (current shape with an index signature, or the
 // legacy { toolResult } shape), so it is narrowed here rather than trusted.
 function asTextResult(raw) {
@@ -100,14 +166,11 @@ async function shut(client, transport) {
     await client.close().catch(() => undefined);
     await transport.close().catch(() => undefined);
 }
-export async function openDownstream(spec) {
-    if (!PREFIX_RE.test(spec.prefix)) {
-        throw new Error("downstream-prefix-invalid");
-    }
-    if (spec.command.trim() === "") {
+/** Spawns the child. Its stderr is drained so a chatty child cannot block it. */
+function stdioTransport(spec) {
+    if (spec.command === undefined || spec.command.trim() === "") {
         throw new Error("downstream-command-invalid");
     }
-    const timeoutMs = spec.timeoutMs ?? 10_000;
     // Safe inherit + operator overlay. Not process.env: that would copy
     // VERAX_* tokens the body already holds.
     const env = { ...getDefaultEnvironment(), ...(spec.env ?? {}) };
@@ -122,6 +185,32 @@ export async function openDownstream(spec) {
     const stderr = transport.stderr;
     if (stderr instanceof Readable)
         stderr.resume();
+    return transport;
+}
+/**
+ * Talks to a server already running. The headers are the operator's, from the
+ * document — the body's own bearer is never forwarded, for the same
+ * confused-deputy reason the stdio child does not inherit `VERAX_*`.
+ */
+function httpTransport(spec) {
+    if (spec.url === undefined)
+        throw new Error("downstream-url-invalid");
+    return new StreamableHTTPClientTransport(new URL(spec.url), {
+        ...(spec.headers ? { requestInit: { headers: spec.headers } } : {}),
+    });
+}
+export async function openDownstream(spec) {
+    if (!PREFIX_RE.test(spec.prefix)) {
+        throw new Error("downstream-prefix-invalid");
+    }
+    if (spec.command !== undefined && spec.url !== undefined) {
+        throw new Error("downstream-transport-ambiguous");
+    }
+    if (spec.command === undefined && spec.url === undefined) {
+        throw new Error("downstream-transport-missing");
+    }
+    const timeoutMs = spec.timeoutMs ?? 10_000;
+    const transport = spec.url !== undefined ? httpTransport(spec) : stdioTransport(spec);
     const client = new Client({ name: "verax-downstream", version: "0.0.0" });
     let listed;
     try {
@@ -148,6 +237,8 @@ export async function openDownstream(spec) {
         const childName = tool.name;
         tools.push({
             name,
+            ...(typeof tool.description === "string" ? { description: tool.description } : {}),
+            ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
             fn: async (call) => {
                 let raw;
                 try {

package/dist/server.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -14,6 +15,7 @@ import { readHeartbeat, readWitnessPulse } from "./health-extras.js";
 import { agentsWindow } from "./agents.js";
 import { inventoryHealth, readInventoryFile } from "./inventory-file.js";
 import { createBodyServices, TOOL_NAMES } from "./wiring.js";
+import { openDownstream, parseDownstreamDocument, } from "./downstream.js";
 // What a brain reads before it calls. Each description says what the tool is
 // for, what it does and does not do, what the gate may answer, and what comes
 // back; each parameter says its format and its bounds. The answers named here
@@ -221,17 +223,94 @@ function send(res, status, body, headers) {
     });
     res.end(text);
 }
+/**
+ * Republishes a child's own `tools/list` entry under its prefixed name. The
+ * description is the child's; the sentence added here says what changes by
+ * going through the body, because the answers a caller gets back
+ * (`denied:…`, `deferred:…`) are the gate's, not the child's.
+ */
+function downstreamMeta(tool) {
+    const own = typeof tool.description === "string" && tool.description !== "" ? `${tool.description} ` : "";
+    return {
+        name: tool.name,
+        description: own +
+            "Forwarded by this body to the downstream server that published it: the call passes the same policy gate " +
+            "and leaves the same signed decision under this name, so it may be answered with denied:<reason>:<ref> or " +
+            "deferred:approval-required:<ref> before the downstream server ever sees it.",
+        inputSchema: tool.inputSchema ?? { type: "object" },
+    };
+}
+async function closeAll(sessions) {
+    for (const session of sessions) {
+        await session.close().catch(() => undefined);
+    }
+}
+/**
+ * What an operator may see about the attached children: the prefix they call
+ * by, how the body reaches them, and the names it will accept.
+ *
+ * Deliberately not the address. A child's URL can carry its token in the path
+ * — the live Conarium's does — and a command line names a path on this host.
+ * Neither is needed to answer "what is standing behind this gate", so neither
+ * is published. The `tests/downstream-visible` guard asserts their absence.
+ */
+function downstreamPublic(sessions, specs) {
+    return sessions.map((session) => {
+        const spec = specs.find((s) => s.prefix === session.prefix);
+        return {
+            prefix: session.prefix,
+            transport: spec?.url !== undefined ? "http" : "stdio",
+            tools: session.tools.map((t) => t.name),
+        };
+    });
+}
+/**
+ * Opens every child the document names. One child that refuses to attach
+ * closes the ones already open and throws: a half-attached body would serve a
+ * tool list its operator never wrote.
+ */
+async function attachDownstream(file) {
+    if (file === null || file.trim() === "")
+        return { sessions: [], specs: [] };
+    const specs = parseDownstreamDocument(readFileSync(file, "utf8"));
+    const sessions = [];
+    for (const spec of specs) {
+        try {
+            sessions.push(await openDownstream(spec));
+        }
+        catch (err) {
+            await closeAll(sessions);
+            const detail = err instanceof Error ? err.message : "attach-failed";
+            throw new Error(`downstream-attach-failed:${spec.prefix}:${detail}`);
+        }
+    }
+    return { sessions, specs };
+}
 export async function listen(config) {
     const signers = loadOrCreateSigners(config.stateDir);
-    const services = createBodyServices({
-        stateDir: config.stateDir,
-        policyFile: config.policyFile,
-        recordSigner: signers.recordSigner,
-        effectSigner: signers.effectSigner,
-    });
+    // The children are attached before the door opens. A named document the body
+    // cannot honour stops the start: a body that serves six tools while its
+    // operator wrote seven is answering for a gate it does not have.
+    const { sessions, specs: downstreamSpecs } = await attachDownstream(config.downstreamFile ?? null);
+    const extraTools = sessions.flatMap((session) => session.tools);
+    let services;
+    try {
+        services = createBodyServices({
+            stateDir: config.stateDir,
+            policyFile: config.policyFile,
+            recordSigner: signers.recordSigner,
+            effectSigner: signers.effectSigner,
+            ...(extraTools.length > 0 ? { extraTools } : {}),
+        });
+    }
+    catch (err) {
+        await closeAll(sessions);
+        throw err;
+    }
+    const toolMeta = [...TOOL_META, ...extraTools.map(downstreamMeta)];
     const verify = createVerifier(config.jwksUrl, config.issuer, config.audience);
     const attachHandlers = (mcp) => {
-        mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_META }));
+        mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolMeta }));
         mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             const auth = extra?.authInfo;
             const scopes = new Set(auth?.scopes ?? []);
@@ -315,6 +394,9 @@ export async function listen(config) {
                     heartbeat: readHeartbeat(config.stateDir),
                     witness: readWitnessPulse(config.stateDir),
                     inventory: inventoryHealth(readInventoryFile(config.inventoryFile)),
+                    // Always an array, empty when nothing is attached: a missing field
+                    // would read as "this body is too old to tell you".
+                    downstream: downstreamPublic(sessions, downstreamSpecs),
                 });
                 return;
             }
@@ -620,6 +702,7 @@ export async function listen(config) {
     });
     server.on("close", () => {
         services.ledger.close();
+        void closeAll(sessions);
     });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verax-ai/body",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {