@openclaw/fs-safe 0.5.6 → 0.6.0

package/dist/native-pinned-write-windows.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, syncNativeFileBestEffort, writeNativeInput, } from "./native-operations.js";
+export function sameNativeIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function closeWriteFd(fd) {
+    if (fd === undefined)
+        return;
+    try {
+        fsSync.closeSync(fd);
+    }
+    catch (error) {
+        return error;
+    }
+}
+export async function runPinnedWriteWindows(binding, params, root, parentFd, parentGuard) {
+    const parentPath = parentGuard.realPath;
+    let tempFd;
+    let targetFd;
+    let tempIdentity;
+    let tempName = "";
+    let renamed = false;
+    let completed = false;
+    try {
+        tempName = `.${params.basename}.${randomUUID()}.native.tmp`;
+        tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
+        tempIdentity = fsSync.fstatSync(tempFd);
+        const verificationIdentity = fsSync.fstatSync(tempFd, { bigint: true });
+        // Creation is requested at 0600 in the binding, but a restrictive umask
+        // can remove owner access. Keep the unpublished inode private and
+        // reopenable until the published name has been identity-fenced.
+        fsSync.fchmodSync(tempFd, 0o600);
+        await writeNativeInput(tempFd, params.input, params.maxBytes);
+        syncNativeFileBestEffort(tempFd);
+        if (params.overwrite === false) {
+            binding.renameNoReplace(parentFd, tempName, parentFd, params.basename);
+        }
+        else {
+            binding.renameReplace(parentFd, tempName, parentFd, params.basename);
+        }
+        renamed = true;
+        targetFd = binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
+        const targetIdentity = binding.fstatIdentity(targetFd);
+        if (!targetIdentity.isFile || !sameNativeIdentity(tempIdentity, targetIdentity)) {
+            throw new FsSafeError("path-mismatch", "native write target changed after rename");
+        }
+        // Native exclusive creation starts at 0600. Apply the requested mode only
+        // after reopening and fencing the published name, both so mode 000 stays
+        // verifiable and so broader modes are never exposed before that fence.
+        try {
+            fsSync.fchmodSync(targetFd, params.mode);
+            syncNativeFileBestEffort(targetFd);
+        }
+        catch (error) {
+            closeWriteFd(targetFd);
+            targetFd = undefined;
+            removeNativeCreatedFileIfStillPinned({
+                binding,
+                parentPath,
+                parentFd,
+                basename: params.basename,
+                created: tempIdentity,
+            });
+            throw error;
+        }
+        syncNativeFileBestEffort(parentFd);
+        // Verification follows publication and final chmod, outside rollback handling.
+        await params.verifyPublished?.(targetFd, verificationIdentity, parentGuard);
+        completed = true;
+        return { dev: targetIdentity.dev, ino: targetIdentity.ino };
+    }
+    finally {
+        const targetCloseError = closeWriteFd(targetFd);
+        const tempCloseError = closeWriteFd(tempFd);
+        if (!renamed) {
+            removeNativeCreatedFileIfStillPinned({
+                binding,
+                parentPath,
+                parentFd,
+                basename: tempName,
+                created: tempIdentity,
+            });
+        }
+        const parentCloseError = closeWriteFd(parentFd);
+        await root.close().catch(() => undefined);
+        const closeError = targetCloseError ?? tempCloseError ?? parentCloseError;
+        if (completed && closeError !== undefined)
+            throw closeError;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiD7E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAsH3B"}
+{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmFvH"}

package/dist/native-pinned-write.js

@@ -1,142 +1,151 @@
-import { randomUUID } from "node:crypto";
-import fsSync, {} from "node:fs";
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { removeNativeCreatedFileIfStillPinned, syncNativeFileBestEffort, writeNativeFd, } from "./native-operations.js";
-function assertWithinMaxBytes(bytes, maxBytes) {
-    if (maxBytes !== undefined && bytes > maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
-    }
-}
-async function writeNativeInput(fd, input, maxBytes) {
-    if (input.kind === "buffer") {
-        const data = typeof input.data === "string"
-            ? Buffer.from(input.data, input.encoding ?? "utf8")
-            : Buffer.from(input.data);
-        assertWithinMaxBytes(data.byteLength, maxBytes);
-        writeNativeFd(fd, data);
-        return;
-    }
-    let bytes = 0;
-    for await (const chunk of input.stream) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += buffer.byteLength;
-        assertWithinMaxBytes(bytes, maxBytes);
-        writeNativeFd(fd, buffer);
-    }
-}
-function nativeOpenFlags(flags) {
-    const closeOnExec = fsSync.constants.O_CLOEXEC;
-    return (flags |
-        (closeOnExec ?? 0) |
-        (typeof fsSync.constants.O_NOFOLLOW === "number" ? fsSync.constants.O_NOFOLLOW : 0));
-}
-function sameNativeIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
+import { runPinnedWriteWindows, sameNativeIdentity } from "./native-pinned-write-windows.js";
+import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
+import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
 export async function runPinnedWriteNative(binding, params) {
-    const root = await fs.open(params.rootPath, fsSync.constants.O_RDONLY |
-        (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
-    let parentFd;
-    let tempFd;
-    let targetFd;
-    let tempIdentity;
-    let parentPath = params.rootPath;
-    const tempName = `.${params.basename}.${randomUUID()}.native.tmp`;
-    let renamed = false;
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        const rootIdentity = binding.fstatIdentity(root.fd);
-        if (params.rootIdentity && !sameNativeIdentity(params.rootIdentity, rootIdentity)) {
-            throw new FsSafeError("path-mismatch", "root path changed during native write");
-        }
-        if (params.mkdir) {
-            binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
-        }
-        const parentFlags = fsSync.constants.O_RDONLY |
-            (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0);
-        parentFd = binding.openBeneath(root.fd, params.relativeParentPath, parentFlags).fd;
-        parentPath = await fs.realpath(params.relativeParentPath
-            ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
-            : params.rootPath);
-        const parentPathStat = await fs.lstat(parentPath);
-        const parentIdentity = binding.fstatIdentity(parentFd);
-        if (parentPathStat.isSymbolicLink() ||
-            !sameNativeIdentity(parentPathStat, parentIdentity)) {
-            throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+        const windows = process.platform === "win32";
+        if (!windows) {
+            assertNativeStaging(binding);
         }
-        if (params.overwrite === false) {
-            try {
-                await fs.lstat(path.join(parentPath, params.basename));
-                throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+        const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
+        const root = await fs.open(params.rootPath, directoryFlags);
+        const posixRoot = __addDisposableResource(env_1, windows ? undefined : root, true);
+        let parentFd;
+        let windowsOwnsDirectories = false;
+        // Until stage construction takes ownership, even admission failures must close
+        // the raw POSIX parent. Disposal preserves both admission and close failures.
+        const parentGuard = __addDisposableResource(env_1, {
+            [Symbol.dispose]() {
+                if (!windows && parentFd !== undefined) {
+                    fsSync.closeSync(parentFd);
+                }
+            },
+        }, false);
+        try {
+            let rootMatches;
+            if (windows) {
+                const identity = binding.fstatIdentity(root.fd);
+                rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
             }
-            catch (error) {
-                if (error.code !== "ENOENT") {
-                    throw error;
+            else {
+                const identity = fsSync.fstatSync(root.fd, { bigint: true });
+                rootMatches = !params.rootIdentity || exactIdentityMatches(params.rootIdentity, identity);
+            }
+            if (!rootMatches) {
+                throw new FsSafeError("path-mismatch", "root path changed during native write");
+            }
+            if (params.mkdir) {
+                binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
+            }
+            parentFd = binding.openBeneath(root.fd, params.relativeParentPath, directoryFlags).fd;
+            const parentPath = await fs.realpath(params.relativeParentPath
+                ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
+                : params.rootPath);
+            const directory = windows ? undefined : describeStagedDirectory(parentFd, parentPath);
+            const parentPathStat = await fs.lstat(parentPath);
+            if (windows) {
+                const parentIdentity = binding.fstatIdentity(parentFd);
+                if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
+                    throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
                 }
             }
+            else if (parentPathStat.isSymbolicLink() || !exactIdentityMatches(parentPathStat, directory.identity)) {
+                throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+            }
+            const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
+            if (params.overwrite === false) {
+                try {
+                    await fs.lstat(path.join(parentPath, params.basename));
+                    throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        throw error;
+                    }
+                }
+            }
+            if (windows) {
+                // The Windows leaf owns both directories after admission.
+                windowsOwnsDirectories = true;
+                return await runPinnedWriteWindows(binding, params, root, parentFd, verificationGuard);
+            }
+            const ownedParent = parentFd;
+            parentFd = undefined;
+            return await writeNativeStage(binding, ownedParent, directory, params, verificationGuard);
         }
-        tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
-        tempIdentity = fsSync.fstatSync(tempFd);
-        // Creation is requested at 0600 in the binding, but a restrictive umask
-        // can remove owner access. Keep the unpublished inode private and
-        // reopenable until the published name has been identity-fenced.
-        fsSync.fchmodSync(tempFd, 0o600);
-        await writeNativeInput(tempFd, params.input, params.maxBytes);
-        syncNativeFileBestEffort(tempFd);
-        if (params.overwrite === false) {
-            binding.renameNoReplace(parentFd, tempName, parentFd, params.basename);
-        }
-        else {
-            binding.renameReplace(parentFd, tempName, parentFd, params.basename);
-        }
-        renamed = true;
-        targetFd = binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
-        const targetIdentity = binding.fstatIdentity(targetFd);
-        if (!targetIdentity.isFile || !sameNativeIdentity(tempIdentity, targetIdentity)) {
-            throw new FsSafeError("path-mismatch", "native write target changed after rename");
-        }
-        // Native exclusive creation starts at 0600. Apply the requested mode only
-        // after reopening and fencing the published name, both so mode 000 stays
-        // verifiable and so broader modes are never exposed before that fence.
-        try {
-            fsSync.fchmodSync(targetFd, params.mode);
-            syncNativeFileBestEffort(targetFd);
-        }
-        catch (error) {
-            fsSync.closeSync(targetFd);
-            targetFd = undefined;
-            removeNativeCreatedFileIfStillPinned({
-                binding,
-                parentPath,
-                parentFd,
-                basename: params.basename,
-                created: tempIdentity,
-            });
-            throw error;
+        finally {
+            if (windows && !windowsOwnsDirectories) {
+                if (parentFd !== undefined) {
+                    fsSync.closeSync(parentFd);
+                }
+                await root.close().catch(() => undefined);
+            }
         }
-        syncNativeFileBestEffort(parentFd);
-        return { dev: targetIdentity.dev, ino: targetIdentity.ino };
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
     }
     finally {
-        if (targetFd !== undefined) {
-            fsSync.closeSync(targetFd);
-        }
-        if (tempFd !== undefined) {
-            fsSync.closeSync(tempFd);
-        }
-        if (!renamed && parentFd !== undefined) {
-            removeNativeCreatedFileIfStillPinned({
-                binding,
-                parentPath,
-                parentFd,
-                basename: tempName,
-                created: tempIdentity,
-            });
-        }
-        if (parentFd !== undefined) {
-            fsSync.closeSync(parentFd);
-        }
-        await root.close().catch(() => undefined);
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
     }
 }

package/dist/native-staged-file.d.ts

@@ -0,0 +1,24 @@
+import type { AsyncDirectoryGuard } from "./directory-guard.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native-binding.js";
+import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write.js";
+import type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
+export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding, "createStagedFile" | "stagedFileMatches" | "removeStagedFile">>;
+export declare function assertNativeStaging(binding: NativeBinding): asserts binding is NativeStagingBinding;
+declare class NativeStagedFile implements StagedFile {
+    #private;
+    constructor(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], portableNames: boolean, publishedMode: number);
+    static create(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], input: PinnedWriteInput, mode: number, maxBytes?: number, portableNames?: boolean): Promise<NativeStagedFile>;
+    static write(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], params: PinnedWriteParams, parentGuard: AsyncDirectoryGuard): Promise<FileIdentityStat>;
+    get receipt(): StagedFileReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string, options: {
+        overwrite: boolean;
+    }): Promise<PublishedFileReceipt>;
+    cleanup(): Promise<StagedFileCleanupReceipt>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare const createNativeStage: (...args: Parameters<typeof NativeStagedFile.create>) => Promise<StagedFile>;
+export declare const writeNativeStage: typeof NativeStagedFile.write;
+export {};
+//# sourceMappingURL=native-staged-file.d.ts.map

package/dist/native-staged-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-staged-file.d.ts","sourceRoot":"","sources":["../src/native-staged-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,wBAAwB,EAGxB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,QAAQ,CAAC,IAAI,CAC9D,aAAa,EACb,kBAAkB,GAAG,mBAAmB,GAAG,kBAAkB,CAC9D,CAAC,CAAC;AAEH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,IAAI,oBAAoB,CAUnG;AA6BD,cAAM,gBAAiB,YAAW,UAAU;;IAU1C,YACE,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,MAAM,EAOtB;IAGD,OAAa,MAAM,CACjB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,EAEjB,aAAa,UAAO,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAc3B;IAED,OAAa,KAAK,CAChB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAU3B;IAED,IAAI,OAAO,IAAI,iBAAiB,CAK/B;IAoFK,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnC;IAEK,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgD9F;IA6CK,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAMjD;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAO3C;CACF;AAED,eAAO,MAAM,iBAAiB,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,UAAU,CAClF,CAAC;AAC1B,eAAO,MAAM,gBAAgB,+BAAyB,CAAC"}