@poe-platform/safe-fs 0.1.726 → 0.1.728

package/dist/safe-fs/fs/object-publication/index.js

@@ -15,6 +15,8 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
         || store.createStaging !== undefined && typeof store.createStaging !== "function")
         throw new TypeError("Invalid object descriptor configuration");
     const createStaging = store.createStaging?.bind(store);
+    const defaultIdentityScope = Symbol("object-file-descriptors");
+    const withIdentity = (stat) => stat.type === "file" && stat.identityScope === undefined ? { ...stat, identityScope: defaultIdentityScope } : stat;
     let stagedBytes = 0;
     let openFiles = 0;
     const stagingWaiters = new Set();
@@ -58,7 +60,7 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             throw new FsError("EIO", { message: "Invalid immutable object version" });
         if (value.stat.size > maxFileBytes)
             throw new FsError("EFBIG", { message: "Object descriptor file limit exceeded" });
-        return Object.freeze({ revision: value.revision, ...(value.publicationToken === undefined ? {} : { publicationToken: value.publicationToken }), stat: Object.freeze({ ...value.stat }), read: value.read.bind(value), close: value.close.bind(value) });
+        return Object.freeze({ revision: value.revision, ...(value.publicationToken === undefined ? {} : { publicationToken: value.publicationToken }), stat: Object.freeze(withIdentity(value.stat)), read: value.read.bind(value), close: value.close.bind(value) });
     };
     const clearPages = (state) => {
         stagedBytes -= state.pages.size * chunkBytes;
@@ -434,17 +436,91 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             throw error;
         }
     });
+    const openReadFile = async (path, readOptions = {}) => {
+        if (!readOptions || typeof readOptions !== "object"
+            || Object.keys(readOptions).some(key => key !== "signal" && key !== "allowDirectory")
+            || readOptions.allowDirectory !== undefined && typeof readOptions.allowDirectory !== "boolean") {
+            throw new FsError("EINVAL", { syscall: "openReadFile", path });
+        }
+        readOptions.signal?.throwIfAborted();
+        if (readOptions.allowDirectory === true)
+            throw new FsError("ENOTSUP", { syscall: "openReadFile", path });
+        const descriptor = await open(path, {
+            access: "read",
+            ...(readOptions.signal === undefined ? {} : { signal: readOptions.signal }),
+        });
+        let retainedStat;
+        try {
+            retainedStat = await descriptor.stat(readOptions.signal === undefined ? {} : { signal: readOptions.signal });
+        }
+        catch (error) {
+            await finishCleanup(() => descriptor.close(), true);
+            throw error;
+        }
+        let closed = false;
+        let closing;
+        const assertOpen = (forwarded, syscall) => {
+            forwarded.signal?.throwIfAborted();
+            if (closed)
+                throw new FsError("EBADF", { syscall, path });
+        };
+        return {
+            async stat(forwarded = {}) {
+                assertOpen(forwarded, "fstat");
+                return descriptor.stat(forwarded);
+            },
+            async seekEnd(forwarded = {}) {
+                assertOpen(forwarded, "lseek");
+                const stat = await descriptor.stat(forwarded);
+                return BigInt(stat.size);
+            },
+            async read(position, maxBytes, forwarded = {}) {
+                assertOpen(forwarded, "read");
+                if (!Number.isSafeInteger(position) || position < 0
+                    || !Number.isSafeInteger(maxBytes) || maxBytes <= 0
+                    || maxBytes > Number.MAX_SAFE_INTEGER - position) {
+                    throw new FsError("EINVAL", { syscall: "read", path });
+                }
+                const length = Math.min(maxBytes, Math.max(0, retainedStat.size - position));
+                if (length === 0) {
+                    await descriptor.stat(forwarded);
+                    return new Uint8Array();
+                }
+                const buffer = new Uint8Array(length);
+                const count = await descriptor.read(buffer, position, forwarded);
+                return count === buffer.byteLength ? buffer : buffer.subarray(0, count);
+            },
+            close() {
+                closed = true;
+                return closing ??= descriptor.close();
+            },
+        };
+    };
     return new Proxy(Object.create(filesystem), {
         get(_target, property) {
             if (property === "open")
                 return open;
+            if (property === "openReadFile")
+                return openReadFile;
+            if (property === "stat" || property === "lstat")
+                return async (path, statOptions) => withIdentity(await filesystem[property](path, statOptions));
             if (property === "capabilities")
-                return { ...filesystem.capabilities, open: true, versionedDescriptors: true };
+                return {
+                    ...filesystem.capabilities,
+                    open: true,
+                    versionedDescriptors: true,
+                    retainedRead: filesystem.capabilities.read !== false,
+                };
             if (property === "capabilitiesFor")
                 return async (path, query) => {
                     const capabilities = await filesystem.capabilitiesFor?.(path, query) ?? filesystem.capabilities;
                     query?.signal?.throwIfAborted();
-                    return { ...capabilities, open: true, versionedDescriptors: true };
+                    return {
+                        ...capabilities,
+                        open: true,
+                        versionedDescriptors: true,
+                        ...(query?.allowDirectory ? {} : { retainedRead: capabilities.read !== false }),
+                    };
                 };
             const value = Reflect.get(filesystem, property, filesystem);
             return typeof value === "function" ? value.bind(filesystem) : value;

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

@@ -1,6 +1,6 @@
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 export interface OverlayFileSystemOptions {
     readonly upper: FileSystem;
     readonly lower: FileSystem;
@@ -73,7 +73,7 @@ export declare class OverlayFileSystem implements FileSystem {
     symlink(target: string, path: string, options?: FsOptions): Promise<void>;
     link(_existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
     private metadata;
-    chmod(path: string, permissions: number, options?: FsOptions): Promise<void>;
+    chmod(path: string, permissions: 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>;
     readStream(path: string, options?: ReadStreamOptions): ByteSource;

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

@@ -123,7 +123,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,
@@ -683,13 +684,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 +1005,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

@@ -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);