@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/native-pinned-write-windows.js

@@ -6,9 +6,6 @@ import { FsSafeError } from "./errors.js";
 import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, writeNativeInput, } from "./native-operations.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
-export function sameNativeIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
 function closeWriteFd(fd) {
     if (fd === undefined)
         return;

package/dist/native-pinned-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAK3D,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2FvH"}
+{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAI3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAIV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAoV3B,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqGvH"}

package/dist/native-pinned-write.js

@@ -50,16 +50,278 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import fsSync from "node:fs";
-import fs from "node:fs/promises";
+import fsSync, {} from "node:fs";
 import path from "node:path";
 import { inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { runPinnedWriteWindows, sameNativeIdentity } from "./native-pinned-write-windows.js";
+import { runPinnedWriteWindows } from "./native-pinned-write-windows.js";
+import { openNativeParentAdmission, openNativeRootAdmission } from "./native-parent-admission.js";
 import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
-import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
+import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
+import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
+function relativeParentSegments(relativeParentPath) {
+    return relativeParentPath.split("/").filter(Boolean);
+}
+function prospectiveTargetPath(parentPath, parentRoute, offset, basename) {
+    return joinPathSegmentRoute(parentPath, parentRoute, offset, basename);
+}
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function assertDirectChildBasename(basename) {
+    if (!basename || basename === "." || basename === ".." || basename.includes("/") ||
+        basename.includes("\0") || (process.platform === "win32" && basename.includes("\\"))) {
+        throw new FsSafeError("invalid-path", "native parent creation requires one direct-child basename");
+    }
+}
+function mkdirPolicyChild(binding, parentFd, basename, mode) {
+    assertDirectChildBasename(basename);
+    const mkdirChild = binding.mkdirChildBeneath;
+    if (typeof mkdirChild === "function") {
+        const created = mkdirChild.call(binding, parentFd, basename, mode);
+        if (typeof created === "boolean")
+            return created;
+    }
+    // Old or malformed optional helpers still execute through the established
+    // recursive primitive, but cannot provide exclusive-creation provenance.
+    binding.mkdirBeneath(parentFd, basename, mode);
+    return false;
+}
+async function authorizePinnedMutation(params, request) {
+    return await params.mutationAdmission?.authorize(Object.freeze(request));
+}
+function normalizePolicyParentOpenError(error, params) {
+    if (!isSymlinkOpenError(error))
+        return error;
+    return params.mutationAdmission?.rejectParentSymlinks
+        ? new FsSafeError("symlink", "symlink path component not allowed", {
+            cause: error instanceof Error ? error : undefined,
+        })
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", {
+            cause: error instanceof Error ? error : undefined,
+        });
+}
+async function describePosixParent(parentFd, pathname) {
+    const parentPath = realpathSync.native(pathname);
+    const directory = describeStagedDirectory(parentFd, parentPath);
+    const parentPathStat = await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })));
+    return {
+        parentFd,
+        parentPath,
+        directory,
+        parentPathStat,
+        observation: checkedMutationDirectory(parentPath, directory.realPath, parentPathStat),
+    };
+}
+function describePolicyPosixParent(parentFd, pathname) {
+    const policyDirectory = describePolicyStagedDirectory(parentFd, pathname);
+    return {
+        parentFd,
+        parentPath: policyDirectory.directory.realPath,
+        directory: policyDirectory.directory,
+        parentPathStat: policyDirectory.stat,
+        observation: policyDirectory.observation,
+        policyDirectory,
+    };
+}
+function policyParentCaptureDeopt(error) {
+    return error instanceof FsSafeError &&
+        (error.code === "path-mismatch" || error.code === "not-file");
+}
+function tryDescribePolicyPosixParent(parentFd, pathname) {
+    try {
+        return describePolicyPosixParent(parentFd, pathname);
+    }
+    catch (error) {
+        if (!policyParentCaptureDeopt(error))
+            throw error;
+        return undefined;
+    }
+}
+function assertPosixParentCurrent(parent) {
+    return parent.policyDirectory
+        ? assertPolicyStagedDirectoryCurrent(parent.policyDirectory)
+        : assertStagedDirectoryCurrent(parent.directory);
+}
+async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryFlags) {
+    const segments = relativeParentSegments(params.relativeParentPath);
+    const parentSpelling = segments.length
+        ? path.join(params.rootPath, ...segments)
+        : params.rootPath;
+    const segmentRoute = createPathSegmentRoute(segments);
+    const initialTarget = prospectiveTargetPath(params.rootPath, segmentRoute, 0, params.basename);
+    let retainedTargetPath = params.mutationAdmission?.beginParentWalk?.();
+    if (retainedTargetPath && !sameAbsolutePath(retainedTargetPath, initialTarget)) {
+        retainedTargetPath = undefined;
+    }
+    // Preserve the one-open hot path when the complete parent still exists.
+    // Policy is attached only after the opened descriptor is associated with its
+    // current canonical pathname, so a contained redirect cannot retain the old
+    // preflight authorization.
+    let completeParentFd;
+    try {
+        completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT" || !params.mkdir)
+            throw error;
+    }
+    if (completeParentFd !== undefined) {
+        const parentFd = completeParentFd;
+        try {
+            let admitted = retainedTargetPath
+                ? tryDescribePolicyPosixParent(parentFd, parentSpelling)
+                : undefined;
+            if (!admitted) {
+                retainedTargetPath = undefined;
+                admitted = await describePosixParent(parentFd, parentSpelling);
+            }
+            const targetPath = path.join(admitted.parentPath, params.basename);
+            await authorizePinnedMutation(params, {
+                targetPath,
+                mutationPath: targetPath,
+                phase: "parent",
+            });
+            assertPosixParentCurrent(admitted);
+            return admitted;
+        }
+        catch (error) {
+            fsSync.closeSync(parentFd);
+            throw error;
+        }
+    }
+    // The canonical preflight spelling has no intentional symlinks in its
+    // existing prefix. Walk missing-parent cases one direct child at a time so
+    // every existing/opened object is authorized and every mkdir is authorized
+    // before dispatch. O_NOFOLLOW makes a concurrently introduced link fail
+    // before the next component can be created through it.
+    const secureDirectoryFlags = directoryFlags | (fsSync.constants.O_NOFOLLOW ?? 0);
+    let currentFd = rootFd;
+    let currentOwnedFd;
+    let currentPath = params.rootPath;
+    let current = retainedTargetPath
+        ? tryDescribePolicyPosixParent(rootFd, currentPath)
+        : undefined;
+    if (!current) {
+        retainedTargetPath = undefined;
+        current = await describePosixParent(rootFd, currentPath);
+    }
+    try {
+        await authorizePinnedMutation(params, {
+            targetPath: retainedTargetPath ?? initialTarget,
+            mutationPath: retainedTargetPath ?? initialTarget,
+            phase: "parent",
+        });
+        assertPosixParentCurrent(current);
+        for (let index = 0; index < segments.length; index += 1) {
+            const segment = segments[index];
+            const childPath = path.join(currentPath, segment);
+            let childFd;
+            let createdByMkdir = false;
+            let createReceipt;
+            try {
+                childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
+            }
+            catch (openError) {
+                if (!isNotFoundPathError(openError)) {
+                    throw normalizePolicyParentOpenError(openError, params);
+                }
+                const targetPath = retainedTargetPath ?? prospectiveTargetPath(currentPath, segmentRoute, index, params.basename);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: childPath,
+                    phase: "parent-create",
+                });
+                createReceipt = params.mutationAdmission?.tryAuthorizeAtParent?.(request, current.observation);
+                if (!createReceipt) {
+                    createReceipt = await authorizePinnedMutation(params, request);
+                    assertPosixParentCurrent(current);
+                }
+                params.assertBeforeMutation?.();
+                // Do not carry pathname freshness across the live authority callback.
+                assertPosixParentCurrent(current);
+                createdByMkdir = mkdirPolicyChild(binding, currentFd, segment, 0o777);
+                try {
+                    childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
+                }
+                catch (createdOpenError) {
+                    throw normalizePolicyParentOpenError(createdOpenError, params);
+                }
+            }
+            let child;
+            try {
+                const acceleratedChild = retainedTargetPath
+                    ? tryDescribePolicyPosixParent(childFd, childPath)
+                    : undefined;
+                if (acceleratedChild) {
+                    child = acceleratedChild;
+                }
+                else {
+                    retainedTargetPath = undefined;
+                    child = await describePosixParent(childFd, childPath);
+                }
+                if (!sameAbsolutePath(child.parentPath, childPath))
+                    retainedTargetPath = undefined;
+                let childAuthorization;
+                if (createdByMkdir && createReceipt && params.mutationAdmission?.advanceCreatedDirectory) {
+                    let evidence;
+                    try {
+                        const parent = current.policyDirectory
+                            ? refreshPolicyStagedDirectoryObservation(current.policyDirectory)
+                            : checkedMutationDirectory(currentPath, current.directory.realPath, assertStagedDirectoryCurrent(current.directory));
+                        evidence = Object.freeze({
+                            admission: createReceipt,
+                            parent,
+                            child: child.observation,
+                        });
+                    }
+                    catch {
+                        // Leave failed evidence to the full ordered admission below.
+                    }
+                    if (evidence) {
+                        childAuthorization = params.mutationAdmission.advanceCreatedDirectory(evidence);
+                    }
+                }
+                const targetPath = retainedTargetPath ?? prospectiveTargetPath(child.parentPath, segmentRoute, index + 1, params.basename);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                childAuthorization ??= params.mutationAdmission?.tryAuthorizeAtParent?.(request, child.observation);
+                if (!childAuthorization) {
+                    await authorizePinnedMutation(params, request);
+                    assertPosixParentCurrent(child);
+                }
+            }
+            catch (error) {
+                fsSync.closeSync(childFd);
+                throw error;
+            }
+            const previousOwnedFd = currentOwnedFd;
+            currentOwnedFd = child.parentFd;
+            currentFd = child.parentFd;
+            currentPath = child.parentPath;
+            current = child;
+            if (previousOwnedFd !== undefined)
+                fsSync.closeSync(previousOwnedFd);
+            if (index === segments.length - 1) {
+                currentOwnedFd = undefined;
+                return child;
+            }
+        }
+        // Empty relative parents are handled by the complete-parent fast path.
+        throw new FsSafeError("path-mismatch", "native write parent admission did not complete");
+    }
+    finally {
+        if (currentOwnedFd !== undefined)
+            fsSync.closeSync(currentOwnedFd);
+    }
+}
 export async function runPinnedWriteNative(binding, params) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
@@ -68,7 +330,12 @@ export async function runPinnedWriteNative(binding, params) {
             assertNativeStaging(binding);
         }
         const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
-        const root = await fs.open(params.rootPath, directoryFlags);
+        const rootAdmission = await openNativeRootAdmission(binding, {
+            rootPath: params.rootPath,
+            rootIdentity: params.rootIdentity,
+            operation: "native write",
+        });
+        const root = rootAdmission.root;
         const posixRoot = __addDisposableResource(env_1, windows ? undefined : root, true);
         let parentFd;
         let windowsOwnsDirectories = false;
@@ -82,44 +349,37 @@ export async function runPinnedWriteNative(binding, params) {
             },
         }, false);
         try {
-            const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
-                ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
-            let rootMatches;
-            if (exactRoot) {
-                inspectFileIdentitySync(() => fsSync.fstatSync(root.fd, { bigint: true }), exactRoot);
-                rootMatches = true;
-            }
-            else if (windows) {
-                const identity = binding.fstatIdentity(root.fd);
-                rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
+            let parentPath;
+            let directory;
+            let parentPathStat;
+            let policyParentAdmitted = false;
+            if (!windows && params.mutationAdmission) {
+                const admitted = await capturePolicyAwarePosixParent(binding, params, root.fd, directoryFlags);
+                parentFd = admitted.parentFd;
+                parentPath = admitted.parentPath;
+                directory = admitted.directory;
+                parentPathStat = admitted.parentPathStat;
+                policyParentAdmitted = true;
             }
             else {
-                const identity = fsSync.fstatSync(root.fd, { bigint: true });
-                rootMatches = !params.rootIdentity || exactIdentityMatches(params.rootIdentity, identity);
-            }
-            if (!rootMatches) {
-                throw new FsSafeError("path-mismatch", "root path changed during native write");
-            }
-            if (params.mkdir) {
-                params.assertBeforeMutation?.();
-                binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
-            }
-            parentFd = binding.openBeneath(root.fd, params.relativeParentPath, directoryFlags).fd;
-            const parentPath = realpathSync.native(params.relativeParentPath
-                ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
-                : params.rootPath);
-            const directory = windows ? undefined : describeStagedDirectory(parentFd, parentPath);
-            const parentPathStat = exactRoot
-                ? await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })))
-                : fsSync.lstatSync(parentPath);
-            if (windows && !exactRoot) {
-                const parentIdentity = binding.fstatIdentity(parentFd);
-                if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
-                    throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+                if (params.mkdir) {
+                    params.assertBeforeMutation?.();
+                    binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
                 }
+                const admitted = await openNativeParentAdmission(binding, rootAdmission, params.relativeParentPath);
+                parentFd = admitted.fd;
+                parentPath = admitted.guard.realPath;
+                directory = admitted.stagedDirectory;
+                parentPathStat = admitted.guard.stat;
             }
-            else if (!windows && (parentPathStat.isSymbolicLink() || !exactIdentityMatches(parentPathStat, directory.identity))) {
-                throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+            if (!policyParentAdmitted && params.mutationAdmission) {
+                const targetPath = path.join(parentPath, params.basename);
+                await authorizePinnedMutation(params, {
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })));
             }
             const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
             if (params.overwrite === false) {
@@ -145,7 +405,16 @@ export async function runPinnedWriteNative(binding, params) {
         finally {
             if (windows && !windowsOwnsDirectories) {
                 if (parentFd !== undefined) {
-                    fsSync.closeSync(parentFd);
+                    // Match the Windows leaf cleanup contract: an admission or identity
+                    // failure remains primary, while every owned directory is still given
+                    // a close attempt. In particular, a parent close failure must not skip
+                    // the root FileHandle close.
+                    try {
+                        fsSync.closeSync(parentFd);
+                    }
+                    catch {
+                        // Best effort while propagating the operation failure.
+                    }
                 }
                 await root.close().catch(() => undefined);
             }

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAyDF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAiDrC"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAyDF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA2DrC"}

package/dist/output.js

@@ -7,6 +7,7 @@ import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./fil
 import { isPathInside } from "./path.js";
 import { root } from "./root.js";
 import { tempFile } from "./temp-target.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const NON_PORTABLE_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
 function tempFileNameForTarget(targetPath, fallbackFileName) {
     const fallback = sanitizeUntrustedFileName(fallbackFileName ?? "output.bin", "output.bin");
@@ -51,8 +52,12 @@ function assertFileTargetPath(targetPath) {
 }
 export async function writeExternalFileWithinRoot(options) {
     const maxBytes = normalizeMaxBytes(options.maxBytes);
-    const targetRoot = await root(options.rootDir);
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "output root uses a Windows filesystem namespace alias");
     const requestedTargetPath = options.path;
+    assertNoWindowsPathAlias(path.dirname(requestedTargetPath), "filesystem", "output target parent uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
+    const targetRoot = await root(rootDir);
     if (requestedTargetPath.length === 0) {
         throw new FsSafeError("invalid-path", "target path is required");
     }
@@ -64,7 +69,9 @@ export async function writeExternalFileWithinRoot(options) {
     });
     assertFileTargetPath(rawTargetPath);
     const targetPath = sanitizedTargetPath(rawTargetPath, options.fallbackFileName);
+    assertNoWindowsPathAlias(targetPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = await targetRoot.resolve(targetPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     if (options.staging === "sibling") {
         const parentPath = path.dirname(targetPath);
         if (parentPath !== ".") {
@@ -74,7 +81,7 @@ export async function writeExternalFileWithinRoot(options) {
         const result = await writeExternalFileViaSibling({
             finalPath: siblingFinalPath,
             write: options.write,
-            producerIsolation: options.producerIsolation,
+            producerIsolation,
             fallbackFileName: options.fallbackFileName,
             maxBytes,
             mode: options.mode,
@@ -99,7 +106,7 @@ export async function writeExternalFileWithinRoot(options) {
         await staged.cleanup();
     }
 }
-function buildSiblingTempPath(targetPath, fallbackFileName) {
+function buildSiblingTempName(targetPath, fallbackFileName) {
     const prefix = `.fs-safe-output-${process.pid}-${randomUUID()}-`;
     const suffix = ".part";
     const safeTail = fitFileNameToPortableComponent({
@@ -107,12 +114,15 @@ function buildSiblingTempPath(targetPath, fallbackFileName) {
         fileName: tempFileNameForTarget(targetPath, fallbackFileName),
         suffix,
     });
-    return path.join(path.dirname(targetPath), `${prefix}${safeTail}${suffix}`);
+    return `${prefix}${safeTail}${suffix}`;
 }
 async function writeExternalFileViaSibling(params) {
+    assertNoWindowsPathAlias(params.finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = path.resolve(params.finalPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const { result } = await writeCallbackSibling({
-        tempPath: buildSiblingTempPath(finalPath, params.fallbackFileName),
+        tempDir: path.dirname(finalPath),
+        tempName: buildSiblingTempName(finalPath, params.fallbackFileName),
         write: params.write,
         producerIsolation: params.producerIsolation,
         resolveFinalPath: () => finalPath,

package/dist/overwrite-file-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overwrite-file-handle.d.ts","sourceRoot":"","sources":["../src/overwrite-file-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,4FAA4F;AAC5F,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAoCf"}
+{"version":3,"file":"overwrite-file-handle.d.ts","sourceRoot":"","sources":["../src/overwrite-file-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,4FAA4F;AAC5F,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/overwrite-file-handle.js

@@ -4,6 +4,10 @@ import { readFileWindowFully } from "./positional-read.js";
 import { writeAllToFile } from "./write-file-handle.js";
 /** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
 export async function overwriteFileHandle(handle, data, options = {}) {
+    // Snapshot caller-owned admission before the first await. Preserve the
+    // former method-call receiver while preventing a later getter mutation from
+    // replacing authority after rollback preparation.
+    const beforeWrite = options.beforeWrite;
     const payload = data.subarray(0, data.byteLength);
     const payloadBytes = payload.byteLength;
     const stat = await handle.stat();
@@ -19,7 +23,7 @@ export async function overwriteFileHandle(handle, data, options = {}) {
     if (await readFileWindowFully(handle, originalPrefix, 0) !== prefixBytes) {
         throw new FsSafeError("read-failed", "file ended before overwrite rollback preparation completed");
     }
-    assertSynchronousCallbackResult(options.beforeWrite?.(), "beforeWrite");
+    assertSynchronousCallbackResult(beforeWrite === undefined ? undefined : Reflect.apply(beforeWrite, options, []), "beforeWrite");
     let prefixStarted = false;
     try {
         // Leave existing bytes intact until any additional storage has been written.

package/dist/owner-dacl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner-dacl.d.ts","sourceRoot":"","sources":["../src/owner-dacl.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,yBAAyB,EAAE,CAAC;CACnC,GACD;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B,CAAC;AAEN,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CA6BvE"}
+{"version":3,"file":"owner-dacl.d.ts","sourceRoot":"","sources":["../src/owner-dacl.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,yBAAyB,EAAE,CAAC;CACnC,GACD;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B,CAAC;AAEN,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAmCvE"}

package/dist/owner-dacl.js

@@ -1,9 +1,11 @@
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function readOwnerAndDacl(targetPath) {
     if (process.platform !== "win32") {
         return { status: "unsupported-platform", platform: process.platform };
     }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
     const native = getNativeBinding();
     if (!native) {
         throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require the matching optional native platform package; " +

package/dist/path-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-policy.d.ts","sourceRoot":"","sources":["../src/path-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB"}
+{"version":3,"file":"path-policy.d.ts","sourceRoot":"","sources":["../src/path-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAKxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB"}

package/dist/path-policy.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
 import { isNotFoundPathError } from "./path.js";
 import { shortPath } from "./error-detail.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
 export async function assertNoPathAliasEscape(params) {
     const resolved = await resolveRootPath({
@@ -25,9 +26,13 @@ export async function assertNoHardlinkedFinalPath(params) {
     if (params.allowFinalHardlinkForUnlink) {
         return;
     }
+    const filePath = params.filePath;
+    const root = params.root;
+    const boundaryLabel = params.boundaryLabel;
+    assertNoWindowsPathAlias(filePath);
     let stat;
     try {
-        stat = fs.statSync(params.filePath);
+        stat = fs.statSync(filePath);
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
@@ -39,6 +44,6 @@ export async function assertNoHardlinkedFinalPath(params) {
         return;
     }
     if (stat.nlink > 1) {
-        throw new Error(`Hardlinked path is not allowed under ${params.boundaryLabel} (${shortPath(params.root)}): ${shortPath(params.filePath)}`);
+        throw new Error(`Hardlinked path is not allowed under ${boundaryLabel} (${shortPath(root)}): ${shortPath(filePath)}`);
     }
 }

package/dist/path-prefix.d.ts

@@ -0,0 +1,7 @@
+export type ResolvedPathPrefix = {
+    readonly absolutePath: string;
+    readonly existingPath: string;
+    readonly unresolvedSegments: readonly string[];
+};
+export declare function resolvePathPrefixSync(input: string): ResolvedPathPrefix;
+//# sourceMappingURL=path-prefix.d.ts.map

package/dist/path-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-prefix.d.ts","sourceRoot":"","sources":["../src/path-prefix.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD,CAAC;AAkBF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAsDvE"}

package/dist/path-prefix.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
+import { assertNoNulPathInput, hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { absolutePathWithRawSegments } from "./root-path-existing.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rawRoot(absolutePath) {
+    if (path.sep === "\\" && /^\\\\[?.]\\UNC\\/i.test(absolutePath)) {
+        // Node parses only the namespace prefix as the root of an extended UNC path.
+        const shareRoot = path.parse(`\\\\${absolutePath.slice(8)}`).root;
+        return absolutePath.slice(0, shareRoot.length + 6);
+    }
+    return path.parse(absolutePath).root;
+}
+function resolutionError(code, absolutePath) {
+    const detail = code === "ELOOP" ? "too many symbolic links" : "not a directory";
+    return Object.assign(new Error(`${code}: ${detail}, resolvePathPrefix ${formatErrorDetail(absolutePath)}`), {
+        code, syscall: "resolvePathPrefix", path: absolutePath,
+    });
+}
+export function resolvePathPrefixSync(input) {
+    assertNoNulPathInput(input);
+    const absolutePath = absolutePathWithRawSegments(input);
+    let resolved = rawRoot(absolutePath);
+    const remaining = absolutePath.slice(resolved.length).split(path.sep);
+    const visitedStates = new Set();
+    let symlinkHops = 0;
+    while (remaining.length > 0) {
+        const segment = remaining.shift();
+        if (segment === "")
+            continue;
+        if (segment === "." || segment === "..") {
+            const atRoot = resolved === rawRoot(resolved);
+            const lookup = segment === ".." && atRoot ? "." : segment;
+            // lstat(dir) does not test search permission, and realpath may erase dots.
+            const operationBase = pathForWindowsFilesystem(resolved);
+            fs.lstatSync(`${operationBase}${operationBase.endsWith(path.sep) ? "" : path.sep}${lookup}`, { bigint: true });
+            if (segment === ".." && !atRoot)
+                resolved = path.dirname(resolved);
+            continue;
+        }
+        const candidate = path.join(resolved, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(candidate, { bigint: true });
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                throw error;
+            return {
+                absolutePath,
+                existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)),
+                unresolvedSegments: [segment, ...remaining],
+            };
+        }
+        if (!stat.isSymbolicLink()) {
+            if (!stat.isDirectory() && remaining.length > 0)
+                throw resolutionError("ENOTDIR", absolutePath);
+            resolved = candidate;
+            continue;
+        }
+        const state = JSON.stringify([String(stat.dev), String(stat.ino), candidate, remaining]);
+        if (symlinkHops >= 64 || visitedStates.has(state))
+            throw resolutionError("ELOOP", absolutePath);
+        visitedStates.add(state);
+        symlinkHops++;
+        const target = fs.readlinkSync(candidate);
+        const rawTarget = path.sep === "\\" ? target.replaceAll("/", "\\") : target;
+        if (path.isAbsolute(rawTarget)) {
+            const targetRoot = rawRoot(rawTarget);
+            // A rooted Windows link target uses the link's drive/share, not cwd's.
+            resolved = path.sep === "\\" && targetRoot === "\\" ? rawRoot(resolved) : targetRoot;
+            remaining.unshift(...rawTarget.slice(targetRoot.length).split(path.sep));
+        }
+        else {
+            // A target's parent traversal applies after resolving its preceding links.
+            remaining.unshift(...rawTarget.split(path.sep));
+        }
+    }
+    return { absolutePath, existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)), unresolvedSegments: [] };
+}