sandboxedjs 0.2.4 → 0.2.5

package/README.md

@@ -51,7 +51,8 @@ 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:
+Give it somewhere to send those requests instead. In development that is a
+process:
 
 ```bash
 npx sandboxedjs-egress 4181 --allow api.openai.com,ollama.com
@@ -63,18 +64,48 @@ const box = await createContainer({
 });
 ```
 
-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.
+In an app that already has a server, mount it there instead — the container
+then calls its own origin, so there is no second port and no CORS on the proxy
+itself:
+
+```ts
+import { egressNodeHandler } from "sandboxedjs/egress";
+app.post("/egress", egressNodeHandler({ allow: ["ollama.com"] }));
+// createContainer({ network: { allowOutbound: true, proxy: "/egress" } })
+```
+
+A static site has no server, which is what the `Request` form is for — a
+Cloudflare Pages Function, a Worker, a route handler:
+
+```ts
+// functions/egress.ts
+import { handleEgressRequest } from "sandboxedjs/egress";
+export const onRequest = ({ request }) => handleEgressRequest(request, { allow: ["ollama.com"] });
+```
+
+Every exit honours it — `curl`, `wget`, a guest's own `fetch`, and Python's
+sockets — so it means the same thing whatever the project is written in.
+Loopback stays inside the container, and the container's outbound policy still
+applies before anything is handed over: a proxy widens what a *page* can reach,
+not what the container may.
+
+Anything that can reach the proxy can make requests through it carrying
+whatever credentials the guest holds, so keep `--allow` set, keep it on
+loopback in development, and put it behind your own authentication in
+production.
+
+## Servers inside the container
+
+A project split into a frontend and a backend calls `http://localhost:8000/api`
+from the frontend. That address is true inside the container and is what the
+project uses everywhere else, so it is left exactly as written: a script in
+each previewed page rewrites loopback addresses to the preview's own origin,
+and the service worker routes them by the port in the path.
+
+That works between pages of the preview, and from another tab of the same
+browser while the page holding the container is open. It does not work from
+outside that browser — Postman, curl, another machine — because the container
+is the tab. There is no server anywhere to reach.
 
 ## Why
 

package/bin/sandboxedjs-egress.mjs

@@ -21,82 +21,21 @@
  */
 
 import { createServer } from "node:http";
+import { egressNodeHandler } from "../dist/egress.js";
 
 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 allow = at === -1 ? undefined : (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);
+const handle = egressNodeHandler({ ...(allow ? { allow } : {}) });
 
 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}`);
-  }
+  const started = Date.now();
+  await handle(req, res);
+  console.log(`${req.method} -> ${res.statusCode} (${Date.now() - started}ms)`);
 }).listen(port, "127.0.0.1", () => {
-  console.log(`sandboxedjs-egress on http://localhost:${port}${allowed ? ` (allowing ${allowed.join(", ")})` : ""}`);
+  console.log(`sandboxedjs-egress on http://localhost:${port}${allow ? ` (allowing ${allow.join(", ")})` : ""}`);
   console.log(`  createContainer({ network: { allowOutbound: true, proxy: "http://localhost:${port}" } })`);
+  console.log("  or mount it in your own app: import { egressNodeHandler } from \"sandboxedjs/egress\"");
 });

package/dist/agent.d.cts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-DJfFjito.cjs';
-import './contracts-CXZ_25-O.cjs';
+import { C as Container } from './container-BQx27_d-.cjs';
+import './contracts-BHo4LdY2.cjs';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-C16pCOWC.js';
-import './contracts-CXZ_25-O.js';
+import { C as Container } from './container-D-e5SMXQ.js';
+import './contracts-BHo4LdY2.js';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/{container-C16pCOWC.d.ts → container-BQx27_d-.d.cts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-CXZ_25-O.js';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-BHo4LdY2.cjs';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.

package/dist/{container-DJfFjito.d.cts → container-D-e5SMXQ.d.ts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-CXZ_25-O.cjs';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-BHo4LdY2.js';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.

package/dist/{contracts-CXZ_25-O.d.cts → contracts-BHo4LdY2.d.cts}

@@ -114,6 +114,15 @@ interface OutboundPolicy {
     allowOutbound: boolean;
     /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
     allowedHosts: string[] | null;
+    /**
+     * A URL that performs this container's outbound requests on its behalf.
+     *
+     * Carried with the policy rather than beside it, because every exit has to
+     * honour it: `curl`, the Python egress and a guest's own `fetch` all leave
+     * the same way, and a proxy that covered only some of them would be a
+     * setting whose meaning depended on which language the guest was written in.
+     */
+    proxy?: string;
 }
 
 /**

package/dist/{contracts-CXZ_25-O.d.ts → contracts-BHo4LdY2.d.ts}

@@ -114,6 +114,15 @@ interface OutboundPolicy {
     allowOutbound: boolean;
     /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
     allowedHosts: string[] | null;
+    /**
+     * A URL that performs this container's outbound requests on its behalf.
+     *
+     * Carried with the policy rather than beside it, because every exit has to
+     * honour it: `curl`, the Python egress and a guest's own `fetch` all leave
+     * the same way, and a proxy that covered only some of them would be a
+     * setting whose meaning depended on which language the guest was written in.
+     */
+    proxy?: string;
 }
 
 /**

package/dist/egress.cjs

@@ -0,0 +1,127 @@
+'use strict';
+
+// src/net/proxy-fetch.ts
+function toBase64(bytes) {
+  let text = "";
+  for (let at = 0; at < bytes.length; at += 32768) {
+    text += String.fromCharCode(...bytes.subarray(at, at + 32768));
+  }
+  return btoa(text);
+}
+function fromBase64(text) {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let at = 0; at < binary.length; at += 1) bytes[at] = binary.charCodeAt(at);
+  return bytes;
+}
+
+// src/net/egress-handler.ts
+var HOP = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length"
+]);
+var HEADERS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, OPTIONS",
+  "access-control-allow-headers": "content-type",
+  "access-control-max-age": "86400",
+  "cross-origin-resource-policy": "cross-origin"
+};
+var refuse = (status, message) => new Response(message, { status, headers: { ...HEADERS, "content-type": "text/plain; charset=utf-8" } });
+async function handleEgressRequest(request, options = {}) {
+  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: HEADERS });
+  if (request.method !== "POST") return refuse(405, "POST a JSON request here.");
+  let payload;
+  try {
+    payload = await request.json();
+  } catch (error) {
+    return refuse(400, `could not read the request: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let target;
+  try {
+    target = new URL(String(payload.url));
+  } catch {
+    return refuse(400, `not a URL: ${payload.url}`);
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") {
+    return refuse(400, `${target.protocol} is not a protocol this proxy speaks`);
+  }
+  const allow = options.allow;
+  if (allow && !allow.some((host) => target.hostname === host || target.hostname.endsWith(`.${host}`))) {
+    return refuse(403, `${target.hostname} is not in this proxy's allow list`);
+  }
+  const headers = {};
+  for (const [name, value] of Object.entries(payload.headers ?? {})) {
+    if (!HOP.has(name.toLowerCase())) headers[name] = value;
+  }
+  const perform = options.fetch ?? fetch;
+  let answer;
+  try {
+    answer = await perform(target.toString(), {
+      method: payload.method ?? "GET",
+      headers,
+      ...payload.body ? { body: fromBase64(payload.body) } : {},
+      redirect: "follow"
+    });
+  } catch (error) {
+    return refuse(502, `the request to ${target.hostname} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const back = {};
+  answer.headers.forEach((value, name) => {
+    if (!HOP.has(name.toLowerCase())) back[name] = value;
+  });
+  const body = new Uint8Array(await answer.arrayBuffer());
+  return new Response(
+    JSON.stringify({ status: answer.status, statusText: answer.statusText, headers: back, body: toBase64(body) }),
+    { headers: { ...HEADERS, "content-type": "application/json" } }
+  );
+}
+function egressNodeHandler(options = {}) {
+  return async (request, response) => {
+    const chunks = [];
+    await new Promise((done, fail) => {
+      request.on("data", (chunk) => chunks.push(chunk));
+      request.on("end", () => done());
+      request.on("error", (error) => fail(error));
+    });
+    let total = 0;
+    for (const chunk of chunks) total += chunk.length;
+    const body = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+      body.set(chunk, at);
+      at += chunk.length;
+    }
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers)) {
+      if (typeof value === "string") headers[name] = value;
+    }
+    const answer = await handleEgressRequest(
+      new Request("http://egress.invalid/", {
+        method: request.method ?? "GET",
+        headers,
+        ...body.length && request.method !== "GET" && request.method !== "HEAD" ? { body } : {}
+      }),
+      options
+    );
+    const out = {};
+    answer.headers.forEach((value, name) => {
+      out[name] = value;
+    });
+    response.writeHead(answer.status, out);
+    response.end(Buffer.from(await answer.arrayBuffer()));
+  };
+}
+
+exports.egressNodeHandler = egressNodeHandler;
+exports.handleEgressRequest = handleEgressRequest;
+//# sourceMappingURL=egress.cjs.map
+//# sourceMappingURL=egress.cjs.map

package/dist/egress.d.cts

@@ -0,0 +1,51 @@
+/**
+ * The proxy, as something a host app can mount instead of run.
+ *
+ * `sandboxedjs-egress` is a whole process, which suits a terminal and suits
+ * nothing else. A host app usually already has a server — an Express route, a
+ * Cloudflare Pages Function, a Worker — and mounting the proxy there is better
+ * than standing another one beside it: the container then calls its own
+ * origin, so there is no second port to start, no CORS on the proxy itself,
+ * and one thing to deploy rather than two.
+ *
+ * A static site has no server at all, which is the case this exists for. Those
+ * hosts all take a function of a `Request`, so that is the shape here, with a
+ * Node adapter for hosts that predate it.
+ *
+ *     // Cloudflare Pages: functions/egress.ts
+ *     import { handleEgressRequest } from "sandboxedjs/egress";
+ *     export const onRequest = ({ request }) =>
+ *       handleEgressRequest(request, { allow: ["ollama.com"] });
+ *
+ * Anything that can reach this can make requests through it, carrying whatever
+ * credentials the guest holds. `allow` is the limit on where those go, and on
+ * a public deployment it should be set and the route should be behind whatever
+ * authentication the rest of the app uses.
+ */
+interface EgressOptions {
+    /** Hosts this proxy will fetch, subdomains included. Unset means any. */
+    allow?: string[];
+    /** The `fetch` used to make the real request. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Answer one proxied request. Safe to mount wherever a `Request` arrives. */
+declare function handleEgressRequest(request: Request, options?: EgressOptions): Promise<Response>;
+/** Minimal shapes of Node's request and response, so this needs no `@types/node`. */
+interface NodeRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: string, listener: (chunk?: unknown) => void): unknown;
+}
+interface NodeResponse {
+    writeHead(status: number, headers: Record<string, string>): unknown;
+    end(body?: unknown): unknown;
+}
+/**
+ * The same handler for Express and `node:http`.
+ *
+ *     app.post("/egress", egressNodeHandler({ allow: ["ollama.com"] }));
+ */
+declare function egressNodeHandler(options?: EgressOptions): (request: NodeRequest, response: NodeResponse) => Promise<void>;
+
+export { type EgressOptions, egressNodeHandler, handleEgressRequest };

package/dist/egress.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The proxy, as something a host app can mount instead of run.
+ *
+ * `sandboxedjs-egress` is a whole process, which suits a terminal and suits
+ * nothing else. A host app usually already has a server — an Express route, a
+ * Cloudflare Pages Function, a Worker — and mounting the proxy there is better
+ * than standing another one beside it: the container then calls its own
+ * origin, so there is no second port to start, no CORS on the proxy itself,
+ * and one thing to deploy rather than two.
+ *
+ * A static site has no server at all, which is the case this exists for. Those
+ * hosts all take a function of a `Request`, so that is the shape here, with a
+ * Node adapter for hosts that predate it.
+ *
+ *     // Cloudflare Pages: functions/egress.ts
+ *     import { handleEgressRequest } from "sandboxedjs/egress";
+ *     export const onRequest = ({ request }) =>
+ *       handleEgressRequest(request, { allow: ["ollama.com"] });
+ *
+ * Anything that can reach this can make requests through it, carrying whatever
+ * credentials the guest holds. `allow` is the limit on where those go, and on
+ * a public deployment it should be set and the route should be behind whatever
+ * authentication the rest of the app uses.
+ */
+interface EgressOptions {
+    /** Hosts this proxy will fetch, subdomains included. Unset means any. */
+    allow?: string[];
+    /** The `fetch` used to make the real request. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Answer one proxied request. Safe to mount wherever a `Request` arrives. */
+declare function handleEgressRequest(request: Request, options?: EgressOptions): Promise<Response>;
+/** Minimal shapes of Node's request and response, so this needs no `@types/node`. */
+interface NodeRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: string, listener: (chunk?: unknown) => void): unknown;
+}
+interface NodeResponse {
+    writeHead(status: number, headers: Record<string, string>): unknown;
+    end(body?: unknown): unknown;
+}
+/**
+ * The same handler for Express and `node:http`.
+ *
+ *     app.post("/egress", egressNodeHandler({ allow: ["ollama.com"] }));
+ */
+declare function egressNodeHandler(options?: EgressOptions): (request: NodeRequest, response: NodeResponse) => Promise<void>;
+
+export { type EgressOptions, egressNodeHandler, handleEgressRequest };

package/dist/egress.js

@@ -0,0 +1,124 @@
+// src/net/proxy-fetch.ts
+function toBase64(bytes) {
+  let text = "";
+  for (let at = 0; at < bytes.length; at += 32768) {
+    text += String.fromCharCode(...bytes.subarray(at, at + 32768));
+  }
+  return btoa(text);
+}
+function fromBase64(text) {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let at = 0; at < binary.length; at += 1) bytes[at] = binary.charCodeAt(at);
+  return bytes;
+}
+
+// src/net/egress-handler.ts
+var HOP = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length"
+]);
+var HEADERS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, OPTIONS",
+  "access-control-allow-headers": "content-type",
+  "access-control-max-age": "86400",
+  "cross-origin-resource-policy": "cross-origin"
+};
+var refuse = (status, message) => new Response(message, { status, headers: { ...HEADERS, "content-type": "text/plain; charset=utf-8" } });
+async function handleEgressRequest(request, options = {}) {
+  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: HEADERS });
+  if (request.method !== "POST") return refuse(405, "POST a JSON request here.");
+  let payload;
+  try {
+    payload = await request.json();
+  } catch (error) {
+    return refuse(400, `could not read the request: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let target;
+  try {
+    target = new URL(String(payload.url));
+  } catch {
+    return refuse(400, `not a URL: ${payload.url}`);
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") {
+    return refuse(400, `${target.protocol} is not a protocol this proxy speaks`);
+  }
+  const allow = options.allow;
+  if (allow && !allow.some((host) => target.hostname === host || target.hostname.endsWith(`.${host}`))) {
+    return refuse(403, `${target.hostname} is not in this proxy's allow list`);
+  }
+  const headers = {};
+  for (const [name, value] of Object.entries(payload.headers ?? {})) {
+    if (!HOP.has(name.toLowerCase())) headers[name] = value;
+  }
+  const perform = options.fetch ?? fetch;
+  let answer;
+  try {
+    answer = await perform(target.toString(), {
+      method: payload.method ?? "GET",
+      headers,
+      ...payload.body ? { body: fromBase64(payload.body) } : {},
+      redirect: "follow"
+    });
+  } catch (error) {
+    return refuse(502, `the request to ${target.hostname} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const back = {};
+  answer.headers.forEach((value, name) => {
+    if (!HOP.has(name.toLowerCase())) back[name] = value;
+  });
+  const body = new Uint8Array(await answer.arrayBuffer());
+  return new Response(
+    JSON.stringify({ status: answer.status, statusText: answer.statusText, headers: back, body: toBase64(body) }),
+    { headers: { ...HEADERS, "content-type": "application/json" } }
+  );
+}
+function egressNodeHandler(options = {}) {
+  return async (request, response) => {
+    const chunks = [];
+    await new Promise((done, fail) => {
+      request.on("data", (chunk) => chunks.push(chunk));
+      request.on("end", () => done());
+      request.on("error", (error) => fail(error));
+    });
+    let total = 0;
+    for (const chunk of chunks) total += chunk.length;
+    const body = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+      body.set(chunk, at);
+      at += chunk.length;
+    }
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers)) {
+      if (typeof value === "string") headers[name] = value;
+    }
+    const answer = await handleEgressRequest(
+      new Request("http://egress.invalid/", {
+        method: request.method ?? "GET",
+        headers,
+        ...body.length && request.method !== "GET" && request.method !== "HEAD" ? { body } : {}
+      }),
+      options
+    );
+    const out = {};
+    answer.headers.forEach((value, name) => {
+      out[name] = value;
+    });
+    response.writeHead(answer.status, out);
+    response.end(Buffer.from(await answer.arrayBuffer()));
+  };
+}
+
+export { egressNodeHandler, handleEgressRequest };
+//# sourceMappingURL=egress.js.map
+//# sourceMappingURL=egress.js.map