file-entry-cache 11.0.0-beta.1 → 11.0.0-beta.3

package/README.md

@@ -15,7 +15,7 @@
 - Ideal for processes that work on a specific set of files
 - Persists cache to Disk via `reconcile()` or `persistInterval` on `cache` options.
 - Uses `checksum` to determine if a file has changed
-- Supports `relative` and `absolute` paths - paths are stored exactly as provided
+- Supports `relative` and `absolute` paths with configurable current working directory
 - Portable cache files when using relative paths
 - ESM and CommonJS support with Typescript
 
@@ -23,11 +23,17 @@
 
 - [Installation](#installation)
 - [Getting Started](#getting-started)
+- [Changes from v10 to v11](#changes-from-v10-to-v11)
 - [Changes from v9 to v10](#changes-from-v9-to-v10)
 - [Global Default Functions](#global-default-functions)
 - [FileEntryCache Options (FileEntryCacheOptions)](#fileentrycache-options-fileentrycacheoptions)
 - [API](#api)
 - [Get File Descriptor](#get-file-descriptor)
+  - [Path Handling and Current Working Directory](#path-handling-and-current-working-directory)
+  - [Cache Portability](#cache-portability)
+  - [Maximum Portability with Checksums](#maximum-portability-with-checksums)
+  - [Handling Project Relocations](#handling-project-relocations)
+- [Path Security and Traversal Prevention](#path-security-and-traversal-prevention)
 - [Using Checksums to Determine if a File has Changed (useCheckSum)](#using-checksums-to-determine-if-a-file-has-changed-usechecksum)
 - [Setting Additional Meta Data](#setting-additional-meta-data)
 - [How to Contribute](#how-to-contribute)
@@ -78,41 +84,16 @@ let fileDescriptor = cache.getFileDescriptor('./src/file.txt');
 console.log(fileDescriptor.changed); // false as it has not changed from the saved cache.
 ```
 
-## Migration Guide from v10 to v11
-
-The main breaking change is the removal of `currentWorkingDirectory`. Here's how to update your code:
-
-**Before (v10):**
-```javascript
-const cache = new FileEntryCache({
-  currentWorkingDirectory: '/project/root'
-});
-// This would store the key as 'src/file.js'
-cache.getFileDescriptor('/project/root/src/file.js');
-```
-
-**After (v11):**
-```javascript
-const cache = new FileEntryCache();
-// Now stores the key exactly as provided
-cache.getFileDescriptor('./src/file.js');  // Key: './src/file.js'
-cache.getFileDescriptor('/project/root/src/file.js'); // Key: '/project/root/src/file.js'
-```
-
-If you were using absolute paths with `currentWorkingDirectory`, you'll need to update your code to use relative paths if you want portable cache files.
 
 # Changes from v10 to v11
 
 **BREAKING CHANGES:**
-- **Removed `currentWorkingDirectory`** - This option has been completely removed from the API. Paths are now stored exactly as provided (relative or absolute).
-- **Path handling changes** - The cache now stores paths exactly as they are provided:
-  - Relative paths remain relative in the cache
-  - Absolute paths remain absolute in the cache
-  - The same file accessed with different path formats will create separate cache entries
-- **Renamed method** - `renameAbsolutePathKeys()` is now `renameCacheKeys()` to reflect that it works with any path format
-- **Simplified API** - Removed `currentWorkingDirectory` parameter from all methods including `getFileDescriptor()`, `removeEntry()`, and factory functions
+- **`strictPaths` now defaults to `true`** - Path traversal protection is enabled by default for security. To restore v10 behavior, explicitly set `strictPaths: false`
 
-These changes make cache files portable when using relative paths, and simplify the API by removing path manipulation logic.
+**NEW FEATURES:**
+- **Added `cwd` option** - You can now specify a custom current working directory for resolving relative paths
+- **Added `strictPaths` option** - Provides protection against path traversal attacks (enabled by default)
+- **Improved cache portability** - When using relative paths with the same `cwd`, cache files are portable across different environments
 
 # Changes from v9 to v10
 
@@ -127,13 +108,15 @@ There have been many features added and changes made to the `file-entry-cache` c
 - On `FileEntryDescriptor.meta` if using typescript you need to use the `meta.data` to set additional information. This is to allow for better type checking and to avoid conflicts with the `meta` object which was `any`.
 
 # Global Default Functions
-- `create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean)` - Creates a new instance of the `FileEntryCache` class
-- `createFromFile(cachePath: string, useCheckSum?: boolean)` - Creates a new instance of the `FileEntryCache` class and loads the cache from a file.
+- `create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string)` - Creates a new instance of the `FileEntryCache` class
+- `createFromFile(cachePath: string, useCheckSum?: boolean, cwd?: string)` - Creates a new instance of the `FileEntryCache` class and loads the cache from a file.
 
 # FileEntryCache Options (FileEntryCacheOptions)
 - `useModifiedTime?` - If `true` it will use the modified time to determine if the file has changed. Default is `true`
 - `useCheckSum?` - If `true` it will use a checksum to determine if the file has changed. Default is `false`
 - `hashAlgorithm?` - The algorithm to use for the checksum. Default is `md5` but can be any algorithm supported by `crypto.createHash`
+- `cwd?` - The current working directory for resolving relative paths. Default is `process.cwd()`
+- `strictPaths?` - If `true` restricts file access to within `cwd` boundaries, preventing path traversal attacks. Default is `true`
 - `cache.ttl?` - The time to live for the cache in milliseconds. Default is `0` which means no expiration
 - `cache.lruSize?` - The number of items to keep in the cache. Default is `0` which means no limit
 - `cache.useClone?` - If `true` it will clone the data before returning it. Default is `false`
@@ -150,17 +133,21 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `useCheckSum: boolean` - If `true` it will use a checksum to determine if the file has changed. Default is `false`
 - `hashAlgorithm: string` - The algorithm to use for the checksum. Default is `md5` but can be any algorithm supported by `crypto.createHash`
 - `getHash(buffer: Buffer): string` - Gets the hash of a buffer used for checksums
+- `cwd: string` - The current working directory for resolving relative paths. Default is `process.cwd()`
+- `strictPaths: boolean` - If `true` restricts file access to within `cwd` boundaries. Default is `true`
 - `createFileKey(filePath: string): string` - Returns the cache key for the file path (returns the path exactly as provided).
 - `deleteCacheFile(): boolean` - Deletes the cache file from disk
 - `destroy(): void` - Destroys the cache. This will clear the cache in memory. If using cache persistence it will stop the interval.
-- `removeEntry(filePath: string): void` - Removes an entry from the cache using the exact path provided.
+- `removeEntry(filePath: string): void` - Removes an entry from the cache.
 - `reconcile(): void` - Saves the cache to disk and removes any files that are no longer found.
 - `hasFileChanged(filePath: string): boolean` - Checks if the file has changed. This will return `true` if the file has changed.
 - `getFileDescriptor(filePath: string, options?: { useModifiedTime?: boolean, useCheckSum?: boolean }): FileEntryDescriptor` - Gets the file descriptor for the file. Please refer to the entire section on `Get File Descriptor` for more information.
-- `normalizeEntries(entries: FileEntryDescriptor[]): FileEntryDescriptor[]` - Normalizes the entries to have the correct paths. This is used when loading the cache from disk.
+- `normalizeEntries(files?: string[]): FileDescriptor[]` - Normalizes the entries. If no files are provided, it will return all cached entries.
 - `analyzeFiles(files: string[])` will return `AnalyzedFiles` object with `changedFiles`, `notFoundFiles`, and `notChangedFiles` as FileDescriptor arrays.
 - `getUpdatedFiles(files: string[])` will return an array of `FileEntryDescriptor` objects that have changed.
 - `getFileDescriptorsByPath(filePath: string): FileEntryDescriptor[]` will return an array of `FileEntryDescriptor` objects that starts with the path prefix specified.
+- `getAbsolutePath(filePath: string): string` - Resolves a relative path to absolute using the configured `cwd`. Returns absolute paths unchanged. When `strictPaths` is enabled, throws an error if the path resolves outside `cwd`.
+- `getAbsolutePathWithCwd(filePath: string, cwd: string): string` - Resolves a relative path to absolute using a custom working directory. When `strictPaths` is enabled, throws an error if the path resolves outside the provided `cwd`.
 
 # Get File Descriptor
 
@@ -172,32 +159,94 @@ The `getFileDescriptor(filePath: string, options?: { useCheckSum?: boolean, useM
 - `meta: FileEntryMeta` - The meta data for the file. This has the following properties: `size`, `mtime`, `hash`, `data`. Note that `data` is an object that can be used to store additional information.
 - `err` - If there was an error analyzing the file.
 
-## Path Handling
+## Path Handling and Current Working Directory
+
+The cache stores paths exactly as they are provided (relative or absolute). When checking if files have changed, relative paths are resolved using the configured `cwd` (current working directory):
+
+```javascript
+// Default: uses process.cwd()
+const cache1 = fileEntryCache.create('cache1');
+
+// Custom working directory
+const cache2 = fileEntryCache.create('cache2', './cache', false, '/project/root');
+// Or with options object
+const cache3 = new FileEntryCache({ cwd: '/project/root' });
+
+// The cache key is always the provided path
+const descriptor = cache2.getFileDescriptor('./src/file.txt');
+console.log(descriptor.key); // './src/file.txt'
+// But file operations resolve from: '/project/root/src/file.txt'
+```
 
-The cache stores paths exactly as they are provided:
+### Cache Portability
 
-- **Relative paths** remain relative in the cache
-- **Absolute paths** remain absolute in the cache
-- The same file accessed with different path formats creates **separate cache entries**
+Using relative paths with a consistent `cwd` (defaults to `process.cwd()`) makes cache files portable across different machines and environments. This is especially useful for CI/CD pipelines and team development.
 
 ```javascript
-const fileEntryCache = new FileEntryCache();
+// On machine A (project at /home/user/project)
+const cacheA = fileEntryCache.create('build-cache', './cache', false, '/home/user/project');
+cacheA.getFileDescriptor('./src/index.js'); // Resolves to /home/user/project/src/index.js
+cacheA.reconcile();
+
+// On machine B (project at /workspace/project)
+const cacheB = fileEntryCache.create('build-cache', './cache', false, '/workspace/project');
+cacheB.getFileDescriptor('./src/index.js'); // Resolves to /workspace/project/src/index.js
+// Cache hit! File hasn't changed since machine A
+```
 
-// Using a relative path
-const relativeDescriptor = fileEntryCache.getFileDescriptor('./file.txt');
-console.log(relativeDescriptor.key); // './file.txt'
+### Maximum Portability with Checksums
 
-// Using an absolute path
-const absolutePath = path.resolve('./file.txt');
-const absoluteDescriptor = fileEntryCache.getFileDescriptor(absolutePath);
-console.log(absoluteDescriptor.key); // '/full/path/to/file.txt'
+For maximum cache portability across different environments, use checksums (`useCheckSum: true`) along with relative paths and `cwd` which defaults to `process.cwd()`. This ensures that cache validity is determined by file content rather than modification times, which can vary across systems:
 
-// These create two separate cache entries even though they refer to the same file
+```javascript
+// Development machine
+const devCache = fileEntryCache.create(
+    '.buildcache',
+    './cache',                 // cache directory
+    true                      // Use checksums for content-based comparison
+);
+
+// Process files using relative paths
+const descriptor = devCache.getFileDescriptor('./src/index.js');
+if (descriptor.changed) {
+    console.log('Building ./src/index.js...');
+    // Build process here
+}
+devCache.reconcile(); // Save cache
+
+// CI/CD Pipeline or another developer's machine
+const ciCache = fileEntryCache.create(
+    '.buildcache',
+    './node_modules/.cache',
+    true,                      // Same checksum setting
+    process.cwd()              // Different absolute path, same relative structure
+);
+
+// Same relative path works across environments
+const descriptor2 = ciCache.getFileDescriptor('./src/index.js');
+if (!descriptor2.changed) {
+    console.log('Using cached result for ./src/index.js');
+    // Skip rebuild - file content unchanged
+}
 ```
 
-This behavior makes cache files portable when using relative paths, as they will work correctly when the project is moved to a different location.
+### Handling Project Relocations
+
+Cache remains valid even when projects are moved or renamed:
+
+```javascript
+// Original location: /projects/my-app
+const cache1 = fileEntryCache.create('.cache', './cache', true, '/projects/my-app');
+cache1.getFileDescriptor('./src/app.js');
+cache1.reconcile();
+
+// After moving project to: /archived/2024/my-app
+const cache2 = fileEntryCache.create('.cache', './cache', true, '/archived/2024/my-app');
+cache2.getFileDescriptor('./src/app.js'); // Still finds cached entry!
+// Cache valid as long as relative structure unchanged
+```
 
-If there is an error when trying to get the file descriptor it will return an ``notFound` and `err` property with the error.
+If there is an error when trying to get the file descriptor it will return a `notFound` and `err` property with the error.
 
 ```javascript
 const fileEntryCache = new FileEntryCache();
@@ -211,6 +260,124 @@ if (fileDescriptor.notFound) {
 }
 ```
 
+# Path Security and Traversal Prevention
+
+The `strictPaths` option provides security against path traversal attacks by restricting file access to within the configured `cwd` boundaries. **This is enabled by default (since v11)** to ensure secure defaults when processing untrusted input or when running in security-sensitive environments.
+
+## Basic Usage
+
+```javascript
+// strictPaths is enabled by default for security
+const cache = new FileEntryCache({
+    cwd: '/project/root'
+});
+
+// This will work - file is within cwd
+const descriptor = cache.getFileDescriptor('./src/index.js');
+
+// This will throw an error - attempts to access parent directory
+try {
+    cache.getFileDescriptor('../../../etc/passwd');
+} catch (error) {
+    console.error(error); // Path traversal attempt blocked
+}
+
+// To allow parent directory access (not recommended for untrusted input)
+const unsafeCache = new FileEntryCache({
+    cwd: '/project/root',
+    strictPaths: false  // Explicitly disable protection
+});
+```
+
+## Security Features
+
+When `strictPaths` is enabled:
+- **Path Traversal Prevention**: Blocks attempts to access files outside the working directory using `../` sequences
+- **Null Byte Protection**: Automatically removes null bytes from paths to prevent injection attacks
+- **Path Normalization**: Cleans and normalizes paths to prevent bypass attempts
+
+## Use Cases
+
+### Build Tools with Untrusted Input
+```javascript
+// Secure build tool configuration
+const cache = fileEntryCache.create(
+    '.buildcache',
+    './cache',
+    true,  // useCheckSum
+    process.cwd()
+);
+
+// Enable strict path checking for security
+cache.strictPaths = true;
+
+// Process user-provided file paths safely
+function processUserFile(userProvidedPath) {
+    try {
+        const descriptor = cache.getFileDescriptor(userProvidedPath);
+        // Safe to process - file is within boundaries
+        return descriptor;
+    } catch (error) {
+        if (error.message.includes('Path traversal attempt blocked')) {
+            console.warn('Security: Blocked access to:', userProvidedPath);
+            return null;
+        }
+        throw error;
+    }
+}
+```
+
+### CI/CD Environments
+```javascript
+// Strict security for CI/CD pipelines
+const cache = new FileEntryCache({
+    cwd: process.env.GITHUB_WORKSPACE || process.cwd(),
+    strictPaths: true,  // Prevent access outside workspace
+    useCheckSum: true   // Content-based validation
+});
+
+// All file operations are now restricted to the workspace
+cache.getFileDescriptor('./src/app.js');  // ✓ Allowed
+cache.getFileDescriptor('/etc/passwd');   // ✗ Blocked (absolute path outside cwd)
+cache.getFileDescriptor('../../../root'); // ✗ Blocked (path traversal)
+```
+
+### Dynamic Security Control
+```javascript
+const cache = new FileEntryCache({ cwd: '/safe/directory' });
+
+// Start with relaxed mode for trusted operations
+cache.strictPaths = false;
+processInternalFiles();
+
+// Enable strict mode for untrusted input
+cache.strictPaths = true;
+processUserUploadedPaths();
+
+// Return to relaxed mode if needed
+cache.strictPaths = false;
+```
+
+## Default Behavior
+
+**As of v11, `strictPaths` is enabled by default** to provide secure defaults. This means:
+- Path traversal attempts using `../` are blocked
+- File access is restricted to within the configured `cwd`
+- Null bytes in paths are automatically sanitized
+
+### Migrating from v10 or Earlier
+
+If you're upgrading from v10 or earlier and need to maintain the previous behavior (for example, if your code legitimately accesses parent directories), you can explicitly disable strict paths:
+
+```javascript
+const cache = new FileEntryCache({
+    cwd: process.cwd(),
+    strictPaths: false  // Restore v10 behavior
+});
+```
+
+However, we strongly recommend keeping `strictPaths: true` and adjusting your code to work within the security boundaries, especially when processing any untrusted input.
+
 # Using Checksums to Determine if a File has Changed (useCheckSum)
 
 By default the `useCheckSum` is `false`. This means that the `FileEntryCache` will use the `mtime` and `ctime` to determine if the file has changed. If you set `useCheckSum` to `true` it will use a checksum to determine if the file has changed. This is useful when you want to make sure that the file has not changed at all. 

package/dist/index.cjs

@@ -40,14 +40,15 @@ var import_node_crypto = __toESM(require("crypto"), 1);
 var import_node_fs = __toESM(require("fs"), 1);
 var import_node_path = __toESM(require("path"), 1);
 var import_flat_cache = require("flat-cache");
-function createFromFile(filePath, useCheckSum) {
+function createFromFile(filePath, useCheckSum, cwd) {
   const fname = import_node_path.default.basename(filePath);
   const directory = import_node_path.default.dirname(filePath);
-  return create(fname, directory, useCheckSum);
+  return create(fname, directory, useCheckSum, cwd);
 }
-function create(cacheId, cacheDirectory, useCheckSum) {
+function create(cacheId, cacheDirectory, useCheckSum, cwd) {
   const options = {
     useCheckSum,
+    cwd,
     cache: {
       cacheId,
       cacheDir: cacheDirectory
@@ -69,25 +70,29 @@ var FileEntryDefault = class {
 var FileEntryCache = class {
   _cache = new import_flat_cache.FlatCache({ useClone: false });
   _useCheckSum = false;
-  _useModifiedTime = true;
   _hashAlgorithm = "md5";
+  _cwd = process.cwd();
+  _strictPaths = true;
   /**
    * Create a new FileEntryCache instance
-   * @param options - The options for the FileEntryCache
+   * @param options - The options for the FileEntryCache (all properties are optional with defaults)
    */
   constructor(options) {
     if (options?.cache) {
       this._cache = new import_flat_cache.FlatCache(options.cache);
     }
-    if (options?.useModifiedTime) {
-      this._useModifiedTime = options.useModifiedTime;
-    }
     if (options?.useCheckSum) {
       this._useCheckSum = options.useCheckSum;
     }
     if (options?.hashAlgorithm) {
       this._hashAlgorithm = options.hashAlgorithm;
     }
+    if (options?.cwd) {
+      this._cwd = options.cwd;
+    }
+    if (options?.strictPaths !== void 0) {
+      this._strictPaths = options.strictPaths;
+    }
   }
   /**
    * Get the cache
@@ -105,7 +110,7 @@ var FileEntryCache = class {
   }
   /**
    * Use the hash to check if the file has changed
-   * @returns {boolean} if the hash is used to check if the file has changed
+   * @returns {boolean} if the hash is used to check if the file has changed (default: false)
    */
   get useCheckSum() {
     return this._useCheckSum;
@@ -117,23 +122,9 @@ var FileEntryCache = class {
   set useCheckSum(value) {
     this._useCheckSum = value;
   }
-  /**
-   * Use the modified time to check if the file has changed
-   * @returns {boolean} if the modified time is used to check if the file has changed
-   */
-  get useModifiedTime() {
-    return this._useModifiedTime;
-  }
-  /**
-   * Set the useModifiedTime value
-   * @param {boolean} value - The value to set
-   */
-  set useModifiedTime(value) {
-    this._useModifiedTime = value;
-  }
   /**
    * Get the hash algorithm
-   * @returns {string} The hash algorithm
+   * @returns {string} The hash algorithm (default: 'md5')
    */
   get hashAlgorithm() {
     return this._hashAlgorithm;
@@ -145,6 +136,34 @@ var FileEntryCache = class {
   set hashAlgorithm(value) {
     this._hashAlgorithm = value;
   }
+  /**
+   * Get the current working directory
+   * @returns {string} The current working directory (default: process.cwd())
+   */
+  get cwd() {
+    return this._cwd;
+  }
+  /**
+   * Set the current working directory
+   * @param {string} value - The value to set
+   */
+  set cwd(value) {
+    this._cwd = value;
+  }
+  /**
+   * Get whether to restrict paths to cwd boundaries
+   * @returns {boolean} Whether strict path checking is enabled (default: true)
+   */
+  get strictPaths() {
+    return this._strictPaths;
+  }
+  /**
+   * Set whether to restrict paths to cwd boundaries
+   * @param {boolean} value - The value to set
+   */
+  set strictPaths(value) {
+    this._strictPaths = value;
+  }
   /**
    * Given a buffer, calculate md5 hash of its content.
    * @method getHash
@@ -241,7 +260,6 @@ var FileEntryCache = class {
     result.meta = this._cache.getKey(result.key) ?? {};
     const absolutePath = this.getAbsolutePath(filePath);
     const useCheckSumValue = options?.useCheckSum ?? this._useCheckSum;
-    const useModifiedTimeValue = options?.useModifiedTime ?? this._useModifiedTime;
     try {
       fstat = import_node_fs.default.statSync(absolutePath);
       result.meta = {
@@ -274,7 +292,7 @@ var FileEntryCache = class {
     if (result.meta.data === void 0) {
       result.meta.data = metaCache.data;
     }
-    if (useModifiedTimeValue && metaCache?.mtime !== result.meta?.mtime) {
+    if (useCheckSumValue === false && metaCache?.mtime !== result.meta?.mtime) {
       result.changed = true;
     }
     if (metaCache?.size !== result.meta?.size) {
@@ -369,13 +387,54 @@ var FileEntryCache = class {
   }
   /**
    * Get the Absolute Path. If it is already absolute it will return the path as is.
+   * When strictPaths is enabled, ensures the resolved path stays within cwd boundaries.
    * @method getAbsolutePath
    * @param filePath - The file path to get the absolute path for
    * @returns {string}
+   * @throws {Error} When strictPaths is true and path would resolve outside cwd
    */
   getAbsolutePath(filePath) {
     if (this.isRelativePath(filePath)) {
-      return import_node_path.default.resolve(process.cwd(), filePath);
+      const sanitizedPath = filePath.replace(/\0/g, "");
+      const resolved = import_node_path.default.resolve(this._cwd, sanitizedPath);
+      if (this._strictPaths) {
+        const normalizedResolved = import_node_path.default.normalize(resolved);
+        const normalizedCwd = import_node_path.default.normalize(this._cwd);
+        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + import_node_path.default.sep);
+        if (!isWithinCwd) {
+          throw new Error(
+            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${this._cwd}"`
+          );
+        }
+      }
+      return resolved;
+    }
+    return filePath;
+  }
+  /**
+   * Get the Absolute Path with a custom working directory. If it is already absolute it will return the path as is.
+   * When strictPaths is enabled, ensures the resolved path stays within the provided cwd boundaries.
+   * @method getAbsolutePathWithCwd
+   * @param filePath - The file path to get the absolute path for
+   * @param cwd - The custom working directory to resolve relative paths from
+   * @returns {string}
+   * @throws {Error} When strictPaths is true and path would resolve outside the provided cwd
+   */
+  getAbsolutePathWithCwd(filePath, cwd) {
+    if (this.isRelativePath(filePath)) {
+      const sanitizedPath = filePath.replace(/\0/g, "");
+      const resolved = import_node_path.default.resolve(cwd, sanitizedPath);
+      if (this._strictPaths) {
+        const normalizedResolved = import_node_path.default.normalize(resolved);
+        const normalizedCwd = import_node_path.default.normalize(cwd);
+        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + import_node_path.default.sep);
+        if (!isWithinCwd) {
+          throw new Error(
+            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${cwd}"`
+          );
+        }
+      }
+      return resolved;
     }
     return filePath;
   }

package/dist/index.d.cts

@@ -2,35 +2,70 @@ import { Buffer } from 'node:buffer';
 import { FlatCacheOptions, FlatCache } from 'flat-cache';
 
 type FileEntryCacheOptions = {
+    /** Whether to use file modified time for change detection (default: true) */
     useModifiedTime?: boolean;
+    /** Whether to use checksum for change detection (default: false) */
     useCheckSum?: boolean;
+    /** Hash algorithm to use for checksum (default: 'md5') */
     hashAlgorithm?: string;
+    /** Current working directory for resolving relative paths (default: process.cwd()) */
+    cwd?: string;
+    /** Restrict file access to within cwd boundaries (default: true) */
+    strictPaths?: boolean;
+    /** Options for the underlying flat cache */
     cache?: FlatCacheOptions;
 };
 type GetFileDescriptorOptions = {
+    /** Whether to use checksum for this specific file check instead of modified time (mtime) (overrides instance setting) */
     useCheckSum?: boolean;
-    useModifiedTime?: boolean;
 };
 type FileDescriptor = {
+    /** The cache key for this file (typically the file path) */
     key: string;
+    /** Whether the file has changed since last cache check */
     changed?: boolean;
+    /** Metadata about the file */
     meta: FileDescriptorMeta;
+    /** Whether the file was not found */
     notFound?: boolean;
+    /** Error encountered when accessing the file */
     err?: Error;
 };
 type FileDescriptorMeta = {
+    /** File size in bytes */
     size?: number;
+    /** File modification time (timestamp in milliseconds) */
     mtime?: number;
+    /** File content hash (when useCheckSum is enabled) */
     hash?: string;
+    /** Custom data associated with the file (e.g., lint results, metadata) */
     data?: unknown;
 };
 type AnalyzedFiles = {
+    /** Array of file paths that have changed since last cache */
     changedFiles: string[];
+    /** Array of file paths that were not found */
     notFoundFiles: string[];
+    /** Array of file paths that have not changed since last cache */
     notChangedFiles: string[];
 };
-declare function createFromFile(filePath: string, useCheckSum?: boolean): FileEntryCache;
-declare function create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean): FileEntryCache;
+/**
+ * Create a new FileEntryCache instance from a file path
+ * @param filePath - The path to the cache file
+ * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
+ * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @returns A new FileEntryCache instance
+ */
+declare function createFromFile(filePath: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
+/**
+ * Create a new FileEntryCache instance
+ * @param cacheId - The cache file name
+ * @param cacheDirectory - The directory to store the cache file (default: undefined, cache won't be persisted)
+ * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
+ * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @returns A new FileEntryCache instance
+ */
+declare function create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
 declare class FileEntryDefault {
     static create: typeof create;
     static createFromFile: typeof createFromFile;
@@ -38,11 +73,12 @@ declare class FileEntryDefault {
 declare class FileEntryCache {
     private _cache;
     private _useCheckSum;
-    private _useModifiedTime;
     private _hashAlgorithm;
+    private _cwd;
+    private _strictPaths;
     /**
      * Create a new FileEntryCache instance
-     * @param options - The options for the FileEntryCache
+     * @param options - The options for the FileEntryCache (all properties are optional with defaults)
      */
     constructor(options?: FileEntryCacheOptions);
     /**
@@ -57,7 +93,7 @@ declare class FileEntryCache {
     set cache(cache: FlatCache);
     /**
      * Use the hash to check if the file has changed
-     * @returns {boolean} if the hash is used to check if the file has changed
+     * @returns {boolean} if the hash is used to check if the file has changed (default: false)
      */
     get useCheckSum(): boolean;
     /**
@@ -65,19 +101,9 @@ declare class FileEntryCache {
      * @param {boolean} value - The value to set
      */
     set useCheckSum(value: boolean);
-    /**
-     * Use the modified time to check if the file has changed
-     * @returns {boolean} if the modified time is used to check if the file has changed
-     */
-    get useModifiedTime(): boolean;
-    /**
-     * Set the useModifiedTime value
-     * @param {boolean} value - The value to set
-     */
-    set useModifiedTime(value: boolean);
     /**
      * Get the hash algorithm
-     * @returns {string} The hash algorithm
+     * @returns {string} The hash algorithm (default: 'md5')
      */
     get hashAlgorithm(): string;
     /**
@@ -85,6 +111,26 @@ declare class FileEntryCache {
      * @param {string} value - The value to set
      */
     set hashAlgorithm(value: string);
+    /**
+     * Get the current working directory
+     * @returns {string} The current working directory (default: process.cwd())
+     */
+    get cwd(): string;
+    /**
+     * Set the current working directory
+     * @param {string} value - The value to set
+     */
+    set cwd(value: string);
+    /**
+     * Get whether to restrict paths to cwd boundaries
+     * @returns {boolean} Whether strict path checking is enabled (default: true)
+     */
+    get strictPaths(): boolean;
+    /**
+     * Set whether to restrict paths to cwd boundaries
+     * @param {boolean} value - The value to set
+     */
+    set strictPaths(value: boolean);
     /**
      * Given a buffer, calculate md5 hash of its content.
      * @method getHash
@@ -173,11 +219,23 @@ declare class FileEntryCache {
     getFileDescriptorsByPath(filePath: string): FileDescriptor[];
     /**
      * Get the Absolute Path. If it is already absolute it will return the path as is.
+     * When strictPaths is enabled, ensures the resolved path stays within cwd boundaries.
      * @method getAbsolutePath
      * @param filePath - The file path to get the absolute path for
      * @returns {string}
+     * @throws {Error} When strictPaths is true and path would resolve outside cwd
      */
     getAbsolutePath(filePath: string): string;
+    /**
+     * Get the Absolute Path with a custom working directory. If it is already absolute it will return the path as is.
+     * When strictPaths is enabled, ensures the resolved path stays within the provided cwd boundaries.
+     * @method getAbsolutePathWithCwd
+     * @param filePath - The file path to get the absolute path for
+     * @param cwd - The custom working directory to resolve relative paths from
+     * @returns {string}
+     * @throws {Error} When strictPaths is true and path would resolve outside the provided cwd
+     */
+    getAbsolutePathWithCwd(filePath: string, cwd: string): string;
     /**
      * Rename cache keys that start with a given path prefix.
      * @method renameCacheKeys

package/dist/index.d.ts

@@ -2,35 +2,70 @@ import { Buffer } from 'node:buffer';
 import { FlatCacheOptions, FlatCache } from 'flat-cache';
 
 type FileEntryCacheOptions = {
+    /** Whether to use file modified time for change detection (default: true) */
     useModifiedTime?: boolean;
+    /** Whether to use checksum for change detection (default: false) */
     useCheckSum?: boolean;
+    /** Hash algorithm to use for checksum (default: 'md5') */
     hashAlgorithm?: string;
+    /** Current working directory for resolving relative paths (default: process.cwd()) */
+    cwd?: string;
+    /** Restrict file access to within cwd boundaries (default: true) */
+    strictPaths?: boolean;
+    /** Options for the underlying flat cache */
     cache?: FlatCacheOptions;
 };
 type GetFileDescriptorOptions = {
+    /** Whether to use checksum for this specific file check instead of modified time (mtime) (overrides instance setting) */
     useCheckSum?: boolean;
-    useModifiedTime?: boolean;
 };
 type FileDescriptor = {
+    /** The cache key for this file (typically the file path) */
     key: string;
+    /** Whether the file has changed since last cache check */
     changed?: boolean;
+    /** Metadata about the file */
     meta: FileDescriptorMeta;
+    /** Whether the file was not found */
     notFound?: boolean;
+    /** Error encountered when accessing the file */
     err?: Error;
 };
 type FileDescriptorMeta = {
+    /** File size in bytes */
     size?: number;
+    /** File modification time (timestamp in milliseconds) */
     mtime?: number;
+    /** File content hash (when useCheckSum is enabled) */
     hash?: string;
+    /** Custom data associated with the file (e.g., lint results, metadata) */
     data?: unknown;
 };
 type AnalyzedFiles = {
+    /** Array of file paths that have changed since last cache */
     changedFiles: string[];
+    /** Array of file paths that were not found */
     notFoundFiles: string[];
+    /** Array of file paths that have not changed since last cache */
     notChangedFiles: string[];
 };
-declare function createFromFile(filePath: string, useCheckSum?: boolean): FileEntryCache;
-declare function create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean): FileEntryCache;
+/**
+ * Create a new FileEntryCache instance from a file path
+ * @param filePath - The path to the cache file
+ * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
+ * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @returns A new FileEntryCache instance
+ */
+declare function createFromFile(filePath: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
+/**
+ * Create a new FileEntryCache instance
+ * @param cacheId - The cache file name
+ * @param cacheDirectory - The directory to store the cache file (default: undefined, cache won't be persisted)
+ * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
+ * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @returns A new FileEntryCache instance
+ */
+declare function create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
 declare class FileEntryDefault {
     static create: typeof create;
     static createFromFile: typeof createFromFile;
@@ -38,11 +73,12 @@ declare class FileEntryDefault {
 declare class FileEntryCache {
     private _cache;
     private _useCheckSum;
-    private _useModifiedTime;
     private _hashAlgorithm;
+    private _cwd;
+    private _strictPaths;
     /**
      * Create a new FileEntryCache instance
-     * @param options - The options for the FileEntryCache
+     * @param options - The options for the FileEntryCache (all properties are optional with defaults)
      */
     constructor(options?: FileEntryCacheOptions);
     /**
@@ -57,7 +93,7 @@ declare class FileEntryCache {
     set cache(cache: FlatCache);
     /**
      * Use the hash to check if the file has changed
-     * @returns {boolean} if the hash is used to check if the file has changed
+     * @returns {boolean} if the hash is used to check if the file has changed (default: false)
      */
     get useCheckSum(): boolean;
     /**
@@ -65,19 +101,9 @@ declare class FileEntryCache {
      * @param {boolean} value - The value to set
      */
     set useCheckSum(value: boolean);
-    /**
-     * Use the modified time to check if the file has changed
-     * @returns {boolean} if the modified time is used to check if the file has changed
-     */
-    get useModifiedTime(): boolean;
-    /**
-     * Set the useModifiedTime value
-     * @param {boolean} value - The value to set
-     */
-    set useModifiedTime(value: boolean);
     /**
      * Get the hash algorithm
-     * @returns {string} The hash algorithm
+     * @returns {string} The hash algorithm (default: 'md5')
      */
     get hashAlgorithm(): string;
     /**
@@ -85,6 +111,26 @@ declare class FileEntryCache {
      * @param {string} value - The value to set
      */
     set hashAlgorithm(value: string);
+    /**
+     * Get the current working directory
+     * @returns {string} The current working directory (default: process.cwd())
+     */
+    get cwd(): string;
+    /**
+     * Set the current working directory
+     * @param {string} value - The value to set
+     */
+    set cwd(value: string);
+    /**
+     * Get whether to restrict paths to cwd boundaries
+     * @returns {boolean} Whether strict path checking is enabled (default: true)
+     */
+    get strictPaths(): boolean;
+    /**
+     * Set whether to restrict paths to cwd boundaries
+     * @param {boolean} value - The value to set
+     */
+    set strictPaths(value: boolean);
     /**
      * Given a buffer, calculate md5 hash of its content.
      * @method getHash
@@ -173,11 +219,23 @@ declare class FileEntryCache {
     getFileDescriptorsByPath(filePath: string): FileDescriptor[];
     /**
      * Get the Absolute Path. If it is already absolute it will return the path as is.
+     * When strictPaths is enabled, ensures the resolved path stays within cwd boundaries.
      * @method getAbsolutePath
      * @param filePath - The file path to get the absolute path for
      * @returns {string}
+     * @throws {Error} When strictPaths is true and path would resolve outside cwd
      */
     getAbsolutePath(filePath: string): string;
+    /**
+     * Get the Absolute Path with a custom working directory. If it is already absolute it will return the path as is.
+     * When strictPaths is enabled, ensures the resolved path stays within the provided cwd boundaries.
+     * @method getAbsolutePathWithCwd
+     * @param filePath - The file path to get the absolute path for
+     * @param cwd - The custom working directory to resolve relative paths from
+     * @returns {string}
+     * @throws {Error} When strictPaths is true and path would resolve outside the provided cwd
+     */
+    getAbsolutePathWithCwd(filePath: string, cwd: string): string;
     /**
      * Rename cache keys that start with a given path prefix.
      * @method renameCacheKeys

package/dist/index.js

@@ -6,14 +6,15 @@ import {
   createFromFile as createFlatCacheFile,
   FlatCache
 } from "flat-cache";
-function createFromFile(filePath, useCheckSum) {
+function createFromFile(filePath, useCheckSum, cwd) {
   const fname = path.basename(filePath);
   const directory = path.dirname(filePath);
-  return create(fname, directory, useCheckSum);
+  return create(fname, directory, useCheckSum, cwd);
 }
-function create(cacheId, cacheDirectory, useCheckSum) {
+function create(cacheId, cacheDirectory, useCheckSum, cwd) {
   const options = {
     useCheckSum,
+    cwd,
     cache: {
       cacheId,
       cacheDir: cacheDirectory
@@ -35,25 +36,29 @@ var FileEntryDefault = class {
 var FileEntryCache = class {
   _cache = new FlatCache({ useClone: false });
   _useCheckSum = false;
-  _useModifiedTime = true;
   _hashAlgorithm = "md5";
+  _cwd = process.cwd();
+  _strictPaths = true;
   /**
    * Create a new FileEntryCache instance
-   * @param options - The options for the FileEntryCache
+   * @param options - The options for the FileEntryCache (all properties are optional with defaults)
    */
   constructor(options) {
     if (options?.cache) {
       this._cache = new FlatCache(options.cache);
     }
-    if (options?.useModifiedTime) {
-      this._useModifiedTime = options.useModifiedTime;
-    }
     if (options?.useCheckSum) {
       this._useCheckSum = options.useCheckSum;
     }
     if (options?.hashAlgorithm) {
       this._hashAlgorithm = options.hashAlgorithm;
     }
+    if (options?.cwd) {
+      this._cwd = options.cwd;
+    }
+    if (options?.strictPaths !== void 0) {
+      this._strictPaths = options.strictPaths;
+    }
   }
   /**
    * Get the cache
@@ -71,7 +76,7 @@ var FileEntryCache = class {
   }
   /**
    * Use the hash to check if the file has changed
-   * @returns {boolean} if the hash is used to check if the file has changed
+   * @returns {boolean} if the hash is used to check if the file has changed (default: false)
    */
   get useCheckSum() {
     return this._useCheckSum;
@@ -83,23 +88,9 @@ var FileEntryCache = class {
   set useCheckSum(value) {
     this._useCheckSum = value;
   }
-  /**
-   * Use the modified time to check if the file has changed
-   * @returns {boolean} if the modified time is used to check if the file has changed
-   */
-  get useModifiedTime() {
-    return this._useModifiedTime;
-  }
-  /**
-   * Set the useModifiedTime value
-   * @param {boolean} value - The value to set
-   */
-  set useModifiedTime(value) {
-    this._useModifiedTime = value;
-  }
   /**
    * Get the hash algorithm
-   * @returns {string} The hash algorithm
+   * @returns {string} The hash algorithm (default: 'md5')
    */
   get hashAlgorithm() {
     return this._hashAlgorithm;
@@ -111,6 +102,34 @@ var FileEntryCache = class {
   set hashAlgorithm(value) {
     this._hashAlgorithm = value;
   }
+  /**
+   * Get the current working directory
+   * @returns {string} The current working directory (default: process.cwd())
+   */
+  get cwd() {
+    return this._cwd;
+  }
+  /**
+   * Set the current working directory
+   * @param {string} value - The value to set
+   */
+  set cwd(value) {
+    this._cwd = value;
+  }
+  /**
+   * Get whether to restrict paths to cwd boundaries
+   * @returns {boolean} Whether strict path checking is enabled (default: true)
+   */
+  get strictPaths() {
+    return this._strictPaths;
+  }
+  /**
+   * Set whether to restrict paths to cwd boundaries
+   * @param {boolean} value - The value to set
+   */
+  set strictPaths(value) {
+    this._strictPaths = value;
+  }
   /**
    * Given a buffer, calculate md5 hash of its content.
    * @method getHash
@@ -207,7 +226,6 @@ var FileEntryCache = class {
     result.meta = this._cache.getKey(result.key) ?? {};
     const absolutePath = this.getAbsolutePath(filePath);
     const useCheckSumValue = options?.useCheckSum ?? this._useCheckSum;
-    const useModifiedTimeValue = options?.useModifiedTime ?? this._useModifiedTime;
     try {
       fstat = fs.statSync(absolutePath);
       result.meta = {
@@ -240,7 +258,7 @@ var FileEntryCache = class {
     if (result.meta.data === void 0) {
       result.meta.data = metaCache.data;
     }
-    if (useModifiedTimeValue && metaCache?.mtime !== result.meta?.mtime) {
+    if (useCheckSumValue === false && metaCache?.mtime !== result.meta?.mtime) {
       result.changed = true;
     }
     if (metaCache?.size !== result.meta?.size) {
@@ -335,13 +353,54 @@ var FileEntryCache = class {
   }
   /**
    * Get the Absolute Path. If it is already absolute it will return the path as is.
+   * When strictPaths is enabled, ensures the resolved path stays within cwd boundaries.
    * @method getAbsolutePath
    * @param filePath - The file path to get the absolute path for
    * @returns {string}
+   * @throws {Error} When strictPaths is true and path would resolve outside cwd
    */
   getAbsolutePath(filePath) {
     if (this.isRelativePath(filePath)) {
-      return path.resolve(process.cwd(), filePath);
+      const sanitizedPath = filePath.replace(/\0/g, "");
+      const resolved = path.resolve(this._cwd, sanitizedPath);
+      if (this._strictPaths) {
+        const normalizedResolved = path.normalize(resolved);
+        const normalizedCwd = path.normalize(this._cwd);
+        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + path.sep);
+        if (!isWithinCwd) {
+          throw new Error(
+            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${this._cwd}"`
+          );
+        }
+      }
+      return resolved;
+    }
+    return filePath;
+  }
+  /**
+   * Get the Absolute Path with a custom working directory. If it is already absolute it will return the path as is.
+   * When strictPaths is enabled, ensures the resolved path stays within the provided cwd boundaries.
+   * @method getAbsolutePathWithCwd
+   * @param filePath - The file path to get the absolute path for
+   * @param cwd - The custom working directory to resolve relative paths from
+   * @returns {string}
+   * @throws {Error} When strictPaths is true and path would resolve outside the provided cwd
+   */
+  getAbsolutePathWithCwd(filePath, cwd) {
+    if (this.isRelativePath(filePath)) {
+      const sanitizedPath = filePath.replace(/\0/g, "");
+      const resolved = path.resolve(cwd, sanitizedPath);
+      if (this._strictPaths) {
+        const normalizedResolved = path.normalize(resolved);
+        const normalizedCwd = path.normalize(cwd);
+        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + path.sep);
+        if (!isWithinCwd) {
+          throw new Error(
+            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${cwd}"`
+          );
+        }
+      }
+      return resolved;
     }
     return filePath;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-entry-cache",
-  "version": "11.0.0-beta.1",
+  "version": "11.0.0-beta.3",
   "description": "A lightweight cache for file metadata, ideal for processes that work on a specific set of files and only need to reprocess files that have changed since the last run",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,16 +29,16 @@
     "cache"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.2.4",
-    "@types/node": "^24.5.0",
+    "@biomejs/biome": "^2.2.5",
+    "@types/node": "^24.6.2",
     "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
+    "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "flat-cache": "^6.1.14"
+    "flat-cache": "^6.1.17"
   },
   "files": [
     "dist",