sandboxedjs 0.2.5 → 0.2.7

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 };

package/dist/egress.js

@@ -13,6 +13,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",
@@ -28,7 +32,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"
@@ -36,6 +40,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 {
@@ -119,6 +128,6 @@ function egressNodeHandler(options = {}) {
   };
 }
 
-export { egressNodeHandler, handleEgressRequest };
+export { EGRESS_MARKER, EGRESS_PATH, egressNodeHandler, handleEgressRequest };
 //# sourceMappingURL=egress.js.map
 //# sourceMappingURL=egress.js.map