sandboxedjs 0.2.0 → 0.2.3

package/README.md

@@ -43,6 +43,39 @@ npx sandboxedjs-build-wheels 4180
 See `docs/python/build-on-miss.md`, and `docs/python/compatibility.md` for what
 has been built and tested.
 
+## Outbound requests from a browser
+
+A page may read a response only from a host that sends CORS headers back, and
+most APIs send none — an `Authorization` header alone forces a preflight that
+plenty of them answer with 405. A container whose guest calls a real API
+therefore works under Node and fails in a browser, for a reason that belongs to
+the page rather than to anything in the container.
+
+Give it somewhere to send those requests instead:
+
+```bash
+npx sandboxedjs-egress 4181 --allow api.openai.com,ollama.com
+```
+
+```ts
+const box = await createContainer({
+  network: { allowOutbound: true, proxy: "http://localhost:4181" },
+});
+```
+
+Every outbound request then leaves through that endpoint, which makes it where
+CORS does not apply and hands the whole response back. Loopback stays inside
+the container, and the container's own outbound policy still applies before
+anything is handed over — a proxy widens what a *page* can reach, not what the
+container may.
+
+In production the proxy is a route on your own origin. It answers `POST` with
+`{ url, method, headers, body }` and replies `{ status, statusText, headers,
+body }`, bodies base64; `bin/sandboxedjs-egress.mjs` is a complete
+implementation in about a hundred lines. Anything that can reach it can make
+requests through it carrying whatever credentials the guest holds, so keep it
+on loopback in development and behind your own auth in production.
+
 ## Why
 
 Sometimes you need to run untrusted or generated code, give an AI agent a shell, build a

package/bin/sandboxedjs-egress.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * The outbound half of a container that runs in a browser.
+ *
+ * A page may read a response only from a host that sends CORS headers back,
+ * and most APIs send none — an `Authorization` header alone forces a preflight
+ * that plenty of them answer with 405. So a container whose guest talks to a
+ * real API works under Node and fails in a browser, for a reason that has
+ * nothing to do with the container. This is the machine that makes those
+ * requests instead, where CORS does not apply.
+ *
+ *   sandboxedjs-egress [port=4181] [--allow host,host]
+ *
+ * Point a container at it:
+ *
+ *   createContainer({ network: { allowOutbound: true, proxy: "http://localhost:4181" } });
+ *
+ * It binds loopback only, and `--allow` narrows what it will fetch. Anything
+ * that can reach this port can make requests through it, carrying whatever
+ * credentials the guest holds — so it stays on this machine.
+ */
+
+import { createServer } from "node:http";
+
+const args = process.argv.slice(2);
+const at = args.indexOf("--allow");
+const allowed = at === -1 ? null : (args[at + 1] ?? "").split(",").map((h) => h.trim()).filter(Boolean);
+const port = Number(args.find((a) => /^\d+$/.test(a)) ?? 4181);
+
+/* Hop-by-hop headers describe the connection they arrived on, not the message.
+ * Forwarding them describes this hop's framing to a server that is not on it. */
+const HOP = new Set([
+  "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+  "te", "trailer", "transfer-encoding", "upgrade", "host", "content-length",
+]);
+
+const cors = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, OPTIONS",
+  "access-control-allow-headers": "content-type",
+  "access-control-max-age": "86400",
+};
+
+const send = (res, status, body, type = "text/plain; charset=utf-8") =>
+  res.writeHead(status, { ...cors, "content-type": type }).end(body);
+
+createServer(async (req, res) => {
+  if (req.method === "OPTIONS") return res.writeHead(204, cors).end();
+  if (req.method !== "POST") return send(res, 405, "POST a JSON request here. See sandboxedjs-egress --help.");
+
+  let payload;
+  try {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch (error) {
+    return send(res, 400, `could not read the request: ${error.message}`);
+  }
+
+  let target;
+  try {
+    target = new URL(payload.url);
+  } catch {
+    return send(res, 400, `not a URL: ${payload.url}`);
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") {
+    return send(res, 400, `${target.protocol} is not a protocol this proxy speaks`);
+  }
+  if (allowed && !allowed.some((host) => target.hostname === host || target.hostname.endsWith(`.${host}`))) {
+    return send(res, 403, `${target.hostname} is not in this proxy's --allow list`);
+  }
+
+  const headers = Object.fromEntries(
+    Object.entries(payload.headers ?? {}).filter(([name]) => !HOP.has(name.toLowerCase())),
+  );
+  try {
+    const answer = await fetch(target, {
+      method: payload.method ?? "GET",
+      headers,
+      ...(payload.body ? { body: Buffer.from(payload.body, "base64") } : {}),
+      redirect: "follow",
+    });
+    const body = Buffer.from(await answer.arrayBuffer());
+    const back = {};
+    answer.headers.forEach((value, name) => {
+      if (!HOP.has(name.toLowerCase())) back[name] = value;
+    });
+    console.log(`${payload.method ?? "GET"} ${target.href} -> ${answer.status} (${body.length} bytes)`);
+    send(res, 200, JSON.stringify({
+      status: answer.status,
+      statusText: answer.statusText,
+      headers: back,
+      body: body.toString("base64"),
+    }), "application/json");
+  } catch (error) {
+    console.error(`${payload.method ?? "GET"} ${target.href} -> ${error.message}`);
+    send(res, 502, `the request to ${target.hostname} failed: ${error.message}`);
+  }
+}).listen(port, "127.0.0.1", () => {
+  console.log(`sandboxedjs-egress on http://localhost:${port}${allowed ? ` (allowing ${allowed.join(", ")})` : ""}`);
+  console.log(`  createContainer({ network: { allowOutbound: true, proxy: "http://localhost:${port}" } })`);
+});

package/dist/agent.d.cts

@@ -1,4 +1,4 @@
-import { C as Container } from './container-CPwyHoUy.cjs';
+import { C as Container } from './container-C9Y8dqos.cjs';
 import './contracts-B6SHFjma.cjs';
 
 /**

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import { C as Container } from './container-CFieZcbe.js';
+import { C as Container } from './container-CIE93_Gh.js';
 import './contracts-B6SHFjma.js';
 
 /**

package/dist/{container-CPwyHoUy.d.cts → container-C9Y8dqos.d.cts}

@@ -461,6 +461,26 @@ interface NetworkOptions {
     allowOutbound?: boolean;
     /** Host allowlist applied when `allowOutbound` is on. `null` means any host. */
     allowedHosts?: string[] | null;
+    /**
+     * A URL that performs this container's outbound requests on its behalf.
+     *
+     * In a browser the container's only way out is the page's `fetch`, and a
+     * page may read a response only from a host that sends CORS headers back.
+     * Most APIs do not — an `Authorization` header alone forces a preflight that
+     * plenty of them answer with 405 — so a container that works under Node
+     * fails in a browser at the first real API call, for a reason that belongs
+     * to the page rather than to anything in here.
+     *
+     * A proxy is the way out of that: a server on an origin the page is allowed
+     * to read, which makes the request where CORS does not apply and hands the
+     * whole response back. `sandboxedjs-egress` is one; any endpoint speaking
+     * the same small JSON protocol will do.
+     *
+     * Loopback requests never reach it — those are the container's own servers —
+     * and the outbound policy is applied before a request is handed over, so a
+     * proxy widens what a page can reach, not what the container may.
+     */
+    proxy?: string;
     /** Address handed to eth0. */
     ipv4?: string;
     gateway?: string;
@@ -494,6 +514,8 @@ declare class NetworkStack {
     /** The policy every way out of the container applies, not only the shell's. */
     get policy(): OutboundPolicy;
     outboundAllowed(url: string): boolean;
+    /** The endpoint outbound requests are handed to, when the host named one. */
+    get proxy(): string | null;
     procNetDev(): string;
     procNetRoute(): string;
     countTx(bytes: number, iface?: string): void;

package/dist/{container-CFieZcbe.d.ts → container-CIE93_Gh.d.ts}

@@ -461,6 +461,26 @@ interface NetworkOptions {
     allowOutbound?: boolean;
     /** Host allowlist applied when `allowOutbound` is on. `null` means any host. */
     allowedHosts?: string[] | null;
+    /**
+     * A URL that performs this container's outbound requests on its behalf.
+     *
+     * In a browser the container's only way out is the page's `fetch`, and a
+     * page may read a response only from a host that sends CORS headers back.
+     * Most APIs do not — an `Authorization` header alone forces a preflight that
+     * plenty of them answer with 405 — so a container that works under Node
+     * fails in a browser at the first real API call, for a reason that belongs
+     * to the page rather than to anything in here.
+     *
+     * A proxy is the way out of that: a server on an origin the page is allowed
+     * to read, which makes the request where CORS does not apply and hands the
+     * whole response back. `sandboxedjs-egress` is one; any endpoint speaking
+     * the same small JSON protocol will do.
+     *
+     * Loopback requests never reach it — those are the container's own servers —
+     * and the outbound policy is applied before a request is handed over, so a
+     * proxy widens what a page can reach, not what the container may.
+     */
+    proxy?: string;
     /** Address handed to eth0. */
     ipv4?: string;
     gateway?: string;
@@ -494,6 +514,8 @@ declare class NetworkStack {
     /** The policy every way out of the container applies, not only the shell's. */
     get policy(): OutboundPolicy;
     outboundAllowed(url: string): boolean;
+    /** The endpoint outbound requests are handed to, when the host named one. */
+    get proxy(): string | null;
     procNetDev(): string;
     procNetRoute(): string;
     countTx(bytes: number, iface?: string): void;

package/dist/index.cjs

@@ -8453,6 +8453,7 @@ var NetworkStack = class {
     this.options = {
       allowOutbound: options.allowOutbound ?? false,
       allowedHosts: options.allowedHosts ?? null,
+      ...options.proxy ? { proxy: options.proxy } : {},
       ipv4: options.ipv4 ?? "172.17.0.2",
       gateway: options.gateway ?? "172.17.0.1"
     };
@@ -8590,6 +8591,10 @@ var NetworkStack = class {
   outboundAllowed(url) {
     return outboundAllowed(this.policy, url);
   }
+  /** The endpoint outbound requests are handed to, when the host named one. */
+  get proxy() {
+    return this.options.proxy ?? null;
+  }
   // ── /proc plumbing ───────────────────────────────────────────────────────
   procNetDev() {
     let out = "Inter-|   Receive                                                |  Transmit\n";
@@ -17498,6 +17503,8 @@ async function performRequest(ctx, url, init) {
       `outbound network access to ${url.hostname} is disabled for this container (enable with network: { allowOutbound: true })`
     );
   }
+  const proxy = ctx.kernel.net.proxy;
+  if (proxy) return await proxyRequest(ctx, proxy, url, init);
   let response;
   try {
     response = await fetch(url.toString(), {
@@ -17507,7 +17514,7 @@ async function performRequest(ctx, url, init) {
     });
   } catch (error) {
     throw isBrowser() ? new Error(
-      `${error instanceof Error ? error.message : String(error)} \u2014 the request to ${url.hostname} was blocked by the browser. A page can only read a response from a host that sends CORS headers; route it through a proxy on your own origin, or run the container on a server.`
+      `${error instanceof Error ? error.message : String(error)} \u2014 the request to ${url.hostname} was blocked by the browser. A page can only read a response from a host that sends CORS headers, and most APIs send none. Give the container a proxy that makes the request for it \u2014 network: { proxy }, and \`npx sandboxedjs-egress\` is one \u2014 or run the container on a server.`
     ) : error;
   }
   const body = new Uint8Array(await response.arrayBuffer());
@@ -17518,6 +17525,53 @@ async function performRequest(ctx, url, init) {
   });
   return { status: response.status, statusText: response.statusText, headers, body, url: response.url || url.toString() };
 }
+async function proxyRequest(ctx, proxy, url, init) {
+  let answer;
+  try {
+    answer = await fetch(proxy, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        url: url.toString(),
+        method: init.method,
+        headers: init.headers,
+        ...init.body?.length ? { body: toBase64(init.body) } : {}
+      })
+    });
+  } catch (error) {
+    throw new Error(
+      `the egress proxy at ${proxy} could not be reached (${error instanceof Error ? error.message : String(error)}). It performs this container's outbound requests, so nothing leaves until it answers.`
+    );
+  }
+  if (!answer.ok) {
+    throw new Error(
+      `the egress proxy at ${proxy} refused ${init.method} ${url.toString()} with ${answer.status} ${answer.statusText}: ${(await answer.text()).trim().slice(0, 300)}`
+    );
+  }
+  const payload = await answer.json();
+  const body = payload.body ? fromBase64(payload.body) : new Uint8Array(0);
+  ctx.kernel.net.countRx(body.length);
+  return {
+    status: payload.status ?? 200,
+    statusText: payload.statusText ?? "",
+    headers: payload.headers ?? {},
+    body,
+    url: url.toString()
+  };
+}
+function toBase64(bytes2) {
+  let text2 = "";
+  for (let at = 0; at < bytes2.length; at += 32768) {
+    text2 += String.fromCharCode(...bytes2.subarray(at, at + 32768));
+  }
+  return btoa(text2);
+}
+function fromBase64(text2) {
+  const binary = atob(text2);
+  const bytes2 = new Uint8Array(binary.length);
+  for (let at = 0; at < binary.length; at += 1) bytes2[at] = binary.charCodeAt(at);
+  return bytes2;
+}
 var curl = defineCommand({
   name: "curl",
   path: "/usr/bin/curl",
@@ -20959,7 +21013,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.2.3"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {
@@ -24320,7 +24374,7 @@ async function runOwnedPython(ctx, argv) {
     }
   } catch {
   }
-  if (ctx.kernel.pod.sockets?.outbound) env2.SBX_OUTBOUND_SOCKETS = "1";
+  if (ctx.kernel.pod.sockets?.outbound && !ctx.kernel.net.proxy) env2.SBX_OUTBOUND_SOCKETS = "1";
   env2.SBX_SERIAL_HOST_CALLS = "1";
   const inherit = claimInheritance(env2);
   const process2 = await startPythonProcess({

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as Shell, a as ShellIO, b as Session, N as Node, c as Command, K as Kernel, E as ExecContext, O as OutputStream, C as Container, B as BinaryBackend, d as createContainer } from './container-CPwyHoUy.cjs';
-export { e as BinaryExecutionRegistry, f as BinaryInfo, g as BinaryRequest, h as BufferSink, i as CallbackSink, j as CommandRegistry, k as ContainerFs, l as ContainerOptions, m as ContextInit, n as Env, o as ExecOptions, p as ExecResult, q as ExecutionDecision, r as ExecutionTier, F as FileData, s as FileInput, t as FileOutput, G as GroupEntry, H as HttpResponse, I as InputStream, J as Job, u as KernelOptions, L as ListeningPort, M as MANIFEST_FORMAT, v as MANIFEST_SCHEMA_VERSION, w as MountEntry, x as NetInterface, y as NetworkOptions, z as NetworkStack, A as NullInput, D as NullOutput, P as PYTHON_VERSION, Q as PasswdEntry, R as Pipe, T as Preparation, U as PreparedBinary, V as Process, W as ProcessKind, X as ProcessOptions, Y as ProcessState, Z as ProcessTable, _ as PythonCapabilities, $ as PythonOptions, a0 as PythonProfile, a1 as PythonRuntimeManifest, a2 as ResolvedExecutable, a3 as RunOptions, a4 as RunResult, a5 as SessionInit, a6 as SessionResult, a7 as SessionRunOptions, a8 as ShellExit, a9 as ShellInit, aa as ShellOptions, ab as SpawnHandle, ac as Stdio, ad as TeeOutput, ae as UserDatabase, af as Variables, ag as WasmCommandArtifact, ah as WasmTranslator, ai as binaryDigest, aj as braceExpand, ak as captureStdio, al as configurePython, am as createContext, an as createTranslationBackend, ao as createWasmCompatibilityBackend, ap as defineCommand, aq as expandWord, ar as expandWords, as as inspectElf, at as installWasmCommands, au as isElfBinary, av as isPythonAvailable, aw as resetPidCounter, ax as shellQuote, ay as validateManifest } from './container-CPwyHoUy.cjs';
+import { S as Shell, a as ShellIO, b as Session, N as Node, c as Command, K as Kernel, E as ExecContext, O as OutputStream, C as Container, B as BinaryBackend, d as createContainer } from './container-C9Y8dqos.cjs';
+export { e as BinaryExecutionRegistry, f as BinaryInfo, g as BinaryRequest, h as BufferSink, i as CallbackSink, j as CommandRegistry, k as ContainerFs, l as ContainerOptions, m as ContextInit, n as Env, o as ExecOptions, p as ExecResult, q as ExecutionDecision, r as ExecutionTier, F as FileData, s as FileInput, t as FileOutput, G as GroupEntry, H as HttpResponse, I as InputStream, J as Job, u as KernelOptions, L as ListeningPort, M as MANIFEST_FORMAT, v as MANIFEST_SCHEMA_VERSION, w as MountEntry, x as NetInterface, y as NetworkOptions, z as NetworkStack, A as NullInput, D as NullOutput, P as PYTHON_VERSION, Q as PasswdEntry, R as Pipe, T as Preparation, U as PreparedBinary, V as Process, W as ProcessKind, X as ProcessOptions, Y as ProcessState, Z as ProcessTable, _ as PythonCapabilities, $ as PythonOptions, a0 as PythonProfile, a1 as PythonRuntimeManifest, a2 as ResolvedExecutable, a3 as RunOptions, a4 as RunResult, a5 as SessionInit, a6 as SessionResult, a7 as SessionRunOptions, a8 as ShellExit, a9 as ShellInit, aa as ShellOptions, ab as SpawnHandle, ac as Stdio, ad as TeeOutput, ae as UserDatabase, af as Variables, ag as WasmCommandArtifact, ah as WasmTranslator, ai as binaryDigest, aj as braceExpand, ak as captureStdio, al as configurePython, am as createContext, an as createTranslationBackend, ao as createWasmCompatibilityBackend, ap as defineCommand, aq as expandWord, ar as expandWords, as as inspectElf, at as installWasmCommands, au as isElfBinary, av as isPythonAvailable, aw as resetPidCounter, ax as shellQuote, ay as validateManifest } from './container-C9Y8dqos.cjs';
 import { V as Vfs, C as Cred, R as RuntimeVolume, a as VirtualTcpNetwork, b as RuntimeHttpResponse, O as OutboundPolicy, S as SpawnChild, c as SyncSpawn, I as IpcTransport, d as VolumeStat, e as VolumeStats, f as RuntimePod, g as RuntimePackageInstaller, h as ChildSpawnConfig, i as ChildHandle, j as RuntimeProcess, k as RuntimeSocketPeer, l as RuntimeConnection } from './contracts-B6SHFjma.cjs';
 export { D as DirEntry, m as ROOT_CRED, n as RuntimeProcessManager, o as RuntimeProcessResult, p as Stats, q as VirtualNode, r as VirtualProvider, W as WriteOptions, s as applyChmod, t as createChildProcessModule, u as formatMode, v as makeCred, w as octalMode, x as parseUmask } from './contracts-B6SHFjma.cjs';
 import { M as MemoryVolume, a as MemoryVolumeSnapshotEntry } from './memory-volume-CRhXUyCN.cjs';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Shell, a as ShellIO, b as Session, N as Node, c as Command, K as Kernel, E as ExecContext, O as OutputStream, C as Container, B as BinaryBackend, d as createContainer } from './container-CFieZcbe.js';
-export { e as BinaryExecutionRegistry, f as BinaryInfo, g as BinaryRequest, h as BufferSink, i as CallbackSink, j as CommandRegistry, k as ContainerFs, l as ContainerOptions, m as ContextInit, n as Env, o as ExecOptions, p as ExecResult, q as ExecutionDecision, r as ExecutionTier, F as FileData, s as FileInput, t as FileOutput, G as GroupEntry, H as HttpResponse, I as InputStream, J as Job, u as KernelOptions, L as ListeningPort, M as MANIFEST_FORMAT, v as MANIFEST_SCHEMA_VERSION, w as MountEntry, x as NetInterface, y as NetworkOptions, z as NetworkStack, A as NullInput, D as NullOutput, P as PYTHON_VERSION, Q as PasswdEntry, R as Pipe, T as Preparation, U as PreparedBinary, V as Process, W as ProcessKind, X as ProcessOptions, Y as ProcessState, Z as ProcessTable, _ as PythonCapabilities, $ as PythonOptions, a0 as PythonProfile, a1 as PythonRuntimeManifest, a2 as ResolvedExecutable, a3 as RunOptions, a4 as RunResult, a5 as SessionInit, a6 as SessionResult, a7 as SessionRunOptions, a8 as ShellExit, a9 as ShellInit, aa as ShellOptions, ab as SpawnHandle, ac as Stdio, ad as TeeOutput, ae as UserDatabase, af as Variables, ag as WasmCommandArtifact, ah as WasmTranslator, ai as binaryDigest, aj as braceExpand, ak as captureStdio, al as configurePython, am as createContext, an as createTranslationBackend, ao as createWasmCompatibilityBackend, ap as defineCommand, aq as expandWord, ar as expandWords, as as inspectElf, at as installWasmCommands, au as isElfBinary, av as isPythonAvailable, aw as resetPidCounter, ax as shellQuote, ay as validateManifest } from './container-CFieZcbe.js';
+import { S as Shell, a as ShellIO, b as Session, N as Node, c as Command, K as Kernel, E as ExecContext, O as OutputStream, C as Container, B as BinaryBackend, d as createContainer } from './container-CIE93_Gh.js';
+export { e as BinaryExecutionRegistry, f as BinaryInfo, g as BinaryRequest, h as BufferSink, i as CallbackSink, j as CommandRegistry, k as ContainerFs, l as ContainerOptions, m as ContextInit, n as Env, o as ExecOptions, p as ExecResult, q as ExecutionDecision, r as ExecutionTier, F as FileData, s as FileInput, t as FileOutput, G as GroupEntry, H as HttpResponse, I as InputStream, J as Job, u as KernelOptions, L as ListeningPort, M as MANIFEST_FORMAT, v as MANIFEST_SCHEMA_VERSION, w as MountEntry, x as NetInterface, y as NetworkOptions, z as NetworkStack, A as NullInput, D as NullOutput, P as PYTHON_VERSION, Q as PasswdEntry, R as Pipe, T as Preparation, U as PreparedBinary, V as Process, W as ProcessKind, X as ProcessOptions, Y as ProcessState, Z as ProcessTable, _ as PythonCapabilities, $ as PythonOptions, a0 as PythonProfile, a1 as PythonRuntimeManifest, a2 as ResolvedExecutable, a3 as RunOptions, a4 as RunResult, a5 as SessionInit, a6 as SessionResult, a7 as SessionRunOptions, a8 as ShellExit, a9 as ShellInit, aa as ShellOptions, ab as SpawnHandle, ac as Stdio, ad as TeeOutput, ae as UserDatabase, af as Variables, ag as WasmCommandArtifact, ah as WasmTranslator, ai as binaryDigest, aj as braceExpand, ak as captureStdio, al as configurePython, am as createContext, an as createTranslationBackend, ao as createWasmCompatibilityBackend, ap as defineCommand, aq as expandWord, ar as expandWords, as as inspectElf, at as installWasmCommands, au as isElfBinary, av as isPythonAvailable, aw as resetPidCounter, ax as shellQuote, ay as validateManifest } from './container-CIE93_Gh.js';
 import { V as Vfs, C as Cred, R as RuntimeVolume, a as VirtualTcpNetwork, b as RuntimeHttpResponse, O as OutboundPolicy, S as SpawnChild, c as SyncSpawn, I as IpcTransport, d as VolumeStat, e as VolumeStats, f as RuntimePod, g as RuntimePackageInstaller, h as ChildSpawnConfig, i as ChildHandle, j as RuntimeProcess, k as RuntimeSocketPeer, l as RuntimeConnection } from './contracts-B6SHFjma.js';
 export { D as DirEntry, m as ROOT_CRED, n as RuntimeProcessManager, o as RuntimeProcessResult, p as Stats, q as VirtualNode, r as VirtualProvider, W as WriteOptions, s as applyChmod, t as createChildProcessModule, u as formatMode, v as makeCred, w as octalMode, x as parseUmask } from './contracts-B6SHFjma.js';
 import { M as MemoryVolume, a as MemoryVolumeSnapshotEntry } from './memory-volume-CwiXvRfs.js';

package/dist/index.js

@@ -8436,6 +8436,7 @@ var NetworkStack = class {
     this.options = {
       allowOutbound: options.allowOutbound ?? false,
       allowedHosts: options.allowedHosts ?? null,
+      ...options.proxy ? { proxy: options.proxy } : {},
       ipv4: options.ipv4 ?? "172.17.0.2",
       gateway: options.gateway ?? "172.17.0.1"
     };
@@ -8573,6 +8574,10 @@ var NetworkStack = class {
   outboundAllowed(url) {
     return outboundAllowed(this.policy, url);
   }
+  /** The endpoint outbound requests are handed to, when the host named one. */
+  get proxy() {
+    return this.options.proxy ?? null;
+  }
   // ── /proc plumbing ───────────────────────────────────────────────────────
   procNetDev() {
     let out = "Inter-|   Receive                                                |  Transmit\n";
@@ -17481,6 +17486,8 @@ async function performRequest(ctx, url, init) {
       `outbound network access to ${url.hostname} is disabled for this container (enable with network: { allowOutbound: true })`
     );
   }
+  const proxy = ctx.kernel.net.proxy;
+  if (proxy) return await proxyRequest(ctx, proxy, url, init);
   let response;
   try {
     response = await fetch(url.toString(), {
@@ -17490,7 +17497,7 @@ async function performRequest(ctx, url, init) {
     });
   } catch (error) {
     throw isBrowser() ? new Error(
-      `${error instanceof Error ? error.message : String(error)} \u2014 the request to ${url.hostname} was blocked by the browser. A page can only read a response from a host that sends CORS headers; route it through a proxy on your own origin, or run the container on a server.`
+      `${error instanceof Error ? error.message : String(error)} \u2014 the request to ${url.hostname} was blocked by the browser. A page can only read a response from a host that sends CORS headers, and most APIs send none. Give the container a proxy that makes the request for it \u2014 network: { proxy }, and \`npx sandboxedjs-egress\` is one \u2014 or run the container on a server.`
     ) : error;
   }
   const body = new Uint8Array(await response.arrayBuffer());
@@ -17501,6 +17508,53 @@ async function performRequest(ctx, url, init) {
   });
   return { status: response.status, statusText: response.statusText, headers, body, url: response.url || url.toString() };
 }
+async function proxyRequest(ctx, proxy, url, init) {
+  let answer;
+  try {
+    answer = await fetch(proxy, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        url: url.toString(),
+        method: init.method,
+        headers: init.headers,
+        ...init.body?.length ? { body: toBase64(init.body) } : {}
+      })
+    });
+  } catch (error) {
+    throw new Error(
+      `the egress proxy at ${proxy} could not be reached (${error instanceof Error ? error.message : String(error)}). It performs this container's outbound requests, so nothing leaves until it answers.`
+    );
+  }
+  if (!answer.ok) {
+    throw new Error(
+      `the egress proxy at ${proxy} refused ${init.method} ${url.toString()} with ${answer.status} ${answer.statusText}: ${(await answer.text()).trim().slice(0, 300)}`
+    );
+  }
+  const payload = await answer.json();
+  const body = payload.body ? fromBase64(payload.body) : new Uint8Array(0);
+  ctx.kernel.net.countRx(body.length);
+  return {
+    status: payload.status ?? 200,
+    statusText: payload.statusText ?? "",
+    headers: payload.headers ?? {},
+    body,
+    url: url.toString()
+  };
+}
+function toBase64(bytes2) {
+  let text2 = "";
+  for (let at = 0; at < bytes2.length; at += 32768) {
+    text2 += String.fromCharCode(...bytes2.subarray(at, at + 32768));
+  }
+  return btoa(text2);
+}
+function fromBase64(text2) {
+  const binary = atob(text2);
+  const bytes2 = new Uint8Array(binary.length);
+  for (let at = 0; at < binary.length; at += 1) bytes2[at] = binary.charCodeAt(at);
+  return bytes2;
+}
 var curl = defineCommand({
   name: "curl",
   path: "/usr/bin/curl",
@@ -20942,7 +20996,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.2.3"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {
@@ -24303,7 +24357,7 @@ async function runOwnedPython(ctx, argv) {
     }
   } catch {
   }
-  if (ctx.kernel.pod.sockets?.outbound) env2.SBX_OUTBOUND_SOCKETS = "1";
+  if (ctx.kernel.pod.sockets?.outbound && !ctx.kernel.net.proxy) env2.SBX_OUTBOUND_SOCKETS = "1";
   env2.SBX_SERIAL_HOST_CALLS = "1";
   const inherit = claimInheritance(env2);
   const process2 = await startPythonProcess({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxedjs",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "A Linux-like container that runs entirely inside Node.js — POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "sbx": "bin/sandboxedjs.mjs",
     "sandboxedjs-serve": "bin/sandboxedjs-serve.mjs",
     "sandboxedjs-build-wheels": "bin/sandboxedjs-build-wheels.mjs",
+    "sandboxedjs-egress": "bin/sandboxedjs-egress.mjs",
     "sandboxedjs-pack": "bin/sandboxedjs-pack.mjs"
   },
   "exports": {