@poe-platform/safe-fs 0.1.800 → 0.1.802

package/README.md

@@ -123,6 +123,7 @@ Capture `retainFileSystemCleanup(scoped, callback, { maxOperations })` before
 cancellation to clean up through a bounded view after ordinary scoped operations
 close. Cleanup preserves its owning scope and limits across separately bundled
 command runtimes, including restrictions added by filesystem wrappers.
+Omit `maxOperations` or pass `Infinity` for unlimited cleanup operations.
 
 | Backend or wrapper | Use it for |
 | --- | --- |
@@ -252,7 +253,7 @@ There are no package environment variables, implicit credentials, or automatic `
 
 | API | Options and defaults |
 | --- | --- |
-| `createFileSystem(config, { registry })` | Required `config.type`; `config.options` defaults to an empty record. `registry` is required. Built-in `memory` accepts optional file, retained-byte, metadata and total-byte quotas; built-in `real` requires `root`. |
+| `createFileSystem(config, { registry })` | Required `config.type`; `config.options` defaults to an empty record. `registry` is required. Built-in `memory` accepts optional file, retained-byte, metadata, total-byte, `maxPathBytes` and `maxPathComponents` quotas (omitted, `undefined`, or `Infinity` disables each quota); built-in `real` requires `root`. |
 | `createNodeFileSystemAdapterRegistry(extensions?)` | Optional map of additional adapter descriptors; defaults to only `memory` and `real`. |
 | Memory / read-only | Memory accepts independent optional `maxFileBytes`, `maxRetainedBytes`, `maxMetadataUnits` and `maxBytes` quotas, all unlimited by default. Read-only takes the backing filesystem, without an options object. |
 | Real | Required `root`: existing absolute host directory; the constructor/factory also accepts the root string directly. |
@@ -277,6 +278,8 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 | `copyFile` | `exclusive` (default false) |
 | `readStream` | `start` (default 0), `endExclusive` (default end of file), `chunkSize` (built-in default 64 KiB) |
 
+`validatePath(path, { maxPathBytes, maxPathComponents })` accepts optional UTF-8 byte and component quotas; both default to `Infinity`. Memory accepts the same constructor options and counts cumulative symlink expansion. Device operations accept these quotas under `pathLimits`. WebDAV accepts `maxTimestampPropertyBytes` for timestamp metadata, also unlimited by default.
+
 `access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). For conditional chmod, check `capabilitiesFor(path, { conditionalChmod: true })` (or `capabilities`) and require `conditionalChmod: true`; supply `parent`, `expected`, and complete root-to-parent `ancestors` together. An optional mutation-free `commitGuard` must return literal `true` synchronously. Memory validates at its metadata commit; mount and supported Memory overlays preserve wrapper ancestry. Real uses its existing externally isolated host-tree boundary and does not prevent races with other processes. Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
 
 `collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxBytes` and `maxMemoryBytes` accept explicit `Infinity`. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Collection limits are disabled by default on Node, browser, and Worker targets. Each call owns its budget; concurrent collections do not consume one another’s allowance. The returned view may retain geometric spare capacity. Configured budgets cover collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -105,6 +105,8 @@ export interface FileSystemCapabilities {
     readonly [capability: string]: boolean | undefined;
 }
 export interface FsOptions {
+    /** Optional virtual device path traversal quotas; disabled by default. */
+    readonly pathLimits?: import("./virtual-path.js").PathLimits;
     readonly signal?: AbortSignal;
 }
 export interface ChmodOptions extends FsOptions {

package/dist/safe-fs/contracts/path.d.ts

@@ -1,2 +1,3 @@
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./virtual-path.js";
 export { posixPath, basename, dirname, extname, joinPath, isAbsolutePath } from "./portable-path.js";
+export type { PathLimits } from "./virtual-path.js";

package/dist/safe-fs/contracts/virtual-path.d.ts

@@ -1,6 +1,11 @@
-export declare const MAX_PATH_BYTES = 65536;
-export declare const MAX_PATH_COMPONENTS = 2048;
-export declare function validatePath(path: string, maxComponents?: number): void;
+export declare const MAX_PATH_BYTES: number;
+export declare const MAX_PATH_COMPONENTS: number;
+export interface PathLimits {
+    readonly maxPathBytes?: number | undefined;
+    readonly maxPathComponents?: number | undefined;
+}
+export declare function pathByteLength(path: string): number;
+export declare function validatePath(path: string, limits?: PathLimits | number): void;
 export declare function resolvePath2(cwd: string, path0: string): string;
 export declare function resolvePath(cwd: string, ...paths: string[]): string;
 export declare function normalizePath(path: string, cwd?: string): string;

package/dist/safe-fs/contracts/virtual-path.js

@@ -1,14 +1,31 @@
 import { FsError } from "./errors.js";
-export const MAX_PATH_BYTES = 65_536;
-export const MAX_PATH_COMPONENTS = 2048;
-export function validatePath(path, maxComponents = MAX_PATH_COMPONENTS) {
+export const MAX_PATH_BYTES = Infinity;
+export const MAX_PATH_COMPONENTS = Infinity;
+export function pathByteLength(path) {
+    let bytes = 0;
+    for (const point of path) {
+        const code = point.codePointAt(0);
+        bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+export function validatePath(path, limits = {}) {
+    const maxBytes = typeof limits === "number" ? Infinity : limits.maxPathBytes ?? Infinity;
+    const maxComponents = typeof limits === "number" ? limits : limits.maxPathComponents ?? Infinity;
+    for (const value of [maxBytes, maxComponents]) {
+        if (value !== Infinity && (!Number.isSafeInteger(value) || value < 0)) {
+            throw new RangeError("Path limits must be nonnegative safe integers or Infinity");
+        }
+    }
     if (typeof path !== "string" || path.includes("\0")) {
         throw new FsError("EINVAL", { syscall: "resolve", message: "paths must be strings without NUL bytes" });
     }
-    if (path.length > MAX_PATH_BYTES) {
+    if (maxBytes !== Infinity && pathByteLength(path) > maxBytes) {
         throw new FsError("ENAMETOOLONG", { syscall: "resolve", path });
     }
-    const limit = Math.min(maxComponents, MAX_PATH_COMPONENTS);
+    if (maxComponents === Infinity)
+        return;
+    const limit = maxComponents;
     let components = 0;
     let inComponent = false;
     for (let i = 0; i < path.length; i++) {

package/dist/safe-fs/fs/devices/path.js

@@ -1,5 +1,5 @@
 import { FsError, isFsError } from "../../contracts/errors.js";
-import { MAX_PATH_COMPONENTS, validatePath } from "../../contracts/virtual-path.js";
+import { pathByteLength, validatePath } from "../../contracts/virtual-path.js";
 import { capturePathNamespace, pathNamespace } from "../path-namespace.js";
 import { isCleanAbsolutePath, tryResolveMemoryDevicePath } from "../memory/index.js";
 export const nullPath = "/dev/null";
@@ -23,20 +23,20 @@ export function lexicalDevicePath(path) {
     return `/${parts.join("/")}`;
 }
 async function resolveResizeDevicePath(filesystem, path, options, create, namespace, traversal) {
-    validatePath(path);
+    validatePath(path, options.pathLimits);
     const components = (value) => {
         const result = value.split("/").filter(Boolean);
         if (value.endsWith("/"))
             result.push("");
         return result;
     };
-    const pending = components(path);
-    let remainingComponents = MAX_PATH_COMPONENTS - pending.length;
+    let pending = components(path);
+    let remainingComponents = (options.pathLimits?.maxPathComponents ?? Infinity) - pending.length;
     if (remainingComponents < 0)
         throw new FsError("ENAMETOOLONG", { path });
     const parts = [];
     let links = 0;
-    let expanded = path.length;
+    let expanded = pathByteLength(path);
     let boundary;
     while (pending.length) {
         options.signal?.throwIfAborted();
@@ -99,9 +99,9 @@ async function resolveResizeDevicePath(filesystem, path, options, create, namesp
                     throw new FsError("ELOOP", { path });
                 const target = await Reflect.apply(readlink, filesystem, [candidate, options]);
                 options.signal?.throwIfAborted();
-                validatePath(target);
-                expanded += target.length;
-                if (expanded > 65536)
+                validatePath(target, options.pathLimits);
+                expanded += pathByteLength(target);
+                if (expanded > (options.pathLimits?.maxPathBytes ?? Infinity))
                     throw new FsError("ENAMETOOLONG", { path });
                 if (target.startsWith("/"))
                     parts.splice(0, parts.length, ...(boundary ?? "/").split("/").filter(Boolean));
@@ -111,7 +111,7 @@ async function resolveResizeDevicePath(filesystem, path, options, create, namesp
                 if (targetParts.length > remainingComponents)
                     throw new FsError("ENAMETOOLONG", { path });
                 remainingComponents -= targetParts.length;
-                pending.unshift(...targetParts);
+                pending = targetParts.concat(pending);
                 continue;
             }
         }
@@ -141,7 +141,8 @@ function exceedsComponentByteLimit(value) {
 }
 export async function resolveDevicePath(filesystem, path, options, followFinal = true, resizeCreate, traversal) {
     options.signal?.throwIfAborted();
-    if (Reflect.get(filesystem, pathNamespace) === undefined) {
+    validatePath(path, options.pathLimits);
+    if (options.pathLimits === undefined && Reflect.get(filesystem, pathNamespace) === undefined) {
         const fast = tryResolveMemoryDevicePath(filesystem, path, resizeCreate);
         if (fast !== undefined)
             return fast;
@@ -155,13 +156,13 @@ export async function resolveDevicePath(filesystem, path, options, followFinal =
     const aliases = typeof lstat === "function";
     if (!aliases && lexical !== nullPath && lexical !== deviceDirectory && lexical !== "/")
         return lexical;
-    const pending = path.split("/");
-    let remainingComponents = MAX_PATH_COMPONENTS - pending.filter(Boolean).length;
+    let pending = path.split("/");
+    let remainingComponents = (options.pathLimits?.maxPathComponents ?? Infinity) - pending.filter(Boolean).length;
     if (remainingComponents < 0)
         throw new FsError("ENAMETOOLONG", { path });
     const parts = [];
     let links = 0;
-    let expanded = path.length;
+    let expanded = pathByteLength(path);
     let absolute = path.startsWith("/");
     let traversalFailure;
     let failedDepth = Infinity;
@@ -218,9 +219,9 @@ export async function resolveDevicePath(filesystem, path, options, followFinal =
                     throw new FsError("ELOOP", { path });
                 const target = await Reflect.apply(readlink, filesystem, [lookup, options]);
                 options.signal?.throwIfAborted();
-                validatePath(target);
-                expanded += target.length;
-                if (expanded > 65536)
+                validatePath(target, options.pathLimits);
+                expanded += pathByteLength(target);
+                if (expanded > (options.pathLimits?.maxPathBytes ?? Infinity))
                     throw new FsError("ENAMETOOLONG", { path });
                 const targetSplit = target.split("/");
                 const nonEmptyCount = targetSplit.filter(Boolean).length;
@@ -232,7 +233,7 @@ export async function resolveDevicePath(filesystem, path, options, followFinal =
                     absolute = true;
                     failedDepth = Infinity;
                 }
-                pending.unshift(...targetSplit);
+                pending = targetSplit.concat(pending);
                 continue;
             }
             if (stat && pending.length && stat.type !== "directory") {

package/dist/safe-fs/fs/memory/index.js

@@ -1,5 +1,5 @@
 import { FsError } from "../../contracts/errors.js";
-import { normalizePath } from "../../contracts/virtual-path.js";
+import { normalizePath, validatePath, pathByteLength } from "../../contracts/virtual-path.js";
 import { assertCallbackAuthorityAllowed, compareEntries, registerEntryAuthority } from "../mount/comparison.js";
 import { getOwnedS3Entry } from "../s3/registry.js";
 import { getOwnedWebDavEntry } from "../webdav/resource-id.js";
@@ -56,10 +56,10 @@ DUMMY_POOL_FILE_NODE.atimeMs = DUMMY_POOL_FILE_NODE.mtimeMs = DUMMY_POOL_FILE_NO
 const defaultDateNow = Date.now;
 let fastWriteCachedNow = Date.now();
 let fastWriteNowTick = 0;
-const lastFastMapMiss = {
-    map: undefined, key: "", slot: -1,
-};
 class FastDirectoryEntriesMap {
+    // Keep speculative slots local so a failed write cannot pin a tenant globally.
+    _missKey = "";
+    _missSlot = -1;
     _table = new Int16Array(128).fill(-1);
     _mask = 127;
     _keys = new Array(64).fill("");
@@ -96,9 +96,8 @@ class FastDirectoryEntriesMap {
     getForWriteWithHash(k, h) {
         let slot = h & this._mask;
         if (this.size === 0) {
-            lastFastMapMiss.map = this;
-            lastFastMapMiss.key = k;
-            lastFastMapMiss.slot = slot;
+            this._missKey = k;
+            this._missSlot = slot;
             return undefined;
         }
         const mask = this._mask;
@@ -108,9 +107,8 @@ class FastDirectoryEntriesMap {
         while (true) {
             const idx = table[slot];
             if (idx === -1) {
-                lastFastMapMiss.map = this;
-                lastFastMapMiss.key = k;
-                lastFastMapMiss.slot = firstDeleted !== -1 ? firstDeleted : slot;
+                this._missKey = k;
+                this._missSlot = firstDeleted !== -1 ? firstDeleted : slot;
                 return undefined;
             }
             if (idx === -2) {
@@ -160,6 +158,7 @@ class FastDirectoryEntriesMap {
         return this.get(k) !== undefined;
     }
     _rebuild(newCap) {
+        this._missKey = "";
         const newTableLen = newCap * 2;
         const newMask = newTableLen - 1;
         const newTable = newCap <= 16384 ? new Int16Array(newTableLen).fill(-1) : new Int32Array(newTableLen).fill(-1);
@@ -199,15 +198,16 @@ class FastDirectoryEntriesMap {
         this._next = writeIdx;
     }
     set(k, v) {
-        if (this === lastFastMapMiss.map && k === lastFastMapMiss.key && this._next < this._keys.length) {
+        if (k === this._missKey && this._next < this._keys.length) {
             const entryIdx = this._next++;
-            this._table[lastFastMapMiss.slot] = entryIdx;
+            this._table[this._missSlot] = entryIdx;
             this._keys[entryIdx] = k;
             this._vals[entryIdx] = v;
             this.size++;
-            lastFastMapMiss.map = undefined;
+            this._missKey = "";
             return this;
         }
+        this._missKey = "";
         if (this._next >= this._keys.length) {
             this._rebuild(this.size * 2 <= this._keys.length ? this._keys.length : this._keys.length * 2);
         }
@@ -239,6 +239,7 @@ class FastDirectoryEntriesMap {
         }
     }
     delete(k) {
+        this._missKey = "";
         if (this.size === 0)
             return false;
         let slot = this._hash(k);
@@ -266,6 +267,7 @@ class FastDirectoryEntriesMap {
         }
     }
     clear() {
+        this._missKey = "";
         if (this._next > 0) {
             this._table.fill(-1);
             for (let i = 0; i < this._next; i++) {
@@ -710,7 +712,7 @@ export class MemoryFileSystem {
         const owner = ownedStores.get(this);
         if (path !== "")
             this.validatePath(path, "realpath");
-        return resolveMissingTarget(owner.root, path || ".", options.signal);
+        return resolveMissingTarget(owner.root, path || ".", options.signal, this.ledger.limits);
     }
     async confineExtraction(roots, options = {}) {
         options.signal?.throwIfAborted();
@@ -935,6 +937,7 @@ export class MemoryFileSystem {
     }
     replaceData(node, allocation, length = allocation.data.byteLength) {
         const previous = node.allocation;
+        node.sourceRef = undefined;
         this.totalBytes += length - node.byteLength;
         node.byteLength = length;
         node.view = length === allocation.data.byteLength ? allocation.data : undefined;
@@ -968,6 +971,8 @@ export class MemoryFileSystem {
             this.fail("EINVAL", syscall, path);
         if (path.length === 0)
             this.fail("ENOENT", syscall, path);
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
     }
     permission(node, mask, syscall, path) {
         if (((node.mode >> 6) & mask) !== mask)
@@ -989,6 +994,8 @@ export class MemoryFileSystem {
         node.mtimeMs = node.ctimeMs = now;
     }
     resolveNode(path, syscall, followFinal = true) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         const cache = memoryCaches.get(this.ledger);
         if (this.symlinkCount === 0 && isCleanAbsolutePath(path)) {
             const fastDir = cache.lastFastDirNode;
@@ -1075,7 +1082,7 @@ export class MemoryFileSystem {
             }
         }
         // Bound all component arrays allocated by this resolution, including cycles.
-        let remainingPathUnits = 65_536 - path.length;
+        let remainingPathUnits = this.ledger.limits.maxPathBytes - pathByteLength(path);
         if (remainingPathUnits < 0)
             this.fail("ENAMETOOLONG", syscall, path);
         let initialComponents = 0;
@@ -1085,12 +1092,12 @@ export class MemoryFileSystem {
                 inComp = false;
             else if (!inComp) {
                 inComp = true;
-                if (++initialComponents > 256)
+                if (++initialComponents > this.ledger.limits.maxPathComponents)
                     this.fail("ENAMETOOLONG", syscall, path);
             }
         }
-        const pending = path.split("/").filter(Boolean);
-        let remainingComponents = 256 - pending.length;
+        let pending = path.split("/").filter(Boolean);
+        let remainingComponents = this.ledger.limits.maxPathComponents - pending.length;
         if (path.endsWith("/"))
             pending.push("");
         const stack = [{ node: this.root, name: "" }];
@@ -1140,9 +1147,9 @@ export class MemoryFileSystem {
             if (node.type === "symlink" && (options.followFinal !== false || pending.length > 0)) {
                 if (++links > 40)
                     this.fail("ELOOP", syscall, path);
-                if (node.target.length > remainingPathUnits)
+                if (pathByteLength(node.target) > remainingPathUnits)
                     this.fail("ENAMETOOLONG", syscall, path);
-                remainingPathUnits -= node.target.length;
+                remainingPathUnits -= pathByteLength(node.target);
                 const target = node.target.split("/").filter(Boolean);
                 if (target.length > remainingComponents)
                     this.fail("ENAMETOOLONG", syscall, path);
@@ -1151,7 +1158,7 @@ export class MemoryFileSystem {
                     target.push("");
                 if (options.resizeCreate !== undefined && target.at(-1) === "" && pending[0] === "")
                     target.pop();
-                pending.unshift(...target);
+                pending = target.concat(pending);
                 if (node.target.startsWith("/"))
                     stack.splice(1);
                 continue;
@@ -1167,6 +1174,8 @@ export class MemoryFileSystem {
         };
     }
     file(path, syscall) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         if (this.symlinkCount === 0 && path.charCodeAt(0) === 47 && path.length > 1 && path.indexOf("/", 1) === -1 && !path.includes("\0")) {
             const name = path === _lastFileSlice1Path ? _lastFileSlice1Name : (_lastFileSlice1Path = path, _lastFileSlice1Name = path.slice(1));
             if (name !== "." && name !== "..") {
@@ -1444,6 +1453,8 @@ export class MemoryFileSystem {
         }, syscall, path);
     }
     writeData(path, data, options, syscall) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         if (!(data instanceof Uint8Array))
             throw new TypeError("Memory files require Uint8Array data");
         const target = this.prepareWrite(path, options, syscall);
@@ -1571,9 +1582,12 @@ export class MemoryFileSystem {
             node.byteLength = length;
             node.view = length === allocation.data.byteLength ? allocation.data : undefined;
         }
+        node.sourceRef = undefined;
         this.changed(node, now);
     }
     writeMemoryFileFast(path, data, append, mode) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         const cache = memoryCaches.get(this.ledger);
         const syscall = append ? "appendFile" : "writeFile";
         if (append &&
@@ -1582,8 +1596,8 @@ export class MemoryFileSystem {
             cache.lastFastFileNode.nlink !== 0 &&
             cache.lastFastDirNode !== undefined &&
             cache.lastFastDirNode.nlink !== 0 &&
-            (cache.lastFastDirNode.mode & 1) !== 0 &&
-            (cache.lastFastFileNode.mode & 2) !== 0) {
+            (cache.lastFastDirNode.mode & 0o100) !== 0 &&
+            (cache.lastFastFileNode.mode & 0o200) !== 0) {
             const current = cache.lastFastFileNode;
             const length = current.byteLength + data.byteLength;
             this.admitSize(current, length, syscall, path);
@@ -1599,7 +1613,7 @@ export class MemoryFileSystem {
         const cachedDir = cache.lastFastDirNode;
         if (cachedDir !== undefined &&
             cachedDir.nlink !== 0 &&
-            (cachedDir.mode & 1) !== 0 &&
+            (cachedDir.mode & 0o100) !== 0 &&
             cachedPrefix.length > 1 &&
             path.startsWith(cachedPrefix) &&
             path.indexOf("/", cachedPrefix.length) === -1) {
@@ -1616,7 +1630,7 @@ export class MemoryFileSystem {
                     name = path.slice(start);
                     if (exceedsComponentByteLimit(name))
                         this.fail("ENAMETOOLONG", syscall, path);
-                    if (start > 1 && (parent.mode & 1) !== 0) {
+                    if (start > 1 && (parent.mode & 0o100) !== 0) {
                         cache.lastFastDirPrefix = path.slice(0, start);
                         cache.lastFastDirNode = parent;
                     }
@@ -1753,6 +1767,7 @@ export class MemoryFileSystem {
                 let ino = this.nextInode;
                 this.nextInode = ino + batchCount;
                 let nextIdx = 1;
+                entries._missKey = "";
                 entries._next = 1 + batchCount;
                 entries.size = 1 + batchCount;
                 const table = entries._table;
@@ -1802,6 +1817,8 @@ export class MemoryFileSystem {
         }
     }
     writeMemoryFileInDirFast(dirPrefix, name, data, append, mode, nameHash) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(dirPrefix + name, this.ledger.limits);
         const cache = this._cache;
         if (!append &&
             dirPrefix === cache.lastFastDirPrefix &&
@@ -1817,6 +1834,7 @@ export class MemoryFileSystem {
             const entries = parent.entries;
             const existing = nameHash !== undefined ? entries.getForWriteWithHash(name, nameHash) : entries.getForWrite(name);
             if (existing === undefined && entries._next < entries._keys.length) {
+                this.ledger.reserve(name.length * 2, 2, "writeFile", name);
                 const now = fastWriteCachedNow;
                 const length = data.byteLength;
                 const node = sharedFileNodePool[--sharedFileNodePoolLen];
@@ -1838,13 +1856,11 @@ export class MemoryFileSystem {
                 node.allocation = DUMMY_POOL_ALLOCATION;
                 node.sourceRef = node.data.subarray(0);
                 const entryIdx = entries._next++;
-                entries._table[lastFastMapMiss.slot] = entryIdx;
+                entries._table[entries._missSlot] = entryIdx;
                 entries._keys[entryIdx] = name;
                 entries._vals[entryIdx] = node;
                 entries.size++;
-                lastFastMapMiss.map = undefined;
-                lastFastMapMiss.key = "";
-                this.ledger.reserve(name.length * 2, 2, "writeFile", name);
+                entries._missKey = "";
                 this.totalBytes += length;
                 this.mutationTick = (this.mutationTick + 1) | 0;
                 parent.revision = parent.revision < 1073741823 ? (parent.revision + 1) | 0 : Math.min(Number.MAX_SAFE_INTEGER + 1, parent.revision + 1);
@@ -1864,8 +1880,8 @@ export class MemoryFileSystem {
                 cache.lastFastFileNode.nlink !== 0 &&
                 cache.lastFastDirNode !== undefined &&
                 cache.lastFastDirNode.nlink !== 0 &&
-                (cache.lastFastDirNode.mode & 1) !== 0 &&
-                (cache.lastFastFileNode.mode & 2) !== 0) {
+                (cache.lastFastDirNode.mode & 0o100) !== 0 &&
+                (cache.lastFastFileNode.mode & 0o200) !== 0) {
                 const current = cache.lastFastFileNode;
                 const length = current.byteLength + data.byteLength;
                 this.admitSize(current, length, syscall, name);
@@ -1878,7 +1894,7 @@ export class MemoryFileSystem {
             const cachedDir = cache.lastFastDirNode;
             if (cachedDir !== undefined &&
                 cachedDir.nlink !== 0 &&
-                (cachedDir.mode & 1) !== 0 &&
+                (cachedDir.mode & 0o100) !== 0 &&
                 dirPrefix === cache.lastFastDirPrefix) {
                 parent = cachedDir;
                 if (exceedsComponentByteLimit(name))
@@ -1905,7 +1921,7 @@ export class MemoryFileSystem {
                 this.permission(parent, 1, syscall, name);
                 if (exceedsComponentByteLimit(name))
                     this.fail("ENAMETOOLONG", syscall, name);
-                if (dirPrefix.length > 1 && (parent.mode & 1) !== 0) {
+                if (dirPrefix.length > 1 && (parent.mode & 0o100) !== 0) {
                     cache.lastFastDirPrefix = dirPrefix;
                     cache.lastFastDirNode = parent;
                 }
@@ -1984,12 +2000,8 @@ export class MemoryFileSystem {
                         cache.lastFastFilePath = "";
                         cache.lastFastFileName = name;
                         cache.lastFastFileNode = node;
-                        lastFastMapMiss.map = undefined;
-                        lastFastMapMiss.key = "";
                     }
                     catch (error) {
-                        lastFastMapMiss.map = undefined;
-                        lastFastMapMiss.key = "";
                         this.ledger.release(nameBytes, 2);
                         throw error;
                     }
@@ -3175,6 +3187,7 @@ export function tryOpenMemoryRedirectHandleSync(filesystem, path, append, mode,
         return undefined;
     }
     signal?.throwIfAborted();
+    validatePath(path, owner.ledger.limits);
     const validMode = (mode & 0o777) === mode
         ? mode
         : mem.mode(mode, 0o666, "open", path);
@@ -3276,14 +3289,13 @@ export function tryOpenMemoryRedirectHandleSync(filesystem, path, append, mode,
         }
         const prevNlink = parent.cachedNlinkRev === parent.revision ? parent.cachedNlink : (parent.entries.size === 0 ? 2 : undefined);
         const entries = parent.entries;
-        if (lastFastMapMiss.map === entries && lastFastMapMiss.key === name && entries._next < entries._keys.length) {
+        if (entries._missKey === name && entries._next < entries._keys.length) {
             const entryIdx = entries._next++;
-            entries._table[lastFastMapMiss.slot] = entryIdx;
+            entries._table[entries._missSlot] = entryIdx;
             entries._keys[entryIdx] = name;
             entries._vals[entryIdx] = newNode;
             entries.size++;
-            lastFastMapMiss.map = undefined;
-            lastFastMapMiss.key = "";
+            entries._missKey = "";
         }
         else {
             entries.set(name, newNode);
@@ -3359,6 +3371,7 @@ export function tryResolveMemoryDevicePath(filesystem, path, resizeCreate) {
     const mem = filesystem;
     if (!ownedStores.has(mem) || mem.symlinkCount !== 0 || !isStockMemoryMethods(mem, deviceFastMethodNames, false))
         return undefined;
+    validatePath(path, ownedStores.get(mem).ledger.limits);
     if (!isCleanAbsolutePath(path) || path === "/dev" || path.startsWith("/dev/"))
         return undefined;
     let current = mem.root;
@@ -3446,6 +3459,9 @@ export function getLastReadMemoryFileSourceRef(view) {
     return ref;
 }
 export function tryReadMemoryFileViewSync(filesystem, path, maxBytes, signal, captureSourceRef = false) {
+    // A capture belongs only to the most recent read, including failed/fallback reads.
+    lastReadViewData = undefined;
+    lastReadViewSourceRef = undefined;
     const mem = filesystem;
     if (mem._owner === undefined || !isStockMemoryMethods(mem, readFileFastMethodNames, false))
         return undefined;
@@ -3461,6 +3477,8 @@ export function tryReadMemoryFileViewSync(filesystem, path, maxBytes, signal, ca
         node.atimeMs = Date.now();
     else if ((++fastWriteNowTick & 63) === 0)
         node.atimeMs = fastWriteCachedNow = Date.now();
+    else
+        node.atimeMs = fastWriteCachedNow;
     if (captureSourceRef && node.revision === 0) {
         lastReadViewData = new WeakRef(data);
         lastReadViewSourceRef = node.sourceRef === undefined ? undefined : new WeakRef(node.sourceRef);
@@ -3540,6 +3558,7 @@ export function tryGetMemoryDirectoryEntryNamesSync(filesystem, path) {
     const owner = ownedStores.get(mem);
     if (!owner || mem.symlinkCount !== 0 || !isStockMemoryMethods(mem, readFileFastMethodNames, false))
         return undefined;
+    validatePath(path, owner.ledger.limits);
     const root = mem.root;
     if (path === "/") {
         if (((root.mode >> 6) & 4) !== 4)
@@ -3606,6 +3625,7 @@ export function tryMkdirMemorySync(filesystem, path, recursive, mode, signal, di
         return false;
     }
     signal?.throwIfAborted();
+    validatePath(path, owner.ledger.limits);
     const validMode = mem.mode(mode, 0o777, "mkdir", path);
     if (recursive) {
         let current = owner.root;
@@ -3657,6 +3677,7 @@ export function tryRmRfMemorySync(filesystem, path, signal) {
         return false;
     }
     signal?.throwIfAborted();
+    validatePath(path, owner.ledger.limits);
     let current = owner.root;
     let start = 1;
     let targetNode;

package/dist/safe-fs/fs/memory/limits.d.ts

@@ -1,9 +1,13 @@
 export interface MemoryFileSystemLimits {
     readonly maxBytes?: number;
+    readonly maxPathBytes: number;
+    readonly maxPathComponents: number;
     readonly maxFileBytes: number;
     readonly maxRetainedBytes: number;
     readonly maxMetadataUnits: number;
 }
-export type MemoryFileSystemOptions = Partial<MemoryFileSystemLimits>;
+export type MemoryFileSystemOptions = {
+    readonly [Key in keyof MemoryFileSystemLimits]?: MemoryFileSystemLimits[Key] | undefined;
+};
 export declare const defaultMemoryFileSystemLimits: Readonly<MemoryFileSystemLimits>;
 export declare function normalizeMemoryFileSystemLimits(options: unknown): Readonly<MemoryFileSystemLimits>;

package/dist/safe-fs/fs/memory/limits.js

@@ -1,25 +1,21 @@
 import { readConfigRecord } from "../../config.js";
 export const defaultMemoryFileSystemLimits = Object.freeze({
+    maxPathBytes: Infinity,
+    maxPathComponents: Infinity,
     maxFileBytes: Infinity,
     maxRetainedBytes: Infinity,
     maxMetadataUnits: Infinity,
 });
 export function normalizeMemoryFileSystemLimits(options) {
-    const keys = ["maxFileBytes", "maxRetainedBytes", "maxMetadataUnits"];
+    const keys = ["maxPathBytes", "maxPathComponents", "maxFileBytes", "maxRetainedBytes", "maxMetadataUnits"];
     const record = readConfigRecord(options, "memory option", [...keys, "maxBytes"]);
     const limits = { ...defaultMemoryFileSystemLimits };
-    if (Object.hasOwn(record, "maxBytes") && record.maxBytes !== undefined) {
-        if (typeof record.maxBytes !== "number" || !Number.isSafeInteger(record.maxBytes) || record.maxBytes < 0) {
-            throw new RangeError("maxBytes must be a nonnegative safe integer");
-        }
-        limits.maxBytes = record.maxBytes;
-    }
-    for (const key of keys) {
-        if (!Object.hasOwn(record, key))
-            continue;
+    for (const key of [...keys, "maxBytes"]) {
         const value = record[key];
+        if (value === undefined || value === Infinity)
+            continue;
         if (typeof value !== "number" || !Number.isSafeInteger(value) || value < (key === "maxMetadataUnits" ? 1 : 0)) {
-            throw new RangeError(`${key} must be a ${key === "maxMetadataUnits" ? "positive" : "nonnegative"} safe integer`);
+            throw new RangeError(`${key} must be a ${key === "maxMetadataUnits" ? "positive" : "nonnegative"} safe integer or Infinity`);
         }
         limits[key] = value;
     }

package/dist/safe-fs/fs/memory/missing-target.d.ts

@@ -1,3 +1,4 @@
+import { type PathLimits } from "../../contracts/virtual-path.js";
 type Node = {
     type: "file";
     mode: number;
@@ -10,5 +11,5 @@ type Node = {
     mode: number;
     entries: ReadonlyMap<string, Node>;
 };
-export declare function resolveMissingTarget(root: Node, path: string, signal?: AbortSignal): string;
+export declare function resolveMissingTarget(root: Node, path: string, signal?: AbortSignal, limits?: PathLimits): string;
 export {};

package/dist/safe-fs/fs/memory/missing-target.js

@@ -1,3 +1,4 @@
+import { pathByteLength, validatePath } from "../../contracts/virtual-path.js";
 import { FsError } from "../../contracts/errors.js";
 function utf8ByteLength(value) {
     let bytes = 0;
@@ -32,11 +33,14 @@ function components(path, signal) {
     }
     return result;
 }
-export function resolveMissingTarget(root, path, signal) {
+export function resolveMissingTarget(root, path, signal, limits = {}) {
+    validatePath(path, limits);
     const fail = (code, failedPath = path) => {
         throw new FsError(code, { syscall: "realpath", path: failedPath });
     };
     const origin = components(path, signal);
+    let remainingBytes = (limits.maxPathBytes ?? Infinity) - pathByteLength(path);
+    let remainingComponents = (limits.maxPathComponents ?? Infinity) - origin.length;
     const initial = { node: root, name: "" };
     let position = initial;
     let links = 0;
@@ -89,7 +93,10 @@ export function resolveMissingTarget(root, path, signal) {
             if (node.type === "symlink") {
                 if (++links > 40)
                     return fail("ELOOP");
+                validatePath(node.target, { maxPathBytes: remainingBytes, maxPathComponents: remainingComponents });
                 const names = components(node.target, signal);
+                remainingBytes -= pathByteLength(node.target);
+                remainingComponents -= names.length;
                 if (node.target.endsWith("/"))
                     names.push({ name: ".", start: node.target.length });
                 if (node.target.startsWith("/"))

package/dist/safe-fs/fs/s3/namespace.js

@@ -18,7 +18,7 @@ export async function createS3NamespaceFileSystem(options) {
         throw new TypeError('An explicit S3 bucket and manifest key are required');
     const maxBytes = limit(options.maxBytes);
     const maxEntries = limit(options.maxEntries);
-    const maxManifestBytes = limit(options.maxManifestBytes ?? 4 * 1024 * 1024);
+    const maxManifestBytes = options.maxManifestBytes === Infinity ? Infinity : limit(options.maxManifestBytes);
     const maxAttempts = limit(options.maxAttempts);
     const descriptorOptions = options;
     for (const key of ['chunkBytes', 'maxStagedBytes', 'maxStagedPages', 'maxFileBytes', 'maxOpenFiles']) {

package/dist/safe-fs/fs/scoped.js

@@ -537,8 +537,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
 }
 export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
     const maximum = options?.maxOperations ?? Infinity;
-    if (options?.maxOperations !== undefined && (!Number.isSafeInteger(maximum) || maximum < 0))
-        throw new RangeError("cleanup maxOperations must be a nonnegative safe integer");
+    if (maximum !== Infinity && (!Number.isSafeInteger(maximum) || maximum < 0))
+        throw new RangeError("cleanup maxOperations must be a nonnegative safe integer or Infinity");
     if (typeof cleanupCallback !== "function")
         throw new TypeError("cleanup callback must be a function");
     const scope = originals.get(filesystem);

package/dist/safe-fs/fs/webdav/webdav.d.ts

@@ -29,6 +29,8 @@ export interface WebDavFileSystemOptions {
     readonly maxResponseBytes?: number;
     /** Metadata response ceiling before decoding/parsing; unlimited unless configured. */
     readonly maxXmlBytes?: number;
+    /** Timestamp property UTF-8 byte ceiling; unlimited unless configured. */
+    readonly maxTimestampPropertyBytes?: number;
     readonly maxEntries?: number;
     /** XML structure ceilings; unlimited unless configured. */
     readonly xmlLimits?: Pick<XmlLimits, "maxNodes" | "maxContentNodes" | "maxDepth" | "maxAttributes">;
@@ -80,6 +82,7 @@ export declare class WebDavFileSystem implements FileSystem {
     private readonly headers;
     private readonly maxResponseBytes;
     private readonly maxXmlBytes;
+    private readonly maxTimestampPropertyBytes;
     private readonly maxEntries;
     private readonly xmlLimits;
     private readonly timeoutMs;

package/dist/safe-fs/fs/webdav/webdav.js

@@ -6,16 +6,15 @@ import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admissi
 import { assertCallbackAuthorityAllowed, compareEntries, registerEntryAuthority } from "../mount/comparison.js";
 import { compareWebDavResources, ownedResponseIdentifier, recordOwnedResourceStat, registerResourceQuery, resourceIdentifier } from "./resource-id.js";
 const timestampNamespace = "urn:virtual-bash:metadata";
-const maxTimestampPropertyBytes = 4096;
 /** Admit only five scalar members before native JSON parsing can allocate a graph. */
-function preflightTimestamps(property) {
+function preflightTimestamps(property, maxTimestampPropertyBytes) {
     // Check the untrimmed text first; counting UTF-8 bytes does not allocate an encoded copy.
     let bytes = 0;
     for (const point of property.text) {
         const code = point.codePointAt(0);
         bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
         if (bytes > maxTimestampPropertyBytes)
-            throw new Error("timestamp property exceeds 4KiB limit");
+            throw new Error("timestamp property exceeds byte limit");
     }
     const text = scalar(property);
     let offset = 0;
@@ -233,6 +232,7 @@ export class WebDavFileSystem {
     headers;
     maxResponseBytes;
     maxXmlBytes;
+    maxTimestampPropertyBytes;
     maxEntries;
     xmlLimits;
     timeoutMs;
@@ -290,6 +290,7 @@ export class WebDavFileSystem {
             streamingAppend: this.requestStreamSupport !== false,
         });
         this.maxResponseBytes = options.maxResponseBytes === undefined ? Infinity : positive(options.maxResponseBytes, "maxResponseBytes", false, true);
+        this.maxTimestampPropertyBytes = positive(options.maxTimestampPropertyBytes ?? Infinity, "maxTimestampPropertyBytes", true, true);
         this.maxXmlBytes = options.maxXmlBytes === undefined ? Infinity : positive(options.maxXmlBytes, "maxXmlBytes", false, true);
         this.xmlLimits = Object.freeze({ ...options.xmlLimits });
         for (const [name, value] of Object.entries(this.xmlLimits))
@@ -714,7 +715,7 @@ export class WebDavFileSystem {
         let mtimeMs = date("getlastmodified") ?? 0;
         let atimeMs = 0;
         if (timestampProperty) {
-            const timestamps = JSON.parse(preflightTimestamps(timestampProperty));
+            const timestamps = JSON.parse(preflightTimestamps(timestampProperty, this.maxTimestampPropertyBytes));
             if (typeof timestamps !== "object" || timestamps === null
                 || !("version" in timestamps) || timestamps.version !== 1
                 || !("etag" in timestamps) || typeof timestamps.etag !== "string" || !/^"[\x21\x23-\x7e\x80-\xff]*"$/.test(timestamps.etag)

package/dist/xml-ast/index.js

@@ -264,27 +264,42 @@ export function* parseXmlSteps(input, limits = {}) {
             throw new XmlLimitError("maxContentNodes", "XML content node limit exceeded");
     };
     let pendingWork = 0;
-    const skipWhitespace = () => {
+    const skipWhitespace = function* () {
         const start = offset;
         while (offset < source.length) {
             const c = source.charCodeAt(offset);
             if (c !== 32 && c !== 9 && c !== 10 && c !== 13)
                 break;
             offset++;
+            pendingWork++;
+            if (pendingWork >= 512) {
+                yield 512;
+                pendingWork -= 512;
+            }
         }
         return offset - start;
     };
-    const scanName = () => {
+    const scanName = function* () {
         const start = offset;
         while (offset < source.length) {
             const c = source.charCodeAt(offset);
             if (c === 32 || c === 9 || c === 13 || c === 10 || c === 47 || c === 61 || c === 62 || c === 63)
                 break;
             offset++;
+            pendingWork++;
+            if (pendingWork >= 512) {
+                yield 512;
+                pendingWork -= 512;
+            }
         }
         const name = source.slice(start, offset);
+        pendingWork += offset - start;
+        while (pendingWork >= 512) {
+            yield 512;
+            pendingWork -= 512;
+        }
         const [prefix, localName] = qualifiedNameSync(name, qualifiedNames);
-        return [name, prefix, localName, (offset - start) * 2];
+        return [name, prefix, localName];
     };
     while (offset < source.length) {
         pendingWork += 1;
@@ -322,11 +337,15 @@ export function* parseXmlSteps(input, limits = {}) {
             }
             else {
                 for (let index = 0; index < resolved.length; index++) {
+                    pendingWork++;
+                    if (pendingWork >= 512) {
+                        yield 512;
+                        pendingWork -= 512;
+                    }
                     const c = resolved.charCodeAt(index);
                     if (c !== 32 && c !== 9 && c !== 13 && c !== 10)
                         invalid("text outside the root");
                 }
-                pendingWork += resolved.length;
                 while (pendingWork >= 512) {
                     yield 512;
                     pendingWork -= 512;
@@ -371,8 +390,7 @@ export function* parseXmlSteps(input, limits = {}) {
         else if (source.startsWith("<?", offset)) {
             const start = offset;
             offset += 2;
-            const [target, , , wName] = scanName();
-            pendingWork += wName;
+            const [target] = yield* scanName();
             while (pendingWork >= 512) {
                 yield 512;
                 pendingWork -= 512;
@@ -415,8 +433,8 @@ export function* parseXmlSteps(input, limits = {}) {
         }
         else if (source.charCodeAt(offset + 1) === 47) {
             offset += 2;
-            const [name, , , wName] = scanName();
-            pendingWork += wName + skipWhitespace();
+            const [name] = yield* scanName();
+            yield* skipWhitespace();
             while (pendingWork >= 512) {
                 yield 512;
                 pendingWork -= 512;
@@ -430,13 +448,14 @@ export function* parseXmlSteps(input, limits = {}) {
         else {
             offset++;
             const repeated = previousEmpty && source.startsWith(previousEmpty.suffix, offset) ? previousEmpty : undefined;
-            const [name, prefix, localName, wName] = repeated
-                ? [repeated.name, repeated.prefix, repeated.localName, repeated.name.length * 2]
-                : scanName();
+            const [name, prefix, localName] = repeated
+                ? [repeated.name, repeated.prefix, repeated.localName]
+                : (yield* scanName());
             if (repeated)
                 offset += name.length;
             // Preserve scan/validation work while reusing the admitted spelling.
-            pendingWork += wName;
+            if (repeated)
+                pendingWork += name.length * 2;
             while (pendingWork >= 512) {
                 yield 512;
                 pendingWork -= 512;
@@ -446,8 +465,7 @@ export function* parseXmlSteps(input, limits = {}) {
             let namespaces = stack.at(-1)?.namespaces ?? new Map([["xml", xmlNamespace]]);
             let ownsNamespaces = stack.length === 0;
             while (!repeated) {
-                const ws = skipWhitespace();
-                pendingWork += ws;
+                const ws = (yield* skipWhitespace());
                 while (pendingWork >= 512) {
                     yield 512;
                     pendingWork -= 512;
@@ -457,8 +475,7 @@ export function* parseXmlSteps(input, limits = {}) {
                     break;
                 if (ws === 0)
                     invalid("attributes require whitespace");
-                const [attribute, attrPrefix, attrLocal, wAttr] = scanName();
-                pendingWork += wAttr;
+                const [attribute, attrPrefix, attrLocal] = yield* scanName();
                 while (pendingWork >= 512) {
                     yield 512;
                     pendingWork -= 512;
@@ -469,10 +486,10 @@ export function* parseXmlSteps(input, limits = {}) {
                     throw new XmlLimitError("maxAttributes", "XML attribute limit exceeded");
                 if ((attributes?.size ?? 0) >= maxAttributesPerElement)
                     throw new XmlLimitError("maxAttributesPerElement", "XML attribute limit exceeded");
-                pendingWork += skipWhitespace();
+                yield* skipWhitespace();
                 if (source[offset++] !== "=")
                     invalid("missing attribute equals");
-                pendingWork += skipWhitespace();
+                yield* skipWhitespace();
                 const quote = source[offset++];
                 if (quote !== '"' && quote !== "'")
                     invalid("unquoted attribute");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.800",
+  "version": "0.1.802",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",