@openclaw/fs-safe 0.6.0 → 0.7.0

package/dist/private-temp-workspace.js

@@ -4,11 +4,18 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileStore, fileStoreSync, } from "./file-store.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { throwFsSafeReadError } from "./read-error.js";
 import { matchRootFileOpenFailure, openRootFileSync, } from "./root-file.js";
 import { registerTempPathForExit, } from "./temp-cleanup.js";
+import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, } from "./temp-workspace-owner.js";
+function resolveTempWorkspaceCleanupSafety(value) {
+    if (value === undefined || value === "compatible")
+        return "compatible";
+    if (value === "require-bounded")
+        return value;
+    throw new TypeError("cleanupSafety must be compatible or require-bounded");
+}
 function sanitizeTempPrefix(prefix) {
     const sanitized = prefix.trim().replace(/[^a-zA-Z0-9._-]/g, "-");
     if (!sanitized || sanitized === "." || sanitized === "..") {
@@ -79,52 +86,47 @@ function ensurePrivateDirectorySync(dir, mode) {
         // Best-effort on platforms that do not enforce POSIX modes.
     }
 }
-async function cleanupWorkspace(dir, identity) {
-    let current;
-    try {
-        current = await fs.lstat(dir, { bigint: true });
-    }
-    catch (error) {
-        return error.code === "ENOENT" ? "missing" : "identity-mismatch";
-    }
-    if (!sameFileIdentityForCleanup(current, identity)) {
-        return "identity-mismatch";
-    }
-    await fs.rm(dir, { recursive: true, force: true });
-    return "removed";
-}
-function cleanupWorkspaceSync(dir, identity) {
-    let current;
-    try {
-        current = fsSync.lstatSync(dir, { bigint: true });
-    }
-    catch (error) {
-        return error.code === "ENOENT" ? "missing" : "identity-mismatch";
-    }
-    if (!sameFileIdentityForCleanup(current, identity)) {
-        return "identity-mismatch";
-    }
-    fsSync.rmSync(dir, { recursive: true, force: true });
-    return "removed";
-}
 async function createTempWorkspace(options) {
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
+    const cleanupSafety = resolveTempWorkspaceCleanupSafety(options.cleanupSafety);
     const requestedRoot = path.resolve(options.rootDir);
     const root = await fs.realpath(requestedRoot).catch(() => requestedRoot);
     await ensurePrivateDirectory(root, dirMode);
-    const dir = await fs.mkdtemp(path.join(root, sanitizeTempPrefix(options.prefix)));
-    await fs.chmod(dir, dirMode).catch(() => undefined);
-    const stat = await fs.lstat(dir, { bigint: true });
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new Error(`Temp workspace must be a directory: ${dir}`);
+    const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety);
+    let dir;
+    let stat;
+    let cleanupOwner;
+    let unregisterTempDir;
+    try {
+        dir = await fs.mkdtemp(path.join(root, sanitizeTempPrefix(options.prefix)));
+        await fs.chmod(dir, dirMode).catch(() => undefined);
+        stat = await fs.lstat(dir, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new Error(`Temp workspace must be a directory: ${dir}`);
+        }
+        if (capability.parent)
+            capability.assertCurrent();
+        cleanupOwner = new TempWorkspaceCleanupOwner(dir, stat, capability);
+        unregisterTempDir = registerTempPathForExit(dir, {
+            cleanupSync: () => cleanupOwner.cleanupSync(),
+        });
     }
+    catch (error) {
+        try {
+            if (cleanupOwner)
+                cleanupOwner.cleanupSync();
+            else
+                capability.close();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
+        }
+        throw error;
+    }
+    const owner = cleanupOwner;
     const identity = { dev: Number(stat.dev), ino: Number(stat.ino) };
-    const cleanupIdentity = { dev: stat.dev, ino: stat.ino };
-    const unregisterTempDir = registerTempPathForExit(dir, {
-        recursive: true,
-        identity: cleanupIdentity,
-    });
+    // Once registered, even a store-construction failure remains exit-cleanable.
     const store = fileStore({ rootDir: dir, private: true, dirMode, mode });
     return {
         dir,
@@ -148,7 +150,7 @@ async function createTempWorkspace(options) {
         },
         cleanup: async () => {
             try {
-                return await cleanupWorkspace(dir, cleanupIdentity);
+                return await owner.cleanup();
             }
             finally {
                 unregisterTempDir();
@@ -156,7 +158,7 @@ async function createTempWorkspace(options) {
         },
         [Symbol.asyncDispose]: async () => {
             try {
-                await cleanupWorkspace(dir, cleanupIdentity);
+                await owner.cleanup();
             }
             finally {
                 unregisterTempDir();
@@ -182,6 +184,7 @@ export async function withTempWorkspace(options, run) {
 export function tempWorkspaceSync(options) {
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
+    const cleanupSafety = resolveTempWorkspaceCleanupSafety(options.cleanupSafety);
     const requestedRoot = path.resolve(options.rootDir);
     let root = requestedRoot;
     try {
@@ -191,23 +194,45 @@ export function tempWorkspaceSync(options) {
         root = requestedRoot;
     }
     ensurePrivateDirectorySync(root, dirMode);
-    const dir = fsSync.mkdtempSync(path.join(root, sanitizeTempPrefix(options.prefix)));
+    const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety);
+    let dir;
+    let stat;
+    let cleanupOwner;
+    let unregisterTempDir;
     try {
-        fsSync.chmodSync(dir, dirMode);
+        dir = fsSync.mkdtempSync(path.join(root, sanitizeTempPrefix(options.prefix)));
+        try {
+            fsSync.chmodSync(dir, dirMode);
+        }
+        catch {
+            // Best-effort on platforms that do not enforce POSIX modes.
+        }
+        stat = fsSync.lstatSync(dir, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new Error(`Temp workspace must be a directory: ${dir}`);
+        }
+        if (capability.parent)
+            capability.assertCurrent();
+        cleanupOwner = new TempWorkspaceCleanupOwner(dir, stat, capability);
+        unregisterTempDir = registerTempPathForExit(dir, {
+            cleanupSync: () => cleanupOwner.cleanupSync(),
+        });
     }
-    catch {
-        // Best-effort on platforms that do not enforce POSIX modes.
-    }
-    const stat = fsSync.lstatSync(dir, { bigint: true });
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new Error(`Temp workspace must be a directory: ${dir}`);
+    catch (error) {
+        try {
+            if (cleanupOwner)
+                cleanupOwner.cleanupSync();
+            else
+                capability.close();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
+        }
+        throw error;
     }
+    const owner = cleanupOwner;
     const identity = { dev: Number(stat.dev), ino: Number(stat.ino) };
-    const cleanupIdentity = { dev: stat.dev, ino: stat.ino };
-    const unregisterTempDir = registerTempPathForExit(dir, {
-        recursive: true,
-        identity: cleanupIdentity,
-    });
+    // Once registered, even a store-construction failure remains exit-cleanable.
     const store = fileStoreSync({ rootDir: dir, private: true, dirMode, mode });
     return {
         dir,
@@ -244,7 +269,7 @@ export function tempWorkspaceSync(options) {
         },
         cleanup: () => {
             try {
-                return cleanupWorkspaceSync(dir, cleanupIdentity);
+                return owner.cleanupSync();
             }
             finally {
                 unregisterTempDir();
@@ -252,7 +277,7 @@ export function tempWorkspaceSync(options) {
         },
         [Symbol.dispose]: () => {
             try {
-                cleanupWorkspaceSync(dir, cleanupIdentity);
+                owner.cleanupSync();
             }
             finally {
                 unregisterTempDir();

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

@@ -1 +1 @@
-{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAI/D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GACpC,cAAc,GACd,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAkBF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AA2ND,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,aAAa,CAAC,EAAE,qCAAqC,CAAC;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4MtC"}
+{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAI/D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GACpC,cAAc,GACd,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAkBF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAsND,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,aAAa,CAAC,EAAE,qCAAqC,CAAC;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4MtC"}

package/dist/publish-file.js

@@ -8,6 +8,7 @@ import { hashFileHandle } from "./file-hash.js";
 import { sameFileIdentity, sameFileIdentityForCleanup, } from "./file-identity.js";
 import { syncNativeFileBestEffort } from "./native-operations.js";
 import { getNativeBinding, requireNativeBinding } from "./native.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { directorySyncFailure, publicationFailure, rememberCreatedTarget, } from "./publish-file-failure.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const HARDLINK_FALLBACK_CODES = new Set([
@@ -29,10 +30,7 @@ export function isHardlinkFallbackError(error) {
     return HARDLINK_FALLBACK_CODES.has(error?.code ?? "");
 }
 function sourceOpenFlags() {
-    return (fsSync.constants.O_RDONLY |
-        (process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
-            ? fsSync.constants.O_NOFOLLOW
-            : 0));
+    return resolveReadOpenFlags();
 }
 function directoryOpenFlags() {
     return (fsSync.constants.O_RDONLY |

package/dist/read-opened-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-opened-file.d.ts","sourceRoot":"","sources":["../src/read-opened-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBtB"}
+{"version":3,"file":"read-opened-file.d.ts","sourceRoot":"","sources":["../src/read-opened-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBtB"}

package/dist/read-opened-file.js

@@ -1,12 +1,14 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 export async function readOpenedFileSafely(params) {
-    if (params.maxBytes !== undefined && params.opened.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${params.opened.stat.size})`);
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
+    if (maxBytes !== undefined && params.opened.stat.size > maxBytes) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got ${params.opened.stat.size})`);
     }
-    const buffer = params.maxBytes === undefined
+    const buffer = maxBytes === undefined
         ? await params.opened.handle.readFile()
-        : await readFileHandleBounded(params.opened.handle, params.maxBytes);
+        : await readFileHandleBounded(params.opened.handle, maxBytes);
     return {
         buffer,
         containment: params.opened.containment,

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;AAY7B,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;AAaD,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,CAyD3C;AA6DD,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,CA6BA;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;AAClD,OAAO,MAAM,MAAM,SAAS,CAAC;AAc7B,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;AAaD,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,CA6D3C;AA2DD,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,CAoCA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwExF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAyE7E"}

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"}