@dexto/tools-filesystem 1.5.0

package/dist/path-validator.d.ts

@@ -0,0 +1,90 @@
+import { FileSystemConfig, PathValidation } from './types.js';
+import { IDextoLogger } from '@dexto/core';
+
+/**
+ * Path Validator
+ *
+ * Security-focused path validation for file system operations
+ */
+
+/**
+ * Callback type for checking if a path is in an approved directory.
+ * Used to consult ApprovalManager without creating a direct dependency.
+ */
+type DirectoryApprovalChecker = (filePath: string) => boolean;
+/**
+ * PathValidator - Validates file paths for security and policy compliance
+ *
+ * Security checks:
+ * 1. Path traversal detection (../, symbolic links)
+ * 2. Allowed paths enforcement (whitelist + approved directories)
+ * 3. Blocked paths detection (blacklist)
+ * 4. File extension restrictions
+ * 5. Absolute path normalization
+ *
+ * PathValidator can optionally consult an external approval checker (e.g., ApprovalManager)
+ * to determine if paths outside the config's allowed paths are accessible.
+ */
+declare class PathValidator {
+    private config;
+    private normalizedAllowedPaths;
+    private normalizedBlockedPaths;
+    private normalizedBlockedExtensions;
+    private logger;
+    private directoryApprovalChecker;
+    constructor(config: FileSystemConfig, logger: IDextoLogger);
+    /**
+     * Set a callback to check if a path is in an approved directory.
+     * This allows PathValidator to consult ApprovalManager without a direct dependency.
+     *
+     * @param checker Function that returns true if path is in an approved directory
+     */
+    setDirectoryApprovalChecker(checker: DirectoryApprovalChecker): void;
+    /**
+     * Validate a file path for security and policy compliance
+     */
+    validatePath(filePath: string): PathValidation;
+    /**
+     * Check if path contains traversal attempts
+     */
+    private hasPathTraversal;
+    /**
+     * Check if path is within allowed paths (whitelist check)
+     * Also consults the directory approval checker if configured.
+     */
+    private isPathAllowed;
+    /**
+     * Check if path matches blocked patterns (blacklist check)
+     */
+    private isPathBlocked;
+    /**
+     * Quick check if a path is allowed (for internal use)
+     */
+    isPathAllowedQuick(normalizedPath: string): boolean;
+    /**
+     * Check if a file path is within the configured allowed paths (from config only).
+     * This method does NOT consult ApprovalManager - it only checks the static config paths.
+     *
+     * This is used by file tools to determine if a path needs directory approval.
+     * Paths within config-allowed directories don't need directory approval prompts.
+     *
+     * @param filePath The file path to check (can be relative or absolute)
+     * @returns true if the path is within config-allowed paths, false otherwise
+     */
+    isPathWithinAllowed(filePath: string): boolean;
+    /**
+     * Check if path is within config-allowed paths only (no approval checker).
+     * Used for prompting decisions.
+     */
+    private isInConfigAllowedPaths;
+    /**
+     * Get normalized allowed paths
+     */
+    getAllowedPaths(): string[];
+    /**
+     * Get blocked paths
+     */
+    getBlockedPaths(): string[];
+}
+
+export { type DirectoryApprovalChecker, PathValidator };

package/dist/path-validator.js

@@ -0,0 +1,198 @@
+import * as path from "node:path";
+import { realpathSync } from "node:fs";
+class PathValidator {
+  config;
+  normalizedAllowedPaths;
+  normalizedBlockedPaths;
+  normalizedBlockedExtensions;
+  logger;
+  directoryApprovalChecker;
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    const workingDir = config.workingDirectory || process.cwd();
+    this.normalizedAllowedPaths = config.allowedPaths.map((p) => path.resolve(workingDir, p));
+    this.normalizedBlockedPaths = config.blockedPaths.map((p) => path.normalize(p));
+    this.normalizedBlockedExtensions = (config.blockedExtensions || []).map((ext) => {
+      const e = ext.startsWith(".") ? ext : `.${ext}`;
+      return e.toLowerCase();
+    });
+    this.logger.debug(
+      `PathValidator initialized with ${this.normalizedAllowedPaths.length} allowed paths`
+    );
+  }
+  /**
+   * Set a callback to check if a path is in an approved directory.
+   * This allows PathValidator to consult ApprovalManager without a direct dependency.
+   *
+   * @param checker Function that returns true if path is in an approved directory
+   */
+  setDirectoryApprovalChecker(checker) {
+    this.directoryApprovalChecker = checker;
+    this.logger.debug("Directory approval checker configured");
+  }
+  /**
+   * Validate a file path for security and policy compliance
+   */
+  validatePath(filePath) {
+    if (!filePath || filePath.trim() === "") {
+      return {
+        isValid: false,
+        error: "Path cannot be empty"
+      };
+    }
+    const workingDir = this.config.workingDirectory || process.cwd();
+    let normalizedPath;
+    try {
+      normalizedPath = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(workingDir, filePath);
+      try {
+        normalizedPath = realpathSync.native(normalizedPath);
+      } catch {
+      }
+    } catch (error) {
+      return {
+        isValid: false,
+        error: `Failed to normalize path: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    if (this.hasPathTraversal(filePath, normalizedPath)) {
+      return {
+        isValid: false,
+        error: "Path traversal detected"
+      };
+    }
+    if (!this.isPathAllowed(normalizedPath)) {
+      return {
+        isValid: false,
+        error: `Path is not within allowed paths. Allowed: ${this.normalizedAllowedPaths.join(", ")}`
+      };
+    }
+    const blockedReason = this.isPathBlocked(normalizedPath);
+    if (blockedReason) {
+      return {
+        isValid: false,
+        error: `Path is blocked: ${blockedReason}`
+      };
+    }
+    const ext = path.extname(normalizedPath).toLowerCase();
+    if (ext && this.normalizedBlockedExtensions.includes(ext)) {
+      return {
+        isValid: false,
+        error: `File extension ${ext} is not allowed`
+      };
+    }
+    return {
+      isValid: true,
+      normalizedPath
+    };
+  }
+  /**
+   * Check if path contains traversal attempts
+   */
+  hasPathTraversal(originalPath, normalizedPath) {
+    if (originalPath.includes("../") || originalPath.includes("..\\")) {
+      const workingDir = this.config.workingDirectory || process.cwd();
+      const relative = path.relative(workingDir, normalizedPath);
+      if (relative.startsWith("..")) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if path is within allowed paths (whitelist check)
+   * Also consults the directory approval checker if configured.
+   */
+  isPathAllowed(normalizedPath) {
+    if (this.normalizedAllowedPaths.length === 0) {
+      return true;
+    }
+    const isInConfigPaths = this.normalizedAllowedPaths.some((allowedPath) => {
+      const relative = path.relative(allowedPath, normalizedPath);
+      return !relative.startsWith("..") && !path.isAbsolute(relative);
+    });
+    if (isInConfigPaths) {
+      return true;
+    }
+    if (this.directoryApprovalChecker) {
+      return this.directoryApprovalChecker(normalizedPath);
+    }
+    return false;
+  }
+  /**
+   * Check if path matches blocked patterns (blacklist check)
+   */
+  isPathBlocked(normalizedPath) {
+    const roots = this.normalizedAllowedPaths.length > 0 ? this.normalizedAllowedPaths : [this.config.workingDirectory || process.cwd()];
+    for (const blocked of this.normalizedBlockedPaths) {
+      for (const root of roots) {
+        const blockedFull = path.isAbsolute(blocked) ? path.normalize(blocked) : path.resolve(root, blocked);
+        if (normalizedPath === blockedFull || normalizedPath.startsWith(blockedFull + path.sep)) {
+          return `Within blocked directory: ${blocked}`;
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * Quick check if a path is allowed (for internal use)
+   */
+  isPathAllowedQuick(normalizedPath) {
+    return this.isPathAllowed(normalizedPath) && !this.isPathBlocked(normalizedPath);
+  }
+  /**
+   * Check if a file path is within the configured allowed paths (from config only).
+   * This method does NOT consult ApprovalManager - it only checks the static config paths.
+   *
+   * This is used by file tools to determine if a path needs directory approval.
+   * Paths within config-allowed directories don't need directory approval prompts.
+   *
+   * @param filePath The file path to check (can be relative or absolute)
+   * @returns true if the path is within config-allowed paths, false otherwise
+   */
+  isPathWithinAllowed(filePath) {
+    if (!filePath || filePath.trim() === "") {
+      return false;
+    }
+    const workingDir = this.config.workingDirectory || process.cwd();
+    let normalizedPath;
+    try {
+      normalizedPath = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(workingDir, filePath);
+      try {
+        normalizedPath = realpathSync.native(normalizedPath);
+      } catch {
+      }
+    } catch {
+      return false;
+    }
+    return this.isInConfigAllowedPaths(normalizedPath);
+  }
+  /**
+   * Check if path is within config-allowed paths only (no approval checker).
+   * Used for prompting decisions.
+   */
+  isInConfigAllowedPaths(normalizedPath) {
+    if (this.normalizedAllowedPaths.length === 0) {
+      return true;
+    }
+    return this.normalizedAllowedPaths.some((allowedPath) => {
+      const relative = path.relative(allowedPath, normalizedPath);
+      return !relative.startsWith("..") && !path.isAbsolute(relative);
+    });
+  }
+  /**
+   * Get normalized allowed paths
+   */
+  getAllowedPaths() {
+    return [...this.normalizedAllowedPaths];
+  }
+  /**
+   * Get blocked paths
+   */
+  getBlockedPaths() {
+    return [...this.normalizedBlockedPaths];
+  }
+}
+export {
+  PathValidator
+};