@unrdf/hooks 5.0.1

package/src/security/sandbox/browser-executor.mjs

@@ -0,0 +1,220 @@
+/**
+ * @file Browser Executor
+ * @module security/sandbox/browser-executor
+ *
+ * @description
+ * Browser-based sandbox executor using Web Workers.
+ * Provides sandboxed execution in browser environments with:
+ * - Separate worker context
+ * - Message-based communication
+ * - WASM support
+ * - Async/await support
+ */
+
+/* global Worker */
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('browser-executor');
+
+/**
+ * Browser Executor (Web Workers)
+ */
+export class BrowserExecutor {
+  /**
+   * @param {Object} [config] - Executor configuration
+   * @param {number} [config.timeout=5000] - Execution timeout in ms
+   * @param {boolean} [config.enableWasm=true] - Enable WASM support
+   * @param {boolean} [config.strictMode=true] - Enable strict mode
+   */
+  constructor(config = {}) {
+    this.config = {
+      timeout: config.timeout || 5000,
+      enableWasm: config.enableWasm !== false,
+      strictMode: config.strictMode !== false,
+      ...config,
+    };
+
+    /** @type {Map<string, Worker>} */
+    this.workers = new Map();
+
+    this.executionCount = 0;
+    this.totalDuration = 0;
+  }
+
+  /**
+   * Execute code in Web Worker
+   * @param {string|Function} code - Code to execute
+   * @param {Object} [context] - Execution context
+   * @param {Object} [options] - Execution options
+   * @returns {Promise<Object>} Execution result
+   */
+  async run(code, context = {}, options = {}) {
+    return tracer.startActiveSpan('security.browser.execute', async span => {
+      const startTime = Date.now();
+      const executionId = `exec_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+      try {
+        span.setAttributes({
+          'security.executor.type': 'browser',
+          'security.execution.id': executionId,
+          'security.timeout': options.timeout || this.config.timeout,
+        });
+
+        // Convert function to string if needed
+        const codeString = typeof code === 'function' ? code.toString() : code;
+
+        // Wrap code in strict mode if enabled
+        const wrappedCode = this.config.strictMode ? `"use strict";\n${codeString}` : codeString;
+
+        // Create worker blob
+        const workerCode = `
+          self.onmessage = function(e) {
+            const { code, context } = e.data;
+
+            try {
+              // Create safe environment
+              const sandbox = {
+                console: {
+                  log: (...args) => self.postMessage({ type: 'log', args }),
+                  error: (...args) => self.postMessage({ type: 'error', args }),
+                  warn: (...args) => self.postMessage({ type: 'warn', args }),
+                  info: (...args) => self.postMessage({ type: 'info', args })
+                },
+                Date: { now: () => Date.now() },
+                Math: Math,
+                JSON: JSON,
+                ...context
+              };
+
+              // Execute code
+              const func = new Function(...Object.keys(sandbox), code);
+              const result = func(...Object.values(sandbox));
+
+              self.postMessage({ type: 'result', success: true, result });
+            } catch (error) {
+              self.postMessage({
+                type: 'result',
+                success: false,
+                error: error.message,
+                stack: error.stack
+              });
+            }
+          };
+        `;
+
+        const blob = new Blob([workerCode], { type: 'application/javascript' });
+        const workerUrl = URL.createObjectURL(blob);
+
+        // Create worker promise
+        const result = await new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            worker.terminate();
+            this.workers.delete(executionId);
+            URL.revokeObjectURL(workerUrl);
+            reject(new Error(`Browser worker execution timeout after ${this.config.timeout}ms`));
+          }, options.timeout || this.config.timeout);
+
+          const worker = new Worker(workerUrl);
+          this.workers.set(executionId, worker);
+
+          worker.onmessage = e => {
+            const { type, success, result, error, args } = e.data;
+
+            if (type === 'log' || type === 'error' || type === 'warn' || type === 'info') {
+              console[type]('[Worker]', ...args);
+              return;
+            }
+
+            if (type === 'result') {
+              clearTimeout(timeout);
+              worker.terminate();
+              this.workers.delete(executionId);
+              URL.revokeObjectURL(workerUrl);
+
+              if (success) {
+                resolve({ success: true, result });
+              } else {
+                reject(new Error(error || 'Worker execution failed'));
+              }
+            }
+          };
+
+          worker.onerror = error => {
+            clearTimeout(timeout);
+            worker.terminate();
+            this.workers.delete(executionId);
+            URL.revokeObjectURL(workerUrl);
+            reject(error);
+          };
+
+          // Send code to worker
+          worker.postMessage({ code: wrappedCode, context });
+        });
+
+        const duration = Date.now() - startTime;
+        this.executionCount++;
+        this.totalDuration += duration;
+
+        span.setAttributes({
+          'security.execution.duration': duration,
+          'security.execution.success': true,
+        });
+        span.setStatus({ code: 1 }); // OK
+
+        return {
+          success: true,
+          result: result.result,
+          duration,
+          executionId,
+        };
+      } catch (error) {
+        const duration = Date.now() - startTime;
+
+        span.recordException(error);
+        span.setAttributes({
+          'security.execution.duration': duration,
+          'security.execution.success': false,
+          'security.error.message': error.message,
+        });
+        span.setStatus({ code: 2, message: error.message });
+
+        return {
+          success: false,
+          error: error.message,
+          duration,
+          executionId,
+        };
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Get executor statistics
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      type: 'browser',
+      config: this.config,
+      executionCount: this.executionCount,
+      averageDuration: this.executionCount > 0 ? this.totalDuration / this.executionCount : 0,
+      activeWorkers: this.workers.size,
+    };
+  }
+
+  /**
+   * Cleanup all workers
+   */
+  async cleanup() {
+    for (const [executionId, worker] of this.workers.entries()) {
+      try {
+        worker.terminate();
+      } catch (err) {
+        // Ignore termination errors
+      }
+      this.workers.delete(executionId);
+    }
+  }
+}

package/src/security/sandbox/detector.mjs

@@ -0,0 +1,342 @@
+/**
+ * @file Sandbox Executor Detector
+ * @module security/sandbox/detector
+ *
+ * @description
+ * Automatically detects the best sandbox executor based on:
+ * - Node.js version and environment
+ * - Available dependencies
+ * - Platform capabilities (V8 isolates, Worker threads, etc.)
+ * - Security requirements
+ */
+
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('sandbox-detector');
+
+/**
+ * Detect runtime environment
+ * @returns {Object} Environment info
+ */
+export function detectEnvironment() {
+  return tracer.startActiveSpan('detector.detectEnvironment', span => {
+    try {
+      const env = {
+        isNode: typeof process !== 'undefined' && process.versions?.node,
+        isBrowser: typeof window !== 'undefined',
+        isWorker: typeof WorkerGlobalScope !== 'undefined',
+        nodeVersion: process.versions?.node || null,
+        v8Version: process.versions?.v8 || null,
+        platform: process.platform || 'unknown',
+        arch: process.arch || 'unknown',
+      };
+
+      span.setAttributes({
+        'detector.isNode': env.isNode,
+        'detector.isBrowser': env.isBrowser,
+        'detector.nodeVersion': env.nodeVersion || 'unknown',
+        'detector.platform': env.platform,
+      });
+
+      span.setStatus({ code: 1 }); // OK
+      return env;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Check if isolated-vm is available and working
+ * @returns {Promise<boolean>} True if isolated-vm is available
+ */
+export async function checkIsolatedVm() {
+  return tracer.startActiveSpan('detector.checkIsolatedVm', async span => {
+    try {
+      // Try to import isolated-vm
+      const ivm = await import('isolated-vm').catch(() => null);
+      const available = !!ivm;
+
+      span.setAttribute('detector.isolatedVm.available', available);
+
+      if (available) {
+        // Quick smoke test
+        try {
+          const isolate = new ivm.default.Isolate({ memoryLimit: 8 });
+          await isolate.dispose();
+          span.setAttribute('detector.isolatedVm.working', true);
+          span.setStatus({ code: 1 });
+          return true;
+        } catch (testError) {
+          span.recordException(testError);
+          span.setAttribute('detector.isolatedVm.working', false);
+          span.setStatus({ code: 1 }); // Not an error, just not working
+          return false;
+        }
+      }
+
+      span.setStatus({ code: 1 });
+      return false;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      return false;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Check if Worker threads are available
+ * @returns {Promise<boolean>} True if Worker threads are available
+ */
+export async function checkWorkerThreads() {
+  return tracer.startActiveSpan('detector.checkWorkerThreads', async span => {
+    try {
+      const { Worker } = await import('worker_threads').catch(() => ({}));
+      const available = !!Worker;
+
+      span.setAttribute('detector.workerThreads.available', available);
+      span.setStatus({ code: 1 });
+
+      return available;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      return false;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Check if vm2 is available (legacy)
+ * @returns {Promise<boolean>} True if vm2 is available
+ */
+export async function checkVm2() {
+  return tracer.startActiveSpan('detector.checkVm2', async span => {
+    try {
+      const vm2Module = await import('vm2').catch(() => null);
+      const available = !!vm2Module?.VM;
+
+      span.setAttribute('detector.vm2.available', available);
+      span.setAttribute('detector.vm2.deprecated', true);
+      span.setStatus({ code: 1 });
+
+      return available;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      return false;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Detect best available sandbox executor
+ * Priority: isolated-vm > worker > vm2 (deprecated) > browser
+ *
+ * @param {Object} [options] - Detection options
+ * @param {boolean} [options.preferIsolatedVm=true] - Prefer isolated-vm if available
+ * @param {boolean} [options.allowVm2=false] - Allow deprecated vm2 (not recommended)
+ * @param {boolean} [options.allowBrowser=true] - Allow browser executor
+ * @returns {Promise<string>} Executor type ('isolated-vm' | 'worker' | 'vm2' | 'browser')
+ */
+export async function detectBestExecutor(options = {}) {
+  return tracer.startActiveSpan('detector.detectBestExecutor', async span => {
+    try {
+      const { preferIsolatedVm = true, allowVm2 = false, allowBrowser = true } = options;
+
+      const env = detectEnvironment();
+      span.setAttributes({
+        'detector.preferIsolatedVm': preferIsolatedVm,
+        'detector.allowVm2': allowVm2,
+        'detector.allowBrowser': allowBrowser,
+      });
+
+      // Browser environment
+      if (env.isBrowser && allowBrowser) {
+        span.setAttribute('detector.executor', 'browser');
+        span.setStatus({ code: 1 });
+        return 'browser';
+      }
+
+      // Node.js environment - check capabilities in priority order
+      if (env.isNode) {
+        // 1. Try isolated-vm (best security and performance)
+        if (preferIsolatedVm && (await checkIsolatedVm())) {
+          span.setAttribute('detector.executor', 'isolated-vm');
+          span.setStatus({ code: 1 });
+          return 'isolated-vm';
+        }
+
+        // 2. Try Worker threads (good isolation, available in Node 12+)
+        if (await checkWorkerThreads()) {
+          span.setAttribute('detector.executor', 'worker');
+          span.setStatus({ code: 1 });
+          return 'worker';
+        }
+
+        // 3. Fall back to vm2 if explicitly allowed (deprecated, security issues)
+        if (allowVm2 && (await checkVm2())) {
+          span.setAttribute('detector.executor', 'vm2');
+          span.setAttribute('detector.warning', 'Using deprecated vm2 - security issues present');
+          span.setStatus({ code: 1 });
+          console.warn(
+            '[SECURITY WARNING] Using deprecated vm2 sandbox executor. ' +
+              'This has known security vulnerabilities. ' +
+              'Consider upgrading Node.js or installing isolated-vm.'
+          );
+          return 'vm2';
+        }
+      }
+
+      // No suitable executor found
+      const error = new Error(
+        'No suitable sandbox executor available. ' +
+          'Install isolated-vm or upgrade to Node.js 12+ for Worker threads.'
+      );
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      throw error;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Create executor instance based on type
+ * @param {string} executorType - Type of executor to create
+ * @param {Object} [config] - Executor configuration
+ * @returns {Promise<Object>} Executor instance
+ */
+export async function createExecutor(executorType, config = {}) {
+  return tracer.startActiveSpan('detector.createExecutor', async span => {
+    try {
+      span.setAttribute('detector.executorType', executorType);
+
+      let ExecutorClass;
+
+      switch (executorType) {
+        case 'isolated-vm':
+          ExecutorClass = (await import('./isolated-vm-executor.mjs')).IsolatedVmExecutor;
+          break;
+
+        case 'worker':
+          ExecutorClass = (await import('./worker-executor.mjs')).WorkerExecutor;
+          break;
+
+        case 'vm2':
+          console.warn('[DEPRECATION] vm2 executor is deprecated and has security vulnerabilities');
+          ExecutorClass = (await import('./vm2-executor.mjs')).Vm2Executor;
+          break;
+
+        case 'browser':
+          ExecutorClass = (await import('./browser-executor.mjs')).BrowserExecutor;
+          break;
+
+        default:
+          throw new Error(`Unknown executor type: ${executorType}`);
+      }
+
+      const executor = new ExecutorClass(config);
+      span.setStatus({ code: 1 });
+      return executor;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Auto-detect and create best executor
+ * @param {Object} [config] - Executor configuration
+ * @param {Object} [detectionOptions] - Detection options
+ * @returns {Promise<Object>} Executor instance
+ */
+export async function createBestExecutor(config = {}, detectionOptions = {}) {
+  return tracer.startActiveSpan('detector.createBestExecutor', async span => {
+    try {
+      const executorType = await detectBestExecutor(detectionOptions);
+      span.setAttribute('detector.selectedExecutor', executorType);
+
+      const executor = await createExecutor(executorType, config);
+      span.setStatus({ code: 1 });
+
+      return executor;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Get executor capabilities
+ * @param {string} executorType - Executor type
+ * @returns {Object} Capabilities object
+ */
+export function getExecutorCapabilities(executorType) {
+  const capabilities = {
+    'isolated-vm': {
+      memoryIsolation: 'full',
+      cpuIsolation: 'full',
+      asyncSupport: true,
+      wasmSupport: true,
+      securityLevel: 'high',
+      performance: 'high',
+      overhead: 'low',
+    },
+    worker: {
+      memoryIsolation: 'partial',
+      cpuIsolation: 'partial',
+      asyncSupport: true,
+      wasmSupport: false,
+      securityLevel: 'medium',
+      performance: 'medium',
+      overhead: 'medium',
+    },
+    vm2: {
+      memoryIsolation: 'weak',
+      cpuIsolation: 'none',
+      asyncSupport: false,
+      wasmSupport: false,
+      securityLevel: 'low',
+      performance: 'medium',
+      overhead: 'low',
+      deprecated: true,
+      securityIssues: true,
+    },
+    browser: {
+      memoryIsolation: 'partial',
+      cpuIsolation: 'partial',
+      asyncSupport: true,
+      wasmSupport: true,
+      securityLevel: 'medium',
+      performance: 'low',
+      overhead: 'high',
+    },
+  };
+
+  return capabilities[executorType] || null;
+}