approval-md 0.2.0 → 0.4.0

package/dist/src/core/run-payload.js

@@ -0,0 +1,304 @@
+/**
+ * The `approval run` payload: the argv, the cwd, and the bytes of the script
+ * the argv names (SPEC.md §6.2, §10.4; APRV-401).
+ *
+ * ## The hazard this closes
+ *
+ * §6.2 defined this payload as "the argv array and cwd", and `approval run`
+ * recomputes it from the argv and cwd it is about to spawn. For a command that
+ * IS its own bytes (`npm update @types/node`) that is the whole action. For a
+ * command that names a script it is not: the payload binds a NAME, and the
+ * bytes behind that name are whatever the path holds at execution time. The
+ * requester controls the file between the request and the grant, so a human
+ * approved a path and the runtime executed a file. Found on a live grant during
+ * APRV-398, exploited by nobody, filed as APRV-401.
+ *
+ * The payload hash is supposed to BE the binding (§10.4: "A grant therefore
+ * approves specific bytes"), so the repair is to put the bytes inside it. A
+ * script edited between the declaration and the execution hashes differently,
+ * and the difference refuses `payload-mismatch` before the child is spawned and
+ * before anything is appended, exactly as a changed argv already did.
+ *
+ * ## The shape, as the operator ruled it (APRV-401 notes, 2026-09-21)
+ *
+ * > the script digest is PART OF THE BINDING, never advisory. Shape: when argv
+ * > names an interpreter (bash, sh, zsh, node, python3 and kin) followed by a
+ * > path that resolves to a regular file at request time, the runtime reads and
+ * > hashes the file into the bound payload, the card shows the digest, byte
+ * > count and path, and approval run re-reads the file and refuses
+ * > payload-mismatch if the bytes changed. No interpretation of the script and
+ * > no second pass for files it sources; the limit is documented. Out of scope:
+ * > piped installers (already opaque), sourced files, interpreters the
+ * > classifier does not name.
+ *
+ * So this is an INTERPRETER-KEYED rule and not "every argv word that happens to
+ * name a file". One script per invocation: the first word after the interpreter
+ * that resolves to a readable regular file, which is the interpreter's operand
+ * whether or not a subcommand comes first (`deno run job.ts`).
+ * {@link SCRIPT_INTERPRETERS} is the list, and every member of it is a name
+ * `core/command-class.ts` already knows: the six shells of its unwrappable set,
+ * `node` from its own branch, and `python`, `python3`, `perl`, `ruby` and
+ * `deno` from its inline-source table. A launcher neither file names binds
+ * nothing, which is the documented limit rather than an oversight.
+ *
+ * The one thing here that the ruling does not spell out is the DEGENERATE case:
+ * `./install.sh` with no interpreter word at all, where the kernel reads the
+ * shebang and the script is `argv[0]` itself. It is bound, because it is the
+ * same fact with the interpreter implied rather than typed, and leaving it out
+ * would be a hole in the rule shaped exactly like the rule.
+ *
+ * ## What is NOT bound, stated plainly
+ *
+ * - **An inline program.** `bash -c '…'`, `node -e '…'`, `python3 -c '…'`: the
+ *   program is a word of the argv, so it was always bound, and there is no file
+ *   to read. The inline flags per interpreter are in {@link SCRIPT_INTERPRETERS}.
+ * - **Nothing resolved through PATH.** The interpreter itself is not hashed. Its
+ *   bytes are the host's rather than the requester's, and resolving a program
+ *   name through `PATH` would make the payload a function of the environment the
+ *   process happens to hold, which §11 says is never read implicitly.
+ * - **Nothing transitive.** A bound script that sources another file, curls a
+ *   second one, or execs a third binds only its own bytes. The digest is a
+ *   binding, not a sandbox.
+ * - **A piped installer.** `curl … | sh` has no file operand and is opaque to
+ *   the classifier for the same reason it is unbindable here.
+ * - **The instant between hashing and spawning.** The digest is taken, then
+ *   `execution.started` is appended, then the child is spawned. A file rewritten
+ *   inside that window runs unbound. Closing it needs the executor to hold the
+ *   bytes rather than the path, which is the adapter contract of §10.4.
+ *
+ * ## Absence is not a claim
+ *
+ * `script` is omitted when nothing is bound, and that omission is deliberate: an
+ * invocation naming no readable script hashes to exactly the value it hashed
+ * before this module existed, so every record already in the log, and every
+ * declaration already written into a task file, verifies unchanged. What the
+ * absence does NOT say is "this runtime checked and there was nothing" — it is
+ * the ordinary shape of a payload with no script to bind, and a reader wanting
+ * to know whether a digest was possible reads the argv, which is right there.
+ *
+ * Every skip is safe for one reason, and it is the same reason in each case: the
+ * value is recomputed at execution by this same rule. A file that was
+ * unreadable at declaration time and readable at execution time gains an entry
+ * and refuses; one that existed and was deleted loses one and refuses. The rule
+ * does not have to decide correctly what a command will do, because both ends
+ * apply it to the same tree and any disagreement is a refusal.
+ *
+ * Reads the filesystem, by design and by necessity: at most one file per call,
+ * and only the one the argv names. Writes nothing, appends nothing, reads no
+ * log, no policy, no environment and no clock.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+/** The payload key carrying the bound script. Omitted when there is none. */
+export const BOUND_SCRIPT_KEY = "script";
+/**
+ * How much of a file is read at once while digesting it.
+ *
+ * Chunked rather than `readFileSync`, because a script may be of any size and
+ * the executor must not be the thing that runs out of memory: a refusal to
+ * compute the binding is a refusal to execute.
+ */
+export const DIGEST_CHUNK_BYTES = 64 * 1024;
+/**
+ * The interpreters whose script operand is bound, and the flags that mean
+ * "the program is inline, there is no file".
+ *
+ * Every name here is one `core/command-class.ts` already knows, which is the
+ * ruling's "interpreters the classifier does not name" read as a positive list:
+ * the six shells of its unwrappable set, `node` from its own classification
+ * branch, and `python`, `python3`, `perl`, `ruby`, `deno` from its
+ * inline-source table. The list is duplicated rather than imported because
+ * those tables are private to that module and a public export of them would be
+ * a second consumer of a decision that belongs to classification; the comment
+ * is the seam, and a name added there without being added here binds nothing,
+ * which fails toward the old behaviour rather than toward a wrong digest.
+ *
+ * The shell inline flag is `-c` with any run of `l` and `i` before it, which is
+ * `INLINE_SCRIPT_FLAG` in that module, spelled here as the same regular
+ * expression for the same reason.
+ */
+export const SCRIPT_INTERPRETERS = new Map([
+    ["bash", [/^-[li]*c$/u]],
+    ["sh", [/^-[li]*c$/u]],
+    ["zsh", [/^-[li]*c$/u]],
+    ["dash", [/^-[li]*c$/u]],
+    ["ksh", [/^-[li]*c$/u]],
+    ["fish", [/^-[li]*c$/u, "--command"]],
+    ["node", ["-e", "--eval", "-p", "--print", "--input-type=module"]],
+    ["nodejs", ["-e", "--eval", "-p", "--print"]],
+    ["python", ["-c"]],
+    ["python3", ["-c"]],
+    ["perl", ["-e", "-E"]],
+    ["ruby", ["-e"]],
+    ["deno", ["eval"]],
+]);
+/**
+ * The digest and size of one file, read in bounded chunks, or `null` when it
+ * cannot be read at all.
+ *
+ * `null` for every failure — gone, a directory, a device, permission denied, a
+ * disappearing file, a read error partway — and the reason is not recorded
+ * anywhere. Recording it would put a local errno inside hashed material, so two
+ * machines that agree about the bytes could disagree about the payload; and the
+ * only thing a reader could do with it is treat "unreadable" as a state, which
+ * the recomputation already handles better than any field could.
+ */
+function fileDigest(path) {
+    let fd;
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile())
+            return null;
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(DIGEST_CHUNK_BYTES);
+    let bytes = 0;
+    try {
+        let read = readSync(fd, buffer, 0, DIGEST_CHUNK_BYTES, null);
+        while (read > 0) {
+            hash.update(buffer.subarray(0, read));
+            bytes += read;
+            read = readSync(fd, buffer, 0, DIGEST_CHUNK_BYTES, null);
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // A close that fails has nothing to do with the bytes already hashed.
+        }
+    }
+    return { bytes, sha256: hash.digest("hex") };
+}
+/** The last path segment of an argv word: `/usr/bin/bash` reads as `bash`. */
+function basenameOf(word) {
+    const segments = word.split("/");
+    return segments[segments.length - 1] ?? word;
+}
+/** Does `word` mean "the program is inline" for this interpreter? */
+function isInlineProgramFlag(word, markers) {
+    return markers.some((marker) => typeof marker === "string" ? word === marker : marker.test(word));
+}
+/**
+ * The words of an interpreter invocation that could be its script, in order,
+ * or `null` when the program is inline and there is no file at all.
+ *
+ * An inline-program marker anywhere in the options answers `null` rather than
+ * "keep looking": the program is a word of the argv and already bound, and a
+ * file that happens to share its spelling is a file the command never opens.
+ *
+ * Otherwise every non-option word is a candidate, in argv order, and the caller
+ * binds the first that resolves to a readable regular file. Not just the first
+ * non-option word, because interpreters take SUBCOMMANDS: `deno run job.ts`
+ * would otherwise offer `run` and stop, and `python3 -m pkg job.py` would offer
+ * `pkg`. Walking on cannot bind anything the argv does not name, and the worst
+ * case is the harmless direction — a command whose script is missing and whose
+ * later argument happens to be a file binds that file, which is one more thing
+ * bound rather than one fewer.
+ *
+ * An option that takes a separate path value is the one place this can pick the
+ * wrong file (`node --require ./a.js job.js` binds `./a.js`), and both are
+ * files that invocation executes.
+ */
+function scriptCandidateIndexes(argv, markers) {
+    const candidates = [];
+    for (let index = 1; index < argv.length; index += 1) {
+        const word = argv[index];
+        if (isInlineProgramFlag(word, markers))
+            return null;
+        if (word === "--")
+            continue;
+        if (word.startsWith("-") && word.length > 1)
+            continue;
+        candidates.push(index);
+    }
+    return candidates;
+}
+/**
+ * Where an argv word points, resolved against the payload's own `cwd`.
+ *
+ * The cwd is the payload's, never `process.cwd()`: the payload already carries
+ * the directory the child will run in, and resolving against anything else
+ * would make the binding a function of where the hashing process happened to
+ * stand.
+ */
+function resolveArgvPath(word, cwd) {
+    if (word === "" || word === "-" || word === "--")
+        return null;
+    if (word.includes("\0"))
+        return null;
+    return isAbsolute(word) ? word : resolvePath(cwd, word);
+}
+/**
+ * The script this argv runs, bound by its bytes, or `null` (APRV-401).
+ *
+ * Two shapes, and only two: an interpreter this module names followed by a path
+ * operand, and a path at `argv[0]` that the kernel will read a shebang from.
+ * Anything else binds nothing and the payload is what it always was.
+ */
+export function boundScript(argv, cwd) {
+    const program = argv[0];
+    if (program === undefined || program === "")
+        return null;
+    const markers = SCRIPT_INTERPRETERS.get(basenameOf(program));
+    if (markers !== undefined) {
+        const candidates = scriptCandidateIndexes(argv, markers);
+        if (candidates === null)
+            return null;
+        for (const index of candidates) {
+            const path = resolveArgvPath(argv[index], cwd);
+            if (path === null)
+                continue;
+            const digest = fileDigest(path);
+            if (digest !== null)
+                return { argv_index: index, path, ...digest };
+        }
+        return null;
+    }
+    // The degenerate case: no interpreter word, so the script IS argv[0] and the
+    // interpreter is whatever its shebang names. A program with no separator in
+    // it is a PATH lookup and is not this (see the module header).
+    if (!isAbsolute(program) && !program.includes("/"))
+        return null;
+    const path = resolveArgvPath(program, cwd);
+    if (path === null)
+        return null;
+    const digest = fileDigest(path);
+    return digest === null ? null : { argv_index: 0, path, ...digest };
+}
+/**
+ * The value `approval run`'s `payload_hash` is taken over (SPEC.md §6.2).
+ *
+ * `{argv, cwd}` when the argv names no readable script, byte for byte what it
+ * has always been; `{argv, cwd, script}` when it does. The caller canonicalizes
+ * and hashes it — this function decides WHAT is bound and never how it is
+ * digested into an approval.
+ */
+export function runPayloadValue(argv, cwd) {
+    const script = boundScript(argv, cwd);
+    const payload = { argv: [...argv], cwd };
+    if (script !== null)
+        payload.script = script;
+    return payload;
+}
+/**
+ * One line naming the bound script, for a refusal message or a terminal.
+ *
+ * Not a rendering an approver signs: the canonical renderer owns that, and this
+ * is the executor explaining to an agent WHICH file moved.
+ */
+export function describeBoundScript(script) {
+    if (script === null)
+        return "no script";
+    return `argv[${String(script.argv_index)}] ${script.path}, ${String(script.bytes)} bytes, sha256 ${script.sha256}`;
+}
+//# sourceMappingURL=run-payload.js.map

package/dist/src/core/run-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-payload.js","sourceRoot":"","sources":["../../../src/core/run-payload.ts"],"names":[],"mappings":"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"}

package/dist/src/core/sandbox.d.ts

@@ -153,9 +153,90 @@ export interface EgressAllowance {
      * reach the profile. Directories deny their whole subtree.
      */
     readonly denyRead: readonly string[];
+    /**
+     * WRITE CONFINEMENT (APRV-325.3): the only absolute subtrees the child may
+     * write, or `undefined` for the ordinary egress-only profile.
+     *
+     * This flips the posture for one rule family and one only. The header explains
+     * why the rest of this module is a deny-LIST: a `(deny default)` profile
+     * spends itself re-allowing dyld, the process's own binary and every temporary
+     * directory, and a control that breaks ordinary development is a control that
+     * gets switched off. That reasoning holds for reads and for everything else,
+     * and it does NOT hold for writes in a confined session, where the whole
+     * property being enforced is "this shell cannot change the canonical
+     * workspace". A write deny-list would have to enumerate every path worth
+     * protecting; this names the handful worth writing, so a path nobody thought
+     * of is denied rather than forgotten.
+     *
+     * `/dev` is allowed alongside them, unconditionally. Writes there are process
+     * I/O rather than filesystem state — `/dev/null`, `/dev/stdout`, `/dev/tty`,
+     * the pty a shell needs — and denying them kills the child before it can
+     * demonstrate anything, which is the failure mode point 1 of the header
+     * records for `network-outbound` and unix sockets.
+     *
+     * An EMPTY array is meaningful and is not the same as `undefined`: it denies
+     * every write outside `/dev`. `undefined` emits no write rules at all.
+     */
+    readonly writeAllow?: readonly string[];
+    /**
+     * The READ JAIL (APRV-347): absolute directories the child may read, with
+     * everything else denied.
+     *
+     * Absent or empty leaves the profile exactly as it was — allow-default with a
+     * deny-list — and the bytes are identical to the pre-APRV-347 profile, which
+     * a fixture test pins. That default is deliberate: a deny-default read
+     * profile is a much larger change to what ordinary development can do, and a
+     * control that breaks `npm run build` is a control someone switches off.
+     *
+     * When it IS set, the profile flips to `(deny file-read*)` plus a `subpath`
+     * allow for each of these roots and for the fixed runtime set a process needs
+     * to exist at all (see {@link RUNTIME_READ_PATHS}). `denyRead` still applies
+     * and is emitted AFTER the allows, so a credential file inside an allowed
+     * root stays unreadable: last match wins in SBPL, and the credential denial
+     * must be the last word.
+     */
+    readonly allowRead?: readonly string[];
 }
 /** The default: nothing allowed, nothing denied beyond the network. */
 export declare const DENY_ALL_EGRESS: EgressAllowance;
+/**
+ * What a process must be able to read to exist, regardless of the jail.
+ *
+ * Deliberately a fixed compiled-in list rather than anything a caller supplies:
+ * a jail whose runtime set could be widened by the party under oversight is not
+ * a jail (SPEC.md §11.1, self-reported fields never reduce scrutiny).
+ *
+ * - `/usr/lib`, `/usr/share`, `/System`, `/Library` — dyld, the shared cache,
+ *   ICU data and the frameworks every Mach-O binary links. A profile without
+ *   them kills the process before `main`, which reads as the command failing
+ *   rather than as the sandbox working.
+ * - `/private/var/db/dyld` and `/var/db/dyld` — the dyld shared cache, which
+ *   moved out of `/usr/lib` and is opened by name.
+ * - `/dev` — `/dev/null`, `/dev/urandom`, `/dev/dtracehelper`, the tty.
+ * - `/bin`, `/usr/bin`, `/sbin`, `/usr/sbin`, `/opt/homebrew`, `/usr/local` —
+ *   the interpreters and tools a build shells out to. The node binary's own
+ *   realpath is added separately by {@link runtimeReadRoots}, because a Node
+ *   installed by a version manager lives under the user's home and none of
+ *   these covers it.
+ * - `/etc`, `/private/etc` — `resolv.conf`, `passwd`, the locale tables.
+ *
+ * `node_modules` is NOT here, and that is a stated limit rather than an
+ * oversight: a repository's dependencies live inside the repository, so they
+ * are covered by the gate root being a read root. A project whose dependencies
+ * sit OUTSIDE the root (a pnpm store elsewhere, a linked package) must name
+ * that directory in `read_scope.roots`, which is exactly the widening that key
+ * exists for. docs/sandboxed-exec.md says so beside the survey.
+ *
+ * **The temp roots are not here either**, and that one is load-bearing. They
+ * reach the profile through the CALLER — `resolveReadRoots` puts the session
+ * scratchpad and the system temp root in the effective read scope, so
+ * `approval run` and `approval sandbox` open them and build tooling keeps
+ * working — and a caller that passes narrower roots gets a narrower jail. A
+ * temp root compiled in here would have been a widening no operator could turn
+ * off and no test could demonstrate a denial against, which is how it was
+ * found.
+ */
+export declare const RUNTIME_READ_PATHS: readonly string[];
 /**
  * The files beside a log that hold credential material, for the profile's
  * `denyRead`.

package/dist/src/core/sandbox.js

@@ -125,6 +125,77 @@ export const SANDBOX_STATES = [
 ];
 /** The default: nothing allowed, nothing denied beyond the network. */
 export const DENY_ALL_EGRESS = { loopback: false, denyRead: [] };
+/**
+ * What a process must be able to read to exist, regardless of the jail.
+ *
+ * Deliberately a fixed compiled-in list rather than anything a caller supplies:
+ * a jail whose runtime set could be widened by the party under oversight is not
+ * a jail (SPEC.md §11.1, self-reported fields never reduce scrutiny).
+ *
+ * - `/usr/lib`, `/usr/share`, `/System`, `/Library` — dyld, the shared cache,
+ *   ICU data and the frameworks every Mach-O binary links. A profile without
+ *   them kills the process before `main`, which reads as the command failing
+ *   rather than as the sandbox working.
+ * - `/private/var/db/dyld` and `/var/db/dyld` — the dyld shared cache, which
+ *   moved out of `/usr/lib` and is opened by name.
+ * - `/dev` — `/dev/null`, `/dev/urandom`, `/dev/dtracehelper`, the tty.
+ * - `/bin`, `/usr/bin`, `/sbin`, `/usr/sbin`, `/opt/homebrew`, `/usr/local` —
+ *   the interpreters and tools a build shells out to. The node binary's own
+ *   realpath is added separately by {@link runtimeReadRoots}, because a Node
+ *   installed by a version manager lives under the user's home and none of
+ *   these covers it.
+ * - `/etc`, `/private/etc` — `resolv.conf`, `passwd`, the locale tables.
+ *
+ * `node_modules` is NOT here, and that is a stated limit rather than an
+ * oversight: a repository's dependencies live inside the repository, so they
+ * are covered by the gate root being a read root. A project whose dependencies
+ * sit OUTSIDE the root (a pnpm store elsewhere, a linked package) must name
+ * that directory in `read_scope.roots`, which is exactly the widening that key
+ * exists for. docs/sandboxed-exec.md says so beside the survey.
+ *
+ * **The temp roots are not here either**, and that one is load-bearing. They
+ * reach the profile through the CALLER — `resolveReadRoots` puts the session
+ * scratchpad and the system temp root in the effective read scope, so
+ * `approval run` and `approval sandbox` open them and build tooling keeps
+ * working — and a caller that passes narrower roots gets a narrower jail. A
+ * temp root compiled in here would have been a widening no operator could turn
+ * off and no test could demonstrate a denial against, which is how it was
+ * found.
+ */
+export const RUNTIME_READ_PATHS = [
+    "/usr/lib",
+    "/usr/share",
+    "/System",
+    "/Library",
+    "/private/var/db/dyld",
+    "/var/db/dyld",
+    "/dev",
+    "/bin",
+    "/sbin",
+    "/usr/bin",
+    "/usr/sbin",
+    "/usr/local",
+    "/opt/homebrew",
+    "/etc",
+    "/private/etc",
+];
+/**
+ * The runtime set plus this process's own interpreter.
+ *
+ * `process.execPath` is resolved because a version manager's `node` is usually
+ * a symlink, and a `subpath` rule matches what the KERNEL resolves rather than
+ * what the profile was handed (the lesson APRV-193's design lane paid for).
+ */
+function runtimeReadRoots() {
+    const roots = [...RUNTIME_READ_PATHS];
+    try {
+        roots.push(dirname(realpathSync(process.execPath)));
+    }
+    catch {
+        // A process that cannot resolve its own binary is one the jail cannot help.
+    }
+    return roots;
+}
 // ---------------------------------------------------------------------------
 // The credential material
 // ---------------------------------------------------------------------------
@@ -293,6 +364,39 @@ export function seatbeltProfile(allowance) {
     if (allowance.loopback) {
         lines.push(";; Carve-out: a suite that starts its own localhost server. A real widening.", '(allow network-outbound (remote ip "localhost:*"))');
     }
+    // APRV-347, the read jail. Emitted between the egress rules and the
+    // credential denials, and the ORDER is the policy: SBPL takes the last
+    // matching rule, so the roots open the filesystem and `denyRead` closes the
+    // credential material inside them afterwards. An empty (or absent)
+    // `allowRead` emits nothing at all, which is why a profile built without it
+    // is byte-identical to the profile this function produced before this task.
+    const allowRead = allowance.allowRead ?? [];
+    if (allowRead.length > 0) {
+        lines.push(";; APRV-347: the read jail. Deny-default, then the roots and the fixed", ";; runtime set a process needs to start at all.", "(deny file-read*)");
+        const seen = new Set();
+        for (const path of [...allowRead, ...runtimeReadRoots()]) {
+            const resolved = resolveForProfile(path);
+            if (seen.has(resolved))
+                continue;
+            seen.add(resolved);
+            lines.push(`(allow file-read* (subpath ${sbplString(resolved)}))`);
+        }
+        // The ROOT DIRECTORY needs `file-read*`, not metadata, and this was
+        // measured rather than reasoned: with every other directory a process needs
+        // opened by subpath and `/` allowed for metadata only, `/usr/bin/true`
+        // dies with SIGABRT before `main`. `/` alone, as a literal: it opens the
+        // top-level directory listing and no file in it.
+        lines.push('(allow file-read* (literal "/"))');
+        // `file-read-metadata` on every other ancestor of every allowed root:
+        // resolving a path means stat-ing each directory on the way down, and a
+        // jail that denied that would refuse `/Users/x/dev/muse` for lack of
+        // `/Users`. Metadata leaks a directory's existence, never its contents.
+        for (const ancestor of ancestorsOf([...seen])) {
+            if (ancestor === "/")
+                continue;
+            lines.push(`(allow file-read-metadata (literal ${sbplString(ancestor)}))`);
+        }
+    }
     for (const path of allowance.denyRead) {
         const resolved = resolveForProfile(path);
         // `literal` for a file, `subpath` for a directory. Both are emitted for a
@@ -312,8 +416,91 @@ export function seatbeltProfile(allowance) {
         if (!file)
             lines.push(`(deny file-read* (subpath ${sbplString(resolved)}))`);
     }
+    if (allowance.writeAllow !== undefined) {
+        lines.push(";; APRV-325.3: write confinement. Deny-DEFAULT for this rule family only,", ";; so a path nobody thought of is denied rather than forgotten.", "(deny file-write*)", ";; /dev is process I/O, not filesystem state. Denying it kills a shell", ";; before it can do anything, for the reason a bare network-outbound deny does.", '(allow file-write* (subpath "/dev"))');
+        for (const path of allowance.writeAllow) {
+            lines.push(`(allow file-write* (subpath ${sbplString(resolveForProfile(path))}))`);
+        }
+    }
     return `${lines.join("\n")}\n`;
 }
+/**
+ * The read jail, plus the directories the command being run lives in (APRV-347).
+ *
+ * You cannot run a program you may not read. `sandbox-exec` execs the RESOLVED
+ * path, so a `node` or `npm` installed outside the compiled-in runtime set — a
+ * version manager under `~`, a `.local/bin` shim — fails `execvp` with
+ * `Operation not permitted` and exits 71, which reads as the command failing
+ * rather than as the jail working.
+ *
+ * Two directories are opened: the resolved executable's own, and its PARENT.
+ * The parent is what makes a toolchain work rather than merely start: an
+ * interpreter's entry point lives at `<prefix>/bin/<name>` and the library it
+ * immediately requires lives at `<prefix>/lib` or beside it, so opening only
+ * `bin` gets a process that launches and cannot find itself. `npm` resolves to
+ * `…/lib/node_modules/npm/bin/npm-cli.js`, whose parent is the npm package, and
+ * that is the shape this rule is for.
+ *
+ * It is NOT a widening a caller chooses: it is derived from the argv this
+ * function was already given, and it does nothing at all when no jail was
+ * asked for. Anything a command needs BEYOND its own install prefix — a
+ * dependency store elsewhere, a linked package — is the operator's
+ * `read_scope.roots` to declare.
+ */
+function withExecutableRoots(allowance, command) {
+    const jail = allowance.allowRead ?? [];
+    if (jail.length === 0)
+        return allowance;
+    let real = command;
+    try {
+        real = realpathSync(command);
+    }
+    catch {
+        // Not resolvable: the caller already handles a command that is not there.
+    }
+    const own = dirname(real);
+    // `dirname(command)` as well as `dirname(real)`: a PATH entry is usually a
+    // directory of symlinks (`~/.local/bin/npm` -> a version manager's tree), and
+    // traversing the link needs the link's own directory open, not just the
+    // target's. Leaving it out fails `execvp` before the program starts.
+    const roots = [own, dirname(command)];
+    // The prefix, behind a DEPTH FLOOR. `dirname("/bin")` is `/`, and a root of
+    // `/` would open the entire filesystem — a jail that opened everything and
+    // reported nothing, which is the worst failure this file can have. Two
+    // segments, the same floor the hook applies to a scratch root and for the
+    // same reason: a value derived from somewhere else must not be able to name
+    // the root of the disk.
+    const prefix = dirname(own);
+    if (prefix.split("/").filter((segment) => segment.length > 0).length >= 2) {
+        roots.push(prefix);
+    }
+    return { ...allowance, allowRead: [...jail, ...roots] };
+}
+/**
+ * Every proper ancestor directory of these paths, sorted and de-duplicated.
+ *
+ * `subpath` opens a subtree; it says nothing about the directories ABOVE it,
+ * and opening `/Users/carter/dev/muse` is useless if the process may not stat
+ * `/Users`, `/Users/carter` and `/Users/carter/dev` on the way down. Metadata
+ * only: the names of the intermediate directories leak, their contents do not.
+ */
+function ancestorsOf(paths) {
+    const out = new Set();
+    for (const path of paths) {
+        let at = dirname(path);
+        for (let depth = 0; depth < 64; depth += 1) {
+            if (at === "/" || at === "." || at === "")
+                break;
+            out.add(at);
+            const up = dirname(at);
+            if (up === at)
+                break;
+            at = up;
+        }
+    }
+    out.add("/");
+    return [...out].sort();
+}
 /**
  * A path as an SBPL string literal.
  *
@@ -377,7 +564,9 @@ export function wrapForSandbox(mechanism, command, args, allowance = DENY_ALL_EG
     }
     const dir = mkdtempSync(join(realTmpdir(), "approval-sandbox-"));
     const profile = join(dir, "egress-denied.sb");
-    writeFileSync(profile, seatbeltProfile(allowance), { mode: 0o600 });
+    writeFileSync(profile, seatbeltProfile(withExecutableRoots(allowance, command)), {
+        mode: 0o600,
+    });
     return {
         command: SANDBOX_EXEC,
         args: [...profileFlags(profile), command, ...args],