@openclaw/fs-safe 0.1.2 → 0.2.0

package/dist/output.d.ts

@@ -0,0 +1,13 @@
+export type ExternalFileWriteOptions<T = void> = {
+    rootDir: string;
+    path: string;
+    write: (filePath: string) => Promise<T>;
+    maxBytes?: number;
+    mode?: number;
+};
+export type ExternalFileWriteResult<T = void> = {
+    path: string;
+    result: T;
+};
+export declare function writeExternalFileWithinRoot<T = void>(options: ExternalFileWriteOptions<T>): Promise<ExternalFileWriteResult<T>>;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA6CF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA8BrC"}

package/dist/output.js

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sanitizeUntrustedFileName } from "./filename.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+import { tempFile } from "./temp-target.js";
+function tempFileNameForTarget(targetPath) {
+    return sanitizeUntrustedFileName(path.basename(targetPath), "output.bin");
+}
+function ensureTrailingSep(value) {
+    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+}
+function toRootPathInput(params) {
+    if (!path.isAbsolute(params.targetPath)) {
+        return params.targetPath;
+    }
+    const absoluteTarget = path.resolve(params.targetPath);
+    const rootDir = path.resolve(params.rootDir);
+    if (isPathInside(ensureTrailingSep(rootDir), absoluteTarget)) {
+        return path.relative(rootDir, absoluteTarget);
+    }
+    if (isPathInside(ensureTrailingSep(params.rootReal), absoluteTarget)) {
+        return path.relative(params.rootReal, absoluteTarget);
+    }
+    return params.targetPath;
+}
+function assertFileTargetPath(targetPath) {
+    const basename = path.basename(targetPath);
+    if (!targetPath ||
+        targetPath === "." ||
+        targetPath.endsWith("/") ||
+        targetPath.endsWith("\\") ||
+        !basename ||
+        basename === "." ||
+        basename === "..") {
+        throw new FsSafeError("invalid-path", "target path must name a file");
+    }
+}
+export async function writeExternalFileWithinRoot(options) {
+    const targetRoot = await root(options.rootDir);
+    const requestedTargetPath = options.path;
+    if (requestedTargetPath.length === 0) {
+        throw new FsSafeError("invalid-path", "target path is required");
+    }
+    const targetPath = toRootPathInput({
+        rootDir: targetRoot.rootDir,
+        rootReal: targetRoot.rootReal,
+        targetPath: requestedTargetPath,
+    });
+    assertFileTargetPath(targetPath);
+    const finalPath = await targetRoot.resolve(targetPath);
+    const staged = await tempFile({
+        prefix: "fs-safe-output",
+        fileName: tempFileNameForTarget(targetPath),
+    });
+    try {
+        const result = await options.write(staged.path);
+        await targetRoot.copyIn(targetPath, staged.path, {
+            maxBytes: options.maxBytes,
+            mode: options.mode,
+            mkdir: true,
+            sourceHardlinks: "reject",
+        });
+        return { path: finalPath, result };
+    }
+    finally {
+        await staged.cleanup();
+    }
+}

package/dist/path-stat.d.ts

@@ -0,0 +1,4 @@
+import type { Stats } from "node:fs";
+import type { PathStat } from "./types.js";
+export declare function pathStatFromStats(stat: Stats): PathStat;
+//# sourceMappingURL=path-stat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path-stat.d.ts","sourceRoot":"","sources":["../src/path-stat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAcvD"}

package/dist/path-stat.js

@@ -0,0 +1,15 @@
+export function pathStatFromStats(stat) {
+    return {
+        dev: Number(stat.dev),
+        gid: Number(stat.gid),
+        ino: Number(stat.ino),
+        isDirectory: stat.isDirectory(),
+        isFile: stat.isFile(),
+        isSymbolicLink: stat.isSymbolicLink(),
+        mode: stat.mode,
+        mtimeMs: stat.mtimeMs,
+        nlink: stat.nlink,
+        size: stat.size,
+        uid: stat.uid,
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQ3D,KAAK,gBAAgB,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAuFzC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;CACzB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuC5B;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoB5B"}
+{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAS3D,KAAK,gBAAgB,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAuFzC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;CACzB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuC5B;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoB5B"}

package/dist/pinned-write.js

@@ -1,9 +1,12 @@
+import { randomUUID } from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
 import { assertPinnedPythonOperationAvailable, runPinnedPythonOperation, validatePinnedOperationPayload, } from "./pinned-python.js";
 function byteLength(input, encoding) {
@@ -67,13 +70,13 @@ async function inputToBase64(input, maxBytes) {
     return Buffer.concat(chunks, bytes).toString("base64");
 }
 export async function runPinnedWriteHelper(params) {
-    if (getFsSafePythonConfig().mode === "off") {
-        return await runPinnedWriteFallback(params);
-    }
     assertSafeBasename(params.basename);
     validatePinnedOperationPayload({
         relativeParentPath: params.relativeParentPath,
     });
+    if (getFsSafePythonConfig().mode === "off") {
+        return await runPinnedWriteFallback(params);
+    }
     if (params.input.kind === "stream") {
         try {
             assertPinnedPythonOperationAvailable();
@@ -133,12 +136,21 @@ async function runPinnedWriteFallback(params) {
     const parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
+    const parentGuard = await createNearestExistingDirectoryGuard(params.rootPath, parentPath);
     if (params.mkdir) {
-        await fs.mkdir(parentPath, { recursive: true });
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            await fs.mkdir(parentPath, { recursive: true });
+        });
     }
     const targetPath = path.join(parentPath, params.basename);
     if (params.overwrite === false) {
-        const handle = await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode);
+        let handle = await withAsyncDirectoryGuards([parentGuard], async () => await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode), {
+            onPostGuardFailure: async (openedHandle) => {
+                // The parent failed verification, so targetPath may now resolve
+                // somewhere else. Close the fd, but do not clean up by path.
+                await openedHandle.close().catch(() => undefined);
+            },
+        });
         let created = true;
         try {
             if (params.input.kind === "buffer") {
@@ -164,32 +176,45 @@ async function runPinnedWriteFallback(params) {
             }
         }
     }
-    const tempPath = path.join(parentPath, `.${params.basename}.fallback.tmp`);
+    const tempPath = path.join(parentPath, `.${params.basename}.${randomUUID()}.fallback.tmp`);
+    const tempFlags = fsSync.constants.O_WRONLY |
+        fsSync.constants.O_CREAT |
+        fsSync.constants.O_EXCL |
+        (process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
+            ? fsSync.constants.O_NOFOLLOW
+            : 0);
+    let handle;
+    let handleClosedByStream = false;
     try {
+        handle = await fs.open(tempPath, tempFlags, params.mode);
         if (params.input.kind === "buffer") {
             assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
             if (typeof params.input.data === "string") {
-                await fs.writeFile(tempPath, params.input.data, {
-                    encoding: params.input.encoding ?? "utf8",
-                    mode: params.mode,
-                });
+                await handle.writeFile(params.input.data, params.input.encoding ?? "utf8");
             }
             else {
-                await fs.writeFile(tempPath, params.input.data, { mode: params.mode });
+                await handle.writeFile(params.input.data);
             }
         }
         else {
-            const handle = await fs.open(tempPath, "w", params.mode);
-            try {
-                await pipelineWithMaxBytes(params.input.stream, handle.createWriteStream(), params.maxBytes);
-            }
-            finally {
-                await handle.close().catch(() => { });
-            }
+            const writable = handle.createWriteStream();
+            writable.once("close", () => {
+                handleClosedByStream = true;
+            });
+            await pipelineWithMaxBytes(params.input.stream, writable, params.maxBytes);
+        }
+        if (!handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+            handle = undefined;
         }
-        await fs.rename(tempPath, targetPath);
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            await fs.rename(tempPath, targetPath);
+        });
     }
     catch (error) {
+        if (handle && !handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
         await fs.rm(tempPath, { force: true }).catch(() => undefined);
         throw error;
     }

package/dist/private-temp-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC;IAC5F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAuGF,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CA4DnB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,CAAC,GACvC,CAAC,CAUH"}
+{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC;IAC5F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAsGF,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAwEnB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,CAAC,GACvC,CAAC,CAUH"}

package/dist/private-temp-workspace.js

@@ -3,6 +3,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileStore, fileStoreSync, } from "./file-store.js";
+import { openRootFileSync } from "./root-file.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 function sanitizeTempPrefix(prefix) {
     const sanitized = prefix.trim().replace(/[^a-zA-Z0-9._-]/g, "-");
@@ -12,21 +13,20 @@ function sanitizeTempPrefix(prefix) {
     return sanitized.endsWith("-") ? sanitized : `${sanitized}-`;
 }
 function resolveWorkspaceLeaf(dir, fileName) {
-    const raw = fileName.trim();
-    if (!raw ||
-        raw === "." ||
-        raw === ".." ||
-        raw.includes("\0") ||
-        raw.includes("/") ||
-        raw.includes("\\") ||
-        path.basename(raw) !== raw) {
-        throw new Error(`Invalid temp workspace file name: ${JSON.stringify(fileName)}`);
-    }
-    return path.join(dir, raw);
+    return path.join(dir, assertWorkspaceFileName(fileName));
 }
 function assertWorkspaceFileName(fileName) {
-    resolveWorkspaceLeaf(".", fileName);
-    return fileName.trim();
+    const value = fileName.trim();
+    if (!value ||
+        value === "." ||
+        value === ".." ||
+        value.includes("\0") ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        path.basename(value) !== value) {
+        throw new Error(`Invalid temp workspace file name: ${JSON.stringify(fileName)}`);
+    }
+    return value;
 }
 async function ensurePrivateDirectory(dir, mode) {
     await fs.mkdir(dir, { recursive: true, mode });
@@ -144,8 +144,21 @@ export function tempWorkspaceSync(options) {
             trailingNewline: writeOptions?.trailingNewline,
         }),
         read: (fileName) => {
-            const filePath = store.path(assertWorkspaceFileName(fileName));
-            return fsSync.readFileSync(filePath);
+            const opened = openRootFileSync({
+                absolutePath: store.path(assertWorkspaceFileName(fileName)),
+                rootPath: dir,
+                boundaryLabel: "temp workspace",
+                rejectHardlinks: true,
+            });
+            if (!opened.ok) {
+                throw Object.assign(new Error(`File not found: ${fileName}`), { code: "ENOENT" });
+            }
+            try {
+                return fsSync.readFileSync(opened.fd);
+            }
+            finally {
+                fsSync.closeSync(opened.fd);
+            }
         },
         cleanup: () => {
             try {

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

@@ -1 +1 @@
-{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAO7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AAWD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CA6B3C;AA0CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAoBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}
+{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAQ7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AA2DD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAgC3C;AA6CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAoBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}

package/dist/regular-file.js

@@ -17,6 +17,44 @@ function resolveRegularFileReadFlags() {
             ? fsSync.constants.O_NOFOLLOW
             : 0));
 }
+async function readFileHandleBounded(params) {
+    if (params.maxBytes === undefined) {
+        return await params.handle.readFile();
+    }
+    const chunks = [];
+    const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, Math.max(1, params.maxBytes + 1)));
+    let total = 0;
+    while (true) {
+        const { bytesRead } = await params.handle.read(scratch, 0, scratch.length, null);
+        if (bytesRead === 0) {
+            return Buffer.concat(chunks, total);
+        }
+        total += bytesRead;
+        if (total > params.maxBytes) {
+            throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
+        }
+        chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
+    }
+}
+function readFileDescriptorBounded(params) {
+    if (params.maxBytes === undefined) {
+        return fsSync.readFileSync(params.fd);
+    }
+    const chunks = [];
+    const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, Math.max(1, params.maxBytes + 1)));
+    let total = 0;
+    while (true) {
+        const bytesRead = fsSync.readSync(params.fd, scratch, 0, scratch.length, null);
+        if (bytesRead === 0) {
+            return Buffer.concat(chunks, total);
+        }
+        total += bytesRead;
+        if (total > params.maxBytes) {
+            throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
+        }
+        chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
+    }
+}
 export async function statRegularFile(filePath) {
     let stat;
     try {
@@ -69,10 +107,13 @@ export async function readRegularFile(params) {
         if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
             throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
         }
-        const buffer = await handle.readFile();
-        if (params.maxBytes !== undefined && buffer.byteLength > params.maxBytes) {
-            throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
-        }
+        // With a byte cap, avoid readFile(): a raced file growth would allocate
+        // the oversized content before the post-read check could reject it.
+        const buffer = await readFileHandleBounded({
+            handle,
+            filePath: params.filePath,
+            maxBytes: params.maxBytes,
+        });
         return { buffer, stat };
     }
     finally {
@@ -99,10 +140,13 @@ function readOpenedRegularFileSync(params) {
     if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
         throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
     }
-    const buffer = fsSync.readFileSync(params.fd);
-    if (params.maxBytes !== undefined && buffer.byteLength > params.maxBytes) {
-        throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
-    }
+    // Keep capped sync reads incremental for the same reason as async reads:
+    // readFileSync(fd) would buffer a raced oversized file before throwing.
+    const buffer = readFileDescriptorBounded({
+        fd: params.fd,
+        filePath: params.filePath,
+        maxBytes: params.maxBytes,
+    });
     return { buffer, stat };
 }
 export function readRegularFileSync(params) {

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

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

package/dist/replace-directory.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { guardedRename, guardedRm } from "./guarded-mutation.js";
 export async function replaceDirectoryAtomic(options) {
     const targetDir = path.resolve(options.targetDir);
     const stagedDir = path.resolve(options.stagedDir);
@@ -8,7 +9,7 @@ export async function replaceDirectoryAtomic(options) {
     let backupCreated = false;
     await fs.mkdir(parentDir, { recursive: true });
     try {
-        await fs.rename(targetDir, backupDir);
+        await guardedRename({ from: targetDir, to: backupDir });
         backupCreated = true;
     }
     catch (err) {
@@ -17,16 +18,16 @@ export async function replaceDirectoryAtomic(options) {
         }
     }
     try {
-        await fs.rename(stagedDir, targetDir);
+        await guardedRename({ from: stagedDir, to: targetDir });
     }
     catch (err) {
         if (backupCreated) {
-            await fs.rename(backupDir, targetDir).catch(() => undefined);
+            await guardedRename({ from: backupDir, to: targetDir }).catch(() => undefined);
             backupCreated = false;
         }
         throw err;
     }
     if (backupCreated) {
-        await fs.rm(backupDir, { recursive: true, force: true });
+        await guardedRm({ target: backupDir, recursive: true, force: true, verifyAfter: false });
     }
 }

package/dist/replace-file.d.ts

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 export type ReplaceFileAtomicFileSystem = {
     promises: Pick<typeof fs, "mkdir" | "chmod" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat">;
 };
-export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "chmodSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "statSync" | "lstatSync">;
+export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "chmodSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "statSync" | "lstatSync">;
 type ReplaceFileAtomicBaseOptions = {
     filePath: string;
     content: string | Uint8Array;

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,MAAM,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAKlC,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,IAAI,CACZ,OAAO,EAAE,EACP,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CACV,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,WAAW,GACX,WAAW,GACX,UAAU,GACV,WAAW,CACd,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,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,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,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,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;AA+NF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;AAyDD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAiEzB"}
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAMlC,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,IAAI,CACZ,OAAO,EAAE,EACP,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CACV,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,WAAW,GACX,WAAW,GACX,UAAU,GACV,WAAW,CACd,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,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,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,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,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;AAySF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;AAyDD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAiEzB"}

package/dist/replace-file.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { serializePathWrite } from "./write-queue.js";
 function isRetryableRenameError(error) {
@@ -11,6 +12,12 @@ function isPermissionRenameError(error) {
     const code = error.code;
     return code === "EPERM" || code === "EEXIST";
 }
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants;
+const OPEN_READ_FLAGS = syncFs.constants.O_RDONLY | (SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0);
+const OPEN_WRITE_EXCLUSIVE_FLAGS = syncFs.constants.O_WRONLY |
+    syncFs.constants.O_CREAT |
+    syncFs.constants.O_EXCL |
+    (SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0);
 async function sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -26,17 +33,7 @@ async function renameWithRetry(params) {
                 continue;
             }
             if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
-                const stat = await params.fsModule.lstat(params.dest).catch((lstatError) => {
-                    if (lstatError.code === "ENOENT") {
-                        return null;
-                    }
-                    throw lstatError;
-                });
-                if (stat?.isSymbolicLink()) {
-                    throw new Error(`Refusing copy fallback through symlink destination: ${params.dest}`);
-                }
-                await params.fsModule.copyFile(params.src, params.dest);
-                await params.fsModule.unlink(params.src).catch(() => undefined);
+                await copyFallbackReplace(params.fsModule, params.src, params.dest);
                 return { method: "copy-fallback" };
             }
             throw error;
@@ -62,25 +59,7 @@ function renameWithRetrySync(params) {
                 continue;
             }
             if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
-                let stat = null;
-                try {
-                    stat = params.fsModule.lstatSync(params.dest);
-                }
-                catch (lstatError) {
-                    if (lstatError.code !== "ENOENT") {
-                        throw lstatError;
-                    }
-                }
-                if (stat?.isSymbolicLink()) {
-                    throw new Error(`Refusing copy fallback through symlink destination: ${params.dest}`);
-                }
-                params.fsModule.copyFileSync(params.src, params.dest);
-                try {
-                    params.fsModule.unlinkSync(params.src);
-                }
-                catch {
-                    // Best-effort cleanup after fallback replacement.
-                }
+                copyFallbackReplaceSync(params.fsModule, params.src, params.dest);
                 return { method: "copy-fallback" };
             }
             throw error;
@@ -88,6 +67,88 @@ function renameWithRetrySync(params) {
     }
     throw new Error("Atomic rename retry loop exhausted.");
 }
+async function copyFallbackReplace(fsModule, src, dest) {
+    const sourceStat = await fsModule.lstat(src);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new Error(`Refusing copy fallback from non-file source: ${src}`);
+    }
+    const destStat = await fsModule.lstat(dest).catch((lstatError) => {
+        if (lstatError.code === "ENOENT") {
+            return null;
+        }
+        throw lstatError;
+    });
+    if (destStat?.isSymbolicLink()) {
+        throw new Error(`Refusing copy fallback through symlink destination: ${dest}`);
+    }
+    if (destStat) {
+        await fsModule.rm(dest, { force: true });
+    }
+    let sourceHandle = null;
+    let destHandle = null;
+    try {
+        sourceHandle = await fsModule.open(src, OPEN_READ_FLAGS);
+        destHandle = await fsModule.open(dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
+        await destHandle.writeFile(await sourceHandle.readFile());
+    }
+    finally {
+        await destHandle?.close().catch(() => undefined);
+        await sourceHandle?.close().catch(() => undefined);
+    }
+    await fsModule.unlink(src).catch(() => undefined);
+}
+function copyFallbackReplaceSync(fsModule, src, dest) {
+    const sourceStat = fsModule.lstatSync(src);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new Error(`Refusing copy fallback from non-file source: ${src}`);
+    }
+    let destStat = null;
+    try {
+        destStat = fsModule.lstatSync(dest);
+    }
+    catch (lstatError) {
+        if (lstatError.code !== "ENOENT") {
+            throw lstatError;
+        }
+    }
+    if (destStat?.isSymbolicLink()) {
+        throw new Error(`Refusing copy fallback through symlink destination: ${dest}`);
+    }
+    if (destStat) {
+        fsModule.rmSync(dest, { force: true });
+    }
+    let sourceFd;
+    let destFd;
+    try {
+        sourceFd = fsModule.openSync(src, OPEN_READ_FLAGS);
+        destFd = fsModule.openSync(dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
+        fsModule.writeFileSync(destFd, fsModule.readFileSync(sourceFd));
+    }
+    finally {
+        if (destFd !== undefined) {
+            try {
+                fsModule.closeSync(destFd);
+            }
+            catch {
+                // Best-effort close after fallback replacement.
+            }
+        }
+        if (sourceFd !== undefined) {
+            try {
+                fsModule.closeSync(sourceFd);
+            }
+            catch {
+                // Best-effort close after fallback replacement.
+            }
+        }
+    }
+    try {
+        fsModule.unlinkSync(src);
+    }
+    catch {
+        // Best-effort cleanup after fallback replacement.
+    }
+}
 function validateReplaceFilePath(filePath) {
     if (!filePath || filePath.includes("\0")) {
         throw new Error("Atomic replace file path must be non-empty.");
@@ -95,7 +156,8 @@ function validateReplaceFilePath(filePath) {
 }
 function buildReplaceTempPath(filePath, tempPrefix) {
     const dir = path.dirname(filePath);
-    return path.join(dir, `${tempPrefix ?? ".fs-safe-replace"}.${process.pid}.${randomUUID()}.tmp`);
+    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) {
     const defaultMode = options.mode ?? 0o600;