@questpie/sandbox 3.1.0

package/src/server-internals.ts

@@ -0,0 +1,127 @@
+/**
+ * Pure supervisor helpers extracted from `sandbox-server.ts`.
+ *
+ * This file contains NO Deno globals and NO top-level side effects, so it is
+ * importable by BOTH the Deno sandbox server (over a `./server-internals.ts`
+ * specifier) AND `bun:test` (over `../src/server-internals.js`). It lands inside
+ * the package's `tsconfig` `include` and MUST typecheck clean — keep it plain TS.
+ *
+ * Behavior is identical to the closures these were lifted from: the two functions
+ * that previously read module-level env-derived state (`brokerUrlRejection` →
+ * `EXPECTED_BROKER_URL`, `extractResult` → `RESULT_MARKER`) now take that value as
+ * a parameter, and the server's single call sites pass the SAME values.
+ */
+
+/** Marker prefixed on the guest's final JSON result line on stdout. */
+export const RESULT_MARKER = "__QP_SANDBOX_RESULT__";
+
+/**
+ * Deno's BUILT-IN default `--allow-import` allowlist, applied when the flag is
+ * OMITTED. Omitting `--allow-import` does NOT mean "deny" — it silently grants
+ * these 7 hosts (incl. esm.sh). So when a guest's import allowlist is empty we
+ * must EXPLICITLY `--deny-import` these, or the guest could import from them.
+ * (Verified on Deno 2.7.8: bare `--deny-import` is a no-op; the value form works.)
+ */
+export const DENO_DEFAULT_IMPORT_HOSTS = [
+	"deno.land:443",
+	"jsr.io:443",
+	"esm.sh:443",
+	"raw.esm.sh:443",
+	"cdn.jsdelivr.net:443",
+	"raw.githubusercontent.com:443",
+	"gist.githubusercontent.com:443",
+];
+
+/**
+ * Run outcome (the result shape WITHOUT the server-measured `ms`). Defined here
+ * as a single local interface so the server can import ONE definition. It is
+ * structurally `Omit<SandboxRunResult, "ms">`.
+ */
+export interface RunOutcome {
+	ok: boolean;
+	output?: unknown;
+	logs: string[];
+	error?: string;
+	timedOut?: boolean;
+}
+
+/** Normalize a broker URL for comparison (drop a trailing slash; ignore case of origin). */
+export function normalizeBrokerUrl(raw: string): string | null {
+	try {
+		const u = new URL(raw);
+		// Compare origin (lowercased by URL) + pathname without a trailing slash.
+		const path = u.pathname.replace(/\/$/, "");
+		return `${u.origin}${path}`;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Reject a guest's bindings target URL unless it matches the supervisor's
+ * configured expected broker URL. Returns an error string to surface, or
+ * `null` when the URL is acceptable (or no expectation is configured).
+ */
+export function brokerUrlRejection(url: unknown, expected: string | undefined): string | null {
+	if (!expected) return null; // not configured → skip (back-compat)
+	if (typeof url !== "string" || url.length === 0) {
+		return "bindings.url is missing";
+	}
+	const got = normalizeBrokerUrl(url);
+	const want = normalizeBrokerUrl(expected);
+	if (got === null) return `bindings.url is not a valid URL: ${url}`;
+	if (got !== want) {
+		return `bindings.url does not match the configured broker URL`;
+	}
+	return null;
+}
+
+export function clampInt(v: unknown, def: number, min: number, max: number): number {
+	const n = Number(v);
+	if (!Number.isFinite(n)) return def;
+	return Math.min(Math.max(Math.round(n), min), max);
+}
+
+/**
+ * Build the `--allow-net` flag for a guest's net allowlist.
+ * Omitting it = no network (verified: NotCapable), so empty → no flag.
+ */
+export function netFlag(hosts: string[]): string[] {
+	const cleaned = hosts.map((h) => h.trim()).filter((h) => h.length > 0);
+	return cleaned.length ? [`--allow-net=${cleaned.join(",")}`] : [];
+}
+
+/**
+ * Build the import-permission flags for a guest's import allowlist.
+ * - Non-empty: `--allow-import=<hosts>` — an explicit value REPLACES Deno's
+ *   defaults (verified), so only these hosts are importable.
+ * - Empty: omit `--allow-import` AND `--deny-import=<defaults>` to neutralize
+ *   the implicit default hosts → no remote imports at all.
+ */
+export function importFlags(hosts: string[]): string[] {
+	const cleaned = hosts.map((h) => h.trim()).filter((h) => h.length > 0);
+	if (cleaned.length) {
+		return [`--allow-import=${cleaned.join(",")}`];
+	}
+	return [`--deny-import=${DENO_DEFAULT_IMPORT_HOSTS.join(",")}`];
+}
+
+/** Pull the marked JSON result line out of the guest's stdout. */
+export function extractResult(stdout: string, marker: string): RunOutcome | null {
+	const idx = stdout.lastIndexOf(marker);
+	if (idx === -1) return null;
+	const after = stdout.slice(idx + marker.length);
+	const newline = after.indexOf("\n");
+	const json = newline === -1 ? after : after.slice(0, newline);
+	try {
+		const parsed = JSON.parse(json);
+		return {
+			ok: !!parsed.ok,
+			output: parsed.output,
+			error: parsed.error,
+			logs: Array.isArray(parsed.logs) ? parsed.logs : [],
+		};
+	} catch {
+		return null;
+	}
+}

package/src/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Wire contract between the `executor` adapter (Bun/Node, main app) and the
+ * standalone Deno sandbox server. Kept intentionally minimal: the main app
+ * never imports Deno; it only speaks this JSON over HTTP.
+ */
+
+/**
+ * Per-request guest capabilities. `net` and `import` are INDEPENDENT axes
+ * (Deno enforces them separately — `--allow-net` gates `fetch`, `--allow-import`
+ * gates module imports). The richer app-binding capabilities (`data`, `services`,
+ * etc.) live on the core `ExecutorCapabilities` type and are NOT enforced by the
+ * sandbox server — they are the later bindings-broker's job.
+ */
+export interface SandboxCapabilities {
+	/** Runtime `fetch()` allowlist as `host[:port]`. Empty = no network. */
+	net: string[];
+	/** Module import allowlist as `host[:port]` (e.g. `esm.sh:443`). Empty = no remote imports. */
+	import: string[];
+	/** Hard wall-clock timeout; the subprocess is force-killed on exceed. */
+	timeoutMs: number;
+	/** Hard per-guest memory bound (`--v8-flags=--max-old-space-size`). */
+	memoryMb: number;
+}
+
+/**
+ * App-bindings wiring for the UNTRUSTED path. When present, the supervisor
+ * exposes a capability-scoped `globalThis.questpie` proxy to the guest whose
+ * methods RPC (over STDIO, never the network) to the host broker at {@link url},
+ * authenticated by the per-run scoped {@link token}.
+ *
+ * The token is OPAQUE and is held by the SUPERVISOR only — it is never written
+ * into the guest subprocess, so guest code cannot read or forge it to widen
+ * scope. The guest only ever sees the typed proxy.
+ *
+ * Critically, the broker is reached SERVER-TO-SERVER (supervisor → app), NOT by
+ * the guest's `fetch`: the guest's egress allowlist rejects loopback/private IPs
+ * (the SSRF defense), so a localhost broker is unreachable from guest code by
+ * design — we do not poke a hole in that.
+ */
+export interface SandboxBindings {
+	/** Absolute URL of the host broker endpoint (e.g. `https://app/sandbox/rpc`). */
+	url: string;
+	/** Per-run opaque scoped token. Supervisor-only; never exposed to the guest. */
+	token: string;
+}
+
+/** POST /run request body. */
+export interface SandboxRunRequest {
+	/** Guest TypeScript source. Must `export default` a `function(input)`. */
+	source: string;
+	/** Payload passed to the guest entry function. */
+	input: unknown;
+	capabilities: SandboxCapabilities;
+	/**
+	 * Secrets injected into the guest (NOT in source). Surfaced to the guest as
+	 * `globalThis.__secrets`. The sandbox never persists these.
+	 */
+	secrets?: Record<string, string>;
+	/**
+	 * App-bindings broker wiring. When omitted, the guest gets no `questpie`
+	 * proxy (the legacy compute-only path). When present, the supervisor brokers
+	 * the guest's binding RPCs to the host. See {@link SandboxBindings}.
+	 */
+	bindings?: SandboxBindings;
+}
+
+/** POST /run response body — also the `ExecutorAdapter.run` result shape. */
+export interface SandboxRunResult {
+	ok: boolean;
+	output?: unknown;
+	logs: string[];
+	error?: string;
+	/** True when the run was killed by the wall-clock timeout. */
+	timedOut?: boolean;
+	/** Wall-clock duration in ms (server-measured). */
+	ms?: number;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// FRAMED stdio protocol (guest subprocess ⇄ supervisor) for the bindings path.
+//
+// Mirrors `questpie`'s executor `protocol.ts` (the sandbox package ships as Deno
+// source and must NOT import the framework — same reason `SandboxCapabilities`
+// is duplicated here). When `bindings` is present the guest emits ONE JSON line
+// per message on stdout, prefixed by FRAME_MARKER; the supervisor demuxes by
+// `type` and replies to "rpc" with an "rpc-result" on the guest's stdin.
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Line prefix marking a framed protocol message on guest stdout. */
+export const FRAME_MARKER = "__QP_SANDBOX_MSG__";
+
+/**
+ * Header carrying the per-run scoped token on the supervisor → broker request.
+ * Mirrors `questpie`'s `BINDINGS_TOKEN_HEADER`. Supervisor-only; never set by or
+ * exposed to guest code.
+ */
+export const BINDINGS_TOKEN_HEADER = "x-questpie-sandbox-token";
+
+/** Structured error returned by the broker (mirrors `questpie` `BindingError`). */
+export interface SandboxBindingError {
+	code: string;
+	message: string;
+}
+
+/** Guest → supervisor: a binding RPC awaiting a brokered result. */
+export interface GuestRpcMessage {
+	type: "rpc";
+	id: number;
+	method: string;
+	args: unknown;
+}
+
+/** Guest → supervisor: the run's final result. */
+export interface GuestResultMessage {
+	type: "result";
+	ok: boolean;
+	output?: unknown;
+	error?: string;
+	logs: string[];
+}
+
+/** Any message the guest emits on stdout (framed). */
+export type GuestMessage = GuestRpcMessage | GuestResultMessage;
+
+/** Supervisor → guest: the brokered outcome of a prior {@link GuestRpcMessage}. */
+export interface HostRpcResultMessage {
+	type: "rpc-result";
+	id: number;
+	ok: boolean;
+	value?: unknown;
+	error?: SandboxBindingError;
+}