@neverinfamous/mysql-mcp 2.2.0 → 2.3.1

package/src/codemode/security.ts

@@ -0,0 +1,188 @@
+/**
+ * mysql-mcp - Code Mode Security
+ *
+ * Input validation, rate limiting, and audit logging for code execution.
+ */
+
+import { logger } from "../utils/logger.js";
+import {
+  DEFAULT_SECURITY_CONFIG,
+  type SecurityConfig,
+  type ValidationResult,
+  type ExecutionRecord,
+  type SandboxResult,
+} from "./types.js";
+
+/**
+ * Security manager for Code Mode executions
+ */
+export class CodeModeSecurityManager {
+  private readonly config: SecurityConfig;
+  private readonly rateLimitMap = new Map<
+    string,
+    { count: number; resetTime: number }
+  >();
+
+  constructor(config?: Partial<SecurityConfig>) {
+    this.config = { ...DEFAULT_SECURITY_CONFIG, ...config };
+  }
+
+  /**
+   * Validate code before execution
+   */
+  validateCode(code: string): ValidationResult {
+    const errors: string[] = [];
+
+    // Check code length
+    if (!code || typeof code !== "string") {
+      errors.push("Code must be a non-empty string");
+      return { valid: false, errors };
+    }
+
+    if (code.length > this.config.maxCodeLength) {
+      errors.push(
+        `Code exceeds maximum length of ${String(this.config.maxCodeLength)} bytes`,
+      );
+      return { valid: false, errors };
+    }
+
+    // Check for blocked patterns
+    for (const pattern of this.config.blockedPatterns) {
+      if (pattern.test(code)) {
+        errors.push(`Blocked pattern detected: ${pattern.source}`);
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Check rate limit for a client
+   * @returns true if within limits, false if rate limited
+   */
+  checkRateLimit(clientId: string): boolean {
+    const now = Date.now();
+    const windowMs = 60000; // 1 minute window
+
+    const existing = this.rateLimitMap.get(clientId);
+
+    if (!existing || now >= existing.resetTime) {
+      // Start new window
+      this.rateLimitMap.set(clientId, {
+        count: 1,
+        resetTime: now + windowMs,
+      });
+      return true;
+    }
+
+    if (existing.count >= this.config.maxExecutionsPerMinute) {
+      return false;
+    }
+
+    existing.count++;
+    return true;
+  }
+
+  /**
+   * Get remaining rate limit for a client
+   */
+  getRateLimitRemaining(clientId: string): number {
+    const existing = this.rateLimitMap.get(clientId);
+    if (!existing || Date.now() >= existing.resetTime) {
+      return this.config.maxExecutionsPerMinute;
+    }
+    return Math.max(0, this.config.maxExecutionsPerMinute - existing.count);
+  }
+
+  /**
+   * Sanitize and truncate result if too large
+   */
+  sanitizeResult(result: unknown): unknown {
+    try {
+      const serialized = JSON.stringify(result);
+      if (serialized.length > this.config.maxResultSize) {
+        return {
+          _truncated: true,
+          _originalSize: serialized.length,
+          _maxSize: this.config.maxResultSize,
+          preview: serialized.substring(0, 1000) + "...",
+        };
+      }
+      return result;
+    } catch {
+      return {
+        _error: "Result could not be serialized",
+        _type: typeof result,
+      };
+    }
+  }
+
+  /**
+   * Log execution for audit purposes
+   */
+  auditLog(execution: ExecutionRecord): void {
+    const { id, clientId, codePreview, result, readonly } = execution;
+
+    const logContext = {
+      module: "CODEMODE" as const,
+      operation: "execute",
+      entityId: id,
+      clientId: clientId ?? "anonymous",
+      readonly,
+      success: result.success,
+      wallTimeMs: result.metrics.wallTimeMs,
+      memoryUsedMb: result.metrics.memoryUsedMb,
+    };
+
+    if (result.success) {
+      logger.info(
+        `Code execution completed: ${codePreview.substring(0, 50)}...`,
+        logContext,
+      );
+    } else {
+      const errorContext = {
+        ...logContext,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+        ...(result.stack !== undefined ? { stack: result.stack } : {}),
+      };
+      logger.warning(
+        `Code execution failed: ${result.error ?? "unknown error"}`,
+        errorContext,
+      );
+    }
+  }
+
+  /**
+   * Create execution record for audit
+   */
+  createExecutionRecord(
+    code: string,
+    result: SandboxResult,
+    readonly: boolean,
+    clientId?: string,
+  ): ExecutionRecord {
+    return {
+      id: crypto.randomUUID(),
+      clientId,
+      timestamp: new Date(),
+      codePreview: code.length > 200 ? code.substring(0, 200) + "..." : code,
+      result,
+      readonly,
+    };
+  }
+
+  /**
+   * Clean up old rate limit entries
+   */
+  cleanupRateLimits(): void {
+    const now = Date.now();
+    for (const [clientId, entry] of this.rateLimitMap) {
+      if (now >= entry.resetTime) {
+        this.rateLimitMap.delete(clientId);
+      }
+    }
+  }
+}

package/src/codemode/types.ts

@@ -0,0 +1,194 @@
+/**
+ * mysql-mcp - Code Mode Types
+ *
+ * Type definitions for the sandboxed code execution environment.
+ */
+
+import type { ToolGroup } from "../types/index.js";
+
+// =============================================================================
+// Sandbox Configuration
+// =============================================================================
+
+/**
+ * Options for sandbox execution
+ */
+export interface SandboxOptions {
+  /** Memory limit in MB (default: 128) */
+  memoryLimitMb?: number;
+  /** Execution timeout in milliseconds (default: 30000) */
+  timeoutMs?: number;
+  /** CPU time limit in milliseconds (default: 10000) */
+  cpuLimitMs?: number;
+}
+
+/**
+ * Options for the sandbox pool
+ */
+export interface PoolOptions {
+  /** Minimum instances to keep warm (default: 2) */
+  minInstances?: number;
+  /** Maximum instances in pool (default: 10) */
+  maxInstances?: number;
+  /** Idle timeout before disposing instance (default: 60000ms) */
+  idleTimeoutMs?: number;
+}
+
+/**
+ * Default sandbox configuration
+ */
+export const DEFAULT_SANDBOX_OPTIONS: Required<SandboxOptions> = {
+  memoryLimitMb: 128,
+  timeoutMs: 30000,
+  cpuLimitMs: 10000,
+};
+
+/**
+ * Default pool configuration
+ */
+export const DEFAULT_POOL_OPTIONS: Required<PoolOptions> = {
+  minInstances: 2,
+  maxInstances: 10,
+  idleTimeoutMs: 60000,
+};
+
+// =============================================================================
+// Execution Results
+// =============================================================================
+
+/**
+ * Metrics collected during sandbox execution
+ */
+export interface ExecutionMetrics {
+  /** Wall clock time in milliseconds */
+  wallTimeMs: number;
+  /** CPU time consumed in milliseconds */
+  cpuTimeMs: number;
+  /** Peak memory usage in MB */
+  memoryUsedMb: number;
+}
+
+/**
+ * Result of sandbox code execution
+ */
+export interface SandboxResult {
+  /** Whether execution completed successfully */
+  success: boolean;
+  /** Return value from the code (if successful) */
+  result?: unknown;
+  /** Error message (if failed) */
+  error?: string | undefined;
+  /** Stack trace (if failed) */
+  stack?: string | undefined;
+  /** Execution metrics */
+  metrics: ExecutionMetrics;
+}
+
+// =============================================================================
+// Security Configuration
+// =============================================================================
+
+/**
+ * Security configuration for code validation
+ */
+export interface SecurityConfig {
+  /** Maximum code length in bytes (default: 50KB) */
+  maxCodeLength: number;
+  /** Maximum executions per minute per client (default: 60) */
+  maxExecutionsPerMinute: number;
+  /** Maximum result size in bytes (default: 10MB) */
+  maxResultSize: number;
+  /** Patterns to block in code */
+  blockedPatterns: RegExp[];
+}
+
+/**
+ * Default security configuration
+ */
+export const DEFAULT_SECURITY_CONFIG: SecurityConfig = {
+  maxCodeLength: 50 * 1024, // 50KB
+  maxExecutionsPerMinute: 60,
+  maxResultSize: 10 * 1024 * 1024, // 10MB
+  blockedPatterns: [
+    /\brequire\s*\(/, // No require()
+    /\bimport\s*\(/, // No dynamic import()
+    /\bprocess\./, // No process access
+    /\bglobal\./, // No global access
+    /\bglobalThis\./, // No globalThis access
+    /\beval\s*\(/, // No eval()
+    /\bFunction\s*\(/, // No Function constructor
+    /\b__proto__\b/, // No prototype pollution
+    /\bconstructor\.constructor/, // No constructor chaining
+    /\bchild_process/, // No child processes
+    /\bfs\./, // No filesystem
+    /\bnet\./, // No networking
+    /\bhttp\./, // No HTTP
+    /\bhttps\./, // No HTTPS
+  ],
+};
+
+/**
+ * Validation result from security checks
+ */
+export interface ValidationResult {
+  /** Whether the code passed validation */
+  valid: boolean;
+  /** Validation errors (if any) */
+  errors: string[];
+}
+
+/**
+ * Execution record for audit logging
+ */
+export interface ExecutionRecord {
+  /** Unique execution ID */
+  id: string;
+  /** Client identifier (for rate limiting) */
+  clientId?: string | undefined;
+  /** Timestamp of execution start */
+  timestamp: Date;
+  /** Code that was executed (truncated for logging) */
+  codePreview: string;
+  /** Execution result */
+  result: SandboxResult;
+  /** Whether code was in readonly mode */
+  readonly: boolean;
+}
+
+// =============================================================================
+// API Types
+// =============================================================================
+
+/**
+ * Tool group API interface - each group exposes its tools as methods
+ */
+export interface GroupApi {
+  /** Tool group name */
+  readonly groupName: ToolGroup;
+}
+
+/**
+ * Options passed to mysql_execute_code tool
+ */
+export interface ExecuteCodeOptions {
+  /** TypeScript code to execute */
+  code: string;
+  /** Timeout in milliseconds (max 30000) */
+  timeout?: number;
+  /** Restrict to read-only operations */
+  readonly?: boolean;
+}
+
+/**
+ * Result returned by mysql_execute_code tool
+ */
+export interface ExecuteCodeResult {
+  /** Whether execution succeeded */
+  success: boolean;
+  /** Return value from the code */
+  result?: unknown;
+  /** Error message (if failed) */
+  error?: string;
+  /** Execution metrics */
+  metrics: ExecutionMetrics;
+}

package/src/codemode/worker-sandbox.ts

@@ -0,0 +1,326 @@
+/**
+ * mysql-mcp - Code Mode Worker Sandbox
+ *
+ * Enhanced sandboxed execution using worker_threads for process-level isolation.
+ * Provides stronger isolation than vm module by running code in a separate thread
+ * with isolated memory space.
+ *
+ * Features:
+ * - Separate V8 instance per worker thread
+ * - Hard timeout enforcement (worker termination)
+ * - Isolated memory space
+ * - Clean process state on each execution
+ */
+
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { logger } from "../utils/logger.js";
+import {
+  DEFAULT_SANDBOX_OPTIONS,
+  DEFAULT_POOL_OPTIONS,
+  type SandboxOptions,
+  type PoolOptions,
+  type SandboxResult,
+  type ExecutionMetrics,
+} from "./types.js";
+
+// Get directory for worker script
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WORKER_SCRIPT_PATH = join(__dirname, "worker-script.js");
+
+/**
+ * A sandboxed execution context using worker_threads
+ * Provides stronger isolation than vm module with separate V8 instance
+ */
+export class WorkerSandbox {
+  private readonly options: Required<SandboxOptions>;
+  private disposed = false;
+
+  private constructor(options: Required<SandboxOptions>) {
+    this.options = options;
+  }
+
+  /**
+   * Create a new worker sandbox instance
+   */
+  static create(options?: SandboxOptions): WorkerSandbox {
+    const opts = { ...DEFAULT_SANDBOX_OPTIONS, ...options };
+    return new WorkerSandbox(opts);
+  }
+
+  /**
+   * Execute code in a worker thread
+   * Each execution spawns a fresh worker for maximum isolation
+   */
+  async execute(
+    code: string,
+    apiBindings: Record<string, unknown>,
+  ): Promise<SandboxResult> {
+    if (this.disposed) {
+      return {
+        success: false,
+        error: "Sandbox has been disposed",
+        metrics: { wallTimeMs: 0, cpuTimeMs: 0, memoryUsedMb: 0 },
+      };
+    }
+
+    const startTime = performance.now();
+    const startMemory = process.memoryUsage().heapUsed;
+
+    return new Promise((resolve) => {
+      let worker: Worker | null = null;
+      let timeoutId: NodeJS.Timeout | null = null;
+      let resolved = false;
+
+      const cleanup = (): void => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+        if (worker) {
+          worker.terminate().catch((): void => {
+            /* intentionally empty */
+          });
+          worker = null;
+        }
+      };
+
+      const respond = (result: SandboxResult): void => {
+        if (resolved) return;
+        resolved = true;
+        cleanup();
+        resolve(result);
+      };
+
+      try {
+        worker = new Worker(WORKER_SCRIPT_PATH, {
+          workerData: {
+            code,
+            apiBindings: this.serializeBindings(apiBindings),
+            timeout: this.options.timeoutMs,
+          },
+        });
+
+        // Set hard timeout (will kill worker)
+        timeoutId = setTimeout(() => {
+          const endTime = performance.now();
+          const endMemory = process.memoryUsage().heapUsed;
+          respond({
+            success: false,
+            error: `Execution timeout: exceeded ${String(this.options.timeoutMs)}ms limit`,
+            metrics: this.calculateMetrics(
+              startTime,
+              endTime,
+              startMemory,
+              endMemory,
+            ),
+          });
+        }, this.options.timeoutMs + 1000); // Extra buffer for cleanup
+
+        worker.on(
+          "message",
+          (result: {
+            success: boolean;
+            result?: unknown;
+            error?: string;
+            stack?: string;
+          }) => {
+            const endTime = performance.now();
+            const endMemory = process.memoryUsage().heapUsed;
+            respond({
+              success: result.success,
+              result: result.result,
+              error: result.error,
+              stack: result.stack,
+              metrics: this.calculateMetrics(
+                startTime,
+                endTime,
+                startMemory,
+                endMemory,
+              ),
+            });
+          },
+        );
+
+        worker.on("error", (error: Error) => {
+          const endTime = performance.now();
+          const endMemory = process.memoryUsage().heapUsed;
+          respond({
+            success: false,
+            error: error.message,
+            stack: error.stack,
+            metrics: this.calculateMetrics(
+              startTime,
+              endTime,
+              startMemory,
+              endMemory,
+            ),
+          });
+        });
+
+        worker.on("exit", (exitCode: number) => {
+          if (!resolved && exitCode !== 0) {
+            const endTime = performance.now();
+            const endMemory = process.memoryUsage().heapUsed;
+            respond({
+              success: false,
+              error: `Worker exited with code ${String(exitCode)}`,
+              metrics: this.calculateMetrics(
+                startTime,
+                endTime,
+                startMemory,
+                endMemory,
+              ),
+            });
+          }
+        });
+      } catch (error) {
+        const endTime = performance.now();
+        const endMemory = process.memoryUsage().heapUsed;
+        respond({
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+          metrics: this.calculateMetrics(
+            startTime,
+            endTime,
+            startMemory,
+            endMemory,
+          ),
+        });
+      }
+    });
+  }
+
+  /**
+   * Serialize API bindings for worker transfer
+   * We can't transfer functions directly, so we send method names
+   */
+  private serializeBindings(
+    bindings: Record<string, unknown>,
+  ): Record<string, string[]> {
+    const serialized: Record<string, string[]> = {};
+    for (const [group, methods] of Object.entries(bindings)) {
+      if (typeof methods === "object" && methods !== null) {
+        serialized[group] = Object.keys(methods);
+      }
+    }
+    return serialized;
+  }
+
+  /**
+   * Calculate execution metrics
+   */
+  private calculateMetrics(
+    startTime: number,
+    endTime: number,
+    startMemory: number,
+    endMemory: number,
+  ): ExecutionMetrics {
+    return {
+      wallTimeMs: Math.round(endTime - startTime),
+      cpuTimeMs: Math.round(endTime - startTime), // Approximation
+      memoryUsedMb: Math.max(
+        0,
+        Math.round(((endMemory - startMemory) / (1024 * 1024)) * 100) / 100,
+      ),
+    };
+  }
+
+  /**
+   * Check if sandbox is healthy
+   */
+  isHealthy(): boolean {
+    return !this.disposed;
+  }
+
+  /**
+   * Dispose of the sandbox
+   */
+  dispose(): void {
+    this.disposed = true;
+  }
+}
+
+/**
+ * Pool of worker sandboxes
+ * Unlike VM pool, worker sandboxes are created fresh for each execution
+ * so this pool is simpler (mainly for statistics and control)
+ */
+export class WorkerSandboxPool {
+  private readonly options: Required<PoolOptions>;
+  private readonly sandboxOptions: Required<SandboxOptions>;
+  private activeCount = 0;
+  private disposed = false;
+
+  constructor(poolOptions?: PoolOptions, sandboxOptions?: SandboxOptions) {
+    this.options = { ...DEFAULT_POOL_OPTIONS, ...poolOptions };
+    this.sandboxOptions = { ...DEFAULT_SANDBOX_OPTIONS, ...sandboxOptions };
+  }
+
+  /**
+   * Initialize the pool
+   */
+  initialize(): void {
+    logger.info(
+      `Worker sandbox pool initialized (max: ${String(this.options.maxInstances)} concurrent)`,
+      {
+        module: "CODEMODE" as const,
+      },
+    );
+  }
+
+  /**
+   * Execute code using a worker sandbox
+   */
+  async execute(
+    code: string,
+    apiBindings: Record<string, unknown>,
+  ): Promise<SandboxResult> {
+    if (this.disposed) {
+      return {
+        success: false,
+        error: "Pool has been disposed",
+        metrics: { wallTimeMs: 0, cpuTimeMs: 0, memoryUsedMb: 0 },
+      };
+    }
+
+    if (this.activeCount >= this.options.maxInstances) {
+      return {
+        success: false,
+        error: `Worker pool exhausted (max: ${String(this.options.maxInstances)} concurrent)`,
+        metrics: { wallTimeMs: 0, cpuTimeMs: 0, memoryUsedMb: 0 },
+      };
+    }
+
+    this.activeCount++;
+    try {
+      const sandbox = WorkerSandbox.create(this.sandboxOptions);
+      return await sandbox.execute(code, apiBindings);
+    } finally {
+      this.activeCount--;
+    }
+  }
+
+  /**
+   * Get pool statistics
+   */
+  getStats(): { available: number; inUse: number; max: number } {
+    return {
+      available: this.options.maxInstances - this.activeCount,
+      inUse: this.activeCount,
+      max: this.options.maxInstances,
+    };
+  }
+
+  /**
+   * Dispose of the pool
+   */
+  dispose(): void {
+    this.disposed = true;
+    logger.info("Worker sandbox pool disposed", {
+      module: "CODEMODE" as const,
+    });
+  }
+}