agileflow 2.89.3 → 2.90.0

package/lib/validate.js

@@ -3,749 +3,47 @@
  *
  * Centralized validation patterns and helpers to prevent
  * 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.
- */
-const PATTERNS = {
-  // Git branch: alphanumeric, underscores, hyphens, forward slashes
-  // Examples: main, feature/US-0001, session-1, my_branch
-  branchName: /^[a-zA-Z0-9][a-zA-Z0-9_/-]*$/,
-
-  // Story ID: US-0001 to US-99999
-  storyId: /^US-\d{4,5}$/,
-
-  // Epic ID: EP-0001 to EP-99999
-  epicId: /^EP-\d{4,5}$/,
-
-  // Feature name: lowercase with hyphens, starts with letter
-  // Examples: damage-control, status-line, archival
-  featureName: /^[a-z][a-z0-9-]*$/,
-
-  // Profile name: alphanumeric with underscores/hyphens, starts with letter
-  // Examples: default, my-profile, dev_config
-  profileName: /^[a-zA-Z][a-zA-Z0-9_-]*$/,
-
-  // Command name: alphanumeric with hyphens/colons, starts with letter
-  // Examples: babysit, story:list, agileflow:configure
-  commandName: /^[a-zA-Z][a-zA-Z0-9:-]*$/,
-
-  // Session nickname: alphanumeric with hyphens/underscores
-  // Examples: auth-work, feature_1, main
-  sessionNickname: /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/,
-
-  // Merge strategy: squash or merge
-  // Examples: squash, merge
-  mergeStrategy: /^(squash|merge)$/,
-};
-
-/**
- * Validate a git branch name.
- * @param {string} name - Branch name to validate
- * @returns {boolean} True if valid
- */
-function isValidBranchName(name) {
-  if (!name || typeof name !== 'string') return false;
-  if (name.length > 255) return false; // Git limit
-  if (name.startsWith('-')) return false; // Prevent flag injection
-  if (name.includes('..')) return false; // Prevent path traversal
-  if (name.endsWith('.lock')) return false; // Reserved
-  return PATTERNS.branchName.test(name);
-}
-
-/**
- * Validate a story ID (US-XXXX format).
- * @param {string} id - Story ID to validate
- * @returns {boolean} True if valid
- */
-function isValidStoryId(id) {
-  if (!id || typeof id !== 'string') return false;
-  return PATTERNS.storyId.test(id);
-}
-
-/**
- * Validate an epic ID (EP-XXXX format).
- * @param {string} id - Epic ID to validate
- * @returns {boolean} True if valid
- */
-function isValidEpicId(id) {
-  if (!id || typeof id !== 'string') return false;
-  return PATTERNS.epicId.test(id);
-}
-
-/**
- * Validate a feature name.
- * @param {string} name - Feature name to validate
- * @returns {boolean} True if valid
- */
-function isValidFeatureName(name) {
-  if (!name || typeof name !== 'string') return false;
-  if (name.length > 50) return false;
-  return PATTERNS.featureName.test(name);
-}
-
-/**
- * Validate a profile name.
- * @param {string} name - Profile name to validate
- * @returns {boolean} True if valid
- */
-function isValidProfileName(name) {
-  if (!name || typeof name !== 'string') return false;
-  if (name.length > 50) return false;
-  return PATTERNS.profileName.test(name);
-}
-
-/**
- * Validate a command name.
- * @param {string} name - Command name to validate
- * @returns {boolean} True if valid
- */
-function isValidCommandName(name) {
-  if (!name || typeof name !== 'string') return false;
-  if (name.length > 100) return false;
-  return PATTERNS.commandName.test(name);
-}
-
-/**
- * Validate a session nickname.
- * @param {string} name - Nickname to validate
- * @returns {boolean} True if valid
- */
-function isValidSessionNickname(name) {
-  if (!name || typeof name !== 'string') return false;
-  if (name.length > 50) return false;
-  return PATTERNS.sessionNickname.test(name);
-}
-
-/**
- * Validate a merge strategy (squash or merge).
- * @param {string} strategy - Strategy to validate
- * @returns {boolean} True if valid
- */
-function isValidMergeStrategy(strategy) {
-  if (!strategy || typeof strategy !== 'string') return false;
-  return PATTERNS.mergeStrategy.test(strategy);
-}
-
-/**
- * Validate that a value is a positive integer within bounds.
- * @param {any} val - Value to validate
- * @param {number} min - Minimum allowed value (inclusive)
- * @param {number} max - Maximum allowed value (inclusive)
- * @returns {boolean} True if valid positive integer in range
- */
-function isPositiveInteger(val, min = 1, max = Number.MAX_SAFE_INTEGER) {
-  const num = typeof val === 'string' ? parseInt(val, 10) : val;
-  if (!Number.isInteger(num)) return false;
-  return num >= min && num <= max;
-}
-
-/**
- * Parse and validate an integer with bounds.
- * @param {any} val - Value to parse
- * @param {number} defaultVal - Default if invalid
- * @param {number} min - Minimum allowed value
- * @param {number} max - Maximum allowed value
- * @returns {number} Parsed integer or default
- */
-function parseIntBounded(val, defaultVal, min = 1, max = Number.MAX_SAFE_INTEGER) {
-  const num = typeof val === 'string' ? parseInt(val, 10) : val;
-  if (!Number.isInteger(num) || num < min || num > max) {
-    return defaultVal;
-  }
-  return num;
-}
-
-/**
- * Validate an option key against an allowed whitelist.
- * @param {string} key - Option key to validate
- * @param {string[]} allowedKeys - Array of allowed keys
- * @returns {boolean} True if key is in whitelist
- */
-function isValidOption(key, allowedKeys) {
-  if (!key || typeof key !== 'string') return false;
-  if (!Array.isArray(allowedKeys)) return false;
-  return allowedKeys.includes(key);
-}
-
-/**
- * Validate and sanitize CLI arguments for known option types.
- * Returns validated args object or null if critical validation fails.
- *
- * @param {string[]} args - Raw process.argv slice
- * @param {Object} schema - Schema defining expected options
- * @returns {{ ok: boolean, data?: Object, error?: string }}
- *
- * @example
- * const schema = {
- *   branch: { type: 'branchName', required: true },
- *   max: { type: 'positiveInt', min: 1, max: 100, default: 20 },
- *   profile: { type: 'profileName', default: 'default' }
- * };
- * const result = validateArgs(args, schema);
- */
-function validateArgs(args, schema) {
-  const result = {};
-  const errors = [];
-
-  // Parse args into key-value pairs
-  const parsed = {};
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg.startsWith('--')) {
-      const [key, ...valueParts] = arg.slice(2).split('=');
-      const value = valueParts.length > 0 ? valueParts.join('=') : args[++i];
-      parsed[key] = value;
-    }
-  }
-
-  // Validate each schema field
-  for (const [field, config] of Object.entries(schema)) {
-    const value = parsed[field];
-
-    // Check required
-    if (config.required && (value === undefined || value === null)) {
-      errors.push(`Missing required option: --${field}`);
-      continue;
-    }
-
-    // Use default if not provided
-    if (value === undefined || value === null) {
-      if (config.default !== undefined) {
-        result[field] = config.default;
-      }
-      continue;
-    }
-
-    // Validate by type
-    switch (config.type) {
-      case 'branchName':
-        if (!isValidBranchName(value)) {
-          errors.push(`Invalid branch name: ${value}`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'storyId':
-        if (!isValidStoryId(value)) {
-          errors.push(`Invalid story ID: ${value} (expected US-XXXX)`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'epicId':
-        if (!isValidEpicId(value)) {
-          errors.push(`Invalid epic ID: ${value} (expected EP-XXXX)`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'featureName':
-        if (!isValidFeatureName(value)) {
-          errors.push(`Invalid feature name: ${value}`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'profileName':
-        if (!isValidProfileName(value)) {
-          errors.push(`Invalid profile name: ${value}`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'commandName':
-        if (!isValidCommandName(value)) {
-          errors.push(`Invalid command name: ${value}`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'sessionNickname':
-        if (!isValidSessionNickname(value)) {
-          errors.push(`Invalid session nickname: ${value}`);
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'positiveInt': {
-        const min = config.min || 1;
-        const max = config.max || Number.MAX_SAFE_INTEGER;
-        if (!isPositiveInteger(value, min, max)) {
-          errors.push(`Invalid integer for ${field}: ${value} (expected ${min}-${max})`);
-          result[field] = config.default;
-        } else {
-          result[field] = parseInt(value, 10);
-        }
-        break;
-      }
-
-      case 'enum':
-        if (!config.values.includes(value)) {
-          errors.push(
-            `Invalid value for ${field}: ${value} (expected: ${config.values.join(', ')})`
-          );
-        } else {
-          result[field] = value;
-        }
-        break;
-
-      case 'boolean':
-        result[field] = value === 'true' || value === '1' || value === true;
-        break;
-
-      case 'string':
-        // Basic string - just store it (caller should validate further if needed)
-        result[field] = String(value);
-        break;
-
-      default:
-        result[field] = value;
-    }
-  }
-
-  if (errors.length > 0) {
-    return { ok: false, error: errors.join('; ') };
-  }
-
-  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);
-  }
-}
-
-/**
- * Check the depth of a symlink chain (how many symlinks to follow to reach final target).
- * Returns early if chain exceeds maxDepth to prevent infinite loops from circular symlinks.
- *
- * @param {string} filePath - Starting path to check
- * @param {number} maxDepth - Maximum allowed symlink chain depth
- * @returns {{ ok: boolean, depth: number, error?: string, isCircular?: boolean }}
- */
-function checkSymlinkChainDepth(filePath, maxDepth) {
-  let current = filePath;
-  let depth = 0;
-  const seen = new Set();
-
-  // Loop until we find a non-symlink or exceed max depth
-  while (true) {
-    // Check for circular symlinks
-    if (seen.has(current)) {
-      return {
-        ok: false,
-        depth,
-        error: `Circular symlink detected at: ${current}`,
-        isCircular: true,
-      };
-    }
-    seen.add(current);
-
-    try {
-      const stats = fs.lstatSync(current);
-      if (!stats.isSymbolicLink()) {
-        // Reached a real file/directory, chain ends
-        return { ok: true, depth };
-      }
-
-      // Increment depth before checking limit
-      depth++;
-
-      // Check if we've exceeded max depth
-      if (depth > maxDepth) {
-        return {
-          ok: false,
-          depth,
-          error: `Symlink chain depth (${depth}) exceeds maximum (${maxDepth})`,
-        };
-      }
-
-      // Read symlink target
-      const target = fs.readlinkSync(current);
-
-      // Resolve target path (could be relative or absolute)
-      if (path.isAbsolute(target)) {
-        current = target;
-      } else {
-        current = path.resolve(path.dirname(current), target);
-      }
-    } catch (e) {
-      if (e.code === 'ENOENT') {
-        // Path doesn't exist, chain ends here
-        return { ok: true, depth };
-      }
-      // Other error (permission denied, etc.)
-      return { ok: true, depth };
-    }
-  }
-}
-
-/**
- * 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)
- * 4. When symlinks allowed, verifying symlink targets stay within base
- * 5. Limiting symlink chain depth to prevent infinite loops
  *
- * @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
- * @param {number} [options.maxSymlinkDepth=3] - Maximum symlink chain depth (when symlinks allowed)
- * @returns {{ ok: boolean, resolvedPath?: string, realPath?: 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'
- *
- * @example
- * // Reject deep symlink chains
- * const result = validatePath('link1', baseDir, { allowSymlinks: true, maxSymlinkDepth: 3 });
- * // If link1 -> link2 -> link3 -> link4 -> target, this fails with 'symlink_chain_too_deep'
+ * This module re-exports from split validation modules for backward compatibility.
+ * For better performance, import directly from:
+ *   - validate-names.js - Name/ID validation patterns
+ *   - validate-args.js  - CLI argument validation
+ *   - validate-paths.js - Path traversal protection
  */
-function validatePath(inputPath, baseDir, options = {}) {
-  const { allowSymlinks = false, mustExist = false, maxSymlinkDepth = 3 } = 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);
-  }
-
-  // Helper function to check if path is within base
-  const checkWithinBase = pathToCheck => {
-    const baseWithSep = normalizedBase.endsWith(path.sep)
-      ? normalizedBase
-      : normalizedBase + path.sep;
-    return pathToCheck === normalizedBase || pathToCheck.startsWith(baseWithSep);
-  };
-
-  // Check for path traversal: resolved path must start with base directory
-  if (!checkWithinBase(resolvedPath)) {
-    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 (!allowSymlinks) {
-    // Symlinks not allowed - reject if found
-    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;
-        }
-      }
-    }
-  } else {
-    // Symlinks allowed - but we must verify the target stays within base!
-    // This prevents symlink-based escape attacks
-    try {
-      const stats = fs.lstatSync(resolvedPath);
-      if (stats.isSymbolicLink()) {
-        // Check symlink chain depth to prevent DoS via infinite loops
-        const chainResult = checkSymlinkChainDepth(resolvedPath, maxSymlinkDepth);
-        if (!chainResult.ok) {
-          const reason = chainResult.isCircular ? 'symlink_circular' : 'symlink_chain_too_deep';
-          return {
-            ok: false,
-            error: new PathValidationError(chainResult.error, inputPath, reason),
-          };
-        }
-
-        // Resolve the symlink target to its real path
-        const realPath = fs.realpathSync(resolvedPath);
-
-        // Verify the real path is also within base directory
-        if (!checkWithinBase(realPath)) {
-          return {
-            ok: false,
-            error: new PathValidationError(
-              `Symlink target escapes base directory: ${inputPath} -> ${realPath}`,
-              inputPath,
-              'symlink_escape'
-            ),
-          };
-        }
-
-        // Return both the resolved path and the real path
-        return {
-          ok: true,
-          resolvedPath,
-          realPath,
-        };
-      }
-    } catch {
-      // Path doesn't exist - that's okay for non-mustExist scenarios
-      // Also check parent directories for symlinks that might escape
-      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()) {
-            // Check symlink chain depth
-            const chainResult = checkSymlinkChainDepth(currentPath, maxSymlinkDepth);
-            if (!chainResult.ok) {
-              const reason = chainResult.isCircular ? 'symlink_circular' : 'symlink_chain_too_deep';
-              return {
-                ok: false,
-                error: new PathValidationError(chainResult.error, inputPath, reason),
-              };
-            }
-
-            // Resolve this symlink and check its target
-            const realPath = fs.realpathSync(currentPath);
-            if (!checkWithinBase(realPath)) {
-              return {
-                ok: false,
-                error: new PathValidationError(
-                  `Path contains symlink escaping base: ${currentPath} -> ${realPath}`,
-                  inputPath,
-                  'symlink_escape'
-                ),
-              };
-            }
-          }
-        } 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)
+// Re-export name validators
+const {
+  PATTERNS,
+  isValidBranchName,
+  isValidStoryId,
+  isValidEpicId,
+  isValidFeatureName,
+  isValidProfileName,
+  isValidCommandName,
+  isValidSessionNickname,
+  isValidMergeStrategy,
+} = require('./validate-names');
 
-  // 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;
-  }
+// Re-export argument validators
+const {
+  isPositiveInteger,
+  parseIntBounded,
+  isValidOption,
+  validateArgs,
+} = require('./validate-args');
 
-  return sanitized;
-}
+// Re-export path validators
+const {
+  PathValidationError,
+  checkSymlinkChainDepth,
+  validatePath,
+  validatePathSync,
+  hasUnsafePathPatterns,
+  sanitizeFilename,
+} = require('./validate-paths');
 
 module.exports = {
-  // Patterns and basic validators
+  // Patterns and basic validators (from validate-names.js)
   PATTERNS,
   isValidBranchName,
   isValidStoryId,
@@ -755,12 +53,14 @@ module.exports = {
   isValidCommandName,
   isValidSessionNickname,
   isValidMergeStrategy,
+
+  // Argument validators (from validate-args.js)
   isPositiveInteger,
   parseIntBounded,
   isValidOption,
   validateArgs,
 
-  // Path traversal protection
+  // Path traversal protection (from validate-paths.js)
   PathValidationError,
   validatePath,
   validatePathSync,