approval-md 0.4.3 → 0.4.6

package/dist/src/cli/hook.d.ts

@@ -321,6 +321,28 @@ export declare const HOOK_DENY_CODES: readonly [
  * say about bytes it could see. Here there are no bytes to see.
  */
 "hook-hermes-execute-code-unbound", 
+/**
+ * An opaque program (`python3 -c`, `node -e` and kin, an interpreter running a
+ * file that is not a skill script, or a Hermes `execute_code` call with
+ * `exec.code.execute_code: hooked`) under a policy that NAMES the `exec.code`
+ * class but does not declare `exec.code.custody: attested` (APRV-510).
+ *
+ * Distinct from `hook-opaque`, and the distinction is the repair: that one
+ * says rewrite the command, this one says the operator has asked for the
+ * class and the one line that opens it is missing. A policy that does not
+ * name `exec.code` at all keeps today's refusal byte for byte, so this code
+ * is never a surprise to an operator who has not opted in. Nothing appends.
+ */
+"hook-exec-code-custody-unattested", 
+/**
+ * An `exec.code` file program this hook cannot read and hash (APRV-510): it
+ * is absent, unreadable by this process (EACCES under co-location), not a
+ * regular file, too large, or relative after a `cd` the hook cannot place.
+ * A record of an opaque program binds its hash, and a program whose bytes
+ * cannot be read is one nothing could bind, so it is refused rather than
+ * recorded without one. Nothing appends.
+ */
+"hook-exec-code-unreadable", 
 /** Malformed hook input, or a log/filesystem fact that stopped the check. */
 "hook-io"];
 export type HookDenyCode = (typeof HOOK_DENY_CODES)[number];
@@ -725,6 +747,95 @@ export declare function resolveReadRoots(cwd: string, gateRoot: string, declared
  * "absent yields today's answer" the classifier context promises.
  */
 export declare function refineReadScope(result: CommandClassification, roots: readonly string[], cwd: string): RefinedClassification;
+/** The rule a credential read found by resolving its path reports. */
+export declare const CREDENTIAL_RESOLVED_RULE = "credential-path-resolved";
+/**
+ * Every credential file a command reads once its paths are resolved the way
+ * the shell and the filesystem will resolve them (APRV-522, M4 and M5).
+ *
+ * The pure classifier judges the words as written. A word written relative
+ * after a `cd`, through a symlinked parent, as a glob, or inside a `$(…)` does
+ * not carry the segments the credential rule matches, so it was `read.shell`
+ * through the Claude Code hook (a relative read after a `cd` into the approval
+ * home, a read through a symlinked alias of it, a glob or `<` target naming a
+ * file in it), and through the Hermes hook too when the reader's segment also
+ * wrote, or the reader sat inside a substitution.
+ *
+ * Every adapter and `hook classify` reach this through {@link classifyForHook}.
+ * What is judged, per segment, whatever class the segment took:
+ *
+ * - the words {@link credentialReadWords} says the binary reads (the pure
+ *   rule's own list: positionals, option-embedded values, git `<rev>:<path>`),
+ *   and every `<` target;
+ * - each word expanded ({@link expandHookWord}, brace lists included), then
+ *   landed from every directory the command may be in: lexically
+ *   ({@link canonicalPath}) and physically ({@link physicalLanding}), a glob
+ *   expanded against its directory (or, where that is unknown, judged by
+ *   whether its pattern could name a credential);
+ * - a directory handed to a recursive reader or a directory copier, when it
+ *   {@link holdsCredentials}. git and diff count as recursive readers here
+ *   (fix round 1, S): git's no-index grep and diff walk a directory, and diff
+ *   compares a directory's files. A recursive search also reads the working
+ *   directory (fix round 1, M-E), whether or not it names a path, because
+ *   which of its words are option values cannot be known for every reader;
+ * - a one-operand link or copy keeps its only operand as a read, because the
+ *   destination is the working directory (fix round 1, M-F);
+ * - `cd` and `pushd` move the directory for later segments, the directories
+ *   before and after both kept (a `cd` may fail, or sit behind `||`), each as
+ *   spelled and with its symlinks resolved (fix round 2). After a `cd` this
+ *   hook cannot resolve, every later RELATIVE read word is a credential read:
+ *   where it lands is unknown, and it may be the vault. A `cd` is
+ *   unresolvable when its operand is a variable, `-`, a glob or a brace list,
+ *   or a tilde prefix this hook does not expand; when it carries an
+ *   assignment prefix; and in the argv shapes {@link cdTarget} lists. `popd`
+ *   is always unresolvable. (A segment that reassigns `HOME` or `CDPATH` on
+ *   its own, `export`, `unset` or `read` of either included, is refused by the
+ *   classifier before this pass runs.)
+ * - a relative operand that does not open with `./` or `../` may be found
+ *   through a `CDPATH` this hook cannot see (fix round 1, M-B). Since fix
+ *   round 2 that does not make the directory wholly unknown: the `cd` also
+ *   lands at `<unknown prefix>/<operand>`, and each later relative word is a
+ *   credential read there only when {@link steeredReadCouldNameCredential}
+ *   says that path could name credential material or a gate home. A
+ *   recursive reader, a word holding `..` and a `**` glob are credential
+ *   reads there, since what they reach below an unknown directory cannot be
+ *   bounded.
+ * - the body of every `$(…)`, and the script of every login-shell wrapper the
+ *   classifier unwraps (fix round 1, M-A), walked the same way from the
+ *   directory it runs in. A known shell handed an inline script in any other
+ *   shape is a credential read, since what it reads cannot be judged;
+ * - past {@link BRACE_WORD_CAP} brace words, or {@link SUBSTITUTION_DEPTH_CAP}
+ *   levels of nesting, a credential read (fix round 1, M-D).
+ *
+ * A word opening with a tilde prefix this hook does not expand (`~+`, `~-`,
+ * `~name`) is a credential read (fix round 1, M-C). A relative word read after an
+ * unresolvable `cd` is a credential read even when it holds a `$` this hook
+ * cannot expand (fix round 1, S-2). Otherwise a word left with such a `$` (a
+ * variable, or the substitution sentinel a `$(…)` leaves) is judged here for
+ * every adapter (APRV-524): by its text, by its literal prefix landed from
+ * each working directory, and, when its last component is the unresolved
+ * one, as a read of whatever that prefix holds, so a home or a directory that
+ * holds credentials makes it a credential read. A word holding the sentinel is
+ * judged once more with every sentinel removed, as a resolved path (the
+ * reading before APRV-511), so an empty substitution is judged too. The Hermes
+ * disk pass also fails closed on every recursive reader of such a word; this
+ * pass does not. Beyond that, a path held in a variable (which may be empty)
+ * or produced by a substitution's output is the accepted limit.
+ *
+ * `cwd` may name several directories (fix round 1, S-1): every one is a place
+ * the command may start in, and each is judged.
+ */
+export declare function credentialReadLandings(command: string, cwd: string | readonly string[], env?: NodeJS.ProcessEnv): Array<{
+    segment: string;
+    path: string;
+}>;
+/**
+ * Add an `account.credential` segment for every credential read
+ * {@link credentialReadLandings} finds that the text did not already name
+ * (APRV-522). Only ever adds: the segment's own class stays, and the
+ * credential read rides beside it in the shape the classifier's `also` has.
+ */
+export declare function refineCredentialReads(result: CommandClassification, command: string, cwd: string | readonly string[], env?: NodeJS.ProcessEnv): RefinedClassification;
 /**
  * The roots a write may land in, resolved.
  *
@@ -798,7 +909,20 @@ export declare function refineSkillScripts(result: CommandClassification, cwd: s
  * resolved gate scope wants and what this classifier did before the field
  * existed.
  */
-export declare function classifyForHook(command: string, protectedPaths: readonly ProtectedPathEntry[], cwd: string, readRoots?: readonly string[]): RefinedClassification;
+export declare function classifyForHook(command: string, protectedPaths: readonly ProtectedPathEntry[], cwd: string, readRoots?: readonly string[], 
+/**
+ * May an opaque program classify `exec.code`? (APRV-510.) `true` only when
+ * the loaded policy opens the class ({@link execCodeGate}); the default is
+ * today's answer, a refusal.
+ */
+execCode?: boolean, 
+/**
+ * Further directories the command may start in, judged by the credential
+ * pass only (APRV-522 fix round 1, S-1): the envelope's `cwd` where the
+ * harness sends no per-call directory. It only ever adds reads, so a stale
+ * or absent directory costs nothing.
+ */
+credentialCwds?: readonly string[]): RefinedClassification;
 /**
  * What the classifier made of a command (APRV-91 #9).
  *