auramaxx 0.0.1

package/server/mcp/tools.ts

@@ -0,0 +1,276 @@
+/**
+ * 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 { 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: 'api',
+    description:
+      'Call the AuraMaxx 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', 'PATCH', 'DELETE'],
+          description: 'HTTP method',
+        },
+        endpoint: {
+          type: 'string',
+          description: 'API path, e.g. /wallets',
+        },
+        body: {
+          type: 'object',
+          description: 'POST/PUT/PATCH request body (optional)',
+        },
+      },
+      required: ['method', 'endpoint'],
+    },
+  },
+  {
+    name: 'status',
+    description: 'Get Aura setup/unlock health state (CLI equivalent: `auramaxx status`).',
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'list_secrets',
+    description: 'List credentials with optional query filters (CLI equivalent: `auramaxx vault list --q ...`).',
+    parameters: {
+      type: 'object',
+      properties: {
+        q: { type: 'string', description: 'Optional search query' },
+        tag: { type: 'string', description: 'Optional tag filter' },
+        vault: { type: 'string', description: 'Optional vault id filter' },
+        lifecycle: { type: 'string', enum: ['active', 'archive', 'recently_deleted'], description: 'Optional lifecycle filter' },
+      },
+    },
+  },
+];
+
+/**
+ * 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;
+
+
+/** 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 === 'status') {
+    return executeTypedWalletApi('status', 'GET', '/setup', undefined, token);
+  }
+
+  if (toolName === 'list_secrets') {
+    const q = typeof input.q === 'string' ? input.q.trim() : '';
+    const tag = typeof input.tag === 'string' ? input.tag.trim() : '';
+    const vault = typeof input.vault === 'string' ? input.vault.trim() : '';
+    const lifecycle = typeof input.lifecycle === 'string' ? input.lifecycle.trim() : '';
+    const params = new URLSearchParams();
+    if (q) params.set('q', q);
+    if (tag) params.set('tag', tag);
+    if (vault) params.set('vault', vault);
+    if (lifecycle) params.set('location', lifecycle);
+    const endpoint = params.toString() ? `/credentials?${params.toString()}` : '/credentials';
+    return executeTypedWalletApi('list_secrets', 'GET', endpoint, undefined, token);
+  }
+
+  if (toolName !== 'api') {
+    return JSON.stringify({ error: `Unknown tool: ${toolName}` });
+  }
+
+  return executeWalletApi(input, token);
+}
+
+async function executeTypedWalletApi(
+  tool: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  endpoint: string,
+  body: Record<string, unknown> | undefined,
+  token?: string,
+): Promise<string> {
+  const raw = await executeWalletApi({ method, endpoint, ...(body ? { body } : {}) }, token);
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    const maybeObj = (parsed && typeof parsed === 'object') ? parsed as Record<string, unknown> : undefined;
+    if (maybeObj?.error) {
+      return JSON.stringify({ success: false, tool, error: maybeObj.error });
+    }
+    return JSON.stringify({ success: true, tool, data: parsed });
+  } catch {
+    if (raw.includes('"error"')) {
+      return JSON.stringify({ success: false, tool, error: raw });
+    }
+    return JSON.stringify({ success: true, tool, data: raw });
+  }
+}
+
+/** 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', 'PATCH', 'DELETE'].includes(upperMethod)) {
+    return JSON.stringify({ error: 'method must be GET, POST, PUT, PATCH, 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' || upperMethod === 'PATCH') && 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 auramaxx` });
+    }
+    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();
+}

package/server/middleware/requestLogger.ts

@@ -0,0 +1,84 @@
+/**
+ * Lightweight request/response logging middleware using Pino
+ *
+ * Console logging via Pino (structured, with request IDs and timing).
+ * Only stores events in DB for errors and security-relevant failures (4xx/5xx).
+ * Business events (send, fund, swap, token create, etc.) are logged separately
+ * by each route via the logger module, which handles DB + WebSocket storage.
+ */
+
+import { randomBytes } from 'crypto';
+import { Request, Response, NextFunction } from 'express';
+import { log } from '../lib/pino';
+import { events } from '../lib/events';
+
+// Paths to skip logging entirely (high-frequency/low-value)
+const SKIP_PATHS = new Set(['/health']);
+
+/**
+ * Express middleware that logs request/response details via Pino
+ * Only persists error/security events to DB to avoid bloat
+ */
+export function requestLogger(req: Request, res: Response, next: NextFunction): void {
+  if (SKIP_PATHS.has(req.path)) {
+    next();
+    return;
+  }
+
+  const requestId = randomBytes(4).toString('hex');
+  const startTime = process.hrtime.bigint();
+
+  const child = log.child({ requestId });
+
+  child.debug({
+    method: req.method,
+    url: req.originalUrl || req.path,
+  }, 'request start');
+
+  res.on('finish', () => {
+    const durationNs = process.hrtime.bigint() - startTime;
+    const durationMs = Number(durationNs) / 1_000_000;
+    const statusCode = res.statusCode;
+
+    const logData: Record<string, unknown> = {
+      method: req.method,
+      url: req.originalUrl || req.path,
+      statusCode,
+      durationMs: Math.round(durationMs * 100) / 100,
+    };
+
+    // Add agent identification for authenticated requests
+    if (req.auth) {
+      logData.agentId = req.auth.token.agentId;
+    }
+
+    // Log level based on status code
+    if (statusCode >= 500) {
+      child.error(logData, 'request error');
+    } else if (statusCode >= 400) {
+      child.warn(logData, 'request complete');
+    } else {
+      child.debug(logData, 'request complete');
+    }
+
+    // Only persist security-relevant failures to DB (auth failures, forbidden, rate limits, server errors)
+    if (statusCode === 401 || statusCode === 403 || statusCode === 429 || statusCode >= 500) {
+      const eventType =
+        statusCode === 401 ? 'request:auth_failed' :
+        statusCode === 403 ? 'request:forbidden' :
+        statusCode === 429 ? 'request:rate_limited' :
+        'request:server_error';
+
+      events.custom(eventType, {
+        requestId,
+        method: req.method,
+        path: req.originalUrl || req.path,
+        statusCode,
+        durationMs: Math.round(durationMs * 100) / 100,
+        agentId: req.auth?.token?.agentId,
+      });
+    }
+  });
+
+  next();
+}