@kadi.build/file-manager 1.0.0

package/src/utils/PathUtils.js

@@ -0,0 +1,144 @@
+/**
+ * PathUtils - Path validation and normalization utilities
+ *
+ * Extracted from LocalProvider for reuse across providers
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+
+class PathUtils {
+  constructor(options = {}) {
+    this.basePath = options.basePath || process.cwd();
+    this.maxPathLength = options.maxPathLength || 255;
+    this.allowSymlinks = options.allowSymlinks || false;
+    this.restrictToBasePath = options.restrictToBasePath !== false;
+  }
+
+  /**
+   * Normalize a file path, resolving relative segments and ensuring consistency
+   */
+  normalizePath(inputPath) {
+    if (!inputPath) return this.basePath;
+
+    // Handle home directory
+    if (inputPath.startsWith('~')) {
+      inputPath = inputPath.replace('~', process.env.HOME || '');
+    }
+
+    // Resolve relative paths against basePath
+    if (!path.isAbsolute(inputPath)) {
+      inputPath = path.resolve(this.basePath, inputPath);
+    }
+
+    // Normalize to remove double slashes, . and ..
+    return path.normalize(inputPath);
+  }
+
+  /**
+   * Validate a path for safety and constraints
+   */
+  validatePath(inputPath) {
+    const errors = [];
+    const warnings = [];
+
+    if (!inputPath) {
+      errors.push('Path is required');
+      return { isValid: false, errors, warnings };
+    }
+
+    const normalized = this.normalizePath(inputPath);
+
+    // Check path length
+    if (normalized.length > this.maxPathLength) {
+      errors.push(`Path exceeds maximum length of ${this.maxPathLength} characters`);
+    }
+
+    // Check for null bytes
+    if (normalized.includes('\0')) {
+      errors.push('Path contains null bytes');
+    }
+
+    // Check for path traversal if restricted
+    if (this.restrictToBasePath) {
+      const resolvedBase = path.resolve(this.basePath);
+      const resolvedPath = path.resolve(normalized);
+      if (!resolvedPath.startsWith(resolvedBase)) {
+        errors.push('Path traversal detected - path is outside base directory');
+      }
+    }
+
+    // Warn about special characters
+    const specialChars = /[<>:"|?*]/;
+    if (specialChars.test(path.basename(normalized))) {
+      warnings.push('Path contains special characters that may not be portable');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      normalizedPath: normalized,
+      errors,
+      warnings
+    };
+  }
+
+  /**
+   * Check if a path exists
+   */
+  async exists(inputPath) {
+    try {
+      const normalized = this.normalizePath(inputPath);
+      await fs.access(normalized);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Ensure a directory exists, creating it if necessary
+   */
+  async ensureDirectory(dirPath) {
+    const normalized = this.normalizePath(dirPath);
+    await fs.mkdir(normalized, { recursive: true });
+    return normalized;
+  }
+
+  /**
+   * Get the relative path from base
+   */
+  relativePath(inputPath) {
+    const normalized = this.normalizePath(inputPath);
+    return path.relative(this.basePath, normalized);
+  }
+
+  /**
+   * Join paths safely
+   */
+  join(...segments) {
+    return path.join(...segments);
+  }
+
+  /**
+   * Get file extension
+   */
+  getExtension(filePath) {
+    return path.extname(filePath).toLowerCase();
+  }
+
+  /**
+   * Get filename without extension
+   */
+  getBaseName(filePath, ext) {
+    return path.basename(filePath, ext);
+  }
+
+  /**
+   * Get directory name
+   */
+  getDirName(filePath) {
+    return path.dirname(filePath);
+  }
+}
+
+export { PathUtils };