seisin 0.1.0

package/src/scan.js

@@ -0,0 +1,175 @@
+/**
+ * Finds credential-shaped content that is NOT under a declared key directory.
+ *
+ * seisin scopes what a role may read from the directories you named. Every
+ * secret living somewhere else is readable by every role, because reads outside
+ * the denied paths stay open — an agent has to be able to read the repo.
+ *
+ * So the honest completion of "seisin protects your keys" is a command that
+ * says which keys it is not protecting. This is that command. It reports and
+ * never edits: moving a credential breaks whatever reads it today, and that is
+ * a decision, not a cleanup.
+ *
+ * ── Why this file is mostly about precision ──
+ * The first version was run against a real 18,000-file tree and returned 200
+ * findings, of which 5 had a specific shape and 2 were actual credentials. A
+ * scanner at that ratio does not get read a second time, which makes it worse
+ * than no scanner: it converts a real risk into a wall of noise someone learns
+ * to skip. Three things were wrong and all three are handled below.
+ */
+import { readdirSync, readFileSync, statSync, realpathSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { covers } from "./owners.js";
+
+/**
+ * A match is `certain` when the shape alone is enough — these strings are
+ * issued by a provider and do not occur by accident. It is `review` when the
+ * shape only says "this line talks about a secret", which is true of a great
+ * deal of ordinary code.
+ *
+ * The split is the point. Mixing them produces one list nobody triages; keeping
+ * them apart lets `certain` be the thing that fails a build.
+ */
+export const SHAPES = [
+  ["certain", "private key block", /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/],
+  ["certain", "Anthropic/OpenAI key", /\bsk-[A-Za-z0-9_-]{20,}/],
+  ["certain", "GitHub token", /\bgh[pousr]_[A-Za-z0-9]{20,}/],
+  ["certain", "AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
+  ["certain", "Google API key", /\bAIza[0-9A-Za-z_-]{30,}/],
+  ["certain", "Slack token", /\bxox[abposr]-[A-Za-z0-9-]{10,}/],
+  ["certain", "Stripe live key", /\b[sr]k_live_[A-Za-z0-9]{20,}/],
+  ["certain", "JSON Web Token", /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/],
+  ["review", "assigned secret", /\b[A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY)[A-Z0-9_]*\s*[=:]\s*["']?([^\s"'#,;)]{12,})/i],
+];
+
+/**
+ * The value is code, not a secret.
+ *
+ * `TOKEN = os.environ["TOKEN"]` matches every naive secret pattern ever
+ * written, and it is the single most common line in any codebase that handles
+ * secrets *correctly*. Measured on the real tree: 46 of 159 loose findings were
+ * exactly this — the scanner was flagging the good practice.
+ */
+const REFERENCE = /(os\.environ|process\.env|import\.meta\.env|getenv|ENV\[|Deno\.env|config\(|settings\.|secrets\.|\$\{|\$\(|%\(|\{\{|<%|%s|%d|\.get\(|request\.|req\.|headers\[|params\[|argv|prompt\(|input\()/i;
+
+/** Values that are obviously not secrets, however secret-shaped the name is. */
+const PLACEHOLDER = /^(?:changeme|change_me|xxx+|your[-_a-z]*|example|placeholder|dummy|sample|redacted|null|none|true|false|test|todo|fixme|\.{3}|-+|\*+)$/i;
+
+/**
+ * Paths skipped by default.
+ *
+ * Two kinds, and both were learned the same way. Machinery nobody wrote
+ * (`node_modules`, `dist`) has always been obvious. What was not: caches of
+ * pages fetched from other people's sites, and `.bak` copies of a config, which
+ * between them produced most of the noise in the first real run — the same
+ * finding repeated five times, and three keys belonging to a company that is
+ * not the one running the scan.
+ */
+export const DEFAULT_IGNORE = [
+  "**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**", "**/.next/**",
+  "**/vendor/**", "**/__pycache__/**", "**/.venv/**", "**/venv/**", "**/coverage/**",
+  "**/_cache/**", "**/.cache/**", "**/.angular/**", "**/.parcel-cache/**",
+  "**/.turbo/**", "**/.nuxt/**", "**/target/**", "**/out/**",
+  "**/*.bak", "**/*.bak-*", "**/*.orig",
+  "**/*.min.js", "**/*.min.css", "**/*-lock.json", "**/*.lock",
+];
+
+const SKIP_EXT = /\.(png|jpe?g|gif|webp|ico|svg|pdf|zip|gz|tgz|bz2|xz|mp[34]|mov|wav|woff2?|ttf|otf|eot|so|dylib|a|o|class|jar|wasm|sqlite3?|db)$/i;
+const MAX_BYTES = 512 * 1024;
+// Written as an escape, not as the byte itself. A literal NUL in the source
+// makes git classify this file as binary, and a file with no readable diff
+// cannot be reviewed — in a repo whose whole argument is that you should read
+// it before you trust it. Same value at runtime, same test.
+const NUL = "\u0000";
+
+/**
+ * Walks `root` and returns [{file, line, shape, level}].
+ *
+ * `protectedDirs` are the declared key directories: a hit inside one is the
+ * system working, not a finding. `ignore` adds to DEFAULT_IGNORE rather than
+ * replacing it, so a user's list stays short.
+ */
+export function scan(root, protectedDirs = [], ignore = [], limit = 500) {
+  const safe = protectedDirs.map((d) => join(root, d));
+  const patterns = [...DEFAULT_IGNORE, ...ignore];
+  const hits = [];
+  const skipped = { ignored: 0, protectedDirs: 0, reference: 0, placeholder: 0 };
+
+  const isIgnored = (rel) => patterns.some((p) => covers(p, rel));
+
+  (function walk(dir) {
+    if (hits.length >= limit) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return; // an unreadable directory is a permission, not a finding
+    }
+    for (const e of entries) {
+      if (hits.length >= limit) return;
+      const full = join(dir, e.name);
+      const rel = relative(root, full);
+
+      if (safe.some((s) => full === s || full.startsWith(s + sep))) { skipped.protectedDirs++; continue; }
+      if (isIgnored(rel)) { skipped.ignored++; continue; }
+
+      /**
+       * A symlink pointing out of the repo, reported without being followed.
+       *
+       * `scan` is the command that answers "do I have credentials outside the
+       * declared key directories", and a link is the one way a credential is
+       * present in the tree without being a file in it. It was skipped
+       * silently, because a symlink is not `isFile()` — so `loose-link ->
+       * ~/.ssh/id_rsa` scanned clean.
+       *
+       * The destination is named, not read. Opening it would put whatever is
+       * there into a report that people paste into issues, and the point is
+       * that it exists, not what it says.
+       */
+      if (e.isSymbolicLink()) {
+        let real;
+        try {
+          real = realpathSync(full);
+        } catch {
+          continue;                       // a broken link has nothing to leak
+        }
+        if (!real.startsWith(root + sep) && real !== root)
+          hits.push({
+            file: rel, line: 0, level: "link", shape: real,
+          });
+        continue;
+      }
+
+      if (e.isDirectory()) { walk(full); continue; }
+      if (!e.isFile() || SKIP_EXT.test(e.name)) continue;
+
+      let text;
+      try {
+        if (statSync(full).size > MAX_BYTES) continue;
+        text = readFileSync(full, "utf8");
+      } catch {
+        continue;
+      }
+      if (text.includes(NUL)) continue; // binary
+
+      const lines = text.split(/\r?\n/);
+      for (let i = 0; i < lines.length && hits.length < limit; i++) {
+        const line = lines[i];
+        for (const [level, shape, re] of SHAPES) {
+          const m = re.exec(line);
+          if (!m) continue;
+          if (level === "review") {
+            // A captured value that is code, or that is plainly a stand-in, is
+            // the pattern working correctly on a line that holds no secret.
+            if (REFERENCE.test(line)) { skipped.reference++; break; }
+            if (m[1] && PLACEHOLDER.test(m[1])) { skipped.placeholder++; break; }
+          }
+          hits.push({ file: rel, line: i + 1, shape, level });
+          break; // one finding per line; the first shape is the most specific
+        }
+      }
+    }
+  })(root);
+
+  return { hits, skipped, truncated: hits.length >= limit };
+}

package/src/serve.js

@@ -0,0 +1,168 @@
+/**
+ * A local server for the console, and the one place seisin keeps a process alive.
+ *
+ * Everything else here is a launcher: it runs, it exits, there is no state to
+ * corrupt and nothing to restart. That property is worth protecting, so this is
+ * scoped hard — the server is a **foreground command you start and stop**, it
+ * serves one page and one JSON document, and nothing in the enforcement path
+ * touches it. If it is not running, seisin loses a window, not a boundary.
+ *
+ * It binds to loopback only, and that is not decoration: the page shows which
+ * key each role can read, which is a map of where the credentials live.
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.js";
+import { read, logPath } from "./log.js";
+import { settingsFor } from "./srt.js";
+import { pending, requestsPath, settle, applyGrant } from "./requests.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Everything the page needs, read fresh on each request.
+ *
+ * Read fresh rather than cached because the file on disk is the truth and the
+ * page is a view of it — someone editing seisin.toml in an editor should see
+ * the console change, not wonder why it disagrees.
+ */
+function state(configPath) {
+  const cfg = loadConfig(configPath);
+  const entries = read(logPath(cfg.root), { limit: 200 });
+
+  const roles = Object.values(cfg.roles).map((r) => ({
+    name: r.name,
+    writes: r.writes,
+    keys: r.keys,
+    env: r.env,
+    blocks: entries.filter((e) => e.role === r.name && e.verdict === "denied").length,
+    settings: settingsFor(cfg, r.name),
+  }));
+
+  return {
+    root: cfg.root,
+    config: cfg.path,
+    requests: pending(requestsPath(cfg.root)),
+    // The file itself, not a regeneration of it. The page can render a policy
+    // from its own model, and that model has no comments — so showing it under
+    // the heading "seisin.toml" next to "copy this back" invites someone to
+    // paste away the provenance a grant just wrote.
+    toml: readFileSync(cfg.path, "utf8"),
+    keyDirs: cfg.keyDirs,
+    allowedDomains: cfg.allowedDomains,
+    roles,
+    log: entries.slice(-60).reverse(),
+    live: true,
+  };
+}
+
+/**
+ * Approve or refuse one pending request, as a person.
+ *
+ * This is the only thing in seisin that writes policy, and it lives here rather
+ * than in the MCP server for one reason: an agent cannot reach this. Measured,
+ * not assumed — a confined role curling this port gets the same nothing it gets
+ * from a domain outside its allowlist, because the egress proxy does not make
+ * an exception for loopback. That is what lets the console hold the half the
+ * MCP server deliberately does not.
+ */
+function decide(configPath, { number, decision, reason }) {
+  const cfg = loadConfig(configPath);
+  const file = requestsPath(cfg.root);
+  const req = pending(file)[Number(number) - 1];
+  if (!req) throw new Error(`no pending request #${number}`);
+  if (decision !== "granted" && decision !== "denied")
+    throw new Error(`decision must be granted or denied`);
+
+  if (decision === "granted") {
+    // The config is edited as text, so comments and order survive. Written
+    // before the queue is settled: if this throws, the request is still open
+    // rather than marked done against a file that never changed.
+    const { toml, changed } = applyGrant(readFileSync(cfg.path, "utf8"), req, reason);
+    if (changed) writeFileSync(cfg.path, toml);
+  }
+  settle(file, req.key, decision, reason ?? "");
+  return { ok: true, role: req.role, grant: req.grant, decision };
+}
+
+/** The body of a POST, capped: this endpoint takes three short fields. */
+function readBody(req) {
+  return new Promise((ok, fail) => {
+    let s = "";
+    req.on("data", (c) => {
+      s += c;
+      if (s.length > 4096) { fail(new Error("body too large")); req.destroy(); }
+    });
+    req.on("end", () => ok(s));
+  });
+}
+
+export function serve(configPath, port = 4178) {
+  const page = join(HERE, "..", "ui", "index.html");
+  if (!existsSync(page)) throw new Error("the console is missing from this install");
+
+  /**
+   * One secret per run, handed to the page and demanded back on every write.
+   *
+   * Loopback is not a boundary against the browser: any site the operator has
+   * open can POST to 127.0.0.1. It cannot read this token, and asking for it in
+   * a custom header also forces a preflight that this server never answers. So
+   * the page can approve and a tab from somewhere else cannot.
+   */
+  const token = randomBytes(24).toString("hex");
+
+  const server = createServer(async (req, res) => {
+    if (req.method === "POST" && req.url === "/api/decide") {
+      if (req.headers["x-seisin-token"] !== token) {
+        res.writeHead(403, { "content-type": "application/json" });
+        return res.end(JSON.stringify({ error: "bad or missing token" }));
+      }
+      try {
+        const out = decide(configPath, JSON.parse((await readBody(req)) || "{}"));
+        res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+        return res.end(JSON.stringify(out));
+      } catch (e) {
+        res.writeHead(400, { "content-type": "application/json" });
+        return res.end(JSON.stringify({ error: e.message }));
+      }
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(405).end("method not allowed");
+      return;
+    }
+    if (req.url === "/api/state") {
+      let body;
+      try {
+        body = JSON.stringify(state(configPath));
+      } catch (e) {
+        res.writeHead(500, { "content-type": "application/json" });
+        return res.end(JSON.stringify({ error: e.message }));
+      }
+      // The page polls, so tell every cache in between to stay out of it.
+      res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+      return res.end(body);
+    }
+    if (req.url === "/" || req.url === "/index.html") {
+      // Inlined rather than put in the URL: a fragment survives in history, in
+      // a screenshot, and in whatever the operator pastes into a chat.
+      const html = readFileSync(page, "utf8")
+        .replace("</head>", `<script>window.SEISIN_TOKEN=${JSON.stringify(token)}</script></head>`);
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+      return res.end(html);
+    }
+    res.writeHead(404).end("not found");
+  });
+
+  return new Promise((ok, fail) => {
+    // Loopback only. The page maps where every credential lives; it has no
+    // business being reachable from the network the laptop happens to be on.
+    server.listen(port, "127.0.0.1", () => ok(server));
+    server.on("error", (e) =>
+      fail(e.code === "EADDRINUSE"
+        ? new Error(`port ${port} is busy — pass another with: seisin ui --port <n>`)
+        : e));
+  });
+}

package/src/spool.js

@@ -0,0 +1,164 @@
+/**
+ * The audit trail, held by the parent instead of by the thing being audited.
+ *
+ * ── 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
+ * 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
+ * enforced it. An external review named this and was right.
+ *
+ * So the file moves out of reach and a socket takes its place:
+ *
+ *     agent ─X─► .seisin/            (no longer writable)
+ *     hook  ──line──► unix socket ──► seisin run ──append──► .seisin/log.jsonl
+ *
+ * The only verb reachable from inside the sandbox is "send one line". There is
+ * no seek, no truncate, no unlink, because there is no file descriptor — and
+ * `allowUnixSockets` is granted for exactly this one socket path, so it is not
+ * a general hole either.
+ *
+ * ── What this does not fix, stated plainly ──
+ * A hostile agent can still *send* lines, so it can add noise to its own
+ * record. What it can no longer do is erase or alter what is already there.
+ * Forgery and tampering are different problems and only the second one is
+ * solved here; the log is evidence of what happened, not proof that nothing
+ * else did.
+ */
+import { createServer, createConnection } from "node:net";
+import { unlinkSync, existsSync, mkdtempSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+
+/** 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`.
+ *
+ * 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
+ * path, which is the other half of why this is not just a slower file write.
+ */
+export function spool(sink, path = spoolPath()) {
+  if (existsSync(path)) unlinkSync(path);
+
+  const server = createServer((conn) => {
+    let buffer = "";
+    conn.setEncoding("utf8");
+    conn.on("data", (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) return conn.destroy();
+      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.
+        }
+      }
+    });
+    conn.on("error", () => {});
+  });
+
+  /**
+   * A failed `listen` has to reject, and it used to do nothing at all.
+   *
+   * The error handler swallowed everything and the promise only ever settled
+   * from the `listen` callback, so any failure to bind — a denied path, a name
+   * 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
+   * 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.
+   *
+   * After a successful bind the handler goes back to swallowing, because by
+   * then an error belongs to one connection and must not take down the run
+   * that the audit trail is only observing.
+   */
+  return new Promise((ok, fail) => {
+    server.once("error", fail);
+    server.listen(path, () => {
+      server.removeListener("error", fail);
+      server.on("error", () => {});
+      ok({
+      path,
+      close() {
+        server.close();
+        // Only the socket. The first version removed `dirname(path)` too,
+        // reasoning that spoolPath() 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.
+        try { unlinkSync(path); } catch {}
+      },
+      });
+    });
+  });
+}
+
+/**
+ * Sends one entry to the parent, if there is one listening.
+ *
+ * Returns a promise and registers it, because the hook is a short-lived
+ * process whose last act is `process.exit` — and an exit does not wait for a
+ * socket to drain. The write would be lost exactly when it matters, silently,
+ * which is the shape of the original bug this file replaces. `flush()` is what
+ * the hook awaits before it answers.
+ */
+const inFlight = new Set();
+
+export function send(to, entry, path = process.env[SOCK_ENV]) {
+  if (!path) return false;
+  const p = new Promise((done) => {
+    let settled = false;
+    const finish = () => { if (!settled) { settled = true; done(true); } };
+    try {
+      const conn = createConnection(path);
+      // Never hang the agent's turn on bookkeeping. If the parent is gone, the
+      // entry is lost and the run continues — the boundary does not depend on
+      // this succeeding.
+      const guard = setTimeout(() => { conn.destroy(); finish(); }, 1000);
+      conn.on("error", () => { clearTimeout(guard); finish(); });
+      conn.on("close", () => { clearTimeout(guard); finish(); });
+      conn.write(JSON.stringify({ to, entry: { at: new Date().toISOString(), ...entry } }) + "\n");
+      conn.end();
+    } catch {
+      finish();
+    }
+  });
+  inFlight.add(p);
+  p.then(() => inFlight.delete(p));
+  return true;
+}
+
+/** Waits for everything `send` started. Call it before exiting. */
+export async function flush() {
+  await Promise.all([...inFlight]);
+}