vfs: add overlay mode for selective file interception

Add overlay mode to VirtualFileSystem that only intercepts paths
that exist in the VFS, allowing real filesystem access to fall
through for non-mocked files. This enables use cases like the
test runner mock fs where specific files are mocked while allowing
access to real files.

Changes:
- Add `overlay` option to VirtualFileSystem constructor
- Modify shouldHandle() to check file existence in overlay mode
- Add `overlay` property getter
- Update test runner mock to use VFS with overlay mode
- Use path.dirname() instead of string manipulation in mock.js
- Rename isMounted to mounted for consistency
- Add security documentation for overlay mode risks
- Add comprehensive tests for overlay mode including worker threads

Author: mcollina

doc/api/vfs.md

@@ -116,6 +116,11 @@ added: REPLACEME
     loading modules from the VFS. **Default:** `true`.
   * `virtualCwd` {boolean} Whether to enable virtual working directory support.
     **Default:** `false`.
+  * `overlay` {boolean} Whether to enable overlay mode. In overlay mode, the VFS
+    only intercepts paths that exist in the VFS, allowing other paths to fall
+    through to the real file system. Useful for mocking specific files while
+    leaving others unchanged. See [Security considerations][] for important
+    warnings. **Default:** `false`.
 * Returns: {VirtualFileSystem}
 
 Creates a new `VirtualFileSystem` instance. If no provider is specified, a
@@ -232,7 +237,7 @@ accessible through the `fs` module. The VFS can be remounted at the same or a
 different path by calling `mount()` again. Unmounting also resets the virtual
 working directory if one was set.
 
-### `vfs.isMounted`
+### `vfs.mounted`
 
 <!-- YAML
 added: REPLACEME
@@ -242,6 +247,18 @@ added: REPLACEME
 
 Returns `true` if the VFS is currently mounted.
 
+### `vfs.overlay`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+Returns `true` if overlay mode is enabled. In overlay mode, the VFS only
+intercepts paths that exist in the VFS, allowing other paths to fall through
+to the real file system.
+
 ### `vfs.mountPoint`
 
 <!-- YAML
@@ -722,6 +739,33 @@ maliciousVfs.mount('/etc');  // Shadows /etc/passwd!
 // Now fs.readFileSync('/etc/passwd') returns 'malicious content'
 ```
 
+### Overlay mode risks
+
+Overlay mode (`{ overlay: true }`) allows a VFS to selectively intercept file
+operations only for paths that exist in the VFS. While this is useful for
+mocking specific files in tests, it can also be exploited to covertly intercept
+access to specific files:
+
+```cjs
+// WARNING: Example of dangerous behavior - DO NOT DO THIS
+const vfs = require('node:vfs');
+
+// Create an overlay VFS that intercepts a specific file
+const spyVfs = vfs.create(new vfs.MemoryProvider(), { overlay: true });
+spyVfs.writeFileSync('/etc/shadow', 'intercepted!');
+spyVfs.mount('/');  // Mount at root with overlay mode
+
+// Only /etc/shadow is intercepted, other files work normally
+fs.readFileSync('/etc/passwd');  // Real file (works normally)
+fs.readFileSync('/etc/shadow');  // Returns 'intercepted!' (mocked)
+```
+
+This is particularly dangerous because:
+
+* It's harder to detect than full path shadowing
+* Only specific targeted files are affected
+* Other operations appear to work normally
+
 ### Recommendations
 
 * **Audit dependencies**: Be cautious of third-party modules that use VFS, as

lib/internal/test_runner/mock/mock.js

@@ -51,11 +51,11 @@ const {
 const { MockTimers } = require('internal/test_runner/mock/mock_timers');
 const { Module } = require('internal/modules/cjs/loader');
 const { _load, _nodeModulePaths, _resolveFilename, isBuiltin } = Module;
-const { join } = require('path');
+const { dirname, join } = require('path');
 
 // Lazy-load VirtualFileSystem to avoid loading VFS code if fs mocking is not used
 const lazyVirtualFileSystem = getLazy(
-  () => require('internal/vfs/virtual_fs').VirtualFileSystem,
+  () => require('internal/vfs/file_system').VirtualFileSystem,
 );
 function kDefaultFunction() {}
 const enableModuleMocking = getOptionValue('--experimental-test-module-mocks');
@@ -439,20 +439,24 @@ class MockFSContext {
 
   /**
    * Adds a file to the mock file system.
-   * @param {string} path - The path of the file.
-   * @param {string|Buffer|Function} content - The file content.
+   * @param {string} filePath - The path of the file.
+   * @param {string|Buffer} content - The file content.
    */
-  addFile(path, content) {
-    this.#vfs.addFile(path, content);
+  addFile(filePath, content) {
+    // Ensure parent directories exist
+    const parentDir = dirname(filePath);
+    if (parentDir !== '/') {
+      this.#vfs.mkdirSync(parentDir, { __proto__: null, recursive: true });
+    }
+    this.#vfs.writeFileSync(filePath, content);
   }
 
   /**
    * Adds a directory to the mock file system.
-   * @param {string} path - The path of the directory.
-   * @param {Function} [populate] - Optional callback to populate the directory.
+   * @param {string} dirPath - The path of the directory.
    */
-  addDirectory(path, populate) {
-    this.#vfs.addDirectory(path, populate);
+  addDirectory(dirPath) {
+    this.#vfs.mkdirSync(dirPath, { __proto__: null, recursive: true });
   }
 
   /**
@@ -813,14 +817,21 @@ class MockTracker {
     }
 
     const VirtualFileSystem = lazyVirtualFileSystem();
-    const vfs = new VirtualFileSystem({ __proto__: null, moduleHooks: true });
+    // Use overlay mode so mocked files are intercepted but real files fall through
+    const vfs = new VirtualFileSystem({ __proto__: null, moduleHooks: true, overlay: true });
 
     // Add initial files if provided
     if (files) {
       const paths = ObjectKeys(files);
       for (let i = 0; i < paths.length; i++) {
-        const path = paths[i];
-        vfs.addFile(path, files[path]);
+        const filePath = paths[i];
+        const content = files[filePath];
+        // Ensure parent directories exist
+        const parentDir = dirname(filePath);
+        if (parentDir !== '/') {
+          vfs.mkdirSync(parentDir, { __proto__: null, recursive: true });
+        }
+        vfs.writeFileSync(filePath, content);
       }
     }
 

lib/internal/vfs/file_system.js

@@ -36,6 +36,7 @@ const { emitExperimentalWarning } = require('internal/util');
 const kProvider = Symbol('kProvider');
 const kMountPoint = Symbol('kMountPoint');
 const kMounted = Symbol('kMounted');
+const kOverlay = Symbol('kOverlay');
 const kModuleHooks = Symbol('kModuleHooks');
 const kPromises = Symbol('kPromises');
 const kVirtualCwd = Symbol('kVirtualCwd');
@@ -65,6 +66,7 @@ class VirtualFileSystem {
    * @param {object} [options] Configuration options
    * @param {boolean} [options.moduleHooks] Whether to enable require/import hooks (default: true)
    * @param {boolean} [options.virtualCwd] Whether to enable virtual working directory
+   * @param {boolean} [options.overlay] Whether to enable overlay mode (only intercept existing files)
    */
   constructor(providerOrOptions, options = {}) {
     emitExperimentalWarning('VirtualFileSystem');
@@ -89,10 +91,14 @@ class VirtualFileSystem {
     if (options.virtualCwd !== undefined) {
       validateBoolean(options.virtualCwd, 'options.virtualCwd');
     }
+    if (options.overlay !== undefined) {
+      validateBoolean(options.overlay, 'options.overlay');
+    }
 
     this[kProvider] = provider ?? new MemoryProvider();
     this[kMountPoint] = null;
     this[kMounted] = false;
+    this[kOverlay] = options.overlay === true;
     this[kModuleHooks] = options.moduleHooks !== false;
     this[kPromises] = null; // Lazy-initialized
     this[kVirtualCwdEnabled] = options.virtualCwd === true;
@@ -121,7 +127,7 @@ class VirtualFileSystem {
    * Returns true if VFS is mounted.
    * @returns {boolean}
    */
-  get isMounted() {
+  get mounted() {
     return this[kMounted];
   }
 
@@ -133,6 +139,16 @@ class VirtualFileSystem {
     return this[kProvider].readonly;
   }
 
+  /**
+   * Returns true if overlay mode is enabled.
+   * In overlay mode, the VFS only intercepts paths that exist in the VFS,
+   * allowing other paths to fall through to the real file system.
+   * @returns {boolean}
+   */
+  get overlay() {
+    return this[kOverlay];
+  }
+
   /**
    * Returns true if virtual working directory is enabled.
    * @returns {boolean}
@@ -319,6 +335,8 @@ class VirtualFileSystem {
 
   /**
    * Checks if a path should be handled by this VFS.
+   * In mount mode (default), returns true for all paths under the mount point.
+   * In overlay mode, returns true only if the path exists in the VFS.
    * @param {string} inputPath The path to check
    * @returns {boolean}
    */
@@ -328,7 +346,21 @@ class VirtualFileSystem {
     }
 
     const normalized = normalizePath(inputPath);
-    return isUnderMountPoint(normalized, this[kMountPoint]);
+    if (!isUnderMountPoint(normalized, this[kMountPoint])) {
+      return false;
+    }
+
+    // In overlay mode, only handle if the path exists in VFS
+    if (this[kOverlay]) {
+      try {
+        const providerPath = getRelativePath(normalized, this[kMountPoint]);
+        return this[kProvider].existsSync(providerPath);
+      } catch {
+        return false;
+      }
+    }
+
+    return true;
   }
 
   // ==================== FS Operations (Sync) ====================

lib/internal/vfs/module_hooks.js

@@ -76,7 +76,7 @@ function findVFSForStat(filename) {
       const result = vfs.internalModuleStat(normalized);
       // For mounted VFS, always return result (even -2 for ENOENT within mount)
       // For overlay VFS, only return if found
-      if (vfs.isMounted || result >= 0) {
+      if (vfs.mounted || result >= 0) {
         return { vfs, result };
       }
     }
@@ -110,11 +110,11 @@ function findVFSForRead(filename, options) {
         } catch (e) {
           // If read fails, fall through to default fs
           // unless we're in mounted mode (where we should return the error)
-          if (vfs.isMounted) {
+          if (vfs.mounted) {
             throw e;
           }
         }
-      } else if (vfs.isMounted) {
+      } else if (vfs.mounted) {
         // In mounted mode, if path is under mount point but doesn't exist,
         // don't fall through to real fs - throw ENOENT
         throw createENOENT('open', filename);
@@ -137,7 +137,7 @@ function findVFSForExists(filename) {
       // For mounted VFS, we handle the path (return exists result)
       // For overlay VFS, we only handle if it exists in VFS
       const exists = vfs.existsSync(normalized);
-      if (vfs.isMounted || exists) {
+      if (vfs.mounted || exists) {
         return { vfs, exists };
       }
     }
@@ -160,11 +160,11 @@ function findVFSForRealpath(filename) {
           const realpath = vfs.realpathSync(normalized);
           return { vfs, realpath };
         } catch (e) {
-          if (vfs.isMounted) {
+          if (vfs.mounted) {
             throw e;
           }
         }
-      } else if (vfs.isMounted) {
+      } else if (vfs.mounted) {
         throw createENOENT('realpath', filename);
       }
     }
@@ -187,11 +187,11 @@ function findVFSForFsStat(filename) {
           const stats = vfs.statSync(normalized);
           return { vfs, stats };
         } catch (e) {
-          if (vfs.isMounted) {
+          if (vfs.mounted) {
             throw e;
           }
         }
-      } else if (vfs.isMounted) {
+      } else if (vfs.mounted) {
         throw createENOENT('stat', filename);
       }
     }
@@ -215,11 +215,11 @@ function findVFSForReaddir(dirname, options) {
           const entries = vfs.readdirSync(normalized, options);
           return { vfs, entries };
         } catch (e) {
-          if (vfs.isMounted) {
+          if (vfs.mounted) {
             throw e;
           }
         }
-      } else if (vfs.isMounted) {
+      } else if (vfs.mounted) {
         throw createENOENT('scandir', dirname);
       }
     }
@@ -243,11 +243,11 @@ async function findVFSForReaddirAsync(dirname, options) {
           const entries = await vfs.promises.readdir(normalized, options);
           return { __proto__: null, vfs, entries };
         } catch (e) {
-          if (vfs.isMounted) {
+          if (vfs.mounted) {
             throw e;
           }
         }
-      } else if (vfs.isMounted) {
+      } else if (vfs.mounted) {
         throw createENOENT('scandir', dirname);
       }
     }
@@ -270,11 +270,11 @@ async function findVFSForLstatAsync(filename) {
           const stats = await vfs.promises.lstat(normalized);
           return { __proto__: null, vfs, stats };
         } catch (e) {
-          if (vfs.isMounted) {
+          if (vfs.mounted) {
             throw e;
           }
         }
-      } else if (vfs.isMounted) {
+      } else if (vfs.mounted) {
         throw createENOENT('lstat', filename);
       }
     }
@@ -416,7 +416,7 @@ function vfsLoadHook(url, context, nextLoad) {
         };
       } catch (e) {
         // If read fails, fall through to default loader
-        if (vfs.isMounted) {
+        if (vfs.mounted) {
           throw e;
         }
       }

lib/internal/vfs/virtual_fs.js

@@ -110,7 +110,7 @@ class VirtualFileSystem {
    * Returns true if VFS is mounted.
    * @returns {boolean}
    */
-  get isMounted() {
+  get mounted() {
     return this[kMounted];
   }
 

test/parallel/test-vfs-basic.js

@@ -9,7 +9,7 @@ const fs = require('fs');
   const myVfs = fs.createVirtual();
   assert.ok(myVfs);
   assert.strictEqual(typeof myVfs.writeFileSync, 'function');
-  assert.strictEqual(myVfs.isMounted, false);
+  assert.strictEqual(myVfs.mounted, false);
 }
 
 // Test adding and reading a static file
@@ -109,17 +109,17 @@ const fs = require('fs');
   myVfs.mkdirSync('/data', { recursive: true });
   myVfs.writeFileSync('/data/file.txt', 'mounted content');
 
-  assert.strictEqual(myVfs.isMounted, false);
+  assert.strictEqual(myVfs.mounted, false);
   myVfs.mount('/app/virtual');
-  assert.strictEqual(myVfs.isMounted, true);
+  assert.strictEqual(myVfs.mounted, true);
   assert.strictEqual(myVfs.mountPoint, '/app/virtual');
 
   // With mount, shouldHandle should work
   assert.strictEqual(myVfs.shouldHandle('/app/virtual/data/file.txt'), true);
   assert.strictEqual(myVfs.shouldHandle('/other/path'), false);
 
   myVfs.unmount();
-  assert.strictEqual(myVfs.isMounted, false);
+  assert.strictEqual(myVfs.mounted, false);
 }
 
 // Test internalModuleStat (used by Module._stat)