@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/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/ez-agents/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/ez-agents/bin/lib/context-errors.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Context Access Error Classes
+ *
+ * Provides structured error handling for context access operations
+ * including file access, URL fetching, and security scanning.
+ */
+
+class ContextAccessError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'ContextAccessError';
+    this.code = options.code || 'CONTEXT_ACCESS_ERROR';
+    this.details = options.details || {};
+    this.timestamp = new Date().toISOString();
+    Error.captureStackTrace(this, ContextAccessError);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      timestamp: this.timestamp
+    };
+  }
+}
+
+class URLFetchError extends ContextAccessError {
+  constructor(url, reason, options = {}) {
+    super(`Failed to fetch URL: ${reason}`, {
+      code: 'URL_FETCH_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: 'FILE_ACCESS_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: 'SECURITY_SCAN_ERROR',
+      details: { findings, ...options.details }
+    });
+    this.name = 'SecurityScanError';
+    this.findings = findings;
+  }
+}
+
+module.exports = {
+  ContextAccessError,
+  URLFetchError,
+  FileAccessError,
+  SecurityScanError
+};

package/ez-agents/bin/lib/context-manager.cjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+/**
+ * Context Manager
+ *
+ * Orchestrates context gathering from files and URLs.
+ * Aggregates content, tracks sources, and updates STATE.md with context metadata.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const FileAccessService = require('./file-access.cjs');
+const URLFetchService = require('./url-fetch.cjs');
+const ContentSecurityScanner = require('./content-scanner.cjs');
+const ContextCache = require('./context-cache.cjs');
+const { SecurityScanError, FileAccessError, URLFetchError } = require('./context-errors.cjs');
+
+class ContextManager {
+  /**
+   * Create a new ContextManager instance
+   * @param {string} cwd - Current working directory
+   */
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.sources = [];
+    this.cache = new ContextCache();
+    this.fileAccess = new FileAccessService(this.cwd);
+    this.urlFetch = new URLFetchService();
+    this.scanner = new ContentSecurityScanner();
+  }
+
+  /**
+   * Request context from files and URLs
+   * @param {{files?: string[], urls?: string[]}} options - Context options
+   * @returns {{context: string, sources: Array, errors: Array}} - Aggregated context
+   */
+  async requestContext(options = {}) {
+    const { files = [], urls = [] } = options;
+    const contextParts = [];
+    const sources = [];
+    const errors = [];
+
+    // Process file patterns
+    for (const pattern of files) {
+      try {
+        const fileResults = this.fileAccess.readFiles(pattern);
+        for (const file of fileResults) {
+          contextParts.push(`## File: ${file.path}\n\n${file.content}`);
+          const source = {
+            type: 'file',
+            source: file.path,
+            timestamp: new Date().toISOString(),
+            size: file.content.length
+          };
+          sources.push(source);
+          this.trackSources([source]);
+        }
+      } catch (err) {
+        errors.push({
+          source: pattern,
+          type: 'file',
+          message: err.message
+        });
+      }
+    }
+
+    // Process URLs
+    for (const url of urls) {
+      try {
+        // Confirm URL fetch with user
+        const confirmed = await URLFetchService.confirmUrlFetch(url);
+        if (!confirmed) {
+          errors.push({
+            source: url,
+            type: 'url',
+            message: 'User declined to fetch URL'
+          });
+          continue;
+        }
+
+        // Fetch the URL
+        const result = await this.urlFetch.fetchUrl(url);
+        
+        // Scan for security issues
+        const scanResult = this.scanner.scan(result.content, result.contentType);
+        if (!scanResult.safe) {
+          throw new SecurityScanError(scanResult.findings);
+        }
+
+        // Add to context
+        contextParts.push(`## URL: ${url}\n\n${result.content}`);
+        
+        const source = {
+          type: 'url',
+          source: url,
+          timestamp: new Date().toISOString(),
+          contentType: result.contentType,
+          size: result.content.length
+        };
+        sources.push(source);
+        this.trackSources([source]);
+
+        // Cache the content
+        this.cache.set(url, result.content, {
+          type: 'url',
+          contentType: result.contentType
+        });
+      } catch (err) {
+        errors.push({
+          source: url,
+          type: 'url',
+          message: err.message
+        });
+      }
+    }
+
+    return {
+      context: contextParts.join('\n\n---\n\n'),
+      sources,
+      errors
+    };
+  }
+
+  /**
+   * Track source metadata (with deduplication)
+   * @param {Array} sources - Array of source objects
+   */
+  trackSources(sources) {
+    for (const source of sources) {
+      // Check for duplicates (same type and source)
+      const isDuplicate = this.sources.some(
+        s => s.type === source.type && s.source === source.source
+      );
+      
+      if (!isDuplicate) {
+        this.sources.push(source);
+      }
+    }
+  }
+
+  /**
+   * Update STATE.md with context sources
+   * Creates or appends to the Context Sources section
+   */
+  updateStateMd() {
+    const statePath = path.join(this.cwd, '.planning', 'STATE.md');
+    
+    // Ensure .planning directory exists
+    const planningDir = path.join(this.cwd, '.planning');
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    let content = '';
+    
+    // Read existing content or start fresh
+    if (fs.existsSync(statePath)) {
+      content = fs.readFileSync(statePath, 'utf-8');
+    } else {
+      content = '# Project State\n\n';
+    }
+
+    // Build the context sources table
+    const tableHeader = '| Source | Type | Timestamp |\n|--------|------|-----------|';
+    const tableRows = this.sources.map(s => 
+      `| ${s.source} | ${s.type.toUpperCase()} | ${s.timestamp} |`
+    );
+    
+    const contextSection = `\n## Context Sources\n\n${tableHeader}\n${tableRows.join('\n')}\n`;
+
+    // Check if Context Sources section already exists
+    const sectionRegex = /## Context Sources\n[\s\S]*?(?=\n## |\n$|$)/i;
+    const existingSection = content.match(sectionRegex);
+
+    if (existingSection) {
+      // Replace existing section
+      content = content.replace(sectionRegex, contextSection);
+    } else {
+      // Append new section
+      content = content.trimEnd() + '\n' + contextSection;
+    }
+
+    // Write back to STATE.md
+    fs.writeFileSync(statePath, content, 'utf-8');
+  }
+
+  /**
+   * Get all tracked sources
+   * @returns {Array} - Array of source objects
+   */
+  getSources() {
+    return [...this.sources];
+  }
+
+  /**
+   * Get cached content for a URL
+   * @param {string} key - Cache key (URL)
+   * @returns {{content: string, timestamp: number, type: string}|undefined}
+   */
+  getCached(key) {
+    return this.cache.get(key);
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {{size: number, keys: Array<string>}}
+   */
+  getCacheStats() {
+    return this.cache.stats();
+  }
+}
+
+module.exports = ContextManager;