approval-md 0.0.1 → 0.2.0

package/dist/src/core/protected-path-guard.d.ts

@@ -0,0 +1,453 @@
+/**
+ * The protected-path guard (APRV-151): CI asks the log, not the session.
+ *
+ * ## The hole this closes
+ *
+ * `approval hook claude-code` classifies a file-tool call before it applies,
+ * and when the target is a protected path the answer is `policy.edit` and the
+ * phone buzzes. That control is only as good as the wiring: a session whose
+ * PreToolUse hook never loaded edits SPEC.md with no prompt, no denial, and —
+ * this is the part that hurts — no refused-request record either. Nothing in
+ * the log says the edit happened, because the thing that would have written
+ * the record is the thing that did not run. Two incidents (2026-08-29 SPEC.md
+ * in worktree `aprv-145-land`, 2026-08-30 `.github/workflows/ci.yml` in
+ * `agent-a3f5d255372d43ac0`) are the same shape.
+ *
+ * A detector that asked the session whether it was hooked would be asking the
+ * party under oversight to report its own oversight, which SPEC.md §11 rules
+ * out on principle. So this one never talks to a session. It takes two commits,
+ * asks git which protected paths changed between them, and requires — for each
+ * one — exact evidence in the committed hash-chained log that either a human
+ * granted that edit or the runtime recorded that policy authorized its
+ * execution. A change with no evidence fails the pull request. Session wiring
+ * is not an input.
+ *
+ * ## What counts as evidence
+ *
+ * Evidence is about the CHANGE, not about the path (APRV-202). The guard reads
+ * the blob at both commits, reduces the difference to the lines this pull
+ * request adds and removes, and requires every one of them to trace back to
+ * bound material in an authorization record. A path authorized last Tuesday
+ * and edited again today has evidence naming it and none covering today's
+ * lines, and that fails. Naming remains necessary; it stopped being sufficient.
+ *
+ * Four verdicts pass:
+ *
+ * 1. `attested` — the policy file, and the gate's ORGANS. `approval policy
+ *    amend --commit` appends `policy.updated` carrying `{policy_path, sha256}`,
+ *    the SHA-256 of the policy bytes a human attested. So for `APPROVAL.md` the
+ *    guard does not look for a grant at all: it hashes the file's bytes AT THE
+ *    HEAD COMMIT and requires that exact digest in the log. This is the
+ *    strongest match in the system — content-level, not path-level — and it is
+ *    why amendment PRs pass without a `policy.edit` grant, which they would
+ *    never have.
+ *
+ *    Since APRV-272 the same verdict covers the gate's organs, the harness
+ *    files that install the hook (`.claude/settings.json` and kin), on a
+ *    `gate.organ.attested` record carrying that path and that digest. They need
+ *    it for a stronger reason than the policy file does: an organ is
+ *    `policy.core`, `policy.core` is human-only, and the gate mints NOTHING for
+ *    a human-only class — so `granted-file` and `granted-command` cannot exist
+ *    for one however correctly a human edited it, and before this the guard
+ *    could only ever fail such a change (PR #300). The path is part of the
+ *    match: a digest attested for one organ is not evidence for another, which
+ *    is why the organ record carries a whole relative path where the policy
+ *    record carries a basename.
+ * 2. `policy-authorized-file` — an exact Edit or Write whose verified
+ *    `execution.started` is preceded by its unique matching registration and no
+ *    approval request. The registration, start and recomputed stored payload
+ *    must agree on task, action, class and hash. The start must precede the
+ *    change and the recorded class must be the class this path is routed to.
+ *    This records authorization to execute, not successful completion; the
+ *    exact hunk checks below establish whether those bytes landed.
+ * 3. `granted-file` — a file-tool edit. The hook binds the CHANGE rather than
+ *    the touch (APRV-124), so the bound material carries `file` plus the exact
+ *    edit: `{before, after}` for an Edit, `{content}` for a Write. That is
+ *    HUNK-level evidence, and it is used as such. The granted `after` bytes
+ *    have to occur verbatim in the blob at head before any added line is
+ *    credited to them, and the granted `before` bytes have to occur in the blob
+ *    at base before any removed line is. A granted edit whose after-state is not
+ *    in head is a grant for something that did not land, and covers nothing.
+ *    Some payloads carry the `{input}` fallback shape instead, which describes
+ *    no bytes; those name the path and cover nothing.
+ * 4. `granted-command` — a shell edit. The bound material is `{command, cwd}`
+ *    or `{argv, cwd}`, and the guard re-runs the runtime's own
+ *    {@link classifyCommand} over it, requiring a segment that classifies as a
+ *    granting class BECAUSE of a word naming this path. A mention is not a
+ *    grant: `cat SPEC.md` is `read.shell` and proves nothing, and the first
+ *    draft of this module, which substring-matched, accepted `hook classify --
+ *    vi SPEC.md` as evidence for a later SPEC.md edit.
+ *
+ *    A command payload cannot describe hunks: `node scripts/apply.mjs` names
+ *    the file it will rewrite and says nothing about the bytes. So this kind is
+ *    attributed rather than covered, and three things all have to hold:
+ *
+ *    - The write lands on THIS checkout's copy of the path. The payload's `cwd`
+ *      joined with the repository-relative path has to be exactly the word the
+ *      classifier matched (see {@link commandTargetsPath}). Three of the grants
+ *      that would otherwise have carried PR #187's SPEC.md change were dry runs
+ *      into `$SCRATCH/dry/SPEC.md`.
+ *    - The grant was SPENT: an `execution.started` for its `action_key`, and
+ *      its `execution.completed` when the log has one. A grant nobody spent
+ *      authorized a command that never ran.
+ *    - That run sits within {@link DEFAULT_COMMAND_ATTRIBUTION_MS} of the
+ *      commit AND does not start after it. A command's effect follows its own
+ *      `execution.started`, so a run four hours after the commit did not write
+ *      it — a real batch, on 2026-09-02, that a symmetric window would have
+ *      credited with PR #187's changes.
+ *
+ *    The finding names the run it attributed the change to, so a reader can
+ *    check the attribution rather than take it. It stays weaker than
+ *    `granted-file` because time is a weaker link than bytes: everything the
+ *    approved run wrote to that path in its window is carried by it.
+ *
+ * There is deliberately no class-level pass. A `policy.edit` grant that exists
+ * in the window but names some other file is not evidence that anybody saw
+ * THIS edit, and accepting it would let one approved edit launder every other
+ * edit in the same window. Class-level grants appear in the failure detail as
+ * diagnosis, never as a verdict.
+ *
+ * ## Grants go stale
+ *
+ * Naming the path is necessary and not sufficient, because grants accumulate
+ * forever. Run without a recency rule against the real log, this guard passed a
+ * SPEC.md edit made on 2026-08-29 on the strength of a `git add SPEC.md`
+ * granted on 2026-08-20: once any edit to a path has ever been approved, every
+ * later edit to that path would inherit the approval. So evidence must also sit
+ * within {@link DEFAULT_LOOKBACK_MS} of the commit that introduced the change,
+ * on either side of it. Either side, because both orderings are real: a grant
+ * shortly BEFORE the commit is the ordinary case, and a grant shortly after is
+ * the grant-follows-write anomaly (APRV-117/150 adjacent) — a defect in its own
+ * right, but a complete consent trail all the same, and not this guard's to
+ * adjudicate.
+ *
+ * That bound used to be the guard's weakest joint: a repeat edit to the same
+ * path inside the window inherited the earlier grant, and the guard passed
+ * PR #187, #196 and #207 on grants that authorized some earlier edit. APRV-202
+ * closes it, and the window is now the cheap pre-filter in front of the real
+ * question. A grant inside the window still has to cover the lines: an
+ * uncovered change fails `uncovered-hunk` however fresh the grants naming its
+ * path are. Attestation is exempt from the bound, because it matches CONTENT: bytes that
+ * hash to an attested digest are the attested bytes whenever they were signed.
+ * And when git cannot date the change at all, no bound is applied rather than a
+ * weaker one invented: see `changeTsFor` on {@link GuardInput} for why a bound
+ * against the head commit would have been theatre. The finding says which of
+ * the two it got, every time.
+ *
+ * ## How a hunk is decided to be covered
+ *
+ * The unit is a line of text. `added` is the multiset of lines the head blob
+ * has and the base blob does not; `removed` is the converse. A line is covered
+ * when its exact text appears in the granted material of some in-window grant
+ * (in `after`/`content` for an added line, in `before` for a removed one) and
+ * that material is anchored to the blob it claims, as described above. Coverage
+ * may be assembled from several grants, because one pull request may carry
+ * several approved edits to one file; the finding names every contributing
+ * grant and puts the strongest and nearest at the head.
+ *
+ * Three properties of that choice are worth stating, because each is a limit:
+ *
+ * - A blob that differs while its line multiset does not is a REORDERING, and
+ *   it is reported as one uncovered hunk rather than as no change. A rule that
+ *   compared multisets alone would pass a rewrite that only moved paragraphs.
+ * - Blank and whitespace-only lines neither need coverage nor give it. They
+ *   carry no content, and treating them as material would let one granted edit
+ *   containing an empty line cover every blank line added anywhere.
+ * - Coverage is by line text, not by position. An added line whose exact text
+ *   appears in some granted edit counts as covered even if it landed somewhere
+ *   else in the file. Tightening that to positions would trade a narrow
+ *   laundering channel (repeating a line the human already approved) for false
+ *   failures on every rebase and re-indent, and the first is the cheaper loss.
+ *
+ * ## The evidence surface is not a protected write surface
+ *
+ * `.approval/` is protected wherever it sits, and the daemon appends to it
+ * every time anything is approved — so a records / log-advance pull request
+ * changes `.approval/log/events.jsonl`, the payload store beside it, and the
+ * regenerated `QUEUE.md`. Requiring a grant for those would require a grant for
+ * the evidence, which is circular and would make it impossible to land the very
+ * commits this guard reads. {@link EXEMPT_PREFIXES} names that surface, and
+ * nothing else under `.approval/` is exempt: the vault, the environment map and
+ * anything else that lands there is still a protected write.
+ *
+ * ## The lag, and the ordering rule it implies
+ *
+ * The log on `main` trails the primary checkout's live log; advances land
+ * periodically as records pull requests. A grant made this morning may not be
+ * on `main` yet, and this module can only see the records its caller hands it.
+ * That is not a bug to paper over, it is an ordering rule, and every failure
+ * states it: **the log advance carrying the grant must be pushed to a records
+ * branch or merged to main before or with the protected-path pull request.**
+ * Each failure also names the window it searched (the seq and timestamp range
+ * of the records it was given) so the reader can tell "the grant is not there"
+ * from "the grant is newer than this log".
+ *
+ * A records branch counts because the caller may read further along the same
+ * chain than the head commit does (APRV-260): `scripts/protected-path-guard.mjs`
+ * takes the freshest committed copy that carries head's own last record at
+ * head's index, so an advance that is pushed but not yet merged is already
+ * evidence. Nothing here changes: this module still reads only the verified
+ * records it was handed, and the window it reports is the window it searched.
+ *
+ * ## Fail closed
+ *
+ * A missing log, a log that does not pass chain verification, and a protected
+ * path with no evidence are all failures, each with its own code. Records that
+ * have not passed verification are never read for evidence (SPEC.md §11.1
+ * invariant 1): the caller hands this module the verified records or none.
+ * This module appends nothing, reads no clock, and performs no IO of its own —
+ * git plumbing and file reads live in the caller.
+ */
+import { type ProtectedPathEntry } from "./command-class.js";
+import type { EventRecord } from "./log.js";
+/**
+ * Classes whose grant authorizes a protected-path write.
+ *
+ * `policy.edit` is what the hook and this repository's policy use.
+ * `policy.core` is accepted alongside it because SPEC.md §7's taxonomy admits
+ * a stricter sibling and a policy that routed the highest-value edits there
+ * should not lose its evidence.
+ */
+export declare const GRANTING_CLASSES: readonly string[];
+/**
+ * Does a grant of this class authorize a protected-path write? (APRV-266.)
+ *
+ * The named classes above, plus any `policy.edit` sub-class a policy routes a
+ * path to. Both directions of the cross-check matter and both are accepted:
+ *
+ * - A grant of the ROUTED class is the ordinary case once a policy adopts
+ *   routing. `policy.edit.spec` is the class the hook asked about and the class
+ *   the human decided, so it is the class the record carries.
+ * - A grant of `policy.edit` ITSELF is accepted for a path now routed, because
+ *   a routing is a policy edit and the two are not synchronized: a grant taken
+ *   under yesterday's string-only policy, or under the daemon's own fallback
+ *   when the policy would not load, names `policy.edit` for a path today's
+ *   policy routes. Refusing it would make adopting a routing retroactively
+ *   invalidate evidence that was correct when it was taken.
+ *
+ * What this does NOT do is loosen the guard: the class only opens the door, and
+ * the naming test — the grant's own material has to name THIS path, and since
+ * APRV-202 has to cover the actual hunks — is unchanged and is what decides.
+ * A sub-class name is not authority over anything; the namespace is closed to
+ * `policy.edit.*` in the classifier, so no grant of `log.mutate` or
+ * `policy.core` can be manufactured by naming one (SPEC.md §11.1 invariant 9).
+ */
+export declare function isGrantingClass(actionClass: string): boolean;
+/**
+ * The daemon's own append surface: evidence, not a protected write.
+ *
+ * Repository-relative, `/`-separated prefixes. A changed path equal to one of
+ * these, or under one of the directory ones, is skipped before any evidence is
+ * sought. See the module note for why this carve-out is narrow on purpose.
+ */
+export declare const EXEMPT_PREFIXES: readonly string[];
+/** Every way this guard can refuse, as stable codes. */
+export declare const GUARD_FAILURE_CODES: readonly [
+/** The log blob does not exist at the head commit at all. */
+"log-missing", 
+/** The log exists and does not pass chain verification. */
+"log-unverified", 
+/** A protected path changed and nothing in the log is evidence for it. */
+"no-evidence", 
+/**
+ * Grants DO name this path, inside the window, and some added or removed line
+ * of this change traces to none of their bound material (APRV-202).
+ *
+ * Distinct from `no-evidence` on purpose, because the two ask different
+ * things of the reader. `no-evidence` says nobody approved anything about
+ * this file and the question is whether the hook fired at all.
+ * `uncovered-hunk` says somebody approved something about this file and it
+ * was not this, which is the repeat-edit shape: the grant is real, the
+ * consent trail for THESE bytes is missing, and the fix is to take the
+ * change to the gate rather than to hunt for a lost record.
+ */
+"uncovered-hunk", 
+/**
+ * The blobs at base and head could not be read for this path (git could not
+ * show them, or they are binary), so no coverage could be established.
+ * Failing is the fail-closed direction: a change the guard cannot read is not
+ * a change it has checked.
+ */
+"change-unreadable"];
+export type GuardFailureCode = (typeof GUARD_FAILURE_CODES)[number];
+/** How the verified log and bound material authorize this exact path. */
+export type EvidenceKind = "attested" | "policy-authorized-file" | "granted-file" | "granted-command";
+/**
+ * How far from the commit that introduced a change a grant may sit and still be
+ * evidence for it: seven days, either side. See the module note.
+ */
+export declare const DEFAULT_LOOKBACK_MS: number;
+/**
+ * How far from the change commit a granted command's RUN may sit and still be
+ * the run that produced it: six hours, either side.
+ *
+ * Deliberately much tighter than {@link DEFAULT_LOOKBACK_MS}, because it is
+ * carrying much more weight. A file grant is checked against the bytes, so the
+ * recency bound is only a sanity rail around a content match. A command grant
+ * has no bytes to check, so time is the whole attribution, and a week of it
+ * would re-open exactly the hole this closes: every later edit to a path some
+ * approved script once wrote would inherit that script's grant. Six hours is
+ * about a working session, which is the unit of "this run produced this
+ * commit"; a batch that legitimately takes longer than that is asked for a
+ * fresh approval, which costs one tap.
+ */
+export declare const DEFAULT_COMMAND_ATTRIBUTION_MS: number;
+/** Fail-closed resource bounds for exact protected-edit reconstruction. */
+export declare const EXACT_REPLAY_MAX_CANDIDATES = 128;
+export declare const EXACT_REPLAY_MAX_STATES = 2048;
+export declare const EXACT_REPLAY_MAX_EXAMINED_BYTES: number;
+export interface GuardFinding {
+    /** The changed path, repository-relative. */
+    path: string;
+    ok: boolean;
+    /** Present on a pass. */
+    evidence?: EvidenceKind;
+    /** The log record that is the evidence, on a pass. */
+    seq?: number;
+    ts?: string;
+    actor?: string;
+    /**
+     * Every grant that covered part of this change, in report order, strongest
+     * and nearest first. `seq` is the head of this list.
+     */
+    coveredBy?: readonly number[];
+    /** Present on a failure. */
+    code?: GuardFailureCode;
+    /**
+     * On `uncovered-hunk`, a sample of the lines that traced to no granted
+     * material, `+` for added and `-` for removed.
+     */
+    uncovered?: readonly string[];
+    /** Prose a reader can act on, on either outcome. */
+    detail: string;
+}
+/** A protected path's bytes at both ends of the range the guard is checking. */
+export interface ChangeBlobs {
+    /** The blob at base, or `null` when this pull request adds the file. */
+    base: string | null;
+    /** The blob at head, or `null` when this pull request deletes it. */
+    head: string | null;
+}
+/** The window of log the guard could see, for the failure messages. */
+export interface LogWindow {
+    /** Lowest and highest `seq` in the log at head, or `null` for an empty log. */
+    firstSeq: number | null;
+    lastSeq: number | null;
+    firstTs: string | null;
+    lastTs: string | null;
+    /** The commit range the caller diffed. */
+    base: string;
+    head: string;
+}
+export interface GuardInput {
+    /** Repository-relative paths that differ between base and head, deletions included. */
+    changedPaths: readonly string[];
+    /**
+     * Records from the log at HEAD that have passed chain verification.
+     * `null` means the log could not be verified or could not be read; pair it
+     * with `logStatus` so the guard can say which.
+     */
+    records: readonly EventRecord[] | null;
+    logStatus: "ok" | "missing" | "unverified";
+    /** Why the log did not verify, when `logStatus` is not `ok`. */
+    logDetail?: string;
+    /** `policy.protected_paths` from the policy, widening the built-in set. */
+    policyProtectedPaths: readonly ProtectedPathEntry[];
+    /**
+     * SHA-256 of the policy file's bytes at the head commit, or `null` when the
+     * head tree carries no policy file. Only used for the `attested` verdict.
+     */
+    policySha256AtHead: string | null;
+    /** The policy file's repository-relative path, e.g. `APPROVAL.md`. */
+    policyPath: string;
+    /**
+     * SHA-256 of one GATE ORGAN's bytes at the head commit, or `null` when the
+     * head tree does not carry that path (APRV-272).
+     *
+     * The per-path counterpart of {@link policySha256AtHead}, computed the same
+     * way and from the same place — the blob at the head COMMIT, never the
+     * working tree. Only used for the `attested` verdict on an organ.
+     *
+     * OPTIONAL, and a caller that omits it gets no organ verdict at all rather
+     * than a weaker one: an organ change then falls through to the grant search
+     * and fails like any other unevidenced protected path. That is the
+     * fail-closed direction, and it is what keeps a caller written before this
+     * field existed correct rather than newly permissive.
+     *
+     * A DELETED organ resolves to `null` here, so removing one cannot pass by
+     * attestation: there are no bytes at head for a human to have signed. That is
+     * deliberate — the repair for a deletion is a grant or a human's own commit
+     * outside a pull request, not a record about bytes that no longer exist.
+     */
+    organSha256AtHead?: (path: string) => string | null;
+    /**
+     * Resolve bound material from the committed payload store, by hash.
+     * Returns `null` when the head tree does not carry that payload.
+     */
+    payloadFor: (hash: string) => unknown | null;
+    /**
+     * The author timestamp of the newest commit in `base..head` that touched this
+     * path, as an ISO-8601 instant, or `null` when git could not say.
+     *
+     * With no anchor — `null`, or a value that does not parse — NO recency bound
+     * is applied to this path, and the finding says so in its own text rather
+     * than reporting a bound it did not enforce.
+     *
+     * That is stated plainly because it is the accepting direction and it would
+     * be easy to dress up. The alternative considered was to bound the grant
+     * against the head commit instead, and it was rejected as theatre: every
+     * record in the log AT head is already before head by construction, so the
+     * rule would pass everything it was asked about while reading like a check.
+     * A guard that reports a bound it cannot enforce is worse than one that
+     * admits it has none, because only the first kind gets trusted.
+     *
+     * In practice the anchor is missing only when git cannot date a path it just
+     * reported in the diff, which is a broken-git condition rather than an
+     * attacker-reachable one; refusing on it would fire only on that breakage.
+     * The path-level evidence requirement is unaffected and still holds.
+     */
+    changeTsFor: (path: string) => string | null;
+    /**
+     * The path's bytes at base and at head, or `null` when they could not be
+     * read (git could not show them, or the blob is binary).
+     *
+     * This is what makes the guard's question "was THIS change approved" rather
+     * than "was this path approved once" (APRV-202). `null` fails the path with
+     * `change-unreadable` rather than falling back to the path-level rule: the
+     * fallback is the hole.
+     */
+    blobsFor: (path: string) => ChangeBlobs | null;
+    /** Override {@link DEFAULT_LOOKBACK_MS}. */
+    lookbackMs?: number;
+    /** Override {@link DEFAULT_COMMAND_ATTRIBUTION_MS}. */
+    commandAttributionMs?: number;
+    window: LogWindow;
+}
+export interface GuardReport {
+    ok: boolean;
+    /** Every protected path that changed, in the order git reported them. */
+    findings: readonly GuardFinding[];
+    /** Changed paths skipped as the daemon's own append surface. */
+    exempt: readonly string[];
+    window: LogWindow;
+}
+/** Is this changed path the daemon's own evidence surface? */
+export declare function isExemptPath(path: string): boolean;
+/**
+ * Is this changed path one whose edit requires a human decision?
+ *
+ * The guarded set is exactly the hook's ({@link isProtectedPath}, built-ins
+ * plus `policy.protected_paths`) minus the evidence surface. Sharing the
+ * predicate is the point: a CI guard whose idea of "protected" drifted from the
+ * hook's would fail the changes the hook already gated and pass the ones it
+ * would have caught.
+ */
+export declare function isGuardedPath(path: string, policyProtectedPaths: readonly ProtectedPathEntry[]): boolean;
+/**
+ * Evaluate a candidate against the committed log. Pure: no IO, no clock.
+ *
+ * @see GuardInput for what the caller has to gather.
+ */
+export declare function evaluateProtectedPaths(input: GuardInput): GuardReport;
+/** The report as the lines CI prints. Pure. */
+export declare function renderGuardReport(report: GuardReport): string;