claude-flow-novice 2.15.3 → 2.15.5

package/dist/lib/password-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/password-generator.ts"],"sourcesContent":["/**\r\n * Secure Password Generator\r\n *\r\n * Generates cryptographically secure passwords for database authentication\r\n * with configurable complexity requirements and validation.\r\n *\r\n * Security Standards:\r\n * - Uses crypto.randomBytes() for cryptographic randomness\r\n * - Default minimum 32 characters for high entropy\r\n * - Requires mixed character types (uppercase, lowercase, digits, special)\r\n * - No ambiguous characters (0/O, 1/l, etc.)\r\n * - Suitable for Redis requirepass and PostgreSQL authentication\r\n */\r\n\r\nimport { randomBytes } from 'crypto';\r\n\r\nexport interface PasswordOptions {\r\n  length?: number;\r\n  uppercase?: boolean;\r\n  lowercase?: boolean;\r\n  digits?: boolean;\r\n  special?: boolean;\r\n  excludeAmbiguous?: boolean;\r\n}\r\n\r\nexport interface PasswordValidationResult {\r\n  valid: boolean;\r\n  length: number;\r\n  hasUppercase: boolean;\r\n  hasLowercase: boolean;\r\n  hasDigits: boolean;\r\n  hasSpecial: boolean;\r\n  errors: string[];\r\n}\r\n\r\n/**\r\n * Default character sets for password generation\r\n */\r\nconst CHAR_SETS = {\r\n  uppercase: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',\r\n  uppercaseNoAmbiguous: 'ABCDEFGHJKMNPQRSTUVWXYZ', // Removed: I, L, O\r\n  lowercase: 'abcdefghijklmnopqrstuvwxyz',\r\n  lowercaseNoAmbiguous: 'abcdefghjkmnpqrstuvwxyz', // Removed: i, l, o\r\n  digits: '0123456789',\r\n  digitsNoAmbiguous: '23456789', // Removed: 0, 1\r\n  special: '!@#$%^&*()_+-=[]{}|;:,.<>?',\r\n  specialSafe: '!@#%^&*_+-=', // Removed: $, `, \", ' for environment variable safety\r\n};\r\n\r\n/**\r\n * Generate a cryptographically secure random password\r\n */\r\nexport function generatePassword(options: PasswordOptions = {}): string {\r\n  const {\r\n    length = 32,\r\n    uppercase = true,\r\n    lowercase = true,\r\n    digits = true,\r\n    special = true,\r\n    excludeAmbiguous = true,\r\n  } = options;\r\n\r\n  if (length < 16) {\r\n    throw new Error('Password length must be at least 16 characters');\r\n  }\r\n\r\n  // Build character pool\r\n  let charPool = '';\r\n  const selectedSets: string[] = [];\r\n\r\n  if (uppercase) {\r\n    const chars = excludeAmbiguous ? CHAR_SETS.uppercaseNoAmbiguous : CHAR_SETS.uppercase;\r\n    charPool += chars;\r\n    selectedSets.push('uppercase');\r\n  }\r\n\r\n  if (lowercase) {\r\n    const chars = excludeAmbiguous ? CHAR_SETS.lowercaseNoAmbiguous : CHAR_SETS.lowercase;\r\n    charPool += chars;\r\n    selectedSets.push('lowercase');\r\n  }\r\n\r\n  if (digits) {\r\n    const chars = excludeAmbiguous ? CHAR_SETS.digitsNoAmbiguous : CHAR_SETS.digits;\r\n    charPool += chars;\r\n    selectedSets.push('digits');\r\n  }\r\n\r\n  if (special) {\r\n    charPool += CHAR_SETS.specialSafe;\r\n    selectedSets.push('special');\r\n  }\r\n\r\n  if (charPool.length === 0) {\r\n    throw new Error('At least one character type must be enabled');\r\n  }\r\n\r\n  // Ensure password contains at least one character from each required type\r\n  const password = new Array(length);\r\n  let generated = 0;\r\n\r\n  // First, place one character from each required set\r\n  for (const setName of selectedSets) {\r\n    let setChars: string;\r\n    switch (setName) {\r\n      case 'uppercase':\r\n        setChars = uppercase ? (excludeAmbiguous ? CHAR_SETS.uppercaseNoAmbiguous : CHAR_SETS.uppercase) : '';\r\n        break;\r\n      case 'lowercase':\r\n        setChars = lowercase ? (excludeAmbiguous ? CHAR_SETS.lowercaseNoAmbiguous : CHAR_SETS.lowercase) : '';\r\n        break;\r\n      case 'digits':\r\n        setChars = digits ? (excludeAmbiguous ? CHAR_SETS.digitsNoAmbiguous : CHAR_SETS.digits) : '';\r\n        break;\r\n      case 'special':\r\n        setChars = special ? CHAR_SETS.specialSafe : '';\r\n        break;\r\n      default:\r\n        setChars = '';\r\n    }\r\n\r\n    if (setChars.length > 0 && generated < length) {\r\n      const index = cryptoRandom(0, setChars.length - 1);\r\n      password[generated] = setChars[index];\r\n      generated++;\r\n    }\r\n  }\r\n\r\n  // Fill remaining positions with random characters from pool\r\n  while (generated < length) {\r\n    const index = cryptoRandom(0, charPool.length - 1);\r\n    password[generated] = charPool[index];\r\n    generated++;\r\n  }\r\n\r\n  // Shuffle password to avoid predictable patterns\r\n  return shuffleArray(password).join('');\r\n}\r\n\r\n/**\r\n * Validate password meets security requirements\r\n */\r\nexport function validatePassword(password: string, minLength: number = 32): PasswordValidationResult {\r\n  const errors: string[] = [];\r\n  const hasUppercase = /[A-Z]/.test(password);\r\n  const hasLowercase = /[a-z]/.test(password);\r\n  const hasDigits = /\\d/.test(password);\r\n  const hasSpecial = /[!@#$%^&*()_+\\-=\\[\\]{}|;:,.<>?]/.test(password);\r\n\r\n  if (password.length < minLength) {\r\n    errors.push(`Password must be at least ${minLength} characters long (current: ${password.length})`);\r\n  }\r\n\r\n  if (!hasUppercase) {\r\n    errors.push('Password must contain at least one uppercase letter');\r\n  }\r\n\r\n  if (!hasLowercase) {\r\n    errors.push('Password must contain at least one lowercase letter');\r\n  }\r\n\r\n  if (!hasDigits) {\r\n    errors.push('Password must contain at least one digit');\r\n  }\r\n\r\n  if (!hasSpecial) {\r\n    errors.push('Password must contain at least one special character');\r\n  }\r\n\r\n  return {\r\n    valid: errors.length === 0,\r\n    length: password.length,\r\n    hasUppercase,\r\n    hasLowercase,\r\n    hasDigits,\r\n    hasSpecial,\r\n    errors,\r\n  };\r\n}\r\n\r\n/**\r\n * Generate a cryptographically secure random integer in range [min, max]\r\n */\r\nfunction cryptoRandom(min: number, max: number): number {\r\n  if (min < 0 || max < 0 || min > max) {\r\n    throw new Error('Invalid range: min must be >= 0 and min must be <= max');\r\n  }\r\n\r\n  const range = max - min + 1;\r\n  const bytesNeeded = Math.ceil(Math.log2(range) / 8);\r\n  const randomBytes_ = randomBytes(bytesNeeded);\r\n\r\n  // Convert bytes to integer and apply modulo to ensure uniform distribution\r\n  let randomValue = 0;\r\n  for (let i = 0; i < bytesNeeded; i++) {\r\n    randomValue = (randomValue << 8) | randomBytes_[i];\r\n  }\r\n\r\n  // Use rejection sampling to ensure uniform distribution\r\n  const limit = Math.floor(256 ** bytesNeeded / range) * range;\r\n\r\n  if (randomValue < limit) {\r\n    return min + (randomValue % range);\r\n  }\r\n\r\n  // Recursively try again if we exceeded the limit (very rare)\r\n  return cryptoRandom(min, max);\r\n}\r\n\r\n/**\r\n * Shuffle array in-place using Fisher-Yates algorithm\r\n */\r\nfunction shuffleArray<T>(array: T[]): T[] {\r\n  const shuffled = [...array];\r\n\r\n  for (let i = shuffled.length - 1; i > 0; i--) {\r\n    const j = cryptoRandom(0, i);\r\n    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];\r\n  }\r\n\r\n  return shuffled;\r\n}\r\n"],"names":["randomBytes","CHAR_SETS","uppercase","uppercaseNoAmbiguous","lowercase","lowercaseNoAmbiguous","digits","digitsNoAmbiguous","special","specialSafe","generatePassword","options","length","excludeAmbiguous","Error","charPool","selectedSets","chars","push","password","Array","generated","setName","setChars","index","cryptoRandom","shuffleArray","join","validatePassword","minLength","errors","hasUppercase","test","hasLowercase","hasDigits","hasSpecial","valid","min","max","range","bytesNeeded","Math","ceil","log2","randomBytes_","randomValue","i","limit","floor","array","shuffled","j"],"mappings":"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"}

package/dist/lib/path-validator.js

@@ -0,0 +1,429 @@
+/**
+ * Path Validator - Security Utility for Safe File Operations
+ *
+ * Provides robust path sanitization and validation to prevent path traversal attacks (CVSS 7.0+).
+ * Enforces strict rules on file access with protection against encoding attacks:
+ *
+ * CRITICAL FIXES (CVSS 7.0+):
+ * - Iterative URL decoding prevents double-encoding bypasses (%252e%252e%252f → ../)
+ * - Unicode normalization (NFC) prevents overlong UTF-8 bypasses (%c0%ae → .)
+ * - Null byte detection prevents null injection attacks
+ * - All decoding performed BEFORE path normalization to prevent layered attacks
+ * - Encoding attack detection with security logging
+ *
+ * Base Security Controls:
+ * - Path normalization to resolve ".." and "." sequences
+ * - Validation that resolved paths stay within allowed directories
+ * - Detection and rejection of symlinks
+ * - Rejection of absolute paths outside allowed directories
+ * - Prevention of home directory access ("~")
+ *
+ * @module path-validator
+ * @version 2.0.0 (SECURITY CRITICAL)
+ */ import * as path from 'path';
+import * as fs from 'fs';
+import { StandardError } from './errors';
+/**
+ * Path validation error - thrown when a path violates security constraints
+ */ export class PathValidationError extends StandardError {
+    constructor(message, context){
+        super('PATH_VALIDATION_ERROR', message, context);
+        this.name = 'PathValidationError';
+    }
+}
+/**
+ * Safely decode a path with protection against encoding attacks
+ *
+ * Performs iterative URL decoding and Unicode normalization to prevent:
+ * - Double encoding bypass (e.g., %252e%252e%252f → %2e%2e%2f → ../)
+ * - Overlong UTF-8 encoding (e.g., %c0%ae%c0%ae/ → ../)
+ * - Mixed encoding attacks
+ *
+ * @param inputPath - The potentially encoded path
+ * @returns Decoded path and attack detection info
+ * @throws PathValidationError if encoding attack detected
+ *
+ * @example
+ * const { decoded, encoding } = decodePathSafely('%252e%252e%252f');
+ * // Detects double-encoding attempt
+ */ function decodePathSafely(inputPath) {
+    let decoded = inputPath;
+    let previous = '';
+    let iterations = 0;
+    const MAX_ITERATIONS = 5;
+    const originalInput = inputPath;
+    let invalidEncodingDetected = false;
+    // Iteratively decode URL-encoded characters until stable
+    // This prevents bypass attacks using multiple encoding layers
+    while(decoded !== previous && iterations < MAX_ITERATIONS){
+        previous = decoded;
+        try {
+            decoded = decodeURIComponent(decoded);
+        } catch (error) {
+            // Invalid URL encoding (including malformed UTF-8) indicates attack
+            // e.g., %c0%ae is malformed UTF-8 for overlong encoding
+            invalidEncodingDetected = true;
+            break;
+        }
+        iterations++;
+    }
+    // Check if we hit max iterations (indicates potential encoding attack)
+    if (iterations >= MAX_ITERATIONS && decoded !== previous) {
+        throw new PathValidationError('Path validation failed: excessive encoding layers detected', {
+            originalInput,
+            decodedOutput: decoded,
+            iterations,
+            reason: 'ENCODING_ATTACK_DETECTED'
+        });
+    }
+    // Invalid encoding like malformed UTF-8 is itself an attack indicator
+    if (invalidEncodingDetected) {
+        throw new PathValidationError('Path validation failed: invalid encoding detected (possible encoding attack)', {
+            originalInput,
+            decodedOutput: decoded,
+            iterations,
+            reason: 'INVALID_ENCODING_DETECTED'
+        });
+    }
+    // Detect if decoding required multiple iterations (possible double-encoding attack)
+    const encodingAttackDetected = iterations > 1;
+    // Unicode normalization to handle overlong UTF-8 sequences
+    // e.g., %c0%ae (%c0%ae = UTF-8 overlong encoding for ".")
+    let normalized = decoded;
+    try {
+        normalized = decoded.normalize('NFC');
+    } catch (error) {
+    // Some paths may not be valid Unicode, continue with non-normalized version
+    }
+    // Check for null bytes (another common encoding attack vector)
+    if (normalized.includes('\0')) {
+        throw new PathValidationError('Path validation failed: null byte injection detected', {
+            originalInput,
+            decodedOutput: normalized,
+            reason: 'NULL_BYTE_INJECTION'
+        });
+    }
+    return {
+        decoded: normalized,
+        encoding: {
+            detected: encodingAttackDetected,
+            type: encodingAttackDetected ? 'double_encoding' : undefined,
+            originalInput,
+            decodedOutput: normalized,
+            iterationsRequired: iterations
+        }
+    };
+}
+/**
+ * Validate a file path to prevent directory traversal attacks
+ *
+ * Security checks performed (in order):
+ * 1. CRITICAL: Iteratively decode URL encoding to handle %252e%252e%252f and similar bypasses
+ * 2. CRITICAL: Normalize Unicode (NFC) to handle overlong UTF-8 like %c0%ae%c0%ae/
+ * 3. CRITICAL: Detect null bytes and excessive encoding layers
+ * 4. Check for home directory expansion ("~") on DECODED path
+ * 5. Normalize path to resolve ".." and "."
+ * 6. Verify all suspicious patterns are eliminated
+ * 7. Check if path is within base directory
+ * 8. Reject symlinks to prevent symlink attacks
+ * 9. Log any encoding attacks detected for security monitoring
+ *
+ * @param filePath - The file path to validate (may be encoded)
+ * @param baseDirectory - The base directory that file must reside within
+ * @returns PathValidationResult with validation details
+ * @throws PathValidationError if path validation fails or encoding attack detected
+ *
+ * @example
+ * const result = validatePath('docs/FEATURE.md', './.claude/skills');
+ * if (!result.valid) {
+ *   throw result; // Safe to throw, contains all context
+ * }
+ * // Use result.resolvedPath
+ *
+ * @security
+ * Designed to prevent:
+ * - Double-encoding bypasses: %252e%252e%252f
+ * - Overlong UTF-8: %c0%ae%c0%ae/
+ * - Mixed encoding: URL + Unicode combinations
+ * - Null byte injection: file.txt%00.jpg
+ * - Traditional path traversal: ../../../etc/passwd
+ */ export function validatePath(filePath, baseDirectory) {
+    // SECURITY FIX: Decode all encoding layers first before any path normalization
+    // This prevents double-encoding bypasses like %252e%252e%252f
+    const { decoded: decodedPath, encoding: pathEncoding } = decodePathSafely(filePath);
+    const { decoded: decodedBase } = decodePathSafely(baseDirectory);
+    // Log encoding attacks for security monitoring
+    if (pathEncoding.detected) {
+        // In production, this should trigger security alerts
+        console.warn('Security: Encoding attack detected in path input', {
+            originalInput: pathEncoding.originalInput,
+            decodedOutput: pathEncoding.decodedOutput,
+            iterationsRequired: pathEncoding.iterationsRequired
+        });
+    }
+    // Check for home directory expansion attempts on DECODED path
+    if (decodedPath.startsWith('~') || decodedPath.includes('/~') || decodedPath.includes('\\~')) {
+        throw new PathValidationError('Path validation failed: home directory access denied', {
+            filePath,
+            decodedPath,
+            baseDirectory,
+            reason: 'HOME_DIRECTORY_ACCESS'
+        });
+    }
+    // Check for home directory expansion attempts in baseDirectory
+    if (decodedBase.startsWith('~')) {
+        throw new PathValidationError('Base directory validation failed: home directory access denied', {
+            baseDirectory,
+            decodedBase,
+            reason: 'BASE_HOME_DIRECTORY_ACCESS'
+        });
+    }
+    // Normalize the base directory first
+    const normalizedBase = path.normalize(decodedBase);
+    const resolvedBase = path.resolve(normalizedBase);
+    // Normalize and resolve the file path relative to base
+    // NOW normalized on already-decoded path to prevent encoding bypasses
+    const normalizedPath = path.normalize(decodedPath);
+    // Check if path contains suspicious patterns after normalization
+    if (normalizedPath.includes('..') || normalizedPath === '.' || normalizedPath.includes('/./')) {
+        throw new PathValidationError('Path validation failed: path contains directory traversal patterns', {
+            filePath,
+            decodedPath,
+            normalizedPath,
+            baseDirectory,
+            reason: 'TRAVERSAL_PATTERN_DETECTED'
+        });
+    }
+    // Resolve the path relative to base directory
+    const resolvedPath = path.resolve(resolvedBase, normalizedPath);
+    // Check if resolved path is within base directory
+    const isWithinBase = isPathWithinBase(resolvedPath, resolvedBase);
+    if (!isWithinBase) {
+        throw new PathValidationError('Path validation failed: resolved path is outside allowed directory', {
+            filePath,
+            resolvedPath,
+            baseDirectory: resolvedBase,
+            reason: 'PATH_OUTSIDE_BASE'
+        });
+    }
+    // Check for symlinks (prevents symlink attacks)
+    let isSymlink = false;
+    try {
+        const stats = fs.lstatSync(resolvedPath);
+        isSymlink = stats.isSymbolicLink();
+        if (isSymlink) {
+            throw new PathValidationError('Path validation failed: symbolic links are not allowed', {
+                filePath,
+                resolvedPath,
+                reason: 'SYMLINK_NOT_ALLOWED'
+            });
+        }
+    } catch (error) {
+        // File doesn't exist yet (expected for validation before creation)
+        // or it's a symlink that was rejected above
+        if (error instanceof PathValidationError) {
+            throw error;
+        }
+    // Other errors (permission denied, etc.) are not path validation failures
+    // The file validation happens later
+    }
+    return {
+        valid: true,
+        resolvedPath,
+        normalizedPath,
+        isWithinBase: true,
+        isSymlink: false
+    };
+}
+/**
+ * Check if a path is within a base directory
+ *
+ * Uses path resolution and string comparison to ensure the resolved path
+ * is actually within the base directory (not just sharing a prefix).
+ *
+ * @param filePath - The path to check
+ * @param baseDirectory - The base directory
+ * @returns True if filePath is within baseDirectory
+ *
+ * @example
+ * isPathWithinBase('/home/user/project/src/file.ts', '/home/user/project')  // true
+ * isPathWithinBase('/home/user/project-evil/file.ts', '/home/user/project') // false
+ */ export function isPathWithinBase(filePath, baseDirectory) {
+    // Ensure both paths are normalized and absolute
+    const normalizedFile = path.normalize(path.resolve(filePath));
+    const normalizedBase = path.normalize(path.resolve(baseDirectory));
+    // Exact match
+    if (normalizedFile === normalizedBase) {
+        return true;
+    }
+    // Check if file is within base (use path.relative to ensure it's not going up)
+    const relative = path.relative(normalizedBase, normalizedFile);
+    // If relative path starts with "..", it's outside the base directory
+    if (relative.startsWith('..')) {
+        return false;
+    }
+    // If relative path is absolute, it's outside the base directory
+    if (path.isAbsolute(relative)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Validate multiple paths within the same base directory
+ *
+ * Efficiently validates multiple paths, returning results for each.
+ *
+ * @param filePaths - Array of file paths to validate
+ * @param baseDirectory - The base directory that all files must reside within
+ * @returns Map of file path to validation result
+ *
+ * @example
+ * const results = validatePaths(['docs/SKILL.md', 'src/index.ts'], './.claude/skills');
+ * results.forEach((result, filePath) => {
+ *   if (!result.valid) {
+ *     console.error(`Invalid path: ${filePath}`, result.reason);
+ *   }
+ * });
+ */ export function validatePaths(filePaths, baseDirectory) {
+    const results = new Map();
+    for (const filePath of filePaths){
+        try {
+            const result = validatePath(filePath, baseDirectory);
+            results.set(filePath, result);
+        } catch (error) {
+            if (error instanceof PathValidationError) {
+                results.set(filePath, {
+                    valid: false,
+                    resolvedPath: '',
+                    normalizedPath: '',
+                    isWithinBase: false,
+                    isSymlink: false,
+                    reason: error.context?.reason
+                });
+            } else {
+                throw error;
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Get the safe path for a file (or throw if validation fails)
+ *
+ * Convenience function that validates and returns the resolved path,
+ * or throws an error if validation fails.
+ *
+ * @param filePath - The file path to validate
+ * @param baseDirectory - The base directory that file must reside within
+ * @returns The resolved, validated absolute path
+ * @throws PathValidationError if path validation fails
+ *
+ * @example
+ * const safePath = getSafePath('docs/SKILL.md', './.claude/skills');
+ * fs.readFileSync(safePath); // Safe to use
+ */ export function getSafePath(filePath, baseDirectory) {
+    const result = validatePath(filePath, baseDirectory);
+    return result.resolvedPath;
+}
+/**
+ * Check if a path is considered safe for operations
+ *
+ * This is a non-throwing version of validatePath for conditional logic.
+ *
+ * @param filePath - The file path to check
+ * @param baseDirectory - The base directory
+ * @returns True if path is safe, false otherwise
+ *
+ * @example
+ * if (isPathSafe(userInput, './.claude/skills')) {
+ *   // Process the file
+ * } else {
+ *   // Reject the request
+ * }
+ */ export function isPathSafe(filePath, baseDirectory) {
+    try {
+        validatePath(filePath, baseDirectory);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Get validation error details for a path (if invalid)
+ *
+ * Useful for logging and diagnostics.
+ *
+ * @param filePath - The file path to validate
+ * @param baseDirectory - The base directory
+ * @returns Error with details, or undefined if path is valid
+ *
+ * @example
+ * const error = getPathValidationError('../../etc/passwd', './.claude/skills');
+ * if (error) {
+ *   logger.error(error.message, error.context);
+ * }
+ */ export function getPathValidationError(filePath, baseDirectory) {
+    try {
+        validatePath(filePath, baseDirectory);
+        return undefined;
+    } catch (error) {
+        if (error instanceof PathValidationError) {
+            return error;
+        }
+        throw error;
+    }
+}
+/**
+ * List allowed files within a base directory (safely)
+ *
+ * Recursively lists all files within base directory, validating
+ * each path to ensure it's within bounds.
+ *
+ * @param baseDirectory - The base directory to scan
+ * @param options - Options for listing (maxDepth, filter)
+ * @returns Array of validated, safe paths relative to baseDirectory
+ *
+ * @example
+ * const files = safeListDirectory('./.claude/skills');
+ * files.forEach(file => {
+ *   // All paths are guaranteed safe
+ *   console.log(file);
+ * });
+ */ export function safeListDirectory(baseDirectory, options) {
+    const safeFiles = [];
+    const maxDepth = options?.maxDepth ?? Infinity;
+    const filter = options?.filter ?? (()=>true);
+    function walkDirectory(dir, currentDepth = 0) {
+        if (currentDepth > maxDepth) {
+            return;
+        }
+        try {
+            const entries = fs.readdirSync(dir, {
+                withFileTypes: true
+            });
+            for (const entry of entries){
+                const fullPath = path.join(dir, entry.name);
+                const relativePath = path.relative(baseDirectory, fullPath);
+                // Validate the path is still within base
+                if (!isPathWithinBase(fullPath, baseDirectory)) {
+                    continue;
+                }
+                // Apply filter
+                if (!filter(relativePath)) {
+                    continue;
+                }
+                safeFiles.push(relativePath);
+                // Recursively walk directories
+                if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                    walkDirectory(fullPath, currentDepth + 1);
+                }
+            }
+        } catch (error) {
+        // Silently skip directories we can't read (permission denied, etc.)
+        }
+    }
+    walkDirectory(baseDirectory);
+    return safeFiles;
+}
+
+//# sourceMappingURL=path-validator.js.map

package/dist/lib/path-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/path-validator.ts"],"sourcesContent":["/**\r\n * Path Validator - Security Utility for Safe File Operations\r\n *\r\n * Provides robust path sanitization and validation to prevent path traversal attacks (CVSS 7.0+).\r\n * Enforces strict rules on file access with protection against encoding attacks:\r\n *\r\n * CRITICAL FIXES (CVSS 7.0+):\r\n * - Iterative URL decoding prevents double-encoding bypasses (%252e%252e%252f → ../)\r\n * - Unicode normalization (NFC) prevents overlong UTF-8 bypasses (%c0%ae → .)\r\n * - Null byte detection prevents null injection attacks\r\n * - All decoding performed BEFORE path normalization to prevent layered attacks\r\n * - Encoding attack detection with security logging\r\n *\r\n * Base Security Controls:\r\n * - Path normalization to resolve \"..\" and \".\" sequences\r\n * - Validation that resolved paths stay within allowed directories\r\n * - Detection and rejection of symlinks\r\n * - Rejection of absolute paths outside allowed directories\r\n * - Prevention of home directory access (\"~\")\r\n *\r\n * @module path-validator\r\n * @version 2.0.0 (SECURITY CRITICAL)\r\n */\r\n\r\nimport * as path from 'path';\r\nimport * as fs from 'fs';\r\nimport { StandardError } from './errors';\r\n\r\n/**\r\n * Path validation error - thrown when a path violates security constraints\r\n */\r\nexport class PathValidationError extends StandardError {\r\n  constructor(message: string, context?: Record<string, unknown>) {\r\n    super('PATH_VALIDATION_ERROR', message, context);\r\n    this.name = 'PathValidationError';\r\n  }\r\n}\r\n\r\n/**\r\n * Security encoding attack detection\r\n */\r\nexport interface EncodingAttackDetection {\r\n  detected: boolean;\r\n  type?: 'double_encoding' | 'unicode_encoding' | 'mixed_encoding';\r\n  originalInput: string;\r\n  decodedOutput: string;\r\n  iterationsRequired: number;\r\n}\r\n\r\n/**\r\n * Path validation result with detailed information\r\n */\r\nexport interface PathValidationResult {\r\n  valid: boolean;\r\n  resolvedPath: string;\r\n  normalizedPath: string;\r\n  isWithinBase: boolean;\r\n  isSymlink: boolean;\r\n  reason?: string;\r\n}\r\n\r\n/**\r\n * Safely decode a path with protection against encoding attacks\r\n *\r\n * Performs iterative URL decoding and Unicode normalization to prevent:\r\n * - Double encoding bypass (e.g., %252e%252e%252f → %2e%2e%2f → ../)\r\n * - Overlong UTF-8 encoding (e.g., %c0%ae%c0%ae/ → ../)\r\n * - Mixed encoding attacks\r\n *\r\n * @param inputPath - The potentially encoded path\r\n * @returns Decoded path and attack detection info\r\n * @throws PathValidationError if encoding attack detected\r\n *\r\n * @example\r\n * const { decoded, encoding } = decodePathSafely('%252e%252e%252f');\r\n * // Detects double-encoding attempt\r\n */\r\nfunction decodePathSafely(inputPath: string): {\r\n  decoded: string;\r\n  encoding: EncodingAttackDetection;\r\n} {\r\n  let decoded = inputPath;\r\n  let previous = '';\r\n  let iterations = 0;\r\n  const MAX_ITERATIONS = 5;\r\n  const originalInput = inputPath;\r\n  let invalidEncodingDetected = false;\r\n\r\n  // Iteratively decode URL-encoded characters until stable\r\n  // This prevents bypass attacks using multiple encoding layers\r\n  while (decoded !== previous && iterations < MAX_ITERATIONS) {\r\n    previous = decoded;\r\n    try {\r\n      decoded = decodeURIComponent(decoded);\r\n    } catch (error) {\r\n      // Invalid URL encoding (including malformed UTF-8) indicates attack\r\n      // e.g., %c0%ae is malformed UTF-8 for overlong encoding\r\n      invalidEncodingDetected = true;\r\n      // Treat invalid encoding as a suspicious attack indicator\r\n      // but continue with the path as-is for analysis\r\n      break;\r\n    }\r\n    iterations++;\r\n  }\r\n\r\n  // Check if we hit max iterations (indicates potential encoding attack)\r\n  if (iterations >= MAX_ITERATIONS && decoded !== previous) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: excessive encoding layers detected',\r\n      {\r\n        originalInput,\r\n        decodedOutput: decoded,\r\n        iterations,\r\n        reason: 'ENCODING_ATTACK_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Invalid encoding like malformed UTF-8 is itself an attack indicator\r\n  if (invalidEncodingDetected) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: invalid encoding detected (possible encoding attack)',\r\n      {\r\n        originalInput,\r\n        decodedOutput: decoded,\r\n        iterations,\r\n        reason: 'INVALID_ENCODING_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Detect if decoding required multiple iterations (possible double-encoding attack)\r\n  const encodingAttackDetected = iterations > 1;\r\n\r\n  // Unicode normalization to handle overlong UTF-8 sequences\r\n  // e.g., %c0%ae (%c0%ae = UTF-8 overlong encoding for \".\")\r\n  let normalized = decoded;\r\n  try {\r\n    normalized = decoded.normalize('NFC');\r\n  } catch (error) {\r\n    // Some paths may not be valid Unicode, continue with non-normalized version\r\n  }\r\n\r\n  // Check for null bytes (another common encoding attack vector)\r\n  if (normalized.includes('\\0')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: null byte injection detected',\r\n      {\r\n        originalInput,\r\n        decodedOutput: normalized,\r\n        reason: 'NULL_BYTE_INJECTION',\r\n      }\r\n    );\r\n  }\r\n\r\n  return {\r\n    decoded: normalized,\r\n    encoding: {\r\n      detected: encodingAttackDetected,\r\n      type: encodingAttackDetected ? 'double_encoding' : undefined,\r\n      originalInput,\r\n      decodedOutput: normalized,\r\n      iterationsRequired: iterations,\r\n    },\r\n  };\r\n}\r\n\r\n/**\r\n * Validate a file path to prevent directory traversal attacks\r\n *\r\n * Security checks performed (in order):\r\n * 1. CRITICAL: Iteratively decode URL encoding to handle %252e%252e%252f and similar bypasses\r\n * 2. CRITICAL: Normalize Unicode (NFC) to handle overlong UTF-8 like %c0%ae%c0%ae/\r\n * 3. CRITICAL: Detect null bytes and excessive encoding layers\r\n * 4. Check for home directory expansion (\"~\") on DECODED path\r\n * 5. Normalize path to resolve \"..\" and \".\"\r\n * 6. Verify all suspicious patterns are eliminated\r\n * 7. Check if path is within base directory\r\n * 8. Reject symlinks to prevent symlink attacks\r\n * 9. Log any encoding attacks detected for security monitoring\r\n *\r\n * @param filePath - The file path to validate (may be encoded)\r\n * @param baseDirectory - The base directory that file must reside within\r\n * @returns PathValidationResult with validation details\r\n * @throws PathValidationError if path validation fails or encoding attack detected\r\n *\r\n * @example\r\n * const result = validatePath('docs/FEATURE.md', './.claude/skills');\r\n * if (!result.valid) {\r\n *   throw result; // Safe to throw, contains all context\r\n * }\r\n * // Use result.resolvedPath\r\n *\r\n * @security\r\n * Designed to prevent:\r\n * - Double-encoding bypasses: %252e%252e%252f\r\n * - Overlong UTF-8: %c0%ae%c0%ae/\r\n * - Mixed encoding: URL + Unicode combinations\r\n * - Null byte injection: file.txt%00.jpg\r\n * - Traditional path traversal: ../../../etc/passwd\r\n */\r\nexport function validatePath(filePath: string, baseDirectory: string): PathValidationResult {\r\n  // SECURITY FIX: Decode all encoding layers first before any path normalization\r\n  // This prevents double-encoding bypasses like %252e%252e%252f\r\n  const { decoded: decodedPath, encoding: pathEncoding } = decodePathSafely(filePath);\r\n  const { decoded: decodedBase } = decodePathSafely(baseDirectory);\r\n\r\n  // Log encoding attacks for security monitoring\r\n  if (pathEncoding.detected) {\r\n    // In production, this should trigger security alerts\r\n    console.warn('Security: Encoding attack detected in path input', {\r\n      originalInput: pathEncoding.originalInput,\r\n      decodedOutput: pathEncoding.decodedOutput,\r\n      iterationsRequired: pathEncoding.iterationsRequired,\r\n    });\r\n  }\r\n\r\n  // Check for home directory expansion attempts on DECODED path\r\n  if (decodedPath.startsWith('~') || decodedPath.includes('/~') || decodedPath.includes('\\\\~')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: home directory access denied',\r\n      {\r\n        filePath,\r\n        decodedPath,\r\n        baseDirectory,\r\n        reason: 'HOME_DIRECTORY_ACCESS',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Check for home directory expansion attempts in baseDirectory\r\n  if (decodedBase.startsWith('~')) {\r\n    throw new PathValidationError(\r\n      'Base directory validation failed: home directory access denied',\r\n      {\r\n        baseDirectory,\r\n        decodedBase,\r\n        reason: 'BASE_HOME_DIRECTORY_ACCESS',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Normalize the base directory first\r\n  const normalizedBase = path.normalize(decodedBase);\r\n  const resolvedBase = path.resolve(normalizedBase);\r\n\r\n  // Normalize and resolve the file path relative to base\r\n  // NOW normalized on already-decoded path to prevent encoding bypasses\r\n  const normalizedPath = path.normalize(decodedPath);\r\n\r\n  // Check if path contains suspicious patterns after normalization\r\n  if (normalizedPath.includes('..') || normalizedPath === '.' || normalizedPath.includes('/./')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: path contains directory traversal patterns',\r\n      {\r\n        filePath,\r\n        decodedPath,\r\n        normalizedPath,\r\n        baseDirectory,\r\n        reason: 'TRAVERSAL_PATTERN_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Resolve the path relative to base directory\r\n  const resolvedPath = path.resolve(resolvedBase, normalizedPath);\r\n\r\n  // Check if resolved path is within base directory\r\n  const isWithinBase = isPathWithinBase(resolvedPath, resolvedBase);\r\n\r\n  if (!isWithinBase) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: resolved path is outside allowed directory',\r\n      {\r\n        filePath,\r\n        resolvedPath,\r\n        baseDirectory: resolvedBase,\r\n        reason: 'PATH_OUTSIDE_BASE',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Check for symlinks (prevents symlink attacks)\r\n  let isSymlink = false;\r\n  try {\r\n    const stats = fs.lstatSync(resolvedPath);\r\n    isSymlink = stats.isSymbolicLink();\r\n\r\n    if (isSymlink) {\r\n      throw new PathValidationError(\r\n        'Path validation failed: symbolic links are not allowed',\r\n        {\r\n          filePath,\r\n          resolvedPath,\r\n          reason: 'SYMLINK_NOT_ALLOWED',\r\n        }\r\n      );\r\n    }\r\n  } catch (error) {\r\n    // File doesn't exist yet (expected for validation before creation)\r\n    // or it's a symlink that was rejected above\r\n    if (error instanceof PathValidationError) {\r\n      throw error;\r\n    }\r\n    // Other errors (permission denied, etc.) are not path validation failures\r\n    // The file validation happens later\r\n  }\r\n\r\n  return {\r\n    valid: true,\r\n    resolvedPath,\r\n    normalizedPath,\r\n    isWithinBase: true,\r\n    isSymlink: false,\r\n  };\r\n}\r\n\r\n/**\r\n * Check if a path is within a base directory\r\n *\r\n * Uses path resolution and string comparison to ensure the resolved path\r\n * is actually within the base directory (not just sharing a prefix).\r\n *\r\n * @param filePath - The path to check\r\n * @param baseDirectory - The base directory\r\n * @returns True if filePath is within baseDirectory\r\n *\r\n * @example\r\n * isPathWithinBase('/home/user/project/src/file.ts', '/home/user/project')  // true\r\n * isPathWithinBase('/home/user/project-evil/file.ts', '/home/user/project') // false\r\n */\r\nexport function isPathWithinBase(filePath: string, baseDirectory: string): boolean {\r\n  // Ensure both paths are normalized and absolute\r\n  const normalizedFile = path.normalize(path.resolve(filePath));\r\n  const normalizedBase = path.normalize(path.resolve(baseDirectory));\r\n\r\n  // Exact match\r\n  if (normalizedFile === normalizedBase) {\r\n    return true;\r\n  }\r\n\r\n  // Check if file is within base (use path.relative to ensure it's not going up)\r\n  const relative = path.relative(normalizedBase, normalizedFile);\r\n\r\n  // If relative path starts with \"..\", it's outside the base directory\r\n  if (relative.startsWith('..')) {\r\n    return false;\r\n  }\r\n\r\n  // If relative path is absolute, it's outside the base directory\r\n  if (path.isAbsolute(relative)) {\r\n    return false;\r\n  }\r\n\r\n  return true;\r\n}\r\n\r\n/**\r\n * Validate multiple paths within the same base directory\r\n *\r\n * Efficiently validates multiple paths, returning results for each.\r\n *\r\n * @param filePaths - Array of file paths to validate\r\n * @param baseDirectory - The base directory that all files must reside within\r\n * @returns Map of file path to validation result\r\n *\r\n * @example\r\n * const results = validatePaths(['docs/SKILL.md', 'src/index.ts'], './.claude/skills');\r\n * results.forEach((result, filePath) => {\r\n *   if (!result.valid) {\r\n *     console.error(`Invalid path: ${filePath}`, result.reason);\r\n *   }\r\n * });\r\n */\r\nexport function validatePaths(\r\n  filePaths: string[],\r\n  baseDirectory: string\r\n): Map<string, PathValidationResult> {\r\n  const results = new Map<string, PathValidationResult>();\r\n\r\n  for (const filePath of filePaths) {\r\n    try {\r\n      const result = validatePath(filePath, baseDirectory);\r\n      results.set(filePath, result);\r\n    } catch (error) {\r\n      if (error instanceof PathValidationError) {\r\n        results.set(filePath, {\r\n          valid: false,\r\n          resolvedPath: '',\r\n          normalizedPath: '',\r\n          isWithinBase: false,\r\n          isSymlink: false,\r\n          reason: error.context?.reason as string | undefined,\r\n        });\r\n      } else {\r\n        throw error;\r\n      }\r\n    }\r\n  }\r\n\r\n  return results;\r\n}\r\n\r\n/**\r\n * Get the safe path for a file (or throw if validation fails)\r\n *\r\n * Convenience function that validates and returns the resolved path,\r\n * or throws an error if validation fails.\r\n *\r\n * @param filePath - The file path to validate\r\n * @param baseDirectory - The base directory that file must reside within\r\n * @returns The resolved, validated absolute path\r\n * @throws PathValidationError if path validation fails\r\n *\r\n * @example\r\n * const safePath = getSafePath('docs/SKILL.md', './.claude/skills');\r\n * fs.readFileSync(safePath); // Safe to use\r\n */\r\nexport function getSafePath(filePath: string, baseDirectory: string): string {\r\n  const result = validatePath(filePath, baseDirectory);\r\n  return result.resolvedPath;\r\n}\r\n\r\n/**\r\n * Check if a path is considered safe for operations\r\n *\r\n * This is a non-throwing version of validatePath for conditional logic.\r\n *\r\n * @param filePath - The file path to check\r\n * @param baseDirectory - The base directory\r\n * @returns True if path is safe, false otherwise\r\n *\r\n * @example\r\n * if (isPathSafe(userInput, './.claude/skills')) {\r\n *   // Process the file\r\n * } else {\r\n *   // Reject the request\r\n * }\r\n */\r\nexport function isPathSafe(filePath: string, baseDirectory: string): boolean {\r\n  try {\r\n    validatePath(filePath, baseDirectory);\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Get validation error details for a path (if invalid)\r\n *\r\n * Useful for logging and diagnostics.\r\n *\r\n * @param filePath - The file path to validate\r\n * @param baseDirectory - The base directory\r\n * @returns Error with details, or undefined if path is valid\r\n *\r\n * @example\r\n * const error = getPathValidationError('../../etc/passwd', './.claude/skills');\r\n * if (error) {\r\n *   logger.error(error.message, error.context);\r\n * }\r\n */\r\nexport function getPathValidationError(\r\n  filePath: string,\r\n  baseDirectory: string\r\n): PathValidationError | undefined {\r\n  try {\r\n    validatePath(filePath, baseDirectory);\r\n    return undefined;\r\n  } catch (error) {\r\n    if (error instanceof PathValidationError) {\r\n      return error;\r\n    }\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * List allowed files within a base directory (safely)\r\n *\r\n * Recursively lists all files within base directory, validating\r\n * each path to ensure it's within bounds.\r\n *\r\n * @param baseDirectory - The base directory to scan\r\n * @param options - Options for listing (maxDepth, filter)\r\n * @returns Array of validated, safe paths relative to baseDirectory\r\n *\r\n * @example\r\n * const files = safeListDirectory('./.claude/skills');\r\n * files.forEach(file => {\r\n *   // All paths are guaranteed safe\r\n *   console.log(file);\r\n * });\r\n */\r\nexport function safeListDirectory(\r\n  baseDirectory: string,\r\n  options?: {\r\n    maxDepth?: number;\r\n    filter?: (path: string) => boolean;\r\n  }\r\n): string[] {\r\n  const safeFiles: string[] = [];\r\n  const maxDepth = options?.maxDepth ?? Infinity;\r\n  const filter = options?.filter ?? (() => true);\r\n\r\n  function walkDirectory(dir: string, currentDepth: number = 0): void {\r\n    if (currentDepth > maxDepth) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const entries = fs.readdirSync(dir, { withFileTypes: true });\r\n\r\n      for (const entry of entries) {\r\n        const fullPath = path.join(dir, entry.name);\r\n        const relativePath = path.relative(baseDirectory, fullPath);\r\n\r\n        // Validate the path is still within base\r\n        if (!isPathWithinBase(fullPath, baseDirectory)) {\r\n          continue;\r\n        }\r\n\r\n        // Apply filter\r\n        if (!filter(relativePath)) {\r\n          continue;\r\n        }\r\n\r\n        safeFiles.push(relativePath);\r\n\r\n        // Recursively walk directories\r\n        if (entry.isDirectory() && !entry.isSymbolicLink()) {\r\n          walkDirectory(fullPath, currentDepth + 1);\r\n        }\r\n      }\r\n    } catch (error) {\r\n      // Silently skip directories we can't read (permission denied, etc.)\r\n    }\r\n  }\r\n\r\n  walkDirectory(baseDirectory);\r\n  return safeFiles;\r\n}\r\n"],"names":["path","fs","StandardError","PathValidationError","message","context","name","decodePathSafely","inputPath","decoded","previous","iterations","MAX_ITERATIONS","originalInput","invalidEncodingDetected","decodeURIComponent","error","decodedOutput","reason","encodingAttackDetected","normalized","normalize","includes","encoding","detected","type","undefined","iterationsRequired","validatePath","filePath","baseDirectory","decodedPath","pathEncoding","decodedBase","console","warn","startsWith","normalizedBase","resolvedBase","resolve","normalizedPath","resolvedPath","isWithinBase","isPathWithinBase","isSymlink","stats","lstatSync","isSymbolicLink","valid","normalizedFile","relative","isAbsolute","validatePaths","filePaths","results","Map","result","set","getSafePath","isPathSafe","getPathValidationError","safeListDirectory","options","safeFiles","maxDepth","Infinity","filter","walkDirectory","dir","currentDepth","entries","readdirSync","withFileTypes","entry","fullPath","join","relativePath","push","isDirectory"],"mappings":"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"}