@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/content-scanner.cjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * Content Security Scanner
+ *
+ * Scans fetched content for XSS vectors, malicious scripts, and dangerous patterns.
+ * Detects script tags, JavaScript URLs, event handlers, and other security threats.
+ */
+
+const { SecurityScanError } = require('./context-errors.cjs');
+
+class ContentSecurityScanner {
+  constructor() {
+    this.maxSize = 1048576; // 1MB
+
+    // XSS detection patterns with severity levels
+    this.patterns = [
+      {
+        name: 'script_tag_open',
+        regex: /<script\b[^>]*>/gi,
+        severity: 'high',
+        description: 'Opening script tag'
+      },
+      {
+        name: 'script_tag_close',
+        regex: /<\/script>/gi,
+        severity: 'high',
+        description: 'Closing script tag'
+      },
+      {
+        name: 'javascript_url',
+        regex: /javascript\s*:/gi,
+        severity: 'high',
+        description: 'JavaScript URL protocol'
+      },
+      {
+        name: 'vbscript_url',
+        regex: /vbscript\s*:/gi,
+        severity: 'high',
+        description: 'VBScript URL protocol'
+      },
+      {
+        name: 'data_html_url',
+        regex: /data\s*:\s*text\/html/gi,
+        severity: 'high',
+        description: 'Data URL with HTML content'
+      },
+      {
+        name: 'event_handler',
+        regex: /\bon\w+\s*=/gi,
+        severity: 'medium',
+        description: 'Event handler attribute'
+      },
+      {
+        name: 'iframe_tag',
+        regex: /<iframe\b[^>]*>/gi,
+        severity: 'medium',
+        description: 'IFRAME tag'
+      },
+      {
+        name: 'embed_tag',
+        regex: /<embed\b[^>]*>/gi,
+        severity: 'medium',
+        description: 'EMBED tag'
+      },
+      {
+        name: 'object_tag',
+        regex: /<object\b[^>]*>/gi,
+        severity: 'medium',
+        description: 'OBJECT tag'
+      },
+      {
+        name: 'svg_tag',
+        regex: /<svg\b[^>]*>/gi,
+        severity: 'medium',
+        description: 'SVG tag (potential XSS vector)'
+      },
+      {
+        name: 'img_onerror',
+        regex: /<img[^>]*\s+onerror\s*=/gi,
+        severity: 'high',
+        description: 'IMG tag with onerror handler'
+      },
+      {
+        name: 'expression_css',
+        regex: /expression\s*\(/gi,
+        severity: 'medium',
+        description: 'CSS expression (IE XSS vector)'
+      },
+      {
+        name: 'eval_call',
+        regex: /\beval\s*\(/gi,
+        severity: 'high',
+        description: 'eval() call'
+      },
+      {
+        name: 'document_cookie',
+        regex: /document\.cookie/gi,
+        severity: 'medium',
+        description: 'Document cookie access'
+      },
+      {
+        name: 'window_location',
+        regex: /window\.location/gi,
+        severity: 'low',
+        description: 'Window location access'
+      }
+    ];
+
+    // Binary content types to reject
+    this.binaryContentTypes = [
+      'application/octet-stream',
+      'image/',
+      'video/',
+      'audio/',
+      'application/pdf',
+      'application/zip',
+      'application/x-rar',
+      'application/x-executable'
+    ];
+  }
+
+  /**
+   * Scan content for security issues
+   * @param {string} content - The content to scan
+   * @param {string} contentType - Optional content type header
+   * @returns {{safe: boolean, findings: Array}} - Scan results
+   */
+  scan(content, contentType = '') {
+    const findings = [];
+
+    // Check content size
+    if (content && content.length > this.maxSize) {
+      return {
+        safe: false,
+        findings: [{
+          type: 'size_limit',
+          severity: 'high',
+          description: `Content exceeds maximum size (${content.length} > ${this.maxSize} bytes)`,
+          pattern: null,
+          matches: []
+        }]
+      };
+    }
+
+    // Check for binary content types
+    if (contentType) {
+      const lowerContentType = contentType.toLowerCase();
+      for (const binaryType of this.binaryContentTypes) {
+        if (lowerContentType.includes(binaryType.toLowerCase())) {
+          return {
+            safe: false,
+            findings: [{
+              type: 'binary_content',
+              severity: 'high',
+              description: `Binary content type detected: ${contentType}`,
+              pattern: null,
+              matches: []
+            }]
+          };
+        }
+      }
+    }
+
+    // Scan for XSS patterns
+    if (content) {
+      for (const pattern of this.patterns) {
+        // Reset regex lastIndex
+        pattern.regex.lastIndex = 0;
+
+        const matches = [];
+        let match;
+
+        while ((match = pattern.regex.exec(content)) !== null) {
+          matches.push(match[0]);
+          // Limit matches to prevent memory issues
+          if (matches.length >= 5) {
+            break;
+          }
+        }
+
+        if (matches.length > 0) {
+          findings.push({
+            type: pattern.name,
+            severity: pattern.severity,
+            description: pattern.description,
+            pattern: pattern.regex.toString(),
+            matches: [...new Set(matches)] // Deduplicate
+          });
+        }
+      }
+    }
+
+    return {
+      safe: findings.length === 0,
+      findings
+    };
+  }
+
+  /**
+   * Get severity level for a pattern
+   * @param {string} patternName - The pattern name
+   * @returns {string} - 'high', 'medium', or 'low'
+   */
+  getSeverity(patternName) {
+    const pattern = this.patterns.find(p => p.name === patternName);
+    if (!pattern) {
+      return 'low';
+    }
+    return pattern.severity;
+  }
+
+  /**
+   * Check if content is safe (convenience method)
+   * @param {string} content - The content to check
+   * @param {string} contentType - Optional content type
+   * @returns {boolean} - True if safe
+   */
+  isSafe(content, contentType = '') {
+    return this.scan(content, contentType).safe;
+  }
+
+  /**
+   * Validate content and throw error if unsafe
+   * @param {string} content - The content to validate
+   * @param {string} contentType - Optional content type
+   * @throws {SecurityScanError} - If content is unsafe
+   */
+  validate(content, contentType = '') {
+    const result = this.scan(content, contentType);
+    if (!result.safe) {
+      throw new SecurityScanError(result.findings);
+    }
+    return result;
+  }
+}
+
+module.exports = ContentSecurityScanner;

package/bin/lib/context-cache.cjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * Context Cache (Session-Only)
+ *
+ * Provides temporary, session-only caching for fetched content.
+ * Cache is stored in system temp directory and auto-cleared on process exit.
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+class ContextCache {
+  constructor() {
+    // Cache stored in system temp directory with PID for isolation
+    this.cacheDir = path.join(os.tmpdir(), `ez-agents-context-${process.pid}`);
+    this.cache = new Map();
+    
+    // Register process exit handlers
+    this._registerExitHandlers();
+  }
+
+  /**
+   * Register process exit handlers to clean up cache
+   * @private
+   */
+  _registerExitHandlers() {
+    // Clean up on normal exit
+    process.on('exit', () => {
+      this.clear();
+    });
+
+    // Clean up on SIGINT (Ctrl+C)
+    process.on('SIGINT', () => {
+      this.clear();
+      process.exit(130);
+    });
+
+    // Clean up on SIGTERM
+    process.on('SIGTERM', () => {
+      this.clear();
+      process.exit(143);
+    });
+
+    // Clean up on uncaught exceptions
+    process.on('uncaughtException', () => {
+      this.clear();
+    });
+  }
+
+  /**
+   * Get cached content by key
+   * @param {string} key - The cache key (usually URL or file path)
+   * @returns {{content: string, timestamp: number, type: string, contentType?: string}|undefined}
+   */
+  get(key) {
+    return this.cache.get(key);
+  }
+
+  /**
+   * Store content in cache
+   * @param {string} key - The cache key
+   * @param {string} content - The content to cache
+   * @param {Object} metadata - Additional metadata (type, contentType, etc.)
+   */
+  set(key, content, metadata = {}) {
+    this.cache.set(key, {
+      content,
+      ...metadata,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Check if key exists in cache
+   * @param {string} key - The cache key
+   * @returns {boolean} - True if key exists
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+
+  /**
+   * Remove item from cache
+   * @param {string} key - The cache key
+   * @returns {boolean} - True if item was removed
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Get the size of the cache
+   * @returns {number} - Number of items in cache
+   */
+  size() {
+    return this.cache.size;
+  }
+
+  /**
+   * Clear all cached content and remove temp directory
+   */
+  clear() {
+    // Clear the in-memory cache
+    this.cache.clear();
+
+    // Remove temp directory if it exists
+    if (fs.existsSync(this.cacheDir)) {
+      try {
+        fs.rmSync(this.cacheDir, { recursive: true, force: true });
+      } catch (err) {
+        // Ignore errors during cleanup (directory may already be gone)
+      }
+    }
+  }
+
+  /**
+   * Get cache directory path
+   * @returns {string} - Path to cache directory
+   */
+  getCacheDir() {
+    return this.cacheDir;
+  }
+
+  /**
+   * Get all cache keys
+   * @returns {Array<string>} - Array of cache keys
+   */
+  keys() {
+    return Array.from(this.cache.keys());
+  }
+
+  /**
+   * Get all cached entries
+   * @returns {Array<{key: string, value: Object}>} - Array of key-value pairs
+   */
+  entries() {
+    return Array.from(this.cache.entries()).map(([key, value]) => ({ key, value }));
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {{size: number, keys: Array<string>}} - Cache statistics
+   */
+  stats() {
+    return {
+      size: this.cache.size,
+      keys: this.keys()
+    };
+  }
+}
+
+module.exports = ContextCache;

package/bin/lib/context-compressor.cjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * Context Compressor — Compress context to reduce token usage
+ *
+ * Strategies:
+ * - Remove redundant information
+ * - Summarize verbose sections
+ * - Compress repeated patterns
+ */
+
+class ContextCompressor {
+  /**
+   * Create a ContextCompressor instance
+   */
+  constructor() {
+    this.compressionThreshold = 0.8; // Compress if over 80% of limit
+    this.defaultLimit = 100000; // Default token limit
+  }
+
+  /**
+   * Compress context content
+   * @param {string} content - Content to compress
+   * @param {Object} options - Compression options
+   * @returns {string} Compressed content
+   */
+  compress(content, options = {}) {
+    if (!content) return '';
+
+    let result = content;
+    const limit = options.limit || this.defaultLimit;
+
+    // Remove excessive whitespace
+    result = this._removeExtraWhitespace(result);
+
+    // Check if compression is needed
+    if (result.length < limit * this.compressionThreshold) {
+      return result;
+    }
+
+    // Apply aggressive compression
+    result = this._summarizeSections(result, options);
+
+    return result;
+  }
+
+  /**
+   * Remove extra whitespace from content
+   * @param {string} content - Content to process
+   * @returns {string} Processed content
+   */
+  _removeExtraWhitespace(content) {
+    return content
+      .replace(/\n{3,}/g, '\n\n') // Max 2 consecutive newlines
+      .replace(/[ \t]+$/gm, '') // Remove trailing whitespace
+      .replace(/^\s*\n/gm, ''); // Remove leading blank lines
+  }
+
+  /**
+   * Summarize long sections
+   * @param {string} content - Content to summarize
+   * @param {Object} options - Options
+   * @returns {string} Summarized content
+   */
+  _summarizeSections(content, options = {}) {
+    const maxLength = options.maxLength || 50000;
+
+    if (content.length <= maxLength) {
+      return content;
+    }
+
+    // Keep first and last parts, summarize middle
+    const keepLength = Math.floor(maxLength / 3);
+    const start = content.slice(0, keepLength);
+    const end = content.slice(-keepLength);
+    const omitted = content.length - (keepLength * 2);
+
+    return `${start}\n\n[... ${omitted} characters omitted ...]\n\n${end}`;
+  }
+
+  /**
+   * Get compression statistics
+   * @param {string} original - Original content
+   * @param {string} compressed - Compressed content
+   * @returns {Object} Compression statistics
+   */
+  getStats(original, compressed) {
+    const originalLength = original?.length || 0;
+    const compressedLength = compressed?.length || 0;
+    const saved = originalLength - compressedLength;
+    const ratio = originalLength > 0 ? (saved / originalLength) * 100 : 0;
+
+    return {
+      original: originalLength,
+      compressed: compressedLength,
+      saved,
+      ratio: Math.round(ratio * 100) / 100
+    };
+  }
+}
+
+module.exports = ContextCompressor;

package/bin/lib/context-deduplicator.cjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * Context Deduplicator — Remove duplicate context items
+ *
+ * Identifies and removes:
+ * - Exact duplicates
+ * - Near-duplicates (similar content)
+ * - Redundant information
+ */
+
+class ContextDeduplicator {
+  /**
+   * Create a ContextDeduplicator instance
+   */
+  constructor() {
+    this.seen = new Set();
+    this.similarityThreshold = 0.9; // 90% similar = duplicate
+  }
+
+  /**
+   * Generate a hash for content
+   * @param {string} content - Content to hash
+   * @returns {string} Hash value
+   */
+  _hash(content) {
+    // Simple hash for deduplication
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+      const char = content.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash; // Convert to 32-bit integer
+    }
+    return hash.toString(36);
+  }
+
+  /**
+   * Check if content is a duplicate
+   * @param {string} content - Content to check
+   * @returns {boolean} True if duplicate
+   */
+  isDuplicate(content) {
+    const hash = this._hash(content);
+    return this.seen.has(hash);
+  }
+
+  /**
+   * Mark content as seen
+   * @param {string} content - Content to mark
+   */
+  markSeen(content) {
+    const hash = this._hash(content);
+    this.seen.add(hash);
+  }
+
+  /**
+   * Deduplicate an array of items
+   * @param {Array} items - Items to deduplicate
+   * @param {string} keyField - Field to use for deduplication
+   * @returns {Array} Deduplicated items
+   */
+  deduplicate(items, keyField = 'content') {
+    const seen = new Set();
+    const result = [];
+
+    for (const item of items) {
+      const key = item[keyField] || JSON.stringify(item);
+      const hash = this._hash(key);
+
+      if (!seen.has(hash)) {
+        seen.add(hash);
+        result.push(item);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear the seen set
+   */
+  clear() {
+    this.seen.clear();
+  }
+
+  /**
+   * Get deduplication statistics
+   * @param {Array} original - Original items
+   * @param {Array} deduplicated - Deduplicated items
+   * @returns {Object} Statistics
+   */
+  getStats(original, deduplicated) {
+    const removed = original.length - deduplicated.length;
+    const ratio = original.length > 0 ? (removed / original.length) * 100 : 0;
+
+    return {
+      original: original.length,
+      deduplicated: deduplicated.length,
+      removed,
+      ratio: Math.round(ratio * 100) / 100
+    };
+  }
+}
+
+module.exports = ContextDeduplicator;

package/bin/lib/context-errors.cjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * Context Access Error Classes
+ *
+ * Provides structured error handling for context access operations
+ * including file access, URL fetching, and security scanning.
+ */
+
+const { SEVERITY, getErrorCode } = require('./error-registry.cjs');
+
+class ContextAccessError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'ContextAccessError';
+    this.code = options.code || getErrorCode('CONTEXT', 'ACCESS_DENIED')?.code || 'CONTEXT_ACCESS_ERROR';
+    this.severity = options.severity || getErrorCode('CONTEXT', 'ACCESS_DENIED')?.severity || SEVERITY.ERROR;
+    this.details = options.details || {};
+    this.timestamp = new Date().toISOString();
+    Error.captureStackTrace(this, ContextAccessError);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      severity: this.severity,
+      message: this.message,
+      details: this.details,
+      timestamp: this.timestamp
+    };
+  }
+}
+
+class URLFetchError extends ContextAccessError {
+  constructor(url, reason, options = {}) {
+    super(`Failed to fetch URL: ${reason}`, {
+      code: getErrorCode('CONTEXT', 'URL_FETCH_FAILED')?.code || 'URL_FETCH_ERROR',
+      severity: SEVERITY.ERROR,
+      details: { url, reason, ...options.details }
+    });
+    this.name = 'URLFetchError';
+    this.url = url;
+    this.reason = reason;
+  }
+}
+
+class FileAccessError extends ContextAccessError {
+  constructor(path, reason, options = {}) {
+    super(`Failed to access file: ${reason}`, {
+      code: getErrorCode('CONTEXT', 'FILE_ACCESS_FAILED')?.code || 'FILE_ACCESS_ERROR',
+      severity: SEVERITY.ERROR,
+      details: { path, reason, ...options.details }
+    });
+    this.name = 'FileAccessError';
+    this.path = path;
+    this.reason = reason;
+  }
+}
+
+class SecurityScanError extends ContextAccessError {
+  constructor(findings, options = {}) {
+    super(`Security scan failed: ${findings.length} issue(s) detected`, {
+      code: getErrorCode('CONTEXT', 'SECURITY_SCAN_FAILED')?.code || 'SECURITY_SCAN_ERROR',
+      severity: SEVERITY.CRITICAL,
+      details: { findings, ...options.details }
+    });
+    this.name = 'SecurityScanError';
+    this.findings = findings;
+  }
+}
+
+module.exports = {
+  ContextAccessError,
+  URLFetchError,
+  FileAccessError,
+  SecurityScanError
+};