@lannguyensi/harness 0.44.0 → 0.46.0

package/dist/policy-packs/builtin/understanding-before-execution/markers.js

@@ -0,0 +1,203 @@
+// Session-scoped approval marker file (filesystem source of the
+// two-source approval check), split out of the former monolithic
+// understanding-before-execution-runtime.ts (structural concentration
+// slice 2, agent-tasks 348a4d42). Pure move: see
+// src/policy-packs/builtin/understanding-before-execution/index.ts for
+// the re-exported public surface.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../../io/atomic-write.js";
+import { readRegularFileRejectingSymlink } from "../../../io/read-regular-file.js";
+import { signMarker, verifyMarkerSignature } from "../../../runtime/approval-signing.js";
+import { rejectMalformedSessionId } from "../../../runtime/reject-malformed-session-id.js";
+import { safeJsonParse } from "./persisted-reports.js";
+export const APPROVAL_MARKER_DIRNAME = ".approvals";
+/** Filesystem path of the per-session approval marker. */
+export function approvalMarkerPathFor(generatedDir, sessionId) {
+    rejectMalformedSessionId(sessionId);
+    return path.join(generatedDir, APPROVAL_MARKER_DIRNAME, sessionId);
+}
+/**
+ * Operator-side: write the marker file the gate consults. Atomic so a
+ * crash mid-write cannot leave a half-empty file the gate would accept
+ * as approved. Caller is `harness approve understanding`, which the
+ * operator runs from their un-hooked shell; if the agent could call
+ * this path the gate's value would collapse, so it lives behind the
+ * approve CLI rather than as a generally importable verb.
+ *
+ * The marker is HMAC-signed (harness/f9485cc7) over (sessionId,
+ * approvedAt, approvedBy, reportContentHash) using an operator-side key
+ * lazily generated at `<generatedDir>/.approval-signing.key` — see
+ * `src/runtime/approval-signing.ts` for the key-management contract and
+ * the honest trust model. Mode 0600 on the marker file itself, best-
+ * effort (matches the signing key's own permission convention); this is
+ * defense-in-depth alongside the signature, not a substitute for it.
+ */
+export function writeApprovalMarker(generatedDir, sessionId, marker) {
+    const filePath = approvalMarkerPathFor(generatedDir, sessionId);
+    const signed = signMarker(generatedDir, sessionId, marker);
+    atomicWriteFile(filePath, `${JSON.stringify(signed, null, 2)}\n`, { mode: 0o600 });
+    return filePath;
+}
+/**
+ * Gate-side: is the per-session marker file present, readable, AND
+ * validly signed? (harness/f9485cc7 — this replaced the earlier
+ * "existence is enough" contract: a marker's mere presence used to
+ * satisfy the gate even with a malformed or corrupted body, on the
+ * theory that Edit/Write/Bash being gated meant only the operator could
+ * ever create the file. That theory holds only as long as no OTHER
+ * write primitive reaches `harness.generated/` — exactly the invariant
+ * this signing scheme no longer has to trust blindly.) A marker with no
+ * `signature`, a wrong `alg`, or a signature that fails to verify is
+ * REJECTED — see `MarkerCheck.forged` — with the SAME `matched: false`
+ * outcome as no marker at all, but a distinct, forgery-specific detail
+ * string so callers can tell the two apart for audit.
+ *
+ * `opts.maxAgeMs` (agent-tasks/d8ee60ca): when set, a validly-signed
+ * marker whose `approvedAt` is older than the cutoff returns
+ * `matched:false` with an "expired" detail so the agent gets the same
+ * "no approval" UX as a never-approved session and must re-approve.
+ * Expiry is only evaluated AFTER signature verification succeeds — an
+ * unsigned/forged marker is rejected outright, never "expired".
+ */
+export function checkApprovalMarker(generatedDir, sessionId, opts = {}) {
+    // Construct the path defensively: a malformed sessionId must fail CLOSED
+    // here (no valid marker, so the gate blocks and demands approval), not
+    // throw out of the gate hook, which the top-level handler turns into a
+    // non-blocking exit that would let the gated tool proceed.
+    let filePath;
+    try {
+        filePath = approvalMarkerPathFor(generatedDir, sessionId);
+    }
+    catch (err) {
+        return {
+            matched: false,
+            detail: `invalid sessionId for approval marker: ${err instanceof Error ? err.message : String(err)}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    // Shared symlink-rejecting read (src/io/read-regular-file.ts): the lstat
+    // reject is defense-in-depth against a planted symlink
+    // (agent-tasks/d39f160e); each failure mode keeps its distinct detail.
+    const read = readRegularFileRejectingSymlink(filePath);
+    if (read.kind === "missing") {
+        return {
+            matched: false,
+            detail: `no approval marker at ${filePath}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    if (read.kind === "symlink") {
+        return {
+            matched: false,
+            detail: `approval marker is a symlink, refusing for safety: ${filePath}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    if (read.kind === "not-regular") {
+        return {
+            matched: false,
+            detail: `approval marker path is not a regular file: ${filePath}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    if (read.kind === "unreadable") {
+        // A genuine I/O error reading an existing regular file (permissions
+        // changed mid-flight, etc.) — not evidence of tampering, but its
+        // signature cannot be proven either, so fail closed. Kept distinct
+        // from `forged` (no claim of an active forgery attempt).
+        return {
+            matched: false,
+            detail: `approval marker at ${filePath} exists but could not be read (I/O error); treating as unapproved since its signature cannot be verified`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    // read.kind === "ok"
+    const parsed = safeJsonParse(read.content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            matched: false,
+            detail: `forged/unsigned marker rejected: marker body at ${filePath} is not a JSON object`,
+            marker: null,
+            expired: false,
+            forged: true,
+        };
+    }
+    const obj = parsed;
+    const verification = verifyMarkerSignature(generatedDir, sessionId, obj);
+    if (!verification.ok) {
+        if (verification.kind === "key-unavailable") {
+            // Fail-closed I/O problem (permission error / disk issue reading or
+            // creating the signing key), NOT evidence of an active forgery
+            // attempt — a marker written by the operator with a perfectly valid
+            // signature would also fail this exact check if the key file became
+            // unreadable. Kept distinct from `forged` (review LOW 1,
+            // harness/f9485cc7) so a broken key file doesn't read as an attack
+            // in audit output, mirroring the `read.kind === "unreadable"` branch
+            // above.
+            return {
+                matched: false,
+                detail: `approval marker at ${filePath} could not be verified: ${verification.reason}; treating as unapproved`,
+                marker: null,
+                expired: false,
+                forged: false,
+            };
+        }
+        return {
+            matched: false,
+            detail: `forged/unsigned marker rejected: ${verification.reason} (${filePath})`,
+            marker: null,
+            expired: false,
+            forged: true,
+        };
+    }
+    const approvedAt = obj["approvedAt"];
+    const approvedBy = obj["approvedBy"];
+    const reportContentHash = typeof obj["reportContentHash"] === "string" ? obj["reportContentHash"] : null;
+    const marker = { approvedAt, approvedBy, reportContentHash };
+    if (opts.maxAgeMs !== undefined) {
+        const approvedAtMs = Date.parse(approvedAt);
+        if (Number.isFinite(approvedAtMs)) {
+            const nowMs = (opts.now ?? new Date()).getTime();
+            const ageMs = nowMs - approvedAtMs;
+            if (ageMs > opts.maxAgeMs) {
+                const ageMin = Math.round(ageMs / 60_000);
+                const maxMin = Math.round(opts.maxAgeMs / 60_000);
+                return {
+                    matched: false,
+                    detail: `approval marker ${path.basename(filePath)} expired: age ${ageMin}m > max ${maxMin}m (approved at ${approvedAt})`,
+                    marker,
+                    expired: true,
+                    forged: false,
+                };
+            }
+        }
+    }
+    return {
+        matched: true,
+        detail: `approved via marker ${path.basename(filePath)}: approved at ${approvedAt} by ${approvedBy}, signature verified`,
+        marker,
+        expired: false,
+        forged: false,
+    };
+}
+/** Clear the per-session marker (used by `harness approve --revoke` and tests). */
+export function clearApprovalMarker(generatedDir, sessionId) {
+    try {
+        fs.rmSync(approvalMarkerPathFor(generatedDir, sessionId));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=markers.js.map

package/dist/policy-packs/builtin/understanding-before-execution/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/markers.ts"],"names":[],"mappings":"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"}

package/dist/policy-packs/builtin/understanding-before-execution/persisted-reports.d.ts

@@ -0,0 +1,177 @@
+export interface PersistedReport {
+    filePath: string;
+    sessionId: string | null;
+    approvalStatus: string | null;
+    approvedAt: string | null;
+    /**
+     * ISO timestamp the producer stamped when it wrote the report; null
+     * for legacy reports without the field.
+     */
+    createdAt: string | null;
+    /**
+     * Effective creation time in epoch ms, resolved `createdAt` →
+     * filename ISO prefix → file mtime. Unlike mtime alone this survives
+     * the approval rewrite (which bumps mtime and would otherwise make a
+     * weeks-old report sort as the freshest, harness-discovery C1).
+     */
+    createdAtMs: number;
+}
+/**
+ * Env var the persisted-report directory can be set from. Honored by
+ * harness (`defaultReportsDir` below + emitted by `harness apply` onto
+ * the pack-contributed hook commands) AND by `@lannguyensi/understanding-gate`
+ * (its `core/persistence.js:resolveReportDir` reads the same name), so
+ * the three actors that touch the directory — Stop hook (package),
+ * PreToolUse blocker (harness), `harness approve understanding` — can
+ * agree on the path regardless of each process's cwd.
+ */
+export declare const REPORTS_DIR_ENV = "UNDERSTANDING_GATE_REPORT_DIR";
+/**
+ * Resolve the persisted-report directory. Precedence:
+ *   1. `UNDERSTANDING_GATE_REPORT_DIR` (taken verbatim — apply emits an
+ *      absolute path, operator-exported values are shell-expanded before
+ *      we see them).
+ *   2. `<cwd>/.understanding-gate/reports` — backward-compat fallback.
+ *      Callers that have a stable anchor (the manifest directory) pass
+ *      it as `cwd` so the fallback agrees with whatever path apply
+ *      baked into the hook commands.
+ */
+export declare function defaultReportsDir(cwd?: string): string;
+/**
+ * Project root anchor for the reports directory: `<dir-of-manifest>/.understanding-gate/reports`.
+ * Used by `harness apply` to bake an absolute, manifest-anchored value into
+ * the pack-contributed hook commands' env, and by `harness approve` as the
+ * fallback when `UNDERSTANDING_GATE_REPORT_DIR` is unset.
+ */
+export declare function reportsDirForManifest(manifestPath: string): string;
+export declare function safeJsonParse(text: string): unknown;
+/**
+ * List persisted reports under `dir`, newest-first by creation time
+ * (JSON `createdAt`, falling back to the filename ISO prefix, falling
+ * back to mtime). Missing directory returns []. Any I/O error on a
+ * single file is silently skipped; the caller falls through to the
+ * ledger result.
+ *
+ * Creation time, NOT mtime, is the sort key: `harness approve
+ * understanding` rewrites the report it flips, which bumps mtime and
+ * made an old just-approved report sort as the freshest
+ * (harness-discovery C1). mtime survives only as the last-resort
+ * fallback for files that carry neither timestamp.
+ */
+export declare function listPersistedReports(dir: string): PersistedReport[];
+/**
+ * Maximum age a sessionId-null report may have for the tolerant
+ * fallback to adopt it on the `harness approve understanding` path.
+ * Sized for the real flow (Stop hook persists at turn end, operator
+ * approves within minutes) with slack for a slow read-through. Live
+ * repro that motivated it: a 17-day-old pending report got adopted,
+ * validated, and stamped for a fresh session because the producer had
+ * silently failed to persist the fresh report (harness-discovery C1,
+ * friction-log #67).
+ */
+export declare const TOLERANT_FALLBACK_MAX_AGE_MS: number;
+/**
+ * Tolerance for a sessionId-less candidate whose `createdAt` lies in
+ * the FUTURE relative to the approve-time clock. A future creation
+ * time is suspect either way: a forged `createdAt` (the producer's
+ * Metadata block lets the agent author it) or serious clock skew.
+ * Beyond this skew the fallback rejects the candidate just like a
+ * stale one rather than trusting a timestamp that cannot be right.
+ */
+export declare const TOLERANT_FALLBACK_FUTURE_SKEW_MS: number;
+export interface FindReportOptions {
+    /**
+     * Behaviour of the sessionId-null tolerant fallback (older Stop-hook
+     * package versions write reports without a `sessionId` field):
+     *  - `"any"` (default): adopt the freshest sessionId-null report
+     *    regardless of its `approvalStatus`. The gate read path
+     *    (`checkPersistedReport`) and post-tool-use expiry
+     *    (`expirePersistedReport`) rely on this so they keep finding the
+     *    session's own report.
+     *  - `"uncompleted"`: skip sessionId-null reports whose
+     *    `approvalStatus` is a terminal `approved` / `expired`. Such a
+     *    report belongs to a prior, finished approval cycle (often from
+     *    a different task days ago) and must not be silently re-adopted
+     *    as the current session's approval. `harness approve
+     *    understanding` passes this so it never flips a stale unrelated
+     *    report into the live session (harness/0dce3880 friction #1).
+     */
+    tolerantFallback?: "any" | "uncompleted";
+    /**
+     * Maximum age (relative to `now`) of a sessionId-null candidate the
+     * tolerant fallback may adopt; older candidates are skipped and
+     * surfaced via `FindReportSelection.staleRejected`. Strict sessionId
+     * matches are never age-limited. Unset means no limit (the legacy
+     * gate-read / expiry contract).
+     */
+    maxFallbackAgeMs?: number;
+    /** Clock anchor for the age computation; defaults to the wall clock. */
+    now?: Date;
+}
+export interface FindReportSelection {
+    report: PersistedReport | null;
+    /**
+     * True when `report` was adopted via the sessionId-null tolerant
+     * fallback rather than a strict sessionId match. Callers that bind
+     * the report to a session (the approve flow) surface this loudly so
+     * the operator can verify the adoption.
+     */
+    fallbackAdopted: boolean;
+    /**
+     * sessionId-null candidates skipped for exceeding `maxFallbackAgeMs`,
+     * newest first. Lets the caller distinguish "no report at all" from
+     * "only stale candidates existed", which are different failures: the
+     * latter usually means the producer failed to persist the fresh
+     * report (harness-discovery C1).
+     */
+    staleRejected: PersistedReport[];
+}
+/**
+ * Select the freshest report for a given session_id, or the freshest
+ * applicable report when the persisted file lacks a sessionId field
+ * (older package versions). `report: null` when nothing matches.
+ *
+ * The strict (sessionId-equals) match always wins. The tolerant
+ * fallback's appetite is controlled by `opts.tolerantFallback` and
+ * `opts.maxFallbackAgeMs` — see `FindReportOptions`. The selection
+ * result carries enough context (`fallbackAdopted`, `staleRejected`)
+ * for the caller to be loud about non-strict adoptions.
+ */
+export declare function selectReportForSession(reports: PersistedReport[], sessionId: string, opts?: FindReportOptions): FindReportSelection;
+/**
+ * Back-compat wrapper around `selectReportForSession` for callers that
+ * only need the report (the gate read and expiry paths).
+ */
+export declare function findLatestReportForSession(reports: PersistedReport[], sessionId: string, opts?: FindReportOptions): PersistedReport | null;
+export interface PersistedReportApprovalCheck {
+    approved: boolean;
+    detail: string;
+    report: PersistedReport | null;
+}
+/**
+ * Flip the latest matching persisted report's approvalStatus to
+ * `expired` so it no longer satisfies the gate's persisted-report
+ * fallback (harness/1ee26e77 follow-up: post-tool-use expiry was
+ * marker-only; the persisted report at .understanding-gate/reports/
+ * silently kept satisfying the gate even after task_finish deleted
+ * the marker).
+ *
+ * Atomic rewrite. Preserves the rest of the report body so the audit
+ * trail (the operator's actual Understanding text + previous approval
+ * timestamps) stays intact; only the status fields change.
+ *
+ * Returns `{ ok: true, filePath, previousStatus }` on success,
+ * `{ ok: false, reason }` when no matching report exists or rewrite
+ * failed. Non-throwing: caller (post-tool-use hook) uses this as a
+ * best-effort cleanup so a missing report dir or unrelated I/O issue
+ * does not escalate into a session-breaking hook failure.
+ */
+export declare function expirePersistedReport(reportsDir: string, sessionId: string, now?: Date): {
+    ok: true;
+    filePath: string;
+    previousStatus: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkPersistedReport(reportsDir: string, sessionId: string): PersistedReportApprovalCheck;