auramaxx 1.0.0-alpha.4

package/server/mcp/tools.ts

@@ -0,0 +1,523 @@
+/**
+ * MCP Tool Definitions
+ * ====================
+ * Provider-agnostic tool definitions + HTTP handler for executing wallet API calls.
+ * Single source of truth — both the MCP server and SDK tool-use loop read from here.
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { publicEncrypt, constants, generateKeyPairSync } from 'crypto';
+import { z } from 'zod';
+import { getErrorMessage } from '../lib/error';
+
+/** Provider-agnostic tool definition */
+export interface ToolDef {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+/** All available tools */
+export const TOOLS: ToolDef[] = [
+  {
+    name: 'create_vault',
+    description:
+      'Create a new wallet vault with a password. Only one primary vault can exist — returns error if one already exists. Returns the vault address, seed phrase (mnemonic), and admin token. Store the password securely (e.g. in env as AURA_VAULT_PASSWORD) for future unlock via POST /unlock. The MCP server auto-activates the returned token for the current session.',
+    parameters: {
+      type: 'object',
+      properties: {
+        password: {
+          type: 'string',
+          description: 'Password to encrypt the vault (minimum 8 characters)',
+        },
+      },
+      required: ['password'],
+    },
+  },
+  {
+    name: 'wallet_api',
+    description:
+      'Call the AuraWallet API. Common endpoints: GET /wallets, GET /token/search?q=PEPE&chain=base (find contract by ticker/name), POST /wallet/create, POST /send, POST /swap, POST /fund, GET /token/:tokenAddress/balance/:walletAddress (check any address\'s token balance). If you have no token yet, use socket bootstrap (preferred) or set AURA_TOKEN for CI/ops. Read the docs://api resource for the full endpoint reference.',
+    parameters: {
+      type: 'object',
+      properties: {
+        method: {
+          type: 'string',
+          enum: ['GET', 'POST', 'PUT', 'DELETE'],
+          description: 'HTTP method',
+        },
+        endpoint: {
+          type: 'string',
+          description: 'API path, e.g. /wallets',
+        },
+        body: {
+          type: 'object',
+          description: 'POST request body (optional)',
+        },
+      },
+      required: ['method', 'endpoint'],
+    },
+  },
+  {
+    name: 'request_human_action',
+    description:
+      'Request human approval for a privileged wallet action. Use this when wallet_api returns 403 (insufficient permissions). The human sees the summary and approves or rejects. On approval the action is auto-executed with a scoped temporary token.',
+    parameters: {
+      type: 'object',
+      properties: {
+        summary: {
+          type: 'string',
+          description: 'Human-readable description of the action (shown in approval card)',
+        },
+        permissions: {
+          type: 'array',
+          description: 'Permission strings needed, e.g. ["swap"], ["send:hot"], ["fund"]',
+        },
+        action: {
+          type: 'object',
+          description: 'Pre-computed API call: { endpoint: "/swap", method: "POST", body: {...} }',
+        },
+        limits: {
+          type: 'object',
+          description: 'Spending caps per permission in native currency, e.g. { swap: 0.01 }',
+        },
+        walletAccess: {
+          type: 'array',
+          description: 'Wallet addresses the temporary token needs access to, e.g. ["0x123...", "0x456..."]',
+        },
+        ttl: {
+          type: 'number',
+          description: 'Seconds the temporary token lives (default 60)',
+        },
+        pubkey: {
+          type: 'string',
+          description: 'Agent RSA public key (PEM or base64). If omitted, MCP generates an ephemeral key for this request.',
+        },
+      },
+      required: ['summary', 'permissions', 'action'],
+    },
+  },
+];
+
+/**
+ * Convert JSON Schema properties to Zod schema shape.
+ * Used by the MCP server to bridge provider-agnostic tool defs with the MCP SDK's Zod requirement.
+ */
+export function jsonSchemaToZod(
+  props: Record<string, unknown>,
+  requiredFields: string[],
+): Record<string, z.ZodTypeAny> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+  const required = new Set(requiredFields);
+
+  for (const [key, schema] of Object.entries(props)) {
+    const s = schema as Record<string, unknown>;
+    let zodType: z.ZodTypeAny;
+
+    if (s.type === 'string') {
+      zodType = s.enum
+        ? z.enum(s.enum as [string, ...string[]])
+        : z.string();
+    } else if (s.type === 'object') {
+      zodType = z.record(z.unknown());
+    } else if (s.type === 'array') {
+      zodType = z.array(z.unknown());
+    } else if (s.type === 'number') {
+      zodType = z.number();
+    } else {
+      zodType = z.unknown();
+    }
+
+    if (s.description) {
+      zodType = zodType.describe(s.description as string);
+    }
+
+    shape[key] = required.has(key) ? zodType : zodType.optional();
+  }
+
+  return shape;
+}
+
+/** Base URL for the wallet server (configurable for testing) */
+const WALLET_BASE_URL = process.env.WALLET_SERVER_URL || 'http://127.0.0.1:4242';
+
+/** Max response size to prevent context bloat */
+const MAX_RESPONSE_SIZE = 4096;
+
+/** Timeout per tool call */
+const TOOL_TIMEOUT_MS = 10_000;
+
+function generateAgentPubkeyPem(): string {
+  const pair = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return pair.publicKey;
+}
+
+/**
+ * Permission → allowed endpoint prefixes.
+ * Prevents a app from disguising e.g. a /send as a /swap request.
+ */
+const PERMISSION_ENDPOINT_MAP: Record<string, string[]> = {
+  'swap': ['/swap'],
+  'send:hot': ['/send'],
+  'send:temp': ['/send'],
+  'fund': ['/fund'],
+  'launch': ['/launch'],
+  'wallet:create:hot': ['/wallet/create'],
+  'wallet:create:temp': ['/wallet/create'],
+  'wallet:list': ['/wallets', '/wallet/', '/wallets/transactions'],
+  'wallet:rename': ['/wallet/rename'],
+};
+
+/**
+ * Reverse mapping: endpoint prefix → required permissions.
+ * Used to catch wrong/unknown permission strings for known endpoints.
+ */
+const ENDPOINT_REQUIRED_PERMISSIONS: Record<string, string[]> = {
+  '/swap': ['swap'],
+  '/send': ['send:hot', 'send:temp'],
+  '/fund': ['fund'],
+  '/launch': ['launch'],
+  '/wallet/create': ['wallet:create:hot', 'wallet:create:temp'],
+};
+
+/**
+ * Validate that requested permissions match the action endpoint.
+ * Returns an error message if invalid, null if ok.
+ *
+ * Two-pass validation:
+ * 1. Forward check: mapped permissions must match the endpoint prefix
+ * 2. Reverse check: known endpoints must have at least one correct permission
+ */
+export function validatePermissionEndpoint(
+  permissions: string[],
+  endpoint: string,
+): string | null {
+  for (const perm of permissions) {
+    const allowed = PERMISSION_ENDPOINT_MAP[perm];
+    if (!allowed) continue; // Unknown permission — check reverse below
+    const match = allowed.some((prefix) => endpoint.startsWith(prefix));
+    if (match) return null; // At least one permission matches the endpoint
+  }
+  // If we have mapped permissions but none matched, reject
+  const mappedPerms = permissions.filter((p) => PERMISSION_ENDPOINT_MAP[p]);
+  if (mappedPerms.length > 0) {
+    // Find expected permissions for this endpoint
+    for (const [prefix, required] of Object.entries(ENDPOINT_REQUIRED_PERMISSIONS)) {
+      if (endpoint.startsWith(prefix)) {
+        return `Permission(s) [${mappedPerms.join(', ')}] do not match endpoint ${endpoint}. Expected one of: [${required.join(', ')}]`;
+      }
+    }
+    return `Permission(s) [${mappedPerms.join(', ')}] do not match endpoint ${endpoint}`;
+  }
+
+  // Reverse check: if the endpoint has known requirements, verify at least one is requested
+  for (const [prefix, required] of Object.entries(ENDPOINT_REQUIRED_PERMISSIONS)) {
+    if (endpoint.startsWith(prefix)) {
+      const hasRequired = required.some((r) => permissions.includes(r));
+      if (!hasRequired) {
+        return `Endpoint ${endpoint} requires one of [${required.join(', ')}] but got [${permissions.join(', ')}]`;
+      }
+      return null;
+    }
+  }
+
+  return null; // No mapped permissions and unknown endpoint — let server enforce
+}
+
+/** Format for Anthropic SDK */
+export function toAnthropicTools(): Anthropic.Tool[] {
+  return TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: {
+      type: t.parameters.type as 'object',
+      properties: t.parameters.properties,
+      required: t.parameters.required,
+    },
+  }));
+}
+
+/** Format for OpenAI SDK */
+export function toOpenAITools(): Array<{
+  type: 'function';
+  function: { name: string; description: string; parameters: ToolDef['parameters'] };
+}> {
+  return TOOLS.map((t) => ({
+    type: 'function' as const,
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  }));
+}
+
+/**
+ * Execute a tool call — makes HTTP request to wallet server.
+ * Validates endpoint, enforces timeout, truncates response.
+ */
+export async function executeTool(
+  toolName: string,
+  input: Record<string, unknown>,
+  token?: string,
+): Promise<string> {
+  if (toolName === 'create_vault') {
+    return executeCreateVault(input);
+  }
+
+  if (toolName === 'request_human_action') {
+    return executeRequestHumanAction(input, token);
+  }
+
+  if (toolName !== 'wallet_api') {
+    return JSON.stringify({ error: `Unknown tool: ${toolName}` });
+  }
+
+  return executeWalletApi(input, token);
+}
+
+/**
+ * Handle create_vault tool — creates a new vault with RSA-encrypted password.
+ * Fetches the server's public key, encrypts the password, and calls POST /setup.
+ */
+async function executeCreateVault(
+  input: Record<string, unknown>,
+): Promise<string> {
+  const { password } = input as { password?: string };
+
+  if (!password || typeof password !== 'string') {
+    return JSON.stringify({ error: 'password is required' });
+  }
+  if (password.length < 8) {
+    return JSON.stringify({ error: 'Password must be at least 8 characters' });
+  }
+
+  // Step 1: Fetch server's RSA public key
+  let publicKeyPem: string;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);
+    const res = await fetch(`${WALLET_BASE_URL}/auth/connect`, { signal: controller.signal });
+    clearTimeout(timeout);
+    const data = await res.json() as { publicKey: string };
+    publicKeyPem = data.publicKey;
+  } catch (err) {
+    const msg = getErrorMessage(err);
+    if (msg.includes('fetch failed') || msg.includes('ECONNREFUSED')) {
+      return JSON.stringify({ error: `Wallet server not reachable at ${WALLET_BASE_URL}. Start it first: npx aurawallet start` });
+    }
+    return JSON.stringify({ error: `Could not fetch server public key: ${msg}` });
+  }
+
+  // Step 2: Encrypt password with RSA-OAEP
+  let encrypted: string;
+  const pubkey = generateAgentPubkeyPem();
+  try {
+    const buffer = Buffer.from(password, 'utf8');
+    const enc = publicEncrypt(
+      { key: publicKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+      buffer,
+    );
+    encrypted = enc.toString('base64');
+  } catch (err) {
+    const msg = getErrorMessage(err);
+    return JSON.stringify({ error: `Password encryption failed: ${msg}` });
+  }
+
+  // Step 3: Create vault via POST /setup
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);
+    const res = await fetch(`${WALLET_BASE_URL}/setup`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ encrypted, pubkey }),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    const text = await res.text();
+    if (text.length > MAX_RESPONSE_SIZE) {
+      return text.slice(0, MAX_RESPONSE_SIZE) + '\n...[truncated]';
+    }
+    return text;
+  } catch (err) {
+    const msg = getErrorMessage(err);
+    return JSON.stringify({ error: `Vault creation failed: ${msg}` });
+  }
+}
+
+/**
+ * Handle request_human_action tool — creates a pending action request
+ * with a pre-computed action that auto-executes on approval.
+ */
+async function executeRequestHumanAction(
+  input: Record<string, unknown>,
+  token?: string,
+): Promise<string> {
+  const { summary, permissions, action, limits, walletAccess, ttl, pubkey } = input as {
+    summary?: string;
+    permissions?: string[];
+    action?: { endpoint?: string; method?: string; body?: Record<string, unknown> };
+    limits?: Record<string, number>;
+    walletAccess?: string[];
+    ttl?: number;
+    pubkey?: string;
+  };
+
+  // Validate inputs
+  if (!summary || typeof summary !== 'string' || summary.trim().length === 0) {
+    return JSON.stringify({ error: 'summary is required and must be a non-empty string' });
+  }
+  const MAX_SUMMARY_LENGTH = 500;
+  if (summary.length > MAX_SUMMARY_LENGTH) {
+    return JSON.stringify({ error: `summary must be ${MAX_SUMMARY_LENGTH} characters or fewer` });
+  }
+  if (!permissions || !Array.isArray(permissions) || permissions.length === 0) {
+    return JSON.stringify({ error: 'permissions must be a non-empty array' });
+  }
+  if (!action || typeof action !== 'object' || !action.endpoint || !action.method) {
+    return JSON.stringify({ error: 'action must have endpoint and method' });
+  }
+
+  // Security: block privilege escalation (defense-in-depth — server also checks)
+  const blocked = permissions.filter((p: string) => p === 'admin:*' || p === 'action:create');
+  if (blocked.length > 0) {
+    return JSON.stringify({ error: `Cannot request privileged permissions: ${blocked.join(', ')}` });
+  }
+
+  // Security: validate permission↔endpoint mapping
+  const endpointError = validatePermissionEndpoint(permissions, action.endpoint);
+  if (endpointError) {
+    return JSON.stringify({ error: endpointError });
+  }
+
+  if (!token) {
+    return JSON.stringify({ error: 'No auth token available — cannot create action request. To get a token, use wallet_api POST /auth with { agentId, profile } then poll GET /auth/<requestId>?secret=<secret> after human approval.' });
+  }
+
+  const actionPubkey = typeof pubkey === 'string' && pubkey.trim().length > 0
+    ? pubkey
+    : generateAgentPubkeyPem();
+
+  // POST to /actions with the pre-computed action in metadata
+  const url = `${WALLET_BASE_URL}/actions`;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      signal: controller.signal,
+      body: JSON.stringify({
+        summary,
+        permissions,
+        limits: limits || {},
+        walletAccess: walletAccess || undefined,
+        ttl: ttl || 60,
+        pubkey: actionPubkey,
+        metadata: {
+          action: {
+            endpoint: action.endpoint,
+            method: action.method,
+            body: action.body,
+          },
+        },
+      }),
+    });
+    clearTimeout(timeout);
+
+    const text = await res.text();
+    if (text.length > MAX_RESPONSE_SIZE) {
+      return text.slice(0, MAX_RESPONSE_SIZE) + '\n...[truncated]';
+    }
+    return text;
+  } catch (err) {
+    const msg = getErrorMessage(err);
+    return JSON.stringify({ error: `Action request failed: ${msg}` });
+  }
+}
+
+/** Execute a wallet_api tool call */
+async function executeWalletApi(
+  input: Record<string, unknown>,
+  token?: string,
+): Promise<string> {
+  const { method, endpoint, body } = input as {
+    method: string;
+    endpoint: string;
+    body?: Record<string, unknown>;
+  };
+
+  // Validate endpoint
+  if (!endpoint || typeof endpoint !== 'string' || !endpoint.startsWith('/')) {
+    return JSON.stringify({ error: 'endpoint must start with /' });
+  }
+
+  // Block internal-only endpoints (defense-in-depth)
+  const BLOCKED_ENDPOINTS = ['/auth/internal', '/apps/internal', '/strategies/internal'];
+  if (BLOCKED_ENDPOINTS.some(prefix => endpoint.startsWith(prefix))) {
+    return JSON.stringify({ error: 'This endpoint is not accessible via MCP' });
+  }
+
+  // Validate method
+  const upperMethod = (method || 'GET').toUpperCase();
+  if (!['GET', 'POST', 'PUT', 'DELETE'].includes(upperMethod)) {
+    return JSON.stringify({ error: 'method must be GET, POST, PUT, or DELETE' });
+  }
+
+  const url = `${WALLET_BASE_URL}${endpoint}`;
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);
+
+    const fetchOpts: RequestInit = {
+      method: upperMethod,
+      headers,
+      signal: controller.signal,
+    };
+
+    if ((upperMethod === 'POST' || upperMethod === 'PUT') && body) {
+      fetchOpts.body = JSON.stringify(body);
+    }
+
+    const res = await fetch(url, fetchOpts);
+    clearTimeout(timeout);
+
+    const text = await res.text();
+
+    // Truncate to prevent context bloat, except encrypted credential reads
+    // where truncation breaks client-side decryption.
+    const bypassTruncation = /^\/credentials\/[^/]+\/read(?:\?.*)?$/.test(endpoint);
+    if (!bypassTruncation && text.length > MAX_RESPONSE_SIZE) {
+      return text.slice(0, MAX_RESPONSE_SIZE) + '\n...[truncated]';
+    }
+
+    return text;
+  } catch (err) {
+    const msg = getErrorMessage(err);
+    if (msg.includes('fetch failed') || msg.includes('ECONNREFUSED')) {
+      return JSON.stringify({ error: `Wallet server not reachable at ${WALLET_BASE_URL}. Is it running? Start it with: npx aurawallet start` });
+    }
+    return JSON.stringify({ error: `API call failed: ${msg}` });
+  }
+}

package/server/middleware/auth.ts

@@ -0,0 +1,119 @@
+import { Request, Response, NextFunction } from 'express';
+import {
+  validateToken,
+  getTokenHash,
+  AgentTokenPayload,
+} from '../lib/auth';
+import { isRevoked } from '../lib/sessions';
+import { logger } from '../lib/logger';
+
+/**
+ * Auth info attached to requests
+ */
+export interface AuthInfo {
+  token: AgentTokenPayload;
+  tokenHash: string;
+  raw: string;
+}
+
+// Extend Express Request to include auth info
+declare global {
+  namespace Express {
+    interface Request {
+      auth?: AuthInfo;
+    }
+  }
+}
+
+/**
+ * Middleware that requires a valid Bearer token for all requests.
+ * Admin tokens are regular tokens with admin:* permission.
+ * Attaches auth info to req.auth on success.
+ */
+export function requireWalletAuth(req: Request, res: Response, next: NextFunction): void {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    logger.authFailed('Missing authorization header', req.path);
+    res.status(401).json({ error: 'Authorization header required' });
+    return;
+  }
+
+  const rawToken = authHeader.slice(7);
+  const token = validateToken(rawToken);
+
+  if (!token) {
+    logger.authFailed('Invalid or expired token', req.path);
+    res.status(401).json({ error: 'Invalid or expired token' });
+    return;
+  }
+
+  const tokenHash = getTokenHash(rawToken);
+
+  if (isRevoked(tokenHash)) {
+    logger.authFailed('Token revoked', req.path, { tokenHash });
+    res.status(401).json({ error: 'Token has been revoked' });
+    return;
+  }
+
+  // Attach auth info to request
+  req.auth = {
+    token,
+    tokenHash,
+    raw: rawToken,
+  };
+
+  next();
+}
+
+/**
+ * Middleware that requires admin permissions.
+ * Must be used after requireWalletAuth (needs req.auth).
+ */
+export function requireAdmin(req: Request, res: Response, next: NextFunction): void {
+  if (!req.auth) {
+    res.status(401).json({ error: 'Authorization required' });
+    return;
+  }
+
+  // Check for admin permission in token
+  const perms: string[] = req.auth.token.permissions || [];
+  const hasAdmin = perms.some(p => p === 'admin:*' || p === '*');
+  if (!hasAdmin) {
+    res.status(403).json({ error: 'Admin access required' });
+    return;
+  }
+
+  next();
+}
+
+/**
+ * Optional auth middleware - extracts token if present but doesn't require it.
+ * Useful for routes that behave differently for authenticated vs unauthenticated users.
+ */
+export function optionalWalletAuth(req: Request, res: Response, next: NextFunction): void {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    // No auth - continue without setting req.auth
+    next();
+    return;
+  }
+
+  const rawToken = authHeader.slice(7);
+  const token = validateToken(rawToken);
+
+  if (token) {
+    const tokenHash = getTokenHash(rawToken);
+
+    if (!isRevoked(tokenHash)) {
+      req.auth = {
+        token,
+        tokenHash,
+        raw: rawToken,
+      };
+    }
+  }
+
+  next();
+}