@muhaven/mcp 0.2.8 → 0.3.0

package/dist/index.d.cts

@@ -9,9 +9,46 @@ 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.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:
+ * **Protocol version 0.5.0** — additive bump from 0.4.0 for Wave 5
+ * Option D Commit 3. Adds the PermissionValidator install lifecycle so
+ * the broker can compose a MODE.ENABLE UserOp on the first Path D buy
+ * after a freshly-minted Scoped session (installs the validator on-chain
+ * atomically with the inner call). Three additive surfaces:
+ *  - `current_nonce` — read-side IPC verb. Broker does `eth_call` against
+ *    the kernel's `currentNonce()` view via its configured chain RPC.
+ *    MCP server compares the returned uint32 with the mirror's stored
+ *    `validatorNonce`; mismatch surfaces as fallback `enable_sig_stale`
+ *    (kernel nonce drifted between mint + first buy → stored enableSig
+ *    is over a stale typed-data digest).
+ *  - `notify_userop_landed` — write-side IPC verb. MCP server invokes
+ *    this after receipt-arrival to hand the broker the on-chain
+ *    `PermissionInstalled` receipt details. Broker posts the receipt
+ *    to the backend's `validator-enabled` route over its configured
+ *    HTTPS egress (R2 design call: broker carries
+ *    `BROKER_CALLBACK_SERVICE_SECRET`; MCP carries the bundler + RPC
+ *    URLs only). Exponential backoff retry 5s/15s/60s/5m, max 1h.
+ *    The backend chain indexer is the authoritative source-of-truth
+ *    (subscribes to `PermissionInstalled` events independently); this
+ *    callback is the fast-path optimization.
+ *  - `PolicySnapshotWire` gains optional `enableData`, `enableSig`, and
+ *    `validatorNonce`. Backwards-compatible: snapshots without these
+ *    are treated as already-enabled validator (the legacy posture
+ *    before C3). New snapshots from C2+ frontends carry all three;
+ *    broker plumbs them through to the MCP for the MODE.ENABLE wrap.
+ *
+ * **Threat-model relaxation (R2 design call)**: in C3 the broker gains
+ * limited outbound egress (chain RPC `eth_call` + HTTPS to the
+ * backend's `validator-enabled` route). The original zero-egress
+ * invariant (lethal-trifecta split) is narrowed: the broker still
+ * holds NO read-side secrets the network peer cares about (the chain
+ * RPC is public; the backend callback is gated on a shared secret the
+ * broker holds + asserts in-bound). Documented in
+ * `development/DEV_WAVE_5/DEV_LOG.md` C3 entry as a load-bearing
+ * decision the operator made at handoff.
+ *
+ * **Protocol version 0.4.0** (history) — 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
@@ -75,7 +112,7 @@ import { z } from 'zod';
  *  - Requests are size-capped (`maxRequestBytes`) — a malformed peer
  *    cannot exhaust broker memory by sending an unbounded JSON blob.
  */
-declare const BROKER_PROTOCOL_VERSION = "0.4.0";
+declare const BROKER_PROTOCOL_VERSION = "0.5.0";
 interface BrokerHelloRequest {
     readonly type: 'hello';
 }
@@ -171,6 +208,60 @@ interface BrokerClearPolicySnapshotRequest {
 interface BrokerGetActiveSessionIdRequest {
     readonly type: 'get_active_session_id';
 }
+/**
+ * Wave 5 Option D Commit 3 — read the kernel's `currentNonce()` view
+ * via the broker's chain RPC. The MCP server uses this to gate the
+ * MODE.ENABLE composition path: mirror's stored `validatorNonce` must
+ * still match the on-chain nonce (the enableSig was signed over the
+ * typed-data digest that pinned the nonce; if the kernel's nonce has
+ * advanced since mint, the digest no longer matches and the on-chain
+ * validator rejects the install).
+ *
+ * Returns a uint32. Broker daemon enforces the range; MCP-side caller
+ * compares to the mirror's stored value as a numeric equality check.
+ */
+interface BrokerCurrentNonceRequest {
+    readonly type: 'current_nonce';
+    /** Kernel/smart-account address. The kernel's `currentNonce()` is
+     *  a view-only method on the account itself (not the EntryPoint). */
+    readonly accountAddress: `0x${string}`;
+}
+/**
+ * Wave 5 Option D Commit 3 — MCP server notifies broker that a
+ * MODE.ENABLE UserOp has settled on-chain. Broker forwards the receipt
+ * to the backend's `validator-enabled` route over HTTPS (using its
+ * pre-configured `BROKER_CALLBACK_SERVICE_SECRET` + `BROKER_BACKEND_BASE_URL`).
+ *
+ * The IPC return is FIRE-AND-FORGET: the broker queues the callback +
+ * acks immediately. The retry loop (5s/15s/60s/5m, max 1h)
+ * runs in the broker's background; failures are operator-visible via
+ * the daemon's log channel only (the MCP server does not block on
+ * the broker's egress).
+ *
+ * Idempotent on the chain-indexer side — the backend route re-verifies
+ * the receipt; the chain indexer is the authoritative source of truth.
+ */
+interface BrokerNotifyUseropLandedRequest {
+    readonly type: 'notify_userop_landed';
+    readonly sessionId: string;
+    /** Address of the kernel that owns the installed PermissionValidator.
+     *  Backend uses (account_address, permission_id) to look up the mirror
+     *  row to flip. */
+    readonly accountAddress: `0x${string}`;
+    /** 0x-prefixed 4-byte permissionId, lower-cased. */
+    readonly permissionId: `0x${string}`;
+    /** Tx hash carrying the install. Backend re-verifies via
+     *  `eth_getTransactionReceipt` before flipping the enum. */
+    readonly txHash: `0x${string}`;
+    /** Block number containing the receipt — telemetry / forensics. */
+    readonly blockNumber: number;
+    /** Log index of the matched `SelectorSet` install event within the
+     *  tx's logs array. INFORMATIONAL only — the backend re-scans the FULL
+     *  receipt and matches by permissionId, so a wrong/0 logIndex is
+     *  harmless (the deployed kernel emits `SelectorSet`, not
+     *  `PermissionInstalled`, for enable-mode installs). */
+    readonly logIndex: number;
+}
 /**
  * Per-selector enforcement rule. The broker matches `innerCall`'s
  * selector against `selector`, then — if `capArgIndex` is not null —
@@ -274,6 +365,31 @@ interface PolicySnapshotWire {
      * (additive optional field, no protocol version bump).
      */
     readonly permissionId?: `0x${string}`;
+    /**
+     * Wave 5 Option D Commit 3 — install material for the MODE.ENABLE
+     * UserOp. `enableData` is the validator-install payload built by the
+     * frontend at mint time (`permissionValidator.getEnableData(...)`).
+     * Variable size — real-world Wave 5 policy sets produce ~30KB hex.
+     * Optional in the wire shape; absence = treat as already-enabled
+     * (legacy posture; MCP composes MODE.DEFAULT directly).
+     */
+    readonly enableData?: `0x${string}`;
+    /**
+     * Wave 5 Option D Commit 3 — WebAuthn-shaped passkey signature over
+     * `getPluginsEnableTypedData(...)`. 256-1024 bytes hex; ZeroDev's
+     * passkey-validator emits a structured envelope (NOT a bare 65-byte
+     * ECDSA). Optional; paired with `enableData` (both present or both
+     * absent — broker daemon enforces; see `parsePolicySnapshot`).
+     */
+    readonly enableSig?: `0x${string}`;
+    /**
+     * Wave 5 Option D Commit 3 — `currentNonce()` value the kernel
+     * returned at mint time. The MCP server's broker pre-check compares
+     * this to the LIVE on-chain nonce (via the broker's new
+     * `current_nonce` IPC verb) — mismatch surfaces as fallback
+     * `enable_sig_stale`. Optional; uint32 range.
+     */
+    readonly validatorNonce?: number;
 }
 interface BrokerHelloResponse {
     readonly type: 'hello';
@@ -371,14 +487,39 @@ interface BrokerGetActiveSessionIdResponse {
      *  in either case. */
     readonly sessionId: string | null;
 }
+interface BrokerCurrentNonceResponse {
+    readonly type: 'current_nonce';
+    /** uint32 returned by the kernel's `currentNonce()` view. */
+    readonly nonce: number;
+    /** Mirror of the request — defends against the broker accidentally
+     *  serving a cached response for a different account. The caller
+     *  compares this to its request input before trusting `nonce`. */
+    readonly accountAddress: `0x${string}`;
+}
+interface BrokerNotifyUseropLandedResponse {
+    readonly type: 'notify_userop_landed';
+    /** Always `true` once the callback is queued. The broker queues
+     *  fire-and-forget; failures surface in the broker's log channel
+     *  only. */
+    readonly queued: true;
+    readonly sessionId: string;
+}
 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' | '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;
+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'
+/** Broker's chain RPC `eth_call` failed (network, malformed reply,
+ *  RPC error). MCP-side caller falls back to Path C with a clear
+ *  "broker chain RPC unreachable" remediation message. */
+ | 'chain_rpc_failed'
+/** Broker hasn't been configured with the callback secret or backend
+ *  base URL — `notify_userop_landed` is a no-op IPC verb in this
+ *  posture (the chain indexer remains the safety net). */
+ | 'callback_unconfigured';
+type BrokerRequest = BrokerHelloRequest | BrokerSignHashRequest | BrokerStoreJwtRequest | BrokerGetJwtRequest | BrokerClearJwtRequest | BrokerSignUserOpRequest | BrokerStorePolicySnapshotRequest | BrokerGetPolicySnapshotRequest | BrokerClearPolicySnapshotRequest | BrokerGetActiveSessionIdRequest | BrokerCurrentNonceRequest | BrokerNotifyUseropLandedRequest;
+type BrokerResponse = BrokerHelloResponse | BrokerSignHashResponse | BrokerStoreJwtResponse | BrokerGetJwtResponse | BrokerClearJwtResponse | BrokerSignUserOpResponse | BrokerStorePolicySnapshotResponse | BrokerGetPolicySnapshotResponse | BrokerClearPolicySnapshotResponse | BrokerGetActiveSessionIdResponse | BrokerCurrentNonceResponse | BrokerNotifyUseropLandedResponse | BrokerErrorResponse;
 /**
  * Parse a single-line request payload. Returns either the validated
  * request or a structured error — the daemon converts errors to a
@@ -508,6 +649,15 @@ declare class BrokerClient {
     getPolicySnapshot(sessionId: string): Promise<BrokerGetPolicySnapshotResponse>;
     clearPolicySnapshot(sessionId: string): Promise<BrokerClearPolicySnapshotResponse>;
     getActiveSessionId(): Promise<BrokerGetActiveSessionIdResponse>;
+    currentNonce(accountAddress: `0x${string}`): Promise<BrokerCurrentNonceResponse>;
+    notifyUseropLanded(args: {
+        sessionId: string;
+        accountAddress: `0x${string}`;
+        permissionId: `0x${string}`;
+        txHash: `0x${string}`;
+        blockNumber: number;
+        logIndex: number;
+    }): Promise<BrokerNotifyUseropLandedResponse>;
     /**
      * Detect whether the running daemon speaks Path D (protocol 0.4.0+).
      * Wraps `hello()` with a semver-gte comparison so the MCP tool layer
@@ -618,6 +768,7 @@ declare class BackendClient {
     private buildUrl;
     private exchangeWithRetry;
     private exchange;
+    private runFetch;
 }
 
 /**
@@ -1275,6 +1426,38 @@ interface BrokerRuntimeConfig {
     backendBaseUrl: string;
     /** Effective dashboard URL paired with backendBaseUrl. */
     dashboardBaseUrl: string;
+    /**
+     * Wave 5 Option D Commit 3 — chain RPC URL the broker uses to read
+     * `kernel.currentNonce()` via `eth_call` during the MODE.ENABLE
+     * pre-check. Optional: when undefined, `current_nonce` IPC returns
+     * `chain_rpc_failed`. Defaults from `MUHAVEN_BROKER_RPC_URL` (broker-
+     * specific) with fallback to `MUHAVEN_BUNDLER_URL` (shared with the
+     * MCP server; ZeroDev bundlers also serve `eth_call`). Operator can
+     * pin a dedicated read-only RPC via `MUHAVEN_BROKER_RPC_URL` to keep
+     * the broker's egress surface narrower than the MCP server's.
+     *
+     * NOTE: this is the first network-egress capability the broker has
+     * been given — see protocol.ts JSDoc on the threat-model relaxation.
+     */
+    chainRpcUrl?: string;
+    /**
+     * Wave 5 Option D Commit 3 — service secret the broker uses to POST
+     * to the backend's `validator-enabled` route. Optional: when
+     * undefined, `notify_userop_landed` returns `callback_unconfigured`
+     * (chain indexer is still the authoritative safety net).
+     *
+     * Sourced from `BROKER_CALLBACK_SERVICE_SECRET`. Held by the broker
+     * (not the MCP server) to keep the secret outside the LLM-controlled
+     * subprocess.
+     */
+    callbackServiceSecret?: string;
+    /**
+     * Wave 5 Option D Commit 3 — `Origin` header the broker stamps on
+     * outbound bundler / RPC calls. ZeroDev bundlers reject bare Node
+     * fetches with 403 (per [[feedback-zerodev-bundler-origin-header]]).
+     * Defaults to `dashboardBaseUrl`.
+     */
+    outboundOriginHeader?: string;
 }
 /**
  * Compute the default IPC endpoint for the broker. POSIX: a socket file
@@ -1560,17 +1743,114 @@ interface IPolicyStore {
     init?(): Promise<void>;
 }
 
+interface OutboundConfig {
+    readonly chainRpcUrl?: string;
+    readonly backendBaseUrl: string;
+    readonly callbackServiceSecret?: string;
+    /** Origin header stamped on outbound bundler / RPC calls. */
+    readonly outboundOriginHeader: string;
+    /** Per-fetch timeout in ms. Defaults to 15s. */
+    readonly fetchTimeoutMs?: number;
+    /**
+     * Injectable fetch impl for tests. Defaults to global `fetch`. The
+     * shape matches the standard Fetch API — no node-specific quirks.
+     */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * Setter/clearer for the retry timer. Tests inject a fake-timer
+     * pair so they can advance virtual time without `await new
+     * Promise(setTimeout)`. Production passes Node's globals.
+     */
+    readonly setTimeout?: typeof setTimeout;
+    readonly clearTimeout?: typeof clearTimeout;
+}
+declare class BrokerOutbound {
+    private readonly config;
+    private readonly log;
+    private readonly fetchImpl;
+    private readonly fetchTimeoutMs;
+    private readonly setTimeoutImpl;
+    private readonly clearTimeoutImpl;
+    /**
+     * Wave 5 Option D Commit 3 (multi-agent review SecEng-MED-3) —
+     * in-process dedup of `notify_userop_landed` callbacks. Map of
+     * `<sessionId>:<txHash>` → the in-flight retry loop's Promise.
+     * Repeated IPC calls with the same key fold into the existing
+     * loop instead of spawning a parallel POST. Defends against a
+     * local-socket peer flooding the broker with replay attempts +
+     * caps the retry-budget waste at one loop per real install.
+     */
+    private readonly inflightCallbacks;
+    constructor(config: OutboundConfig, log?: (level: 'info' | 'warn' | 'error', msg: string, meta?: Record<string, unknown>) => void);
+    /**
+     * Read the kernel's `currentNonce()` view via `eth_call` against the
+     * configured chain RPC. Returns a uint32. Throws `ChainRpcError` when
+     * unconfigured / network failed / RPC returned non-decodable bytes.
+     */
+    currentNonce(accountAddress: `0x${string}`): Promise<number>;
+    /**
+     * Whether the callback path is wired (both secret + backend URL set).
+     * The `notify_userop_landed` daemon handler checks this and returns
+     * `callback_unconfigured` when false so the operator sees the gap.
+     */
+    isCallbackConfigured(): boolean;
+    /**
+     * Queue a `validator-enabled` callback POST to the backend. Returns
+     * immediately; the retry loop runs in the background (5s / 15s / 60s
+     * / 5m, max 1h elapsed). Failures are logged but do NOT propagate to
+     * the IPC caller — the chain indexer is the authoritative safety
+     * net.
+     *
+     * Idempotency: every POST carries an `Idempotency-Key` header
+     * `<sessionId>:validator-enabled`. The backend route is no-op if the
+     * mirror row's `enable_status` is already `'enabled'` (because the
+     * chain indexer raced ahead).
+     *
+     * Returns a Promise resolved when the loop terminates (success or
+     * max-elapsed). Callers don't need to await; tests use it for
+     * deterministic assertions.
+     */
+    enqueueValidatorEnabledCallback(args: {
+        readonly sessionId: string;
+        readonly userId?: string;
+        readonly accountAddress: `0x${string}`;
+        readonly permissionId: `0x${string}`;
+        readonly txHash: `0x${string}`;
+        readonly blockNumber: number;
+        readonly logIndex: number;
+    }): Promise<{
+        ok: boolean;
+        attempts: number;
+        lastError?: string;
+    }>;
+    private runCallbackLoop;
+    private postCallback;
+    private sleep;
+}
+
 /**
  * `muhaven-broker` daemon — the single-purpose process that holds the
- * session-key private half AND the device-flow JWT, exposing only IPC
- * primitives for `sign_hash` + `store_jwt` / `get_jwt` / `clear_jwt`.
+ * session-key private half AND the device-flow JWT, exposing IPC
+ * primitives for `sign_hash` + `store_jwt` / `get_jwt` / `clear_jwt` +
+ * the Wave 5 Path D policy + UserOp signing surface.
  *
  * Design constraints (ranked):
  *  1. Never speak TCP. Reachable only via local socket / named pipe.
- *  2. Never reach out to the network. No fetch, no RPC, no bundler —
- *     even after ADR-3 the broker remains zero-egress; the *MCP server*
- *     speaks HTTPS to the backend and hands the JWT to the broker for
- *     storage via `store_jwt`.
+ *  2. **Outbound network egress is NARROW (Wave 5 Option D Commit 3
+ *     relaxation, operator-approved at handoff)**. The broker has
+ *     EXACTLY two outbound channels — both via the `BrokerOutbound`
+ *     module (`./outbound.ts`):
+ *       (a) chain RPC `eth_call` to the configured `MUHAVEN_BROKER_RPC_URL`
+ *           (fallback `MUHAVEN_BUNDLER_URL`) for `kernel.currentNonce()`
+ *           reads, gating the MODE.ENABLE pre-check;
+ *       (b) HTTPS POST to the backend's `validator-enabled` route,
+ *           gated by `BROKER_CALLBACK_SERVICE_SECRET`.
+ *     NO other outbound capability. NO bundler `eth_sendUserOperation`,
+ *     NO `eth_call` against non-`currentNonce` selectors, NO non-
+ *     backend HTTPS destinations. The JWT keystore + the IPC-mediated
+ *     `sign_hash` / `sign_userop` paths remain zero-egress.
+ *     See `./protocol.ts` JSDoc (top) for the threat-model rationale
+ *     + `./outbound.ts` JSDoc (top) for the per-channel contracts.
  *  3. Peer access is enforced by filesystem permissions on POSIX (parent
  *     dir 0700 / socket file 0600). Windows named pipe inherits the
  *     creating user's ACL by default.
@@ -1595,6 +1875,12 @@ interface BrokerDaemonOptions {
      * verbs added in Wave 5 Path D Slice 1 (protocol 0.4.0).
      */
     policyStore?: IPolicyStore;
+    /**
+     * Wave 5 Option D Commit 3 — inject the outbound module for tests.
+     * Production builds one from `config.chainRpcUrl` +
+     * `config.callbackServiceSecret` at constructor time.
+     */
+    outbound?: BrokerOutbound;
     /** Override for the connection-handler logger; defaults to silent. */
     logger?: (event: BrokerLogEvent) => void;
 }
@@ -1634,7 +1920,7 @@ interface HandleBrokerRequestOptions {
      */
     pid?: number;
 }
-declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions, policyStore?: IPolicyStore): Promise<BrokerResponse>;
+declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions, policyStore?: IPolicyStore, outbound?: BrokerOutbound): Promise<BrokerResponse>;
 declare class BrokerDaemon {
     private readonly server;
     private readonly signer;
@@ -1642,6 +1928,7 @@ declare class BrokerDaemon {
     private readonly config;
     private keystore;
     private readonly policyStore;
+    private readonly outbound;
     /**
      * Whether a session-key private half is actually loaded. `false` =
      * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`