approval-md 0.2.0 → 0.4.0

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

@@ -32,6 +32,20 @@
  * Self-reported text is never read. The hook passes the command only; the
  * harness's `description` field is authored by the very agent being gated
  * (SPEC.md §11.1: self-reported fields never reduce scrutiny).
+ *
+ * Two imports, and both are pure in exactly the same way this file is: no disk,
+ * no clock, no environment, no dependencies.
+ *
+ * `core/read-scope.ts` (APRV-347) holds the read-side path arithmetic, so the
+ * hook and the policy explainer can ask the same questions this file asks, of
+ * the same table, rather than each growing a copy of it.
+ *
+ * `core/policy-match.ts` (APRV-354) is imported for ONE name, the
+ * `harness.launch.` prefix. The classifier emits the family and two enforcement
+ * paths refuse a member of it that no policy rule names, so the three have to
+ * agree on what the family is; a second spelling of the prefix would close one
+ * of those doors and leave the other open. The import is type-safe in the
+ * dependency sense as well: `policy-match.ts` itself imports only types.
  */
 /** Why a command could not be classified. Each denies; none is a soft failure. */
 export type ClassifierFailureCode = "unclassified" | "opaque" | "unparseable";
@@ -122,6 +136,14 @@ export declare const GATE_SELF_CLASS = "gate.self";
  *   a policy can sensibly sample.
  */
 export type ProtectedPathClass = "log.mutate" | "policy.core" | "policy.edit";
+/**
+ * The class a write under `$HERMES_HOME/scripts/` takes (APRV-445): scheduling
+ * code that Hermes's cron runs later with no hook in front of it. Returned by
+ * {@link protectedPathClass} beside the organs, ranked with `policy.edit`, and
+ * deliberately not a {@link ProtectedPathClass}: it is a side effect an
+ * operator prices, not a surface of the gate itself.
+ */
+export declare const HERMES_SCHEDULED_SCRIPT_CLASS = "cron.manage";
 /**
  * The `policy.edit` sub-class namespace a `protected_paths` entry may route to
  * (APRV-266).
@@ -317,6 +339,16 @@ export declare function normalizePathSpelling(candidate: string): string;
  * refuses to honor.
  */
 export declare function isGateOrganPath(candidate: string): boolean;
+/**
+ * Files under the approval home that hold credential material.
+ *
+ * Named by their position under `.approval/`, so this is the same pure segment
+ * matching every other rule in this file uses: `vault*` (the sealed store and
+ * anything beside it), `keys/` (the subtree), and `env` (plus `env.local` and
+ * kin), which is the environment map holding the Telegram token, the vault
+ * passphrase and the sampling secret.
+ */
+export declare function isCredentialPath(candidate: string): boolean;
 /**
  * Environment variables whose NAME says they carry a secret.
  *
@@ -352,6 +384,26 @@ 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;
+interface LexWord {
+    /** Literal text, quotes removed and backslash escapes applied. */
+    text: string;
+    /** True when any part of the word was quoted. */
+    quoted: boolean;
+    /** Inner text of each `$(…)` in this word, for recursive classification. */
+    substitutions: string[];
+}
+interface LexRedirect {
+    /** `>` and `>>` write; `<` reads. */
+    op: ">" | ">>" | "<";
+    target: LexWord;
+}
+interface LexSegment {
+    text: string;
+    words: LexWord[];
+    redirects: LexRedirect[];
+    /** Set when the segment contains a construct whose effect cannot be read. */
+    opaque: string | null;
+}
 /**
  * Facts about the machine the command will run on, resolved by the CALLER
  * (APRV-267).
@@ -381,6 +433,38 @@ export interface ClassifierContext {
      * own: a path under a root still has to survive that second pass.
      */
     scratchRoots?: readonly string[];
+    /**
+     * Roots a read may stay inside: the gate root, the session scratchpad and the
+     * system temp root, plus whatever `read_scope.roots` added (APRV-347).
+     *
+     * The polarity is the OPPOSITE of `scratchRoots`, and the difference is worth
+     * stating. A scratch root LOOSENS a delete, so forgetting the field is safe
+     * by construction. A read root NARROWS a read, so forgetting the field would
+     * be safe in a different way — it leaves every read `read.shell`, exactly as
+     * this classifier answered before the field existed. An EMPTY array means the
+     * same thing as absent, and deliberately: read against no roots at all would
+     * make every read in the session a decision, which is a fail-closed answer
+     * nobody asked for and the one spelling a caller reaches by accident. A
+     * caller that means to scope reads passes roots.
+     *
+     * As with `scratchRoots`, this file only compares segments. The relative
+     * paths, the symlinks and the working directory are the hook's second pass,
+     * which can only ever tighten the answer reached here.
+     */
+    readRoots?: readonly string[];
+    /**
+     * May a login-shell wrapper be classified by the script it runs (APRV-380)?
+     *
+     * `true` by default, and `false` for exactly one caller: the classifier
+     * itself, recursing into an unwrapped script. That is what keeps the unwrap
+     * ONE LEVEL deep — a shell nested inside the script is the shape the
+     * {@link OPAQUE_BINS} position still covers, and it stays opaque.
+     *
+     * A caller that passes `false` gets the pre-APRV-380 answer, which is the
+     * strictly stricter one: every wrapper refuses. As with every other field
+     * here, forgetting it cannot loosen anything.
+     */
+    unwrapShell?: boolean;
 }
 /** Everything a refinement needs: the binary and the words that followed it. */
 interface RuleContext {
@@ -413,6 +497,7 @@ interface RuleContext {
 type Refinement = {
     class: string;
     rule: string;
+    path?: string;
 } | {
     opaque: string;
 };
@@ -434,7 +519,32 @@ export interface CommandRule {
     emits?: readonly string[];
     /** Flag-sensitive answer; falls back to `class` when it returns `null`. */
     refine?: (ctx: RuleContext) => Refinement | null;
+    /**
+     * Match only an argv that is nothing but version or help flags (APRV-397).
+     *
+     * The row a binary needs when the thing being classified is the ABSENCE of a
+     * subcommand: `npm --version` carries no positional, so `subs` can never
+     * match it, and a row with no `subs` at all would have matched every
+     * subcommand this table does not name and turned a wall of `unclassified`
+     * denials into whatever class that row declared. A `probe` row matches the
+     * probe shape and nothing else, so everything it does not match keeps the
+     * answer it has today.
+     */
+    probe?: boolean;
 }
+/**
+ * The suffix that marks a Muse model as training on what it is shown.
+ *
+ * Exported since APRV-350 so the hook adapter's contributor guard and this
+ * classifier's `harness.launch.muse` refinement test the SAME mark. Two
+ * spellings of "which models are unsafe" would drift, and the direction they
+ * drift in is the one where a launch is refused and a tool call is not.
+ */
+export declare const CONTRIBUTOR_SUFFIX = "-contributor";
+/** The rule id for a read whose ABSOLUTE target sits outside every root. */
+export declare const READ_OUT_OF_SCOPE_RULE = "read-out-of-scope";
+/** The rule id for a read target whose expansion the text cannot show. */
+export declare const READ_UNREADABLE_TARGET_RULE = "read-unreadable-path";
 /**
  * The table.
  *
@@ -446,6 +556,42 @@ export interface CommandRule {
  * move the log file, introduced by SPEC §10.1's APRV-125 amendment.
  */
 export declare const COMMAND_RULES: readonly CommandRule[];
+/**
+ * The script a LOGIN-SHELL WRAPPER runs, when the segment is exactly one
+ * (APRV-380), or `null`.
+ *
+ * ## Why this is not the second parser the table above refuses
+ *
+ * {@link OPAQUE_BINS} states the position this narrows: a second parser for the
+ * same text is a second answer waiting to disagree with the shell's. The hazard
+ * that names is reading shell text a SECOND WAY. This is not that. When the
+ * argv is exactly `[shell, -lc, script]` and nothing else, the script is the
+ * text a Claude Code `Bash` call hands this classifier directly, and what
+ * happens to it here is what happens to that: the same lexer, the same segment
+ * rules, the same table. No new parser is written, and the text is not read a
+ * second way — it is read the first way, by the only reader there is.
+ *
+ * ## The line, and it is exact
+ *
+ * Three words, no more: a known shell, one inline-script flag, one script. Any
+ * of these keeps the wrapper opaque, because each is a shape whose effect
+ * depends on something the argv alone does not say:
+ *
+ * - extra words (a script FILE, `--`, an option this rule does not model);
+ * - an assignment prefix, which changes the environment the script runs in;
+ * - a redirection on the wrapper, which is the outer shell's and not the
+ *   script's;
+ * - 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 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
+ * classified, and the classes are additional evidence about bytes that are
+ * bound elsewhere and unchanged.
+ */
+export declare function loginShellScript(segment: LexSegment): string | null;
 /**
  * The rules whose commands RUN CODE THIS RUNTIME DID NOT AUTHOR (APRV-193).
  *
@@ -473,6 +619,39 @@ export declare const CODE_EXECUTING_RULES: readonly string[];
  * it WITH the policy in hand — {@link emittableClass} is that question.
  */
 export declare const CLASSIFIER_CLASSES: readonly string[];
+/**
+ * The class the DAEMON's own cadence advance is gated as (APRV-382).
+ *
+ * The sub-class exists because the policy grammar has no actor condition and
+ * this repository wanted one: an advance publishes records the log already
+ * holds, so the daemon may make it unattended, while the same act from a
+ * session in a worktree or a human terminal stays supervised. Two classes are
+ * how that is written down, and which of them a cycle asks under is decided by
+ * `core/advance-cycle.ts` from the running process, never from an argument.
+ *
+ * NO COMMAND SPELLS IT, on purpose. `approval log advance` classifies
+ * `log.advance` whoever types it, so the looser line is unreachable from a
+ * shell an agent can drive: it is reached only from inside the daemon process,
+ * which an agent cannot become without a `gate.self` command this policy holds
+ * at the manual default.
+ */
+export declare const ADVANCE_DAEMON_CLASS = "log.advance.daemon";
+/**
+ * Classes this RUNTIME emits for its own gated actions, which no command spells.
+ *
+ * Separate from {@link CLASSIFIER_CLASSES}, which is the binary table's own set
+ * and is what `docs/claude-code-hook.md` documents row by row. A class here is
+ * emitted by a runtime cycle that registers and requests it directly — the
+ * daemon's advance is the first — so a policy declaring it is declaring a line
+ * that CAN fire, and the reachability check `core/policy-expectations.ts` runs
+ * at the amendment ceremony must say so. Without this list that ceremony would
+ * refuse the line `unreachable`, which is a true statement about the command
+ * classifier and a false one about the runtime.
+ *
+ * Adding a name here is a claim that some path in this codebase asks the gate
+ * for that class, and widening it is a reviewable diff.
+ */
+export declare const RUNTIME_CLASSES: readonly string[];
 /**
  * Can the classifier emit `actionClass` for a project whose policy carries
  * these `protected_paths`? (APRV-266.)
@@ -488,6 +667,11 @@ export declare const CLASSIFIER_CLASSES: readonly string[];
  * A routed name is reachable exactly when some entry routes to it. A
  * `policy.edit.spec` rule in a policy whose `protected_paths` routes nothing to
  * it is a line that will never fire, and saying so is the whole point.
+ *
+ * {@link RUNTIME_CLASSES} is the third answer (APRV-382): a class no command
+ * spells and a runtime cycle asks for directly is reachable in every project,
+ * with no policy entry needed, because the path that emits it is in this
+ * codebase rather than in the operator's file.
  */
 export declare function emittableClass(actionClass: string, protectedPaths?: readonly ProtectedPathEntry[]): boolean;
 /**
@@ -539,5 +723,26 @@ export interface CommandSegmentWords {
  * `classifyCommand` answers `unparseable` for. Segments carrying no binary (a
  * bare assignment, a lone redirection) are omitted: they have no verb to show.
  */
+/**
+ * The paths each segment WRITES through a redirection, from the same parse
+ * (APRV-445). `<` is a read and is left out, as are the discard devices.
+ * `null` when the tokenizer refuses the string.
+ */
+export declare function commandSegmentWriteTargets(command: string): string[][] | null;
+/**
+ * Every segment of `command` with its binary (or `null`), its arguments and the
+ * paths it writes through a redirection, from ONE lex of the whole command
+ * (APRV-445 recheck). Lexing a segment's text on its own fails for a heredoc,
+ * whose body lives outside the segment's text; this keeps the body attached.
+ */
+export interface CommandSegmentShape {
+    text: string;
+    bin: string | null;
+    args: string[];
+    writes: string[];
+    /** Paths read through `<` (APRV-445 recheck 3, SF3c). */
+    reads: string[];
+}
+export declare function commandSegmentShapes(command: string): CommandSegmentShape[] | null;
 export declare function commandSegmentWords(command: string): CommandSegmentWords[] | null;
 export {};