@shroud-fi/mcp-server 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Model Context Protocol server for ShroudFi. 9 tools any MCP-aware AI agent host can call — Claude Code, Cursor, Windsurf, Zed.",
   "keywords": [
     "shroudfi",
@@ -41,17 +41,20 @@
     "shroudfi-mcp": "./dist/esm/bin/stdio.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "zod": "^3.23.0",
-    "@shroud-fi/scanning": "0.1.2",
-    "@shroud-fi/agent-runtime": "0.1.5",
-    "@shroud-fi/core": "0.1.2",
-    "@shroud-fi/x402": "0.1.4",
-    "@shroud-fi/payments": "0.1.2",
-    "@shroud-fi/transport": "0.1.3"
+    "@shroud-fi/agent-runtime": "0.1.6",
+    "@shroud-fi/core": "0.1.3",
+    "@shroud-fi/x402": "0.1.5",
+    "@shroud-fi/transport": "0.1.4",
+    "@shroud-fi/scanning": "0.1.3",
+    "@shroud-fi/payments": "0.1.3"
   },
   "peerDependencies": {
     "viem": "^2.21.0"

package/src/auth.ts

@@ -0,0 +1,129 @@
+/**
+ * EIP-191 challenge-response auth for the HTTP transport.
+ *
+ * Flow:
+ *   1. Client POSTs /auth/challenge with their wallet address.
+ *   2. Server returns a fresh nonce + a canonical message string.
+ *   3. Client signs message with personal_sign / signMessage (EIP-191).
+ *   4. Client sends every subsequent request with:
+ *        X-Shroudfi-Wallet:    <0x… EOA>
+ *        X-Shroudfi-Nonce:     <nonce returned at step 2>
+ *        X-Shroudfi-Signature: <0x… hex sig>
+ *   5. Server recovers, checks address match + expiry + allow-list.
+ *
+ * The signature is single-shot — once verifyAndConsume returns true for a
+ * nonce, the cache entry is deleted, so the same signed challenge cannot be
+ * replayed.
+ *
+ * Privacy: signature bytes never appear in logs, error messages, or response
+ * bodies. Errors are short tags only.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { recoverMessageAddress } from 'viem';
+import type { Hex } from 'viem';
+import { EIP191_CHALLENGE_TTL_MS } from './constants.js';
+import {
+  McpEip191ChallengeExpiredError,
+  McpEip191SignatureInvalidError,
+  McpUnauthorizedError,
+} from './errors.js';
+import type { Eip191Challenge } from './types.js';
+
+export interface AuthCache {
+  issue(wallet: `0x${string}`): Eip191Challenge;
+  verifyAndConsume(args: {
+    wallet: `0x${string}`;
+    nonce: Hex;
+    signature: Hex;
+  }): Promise<void>;
+  /** Test seam — drop expired entries. Called automatically on every op. */
+  prune(now?: number): void;
+  /** Returns the current size — test seam. */
+  size(): number;
+}
+
+const SHROUDFI_DOMAIN_MARK = 'ShroudFi MCP HTTP authentication';
+
+function buildMessage(wallet: `0x${string}`, nonce: Hex, issuedAtMs: number): string {
+  // The message is deliberately self-describing so a wallet UI shows the
+  // user the exact intent before signing. The nonce is the only random
+  // piece — it ties the signature to a single server-issued challenge.
+  return [
+    SHROUDFI_DOMAIN_MARK,
+    `Wallet: ${wallet}`,
+    `Nonce: ${nonce}`,
+    `Issued: ${new Date(issuedAtMs).toISOString()}`,
+    'Sign to prove control of this wallet.',
+  ].join('\n');
+}
+
+export function createAuthCache(
+  ttlMs: number = EIP191_CHALLENGE_TTL_MS,
+): AuthCache {
+  const store = new Map<string, Eip191Challenge>();
+
+  function makeKey(wallet: `0x${string}`, nonce: Hex): string {
+    return `${wallet.toLowerCase()}|${nonce.toLowerCase()}`;
+  }
+
+  function prune(now: number = Date.now()): void {
+    for (const [k, v] of store) {
+      if (v.expiresAtMs <= now) store.delete(k);
+    }
+  }
+
+  return {
+    issue(wallet) {
+      prune();
+      const nonceBytes = randomBytes(16);
+      const nonce: Hex = `0x${nonceBytes.toString('hex')}`;
+      const now = Date.now();
+      const ch: Eip191Challenge = {
+        wallet: wallet.toLowerCase() as `0x${string}`,
+        nonce,
+        issuedAtMs: now,
+        expiresAtMs: now + ttlMs,
+        message: buildMessage(wallet.toLowerCase() as `0x${string}`, nonce, now),
+      };
+      store.set(makeKey(ch.wallet, ch.nonce), ch);
+      return ch;
+    },
+
+    async verifyAndConsume({ wallet, nonce, signature }) {
+      // Don't prune before lookup — we want callers to see the explicit
+      // `auth_challenge_expired` code when their nonce has timed out, instead
+      // of an indistinguishable `unauthorized`.
+      const key = makeKey(wallet, nonce);
+      const ch = store.get(key);
+      if (ch === undefined) {
+        throw new McpUnauthorizedError();
+      }
+      if (ch.expiresAtMs <= Date.now()) {
+        store.delete(key);
+        throw new McpEip191ChallengeExpiredError();
+      }
+
+      let recovered: `0x${string}`;
+      try {
+        recovered = await recoverMessageAddress({
+          message: ch.message,
+          signature,
+        });
+      } catch {
+        throw new McpEip191SignatureInvalidError();
+      }
+      if (recovered.toLowerCase() !== ch.wallet.toLowerCase()) {
+        throw new McpEip191SignatureInvalidError();
+      }
+
+      // Single-use: consume the nonce so the signed challenge can't be replayed.
+      store.delete(key);
+    },
+
+    prune,
+    size: () => store.size,
+  };
+}
+
+export const __auth_test__ = { buildMessage };

package/src/bin/http.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * HTTP transport bin. Reads SHROUDFI_MCP_HTTP_PORT (default 7070) via the
+ * config module, boots the HTTP server, parks until SIGINT/SIGTERM.
+ */
+
+import { runHttpServer } from '../http.js';
+import { readHttpPortFromEnv } from '../config.js';
+
+const port = readHttpPortFromEnv();
+
+runHttpServer({ port })
+  .then((handle) => {
+    process.stderr.write(`shroudfi-mcp-http listening on :${port}\n`);
+    const shutdown = (): void => {
+      void handle.close().then(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  })
+  .catch((err: unknown) => {
+    process.stderr.write(
+      `shroudfi-mcp-http failed: ${(err as { code?: string }).code ?? 'unknown'}\n`,
+    );
+    process.exitCode = 1;
+  });

package/src/bin/stdio.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Stdio bin — invoked by MCP clients via `.mcp.json` `command` field.
+ *
+ * Errors go to stderr only — stdout is reserved for the JSON-RPC framed
+ * MCP protocol stream. Any stdout pollution corrupts the client.
+ */
+
+import { runStdioServer } from '../stdio.js';
+
+runStdioServer().catch((err: unknown) => {
+  process.stderr.write(
+    `shroudfi-mcp stdio failed: ${(err as { code?: string }).code ?? 'unknown'}\n`,
+  );
+  process.exitCode = 1;
+});

package/src/config.ts

@@ -0,0 +1,198 @@
+/**
+ * Resolve operator config from env (or explicit args) into a runtime context.
+ *
+ * Env reads concentrated here per verify-privacy R5. Allowed to use process.env.
+ */
+
+import { readFileSync } from 'node:fs';
+import type { Hex } from 'viem';
+import { hexToBytes, isHex } from 'viem';
+import { createTransport, getShroudFiStealth } from '@shroud-fi/transport';
+import { createShroudAgent } from '@shroud-fi/agent-runtime';
+import {
+  DEFAULT_RPC_URL_BY_CHAIN,
+  ENV_CHAIN,
+  ENV_HTTP_ALLOWED_WALLETS,
+  ENV_HTTP_PORT,
+  ENV_MASTER_SEED,
+  ENV_MASTER_SEED_FILE,
+  ENV_PRIVATE_KEY,
+  ENV_PRIVATE_KEY_FILE,
+  ENV_RPC_URL,
+  ENV_START_BLOCK,
+} from './constants.js';
+import { McpConfigError } from './errors.js';
+import type {
+  McpServerBootstrapConfig,
+  McpServerContext,
+} from './types.js';
+
+function readChain(): number {
+  const v = process.env[ENV_CHAIN];
+  if (v === undefined || v === '') return 8453;
+  if (v === 'base' || v === 'mainnet' || v === '8453') return 8453;
+  if (v === 'sepolia' || v === 'base-sepolia' || v === '84532') return 84532;
+  throw new McpConfigError('Unknown chain — set SHROUDFI_CHAIN to base|sepolia');
+}
+
+function readPrivateKey(): Hex | undefined {
+  const inline = process.env[ENV_PRIVATE_KEY];
+  if (typeof inline === 'string' && inline.length > 0) {
+    if (!isHex(inline) || inline.length !== 66) {
+      throw new McpConfigError('SHROUDFI_PRIVATE_KEY is not a 0x… 32-byte hex');
+    }
+    return inline as Hex;
+  }
+  const file = process.env[ENV_PRIVATE_KEY_FILE];
+  if (typeof file === 'string' && file.length > 0) {
+    let raw: string;
+    try {
+      raw = readFileSync(file, 'utf-8').trim();
+    } catch {
+      throw new McpConfigError('SHROUDFI_PRIVATE_KEY_FILE could not be read');
+    }
+    if (!isHex(raw) || raw.length !== 66) {
+      throw new McpConfigError('Private key file contents are not a 0x… 32-byte hex');
+    }
+    return raw as Hex;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the optional 32-byte master seed from env. Accepts either an inline
+ * 0x… hex string or a path to a file containing one (same shape as the
+ * private-key resolution). Returns `undefined` when neither is set so callers
+ * can fall back to per-process random seeds.
+ */
+function readMasterSeed(): Uint8Array | undefined {
+  const inline = process.env[ENV_MASTER_SEED];
+  if (typeof inline === 'string' && inline.length > 0) {
+    if (!isHex(inline) || inline.length !== 66) {
+      throw new McpConfigError('SHROUDFI_MASTER_SEED is not a 0x… 32-byte hex');
+    }
+    return hexToBytes(inline as Hex);
+  }
+  const file = process.env[ENV_MASTER_SEED_FILE];
+  if (typeof file === 'string' && file.length > 0) {
+    let raw: string;
+    try {
+      raw = readFileSync(file, 'utf-8').trim();
+    } catch {
+      throw new McpConfigError('SHROUDFI_MASTER_SEED_FILE could not be read');
+    }
+    if (!isHex(raw) || raw.length !== 66) {
+      throw new McpConfigError('Master seed file contents are not a 0x… 32-byte hex');
+    }
+    return hexToBytes(raw as Hex);
+  }
+  return undefined;
+}
+
+function readStartBlock(): bigint {
+  const v = process.env[ENV_START_BLOCK];
+  if (v === undefined || v === '') return 0n;
+  try {
+    return BigInt(v);
+  } catch {
+    throw new McpConfigError('SHROUDFI_START_BLOCK must be a non-negative integer');
+  }
+}
+
+function readHttpAllowedWallets(): ReadonlySet<`0x${string}`> {
+  const v = process.env[ENV_HTTP_ALLOWED_WALLETS];
+  if (v === undefined || v === '') return new Set();
+  const out = new Set<`0x${string}`>();
+  for (const piece of v.split(',')) {
+    const trimmed = piece.trim().toLowerCase();
+    if (trimmed.length === 0) continue;
+    if (!isHex(trimmed) || trimmed.length !== 42) {
+      throw new McpConfigError(
+        'SHROUDFI_MCP_HTTP_ALLOWED_WALLETS contains a non-address entry',
+      );
+    }
+    out.add(trimmed as `0x${string}`);
+  }
+  return out;
+}
+
+/**
+ * Read the HTTP port the operator wants the MCP server to listen on. Defaults
+ * to 7070. Strict integer between 1 and 65535.
+ */
+export function readHttpPortFromEnv(defaultPort = 7070): number {
+  const raw = process.env[ENV_HTTP_PORT];
+  if (raw === undefined || raw.length === 0) return defaultPort;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new McpConfigError('SHROUDFI_MCP_HTTP_PORT must be 1..65535');
+  }
+  return port;
+}
+
+/**
+ * Resolve env into a fully-formed bootstrap config.
+ */
+export function loadBootstrapConfigFromEnv(): McpServerBootstrapConfig {
+  const chainId = readChain();
+  const rpcOverride = process.env[ENV_RPC_URL];
+  const rpcUrl =
+    rpcOverride !== undefined && rpcOverride.length > 0
+      ? rpcOverride
+      : DEFAULT_RPC_URL_BY_CHAIN[chainId];
+  if (rpcUrl === undefined) {
+    throw new McpConfigError('No RPC URL resolved for the requested chain');
+  }
+  return {
+    chainId,
+    rpcUrl,
+    privateKey: readPrivateKey(),
+    startBlock: readStartBlock(),
+    masterSeed: readMasterSeed(),
+    httpAllowedWallets: readHttpAllowedWallets(),
+  };
+}
+
+/**
+ * Build a McpServerContext from a resolved bootstrap config.
+ *
+ * Throws McpConfigError if the chain is unknown to @shroud-fi/transport.
+ */
+export function buildContextFromConfig(
+  config: McpServerBootstrapConfig,
+): McpServerContext {
+  const chainName = config.chainId === 8453 ? 'base' : 'baseSepolia';
+
+  const transport = createTransport({
+    chain: chainName as 'base' | 'baseSepolia',
+    rpcUrl: config.rpcUrl,
+    ...(config.privateKey !== undefined
+      ? { privateKey: config.privateKey }
+      : {}),
+  });
+
+  // Will throw UnknownChainError if no manifest entry — surface as config error.
+  let stealthContract: `0x${string}`;
+  try {
+    stealthContract = getShroudFiStealth(config.chainId);
+  } catch {
+    throw new McpConfigError('No ShroudFiStealth deployment for the chain');
+  }
+
+  const agent = createShroudAgent({
+    transport,
+    startBlock: config.startBlock,
+    stealthContract,
+    autoRegister: true,
+    ...(config.masterSeed !== undefined ? { masterSeed: config.masterSeed } : {}),
+  });
+
+  const walletAddress = transport.walletClient?.account?.address;
+
+  return {
+    agent,
+    transport,
+    chainId: config.chainId,
+    walletAddress,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,35 @@
+/**
+ * Static constants. All env reads live here per verify-privacy R5.
+ */
+
+export const SHROUDFI_MCP_SERVER_NAME = 'shroudfi-mcp' as const;
+export const SHROUDFI_MCP_SERVER_VERSION = '0.0.1' as const;
+
+/** EIP-191 challenge TTL — short window so a replayed challenge dies fast. */
+export const EIP191_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+
+/** Default RPC URLs by chain id. Operator override via SHROUDFI_RPC_URL. */
+export const DEFAULT_RPC_URL_BY_CHAIN: Record<number, string> = {
+  8453: 'https://mainnet.base.org',
+  84532: 'https://sepolia.base.org',
+};
+
+/** Env knobs the bootstrap surface reads. */
+export const ENV_PRIVATE_KEY = 'SHROUDFI_PRIVATE_KEY' as const;
+export const ENV_PRIVATE_KEY_FILE = 'SHROUDFI_PRIVATE_KEY_FILE' as const;
+export const ENV_RPC_URL = 'SHROUDFI_RPC_URL' as const;
+export const ENV_CHAIN = 'SHROUDFI_CHAIN' as const;
+export const ENV_START_BLOCK = 'SHROUDFI_START_BLOCK' as const;
+export const ENV_HTTP_PORT = 'SHROUDFI_MCP_HTTP_PORT' as const;
+export const ENV_HTTP_ALLOWED_WALLETS = 'SHROUDFI_MCP_HTTP_ALLOWED_WALLETS' as const;
+/**
+ * Deterministic 32-byte master seed (0x… 64 hex chars). When set, every
+ * boot of the MCP server, REST API, or any other surface using
+ * `loadBootstrapConfigFromEnv` resolves the SAME stealth meta-address for
+ * the same operator EOA. When unset, a fresh random seed is generated per
+ * process — fine for local testing, BAD for production multi-surface
+ * deployments (caller's main wallet ↔ stealth meta-address binding would
+ * desync between MCP, REST, and UI processes).
+ */
+export const ENV_MASTER_SEED = 'SHROUDFI_MASTER_SEED' as const;
+export const ENV_MASTER_SEED_FILE = 'SHROUDFI_MASTER_SEED_FILE' as const;

package/src/errors.ts

@@ -0,0 +1,68 @@
+/**
+ * Errors for @shroud-fi/mcp-server.
+ *
+ * Privacy invariants:
+ *   - No private keys, signatures, or amounts in error messages.
+ *   - No wallet addresses concatenated into `.message` strings — addresses
+ *     are exposed on dedicated structured fields when needed.
+ */
+
+export class McpServerError extends Error {
+  override readonly name: string = 'McpServerError';
+  readonly code: string;
+  constructor(message: string, code: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export class McpConfigError extends McpServerError {
+  override readonly name = 'McpConfigError';
+  constructor(message: string) {
+    super(message, 'config_invalid');
+  }
+}
+
+export class McpUnauthorizedError extends McpServerError {
+  override readonly name = 'McpUnauthorizedError';
+  constructor() {
+    super('Unauthorized', 'unauthorized');
+  }
+}
+
+export class McpToolNotFoundError extends McpServerError {
+  override readonly name = 'McpToolNotFoundError';
+  constructor() {
+    super('Tool not found', 'tool_not_found');
+  }
+}
+
+export class McpInvalidArgsError extends McpServerError {
+  override readonly name = 'McpInvalidArgsError';
+  constructor() {
+    super('Invalid tool arguments', 'invalid_args');
+  }
+}
+
+export class McpExecutionError extends McpServerError {
+  override readonly name = 'McpExecutionError';
+  readonly cause: unknown;
+  constructor(cause: unknown) {
+    super('Tool execution failed', 'execution_failed');
+    this.cause = cause;
+  }
+}
+
+export class McpEip191ChallengeExpiredError extends McpServerError {
+  override readonly name = 'McpEip191ChallengeExpiredError';
+  constructor() {
+    super('EIP-191 challenge expired', 'auth_challenge_expired');
+  }
+}
+
+export class McpEip191SignatureInvalidError extends McpServerError {
+  override readonly name = 'McpEip191SignatureInvalidError';
+  constructor() {
+    super('EIP-191 signature invalid', 'auth_signature_invalid');
+  }
+}