@wardby/cli 0.5.2 → 0.6.0

package/dist/sandbox/host-functions.js

@@ -33,20 +33,50 @@ export function sandboxFetchPolicy(toolHosts, operatorHosts = FETCH_ALLOWED_HOST
 function args(argsJson) {
     return JSON.parse(argsJson);
 }
-export function installHostFunctions(context, runtime, options) {
+/**
+ * The bridges that touch credentials, storage, the network, or the operator's
+ * logs. They always run on the trusted side: in-process today, and served by
+ * the native sandbox gateway for a run whose engine runs in a worker.
+ */
+export const PRIVILEGED_BRIDGE_NAMES = [
+    "__bridge_console",
+    "__bridge_fetch",
+    "__bridge_datastoreGet",
+    "__bridge_datastoreSet",
+    "__bridge_datastoreDelete",
+    "__bridge_datastoreList",
+    "__bridge_sharedDatastoreGet",
+    "__bridge_sharedDatastoreSet",
+    "__bridge_sharedDatastoreDelete",
+    "__bridge_sharedDatastoreList",
+    "__bridge_secretsGet",
+];
+/** The bridges that need no privilege, run wherever QuickJS runs. */
+export const LOCAL_BRIDGE_NAMES = [
+    "__bridge_sleep",
+    "__bridge_randomUUID",
+    "__bridge_randomBytes",
+    "__bridge_parseHTML",
+    "__bridge_parseCSV",
+    "__bridge_parseXML",
+];
+export function isPrivilegedBridgeName(name) {
+    return PRIVILEGED_BRIDGE_NAMES.includes(name);
+}
+/** The privileged bridges for one tool invocation, scoped by its options. */
+export function createPrivilegedHost(options) {
     const { agentId, datastore, sharedDatastore, logTag, secrets, signal, allowedFetchHosts } = options;
-    const register = (name, fn) => registerJsonAsyncFunction(context, runtime, name, fn, signal);
+    const fetchImpl = options.fetchImpl ?? safeFetch;
     const sandboxLog = (options.logger ?? defaultLogger).child({
         module: "sandbox-tool",
         agentId,
         tool: logTag.slice(0, 100),
     });
-    const parserPool = options.parserPool ?? (sharedParserPool ??= createParserWorkerPool());
     // Values fetched via secrets.get() during THIS invocation only — a tool
     // that logs a secret it never fetched has nothing to redact, and one that
     // fetches but doesn't log it costs nothing extra. Fresh per invocation
-    // (installHostFunctions runs once per sandbox context, one per tool call).
-    const fetchedSecretValues = new Set();
+    // (one privileged host per sandbox context, one per tool call).
+    const fetchedSecretValues = new Set(options.redactSecretValues ?? []);
     function redactSecrets(text) {
         let out = text;
         for (const value of fetchedSecretValues) {
@@ -56,17 +86,106 @@ export function installHostFunctions(context, runtime, options) {
         }
         return out;
     }
-    register("__bridge_console", async (argsJson) => {
-        const [level, logArgs] = args(argsJson);
-        const message = redactPii(redactSecrets(boundedJson(logArgs, LOG_BYTES)));
-        if (level === "warn")
-            sandboxLog.warn(message);
-        else if (level === "error")
-            sandboxLog.error(message);
-        else
-            sandboxLog.info(message);
-        return null;
-    });
+    return {
+        async __bridge_console(argsJson) {
+            const [level, logArgs] = args(argsJson);
+            const message = redactPii(redactSecrets(boundedJson(logArgs, LOG_BYTES)));
+            if (level === "warn")
+                sandboxLog.warn(message);
+            else if (level === "error")
+                sandboxLog.error(message);
+            else
+                sandboxLog.info(message);
+            return null;
+        },
+        async __bridge_fetch(argsJson) {
+            const [url, init = {}, secretNames] = args(argsJson);
+            const policy = { ...sandboxFetchPolicy(allowedFetchHosts ?? []), signal };
+            if (secretNames === undefined || (Array.isArray(secretNames) && secretNames.length === 0)) {
+                return fetchImpl(url, init, policy);
+            }
+            // Loaded only here: the brokering code needs packages the native worker image does not ship,
+            // and the worker never runs this bridge (the gateway does).
+            const { brokeredFetch } = await import("./brokered-fetch.js");
+            return brokeredFetch({
+                url,
+                init,
+                secretNames,
+                secrets,
+                fetchImpl,
+                policy,
+                redactFromConsole: (value) => fetchedSecretValues.add(value),
+            });
+        },
+        async __bridge_datastoreGet(argsJson) {
+            const [key] = args(argsJson);
+            boundedString(key, 1024);
+            const value = await datastore.get(agentId, key);
+            return value === undefined ? null : value;
+        },
+        async __bridge_datastoreSet(argsJson) {
+            const [key, value, opts] = args(argsJson);
+            boundedString(key, 1024);
+            await datastore.set(agentId, key, value, opts);
+            return null;
+        },
+        async __bridge_datastoreDelete(argsJson) {
+            const [key] = args(argsJson);
+            boundedString(key, 1024);
+            await datastore.delete(agentId, key);
+            return null;
+        },
+        async __bridge_datastoreList(argsJson) {
+            const [prefix] = args(argsJson);
+            if (prefix !== null)
+                boundedString(prefix, 1024);
+            return datastore.list(agentId, prefix ?? undefined);
+        },
+        async __bridge_sharedDatastoreGet(argsJson) {
+            const [boundName, key] = args(argsJson);
+            boundedString(boundName, 1024);
+            boundedString(key, 1024);
+            const value = await sharedDatastore.get(boundName, key);
+            return value === undefined ? null : value;
+        },
+        async __bridge_sharedDatastoreSet(argsJson) {
+            const [boundName, key, value, opts] = args(argsJson);
+            boundedString(boundName, 1024);
+            boundedString(key, 1024);
+            await sharedDatastore.set(boundName, key, value, opts);
+            return null;
+        },
+        async __bridge_sharedDatastoreDelete(argsJson) {
+            const [boundName, key] = args(argsJson);
+            boundedString(boundName, 1024);
+            boundedString(key, 1024);
+            await sharedDatastore.delete(boundName, key);
+            return null;
+        },
+        async __bridge_sharedDatastoreList(argsJson) {
+            const [boundName, prefix] = args(argsJson);
+            boundedString(boundName, 1024);
+            if (prefix !== null)
+                boundedString(prefix, 1024);
+            return sharedDatastore.list(boundName, prefix ?? undefined);
+        },
+        async __bridge_secretsGet(argsJson) {
+            const [name] = args(argsJson);
+            boundedString(name, 1024);
+            const value = secrets ? await secrets.get(name) : undefined;
+            if (value)
+                fetchedSecretValues.add(value);
+            return value ?? null;
+        },
+    };
+}
+/** Registers the whole sandbox API: the local bridges directly, the privileged ones through `privileged`. */
+export function installSandboxApi(context, runtime, options) {
+    const { privileged, signal } = options;
+    const register = (name, fn) => registerJsonAsyncFunction(context, runtime, name, fn, signal);
+    const parserPool = options.parserPool ?? (sharedParserPool ??= createParserWorkerPool());
+    for (const name of PRIVILEGED_BRIDGE_NAMES)
+        register(name, (argsJson) => privileged[name](argsJson));
     register("__bridge_sleep", async (argsJson) => {
         const [ms] = args(argsJson);
         if (!Number.isFinite(ms) || ms < 0 || ms > WALL_TIME_LIMIT_MS)
@@ -83,70 +202,6 @@ export function installHostFunctions(context, runtime, options) {
             throw new Error("random_bytes_limit");
         return Array.from(nodeRandomBytes(length));
     });
-    register("__bridge_fetch", async (argsJson) => {
-        const [url, init] = args(argsJson);
-        return safeFetch(url, init, { ...sandboxFetchPolicy(allowedFetchHosts ?? []), signal });
-    });
-    register("__bridge_datastoreGet", async (argsJson) => {
-        const [key] = args(argsJson);
-        boundedString(key, 1024);
-        const value = await datastore.get(agentId, key);
-        return value === undefined ? null : value;
-    });
-    register("__bridge_datastoreSet", async (argsJson) => {
-        const [key, value, opts] = args(argsJson);
-        boundedString(key, 1024);
-        await datastore.set(agentId, key, value, opts);
-        return null;
-    });
-    register("__bridge_datastoreDelete", async (argsJson) => {
-        const [key] = args(argsJson);
-        boundedString(key, 1024);
-        await datastore.delete(agentId, key);
-        return null;
-    });
-    register("__bridge_datastoreList", async (argsJson) => {
-        const [prefix] = args(argsJson);
-        if (prefix !== null)
-            boundedString(prefix, 1024);
-        return datastore.list(agentId, prefix ?? undefined);
-    });
-    register("__bridge_sharedDatastoreGet", async (argsJson) => {
-        const [boundName, key] = args(argsJson);
-        boundedString(boundName, 1024);
-        boundedString(key, 1024);
-        const value = await sharedDatastore.get(boundName, key);
-        return value === undefined ? null : value;
-    });
-    register("__bridge_sharedDatastoreSet", async (argsJson) => {
-        const [boundName, key, value, opts] = args(argsJson);
-        boundedString(boundName, 1024);
-        boundedString(key, 1024);
-        await sharedDatastore.set(boundName, key, value, opts);
-        return null;
-    });
-    register("__bridge_sharedDatastoreDelete", async (argsJson) => {
-        const [boundName, key] = args(argsJson);
-        boundedString(boundName, 1024);
-        boundedString(key, 1024);
-        await sharedDatastore.delete(boundName, key);
-        return null;
-    });
-    register("__bridge_sharedDatastoreList", async (argsJson) => {
-        const [boundName, prefix] = args(argsJson);
-        boundedString(boundName, 1024);
-        if (prefix !== null)
-            boundedString(prefix, 1024);
-        return sharedDatastore.list(boundName, prefix ?? undefined);
-    });
-    register("__bridge_secretsGet", async (argsJson) => {
-        const [name] = args(argsJson);
-        boundedString(name, 1024);
-        const value = secrets ? await secrets.get(name) : undefined;
-        if (value)
-            fetchedSecretValues.add(value);
-        return value ?? null;
-    });
     // The actual node-html-parser/papaparse/fast-xml-parser calls run in a
     // disposable worker thread (see ./parser-worker/pool.ts) — this host
     // process runs fully attacker-controlled (but size-capped) input through
@@ -173,3 +228,12 @@ export function installHostFunctions(context, runtime, options) {
         return parserPool.run("xml", { xml, xmlOptions }, signal);
     });
 }
+/** The in-process sandbox API for one tool invocation: privileged bridges served right here. */
+export function installHostFunctions(context, runtime, options) {
+    const { parserPool, ...privilegedOptions } = options;
+    installSandboxApi(context, runtime, {
+        privileged: createPrivilegedHost(privilegedOptions),
+        signal: options.signal,
+        parserPool,
+    });
+}

package/dist/sandbox/prelude.js

@@ -340,8 +340,12 @@ globalThis.fetch = async (url, init) => {
     if (body instanceof Blob) body = await body.text();
     else body = JSON.stringify(body);
   }
+  // Brokered secrets: named here, placed by the host, never visible to this code. Anything but a list
+  // goes through unchanged, so the host refuses it rather than fetching without the secret.
+  const secretNames =
+    !init || init.secrets === undefined ? [] : Array.isArray(init.secrets) ? init.secrets.map(String) : init.secrets;
   const raw = await __bridge_fetch(
-    JSON.stringify([String(url), { method: (init && init.method) || "GET", headers: (init && init.headers) || {}, body }]),
+    JSON.stringify([String(url), { method: (init && init.method) || "GET", headers: (init && init.headers) || {}, body }, secretNames]),
   );
   const data = JSON.parse(raw);
   const headersLower = {};
@@ -380,6 +384,8 @@ globalThis.sharedDatastore = {
 };
 
 // ---- secrets (bridged; decrypt-on-demand, scoped per agent by the host) ----
+// A brokered secret is never readable: secrets.get throws secret_brokered for
+// it; name it in fetch(url, { secrets: [name] }) instead.
 
 globalThis.secrets = {
   get: async (name) => {

package/dist/sandbox/run-in-sandbox.d.ts

@@ -7,11 +7,14 @@
  * exhaustion, or non-serializable return all fail *that call* cleanly
  * instead of crashing the run or the host process.
  */
+import { type PrivilegedHost } from "./host-functions.js";
+import type { ParserWorkerPool } from "./parser-worker/pool.js";
 import { type SandboxLimits, type SandboxResult } from "./eval-core.js";
 import type { Datastore } from "../providers/datastore/types.js";
 import type { SecretsAccessor } from "../core/secrets.js";
 import type { SharedDatastoreAccessor } from "../core/datastores.js";
 import type { Logger } from "../core/logger.js";
+import type { safeFetch } from "./safe-fetch.js";
 export type { SandboxErrorKind, SandboxLimits, SandboxResult } from "./eval-core.js";
 export interface SandboxInvocation {
     /** The tool body source. Runs as an async function body receiving `params`. */
@@ -30,5 +33,21 @@ export interface SandboxInvocation {
     logger?: Logger;
     /** Forwarded to installHostFunctions — which hosts this tool attachment may fetch. Omitted/empty = no outbound fetch at all; a literal "*" element lifts the restriction. */
     allowedFetchHosts?: string[];
+    /** Overrides the sandbox's outbound network call — tests only. */
+    fetchImpl?: typeof safeFetch;
 }
+/** Tool code plus whichever privileged host serves its bridges (in-process, or a gateway). */
+export interface ToolCodeInvocation {
+    /** The tool body source. Runs as an async function body receiving `params`. */
+    code: string;
+    params: unknown;
+    limits?: Partial<SandboxLimits>;
+    /** Built once per invocation, with that invocation's abort signal (fetch needs it). */
+    privileged: (signal: AbortSignal) => PrivilegedHost;
+    parserPool?: ParserWorkerPool;
+}
+/** Evaluates one tool body in a fresh QuickJS context against the given privileged host. */
+export declare function runToolCode(invocation: ToolCodeInvocation): Promise<SandboxResult>;
+/** The in-process privileged host for a sandbox invocation. */
+export declare function privilegedHostFor(invocation: SandboxInvocation, signal: AbortSignal): PrivilegedHost;
 export declare function runInSandbox(invocation: SandboxInvocation): Promise<SandboxResult>;

package/dist/sandbox/run-in-sandbox.js

@@ -7,12 +7,13 @@
  * exhaustion, or non-serializable return all fail *that call* cleanly
  * instead of crashing the run or the host process.
  */
-import { installHostFunctions } from "./host-functions.js";
+import { createPrivilegedHost, installSandboxApi } from "./host-functions.js";
 import { SANDBOX_PRELUDE } from "./prelude.js";
 import { evalToJson, NON_SERIALIZABLE_MARKER } from "./eval-core.js";
 import { boundedJson, boundedString } from "./bounded-json.js";
 import { BRIDGE_INPUT_BYTES } from "./limits.js";
-export async function runInSandbox(invocation) {
+/** Evaluates one tool body in a fresh QuickJS context against the given privileged host. */
+export async function runToolCode(invocation) {
     let params;
     try {
         boundedString(invocation.code, BRIDGE_INPUT_BYTES);
@@ -39,15 +40,32 @@ export async function runInSandbox(invocation) {
   }
 })()`;
     return evalToJson(code, invocation.limits, (context, runtime, signal) => {
-        installHostFunctions(context, runtime, {
-            agentId: invocation.agentId,
-            datastore: invocation.datastore,
-            sharedDatastore: invocation.sharedDatastore,
-            logTag: invocation.toolName,
-            secrets: invocation.secrets,
-            logger: invocation.logger,
-            allowedFetchHosts: invocation.allowedFetchHosts,
+        installSandboxApi(context, runtime, {
+            privileged: invocation.privileged(signal),
             signal,
+            parserPool: invocation.parserPool,
         });
     });
 }
+/** The in-process privileged host for a sandbox invocation. */
+export function privilegedHostFor(invocation, signal) {
+    return createPrivilegedHost({
+        agentId: invocation.agentId,
+        datastore: invocation.datastore,
+        sharedDatastore: invocation.sharedDatastore,
+        logTag: invocation.toolName,
+        secrets: invocation.secrets,
+        logger: invocation.logger,
+        allowedFetchHosts: invocation.allowedFetchHosts,
+        fetchImpl: invocation.fetchImpl,
+        signal,
+    });
+}
+export async function runInSandbox(invocation) {
+    return runToolCode({
+        code: invocation.code,
+        params: invocation.params,
+        limits: invocation.limits,
+        privileged: (signal) => privilegedHostFor(invocation, signal),
+    });
+}

package/dist/sandbox/safe-fetch.d.ts

@@ -12,6 +12,8 @@ export declare function requestPinned(destination: Destination, init: SafeFetchI
 export interface SafeFetchOptions extends FetchPolicyOptions {
     signal?: AbortSignal;
     connect?: typeof requestPinned;
+    /** False: a 3xx is returned to the caller as-is (brokered requests re-check every hop themselves). */
+    followRedirects?: boolean;
 }
 export declare function safeFetch(input: string, init?: SafeFetchInit, options?: SafeFetchOptions): Promise<{
     ok: boolean;

package/dist/sandbox/safe-fetch.js

@@ -60,7 +60,9 @@ export async function safeFetch(input, init = {}, options = {}) {
             signal.throwIfAborted();
             response = await (options.connect ?? requestPinned)(destination, { method, headers, body }, signal);
             const status = response.statusCode ?? 0;
-            if ([301, 302, 303, 307, 308].includes(status) && response.headers.location) {
+            if (options.followRedirects !== false &&
+                [301, 302, 303, 307, 308].includes(status) &&
+                response.headers.location) {
                 response.destroy();
                 if (hop >= MAX_REDIRECTS)
                     throw new Error("fetch_redirect_limit");

package/dist/sandbox/secret-broker-sigv4.d.ts

@@ -0,0 +1,2 @@
+import type { BrokeredSecret, BrokerRequest } from "./secret-broker.js";
+export declare function signSigV4(request: BrokerRequest, secret: BrokeredSecret, now?: Date): Promise<BrokerRequest>;

package/dist/sandbox/secret-broker-sigv4.js

@@ -0,0 +1,49 @@
+/** AWS SigV4 for a brokered secret, using AWS's own signer. The tool never sees the keys. */
+import { SignatureV4 } from "@smithy/signature-v4";
+import { Sha256 } from "@aws-crypto/sha256-js";
+import { parseSigV4Value } from "../core/secret-broker-config.js";
+const SIGNER_HEADERS = ["authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"];
+/** Group query params by key so repeated keys survive (Object.fromEntries would drop them). */
+function queryOf(url) {
+    const query = {};
+    for (const key of new Set(url.searchParams.keys())) {
+        const all = url.searchParams.getAll(key);
+        query[key] = all.length === 1 ? all[0] : all;
+    }
+    return query;
+}
+export async function signSigV4(request, secret, now = new Date()) {
+    if (secret.broker.placement.kind !== "aws-sigv4") {
+        throw new Error("signSigV4 needs an aws-sigv4 secret");
+    }
+    const headers = Object.fromEntries(Object.entries(request.headers).map(([k, v]) => [k.toLowerCase(), v]));
+    for (const h of SIGNER_HEADERS) {
+        if (h in headers) {
+            throw new Error(`secret_broker_conflict: header "${h}" is set by the SigV4 signer for "${secret.name}"`);
+        }
+    }
+    // safeFetch replaces accept-encoding after signing; a signed one would no longer match.
+    delete headers["accept-encoding"];
+    const { region, service } = secret.broker.placement;
+    const signer = new SignatureV4({
+        credentials: parseSigV4Value(secret.value),
+        region,
+        service,
+        sha256: Sha256,
+        applyChecksum: service === "s3",
+        uriEscapePath: service !== "s3",
+    });
+    const url = new URL(request.url);
+    const signed = await signer.sign({
+        method: request.method,
+        protocol: url.protocol,
+        hostname: url.hostname,
+        path: url.pathname,
+        query: queryOf(url),
+        headers: { ...headers, host: url.host },
+        body: request.body,
+    }, { signingDate: now });
+    const out = Object.fromEntries(Object.entries(signed.headers).map(([k, v]) => [k.toLowerCase(), String(v)]));
+    delete out.host; // safeFetch forbids setting Host; Node sets the same value from the URL.
+    return { ...request, headers: out };
+}

package/dist/sandbox/secret-broker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Brokered secrets at request time: check the destination, place each value where its
+ * owner said, and scrub values from the response. Pure — the privileged host
+ * (host-functions.ts) does the I/O. SigV4 signing is in secret-broker-sigv4.ts.
+ */
+import { type SecretBrokerConfig } from "../core/secret-broker-config.js";
+export interface BrokeredSecret {
+    name: string;
+    value: string;
+    broker: SecretBrokerConfig;
+}
+export interface BrokerRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export declare function checkBrokerDestination(url: string, secrets: readonly BrokeredSecret[]): void;
+export declare function applyBrokerPlacements(request: BrokerRequest, secrets: readonly BrokeredSecret[]): BrokerRequest;
+export declare function brokerScrubValues(secrets: readonly BrokeredSecret[]): string[];
+/**
+ * The strings console output must not show for one secret the tool may use: its value and, for a
+ * brokered SigV4 secret, the secret key and session token alone. A value that won't parse adds nothing.
+ */
+export declare function consoleRedactionValues(entry: {
+    value: string;
+    broker: SecretBrokerConfig | null;
+}): string[];
+export declare function scrubBrokeredResponse<T extends {
+    headers: Record<string, string>;
+    bodyBase64: string;
+    url: string;
+    statusText?: string;
+}>(response: T, values: readonly string[]): T;

package/dist/sandbox/secret-broker.js

@@ -0,0 +1,162 @@
+/**
+ * Brokered secrets at request time: check the destination, place each value where its
+ * owner said, and scrub values from the response. Pure — the privileged host
+ * (host-functions.ts) does the I/O. SigV4 signing is in secret-broker-sigv4.ts.
+ */
+import { parseSigV4Value } from "../core/secret-broker-config.js";
+const REDACTED = "[REDACTED]";
+function deny(reason) {
+    throw new Error(`secret_broker_destination_denied: ${reason}`);
+}
+function conflict(reason) {
+    throw new Error(`secret_broker_conflict: ${reason}`);
+}
+export function checkBrokerDestination(url, secrets) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        deny("invalid URL");
+    }
+    if (parsed.protocol !== "https:")
+        deny("brokered secrets are only sent over https");
+    if (parsed.port !== "")
+        deny("brokered secrets are only sent to the default https port");
+    const host = parsed.hostname.toLowerCase();
+    for (const s of secrets) {
+        if (!s.broker.hosts.includes(host))
+            deny(`"${s.name}" may not be sent to ${host}`);
+        const prefixes = s.broker.pathPrefixes ?? [];
+        if (prefixes.length && !prefixes.some((p) => parsed.pathname.startsWith(p))) {
+            deny(`"${s.name}" may not be sent to path ${parsed.pathname}`);
+        }
+        // An encoded slash or backslash may be decoded upstream into a separator, escaping the prefix.
+        if (prefixes.length && /%2f|%5c/i.test(parsed.pathname)) {
+            deny(`"${s.name}" may not be sent to a path with an encoded separator`);
+        }
+    }
+}
+function contentType(headers) {
+    return (headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+}
+export function applyBrokerPlacements(request, secrets) {
+    const headers = Object.fromEntries(Object.entries(request.headers).map(([k, v]) => [k.toLowerCase(), v]));
+    const url = new URL(request.url);
+    let body = request.body;
+    const placed = new Set();
+    for (const s of secrets) {
+        const p = s.broker.placement;
+        if (p.kind === "header") {
+            const key = p.name.toLowerCase();
+            if (key in headers || placed.has(`h:${key}`))
+                conflict(`header "${p.name}" is set by the broker for "${s.name}"`);
+            // A replacer function, not a string: "$$", "$&", "$'" in a value are literal, not patterns.
+            headers[key] = p.format.replace("{value}", () => s.value);
+            placed.add(`h:${key}`);
+        }
+        else if (p.kind === "query") {
+            if (url.searchParams.has(p.name) || placed.has(`q:${p.name}`))
+                conflict(`query parameter "${p.name}" is set by the broker for "${s.name}"`);
+            url.searchParams.append(p.name, s.value);
+            placed.add(`q:${p.name}`);
+        }
+        else if (p.kind === "body") {
+            if (placed.has(`b:${p.field}`))
+                conflict(`body field "${p.field}" is set by the broker for "${s.name}"`);
+            body = placeBodyField(headers, body, p.field, s);
+            placed.add(`b:${p.field}`);
+        }
+    }
+    return { ...request, url: url.href, headers, body };
+}
+function placeBodyField(headers, body, field, s) {
+    const type = contentType(headers);
+    if (body === undefined)
+        throw new Error(`secret_broker_body_invalid: "${s.name}" is placed in the body, but the request has none`);
+    if (type === "application/json" || type.endsWith("+json")) {
+        let json;
+        try {
+            json = JSON.parse(body);
+        }
+        catch {
+            throw new Error("secret_broker_body_invalid: the body is not valid JSON");
+        }
+        if (json === null || typeof json !== "object" || Array.isArray(json)) {
+            throw new Error("secret_broker_body_invalid: a brokered JSON body must be an object");
+        }
+        if (Object.hasOwn(json, field))
+            conflict(`body field "${field}" is set by the broker for "${s.name}"`);
+        return JSON.stringify({ ...json, [field]: s.value });
+    }
+    if (type === "application/x-www-form-urlencoded") {
+        const form = new URLSearchParams(body);
+        if (form.has(field))
+            conflict(`body field "${field}" is set by the broker for "${s.name}"`);
+        form.append(field, s.value);
+        return form.toString();
+    }
+    throw new Error("secret_broker_body_invalid: body placement needs a JSON-object or form-encoded body");
+}
+export function brokerScrubValues(secrets) {
+    return secrets.flatMap((s) => {
+        if (s.broker.placement.kind !== "aws-sigv4")
+            return [s.value];
+        const creds = parseSigV4Value(s.value);
+        return [creds.secretAccessKey, ...(creds.sessionToken ? [creds.sessionToken] : [])];
+    });
+}
+/**
+ * The strings console output must not show for one secret the tool may use: its value and, for a
+ * brokered SigV4 secret, the secret key and session token alone. A value that won't parse adds nothing.
+ */
+export function consoleRedactionValues(entry) {
+    if (!entry.broker)
+        return [entry.value];
+    try {
+        return [entry.value, ...brokerScrubValues([{ name: "", value: entry.value, broker: entry.broker }])].filter((v, i, all) => all.indexOf(v) === i);
+    }
+    catch {
+        return [entry.value];
+    }
+}
+function encodedForms(value) {
+    const buf = Buffer.from(value, "utf8");
+    // Query placement goes through URLSearchParams, which encodes ~ ! ' ( ) differently and space as "+",
+    // so both percent-encodings are scrubbed, each also in lowercase-hex form (a response may echo either).
+    const percent = [encodeURIComponent(value), new URLSearchParams({ k: value }).toString().slice("k=".length)];
+    const lowerHex = percent.map((f) => f.replace(/%[0-9A-F]{2}/g, (m) => m.toLowerCase()));
+    return [
+        ...new Set([
+            value,
+            buf.toString("base64"),
+            buf.toString("base64").replace(/=+$/, ""),
+            buf.toString("base64url"),
+            ...percent,
+            ...lowerHex,
+        ]),
+    ]
+        .filter((form) => form.length >= 6)
+        .sort((a, b) => b.length - a.length);
+}
+function scrubText(text, forms) {
+    let out = text;
+    for (const form of forms)
+        out = out.split(form).join(REDACTED);
+    return out;
+}
+export function scrubBrokeredResponse(response, values) {
+    // Longest first across every value: a value that prefixes another must not split the longer one.
+    const forms = [...new Set(values.flatMap(encodedForms))].sort((a, b) => b.length - a.length);
+    const body = Buffer.from(response.bodyBase64, "base64").toString("latin1");
+    // latin1 is byte-preserving, so scrubbing never corrupts non-UTF-8 bodies; every encoded form is ASCII,
+    // and a UTF-8 plaintext's bytes appear verbatim in latin1 as the latin1 decode of its UTF-8 bytes.
+    const latinForms = forms.map((f) => Buffer.from(f, "utf8").toString("latin1"));
+    return {
+        ...response,
+        url: scrubText(response.url, forms),
+        ...(response.statusText === undefined ? {} : { statusText: scrubText(response.statusText, forms) }),
+        headers: Object.fromEntries(Object.entries(response.headers).map(([k, v]) => [k, scrubText(v, forms)])),
+        bodyBase64: Buffer.from(scrubText(body, latinForms), "latin1").toString("base64"),
+    };
+}

package/dist/sandbox/user-tool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One user-tool call, end to end: parse the model's arguments, validate them
+ * against the tool's Zod schema (in its own sandbox), run the body, and format
+ * the result string fed back to the model. Never throws — every failure is a
+ * JSON error result. Worker-safe: it touches no database or provider, only the
+ * privileged host it is given, so the native sandbox worker runs it as is.
+ */
+import type { PrivilegedHost } from "./host-functions.js";
+import type { SandboxLimits } from "./eval-core.js";
+export interface UserToolDefinition {
+    code: string;
+    paramsZod: string;
+}
+export declare function runUserToolCall(tool: UserToolDefinition, argsJson: string, privileged: (signal: AbortSignal) => PrivilegedHost, limits?: Partial<SandboxLimits>): Promise<string>;