sandboxedjs 0.1.22 → 0.1.24

package/README.md

@@ -4,8 +4,9 @@ A Linux-like container that runs entirely inside a Node.js process. No Docker, n
 modules — a virtual filesystem, a POSIX shell, 154 Unix programs, and both Node.js and Python
 runtimes, all in-process.
 
-Built on [Nodepod](https://github.com/R1ck404/Nodepod), which supplies the Node.js execution
-engine and the in-memory volume.
+The Node.js runtime is its own: a module engine that loads both CommonJS and ES modules, an
+in-memory volume, an npm-registry installer and a virtual HTTP stack, with no native modules and
+no dependency on the host's `node_modules`.
 
 ```ts
 import { createContainer } from "sandboxedjs";
@@ -43,7 +44,7 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **Filesystem** | Full FHS tree (`/etc`, `/usr`, `/var`, `/home`, …), permissions, ownership, symlinks, hard links, `umask`, sticky bits |
 | **Shell** | POSIX `sh` (54 builtins) — pipelines, redirection, here-docs, globbing, brace/parameter/arithmetic/command expansion, functions, `if`/`for`/`while`/`case`/`select`, job control, traps, arrays, `[[ ]]`, `(( ))` |
 | **Coreutils** | 154 programs — `ls cat cp mv rm mkdir grep sed awk find head tail sort uniq wc cut tr tee xargs chmod chown ln du df ps tar gzip base64 sha256sum diff curl wget` and the rest — plus 54 shell builtins |
-| **Node.js** | Real Node semantics via Nodepod — `require`, npm packages, `http`, `fs`, streams, `worker_threads` |
+| **Node.js** | Its own module engine — `require` *and* `import`, live bindings, `exports` maps, top-level `await`, npm packages, `http`, `fs`, streams, `child_process` |
 | **Python** | CPython 3.13 (Pyodide) on the *same* filesystem, with the real standard library |
 | **FFmpeg** | `ffmpeg` and `ffprobe` (FFmpeg 5.1) reading and writing container files directly — [optional install](#video-and-audio) |
 | **`/proc`** | Live and synthesised — `ps`, `top`, `free` and `uptime` all read the same source |
@@ -219,10 +220,11 @@ The iframe is cross-origin, so your IDE cannot read its DOM. You can still:
 #### 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, the preview goes through Nodepod's service
-worker instead of this package: boot Nodepod's browser build, pass it in with
-`createContainer({ pod })`, and use Nodepod's own preview iframe support. I have not verified
-that path; see [Running in a browser](#running-in-a-browser).
+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.
 
 ### npm and npx
 
@@ -517,10 +519,14 @@ so it can read and write any path in the container regardless of `user`:
 await box.exec("node -e \"require('fs').readFileSync('/root/secret')\"", { user: "agent" }); // succeeds
 ```
 
-Node code runs inside Nodepod's worker, which owns the volume and has no notion of container
-uids. Treat `user` as a way to model *ordinary* multi-user behaviour, not as a privilege
-boundary for JavaScript you do not trust. If untrusted JavaScript must not see something, keep
-it out of the container rather than relying on file modes.
+Node code runs on the JavaScript runtime, which owns its own volume and has no notion of
+container uids. Treat `user` as a way to model *ordinary* multi-user behaviour, not as a
+privilege boundary for JavaScript you do not trust. If untrusted JavaScript must not see
+something, keep it out of the container rather than relying on file modes.
+
+The runtime also shares the host's JavaScript realm today rather than running in a worker, so a
+program inside the container can reach host globals. Isolating it in a worker is planned; until
+then, do not treat the container as a boundary against hostile code.
 
 ### And it is not a VM
 
@@ -579,9 +585,8 @@ resolve their implementation at call time (`node:zlib`/`node:crypto` on Node,
 `CompressionStream`/`crypto.subtle` plus a JS MD5 in a browser), so nothing pulls a `node:`
 builtin in when the module loads and a bundler will not fail on it.
 
-**One call, either side.** `createContainer()` picks its own host: the headless
-`worker_threads` engine on Node, Nodepod's browser build in a browser. You do not import Nodepod,
-and you do not pass a pod:
+**One call, either side.** `createContainer()` boots its own runtime. There is no host to pick
+and no pod to pass:
 
 ```ts
 import { createContainer } from "sandboxedjs";
@@ -592,40 +597,32 @@ await box.exec("ls -la /");      // shell + coreutils
 await box.exec("node app/index.js");
 ```
 
-**Serve the service worker.** In a browser, a container's preview iframe reaches an HTTP server
-running inside the page through a service worker, and a browser will not register one from
-`node_modules` — it has to come from your own origin at `/__sw__.js`. One line:
-
-```ts
-// vite.config.ts
-import sandboxedjs from "sandboxedjs/vite";
-export default defineConfig({ plugins: [sandboxedjs()] });
-```
-
-For anything else, `sandboxedjs/server` exports `serveSW()` (Fetch-style hosts) and
-`serveSWNode()` (Express, Fastify, `node:http`). Skip it with
-`createContainer({ browser: { serviceWorker: false } })`, which also disables preview iframes.
+**Not done — three things stand between this and a browser IDE.**
 
-You can still boot the pod yourself and pass it as `pod` when you need control over Nodepod's
-own options.
-
-**Verified in a browser.** Booted under Vite, the following run:
-
-```
-$ uname -a              Linux sandbox 5.10.0 (sandboxedjs@nodepod) … x86_64 GNU/Linux
-$ ls -la /app           the mounted files
-$ grep beta …           beta
-$ node /app/hello.js    node runtime says hi
-```
+- *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.
+- *esbuild.* 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`, which is why Vite's dev server works there. In a browser there is
+  nothing to borrow, so anything routed through esbuild fails until esbuild-wasm runs *inside*
+  the sandbox.
 
-Shell, coreutils, the virtual filesystem and the Node runtime all work. Boot costs about ten
-seconds, nearly all of it Nodepod starting.
+Everything else is already browser-shaped. Nothing in the runtime imports a `node:` builtin except
+through an explicitly Node-only path that returns `null` elsewhere, compression and hashing pick
+their implementation at call time, and the module engine, volume, HTTP stack and npm installer are
+built on `fetch`, `acorn`, `resolve.exports`, `@noble/hashes` and `pako`.
 
 **What does not work in a browser:**
 
 - `copyIn()` / `copyOut()` — they read and write the host filesystem, which does not exist.
-- `expose()` — it opens a real `node:http` listener. Use the service worker and a preview iframe
-  to reach an in-container server instead of a host port.
+- `expose()` — it opens a real `node:http` listener. Use `request()` to reach an in-container
+  server instead of a host port.
 - `python3` — see below.
 - The `sandboxedjs` CLI, obviously.
 
@@ -736,11 +733,18 @@ Two caveats worth knowing:
 
 Honest list of what does not work:
 
-- **esbuild-based toolchains.** Nodepod boots esbuild by importing it from a CDN over `https:`,
-  which the Node ESM loader refuses, so anything routed through esbuild cannot start under Node.
-  This affects older toolchains — Vite 4 and its contemporaries. Current Vite ships its Rust
-  pipeline as WebAssembly and runs fine, dev server included, as do Express, Koa, Fastify-style
-  apps and plain `http` servers.
+- **Compiled native addons.** A `.node` file cannot be loaded, so a package that ships one has to
+  have a JavaScript or WebAssembly build to fall back on. `rollup` and `esbuild` do, and the
+  runtime redirects those two names to `@rollup/wasm-node` and `esbuild-wasm` automatically when
+  they are installed. **Vite 8 does not work** for this reason: it builds on Rolldown, whose only
+  sandbox-viable binding needs WASI and `worker_threads`. Vite 7 runs, dev server included, as do
+  Express, Koa, Fastify-style apps and plain `http` servers.
+- **`child_process` is asynchronous only.** `spawn`, `exec` and `execFile` run through the kernel,
+  so a child sees the same filesystem and coreutils as the shell. `execSync`, `spawnSync` and
+  `execFileSync` throw `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`: blocking the JavaScript thread on
+  another process is not expressible here.
+- **No `net`, `tls`, `worker_threads` or `vm`.** `http` and `https` are served by a virtual stack
+  that `request()` talks to directly, so servers work; raw sockets do not.
 - **Python is CPython via Pyodide.** The standard library is the real one. A C
   extension works only if it has been built for WebAssembly — Pyodide ships
   many, including `numpy`, but an arbitrary wheel from PyPI will not install.
@@ -772,6 +776,9 @@ Honest list of what does not work:
 | `timezone` | `string` | `"UTC"` | |
 | `timeoutMs` | `number` | none | Default limit for `exec` |
 | `onStdout` / `onStderr` | `(chunk: string) => void` | — | Container-wide output taps |
+| `onServerReady` | `(port, url) => void` | — | Fires when something inside starts listening |
+| `pod` | `RuntimePod` | booted for you | Share or substitute the JavaScript runtime |
+| `python` | `PythonOptions` | jsDelivr | Where to load Pyodide from |
 
 ### `Container`
 
@@ -825,5 +832,4 @@ agent sandbox, and a browser terminal.
 
 ## License
 
-MIT. Nodepod itself is MIT with the Commons Clause; this package depends on it rather than
-redistributing it.
+MIT, with no dependency carrying a stricter licence.