sandboxedjs 0.1.4 → 0.1.6

package/README.md

@@ -459,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
@@ -468,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:
@@ -633,6 +652,25 @@ 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 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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxedjs",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A Linux-like container that runs entirely inside Node.js — POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
   "type": "module",
   "license": "MIT",