@questpie/sandbox 3.16.0 → 3.17.0

package/dist/modules/sandbox.d.mts

@@ -0,0 +1,40 @@
+import "../custom-tools-CgfgyVNv.mjs";
+import * as questpie0 from "questpie";
+import { routeApp } from "questpie";
+import "questpie/executor";
+import { RouteDefinition, RouteParamsFromKey } from "questpie/types";
+
+//#region src/server/modules/sandbox/routes/sandbox/rpc.d.ts
+
+declare const sandboxRpcRoute: questpie0.RawRouteDefinition<questpie0.JsonRouteParams>;
+//#endregion
+//#region src/server/modules/sandbox/.generated/module.d.ts
+type SandboxCollections = Record<never, never>;
+type SandboxChannels = Record<never, never>;
+type SandboxGlobals = Record<never, never>;
+type SandboxJobs = Record<never, never>;
+type SandboxRoutes = {
+  "sandbox/rpc": typeof sandboxRpcRoute extends {
+    __brand: "route";
+  } ? RouteDefinition<unknown, unknown, RouteParamsFromKey<"sandbox/rpc">> : typeof sandboxRpcRoute;
+};
+type SandboxFieldTypes = Record<never, never>;
+type SandboxModule = {
+  name: "questpie-sandbox";
+  routes: SandboxRoutes;
+  collections: SandboxCollections;
+  channels: SandboxChannels;
+  globals: SandboxGlobals;
+  jobs: SandboxJobs;
+  fieldTypes: SandboxFieldTypes;
+  messages: Record<never, never>;
+  services: Record<never, never>;
+  emails: Record<never, never>;
+  migrations: readonly unknown[];
+  seeds: readonly unknown[];
+};
+//#endregion
+//#region src/server/modules/sandbox/index.d.ts
+declare const sandboxModule: SandboxModule;
+//#endregion
+export { sandboxModule as default, sandboxModule };

package/dist/modules/sandbox.mjs

@@ -0,0 +1,211 @@
+import { a as BROKER_MAX_REQUEST_WIRE_BYTES, c as brokerResultValueCap, o as brokerRequestWireCap, s as brokerResponseWireCap, t as handleSandboxCustomToolsRpc } from "../custom-tools-DxI7JvUn.mjs";
+import { route, routeApp } from "questpie";
+import { BINDINGS_TOKEN_HEADER, snapshotBoundedBrokerValue } from "questpie/executor";
+
+//#region src/server/modules/sandbox/routes/sandbox/rpc.ts
+const MAX_METHOD_BYTES = 256;
+const BINDING_ERROR_CODES = new Set([
+	"bad_method",
+	"bad_args",
+	"unauthorized",
+	"forbidden",
+	"not_implemented",
+	"execution_error"
+]);
+function json(body, status) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+function errorResponse(status, code, message) {
+	return json({
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	}, status);
+}
+async function readBoundedJson(request) {
+	const contentLength = request.headers.get("content-length");
+	if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > BROKER_MAX_REQUEST_WIRE_BYTES)) return {
+		ok: false,
+		response: errorResponse(413, "bad_args", "sandbox broker request body is too large")
+	};
+	if (!request.body) return {
+		ok: false,
+		response: errorResponse(400, "bad_args", "invalid JSON body")
+	};
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	try {
+		while (true) {
+			const part = await reader.read();
+			if (part.done) break;
+			size += part.value.byteLength;
+			if (size > BROKER_MAX_REQUEST_WIRE_BYTES) {
+				await reader.cancel();
+				return {
+					ok: false,
+					response: errorResponse(413, "bad_args", "sandbox broker request body is too large")
+				};
+			}
+			chunks.push(part.value);
+		}
+	} catch {
+		return {
+			ok: false,
+			response: errorResponse(400, "bad_args", "invalid JSON body")
+		};
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)),
+			bytes: size
+		};
+	} catch {
+		return {
+			ok: false,
+			response: errorResponse(400, "bad_args", "invalid JSON body")
+		};
+	}
+}
+function parseRequestBody(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {
+		ok: false,
+		response: errorResponse(400, "bad_args", "invalid request body")
+	};
+	const body = value;
+	if (Object.keys(body).some((key) => key !== "method" && key !== "args")) return {
+		ok: false,
+		response: errorResponse(400, "bad_args", "invalid request body")
+	};
+	if (typeof body.method !== "string" || body.method.length === 0 || new TextEncoder().encode(body.method).byteLength > MAX_METHOD_BYTES) return {
+		ok: false,
+		response: errorResponse(400, "bad_method", "invalid method")
+	};
+	return {
+		ok: true,
+		method: body.method,
+		args: body.args
+	};
+}
+function invalidBrokerResult() {
+	return {
+		ok: false,
+		error: {
+			code: "execution_error",
+			message: "sandbox broker returned an invalid result",
+			correlationId: crypto.randomUUID()
+		}
+	};
+}
+function normalizeBrokerResult(method, value) {
+	const bounded = snapshotBoundedBrokerValue(value, brokerResponseWireCap(method));
+	if (!bounded.ok || !bounded.value || Array.isArray(bounded.value)) return null;
+	const result = bounded.value;
+	const resultKeys = Object.keys(result);
+	if (result.ok === true) {
+		if (resultKeys.length !== 2 || !resultKeys.includes("ok") || !resultKeys.includes("value")) return null;
+		const normalizedValue = snapshotBoundedBrokerValue(result.value, brokerResultValueCap(method));
+		if (!normalizedValue.ok) return null;
+		return {
+			ok: true,
+			value: normalizedValue.value
+		};
+	}
+	if (result.ok !== false || resultKeys.length !== 2 || !resultKeys.includes("error") || !result.error || typeof result.error !== "object" || Array.isArray(result.error)) return null;
+	const error = result.error;
+	const errorKeys = Object.keys(error);
+	if (!errorKeys.every((key) => [
+		"code",
+		"message",
+		"correlationId"
+	].includes(key)) || !errorKeys.includes("code") || !errorKeys.includes("message") || typeof error.code !== "string" || !BINDING_ERROR_CODES.has(error.code) || typeof error.message !== "string" || error.correlationId !== void 0 && typeof error.correlationId !== "string") return null;
+	const correlationId = typeof error.correlationId === "string" && /^[\w-]{1,128}$/.test(error.correlationId) ? error.correlationId : void 0;
+	if (error.code === "execution_error") return {
+		ok: false,
+		error: {
+			code: "execution_error",
+			message: "sandbox binding operation failed",
+			correlationId: correlationId ?? crypto.randomUUID()
+		}
+	};
+	return {
+		ok: false,
+		error: {
+			code: error.code,
+			message: error.message,
+			...correlationId ? { correlationId } : {}
+		}
+	};
+}
+async function handleSandboxBrokerRequest(request, broker, customTools) {
+	const decoded = await readBoundedJson(request);
+	if (!decoded.ok) return decoded.response;
+	const body = parseRequestBody(decoded.value);
+	if (!body.ok) return body.response;
+	if (decoded.bytes > brokerRequestWireCap(body.method)) return errorResponse(413, "bad_args", "sandbox broker request body is too large");
+	let result;
+	try {
+		result = body.method.startsWith("tools.") ? await handleSandboxCustomToolsRpc({
+			app: customTools?.app,
+			config: customTools?.config,
+			token: request.headers.get(BINDINGS_TOKEN_HEADER),
+			requestUrl: request.url,
+			method: body.method,
+			args: body.args,
+			signal: request.signal
+		}) : await broker.handleRpc(request.headers.get(BINDINGS_TOKEN_HEADER), body.method, body.args);
+	} catch {
+		return errorResponse(500, "execution_error", "sandbox broker request failed");
+	}
+	result = normalizeBrokerResult(body.method, result) ?? invalidBrokerResult();
+	const status = result.ok ? 200 : result.error.code === "unauthorized" ? 401 : result.error.code === "forbidden" ? 403 : result.error.code === "not_implemented" ? 501 : result.error.code === "execution_error" ? 500 : 400;
+	return json(result, status);
+}
+const sandboxRpcRoute = route().post().raw().access(true).handler((ctx) => {
+	const app = routeApp(ctx);
+	const broker = app.executor?.broker;
+	if (!broker) return errorResponse(503, "execution_error", "sandbox broker unavailable");
+	return handleSandboxBrokerRequest(ctx.request, broker, {
+		app,
+		config: app.state.sandboxCustomTools
+	});
+});
+var rpc_default = sandboxRpcRoute;
+
+//#endregion
+//#region src/server/modules/sandbox/.generated/module.ts
+const _module = {
+	name: "questpie-sandbox",
+	routes: { "sandbox/rpc": rpc_default },
+	collections: {},
+	channels: {},
+	globals: {},
+	jobs: {},
+	messages: {},
+	services: {},
+	emails: {},
+	migrations: [],
+	seeds: [],
+	fieldTypes: {}
+};
+var module_default = _module;
+
+//#endregion
+//#region src/server/modules/sandbox/index.ts
+const sandboxModule = module_default;
+var sandbox_default = sandboxModule;
+
+//#endregion
+export { sandbox_default as default, sandboxModule };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@questpie/sandbox",
-	"version": "3.16.0",
+	"version": "3.17.0",
 	"private": false,
 	"repository": {
 		"type": "git",
@@ -10,12 +10,16 @@
 	"files": [
 		"dist",
 		"src/sandbox-server.ts",
+		"src/broker-wire.ts",
 		"src/guest-entry.ts",
 		"src/net-validation.ts",
 		"src/server-internals.ts",
 		"src/egress-firewall.ts",
 		"src/types.ts",
-		"src/guest-bindings.ts"
+		"src/guest-bindings.ts",
+		"src/guest-runtime-source.ts",
+		"src/workload-admission.ts",
+		"src/workload.ts"
 	],
 	"type": "module",
 	"sideEffects": false,
@@ -31,6 +35,10 @@
 			"types": "./dist/adapter.d.mts",
 			"default": "./dist/adapter.mjs"
 		},
+		"./modules/sandbox": {
+			"types": "./dist/modules/sandbox.d.mts",
+			"default": "./dist/modules/sandbox.mjs"
+		},
 		"./package.json": {
 			"types": "./package.json",
 			"default": "./package.json"
@@ -47,6 +55,10 @@
 				"types": "./dist/adapter.d.mts",
 				"default": "./dist/adapter.mjs"
 			},
+			"./modules/sandbox": {
+				"types": "./dist/modules/sandbox.d.mts",
+				"default": "./dist/modules/sandbox.mjs"
+			},
 			"./package.json": {
 				"types": "./package.json",
 				"default": "./package.json"
@@ -56,16 +68,19 @@
 	"scripts": {
 		"build": "tsdown",
 		"check-types": "tsc --noEmit",
+		"questpie:generate": "bun questpie generate --verbose",
 		"test": "bun test"
 	},
 	"dependencies": {
-		"questpie": "^3.16.0"
+		"@questpie/mcp": "^3.17.0",
+		"questpie": "^3.17.0"
 	},
 	"devDependencies": {
 		"bun-types": "latest",
-		"tsdown": "^0.18.3"
+		"tsdown": "^0.18.3",
+		"zod": "^4.2.1"
 	},
 	"peerDependencies": {
-		"questpie": "^3.0.0"
+		"questpie": "^3.17.0"
 	}
 }

package/src/broker-wire.ts

@@ -0,0 +1,94 @@
+/**
+ * One place for the sandbox broker's decoded payload and derived wire budgets.
+ *
+ * `http.fetch` bodies are binary-to-base64, then nested in JSON RPC envelopes.
+ * The transport limits therefore cannot equal the decoded body limit. Keep all
+ * supervisor, route, frame, and custom-tool caps derived here.
+ */
+
+/** Decoded request/response body limit promised by `http.fetch`. */
+export const BROKER_HTTP_BODY_CAP_BYTES = 5 * 1024 * 1024;
+
+/** Exact maximum base64 length for a decoded HTTP body at the public cap. */
+export const BROKER_HTTP_BASE64_CAP_BYTES =
+	4 * Math.ceil(BROKER_HTTP_BODY_CAP_BYTES / 3);
+
+/**
+ * Room for URL, method, bounded HTTP headers, status metadata, and JSON RPC
+ * envelope syntax around a maximum-size base64 body.
+ */
+export const BROKER_HTTP_JSON_HEADROOM_BYTES = 128 * 1024;
+
+/** Whole JSON request/response budget for the `http.fetch` method. */
+export const BROKER_HTTP_WIRE_CAP_BYTES =
+	BROKER_HTTP_BASE64_CAP_BYTES + BROKER_HTTP_JSON_HEADROOM_BYTES;
+
+/** Existing small native binding request budget, including its JSON envelope. */
+export const BROKER_NATIVE_REQUEST_WIRE_CAP_BYTES = 64 * 1024;
+
+/** Maximum JSON value returned by native bindings before envelope overhead. */
+export const BROKER_NATIVE_RESULT_CAP_BYTES = 768 * 1024;
+
+/** Custom-tool logical limits; shared with the host session implementation. */
+export const BROKER_CUSTOM_ARGUMENT_CAP_BYTES = 63 * 1024;
+export const BROKER_CUSTOM_RESULT_CAP_BYTES = 768 * 1024;
+export const BROKER_CUSTOM_LIST_CAP_BYTES = 768 * 1024;
+
+const BROKER_JSON_ENVELOPE_HEADROOM_BYTES = 4 * 1024;
+
+export const BROKER_NATIVE_RESPONSE_WIRE_CAP_BYTES =
+	BROKER_NATIVE_RESULT_CAP_BYTES + BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+export const BROKER_CUSTOM_REQUEST_WIRE_CAP_BYTES =
+	BROKER_CUSTOM_ARGUMENT_CAP_BYTES + BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+export const BROKER_CUSTOM_RESPONSE_WIRE_CAP_BYTES =
+	Math.max(BROKER_CUSTOM_RESULT_CAP_BYTES, BROKER_CUSTOM_LIST_CAP_BYTES) +
+	BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+
+/** Maximum body the app broker route will read before method-aware validation. */
+export const BROKER_MAX_REQUEST_WIRE_BYTES = Math.max(
+	BROKER_HTTP_WIRE_CAP_BYTES,
+	BROKER_NATIVE_REQUEST_WIRE_CAP_BYTES,
+	BROKER_CUSTOM_REQUEST_WIRE_CAP_BYTES,
+);
+
+/** Maximum response the supervisor will read before method-aware validation. */
+export const BROKER_MAX_RESPONSE_WIRE_BYTES = Math.max(
+	BROKER_HTTP_WIRE_CAP_BYTES,
+	BROKER_NATIVE_RESPONSE_WIRE_CAP_BYTES,
+	BROKER_CUSTOM_RESPONSE_WIRE_CAP_BYTES,
+);
+
+/** Prefix/newline room around the largest JSON RPC frame. */
+export const BROKER_FRAME_CAP_BYTES =
+	Math.max(BROKER_MAX_REQUEST_WIRE_BYTES, BROKER_MAX_RESPONSE_WIRE_BYTES) +
+	1024;
+
+/**
+ * A run may emit one maximum RPC request and still return a maximum-sized final
+ * frame. Repeated large calls remain bounded by this cumulative budget.
+ */
+export const BROKER_TOTAL_OUTPUT_CAP_BYTES = BROKER_FRAME_CAP_BYTES * 2;
+
+export function brokerRequestWireCap(method: string): number {
+	if (method === "http.fetch") return BROKER_HTTP_WIRE_CAP_BYTES;
+	if (method === "tools.call") return BROKER_CUSTOM_REQUEST_WIRE_CAP_BYTES;
+	if (method === "tools.list") return BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+	return BROKER_NATIVE_REQUEST_WIRE_CAP_BYTES;
+}
+
+export function brokerResponseWireCap(method: string): number {
+	if (method === "http.fetch") return BROKER_HTTP_WIRE_CAP_BYTES;
+	if (method === "tools.call" || method === "tools.list") {
+		return BROKER_CUSTOM_RESPONSE_WIRE_CAP_BYTES;
+	}
+	return BROKER_NATIVE_RESPONSE_WIRE_CAP_BYTES;
+}
+
+export function brokerResultValueCap(method: string): number {
+	if (method === "http.fetch") {
+		return BROKER_HTTP_WIRE_CAP_BYTES - BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+	}
+	if (method === "tools.call") return BROKER_CUSTOM_RESULT_CAP_BYTES;
+	if (method === "tools.list") return BROKER_CUSTOM_LIST_CAP_BYTES;
+	return BROKER_NATIVE_RESULT_CAP_BYTES;
+}

package/src/egress-firewall.ts

@@ -161,7 +161,9 @@ function looksIpv4(ip: string): boolean {
 	const parts = ip.split(".");
 	return (
 		parts.length === 4 &&
-		parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) >= 0 && Number(p) <= 255)
+		parts.every(
+			(p) => /^\d{1,3}$/.test(p) && Number(p) >= 0 && Number(p) <= 255,
+		)
 	);
 }
 
@@ -182,7 +184,9 @@ function looksIpv4(ip: string): boolean {
 export function buildNftRuleset(allow: readonly AllowedEndpoint[]): string {
 	const lines: string[] = [];
 	lines.push(`# QUESTPIE sandbox egress firewall (defense-in-depth, per-run).`);
-	lines.push(`# Default-deny: only the resolved allowlist + broker may egress.`);
+	lines.push(
+		`# Default-deny: only the resolved allowlist + broker may egress.`,
+	);
 	lines.push(`table inet ${NFT_TABLE} {`);
 	lines.push(`\tchain output {`);
 	lines.push(`\t\ttype filter hook output priority 0; policy drop;`);
@@ -228,7 +232,9 @@ export function buildNftRuleset(allow: readonly AllowedEndpoint[]): string {
  * default-deny netns, the correct posture for the brokered (`--allow-net=[]`)
  * path. The guest has nothing to reach over raw sockets; the kernel enforces it.
  */
-export function planEgressFirewall(input: EgressFirewallPlanInput): EgressFirewallPlan {
+export function planEgressFirewall(
+	input: EgressFirewallPlanInput,
+): EgressFirewallPlan {
 	if (!isLinux(input.os)) {
 		return {
 			applied: false,

package/src/guest-bindings.ts

@@ -54,6 +54,31 @@ export interface GuestStore {
 	delete(args?: { where?: unknown }): Promise<unknown>;
 }
 
+/** Schema-preserving custom-tool descriptor returned by discovery. */
+export interface GuestToolDescriptor {
+	name: string;
+	title?: string;
+	description?: string;
+	inputSchema: Record<string, unknown>;
+	outputSchema?: Record<string, unknown>;
+	annotations?: Record<string, unknown>;
+	_meta?: Record<string, unknown>;
+}
+
+/** Protocol-safe custom-tool result returned to the guest. */
+export interface GuestToolResult {
+	content: Array<{ type: string; [key: string]: unknown }>;
+	structuredContent?: Record<string, unknown>;
+	isError?: boolean;
+	_meta?: Record<string, unknown>;
+}
+
+/** Explicit custom-tool discovery/call surface. Authorization stays host-side. */
+export interface GuestTools {
+	list(): Promise<{ tools: GuestToolDescriptor[] }>;
+	call(name: string, args?: Record<string, unknown>): Promise<GuestToolResult>;
+}
+
 /** The `globalThis.questpie` surface handed to untrusted guest code. */
 export interface GuestBindings {
 	/** Files (file-as-DB), scoped by the run's `capabilities.files`. */
@@ -76,6 +101,11 @@ export interface GuestBindings {
 	 * `collections.document_store.<op>` call.
 	 */
 	store: Record<string, GuestStore>;
+	/**
+	 * Explicitly released custom MCP tools. Built-in CRUD/file/store operations
+	 * never flow through this namespace.
+	 */
+	tools: GuestTools;
 }
 
 /**
@@ -142,5 +172,17 @@ export function buildGuestBindings(hostCall: HostCall): GuestBindings {
 		},
 	) as Record<string, GuestStore>;
 
-	return { files, collections, store };
+	const tools: GuestTools = {
+		list: async () =>
+			(await hostCall("tools.list", {})) as {
+				tools: GuestToolDescriptor[];
+			},
+		call: async (name, args) =>
+			(await hostCall("tools.call", {
+				name,
+				arguments: args ?? {},
+			})) as GuestToolResult,
+	};
+
+	return { files, collections, store, tools };
 }