@openclaw/fs-safe 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.2 - 2026-09-01
+
+- Add `movePathWithCopyFallback({ assertBeforeRename })` to synchronously recheck caller-owned authorization immediately before direct or staged rename, preserving refusal errors and rejecting asynchronous callbacks without publishing the move.
+
 ## 0.7.1 - 2026-09-01
 
 ### Highlights

package/dist/guarded-mutation.d.ts

@@ -7,6 +7,7 @@ export declare function withSyncDirectoryGuards<T>(guards: readonly SyncDirector
     verifyAfter?: boolean;
 }): T;
 export declare function guardedRename(params: {
+    assertBeforeRename?: () => void;
     from: string;
     to: string;
     targetRoot?: string;

package/dist/guarded-mutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}
+{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}

package/dist/guarded-mutation.js

@@ -48,6 +48,8 @@ export async function guardedRename(params) {
         ? await createNearestExistingDirectoryGuard(params.targetRoot, path.dirname(params.to))
         : await createAsyncDirectoryGuard(path.dirname(params.to));
     await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
+        // Authority must survive all awaited guards; do not yield before rename dispatch.
+        params.assertBeforeRename?.();
         await fs.rename(params.from, params.to);
     }, { verifyAfter: params.verifyAfter });
 }

package/dist/move-path.d.ts

@@ -1,4 +1,6 @@
 export type MovePathWithCopyFallbackOptions = {
+    /** Rechecks caller authority synchronously immediately before each rename dispatch. */
+    assertBeforeRename?: () => void;
     from: string;
     sourceHardlinks?: "allow" | "reject";
     to: string;

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

@@ -1 +1 @@
-{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AAiVD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA2Df"}
+{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AAiVD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA4Ef"}

package/dist/move-path.js

@@ -267,6 +267,23 @@ async function cleanupCopiedEntry(sourcePath, manifest) {
     return "removed";
 }
 export async function movePathWithCopyFallback(options) {
+    // Keep the initiating owner's callback across preparation and copy fallback.
+    const callerAssert = options.assertBeforeRename;
+    let assertionRejected = false;
+    const assertBeforeRename = () => {
+        try {
+            const returned = callerAssert?.();
+            if (returned !== undefined) {
+                // TypeScript permits async functions for () => void; they cannot authorize a rename.
+                void Promise.resolve(returned).catch(() => { });
+                throw new TypeError("assertBeforeRename must return undefined synchronously");
+            }
+        }
+        catch (error) {
+            assertionRejected = true;
+            throw error;
+        }
+    };
     const sourcePath = path.resolve(options.from);
     const targetPath = path.resolve(options.to);
     const rejectHardlinks = options.sourceHardlinks === "reject";
@@ -275,11 +292,12 @@ export async function movePathWithCopyFallback(options) {
     }
     if (!rejectHardlinks) {
         try {
-            await guardedRename({ from: sourcePath, to: targetPath });
+            await guardedRename({ from: sourcePath, to: targetPath, assertBeforeRename });
             return;
         }
         catch (error) {
-            if (!moveCopyFallbackReasonForRenameError(error)) {
+            // An owner's EXDEV/EPERM refusal is not permission to copy instead.
+            if (assertionRejected || !moveCopyFallbackReasonForRenameError(error)) {
                 throw error;
             }
         }
@@ -301,7 +319,7 @@ export async function movePathWithCopyFallback(options) {
         });
         unregisterStaged.setIdentity(await fs.lstat(staged, { bigint: true }));
         await assertCopyDestinationOutsideSource(sourcePath, targetPath);
-        await guardedRename({ from: staged, to: targetPath });
+        await guardedRename({ from: staged, to: targetPath, assertBeforeRename });
         stagedCommitted = true;
         unregisterStaged();
         const cleanupResult = await cleanupCopiedEntry(sourcePath, manifest);

package/docs/atomic.md

@@ -209,6 +209,40 @@ throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
 `ESTALE`.
 
+### Final rename authorization
+
+Pass `assertBeforeRename` when a move depends on a revocable lease or another
+caller-owned authorization. The helper captures this callback when called and
+runs it synchronously after asynchronous preparation and directory checks,
+immediately before each rename is dispatched:
+
+```ts
+type MovePathWithCopyFallbackOptions = {
+  from: string;
+  sourceHardlinks?: "allow" | "reject";
+  to: string;
+  assertBeforeRename?: () => void;
+};
+```
+
+Throw to refuse publication. The original error is propagated, including errors
+with `EXDEV` or `EPERM` codes; an authorization failure never starts a copy
+fallback. A genuine rename failure may still require a second authorization
+check before publishing the staged copy.
+
+The callback must return `undefined` synchronously. Returning a Promise, thenable,
+or any other value refuses the rename with a `TypeError`; rejected asynchronous
+results are consumed without authorizing the operation. Perform asynchronous
+policy checks before calling the helper and use this callback to recheck the
+current owner at the mutation boundary.
+
+A refused rename leaves the source and destination unchanged; any private
+staged copy follows the helper's normal cleanup. The check does not cancel an
+already-dispatched rename or make an external lease store atomic with the
+filesystem. Cleanup after a successful move retains the existing source-identity
+checks. Omitting the
+callback preserves the usual move behavior.
+
 ## Difference from `root()`
 
 | `Root` methods | `atomic` helpers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -149,13 +149,13 @@
     "crabbox:warmup": "crabbox warmup"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.7.1",
-    "@openclaw/fs-safe-darwin-x64": "0.7.1",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.7.1",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.7.1",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.7.1",
-    "@openclaw/fs-safe-linux-x64-musl": "0.7.1",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.7.1",
+    "@openclaw/fs-safe-darwin-arm64": "0.7.2",
+    "@openclaw/fs-safe-darwin-x64": "0.7.2",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.7.2",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.7.2",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.7.2",
+    "@openclaw/fs-safe-linux-x64-musl": "0.7.2",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.7.2",
     "jszip": "^3.10.1",
     "tar": "7.5.22"
   },