sandboxedjs 0.1.30 → 0.1.32

package/README.md

@@ -134,97 +134,37 @@ await bridge.close();
 
 ### Showing a live preview in an IDE
 
-This is the StackBlitz/CodeSandbox preview pane: the user runs a dev server inside the
-container, and sees the rendered page, not just logs.
+A container's port is virtual. Its printed `http://localhost:5173` is not automatically
+reachable from your browser. Render a whole site in an iframe using the bridge for your host:
 
-**It works today, as an `<iframe>` — not as a `<div>`.** A `<div>` cannot host it: the preview
-is a whole HTML document with its own scripts, styles, `<base>` and routing, and it must not be
-able to reach into your IDE's DOM. An iframe on its own origin is exactly the isolation you
-want, and it is what StackBlitz and CodeSandbox use too.
+| Container host | API | Browser-facing URL |
+| --- | --- | --- |
+| Browser only | `createPreview(box)` | A service-worker URL from `preview.urlFor(port)` |
+| Node.js | `box.expose(port)` | A real loopback HTTP URL from `bridge.url` |
 
-`expose(port)` gives you a real, browser-loadable URL:
+Browser-only example, after starting a server in `box`:
 
 ```ts
-box.spawn("npm run dev", { cwd: "/app" });
-await box.waitForPort(5173);
-
-const preview = await box.expose(5173);
-document.querySelector("#preview").src = preview.url; // an <iframe>
-```
-
-A minimal IDE preview pane, in React:
-
-```tsx
-function PreviewPane({ box, port }) {
-  const [url, setUrl] = useState(null);
-  const frame = useRef(null);
-
-  useEffect(() => {
-    let bridge;
-    let cancelled = false;
-
-    (async () => {
-      if (!(await box.waitForPort(port, { timeoutMs: 60_000 }))) return;
-      bridge = await box.expose(port);
-      if (!cancelled) setUrl(bridge.url);
-    })();
-
-    return () => {
-      cancelled = true;
-      void bridge?.close();
-    };
-  }, [box, port]);
-
-  // Call this after a rebuild to refresh the pane.
-  const reload = () => {
-    if (frame.current) frame.current.src = frame.current.src;
-  };
-
-  if (!url) return <div>starting…</div>;
-  return <iframe ref={frame} src={url} style={{ width: "100%", height: "100%", border: 0 }} />;
+import { createPreview } from 'sandboxedjs';
+if (!(await box.waitForPort(5173, { timeoutMs: 60_000 }))) {
+  throw new Error('Server did not start; inspect its logs');
 }
+const preview = await createPreview(box);
+if (!preview) throw new Error('Secure context and service-worker support required');
+iframe.src = preview.urlFor(5173);
+// On teardown: remove the iframe, await preview.dispose(), then dispose the container.
 ```
 
-Pin the port if you want a stable URL across restarts:
-
-```ts
-const preview = await box.expose(5173, { hostPort: 5173 }); // http://127.0.0.1:5173
-```
-
-Serve several ports by exposing each one; every call gets its own host port.
-
-#### Refreshing on change
-
-**`expose()` proxies HTTP, not WebSockets.** A dev server's hot-reload channel is a WebSocket,
-so HMR and live-reload overlays will not reach the iframe. Drive the refresh from your IDE
-instead — which you need to do anyway if you are compiling on save:
-
-```ts
-// after writing the user's edit and rebuilding
-await box.fs.writeFile("/app/src/App.jsx", nextSource);
-await box.exec("npm run build", { cwd: "/app" });
-frame.current.src = frame.current.src; // reload the pane
-```
-
-That is a full reload rather than hot module replacement: state in the page is lost. For most
-IDE previews that is acceptable; if you need true HMR, the WebSocket proxy is the missing piece.
+The service worker routes that iframe's HTML, scripts, styles and API requests into the
+container without rewriting the site's asset paths. Keep its owner page alive.
 
-#### What the IDE can and cannot do with the frame
+**Trust and scope:** this browser preview runs on the host page's origin. It is for trusted
+code, not a security boundary for arbitrary projects. Both preview bridges handle HTTP;
+WebSocket HMR is not implemented, so reload the iframe after changes.
 
-The iframe is cross-origin, so your IDE cannot read its DOM. You can still:
-
-- `postMessage` to it, if the app inside cooperates;
-- watch `/app/**` through the container to know when to rebuild;
-- read the dev server's stdout from `spawn()` for a log pane.
-
-#### In a pure browser IDE
-
-`expose()` opens a real `node:http` listener, so it needs a Node host — an Electron app, or a web
-IDE with a Node backend. With no backend at all, an iframe needs a real URL to load, and giving
-it one means a service worker that intercepts requests and routes them to `request()`. That is
-not built yet; see [Running in a browser](#running-in-a-browser). Until it is, you can still
-drive an in-container server programmatically through `request()` and render the result
-yourself.
+For complete browser and Node examples, IDE lifecycle/port selection, hosting requirements,
+single-response rendering and troubleshooting, see [Server preview integration](docs/server-previews.md).
+For the startup bug investigation and validation, see [Runtime lifecycle fixes](docs/runtime-lifecycle-fixes.md).
 
 ### npm and npx
 
@@ -634,16 +574,21 @@ mentions Rolldown. Excluding the binding leaves it served from `node_modules`, w
 resolves. The compiler is loaded only when an installed
 project actually contains Rolldown, so ordinary container boot does not pay its WASM startup cost.
 
+Host-backed compiler promises now count as active process work. The runtime keeps the guest
+alive while WASM initialization/build operations are pending, rather than guessing a startup
+delay from unreferenced timers. Listening servers remain live until closed, unreferenced, or
+killed. Cancellation releases owned child processes and ports, including children behind
+synchronous `npm`/`npx` wrappers; inherited terminal input bypasses a blocked parent worker.
+These are runtime lifecycle rules, not Vite-specific command replacements.
+
 **Not done — these things still stand between this and a complete browser IDE.**
 
-- *A service worker.* A preview iframe needs a real URL, and giving it one means a worker on your
-  own origin that intercepts requests and routes them into the container. `request()` works
-  everywhere and is unaffected; only the iframe needs this. Earlier versions re-exported one from
-  the package this was built on, at `sandboxedjs/vite` and `sandboxedjs/server`. Both are gone
-  along with that dependency, and a replacement is not written yet.
-- *Worker isolation.* The runtime executes in whichever realm you boot it from, which in a browser
-  is the main thread — so a long build blocks the UI, and container code can reach page globals.
-  `comlink` is a dependency in anticipation of this and is not used yet.
+- *Preview isolation and WebSockets.* `createPreview()` registers the bundled service worker
+  and routes HTTP requests into the container. It is an origin-local preview for trusted code;
+  WebSocket forwarding/HMR is not implemented. Reload the iframe after changes.
+- *Complete worker isolation.* Worker-capable programs run off the main thread, but host-backed
+  compiler modules can require the local runtime. Container code is not a security boundary
+  from the host page; do not treat it as one.
 - *esbuild-dependent tools.* The runtime cannot execute any build of esbuild itself: one dlopens a compiled addon,
   the other drives a Go program through facilities the sandbox does not have. On Node it borrows
   the host's `esbuild-wasm`. Vite 8's Rolldown path works in a browser, but tools which call
@@ -820,6 +765,51 @@ the `null` return rather than a throw. Responses are served with both
 `Cross-Origin-Resource-Policy` and `Cross-Origin-Embedder-Policy`, so a preview still frames
 correctly inside the cross-origin isolated page that Rolldown requires.
 
+### Serving a built browser application
+
+The host page must enable cross-origin isolation **before** `createContainer()` runs.
+This is a prerequisite for both synchronous child processes and threaded WASM; it is
+not something `npm create`, `npm install`, or `npm run` inside the container can fix.
+Headers configured on a development server do not carry over to a plain static server.
+
+SandboxedJs ships a local browser host for built applications:
+
+```sh
+npx sandboxedjs-serve ./dist 4173
+```
+
+It serves the app on `http://127.0.0.1:4173` with COOP/COEP on documents, scripts,
+workers, and WASM. Missing assets return 404 rather than an HTML fallback. It binds
+to loopback by default and does not serve dotfiles or symlinks outside the web root.
+This is a local static host, not a production deployment server or SPA route rewriter.
+
+For a Node host integration (this subpath must not be imported into browser code):
+
+```ts
+import { serveBrowserApp, browserIsolationHeaders } from 'sandboxedjs/browser-host';
+const host = await serveBrowserApp({ directory: './dist', port: 4173 });
+console.log(host.url);
+// Or apply browserIsolationHeaders to your existing server's responses.
+// await host.close();
+```
+
+For remote deployments configure HTTPS plus those headers on your actual web server
+or CDN. Check `crossOriginIsolated` in the page, not just the network response: iframe
+permissions and embedded browser restrictions can still deny shared memory. A loaded
+page cannot grant itself this permission with a polyfill or a meta tag. Cross-origin
+resources also need CORS or an appropriate CORP policy under `require-corp`.
+
+Require worker support at boot when the application depends on synchronous Node APIs:
+
+```ts
+const box = await createContainer({ isolation: 'worker' });
+```
+
+This rejects with the missing prerequisite or worker-load cause before commands run.
+The default `isolation: 'auto'` retains compatibility but reports fallback through
+`onRuntimeFallback(error)` (or `console.warn` if omitted). `isolation: 'realm'` is an
+explicit opt-out and does not support synchronous child processes.
+
 ## Isolation
 
 By default each guest program runs on its own thread, in a Worker. The volume, the kernel, the
@@ -832,7 +822,7 @@ they cannot be expressed any other way, because a synchronous call has to block
 the child it is waiting for still makes progress, which is impossible when both are the same
 thread.
 
-It is chosen automatically and falls back on its own, so nothing that runs today stops running:
+In default `auto` mode the runtime reports its fallback reason and stays usable:
 
 | Condition | What happens |
 |---|---|
@@ -843,7 +833,10 @@ It is chosen automatically and falls back on its own, so nothing that runs today
 
 In a browser this needs the same COOP/COEP headers Rolldown does, which is the usual reason to
 find yourself in the fallback. `createContainer({ isolation: "realm" })` opts out entirely, and
-`workerUrl` points at the guest bundle when a bundler has moved it.
+`workerUrl` points at the guest bundle when a bundler has moved it. Explicit
+`isolation: "worker"` rejects at boot instead of taking either environment fallback.
+Host-native module processes still use the realm runtime; selecting worker mode is
+not a guarantee that every package executes off the host thread.
 
 ## Known limits
 

package/bin/sandboxedjs-serve.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { serveBrowserApp } from "../dist/browser-host.js";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log("Usage: sandboxedjs-serve [directory=dist] [port=4173]\nServes a built browser app on loopback with the headers required by SandboxedJs workers and WASM.");
+} else {
+  const port = Number(args[1] ?? 4173);
+  if (args.length > 2 || !Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error("Usage: sandboxedjs-serve [directory=dist] [port=4173]");
+    process.exitCode = 1;
+  } else {
+    try {
+      const host = await serveBrowserApp({ directory: args[0] ?? "dist", port });
+      console.log(`SandboxedJs browser host: ${host.url}`);
+      const stop = () => { void host.close().then(() => process.exit(0)); };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    } catch (error) {
+      console.error(`sandboxedjs-serve: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
+}

package/dist/browser-host.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+var http = require('http');
+var promises = require('fs/promises');
+var path = require('path');
+
+// src/hosting/browser-host.ts
+var browserIsolationHeaders = Object.freeze({
+  "Cross-Origin-Opener-Policy": "same-origin",
+  "Cross-Origin-Embedder-Policy": "require-corp"
+});
+var mime = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".wasm": "application/wasm",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8"
+};
+async function serveBrowserApp(options) {
+  const root = await promises.realpath(path.resolve(options.directory));
+  if (!(await promises.stat(root)).isDirectory()) throw new Error("Browser app directory is not a directory");
+  const inside = (path$1) => {
+    const rel = path.relative(root, path$1);
+    return rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+  };
+  const handle = async (req, res) => {
+    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");
+    const reply = (status, body) => {
+      res.statusCode = status;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end(req.method === "HEAD" ? void 0 : body);
+    };
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.setHeader("Allow", "GET, HEAD");
+      reply(405, "Method not allowed");
+      return;
+    }
+    let pathname;
+    try {
+      pathname = decodeURIComponent((req.url ?? "/").split("?")[0]);
+    } catch {
+      reply(400, "Invalid URL");
+      return;
+    }
+    if (pathname.includes("\0") || pathname.includes("\\") || pathname.split("/").some((p) => p.startsWith("."))) {
+      reply(403, "Forbidden");
+      return;
+    }
+    let candidate = path.resolve(root, `.${pathname.startsWith("/") ? pathname : `/${pathname}`}`);
+    try {
+      if (!inside(candidate)) {
+        reply(403, "Forbidden");
+        return;
+      }
+      if ((await promises.stat(candidate)).isDirectory()) candidate = path.resolve(candidate, "index.html");
+      candidate = await promises.realpath(candidate);
+      if (!inside(candidate)) {
+        reply(403, "Forbidden");
+        return;
+      }
+      if (!(await promises.stat(candidate)).isFile()) {
+        reply(404, "Not found");
+        return;
+      }
+      const body = await promises.readFile(candidate);
+      res.setHeader("Content-Type", mime[path.extname(candidate)] ?? "application/octet-stream");
+      res.setHeader("Content-Length", body.byteLength);
+      res.end(req.method === "HEAD" ? void 0 : body);
+    } catch (error) {
+      const code = error.code;
+      reply(code === "ENOENT" || code === "ENOTDIR" ? 404 : 500, "Unable to serve file");
+    }
+  };
+  const server = http.createServer((req, res) => {
+    void handle(req, res);
+  });
+  const hostname = options.hostname ?? "127.0.0.1";
+  await new Promise((done, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 4173, hostname, () => {
+      server.off("error", reject);
+      done();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Browser host has no TCP address");
+  return {
+    server,
+    url: `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${address.port}`,
+    close: () => new Promise((done, reject) => {
+      server.close((error) => error ? reject(error) : done());
+      server.closeIdleConnections();
+    })
+  };
+}
+
+exports.browserIsolationHeaders = browserIsolationHeaders;
+exports.serveBrowserApp = serveBrowserApp;
+//# sourceMappingURL=browser-host.cjs.map
+//# sourceMappingURL=browser-host.cjs.map

package/dist/browser-host.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hosting/browser-host.ts"],"names":["realpath","resolve","stat","path","relative","sep","isAbsolute","readFile","extname","createServer"],"mappings":"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","file":"browser-host.cjs","sourcesContent":["/** Node-side hosting for a built SandboxedJs browser application. */\nimport { createServer, type Server, type IncomingMessage, type ServerResponse } from \"node:http\";\nimport { readFile, realpath, stat } from \"node:fs/promises\";\nimport { extname, isAbsolute, relative, resolve, sep } from \"node:path\";\n\n/** These must be sent on the host document, not just the guest's HTTP responses. */\nexport const browserIsolationHeaders = Object.freeze({\n  \"Cross-Origin-Opener-Policy\": \"same-origin\",\n  \"Cross-Origin-Embedder-Policy\": \"require-corp\",\n});\n\nconst mime: Record<string, string> = {\n  \".html\": \"text/html; charset=utf-8\", \".js\": \"text/javascript; charset=utf-8\",\n  \".mjs\": \"text/javascript; charset=utf-8\", \".css\": \"text/css; charset=utf-8\",\n  \".json\": \"application/json\", \".wasm\": \"application/wasm\",\n  \".svg\": \"image/svg+xml\", \".png\": \"image/png\", \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\", \".ico\": \"image/x-icon\", \".webp\": \"image/webp\",\n  \".woff\": \"font/woff\", \".woff2\": \"font/woff2\", \".txt\": \"text/plain; charset=utf-8\",\n};\n\n/**\n * Serve a built host application with the prerequisites for guest workers and\n * threaded WASM. Loopback-only by default; use HTTPS at a reverse proxy for\n * remote access. An arbitrary HTTP origin is not a secure browser context.\n */\nexport async function serveBrowserApp(options: {\n  directory: string;\n  port?: number;\n  hostname?: string;\n}): Promise<{ server: Server; url: string; close(): Promise<void> }> {\n  const root = await realpath(resolve(options.directory));\n  if (!(await stat(root)).isDirectory()) throw new Error(\"Browser app directory is not a directory\");\n  const inside = (path: string) => {\n    const rel = relative(root, path);\n    return rel !== \"..\" && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);\n  };\n  const handle = async (req: IncomingMessage, res: ServerResponse) => {\n    for (const [name, value] of Object.entries(browserIsolationHeaders)) res.setHeader(name, value);\n    res.setHeader(\"X-Content-Type-Options\", \"nosniff\");\n    res.setHeader(\"Cache-Control\", \"no-cache\");\n    const reply = (status: number, body: string) => {\n      res.statusCode = status;\n      res.setHeader(\"Content-Type\", \"text/plain; charset=utf-8\");\n      res.end(req.method === \"HEAD\" ? undefined : body);\n    };\n    if (req.method !== \"GET\" && req.method !== \"HEAD\") {\n      res.setHeader(\"Allow\", \"GET, HEAD\");\n      reply(405, \"Method not allowed\");\n      return;\n    }\n    let pathname: string;\n    try { pathname = decodeURIComponent((req.url ?? \"/\").split(\"?\")[0]!); }\n    catch { reply(400, \"Invalid URL\"); return; }\n    // Reject traversal, hidden files, and platform-dependent separators before resolving.\n    if (pathname.includes(\"\\0\") || pathname.includes(\"\\\\\") || pathname.split(\"/\").some(p => p.startsWith(\".\"))) {\n      reply(403, \"Forbidden\"); return;\n    }\n    let candidate = resolve(root, `.${pathname.startsWith(\"/\") ? pathname : `/${pathname}`}`);\n    try {\n      if (!inside(candidate)) { reply(403, \"Forbidden\"); return; }\n      if ((await stat(candidate)).isDirectory()) candidate = resolve(candidate, \"index.html\");\n      candidate = await realpath(candidate);\n      // A symlink inside the web root must not expose files outside it.\n      if (!inside(candidate)) { reply(403, \"Forbidden\"); return; }\n      if (!(await stat(candidate)).isFile()) { reply(404, \"Not found\"); return; }\n      const body = await readFile(candidate);\n      res.setHeader(\"Content-Type\", mime[extname(candidate)] ?? \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", body.byteLength);\n      res.end(req.method === \"HEAD\" ? undefined : body);\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n      reply(code === \"ENOENT\" || code === \"ENOTDIR\" ? 404 : 500, \"Unable to serve file\");\n    }\n  };\n  const server = createServer((req, res) => { void handle(req, res); });\n  const hostname = options.hostname ?? \"127.0.0.1\";\n  await new Promise<void>((done, reject) => {\n    server.once(\"error\", reject);\n    server.listen(options.port ?? 4173, hostname, () => { server.off(\"error\", reject); done(); });\n  });\n  const address = server.address();\n  if (!address || typeof address === \"string\") throw new Error(\"Browser host has no TCP address\");\n  return {\n    server,\n    url: `http://${hostname.includes(\":\") ? `[${hostname}]` : hostname}:${address.port}`,\n    close: () => new Promise<void>((done, reject) => {\n      server.close(error => error ? reject(error) : done());\n      server.closeIdleConnections();\n    }),\n  };\n}\n"]}

package/dist/browser-host.d.cts

@@ -0,0 +1,25 @@
+import { Server } from 'node:http';
+
+/** Node-side hosting for a built SandboxedJs browser application. */
+
+/** These must be sent on the host document, not just the guest's HTTP responses. */
+declare const browserIsolationHeaders: Readonly<{
+    "Cross-Origin-Opener-Policy": "same-origin";
+    "Cross-Origin-Embedder-Policy": "require-corp";
+}>;
+/**
+ * Serve a built host application with the prerequisites for guest workers and
+ * threaded WASM. Loopback-only by default; use HTTPS at a reverse proxy for
+ * remote access. An arbitrary HTTP origin is not a secure browser context.
+ */
+declare function serveBrowserApp(options: {
+    directory: string;
+    port?: number;
+    hostname?: string;
+}): Promise<{
+    server: Server;
+    url: string;
+    close(): Promise<void>;
+}>;
+
+export { browserIsolationHeaders, serveBrowserApp };

package/dist/browser-host.d.ts

@@ -0,0 +1,25 @@
+import { Server } from 'node:http';
+
+/** Node-side hosting for a built SandboxedJs browser application. */
+
+/** These must be sent on the host document, not just the guest's HTTP responses. */
+declare const browserIsolationHeaders: Readonly<{
+    "Cross-Origin-Opener-Policy": "same-origin";
+    "Cross-Origin-Embedder-Policy": "require-corp";
+}>;
+/**
+ * Serve a built host application with the prerequisites for guest workers and
+ * threaded WASM. Loopback-only by default; use HTTPS at a reverse proxy for
+ * remote access. An arbitrary HTTP origin is not a secure browser context.
+ */
+declare function serveBrowserApp(options: {
+    directory: string;
+    port?: number;
+    hostname?: string;
+}): Promise<{
+    server: Server;
+    url: string;
+    close(): Promise<void>;
+}>;
+
+export { browserIsolationHeaders, serveBrowserApp };

package/dist/browser-host.js

@@ -0,0 +1,109 @@
+import { createServer } from 'http';
+import { realpath, stat, readFile } from 'fs/promises';
+import { resolve, extname, relative, sep, isAbsolute } from 'path';
+
+// src/hosting/browser-host.ts
+var browserIsolationHeaders = Object.freeze({
+  "Cross-Origin-Opener-Policy": "same-origin",
+  "Cross-Origin-Embedder-Policy": "require-corp"
+});
+var mime = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".wasm": "application/wasm",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8"
+};
+async function serveBrowserApp(options) {
+  const root = await realpath(resolve(options.directory));
+  if (!(await stat(root)).isDirectory()) throw new Error("Browser app directory is not a directory");
+  const inside = (path) => {
+    const rel = relative(root, path);
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+  };
+  const handle = async (req, res) => {
+    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");
+    const reply = (status, body) => {
+      res.statusCode = status;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end(req.method === "HEAD" ? void 0 : body);
+    };
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.setHeader("Allow", "GET, HEAD");
+      reply(405, "Method not allowed");
+      return;
+    }
+    let pathname;
+    try {
+      pathname = decodeURIComponent((req.url ?? "/").split("?")[0]);
+    } catch {
+      reply(400, "Invalid URL");
+      return;
+    }
+    if (pathname.includes("\0") || pathname.includes("\\") || pathname.split("/").some((p) => p.startsWith("."))) {
+      reply(403, "Forbidden");
+      return;
+    }
+    let candidate = resolve(root, `.${pathname.startsWith("/") ? pathname : `/${pathname}`}`);
+    try {
+      if (!inside(candidate)) {
+        reply(403, "Forbidden");
+        return;
+      }
+      if ((await stat(candidate)).isDirectory()) candidate = resolve(candidate, "index.html");
+      candidate = await realpath(candidate);
+      if (!inside(candidate)) {
+        reply(403, "Forbidden");
+        return;
+      }
+      if (!(await stat(candidate)).isFile()) {
+        reply(404, "Not found");
+        return;
+      }
+      const body = await readFile(candidate);
+      res.setHeader("Content-Type", mime[extname(candidate)] ?? "application/octet-stream");
+      res.setHeader("Content-Length", body.byteLength);
+      res.end(req.method === "HEAD" ? void 0 : body);
+    } catch (error) {
+      const code = error.code;
+      reply(code === "ENOENT" || code === "ENOTDIR" ? 404 : 500, "Unable to serve file");
+    }
+  };
+  const server = createServer((req, res) => {
+    void handle(req, res);
+  });
+  const hostname = options.hostname ?? "127.0.0.1";
+  await new Promise((done, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 4173, hostname, () => {
+      server.off("error", reject);
+      done();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Browser host has no TCP address");
+  return {
+    server,
+    url: `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${address.port}`,
+    close: () => new Promise((done, reject) => {
+      server.close((error) => error ? reject(error) : done());
+      server.closeIdleConnections();
+    })
+  };
+}
+
+export { browserIsolationHeaders, serveBrowserApp };
+//# sourceMappingURL=browser-host.js.map
+//# sourceMappingURL=browser-host.js.map

package/dist/browser-host.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hosting/browser-host.ts"],"names":[],"mappings":"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","file":"browser-host.js","sourcesContent":["/** Node-side hosting for a built SandboxedJs browser application. */\nimport { createServer, type Server, type IncomingMessage, type ServerResponse } from \"node:http\";\nimport { readFile, realpath, stat } from \"node:fs/promises\";\nimport { extname, isAbsolute, relative, resolve, sep } from \"node:path\";\n\n/** These must be sent on the host document, not just the guest's HTTP responses. */\nexport const browserIsolationHeaders = Object.freeze({\n  \"Cross-Origin-Opener-Policy\": \"same-origin\",\n  \"Cross-Origin-Embedder-Policy\": \"require-corp\",\n});\n\nconst mime: Record<string, string> = {\n  \".html\": \"text/html; charset=utf-8\", \".js\": \"text/javascript; charset=utf-8\",\n  \".mjs\": \"text/javascript; charset=utf-8\", \".css\": \"text/css; charset=utf-8\",\n  \".json\": \"application/json\", \".wasm\": \"application/wasm\",\n  \".svg\": \"image/svg+xml\", \".png\": \"image/png\", \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\", \".ico\": \"image/x-icon\", \".webp\": \"image/webp\",\n  \".woff\": \"font/woff\", \".woff2\": \"font/woff2\", \".txt\": \"text/plain; charset=utf-8\",\n};\n\n/**\n * Serve a built host application with the prerequisites for guest workers and\n * threaded WASM. Loopback-only by default; use HTTPS at a reverse proxy for\n * remote access. An arbitrary HTTP origin is not a secure browser context.\n */\nexport async function serveBrowserApp(options: {\n  directory: string;\n  port?: number;\n  hostname?: string;\n}): Promise<{ server: Server; url: string; close(): Promise<void> }> {\n  const root = await realpath(resolve(options.directory));\n  if (!(await stat(root)).isDirectory()) throw new Error(\"Browser app directory is not a directory\");\n  const inside = (path: string) => {\n    const rel = relative(root, path);\n    return rel !== \"..\" && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);\n  };\n  const handle = async (req: IncomingMessage, res: ServerResponse) => {\n    for (const [name, value] of Object.entries(browserIsolationHeaders)) res.setHeader(name, value);\n    res.setHeader(\"X-Content-Type-Options\", \"nosniff\");\n    res.setHeader(\"Cache-Control\", \"no-cache\");\n    const reply = (status: number, body: string) => {\n      res.statusCode = status;\n      res.setHeader(\"Content-Type\", \"text/plain; charset=utf-8\");\n      res.end(req.method === \"HEAD\" ? undefined : body);\n    };\n    if (req.method !== \"GET\" && req.method !== \"HEAD\") {\n      res.setHeader(\"Allow\", \"GET, HEAD\");\n      reply(405, \"Method not allowed\");\n      return;\n    }\n    let pathname: string;\n    try { pathname = decodeURIComponent((req.url ?? \"/\").split(\"?\")[0]!); }\n    catch { reply(400, \"Invalid URL\"); return; }\n    // Reject traversal, hidden files, and platform-dependent separators before resolving.\n    if (pathname.includes(\"\\0\") || pathname.includes(\"\\\\\") || pathname.split(\"/\").some(p => p.startsWith(\".\"))) {\n      reply(403, \"Forbidden\"); return;\n    }\n    let candidate = resolve(root, `.${pathname.startsWith(\"/\") ? pathname : `/${pathname}`}`);\n    try {\n      if (!inside(candidate)) { reply(403, \"Forbidden\"); return; }\n      if ((await stat(candidate)).isDirectory()) candidate = resolve(candidate, \"index.html\");\n      candidate = await realpath(candidate);\n      // A symlink inside the web root must not expose files outside it.\n      if (!inside(candidate)) { reply(403, \"Forbidden\"); return; }\n      if (!(await stat(candidate)).isFile()) { reply(404, \"Not found\"); return; }\n      const body = await readFile(candidate);\n      res.setHeader(\"Content-Type\", mime[extname(candidate)] ?? \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", body.byteLength);\n      res.end(req.method === \"HEAD\" ? undefined : body);\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n      reply(code === \"ENOENT\" || code === \"ENOTDIR\" ? 404 : 500, \"Unable to serve file\");\n    }\n  };\n  const server = createServer((req, res) => { void handle(req, res); });\n  const hostname = options.hostname ?? \"127.0.0.1\";\n  await new Promise<void>((done, reject) => {\n    server.once(\"error\", reject);\n    server.listen(options.port ?? 4173, hostname, () => { server.off(\"error\", reject); done(); });\n  });\n  const address = server.address();\n  if (!address || typeof address === \"string\") throw new Error(\"Browser host has no TCP address\");\n  return {\n    server,\n    url: `http://${hostname.includes(\":\") ? `[${hostname}]` : hostname}:${address.port}`,\n    close: () => new Promise<void>((done, reject) => {\n      server.close(error => error ? reject(error) : done());\n      server.closeIdleConnections();\n    }),\n  };\n}\n"]}