sandboxedjs 0.2.7 → 0.2.8

package/README.md

@@ -51,38 +51,45 @@ 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. In development that is a
-process:
+Give it somewhere to send those requests instead. Add that somewhere to the
+project that is already being deployed, and the container finds it by itself:
 
 ```bash
-npx sandboxedjs-egress 4181 --allow api.openai.com,ollama.com
+npx sandboxedjs-egress init --allow api.openai.com,ollama.com
 ```
 
-```ts
-const box = await createContainer({
-  network: { allowOutbound: true, proxy: "http://localhost:4181" },
-});
+That writes one file at the path the host platform serves — Cloudflare Pages,
+Vercel and Netlify are detected, `--target` names one — and nothing else
+changes. A container in a page probes its own origin for the proxy before it
+gives up, so no project passes `proxy` and none of them has to be told twice.
+
+In development the same proxy runs as a process, on the port the probe checks:
+
+```bash
+npx sandboxedjs-egress
 ```
 
-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:
+In an app that already has a server, mount the handler on the well-known path.
+Before any body parser: it reads the request stream itself.
 
 ```ts
-import { egressNodeHandler } from "sandboxedjs/egress";
-app.post("/egress", egressNodeHandler({ allow: ["ollama.com"] }));
-// createContainer({ network: { allowOutbound: true, proxy: "/egress" } })
+import { egressNodeHandler, EGRESS_PATH } from "sandboxedjs/egress";
+app.use(EGRESS_PATH, egressNodeHandler({ allow: ["ollama.com"] }));
 ```
 
-A static site has no server, which is what the `Request` form is for — a
-Cloudflare Pages Function, a Worker, a route handler:
+A static host takes the `Request` form — which is what `init` writes:
 
 ```ts
-// functions/egress.ts
+// functions/__sandboxedjs__/egress.ts, on Cloudflare Pages
 import { handleEgressRequest } from "sandboxedjs/egress";
 export const onRequest = ({ request }) => handleEgressRequest(request, { allow: ["ollama.com"] });
 ```
 
+`network: { proxy }` still names one explicitly — a proxy somewhere else, or
+one that discovery should not be trusted to find — and it is never overridden.
+`sandboxedjs-serve` mounts the proxy itself, so an app served by it needs none
+of this.
+
 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

package/bin/sandboxedjs-egress.mjs

@@ -21,9 +21,126 @@
  */
 
 import { createServer } from "node:http";
+import { mkdir, writeFile, access } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { egressNodeHandler } from "../dist/egress.js";
 
 const args = process.argv.slice(2);
+
+/*
+ * `sandboxedjs-egress init` — the proxy as a file in the project that is
+ * already being deployed.
+ *
+ * Running a process beside a site works on a laptop and nowhere else, and a
+ * static host has no server to add one to. What every static host does have is
+ * a functions directory, so the proxy goes there: one file, at the path the
+ * container already looks for, and a deployment that needed a setting needs
+ * nothing.
+ */
+const TARGETS = {
+  cloudflare: {
+    file: "functions/__sandboxedjs__/egress.ts",
+    detect: ["wrangler.toml", "wrangler.json", "wrangler.jsonc", "functions"],
+    source: (allow) => `import { handleEgressRequest } from "sandboxedjs/egress";
+${allow}
+/* Cloudflare Pages serves this file at /__sandboxedjs__/egress, which is where
+ * a container in this site's pages looks for its way out. */
+export const onRequest = ({ request }) => handleEgressRequest(request, options);
+`,
+  },
+  vercel: {
+    file: "api/__sandboxedjs__/egress.ts",
+    detect: ["vercel.json", "api"],
+    source: (allow) => `import { handleEgressRequest } from "sandboxedjs/egress";
+${allow}
+export const config = { runtime: "edge" };
+
+/* Vercel serves this file at /api/__sandboxedjs__/egress, which is one of the
+ * paths a container in this site's pages probes for its way out. */
+export default (request) => handleEgressRequest(request, options);
+`,
+  },
+  netlify: {
+    file: "netlify/functions/sandboxedjs-egress.ts",
+    detect: ["netlify.toml", "netlify"],
+    source: (allow) => `import { handleEgressRequest } from "sandboxedjs/egress";
+${allow}
+export const config = { path: "/.netlify/functions/sandboxedjs-egress" };
+
+export default (request) => handleEgressRequest(request, options);
+`,
+  },
+};
+
+const NODE_SNIPPET = `  import { egressNodeHandler, EGRESS_PATH } from "sandboxedjs/egress";
+  // Before any body parser: the handler reads the request stream itself.
+  app.use(EGRESS_PATH, egressNodeHandler({ allow: ["api.example.com"] }));`;
+
+async function exists(path) {
+  try { await access(path); return true; } catch { return false; }
+}
+
+async function detectTarget(root) {
+  for (const [name, target] of Object.entries(TARGETS)) {
+    for (const marker of target.detect) {
+      if (await exists(join(root, marker))) return name;
+    }
+  }
+  return null;
+}
+
+async function init(argv) {
+  const root = argv.find((a) => !a.startsWith("-")) ?? process.cwd();
+  const at = argv.indexOf("--target");
+  const allowAt = argv.indexOf("--allow");
+  const allowed = allowAt === -1
+    ? null
+    : (argv[allowAt + 1] ?? "").split(",").map((h) => h.trim()).filter(Boolean);
+  const name = at === -1 ? await detectTarget(root) : argv[at + 1];
+  if (!name || !TARGETS[name]) {
+    console.error(
+      name
+        ? `sandboxedjs-egress init: unknown target ${name}`
+        : "sandboxedjs-egress init: could not tell what this project deploys to.",
+    );
+    console.error(`Targets: ${Object.keys(TARGETS).join(", ")} (--target <name>)`);
+    console.error(`A server of your own takes the handler directly:\n\n${NODE_SNIPPET}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const target = TARGETS[name];
+  const path = join(root, target.file);
+  if (await exists(path)) {
+    console.log(`${target.file} is already there; leaving it alone.`);
+    return;
+  }
+  /* An open proxy carries whatever credentials the container holds to wherever
+   * it is asked, so the list is the limit and its absence is said out loud. */
+  const allow = allowed?.length
+    ? `\n/* The hosts this proxy will fetch, subdomains included. */\nconst options = { allow: ${JSON.stringify(allowed)} };\n`
+    : `\n/* Anything that can reach this route can make a request through it, carrying\n * whatever credentials the container holds. Narrow it before this is public:\n * const options = { allow: ["api.example.com"] };\n */\nconst options = {};\n`;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, target.source(allow));
+  console.log(`Wrote ${target.file} (${name}).`);
+  if (!allowed?.length) console.log("It will fetch any host: set `allow` in that file before deploying it publicly.");
+  console.log("Deploy it, and containers in this site's pages find it with no further configuration.");
+}
+
+if (args[0] === "init") {
+  await init(args.slice(1));
+  process.exit(process.exitCode ?? 0);
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`sandboxedjs-egress — outbound HTTP for a container that runs in a browser
+
+Usage:
+  sandboxedjs-egress [port=4181] [--allow host,host]   run the proxy here
+  sandboxedjs-egress init [dir] [--target cloudflare|vercel|netlify] [--allow host,host]
+                                                       add it to a deployment
+`);
+  process.exit(0);
+}
 const at = args.indexOf("--allow");
 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);

package/dist/index.cjs

@@ -8424,12 +8424,17 @@ function isBrowser() {
 }
 function browserBlocked(hostname, message) {
   return new Error(
-    `${message} \u2014 the request to ${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. The container looks for a proxy to make the request for it and found none: mount \`handleEgressRequest\` from "sandboxedjs/egress" at /__sandboxedjs__/egress on this origin, or run \`npx sandboxedjs-egress\`, and it is used without further configuration (network: { proxy } names one somewhere else) \u2014 or run the container on a server.`
+    `${message} \u2014 the request to ${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. The container looked on this origin for a proxy to make the request for it and found none: run \`npx sandboxedjs-egress init\` to add one to this deployment, or \`npx sandboxedjs-egress\` while developing, and it is used with no further configuration (network: { proxy } names one somewhere else) \u2014 or run the container on a server, where CORS does not apply.`
   );
 }
 
 // src/net/discover-egress.ts
 var EGRESS_PATH = "/__sandboxedjs__/egress";
+var EGRESS_PATHS = [
+  EGRESS_PATH,
+  `/api${EGRESS_PATH}`,
+  "/.netlify/functions/sandboxedjs-egress"
+];
 var EGRESS_MARKER = { sandboxedjs: "egress", protocol: 1 };
 var CLI_PORT = 4181;
 var found = null;
@@ -8451,7 +8456,7 @@ async function isEgress(url, fetchImpl) {
 function candidates() {
   const origin = globalThis.location?.origin;
   const list = [];
-  if (origin && /^https?:/.test(origin)) list.push(`${origin}${EGRESS_PATH}`);
+  if (origin && /^https?:/.test(origin)) list.push(...EGRESS_PATHS.map((path) => `${origin}${path}`));
   list.push(`http://127.0.0.1:${CLI_PORT}/`);
   return list;
 }
@@ -8459,10 +8464,10 @@ async function discoverEgress(fetchImpl = fetch) {
   if (!isBrowser()) return null;
   if (!found) {
     found = (async () => {
-      for (const candidate of candidates()) {
-        if (await isEgress(candidate, fetchImpl)) return candidate;
-      }
-      return null;
+      const list = candidates();
+      const answers = await Promise.all(list.map((candidate) => isEgress(candidate, fetchImpl)));
+      const at = answers.findIndex(Boolean);
+      return at === -1 ? null : list[at];
     })();
   }
   return await found;
@@ -21098,7 +21103,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.7"};
+  version: "0.2.8"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/dist/index.js

@@ -8407,12 +8407,17 @@ function isBrowser() {
 }
 function browserBlocked(hostname, message) {
   return new Error(
-    `${message} \u2014 the request to ${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. The container looks for a proxy to make the request for it and found none: mount \`handleEgressRequest\` from "sandboxedjs/egress" at /__sandboxedjs__/egress on this origin, or run \`npx sandboxedjs-egress\`, and it is used without further configuration (network: { proxy } names one somewhere else) \u2014 or run the container on a server.`
+    `${message} \u2014 the request to ${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. The container looked on this origin for a proxy to make the request for it and found none: run \`npx sandboxedjs-egress init\` to add one to this deployment, or \`npx sandboxedjs-egress\` while developing, and it is used with no further configuration (network: { proxy } names one somewhere else) \u2014 or run the container on a server, where CORS does not apply.`
   );
 }
 
 // src/net/discover-egress.ts
 var EGRESS_PATH = "/__sandboxedjs__/egress";
+var EGRESS_PATHS = [
+  EGRESS_PATH,
+  `/api${EGRESS_PATH}`,
+  "/.netlify/functions/sandboxedjs-egress"
+];
 var EGRESS_MARKER = { sandboxedjs: "egress", protocol: 1 };
 var CLI_PORT = 4181;
 var found = null;
@@ -8434,7 +8439,7 @@ async function isEgress(url, fetchImpl) {
 function candidates() {
   const origin = globalThis.location?.origin;
   const list = [];
-  if (origin && /^https?:/.test(origin)) list.push(`${origin}${EGRESS_PATH}`);
+  if (origin && /^https?:/.test(origin)) list.push(...EGRESS_PATHS.map((path) => `${origin}${path}`));
   list.push(`http://127.0.0.1:${CLI_PORT}/`);
   return list;
 }
@@ -8442,10 +8447,10 @@ async function discoverEgress(fetchImpl = fetch) {
   if (!isBrowser()) return null;
   if (!found) {
     found = (async () => {
-      for (const candidate of candidates()) {
-        if (await isEgress(candidate, fetchImpl)) return candidate;
-      }
-      return null;
+      const list = candidates();
+      const answers = await Promise.all(list.map((candidate) => isEgress(candidate, fetchImpl)));
+      const at = answers.findIndex(Boolean);
+      return at === -1 ? null : list[at];
     })();
   }
   return await found;
@@ -21081,7 +21086,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.7"};
+  version: "0.2.8"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/dist/worker-entry.js

@@ -28281,12 +28281,17 @@ function isBrowser() {
 }
 function browserBlocked(hostname, message) {
   return new Error(
-    `${message} \u2014 the request to ${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. The container looks for a proxy to make the request for it and found none: mount \`handleEgressRequest\` from "sandboxedjs/egress" at /__sandboxedjs__/egress on this origin, or run \`npx sandboxedjs-egress\`, and it is used without further configuration (network: { proxy } names one somewhere else) \u2014 or run the container on a server.`
+    `${message} \u2014 the request to ${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. The container looked on this origin for a proxy to make the request for it and found none: run \`npx sandboxedjs-egress init\` to add one to this deployment, or \`npx sandboxedjs-egress\` while developing, and it is used with no further configuration (network: { proxy } names one somewhere else) \u2014 or run the container on a server, where CORS does not apply.`
   );
 }
 
 // src/net/discover-egress.ts
 var EGRESS_PATH = "/__sandboxedjs__/egress";
+var EGRESS_PATHS = [
+  EGRESS_PATH,
+  `/api${EGRESS_PATH}`,
+  "/.netlify/functions/sandboxedjs-egress"
+];
 var EGRESS_MARKER = { sandboxedjs: "egress", protocol: 1 };
 var CLI_PORT = 4181;
 var found = null;
@@ -28308,7 +28313,7 @@ async function isEgress(url, fetchImpl) {
 function candidates() {
   const origin = globalThis.location?.origin;
   const list = [];
-  if (origin && /^https?:/.test(origin)) list.push(`${origin}${EGRESS_PATH}`);
+  if (origin && /^https?:/.test(origin)) list.push(...EGRESS_PATHS.map((path) => `${origin}${path}`));
   list.push(`http://127.0.0.1:${CLI_PORT}/`);
   return list;
 }
@@ -28316,10 +28321,10 @@ async function discoverEgress(fetchImpl = fetch) {
   if (!isBrowser()) return null;
   if (!found) {
     found = (async () => {
-      for (const candidate of candidates()) {
-        if (await isEgress(candidate, fetchImpl)) return candidate;
-      }
-      return null;
+      const list = candidates();
+      const answers = await Promise.all(list.map((candidate) => isEgress(candidate, fetchImpl)));
+      const at2 = answers.findIndex(Boolean);
+      return at2 === -1 ? null : list[at2];
     })();
   }
   return await found;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxedjs",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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",