@openclaw/fs-safe 0.6.0 → 0.7.1

package/dist/replace-file.js

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
-import syncFs from "node:fs";
+import syncFs, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertDestinationHardlinkPolicy, assertDestinationHardlinkPolicySync, copyFallbackReplace, copyFallbackReplaceSync, } from "./replace-file-copy-fallback.js";
 import { applyDirectoryMode, applyDirectoryModeSync, writeTempFile, writeTempFileSync, } from "./replace-file-descriptor.js";
+import { atomicExpectedContentHash, validateRenameIdentity, withAtomicRenameIdentityLock, withAtomicRenameIdentityLockSync, } from "./replace-file-rename-policy.js";
+import { AsyncAtomicTempOwner, SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
-import { registerTempPathForExit } from "./temp-cleanup.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 function isRetryableRenameError(error) {
@@ -17,6 +18,7 @@ function isPermissionRenameError(error) {
 }
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
+        await params.assertSourceCurrent();
         try {
             await params.fsModule.rename(params.src, params.dest);
             return { method: "rename" };
@@ -34,6 +36,7 @@ async function renameWithRetry(params) {
                     destinationHardlinks: params.destinationHardlinks,
                     restore: params.copyFallbackRestore,
                     maxRestoreBytes: params.maxRestoreBytes,
+                    expectedSourceIdentity: params.sourceIdentity,
                     sync: params.syncFallback,
                 });
                 return { method: "copy-fallback" };
@@ -45,6 +48,7 @@ async function renameWithRetry(params) {
 }
 function renameWithRetrySync(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
+        params.assertSourceCurrent();
         try {
             params.fsModule.renameSync(params.src, params.dest);
             return { method: "rename" };
@@ -62,6 +66,7 @@ function renameWithRetrySync(params) {
                     destinationHardlinks: params.destinationHardlinks,
                     restore: params.copyFallbackRestore,
                     maxRestoreBytes: params.maxRestoreBytes,
+                    expectedSourceIdentity: params.sourceIdentity,
                     fchmodSync: params.fchmodSync,
                     sync: params.syncFallback,
                 });
@@ -158,26 +163,20 @@ function syncDirectoryBestEffortSync(fsModule, dirPath) {
         }
     }
 }
-async function cleanupTempFile(params) {
-    const cleanupError = await params.fsModule
-        .rm(params.tempPath, { force: true })
-        .catch((error) => error);
-    if (!cleanupError)
-        return true;
-    if (params.throwOnCleanupError) {
-        if (params.originalError !== undefined) {
-            throw new Error(`Atomic file replace failed (${String(params.originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: params.originalError });
-        }
-        throw cleanupError;
-    }
-    return false;
-}
 export async function replaceFileAtomic(options) {
     const filePath = options.filePath;
     validateReplaceFilePath(filePath);
     validateRestoreOptions(options);
+    validateRenameIdentity(options.renameIdentity);
     return await serializePathWrite(path.resolve(filePath), async () => {
-        return await replaceFileAtomicUnserialized(options);
+        if (options.renameIdentity !== "verify-content-with-lock") {
+            return await replaceFileAtomicUnserialized(options);
+        }
+        await (options.fileSystem?.promises ?? fs).mkdir(path.dirname(filePath), {
+            recursive: true,
+            mode: options.dirMode ?? 0o700,
+        });
+        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options));
     });
 }
 async function replaceFileAtomicUnserialized(options) {
@@ -186,24 +185,27 @@ async function replaceFileAtomicUnserialized(options) {
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
     const mode = await resolveMode(options);
+    const expectedHash = atomicExpectedContentHash(options.renameIdentity, options.content);
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
-    const unregisterTempPath = registerTempPathForExit(tempPath);
-    let tempExists = false;
+    const tempOwner = new AsyncAtomicTempOwner(tempPath);
     let originalError;
     try {
         await fsModule.mkdir(dir, { recursive: true, mode: dirMode });
         await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
-        tempExists = true;
-        unregisterTempPath.setIdentity(await writeTempFile({
+        tempOwner.start();
+        tempOwner.adopt(await writeTempFile({
             fsModule,
             tempPath,
             content: options.content,
             mode,
             sync: options.syncTempFile === true,
+            onIdentity: tempOwner.onIdentity,
         }));
+        await tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
             await options.beforeRename({ filePath, tempPath });
         }
+        await tempOwner.assertCurrent(fsModule);
         await assertDestinationHardlinkPolicy(fsModule, filePath, options.destinationHardlinks);
         const result = await renameWithRetry({
             fsModule,
@@ -215,15 +217,23 @@ async function replaceFileAtomicUnserialized(options) {
             copyFallbackRestore: options.copyFallbackRestore ?? "none",
             maxRestoreBytes: options.maxRestoreBytes,
             destinationHardlinks: options.destinationHardlinks,
+            sourceIdentity: tempOwner.identity,
+            assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             syncFallback: options.syncTempFile === true,
         });
         if (result.method === "rename") {
-            tempExists = false;
-            unregisterTempPath();
+            tempOwner.markRenamed();
+            await tempOwner.assertPublished(fsModule, filePath, expectedHash);
+        }
+        else {
+            await tempOwner.assertCurrent(fsModule);
         }
         if (options.syncParentDir) {
             await syncDirectoryBestEffort(fsModule, dir);
         }
+        if (result.method === "rename") {
+            await tempOwner.assertPublished(fsModule, filePath, expectedHash);
+        }
         return result;
     }
     catch (error) {
@@ -231,27 +241,34 @@ async function replaceFileAtomicUnserialized(options) {
         throw error;
     }
     finally {
-        let tempRemoved = !tempExists;
-        if (tempExists) {
-            tempRemoved = await cleanupTempFile({
-                fsModule,
-                tempPath,
-                originalError,
-                throwOnCleanupError: options.throwOnCleanupError === true,
-            });
-        }
-        if (tempRemoved)
-            unregisterTempPath();
+        await tempOwner.finish({
+            fsModule,
+            originalError,
+            throwOnCleanupError: options.throwOnCleanupError === true,
+        });
     }
 }
 export function replaceFileAtomicSync(options) {
     const filePath = options.filePath;
     validateReplaceFilePath(filePath);
     validateRestoreOptions(options);
+    validateRenameIdentity(options.renameIdentity);
+    if (options.renameIdentity !== "verify-content-with-lock") {
+        return replaceFileAtomicSyncUnserialized(options);
+    }
+    (options.fileSystem ?? syncFs).mkdirSync(path.dirname(filePath), {
+        recursive: true,
+        mode: options.dirMode ?? 0o700,
+    });
+    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options));
+}
+function replaceFileAtomicSyncUnserialized(options) {
+    const filePath = options.filePath;
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
     const mode = resolveModeSync(options);
+    const expectedHash = atomicExpectedContentHash(options.renameIdentity, options.content);
     const fchmodSync = options.fileSystem?.fchmodSync ?? (options.fileSystem === undefined ? syncFs.fchmodSync : undefined);
     if (!fchmodSync &&
         (options.mode !== undefined ||
@@ -260,24 +277,26 @@ export function replaceFileAtomicSync(options) {
         throw missingFchmodSyncError();
     }
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
-    const unregisterTempPath = registerTempPathForExit(tempPath);
-    let tempExists = false;
+    const tempOwner = new SyncAtomicTempOwner(tempPath);
     let originalError;
     try {
         fsModule.mkdirSync(dir, { recursive: true, mode: dirMode });
         applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
-        tempExists = true;
-        unregisterTempPath.setIdentity(writeTempFileSync({
+        tempOwner.start();
+        tempOwner.adopt(writeTempFileSync({
             fsModule,
             tempPath,
             content: options.content,
             mode,
             fchmodSync,
             sync: options.syncTempFile === true,
+            onIdentity: tempOwner.onIdentity,
         }));
+        tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
             options.beforeRename({ filePath, tempPath });
         }
+        tempOwner.assertCurrent(fsModule);
         assertDestinationHardlinkPolicySync(fsModule, filePath, options.destinationHardlinks);
         const result = renameWithRetrySync({
             fsModule,
@@ -289,16 +308,24 @@ export function replaceFileAtomicSync(options) {
             copyFallbackRestore: options.copyFallbackRestore ?? "none",
             maxRestoreBytes: options.maxRestoreBytes,
             destinationHardlinks: options.destinationHardlinks,
+            sourceIdentity: tempOwner.identity,
+            assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             fchmodSync,
             syncFallback: options.syncTempFile === true,
         });
         if (result.method === "rename") {
-            tempExists = false;
-            unregisterTempPath();
+            tempOwner.markRenamed();
+            tempOwner.assertPublished(fsModule, filePath, expectedHash);
+        }
+        else {
+            tempOwner.assertCurrent(fsModule);
         }
         if (options.syncParentDir) {
             syncDirectoryBestEffortSync(fsModule, dir);
         }
+        if (result.method === "rename") {
+            tempOwner.assertPublished(fsModule, filePath, expectedHash);
+        }
         return result;
     }
     catch (error) {
@@ -306,23 +333,10 @@ export function replaceFileAtomicSync(options) {
         throw error;
     }
     finally {
-        let tempRemoved = !tempExists;
-        if (tempExists) {
-            try {
-                fsModule.rmSync(tempPath, { force: true });
-                tempRemoved = true;
-            }
-            catch (cleanupError) {
-                if (options.throwOnCleanupError) {
-                    if (originalError !== undefined) {
-                        throw new Error(`Atomic file replace failed (${String(originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: originalError });
-                    }
-                    throw cleanupError;
-                }
-                // The temp file is best-effort cleanup after write failure.
-            }
-        }
-        if (tempRemoved)
-            unregisterTempPath();
+        tempOwner.finish({
+            fsModule,
+            originalError,
+            throwOnCleanupError: options.throwOnCleanupError === true,
+        });
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"root-impl.d.ts","sourceRoot":"","sources":["../src/root-impl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"root-impl.d.ts","sourceRoot":"","sources":["../src/root-impl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,KAAK,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAW7D,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAyB9E,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAY,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAMpF,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,kCAAkC,EAAE,MAAM,sBAAsB,CAAC;AAC1E,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,oBAAoB,CAAC;IAClC,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,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,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,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,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,gBAAgB,CAAC,GAAG;IACzG,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG;IAC7F,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG;IAClG,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;AAEF,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AACpE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AA6BnE,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAwJvD,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,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,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,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,qBAAqB,CAAC,aAAa,CAAC,CAAC;CAC5F;AAiSD,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,YAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAGf;AA6ED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAQtB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAG3F;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,oBAAoB,CAAC;IAClC,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"}

package/dist/root-impl.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./fsync.js";
@@ -10,6 +11,7 @@ import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { assertMutationNotDenied, mergeDenyMutationPolicies, } from "./deny-mutations.js";
 import { resolveOpenedFileRealPathForFd, resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
+import { openedPathResolutionError, recordFileOpenFailure, recordOpenedFileFailure, recordPreOpenFileChange } from "./opened-file-failure.js";
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy, } from "./pinned-write.js";
 import { getNativeBinding } from "./native.js";
 import { validatePinnedOperationPayload } from "./pinned-operation.js";
@@ -101,25 +103,15 @@ async function openVerifiedLocalFile(filePath, options) {
     if (preOpenStat) {
         await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
     }
+    const openFlags = options?.symlinks === "follow-within-root"
+        ? OPEN_READ_FOLLOW_FLAGS
+        : OPEN_READ_FLAGS;
+    await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
     let handle;
     try {
-        const openFlags = options?.symlinks === "follow-within-root"
-            ? OPEN_READ_FOLLOW_FLAGS
-            : OPEN_READ_FLAGS;
-        await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
-        handle = await fs.open(filePath, openFlags);
-        try {
-            await fsSafeTestHooks?.afterOpen?.(filePath, handle);
-        }
-        catch (err) {
-            await handle.close().catch(() => { });
-            throw err;
-        }
+        handle = await fs.open(filePath, openFlags).catch((error) => recordFileOpenFailure(isNotFoundPathError(error) ? fileNotFoundError() : error, filePath));
     }
     catch (err) {
-        if (isNotFoundPathError(err)) {
-            throw fileNotFoundError();
-        }
         if (isSymlinkOpenError(err)) {
             throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
         }
@@ -130,16 +122,35 @@ async function openVerifiedLocalFile(filePath, options) {
         throw err;
     }
     try {
+        await fsSafeTestHooks?.afterOpen?.(filePath, handle);
         const stat = await handle.stat();
         if (!stat.isFile()) {
             throw new FsSafeError("not-file", "not a file");
         }
         // Keep numeric Stats for the public receipt, never for identity verification.
-        const identity = await inspectFileIdentity(() => handle.stat({ bigint: true }), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined);
+        let openedIdentity;
+        const identity = await inspectFileIdentity(async () => (openedIdentity = await handle.stat({ bigint: true })), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined).catch(async (error) => {
+            if ([0, 1].includes(stat.nlink)) {
+                await recordPreOpenFileChange(error, handle, filePath, preOpenStat, openedIdentity);
+            }
+            throw error;
+        });
         if (options?.hardlinks === "reject" && stat.nlink > 1) {
             throw hardlinkedPathNotAllowedError();
         }
-        await inspectFileIdentity(async () => {
+        const inspectPathIdentity = async (inspect) => {
+            try {
+                return await inspectFileIdentity(inspect, identity);
+            }
+            catch (error) {
+                const failure = isNotFoundPathError(error) ? openedPathResolutionError(fileNotFoundError()) : error;
+                if (stat.nlink <= 1 && (!preOpenStat || preOpenStat.nlink <= 1n)) {
+                    await recordOpenedFileFailure(failure, handle, filePath, identity);
+                }
+                throw failure;
+            }
+        };
+        await inspectPathIdentity(async () => {
             const pathStat = options?.symlinks === "follow-within-root"
                 ? await fs.stat(filePath, { bigint: true })
                 : await fs.lstat(filePath, { bigint: true });
@@ -147,25 +158,26 @@ async function openVerifiedLocalFile(filePath, options) {
                 throw new FsSafeError("symlink", "symlink not allowed");
             }
             return pathStat;
-        }, identity);
-        const realPath = await resolveOpenedFileRealPathForFd(handle.fd, identity, filePath);
-        await inspectFileIdentity(async () => {
+        });
+        await fsSafeTestHooks?.afterOpenedPathIdentityCheck?.(filePath, handle);
+        const realPath = await resolveOpenedFileRealPathForFd(handle.fd, identity, filePath)
+            .catch(async (error) => {
+            if (stat.nlink <= 1 && (!preOpenStat || preOpenStat.nlink <= 1n)) {
+                await recordOpenedFileFailure(error, handle, filePath, identity);
+            }
+            throw error;
+        });
+        await inspectPathIdentity(async () => {
             const realStat = await fs.stat(realPath, { bigint: true });
             if (options?.hardlinks === "reject" && realStat.nlink > 1n) {
                 throw hardlinkedPathNotAllowedError();
             }
             return realStat;
-        }, identity);
-        return openResult({ handle, realPath, stat });
+        });
+        return { opened: openResult({ handle, realPath, stat }), identity };
     }
     catch (err) {
         await handle.close().catch(() => { });
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        if (isNotFoundPathError(err)) {
-            throw fileNotFoundError();
-        }
         throw err;
     }
 }
@@ -210,8 +222,7 @@ class RootHandle {
     async read(relativePath, options = {}) {
         return await readFileInRoot(this.context, {
             relativePath,
-            ...readDefaults(this.defaults),
-            ...options,
+            ...mergeReadOptions(this.defaults, options),
         });
     }
     async readBytes(relativePath, options = {}) {
@@ -227,8 +238,7 @@ class RootHandle {
     async readAbsolute(filePath, options = {}) {
         return await readPathInRoot(this.context, {
             filePath,
-            ...readDefaults(this.defaults),
-            ...options,
+            ...mergeReadOptions(this.defaults, options),
         });
     }
     reader(options = {}) {
@@ -313,13 +323,14 @@ class RootHandle {
     }
     async copyIn(relativePath, sourcePath, options = {}) {
         assertValidRootDestinationPath(relativePath);
+        const { maxBytes, ...copyOptions } = this.mutationOptions(options);
         await copyFileInRoot(this.context, {
             sourcePath,
             relativePath,
-            maxBytes: this.defaults.maxBytes,
+            maxBytes: normalizeMaxBytes(maxBytes, { defaultValue: this.defaults.maxBytes }),
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
-            ...this.mutationOptions(options),
+            ...copyOptions,
         });
     }
     async exists(relativePath) {
@@ -369,12 +380,24 @@ class RootHandle {
 function readDefaults(defaults) {
     return {
         hardlinks: defaults.hardlinks,
-        maxBytes: defaults.maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
+        maxBytes: normalizeMaxBytes(defaults.maxBytes, { defaultValue: DEFAULT_ROOT_MAX_BYTES }),
         nonBlockingRead: defaults.nonBlockingRead,
         symlinks: defaults.symlinks,
     };
 }
+function mergeReadOptions(defaults, options) {
+    const merged = readDefaults(defaults);
+    if (options.hardlinks !== undefined)
+        merged.hardlinks = options.hardlinks;
+    merged.maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: merged.maxBytes });
+    if (options.nonBlockingRead !== undefined)
+        merged.nonBlockingRead = options.nonBlockingRead;
+    if (options.symlinks !== undefined)
+        merged.symlinks = options.symlinks;
+    return merged;
+}
 export async function root(rootDir, defaults = {}) {
+    normalizeMaxBytes(defaults.maxBytes);
     return new RootHandle(await resolveRootContext(rootDir), defaults);
 }
 async function openFileInRoot(root, params) {
@@ -383,19 +406,10 @@ async function openFileInRoot(root, params) {
         rejectUnsafeDeviceReads: true,
         rejectSymlinks: params.symlinks !== "follow-within-root",
     });
-    let opened;
-    try {
-        opened = await openVerifiedLocalFile(resolved, {
-            nonBlockingRead: params.nonBlockingRead,
-            symlinks: params.symlinks,
-        });
-    }
-    catch (err) {
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        throw err;
-    }
+    const { opened } = await openVerifiedLocalFile(resolved, {
+        nonBlockingRead: params.nonBlockingRead,
+        symlinks: params.symlinks,
+    });
     if (params.hardlinks !== "allow" && opened.stat.nlink > 1) {
         await opened.handle.close().catch(() => { });
         throw hardlinkedPathNotAllowedError();
@@ -430,9 +444,10 @@ async function readPathInRoot(root, params) {
     });
 }
 export async function readLocalFileSafely(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
     const opened = await openLocalFileSafely({ filePath: params.filePath });
     try {
-        return await readOpenedFileSafely({ opened, maxBytes: params.maxBytes });
+        return await readOpenedFileSafely({ opened, maxBytes });
     }
     finally {
         await opened.handle.close().catch(() => { });
@@ -440,15 +455,13 @@ export async function readLocalFileSafely(params) {
 }
 export async function openLocalFileSafely(params) {
     assertNoNulPathInput(params.filePath, "file path contains a NUL byte");
-    return await openVerifiedLocalFile(params.filePath);
+    return (await openVerifiedLocalFile(params.filePath)).opened;
 }
 function emitWriteBoundaryWarning(reason) {
     logWarn(`security: fs-safe write boundary warning (${reason})`);
 }
 function buildAtomicWriteTempPath(targetPath) {
-    const dir = path.dirname(targetPath);
-    const base = path.basename(targetPath);
-    return path.join(dir, `.${base}.${process.pid}.${randomUUID()}.tmp`);
+    return path.join(path.dirname(targetPath), `.fs-safe-${randomUUID()}.tmp`);
 }
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
@@ -687,7 +700,7 @@ async function writeFileInRoot(root, params) {
             await writeFileFallback(root, params);
             return;
         }
-        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations, params.overwrite);
         await serializePathWrite(pinned.targetPath, async () => {
             await commitPinnedWriteInRoot(root, pinned, params);
         });
@@ -743,7 +756,7 @@ async function commitPinnedWriteInRoot(root, pinned, params) {
 async function copyFileInRoot(root, params) {
     assertValidRootRelativePath(params.relativePath);
     assertNoNulPathInput(params.sourcePath, "source path contains a NUL byte");
-    const source = await openVerifiedLocalFile(params.sourcePath, {
+    const { opened: source, identity: sourceIdentity } = await openVerifiedLocalFile(params.sourcePath, {
         hardlinks: params.sourceHardlinks,
     });
     if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
@@ -754,7 +767,7 @@ async function copyFileInRoot(root, params) {
         await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
             const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
             await serializePathWrite(pinned.targetPath, async () => {
-                await assertCopySourceCurrent(source);
+                await assertCopySourceCurrent(source, sourceIdentity);
                 let identity;
                 try {
                     identity = await runPinnedWriteHelper({
@@ -773,7 +786,7 @@ async function copyFileInRoot(root, params) {
                     throw normalizePinnedWriteError(error);
                 }
                 try {
-                    await assertCopySourcePathCurrent(source);
+                    await assertCopySourcePathCurrent(source, sourceIdentity);
                 }
                 catch (error) {
                     await removePathIfIdentityUnchanged(pinned.targetPath, identity).catch(() => undefined);
@@ -786,18 +799,18 @@ async function copyFileInRoot(root, params) {
         await source.handle.close().catch(() => { });
     }
 }
-async function assertCopySourceCurrent(source) {
-    const opened = await source.handle.stat();
-    if (!sameFileIdentity(opened, source.stat)) {
-        throw new FsSafeError("path-mismatch", "copy source descriptor changed");
-    }
-    await assertCopySourcePathCurrent(source);
+async function assertCopySourceCurrent(source, identity) {
+    await inspectFileIdentity(() => source.handle.stat({ bigint: true }), identity);
+    await assertCopySourcePathCurrent(source, identity);
 }
-async function assertCopySourcePathCurrent(source) {
-    const current = await fs.lstat(source.realPath);
-    if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, source.stat)) {
-        throw new FsSafeError("path-mismatch", "copy source path changed");
-    }
+async function assertCopySourcePathCurrent(source, identity) {
+    await inspectFileIdentity(async () => {
+        const current = await fs.lstat(source.realPath, { bigint: true });
+        if (current.isSymbolicLink() || !current.isFile()) {
+            throw new FsSafeError("path-mismatch", "copy source path changed");
+        }
+        return current;
+    }, identity);
 }
 async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
@@ -809,7 +822,7 @@ async function removePathIfIdentityUnchanged(targetPath, identity) {
         await fs.rm(targetPath);
     });
 }
-async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations) {
+async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations, overwrite = true) {
     const { rootReal, rootWithSep, resolved } = await resolveGuardedWritePathInRoot(root, {
         relativePath,
         denyMutations,
@@ -827,22 +840,40 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode,
     if (!basename || basename === "." || basename === "/") {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
+    // Exclusive publication cannot inherit an existing file's mode. Keep type
+    // and alias checks, but never open a competing owner's record just to reject it.
+    if (!overwrite) {
+        try {
+            const existing = await fs.stat(resolved);
+            if (!existing.isFile())
+                throw new FsSafeError("not-file", "not a file");
+            if (existing.nlink > 1)
+                throw hardlinkedPathNotAllowedError();
+            throw new FsSafeError("already-exists", "file already exists");
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+        }
+    }
     let mode = requestedMode ?? 0o600;
     try {
-        const opened = await openFileInRoot(root, {
-            relativePath,
-            hardlinks: "reject",
-            nonBlockingRead: true,
-            symlinks: "follow-within-root",
-        });
-        try {
-            mode = requestedMode ?? (opened.stat.mode & 0o777);
-            if (!isPathInside(rootWithSep, opened.realPath)) {
-                throw outsideWorkspaceError();
+        if (overwrite) {
+            const opened = await openFileInRoot(root, {
+                relativePath,
+                hardlinks: "reject",
+                nonBlockingRead: true,
+                symlinks: "follow-within-root",
+            });
+            try {
+                mode = requestedMode ?? (opened.stat.mode & 0o777);
+                if (!isPathInside(rootWithSep, opened.realPath)) {
+                    throw outsideWorkspaceError();
+                }
+            }
+            finally {
+                await opened.handle.close().catch(() => { });
             }
-        }
-        finally {
-            await opened.handle.close().catch(() => { });
         }
     }
     catch (err) {

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAWA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAsER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AAoID,KAAK,qBAAqB,GAAG;IAC3B,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,CAAC;AAkEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAwER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AAkID,KAAK,qBAAqB,GAAG;IAC3B,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,CAAC;AAkEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}