@muhaven/mcp 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -9,14 +9,52 @@ import { z } from 'zod';
  * (Windows). Each request is a single JSON object; each response is a
  * single JSON object. No request pipelining, no streaming.
  *
- * **Protocol version 0.3.0** — additive bump from 0.2.0 in @muhaven/mcp@0.1.3
- * to add `hello.hasSessionKey` + `hello.effectiveConfig` (so a daemon
- * booted without `MUHAVEN_BROKER_SESSION_KEY` can serve read paths AND
- * surface its effective backend/dashboard URLs to `muhaven-broker login
- * --from-daemon`). The 0.2.0 bump from 0.1.0 (Wave 4 P3 ADR-3) added the
- * `store_jwt` / `get_jwt` / `clear_jwt` triple — the broker is the single
- * keeper of the device-flow JWT (per ADR-3 D1 "polling, not loopback
- * callback") in addition to the session-key private half.
+ * **Protocol version 0.4.0** — additive bump from 0.3.0 for Wave 5
+ * Path D Slice 1. Adds the policy-snapshot subsystem so the broker can
+ * enforce scope + per-op spend cap BEFORE signing a UserOp:
+ *  - `sign_userop` — like `sign_hash` but carries the structured inner
+ *    call (target + callData) so the broker validates against the active
+ *    policy snapshot before delegating to the signer. The MCP server
+ *    computes the UserOp hash from the prepared UserOp; the broker
+ *    signs it once policy passes.
+ *  - `store_policy_snapshot` / `get_policy_snapshot` /
+ *    `clear_policy_snapshot` — per-session policy CRUD. Snapshot
+ *    persists across daemon restarts (file-backed under
+ *    `~/.muhaven/policy-snapshots/<sessionId>.json`).
+ *  - `get_active_session_id` — narrow "which session is live?" probe used
+ *    by the MCP server to bootstrap Path D without needing the operator
+ *    to thread the sessionId through env vars. Returns the sessionId of
+ *    the SINGLE non-expired snapshot whose `signerAddress` matches the
+ *    broker's loaded signer; returns `null` when zero match OR when
+ *    multiple non-expired snapshots match (ambiguous case — caller falls
+ *    back to Path C). Intentionally narrower than `list()` so RD-3 stays
+ *    honoured (list() is daemon-internal only).
+ * Also adds error codes `rate_limited`, `max_spend_exceeded`,
+ * `policy_violation`, `scope_violation`, `no_active_snapshot`. Rate
+ * limiting is enforced in Slice 5; the enum value ships now so
+ * future-additive protocol bumps don't churn the codeset again.
+ *
+ * Trust model for `sign_userop`: per-selector, the broker decodes the
+ * uint256 at the snapshot-declared `capArgIndex` of `innerCall.callData`
+ * and enforces it against the matched `selectorCaps[i].maxAmount`. The
+ * broker does NOT re-compute the UserOp hash from packed fields (that
+ * would require entry-point + chain-id + packing knowledge inside the
+ * broker). The hash itself is trusted as supplied by the MCP server; the
+ * broker's job is to refuse signing when scope + per-op cap + signer
+ * binding don't match. The on-chain CallPolicy validator is the
+ * structural backstop for "what calldata can be executed at all" per
+ * RD-2 / RD-5 in `PATH_D_PLAN.md`. Slice 4 wildcard MUST graduate to
+ * canonical userOpHash reconstruction (RD-5).
+ *
+ * **Protocol version 0.3.0** (history) — additive bump from 0.2.0 in
+ * @muhaven/mcp@0.1.3 to add `hello.hasSessionKey` + `hello.effectiveConfig`
+ * (so a daemon booted without `MUHAVEN_BROKER_SESSION_KEY` can serve read
+ * paths AND surface its effective backend/dashboard URLs to
+ * `muhaven-broker login --from-daemon`). The 0.2.0 bump from 0.1.0 (Wave
+ * 4 P3 ADR-3) added the `store_jwt` / `get_jwt` / `clear_jwt` triple —
+ * the broker is the single keeper of the device-flow JWT (per ADR-3 D1
+ * "polling, not loopback callback") in addition to the session-key
+ * private half.
  *
  * @muhaven/mcp@0.1.5 added `hello.pid` (still protocol 0.3.0 — additive
  * optional field) so `muhaven-broker stop` can reach into the daemon
@@ -28,14 +66,16 @@ import { z } from 'zod';
  *  - The broker NEVER reaches out to the network. It only:
  *      (a) signs hashes that the MCP server received from the backend,
  *      (b) stores / returns / clears a JWT that the MCP server
- *          received from the backend.
+ *          received from the backend,
+ *      (c) stores / returns / clears per-session policy snapshots that
+ *          the MCP server (or operator CLI) provides at mint time.
  *    Splitting network egress (MCP server) from signing + secret
  *    storage (broker) is the lethal-trifecta mitigation in
  *    `THREAT_MODEL_P0.md` §"Lethal-trifecta self-audit".
  *  - Requests are size-capped (`maxRequestBytes`) — a malformed peer
  *    cannot exhaust broker memory by sending an unbounded JSON blob.
  */
-declare const BROKER_PROTOCOL_VERSION = "0.3.0";
+declare const BROKER_PROTOCOL_VERSION = "0.4.0";
 interface BrokerHelloRequest {
     readonly type: 'hello';
 }
@@ -63,6 +103,178 @@ interface BrokerGetJwtRequest {
 interface BrokerClearJwtRequest {
     readonly type: 'clear_jwt';
 }
+/**
+ * Wave 5 Path D Slice 1 — request a policy-gated UserOp signature. The
+ * MCP server has computed `userOpHash` from a prepared UserOp; the broker
+ * looks up the snapshot for `sessionId`, validates `innerCall` against
+ * the snapshot's allowlist + per-op cap, signs `userOpHash`, and returns
+ * the signature. See protocol-version JSDoc above for the trust model.
+ */
+interface BrokerSignUserOpRequest {
+    readonly type: 'sign_userop';
+    /** Snapshot key — must match a snapshot previously stored via
+     *  `store_policy_snapshot`. */
+    readonly sessionId: string;
+    /** EIP-4337 v0.7 userOpHash, 0x-prefixed 32-byte hex. Signed as-is. */
+    readonly userOpHash: `0x${string}`;
+    /** Structured representation of the kernel-inner call the prepared
+     *  UserOp will execute. Broker uses this to validate scope + per-op
+     *  cap. The MCP server is responsible for ensuring this matches what
+     *  the on-chain executor will see. */
+    readonly innerCall: {
+        /** 0x-prefixed 20-byte hex (lowercased for compare-stability). */
+        readonly target: `0x${string}`;
+        /** Encoded selector + args. Selector = bytes 0..3; ABI words at
+         *  bytes 4..35, 36..67, ... read by `decodeUint256ArgAt(callData,
+         *  wordIndex)` per the matched `selectorCaps[i].capArgIndex`. */
+        readonly callData: `0x${string}`;
+    };
+    /** Free-form context for the audit log. NOT trusted as policy input. */
+    readonly intent?: {
+        readonly tool: string;
+        readonly summary?: string;
+    };
+}
+/**
+ * Wave 5 Path D Slice 1 — write a per-session policy snapshot. The MCP
+ * server (or `muhaven-broker set-policy` CLI in Slice 3) calls this
+ * after the frontend mint ceremony to give the broker the rules it
+ * should enforce when `sign_userop` arrives.
+ */
+interface BrokerStorePolicySnapshotRequest {
+    readonly type: 'store_policy_snapshot';
+    readonly snapshot: PolicySnapshotWire;
+}
+interface BrokerGetPolicySnapshotRequest {
+    readonly type: 'get_policy_snapshot';
+    readonly sessionId: string;
+}
+interface BrokerClearPolicySnapshotRequest {
+    readonly type: 'clear_policy_snapshot';
+    readonly sessionId: string;
+}
+/**
+ * Wave 5 Path D Slice 1 (Commit 3) — narrow "active session" probe. No
+ * arguments; the broker resolves uniqueness against its loaded signer's
+ * address. The MCP server uses this to bootstrap Path D's broker-side
+ * signing path before Slice 2's backend-mirror `agent_scoped_sessions`
+ * table lands. Distinct from `get_policy_snapshot(sessionId)`: that
+ * fetches a known-id snapshot; this discovers the active id when there
+ * is exactly one.
+ *
+ * Returns `sessionId: null` (rather than an error) for both the "no
+ * active snapshot" AND "ambiguous, multiple match" cases — callers must
+ * treat them identically (fall back to Path C). Enumerating expired
+ * snapshots OR snapshots for other signers is daemon-internal; never
+ * surfaced over IPC.
+ */
+interface BrokerGetActiveSessionIdRequest {
+    readonly type: 'get_active_session_id';
+}
+/**
+ * Per-selector enforcement rule. The broker matches `innerCall`'s
+ * selector against `selector`, then — if `capArgIndex` is not null —
+ * decodes the 32-byte word at that index after the 4-byte selector and
+ * compares to `maxAmount` (≤ semantics).
+ *
+ * `capArgIndex` is the 0-based word index INTO THE ABI-ENCODED ARG TAIL.
+ * For `subscription.purchase(address token, InEuint128 encShares,
+ * uint128 maxSharesHint, address ephemeralEOA)`, the layout is:
+ *   word 0 (bytes 4..35):  address token (left-zero-padded to 32 bytes)
+ *   word 1 (bytes 36..67): InEuint128 dynamic-offset (FHE-encrypted tail)
+ *   word 2 (bytes 68..99): uint128 maxSharesHint (left-zero-padded to 32 bytes per Solidity ABI v1; value in the low 16 bytes)
+ *   word 3 (bytes 100..131): address ephemeralEOA (left-zero-padded)
+ * So `capArgIndex: 2` caps `maxSharesHint` — the plaintext upper bound
+ * on the encrypted share amount. The actual `encShares` is FHE-encrypted
+ * and the broker cannot decrypt it; `maxSharesHint` is the structural
+ * ceiling the broker enforces.
+ *
+ * `capArgIndex: null` means "selector is allowed, no arg-cap enforced"
+ * (intended for nullary-value selectors like `claim()` in future slices).
+ * `maxAmount` MUST be null when `capArgIndex` is null, and a uint256
+ * decimal string otherwise.
+ *
+ * **Static-arg assumption (Slice 1):** the broker assumes the calldata
+ * is ABI-encoded with no dynamic-type args at-or-before `capArgIndex`.
+ * For dynamic-arg targets (`bytes`, `string`, dynamic struct head), the
+ * 32-byte slot at the cap offset would be an OFFSET, not the value, and
+ * the cap would trivially pass on a tiny "offset" value while the real
+ * value sits in the dynamic tail. Slice 4 must NOT add such targets
+ * without a selector-aware ABI decoder. (`subscription.purchase` is safe
+ * — `InEuint128 calldata` is a dynamic struct, but `maxSharesHint` at
+ * word 2 is statically encoded after the dynamic-struct head-offset.)
+ */
+interface PolicySelectorCap {
+    /** 0x-prefixed 4-byte hex (lowercased). */
+    readonly selector: `0x${string}`;
+    /** 0-based word index after the selector. Null = no arg-cap enforced. */
+    readonly capArgIndex: number | null;
+    /** uint256 decimal string. Null iff `capArgIndex` is null. Unit is
+     *  whatever the target arg's base unit is (e.g. for purchase, uint128
+     *  maxSharesHint → shares, not mhUSDC base-6). MCP server is
+     *  responsible for converting user-intent units to the on-chain unit
+     *  at snapshot-mint time. */
+    readonly maxAmount: string | null;
+}
+/**
+ * Wire shape of a policy snapshot. Strings (not bigints) so JSON
+ * round-trips cleanly.
+ *
+ * Per-selector caps are carried in `selectorCaps`. The set of allowed
+ * selectors is exactly `selectorCaps.map(c => c.selector)` — no
+ * `allowedSelectors` field, single source of truth. See
+ * `PolicySelectorCap` JSDoc for the static-arg-encoding assumption +
+ * `capArgIndex` semantics.
+ */
+interface PolicySnapshotWire {
+    readonly sessionId: string;
+    readonly mode: 'scoped';
+    /** Address derived from the session-key private half. Broker compares
+     *  this against its loaded `signer.address` at sign time; mismatch
+     *  rejects with `policy_violation` to defend against snapshots minted
+     *  for a rotated session-key being applied to the new key. */
+    readonly signerAddress: `0x${string}`;
+    /** Lowercased 0x-addresses that the broker will accept as
+     *  `innerCall.target`. */
+    readonly targetContracts: readonly `0x${string}`[];
+    /** Per-selector rules. Selector must appear in this list AND
+     *  `innerCall.target` must be in `targetContracts` for the selector
+     *  match to authorize signing. */
+    readonly selectorCaps: readonly PolicySelectorCap[];
+    /** Epoch seconds. Snapshot is rejected on lookup after this time. */
+    readonly validUntilSec: number;
+    /** Epoch seconds at which the snapshot was created (audit). */
+    readonly mintedAtSec: number;
+    /** Optional Slice 1, REQUIRED Slice 4 wildcard. Hex-32 hash of the
+     *  authorizing ConfirmToken's `actionHash` so the audit chain
+     *  {userop → tier transition → consent token} is correlatable by
+     *  stable key. Future-compat reserve per Trust Architect §4. */
+    readonly consentActionHash?: `0x${string}`;
+    /** Optional Slice 1, REQUIRED Slice 4 wildcard. Hex-32 hash of the
+     *  consent text the user saw at mint time (Slice 4 gate #5). */
+    readonly consentTextSha256?: `0x${string}`;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — `getPermissionId()` for the
+     * installed `@zerodev/permissions` PermissionValidator. 4-byte hex
+     * (`keccak256(policyAndSignerData).slice(0, 4)`). Used by the MCP
+     * server to compose the 24-byte nonce-key composite Kernel v3.1
+     * requires for UserOps routed through the permission validator
+     * (`pad(concat([VALIDATOR_MODE, VALIDATOR_TYPE.PERMISSION,
+     * identifier(20), customKey(2)]))`). Without this, the bundler reads
+     * the SUDO-validator nonce slot and the UserOp is routed through
+     * the wrong validator → `AA24 InvalidSigner`.
+     *
+     * **Optional in the wire shape** so the protocol stays back-compat
+     * with pre-Pickup-B mints (DB row + broker keystore snapshots
+     * predating the Pickup B commit `1a28618` may have NULL here).
+     * Pickup B's frontend mint flow ALWAYS populates this field; any
+     * non-Pickup-B client / legacy row that omits it surfaces as Path D
+     * fallback reason `no_permission_id_in_snapshot` and degrades
+     * cleanly to Path C. Broker daemon enforces no tighter today
+     * (additive optional field, no protocol version bump).
+     */
+    readonly permissionId?: `0x${string}`;
+}
 interface BrokerHelloResponse {
     readonly type: 'hello';
     readonly version: string;
@@ -128,14 +340,45 @@ interface BrokerClearJwtResponse {
     readonly type: 'clear_jwt';
     readonly cleared: true;
 }
+interface BrokerSignUserOpResponse {
+    readonly type: 'sign_userop';
+    /** 0x-prefixed 65-byte ECDSA signature (r || s || v). */
+    readonly signature: `0x${string}`;
+    readonly signerAddress: `0x${string}`;
+    readonly sessionId: string;
+}
+interface BrokerStorePolicySnapshotResponse {
+    readonly type: 'store_policy_snapshot';
+    readonly stored: true;
+    readonly sessionId: string;
+}
+interface BrokerGetPolicySnapshotResponse {
+    readonly type: 'get_policy_snapshot';
+    /** Null when no snapshot for the requested sessionId, OR when the
+     *  snapshot exists but is past `validUntilSec` (caller treats both as
+     *  "no active snapshot"). */
+    readonly snapshot: PolicySnapshotWire | null;
+}
+interface BrokerClearPolicySnapshotResponse {
+    readonly type: 'clear_policy_snapshot';
+    readonly cleared: true;
+    readonly sessionId: string;
+}
+interface BrokerGetActiveSessionIdResponse {
+    readonly type: 'get_active_session_id';
+    /** Null when zero non-expired snapshots match the broker's loaded
+     *  signer, OR when 2+ match (ambiguous). Callers fall back to Path C
+     *  in either case. */
+    readonly sessionId: string | null;
+}
 interface BrokerErrorResponse {
     readonly type: 'error';
     readonly code: BrokerErrorCode;
     readonly message: string;
 }
-type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable' | 'session_key_unavailable';
-type BrokerRequest = BrokerHelloRequest | BrokerSignHashRequest | BrokerStoreJwtRequest | BrokerGetJwtRequest | BrokerClearJwtRequest;
-type BrokerResponse = BrokerHelloResponse | BrokerSignHashResponse | BrokerStoreJwtResponse | BrokerGetJwtResponse | BrokerClearJwtResponse | BrokerErrorResponse;
+type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable' | 'session_key_unavailable' | 'no_active_snapshot' | 'policy_violation' | 'scope_violation' | 'max_spend_exceeded' | 'rate_limited';
+type BrokerRequest = BrokerHelloRequest | BrokerSignHashRequest | BrokerStoreJwtRequest | BrokerGetJwtRequest | BrokerClearJwtRequest | BrokerSignUserOpRequest | BrokerStorePolicySnapshotRequest | BrokerGetPolicySnapshotRequest | BrokerClearPolicySnapshotRequest | BrokerGetActiveSessionIdRequest;
+type BrokerResponse = BrokerHelloResponse | BrokerSignHashResponse | BrokerStoreJwtResponse | BrokerGetJwtResponse | BrokerClearJwtResponse | BrokerSignUserOpResponse | BrokerStorePolicySnapshotResponse | BrokerGetPolicySnapshotResponse | BrokerClearPolicySnapshotResponse | BrokerGetActiveSessionIdResponse | BrokerErrorResponse;
 /**
  * Parse a single-line request payload. Returns either the validated
  * request or a structured error — the daemon converts errors to a
@@ -160,12 +403,84 @@ type BrokerClientErrorCode = 'connect_failed' | 'timeout' | 'protocol_error' | '
 declare class BrokerClientError extends Error {
     readonly code: BrokerClientErrorCode;
     readonly cause?: unknown | undefined;
-    constructor(code: BrokerClientErrorCode, message: string, cause?: unknown | undefined);
+    /**
+     * When `code === 'broker_error'`, this carries the typed upstream
+     * error code from the daemon (e.g. `unsupported_type`,
+     * `policy_violation`, `no_active_snapshot`). Callers in the tool
+     * handler layer use it to map to fine-grained fallback reasons
+     * without substring-matching on the message. Undefined for non-
+     * broker_error variants (connect_failed / timeout / protocol_error)
+     * since they never carry a daemon-side code.
+     *
+     * Added in Wave 5 Path D Slice 1 Commit 3 to close the
+     * MCP-Builder H-1: a 0.3.x daemon returning `unsupported_type` for
+     * `get_active_session_id` was previously mapped to the generic
+     * `broker_internal` Path D fallback — operator-confusing. With
+     * `brokerCode`, callers can route `unsupported_type` to
+     * `version_too_old` explicitly.
+     */
+    readonly brokerCode?: BrokerErrorCode | undefined;
+    constructor(code: BrokerClientErrorCode, message: string, cause?: unknown | undefined, 
+    /**
+     * When `code === 'broker_error'`, this carries the typed upstream
+     * error code from the daemon (e.g. `unsupported_type`,
+     * `policy_violation`, `no_active_snapshot`). Callers in the tool
+     * handler layer use it to map to fine-grained fallback reasons
+     * without substring-matching on the message. Undefined for non-
+     * broker_error variants (connect_failed / timeout / protocol_error)
+     * since they never carry a daemon-side code.
+     *
+     * Added in Wave 5 Path D Slice 1 Commit 3 to close the
+     * MCP-Builder H-1: a 0.3.x daemon returning `unsupported_type` for
+     * `get_active_session_id` was previously mapped to the generic
+     * `broker_internal` Path D fallback — operator-confusing. With
+     * `brokerCode`, callers can route `unsupported_type` to
+     * `version_too_old` explicitly.
+     */
+    brokerCode?: BrokerErrorCode | undefined);
 }
 interface BrokerClientOptions {
     endpoint: string;
     timeoutMs: number;
 }
+/**
+ * Result of `BrokerClient.preflight()`. Discriminated on `supported`.
+ * The unsupported variants carry enough structured info that the host
+ * LLM can render an actionable remediation message — semver-mismatch
+ * tells the operator to upgrade the broker; broker-unreachable tells
+ * them to start it; session-key-unavailable tells them to rotate env.
+ */
+type PreflightResult = {
+    readonly supported: true;
+    readonly daemonVersion: string;
+    readonly signerAddress: `0x${string}`;
+} | {
+    readonly supported: false;
+    readonly reason: 'version_too_old';
+    readonly daemonVersion: string;
+    readonly requiredVersion: string;
+} | {
+    readonly supported: false;
+    readonly reason: 'session_key_unavailable';
+    readonly daemonVersion: string;
+    readonly requiredVersion: string;
+} | {
+    readonly supported: false;
+    readonly reason: 'broker_unreachable';
+    readonly message: string;
+    readonly requiredVersion: string;
+};
+/**
+ * Tiny semver-gte for "is X ≥ Y". Both inputs MUST be M.m.p (no
+ * pre-release / build-metadata suffixes) — the broker protocol version
+ * is locked to that shape. Non-conforming inputs throw rather than
+ * silently mis-compare.
+ *
+ * Kept inline to avoid adding a `semver` dep just for one three-segment
+ * comparison; the broker's version space is small enough that a regex
+ * + numeric compare is bulletproof.
+ */
+declare function semverGte(a: string, b: string): boolean;
 declare class BrokerClient {
     private readonly options;
     constructor(options: BrokerClientOptions);
@@ -177,6 +492,35 @@ declare class BrokerClient {
     storeJwt(jwt: string, expiresAtSec?: number): Promise<BrokerStoreJwtResponse>;
     getJwt(): Promise<BrokerGetJwtResponse>;
     clearJwt(): Promise<void>;
+    signUserOp(args: {
+        sessionId: string;
+        userOpHash: `0x${string}`;
+        innerCall: {
+            target: `0x${string}`;
+            callData: `0x${string}`;
+        };
+        intent?: {
+            tool: string;
+            summary?: string;
+        };
+    }): Promise<BrokerSignUserOpResponse>;
+    storePolicySnapshot(snapshot: PolicySnapshotWire): Promise<BrokerStorePolicySnapshotResponse>;
+    getPolicySnapshot(sessionId: string): Promise<BrokerGetPolicySnapshotResponse>;
+    clearPolicySnapshot(sessionId: string): Promise<BrokerClearPolicySnapshotResponse>;
+    getActiveSessionId(): Promise<BrokerGetActiveSessionIdResponse>;
+    /**
+     * Detect whether the running daemon speaks Path D (protocol 0.4.0+).
+     * Wraps `hello()` with a semver-gte comparison so the MCP tool layer
+     * can short-circuit to Path C with a clear `version_too_old` reason
+     * instead of surfacing the opaque `unsupported_type` error a stale
+     * 0.3.0 daemon would emit on `sign_userop` / `get_active_session_id`
+     * (Backend Architect H-2, round 2).
+     *
+     * Returns `{ supported: false }` on broker connect failure too — the
+     * caller treats "daemon down" identically to "version too old": Path D
+     * not available, fall through to Path C.
+     */
+    preflight(): Promise<PreflightResult>;
     private exchange;
 }
 
@@ -263,11 +607,240 @@ declare class BackendClient {
      * Authorization header.
      */
     postUnauth<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * GET variant that sends no Authorization header. Use for backend
+     * endpoints that are intentionally public (e.g. `/api/v1/tokens`
+     * which the marketplace + the 0.2.1 `positionBuy` NAV-conversion
+     * both read). Avoids triggering the AUTH_REQUIRED branch for the
+     * "not yet logged in" case on read paths that don't need auth.
+     */
+    getUnauth<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
     private buildUrl;
     private exchangeWithRetry;
     private exchange;
 }
 
+/**
+ * ERC-4337 v0.7 bundler JSON-RPC client. Lives in the MCP SERVER (not
+ * the broker daemon) because submission is a network-egress action and
+ * the broker is bound by the R-1 zero-egress invariant (see
+ * `broker/protocol.ts` JSDoc + THREAT_MODEL_P0.md §"Lethal-trifecta
+ * self-audit"). The broker signs hashes; the MCP server (which already
+ * speaks HTTPS to the backend) speaks JSON-RPC to the bundler.
+ *
+ * Wave 5 Path D Slice 1 (Commit 3) scope: the BundlerClient surface +
+ * tests ship now, even though the actual UserOp build is deferred to
+ * Commit 3.5 (the FHE encrypt + kernel-execute encoding pieces have
+ * unresolved design points — see PATH_D_PLAN.md Commit 3 scope-cut).
+ *
+ * Three RPCs in scope:
+ *  - `eth_sendUserOperation(userOp, entryPoint)` → returns
+ *    `userOpHash: Hex32`.
+ *  - `eth_getUserOperationReceipt(userOpHash)` → returns receipt or
+ *    `null` when the userOp hasn't been bundled into a block yet.
+ *  - `eth_chainId()` → returns the bundler's view of the chain id;
+ *    used to detect operator misconfiguration (wrong network).
+ *
+ * Trust model: the bundler is a network peer; treat its responses as
+ * untrusted input. Every parse step throws a structured BundlerClientError
+ * on shape mismatch — never silently coerces. RPC errors (`{code, message,
+ * data}`) surface as `rpc_error` with the upstream `code` preserved so the
+ * host LLM can map known bundler error classes (`AA21`, `AA23`, etc.)
+ * without parsing message text.
+ */
+type BundlerClientErrorCode = 'config' | 'network' | 'timeout' | 'http_error' | 'invalid_response' | 'rpc_error' | 'receipt_timeout' | 'chain_mismatch';
+declare class BundlerClientError extends Error {
+    readonly code: BundlerClientErrorCode;
+    /** Optional structured detail — for rpc_error, the upstream JSON-RPC
+     *  error object (e.g. `{ code: -32600, message: "AA23 reverted", data: ... }`).
+     *  Surface fields that help the LLM steer; never the raw upstream
+     *  fields (they may carry implementation-specific data). */
+    readonly detail?: unknown | undefined;
+    constructor(code: BundlerClientErrorCode, message: string, 
+    /** Optional structured detail — for rpc_error, the upstream JSON-RPC
+     *  error object (e.g. `{ code: -32600, message: "AA23 reverted", data: ... }`).
+     *  Surface fields that help the LLM steer; never the raw upstream
+     *  fields (they may carry implementation-specific data). */
+    detail?: unknown | undefined);
+}
+/**
+ * EIP-4337 v0.7 packed UserOperation as accepted by `eth_sendUserOperation`.
+ * Bigint-valued fields are hex strings on the wire (`0x` + ≤64 hex).
+ *
+ * We accept a permissive shape (Record<string, string>) at the client
+ * boundary — the caller (Commit 3.5 UserOp builder) is responsible for
+ * stringifying its bigints. The client validates `0x`-prefix shape only;
+ * deeper shape correctness is the bundler's job to enforce.
+ */
+interface UserOperationV07Wire {
+    readonly sender: `0x${string}`;
+    readonly nonce: `0x${string}`;
+    readonly factory?: `0x${string}`;
+    readonly factoryData?: `0x${string}`;
+    readonly callData: `0x${string}`;
+    readonly callGasLimit: `0x${string}`;
+    readonly verificationGasLimit: `0x${string}`;
+    readonly preVerificationGas: `0x${string}`;
+    readonly maxFeePerGas: `0x${string}`;
+    readonly maxPriorityFeePerGas: `0x${string}`;
+    readonly paymaster?: `0x${string}`;
+    readonly paymasterVerificationGasLimit?: `0x${string}`;
+    readonly paymasterPostOpGasLimit?: `0x${string}`;
+    readonly paymasterData?: `0x${string}`;
+    readonly signature: `0x${string}`;
+}
+/**
+ * Wave 5 Path D Slice 1 Commit 3.5 — the unsigned UserOp shape passed
+ * to `pm_sponsorUserOperation`. ZeroDev's paymaster fills in the gas
+ * limits + paymaster fields and returns them; the caller then composes
+ * the full `UserOperationV07Wire` with the placeholder signature
+ * replaced by the broker's session-key signature.
+ *
+ * Optional fields the bundler tolerates being absent: gas + paymaster
+ * fields. `signature` is required (use a non-zero high-entropy
+ * placeholder so the bundler simulates a worst-case verifier cost).
+ */
+interface PartialUserOpForSponsorship {
+    readonly sender: `0x${string}`;
+    readonly nonce: `0x${string}`;
+    readonly callData: `0x${string}`;
+    readonly maxFeePerGas: `0x${string}`;
+    readonly maxPriorityFeePerGas: `0x${string}`;
+    /** Worst-case placeholder so paymaster simulates realistic gas. */
+    readonly signature: `0x${string}`;
+}
+interface SponsoredUserOpFields {
+    readonly paymaster: `0x${string}`;
+    readonly paymasterVerificationGasLimit: `0x${string}`;
+    readonly paymasterPostOpGasLimit: `0x${string}`;
+    readonly paymasterData: `0x${string}`;
+    readonly callGasLimit: `0x${string}`;
+    readonly verificationGasLimit: `0x${string}`;
+    readonly preVerificationGas: `0x${string}`;
+}
+interface EstimatedUserOpGas {
+    readonly callGasLimit: `0x${string}`;
+    readonly verificationGasLimit: `0x${string}`;
+    readonly preVerificationGas: `0x${string}`;
+}
+interface FeeData {
+    readonly maxFeePerGas: `0x${string}`;
+    readonly maxPriorityFeePerGas: `0x${string}`;
+}
+/**
+ * Receipt shape as returned by `eth_getUserOperationReceipt`. Subset
+ * we depend on; bundlers commonly return additional fields we ignore.
+ */
+interface UserOperationReceipt {
+    readonly userOpHash: `0x${string}`;
+    readonly sender: `0x${string}`;
+    readonly success: boolean;
+    /** Bundler-reported revert reason (string or hex); present on failure. */
+    readonly reason?: string;
+    /** The underlying L1/L2 tx that bundled this UserOp. */
+    readonly receipt: {
+        readonly transactionHash: `0x${string}`;
+        readonly blockNumber: `0x${string}`;
+        readonly blockHash: `0x${string}`;
+    };
+}
+interface BundlerClientOptions {
+    /** Bundler RPC endpoint — MUHAVEN_BUNDLER_URL. https-or-loopback validated
+     *  at config-load time (see `config.ts::validatePublicUrlEnv`). */
+    readonly endpoint: string;
+    /** Per-RPC HTTP timeout (ms). Default 15s — same as backend client. */
+    readonly requestTimeoutMs: number;
+    /** Expected chain id (Arb Sepolia = 421614). When set, `assertChainId()`
+     *  refuses to proceed if the bundler reports a different chain. */
+    readonly expectedChainId?: number;
+    /** Inject for tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+declare class BundlerClient {
+    private readonly options;
+    private readonly fetchImpl;
+    private nextRpcId;
+    constructor(options: BundlerClientOptions);
+    /**
+     * Submit a signed UserOperation. Returns the userOpHash the bundler
+     * computed (which must match the hash the broker signed — caller is
+     * responsible for the consistency check; broker policy snapshot
+     * captures the signer-binding piece).
+     */
+    sendUserOp(userOp: UserOperationV07Wire, entryPoint: `0x${string}`): Promise<`0x${string}`>;
+    /** Return the receipt for a userOpHash, or null when the UserOp has
+     *  not yet been bundled. */
+    getReceipt(userOpHash: `0x${string}`): Promise<UserOperationReceipt | null>;
+    /**
+     * Poll until the bundler returns a receipt, or `timeoutMs` elapses.
+     * Caller decides retry / fallback behaviour on `receipt_timeout`.
+     *
+     * Poll interval grows linearly from `initialIntervalMs` to
+     * `maxIntervalMs` to avoid burning the bundler quota when blocks are
+     * slow. Default tuning: 500ms → 2000ms over the first 6 polls; then
+     * pinned at 2000ms.
+     */
+    waitForReceipt(userOpHash: `0x${string}`, opts: {
+        readonly timeoutMs: number;
+        readonly initialIntervalMs?: number;
+        readonly maxIntervalMs?: number;
+        /** Inject for tests that want deterministic timing. */
+        readonly clockMs?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+    }): Promise<UserOperationReceipt>;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — `pm_sponsorUserOperation`.
+     * ZeroDev's bundler URL serves both bundler RPCs AND paymaster RPCs
+     * at the same endpoint, so we don't need a separate paymaster URL.
+     * Returns the paymaster fields + the gas limits the paymaster's
+     * simulation computed (the caller doesn't need a separate
+     * `estimateUserOpGas` round-trip on the happy path).
+     */
+    sponsorUserOp(userOp: PartialUserOpForSponsorship, entryPoint: `0x${string}`): Promise<SponsoredUserOpFields>;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — `eth_estimateUserOperationGas`.
+     * Not used in the happy path (sponsorship returns gas), but lives as
+     * a fallback for unsponsored flows OR if the operator's paymaster
+     * goes down. Reading gas separately also makes the failure modes
+     * distinguishable for the LLM-facing fallback reasons.
+     */
+    estimateUserOpGas(userOp: PartialUserOpForSponsorship, entryPoint: `0x${string}`): Promise<EstimatedUserOpGas>;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — `eth_call` against the
+     * EntryPoint's `getNonce(sender, key)`. Uses the bundler URL as a
+     * full Arb Sepolia node (ZeroDev's bundler accepts read-side RPCs).
+     *
+     * Pass `key = 0n` for the default nonce key — Path D never uses a
+     * non-default key in Slice 1; reserved for batched UserOps in
+     * later slices.
+     */
+    getNonce(sender: `0x${string}`, entryPoint: `0x${string}`, key?: bigint): Promise<bigint>;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — fetch the fee market via
+     * `eth_gasPrice` (returns a single value the bundler will accept for
+     * both maxFee + maxPriorityFee on Arb Sepolia, which has effectively
+     * no priority-vs-base distinction).
+     *
+     * Simple-on-purpose: a full EIP-1559 fee market read would need two
+     * RPCs (`eth_maxPriorityFeePerGas` + `eth_getBlock`); Arb Sepolia's
+     * fee dynamics don't require that precision and the paymaster pays
+     * either way. A future caller wanting EIP-1559 precision can add a
+     * sibling method.
+     */
+    getFeeData(): Promise<FeeData>;
+    /**
+     * Verify the bundler's reported chainId matches `expectedChainId`. Cheap
+     * to call once at MCP server boot (or lazily before the first send) so
+     * a misconfigured bundler URL surfaces as `chain_mismatch` before any
+     * user-facing send rather than after a guaranteed-failing submit.
+     *
+     * Throws `BundlerClientError(config)` if no `expectedChainId` is set —
+     * caller asked for an assert without configuring the expectation.
+     */
+    assertChainId(): Promise<void>;
+    private rpc;
+}
+
 /**
  * Tool descriptions are the **single source of truth** for what each MCP
  * tool advertises to the host LLM. They are also hashed (SHA-256) at
@@ -305,14 +878,15 @@ interface ToolDescriptor {
     readonly sensitive: boolean;
 }
 /**
- * The 22 Wave 4 MCP tools across five groups:
- *   muhaven.read.*       (7 — incl. P11 protection_coverage + kyc_attestation)
+ * The 23 MCP tools across five groups:
+ *   muhaven.read.*       (8 — incl. P11 protection_coverage + kyc_attestation
+ *                            + 0.2.1 read.activity for Path C settle verify)
  *   muhaven.position.*   (4)
  *   muhaven.policy.*     (4)
  *   muhaven.issuer.*     (5 — P7)
  *   muhaven.governance.* (2 — P11; cast_vote frontend runner deferred to Wave 5)
  *
- * `MUHAVEN_READ_ONLY=true` exposes only the 7 `muhaven.read.*` tools.
+ * `MUHAVEN_READ_ONLY=true` exposes only the 8 `muhaven.read.*` tools.
  * P5's `muhaven.checkout.*` namespace was retired before Wave 4 close — the
  * hosted checkout surface ships as a separate Vite SPA (apps/checkout-pay/),
  * not as an MCP tool group.
@@ -387,6 +961,16 @@ interface SessionKeyRequiredPayload {
 interface ToolDeps {
     backend: BackendClient;
     broker?: BrokerClient;
+    /**
+     * Wave 5 Path D Slice 1 (Commit 3) — ERC-4337 bundler JSON-RPC client.
+     * Undefined → Path D autonomous-buy disabled, position tools fall back
+     * to Path C deep-link (existing behaviour). Configured at MCP boot via
+     * `MUHAVEN_BUNDLER_URL`. Slice 1 ships the probe + cap-check chain;
+     * the actual UserOp build lands in Commit 3.5 (the FHE encrypt + kernel-
+     * execute encoding pieces have unresolved design points — see
+     * PATH_D_PLAN.md Commit 3 scope-cut).
+     */
+    bundler?: BundlerClient;
     /** Surface this MCP server is configured for. Always 'mcp' here, but
      *  carried as a dep so the audit tool can filter to the local surface. */
     surface: 'mcp';
@@ -397,6 +981,26 @@ interface ToolDeps {
      * production default when absent.
      */
     dashboardBaseUrl?: string;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — chain id Path D's UserOp hash
+     * computation needs. Sourced from `MUHAVEN_CHAIN_ID` env (default
+     * Arb Sepolia 421614). Always present; not optional even when Path
+     * D is disabled (cheap default + future read tools may want it).
+     */
+    chainId?: number;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — `MuHavenSubscription` contract
+     * address. Sourced from `MUHAVEN_SUBSCRIPTION_ADDRESS`. Undefined
+     * disables Path D's UserOp build path; position tools fall back to
+     * Path C with reason `subscription_address_unset`.
+     */
+    subscriptionAddress?: `0x${string}`;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — ERC-4337 EntryPoint v0.7
+     * address. Sourced from `MUHAVEN_ENTRY_POINT` env (default canonical
+     * deployment).
+     */
+    entryPointAddress?: `0x${string}`;
 }
 type ToolResult<T> = {
     ok: true;
@@ -452,12 +1056,25 @@ interface BuildServerOptions {
     registry: readonly ToolEntry[];
     backend: BackendClient;
     broker: BrokerClient | undefined;
+    /**
+     * Wave 5 Path D Slice 1 (Commit 3) — bundler client wired through to
+     * `ToolDeps.bundler`. Undefined → Path D autonomous mode off; position
+     * tools stay on Path C deep-link (existing behaviour). Configured from
+     * `MUHAVEN_BUNDLER_URL` env at MCP boot.
+     */
+    bundler?: BundlerClient;
     /**
      * Threaded into `ToolDeps` so the `SESSION_KEY_REQUIRED` payload's
      * `mintUrl` points at the operator's actual dashboard, not a hardcoded
      * production URL.
      */
     dashboardBaseUrl?: string;
+    /** Wave 5 Path D Slice 1 (Commit 3.5) — Arb Sepolia chain id (421614). */
+    chainId?: number;
+    /** Wave 5 Path D Slice 1 (Commit 3.5) — MuHavenSubscription target. */
+    subscriptionAddress?: `0x${string}`;
+    /** Wave 5 Path D Slice 1 (Commit 3.5) — ERC-4337 EntryPoint v0.7 addr. */
+    entryPointAddress?: `0x${string}`;
 }
 declare function buildMcpServer(opts: BuildServerOptions): Server;
 /**
@@ -513,6 +1130,41 @@ interface McpRuntimeConfig {
     allowedBackendHosts: readonly string[];
     /** In-process JWT cache TTL in seconds. Default 30. */
     jwtCacheTtlSec: number;
+    /**
+     * Wave 5 Path D Slice 1 (Commit 3) — ERC-4337 v0.7 bundler JSON-RPC URL.
+     * Undefined → Path D autonomous-buy mode disabled (position tools fall
+     * back to Path C deep-link). Validated via the same https-or-loopback
+     * rule as backend/dashboard URLs.
+     */
+    bundlerUrl: string | undefined;
+    /** Path D request timeout for bundler RPC calls. Default 20s
+     *  (slightly higher than backend default to absorb head-of-line block
+     *  delays). */
+    bundlerTimeoutMs: number;
+    /** Wave 5 Path D — expected chain id (Arb Sepolia = 421614). Sourced
+     *  from env so a future mainnet rollout doesn't require a code change.
+     *  Default 421614. */
+    chainId: number;
+    /**
+     * Wave 5 Path D Slice 1 (Commit 3.5) — the
+     * `MuHavenSubscription.purchase` target the autonomous-buy UserOp
+     * calls into. Undefined → Path D's UserOp build path is disabled
+     * (handler falls back to Path C with reason
+     * `subscription_address_unset`). Lives in env (NOT a contract
+     * deployment lookup) so the MCP package stays free of the deployment
+     * JSON files. Source of truth: `deployments/arb-sepolia-v2.json`
+     * (prod) / `deployments/arb-sepolia-v2.staging.json` (stage) →
+     * `subscription` field.
+     */
+    subscriptionAddress: `0x${string}` | undefined;
+    /**
+     * Wave 5 Path D Slice 1 (Commit 3.5) — ERC-4337 EntryPoint v0.7
+     * address. Defaults to the canonical deployment
+     * `0x0000000071727De22E5E9d8BAf0edAc6f37da032` (same on every EVM
+     * chain). Operators on a future EntryPoint rotation override via
+     * `MUHAVEN_ENTRY_POINT`.
+     */
+    entryPointAddress: `0x${string}`;
 }
 interface BrokerRuntimeConfig {
     /** Endpoint to bind: socket path on POSIX, named pipe name on Windows. */
@@ -661,6 +1313,22 @@ declare class DeviceFlowClient {
 interface ISigner {
     readonly address: `0x${string}`;
     signHash(hash: `0x${string}`): Promise<`0x${string}`>;
+    /**
+     * Wave 5 Path D Slice 1 Commit 3.5 — EIP-191 personal-sign over a
+     * raw 32-byte hash. ZeroDev's permission validator on Kernel v3.1
+     * (via `@zerodev/permissions::signUserOperation`) does
+     * `signer.account.signMessage({ message: { raw: userOpHash } })` —
+     * i.e., it ECDSA-signs `keccak256("\x19Ethereum Signed Message:\n32"
+     * || userOpHash)`, NOT the raw userOpHash. For Path D autonomous
+     * UserOps, the broker MUST sign via this path or the on-chain
+     * `ecrecover` yields a different address → `AA24 InvalidSigner`.
+     *
+     * `signHash` (raw ECDSA over the supplied hash) stays for back-compat
+     * with `sign_hash` IPC verb / Wave 4 placeholder envelope; the new
+     * `signRawMessage` is the verb Path D's `sign_userop` daemon path
+     * calls.
+     */
+    signRawMessage(hash: `0x${string}`): Promise<`0x${string}`>;
 }
 /**
  * Sentinel signer for the read-only daemon posture (no
@@ -678,12 +1346,14 @@ declare const ZERO_ADDRESS: "0x0000000000000000000000000000000000000000";
 declare class NullSigner implements ISigner {
     readonly address: "0x0000000000000000000000000000000000000000";
     signHash(_hash: `0x${string}`): Promise<`0x${string}`>;
+    signRawMessage(_hash: `0x${string}`): Promise<`0x${string}`>;
 }
 declare class ViemSigner implements ISigner {
     private readonly account;
     constructor(privateKey: `0x${string}`);
     get address(): `0x${string}`;
     signHash(hash: `0x${string}`): Promise<`0x${string}`>;
+    signRawMessage(hash: `0x${string}`): Promise<`0x${string}`>;
 }
 
 /**
@@ -739,6 +1409,71 @@ declare function openKeystore(options?: OpenKeystoreOptions): Promise<{
     fallbackReason: string | null;
 }>;
 
+/**
+ * Wave 5 Path D Slice 1 — per-session policy snapshot subsystem for the
+ * broker daemon. Each snapshot describes the rules the broker enforces
+ * BEFORE signing a UserOp: target-contract allowlist, selector allowlist,
+ * per-op amount cap, expiry.
+ *
+ * Persistence model: one JSON file per snapshot under
+ * `~/.muhaven/policy-snapshots/<sessionId>.json`. Atomic writes via
+ * tmp-file + rename (POSIX & Windows). Mode 0600 on POSIX; Windows ACL
+ * is whatever the user's profile dir provides.
+ *
+ * Why a directory not a single keystore record (cf. `keystore.ts` for
+ * the JWT): users can have multiple concurrent scoped sessions
+ * (different surfaces, different tiers), and the broker needs lookup-by-
+ * sessionId during sign_userop. The JWT is a single-tenant record;
+ * snapshots are a multi-record store keyed by sessionId.
+ *
+ * The OS keychain backend is intentionally NOT used here. Keychain APIs
+ * generally hold one value per (service, account) pair and are awkward
+ * for the "list all keys" lookup the doctor command needs. File-only
+ * keeps it simple. Snapshots aren't long-term secrets — they describe
+ * policy, not credentials — so the security posture is "operator
+ * filesystem permissions" not "OS-trust-zone".
+ */
+
+/** Public alias — callers can import either name. */
+type PolicySnapshot = PolicySnapshotWire;
+
+interface IPolicyStore {
+    /** Return the snapshot for `sessionId`, or null if absent OR past
+     *  `validUntilSec`. Callers treat both as "no active snapshot." */
+    get(sessionId: string, nowSec: number): Promise<PolicySnapshot | null>;
+    /** Overwrite any existing record for the snapshot's sessionId. */
+    put(snapshot: PolicySnapshot): Promise<void>;
+    /** Delete the snapshot. No-op when sessionId is absent. */
+    delete(sessionId: string): Promise<void>;
+    /** Return every snapshot in the store (including expired). Used by
+     *  doctor / hello surfaces for diagnostics. NEVER exposed over IPC —
+     *  see RD-3 commentary in PATH_D_PLAN.md and Backend Architect M-4. */
+    list(): Promise<PolicySnapshot[]>;
+    /**
+     * Return the sessionId of the SINGLE non-expired snapshot whose
+     * `signerAddress` (case-insensitive) matches `activeSignerAddress`, or
+     * `null` when zero match OR when 2+ match (ambiguous case). Backs the
+     * narrow `get_active_session_id` IPC verb (Wave 5 Path D Slice 1
+     * Commit 3) — intentionally narrower than `list()` so RD-3 / M-4 stays
+     * honoured (snapshot enumeration never crosses the IPC boundary; only
+     * the unique-id answer does).
+     *
+     * Callers fall back to Path C on null. The "ambiguous" case is a
+     * design choice — operators rotating through scoped sessions
+     * intentionally must clear the prior session before the new one
+     * becomes "active" — so we never auto-pick a winner the operator
+     * didn't ask for.
+     */
+    activeSessionId(activeSignerAddress: `0x${string}`, nowSec: number): Promise<string | null>;
+    /** Optional one-shot async setup. The file-backed impl doesn't need
+     *  this — the dir is created lazily on first put. Slice 5's spend-
+     *  ledger impl will need to seed the SHA-256 chain from disk at boot;
+     *  daemon.start() awaits `policyStore.init?.()` so the seed runs
+     *  before any IPC request. Adding the optional method now avoids a
+     *  refactor when Slice 5 lands (Backend Architect M-1). */
+    init?(): Promise<void>;
+}
+
 /**
  * `muhaven-broker` daemon — the single-purpose process that holds the
  * session-key private half AND the device-flow JWT, exposing only IPC
@@ -766,6 +1501,14 @@ interface BrokerDaemonOptions {
     signer?: ISigner;
     /** Inject a keystore for tests; default opens the configured backend. */
     keystore?: IKeystore;
+    /**
+     * Inject a policy store for tests; defaults to a `FilePolicyStore` rooted
+     * at `~/.muhaven/policy-snapshots/`. The store is consulted by
+     * `sign_userop` (validate before signing) and exposed via the
+     * `store_policy_snapshot` / `get_policy_snapshot` / `clear_policy_snapshot`
+     * verbs added in Wave 5 Path D Slice 1 (protocol 0.4.0).
+     */
+    policyStore?: IPolicyStore;
     /** Override for the connection-handler logger; defaults to silent. */
     logger?: (event: BrokerLogEvent) => void;
 }
@@ -805,13 +1548,14 @@ interface HandleBrokerRequestOptions {
      */
     pid?: number;
 }
-declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions): Promise<BrokerResponse>;
+declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions, policyStore?: IPolicyStore): Promise<BrokerResponse>;
 declare class BrokerDaemon {
     private readonly server;
     private readonly signer;
     private readonly log;
     private readonly config;
     private keystore;
+    private readonly policyStore;
     /**
      * Whether a session-key private half is actually loaded. `false` =
      * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`
@@ -825,4 +1569,4 @@ declare class BrokerDaemon {
     private runAndRespond;
 }
 
-export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type HandleBrokerRequestOptions, type IKeystore, type ISigner, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, MissingSessionKeyError, NoJwtAvailableError, NullSigner, type RunMcpStdioCliOptions, SERVER_VERSION, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, ViemSigner, ZERO_ADDRESS, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, serializeResponse, verifyDescriptorAgainstPin };
+export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, BundlerClient, BundlerClientError, type BundlerClientErrorCode, type BundlerClientOptions, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type HandleBrokerRequestOptions, type IKeystore, type ISigner, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, MissingSessionKeyError, NoJwtAvailableError, NullSigner, type PreflightResult, type RunMcpStdioCliOptions, SERVER_VERSION, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, type UserOperationReceipt, type UserOperationV07Wire, ViemSigner, ZERO_ADDRESS, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, semverGte, serializeResponse, verifyDescriptorAgainstPin };