kern-sandbox 0.1.11 → 0.1.13

package/README.md

@@ -1,7 +1,9 @@
 # kern-sandbox (Node.js / TypeScript)
 
-**[kern](https://github.com/getkern/kern)** is a fast, rootless, daemonless Linux sandbox runtime: a real,
-kernel-enforced box that starts in **~2.3 ms**, from one **~1.8 MB** binary, with no daemon. **kern-sandbox**
+**[kern](https://github.com/getkern/kern)** is a fast, rootless sandbox and virtual resource
+runtime for any workload, including untrusted and AI-generated code: a real, kernel-enforced box
+that starts in **3.4 ms** from an OCI image, out of one **~1.8 MB** binary, with no daemon.
+**kern-sandbox**
 is its Node / TypeScript binding: run untrusted or agent-generated code in a fresh, isolated box, from Node.
 
 On npm: [`npm install kern-sandbox`](https://www.npmjs.com/package/kern-sandbox). For Python, the same
@@ -175,7 +177,7 @@ can still WRITE an artifact to the workspace and `readFile` it if you prefer.
 **Warm kernel (kill the interpreter boot).** Each `runCode` starts a **fresh** interpreter, paying the
 CPython boot (~12 ms) every call. When you run many cells that share state (a REPL, a notebook, an
 agent's tool loop), open a `kernel()`: ONE warm interpreter in a long-lived box, fed cells over a pipe.
-In-memory state persists across cells and the per-cell cost drops from ~16 ms to **sub-millisecond**
+In-memory state persists across cells and the per-cell cost drops from ~14 ms to **sub-millisecond**
 (~300x). Same rich `results` capture as `runCode`.
 
 ```js

package/index.js

@@ -36,12 +36,19 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.11";
+const VERSION = "0.1.13";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
 const DEPS_DIR = ".deps"; // pip --target dir inside the workspace (added to PYTHONPATH for python)
 const ENV_FILE = ".kern-env"; // host-side 0600 env file (kept out of argv so values don't show in `ps`)
+// One file per CALL, `.kern-env.<box-name>`. A single fixed name made concurrent calls on the same
+// Sandbox fight over one path: one call `unlink`ed the file while kern was still starting for
+// another and had not read it yet, and that box died with
+//   error: sandbox: cannot read --env-file '...': No such file or directory
+// Measured at 30 concurrent runCode calls: 2 failed that way, and one file was left behind.
+// The `O_EXCL|O_NOFOLLOW` create is a security property and is unchanged; only the NAME is per-call.
+const ENV_SEP = ".";
 const INLINE_CODE_MAX = 128 * 1024; // above this, pass code via a file instead of argv (ARG_MAX guard)
 // Cap the results file the (untrusted) box writes before the binding reads it into host RAM: a malicious
 // cell could stream a multi-GB `.res` to disk (past its own memory cap) and OOM the host.
@@ -660,7 +667,9 @@ function tarCollect(dir, base, skip, out) {
     if (st.isDirectory()) tarCollect(abs, base, skip, out);
     else if (st.isFile()) {
       const rel = path.relative(base, abs);
-      if (rel === skip) continue; // our private --env-file, not user state
+      // `skip` names OUR env file. Since it is now one per call, match the `<skip>.` prefix too, so a
+      // file left behind by a process that died mid-call cannot end up inside a user's snapshot.
+      if (rel === skip || rel.startsWith(skip + ENV_SEP)) continue;
       tarWriteFile(out, rel.split(path.sep).join("/"), fs.readFileSync(abs));
     }
   }
@@ -835,6 +844,29 @@ class Sandbox {
 
   // -- the box invocation --------------------------------------------------------------------------
 
+  /** Host path of the private --env-file for the box called `name`, inside the workspace. */
+  _envPath(name) {
+    return path.join(this._ws, `${ENV_FILE}${ENV_SEP}${name}`);
+  }
+
+  /**
+   * Is `rel` one of OUR env files rather than user state? Exact-match on the legacy name plus the
+   * `.kern-env.` prefix, never a bare startsWith: a user file called `.kern-environment` is theirs
+   * and must still show up in `files` and in a snapshot.
+   */
+  static _isEnvFile(rel) {
+    return rel === ENV_FILE || rel.startsWith(ENV_FILE + ENV_SEP);
+  }
+
+  /** Remove this call's env file. Every exit path calls it; a missing file is the desired end state. */
+  _removeEnvFile(name) {
+    try {
+      fs.unlinkSync(this._envPath(name));
+    } catch {
+      /* ENOENT is fine: no env was passed, or it is already gone */
+    }
+  }
+
   _baseArgv(name, { network, timeoutS, isSetup = false }) {
     const argv = [
       this._kern, "box", name, "--image", this.image, "--ro",
@@ -867,8 +899,13 @@ class Sandbox {
     if (mergedEnv.PYTHONPATH === undefined) mergedEnv.PYTHONPATH = `${WORKSPACE}/${DEPS_DIR}`;
     // Pass env via a private 0600 --env-file, NOT `--env K=V` on argv (an argv value is visible in
     // `ps` to any local user for the box's lifetime; a credential in env= would leak).
-    if (Object.keys(mergedEnv).length > 0) {
-      const envPath = path.join(this._ws, ENV_FILE);
+    // `_ws` is set by open(); before that it is "". The public API is gated, but the unit tests call
+    // `_baseArgv` directly to inspect the argv, and with an empty workspace `path.join` yielded a
+    // RELATIVE path, so the env file was written into the current directory. Same as the Python side:
+    // it had been landing in the repository, hidden by a `.gitignore` line that stopped matching when
+    // the name became per-call. No workspace means nowhere to put it.
+    if (Object.keys(mergedEnv).length > 0 && this._ws) {
+      const envPath = this._envPath(name);
       const lines = [];
       for (const [k, v] of Object.entries(mergedEnv)) {
         const val = String(v);
@@ -923,6 +960,7 @@ class Sandbox {
           stdio: ["ignore", "pipe", "pipe"],
         });
       } catch (e) {
+        this._removeEnvFile(name);
         return reject(new SandboxError(`could not spawn the box: ${e.message}`));
       }
 
@@ -930,20 +968,20 @@ class Sandbox {
       const err = cappedCollector(child.stderr, this.maxOutputBytes, cbErr);
       let timedOut = false;
       let settled = false;
-
-      const timer = setTimeout(() => {
-        timedOut = true;
-        this._teardown(child, name, childEnv);
-      }, timeoutS * 1000);
-
-      // Hard safety net: a CPU-bound box can survive our signals until kern's backstop reaps it; never
-      // hang the caller. If close hasn't fired a few seconds after our teardown, resolve anyway.
+      // Both timers are armed further down, once `finish` exists. They are declared here, as `let`,
+      // so the closures that clear them can never reference a binding in its temporal dead zone
+      // whatever the callback ordering turns out to be.
+      let timer = null;
       let hardTimer = null;
+
       const finish = (code, signal) => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
+        if (timer) clearTimeout(timer);
         if (hardTimer) clearTimeout(hardTimer);
+        // kern has read the file by the time it exits; leaving it behind would accrete one per call
+        // in a persistent `workspace`.
+        this._removeEnvFile(name);
         const wallMs = Number((process.hrtime.bigint() - started) / 1000000n);
         const stdout = out.buffer().toString("utf8");
         const stderr = err.buffer().toString("utf8");
@@ -959,6 +997,7 @@ class Sandbox {
       };
 
       child.on("error", (e) => {
+        this._removeEnvFile(name);
         if (e && e.code === "ENOENT")
           return reject(new SandboxError(`could not execute kern (${argv[0]}): not found`));
         return reject(new SandboxError(`could not execute kern: ${e.message}`));
@@ -966,20 +1005,22 @@ class Sandbox {
       child.on("close", (code, signal) => {
         finish(code, signal);
       });
-      // arm the hard net only once we've decided to kill (teardown sets timedOut)
+      // Hard safety net: a CPU-bound box can survive our signals until kern's backstop reaps it;
+      // never hang the caller. If close hasn't fired a few seconds after our teardown, resolve anyway.
       const armHardNet = () => {
         if (hardTimer) return;
         hardTimer = setTimeout(() => finish(EXIT_SIGKILL, "SIGKILL"), 10000);
       };
-      // re-check shortly after the deadline in case teardown fired
-      const watch = setInterval(() => {
-        if (settled) {
-          clearInterval(watch);
-        } else if (timedOut) {
-          clearInterval(watch);
-          armHardNet();
-        }
-      }, 250);
+
+      timer = setTimeout(() => {
+        timedOut = true;
+        this._teardown(child, name, childEnv);
+        // Armed HERE, at the one place that decides to kill. It used to be noticed instead by a
+        // 250 ms setInterval that `finish` never cleared, so after every call that interval kept the
+        // event loop alive until its own next tick: measured 224 to 232 ms of dead time between a
+        // call resolving and the process being able to exit, against 19 to 27 ms of real work.
+        armHardNet();
+      }, timeoutS * 1000);
     });
   }
 
@@ -1200,7 +1241,7 @@ class Sandbox {
   snapshot(dest) {
     this._requireEntered();
     this._requireSnapshotOptIn();
-    fs.writeFileSync(dest, tarPack(fs.realpathSync(this._ws), ENV_FILE));
+    fs.writeFileSync(dest, tarPack(fs.realpathSync(this._ws), ENV_FILE));  // prefix-excluded inside tarPack
   }
 
   /** Extract a snapshot (from snapshot()) into the workspace, SAFELY. Every member is vetted first:
@@ -1316,7 +1357,7 @@ class Sandbox {
         }
         if (!st.isFile()) continue; // excludes symlinks and non-regular files
         const rel = path.relative(base, fp);
-        if (rel === ENV_FILE) continue; // our private host-side env file, not a user artifact
+        if (Sandbox._isEnvFile(rel)) continue; // our private host-side env file, not a user artifact
         out[rel] = [Math.round(st.mtimeMs * 1e6), st.size];
       }
     }
@@ -1595,6 +1636,15 @@ class Kernel {
       const kind = looksLikeStartupFailure(err) ? "startup_failed" : "killed";
       return this._teardownResult(kind, err.trim() || "the kernel box exited", started);
     }
+    return this._resultFromReply(reply, started);
+  }
+
+  /** Turn one kernel reply into an `ExecutionResult`.
+   *
+   * Extracted so the UNTRUSTED-INPUT boundary is one named place a test can drive directly: `reply`
+   * is JSON written INSIDE the box, by the same code the sandbox exists to contain. Every field is
+   * attacker-chosen, and the question for each is what a missing or wrong-typed value must mean. */
+  _resultFromReply(reply, started) {
     let obj;
     try {
       obj = JSON.parse(reply);
@@ -1603,15 +1653,25 @@ class Kernel {
     }
     if (!obj || typeof obj !== "object")
       return this._teardownResult("killed", "the kernel sent a non-object reply", started);
+    // `rc` is the ONE field whose absence cannot be defaulted. `success` is
+    // `exitCode === 0 && fault === null`, so coercing a missing or non-integer `rc` to 0 - which is
+    // what this did - reported a SUCCESSFUL run. Since the JSON comes from the box, a cell could
+    // declare its own failed run successful by omitting the field or sending a string. An unusable
+    // status is not a status: it is a protocol violation by the in-box runner, which always emits
+    // `"rc"`, and it is handled like the malformed replies above. `Number.isInteger` also rejects a
+    // boolean, a float and a numeric string, which is what it is here for.
+    if (!Number.isInteger(obj.rc))
+      return this._teardownResult("killed", "the kernel reply carried no usable exit code", started);
+    // The REMAINING fields are informational, so a wrong type degrades to an empty value rather than
+    // failing the call: coerced so a caller doing `r.stdout.trim()` cannot be crashed by a box that
+    // sent a number.
     const results = Array.isArray(obj.results)
       ? obj.results.filter((r) => r && typeof r === "object").map((r) => new Result(r))
       : [];
-    // obj is UNTRUSTED (box-controlled JSON): coerce scalars so a non-string stdout / non-int rc can't
-    // crash a caller doing r.stdout.trim() or arithmetic on r.exitCode.
     return new ExecutionResult({
       stdout: typeof obj.stdout === "string" ? obj.stdout : "",
       stderr: typeof obj.stderr === "string" ? obj.stderr : "",
-      exitCode: Number.isInteger(obj.rc) ? obj.rc : 0,
+      exitCode: obj.rc,
       durationMs: Date.now() - started,
       fault: null,
       files: [],
@@ -1665,7 +1725,24 @@ class Kernel {
       } catch {
         /* ignore */
       }
-      await new Promise((r) => setTimeout(r, 150));
+      // Wait for the exit EVENT, capped at 150 ms, rather than sleeping 150 ms unconditionally: that
+      // fixed sleep cost 152 ms on every close of a persistent kernel (measured) for a box that
+      // exits in a few. A child that is already gone has emitted `exit` and will not emit it again,
+      // so that case is tested directly instead of waited on.
+      if (child.exitCode === null && child.signalCode === null) {
+        await new Promise((resolve) => {
+          let t = null;
+          const onExit = () => {
+            if (t !== null) clearTimeout(t);
+            resolve();
+          };
+          t = setTimeout(() => {
+            child.removeListener("exit", onExit);
+            resolve();
+          }, 150);
+          child.once("exit", onExit);
+        });
+      }
       this._kill();
     } else {
       this._kill();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.11",
-  "description": "kern is a fast, rootless, daemonless Linux sandbox runtime; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box, ~2 ms, no cloud, no account, no VM.",
+  "version": "0.1.13",
+  "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and AI-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box in single-digit milliseconds, with no cloud, no account and no VM.",
   "keywords": [
     "sandbox",
     "kern",