@dexto/tools-filesystem 1.5.2 → 1.5.3

package/dist/path-validator.d.ts

@@ -43,7 +43,7 @@ declare class PathValidator {
     /**
      * Validate a file path for security and policy compliance
      */
-    validatePath(filePath: string): PathValidation;
+    validatePath(filePath: string): Promise<PathValidation>;
     /**
      * Check if path contains traversal attempts
      */
@@ -51,6 +51,7 @@ declare class PathValidator {
     /**
      * Check if path is within allowed paths (whitelist check)
      * Also consults the directory approval checker if configured.
+     * Uses the sync version since the path is already normalized at this point.
      */
     private isPathAllowed;
     /**
@@ -59,8 +60,14 @@ declare class PathValidator {
     private isPathBlocked;
     /**
      * Quick check if a path is allowed (for internal use)
+     * Note: This assumes the path is already normalized/canonicalized
      */
     isPathAllowedQuick(normalizedPath: string): boolean;
+    /**
+     * Synchronous path allowed check (for already-normalized paths)
+     * This is used internally when we already have a canonicalized path
+     */
+    private isPathAllowedSync;
     /**
      * 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.
@@ -71,7 +78,7 @@ declare class PathValidator {
      * @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;
+    isPathWithinAllowed(filePath: string): Promise<boolean>;
     /**
      * Check if path is within config-allowed paths only (no approval checker).
      * Used for prompting decisions.

package/dist/path-validator.js

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { realpathSync } from "node:fs";
+import * as fs from "node:fs/promises";
 class PathValidator {
   config;
   normalizedAllowedPaths;
@@ -34,7 +34,7 @@ class PathValidator {
   /**
    * Validate a file path for security and policy compliance
    */
-  validatePath(filePath) {
+  async validatePath(filePath) {
     if (!filePath || filePath.trim() === "") {
       return {
         isValid: false,
@@ -46,7 +46,7 @@ class PathValidator {
     try {
       normalizedPath = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(workingDir, filePath);
       try {
-        normalizedPath = realpathSync.native(normalizedPath);
+        normalizedPath = await fs.realpath(normalizedPath);
       } catch {
       }
     } catch (error) {
@@ -102,22 +102,10 @@ class PathValidator {
   /**
    * Check if path is within allowed paths (whitelist check)
    * Also consults the directory approval checker if configured.
+   * Uses the sync version since the path is already normalized at this point.
    */
   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;
+    return this.isPathAllowedSync(normalizedPath);
   }
   /**
    * Check if path matches blocked patterns (blacklist check)
@@ -136,9 +124,30 @@ class PathValidator {
   }
   /**
    * Quick check if a path is allowed (for internal use)
+   * Note: This assumes the path is already normalized/canonicalized
    */
   isPathAllowedQuick(normalizedPath) {
-    return this.isPathAllowed(normalizedPath) && !this.isPathBlocked(normalizedPath);
+    return this.isPathAllowedSync(normalizedPath) && !this.isPathBlocked(normalizedPath);
+  }
+  /**
+   * Synchronous path allowed check (for already-normalized paths)
+   * This is used internally when we already have a canonicalized path
+   */
+  isPathAllowedSync(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 a file path is within the configured allowed paths (from config only).
@@ -150,7 +159,7 @@ class PathValidator {
    * @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) {
+  async isPathWithinAllowed(filePath) {
     if (!filePath || filePath.trim() === "") {
       return false;
     }
@@ -159,7 +168,7 @@ class PathValidator {
     try {
       normalizedPath = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(workingDir, filePath);
       try {
-        normalizedPath = realpathSync.native(normalizedPath);
+        normalizedPath = await fs.realpath(normalizedPath);
       } catch {
       }
     } catch {

package/dist/path-validator.test.cjs

@@ -16,7 +16,7 @@ const createMockLogger = () => ({
   });
   (0, import_vitest.describe)("validatePath", () => {
     (0, import_vitest.describe)("Empty and Invalid Paths", () => {
-      (0, import_vitest.it)("should reject empty path", () => {
+      (0, import_vitest.it)("should reject empty path", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -29,11 +29,11 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("");
+        const result = await validator.validatePath("");
         (0, import_vitest.expect)(result.isValid).toBe(false);
         (0, import_vitest.expect)(result.error).toBe("Path cannot be empty");
       });
-      (0, import_vitest.it)("should reject whitespace-only path", () => {
+      (0, import_vitest.it)("should reject whitespace-only path", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -46,13 +46,13 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("   ");
+        const result = await validator.validatePath("   ");
         (0, import_vitest.expect)(result.isValid).toBe(false);
         (0, import_vitest.expect)(result.error).toBe("Path cannot be empty");
       });
     });
     (0, import_vitest.describe)("Allowed Paths", () => {
-      (0, import_vitest.it)("should allow paths within allowed directories", () => {
+      (0, import_vitest.it)("should allow paths within allowed directories", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -65,11 +65,11 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/home/user/project/src/file.ts");
+        const result = await validator.validatePath("/home/user/project/src/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(true);
         (0, import_vitest.expect)(result.normalizedPath).toBeDefined();
       });
-      (0, import_vitest.it)("should allow relative paths within working directory", () => {
+      (0, import_vitest.it)("should allow relative paths within working directory", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -82,10 +82,10 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("src/file.ts");
+        const result = await validator.validatePath("src/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(true);
       });
-      (0, import_vitest.it)("should reject paths outside allowed directories", () => {
+      (0, import_vitest.it)("should reject paths outside allowed directories", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -98,11 +98,11 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/external/project/file.ts");
+        const result = await validator.validatePath("/external/project/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(false);
         (0, import_vitest.expect)(result.error).toContain("not within allowed paths");
       });
-      (0, import_vitest.it)("should allow all paths when allowedPaths is empty", () => {
+      (0, import_vitest.it)("should allow all paths when allowedPaths is empty", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: [],
@@ -115,12 +115,12 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/anywhere/file.ts");
+        const result = await validator.validatePath("/anywhere/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(true);
       });
     });
     (0, import_vitest.describe)("Path Traversal Detection", () => {
-      (0, import_vitest.it)("should reject path traversal attempts", () => {
+      (0, import_vitest.it)("should reject path traversal attempts", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -133,13 +133,15 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/home/user/project/../../../etc/passwd");
+        const result = await validator.validatePath(
+          "/home/user/project/../../../etc/passwd"
+        );
         (0, import_vitest.expect)(result.isValid).toBe(false);
         (0, import_vitest.expect)(result.error).toBe("Path traversal detected");
       });
     });
     (0, import_vitest.describe)("Blocked Paths", () => {
-      (0, import_vitest.it)("should reject paths in blocked directories", () => {
+      (0, import_vitest.it)("should reject paths in blocked directories", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -152,11 +154,11 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/home/user/project/.git/config");
+        const result = await validator.validatePath("/home/user/project/.git/config");
         (0, import_vitest.expect)(result.isValid).toBe(false);
         (0, import_vitest.expect)(result.error).toContain("blocked");
       });
-      (0, import_vitest.it)("should reject paths in node_modules", () => {
+      (0, import_vitest.it)("should reject paths in node_modules", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -169,7 +171,7 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath(
+        const result = await validator.validatePath(
           "/home/user/project/node_modules/lodash/index.js"
         );
         (0, import_vitest.expect)(result.isValid).toBe(false);
@@ -177,7 +179,7 @@ const createMockLogger = () => ({
       });
     });
     (0, import_vitest.describe)("Blocked Extensions", () => {
-      (0, import_vitest.it)("should reject files with blocked extensions", () => {
+      (0, import_vitest.it)("should reject files with blocked extensions", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -190,11 +192,11 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/home/user/project/malware.exe");
+        const result = await validator.validatePath("/home/user/project/malware.exe");
         (0, import_vitest.expect)(result.isValid).toBe(false);
         (0, import_vitest.expect)(result.error).toContain(".exe is not allowed");
       });
-      (0, import_vitest.it)("should handle extensions without leading dot", () => {
+      (0, import_vitest.it)("should handle extensions without leading dot", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -208,10 +210,10 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/home/user/project/file.exe");
+        const result = await validator.validatePath("/home/user/project/file.exe");
         (0, import_vitest.expect)(result.isValid).toBe(false);
       });
-      (0, import_vitest.it)("should be case-insensitive for extensions", () => {
+      (0, import_vitest.it)("should be case-insensitive for extensions", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -224,12 +226,12 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        const result = validator.validatePath("/home/user/project/file.EXE");
+        const result = await validator.validatePath("/home/user/project/file.EXE");
         (0, import_vitest.expect)(result.isValid).toBe(false);
       });
     });
     (0, import_vitest.describe)("Directory Approval Checker Integration", () => {
-      (0, import_vitest.it)("should consult approval checker for external paths", () => {
+      (0, import_vitest.it)("should consult approval checker for external paths", async () => {
         const validator = new import_path_validator.PathValidator(
           {
             allowedPaths: ["/home/user/project"],
@@ -242,16 +244,16 @@ const createMockLogger = () => ({
           },
           mockLogger
         );
-        let result = validator.validatePath("/external/project/file.ts");
+        let result = await validator.validatePath("/external/project/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(false);
         const approvalChecker = (filePath) => {
           return filePath.startsWith("/external/project");
         };
         validator.setDirectoryApprovalChecker(approvalChecker);
-        result = validator.validatePath("/external/project/file.ts");
+        result = await validator.validatePath("/external/project/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(true);
       });
-      (0, import_vitest.it)("should not use approval checker for config-allowed paths", () => {
+      (0, import_vitest.it)("should not use approval checker for config-allowed paths", async () => {
         const approvalChecker = import_vitest.vi.fn().mockReturnValue(false);
         const validator = new import_path_validator.PathValidator(
           {
@@ -266,14 +268,14 @@ const createMockLogger = () => ({
           mockLogger
         );
         validator.setDirectoryApprovalChecker(approvalChecker);
-        const result = validator.validatePath("/home/user/project/src/file.ts");
+        const result = await validator.validatePath("/home/user/project/src/file.ts");
         (0, import_vitest.expect)(result.isValid).toBe(true);
         (0, import_vitest.expect)(approvalChecker).not.toHaveBeenCalled();
       });
     });
   });
   (0, import_vitest.describe)("isPathWithinAllowed", () => {
-    (0, import_vitest.it)("should return true for paths within config-allowed directories", () => {
+    (0, import_vitest.it)("should return true for paths within config-allowed directories", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: ["/home/user/project"],
@@ -286,12 +288,14 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/home/user/project/src/file.ts")).toBe(true);
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/home/user/project/deep/nested/file.ts")).toBe(
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/home/user/project/src/file.ts")).toBe(
         true
       );
+      (0, import_vitest.expect)(
+        await validator.isPathWithinAllowed("/home/user/project/deep/nested/file.ts")
+      ).toBe(true);
     });
-    (0, import_vitest.it)("should return false for paths outside config-allowed directories", () => {
+    (0, import_vitest.it)("should return false for paths outside config-allowed directories", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: ["/home/user/project"],
@@ -304,10 +308,10 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/external/project/file.ts")).toBe(false);
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/home/user/other/file.ts")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/external/project/file.ts")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/home/user/other/file.ts")).toBe(false);
     });
-    (0, import_vitest.it)("should NOT consult approval checker (used for prompting decisions)", () => {
+    (0, import_vitest.it)("should NOT consult approval checker (used for prompting decisions)", async () => {
       const approvalChecker = import_vitest.vi.fn().mockReturnValue(true);
       const validator = new import_path_validator.PathValidator(
         {
@@ -322,10 +326,10 @@ const createMockLogger = () => ({
         mockLogger
       );
       validator.setDirectoryApprovalChecker(approvalChecker);
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/external/project/file.ts")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/external/project/file.ts")).toBe(false);
       (0, import_vitest.expect)(approvalChecker).not.toHaveBeenCalled();
     });
-    (0, import_vitest.it)("should return false for empty path", () => {
+    (0, import_vitest.it)("should return false for empty path", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: ["/home/user/project"],
@@ -338,10 +342,10 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("")).toBe(false);
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("   ")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("   ")).toBe(false);
     });
-    (0, import_vitest.it)("should return true when allowedPaths is empty (all paths allowed)", () => {
+    (0, import_vitest.it)("should return true when allowedPaths is empty (all paths allowed)", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: [],
@@ -354,11 +358,11 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/anywhere/file.ts")).toBe(true);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/anywhere/file.ts")).toBe(true);
     });
   });
   (0, import_vitest.describe)("Path Containment (Parent Directory Coverage)", () => {
-    (0, import_vitest.it)("should recognize that approving parent covers child paths", () => {
+    (0, import_vitest.it)("should recognize that approving parent covers child paths", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: ["/external/sub"],
@@ -371,9 +375,11 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/external/sub/deep/nested/file.ts")).toBe(true);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/external/sub/deep/nested/file.ts")).toBe(
+        true
+      );
     });
-    (0, import_vitest.it)("should not allow sibling directories", () => {
+    (0, import_vitest.it)("should not allow sibling directories", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: ["/external/sub"],
@@ -386,9 +392,9 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/external/other/file.ts")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/external/other/file.ts")).toBe(false);
     });
-    (0, import_vitest.it)("should not allow parent directories when child is approved", () => {
+    (0, import_vitest.it)("should not allow parent directories when child is approved", async () => {
       const validator = new import_path_validator.PathValidator(
         {
           allowedPaths: ["/external/sub/deep"],
@@ -401,7 +407,7 @@ const createMockLogger = () => ({
         },
         mockLogger
       );
-      (0, import_vitest.expect)(validator.isPathWithinAllowed("/external/sub/file.ts")).toBe(false);
+      (0, import_vitest.expect)(await validator.isPathWithinAllowed("/external/sub/file.ts")).toBe(false);
     });
   });
   (0, import_vitest.describe)("getAllowedPaths and getBlockedPaths", () => {