@poe-platform/safe-fs 0.1.727 → 0.1.729

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

@@ -6,7 +6,10 @@ import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admissi
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
 import { forwardFileDescriptor, openFileDescriptor } from "../descriptor.js";
 import { pathNamespace } from "../path-namespace.js";
+import { createStagingCleanup, snapshotStagingCreation } from "../staging-cleanup.js";
+import { directoryAncestryPaths, inspectStagingBindings, runStagingGuard, snapshotDirectoryAncestry, snapshotStagingResolution } from "../staging-ancestry.js";
 import { compareIdentity } from "./identity.js";
+import { snapshotConditionalChmod } from "../conditional-chmod.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "./comparison.js";
 const syntheticStat = Object.freeze({
     type: "directory", size: 0, mode: 0o40555,
@@ -102,8 +105,10 @@ export class MountFileSystem {
         const common = (capability) => {
             const optional = {
                 open: ["open"],
+                retainedStagingCleanup: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
+                synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 trustedOwnedStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"],
-                atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
+                atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicEntryRemovalReceipt: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
                 descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
             };
@@ -111,7 +116,8 @@ export class MountFileSystem {
                 if (backend.capabilities.readOnly === true
                     && !["open", "versionedDescriptors", "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
                     return false;
-                const declared = backend.capabilities[capability];
+                const declared = capability === "retainedStagingCleanup" || capability === "atomicEntryRemovalReceipt"
+                    ? ownedMutationCapabilities(backend)[capability] : backend.capabilities[capability];
                 if (capability === "descriptorWriteStream" && backend.capabilities.streamingWrite === false)
                     return false;
                 return declared === true && optional[capability]?.some(method => typeof backend[method] !== "function") ? false : declared;
@@ -121,6 +127,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
+            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt",
             "trustedOwnedStaging", "atomicFilePublication", "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open", "versionedDescriptors",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
@@ -131,8 +138,13 @@ export class MountFileSystem {
             readOnly: all("readOnly"),
             ...(append === undefined ? {} : { append }),
             ...semantics,
-            atomicStagingAncestry: false,
+            // Real ancestry (including synthetic mount parents) is path-dependent.
+            synchronousStagingResolution: mounts.some(({ backend }) => typeof backend.prepareStagingResolution === "function") ? undefined : false,
+            atomicStagingAncestry: mounts.some(({ backend }) => typeof backend.prepareDirectoryAncestry === "function"
+                && typeof backend.publishStagedFile === "function" && (typeof backend.capabilitiesFor === "function"
+                || backend.capabilities.guardedStagingPublication !== false && backend.capabilities.synchronousDirectoryValidation !== false)) ? undefined : false,
             atomicRename: mounts.length === 1 && all("atomicRename"),
+            conditionalChmod: all("conditionalChmod", ["chmod", "prepareDirectoryAncestry"]),
             ...(streamingRead === undefined ? {} : { streamingRead }),
             ...(streamingWrite === undefined ? {} : { streamingWrite }),
             ...(retainedRead === undefined ? {} : { retainedRead }),
@@ -143,9 +155,11 @@ export class MountFileSystem {
     }
     async capabilitiesFor(path, options = {}) {
         return this.operation("capabilitiesFor", path, options, async () => {
+            if (options.stagingResolution === true && normalizePath(globalPath(path)) !== path)
+                fail("EINVAL");
             const location = await this.resolve(path, options, {
                 allowMissing: options.create ?? true,
-                followFinal: options.create !== undefined || options.creation !== "exclusive",
+                followFinal: options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"),
                 ...(options.create === undefined ? {} : { resizeCreate: options.create }),
             });
             const observed = ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(location.local, options)
@@ -155,7 +169,26 @@ export class MountFileSystem {
                 ? { ...observed, descriptorWriteStream: false } : observed;
             const resize = declared.atomicResize === true && (typeof location.mount.backend.resizeFile !== "function" || declared.readOnly === true)
                 ? { ...declared, atomicResize: false } : declared;
-            const withOpen = { ...resize, atomicStagingAncestry: false, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const ancestry = options.stagingAncestry === true && location.path === normalizePath(globalPath(path))
+                && await this.supportsStagingAncestry(location, resize, options);
+            const validation = options.stagingAncestry === true ? location.stat?.type === "directory"
+                && location.path === normalizePath(globalPath(path)) && await this.supportsDirectoryValidation(location.path, options) : undefined;
+            let resolution;
+            if (options.stagingResolution === true) {
+                resolution = false;
+                if (within(location.mount.path, path) && typeof location.mount.backend.prepareStagingResolution === "function") {
+                    const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
+                    const declared = input === location.local ? resize : ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(input, options) ?? location.mount.backend.capabilities);
+                    options.signal?.throwIfAborted();
+                    resolution = declared.synchronousStagingResolution === true && await this.supportsStagingAncestry(location, resize, options);
+                }
+            }
+            const conditionalChmod = options.conditionalChmod === true
+                ? resize.conditionalChmod === true && typeof location.mount.backend.chmod === "function"
+                    && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
+                : this.capabilities.conditionalChmod;
+            const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, ...ordinary } = resize;
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
@@ -171,6 +204,147 @@ export class MountFileSystem {
             });
         });
     }
+    async supportsStagingAncestry(target, capabilities, options) {
+        options.signal?.throwIfAborted();
+        if (target.synthetic || target.stat !== undefined && (target.stat.type !== "file" || compareIdentity(target.stat, target.stat) !== "same")
+            || capabilities.atomicFileStaging !== true || capabilities.atomicStagingAncestry !== true
+            || capabilities.guardedStagingPublication !== true || capabilities.readOnly === true)
+            return false;
+        const parent = target.path.slice(0, target.path.lastIndexOf("/")) || "/";
+        return this.supportsDirectoryValidation(parent, options);
+    }
+    async supportsDirectoryValidation(directory, options, conditionalChmod = false) {
+        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        for (const path of directoryAncestryPaths(directory)) {
+            const entry = await this.lookup(path, controls);
+            if (entry.synthetic || entry.stat?.type !== "directory" || compareIdentity(entry.stat, entry.stat) !== "same")
+                return false;
+            const backend = entry.mount.backend;
+            const declared = await backend.capabilitiesFor?.(entry.local, { ...controls, stagingAncestry: true }) ?? backend.capabilities;
+            options.signal?.throwIfAborted();
+            if (declared.synchronousDirectoryValidation !== true && !(conditionalChmod && declared.conditionalChmod === true)
+                || typeof backend.prepareDirectoryAncestry !== "function")
+                return false;
+        }
+        return true;
+    }
+    prepareDirectoryAncestry(ancestors, options = {}) {
+        return this.operation("prepareDirectoryAncestry", ancestors.at(-1)?.path ?? "/", options, () => this.prepareAncestry(ancestors, options));
+    }
+    prepareStagingResolution(path, options = {}) {
+        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        return this.operation("prepareStagingResolution", path, controls, async () => {
+            if (normalizePath(globalPath(path)) !== path)
+                fail("EINVAL");
+            const observed = [];
+            const location = await this.resolve(path, controls, { followFinal: false, allowMissing: true, resolutionSteps: observed });
+            if (location.synthetic || !within(location.mount.path, path))
+                fail("ENOTSUP");
+            const backend = location.mount.backend;
+            const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
+            const declared = ownedMutationCapabilities(backend, await backend.capabilitiesFor?.(input, { ...controls, stagingResolution: true }) ?? backend.capabilities);
+            controls.signal?.throwIfAborted();
+            if (declared.synchronousStagingResolution !== true || !backend.prepareStagingResolution)
+                fail("ENOTSUP");
+            const prefix = directoryAncestryPaths(location.mount.path).map(ancestor => {
+                const entry = observed.find(step => step.path === ancestor);
+                if (!entry)
+                    fail("ENOTSUP");
+                return entry;
+            });
+            const outerGuard = await this.prepareAncestry(prefix, controls);
+            const bound = snapshotStagingResolution(await backend.prepareStagingResolution(input, controls));
+            controls.signal?.throwIfAborted();
+            const mapPath = (local) => location.mount.path === "/" ? local : `${location.mount.path}${local === "/" ? "" : local}`;
+            const map = (entry) => ({ ...entry, path: mapPath(entry.path) });
+            const traversed = bound.traversed.map(map);
+            const localObserved = observed.filter(entry => within(location.mount.path, entry.path));
+            if (mapPath(bound.path) !== location.path || localObserved.length !== traversed.length)
+                fail("EAGAIN");
+            for (const [index, before] of localObserved.entries()) {
+                const after = traversed[index];
+                if (this.select(after.path) !== location.mount)
+                    fail("EACCES");
+                if (before.path !== after.path || before.linkTarget !== after.linkTarget || before.stat.type !== after.stat.type
+                    || compareIdentity(before.stat, after.stat) !== "same"
+                    || before.stat.type !== "directory" && ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].some(field => before.stat[field] !== after.stat[field]))
+                    fail("EAGAIN");
+            }
+            const validate = () => {
+                controls.signal?.throwIfAborted();
+                runStagingGuard(outerGuard);
+                runStagingGuard(bound.validate);
+                return true;
+            };
+            const result = snapshotStagingResolution({ ...bound, path: mapPath(bound.path),
+                ancestors: [...prefix.slice(0, -1), ...bound.ancestors.map(map)], traversed: [...prefix.slice(0, -1), ...traversed], validate });
+            runStagingGuard(validate);
+            return result;
+        });
+    }
+    async prepareAncestry(ancestors, options, conditionalChmod = false) {
+        options.signal?.throwIfAborted();
+        try {
+            const entries = snapshotDirectoryAncestry(ancestors);
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            const groups = [];
+            for (const entry of entries) {
+                const mount = this.select(entry.path);
+                let group = groups.at(-1);
+                if (group?.mount !== mount) {
+                    group = { mount, entries: [] };
+                    groups.push(group);
+                }
+                group.entries.push({ path: mount.path === "/" ? entry.path : entry.path.slice(mount.path.length) || "/", stat: entry.stat });
+            }
+            const guards = [];
+            for (const group of groups) {
+                controls.signal?.throwIfAborted();
+                const backend = group.mount.backend;
+                for (const entry of group.entries) {
+                    let current;
+                    try {
+                        current = await backend.lstat(entry.path, controls);
+                    }
+                    catch (error) {
+                        controls.signal?.throwIfAborted();
+                        if (["ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code))
+                            fail("EAGAIN");
+                        throw error;
+                    }
+                    controls.signal?.throwIfAborted();
+                    if (current.type !== "directory")
+                        fail("EAGAIN");
+                    const identity = compareIdentity(current, entry.stat);
+                    if (identity === "unknown")
+                        fail("ENOTSUP");
+                    if (identity !== "same")
+                        fail("EAGAIN");
+                    const declared = await backend.capabilitiesFor?.(entry.path, { ...controls, stagingAncestry: true }) ?? backend.capabilities;
+                    controls.signal?.throwIfAborted();
+                    if (declared.synchronousDirectoryValidation !== true && !(conditionalChmod && declared.conditionalChmod === true))
+                        fail("ENOTSUP");
+                }
+                if (typeof backend.prepareDirectoryAncestry !== "function")
+                    fail("ENOTSUP");
+                const guard = await backend.prepareDirectoryAncestry(group.entries, controls);
+                controls.signal?.throwIfAborted();
+                if (typeof guard !== "function")
+                    fail("ENOTSUP");
+                guards.push(guard);
+            }
+            return () => {
+                controls.signal?.throwIfAborted();
+                for (const guard of guards)
+                    runStagingGuard(guard);
+                return true;
+            };
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+    }
     protected(path) {
         return path === "/" || this.mounts.some((mount) => within(path, mount.path));
     }
@@ -324,23 +498,48 @@ export class MountFileSystem {
     async resolve(path, options, settings = {}) {
         let pending = this.components(path);
         const stack = [await this.lookup("/", options)];
+        let recordedUnits = 0;
+        const observe = (entry, linkTarget) => {
+            if (!settings.resolutionSteps || !entry.stat)
+                return;
+            recordedUnits += entry.path.length + (linkTarget?.length ?? 0);
+            if (settings.resolutionSteps.length >= 4096 || recordedUnits > 1_048_576)
+                fail("EFBIG");
+            settings.resolutionSteps.push({ path: entry.path, stat: snapshotStat(entry.stat), ...(linkTarget === undefined ? {} : { linkTarget }) });
+        };
+        observe(stack[0]);
         let boundary;
         let verification;
         let creationVerification;
+        let followedFinalLink = false;
         const verified = async (location) => {
-            const inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            let inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            // A missing entry has no realpath. Verify its existing parent while
+            // leaving dangling final symlinks on the ordinary following path.
+            if (inspection && !location.stat && settings.allowMissing && !followedFinalLink && inspection.finalName === undefined) {
+                const separator = inspection.path.lastIndexOf("/");
+                const finalName = inspection.path.slice(separator + 1);
+                if (finalName && finalName !== "." && finalName !== "..") {
+                    inspection = { ...inspection, path: inspection.path.slice(0, separator) || "/", finalName };
+                }
+            }
             if (inspection) {
                 const canonical = await inspection.mount.backend.realpath(inspection.path, options);
+                options.signal?.throwIfAborted();
+                if (!location.stat && inspection.finalName === undefined)
+                    fail("ENOTSUP");
                 validatePath(canonical);
                 if (!canonical.startsWith("/") || normalizePath(canonical) !== canonical)
                     fail("EIO");
                 if (inspection.finalName !== undefined) {
                     try {
                         await inspection.mount.backend.lstat(`${inspection.path}/${inspection.finalName}`, options);
-                        if (!location.stat && settings.resizeCreate === true)
+                        options.signal?.throwIfAborted();
+                        if (!location.stat && settings.allowMissing && settings.followFinal !== false)
                             fail("ENOTSUP");
                     }
                     catch (error) {
+                        options.signal?.throwIfAborted();
                         if (location.stat || toFsError(error).code !== "ENOENT")
                             throw error;
                     }
@@ -406,6 +605,8 @@ export class MountFileSystem {
             if (next.stat?.type === "symlink" && (settings.followFinal !== false || !final)) {
                 if (++links > 40)
                     fail("ELOOP");
+                if (final)
+                    followedFinalLink = true;
                 boundary ??= next.mount;
                 if (boundary !== next.mount)
                     fail("EACCES");
@@ -422,6 +623,7 @@ export class MountFileSystem {
                 }
                 const readlink = this.optional(next, "readlink", "symlinks");
                 const target = await readlink.call(next.mount.backend, next.local, options);
+                observe(next, target);
                 const targetParts = this.components(target);
                 if (settings.resizeCreate !== undefined && targetParts.at(-1)?.trailing && pending[0]?.trailing)
                     targetParts.pop();
@@ -446,6 +648,7 @@ export class MountFileSystem {
                 pending = [...targetParts, ...pending];
             }
             else {
+                observe(next);
                 stack.push(next);
             }
         }
@@ -672,6 +875,8 @@ export class MountFileSystem {
         }, undefined, true);
     }
     removeEntryConditional(path, options) {
+        options = { ...options };
+        const requested = options.returnRemainingStat === true;
         return this.operation("removeEntryConditional", path, options, async () => {
             const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true });
             if (this.protected(location.path))
@@ -679,10 +884,13 @@ export class MountFileSystem {
             this.mutable(location);
             const backend = location.mount.backend;
             await requireOwnedMutation(backend, location.local, "atomicEntryRemoval", options);
+            if (requested)
+                await requireOwnedMutation(backend, location.local, "atomicEntryRemovalReceipt", options);
             if (!backend.removeEntryConditional)
                 fail("ENOTSUP");
-            await backend.removeEntryConditional(location.local, options);
-        });
+            const receipt = await backend.removeEntryConditional(location.local, options);
+            return requested && receipt !== undefined ? Object.freeze(snapshotStat(receipt)) : undefined;
+        }, undefined, requested);
     }
     removeFileConditional(path, options) {
         return this.operation("removeFileConditional", path, options, async () => {
@@ -710,7 +918,8 @@ export class MountFileSystem {
             await backend.removeTreeConditional(location.local, options);
         });
     }
-    createStagedFile(path, name, content, options) {
+    async createStagedFile(path, name, content, options) {
+        options = snapshotStagingCreation(options, path);
         return this.operation("createStagedFile", path, options, async () => {
             const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true, missingDirectory: true });
             if (this.protected(location.path))
@@ -718,6 +927,8 @@ export class MountFileSystem {
             this.mutable(location);
             const backend = location.mount.backend;
             await requireOwnedMutation(backend, location.local, "atomicFileStaging", options, true);
+            if (options.retainCleanup === true)
+                await requireOwnedMutation(backend, location.local, "retainedStagingCleanup", options, true);
             if (!backend.createStagedFile)
                 fail("ENOTSUP");
             const receipt = await backend.createStagedFile(location.local, name, content, options);
@@ -725,23 +936,103 @@ export class MountFileSystem {
                 path: location.mount.path === "/" ? entry.path : `${location.mount.path}${entry.path === "/" ? "" : entry.path}`,
                 stat: Object.freeze(snapshotStat(entry.stat)),
             });
-            return Object.freeze({ parent: map(receipt.parent), directory: map(receipt.directory), file: map(receipt.file) });
+            try {
+                const staging = { parent: map(receipt.parent), directory: map(receipt.directory), file: map(receipt.file) };
+                if (!receipt.cleanup)
+                    return Object.freeze(staging);
+                const backendCleanup = receipt.cleanup;
+                const cleanup = createStagingCleanup(staging.directory.path, controls => this.operation("removeStagedFile", staging.directory.path, controls, () => backendCleanup.remove(controls), undefined, true), () => backendCleanup.close());
+                return Object.freeze({ ...staging, cleanup });
+            }
+            catch (error) {
+                await finishCleanup(() => receipt.cleanup?.close(), true);
+                throw error;
+            }
         }, undefined, true);
     }
     publishStagedFile(staging, destination, options) {
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
+            const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
+            const callerGuard = options.commitGuard;
+            let guard;
+            if (ancestors) {
+                const canonical = normalizePath(globalPath(destination));
+                const parent = canonical.slice(0, canonical.lastIndexOf("/")) || "/";
+                if (canonical !== destination || ancestors.at(-1)?.path !== parent)
+                    fail("EINVAL");
+                guard = await this.prepareAncestry(ancestors, options);
+                runStagingGuard(guard);
+            }
             const local = await this.localStaging(staging, options);
             const target = await this.resolve(destination, options, { followFinal: false, entry: true, allowMissing: true });
+            if (ancestors) {
+                if (target.path !== destination)
+                    fail("EAGAIN");
+                if (options.destination === null) {
+                    if (target.stat !== undefined)
+                        fail("EAGAIN");
+                }
+                else {
+                    if (target.stat === undefined || target.stat.type !== options.destination.type)
+                        fail("EAGAIN");
+                    const identity = compareIdentity(target.stat, options.destination);
+                    if (identity === "unknown")
+                        fail("ENOTSUP");
+                    if (identity !== "same")
+                        fail("EAGAIN");
+                }
+            }
             if (this.protected(target.path))
                 fail("EBUSY");
             if (local.mount !== target.mount)
                 fail("EXDEV");
             this.mutable(target);
             await requireOwnedMutation(local.mount.backend, local.staging.directory.path, "atomicFileStaging", options);
+            await requireOwnedMutation(local.mount.backend, target.local, "atomicFileStaging", options, options.destination === null);
             if (!local.mount.backend.publishStagedFile)
                 fail("ENOTSUP");
-            await local.mount.backend.publishStagedFile(local.staging, target.local, options);
-        }, destination);
+            if (ancestors || callerGuard !== undefined)
+                await requireOwnedMutation(local.mount.backend, target.local, "guardedStagingPublication", options, options.destination === null);
+            if (!ancestors) {
+                await local.mount.backend.publishStagedFile(local.staging, target.local, options);
+                return;
+            }
+            const parent = target.path.slice(0, target.path.lastIndexOf("/")) || "/";
+            if (target.path !== normalizePath(globalPath(destination)) || ancestors.at(-1)?.path !== parent)
+                fail("EINVAL");
+            try {
+                const declared = await local.mount.backend.capabilitiesFor?.(target.local, { ...options, stagingAncestry: true, ...(options.destination === null ? { create: true } : {}) }) ?? local.mount.backend.capabilities;
+                if (!await this.supportsStagingAncestry(target, declared, options))
+                    fail("ENOTSUP");
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                if (["ENOTSUP", "ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code)) {
+                    await inspectStagingBindings(async (path) => {
+                        const entry = await this.lookup(path, options);
+                        if (!entry.stat)
+                            fail("ENOENT");
+                        return entry.stat;
+                    }, destination, options);
+                }
+                throw error;
+            }
+            const first = ancestors.findIndex(entry => entry.path === target.mount.path);
+            if (first < 0)
+                fail("EINVAL");
+            const localAncestors = ancestors.slice(first).map(entry => ({
+                path: target.mount.path === "/" ? entry.path : entry.path.slice(target.mount.path.length) || "/", stat: entry.stat,
+            }));
+            await local.mount.backend.publishStagedFile(local.staging, target.local, {
+                ...options, ancestors: localAncestors,
+                commitGuard: () => {
+                    if (callerGuard !== undefined)
+                        runStagingGuard(callerGuard);
+                    runStagingGuard(guard);
+                    return true;
+                },
+            });
+        }, destination, true);
     }
     removeStagedFile(staging, options = {}) {
         return this.operation("removeStagedFile", staging.directory.path, options, async () => {
@@ -895,9 +1186,29 @@ export class MountFileSystem {
     }
     chmod(path, mode, options = {}) {
         return this.operation("chmod", path, options, async () => {
-            const location = await this.resolve(path, options);
+            const conditional = snapshotConditionalChmod(path, options);
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            const location = await this.resolve(path, controls, conditional ? { followFinal: false } : {});
             this.mutable(location);
-            await this.optional(location, "chmod", "permissions").call(location.mount.backend, location.local, mode, options);
+            const chmod = this.optional(location, "chmod", "permissions");
+            if (!conditional)
+                return chmod.call(location.mount.backend, location.local, mode, controls);
+            if (location.path !== path)
+                fail("EAGAIN");
+            const backend = location.mount.backend;
+            const capabilities = await backend.capabilitiesFor?.(location.local, { ...controls, conditionalChmod: true }) ?? backend.capabilities;
+            if (capabilities.conditionalChmod !== true)
+                fail("ENOTSUP");
+            const guard = await this.prepareAncestry(conditional.ancestors, controls, true);
+            const ancestors = conditional.ancestors.filter(entry => this.select(entry.path) === location.mount).map(entry => ({
+                path: location.mount.path === "/" ? entry.path : entry.path.slice(location.mount.path.length) || "/", stat: entry.stat,
+            }));
+            await chmod.call(backend, location.local, mode, { ...conditional, ancestors, commitGuard: () => {
+                    if (conditional.commitGuard)
+                        runStagingGuard(conditional.commitGuard);
+                    runStagingGuard(guard);
+                    return true;
+                } });
         });
     }
     utimes(path, atimeMs, mtimeMs, options = {}) {

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;