@poe-platform/safe-fs 0.1.727 → 0.1.729

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

@@ -36,7 +36,9 @@ function hasCode(error, code) {
 function fail(code, path, message) {
     throw new FsError(code, { syscall: "overlay", path, ...(message === undefined ? {} : { message }) });
 }
-function integer(value, path) {
+function integer(value, path, unlimited = false) {
+    if (unlimited && value === Infinity)
+        return;
     if (!Number.isSafeInteger(value) || value < 0)
         fail("EINVAL", path);
 }
@@ -86,7 +88,7 @@ export class OverlayFileSystem {
         }, false));
         this.maxBufferBytes = options.maxBufferBytes ?? Infinity;
         if (options.maxBufferBytes !== undefined)
-            integer(options.maxBufferBytes, "/");
+            integer(options.maxBufferBytes, "/", true);
         const writable = !this.#upper.capabilities.readOnly && this.#upper.capabilities.atomicRename === true;
         const readable = [this.#upper, this.#lower].map((backend) => retainedReadCapabilities(backend).retainedRead);
         const streamingRead = readable.every((capability) => capability === true) ? true
@@ -123,7 +125,8 @@ export class OverlayFileSystem {
         this.capabilities = Object.freeze({
             ...semantics,
             open: false,
-            atomicFilePublication: false, atomicFileMutation: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+            conditionalChmod: this.publication.supported(),
+            atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), atomicDirectoryMetadata: false, trustedOwnedStaging: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
                 : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
@@ -519,7 +522,7 @@ export class OverlayFileSystem {
             fail("EISDIR", entry.path);
         this.permission(entry, 4);
         if (options.maxBytes !== undefined)
-            integer(options.maxBytes, entry.path);
+            integer(options.maxBytes, entry.path, true);
         const limit = Math.min(options.maxBytes ?? this.maxBufferBytes, this.maxBufferBytes);
         if (entry.stat.size > limit)
             fail("EFBIG", entry.path);
@@ -683,13 +686,14 @@ export class OverlayFileSystem {
         }
         return location;
     }
-    async replace(location, options, operation, streaming = false) {
+    async replace(location, options, operation, streaming = false, commitGuard) {
         await this.parent(location.path, options);
         await this.staged(options, async (temporary) => {
             if (location.entry)
                 await this.clone(location.entry, temporary, options, streaming);
             await operation(temporary);
             options.signal?.throwIfAborted();
+            commitGuard?.();
             await this.#upper.rename(temporary, location.path, options);
             this.linkMetadata.delete(location.path);
             this.linkOrigins.delete(location.path);
@@ -1003,6 +1007,24 @@ export class OverlayFileSystem {
         if (permissions === undefined)
             fail("EINVAL", path);
         mode(permissions, path);
+        const guard = this.publication.prepareChmod(path, options);
+        if (guard) {
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            return this.run(controls, async () => {
+                this.writable(path);
+                guard();
+                const entry = await this.required(path, controls, false);
+                guard();
+                if (entry.stat.type === "directory") {
+                    await this.copyUp(entry, controls);
+                    guard();
+                    await this.#upper.chmod(entry.path, permissions, controls);
+                }
+                else {
+                    await this.replace({ path: entry.path, entry }, controls, temporary => this.#upper.chmod(temporary, permissions, controls), false, guard);
+                }
+            });
+        }
         return this.metadata(path, "permissions", options, (target) => this.#upper.chmod(target, permissions, options));
     }
     async utimes(path, atimeMs, mtimeMs, options = {}) {

package/dist/safe-fs/fs/overlay/memory-publication.d.ts

@@ -1,4 +1,4 @@
-import type { CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, PublishStagedFileOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, ChmodOptions, PublishStagedFileOptions, StagedFileContent } from "../../contracts/filesystem.js";
 /** Stock Memory mutations commit before returning their promise. No user code or
  * await is allowed between inspecting the two stores and invoking a mutation. */
 export declare class OverlayMemoryPublication {
@@ -26,6 +26,7 @@ export declare class OverlayMemoryPublication {
     private inspect;
     private capture;
     private check;
+    prepareChmod(path: string, options: ChmodOptions): (() => true) | undefined;
     private copyParents;
     create(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publish(staging: FileStaging, path: string, options: PublishStagedFileOptions): Promise<void>;

package/dist/safe-fs/fs/overlay/memory-publication.js

@@ -2,6 +2,8 @@ import { FsError, isFsError } from "../../contracts/errors.js";
 import { dirname, isPathWithin, validatePath } from "../../contracts/virtual-path.js";
 import { memoryAtomicView } from "../memory/atomic-view.js";
 import { compareIdentity } from "../mount/identity.js";
+import { snapshotConditionalChmod } from "../conditional-chmod.js";
+import { runStagingGuard } from "../staging-ancestry.js";
 /** Stock Memory mutations commit before returning their promise. No user code or
  * await is allowed between inspecting the two stores and invoking a mutation. */
 export class OverlayMemoryPublication {
@@ -21,10 +23,10 @@ export class OverlayMemoryPublication {
         this.opaque = opaque;
         this.hidden = hidden;
     }
-    supported() { return !!memoryAtomicView(this.upper) && !!memoryAtomicView(this.lower); }
+    supported() { return this.upper.capabilities.readOnly !== true && !!memoryAtomicView(this.upper) && !!memoryAtomicView(this.lower); }
     stores() {
         const upper = memoryAtomicView(this.upper), lower = memoryAtomicView(this.lower);
-        if (!upper || !lower)
+        if (!upper || !lower || this.upper.capabilities.readOnly === true)
             throw new FsError("ENOTSUP", { syscall: "overlayPublication" });
         return { upper, lower };
     }
@@ -138,6 +140,41 @@ export class OverlayMemoryPublication {
                 throw new FsError("ENOTDIR", { path: entry.path });
         }
     }
+    prepareChmod(path, options) {
+        const { signal, parent, expected, ancestors, commitGuard } = options;
+        const sources = ancestors?.map(entry => ({ path: entry.path, stat: entry.stat }));
+        const captured = snapshotConditionalChmod(path, {
+            ...(signal === undefined ? {} : { signal }), ...(parent === undefined ? {} : { parent }),
+            ...(expected === undefined ? {} : { expected }), ...(sources === undefined ? {} : { ancestors: sources }),
+            ...(commitGuard === undefined ? {} : { commitGuard }),
+        });
+        if (!captured)
+            return undefined;
+        this.stores();
+        this.path(path);
+        const retain = (source, snapshot) => {
+            const receipt = this.receipts.get(source);
+            if (!receipt)
+                throw new FsError("ENOTSUP", { path, message: "unowned overlay chmod receipt" });
+            this.receipts.set(snapshot, receipt);
+        };
+        retain(parent, captured.parent);
+        retain(expected, captured.expected);
+        for (const [index, entry] of captured.ancestors.entries())
+            retain(sources[index].stat, entry.stat);
+        return () => {
+            signal?.throwIfAborted();
+            if (captured.commitGuard)
+                runStagingGuard(captured.commitGuard);
+            this.stores();
+            this.check(captured.ancestors);
+            this.expect(dirname(path), captured.parent);
+            this.expect(path, captured.expected, captured.expected.type !== "directory");
+            if (this.inspect(path)?.type !== captured.expected.type)
+                throw new FsError("EAGAIN", { path });
+            return true;
+        };
+    }
     async copyParents(entries, options) {
         for (const entry of entries) {
             options.signal?.throwIfAborted();

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

@@ -153,15 +153,15 @@ async function existingBytes(fs, path, options) {
     }
 }
 export function withFileSystemQuota(fs, options) {
-    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)
-        throw new RangeError("maxBytes must be a nonnegative safe integer");
+    if (options.maxBytes !== Infinity && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0))
+        throw new RangeError("maxBytes must be a nonnegative safe integer or Infinity");
     const scanLimits = {
         maxScanEntries: options.maxScanEntries ?? Infinity,
         maxScanDepth: options.maxScanDepth ?? Infinity,
     };
     for (const [name, value] of Object.entries({ maxScanEntries: options.maxScanEntries, maxScanDepth: options.maxScanDepth })) {
-        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
-            throw new RangeError(`${name} must be a nonnegative safe integer`);
+        if (value !== undefined && value !== Infinity && (!Number.isSafeInteger(value) || value < 0))
+            throw new RangeError(`${name} must be a nonnegative safe integer or Infinity`);
     }
     let queue = Promise.resolve();
     let reservedBytes = 0;
@@ -499,7 +499,7 @@ export function withFileSystemQuota(fs, options) {
     // capabilities and methods without violating invariants on own properties.
     return new Proxy(Object.create(fs), {
         get(_target, property) {
-            if (property === "publishFileConditional" || property === "removeEntryConditional" || property === "writeFileConditional" || property === "removeFileConditional" || property === "resizeFile" || property === "canonicalizeMissingTarget" || property === "createStagedFile" || property === "publishStagedFile" || property === "removeStagedFile" || property === "prepareDirectory")
+            if (property === "prepareStagingResolution" || property === "prepareDirectoryAncestry" || property === "publishFileConditional" || property === "removeEntryConditional" || property === "writeFileConditional" || property === "removeFileConditional" || property === "resizeFile" || property === "canonicalizeMissingTarget" || property === "createStagedFile" || property === "publishStagedFile" || property === "removeStagedFile" || property === "prepareDirectory")
                 return undefined;
             if (property === "capabilities")
                 return quotaCapabilities({ ...retainedResizeCapabilities(fs, retainedReadCapabilities(fs)), ...(typeof fs.open === "function" ? {} : { open: false }) });

package/dist/safe-fs/fs/readonly/index.d.ts

@@ -3,6 +3,7 @@ import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, Direct
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export declare class ReadOnlyFileSystem implements FileSystem {
     #private;
+    readonly removeEntryConditional?: NonNullable<FileSystem["removeEntryConditional"]>;
     constructor(filesystem: FileSystem);
     get capabilities(): FileSystemCapabilities;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;

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

@@ -7,6 +7,7 @@ import { openRetainedReadFile, readOnlyCapabilities, retainedReadCapabilities }
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { forwardFileDescriptor, openFileDescriptor } from "../descriptor.js";
 import { pathNamespace, readOnlyPathNamespace } from "../path-namespace.js";
+import { memoryAtomicView, registerMemoryAtomicView } from "../memory/atomic-view.js";
 function readOnly(syscall, path, dest) {
     throw new FsError("EROFS", { syscall, path, ...(dest === undefined ? {} : { dest }) });
 }
@@ -37,6 +38,17 @@ export class ReadOnlyFileSystem {
     #capabilities;
     constructor(filesystem) {
         this.#filesystem = filesystem;
+        const atomic = memoryAtomicView(filesystem);
+        if (atomic)
+            registerMemoryAtomicView(this, atomic, () => {
+                if (Object.getPrototypeOf(this) !== ReadOnlyFileSystem.prototype || memoryAtomicView(filesystem) !== atomic)
+                    return false;
+                return Object.entries(readOnlyImplementation).every(([name, expected]) => {
+                    const actual = Object.getOwnPropertyDescriptor(this, name)
+                        ?? Object.getOwnPropertyDescriptor(ReadOnlyFileSystem.prototype, name);
+                    return actual?.value === expected.value && actual?.get === expected.get && actual?.set === expected.set;
+                });
+            });
         if (Reflect.has(filesystem, pathNamespace))
             Object.defineProperty(this, pathNamespace, {
                 get: () => readOnlyPathNamespace(Reflect.get(filesystem, pathNamespace)),
@@ -190,6 +202,7 @@ export class ReadOnlyFileSystem {
         readOnly("openResizeFile", path);
     }
 }
+const readOnlyImplementation = Object.getOwnPropertyDescriptors(ReadOnlyFileSystem.prototype);
 export function createReadOnlyFileSystem(filesystem) {
     return new ReadOnlyFileSystem(filesystem);
 }

package/dist/safe-fs/fs/real/index.d.ts

@@ -1,5 +1,5 @@
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent, OpenReadFileOptions, OpenResizeFileOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
+import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ChmodOptions, FileStagingEntry, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent, OpenReadFileOptions, OpenResizeFileOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
 export interface RealFileSystemOptions {
     /** An existing, absolute host directory. It is never created implicitly. */
     readonly root: string;
@@ -36,6 +36,9 @@ export interface RealFileSystemOptions {
  * concurrent renames, mount changes, and preexisting hardlinks cannot be made
  * safe by these APIs. This is NOT a race-proof sandbox or an isolation boundary
  * against another process modifying the tree. Use an OS sandbox for that.
+ * Conditional chmod and synchronous ancestry validation use the same trusted,
+ * externally isolated tree boundary as owned staging. Their final checks and
+ * metadata commit do not yield to JavaScript; they do not prevent OS races.
  *
  * Only regular files, directories, and symlinks are represented. Permissions,
  * ownership, timestamp precision, case sensitivity, umask, and rename behavior
@@ -62,6 +65,7 @@ export declare class RealFileSystem implements FileSystem {
     private stagingSnapshot;
     private expectStaging;
     private stagingMetadata;
+    prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
     createStagedFile(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     private stagingPaths;
     private checkStaging;
@@ -89,7 +93,7 @@ export declare class RealFileSystem implements FileSystem {
     readlink(path: string, options?: FsOptions): Promise<string>;
     symlink(target: string, path: string, options?: FsOptions): Promise<void>;
     link(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
-    chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
+    chmod(path: string, mode: number, options?: ChmodOptions): Promise<void>;
     utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
     truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
     openResizeFile(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;

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

@@ -1,3 +1,6 @@
+import { snapshotStagingCreation } from "../staging-cleanup.js";
+import { snapshotConditionalChmod } from "../conditional-chmod.js";
+import { runStagingGuard, snapshotDirectoryAncestry } from "../staging-ancestry.js";
 import { constants } from "node:fs";
 import * as immediate from "node:fs";
 import * as native from "node:fs/promises";
@@ -79,6 +82,9 @@ function nativeError(error) {
  * concurrent renames, mount changes, and preexisting hardlinks cannot be made
  * safe by these APIs. This is NOT a race-proof sandbox or an isolation boundary
  * against another process modifying the tree. Use an OS sandbox for that.
+ * Conditional chmod and synchronous ancestry validation use the same trusted,
+ * externally isolated tree boundary as owned staging. Their final checks and
+ * metadata commit do not yield to JavaScript; they do not prevent OS races.
  *
  * Only regular files, directories, and symlinks are represented. Permissions,
  * ownership, timestamp precision, case sensitivity, umask, and rename behavior
@@ -98,6 +104,7 @@ export class RealFileSystem {
         rename: true, atomicRenameNoReplace: false, copy: true, exclusiveCopy: true, readlink: true, truncate: true,
         streamingAppend: true, randomAccessWrite: true,
         readOnly: false, symlinks: true, hardlinks: true, permissions: true,
+        conditionalChmod: true,
         timestamps: true, atomicRename: true, streamingRead: true, streamingWrite: true, retainedRead: true, retainedResize: true, trustedOwnedStaging: true,
     });
     configuredRoot;
@@ -244,18 +251,22 @@ export class RealFileSystem {
             throw new FsError("ENOENT");
         return this.walk(await this.root(options), path.split("/").map((name) => ({ name, fromLink: false })), options);
     }
-    async operation(syscall, path, options, action, dest) {
+    async operation(syscall, path, options, action, dest, preserveReceipt = false) {
         options.signal?.throwIfAborted();
         try {
             validatePath(path);
             if (dest !== undefined)
                 validatePath(dest);
             const result = await action();
-            options.signal?.throwIfAborted();
+            if (!preserveReceipt)
+                options.signal?.throwIfAborted();
             return result;
         }
         catch (error) {
-            options.signal?.throwIfAborted();
+            if (!preserveReceipt)
+                options.signal?.throwIfAborted();
+            else if (options.signal?.aborted && Object.is(error, options.signal.reason))
+                throw error;
             const converted = nativeError(error);
             throw new FsError(converted.code, {
                 syscall, path, ...(dest === undefined ? {} : { dest }),
@@ -298,11 +309,37 @@ export class RealFileSystem {
             if (time !== undefined && (!Number.isFinite(time) || Math.abs(time) > 8.64e15))
                 throw new FsError("EINVAL");
     }
+    async prepareDirectoryAncestry(ancestors, options = {}) {
+        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        controls.signal?.throwIfAborted();
+        const entries = snapshotDirectoryAncestry(ancestors);
+        const path = entries.at(-1).path;
+        return this.operation("prepareDirectoryAncestry", path, controls, async () => {
+            const root = await this.root(controls);
+            const validate = () => {
+                controls.signal?.throwIfAborted();
+                try {
+                    for (const entry of entries)
+                        this.expectStaging(join(root, entry.path.slice(1)), entry.stat, true);
+                    return true;
+                }
+                catch (error) {
+                    controls.signal?.throwIfAborted();
+                    throw new FsError(nativeError(error).code, { syscall: "prepareDirectoryAncestry", path });
+                }
+            };
+            validate();
+            return validate;
+        });
+    }
     async createStagedFile(directoryPath, name, content, options) {
+        options = snapshotStagingCreation(options, directoryPath);
         // Unlike operation(), this must return its receipt after commit even if the
         // signal is aborted before the promise settles.
         options.signal?.throwIfAborted();
         try {
+            if (options.retainCleanup === true)
+                throw new FsError("ENOTSUP");
             if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0"))
                 throw new FsError("EINVAL");
             this.stagingMetadata(options);
@@ -369,6 +406,9 @@ export class RealFileSystem {
     }
     async publishStagedFile(staging, destination, options) {
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
+            options.signal?.throwIfAborted();
+            if (options.ancestors !== undefined || options.commitGuard !== undefined)
+                throw new FsError("ENOTSUP");
             const paths = await this.stagingPaths(staging, options);
             const target = await this.path(destination, { ...options, followFinal: false, missing: "final" });
             options.signal?.throwIfAborted();
@@ -377,12 +417,13 @@ export class RealFileSystem {
             this.expectStaging(paths.file, staging.file.stat);
             this.expectStaging(dirname(target), options.parent, true);
             const existing = this.expectStaging(target, options.destination);
-            if (existing && (existing.type !== "file" || existing.nlink !== 1))
-                throw new FsError("EAGAIN");
-            if (target === paths.file || target === paths.directory || dirname(target) === paths.directory)
+            if (existing && existing.dev === staging.file.stat.dev && existing.ino === staging.file.stat.ino
+                || target === paths.file || target === paths.directory || dirname(target) === paths.directory)
                 throw new FsError("EINVAL");
+            if (existing && existing.type !== "file")
+                throw new FsError("EAGAIN");
             immediate.renameSync(paths.file, target);
-        }, destination);
+        }, destination, true);
     }
     async removeStagedFile(staging, options = {}) {
         return this.operation("removeStagedFile", staging.directory.path, options, async () => {
@@ -410,7 +451,7 @@ export class RealFileSystem {
             options.signal?.throwIfAborted();
             this.expectStaging(dirname(target), options.parent, true);
             const existing = this.expectStaging(target, options.expected);
-            if (existing && (existing.type !== "file" || existing.nlink !== 1))
+            if (existing && existing.type !== "file")
                 throw new FsError("EAGAIN");
             const fd = immediate.openSync(target, constants.O_WRONLY | constants.O_NOFOLLOW | (existing ? 0 : constants.O_CREAT | constants.O_EXCL), options.mode ?? 0o666);
             try {
@@ -427,6 +468,10 @@ export class RealFileSystem {
                 }
                 if (options.mode !== undefined)
                     immediate.fchmodSync(fd, options.mode);
+                if (options.atimeMs !== undefined || options.mtimeMs !== undefined) {
+                    const stat = immediate.fstatSync(fd);
+                    immediate.futimesSync(fd, (options.atimeMs ?? stat.atimeMs) / 1000, (options.mtimeMs ?? stat.mtimeMs) / 1000);
+                }
                 return fileStat(immediate.fstatSync(fd, { bigint: true }));
             }
             finally {
@@ -769,6 +814,31 @@ export class RealFileSystem {
     async chmod(path, mode, options = {}) {
         return this.operation("chmod", path, options, async () => {
             integer(mode);
+            const conditional = snapshotConditionalChmod(path, options);
+            if (conditional) {
+                const target = await this.path(path, { ...conditional, followFinal: false });
+                const root = await this.root(conditional);
+                if ((target === root ? "/" : `/${relative(root, target)}`) !== path)
+                    throw new FsError("EAGAIN");
+                if (conditional.expected.type !== "file" && conditional.expected.type !== "directory")
+                    throw new FsError("ENOTSUP");
+                const parent = target === root ? root : dirname(target);
+                const validate = () => {
+                    conditional.signal?.throwIfAborted();
+                    for (const entry of conditional.ancestors)
+                        this.expectStaging(join(root, entry.path.slice(1)), entry.stat, true);
+                    this.expectStaging(parent, conditional.parent, true);
+                    const current = this.expectStaging(target, conditional.expected, conditional.expected.type === "directory");
+                    if (current?.mode !== conditional.expected.mode)
+                        throw new FsError("EAGAIN");
+                };
+                validate();
+                if (conditional.commitGuard)
+                    runStagingGuard(conditional.commitGuard);
+                validate();
+                immediate.chmodSync(target, mode);
+                return;
+            }
             const target = await this.path(path, options);
             options.signal?.throwIfAborted();
             await native.chmod(target, mode);

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

@@ -14,6 +14,7 @@ export interface S3FileSystemOptions {
     readonly maxReadBytes?: number;
     readonly maxStreamBytes?: number;
     readonly maxListEntries?: number;
+    readonly maxRequests?: number;
     /** Aggregate budgets for each rm operation, including ancestor inspection. */
     readonly removalLimits?: {
         readonly maxRequests?: number;
@@ -74,6 +75,8 @@ export declare class S3FileSystem implements FileSystem {
     private readonly maxReadBytes;
     private readonly maxStreamBytes;
     private readonly maxListEntries;
+    private readonly maxRequests;
+    private requests;
     private readonly removalLimits;
     private readonly removalBudgets;
     constructor(options: S3FileSystemOptions);

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

@@ -3,6 +3,7 @@ import { FsError, isFsError } from "../../contracts/errors.js";
 import { composeAbortSignals } from "../../contracts/abort.js";
 import { collectBytes, readBytes } from "../../contracts/io.js";
 import { compareEntries, registerEntryAuthority } from "../mount/comparison.js";
+import { chargeScopedTransportCall } from "#safe-fs-platform";
 import { compareOwnedS3Entries, queryS3Head, recordS3Stat, registerS3EntryOwner } from "./authority.js";
 import { encodeCopySource } from "./transport.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
@@ -58,11 +59,31 @@ function fail(code, syscall, path, message) {
     throw new FsError(code, { syscall, path, ...(message === undefined ? {} : { message }) });
 }
 function validateLimit(value, name, minimum, maximum = Number.MAX_SAFE_INTEGER) {
-    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    if ((value !== Infinity || maximum !== Infinity) && (!Number.isSafeInteger(value) || value < minimum || value > maximum)) {
         throw new FsError("EINVAL", { message: `${name} must be an integer from ${minimum} to ${maximum}` });
     }
     return value;
 }
+function utf8ByteLength(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length && value.charCodeAt(i + 1) >= 0xdc00 && value.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+function exceedsComponentByteLimit(value) {
+    return value.length > 85 && (value.length > 255 || utf8ByteLength(value) > 255);
+}
 function isWellFormed(value) {
     return !/[\uD800-\uDFFF]/u.test(value);
 }
@@ -82,6 +103,8 @@ export class S3FileSystem {
     maxReadBytes;
     maxStreamBytes;
     maxListEntries;
+    maxRequests;
+    requests = 0;
     removalLimits;
     removalBudgets = new WeakMap();
     constructor(options) {
@@ -101,19 +124,20 @@ export class S3FileSystem {
             throw new FsError("EINVAL", { message: "prefix must be a canonical relative object-key prefix" });
         }
         this.prefix = prefix === "" || prefix.endsWith("/") ? prefix : `${prefix}/`;
-        if (Buffer.byteLength(this.prefix) > 1024)
+        if (utf8ByteLength(this.prefix) > 1024)
             throw new FsError("ENAMETOOLONG", { message: "S3 prefix exceeds 1024 UTF-8 bytes" });
         this.transport = options.transport;
         this.bucket = options.bucket;
         this.allowRename = options.allowNonAtomicRename ?? true;
         this.pageSize = validateLimit(options.pageSize ?? 1000, "pageSize", 1, 1000);
-        this.maxReadBytes = options.maxReadBytes === undefined ? Infinity : validateLimit(options.maxReadBytes, "maxReadBytes", 0);
-        this.maxStreamBytes = options.maxStreamBytes === undefined ? Infinity : validateLimit(options.maxStreamBytes, "maxStreamBytes", 0);
-        this.maxListEntries = options.maxListEntries === undefined ? Infinity : validateLimit(options.maxListEntries, "maxListEntries", 1);
+        this.maxReadBytes = options.maxReadBytes === undefined ? Infinity : validateLimit(options.maxReadBytes, "maxReadBytes", 0, Infinity);
+        this.maxStreamBytes = options.maxStreamBytes === undefined ? Infinity : validateLimit(options.maxStreamBytes, "maxStreamBytes", 0, Infinity);
+        this.maxListEntries = options.maxListEntries === undefined ? Infinity : validateLimit(options.maxListEntries, "maxListEntries", 1, Infinity);
+        this.maxRequests = options.maxRequests === undefined ? Infinity : validateLimit(options.maxRequests, "maxRequests", 1, Infinity);
         this.removalLimits = {
-            maxRequests: validateLimit(options.removalLimits?.maxRequests ?? 32, "removalLimits.maxRequests", 1),
-            maxListEntries: validateLimit(options.removalLimits?.maxListEntries ?? 32, "removalLimits.maxListEntries", 1),
-            maxDeleteObjects: validateLimit(options.removalLimits?.maxDeleteObjects ?? 16, "removalLimits.maxDeleteObjects", 1),
+            maxRequests: validateLimit(options.removalLimits?.maxRequests ?? Infinity, "removalLimits.maxRequests", 1, Infinity),
+            maxListEntries: validateLimit(options.removalLimits?.maxListEntries ?? Infinity, "removalLimits.maxListEntries", 1, Infinity),
+            maxDeleteObjects: validateLimit(options.removalLimits?.maxDeleteObjects ?? Infinity, "removalLimits.maxDeleteObjects", 1, Infinity),
         };
         this.capabilities = Object.freeze({
             open: false,
@@ -167,7 +191,7 @@ export class S3FileSystem {
                 components.push(part);
         }
         const path = `/${components.join("/")}`;
-        if (Buffer.byteLength(this.key(path)) > 1024)
+        if (utf8ByteLength(this.key(path)) > 1024)
             fail("ENAMETOOLONG", "resolve", input);
         return path;
     }
@@ -176,7 +200,7 @@ export class S3FileSystem {
     }
     directoryKey(path) {
         const key = path === "/" ? this.prefix : `${this.key(path)}/`;
-        if (Buffer.byteLength(key) > 1024)
+        if (utf8ByteLength(key) > 1024)
             fail("ENAMETOOLONG", "resolve", path);
         return key;
     }
@@ -188,11 +212,17 @@ export class S3FileSystem {
         return options.signal === undefined ? {} : { abortSignal: options.signal };
     }
     async call(syscall, path, options, action, precondition) {
+        this.checkAbort(options, syscall, path);
+        chargeScopedTransportCall(options);
         this.checkAbort(options, syscall, path);
         const budget = this.removalBudgets.get(options);
         if (budget && ++budget.requests > this.removalLimits.maxRequests) {
             fail("EFBIG", "rm", path, "S3 removal request budget exceeded");
         }
+        if (this.requests >= this.maxRequests) {
+            fail("EFBIG", syscall, path, "S3 transport request budget exceeded");
+        }
+        this.requests++;
         let onAbort;
         try {
             const pending = action();
@@ -297,7 +327,7 @@ export class S3FileSystem {
         if (!key.startsWith(this.prefix))
             fail("EIO", "listObjectsV2", path, "key escapes the configured prefix");
         const relative = key.slice(this.prefix.length).replace(/\/$/, "");
-        if (!isWellFormed(key) || key.includes("\0") || Buffer.byteLength(key) > 1024
+        if (!isWellFormed(key) || key.includes("\0") || utf8ByteLength(key) > 1024
             || (relative !== "" && relative.split("/").some((part) => !part || part === "." || part === ".."))) {
             fail("ENOTSUP", "listObjectsV2", path, "object key cannot be represented as a canonical filesystem path");
         }
@@ -338,22 +368,22 @@ export class S3FileSystem {
             return { stat: this.makeStat("directory", marker), ...(marker ? { metadata: marker } : {}) };
         }
         const file = await this.head(this.key(path), path, options);
-        if (Buffer.byteLength(this.key(path)) === 1024) {
+        if (utf8ByteLength(this.key(path)) === 1024) {
             return file ? { stat: this.makeStat("file", file), metadata: file } : undefined;
         }
         const directoryKey = this.directoryKey(path);
-        const marker = await this.head(directoryKey, path, options);
-        if (marker && marker.ContentLength !== 0)
-            this.unsupported("nonempty directory markers", path);
-        let directory = marker !== undefined;
-        if (!directory) {
-            for await (const children of this.pages(directoryKey, path, options, undefined, 1)) {
-                if ((children.Contents?.length ?? 0) > 0) {
-                    directory = true;
-                    break;
-                }
+        let directory = false;
+        let hasMarker = false;
+        for await (const children of this.pages(directoryKey, path, options, undefined, 1)) {
+            if ((children.Contents?.length ?? 0) > 0) {
+                directory = true;
+                hasMarker = children.Contents.some(object => object.Key === directoryKey);
+                break;
             }
         }
+        const marker = hasMarker ? await this.head(directoryKey, path, options) : undefined;
+        if (marker && marker.ContentLength !== 0)
+            this.unsupported("nonempty directory markers", path);
         if (file && directory)
             this.unsupported("file/prefix collisions", path);
         if (file)
@@ -370,6 +400,8 @@ export class S3FileSystem {
                 break;
         }
         for (const parent of ancestors) {
+            if (parent === "/" && this.prefix === "")
+                continue;
             const ancestor = await this.inspect(parent, options);
             if (!ancestor)
                 fail("ENOENT", "stat", parent);
@@ -395,7 +427,7 @@ export class S3FileSystem {
         return this.stat(path, options);
     }
     async body(output, path, options) {
-        const limit = Math.min(this.maxReadBytes, options.maxBytes === undefined ? this.maxReadBytes : validateLimit(options.maxBytes, "maxBytes", 0));
+        const limit = Math.min(this.maxReadBytes, options.maxBytes === undefined ? this.maxReadBytes : validateLimit(options.maxBytes, "maxBytes", 0, Infinity));
         let iterator;
         return this.call("readFile", path, options, async () => {
             if (output.Body && Symbol.asyncIterator in output.Body)
@@ -441,7 +473,7 @@ export class S3FileSystem {
     async readFile(input, options = {}) {
         const path = this.path(input);
         if (options.maxBytes !== undefined)
-            validateLimit(options.maxBytes, "maxBytes", 0);
+            validateLimit(options.maxBytes, "maxBytes", 0, Infinity);
         const info = await this.stat(input, options);
         if (info.type === "directory")
             fail("EISDIR", "readFile", path);
@@ -776,7 +808,7 @@ export class S3FileSystem {
             if (!conditionalCopy && object.Size > (streamFallback ? this.maxStreamBytes : this.maxReadBytes)) {
                 fail("EFBIG", "rename", source, "conditional PUT fallback exceeds its configured transfer or buffered read limit");
             }
-            if (Buffer.byteLength(this.key(destination) + object.Key.slice(this.key(source).length)) > 1024)
+            if (utf8ByteLength(this.key(destination) + object.Key.slice(this.key(source).length)) > 1024)
                 fail("ENAMETOOLONG", "rename", destination);
         }
         const copied = [];