sandboxedjs 0.1.8 → 0.1.9

package/README.md

@@ -46,6 +46,7 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **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) |
+| **x86-64 Linux** | Native ELF binaries run on an emulated CPU, with a Linux syscall layer over 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 |
@@ -443,69 +444,93 @@ MicroPython, not CPython — there is no `numpy`, and `pip` can install pure-Pyt
 
 ### 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:
+Three kinds of program run here. JavaScript and WebAssembly run natively. Native **x86-64 Linux
+binaries run on an emulated CPU** — the container ships an x86-64 interpreter and a Linux syscall
+layer that reads and writes the same filesystem as everything else.
 
 ```
-$ cp jq.wasm /usr/local/bin/jq && chmod +x /usr/local/bin/jq
-$ echo '{"name":"ada"}' | jq .name
-"ada"
+$ file ./mytool
+./mytool: ELF 64-bit LSB executable, x86-64, statically linked
+$ ./mytool --version
 ```
 
-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:
+A statically linked binary needs nothing but the file. Build one with:
 
 ```bash
-GOOS=wasip1 GOARCH=wasm go build -o mytool
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o mytool
 ```
 
-From Rust: `cargo build --target wasm32-wasip1`. From C or C++: the `wasi-sdk` clang. Zig:
-`-target wasm32-wasi`.
+Rust: `cargo build --target x86_64-unknown-linux-musl`. C: `musl-gcc -static`.
 
-`wasm info <file>` reports what a module was built for before you try to run it:
+`x86 info` reports what a binary needs before you run it, and `x86 trace` prints every syscall,
+which is how you find out where something stalls:
 
 ```
-$ wasm info mytool
-flavour:   wasi
-imports:   wasi_snapshot_preview1
-threads:   no
-entry:     _start
+$ x86 info ./mytool
+machine:   x86-64
+linkage:   static
 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`:
+#### Dynamically linked binaries
+
+A binary linked against glibc needs its loader and libraries — and those are **not simulated**.
+They are ordinary x86-64 code, and a machine that can run the program can run them too. Copy them
+in from any Linux system and the binary works:
+
+```
+/lib64/ld-linux-x86-64.so.2
+/lib/x86_64-linux-gnu/libc.so.6
+```
+
+That is a couple of megabytes, not a distribution. If they are missing, the failure names the exact
+file it wanted rather than failing vaguely.
+
+#### WebAssembly
+
+Anything targeting `wasm32-wasi` is also a program, with no emulation and no speed penalty:
+
+```
+$ 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
+every one of these is dispatched through the same lookup as `grep` or a shell script. The name on
+`$PATH` need not match the format, `argv[0]` is the name it was invoked as, and all of them see the
+container's real filesystem — a binary's `open("data.csv")` opens the file the shell just created.
+
+`wasm info <file>` reports what a module was built for.
+
+#### What does not run, and how it tells you
 
 | 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 |
+| Static x86-64 Linux ELF | Runs, emulated |
+| Dynamic x86-64 Linux ELF | Runs once its loader and libraries are present; names them if not |
+| `wasm32-wasi` module | Runs natively |
+| ELF for another architecture | Named by architecture and refused |
+| Mach-O / PE binary | Named as macOS or Windows; another OS is not emulated |
+| Emscripten or wasm-bindgen `.wasm` | Points at the JavaScript loader 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:
+The same honesty applies to npm. A package whose `bin` is a compiled executable, whose payload
+lives in platform-gated `optionalDependencies`, or which declares a `cpu` constraint, 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 of the emulator
 
-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.
+- **Speed.** An interpreter, not a JIT — expect it to be one to two orders of magnitude slower
+  than native. Fine for a CLI, wrong for a compiler.
+- **Threads are cooperative.** `clone` creates a real thread with its own registers and stack, but
+  only one runs at a time, and switches happen at `futex`, `sched_yield` and `nanosleep`. A thread
+  that spins on memory without entering the kernel keeps the machine to itself.
+- **Integer and the common vector instructions only.** Moves, bitwise operations, byte compares
+  and scalar floating point are implemented; the wider AVX paths are not. An unimplemented
+  instruction names itself and dumps the registers instead of misbehaving quietly.
+- **No sockets, no signals, no `fork`/`exec`.** A guest cannot start another process.
 
 ### Filesystem from the host
 
@@ -767,10 +792,12 @@ Honest list of what does not work:
   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 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.
+- **The x86-64 emulator is an interpreter**, so native binaries run one to two orders of magnitude
+  slower than they would on a real CPU, its threads are cooperative rather than parallel, and it
+  implements the integer and common vector instructions rather than all of AVX. See
+  [Running compiled software](#running-compiled-software).
+- **macOS and Windows binaries cannot run.** Another instruction set is a matter of emulation;
+  another operating system is not.
 - **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
@@ -844,6 +871,39 @@ await box.exec("greet there | tr a-z A-Z"); // → HELLO THERE
 
 It becomes a real file in `/usr/bin`, so `which greet`, `man greet` and shebang dispatch all work.
 
+### Adding an executable format
+
+The kernel identifies executables by magic bytes and dispatches to a registered handler, the way
+`binfmt_misc` does. WebAssembly is one such handler; so is each native format. Registering your own
+is the supported way to teach the container a new kind of binary — including plugging in an
+emulator:
+
+```ts
+import { createContainer, type ExecFormat } from "sandboxedjs";
+
+const box = await createContainer();
+
+const upx: ExecFormat = {
+  name: "upx",
+  priority: 5, // consulted before the ELF handler
+  matches: (head) => head.subarray(0, 4).toString() === "UPX!",
+  describe: () => "UPX-compressed executable",
+  run: async (ctx, path) => {
+    /* decompress, then hand off however you like */
+    return 0;
+  },
+};
+
+box.kernel.formats.register(upx);
+```
+
+A handler with no `run` is still useful: `explain(head, path)` returns the lines printed in place
+of `Exec format error`, which is how ELF, Mach-O and PE files report what they are.
+
+The x86-64 handler in `src/runtime/x86/` is the worked example: it matches on `\x7fELF` and its
+`run` boots an interpreter, a Linux syscall layer and a process image. A handler for another
+architecture would sit alongside it without the kernel changing at all.
+
 ## Examples
 
 See [`examples/`](./examples): a REPL, an Express API, a React app, a Python data pipeline, an

package/bin/sandboxedjs.mjs

@@ -187,6 +187,7 @@ async function printReplBanner(box, opts) {
     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("x86-64", "emulated", "static Linux ELF binaries run too"),
     row("ffmpeg", ffmpeg, ffmpeg ? "video and audio" : "npm install @ffmpeg/core"),
     row(
       "network",
@@ -202,11 +203,12 @@ async function printReplBanner(box, opts) {
     "  npm i -g prettier && prettier --version",
     "  npm create vite@latest app -- --template react && cd app && npm i && npm run dev",
     "  wasm info tool.wasm && chmod +x tool.wasm && ./tool.wasm",
+    "  x86 info ./linux-binary && ./linux-binary   # native ELF, emulated",
     "",
-    `${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}JavaScript and WebAssembly run natively. Static x86-64 Linux binaries run`,
+    "on an emulated CPU — slower, and threads are cooperative. Dynamically linked",
+    "ones also need their loader and libc copied in. macOS and Windows binaries",
+    `cannot run and say so by name. No raw sockets.${RESET}`,
     "",
     `${DIM}Ctrl-D or \`exit\` to leave.${RESET}`,
     "",