@muhaven/mcp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -7,6 +7,205 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-05-17
+
+Adds the one-shot `muhaven-broker setup` subcommand so a fresh install
+goes from `npm install -g @muhaven/mcp` straight to a working MCP host
+in two commands. Surfaced during the Wave 4 demo-recording prep — the
+prior five-line manual ritual (env exports + session-key mint +
+background daemon + login) was the longest opaque block in the demo
+script. Also adds `--version` / `--help` to both `muhaven-broker` and
+`muhaven-mcp` bins.
+
+### Added
+
+- **`muhaven-broker setup` subcommand** — orchestrates env defaulting +
+  session-key minting + detached daemon spawn + login in a single
+  invocation. Flags:
+  - `--foreground` / `-f`: keep the daemon attached to the current
+    shell (useful when systemd/launchd will supervise instead of the
+    backgrounded child).
+  - `--skip-login`: spawn the daemon but defer the device-code flow.
+  - `--no-launch-browser`: pass-through to the embedded `login` step.
+  - `--broker-endpoint`, `--backend-base-url`, `--dashboard-base-url`:
+    same overrides as `login`.
+
+  Env defaults applied (only when the var is unset):
+  - `MUHAVEN_BACKEND_URL=https://api.muhaven.app`
+  - `MUHAVEN_DASHBOARD_URL=https://muhaven.app`
+  - `MUHAVEN_KEYRING=file` (auto-applied on Windows / WSL2 /
+    devcontainer / GitHub Codespace / SSH — same heuristic as
+    `muhaven-broker doctor`'s environment detector). Native macOS +
+    Linux desktop leave the value unset so the OS keychain remains
+    the default.
+
+  Idempotent: re-running `setup` against an already-up daemon detects
+  the existing JWT and short-circuits to `Login: skipped — JWT already
+  in keystore.`. Against a daemon that's up but unauthenticated, it
+  skips the spawn and only runs the login step.
+
+  Closing summary always surfaces the broker endpoint and a
+  platform-specific "Stop daemon" command (`kill <pid>` on POSIX,
+  `Stop-Process -Id <pid>` on Windows). Sign-out is explicitly
+  documented as separate from daemon shutdown — `muhaven-broker logout`
+  clears the JWT but leaves the daemon running.
+
+- **`muhaven-broker --version` / `-v`** — prints `muhaven-broker
+  @muhaven/mcp@<version>` and exits 0. Wired into the dispatcher
+  alongside the existing `--help` / `-h`. Reads the package version
+  from the tsup-injected `__SERVER_VERSION__` constant.
+
+- **`muhaven-mcp --version` / `-v` and `--help` / `-h`** — bin shim
+  short-circuits before requiring `dist/index.cjs`, so the flags exit
+  cleanly without spinning up the broker IPC + tool registry. Reads
+  the version from the sibling `package.json` directly.
+
+### Security
+
+- **Session key never lands in `process.env`** — the orchestrator
+  builds a local `effectiveEnv` snapshot and passes the minted
+  session key only to the spawned daemon's env. Prior version
+  mutated `process.env.MUHAVEN_BROKER_SESSION_KEY` so any subsequent
+  child of the operator's shell would inherit the key. Foreground
+  mode brackets its required `process.env` mutation in a try/finally
+  that restores the original values on exit.
+
+- **Spawned daemon strips `NODE_OPTIONS` / `NODE_TLS_REJECT_UNAUTHORIZED`
+  / `NODE_EXTRA_CA_CERTS` / `NODE_PATH`** from inherited env so a
+  same-user attacker who set those in the operator's shell can't
+  hijack the daemon's execution to exfiltrate the session key.
+
+- **URL flag validation** — `--backend-base-url` / `--dashboard-base-url`
+  must be `https://` (with `http://localhost` / `127.0.0.1` /
+  `[::1]` dev carve-out). Rejects `javascript:`, `file:`, `data:`,
+  and plain `http:` to non-loopback BEFORE the spawn — defense
+  against the OAuth-device-flow phishing vector where a malicious
+  `--backend-base-url` would ship the JWT to an attacker host.
+
+- **`--broker-endpoint` path validation** — must be a `\\.\pipe\…`
+  path on Windows or an absolute path on POSIX. Rejects relative
+  paths + flag-injection (e.g. `--broker-endpoint --from-daemon` is
+  parsed but rejected at validation, preventing the spawned daemon
+  from being bound to an attacker-controlled location).
+
+- **Preserved env values not echoed** — `Env preserved: NAME (set in
+  your shell)` only — values stay opaque. Prior version printed
+  `Env preserved: NAME=value` which would leak operator-supplied
+  values to shell history / CI logs.
+
+- **Session key minted via viem's `generatePrivateKey`** — guarantees
+  the result is in the valid secp256k1 scalar range. Prior version
+  used raw `crypto.randomBytes(32)`, which had a (negligible but
+  nonzero) probability of returning an out-of-range value that the
+  signer would reject as invalid much later in the flow.
+
+- **Bin path resolved via `__dirname`** — `resolveBrokerBinPath` walks
+  from the bundled `dist/broker.cjs` to the sibling
+  `bin/muhaven-broker.cjs` deterministically, so Windows global-npm
+  shim wrappers (`.cmd` / `.ps1` in `process.argv[1]`) don't end up
+  as the spawn target.
+
+- **`detectMcpHost` no longer falls through to `npm_lifecycle_event`**
+  — that var is the npm script name, not an MCP-host identity. The
+  device-flow `/link` page's "requesting client" panel would have
+  displayed "setup" for operators running via `npm run setup`,
+  misleading the passkey ceremony.
+
+### Tests
+
+- 197 vitest pass (up from 134 in 0.1.3). Net +58 cases in
+  `__tests__/setup.test.ts` (+22 over the initial +36 after the
+  parallel agent security review) + 5 in `__tests__/cli-version-flag.test.ts`:
+  - **+10** `applyEnvDefaults` — defaults applied on empty env;
+    backend/dashboard preserved when set; KEYRING auto-applied on
+    win32/WSL2/SSH/devcontainer/Codespaces; left unset on native
+    macOS/Linux desktop; explicit `MUHAVEN_KEYRING=os` preserved on
+    Windows; empty-string vars treated as unset.
+  - **+2** `mintSessionKey` — 0x-prefixed 32-byte hex shape;
+    non-deterministic across calls.
+  - **+3** `decideSetupAction` — spawn-and-login / login-only /
+    already-ready decision tree.
+  - **+6** `parseSetupFlags` — defaults; `--foreground` and `-f`
+    aliases; `--skip-login`; `--no-launch-browser` pass-through; value
+    flag parsing; unknown-flag rejection.
+  - **+3** `waitForBroker` — first-call success; retry-until-success
+    with virtual clock; timeout throws with last error in message.
+  - **+12** `runSetup` orchestrator — flag-error path returns 2;
+    foreground mode short-circuits; spawn_and_login happy path;
+    login_only path; already_ready path; `--skip-login`; login-failure
+    bubbles exit code + leaves daemon running; wait timeout returns 1;
+    `--no-launch-browser` pass-through; value-flag pass-through;
+    session key minted vs preserved.
+
+## [0.1.3] — 2026-05-16
+
+Q2 fix bundle from the post-§4 queue closing four findings from §3e⁶
+(broker-session-key-required-for-reads, broker-env-divergence,
+mcp-serverinfo-version-stale) and unblocking the openclaw-skill ClawScan
+fix (the `noExternal: ['@muhaven/mcp']` inline bundle requires this
+version on npm before the skill can be republished).
+
+### Added
+
+- **Read-only daemon posture**: the broker daemon now boots WITHOUT
+  `MUHAVEN_BROKER_SESSION_KEY`. In that mode the daemon still serves
+  `hello` + the JWT verbs (so `muhaven.read.*` tools work end-to-end via
+  the standalone `@muhaven/mcp` install), but any `sign_hash` request
+  returns the new `session_key_unavailable` broker error so write paths
+  fail with a clear remediation message instead of the daemon dying at
+  startup. Closes §3e⁶ F-broker-session-key-required-for-reads.
+- **`muhaven-broker login --from-daemon` flag**: resolves backend +
+  dashboard URLs from the running daemon's `hello.effectiveConfig`
+  rather than the login CLI's env. Solves the daemon-vs-CLI env-divergence
+  problem when the two processes inherit different shell environments
+  (e.g. the daemon was launched by systemd/launchd, the CLI by ssh).
+  Mutually exclusive with explicit `--backend-base-url` /
+  `--dashboard-base-url`. Closes §3e⁶ F-broker-env-divergence.
+- **`muhaven-broker doctor` surfaces the daemon's effective config**
+  and read-only-posture status — the operator can verify which backend
+  URL is actually in play before driving a login.
+
+### Changed
+
+- **Broker protocol bumped 0.2.0 → 0.3.0** (additive — pre-0.3.0 clients
+  remain compatible):
+  - `hello.hasSessionKey` (optional `boolean`) — absence implies `true`
+    for back-compat.
+  - `hello.effectiveConfig` (optional `{ backendBaseUrl, dashboardBaseUrl }`).
+  - New `session_key_unavailable` broker error code.
+- **`serverInfo.version`** in the MCP server's `initialize` response is
+  now build-time injected from `package.json#version` (tsup `define` on
+  `__SERVER_VERSION__`) rather than the previously hardcoded `'0.1.0'`
+  string in `src/server.ts`. Closes §3e⁶ F-mcp-serverinfo-version-stale.
+
+### Tests
+
+- 134 vitest pass (up from 101 in 0.1.2). Net +33 cases:
+  - **+6** `config.test.ts` — `loadBrokerConfig` lazy-validation
+    (no key, empty string, valid key, malformed key) + env-driven backend
+    + dashboard URL surface.
+  - **+5** `daemon-handler.test.ts` — 0.3.0 protocol: `hello` surfaces
+    `hasSessionKey` + `effectiveConfig` from options, defaults `true`
+    when omitted, reflects `false` when set; `sign_hash` with
+    `NullSigner` returns `session_key_unavailable`; re-throws non-Missing
+    errors verbatim.
+  - **+9** `cli-parse-login-flags.test.ts` — flag parser unit cases
+    incl. `--from-daemon` mutual-exclusion guard.
+  - **+8** `session-key-required.test.ts` — `signEnvelope` probe of
+    `hello.hasSessionKey`; short-circuit returns `SESSION_KEY_REQUIRED`
+    for buy + claim with mint-URL pointing at `dashboardBaseUrl`;
+    safety-net mapping of inner `session_key_unavailable`;
+    probe-cache reuse; concurrent-call coalescing (one hello round-trip
+    for N callers); retry-after-rejection (eager cache clear); trailing-slash
+    mintUrl strip.
+  - **+2** `server-version.test.ts` — runtime fallback returns
+    `package.json#version`; matches `manifest.json#version`.
+  - **+2** `build-artifacts.test.ts` — hostname-migration guard + new
+    `__SERVER_VERSION__` literal grep in bundled dist.
+  - **+1** `daemon-lifecycle.test.ts` — read-only-posture boot test
+    replaces the prior "exits on missing key" assertion; added
+    "exits on a malformed session key" as the second negative-path test.
+
 ## [0.1.2] — 2026-05-11
 
 Re-roll of the `0.1.1` workflow-validation cut. `0.1.1` never reached npm:
@@ -181,7 +380,8 @@ Workstream H)
     muhaven-mcp-0.1.0.tgz
   ```
 
-[Unreleased]: https://github.com/hasToDev/muhaven/compare/mcp-v0.1.2...HEAD
+[Unreleased]: https://github.com/hasToDev/muhaven/compare/mcp-v0.1.3...HEAD
+[0.1.3]: https://github.com/hasToDev/muhaven/releases/tag/mcp-v0.1.3
 [0.1.2]: https://github.com/hasToDev/muhaven/releases/tag/mcp-v0.1.2
 [0.1.1]: https://github.com/hasToDev/muhaven/releases/tag/mcp-v0.1.1
 [0.1.0]: https://github.com/hasToDev/muhaven/releases/tag/mcp-v0.1.0

package/bin/muhaven-mcp.cjs

@@ -1,5 +1,50 @@
 #!/usr/bin/env node
 /* eslint-disable */
+//
+// `muhaven-mcp` bin entrypoint.
+//
+// Production: MCPB hosts (Claude Desktop / Cursor / Claude Code) spawn this
+// binary over STDIO and immediately start a JSON-RPC handshake. The host
+// never passes argv flags — but operators occasionally run `muhaven-mcp
+// --version` / `--help` from the shell to sanity-check the install. Those
+// flags short-circuit BEFORE we wire up the STDIO transport so they exit
+// cleanly without spinning up the broker IPC + tool registry.
+//
+// Keep this shim tiny — the production path is `runMcpStdioCli()` from the
+// bundled dist. Anything richer goes in src/ where it's testable.
+//
+
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../package.json');
+  process.stdout.write(`muhaven-mcp ${pkg.version}\n`);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+  const pkg = require('../package.json');
+  process.stdout.write(
+    [
+      `muhaven-mcp ${pkg.version} — MuHaven MCP STDIO server`,
+      ``,
+      `Usage:`,
+      `  muhaven-mcp                        Run the MCP server over STDIO`,
+      `                                     (called by Claude Desktop / Cursor /`,
+      `                                     Claude Code — not directly by humans)`,
+      `  muhaven-mcp --version | -v         Print the @muhaven/mcp package version`,
+      `  muhaven-mcp --help    | -h         Show this help`,
+      ``,
+      `For first-time setup, run:   muhaven-broker setup`,
+      `For troubleshooting, run:    muhaven-broker doctor`,
+      ``,
+      `Docs: https://github.com/hasToDev/muhaven/blob/master/packages/mcp/README.md`,
+      ``,
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
 const { runMcpStdioCli } = require('../dist/index.cjs');
 
 runMcpStdioCli().then(