@openclaw/fs-safe 0.6.0 → 0.7.0

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

@@ -1,9 +1,11 @@
 import syncFs, {} from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { readOwnedCopySource, readOwnedCopySourceSync } from "./replace-file-copy-source.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants;
 const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
-const OPEN_READ_FLAGS = syncFs.constants.O_RDONLY | NOFOLLOW;
+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;
@@ -236,24 +238,19 @@ function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes
     }
 }
 export async function copyFallbackReplace(params) {
-    const sourcePreview = await params.fsModule.lstat(params.src);
-    if (sourcePreview.isSymbolicLink() || !sourcePreview.isFile()) {
-        throw new Error(`Refusing copy fallback from non-file source: ${params.src}`);
-    }
-    const sourceHandle = await params.fsModule.open(params.src, OPEN_READ_FLAGS);
+    const source = await readOwnedCopySource({
+        fsModule: params.fsModule,
+        src: params.src,
+        expectedIdentity: params.expectedSourceIdentity,
+    });
+    const { replacement } = source;
     let destHandle = null;
     try {
-        const sourceStat = await sourceHandle.stat();
-        const sourceCurrent = await params.fsModule.lstat(params.src);
-        if (!sourceStat.isFile() || sourceCurrent.isSymbolicLink() || !sameFileIdentity(sourceStat, sourceCurrent)) {
-            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
-        }
-        const replacement = await sourceHandle.readFile();
         if (params.restore === "restore-original") {
             const pinned = await openPinnedDestination(params.fsModule, params.dest, params.destinationHardlinks);
             if (pinned) {
                 destHandle = pinned.handle;
-                await replacePinnedWithRestore(destHandle, replacement, params.maxRestoreBytes, sourceStat.mode);
+                await replacePinnedWithRestore(destHandle, replacement, params.maxRestoreBytes, source.mode);
             }
         }
         if (!destHandle) {
@@ -269,9 +266,9 @@ export async function copyFallbackReplace(params) {
                 await assertDestinationHardlinkPolicy(params.fsModule, params.dest, params.destinationHardlinks);
                 await params.fsModule.rm(params.dest, { force: true });
             }
-            destHandle = await params.fsModule.open(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
+            destHandle = await params.fsModule.open(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, source.mode & 0o777);
             await destHandle.writeFile(replacement);
-            await destHandle.chmod(sourceStat.mode);
+            await destHandle.chmod(source.mode);
             if (params.sync) {
                 await destHandle.sync();
             }
@@ -279,28 +276,22 @@ export async function copyFallbackReplace(params) {
     }
     finally {
         await destHandle?.close().catch(() => undefined);
-        await sourceHandle.close().catch(() => undefined);
     }
 }
 export function copyFallbackReplaceSync(params) {
-    const sourcePreview = params.fsModule.lstatSync(params.src);
-    if (sourcePreview.isSymbolicLink() || !sourcePreview.isFile()) {
-        throw new Error(`Refusing copy fallback from non-file source: ${params.src}`);
-    }
-    const sourceFd = params.fsModule.openSync(params.src, OPEN_READ_FLAGS);
+    const source = readOwnedCopySourceSync({
+        fsModule: params.fsModule,
+        src: params.src,
+        expectedIdentity: params.expectedSourceIdentity,
+    });
+    const { replacement } = source;
     let destFd;
     try {
-        const sourceStat = params.fsModule.fstatSync(sourceFd);
-        const sourceCurrent = params.fsModule.lstatSync(params.src);
-        if (!sourceStat.isFile() || sourceCurrent.isSymbolicLink() || !sameFileIdentity(sourceStat, sourceCurrent)) {
-            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
-        }
-        const replacement = readBoundedSync(params.fsModule, sourceFd, Number.MAX_SAFE_INTEGER);
         if (params.restore === "restore-original") {
             const pinned = openPinnedDestinationSync(params.fsModule, params.dest, params.destinationHardlinks);
             if (pinned) {
                 destFd = pinned.fd;
-                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, sourceStat.mode, params.fchmodSync);
+                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync);
             }
         }
         if (destFd === undefined) {
@@ -319,9 +310,9 @@ export function copyFallbackReplaceSync(params) {
                 assertDestinationHardlinkPolicySync(params.fsModule, params.dest, params.destinationHardlinks);
                 params.fsModule.rmSync(params.dest, { force: true });
             }
-            destFd = params.fsModule.openSync(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
+            destFd = params.fsModule.openSync(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, source.mode & 0o777);
             writeAllSync(params.fsModule, destFd, replacement);
-            params.fchmodSync?.(destFd, sourceStat.mode);
+            params.fchmodSync?.(destFd, source.mode);
             if (params.sync) {
                 params.fsModule.fsyncSync(destFd);
             }
@@ -336,11 +327,5 @@ export function copyFallbackReplaceSync(params) {
                 // Best-effort close after fallback replacement.
             }
         }
-        try {
-            params.fsModule.closeSync(sourceFd);
-        }
-        catch {
-            // Best-effort close after fallback replacement.
-        }
     }
 }

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

@@ -0,0 +1,21 @@
+import syncFs, { type BigIntStats } from "node:fs";
+type AsyncSourceFileSystem = Pick<typeof import("node:fs/promises"), "lstat" | "open">;
+type SyncSourceFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readSync">;
+export declare function readOwnedCopySource(params: {
+    fsModule: AsyncSourceFileSystem;
+    src: string;
+    expectedIdentity?: BigIntStats;
+}): Promise<{
+    replacement: Buffer;
+    mode: number;
+}>;
+export declare function readOwnedCopySourceSync(params: {
+    fsModule: SyncSourceFileSystem;
+    src: string;
+    expectedIdentity?: BigIntStats;
+}): {
+    replacement: Buffer;
+    mode: number;
+};
+export {};
+//# sourceMappingURL=replace-file-copy-source.d.ts.map

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

@@ -0,0 +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;AAMnD,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;AAgEF,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,CA0BjD;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

@@ -0,0 +1,112 @@
+import syncFs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+const NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants
+    ? syncFs.constants.O_NOFOLLOW
+    : 0;
+const NONBLOCK = process.platform !== "win32" && "O_NONBLOCK" in syncFs.constants
+    ? syncFs.constants.O_NONBLOCK
+    : 0;
+const OPEN_READ_FLAGS = syncFs.constants.O_RDONLY | NOFOLLOW | NONBLOCK;
+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}`);
+    }
+    if (!source.isFile()) {
+        throw new FsSafeError("not-file", `Refusing copy fallback from non-file source: ${src}`);
+    }
+    if (source.nlink !== 1) {
+        throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${src}`);
+    }
+}
+function sourceSymlinkError(src, cause) {
+    return new FsSafeError("symlink", `Refusing copy fallback from non-file source: ${src}`, {
+        cause,
+    });
+}
+async function openSource(fsModule, src) {
+    try {
+        return await fsModule.open(src, OPEN_READ_FLAGS);
+    }
+    catch (error) {
+        if (error.code === "ELOOP") {
+            throw sourceSymlinkError(src, error);
+        }
+        throw error;
+    }
+}
+function openSourceSync(fsModule, src) {
+    try {
+        return fsModule.openSync(src, OPEN_READ_FLAGS);
+    }
+    catch (error) {
+        if (error.code === "ELOOP") {
+            throw sourceSymlinkError(src, error);
+        }
+        throw error;
+    }
+}
+function readAllSync(fsModule, fd) {
+    const chunks = [];
+    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;
+        position += bytesRead;
+        chunks.push(buffer.subarray(0, bytesRead));
+    }
+    return Buffer.concat(chunks, position);
+}
+export async function readOwnedCopySource(params) {
+    assertSourcePreview(await params.fsModule.lstat(params.src), params.src);
+    const handle = await openSource(params.fsModule, params.src);
+    try {
+        if (params.expectedIdentity) {
+            const exact = await inspectFileIdentity(() => handle.stat({ bigint: true }), params.expectedIdentity);
+            await inspectFileIdentity(() => params.fsModule.lstat(params.src, { bigint: true }), exact);
+        }
+        const opened = await handle.stat();
+        const current = await params.fsModule.lstat(params.src);
+        if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
+            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
+        }
+        if (opened.nlink !== 1) {
+            throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${params.src}`);
+        }
+        return { replacement: await handle.readFile(), mode: opened.mode };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export function readOwnedCopySourceSync(params) {
+    assertSourcePreview(params.fsModule.lstatSync(params.src), params.src);
+    const fd = openSourceSync(params.fsModule, params.src);
+    try {
+        if (params.expectedIdentity) {
+            const exact = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }), params.expectedIdentity);
+            inspectFileIdentitySync(() => params.fsModule.lstatSync(params.src, { bigint: true }), exact);
+        }
+        const opened = params.fsModule.fstatSync(fd);
+        const current = params.fsModule.lstatSync(params.src);
+        if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
+            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
+        }
+        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 };
+    }
+    finally {
+        try {
+            params.fsModule.closeSync(fd);
+        }
+        catch {
+            // Best-effort close after reading a copy-fallback source.
+        }
+    }
+}

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

@@ -1,5 +1,5 @@
 import syncFs, { type BigIntStats } from "node:fs";
-import fs from "node:fs/promises";
+import fs, { type FileHandle } from "node:fs/promises";
 type AsyncTempFileSystem = Pick<typeof fs, "lstat" | "open" | "writeFile">;
 type SyncTempFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "lstatSync" | "openSync" | "writeFileSync">;
 export type SyncFchmod = (fd: number, mode: number) => void;
@@ -7,6 +7,8 @@ export declare function applyDirectoryMode(params: {
     fsModule: AsyncTempFileSystem;
     dirPath: string;
     mode: number;
+    /** Compatibility for best-effort directory modes; admission and close still fail closed. */
+    ignoreChmodError?: boolean;
 }): Promise<void>;
 export declare function applyDirectoryModeSync(params: {
     fsModule: SyncTempFileSystem;
@@ -20,7 +22,11 @@ export declare function writeTempFile(params: {
     content: string | Uint8Array;
     mode: number;
     sync: boolean;
-}): Promise<BigIntStats>;
+    onIdentity?: (identity: BigIntStats) => void;
+}): Promise<{
+    handle: FileHandle;
+    identity: BigIntStats;
+}>;
 export declare function writeTempFileSync(params: {
     fsModule: SyncTempFileSystem;
     tempPath: string;
@@ -28,6 +34,10 @@ export declare function writeTempFileSync(params: {
     mode: number;
     fchmodSync?: SyncFchmod;
     sync: boolean;
-}): BigIntStats;
+    onIdentity?: (identity: BigIntStats) => void;
+}): {
+    fd: number;
+    identity: BigIntStats;
+};
 export {};
 //# sourceMappingURL=replace-file-descriptor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAIvD,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA2B5D,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAcP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,WAAW,CAAC,CAkBvB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,WAAW,CAkBd"}
+{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKvD,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA2B5D,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAcP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC,CA0BzD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CA0BxC"}

package/dist/replace-file-descriptor.js

@@ -2,6 +2,7 @@ import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 function directoryOpenFlags() {
     return (syncFs.constants.O_RDONLY |
         syncFs.constants.O_DIRECTORY |
@@ -31,7 +32,13 @@ export async function applyDirectoryMode(params) {
     const handle = await params.fsModule.open(params.dirPath, directoryOpenFlags());
     try {
         assertSameDirectory(expected, await handle.stat(), params.dirPath);
-        await handle.chmod(params.mode);
+        try {
+            await handle.chmod(params.mode);
+        }
+        catch (error) {
+            if (params.ignoreChmodError !== true)
+                throw error;
+        }
     }
     finally {
         await handle.close();
@@ -55,6 +62,8 @@ export function applyDirectoryModeSync(params) {
 export async function writeTempFile(params) {
     const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
     try {
+        const identity = await inspectFileIdentity(() => handle.stat({ bigint: true }));
+        params.onIdentity?.(identity);
         await params.fsModule.writeFile(handle, params.content);
         await handle.chmod(params.mode);
         if (params.sync) {
@@ -67,15 +76,24 @@ export async function writeTempFile(params) {
                 }
             }
         }
-        return await handle.stat({ bigint: true });
+        await inspectFileIdentity(() => handle.stat({ bigint: true }), identity);
+        return { handle, identity };
     }
-    finally {
-        await handle.close();
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Atomic temp write and close failed");
+        }
+        throw error;
     }
 }
 export function writeTempFileSync(params) {
     const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
     try {
+        const identity = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }));
+        params.onIdentity?.(identity);
         params.fsModule.writeFileSync(fd, params.content);
         params.fchmodSync?.(fd, params.mode);
         if (params.sync) {
@@ -88,9 +106,16 @@ export function writeTempFileSync(params) {
                 }
             }
         }
-        return params.fsModule.fstatSync(fd, { bigint: true });
+        inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }), identity);
+        return { fd, identity };
     }
-    finally {
-        params.fsModule.closeSync(fd);
+    catch (error) {
+        try {
+            params.fsModule.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Atomic temp write and close failed");
+        }
+        throw error;
     }
 }

package/dist/replace-file-rename-policy.d.ts

@@ -0,0 +1,7 @@
+import type { RenameIdentityPolicy } from "./pinned-write.js";
+export type { RenameIdentityPolicy };
+export declare function validateRenameIdentity(policy: RenameIdentityPolicy | undefined): void;
+export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
+export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+export declare function withAtomicRenameIdentityLockSync<T>(filePath: string, fn: () => T): T;
+//# sourceMappingURL=replace-file-rename-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-rename-policy.d.ts","sourceRoot":"","sources":["../src/replace-file-rename-policy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAIrF;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,MAAM,GAAG,SAAS,CAGpB;AAcD,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAgB,gCAAgC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpF"}

package/dist/replace-file-rename-policy.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { withFileLock, withFileLockSync } from "./file-lock.js";
+import { sha256Hex } from "./file-identity.js";
+export function validateRenameIdentity(policy) {
+    if (policy !== undefined && policy !== "strict" && policy !== "verify-content-with-lock") {
+        throw new RangeError("renameIdentity must be strict or verify-content-with-lock");
+    }
+}
+export function atomicExpectedContentHash(policy, content) {
+    if (policy !== "verify-content-with-lock")
+        return undefined;
+    return sha256Hex(typeof content === "string" ? content : Buffer.from(content));
+}
+function lockOptions(filePath) {
+    const resolved = path.resolve(filePath);
+    return {
+        managerKey: `fs-safe.atomic:${resolved}`,
+        lockPath: path.join(path.dirname(resolved), `.fs-safe-atomic-${sha256Hex(resolved)}.lock`),
+        staleMs: 30_000,
+        timeoutMs: 5_000,
+        payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+        retry: { retries: 5, minTimeout: 100, maxTimeout: 2_000, factor: 2 },
+    };
+}
+export async function withAtomicRenameIdentityLock(filePath, fn) {
+    return await withFileLock(filePath, lockOptions(filePath), fn);
+}
+export function withAtomicRenameIdentityLockSync(filePath, fn) {
+    return withFileLockSync(filePath, lockOptions(filePath), fn);
+}

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

@@ -0,0 +1,46 @@
+import syncFs, { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
+type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export declare class AsyncAtomicTempOwner {
+    #private;
+    readonly pathname: string;
+    constructor(pathname: string);
+    start(): void;
+    readonly onIdentity: (identity: BigIntStats) => void;
+    adopt(temp: {
+        handle: FileHandle;
+        identity: BigIntStats;
+    }): void;
+    get identity(): BigIntStats;
+    assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
+    markRenamed(): void;
+    finish(params: {
+        fsModule: AsyncOwnerFileSystem;
+        originalError?: unknown;
+        throwOnCleanupError: boolean;
+    }): Promise<void>;
+}
+export declare class SyncAtomicTempOwner {
+    #private;
+    readonly pathname: string;
+    constructor(pathname: string);
+    start(): void;
+    readonly onIdentity: (identity: BigIntStats) => void;
+    adopt(temp: {
+        fd: number;
+        identity: BigIntStats;
+    }): void;
+    get identity(): BigIntStats;
+    assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
+    markRenamed(): void;
+    finish(params: {
+        fsModule: SyncOwnerFileSystem;
+        originalError?: unknown;
+        throwOnCleanupError: boolean;
+    }): void;
+}
+export {};
+//# sourceMappingURL=replace-file-temp-owner.d.ts.map

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

@@ -0,0 +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;AAMvD,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;AAiGF,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,CAkB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA0Cf;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"}