@openclaw/fs-safe 0.15.0 → 0.17.0

package/dist/pinned-write-staged.js

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { createFileHandle } from "./create.js";
+import { hasPreservedCreationArtifacts } from "./creation-file-state.js";
+import { creationAdmissionFromParent } from "./creation-path.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity, sha256Hex } from "./file-identity.js";
+import { syncFileBestEffort } from "./file-sync.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
+import { writePinnedInput } from "./pinned-write-input.js";
+import { assertPinnedWriteMode, pinnedWriteModeAssertion, preparePinnedWriteMode } from "./pinned-write-mode.js";
+import { publishCopyStage } from "./publish-copy-stage.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { createStagedFileReceipt, settleStagedFile } from "./staged-file-settlement.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
+    const verifyPosixMode = process.platform !== "win32" &&
+        (params.verifyPosixMode === true || params.private === true);
+    const targetPath = path.join(parentPath, params.basename);
+    // Private staging must not consume the destination basename's filename budget.
+    const tempPath = path.join(parentPath, `.fs-safe-${randomUUID()}.tmp`);
+    const tempFlags = fsSync.constants.O_WRONLY |
+        fsSync.constants.O_CREAT |
+        fsSync.constants.O_EXCL |
+        (process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
+            ? fsSync.constants.O_NOFOLLOW
+            : 0);
+    let handle;
+    let tempStat;
+    let tempIdentity;
+    let readHandle;
+    let renamed = false;
+    const completeCreate = params.overwrite === false && params.input.kind !== "file" && params.input.stageBeforePublish === true;
+    let receipt;
+    let publication = Object.freeze({ status: "not-published" });
+    let phase = "prepare";
+    let failure;
+    try {
+        params.assertBeforeMutation?.();
+        handle = params.private
+            ? await createFileHandle(tempPath, {
+                private: true, mode: 0o600, assertBeforeMutation: params.assertBeforeMutation,
+            }, creationAdmissionFromParent(parentGuard))
+            : await fs.open(tempPath, tempFlags, verifyPosixMode ? 0o600 : params.mode);
+        let verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
+        tempIdentity = verificationIdentity;
+        let assertBeforeMutation = params.assertBeforeMutation;
+        const assertBeforeWrite = verifyPosixMode
+            ? await preparePinnedWriteMode(handle, Number(tempIdentity.mode & 4095n), assertBeforeMutation, params.private)
+            : assertBeforeMutation;
+        if (verifyPosixMode)
+            assertPinnedWriteMode(handle.fd, 0o600, params.private);
+        await writePinnedInput(handle, params.input, params.maxBytes, assertBeforeWrite);
+        if (verifyPosixMode)
+            assertPinnedWriteMode(handle.fd, 0o600, params.private);
+        tempStat = fsSync.fstatSync(handle.fd);
+        const tempPathStat = fsSync.lstatSync(tempPath);
+        if (tempPathStat.isSymbolicLink() || !sameFileIdentity(tempPathStat, tempStat)) {
+            throw new FsSafeError("path-mismatch", "fallback temp path changed during write");
+        }
+        const expectedTempStat = tempStat;
+        await handle.chmod(params.mode);
+        if (verifyPosixMode) {
+            assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            assertBeforeMutation = pinnedWriteModeAssertion(handle.fd, params.mode, params.assertBeforeMutation, params.private);
+        }
+        if (params.sync !== false) {
+            if (params.strictFileSync)
+                await handle.sync();
+            else
+                await syncFileBestEffort(handle);
+        }
+        if (params.input.kind === "file")
+            await params.input.verifySource();
+        if (completeCreate) {
+            receipt = createStagedFileReceipt(Object.freeze({
+                path: parentGuard.dir,
+                realPath: parentGuard.realPath,
+                identity: Object.freeze({ dev: parentGuard.stat.dev, ino: parentGuard.stat.ino }),
+            }), path.basename(tempPath), fsSync.fstatSync(handle.fd, { bigint: true }));
+        }
+        let verifiedIdentity = expectedTempStat;
+        phase = "publish";
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
+            if (params.overwrite === false) {
+                publishCopyStage({
+                    temporaryPath: tempPath, targetPath, fd: handle.fd,
+                    identity: tempIdentity, parentGuard,
+                    assertBeforeMutation,
+                    onPublicationAttempt: () => {
+                        if (receipt)
+                            publication = Object.freeze({ status: "indeterminate", basename: params.basename, overwrite: false });
+                    },
+                    onPublished: (identity) => {
+                        renamed = true;
+                        if (receipt)
+                            publication = Object.freeze({ status: "published", staged: receipt, basename: params.basename, overwrite: false });
+                        params.onPublished?.(identity);
+                    },
+                });
+            }
+            else {
+                assertBeforeMutation?.();
+                await fs.rename(tempPath, targetPath);
+                renamed = true;
+                params.onPublished?.(verificationIdentity);
+            }
+            await getFsSafeTestHooks()?.afterPinnedWriteFallbackRename?.(targetPath);
+            if (params.sync !== false)
+                await syncDirectoryBestEffort(parentPath);
+            const targetStat = fsSync.lstatSync(targetPath);
+            if (targetStat.isSymbolicLink()) {
+                throw new FsSafeError("path-mismatch", "fallback target changed during write");
+            }
+            if (!sameFileIdentity(targetStat, expectedTempStat)) {
+                // On filesystems like rclone FUSE, rename(2) can give the destination a
+                // different inode from the source temp fd even with zero concurrency. The
+                // caller must ensure mutual exclusion before passing "verify-content";
+                // fall back to a content hash for this rename-boundary check only.
+                if (params.onRenameIdentityMismatch !== "verify-content") {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                if (params.input.kind !== "buffer") {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                const expectedHash = sha256Hex(params.input.data, params.input.encoding);
+                readHandle = await fs.open(targetPath, resolveReadOpenFlags());
+                const readHandleStat = fsSync.fstatSync(readHandle.fd, { bigint: true });
+                const actualHash = sha256Hex(await readHandle.readFile());
+                if (actualHash !== expectedHash) {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                // The content-verified destination, not the old temp inode, is now pinned.
+                verificationIdentity = readHandleStat;
+                // Preserve the helper's legacy numeric return facts, not the private proof.
+                verifiedIdentity = { dev: Number(readHandleStat.dev), ino: Number(readHandleStat.ino) };
+            }
+        });
+        await params.verifyPublished?.((readHandle ?? handle).fd, verificationIdentity, parentGuard);
+        if (verifyPosixMode)
+            assertPinnedWriteMode((readHandle ?? handle).fd, params.mode, params.private);
+        return { dev: verifiedIdentity.dev, ino: verifiedIdentity.ino };
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        const preservedPreparation = params.private && !handle && hasPreservedCreationArtifacts(failure?.error);
+        if (completeCreate || preservedPreparation) {
+            await settleStagedFile({
+                temporaryBasename: path.basename(tempPath), publication, phase, failure,
+                cleanup: async () => {
+                    if (preservedPreparation)
+                        return "preserved";
+                    if (publication.status === "indeterminate")
+                        return "preserved";
+                    if (renamed) {
+                        return failure?.error instanceof FsSafeError && failure.error.details?.cleanup === "failed"
+                            ? "failed" : "not-needed";
+                    }
+                    return handle ? await cleanupPinnedFilePath({
+                        pathname: tempPath, handle, identity: tempIdentity, parentGuard, throwOnCleanupError: true,
+                    }) : "not-needed";
+                },
+                close: [async () => { await readHandle?.close(); }, async () => { await handle?.close(); }],
+            });
+        }
+        else
+            try {
+                if (!renamed && handle) {
+                    await cleanupPinnedFilePath({ pathname: tempPath, handle, identity: tempIdentity, parentGuard });
+                }
+            }
+            finally {
+                await readHandle?.close().catch(() => undefined);
+                await handle?.close().catch(() => undefined);
+            }
+    }
+}

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

@@ -62,7 +62,10 @@ export type PinnedWriteParams = {
     basename: string;
     mkdir: boolean;
     mode: number;
+    private?: boolean;
+    verifyPosixMode?: boolean;
     sync?: boolean;
+    strictFileSync?: boolean;
     overwrite?: boolean;
     assertBeforeMutation?: () => void;
     rejectFinalSymlink?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"pinned-write-types.d.ts","sourceRoot":"","sources":["../src/pinned-write-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pinned-write-types.d.ts","sourceRoot":"","sources":["../src/pinned-write-types.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAiB3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACvF,YAAY,EACV,gBAAgB,EAAE,oBAAoB,EAAE,sBAAsB,EAC9D,8BAA8B,EAAE,gCAAgC,EAChE,6BAA6B,EAAE,+BAA+B,EAC9D,4BAA4B,EAAE,iBAAiB,GAChD,MAAM,yBAAyB,CAAC;AAgFjC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsD/F;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED,wBAAsB,iCAAiC,CAAC,CAAC,EACvD,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,EAC5E,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}
+{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgB3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACvF,YAAY,EACV,gBAAgB,EAAE,oBAAoB,EAAE,sBAAsB,EAC9D,8BAA8B,EAAE,gCAAgC,EAChE,6BAA6B,EAAE,+BAA+B,EAC9D,4BAA4B,EAAE,iBAAiB,GAChD,MAAM,yBAAyB,CAAC;AAkDjC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsD/F;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED,wBAAsB,iCAAiC,CAAC,CAAC,EACvD,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,EAC5E,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/pinned-write.js

@@ -1,32 +1,27 @@
 import { syncFileBestEffort } from "./file-sync.js";
-import { randomUUID } from "node:crypto";
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { createFileHandle } from "./create.js";
+import { creationAdmissionFromParent } from "./creation-path.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
-import { sameFileIdentity, sha256Hex } from "./file-identity.js";
+import { sha256Hex } from "./file-identity.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { runPinnedWriteNative } from "./native-pinned-write.js";
 import { getNativeBinding } from "./native.js";
 import { validatePinnedOperationPayload } from "./pinned-operation.js";
-import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { cleanupPinnedFilePath } from "./replace-file-temp-owner.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { withSidecarLock } from "./sidecar-lock.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { writeAllToFile } from "./write-file-handle.js";
+import { writePinnedInput } from "./pinned-write-input.js";
+import { assertPinnedWriteMode, preparePinnedWriteMode } from "./pinned-write-mode.js";
+import { runPinnedStagedWrite } from "./pinned-write-staged.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
-import { writeCopyFileToFd } from "./copy-file-input.js";
-import { publishCopyStage } from "./publish-copy-stage.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-function byteLength(input, encoding) {
-    return typeof input === "string"
-        ? Buffer.byteLength(input, encoding ?? "utf8")
-        : input.byteLength;
-}
 function assertSafeBasename(basename) {
     if (!basename ||
         basename === "." ||
@@ -37,24 +32,10 @@ function assertSafeBasename(basename) {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
 }
-function assertWithinMaxBytes(bytes, maxBytes) {
-    if (maxBytes !== undefined && bytes > maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
-    }
-}
 function fastParentGuardDeopt(error) {
     return error instanceof FsSafeError &&
         (error.code === "path-mismatch" || error.code === "not-file");
 }
-async function writeStreamToHandle(stream, handle, maxBytes, assertBeforeMutation) {
-    let bytes = 0;
-    for await (const chunk of stream) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += buffer.byteLength;
-        assertWithinMaxBytes(bytes, maxBytes);
-        await writeAllToFile(handle, buffer, { assertBeforeMutation });
-    }
-}
 const PINNED_WRITE_SNAPSHOT_KEYS = [
     "rootPath", "relativeParentPath", "basename", "maxBytes", "rootIdentity",
 ];
@@ -142,6 +123,8 @@ export async function withPinnedWriteRenameIdentityLock(params, run) {
     }, run);
 }
 async function runPinnedWriteFallback(params) {
+    const verifyPosixMode = process.platform !== "win32" &&
+        (params.verifyPosixMode === true || params.private === true);
     const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
         ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
     const mutationAdmission = params.mutationAdmission;
@@ -246,15 +229,19 @@ async function runPinnedWriteFallback(params) {
         }));
         await assertAsyncDirectoryGuard(parentGuard);
     }
-    if (params.overwrite === false && (params.input.kind === "buffer" ||
-        (params.input.kind === "stream" && !params.input.stageBeforePublish))) {
+    if (params.overwrite === false && params.input.kind !== "file" && !params.input.stageBeforePublish) {
         const assertBeforeMutation = () => {
             assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
             params.assertBeforeMutation?.();
         };
         const handle = await withAsyncDirectoryGuards([parentGuard], async () => {
             assertBeforeMutation();
-            return await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode);
+            if (params.private) {
+                return await createFileHandle(targetPath, {
+                    private: true, mode: 0o600, assertBeforeMutation,
+                }, creationAdmissionFromParent(parentGuard));
+            }
+            return await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, verifyPosixMode ? 0o600 : params.mode);
         }, {
             onPostGuardFailure: async (openedHandle) => {
                 // The parent failed verification, so targetPath may now resolve
@@ -263,29 +250,38 @@ async function runPinnedWriteFallback(params) {
             },
         });
         let created = true;
+        let completed = false;
         let createdIdentity;
         try {
             const verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
             createdIdentity = verificationIdentity;
-            if (params.input.kind === "buffer") {
-                assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
-                await writeAllToFile(handle, params.input.data, {
-                    encoding: params.input.encoding, assertBeforeMutation,
-                });
-            }
-            else {
-                await writeStreamToHandle(params.input.stream, handle, params.maxBytes, assertBeforeMutation);
-            }
+            const assertBeforeWrite = verifyPosixMode
+                ? await preparePinnedWriteMode(handle, Number(createdIdentity.mode & 4095n), assertBeforeMutation, params.private)
+                : assertBeforeMutation;
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, 0o600, params.private);
+            await writePinnedInput(handle, params.input, params.maxBytes, assertBeforeWrite);
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, 0o600, params.private);
             // Content writes may clear set-ID bits; finalize them through the owned fd.
             await handle.chmod(params.mode);
-            if (params.sync !== false)
-                await syncFileBestEffort(handle);
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            if (params.sync !== false) {
+                if (params.strictFileSync)
+                    await handle.sync();
+                else
+                    await syncFileBestEffort(handle);
+            }
             const stat = fsSync.fstatSync(handle.fd);
             if (params.sync !== false)
                 await syncDirectoryBestEffort(parentPath);
             // Publication is complete. A failed outer check must not remove its target.
             created = false;
             await params.verifyPublished?.(handle.fd, verificationIdentity, parentGuard);
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            completed = true;
             return { dev: stat.dev, ino: stat.ino };
         }
         finally {
@@ -295,114 +291,12 @@ async function runPinnedWriteFallback(params) {
                 }
             }
             finally {
-                await handle.close().catch(() => undefined);
-            }
-        }
-    }
-    // Private staging must not consume the destination basename's filename budget.
-    const tempPath = path.join(parentPath, `.fs-safe-${randomUUID()}.tmp`);
-    const tempFlags = fsSync.constants.O_WRONLY |
-        fsSync.constants.O_CREAT |
-        fsSync.constants.O_EXCL |
-        (process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
-            ? fsSync.constants.O_NOFOLLOW
-            : 0);
-    let handle;
-    let tempStat;
-    let tempIdentity;
-    let readHandle;
-    let renamed = false;
-    try {
-        params.assertBeforeMutation?.();
-        handle = await fs.open(tempPath, tempFlags, params.mode);
-        let verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
-        tempIdentity = verificationIdentity;
-        if (params.input.kind === "buffer") {
-            assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
-            await writeAllToFile(handle, params.input.data, {
-                encoding: params.input.encoding, assertBeforeMutation: params.assertBeforeMutation,
-            });
-        }
-        else if (params.input.kind === "file") {
-            await writeCopyFileToFd(handle.fd, params.input, params.maxBytes, params.assertBeforeMutation);
-        }
-        else {
-            await writeStreamToHandle(params.input.stream, handle, params.maxBytes, params.assertBeforeMutation);
-        }
-        tempStat = fsSync.fstatSync(handle.fd);
-        const tempPathStat = fsSync.lstatSync(tempPath);
-        if (tempPathStat.isSymbolicLink() || !sameFileIdentity(tempPathStat, tempStat)) {
-            throw new FsSafeError("path-mismatch", "fallback temp path changed during write");
-        }
-        const expectedTempStat = tempStat;
-        await handle.chmod(params.mode);
-        if (params.sync !== false)
-            await syncFileBestEffort(handle);
-        if (params.input.kind === "file")
-            await params.input.verifySource();
-        let verifiedIdentity = expectedTempStat;
-        await withAsyncDirectoryGuards([parentGuard], async () => {
-            assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
-            if (params.overwrite === false) {
-                publishCopyStage({
-                    temporaryPath: tempPath, targetPath, fd: handle.fd,
-                    identity: tempIdentity, parentGuard,
-                    assertBeforeMutation: params.assertBeforeMutation,
-                    onPublished: (identity) => {
-                        renamed = true;
-                        params.onPublished?.(identity);
-                    },
-                });
+                if (completed)
+                    await handle.close();
+                else
+                    await handle.close().catch(() => undefined);
             }
-            else {
-                params.assertBeforeMutation?.();
-                await fs.rename(tempPath, targetPath);
-                renamed = true;
-                params.onPublished?.(verificationIdentity);
-            }
-            await getFsSafeTestHooks()?.afterPinnedWriteFallbackRename?.(targetPath);
-            if (params.sync !== false)
-                await syncDirectoryBestEffort(parentPath);
-            const targetStat = fsSync.lstatSync(targetPath);
-            if (targetStat.isSymbolicLink()) {
-                throw new FsSafeError("path-mismatch", "fallback target changed during write");
-            }
-            if (!sameFileIdentity(targetStat, expectedTempStat)) {
-                // On filesystems like rclone FUSE, rename(2) can give the destination a
-                // different inode from the source temp fd even with zero concurrency. The
-                // caller must ensure mutual exclusion before passing "verify-content";
-                // fall back to a content hash for this rename-boundary check only.
-                if (params.onRenameIdentityMismatch !== "verify-content") {
-                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
-                }
-                if (params.input.kind !== "buffer") {
-                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
-                }
-                const expectedHash = sha256Hex(params.input.data, params.input.encoding);
-                readHandle = await fs.open(targetPath, resolveReadOpenFlags());
-                const readHandleStat = fsSync.fstatSync(readHandle.fd, { bigint: true });
-                const actualHash = sha256Hex(await readHandle.readFile());
-                if (actualHash !== expectedHash) {
-                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
-                }
-                // The content-verified destination, not the old temp inode, is now pinned.
-                verificationIdentity = readHandleStat;
-                // Preserve the helper's legacy numeric return facts, not the private proof.
-                verifiedIdentity = { dev: Number(readHandleStat.dev), ino: Number(readHandleStat.ino) };
-            }
-        });
-        await params.verifyPublished?.((readHandle ?? handle).fd, verificationIdentity, parentGuard);
-        return { dev: verifiedIdentity.dev, ino: verifiedIdentity.ino };
-    }
-    finally {
-        try {
-            if (!renamed && handle) {
-                await cleanupPinnedFilePath({ pathname: tempPath, handle, identity: tempIdentity, parentGuard });
-            }
-        }
-        finally {
-            await readHandle?.close().catch(() => undefined);
-            await handle?.close().catch(() => undefined);
         }
     }
+    return await runPinnedStagedWrite(params, parentPath, parentGuard);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"private-directory.d.ts","sourceRoot":"","sources":["../src/private-directory.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,IAAI,CAAC,CAyBf"}
+{"version":3,"file":"private-directory.d.ts","sourceRoot":"","sources":["../src/private-directory.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/private-directory.js

@@ -1,6 +1,10 @@
+import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { createPrivateWindowsDirectoryCommand } from "./windows-security-command.js";
 export async function createPrivateDirectory(targetPath, options) {
     const platform = options?.platform ?? process.platform;
     if (platform !== "win32") {
@@ -8,9 +12,19 @@ export async function createPrivateDirectory(targetPath, options) {
     }
     assertNoWindowsPathAlias(targetPath, "filesystem", "private directory path uses a Windows filesystem namespace alias", platform);
     const native = getNativeBinding();
-    if (!native) {
-        throw new FsSafeError("helper-unavailable", "private Windows directory creation requires the matching optional native platform package; " +
-            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
+    if (typeof native?.createPrivateDirectory === "function") {
+        native.createPrivateDirectory(targetPath);
+        return;
     }
-    native.createPrivateDirectory(targetPath);
+    if (getFsSafeNativeConfig().mode === "require") {
+        throw new FsSafeError("helper-unavailable", "private Windows directory creation requires an up-to-date native helper");
+    }
+    // Preserve the native parser's raw component restrictions before resolve()
+    // could discard dot components or Win32 could trim trailing aliases.
+    const components = targetPath.replaceAll("/", "\\").split("\\");
+    if (components.some(component => component.endsWith(".") || component.endsWith(" "))) {
+        throw Object.assign(new Error("private directory path has an ambiguous component"), { code: "EINVAL" });
+    }
+    warnNativeFallback("windows-private-directory", "Private Windows directory creation uses a slower built-in system command.");
+    await createPrivateWindowsDirectoryCommand(path.win32.resolve(targetPath));
 }

package/dist/private-producer-handoff-sync.d.ts

@@ -0,0 +1,14 @@
+import { type BigIntStats } from "node:fs";
+import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
+export declare function handoffCreatedFileSync(params: {
+    source: OwnedFileDescriptorSync;
+    sourcePath: string;
+    targetPath: string;
+    identity: BigIntStats;
+    assertSourceParent: () => void;
+    assertTargetParent: () => void;
+    assertBeforeMutation?: () => void;
+    verifyDescriptor?: (fd: number, path: string, links: number) => void;
+    onPublished?: () => void;
+}): OwnedFileDescriptorSync;
+//# sourceMappingURL=private-producer-handoff-sync.d.ts.map

package/dist/private-producer-handoff-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-producer-handoff-sync.d.ts","sourceRoot":"","sources":["../src/private-producer-handoff-sync.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAyB,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAW7F,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,MAAM,EAAE,uBAAuB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,GAAG,uBAAuB,CA0H1B"}