@muhaven/mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +250,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/dist/broker.cjs

@@ -73,23 +73,26 @@ function loadMcpConfig(env = process.env) {
 }
 var PRIVKEY_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
 function loadBrokerConfig(env = process.env) {
-  const sessionKeyHex = env.MUHAVEN_BROKER_SESSION_KEY;
-  if (!sessionKeyHex) {
-    throw new Error(
-      "MUHAVEN_BROKER_SESSION_KEY is required (0x-prefixed 32-byte hex). Mint a session key via the dashboard policy-template install flow."
-    );
-  }
-  if (!PRIVKEY_HEX_RE.test(sessionKeyHex)) {
-    throw new Error("MUHAVEN_BROKER_SESSION_KEY must be a 0x-prefixed 32-byte hex string");
+  const sessionKeyHexRaw = env.MUHAVEN_BROKER_SESSION_KEY;
+  let sessionKeyHex;
+  if (sessionKeyHexRaw && sessionKeyHexRaw.length > 0) {
+    if (!PRIVKEY_HEX_RE.test(sessionKeyHexRaw)) {
+      throw new Error("MUHAVEN_BROKER_SESSION_KEY must be a 0x-prefixed 32-byte hex string");
+    }
+    sessionKeyHex = sessionKeyHexRaw;
   }
   const endpoint = env.MUHAVEN_BROKER_ENDPOINT ?? defaultBrokerEndpoint();
   const maxRequestBytes = readEnvInt("MUHAVEN_BROKER_MAX_BYTES", DEFAULT_BROKER_MAX_BYTES, env);
   const requestTimeoutMs = readEnvInt("MUHAVEN_BROKER_TIMEOUT_MS", DEFAULT_BROKER_TIMEOUT_MS, env);
+  const backendBaseUrl = trimTrailingSlash(env.MUHAVEN_BACKEND_URL ?? DEFAULT_BACKEND_URL);
+  const dashboardBaseUrl = trimTrailingSlash(env.MUHAVEN_DASHBOARD_URL ?? DEFAULT_DASHBOARD_URL);
   return {
     endpoint,
     sessionKeyHex,
     maxRequestBytes,
-    requestTimeoutMs
+    requestTimeoutMs,
+    backendBaseUrl,
+    dashboardBaseUrl
   };
 }
 var BrokerClientError = class extends Error {
@@ -522,7 +525,7 @@ async function openKeystore(options = {}) {
 }
 
 // src/broker/protocol.ts
-var BROKER_PROTOCOL_VERSION = "0.2.0";
+var BROKER_PROTOCOL_VERSION = "0.3.0";
 var HASH_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
 var JWT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
 function isHashHex(value) {
@@ -608,6 +611,21 @@ function parseBrokerRequest(line) {
 function serializeResponse(res) {
   return JSON.stringify(res) + "\n";
 }
+var MissingSessionKeyError = class extends Error {
+  constructor() {
+    super(
+      "session_key_unavailable: daemon booted in read-only posture (no MUHAVEN_BROKER_SESSION_KEY at env-load time). Mint a session key via the dashboard /agent/policy/transition flow, set MUHAVEN_BROKER_SESSION_KEY, and restart the daemon. (Note: `muhaven-broker login` mints a JWT, NOT a session key \u2014 do not loop on that command for this error.)"
+    );
+    this.name = "MissingSessionKeyError";
+  }
+};
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var NullSigner = class {
+  address = ZERO_ADDRESS;
+  async signHash(_hash) {
+    throw new MissingSessionKeyError();
+  }
+};
 var ViemSigner = class {
   account;
   constructor(privateKey) {
@@ -624,7 +642,7 @@ var ViemSigner = class {
 // src/broker/daemon.ts
 var noopLogger = (_e) => {
 };
-async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.floor(Date.now() / 1e3)) {
+async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.floor(Date.now() / 1e3), options = {}) {
   switch (req.type) {
     case "hello": {
       let hasJwt = false;
@@ -634,16 +652,26 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
       } catch {
         hasJwt = false;
       }
+      const hasSessionKey = options.hasSessionKey ?? true;
       return {
         type: "hello",
         version: BROKER_PROTOCOL_VERSION,
         sessionKeyAddress: signer.address,
-        hasJwt
+        hasJwt,
+        hasSessionKey,
+        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {}
       };
     }
     case "sign_hash": {
-      const signature = await signer.signHash(req.hash);
-      return { type: "sign_hash", signature, signerAddress: signer.address };
+      try {
+        const signature = await signer.signHash(req.hash);
+        return { type: "sign_hash", signature, signerAddress: signer.address };
+      } catch (err) {
+        if (err instanceof MissingSessionKeyError) {
+          return errorResponse("session_key_unavailable", err.message);
+        }
+        throw err;
+      }
     }
     case "store_jwt": {
       try {
@@ -715,9 +743,24 @@ var BrokerDaemon = class {
   log;
   config;
   keystore;
+  /**
+   * Whether a session-key private half is actually loaded. `false` =
+   * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`
+   * at env-load time) and uses a `NullSigner` whose `signHash` throws.
+   */
+  hasSessionKey;
   constructor(options) {
     this.config = options.config;
-    this.signer = options.signer ?? new ViemSigner(options.config.sessionKeyHex);
+    if (options.signer) {
+      this.signer = options.signer;
+      this.hasSessionKey = true;
+    } else if (options.config.sessionKeyHex) {
+      this.signer = new ViemSigner(options.config.sessionKeyHex);
+      this.hasSessionKey = true;
+    } else {
+      this.signer = new NullSigner();
+      this.hasSessionKey = false;
+    }
     this.keystore = options.keystore ?? null;
     this.log = options.logger ?? noopLogger;
     this.server = net.createServer((socket) => this.onConnection(socket));
@@ -755,6 +798,7 @@ var BrokerDaemon = class {
       meta: {
         endpoint: this.config.endpoint,
         signer: this.signer.address,
+        hasSessionKey: this.hasSessionKey,
         keystore: this.keystore.backend,
         version: BROKER_PROTOCOL_VERSION
       }
@@ -836,7 +880,19 @@ var BrokerDaemon = class {
       return;
     }
     try {
-      const res = await handleBrokerRequest(parsed, this.signer, this.keystore);
+      const res = await handleBrokerRequest(
+        parsed,
+        this.signer,
+        this.keystore,
+        void 0,
+        {
+          hasSessionKey: this.hasSessionKey,
+          effectiveConfig: {
+            backendBaseUrl: this.config.backendBaseUrl,
+            dashboardBaseUrl: this.config.dashboardBaseUrl
+          }
+        }
+      );
       socket.end(serializeResponse(res));
     } catch (err) {
       this.log({
@@ -852,6 +908,15 @@ var BrokerDaemon = class {
 };
 async function runBrokerDaemonCli() {
   const config = loadBrokerConfig();
+  if (!config.sessionKeyHex) {
+    process.stderr.write(
+      JSON.stringify({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        level: "info",
+        msg: "broker booting in read-only posture (no MUHAVEN_BROKER_SESSION_KEY)"
+      }) + "\n"
+    );
+  }
   const daemon = new BrokerDaemon({
     config,
     logger: (e) => {
@@ -904,9 +969,11 @@ function parseLoginFlags(argv) {
   let brokerEndpoint;
   let backendBaseUrl;
   let dashboardBaseUrl;
+  let fromDaemon = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--no-launch-browser") noLaunchBrowser = true;
+    else if (a === "--from-daemon") fromDaemon = true;
     else if (a === "--broker-endpoint" && i + 1 < argv.length) {
       brokerEndpoint = argv[++i];
     } else if (a === "--backend-base-url" && i + 1 < argv.length) {
@@ -917,7 +984,12 @@ function parseLoginFlags(argv) {
       throw new Error(`unknown flag: ${a}`);
     }
   }
-  return { noLaunchBrowser, brokerEndpoint, backendBaseUrl, dashboardBaseUrl };
+  if (fromDaemon && (backendBaseUrl || dashboardBaseUrl)) {
+    throw new Error(
+      "--from-daemon is mutually exclusive with --backend-base-url / --dashboard-base-url"
+    );
+  }
+  return { noLaunchBrowser, brokerEndpoint, backendBaseUrl, dashboardBaseUrl, fromDaemon };
 }
 async function tryLaunchBrowser(url) {
   return new Promise((resolve) => {
@@ -931,7 +1003,9 @@ async function runLogin(argv) {
     flags = parseLoginFlags(argv);
   } catch (err) {
     printErr(`error: ${err.message}`);
-    printErr("usage: muhaven-broker login [--no-launch-browser] [--broker-endpoint PATH] [--backend-base-url URL] [--dashboard-base-url URL]");
+    printErr(
+      "usage: muhaven-broker login [--no-launch-browser] [--broker-endpoint PATH] [--from-daemon | (--backend-base-url URL --dashboard-base-url URL)]"
+    );
     return 2;
   }
   const env = process.env;
@@ -945,8 +1019,9 @@ async function runLogin(argv) {
     endpoint: config.brokerEndpoint,
     timeoutMs: config.brokerTimeoutMs
   });
+  let helloResult;
   try {
-    await broker.hello();
+    helloResult = await broker.hello();
   } catch (err) {
     printErr(
       `cannot reach muhaven-broker daemon at ${config.brokerEndpoint}: ${err.message}`
@@ -954,9 +1029,42 @@ async function runLogin(argv) {
     printErr("hint: start the daemon first (`muhaven-broker` with no subcommand).");
     return 1;
   }
+  let backendBaseUrl = config.backendBaseUrl;
+  let dashboardBaseUrl = config.dashboardBaseUrl;
+  if (flags.fromDaemon) {
+    if (!helloResult.effectiveConfig) {
+      printErr(
+        "--from-daemon requested but broker did not return effectiveConfig (daemon is older than protocol 0.3.0). Upgrade the daemon (`@muhaven/mcp@0.1.3+`) or drop the flag."
+      );
+      return 1;
+    }
+    const daemonBackend = helloResult.effectiveConfig.backendBaseUrl;
+    const daemonDashboard = helloResult.effectiveConfig.dashboardBaseUrl;
+    if (!daemonBackend || !daemonDashboard) {
+      printErr(
+        "--from-daemon: daemon returned an empty backend/dashboard URL \u2014 refusing to proceed."
+      );
+      return 1;
+    }
+    if (daemonBackend !== config.backendBaseUrl) {
+      print(
+        `\u26A0 daemon backend (${daemonBackend}) differs from CLI env (${config.backendBaseUrl}). Using daemon's value per --from-daemon.`
+      );
+    }
+    if (daemonDashboard !== config.dashboardBaseUrl) {
+      print(
+        `\u26A0 daemon dashboard (${daemonDashboard}) differs from CLI env (${config.dashboardBaseUrl}). Using daemon's value per --from-daemon.`
+      );
+    }
+    backendBaseUrl = daemonBackend;
+    dashboardBaseUrl = daemonDashboard;
+    print(`Using daemon's effective config:`);
+    print(`  backend:   ${backendBaseUrl}`);
+    print(`  dashboard: ${dashboardBaseUrl}`);
+  }
   const flow = new DeviceFlowClient({
-    backendBaseUrl: config.backendBaseUrl,
-    dashboardBaseUrl: config.dashboardBaseUrl,
+    backendBaseUrl,
+    dashboardBaseUrl,
     requesterMetadata: {
       processName: detectMcpHost(),
       hostname: os.hostname(),
@@ -1071,7 +1179,13 @@ async function runDoctor() {
   });
   try {
     const h = await broker.hello();
-    print(`Broker daemon     : reachable (proto v${h.version}, signer ${h.sessionKeyAddress}, hasJwt=${h.hasJwt})`);
+    const hasKey = h.hasSessionKey ?? true;
+    const keyTag = hasKey ? `signer ${h.sessionKeyAddress}` : "NO SESSION KEY (read-only posture)";
+    print(`Broker daemon     : reachable (proto v${h.version}, ${keyTag}, hasJwt=${h.hasJwt})`);
+    if (h.effectiveConfig) {
+      print(`Daemon backend URL: ${h.effectiveConfig.backendBaseUrl}`);
+      print(`Daemon dashboard  : ${h.effectiveConfig.dashboardBaseUrl}`);
+    }
     return 0;
   } catch (err) {
     print(`Broker daemon     : NOT reachable (${err.message})`);
@@ -1084,6 +1198,7 @@ function printUsage() {
   print("");
   print("  (no subcommand)    Run the daemon (production mode)");
   print("  login              Acquire a JWT via the device-code flow + store in keystore");
+  print("                       [--from-daemon] resolves backend/dashboard URLs from the running daemon");
   print("  logout             Clear the JWT from the keystore");
   print("  doctor             Print environment + keystore + reachability report");
   print("  -h, --help         Show this help");
@@ -1111,6 +1226,7 @@ async function runCli(argv) {
   }
 }
 
+exports.parseLoginFlags = parseLoginFlags;
 exports.runCli = runCli;
 exports.runDoctor = runDoctor;
 exports.runLogin = runLogin;

package/dist/broker.d.cts

@@ -8,9 +8,29 @@
  *   doctor         → environment + keystore capability report
  *   --help, -h     → usage
  */
+interface LoginFlags {
+    noLaunchBrowser: boolean;
+    brokerEndpoint?: string;
+    backendBaseUrl?: string;
+    dashboardBaseUrl?: string;
+    /**
+     * Resolve `backendBaseUrl` + `dashboardBaseUrl` from the running
+     * daemon's view (returned in `hello.effectiveConfig`) rather than the
+     * CLI's env. Solves the daemon-vs-CLI env-divergence problem when the
+     * CLI is launched from a different shell (ssh, IDE-spawned terminal)
+     * than the systemd / launchd-launched daemon. Closes §3e⁶
+     * F-broker-env-divergence.
+     *
+     * Mutually exclusive with explicit `--backend-base-url` /
+     * `--dashboard-base-url`; the CLI rejects the combination so the
+     * operator picks one source of truth.
+     */
+    fromDaemon: boolean;
+}
+declare function parseLoginFlags(argv: readonly string[]): LoginFlags;
 declare function runLogin(argv: readonly string[]): Promise<number>;
 declare function runLogout(): Promise<number>;
 declare function runDoctor(): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { runCli, runDoctor, runLogin, runLogout };
+export { parseLoginFlags, runCli, runDoctor, runLogin, runLogout };

package/dist/broker.d.ts

@@ -8,9 +8,29 @@
  *   doctor         → environment + keystore capability report
  *   --help, -h     → usage
  */
+interface LoginFlags {
+    noLaunchBrowser: boolean;
+    brokerEndpoint?: string;
+    backendBaseUrl?: string;
+    dashboardBaseUrl?: string;
+    /**
+     * Resolve `backendBaseUrl` + `dashboardBaseUrl` from the running
+     * daemon's view (returned in `hello.effectiveConfig`) rather than the
+     * CLI's env. Solves the daemon-vs-CLI env-divergence problem when the
+     * CLI is launched from a different shell (ssh, IDE-spawned terminal)
+     * than the systemd / launchd-launched daemon. Closes §3e⁶
+     * F-broker-env-divergence.
+     *
+     * Mutually exclusive with explicit `--backend-base-url` /
+     * `--dashboard-base-url`; the CLI rejects the combination so the
+     * operator picks one source of truth.
+     */
+    fromDaemon: boolean;
+}
+declare function parseLoginFlags(argv: readonly string[]): LoginFlags;
 declare function runLogin(argv: readonly string[]): Promise<number>;
 declare function runLogout(): Promise<number>;
 declare function runDoctor(): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { runCli, runDoctor, runLogin, runLogout };
+export { parseLoginFlags, runCli, runDoctor, runLogin, runLogout };