seisin 0.4.2 → 0.6.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,15 @@
  * 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";
+import { lineReader as readLines } from "./lines.js";
 
 /** 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 +44,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
@@ -82,24 +63,14 @@ const PIPE_BUF = 4096;
 
 /** Parses newline-separated JSON messages and hands each to `sink`. */
 function lineReader(sink, onTooLong) {
-  let buffer = "";
-  return (chunk) => {
-    buffer += chunk;
-    // A 1 MB line is not a log entry, it is something trying to fill a disk.
-    if (buffer.length > 1_000_000) { buffer = ""; return onTooLong?.(); }
-    let nl;
-    while ((nl = buffer.indexOf("\n")) !== -1) {
-      const line = buffer.slice(0, nl);
-      buffer = buffer.slice(nl + 1);
-      if (!line.trim()) continue;
-      try {
-        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.
-      }
+  return readLines((line) => {
+    try {
+      const msg = JSON.parse(line);
+      if (msg && (msg.to === "log" || msg.to === "requests")) sink(msg.to, msg.entry);
+    } catch {
+      // Garbage from inside the sandbox is not the parent's emergency.
     }
-  };
+  }, { onTooLong });
 }
 
 /**
@@ -125,7 +96,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 +114,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 +132,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,23 +13,31 @@
  *      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 { privateDir } from "./config.js";
+import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { homedir } from "node:os";
 import { STATE_DIR, CONFIG_NAME } from "./layout.js";
-import { entriesOf } from "./keys.js";
+import { entriesOf, injectKeysOf } from "./keys.js";
 import { enforcedNeverWrites } from "./owners.js";
 import { realAncestor } from "./paths.js";
 import { denyFor } from "./surface.js";
-import { runsRootOf } from "./rundir.js";
+import { runsRootOf, SETTINGS_NAME, TMP_NAME } from "./rundir.js";
 import { FIFO_SUFFIX } from "./spool.js";
+import { machOf } from "./browsers.js";
+import { territoryReads, outlastAllows, dataRoots, keptFor } from "./territory.js";
+import { seccompDir } from "./sandboxes/srt.js";
 import {
   SOCKET_MAX, isLink, realOrSelf, expand, homeFits, roleHome, roleHomeRoot,
-  CREDENTIAL_HOMES, toWritePath, writePathsOf,
+  CREDENTIAL_HOMES, toWritePath, writePathsOf, otherAgentsCredentials,
 } from "./grants.js";
 
 // Re-exported: these were srt.js's exports before grants.js existed, and
 // callers (the CLI, the tests, anyone embedding seisin) import them from here.
 export {
   expand, homeFits, roleHome, roleHomeRoot, CREDENTIAL_HOMES, RUNTIME_WRITES,
+  AGENTS, AGENT_HOMES, AGENT_CREDENTIALS, agentOf,
 } from "./grants.js";
 
 
@@ -75,28 +83,49 @@ export const NO_PROXY_WITHOUT_LOOPBACK = "169.254.0.0/16,10.0.0.0/8,172.16.0.0/1
 
 /**
  * The command a role runs, with loopback routed through the proxy when it
- * has `local_ports`.
+ * has `local_ports` and the sandbox is sandbox-runtime.
  *
  * 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.
  */
-export function loopbackVia(role, cmd) {
-  if (!role?.localPorts?.length) return cmd;
+export function loopbackVia(role, cmd, sandbox = "srt") {
+  // tartaros holds the port list in the kernel's profile itself: a listed port
+  // is reached directly, any other refused, and its own NO_PROXY already exempts
+  // loopback. Its egress broker, made to carry loopback as a forward proxy, cut
+  // POST bodies (measured on 0.1.0-alpha.7: curl got no answer, and Claude Code
+  // retried until ECONNRESET), so under it the route is left as it sets it.
+  if (!role?.localPorts?.length || sandbox === "tartaros") return cmd;
   return ["env", `NO_PROXY=${NO_PROXY_WITHOUT_LOOPBACK}`, `no_proxy=${NO_PROXY_WITHOUT_LOOPBACK}`, ...cmd];
 }
 
-export function settingsFor(config, roleName, spool = null, observe = false) {
+/** The temp directory sandbox-runtime grants every sandbox it starts. See settingsFor. */
+export const SHARED_TMP = { darwin: ["/tmp/claude", "/private/tmp/claude"], linux: ["/tmp/claude"] };
+
+/**
+ * `agent` is what the run's command runs — `agentOf(cmd)`, or `--agent`. It
+ * decides which agent's home is scratch for this run and whose sign-in files
+ * are closed to it. Left out (check, console, explain: no command), the
+ * settings are the most the role can get, which is every agent's home.
+ */
+export function settingsFor(config, roleName, spool = null, observe = false, { agent, program, tmp, forRun = 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 claudeGrant = role.writes.find((g) => /^(?:\.\/)?\.claude(?:\/|$)/.test(g));
+  if (claudeGrant)
+    throw new Error(
+      `roles.${roleName}.writes includes "${claudeGrant}", but a project's .claude cannot be granted.\n` +
+      "  Claude Code reads its settings and hooks outside the sandbox. Remove this territory; " +
+      "a broad territory such as ** keeps working with .claude protected.",
+    );
 
   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 +133,45 @@ 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: [] }, { agent });
+  const runtimeConvenience = ["~/.npm/_logs", "~/.claude/debug"]
+    .map(expand)
+    .filter((p) => process.platform !== "linux" || existsSync(p) || madeFirst(p, scratch));
+  /**
+   * The runtime's own temp directory, shared by every sandbox on the machine.
+   *
+   * sandbox-runtime grants `/tmp/claude` to every sandbox it starts, outside
+   * any allowWrite and "never left out", and hands it to the child as TMPDIR.
+   * Every Claude Code session on the machine keeps its own temp files there
+   * too, so a confined role could write beside them — caches, locks — with
+   * nothing in the policy saying so (measured: `echo x > /tmp/claude/…` from
+   * a role with `read = "territory"` and no scratch, rc=0). Only a denyWrite
+   * takes it back. The run gets a temp directory of its own instead
+   * (`tmp`, passed in, through CLAUDE_CODE_TMPDIR in commands/run.js), so
+   * nothing the runtime does needs the shared one.
+   */
+  const sharedTmp = SHARED_TMP[process.platform === "linux" ? "linux" : "darwin"]
+    .filter((p) => process.platform !== "linux" || existsSync(p) || madeFirst(p, scratch));
 
   /**
    * Refuse before the runtime does, because the runtime's refusal says nothing.
@@ -127,6 +195,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
@@ -168,9 +237,29 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
    * touches, gets one wrong, and fails as an unexplainable crash inside the
    * agent. Naming the places credentials actually live is narrower than the
    * ideal and it is a boundary that holds up in practice.
+   *
+   * For agents you would not trust there is `[runtime] read = "territory"`,
+   * below: not that allowlist, but its useful half — the places data lives are
+   * denied, the system stays readable, and what a toolchain needs from a home
+   * is declared and checked before the run. decisions.md has both halves.
    */
   if (shielded) denyRead.push(...CREDENTIAL_HOMES.map(expand));
 
+  /**
+   * The other agents' sign-in, closed to this run both ways. See AGENT_HOMES
+   * in grants.js. Under `isolate = "home"` the agent signs in inside the role's
+   * own home, so that is where the files are looked for too.
+   *
+   * On Linux only the ones that exist: bubblewrap would otherwise put a file
+   * where the agent will later want to write its own. The directory around a
+   * missing one is not this run's to write (it is another agent's home), so
+   * nothing in the run can create it either — except under `isolate = "home"`,
+   * where the whole role home is writable and a missing one stays creatable.
+   */
+  const notMine = otherAgentsCredentials(agent, isolated ? roleHome(config, roleName) : homedir())
+    .filter((p) => process.platform !== "linux" || existsSync(p));
+  denyRead.push(...notMine);
+
   /**
    * `~/.claude` and `~/.codex` are closed only at the `home` level, and the
    * difference is the whole reason the two levels exist.
@@ -199,7 +288,7 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
    *
    * A reference has no path, so there is nothing here to allow: it is resolved
    * by the parent before the sandbox starts and handed over as an environment
-   * variable or as a scratch file. See keys.js. Filtering here rather than
+   * variable or as a file in the run directory. See keys.js. Filtering here rather than
    * upstream keeps the two kinds from having to know about each other — the
    * settings this function emits are still, entirely, about the filesystem.
    */
@@ -235,9 +324,9 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
   /**
    * Other runs' directories are unreadable; this run's is readable.
    *
-   * Every run keeps its socket and `scratch` keys under one root (rundir.js),
+   * Every run keeps its socket and `run-file` keys under one root (rundir.js),
    * and every role runs as the same user, so the directory mode protects
-   * nothing between roles. Measured: one role read another's scratch key while
+   * nothing between roles. Measured: one role read another's run-file key while
    * both ran. Same shape as the key directories: deny the parent, allow your own.
    */
   const runs = runsRootOf(spool);
@@ -245,46 +334,137 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
   if (runs) {
     denyRead.push(runs);
     allowRead.push(dirname(spool));
+    /**
+     * And the temp directories runs are given when their role may write no
+     * other (rundir.js, TMP_NAME): denied as a whole, this run's own allowed
+     * back. Same shape again, and for the same reason — every run is the same
+     * user, so a run could otherwise read what another left in its temp.
+     */
+    const tmps = join(dirname(runs), TMP_NAME);
+    denyRead.push(tmps);
+    if (tmp && (tmp === tmps || tmp.startsWith(tmps + "/"))) allowRead.push(tmp);
+    /**
+     * This run's settings are not this run's to read.
+     *
+     * They sit in the run's own directory, which the run reads for its run-file
+     * keys, so they were readable from inside: a map of every path left open
+     * and every one shut, handed to the process it confines. Not a defence on
+     * its own — the policy has to be right either way — but there is no reason
+     * to give an agent the list of doors to try. Named here, by the path
+     * rundir.js writes them to, because they do not exist yet.
+     */
+    denyRead.push(join(dirname(spool), SETTINGS_NAME));
   }
 
+  /**
+   * `[runtime] read = "territory"`: the data roots are denied whole and what
+   * this role needs is allowed back inside them. See territory.js for why
+   * allowed back and no longer carved.
+   *
+   * Allowed back: the repo (key directories inside it stay denied by name,
+   * above), what the role writes, and what it declares in `reads` and
+   * `toolchain` — except where a deny above already covers it. A `reads`
+   * entry under `~/.ssh` stays shut, as it did when the mode only denied.
+   *
+   * Not allowed back twice: what is already re-allowed above — this run's
+   * directory, the role's own home, the key files.
+   */
+  /**
+   * Other roles' private folders: denied to read and to write, whatever this
+   * role's territory says and in either read mode.
+   *
+   * Deny-only, and never an allow for the owner: the owner reaches its folder
+   * the way it reaches the rest of its territory, and nobody else gets an
+   * allow anywhere near it. That is the shape that holds on both platforms —
+   * an allow around a deny is re-emitted after it on macOS, and a read allow
+   * is mounted over the writable mounts on Linux (territory.js).
+   *
+   * On Linux the folder is made first when it is missing: bubblewrap denies a
+   * missing path by putting something on the host in its place, and the owner
+   * would find a file where its folder should be. It is the owner's territory,
+   * so an empty folder there is what the policy already says. Only for a run
+   * (`forRun`, passed by `seisin run`): check, explain and the console ask for
+   * these settings too, and they write nothing to disk. For them a missing
+   * folder on Linux is left out — there is no run for it to be denied in.
+   */
+  const shut = othersPrivate(config, roleName, abs, { make: forRun });
+  denyRead.push(...shut);
+
+  const allowWrite = [
+    // Observing means the kernel stops refusing, because otherwise there is
+    // nothing to observe. `--observe` used to relax only the hook, so the
+    // sandbox denied the write anyway and the banner said "nothing denied"
+    // over a transcript of denials — and `init --from-observations` builds
+    // a policy out of that transcript. It would read "the agent needs
+    // nothing outside its territory", which is the opposite of the truth.
+    //
+    // The repo, and only the repo. Everything in denyWrite below still
+    // holds: the config, the state directory and the key directories stay
+    // shut even here, because observing is not a reason to hand over the
+    // paperwork of the confinement.
+    // One function answers "what may this role write" for the settings and
+    // for surface.js, which needs the union over every role. Two copies of
+    // that arithmetic would be two answers the day one of them changes.
+    ...writePathsOf(config, role, { observe, agent }),
+    ...(isFifo ? [spool] : []),
+    ...(tmp ? [tmp] : []),
+  ];
+
+  if (config.read === "territory") {
+    const reopened = allowRead.map(realOrSelf);
+    const inReopened = (p) => { const r = realAncestor(p); return reopened.some((a) => r === a || r.startsWith(a + "/")); };
+    // On Linux the runtime's apply-seccomp runs inside: see seccompDir.
+    const seccomp = process.platform === "linux" ? seccompDir() : null;
+    const keep = [...keptFor(config, role, { observe, agent, program }), ...(seccomp ? [seccomp] : [])]
+      .filter((p) => !inReopened(p));
+    const { deny, allow } = territoryReads(dataRoots(), keep, { writes: allowWrite, denied: [...denyRead] });
+    denyRead.push(...deny);
+    allowRead.push(...allow);
+  }
+  // The key directory inside a repo that is now an allow: see outlastAllows.
+  const spelt = config.read === "territory" && process.platform === "darwin"
+    ? outlastAllows(denyRead, allowRead, realAncestor) : denyRead;
+
+  const allowedDomains = role.localPorts?.length
+    ? [...(role.network ?? config.allowedDomains ?? []), ...localPortDomains(role.localPorts)]
+    : role.network ?? config.allowedDomains;
+  const { credentials, tlsTerminate } = injectSettings(config, role, allowedDomains);
+
   return {
     network: {
       // `local_ports` rides the same allowlist as the domains: the runtime's
       // proxy is the one place that sees the destination PORT. See loopbackVia.
       // Without ports the value is passed through untouched, `undefined` included: that
       // is how a config with no network list has always read, and a spread would throw.
-      allowedDomains: role.localPorts?.length
-        ? [...(role.network ?? config.allowedDomains ?? []), ...localPortDomains(role.localPorts)]
-        : role.network ?? config.allowedDomains,
+      allowedDomains,
       deniedDomains: [],
+      // `[network] deny_addresses`: what an allowed name may not resolve to, on
+      // top of the runtime's own loopback / link-local / metadata set. Left out
+      // when empty, so a policy without it emits the settings it always did.
+      ...(config.deniedAddresses?.length ? { deniedResolvedAddresses: config.deniedAddresses } : {}),
+      /**
+       * `inject` keys terminate TLS, because substituting a header needs reading
+       * it. Only the hosts that carry a masked credential are terminated; every
+       * other allowed domain is excluded, so the MITM is as narrow as the policy
+       * lets it be. A wildcard allow that covers an inject host is terminated
+       * whole — srt cannot terminate one host out of `*.x` — and `check` says so.
+       */
+      ...(tlsTerminate ? { tlsTerminate } : {}),
       // Exactly one socket: the parent's audit spool, when there is a parent.
       // Granted by path, not by turning unix sockets on.
       allowUnixSockets: spool && !isFifo ? [spool] : [],
       // Per role, `local_binding = true`. Off by default: listening is a
       // capability, and most roles never need it.
       allowLocalBinding: role.localBinding === true,
+      // `browsers = ["chromium"]`: the Mach services the browser's own
+      // processes look up to find each other, by prefix (browsers.js). The
+      // register half has no field here; srt-mach.mjs adds it.
+      ...(machOf(role).lookup.length ? { allowMachLookup: machOf(role).lookup.map((p) => `${p}*`) } : {}),
     },
     filesystem: {
-      denyRead,
+      denyRead: spelt,
       allowRead,
-      allowWrite: [
-        // Observing means the kernel stops refusing, because otherwise there is
-        // nothing to observe. `--observe` used to relax only the hook, so the
-        // sandbox denied the write anyway and the banner said "nothing denied"
-        // over a transcript of denials — and `init --from-observations` builds
-        // a policy out of that transcript. It would read "the agent needs
-        // nothing outside its territory", which is the opposite of the truth.
-        //
-        // The repo, and only the repo. Everything in denyWrite below still
-        // holds: the config, the state directory and the key directories stay
-        // shut even here, because observing is not a reason to hand over the
-        // paperwork of the confinement.
-        // One function answers "what may this role write" for the settings and
-        // for surface.js, which needs the union over every role. Two copies of
-        // that arithmetic would be two answers the day one of them changes.
-        ...writePathsOf(config, role, { observe }),
-        ...(isFifo ? [spool] : []),
-      ],
+      allowWrite,
       /**
        * The confinement's own paperwork, never writable — not even by a role
        * that was granted the whole repo.
@@ -301,6 +481,9 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
        * relying on someone else's implementation detail staying put.
        */
       denyWrite: [
+        ...runtimeConvenience,
+        ...sharedTmp,
+        ...notMine,
         /**
          * The role's own subtractions, `never_writes`.
          *
@@ -318,13 +501,14 @@ 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
          * each member of the family is on it. `seisin check` prints it.
          */
         ...denyFor(config, role, { observe }).map((e) => e.path),
+        ...shut,
         // The audit socket, and the directory holding it. Denying only the
         // socket left `mv /tmp/seisin-xxxx /tmp/gone` as a way to take the
         // channel out without ever touching the file that was protected.
@@ -343,27 +527,90 @@ 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 } : {}),
+    /**
+     * Masked credentials: the real value reaches the runtime's own environment
+     * (run.js), never the sandbox, which sees `fake_value_…`. `mode: "mask"`
+     * and the per-credential `injectHosts` are all that is emitted — no
+     * `extract`, `decode`, files or SigV4, and never `allowPlaintextInject`,
+     * which over HTTPS carries the sentinel and so is deny with extra steps.
+     */
+    ...(credentials ? { credentials } : {}),
   };
 }
 
 /**
- * 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.
+ * A domain pattern covers a host — srt's rule, narrowed to what seisin needs.
+ * `*` covers all; `*.base` covers any `x.base`; otherwise an exact, case-folded
+ * match. Mirrors `matchesDomainPattern` in the runtime's domain-pattern.js;
+ * written here rather than imported because seisin generates settings and does
+ * not embed the library, and exported so `inspect/inject.js` shares the one
+ * rule. Inject hosts are exact (config.js rejects a wildcard), so
+ * this is only ever asked "does this allowedDomains pattern cover this host".
+ */
+export function coversHost(pattern, host) {
+  const p = String(pattern).toLowerCase(), h = host.toLowerCase();
+  if (p === "*") return true;
+  if (p.startsWith("*.")) return h.endsWith("." + p.slice(2));
+  return h === p;
+}
+
+/**
+ * The `credentials` block and `tlsTerminate.excludeDomains` for a role's
+ * `inject` keys, or `{}` when it has none. One `envVars` entry per credential,
+ * `mode: "mask"` with its own `injectHosts`; TLS is terminated only for the
+ * domains that carry one, every other allowed domain excluded. Throws when an
+ * inject host is not reachable through the role's `allowedDomains` — a masked
+ * credential aimed at a host the role cannot connect to is a policy mistake,
+ * not a thing to emit silently.
+ */
+export function injectSettings(config, role, allowedDomains) {
+  const inject = injectKeysOf(config, role);
+  if (inject.length === 0) return {};
+  const allowed = allowedDomains ?? [];
+  for (const c of inject)
+    for (const h of c.hosts)
+      if (!allowed.some((p) => coversHost(p, h)))
+        throw new Error(
+          `roles.${role.name}: inject host ${h} (for ${c.name}) is not reachable.\n` +
+          `  A masked credential is substituted only on egress to its host, and this role's ` +
+          `network does not allow ${h}. Add it: [roles.${role.name}] network = ["${h}", …], ` +
+          `or correct the host in inject_hosts.`);
+  const credentials = {
+    envVars: inject.map((c) => ({ name: c.name, mode: "mask", injectHosts: c.hosts })),
+  };
+  // Terminate a domain only if it carries an inject host; exclude the rest.
+  const targets = inject.flatMap((c) => c.hosts);
+  const excludeDomains = allowed.filter((d) => !targets.some((h) => coversHost(d, h)));
+  return { credentials, tlsTerminate: { excludeDomains } };
+}
+
+/**
+ * The private folders of every role but `roleName`, absolute, in both
+ * spellings (as written and as the kernel meets it through a symlink).
  */
-export function providerPaths(config) {
+export function othersPrivate(config, roleName, abs = (p) => (p.startsWith("/") ? p : join(config.root, p)), { make = false } = {}) {
   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)];
+  for (const r of Object.values(config.roles))
+    if (r.name !== roleName)
+      for (const entry of r.private ?? []) {
+        const p = abs(privateDir(entry));
+        if (process.platform === "linux" && !existsSync(p)) {
+          if (!make) continue;
+          try { mkdirSync(p, { recursive: true }); } catch { continue; }
+        }
+        const real = realAncestor(p);
+        out.push(...(real === p ? [p] : [p, real]));
+      }
+  return 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;
+  }
+}