@muhaven/mcp 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,698 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+
+/**
+ * Wire protocol between the MCP server (`@muhaven/mcp` STDIO subprocess)
+ * and the long-running `muhaven-broker` daemon.
+ *
+ * Newline-delimited JSON over a Unix socket (POSIX) or named pipe
+ * (Windows). Each request is a single JSON object; each response is a
+ * single JSON object. No request pipelining, no streaming.
+ *
+ * **Protocol version 0.2.0** — bumped from 0.1.0 in Wave 4 P3 ADR-3
+ * to add the `store_jwt` / `get_jwt` / `clear_jwt` triple. The broker
+ * is now the single keeper of the device-flow JWT (per ADR-3 D1
+ * "polling, not loopback callback") in addition to the session-key
+ * private half.
+ *
+ * Threat-model invariants:
+ *  - The broker NEVER reaches out to the network. It only:
+ *      (a) signs hashes that the MCP server received from the backend,
+ *      (b) stores / returns / clears a JWT that the MCP server
+ *          received from the backend.
+ *    Splitting network egress (MCP server) from signing + secret
+ *    storage (broker) is the lethal-trifecta mitigation in
+ *    `THREAT_MODEL_P0.md` §"Lethal-trifecta self-audit".
+ *  - Requests are size-capped (`maxRequestBytes`) — a malformed peer
+ *    cannot exhaust broker memory by sending an unbounded JSON blob.
+ */
+declare const BROKER_PROTOCOL_VERSION = "0.2.0";
+interface BrokerHelloRequest {
+    readonly type: 'hello';
+}
+interface BrokerSignHashRequest {
+    readonly type: 'sign_hash';
+    /** 0x-prefixed 32-byte hex (e.g., a UserOp hash to be ECDSA-signed). */
+    readonly hash: `0x${string}`;
+    /** Free-form context for the audit log. NOT trusted as policy input. */
+    readonly intent?: {
+        readonly tool: string;
+        readonly summary?: string;
+    };
+}
+interface BrokerStoreJwtRequest {
+    readonly type: 'store_jwt';
+    /** A scoped device-flow JWT (mcp.read.*, mcp.propose.*) per ADR-3 D2. */
+    readonly jwt: string;
+    /** Optional issuer-stated expiry (epoch seconds). Used for proactive
+     *  re-login UX; not for trust decisions. */
+    readonly expiresAtSec?: number;
+}
+interface BrokerGetJwtRequest {
+    readonly type: 'get_jwt';
+}
+interface BrokerClearJwtRequest {
+    readonly type: 'clear_jwt';
+}
+interface BrokerHelloResponse {
+    readonly type: 'hello';
+    readonly version: string;
+    /** 0x-prefixed checksummed address derived from the session key. */
+    readonly sessionKeyAddress: `0x${string}`;
+    /** Whether a JWT is currently in the keystore. Useful for `doctor`. */
+    readonly hasJwt: boolean;
+}
+interface BrokerSignHashResponse {
+    readonly type: 'sign_hash';
+    /** 0x-prefixed 65-byte ECDSA signature (r || s || v). */
+    readonly signature: `0x${string}`;
+    readonly signerAddress: `0x${string}`;
+}
+interface BrokerStoreJwtResponse {
+    readonly type: 'store_jwt';
+    readonly stored: true;
+}
+interface BrokerGetJwtResponse {
+    readonly type: 'get_jwt';
+    /** Null when no JWT in keystore — caller must trigger device-flow. */
+    readonly jwt: string | null;
+    readonly expiresAtSec: number | null;
+}
+interface BrokerClearJwtResponse {
+    readonly type: 'clear_jwt';
+    readonly cleared: true;
+}
+interface BrokerErrorResponse {
+    readonly type: 'error';
+    readonly code: BrokerErrorCode;
+    readonly message: string;
+}
+type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable';
+type BrokerRequest = BrokerHelloRequest | BrokerSignHashRequest | BrokerStoreJwtRequest | BrokerGetJwtRequest | BrokerClearJwtRequest;
+type BrokerResponse = BrokerHelloResponse | BrokerSignHashResponse | BrokerStoreJwtResponse | BrokerGetJwtResponse | BrokerClearJwtResponse | BrokerErrorResponse;
+/**
+ * Parse a single-line request payload. Returns either the validated
+ * request or a structured error — the daemon converts errors to a
+ * `BrokerErrorResponse` without raising so a malformed peer cannot crash
+ * the daemon process.
+ */
+declare function parseBrokerRequest(line: string): BrokerRequest | BrokerErrorResponse;
+declare function serializeResponse(res: BrokerResponse): string;
+
+/**
+ * Tiny line-based IPC client used by the MCP server to talk to a
+ * running `muhaven-broker` daemon. Mirrors the protocol in
+ * `src/broker/protocol.ts`.
+ *
+ * One request per connection; response is a single line. Connection
+ * timeouts surface as `BrokerClientError` with a stable `code` string so
+ * the MCP tool layer can map to host-friendly error responses without
+ * inspecting message strings.
+ */
+
+type BrokerClientErrorCode = 'connect_failed' | 'timeout' | 'protocol_error' | 'broker_error';
+declare class BrokerClientError extends Error {
+    readonly code: BrokerClientErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: BrokerClientErrorCode, message: string, cause?: unknown | undefined);
+}
+interface BrokerClientOptions {
+    endpoint: string;
+    timeoutMs: number;
+}
+declare class BrokerClient {
+    private readonly options;
+    constructor(options: BrokerClientOptions);
+    hello(): Promise<BrokerHelloResponse>;
+    signHash(hash: `0x${string}`, intent?: {
+        tool: string;
+        summary?: string;
+    }): Promise<BrokerSignHashResponse>;
+    storeJwt(jwt: string, expiresAtSec?: number): Promise<BrokerStoreJwtResponse>;
+    getJwt(): Promise<BrokerGetJwtResponse>;
+    clearJwt(): Promise<void>;
+    private exchange;
+}
+
+/**
+ * JWT source for the MCP server. Wraps `BrokerClient.getJwt()` with a
+ * brief in-process cache (default 30s; tunable via
+ * `MUHAVEN_JWT_CACHE_TTL_SEC`) so the per-tool-call hot path doesn't
+ * round-trip the broker socket on every invocation.
+ *
+ * The cache is invalidated on:
+ *  - Explicit `invalidate()` (called on backend-side 401 responses).
+ *  - JWT expiry (when the broker recorded an `expiresAtSec`).
+ *
+ * On a cache miss, the source asks the broker via IPC. If the broker
+ * returns `jwt: null`, the caller (tool handler / device-flow client)
+ * is responsible for kicking off the device-flow ceremony — this module
+ * never speaks HTTPS itself.
+ */
+
+declare class NoJwtAvailableError extends Error {
+    readonly code = "no_jwt";
+    constructor();
+}
+declare class JwtSource {
+    private readonly broker;
+    private readonly cacheTtlSec;
+    private readonly nowMs;
+    private cached;
+    constructor(broker: BrokerClient, cacheTtlSec: number, nowMs?: () => number);
+    /**
+     * Fetch the current JWT, throwing `NoJwtAvailableError` when the
+     * broker keystore is empty.
+     */
+    get(): Promise<string>;
+    /** Drop the in-process cache. Call after a backend 401 to force refresh. */
+    invalidate(): void;
+    /** Returns the cached JWT iff it's fresh AND not past `expiresAtSec`. */
+    private cachedJwtIfValid;
+}
+
+/**
+ * Thin REST client for the MuHaven backend. The backend exposes JWT-
+ * authenticated endpoints under `/api/v1/...`; this client carries the
+ * caller's bearer token on every request and surfaces errors as
+ * `BackendError` with stable codes.
+ *
+ * **JWT acquisition**: per ADR-3, the JWT is fetched from a `JwtSource`
+ * (which is broker-mediated). On a 401 response the client invalidates
+ * the JWT cache once and retries; if the second 401 lands, surface
+ * `BackendError(unauthorized)` to the caller — that's the device-flow
+ * trigger.
+ *
+ * **URL guard**: every request URL is checked against the configured
+ * allowed-host allowlist. Defends against (Wave-5) prompt-injection
+ * coercing the LLM into a host-swap. Today the tool layer hard-codes
+ * paths so the guard is belt-and-suspenders, but defining it here means
+ * the guarantee survives later refactors.
+ */
+
+interface BackendClientOptions {
+    baseUrl: string;
+    jwtSource: JwtSource;
+    timeoutMs: number;
+    allowedHosts: readonly string[];
+    /** Inject a fetch impl for tests. */
+    fetchImpl?: typeof fetch;
+}
+type BackendErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'gone' | 'rate_limited' | 'bad_request' | 'server_error' | 'network' | 'timeout' | 'invalid_response' | 'host_not_allowed';
+declare class BackendError extends Error {
+    readonly code: BackendErrorCode;
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(code: BackendErrorCode, message: string, status?: number | undefined, body?: unknown | undefined);
+}
+declare class BackendClient {
+    private readonly options;
+    private readonly fetchImpl;
+    constructor(options: BackendClientOptions);
+    get<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * Path-less variant for unauthenticated calls (e.g., device-code
+     * flow's `/auth/device/code` and `/auth/device/token`). Sends no
+     * Authorization header.
+     */
+    postUnauth<T>(path: string, body: unknown): Promise<T>;
+    private buildUrl;
+    private exchangeWithRetry;
+    private exchange;
+}
+
+/**
+ * Tool descriptions are the **single source of truth** for what each MCP
+ * tool advertises to the host LLM. They are also hashed (SHA-256) at
+ * package build time and the hashes shipped in `tool-hashes.json`.
+ *
+ * The mcp-context-protector pattern (post-MCPoison, Apr 2026) compares
+ * the live description hash against the pinned hash on first use; a
+ * mismatch implies either a malicious downgrade attack or an
+ * out-of-band patch. Both warrant operator review before re-confirming.
+ *
+ * Naming convention is locked in `development/DEV_WAVE_4/TOOL_NAMESPACE.md`:
+ *   muhaven.<group>.<verb>     ^muhaven\.[a-z]+\.[a-z][a-z0-9_]*$
+ *
+ * Renaming a tool is a breaking change — bump the package major.
+ */
+interface ToolDescriptor {
+    /** Canonical name. MUST match the regex in TOOL_NAMESPACE.md. */
+    readonly name: string;
+    /** Group classification — drives the --read-only filter. P7 adds
+     *  `issuer` for issuer-side state-mutating tools that require an
+     *  approved issuer kernel (the use-case-side gate produces structured
+     *  403s for non-issuers; the group is for the read-only filter only).
+     *
+     *  P11 adds `governance` for the FHE-encrypted voting ceremony +
+     *  protection-coverage / KYC-attestation reads. The two read tools
+     *  (`muhaven.governance.protection_coverage`,
+     *  `muhaven.governance.kyc_attestation`) are also exposed under
+     *  `read` so `--read-only` keeps them available; the two propose
+     *  tools (`muhaven.governance.propose`, `muhaven.governance.cast_vote`)
+     *  are filtered off in read-only mode. */
+    readonly group: 'read' | 'position' | 'policy' | 'issuer' | 'governance';
+    /** Human-readable description shown in the host UI. */
+    readonly description: string;
+    /** When true, the host SHOULD render a confirmation cue before invoking. */
+    readonly sensitive: boolean;
+}
+/**
+ * The 22 Wave 4 MCP tools across five groups:
+ *   muhaven.read.*       (7 — incl. P11 protection_coverage + kyc_attestation)
+ *   muhaven.position.*   (4)
+ *   muhaven.policy.*     (4)
+ *   muhaven.issuer.*     (5 — P7)
+ *   muhaven.governance.* (2 — P11; cast_vote frontend runner deferred to Wave 5)
+ *
+ * `MUHAVEN_READ_ONLY=true` exposes only the 7 `muhaven.read.*` tools.
+ * P5's `muhaven.checkout.*` namespace was retired before Wave 4 close — the
+ * hosted checkout surface ships as a separate Vite SPA (apps/checkout-pay/),
+ * not as an MCP tool group.
+ */
+declare const TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+/**
+ * Hash a tool descriptor — the bytes that change when an attacker
+ * rewrites a tool's *advertised behaviour*. Excluding `group` keeps the
+ * hash stable across refactors that move a tool between groups; both
+ * `name` and `description` are included because either changing alters
+ * the LLM's interpretation of the tool.
+ */
+declare function hashToolDescriptor(d: ToolDescriptor): string;
+interface ToolHashEntry {
+    readonly name: string;
+    readonly sha256: string;
+}
+declare function buildToolHashTable(): readonly ToolHashEntry[];
+/** Compare a live descriptor against a pinned hash. Returns null on
+ *  match; returns a structured mismatch payload on drift. */
+declare function verifyDescriptorAgainstPin(descriptor: ToolDescriptor, pinnedSha256: string): {
+    liveSha256: string;
+    pinnedSha256: string;
+} | null;
+
+/**
+ * Shared AUTH_REQUIRED payload used by both server-level and handler-level
+ * unauthorized mappings.
+ *
+ * Why both layers? The handlers wrap every BackendClient call in a
+ * try/catch + `mapBackendError(...)` (so the structured tool result is
+ * uniform). That means a `BackendError(unauthorized)` is converted to a
+ * normal return value and never reaches `server.ts`'s catch block, where
+ * the original AUTH_REQUIRED branch lived. Surfacing it from BOTH layers:
+ *  1. handler layer → catches the common case (backend 401 after one
+ *     refresh retry).
+ *  2. server layer → catches the JwtSource-throws-NoJwtAvailable case,
+ *     which propagates THROUGH the handler (the handler never sees a
+ *     BackendError because no HTTP request fires).
+ *
+ * Producing the same payload from both keeps the host LLM's parsing path
+ * stable (always look for `code: 'AUTH_REQUIRED'`).
+ */
+interface AuthRequiredPayload {
+    readonly ok: false;
+    readonly code: 'AUTH_REQUIRED';
+    readonly message: string;
+    readonly loginCommand: string;
+}
+
+/**
+ * Tool handlers — pure functions of `(input, deps)` returning a structured
+ * tool result. The MCP server transport layer (`src/server.ts`) wires
+ * these to the host LLM via `@modelcontextprotocol/sdk`.
+ *
+ * Design notes:
+ *  - Handlers NEVER throw. They translate every error into a structured
+ *    `{ ok: false, code, message }` payload so the host LLM can decide
+ *    how to surface it without crashing the MCP server. This matches the
+ *    MCPB error-presentation convention.
+ *  - Position handlers DO NOT submit UserOps. They return an unsigned
+ *    envelope plus a broker signature; the host (or the MuHaven
+ *    dashboard via deep-link) is responsible for bundler submission.
+ *    Splitting submission from signing is the lethal-trifecta defense.
+ *  - Backend errors with status >= 500 are surfaced as `server_error`
+ *    so the host can retry; client errors (4xx) bubble up as the
+ *    discriminating code (`unauthorized`, `forbidden`, etc.). The host
+ *    MUST NOT auto-retry 4xx.
+ */
+
+interface ToolDeps {
+    backend: BackendClient;
+    broker?: BrokerClient;
+    /** Surface this MCP server is configured for. Always 'mcp' here, but
+     *  carried as a dep so the audit tool can filter to the local surface. */
+    surface: 'mcp';
+}
+type ToolResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+} | AuthRequiredPayload;
+
+/**
+ * Static registry binding each tool descriptor to its zod schema and
+ * handler. Keeping this in one file means a CI lint can audit the
+ * mapping in a single read — no risk of a tool being declared in
+ * `descriptions.ts` but accidentally not wired to a handler, or vice
+ * versa.
+ *
+ * The registry exposes a filtered view (`registryForReadOnly`) consumed
+ * by `src/server.ts` when `MUHAVEN_READ_ONLY=true`. The filter prunes
+ * the `position.*` and `policy.*` groups; only `read.*` tools remain
+ * advertised. Mirrors `github/github-mcp-server`'s `--read-only` flag.
+ */
+
+interface ToolEntry<TInput = unknown, TOutput = unknown> {
+    descriptor: ToolDescriptor;
+    schema: z.ZodTypeAny;
+    handler: (input: TInput, deps: ToolDeps) => Promise<ToolResult<TOutput>>;
+}
+declare function fullToolRegistry(): readonly ToolEntry[];
+declare function registryForReadOnly(): readonly ToolEntry[];
+declare function selectRegistry(readOnly: boolean): readonly ToolEntry[];
+
+/**
+ * MCP STDIO server bridge — registers all tools from `tools/registry.ts`
+ * with `@modelcontextprotocol/sdk`'s STDIO transport, validates each
+ * tool input against its zod schema, and dispatches to the handler.
+ *
+ * Hardening invariants per `THREAT_MODEL_P0.md` + ADR-3:
+ *  - Transport is STDIO **only** — never TCP. The MCP SDK's
+ *    `StdioServerTransport` is the only one we mount.
+ *  - Tool inputs are zod-validated server-side; the LLM cannot inject
+ *    new fields (`additionalProperties: false`).
+ *  - Tool descriptions are pinned at build time via `tool-hashes.json`
+ *    and re-verified on startup. A drift exits with code 70 (matches
+ *    the BSD `EX_CONFIG` convention).
+ *  - On any backend `unauthorized` response after a single retry, the
+ *    handler returns a structured `AUTH_REQUIRED` payload that
+ *    instructs the user to run `muhaven-broker login`.
+ */
+
+interface BuildServerOptions {
+    registry: readonly ToolEntry[];
+    backend: BackendClient;
+    broker: BrokerClient | undefined;
+}
+declare function buildMcpServer(opts: BuildServerOptions): Server;
+/**
+ * Boot options for `runMcpStdioCli`.
+ *
+ * `filterRegistry` is the OpenClaw-shaped extension point: callers can
+ * supply a function that receives the post-`--read-only` registry and
+ * returns a (possibly narrower) subset. The bundled OpenClaw skill uses
+ * this to ship a curated 11-tool subset out of the 22-tool upstream
+ * surface (ADR-C). The filter MUST be a pure function; any side effect
+ * (mutation of the input array, network call, etc.) is unsupported.
+ *
+ * Tool-description hash verification fires BEFORE the filter — drift in
+ * an upstream descriptor must abort startup even if the consumer would
+ * have filtered the affected tool out. Otherwise an attacker who patches
+ * a single descriptor could hide it from the verification gate by
+ * shipping a subset filter that excludes only that tool.
+ */
+interface RunMcpStdioCliOptions {
+    filterRegistry?: (registry: readonly ToolEntry[]) => readonly ToolEntry[];
+}
+/** Production STDIO entrypoint — wired through `bin/muhaven-mcp.cjs`. */
+declare function runMcpStdioCli(opts?: RunMcpStdioCliOptions): Promise<void>;
+
+/**
+ * Runtime configuration sourced from env vars declared in `manifest.json`.
+ *
+ * MCPB hosts (Claude Desktop, Cursor, Claude Code) inject these via the
+ * STDIO subprocess environment. Per ADR-3 the **JWT itself is no longer
+ * an env var** — it is acquired via the device-flow ceremony and lives
+ * in the broker-managed keystore. The MCP server fetches it from the
+ * broker on each tool call (with a brief in-process cache).
+ *
+ * Validation is intentionally strict: we fail to start rather than
+ * launch with a half-configured signing path. The error messages name
+ * the env var so an MCPB user can fix their host config without reading
+ * code.
+ */
+interface McpRuntimeConfig {
+    /** MuHaven backend base URL (no trailing slash). e.g. https://api.muhaven.app */
+    backendBaseUrl: string;
+    /** Origin of the MuHaven dashboard (used in AUTH_REQUIRED messages). */
+    dashboardBaseUrl: string;
+    /** Path / endpoint of the muhaven-broker IPC. */
+    brokerEndpoint: string;
+    /** When true, the position.* and policy.* toolsets are not registered. */
+    readOnly: boolean;
+    /** Soft timeout (ms) for backend HTTP calls. Default 15s. */
+    requestTimeoutMs: number;
+    /** Soft timeout (ms) for broker IPC calls. Default 5s. */
+    brokerTimeoutMs: number;
+    /** Allowed backend hostnames for URL guard. Derived from baseUrl. */
+    allowedBackendHosts: readonly string[];
+    /** In-process JWT cache TTL in seconds. Default 30. */
+    jwtCacheTtlSec: number;
+}
+interface BrokerRuntimeConfig {
+    /** Endpoint to bind: socket path on POSIX, named pipe name on Windows. */
+    endpoint: string;
+    /** 0x-prefixed 32-byte private key. Sensitive — keychain-backed. */
+    sessionKeyHex: `0x${string}`;
+    /** Maximum payload bytes accepted from the IPC peer. */
+    maxRequestBytes: number;
+    /** Per-request hard timeout (ms). */
+    requestTimeoutMs: number;
+}
+/**
+ * Compute the default IPC endpoint for the broker. POSIX: a socket file
+ * inside the user's home dir. Windows: a per-user named pipe.
+ *
+ * Both endpoints are bound to the local user only — never exposed over
+ * TCP. The TCP transport ban is a hard invariant of the broker.
+ */
+declare function defaultBrokerEndpoint(): string;
+declare function loadMcpConfig(env?: NodeJS.ProcessEnv): McpRuntimeConfig;
+declare function loadBrokerConfig(env?: NodeJS.ProcessEnv): BrokerRuntimeConfig;
+
+/**
+ * RFC 8628-flavored device authorization grant client.
+ *
+ * Per ADR-3 D1, the broker is zero-egress — so the device-flow HTTPS
+ * traffic happens here in the MCP package's process space (the
+ * `muhaven-broker login` CLI invokes this; once a JWT is acquired it
+ * is handed to the broker over IPC via `BrokerClient.storeJwt`).
+ *
+ * Three backend endpoints involved:
+ *   POST /api/v1/auth/device/code     — broker requests a code
+ *   POST /api/v1/auth/device/authorize — dashboard authorizes (NOT called here)
+ *   POST /api/v1/auth/device/token    — broker polls for the JWT
+ */
+interface DeviceCodeIssued {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresInSec: number;
+    pollIntervalSec: number;
+}
+interface DeviceFlowOptions {
+    backendBaseUrl: string;
+    dashboardBaseUrl: string;
+    /** Optional describer for the request, displayed on the /link page. */
+    requesterMetadata?: {
+        processName?: string;
+        hostname?: string;
+        os?: string;
+    };
+    /** Inject a fetch impl for tests. */
+    fetchImpl?: typeof fetch;
+    /** Inject a sleeper for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Inject a clock for tests. */
+    nowMs?: () => number;
+}
+type DeviceFlowEvent = {
+    type: 'code_issued';
+    code: DeviceCodeIssued;
+} | {
+    type: 'polling';
+    attempt: number;
+    nextPollMs: number;
+} | {
+    type: 'authorized';
+    jwt: string;
+    expiresAtSec: number | null;
+    scope: string[] | null;
+} | {
+    type: 'denied';
+    reason?: string;
+} | {
+    type: 'expired';
+};
+type DeviceFlowError = {
+    code: 'network';
+    cause: unknown;
+} | {
+    code: 'rate_limited';
+} | {
+    code: 'invalid_response';
+    status?: number;
+    body?: unknown;
+} | {
+    code: 'denied';
+    reason?: string;
+} | {
+    code: 'expired';
+} | {
+    code: 'timeout';
+};
+declare class DeviceFlowAbortedError extends Error {
+    readonly detail: DeviceFlowError;
+    constructor(detail: DeviceFlowError);
+}
+declare class DeviceFlowClient {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly sleep;
+    private readonly nowMs;
+    constructor(options: DeviceFlowOptions);
+    /**
+     * Run the full ceremony: request a code, yield events for the caller
+     * to display the URL, then poll until authorized / denied / expired.
+     * Throws `DeviceFlowAbortedError` on terminal failure.
+     */
+    run(opts?: {
+        overallTimeoutMs?: number;
+    }): AsyncGenerator<DeviceFlowEvent, {
+        jwt: string;
+        expiresAtSec: number | null;
+        scope: string[] | null;
+    }, void>;
+    private requestCode;
+    private pollOnce;
+}
+
+/**
+ * Thin wrapper around viem's privateKeyToAccount. Keeps the rest of the
+ * broker free of viem types so the IPC layer can be tested without
+ * pulling viem into the test-runtime resolution graph.
+ *
+ * The on-chain UserOp submission is the frontend / dashboard's job in
+ * Wave 4 (P6 wires it for the policy-engine cron path). The broker's
+ * single responsibility is to ECDSA-sign a hash — never to issue an
+ * RPC, never to construct an unsigned UserOp, never to read an Arb
+ * RPC endpoint. That isolation is the lethal-trifecta mitigation.
+ */
+interface ISigner {
+    readonly address: `0x${string}`;
+    signHash(hash: `0x${string}`): Promise<`0x${string}`>;
+}
+
+/**
+ * Cross-platform JWT keystore for the broker daemon.
+ *
+ * Two backends per ADR-3 D3:
+ *  - **OS keychain** (default) via `@napi-rs/keyring` — Windows DPAPI /
+ *    Credential Manager / macOS Security framework / Linux Secret
+ *    Service via D-Bus.
+ *  - **File** (opt-in via `MUHAVEN_KEYRING=file`) — JSON file at
+ *    `~/.muhaven/jwt`, mode 0600, parent dir mode 0700. Required for
+ *    WSL2 / devcontainer / SSH-remote where Secret Service is absent.
+ *
+ * The interface is intentionally tiny — the broker daemon never inspects
+ * a JWT, only stores / fetches / clears it.
+ */
+interface JwtRecord {
+    jwt: string;
+    expiresAtSec: number | null;
+    storedAtSec: number;
+}
+type KeystoreBackend = 'os' | 'file';
+interface IKeystore {
+    readonly backend: KeystoreBackend;
+    readonly available: boolean;
+    set(record: JwtRecord): Promise<void>;
+    get(): Promise<JwtRecord | null>;
+    clear(): Promise<void>;
+}
+type KeystoreErrorCode = 'os_keystore_unavailable' | 'file_read_failed' | 'file_clear_failed' | 'malformed_record';
+declare class KeystoreError extends Error {
+    readonly code: KeystoreErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: KeystoreErrorCode, message: string, cause?: unknown | undefined);
+}
+interface OpenKeystoreOptions {
+    /** When 'file', force the file backend regardless of OS support. */
+    preferred?: KeystoreBackend;
+    /** Override default file path (testing / Docker volumes). */
+    filePath?: string;
+}
+/**
+ * Pick a keystore backend. Order:
+ *   1. `MUHAVEN_KEYRING=file` env or `preferred='file'` → FileKeystore.
+ *   2. `@napi-rs/keyring` import succeeds + `getPassword()` doesn't throw → OsKeystore.
+ *   3. Fall back to FileKeystore (with a warning the caller can surface).
+ *
+ * Returns the keystore + whether a fallback was applied so the caller
+ * can print a doctor-style warning.
+ */
+declare function openKeystore(options?: OpenKeystoreOptions): Promise<{
+    keystore: IKeystore;
+    fallbackReason: string | null;
+}>;
+
+/**
+ * `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`.
+ *
+ * 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`.
+ *  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.
+ *  4. Survive a malformed peer: each request size-capped, JSON parse
+ *     failure → structured error response (not a crash), hung peer
+ *     force-disconnected after `requestTimeoutMs`.
+ *
+ * See `development/DEV_WAVE_4/ADR_LOG.md` ADR-3 for the device-flow
+ * design that motivates the JWT verbs.
+ */
+
+interface BrokerDaemonOptions {
+    config: BrokerRuntimeConfig;
+    signer?: ISigner;
+    /** Inject a keystore for tests; default opens the configured backend. */
+    keystore?: IKeystore;
+    /** Override for the connection-handler logger; defaults to silent. */
+    logger?: (event: BrokerLogEvent) => void;
+}
+interface BrokerLogEvent {
+    level: 'info' | 'warn' | 'error';
+    msg: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Pure-function request handler — given a parsed request, signer, and
+ * keystore, returns the response object. Easy to unit-test without
+ * spawning a socket.
+ */
+declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number): Promise<BrokerResponse>;
+declare class BrokerDaemon {
+    private readonly server;
+    private readonly signer;
+    private readonly log;
+    private readonly config;
+    private keystore;
+    constructor(options: BrokerDaemonOptions);
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    private onConnection;
+    private runAndRespond;
+}
+
+export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type IKeystore, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, NoJwtAvailableError, type RunMcpStdioCliOptions, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, serializeResponse, verifyDescriptorAgainstPin };