Merge pull request #12 from rivet-dev/ralph/kernel-hardening

chore: kernel hardening

Author: NathanFlurry

.agent/contracts/node-stdlib.md

@@ -130,7 +130,13 @@ The `crypto` module SHALL be classified as Stub (Tier 3). `getRandomValues()` an
 
 #### Scenario: Calling crypto.subtle.digest
 - **WHEN** sandboxed code calls `crypto.subtle.digest("SHA-256", data)`
-- **THEN** the call MUST throw an error indicating subtle crypto is not supported in sandbox
+- **THEN** the call MUST delegate to host `node:crypto` and return an ArrayBuffer containing the hash
+
+#### Scenario: crypto.subtle operations delegate to host
+- **WHEN** sandboxed code calls any `crypto.subtle` method (digest, encrypt, decrypt, sign, verify, generateKey, importKey, exportKey)
+- **THEN** the operation MUST delegate to host `node:crypto` via the `_cryptoSubtle` bridge ref
+- **AND** all cryptographic material MUST be transferred as base64-encoded JSON across the isolate boundary
+- **AND** CryptoKey objects in the sandbox MUST be opaque wrappers holding serialized key data
 
 ### Requirement: Unimplemented Module Tier Assignments
 The following modules SHALL be classified as Deferred (Tier 4): `net`, `tls`, `readline`, `perf_hooks`, `async_hooks`, `worker_threads`, `diagnostics_channel`. The following modules SHALL be classified as Unsupported (Tier 5): `dgram`, `http2` (full), `cluster`, `wasi`, `inspector`, `repl`, `trace_events`, `domain`.

CLAUDE.md

@@ -55,6 +55,16 @@
 - track development friction in `docs-internal/friction.md` (mark resolved items with fix notes)
 - see `.agent/contracts/README.md` for the full contract index
 
+## Shell & Process Behavior (POSIX compliance)
+
+- the interactive shell (brush-shell via WasmVM) and kernel process model must match POSIX behavior unless explicitly documented otherwise
+- `node -e <code>` must produce stdout/stderr visible to the user, both through `kernel.exec()` and in the interactive shell PTY — identical to running `node -e` on a real Linux terminal
+- `node -e <invalid>` must display the error (SyntaxError/ReferenceError) on stderr, not silently swallow it
+- commands that only read stdin when stdin is a TTY (e.g. `tree`, `cat` with no args) must not hang when run from the shell; commands must detect whether stdin is a real data source vs an empty pipe/PTY
+- Ctrl+C (SIGINT) must interrupt the foreground process group within 1 second, matching POSIX `isig` + `VINTR` behavior — this applies to all runtimes (WasmVM, Node, Python)
+- signal delivery through the PTY line discipline → kernel process table → driver kill() chain must be end-to-end tested
+- when adding or fixing process/signal/PTY behavior, always verify against the equivalent behavior on a real Linux system
+
 ## Compatibility Project-Matrix Policy
 
 - compatibility fixtures live under `packages/secure-exec/tests/projects/` and MUST be black-box Node projects (`package.json` + source entrypoint)
@@ -63,6 +73,13 @@
 - the matrix runs each fixture in host Node and secure-exec and compares normalized `code`, `stdout`, and `stderr`
 - no known-mismatch classification is allowed; parity mismatches stay failing until runtime/bridge behavior is fixed
 
+## Tested Package Tracking
+
+- the Tested Packages section in `docs/nodejs-compatibility.mdx` lists all packages validated via the project-matrix test suite
+- when adding a new project-matrix fixture, add the package to the Tested Packages table
+- when removing a fixture, remove the package from the table
+- the table links to GitHub Issues for requesting new packages to be tracked
+
 ## Test Structure
 
 - `tests/test-suite/{node,python}.test.ts` are integration suite drivers; `tests/test-suite/{node,python}/` hold the shared suite definitions
@@ -97,6 +114,8 @@ Follow the style in `packages/secure-exec/src/index.ts`.
   - `docs/runtimes/python.mdx` — update when PythonRuntime options/behavior changes
   - `docs/system-drivers/node.mdx` — update when createNodeDriver options change
   - `docs/system-drivers/browser.mdx` — update when createBrowserDriver options change
+  - `docs/nodejs-compatibility.mdx` — update when bridge, polyfill, or stub implementations change; keep the Tested Packages section current when adding or removing project-matrix fixtures
+  - `docs/cloudflare-workers-comparison.mdx` — update when secure-exec capabilities change; bump "Last updated" date
 
 ## Backlog Tracking
 

docs/comparison/cloudflare-workers.mdx

@@ -5,7 +5,7 @@ description: Node.js API compatibility comparison between secure-exec and Cloudf
 icon: "scale-balanced"
 ---
 
-*Last updated: 2026-03-10*
+*Last updated: 2026-03-18*
 
 ## Overview
 
@@ -40,8 +40,8 @@ All three CF deployment models share the same `nodejs_compat` API surface. WfP a
 
 | Module | secure-exec | CF Workers (`nodejs_compat`) | Notes |
 | --- | --- | --- | --- |
-| **`fs`** | 🟡 Core I/O: `readFile`, `writeFile`, `appendFile`, `open`, `read`, `write`, `close`, `readdir`, `mkdir`, `rmdir`, `rm`, `unlink`, `stat`, `lstat`, `rename`, `copyFile`, `exists`, `createReadStream`, `createWriteStream`, `writev`, `access`, `realpath`. Missing: `cp`, `glob`, `opendir`, `mkdtemp`, `statfs`, `readv`, `fdatasync`, `fsync`. Deferred: `watch`, `watchFile`, `chmod`, `chown`, `link`, `symlink`, `readlink`, `truncate`, `utimes`. Full coverage planned. | 🟡 In-memory VFS only. `/bundle` (read-only), `/tmp` (writable, ephemeral per-request), `/dev` devices. Missing: `watch`, `watchFile`, `globSync`, file permissions/ownership. All operations synchronous regardless of API style. Timestamps frozen to Unix epoch. 128 MB max file size. | **secure-exec**: Permission-gated; filesystem behavior determined by system driver (host FS or VFS). Read-only `/app/node_modules` overlay. **CF**: No persistent storage; `/tmp` contents isolated per request and lost after response; no real permissions or ownership. |
-| **`http`** | 🟡 `request`, `get`, `createServer` with bridged request/response classes. Fetch-based, fully buffered. No connection pooling, no keep-alive tuning, no WebSocket upgrade, no trailer headers. `Agent` is stub-only. | 🟡 `request`, `get`, `createServer` via fetch API wrapper. Requires extra compat flags. No `Connection` headers, no `Expect: 100-continue`, no socket-level events (`socket`, `upgrade`), no 1xx responses, no trailer headers. `Agent` is stub-only. | |
+| **`fs`** | 🟢 Core I/O: `readFile`, `writeFile`, `appendFile`, `open`, `read`, `write`, `close`, `readdir`, `mkdir`, `rmdir`, `rm`, `unlink`, `stat`, `lstat`, `rename`, `copyFile`, `exists`, `createReadStream`, `createWriteStream`, `writev`, `access`, `realpath`, `cp`, `glob`, `opendir`, `mkdtemp`, `statfs`, `readv`, `fdatasync`, `fsync`, `chmod`, `chown`, `link`, `symlink`, `readlink`, `truncate`, `utimes`. Deferred: `watch`, `watchFile`. | 🟡 In-memory VFS only. `/bundle` (read-only), `/tmp` (writable, ephemeral per-request), `/dev` devices. Missing: `watch`, `watchFile`, `globSync`, file permissions/ownership. All operations synchronous regardless of API style. Timestamps frozen to Unix epoch. 128 MB max file size. | **secure-exec**: Permission-gated; filesystem behavior determined by system driver (host FS or VFS). Read-only `/app/node_modules` overlay. **CF**: No persistent storage; `/tmp` contents isolated per request and lost after response; no real permissions or ownership. |
+| **`http`** | 🟡 `request`, `get`, `createServer` with bridged request/response classes. Fetch-based, fully buffered. `Agent` with connection pooling and per-host `maxSockets` limits. HTTP upgrade (101 Switching Protocols) support. Trailer header support on `IncomingMessage`. No keep-alive tuning, no WebSocket data framing. | 🟡 `request`, `get`, `createServer` via fetch API wrapper. Requires extra compat flags. No `Connection` headers, no `Expect: 100-continue`, no socket-level events (`socket`, `upgrade`), no 1xx responses, no trailer headers. `Agent` is stub-only. | |
 | **`https`** | 🟡 Same contract and limitations as `http`. | 🟡 Same wrapper model and limitations as `http`. | |
 | **`http2`** | 🔴 Compatibility classes only; `createServer`/`createSecureServer` throw. | 🔴 Non-functional stub. | Neither platform supports HTTP/2 server creation. |
 | **`net`** | 🔵 Planned. | 🟡 `net.connect()` / `net.Socket` for outbound TCP via Cloudflare Sockets API. No `net.createServer()`. | **CF**: Outbound TCP connections supported. **secure-exec**: On roadmap. |
@@ -56,7 +56,7 @@ All three CF deployment models share the same `nodejs_compat` API surface. WfP a
 | **`process`** | 🟢 `env` (permission-gated), `cwd`/`chdir`, `exit`, timers, stdio event emitters, `hrtime`, `platform`, `arch`, `version`, `argv`, `pid`, `ppid`, `uid`, `gid`. | 🟡 `env`, `cwd`/`chdir`, `exit`, `nextTick`, `stdin`/`stdout`/`stderr`, `platform`, `arch`, `version`. No real process IDs or OS-level user/group IDs. Requires extra `enable_nodejs_process_v2` flag for full surface. | **secure-exec**: Configurable timing mitigation (`freeze` mode); real `pid`/`uid`/`gid` metadata. **CF**: Synthetic process metadata. |
 | **`child_process`** | 🟢 `spawn`, `spawnSync`, `exec`, `execSync`, `execFile`, `execFileSync`. `fork` unsupported. | 🔴 Non-functional stub; all methods throw. | **secure-exec**: Bound to the system driver; subprocess behavior determined by driver implementation. CF has no subprocess support. |
 | **`os`** | 🟢 `platform`, `arch`, `type`, `release`, `version`, `homedir`, `tmpdir`, `hostname`, `userInfo`, `os.constants`. | 🟡 Basic platform/arch metadata. | **secure-exec**: Richer OS metadata surface. |
-| **`worker_threads`** | ⛔ Stubs that throw on API call. | 🔴 Non-functional stub. | Neither platform supports worker threads. |
+| **`worker_threads`** | 🔴 Requireable; all APIs throw deterministic unsupported errors. | 🔴 Non-functional stub. | Neither platform supports worker threads. |
 | **`cluster`** | ⛔ `require()` throws. | 🔴 Non-functional stub. | Neither platform supports clustering. |
 | **`timers`** | 🟢 `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `setImmediate`, `clearImmediate`. | 🟢 Same surface; returns `Timeout` objects. | Equivalent support. |
 | **`vm`** | 🔴 Browser polyfill via `Function()`/`eval()`. No real context isolation; shares global scope. | 🔴 Non-functional stub. | Neither offers real `vm` sandboxing. secure-exec polyfill silently runs code in shared scope, not safe for isolation. |
@@ -91,13 +91,13 @@ All three CF deployment models share the same `nodejs_compat` API surface. WfP a
 | **`events`** | 🟢 Supported. | 🟢 Supported. | |
 | **`module`** | 🟢 `createRequire`, `Module` basics, builtin resolution. | 🟡 Limited surface. | **secure-exec**: CJS/ESM with `createRequire`. |
 | **`console`** | 🟢 Circular-safe bounded formatting; drop-by-default with `onStdio` hook. | 🟢 Supported; output routed to Workers Logs / Tail Workers. | |
-| **`async_hooks`** | ⚪ TBD. | 🔴 Non-functional stub. | |
-| **`perf_hooks`** | ⚪ TBD. | 🟡 Limited surface. | |
-| **`diagnostics_channel`** | ⚪ TBD. | 🟢 Supported. | |
-| **`readline`** | ⚪ TBD. | 🔴 Non-functional stub. | |
+| **`async_hooks`** | 🔴 Stub: `AsyncLocalStorage` (run/enterWith/getStore/disable/exit), `AsyncResource` (runInAsyncScope/emitDestroy), `createHook` (returns enable/disable no-ops), `executionAsyncId`/`triggerAsyncId`. All methods are callable but do not track real async context. | 🔴 Non-functional stub. | |
+| **`perf_hooks`** | 🔴 Requireable stub; APIs throw deterministic unsupported errors. | 🟡 Limited surface. | |
+| **`diagnostics_channel`** | 🔴 Stub: `channel()`, `hasSubscribers()`, `tracingChannel()`, `Channel` constructor. All channels report no subscribers; `publish` is a no-op. Sufficient for framework compatibility (e.g., Fastify). | 🟢 Supported. | |
+| **`readline`** | 🔴 Requireable stub; APIs throw deterministic unsupported errors. | 🔴 Non-functional stub. | |
 | **`tty`** | 🔴 `isatty()` returns `false`; `ReadStream`/`WriteStream` throw. | 🔴 Stub-like. | Both platforms are essentially non-functional beyond `isatty()`. |
 | **`constants`** | 🟢 Supported. | 🟢 Supported. | |
-| **`punycode`** | Not listed. | 🟢 Supported (deprecated). | |
+| **`punycode`** | 🟢 Supported via `node-stdlib-browser` polyfill (deprecated upstream). | 🟢 Supported (deprecated). | |
 
 ### Unsupported in Both
 

docs/nodejs-compatibility.mdx

@@ -39,7 +39,7 @@ Unsupported modules use: `"<module> is not supported in sandbox"`.
 | `buffer` | 2 (Polyfill) | Polyfill via `buffer`. |
 | `url` | 2 (Polyfill) | Polyfill via `whatwg-url` and node-stdlib-browser shims. |
 | `events` | 2 (Polyfill) | Polyfill via `events`. |
-| `stream` | 2 (Polyfill) | Polyfill via `readable-stream`. |
+| `stream` | 2 (Polyfill) | Polyfill via `readable-stream`. `stream/web` subpath supported (Web Streams API: `ReadableStream`, `WritableStream`, `TransformStream`, etc.). |
 | `util` | 2 (Polyfill) | Polyfill via node-stdlib-browser. |
 | `assert` | 2 (Polyfill) | Polyfill via node-stdlib-browser. |
 | `querystring` | 2 (Polyfill) | Polyfill via node-stdlib-browser. |
@@ -53,7 +53,8 @@ Unsupported modules use: `"<module> is not supported in sandbox"`.
 | `constants` | 2 (Polyfill) | `constants-browserify`; `os.constants` remains available via `os`. |
 | Fetch globals (`fetch`, `Headers`, `Request`, `Response`) | 1 (Bridge) | Bridged via network bridge implementation. |
 | `async_hooks` | 3 (Stub) | `AsyncLocalStorage` (with `run`, `enterWith`, `getStore`, `disable`, `exit`), `AsyncResource` (with `runInAsyncScope`, `emitDestroy`), `createHook` (returns enable/disable no-ops), `executionAsyncId`, `triggerAsyncId`. |
-| `diagnostics_channel` | 3 (Stub) | No-op `channel()` and `tracingChannel()` stubs; channels always report `hasSubscribers: false`; `publish`, `subscribe`, `unsubscribe` are no-ops. Provides Fastify compatibility. |
+| `console` | 1 (Bridge) | Circular-safe bounded formatting via bridge shim; `log`, `warn`, `error`, `info`, `debug`, `dir`, `time`/`timeEnd`/`timeLog`, `assert`, `clear`, `count`/`countReset`, `group`/`groupEnd`, `table`, `trace`. Drop-by-default; consumers use `onStdio` hook for streaming. |
+| `diagnostics_channel` | 3 (Stub) | No-op `channel()`, `tracingChannel()`, `Channel` constructor; channels always report `hasSubscribers: false`; `publish`, `subscribe`, `unsubscribe` are no-ops. Provides Fastify compatibility. |
 | Deferred modules (`net`, `tls`, `readline`, `perf_hooks`, `worker_threads`) | 4 (Deferred) | `require()` returns stubs; APIs throw deterministic unsupported errors when called. |
 | Unsupported modules (`dgram`, `cluster`, `wasi`, `inspector`, `repl`, `trace_events`, `domain`) | 5 (Unsupported) | `require()` fails immediately with deterministic unsupported-module errors. |
 
@@ -69,8 +70,25 @@ The [project-matrix test suite](https://github.com/rivet-dev/secure-exec/tree/ma
 | [vite](https://npmjs.com/package/vite) | Build Tool | ESM, HMR server, plugin system |
 | [astro](https://npmjs.com/package/astro) | Web Framework | Island architecture, SSR, multi-framework |
 | [hono](https://npmjs.com/package/hono) | Web Framework | ESM imports, lightweight HTTP |
+| [axios](https://npmjs.com/package/axios) | HTTP Client | HTTP client requests via fetch adapter, JSON APIs |
+| [node-fetch](https://npmjs.com/package/node-fetch) | HTTP Client | Fetch polyfill using http module, stream piping |
 | [dotenv](https://npmjs.com/package/dotenv) | Configuration | Environment variable loading, fs reads |
 | [semver](https://npmjs.com/package/semver) | Utility | Version parsing and comparison |
+| [ssh2](https://npmjs.com/package/ssh2) | Networking | SSH client/server, crypto, streams, events |
+| [ssh2-sftp-client](https://npmjs.com/package/ssh2-sftp-client) | Networking | SFTP client, file transfer APIs over SSH |
+| [pg](https://npmjs.com/package/pg) | Database | PostgreSQL client, Pool/Client classes, type parsers |
+| [mysql2](https://npmjs.com/package/mysql2) | Database | MySQL client, connection/pool classes, escape/format utilities |
+| [ioredis](https://npmjs.com/package/ioredis) | Database | Redis client, Cluster, Command, pipeline/multi transaction APIs |
+| [drizzle-orm](https://npmjs.com/package/drizzle-orm) | Database | ORM schema definition, query building, ESM module graph |
+| [ws](https://npmjs.com/package/ws) | Networking | WebSocket client/server, HTTP upgrade, events |
+| [jsonwebtoken](https://npmjs.com/package/jsonwebtoken) | Crypto | JWT signing (HS256), verification, decode |
+| [bcryptjs](https://npmjs.com/package/bcryptjs) | Crypto | Pure JS password hashing and verification |
+| [chalk](https://npmjs.com/package/chalk) | Terminal | Terminal string styling, ANSI escape codes |
+| [lodash-es](https://npmjs.com/package/lodash-es) | Utility | Large ESM module resolution at scale |
+| [pino](https://npmjs.com/package/pino) | Logging | Structured JSON logging, child loggers, serializers |
+| [uuid](https://npmjs.com/package/uuid) | Crypto | UUID generation (v4, v5), validation, version detection |
+| [yaml](https://npmjs.com/package/yaml) | Utility | YAML parsing, stringifying, document API |
+| [zod](https://npmjs.com/package/zod) | Validation | Schema definition, parsing, safe parse, transforms |
 | [rivetkit](https://npmjs.com/package/rivetkit) | SDK | Local vendor package resolution |
 | crypto (builtin) | Crypto | `crypto.randomBytes`, `randomUUID`, `getRandomValues` |
 | fs-metadata-rename | Filesystem | `stat` metadata, `rename` semantics |
@@ -85,6 +103,7 @@ The [project-matrix test suite](https://github.com/rivet-dev/secure-exec/tree/ma
 | yarn-berry-layout | Package Manager | Yarn Berry PnP/node_modules layout |
 | bun-layout | Package Manager | Bun `node_modules` layout |
 | workspace-layout | Package Manager | npm workspace `node_modules` layout |
+| sse-streaming | Networking | SSE server, chunked transfer-encoding, streaming reads |
 | net-unsupported (fail) | Error Handling | `net.createServer` correctly errors |
 
 To request a new package be added to the test suite, [open an issue](https://github.com/rivet-dev/secure-exec/issues/new?labels=package-request&title=Package+request:+%5Bpackage-name%5D).

packages/kernel/src/kernel.ts

@@ -427,9 +427,13 @@ class KernelImpl implements Kernel {
 		// Resolve output callbacks: when a child inherits non-piped stdio from
 		// a parent, forward output to the parent's DriverProcess callbacks so
 		// cross-runtime child output reaches the top-level collector.
+		// When piped, wire a callback that forwards through the pipe/PTY so
+		// drivers that emit output via callbacks (Node) reach the PTY/pipe.
 		let stdoutCb: ((data: Uint8Array) => void) | undefined;
 		let stderrCb: ((data: Uint8Array) => void) | undefined;
-		if (!stdoutPiped) {
+		if (stdoutPiped) {
+			stdoutCb = this.createPipedOutputCallback(table, 1);
+		} else {
 			if (options?.onStdout) {
 				stdoutCb = options.onStdout;
 			} else if (callerPid !== undefined) {
@@ -440,7 +444,9 @@ class KernelImpl implements Kernel {
 			}
 			if (!stdoutCb) stdoutCb = (data) => stdoutBuf.push(data);
 		}
-		if (!stderrPiped) {
+		if (stderrPiped) {
+			stderrCb = this.createPipedOutputCallback(table, 2);
+		} else {
 			if (options?.onStderr) {
 				stderrCb = options.onStderr;
 			} else if (callerPid !== undefined) {
@@ -983,6 +989,32 @@ class KernelImpl implements Kernel {
 		return this.pipeManager.isPipe(entry.description.id) || this.ptyManager.isPty(entry.description.id);
 	}
 
+	/**
+	 * Create a callback that forwards data through a piped stdio FD.
+	 * Needed for drivers (like Node) that emit output via callbacks rather
+	 * than kernel FD writes (like WasmVM does via WASI fd_write).
+	 */
+	private createPipedOutputCallback(
+		table: ProcessFDTable,
+		fd: number,
+	): ((data: Uint8Array) => void) | undefined {
+		const entry = table.get(fd);
+		if (!entry) return undefined;
+
+		const descId = entry.description.id;
+		if (this.pipeManager.isPipe(descId)) {
+			return (data) => {
+				try { this.pipeManager.write(descId, data); } catch { /* pipe closed */ }
+			};
+		}
+		if (this.ptyManager.isPty(descId)) {
+			return (data) => {
+				try { this.ptyManager.write(descId, data); } catch { /* pty closed */ }
+			};
+		}
+		return undefined;
+	}
+
 	/** Clean up all FDs for a process, closing pipe/PTY ends when last reference drops. */
 	private cleanupProcessFDs(pid: number): void {
 		const table = this.fdTableManager.get(pid);