@questpie/sandbox 3.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @questpie/sandbox
+
+Hardened sandboxed code execution for QUESTPIE executor workloads. The package ships the HTTP adapter used by a QUESTPIE app and the Deno supervisor source that executes untrusted code in a separate process with capability-scoped network, import, file, and app bindings.
+
+## Features
+
+- **HTTP executor adapter** - connect `ctx.executor.run()` to a standalone sandbox service.
+- **Deno supervisor** - run guest code outside the main Bun/Node app process.
+- **Capability-scoped bindings** - expose only declared collections, stores, files, and fetch access.
+- **SSRF protection** - validate literal IPs, DNS rebinding, redirects, and private/metadata ranges.
+- **Network isolation support** - Linux network namespace/firewall planning for defense in depth.
+- **Structured failures** - timeouts, non-JSON responses, and network failures return predictable results.
+
+## Installation
+
+```bash
+bun add @questpie/sandbox
+```
+
+## Configure The Adapter
+
+```ts
+// config/app.ts
+import { httpSandboxAdapter } from "@questpie/sandbox/adapter";
+import { appConfig } from "questpie";
+
+export default appConfig({
+	executor: {
+		sandboxed: httpSandboxAdapter({
+			url: process.env.SANDBOX_URL,
+		}),
+	},
+});
+```
+
+Guest bindings require a host-side broker route in the app or control-plane layer. Compute-only sandboxed execution only needs the adapter above.
+
+## Run The Supervisor
+
+The Deno supervisor source is published with the package:
+
+```bash
+deno run --allow-net --allow-env --allow-run --allow-read --allow-write=$TMPDIR \
+	node_modules/@questpie/sandbox/src/sandbox-server.ts
+```
+
+Set `SANDBOX_URL` in the app to the supervisor URL.
+
+## Exports
+
+| Entry Point                 | Purpose                                    |
+| --------------------------- | ------------------------------------------ |
+| `@questpie/sandbox`         | Adapter, validation, and binding utilities |
+| `@questpie/sandbox/adapter` | `httpSandboxAdapter()` only                |
+
+## License
+
+MIT

package/dist/adapter-http-7ypWHBck.d.mts

@@ -0,0 +1,43 @@
+import { ExecutorAdapter, ExecutorRunOptions, ExecutorRunResult } from "questpie/executor";
+
+//#region src/adapter-http.d.ts
+interface HttpSandboxAdapterOptions {
+  /**
+   * Base URL of the standalone Deno sandbox service (`sandbox-server.ts`).
+   * Defaults to `process.env.SANDBOX_URL`. Throws on `run` if neither is set.
+   */
+  url?: string;
+  /**
+   * Per-request HTTP fetch timeout (ms). A safety margin above the guest
+   * wall-timeout so the server's own kill fires first; if the server is
+   * unreachable this bounds the client wait. Default: guest timeout + 10s.
+   */
+  fetchTimeoutMs?: number;
+  /** Optional custom `fetch` (e.g. for auth headers / mTLS). */
+  fetch?: typeof fetch;
+  /**
+   * Validate net/import hosts against the private-IP policy BEFORE sending to
+   * the sandbox (defense-in-depth; the server validates too). Default: true.
+   */
+  validateEgress?: boolean;
+}
+/**
+ * Production sandboxed `ExecutorAdapter` — POSTs the run to the standalone Deno
+ * sandbox service over HTTP. The main app (Bun/Node) holds NO Deno; it only
+ * speaks this JSON contract.
+ *
+ * Use as the `sandboxed` adapter in the executor config:
+ *   executor: { sandboxed: httpSandboxAdapter({ url: process.env.SANDBOX_URL }) }
+ */
+declare class HttpSandboxAdapter implements ExecutorAdapter {
+  private readonly options;
+  private readonly fetchImpl;
+  private readonly validateEgress;
+  constructor(options?: HttpSandboxAdapterOptions);
+  private resolveUrl;
+  run(options: ExecutorRunOptions): Promise<ExecutorRunResult>;
+}
+/** Factory for the production sandboxed adapter. */
+declare function httpSandboxAdapter(options?: HttpSandboxAdapterOptions): HttpSandboxAdapter;
+//#endregion
+export { HttpSandboxAdapterOptions as n, httpSandboxAdapter as r, HttpSandboxAdapter as t };

package/dist/adapter-http-w7SjAfcC.mjs

@@ -0,0 +1,298 @@
+//#region src/net-validation.ts
+/**
+* Parse a `host[:port]` allowlist entry (Deno `--allow-net` syntax).
+* Bracketed IPv6 (`[::1]:443`) and bare IPv6 (`::1`) are both handled.
+*/
+function parseHostEntry(entry) {
+	const trimmed = entry.trim();
+	if (trimmed.startsWith("[")) {
+		const close = trimmed.indexOf("]");
+		if (close === -1) return { host: trimmed };
+		const host = trimmed.slice(1, close);
+		const rest = trimmed.slice(close + 1);
+		if (rest.startsWith(":")) {
+			const port = Number(rest.slice(1));
+			return Number.isInteger(port) ? {
+				host,
+				port
+			} : { host };
+		}
+		return { host };
+	}
+	if ((trimmed.match(/:/g)?.length ?? 0) > 1) return { host: trimmed };
+	const lastColon = trimmed.lastIndexOf(":");
+	if (lastColon !== -1) {
+		const maybePort = Number(trimmed.slice(lastColon + 1));
+		if (Number.isInteger(maybePort)) return {
+			host: trimmed.slice(0, lastColon),
+			port: maybePort
+		};
+	}
+	return { host: trimmed };
+}
+/** True if `s` is a syntactically-valid dotted-quad IPv4 literal. */
+function isIpv4Literal(s) {
+	const parts = s.split(".");
+	if (parts.length !== 4) return false;
+	return parts.every((p) => {
+		if (!/^\d{1,3}$/.test(p)) return false;
+		const n = Number(p);
+		return n >= 0 && n <= 255;
+	});
+}
+/** True if `s` looks like an IPv6 literal (contains a colon, hex/`:`/`.` only). */
+function isIpv6Literal(s) {
+	if (!s.includes(":")) return false;
+	return /^[0-9a-fA-F:.]+$/.test(s);
+}
+/**
+* Classify an IPv4 literal as private/link-local/loopback/metadata/CGNAT.
+* Ranges (all per the task + cloud-metadata convention):
+*   0.0.0.0/8 (this-host), 127/8 (loopback), 10/8, 172.16/12, 192.168/16 (RFC-1918),
+*   169.254/16 (link-local, incl. 169.254.169.254 metadata), 100.64/10 (CGNAT/RFC-6598).
+*/
+function isPrivateIpv4(ip) {
+	const [a, b] = ip.split(".").map(Number);
+	if (a === 0) return true;
+	if (a === 127) return true;
+	if (a === 10) return true;
+	if (a === 172 && b >= 16 && b <= 31) return true;
+	if (a === 192 && b === 168) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 100 && b >= 64 && b <= 127) return true;
+	return false;
+}
+/** Normalize an IPv6 literal to lowercase, stripping a `%zone` suffix. */
+function normalizeIpv6(ip) {
+	const pct = ip.indexOf("%");
+	return (pct === -1 ? ip : ip.slice(0, pct)).toLowerCase();
+}
+/**
+* Classify an IPv6 literal as private/link-local/loopback/metadata.
+* Covers: ::1 (loopback), :: (unspecified), fc00::/7 (unique-local),
+* fe80::/10 (link-local), and IPv4-mapped/translated forms (::ffff:a.b.c.d,
+* ::a.b.c.d) by delegating their embedded IPv4 to `isPrivateIpv4`.
+*/
+function isPrivateIpv6(raw) {
+	const ip = normalizeIpv6(raw);
+	if (ip === "::1") return true;
+	if (ip === "::" || ip === "") return true;
+	const v4Tail = ip.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+	if (v4Tail && isIpv4Literal(v4Tail[1])) {
+		if (ip.startsWith("::")) return isPrivateIpv4(v4Tail[1]);
+	}
+	const mapped = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+	if (mapped) {
+		const hi = Number.parseInt(mapped[1], 16) & 65535;
+		const lo = Number.parseInt(mapped[2], 16) & 65535;
+		return isPrivateIpv4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+	}
+	if (/^f[cd][0-9a-f]{0,2}:/.test(ip) || ip.startsWith("fc") || ip.startsWith("fd")) {
+		const first = ip.split(":")[0];
+		if (first.length > 0) {
+			if ((Number.parseInt(first.padStart(4, "0").slice(0, 2), 16) & 254) === 252) return true;
+		}
+	}
+	if (ip.startsWith("fe8") || ip.startsWith("fe9") || ip.startsWith("fea") || ip.startsWith("feb")) return true;
+	return false;
+}
+/**
+* Classify a bare IP literal (v4 or v6) as a blocked egress target.
+* Returns `{ ok:false, reason }` when the IP is private/link-local/loopback/metadata.
+*/
+function classifyIpLiteral(ip) {
+	if (isIpv4Literal(ip)) return isPrivateIpv4(ip) ? {
+		ok: false,
+		reason: `private/link-local/loopback IPv4: ${ip}`
+	} : { ok: true };
+	if (isIpv6Literal(ip)) return isPrivateIpv6(ip) ? {
+		ok: false,
+		reason: `private/link-local/loopback IPv6: ${ip}`
+	} : { ok: true };
+	return { ok: true };
+}
+/** Bound each DNS lookup so a slow/hanging resolver can't stall validation. */
+const DNS_TIMEOUT_MS = 3e3;
+function withDnsTimeout(p) {
+	return Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`DNS lookup timed out (${DNS_TIMEOUT_MS}ms)`)), DNS_TIMEOUT_MS))]);
+}
+/** Lazily load `node:dns/promises` `resolve` (works on both Bun and Deno). */
+let cachedResolver;
+async function defaultResolver(hostname) {
+	if (!cachedResolver) {
+		const dns = await import("node:dns/promises");
+		cachedResolver = async (h) => {
+			const [v4, v6] = await Promise.allSettled([withDnsTimeout(dns.resolve4(h)), withDnsTimeout(dns.resolve6(h))]);
+			const out = [];
+			if (v4.status === "fulfilled") out.push(...v4.value);
+			if (v6.status === "fulfilled") out.push(...v6.value);
+			if (out.length === 0 && v4.status === "rejected" && v6.status === "rejected") throw new Error(`DNS resolution failed (v4: ${reasonOf(v4)}, v6: ${reasonOf(v6)})`);
+			return out;
+		};
+	}
+	return cachedResolver(hostname);
+}
+function reasonOf(settled) {
+	const r = settled.reason;
+	return r instanceof Error ? r.message : String(r);
+}
+/**
+* Validate a single `host[:port]` allowlist entry against the private-IP policy.
+*
+* - IP literals are classified directly (no DNS).
+* - Hostnames are DNS-resolved; if ANY resolved address is private/link-local/
+*   loopback/metadata, the host is REJECTED (DNS-rebind defense at manifest time).
+* - `localhost` and the `.local` mDNS suffix are rejected up-front.
+*
+* `resolve` is injectable for tests / Deno; defaults to `node:dns/promises`.
+*/
+async function validateHostEgress(entry, opts = {}) {
+	const { host } = parseHostEntry(entry);
+	const lower = host.toLowerCase();
+	if (lower.length === 0) return {
+		ok: false,
+		reason: "empty host"
+	};
+	if (lower === "localhost" || lower.endsWith(".localhost") || lower.endsWith(".local")) return {
+		ok: false,
+		reason: `loopback/mDNS hostname not allowed: ${host}`
+	};
+	const literal = classifyIpLiteral(host);
+	if (!literal.ok) return literal;
+	if (isIpv4Literal(host) || isIpv6Literal(host)) return { ok: true };
+	const resolver = opts.resolve ?? defaultResolver;
+	let addrs;
+	try {
+		addrs = await resolver(host);
+	} catch (err) {
+		return {
+			ok: false,
+			reason: `DNS resolution failed for ${host}: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	if (addrs.length === 0) return {
+		ok: false,
+		reason: `DNS resolution returned no addresses for ${host}`
+	};
+	for (const addr of addrs) {
+		const c = classifyIpLiteral(addr);
+		if (!c.ok) return {
+			ok: false,
+			reason: `${host} resolves to a blocked address (${c.reason})`
+		};
+	}
+	return { ok: true };
+}
+/**
+* Validate ALL `net` + `import` hosts in a capability set.
+* Returns the first rejection found, or `{ ok:true }` if every host passes.
+*/
+async function validateEgressHosts(hosts, opts = {}) {
+	for (const entry of hosts) {
+		const r = await validateHostEgress(entry, opts);
+		if (!r.ok) return {
+			ok: false,
+			reason: `host "${entry}": ${r.reason}`
+		};
+	}
+	return { ok: true };
+}
+
+//#endregion
+//#region src/adapter-http.ts
+const DEFAULT_GUEST_TIMEOUT_MS = 5e3;
+/**
+* Production sandboxed `ExecutorAdapter` — POSTs the run to the standalone Deno
+* sandbox service over HTTP. The main app (Bun/Node) holds NO Deno; it only
+* speaks this JSON contract.
+*
+* Use as the `sandboxed` adapter in the executor config:
+*   executor: { sandboxed: httpSandboxAdapter({ url: process.env.SANDBOX_URL }) }
+*/
+var HttpSandboxAdapter = class {
+	fetchImpl;
+	validateEgress;
+	constructor(options = {}) {
+		this.options = options;
+		this.fetchImpl = options.fetch ?? globalThis.fetch;
+		this.validateEgress = options.validateEgress ?? true;
+	}
+	resolveUrl() {
+		const url = this.options.url ?? (typeof process !== "undefined" ? process.env?.SANDBOX_URL : void 0);
+		if (!url) throw new Error("HttpSandboxAdapter: no sandbox URL configured. Pass `url` or set SANDBOX_URL.");
+		return url.replace(/\/$/, "");
+	}
+	async run(options) {
+		const base = this.resolveUrl();
+		const caps = options.capabilities ?? {};
+		const net = caps.net ?? [];
+		const importHosts = caps.import ?? [];
+		const timeoutMs = caps.timeoutMs ?? DEFAULT_GUEST_TIMEOUT_MS;
+		if (this.validateEgress) {
+			const egress = await validateEgressHosts([...net, ...importHosts]);
+			if (!egress.ok) return {
+				ok: false,
+				error: `egress blocked: ${egress.reason}`,
+				logs: []
+			};
+		}
+		const sandboxCaps = {
+			net,
+			import: importHosts,
+			timeoutMs,
+			memoryMb: caps.memoryMb ?? 128
+		};
+		const fetchTimeoutMs = this.options.fetchTimeoutMs ?? timeoutMs + 1e4;
+		const controller = new AbortController();
+		const abortTimer = setTimeout(() => controller.abort(), fetchTimeoutMs);
+		try {
+			const bindings = options.sandboxBindings;
+			const res = await this.fetchImpl(`${base}/run`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					source: options.source,
+					input: options.input ?? null,
+					capabilities: sandboxCaps,
+					secrets: options.secrets ?? {},
+					...bindings ? { bindings } : {}
+				}),
+				signal: controller.signal
+			});
+			const text = await res.text();
+			let parsed;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				return {
+					ok: false,
+					error: `sandbox returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`,
+					logs: []
+				};
+			}
+			return {
+				ok: !!parsed.ok,
+				output: parsed.output,
+				error: parsed.error,
+				logs: Array.isArray(parsed.logs) ? parsed.logs : [],
+				timedOut: parsed.timedOut,
+				ms: parsed.ms
+			};
+		} catch (err) {
+			return {
+				ok: false,
+				error: err instanceof Error && err.name === "AbortError" ? `sandbox request timed out after ${fetchTimeoutMs}ms` : `sandbox request failed: ${err instanceof Error ? err.message : String(err)}`,
+				logs: []
+			};
+		} finally {
+			clearTimeout(abortTimer);
+		}
+	}
+};
+/** Factory for the production sandboxed adapter. */
+function httpSandboxAdapter(options = {}) {
+	return new HttpSandboxAdapter(options);
+}
+
+//#endregion
+export { validateEgressHosts as a, parseHostEntry as i, httpSandboxAdapter as n, validateHostEgress as o, classifyIpLiteral as r, HttpSandboxAdapter as t };

package/dist/adapter.d.mts

@@ -0,0 +1,2 @@
+import { n as HttpSandboxAdapterOptions, r as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-7ypWHBck.mjs";
+export { HttpSandboxAdapter, type HttpSandboxAdapterOptions, httpSandboxAdapter };

package/dist/adapter.mjs

@@ -0,0 +1,3 @@
+import { n as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-w7SjAfcC.mjs";
+
+export { HttpSandboxAdapter, httpSandboxAdapter };

package/dist/index.d.mts

@@ -0,0 +1,280 @@
+import { n as HttpSandboxAdapterOptions, r as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-7ypWHBck.mjs";
+
+//#region src/net-validation.d.ts
+
+/**
+ * Network egress validation — SSRF / DNS-rebind defense for sandboxed guests.
+ *
+ * The sandbox grants each guest a per-request `net`/`import` allowlist of
+ * `host[:port]` entries (driving Deno's `--allow-net` / `--allow-import`).
+ * Deno's allowlist is a hostname-STRING match with NO IP validation, so an
+ * allowlisted domain that resolves to a private/link-local/loopback/metadata
+ * address (e.g. `169.254.169.254`, `127.0.0.1`, RFC-1918) would still connect.
+ * This module rejects those at MANIFEST-VALIDATION time.
+ *
+ * Runtime-agnostic: the DNS resolver is injectable so this same code runs under
+ * Bun/Node (manifest validation in the adapter) and Deno (the sandbox server).
+ * It defaults to `node:dns/promises`, which both Bun and Deno implement.
+ *
+ * SCOPE (M2): manifest-time rejection of private-IP hosts is implemented and
+ * enforced here. Full connect-time DNS-rebind PINNING (re-resolving and
+ * re-checking the exact IP the socket connects to, including across redirects)
+ * is NOT yet implemented — see `TODO(security)` in `sandbox-server.ts`.
+ */
+/** A single parsed `host[:port]` allowlist entry. */
+interface ParsedHost {
+  /** Bare hostname or IP literal (IPv6 without brackets). */
+  host: string;
+  /** Port if specified, else undefined. */
+  port?: number;
+}
+interface IpValidationResult {
+  ok: boolean;
+  /** Reason the host was rejected (only set when `ok` is false). */
+  reason?: string;
+}
+/** Async DNS resolver shape (subset of `node:dns/promises`). */
+type DnsResolver = (hostname: string) => Promise<string[]>;
+/**
+ * Parse a `host[:port]` allowlist entry (Deno `--allow-net` syntax).
+ * Bracketed IPv6 (`[::1]:443`) and bare IPv6 (`::1`) are both handled.
+ */
+declare function parseHostEntry(entry: string): ParsedHost;
+/**
+ * Classify a bare IP literal (v4 or v6) as a blocked egress target.
+ * Returns `{ ok:false, reason }` when the IP is private/link-local/loopback/metadata.
+ */
+declare function classifyIpLiteral(ip: string): IpValidationResult;
+/**
+ * Validate a single `host[:port]` allowlist entry against the private-IP policy.
+ *
+ * - IP literals are classified directly (no DNS).
+ * - Hostnames are DNS-resolved; if ANY resolved address is private/link-local/
+ *   loopback/metadata, the host is REJECTED (DNS-rebind defense at manifest time).
+ * - `localhost` and the `.local` mDNS suffix are rejected up-front.
+ *
+ * `resolve` is injectable for tests / Deno; defaults to `node:dns/promises`.
+ */
+declare function validateHostEgress(entry: string, opts?: {
+  resolve?: DnsResolver;
+}): Promise<IpValidationResult>;
+/**
+ * Validate ALL `net` + `import` hosts in a capability set.
+ * Returns the first rejection found, or `{ ok:true }` if every host passes.
+ */
+declare function validateEgressHosts(hosts: readonly string[], opts?: {
+  resolve?: DnsResolver;
+}): Promise<IpValidationResult>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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. */
+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;
+}
+/** Line prefix marking a framed protocol message on guest stdout. */
+declare 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.
+ */
+declare const BINDINGS_TOKEN_HEADER = "x-questpie-sandbox-token";
+/** Structured error returned by the broker (mirrors `questpie` `BindingError`). */
+interface SandboxBindingError {
+  code: string;
+  message: string;
+}
+/** Guest → supervisor: a binding RPC awaiting a brokered result. */
+interface GuestRpcMessage {
+  type: "rpc";
+  id: number;
+  method: string;
+  args: unknown;
+}
+/** Guest → supervisor: the run's final result. */
+interface GuestResultMessage {
+  type: "result";
+  ok: boolean;
+  output?: unknown;
+  error?: string;
+  logs: string[];
+}
+/** Any message the guest emits on stdout (framed). */
+type GuestMessage = GuestRpcMessage | GuestResultMessage;
+/** Supervisor → guest: the brokered outcome of a prior {@link GuestRpcMessage}. */
+interface HostRpcResultMessage {
+  type: "rpc-result";
+  id: number;
+  ok: boolean;
+  value?: unknown;
+  error?: SandboxBindingError;
+}
+//#endregion
+//#region src/guest-bindings.d.ts
+/**
+ * Guest bindings proxy — the UNTRUSTED-side typed surface a sandboxed mini-app
+ * uses to call the app's primitives WITHOUT importing the app.
+ *
+ * Design: `.private/knowledge-miniapps-mvp.md` §13 (TRUSTED vs UNTRUSTED) + §14
+ * (the primitive surface). Mirrors the server `ctx` names (consistent-naming
+ * principle) so guest code reads like a server handler:
+ *
+ *   const orders = await globalThis.questpie.collections.orders.find({ where });
+ *   const note   = await globalThis.questpie.files.read({ path });
+ *
+ * Every method just does `await hostCall(method, args)`. `hostCall` is INJECTED
+ * (it writes a framed RPC to the supervisor over stdio and awaits the brokered
+ * result) — this module holds NO transport and NO secrets, so it is pure and
+ * unit-testable with a fake `hostCall`. The guest never sees the per-run token
+ * or a broker URL; the only thing it can do is call these methods, which the
+ * trusted host broker enforces per call (default-deny).
+ *
+ * This file is plain TS (no Deno globals) so it typechecks + unit-tests in Bun;
+ * `guest-entry.ts` (Deno) imports it and supplies the real stdio `hostCall`.
+ */
+/** Transport: send one binding RPC, resolve with its brokered value or reject. */
+type HostCall = (method: string, args: unknown) => Promise<unknown>;
+/**
+ * Per-collection access surface. Reads (`find`/`findOne`) are always available;
+ * writes (`create`/`update`/`delete`) are dispatched ONLY where the host wires a
+ * safe handler (the `document_store` store-grant clamp, or a collection with an
+ * explicit write rule — Decision 8 / §7). An ungranted/unwired call rejects host-side.
+ */
+interface GuestCollection {
+  find(args?: unknown): Promise<unknown>;
+  findOne(args?: unknown): Promise<unknown>;
+  create(args?: unknown): Promise<unknown>;
+  update(args?: unknown): Promise<unknown>;
+  delete(args?: unknown): Promise<unknown>;
+}
+/**
+ * Sugar surface for ONE `document_store` namespace. Every op auto-injects
+ * `store: <name>`; the host still clamps to the run's granted stores (the sugar is
+ * a convenience, NOT a second enforcement path — `questpie.store.posts.create(x)`
+ * is exactly `questpie.collections.document_store.create({ ...x, store:"posts" })`).
+ */
+interface GuestStore {
+  find(args?: Record<string, unknown>): Promise<unknown>;
+  findOne(args?: Record<string, unknown>): Promise<unknown>;
+  create(args: {
+    key: string;
+    data?: unknown;
+  }): Promise<unknown>;
+  update(args: {
+    where?: unknown;
+    data?: Record<string, unknown>;
+  }): Promise<unknown>;
+  delete(args?: {
+    where?: unknown;
+  }): Promise<unknown>;
+}
+/** The `globalThis.questpie` surface handed to untrusted guest code. */
+interface GuestBindings {
+  /** Files (file-as-DB), scoped by the run's `capabilities.files`. */
+  files: {
+    read(args: {
+      path: string;
+      scope?: unknown;
+    }): Promise<unknown>;
+    write(args: {
+      path: string;
+      content: string;
+      title?: string;
+      mime_type?: string;
+      scope?: unknown;
+    }): Promise<unknown>;
+    list(args?: {
+      path?: string;
+      scope?: unknown;
+    }): Promise<unknown>;
+  };
+  /** Per-collection read/write access, scoped by `capabilities.data.collections`. */
+  collections: Record<string, GuestCollection>;
+  /**
+   * Per-namespace `document_store` sugar, scoped by `capabilities.data.stores`.
+   * `questpie.store.<name>.<op>` injects `store:<name>` onto the underlying
+   * `collections.document_store.<op>` call.
+   */
+  store: Record<string, GuestStore>;
+}
+/**
+ * Build the guest bindings proxy over an injected {@link HostCall}.
+ *
+ * `collections` is a Proxy so any collection NAME resolves to a `{ find,
+ * findOne }` shim — capability enforcement for the specific collection happens
+ * HOST-SIDE in the broker (the guest can't pre-know which names are granted, and
+ * the proxy must not leak that). An out-of-scope collection call simply rejects
+ * when the host denies it.
+ */
+declare function buildGuestBindings(hostCall: HostCall): GuestBindings;
+//#endregion
+export { BINDINGS_TOKEN_HEADER, type DnsResolver, FRAME_MARKER, type GuestBindings, type GuestCollection, type GuestMessage, type GuestResultMessage, type GuestRpcMessage, type HostCall, type HostRpcResultMessage, HttpSandboxAdapter, type HttpSandboxAdapterOptions, type IpValidationResult, type ParsedHost, type SandboxBindingError, type SandboxBindings, type SandboxCapabilities, type SandboxRunRequest, type SandboxRunResult, buildGuestBindings, classifyIpLiteral, httpSandboxAdapter, parseHostEntry, validateEgressHosts, validateHostEgress };