seisin 0.1.1 → 0.2.0

package/src/inspect.js

@@ -8,9 +8,11 @@
  * does — each one is a way the policy silently does not hold — so they belong
  * where they can be exercised directly.
  */
-import { resolve, dirname, basename, relative } from "node:path";
-import { realpathSync, lstatSync, readdirSync } from "node:fs";
+import { resolve, dirname, basename, relative, join, delimiter } from "node:path";
+import { realpathSync, lstatSync, readdirSync, existsSync, readFileSync, statSync } from "node:fs";
 import { ownersOf } from "./owners.js";
+import { entriesOf } from "./keys.js";
+import { SHAPES } from "./scan.js";
 import { wired } from "./commands/wire.js";
 import { RUNTIME_WRITES, CREDENTIAL_HOMES, expand, settingsFor } from "./srt.js";
 
@@ -28,6 +30,17 @@ export function inspect(config, only = null, where = config.path) {
   return {
     where,
     roles: roles.map((r) => ({ name: r.name, writes: r.writes, keys: r.keys })),
+    /**
+     * The provider commands this config would run, listed because they are the
+     * one thing in a `seisin.toml` that **executes**, and it executes in the
+     * parent, unsandboxed, as you. Everything else in the file only describes a
+     * boundary. `check` runs nothing, so this is where you see them first — and
+     * seeing them first is the whole point when the file came with a repo you
+     * cloned rather than one you wrote.
+     */
+    providers: Object.values(config.keyProviders ?? {}).map((p) => ({
+      name: p.name, command: p.command, mode: p.mode,
+    })),
     shared: sharedPaths(config, roles),
     warnings: warningsFor(config, roles),
     limits: LIMITS,
@@ -102,7 +115,21 @@ export function sharedPaths(config, roles = Object.values(config.roles)) {
   for (const r of roles)
     for (const glob of r.writes)
       if (ownersOf(config, glob.replace(/\/\*\*$/, "")).length > 1) seen.add(glob);
-  return [...seen];
+  /**
+   * A shared database counts once, not four times.
+   *
+   * `writes` carries the sidecar expansion so that the grant and the sentence
+   * agree (see config.js), and this list read straight off it turned nine
+   * shared things into thirty-three — the same name with three suffixes,
+   * announced as if it were three more decisions to make. The expansion exists
+   * to stop a policy saying one thing four times; a warning that undoes that
+   * is the feature leaking into the place it was meant to clean up.
+   *
+   * A sidecar shared WITHOUT its database still counts on its own, because
+   * that is a real and odd thing to have.
+   */
+  const todas = new Set(seen);
+  return [...seen].filter((p) => !(/-(wal|shm|journal)$/.test(p) && todas.has(p.replace(/-(wal|shm|journal)$/, ""))));
 }
 
 /**
@@ -147,6 +174,58 @@ function homeReachWarning(config) {
 
 
 /** Every way this policy does not hold, each with what to do about it. */
+/**
+ * Credential-shaped names at the top of the repository, and nothing deeper.
+ *
+ * One `readdir`, no recursion, conventional names only. It exists to answer
+ * "does this repo plausibly have secrets" fast enough to run on every `check`,
+ * not to find them — `seisin scan` is the one that looks properly.
+ */
+const CREDENTIAL_NAMES = /^(\.env(\..+)?|\.secrets|secrets|\.netrc|.*\.(pem|key|p12|pfx))$/i;
+
+function credentialish(root) {
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = new Set(entries.filter((e) => CREDENTIAL_NAMES.test(e.name)).map((e) => e.name));
+
+  /**
+   * And the ones whose name gives nothing away.
+   *
+   * The name test misses `credentials.txt`, `tokens.conf`, `config.local` —
+   * which a field review found by writing a test file this did not catch, and
+   * then blaming the test. The test was fine; the detector was name-only.
+   *
+   * So the root's small text files are also read, with the same shapes
+   * `seisin scan` uses. Root only, small only, and it stops at the first hit
+   * per file: this runs on every `check` and the full walk is `scan`'s job.
+   */
+  const CERTAIN = SHAPES.filter(([c]) => c === "certain").map(([, , re]) => re);
+  for (const e of entries) {
+    if (found.size >= 4) break;
+    if (!e.isFile() || found.has(e.name)) continue;
+    try {
+      const p = join(root, e.name);
+      if (statSync(p).size > 64 * 1024) continue;
+      const text = readFileSync(p, "utf8");
+      if (CERTAIN.some((re) => re.test(text))) found.add(e.name);
+    } catch {
+      /* unreadable, or not text: not our business here */
+    }
+  }
+  return [...found].sort().slice(0, 4);
+}
+
+/** Is this a command the shell would find? Walks PATH; asks no shell. */
+function onPath(cmd) {
+  if (cmd.includes("/")) return existsSync(cmd);
+  const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  return dirs.some((d) => existsSync(join(d, cmd)));
+}
+
 function warningsFor(config, roles) {
   const warnings = [];
 
@@ -400,13 +479,84 @@ function warningsFor(config, roles) {
       });
   }
 
-  if (config.keyDirs.length === 0 && Object.values(config.roles).some((r) => r.keys.length))
+  /**
+   * A policy with no credential floor at all, in a repo that has credentials.
+   *
+   * `[keys] dir` is what produces `denyRead`. Without it the emitted settings
+   * carry an empty deny list, so every role reads every secret in the
+   * repository — and until this warning, nothing said so. The existing
+   * `keys-unscoped` only fires when a role *lists* keys, which is the case
+   * where somebody already thought about it.
+   *
+   * The dangerous shape is the other one, and it is not hypothetical: a policy
+   * generated by a script. The deployment this was built against generates its
+   * `seisin.toml` from a Python program, and declares `[keys] dir` mostly so
+   * `scan` skips those directories. A generator that dropped that one line
+   * would hand every role the credential tree and produce a clean `check`.
+   *
+   * Credit where it is due: this is `L-01` of a code review of another
+   * project's contract type, which makes its credential floor impossible to
+   * construct empty. That is the right shape and it is a bigger change than a
+   * warning. This is the cheap half — and the review's claim that the file
+   * path was safe turned out to be generous: it was not.
+   *
+   * Deliberately NOT a full `seisin scan`: that walks the tree and `check` has
+   * to stay instant. A shallow look at the repository root catches the
+   * conventional places and costs one `readdir`.
+   */
+  if ((config.keyDirs ?? []).length === 0) {
+    const found = credentialish(config.root);
+    if (found.length)
+      warnings.push({
+        kind: "no-key-floor",
+        headline: `no [keys] dir is declared, and this repo has ${found.join(", ")} — every role can read them`,
+        detail:
+          "Without a key directory the emitted policy denies no reads at all. Declare the " +
+          "directory your secrets live in, and the roles that may read each one.",
+      });
+  }
+
+  // Only a key that is a PATH needs a key directory. A config whose secrets all
+  // live in a vault has no `[keys] dir` and nothing wrong with it, and warning
+  // there would be the tool insisting on the arrangement it was built for.
+  if (config.keyDirs.length === 0 &&
+      Object.values(config.roles).some((r) => entriesOf(r).some((k) => k.kind === "file")))
     warnings.push({
       kind: "keys-unscoped",
       headline: "keys are listed but [keys] dir is unset — nothing will be scoped",
       detail: null,
     });
 
+  /**
+   * A provider whose command is not on PATH.
+   *
+   * This is the half of validating references that can be done without
+   * resolving one — which is the whole requirement: a broken policy has to be
+   * visible in `check`, not on the first run, and certainly not by asking
+   * somebody's keychain for a password to find out. The scheme and the
+   * provider are checked when the config loads, so by the time we are here
+   * they exist; what is left is whether the command does.
+   *
+   * A warning and not an error: the binary can legitimately be missing on the
+   * machine reading the policy and present on the one that runs it, which is
+   * every CI checkout.
+   */
+  const used = new Set();
+  for (const r of Object.values(config.roles))
+    for (const k of entriesOf(r)) if (k.kind === "ref") used.add(k.scheme);
+  for (const scheme of [...used].sort()) {
+    const provider = config.keyProviders?.[scheme];
+    if (!provider || onPath(provider.command[0])) continue;
+    warnings.push({
+      kind: "provider-missing",
+      headline: `the ${scheme} provider runs "${provider.command[0]}", which is not on PATH`,
+      detail:
+        "every key of that scheme will stop the run rather than resolve. Nothing is " +
+        "substituted for a key that did not resolve, so this fails closed — but it fails " +
+        "at the start of a turn, not here.",
+    });
+  }
+
   return warnings;
 }
 

package/src/keys.js

@@ -0,0 +1,483 @@
+/**
+ * Keys that are references rather than files.
+ *
+ * Until this existed a key was a path: `keys = ["netlify-token.txt"]` named a
+ * file inside a declared `[keys] dir`, and the whole mechanism was the
+ * filesystem's — resolve it, check it lands inside the directory, add it to
+ * `allowRead`. That works and it stays. What it cannot do is reach a secret
+ * that has no path, which is where most secrets that are looked after at all
+ * actually live: a keychain, 1Password, Bitwarden, sops, Vault.
+ *
+ * So a key may also be a **reference with a scheme**, resolved by a provider
+ * declared in the same file:
+ *
+ *   [keys.providers.keychain]
+ *   command = ["security", "find-generic-password", "-w", "-s", "{ref}"]
+ *
+ *   [roles.frontend]
+ *   keys = ["keychain://netlify-token", "netlify-token.txt"]
+ *
+ * A provider is a command with a placeholder. Adding Bitwarden or
+ * `sops` is then three lines of TOML and no code — which is what makes this one
+ * integration instead of one per vault, and what keeps seisin from aging with
+ * somebody else's CLI.
+ *
+ * ## What this does not do
+ *
+ * It resolves the secret **at rest**, not in the agent's context. The value
+ * still reaches the process and the agent can still read it. That is a strict
+ * improvement over a plaintext file — the secret stops living on disk, the
+ * policy holds a reviewable reference instead of a path, and every resolution
+ * is logged without its value — but it is not "the agent never sees it". That
+ * is `inject`, it costs terminating the role's TLS with a CA of your own, and
+ * it is not built. `modeOf` refuses it by name rather than letting it read as
+ * available.
+ *
+ * ## Why the value is never written down
+ *
+ * The reference is what gets committed, diffed and approved; the value is what
+ * gets handed to one process and forgotten. A log that carries the secret is a
+ * second plaintext copy with worse access control than the first.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve, isAbsolute } from "node:path";
+import { BASE, DEFAULTS } from "./env.js";
+import { SOCK_ENV } from "./spool.js";
+
+/**
+ * `scheme://rest`, and nothing cleverer.
+ *
+ * The scheme is matched the way a URL scheme is, so a Windows path (`C:\…`) and
+ * a relative path with a colon in it do not read as references. `rest` is the
+ * whole remainder including any slashes, because `op://vault/item/field` is one
+ * reference and not three.
+ */
+const RE_REF = /^([a-z][a-z0-9+.\-]*):\/\/(.+)$/;
+
+/** `NAME=` in front of a reference: the environment variable to deliver it as. */
+const RE_NAMED = /^([A-Za-z_][A-Za-z0-9_]*)=(.+)$/;
+
+/**
+ * The name a reference arrives under when nobody said.
+ *
+ * Derived rather than required, because `keys = ["keychain://netlify-token"]`
+ * is the spelling in front of everyone and making it illegal buys nothing. The
+ * derivation is dull — last segment, uppercased, anything that is
+ * not a letter or a digit becomes `_` — and `seisin check` prints the result,
+ * so a name that surprises somebody is visible before a run rather than after.
+ */
+export function defaultName(ref) {
+  const last = ref.split("/").filter(Boolean).pop() ?? ref;
+  const name = last.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
+  // A reference of punctuation only would otherwise derive the empty string and
+  // produce an unsettable variable. It is not reachable from a sane vault name;
+  // it is here because an unnamed failure at spawn time is worse than a refusal.
+  return /^[A-Za-z_]/.test(name) ? name : `KEY_${name}`;
+}
+
+/**
+ * One entry of `keys = [...]`, read.
+ *
+ * Returns `{ kind: "file", raw }` for a path — which is everything that was
+ * valid before this module existed, unchanged — or
+ * `{ kind: "ref", scheme, ref, name, raw }` for a reference.
+ *
+ * It does not decide whether the scheme is *known*: that needs the config, and
+ * separating the two is what lets `check` report every unknown scheme in a file
+ * at once instead of dying on the first.
+ */
+export function parseKey(entry) {
+  if (typeof entry !== "string") throw new Error(`keys: expected a string, got ${typeof entry}`);
+  const named = RE_NAMED.exec(entry);
+  const body = named ? named[2] : entry;
+  const m = RE_REF.exec(body);
+  if (!m) {
+    // `NAME=path` is refused rather than read as a file called `NAME=path`.
+    // A name in front of a path means the writer expected delivery by
+    // environment, and a path key is delivered by being readable — so the
+    // spelling asks for something that will not happen, silently.
+    if (named)
+      throw new Error(
+        `keys = "${entry}": "${named[1]}=" names an environment variable, but ` +
+        `"${body}" is a path, not a reference.\n` +
+        `  A path key is delivered by being readable, so there is no variable to name. ` +
+        `Drop the prefix, or point it at a provider: "${named[1]}=keychain://${named[2]}".`);
+    return { kind: "file", raw: entry };
+  }
+  const [, scheme, ref] = m;
+  return { kind: "ref", scheme, ref, name: named ? named[1] : defaultName(ref), raw: entry };
+}
+
+/**
+ * `file://` — the one provider seisin ships, because it is the common case.
+ *
+ * Everything else stays out: a provider is a command,
+ * and wiring 1Password or Vault into the package would be choosing for you and
+ * ageing with somebody else's CLI. This one is different, and the difference is
+ * not convenience.
+ *
+ * The secret in a plain file is **the case the tool exists for**. Measured on
+ * one real deployment: 128 credential files in the clear, 79 of them
+ * world-readable, and not one role using the key mechanism at all. Telling
+ * that person "declare a provider that runs `cat`" puts a papercut on the only
+ * path most people will ever take, and `cat` is worse than it looks — it
+ * resolves relative to whatever directory the parent happened to be in, and it
+ * hands back the whole file when the file holds twelve variables.
+ *
+ * So `file://` is native, resolves against the policy's own directory, and
+ * takes a fragment:
+ *
+ *     keys = ["TOKEN=file://.secrets/netlify.txt"]              the whole file
+ *     keys = ["RESEND_KEY=file://.secrets/all.env#RESEND_KEY"]  one key of many
+ *
+ * It grants **no read**. That is the entire point: the role gets the value and
+ * cannot open the file, which is the thing `keys = ["all.env"]` cannot do
+ * because a file grant is a file grant.
+ *
+ * It does not require the file to live under `[keys] dir`. The path form does,
+ * because it opens a read inside a denied directory and has to be bounded. This
+ * opens nothing — it hands over a string — so the same rule would be a
+ * restriction copied for looking like the other one.
+ */
+export const BUILTIN = new Set(["file"]);
+
+/** The file as a JSON object, or null if it is not one. */
+function parseJsonObject(text) {
+  const t = text.trim();
+  if (!t.startsWith("{")) return null;
+  try {
+    const v = JSON.parse(t);
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One trailing newline is the editor's, not the secret's. */
+const unterminate = (v) => v.replace(/\r?\n$/, "");
+
+/**
+ * `KEY=value` out of a file that holds several.
+ *
+ * Deliberately small: `export` is tolerated because half the world's `.env`
+ * files have it, surrounding quotes come off, and everything else is left
+ * alone. This is not a shell parser and should never become one — a config
+ * language that grows an interpreter is how a permission tool gets a CVE.
+ */
+/**
+ * One value out of a JSON object.
+ *
+ * JSON is here and Markdown is not, and the line between them is not effort:
+ * **JSON is a format, a runbook is a document.** A service-account key, a
+ * `credentials.json`, anything a cloud CLI writes — those have one shape, so
+ * reading them is a rule. A table of passwords inside a page of prose has no
+ * shape; extracting from it would be guessing, and a credential tool that
+ * guesses hands over the wrong secret rather than failing.
+ *
+ * The literal key first, then a dotted path, because a key that contains a dot
+ * is real and should win over a reading of it as a path.
+ *
+ * Only scalars. An object or an array is not a credential, and returning one
+ * stringified would put `[object Object]` in an environment variable and call
+ * it a token.
+ */
+function fromJson(obj, key, ref) {
+  let v = Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+  if (v === undefined && key.includes(".")) {
+    v = key.split(".").reduce((o, k) => (o && typeof o === "object" ? o[k] : undefined), obj);
+  }
+  if (v === undefined) {
+    const top = Object.keys(obj).slice(0, 8).join(", ");
+    throw new Error(
+      `key "${ref}": that JSON has no ${key}.\n` +
+      `  Top-level names: ${top}${Object.keys(obj).length > 8 ? ", …" : ""}.\n` +
+      `  A nested one is reached with dots: "#credentials.token".`);
+  }
+  if (v === null || typeof v === "object")
+    throw new Error(
+      `key "${ref}": ${key} is ${v === null ? "null" : Array.isArray(v) ? "an array" : "an object"}, ` +
+      `not a value.\n  A credential is a string or a number. Point the fragment at one, or drop ` +
+      `the fragment to hand over the whole file.`);
+  return String(v);
+}
+
+function fromDotEnv(text, key, ref) {
+  let sawAny = false;
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    sawAny = true;
+    if (m[1] !== key) continue;
+    return m[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+  }
+  /**
+   * Two different failures, and telling them apart is the whole message.
+   *
+   * "this file has no `TOKEN=`" is a typo in the reference. "this file has no
+   * `NAME=` lines at all" is a person pointing a fragment at something that is
+   * not an env file — and in the field that was a 146-line Markdown runbook
+   * with the credentials in a table, which no extractor is going to read.
+   * Saying "has no TOKEN=" about that sends somebody hunting for a typo in a
+   * file where the answer is that the secrets are in prose.
+   */
+  if (!sawAny)
+    throw new Error(
+      `key "${ref}": nothing in that file looks like NAME=value, so there is no ${key} to take.\n` +
+      `  A fragment reads one line out of an env file. If the secret lives inside a document ` +
+      `— a runbook, a table, a note — seisin cannot reach it, and the fix is to move the ` +
+      `secret out of the document rather than to teach a parser about it.\n` +
+      `  Without the "#${key}", file:// hands over the whole file as the value.`);
+  throw new Error(
+    `key "${ref}": the file has NAME=value lines, but no ${key}=.\n` +
+    `  A name that is not there is not an empty value — nothing is substituted for a key ` +
+    `that did not resolve.`);
+}
+
+/**
+ * Read `file://<path>` or `file://<path>#<KEY>`, relative to the policy.
+ *
+ * Relative to the policy and not to the process: a key that resolves
+ * differently depending on where you were standing when you typed the command
+ * is a key that works in your shell and fails in the agent's.
+ */
+export function readFileRef(entry, root = ".") {
+  const hash = entry.ref.lastIndexOf("#");
+  const path = hash === -1 ? entry.ref : entry.ref.slice(0, hash);
+  const key = hash === -1 ? null : entry.ref.slice(hash + 1);
+  const full = isAbsolute(path) ? path : resolve(root, path);
+  let text;
+  try {
+    text = readFileSync(full, "utf8");
+  } catch (e) {
+    throw new Error(
+      `key "${entry.raw}": cannot read ${full} (${e.code ?? e.message}).\n` +
+      `  The path is resolved against the policy file's directory, not the current one.`);
+  }
+  let value;
+  if (key === null) {
+    value = unterminate(text);
+  } else {
+    // Sniffed, not taken from the extension. The file that motivated this was
+    // named `.txt` and the one before it `.env`; the name is a hint and the
+    // content is the fact.
+    const asJson = parseJsonObject(text);
+    value = asJson ? fromJson(asJson, key, entry.raw) : fromDotEnv(text, key, entry.raw);
+  }
+  if (value === "")
+    throw new Error(`key "${entry.raw}": ${full} is empty. An empty credential is not a credential.`);
+  return value;
+}
+
+/**
+ * Variable names a key may not take, and why each group is here.
+ *
+ * A key delivered by `env` is written into the child's environment after it is
+ * built, so whatever it is called, it wins. That is fine until the name is one
+ * 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
+ *     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.
+ *   - **What the child needs to be a child.** `keys = ["keychain://path"]`
+ *     derives `PATH`, and the measured result is the sandbox failing with
+ *     `env: node: No such file or directory` — a config mistake that reads
+ *     exactly like a broken installation. `HOME`, `TMPDIR` and the TLS
+ *     variables are the same shape, and `NODE_EXTRA_CA_CERTS` is worse than
+ *     cosmetic.
+ *
+ * Refused when the policy loads rather than when it runs, so `seisin check`
+ * catches it and nobody debugs it from inside a sandbox.
+ */
+export const RESERVED_ENV = new Set([
+  "SEISIN_ROLE", "SEISIN_CONFIG", SOCK_ENV,
+  ...BASE, ...Object.keys(DEFAULTS),
+]);
+
+/**
+ * Every delivered name a role's keys would claim — the variable, and for
+ * `scratch` the `_FILE` that carries the path.
+ *
+ * Checked as a set because two keys resolving to one name is the other half of
+ * the same failure: `keys = ["T=a://x", "T=b://y"]` used to deliver the second
+ * and drop the first, in silence, in a credential list. Measured before this
+ * existed; the run printed `T=b` and said nothing about `a://x`.
+ */
+export function checkNames(role) {
+  const taken = new Map();
+  for (const e of role.keyEntries ?? []) {
+    if (e.kind !== "ref") continue;
+    for (const name of [e.name, `${e.name}_FILE`]) {
+      if (RESERVED_ENV.has(name))
+        throw new Error(
+          `roles.${role.name}: key "${e.raw}" would arrive as ${name}, which seisin or the ` +
+          `child already needs.\n` +
+          `  Give it a name of its own: keys = ["MY_${name}=${e.scheme}://${e.ref}"].`);
+      const first = taken.get(name);
+      if (first !== undefined)
+        throw new Error(
+          `roles.${role.name}: "${first}" and "${e.raw}" both arrive as ${name}. ` +
+          `One would silently replace the other.\n` +
+          `  Name at least one of them: keys = ["SOMETHING_ELSE=${e.scheme}://${e.ref}"].`);
+      taken.set(name, e.raw);
+    }
+  }
+}
+
+/**
+ * A role's key entries, however the role object was built.
+ *
+ * `loadConfig` fills `keyEntries`; a role assembled by hand — a test, or an
+ * embedder holding seisin as a library — has only `keys`, and that shape
+ * shipped, so it keeps working. One helper rather than the same fallback
+ * written in three files, because the day they disagree is the day a key is
+ * scoped in one place and not in another.
+ */
+export function entriesOf(role) {
+  return role.keyEntries ?? (role.keys ?? []).map(parseKey);
+}
+
+/**
+ * The three ways a resolved value can reach a role.
+ *
+ * The middle one is called `scratch` and not `file`, which looks like a
+ * cosmetic choice and is not. The runtime has a field named
+ * `credentials.files`, it is the one that looks like seisin's `keys` (both take
+ * paths), and on macOS it does **not** mask — it makes the file unreadable, so
+ * a `cat` returns `Operation not permitted` and the reader concludes the
+ * feature is broken rather than misused. That mistake has already been made
+ * once here and cost a measurement that got written up as a finding about the
+ * 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.
+ */
+export const MODES = ["env", "scratch", "inject"];
+
+/**
+ * How a role receives its reference keys, and where that is written.
+ *
+ * Per role (`key_mode`) or per provider (`mode`), role first. It is not a
+ * per-key setting, and that is a limit of the config language rather than a
+ * judgement: the parser covers `[table]` headers and `key = value` pairs, so a
+ * mode attached to one entry of an array has nowhere to live without inline
+ * 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
+ * "this role sees the value" without opening any code, and a per-role setting
+ * answers exactly that question.
+ *
+ * There is no silent default. A reference with no mode anywhere is an error,
+ * because the two available answers differ in what the agent can walk away
+ * with, and picking one for somebody is picking how much a leak costs them.
+ */
+export function modeOf(config, role, entry) {
+  const provider = config.keyProviders?.[entry.scheme];
+  const mode = role.keyMode ?? provider?.mode ?? null;
+  if (mode === null) {
+    // A built-in scheme has no `[keys.providers.…]` table to put a default in —
+    // declaring one is refused, because a scheme cannot mean two things. So
+    // offering it here sent the first person who tried the feature from this
+    // error straight into another one. Found in the field, on the first wall.
+    const second = BUILTIN.has(entry.scheme)
+      ? ""
+      : ` Or set one for every key of that provider: ` +
+        `[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.`);
+  }
+  if (mode === "inject")
+    throw new Error(
+      `roles.${role.name}: key_mode = "inject" is not implemented.\n` +
+      `  It is the one mode where the agent never sees the value, and it is not free: the ` +
+      `runtime only masks a credential when the role's TLS is terminated with a CA of ` +
+      `seisin's own — MITM over all of that role's traffic, not just the host holding the ` +
+      `secret. It is refused rather than half-available.\n` +
+      `  Use "env" or "file" today. See docs/decisions.md.`);
+  if (!MODES.includes(mode))
+    throw new Error(
+      `roles.${role.name}: key_mode = "${mode}" is not a delivery mode. Known: ${MODES.join(", ")}.` +
+      // The one wrong answer named, because it is the word everybody
+      // reaches for and it is one letter from a runtime field that fails
+      // silently. Guessing costs a debugging session; saying so costs a line.
+      (mode === "file"
+        ? `\n  "file" is not one of them on purpose — the runtime has a "credentials.files" that ` +
+          `takes paths and, on macOS, makes them unreadable instead of masking. The mode that ` +
+          `hands a role a file is "scratch".`
+        : ""));
+  return mode;
+}
+
+/**
+ * Run a provider and hand back what it printed.
+ *
+ * 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.
+ *     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.
+ *   - **A failure is a failure.** Not empty, not the file of the same name, not
+ *     a skipped key. The house rule is already written twice: a check that
+ *     cannot measure and says ok lies more than one that says no. A role that
+ *     starts without the credential it declared fails later, further away, and
+ *     looking like something else.
+ *   - **The value is not in the error.** `stderr` from the provider is passed
+ *     through because it is how `op` says "not signed in", but `stdout` never
+ *     is — a provider that prints the secret and then exits non-zero would
+ *     otherwise put it in the terminal and the log.
+ */
+export function resolveRef(entry, provider, { run = spawnSync, root = "." } = {}) {
+  if (provider?.builtin === "file" || (provider === undefined && entry.scheme === "file"))
+    return readFileRef(entry, root);
+  const argv = provider.command.map((part) => part.replaceAll("{ref}", entry.ref));
+  const r = run(argv[0], argv.slice(1), { encoding: "utf8" });
+  if (r.error)
+    throw new Error(
+      `key "${entry.raw}": could not run the ${entry.scheme} provider (${argv[0]}): ${r.error.message}`);
+  if (r.status !== 0) {
+    const said = (r.stderr ?? "").trim().split("\n").slice(0, 3).join("\n    ");
+    throw new Error(
+      `key "${entry.raw}": the ${entry.scheme} provider exited ${r.status ?? "on a signal"}.` +
+      (said ? `\n    ${said}` : "") +
+      `\n  Nothing is substituted for a key that did not resolve — the run stops here rather ` +
+      `than starting a role without a credential it declared.`);
+  }
+  // One trailing newline is the shell's, not the secret's: `security -w` and
+  // `op read` both add one, and a token with a newline welded to it fails
+  // authentication in a way that looks like a wrong token.
+  const value = (r.stdout ?? "").replace(/\r?\n$/, "");
+  if (value === "")
+    throw new Error(
+      `key "${entry.raw}": the ${entry.scheme} provider succeeded and printed nothing.\n` +
+      `  An empty credential is not a credential. Check the reference — most providers exit 0 ` +
+      `for a name they do not have.`);
+  return value;
+}
+
+/**
+ * Every reference a role declares, resolved, as `{ entry, mode, value }`.
+ *
+ * Validation of schemes and modes happens over the whole list before the first
+ * provider runs. A config with three bad references should say so once, and it
+ * should say so without asking anyone's keychain for a password first.
+ */
+export function resolveKeys(config, role, opts = {}) {
+  opts = { root: config.root ?? ".", ...opts };
+  const refs = role.keyEntries.filter((e) => e.kind === "ref");
+  const plan = refs.map((entry) => ({ entry, mode: modeOf(config, role, entry) }));
+  return plan.map((p) => ({
+    ...p,
+    value: resolveRef(p.entry, config.keyProviders[p.entry.scheme], opts),
+  }));
+}