seisin 0.1.0

package/src/mcp.js

@@ -0,0 +1,290 @@
+/**
+ * An MCP server over stdio. Read-only, by construction.
+ *
+ * The point of it: configuring a permission tool by hand-editing a config is
+ * the reason permission tools get abandoned. Asking your own assistant "who
+ * owns src/api, and what is frontend waiting on?" is the version of that people
+ * actually do.
+ *
+ * ── What it cannot do, and how that is enforced ──
+ * There is no tool here that changes anything. Not the policy, not the queue,
+ * not a proposal file — nothing on disk is opened for writing by this process.
+ * `seisin_draft_grant` returns text for a human to read and a command for them
+ * to run; it does not stage a file, because a staged file is one `mv` away from
+ * being policy and the whole invariant is that the last step belongs to a
+ * person in a channel the agent does not have.
+ *
+ * If granting were a tool here, an agent holding it could widen its own
+ * territory and the record would say a human did it. See
+ * `docs/permission-requests.md`.
+ *
+ * ── Why there is no SDK ──
+ * The official SDK pulls 91 packages and 26 MB — express, hono, cors, jose —
+ * (counted against 1.30.0; it was 94 a version ago, which is the point)
+ * for a server that speaks line-delimited JSON on two file descriptors. In a
+ * tool people install to reduce their attack surface, that is the wrong trade.
+ * The cost of this choice is written down under PROTOCOLS below: we track the
+ * spec by hand, and the spec moves.
+ */
+import { loadConfig, findConfig } from "./config.js";
+import { inspect } from "./inspect.js";
+import { explain, ownersOf } from "./owners.js";
+import { settingsFor } from "./srt.js";
+import { pending, requestsPath, grantFor } from "./requests.js";
+import { read, logPath } from "./log.js";
+
+/**
+ * Versions this server will agree to.
+ *
+ * Negotiation is "echo what the client asked for if we know it, otherwise offer
+ * our newest". The 2026-07-28 revision made the core stateless and moved the
+ * handshake into `_meta`, but for a stdio server exposing four read-only tools
+ * the wire shape of `tools/list` and `tools/call` is unchanged — which is the
+ * only reason hand-rolling this is defensible. If that stops being true, this
+ * list is where it will show up first.
+ */
+const PROTOCOLS = ["2026-07-28", "2025-11-25", "2025-06-18"];
+const NEWEST = PROTOCOLS[0];
+
+const TOOLS = [
+  {
+    name: "seisin_state",
+    description:
+      "The permission map: every role, the folders it may write, the keys it may read, " +
+      "and every way the policy silently does not hold. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: { role: { type: "string", description: "narrow to one role" } },
+    },
+  },
+  {
+    name: "seisin_explain",
+    description:
+      "Whether a role may read or write a path, and whose it is if not. " +
+      "Use this before suggesting an agent touch a file. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        role: { type: "string" },
+        action: { type: "string", enum: ["read", "write"] },
+        target: { type: "string", description: "path, or key filename for a read" },
+      },
+      required: ["role", "action", "target"],
+    },
+  },
+  {
+    name: "seisin_requests",
+    description:
+      "Permissions agents asked for and cannot have yet, waiting on a human, with how many " +
+      "times each was asked. A refusal files one of these automatically, so this is where " +
+      "to look after being denied rather than retrying. Read-only — approving is not " +
+      "available here, by design.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "seisin_activity",
+    description: "Recent allow/deny decisions, newest last. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        role: { type: "string" },
+        verdict: { type: "string", enum: ["allowed", "denied", "observed"] },
+        limit: { type: "number" },
+      },
+    },
+  },
+  {
+    name: "seisin_draft_grant",
+    description:
+      "Draft the change a pending request would make, as text, plus the command a person " +
+      "runs to apply it. Reach for this after a refusal: the denial is already in " +
+      "seisin_requests, and this turns it into a concrete proposal someone can approve. " +
+      "Writes nothing: the approval is a human action in another channel.",
+    inputSchema: {
+      type: "object",
+      properties: { number: { type: "number", description: "position in seisin_requests" } },
+      required: ["number"],
+    },
+  },
+];
+
+/* ── the tools ────────────────────────────────────────────────────────── */
+
+function config() {
+  const path = findConfig();
+  if (!path) throw new Error('no seisin.toml found. Run "seisin init" in the repo first.');
+  return loadConfig(path);
+}
+
+const HANDLERS = {
+  seisin_state({ role }) {
+    const cfg = config();
+    const report = inspect(cfg, role ?? null, cfg.path);
+    return {
+      config: cfg.path,
+      keyDirectories: cfg.keyDirs,
+      roles: report.roles.map((r) => ({
+        ...r,
+        sandbox: settingsFor(cfg, r.name).filesystem,
+      })),
+      warnings: report.warnings,
+      // The blank parts of the map travel with it. A model that can see the
+      // policy and not its limits will confidently tell someone a file is safe.
+      limits: report.limits,
+    };
+  },
+
+  seisin_explain({ role, action, target }) {
+    // The schema says enum: [read, write]. Nothing was checking, so anything
+    // that was not "read" fell into the write branch — including a typo, which
+    // would answer the wrong question confidently. A declared schema that is
+    // not enforced is documentation.
+    if (action !== "read" && action !== "write")
+      throw new Error(`action must be "read" or "write", got ${JSON.stringify(action)}`);
+    if (typeof target !== "string" || !target)
+      throw new Error("target must be a non-empty path");
+    const cfg = config();
+    if (!cfg.roles[role])
+      return { error: `unknown role "${role}"`, known: Object.keys(cfg.roles) };
+    const verdict = explain(cfg, role, action, target);
+    return { ...verdict, alsoOwnedBy: action === "write" ? ownersOf(cfg, target) : undefined };
+  },
+
+  seisin_requests() {
+    const cfg = config();
+    const queue = pending(requestsPath(cfg.root));
+    return {
+      pending: queue.map((r, i) => ({
+        number: i + 1, role: r.role, action: r.action,
+        wants: r.grant, ownedBy: r.owners, asked: r.times, lastAsked: r.last,
+      })),
+      // Said in the payload and not only in the tool description, because a
+      // model reading this is deciding what to do next.
+      note: queue.length
+        ? "Approving is not available through MCP. Tell the operator to run: seisin grant <number>"
+        : "nothing waiting",
+    };
+  },
+
+  seisin_activity({ role, verdict, limit }) {
+    if (verdict !== undefined && !["allowed", "denied", "observed"].includes(verdict))
+      throw new Error(`verdict must be allowed, denied or observed, got ${JSON.stringify(verdict)}`);
+    const n = limit === undefined ? 30 : Number(limit);
+    if (!Number.isInteger(n) || n < 1 || n > 1000) throw new Error("limit must be 1..1000");
+    const cfg = config();
+    return { entries: read(logPath(cfg.root), { role, verdict, limit: n }) };
+  },
+
+  seisin_draft_grant({ number }) {
+    if (!Number.isInteger(Number(number)) || Number(number) < 1)
+      throw new Error("number must be a positive integer from seisin_requests");
+    const cfg = config();
+    const req = pending(requestsPath(cfg.root))[Number(number) - 1];
+    if (!req) throw new Error(`no pending request #${number}`);
+
+    const field = req.action === "read" ? "keys" : "writes";
+    return {
+      wouldAdd: { role: req.role, field, value: req.grant },
+      preview: `[roles.${req.role}]\n${field} = [ …, "${req.grant}" ]   # asked ${req.times}×`,
+      ownedBy: req.owners,
+      applyWith: `seisin grant ${number} --reason "<why>"`,
+      note: "Not applied. seisin's MCP server writes nothing — a person runs the command above.",
+    };
+  },
+};
+
+/* ── the wire ─────────────────────────────────────────────────────────── */
+
+/**
+ * One session's state: where to write, and what version to claim.
+ *
+ * Injected rather than read from the process, because a server that writes to a
+ * global cannot be exercised without patching the process it runs in — and a
+ * test that patches `process.stdout` also captures the test runner's own
+ * output, which is how these tests failed the first time they were written.
+ */
+function handle(message, { write, version }) {
+  const send = (m) => write(JSON.stringify(m) + "\n");
+  const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, msg) => send({ jsonrpc: "2.0", id, error: { code, message: msg } });
+
+  const { id, method, params = {} } = message;
+
+  // A notification has no id and takes no answer. Replying to one is a protocol
+  // error that some clients tolerate and others hang on.
+  if (id === undefined) return;
+
+  switch (method) {
+    case "initialize": {
+      const asked = params.protocolVersion;
+      return reply(id, {
+        protocolVersion: PROTOCOLS.includes(asked) ? asked : NEWEST,
+        capabilities: { tools: {} },
+        serverInfo: { name: "seisin", title: "seisin — folders and keys per agent", version },
+        instructions:
+          "Read-only view of this repo's agent permissions. Ask seisin_explain before " +
+          "suggesting an agent edit a file it may not own. Granting is not available " +
+          "here: surface seisin_requests and let the operator run `seisin grant`.",
+      });
+    }
+    case "ping":
+      return reply(id, {});
+    case "server/discover":            // 2026-07-28 clients ask up front
+      return reply(id, { capabilities: { tools: {} }, tools: TOOLS });
+    case "tools/list":
+      return reply(id, { tools: TOOLS });
+    case "tools/call": {
+      const fn = HANDLERS[params.name];
+      if (!fn) return fail(id, -32602, `unknown tool "${params.name}"`);
+      try {
+        const result = fn(params.arguments ?? {});
+        // Content, not a bare object: every client renders `content`, and only
+        // some read `structuredContent`. Both are sent.
+        return reply(id, {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          structuredContent: result,
+        });
+      } catch (e) {
+        // A failing tool is an error the model should see and work around, not
+        // a transport error that kills the session.
+        return reply(id, { content: [{ type: "text", text: `seisin: ${e.message}` }], isError: true });
+      }
+    }
+    default:
+      return fail(id, -32601, `method not found: ${method}`);
+  }
+}
+
+/** Reads line-delimited JSON-RPC until the input closes. */
+export function serveMcp(version = "0.0.0", input = process.stdin, output = process.stdout) {
+  const ctx = { version, write: (s) => output.write(s) };
+  input.setEncoding("utf8");
+  let buffer = "";
+
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    // A megabyte with no newline in it is not a JSON-RPC message, it is a
+    // client — or something wearing one — filling this process's memory.
+    // spool.js already caps its input; this one did not.
+    if (buffer.length > 1_000_000) {
+      buffer = "";
+      return;
+    }
+    let nl;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      try {
+        handle(JSON.parse(line), ctx);
+      } catch {
+        // Unparseable input has no id to answer to, so there is nobody to tell.
+        // Staying alive is the only useful response.
+      }
+    }
+  });
+
+  return new Promise((done) => input.on("end", done));
+}
+
+export { TOOLS, HANDLERS, PROTOCOLS };

package/src/owners.js

@@ -0,0 +1,166 @@
+/**
+ * Who owns a path.
+ *
+ * This is the part no other agent-permission tool has, and it is why seisin
+ * exists. Every hook and sandbox in this space answers yes or no. Answering
+ * "no, and it belongs to `frontend`" turns a block into a handoff: the agent
+ * knows who to ask, and so do you when you read the log.
+ *
+ * Owning means being allowed to WRITE it. Reads are not partitioned by owner —
+ * agents have to read each other's code to do anything useful. Keys are the
+ * exception, and they are handled separately below.
+ */
+
+/**
+ * Does this glob cover this path? Supports `**`, `*`, `?` and a trailing `/`.
+ *
+ * A wildcard-free pattern is a **prefix**, because that is what the kernel is
+ * given. `toWritePath` in srt.js hands `src/api` to `allowWrite` unchanged, and
+ * a sandbox grants a path and everything under it — so `src/api`, `src/api/`
+ * and `src/api/**` are one grant to the OS, and reading the first of them as
+ * "that path only" made seisin describe a boundary that was not there.
+ *
+ * Measured against the real kernel, not reasoned about. With
+ * `writes = ["src/api"]`:
+ *
+ *     seisin explain dev write src/api/x.ts   ->  denied, "has no owner"
+ *     seisin run dev -- sh -c 'echo > src/api/x.ts'  ->  the file is written
+ *
+ * That is the document being tighter than the boundary, which
+ * [decisions.md](../docs/decisions.md) names as the one direction this must
+ * never fail in — and it is worse than the `src/*` case already recorded there,
+ * because nothing looked wrong: `whose` reported the path as unowned while a
+ * role could write it, so a reader was told it was protected.
+ *
+ * Refusing is not the answer here the way it was for `src/*`. "One level down"
+ * has no exact translation and had to be refused; a subtree has one, and the
+ * kernel is already enforcing it. What was missing was seisin saying so.
+ */
+export function covers(glob, path) {
+  const p = normalize(path);
+  let g = normalize(glob);
+  if (glob.endsWith("/")) g += "/**";
+  // The path itself, or anything beneath it. The `/` is load-bearing: without
+  // it `src/api` would also cover `src/apifoo.ts`, which the kernel does not.
+  if (!WILD.test(g)) return p === g || p.startsWith(g + "/");
+  return toRegExp(g).test(p);
+}
+
+/** The four characters toRegExp() treats as wildcards. */
+const WILD = /[*?[\]]/;
+
+/**
+ * One spelling per file, before anybody decides anything about it.
+ *
+ * `..` is the reason this is more than tidying. `src/web/../api/orders.ts` is
+ * backend's file, and the unresolved form let it match frontend's `src/web/**`
+ * — so `whose` named the wrong owner, the hook raised no request, and the log
+ * recorded `allowed` for a write the kernel then refused. The boundary held;
+ * every sentence seisin said about it was wrong, which is the half of the tool
+ * that is actually ours.
+ *
+ * A path that climbs above the repo root comes back as `..`, which owns
+ * nothing and matches nothing. Outside the repo has no owner by definition.
+ */
+export function normalize(s) {
+  const flat = s.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/+$/, "");
+  const up = [];
+  for (const part of flat.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === ".." && up.length && up[up.length - 1] !== "..") { up.pop(); continue; }
+    up.push(part);
+  }
+  return up.join("/");
+}
+
+/**
+ * Glob to RegExp.
+ *
+ * The wildcards are parked on sentinels before `*` is expanded, because
+ * expanding `**` first produces a `.*` whose own `*` the next pass would
+ * rewrite again. Getting that order wrong is silent: the regex still compiles
+ * and quietly matches the wrong set of files.
+ *
+ * `src/api/**` also matches `src/api` itself. Without that, the directory a
+ * role was just granted comes back ownerless, which reads as a bug every time.
+ *
+ * Dotfiles are matched like any other name: `*.env` covers `.env`. Shell globs
+ * hide them by default, and most glob libraries copy that. A permission tool
+ * must not: covering one file too many costs an argument, covering one too few
+ * is the hole. When the two readings disagree, this one takes the wider set.
+ */
+function toRegExp(glob) {
+  const out = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\/\*\*$/, "\u0001")
+    .replace(/\*\*\//g, "\u0002")
+    .replace(/\*\*/g, "\u0003")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, "[^/]")
+    .replace(/\u0001/g, "(?:/.*)?")
+    .replace(/\u0002/g, "(?:.*/)?")
+    .replace(/\u0003/g, ".*");
+  return new RegExp("^" + out + "$");
+}
+
+/** Every role whose territory covers `path`. Usually one; zero is a finding. */
+export function ownersOf(config, path) {
+  return Object.values(config.roles)
+    .filter((r) => r.writes.some((g) => covers(g, path)))
+    .map((r) => r.name);
+}
+
+/** Every role allowed to read `key`, matched with or without its extension. */
+export function keyHolders(config, key) {
+  const dirs = config.keyDirs ?? [];
+
+  /**
+   * Both sides resolved to a path before anything is compared.
+   *
+   * A declaration without a directory means the first key directory — that is
+   * what settingsFor does — and the hook sees whatever path the tool call
+   * used. So `database.txt` in the config and `.secrets/database.txt` from a
+   * Read are the same file and must match.
+   *
+   * What must NOT match is `.secrets/api.txt` against `shared/api.txt`. With
+   * two key directories those are different files, and comparing basenames
+   * made `explain` answer "allowed" for a key the sandbox would refuse. A
+   * wrong yes from the layer whose only job is explaining is worse than no
+   * answer at all.
+   */
+  const resolve = (s) => (s.includes("/") ? s : `${dirs[0] ?? "."}/${s}`);
+  const bare = (s) => s.replace(/^.*\//, "").replace(/\.[^.]+$/, "");
+
+  const wanted = resolve(key);
+  // The extension-less form is how a person asks — `seisin explain f read
+  // netlify` — so it stays, and only for an unqualified question.
+  const loose = !key.includes("/");
+
+  return Object.values(config.roles)
+    .filter((r) => r.keys.some((k) =>
+      resolve(k) === wanted || (loose && bare(k) === bare(key))))
+    .map((r) => r.name);
+}
+
+/**
+ * The sentence a blocked agent should read.
+ *
+ * Three outcomes, and the third is the one worth having: a path nobody owns is
+ * not a permission problem, it is a hole in the map. Saying so is more useful
+ * than denying quietly, and it is the only way the hole ever gets fixed.
+ */
+export function explain(config, role, action, target) {
+  if (action === "read") {
+    const holders = keyHolders(config, target);
+    if (holders.includes(role)) return { allowed: true, owners: holders, reason: `${role} declares ${target}` };
+    if (holders.length === 0)
+      return { allowed: false, owners: [], reason: `no role declares ${target} — add it under a [roles.<name>] keys list` };
+    return { allowed: false, owners: holders, reason: `${target} belongs to ${holders.join(", ")}` };
+  }
+
+  const owners = ownersOf(config, target);
+  if (owners.includes(role)) return { allowed: true, owners, reason: `${target} is inside ${role}'s territory` };
+  if (owners.length === 0)
+    return { allowed: false, owners: [], reason: `${target} has no owner — no role can write it until one claims it` };
+  return { allowed: false, owners, reason: `${target} belongs to ${owners.join(", ")}` };
+}

package/src/redact.js

@@ -0,0 +1,82 @@
+/**
+ * Masks a role's own secrets on their way out of the process.
+ *
+ * The sandbox stops a role from *getting* a key that is not its own. It cannot
+ * stop a role from spilling one it legitimately holds — a `cat` while debugging,
+ * an error message that echoes a header, a token printed into a log that is
+ * three commits from being pushed. That is a different failure and it needs a
+ * different place to stand: the launcher already carries the child's output.
+ *
+ * ── The trade this makes, stated plainly ──
+ * To mask a value, seisin has to read it. So a role's own keys pass through this
+ * process in memory. That is a real cost and it buys the only leak that matters
+ * in practice; if you would rather it not, `[runtime] redact = false`.
+ *
+ * ── And what it cannot catch ──
+ * Only the literal value, and only on stdout and stderr. A key the agent writes
+ * straight to a file never comes through here, and neither does one it has
+ * base64'd. This narrows the blast radius of a careless print. It is not a
+ * containment boundary, and calling it one would be the sort of claim this
+ * README spends its time avoiding.
+ */
+import { Transform } from "node:stream";
+
+/** Reads the values this role may read. Unreadable or huge files are skipped. */
+export function secretsOf(settings, readFile) {
+  const out = [];
+  for (const path of settings.filesystem.allowRead) {
+    let text;
+    try {
+      text = readFile(path, "utf8");
+    } catch {
+      continue; // declared but not on disk yet: nothing to mask
+    }
+    if (text.length > 64 * 1024) continue; // not a credential; do not scan a blob
+    for (const line of text.split(/\r?\n/)) {
+      const value = line.includes("=") ? line.slice(line.indexOf("=") + 1) : line;
+      const v = value.trim().replace(/^["']|["']$/g, "");
+      // Short strings produce false positives that mangle ordinary output.
+      if (v.length >= 8) out.push(v);
+    }
+  }
+  // Longest first, so a value that contains another is masked whole.
+  return [...new Set(out)].sort((a, b) => b.length - a.length);
+}
+
+/**
+ * A stream that replaces each secret with `‹redacted:name›`.
+ *
+ * It carries the tail of each chunk forward, because a value split across a
+ * buffer boundary would otherwise sail through — which is the one case a
+ * naive implementation always gets wrong and never notices.
+ */
+export function redactor(secrets, label = "redacted") {
+  if (secrets.length === 0) return null;
+  const longest = secrets[0].length;
+  let tail = "";
+
+  return new Transform({
+    transform(chunk, _enc, done) {
+      // Mask the WHOLE accumulated text first, then cut. Doing it the other way
+      // — masking only the part about to be emitted — lets a secret that
+      // straddles the cut through in two innocent halves. Written that way
+      // first; the split-buffer test caught it on the first run.
+      const masked = mask(tail + chunk.toString("utf8"), secrets, label);
+      const keep = Math.min(longest - 1, masked.length);
+      this.push(masked.slice(0, masked.length - keep));
+      tail = masked.slice(masked.length - keep);
+      done();
+    },
+    flush(done) {
+      this.push(mask(tail, secrets, label));
+      tail = "";
+      done();
+    },
+  });
+}
+
+function mask(text, secrets, label) {
+  let out = text;
+  for (const s of secrets) out = out.split(s).join(`‹${label}›`);
+  return out;
+}