approval-md 0.4.5 → 0.4.7

package/dist/src/core/command-class.d.ts

@@ -82,7 +82,32 @@ export interface ClassifiedSegment {
      * profile is the caller's, and a profile a caller wrote can allow anything.
      */
     sandbox?: SandboxWrapper;
+    /**
+     * The program an `exec.code` segment runs, present only on such a segment
+     * (APRV-510). Text only, like everything this file returns: the hook hashes
+     * the inline source, or reads and hashes the file, and binds the hash and the
+     * length, never the text (SPEC.md §11.1 invariant 3).
+     */
+    execCode?: ExecCodeSource;
 }
+/**
+ * What an `exec.code` segment runs, as the classifier read it (APRV-510).
+ *
+ * `source` is the inline program (`python3 -c <source>`, `node -e <source>`,
+ * `deno eval <source>`) or the file path as written (`python3 <source>`,
+ * `bun <source>`). `argv` is the segment's argv from the binary on, verbatim,
+ * and `sourceIndex` names the word of `argv` that carries `source`, so a
+ * caller can bind the argv with that one word replaced by its hash.
+ */
+export interface ExecCodeSource {
+    interpreter: string;
+    mode: ExecCodeMode;
+    source: string;
+    argv: string[];
+    sourceIndex: number;
+}
+/** How an `exec.code` segment carries its program (APRV-510). */
+export type ExecCodeMode = "inline" | "file";
 /**
  * Who wrote the profile a wrapped command runs under (APRV-193).
  *
@@ -222,6 +247,35 @@ interface ProtectedEntry {
  * skipped validation.
  */
 export declare function parseProtectedEntry(entry: ProtectedPathEntry): ProtectedEntry | null;
+/**
+ * The words bash's brace expansion makes of `word`, or `null` when there would
+ * be more than {@link BRACE_EXPANSION_CAP}, or making them would take more than
+ * {@link BRACE_EXPANSION_STEPS} expansions (APRV-511 refuter M2, recheck S(new)).
+ *
+ * A group is `{` … `}` holding a top-level comma (`{a,b}`, `{,s}`) or a
+ * sequence (`{1..3}`, `{a..c}`, `{1..9..2}`); a `{` right after `$` opens a
+ * parameter expansion and is never a group, and anything else stays literal,
+ * as it does in bash. Groups nest and multiply. The lexer has already removed
+ * quoting, so a quoted brace pair reads as a group too, which can only make an
+ * answer stricter.
+ *
+ * The expansion is iterative, never recursive: a work list holds the words
+ * still carrying a group, and both bounds are tested BEFORE a word is
+ * expanded further, so no input reaches the stack limit or runs unbounded.
+ * Every caller reads `null` as the stricter class.
+ */
+export declare function braceExpansions(word: string): string[] | null;
+/**
+ * The words a path word may stand for once bash has expanded its brace groups,
+ * plus, for any word that still carries a stray `{` or `}` outside a parameter
+ * expansion, the same word with the stray braces removed (APRV-511 review).
+ * Bash keeps a stray brace literally (`{~/.hermes/.op.env` names a directory
+ * called `{~`), but a word whose only distance from an organ or a credential is
+ * a stray brace is judged as that organ: the stricter of the two readings.
+ * `null` when the expansion exceeds {@link BRACE_EXPANSION_CAP}, unless every
+ * group is a sequence or list of plain numbers ({@link numericRepresentative}).
+ */
+export declare function braceCandidates(word: string): string[] | null;
 /**
  * Which protected class does this path name, if any? (APRV-198.)
  *
@@ -384,6 +438,58 @@ export declare const NON_SECRET_ENV_NAMES: readonly string[];
  * environment rather than of command text, and it must ask it the same way.
  */
 export declare function isSecretEnvName(name: string): boolean;
+/**
+ * Does this git argv only WRITE the paths it names? (APRV-522.) `true` only
+ * when the verb is read unambiguously, is one of
+ * {@link GIT_PATH_WRITE_OPTIONS}, and every option before `--` is on that
+ * verb's allow-list.
+ *
+ * The verb is found the way APRV-520's {@link gitGlobalRefusal} reads the
+ * globals: zero-value globals are skipped, and ANY other flag before the verb
+ * (a global that takes a value, `-C dir`, `-c k=v`, `--git-dir x`, a joined
+ * `--work-tree=`, or one this table does not know) leaves the verb unknown, so
+ * the argv is a READER. `classifySegment` refuses those globals anyway; this
+ * does not rely on that ordering.
+ *
+ * The options are a closed list, never a deny-list: git accepts any unique
+ * prefix of a long option (`--pat` is `--patch`), several verbs print the
+ * file's hunks (`git add -p`, `git checkout -p`, `git restore --patch`), and
+ * `git checkout-index --prefix=/tmp/` writes a copy elsewhere. So an option
+ * not listed for the verb (an abbreviation, a short letter bundled with one
+ * not listed, `-fp`, an unknown flag) makes the argv a reader, and the
+ * credential rule judges what it names.
+ */
+/**
+ * Where git's verb sits in its argv, read the way {@link gitWritesNamedPathsOnly}
+ * reads it (APRV-522 fix round 2): only zero-value globals may come before it,
+ * and any other flag leaves the verb unknown (`null`). The hook's credential
+ * pass uses it so that, under a directory a `CDPATH` lookup may have chosen,
+ * the verb word is not judged as a path: git never opens its verb.
+ */
+export declare function gitVerbIndex(args: readonly string[]): number | null;
+/**
+ * The words of a segment the credential rule reads as paths (APRV-522), for
+ * the pure classifier and the hook's disk pass alike: one judgement, so the two
+ * cannot disagree about which words a reader opens.
+ *
+ * Empty for a binary that only WRITES what it names
+ * ({@link credentialWritesOnly}). Otherwise:
+ *
+ * - every positional (the words that are not flags, a flag's separate value
+ *   included);
+ * - the value of every `--name=value` flag and of every short flag carrying
+ *   its value attached (`-fFILE`), because a reader's file operand may arrive
+ *   inside its own option (M6);
+ * - the file half of an upload spelling, `@FILE` and `name=@FILE;type=…`, and
+ *   `name=<FILE`, which curl reads the same way;
+ * - for git, the path half of a `<rev>:<path>` or `:<path>` word, pathspec
+ *   magic (`:(top)`, `:/`) stripped, because show and cat-file print the blob
+ *   such a word names.
+ *
+ * Over-reading a word costs an approval prompt when it happens to spell a
+ * credential path; under-reading one costs the property.
+ */
+export declare function credentialReadWords(basename: string, args: readonly string[]): string[];
 interface LexWord {
     /** Literal text, quotes removed and backslash escapes applied. */
     text: string;
@@ -391,6 +497,36 @@ interface LexWord {
     quoted: boolean;
     /** Inner text of each `$(…)` in this word, for recursive classification. */
     substitutions: string[];
+    /**
+     * An UNQUOTED variable or `$(…)` is part of the word, so the shell may split
+     * its value into several words (APRV-511 fix round 3, S(open)).
+     */
+    splits: boolean;
+    /**
+     * An UNQUOTED `{`, `*`, `?` or `[` is part of the word, so brace expansion or
+     * a glob may make it several words or change its head (fix round 3).
+     */
+    expands: boolean;
+    /**
+     * Is `text` exactly the bytes the shell would hand the command for this
+     * word? (APRV-510.) `false` when the shell would still change it: a `$`
+     * outside single quotes (a parameter expansion), an unquoted glob or brace
+     * character, a leading unquoted `~`, or a backslash inside double quotes
+     * before a character the shell keeps it for (this lexer drops every such
+     * backslash, the shell drops only five). Read by the `exec.code` shape alone,
+     * which hashes a word and so needs the word's bytes to be the program's
+     * bytes; every other reader keeps reading `text` exactly as before.
+     */
+    exact: boolean;
+    /**
+     * Is this word an assignment to bash (APRV-523)? bash decides that on the
+     * word as WRITTEN, before quote removal: the name, an optional subscript, the
+     * `+` and the `=` must carry no quoting or escaping character, and the name
+     * no `$`, backtick or brace. {@link ASSIGNMENT} applied to the source
+     * spelling, not to `text`: a word whose name is quoted or escaped has the
+     * same `text` as an assignment and is a command word, the program bash runs.
+     */
+    assignment: boolean;
 }
 interface LexRedirect {
     /** `>` and `>>` write; `<` reads. */
@@ -409,7 +545,40 @@ interface LexSegment {
     bodySubstitutions: string[];
     /** Set when the segment contains a construct whose effect cannot be read. */
     opaque: string | null;
+    /**
+     * Did this segment open a heredoc (`<<EOF`, `<<-EOF`)? (APRV-510.) The body
+     * is skipped and never classified, and an unquoted body still expands
+     * (APRV-504), so the `exec.code` shape declines a segment carrying one.
+     */
+    heredoc: boolean;
+    /**
+     * Does this segment's stdin come from somewhere the text names as input:
+     * the previous segment of a pipeline (`a | b`, `a |& b`), or a descriptor
+     * duplicated onto it (`<&3`)? (APRV-510, security review round 2.) A program
+     * can read its real source from stdin (`echo '<src>' | python3 -c
+     * 'exec(sys.stdin.read())'`), outside the hash, so the `exec.code` shape
+     * declines a segment fed this way.
+     */
+    stdinFed: boolean;
+    /**
+     * Is this segment inside a subshell `( … )`? (APRV-510, refuter rS2.) A
+     * redirection or heredoc written after the closing `)` feeds the stdin of
+     * every command inside it (`(python3 -c '…') < evil.py`), and lands on a
+     * segment of its own, so `stdinFed`, `heredoc` and `redirects` never reach
+     * the program's segment. The `exec.code` shape declines any segment inside a
+     * subshell at all, the stricter form of "a subshell carrying a redirection".
+     * A depth that goes negative (an unmatched `)`, as in a `case` pattern)
+     * counts as inside.
+     */
+    subshell: boolean;
 }
+/**
+ * What a `$(…)` leaves in a word's text (APRV-511 refuter M1): an unexpanded
+ * variable, which is exactly what the shell's substitution is to a classifier
+ * that does not run it. The name cannot collide with a real expansion a
+ * command would carry, and it is braced so no brace-expansion reading applies.
+ */
+export declare const SUBSTITUTION_SENTINEL = "${__APPROVAL_SUBST__}";
 /**
  * Facts about the machine the command will run on, resolved by the CALLER
  * (APRV-267).
@@ -471,6 +640,32 @@ export interface ClassifierContext {
      * here, forgetting it cannot loosen anything.
      */
     unwrapShell?: boolean;
+    /**
+     * A variable git could inherit that the command line's own shell sets
+     * (APRV-521, {@link gitEnvironmentWrite}). {@link classifyCommand} fills it
+     * from its own segments and hands it down to a substitution and an
+     * unwrapped script, which run in a shell that inherits it; every `git`
+     * segment under it is `unclassified`. A caller that sets it only refuses
+     * more.
+     */
+    shellEnvWrite?: string;
+    /**
+     * May an opaque PROGRAM be classified `exec.code` rather than refused
+     * (APRV-510)?
+     *
+     * `false` by default, and the default is today's answer exactly: `python3 -c`,
+     * `node -e`, `perl -e`, `ruby -e` and `deno eval` stay `opaque`, `bun -e`,
+     * `python3 <file>` and `bun <file>.ts` stay `unclassified`. `src/cli/hook.ts`
+     * passes `true` only when the loaded policy declares
+     * `exec.code.custody: attested`, the operator's statement that the agent's
+     * code cannot reach credentials it should not hold. Like `scratchRoots`, a
+     * caller that forgets it gets the stricter answer: a refusal.
+     *
+     * It opens a SHAPE and nothing wider ({@link execCodeShape}): `bash -c`,
+     * `sh -c`, `eval`, a pipe into an interpreter and `python3 -` (stdin) are
+     * refused whatever this says.
+     */
+    execCode?: boolean;
 }
 /** Everything a refinement needs: the binary and the words that followed it. */
 interface RuleContext {
@@ -496,6 +691,12 @@ interface RuleContext {
      * `PYTHONPATH`, `PYTHONSTARTUP`, `HOME`).
      */
     assigned: boolean;
+    /**
+     * Those assignments, verbatim (APRV-517). `git push` reads them: a `GIT_*`
+     * variable or `HOME` decides which configuration the push runs under, and
+     * configuration can carry a deleting refspec.
+     */
+    assignments: readonly string[];
     /** What the caller knows about the machine (APRV-267). Never read from here. */
     context: ClassifierContext;
 }
@@ -571,6 +772,14 @@ export interface CommandRule {
      * `NAME=value` words in front of the binary, verbatim.
      */
     shape?: (args: readonly string[], assignments: readonly string[]) => boolean;
+    /**
+     * Match only an argv in the `exec.code` shape, and only when the caller
+     * opened the class (APRV-510, {@link ClassifierContext.execCode},
+     * {@link execCodeShape}). The `probe`, `skillScript` and `shape` device again:
+     * an argv outside the shape does not match the row at all, so it keeps the
+     * answer it has today.
+     */
+    execCode?: boolean;
 }
 /**
  * The suffix that marks a Muse model as training on what it is shown.
@@ -621,6 +830,57 @@ export declare function isSkillScriptPath(word: string): boolean;
  * `classifySegment`, which runs after the table and can only tighten.
  */
 export declare function skillScriptArg(bin: string, args: readonly string[]): string | null;
+/**
+ * The class an opaque program takes once a policy opens it: an inline program
+ * or an interpreter run of a file the gate cannot read as a skill script.
+ * Under `exec.*` (SPEC.md §7) beside `exec.local`, and deliberately not under
+ * it: `exec.local` is code in the workspace the runtime may name, this is code
+ * whose effect nothing here reads. A record of it says the program EXISTED
+ * (its hash and length), never what it did: every tool call the program then
+ * makes through the harness is its own hook event, and a shell command it
+ * spawns is not seen at all.
+ */
+export declare const EXEC_CODE_CLASS = "exec.code";
+/** The table row that matches the `exec.code` shape. */
+export declare const EXEC_CODE_ROW = "exec-code";
+/** The rule id of an inline program (`python3 -c`, `node -e`, ...). */
+export declare const EXEC_CODE_INLINE_RULE = "exec-code-inline";
+/** The rule id of an interpreter running a file (`python3 x.py`, `bun x.ts`). */
+export declare const EXEC_CODE_FILE_RULE = "exec-code-file";
+/** Where an `exec.code` argv carries its program (an index into the args). */
+export interface ExecCodeShape {
+    mode: ExecCodeMode;
+    /** Index into the args (the words after the binary) of the source word. */
+    index: number;
+}
+/** A word as {@link execCodeShape} needs it: its text and whether the shell would change it. */
+interface ExecShapeWord {
+    exact: boolean;
+    substitutions: readonly string[];
+}
+/**
+ * The `exec.code` shape of an interpreter argv, or `null` (APRV-510).
+ *
+ * An ALLOWLIST, like {@link skillScriptArg}, and the same flags are inert here:
+ *
+ * - inline: `[inert flags…] <inline flag> <program>`, and NOTHING after the
+ *   program, for every interpreter. A word after it is handed to the program
+ *   (`sys.argv`, `process.argv`, `ARGV`), and a one-line loader
+ *   (`python3 -c 'import sys; exec(sys.argv[1])' '<real program>'`) would put
+ *   the real program there, outside the hash and inside the argv the payload
+ *   carries verbatim (security review of APRV-510, finding 3a). `deno` is
+ *   exactly `deno eval <program>`;
+ * - file (python, python3 and bun only): `[inert flags…] <path> [args…]`,
+ *   where the path is not a skill script (those are `exec.local`, APRV-502)
+ *   and, for `bun`, carries a script extension.
+ *
+ * Anything else is not the shape: a value-taking flag, `--flag=value`, `-m`,
+ * a lone `-` (stdin), an inline flag with no program, two programs, a cluster
+ * hiding the inline flag (`-Ic`), and, when `words` is given, a source word the
+ * shell would still change (`LexWord.exact`) or one built from a substitution:
+ * the hash binds the program's bytes, so the word must BE them.
+ */
+export declare function execCodeShape(bin: string, args: readonly string[], words?: readonly ExecShapeWord[] | null): ExecCodeShape | null;
 /**
  * The table.
  *
@@ -660,7 +920,16 @@ export declare const COMMAND_RULES: readonly CommandRule[];
  * - a substitution in any of the three words, whose effect happens before the
  *   shell even starts;
  * - a nested shell inside the script, refused by {@link ClassifierContext} when
- *   the recursion runs (the inner classification unwraps nothing).
+ *   the recursion runs (the inner classification unwraps nothing);
+ * - a shell word that is not the system's binary ({@link isSystemBinWord}): a
+ *   relative path, or an absolute one outside the system-bin directories, is
+ *   whatever program sits there, which its last path segment does not name
+ *   (APRV-523 fix round, review-b S1);
+ * - a shell word that is assignment-shaped, in its source spelling
+ *   ({@link LexWord.assignment}) or its dequoted text ({@link ASSIGNMENT}).
+ *   bash runs a word whose name is quoted or escaped as a program named by the
+ *   whole word, and {@link classifySegment} refuses that segment; unwrapping
+ *   it here would answer before that check runs.
  *
  * The BINDING does not move. `cli/hook.ts` binds the outer command and argv
  * exactly as APRV-362 built them; what this changes is only which text is
@@ -668,6 +937,59 @@ export declare const COMMAND_RULES: readonly CommandRule[];
  * bound elsewhere and unchanged.
  */
 export declare function loginShellScript(segment: LexSegment): string | null;
+/**
+ * How the shell may still change one argv word before the program sees it
+ * (APRV-511 fix round 3, S(open)): `splits`, an unquoted variable or `$(…)` is
+ * in it; `expands`, an unquoted brace or glob character is. A caller that
+ * cannot say passes neither, and only the text is read.
+ */
+export interface ArgExpansion {
+    splits: boolean;
+    expands: boolean;
+}
+/**
+ * The first word of a `cp`, `mv`, `ln` or `install` argv that makes its write
+ * targets unknowable (APRV-511 fix round 3, S(open)), or `null`. GNU permutes
+ * options, so every word before `--` is in an option slot.
+ */
+export declare function copyArgvUnknown(args: readonly string[], flags?: readonly ArgExpansion[]): string | null;
+/**
+ * The destination directories a `cp`, `mv`, `ln` or `install` argv names by
+ * flag (APRV-511 refuter S3, recheck S(open)): `-t DIR`, `-tDIR`, `-t` anywhere
+ * in a short cluster (`-vtDIR`, `-rt DIR`, `-ftDIR`, `-stDIR`), and the long
+ * option by any unique prefix GNU accepts (`--target-directory=DIR`,
+ * `--target-dir=DIR`, `--t DIR`). A cluster is read from its first `t` even
+ * where an earlier letter would have taken the rest as its own value: one more
+ * target judged can only make the answer stricter. Words after `--` are
+ * operands. An absent value is not returned (the operand scan judges the rest).
+ */
+export declare function copyTargetDirectories(args: readonly string[]): string[];
+/**
+ * Where `curl` and `wget` write (APRV-511 refuter S1 and review): `files`,
+ * paths written by name (`curl -o F`, `-sSLoF`, `--output F`, `--outp=F`,
+ * `-D`, `-c`, `--trace`, `--stderr`; `wget -O F`, `--output-doc=F`, `-o`/`-a`
+ * logs), and `directories`, directories written with a name the server
+ * chooses (`curl -O` into `--output-dir` or `.`; `wget` without `-O` into
+ * `-P`/`--directory-p…` or `.`). `unknown` names the first option that makes
+ * the outputs unknowable: one this table does not know, an ambiguous prefix,
+ * or a config source (`curl -K`/`--config`, `wget -e`/`--execute`/`--config`).
+ * `-` is standard output and writes nothing. Any other binary writes nothing.
+ *
+ * Fix round 4 (M(L5f-1)): `sources` are the files an upload or request-body
+ * option READS ({@link uploadSourcePaths}), in every spelling: separated
+ * (`-T F`, `--data @F`), joined by `=` (`--upload-file=F`, `--data=@F`) and
+ * glued (`-TF`, `-sd@F`, `-Ff=@F`). `sourceUnknown` is the first option word
+ * whose EMBEDDED value names a file this text cannot read (a variable, a
+ * substitution, a glob or a brace in it). A separated value is a word of its
+ * own and is judged as the positional it also is.
+ */
+export declare function fetchOutputs(bin: string, args: readonly string[], flags?: readonly ArgExpansion[]): {
+    files: string[];
+    directories: string[];
+    unknown: string | null;
+    sources: string[];
+    sourceUnknown: string | null;
+};
 /**
  * The rules whose commands RUN CODE THIS RUNTIME DID NOT AUTHOR (APRV-193).
  *
@@ -815,9 +1137,35 @@ export interface CommandSegmentShape {
     text: string;
     bin: string | null;
     args: string[];
+    /** What the shell may still do to each of `args` (APRV-511 fix round 3). */
+    argFlags: ArgExpansion[];
     writes: string[];
     /** Paths read through `<` (APRV-445 recheck 3, SF3c). */
     reads: string[];
+    /** Is this segment's stdin the previous segment's output? (APRV-522.) */
+    stdinFed: boolean;
+    /**
+     * The inner text of every `$(…)` this segment expands: in its words, its
+     * redirection targets and an unquoted heredoc's body (APRV-522), so the
+     * hook's disk pass judges the reads a substitution makes.
+     */
+    substitutions: string[];
+    /**
+     * The `NAME=value` words before the binary (APRV-522 fix round 1, M-B): a
+     * prefix such as `CDPATH=` or `HOME=` steers where a `cd` lands.
+     */
+    assignments: string[];
+    /**
+     * The script of a login-shell wrapper, exactly as {@link loginShellScript}
+     * reads it for `classifyCommand` (APRV-522 fix round 1, M-A), or `null`.
+     */
+    script: string | null;
+    /**
+     * A known shell handed an inline-script flag in a shape
+     * {@link loginShellScript} does not unwrap (APRV-522 fix round 1, M-A): what
+     * its script reads cannot be judged, so the hook's disk pass fails closed.
+     */
+    opaqueShell: boolean;
 }
 export declare function commandSegmentShapes(command: string): CommandSegmentShape[] | null;
 export declare function commandSegmentWords(command: string): CommandSegmentWords[] | null;