@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/realpath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realpath.d.ts","sourceRoot":"","sources":["../src/realpath.ts"],"names":[],"mappings":"AA0CA,eAAO,MAAM,YAAY,WAAyB,MAAM;oBACtC,MAAM;CACtB,CAAC"}

package/dist/realpath.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import { platform } from "node:os";
+import { getSystemErrorName } from "node:util";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+const runtimePlatform = process.versions.bun ? platform() : undefined;
+const bunPosix = runtimePlatform === "darwin" || runtimePlatform === "linux" ? runtimePlatform : undefined;
+function resolve(input, native) {
+    if (bunPosix) {
+        // Bun 1.4.2 normalizes native path components and opens the leaf for reads.
+        // The Rust OS resolver preserves permissions, locks and physical spelling.
+        // Reuse our N-API addon so this also works with JIT disabled; Bun's FFI
+        // bridge requires JIT and would duplicate native loading and memory handling.
+        // Remove this routing once the Bun baseline includes oven-sh/bun#42374.
+        if (input.includes("\0")) {
+            throw Object.assign(new TypeError("realpath input must not contain null bytes"), {
+                code: "ERR_INVALID_ARG_VALUE",
+            });
+        }
+        const binding = getNativeBinding();
+        if (binding?.canonicalizePath) {
+            // Ordinary resolution normalizes both the input and each expanded symlink.
+            const result = binding.canonicalizePath(input, !native);
+            if (result.path !== undefined)
+                return result.path;
+            const errno = -(result.errno);
+            const code = getSystemErrorName(errno);
+            throw Object.assign(new Error(`${code}: realpath '${input}'`), {
+                code, errno, syscall: "realpath", path: input,
+            });
+        }
+        if (getFsSafeNativeConfig().mode === "require") {
+            throw new FsSafeError("helper-unavailable", "native fs-safe canonicalization is unavailable");
+        }
+        // The workaround belongs to the same optional addon, so "off" disables it
+        // too. With off or a missing addon in auto, Bun's upstream limits still apply.
+    }
+    return native ? fs.realpathSync.native(input) : fs.realpathSync(input);
+}
+export const realpathSync = Object.assign((input) => resolve(input, false), {
+    native: (input) => resolve(input, true),
+});

package/dist/recursive-mkdir-path.d.ts

@@ -0,0 +1,3 @@
+/** Bun's Windows recursive mkdir cannot inspect existing relative dot components. */
+export declare function recursiveMkdirPath(directory: string): string;
+//# sourceMappingURL=recursive-mkdir-path.d.ts.map

package/dist/recursive-mkdir-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recursive-mkdir-path.d.ts","sourceRoot":"","sources":["../src/recursive-mkdir-path.ts"],"names":[],"mappings":"AAKA,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5D"}

package/dist/recursive-mkdir-path.js

@@ -0,0 +1,8 @@
+import { platform } from "node:os";
+import { absolutePathWithRawSegments } from "./root-path-existing.js";
+const needsAbsolutePath = Boolean(process.versions.bun) && platform() === "win32";
+/** Bun's Windows recursive mkdir cannot inspect existing relative dot components. */
+export function recursiveMkdirPath(directory) {
+    // Preserve junction/parent traversal; path.resolve would erase those components.
+    return needsAbsolutePath ? absolutePathWithRawSegments(directory) : directory;
+}

package/dist/replace-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-directory.d.ts","sourceRoot":"","sources":["../src/replace-directory.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAKf"}
+{"version":3,"file":"replace-directory.d.ts","sourceRoot":"","sources":["../src/replace-directory.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/replace-directory.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { guardedRename, guardedRm } from "./guarded-mutation.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { serializePathWrite } from "./write-queue.js";
 export async function replaceDirectoryAtomic(options) {
@@ -16,7 +17,7 @@ async function replaceDirectoryAtomicUnserialized(options, targetDir) {
     const backupPrefix = assertSafePathPrefix(options.backupPrefix ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
     const backupDir = path.join(parentDir, `${backupPrefix}${process.pid}-${randomUUID()}`);
     let backupCreated = false;
-    await fs.mkdir(parentDir, { recursive: true });
+    await fs.mkdir(recursiveMkdirPath(parentDir), { recursive: true });
     try {
         await guardedRename({ from: targetDir, to: backupDir });
         backupCreated = true;

package/dist/replace-file-copy-fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAO/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AA0FF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AAoID,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAkEP"}
+{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAyFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AA+HD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAkEP"}

package/dist/replace-file-copy-fallback.js

@@ -1,5 +1,6 @@
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
+import { readBoundedAsync, readBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { readOwnedCopySource, readOwnedCopySourceSync } from "./replace-file-copy-source.js";
@@ -9,7 +10,6 @@ const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
 const OPEN_READ_WRITE_FLAGS = syncFs.constants.O_RDWR | NOFOLLOW;
 const OPEN_WRITE_EXCLUSIVE_FLAGS = syncFs.constants.O_WRONLY | syncFs.constants.O_CREAT | syncFs.constants.O_EXCL | NOFOLLOW;
-const READ_CHUNK_BYTES = 64 * 1024;
 function notFound(error) {
     return error.code === "ENOENT";
 }
@@ -136,37 +136,27 @@ export function assertDestinationHardlinkPolicySync(fsModule, dest, policy) {
         fsModule.closeSync(fd);
     }
 }
-async function readBounded(handle, maxBytes) {
-    const chunks = [];
+function restoreReadOptions(stat, maxBytes) {
+    return {
+        initialSize: Number.isSafeInteger(stat.size) && stat.size >= 0 ? stat.size : undefined,
+        createLimitError: () => new FsSafeError("too-large", `Atomic replace restore snapshot exceeds maxRestoreBytes (${maxBytes})`),
+    };
+}
+async function readRestoreSnapshot(handle, maxBytes, stat) {
     let position = 0;
-    while (position <= maxBytes) {
-        const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - position + 1));
-        const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
-        if (bytesRead === 0)
-            break;
+    return await readBoundedAsync(maxBytes, async (buffer, length) => {
+        const { bytesRead } = await handle.read(buffer, 0, length, position);
         position += bytesRead;
-        if (position > maxBytes) {
-            throw new FsSafeError("too-large", `Atomic replace restore snapshot exceeds maxRestoreBytes (${maxBytes})`);
-        }
-        chunks.push(buffer.subarray(0, bytesRead));
-    }
-    return Buffer.concat(chunks, position);
+        return bytesRead;
+    }, restoreReadOptions(stat, maxBytes));
 }
-function readBoundedSync(fsModule, fd, maxBytes) {
-    const chunks = [];
+function readRestoreSnapshotSync(fsModule, fd, maxBytes, stat) {
     let position = 0;
-    while (position <= maxBytes) {
-        const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - position + 1));
-        const bytesRead = fsModule.readSync(fd, buffer, 0, buffer.length, position);
-        if (bytesRead === 0)
-            break;
+    return readBoundedSync(maxBytes, (buffer, length) => {
+        const bytesRead = fsModule.readSync(fd, buffer, 0, length, position);
         position += bytesRead;
-        if (position > maxBytes) {
-            throw new FsSafeError("too-large", `Atomic replace restore snapshot exceeds maxRestoreBytes (${maxBytes})`);
-        }
-        chunks.push(buffer.subarray(0, bytesRead));
-    }
-    return Buffer.concat(chunks, position);
+        return bytesRead;
+    }, restoreReadOptions(stat, maxBytes));
 }
 async function writeAll(handle, data) {
     await handle.truncate(0);
@@ -201,8 +191,9 @@ function restoreFailure(writeError, cleanup, restoreError) {
         : `Atomic copy fallback failed and original restoration failed: ${primary.message}`, { cause, details });
 }
 async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestoreBytes, replacementMode) {
-    const originalMode = (fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat()).mode;
-    const original = await readBounded(handle, maxRestoreBytes);
+    const originalStat = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
+    const originalMode = originalStat.mode;
+    const original = await readRestoreSnapshot(handle, maxRestoreBytes, originalStat);
     try {
         await writeAll(handle, replacement);
         await handle.chmod(replacementMode);
@@ -224,8 +215,9 @@ async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestor
     }
 }
 function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes, replacementMode, fchmodSync) {
-    const originalMode = fsModule.fstatSync(fd).mode;
-    const original = readBoundedSync(fsModule, fd, maxRestoreBytes);
+    const originalStat = fsModule.fstatSync(fd);
+    const originalMode = originalStat.mode;
+    const original = readRestoreSnapshotSync(fsModule, fd, maxRestoreBytes, originalStat);
     try {
         writeAllSync(fsModule, fd, replacement);
         fchmodSync?.(fd, replacementMode);

package/dist/replace-file-copy-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-copy-source.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-source.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAOnD,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AACvF,KAAK,oBAAoB,GAAG,IAAI,CAC9B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAClE,CAAC;AA0DF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA8BxC"}
+{"version":3,"file":"replace-file-copy-source.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-source.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAQnD,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AACvF,KAAK,oBAAoB,GAAG,IAAI,CAC9B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAClE,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA8BxC"}

package/dist/replace-file-copy-source.js

@@ -1,11 +1,11 @@
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
+import { readBoundedSync } from "./bounded-read.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
-const READ_CHUNK_BYTES = 64 * 1024;
 function assertSourcePreview(source, src) {
     if (source.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback from non-file source: ${src}`);
@@ -44,18 +44,13 @@ function openSourceSync(fsModule, src) {
         throw error;
     }
 }
-function readAllSync(fsModule, fd) {
-    const chunks = [];
+function readAllSync(fsModule, fd, size) {
     let position = 0;
-    while (true) {
-        const buffer = Buffer.allocUnsafe(READ_CHUNK_BYTES);
-        const bytesRead = fsModule.readSync(fd, buffer, 0, buffer.length, position);
-        if (bytesRead === 0)
-            break;
+    return readBoundedSync(Infinity, (buffer, length) => {
+        const bytesRead = fsModule.readSync(fd, buffer, 0, length, position);
         position += bytesRead;
-        chunks.push(buffer.subarray(0, bytesRead));
-    }
-    return Buffer.concat(chunks, position);
+        return bytesRead;
+    }, { initialSize: Number.isSafeInteger(size) && size >= 0 ? size : undefined });
 }
 export async function readOwnedCopySource(params) {
     assertSourcePreview(params.fsModule === fs
@@ -99,7 +94,7 @@ export function readOwnedCopySourceSync(params) {
         if (opened.nlink !== 1) {
             throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${params.src}`);
         }
-        return { replacement: readAllSync(params.fsModule, fd), mode: opened.mode };
+        return { replacement: readAllSync(params.fsModule, fd, opened.size), mode: opened.mode };
     }
     finally {
         try {

package/dist/replace-file-mode.d.ts

@@ -0,0 +1,3 @@
+import type { Stats } from "node:fs";
+export declare function inheritedRegularFileMode(stat: Stats): number;
+//# sourceMappingURL=replace-file-mode.d.ts.map

package/dist/replace-file-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-mode.d.ts","sourceRoot":"","sources":["../src/replace-file-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGrC,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAQ5D"}

package/dist/replace-file-mode.js

@@ -0,0 +1,10 @@
+import { FsSafeError } from "./errors.js";
+export function inheritedRegularFileMode(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "atomic replace destination must not be a symbolic link");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "atomic replace destination must be a regular file");
+    }
+    return stat.mode & 0o777;
+}

package/dist/replace-file-temp-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAO9F,KAAK,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;AACzE,KAAK,mBAAmB,GAAG,IAAI,CAC7B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CACrF,CAAC;AAgEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB;AA+BD,qBAAa,oBAAoB;;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAG/D;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAEK,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Cf;IAED,WAAW,IAAI,IAAI,CAGlB;IAEK,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,oBAAoB,CAAC;QAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB;CACF;AAED,qBAAa,mBAAmB;;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAGvD;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAED,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,SAAgB,GAAG,IAAI,CAkB3E;IAED,eAAe,CACb,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAgDN;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,IAAI,CAgCP;CACF"}
+{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAO9F,KAAK,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;AACzE,KAAK,mBAAmB,GAAG,IAAI,CAC7B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CACrF,CAAC;AAgEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB;AA+BD,qBAAa,oBAAoB;;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAG/D;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAEK,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Cf;IAED,WAAW,IAAI,IAAI,CAGlB;IAEK,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,oBAAoB,CAAC;QAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB;CACF;AAED,qBAAa,mBAAmB;;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAGvD;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAED,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,SAAgB,GAAG,IAAI,CAkB3E;IAED,eAAe,CACb,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAkDN;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,IAAI,CAkCP;CACF"}

package/dist/replace-file-temp-owner.js

@@ -319,7 +319,9 @@ export class SyncAtomicTempOwner {
             if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            fsModule.closeSync(this.#fd);
+            const previousFd = this.#fd;
+            this.#fd = undefined;
+            fsModule.closeSync(previousFd);
             this.#fd = publishedFd;
             this.#identity = identity;
             publishedFd = undefined;
@@ -359,8 +361,10 @@ export class SyncAtomicTempOwner {
         if (cleanupComplete)
             this.#unregister();
         if (this.#fd !== undefined) {
+            const fd = this.#fd;
+            this.#fd = undefined;
             try {
-                params.fsModule.closeSync(this.#fd);
+                params.fsModule.closeSync(fd);
             }
             catch (closeError) {
                 deferredError = deferredError

package/dist/replace-file.d.ts

@@ -19,6 +19,7 @@ type ReplaceFileAtomicBaseOptions = {
     content: string | Uint8Array;
     dirMode?: number;
     mode?: number;
+    /** Inherit only rwx bits from an existing non-symlink regular file. */
     preserveExistingMode?: boolean;
     tempPrefix?: string;
     renameMaxRetries?: number;

package/dist/replace-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AACA,OAAO,MAAwC,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGlC,OAAO,EAKL,KAAK,+BAA+B,EACpC,KAAK,sCAAsC,EAC3C,KAAK,oCAAoC,EACzC,KAAK,oCAAoC,EAC1C,MAAM,iCAAiC,CAAC;AAWzC,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,iCAAiC,CAAC;AAMzC,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,IAAI,CACZ,OAAO,EAAE,EACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CACV,GAAG;QACF,uEAAuE;QACvE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,OAAO,MAAM,EACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,WAAW,GACX,eAAe,GACf,UAAU,GACV,WAAW,CACd,GAAG;IACF,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,OAAO,MAAM,CAAC,UAAU,CAAC;CACvC,CAAC;AAEF,YAAY,EACV,oBAAoB,EACpB,+BAA+B,EAC/B,sCAAsC,EACtC,oCAAoC,EACpC,oCAAoC,GACrC,CAAC;AAEF,KAAK,4BAA4B,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,mBAAmB,CAAC,EAAE,oCAAoC,CAAC;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,+FAA+F;IAC/F,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAAG;IACpE,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,4BAA4B,GAAG;IACxE,UAAU,CAAC,EAAE,+BAA+B,CAAC;IAC7C,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACzE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAAC;CACpC,CAAC;AAkKF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAGD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,wBAAwB,EACjC,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,uBAAuB,CAAC,CAkBlC;AAgFD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAgBzB"}

package/dist/replace-file.js

@@ -2,8 +2,10 @@ import { randomUUID } from "node:crypto";
 import syncFs, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { assertDestinationHardlinkPolicy, assertDestinationHardlinkPolicySync, copyFallbackReplace, copyFallbackReplaceSync, } from "./replace-file-copy-fallback.js";
 import { applyDirectoryMode, applyDirectoryModeSync, syncDirectoryBestEffort, syncDirectoryBestEffortSync, writeTempFile, writeTempFileSync, } from "./replace-file-descriptor.js";
+import { inheritedRegularFileMode } from "./replace-file-mode.js";
 import { atomicExpectedContentHash, validateRenameIdentity, withAtomicRenameIdentityLock, withAtomicRenameIdentityLockSync, } from "./replace-file-rename-policy.js";
 import { AsyncAtomicTempOwner, SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
@@ -107,7 +109,7 @@ async function resolveMode(options) {
     const fsModule = options.fileSystem?.promises ?? fs;
     let stat;
     try {
-        stat = fsModule === fs ? syncFs.statSync(options.filePath) : await fsModule.stat(options.filePath);
+        stat = fsModule === fs ? syncFs.lstatSync(options.filePath) : await fsModule.lstat(options.filePath);
     }
     catch (error) {
         if (error.code === "ENOENT") {
@@ -115,7 +117,7 @@ async function resolveMode(options) {
         }
         throw error;
     }
-    return stat ? stat.mode : defaultMode;
+    return stat ? inheritedRegularFileMode(stat) : defaultMode;
 }
 function resolveModeSync(options) {
     const defaultMode = options.mode ?? 0o600;
@@ -125,14 +127,14 @@ function resolveModeSync(options) {
     const fsModule = options.fileSystem ?? syncFs;
     let stat;
     try {
-        stat = fsModule.statSync(options.filePath);
+        stat = fsModule.lstatSync(options.filePath);
     }
     catch (error) {
         if (error.code !== "ENOENT") {
             throw error;
         }
     }
-    return stat ? stat.mode : defaultMode;
+    return stat ? inheritedRegularFileMode(stat) : defaultMode;
 }
 function missingFchmodSyncError() {
     return new TypeError("fileSystem.fchmodSync is required when mode, dirMode, or preserveExistingMode is specified");
@@ -150,7 +152,9 @@ export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
         if (options.renameIdentity !== "verify-content-with-lock") {
             return await replaceFileAtomicUnserialized(options, syncParent);
         }
-        await (options.fileSystem?.promises ?? fs).mkdir(path.dirname(filePath), {
+        const fsModule = options.fileSystem?.promises ?? fs;
+        const dir = path.dirname(filePath);
+        await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, {
             recursive: true,
             mode: options.dirMode ?? 0o700,
         });
@@ -168,7 +172,7 @@ async function replaceFileAtomicUnserialized(options, syncParent) {
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
     let originalError;
     try {
-        await fsModule.mkdir(dir, { recursive: true, mode: dirMode });
+        await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
         tempOwner.start();
         tempOwner.adopt(await writeTempFile({
@@ -243,7 +247,9 @@ export function replaceFileAtomicSync(options) {
     if (options.renameIdentity !== "verify-content-with-lock") {
         return replaceFileAtomicSyncUnserialized(options);
     }
-    (options.fileSystem ?? syncFs).mkdirSync(path.dirname(filePath), {
+    const fsModule = options.fileSystem ?? syncFs;
+    const dir = path.dirname(filePath);
+    fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, {
         recursive: true,
         mode: options.dirMode ?? 0o700,
     });
@@ -267,7 +273,7 @@ function replaceFileAtomicSyncUnserialized(options) {
     const tempOwner = new SyncAtomicTempOwner(tempPath);
     let originalError;
     try {
-        fsModule.mkdirSync(dir, { recursive: true, mode: dirMode });
+        fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
         tempOwner.start();
         tempOwner.adopt(writeTempFileSync({

package/dist/root-context.d.ts

@@ -22,6 +22,9 @@ export declare function resolvePathInRoot(root: RootContext, relativePath: strin
     allowFinalSymlink?: boolean;
     rejectUnsafeDeviceReads?: boolean;
     rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    resolveCanonical?: boolean;
+    rejectAmbiguousParents?: boolean;
 }): Promise<{
     rootReal: string;
     rootWithSep: string;

package/dist/root-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAID,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0B9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAehF;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhF;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0CtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAetF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBhF;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhF;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqDtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}

package/dist/root-context.js

@@ -4,11 +4,12 @@ import path from "node:path";
 import { inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
-import { expandHomePrefix } from "./home-dir.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
-import { outsideWorkspaceError } from "./root-errors.js";
+import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
 export function assertValidRootRelativePath(relativePath) {
     assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
@@ -20,30 +21,39 @@ export function assertValidRootDestinationPath(relativePath) {
     }
 }
 let cachedHomePath;
+const POSIX_PARENT_COMPONENT = /(?:^|\/)\.\.(?:\/|$)/;
+const WINDOWS_PARENT_COMPONENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export async function expandRelativePathWithHome(relativePath) {
+    const homeOnly = relativePath === "~";
+    const homePrefix = relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"));
+    if (!homeOnly && !homePrefix)
+        return relativePath;
     const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
     if (cachedHomePath?.raw !== rawHome) {
         let realHome = rawHome;
         try {
-            realHome = fs.realpathSync.native(rawHome);
+            realHome = realpathSync.native(rawHome);
         }
         catch {
             // If the home dir cannot be canonicalized, keep lexical expansion behavior.
         }
         cachedHomePath = { raw: rawHome, real: realHome };
     }
-    return expandHomePrefix(relativePath, { home: cachedHomePath.real });
+    return homeOnly ? cachedHomePath.real : `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
 }
 export async function resolveRootContext(rootDir) {
     assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
+    const lexicalRoot = path.resolve(rootDir);
     let rootReal;
     let rootIdentity;
     try {
-        rootReal = fs.realpathSync.native(rootDir);
-        const rootStat = fs.statSync(rootReal);
-        if (!rootStat.isDirectory()) {
-            throw new FsSafeError("invalid-path", "root dir is not a directory");
-        }
+        rootReal = realpathSync.native(rootDir);
+        const rootStat = await inspectFileIdentity(() => {
+            const stat = fs.statSync(rootReal, { bigint: true });
+            if (!stat.isDirectory())
+                throw new FsSafeError("invalid-path", "root dir is not a directory");
+            return stat;
+        });
         rootIdentity = { dev: rootStat.dev, ino: rootStat.ino };
     }
     catch (err) {
@@ -56,7 +66,7 @@ export async function resolveRootContext(rootDir) {
         throw err;
     }
     return {
-        rootDir: path.resolve(rootDir),
+        rootDir: lexicalRoot,
         rootIdentity,
         rootReal,
         rootWithSep: ensureTrailingSep(rootReal),
@@ -64,17 +74,22 @@ export async function resolveRootContext(rootDir) {
 }
 export function rootRelativeReadPath(root, filePath) {
     const absoluteInput = path.isAbsolute(filePath);
-    const candidatePath = absoluteInput
-        ? path.resolve(filePath)
-        : path.resolve(root.rootDir, filePath);
-    let relativeBase = root.rootDir;
-    if (absoluteInput &&
-        !isPathInside(root.rootDir, candidatePath) &&
-        isPathInside(root.rootReal, candidatePath)) {
-        // A Root created through an alias has two valid in-root absolute spellings.
-        relativeBase = root.rootReal;
+    if (!absoluteInput)
+        return filePath;
+    const raw = process.platform === "win32" ? filePath.replaceAll("/", path.sep) : filePath;
+    for (const base of [root.rootDir, root.rootReal]) {
+        const prefix = ensureTrailingSep(base);
+        const matches = process.platform === "win32"
+            ? raw.slice(0, prefix.length).toLowerCase() === prefix.toLowerCase()
+            : raw.startsWith(prefix);
+        if (matches) {
+            let start = prefix.length;
+            while (raw[start] === path.sep)
+                start += 1;
+            return raw.slice(start);
+        }
     }
-    return path.relative(relativeBase, candidatePath);
+    return raw;
 }
 export async function assertRootIdentityCurrent(root) {
     let current;
@@ -86,22 +101,20 @@ export async function assertRootIdentityCurrent(root) {
         current = fs.lstatSync(root.rootReal);
     }
     catch (error) {
-        throw new FsSafeError("path-mismatch", "root path changed during operation", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
     }
     if (current.isSymbolicLink() ||
         !current.isDirectory() ||
         !sameFileIdentity(current, root.rootIdentity)) {
-        throw new FsSafeError("path-mismatch", "root path changed during operation");
+        throw rootPathChangedError();
     }
 }
 export async function resolvePathInRoot(root, relativePath, options) {
     assertValidRootRelativePath(relativePath);
     await assertRootIdentityCurrent(root);
     const expanded = await expandRelativePathWithHome(relativePath);
-    const resolved = path.resolve(root.rootWithSep, expanded);
-    if (!isPathInside(root.rootWithSep, resolved)) {
+    let resolved = path.resolve(root.rootWithSep, expanded);
+    if (!options?.resolveCanonical && !isPathInside(root.rootWithSep, resolved)) {
         throw outsideWorkspaceError();
     }
     if (options?.rejectUnsafeDeviceReads === true) {
@@ -111,14 +124,26 @@ export async function resolvePathInRoot(root, relativePath, options) {
         ? expanded
         : `${root.rootWithSep}${expanded}`;
     try {
-        await resolveRootPath({
+        const resolution = {
             absolutePath: rawAbsolutePath,
             rootPath: root.rootReal,
             rootCanonicalPath: root.rootReal,
             boundaryLabel: "root",
             policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
             rejectSymlinks: options?.rejectSymlinks,
-        });
+            rejectFinalSymlink: options?.rejectFinalSymlink,
+        };
+        const checked = await resolveRootPath(resolution);
+        const parentComponent = process.platform === "win32" ? WINDOWS_PARENT_COMPONENT : POSIX_PARENT_COMPONENT;
+        if (options?.rejectAmbiguousParents && parentComponent.test(expanded) &&
+            path.relative(checked.canonicalPath, resolved) !== "") {
+            const normalized = await resolveRootPath({ ...resolution, absolutePath: resolved });
+            if (path.relative(checked.canonicalPath, normalized.canonicalPath) !== "") {
+                throw new FsSafeError("path-alias", "parent traversal resolves differently through a symlink");
+            }
+        }
+        if (options?.resolveCanonical)
+            resolved = checked.canonicalPath;
     }
     catch (error) {
         if (error instanceof FsSafeError && error.code === "symlink") {

package/dist/root-create-input.d.ts

@@ -0,0 +1,10 @@
+import type { PinnedWriteInput } from "./pinned-write.js";
+import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+export type RootWriteParams = RootWriteOptions & RootCreateStreamOptions & {
+    relativePath: string;
+    data: string | Buffer | AsyncIterable<Uint8Array>;
+};
+export declare function rethrowCreateInputError(error: unknown): never;
+export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
+export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
+//# sourceMappingURL=root-create-input.d.ts.map

package/dist/root-create-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-create-input.d.ts","sourceRoot":"","sources":["../src/root-create-input.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtG,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,uBAAuB,GAAG;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;CACnD,CAAC;AAQF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,iBAAiB,GAAG,uBAAuB,EACpD,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,GAAG,uBAAuB,CAe7C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAwCxE"}