agileflow 2.87.0 → 2.89.0

package/lib/validate.js

@@ -2,9 +2,12 @@
  * AgileFlow CLI - Input Validation Utilities
  *
  * Centralized validation patterns and helpers to prevent
- * command injection and invalid input handling.
+ * command injection, path traversal, and invalid input handling.
  */
 
+const path = require('node:path');
+const fs = require('node:fs');
+
 /**
  * Validation patterns for common input types.
  * All patterns use strict whitelisting approach.
@@ -320,7 +323,277 @@ function validateArgs(args, schema) {
   return { ok: true, data: result };
 }
 
+// =============================================================================
+// Path Traversal Protection
+// =============================================================================
+
+/**
+ * Path validation error with context.
+ */
+class PathValidationError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} inputPath - The problematic path
+   * @param {string} reason - Reason for rejection
+   */
+  constructor(message, inputPath, reason) {
+    super(message);
+    this.name = 'PathValidationError';
+    this.inputPath = inputPath;
+    this.reason = reason;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Validate that a path is safe and within the allowed base directory.
+ * Prevents path traversal attacks by:
+ * 1. Resolving the path to absolute form
+ * 2. Ensuring it stays within the base directory
+ * 3. Rejecting symbolic links (optional)
+ *
+ * @param {string} inputPath - The path to validate (can be relative or absolute)
+ * @param {string} baseDir - The allowed base directory (must be absolute)
+ * @param {Object} options - Validation options
+ * @param {boolean} [options.allowSymlinks=false] - Allow symbolic links
+ * @param {boolean} [options.mustExist=false] - Path must exist on filesystem
+ * @returns {{ ok: boolean, resolvedPath?: string, error?: PathValidationError }}
+ *
+ * @example
+ * // Validate a file path within project directory
+ * const result = validatePath('./config.yaml', '/home/user/project');
+ * if (result.ok) {
+ *   console.log('Safe path:', result.resolvedPath);
+ * }
+ *
+ * @example
+ * // Reject path traversal attempt
+ * const result = validatePath('../../../etc/passwd', '/home/user/project');
+ * // result.ok === false
+ * // result.error.reason === 'path_traversal'
+ */
+function validatePath(inputPath, baseDir, options = {}) {
+  const { allowSymlinks = false, mustExist = false } = options;
+
+  // Input validation
+  if (!inputPath || typeof inputPath !== 'string') {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        'Path is required and must be a string',
+        String(inputPath),
+        'invalid_input'
+      ),
+    };
+  }
+
+  if (!baseDir || typeof baseDir !== 'string') {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        'Base directory is required and must be a string',
+        inputPath,
+        'invalid_base'
+      ),
+    };
+  }
+
+  // Base directory must be absolute
+  if (!path.isAbsolute(baseDir)) {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        'Base directory must be an absolute path',
+        inputPath,
+        'relative_base'
+      ),
+    };
+  }
+
+  // Normalize the base directory
+  const normalizedBase = path.resolve(baseDir);
+
+  // Resolve the input path relative to base directory
+  let resolvedPath;
+  if (path.isAbsolute(inputPath)) {
+    resolvedPath = path.resolve(inputPath);
+  } else {
+    resolvedPath = path.resolve(normalizedBase, inputPath);
+  }
+
+  // Check for path traversal: resolved path must start with base directory
+  // Add trailing separator to prevent prefix attacks (e.g., /home/user vs /home/user2)
+  const baseWithSep = normalizedBase.endsWith(path.sep)
+    ? normalizedBase
+    : normalizedBase + path.sep;
+
+  const isWithinBase =
+    resolvedPath === normalizedBase || resolvedPath.startsWith(baseWithSep);
+
+  if (!isWithinBase) {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        `Path escapes base directory: ${inputPath}`,
+        inputPath,
+        'path_traversal'
+      ),
+    };
+  }
+
+  // Check if path exists (if required)
+  if (mustExist) {
+    try {
+      fs.accessSync(resolvedPath);
+    } catch {
+      return {
+        ok: false,
+        error: new PathValidationError(
+          `Path does not exist: ${resolvedPath}`,
+          inputPath,
+          'not_found'
+        ),
+      };
+    }
+  }
+
+  // Check for symbolic links (if not allowed)
+  if (!allowSymlinks) {
+    try {
+      const stats = fs.lstatSync(resolvedPath);
+      if (stats.isSymbolicLink()) {
+        return {
+          ok: false,
+          error: new PathValidationError(
+            `Symbolic links are not allowed: ${inputPath}`,
+            inputPath,
+            'symlink_rejected'
+          ),
+        };
+      }
+    } catch {
+      // Path doesn't exist yet, which is fine if mustExist is false
+      // Check parent directories for symlinks
+      const parts = path.relative(normalizedBase, resolvedPath).split(path.sep);
+      let currentPath = normalizedBase;
+
+      for (const part of parts) {
+        currentPath = path.join(currentPath, part);
+        try {
+          const stats = fs.lstatSync(currentPath);
+          if (stats.isSymbolicLink()) {
+            return {
+              ok: false,
+              error: new PathValidationError(
+                `Path contains symbolic link: ${currentPath}`,
+                inputPath,
+                'symlink_in_path'
+              ),
+            };
+          }
+        } catch {
+          // Part of path doesn't exist, stop checking
+          break;
+        }
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    resolvedPath,
+  };
+}
+
+/**
+ * Synchronous version that throws on invalid paths.
+ * Use when you want exceptions rather than result objects.
+ *
+ * @param {string} inputPath - The path to validate
+ * @param {string} baseDir - The allowed base directory
+ * @param {Object} options - Validation options
+ * @returns {string} The validated absolute path
+ * @throws {PathValidationError} If path is invalid
+ */
+function validatePathSync(inputPath, baseDir, options = {}) {
+  const result = validatePath(inputPath, baseDir, options);
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.resolvedPath;
+}
+
+/**
+ * Check if a path contains dangerous patterns without resolving.
+ * Useful for quick pre-validation before expensive operations.
+ *
+ * @param {string} inputPath - The path to check
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+function hasUnsafePathPatterns(inputPath) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { safe: false, reason: 'invalid_input' };
+  }
+
+  // Check for null bytes (can bypass security in some systems)
+  if (inputPath.includes('\0')) {
+    return { safe: false, reason: 'null_byte' };
+  }
+
+  // Check for obvious traversal patterns
+  if (inputPath.includes('..')) {
+    return { safe: false, reason: 'dot_dot_sequence' };
+  }
+
+  // Check for absolute paths on Unix when expecting relative
+  if (inputPath.startsWith('/') && !path.isAbsolute(inputPath)) {
+    return { safe: false, reason: 'unexpected_absolute' };
+  }
+
+  // Check for Windows-style absolute paths
+  if (/^[a-zA-Z]:/.test(inputPath)) {
+    return { safe: false, reason: 'windows_absolute' };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Sanitize a filename by removing dangerous characters.
+ * Does NOT validate the full path - use with validatePath().
+ *
+ * @param {string} filename - The filename to sanitize
+ * @param {Object} options - Sanitization options
+ * @param {string} [options.replacement='_'] - Character to replace with
+ * @param {number} [options.maxLength=255] - Maximum filename length
+ * @returns {string} Sanitized filename
+ */
+function sanitizeFilename(filename, options = {}) {
+  const { replacement = '_', maxLength = 255 } = options;
+
+  if (!filename || typeof filename !== 'string') {
+    return '';
+  }
+
+  // Remove or replace dangerous characters
+  let sanitized = filename
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, replacement) // Control chars and reserved
+    .replace(/\.{2,}/g, replacement) // Multiple dots
+    .replace(/^\.+/, replacement) // Leading dots
+    .replace(/^-+/, replacement); // Leading dashes (prevent flag injection)
+
+  // Truncate if too long
+  if (sanitized.length > maxLength) {
+    const ext = path.extname(sanitized);
+    const base = path.basename(sanitized, ext);
+    sanitized = base.slice(0, maxLength - ext.length) + ext;
+  }
+
+  return sanitized;
+}
+
 module.exports = {
+  // Patterns and basic validators
   PATTERNS,
   isValidBranchName,
   isValidStoryId,
@@ -334,4 +607,11 @@ module.exports = {
   parseIntBounded,
   isValidOption,
   validateArgs,
+
+  // Path traversal protection
+  PathValidationError,
+  validatePath,
+  validatePathSync,
+  hasUnsafePathPatterns,
+  sanitizeFilename,
 };

package/lib/yaml-utils.js

@@ -0,0 +1,122 @@
+/**
+ * Centralized YAML parsing utilities with security guarantees.
+ *
+ * Security Note (js-yaml v4.x):
+ * - yaml.load() is SAFE by default in v4+ (unlike v3.x)
+ * - Dangerous JavaScript types (functions, regexps) are NOT supported
+ * - Only JSON-compatible types are parsed
+ * - See: https://github.com/nodeca/js-yaml/blob/master/migrate_v3_to_v4.md
+ *
+ * This wrapper provides:
+ * - Explicit security documentation
+ * - Input validation
+ * - Consistent error handling
+ * - Future-proofing for library changes
+ */
+
+const yaml = require('js-yaml');
+
+/**
+ * Safely parse YAML content. Uses js-yaml's DEFAULT_SCHEMA which is
+ * safe by default in v4+ (does not execute arbitrary JavaScript).
+ *
+ * @param {string} content - YAML string to parse
+ * @param {Object} options - Optional yaml.load options
+ * @returns {any} Parsed YAML content (object, array, or primitive)
+ * @throws {yaml.YAMLException} If YAML is malformed
+ */
+function safeLoad(content, options = {}) {
+  if (typeof content !== 'string') {
+    throw new TypeError('YAML content must be a string');
+  }
+
+  // In js-yaml v4+, load() uses DEFAULT_SCHEMA which is safe.
+  // Explicitly pass schema to make the security guarantee clear
+  // and protect against future library changes.
+  return yaml.load(content, {
+    schema: yaml.DEFAULT_SCHEMA,
+    ...options,
+  });
+}
+
+/**
+ * Safely parse all YAML documents in a multi-document file.
+ *
+ * @param {string} content - YAML string containing one or more documents
+ * @param {Object} options - Optional yaml.loadAll options
+ * @returns {any[]} Array of parsed YAML documents
+ * @throws {yaml.YAMLException} If YAML is malformed
+ */
+function safeLoadAll(content, options = {}) {
+  if (typeof content !== 'string') {
+    throw new TypeError('YAML content must be a string');
+  }
+
+  const documents = [];
+  yaml.loadAll(
+    content,
+    (doc) => documents.push(doc),
+    { schema: yaml.DEFAULT_SCHEMA, ...options }
+  );
+  return documents;
+}
+
+/**
+ * Safely serialize data to YAML string.
+ *
+ * @param {any} data - Data to serialize
+ * @param {Object} options - Optional yaml.dump options
+ * @returns {string} YAML string representation
+ */
+function safeDump(data, options = {}) {
+  return yaml.dump(data, {
+    schema: yaml.DEFAULT_SCHEMA,
+    ...options,
+  });
+}
+
+/**
+ * Test if js-yaml is configured securely (no JavaScript type support).
+ * This function is used in security tests to verify the library version
+ * and configuration.
+ *
+ * @returns {boolean} True if the configuration is secure
+ */
+function isSecureConfiguration() {
+  // Attempt to parse YAML with JavaScript function syntax
+  // This should NOT execute any code in v4+
+  const maliciousYaml = `
+test: !!js/function 'function() { return "pwned"; }'
+regex: !!js/regexp /test/i
+undef: !!js/undefined ''
+`;
+
+  try {
+    const result = safeLoad(maliciousYaml);
+    // If we get here without executing code, and the values are
+    // either strings or undefined (not actual functions), we're safe
+    if (typeof result.test === 'function') {
+      return false; // Unsafe: function was instantiated
+    }
+    if (result.regex instanceof RegExp) {
+      return false; // Unsafe: regex was instantiated
+    }
+    // Values should be undefined or error out due to unknown tags
+    return true;
+  } catch (e) {
+    // YAMLException for unknown tags is the expected safe behavior
+    if (e.name === 'YAMLException') {
+      return true;
+    }
+    throw e;
+  }
+}
+
+module.exports = {
+  safeLoad,
+  safeLoadAll,
+  safeDump,
+  isSecureConfiguration,
+  // Re-export yaml module for edge cases that need direct access
+  yaml,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.87.0",
+  "version": "2.89.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",
@@ -53,8 +53,6 @@
     "test:coverage": "jest --coverage"
   },
   "dependencies": {
-    "blessed": "^0.1.81",
-    "blessed-contrib": "^4.10.1",
     "chalk": "^4.1.2",
     "commander": "^12.1.0",
     "fs-extra": "^11.2.0",

package/scripts/agileflow-welcome.js

@@ -18,6 +18,7 @@ const { execSync, spawnSync } = require('child_process');
 // Shared utilities
 const { c, box } = require('../lib/colors');
 const { getProjectRoot } = require('../lib/paths');
+const { readJSONCached, readFileCached } = require('../lib/file-cache');
 
 // Session manager path (relative to script location)
 const SESSION_MANAGER_PATH = path.join(__dirname, 'session-manager.js');
@@ -47,44 +48,29 @@ try {
 }
 
 /**
- * PERFORMANCE OPTIMIZATION: Load all project files once into cache
- * This eliminates duplicate file reads across multiple functions.
- * Estimated savings: 40-80ms
+ * PERFORMANCE OPTIMIZATION: Load all project files using LRU cache
+ * Uses file-cache module for automatic caching with 30s TTL.
+ * Files are cached across script invocations within TTL window.
+ * Estimated savings: 60-120ms on cache hits
  */
 function loadProjectFiles(rootDir) {
-  const cache = {
-    status: null,
-    metadata: null,
-    settings: null,
-    sessionState: null,
-    configYaml: null,
-    cliPackage: null,
-  };
-
   const paths = {
-    status: 'docs/09-agents/status.json',
-    metadata: 'docs/00-meta/agileflow-metadata.json',
-    settings: '.claude/settings.json',
-    sessionState: 'docs/09-agents/session-state.json',
-    configYaml: '.agileflow/config.yaml',
-    cliPackage: 'packages/cli/package.json',
+    status: path.join(rootDir, 'docs', '09-agents', 'status.json'),
+    metadata: path.join(rootDir, 'docs', '00-meta', 'agileflow-metadata.json'),
+    settings: path.join(rootDir, '.claude', 'settings.json'),
+    sessionState: path.join(rootDir, 'docs', '09-agents', 'session-state.json'),
+    configYaml: path.join(rootDir, '.agileflow', 'config.yaml'),
+    cliPackage: path.join(rootDir, 'packages', 'cli', 'package.json'),
   };
 
-  for (const [key, relPath] of Object.entries(paths)) {
-    const fullPath = path.join(rootDir, relPath);
-    try {
-      if (!fs.existsSync(fullPath)) continue;
-      if (key === 'configYaml') {
-        cache[key] = fs.readFileSync(fullPath, 'utf8');
-      } else {
-        cache[key] = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-      }
-    } catch (e) {
-      // Silently ignore - file not available or invalid
-    }
-  }
-
-  return cache;
+  return {
+    status: readJSONCached(paths.status),
+    metadata: readJSONCached(paths.metadata),
+    settings: readJSONCached(paths.settings),
+    sessionState: readJSONCached(paths.sessionState),
+    configYaml: readFileCached(paths.configYaml),
+    cliPackage: readJSONCached(paths.cliPackage),
+  };
 }
 
 /**

package/scripts/damage-control-bash.js

@@ -20,67 +20,10 @@ const {
   loadPatterns,
   outputBlocked,
   runDamageControlHook,
+  parseBashPatterns,
   c,
 } = require('./lib/damage-control-utils');
 
-/**
- * Parse simplified YAML for damage control patterns
- * Only parses the structure we need - not a full YAML parser
- */
-function parseSimpleYAML(content) {
-  const config = {
-    bashToolPatterns: [],
-    askPatterns: [],
-    agileflowProtections: [],
-  };
-
-  let currentSection = null;
-  let currentPattern = null;
-
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    // Detect section headers
-    if (trimmed === 'bashToolPatterns:') {
-      currentSection = 'bashToolPatterns';
-      currentPattern = null;
-    } else if (trimmed === 'askPatterns:') {
-      currentSection = 'askPatterns';
-      currentPattern = null;
-    } else if (trimmed === 'agileflowProtections:') {
-      currentSection = 'agileflowProtections';
-      currentPattern = null;
-    } else if (trimmed.endsWith(':') && !trimmed.startsWith('-')) {
-      // Other sections we don't care about for bash validation
-      currentSection = null;
-      currentPattern = null;
-    } else if (trimmed.startsWith('- pattern:') && currentSection) {
-      // New pattern entry
-      const patternValue = trimmed
-        .replace('- pattern:', '')
-        .trim()
-        .replace(/^["']|["']$/g, '');
-      currentPattern = { pattern: patternValue };
-      config[currentSection].push(currentPattern);
-    } else if (trimmed.startsWith('reason:') && currentPattern) {
-      currentPattern.reason = trimmed
-        .replace('reason:', '')
-        .trim()
-        .replace(/^["']|["']$/g, '');
-    } else if (trimmed.startsWith('flags:') && currentPattern) {
-      currentPattern.flags = trimmed
-        .replace('flags:', '')
-        .trim()
-        .replace(/^["']|["']$/g, '');
-    }
-  }
-
-  return config;
-}
-
 /**
  * Test command against a single pattern rule
  */
@@ -134,7 +77,7 @@ const defaultConfig = { bashToolPatterns: [], askPatterns: [], agileflowProtecti
 
 runDamageControlHook({
   getInputValue: input => input.command || input.tool_input?.command,
-  loadConfig: () => loadPatterns(projectRoot, parseSimpleYAML, defaultConfig),
+  loadConfig: () => loadPatterns(projectRoot, parseBashPatterns, defaultConfig),
   validate: validateCommand,
   onBlock: (result, command) => {
     outputBlocked(

package/scripts/damage-control-edit.js

@@ -15,85 +15,20 @@
 const {
   findProjectRoot,
   loadPatterns,
-  pathMatches,
   outputBlocked,
   runDamageControlHook,
+  parsePathPatterns,
+  validatePathAgainstPatterns,
 } = require('./lib/damage-control-utils');
 
-/**
- * Parse simplified YAML for path patterns
- */
-function parseSimpleYAML(content) {
-  const config = {
-    zeroAccessPaths: [],
-    readOnlyPaths: [],
-    noDeletePaths: [],
-  };
-
-  let currentSection = null;
-
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    // Detect section headers
-    if (trimmed === 'zeroAccessPaths:') {
-      currentSection = 'zeroAccessPaths';
-    } else if (trimmed === 'readOnlyPaths:') {
-      currentSection = 'readOnlyPaths';
-    } else if (trimmed === 'noDeletePaths:') {
-      currentSection = 'noDeletePaths';
-    } else if (trimmed.endsWith(':') && !trimmed.startsWith('-')) {
-      // Other sections we don't care about for path validation
-      currentSection = null;
-    } else if (trimmed.startsWith('- ') && currentSection && config[currentSection]) {
-      // Path entry
-      const pathValue = trimmed.slice(2).replace(/^["']|["']$/g, '');
-      config[currentSection].push(pathValue);
-    }
-  }
-
-  return config;
-}
-
-/**
- * Validate file path for edit operation
- */
-function validatePath(filePath, config) {
-  // Check zero access paths - completely blocked
-  const zeroMatch = pathMatches(filePath, config.zeroAccessPaths || []);
-  if (zeroMatch) {
-    return {
-      action: 'block',
-      reason: `Zero-access path: ${zeroMatch}`,
-      detail: 'This file is protected and cannot be accessed',
-    };
-  }
-
-  // Check read-only paths - cannot edit
-  const readOnlyMatch = pathMatches(filePath, config.readOnlyPaths || []);
-  if (readOnlyMatch) {
-    return {
-      action: 'block',
-      reason: `Read-only path: ${readOnlyMatch}`,
-      detail: 'This file is read-only and cannot be edited',
-    };
-  }
-
-  // Allow by default
-  return { action: 'allow' };
-}
-
 // Run the hook
 const projectRoot = findProjectRoot();
 const defaultConfig = { zeroAccessPaths: [], readOnlyPaths: [], noDeletePaths: [] };
 
 runDamageControlHook({
   getInputValue: input => input.file_path || input.tool_input?.file_path,
-  loadConfig: () => loadPatterns(projectRoot, parseSimpleYAML, defaultConfig),
-  validate: validatePath,
+  loadConfig: () => loadPatterns(projectRoot, parsePathPatterns, defaultConfig),
+  validate: (filePath, config) => validatePathAgainstPatterns(filePath, config, 'edit'),
   onBlock: (result, filePath) => {
     outputBlocked(result.reason, result.detail, `File: ${filePath}`);
   },