sandboxedjs 0.1.3 → 0.1.5

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 |
+| **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 |
 | **Users** | Real `/etc/passwd` and `/etc/group`; `useradd`, `su`, `sudo`, and permission checks that deny for real — for the shell and Python, [but not Node](#the-in-container-user-model-does-not-constrain-nodejs) |
@@ -458,6 +459,7 @@ and the usual control keys.
 ## Command line
 
 ```bash
+npx sandboxedjs --repl                     # explore: what runs, what doesn't
 npx sandboxedjs                            # interactive shell
 npx sandboxedjs -c 'ls -la /etc'           # one command
 npx sandboxedjs script.sh                  # run a script
@@ -467,6 +469,24 @@ npx sandboxedjs --network -p 3000          # allow outbound, publish a port
 
 Run `sandboxedjs --help` for the full list.
 
+### Trying it out
+
+`--repl` drops you into a shell with a summary of what this container can actually do. Every
+line is measured on the spot rather than claimed, so a runtime that is missing says so:
+
+```
+sandboxedjs — a Linux-like container inside Node.js
+
+  node      v22.12.0      npm, require, http servers
+  python3   MicroPython   no C extensions (numpy, pandas)
+  ffmpeg    5.1.4         video and audio
+  network   on            npm install reaches the real registry
+```
+
+It needs no project and no files — it is meant for finding the edges. Because installing
+packages is most of what people want to test, `--repl` allows outbound access; pass
+`--no-network` to take it away and watch what breaks.
+
 ## Security
 
 The container has no access to your filesystem, environment, or network unless you grant it:
@@ -587,15 +607,51 @@ 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.
 
+## Video and audio
+
+`ffmpeg` and `ffprobe` are FFmpeg 5.1 compiled to WebAssembly, mounted on the container's own
+filesystem. The mount is the point: inputs and outputs are ordinary container files, so nothing
+is staged in or copied back and a pipeline can be built out of scripts and pipes as usual.
+
+The runtime is ~31MB of WebAssembly, which is a lot to force on someone who wants a shell, so it
+installs separately. Without it the commands report themselves as missing, exactly as a real
+system reports an uninstalled binary:
+
+```bash
+npm install @ffmpeg/core
+```
+
+```js
+const box = await createContainer({ cwd: "/media" });
+
+// Make a clip, then transcode it — both files are just container files.
+await box.exec("ffmpeg -f lavfi -i testsrc=size=640x480:rate=25:duration=5 -pix_fmt yuv420p clip.mp4");
+await box.exec("ffmpeg -i clip.mp4 -vf scale=320:-2 -frames:v 1 thumb.png");
+
+const thumbnail = await box.fs.readFile("/media/thumb.png");
+```
+
+Every FFmpeg invocation gets a fresh WebAssembly instance, because FFmpeg ends by calling
+`exit()` and tears its runtime down as it goes; the compiled module is cached, so only the cheap
+half is repeated. Runs are synchronous — a long transcode occupies the thread until it finishes.
+
+Two caveats worth knowing:
+
+- **`ffprobe` does not report an exit status.** Whenever it does real work this build leaves
+  through `exit()` without setting a return value, so success and failure are indistinguishable
+  to the caller. It is reported as success; branch on its *output*, not its exit code. `ffmpeg`
+  itself reports status correctly and can be relied on in `&&` chains.
+- **No hardware acceleration and no native codecs** beyond what the WebAssembly build ships.
+
 ## Known limits
 
 Honest list of what does not work:
 
-- **Vite's dev server** loads and reads its config, then stops when esbuild starts: Nodepod
-  initialises esbuild by importing it from a CDN over `https:`, which the Node ESM loader
-  refuses. Anything that needs esbuild — Vite, and tools built on it — is therefore unavailable
-  under Node. Express, Koa, Fastify-style apps and plain `http` servers work. See
-  `examples/react-app` for a React setup that runs.
+- **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.
 - **Python is MicroPython**, so C extensions (`numpy`, `pandas`, `cryptography`) are unavailable.
 - **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

package/bin/sandboxedjs.mjs

@@ -19,10 +19,13 @@ const USAGE = `sandboxedjs — a Linux-like container inside Node.js
 
 Usage:
   sandboxedjs [options]                 start an interactive shell
+  sandboxedjs --repl                    explore the sandbox interactively
   sandboxedjs [options] -c <command>    run a command and exit
   sandboxedjs [options] <script.sh>     run a shell script and exit
 
 Options:
+      --repl              interactive shell with a summary of what is
+                          available; enables --network (see --no-network)
   -c, --command <cmd>     run <cmd> and exit
   -v, --volume <src:dst>  copy a host directory into the container (repeatable)
   -o, --out <src:dst>     copy a container path back out on exit (repeatable)
@@ -32,6 +35,7 @@ Options:
   -p, --publish <port>    publish a container port on the host (repeatable)
   -H, --hostname <name>   container hostname (default sandbox)
       --network           allow outbound network access (off by default)
+      --no-network        deny outbound access, even under --repl
       --allow <host>      allow one outbound host (implies --network, repeatable)
       --memory <bytes>    RAM reported inside the container
       --cpus <n>          CPU count reported inside the container
@@ -100,9 +104,15 @@ function parseCli(argv) {
       case "--hostname":
         opts.hostname = value();
         break;
+      case "--repl":
+        opts.repl = true;
+        break;
       case "--network":
         opts.network = true;
         break;
+      case "--no-network":
+        opts.noNetwork = true;
+        break;
       case "--allow":
         opts.network = true;
         opts.allow.push(value());
@@ -138,9 +148,78 @@ async function packageVersion() {
   }
 }
 
+const DIM = "";
+const BOLD = "";
+const RESET = "";
+
+/**
+ * Report what this container can actually do, before handing over the prompt.
+ *
+ * Every line is measured rather than asserted: each runtime is asked for its
+ * version, and a runtime that is missing says so. The point of `--repl` is to
+ * find out what runs here, and a banner that listed capabilities from a
+ * hard-coded string would be the one thing that could quietly lie about it.
+ */
+async function printReplBanner(box, opts) {
+  const probe = async (command, extract) => {
+    try {
+      const result = await box.exec(command, { timeoutMs: 60_000 });
+      if (result.exitCode !== 0) return null;
+      return extract(`${result.stdout}${result.stderr}`)?.trim() ?? null;
+    } catch {
+      return null;
+    }
+  };
+
+  const [node, python, ffmpeg] = await Promise.all([
+    probe("node -v", (out) => out.match(/v[\d.]+/)?.[0]),
+    probe("python3 -c \"import sys; print(sys.version.split()[0])\"", (out) => out),
+    probe("ffmpeg -version", (out) => out.match(/ffmpeg version (\S+)/)?.[1]),
+  ]);
+
+  const row = (name, value, note) =>
+    `  ${name.padEnd(10)}${(value ?? "not installed").padEnd(14)}${DIM}${note}${RESET}`;
+
+  const lines = [
+    "",
+    `${BOLD}sandboxedjs${RESET} — a Linux-like container inside Node.js`,
+    "",
+    row("node", node, "npm, require, http servers"),
+    row("python3", python && `MicroPython`, "no C extensions (numpy, pandas)"),
+    row("ffmpeg", ffmpeg, ffmpeg ? "video and audio" : "npm install @ffmpeg/core"),
+    row(
+      "network",
+      opts.network ? "on" : "off",
+      opts.network
+        ? "npm install reaches the real registry"
+        : "outbound denied — drop --no-network to allow it",
+    ),
+    "",
+    `${DIM}Try:${RESET}`,
+    "  cat /etc/os-release && ls /usr/bin | head",
+    '  node -e "require(\'http\').createServer((_,r)=>r.end(\'hi\')).listen(3000)" &',
+    "  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",
+    "",
+    `${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}Ctrl-D or \`exit\` to leave.${RESET}`,
+    "",
+  ];
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
 async function main() {
   const opts = parseCli(process.argv.slice(2));
 
+  /* The REPL exists to answer "what actually runs in here?", and the honest
+   * answer involves installing packages — so it opens the network unless the
+   * caller says otherwise, and the banner states that plainly rather than
+   * leaving it to be discovered. */
+  if (opts.repl && !opts.noNetwork) opts.network = true;
+  if (opts.noNetwork) opts.network = false;
+
   if (opts.help) {
     process.stdout.write(USAGE);
     return 0;
@@ -244,10 +323,14 @@ async function main() {
     return finish(result.exitCode);
   }
 
+  if (opts.repl) await printReplBanner(box, opts);
+
   const session = box.session();
   await new Promise((resolve) => {
     const terminal = new Terminal(session, {
       write: (data) => process.stdout.write(data),
+      // The REPL banner already introduced the container, and says more.
+      ...(opts.repl ? { motd: false } : {}),
       columns: process.stdout.columns ?? 80,
       rows: process.stdout.rows ?? 24,
       onExit: (code) => {