@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/regular-file.js

@@ -2,12 +2,14 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertNoSymlinkParents, assertNoSymlinkParentsSync } from "./symlink-parents.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 export function resolveRegularFileAppendFlags(constants = fsSync.constants) {
     const noFollow = constants.O_NOFOLLOW;
     return (constants.O_CREAT |
@@ -57,13 +59,15 @@ export function statRegularFileSync(filePath) {
     return { missing: false, stat };
 }
 export async function readRegularFile(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
     assertNoUnsafeDeviceReadPath(params.filePath);
-    const result = await statRegularFile(params.filePath);
-    if (result.missing) {
-        throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
-    }
-    if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw regularFileTooLargeError(params.filePath, params.maxBytes);
+    const before = await inspectFileIdentity(async () => {
+        const stat = await fs.lstat(params.filePath, { bigint: true });
+        assertRegularReadStat(stat, params.filePath, true);
+        return stat;
+    }).catch((error) => throwReadPreviewError(error, params.filePath));
+    if (maxBytes !== undefined && before.size > maxBytes) {
+        throw regularFileTooLargeError(params.filePath, maxBytes);
     }
     let handle;
     try {
@@ -77,9 +81,17 @@ export async function readRegularFile(params) {
     }
     try {
         const stat = await handle.stat();
-        let pathStat;
+        const identity = await inspectFileIdentity(async () => {
+            const exact = await handle.stat({ bigint: true });
+            assertRegularReadStat(exact, params.filePath);
+            return exact;
+        }, before);
         try {
-            pathStat = await fs.lstat(params.filePath);
+            await inspectFileIdentity(async () => {
+                const current = await fs.lstat(params.filePath, { bigint: true });
+                assertRegularReadStat(current, params.filePath);
+                return current;
+            }, identity);
         }
         catch (err) {
             if (isNotFoundPathError(err)) {
@@ -87,27 +99,21 @@ export async function readRegularFile(params) {
             }
             throw err;
         }
-        verifyStableReadTarget({
-            filePath: params.filePath,
-            pathStat,
-            postOpenStat: stat,
-            preOpenStat: result.stat,
-        });
-        if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-            throw regularFileTooLargeError(params.filePath, params.maxBytes);
+        if (maxBytes !== undefined && stat.size > maxBytes) {
+            throw regularFileTooLargeError(params.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.
         let buffer;
         try {
             buffer =
-                params.maxBytes === undefined
+                maxBytes === undefined
                     ? await handle.readFile()
-                    : await readFileHandleBounded(handle, params.maxBytes);
+                    : await readFileHandleBounded(handle, maxBytes);
         }
         catch (error) {
-            if (params.maxBytes !== undefined) {
-                translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
+            if (maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, params.filePath, maxBytes);
             }
             throw error;
         }
@@ -117,20 +123,30 @@ export async function readRegularFile(params) {
         await handle.close();
     }
 }
-function verifyStableReadTarget(params) {
-    if (!params.postOpenStat.isFile() || params.pathStat.isSymbolicLink() || !params.pathStat.isFile()) {
-        throw new Error(`File is not a regular file: ${params.filePath}`);
+function throwReadPreviewError(error, filePath) {
+    if (isNotFoundPathError(error)) {
+        throw Object.assign(new Error(`File not found: ${filePath}`), { code: "ENOENT" });
     }
-    if (!sameFileIdentity(params.preOpenStat, params.postOpenStat) ||
-        !sameFileIdentity(params.pathStat, params.postOpenStat)) {
-        throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+    throw error;
+}
+function assertRegularReadStat(stat, filePath, preview = false) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(preview ? "path must be a regular file" : `File is not a regular file: ${filePath}`);
     }
 }
 function readOpenedRegularFileSync(params) {
     const stat = fsSync.fstatSync(params.fd);
-    let pathStat;
+    const identity = inspectFileIdentitySync(() => {
+        const exact = fsSync.fstatSync(params.fd, { bigint: true });
+        assertRegularReadStat(exact, params.filePath);
+        return exact;
+    }, params.preOpenStat);
     try {
-        pathStat = fsSync.lstatSync(params.filePath);
+        inspectFileIdentitySync(() => {
+            const current = fsSync.lstatSync(params.filePath, { bigint: true });
+            assertRegularReadStat(current, params.filePath);
+            return current;
+        }, identity);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -138,12 +154,6 @@ function readOpenedRegularFileSync(params) {
         }
         throw error;
     }
-    verifyStableReadTarget({
-        filePath: params.filePath,
-        pathStat,
-        postOpenStat: stat,
-        preOpenStat: params.preOpenStat,
-    });
     if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
         throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
@@ -165,13 +175,21 @@ function readOpenedRegularFileSync(params) {
     return { buffer, stat };
 }
 export function readRegularFileSync(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
     assertNoUnsafeDeviceReadPath(params.filePath);
-    const result = statRegularFileSync(params.filePath);
-    if (result.missing) {
-        throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
+    let before;
+    try {
+        before = inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(params.filePath, { bigint: true });
+            assertRegularReadStat(stat, params.filePath, true);
+            return stat;
+        });
     }
-    if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw regularFileTooLargeError(params.filePath, params.maxBytes);
+    catch (error) {
+        throwReadPreviewError(error, params.filePath);
+    }
+    if (maxBytes !== undefined && before.size > maxBytes) {
+        throw regularFileTooLargeError(params.filePath, maxBytes);
     }
     let fd;
     try {
@@ -187,25 +205,28 @@ export function readRegularFileSync(params) {
         return readOpenedRegularFileSync({
             fd,
             filePath: params.filePath,
-            preOpenStat: result.stat,
-            maxBytes: params.maxBytes,
+            preOpenStat: before,
+            maxBytes,
         });
     }
     finally {
         fsSync.closeSync(fd);
     }
 }
-function verifyStableAppendTarget(params) {
-    if (!params.postOpenStat.isFile()) {
-        throw new Error(`Refusing to append to non-file: ${params.filePath}`);
+function assertRegularAppendStat(stat, filePath) {
+    if (!stat.isFile()) {
+        throw new Error(`Refusing to append to non-file: ${filePath}`);
     }
-    if (params.postOpenStat.nlink > 1) {
-        throw new Error(`Refusing to append to hardlinked file: ${params.filePath}`);
+    if (stat.nlink > 1n) {
+        throw new Error(`Refusing to append to hardlinked file: ${filePath}`);
     }
-    const pre = params.preOpenStat;
-    if (pre && (pre.dev !== params.postOpenStat.dev || pre.ino !== params.postOpenStat.ino)) {
-        throw new Error(`Refusing to append after file changed: ${params.filePath}`);
+}
+function throwAppendIdentityError(error, filePath) {
+    if (isNotFoundPathError(error) ||
+        (error instanceof FsSafeError && error.code === "path-mismatch")) {
+        throw new Error(`Refusing to append after file changed: ${filePath}`, { cause: error });
     }
+    throw error;
 }
 export async function appendRegularFile(options) {
     if (options.rejectSymlinkParents === true) {
@@ -221,32 +242,49 @@ export async function appendRegularFile(options) {
     }
     let preOpenStat;
     try {
-        const stat = await fs.lstat(options.filePath);
-        if (stat.isSymbolicLink()) {
-            throw new Error(`Refusing to append through symlink: ${options.filePath}`);
-        }
-        if (!stat.isFile()) {
-            throw new Error(`Refusing to append to non-file: ${options.filePath}`);
-        }
-        preOpenStat = stat;
+        preOpenStat = await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(options.filePath, { bigint: true });
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Refusing to append through symlink: ${options.filePath}`);
+            }
+            if (!stat.isFile()) {
+                throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+            }
+            return stat;
+        });
     }
-    catch (err) {
-        if (!isNotFoundPathError(err)) {
-            throw err;
-        }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
     }
     const contentBytes = Buffer.isBuffer(options.content)
         ? options.content.byteLength
         : Buffer.byteLength(options.content, options.encoding ?? "utf8");
     if (options.maxFileBytes !== undefined &&
-        (preOpenStat?.size ?? 0) + contentBytes > options.maxFileBytes) {
+        Number(preOpenStat?.size ?? 0n) + contentBytes > options.maxFileBytes) {
         return;
     }
+    await getFsSafeTestHooks()?.beforeRegularFileAppendOpen?.(options.filePath);
     const handle = await fs.open(options.filePath, resolveRegularFileAppendFlags(), options.mode ?? 0o600);
     try {
-        const stat = await handle.stat();
-        verifyStableAppendTarget({ preOpenStat, postOpenStat: stat, filePath: options.filePath });
-        if (options.maxFileBytes !== undefined && stat.size + contentBytes > options.maxFileBytes) {
+        let identity;
+        try {
+            identity = await inspectFileIdentity(async () => {
+                const stat = await handle.stat({ bigint: true });
+                assertRegularAppendStat(stat, options.filePath);
+                return stat;
+            }, preOpenStat);
+            await inspectFileIdentity(async () => {
+                const current = await fs.lstat(options.filePath, { bigint: true });
+                assertRegularAppendStat(current, options.filePath);
+                return current;
+            }, identity);
+        }
+        catch (error) {
+            throwAppendIdentityError(error, options.filePath);
+        }
+        if (options.maxFileBytes !== undefined &&
+            Number(identity.size) + contentBytes > options.maxFileBytes) {
             return;
         }
         await handle.chmod(options.mode ?? 0o600);
@@ -270,33 +308,49 @@ export function appendRegularFileSync(options) {
     }
     let preOpenStat;
     try {
-        const stat = fsSync.lstatSync(options.filePath);
-        if (stat.isSymbolicLink()) {
-            throw new Error(`Refusing to append through symlink: ${options.filePath}`);
-        }
-        if (!stat.isFile()) {
-            throw new Error(`Refusing to append to non-file: ${options.filePath}`);
-        }
-        preOpenStat = stat;
+        preOpenStat = inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(options.filePath, { bigint: true });
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Refusing to append through symlink: ${options.filePath}`);
+            }
+            if (!stat.isFile()) {
+                throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+            }
+            return stat;
+        });
     }
-    catch (err) {
-        if (!isNotFoundPathError(err)) {
-            throw err;
-        }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
     }
     const contentBuffer = typeof options.content === "string"
         ? Buffer.from(options.content, options.encoding ?? "utf8")
         : Buffer.from(options.content);
     if (options.maxFileBytes !== undefined &&
-        (preOpenStat?.size ?? 0) + contentBuffer.byteLength > options.maxFileBytes) {
+        Number(preOpenStat?.size ?? 0n) + contentBuffer.byteLength > options.maxFileBytes) {
         return;
     }
+    getFsSafeTestHooks()?.beforeRegularFileAppendOpenSync?.(options.filePath);
     const fd = fsSync.openSync(options.filePath, resolveRegularFileAppendFlags(), options.mode ?? 0o600);
     try {
-        const stat = fsSync.fstatSync(fd);
-        verifyStableAppendTarget({ preOpenStat, postOpenStat: stat, filePath: options.filePath });
+        let identity;
+        try {
+            identity = inspectFileIdentitySync(() => {
+                const stat = fsSync.fstatSync(fd, { bigint: true });
+                assertRegularAppendStat(stat, options.filePath);
+                return stat;
+            }, preOpenStat);
+            inspectFileIdentitySync(() => {
+                const current = fsSync.lstatSync(options.filePath, { bigint: true });
+                assertRegularAppendStat(current, options.filePath);
+                return current;
+            }, identity);
+        }
+        catch (error) {
+            throwAppendIdentityError(error, options.filePath);
+        }
         if (options.maxFileBytes !== undefined &&
-            stat.size + contentBuffer.byteLength > options.maxFileBytes) {
+            Number(identity.size) + contentBuffer.byteLength > options.maxFileBytes) {
             return;
         }
         fsSync.fchmodSync(fd, options.mode ?? 0o600);

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

@@ -1,4 +1,4 @@
-import syncFs from "node:fs";
+import syncFs, { type BigIntStats } from "node:fs";
 export type ReplaceFileDestinationHardlinkPolicy = "reject";
 export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
 export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
@@ -21,6 +21,7 @@ export declare function copyFallbackReplace(params: {
     destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
     restore: ReplaceFileCopyFallbackRestorePolicy;
     maxRestoreBytes?: number;
+    expectedSourceIdentity?: BigIntStats;
     sync: boolean;
 }): Promise<void>;
 export declare function copyFallbackReplaceSync(params: {
@@ -30,6 +31,7 @@ export declare function copyFallbackReplaceSync(params: {
     destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
     restore: ReplaceFileCopyFallbackRestorePolicy;
     maxRestoreBytes?: number;
+    expectedSourceIdentity?: BigIntStats;
     fchmodSync?: (fd: number, mode: number) => void;
     sync: boolean;
 }): void;

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,MAAsB,MAAM,SAAS,CAAC;AAK7C,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;AAuFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AAmID,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,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CA+DhB;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,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CA6EP"}
+{"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;AAuFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AAmID,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,CAwDhB;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,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.
+        }
+    }
+}