seisin 0.6.3 → 0.6.5

package/src/config.js

@@ -1,21 +1,22 @@
 /**
- * Reads and validates seisin.toml.
- *
- * The parser covers a deliberate subset of TOML: `[table.name]` headers, and
- * `key = ["a", "b"]` / `key = "a"` values. That is the whole config language,
- * and keeping it in-house is why installing seisin pulls in exactly one
- * dependency (the sandbox runtime) instead of a parser too.
- *
- * If your config outgrows this subset, the config is doing too much.
+ * Reads and validates seisin.toml (or a JSON policy): the shape, every role's
+ * fields, the sandbox and key providers. The TOML subset is in toml.js.
  */
 import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
-import { isIP } from "node:net";
 import { CONFIG_NAME } from "./layout.js";
 import { parseKey, MODES, checkNames, BUILTIN, unknownMode } from "./keys.js";
-import { readNotify } from "./notify.js";
-import { BROWSERS } from "./browsers.js";
+import { readNotify } from "./notify-config.js";
+import { FORBIDDEN, dict, isTable, own, LINES, parseToml } from "./toml.js";
+
+export { own, parseToml, closesArray, stripComment } from "./toml.js";
+import {
+  closest, readBoolean, ROLE_KEYS, readControlFiles, readProtect, readMcp, readBrowsers, readLocalPorts, readInjectHosts, readNeverWrites, readPrivate, checkPrivateOverlap, assertNotAbsolute, readAddresses, asArray, trimSlashes, beforeGlob,
+} from "./config-fields.js";
+export { closest, ROLE_KEYS, CONTROL_FAMILIES, privateDir } from "./config-fields.js";
+
+
 
 export { CONFIG_NAME } from "./layout.js";
 
@@ -31,247 +32,6 @@ export function findConfig(from = process.cwd()) {
   }
 }
 
-const RE_TABLE = /^\[([A-Za-z0-9_.\-]+)\]$/;
-const RE_PAIR = /^([A-Za-z0-9_\-]+)\s*=\s*(.+)$/;
-
-/**
- * Names a table or key may not have.
- *
- * `[roles.__proto__]` does not show up in `Object.keys(roles)`, so `check`
- * prints the roles that exist and says nothing — while every other role
- * inherits whatever it declared. A config reading `[roles.frontend]` with no
- * `writes` came out of the parser owning the entire repo and holding
- * GITHUB_TOKEN, and no amount of reading the file would show it.
- *
- * The tables below are made with a null prototype, which stops the inheritance
- * on its own. The names are refused as well, because a config containing them
- * is not a config with a mistake in it.
- */
-const FORBIDDEN = new Set(["__proto__", "prototype", "constructor"]);
-
-/** A table with no prototype, so nothing is inherited into it. */
-function dict() {
-  return Object.create(null);
-}
-
-const isTable = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-
-/** Read a property only if the object actually has it. */
-export function own(obj, key) {
-  return obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
-}
-
-/**
- * Where each table and key of a parsed file was written, by dotted name.
- *
- * Kept beside the result rather than in it, so the object stays exactly the
- * data that was written; loadConfig reads it to put a line number on a name it
- * does not know.
- */
-const LINES = new WeakMap();
-
-/** Minimal TOML subset -> plain object. Throws with a line number on bad input. */
-export function parseToml(text) {
-  const out = dict();
-  const where = new Map();
-  LINES.set(out, where);
-  let table = out;
-  let tableName = "";
-  // "Last one wins" is TOML-ish and wrong for a permission file. A policy can
-  // look restrictive at the top and be cancelled forty lines down, and the
-  // person reviewing it reads the first block. Both shapes are refused.
-  const seenTables = new Set();
-  const seenKeys = new Set();
-  const lines = text.split(/\r?\n/);
-
-  for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i];
-    const line = stripComment(raw).trim();
-    if (!line) continue;
-
-    const header = RE_TABLE.exec(line);
-    if (header) {
-      tableName = header[1];
-      for (const part of tableName.split("."))
-        if (FORBIDDEN.has(part))
-          throw new Error(
-            `${CONFIG_NAME}:${i + 1}: "[${tableName}]" uses the reserved name "${part}". ` +
-            `A table named that would not appear as a role and would hand its settings to ` +
-            `every other one.`);
-      if (seenTables.has(tableName))
-        throw new Error(
-          `${CONFIG_NAME}:${i + 1}: [${tableName}] appears twice. ` +
-          `A later table would silently override the earlier one — put every setting for ` +
-          `${tableName} in one place.`);
-      seenTables.add(tableName);
-      tableName.split(".").forEach((_, k, parts) => {
-        const name = parts.slice(0, k + 1).join(".");
-        if (!where.has(name)) where.set(name, i + 1);
-      });
-      table = tableName.split(".").reduce((node, key, k, parts) => {
-        if (!Object.prototype.hasOwnProperty.call(node, key)) node[key] = dict();
-        else if (!isTable(node[key]))
-          throw new Error(
-            `${CONFIG_NAME}:${i + 1}: [${tableName}] — "${parts.slice(0, k + 1).join(".")}" is already ` +
-            `a value, not a table. One name cannot be both.`);
-        return node[key];
-      }, out);
-      continue;
-    }
-
-    const pair = RE_PAIR.exec(line);
-    if (!pair) throw new Error(`${CONFIG_NAME}:${i + 1}: cannot read "${raw.trim()}"`);
-
-    let [, key, value] = pair;
-    const at = i + 1;
-    // An array may span lines; keep pulling until the brackets balance. Only
-    // the new line is searched: searching the whole growing value made an
-    // unclosed array of 100k lines take 20 s to be refused. A `]` inside a
-    // quoted item does not close it — `["a]b",` used to end the array there.
-    if (value.startsWith("[") && !closesArray(value)) {
-      const parts = [value];
-      let closed = false;
-      while (!closed && i + 1 < lines.length) {
-        const next = stripComment(lines[++i]).trim();
-        parts.push(next);
-        closed = closesArray(next);
-      }
-      value = parts.join(" ");
-    }
-    if (FORBIDDEN.has(key))
-      throw new Error(`${CONFIG_NAME}:${i + 1}: "${key}" is a reserved name and cannot be a setting.`);
-    const seen = `${tableName}.${key}`;
-    if (seenKeys.has(seen))
-      throw new Error(
-        `${CONFIG_NAME}:${i + 1}: "${key}" is set twice in [${tableName || "the root"}]. ` +
-        `The second would win, which is not a thing a permission file should do quietly.`);
-    seenKeys.add(seen);
-    where.set(tableName ? `${tableName}.${key}` : key, at);
-    /**
-     * A key may not be a table that is declared elsewhere, in either order.
-     *
-     * `[roles.a]` with `network = []`, then `[roles]` and `a = true` forty lines
-     * down, used to replace the whole role with `true`: its `network = []` came
-     * back as "not set", which means the global allow list. `check` said
-     * nothing. It is the "last one wins" this parser refuses everywhere else,
-     * arriving by a different spelling.
-     */
-    if (Object.prototype.hasOwnProperty.call(table, key))
-      throw new Error(
-        `${CONFIG_NAME}:${i + 1}: "${key}" in [${tableName || "the root"}] is already the table ` +
-        `[${tableName ? tableName + "." : ""}${key}]. One name cannot be both — the value would replace ` +
-        `everything that table says.`);
-    table[key] = readValue(value, i + 1);
-  }
-  return out;
-}
-
-/** Is there a `]` on this line outside a quoted string? Strings do not span lines. */
-export function closesArray(line) {
-  let quoted = false;
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i];
-    if (c === '"') quoted = !quoted;
-    else if (c === "]" && !quoted) return true;
-  }
-  return false;
-}
-
-/** Strips a trailing `#` comment, but not one inside a quoted string. */
-export function stripComment(line) {
-  let quoted = false;
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i];
-    if (c === '"') quoted = !quoted;
-    else if (c === "#" && !quoted) return line.slice(0, i);
-  }
-  return line;
-}
-
-/**
- * One value, read strictly.
- *
- * Strict is the whole point, and it was not before. The array reader used to
- * pick quoted runs out of the line with a regex and ignore everything between
- * them, so `["a" GARBAGE "b"]` parsed as `["a","b"]` and an unterminated string
- * parsed as `""`. A permission file that is half-understood is worse than one
- * that is rejected: the half that was dropped is the half you meant.
- *
- * So this scans rather than matches, and anything it does not recognise is an
- * error with a line number. There are no escapes — a `"` ends the string. If a
- * path of yours needs a quote in it, that is outside this subset and the
- * message says so instead of guessing.
- */
-function readValue(value, lineNo) {
-  const v = value.trim();
-  const bad = (msg) => { throw new Error(`${CONFIG_NAME}:${lineNo}: ${msg}`); };
-
-  if (v === "true") return true;
-  if (v === "false") return false;
-
-  if (v.startsWith('"')) {
-    const end = v.indexOf('"', 1);
-    if (end === -1) bad(`unterminated string — no closing quote in ${v}`);
-    const rest = v.slice(end + 1).trim();
-    if (rest) bad(`unexpected ${JSON.stringify(rest)} after the string`);
-    return v.slice(1, end);
-  }
-
-  if (v.startsWith("[")) {
-    if (!v.endsWith("]")) bad("unterminated array — no closing bracket");
-    const items = [];
-    let i = 1;
-    const body = v.slice(0, -1);          // everything up to the closing bracket
-    let expectItem = true;                // a list alternates item, comma, item…
-
-    while (i < body.length) {
-      const c = body[i];
-      if (c === " " || c === "\t") { i++; continue; }
-
-      if (c === ",") {
-        if (expectItem) bad("empty array slot — two commas in a row, or a leading comma");
-        expectItem = true; i++; continue;
-      }
-      if (!expectItem) bad(`missing comma before ${JSON.stringify(body.slice(i, i + 12))}`);
-      // Whole numbers, for `local_ports`. Digits only: no sign, no decimal, no
-      // underscore — a port is none of those, and every other key still
-      // refuses a number through asArray.
-      const digits = /^\d+/.exec(body.slice(i));
-      if (digits) {
-        const after = body[i + digits[0].length];
-        if (after !== undefined && after !== "," && after !== " " && after !== "\t")
-          bad(`${JSON.stringify(body.slice(i, i + 12))} is not a whole number`);
-        items.push(Number(digits[0]));
-        i += digits[0].length;
-        expectItem = false;
-        continue;
-      }
-      if (c !== '"') bad(`array items must be double-quoted, found ${JSON.stringify(body.slice(i, i + 12))}`);
-
-      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
-    }
-    return items;
-  }
-
-  if (/^\d+$/.test(v)) return Number(v);
-
-  bad("value must be a string, an array of strings, a whole number, or a boolean");
-}
 
 /**
  * `[runtime] isolate` — one setting, two levels, because they were one and
@@ -329,7 +89,7 @@ function readReadList(v, at) {
     if (/[*?[\]{}]/.test(above) || p === "**")
       throw new Error(
         `${at} = "${p}" cannot be enforced as written.\n` +
-        `  A read grant is a path and everything under it. Write "${above.replace(/\/?[^/]*[*?[\]{}].*$/, "") || "."}/**" ` +
+        `  A read grant is a path and everything under it. Write "${beforeGlob(above) || "."}/**" ` +
         `for the subtree, or name the paths.`);
   }
   return list;
@@ -365,10 +125,10 @@ export function policyId(config) {
  * settings file rather than falling back to a permissive default, and seisin
  * matches that: a permission tool that guesses is worse than no permission tool.
  */
-export function loadConfig(path, text = readFileSync(path, "utf8")) {
+export function loadConfig(path, text = readFileSync(path, "utf8"), { root = null } = {}) {
   // `text` lets a caller validate an edit before writing it — the console
   // previews a policy that does not exist on disk yet, against the real root.
-  const parsed = parseToml(text);
+  const parsed = String(path).endsWith(".json") ? parseJsonPolicy(text, path) : parseToml(text);
   checkShape(parsed, SHAPE, "", path, LINES.get(parsed));
   // Read only what the file actually declared. The parser refuses the names
   // that make inheritance possible, and this is the second half of the same
@@ -436,7 +196,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
   // them as prefixes: with the slash kept, `scan` walked into the protected
   // directory and a bare key resolved to `.secrets//x`, which matched nothing.
   const keyDirs = (keyDir === undefined ? [] : asArray(keyDir, "keys.dir"))
-    .map((d) => d.replace(/\/+$/, "") || d);
+    .map((d) => trimSlashes(d) || d);
   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
@@ -445,7 +205,10 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
   const runtimeWrites = own(runtime, "writes");
 
   const out = {
-    root: dirname(path), path, keyDirs, keyProviders,
+    // The root is the policy's folder, unless the policy was read from elsewhere
+    // (`--policy`): then it is the folder the command runs in, and the policy
+    // stays outside the repo it governs.
+    root: root ? resolve(root) : dirname(path), path, keyDirs, keyProviders,
     // Through asArray like every other list: `allow = "github.com"` was kept as
     // a string, and a string iterated is its characters.
     allowedDomains: asArray(own(own(parsed, "network"), "allow"), "network.allow"),
@@ -458,7 +221,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
     deniedAddresses: readAddresses(own(own(parsed, "network"), "deny_addresses"), `${path}: network.deny_addresses`),
     runtimeWrites: runtimeWrites === undefined ? undefined : asArray(runtimeWrites, "runtime.writes"),
     // `[runtime] isolate` — how much of your home a role stops reaching. See
-    // srt.js for what each level emits, and readIsolate() below for why there
+    // srt-settings.js for what each level emits, and readIsolate() below for why there
     // are two of them.
     isolate: readIsolate(own(runtime, "isolate")),
     // `[runtime] read` — what a role may read. "all" is every file but the ones
@@ -537,6 +300,37 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
     const toolchain = readReadList(own(r, "toolchain"), `${path}: roles.${name}.toolchain`);
     const priv = readPrivate(own(r, "private"), `${path}: roles.${name}.private`);
     const verify = own(r, "verify") === undefined ? null : asArray(own(r, "verify"), `roles.${name}.verify`);
+    /**
+     * `handoff_exempt`: folders where the trust-handoff set is not protected, for a
+     * setup phase that fills a dependency tree whose packages ship their own
+     * `.gitattributes`, `.github/` or `.git/` (`composer install`, measured: 326
+     * denials). Relative to the repo, no `..`, no globs. Only a sandbox that can
+     * open exactly that (tartaros) is handed the role.
+     */
+    const handoffExempt = own(r, "handoff_exempt") === undefined ? [] : asArray(own(r, "handoff_exempt"), `roles.${name}.handoff_exempt`);
+    /**
+     * `requests`: the only requests the role may send to an allowed host,
+     * `"METHODS host[/path]"` (METHODS: `GET,POST` or `*`). An allowed host is
+     * otherwise all of it: a token for api.github.com pushes to any repository
+     * it reaches. The host must be in `network`. Only tartaros enforces it
+     * (from 0.1.0-alpha.18): it terminates that host and refuses anything else.
+     */
+    const requests = own(r, "requests") === undefined ? [] : asArray(own(r, "requests"), `roles.${name}.requests`).map((spec) => {
+      const m = /^(\*|[A-Z]+(?:,[A-Z]+)*)\s+([A-Za-z0-9.-]+)(\/\S*)?$/.exec(String(spec).trim());
+      if (!m || (m[3] ?? "").split("/").some((seg) => seg === "." || seg === ".."))
+        throw new Error(`${path}: roles.${name}.requests "${spec}": "METHODS host[/path]", e.g. "GET api.github.com" or "POST,PATCH api.github.com/repos/acme/"`);
+      return { host: m[2], methods: m[1] === "*" ? [] : m[1].split(","), paths: m[3] ? [m[3]] : [] };
+    });
+    // A rule narrows a host the role may reach; on a host it may not, it says nothing.
+    const reach = own(r, "network") === undefined ? [] : asArray(own(r, "network"), `roles.${name}.network`);
+    for (const q of requests) {
+      const covered = reach.some((h) => h === q.host || (h.startsWith("*.") && q.host.endsWith(h.slice(1))));
+      if (!covered)
+        throw new Error(`${path}: roles.${name}.requests: ${q.host} is not in roles.${name}.network, so the role cannot reach it at all`);
+    }
+    for (const e of handoffExempt)
+      if (e.startsWith("/") || e.startsWith("~") || e.split("/").includes("..") || /[*?[\]]/.test(e) || !e.trim())
+        throw new Error(`${path}: roles.${name}.handoff_exempt "${e}": a folder in the repo, relative, with no ".." and no globs`);
     if (verify && verify.length === 0)
       throw new Error(`${path}: roles.${name}.verify is empty. It is the command that proves the role can check ` +
         `its own work — ["python", "-m", "pytest", "--version"] — or leave it out.`);
@@ -604,7 +398,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
        * every port on localhost (macOS), which includes whatever control API
        * is listening there without a password. This names the ports instead,
        * and the runtime's proxy enforces the list — the same allowlist the
-       * domains go through. See srt.js for what that costs: the client has to
+       * domains go through. See srt-settings.js for what that costs: the client has to
        * go through the proxy, which HTTP clients do and a MySQL driver does not.
        */
       localPorts,
@@ -626,7 +420,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
        * Whether this role may reach com.apple.trustd.agent (macOS). Needed by
        * Dart/Flutter and by Go built before 1.27 to verify TLS at all; Go 1.27+
        * does without it through the SSL_CERT_FILE that env.js sets. Off unless
-       * the role says so. See srt.js for what it costs.
+       * the role says so. See srt-settings.js for what it costs.
        */
       trustd: trustd === true,
       /**
@@ -644,6 +438,10 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
        * another owner or to a person instead of starting it.
        */
       handoff: handoff !== false,
+      /** Folders, relative to the root, where trust-handoff is not protected (tartaros only). */
+      handoffExempt,
+      /** The only requests to an allowed host: `{ host, methods, paths }` (tartaros only). */
+      requests,
       /**
        * What this role reads beyond its repo, under `read = "territory"`.
        *
@@ -879,284 +677,66 @@ function checkShape(table, shape, prefix, path, lines) {
   }
 }
 
-/** The candidate within edit distance 3 of `word`, or null. Shared with `check`. */
-export function closest(word, candidates) {
-  let best = null, bestD = 4;
-  for (const c of candidates) {
-    const d = distance(word.toLowerCase(), c);
-    if (d < bestD) { best = c; bestD = d; }
-  }
-  return best;
-}
-
-/** Levenshtein distance. */
-function distance(a, b) {
-  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i++) {
-    let prev = row[0]; row[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const cur = row[j];
-      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
-      prev = cur;
-    }
-  }
-  return row[b.length];
-}
-
-/** true, false, or absent (undefined). Anything else is a mistake, said as one. */
-function readBoolean(value, where) {
-  if (value === undefined || typeof value === "boolean") return value;
-  throw new Error(`${where} must be true or false, not ${JSON.stringify(value)}`);
-}
-
-/** The keys a `[roles.<name>]` table can hold. Anything else is reported by `check`. */
-export const ROLE_KEYS = ["writes", "private", "keys", "key_mode", "inject_hosts", "env", "network", "never_writes", "local_binding", "local_ports", "browsers", "mcp", "trustd", "control_files", "reads", "toolchain", "verify", "handoff"];
-
-/**
- * `control_files`: which families of control files a role may edit. Refused at
- * load when it names anything else — `.claude`, git hooks and the rest are not
- * on the list on purpose, and a word the reader does not know must not load as
- * a permission it thinks it wrote.
- */
-export const CONTROL_FAMILIES = ["ide", "instructions"];
-
-function readControlFiles(value, where) {
-  if (value === undefined) return [];
-  const out = [];
-  for (const f of asArray(value, where)) {
-    if (!CONTROL_FAMILIES.includes(f))
-      throw new Error(`${where}: ${JSON.stringify(f)} is not a family of control files. ` +
-        `Known: ${CONTROL_FAMILIES.map((x) => JSON.stringify(x)).join(", ")}. ` +
-        `The others (.claude, git hooks, .mcp.json, .envrc) are never handed to a role.`);
-    if (!out.includes(f)) out.push(f);
-  }
-  return out;
-}
-
-/**
- * `[protect]` — what is protected beyond the defaults. One key today:
- * `instructions = true` protects `CLAUDE.md`, `AGENTS.md` and their kin from
- * every role that is not handed them. Anything else in the table is refused.
- */
-function readProtect(value, path) {
-  if (value === undefined) return { instructions: false };
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    throw new Error(`${path}: [protect] must be a table`);
-  for (const k of Object.keys(value))
-    if (k !== "instructions")
-      throw new Error(`${path}: [protect] ${k} is not a setting. Known: instructions.`);
-  const v = own(value, "instructions");
-  if (v !== undefined && typeof v !== "boolean")
-    throw new Error(`${path}: [protect] instructions must be true or false, not ${JSON.stringify(v)}`);
-  return { instructions: v === true };
-}
-
-/**
- * `mcp`: names of MCP servers, as the CLI's config calls them. Absent is null,
- * not [], so a policy that never mentions MCP changes nothing for a launcher
- * that reads it; `mcp = []` is the explicit "none".
- */
-function readMcp(value, where) {
-  if (value === undefined) return null;
-  const list = asArray(value, where);
-  const out = [];
-  for (const n of list) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n))
-      throw new Error(`${where}: ${JSON.stringify(n)} is not an MCP server name. ` +
-        `Use the name from the CLI's config, for example mcp = ["playwright"].`);
-    if (!out.includes(n)) out.push(n);
-  }
-  return out;
-}
-
-/**
- * `browsers`, refused rather than guessed: a name seisin has no preset for
- * would read as a grant that was made, and grant nothing.
- */
-function readBrowsers(value, where) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value) || value.some((v) => typeof v !== "string"))
-    throw new Error(`${where} is a list of browser names, for example browsers = ["chromium"].`);
-  for (const b of value)
-    if (!Object.hasOwn(BROWSERS, b)) {
-      const near = closest(b, Object.keys(BROWSERS));
-      throw new Error(`${where}: "${b}" is not a browser seisin has a preset for${near ? ` — did you mean "${near}"?` : ""} ` +
-        `Known: ${Object.keys(BROWSERS).join(", ")}.`);
-    }
-  return [...new Set(value)];
-}
-
 /**
- * `local_ports`, refused rather than guessed when it is not a list of ports.
+ * A policy written as JSON (`--policy run.json`), for a launcher that generates
+ * one: JSON can hold a quote in a value, which the TOML subset cannot, and a
+ * program writing the policy should not have to avoid them.
  *
- * Refused at load for the same reason as `never_writes`: a port list that loads
- * with a typo in it opens a port nobody meant, or silently fails to open the
- * one they did. A string is accepted when it is only digits, because TOML
- * written by hand says `"8001"` as often as `8001`.
+ * The same data and the same strictness as the TOML reader: tables, strings,
+ * whole numbers, booleans, and arrays of strings or whole numbers, nothing
+ * else; the forbidden names refused; every table with a null prototype; and a
+ * key written twice in one object refused, because JSON.parse keeps the last
+ * one, and a policy that is restrictive at the top and cancelled further down
+ * is exactly what the TOML reader refuses too. A JSON policy is not edited by
+ * `grant`: it is generated, so it is changed where it is generated.
  */
-function readLocalPorts(value, where) {
-  if (value === undefined) return [];
-  const list = Array.isArray(value) ? value : [value];
-  const out = [];
-  for (const v of list) {
-    const n = typeof v === "string" && /^\d+$/.test(v) ? Number(v) : v;
-    if (!Number.isInteger(n) || n < 1 || n > 65535)
-      throw new Error(`${where}: ${JSON.stringify(v)} is not a port. Write numbers from 1 to 65535, ` +
-        `for example local_ports = [8001, 8081].`);
-    if (!out.includes(n)) out.push(n);
-  }
-  return out;
-}
-
-/**
- * `inject_hosts`: for `key_mode = "inject"`, the hosts each masked credential
- * is substituted into, keyed by the delivered variable name.
- *
- *   [roles.frontend.inject_hosts]
- *   GH_TOKEN = ["api.github.com"]
- *
- * One list per credential and not one for the role, because the runtime gates
- * substitution per credential: credential A's real value reaches only A's
- * hosts, never B's. A host is an exact name — no wildcard — so `check` can say
- * precisely which traffic is intercepted; the match against a wider wildcard in
- * `allowedDomains` is computed later (srt.js), where the terminated set is.
- */
-function readInjectHosts(value, where) {
-  if (value === undefined) return null;
-  if (typeof value !== "object" || Array.isArray(value))
-    throw new Error(`${where}: inject_hosts is a table of VAR = ["host", …], ` +
-      `for example [roles.x.inject_hosts] GH_TOKEN = ["api.github.com"].`);
-  const out = {};
-  for (const [name, hosts] of Object.entries(value)) {
-    const list = asArray(hosts, `${where}.${name}`);
-    if (list.length === 0)
-      throw new Error(`${where}.${name}: a masked credential with no host injects nowhere. ` +
-        `List the host its token authenticates to, like ["api.github.com"].`);
-    for (const h of list) {
-      if (typeof h !== "string" || h.trim() === "")
-        throw new Error(`${where}.${name}: every host is a non-empty string`);
-      if (h.includes("*"))
-        throw new Error(`${where}.${name}: "${h}" is a wildcard. An inject host is an exact name, ` +
-          `so check can say which traffic is intercepted. A wildcard in allowedDomains still ` +
-          `covers it; that is reported, not declared here.`);
-      if (/^https?:\/\//.test(h) || h.includes("/"))
-        throw new Error(`${where}.${name}: "${h}" is not a host. Write the bare domain, like "api.github.com".`);
+export function parseJsonPolicy(text, path = "policy.json") {
+  let raw;
+  try { raw = JSON.parse(text); } catch (e) { throw new Error(`${path}: not JSON — ${e.message}`); }
+  // Duplicate keys, which JSON.parse folds away: one pass over the text, which
+  // JSON.parse has just said is well formed.
+  const stack = [];
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "{") stack.push({ obj: true, keys: new Set(), key: true });
+    else if (c === "[") stack.push({ obj: false });
+    else if (c === "}" || c === "]") stack.pop();
+    else if (c === "," && stack.at(-1)?.obj) stack.at(-1).key = true;
+    else if (c === '"') {
+      let j = i + 1;
+      while (text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      const top = stack.at(-1);
+      if (top?.obj && top.key) {
+        const k = JSON.parse(text.slice(i, j + 1));
+        if (top.keys.has(k)) throw new Error(`${path}: "${k}" is written twice in one object; the last would silently win.`);
+        top.keys.add(k);
+        top.key = false;
+      }
+      i = j;
     }
-    out[name] = [...new Set(list)];
-  }
-  return out;
-}
-
-/**
- * `never_writes`, refused rather than guessed when it cannot mean what it says.
- *
- * Refused at load, not warned about: this is a list of things a role must not
- * do, and a malformed entry that loads anyway fails open. An absolute path or a
- * `..` would point outside the repo the rest of the policy is written against,
- * so it cannot be the subtraction the person meant.
- */
-function readNeverWrites(value, where) {
-  const list = asArray(value, where);
-  for (const g of list) {
-    if (typeof g !== "string" || g.trim() === "")
-      throw new Error(`${where}: every entry must be a non-empty string`);
-    if (g.startsWith("/"))
-      throw new Error(`${where}: "${g}" is absolute. never_writes is relative to the repo root, like writes.`);
-    if (g.split("/").includes(".."))
-      throw new Error(`${where}: "${g}" contains "..". never_writes names paths inside the repo.`);
   }
-  return list;
-}
-
-/**
- * `private`: folders inside the repo, written `dir` or `dir/**`.
- *
- * A folder and not a glob, because what is enforced is a deny on one path for
- * every other role: `notes/*.md` would have to be widened to `notes` or frozen
- * to today's files. Not absolute and no `..`, because the denies are given
- * against the repo the policy describes and `explain` answers in it. Not the
- * repo itself: private to one role, the whole repo is shut to all the others,
- * which is a policy of one role written in the long way.
- */
-function readPrivate(value, where) {
-  const list = value === undefined ? [] : asArray(value, where);
-  for (const p of list) {
-    const dir = p.replace(/\/\*\*$/, "").replace(/\/+$/, "").replace(/^\.\//, "");
-    if (p.startsWith("/"))
-      throw new Error(`${where}: "${p}" is absolute. A private folder is relative to the repo root, like writes.`);
-    if (dir.split("/").includes(".."))
-      throw new Error(`${where}: "${p}" contains "..". A private folder is inside the repo.`);
-    if (dir === "" || dir === "." || dir === "**")
-      throw new Error(`${where}: "${p}" is the whole repo. A private folder is a folder inside it — ` +
-        `"notes/**" — and every other role is denied it.`);
-    if (/[*?[\]{}]/.test(dir))
-      throw new Error(`${where}: "${p}" is a pattern. A private folder is one path and everything under it: ` +
-        `write "${dir.replace(/\/?[^/]*[*?[\]{}].*$/, "") || "dir"}/**".`);
-  }
-  return list;
-}
-
-/** `private` with its `/**` and `./` taken off: the folder itself. */
-export const privateDir = (p) => p.replace(/\/\*\*$/, "").replace(/\/+$/, "").replace(/^\.\//, "");
-
-/**
- * One owner per private folder. Two roles naming the same folder, or one
- * inside the other, would each be denied the other's — so neither could read
- * its own. Refused at load, with both names.
- */
-function checkPrivateOverlap(roles, path) {
-  const all = Object.values(roles).flatMap((r) => (r.private ?? []).map((p) => ({ role: r.name, p, dir: privateDir(p) })));
-  const inside = (a, b) => a === b || a.startsWith(b + "/");
-  for (let i = 0; i < all.length; i++)
-    for (let j = i + 1; j < all.length; j++) {
-      const a = all[i], b = all[j];
-      if (a.role === b.role || !(inside(a.dir, b.dir) || inside(b.dir, a.dir))) continue;
-      throw new Error(
-        `${path}: roles.${a.role}.private "${a.p}" and roles.${b.role}.private "${b.p}" ` +
-        `${a.dir === b.dir ? "are the same folder" : "overlap"}. A private folder has one owner: every ` +
-        `other role is denied it, so each of these two would be denied its own. Give it to one of them.`);
+  const walk = (v, name) => {
+    if (typeof v === "string" || typeof v === "boolean") return v;
+    if (typeof v === "number") {
+      if (!Number.isInteger(v) || v < 0) throw new Error(`${path}: ${name} = ${v} — only whole numbers`);
+      return v;
     }
-}
-
-/**
- * A territory is relative to the repo root. An absolute one would ask the kernel
- * for a path on the machine and make `explain` (which reads absolute as outside
- * the repo) disagree with what the profile grants — see the CODEOWNERS `/apps/`
- * case. `..` is allowed on purpose: a role legitimately writes a sibling
- * directory (`../shared/...`), and it is resolved relative to the root, so a
- * territory that climbs above it grants what it resolves to, by the choice of
- * whoever wrote the policy.
- */
-function assertNotAbsolute(list, where) {
-  for (const g of list) {
-    if (typeof g !== "string" || g.trim() === "")
-      throw new Error(`${where}: every entry must be a non-empty string`);
-    if (g.startsWith("/"))
-      throw new Error(`${where}: "${g}" is absolute. Territories are relative to the repo root.`);
-  }
-  return list;
-}
-
-/**
- * An IP address or a CIDR range: `10.0.0.0/8`, `192.168.1.10`, `fc00::/7`
- * (IPv6 without brackets). Anything else is refused with what was written.
- */
-function readAddresses(value, where) {
-  const list = asArray(value, where);
-  for (const v of list) {
-    const [addr, prefix, extra] = v.split("/");
-    const family = isIP(addr);
-    const max = family === 6 ? 128 : 32;
-    const okPrefix = prefix === undefined || (/^\d+$/.test(prefix) && Number(prefix) <= max);
-    if (!family || !okPrefix || extra !== undefined)
-      throw new Error(`${where}: "${v}" is not an IP address or a CIDR range (e.g. "10.0.0.0/8", "fc00::/7")`);
-  }
-  return list;
-}
-
-function asArray(value, where) {
-  if (value === undefined) return [];
-  if (typeof value === "string") return [value];
-  if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value;
-  throw new Error(`${where}: expected a string or an array of strings`);
+    if (Array.isArray(v)) {
+      return v.map((x, i) => {
+        if (typeof x === "string" || (typeof x === "number" && Number.isInteger(x) && x >= 0)) return x;
+        throw new Error(`${path}: ${name}[${i}] — array items are strings or whole numbers`);
+      });
+    }
+    if (isTable(v)) {
+      const t = dict();
+      for (const [k, x] of Object.entries(v)) {
+        if (FORBIDDEN.has(k)) throw new Error(`${path}: "${k}" is not a name a table or key may have`);
+        t[k] = walk(x, name ? `${name}.${k}` : k);
+      }
+      return t;
+    }
+    throw new Error(`${path}: ${name} = ${JSON.stringify(v)} — a value is a string, a whole number, a boolean, an array or a table`);
+  };
+  if (!isTable(raw)) throw new Error(`${path}: the policy is an object`);
+  return walk(raw, "");
 }