@componentor/fs 3.0.17 → 3.0.19

package/README.md

@@ -82,7 +82,15 @@ const fs = new VFSFileSystem({
   strictPermissions: false, // Enforce Unix permissions (default: false)
   sabSize: 4194304,       // SharedArrayBuffer size in bytes (default: 4MB)
   debug: false,           // Enable debug logging (default: false)
+  swUrl: undefined,       // URL of the service worker script (default: auto-resolved)
   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)
+  },
 });
 ```
 
@@ -153,6 +161,30 @@ console.log(fs.mode); // 'hybrid'
 
 `setMode()` terminates internal workers, allocates fresh shared memory, and reinitializes the filesystem in the requested mode.
 
+### Service Worker Setup (Multi-Tab)
+
+Multi-tab coordination requires a service worker that acts as a MessagePort broker between tabs. The built service worker is shipped at `dist/workers/service.worker.js`. Unlike regular workers (which are resolved by the bundler), **service workers must be served as a real file at a public URL**.
+
+Most bundlers (Vite, webpack) handle `new URL('./workers/service.worker.js', import.meta.url)` automatically, but if the default resolution doesn't work in your setup, use the `swUrl` option:
+
+```typescript
+const fs = new VFSFileSystem({
+  swUrl: '/vfs-service-worker.js', // your public URL
+});
+```
+
+**Vite example** — copy the file to `public/`:
+
+```bash
+cp node_modules/@componentor/fs/dist/workers/service.worker.js public/vfs-service-worker.js
+```
+
+```typescript
+const fs = new VFSFileSystem({ swUrl: '/vfs-service-worker.js' });
+```
+
+If you only use a single tab, the service worker is not needed — the tab always runs as the leader.
+
 ## COOP/COEP Headers
 
 To enable the sync API, your page must be `crossOriginIsolated`. Add these headers:
@@ -570,6 +602,24 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 ## Changelog
 
+### v3.0.19 (2026)
+
+**Features:**
+- Add `swUrl` config option to specify a custom service worker URL for multi-tab support in bundled environments where the default auto-resolved URL doesn't work
+- Remove `type: 'module'` from service worker registration (built output is plain script, not ESM)
+
+### 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:**
@@ -757,7 +807,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));