agileflow 2.88.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.88.0",
+  "version": "2.89.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

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/obtain-context.js

@@ -20,6 +20,7 @@ const path = require('path');
 const { execSync } = require('child_process');
 const { c: C, box } = require('../lib/colors');
 const { isValidCommandName } = require('../lib/validate');
+const { readJSONCached, readFileCached } = require('../lib/file-cache');
 
 // Claude Code's Bash tool truncates around 30K chars, but ANSI codes and
 // box-drawing characters (╭╮╰╯─│) are multi-byte UTF-8, so we need buffer.
@@ -131,11 +132,9 @@ function safeRead(filePath) {
 }
 
 function safeReadJSON(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
+  // Use cached read for common JSON files
+  const absPath = path.resolve(filePath);
+  return readJSONCached(absPath);
 }
 
 function safeLs(dirPath) {

package/tools/cli/installers/core/installer.js

@@ -11,6 +11,7 @@ const ora = require('ora');
 const yaml = require('js-yaml');
 const { injectContent } = require('../../lib/content-injector');
 const { sha256Hex, toPosixPath, safeTimestampForPath } = require('../../lib/utils');
+const { validatePath, PathValidationError } = require('../../../../lib/validate');
 
 const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json']);
 
@@ -191,6 +192,22 @@ class Installer {
     }
   }
 
+  /**
+   * Validate that a path is within the allowed installation directory.
+   * Prevents path traversal attacks when writing files.
+   *
+   * @param {string} filePath - Path to validate
+   * @param {string} baseDir - Allowed base directory
+   * @throws {PathValidationError} If path escapes base directory
+   */
+  validateInstallPath(filePath, baseDir) {
+    const result = validatePath(filePath, baseDir, { allowSymlinks: false });
+    if (!result.ok) {
+      throw result.error;
+    }
+    return result.resolvedPath;
+  }
+
   /**
    * Copy content from source to destination with placeholder replacement
    * @param {string} source - Source directory
@@ -201,10 +218,16 @@ class Installer {
   async copyContent(source, dest, agileflowFolder, policy = null) {
     const entries = await fs.readdir(source, { withFileTypes: true });
 
+    // Get base directory for validation (agileflowDir from policy or dest itself)
+    const baseDir = policy?.agileflowDir || dest;
+
     for (const entry of entries) {
       const srcPath = path.join(source, entry.name);
       const destPath = path.join(dest, entry.name);
 
+      // Validate destination path to prevent traversal attacks via malicious filenames
+      this.validateInstallPath(destPath, baseDir);
+
       if (entry.isDirectory()) {
         await fs.ensureDir(destPath);
         await this.copyContent(srcPath, destPath, agileflowFolder, policy);
@@ -688,18 +711,25 @@ class Installer {
    * @param {string} srcDir - Source directory
    * @param {string} destDir - Destination directory
    * @param {boolean} force - Overwrite existing files
+   * @param {string} [baseDir] - Base directory for path validation (defaults to destDir on first call)
    */
-  async copyScriptsRecursive(srcDir, destDir, force) {
+  async copyScriptsRecursive(srcDir, destDir, force, baseDir = null) {
     const entries = await fs.readdir(srcDir, { withFileTypes: true });
 
+    // Use destDir as base for validation on first call
+    const validationBase = baseDir || destDir;
+
     for (const entry of entries) {
       const srcPath = path.join(srcDir, entry.name);
       const destPath = path.join(destDir, entry.name);
 
+      // Validate destination path to prevent traversal via malicious filenames
+      this.validateInstallPath(destPath, validationBase);
+
       if (entry.isDirectory()) {
         // Recursively copy subdirectories
         await fs.ensureDir(destPath);
-        await this.copyScriptsRecursive(srcPath, destPath, force);
+        await this.copyScriptsRecursive(srcPath, destPath, force, validationBase);
       } else {
         // Copy file
         const destExists = await fs.pathExists(destPath);