sandboxedjs 0.2.6 → 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/browser-host.cjs

@@ -4,6 +4,138 @@ var http = require('http');
 var promises = require('fs/promises');
 var path = require('path');
 
+// src/hosting/browser-host.ts
+
+// 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/discover-egress.ts
+var EGRESS_PATH = "/__sandboxedjs__/egress";
+var EGRESS_MARKER = { sandboxedjs: "egress", protocol: 1 };
+
+// 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": "GET, 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 === "GET" || request.method === "HEAD") {
+    return new Response(request.method === "HEAD" ? null : JSON.stringify(EGRESS_MARKER), {
+      headers: { ...HEADERS, "content-type": "application/json" }
+    });
+  }
+  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()));
+  };
+}
+
 // src/hosting/browser-host.ts
 var browserIsolationHeaders = Object.freeze({
   "Cross-Origin-Opener-Policy": "same-origin",
@@ -33,7 +165,12 @@ async function serveBrowserApp(options) {
     const rel = path.relative(root, path$1);
     return rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
   };
+  const egress = options.egress === false ? null : egressNodeHandler({ ...options.egress?.allow ? { allow: options.egress.allow } : {} });
   const handle = async (req, res) => {
+    if (egress && (req.url ?? "").split("?")[0] === EGRESS_PATH) {
+      await egress(req, res);
+      return;
+    }
     for (const [name, value] of Object.entries(browserIsolationHeaders)) res.setHeader(name, value);
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.setHeader("Cache-Control", "no-cache");

package/dist/browser-host.d.cts

@@ -16,6 +16,18 @@ declare function serveBrowserApp(options: {
     directory: string;
     port?: number;
     hostname?: string;
+    /**
+     * The outbound proxy this host serves for the containers it hosts.
+     *
+     * On by default, because a container in a browser cannot reach an API that
+     * sends no CORS headers without one, and a host that serves the page is
+     * already the right place to put it -- same origin, nothing else to start,
+     * and the container finds it without being configured. `allow` narrows what
+     * it will fetch; `false` turns it off for a host that wants none.
+     */
+    egress?: false | {
+        allow?: string[];
+    };
 }): Promise<{
     server: Server;
     url: string;

package/dist/browser-host.d.ts

@@ -16,6 +16,18 @@ declare function serveBrowserApp(options: {
     directory: string;
     port?: number;
     hostname?: string;
+    /**
+     * The outbound proxy this host serves for the containers it hosts.
+     *
+     * On by default, because a container in a browser cannot reach an API that
+     * sends no CORS headers without one, and a host that serves the page is
+     * already the right place to put it -- same origin, nothing else to start,
+     * and the container finds it without being configured. `allow` narrows what
+     * it will fetch; `false` turns it off for a host that wants none.
+     */
+    egress?: false | {
+        allow?: string[];
+    };
 }): Promise<{
     server: Server;
     url: string;

package/dist/browser-host.js

@@ -2,6 +2,138 @@ import { createServer } from 'http';
 import { realpath, stat, readFile } from 'fs/promises';
 import { resolve, extname, relative, sep, isAbsolute } from 'path';
 
+// src/hosting/browser-host.ts
+
+// 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/discover-egress.ts
+var EGRESS_PATH = "/__sandboxedjs__/egress";
+var EGRESS_MARKER = { sandboxedjs: "egress", protocol: 1 };
+
+// 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": "GET, 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 === "GET" || request.method === "HEAD") {
+    return new Response(request.method === "HEAD" ? null : JSON.stringify(EGRESS_MARKER), {
+      headers: { ...HEADERS, "content-type": "application/json" }
+    });
+  }
+  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()));
+  };
+}
+
 // src/hosting/browser-host.ts
 var browserIsolationHeaders = Object.freeze({
   "Cross-Origin-Opener-Policy": "same-origin",
@@ -31,7 +163,12 @@ async function serveBrowserApp(options) {
     const rel = relative(root, path);
     return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
   };
+  const egress = options.egress === false ? null : egressNodeHandler({ ...options.egress?.allow ? { allow: options.egress.allow } : {} });
   const handle = async (req, res) => {
+    if (egress && (req.url ?? "").split("?")[0] === EGRESS_PATH) {
+      await egress(req, res);
+      return;
+    }
     for (const [name, value] of Object.entries(browserIsolationHeaders)) res.setHeader(name, value);
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.setHeader("Cache-Control", "no-cache");

package/dist/egress.cjs

@@ -15,6 +15,10 @@ function fromBase64(text) {
   return bytes;
 }
 
+// src/net/discover-egress.ts
+var EGRESS_PATH = "/__sandboxedjs__/egress";
+var EGRESS_MARKER = { sandboxedjs: "egress", protocol: 1 };
+
 // src/net/egress-handler.ts
 var HOP = /* @__PURE__ */ new Set([
   "connection",
@@ -30,7 +34,7 @@ var HOP = /* @__PURE__ */ new Set([
 ]);
 var HEADERS = {
   "access-control-allow-origin": "*",
-  "access-control-allow-methods": "POST, OPTIONS",
+  "access-control-allow-methods": "GET, POST, OPTIONS",
   "access-control-allow-headers": "content-type",
   "access-control-max-age": "86400",
   "cross-origin-resource-policy": "cross-origin"
@@ -38,6 +42,11 @@ var HEADERS = {
 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 === "GET" || request.method === "HEAD") {
+    return new Response(request.method === "HEAD" ? null : JSON.stringify(EGRESS_MARKER), {
+      headers: { ...HEADERS, "content-type": "application/json" }
+    });
+  }
   if (request.method !== "POST") return refuse(405, "POST a JSON request here.");
   let payload;
   try {
@@ -121,6 +130,8 @@ function egressNodeHandler(options = {}) {
   };
 }
 
+exports.EGRESS_MARKER = EGRESS_MARKER;
+exports.EGRESS_PATH = EGRESS_PATH;
 exports.egressNodeHandler = egressNodeHandler;
 exports.handleEgressRequest = handleEgressRequest;
 //# sourceMappingURL=egress.cjs.map

package/dist/egress.d.cts

@@ -48,4 +48,36 @@ interface NodeResponse {
  */
 declare function egressNodeHandler(options?: EgressOptions): (request: NodeRequest, response: NodeResponse) => Promise<void>;
 
-export { type EgressOptions, egressNodeHandler, handleEgressRequest };
+/**
+ * Finding the proxy instead of being told where it is.
+ *
+ * A page cannot read a response from a host that does not send CORS headers,
+ * so a container in a browser needs a proxy to make its outbound requests --
+ * and until now every project had to say where that proxy was. That is a
+ * setting whose right value is almost always the same, and getting it wrong
+ * looks like the container being broken: the guest reports "Failed to fetch"
+ * from code that works everywhere else.
+ *
+ * So a browser container with no proxy configured looks for one before it
+ * gives up. A host that mounts `handleEgressRequest` at `EGRESS_PATH` on its
+ * own origin, or runs `sandboxedjs-egress` on its default port, is found
+ * without being named.
+ *
+ * A probe is a GET, which the handler answers with a marker. That matters more
+ * than it sounds: a single-page host answers every unknown path with its own
+ * index.html and status 200, so "the request succeeded" cannot mean "the proxy
+ * is here". Only the marker does.
+ *
+ * Discovery never overrides a proxy the host named, and finding nothing is not
+ * an error -- the request is then made directly, which is right on a server
+ * and is what produces the explanatory CORS failure in a browser.
+ */
+/** Where a host app mounts the proxy for its own containers to find. */
+declare const EGRESS_PATH = "/__sandboxedjs__/egress";
+/** What a GET to the proxy answers, so a probe can tell it from a 200 page. */
+declare const EGRESS_MARKER: {
+    readonly sandboxedjs: "egress";
+    readonly protocol: 1;
+};
+
+export { EGRESS_MARKER, EGRESS_PATH, type EgressOptions, egressNodeHandler, handleEgressRequest };

package/dist/egress.d.ts

@@ -48,4 +48,36 @@ interface NodeResponse {
  */
 declare function egressNodeHandler(options?: EgressOptions): (request: NodeRequest, response: NodeResponse) => Promise<void>;
 
-export { type EgressOptions, egressNodeHandler, handleEgressRequest };
+/**
+ * Finding the proxy instead of being told where it is.
+ *
+ * A page cannot read a response from a host that does not send CORS headers,
+ * so a container in a browser needs a proxy to make its outbound requests --
+ * and until now every project had to say where that proxy was. That is a
+ * setting whose right value is almost always the same, and getting it wrong
+ * looks like the container being broken: the guest reports "Failed to fetch"
+ * from code that works everywhere else.
+ *
+ * So a browser container with no proxy configured looks for one before it
+ * gives up. A host that mounts `handleEgressRequest` at `EGRESS_PATH` on its
+ * own origin, or runs `sandboxedjs-egress` on its default port, is found
+ * without being named.
+ *
+ * A probe is a GET, which the handler answers with a marker. That matters more
+ * than it sounds: a single-page host answers every unknown path with its own
+ * index.html and status 200, so "the request succeeded" cannot mean "the proxy
+ * is here". Only the marker does.
+ *
+ * Discovery never overrides a proxy the host named, and finding nothing is not
+ * an error -- the request is then made directly, which is right on a server
+ * and is what produces the explanatory CORS failure in a browser.
+ */
+/** Where a host app mounts the proxy for its own containers to find. */
+declare const EGRESS_PATH = "/__sandboxedjs__/egress";
+/** What a GET to the proxy answers, so a probe can tell it from a 200 page. */
+declare const EGRESS_MARKER: {
+    readonly sandboxedjs: "egress";
+    readonly protocol: 1;
+};
+
+export { EGRESS_MARKER, EGRESS_PATH, type EgressOptions, egressNodeHandler, handleEgressRequest };