@sparkleideas/security 3.0.0-alpha.10

package/src/path-validator.ts

@@ -0,0 +1,525 @@
+/**
+ * Path Validator - HIGH-2 Remediation
+ *
+ * Fixes path traversal vulnerabilities by:
+ * - Validating all file paths against allowed prefixes
+ * - Using path.resolve() for canonicalization
+ * - Blocking traversal patterns (../, etc.)
+ * - Enforcing path length limits
+ *
+ * Security Properties:
+ * - Path canonicalization
+ * - Prefix validation
+ * - Symlink resolution (optional)
+ * - Traversal pattern detection
+ *
+ * @module v3/security/path-validator
+ */
+
+import * as path from 'path';
+import * as fs from 'fs/promises';
+
+export interface PathValidatorConfig {
+  /**
+   * Allowed directory prefixes.
+   * Paths must start with one of these after resolution.
+   */
+  allowedPrefixes: string[];
+
+  /**
+   * Blocked file extensions.
+   * Files with these extensions are rejected.
+   */
+  blockedExtensions?: string[];
+
+  /**
+   * Blocked file names.
+   * Files matching these names are rejected.
+   */
+  blockedNames?: string[];
+
+  /**
+   * Maximum path length.
+   * Default: 4096 characters
+   */
+  maxPathLength?: number;
+
+  /**
+   * Whether to resolve symlinks.
+   * Default: true
+   */
+  resolveSymlinks?: boolean;
+
+  /**
+   * Whether to allow paths that don't exist.
+   * Default: true (for write operations)
+   */
+  allowNonExistent?: boolean;
+
+  /**
+   * Whether to allow hidden files/directories.
+   * Default: false
+   */
+  allowHidden?: boolean;
+}
+
+export interface PathValidationResult {
+  isValid: boolean;
+  resolvedPath: string;
+  relativePath: string;
+  matchedPrefix: string;
+  errors: string[];
+}
+
+export class PathValidatorError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly path?: string,
+  ) {
+    super(message);
+    this.name = 'PathValidatorError';
+  }
+}
+
+/**
+ * Dangerous path patterns that indicate traversal attempts.
+ */
+const TRAVERSAL_PATTERNS = [
+  /\.\.\//,              // ../
+  /\.\.\\/,              // ..\
+  /\.\./,                // .. anywhere
+  /%2e%2e/i,             // URL-encoded ..
+  /%252e%252e/i,         // Double URL-encoded ..
+  /\.%2e/i,              // Mixed encoding
+  /%2e\./i,              // Mixed encoding
+  /\0/,                  // Null byte
+  /%00/,                 // URL-encoded null
+];
+
+/**
+ * Default blocked file extensions (sensitive files).
+ */
+const DEFAULT_BLOCKED_EXTENSIONS = [
+  '.env',
+  '.pem',
+  '.key',
+  '.crt',
+  '.pfx',
+  '.p12',
+  '.jks',
+  '.keystore',
+  '.secret',
+  '.credentials',
+];
+
+/**
+ * Default blocked file names (sensitive files).
+ */
+const DEFAULT_BLOCKED_NAMES = [
+  'id_rsa',
+  'id_dsa',
+  'id_ecdsa',
+  'id_ed25519',
+  '.htpasswd',
+  '.htaccess',
+  'shadow',
+  'passwd',
+  'authorized_keys',
+  'known_hosts',
+  '.git',
+  '.gitconfig',
+  '.npmrc',
+  '.docker',
+];
+
+/**
+ * Path validator that prevents traversal attacks.
+ *
+ * This class validates file paths to ensure they stay within
+ * allowed directories and don't access sensitive files.
+ *
+ * @example
+ * ```typescript
+ * const validator = new PathValidator({
+ *   allowedPrefixes: ['/workspaces/project']
+ * });
+ *
+ * const result = await validator.validate('/workspaces/project/src/file.ts');
+ * if (result.isValid) {
+ *   // Safe to use result.resolvedPath
+ * }
+ * ```
+ */
+export class PathValidator {
+  private readonly config: Required<PathValidatorConfig>;
+  private readonly resolvedPrefixes: string[];
+
+  constructor(config: PathValidatorConfig) {
+    this.config = {
+      allowedPrefixes: config.allowedPrefixes,
+      blockedExtensions: config.blockedExtensions ?? DEFAULT_BLOCKED_EXTENSIONS,
+      blockedNames: config.blockedNames ?? DEFAULT_BLOCKED_NAMES,
+      maxPathLength: config.maxPathLength ?? 4096,
+      resolveSymlinks: config.resolveSymlinks ?? true,
+      allowNonExistent: config.allowNonExistent ?? true,
+      allowHidden: config.allowHidden ?? false,
+    };
+
+    if (this.config.allowedPrefixes.length === 0) {
+      throw new PathValidatorError(
+        'At least one allowed prefix must be specified',
+        'EMPTY_PREFIXES'
+      );
+    }
+
+    // Pre-resolve all prefixes
+    this.resolvedPrefixes = this.config.allowedPrefixes.map(p =>
+      path.resolve(p)
+    );
+  }
+
+  /**
+   * Validates a path against security rules.
+   *
+   * @param inputPath - The path to validate
+   * @returns Validation result with resolved path
+   */
+  async validate(inputPath: string): Promise<PathValidationResult> {
+    const errors: string[] = [];
+
+    // Check for empty path
+    if (!inputPath || inputPath.trim() === '') {
+      return {
+        isValid: false,
+        resolvedPath: '',
+        relativePath: '',
+        matchedPrefix: '',
+        errors: ['Path is empty'],
+      };
+    }
+
+    // Check path length
+    if (inputPath.length > this.config.maxPathLength) {
+      return {
+        isValid: false,
+        resolvedPath: '',
+        relativePath: '',
+        matchedPrefix: '',
+        errors: [`Path exceeds maximum length of ${this.config.maxPathLength}`],
+      };
+    }
+
+    // Check for traversal patterns
+    for (const pattern of TRAVERSAL_PATTERNS) {
+      if (pattern.test(inputPath)) {
+        return {
+          isValid: false,
+          resolvedPath: '',
+          relativePath: '',
+          matchedPrefix: '',
+          errors: ['Path traversal pattern detected'],
+        };
+      }
+    }
+
+    // Resolve the path
+    let resolvedPath: string;
+    try {
+      resolvedPath = path.resolve(inputPath);
+
+      // Optionally resolve symlinks
+      if (this.config.resolveSymlinks) {
+        try {
+          resolvedPath = await fs.realpath(resolvedPath);
+        } catch (error: any) {
+          // Path doesn't exist yet - use resolved path
+          if (error.code !== 'ENOENT' || !this.config.allowNonExistent) {
+            if (error.code === 'ENOENT') {
+              errors.push('Path does not exist');
+            } else {
+              errors.push(`Failed to resolve path: ${error.message}`);
+            }
+          }
+        }
+      }
+    } catch (error: any) {
+      return {
+        isValid: false,
+        resolvedPath: '',
+        relativePath: '',
+        matchedPrefix: '',
+        errors: [`Invalid path: ${error.message}`],
+      };
+    }
+
+    // Check against allowed prefixes
+    let matchedPrefix = '';
+    let relativePath = '';
+    let prefixMatched = false;
+
+    for (const prefix of this.resolvedPrefixes) {
+      if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
+        prefixMatched = true;
+        matchedPrefix = prefix;
+        relativePath = resolvedPath.slice(prefix.length);
+        if (relativePath.startsWith(path.sep)) {
+          relativePath = relativePath.slice(1);
+        }
+        break;
+      }
+    }
+
+    if (!prefixMatched) {
+      return {
+        isValid: false,
+        resolvedPath,
+        relativePath: '',
+        matchedPrefix: '',
+        errors: ['Path is outside allowed directories'],
+      };
+    }
+
+    // Check for hidden files
+    const pathParts = resolvedPath.split(path.sep);
+    if (!this.config.allowHidden) {
+      for (const part of pathParts) {
+        if (part.startsWith('.') && part !== '.' && part !== '..') {
+          errors.push('Hidden files/directories are not allowed');
+          break;
+        }
+      }
+    }
+
+    // Check blocked file names
+    const basename = path.basename(resolvedPath);
+    if (this.config.blockedNames.includes(basename)) {
+      errors.push(`File name "${basename}" is blocked`);
+    }
+
+    // Check blocked extensions
+    const ext = path.extname(resolvedPath).toLowerCase();
+    if (this.config.blockedExtensions.includes(ext)) {
+      errors.push(`File extension "${ext}" is blocked`);
+    }
+
+    // Also check for double extensions (e.g., .tar.gz, .config.json)
+    const fullname = basename.toLowerCase();
+    for (const blockedExt of this.config.blockedExtensions) {
+      if (fullname.endsWith(blockedExt)) {
+        errors.push(`File extension "${blockedExt}" is blocked`);
+        break;
+      }
+    }
+
+    return {
+      isValid: errors.length === 0,
+      resolvedPath,
+      relativePath,
+      matchedPrefix,
+      errors,
+    };
+  }
+
+  /**
+   * Validates and returns resolved path, throwing on failure.
+   *
+   * @param inputPath - The path to validate
+   * @returns Resolved path if valid
+   * @throws PathValidatorError if validation fails
+   */
+  async validateOrThrow(inputPath: string): Promise<string> {
+    const result = await this.validate(inputPath);
+
+    if (!result.isValid) {
+      throw new PathValidatorError(
+        result.errors.join('; '),
+        'VALIDATION_FAILED',
+        inputPath
+      );
+    }
+
+    return result.resolvedPath;
+  }
+
+  /**
+   * Synchronous validation (without symlink resolution).
+   *
+   * @param inputPath - The path to validate
+   * @returns Validation result
+   */
+  validateSync(inputPath: string): PathValidationResult {
+    const errors: string[] = [];
+
+    if (!inputPath || inputPath.trim() === '') {
+      return {
+        isValid: false,
+        resolvedPath: '',
+        relativePath: '',
+        matchedPrefix: '',
+        errors: ['Path is empty'],
+      };
+    }
+
+    if (inputPath.length > this.config.maxPathLength) {
+      return {
+        isValid: false,
+        resolvedPath: '',
+        relativePath: '',
+        matchedPrefix: '',
+        errors: [`Path exceeds maximum length of ${this.config.maxPathLength}`],
+      };
+    }
+
+    for (const pattern of TRAVERSAL_PATTERNS) {
+      if (pattern.test(inputPath)) {
+        return {
+          isValid: false,
+          resolvedPath: '',
+          relativePath: '',
+          matchedPrefix: '',
+          errors: ['Path traversal pattern detected'],
+        };
+      }
+    }
+
+    const resolvedPath = path.resolve(inputPath);
+
+    let matchedPrefix = '';
+    let relativePath = '';
+    let prefixMatched = false;
+
+    for (const prefix of this.resolvedPrefixes) {
+      if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
+        prefixMatched = true;
+        matchedPrefix = prefix;
+        relativePath = resolvedPath.slice(prefix.length);
+        if (relativePath.startsWith(path.sep)) {
+          relativePath = relativePath.slice(1);
+        }
+        break;
+      }
+    }
+
+    if (!prefixMatched) {
+      return {
+        isValid: false,
+        resolvedPath,
+        relativePath: '',
+        matchedPrefix: '',
+        errors: ['Path is outside allowed directories'],
+      };
+    }
+
+    const pathParts = resolvedPath.split(path.sep);
+    if (!this.config.allowHidden) {
+      for (const part of pathParts) {
+        if (part.startsWith('.') && part !== '.' && part !== '..') {
+          errors.push('Hidden files/directories are not allowed');
+          break;
+        }
+      }
+    }
+
+    const basename = path.basename(resolvedPath);
+    if (this.config.blockedNames.includes(basename)) {
+      errors.push(`File name "${basename}" is blocked`);
+    }
+
+    const ext = path.extname(resolvedPath).toLowerCase();
+    if (this.config.blockedExtensions.includes(ext)) {
+      errors.push(`File extension "${ext}" is blocked`);
+    }
+
+    return {
+      isValid: errors.length === 0,
+      resolvedPath,
+      relativePath,
+      matchedPrefix,
+      errors,
+    };
+  }
+
+  /**
+   * Securely joins path segments within allowed directories.
+   *
+   * @param prefix - Base directory (must be in allowedPrefixes)
+   * @param segments - Path segments to join
+   * @returns Validated resolved path
+   */
+  async securePath(prefix: string, ...segments: string[]): Promise<string> {
+    // Join the segments
+    const joined = path.join(prefix, ...segments);
+
+    // Validate the result
+    return this.validateOrThrow(joined);
+  }
+
+  /**
+   * Adds a prefix to the allowed list at runtime.
+   *
+   * @param prefix - Prefix to add
+   */
+  addPrefix(prefix: string): void {
+    const resolved = path.resolve(prefix);
+    if (!this.resolvedPrefixes.includes(resolved)) {
+      this.config.allowedPrefixes.push(prefix);
+      this.resolvedPrefixes.push(resolved);
+    }
+  }
+
+  /**
+   * Returns the current allowed prefixes.
+   */
+  getAllowedPrefixes(): readonly string[] {
+    return [...this.resolvedPrefixes];
+  }
+
+  /**
+   * Checks if a path is within allowed prefixes (quick check).
+   */
+  isWithinAllowed(inputPath: string): boolean {
+    try {
+      const resolved = path.resolve(inputPath);
+      return this.resolvedPrefixes.some(
+        prefix => resolved === prefix || resolved.startsWith(prefix + path.sep)
+      );
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Factory function to create a path validator for a project directory.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Configured PathValidator
+ */
+export function createProjectPathValidator(projectRoot: string): PathValidator {
+  const srcDir = path.join(projectRoot, 'src');
+  const testDir = path.join(projectRoot, 'tests');
+  const docsDir = path.join(projectRoot, 'docs');
+
+  return new PathValidator({
+    allowedPrefixes: [srcDir, testDir, docsDir],
+    allowHidden: false,
+  });
+}
+
+/**
+ * Factory function to create a path validator for the entire project.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Configured PathValidator
+ */
+export function createFullProjectPathValidator(projectRoot: string): PathValidator {
+  return new PathValidator({
+    allowedPrefixes: [projectRoot],
+    allowHidden: true, // Allow .gitignore, etc.
+    blockedNames: [
+      ...DEFAULT_BLOCKED_NAMES,
+      'node_modules', // Block access to node_modules
+    ],
+  });
+}