auramaxx 0.0.1

package/server/lib/logger.ts

@@ -0,0 +1,340 @@
+/**
+ * Event logger helper for consistent event emission across Express routes
+ * Convenience wrapper around events.custom() for structured logging
+ */
+
+import { events } from './events';
+
+export type EventCategory = 'auth' | 'wallet' | 'transaction' | 'token' | 'request' | 'system' | 'agent';
+
+export interface LogParams {
+  category: EventCategory;
+  action: string;
+  description: string;
+  agentId?: string;
+  walletAddress?: string;
+  txHash?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Log an event with structured data
+ * Emits to WebSocket and stores in database
+ */
+export function logEvent(params: LogParams): void {
+  const eventType = `${params.category}:${params.action}`;
+  events.custom(eventType, {
+    description: params.description,
+    agentId: params.agentId,
+    walletAddress: params.walletAddress,
+    txHash: params.txHash,
+    timestamp: Date.now(),
+    ...params.metadata,
+  });
+}
+
+/**
+ * Convenience methods for common events
+ */
+export const logger = {
+  // ── Auth Events ──────────────────────────────────────────────
+
+  /** Wallet unlocked event */
+  unlocked: (address: string) =>
+    logEvent({
+      category: 'auth',
+      action: 'unlocked',
+      description: `Wallet unlocked: ${address.slice(0, 10)}...`,
+      walletAddress: address,
+    }),
+
+  /** Wallet locked event */
+  locked: () =>
+    logEvent({
+      category: 'auth',
+      action: 'locked',
+      description: 'Wallet locked',
+    }),
+
+  /** Auth failure (invalid/expired/revoked token, missing header) */
+  authFailed: (reason: string, path: string, metadata?: Record<string, unknown>) =>
+    logEvent({
+      category: 'auth',
+      action: 'auth_failed',
+      description: `Auth failed: ${reason}`,
+      metadata: { path, reason, ...metadata },
+    }),
+
+  /** Permission denied */
+  permissionDenied: (permission: string, agentId: string, path: string) =>
+    logEvent({
+      category: 'auth',
+      action: 'permission_denied',
+      description: `Permission denied: ${permission}`,
+      agentId,
+      metadata: { permission, path },
+    }),
+
+  /** Token validated successfully */
+  tokenValidated: (agentId: string, tokenHash: string) =>
+    logEvent({
+      category: 'auth',
+      action: 'token_validated',
+      description: `Token validated for ${agentId}`,
+      agentId,
+      metadata: { tokenHash },
+    }),
+
+  // ── Token Events ─────────────────────────────────────────────
+
+  /** Agent token created */
+  tokenCreated: (agentId: string, tokenHash: string, limit: number, permissions: string[]) =>
+    logEvent({
+      category: 'token',
+      action: 'created',
+      description: `Token created for ${agentId} (limit: ${limit} ETH)`,
+      agentId,
+      metadata: { tokenHash, limit, permissions },
+    }),
+
+  /** Agent token revoked */
+  tokenRevoked: (tokenHash: string, revokedBy?: string) =>
+    logEvent({
+      category: 'token',
+      action: 'revoked',
+      description: `Token revoked: ${tokenHash.slice(0, 12)}...`,
+      metadata: { tokenHash, revokedBy },
+    }),
+
+  /** Spending limit exceeded */
+  limitExceeded: (agentId: string, limitType: string, requested: number, remaining: number) =>
+    logEvent({
+      category: 'token',
+      action: 'limit_exceeded',
+      description: `${limitType} limit exceeded: requested ${requested}, remaining ${remaining}`,
+      agentId,
+      metadata: { limitType, requested, remaining },
+    }),
+
+  // ── Wallet Events ────────────────────────────────────────────
+
+  /** Cold wallet setup event */
+  setup: (address: string) =>
+    logEvent({
+      category: 'wallet',
+      action: 'setup',
+      description: `Cold wallet created: ${address.slice(0, 10)}...`,
+      walletAddress: address,
+    }),
+
+  /** Hot/temp wallet created event */
+  walletCreated: (address: string, tier: string, agentId?: string) =>
+    logEvent({
+      category: 'wallet',
+      action: 'created',
+      description: `${tier} wallet created`,
+      walletAddress: address,
+      agentId,
+      metadata: { tier },
+    }),
+
+  /** Wallet renamed/updated */
+  walletRenamed: (address: string, agentId?: string) =>
+    logEvent({
+      category: 'wallet',
+      action: 'renamed',
+      description: `Wallet updated: ${address.slice(0, 10)}...`,
+      walletAddress: address,
+      agentId,
+    }),
+
+  /** Wallet private key exported */
+  walletExported: (address: string, agentId?: string) =>
+    logEvent({
+      category: 'wallet',
+      action: 'exported',
+      description: `Private key exported: ${address.slice(0, 10)}...`,
+      walletAddress: address,
+      agentId,
+    }),
+
+  /** Seed phrase exported */
+  seedExported: (vaultId?: string) =>
+    logEvent({
+      category: 'wallet',
+      action: 'seed_exported',
+      description: `Seed phrase exported${vaultId ? ` (vault: ${vaultId})` : ''}`,
+      metadata: { vaultId },
+    }),
+
+  // ── Transaction Events ───────────────────────────────────────
+
+  /** ETH send event */
+  send: (from: string, to: string, amount: string, txHash: string, agentId?: string) =>
+    logEvent({
+      category: 'transaction',
+      action: 'send',
+      description: `Sent ${amount} ETH`,
+      walletAddress: from,
+      txHash,
+      agentId,
+      metadata: { to, amount },
+    }),
+
+  /** Cold to hot fund transfer event */
+  fund: (to: string, amount: string, txHash: string, agentId?: string) =>
+    logEvent({
+      category: 'transaction',
+      action: 'fund',
+      description: `Funded ${amount} ETH`,
+      walletAddress: to,
+      txHash,
+      agentId,
+      metadata: { amount },
+    }),
+
+  /** Token swap event */
+  swap: (wallet: string, fromToken: string, toToken: string, amount: string, txHash: string, agentId?: string) =>
+    logEvent({
+      category: 'transaction',
+      action: 'swap',
+      description: `Swapped ${amount} ${fromToken} to ${toToken}`,
+      walletAddress: wallet,
+      txHash,
+      agentId,
+      metadata: { fromToken, toToken, amount },
+    }),
+
+  // ── Agent Events ─────────────────────────────────────────────
+
+  /** Agent requested access */
+  agentRequested: (agentId: string, requestId: string, limit: number) =>
+    logEvent({
+      category: 'agent',
+      action: 'access_requested',
+      description: `${agentId} requested access (limit: ${limit} ETH)`,
+      agentId,
+      metadata: { requestId, limit },
+    }),
+
+  /** Agent polled for token */
+  agentPolled: (requestId: string) =>
+    logEvent({
+      category: 'agent',
+      action: 'polled',
+      description: `Token poll for request ${requestId}`,
+      metadata: { requestId },
+    }),
+
+  /** Permission update requested */
+  permissionRequested: (agentId: string, requestId: string, permissions: string[]) =>
+    logEvent({
+      category: 'agent',
+      action: 'permission_requested',
+      description: `${agentId} requested permission update`,
+      agentId,
+      metadata: { requestId, permissions },
+    }),
+
+  /** Action created by agent */
+  actionCreated: (agentId: string, requestId: string, type: string, summary: string) =>
+    logEvent({
+      category: 'agent',
+      action: 'action_created',
+      description: `${agentId} created ${type}: ${summary}`,
+      agentId,
+      metadata: { requestId, type, summary },
+    }),
+
+  /** Action resolved (approved/rejected) */
+  actionResolved: (requestId: string, type: string, approved: boolean, resolvedBy: string) =>
+    logEvent({
+      category: 'agent',
+      action: 'action_resolved',
+      description: `${type} ${approved ? 'approved' : 'rejected'} by ${resolvedBy}`,
+      metadata: { requestId, type, approved, resolvedBy },
+    }),
+
+  // ── System Events ────────────────────────────────────────────
+
+  /** System nuke (full reset) */
+  nuke: () =>
+    logEvent({
+      category: 'system',
+      action: 'nuke',
+      description: 'System nuke: all data wiped',
+    }),
+
+  /** Database backup */
+  backup: (filename: string) =>
+    logEvent({
+      category: 'system',
+      action: 'backup',
+      description: `Database backup created: ${filename}`,
+      metadata: { filename },
+    }),
+
+  /** API key created */
+  apiKeyCreated: (service: string, name: string) =>
+    logEvent({
+      category: 'system',
+      action: 'apikey_created',
+      description: `API key created: ${service}/${name}`,
+      metadata: { service, name },
+    }),
+
+  /** API key deleted */
+  apiKeyDeleted: (service: string, name: string) =>
+    logEvent({
+      category: 'system',
+      action: 'apikey_deleted',
+      description: `API key deleted: ${service}/${name}`,
+      metadata: { service, name },
+    }),
+
+  /** All API keys revoked */
+  apiKeysRevokedAll: (revokedCount: number) =>
+    logEvent({
+      category: 'system',
+      action: 'apikey_revoked_all',
+      description: `All API keys revoked (${revokedCount})`,
+      metadata: { revokedCount },
+    }),
+
+  /** Strategy toggled */
+  strategyToggled: (strategyId: string, enabled: boolean) =>
+    logEvent({
+      category: 'system',
+      action: 'strategy_toggled',
+      description: `Strategy ${strategyId} ${enabled ? 'enabled' : 'disabled'}`,
+      metadata: { strategyId, enabled },
+    }),
+
+  /** Adapter configuration changed */
+  adapterChanged: (action: string, type: string) =>
+    logEvent({
+      category: 'system',
+      action: 'adapter_changed',
+      description: `Adapter ${type}: ${action}`,
+      metadata: { action, type },
+    }),
+
+  /** App operation */
+  appOperation: (operation: string, appId: string, agentId?: string) =>
+    logEvent({
+      category: 'system',
+      action: 'app_operation',
+      description: `App ${operation}: ${appId}`,
+      agentId,
+      metadata: { operation, appId },
+    }),
+
+  /** Server error */
+  error: (message: string, path?: string, metadata?: Record<string, unknown>) =>
+    logEvent({
+      category: 'system',
+      action: 'error',
+      description: `Error: ${message}`,
+      metadata: { path, ...metadata },
+    }),
+};

package/server/lib/network.ts

@@ -0,0 +1,137 @@
+/**
+ * Network / SSRF Utilities
+ * ========================
+ * Shared utilities for validating external URLs and preventing SSRF attacks.
+ * Used by the strategy executor, source fetcher, app fetch proxy,
+ * webhook adapter, and app installer.
+ */
+
+import { isIPv4, isIPv6 } from 'net';
+import dns from 'dns';
+import { getErrorMessage } from './error';
+
+/**
+ * Check whether a resolved IP address is in a private/reserved range.
+ * Handles both IPv4 and IPv6 (including IPv4-mapped IPv6 addresses).
+ */
+export function isPrivateIp(ip: string): boolean {
+  if (isIPv4(ip)) {
+    const parts = ip.split('.').map(Number);
+    const [a, b] = parts;
+    if (a === 127) return true;                          // 127.0.0.0/8 loopback
+    if (a === 10) return true;                           // 10.0.0.0/8 private
+    if (a === 172 && b >= 16 && b <= 31) return true;    // 172.16.0.0/12 private
+    if (a === 192 && b === 168) return true;              // 192.168.0.0/16 private
+    if (a === 169 && b === 254) return true;              // 169.254.0.0/16 link-local
+    if (a === 0) return true;                             // 0.0.0.0/8
+    return false;
+  }
+
+  if (isIPv6(ip)) {
+    const normalized = ip.toLowerCase();
+
+    // Loopback
+    if (normalized === '::1') return true;
+
+    // IPv4-mapped IPv6 — ::ffff:a.b.c.d
+    if (normalized.startsWith('::ffff:')) {
+      const embedded = normalized.slice(7);
+      if (isIPv4(embedded)) return isPrivateIp(embedded);
+    }
+
+    // Link-local fe80::/10 — first 10 bits = 1111 1110 10
+    // Covers fe80:: through febf::
+    const firstSegment = normalized.split(':')[0];
+    if (firstSegment.length >= 3) {
+      const prefix = firstSegment.slice(0, 3);
+      if (prefix === 'fe8' || prefix === 'fe9' || prefix === 'fea' || prefix === 'feb') return true;
+    }
+
+    // Unique local fc00::/7 — first 7 bits = 1111 110
+    // Covers fc00:: through fdff::
+    if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+
+    return false;
+  }
+
+  // Unknown format — treat as suspicious
+  return false;
+}
+
+/**
+ * Resolve a hostname via DNS and verify the resolved IP is not private.
+ * Throws if the hostname resolves to a private/reserved IP.
+ */
+export async function resolveAndValidateHost(hostname: string): Promise<void> {
+  // If the hostname is already a raw IP, check directly
+  if (isIPv4(hostname) || isIPv6(hostname)) {
+    if (isPrivateIp(hostname)) {
+      throw new Error(`Address "${hostname}" is a private/reserved IP`);
+    }
+    return;
+  }
+
+  let address: string;
+  try {
+    const result = await dns.promises.lookup(hostname);
+    address = result.address;
+  } catch (err) {
+    const msg = getErrorMessage(err);
+    throw new Error(`DNS lookup failed for "${hostname}": ${msg}`);
+  }
+
+  if (isPrivateIp(address)) {
+    throw new Error(`Host "${hostname}" resolves to private IP ${address}`);
+  }
+}
+
+/**
+ * Full validation pipeline for an external URL:
+ * 1. Parse the URL
+ * 2. Verify protocol is http: or https:
+ * 3. If allowedHosts is provided, verify hostname is in the list
+ * 4. DNS-resolve and verify the IP is not private
+ */
+// Reserved test TLDs (RFC 2606) — skip DNS resolution in test environments
+const TEST_TLDS = ['.example.com', '.example.org', '.example.net', '.test', '.localhost'];
+
+export async function validateExternalUrl(
+  url: string,
+  allowedHosts?: string[],
+): Promise<void> {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`Protocol "${parsed.protocol}" is not allowed. Only http: and https: are permitted`);
+  }
+
+  if (allowedHosts && allowedHosts.length > 0) {
+    if (!allowedHosts.includes(parsed.hostname)) {
+      throw new Error(`Host "${parsed.hostname}" is not in the allowed hosts list`);
+    }
+  }
+
+  // Skip DNS resolution for RFC 2606 reserved test domains in test environments
+  if (process.env.NODE_ENV === 'test' && TEST_TLDS.some(tld => parsed.hostname.endsWith(tld))) {
+    return;
+  }
+
+  await resolveAndValidateHost(parsed.hostname);
+}
+
+/**
+ * Sanitize a path segment (e.g., strategyId, appId) to prevent
+ * path traversal when interpolated into REST API URLs.
+ * Throws if the segment contains forbidden characters.
+ */
+export function sanitizePathSegment(segment: string): string {
+  if (segment.includes('/') || segment.includes('..') || segment.includes('\\')) {
+    throw new Error(`Invalid path segment: "${segment}" contains forbidden characters`);
+  }
+  return segment;
+}

package/server/lib/notifications.ts

@@ -0,0 +1,230 @@
+import { prisma } from './db';
+import { loadConfig } from './config';
+
+interface NotificationAction {
+  id: string;
+  label: string;
+  type: 'primary' | 'secondary' | 'danger' | 'link';
+  action: 'api' | 'navigate' | 'dismiss';
+  endpoint?: string;
+  method?: string;
+  body?: Record<string, unknown>;
+  href?: string;
+  external?: boolean;
+}
+
+interface CreateNotificationParams {
+  type: 'pending_approval' | 'info' | 'warning' | 'success' | 'error' | 'system';
+  category?: 'transaction' | 'security' | 'token' | 'wallet' | 'general';
+  title: string;
+  message: string;
+  actions?: NotificationAction[];
+  metadata?: Record<string, unknown>;
+  humanActionId?: string;
+  expiresAt?: Date;
+  source?: 'system' | 'agent' | 'user';
+  agentId?: string;
+}
+
+export async function createNotification(params: CreateNotificationParams) {
+  return prisma.notification.create({
+    data: {
+      type: params.type,
+      category: params.category,
+      title: params.title,
+      message: params.message,
+      actions: params.actions ? JSON.stringify(params.actions) : null,
+      metadata: params.metadata ? JSON.stringify(params.metadata) : null,
+      humanActionId: params.humanActionId,
+      expiresAt: params.expiresAt,
+      source: params.source || 'system',
+      agentId: params.agentId,
+    },
+  });
+}
+
+export async function createHumanActionNotification(request: {
+  id: string;
+  type: string;
+  fromTier: string;
+  toAddress: string | null;
+  amount: string | null;
+  chain: string;
+  metadata?: string | null;
+}) {
+  const config = loadConfig();
+  const explorer = config.chains[request.chain]?.explorer || 'https://basescan.org';
+
+  const typeLabels: Record<string, string> = {
+    fund: 'Fund Request',
+    send: 'Send Request',
+    agent_access: 'Agent Access Request',
+    auth: 'Agent Auth Request',
+    action: 'Action Request',
+    notify: 'Token Alert',
+  };
+
+  const title = typeLabels[request.type] || 'Pending Request';
+  const shortAddr = request.toAddress
+    ? `${request.toAddress.slice(0, 6)}...${request.toAddress.slice(-4)}`
+    : 'Unknown';
+
+  let message: string;
+  if (request.type === 'agent_access' || request.type === 'auth') {
+    // Parse metadata to get agent info
+    let agentId = 'Unknown Agent';
+    let limit = 0;
+    let requestedLimitExplicit = false;
+    let summary = '';
+    if (request.metadata) {
+      try {
+        const meta = JSON.parse(request.metadata);
+        agentId = meta.agentId || agentId;
+        if (typeof meta.limit === 'number') limit = meta.limit;
+        if (typeof meta?.limits?.fund === 'number') limit = meta.limits.fund;
+        requestedLimitExplicit = meta.requestedLimitExplicit === true;
+        if (typeof meta.summary === 'string') summary = meta.summary;
+      } catch {
+        // ignore
+      }
+    }
+    if (summary) {
+      message = summary;
+    } else if (requestedLimitExplicit) {
+      message = `${agentId} requesting ${limit} ETH access`;
+    } else {
+      message = `${agentId} requesting access`;
+    }
+  } else if (request.type === 'action') {
+    let summary = 'Action pending';
+    let callerAgentId = 'app';
+    if (request.metadata) {
+      try {
+        const meta = JSON.parse(request.metadata);
+        const vs = meta.verifiedSummary;
+        summary = vs?.oneLiner || meta.summary || summary;
+        callerAgentId = meta.agentId || callerAgentId;
+      } catch {}
+    }
+    message = `${callerAgentId}: ${summary}`;
+  } else if (request.amount) {
+    message = `${request.amount} ETH to ${shortAddr}`;
+  } else {
+    message = `Request to ${shortAddr}`;
+  }
+
+  const actions: NotificationAction[] = [
+    {
+      id: 'approve',
+      label: 'APPROVE',
+      type: 'primary',
+      action: 'api',
+      endpoint: `/actions/${request.id}/resolve`,
+      method: 'POST',
+      body: { approved: true },
+    },
+    {
+      id: 'reject',
+      label: 'REJECT',
+      type: 'danger',
+      action: 'api',
+      endpoint: `/actions/${request.id}/resolve`,
+      method: 'POST',
+      body: { approved: false },
+    },
+  ];
+
+  const metadata: Record<string, unknown> = {
+    requestType: request.type,
+    fromTier: request.fromTier,
+    toAddress: request.toAddress,
+    amount: request.amount,
+    chain: request.chain,
+    explorer,
+  };
+
+  if (request.metadata) {
+    try {
+      const parsed = JSON.parse(request.metadata);
+      Object.assign(metadata, parsed);
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  return createNotification({
+    type: 'pending_approval',
+    category: 'transaction',
+    title,
+    message,
+    actions,
+    metadata,
+    humanActionId: request.id,
+    source: 'system',
+  });
+}
+
+export async function resolveNotificationForRequest(
+  requestId: string,
+  resolution: 'approved' | 'rejected',
+  resultData?: { txHash?: string; explorer?: string }
+) {
+  // Find and dismiss the pending notification
+  const notification = await prisma.notification.findFirst({
+    where: { humanActionId: requestId },
+  });
+
+  if (notification) {
+    await prisma.notification.update({
+      where: { id: notification.id },
+      data: { dismissed: true, read: true },
+    });
+  }
+
+  // Create a success/info notification about the resolution
+  if (resolution === 'approved' && resultData?.txHash) {
+    const actions: NotificationAction[] = [];
+    if (resultData.explorer) {
+      actions.push({
+        id: 'view_tx',
+        label: 'VIEW TX',
+        type: 'link',
+        action: 'navigate',
+        href: `${resultData.explorer}/tx/${resultData.txHash}`,
+        external: true,
+      });
+    }
+    actions.push({
+      id: 'dismiss',
+      label: 'DISMISS',
+      type: 'secondary',
+      action: 'dismiss',
+    });
+
+    await createNotification({
+      type: 'success',
+      category: 'transaction',
+      title: 'Transaction Approved',
+      message: `TX: ${resultData.txHash.slice(0, 10)}...${resultData.txHash.slice(-6)}`,
+      actions,
+      metadata: { txHash: resultData.txHash, explorer: resultData.explorer },
+      source: 'system',
+    });
+  } else if (resolution === 'rejected') {
+    await createNotification({
+      type: 'info',
+      category: 'transaction',
+      title: 'Request Rejected',
+      message: 'The pending request was rejected.',
+      actions: [
+        {
+          id: 'dismiss',
+          label: 'DISMISS',
+          type: 'secondary',
+          action: 'dismiss',
+        },
+      ],
+      source: 'system',
+    });
+  }
+}