@dynamicu/chromedebug-mcp 2.2.0

package/src/services/heartbeat-manager.js

@@ -0,0 +1,200 @@
+/**
+ * HeartbeatManager - Manages heartbeats for multiple Chrome Debug sessions
+ * 
+ * Coordinates heartbeat mechanisms across different session managers
+ * to ensure sessions stay alive and detect stale sessions for cleanup.
+ * 
+ * Key Features:
+ * - Multi-session heartbeat coordination
+ * - Stale heartbeat detection
+ * - Automatic cleanup integration
+ * - Thread-safe heartbeat operations
+ */
+
+export class HeartbeatManager {
+  constructor() {
+    this.heartbeats = new Map(); // sessionId -> { interval, lastUpdate }
+    this.HEARTBEAT_INTERVAL = 30000; // 30 seconds
+    this.STALE_THRESHOLD = 5 * 60 * 1000; // 5 minutes
+  }
+
+  /**
+   * Starts heartbeat for a session
+   * @param {string} sessionId - Session ID to start heartbeat for
+   * @param {Function} updateCallback - Optional callback to call on each heartbeat
+   */
+  startHeartbeat(sessionId, updateCallback = null) {
+    // Stop existing heartbeat if running
+    this.stopHeartbeat(sessionId);
+
+    const heartbeatData = {
+      lastUpdate: new Date(),
+      callback: updateCallback,
+      interval: setInterval(() => {
+        heartbeatData.lastUpdate = new Date();
+        if (updateCallback && typeof updateCallback === 'function') {
+          updateCallback(sessionId).catch(error => {
+            console.error(`[HeartbeatManager] Heartbeat callback error for ${sessionId}:`, error);
+          });
+        }
+      }, this.HEARTBEAT_INTERVAL)
+    };
+
+    this.heartbeats.set(sessionId, heartbeatData);
+    console.log(`[HeartbeatManager] Started heartbeat for session ${sessionId}`);
+  }
+
+  /**
+   * Stops heartbeat for a session
+   * @param {string} sessionId - Session ID to stop heartbeat for
+   */
+  stopHeartbeat(sessionId) {
+    const heartbeatData = this.heartbeats.get(sessionId);
+    if (heartbeatData) {
+      clearInterval(heartbeatData.interval);
+      this.heartbeats.delete(sessionId);
+      console.log(`[HeartbeatManager] Stopped heartbeat for session ${sessionId}`);
+    }
+  }
+
+  /**
+   * Checks if heartbeat is running for a session
+   * @param {string} sessionId - Session ID to check
+   * @returns {boolean} True if heartbeat is running
+   */
+  isHeartbeatRunning(sessionId) {
+    return this.heartbeats.has(sessionId);
+  }
+
+  /**
+   * Updates heartbeat timestamp for a session (manual update)
+   * @param {string} sessionId - Session ID to update
+   * @returns {Promise<void>}
+   */
+  async updateHeartbeat(sessionId) {
+    const heartbeatData = this.heartbeats.get(sessionId);
+    if (heartbeatData) {
+      heartbeatData.lastUpdate = new Date();
+      console.log(`[HeartbeatManager] Manual heartbeat update for session ${sessionId}`);
+    } else {
+      console.warn(`[HeartbeatManager] Cannot update heartbeat for unknown session ${sessionId}`);
+    }
+  }
+
+  /**
+   * Gets last heartbeat time for a session
+   * @param {string} sessionId - Session ID to check
+   * @returns {Date|null} Last heartbeat time or null if not found
+   */
+  getLastHeartbeat(sessionId) {
+    const heartbeatData = this.heartbeats.get(sessionId);
+    return heartbeatData ? heartbeatData.lastUpdate : null;
+  }
+
+  /**
+   * Checks for stale heartbeats across all sessions
+   * @returns {Promise<string[]>} Array of session IDs with stale heartbeats
+   */
+  async checkStaleHeartbeats() {
+    const now = new Date();
+    const staleSessionIds = [];
+
+    for (const [sessionId, heartbeatData] of this.heartbeats.entries()) {
+      const timeSinceHeartbeat = now.getTime() - heartbeatData.lastUpdate.getTime();
+      
+      if (timeSinceHeartbeat > this.STALE_THRESHOLD) {
+        staleSessionIds.push(sessionId);
+      }
+    }
+
+    if (staleSessionIds.length > 0) {
+      console.log(`[HeartbeatManager] Found ${staleSessionIds.length} stale heartbeats:`, staleSessionIds);
+    }
+
+    return staleSessionIds;
+  }
+
+  /**
+   * Gets heartbeat status for all sessions
+   * @returns {Object} Heartbeat status summary
+   */
+  getHeartbeatStatus() {
+    const now = new Date();
+    const status = {
+      totalSessions: this.heartbeats.size,
+      activeSessions: 0,
+      staleSessions: 0,
+      sessionDetails: []
+    };
+
+    for (const [sessionId, heartbeatData] of this.heartbeats.entries()) {
+      const timeSinceHeartbeat = now.getTime() - heartbeatData.lastUpdate.getTime();
+      const isStale = timeSinceHeartbeat > this.STALE_THRESHOLD;
+
+      if (isStale) {
+        status.staleSessions++;
+      } else {
+        status.activeSessions++;
+      }
+
+      status.sessionDetails.push({
+        sessionId,
+        lastHeartbeat: heartbeatData.lastUpdate,
+        timeSinceHeartbeat,
+        isStale
+      });
+    }
+
+    return status;
+  }
+
+  /**
+   * Stops all heartbeats (cleanup method)
+   */
+  stopAllHeartbeats() {
+    console.log(`[HeartbeatManager] Stopping all heartbeats (${this.heartbeats.size} sessions)`);
+    
+    for (const [sessionId, heartbeatData] of this.heartbeats.entries()) {
+      clearInterval(heartbeatData.interval);
+    }
+    
+    this.heartbeats.clear();
+  }
+
+  /**
+   * Automatically cleans up stale heartbeats
+   * @returns {Promise<string[]>} Array of cleaned up session IDs
+   */
+  async autoCleanupStaleHeartbeats() {
+    const staleSessionIds = await this.checkStaleHeartbeats();
+    
+    for (const sessionId of staleSessionIds) {
+      this.stopHeartbeat(sessionId);
+    }
+
+    if (staleSessionIds.length > 0) {
+      console.log(`[HeartbeatManager] Auto-cleaned ${staleSessionIds.length} stale heartbeats`);
+    }
+
+    return staleSessionIds;
+  }
+
+  /**
+   * Gets statistics about heartbeat performance
+   * @returns {Object} Heartbeat statistics
+   */
+  getStatistics() {
+    const status = this.getHeartbeatStatus();
+    
+    return {
+      totalSessions: status.totalSessions,
+      activeSessions: status.activeSessions,
+      staleSessions: status.staleSessions,
+      stalePercentage: status.totalSessions > 0 
+        ? Math.round((status.staleSessions / status.totalSessions) * 100) 
+        : 0,
+      heartbeatInterval: this.HEARTBEAT_INTERVAL,
+      staleThreshold: this.STALE_THRESHOLD
+    };
+  }
+}

package/src/services/http-client.js

@@ -0,0 +1,195 @@
+/**
+ * HTTP Client Service for MCP handlers to access authenticated endpoints
+ * This service handles service-to-service authentication
+ */
+
+// Use built-in fetch (Node.js 18+)
+
+class HttpClientService {
+  constructor() {
+    this.baseUrl = null;
+    this.serviceToken = process.env.MCP_SERVICE_TOKEN;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize the HTTP client with server port
+   */
+  async initialize() {
+    if (this.initialized) return;
+    
+    try {
+      // Get the current server port from configuration
+      let port = process.env.CHROME_PILOT_PORT || 3000;
+      
+      // Try to load configLoader dynamically
+      try {
+        const { configLoader } = await import('../config-loader.js');
+        if (configLoader && typeof configLoader.getConfig === 'function') {
+          const config = configLoader.getConfig();
+          port = config.httpPort || port;
+        }
+      } catch (configError) {
+        console.warn('[HttpClient] Config loader not available, using default port:', port);
+      }
+      
+      this.baseUrl = `http://localhost:${port}`;
+      this.initialized = true;
+      console.log(`[HttpClient] Initialized with base URL: ${this.baseUrl}`);
+    } catch (error) {
+      console.error('[HttpClient] Failed to initialize:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Make authenticated request to HTTP server
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} options - Request options
+   * @returns {Promise<Object>} Response data
+   */
+  async request(endpoint, options = {}) {
+    await this.initialize();
+    
+    if (!this.serviceToken) {
+      throw new Error('MCP service token not available. Cannot make authenticated requests.');
+    }
+
+    const url = `${this.baseUrl}${endpoint}`;
+    const requestOptions = {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-service-token': this.serviceToken,
+        ...options.headers
+      },
+      ...options
+    };
+
+    if (options.body && typeof options.body === 'object') {
+      requestOptions.body = JSON.stringify(options.body);
+    }
+
+    try {
+      console.log(`[HttpClient] Making ${requestOptions.method} request to ${url}`);
+      const response = await fetch(url, requestOptions);
+      
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+      }
+
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error(`[HttpClient] Request failed for ${url}:`, error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get workflow recording via HTTP
+   * @param {string} sessionId - Session ID
+   * @returns {Promise<Object>} Workflow recording data
+   */
+  async getWorkflowRecording(sessionId) {
+    return this.request(`/chromedebug/workflow-recording/${sessionId}`);
+  }
+
+  /**
+   * List workflow recordings via HTTP
+   * @returns {Promise<Object>} List of recordings
+   */
+  async listWorkflowRecordings() {
+    return this.request('/chromedebug/workflow-recordings');
+  }
+
+  /**
+   * Get frame session info via HTTP
+   * @param {string} sessionId - Session ID
+   * @returns {Promise<Object>} Frame session info
+   */
+  async getFrameSessionInfo(sessionId) {
+    return this.request(`/chromedebug/frame-session/${sessionId}`);
+  }
+
+  /**
+   * Get specific frame via HTTP
+   * @param {string} sessionId - Session ID
+   * @param {number} frameIndex - Frame index
+   * @returns {Promise<Object>} Frame data
+   */
+  async getFrame(sessionId, frameIndex) {
+    return this.request(`/chromedebug/frame/${sessionId}/${frameIndex}`);
+  }
+
+  /**
+   * Search frame logs via HTTP
+   * @param {string} sessionId - Session ID
+   * @param {string} searchText - Search text
+   * @param {string} logLevel - Log level filter
+   * @param {number} maxResults - Maximum results
+   * @returns {Promise<Object>} Search results
+   */
+  async searchFrameLogs(sessionId, searchText, logLevel = 'all', maxResults = 50) {
+    const params = new URLSearchParams({
+      searchText,
+      logLevel,
+      maxResults: maxResults.toString()
+    });
+    return this.request(`/chromedebug/frame-logs/search/${sessionId}?${params}`);
+  }
+
+  /**
+   * Get frame logs paginated via HTTP
+   * @param {string} sessionId - Session ID
+   * @param {number} frameIndex - Frame index
+   * @param {number} offset - Offset
+   * @param {number} limit - Limit
+   * @param {string} logLevel - Log level filter
+   * @param {string} searchText - Search text
+   * @returns {Promise<Object>} Paginated logs
+   */
+  async getFrameLogsPaginated(sessionId, frameIndex, offset = 0, limit = 100, logLevel = 'all', searchText = null) {
+    const params = new URLSearchParams({
+      offset: offset.toString(),
+      limit: limit.toString(),
+      logLevel
+    });
+    if (searchText) {
+      params.append('searchText', searchText);
+    }
+    return this.request(`/chromedebug/frame-logs/${sessionId}/${frameIndex}?${params}`);
+  }
+
+  /**
+   * Get screen interactions via HTTP
+   * @param {string} sessionId - Session ID
+   * @param {number} frameIndex - Optional frame index
+   * @param {string} type - Optional interaction type filter
+   * @returns {Promise<Object>} Screen interactions
+   */
+  async getScreenInteractions(sessionId, frameIndex = null, type = null) {
+    const params = new URLSearchParams();
+    if (frameIndex !== null) {
+      params.append('frameIndex', frameIndex.toString());
+    }
+    if (type) {
+      params.append('type', type);
+    }
+    const queryString = params.toString();
+    const endpoint = `/chromedebug/screen-interactions/${sessionId}${queryString ? `?${queryString}` : ''}`;
+    return this.request(endpoint);
+  }
+
+  /**
+   * List frame sessions via HTTP
+   * @returns {Promise<Object>} List of frame sessions
+   */
+  async listFrameSessions() {
+    return this.request('/chromedebug/frame-sessions');
+  }
+}
+
+// Export singleton instance
+export const httpClient = new HttpClientService();

package/src/services/process-manager.js

@@ -0,0 +1,318 @@
+/**
+ * Process Manager Service - Secure process management with input validation
+ * Extracted from original index.js with preserved security measures
+ */
+
+/**
+ * Safely validates a process ID to prevent injection attacks
+ * @param {*} pid - The process ID to validate
+ * @returns {number|null} - Validated PID or null if invalid
+ */
+function validateProcessId(pid) {
+  // Security: Check for suspicious characters before parsing
+  const pidStr = String(pid).trim();
+  if (!/^\d+$/.test(pidStr)) {
+    // Contains non-digit characters - potential injection attempt
+    return null;
+  }
+  
+  const numericPid = parseInt(pidStr, 10);
+  if (isNaN(numericPid) || numericPid <= 0 || numericPid > 4194304) { // Max PID on Linux/macOS
+    return null;
+  }
+  return numericPid;
+}
+
+/**
+ * Safely kills a process using Node.js native APIs to prevent command injection
+ * @param {number} pid - Validated process ID
+ * @param {string} signal - Signal to send ('SIGTERM' or 'SIGKILL')
+ * @returns {Promise<boolean>} - True if successful, false otherwise
+ */
+async function safeKillProcess(pid, signal = 'SIGTERM') {
+  const validatedPid = validateProcessId(pid);
+  if (!validatedPid) {
+    console.error(`Invalid process ID: ${pid}`);
+    return false;
+  }
+  
+  try {
+    // Security: Use Node.js native process.kill() instead of shell commands
+    process.kill(validatedPid, signal);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') {
+      // Process doesn't exist
+      return true;
+    } else if (error.code === 'EPERM') {
+      console.error(`Permission denied killing process ${validatedPid}`);
+      return false;
+    } else {
+      console.error(`Error killing process ${validatedPid}: ${error.message}`);
+      return false;
+    }
+  }
+}
+
+/**
+ * Find ChromeDebug MCP processes using Node.js process list instead of shell commands
+ * This prevents command injection while maintaining functionality
+ */
+async function findChromePilotProcesses() {
+  const currentPid = process.pid;
+  const pidsToKill = [];
+  const processDescriptions = [];
+  
+  try {
+    // Security: Use Node.js process list instead of shell commands
+    // This approach uses the 'ps-list' module or similar safe approach
+    // For now, we'll use a safer implementation with spawn instead of exec
+    const { spawn } = await import('child_process');
+    
+    return new Promise((resolve) => {
+      const ps = spawn('ps', ['aux'], { stdio: ['ignore', 'pipe', 'ignore'] });
+      let stdout = '';
+      
+      ps.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+      
+      ps.on('close', (code) => {
+        if (code !== 0) {
+          console.error('Failed to get process list');
+          resolve({ pidsToKill: [], processDescriptions: [] });
+          return;
+        }
+        
+        const lines = stdout.trim().split('\n');
+        
+        for (const line of lines) {
+          // Security: Validate each line and extract PID safely
+          const parts = line.trim().split(/\\s+/);
+          if (parts.length < 2) continue;
+          
+          const pid = validateProcessId(parts[1]);
+          if (!pid || pid === currentPid) continue;
+          
+          // Check if it's a ChromeDebug MCP related process
+          let processType = '';
+          if (line.includes('src/index.js')) {
+            processType = 'MCP server';
+            pidsToKill.push(pid);
+          } else if (line.includes('standalone-server.js')) {
+            processType = 'HTTP server';
+            pidsToKill.push(pid);
+          } else if (line.includes('http-server.js')) {
+            processType = 'HTTP server';
+            pidsToKill.push(pid);
+          } else if (line.includes('chrome-pilot') && line.includes('node')) {
+            processType = 'ChromeDebug MCP process';
+            pidsToKill.push(pid);
+          }
+          
+          if (processType) {
+            processDescriptions.push(`${processType} (PID: ${pid})`);
+          }
+        }
+        
+        resolve({ pidsToKill, processDescriptions });
+      });
+      
+      ps.on('error', (error) => {
+        console.error('Error running ps command:', error);
+        resolve({ pidsToKill: [], processDescriptions: [] });
+      });
+    });
+  } catch (error) {
+    console.error('Error finding ChromeDebug MCP processes:', error);
+    return { pidsToKill: [], processDescriptions: [] };
+  }
+}
+
+/**
+ * Process Manager class for secure process lifecycle management
+ */
+export class ProcessManager {
+  constructor() {
+    this.managedProcesses = new Set();
+    this.shutdownHandlers = [];
+    this.setupGracefulShutdown();
+  }
+
+  /**
+   * Validates and registers a process ID for management
+   * @param {number} pid - Process ID to manage
+   * @returns {boolean} True if successfully registered
+   */
+  registerProcess(pid) {
+    const validatedPid = validateProcessId(pid);
+    if (!validatedPid) {
+      console.error(`Cannot register invalid process ID: ${pid}`);
+      return false;
+    }
+    
+    this.managedProcesses.add(validatedPid);
+    return true;
+  }
+
+  /**
+   * Unregisters a process from management
+   * @param {number} pid - Process ID to unregister
+   */
+  unregisterProcess(pid) {
+    const validatedPid = validateProcessId(pid);
+    if (validatedPid) {
+      this.managedProcesses.delete(validatedPid);
+    }
+  }
+
+  /**
+   * Safely kills a managed process
+   * @param {number} pid - Process ID to kill
+   * @param {string} signal - Signal to send
+   * @returns {Promise<boolean>} Success status
+   */
+  async killProcess(pid, signal = 'SIGTERM') {
+    const result = await safeKillProcess(pid, signal);
+    if (result) {
+      this.unregisterProcess(pid);
+    }
+    return result;
+  }
+
+  /**
+   * Kills all managed processes
+   * @param {string} signal - Signal to send
+   * @returns {Promise<Object>} Kill results
+   */
+  async killAllManagedProcesses(signal = 'SIGTERM') {
+    const results = {
+      killed: [],
+      failed: [],
+      total: this.managedProcesses.size
+    };
+
+    for (const pid of this.managedProcesses) {
+      const success = await safeKillProcess(pid, signal);
+      if (success) {
+        results.killed.push(pid);
+        this.managedProcesses.delete(pid);
+      } else {
+        results.failed.push(pid);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Finds and kills ChromeDebug MCP processes
+   * @returns {Promise<Object>} Cleanup results
+   */
+  async cleanupChromePilotProcesses() {
+    const { pidsToKill, processDescriptions } = await findChromePilotProcesses();
+    
+    const results = {
+      found: processDescriptions,
+      killed: [],
+      failed: [],
+      total: pidsToKill.length
+    };
+
+    if (pidsToKill.length === 0) {
+      return results;
+    }
+
+    console.error('Found existing ChromeDebug MCP processes, cleaning up...');
+    
+    // Try SIGTERM first
+    for (const pid of pidsToKill) {
+      const success = await safeKillProcess(pid, 'SIGTERM');
+      if (success) {
+        results.killed.push(pid);
+      } else {
+        results.failed.push(pid);
+      }
+    }
+
+    // Wait a bit for graceful shutdown
+    if (results.failed.length > 0) {
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      
+      // Try SIGKILL for remaining processes
+      const finalAttempts = [];
+      for (const pid of results.failed) {
+        const success = await safeKillProcess(pid, 'SIGKILL');
+        if (success) {
+          // Move from failed to killed
+          const index = results.failed.indexOf(pid);
+          results.failed.splice(index, 1);
+          results.killed.push(pid);
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Adds a shutdown handler
+   * @param {Function} handler - Cleanup function to call on shutdown
+   */
+  addShutdownHandler(handler) {
+    this.shutdownHandlers.push(handler);
+  }
+
+  /**
+   * Sets up graceful shutdown handling
+   */
+  setupGracefulShutdown() {
+    const cleanup = async (signal) => {
+      console.error(`Received ${signal}, cleaning up...`);
+      
+      // Run custom shutdown handlers
+      for (const handler of this.shutdownHandlers) {
+        try {
+          await handler();
+        } catch (error) {
+          console.error('Error in shutdown handler:', error);
+        }
+      }
+      
+      // Kill all managed processes
+      await this.killAllManagedProcesses('SIGTERM');
+      
+      process.exit(0);
+    };
+
+    // Register signal handlers
+    process.on('SIGINT', () => cleanup('SIGINT'));
+    process.on('SIGTERM', () => cleanup('SIGTERM'));
+    
+    // Handle uncaught exceptions
+    process.on('uncaughtException', (error) => {
+      console.error('Uncaught exception:', error);
+      cleanup('uncaughtException');
+    });
+    
+    process.on('unhandledRejection', (reason, promise) => {
+      console.error('Unhandled rejection at:', promise, 'reason:', reason);
+      cleanup('unhandledRejection');
+    });
+  }
+
+  /**
+   * Gets statistics about managed processes
+   * @returns {Object} Process statistics
+   */
+  getStatistics() {
+    return {
+      managedProcesses: this.managedProcesses.size,
+      shutdownHandlers: this.shutdownHandlers.length,
+      currentPid: process.pid
+    };
+  }
+}
+
+// Export utility functions for backward compatibility
+export { validateProcessId, safeKillProcess, findChromePilotProcesses };