@poe-platform/safe-fs 0.1.818 → 0.1.819

package/README.md

@@ -54,7 +54,7 @@ rename nor inode/version identity from placeholder native metadata. Retained
 reads remain available, with native seek reporting `ENOTSUP`. Ordinary browser
 bundles cannot import this backend. Node keeps its POSIX host profile.
 
-For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Archive extraction requires atomic ancestry verification. MemoryFileSystem supports it, including a writable root composed with read-only mounts such as `/skills/.system`; the real adapter refuses it. Mount extraction delegates confinement to the root backend and keeps other mounts read-only in the extraction view. Extraction roots inside a separate mount are rejected because directory and metadata mutations cannot atomically guard ancestors on another backend. Staged file publication supports nested writable mounts when every ancestor provides authoritative validation. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
+For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Tar extraction can use `confineTrustedExtraction` on an externally isolated host tree. This view retains extraction roots and checks full ancestry at publication without claiming OS-atomic staging. Atomic archive extraction requires atomic ancestry verification. MemoryFileSystem supports it, including a writable root composed with read-only mounts such as `/skills/.system`; the real adapter refuses it. Mount extraction delegates confinement to each selected backend and keeps other mounts read-only. Extraction inside a separate mount requires synchronous outer-ancestor guards at every mutation; backends that cannot honor those guards refuse it. Staged file publication supports nested writable mounts when every ancestor provides authoritative validation. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
 
 To create new outputs with Safe Bash's `dos2unix`, `unix2dos`, or compression commands, host adapters need atomic no-replace publication. Supply `createRealFileSystem({ root, renameNoReplace })` only when that callback binds a qualified native primitive such as Linux `renameat2` with `RENAME_NOREPLACE`. It receives resolved absolute host paths and an optional signal in its third argument. Existing destinations must reject `EEXIST` atomically; existence checks followed by rename and copy/delete are insufficient. Without this binding the adapter explicitly refuses those operations. See the [no-replace contract](src/contracts/filesystem.md#atomic-no-replace-rename).
 

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

@@ -83,6 +83,8 @@ export interface FileSystemCapabilities {
     readonly retainedStagingWrite?: boolean;
     /** Atomically verifies every supplied root-to-parent directory identity at publication. */
     readonly atomicStagingAncestry?: boolean;
+    /** Full ancestry validation serialized with publication on an externally isolated host. */
+    readonly trustedStagingAncestry?: boolean;
     /** Prepares directory guards that validate without yielding or mutating state. */
     readonly synchronousDirectoryValidation?: boolean;
     /** Captures a followed destination path with a synchronous commit validator. */
@@ -323,12 +325,18 @@ export interface ConditionalFilePublicationOptions extends FsOptions {
     readonly mode?: number;
     readonly mtimeMs?: number;
 }
+export interface ExtractionOptions extends FsOptions {
+    /** Validate outer mount bindings synchronously at every mutation; reject unsupported guards. */
+    readonly commitGuard?: () => true;
+}
 export interface FileSystem {
     /** Retain each extraction root and enforce no-symlink ancestry atomically with
      * every mutation (including metadata and both hardlink paths). Returned views
      * must refuse unsupported mutations; no check-then-write emulation is allowed.
      * Roots and their ancestors must remain the retained directories. */
-    confineExtraction?(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    confineExtraction?(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
+    /** Trusted-host counterpart; requires external tree isolation, and never promises OS-atomic confinement. */
+    confineTrustedExtraction?(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
     /** Explicit retained-object capability for qualified byte-path backends. */
     readonly objects?: ObjectFileSystem;
     /** Consume the complete source privately, then atomically compare/publish.

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

@@ -9,7 +9,7 @@ export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
 export { parseXml, parseXmlSteps, parseXmlSourceSteps, normalizeXmlChunks, parseXmlStream, XmlLimitError } from "./xml.js";
-export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits, XmlParserFrame, XmlFrameRequest, XmlNamespaceScope, XmlNamespaceRequest, XmlAttributeRequest, XmlAttributeRecord } from "./xml.js";
+export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits, XmlParserFrame, XmlFrameRequest, XmlNamespaceScope, XmlNamespaceRequest, XmlSourceRead, XmlSourceSpan, XmlAttributeRequest, XmlAttributeRecord } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";

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

@@ -144,7 +144,7 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, synchronousStagingResolution: false, synchronousFollowedStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    return Object.freeze({ ...rest, synchronousStagingResolution: false, synchronousFollowedStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, trustedStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -181,7 +181,7 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
         (unavailable ??= {}).synchronousStagingResolution = false;
     if (capabilities.synchronousFollowedStagingResolution === true && (capabilities.synchronousStagingResolution !== true || unavailable?.synchronousStagingResolution === false))
         (unavailable ??= {}).synchronousFollowedStagingResolution = false;
-    if (capabilities.guardedStagingPublication === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+    if (capabilities.guardedStagingPublication === true && ((capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false) && capabilities.trustedOwnedStaging !== true))
         (unavailable ??= {}).guardedStagingPublication = false;
     if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))
         (unavailable ??= {}).atomicDirectoryMetadata = false;
@@ -195,8 +195,11 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
                 }
             }
         }
-        if (missing)
+        if (missing) {
             (unavailable ??= {}).trustedOwnedStaging = false;
+            unavailable.trustedStagingAncestry = false;
+            unavailable.guardedStagingPublication = false;
+        }
     }
     return unavailable ? { ...capabilities, ...unavailable } : capabilities;
 }
@@ -206,7 +209,7 @@ export async function requireOwnedMutation(filesystem, path, capability, options
         const query = create ? { ...options, create: true } : options;
         const capabilities = ownedMutationCapabilities(filesystem, await filesystem.capabilitiesFor?.(path, capability === "atomicStagingAncestry" ? { ...query, stagingAncestry: true } : query) ?? filesystem.capabilities);
         options.signal?.throwIfAborted();
-        if (capabilities[capability] !== true && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
+        if (capabilities[capability] !== true && !(capability === "atomicStagingAncestry" && capabilities.trustedStagingAncestry === true && capabilities.trustedOwnedStaging === true) && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
             throw new FsError("ENOTSUP", { path, syscall: capability });
     }
     catch (error) {

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

@@ -1,3 +1,4 @@
+import type { ExtractionOptions } from "../../contracts/filesystem.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
@@ -51,7 +52,8 @@ export declare class DeviceFileSystem implements FileSystem {
     access(path: string, mode?: number, options?: FsOptions): Promise<void>;
     readlink(path: string, options?: FsOptions): Promise<string>;
     symlink(target: string, path: string, options?: FsOptions): Promise<void>;
-    confineExtraction(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    confineTrustedExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
+    confineExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
     link(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
     chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
     utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;

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

@@ -873,6 +873,13 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.symlink(target, path, options);
     }
+    async confineTrustedExtraction(roots, options = {}) {
+        options.signal?.throwIfAborted();
+        const operation = this.#filesystem.confineTrustedExtraction ?? this.#filesystem.confineExtraction;
+        if (!operation)
+            throw new FsError("ENOTSUP", { syscall: "confineTrustedExtraction" });
+        return operation.call(this.#filesystem, roots, options);
+    }
     async confineExtraction(roots, options = {}) {
         options.signal?.throwIfAborted();
         if (!this.#filesystem.confineExtraction)

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

@@ -1,3 +1,4 @@
+import { plainDevicePathResolvers } from "./plain-path.js";
 import { FsError, isFsError } from "../../contracts/errors.js";
 import { pathByteLength, validatePath } from "../../contracts/virtual-path.js";
 import { capturePathNamespace, pathNamespace } from "../path-namespace.js";
@@ -146,6 +147,11 @@ export async function resolveDevicePath(filesystem, path, options, followFinal =
         const fast = tryResolveMemoryDevicePath(filesystem, path, resizeCreate);
         if (fast !== undefined)
             return fast;
+        if (followFinal && resizeCreate === undefined && traversal === undefined && isCleanAbsolutePath(path) && path !== "/" && path !== "/dev" && !path.startsWith("/dev/")) {
+            const resolved = await plainDevicePathResolvers.get(filesystem)?.(path, options);
+            if (resolved !== undefined)
+                return resolved;
+        }
     }
     const namespace = capturePathNamespace(filesystem, options);
     if (resizeCreate !== undefined)

package/dist/safe-fs/fs/devices/plain-path.d.ts

@@ -0,0 +1,2 @@
+import type { FileSystem, FsOptions } from "../../contracts/filesystem.js";
+export declare const plainDevicePathResolvers: WeakMap<FileSystem, (path: string, options: FsOptions) => Promise<string | undefined>>;

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

@@ -0,0 +1,3 @@
+// Private backend hooks, not cached path observations. A hook may only accept
+// an ordinary existing path after freshly checking every component for symlinks.
+export const plainDevicePathResolvers = new WeakMap();

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

@@ -1,3 +1,4 @@
+import type { ExtractionOptions } from "../../contracts/filesystem.js";
 import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, FileDescriptor, OpenFileOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import { type MemoryAtomicView } from "./atomic-view.js";
@@ -77,7 +78,7 @@ export declare class MemoryFileSystem implements FileSystem {
     constructor(options?: MemoryFileSystemOptions);
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
-    confineExtraction(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    confineExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
     private metadata;
     private directory;
     private addDirectoryNode;

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

@@ -738,6 +738,7 @@ export class MemoryFileSystem {
     }
     async confineExtraction(roots, options = {}) {
         options.signal?.throwIfAborted();
+        const commitGuard = options.commitGuard;
         const retained = new Map();
         for (const root of roots) {
             this.validatePath(root, "confineExtraction");
@@ -757,6 +758,8 @@ export class MemoryFileSystem {
         const allowed = new Set(["mkdir", "rm", "rmdir", "rename", "symlink", "link", "chmod", "utimes", "writeFile", "appendFile", "writeStream", "writeFileConditional", "removeFileConditional", "removeEntryConditional", "prepareDirectory", "createStagedFile", "publishStagedFile", "removeStagedFile"]);
         const reads = new Set(["access", "capabilitiesFor", "compareEntry", "lstat", "stat", "readFile", "readStream", "readdir", "readlink", "realpath"]);
         const check = (path, followFinal) => {
+            if (commitGuard)
+                runStagingGuard(commitGuard);
             if (!roots.some(root => root === "/" || path === root || path.startsWith(`${root}/`)))
                 this.fail("EPERM", "confineExtraction", path);
             const components = path.split("/").filter(Boolean);

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

@@ -1,3 +1,4 @@
+import type { ExtractionOptions } from "../../contracts/filesystem.js";
 import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
@@ -12,7 +13,9 @@ export declare class MountFileSystem implements FileSystem {
     private namespaceMutation;
     private readonly namespaceWaiters;
     constructor(options: MountFileSystemOptions);
-    confineExtraction(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    private confineArchive;
+    confineTrustedExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
+    confineExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
     private select;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
     private supportsStagingAncestry;

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

@@ -152,35 +152,66 @@ export class MountFileSystem {
             ...(retainedRead === undefined ? {} : { retainedRead }),
         });
     }
-    async confineExtraction(roots, options = {}) {
-        options.signal?.throwIfAborted();
-        const root = this.select("/").backend;
-        const captured = [...roots];
-        for (const path of captured) {
+    async confineArchive(roots, options, trusted) {
+        const callerGuard = options.commitGuard;
+        const groups = new Map();
+        for (const path of [...roots]) {
             validatePath(path);
             if (normalizePath(globalPath(path)) !== path)
                 fail("EINVAL");
-            // A backing confinement retains its own root-to-destination ancestry.
-            // It cannot retain directories belonging to another mounted backend.
-            if (this.select(path).path !== "/")
+            const location = await this.resolve(path, options, { followFinal: false, entry: true });
+            if (location.path !== path || location.stat?.type !== "directory" || location.synthetic)
                 fail("ENOTSUP");
+            const paths = groups.get(location.mount) ?? [];
+            paths.push(location.local);
+            groups.set(location.mount, paths);
+        }
+        const confined = new Map();
+        for (const mount of this.mounts) {
+            const paths = groups.get(mount);
+            const backend = mount.backend;
+            const operation = trusted ? backend.confineTrustedExtraction ?? backend.confineExtraction : backend.confineExtraction;
+            if (paths && !operation)
+                fail("ENOTSUP");
+            let outerGuard;
+            if (paths && mount.path !== "/") {
+                const parent = mount.path.slice(0, mount.path.lastIndexOf("/")) || "/";
+                const ancestors = await Promise.all(directoryAncestryPaths(parent).map(async (path) => ({ path, stat: await this.lstat(path, options) })));
+                outerGuard = await this.prepareAncestry(ancestors, options);
+            }
+            const controls = { ...options, ...(outerGuard || callerGuard ? { commitGuard: () => {
+                        if (callerGuard)
+                            runStagingGuard(callerGuard);
+                        if (outerGuard)
+                            runStagingGuard(outerGuard);
+                        return true;
+                    } } : {}) };
+            const view = paths ? await operation.call(backend, paths, controls) : createReadOnlyFileSystem(backend);
+            const observations = paths ? view : backend;
+            confined.set(mount, new Proxy(view, {
+                get(target, property) {
+                    if (property === "capabilities")
+                        return { ...target.capabilities, synchronousDirectoryValidation: observations.capabilities.synchronousDirectoryValidation };
+                    if (property === "capabilitiesFor")
+                        return async (path, query = {}) => ({
+                            ...await target.capabilitiesFor?.(path, query) ?? target.capabilities,
+                            synchronousDirectoryValidation: (await observations.capabilitiesFor?.(path, query) ?? observations.capabilities).synchronousDirectoryValidation,
+                        });
+                    // These capture bindings; mutations still use the confined view.
+                    const owner = property === "prepareDirectoryAncestry" || property === "prepareStagingResolution" ? backend : target;
+                    const value = Reflect.get(owner, property);
+                    return typeof value === "function" ? value.bind(owner) : value;
+                },
+            }));
         }
-        if (!root.confineExtraction)
-            fail("ENOTSUP");
-        const confined = await root.confineExtraction(captured, options);
         options.signal?.throwIfAborted();
-        const observations = new Set(["prepareDirectoryAncestry", "prepareStagingResolution"]);
-        const backing = new Proxy(confined, {
-            get(target, key) {
-                // These only capture/validate bindings. Mutations must always use the
-                // backend's confined view, including creation, metadata and hardlinks.
-                const owner = observations.has(key) ? root : target;
-                const value = Reflect.get(owner, key);
-                return typeof value === "function" ? value.bind(owner) : value;
-            },
-        });
-        return new MountFileSystem({ root: backing, mounts: Object.fromEntries(this.mounts.filter(mount => mount.path !== "/").map(mount => [mount.path,
-                mount.backend.capabilities.readOnly === true ? mount.backend : createReadOnlyFileSystem(mount.backend)])) });
+        return new MountFileSystem({ root: confined.get(this.select("/")), mounts: Object.fromEntries(this.mounts.filter(mount => mount.path !== "/").map(mount => [mount.path, confined.get(mount)])) });
+    }
+    confineTrustedExtraction(roots, options = {}) {
+        return this.confineArchive(roots, options, true);
+    }
+    confineExtraction(roots, options = {}) {
+        return this.confineArchive(roots, options, false);
     }
     select(path) {
         return this.mounts.find((mount) => within(mount.path, path));
@@ -221,7 +252,7 @@ export class MountFileSystem {
                     && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
                 : this.capabilities.conditionalChmod;
             const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, synchronousFollowedStagingResolution: ignoredFollowedResolution, ...ordinary } = resize;
-            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution, ...(options.followFinalSymlink === true ? { synchronousFollowedStagingResolution: resolution } : {}) }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution, ...(options.followFinalSymlink === true ? { synchronousFollowedStagingResolution: resolution } : {}) }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry && resize.atomicStagingAncestry === true, trustedStagingAncestry: ancestry && resize.trustedStagingAncestry === true, ...(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)
@@ -240,7 +271,7 @@ 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.atomicFileStaging !== true || capabilities.atomicStagingAncestry !== true) && (capabilities.trustedOwnedStaging !== true || capabilities.trustedStagingAncestry !== true)
             || capabilities.guardedStagingPublication !== true || capabilities.readOnly === true)
             return false;
         const parent = target.path.slice(0, target.path.lastIndexOf("/")) || "/";

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

@@ -1,3 +1,4 @@
+import type { ExtractionOptions } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 import type { ConditionalWriteFileOptions, ConditionalRemoveFileOptions, PrepareDirectoryOptions, 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";
@@ -19,7 +20,7 @@ export declare class OverlayFileSystem implements FileSystem {
     private readonly publication;
     private queue;
     constructor(options: OverlayFileSystemOptions);
-    confineExtraction(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    confineExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
     createStagedFile(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;

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

@@ -148,6 +148,8 @@ export class OverlayFileSystem {
         Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
     }
     confineExtraction(roots, options = {}) {
+        if (options.commitGuard !== undefined)
+            return Promise.reject(new FsError("ENOTSUP"));
         return this.run(options, async () => this.publication.confine(roots, options, (options, operation) => this.run(options, operation, false), this, this.maxBufferBytes), false);
     }
     createStagedFile(directory, name, content, options) {

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

@@ -1,3 +1,4 @@
+import type { ExtractionOptions } from "../../contracts/filesystem.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.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 {
@@ -54,6 +55,7 @@ export declare class RealFileSystem implements FileSystem {
     readonly capabilities: FileSystemCapabilities;
     private readonly configuredRoot;
     private readonly renameNoReplace;
+    private extractionGuard?;
     private rootPromise;
     constructor(options: RealFileSystemOptions | string);
     private root;
@@ -62,6 +64,7 @@ export declare class RealFileSystem implements FileSystem {
     private path;
     private operation;
     private protectRoot;
+    confineTrustedExtraction(roots: readonly string[], options?: ExtractionOptions): Promise<FileSystem>;
     private stagingSnapshot;
     private expectStaging;
     private stagingMetadata;

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

@@ -1,7 +1,8 @@
+import { plainDevicePathResolvers } from "../devices/plain-path.js";
 import { platform } from "#safe-fs-platform";
 import { snapshotStagingCreation } from "../staging-cleanup.js";
 import { snapshotConditionalChmod } from "../conditional-chmod.js";
-import { runStagingGuard, snapshotDirectoryAncestry } from "../staging-ancestry.js";
+import { directoryAncestryPaths, runStagingGuard, snapshotDirectoryAncestry } from "../staging-ancestry.js";
 import { constants } from "node:fs";
 import * as immediate from "node:fs";
 import * as native from "node:fs/promises";
@@ -110,6 +111,7 @@ export class RealFileSystem {
     });
     configuredRoot;
     renameNoReplace;
+    extractionGuard;
     rootPromise;
     constructor(options) {
         const root = typeof options === "string" ? options : options.root;
@@ -121,6 +123,30 @@ export class RealFileSystem {
             throw new FsError("ENOTSUP", { syscall: "root", message: "this backend requires a POSIX host" });
         }
         this.configuredRoot = root;
+        if (Object.getPrototypeOf(this) === RealFileSystem.prototype) {
+            plainDevicePathResolvers.set(this, async (path, options) => {
+                if (this.lstat !== realImplementation.lstat?.value || this.readlink !== realImplementation.readlink?.value)
+                    return undefined;
+                try {
+                    let target = await this.root(options);
+                    const components = path.slice(1).split("/");
+                    for (let index = 0; index < components.length; index++) {
+                        options.signal?.throwIfAborted();
+                        target = join(target, components[index]);
+                        const stat = await native.lstat(target);
+                        options.signal?.throwIfAborted();
+                        if ((!stat.isFile() && !stat.isDirectory()) || (index < components.length - 1 && !stat.isDirectory()))
+                            return undefined;
+                    }
+                    return path;
+                }
+                catch {
+                    options.signal?.throwIfAborted();
+                    // Missing entries, symlinks and other failures use generic routing.
+                    return undefined;
+                }
+            });
+        }
         this.renameNoReplace = typeof options === "string" ? undefined : options.renameNoReplace;
         if (this.renameNoReplace !== undefined) {
             if (!platform.nativeFileSystem.atomicRename)
@@ -140,10 +166,15 @@ export class RealFileSystem {
         })();
         const root = await this.rootPromise;
         options.signal?.throwIfAborted();
-        if (await native.realpath(root) !== root)
+        const [canonical, metadata] = await Promise.allSettled([native.realpath(root), native.stat(root)]);
+        if (canonical.status === "rejected")
+            throw canonical.reason;
+        if (canonical.value !== root)
             throw new FsError("EACCES");
         options.signal?.throwIfAborted();
-        if (!(await native.stat(root)).isDirectory())
+        if (metadata.status === "rejected")
+            throw metadata.reason;
+        if (!metadata.value.isDirectory())
             throw new FsError("ENOTDIR");
         options.signal?.throwIfAborted();
         return root;
@@ -283,6 +314,57 @@ export class RealFileSystem {
     // These critical sections contain no await. They serialize with all JavaScript
     // callers, under this adapter's existing trusted-host (externally isolated tree)
     // boundary. They deliberately do not advertise the stronger atomic capabilities.
+    async confineTrustedExtraction(roots, options = {}) {
+        if (!platform.nativeFileSystem.trustedOwnedStaging || !roots.length)
+            throw new FsError("ENOTSUP");
+        const root = await this.root(options);
+        const retained = new Map();
+        const captured = [...roots];
+        const commitGuard = options.commitGuard;
+        for (const path of captured) {
+            for (const ancestor of directoryAncestryPaths(path)) {
+                const host = join(root, ancestor.slice(1));
+                const stat = this.stagingSnapshot(host);
+                if (stat?.type !== "directory")
+                    throw new FsError("ENOTDIR", { path: ancestor });
+                this.expectStaging(host, stat, true);
+                retained.set(host, stat);
+            }
+        }
+        options.signal?.throwIfAborted();
+        const view = new RealFileSystem({ root });
+        Object.defineProperty(view, "capabilities", { value: Object.freeze({ ...view.capabilities, trustedStagingAncestry: true, guardedStagingPublication: true, synchronousDirectoryValidation: true }) });
+        view.extractionGuard = host => {
+            if (commitGuard)
+                runStagingGuard(commitGuard);
+            const path = `/${relative(root, host)}`;
+            if (!captured.some(base => base === "/" || path === base || path.startsWith(`${base}/`)))
+                throw new FsError("EPERM");
+            for (const [entry, stat] of retained)
+                view.expectStaging(entry, stat, true);
+            for (const ancestor of directoryAncestryPaths(dirname(path))) {
+                const entry = join(root, ancestor.slice(1));
+                if (view.stagingSnapshot(entry)?.type !== "directory")
+                    throw new FsError("EAGAIN");
+                if (immediate.realpathSync(entry) !== entry)
+                    throw new FsError("EAGAIN");
+            }
+        };
+        const reads = new Set(["access", "capabilitiesFor", "lstat", "stat", "readFile", "readStream", "openReadFile", "readdir", "readlink", "realpath", "prepareDirectoryAncestry"]);
+        const mutations = new Set(["prepareDirectory", "createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "link"]);
+        return new Proxy(view, {
+            get(target, property) {
+                if (property === "confineTrustedExtraction" || property === "confineExtraction")
+                    return undefined;
+                const value = Reflect.get(target, property);
+                if (typeof value !== "function")
+                    return value;
+                if (reads.has(String(property)) || mutations.has(String(property)))
+                    return value.bind(target);
+                return () => { throw new FsError("ENOTSUP", { syscall: String(property) }); };
+            },
+        });
+    }
     stagingSnapshot(path) {
         try {
             return fileStat(immediate.lstatSync(path, { bigint: true }));
@@ -361,6 +443,7 @@ export class RealFileSystem {
             options.signal?.throwIfAborted();
             this.protectTerminal(directoryPath);
             this.expectStaging(dirname(directory), options.parent, true);
+            this.extractionGuard?.(directory);
             immediate.mkdirSync(directory, { mode: 0o700 });
             const file = join(directory, name);
             try {
@@ -417,8 +500,12 @@ export class RealFileSystem {
             throw new FsError("ENOTSUP", { path: destination });
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
             options.signal?.throwIfAborted();
-            if (options.ancestors !== undefined || options.commitGuard !== undefined)
+            if (!this.extractionGuard && (options.ancestors !== undefined || options.commitGuard !== undefined))
                 throw new FsError("ENOTSUP");
+            const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
+            if (ancestors && ancestors.at(-1).path !== dirname(destination))
+                throw new FsError("EINVAL");
+            const root = await this.root(options);
             const paths = await this.stagingPaths(staging, options);
             const target = await this.path(destination, { ...options, followFinal: false, missing: "final" });
             options.signal?.throwIfAborted();
@@ -432,6 +519,12 @@ export class RealFileSystem {
                 throw new FsError("EINVAL");
             if (existing && existing.type !== "file")
                 throw new FsError("EAGAIN");
+            if (ancestors)
+                for (const entry of ancestors)
+                    this.expectStaging(join(root, entry.path.slice(1)), entry.stat, true);
+            if (options.commitGuard)
+                runStagingGuard(options.commitGuard);
+            this.extractionGuard?.(target);
             immediate.renameSync(paths.file, target);
         }, destination, true);
     }
@@ -446,6 +539,7 @@ export class RealFileSystem {
             const children = immediate.readdirSync(paths.directory);
             if (children.length !== (file ? 1 : 0) || file && children[0] !== basename(paths.file))
                 throw new FsError("ENOTEMPTY");
+            this.extractionGuard?.(paths.directory);
             if (file)
                 immediate.unlinkSync(paths.file);
             immediate.rmdirSync(paths.directory);
@@ -463,6 +557,7 @@ export class RealFileSystem {
             const existing = this.expectStaging(target, options.expected);
             if (existing && existing.type !== "file")
                 throw new FsError("EAGAIN");
+            this.extractionGuard?.(target);
             const fd = immediate.openSync(target, constants.O_WRONLY | constants.O_NOFOLLOW | (existing ? 0 : constants.O_CREAT | constants.O_EXCL), options.mode ?? 0o666);
             try {
                 if (!options.append)
@@ -501,6 +596,7 @@ export class RealFileSystem {
             const file = this.expectStaging(target, options.expected);
             if (file?.type !== "file" || file.nlink !== 1)
                 throw new FsError("EAGAIN");
+            this.extractionGuard?.(target);
             immediate.unlinkSync(target);
         });
     }
@@ -515,6 +611,7 @@ export class RealFileSystem {
             const existing = this.expectStaging(target, options.expected, true);
             if (existing && existing.type !== "directory")
                 throw new FsError("EAGAIN");
+            this.extractionGuard?.(target);
             if (!existing)
                 immediate.mkdirSync(target, { mode: options.mode ?? 0o777 });
             if (options.mode !== undefined)
@@ -853,7 +950,15 @@ export class RealFileSystem {
             const source = await this.path(existingPath, { ...options, followFinal: false });
             const destination = await this.path(newPath, { ...options, followFinal: false, missing: "final" });
             options.signal?.throwIfAborted();
-            await native.link(source, destination);
+            if (this.extractionGuard) {
+                this.extractionGuard(source);
+                this.extractionGuard(destination);
+                if (this.stagingSnapshot(source)?.type !== "file")
+                    throw new FsError("EAGAIN");
+                immediate.linkSync(source, destination);
+            }
+            else
+                await native.link(source, destination);
         }, newPath);
     }
     async chmod(path, mode, options = {}) {

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

@@ -20,7 +20,7 @@ export function retargetScopedFileSystem(scoped, charge, signal, cleanupCharge =
 const operations = new Set([
     "prepareDirectoryAncestry", "prepareStagingResolution", "publishStagedFileSet",
     "publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
-    "confineExtraction", "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
+    "confineExtraction", "confineTrustedExtraction", "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
     "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir", "iterateDirectory",
     "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "unlink", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
@@ -507,7 +507,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             throw error;
                         }
                     }
-                    : property === "confineExtraction"
+                    : (property === "confineExtraction" || property === "confineTrustedExtraction")
                         ? async (...args) => scopeFileSystem(await dispatch(...args), charge, signal, cleanupCharge, options)
                         : property === "open"
                             ? async (path, options) => {