@webpieces/rules-config 0.4.718 → 0.4.720

package/src/human-authorization.js

@@ -1,376 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HumanAuthorizationService = exports.AuthorizedOverrides = exports.AuthorizationCheck = exports.AuthorizationContext = exports.AuthorizationFile = exports.HumanApproval = exports.DEFAULT_APPROVAL_HOURS = exports.AUTHORIZATIONS_DIR = void 0;
-const tslib_1 = require("tslib");
-const crypto_1 = require("crypto");
-const fs = tslib_1.__importStar(require("fs"));
-const path = tslib_1.__importStar(require("path"));
-const inversify_1 = require("inversify");
-const state_dir_1 = require("./state-dir");
-const exclude_paths_1 = require("./exclude-paths");
-const to_error_1 = require("./to-error");
-// The directory under `.webpieces/` that holds one authorization file per branch. Gitignored with the
-// rest of `.webpieces/` — deliberately, see HumanAuthorizationService's docstring.
-exports.AUTHORIZATIONS_DIR = 'authorizations';
-// How long a fresh approval is good for, in hours, when the human does not say otherwise. An approval is
-// for TODAY'S work, not a standing grant: the thing being authorized is a specific partial delivery, and
-// a grant that outlives the sitting it was given in is one nobody remembers giving.
-exports.DEFAULT_APPROVAL_HOURS = 4;
-// The marker version in the signed payload. An approval signed under a different version does not verify,
-// so the payload can gain a field without a stale entry silently continuing to pass.
-const PAYLOAD_VERSION = 'wp-authorize-v1';
-/**
- * ONE human approval of ONE checklist's override, on ONE branch. Data-only (per CLAUDE.md).
- *
- * `approves` is prose the human typed at the tty in their own words, and it is the POINT of the record:
- * `wp-check-auth` prints it, so a reviewer can judge whether the approval actually covers the thing it is
- * being applied to — not merely that *an* approval exists on this branch.
- *
- * `hmac` is `HMAC-SHA256(prGate.gateSalt, canonical payload)` over every other field plus the branch. It
- * is what makes the approval VERIFIABLE by an agent that cannot MINT one: the agent runs `wp-check-auth`,
- * which recomputes the HMAC, rather than believing a claim relayed to it in a message.
- */
-class HumanApproval {
-    checklist; // the checklist id this authorizes an override of (= the reviewer subagent name)
-    gate; // the specific gate inside that checklist, or '' for the checklist as a whole
-    approves; // the human's OWN words: what they are approving and why
-    scopePaths; // globs the diff touched when approved; the approval dies if it grows past them
-    forkPoint; // merge-base when approved; survives new commits, dies on a re-based branch
-    issuedAt; // ISO
-    expiresAt; // ISO
-    hmac; // '' until signed
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(checklist, gate, approves, scopePaths, forkPoint, issuedAt, expiresAt, hmac = '') {
-        this.checklist = checklist;
-        this.gate = gate;
-        this.approves = approves;
-        this.scopePaths = scopePaths;
-        this.forkPoint = forkPoint;
-        this.issuedAt = issuedAt;
-        this.expiresAt = expiresAt;
-        this.hmac = hmac;
-    }
-}
-exports.HumanApproval = HumanApproval;
-/**
- * The append-only authorization file for ONE branch: N approvals, each naming what it approves. Data-only.
- *
- * The unit is the BRANCH, not the gate, because one run of work routinely needs more than one override and
- * they arrive at different times. One file per gate would mean the human re-answering the same "where does
- * this go?" question on every approval.
- */
-class AuthorizationFile {
-    branch;
-    approvals;
-    /**
-     * '' when the file was absent or read cleanly. Non-empty = it EXISTS but could not be parsed, and the
-     * reason.
-     *
-     * Carried rather than swallowed because "no approvals" and "approvals I could not read" are different
-     * facts and the second one is actionable: a corrupt file means the human's approval is sitting on disk
-     * unreadable, and the fix is to re-authorize rather than to wonder why nothing was found. `verifiedFor`
-     * turns this into a `rejected` line, which `wp-check-auth` already prints.
-     */
-    unreadable;
-    constructor(branch = '', approvals = [], unreadable = '') {
-        this.branch = branch;
-        this.approvals = approvals;
-        this.unreadable = unreadable;
-    }
-}
-exports.AuthorizationFile = AuthorizationFile;
-/**
- * The git facts an approval is verified AGAINST, gathered once by the caller. Data-only.
- *
- * A data class rather than four parameters because the four must describe ONE branch state: a `forkPoint`
- * resolved from one tree checked against a `changedFiles` gathered from another is a verification that
- * means nothing, and separate parameters are how that happens.
- */
-class AuthorizationContext {
-    branch;
-    forkPoint;
-    changedFiles;
-    now;
-    constructor(branch, forkPoint, changedFiles = [], now = new Date()) {
-        this.branch = branch;
-        this.forkPoint = forkPoint;
-        this.changedFiles = changedFiles;
-        this.now = now;
-    }
-}
-exports.AuthorizationContext = AuthorizationContext;
-/**
- * The verdict on ONE approval. `ok` false ⇒ `reason` says WHICH of the four bindings failed, in the
- * human's terms, because that is the sentence the agent has to relay back to them. Data-only.
- */
-class AuthorizationCheck {
-    ok;
-    reason; // '' when ok
-    approval;
-    constructor(ok, reason, approval) {
-        this.ok = ok;
-        this.reason = reason;
-        this.approval = approval;
-    }
-}
-exports.AuthorizationCheck = AuthorizationCheck;
-/**
- * What a branch is actually authorized to override RIGHT NOW: checklist id → the human's `approves` prose.
- * Data-only, with accessors so every consumer asks the question one way.
- *
- * `rejected` carries the approvals that were found but did NOT verify, one rendered line each. They are
- * kept rather than dropped because "there is an approval on this branch, and here is why it no longer
- * counts" is a completely different message from "nobody has authorized anything" — the first needs a
- * re-authorization, the second needs a human at all — and an empty map cannot tell them apart.
- */
-class AuthorizedOverrides {
-    proseById;
-    rejected;
-    constructor(proseById = new Map(), rejected = []) {
-        this.proseById = proseById;
-        this.rejected = rejected;
-    }
-    has(checklistId) {
-        return this.proseById.has(checklistId);
-    }
-    /** The human's own words for `checklistId`, or '' when it is not authorized. */
-    proseFor(checklistId) {
-        return this.proseById.get(checklistId) ?? '';
-    }
-}
-exports.AuthorizedOverrides = AuthorizedOverrides;
-/**
- * Mints (for a HUMAN at a tty) and verifies (for ANYONE, agents included) the human-authorization records
- * that are the ONLY channel by which a review checklist's override may be granted.
- *
- * ─── The problem ───────────────────────────────────────────────────────────────────────────────────────
- * A required checklist goes red, the human authorizes the partial scope, and there is NO channel by which
- * the subagent doing the work can know that. Every channel available before this carried a CLAIM of
- * authorization and never EVIDENCE of it: a coordinator relaying the human's words is unverifiable by
- * construction (and correctly refused — that refusal is the shape a prompt injection exploits); a ticket
- * comment can be written by an agent holding the same MCP; and the `override` field in review-<id>.json is
- * the agent authorizing itself.
- *
- * So the property this class buys is exactly one sentence: **an agent can VERIFY an authorization it
- * cannot MINT.** `wp-authorize` reads the approval from `/dev/tty`, which an agent's Bash tool has no way
- * to answer; `wp-check-auth` recomputes the HMAC and is read-only, so agents run it freely.
- *
- * ─── Bound to SCOPE, never to a diff sha ───────────────────────────────────────────────────────────────
- * An approval bound to the head-commit diff would be void on the next commit, so the human would
- * re-authorize on every push and nobody would use it. Each approval binds to WHAT WAS APPROVED instead:
- *   • `scopePaths` — the globs the diff touched when approved. A "terraform only" approval is void the
- *     moment app files appear, which is the abuse actually worth stopping.
- *   • `forkPoint`  — the merge-base when approved. Survives new commits; dies if the branch is restarted.
- *   • `expiresAt`  — hours, not days.
- * Edits inside the approved scope keep working; widening it does not. That is what the human means when
- * they say "yes, ship the terraform half".
- *
- * ─── Where the file lives, and why it is SHARED rather than per-worktree ───────────────────────────────
- * `dotWebpieces.shared()/authorizations/<branch-slug>.json`, keyed by BRANCH. Not `local()`: the human
- * routinely types `wp-authorize` in the primary clone while the agent works in a linked worktree, and
- * under `local()` those are two different files — the approval would be minted somewhere the agent never
- * looks, which is the same stall this feature exists to end. The branch key is what makes sharing safe:
- * an approval names its branch inside the SIGNED payload, so a file copied to another branch does not
- * verify there.
- *
- * It is never committed (`.webpieces/` is gitignored in full). A committed authorization would travel to
- * branches nobody approved.
- *
- * ─── Honest limits — do not oversell this ─────────────────────────────────────────────────────────────
- * The agent runs as the SAME OS USER as the human, and the HMAC key is `prGate.gateSalt`, which lives in a
- * committed file agents read routinely. Nothing here is cryptographically airtight against a determined
- * model; the real enforcement is the tty affordance plus the harness deny rule. That is fine, because the
- * problem being solved is agents drifting, guessing, or being confused by relays — not an adversarial
- * model. Moving the key to `~/.webpieces/authorize.key` is a one-line change to `sign()` if the threat
- * model ever changes; nothing else in the design moves.
- *
- * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
- */
-let HumanAuthorizationService = class HumanAuthorizationService {
-    dotDir;
-    constructor(dotDir = state_dir_1.dotWebpieces) {
-        this.dotDir = dotDir;
-    }
-    /** The repo-wide authorizations directory. See the class docstring for why `shared()` and not `local()`. */
-    dirFor(repoRoot) {
-        return this.dotDir.sharedFile(repoRoot, exports.AUTHORIZATIONS_DIR);
-    }
-    /**
-     * A filesystem-safe leaf for a branch name. Slashes and anything exotic collapse to `-`, so
-     * `dean/one-2779-grants` becomes `dean-one-2779-grants`.
-     *
-     * A collision between two slugs is harmless: the branch is inside the SIGNED payload, so an approval
-     * that landed in a colliding file fails `verify` on the branch check rather than leaking across.
-     */
-    slugFor(branch) {
-        return branch.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
-    }
-    pathFor(repoRoot, branch) {
-        return path.join(this.dirFor(repoRoot), `${this.slugFor(branch)}.json`);
-    }
-    /**
-     * The exact bytes that get signed: a version tag, the branch, and every field of the approval EXCEPT
-     * the hmac, in a fixed order with `scopePaths` sorted.
-     *
-     * Fixed order and sorting are load-bearing — `JSON.stringify` over a re-parsed object preserves
-     * insertion order, so a round-tripped approval whose keys arrived in a different order would compute a
-     * different payload and fail to verify a signature that is perfectly good.
-     */
-    canonicalPayload(branch, approval) {
-        return [
-            PAYLOAD_VERSION,
-            branch,
-            approval.checklist,
-            approval.gate,
-            approval.approves,
-            [...approval.scopePaths].sort().join(','),
-            approval.forkPoint,
-            approval.issuedAt,
-            approval.expiresAt,
-        ].join('\n');
-    }
-    /** `HMAC-SHA256(salt, canonical payload)`. '' for an empty salt — the caller treats '' as "not configured". */
-    sign(branch, approval, salt) {
-        if (salt.trim() === '')
-            return '';
-        return (0, crypto_1.createHmac)('sha256', salt).update(this.canonicalPayload(branch, approval)).digest('hex');
-    }
-    /** The same approval, carrying its signature. Never mutates the input. */
-    signed(branch, approval, salt) {
-        return new HumanApproval(approval.checklist, approval.gate, approval.approves, approval.scopePaths, approval.forkPoint, approval.issuedAt, approval.expiresAt, this.sign(branch, approval, salt));
-    }
-    /**
-     * Every approval recorded for `branch`, signature UNCHECKED. An absent or unreadable file is an EMPTY
-     * file, never a throw: a corrupt authorization must degrade to "nothing is authorized", which is the
-     * safe direction, and a branch that cannot open its own authorization file must still be able to run
-     * the gate and be told to go get one.
-     */
-    load(repoRoot, branch) {
-        const p = this.pathFor(repoRoot, branch);
-        if (!fs.existsSync(p))
-            return new AuthorizationFile(branch);
-        // webpieces-disable no-unmanaged-exceptions -- chokepoint: unreadable authorizations mean "none", never a crash
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-        try {
-            // webpieces-disable no-any-unknown -- parsed JSON is opaque until each field is narrowed below
-            const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
-            const list = Array.isArray(raw['approvals']) ? raw['approvals'] : [];
-            return new AuthorizationFile(branch, list.map((e) => this.toApproval(e)));
-        }
-        catch (err) {
-            const error = (0, to_error_1.toError)(err);
-            // Fail CLOSED on the grant, but say so: nothing is authorized either way, and reporting WHY is
-            // the difference between "ask the human to authorize" and "ask the human to authorize AGAIN
-            // because their last one is unreadable on disk".
-            return new AuthorizationFile(branch, [], `${p} exists but could not be read (${error.message})`);
-        }
-    }
-    // One parsed entry. Every field is read defensively — a hand-edited file is exactly the input this must
-    // survive, and a missing field simply yields '' / [], which then fails the signature check.
-    // webpieces-disable no-any-unknown -- opaque parsed JSON entry; each field is narrowed here
-    toApproval(entry) {
-        const raw = (typeof entry === 'object' && entry !== null ? entry : {});
-        return new HumanApproval(this.str(raw['checklist']), this.str(raw['gate']), this.str(raw['approves']), this.strList(raw['scopePaths']), this.str(raw['forkPoint']), this.str(raw['issuedAt']), this.str(raw['expiresAt']), this.str(raw['hmac']));
-    }
-    // webpieces-disable no-any-unknown -- reading ONE opaque field out of hand-editable JSON; narrowed right here
-    str(value) {
-        return typeof value === 'string' ? value : '';
-    }
-    // webpieces-disable no-any-unknown -- reading ONE opaque field out of hand-editable JSON; narrowed right here
-    strList(value) {
-        if (!Array.isArray(value))
-            return [];
-        // webpieces-disable no-any-unknown -- element of an opaque JSON array, narrowed by the type guard
-        return value.filter((v) => typeof v === 'string');
-    }
-    /**
-     * APPEND one signed approval to the branch's file and return the path written. Append, never replace:
-     * a run of work needs several overrides at different times, and each one is its own record of intent.
-     */
-    append(repoRoot, branch, approval, salt) {
-        const file = this.load(repoRoot, branch);
-        file.approvals.push(this.signed(branch, approval, salt));
-        const p = this.pathFor(repoRoot, branch);
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, JSON.stringify(new AuthorizationFile(branch, file.approvals), null, 2) + '\n');
-        return p;
-    }
-    /**
-     * Verify ONE approval against the branch state, in the order a reader wants to hear it: signature,
-     * expiry, fork point, scope. Signature first — an unsigned entry's other fields are not evidence of
-     * anything, and reporting "expired" for a forged record would be answering the wrong question.
-     */
-    verify(ctx, approval, salt) {
-        const expected = this.sign(ctx.branch, approval, salt);
-        if (expected === '' || approval.hmac !== expected) {
-            return this.fail(approval, 'its signature does not verify — it was hand-written, edited after '
-                + 'signing, minted on a different branch, or the repo\'s prGate.gateSalt changed');
-        }
-        if (this.expired(approval, ctx.now)) {
-            return this.fail(approval, `it EXPIRED at ${approval.expiresAt} (an approval is for the sitting it was given in)`);
-        }
-        if (approval.forkPoint !== '' && ctx.forkPoint !== '' && approval.forkPoint !== ctx.forkPoint) {
-            return this.fail(approval, `the branch was restarted from a different base — approved at fork point `
-                + `${approval.forkPoint.slice(0, 12)}, now ${ctx.forkPoint.slice(0, 12)}`);
-        }
-        const outside = this.outsideScope(approval, ctx.changedFiles);
-        if (outside.length > 0) {
-            return this.fail(approval, `the diff now touches ${outside.length} file(s) OUTSIDE the approved scope `
-                + `(${approval.scopePaths.join(', ')}): ${outside.slice(0, 5).join(', ')}`);
-        }
-        return new AuthorizationCheck(true, '', approval);
-    }
-    fail(approval, reason) {
-        return new AuthorizationCheck(false, reason, approval);
-    }
-    // An approval with no parseable `expiresAt` is treated as EXPIRED. Failing closed is the only safe
-    // reading: a missing expiry on a record whose whole purpose is to be time-bounded is a broken record,
-    // and the alternative reading is a grant that never ends.
-    expired(approval, now) {
-        const at = Date.parse(approval.expiresAt);
-        if (Number.isNaN(at))
-            return true;
-        return at <= now.getTime();
-    }
-    /**
-     * The changed files NOT covered by `scopePaths`. An approval with an EMPTY `scopePaths` covers nothing
-     * and is therefore always out of scope when anything changed — `wp-authorize` never mints one, and the
-     * alternative reading ("empty means everything") is precisely the widening-by-absence that makes the
-     * permissive path the shortest thing to type.
-     */
-    outsideScope(approval, changedFiles) {
-        return changedFiles.filter((f) => !(0, exclude_paths_1.matchesAnyGlob)(f, approval.scopePaths));
-    }
-    /**
-     * THE question every consumer asks: what is this branch authorized to override right now? Verifies every
-     * recorded approval and returns the ones that hold, plus a rendered line per one that does not.
-     *
-     * Later approvals win for the same checklist — the human appended it because they meant to say something
-     * newer, and the file is append-only precisely so the earlier one stays readable as history.
-     */
-    verifiedFor(repoRoot, ctx, salt) {
-        const prose = new Map();
-        const rejected = [];
-        const file = this.load(repoRoot, ctx.branch);
-        if (file.unreadable !== '')
-            rejected.push(`(unreadable, treated as NO approvals) — ${file.unreadable}`);
-        for (const approval of file.approvals) {
-            const check = this.verify(ctx, approval, salt);
-            if (check.ok)
-                prose.set(approval.checklist, approval.approves);
-            else
-                rejected.push(`"${approval.checklist}" (issued ${approval.issuedAt}) — ${check.reason}`);
-        }
-        return new AuthorizedOverrides(prose, rejected);
-    }
-    /** An expiry `hours` from `issuedAt`, as ISO — the one place the TTL arithmetic lives. */
-    expiryFrom(issuedAt, hours) {
-        return new Date(issuedAt.getTime() + hours * 3600 * 1000).toISOString();
-    }
-};
-exports.HumanAuthorizationService = HumanAuthorizationService;
-exports.HumanAuthorizationService = HumanAuthorizationService = tslib_1.__decorate([
-    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
-    tslib_1.__metadata("design:paramtypes", [state_dir_1.DotWebpieces])
-], HumanAuthorizationService);
-//# sourceMappingURL=human-authorization.js.map

package/src/human-authorization.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"human-authorization.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/human-authorization.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHmac } from 'crypto';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { DotWebpieces, dotWebpieces } from './state-dir';\nimport { matchesAnyGlob } from './exclude-paths';\nimport { toError } from './to-error';\n\n// The directory under `.webpieces/` that holds one authorization file per branch. Gitignored with the\n// rest of `.webpieces/` — deliberately, see HumanAuthorizationService's docstring.\nexport const AUTHORIZATIONS_DIR = 'authorizations';\n\n// How long a fresh approval is good for, in hours, when the human does not say otherwise. An approval is\n// for TODAY'S work, not a standing grant: the thing being authorized is a specific partial delivery, and\n// a grant that outlives the sitting it was given in is one nobody remembers giving.\nexport const DEFAULT_APPROVAL_HOURS = 4;\n\n// The marker version in the signed payload. An approval signed under a different version does not verify,\n// so the payload can gain a field without a stale entry silently continuing to pass.\nconst PAYLOAD_VERSION = 'wp-authorize-v1';\n\n/**\n * ONE human approval of ONE checklist's override, on ONE branch. Data-only (per CLAUDE.md).\n *\n * `approves` is prose the human typed at the tty in their own words, and it is the POINT of the record:\n * `wp-check-auth` prints it, so a reviewer can judge whether the approval actually covers the thing it is\n * being applied to — not merely that *an* approval exists on this branch.\n *\n * `hmac` is `HMAC-SHA256(prGate.gateSalt, canonical payload)` over every other field plus the branch. It\n * is what makes the approval VERIFIABLE by an agent that cannot MINT one: the agent runs `wp-check-auth`,\n * which recomputes the HMAC, rather than believing a claim relayed to it in a message.\n */\nexport class HumanApproval {\n    checklist: string;    // the checklist id this authorizes an override of (= the reviewer subagent name)\n    gate: string;         // the specific gate inside that checklist, or '' for the checklist as a whole\n    approves: string;     // the human's OWN words: what they are approving and why\n    scopePaths: string[]; // globs the diff touched when approved; the approval dies if it grows past them\n    forkPoint: string;    // merge-base when approved; survives new commits, dies on a re-based branch\n    issuedAt: string;     // ISO\n    expiresAt: string;    // ISO\n    hmac: string;         // '' until signed\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        checklist: string,\n        gate: string,\n        approves: string,\n        scopePaths: string[],\n        forkPoint: string,\n        issuedAt: string,\n        expiresAt: string,\n        hmac = '',\n    ) {\n        this.checklist = checklist;\n        this.gate = gate;\n        this.approves = approves;\n        this.scopePaths = scopePaths;\n        this.forkPoint = forkPoint;\n        this.issuedAt = issuedAt;\n        this.expiresAt = expiresAt;\n        this.hmac = hmac;\n    }\n}\n\n/**\n * The append-only authorization file for ONE branch: N approvals, each naming what it approves. Data-only.\n *\n * The unit is the BRANCH, not the gate, because one run of work routinely needs more than one override and\n * they arrive at different times. One file per gate would mean the human re-answering the same \"where does\n * this go?\" question on every approval.\n */\nexport class AuthorizationFile {\n    branch: string;\n    approvals: HumanApproval[];\n    /**\n     * '' when the file was absent or read cleanly. Non-empty = it EXISTS but could not be parsed, and the\n     * reason.\n     *\n     * Carried rather than swallowed because \"no approvals\" and \"approvals I could not read\" are different\n     * facts and the second one is actionable: a corrupt file means the human's approval is sitting on disk\n     * unreadable, and the fix is to re-authorize rather than to wonder why nothing was found. `verifiedFor`\n     * turns this into a `rejected` line, which `wp-check-auth` already prints.\n     */\n    unreadable: string;\n\n    constructor(branch = '', approvals: HumanApproval[] = [], unreadable = '') {\n        this.branch = branch;\n        this.approvals = approvals;\n        this.unreadable = unreadable;\n    }\n}\n\n/**\n * The git facts an approval is verified AGAINST, gathered once by the caller. Data-only.\n *\n * A data class rather than four parameters because the four must describe ONE branch state: a `forkPoint`\n * resolved from one tree checked against a `changedFiles` gathered from another is a verification that\n * means nothing, and separate parameters are how that happens.\n */\nexport class AuthorizationContext {\n    branch: string;\n    forkPoint: string;\n    changedFiles: string[];\n    now: Date;\n\n    constructor(branch: string, forkPoint: string, changedFiles: string[] = [], now: Date = new Date()) {\n        this.branch = branch;\n        this.forkPoint = forkPoint;\n        this.changedFiles = changedFiles;\n        this.now = now;\n    }\n}\n\n/**\n * The verdict on ONE approval. `ok` false ⇒ `reason` says WHICH of the four bindings failed, in the\n * human's terms, because that is the sentence the agent has to relay back to them. Data-only.\n */\nexport class AuthorizationCheck {\n    ok: boolean;\n    reason: string;               // '' when ok\n    approval: HumanApproval | null;\n\n    constructor(ok: boolean, reason: string, approval: HumanApproval | null) {\n        this.ok = ok;\n        this.reason = reason;\n        this.approval = approval;\n    }\n}\n\n/**\n * What a branch is actually authorized to override RIGHT NOW: checklist id → the human's `approves` prose.\n * Data-only, with accessors so every consumer asks the question one way.\n *\n * `rejected` carries the approvals that were found but did NOT verify, one rendered line each. They are\n * kept rather than dropped because \"there is an approval on this branch, and here is why it no longer\n * counts\" is a completely different message from \"nobody has authorized anything\" — the first needs a\n * re-authorization, the second needs a human at all — and an empty map cannot tell them apart.\n */\nexport class AuthorizedOverrides {\n    proseById: Map<string, string>;\n    rejected: string[];\n\n    constructor(proseById: Map<string, string> = new Map<string, string>(), rejected: string[] = []) {\n        this.proseById = proseById;\n        this.rejected = rejected;\n    }\n\n    has(checklistId: string): boolean {\n        return this.proseById.has(checklistId);\n    }\n\n    /** The human's own words for `checklistId`, or '' when it is not authorized. */\n    proseFor(checklistId: string): string {\n        return this.proseById.get(checklistId) ?? '';\n    }\n}\n\n/**\n * Mints (for a HUMAN at a tty) and verifies (for ANYONE, agents included) the human-authorization records\n * that are the ONLY channel by which a review checklist's override may be granted.\n *\n * ─── The problem ───────────────────────────────────────────────────────────────────────────────────────\n * A required checklist goes red, the human authorizes the partial scope, and there is NO channel by which\n * the subagent doing the work can know that. Every channel available before this carried a CLAIM of\n * authorization and never EVIDENCE of it: a coordinator relaying the human's words is unverifiable by\n * construction (and correctly refused — that refusal is the shape a prompt injection exploits); a ticket\n * comment can be written by an agent holding the same MCP; and the `override` field in review-<id>.json is\n * the agent authorizing itself.\n *\n * So the property this class buys is exactly one sentence: **an agent can VERIFY an authorization it\n * cannot MINT.** `wp-authorize` reads the approval from `/dev/tty`, which an agent's Bash tool has no way\n * to answer; `wp-check-auth` recomputes the HMAC and is read-only, so agents run it freely.\n *\n * ─── Bound to SCOPE, never to a diff sha ───────────────────────────────────────────────────────────────\n * An approval bound to the head-commit diff would be void on the next commit, so the human would\n * re-authorize on every push and nobody would use it. Each approval binds to WHAT WAS APPROVED instead:\n *   • `scopePaths` — the globs the diff touched when approved. A \"terraform only\" approval is void the\n *     moment app files appear, which is the abuse actually worth stopping.\n *   • `forkPoint`  — the merge-base when approved. Survives new commits; dies if the branch is restarted.\n *   • `expiresAt`  — hours, not days.\n * Edits inside the approved scope keep working; widening it does not. That is what the human means when\n * they say \"yes, ship the terraform half\".\n *\n * ─── Where the file lives, and why it is SHARED rather than per-worktree ───────────────────────────────\n * `dotWebpieces.shared()/authorizations/<branch-slug>.json`, keyed by BRANCH. Not `local()`: the human\n * routinely types `wp-authorize` in the primary clone while the agent works in a linked worktree, and\n * under `local()` those are two different files — the approval would be minted somewhere the agent never\n * looks, which is the same stall this feature exists to end. The branch key is what makes sharing safe:\n * an approval names its branch inside the SIGNED payload, so a file copied to another branch does not\n * verify there.\n *\n * It is never committed (`.webpieces/` is gitignored in full). A committed authorization would travel to\n * branches nobody approved.\n *\n * ─── Honest limits — do not oversell this ─────────────────────────────────────────────────────────────\n * The agent runs as the SAME OS USER as the human, and the HMAC key is `prGate.gateSalt`, which lives in a\n * committed file agents read routinely. Nothing here is cryptographically airtight against a determined\n * model; the real enforcement is the tty affordance plus the harness deny rule. That is fine, because the\n * problem being solved is agents drifting, guessing, or being confused by relays — not an adversarial\n * model. Moving the key to `~/.webpieces/authorize.key` is a one-line change to `sign()` if the threat\n * model ever changes; nothing else in the design moves.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class HumanAuthorizationService {\n    constructor(private readonly dotDir: DotWebpieces = dotWebpieces) {}\n\n    /** The repo-wide authorizations directory. See the class docstring for why `shared()` and not `local()`. */\n    dirFor(repoRoot: string): string {\n        return this.dotDir.sharedFile(repoRoot, AUTHORIZATIONS_DIR);\n    }\n\n    /**\n     * A filesystem-safe leaf for a branch name. Slashes and anything exotic collapse to `-`, so\n     * `dean/one-2779-grants` becomes `dean-one-2779-grants`.\n     *\n     * A collision between two slugs is harmless: the branch is inside the SIGNED payload, so an approval\n     * that landed in a colliding file fails `verify` on the branch check rather than leaking across.\n     */\n    slugFor(branch: string): string {\n        return branch.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');\n    }\n\n    pathFor(repoRoot: string, branch: string): string {\n        return path.join(this.dirFor(repoRoot), `${this.slugFor(branch)}.json`);\n    }\n\n    /**\n     * The exact bytes that get signed: a version tag, the branch, and every field of the approval EXCEPT\n     * the hmac, in a fixed order with `scopePaths` sorted.\n     *\n     * Fixed order and sorting are load-bearing — `JSON.stringify` over a re-parsed object preserves\n     * insertion order, so a round-tripped approval whose keys arrived in a different order would compute a\n     * different payload and fail to verify a signature that is perfectly good.\n     */\n    canonicalPayload(branch: string, approval: HumanApproval): string {\n        return [\n            PAYLOAD_VERSION,\n            branch,\n            approval.checklist,\n            approval.gate,\n            approval.approves,\n            [...approval.scopePaths].sort().join(','),\n            approval.forkPoint,\n            approval.issuedAt,\n            approval.expiresAt,\n        ].join('\\n');\n    }\n\n    /** `HMAC-SHA256(salt, canonical payload)`. '' for an empty salt — the caller treats '' as \"not configured\". */\n    sign(branch: string, approval: HumanApproval, salt: string): string {\n        if (salt.trim() === '') return '';\n        return createHmac('sha256', salt).update(this.canonicalPayload(branch, approval)).digest('hex');\n    }\n\n    /** The same approval, carrying its signature. Never mutates the input. */\n    signed(branch: string, approval: HumanApproval, salt: string): HumanApproval {\n        return new HumanApproval(\n            approval.checklist, approval.gate, approval.approves, approval.scopePaths,\n            approval.forkPoint, approval.issuedAt, approval.expiresAt,\n            this.sign(branch, approval, salt),\n        );\n    }\n\n    /**\n     * Every approval recorded for `branch`, signature UNCHECKED. An absent or unreadable file is an EMPTY\n     * file, never a throw: a corrupt authorization must degrade to \"nothing is authorized\", which is the\n     * safe direction, and a branch that cannot open its own authorization file must still be able to run\n     * the gate and be told to go get one.\n     */\n    load(repoRoot: string, branch: string): AuthorizationFile {\n        const p = this.pathFor(repoRoot, branch);\n        if (!fs.existsSync(p)) return new AuthorizationFile(branch);\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: unreadable authorizations mean \"none\", never a crash\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- parsed JSON is opaque until each field is narrowed below\n            const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as Record<string, unknown>;\n            const list = Array.isArray(raw['approvals']) ? (raw['approvals'] as unknown[]) : [];\n            return new AuthorizationFile(branch, list.map((e: unknown): HumanApproval => this.toApproval(e)));\n        } catch (err: unknown) {\n            const error = toError(err);\n            // Fail CLOSED on the grant, but say so: nothing is authorized either way, and reporting WHY is\n            // the difference between \"ask the human to authorize\" and \"ask the human to authorize AGAIN\n            // because their last one is unreadable on disk\".\n            return new AuthorizationFile(branch, [], `${p} exists but could not be read (${error.message})`);\n        }\n    }\n\n    // One parsed entry. Every field is read defensively — a hand-edited file is exactly the input this must\n    // survive, and a missing field simply yields '' / [], which then fails the signature check.\n    // webpieces-disable no-any-unknown -- opaque parsed JSON entry; each field is narrowed here\n    private toApproval(entry: unknown): HumanApproval {\n        const raw = (typeof entry === 'object' && entry !== null ? entry : {}) as Record<string, unknown>;\n        return new HumanApproval(\n            this.str(raw['checklist']), this.str(raw['gate']), this.str(raw['approves']),\n            this.strList(raw['scopePaths']), this.str(raw['forkPoint']),\n            this.str(raw['issuedAt']), this.str(raw['expiresAt']), this.str(raw['hmac']),\n        );\n    }\n\n    // webpieces-disable no-any-unknown -- reading ONE opaque field out of hand-editable JSON; narrowed right here\n    private str(value: unknown): string {\n        return typeof value === 'string' ? value : '';\n    }\n\n    // webpieces-disable no-any-unknown -- reading ONE opaque field out of hand-editable JSON; narrowed right here\n    private strList(value: unknown): string[] {\n        if (!Array.isArray(value)) return [];\n        // webpieces-disable no-any-unknown -- element of an opaque JSON array, narrowed by the type guard\n        return value.filter((v: unknown): v is string => typeof v === 'string');\n    }\n\n    /**\n     * APPEND one signed approval to the branch's file and return the path written. Append, never replace:\n     * a run of work needs several overrides at different times, and each one is its own record of intent.\n     */\n    append(repoRoot: string, branch: string, approval: HumanApproval, salt: string): string {\n        const file = this.load(repoRoot, branch);\n        file.approvals.push(this.signed(branch, approval, salt));\n        const p = this.pathFor(repoRoot, branch);\n        fs.mkdirSync(path.dirname(p), { recursive: true });\n        fs.writeFileSync(p, JSON.stringify(new AuthorizationFile(branch, file.approvals), null, 2) + '\\n');\n        return p;\n    }\n\n    /**\n     * Verify ONE approval against the branch state, in the order a reader wants to hear it: signature,\n     * expiry, fork point, scope. Signature first — an unsigned entry's other fields are not evidence of\n     * anything, and reporting \"expired\" for a forged record would be answering the wrong question.\n     */\n    verify(ctx: AuthorizationContext, approval: HumanApproval, salt: string): AuthorizationCheck {\n        const expected = this.sign(ctx.branch, approval, salt);\n        if (expected === '' || approval.hmac !== expected) {\n            return this.fail(approval, 'its signature does not verify — it was hand-written, edited after '\n                + 'signing, minted on a different branch, or the repo\\'s prGate.gateSalt changed');\n        }\n        if (this.expired(approval, ctx.now)) {\n            return this.fail(approval, `it EXPIRED at ${approval.expiresAt} (an approval is for the sitting it was given in)`);\n        }\n        if (approval.forkPoint !== '' && ctx.forkPoint !== '' && approval.forkPoint !== ctx.forkPoint) {\n            return this.fail(approval, `the branch was restarted from a different base — approved at fork point `\n                + `${approval.forkPoint.slice(0, 12)}, now ${ctx.forkPoint.slice(0, 12)}`);\n        }\n        const outside = this.outsideScope(approval, ctx.changedFiles);\n        if (outside.length > 0) {\n            return this.fail(approval, `the diff now touches ${outside.length} file(s) OUTSIDE the approved scope `\n                + `(${approval.scopePaths.join(', ')}): ${outside.slice(0, 5).join(', ')}`);\n        }\n        return new AuthorizationCheck(true, '', approval);\n    }\n\n    private fail(approval: HumanApproval, reason: string): AuthorizationCheck {\n        return new AuthorizationCheck(false, reason, approval);\n    }\n\n    // An approval with no parseable `expiresAt` is treated as EXPIRED. Failing closed is the only safe\n    // reading: a missing expiry on a record whose whole purpose is to be time-bounded is a broken record,\n    // and the alternative reading is a grant that never ends.\n    private expired(approval: HumanApproval, now: Date): boolean {\n        const at = Date.parse(approval.expiresAt);\n        if (Number.isNaN(at)) return true;\n        return at <= now.getTime();\n    }\n\n    /**\n     * The changed files NOT covered by `scopePaths`. An approval with an EMPTY `scopePaths` covers nothing\n     * and is therefore always out of scope when anything changed — `wp-authorize` never mints one, and the\n     * alternative reading (\"empty means everything\") is precisely the widening-by-absence that makes the\n     * permissive path the shortest thing to type.\n     */\n    private outsideScope(approval: HumanApproval, changedFiles: readonly string[]): string[] {\n        return changedFiles.filter((f: string): boolean => !matchesAnyGlob(f, approval.scopePaths));\n    }\n\n    /**\n     * THE question every consumer asks: what is this branch authorized to override right now? Verifies every\n     * recorded approval and returns the ones that hold, plus a rendered line per one that does not.\n     *\n     * Later approvals win for the same checklist — the human appended it because they meant to say something\n     * newer, and the file is append-only precisely so the earlier one stays readable as history.\n     */\n    verifiedFor(repoRoot: string, ctx: AuthorizationContext, salt: string): AuthorizedOverrides {\n        const prose = new Map<string, string>();\n        const rejected: string[] = [];\n        const file = this.load(repoRoot, ctx.branch);\n        if (file.unreadable !== '') rejected.push(`(unreadable, treated as NO approvals) — ${file.unreadable}`);\n        for (const approval of file.approvals) {\n            const check = this.verify(ctx, approval, salt);\n            if (check.ok) prose.set(approval.checklist, approval.approves);\n            else rejected.push(`\"${approval.checklist}\" (issued ${approval.issuedAt}) — ${check.reason}`);\n        }\n        return new AuthorizedOverrides(prose, rejected);\n    }\n\n    /** An expiry `hours` from `issuedAt`, as ISO — the one place the TTL arithmetic lives. */\n    expiryFrom(issuedAt: Date, hours: number): string {\n        return new Date(issuedAt.getTime() + hours * 3600 * 1000).toISOString();\n    }\n}\n"]}