auramaxx 1.0.0-alpha.4

package/server/lib/key-fingerprint.ts

@@ -0,0 +1,28 @@
+import { createHash, createPublicKey } from 'crypto';
+
+function normalizeFingerprint(hex: string): string {
+  return hex.toLowerCase().replace(/[^a-f0-9]/g, '').match(/.{1,2}/g)?.join(':') || '';
+}
+
+export function computeSshFingerprint(publicKeyOrPrivateKey: string): string | null {
+  const material = publicKeyOrPrivateKey?.trim();
+  if (!material) return null;
+
+  try {
+    const keyObject = createPublicKey(material);
+    const der = keyObject.export({ format: 'der', type: 'spki' }) as Buffer;
+    const digest = createHash('sha256').update(der).digest('hex');
+    return normalizeFingerprint(digest);
+  } catch {
+    return null;
+  }
+}
+
+export function computeGpgFingerprint(material: string): string | null {
+  const normalized = material?.trim();
+  if (!normalized) return null;
+
+  // Deterministic pseudo-fingerprint for armored key material (v1 scope).
+  const digest = createHash('sha1').update(normalized).digest('hex');
+  return normalizeFingerprint(digest);
+}

package/server/lib/logger.ts

@@ -0,0 +1,331 @@
+/**
+ * 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 },
+    }),
+
+  /** 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;
+}