@wardby/cli 0.1.0

package/dist/sandbox/bounded-json.js

@@ -0,0 +1,36 @@
+export function boundedJson(value, maxBytes) {
+    const seen = new Set();
+    let budget = maxBytes;
+    let nodes = 0;
+    function visit(v, depth) {
+        if (++nodes > 100_000 || depth > 64)
+            throw new Error("bridge_structure_limit");
+        if (typeof v === "string")
+            budget -= Buffer.byteLength(v) + 2;
+        else if (v && typeof v === "object") {
+            if (seen.has(v))
+                throw new Error("bridge_cycle");
+            seen.add(v);
+            for (const [key, child] of Object.entries(v)) {
+                budget -= Buffer.byteLength(key) + 4;
+                if (budget < 0)
+                    throw new Error("bridge_size_limit");
+                visit(child, depth + 1);
+            }
+            seen.delete(v);
+        }
+        else
+            budget -= 8;
+        if (budget < 0)
+            throw new Error("bridge_size_limit");
+    }
+    visit(value, 0);
+    const json = JSON.stringify(value ?? null);
+    if (Buffer.byteLength(json) > maxBytes)
+        throw new Error("bridge_size_limit");
+    return json;
+}
+export function boundedString(value, maxBytes) {
+    if (typeof value !== "string" || Buffer.byteLength(value) > maxBytes)
+        throw new Error("bridge_input_limit");
+}

package/dist/sandbox/bridge.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The one generic mechanism for exposing a host-side async capability to
+ * sandboxed code. Every host function (fetch, datastore, parsers, sleep,
+ * console) is registered through this — centralizing the QuickJS handle
+ * lifecycle (a real leak/crash risk if scattered across many call sites; a
+ * spike confirmed both proper disposal and rejection propagation with
+ * this exact shape) in one place instead of repeating it per capability.
+ *
+ * Values cross the boundary JSON-serialized: the registered function takes
+ * one JSON-string argument and the sandbox-side prelude (prelude.ts)
+ * JSON-parses the JSON-string result. A thrown/rejected `impl` becomes a
+ * real catchable exception inside the sandbox (QuickJS promise rejection).
+ */
+import type { QuickJSContext, QuickJSRuntime } from "quickjs-emscripten";
+export declare function registerJsonAsyncFunction(context: QuickJSContext, runtime: QuickJSRuntime, name: string, impl: (argsJson: string) => Promise<unknown>, signal?: AbortSignal): void;

package/dist/sandbox/bridge.js

@@ -0,0 +1,78 @@
+/**
+ * The one generic mechanism for exposing a host-side async capability to
+ * sandboxed code. Every host function (fetch, datastore, parsers, sleep,
+ * console) is registered through this — centralizing the QuickJS handle
+ * lifecycle (a real leak/crash risk if scattered across many call sites; a
+ * spike confirmed both proper disposal and rejection propagation with
+ * this exact shape) in one place instead of repeating it per capability.
+ *
+ * Values cross the boundary JSON-serialized: the registered function takes
+ * one JSON-string argument and the sandbox-side prelude (prelude.ts)
+ * JSON-parses the JSON-string result. A thrown/rejected `impl` becomes a
+ * real catchable exception inside the sandbox (QuickJS promise rejection).
+ */
+import { boundedJson } from "./bounded-json.js";
+import { BRIDGE_INPUT_BYTES, BRIDGE_RESULT_BYTES, MAX_HOST_CALLS, MAX_PENDING_HOST_CALLS } from "./limits.js";
+const budgets = new WeakMap();
+export function registerJsonAsyncFunction(context, runtime, name, impl, signal) {
+    const fnHandle = context.newFunction(name, (argHandle) => {
+        const budget = budgets.get(runtime) ?? { calls: 0, pending: 0 };
+        budgets.set(runtime, budget);
+        if (signal?.aborted || ++budget.calls > MAX_HOST_CALLS || budget.pending >= MAX_PENDING_HOST_CALLS)
+            return { error: context.newError("bridge_call_limit") };
+        if (!argHandle || context.typeof(argHandle) !== "string")
+            return { error: context.newError("bridge_input_invalid") };
+        const lengthHandle = context.getProp(argHandle, "length");
+        const length = context.getNumber(lengthHandle);
+        lengthHandle.dispose();
+        if (length > BRIDGE_INPUT_BYTES)
+            return { error: context.newError("bridge_input_limit") };
+        const argsJson = context.getString(argHandle);
+        if (Buffer.byteLength(argsJson) > BRIDGE_INPUT_BYTES)
+            return { error: context.newError("bridge_input_limit") };
+        const deferred = context.newPromise();
+        budget.pending++;
+        const abort = () => {
+            if (deferred.alive)
+                deferred.dispose();
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        Promise.resolve()
+            .then(() => {
+            signal?.throwIfAborted();
+            return impl(argsJson);
+        })
+            .then((value) => {
+            if (!deferred.alive)
+                return;
+            const resultHandle = context.newString(boundedJson(value, BRIDGE_RESULT_BYTES));
+            deferred.resolve(resultHandle);
+            resultHandle.dispose();
+        })
+            .catch((err) => {
+            if (!deferred.alive)
+                return;
+            const message = err instanceof Error ? err.message.slice(0, 1024) : "Host function failed.";
+            const errorHandle = context.newError(message);
+            deferred.reject(errorHandle);
+            errorHandle.dispose();
+        })
+            .finally(() => {
+            budget.pending--;
+            signal?.removeEventListener("abort", abort);
+        });
+        deferred.settled
+            .then(() => {
+            if (runtime.alive && !signal?.aborted)
+                runtime.executePendingJobs();
+        })
+            .finally(() => {
+            if (deferred.alive)
+                deferred.dispose();
+        })
+            .catch(() => { });
+        return deferred.handle;
+    });
+    context.setProp(context.global, name, fnHandle);
+    fnHandle.dispose();
+}

package/dist/sandbox/eval-core.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The reusable core: create a fresh runtime + context with resource limits,
+ * eval a script that resolves to a JSON string, marshal the result,
+ * dispose. Shared by `run-in-sandbox.ts` (installs the full host API for a
+ * tool invocation) and `zod-params.ts` (installs nothing — schema
+ * compilation/validation is pure computation, no host I/O at all).
+ */
+import type { QuickJSContext, QuickJSRuntime } from "quickjs-emscripten";
+export type SandboxErrorKind = "thrown" | "timeout" | "memory" | "cpu" | "non_serializable";
+export type SandboxResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    errorKind: SandboxErrorKind;
+    errorMessage: string;
+};
+export interface SandboxLimits {
+    memoryLimitBytes: number;
+    maxInterruptChecks: number;
+    wallTimeLimitMs: number;
+    maxStackSizeBytes: number;
+}
+export declare const DEFAULT_SANDBOX_LIMITS: SandboxLimits;
+/**
+ * The script must evaluate to a JSON-string-yielding value (a Promise of a
+ * string, per the calling convention both `run-in-sandbox.ts` and
+ * `zod-params.ts` use: wrap the real payload in a final `JSON.stringify`
+ * inside the sandbox so a serialization failure is itself a catchable
+ * sandbox exception, not a host-side surprise).
+ */
+export declare const NON_SERIALIZABLE_MARKER = "__wardby_non_serializable__:";
+export declare function classifyEvalError(dumped: {
+    name?: string;
+    message?: string;
+}): SandboxResult;
+export declare function evalToJson(code: string, limitsOverride: Partial<SandboxLimits> | undefined, installExtras: (context: QuickJSContext, runtime: QuickJSRuntime, signal: AbortSignal) => void): Promise<SandboxResult>;

package/dist/sandbox/eval-core.js

@@ -0,0 +1,159 @@
+/**
+ * The reusable core: create a fresh runtime + context with resource limits,
+ * eval a script that resolves to a JSON string, marshal the result,
+ * dispose. Shared by `run-in-sandbox.ts` (installs the full host API for a
+ * tool invocation) and `zod-params.ts` (installs nothing — schema
+ * compilation/validation is pure computation, no host I/O at all).
+ */
+import { getQuickJsModule } from "./quickjs-module.js";
+import { MAX_INTERRUPT_CHECKS, MAX_STACK_SIZE_BYTES, MEMORY_LIMIT_BYTES, WALL_TIME_LIMIT_MS } from "./limits.js";
+import { BRIDGE_RESULT_BYTES } from "./limits.js";
+export const DEFAULT_SANDBOX_LIMITS = {
+    memoryLimitBytes: MEMORY_LIMIT_BYTES,
+    maxInterruptChecks: MAX_INTERRUPT_CHECKS,
+    wallTimeLimitMs: WALL_TIME_LIMIT_MS,
+    maxStackSizeBytes: MAX_STACK_SIZE_BYTES,
+};
+/**
+ * The script must evaluate to a JSON-string-yielding value (a Promise of a
+ * string, per the calling convention both `run-in-sandbox.ts` and
+ * `zod-params.ts` use: wrap the real payload in a final `JSON.stringify`
+ * inside the sandbox so a serialization failure is itself a catchable
+ * sandbox exception, not a host-side surprise).
+ */
+export const NON_SERIALIZABLE_MARKER = "__wardby_non_serializable__:";
+function boundedError(context, handle) {
+    const result = {};
+    for (const key of ["name", "message"]) {
+        const value = context.getProp(handle, key);
+        if (context.typeof(value) === "string") {
+            const size = context.getProp(value, "length");
+            const length = context.getNumber(size);
+            size.dispose();
+            result[key] = length <= 4096 ? context.getString(value) : "Sandbox error text exceeded limit.";
+        }
+        value.dispose();
+    }
+    return result;
+}
+export function classifyEvalError(dumped) {
+    if (dumped.name === "InternalError" && dumped.message === "interrupted") {
+        return { ok: false, errorKind: "cpu", errorMessage: "Exceeded the CPU/instruction budget." };
+    }
+    if (dumped.name === "InternalError" && dumped.message === "out of memory") {
+        return { ok: false, errorKind: "memory", errorMessage: "Exceeded the sandbox memory limit." };
+    }
+    if (dumped.message?.startsWith(NON_SERIALIZABLE_MARKER)) {
+        return {
+            ok: false,
+            errorKind: "non_serializable",
+            errorMessage: `Returned a value that could not be JSON-serialized: ${dumped.message.slice(NON_SERIALIZABLE_MARKER.length)}`,
+        };
+    }
+    return {
+        ok: false,
+        errorKind: "thrown",
+        errorMessage: dumped.message ? `${dumped.name ?? "Error"}: ${dumped.message}` : JSON.stringify(dumped),
+    };
+}
+export async function evalToJson(code, limitsOverride, installExtras) {
+    const limits = { ...DEFAULT_SANDBOX_LIMITS, ...limitsOverride };
+    const controller = new AbortController();
+    let timer;
+    const deadline = Date.now() + limits.wallTimeLimitMs;
+    const qjsModule = await getQuickJsModule();
+    const runtime = qjsModule.newRuntime();
+    runtime.setMemoryLimit(limits.memoryLimitBytes);
+    runtime.setMaxStackSize(limits.maxStackSizeBytes);
+    let steps = 0;
+    runtime.setInterruptHandler(() => {
+        steps += 1;
+        return steps > limits.maxInterruptChecks || Date.now() >= deadline;
+    });
+    const context = runtime.newContext();
+    let disposed = false;
+    const disposeAll = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        // Best-effort: if the wall-time race below abandons a still-running
+        // evaluation, teardown may not be pristine. Never let it crash the host.
+        try {
+            context.dispose();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            runtime.dispose();
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    try {
+        installExtras(context, runtime, controller.signal);
+        const runPromise = (async () => {
+            const evalResult = context.evalCode(code);
+            if (evalResult.error) {
+                const dumped = boundedError(context, evalResult.error);
+                evalResult.error.dispose();
+                return classifyEvalError(dumped);
+            }
+            const settledPromise = context.resolvePromise(evalResult.value);
+            evalResult.value.dispose();
+            runtime.executePendingJobs();
+            const settled = await settledPromise;
+            if (settled.error) {
+                const dumped = boundedError(context, settled.error);
+                settled.error.dispose();
+                return classifyEvalError(dumped);
+            }
+            if (context.typeof(settled.value) !== "string") {
+                settled.value.dispose();
+                throw new Error("bridge_result_invalid");
+            }
+            const lengthHandle = context.getProp(settled.value, "length");
+            const length = context.getNumber(lengthHandle);
+            lengthHandle.dispose();
+            if (length > BRIDGE_RESULT_BYTES) {
+                settled.value.dispose();
+                throw new Error("bridge_result_limit");
+            }
+            const raw = context.getString(settled.value);
+            settled.value.dispose();
+            if (Buffer.byteLength(raw) > BRIDGE_RESULT_BYTES)
+                throw new Error("bridge_result_limit");
+            try {
+                return { ok: true, value: JSON.parse(raw) };
+            }
+            catch {
+                return {
+                    ok: false,
+                    errorKind: "non_serializable",
+                    errorMessage: "Returned a value that could not be JSON-serialized.",
+                };
+            }
+        })();
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({
+                ok: false,
+                errorKind: "timeout",
+                errorMessage: `Exceeded the ${limits.wallTimeLimitMs}ms wall-time limit.`,
+            }), limits.wallTimeLimitMs);
+        });
+        return await Promise.race([runPromise, timeoutPromise]);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            errorKind: "thrown",
+            errorMessage: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        disposeAll();
+    }
+}

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

@@ -0,0 +1,24 @@
+export type ResolvedAddress = {
+    address: string;
+    family: number;
+};
+export type Resolver = (hostname: string) => Promise<ResolvedAddress[]>;
+export interface FetchPolicyOptions {
+    allowedHosts?: string[];
+    allowPrivateHosts?: boolean;
+    resolve?: Resolver;
+    restrictToAllowedHosts?: boolean;
+}
+export declare class FetchPolicyError extends Error {
+    constructor();
+}
+export declare function isGlobalAddress(address: string): boolean;
+export declare function normalizeHost(host: string): string;
+export declare function parseAllowedHosts(value: string | undefined): string[];
+export declare function resolveDestination(urlString: string, options?: FetchPolicyOptions): Promise<{
+    url: URL;
+    hostname: string;
+    address: string;
+    family: number;
+}>;
+export declare function assertFetchDestinationAllowed(url: string, options?: FetchPolicyOptions): Promise<void>;

package/dist/sandbox/fetch-policy.js

@@ -0,0 +1,96 @@
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+export class FetchPolicyError extends Error {
+    constructor() {
+        super("fetch_destination_blocked");
+    }
+}
+const blockedV4 = [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+];
+function v4(ip) {
+    return ip.split(".").reduce((a, b) => (a << 8) + Number(b), 0) >>> 0;
+}
+function v6(ip) {
+    const [left, right] = ip.split("::");
+    const a = left ? left.split(":") : [];
+    const b = right ? right.split(":") : [];
+    const groups = ip.includes("::") ? [...a, ...new Array(8 - a.length - b.length).fill("0"), ...b] : a;
+    return groups.reduce((n, g) => (n << 16n) + BigInt("0x" + g), 0n);
+}
+export function isGlobalAddress(address) {
+    if (isIP(address) === 4)
+        return !blockedV4.some(([net, prefix]) => v4(address) >>> (32 - prefix) === v4(net) >>> (32 - prefix));
+    if (isIP(address) !== 6)
+        return false;
+    const normalized = new URL("http://[" + address + "]").hostname.slice(1, -1);
+    const n = v6(normalized);
+    // Conservative global-unicast subset; exclude transition, protocol, and documentation space.
+    return (n >> 125n === 1n &&
+        ![
+            ["2001::", 23],
+            ["2001:db8::", 32],
+            ["2002::", 16],
+            ["3fff::", 20],
+        ].some(([net, prefix]) => {
+            const shift = 128n - BigInt(prefix);
+            return n >> shift === v6(net) >> shift;
+        }));
+}
+export function normalizeHost(host) {
+    if (!host || /[\s*/@?#\\]/.test(host))
+        throw new FetchPolicyError();
+    const value = host.startsWith("[") ? host.slice(1, -1) : host;
+    if (isIP(value))
+        return new URL(isIP(value) === 6 ? "http://[" + value + "]" : "http://" + value).hostname
+            .replace(/^\[|\]$/g, "")
+            .toLowerCase();
+    if (host.includes(":"))
+        throw new FetchPolicyError();
+    return new URL("http://" + host).hostname.toLowerCase().replace(/\.$/, "");
+}
+export function parseAllowedHosts(value) {
+    return value === undefined || value === "" ? [] : value.split(",").map((host) => normalizeHost(host.trim()));
+}
+export async function resolveDestination(urlString, options = {}) {
+    let url;
+    try {
+        url = new URL(urlString);
+    }
+    catch {
+        throw new FetchPolicyError();
+    }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || urlString.length > 8192)
+        throw new FetchPolicyError();
+    const hostname = normalizeHost(url.hostname);
+    const allowed = (options.allowedHosts ?? []).map(normalizeHost).includes(hostname);
+    if (options.restrictToAllowedHosts && !allowed)
+        throw new FetchPolicyError();
+    const version = isIP(hostname);
+    const addresses = version
+        ? [{ address: hostname, family: version }]
+        : await (options.resolve ?? ((host) => lookup(host, { all: true })))(hostname);
+    if (!addresses.length ||
+        addresses.some((a) => !isIP(a.address) ||
+            isIP(a.address) !== a.family ||
+            (!isGlobalAddress(a.address) && !(allowed && options.allowPrivateHosts !== false))))
+        throw new FetchPolicyError();
+    return { url, hostname, address: addresses[0].address, family: addresses[0].family };
+}
+export async function assertFetchDestinationAllowed(url, options = {}) {
+    await resolveDestination(url, options);
+}