sandboxedjs 0.1.6 → 0.1.8

package/README.md

@@ -45,6 +45,7 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **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` |
 | **Python** | MicroPython on WebAssembly, mounted on the *same* filesystem |
+| **WebAssembly** | Any `wasm32-wasi` binary is an executable — [drop it in `$PATH` and run it](#running-compiled-software) |
 | **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 |
 | **Networking** | Virtual interfaces, `/etc/hosts` resolution, in-container HTTP servers, an optional bridge to a real host port |
@@ -259,6 +260,29 @@ await box.waitForPort(3000);
 `yarn` and `pnpm` map onto the same installer. `apt`/`apt-get` reports the built-in package set
 rather than pretending to download Debian archives.
 
+#### Global installs
+
+`npm install -g` works the way it does on a real system. The package goes to
+`/usr/local/lib/node_modules`, every binary its `bin` field declares is linked into
+`/usr/local/bin`, and that directory is already on `$PATH`:
+
+```
+$ npm i -g prettier
+/usr/local/bin/prettier -> /usr/local/lib/node_modules/prettier
+
+$ prettier --version
+3.6.2
+```
+
+Install hooks (`preinstall`, `install`, `postinstall`) run, because for a good number of packages
+the hook is what generates the file `bin` points at. A hook that fails is reported and skipped
+rather than failing the install — the usual cause is a `node-gyp` build that was never going to
+work here, and the package's JavaScript is often fine without it. `--ignore-scripts` opts out, and
+`npm rebuild [-g] [package]` re-runs the hooks and redoes the links without touching the network.
+
+`npm uninstall -g`, `npm ls -g`, `npm root -g`, `npm prefix -g` and `npm bin -g` all operate on
+the same prefix.
+
 #### npx
 
 `npx` works the way you expect: it runs a local binary if there is one, and otherwise installs
@@ -417,6 +441,72 @@ The bundled standard library includes `json`, `re`, `os`, `sys`, `math`, `random
 MicroPython, not CPython — there is no `numpy`, and `pip` can install pure-Python wheels only
 (and only with outbound networking enabled).
 
+### Running compiled software
+
+The container has no CPU, so it cannot execute machine code — but it can execute WebAssembly, and
+most compiled software can be built for it. Anything targeting `wasm32-wasi` is a program here,
+with no registration, wrapper or configuration:
+
+```
+$ cp jq.wasm /usr/local/bin/jq && chmod +x /usr/local/bin/jq
+$ echo '{"name":"ada"}' | jq .name
+"ada"
+```
+
+The kernel decides what a file is by its magic bytes, exactly as `binfmt_misc` does on Linux, so a
+`.wasm` file is dispatched through the same lookup as `grep` or a shell script. The name on `$PATH`
+does not have to end in `.wasm`, `argv[0]` is the name it was invoked as, and the module runs
+against the container's real filesystem — `path_open("data.csv")` opens the file the shell just
+created, and what it writes is there for `cat` afterwards.
+
+To produce a binary that works, target WASI. From Go:
+
+```bash
+GOOS=wasip1 GOARCH=wasm go build -o mytool
+```
+
+From Rust: `cargo build --target wasm32-wasip1`. From C or C++: the `wasi-sdk` clang. Zig:
+`-target wasm32-wasi`.
+
+`wasm info <file>` reports what a module was built for before you try to run it:
+
+```
+$ wasm info mytool
+flavour:   wasi
+imports:   wasi_snapshot_preview1
+threads:   no
+entry:     _start
+runnable:  yes
+```
+
+**What does not run, and how it tells you.** Every executable format is recognised by name, so a
+failure says what the file actually is instead of `Exec format error`:
+
+| File | What happens |
+|---|---|
+| `wasm32-wasi` module | Runs |
+| ELF / Mach-O / PE binary | Named by architecture, with a note that a WebAssembly build would work |
+| Emscripten or wasm-bindgen `.wasm` | Points at the JavaScript loader generated beside it |
+| WASI preview 2 component | Points at `jco transpile` |
+| `GOOS=js` build | Points at `GOOS=wasip1` |
+| Threaded module (shared memory) | Refused up front rather than failing deep inside startup |
+
+The same honesty applies to npm. A package whose `bin` is a compiled executable, or whose real
+payload is one of several platform-gated `optionalDependencies`, is diagnosed at install time
+rather than at first run:
+
+```
+$ npm i -g opencode-ai
+npm warn opencode-ai: 'opencode' points at ./bin/opencode.exe, which is a compiled
+npm warn executable, not JavaScript.
+npm warn Its real binary comes from 12 platform packages (opencode-linux-arm64, …),
+npm warn each of which is native machine code for one OS and CPU.
+```
+
+Limits worth knowing: no threads (`wasi-threads` modules are refused), no sockets (`sock_*`
+returns `ENOTSUP`), and `poll_oneoff` supports clock subscriptions only. Standard input is read to
+completion before a module starts, because WASI's read is synchronous.
+
 ### Filesystem from the host
 
 ```ts
@@ -607,6 +697,30 @@ Those three use dynamic imports, so they only fail if you call them.
 removed and the seam is there, but treat browser support as "should work, unproven" rather than
 a tested claim.
 
+## Uploading files
+
+A file picker in a browser never hands over a path — it hands over the file's bytes. So getting a
+picked file into the container is an ordinary write, and there is nothing to mirror from the host
+disk.
+
+Two ways in, both byte-exact:
+
+```js
+// 1. Directly, when your own server received the upload.
+await box.fs.writeFile("/workspace/uploads/clip.mp4", bytes);   // creates missing directories
+```
+
+```js
+// 2. Through a server running inside the container — a picker in the previewed
+//    app posting to its own backend. Publish the port and upload normally.
+const bridge = await box.expose(3000);
+await fetch(`${bridge.url}/api/upload`, { method: "POST", body: file });
+```
+
+Either way the file lands on the container's filesystem, and `ffmpeg`, Node and Python all see the
+same bytes. Uploads are held in memory like the rest of the filesystem, so a very large video is
+bounded by RAM.
+
 ## Video and audio
 
 `ffmpeg` and `ffprobe` are FFmpeg 5.1 compiled to WebAssembly, mounted on the container's own
@@ -652,26 +766,12 @@ Honest list of what does not work:
   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.
-- **HTTP request bodies into the container are text, not bytes.** Nodepod decodes a request body
-  as UTF-8 on its way to an in-container server, so any byte above `0x7f` is replaced: five bytes
-  containing `0x89` and `0xff` arrive as nine. Uploading a JPEG or an MP4 by POSTing it to a
-  server running inside the sandbox produces a file of roughly the right size that will not open,
-  and reports no error. This affects `box.request()`, `box.expose()` and the request proxy alike.
-
-  Write the file instead — `box.fs.writeFile(path, bytes)` takes a `Uint8Array` and is exact,
-  which the binary round-trip tests assert byte for byte. To accept an upload from a browser,
-  receive it in *your* server and write the bytes into the container:
-
-  ```js
-  // Express on the host, sandboxedjs holding the workspace.
-  app.post("/upload", async (req, res) => {
-    await box.fs.writeFile(`/workspace/uploads/${req.file.originalname}`, req.file.buffer);
-    res.json({ ok: true });
-  });
-  ```
-
-  Text bodies — JSON APIs, form fields, GraphQL — are unaffected.
 - **Python is MicroPython**, so C extensions (`numpy`, `pandas`, `cryptography`) are unavailable.
+- **No machine code.** ELF, Mach-O and PE binaries cannot run, and neither can npm packages that
+  are a wrapper around one. A `wasm32-wasi` build of the same tool does run — see
+  [Running compiled software](#running-compiled-software) — but nothing converts a native binary
+  into one for you.
+- **No WebAssembly threads.** Modules built with shared memory are refused at startup.
 - **No real sockets.** HTTP servers work through the request proxy; raw TCP/UDP does not.
 - **No real processes.** Processes are cooperative async tasks: `kill -9` cannot interrupt a
   tight synchronous loop, and `SIGSTOP` only marks state.

package/bin/sandboxedjs.mjs

@@ -184,8 +184,9 @@ async function printReplBanner(box, opts) {
     "",
     `${BOLD}sandboxedjs${RESET} — a Linux-like container inside Node.js`,
     "",
-    row("node", node, "npm, require, http servers"),
+    row("node", node, "npm, npm -g, require, http servers"),
     row("python3", python && `MicroPython`, "no C extensions (numpy, pandas)"),
+    row("wasm", "wasi p1", "wasm32-wasi binaries run as commands"),
     row("ffmpeg", ffmpeg, ffmpeg ? "video and audio" : "npm install @ffmpeg/core"),
     row(
       "network",
@@ -198,11 +199,14 @@ async function printReplBanner(box, opts) {
     `${DIM}Try:${RESET}`,
     "  cat /etc/os-release && ls /usr/bin | head",
     '  node -e "require(\'http\').createServer((_,r)=>r.end(\'hi\')).listen(3000)" &',
+    "  npm i -g prettier && prettier --version",
     "  npm create vite@latest app -- --template react && cd app && npm i && npm run dev",
-    "  ffmpeg -f lavfi -i testsrc=size=64x64:rate=5:duration=1 out.mp4 && ls -l out.mp4",
+    "  wasm info tool.wasm && chmod +x tool.wasm && ./tool.wasm",
     "",
-    `${DIM}Known limits: no native binaries, no raw sockets, and esbuild-based`,
-    `toolchains (Vite 4 and its contemporaries) cannot start. Current Vite works.${RESET}`,
+    `${DIM}Software runs here if it is JavaScript or WebAssembly. Any wasm32-wasi`,
+    "build is a command: drop it in /usr/local/bin, chmod +x, call it by name.",
+    "Compiled native binaries (ELF, Mach-O, PE) cannot run and say so by name —",
+    `so can npm CLIs that are only a wrapper around one. No raw sockets.${RESET}`,
     "",
     `${DIM}Ctrl-D or \`exit\` to leave.${RESET}`,
     "",