seisin 0.4.2 → 0.6.0

package/src/index.js

@@ -18,12 +18,11 @@ export { findConfig, loadConfig, parseToml } from "./config.js";
 /** Where seisin's own files live. */
 export { CONFIG_NAME, STATE_DIR, LOG_NAME } from "./layout.js";
 
-/** Who owns a path, and the sentence to hand a blocked agent. */
-export { covers, ownersOf, keyHolders, explain } from "./owners.js";
+/** Who owns a path, and the sentence to hand a denied agent. */
+export { covers, ownersOf, keyHolders, explain, explainFileRead, readTarget } from "./owners.js";
 
-/** A policy, resolved into sandbox settings and a child environment. */
-export { settingsFor, RUNTIME_WRITES, expand } from "./srt.js";
-export { buildEnv, BASE as BASE_ENV, DEFAULTS as DEFAULT_ENV } from "./env.js";
+/** A policy, resolved into sandbox settings. */
+export { settingsFor } from "./srt.js";
 
 /**
  * Keys that are references, and how a resolved value reaches a role.
@@ -32,33 +31,42 @@ export { buildEnv, BASE as BASE_ENV, DEFAULTS as DEFAULT_ENV } from "./env.js";
  * knowing whether an entry is a path or a reference; `resolveRef` is not,
  * because resolving is something seisin does and not something you ask it.
  */
-export { parseKey, defaultName, entriesOf, MODES, RESERVED_ENV } from "./keys.js";
+export { parseKey, defaultName, entriesOf, MODES } from "./keys.js";
 
-/** What a role keeps being refused, recomputed against the policy as it stands. */
-export { walls, wasted, MIN_HITS } from "./walls.js";
+/** What a role keeps being denied, recomputed against the policy as it stands. */
+export { walls, wasted } from "./walls.js";
 
 /** The report `check` prints, without the printing. */
 export { inspect, sharedPaths } from "./inspect.js";
 
 /** Credential-shaped content outside the declared key directories. */
-export { scan, SHAPES, DEFAULT_IGNORE } from "./scan.js";
+export { scan } from "./scan.js";
 
 /** The append-only record, and what can be learned from it. */
 export { read as readLog, logPath, observed, generalise } from "./log.js";
 
 /**
- * The queue of refusals waiting on a person.
+ * The queue of requests waiting on a person.
  *
  * `pending` and `grantFor` are public because reading the queue and drafting a
  * proposal are things a caller — including an MCP server — legitimately does.
- * `settle` and `applyGrant` are NOT exported: approving is not a tool call, and
+ * `settle` and `applyGrant` are NOT exported: granting is not a tool call, and
  * the surface should make that hard to get wrong rather than merely document
- * it. See docs/permission-requests.md.
+ * it. See docs/requests.md.
  */
-export { pending as pendingRequests, requestsPath, grantFor } from "./requests.js";
+export { pending as pendingRequests, requestsPath, grantFor, queueOf as requestQueue, recordHandoff } from "./requests.js";
+
+/**
+ * Where a denied write goes — decided, never executed.
+ *
+ * `requestQueue(config)` is the pending queue with each request's `handoff`
+ * decision against the policy as it stands. Something that starts roles reads
+ * it, starts `seisin run <handoff.role> --handoff <id>`, and may record with
+ * `recordHandoff` that it held one back; `decideHandoff` is there for the
+ * limits only that caller knows (how many chains a role has open, how many of
+ * the receiver are running). None of them grants anything.
+ */
+export { decideHandoff, MAX_DEPTH } from "./handoff.js";
 
 /** One PreToolUse decision. */
 export { decide, targetsOf } from "./hook.js";
-
-/** Masking a role's own secrets on the way out. */
-export { secretsOf, redactor } from "./redact.js";

package/src/inspect/codex.js

@@ -0,0 +1,64 @@
+import { join, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+
+/**
+ * How Codex is signed in on this machine: "chatgpt", "apikey", or null.
+ *
+ * Read from `auth.json` in `CODEX_HOME` or `~/.codex`, by the parent, which
+ * `check` is. Only the shape is looked at — which fields are set — and
+ * nothing from the file is kept or printed.
+ */
+export function codexSignIn(env = process.env) {
+  const home = env.CODEX_HOME && isAbsolute(env.CODEX_HOME) ? env.CODEX_HOME : join(homedir(), ".codex");
+  let auth;
+  try { auth = JSON.parse(readFileSync(join(home, "auth.json"), "utf8")); } catch { return null; }
+  if (!auth || typeof auth !== "object") return null;
+  if (typeof auth.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY) return "apikey";
+  if (auth.tokens && typeof auth.tokens === "object" && auth.tokens.refresh_token) return "chatgpt";
+  return null;
+}
+
+/**
+ * A role that looks set up for OpenAI and would leave Codex hanging.
+ *
+ * Signed in with ChatGPT, Codex talks to `chatgpt.com` for the model and to
+ * `auth.openai.com` to renew the sign-in — never to `api.openai.com` (measured
+ * 2026-09-30, codex 0.150.1: 0 connections). Without `chatgpt.com` it does not
+ * fail: it retries without end and prints nothing, which reads as an agent
+ * thinking. And the proxy's refusal does not reach seisin's log.
+ *
+ * `check` does not know which CLI a role runs, so the signal is the two facts
+ * it can see: this machine's Codex is signed in with ChatGPT, and the role's
+ * list names something under `openai.com` — a list written for OpenAI — but
+ * not `chatgpt.com`. A role whose `env` passes `OPENAI_API_KEY` is left out:
+ * it is set up for the API, where `api.openai.com` is right. Wrong costs a
+ * sentence, never a run, the same trade as the model-endpoint warning above.
+ */
+export function codexSignInWarnings(config, roles, env = process.env) {
+  if (codexSignIn(env) !== "chatgpt") return [];
+  const reaches = (list, host) => list.some((d) => d === "*" || d === host ||
+    (d.startsWith("*.") && host.endsWith(d.slice(1))));
+  const out = [];
+  for (const r of roles) {
+    const list = r.network ?? config.allowedDomains ?? [];
+    if (!list.some((d) => /(^|\.)openai\.com$/i.test(d))) continue;
+    if ((r.env ?? []).includes("OPENAI_API_KEY")) continue;
+    const missing = ["chatgpt.com", "auth.openai.com"].filter((h) => !reaches(list, h));
+    if (!missing.length) continue;
+    out.push({
+      kind: "codex-chatgpt-endpoint",
+      headline: `${r.name} allows ${list.filter((d) => /openai\.com$/i.test(d)).join(" ")} but not ${missing.join(" ")}`,
+      detail:
+        "Codex on this machine is signed in with ChatGPT, and with that sign-in it talks to " +
+        "chatgpt.com for the model and to auth.openai.com to renew the sign-in, never to " +
+        "api.openai.com. " +
+        (missing.includes("chatgpt.com")
+          ? "Without chatgpt.com a Codex run does not fail: it retries without end and prints " +
+            "nothing, and the proxy's denial does not reach seisin's log. "
+          : "Without auth.openai.com a Codex run works until the sign-in has to be renewed. ") +
+        `If ${r.name} runs Codex, add ${missing.join(" and ")}; if it does not, this is not about it.`,
+    });
+  }
+  return out;
+}

package/src/inspect/credentials.js

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { SHAPES } from "../scan.js";
+
+/**
+ * Credential-shaped names at the top of the repository, and nothing deeper.
+ *
+ * One `readdir`, no recursion, conventional names only. It exists to answer
+ * "does this repo plausibly have secrets" fast enough to run on every `check`,
+ * not to find them — `seisin scan` is the one that looks properly.
+ */
+const CREDENTIAL_NAMES = /^(\.env(\..+)?|\.secrets|secrets|\.netrc|.*\.(pem|key|p12|pfx))$/i;
+
+export function credentialish(root) {
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = new Set(entries.filter((e) => CREDENTIAL_NAMES.test(e.name)).map((e) => e.name));
+
+  /**
+   * And the ones whose name gives nothing away.
+   *
+   * The name test misses `credentials.txt`, `tokens.conf`, `config.local` —
+   * which a field review found by writing a test file this did not catch, and
+   * then blaming the test. The test was fine; the detector was name-only.
+   *
+   * So the root's small text files are also read, with the same shapes
+   * `seisin scan` uses. Root only, small only, and it stops at the first hit
+   * per file: this runs on every `check` and the full walk is `scan`'s job.
+   */
+  const CERTAIN = SHAPES.filter(([c]) => c === "certain").map(([, , re]) => re);
+  for (const e of entries) {
+    if (found.size >= 4) break;
+    if (!e.isFile() || found.has(e.name)) continue;
+    try {
+      const p = join(root, e.name);
+      if (statSync(p).size > 64 * 1024) continue;
+      const text = readFileSync(p, "utf8");
+      if (CERTAIN.some((re) => re.test(text))) found.add(e.name);
+    } catch {
+      /* unreadable, or not text: not our business here */
+    }
+  }
+  return [...found].sort().slice(0, 4);
+}

package/src/inspect/enforce.js

@@ -0,0 +1,24 @@
+import { settingsFor } from "../srt.js";
+
+export function enforceWarnings(config, roles) {
+  const warnings = [];
+  // A pattern the kernel cannot be given is not a policy, it is a sentence that
+  // reads like one. `run` refuses it; `check` exists precisely so you find that
+  // out while reading the map rather than mid-run.
+  for (const r of roles) {
+    try {
+      settingsFor(config, r.name);
+    } catch (e) {
+      // Whatever settingsFor refuses, `run` will refuse too. The label used to
+      // say "unenforceable-glob" for every one of them, which mislabelled the
+      // key-outside-its-directory error as a glob problem — a warning that
+      // names the wrong cause sends the reader to the wrong line.
+      warnings.push({
+        kind: "cannot-be-enforced",
+        headline: `${r.name}: ${e.message.split("\n")[0]}`,
+        detail: e.message.split("\n").slice(1).map((s) => s.trim()).filter(Boolean).join(" "),
+      });
+    }
+  }
+  return warnings;
+}

package/src/inspect/files.js

@@ -0,0 +1,71 @@
+import { resolve } from "node:path";
+import { lstatSync, readdirSync } from "node:fs";
+
+/**
+ * A role's territory, sorted by what the kernel will do with each line.
+ *
+ * Three shapes get through `settingsFor` (see EXPRESSIBLE in srt.js): the whole
+ * repo, a subtree `x/**`, and a literal path. The literal path is the one the
+ * text cannot settle on its own — `data/base.sqlite` and `data` are both
+ * literal, and to the kernel the second is a subtree because it is a directory.
+ * So the disk is asked, once per line: a regular file is a file, a directory is
+ * a subtree, and anything else — absent, a symlink, a socket — goes in neither
+ * count rather than being guessed at. That is one `lstat` per declared path,
+ * bounded by the length of the policy and not the size of the repo, which is
+ * the line `check` stays on.
+ *
+ * Subtrees come back as the absolute prefix the kernel will be handed, so that
+ * "is this file's folder inside that grant" is the same comparison the kernel
+ * makes — a prefix — and not a second reading of the glob.
+ */
+export function territoryOf(config, role) {
+  const root = resolve(config.root);
+  const abs = (p) => resolve(root, p);
+  const files = [];
+  const subtrees = [];
+  for (const glob of role.writes) {
+    if (glob === "**" || glob.endsWith("/**")) {
+      subtrees.push(abs(glob === "**" ? "." : glob.slice(0, -3)));
+      continue;
+    }
+    if (/[*?[\]]/.test(glob)) continue;      // already refused above as cannot-be-enforced
+    if (implicitSidecar(role, glob)) continue; // part of its database, not a file of its own
+    const s = lstatOrNull(abs(glob));
+    if (s?.isFile()) files.push({ glob, abs: abs(glob) });
+    else if (s?.isDirectory()) subtrees.push(abs(glob));
+  }
+  return { files, subtrees };
+}
+
+/**
+ * A `-wal`, `-shm` or `-journal` the role has because it writes the database
+ * beside it — the expansion in config.js, which `writes` carries. It is the
+ * same resource as the database, so it is not counted or reported as another
+ * file. One declared WITHOUT its database is the role's own, and counts.
+ */
+export function implicitSidecar(role, glob) {
+  const m = /^(.*\.sqlite3?)-(wal|shm|journal)$/.exec(glob);
+  return !!m && role.writes.includes(m[1]);
+}
+
+/** Is `p` the prefix, or somewhere beneath it. The kernel's own test, in one line. */
+export function under(p, prefix) {
+  return p === prefix || p.startsWith(prefix + "/");
+}
+
+/** The regular files directly inside `dir`, by name. Not folders, not links, not deeper. */
+export function regularFilesIn(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+function lstatOrNull(p) {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+}

package/src/inspect/home.js

@@ -0,0 +1,43 @@
+import { CREDENTIAL_HOMES } from "../srt.js";
+
+/**
+ * What a role can still read in YOUR home, which is the limit people are most
+ * surprised by.
+ *
+ * `~/.ssh`, `~/.aws/credentials`, `~/.npmrc` and `~/.config/gh/hosts.yml` are
+ * ordinary readable files to every role unless `[runtime] isolate` says
+ * otherwise, and nothing on screen said so. Reads outside the key directories
+ * being open is a deliberate trade - an agent that cannot read the machine
+ * cannot work - but a trade nobody was shown is not a trade they made.
+ *
+ * It reports the level rather than pushing one. `credentials` closes those four
+ * and leaves the agent logged in; `home` closes the agent's own directories too
+ * and costs the session. Which of the two you want is the threat model, which
+ * is why there is no default beyond off.
+ */
+export function homeReachWarning(config) {
+  if (config.read === "territory") return null;
+  const level = config.isolate === true ? "home" : config.isolate;
+  if (level === "home") return null;             // nothing left to say
+
+  const where = CREDENTIAL_HOMES.slice(0, 4).join(" ");
+  return level === "credentials"
+    ? {
+        kind: "home-partly-open",
+        headline: "your credentials are closed to every role; the agent's own directories are not",
+        detail:
+          `isolate = "credentials" denies ${where} and the rest. What stays open is ` +
+          "~/.claude to runs of claude and ~/.codex to runs of codex, which is what keeps the " +
+          "agent signed in, so the runs of one agent share its session and can read each other's. " +
+          '`isolate = "home"` closes those ' +
+          "too, and then every CLI in the sandbox will ask you to log in again.",
+      }
+    : {
+        kind: "home-open",
+        headline: `every role can read ${where} and the rest of your home`,
+        detail:
+          "reads outside the [keys] dir are open on purpose - an agent that cannot read the " +
+          "machine cannot work - but that includes the places credentials live. " +
+          '`[runtime] isolate = "credentials"` closes them, and the agent stays logged in.',
+      };
+}

package/src/inspect/inject.js

@@ -0,0 +1,68 @@
+/**
+ * Warnings for `key_mode = "inject"`: the MITM it costs, the traffic it
+ * widens, the one thing it does not close, and the platform it does not run on.
+ *
+ * Masking is the only mode where the agent never sees the value, and it is the
+ * only one that reads the role's encrypted traffic to do it. A reader of
+ * `check` should see, per masked credential: which hosts are intercepted (and
+ * when a wildcard allow drags more than the one host under interception), that
+ * the value is still recoverable by reflection, and — off Linux — that the role
+ * will not run here. None of this is a reason not to use inject; it is the
+ * price printed next to the thing it buys.
+ */
+import { injectKeysOf } from "../keys.js";
+import { coversHost as covers } from "../srt.js";
+
+export function injectWarnings(config, roles) {
+  const out = [];
+  for (const r of roles) {
+    let inject;
+    try {
+      inject = injectKeysOf(config, r);
+    } catch (e) {
+      const [headline, ...rest] = e.message.split("\n");
+      out.push({ kind: "cannot-be-enforced", role: r.name, headline, detail: rest.join("\n").trim() });
+      continue;
+    }
+    if (inject.length === 0) continue;
+    const allowed = r.network ?? config.allowedDomains ?? [];
+
+    if (process.platform !== "linux")
+      out.push({
+        kind: "inject-platform",
+        role: r.name,
+        headline: `${r.name}: key_mode = "inject" is not available on ${process.platform} — it is Linux-only for now`,
+        detail: `On this machine the role will not run. Masked injection on macOS is tracked upstream ` +
+          `(anthropics/sandbox-runtime#593) and enables once that lands. Run this role on Linux, or ` +
+          `use "env"/"run-file" here.`,
+      });
+
+    for (const c of inject) {
+      const terminated = new Set();
+      const wholesale = [];
+      for (const h of c.hosts)
+        for (const p of allowed)
+          if (covers(p, h)) {
+            terminated.add(p);
+            if (p.startsWith("*.")) wholesale.push({ pattern: p, host: h });
+          }
+      const under = [...terminated].join(", ") || "(none reachable — check network)";
+      const wildcardNote = wholesale.length
+        ? ` The wildcard ${wholesale.map((w) => w.pattern).join(", ")} is terminated whole, not just ` +
+          `${wholesale.map((w) => w.host).join(", ")}: srt cannot intercept one host out of a wildcard.`
+        : "";
+      out.push({
+        kind: "inject-mitm",
+        role: r.name,
+        headline: `${r.name}: ${c.name} is masked (agent sees a fake); TLS terminated for ${under}`,
+        detail:
+          `seisin reads this role's HTTPS to ${under} with a CA of its own, to substitute the real token ` +
+          `on the way out.${wildcardNote} The token is still recoverable by reflection: if ${c.hosts.join("/")} ` +
+          `stores what the agent sends and returns it later (an issue, a gist, a comment, a note), the agent ` +
+          `can POST the sentinel, have the host keep the real value, and read it back. inject stops the agent ` +
+          `from seeing the token directly and from sending it anywhere else — not this. Use a least-scope token.`,
+      });
+    }
+  }
+  return out;
+}

package/src/inspect/keys.js

@@ -0,0 +1,74 @@
+import { entriesOf } from "../keys.js";
+import { credentialish } from "./credentials.js";
+
+export function envWarnings(roles) {
+  const warnings = [];
+  // `env` is a hole in the [keys] model, on purpose: some tools only take a
+  // credential through the environment. It should still be loud, because it is
+  // the one place a secret reaches a role without being a declared key.
+  const SECRETISH = /(TOKEN|KEY|SECRET|PASSWORD|PASSWD|AUTH|COOKIE|SESSION|PRIVATE|CREDENTIAL)/i;
+  for (const r of roles) {
+    const risky = (r.env ?? []).filter((n) => SECRETISH.test(n));
+    if (risky.length)
+      warnings.push({
+        kind: "secret-through-env",
+        headline: `${r.name} receives ${risky.join(", ")} through the environment`,
+        detail:
+          "that bypasses [keys] entirely: it is not scoped, not redacted by name, and not " +
+          "visible in the key map. Declare it as a key file where the tool allows one.",
+      });
+  }
+  return warnings;
+}
+
+export function keyFloorWarnings(config) {
+  const warnings = [];
+  /**
+   * A policy with no credential floor at all, in a repo that has credentials.
+   *
+   * `[keys] dir` is what produces `denyRead`. Without it the emitted settings
+   * carry an empty deny list, so every role reads every secret in the
+   * repository — and until this warning, nothing said so. The existing
+   * `keys-unscoped` only fires when a role *lists* keys, which is the case
+   * where somebody already thought about it.
+   *
+   * The dangerous shape is the other one, and it is not hypothetical: a policy
+   * generated by a script. The deployment this was built against generates its
+   * `seisin.toml` from a Python program, and declares `[keys] dir` mostly so
+   * `scan` skips those directories. A generator that dropped that one line
+   * would hand every role the credential tree and produce a clean `check`.
+   *
+   * Credit where it is due: this is `L-01` of a code review of another
+   * project's contract type, which makes its credential floor impossible to
+   * construct empty. That is the right shape and it is a bigger change than a
+   * warning. This is the cheap half — and the review's claim that the file
+   * path was safe turned out to be generous: it was not.
+   *
+   * Deliberately NOT a full `seisin scan`: that walks the tree and `check` has
+   * to stay instant. A shallow look at the repository root catches the
+   * conventional places and costs one `readdir`.
+   */
+  if ((config.keyDirs ?? []).length === 0) {
+    const found = credentialish(config.root);
+    if (found.length)
+      warnings.push({
+        kind: "no-key-floor",
+        headline: `no [keys] dir is declared, and this repo has ${found.join(", ")} — every role can read them`,
+        detail:
+          "Without a key directory the emitted policy denies no reads at all. Declare the " +
+          "directory your secrets live in, and the roles that may read each one.",
+      });
+  }
+
+  // Only a key that is a PATH needs a key directory. A config whose secrets all
+  // live in a vault has no `[keys] dir` and nothing wrong with it, and warning
+  // there would be the tool insisting on the arrangement it was built for.
+  if (config.keyDirs.length === 0 &&
+      Object.values(config.roles).some((r) => entriesOf(r).some((k) => k.kind === "file")))
+    warnings.push({
+      kind: "keys-unscoped",
+      headline: "keys are listed but [keys] dir is unset — nothing will be scoped",
+      detail: null,
+    });
+  return warnings;
+}