approval-md 0.2.0 → 0.3.0

package/dist/src/core/read-scope.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Read scope: which directories an agent may read from (APRV-347).
+ *
+ * ## The hole this closes
+ *
+ * Writes and deletes have been path-scoped for a while. `files.delete.scratch`
+ * versus `files.delete.out_of_scope` is decided by comparing a resolved target
+ * against roots the caller supplied (`ClassifierContext.scratchRoots`), and the
+ * file tools carry their target into the payload a grant binds. Reads had none
+ * of that: every shell reader classified `read.shell` with no path bound, and
+ * `Read`, `Glob` and `Grep` were answered `allow` before classification ever
+ * ran. So a policy could say a great deal about what an agent may WRITE and
+ * nothing at all about what it may SEE, and an agent working in one directory
+ * could read every sibling of it.
+ *
+ * This module is the pure half of the read-side mirror. It holds the class
+ * name, the roots arithmetic, and the one genuinely fiddly question — which
+ * words of a read command are paths — and it touches no disk, reads no
+ * environment and resolves nothing. The impure half (relative paths resolved
+ * against a working directory, symlinks followed, the escape that only the
+ * filesystem can see) lives in `src/cli/hook.ts`, exactly where the delete
+ * rule's second pass lives, and it can only ever TIGHTEN this file's answer.
+ *
+ * ## Fail closed, in three places
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path. Here that is
+ *
+ * 1. a target this file cannot read as a path (a `$VAR`, a glob, a `~`) is out
+ *    of scope, because what it expands to is not in the text;
+ * 2. a read command naming NO target reads the working directory, so it is
+ *    checked against the working directory rather than waved through;
+ * 3. an empty root list means nothing is in scope — but a caller that passes no
+ *    roots at all gets today's answer instead (see {@link ClassifierContext}),
+ *    because a caller that forgot the field must not have every read it makes
+ *    turned into a decision.
+ *
+ * ## What a root is
+ *
+ * The gate root (the directory holding the policy file the runtime resolved),
+ * the session scratchpad, and the system temp root. A policy may WIDEN that
+ * with `read_scope.roots`; it may not narrow it below the gate root, because a
+ * runtime that cannot read its own policy, log and workspace cannot run at all.
+ */
+/**
+ * The class a read outside every root takes.
+ *
+ * A sibling of `read.shell` rather than a replacement for it: a read INSIDE the
+ * roots is the same ordinary, autonomous act it has always been, and a policy
+ * that says nothing about this class gets `defaults.autonomy` for it, which is
+ * the fail-closed direction for a name nobody has declared.
+ */
+export declare const READ_OUT_OF_SCOPE_CLASS = "read.file.out_of_scope";
+/**
+ * The `read_scope` block of a policy (SPEC.md §5, amended APRV-347).
+ *
+ * Additive and optional, with the same discipline `protected_paths` has: the
+ * built-in roots stand whatever this says, so a policy can widen the scope and
+ * never shrink it. A relative entry is resolved against the gate root, so a
+ * policy stays portable between a checkout and a clone of it.
+ */
+export interface ReadScope {
+    roots?: string[];
+}
+/**
+ * Is `candidate` AT or under `root`, by path segment?
+ *
+ * At-or-under rather than the delete rule's strictly-under: `ls <gate root>` is
+ * a read of the workspace an agent is working in, and a rule that made the root
+ * itself out of scope would classify the most ordinary command in the session.
+ *
+ * Segment matching, never string prefixes: `/dev/muse-other` must not match a
+ * root of `/dev/muse`, and `startsWith` says it does.
+ */
+export declare function isAtOrUnderReadRoot(candidate: string, root: string): boolean;
+/** Is this path inside ANY of these roots? */
+export declare function isInReadScope(candidate: string, roots: readonly string[]): boolean;
+/**
+ * A value whose expansion the classifier cannot see, and therefore may not
+ * vouch for. The same test the delete rule applies, and for the same reason:
+ * `cat $SOMEWHERE` reads whatever that variable holds.
+ */
+export declare function isUnreadableTarget(word: string): boolean;
+/**
+ * The effective read roots: the built-ins, plus whatever the policy added.
+ *
+ * Pure, and every input is the caller's. `gateRoot` is the directory holding
+ * the policy file the runtime resolved; `systemRoots` are the scratchpad and
+ * temp roots the caller already resolved (`resolveScratchRoots` in the hook);
+ * `declared` is `read_scope.roots` verbatim.
+ *
+ * A declared entry that is relative is joined onto the gate root. A declared
+ * entry the caller cannot vouch for — empty, or one this file can see is not a
+ * path at all — is DROPPED rather than accepted, because a root is an
+ * authorization and a malformed one must not become `/`.
+ *
+ * The result is de-duplicated and otherwise in the order given, so the first
+ * root a path matches is the most specific one a reader would expect.
+ */
+export declare function effectiveReadRoots(options: {
+    gateRoot: string;
+    declared?: readonly string[] | undefined;
+    systemRoots?: readonly string[] | undefined;
+}): string[];
+/**
+ * How a reader's positionals map to paths.
+ *
+ * - `all`: every positional is a file or directory (`cat a b`, `ls src`,
+ *   `diff a b`, `cut -d: -f1 /etc/passwd` — `cut`'s delimiter and field list
+ *   are flags, so none of its positionals is a pattern).
+ * - `after-pattern`: the FIRST positional is a pattern or a script and the rest
+ *   are paths (`grep needle src`, `sed -n 1,5p file`, `jq .x file.json`) —
+ *   UNLESS the pattern arrived through a flag (`-e`, `-f`), in which case every
+ *   positional is a path and the shape collapses to `all`.
+ * - `walk`: `find`'s shape — positionals up to the first primary are paths.
+ *
+ * Binaries absent from this table are absent on purpose, and each omission is a
+ * decision not to widen anything:
+ *
+ * - `echo`, `printf`, `tr`, `test`, `type`, `which`, `pwd`, `true`, `false`,
+ *   `cd`: their positionals are not files, or name a file without reading its
+ *   contents. A rule that treated `echo /etc/passwd` as a read of that file
+ *   would route text through a human.
+ * - `basename`, `dirname`, `readlink`, `realpath`: they manipulate or resolve a
+ *   path and never open it. What leaks is the existence of a name, which is not
+ *   what this class is about.
+ * - `less` and `more` are NOT added to the classifier's reader list by this
+ *   task. Adding them would take them from `unclassified` (a deny) to
+ *   `read.shell` (this repository's policy: autonomous), which is a widening,
+ *   and a task that exists to narrow reads has no business doing that in
+ *   passing. They are named in the follow-up in `docs/sandboxed-exec.md`.
+ */
+export type ReadTargetShape = "all" | "after-pattern" | "walk";
+/** Which readers take paths, and where. Keyed by the binary's basename. */
+export declare const READ_TARGET_SHAPES: Readonly<Record<string, ReadTargetShape>>;
+/**
+ * The paths a read command will open, or `null` when this binary is not one
+ * whose reads this module scopes.
+ *
+ * An empty array is a real answer and is NOT the same as `null`: it means this
+ * reader opens the working directory (`ls`, `find`, `grep needle` with no file
+ * operand), and the caller checks the working directory in its place. `null`
+ * means "not a scoped reader", and the caller leaves the segment alone.
+ *
+ * Treating a non-path positional as a path costs nothing: a bare word resolves
+ * against the working directory, which is inside a root in every session this
+ * module is meant for. Treating a path as a non-path costs the whole property.
+ */
+export declare function readTargetsOf(bin: string, positionals: readonly string[], args?: readonly string[]): string[] | null;
+/**
+ * The verdict the PURE half can reach for one target.
+ *
+ * `out-of-scope` and `in-scope` are final. `needs-disk` is the honest answer
+ * for a relative path: its meaning depends on a working directory this file
+ * does not have, and the caller with the disk decides it. A caller that cannot
+ * do the second pass must treat `needs-disk` as out of scope — which is what
+ * `hook classify` and `hook <harness>` both do, through the same function.
+ */
+export type ReadTargetVerdict = "in-scope" | "out-of-scope" | "needs-disk";
+/**
+ * Read one target against the roots, as far as text alone can settle it.
+ *
+ * Absolute and inside a root: in scope. Absolute and outside every root: out of
+ * scope, decided here, no disk needed. Unreadable (a variable, a glob, a `~`):
+ * out of scope, because what it names is not in the text. Anything relative, or
+ * carrying a `..`, is `needs-disk`.
+ */
+export declare function readTargetVerdict(target: string, roots: readonly string[]): ReadTargetVerdict;
+/**
+ * The roots, rendered for a human: `approval policy check`'s line and the
+ * hook's verdict note say the same sentence.
+ */
+export declare function renderReadRoots(roots: readonly string[]): string;

package/dist/src/core/read-scope.js

@@ -0,0 +1,252 @@
+/**
+ * Read scope: which directories an agent may read from (APRV-347).
+ *
+ * ## The hole this closes
+ *
+ * Writes and deletes have been path-scoped for a while. `files.delete.scratch`
+ * versus `files.delete.out_of_scope` is decided by comparing a resolved target
+ * against roots the caller supplied (`ClassifierContext.scratchRoots`), and the
+ * file tools carry their target into the payload a grant binds. Reads had none
+ * of that: every shell reader classified `read.shell` with no path bound, and
+ * `Read`, `Glob` and `Grep` were answered `allow` before classification ever
+ * ran. So a policy could say a great deal about what an agent may WRITE and
+ * nothing at all about what it may SEE, and an agent working in one directory
+ * could read every sibling of it.
+ *
+ * This module is the pure half of the read-side mirror. It holds the class
+ * name, the roots arithmetic, and the one genuinely fiddly question — which
+ * words of a read command are paths — and it touches no disk, reads no
+ * environment and resolves nothing. The impure half (relative paths resolved
+ * against a working directory, symlinks followed, the escape that only the
+ * filesystem can see) lives in `src/cli/hook.ts`, exactly where the delete
+ * rule's second pass lives, and it can only ever TIGHTEN this file's answer.
+ *
+ * ## Fail closed, in three places
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path. Here that is
+ *
+ * 1. a target this file cannot read as a path (a `$VAR`, a glob, a `~`) is out
+ *    of scope, because what it expands to is not in the text;
+ * 2. a read command naming NO target reads the working directory, so it is
+ *    checked against the working directory rather than waved through;
+ * 3. an empty root list means nothing is in scope — but a caller that passes no
+ *    roots at all gets today's answer instead (see {@link ClassifierContext}),
+ *    because a caller that forgot the field must not have every read it makes
+ *    turned into a decision.
+ *
+ * ## What a root is
+ *
+ * The gate root (the directory holding the policy file the runtime resolved),
+ * the session scratchpad, and the system temp root. A policy may WIDEN that
+ * with `read_scope.roots`; it may not narrow it below the gate root, because a
+ * runtime that cannot read its own policy, log and workspace cannot run at all.
+ */
+/**
+ * The class a read outside every root takes.
+ *
+ * A sibling of `read.shell` rather than a replacement for it: a read INSIDE the
+ * roots is the same ordinary, autonomous act it has always been, and a policy
+ * that says nothing about this class gets `defaults.autonomy` for it, which is
+ * the fail-closed direction for a name nobody has declared.
+ */
+export const READ_OUT_OF_SCOPE_CLASS = "read.file.out_of_scope";
+/** Non-empty path segments, `.` dropped. Identical to the classifier's own. */
+function segmentsOf(candidate) {
+    return candidate
+        .split(/[/\\]+/u)
+        .filter((segment) => segment.length > 0 && segment !== ".");
+}
+/**
+ * Is `candidate` AT or under `root`, by path segment?
+ *
+ * At-or-under rather than the delete rule's strictly-under: `ls <gate root>` is
+ * a read of the workspace an agent is working in, and a rule that made the root
+ * itself out of scope would classify the most ordinary command in the session.
+ *
+ * Segment matching, never string prefixes: `/dev/muse-other` must not match a
+ * root of `/dev/muse`, and `startsWith` says it does.
+ */
+export function isAtOrUnderReadRoot(candidate, root) {
+    const want = segmentsOf(root);
+    const have = segmentsOf(candidate);
+    if (want.length === 0)
+        return false;
+    if (have.length < want.length)
+        return false;
+    return want.every((segment, index) => segment === have[index]);
+}
+/** Is this path inside ANY of these roots? */
+export function isInReadScope(candidate, roots) {
+    return roots.some((root) => isAtOrUnderReadRoot(candidate, root));
+}
+/**
+ * A value whose expansion the classifier cannot see, and therefore may not
+ * vouch for. The same test the delete rule applies, and for the same reason:
+ * `cat $SOMEWHERE` reads whatever that variable holds.
+ */
+export function isUnreadableTarget(word) {
+    return (word.includes("$") ||
+        word.includes("*") ||
+        word.includes("?") ||
+        word.includes("[") ||
+        word.startsWith("~"));
+}
+/**
+ * The effective read roots: the built-ins, plus whatever the policy added.
+ *
+ * Pure, and every input is the caller's. `gateRoot` is the directory holding
+ * the policy file the runtime resolved; `systemRoots` are the scratchpad and
+ * temp roots the caller already resolved (`resolveScratchRoots` in the hook);
+ * `declared` is `read_scope.roots` verbatim.
+ *
+ * A declared entry that is relative is joined onto the gate root. A declared
+ * entry the caller cannot vouch for — empty, or one this file can see is not a
+ * path at all — is DROPPED rather than accepted, because a root is an
+ * authorization and a malformed one must not become `/`.
+ *
+ * The result is de-duplicated and otherwise in the order given, so the first
+ * root a path matches is the most specific one a reader would expect.
+ */
+export function effectiveReadRoots(options) {
+    const roots = [];
+    const add = (candidate) => {
+        if (candidate.length === 0)
+            return;
+        if (!roots.includes(candidate))
+            roots.push(candidate);
+    };
+    add(options.gateRoot);
+    for (const root of options.systemRoots ?? [])
+        add(root);
+    for (const entry of options.declared ?? []) {
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        if (isUnreadableTarget(entry))
+            continue;
+        add(entry.startsWith("/") ? entry : `${options.gateRoot}/${entry}`);
+    }
+    return roots;
+}
+/** Which readers take paths, and where. Keyed by the binary's basename. */
+export const READ_TARGET_SHAPES = {
+    cat: "all",
+    cksum: "all",
+    cut: "all",
+    diff: "all",
+    du: "all",
+    file: "all",
+    find: "walk",
+    grep: "after-pattern",
+    head: "all",
+    jq: "after-pattern",
+    ls: "all",
+    md5sum: "all",
+    rg: "after-pattern",
+    sed: "after-pattern",
+    sha256sum: "all",
+    shasum: "all",
+    sort: "all",
+    stat: "all",
+    tail: "all",
+    tree: "all",
+    uniq: "all",
+    wc: "all",
+};
+/**
+ * `find` primaries: the first word starting with `-` ends the path list.
+ *
+ * `find` is the one reader whose arguments are a little language, and its shape
+ * is `find [paths…] [expression]`. This one reads the RAW argument list rather
+ * than the flag-filtered positionals, because the filter is what tells the
+ * paths from the expression: in `find . -name '*.ts'` the pattern `*.ts` is a
+ * positional too, and a rule fed the filtered list would read it as a path,
+ * find it unreadable, and call an ordinary walk of the workspace out of scope.
+ */
+function walkTargets(args) {
+    const targets = [];
+    for (const word of args) {
+        if (word.startsWith("-"))
+            break;
+        targets.push(word);
+    }
+    return targets;
+}
+/**
+ * Flags that carry the pattern or the script, so every positional is a path.
+ *
+ * `grep -e needle src`, `sed -f script.sed file`, `rg --regexp needle dir`: the
+ * first positional is the FILE, and a rule that skipped it would leave the one
+ * target that matters unchecked. Under-detection is the failure mode that
+ * matters here — an unchecked read is a read outside the jail — so the shape
+ * widens to `all` whenever one of these appears.
+ */
+const PATTERN_BEARING_FLAGS = [
+    "-e",
+    "-f",
+    "--regexp",
+    "--expression",
+    "--file",
+];
+/** Did the pattern (or script) arrive through a flag rather than a positional? */
+function patternCameFromFlag(args) {
+    return args.some((arg) => PATTERN_BEARING_FLAGS.includes(arg) ||
+        PATTERN_BEARING_FLAGS.some((flag) => flag.startsWith("--") && arg.startsWith(`${flag}=`)));
+}
+/**
+ * The paths a read command will open, or `null` when this binary is not one
+ * whose reads this module scopes.
+ *
+ * An empty array is a real answer and is NOT the same as `null`: it means this
+ * reader opens the working directory (`ls`, `find`, `grep needle` with no file
+ * operand), and the caller checks the working directory in its place. `null`
+ * means "not a scoped reader", and the caller leaves the segment alone.
+ *
+ * Treating a non-path positional as a path costs nothing: a bare word resolves
+ * against the working directory, which is inside a root in every session this
+ * module is meant for. Treating a path as a non-path costs the whole property.
+ */
+export function readTargetsOf(bin, positionals, args = []) {
+    const shape = READ_TARGET_SHAPES[basenameOf(bin)];
+    if (shape === undefined)
+        return null;
+    switch (shape) {
+        case "all":
+            return [...positionals];
+        case "after-pattern":
+            return patternCameFromFlag(args) ? [...positionals] : positionals.slice(1);
+        case "walk":
+            return walkTargets(args.length === 0 ? positionals : args);
+    }
+}
+/** The last segment of a command word, so `/usr/bin/cat` reads as `cat`. */
+function basenameOf(bin) {
+    const segments = segmentsOf(bin);
+    return segments[segments.length - 1] ?? bin;
+}
+/**
+ * Read one target against the roots, as far as text alone can settle it.
+ *
+ * Absolute and inside a root: in scope. Absolute and outside every root: out of
+ * scope, decided here, no disk needed. Unreadable (a variable, a glob, a `~`):
+ * out of scope, because what it names is not in the text. Anything relative, or
+ * carrying a `..`, is `needs-disk`.
+ */
+export function readTargetVerdict(target, roots) {
+    if (target.length === 0)
+        return "needs-disk";
+    if (isUnreadableTarget(target))
+        return "out-of-scope";
+    if (!target.startsWith("/"))
+        return "needs-disk";
+    if (segmentsOf(target).includes(".."))
+        return "needs-disk";
+    return isInReadScope(target, roots) ? "in-scope" : "out-of-scope";
+}
+/**
+ * The roots, rendered for a human: `approval policy check`'s line and the
+ * hook's verdict note say the same sentence.
+ */
+export function renderReadRoots(roots) {
+    return roots.length === 0 ? "(none)" : roots.join(", ");
+}
+//# sourceMappingURL=read-scope.js.map

package/dist/src/core/read-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-scope.js","sourceRoot":"","sources":["../../../src/core/read-scope.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`.