@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/regular-file.js

@@ -11,6 +11,7 @@ import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertNoSymlinkParents, assertNoSymlinkParentsSync } from "./symlink-parents.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { isNonRegularWriteOpenError, isNonRegularWriteOpenErrorSync, resolveNonblockingWriteFlag, } from "./write-open-flags.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export function resolveRegularFileAppendFlags(constants = fsSync.constants) {
     const noFollow = constants.O_NOFOLLOW;
     return (constants.O_CREAT |
@@ -29,6 +30,7 @@ function translateBoundedReadOverflow(error, filePath, maxBytes) {
     throw error;
 }
 export async function statRegularFile(filePath) {
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
     let stat;
     try {
         stat = fsSync.lstatSync(filePath);
@@ -45,6 +47,7 @@ export async function statRegularFile(filePath) {
     return { missing: false, stat };
 }
 export function statRegularFileSync(filePath) {
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
     let stat;
     try {
         stat = fsSync.lstatSync(filePath);
@@ -62,22 +65,24 @@ export function statRegularFileSync(filePath) {
 }
 export async function readRegularFile(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
-    assertNoUnsafeDeviceReadPath(params.filePath);
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+    assertNoUnsafeDeviceReadPath(filePath);
     const before = await inspectFileIdentity(async () => {
-        const stat = fsSync.lstatSync(params.filePath, { bigint: true });
-        assertRegularReadStat(stat, params.filePath, true);
+        const stat = fsSync.lstatSync(filePath, { bigint: true });
+        assertRegularReadStat(stat, filePath, true);
         return stat;
-    }).catch((error) => throwReadPreviewError(error, params.filePath));
+    }).catch((error) => throwReadPreviewError(error, filePath));
     if (maxBytes !== undefined && before.size > maxBytes) {
-        throw regularFileTooLargeError(params.filePath, maxBytes);
+        throw regularFileTooLargeError(filePath, maxBytes);
     }
     let handle;
     try {
-        handle = await fs.open(params.filePath, resolveReadOpenFlags());
+        handle = await fs.open(filePath, resolveReadOpenFlags());
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
-            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+            throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
         }
         throw err;
     }
@@ -85,24 +90,24 @@ export async function readRegularFile(params) {
         const stat = fsSync.fstatSync(handle.fd);
         const identity = await inspectFileIdentity(async () => {
             const exact = fsSync.fstatSync(handle.fd, { bigint: true });
-            assertRegularReadStat(exact, params.filePath);
+            assertRegularReadStat(exact, filePath);
             return exact;
         }, before);
         try {
             await inspectFileIdentity(async () => {
-                const current = fsSync.lstatSync(params.filePath, { bigint: true });
-                assertRegularReadStat(current, params.filePath);
+                const current = fsSync.lstatSync(filePath, { bigint: true });
+                assertRegularReadStat(current, filePath);
                 return current;
             }, identity);
         }
         catch (err) {
             if (isNotFoundPathError(err)) {
-                throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+                throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
             }
             throw err;
         }
         if (maxBytes !== undefined && stat.size > maxBytes) {
-            throw regularFileTooLargeError(params.filePath, maxBytes);
+            throw regularFileTooLargeError(filePath, maxBytes);
         }
         // With a byte cap, avoid readFile(): a raced file growth would allocate
         // the oversized content before the post-read check could reject it.
@@ -115,7 +120,7 @@ export async function readRegularFile(params) {
         }
         catch (error) {
             if (maxBytes !== undefined) {
-                translateBoundedReadOverflow(error, params.filePath, maxBytes);
+                translateBoundedReadOverflow(error, filePath, maxBytes);
             }
             throw error;
         }
@@ -178,35 +183,37 @@ function readOpenedRegularFileSync(params) {
 }
 export function readRegularFileSync(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
-    assertNoUnsafeDeviceReadPath(params.filePath);
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+    assertNoUnsafeDeviceReadPath(filePath);
     let before;
     try {
         before = inspectFileIdentitySync(() => {
-            const stat = fsSync.lstatSync(params.filePath, { bigint: true });
-            assertRegularReadStat(stat, params.filePath, true);
+            const stat = fsSync.lstatSync(filePath, { bigint: true });
+            assertRegularReadStat(stat, filePath, true);
             return stat;
         });
     }
     catch (error) {
-        throwReadPreviewError(error, params.filePath);
+        throwReadPreviewError(error, filePath);
     }
     if (maxBytes !== undefined && before.size > maxBytes) {
-        throw regularFileTooLargeError(params.filePath, maxBytes);
+        throw regularFileTooLargeError(filePath, maxBytes);
     }
     let fd;
     try {
-        fd = fsSync.openSync(params.filePath, resolveReadOpenFlags());
+        fd = fsSync.openSync(filePath, resolveReadOpenFlags());
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+            throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
         }
         throw error;
     }
     try {
         return readOpenedRegularFileSync({
             fd,
-            filePath: params.filePath,
+            filePath,
             preOpenStat: before,
             maxBytes,
         });
@@ -231,8 +238,10 @@ function throwAppendIdentityError(error, filePath) {
     throw error;
 }
 export async function appendRegularFile(options) {
+    const filePath = options.filePath;
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
     if (options.rejectSymlinkParents === true) {
-        const resolvedDir = path.resolve(path.dirname(options.filePath));
+        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
         await assertNoSymlinkParents({
             rootDir: path.parse(resolvedDir).root,
             targetPath: resolvedDir,
@@ -245,12 +254,12 @@ export async function appendRegularFile(options) {
     let preOpenStat;
     try {
         preOpenStat = await inspectFileIdentity(async () => {
-            const stat = fsSync.lstatSync(options.filePath, { bigint: true });
+            const stat = fsSync.lstatSync(filePath, { bigint: true });
             if (stat.isSymbolicLink()) {
-                throw new Error(`Refusing to append through symlink: ${options.filePath}`);
+                throw new Error(`Refusing to append through symlink: ${filePath}`);
             }
             if (!stat.isFile()) {
-                throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+                throw new Error(`Refusing to append to non-file: ${filePath}`);
             }
             return stat;
         });
@@ -266,15 +275,15 @@ export async function appendRegularFile(options) {
         Number(preOpenStat?.size ?? 0n) + contentBytes > options.maxFileBytes) {
         return;
     }
-    await getFsSafeTestHooks()?.beforeRegularFileAppendOpen?.(options.filePath);
+    await getFsSafeTestHooks()?.beforeRegularFileAppendOpen?.(filePath);
     const flags = resolveRegularFileAppendFlags();
     let handle;
     try {
-        handle = await fs.open(options.filePath, flags, options.mode ?? 0o600);
+        handle = await fs.open(filePath, flags, options.mode ?? 0o600);
     }
     catch (error) {
-        if (await isNonRegularWriteOpenError(error, options.filePath, flags)) {
-            throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+        if (await isNonRegularWriteOpenError(error, filePath, flags)) {
+            throw new Error(`Refusing to append to non-file: ${filePath}`);
         }
         throw error;
     }
@@ -283,17 +292,17 @@ export async function appendRegularFile(options) {
         try {
             identity = await inspectFileIdentity(async () => {
                 const stat = fsSync.fstatSync(handle.fd, { bigint: true });
-                assertRegularAppendStat(stat, options.filePath);
+                assertRegularAppendStat(stat, filePath);
                 return stat;
             }, preOpenStat);
             await inspectFileIdentity(async () => {
-                const current = fsSync.lstatSync(options.filePath, { bigint: true });
-                assertRegularAppendStat(current, options.filePath);
+                const current = fsSync.lstatSync(filePath, { bigint: true });
+                assertRegularAppendStat(current, filePath);
                 return current;
             }, identity);
         }
         catch (error) {
-            throwAppendIdentityError(error, options.filePath);
+            throwAppendIdentityError(error, filePath);
         }
         if (options.maxFileBytes !== undefined &&
             Number(identity.size) + contentBytes > options.maxFileBytes) {
@@ -311,8 +320,10 @@ export async function appendRegularFile(options) {
     }
 }
 export function appendRegularFileSync(options) {
+    const filePath = options.filePath;
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
     if (options.rejectSymlinkParents === true) {
-        const resolvedDir = path.resolve(path.dirname(options.filePath));
+        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
         assertNoSymlinkParentsSync({
             rootDir: path.parse(resolvedDir).root,
             targetPath: resolvedDir,
@@ -325,12 +336,12 @@ export function appendRegularFileSync(options) {
     let preOpenStat;
     try {
         preOpenStat = inspectFileIdentitySync(() => {
-            const stat = fsSync.lstatSync(options.filePath, { bigint: true });
+            const stat = fsSync.lstatSync(filePath, { bigint: true });
             if (stat.isSymbolicLink()) {
-                throw new Error(`Refusing to append through symlink: ${options.filePath}`);
+                throw new Error(`Refusing to append through symlink: ${filePath}`);
             }
             if (!stat.isFile()) {
-                throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+                throw new Error(`Refusing to append to non-file: ${filePath}`);
             }
             return stat;
         });
@@ -346,15 +357,15 @@ export function appendRegularFileSync(options) {
         Number(preOpenStat?.size ?? 0n) + contentBuffer.byteLength > options.maxFileBytes) {
         return;
     }
-    getFsSafeTestHooks()?.beforeRegularFileAppendOpenSync?.(options.filePath);
+    getFsSafeTestHooks()?.beforeRegularFileAppendOpenSync?.(filePath);
     const flags = resolveRegularFileAppendFlags();
     let fd;
     try {
-        fd = fsSync.openSync(options.filePath, flags, options.mode ?? 0o600);
+        fd = fsSync.openSync(filePath, flags, options.mode ?? 0o600);
     }
     catch (error) {
-        if (isNonRegularWriteOpenErrorSync(error, options.filePath, flags)) {
-            throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+        if (isNonRegularWriteOpenErrorSync(error, filePath, flags)) {
+            throw new Error(`Refusing to append to non-file: ${filePath}`);
         }
         throw error;
     }
@@ -363,17 +374,17 @@ export function appendRegularFileSync(options) {
         try {
             identity = inspectFileIdentitySync(() => {
                 const stat = fsSync.fstatSync(fd, { bigint: true });
-                assertRegularAppendStat(stat, options.filePath);
+                assertRegularAppendStat(stat, filePath);
                 return stat;
             }, preOpenStat);
             inspectFileIdentitySync(() => {
-                const current = fsSync.lstatSync(options.filePath, { bigint: true });
-                assertRegularAppendStat(current, options.filePath);
+                const current = fsSync.lstatSync(filePath, { bigint: true });
+                assertRegularAppendStat(current, filePath);
                 return current;
             }, identity);
         }
         catch (error) {
-            throwAppendIdentityError(error, options.filePath);
+            throwAppendIdentityError(error, filePath);
         }
         if (options.maxFileBytes !== undefined &&
             Number(identity.size) + contentBuffer.byteLength > options.maxFileBytes) {

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"replace-directory.d.ts","sourceRoot":"","sources":["../src/replace-directory.ts"],"names":[],"mappings":"AAUA,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,CAiBf"}

package/dist/replace-directory.js

@@ -4,17 +4,24 @@ 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 { admitStandalonePublicationPath } from "./standalone-publication-path.js";
 import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function replaceDirectoryAtomic(options) {
-    const targetDir = path.resolve(options.targetDir);
+    const stagedDirInput = admitStandalonePublicationPath(options.stagedDir, "staged directory uses a Windows filesystem namespace alias");
+    const targetDirInput = admitStandalonePublicationPath(options.targetDir, "target directory uses a Windows filesystem namespace alias");
+    const stagedDir = path.resolve(stagedDirInput);
+    const targetDir = path.resolve(targetDirInput);
+    assertNoWindowsPathAlias(stagedDir, "filesystem", "staged directory uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(targetDir, "filesystem", "target directory uses a Windows filesystem namespace alias");
+    const backupPrefixInput = options.backupPrefix;
     await serializePathWrite(targetDir, async () => {
-        await replaceDirectoryAtomicUnserialized(options, targetDir);
+        await replaceDirectoryAtomicUnserialized(stagedDir, targetDir, backupPrefixInput);
     });
 }
-async function replaceDirectoryAtomicUnserialized(options, targetDir) {
-    const stagedDir = path.resolve(options.stagedDir);
+async function replaceDirectoryAtomicUnserialized(stagedDir, targetDir, backupPrefixInput) {
     const parentDir = path.dirname(targetDir);
-    const backupPrefix = assertSafePathPrefix(options.backupPrefix ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
+    const backupPrefix = assertSafePathPrefix(backupPrefixInput ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
     const backupDir = path.join(parentDir, `${backupPrefix}${process.pid}-${randomUUID()}`);
     let backupCreated = false;
     await fs.mkdir(recursiveMkdirPath(parentDir), { recursive: true });

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

@@ -3,6 +3,7 @@ import fs, { type FileHandle } from "node:fs/promises";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
 type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
 export declare function cleanupPinnedFilePath(params: {
     pathname: string;
     handle: FileHandle;

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,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"}
+{"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;AAEvD,OAAO,EAAwD,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAQzH,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;AAIF,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAOf;AA8DD,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

@@ -1,12 +1,23 @@
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
-import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 const PUBLISHED_READ_FLAGS = resolveReadOpenFlags();
+export async function removePathIfIdentityUnchanged(targetPath, identity) {
+    const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
+    await withAsyncDirectoryGuards([parentGuard], async () => {
+        const current = syncFs.lstatSync(targetPath, { bigint: true });
+        if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentityForCleanup(current, identity))
+            return;
+        await fs.unlink(targetPath);
+    });
+}
 function assertOwnedFile(stat, pathname, pathnameEntry) {
     if (stat.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Atomic replace owned file became a symlink: ${pathname}`);

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"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"}

package/dist/replace-file.js

@@ -9,6 +9,7 @@ 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";
+import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 function isRetryableRenameError(error) {
@@ -85,6 +86,7 @@ function validateReplaceFilePath(filePath) {
     if (!filePath || filePath.includes("\0")) {
         throw new Error("Atomic replace file path must be non-empty.");
     }
+    return admitStandalonePublicationPath(filePath, "atomic replace path uses a Windows filesystem namespace alias");
 }
 function validateRestoreOptions(options) {
     if (options.copyFallbackRestore !== "restore-original")
@@ -101,7 +103,7 @@ function buildReplaceTempPath(filePath, tempPrefix) {
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-replace", { label: "atomic replace temp prefix" });
     return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
 }
-async function resolveMode(options) {
+async function resolveMode(options, filePath) {
     const defaultMode = options.mode ?? 0o600;
     if (!options.preserveExistingMode) {
         return defaultMode;
@@ -109,7 +111,7 @@ async function resolveMode(options) {
     const fsModule = options.fileSystem?.promises ?? fs;
     let stat;
     try {
-        stat = fsModule === fs ? syncFs.lstatSync(options.filePath) : await fsModule.lstat(options.filePath);
+        stat = fsModule === fs ? syncFs.lstatSync(filePath) : await fsModule.lstat(filePath);
     }
     catch (error) {
         if (error.code === "ENOENT") {
@@ -119,7 +121,7 @@ async function resolveMode(options) {
     }
     return stat ? inheritedRegularFileMode(stat) : defaultMode;
 }
-function resolveModeSync(options) {
+function resolveModeSync(options, filePath) {
     const defaultMode = options.mode ?? 0o600;
     if (!options.preserveExistingMode) {
         return defaultMode;
@@ -127,7 +129,7 @@ function resolveModeSync(options) {
     const fsModule = options.fileSystem ?? syncFs;
     let stat;
     try {
-        stat = fsModule.lstatSync(options.filePath);
+        stat = fsModule.lstatSync(filePath);
     }
     catch (error) {
         if (error.code !== "ENOENT") {
@@ -144,13 +146,13 @@ export async function replaceFileAtomic(options) {
 }
 // Internal owner hook: keep directory durability inside publication verification and serialization.
 export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
-    const filePath = options.filePath;
-    validateReplaceFilePath(filePath);
+    const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
-    validateRenameIdentity(options.renameIdentity);
+    const renameIdentity = options.renameIdentity;
+    validateRenameIdentity(renameIdentity);
     return await serializePathWrite(path.resolve(filePath), async () => {
-        if (options.renameIdentity !== "verify-content-with-lock") {
-            return await replaceFileAtomicUnserialized(options, syncParent);
+        if (renameIdentity !== "verify-content-with-lock") {
+            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent);
         }
         const fsModule = options.fileSystem?.promises ?? fs;
         const dir = path.dirname(filePath);
@@ -158,16 +160,15 @@ export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
             recursive: true,
             mode: options.dirMode ?? 0o700,
         });
-        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, syncParent));
+        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent));
     });
 }
-async function replaceFileAtomicUnserialized(options, syncParent) {
-    const filePath = options.filePath;
+async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent) {
     const fsModule = options.fileSystem?.promises ?? fs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
-    const mode = await resolveMode(options);
-    const expectedHash = atomicExpectedContentHash(options.renameIdentity, options.content);
+    const mode = await resolveMode(options, filePath);
+    const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
     let originalError;
@@ -240,12 +241,12 @@ async function replaceFileAtomicUnserialized(options, syncParent) {
     }
 }
 export function replaceFileAtomicSync(options) {
-    const filePath = options.filePath;
-    validateReplaceFilePath(filePath);
+    const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
-    validateRenameIdentity(options.renameIdentity);
-    if (options.renameIdentity !== "verify-content-with-lock") {
-        return replaceFileAtomicSyncUnserialized(options);
+    const renameIdentity = options.renameIdentity;
+    validateRenameIdentity(renameIdentity);
+    if (renameIdentity !== "verify-content-with-lock") {
+        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity);
     }
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
@@ -253,15 +254,14 @@ export function replaceFileAtomicSync(options) {
         recursive: true,
         mode: options.dirMode ?? 0o700,
     });
-    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options));
+    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity));
 }
-function replaceFileAtomicSyncUnserialized(options) {
-    const filePath = options.filePath;
+function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
-    const mode = resolveModeSync(options);
-    const expectedHash = atomicExpectedContentHash(options.renameIdentity, options.content);
+    const mode = resolveModeSync(options, filePath);
+    const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const fchmodSync = options.fileSystem?.fchmodSync ?? (options.fileSystem === undefined ? syncFs.fchmodSync : undefined);
     if (!fchmodSync &&
         (options.mode !== undefined ||

package/dist/root-boundary.d.ts

@@ -0,0 +1,29 @@
+export type RootBoundaryIdentity = Readonly<{
+    dev: number | bigint;
+    ino: number | bigint;
+}>;
+export type AdmittedRootPath = Readonly<{
+    path: string;
+    relativePath: string;
+    admission: "exact" | "identity";
+}>;
+/**
+ * Admit a path at a trusted directory boundary.
+ *
+ * On Windows, an exact structural prefix is allocation-only and performs no
+ * filesystem observation. A match which depends on case folding is accepted
+ * only when the candidate prefix names the exact trusted root object. Accepted
+ * paths are always returned under the trusted root spelling.
+ */
+export declare function admitPathInsideRoot(params: {
+    rootPath: string;
+    candidatePath: string;
+    rootIdentity?: RootBoundaryIdentity;
+    resolveCandidateRoot?: boolean;
+    identityCache?: Map<string, boolean>;
+    inspectCandidateRoot?: (candidateRootPath: string, expected: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>) => void;
+}): AdmittedRootPath | undefined;
+//# sourceMappingURL=root-boundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-boundary.d.ts","sourceRoot":"","sources":["../src/root-boundary.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAwHH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,CACrB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,KAC7C,IAAI,CAAC;CACX,GAAG,gBAAgB,GAAG,SAAS,CAiE/B"}