outcome-cli 1.0.0

package/src/modules/omnibridge/auth/auth-tunnel.ts

@@ -0,0 +1,843 @@
+/**
+ * Auth Tunnel - MFA Relay for OmniBridge
+ *
+ * Secure relay for human-in-the-loop authentication.
+ * Handles MFA challenge detection, user notification, and code injection.
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4, 5.6
+ */
+
+import { randomBytes } from 'crypto';
+import type {
+  MFAChallenge,
+  AuthResult,
+  AuthError,
+  ShadowSession,
+  IntentDocument,
+  IntentElement,
+} from '../core/types.js';
+import type { SessionVault, RawSessionData } from './session-vault.js';
+import type { ShadowSessionOrchestrator } from '../execution/shadow-session.js';
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** MFA timeout in milliseconds (5 minutes as per Requirements 5.6) */
+export const MFA_TIMEOUT_MS = 300000; // 5 minutes = 300 seconds
+
+/** MFA challenge polling interval */
+export const MFA_POLL_INTERVAL_MS = 1000;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * MFA detection patterns for different challenge types.
+ */
+export interface MFADetectionPattern {
+  /** Type of MFA challenge */
+  type: MFAChallenge['type'];
+  /** Keywords to look for in page content */
+  keywords: string[];
+  /** Input field patterns (type, name, placeholder) */
+  inputPatterns: RegExp[];
+  /** ARIA roles that indicate MFA */
+  ariaRoles: string[];
+}
+
+/**
+ * User notification configuration.
+ */
+export interface NotificationConfig {
+  /** Webhook URL for notifications */
+  webhookUrl?: string;
+  /** Dashboard notification callback */
+  dashboardCallback?: (challenge: MFAChallenge) => Promise<void>;
+  /** Email notification address */
+  notificationEmail?: string;
+}
+
+/**
+ * MFA code submission result.
+ */
+export interface MFASubmissionResult {
+  success: boolean;
+  sessionState?: RawSessionData;
+  error?: AuthError;
+}
+
+/**
+ * Pending MFA challenge with additional metadata.
+ */
+export interface PendingMFAChallenge extends MFAChallenge {
+  /** Callback to resolve the challenge */
+  resolve?: (code: string) => void;
+  /** Callback to reject the challenge */
+  reject?: (error: AuthError) => void;
+  /** Whether the challenge has been notified to user */
+  notified: boolean;
+  /** Number of code submission attempts */
+  attempts: number;
+  /** Maximum allowed attempts */
+  maxAttempts: number;
+}
+
+/**
+ * Auth Tunnel configuration.
+ */
+export interface AuthTunnelConfig {
+  /** Session Vault for storing authenticated states */
+  vault?: SessionVault;
+  /** Shadow Session Orchestrator for browser sessions */
+  orchestrator?: ShadowSessionOrchestrator;
+  /** Notification configuration */
+  notificationConfig?: NotificationConfig;
+  /** MFA timeout in milliseconds (default: 300000 = 5 minutes) */
+  mfaTimeoutMs?: number;
+  /** Maximum MFA code submission attempts (default: 3) */
+  maxMfaAttempts?: number;
+}
+
+// =============================================================================
+// MFA Detection Patterns
+// =============================================================================
+
+/**
+ * Detection patterns for different MFA challenge types.
+ * Used by the Semantic Engine to identify MFA input fields.
+ *
+ * Requirements: 5.1, 5.3
+ */
+export const MFA_DETECTION_PATTERNS: MFADetectionPattern[] = [
+  {
+    type: 'sms',
+    keywords: [
+      'sms', 'text message', 'verification code', 'security code',
+      'phone code', 'mobile code', 'sent to your phone', 'sent a code',
+      '6-digit', '6 digit', 'enter code', 'enter the code',
+    ],
+    inputPatterns: [
+      /^(sms|phone|mobile|verification|security|otp|code|token)[-_]?(code|input|field)?$/i,
+      /^(one[-_]?time[-_]?password|otp)$/i,
+      /^mfa[-_]?code$/i,
+    ],
+    ariaRoles: ['textbox'],
+  },
+  {
+    type: 'authenticator',
+    keywords: [
+      'authenticator', 'google authenticator', 'microsoft authenticator',
+      'authy', 'totp', 'time-based', '2fa', 'two-factor',
+      'authentication app', 'authenticator app', '6-digit code',
+    ],
+    inputPatterns: [
+      /^(totp|authenticator|2fa|two[-_]?factor)[-_]?(code|input|field)?$/i,
+      /^(auth[-_]?code|mfa[-_]?token)$/i,
+    ],
+    ariaRoles: ['textbox'],
+  },
+  {
+    type: 'push',
+    keywords: [
+      'push notification', 'approve', 'confirm on your device',
+      'check your phone', 'tap to approve', 'waiting for approval',
+      'sent a notification', 'open your app',
+    ],
+    inputPatterns: [], // Push doesn't typically have input fields
+    ariaRoles: ['alert', 'status'],
+  },
+  {
+    type: 'email',
+    keywords: [
+      'email code', 'sent to your email', 'check your email',
+      'email verification', 'verification email', 'magic link',
+      'email link', 'sent a link', 'emailed you',
+    ],
+    inputPatterns: [
+      /^(email[-_]?code|email[-_]?verification|email[-_]?otp)$/i,
+    ],
+    ariaRoles: ['textbox'],
+  },
+];
+
+// =============================================================================
+// Auth Tunnel Implementation
+// =============================================================================
+
+/**
+ * Auth Tunnel - MFA Relay
+ *
+ * Handles the human-in-the-loop authentication flow:
+ * 1. Detects MFA challenges in Shadow Sessions
+ * 2. Notifies users via dashboard/webhook
+ * 3. Injects MFA codes into sessions
+ * 4. Serializes successful auth state to vault
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4, 5.6
+ */
+export class AuthTunnel {
+  private readonly vault?: SessionVault;
+  private readonly orchestrator?: ShadowSessionOrchestrator;
+  private readonly notificationConfig: NotificationConfig;
+  private readonly mfaTimeoutMs: number;
+  private readonly maxMfaAttempts: number;
+
+  /** Pending MFA challenges by ID */
+  private pendingChallenges: Map<string, PendingMFAChallenge> = new Map();
+
+  /** Timeout timers for challenges */
+  private timeoutTimers: Map<string, NodeJS.Timeout> = new Map();
+
+  constructor(config: AuthTunnelConfig = {}) {
+    this.vault = config.vault;
+    this.orchestrator = config.orchestrator;
+    this.notificationConfig = config.notificationConfig ?? {};
+    this.mfaTimeoutMs = config.mfaTimeoutMs ?? MFA_TIMEOUT_MS;
+    this.maxMfaAttempts = config.maxMfaAttempts ?? 3;
+  }
+
+  /**
+   * Get the orchestrator instance (for future browser automation).
+   */
+  getOrchestrator(): ShadowSessionOrchestrator | undefined {
+    return this.orchestrator;
+  }
+
+  // ===========================================================================
+  // MFA Challenge Detection
+  // ===========================================================================
+
+  /**
+   * Generate a unique challenge ID.
+   */
+  private generateChallengeId(): string {
+    return `mfa_${randomBytes(16).toString('hex')}`;
+  }
+
+  /**
+   * Detect MFA challenge type from page content.
+   * Uses keyword matching and input field analysis.
+   *
+   * Requirements: 5.1, 5.3
+   */
+  detectMFAType(
+    pageContent: string,
+    intentDocument?: IntentDocument
+  ): MFAChallenge['type'] | null {
+    const contentLower = pageContent.toLowerCase();
+
+    // Score each MFA type based on keyword matches
+    const scores: Record<MFAChallenge['type'], number> = {
+      sms: 0,
+      authenticator: 0,
+      push: 0,
+      email: 0,
+    };
+
+    for (const pattern of MFA_DETECTION_PATTERNS) {
+      // Check keywords
+      for (const keyword of pattern.keywords) {
+        if (contentLower.includes(keyword.toLowerCase())) {
+          scores[pattern.type] += 1;
+        }
+      }
+
+      // Check input fields in intent document
+      if (intentDocument) {
+        for (const form of intentDocument.forms) {
+          for (const field of form.fields) {
+            for (const inputPattern of pattern.inputPatterns) {
+              if (
+                inputPattern.test(field.name) ||
+                inputPattern.test(field.intentId) ||
+                (field.placeholder && inputPattern.test(field.placeholder))
+              ) {
+                scores[pattern.type] += 2; // Input field match is stronger signal
+              }
+            }
+          }
+        }
+
+        // Check elements for ARIA roles
+        for (const element of intentDocument.elements) {
+          if (element.ariaRole && pattern.ariaRoles.includes(element.ariaRole)) {
+            // Check if element label contains MFA keywords
+            const labelLower = element.label.toLowerCase();
+            for (const keyword of pattern.keywords) {
+              if (labelLower.includes(keyword.toLowerCase())) {
+                scores[pattern.type] += 1;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Find the type with highest score
+    let maxScore = 0;
+    let detectedType: MFAChallenge['type'] | null = null;
+
+    for (const [type, score] of Object.entries(scores)) {
+      if (score > maxScore) {
+        maxScore = score;
+        detectedType = type as MFAChallenge['type'];
+      }
+    }
+
+    // Require minimum score to confirm detection
+    return maxScore >= 2 ? detectedType : null;
+  }
+
+  /**
+   * Find MFA input field in the intent document.
+   * Uses Semantic Engine to identify the correct input field.
+   *
+   * Requirements: 5.1, 5.3
+   */
+  findMFAInputField(
+    intentDocument: IntentDocument,
+    mfaType: MFAChallenge['type']
+  ): IntentElement | null {
+    const pattern = MFA_DETECTION_PATTERNS.find((p) => p.type === mfaType);
+    if (!pattern) return null;
+
+    // First, check form fields
+    for (const form of intentDocument.forms) {
+      for (const field of form.fields) {
+        // Check input patterns
+        for (const inputPattern of pattern.inputPatterns) {
+          if (
+            inputPattern.test(field.name) ||
+            inputPattern.test(field.intentId) ||
+            (field.placeholder && inputPattern.test(field.placeholder))
+          ) {
+            // Find corresponding element
+            const element = intentDocument.elements.find(
+              (el) => el.intentId === field.intentId
+            );
+            if (element) return element;
+          }
+        }
+
+        // Check for generic code input fields
+        if (
+          field.type === 'text' ||
+          field.type === 'number' ||
+          field.type === 'tel'
+        ) {
+          const fieldLower = (field.label + field.name + (field.placeholder || '')).toLowerCase();
+          for (const keyword of pattern.keywords) {
+            if (fieldLower.includes(keyword.toLowerCase())) {
+              const element = intentDocument.elements.find(
+                (el) => el.intentId === field.intentId
+              );
+              if (element) return element;
+            }
+          }
+        }
+      }
+    }
+
+    // Fallback: check elements directly
+    for (const element of intentDocument.elements) {
+      if (element.role === 'input') {
+        const labelLower = element.label.toLowerCase();
+        for (const keyword of pattern.keywords) {
+          if (labelLower.includes(keyword.toLowerCase())) {
+            return element;
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Generate user-friendly prompt for MFA challenge.
+   */
+  private generatePrompt(mfaType: MFAChallenge['type']): string {
+    switch (mfaType) {
+      case 'sms':
+        return 'Enter the verification code sent to your phone via SMS';
+      case 'authenticator':
+        return 'Enter the 6-digit code from your authenticator app';
+      case 'push':
+        return 'Approve the login request on your mobile device';
+      case 'email':
+        return 'Enter the verification code sent to your email';
+      default:
+        return 'Complete the verification to continue';
+    }
+  }
+
+  /**
+   * Detect MFA challenge in a Shadow Session.
+   * Returns the challenge if detected, null otherwise.
+   *
+   * Requirements: 5.1, 5.3
+   */
+  async detectMFA(
+    session: ShadowSession,
+    pageContent: string,
+    intentDocument?: IntentDocument
+  ): Promise<MFAChallenge | null> {
+    // Detect MFA type
+    const mfaType = this.detectMFAType(pageContent, intentDocument);
+    if (!mfaType) {
+      return null;
+    }
+
+    // Create MFA challenge
+    const challenge: MFAChallenge = {
+      id: this.generateChallengeId(),
+      sessionId: session.id,
+      type: mfaType,
+      prompt: this.generatePrompt(mfaType),
+      expiresAt: Date.now() + this.mfaTimeoutMs,
+    };
+
+    return challenge;
+  }
+
+  // ===========================================================================
+  // User Notification
+  // ===========================================================================
+
+  /**
+   * Send notification to user about MFA challenge.
+   * Supports dashboard callback and webhook notifications.
+   *
+   * Requirements: 5.1
+   */
+  async requestCode(challenge: MFAChallenge): Promise<void> {
+    // Store as pending challenge
+    const pendingChallenge: PendingMFAChallenge = {
+      ...challenge,
+      notified: false,
+      attempts: 0,
+      maxAttempts: this.maxMfaAttempts,
+    };
+    this.pendingChallenges.set(challenge.id, pendingChallenge);
+
+    // Set up timeout timer
+    this.setupTimeoutTimer(challenge.id);
+
+    // Send dashboard notification
+    if (this.notificationConfig.dashboardCallback) {
+      try {
+        await this.notificationConfig.dashboardCallback(challenge);
+        pendingChallenge.notified = true;
+      } catch (error) {
+        console.error('Failed to send dashboard notification:', error);
+      }
+    }
+
+    // Send webhook notification
+    if (this.notificationConfig.webhookUrl) {
+      try {
+        await this.sendWebhookNotification(challenge);
+        pendingChallenge.notified = true;
+      } catch (error) {
+        console.error('Failed to send webhook notification:', error);
+      }
+    }
+
+    // If no notification method configured, mark as notified anyway
+    // (for testing or manual code entry scenarios)
+    if (!this.notificationConfig.dashboardCallback && !this.notificationConfig.webhookUrl) {
+      pendingChallenge.notified = true;
+    }
+  }
+
+  /**
+   * Send webhook notification for MFA challenge.
+   */
+  private async sendWebhookNotification(challenge: MFAChallenge): Promise<void> {
+    if (!this.notificationConfig.webhookUrl) return;
+
+    const payload = {
+      type: 'mfa_challenge',
+      challenge: {
+        id: challenge.id,
+        sessionId: challenge.sessionId,
+        type: challenge.type,
+        prompt: challenge.prompt,
+        expiresAt: challenge.expiresAt,
+      },
+      timestamp: Date.now(),
+    };
+
+    // In a real implementation, this would use fetch
+    // For now, we'll simulate the webhook call
+    console.log('Webhook notification:', this.notificationConfig.webhookUrl, payload);
+  }
+
+  /**
+   * Set up timeout timer for MFA challenge.
+   *
+   * Requirements: 5.6
+   */
+  private setupTimeoutTimer(challengeId: string): void {
+    // Clear existing timer if any
+    this.clearTimeoutTimer(challengeId);
+
+    const challenge = this.pendingChallenges.get(challengeId);
+    if (!challenge) return;
+
+    const timeoutMs = challenge.expiresAt - Date.now();
+    if (timeoutMs <= 0) {
+      this.handleTimeout(challengeId);
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      this.handleTimeout(challengeId);
+    }, timeoutMs);
+
+    this.timeoutTimers.set(challengeId, timer);
+  }
+
+  /**
+   * Clear timeout timer for a challenge.
+   */
+  private clearTimeoutTimer(challengeId: string): void {
+    const timer = this.timeoutTimers.get(challengeId);
+    if (timer) {
+      clearTimeout(timer);
+      this.timeoutTimers.delete(challengeId);
+    }
+  }
+
+  /**
+   * Handle MFA timeout.
+   *
+   * Requirements: 5.6
+   */
+  private handleTimeout(challengeId: string): void {
+    const challenge = this.pendingChallenges.get(challengeId);
+    if (!challenge) return;
+
+    // Reject the challenge with timeout error
+    if (challenge.reject) {
+      challenge.reject({
+        code: 'timeout',
+        message: 'MFA challenge timed out after 5 minutes',
+      });
+    }
+
+    // Clean up
+    this.pendingChallenges.delete(challengeId);
+    this.clearTimeoutTimer(challengeId);
+  }
+
+  // ===========================================================================
+  // Code Injection
+  // ===========================================================================
+
+  /**
+   * Inject MFA code into Shadow Session.
+   * Serializes successful auth state to vault.
+   *
+   * Requirements: 5.2, 5.4
+   */
+  async injectCode(
+    challenge: MFAChallenge,
+    code: string
+  ): Promise<AuthResult> {
+    const pendingChallenge = this.pendingChallenges.get(challenge.id);
+
+    // Check if challenge exists - if not, check if it was timed out
+    if (!pendingChallenge) {
+      // Check if the original challenge has expired
+      if (Date.now() > challenge.expiresAt) {
+        return {
+          success: false,
+          error: {
+            code: 'timeout',
+            message: 'MFA challenge has expired',
+          },
+        };
+      }
+      return {
+        success: false,
+        error: {
+          code: 'mfa_failed',
+          message: 'MFA challenge not found or already completed',
+        },
+      };
+    }
+
+    // Check if challenge has expired
+    if (Date.now() > pendingChallenge.expiresAt) {
+      this.pendingChallenges.delete(challenge.id);
+      this.clearTimeoutTimer(challenge.id);
+      return {
+        success: false,
+        error: {
+          code: 'timeout',
+          message: 'MFA challenge has expired',
+        },
+      };
+    }
+
+    // Check attempt count
+    pendingChallenge.attempts++;
+    if (pendingChallenge.attempts > pendingChallenge.maxAttempts) {
+      this.pendingChallenges.delete(challenge.id);
+      this.clearTimeoutTimer(challenge.id);
+      return {
+        success: false,
+        error: {
+          code: 'mfa_failed',
+          message: 'Maximum MFA attempts exceeded',
+        },
+      };
+    }
+
+    // Validate code format
+    if (!this.validateCodeFormat(code, challenge.type)) {
+      return {
+        success: false,
+        error: {
+          code: 'mfa_failed',
+          message: 'Invalid code format',
+        },
+      };
+    }
+
+    // In a real implementation, this would:
+    // 1. Get the Shadow Session from orchestrator
+    // 2. Find the MFA input field using Semantic Engine
+    // 3. Type the code into the field
+    // 4. Submit the form
+    // 5. Check if authentication succeeded
+    // 6. Serialize session state to vault
+
+    // For now, we simulate successful code injection
+    const sessionState: RawSessionData = {
+      cookies: JSON.stringify([
+        { name: 'auth_token', value: `authenticated_${challenge.sessionId}`, domain: 'example.com' },
+      ]),
+      localStorage: JSON.stringify({ authenticated: true }),
+      sessionStorage: JSON.stringify({ mfa_completed: true }),
+    };
+
+    // Store in vault if available
+    if (this.vault) {
+      // Extract domain from session (would come from orchestrator in real impl)
+      const domain = 'example.com'; // Placeholder
+      await this.vault.store(domain, sessionState);
+    }
+
+    // Clean up challenge
+    this.pendingChallenges.delete(challenge.id);
+    this.clearTimeoutTimer(challenge.id);
+
+    // Resolve the challenge if callback exists
+    if (pendingChallenge.resolve) {
+      pendingChallenge.resolve(code);
+    }
+
+    return {
+      success: true,
+      sessionState: {
+        cookies: this.vault?.encrypt(sessionState.cookies) ?? { data: '', iv: '', algorithm: 'AES-256-GCM' },
+        localStorage: this.vault?.encrypt(sessionState.localStorage) ?? { data: '', iv: '', algorithm: 'AES-256-GCM' },
+        sessionStorage: this.vault?.encrypt(sessionState.sessionStorage) ?? { data: '', iv: '', algorithm: 'AES-256-GCM' },
+        expiresAt: Date.now() + 86400000, // 24 hours
+      },
+    };
+  }
+
+  /**
+   * Validate MFA code format based on challenge type.
+   */
+  private validateCodeFormat(code: string, type: MFAChallenge['type']): boolean {
+    if (!code || code.trim().length === 0) {
+      return false;
+    }
+
+    switch (type) {
+      case 'sms':
+      case 'authenticator':
+        // Typically 6-digit codes
+        return /^\d{4,8}$/.test(code.trim());
+      case 'email':
+        // Could be numeric code or alphanumeric
+        return /^[A-Za-z0-9]{4,10}$/.test(code.trim());
+      case 'push':
+        // Push doesn't require code input
+        return true;
+      default:
+        return code.trim().length > 0;
+    }
+  }
+
+  // ===========================================================================
+  // Timeout Handling
+  // ===========================================================================
+
+  /**
+   * Wait for MFA code with timeout.
+   * Returns the auth result or timeout error.
+   *
+   * Requirements: 5.6
+   */
+  async waitForCode(challenge: MFAChallenge): Promise<AuthResult> {
+    return new Promise((resolve) => {
+      const pendingChallenge = this.pendingChallenges.get(challenge.id);
+      if (!pendingChallenge) {
+        resolve({
+          success: false,
+          error: {
+            code: 'mfa_failed',
+            message: 'MFA challenge not found',
+          },
+        });
+        return;
+      }
+
+      // Set up resolve/reject callbacks
+      pendingChallenge.resolve = () => {
+        resolve({
+          success: true,
+        });
+      };
+
+      pendingChallenge.reject = (error: AuthError) => {
+        resolve({
+          success: false,
+          error,
+        });
+      };
+
+      // Check if already expired
+      if (Date.now() > pendingChallenge.expiresAt) {
+        this.handleTimeout(challenge.id);
+      }
+    });
+  }
+
+  /**
+   * Check if a challenge has timed out.
+   *
+   * Requirements: 5.6
+   */
+  isTimedOut(challengeId: string): boolean {
+    const challenge = this.pendingChallenges.get(challengeId);
+    if (!challenge) return true;
+    return Date.now() > challenge.expiresAt;
+  }
+
+  /**
+   * Get remaining time for a challenge in milliseconds.
+   */
+  getRemainingTime(challengeId: string): number {
+    const challenge = this.pendingChallenges.get(challengeId);
+    if (!challenge) return 0;
+    return Math.max(0, challenge.expiresAt - Date.now());
+  }
+
+  // ===========================================================================
+  // Challenge Management
+  // ===========================================================================
+
+  /**
+   * Get a pending challenge by ID.
+   */
+  getChallenge(challengeId: string): MFAChallenge | null {
+    const pending = this.pendingChallenges.get(challengeId);
+    if (!pending) return null;
+
+    // Return public challenge (without internal callbacks)
+    return {
+      id: pending.id,
+      sessionId: pending.sessionId,
+      type: pending.type,
+      prompt: pending.prompt,
+      expiresAt: pending.expiresAt,
+    };
+  }
+
+  /**
+   * Get all pending challenges for a session.
+   */
+  getChallengesForSession(sessionId: string): MFAChallenge[] {
+    const challenges: MFAChallenge[] = [];
+    for (const pending of this.pendingChallenges.values()) {
+      if (pending.sessionId === sessionId) {
+        challenges.push({
+          id: pending.id,
+          sessionId: pending.sessionId,
+          type: pending.type,
+          prompt: pending.prompt,
+          expiresAt: pending.expiresAt,
+        });
+      }
+    }
+    return challenges;
+  }
+
+  /**
+   * Cancel a pending challenge.
+   */
+  cancelChallenge(challengeId: string): boolean {
+    const challenge = this.pendingChallenges.get(challengeId);
+    if (!challenge) return false;
+
+    if (challenge.reject) {
+      challenge.reject({
+        code: 'mfa_failed',
+        message: 'MFA challenge was cancelled',
+      });
+    }
+
+    this.pendingChallenges.delete(challengeId);
+    this.clearTimeoutTimer(challengeId);
+    return true;
+  }
+
+  /**
+   * Get count of pending challenges.
+   */
+  getPendingChallengeCount(): number {
+    return this.pendingChallenges.size;
+  }
+
+  /**
+   * Clear all pending challenges (for testing).
+   */
+  clear(): void {
+    // Clear all timeout timers
+    for (const challengeId of this.timeoutTimers.keys()) {
+      this.clearTimeoutTimer(challengeId);
+    }
+
+    // Reject all pending challenges
+    for (const challenge of this.pendingChallenges.values()) {
+      if (challenge.reject) {
+        challenge.reject({
+          code: 'mfa_failed',
+          message: 'Auth tunnel was cleared',
+        });
+      }
+    }
+
+    this.pendingChallenges.clear();
+    this.timeoutTimers.clear();
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a new Auth Tunnel instance.
+ */
+export function createAuthTunnel(config?: AuthTunnelConfig): AuthTunnel {
+  return new AuthTunnel(config);
+}