@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/policy-packs/builtin/solution-acceptance-runtime.d.ts

@@ -1,323 +0,0 @@
-import { type SignatureVerification } from "../../runtime/approval-signing.js";
-import type { PolicyPack } from "../../schema/index.js";
-export declare const PACK_NAME = "solution-acceptance";
-/**
- * agent-tasks MCP verbs that mark a completion boundary. The gate fires on
- * these (matched by exact tool name `mcp__agent-tasks__<verb>`). These MCP
- * choke points are reliable: unlike the bash matcher they cannot be evaded
- * by shell indirection.
- */
-export declare const DEFAULT_PROTECTED_COMPLETION_TOOLS: readonly ["task_finish", "task_submit_pr", "task_merge", "pull_requests_merge"];
-/**
- * Belt-and-suspenders bash matcher for `git push` / `gh pr merge`. Regex on
- * the typed command, so an env-var indirection
- * (`B=main && git push origin $B`) evades it — the MCP verbs above are the
- * load-bearing choke points; hardening this is follow-up `7207d8f9`.
- * Tolerates a leading `cd … &&`, inline `VAR=val` assignments, and `git -C
- * <path> push`.
- *
- * Task 76671e5a: bare `&` added to the boundary alternation (`&&` kept to
- * its left only to mirror `src/runtime/command-normalize.ts`'s alternation
- * order for readability — NOT because order is load-bearing here, unlike
- * that module). Same fix as `d834a065` applied to every policy trigger —
- * bash starts a new command after a single `&`, so `A=x&git push` used to
- * slip past this DENY matcher entirely. Broadening is the stricter direction
- * here (this gates completion actions, it is not an allow-list). Measured:
- * swapping to `&|&&` produces a byte-identical match set for this matcher
- * (a `RegExp.test` existential check over every start offset, not a
- * segmenter — the reasoning that makes order matter in
- * `command-normalize.ts`'s `BOUNDARY_RE`/`AMP_BOUNDARY_RE` does not transfer
- * to a plain `.test()` matcher like this one).
- */
-export declare const DEFAULT_PUSH_BASH_RE: RegExp;
-/**
- * Resolve the completion verbs the gate fires on: the pack's
- * `config.protected_completion_tools` override, else the default set.
- * Always non-empty. Lives here (not in the pack module) so the
- * completion-gate hook can share it without importing the pack's zod
- * surface (mirrors `resolveProtectedBranches` in branch-protection-runtime).
- */
-export declare function resolveProtectedCompletionTools(pack: PolicyPack): string[];
-/**
- * The verdict marker the producer writes. Keep field-for-field with
- * grounding-mcp for the first 7 keys (golden-fixture-pinned below).
- *
- * `alg` / `signature` (harness/c7c3f606) are ADDITIVE and OPTIONAL: a
- * legacy / not-yet-updated producer omits them entirely (parsed as
- * `undefined`, never `null` — mirrors how `ApprovalMarker.reportContentHash`
- * distinguishes "absent" from an explicit empty value), and such a verdict
- * is REJECTED by `evaluateGate` (missing signature = forged/unsigned, fail
- * closed) rather than silently accepted. See the module doc for the
- * consumer-only / cross-repo-follow-up honesty.
- */
-export interface Verdict {
-    id: string;
-    head: string;
-    ready: boolean;
-    confidence: number;
-    blockers: string[];
-    timestamp: string;
-    source: string;
-    /** Signature algorithm tag; only `SIGNING_ALG` (`src/runtime/approval-signing.ts`) verifies. */
-    alg?: string;
-    /** HMAC-SHA256 hex signature over the canonical identifying tuple (see `verifyVerdictSignature`). */
-    signature?: string;
-}
-/**
- * Marker-id namespace the verdict's HMAC signature is bound to (mirrors
- * `BRANCH_PROTECTION_MARKER_PREFIX` in branch-protection-runtime.ts): a
- * validly-signed verdict for one id can never be replayed as a validly-
- * signed verdict — or a validly-signed understanding-gate / branch-
- * protection marker — for a different id, because `markerId` is bound into
- * the signed payload (`approval-signing.ts` `canonicalPayload`) and this
- * prefix keeps the three id spaces disjoint even where the raw ids
- * (task ids, session ids) could otherwise collide.
- */
-export declare const VERDICT_MARKER_ID_PREFIX = "solution-verdict-";
-/** The HMAC markerId for verdict `id` (NOT a filesystem path — see `verdictPathFor` for that). */
-export declare function verdictMarkerId(id: string): string;
-/**
- * Sign `verdict`, reusing `signMarker` (`src/runtime/approval-signing.ts`)
- * unmodified — same crypto as the understanding-gate / branch-protection
- * markers (harness/f9485cc7). Payload mapping mirrors the approval
- * marker's shape (`approvedAt`/`approvedBy`/`reportContentHash`) onto the
- * verdict's own fields:
- *   - `approvedAt` <- `verdict.timestamp` (when the attestation was made)
- *   - `approvedBy` <- `verdict.source` (what attests it, e.g. "preflight")
- *   - `reportContentHash` <- `verdictContentHash(verdict)` (binds
- *     head/ready/confidence/blockers, the fields signMarker's fixed shape
- *     has no dedicated slot for)
- *
- * NOT wired to any production write path in harness (harness is a pure
- * CONSUMER of this marker, see module doc) — exported as the pattern +
- * exemplar a grounding-mcp-side producer change reuses, and used directly
- * by this module's own tests to construct validly-signed fixtures.
- *
- * Load-bearing on the producer side: `signMarker` is called with
- * `verdictMarkerId(verdict.id)`, while the consumer (`verifyVerdictSignature`
- * below) verifies with `verdictMarkerId(id)` where `id` is the CALLER's id,
- * not `verdict.id`. Those two only agree when a mirroring producer sets
- * `verdict.id` to the EXACT id string the consumer looks the marker up by —
- * byte-identical, no trimming or case normalization on either side — and the
- * consumer additionally rejects outright when `verdict.id !== id` even if
- * the signature itself still verifies (belt-and-braces, see `evaluateGate`).
- */
-export declare function signVerdict(generatedDir: string, verdict: Verdict): Verdict;
-/**
- * Verify `verdict`'s signature, reusing `verifyMarkerSignature` unmodified.
- * Recomputes `verdictContentHash` from the (possibly tampered) verdict
- * being checked — the SAME name-mapping `signVerdict` uses — so any
- * post-signing edit to `head` / `ready` / `confidence` / `blockers` /
- * `timestamp` / `source` fails verification, not just an edit to
- * `signature` itself.
- *
- * `id` is the CALLER's id — the one `evaluateGate` is actually checking
- * (`readVerdict`'s lookup key) — NOT `verdict.id` (a field read back out of
- * the marker BODY, which is exactly the bytes an attacker controls when
- * copying a validly-signed marker verbatim onto a different id's path).
- * This mirrors the load-bearing invariant `approval-signing.ts`'s
- * `signMarker` doc states explicitly: "verification always recomputes the
- * HMAC using the id the caller is checking, NOT one read back out of the
- * marker body." Trusting `verdict.id` here would let a byte-for-byte copy
- * of one id's signed verdict pass verification under a DIFFERENT id's
- * request, because the copy's `signature` and its own (also-copied)
- * `verdict.id` field would always agree with each other regardless of which
- * id actually asked.
- */
-export declare function verifyVerdictSignature(generatedDir: string, id: string, verdict: Verdict): SignatureVerification;
-/** Env knob that overrides the verdict directory (mirrors the producer). */
-export declare const VERDICT_DIR_ENV = "SOLUTION_VERDICT_DIR";
-/**
- * Env knob that supplies the verdict id for SOLO / non-agent-tasks sessions.
- * The completion-gate consults it ONLY when no agent-tasks `active-claim` is
- * recorded (resolution order: active-claim first, then this env, then
- * fail-closed), so a claimed session's id stays authoritative and cannot be
- * redirected by an env var. A sessionId fallback is intentionally still NOT a
- * source (the wrong-scope bug class understanding-gate closed).
- */
-export declare const VERDICT_ID_ENV = "SOLUTION_VERDICT_ID";
-/**
- * Stable tail of the default verdict dir. The write-guard's reference
- * detection matches on this so ANY spelling of the home prefix is caught
- * (`~/.local/state/...`, `$HOME/...`, `$XDG_STATE_HOME/...`, the literal
- * absolute path).
- */
-export declare const VERDICT_DIR_TAIL: string;
-/**
- * Resolve the verdict directory. Resolution order MUST match grounding-mcp's
- * `verdictDir()` so the consumer reads exactly where the producer writes
- * (operator decision B: both sides use the producer default; no apply-time
- * env threading, no divergence risk):
- *   1. SOLUTION_VERDICT_DIR
- *   2. $XDG_STATE_HOME/agent-grounding/solution-verdicts
- *   3. ~/.local/state/agent-grounding/solution-verdicts
- */
-export declare function verdictDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
-/**
- * Reduce a verdict id to a single safe path segment. Mirrors the producer's
- * `sanitizeVerdictId`: non-portable chars collapse to `_`, `path.basename`
- * strips any residual separator (path-traversal guard), empty / dot-only ids
- * are rejected.
- */
-export declare function sanitizeVerdictId(id: string): string;
-export declare function verdictPathFor(dir: string, id: string): string;
-/**
- * Resolve the explicit verdict id from `SOLUTION_VERDICT_ID`, or null when it
- * is unset, blank, or not a safe single path segment. Validated through
- * `sanitizeVerdictId` so a traversal-y or empty value fails closed here
- * (returns null -> the gate denies) rather than reaching the marker read. This
- * is the solo / non-agent-tasks fallback the completion-gate uses only when no
- * active-claim is present.
- */
-export declare function resolveExplicitVerdictId(env?: NodeJS.ProcessEnv): string | null;
-/**
- * WHY the verdict marker for an id yielded no verdict, as ONE observation.
- * `readVerdict` below answers `null` for every non-`ok` kind, which is all
- * the gate DECISION needs; the deny TEXT needs to say which one, and must
- * not learn it from a second look at the path. A second look can disagree
- * with the first (a background attempt finishing in between is exactly the
- * case this pack exists for), and a note rendered from the later one then
- * describes a rejection the gate never made: it would tell the agent its
- * fresh marker was refused when the gate had simply not seen it yet
- * (review finding, harness/799de976, round 6). Both consumers therefore
- * read through this one function.
- */
-export type VerdictReadOutcome = {
-    kind: "ok";
-    verdict: Verdict;
-} | {
-    kind: "invalid-id";
-} | {
-    kind: "missing";
-} | {
-    kind: "symlink";
-} | {
-    kind: "not-regular";
-} | {
-    kind: "unreadable";
-} | {
-    kind: "invalid-record";
-};
-/**
- * Read + validate the verdict marker for `id` in ONE filesystem
- * observation, reporting the outcome instead of collapsing it. The
- * symlink-rejecting read is the shared `src/io/read-regular-file.ts`
- * helper (same defense-in-depth as `checkApprovalMarker` against a symlink
- * planted at the marker path pointing at agent-controlled content), and
- * its four non-ok kinds pass straight through, so this outcome set cannot
- * drift from the reader's own. `invalid-record` is the one kind added on
- * top: a regular file that WAS read but is not a verdict (unparseable
- * JSON, or JSON missing one of the three required fields).
- */
-export declare function readVerdictDetailed(dir: string, id: string): VerdictReadOutcome;
-/**
- * Read + validate the verdict marker for `id`, or null when it is absent,
- * unparseable, a symlink, or not a regular file: `readVerdictDetailed`
- * above with the reason dropped. The completion-gate hook reads through
- * `readVerdictDetailed` (it needs the reason), so this null-collapsing form
- * has no production caller today; it stays as the exported form for a
- * caller that only needs the verdict, and its collapse is unit-tested.
- */
-export declare function readVerdict(dir: string, id: string): Verdict | null;
-export interface GateResult {
-    allowed: boolean;
-    reason: string;
-    verdict: Verdict | null;
-    /**
-     * True when `allowed` is false SPECIFICALLY because a verdict file
-     * existed and parsed (the 7 producer keys), but carried a missing or
-     * invalid HMAC signature (harness/c7c3f606), or a body that identifies a
-     * different id than the one being checked (cross-id replay, see the
-     * `verdict.id !== id` check below) — a legacy/not-yet-signing producer, a
-     * marker planted through some write primitive the write-guard doesn't
-     * enumerate, or content tampered/copied post-signing. Distinct from
-     * `verdict === null` (no marker at all, `forged: false`), from a
-     * signing-key I/O failure (fail-closed but NOT classified as forged,
-     * mirroring `SignatureVerification`'s `kind: "key-unavailable"` — a
-     * broken key file must not read as an active forgery attempt in audit
-     * output), and from a verdict with NO `alg`/`signature` fields at all
-     * whose `timestamp` / `source` also reads blank (fail-closed but NOT
-     * classified as forged either — a legitimately malformed, never-signed
-     * marker, not evidence of an attack; see the `MISSING_*_REASON` carve-out
-     * below). That last carve-out is scoped tightly: a verdict that DOES carry
-     * `alg`/`signature` but still hits the same blank-field reason IS
-     * classified `forged: true` — a signed field reading blank only happens
-     * via post-signing tampering, so it does not get the "legitimately
-     * malformed" benefit of the doubt (review R2, closes an audit-fidelity
-     * gap where a forger could blank a real signed verdict's `timestamp` to
-     * suppress this tag while the block itself still held). `allowed` is
-     * always false when `forged` is true.
-     */
-    forged: boolean;
-}
-/**
- * Evaluate the gate for `id` at `currentHead`. First verifies the verdict's
- * HMAC signature (harness/c7c3f606, fail-closed — see `verifyVerdictSignature`);
- * a verdict that fails this is REJECTED before its `ready` / `head` fields
- * are ever trusted, with a distinct forged/unsigned reason so an
- * operator/auditor can tell that apart from the routine "not ready yet" or
- * "no verdict" cases. Signature verification needs `generatedDir` (the
- * harness `.generated/` dir holding the shared signing key, NOT the verdict
- * dir) — `undefined` when it could not be resolved, which fails closed with
- * its own distinct (non-forged) reason.
- *
- * `verifyVerdictSignature` is called with `id` — the CALLER's id, i.e. the
- * one this function is asked to check — not `verdict.id`. A SECOND,
- * belt-and-braces check below independently rejects `verdict.id !== id`:
- * even though the signature check alone already closes the cross-id-replay
- * hole (a byte-for-byte copy of a validly-signed verdict onto a different
- * id's path fails signature verification, because the markerId the
- * signature is bound to no longer matches `id`), the verdict body's `id`
- * field itself is NOT part of the signed payload (only `timestamp` /
- * `source` / the head-ready-confidence-blockers content hash are), so it
- * can drift from the id that was actually verified without invalidating an
- * otherwise-valid signature. This check makes that drift fail loudly too,
- * rather than silently ignoring an inconsistency in the body of a verdict
- * that otherwise passed.
- *
- * Once signed and identity-checked, mirrors grounding-mcp `evaluateGate`:
- * allow iff `verdict.ready === true` AND `verdict.head === currentHead`.
- * `confidence` is INFORMATIONAL ONLY and never gates — a `ready:true
- * confidence:0` verdict at HEAD passes — so the harness consumer stays
- * byte-parity with the producer's `solution_gate` for THAT decision.
- * Signature verification itself is NOT (yet) mirrored on the producer side
- * — see module doc, "HONEST RESIDUAL": grounding-mcp's own `solution_gate`
- * does not enforce this signature, only this harness consumer does, until a
- * matching producer release ships.
- */
-export declare function evaluateGate(verdict: Verdict | null, currentHead: string | null, id: string, generatedDir: string | undefined): GateResult;
-/**
- * Is `target` inside `dir` after resolution? Used for the path-tool arm
- * (Write/Edit/MultiEdit/NotebookEdit `file_path`) and for a Bash shell whose
- * cwd is the protected dir. A relative `target` resolves against `cwd`
- * (falling back to process.cwd()).
- */
-export declare function isInsideDir(target: string, dir: string, cwd?: string): boolean;
-/**
- * Does a Bash command TEXTUALLY reference the verdict dir? Catches the
- * enumerated spellings without shell-evaluating (same contract as
- * read-only-bash):
- *   - the literal absolute dir,
- *   - the `$SOLUTION_VERDICT_DIR` env token,
- *   - the stable tail `agent-grounding/solution-verdicts` (covers `~/...`,
- *     `$HOME/...`, `$XDG_STATE_HOME/...`, and absolute spellings), and
- *   - the dir's LEAF segment (`solution-verdicts` for the default).
- *
- * The leaf segment closes the `cd <parent> && write <relative-into-dir>`
- * descent (where the parent path and the child redirect never form the
- * contiguous tail): ANY relative write into the dir from a cwd that is not
- * the dir itself must name the leaf somewhere in the command, and a
- * `cd <…/leaf>` to first make cwd==dir would itself contain the leaf. The
- * write-guard's cwd-inside check covers the only remaining case (cwd already
- * inside the dir). The leaf needle is length-guarded so a short custom
- * basename does not over-block; the default leaf is distinctive, and a
- * non-default dir already warns at validate time.
- *
- * `chmod`/`chattr` that target the dir are caught the same way, so the
- * FS-perm-loosening attack is covered.
- *
- * Honest residual: a path constructed at runtime inside an interpreter with
- * no textual reference (e.g. base64-decoded inside `python3 -c`) is NOT
- * caught. That is what marker signing (follow-up) closes.
- */
-export declare function bashReferencesVerdictDir(command: string, dir: string): boolean;