sandboxedjs 0.1.29 → 0.1.30

package/LICENSE

@@ -18,10 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-This package depends on @scelar/nodepod, which is licensed MIT with the
-Commons Clause. Nodepod is not redistributed here; it is installed as a normal
-npm dependency.
+SOFTWARE.

package/README.md

@@ -768,6 +768,58 @@ Two caveats worth knowing:
   itself reports status correctly and can be relied on in `&&` chains.
 - **No hardware acceleration and no native codecs** beyond what the WebAssembly build ships.
 
+## Reaching a container's servers from the page
+
+A server inside the container is not on the network, so there is no `http://localhost:5173`
+your page can navigate to. There are three ways to reach one, and the right choice depends on
+whether you need a whole site or a single response — and on whether you trust the code.
+
+**1. One response, into a variable.** `request()` speaks to a server directly and hands back the
+bytes. Nothing is executed, so there is nothing to be careful about.
+
+```ts
+const res = await box.request(5173, { path: "/api/items" });
+element.textContent = res.body;          // text
+const items = res.json<Item[]>();        // parsed
+const bytes = res.bytes;                 // exact bytes, for images and source maps
+```
+
+**2. One response, rendered — safely.** `renderInto` puts the response in an iframe with
+`sandbox="allow-scripts"` and deliberately *without* `allow-same-origin`. The document lands in an
+opaque origin: its scripts run, and they can reach neither your DOM nor your cookies and storage.
+
+```ts
+import { renderInto } from "sandboxedjs";
+await renderInto(box, document.querySelector("#preview")!, { port: 5173 });
+```
+
+This is the option to reach for when the code came from somewhere you do not control. Its limit is
+that only that one response exists — a page asking for `/main.js` gets nothing, because there is no
+origin to serve it from. Good for generated HTML, a chart, a rendered document.
+
+**3. A whole site, with real URLs.** `createPreview` registers a service worker that gives the
+container's ports working URLs, so an iframe can load a dev server with all its subresources.
+
+```ts
+import { createPreview } from "sandboxedjs";
+const preview = await createPreview(box);          // null where service workers are unavailable
+iframe.src = preview!.urlFor(5173);
+```
+
+Requests are routed by *which client is asking* rather than by path, so a dev server's absolute
+URLs — `/src/main.js`, `/@vite/client` — resolve without rewriting anything.
+
+> **This one runs guest code on your origin.** A service worker can only serve URLs under the
+> origin that registered it, so scripts in the preview can reach `window.parent`, your cookies and
+> your `localStorage`. The sandbox contains a program's *filesystem and process table*, not the
+> page it serves. Use it for code you trust; for anything else, serve the preview from a separate
+> origin (a subdomain pointed at the same app) or stay with option 2.
+
+Service workers need a secure context, and some embedded browsers disable them entirely — hence
+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.
+
 ## Isolation
 
 By default each guest program runs on its own thread, in a Worker. The volume, the kernel, the

package/dist/index.cjs

@@ -19712,6 +19712,10 @@ var KernelChildProcess = class {
   started = false;
   cancelled = false;
   constructor(kernel, cred, config, pid) {
+    if (config.inheritStdio) {
+      this.stdin.isTTY = true;
+      this.stdin.interactive = true;
+    }
     this.kernel = kernel;
     this.cred = cred;
     this.pid = pid;
@@ -22116,7 +22120,8 @@ var ChildProcess = class extends EventEmitter4__default.default {
     queueMicrotask(() => this.emit("close", code, null));
   }
 };
-function createChildProcessModule(spawnChild, defaultCwd, syncSpawn) {
+function createChildProcessModule(spawnChild, defaultCwd, syncSpawn, defaultEnv = () => ({})) {
+  const environmentFor = (options) => options.env ? { ...options.env } : defaultEnv();
   const throughShell = (command, options) => {
     const shell = typeof options.shell === "string" ? options.shell : "/bin/sh";
     return { file: shell, args: ["-c", command] };
@@ -22127,7 +22132,7 @@ function createChildProcessModule(spawnChild, defaultCwd, syncSpawn) {
       command: resolved.file,
       args: resolved.args,
       cwd: options.cwd ?? defaultCwd(),
-      ...options.env ? { env: options.env } : {}
+      env: environmentFor(options)
     });
     return new ChildProcess(handle, resolved.file, resolved.args);
   };
@@ -22173,11 +22178,11 @@ ${err.join("")}`),
     exec,
     execFile,
     fork: (modulePath, args = [], options = {}) => spawn("node", [modulePath, ...args], options),
-    ...buildSyncFamily(syncSpawn, throughShell, defaultCwd),
+    ...buildSyncFamily(syncSpawn, throughShell, defaultCwd, environmentFor),
     ChildProcess
   };
 }
-function buildSyncFamily(syncSpawn, throughShell, defaultCwd) {
+function buildSyncFamily(syncSpawn, throughShell, defaultCwd, environmentFor) {
   if (!syncSpawn) {
     return {
       execSync: unavailable("execSync"),
@@ -22188,12 +22193,14 @@ function buildSyncFamily(syncSpawn, throughShell, defaultCwd) {
   const run = (file3, args, options) => {
     const resolved = options.shell ? throughShell([file3, ...args].join(" "), options) : { file: file3, args };
     const input = options.input === void 0 ? void 0 : typeof options.input === "string" ? options.input : new TextDecoder().decode(options.input);
+    const inherit = options.stdio === "inherit" || Array.isArray(options.stdio) && options.stdio[0] === "inherit";
     return syncSpawn({
       command: resolved.file,
       args: resolved.args,
       cwd: options.cwd ?? defaultCwd(),
-      ...options.env ? { env: options.env } : {},
-      ...input === void 0 ? {} : { input }
+      env: environmentFor(options),
+      ...input === void 0 ? {} : { input },
+      ...inherit ? { inheritStdio: true } : {}
     });
   };
   const asOutput = (text2, options) => options.encoding === "buffer" || options.encoding === void 0 ? Buffer2.from(text2) : text2;
@@ -22873,7 +22880,7 @@ function createCoreModules(options) {
   };
   const http = options.http ? createHttpModule(options.http.router, options.http.owner, httpOptions, "http:") : createUnsupportedModule("http");
   const https = options.http ? createHttpModule(options.http.router, options.http.owner, httpOptions, "https:") : createUnsupportedModule("https");
-  const childProcess = options.spawnChild ? createChildProcessModule(options.spawnChild, () => cwd, options.syncSpawn) : createUnsupportedModule("child_process");
+  const childProcess = options.spawnChild ? createChildProcessModule(options.spawnChild, () => cwd, options.syncSpawn, () => ({ ...processObject.env })) : createUnsupportedModule("child_process");
   const readline = createReadlineModule(() => processObject.stdin, () => processObject.stdout);
   const dns = createDnsModule();
   const builtins = {
@@ -24118,8 +24125,10 @@ var MirroringVolume = class {
    * container pays nothing for this.
    */
   attach(mirror, root) {
+    const cleanRoot = clean(root);
+    if (this.mirror === mirror && this.root === cleanRoot) return;
     this.mirror = mirror;
-    this.root = clean(root);
+    this.root = cleanRoot;
     this.seed();
   }
   detach() {
@@ -25254,9 +25263,10 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       ...this.workerUrl ? { url: this.workerUrl } : {},
       timeoutMs: 15e3
     });
+    const streams = { target: null };
     const server = new SyncChannelServer(buffers, serveSyncSyscalls({
       volume: this.volume,
-      spawnChild: (request) => this.runChildToCompletion(request)
+      spawnChild: (request) => this.runChildToCompletion(request, streams.target)
     }));
     const entry = { worker, server };
     this.live.add(entry);
@@ -25266,6 +25276,7 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       this.closeProxies(owner);
       void worker.terminate();
     });
+    streams.target = process2;
     const children = /* @__PURE__ */ new Map();
     worker.onMessage((raw) => {
       const message = raw;
@@ -25332,7 +25343,7 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
     handle.exec();
   }
   /** Run a child to completion and collect it, for the guest's `spawnSync`. */
-  runChildToCompletion(request) {
+  runChildToCompletion(request, streamTo) {
     return new Promise((resolve2) => {
       let handle;
       try {
@@ -25340,7 +25351,8 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
           command: request.command,
           args: request.args,
           cwd: request.cwd,
-          ...request.env ? { env: request.env } : {}
+          ...request.env ? { env: request.env } : {},
+          ...request.inheritStdio ? { inheritStdio: true } : {}
         });
       } catch (error) {
         const failure = error;
@@ -25349,18 +25361,21 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       }
       let stdout = "";
       let stderr = "";
+      const live = request.inheritStdio ? streamTo : null;
       handle.on("stdout", (text2) => {
         stdout += text2;
+        live?.output(text2);
       });
       handle.on("stderr", (text2) => {
         stderr += text2;
+        live?.error(text2);
       });
       handle.on("exit", (code) => resolve2({ status: code, stdout, stderr, signal: null }));
       handle.exec();
       if (request.input !== void 0) {
         handle.sendStdin?.(request.input);
       }
-      handle.endStdin?.();
+      if (!request.inheritStdio) handle.endStdin?.();
     });
   }
   // ── HTTP servers living on another thread ─────────────────────────────────
@@ -26361,6 +26376,97 @@ init_variables();
 init_arith();
 init_expand();
 init_builtins();
+
+// src/preview/register.ts
+function serveContainerOn(port, box) {
+  port.onmessage = async (event) => {
+    const request = event.data;
+    try {
+      const response = await box.request(request.port, {
+        method: request.method,
+        path: request.path,
+        headers: request.headers,
+        ...request.body ? { body: new Uint8Array(request.body) } : {}
+      });
+      const bytes2 = response.bytes.slice();
+      port.postMessage(
+        {
+          id: request.id,
+          response: {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            body: bytes2.buffer
+          }
+        },
+        [bytes2.buffer]
+      );
+    } catch (error) {
+      const message = new TextEncoder().encode(error instanceof Error ? error.message : String(error));
+      port.postMessage({
+        id: request.id,
+        response: { status: 502, statusText: "Bad Gateway", headers: {}, body: message.buffer }
+      });
+    }
+  };
+  port.start?.();
+}
+async function createPreview(box, options = {}) {
+  if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) return null;
+  const scriptUrl = options.scriptUrl ?? new URL("./service-worker.js", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+  let registration;
+  try {
+    registration = await navigator.serviceWorker.register(scriptUrl, {
+      type: "module",
+      ...options.scope ? { scope: options.scope } : {}
+    });
+  } catch {
+    return null;
+  }
+  const worker = registration.active ?? registration.waiting ?? registration.installing;
+  if (!worker) return null;
+  if (worker.state !== "activated") {
+    const activated = await new Promise((resolve2) => {
+      const check = () => {
+        if (worker.state === "activated") {
+          worker.removeEventListener("statechange", check);
+          resolve2(true);
+        } else if (worker.state === "redundant") {
+          worker.removeEventListener("statechange", check);
+          resolve2(false);
+        }
+      };
+      worker.addEventListener("statechange", check);
+      setTimeout(() => resolve2(worker.state === "activated"), 1e4);
+      check();
+    });
+    if (!activated) return null;
+  }
+  const channel = new MessageChannel();
+  serveContainerOn(channel.port1, box);
+  worker.postMessage({ type: "sandboxedjs:connect" }, [channel.port2]);
+  const base2 = registration.scope.replace(/\/$/, "");
+  return {
+    urlFor: (port) => `${base2}/__sbx__/${port}/`,
+    dispose: async () => {
+      channel.port1.close();
+      await registration.unregister();
+    }
+  };
+}
+async function renderInto(box, element, options = { port: 80 }) {
+  const response = await box.request(options.port, { path: options.path ?? "/" });
+  const frame = document.createElement("iframe");
+  frame.setAttribute("sandbox", "allow-scripts");
+  frame.style.width = "100%";
+  frame.style.height = "100%";
+  frame.style.border = "0";
+  frame.srcdoc = response.body;
+  element.replaceChildren(frame);
+  return frame;
+}
+
+// src/index.ts
 var src_default = createContainer;
 
 exports.BufferSink = BufferSink;
@@ -26404,6 +26510,7 @@ exports.VirtualHttpServer = VirtualHttpServer;
 exports.VirtualIncomingMessage = VirtualIncomingMessage;
 exports.VirtualServerResponse = VirtualServerResponse;
 exports.WASM_ALIASES = WASM_ALIASES;
+exports.WorkerRuntimePod = WorkerRuntimePod;
 exports.allCommands = allCommands;
 exports.applyChmod = applyChmod;
 exports.braceExpand = braceExpand;
@@ -26416,6 +26523,7 @@ exports.createChildProcessModule = createChildProcessModule;
 exports.createContainer = createContainer;
 exports.createContext = createContext;
 exports.createCoreModules = createCoreModules;
+exports.createPreview = createPreview;
 exports.default = src_default;
 exports.defineCommand = defineCommand;
 exports.evalArith = evalArith;
@@ -26442,6 +26550,7 @@ exports.octalMode = octalMode;
 exports.parseShell = parse;
 exports.parseUmask = parseUmask;
 exports.posixPath = path_exports;
+exports.renderInto = renderInto;
 exports.resetPidCounter = resetPidCounter;
 exports.shellQuote = shellQuote;
 exports.startRuntimeWorker = startRuntimeWorker;