indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/helpers/path-validator.js

@@ -1,895 +0,0 @@
-/**
- * @fileoverview Path Validation and Normalization Utilities
- *
- * **SECURITY FOCUSED**: This module provides secure path handling to prevent
- * common path traversal and directory escape vulnerabilities.
- *
- * Common Path Vulnerabilities Addressed:
- * - Directory traversal (../../) attacks
- * - Symlink following (TOCTOU - Time-of-Check-Time-of-Use)
- * - Path normalization bypasses
- * - Null byte injection (\0)
- * - Mixed slash handling (Windows vs Unix)
- * - Relative path escape patterns
- *
- * SECURITY PRINCIPLES:
- * 1. Always validate and normalize paths before file operations
- * 2. Prevent directory traversal with ".." and "." resolution
- * 3. Resolve symlinks to detect jail breaks
- * 4. Whitelist allowed directories when possible
- * 5. Never trust user-supplied paths directly
- *
- * This module provides type-safe, well-tested functions for:
- * - Path safety validation and sanitization
- * - Secure path resolution and normalization
- * - Path component extraction
- * - Cross-platform path handling
- * - Symlink and traversal detection
- *
- * @example
- * // SAFE: Validate before use
- * if (isPathSafe(userPath, baseDir)) {
- *   const fullPath = joinSafe(baseDir, userPath);
- *   // Safe to use fullPath
- * }
- *
- * @example
- * // UNSAFE: Direct concatenation - vulnerable to path traversal
- * const fullPath = baseDir + '/' + userPath; // DON'T DO THIS
- *
- * @example
- * // SAFE: Use validation helpers
- * validatePath(userPath, { allowRelative: true, base: '/app/uploads' });
- * const dir = getDirName(path);
- * const name = getFileName(path);
- */
-import * as fs from 'fs';
-import * as path from 'path';
-/**
- * SECURITY: Checks if a path is safe for operations
- *
- * This is the primary security function - use before ANY file operation.
- * Prevents:
- * - Directory traversal (../../etc/passwd)
- * - Absolute path bypass
- * - Symlink attacks
- * - Path normalization bypass
- *
- * @param pathStr - Path to validate
- * @param baseDir - Optional base directory for restriction
- * @returns true if path is safe, false otherwise
- *
- * @example
- * // SAFE: Check user-supplied path
- * const userInput = req.query.file;
- * if (isPathSafe(userInput, '/app/uploads')) {
- *   const fullPath = path.join('/app/uploads', userInput);
- *   const data = fs.readFileSync(fullPath); // Safe
- * }
- *
- * @example
- * // UNSAFE: Allows directory traversal
- * const fullPath = path.join('/app/uploads', userInput); // DON'T - no validation
- * const data = fs.readFileSync(fullPath);
- *
- * @example
- * // UNSAFE PATHS (returns false)
- * isPathSafe('../../../etc/passwd') // true -> prevents escape
- * isPathSafe('/etc/passwd', '/app') // false -> absolute outside base
- * isPathSafe('../../file.txt') // false -> traversal attempt
- * isPathSafe('./file.txt', '/app') // true -> safe relative
- *
- * @edge-cases
- * - Empty path returns true (cwd)
- * - Resolves .. but only within base directory
- * - Strips null bytes (\0) - potential injection
- * - Windows paths with backslashes normalized to forward slashes
- *
- * @security-notes
- * - Use this function BEFORE every file operation with user input
- * - Does NOT check file existence
- * - For maximum security, use with baseDir parameter
- * - Be aware of TOCTOU: file can change between check and use
- */
-export function isPathSafe(pathStr, baseDir) {
-    try {
-        // Reject null bytes (common injection vector)
-        if (pathStr.includes('\0')) {
-            return false;
-        }
-        // Reject empty absolute paths when base is specified
-        if (baseDir && path.isAbsolute(pathStr)) {
-            return false;
-        }
-        // Normalize the path
-        let normalized = normalizePath(pathStr);
-        // If no base, only allow relative paths that don't escape
-        if (!baseDir) {
-            if (path.isAbsolute(normalized)) {
-                return false;
-            }
-            // Check that the normalized path doesn't start with ..
-            if (normalized.startsWith('..') || normalized.startsWith('../')) {
-                return false;
-            }
-            return true;
-        }
-        // Resolve within the base directory
-        const baseDirResolved = path.resolve(baseDir);
-        const fullPath = path.resolve(baseDirResolved, normalized);
-        // Check that resolved path is within base directory
-        const relativePath = path.relative(baseDirResolved, fullPath);
-        // Relative path should not start with ".." to be safe
-        if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
-            return false;
-        }
-        return true;
-    }
-    catch (error) {
-        return false;
-    }
-}
-/**
- * SECURITY: Comprehensive path validation with detailed results
- *
- * Use this for detailed validation and error reporting.
- * Returns structured result with specific error information.
- *
- * @param pathStr - Path to validate
- * @param options - Validation options
- * @returns Detailed validation result
- *
- * @example
- * // Validate with full options
- * const result = validatePath(userPath, {
- *   base: '/app/uploads',
- *   allowRelative: true,
- *   allowSymlinks: false,
- *   maxLength: 255,
- * });
- *
- * if (!result.valid) {
- *   console.error(result.error);
- *   // Reject the request
- * }
- *
- * @example
- * // Check for symlinks and traversal
- * const result = validatePath('../../secret.txt', {
- *   base: '/app/data',
- *   allowSymlinks: false,
- * });
- * // result.valid === false
- * // result.error mentions directory traversal
- *
- * @edge-cases
- * - Symlink detection requires filesystem access
- * - May be expensive for deeply nested paths
- * - Resolved path is provided even if invalid (for debugging)
- */
-export function validatePath(pathStr, options = {}) {
-    const { base, allowRelative = false, allowSymlinks = false, allowHidden = false, maxLength = 4096, } = options;
-    try {
-        // Check length
-        if (pathStr.length === 0) {
-            return {
-                valid: false,
-                error: 'Path cannot be empty',
-            };
-        }
-        if (pathStr.length > maxLength) {
-            return {
-                valid: false,
-                error: `Path exceeds maximum length of ${maxLength} characters`,
-            };
-        }
-        // Check for null bytes
-        if (pathStr.includes('\0')) {
-            return {
-                valid: false,
-                error: 'Path contains null bytes (potential injection)',
-            };
-        }
-        // Normalize path
-        let normalized = normalizePath(pathStr);
-        // Check for hidden files (but not . or .. which are navigation)
-        if (!allowHidden) {
-            const components = normalized.split('/').filter(c => c);
-            const hasHidden = components.some(c => c.startsWith('.') && c !== '.' && c !== '..');
-            if (hasHidden) {
-                return {
-                    valid: false,
-                    error: 'Path contains hidden files (starting with .)',
-                };
-            }
-        }
-        // Check if absolute
-        const isAbsolute = path.isAbsolute(normalized);
-        if (isAbsolute && !base) {
-            return {
-                valid: false,
-                error: 'Absolute paths not allowed without a base directory',
-            };
-        }
-        if (isAbsolute && base) {
-            return {
-                valid: false,
-                error: 'Absolute paths not allowed when base directory is specified',
-            };
-        }
-        if (!isAbsolute && !allowRelative && !base) {
-            return {
-                valid: false,
-                error: 'Relative paths not allowed',
-            };
-        }
-        // If base is provided, resolve and check containment
-        let resolved = normalized;
-        let isWithinBase = true;
-        if (base) {
-            const baseDirResolved = path.resolve(base);
-            resolved = path.resolve(baseDirResolved, normalized);
-            const relativePath = path.relative(baseDirResolved, resolved);
-            if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
-                return {
-                    valid: false,
-                    error: 'Path attempts to escape base directory (directory traversal)',
-                    resolved,
-                    isWithinBase: false,
-                };
-            }
-        }
-        // Check for symlinks
-        let hasSymlinks = false;
-        if (!allowSymlinks && base) {
-            const baseDirResolved = path.resolve(base);
-            const components = normalized.split('/').filter(c => c);
-            let currentPath = baseDirResolved;
-            for (const component of components) {
-                currentPath = path.join(currentPath, component);
-                try {
-                    const stat = fs.lstatSync(currentPath);
-                    if (stat.isSymbolicLink()) {
-                        hasSymlinks = true;
-                        break;
-                    }
-                }
-                catch (err) {
-                    // File doesn't exist yet, continue
-                }
-            }
-            if (hasSymlinks) {
-                return {
-                    valid: false,
-                    error: 'Path contains symbolic links (not allowed)',
-                    resolved,
-                    hasSymlinks: true,
-                    isWithinBase,
-                };
-            }
-        }
-        return {
-            valid: true,
-            resolved,
-            hasSymlinks,
-            isWithinBase,
-        };
-    }
-    catch (error) {
-        return {
-            valid: false,
-            error: `Validation error: ${error instanceof Error ? error.message : 'unknown'}`,
-        };
-    }
-}
-/**
- * SECURITY: Normalizes a path to prevent traversal bypass
- *
- * Removes redundant separators and resolves . and .. patterns.
- * Critical for preventing normalized path bypass attacks.
- *
- * @param pathStr - Path to normalize
- * @returns Normalized path
- *
- * @example
- * normalizePath('./foo/../bar') // "bar"
- * normalizePath('foo//bar') // "foo/bar"
- * normalizePath('foo/./bar') // "foo/bar"
- * normalizePath('\\foo\\bar') // "foo/bar" (Windows)
- * normalizePath('') // "."
- * normalizePath('/absolute/./path') // "/absolute/path"
- * normalizePath('foo/../../bar') // "../bar"
- *
- * @edge-cases
- * - Normalizes both forward and backslashes (Windows/Unix)
- * - Preserves absolute path status
- * - Collapses .. patterns (may escape if outside boundary)
- * - Use isPathSafe() to prevent escape with .. patterns
- *
- * @security-notes
- * - This ALONE doesn't prevent attacks
- * - Use with isPathSafe() for full protection
- * - Directory traversal requires checking against base dir
- */
-export function normalizePath(pathStr) {
-    if (!pathStr)
-        return '.';
-    // Remove null bytes
-    let normalized = pathStr.replace(/\0/g, '');
-    // Normalize slashes (handle Windows backslashes)
-    normalized = normalized.replace(/\\/g, '/');
-    // Remove duplicate slashes
-    normalized = normalized.replace(/\/+/g, '/');
-    // Resolve . and ..
-    normalized = path.normalize(normalized);
-    // Convert back to forward slashes for consistency
-    normalized = normalized.replace(/\\/g, '/');
-    return normalized;
-}
-/**
- * SECURITY: Safely joins path segments with base directory
- *
- * Validates each segment against directory traversal before joining.
- * Preferred over path.join() for security-sensitive code.
- *
- * @param base - Base directory (absolute path)
- * @param ...segments - Path segments to join
- * @returns Safely joined path, or throws if unsafe
- *
- * @example
- * // SAFE: Returns '/app/uploads/user-file.txt'
- * joinSafe('/app/uploads', 'user-file.txt')
- *
- * @example
- * // UNSAFE: Throws error
- * try {
- *   joinSafe('/app/uploads', '../../etc/passwd')
- * } catch (e) {
- *   console.log('Traversal attempt blocked')
- * }
- *
- * @example
- * // SAFE: Multiple segments
- * joinSafe('/app', 'uploads', 'users', 'file.txt')
- * // -> '/app/uploads/users/file.txt'
- *
- * @example
- * // UNSAFE: Symlink in path (if allowSymlinks: false)
- * joinSafe('/app', './link-to-escape')
- * // throws if link escapes /app
- *
- * @throws Error if any segment is unsafe for the given base
- *
- * @security-notes
- * - Base directory must be absolute
- * - Each segment is validated independently
- * - Throws on traversal attempts (fail-safe)
- * - Suitable for file server implementations
- */
-export function joinSafe(base, ...segments) {
-    if (!path.isAbsolute(base)) {
-        throw new Error('Base directory must be absolute');
-    }
-    let current = path.resolve(base);
-    for (const segment of segments) {
-        // Validate segment
-        if (!isPathSafe(segment, current)) {
-            throw new Error(`Unsafe path segment: ${segment}`);
-        }
-        // Safely resolve
-        current = path.resolve(current, normalizePath(segment));
-        // Verify we haven't escaped the base
-        const baseResolved = path.resolve(base);
-        const relative = path.relative(baseResolved, current);
-        if (relative.startsWith('..')) {
-            throw new Error(`Path segment escapes base directory: ${segment}`);
-        }
-    }
-    return current;
-}
-/**
- * SECURITY: Resolves a path safely relative to a base directory
- *
- * Like joinSafe but returns resolved path. Better for cases
- * where the target path must be within base (sandboxing).
- *
- * @param pathStr - Path to resolve
- * @param baseDir - Base directory for restriction
- * @returns Resolved absolute path
- *
- * @example
- * resolvePath('uploads/file.txt', '/app')
- * // -> '/app/uploads/file.txt'
- *
- * @example
- * // Throws: attempts escape
- * resolvePath('../../etc/passwd', '/app')
- *
- * @throws Error if path attempts to escape base directory
- *
- * @security-notes
- * - For sandboxing / jail implementations
- * - Always validate user input
- * - Return error, don't expose real paths
- */
-export function resolvePath(pathStr, baseDir) {
-    const baseResolved = path.resolve(baseDir);
-    if (!isPathSafe(pathStr, baseResolved)) {
-        throw new Error(`Path is not safe: ${pathStr}`);
-    }
-    const resolved = path.resolve(baseResolved, normalizePath(pathStr));
-    // Final verification
-    const relative = path.relative(baseResolved, resolved);
-    if (relative.startsWith('..')) {
-        throw new Error('Resolved path escapes base directory');
-    }
-    return resolved;
-}
-/**
- * Returns whether a path is absolute (not relative)
- *
- * Works consistently across Windows and Unix.
- *
- * @param pathStr - Path to check
- * @returns true if absolute, false if relative
- *
- * @example
- * isAbsolutePath('/home/user') // true
- * isAbsolutePath('C:\\Users\\User') // true (Windows)
- * isAbsolutePath('./relative') // false
- * isAbsolutePath('relative/path') // false
- * isAbsolutePath('') // false
- *
- * @edge-cases
- * - Windows drive letters (C:\) are absolute
- * - UNC paths (\\server\share) are absolute
- * - Relative paths with ./ prefix are still relative
- */
-export function isAbsolutePath(pathStr) {
-    if (!pathStr)
-        return false;
-    // Check for Unix absolute paths
-    if (path.isAbsolute(pathStr)) {
-        return true;
-    }
-    // Check for Windows absolute paths (e.g., C:\, D:\)
-    // This handles Windows paths when running on Unix systems
-    if (/^[a-zA-Z]:[/\\]/.test(pathStr)) {
-        return true;
-    }
-    // Check for UNC paths (\\server\share)
-    if (/^\\\\[^\\]+\\/.test(pathStr)) {
-        return true;
-    }
-    return false;
-}
-/**
- * Returns whether a path is relative (not absolute)
- *
- * Inverse of isAbsolutePath.
- *
- * @param pathStr - Path to check
- * @returns true if relative, false if absolute
- *
- * @example
- * isRelativePath('./file') // true
- * isRelativePath('file.txt') // true
- * isRelativePath('dir/file') // true
- * isRelativePath('/absolute') // false
- * isRelativePath('') // true
- *
- * @edge-cases
- * - Relative paths may escape with .. patterns
- * - Empty string is technically relative
- */
-export function isRelativePath(pathStr) {
-    return !isAbsolutePath(pathStr);
-}
-/**
- * Extracts the file name from a path (including extension)
- *
- * Safe extraction of filename from path.
- *
- * @param pathStr - Full path
- * @returns File name without directory
- *
- * @example
- * getFileName('/home/user/file.txt') // "file.txt"
- * getFileName('file.txt') // "file.txt"
- * getFileName('/home/user/') // "" (directory path)
- * getFileName('/home/user/doc.tar.gz') // "doc.tar.gz"
- * getFileName('') // ""
- * getFileName('.gitignore') // ".gitignore"
- *
- * @edge-cases
- * - Returns empty string for directory paths
- * - Preserves multiple extensions
- */
-export function getFileName(pathStr) {
-    if (!pathStr)
-        return '';
-    return path.basename(pathStr);
-}
-/**
- * Extracts the directory path without the file name
- *
- * Returns the directory containing the file.
- *
- * @param pathStr - Full path
- * @returns Directory path
- *
- * @example
- * getDirName('/home/user/file.txt') // "/home/user"
- * getDirName('file.txt') // "." (current directory)
- * getDirName('/home/user/') // "/home/user"
- * getDirName('') // "."
- * getDirName('/') // "/" (root)
- *
- * @edge-cases
- * - Returns "." for relative paths without directory
- * - Trailing slashes are normalized
- */
-export function getDirName(pathStr) {
-    if (!pathStr)
-        return '.';
-    return path.dirname(pathStr);
-}
-/**
- * Extracts the file extension (without the dot)
- *
- * Gets the extension of a file.
- *
- * @param pathStr - File path
- * @returns Extension without dot, or empty string
- *
- * @example
- * getFileExtension('/home/user/file.txt') // "txt"
- * getFileExtension('archive.tar.gz') // "gz"
- * getFileExtension('file') // ""
- * getFileExtension('.gitignore') // ""
- * getFileExtension('/path/.hidden') // ""
- * getFileExtension('') // ""
- *
- * @edge-cases
- * - Hidden files starting with . don't have extension
- * - Returns only the last extension (use custom parser for .tar.gz)
- * - Case preserved (not lowercased)
- */
-export function getFileExtension(pathStr) {
-    if (!pathStr)
-        return '';
-    const ext = path.extname(pathStr);
-    return ext.startsWith('.') ? ext.slice(1) : ext;
-}
-/**
- * Gets file name without extension
- *
- * Returns just the base file name.
- *
- * @param pathStr - File path
- * @returns File name without extension
- *
- * @example
- * getBaseName('/home/user/file.txt') // "file"
- * getBaseName('document.pdf') // "document"
- * getBaseName('archive.tar.gz') // "archive.tar" (only removes last ext)
- * getBaseName('noextension') // "noextension"
- * getBaseName('') // ""
- *
- * @edge-cases
- * - Only removes the last extension
- * - For .tar.gz, returns "archive.tar"
- */
-export function getBaseName(pathStr) {
-    if (!pathStr)
-        return '';
-    const basename = path.basename(pathStr);
-    const ext = path.extname(basename);
-    return ext ? basename.slice(0, -ext.length) : basename;
-}
-/**
- * SECURITY: Compares two paths for equality
- *
- * Safe comparison that handles path variations (normalization, case sensitivity).
- * Important for security checks.
- *
- * @param pathA - First path
- * @param pathB - Second path
- * @param caseSensitive - Case-sensitive comparison (default: true on Unix, false on Windows)
- * @returns true if paths refer to the same location
- *
- * @example
- * comparePaths('/home/user', '/home/user') // true
- * comparePaths('/home/user/', '/home/user') // true (trailing slash removed)
- * comparePaths('./file', 'file') // true (when run from same directory)
- * comparePaths('/HOME/user', '/home/user', false) // true (case-insensitive)
- * comparePaths('/home/user', '/other/path') // false
- *
- * @edge-cases
- * - Normalizes paths before comparison
- * - Case sensitivity depends on filesystem
- * - Relative paths resolved to current directory
- *
- * @security-notes
- * - Use for validating against whitelists
- * - Prevents bypass via path normalization tricks
- */
-export function comparePaths(pathA, pathB, caseSensitive = process.platform !== 'win32') {
-    try {
-        const normA = normalizePath(path.resolve(pathA));
-        const normB = normalizePath(path.resolve(pathB));
-        if (caseSensitive) {
-            return normA === normB;
-        }
-        return normA.toLowerCase() === normB.toLowerCase();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Checks if a path is contained within a base directory
- *
- * Useful for sandboxing and access control.
- *
- * @param pathStr - Path to check
- * @param baseDir - Base directory
- * @returns true if pathStr is within baseDir
- *
- * @example
- * isPathWithinBase('/home/user/file.txt', '/home/user') // true
- * isPathWithinBase('/home/user/docs/file.txt', '/home/user') // true
- * isPathWithinBase('/home/user', '/home/user/subdir') // false
- * isPathWithinBase('/etc/passwd', '/home/user') // false
- * isPathWithinBase('/home/user/../etc/passwd', '/home/user') // false
- *
- * @edge-cases
- * - Resolves paths before comparison
- * - Trailing slashes ignored
- * - Case-insensitive on Windows
- *
- * @security-notes
- * - Critical for file upload handlers
- * - Prevents directory traversal in validation
- * - Use with normalizePath() for defense in depth
- */
-export function isPathWithinBase(pathStr, baseDir) {
-    try {
-        const baseDirResolved = path.resolve(baseDir);
-        const pathResolved = path.resolve(baseDir, normalizePath(pathStr));
-        const relative = path.relative(baseDirResolved, pathResolved);
-        return !relative.startsWith('..') && !path.isAbsolute(relative);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Detects if a path contains directory traversal patterns
- *
- * Simple pattern-based detection for common attack vectors.
- *
- * @param pathStr - Path to check
- * @returns true if path contains traversal patterns
- *
- * @example
- * hasTraversalPattern('../../etc/passwd') // true
- * hasTraversalPattern('file.txt') // false
- * hasTraversalPattern('./file.txt') // false
- * hasTraversalPattern('..\\..\\windows\\system32') // true (Windows)
- * hasTraversalPattern('foo/..') // true
- * hasTraversalPattern('') // false
- *
- * @edge-cases
- * - Detects both / and \ separators
- * - Catches .. patterns anywhere in path
- * - May have false positives (validate with isPathSafe)
- *
- * @security-notes
- * - Use as quick check before detailed validation
- * - Not sufficient alone - use isPathSafe() for security
- */
-export function hasTraversalPattern(pathStr) {
-    if (!pathStr)
-        return false;
-    // Check for .. patterns
-    return /(\.\.)|(\.\.\\)/.test(pathStr);
-}
-/**
- * Detects if a path contains null bytes (injection attempt)
- *
- * Null bytes can truncate paths in C string libraries.
- * Critical security check for some codebases.
- *
- * @param pathStr - Path to check
- * @returns true if path contains null bytes
- *
- * @example
- * hasNullBytes('file.txt') // false
- * hasNullBytes('file.txt\0.jsp') // true
- * hasNullBytes('') // false
- *
- * @edge-cases
- * - Only relevant for C-based systems
- * - Node.js handles this automatically in most cases
- */
-export function hasNullBytes(pathStr) {
-    return pathStr.includes('\0');
-}
-/**
- * Sanitizes a path by removing dangerous characters
- *
- * Removes null bytes, excess whitespace, and potentially problematic characters.
- * Use for defensive programming.
- *
- * @param pathStr - Path to sanitize
- * @returns Sanitized path
- *
- * @example
- * sanitizePath('file.txt') // "file.txt"
- * sanitizePath('file.txt\0.jsp') // "file.txt.jsp"
- * sanitizePath('file  name.txt') // "file  name.txt"
- * sanitizePath('') // ""
- *
- * @edge-cases
- * - Doesn't validate path, only removes dangerous chars
- * - Use with isPathSafe() for full validation
- */
-export function sanitizePath(pathStr) {
-    if (!pathStr)
-        return '';
-    // Remove null bytes and excessive whitespace
-    return pathStr.replace(/\0/g, '').trim();
-}
-/**
- * Gets the relative path between two paths
- *
- * Safe version of path.relative with error handling.
- *
- * @param from - Starting path
- * @param to - Target path
- * @returns Relative path from 'from' to 'to'
- *
- * @example
- * getRelativePath('/home/user', '/home/user/file.txt')
- * // "file.txt"
- *
- * getRelativePath('/home/user/docs', '/home/user/file.txt')
- * // "../file.txt"
- *
- * getRelativePath('/home', '/var')
- * // "../../var"
- *
- * @edge-cases
- * - Empty paths treated as current directory
- * - May produce .. patterns
- */
-export function getRelativePath(from, to) {
-    try {
-        return path.relative(from || '.', to || '.');
-    }
-    catch {
-        return to;
-    }
-}
-/**
- * SECURITY: Validates a list of paths
- *
- * Batch validation useful for multi-file operations.
- *
- * @param paths - Array of paths to validate
- * @param options - Validation options
- * @returns Array of valid paths
- *
- * @example
- * validatePaths(userPaths, {
- *   base: '/app/uploads',
- *   filterUnsafe: true,
- * })
- *
- * @edge-cases
- * - Filters out duplicates if normalize: true
- * - Returns empty array if no valid paths
- */
-export function validatePaths(paths, options = {}) {
-    const { base, filterUnsafe = true, normalize = true } = options;
-    return paths.filter(p => {
-        if (filterUnsafe && !isPathSafe(p, base)) {
-            return false;
-        }
-        return true;
-    });
-}
-/**
- * Creates a pattern to detect path variations
- *
- * Useful for accepting different path formats.
- *
- * @param pathStr - Base path
- * @returns Test function for path equivalence
- *
- * @example
- * const isSameFile = createPathMatcher('/home/user/file.txt');
- * isSameFile('/home/user/file.txt') // true
- * isSameFile('/home/user//file.txt') // true
- * isSameFile('/home/user/./file.txt') // true
- * isSameFile('~/file.txt') // false (if ~ not expanded)
- *
- * @edge-cases
- * - Doesn't expand ~ (home directory)
- * - Case-sensitive on Unix, insensitive on Windows
- */
-export function createPathMatcher(pathStr) {
-    const normalized = normalizePath(path.resolve(pathStr));
-    return (other) => {
-        try {
-            const otherNormalized = normalizePath(path.resolve(other));
-            const isCaseSensitive = process.platform !== 'win32';
-            if (isCaseSensitive) {
-                return normalized === otherNormalized;
-            }
-            return normalized.toLowerCase() === otherNormalized.toLowerCase();
-        }
-        catch {
-            return false;
-        }
-    };
-}
-/**
- * Checks if a file path looks like a suspicious upload
- *
- * Detects common file upload attack patterns.
- *
- * @param pathStr - File path to check
- * @returns Array of detected issues (empty if safe)
- *
- * @example
- * detectUploadThreats('shell.php.txt') // ['suspicious_extension_combo']
- * detectUploadThreats('../../../etc/passwd') // ['traversal_pattern']
- * detectUploadThreats('file.txt') // []
- * detectUploadThreats('.htaccess') // ['hidden_file']
- *
- * @edge-cases
- * - Uses heuristics, not definitive
- * - May have false positives
- * - Combine with extension whitelisting
- *
- * @security-notes
- * - Use as additional layer, not primary validation
- * - Always validate against whitelist of extensions
- * - Store uploads outside web root
- */
-export function detectUploadThreats(pathStr) {
-    const issues = [];
-    // Check for traversal
-    if (hasTraversalPattern(pathStr)) {
-        issues.push('traversal_pattern');
-    }
-    // Check for null bytes
-    if (hasNullBytes(pathStr)) {
-        issues.push('null_byte_injection');
-    }
-    // Check for hidden files
-    if (getFileName(pathStr).startsWith('.')) {
-        issues.push('hidden_file');
-    }
-    // Check for suspicious extension combinations
-    const filename = getFileName(pathStr);
-    const dangerousExts = ['php', 'php3', 'php4', 'phtml', 'jsp', 'asp', 'exe', 'sh', 'bat'];
-    const ext = getFileExtension(pathStr).toLowerCase();
-    const parts = filename.split('.');
-    // Check for suspicious double extension like shell.php.txt or image.php.jpg
-    if (parts.length > 2) {
-        // Check if any middle part is a dangerous extension
-        const middleParts = parts.slice(1, -1); // Exclude first part and last extension
-        if (middleParts.some(p => dangerousExts.includes(p.toLowerCase()))) {
-            issues.push('suspicious_extension_combo');
-        }
-    }
-    // Check if the final extension is dangerous
-    if (dangerousExts.includes(ext)) {
-        issues.push('dangerous_extension');
-    }
-    return issues;
-}
-//# sourceMappingURL=path-validator.js.map