@openclaw/fs-safe 0.12.0 → 0.13.0

package/dist/pinned-write.js

@@ -4,7 +4,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
-import { createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.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";
@@ -21,6 +21,7 @@ import { writeAllToFile } from "./write-file-handle.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")
@@ -31,6 +32,7 @@ function assertSafeBasename(basename) {
         basename === "." ||
         basename === ".." ||
         basename.includes("/") ||
+        (process.platform === "win32" && basename.includes("\\")) ||
         basename.includes("\0")) {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
@@ -40,6 +42,10 @@ function assertWithinMaxBytes(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) {
@@ -49,12 +55,54 @@ async function writeStreamToHandle(stream, handle, maxBytes, assertBeforeMutatio
         await writeAllToFile(handle, buffer, { assertBeforeMutation });
     }
 }
+const PINNED_WRITE_SNAPSHOT_KEYS = [
+    "rootPath", "relativeParentPath", "basename", "maxBytes", "rootIdentity",
+];
+const RENAME_POLICY_SNAPSHOT_KEYS = ["targetPath", "renameIdentity"];
+function copyOwnEnumerableExcept(source, excluded) {
+    const owned = {};
+    for (const key of Reflect.ownKeys(source)) {
+        // Node 22's object-rest fast path can read excluded accessors eagerly.
+        // Exclude before even inspecting the descriptor so named authority and
+        // pathname fields remain single-read snapshots on every supported Node.
+        if (excluded.includes(key))
+            continue;
+        if (!Object.getOwnPropertyDescriptor(source, key)?.enumerable)
+            continue;
+        Object.defineProperty(owned, key, {
+            value: Reflect.get(source, key),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return owned;
+}
 export async function runPinnedWriteHelper(params) {
-    const normalizedParams = { ...params, maxBytes: normalizeMaxBytes(params.maxBytes) };
-    assertSafeBasename(params.basename);
+    const { rootPath, relativeParentPath, basename, maxBytes, rootIdentity } = params;
+    const ownedParams = copyOwnEnumerableExcept(params, PINNED_WRITE_SNAPSHOT_KEYS);
+    const normalizedParams = {
+        ...ownedParams,
+        rootPath,
+        relativeParentPath,
+        basename,
+        maxBytes: normalizeMaxBytes(maxBytes),
+        rootIdentity,
+    };
+    assertSafeBasename(normalizedParams.basename);
     validatePinnedOperationPayload({
-        relativeParentPath: params.relativeParentPath,
+        relativeParentPath: normalizedParams.relativeParentPath,
     });
+    assertNoWindowsPathAlias(normalizedParams.rootPath, "filesystem", "pinned write root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(normalizedParams.relativeParentPath, "relative", "pinned write parent uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(normalizedParams.basename, "relative", "pinned write basename uses a Windows filesystem namespace alias");
+    if (rootIdentity !== undefined) {
+        normalizedParams.rootIdentity = { dev: rootIdentity.dev, ino: rootIdentity.ino };
+    }
+    if (normalizedParams.mutationAdmission) {
+        const targetPath = path.join(normalizedParams.rootPath, ...normalizedParams.relativeParentPath.split("/").filter(Boolean), normalizedParams.basename);
+        await getFsSafeTestHooks()?.beforePinnedWriteParentAdmission?.(targetPath);
+    }
     // The explicit compatibility policy uses the guarded Node fallback, where
     // content verification can replace the strict post-rename inode check.
     if (normalizedParams.onRenameIdentityMismatch === "verify-content") {
@@ -67,51 +115,137 @@ export async function runPinnedWriteHelper(params) {
     return await runPinnedWriteFallback(normalizedParams);
 }
 export async function runPinnedWriteWithRenamePolicy(params) {
-    const { targetPath, renameIdentity, ...writeParams } = params;
+    const { targetPath, renameIdentity } = params;
+    const writeParams = copyOwnEnumerableExcept(params, RENAME_POLICY_SNAPSHOT_KEYS);
     if (renameIdentity !== "verify-content-with-lock") {
         return await runPinnedWriteHelper(writeParams);
     }
     const relativeTargetPath = writeParams.relativeParentPath
         ? `${writeParams.relativeParentPath}/${writeParams.basename}`
         : writeParams.basename;
-    const lockPath = path.join(writeParams.rootPath, `.fs-safe-write-${sha256Hex(relativeTargetPath)}.lock`);
-    return await withSidecarLock(writeParams.rootPath, {
-        managerKey: `fs-safe.write:${targetPath}`,
+    return await withPinnedWriteRenameIdentityLock({
+        rootPath: writeParams.rootPath, targetPath, relativeTargetPath,
+    }, async () => await runPinnedWriteHelper({
+        ...writeParams,
+        onRenameIdentityMismatch: "verify-content",
+    }));
+}
+export async function withPinnedWriteRenameIdentityLock(params, run) {
+    const lockPath = path.join(params.rootPath, `.fs-safe-write-${sha256Hex(params.relativeTargetPath)}.lock`);
+    return await withSidecarLock(params.rootPath, {
+        managerKey: `fs-safe.write:${params.targetPath}`,
         lockPath,
         staleMs: 30_000,
         timeoutMs: 5_000,
         payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
         retry: { retries: 5, minTimeout: 100, maxTimeout: 2_000, factor: 2 },
-    }, async () => await runPinnedWriteHelper({
-        ...writeParams,
-        onRenameIdentityMismatch: "verify-content",
-    }));
+    }, run);
 }
 async function runPinnedWriteFallback(params) {
     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;
     if (exactRoot)
         await inspectDirectoryIdentity(params.rootPath, exactRoot);
     let parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
-    if (params.mkdir) {
+    let parentGuard;
+    let parentAdmitted = false;
+    const initialTargetPath = path.join(parentPath, params.basename);
+    const retainedTargetPath = mutationAdmission?.beginParentWalk?.();
+    const ordinaryRetainedTarget = retainedTargetPath !== undefined &&
+        path.relative(path.resolve(retainedTargetPath), path.resolve(initialTargetPath)) === "";
+    let fastGuardClassifierFailure;
+    if (ordinaryRetainedTarget) {
+        try {
+            parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+        }
+        catch (error) {
+            // Only a genuinely missing complete parent may enter the component
+            // creator. ENOTDIR, permission, identity, and canonicalization failures
+            // retain their original fail-closed result.
+            if (error?.code !== "ENOENT") {
+                if (!fastParentGuardDeopt(error))
+                    throw error;
+                fastGuardClassifierFailure = error;
+            }
+        }
+        if (parentGuard) {
+            await mutationAdmission.authorize(Object.freeze({
+                targetPath: initialTargetPath,
+                mutationPath: initialTargetPath,
+                phase: "parent",
+            }));
+            await assertAsyncDirectoryGuard(parentGuard);
+            parentAdmitted = true;
+        }
+    }
+    if (fastGuardClassifierFailure) {
+        // The optimized exact-guard classifier runs before policy admission. Let
+        // the established resolver restore deny/symlink precedence before using
+        // the guarded walker or reporting the classifier failure. Because this
+        // was not an ENOENT probe, it may never authorize a newly missing parent.
+        await mutationAdmission.authorize(Object.freeze({
+            targetPath: initialTargetPath,
+            mutationPath: initialTargetPath,
+            phase: "parent",
+        }));
+    }
+    if (params.mkdir && !parentGuard) {
         // mkdirPathComponentsWithGuards may resolve the final component through
         // an in-root symlink (e.g. a skill-bank layout). Use its returned real
         // path for the subsequent guard and target path so we don't re-check the
         // original, possibly-symlinked, lexical path and reject it outright.
-        parentPath = await mkdirPathComponentsWithGuards({
+        const mkdirParams = {
             rootReal: params.rootPath,
             targetPath: parentPath,
             rootIdentity: params.rootIdentity,
             assertBeforeMutation: params.assertBeforeMutation,
-            beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
-        });
+            beforeComponent: async (componentPath) => {
+                await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath);
+            },
+        };
+        parentPath = await mkdirPathComponentsWithGuards(mutationAdmission ? {
+            ...mkdirParams,
+            rejectSymlinks: mutationAdmission.rejectParentSymlinks,
+            revalidateParentAfterBeforeComponent: true,
+            synchronousAuthorizationIncludesFence: true,
+            retainedTargetPath,
+            afterCreateComponent: mutationAdmission.advanceCreatedDirectory,
+            beforeCreateComponent: (componentPath, prospectiveParentPath, retainedTarget, parent) => {
+                if (fastGuardClassifierFailure)
+                    throw fastGuardClassifierFailure;
+                const request = Object.freeze({
+                    targetPath: retainedTarget ?? path.join(prospectiveParentPath, params.basename),
+                    mutationPath: componentPath,
+                    phase: "parent-create",
+                });
+                return mutationAdmission.tryAuthorizeAtParent?.(request, parent) ??
+                    mutationAdmission.authorize(request);
+            },
+            beforeUseComponent: async (_componentPath, prospectiveParentPath, retainedTarget) => {
+                const targetPath = retainedTarget ?? path.join(prospectiveParentPath, params.basename);
+                await mutationAdmission.authorize(Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                }));
+            },
+        } : mkdirParams);
     }
-    const parentGuard = params.mkdir
+    parentGuard ??= params.mkdir
         ? await createAsyncDirectoryGuard(parentPath, { bigint: true })
         : await createNearestExistingDirectoryGuard(params.rootPath, parentPath, { bigint: true });
     const targetPath = path.join(parentPath, params.basename);
+    if (mutationAdmission && !parentAdmitted) {
+        await mutationAdmission.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+    }
     if (params.overwrite === false && (params.input.kind === "buffer" ||
         (params.input.kind === "stream" && !params.input.stageBeforePublish))) {
         const assertBeforeMutation = () => {

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

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

package/dist/private-directory.js

@@ -1,10 +1,12 @@
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function createPrivateDirectory(targetPath, options) {
     const platform = options?.platform ?? process.platform;
     if (platform !== "win32") {
         throw new FsSafeError("helper-unavailable", "private-directory creation is supported only on Windows");
     }
+    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; " +

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

@@ -0,0 +1,16 @@
+import { type BigIntStats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+import { type TempPathRegistration } from "./temp-cleanup.js";
+export type PrivateProducerHandoff = {
+    handle: FileHandle;
+    identity: BigIntStats;
+    unregister: TempPathRegistration;
+};
+export declare function handoffPrivateProducerFile(params: {
+    sourcePath: string;
+    targetPath: string;
+    assertSourceParent: () => void;
+    assertTargetParent: () => void;
+    readWrite: boolean;
+}): Promise<PrivateProducerHandoff>;
+//# sourceMappingURL=private-producer-handoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"private-producer-handoff.d.ts","sourceRoot":"","sources":["../src/private-producer-handoff.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKvD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,oBAAoB,CAAC;CAClC,CAAC;AA2OF,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA6HlC"}

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"}