seisin 0.4.2 → 0.5.0

package/src/spool.js

@@ -3,7 +3,7 @@
  *
  * ── Why this exists ──
  * `.seisin/` used to be in every role's allowWrite, because the hook runs
- * inside the box and has to record what it decided. That made the log and the
+ * inside the sandbox and has to record what it decided. That made the log and the
  * request queue writable by the process they are a record of: an agent could
  * truncate `log.jsonl`, rewrite a decision, or invent a request that had never
  * been refused. The files said "append-only" in their own comments and nothing
@@ -27,34 +27,14 @@
  * else did.
  */
 import { createServer, createConnection, Socket } from "node:net";
-import { unlinkSync, existsSync, mkdtempSync, chmodSync, openSync, writeSync, closeSync, constants } from "node:fs";
+import { unlinkSync, existsSync, openSync, writeSync, closeSync, constants } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
 
 /** The env var a confined hook looks for. Absent means "write the file". */
 export const SOCK_ENV = "SEISIN_SPOOL";
 
 /**
- * Where the socket lives.
- *
- * Not under the repo: the point is a path the role's territory does not cover.
- * Kept short because a unix socket path is capped near 104 bytes on macOS and
- * the failure when it is too long is an unhelpful EINVAL.
- */
-export function spoolPath() {
-  // A random directory, 0700, rather than a name anyone can guess from the pid.
-  // The socket itself is already denyWrite so the agent cannot unlink it, but
-  // any other process running as this user could otherwise connect and add
-  // lines. That does not let them erase anything — forgery is the part that
-  // stays open — but a predictable path invites it for free.
-  const dir = mkdtempSync(join(tmpdir(), "seisin-"));
-  chmodSync(dir, 0o700);
-  return join(dir, "spool.sock");
-}
-
-/**
- * Listens for lines from inside the box and hands each to `sink`.
+ * Listens for lines from inside the sandbox and hands each to `sink`.
  *
  * One line is one JSON object with a `to` field naming which file it belongs
  * in. The parent decides what that means; the sender does not get to pick a
@@ -63,7 +43,7 @@ export function spoolPath() {
 /**
  * Which channel this platform can use: a unix socket, or a FIFO.
  *
- * On Linux the runtime blocks creating ANY unix socket inside the box with a
+ * On Linux the runtime blocks creating ANY unix socket inside the sandbox with a
  * seccomp filter — it cannot filter by path, so `allowUnixSockets` is ignored
  * there (its README says so). The socket this file was built on therefore
  * never carried a line on Linux: measured in Docker on 2026-09-23, with the
@@ -96,7 +76,7 @@ function lineReader(sink, onTooLong) {
         const msg = JSON.parse(line);
         if (msg && (msg.to === "log" || msg.to === "requests")) sink(msg.to, msg.entry);
       } catch {
-        // Garbage from inside the box is not the parent's emergency.
+        // Garbage from inside the sandbox is not the parent's emergency.
       }
     }
   };
@@ -125,7 +105,7 @@ function fifoSpool(sink, path) {
   });
 }
 
-export function spool(sink, path = spoolPath()) {
+export function spool(sink, path) {
   if (path.endsWith(FIFO_SUFFIX)) return fifoSpool(sink, path);
   if (existsSync(path)) unlinkSync(path);
 
@@ -143,7 +123,7 @@ export function spool(sink, path = spoolPath()) {
    * too long for a unix socket, a directory that is not there — left an awaited
    * promise pending forever. What the user saw was Node's "Detected unsettled
    * top-level await" and rc=13: no error, no path, nothing naming the spool.
-   * Measured while running seisin inside seisin, where the outer box refuses
+   * Measured while running seisin inside seisin, where the outer sandbox denies
    * the inner bind; but nothing about it is particular to that case, which is
    * the reason it is fixed here rather than beside the nesting check.
    *
@@ -161,11 +141,11 @@ export function spool(sink, path = spoolPath()) {
       close() {
         server.close();
         // Only the socket. The first version removed `dirname(path)` too,
-        // reasoning that spoolPath() had just made that directory — but a
+        // reasoning that the spool had just made that directory — but a
         // caller passing its own path makes dirname the system temp directory,
         // and closing the spool deleted it. That is a caller's whole scratch
         // space gone, for a cleanup. Whoever created the directory removes it:
-        // see `run`, which owns the one spoolPath() makes.
+        // see `run`, whose run directory (rundir.js) holds the socket.
         try { unlinkSync(path); } catch {}
       },
       });

package/src/srt.js

@@ -13,6 +13,8 @@
  *      back to its defaults. Emitting the whole object removes that class of
  *      error, which is most of what this file is for.
  */
+import { unknownRole } from "./suggest.js";
+import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { STATE_DIR, CONFIG_NAME } from "./layout.js";
 import { entriesOf } from "./keys.js";
@@ -79,7 +81,7 @@ export const NO_PROXY_WITHOUT_LOOPBACK = "169.254.0.0/16,10.0.0.0/8,172.16.0.0/1
  *
  * An `env` in front and not a variable in the environment seisin passes: the
  * runtime sets NO_PROXY itself, after seisin's environment, so the only place
- * that wins is inside the box. Clients that ignore HTTP_PROXY — a MySQL driver,
+ * that wins is inside the sandbox. Clients that ignore HTTP_PROXY — a MySQL driver,
  * Chromium, which exempts loopback on its own — still get refused. They need
  * to be pointed at the proxy, or the port needs `local_binding`, which opens
  * every port.
@@ -91,12 +93,12 @@ export function loopbackVia(role, cmd) {
 
 export function settingsFor(config, roleName, spool = null, observe = false) {
   const role = config.roles[roleName];
-  if (!role) throw new Error(`unknown role "${roleName}". Known: ${Object.keys(config.roles).join(", ")}`);
+  if (!role) throw unknownRole(config, roleName);
 
   const abs = (p) => (p.startsWith("/") ? p : join(config.root, p));
   // "credentials" closes the places credentials live; "home" does that and
   // gives the role a home of its own. Only the second one needs a new HOME,
-  // and only the second one signs every CLI in the box out. See config.js.
+  // and only the second one signs every CLI in the sandbox out. See config.js.
   //
   // `true` is normalised here as well as in the config reader, because a caller
   // embedding the library builds this object itself and `isolate: true` has
@@ -104,6 +106,30 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
   const level = config.isolate === true ? "home" : config.isolate;
   const shielded = level === "credentials" || level === "home";
   const isolated = level === "home";
+  /**
+   * `sandbox-runtime` silently makes these writable as conveniences even when
+   * they are absent from `allowWrite`. That gives every role a shared host
+   * directory outside its territory. A denyRead makes the runtime drop its
+   * implicit grant; denyWrite also wins over Seisin's explicit `~/.claude`
+   * runtime scratch grant for the nested debug directory.
+   *
+   * On macOS both are named whether they exist or not: the profile is a set of
+   * patterns, and a missing directory costs nothing. On Linux only the ones
+   * that exist are. bubblewrap denies a missing path by placing something on
+   * the host for the length of the run, in the user's home, where other tools
+   * see it — and a run that is killed leaves it behind. So a missing one is
+   * either not needed or made first:
+   * - its parent is not one a role may write (`~/.npm`): nothing can create
+   *   it inside the sandbox, and there is nothing to deny;
+   * - its parent is (`~/.claude`, the runtime scratch every role gets): a role
+   *   could create it, so it is created here, outside the sandbox, and denied like
+   *   any directory that exists. It is the directory Claude Code itself logs
+   *   to; making it empty changes nothing for anyone.
+   */
+  const scratch = writePathsOf(config, config.roles[roleName] ?? { name: roleName, writes: [] });
+  const runtimeConvenience = ["~/.npm/_logs", "~/.claude/debug"]
+    .map(expand)
+    .filter((p) => process.platform !== "linux" || existsSync(p) || madeFirst(p, scratch));
 
   /**
    * Refuse before the runtime does, because the runtime's refusal says nothing.
@@ -127,6 +153,7 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
   const home = isolated ? roleHome(config, roleName) : null;
   const denyRead = [];
   const allowRead = [];
+  denyRead.push(...runtimeConvenience);
 
   // Every declared directory is denied, then each key the role names is
   // re-allowed. A key written without a directory resolves against the first
@@ -301,6 +328,7 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
        * relying on someone else's implementation detail staying put.
        */
       denyWrite: [
+        ...runtimeConvenience,
         /**
          * The role's own subtractions, `never_writes`.
          *
@@ -318,7 +346,7 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
           .flatMap((p) => { const r = realAncestor(p); return r === p ? [p] : [p, r]; }),
         /**
          * Everything the parent reads or executes, and every file that tells a
-         * program outside the box what to run — the policy, `.seisin/`, the key
+         * program outside the sandbox what to run — the policy, `.seisin/`, the key
          * directories, the key providers, `file://` targets, programs on PATH
          * installed where a role writes, and each project's hooks and settings.
          * One list with a reason per entry, built in surface.js, which says why
@@ -343,27 +371,16 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
      * verify through the Security framework — Go before 1.27 (gh, kubectl,
      * terraform) and every Dart/Flutter. The runtime ships it as
      * `enableWeakerNetworkIsolation` and warns it is an exfiltration path:
-     * trustd fetches, outside the box, the URLs a certificate carries. Per role
+     * trustd fetches, outside the sandbox, the URLs a certificate carries. Per role
      * and off by default, so the answer is written next to the role that needs it.
      */
     ...(role.trustd === true ? { enableWeakerNetworkIsolation: true } : {}),
   };
 }
 
-/**
- * The provider executables that live at a path, absolute.
- *
- * A command with no separator (`security`, `op`, `gpg`) is resolved by the OS
- * from PATH and is deliberately left alone: denying "wherever gpg happens to
- * be" would mean writing a rule about a machine rather than about a repo.
- */
-export function providerPaths(config) {
-  const out = [];
-  for (const p of Object.values(config.keyProviders ?? {})) {
-    const cmd = p.command?.[0];
-    if (!cmd || !cmd.includes("/")) continue;
-    out.push(cmd.startsWith("/") ? cmd : join(config.root ?? ".", cmd));
-  }
-  return [...new Set(out)];
+/** Creates `p` when its parent exists and a role may write there; says whether it now exists. */
+function madeFirst(p, writable) {
+  const parent = dirname(p);
+  if (!existsSync(parent) || !writable.some((w) => parent === w || parent.startsWith(w + "/"))) return false;
+  try { mkdirSync(p, { recursive: true }); return true; } catch { return false; }
 }
-

package/src/suggest.js

@@ -0,0 +1,58 @@
+/**
+ * "Did you mean" — for a command, a role, a flag.
+ *
+ * One place, so every command answers a typo the same way: the name that was
+ * not found, what exists, and the nearest one when it is near enough to be a
+ * typo rather than a different word.
+ */
+
+/** Edit distance, small strings only. */
+function distance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++)
+    for (let j = 1; j <= b.length; j++)
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+}
+
+/** The nearest of `known` to `word`, or null when nothing is close. */
+export function nearest(word, known) {
+  let best = null, score = Infinity;
+  for (const k of known) {
+    const n = distance(String(word).toLowerCase(), k.toLowerCase());
+    if (n < score) { best = k; score = n; }
+  }
+  const room = Math.max(1, Math.floor(String(word).length / 3));
+  return score <= room || (best && best.startsWith(word) && word.length >= 2) ? best : null;
+}
+
+/** The error for a role the policy does not have, always with the list. */
+export function unknownRole(config, role) {
+  const known = Object.keys(config.roles ?? {});
+  const near = nearest(role, known);
+  return new Error(
+    `unknown role "${role}"${near ? ` — did you mean "${near}"?` : ""}` +
+    `\n  known roles: ${known.join(", ") || "none — add a [roles.<name>] section"}`);
+}
+
+/**
+ * Flags a command does not take are refused, never ignored. An ignored
+ * `--verbsoe` is a question answered as if it had not been asked.
+ * `values` are the flags that take the next word as their value.
+ */
+export function checkFlags(command, argv, known, values = []) {
+  const all = [...known, ...values];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") break;
+    if (values.includes(a)) { i++; continue; }
+    if (!a.startsWith("-") || a === "-") continue;
+    if (all.includes(a)) continue;
+    const near = nearest(a, all);
+    const e = new Error(`unknown flag "${a}" for ${command}${near ? ` — did you mean "${near}"?` : ""}` +
+      `\n  seisin ${command} --help lists its flags`);
+    e.usage = true;
+    throw e;
+  }
+}