@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/private-producer-handoff.js

@@ -0,0 +1,272 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { registerTempPathForExit, } from "./temp-cleanup.js";
+function pathMismatch(message) {
+    return new FsSafeError("path-mismatch", message);
+}
+function assertInitialSource(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("path-alias", "isolated producer output must not be a symlink");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "isolated producer output must be a regular file");
+    }
+    if (stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", "isolated producer output must have exactly one link");
+    }
+}
+function inspectLinkedFile(inspect, expected, links, label) {
+    return inspectFileIdentitySync(() => {
+        const stat = inspect();
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== links) {
+            throw pathMismatch(`${label} changed during isolated producer handoff`);
+        }
+        return stat;
+    }, expected);
+}
+function assertParents(params) {
+    params.assertTargetParent();
+    params.assertSourceParent();
+}
+function normalizeLinkError(error) {
+    const code = error?.code;
+    if (code === "EEXIST") {
+        return new FsSafeError("already-exists", "isolated producer sibling already exists", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (code === "EXDEV" ||
+        code === "ENOSYS" ||
+        code === "ENOTSUP" ||
+        code === "EOPNOTSUPP" ||
+        code === "EPERM") {
+        return new FsSafeError("helper-unavailable", "atomic isolated producer handoff is unavailable", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    return error;
+}
+function removeSiblingIfOwned(params) {
+    if (!params.state.siblingOwned)
+        return;
+    params.assertTargetParent();
+    let current;
+    try {
+        current = fsSync.lstatSync(params.targetPath, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            params.state.siblingOwned = false;
+            return;
+        }
+        throw error;
+    }
+    if (current.isSymbolicLink() ||
+        !current.isFile() ||
+        (current.nlink !== 1n && current.nlink !== 2n) ||
+        !sameFileIdentityForCleanup(current, params.identity)) {
+        throw pathMismatch("isolated producer sibling changed before cleanup");
+    }
+    fsSync.unlinkSync(params.targetPath);
+    params.state.siblingOwned = false;
+    params.assertTargetParent();
+}
+function combinedFailure(primary, settlement) {
+    if (settlement.length === 0)
+        return primary;
+    return new AggregateError([primary, ...settlement], "isolated producer handoff and settlement failed");
+}
+function hasCode(error, codes) {
+    return !(error instanceof FsSafeError) &&
+        codes.includes(error?.code ?? "");
+}
+async function throwAfterClosing(primary, handles) {
+    const settlement = [];
+    const closed = new Set();
+    for (const handle of handles) {
+        if (!handle || closed.has(handle))
+            continue;
+        closed.add(handle);
+        try {
+            await handle.close();
+        }
+        catch (error) {
+            settlement.push(error);
+        }
+    }
+    throw combinedFailure(primary, settlement);
+}
+function inspectSourceDescriptor(handle, identity, links = 1n) {
+    inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, links, "isolated producer descriptor");
+}
+function historicalOpenFlags(readWrite) {
+    const access = readWrite ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+    return access | resolveReadOpenFlags();
+}
+async function openHistoricalSource(sourcePath, identity, readWrite, links) {
+    let handle;
+    try {
+        handle = await fs.open(sourcePath, historicalOpenFlags(readWrite));
+        inspectSourceDescriptor(handle, identity, links);
+        return handle;
+    }
+    catch (error) {
+        if (handle)
+            return await throwAfterClosing(error, [handle]);
+        throw error;
+    }
+}
+// Windows data-read access can synchronously inspect a completed file through
+// filesystem filters. Prefer write-only admission, which still supports the
+// descriptor metadata, chmod and sync operations used below. Providers or
+// read-only files that reject that access retain the historical open contract.
+async function openProducerSource(params, identity, links = 1n) {
+    if (process.platform !== "win32") {
+        return await openHistoricalSource(params.sourcePath, identity, params.readWrite, links);
+    }
+    let provisional;
+    try {
+        provisional = await fs.open(params.sourcePath, fsSync.constants.O_WRONLY);
+    }
+    catch (error) {
+        if (!hasCode(error, ["EACCES", "EPERM", "EBUSY"]))
+            throw error;
+        return await openHistoricalSource(params.sourcePath, identity, params.readWrite, links);
+    }
+    try {
+        inspectSourceDescriptor(provisional, identity, links);
+        return provisional;
+    }
+    catch (error) {
+        if (!hasCode(error, ["EACCES", "EPERM"])) {
+            return await throwAfterClosing(error, [provisional]);
+        }
+    }
+    let fallback;
+    try {
+        fallback = await fs.open(params.sourcePath, historicalOpenFlags(params.readWrite));
+        inspectSourceDescriptor(fallback, identity, links);
+        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, links, "isolated producer path");
+        assertParents(params);
+    }
+    catch (error) {
+        return await throwAfterClosing(error, [fallback, provisional]);
+    }
+    try {
+        await provisional.close();
+    }
+    catch (error) {
+        return await throwAfterClosing(error, [fallback]);
+    }
+    return fallback;
+}
+function assertLinkedHandoff(params, handle, identity) {
+    assertParents(params);
+    inspectSourceDescriptor(handle, identity, 2n);
+    inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 2n, "isolated producer path");
+    inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 2n, "isolated producer sibling");
+}
+export async function handoffPrivateProducerFile(params) {
+    assertParents(params);
+    const identity = inspectFileIdentitySync(() => {
+        const stat = fsSync.lstatSync(params.sourcePath, { bigint: true });
+        assertInitialSource(stat);
+        return stat;
+    });
+    let handle;
+    let siblingHandle;
+    let unregister;
+    const state = { siblingOwned: false };
+    try {
+        handle = await openProducerSource(params, identity);
+        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 1n, "isolated producer path");
+        assertParents(params);
+        unregister = registerTempPathForExit(params.targetPath, {
+            cleanupSync: () => removeSiblingIfOwned({
+                assertTargetParent: params.assertTargetParent,
+                identity,
+                state,
+                targetPath: params.targetPath,
+            }),
+        });
+        assertParents(params);
+        try {
+            fsSync.linkSync(params.sourcePath, params.targetPath);
+        }
+        catch (error) {
+            throw normalizeLinkError(error);
+        }
+        state.siblingOwned = true;
+        assertLinkedHandoff(params, handle, identity);
+        if (process.platform === "win32") {
+            // Legacy Windows unlink retains a delete-pending name until handles
+            // opened through that name close. Transfer the pin before retiring it.
+            siblingHandle = await openProducerSource({ ...params, sourcePath: params.targetPath }, identity, 2n);
+            assertLinkedHandoff(params, siblingHandle, identity);
+            inspectSourceDescriptor(handle, identity, 2n);
+            await handle.close();
+            handle = siblingHandle;
+            siblingHandle = undefined;
+            // The old handle's close yielded; both names must still be ours.
+            assertLinkedHandoff(params, handle, identity);
+        }
+        assertParents(params);
+        fsSync.unlinkSync(params.sourcePath);
+        assertParents(params);
+        const opened = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
+        const sibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
+        const originalMode = identity.mode & 511n;
+        if (process.platform === "win32" && (originalMode & 128n) === 0n &&
+            ((opened.mode & 511n) !== originalMode || (sibling.mode & 511n) !== originalMode)) {
+            // Legacy unlink clears the shared read-only attribute. Repair only the
+            // admitted sibling inode, without reopening or chmodding its pathname.
+            assertParents(params);
+            fsSync.fchmodSync(handle.fd, Number(originalMode));
+            assertParents(params);
+            const restored = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
+            const restoredSibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
+            if ((restored.mode & 511n) !== originalMode || (restoredSibling.mode & 511n) !== originalMode) {
+                throw pathMismatch("isolated producer read-only mode could not be restored");
+            }
+        }
+        const registered = unregister;
+        const release = (() => {
+            state.siblingOwned = false;
+            registered();
+        });
+        release.setIdentity = registered.setIdentity;
+        return { handle, identity, unregister: release };
+    }
+    catch (error) {
+        const settlement = [];
+        if (unregister) {
+            try {
+                removeSiblingIfOwned({
+                    assertTargetParent: params.assertTargetParent,
+                    identity,
+                    state,
+                    targetPath: params.targetPath,
+                });
+                unregister();
+            }
+            catch (cleanupError) {
+                settlement.push(cleanupError);
+            }
+        }
+        for (const retained of new Set([siblingHandle, handle])) {
+            if (!retained)
+                continue;
+            try {
+                await retained.close();
+            }
+            catch (closeError) {
+                settlement.push(closeError);
+            }
+        }
+        throw combinedFailure(error, settlement);
+    }
+}

package/dist/private-temp-workspace.d.ts

@@ -1,43 +1,6 @@
-import { type FileStore, type FileStoreSync } from "./file-store.js";
-import { type TempPathIdentityReceipt } from "./temp-cleanup.js";
-import { type TempWorkspaceCleanupResult, type TempWorkspaceCleanupSafety } from "./temp-workspace-owner.js";
+import type { TempWorkspaceOptions, TempWorkspace, TempWorkspaceSync } from "./temp-workspace-types.js";
 export type { TempWorkspaceCleanupResult, TempWorkspaceCleanupSafety, } from "./temp-workspace-owner.js";
-export type TempWorkspaceOptions = {
-    rootDir: string;
-    prefix: string;
-    dirMode?: number;
-    mode?: number;
-    cleanupSafety?: TempWorkspaceCleanupSafety;
-};
-export type TempWorkspace = {
-    dir: string;
-    identity: TempPathIdentityReceipt;
-    store: FileStore;
-    path(fileName: string): string;
-    write(fileName: string, data: string | Uint8Array): Promise<string>;
-    writeText(fileName: string, data: string): Promise<string>;
-    writeJson(fileName: string, data: unknown, options?: {
-        trailingNewline?: boolean;
-    }): Promise<string>;
-    copyIn(fileName: string, sourcePath: string): Promise<string>;
-    read(fileName: string): Promise<Buffer>;
-    cleanup(): Promise<TempWorkspaceCleanupResult>;
-    [Symbol.asyncDispose](): Promise<void>;
-};
-export type TempWorkspaceSync = {
-    dir: string;
-    identity: TempPathIdentityReceipt;
-    store: FileStoreSync;
-    path(fileName: string): string;
-    write(fileName: string, data: string | Uint8Array): string;
-    writeText(fileName: string, data: string): string;
-    writeJson(fileName: string, data: unknown, options?: {
-        trailingNewline?: boolean;
-    }): string;
-    read(fileName: string): Buffer;
-    cleanup(): TempWorkspaceCleanupResult;
-    [Symbol.dispose](): void;
-};
+export type { TempWorkspaceOptions, TempWorkspace, TempWorkspaceSync } from "./temp-workspace-types.js";
 export declare function tempWorkspace(options: TempWorkspaceOptions): Promise<TempWorkspace>;
 export declare function withTempWorkspace<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspace) => Promise<T>): Promise<T>;
 export declare function tempWorkspaceSync(options: TempWorkspaceOptions): TempWorkspaceSync;

package/dist/private-temp-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAExG,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AA8OxG,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC,CAOZ;AA6JD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAEnB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,CAAC,GACvC,CAAC,CAOH"}