auramaxx 1.0.0-alpha.4

package/server/lib/adapters/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Core interfaces for the approval adapter system.
+ *
+ * Adapters receive action notifications and relay human decisions
+ * back to the wallet server via POST /actions/:id/resolve.
+ */
+
+import type { VerifiedSummary } from '../verified-summary';
+
+/** Notification sent to adapters when an action is created */
+export interface ActionNotification {
+  id: string;
+  type: string;
+  source: string;
+  summary: string;
+  expiresAt: number | null;
+  metadata?: Record<string, unknown>;
+  verifiedSummary?: VerifiedSummary;
+}
+
+/** Resolution sent to adapters when an action is resolved (by any channel) */
+export interface ActionResolution {
+  id: string;
+  type: string;
+  approved: boolean;
+  resolvedBy: string;
+}
+
+/** Incoming chat message from an adapter */
+export interface ChatMessage {
+  /** Raw text from the user */
+  text: string;
+  /** Adapter-specific sender ID (Telegram chat ID, etc.) */
+  senderId: string;
+  /** Optional: explicit app target (e.g., "/app-name" prefix) */
+  targetApp?: string;
+}
+
+/** Reply from the AI engine to an adapter chat message */
+export interface ChatReply {
+  text: string;
+  /** Optional metadata for rich formatting */
+  metadata?: Record<string, unknown>;
+}
+
+/** Options passed when resolving an action */
+export interface ResolveOptions {
+  walletAccess?: string[];
+  limits?: { fund?: number; send?: number; swap?: number };
+}
+
+/** Result of a resolve call */
+export interface ResolveResult {
+  success: boolean;
+  error?: string;
+  token?: string;
+  agentId?: string;
+}
+
+/** Context provided to adapters on start */
+export interface AdapterContext {
+  /** Resolve an action by ID */
+  resolve(actionId: string, approved: boolean, opts?: ResolveOptions): Promise<ResolveResult>;
+  /** Base URL of the wallet server */
+  serverUrl: string;
+  /** Route a chat message to a app's AI */
+  sendMessage(appId: string, text: string, onProgress?: (status: string) => void, adapter?: string): Promise<{ reply: string | null; error?: string }>;
+  /** Resolve which app should handle a message */
+  resolveApp(targetApp?: string): Promise<string | null>;
+}
+
+/** Approval adapter interface — implement this for new channels */
+export interface ApprovalAdapter {
+  /** Unique name for this adapter instance */
+  name: string;
+  /** Start the adapter (called once with context) */
+  start(ctx: AdapterContext): Promise<void>;
+  /** Called when an action is created and needs human review */
+  notify(action: ActionNotification): Promise<void>;
+  /** Called when an action is resolved (so adapter can clean up UI) */
+  resolved(resolution: ActionResolution): Promise<void>;
+  /** Stop the adapter and clean up resources */
+  stop(): Promise<void>;
+  /** Optional: handle incoming chat messages (adapters that support chat) */
+  onMessage?(message: ChatMessage): Promise<ChatReply | null>;
+}
+
+/** Factory function type for creating adapters */
+export type AdapterFactory = (config: Record<string, unknown>) => ApprovalAdapter;

package/server/lib/adapters/webhook.ts

@@ -0,0 +1,95 @@
+/**
+ * Webhook adapter — notification-only.
+ *
+ * POSTs action notifications and resolutions to a configured URL.
+ * Useful for Slack incoming webhooks, Discord webhooks, ntfy, or
+ * any HTTP endpoint that wants to receive approval events.
+ *
+ * This adapter does NOT handle responses — it only pushes events out.
+ * To approve/reject from a webhook target, build a bidirectional adapter
+ * (like the Telegram adapter) or have the target POST to /actions/:id/resolve.
+ */
+
+import { createHmac } from 'crypto';
+import { validateExternalUrl } from '../network';
+import type {
+  ApprovalAdapter,
+  AdapterContext,
+  ActionNotification,
+  ActionResolution,
+} from './types';
+import { getErrorMessage } from '../error';
+
+export interface WebhookAdapterConfig {
+  /** URL to POST notifications to */
+  url: string;
+  /** Optional HMAC-SHA256 secret for signing payloads */
+  secret?: string;
+  /** Optional custom headers to include */
+  headers?: Record<string, string>;
+}
+
+export class WebhookAdapter implements ApprovalAdapter {
+  readonly name: string;
+  private config: WebhookAdapterConfig;
+
+  constructor(config: WebhookAdapterConfig) {
+    this.name = `webhook:${new URL(config.url).hostname}`;
+    this.config = config;
+    // Validate URL synchronously at construction — DNS check happens at send time
+    const parsed = new URL(config.url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error(`Webhook URL must use http: or https: (got ${parsed.protocol})`);
+    }
+  }
+
+  async start(_ctx: AdapterContext): Promise<void> {
+    // Nothing to initialize
+  }
+
+  async notify(action: ActionNotification): Promise<void> {
+    await this.post('action:created', action);
+  }
+
+  async resolved(resolution: ActionResolution): Promise<void> {
+    await this.post('action:resolved', resolution);
+  }
+
+  async stop(): Promise<void> {
+    // Nothing to clean up
+  }
+
+  private async post(eventType: string, data: unknown): Promise<void> {
+    const payload = JSON.stringify({ type: eventType, data, timestamp: Date.now() });
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.config.headers,
+    };
+
+    // Add HMAC signature if secret is configured
+    if (this.config.secret) {
+      const signature = createHmac('sha256', this.config.secret)
+        .update(payload)
+        .digest('hex');
+      headers['X-Signature-256'] = `sha256=${signature}`;
+    }
+
+    try {
+      await validateExternalUrl(this.config.url);
+      const response = await fetch(this.config.url, {
+        method: 'POST',
+        headers,
+        body: payload,
+        redirect: 'error',
+      });
+
+      if (!response.ok) {
+        console.error(`[adapters] ${this.name} POST failed: ${response.status}`);
+      }
+    } catch (err) {
+      const msg = getErrorMessage(err);
+      console.error(`[adapters] ${this.name} POST error:`, msg);
+    }
+  }
+}

package/server/lib/address.ts

@@ -0,0 +1,49 @@
+/**
+ * Address normalization utilities for multi-chain support.
+ * EVM addresses are case-insensitive (lowercase), Solana addresses are case-sensitive (base58).
+ */
+
+// Native token addresses by chain type
+export const NATIVE_ADDRESSES = {
+  ETH: '0x0000000000000000000000000000000000000000',
+  SOL: 'So11111111111111111111111111111111111111112',
+} as const;
+
+/**
+ * Check if a chain identifier refers to a Solana chain.
+ */
+export function isSolanaChain(chain: string): boolean {
+  return chain === 'solana' || chain === 'solana-devnet';
+}
+
+/**
+ * Normalize an address for the given chain.
+ * EVM: lowercase (case-insensitive)
+ * Solana: no-op (base58 is case-sensitive)
+ */
+export function normalizeAddress(addr: string, chain?: string): string {
+  if (chain && isSolanaChain(chain)) {
+    return addr; // base58 is case-sensitive
+  }
+  return addr.toLowerCase();
+}
+
+/**
+ * Get the native token address for a chain.
+ */
+export function getNativeAddress(chain: string): string {
+  if (isSolanaChain(chain)) {
+    return NATIVE_ADDRESSES.SOL;
+  }
+  return NATIVE_ADDRESSES.ETH;
+}
+
+/**
+ * Get the native currency symbol for a chain.
+ */
+export function getNativeCurrency(chain: string): string {
+  if (isSolanaChain(chain)) {
+    return 'SOL';
+  }
+  return 'ETH';
+}