@muhaven/mcp 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,126 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-05-23
+
+### Added
+
+- **Wave 5 Option D Commit 3 — MCP-side MODE.ENABLE UserOp pipeline.**
+  Closes the `paymaster_rejected → AA23 reverted 0x` smoke gap by
+  installing the PermissionValidator atomically with the first Path D
+  buy. On a freshly-minted Scoped session (`enable_status='pending'`
+  on the backend mirror), `position.buy` now:
+  - Fetches install material (`enableData` + `enableSig` +
+    `validatorNonce`) from the backend's
+    `GET /agent/policy/scoped-session/:id/install-material` subroute,
+    gated by `BROKER_CALLBACK_SERVICE_SECRET`.
+  - Calls the broker daemon's NEW `current_nonce` IPC verb to read the
+    kernel's live `currentNonce()` and pre-checks it against the
+    stored `validatorNonce`; mismatch surfaces as fallback
+    `enable_sig_stale` with a re-mint remediation.
+  - Composes the UserOp with `composeKernelV3NonceKey({mode:'enable'})`
+    (byte 0 of the 24-byte composite flips `0x00` → `0x01`) AND
+    wraps the 66-byte session-key signature with NEW
+    `wrapEnableModeSignature(...)` — a byte-exact mirror of
+    `@zerodev/sdk::getEncodedPluginsData`. The byte-equality is
+    pinned by 5 regression fixtures importing the canonical SDK as a
+    `devDep` (test-only — `@zerodev/sdk` is NOT in the runtime
+    bundle).
+  - After receipt, calls the broker daemon's NEW
+    `notify_userop_landed` IPC verb so the broker can POST the
+    backend's `validator-enabled` callback route. The chain indexer
+    is the authoritative source-of-truth; the callback is a fast-path
+    optimization.
+- **Broker protocol bump 0.4.0 → 0.5.0.** Additive surface only —
+  legacy 0.4.0 callers continue to work. New verbs: `current_nonce`,
+  `notify_userop_landed`. New optional `enableData`/`enableSig`/
+  `validatorNonce` on `PolicySnapshotWire` with an all-or-none
+  refinement. New error codes: `chain_rpc_failed`, `callback_unconfigured`.
+- **Broker daemon outbound egress (narrow, operator-approved
+  threat-model relaxation).** Until C3 the broker had ZERO outbound
+  channels; C3 adds exactly TWO via the NEW `BrokerOutbound` module:
+  - Chain RPC `eth_call` to `MUHAVEN_BROKER_RPC_URL` (fallback
+    `MUHAVEN_BUNDLER_URL`) for `kernel.currentNonce()` reads.
+  - HTTPS POST to backend's `validator-enabled` route with
+    `BROKER_CALLBACK_SERVICE_SECRET` bearer, exponential 5s/15s/60s/5m
+    backoff (`MUHAVEN_BROKER_ORIGIN` header per the ZeroDev
+    allowlist gotcha codified in earlier commits).
+  - Per-(sessionId, txHash, accountAddress) in-process dedup folds
+    flood IPC into a single retry loop.
+- New fallback codes on `position.buy` Path D probe:
+  `install_material_unavailable`, `install_material_malformed`,
+  `enable_sig_stale`, `validator_install_failed_re_walk_required`,
+  `broker_chain_rpc_failed`.
+- New broker config knobs: `MUHAVEN_BROKER_RPC_URL`,
+  `BROKER_CALLBACK_SERVICE_SECRET`, `MUHAVEN_BROKER_ORIGIN`.
+
+### Changed
+
+- `composeKernelV3NonceKey` now accepts a `mode: 'default'|'enable'`
+  parameter. Default-omitted = `'default'` (backwards-compatible
+  with 0.2.x callers).
+- `BackendClient` gains a `getServiceSecret(path, secret, query?)`
+  method (refactored `exchange` to share `runFetch`). Used only by
+  the install-material subroute.
+- `daemon.ts` JSDoc header rewrites the "zero-egress" invariant to
+  document the C3 narrow outbound channels load-bearingly.
+
+### Notes
+
+- 28 files changed, +4029 / -20 LOC.
+- 18 new unit tests (5 byte-equality fixtures + 8 use-case + 6
+  watchdog + 6 indexer + 12 protocol parser + 5 daemon).
+- @muhaven/mcp 0.3.0 publish requires `npm publish` after
+  `pnpm clean && pnpm build && pnpm test`.
+
+## [0.2.9] — 2026-05-23
+
+### Added
+
+- **`pathDDecodedCall` in the position.buy echo on Path D fallback.**
+  When the bundler trace contains a `zd_sponsorUserOperation` event,
+  the handler now decodes the userOp.callData inline and surfaces:
+
+      pathDDecodedCall: {
+        sender: '0x<kernel>',
+        kernelExecuteMode: '0x<32 bytes>',
+        kernelExecuteTarget: '0x<addr>',          // should == MuHavenSubscription
+        kernelExecuteValue: '0',
+        innerSelector: '0xd29b624b',              // purchase(...)
+        innerPurchaseTokenArg: '0x<addr>',        // the RWA token (MuHavenToken)
+        innerPurchaseMaxSharesHint: '14',
+        innerPurchaseEphemeralEOA: '0x<addr>',
+        expectedSubscriptionAddress: '0x<addr>',  // MCP env wiring
+        kernelExecuteTargetMatchesSubscription: true|false,
+        interpretation: 'kernel.execute target matches MuHavenSubscription. ...',
+      }
+
+  Lets the LLM read at-a-glance which contract the kernel was about
+  to call (kernel.execute target) vs which RWA token the inner
+  purchase() carries — the two are commonly confused (the inner
+  purchase's first arg IS the token address, but the kernel.execute
+  target should be the subscription).
+
+  The `interpretation` field branches on three cases:
+    1. target == expected subscription → "shape is correct; AA23 is
+       downstream of validator signature decode; check
+       muhaven.policy.session_key_status."
+    2. target == inner purchase.token → "kernel is dispatching to
+       the token instead of the subscription — code bug."
+    3. Anything else → "unexpected third-address dispatch."
+
+- **`decodeKernelExecuteSingleCall` exported from
+  `clients/kernel-encoder.ts`.** Sibling to the existing encoder;
+  reuses the same KERNEL_EXECUTE_ABI + single-call default mode.
+  Returns `null` on unsupported modes (batch / delegate / try) so
+  the diagnostic emits a clear gap instead of garbage.
+
+- **`scripts/decode-userop-trace.ts`** — standalone CLI that takes
+  the raw `pathDBundlerTrace` JSON via stdin and prints the same
+  decode + cross-check. Useful when triaging against an older MCP
+  version that doesn't ship `pathDDecodedCall`, or for offline
+  analysis from a saved trace.
+
 ## [0.2.8] — 2026-05-23
 
 ### Added