@openclaw/fs-safe 0.1.2 → 0.2.1

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;

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

@@ -1 +1 @@
-{"version":3,"file":"root-impl.d.ts","sourceRoot":"","sources":["../src/root-impl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAsCnD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,oBAAoB,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAChD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,YAAY,EACZ,WAAW,GAAG,UAAU,GAAG,iBAAiB,GAAG,UAAU,CAC1D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;AAEhE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC,GAAG;IACpE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC,GAAG;IAC3E,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG;IAChF,eAAe,CAAC,EAAE,cAAc,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG;IACpD,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;AACpE,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG;IACjD,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,CAAC;AAgCF,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AA0HvD,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3E,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5E,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GACxD,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAClB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GACxD,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/E,MAAM,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,YAAY,CACV,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC/B,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,CACH,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,SAAS,CACP,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CACR,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3F,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACnF,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClF,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAChC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AA6QD,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,YAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAEf;AAiFD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAOtB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAG3F;AA0BD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8EF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAoCjB"}
+{"version":3,"file":"root-impl.d.ts","sourceRoot":"","sources":["../src/root-impl.ts"],"names":[],"mappings":"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"}

package/dist/root-impl.js

@@ -2,16 +2,20 @@ import { randomUUID } from "node:crypto";
 import { constants as fsConstants } 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 { createBoundedReadStream } from "./bounded-read-stream.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { isPinnedPathHelperSpawnError, runPinnedPathHelper } from "./pinned-path.js";
 import { runPinnedCopyHelper, runPinnedWriteHelper } from "./pinned-write.js";
 import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
 import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
 import { helperReaddir, helperStat, runPinnedHelper, } from "./pinned-helper.js";
+import { pathStatFromStats } from "./path-stat.js";
 import { resolveRootPath } from "./root-path.js";
 import { assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, } from "./root-context.js";
 import { isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, } from "./root-errors.js";
@@ -433,24 +437,6 @@ function buildAtomicWriteTempPath(targetPath) {
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
 }
-function createMaxBytesTransform(maxBytes) {
-    let bytes = 0;
-    return new Transform({
-        transform(chunk, _encoding, callback) {
-            const buffer = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
-            bytes += buffer.byteLength;
-            if (bytes > maxBytes) {
-                callback(new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`));
-                return;
-            }
-            callback(null, buffer);
-        },
-    });
-}
-function createBoundedReadStream(opened, maxBytes) {
-    const stream = opened.handle.createReadStream();
-    return maxBytes === undefined ? stream : stream.pipe(createMaxBytesTransform(maxBytes));
-}
 async function writeTempFileForAtomicReplace(params) {
     const tempHandle = await fs.open(params.tempPath, OPEN_WRITE_CREATE_FLAGS, params.mode);
     try {
@@ -567,7 +553,10 @@ async function openWritableFileInRoot(root, params) {
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
     if (params.mkdir !== false) {
-        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        const parentGuard = await createNearestExistingDirectoryGuard(rootReal, path.dirname(resolved));
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            await fs.mkdir(path.dirname(resolved), { recursive: true });
+        });
     }
     let ioPath = resolved;
     try {
@@ -867,8 +856,10 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode)
     catch (err) {
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
+    // resolvePathInRoot already enforces isPathInside, so any actual escape
+    // is rejected upstream.
     const relativeResolved = path.relative(rootReal, resolved);
-    if (relativeResolved.startsWith("..") || path.isAbsolute(relativeResolved)) {
+    if (path.isAbsolute(relativeResolved)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }
     const relativePosix = relativeResolved
@@ -930,9 +921,10 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
         return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
     }
+    const firstSegment = relativeResolved.split(path.sep)[0];
     if (relativeResolved === "" ||
         relativeResolved === "." ||
-        relativeResolved.startsWith("..") ||
+        firstSegment === ".." ||
         path.isAbsolute(relativeResolved)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }
@@ -965,25 +957,17 @@ async function resolvePinnedRootPathInRoot(root, params) {
     };
 }
 async function removePathFallback(resolved) {
-    await fs.rm(resolved.resolved);
+    const guard = await createAsyncDirectoryGuard(path.dirname(resolved.resolved));
+    await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("remove", resolved.resolved);
+    await assertAsyncDirectoryGuard(guard);
+    await ((await fs.lstat(resolved.resolved)).isDirectory() ? fs.rmdir(resolved.resolved) : fs.rm(resolved.resolved));
+    await assertAsyncDirectoryGuard(guard).catch(() => undefined);
 }
 async function mkdirPathFallback(resolved) {
-    await fs.mkdir(resolved.resolved, { recursive: true });
-}
-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,
-    };
+    await mkdirPathComponentsWithGuards({
+        rootReal: resolved.rootReal, targetPath: resolved.resolved,
+        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
+    });
 }
 async function statPathFallback(root, relativePath) {
     const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
@@ -1080,6 +1064,11 @@ async function movePathFallback(root, params) {
             }
         }
     }
+    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved));
+    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved));
+    await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", target.resolved);
+    await assertAsyncDirectoryGuard(sourceParentGuard);
+    await assertAsyncDirectoryGuard(targetParentGuard);
     try {
         await fs.rename(source.resolved, target.resolved);
     }
@@ -1096,6 +1085,7 @@ async function movePathFallback(root, params) {
         }
         throw error;
     }
+    await assertAsyncDirectoryGuard(targetParentGuard).catch(() => undefined);
 }
 async function writeFileFallback(root, params) {
     if (params.overwrite === false) {
@@ -1111,6 +1101,7 @@ async function writeFileFallback(root, params) {
     const destinationPath = target.realPath;
     const mode = params.mode ?? (target.stat.mode & 0o777);
     await target.handle.close().catch(() => { });
+    const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
     let tempPath = null;
     let unregisterTempPath = null;
     try {
@@ -1122,7 +1113,10 @@ async function writeFileFallback(root, params) {
             encoding: params.encoding,
             mode: mode || 0o600,
         });
-        await fs.rename(tempPath, destinationPath);
+        const commitTempPath = tempPath;
+        await withAsyncDirectoryGuards([destinationGuard], async () => {
+            await fs.rename(commitTempPath, destinationPath);
+        });
         tempPath = null;
         unregisterTempPath();
         unregisterTempPath = null;
@@ -1160,20 +1154,32 @@ async function writeMissingFileFallback(root, params) {
     if (params.mkdir !== false) {
         await fs.mkdir(path.dirname(resolved), { recursive: true });
     }
-    let handle = null;
+    const parentGuard = await createAsyncDirectoryGuard(path.dirname(resolved));
     let created = false;
     try {
-        handle = await fs.open(resolved, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
-        created = true;
-        if (typeof params.data === "string") {
-            await handle.writeFile(params.data, params.encoding ?? "utf8");
-        }
-        else {
-            await handle.writeFile(params.data);
-        }
-        const writtenStat = await handle.stat();
+        const { handle, writtenStat } = await withAsyncDirectoryGuards([parentGuard], async () => {
+            const handle = await fs.open(resolved, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
+            created = true;
+            try {
+                if (typeof params.data === "string") {
+                    await handle.writeFile(params.data, params.encoding ?? "utf8");
+                }
+                else {
+                    await handle.writeFile(params.data);
+                }
+                return { handle, writtenStat: await handle.stat() };
+            }
+            catch (error) {
+                await handle.close().catch(() => undefined);
+                throw error;
+            }
+        }, {
+            onPostGuardFailure: async ({ handle }) => {
+                created = false; // Parent is untrusted now; skip outer path cleanup by name.
+                await handle.close().catch(() => undefined);
+            },
+        });
         await handle.close();
-        handle = null;
         await verifyAtomicWriteResult({
             root,
             targetPath: resolved,
@@ -1190,7 +1196,6 @@ async function writeMissingFileFallback(root, params) {
         throw err;
     }
     finally {
-        await handle?.close().catch(() => undefined);
         if (created) {
             await fs.rm(resolved, { force: true }).catch(() => undefined);
         }
@@ -1215,6 +1220,7 @@ async function copyFileFallback(root, params, source) {
         const mode = params.mode ?? (target.stat.mode & 0o777);
         await target.handle.close().catch(() => { });
         targetClosedByUs = true;
+        const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
         tempPath = buildAtomicWriteTempPath(destinationPath);
         unregisterTempPath = registerTempPathForExit(tempPath);
         tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, mode || 0o600);
@@ -1233,7 +1239,10 @@ async function copyFileFallback(root, params, source) {
             tempClosedByStream = true;
         }
         tempHandle = null;
-        await fs.rename(tempPath, destinationPath);
+        const commitTempPath = tempPath;
+        await withAsyncDirectoryGuards([destinationGuard], async () => {
+            await fs.rename(commitTempPath, destinationPath);
+        });
         tempPath = null;
         unregisterTempPath();
         unregisterTempPath = null;

package/dist/safe-path-segment.d.ts

@@ -0,0 +1,9 @@
+export type SafePathSegmentOptions = {
+    allowDotPrefix?: boolean;
+    label?: string;
+};
+export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
+export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
+export declare function sanitizeSafePathSegment(value: string, fallback: string, options?: SafePathSegmentOptions): string;
+export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;
+//# sourceMappingURL=safe-path-segment.d.ts.map

package/dist/safe-path-segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-path-segment.d.ts","sourceRoot":"","sources":["../src/safe-path-segment.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAaT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAUR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAWR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAeR"}

package/dist/safe-path-segment.js

@@ -0,0 +1,51 @@
+import { FsSafeError } from "./errors.js";
+const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+export function isSafePathSegment(segment, options = {}) {
+    return (segment !== "" &&
+        segment !== "." &&
+        segment !== ".." &&
+        !segment.includes("/") &&
+        !segment.includes("\\") &&
+        !segment.includes("\0") &&
+        (options.allowDotPrefix === true || !segment.startsWith(".")) &&
+        (options.allowDotPrefix === true
+            ? SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN.test(segment)
+            : SAFE_PATH_SEGMENT_PATTERN.test(segment)));
+}
+export function assertSafePathSegment(segment, options = {}) {
+    // Validate the exact value callers will later join into paths; trimming here
+    // would let whitespace-padded ids pass and then be used verbatim.
+    if (!isSafePathSegment(segment, options)) {
+        throw new FsSafeError("invalid-path", `${options.label ?? "path segment"} must be a safe path segment`);
+    }
+    return segment;
+}
+export function sanitizeSafePathSegment(value, fallback, options = {}) {
+    const sanitized = value
+        .trim()
+        .replace(/[\\/]+/g, "-")
+        .replace(/\0/g, "")
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (isSafePathSegment(sanitized, options)) {
+        return sanitized;
+    }
+    return assertSafePathSegment(fallback, { ...options, label: "fallback path segment" });
+}
+export function assertSafePathPrefix(prefix, options = {}) {
+    // Prefixes are often derived from safe filenames. Normalize harmless
+    // filename characters first, but still reject real path-control bytes.
+    if (prefix.includes("/") || prefix.includes("\\") || prefix.includes("\0")) {
+        return assertSafePathSegment(prefix, {
+            allowDotPrefix: true,
+            ...options,
+            label: options.label ?? "path prefix",
+        });
+    }
+    return assertSafePathSegment(prefix.replace(/[^A-Za-z0-9._-]+/g, "-"), {
+        allowDotPrefix: true,
+        ...options,
+        label: options.label ?? "path prefix",
+    });
+}

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAuGF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoFD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDhB"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAqHF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoFD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhB"}

package/dist/secret-file.js

@@ -2,7 +2,9 @@ import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
@@ -34,12 +36,28 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
             message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };
     }
-    if (options.rejectSymlink && previewStat.isSymbolicLink()) {
-        return {
-            ok: false,
-            code: "symlink",
-            message: `${label} file at ${resolvedPath} must not be a symlink.`,
-        };
+    if (previewStat.isSymbolicLink()) {
+        if (!options.rejectSymlink) {
+            try {
+                previewStat = fs.statSync(resolvedPath);
+            }
+            catch (error) {
+                const normalized = normalizeSecretReadError(error);
+                return {
+                    ok: false,
+                    code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+                    error: normalized,
+                    message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
+                };
+            }
+        }
+        else {
+            return {
+                ok: false,
+                code: "symlink",
+                message: `${label} file at ${resolvedPath} must not be a symlink.`,
+            };
+        }
     }
     if (!previewStat.isFile()) {
         return {
@@ -188,6 +206,7 @@ export async function writeSecretFileAtomic(params) {
     const resolvedRootReal = await fsp.realpath(resolvedRoot);
     const parentDir = await fsp.realpath(intendedParentDir);
     assertRealPathWithinRoot(resolvedRootReal, parentDir);
+    const parentGuard = await createAsyncDirectoryGuard(parentDir);
     const fileName = path.basename(resolvedFile);
     const finalFilePath = path.join(parentDir, fileName);
     try {
@@ -220,7 +239,9 @@ export async function writeSecretFileAtomic(params) {
         if (refreshedParentReal !== parentDir) {
             throw new Error(`Private secret parent directory changed during write for ${finalFilePath}.`);
         }
-        await fsp.rename(tempPath, finalFilePath);
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            await fsp.rename(tempPath, finalFilePath);
+        });
         createdTemp = false;
         await enforcePrivatePathMode(finalFilePath, mode, "file");
     }

package/dist/sibling-temp.d.ts

@@ -4,6 +4,7 @@ export type WriteSiblingTempFileOptions<T> = {
     resolveFinalPath: (result: T) => string;
     tempPrefix?: string;
     dirMode?: number;
+    chmodDir?: boolean;
     mode?: number;
     syncTempFile?: boolean;
     syncParentDir?: boolean;

package/dist/sibling-temp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAuCF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAoCxC;AAeD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA0CF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAyCxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ChB"}

package/dist/sibling-temp.js

@@ -1,12 +1,20 @@
 import crypto, { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { sanitizeUntrustedFileName } from "./filename.js";
 import { root } from "./root.js";
+import { assertSafePathPrefix } from "./safe-path-segment.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 import { serializePathWrite } from "./write-queue.js";
 function buildTempPath(dir, tempPrefix) {
-    return path.join(dir, `${tempPrefix ?? ".fs-safe-stream"}.${process.pid}.${randomUUID()}.tmp`);
+    const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
+        label: "sibling temp prefix",
+    });
+    return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
 }
 async function syncFileBestEffort(filePath) {
     const handle = await fs.open(filePath, "r+");
@@ -45,7 +53,10 @@ function assertFinalPathIsSibling(dir, filePath) {
 export async function writeSiblingTempFile(options) {
     const dir = path.resolve(options.dir);
     await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
-    await fs.chmod(dir, options.dirMode ?? 0o700).catch(() => undefined);
+    if (options.chmodDir !== false) {
+        await fs.chmod(dir, options.dirMode ?? 0o700).catch(() => undefined);
+    }
+    const dirGuard = await createAsyncDirectoryGuard(dir);
     const tempPath = buildTempPath(dir, options.tempPrefix);
     const unregisterTempPath = registerTempPathForExit(tempPath);
     let tempExists = false;
@@ -61,7 +72,9 @@ export async function writeSiblingTempFile(options) {
         const filePath = path.resolve(options.resolveFinalPath(result));
         assertFinalPathIsSibling(dir, filePath);
         await serializePathWrite(filePath, async () => {
-            await fs.rename(tempPath, filePath);
+            await withAsyncDirectoryGuards([dirGuard], async () => {
+                await fs.rename(tempPath, filePath);
+            });
             tempExists = false;
             unregisterTempPath();
             if (options.mode !== undefined) {
@@ -82,8 +95,11 @@ export async function writeSiblingTempFile(options) {
 }
 function buildSiblingTempPath(params) {
     const id = crypto.randomUUID();
+    const safePrefix = assertSafePathPrefix(params.tempPrefix, {
+        label: "sibling temp prefix",
+    });
     const safeTail = sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName);
-    return path.join(path.dirname(params.targetPath), `${params.tempPrefix}${id}-${safeTail}.part`);
+    return path.join(path.dirname(params.targetPath), `${safePrefix}${id}-${safeTail}.part`);
 }
 export async function writeViaSiblingTempPath(params) {
     const rootDir = await fs
@@ -101,19 +117,28 @@ export async function writeViaSiblingTempPath(params) {
         path.isAbsolute(relativeTargetPath)) {
         throw new Error("Target path is outside the allowed root");
     }
+    const rootGuard = await createAsyncDirectoryGuard(rootDir);
+    const tempDir = await fs.mkdtemp(path.join(resolveSecureTempRoot({
+        fallbackPrefix: "fs-safe-output",
+        unsafeFallbackLabel: "sibling temp output dir",
+        warn: () => undefined,
+    }), "fs-safe-output-"));
     const tempPath = buildSiblingTempPath({
-        targetPath,
+        targetPath: path.join(tempDir, path.basename(targetPath)),
         fallbackFileName: params.fallbackFileName ?? "output.bin",
         tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
     });
-    const unregisterTempPath = registerTempPathForExit(tempPath);
+    const unregisterTempPath = registerTempPathForExit(tempDir, { recursive: true });
     try {
+        await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
         await params.writeTemp(tempPath);
+        await assertAsyncDirectoryGuard(rootGuard);
         const targetRoot = await root(rootDir);
         await targetRoot.copyIn(relativeTargetPath, tempPath, { mkdir: false });
+        await assertAsyncDirectoryGuard(rootGuard);
     }
     finally {
-        await fs.rm(tempPath, { force: true }).catch(() => { });
+        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { });
         unregisterTempPath();
     }
 }