seisin 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it blocks it tells you whose file it was.",
   "keywords": [
     "ai-agents",
@@ -17,7 +17,7 @@
   ],
   "license": "MIT",
   "author": "Carlos Tapia",
-  "homepage": "https://github.com/carlostapiaolguin3-stack/seisin#readme",
+  "homepage": "https://carlostapiaolguin3-stack.github.io/seisin/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/carlostapiaolguin3-stack/seisin.git"

package/src/cli.js

@@ -30,6 +30,7 @@ import { hook } from "./commands/hook.js";
 import { ui } from "./commands/ui.js";
 import { requests, grant, deny } from "./commands/requests.js";
 import { whose } from "./commands/whose.js";
+import { wallsCommand } from "./commands/walls.js";
 import { reviewCommand } from "./commands/review.js";
 import { wire } from "./commands/wire.js";
 import { serveMcp } from "./mcp.js";
@@ -47,10 +48,11 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
   seisin whose <path>                   who owns it — safe to call from inside the box
   seisin scan                           find secrets outside the declared key dirs
   seisin review                         what the log says about the policy
+  seisin walls <role>                   what that role keeps being denied, and what it cost
   seisin wire                           let the agent record what it does
-  seisin requests                       what the agents asked for and could not do
+  seisin requests                       what the agents asked for and cannot have
   seisin grant <n> [--reason "…"]       approve one, with its provenance
-  seisin deny <n> [--reason "…"]        refuse one, and record why
+  seisin decline <n> [--reason "…"]     turn one down, and record why
   seisin log [--role r] [--verdict denied]
   seisin watch                          follow the log live
   seisin init [--from-observations]     propose a ${CONFIG_NAME} for this repo
@@ -90,8 +92,19 @@ const COMMANDS = {
   whose: () => void whose(config(), argv),
   wire: () => void wire(config()),
   review: () => (reviewCommand(config(), argv).friction.length ? 1 : 0),
+  walls: () => (wallsCommand(config(), argv).length ? 1 : 0),
   requests: () => (requests(config()).length ? 1 : 0),
   grant: () => void grant(config(), argv),
+  /**
+   * A person DECLINES a request; the boundary DENIES a write. One word each,
+   * because they are opposite events and `deny` used to name both — a queue
+   * entry said `first refused on …` (the kernel) and the answer said
+   * `refused frontend ✕ …` (you).
+   *
+   * `deny` stays and is not documented. Renaming a published command over a
+   * word is not worth breaking somebody's script; teaching the new one is.
+   */
+  decline: () => void deny(config(), argv),
   deny: () => void deny(config(), argv),
   mcp: async () => {
     await serveMcp(version());

package/src/commands/init.js

@@ -126,7 +126,7 @@ export function renderObserved(config, entries) {
     const declared = config.roles[name];
     const seen = roles.get(name);
 
-    const from = declared ? declared.writes : [];
+    const from = declared ? declared.writesDeclared ?? declared.writes : [];
     const found = seen ? generalise([...seen.writes]).filter((w) => !from.includes(w)) : [];
     const keys = [
       ...(declared ? declared.keys : []),

package/src/commands/requests.js

@@ -73,7 +73,7 @@ export function renderQueue(queue) {
     const note = handoffNote(r.handoff);
     if (note) lines.push(`        ${C.yellow}${note}${C.off}\n`);
   });
-  lines.push(`\n    ${C.dim}seisin grant <n> [--reason "…"]   ·   seisin deny <n> [--reason "…"]${C.off}\n\n`);
+  lines.push(`\n    ${C.dim}seisin grant <n> [--reason "…"]   ·   seisin decline <n> [--reason "…"]${C.off}\n\n`);
   return lines.join("");
 }
 

package/src/commands/run.js

@@ -13,6 +13,8 @@ import { join, dirname, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { settingsFor, roleHome } from "../srt.js";
 import { buildEnv } from "../env.js";
+import { resolveKeys } from "../keys.js";
+import { nestedSandboxWarning } from "../nested.js";
 import { spool, spoolPath, SOCK_ENV } from "../spool.js";
 import { secretsOf, redactor } from "../redact.js";
 import { STATE_DIR } from "../layout.js";
@@ -202,6 +204,54 @@ export async function run(config, argv) {
   env.SEISIN_CONFIG = config.path;
   env[SOCK_ENV] = sockPath;
 
+  /**
+   * Reference keys: resolved here, by the parent, before anything is spawned.
+   *
+   * The ordering is the security property, not a convenience. The provider
+   * command holds the vault's own credential — the keychain prompt, the
+   * 1Password session — and running it inside the box would mean putting that
+   * credential in there too, which is the thing this feature exists to avoid.
+   * The confined side cannot reach the parent; the parent can reach the vault;
+   * so the parent resolves and hands over the result.
+   *
+   * A failure here stops the run. Not an empty value, not the file of the same
+   * name, not a skipped key: a role that starts without a credential it
+   * declared fails later, somewhere else, looking like something it is not.
+   */
+  const resolved = resolveKeys(config, config.roles[role]);
+  const scratchKeys = join(dirname(sockPath), "keys");
+  if (resolved.some((r) => r.mode === "scratch")) mkdirSync(scratchKeys, { recursive: true, mode: 0o700 });
+  for (const { entry, mode, value } of resolved) {
+    if (mode === "env") { env[entry.name] = value; continue; }
+    // `scratch`: the value lands in the per-run directory this process already
+    // makes for the spool and already removes on exit, so its lifetime is the
+    // turn's by construction rather than by a cleanup somebody has to remember.
+    // The variable carries the PATH, which is the convention every tool that
+    // wants a secret from a file already reads (`_FILE`), and it means the
+    // value itself is not in the environment of a process that may print it.
+    const file = join(scratchKeys, entry.name);
+    writeFileSync(file, value, { mode: 0o600 });
+    /**
+     * Both names, because the world has two conventions and neither is ours.
+     *
+     * `<NAME>_FILE` is the Docker-secrets shape, read by tools that normally
+     * take the value in `<NAME>`. But a large family of tools already expects
+     * a PATH in the plain variable — `KUBECONFIG`,
+     * `GOOGLE_APPLICATION_CREDENTIALS`, `AWS_SHARED_CREDENTIALS_FILE` — and
+     * for those, `KUBECONFIG_FILE` is a name nothing reads.
+     *
+     * Found by running `kubectl` against it rather than reasoning about it:
+     * the file was there and correct, and the variable it was announced under
+     * was one kubectl has never heard of.
+     *
+     * Setting both costs nothing and leaks nothing: in `scratch` mode the
+     * value is deliberately not in the environment, so both variables hold a
+     * path and neither holds a secret.
+     */
+    env[entry.name] = file;
+    env[`${entry.name}_FILE`] = file;
+  }
+
   /**
    * Isolated mode: point the toolchain at a home of this role's own.
    *
@@ -247,7 +297,15 @@ export async function run(config, argv) {
   const canRedact = wantRedact && !process.stdout.isTTY;
   if (wantRedact && !canRedact) err(`${C.dim}seisin: redaction off — interactive terminal${C.off}\n`);
 
-  const secrets = canRedact ? secretsOf(settings, readFileSync) : [];
+  // Resolved references are masked alongside the key files. They never touched
+  // the disk under a path `secretsOf` could find, so without this the one kind
+  // of key that is supposed to be better looked after would be the one kind
+  // that sails through the redactor into a log.
+  const secrets = canRedact
+    ? [...secretsOf(settings, readFileSync), ...resolved.map((r) => r.value)]
+        .filter((v) => v.length >= 8)
+        .sort((a, b) => b.length - a.length)
+    : [];
   const outStream = secrets.length ? redactor(secrets) : null;
   const errStream = secrets.length ? redactor(secrets) : null;
   if (outStream) { outStream.pipe(process.stdout); errStream.pipe(process.stderr); }
@@ -327,6 +385,16 @@ export async function run(config, argv) {
   // platform, so it belongs with the other standing limits, in `seisin check`.
   void denials.available;
 
+  /**
+   * An agent that sandboxes itself has to be told about, before it starts.
+   *
+   * Said here and not by `check`, because `check` never sees the command. And
+   * said rather than fixed: passing somebody's bypass flag for them is exactly
+   * the kind of quiet widening this tool exists to refuse.
+   */
+  const nested = nestedSandboxWarning(cmd);
+  if (nested) err(`${C.yellow}seisin: ${nested}${C.off}\n`);
+
   const child = spawn(srt, ["--settings", file, "--", ...cmd], {
     stdio: outStream ? ["inherit", "pipe", "pipe"] : "inherit",
     env,

package/src/commands/walls.js

@@ -0,0 +1,24 @@
+/** `seisin walls <role>` — what that role keeps being refused, and what it cost. */
+import { walls, render } from "../walls.js";
+import { logPath } from "../log.js";
+import { out } from "../render.js";
+
+export function wallsCommand(config, argv = []) {
+  const role = argv[0];
+  if (!role) throw new Error("usage: seisin walls <role> [--since <iso>] [--min <n>]");
+  if (!config.roles[role])
+    throw new Error(`unknown role "${role}". Known: ${Object.keys(config.roles).join(", ")}`);
+  const at = (flag, fallback) => {
+    const i = argv.indexOf(flag);
+    return i === -1 ? fallback : argv[i + 1];
+  };
+  const list = walls(config, role, {
+    file: logPath(config.root),
+    min: Number(at("--min", 2)),
+    since: at("--since", null),
+  });
+  // Nothing to say prints nothing, the way `scan` does when a repo is clean.
+  // A command that always speaks is one whose output stops being read.
+  if (list.length) out(render(list));
+  return list;
+}

package/src/config.js

@@ -11,6 +11,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { CONFIG_NAME } from "./layout.js";
+import { parseKey, MODES, checkNames, BUILTIN } from "./keys.js";
 
 export { CONFIG_NAME } from "./layout.js";
 
@@ -174,6 +175,17 @@ function readValue(value, lineNo) {
 
       const end = body.indexOf('"', i + 1);
       if (end === -1) bad("unterminated string inside the array");
+      // A backslash before the closing quote means somebody wrote `\"` and
+      // expected an escape. There are none — the quote just ended the string,
+      // and the error they get otherwise is about a missing comma somewhere in
+      // the middle of a shell pipeline, which names the symptom and hides the
+      // cause. Measured while writing the docs: every attempt at a one-line
+      // provider command landed here.
+      if (body[end - 1] === "\\")
+        bad(`there are no escapes in this format, so the \\" in ` +
+            `${JSON.stringify(body.slice(i, Math.min(end + 2, i + 40)))} ended the string early.\n` +
+            `  A value cannot contain a double quote. If this is a shell command, put it in a ` +
+            `script and name the script instead — which is also how it stops being unreadable.`);
       items.push(body.slice(i + 1, end));
       i = end + 1;
       expectItem = false;                 // a trailing comma is fine; a trailing item is not
@@ -273,6 +285,7 @@ export function loadConfig(path) {
   // is how a tool gets kept out.
   const keyDir = own(own(parsed, "keys"), "dir");
   const keyDirs = keyDir === undefined ? [] : asArray(keyDir, "keys.dir");
+  const keyProviders = readProviders(own(own(parsed, "keys"), "providers"), path);
   // `undefined` means "use the defaults"; an explicit empty array means "none".
   // The difference matters: one is a user who has not thought about it, the
   // other is a user who has.
@@ -280,7 +293,7 @@ export function loadConfig(path) {
   const runtimeWrites = own(runtime, "writes");
 
   const out = {
-    root: dirname(path), path, keyDirs,
+    root: dirname(path), path, keyDirs, keyProviders,
     allowedDomains: own(own(parsed, "network"), "allow") ?? [],
     runtimeWrites: runtimeWrites === undefined ? undefined : asArray(runtimeWrites, "runtime.writes"),
     // `[runtime] isolate` — how much of your home a role stops reaching. See
@@ -296,12 +309,69 @@ export function loadConfig(path) {
     const r = own(roles, name);
     const writes = asArray(own(r, "writes"), `roles.${name}.writes`);
     const keys = asArray(own(r, "keys"), `roles.${name}.keys`);
-    if (keys.length && keyDirs.length === 0)
+    // Read once, here, so every consumer sees the same answer about what an
+    // entry is. `keys` itself stays the array of strings that was written: it
+    // is what `render`, `serve` and `init` print, and the whole point of a
+    // reference is that the written form is the reviewable one.
+    const keyEntries = keys.map((k) => {
+      try {
+        return parseKey(k);
+      } catch (e) {
+        throw new Error(`${path}: roles.${name}: ${e.message}`);
+      }
+    });
+    // Only a path needs somewhere to live. A reference does not, and demanding
+    // `[keys] dir` from a config whose secrets are all in a vault would be the
+    // tool insisting on the arrangement it was built for.
+    if (keyEntries.some((k) => k.kind === "file") && keyDirs.length === 0)
       throw new Error(`${path}: roles.${name} lists keys, but [keys] dir is not set`);
+    /**
+     * An unknown scheme is refused, not ignored.
+     *
+     * Same rule as everywhere else here: a `keys = ["vault://x"]` with no
+     * `[keys.providers.vault]` is a configuration error, and the alternative —
+     * treating it as a filename, or as a key that quietly never arrives — is a
+     * policy that reads as protecting something it is not.
+     */
+    for (const k of keyEntries) {
+      // `file://` ships with seisin, so it needs no declaration. It is the one
+      // builtin, and the reason is in keys.js: a secret in a plain file is the
+      // case this exists for, and making that case declare a provider that
+      // runs `cat` is a papercut on the only path most people take.
+      if (k.kind !== "ref" || BUILTIN.has(k.scheme) || own(keyProviders, k.scheme)) continue;
+      const known = Object.keys(keyProviders);
+      throw new Error(
+        `${path}: roles.${name}: key "${k.raw}" uses the "${k.scheme}" scheme, and no ` +
+        `[keys.providers.${k.scheme}] is declared.\n` +
+        `  ${known.length ? `Declared providers: ${known.join(", ")}.` : "No providers are declared."}\n` +
+        `  A provider is a command with a placeholder:\n` +
+        `    [keys.providers.${k.scheme}]\n` +
+        `    command = ["your-cli", "read", "{ref}"]`);
+    }
+    checkNames({ name, keyEntries });
+    const keyMode = own(r, "key_mode");
+    if (keyMode !== undefined && !MODES.includes(keyMode))
+      throw new Error(
+        `${path}: roles.${name}: key_mode = "${keyMode}" is not a delivery mode. ` +
+        `Known: ${MODES.join(", ")}.`);
     out.roles[name] = {
       name,
-      writes,
+      /**
+       * `writes` is what is GRANTED; `writesDeclared` is what was written.
+       *
+       * Expanded here and not at emit time, because two answers is how the
+       * document ends up looser or tighter than the boundary. Everything
+       * downstream — `ownersOf`, `explain`, `whose`, the settings, the console
+       * — reads `writes`, so the owner of a database is the owner of its `-wal`
+       * everywhere, and the kernel and the sentence agree. The declared form is
+       * kept so that regenerating a config writes back what a person typed
+       * rather than the expansion.
+       */
+      writes: withSidecars(writes),
+      writesDeclared: writes,
       keys,
+      keyEntries,
+      keyMode: keyMode ?? null,
       env: asArray(own(r, "env"), `roles.${name}.env`),
       network: own(r, "network") === undefined ? null : asArray(own(r, "network"), `roles.${name}.network`),
     };
@@ -309,6 +379,93 @@ export function loadConfig(path) {
   return out;
 }
 
+/**
+ * `[keys.providers.<name>]` — the commands that turn a reference into a value.
+ *
+ * Validated here and not at resolution time, because the whole argument for
+ * references is that a broken policy should be visible in `seisin check`,
+ * without asking anybody's keychain for a password to find out.
+ *
+ * `{ref}` is required. A command without it resolves every reference to the
+ * same thing, which is the kind of mistake that looks like it works: the first
+ * key comes back, so does the second, and they are both the first one.
+ */
+function readProviders(table, path) {
+  const out = Object.create(null);
+  if (table === undefined) return out;
+  for (const name of Object.keys(table)) {
+    const p = own(table, name);
+    // Redefining `file://` is refused rather than honoured. Two configs where
+    // the same scheme means different things is the failure this whole feature
+    // is supposed to remove — and it would be invisible, because the policy
+    // reads identically in both.
+    if (BUILTIN.has(name))
+      throw new Error(
+        `${path}: [keys.providers.${name}] — "${name}://" is built in and cannot be redefined.\n` +
+        `  It reads a file, optionally one KEY out of it: "file://.secrets/all.env#TOKEN".\n` +
+        `  For different behaviour, give your provider another name.`);
+    const command = own(p, "command");
+    if (!Array.isArray(command) || command.length === 0 || command.some((c) => typeof c !== "string"))
+      throw new Error(
+        `${path}: [keys.providers.${name}] needs a command, as an array of strings.\n` +
+        `  e.g. command = ["security", "find-generic-password", "-w", "-s", "{ref}"]`);
+    if (!command.some((c) => c.includes("{ref}")))
+      throw new Error(
+        `${path}: [keys.providers.${name}] has no {ref} in its command, so every key of this ` +
+        `provider would resolve to the same value.\n` +
+        `  Put {ref} where the reference goes: command = [${command.map((c) => `"${c}"`).join(", ")}, "{ref}"]`);
+    const mode = own(p, "mode");
+    if (mode !== undefined && !MODES.includes(mode))
+      throw new Error(
+        `${path}: [keys.providers.${name}] mode = "${mode}" is not a delivery mode. ` +
+        `Known: ${MODES.join(", ")}.`);
+    out[name] = { name, command, mode: mode ?? null };
+  }
+  return out;
+}
+
+/**
+ * A SQLite database is four files, and a policy should say it once.
+ *
+ * `bitacora/x/equipo.sqlite` is not the database — it is one of the files the
+ * database is made of. Writing to it in WAL mode also writes `-wal` and
+ * `-shm`; in rollback mode, `-journal`. So "this role writes this database"
+ * takes four lines, and a policy with eight databases and thirty-one roles
+ * takes nine hundred and ninety-two of them. Measured on a real one: 744 of
+ * 1,248 write lines — 60% — were sidecars, and every single one had its
+ * `.sqlite` declared beside it. Not one case wanted the `-wal` without the
+ * database.
+ *
+ * **This grants no authority that was not already there**, which is the whole
+ * reason it is safe to do implicitly. The `-wal` holds that database's pending
+ * transactions: whoever can write the database can already empty it, replace
+ * it, or corrupt it. The sidecar is not a second resource — it is the same one.
+ *
+ * It is also not a glob. The kernel grants a path and everything under it, so
+ * `equipo.sqlite*` is unenforceable and `seisin check` refuses it; these are
+ * emitted as literal paths, exactly as if they had been typed.
+ *
+ * **The suffix list is closed on purpose** and this is the line that keeps the
+ * idea from becoming the exception list it could be: three suffixes, and only
+ * after a name that says SQLite. `.db` is deliberately not in it — plenty of
+ * things are called `.db` and a grant to create `whatever.db-wal` inside a
+ * directory somebody else owns would be new authority, arriving quietly. A
+ * database with another name declares its sidecars by hand, as before.
+ */
+const SIDECARS = ["-wal", "-shm", "-journal"];
+const IS_SQLITE = /\.sqlite3?$/;
+
+export function withSidecars(paths) {
+  const out = [];
+  for (const p of paths) {
+    out.push(p);
+    if (IS_SQLITE.test(p)) for (const s of SIDECARS) out.push(p + s);
+  }
+  // A policy written before this existed already lists them. Keeping the first
+  // occurrence keeps the order somebody chose.
+  return [...new Set(out)];
+}
+
 function asArray(value, where) {
   if (value === undefined) return [];
   if (typeof value === "string") return [value];

package/src/hook.js

@@ -18,6 +18,7 @@
  */
 import { explain, normalize } from "./owners.js";
 import { append, logPath } from "./log.js";
+import { timesHit } from "./walls.js";
 import { record, requestsPath } from "./requests.js";
 
 /** Tools whose input names a file directly. */
@@ -118,6 +119,12 @@ function kindOf(config, path) {
  */
 const QUEUED = "Already queued for a person to answer — retrying or waiting will not move it.";
 
+/** 4 -> "fourth". Past a handful the numeral reads better than the word. */
+function ordinal(n) {
+  const words = ["", "first", "second", "third", "fourth", "fifth", "sixth", "seventh", "eighth", "ninth", "tenth"];
+  return words[n] ?? `${n}th`;
+}
+
 /**
  * Decides and records one tool call.
  *
@@ -164,7 +171,12 @@ export function decide(config, role, event, { observe = false, now = append, ask
     if (!observe && !v.allowed)
       ask(queue, { role, action: kind === "key" ? "read" : t.action, target: rel, owners: v.owners ?? [] });
 
-    verdicts.push({ ...v, target: rel, kind });
+    // The action as it was RECORDED, not as the tool named it: a read of a key
+    // is logged as "read" and a write is "write", and the counter below looks
+    // the entry up by that pair. Carrying the tool's word here instead would
+    // make every lookup miss, silently — the refusal would simply never
+    // mention that it had been given before.
+    verdicts.push({ ...v, target: rel, kind, action: kind === "key" ? "read" : t.action });
   }
 
   if (observe) return { decision: null, logged: verdicts.length };
@@ -173,6 +185,25 @@ export function decide(config, role, event, { observe = false, now = append, ask
   if (!denied) return { decision: null, logged: verdicts.length };
   const wasRead = denied.kind === "key";
 
+  /**
+   * How many times this exact denial has already been handed to this role.
+   *
+   * The sentence below is correct every time and that has not been enough:
+   * measured on a real team, 25% of all denials were a repeat of something the
+   * same role had already been refused, one of them nineteen times. Correct
+   * and *heard* are different properties, and only the first was being
+   * measured. So the refusal carries its own history: the second time, it says
+   * it is the second time.
+   *
+   * Counted from the log that was just written, so the count includes this
+   * attempt. Silent on the first — a counter that says "1×" on every first
+   * refusal is noise on the turn where the sentence is already doing its job.
+   */
+  const before = timesHit(logPath(config.root), role, denied.action, denied.target);
+  const again = before > 1
+    ? ` You have been denied this ${before} times now; it is not going to work on the ${ordinal(before + 1)} try.`
+    : "";
+
   // 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.
@@ -189,7 +220,7 @@ export function decide(config, role, event, { observe = false, now = append, ask
           ? 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,
+          : `${denied.reason} (seisin)`) + again + " " + QUEUED,
     },
   };
 }

package/src/index.js

@@ -25,6 +25,18 @@ export { covers, ownersOf, keyHolders, explain } from "./owners.js";
 export { settingsFor, RUNTIME_WRITES, expand } from "./srt.js";
 export { buildEnv, BASE as BASE_ENV, DEFAULTS as DEFAULT_ENV } from "./env.js";
 
+/**
+ * Keys that are references, and how a resolved value reaches a role.
+ *
+ * `parseKey` and `MODES` are here because reading somebody's policy means
+ * 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";
+
+/** What a role keeps being refused, recomputed against the policy as it stands. */
+export { walls, wasted, MIN_HITS } from "./walls.js";
+
 /** The report `check` prints, without the printing. */
 export { inspect, sharedPaths } from "./inspect.js";