@componentor/fs 3.0.16 → 3.0.18

package/README.md

@@ -83,6 +83,13 @@ const fs = new VFSFileSystem({
   sabSize: 4194304,       // SharedArrayBuffer size in bytes (default: 4MB)
   debug: false,           // Enable debug logging (default: false)
   swScope: undefined,     // Custom service worker scope (default: auto-scoped per root)
+  limits: {               // Upper bounds for VFS validation (prevents corrupt data from causing OOM)
+    maxInodes: 4_000_000,   // Max inode count (default: 4M)
+    maxBlocks: 4_000_000,   // Max data blocks (default: 4M)
+    maxPathTable: 256 * 1024 * 1024, // Max path table bytes (default: 256MB)
+    maxVFSSize: 100 * 1024 * 1024 * 1024, // Max .vfs.bin size (default: 100GB)
+    maxPayload: 2 * 1024 * 1024 * 1024,   // Max single SAB payload (default: 2GB)
+  },
 });
 ```
 
@@ -570,6 +577,23 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 ## Changelog
 
+### v3.0.18 (2026)
+
+**Features:**
+- Configurable VFS limits via `limits` option: `maxInodes`, `maxBlocks`, `maxPathTable`, `maxVFSSize`, `maxPayload`
+
+**Fixes:**
+- Pre-validate superblock before `engine.init()` to prevent hangs from corrupt values causing huge allocations
+- Add upper bounds in `mount()`: max 4M inodes, 4M blocks, 256MB path table, 100GB total VFS size
+- Ensure all mount errors are prefixed with `Corrupt VFS:` for consistent corruption fallback
+- Cap `readPayload()` at 2GB (configurable) and validate each chunk length in the multi-chunk loop to prevent OOM/infinite loops from corrupt SAB data
+- Cap `MemoryHandle.grow()` at 4GB to prevent OOM from corrupt VFS offsets on main-thread fallback
+
+### v3.0.17 (2026)
+
+**Features:**
+- Auto-populate VFS from existing OPFS files when `.vfs.bin` doesn't exist — seamless transition from OPFS mode back to hybrid mode without manual `loadFromOPFS()` call
+
 ### v3.0.16 (2026)
 
 **Fixes:**
@@ -752,7 +776,7 @@ git clone https://github.com/componentor/fs
 cd fs
 npm install
 npm run build       # Build the library
-npm test            # Run unit tests (97 tests)
+npm test            # Run unit tests (107 tests)
 npm run benchmark:open  # Run benchmarks in browser
 ```
 

package/dist/index.d.mts

@@ -140,6 +140,19 @@ type WatchFileListener = (curr: Stats, prev: Stats) => void;
  *    Automatically selected as fallback when VFS corruption is detected in hybrid mode.
  */
 type FSMode = 'hybrid' | 'vfs' | 'opfs';
+/** Upper bounds for VFS validation. Prevents corrupt data from causing OOM/hangs. */
+interface VFSLimits {
+    /** Maximum number of inodes (default: 4,000,000) */
+    maxInodes?: number;
+    /** Maximum number of data blocks (default: 4,000,000) */
+    maxBlocks?: number;
+    /** Maximum path table size in bytes (default: 256MB) */
+    maxPathTable?: number;
+    /** Maximum total VFS file size in bytes (default: 100GB) */
+    maxVFSSize?: number;
+    /** Maximum single SAB payload size in bytes (default: 2GB) */
+    maxPayload?: number;
+}
 /** VFS configuration options */
 interface VFSConfig {
     root?: string;
@@ -158,6 +171,8 @@ interface VFSConfig {
      *  `'./opfs-fs-sw/'` (relative to the SW script URL) so it won't collide
      *  with the host application's service worker. */
     swScope?: string;
+    /** Upper bounds for VFS validation (prevents corrupt data from causing OOM/hangs). */
+    limits?: VFSLimits;
 }
 
 type AsyncRequestFn = (op: number, path: string, flags?: number, data?: Uint8Array | string | null, path2?: string, fdArgs?: Record<string, unknown>) => Promise<{
@@ -506,4 +521,4 @@ declare function getDefaultFS(): VFSFileSystem;
 /** Async init helper — avoids blocking main thread */
 declare function init(): Promise<void>;
 
-export { type Dir, type Dirent, type Encoding, FSError, type FSMode, type FSWatcher, type FileHandle, type LoadResult, type MkdirOptions, type PathLike, type ReadOptions, type ReadStreamOptions, type ReaddirOptions, type RepairResult, type RmOptions, type RmdirOptions, type Stats, type UnpackResult, type VFSConfig, VFSFileSystem, type WatchEventType, type WatchFileListener, type WatchListener, type WatchOptions, type WriteOptions, type WriteStreamOptions, constants, createError, createFS, getDefaultFS, init, loadFromOPFS, path, repairVFS, statusToError, unpackToOPFS };
+export { type Dir, type Dirent, type Encoding, FSError, type FSMode, type FSWatcher, type FileHandle, type LoadResult, type MkdirOptions, type PathLike, type ReadOptions, type ReadStreamOptions, type ReaddirOptions, type RepairResult, type RmOptions, type RmdirOptions, type Stats, type UnpackResult, type VFSConfig, VFSFileSystem, type VFSLimits, type WatchEventType, type WatchFileListener, type WatchListener, type WatchOptions, type WriteOptions, type WriteStreamOptions, constants, createError, createFS, getDefaultFS, init, loadFromOPFS, path, repairVFS, statusToError, unpackToOPFS };

package/dist/index.js

@@ -1351,7 +1351,8 @@ var VFSFileSystem = class {
       strictPermissions: config.strictPermissions ?? false,
       sabSize: config.sabSize ?? DEFAULT_SAB_SIZE,
       debug: config.debug ?? false,
-      swScope: config.swScope
+      swScope: config.swScope,
+      limits: config.limits
     };
     this.tabId = crypto.randomUUID();
     this.ns = ns;
@@ -1473,7 +1474,8 @@ var VFSFileSystem = class {
         gid: this.config.gid,
         umask: this.config.umask,
         strictPermissions: this.config.strictPermissions,
-        debug: this.config.debug
+        debug: this.config.debug,
+        limits: this.config.limits
       }
     });
   }
@@ -2193,6 +2195,13 @@ var VFSEngine = class {
   superblockDirty = false;
   // Free inode hint — skip O(n) scan
   freeInodeHint = 0;
+  // Configurable upper bounds
+  maxInodes = 4e6;
+  maxBlocks = 4e6;
+  maxPathTable = 256 * 1024 * 1024;
+  // 256MB
+  maxVFSSize = 100 * 1024 * 1024 * 1024;
+  // 100GB
   init(handle, opts) {
     this.handle = handle;
     this.processUid = opts?.uid ?? 0;
@@ -2200,11 +2209,23 @@ var VFSEngine = class {
     this.umask = opts?.umask ?? DEFAULT_UMASK;
     this.strictPermissions = opts?.strictPermissions ?? false;
     this.debug = opts?.debug ?? false;
+    if (opts?.limits) {
+      if (opts.limits.maxInodes != null) this.maxInodes = opts.limits.maxInodes;
+      if (opts.limits.maxBlocks != null) this.maxBlocks = opts.limits.maxBlocks;
+      if (opts.limits.maxPathTable != null) this.maxPathTable = opts.limits.maxPathTable;
+      if (opts.limits.maxVFSSize != null) this.maxVFSSize = opts.limits.maxVFSSize;
+    }
     const size = handle.getSize();
     if (size === 0) {
       this.format();
     } else {
-      this.mount();
+      try {
+        this.mount();
+      } catch (err) {
+        const msg = err.message ?? String(err);
+        if (msg.startsWith("Corrupt VFS:")) throw err;
+        throw new Error(`Corrupt VFS: ${msg}`);
+      }
     }
   }
   /** Release the sync access handle (call on fatal error or shutdown) */
@@ -2271,6 +2292,18 @@ var VFSEngine = class {
     if (freeBlocks > totalBlocks) {
       throw new Error(`Corrupt VFS: free blocks (${freeBlocks}) exceeds total blocks (${totalBlocks})`);
     }
+    if (inodeCount > this.maxInodes) {
+      throw new Error(`Corrupt VFS: inode count ${inodeCount} exceeds maximum ${this.maxInodes}`);
+    }
+    if (totalBlocks > this.maxBlocks) {
+      throw new Error(`Corrupt VFS: total blocks ${totalBlocks} exceeds maximum ${this.maxBlocks}`);
+    }
+    if (fileSize > this.maxVFSSize) {
+      throw new Error(`Corrupt VFS: file size ${fileSize} exceeds maximum ${this.maxVFSSize}`);
+    }
+    if (!Number.isFinite(inodeTableOffset) || inodeTableOffset < 0 || !Number.isFinite(pathTableOffset) || pathTableOffset < 0 || !Number.isFinite(bitmapOffset) || bitmapOffset < 0 || !Number.isFinite(dataOffset) || dataOffset < 0) {
+      throw new Error(`Corrupt VFS: non-finite or negative section offset`);
+    }
     if (inodeTableOffset !== SUPERBLOCK.SIZE) {
       throw new Error(`Corrupt VFS: inode table offset ${inodeTableOffset} (expected ${SUPERBLOCK.SIZE})`);
     }
@@ -2288,7 +2321,13 @@ var VFSEngine = class {
     if (pathUsed > pathTableSize) {
       throw new Error(`Corrupt VFS: path used (${pathUsed}) exceeds path table size (${pathTableSize})`);
     }
+    if (pathTableSize > this.maxPathTable) {
+      throw new Error(`Corrupt VFS: path table size ${pathTableSize} exceeds maximum ${this.maxPathTable}`);
+    }
     const expectedMinSize = dataOffset + totalBlocks * blockSize;
+    if (expectedMinSize > this.maxVFSSize) {
+      throw new Error(`Corrupt VFS: computed layout size ${expectedMinSize} exceeds maximum ${this.maxVFSSize}`);
+    }
     if (fileSize < expectedMinSize) {
       throw new Error(`Corrupt VFS: file size ${fileSize} too small for layout (need ${expectedMinSize})`);
     }
@@ -3483,6 +3522,10 @@ var MemoryHandle = class {
     return this.buf.buffer.slice(0, this.len);
   }
   grow(minSize) {
+    const MAX_SIZE = 4 * 1024 * 1024 * 1024;
+    if (minSize > MAX_SIZE) {
+      throw new Error(`MemoryHandle: cannot grow to ${minSize} bytes (max ${MAX_SIZE})`);
+    }
     const newSize = Math.max(minSize, this.buf.length * 2);
     const newBuf = new Uint8Array(newSize);
     newBuf.set(this.buf.subarray(0, this.len));