@muhaven/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to `@muhaven/mcp` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-10
+
+First publishable cut. All publish-readiness security must-fixes (H-1 / H-2 /
+H-3 from `MCP_PUBLISH_READINESS.md` §2) and package-hygiene work landed on
+`agenticwave` ahead of the npm publish ceremony. The actual `npm publish` is
+gated on the operator-side `AGENTIC_TEST_PLAN.md` walkthroughs completing.
+
+### Added — Tools (22)
+
+- `muhaven.read.*` (7): `portfolio` · `yields` · `distribution` · `tokens` ·
+  `audit` · `protection_coverage` · `kyc_attestation`
+- `muhaven.position.*` (4): `buy` · `sell` · `claim` · `rebalance`
+- `muhaven.policy.*` (4): `set_tier` · `pause` · `audit_export` ·
+  `session_key_status`
+- `muhaven.issuer.*` (5): `distribute_yield` · `kyc_add` · `kyc_remove` ·
+  `unpause_token` · `audit_query`
+- `muhaven.governance.*` (2): `propose` · `cast_vote` (frontend runner
+  deferred to Wave 5)
+
+### Added — Infrastructure
+
+- MCPB-format `manifest.json` (manifest_version 0.2) declaring four
+  `user_config` entries (`backend_url`, `dashboard_url`, `broker_endpoint`,
+  `read_only`) so MCPB hosts (Claude Desktop, Cursor, future MCPB store) can
+  render install dialogs without the operator hand-editing config files.
+- Companion `muhaven-broker` daemon over Unix socket (POSIX) / named pipe
+  (Windows). Holds the session-key private half; the MCP server never sees
+  the key, only signed UserOps it relays back to the LLM host.
+- OAuth 2.0 Device Authorization Grant flow with scoped JWTs
+  (`mcp.read.*` + `mcp.propose.*`). Replaces paste-JWT UX; mitigates the
+  R-7 lethal-trifecta concern (env-block credential storage).
+- Tool-description SHA-256 hash pinning (`tool-hashes.json` + the
+  `verify-tool-hashes` script). Server startup re-verifies and exits with
+  code `70` (`EX_CONFIG`) on drift; CI gate via the same script with
+  `--check`.
+- `@napi-rs/keyring` integration for the broker's JWT keystore (Windows
+  DPAPI / macOS Security framework / Linux Secret Service via D-Bus) with
+  file-backed fallback (`MUHAVEN_KEYRING=file`) for WSL2 / devcontainer /
+  SSH-remote where Secret Service is absent.
+
+### Security
+
+- Broker isolation: no TCP transport; POSIX socket created at mode `0700`
+  with file mode `0600`; Windows named-pipe ACL inherits user.
+- STDIO-only MCP transport; `mcp-remote` (CVE-2025-6514) banned in README.
+- Position / policy / issuer / governance tools return unsigned UserOps +
+  broker signatures; **never** auto-submit to a bundler.
+- Tool-description hash pinning makes MCPoison-style descriptor-tampering
+  attacks fail-closed (server exits before the LLM sees the drifted text).
+- Workstream A security must-fixes (commit `44bd8b2`):
+  - **H-1**: sourcemaps stripped from publish bundle (`tsup.config.ts`
+    gates on `MUHAVEN_DEV_BUILD=1`). Removes `.js.map` / `.cjs.map` /
+    `.d.ts.map` containing absolute developer paths from npm tarballs.
+  - **H-2**: `package.json` declares `publishConfig.{access:public,
+    registry:https://registry.npmjs.org/, provenance:true}` so a manual
+    `npm publish` from a recovery laptop can't silently publish privately
+    or without provenance.
+  - **H-3**: keystore probe round-trip-parses the OS-keychain value via
+    `parseRecord`. Malformed JSON / wrong-shape JSON / Secret-Service-down
+    each fall back to `FileKeystore` with a discriminated `fallbackReason`.
+    `muhaven-broker doctor` performs a non-destructive sentinel round-trip.
+- Workstream B publint hardening (commit `a01116e`): `exports` map fixed
+  to per-condition `import.types` + `require.types` so TypeScript
+  resolution is honest on both ESM and CJS consumers.
+
+### Tests
+
+- 100 vitest cases (`__tests__/`):
+  - `protocol` (13) — IPC frame codec / JSON-RPC envelope shape
+  - `backend-client` (5) — REST-call shape + error mapping
+  - `descriptions` (7) — descriptor surface drift detection
+  - `jwt-source` (5) — broker-cached JWT lifecycle
+  - `daemon-handler` (7) — IPC method dispatch
+  - `registry` (8) — tool registration invariants
+  - `mcp-redteam` (46) — adversarial inputs against `buildMcpServer` +
+    `InMemoryTransport`
+  - `daemon-lifecycle` (3) — bin shim survives past `runMcpStdioCli`
+    resolution (regression guard against the 2026-05-10 ship-blocker
+    bugs in `bin/*.cjs`)
+  - `keystore` (5) — H-3 OS-keychain probe regression coverage
+  - `build-artifacts` (1) — H-1 publish-bundle map-free assertion
+- Three-way subset gate (`scripts/verify-tool-hashes.ts`) enforces
+  consistency between `src/index.ts` registry, `manifest.json#tools`,
+  and `tool-hashes.json`.
+
+### Known limitations (documented residuals — see SECURITY.md to land in
+Workstream H)
+
+- The MCP package is published WITHOUT a domain-bound icon — manifest's
+  `icon` field was deliberately removed in Workstream B because no asset
+  ships yet. MCPB host install dialogs render the default placeholder.
+  Real amber-gradient icon ships in a Wave 5 follow-up.
+- Listed JSON schemas don't reflect per-tool field hints (L-1 backlog).
+- `BackendClient` errors echo URL pathnames (L-2; recommend host-side
+  scrubbing).
+
+### Distribution
+
+- Published via npm OIDC + Sigstore provenance attestations from the
+  `.github/workflows/mcp-publish.yml` workflow (tag-driven on
+  `mcp-v*`; manual `workflow_dispatch` available for recovery).
+- Tarball + `.sigstore` bundle uploaded as workflow artifacts and as
+  files on the `mcp-v0.1.0` GitHub Release.
+- Verify locally with:
+  ```
+  cosign verify-blob \
+    --bundle muhaven-mcp-0.1.0.tgz.sigstore \
+    --certificate-identity-regexp "^https://github\.com/hasToDev/muhaven/" \
+    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+    muhaven-mcp-0.1.0.tgz
+  ```
+
+[Unreleased]: https://github.com/hasToDev/muhaven/compare/mcp-v0.1.0...HEAD
+[0.1.0]: https://github.com/hasToDev/muhaven/releases/tag/mcp-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hasToDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# `@muhaven/mcp` — MCP server for MuHaven RWA portfolios
+
+Confidential RWA portfolio management on Fhenix CoFHE, exposed as a Model
+Context Protocol server installable in Claude Desktop / Cursor / Claude Code.
+
+## What it does
+
+22 tools across five groups (P3 + P7 + P11):
+
+| Group | Tools | Description |
+|---|---|---|
+| `muhaven.read.*` | `portfolio` · `yields` · `distribution` · `tokens` · `audit` · `protection_coverage` · `kyc_attestation` | Read your encrypted-balance portfolio, yield history, audit log, and P11 governance/KYC state |
+| `muhaven.position.*` | `buy` · `sell` · `claim` · `rebalance` | **Propose** trades — returns unsigned UserOps + broker signature; never auto-submits |
+| `muhaven.policy.*` | `set_tier` · `pause` · `audit_export` · `session_key_status` | Manage the tiered-autonomy state machine |
+| `muhaven.issuer.*` | `distribute_yield` · `kyc_add` · `kyc_remove` · `unpause_token` · `audit_query` | Issuer-side: distribute yield, manage KYC whitelist, NAV-set+unpause, query own audit trail |
+| `muhaven.governance.*` | `propose` · `cast_vote` | P11 encrypted-governance ceremony (cast-vote frontend runner deferred to Wave 5) |
+
+`MUHAVEN_READ_ONLY=true` exposes only the 7 `muhaven.read.*` tools.
+
+## Architecture (one paragraph)
+
+The MCP server runs as an MCPB STDIO subprocess of the host LLM (Claude
+Desktop, Cursor, Claude Code). It speaks HTTPS to the MuHaven backend at
+`https://api.muhaven.app` and IPC to a long-running sibling daemon
+called `muhaven-broker`. The broker holds two secrets — your ZeroDev
+session-key private half (for signing UserOps) and your scoped JWT (for
+authenticating to the backend) — both in your OS keychain. The broker
+NEVER speaks TCP and NEVER reaches out to the network. It exposes one
+signing primitive over a Unix socket (POSIX) or named pipe (Windows).
+This split — network-facing MCP server / signing-only broker — is the
+**lethal-trifecta** mitigation: an attacker who compromises the LLM
+process cannot exfiltrate your key without also compromising a separate
+process running under your user.
+
+The `muhaven-broker login` ceremony uses the OAuth 2.0 Device
+Authorization Grant (RFC 8628) — same shape as `gh auth login --web`,
+`wrangler login`, `gcloud auth login`. You never paste a JWT.
+
+## Install (development)
+
+```bash
+# In the muhaven monorepo, from repo root
+pnpm install
+pnpm --filter @muhaven/mcp build
+```
+
+The `bin/` shims will be invokable as `muhaven-mcp` and `muhaven-broker`
+once the package is linked.
+
+## Setup (end-user, post-MCPB-publish)
+
+1. **Install the MCPB package** in your host (Claude Desktop / Cursor / Claude Code).
+2. **Provision a session key.** This is the private half the broker holds for signing UserOps. The dashboard-side mint UI is a Wave 5 deliverable — until then, generate one yourself:
+   ```bash
+   node -e "console.log('0x' + require('crypto').randomBytes(32).toString('hex'))"
+   ```
+   The corresponding kernel session key install on-chain runs through the dashboard `/agent/policy/transition` flow (one-time per tier). For read-only smokes you can skip the install — the broker only needs the private half to start.
+3. **Start the broker daemon.** Set `MUHAVEN_BROKER_SESSION_KEY=0x…` and run:
+   ```bash
+   muhaven-broker
+   ```
+   Recipes for systemd / launchd / Windows Service in `docs/runbook.md` (TODO).
+4. **Authenticate via device-code flow:**
+   ```bash
+   muhaven-broker login
+   ```
+   The broker prints a URL like `https://muhaven.app/link?code=ABCD-1234` and (when not run with `--no-launch-browser`) opens it. Sign in with your passkey on the dashboard, verify the device fingerprint shown on the `/link` page, click **Authorize**. The CLI exits with success when the JWT lands in your keystore.
+5. **Use any MCP tool** from your host LLM. First call may take a moment as the broker fetches the JWT from the keystore.
+
+> **Windows / WSL2 / devcontainer / SSH-remote operators:** export `MUHAVEN_KEYRING=file` to skip the OS-keychain probe and use the file-backed keystore at `~/.muhaven/jwt` (mode 0600, parent dir mode 0700). The keychain backend depends on `@napi-rs/keyring` which needs platform-specific build prerequisites; the file fallback works everywhere.
+
+## Hardening invariants (`THREAT_MODEL_P0.md` aligned)
+
+- **Transport is STDIO + Unix-socket only.** The MCP server's `StdioServerTransport` is the only transport mounted; the broker's IPC is a Unix socket on POSIX (parent dir mode `0700`, socket file mode `0600`) or a per-user named pipe on Windows. **Never bind TCP.**
+- **`mcp-remote` is banned.** CVE-2025-6514 disclosed an arbitrary-command-execution path through that proxy. Do not use it; do not set `MUHAVEN_BACKEND_URL` to anything that wraps it.
+- **`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1`** is recommended in your shell rc when running Claude Code locally — it prevents inherited env vars from leaking into the MCP subprocess. The MCP package's `MUHAVEN_*` env vars are read at boot, but adopting the scrub habit limits collateral exposure.
+- **Tool descriptions are pinned** at build time in `tool-hashes.json`. The server exits with code 70 (`EX_CONFIG`) on startup if the live descriptors don't match the pinned hashes — defends against tool-description-poisoning patches per the mcp-context-protector pattern (post-MCPoison, March 2026).
+- **Position tools never auto-submit.** They return an unsigned UserOp envelope plus a broker signature. The host LLM is expected to present this to the user for explicit confirmation before bundler submission. The MCP server does not speak to any bundler.
+
+## Environment variables
+
+| Var | Required | Default | Purpose |
+|---|---|---|---|
+| `MUHAVEN_BACKEND_URL` | no | `https://api.muhaven.app` | Backend host. Use staging URL for development. |
+| `MUHAVEN_DASHBOARD_URL` | no | `https://muhaven.app` | Dashboard origin used for the `/link` URL. |
+| `MUHAVEN_BROKER_ENDPOINT` | no | `~/.muhaven/broker.sock` (POSIX) / `\\.\pipe\muhaven-broker-<user>` (Windows) | IPC path. Set if running multiple isolated brokers. |
+| `MUHAVEN_BROKER_SESSION_KEY` | **yes** (broker) | — | 0x-prefixed 32-byte hex; the session-key private half. |
+| `MUHAVEN_READ_ONLY` | no | `false` | When `true`, only `muhaven.read.*` tools are registered. |
+| `MUHAVEN_KEYRING` | no | auto | Set to `file` to force the file-backed keystore (required on WSL2 / devcontainer / SSH-remote). |
+| `MUHAVEN_REQUEST_TIMEOUT_MS` | no | `15000` | Backend HTTP timeout. |
+| `MUHAVEN_BROKER_TIMEOUT_MS` | no | `5000` | Broker IPC timeout. |
+| `MUHAVEN_JWT_CACHE_TTL_SEC` | no | `30` | In-process JWT cache TTL. |
+| `MUHAVEN_BROKER_MAX_BYTES` | no | `65536` | Per-request payload cap on the broker IPC. |
+
+The MCPB `manifest.json` declares the user-facing subset (`backend_url`, `dashboard_url`, `broker_endpoint`, `read_only`); the host's secret manager handles the values.
+
+## CLI subcommands (`muhaven-broker`)
+
+| Command | Effect |
+|---|---|
+| (none) | Run the daemon (production mode). |
+| `muhaven-broker login [--no-launch-browser]` | Run the device-code ceremony; on success store the JWT in the keystore. |
+| `muhaven-broker logout` | Clear the JWT from the keystore. |
+| `muhaven-broker doctor` | Print environment + keystore + reachability report. |
+
+## Threat model in 30 seconds
+
+Per `development/DEV_WAVE_4/THREAT_MODEL_P0.md`:
+
+| Risk | Control |
+|---|---|
+| **R-1** Prompt injection escalating into a tx | Position tools return *unsigned* UserOps; host MUST present to user for explicit passkey confirmation. |
+| **R-2** Hallucinated tool call | Strict-enum tool registry + `additionalProperties: false` Zod schemas. |
+| **R-3** Replay of confirmation tokens | Single-use server-side nonced tokens via existing P1 confirm-token-service. |
+| **R-6** ZeroDev session-key escape | Session key lives in broker keystore (OS keychain) — never in the LLM-process env. |
+| **R-7** MCP env-block exfiltration | MCPB `sensitive: true` for secrets → OS keychain; broker isolation; no plaintext disk. |
+| **R-8** FHE ACL bypass | Backend enforces every read; MCP server never decrypts FHE handles. |
+
+## License
+
+MIT
+
+## Status: `0.1.0` — first publish-ready cut
+
+Wave 4 Phase P3 deliverable per `development/DEV_WAVE_4/PROGRESS.md`. Workstreams A–D of the npm-publish ceremony (security must-fixes, `package.json` hygiene, `LICENSE` + `CHANGELOG`, GitHub Actions workflows) are landed on `agenticwave`; the actual `npm publish` is operator-driven via the tag-push of `mcp-v0.1.0` against the `npm-publish` GitHub Environment (2-reviewer gate · OIDC trusted-publishing · Sigstore provenance). See `development/DEV_WAVE_4/MCP_PUBLISH_READINESS.md` §6 for the operator runbook.

package/bin/muhaven-broker.cjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/* eslint-disable */
+const { runCli } = require('../dist/broker.cjs');
+
+runCli(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`fatal: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.exit(1);
+  },
+);

package/bin/muhaven-mcp.cjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/* eslint-disable */
+const { runMcpStdioCli } = require('../dist/index.cjs');
+
+runMcpStdioCli().then(
+  () => process.exit(0),
+  (err) => {
+    process.stderr.write(`fatal: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.exit(1);
+  },
+);