@scriptmasterlabs/mcp-x402 2.0.0

package/src/server/health.ts

@@ -0,0 +1,52 @@
+import type { Request, Response } from 'express';
+
+const startTime = Date.now();
+
+export interface HealthStatus {
+  status: 'ok' | 'degraded';
+  version: string;
+  transport: string;
+  uptime_seconds: number;
+  uptime_human: string;
+  timestamp: string;
+  checks: {
+    process: 'ok';
+    memory_mb: number;
+    memory_ok: boolean;
+  };
+}
+
+function formatUptime(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  const m = Math.floor(s / 60);
+  const h = Math.floor(m / 60);
+  const d = Math.floor(h / 24);
+  if (d > 0) return `${d}d ${h % 24}h ${m % 60}m`;
+  if (h > 0) return `${h}h ${m % 60}m ${s % 60}s`;
+  if (m > 0) return `${m}m ${s % 60}s`;
+  return `${s}s`;
+}
+
+export function healthHandler(_req: Request, res: Response): void {
+  const uptimeMs = Date.now() - startTime;
+  const memMb = Math.round(process.memoryUsage().rss / 1024 / 1024);
+  const memOk = memMb < 450; // warn if approaching 512MB container limit
+
+  const body: HealthStatus = {
+    status: memOk ? 'ok' : 'degraded',
+    version: process.env['npm_package_version'] ?? '1.0.0',
+    transport: process.env['MCP_TRANSPORT'] ?? 'stdio',
+    uptime_seconds: Math.floor(uptimeMs / 1000),
+    uptime_human: formatUptime(uptimeMs),
+    timestamp: new Date().toISOString(),
+    checks: {
+      process: 'ok',
+      memory_mb: memMb,
+      memory_ok: memOk,
+    },
+  };
+
+  // Return 200 even if degraded — let the orchestrator decide.
+  // Only return 5xx if the process itself is fundamentally broken.
+  res.status(200).json(body);
+}

package/src/server/index.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import { randomUUID } from 'crypto';
+import cors from 'cors';
+import { registerTools } from './tools/index.js';
+import { AuditLogger } from './security/audit.js';
+import { RateLimiter } from './security/rate-limit.js';
+import { healthHandler } from './health.js';
+
+const VERSION = '1.0.0';
+
+async function createServer(): Promise<McpServer> {
+  const server = new McpServer(
+    { name: 'mcp-x402', version: VERSION },
+    { capabilities: { tools: {} } },
+  );
+  await registerTools(server);
+  return server;
+}
+
+async function runStdio(): Promise<void> {
+  const server = await createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  AuditLogger.getInstance().info('server_start', { transport: 'stdio', version: VERSION });
+
+  const shutdown = async () => {
+    AuditLogger.getInstance().info('server_stop', { transport: 'stdio' });
+    await server.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Keep stdio process alive
+  process.stdin.on('end', () => {
+    AuditLogger.getInstance().warn('stdio_stdin_end', {});
+    process.exit(0);
+  });
+}
+
+async function runSSE(): Promise<void> {
+  const app = express();
+  const port = parseInt(process.env['MCP_SSE_PORT'] ?? '3402', 10);
+
+  app.use(cors({ origin: process.env['CORS_ORIGIN'] ?? '*' }));
+  app.use(express.json({ limit: '1mb' }));
+
+  // Health endpoint
+  app.get('/health', healthHandler);
+
+  app.get('/agents.json', (_req, res) => {
+    res.sendFile('agents.json', { root: process.cwd() });
+  });
+  app.get('/llms.txt', (_req, res) => {
+    res.sendFile('llms.txt', { root: process.cwd() });
+  });
+  app.get('/.well-known/agentcard.json', (_req, res) => {
+    res.sendFile('.well-known/agentcard.json', { root: process.cwd() });
+  });
+
+  // FIX: Root handler — was 404, now returns service discovery
+  app.get('/', (_req, res) => {
+    res.json({
+      name: 'mcp-x402',
+      version: VERSION,
+      description: 'The x402 Amazon — 43+ tools, pay-per-call via XRPL. scriptmasterlabs.com',
+      status: 'online',
+      transport: 'streamable-http + sse',
+      endpoints: {
+        mcp_streamable: 'POST /mcp',
+        sse_connect: 'GET /sse',
+        sse_messages: 'POST /messages',
+        health: 'GET /health',
+        agentCard: 'GET /.well-known/agentcard.json',
+        llms: 'GET /llms.txt',
+      },
+      links: {
+        github: 'https://github.com/Timwal78/SML_Portfolio/tree/main/mcp-x402',
+        homepage: 'https://scriptmasterlabs.com',
+      },
+    });
+  });
+
+  // Streamable HTTP transport — claude.ai web connectors
+  const streamableTransports = new Map<string, StreamableHTTPServerTransport>();
+
+  app.post('/mcp', async (req, res) => {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    let transport = sessionId ? streamableTransports.get(sessionId) : undefined;
+
+    if (!transport) {
+      const newSessionId = randomUUID();
+      transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newSessionId });
+      streamableTransports.set(newSessionId, transport);
+      transport.onclose = () => streamableTransports.delete(newSessionId);
+      const server = await createServer();
+      await server.connect(transport);
+      AuditLogger.getInstance().info('mcp_connect', { sessionId: newSessionId });
+    }
+
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  // FIX: GET /mcp with no session was 404, now returns service info
+  app.get('/mcp', async (req, res) => {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    const transport = sessionId ? streamableTransports.get(sessionId) : undefined;
+    if (!transport) {
+      res.json({
+        name: 'mcp-x402',
+        version: VERSION,
+        protocol: 'MCP/streamable-http',
+        status: 'ready',
+        tools: '43+ tools available',
+        how_to_connect: 'POST /mcp with a JSON-RPC initialize request',
+        sse_alternative: 'GET /sse for legacy SSE transport',
+        health: '/health',
+        homepage: 'https://scriptmasterlabs.com',
+      });
+      return;
+    }
+    await transport.handleRequest(req, res);
+  });
+
+  app.delete('/mcp', async (req, res) => {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    const transport = sessionId ? streamableTransports.get(sessionId) : undefined;
+    if (!transport) { res.status(404).json({ error: 'session_not_found' }); return; }
+    await transport.handleRequest(req, res);
+  });
+
+  const transports = new Map<string, SSEServerTransport>();
+  const rateLimiter = RateLimiter.getInstance();
+
+  app.get('/sse', async (req, res) => {
+    const clientIp = req.ip ?? 'unknown';
+    if (!rateLimiter.checkIp(clientIp)) {
+      res.status(429).json({ error: 'rate_limit_exceeded', retry_after: 60 });
+      return;
+    }
+    const transport = new SSEServerTransport('/messages', res);
+    const sessionId = transport.sessionId;
+    transports.set(sessionId, transport);
+    const server = await createServer();
+    await server.connect(transport);
+    AuditLogger.getInstance().info('sse_connect', { sessionId, clientIp });
+    res.on('close', async () => {
+      transports.delete(sessionId);
+      AuditLogger.getInstance().info('sse_disconnect', { sessionId });
+      await server.close();
+    });
+  });
+
+  app.post('/messages', async (req, res) => {
+    const sessionId = req.query['sessionId'] as string | undefined;
+    if (!sessionId) { res.status(400).json({ error: 'missing_session_id' }); return; }
+    const transport = transports.get(sessionId);
+    if (!transport) { res.status(404).json({ error: 'session_not_found' }); return; }
+    await transport.handlePostMessage(req, res);
+  });
+
+  const httpServer = await new Promise<ReturnType<typeof app.listen>>(
+    (resolve) => {
+      const s = app.listen(port, () => resolve(s));
+    },
+  );
+
+  AuditLogger.getInstance().info('server_start', { transport: 'sse', port, version: VERSION });
+  console.error(`[mcp-x402] listening on :${port} — health: http://localhost:${port}/health`);
+
+  const shutdown = async () => {
+    AuditLogger.getInstance().info('server_stop', { transport: 'sse' });
+    for (const [id] of transports) {
+      AuditLogger.getInstance().info('sse_force_close', { sessionId: id });
+    }
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(1), 10_000).unref();
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  process.on('uncaughtException', (err) => {
+    AuditLogger.getInstance().error('uncaught_exception', { error: String(err), stack: err.stack ?? '' });
+  });
+  process.on('unhandledRejection', (reason) => {
+    AuditLogger.getInstance().error('unhandledRejection', { reason: String(reason) });
+  });
+}
+
+const transport = process.env['MCP_TRANSPORT'] ?? 'stdio';
+if (transport === 'sse') {
+  runSSE().catch((err) => {
+    console.error('[mcp-x402] fatal:', err);
+    process.exit(1);
+  });
+} else {
+  runStdio().catch((err) => {
+    console.error('[mcp-x402] fatal:', err);
+    process.exit(1);
+  });
+}

package/src/server/payments/ap2.ts

@@ -0,0 +1,99 @@
+import { AuditLogger } from '../security/audit.js';
+
+export interface MandateParams {
+  maxAmount: string;
+  currency: string;
+  toolName: string;
+}
+
+interface MandateCache {
+  valid: boolean;
+  expiresAt: number;
+}
+
+// In-memory mandate cache — 5 minute TTL per wallet+tool combination
+const mandateCache = new Map<string, MandateCache>();
+
+export class AP2Client {
+  private static instance: AP2Client;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): AP2Client {
+    if (!AP2Client.instance) {
+      AP2Client.instance = new AP2Client();
+    }
+    return AP2Client.instance;
+  }
+
+  async verifyMandate(wallet: string, params: MandateParams): Promise<boolean> {
+    const cacheKey = `${wallet}:${params.toolName}:${params.currency}`;
+    const cached = mandateCache.get(cacheKey);
+
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.valid;
+    }
+
+    const audit = AuditLogger.getInstance();
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 5000);
+
+      const res = await fetch(`${this.baseUrl}/ap2/v1/mandate/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          wallet,
+          max_amount: params.maxAmount,
+          currency: params.currency,
+          tool: params.toolName,
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeout);
+
+      if (!res.ok) {
+        audit.warn('ap2_mandate_http_error', { status: res.status, wallet });
+        mandateCache.set(cacheKey, { valid: false, expiresAt: Date.now() + 60_000 });
+        return false;
+      }
+
+      const body = (await res.json()) as { valid: boolean; expires_in?: number };
+      const ttl = (body.expires_in ?? 300) * 1000;
+
+      mandateCache.set(cacheKey, { valid: body.valid, expiresAt: Date.now() + ttl });
+      return body.valid;
+    } catch (err) {
+      audit.error('ap2_mandate_error', { error: String(err), wallet });
+      // Fail closed — if AP2 is unreachable, deny payment
+      return false;
+    }
+  }
+
+  async createMandate(
+    wallet: string,
+    params: { dailyCap: string; currency: string },
+  ): Promise<string> {
+    const res = await fetch(`${this.baseUrl}/ap2/v1/mandate/create`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        wallet,
+        daily_cap: params.dailyCap,
+        currency: params.currency,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`AP2 mandate creation failed: HTTP ${res.status}`);
+    }
+
+    const body = (await res.json()) as { mandate_id: string };
+    return body.mandate_id;
+  }
+}

package/src/server/payments/receipt.ts

@@ -0,0 +1,85 @@
+import { createHash, randomUUID } from 'crypto';
+import { AuditLogger } from '../security/audit.js';
+
+export interface ReceiptInput {
+  txHash: string;
+  chain: string;
+  amount: string;
+  currency: string;
+  tool: string;
+  wallet: string;
+}
+
+export interface Receipt {
+  id: string;
+  txHash: string;
+  chain: string;
+  amount: string;
+  currency: string;
+  tool: string;
+  wallet: string;
+  issuedAt: number;
+  hash: string;
+}
+
+export class ReceiptStore {
+  private static instance: ReceiptStore;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): ReceiptStore {
+    if (!ReceiptStore.instance) {
+      ReceiptStore.instance = new ReceiptStore();
+    }
+    return ReceiptStore.instance;
+  }
+
+  async create(input: ReceiptInput): Promise<Receipt> {
+    const id = randomUUID();
+    const issuedAt = Date.now();
+
+    // Content hash for tamper detection
+    const hash = createHash('sha256')
+      .update(`${id}:${input.txHash}:${input.chain}:${input.amount}:${input.currency}:${input.tool}:${input.wallet}:${issuedAt}`)
+      .digest('hex');
+
+    const receipt: Receipt = { id, ...input, issuedAt, hash };
+
+    // Attempt to register with 402Proof server (N7)
+    try {
+      await this.registerWithProofServer(receipt);
+    } catch (err) {
+      // Log but don't fail — local receipt is still valid
+      AuditLogger.getInstance().warn('proof_server_register_fail', { error: String(err), receiptId: id });
+    }
+
+    AuditLogger.getInstance().info('receipt_issued', { receiptId: id, tool: input.tool });
+    return receipt;
+  }
+
+  private async registerWithProofServer(receipt: Receipt): Promise<void> {
+    const proofUrl = process.env['PROOF402_URL'] ?? 'https://four02proof.onrender.com';
+    const res = await fetch(`${proofUrl}/v1/receipt`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        receipt_id: receipt.id,
+        tx_hash: receipt.txHash,
+        chain: receipt.chain,
+        amount: receipt.amount,
+        currency: receipt.currency,
+        tool: receipt.tool,
+        wallet: receipt.wallet,
+        issued_at: receipt.issuedAt,
+        hash: receipt.hash,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`402Proof server returned HTTP ${res.status}`);
+    }
+  }
+}

package/src/server/payments/router.ts

@@ -0,0 +1,110 @@
+import { AuditLogger } from '../security/audit.js';
+import { BaseChain } from '../../lib/chains/base.js';
+import { XRPLChain } from '../../lib/chains/xrpl.js';
+import { SolanaChain } from '../../lib/chains/solana.js';
+
+export interface RouteParams {
+  amount: string;
+  currency: 'USDC' | 'RLUSD';
+  from: string;
+  to: string;
+  timeoutMs?: number;
+}
+
+export interface RouteResult {
+  txHash: string;
+  chain: string;
+  latencyMs: number;
+}
+
+// Chain preference order: cheapest/fastest first (N13)
+const CHAIN_PREFERENCE = ['base', 'xrpl', 'solana'] as const;
+
+export class ChainRouter {
+  private static instance: ChainRouter;
+
+  private constructor(
+    private readonly base = BaseChain.getInstance(),
+    private readonly xrpl = XRPLChain.getInstance(),
+    private readonly solana = SolanaChain.getInstance(),
+  ) {}
+
+  static getInstance(): ChainRouter {
+    if (!ChainRouter.instance) {
+      ChainRouter.instance = new ChainRouter();
+    }
+    return ChainRouter.instance;
+  }
+
+  async route(params: RouteParams): Promise<RouteResult> {
+    const audit = AuditLogger.getInstance();
+    const timeout = params.timeoutMs ?? 3000;
+
+    // For RLUSD, prefer XRPL
+    const ordered =
+      params.currency === 'RLUSD'
+        ? (['xrpl', 'base', 'solana'] as const)
+        : CHAIN_PREFERENCE;
+
+    const errors: string[] = [];
+
+    for (const chain of ordered) {
+      try {
+        const start = Date.now();
+        let txHash: string;
+
+        switch (chain) {
+          case 'base':
+            txHash = await this.withTimeout(
+              this.base.sendPayment(params),
+              timeout,
+              'base',
+            );
+            break;
+          case 'xrpl':
+            txHash = await this.withTimeout(
+              this.xrpl.sendPayment(params),
+              timeout,
+              'xrpl',
+            );
+            break;
+          case 'solana':
+            txHash = await this.withTimeout(
+              this.solana.sendPayment(params),
+              timeout,
+              'solana',
+            );
+            break;
+        }
+
+        const latencyMs = Date.now() - start;
+        audit.info('chain_route_success', { chain, latencyMs, tx: txHash });
+
+        return { txHash, chain, latencyMs };
+      } catch (err) {
+        const msg = String(err);
+        errors.push(`${chain}: ${msg}`);
+        audit.warn('chain_route_fail', { chain, error: msg });
+      }
+    }
+
+    throw new Error(`All chains failed.\n${errors.join('\n')}`);
+  }
+
+  private withTimeout<T>(
+    promise: Promise<T>,
+    ms: number,
+    chain: string,
+  ): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const t = setTimeout(
+        () => reject(new Error(`${chain} timeout after ${ms}ms`)),
+        ms,
+      );
+      promise.then(
+        (v) => { clearTimeout(t); resolve(v); },
+        (e) => { clearTimeout(t); reject(e); },
+      );
+    });
+  }
+}

package/src/server/payments/wallet.ts

@@ -0,0 +1,123 @@
+import { AuditLogger } from '../security/audit.js';
+
+const KEYCHAIN_SERVICE = 'mcp-x402';
+const KEYCHAIN_ACCOUNT = 'master-seed';
+
+export interface WalletInfo {
+  address: string;
+  chain: 'base' | 'xrpl' | 'solana';
+}
+
+export class WalletManager {
+  private static instance: WalletManager;
+  private cachedAddress: string | null = null;
+  private cachedSeed: string | null = null;
+
+  private constructor() {}
+
+  static getInstance(): WalletManager {
+    if (!WalletManager.instance) {
+      WalletManager.instance = new WalletManager();
+    }
+    return WalletManager.instance;
+  }
+
+  // Try OS keychain; returns null if keytar is unavailable (Docker/cloud) or no entry exists.
+  private async keytarGet(): Promise<string | null> {
+    try {
+      const kt = await import('keytar');
+      return await kt.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    } catch {
+      return null;
+    }
+  }
+
+  private async keytarSet(value: string): Promise<void> {
+    try {
+      const kt = await import('keytar');
+      await kt.setPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, value);
+    } catch {
+      // Silently skip — keytar unavailable in this environment
+    }
+  }
+
+  // Seed resolution priority:
+  // 1. OS keychain (local desktop — most secure)
+  // 2. WALLET_SEED env var (Render secret — cloud/Docker deployment)
+  // 3. CI_WALLET_SEED env var (CI only, never production)
+  // 4. Generate fresh and try to persist in keychain
+  async getSeed(): Promise<string> {
+    if (this.cachedSeed) return this.cachedSeed;
+
+    const audit = AuditLogger.getInstance();
+
+    let seed = await this.keytarGet();
+
+    if (!seed) {
+      const envSeed = process.env['WALLET_SEED'];
+      if (envSeed) {
+        seed = envSeed;
+        audit.warn('wallet_env_seed', { note: 'Using WALLET_SEED env var (cloud deployment).' });
+      } else if (process.env['CI_WALLET_SEED'] && process.env['NODE_ENV'] !== 'production') {
+        seed = process.env['CI_WALLET_SEED'];
+        audit.warn('wallet_ci_fallback', { note: 'Using CI_WALLET_SEED. NEVER do this in production.' });
+      } else {
+        const { generateMnemonic } = await import('bip39');
+        seed = generateMnemonic(256);
+        await this.keytarSet(seed);
+        audit.info('wallet_created', { note: 'New BIP-39 seed generated.' });
+      }
+    }
+
+    this.cachedSeed = seed;
+    return seed;
+  }
+
+  async getOrCreateWallet(): Promise<WalletInfo> {
+    if (this.cachedAddress) {
+      return { address: this.cachedAddress, chain: 'base' };
+    }
+
+    const audit = AuditLogger.getInstance();
+    const seed = await this.getSeed();
+    const address = await this.deriveAddress(seed);
+    this.cachedAddress = address;
+    audit.info('wallet_loaded', { address });
+    return { address, chain: 'base' };
+  }
+
+  private async deriveAddress(mnemonic: string): Promise<string> {
+    // BIP-44 deterministic derivation: m/44'/60'/0'/0/0 (Base = EVM)
+    const { mnemonicToSeedSync } = await import('bip39');
+    const { default: HDKey } = await import('hdkey');
+    const { privateKeyToAccount } = await import('viem/accounts');
+
+    const seed = mnemonicToSeedSync(mnemonic);
+    const hdkey = HDKey.fromMasterSeed(seed);
+    const child = hdkey.derive("m/44'/60'/0'/0/0");
+
+    if (!child.privateKey) {
+      throw new Error('Failed to derive private key from HD path');
+    }
+
+    const account = privateKeyToAccount(`0x${child.privateKey.toString('hex')}`);
+    return account.address;
+  }
+
+  async signPayload(payload: string): Promise<string> {
+    const mnemonic = await this.getSeed();
+
+    const { mnemonicToSeedSync } = await import('bip39');
+    const { default: HDKey } = await import('hdkey');
+    const { privateKeyToAccount } = await import('viem/accounts');
+
+    const seed = mnemonicToSeedSync(mnemonic);
+    const hdkey = HDKey.fromMasterSeed(seed);
+    const child = hdkey.derive("m/44'/60'/0'/0/0");
+
+    if (!child.privateKey) throw new Error('Key derivation failed');
+
+    const account = privateKeyToAccount(`0x${child.privateKey.toString('hex')}`);
+    return account.signMessage({ message: payload });
+  }
+}