outcome-cli 1.0.0

package/src/modules/omnibridge/execution/shadow-session.ts

@@ -0,0 +1,794 @@
+/**
+ * Shadow Session Orchestrator
+ *
+ * Manages virtualized browser environments with persistent authentication.
+ * Each Shadow Session is isolated, fingerprinted, and maintains its own state.
+ *
+ * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 5.5
+ */
+
+import { randomBytes } from 'crypto';
+import type {
+  ShadowSession,
+  DeviceFingerprint,
+  SessionConfig,
+} from '../core/types.js';
+import type { SessionVault, RawSessionData } from '../auth/session-vault.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Browser context state for isolation.
+ */
+export interface BrowserContextState {
+  /** Unique context ID */
+  contextId: string;
+  /** Cookies stored in this context */
+  cookies: CookieData[];
+  /** localStorage data */
+  localStorage: Record<string, string>;
+  /** sessionStorage data */
+  sessionStorage: Record<string, string>;
+  /** Headers to use for requests */
+  headers: Record<string, string>;
+  /** Last activity timestamp */
+  lastActivity: number;
+}
+
+/**
+ * Cookie data structure.
+ */
+export interface CookieData {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+/**
+ * Shadow Session with internal state.
+ */
+export interface ShadowSessionInternal extends ShadowSession {
+  /** Browser context state */
+  contextState: BrowserContextState;
+  /** Agent ID this session belongs to */
+  agentId?: string;
+  /** Whether session is currently locked for use */
+  locked: boolean;
+}
+
+/**
+ * Session creation result.
+ */
+export interface SessionCreationResult {
+  success: boolean;
+  session?: ShadowSession;
+  error?: string;
+}
+
+/**
+ * Session resumption result.
+ */
+export interface SessionResumptionResult {
+  success: boolean;
+  session?: ShadowSession;
+  error?: string;
+  reAuthRequired?: boolean;
+}
+
+/**
+ * Heartbeat result.
+ */
+export interface HeartbeatResult {
+  success: boolean;
+  sessionActive: boolean;
+  nextHeartbeatMs: number;
+  error?: string;
+}
+
+// =============================================================================
+// Fingerprint Generation
+// =============================================================================
+
+/**
+ * Common user agents for realistic fingerprinting.
+ */
+const USER_AGENTS = [
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15',
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+];
+
+/**
+ * Common screen resolutions.
+ */
+const RESOLUTIONS = [
+  { width: 1920, height: 1080 },
+  { width: 1366, height: 768 },
+  { width: 1536, height: 864 },
+  { width: 1440, height: 900 },
+  { width: 2560, height: 1440 },
+  { width: 1280, height: 720 },
+];
+
+/**
+ * Common fonts for fingerprinting.
+ */
+const FONT_SETS = [
+  ['Arial', 'Helvetica', 'Times New Roman', 'Georgia', 'Verdana', 'Courier New'],
+  ['Arial', 'Helvetica Neue', 'Segoe UI', 'Roboto', 'Open Sans', 'Lato'],
+  ['San Francisco', 'Helvetica', 'Arial', 'Lucida Grande', 'Geneva'],
+];
+
+/**
+ * Common timezones.
+ */
+const TIMEZONES = [
+  'America/New_York',
+  'America/Los_Angeles',
+  'America/Chicago',
+  'Europe/London',
+  'Europe/Paris',
+  'Asia/Tokyo',
+  'Asia/Shanghai',
+];
+
+/**
+ * Common languages.
+ */
+const LANGUAGES = ['en-US', 'en-GB', 'en', 'es-ES', 'fr-FR', 'de-DE', 'ja-JP', 'zh-CN'];
+
+/**
+ * Generate a unique device fingerprint.
+ * Creates realistic browser fingerprints to avoid bot detection.
+ *
+ * Requirements: 4.1, 4.2
+ */
+export function generateFingerprint(seed?: string): DeviceFingerprint {
+  // Use seed for deterministic generation if provided
+  const random = seed
+    ? createSeededRandom(seed)
+    : () => Math.random();
+
+  const resolution = RESOLUTIONS[Math.floor(random() * RESOLUTIONS.length)];
+  const userAgent = USER_AGENTS[Math.floor(random() * USER_AGENTS.length)];
+  const fonts = FONT_SETS[Math.floor(random() * FONT_SETS.length)];
+  const timezone = TIMEZONES[Math.floor(random() * TIMEZONES.length)];
+  const language = LANGUAGES[Math.floor(random() * LANGUAGES.length)];
+
+  // Generate a unique GPU signature
+  const gpuVendors = ['NVIDIA', 'AMD', 'Intel'];
+  const gpuModels = ['GeForce RTX 3080', 'Radeon RX 6800', 'UHD Graphics 630', 'GeForce GTX 1660'];
+  const gpuVendor = gpuVendors[Math.floor(random() * gpuVendors.length)];
+  const gpuModel = gpuModels[Math.floor(random() * gpuModels.length)];
+  const gpuSignature = `${gpuVendor} ${gpuModel}`;
+
+  return {
+    resolution,
+    userAgent,
+    fonts,
+    gpuSignature,
+    timezone,
+    language,
+  };
+}
+
+/**
+ * Create a seeded random number generator for deterministic fingerprints.
+ */
+function createSeededRandom(seed: string): () => number {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i++) {
+    const char = seed.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+
+  return () => {
+    hash = Math.sin(hash) * 10000;
+    return hash - Math.floor(hash);
+  };
+}
+
+// =============================================================================
+// Shadow Session Orchestrator
+// =============================================================================
+
+/**
+ * Configuration for the Shadow Session Orchestrator.
+ */
+export interface ShadowSessionOrchestratorConfig {
+  /** Session Vault for credential storage */
+  vault?: SessionVault;
+  /** Heartbeat interval in milliseconds (default: 30000) */
+  heartbeatIntervalMs?: number;
+  /** Session timeout in milliseconds (default: 3600000 = 1 hour) */
+  sessionTimeoutMs?: number;
+  /** Maximum concurrent sessions (default: 100) */
+  maxConcurrentSessions?: number;
+}
+
+/**
+ * Shadow Session Orchestrator
+ *
+ * Manages virtualized browser environments with:
+ * - Unique device fingerprints per session
+ * - Per-agent isolation (no cross-contamination)
+ * - Persistent authentication via Session Vault
+ * - Automatic heartbeat and session maintenance
+ *
+ * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 5.5
+ */
+export class ShadowSessionOrchestrator {
+  private readonly vault?: SessionVault;
+  private readonly heartbeatIntervalMs: number;
+  private readonly sessionTimeoutMs: number;
+  private readonly maxConcurrentSessions: number;
+
+  /** Active sessions by ID */
+  private sessions: Map<string, ShadowSessionInternal> = new Map();
+
+  /** Sessions by agent ID for isolation tracking */
+  private sessionsByAgent: Map<string, Set<string>> = new Map();
+
+  /** Heartbeat timers by session ID */
+  private heartbeatTimers: Map<string, NodeJS.Timeout> = new Map();
+
+  constructor(config: ShadowSessionOrchestratorConfig = {}) {
+    this.vault = config.vault;
+    this.heartbeatIntervalMs = config.heartbeatIntervalMs ?? 30000;
+    this.sessionTimeoutMs = config.sessionTimeoutMs ?? 3600000;
+    this.maxConcurrentSessions = config.maxConcurrentSessions ?? 100;
+  }
+
+  // ===========================================================================
+  // Session Creation
+  // ===========================================================================
+
+  /**
+   * Generate a unique session ID.
+   */
+  private generateSessionId(): string {
+    return `shadow_${randomBytes(16).toString('hex')}`;
+  }
+
+  /**
+   * Generate a unique context ID for browser isolation.
+   */
+  private generateContextId(): string {
+    return `ctx_${randomBytes(12).toString('hex')}`;
+  }
+
+  /**
+   * Create a new Shadow Session with unique fingerprint.
+   *
+   * Requirements: 4.1, 4.2
+   */
+  async create(config: SessionConfig, agentId?: string): Promise<SessionCreationResult> {
+    // Check concurrent session limit
+    if (this.sessions.size >= this.maxConcurrentSessions) {
+      return {
+        success: false,
+        error: `Maximum concurrent sessions (${this.maxConcurrentSessions}) reached`,
+      };
+    }
+
+    const sessionId = this.generateSessionId();
+    const contextId = this.generateContextId();
+    const now = Date.now();
+
+    // Use provided fingerprint or generate a new one
+    const fingerprint = config.fingerprint ?? generateFingerprint(sessionId);
+
+    // Create isolated browser context state
+    const contextState: BrowserContextState = {
+      contextId,
+      cookies: [],
+      localStorage: {},
+      sessionStorage: {},
+      headers: this.generateHeaders(fingerprint),
+      lastActivity: now,
+    };
+
+    // Create the session
+    const session: ShadowSessionInternal = {
+      id: sessionId,
+      domain: config.targetDomain,
+      status: 'active',
+      createdAt: now,
+      lastHeartbeat: now,
+      fingerprint,
+      contextState,
+      agentId,
+      locked: false,
+    };
+
+    // Store the session
+    this.sessions.set(sessionId, session);
+
+    // Track by agent ID for isolation
+    if (agentId) {
+      if (!this.sessionsByAgent.has(agentId)) {
+        this.sessionsByAgent.set(agentId, new Set());
+      }
+      this.sessionsByAgent.get(agentId)!.add(sessionId);
+    }
+
+    // Start heartbeat timer
+    this.startHeartbeat(sessionId);
+
+    // Return public session (without internal state)
+    return {
+      success: true,
+      session: this.toPublicSession(session),
+    };
+  }
+
+  /**
+   * Generate realistic HTTP headers based on fingerprint.
+   */
+  private generateHeaders(fingerprint: DeviceFingerprint): Record<string, string> {
+    return {
+      'User-Agent': fingerprint.userAgent,
+      'Accept-Language': `${fingerprint.language},en;q=0.9`,
+      'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+      'Accept-Encoding': 'gzip, deflate, br',
+      'Connection': 'keep-alive',
+      'Upgrade-Insecure-Requests': '1',
+      'Sec-Fetch-Dest': 'document',
+      'Sec-Fetch-Mode': 'navigate',
+      'Sec-Fetch-Site': 'none',
+      'Sec-Fetch-User': '?1',
+    };
+  }
+
+  /**
+   * Convert internal session to public session (hide internal state).
+   */
+  private toPublicSession(internal: ShadowSessionInternal): ShadowSession {
+    return {
+      id: internal.id,
+      domain: internal.domain,
+      status: internal.status,
+      createdAt: internal.createdAt,
+      lastHeartbeat: internal.lastHeartbeat,
+      fingerprint: internal.fingerprint,
+    };
+  }
+
+  // ===========================================================================
+  // Session Heartbeat and Persistence
+  // ===========================================================================
+
+  /**
+   * Start heartbeat timer for a session.
+   *
+   * Requirements: 4.3
+   */
+  private startHeartbeat(sessionId: string): void {
+    // Clear existing timer if any
+    this.stopHeartbeat(sessionId);
+
+    const timer = setInterval(() => {
+      this.performHeartbeat(sessionId);
+    }, this.heartbeatIntervalMs);
+
+    this.heartbeatTimers.set(sessionId, timer);
+  }
+
+  /**
+   * Stop heartbeat timer for a session.
+   */
+  private stopHeartbeat(sessionId: string): void {
+    const timer = this.heartbeatTimers.get(sessionId);
+    if (timer) {
+      clearInterval(timer);
+      this.heartbeatTimers.delete(sessionId);
+    }
+  }
+
+  /**
+   * Perform heartbeat for a session.
+   * Refreshes cookies and rotates headers to maintain session.
+   *
+   * Requirements: 4.3
+   */
+  private async performHeartbeat(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      this.stopHeartbeat(sessionId);
+      return;
+    }
+
+    const now = Date.now();
+
+    // Check if session has timed out
+    if (now - session.lastHeartbeat > this.sessionTimeoutMs) {
+      session.status = 'expired';
+      this.stopHeartbeat(sessionId);
+      return;
+    }
+
+    // Update heartbeat timestamp
+    session.lastHeartbeat = now;
+    session.contextState.lastActivity = now;
+
+    // Rotate some headers to appear more human-like
+    this.rotateHeaders(session);
+  }
+
+  /**
+   * Rotate headers to maintain realistic behavior.
+   */
+  private rotateHeaders(session: ShadowSessionInternal): void {
+    // Slightly vary Accept-Language quality values
+    const lang = session.fingerprint.language;
+    const quality = (0.8 + Math.random() * 0.2).toFixed(1);
+    session.contextState.headers['Accept-Language'] = `${lang},en;q=${quality}`;
+  }
+
+  /**
+   * Manually trigger heartbeat for a session.
+   *
+   * Requirements: 4.3
+   */
+  async heartbeat(sessionId: string): Promise<HeartbeatResult> {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        sessionActive: false,
+        nextHeartbeatMs: 0,
+        error: 'Session not found',
+      };
+    }
+
+    if (session.status === 'expired') {
+      return {
+        success: false,
+        sessionActive: false,
+        nextHeartbeatMs: 0,
+        error: 'Session expired',
+      };
+    }
+
+    await this.performHeartbeat(sessionId);
+
+    return {
+      success: true,
+      sessionActive: session.status === 'active',
+      nextHeartbeatMs: this.heartbeatIntervalMs,
+    };
+  }
+
+  // ===========================================================================
+  // Session Isolation
+  // ===========================================================================
+
+  /**
+   * Get a session by ID.
+   */
+  getSession(sessionId: string): ShadowSession | null {
+    const session = this.sessions.get(sessionId);
+    return session ? this.toPublicSession(session) : null;
+  }
+
+  /**
+   * Get internal session (for testing).
+   */
+  getInternalSession(sessionId: string): ShadowSessionInternal | null {
+    return this.sessions.get(sessionId) ?? null;
+  }
+
+  /**
+   * Get all sessions for an agent.
+   *
+   * Requirements: 4.4
+   */
+  getSessionsForAgent(agentId: string): ShadowSession[] {
+    const sessionIds = this.sessionsByAgent.get(agentId);
+    if (!sessionIds) {
+      return [];
+    }
+
+    return Array.from(sessionIds)
+      .map((id) => this.sessions.get(id))
+      .filter((s): s is ShadowSessionInternal => s !== undefined)
+      .map((s) => this.toPublicSession(s));
+  }
+
+  /**
+   * Check if two sessions are isolated (no shared state).
+   *
+   * Requirements: 4.4
+   */
+  areSessionsIsolated(sessionId1: string, sessionId2: string): boolean {
+    const session1 = this.sessions.get(sessionId1);
+    const session2 = this.sessions.get(sessionId2);
+
+    if (!session1 || !session2) {
+      return true; // Non-existent sessions are trivially isolated
+    }
+
+    // Sessions are isolated if they have different context IDs
+    return session1.contextState.contextId !== session2.contextState.contextId;
+  }
+
+  /**
+   * Modify session state (for testing isolation).
+   */
+  modifySessionState(
+    sessionId: string,
+    key: string,
+    value: string,
+    storage: 'localStorage' | 'sessionStorage' = 'localStorage'
+  ): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    if (storage === 'localStorage') {
+      session.contextState.localStorage[key] = value;
+    } else {
+      session.contextState.sessionStorage[key] = value;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get session state value (for testing isolation).
+   */
+  getSessionStateValue(
+    sessionId: string,
+    key: string,
+    storage: 'localStorage' | 'sessionStorage' = 'localStorage'
+  ): string | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return undefined;
+    }
+
+    if (storage === 'localStorage') {
+      return session.contextState.localStorage[key];
+    } else {
+      return session.contextState.sessionStorage[key];
+    }
+  }
+
+  // ===========================================================================
+  // Session Resumption from Vault
+  // ===========================================================================
+
+  /**
+   * Resume a session from the vault without re-authentication.
+   *
+   * Requirements: 5.5
+   */
+  async resume(domain: string, agentId?: string): Promise<SessionResumptionResult> {
+    if (!this.vault) {
+      return {
+        success: false,
+        error: 'No vault configured for session resumption',
+        reAuthRequired: true,
+      };
+    }
+
+    // Try to retrieve session from vault
+    const vaultedSession = await this.vault.retrieve(domain);
+
+    if (!vaultedSession) {
+      return {
+        success: false,
+        error: 'No vaulted session found for domain',
+        reAuthRequired: true,
+      };
+    }
+
+    // Check if session is expired
+    if (vaultedSession.expiresAt < Date.now()) {
+      return {
+        success: false,
+        error: 'Vaulted session has expired',
+        reAuthRequired: true,
+      };
+    }
+
+    // Decrypt session data
+    const rawData = await this.vault.retrieveDecrypted(domain);
+    if (!rawData) {
+      return {
+        success: false,
+        error: 'Failed to decrypt vaulted session',
+        reAuthRequired: true,
+      };
+    }
+
+    // Create a new session with the vaulted state
+    const fingerprint = generateFingerprint();
+    const config: SessionConfig = {
+      targetDomain: domain,
+      fingerprint,
+      isolationLevel: 'strict',
+    };
+
+    const createResult = await this.create(config, agentId);
+    if (!createResult.success || !createResult.session) {
+      return {
+        success: false,
+        error: createResult.error ?? 'Failed to create session',
+        reAuthRequired: true,
+      };
+    }
+
+    // Restore the vaulted state to the new session
+    const session = this.sessions.get(createResult.session.id);
+    if (session) {
+      // Parse and restore cookies
+      try {
+        session.contextState.cookies = JSON.parse(rawData.cookies);
+      } catch {
+        session.contextState.cookies = [];
+      }
+
+      // Parse and restore localStorage
+      try {
+        session.contextState.localStorage = JSON.parse(rawData.localStorage);
+      } catch {
+        session.contextState.localStorage = {};
+      }
+
+      // Parse and restore sessionStorage
+      try {
+        session.contextState.sessionStorage = JSON.parse(rawData.sessionStorage);
+      } catch {
+        session.contextState.sessionStorage = {};
+      }
+    }
+
+    return {
+      success: true,
+      session: createResult.session,
+      reAuthRequired: false,
+    };
+  }
+
+  /**
+   * Save current session state to vault.
+   */
+  async saveToVault(sessionId: string): Promise<boolean> {
+    if (!this.vault) {
+      return false;
+    }
+
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const rawData: RawSessionData = {
+      cookies: JSON.stringify(session.contextState.cookies),
+      localStorage: JSON.stringify(session.contextState.localStorage),
+      sessionStorage: JSON.stringify(session.contextState.sessionStorage),
+    };
+
+    // Store with 24-hour expiration
+    const expiresAt = Date.now() + 86400000;
+    await this.vault.store(session.domain, rawData, expiresAt);
+
+    return true;
+  }
+
+  /**
+   * Check if a vaulted session exists and is valid.
+   *
+   * Requirements: 5.5
+   */
+  async hasValidVaultedSession(domain: string): Promise<boolean> {
+    if (!this.vault) {
+      return false;
+    }
+
+    const session = await this.vault.retrieve(domain);
+    return session !== null && session.expiresAt > Date.now();
+  }
+
+  // ===========================================================================
+  // Session Destruction
+  // ===========================================================================
+
+  /**
+   * Destroy a session and clean up resources.
+   */
+  async destroy(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+
+    // Stop heartbeat
+    this.stopHeartbeat(sessionId);
+
+    // Remove from agent tracking
+    if (session.agentId) {
+      const agentSessions = this.sessionsByAgent.get(session.agentId);
+      if (agentSessions) {
+        agentSessions.delete(sessionId);
+        if (agentSessions.size === 0) {
+          this.sessionsByAgent.delete(session.agentId);
+        }
+      }
+    }
+
+    // Remove session
+    this.sessions.delete(sessionId);
+  }
+
+  /**
+   * Destroy all sessions for an agent.
+   */
+  async destroyAllForAgent(agentId: string): Promise<number> {
+    const sessionIds = this.sessionsByAgent.get(agentId);
+    if (!sessionIds) {
+      return 0;
+    }
+
+    const count = sessionIds.size;
+    for (const sessionId of sessionIds) {
+      await this.destroy(sessionId);
+    }
+
+    return count;
+  }
+
+  /**
+   * Get count of active sessions.
+   */
+  getActiveSessionCount(): number {
+    return Array.from(this.sessions.values()).filter((s) => s.status === 'active').length;
+  }
+
+  /**
+   * Get total session count.
+   */
+  getTotalSessionCount(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Clear all sessions (for testing).
+   */
+  clear(): void {
+    // Stop all heartbeats
+    for (const sessionId of this.heartbeatTimers.keys()) {
+      this.stopHeartbeat(sessionId);
+    }
+
+    this.sessions.clear();
+    this.sessionsByAgent.clear();
+    this.heartbeatTimers.clear();
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a new Shadow Session Orchestrator.
+ */
+export function createShadowSessionOrchestrator(
+  config?: ShadowSessionOrchestratorConfig
+): ShadowSessionOrchestrator {
+  return new ShadowSessionOrchestrator(config);
+}