@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/dist/middleware/approval-gate.js

@@ -16,46 +16,107 @@
  * pausing again.
  *
  * Platform tool defaults: DeepAgents JS backend tools (read, write,
- * edit, execute, etc.) are not covered by MCP policy chains. This
- * middleware applies sensible defaults: read-only tools are auto-approved,
- * mutating tools require approval when no explicit policy exists.
+ * edit, execute, etc.) are not covered by MCP policy chains. Built-in tools
+ * are classified through the shared {@link toolApprovalCategory} — the single
+ * source of truth, shared with the Cursor deny-oracle hook — so read-only tools
+ * are auto-approved and every mutating tool (write/edit/delete/shell) is gated
+ * fail-CLOSED, by category rather than by a hand-maintained name list. An
+ * unrecognized mutating built-in (e.g. `bash`, `overwrite_file`) is therefore
+ * gated by what it does, not by whether someone remembered to list it.
+ *
+ * Gateway invariant (Phase 2): this middleware IS the in-process execution
+ * gateway for the deep-agent harness — `handler(request)` is the side effect. A
+ * side effect runs only with a backing authorization: either (a) the tool was
+ * auto-approved (policy/classifier cleared it, or auto-approve-all disabled the
+ * whole gate), or (b) the user explicitly approved THIS interrupted call. Every
+ * other outcome — skip, reject, or an unrecognized decision — returns a
+ * ToolMessage WITHOUT executing. There is no path from a model proposal to a
+ * side effect that skips an authorization.
+ *
+ * Shadow ExecutionReceipt: when the gateway lets a side effect through it emits a
+ * structured, non-persisted receipt (a `[hitl-gateway] receipt …` log carrying
+ * the action's HMAC fingerprint and the authorization source). This is an audit
+ * + uniformity signal only — no proto, no storage — mirroring the Phase-1 shadow
+ * discipline. On the deep-agent normal path the fingerprint match is guaranteed
+ * by LangGraph checkpoint replay (the resumed action equals the approved one), so
+ * the receipt is defense-in-depth here; the fingerprint earns real enforcement
+ * teeth in the out-of-process Cursor substrate.
  */
 import { ToolMessage } from "@langchain/core/messages";
 import { interrupt } from "@langchain/langgraph";
-import { resolveApprovalMessage, } from "../shared/approval-policy.js";
-const SAFE_PLATFORM_TOOLS = new Set([
-    "read", "read_file",
-    "ls", "list_directory",
-    "glob", "find_files",
-    "grep", "search", "ripgrep",
-    "think",
-]);
-const DANGEROUS_PLATFORM_TOOLS = new Map([
-    ["write", "Write file: {{args.path}}"],
-    ["write_file", "Write file: {{args.path}}"],
-    ["edit", "Edit file: {{args.path}}"],
-    ["edit_file", "Edit file: {{args.path}}"],
-    ["create", "Create file: {{args.path}}"],
-    ["create_file", "Create file: {{args.path}}"],
-    ["delete", "Delete: {{args.path}}"],
-    ["delete_file", "Delete file: {{args.path}}"],
-    ["execute", "Execute command: {{args.command}}"],
-    ["shell", "Execute shell command: {{args.command}}"],
-    ["str_replace_editor", "Edit file: {{args.path}}"],
-]);
+import { POLICY_ENGINE_VERSION, resolveApprovalMessage, } from "../shared/approval-policy.js";
+import { toolApprovalCategory } from "../shared/tool-kind.js";
+import { extractFilePath } from "../shared/file-tools.js";
+import { isSecretLikePath } from "../shared/filereview/secret-paths.js";
+import { computeApprovalFingerprint, } from "../shared/approval-fingerprint.js";
+// Approval-message template per mutating category. Keyed by category (not raw
+// tool name) so every alias of a mutation renders one message; placeholders
+// resolve against the deep-agent stream arg shape (`path`/`command`). Mirrors
+// the Cursor side's CATEGORY_APPROVAL_MESSAGE.
+const CATEGORY_APPROVAL_MESSAGE = {
+    write: "Write file: {{args.path}}",
+    delete: "Delete: {{args.path}}",
+    shell: "Execute command: {{args.command}}",
+};
 export function createApprovalGateMiddleware(config) {
-    const { policies, autoApproveAll, toolServerMap } = config;
-    if (autoApproveAll) {
-        return { name: "ApprovalGateMiddleware" };
-    }
+    const { policies, toolServerMap } = config;
+    const leasedCategories = config.leasedCategories ?? EMPTY_CATEGORY_SET;
+    // No global-bypass early return: a pre-armed spec.auto_approve_all means the
+    // gate is never even installed (setup.ts builds this config only when not
+    // global). Scoped leases keep the gate active so non-leased actions still gate.
     return {
         name: "ApprovalGateMiddleware",
         async wrapToolCall(request, handler) {
             const { toolCall } = request;
             const toolName = toolCall.name;
             const serverSlug = toolServerMap.get(toolName) ?? "";
-            const requirement = resolveToolApproval(toolName, serverSlug, toolCall.args, policies);
+            const category = toolApprovalCategory(toolName);
+            // Capture mode (git workspaces): a git-tracked built-in file mutation flows
+            // during the turn and is reviewed post-hoc via the file_review ledger (the
+            // apply-then-review model). shell and MCP tools (serverSlug present) are
+            // never bypassed here.
+            if (config.fileCaptureMode &&
+                config.isCapturablePath &&
+                !serverSlug &&
+                (category === "write" || category === "delete")) {
+                const path = extractFilePath(toolCall.args);
+                if (path !== null) {
+                    if (await config.isCapturablePath(path)) {
+                        // Git-tracked: flows and is reviewed post-hoc by the git substrate.
+                        emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
+                        return await handler(request);
+                    }
+                    // Gitignored path. Only the PARENT gate (captureIgnored) routes it into
+                    // CAS capture; sub-agent gates fall through to the interrupt gate below,
+                    // exactly as before (their backends are not CAS-observed).
+                    if (config.captureIgnored) {
+                        if (isSecretLikePath(path)) {
+                            // DD-E fail-closed: a secret-like gitignored edit is NEVER applied
+                            // and NEVER captured. Record it so the turn boundary authors a
+                            // DIFF_UNREVIEWABLE entry (blocking approval); nothing is written.
+                            config.recordBlockedSecret?.(path);
+                            return new ToolMessage({
+                                content: `Tool '${toolName}' was blocked for security: '${path}' matches a ` +
+                                    `secret-like path Stigmer will not capture for review. Nothing was written.`,
+                                tool_call_id: toolCall.id,
+                                name: toolName,
+                            });
+                        }
+                        if (category === "write") {
+                            // Non-secret gitignored write/edit: flows (apply-then-review). The
+                            // CAS observer already holds its before-bytes and the turn boundary
+                            // captures it into CAS. (A gitignored delete has no backend capture
+                            // path, so it falls through to the interrupt gate.)
+                            emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
+                            return await handler(request);
+                        }
+                    }
+                }
+            }
+            const requirement = resolveToolApproval(toolName, serverSlug, toolCall.args, policies, leasedCategories);
             if (!requirement.requiresApproval) {
+                // Backing authorization: the classifier/policy auto-approved this tool.
+                emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", requirement.source);
                 return await handler(request);
             }
             const approvalRequest = {
@@ -63,12 +124,18 @@ export function createApprovalGateMiddleware(config) {
                 tool_name: toolName,
                 mcp_server_slug: serverSlug,
                 message: requirement.message,
+                // Carry the gate's provenance verdict through the interrupt so the
+                // reinvocation that seeds the WAITING_APPROVAL tool call (index.ts) can
+                // persist ToolCall.approval_policy_source without re-deriving it.
+                policy_source: requirement.source,
             };
             const response = interrupt(approvalRequest);
             const action = (typeof response === "object" && response !== null
                 ? (response.action ?? "")
                 : "").toString().toLowerCase();
             if (action === "approve") {
+                // Backing authorization: the user approved THIS interrupted call.
+                emitExecutionReceipt(config, toolCall, serverSlug, category, "approval", requirement.source);
                 return await handler(request);
             }
             if (action === "skip") {
@@ -98,28 +165,88 @@ export function createApprovalGateMiddleware(config) {
         },
     };
 }
-function resolveToolApproval(toolName, serverSlug, args, policies) {
+function resolveToolApproval(toolName, serverSlug, args, policies, leasedCategories) {
     if (serverSlug) {
+        // MCP tools stay governed by the connect-flow classifier + four-level policy
+        // chain. The policy map carries only the tools that REQUIRE approval, so an
+        // absent entry means the classifier already auto-approved it — fail-OPEN is
+        // correct here (a fail-closed default would re-gate everything the classifier
+        // cleared). This is deliberately NOT changed by the built-in fail-closed flip.
+        //
+        // A server-scoped lease surfaces here as an absent entry too: the leased
+        // server's tools are dropped from `policies` upstream (mergeApprovalPolicies),
+        // so a lease-cleared MCP tool takes this same auto-approve path. (Its shadow
+        // receipt therefore reads classifier_default rather than approval_lease; a
+        // faithful per-server lease provenance would need the lease set threaded here
+        // and is deferred with the rest of the persisted-receipt work.)
         const key = `${serverSlug}/${toolName}`;
         const policy = policies.get(key);
         if (policy) {
             return {
                 requiresApproval: policy.requiresApproval,
                 message: resolveApprovalMessage(policy.approvalMessage, toolName, args),
+                source: policy.source,
             };
         }
-        return { requiresApproval: false, message: "" };
-    }
-    if (SAFE_PLATFORM_TOOLS.has(toolName)) {
-        return { requiresApproval: false, message: "" };
+        // Absent = cleared by the MCP four-level chain (classifier base) or by a
+        // server-scoped lease (dropped upstream).
+        return { requiresApproval: false, message: "", source: "classifier_default" };
     }
-    const dangerousTemplate = DANGEROUS_PLATFORM_TOOLS.get(toolName);
-    if (dangerousTemplate) {
+    // Built-in/platform tool: gate exactly the mutating categories via the shared
+    // classifier. Fail-CLOSED for the mutating set — any built-in classifyTool
+    // deems write/edit/delete/shell requires approval. Read-only and unclassified
+    // built-ins are not mutating, so they remain fail-open.
+    const category = toolApprovalCategory(toolName);
+    if (category) {
+        // Run-lifetime category lease: the user chose "approve all <category>"
+        // earlier in this run, so every built-in of that category is auto-approved
+        // for the rest of the run (the scoped successor to auto-approve-all).
+        if (leasedCategories.has(category)) {
+            return { requiresApproval: false, message: "", source: "approval_lease" };
+        }
         return {
             requiresApproval: true,
-            message: resolveApprovalMessage(dangerousTemplate, toolName, args),
+            message: resolveApprovalMessage(CATEGORY_APPROVAL_MESSAGE[category], toolName, args),
+            source: "builtin_category",
         };
     }
-    return { requiresApproval: false, message: "" };
+    return { requiresApproval: false, message: "", source: "builtin_category" };
+}
+/** Shared empty set so a config without leases allocates nothing per call. */
+const EMPTY_CATEGORY_SET = new Set();
+/**
+ * Emit the shadow ExecutionReceipt when the gateway authorizes a side effect.
+ *
+ * Scope: only side-effecting actions are recorded — a mutating built-in (a
+ * non-empty {@link ToolApprovalCategory}) or any MCP tool (`serverSlug` present).
+ * Read-only built-ins are not side effects, so recording them would only dilute
+ * the signal. The receipt is a structured log carrying the action's HMAC
+ * fingerprint and the authorization source; it is never persisted and crosses no
+ * wire (no proto). The fingerprint is omitted (empty) when no per-execution key
+ * was supplied (tests / no-secret paths).
+ */
+function emitExecutionReceipt(config, toolCall, serverSlug, category, source, policySource) {
+    if (!category && !serverSlug)
+        return;
+    const fingerprint = config.fingerprintKey
+        ? computeApprovalFingerprint(config.fingerprintKey, {
+            toolName: toolCall.name,
+            mcpServerSlug: serverSlug,
+            args: toolCall.args,
+        })
+        : "";
+    console.log("[hitl-gateway] receipt " +
+        JSON.stringify({
+            executionId: config.executionId ?? "",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            mcpServerSlug: serverSlug,
+            category: category ?? "",
+            authorization: source,
+            policySource,
+            policyEngineVersion: POLICY_ENGINE_VERSION,
+            fingerprint,
+            substrate: "deep-agent",
+        }));
 }
 //# sourceMappingURL=approval-gate.js.map

package/dist/middleware/approval-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"approval-gate.js","sourceRoot":"","sources":["../../src/middleware/approval-gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approval-gate.js","sourceRoot":"","sources":["../../src/middleware/approval-gate.ts"],"names":[],"mappings":"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"}

package/dist/middleware/types.d.ts

@@ -81,11 +81,8 @@ export interface CostCapConfig {
 export interface OtelSpansConfig {
     readonly toolServerMap: ReadonlyMap<string, string>;
 }
-export interface ApprovalGateConfig {
-    readonly policies: ReadonlyMap<string, import("../shared/approval-policy.js").MergedToolPolicy>;
-    readonly autoApproveAll: boolean;
-    readonly toolServerMap: ReadonlyMap<string, string>;
-}
+import type { ApprovalGateConfig } from "./approval-gate.js";
+export type { ApprovalGateConfig };
 /**
  * Top-level configuration for buildMiddlewareStack().
  * All sections are optional — the factory applies sensible defaults.

package/dist/shared/activity-input.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed Temporal activity input shared by ExecuteCursor and ExecuteDeepAgent.
+ *
+ * The Go and Java control planes now invoke these activities with a single
+ * object carrying snake_case keys (mirroring the polyglot workflow-input
+ * convention) instead of positional string args. This ends the prior drift
+ * where Go sent (executionId, threadId) and Java sent
+ * (executionId, threadId, invokerIdentityAccountId) while this single runner
+ * read only the first two positionally.
+ *
+ * TRANSITIONAL DUAL-SHAPE: the activity is MaximumAttempts=1 (a failed activity
+ * fails the execution with no retry), and the control plane and this runner
+ * deploy separately. To make the rollout order-independent, the runner accepts
+ * BOTH the new object and the legacy positional args. Deploy the runner first,
+ * then the control planes; once both are everywhere, drop the positional branch
+ * (and the `string` arms below).
+ */
+export interface ExecuteActivityInput {
+    readonly execution_id: string;
+    readonly thread_id: string;
+    /** Carried for cross-edition parity; the runner hydrates the invoker from the DB. */
+    readonly invoker_identity_account_id?: string;
+    /**
+     * Monotonic HITL-cycle index within this execution: 0 on the first invocation,
+     * then the workflow's approvalCycle on each reinvocation. The Cursor producer
+     * mints its deterministic file-review change-set id ({@code executionId:turnSeq})
+     * from it. Absent on the legacy positional wire shape (defaults to 0).
+     */
+    readonly turn_seq?: number;
+}
+export interface NormalizedActivityInput {
+    readonly executionId: string;
+    readonly threadId: string;
+    /** HITL-cycle index for this invocation; 0 on the first turn / legacy wire shape. */
+    readonly turnSeq: number;
+}
+/**
+ * Normalizes either the new typed object or the legacy positional args into the
+ * `{ executionId, threadId, turnSeq }` the inner activity path consumes.
+ * `thread_id` is empty on a first invocation (new harness state) and `turn_seq`
+ * defaults to 0 (first turn, or the legacy positional shape that never carried it).
+ */
+export declare function normalizeActivityInput(arg0: ExecuteActivityInput | string | undefined, arg1?: string): NormalizedActivityInput;

package/dist/shared/activity-input.js

@@ -0,0 +1,17 @@
+/**
+ * Normalizes either the new typed object or the legacy positional args into the
+ * `{ executionId, threadId, turnSeq }` the inner activity path consumes.
+ * `thread_id` is empty on a first invocation (new harness state) and `turn_seq`
+ * defaults to 0 (first turn, or the legacy positional shape that never carried it).
+ */
+export function normalizeActivityInput(arg0, arg1) {
+    if (arg0 !== null && typeof arg0 === "object") {
+        return {
+            executionId: arg0.execution_id ?? "",
+            threadId: arg0.thread_id ?? "",
+            turnSeq: arg0.turn_seq ?? 0,
+        };
+    }
+    return { executionId: arg0 ?? "", threadId: arg1 ?? "", turnSeq: 0 };
+}
+//# sourceMappingURL=activity-input.js.map

package/dist/shared/activity-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-input.js","sourceRoot":"","sources":["../../src/shared/activity-input.ts"],"names":[],"mappings":"AAsCA;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAA+C,EAC/C,IAAa;IAEb,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO;YACL,WAAW,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE;YACpC,QAAQ,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE;YAC9B,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC;SAC5B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC"}

package/dist/shared/approval-canonicalize.d.ts

@@ -0,0 +1,19 @@
+export interface ToolActionInput {
+    toolName: string;
+    mcpServerSlug?: string;
+    paths?: string[];
+    shellCommand?: string;
+    args?: Record<string, unknown>;
+    secretKeys?: string[];
+    workspaceRoot?: string;
+}
+export interface CanonicalToolAction {
+    toolName: string;
+    mcpServerSlug: string;
+    paths: string[];
+    shellCommand: string;
+    args: Record<string, unknown>;
+}
+export declare function canonicalizeToolAction(input: ToolActionInput): CanonicalToolAction;
+export declare function canonicalToolActionJson(input: ToolActionInput): string;
+export declare function canonicalJson(value: unknown): string;

package/dist/shared/approval-canonicalize.js

@@ -0,0 +1,119 @@
+// Deterministic canonicalization of a tool action into a byte-stable form.
+// Domain: HITL approval. This is the cross-language contract the approval
+// fingerprint (Phase 2) will hash; Phase 1 *defines and computes* it without
+// hashing, so Go/Java/TS can be pinned to byte-identical output via the shared
+// vector corpus (apis/testdata/hitl/canonicalization/).
+//
+// Why this exists: the March 2026 dedup bug was caused by hashing divergent
+// representations of the same action (display args in one place, raw args in
+// another). The fix is a single, explicit normalization pass — applied at ONE
+// layer — that erases incidental differences (path separators, workspace
+// location, shell whitespace, MCP slug case, secret values) before any hash.
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+export function canonicalizeToolAction(input) {
+    return {
+        toolName: input.toolName.trim(),
+        // Slugs are case-insensitive identity; lowercase so "GitHub" == "github".
+        mcpServerSlug: (input.mcpServerSlug ?? "").trim().toLowerCase(),
+        paths: normalizePaths(input.paths ?? [], input.workspaceRoot),
+        shellCommand: normalizeShellCommand(input.shellCommand ?? ""),
+        args: redactSecrets(input.args ?? {}, new Set(input.secretKeys ?? [])),
+    };
+}
+// canonicalToolActionJson is the single entry point: normalize, then serialize
+// to canonical JSON. The returned string is the byte-stable contract value.
+export function canonicalToolActionJson(input) {
+    return canonicalJson(canonicalizeToolAction(input));
+}
+// canonicalJson serializes a value to RFC 8785-style canonical JSON: object keys
+// sorted by UTF-16 code unit, no insignificant whitespace, UTF-8 output.
+//
+// The input domain is deliberately constrained to strings, booleans, null,
+// integers, arrays, and plain objects — the shape of a normalized tool action.
+// Non-integer numbers are rejected rather than implementing RFC 8785's full
+// number-formatting algorithm, keeping this hand-rolled serializer small and
+// provably cross-language without a third-party dependency. Revisit if the
+// canonical domain ever needs floats.
+export function canonicalJson(value) {
+    return serialize(value);
+}
+function serialize(v) {
+    if (v === null)
+        return "null";
+    switch (typeof v) {
+        case "boolean":
+            return v ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(v))
+                throw new Error("canonicalJson: non-finite number");
+            if (!Number.isInteger(v)) {
+                throw new Error("canonicalJson: non-integer numbers are not part of the canonical contract");
+            }
+            return String(v);
+        case "string":
+            // JSON.stringify produces the same minimal escaping and raw UTF-8 for
+            // non-ASCII that RFC 8785 mandates for these inputs.
+            return JSON.stringify(v);
+        case "object":
+            if (Array.isArray(v))
+                return "[" + v.map(serialize).join(",") + "]";
+            return serializeObject(v);
+        default:
+            throw new Error(`canonicalJson: unsupported type ${typeof v}`);
+    }
+}
+function serializeObject(obj) {
+    // `undefined`-valued keys are dropped (they have no JSON representation);
+    // remaining keys are sorted by UTF-16 code unit, which is JS's default string
+    // ordering and matches RFC 8785.
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort(compareUtf16);
+    const parts = keys.map((k) => JSON.stringify(k) + ":" + serialize(obj[k]));
+    return "{" + parts.join(",") + "}";
+}
+function compareUtf16(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function normalizePaths(paths, workspaceRoot) {
+    return paths.map((p) => normalizeOnePath(p, workspaceRoot)).sort(compareUtf16);
+}
+function normalizeOnePath(p, workspaceRoot) {
+    // Separator-normalize to forward slashes first so Windows and POSIX agree.
+    let s = p.replace(/\\/g, "/");
+    if (workspaceRoot) {
+        const root = workspaceRoot.replace(/\\/g, "/");
+        if (s === root) {
+            s = "";
+        }
+        else if (s.startsWith(root + "/")) {
+            s = s.slice(root.length + 1);
+        }
+    }
+    // Collapse `.`/`..` segments deterministically. posix.normalize("") -> ".".
+    return s === "" ? "" : posix.normalize(s);
+}
+function normalizeShellCommand(cmd) {
+    // Collapse runs of whitespace to a single space and trim. The argument VALUE
+    // (the command) is what matters; incidental spacing is not identity.
+    return cmd.replace(/\s+/g, " ").trim();
+}
+function redactSecrets(args, secretKeys) {
+    if (secretKeys.size === 0)
+        return args;
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        out[k] = secretKeys.has(k) ? redactValue(v) : v;
+    }
+    return out;
+}
+function redactValue(v) {
+    // Redact-but-stable: a SHA-256 digest keeps the canonical form stable across
+    // runs without ever placing the secret in cleartext. This is NOT the approval
+    // fingerprint — that is an HMAC keyed on a Stigmer secret, introduced in
+    // Phase 2. This digest is unkeyed redaction only.
+    const material = typeof v === "string" ? v : canonicalJson(v);
+    return "sha256:" + createHash("sha256").update(material, "utf8").digest("hex");
+}
+//# sourceMappingURL=approval-canonicalize.js.map

package/dist/shared/approval-canonicalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-canonicalize.js","sourceRoot":"","sources":["../../src/shared/approval-canonicalize.ts"],"names":[],"mappings":"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"}

package/dist/shared/approval-fingerprint.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Approval fingerprint — the exact-match enforcement identity for the HITL Tool
+ * Execution Gateway (Phase 2).
+ *
+ * A fingerprint is `HMAC-SHA256(key, canonicalForm)` over a canonicalized tool
+ * action (see {@link file://./approval-canonicalize.ts}). It answers exactly one
+ * question at the moment of side effect: "is *this* action the one the user
+ * approved?" An approval is bound to the canonical identity of the action, not to
+ * the transient id of the proposing tool call, so a re-driven action that differs
+ * from what was approved is re-asked — never silently executed.
+ *
+ * Why HMAC and not a bare SHA-256 (binding canonical decision,
+ * design-decisions/approval-fingerprint-vs-march-rollback.md, Rule 4): the
+ * fingerprint is an authorization token, not a correlation key. Keying it under a
+ * Stigmer-held secret means a model (or a compromised workspace) cannot forge a
+ * value that the gateway will accept. In Phase 2 the fingerprint is
+ * recompute-and-compare at one trusted layer (no bearer token crosses a wire), so
+ * the anti-forgery property is forward-looking — it earns its keep when a lease
+ * later becomes a server-issued bearer token (Phase 7). We pay the small cost now
+ * to avoid a migration that re-keys every persisted approval later.
+ *
+ * Two fidelities share this one canonicalization core, because the two
+ * enforcement substrates differ (see the Phase-2 plan, "two enforcement
+ * substrates, not one"):
+ *
+ *  - FULL ({@link computeApprovalFingerprint}) — HMAC over the full canonical
+ *    action (tool + paths + shellCommand + args). Used by the in-process
+ *    deep-agent gateway, where approve-time and execute-time observe the same
+ *    arg shape (LangGraph checkpoint replay), so the action can be matched at
+ *    full fidelity.
+ *  - COARSE ({@link computeCoarseApprovalFingerprint}) — HMAC over
+ *    (category, salient) only. Used by the out-of-process Cursor deny-oracle
+ *    hook, whose stdin payload names the same action with a different taxonomy
+ *    (`Write` vs `edit`, `file_path` vs `path`) and cannot reproduce the full
+ *    args. The coarse projection is the documented, substrate-forced coarsening
+ *    that lets the hook-side and stream-side fingerprints agree; it is the
+ *    successor identity for execute-cursor's grant token.
+ *
+ * The fingerprint is enforcement-only and never a correlation key — correlation
+ * stays `approval_request_id` + `tool_call_id`.
+ */
+import { type BinaryLike } from "node:crypto";
+import { type ToolActionInput } from "./approval-canonicalize.js";
+/**
+ * Version tag prefixed to every fingerprint. Bumping it is the migration lever
+ * if the canonical form or the MAC primitive ever changes: an old lease and a
+ * new computation will not compare equal, so a version skew re-asks (safe) rather
+ * than silently mismatching. Keep in lockstep with the Go/Java editions.
+ */
+export declare const APPROVAL_FINGERPRINT_VERSION = "v1";
+/** The HMAC key. Raw bytes (Buffer) in production; a UTF-8 string in tests. */
+export type FingerprintKey = BinaryLike;
+/**
+ * Full-fidelity fingerprint for the in-process deep-agent gateway. Distinct
+ * actions (different tool, paths, command, or args) yield distinct fingerprints;
+ * the same action is byte-stable across re-invocations.
+ */
+export declare function computeApprovalFingerprint(key: FingerprintKey, input: ToolActionInput): string;
+/**
+ * The substrate-coarsened identity of a tool action — the only fidelity the
+ * Cursor deny-oracle hook can reproduce from its stdin payload.
+ *
+ * Mirrors execute-cursor's `toolIdentity` so the two converge on one definition:
+ * - `tool` is the cross-taxonomy {@link toolApprovalCategory} (`write`/`delete`/
+ *   `shell`) for gated built-ins, the tool name for MCP tools (whose name is
+ *   stable across layers), or the trimmed tool name for non-gated built-ins
+ *   (never lease-matched, so the fallback is harmless).
+ * - `salient` is the single resource the action targets (a normalized path or the
+ *   shell command), reusing the full form's normalization so one rule governs
+ *   both fidelities. Empty for MCP tools, which are matched by `tool` alone.
+ */
+export interface CoarseToolIdentity {
+    tool: string;
+    mcpServerSlug: string;
+    salient: string;
+}
+export declare function coarseToolIdentity(input: ToolActionInput): CoarseToolIdentity;
+/**
+ * Fingerprint an already-reduced {@link CoarseToolIdentity}. Split out from
+ * {@link computeCoarseApprovalFingerprint} so a substrate that has *already*
+ * reduced a tool call to its (tool, mcpServerSlug, salient) identity — the Cursor
+ * harness, whose hook and stream both key on a raw, un-normalized salient that
+ * the bash hook can reproduce without a workspace root — can fingerprint that
+ * exact identity through the one shared HMAC+canonical-JSON path, instead of
+ * re-deriving the salient via {@link canonicalizeToolAction} (which normalizes
+ * paths and would diverge from the hook's raw value).
+ */
+export declare function fingerprintCoarseIdentity(key: FingerprintKey, identity: CoarseToolIdentity): string;
+/**
+ * Coarse fingerprint for the out-of-process Cursor hook. By construction, two
+ * actions that name the same operation in different taxonomies (`Write` vs
+ * `edit`) over the same resource collapse to one fingerprint — this is what makes
+ * the hook-side (deny/grant) and stream-side (reconciliation) values agree.
+ */
+export declare function computeCoarseApprovalFingerprint(key: FingerprintKey, input: ToolActionInput): string;
+/**
+ * Derive the per-execution fingerprint key from a runner-held master secret.
+ *
+ * The key is scoped to one `execution_id`: stable across Temporal re-invocations
+ * of the same execution (the gateway approves on one invocation and enforces on
+ * the next), and isolated between executions so a fingerprint approved for one
+ * cannot be replayed against another. The master-secret source is wired when the
+ * gateway first consumes the fingerprint (Slices C/D); until then this is
+ * exercised only by tests against a fixed master secret.
+ */
+export declare function deriveExecutionFingerprintKey(masterSecret: FingerprintKey, executionId: string): Buffer;