seisin 0.4.0 → 0.5.0

package/src/intake.js

@@ -2,8 +2,8 @@
  * The parent's intake: what arrives during a run, checked, and written down.
  *
  * Two sources, and they are not equally trustworthy. The hook runs inside the
- * box, so everything it sends is a claim by the process being recorded. The
- * kernel is the thing that actually refused. Both end up as log lines and,
+ * sandbox, so everything it sends is a claim by the process being recorded. The
+ * kernel is the thing that actually denied. Both end up as log lines and,
  * sometimes, as requests in front of a person; this module is where each is
  * recomputed from the policy rather than believed.
  *
@@ -26,7 +26,7 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { toRepoRelative } from "./paths.js";
-import { explain, ownersOf } from "./owners.js";
+import { explain, ownersOf, keyHolders, inKeyDir } from "./owners.js";
 import { append, logPath } from "./log.js";
 import { record, requestsPath } from "./requests.js";
 import { inScope, scopeOf, reachedForContent } from "./violations.js";
@@ -50,6 +50,10 @@ export function policyId(config) {
  */
 export function intake({ config, role, runId, observe = false, settings, notify }) {
   const stamp = { run: runId.slice(0, 8), policy: policyId(config) };
+  // No `at` from here or from the sandbox: append() stamps the parent's clock and
+  // ignores any other. The confined process chose the time of its own lines —
+  // it could date them into or out of every `since` window, or make its
+  // requests look old enough to be passed over.
   const log = (entry) => append(logPath(config.root), { ...entry, ...stamp });
   const ask = (asked) => { record(requestsPath(config.root), asked); notify?.maybe(asked); };
 
@@ -59,12 +63,12 @@ export function intake({ config, role, runId, observe = false, settings, notify
   const stats = { offPolicy: 0, walks: 0 };
 
   /**
-   * Nothing from inside the box is taken at its word.
+   * Nothing from inside the sandbox is taken at its word.
    *
    * The sender is the process being recorded, so every field it supplies is
    * a claim. Two of them matter. `role` decides whose request this is — left
-   * alone, a frontend agent could file one as backend and wait for a human to
-   * approve it. `owners` decides who the queue says it belongs to, and the
+   * alone, a frontend agent could file one as backend and wait for a person to
+   * grant it. `owners` decides who the queue says it belongs to, and the
    * parent can work that out itself from the policy.
    *
    * So the role is overwritten with the role of this run, the owners are
@@ -80,7 +84,7 @@ export function intake({ config, role, runId, observe = false, settings, notify
      * never queued — which servers a role may load is a change to its `mcp`
      * list, not a grant a person approves, the same shape as never_writes. The
      * verdict is recomputed here from the same list rather than believed from
-     * inside the box: the server is parsed from the tool name and asked of the
+     * inside the sandbox: the server is parsed from the tool name and asked of the
      * policy, so a line claiming "allowed" for a server the role may not load
      * comes back marked `disputed`.
      */
@@ -91,7 +95,7 @@ export function intake({ config, role, runId, observe = false, settings, notify
       const v = server ? explain(config, role, "mcp", server) : { allowed: false };
       const expected = observe ? "observed" : v.allowed ? "allowed" : "denied";
       return void log({
-        at: entry.at, role,
+        role,
         tool: String(entry.tool ?? "").slice(0, 40),
         action: "use", kind: "tool",
         target: entry.target.slice(0, 1000),
@@ -106,7 +110,7 @@ export function intake({ config, role, runId, observe = false, settings, notify
 
     if (to === "log") {
       // The same treatment the queue already got. The role was overwritten but
-      // everything else was passed through, so a process inside the box could
+      // everything else was passed through, so a process inside the sandbox could
       // write "allowed" lines for paths it never touched — which would not move
       // the boundary, but would move `review`, and `init --from-observations`
       // builds a policy out of exactly this.
@@ -123,7 +127,6 @@ export function intake({ config, role, runId, observe = false, settings, notify
         ? "observed"
         : explain(config, role, entry.action, entry.target).allowed ? "allowed" : "denied";
       return void log({
-        at: entry.at,
         role,
         tool: String(entry.tool ?? "").slice(0, 40),
         action: entry.action,
@@ -139,7 +142,7 @@ export function intake({ config, role, runId, observe = false, settings, notify
     /**
      * The policy has to actually refuse it, or it does not belong in a queue.
      *
-     * Nothing checked. A process inside the box could file a request for a path
+     * Nothing checked. A process inside the sandbox could file a request for a path
      * its own role already owns, and the queue would print *first refused on
      * …* about something that was never refused — a sentence placed in front of
      * a person for approval, describing an event that did not happen.
@@ -161,7 +164,10 @@ export function intake({ config, role, runId, observe = false, settings, notify
     // The owners explain found: for a key that is who declares it, not who
     // writes the directory it sits in — the queue said "owned by dev" about
     // backend's key because dev writes `**`.
-    ask({ role, action: entry.action, target: entry.target, owners: v.owners });
+    // Capped like the log line above: a request's target is a path, and an
+    // uncapped one (5k+ chars were accepted) is a way to bloat the queue a
+    // person reads. 1000 is more than any real path and matches the log.
+    ask({ role, action: entry.action, target: entry.target.slice(0, 1000), owners: v.owners });
   }
 
   function fromKernel(d) {
@@ -179,7 +185,7 @@ export function intake({ config, role, runId, observe = false, settings, notify
       connects.add(d.path);
       const v = explain(config, role, "connect", d.path);
       log({
-        at: new Date().toISOString(), role, tool: "kernel", source: "kernel",
+        role, tool: "kernel", source: "kernel",
         action: "connect", kind: "network", target: d.path, verdict: "denied",
         owners: [], reason: d.operation, ...(v.listed ? { listed: true } : {}),
       });
@@ -197,7 +203,7 @@ export function intake({ config, role, runId, observe = false, settings, notify
      *
      * Without this the two halves of the record disagree in the worst
      * direction: `review` would show a role stopped repeatedly on a directory
-     * while the queue held nothing to approve, so the one refusal a person most
+     * while the queue held nothing to grant, so the one refusal a person most
      * needed to see — the one that escaped the hook — would be the one with no
      * way to act on it.
      *
@@ -218,11 +224,13 @@ export function intake({ config, role, runId, observe = false, settings, notify
     // path has always had this check; the kernel path did not, which is how a
     // role ended up asking for its own territory.
     const granted = verdict?.allowed === true;
+    // A key is declared, not owned: who a write lookup finds for `.secrets/x`
+    // is always nobody, and the queue said "(unowned)" over another role's key.
+    const whose = d.action === "read" && inKeyDir(config, rel) ? keyHolders(config, rel) : ownersOf(config, rel);
     if (rel !== d.path && !barred && !unaskable && !granted)
-      ask({ role, action: d.action, target: rel, owners: ownersOf(config, rel) });
+      ask({ role, action: d.action, target: rel, owners: whose });
 
     log({
-      at: new Date().toISOString(),
       role,
       tool: "kernel",
       source: "kernel",

package/src/keys.js

@@ -352,7 +352,7 @@ export function readFileRef(entry, root = ".") {
  * of these:
  *
  *   - **What seisin itself injects.** `SEISIN_ROLE` is how the hook inside the
- *     box learns which role it is. A key called that would let a policy tell
+ *     sandbox learns which role it is. A key called that would let a policy tell
  *     the hook it is somebody else — privilege confusion written in the one
  *     file that is supposed to prevent it. Same for the config path and the
  *     audit socket.
@@ -427,8 +427,10 @@ export function entriesOf(role) {
  * runtime. A mode called `file` sitting ten centimetres from a runtime field
  * called `files` that fails that way is a trap with a date on it.
  *
- * `scratch` also says what actually happens: the value lands in scratch space
- * for the turn and is removed after it, which `file` does not say at all.
+ * `scratch` said what happened when it was named: the value landed in scratch
+ * space and was removed after the run, which `file` does not say at all. Since
+ * the 2026-09-23 fix it lands in the run's private directory instead (rundir.js),
+ * and the name is a breaking rename listed in docs/glossary.md, not made here.
  */
 export const MODES = ["env", "scratch", "inject"];
 
@@ -442,8 +444,8 @@ export const MODES = ["env", "scratch", "inject"];
  * tables — and growing the parser to hold one field is the trade this repo has
  * already decided against out loud.
  *
- * The important half survives that limit. The encargo's argument for declaring
- * the mode beside the permission is that a reader of `seisin.toml` can say
+ * The important half survives that limit. The argument for declaring
+ * the mode beside the key is that a reader of `seisin.toml` can say
  * "this role sees the value" without opening any code, and a per-role setting
  * answers exactly that question.
  *
@@ -465,9 +467,9 @@ export function modeOf(config, role, entry) {
         `[keys.providers.${entry.scheme}] mode = "env".`;
     throw new Error(
       `roles.${role.name}: key "${entry.raw}" has no delivery mode.\n` +
-      `  Declare one beside the permission: [roles.${role.name}] key_mode = "env".${second}\n` +
-      `  "env" passes the value as ${entry.name}; "scratch" writes it to a file inside the ` +
-      `role's scratch space, grants that one path, and removes it when the turn ends.`);
+      `  Declare one beside the key: [roles.${role.name}] key_mode = "env".${second}\n` +
+      `  "env" passes the value as ${entry.name}; "scratch" writes it to a file in the ` +
+      `run's private directory, grants that one path, and removes it when the run ends.`);
   }
   if (mode === "inject")
     throw new Error(
@@ -497,8 +499,8 @@ export function modeOf(config, role, entry) {
  * Three properties, each of which was a requirement before it was code:
  *
  *   - **The parent runs it, never the confined process.** Same reason `owners`
- *     recomputes instead of believing what it is told: the inside of the box
- *     cannot be allowed to reach the thing that decides what the box contains.
+ *     recomputes instead of believing what it is told: the inside of the sandbox
+ *     cannot be allowed to reach the thing that decides what the sandbox contains.
  *     A provider command spawned from within the sandbox would need the vault's
  *     own credential in there with it, which is the problem this feature exists
  *     to remove.
@@ -521,7 +523,7 @@ export function resolveRef(entry, provider, { run = spawnSync, root = ".", confi
    *
    * `spawnSync("fakeprov")` searched the parent's PATH, and a PATH directory
    * inside a territory made the next run execute whatever that role had put
-   * there — outside the box, as you. Measured on 2026-09-23 with a marker file.
+   * there — outside the sandbox, as you. Measured on 2026-09-23 with a marker file.
    * The provider's own PATH is narrowed the same way, because a provider that
    * is a script starts with `#!/usr/bin/env bash` and looks its interpreter up
    * again. Without a config (a caller embedding seisin), or with a `run` of the

package/src/kinds.js

@@ -0,0 +1,207 @@
+/**
+ * What kind of thing an unowned refused path is.
+ *
+ * "Owned by nobody" used to be the whole sentence, and the question a person
+ * brings to it is not *whose should this be* but *what do I do with it*. The
+ * obvious helper — suggest an owner, the role that asked or the owner of the
+ * nearest folder — was measured on one deployment's 317 unowned paths before
+ * it was built: it was right about 5% of the time, and in the other 95% it was
+ * wrong in the one direction seisin does not accept, it widened. A lock file
+ * inside `.git` is a mutex, not territory; a directory a test creates with its
+ * PID in the name is the test's bug; a credential is never granted a write.
+ * Giving any of those to "whoever asked" hands them a folder that is everybody's.
+ *
+ * So this names the kind and the move that fits it, and only `territory` — a
+ * normal path that nobody claims — is left as the decision it looks like.
+ *
+ * Read from the path alone, plus one fact about the log (`kindsOf`): the same
+ * name made unique per run in several sibling places. No disk, no policy, no
+ * clock, so it is the same answer on every screen that asks. It never changes
+ * what is allowed; it changes what is said about a refusal.
+ */
+import { CREDENTIAL_HOMES } from "./grants.js";
+
+/** Every kind, in the order a reader should deal with them, and the one line each says. */
+export const KINDS = {
+  credential:
+    "credential-shaped: never grant a write to it; if a role needs to read it, declare it as a key",
+  git:
+    "git's own bookkeeping, not territory: grant the repository to the role that runs git there, never the file",
+  temporary:
+    "temporary files a tool or a test makes while it runs: point it at $TMPDIR (already writable through [runtime] writes), or fix it; do not grant it in the repo",
+  build:
+    "build output or installed dependencies: grant the folder to the role that builds it, or build outside the repo",
+  territory:
+    "an ownable path no role claims: a real decision — give it an owner, or tell the agent not to write there",
+};
+
+/** A lock file inside `.git` gets a more precise line than the rest of git's metadata. */
+const GIT_LOCK =
+  "git taking a lock in a repo this role does not own: `seisin run` sets GIT_OPTIONAL_LOCKS=0 so status and diff stop taking it; a commit or fetch still needs the repository — grant the repository, never the lock";
+
+/**
+ * Credential-shaped names.
+ *
+ * The places `[runtime] isolate` closes in a home directory are the first
+ * source (grants.js), by name, because a repository can hold the same files:
+ * a `.npmrc` with a token in it is the same secret in either place. `.config`
+ * is left out on purpose — it is a container, and inside a repo it is mostly
+ * tool settings; `.docker` and `.kube` count only for the file that holds the
+ * login (`config`, `config.json`), not for every Dockerfile beside it.
+ */
+const HOME_NAMES = CREDENTIAL_HOMES.map((h) => h.replace(/^~\//, ""));
+const CONTAINERS = new Set([".config", ".docker", ".kube"]);
+const SECRET_DIRS = new Set([...HOME_NAMES.filter((n) => !CONTAINERS.has(n) && !/rc$|credentials$/.test(n)), ".secrets", "secrets"]);
+const LOGIN_DIRS = new Set([".docker", ".kube"]);
+const SECRET_FILES = new Set([...HOME_NAMES.filter((n) => /rc$|credentials$/.test(n)), ".pypirc", ".pgpass", ".htpasswd"]);
+const SECRET_EXT = /\.(pem|key|p12|pfx|jks|keystore|kdbx|gpg)$/i;
+const SSH_KEY = /^id_(rsa|dsa|ecdsa|ed25519)(_sk)?$/;
+// `.env`, `.env.local`, `.env.production` — but not the file that exists to be committed.
+const DOTENV = /^\.env(\..+)?$/;
+const DOTENV_TEMPLATE = /\.(example|sample|template|dist|defaults?)$/i;
+/**
+ * A token file: the word in the name, and a data extension. The extension is
+ * what keeps `src/auth/token.ts` — code about tokens — out of it.
+ */
+const TOKEN_FILE = /(^|[-_.])(tokens?|secrets?|passwords?|passwd|credentials?|api[-_]?keys?|private[-_]?key)([-_.]|$)/i;
+const DATA_EXT = /(^[^.]*$)|\.(txt|json|ya?ml|toml|ini|cfg|conf|env|key)$/i;
+
+/**
+ * Scratch. Directories every toolchain uses for caches, and the shapes an
+ * atomic write, an editor or a database leaves beside a file for a moment.
+ */
+const CACHE_DIRS = new Set([
+  "tmp", "temp", ".tmp", ".temp", ".cache", "_cache", "__pycache__", ".pytest_cache",
+  ".mypy_cache", ".ruff_cache", ".hypothesis", ".tox", ".nox", ".parcel-cache", ".turbo",
+  ".eslintcache", ".sass-cache", ".gradle", ".dart_tool",
+]);
+const SCRATCH_FILE = [
+  /\.(tmp|temp|swp|swo|swx|bak|orig|rej|pid|sock|log)$/i,
+  /\.tmp[.\-_]/i,                              // `BACKLOG.md.tmp.32029.03c4` — write-then-rename
+  /\.py[co](\.\d+)?$/,                         // bytecode, and its own write-then-rename
+  /-(wal|shm|journal)$/,                       // sqlite's sidecars, beside a database
+  /~$/, /^\.#/, /^#.*#$/,                      // editors
+  /^\.!\d+!/,                                  // `.!36165!file` — a copy in flight
+  /^\.DS_Store$/,
+  /^pytest-cache-files-/,
+  /(^|[-_])logs?$/i,                           // `logs`, `latest_logs`: what a run leaves
+];
+/**
+ * `*.lock` is scratch — a mutex a tool takes and drops — except the files that
+ * pin dependencies, which are committed and somebody's to edit.
+ */
+const TOOL_LOCK = /\.lock$/i;
+const DEPENDENCY_LOCKS = new Set([
+  "yarn.lock", "Cargo.lock", "Gemfile.lock", "poetry.lock", "composer.lock", "flake.lock",
+  "Pipfile.lock", "uv.lock", "mix.lock", "pubspec.lock", "Podfile.lock", "bun.lock", "pdm.lock",
+]);
+
+/**
+ * Build output and installed dependencies. The same names `seisin scan` skips
+ * as machinery nobody wrote (scan.js DEFAULT_IGNORE), minus the caches above.
+ */
+const BUILD_DIRS = new Set([
+  "node_modules", "dist", "build", ".next", ".nuxt", ".svelte-kit", ".output", ".angular",
+  "vendor", ".venv", "venv", "coverage", "target", "out", ".expo", "bower_components",
+]);
+
+const segmentsOf = (p) => String(p).replace(/\\/g, "/").split("/").filter((s) => s && s !== ".");
+
+/**
+ * The kind of one path, from the path alone.
+ *
+ * `keyDirs` are the policy's declared key directories: a path under one is a
+ * credential whatever it is called. The order is the safe one — a name that is
+ * both a credential and scratch (`.env.tmp`) is said as a credential, since
+ * that is the reading that never ends in a grant.
+ */
+export function kindOf(target, { keyDirs = [] } = {}) {
+  const segs = segmentsOf(target);
+  const name = segs[segs.length - 1] ?? "";
+  const dirs = segs.slice(0, -1);
+  const kind = (k, hint = KINDS[k]) => ({ kind: k, hint });
+
+  const flat = segs.join("/");
+  const inKeyDir = keyDirs.some((d) => {
+    const k = segmentsOf(d).join("/");
+    return k && (flat === k || flat.startsWith(k + "/") || flat.includes("/" + k + "/") || flat.endsWith("/" + k));
+  });
+  if (inKeyDir || dirs.some((d) => SECRET_DIRS.has(d)) || SECRET_FILES.has(name) ||
+      SECRET_EXT.test(name) || SSH_KEY.test(name) ||
+      (DOTENV.test(name) && !DOTENV_TEMPLATE.test(name)) ||
+      (TOKEN_FILE.test(name) && DATA_EXT.test(name)) ||
+      (LOGIN_DIRS.has(dirs[dirs.length - 1]) && /^config(\.json)?$/.test(name)))
+    return kind("credential");
+
+  const git = segs.indexOf(".git");
+  if (git !== -1) return git < segs.length - 1 && /\.lock$/.test(name) ? kind("git", GIT_LOCK) : kind("git");
+
+  if (segs.some((s) => CACHE_DIRS.has(s)) || SCRATCH_FILE.some((re) => re.test(name)) ||
+      (TOOL_LOCK.test(name) && !DEPENDENCY_LOCKS.has(name)))
+    return kind("temporary");
+
+  if (segs.some((s) => BUILD_DIRS.has(s))) return kind("build");
+
+  return kind("territory");
+}
+
+/**
+ * A name made unique per run: `test-run-57141-2b32ca`, `run_8812`,
+ * `out.4419525232`. The stem, and a tail of one or two tokens: the first with a
+ * digit, the second with a digit or all hex (`-bfaeec` is a random suffix
+ * that happened to draw no digit) — so `report-2026.json` never matches, since
+ * an extension is not a run.
+ * Only a hint on its own: `run-2026` looks the same as a folder somebody named.
+ */
+const RUN_UNIQUE = /^(.+?)[-_.](?=[0-9a-z]*\d)([0-9a-z]{3,})([-_.](?:(?=[0-9a-z]*\d)[0-9a-z]{4,}|[0-9a-f]{6,}))?$/i;
+
+/** How many siblings of one stem it takes to call it generated rather than named. */
+export const GENERATED_SIBLINGS = 3;
+
+/**
+ * The kind of every path in a set, which is what a screen has.
+ *
+ * One rule needs the set and not the path, and it is the one that mattered
+ * most on the log it was measured on: a test that makes a directory with its
+ * PID in the name produced 258 of 317 unowned paths, each one different. Alone,
+ * `test-run-57141-2b32ca` could be a real folder. The same stem with a
+ * different run-unique tail in three or more places under one parent is not a
+ * folder anybody named — it is a generator, and granting it to whoever asked
+ * would hand over the parent. A repeated name is a fact about this log, not a
+ * guess about somebody's toolchain, which is why this is here and a list of
+ * test runners is not.
+ *
+ * Returns a Map from each target to `{ kind, hint }`.
+ */
+export function kindsOf(targets, opts = {}) {
+  const out = new Map();
+  const stems = new Map();
+  for (const t of targets) {
+    if (out.has(t)) continue;
+    out.set(t, kindOf(t, opts));
+    const segs = segmentsOf(t);
+    segs.forEach((s, i) => {
+      const m = RUN_UNIQUE.exec(s);
+      if (!m) return;
+      const k = `${segs.slice(0, i).join("/")}\u0000${m[1]}`;
+      (stems.get(k) ?? stems.set(k, new Set()).get(k)).add(s);
+    });
+  }
+  const generated = new Set();
+  for (const [k, names] of stems) {
+    if (names.size < GENERATED_SIBLINGS) continue;
+    const parent = k.split("\u0000")[0];
+    for (const n of names) generated.add(parent ? `${parent}/${n}` : n);
+  }
+  if (!generated.size) return out;
+  for (const [t, k] of out) {
+    if (k.kind !== "territory") continue;
+    const segs = segmentsOf(t);
+    for (let i = 1; i <= segs.length; i++)
+      if (generated.has(segs.slice(0, i).join("/"))) {
+        out.set(t, { kind: "temporary", hint: KINDS.temporary });
+        break;
+      }
+  }
+  return out;
+}