seisin 0.1.0

package/src/handoff.js

@@ -0,0 +1,111 @@
+/**
+ * Who a refused write should be handed to — decided, not executed.
+ *
+ * Nothing in here spawns, connects, reads a file or talks to a model. It takes
+ * the request, the policy as it stands right now, the chain it belongs to and
+ * what the sender and receiver already have running, and returns one decision.
+ * Something else acts on it.
+ *
+ * That split is the whole reason this file exists separately. The rules below
+ * are the security semantics of a handoff, and security semantics that live
+ * inside a function which also does `child_process.spawn` cannot be tested
+ * without starting an agent — so in practice they stop being tested.
+ *
+ * ── The one property everything here serves ──
+ * A model may influence content, which path it reaches for, and therefore the
+ * *demand* for work. It may not determine authority, routing identity,
+ * admission or policy. Every input below is either derived from the boundary
+ * or supplied by the caller; none of them is a role name a model chose.
+ */
+import { ownersOf } from "./owners.js";
+
+/** Small on purpose: a fuse for a topology nobody predicted, not a budget. */
+export const MAX_DEPTH = 4;
+
+/**
+ * Ownership is recomputed here, and the stored `owners` on the request is not
+ * consulted at all.
+ *
+ * A request carries the owners as they were when the denial happened. Between
+ * then and now a person may have changed the policy — that is the entire point
+ * of the queue. The stored value is historical evidence; the authority is the
+ * policy in front of us.
+ */
+export function decideHandoff({
+  request,
+  config,
+  chain = null,
+  limits = {},
+  load = {},
+  revision = null,
+}) {
+  if (!request || !request.role || !request.target)
+    throw new Error("decideHandoff: request needs at least { role, target }");
+  if (!config || !config.roles) throw new Error("decideHandoff: config needs roles");
+
+  const depthMax = limits.depth ?? MAX_DEPTH;
+  const visited = chain?.visited ?? [request.role];
+  const depth = chain?.depth ?? 0;
+  const at = (type, extra = {}) => ({ type, revision, chainId: chain?.id ?? null, ...extra });
+
+  const owners = ownersOf(config, request.target);
+
+  /**
+   * Authority first, admission second, and the order is not cosmetic.
+   *
+   * The two outcomes below start no worker at all, so they must not be able to
+   * be turned into a throttle or a cycle report by load or by chain shape. A
+   * request whose target nobody owns is a hole in the policy whichever way the
+   * budget happens to be sitting, and one that the asker now owns is finished.
+   * Reporting either as CYCLE or THROTTLED would send a person to look at the
+   * wrong thing.
+   */
+  if (owners.length === 0) return at("human", { reason: "unowned", owners });
+  if (owners.length > 1) return at("human", { reason: "ambiguous", owners });
+
+  const [owner] = owners;
+
+  /**
+   * The policy moved and the asker owns it now. Nobody granted anything, so
+   * this is not `granted` — it is a request that stopped existing, and saying
+   * so is what keeps the human queue readable. Sending this to a person would
+   * be asking them to decide something already decided.
+   */
+  if (owner === request.role)
+    return at("resolved", { resolution: "policy_changed", role: owner });
+
+  /**
+   * A role already in this chain does not get re-entered, even for a different
+   * file. Work that crosses a boundary and needs to come back has stopped being
+   * a handoff and become multi-role coordination; that is a decomposition a
+   * person should make on purpose.
+   */
+  if (visited.includes(owner))
+    return at("cycle", { role: owner, visited: [...visited] });
+
+  if (depth + 1 > depthMax)
+    return at("depth", { role: owner, depth: depth + 1, max: depthMax });
+
+  /**
+   * Bounded invocation. A role cannot write another role's territory, but it
+   * can *reach for* it as often as it likes, and each refusal is a way to make
+   * another role run. Filesystem authority was already closed; this closes
+   * cross-role invocation, which is a separate resource.
+   *
+   * Throttling is never silent: the decision says which limit stopped it, so a
+   * queue can show work that is waiting rather than let it evaporate.
+   */
+  const senderMax = limits.senderChains ?? Infinity;
+  if ((load.senderOpenChains ?? 0) >= senderMax)
+    return at("throttled", { role: owner, limit: "senderChains", max: senderMax });
+
+  const receiverMax = limits.receiverConcurrent ?? Infinity;
+  if ((load.receiverRunning ?? 0) >= receiverMax)
+    return at("throttled", { role: owner, limit: "receiverConcurrent", max: receiverMax });
+
+  return at("route", {
+    role: owner,
+    depth: depth + 1,
+    visited: [...visited, owner],
+  });
+}

package/src/hook.js

@@ -0,0 +1,195 @@
+/**
+ * The PreToolUse hook: the only place that can see an attempt.
+ *
+ * The kernel is silent by design. When the sandbox refuses a write, all that
+ * reaches anyone is the operating system's `Operation not permitted` on the
+ * child's stderr — no path, no reason, and nothing to read afterwards. That is
+ * correct behaviour for an enforcer and useless as an instrument.
+ *
+ * A hook runs one layer up. It sees the path *before* the attempt, which means
+ * it can do the two things the kernel cannot: write down what was tried, and
+ * say whose file it was.
+ *
+ * ── Why this file is allowed to be imperfect ──
+ * It reads a Bash command with regular expressions, and a determined command
+ * can hide its target from that. That would be a fatal flaw in an enforcer and
+ * is a minor one here, because the enforcer is the kernel and it is not fooled.
+ * What escapes this file goes unexplained, not unblocked.
+ */
+import { explain, normalize } from "./owners.js";
+import { append, logPath } from "./log.js";
+import { record, requestsPath } from "./requests.js";
+
+/** Tools whose input names a file directly. */
+const FILE_TOOLS = {
+  Write: "write", Edit: "write", MultiEdit: "write", NotebookEdit: "write",
+  Read: "read", NotebookRead: "read",
+};
+
+/**
+ * Paths a shell command is going to write.
+ *
+ * Redirections and the handful of commands whose job is to put bytes
+ * somewhere. Deliberately not exhaustive — see the note at the top about what
+ * this file is for.
+ */
+const REDIRECT = /(?:^|\s|;|&&|\|\|)>{1,2}\s*("[^"]+"|'[^']+'|[^\s;|&<>]+)/g;
+const WRITERS = /(?:^|\s|;|&&|\|\|)(?:cp|mv|install|tee|touch|mkdir|rm|rmdir|truncate|dd)\s+([^\n;|&]+)/g;
+
+export function targetsOf(tool, input = {}) {
+  const kind = FILE_TOOLS[tool];
+  if (kind) {
+    const p = input.file_path ?? input.path ?? input.notebook_path;
+    return p ? [{ action: kind, path: p }] : [];
+  }
+  if (tool !== "Bash" || typeof input.command !== "string") return [];
+
+  const out = [];
+  const seen = new Set();
+  const add = (raw) => {
+    const p = String(raw).replace(/^["']|["']$/g, "");
+    if (!p || p.startsWith("-") || seen.has(p)) return;
+    if (!looksLikeAPath(p)) return;
+    seen.add(p);
+    out.push({ action: "write", path: p });
+  };
+
+  for (const m of input.command.matchAll(REDIRECT)) add(m[1]);
+  for (const m of input.command.matchAll(WRITERS)) {
+    for (const arg of m[1].split(/\s+/)) if (!arg.startsWith("-")) add(arg);
+  }
+  return out;
+}
+
+/**
+ * Is this a filename, or shell debris?
+ *
+ * Reading a command with regular expressions picks up things that are not
+ * paths: a stray `2>`, the word `test` out of `[ -w x ] && test ...`, a device
+ * node. Each one becomes a line in the log that says a role was denied
+ * something it never asked for, and a log with fabricated entries in it stops
+ * being read. Better to explain less and be believed.
+ */
+const SHELL_NOISE = new Set(["test", "true", "false", "then", "else", "fi", "do", "done", "&&", "||", ";"]);
+
+function looksLikeAPath(p) {
+  if (SHELL_NOISE.has(p)) return false;
+  if (/^\d*[<>&|]/.test(p)) return false;              // 2>, >&1, |
+  if (p.startsWith("/dev/")) return false;              // /dev/null and friends
+  if (!/[/.]/.test(p) && !/^[.\w-]+$/.test(p)) return false;
+  return /[/.]/.test(p) || p.length > 2;
+}
+
+/** A path inside a declared key directory is a key, and reads of it are policy. */
+/**
+ * Is this path inside a declared key directory?
+ *
+ * By prefix, not by `includes`. The loose version matched a key directory's
+ * name anywhere in the path, so `src/web/.secrets/readme.md` was treated as a
+ * credential — denied with a message about keys, for a file that is nothing of
+ * the sort. Wrong in the harmless direction, and still wrong: the reason a
+ * denial gives is the entire product.
+ */
+function kindOf(config, path) {
+  const p = normalize(path);
+  return (config.keyDirs ?? []).some((d) => {
+    const k = normalize(d);
+    return p === k || p.startsWith(k + "/");
+  })
+    ? "key"
+    : "file";
+}
+
+/**
+ * The half of the refusal that nothing inside the box could otherwise know.
+ *
+ * `ask()` has already filed a request by the time this sentence is built — and
+ * until now it did so silently, so an agent could not tell the person who sent
+ * it that anything was pending. It closes two loops the bare refusal leaves
+ * open: retrying, because the queue deduplicates and a second attempt only
+ * raises a counter; and waiting, because nothing inside the sandbox can
+ * approve.
+ *
+ * It deliberately says nothing about the MCP server. The hook cannot know
+ * whether one is configured — `wire` writes `.claude/settings.json` and MCP
+ * servers live elsewhere — and naming a tool the agent may not hold costs it a
+ * turn to find out. An agent that does hold the tools discovers them the normal
+ * way; that is what their descriptions are for.
+ */
+const QUEUED = "Already queued for a person to answer — retrying or waiting will not move it.";
+
+/**
+ * Decides and records one tool call.
+ *
+ * `observe` is the mode that makes the whole thing usable: it records exactly
+ * the same decisions and returns none of them, so a policy can be written from
+ * what a real run did instead of from what someone imagined it would do.
+ */
+export function decide(config, role, event, { observe = false, now = append, ask = record } = {}) {
+  const targets = targetsOf(event.tool_name, event.tool_input);
+  const file = logPath(config.root);
+  const queue = requestsPath(config.root);
+  const verdicts = [];
+
+  for (const t of targets) {
+    const rel = t.path.startsWith(config.root + "/") ? t.path.slice(config.root.length + 1) : t.path;
+    const kind = kindOf(config, rel);
+
+    // Reading an ordinary file is never a policy question. Territory divides
+    // who may CHANGE something; an agent that cannot read the rest of the repo
+    // cannot do the work at all. Only keys are scoped on read.
+    //
+    // This was wrong once and it was not subtle: the hook denied a plain Read
+    // of a markdown file, the agent burned its turns unable to look at what it
+    // had been asked to edit, and the log showed a tidy `denied` that looked
+    // like the system working.
+    if (t.action === "read" && kind !== "key") continue;
+
+    const v = explain(config, role, kind === "key" ? "read" : "write", rel);
+
+    now(file, {
+      role,
+      tool: event.tool_name,
+      action: t.action,
+      kind,
+      target: rel,
+      verdict: observe ? "observed" : v.allowed ? "allowed" : "denied",
+      owners: v.owners ?? [],
+      reason: v.reason,
+    });
+    // A denial already carries everything a request needs, so leave one behind:
+    // the refusal stops being a dead end and becomes something a person can act
+    // on in one command. Observing records nothing to approve — there was no
+    // denial to answer. See docs/permission-requests.md.
+    if (!observe && !v.allowed)
+      ask(queue, { role, action: kind === "key" ? "read" : t.action, target: rel, owners: v.owners ?? [] });
+
+    verdicts.push({ ...v, target: rel, kind });
+  }
+
+  if (observe) return { decision: null, logged: verdicts.length };
+
+  const denied = verdicts.find((v) => !v.allowed);
+  if (!denied) return { decision: null, logged: verdicts.length };
+  const wasRead = denied.kind === "key";
+
+  // The hook advises; it does not enforce. Returning `deny` here stops the call
+  // early and — the part that matters — hands the agent a sentence it can act
+  // on, instead of an errno it can only retry.
+  return {
+    decision: "deny",
+    logged: verdicts.length,
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason:
+        // The sentence has to name a next step, not just a refusal. An agent
+        // told "no" retries; an agent told whose it is asks, or moves on.
+        (denied.owners?.length
+          ? wasRead
+            ? `${denied.target} is declared for ${denied.owners.join(", ")}, not ${role}. Ask for what you need from it rather than reading the key.`
+            : `${denied.target} belongs to ${denied.owners.join(", ")}. It is not ${role}'s to change — hand it over rather than working around it.`
+          : `${denied.reason} (seisin)`) + " " + QUEUED,
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,52 @@
+/**
+ * The public surface. Everything not re-exported here is internal and may move.
+ *
+ * Drawing this line is the point of the file. Without it every function in
+ * `src/` is de facto public, which means either nothing can be refactored or
+ * somebody's build breaks when it is. The rule applied below: a thing is public
+ * if you would need it to make a decision — what is allowed, who owns a path,
+ * what the policy resolves to. Rendering, dispatch and process handling are not.
+ *
+ *   import { loadConfig, explain } from "seisin";
+ *
+ * The CLI is the other entry point and uses exactly the same functions.
+ */
+
+/** Reading and validating a policy file. */
+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";
+
+/** A policy, resolved into sandbox settings and a child environment. */
+export { settingsFor, RUNTIME_WRITES, expand } from "./srt.js";
+export { buildEnv, BASE as BASE_ENV } from "./env.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";
+
+/** 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.
+ *
+ * `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
+ * the surface should make that hard to get wrong rather than merely document
+ * it. See docs/permission-requests.md.
+ */
+export { pending as pendingRequests, requestsPath, grantFor } from "./requests.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";