kern-sandbox 0.2.20 → 0.2.23

package/README.md

@@ -78,14 +78,20 @@ spawns a **fresh** box on that shared workspace, so file state persists but in-m
 (write to disk for continuity). `withSandbox` opens the session and cleans it up, even on throw:
 
 ```js
-await kern.withSandbox({ setup: "pip install pandas" }, async (sbx) => {
-  await sbx.writeFile("data.csv", csvBytes);
-  const r = await sbx.runCode(
-    "import pandas as pd; print(pd.read_csv('data.csv').describe())",
-  );
-  console.log(r.stdout);          // network off, capped, isolated
-  const chart = await sbx.readFile("out.png");
-});
+await kern.withSandbox(
+  { setup: "pip install pandas matplotlib", memoryMb: 1536 },
+  async (sbx) => {
+    await sbx.writeFile("data.csv", "a,b\n1,2\n3,4\n");
+    const r = await sbx.runCode(
+      "import matplotlib; matplotlib.use('Agg')\n" +
+        "import pandas as pd, matplotlib.pyplot as plt\n" +
+        "df = pd.read_csv('data.csv'); print(df.describe())\n" +
+        "df.plot(); plt.savefig('out.png')",
+    );
+    console.log(r.stdout);        // network off, capped, isolated
+    const chart = await sbx.readFile("out.png");   // a Uint8Array of the PNG
+  },
+);
 ```
 
 `setup` is the **only** moment the network is on (a separate box that installs deps into the workspace
@@ -164,8 +170,8 @@ Every relaxing option says so in its name or docs:
 - **mounts refused**: the host's own sources (`/`, `/etc`, `/root`, `/boot`, `/proc`, `/sys`, `/dev`,
   `$HOME`, the docker socket), any path with a **credential directory** in it (`.ssh`, `.aws`, `.gnupg`,
   `.kube`, `.docker`, `.azure`, `.password-store`, `.netrc`, `.git-credentials`, `.pypirc`, `.npmrc`),
-  **kern's own state** (`$XDG_RUNTIME_DIR/kern`, the image cache, the config dir: the sandbox's control
-  plane), and escaping targets.
+  **kern's own state** (`$XDG_RUNTIME_DIR/kern`, the image cache, the config dir, the data dir that
+  holds every named volume: the sandbox's control plane), and escaping targets.
 - **workspace I/O contained**: `writeFile`/`readFile` reject `..` escapes, open the final component
   `O_NOFOLLOW` so a symlink the box plants cannot redirect host I/O, and refuse anything that is not a
   REGULAR file (see the notes for the FIFO that made a read hang).
@@ -214,6 +220,13 @@ memory, scratch that does not survive a call, and the two writable places a tool
 `network: false` gives the run phase no network and `network: true` gives it the host's. `egressAllow`
 is the middle one, and usually the one an agent wants:
 
+**`network: true` includes the host's LOOPBACK, which is where unauthenticated services live.** It
+puts the box in the host's network namespace, so `127.0.0.1` inside the box is the host's
+`127.0.0.1`: a reviewer's cell connected to `127.0.0.1:22` and read back `SSH-2.0-OpenSSH_9.6p1`,
+and a developer's laptop is where a database, a Redis and a dashboard sit bound to localhost with no
+password. The same connect is refused under the default `network: false`, and `egressAllow` refuses
+it too, because that one goes through kern's proxy rather than through the host's stack.
+
 ```js
 await withSandbox({ egressAllow: ["pypi.org", "files.pythonhosted.org"] }, async (sbx) => { /* ... */ });
 ```

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.2.20";
+const VERSION = "0.2.23";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -456,16 +456,35 @@ const REFUSED_MOUNT_SOURCES = new Set([
  * follow the environment and a service manager moves them. */
 function kernStateDirs() {
   const uid = process.getuid();
-  const runtime = process.env.XDG_RUNTIME_DIR || `/run/user/${uid}`;
   const home = os.homedir();
-  const cache = process.env.XDG_CACHE_HOME || path.join(home, ".cache");
-  const config = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
-  return [
-    [path.join(runtime, "kern"), "kern's runtime state (the registry, instance dirs, netns handles and exit files of every box you are running)"],
-    [`/run/user/${uid}/kern`, "kern's runtime state"],
-    [path.join(cache, "kern"), "kern's image cache (a box that writes it poisons the rootfs a later box runs)"],
-    [path.join(config, "kern"), "kern's configuration (the profiles a later box may be given)"],
+  // EACH DIRECTORY TWICE: where the environment says it is, AND where XDG says it is by default. The
+  // runtime dir was already spelled both ways; the other three were not, and a reviewer measured the
+  // consequence in one process - with `XDG_DATA_HOME=/tmp/xdh2`, `~/.local/share/kern` was ACCEPTED
+  // and still held `builds` and `volumes`. The variable answers "which kern will this SDK spawn",
+  // which is the right input for the guard, but data a previous run left on disk does not move with it.
+  //
+  // The DATA dir itself joined the list after the same reviewer took the refused two as the shape of
+  // the rule and looked for the rest: it holds `volumes/`, the CONTENT of every named volume on this
+  // host, and `builds/`, the records a later image is assembled from.
+  const known = [
+    [process.env.XDG_RUNTIME_DIR, `/run/user/${uid}`,
+      "kern's runtime state (the registry, instance dirs, netns handles and exit files of every box you are running)"],
+    [process.env.XDG_CACHE_HOME, path.join(home, ".cache"),
+      "kern's image cache (a box that writes it poisons the rootfs a later box runs)"],
+    [process.env.XDG_CONFIG_HOME, path.join(home, ".config"),
+      "kern's configuration (the profiles a later box may be given)"],
+    [process.env.XDG_DATA_HOME, path.join(home, ".local", "share"),
+      "kern's data (every named volume on this host, and the build records a later image is assembled from)"],
   ];
+  // A MAP, so the usual case where the variable IS the default collapses to one entry instead of
+  // listing the same directory twice with two different accounts of what it is.
+  const out = new Map();
+  for (const [configured, dflt, what] of known)
+    for (const base of [configured || dflt, dflt]) {
+      const dir = path.join(base, "kern");
+      if (!out.has(dir)) out.set(dir, what);
+    }
+  return [...out];
 }
 
 /** Credential directories, refused as a COMPONENT anywhere in the source. The set above is absolute

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.20",
+  "version": "0.2.23",
   "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and LLM-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",