@openclaw/fs-safe 0.6.0 → 0.7.1

package/dist/secret-file.js

@@ -3,11 +3,13 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
 import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
@@ -19,7 +21,9 @@ export function readSecretFileSync(filePath, label, options = {}) {
     if (!resolvedPath) {
         throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
     }
-    const maxBytes = options.maxBytes ?? DEFAULT_SECRET_FILE_MAX_BYTES;
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
+    });
     function inspectInput(symlinkMessage) {
         const stat = options.rejectSymlink
             ? fs.lstatSync(resolvedPath, { bigint: true })
@@ -112,8 +116,7 @@ async function enforcePrivatePathMode(resolvedPath, expectedMode, kind) {
     }
 }
 async function enforcePrivateFileIdentityAndMode(resolvedPath, expectedIdentity, expectedMode) {
-    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0;
-    const handle = await fsp.open(resolvedPath, fs.constants.O_RDONLY | noFollowFlag);
+    const handle = await fsp.open(resolvedPath, resolveReadOpenFlags());
     try {
         const openedStat = await handle.stat();
         if (!openedStat.isFile() || !sameFileIdentity(openedStat, expectedIdentity)) {

package/dist/secret-read-async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAgEjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA8DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/secret-read-async.js

@@ -1,8 +1,10 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 export async function readSecretFile(filePath, label, options = {}) {
@@ -10,7 +12,9 @@ export async function readSecretFile(filePath, label, options = {}) {
     if (!resolvedPath) {
         throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
     }
-    const maxBytes = options.maxBytes ?? DEFAULT_SECRET_FILE_MAX_BYTES;
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
+    });
     async function inspectInput(symlinkMessage) {
         const stat = options.rejectSymlink
             ? await fs.lstat(resolvedPath, { bigint: true })
@@ -32,10 +36,7 @@ export async function readSecretFile(filePath, label, options = {}) {
     let raw;
     try {
         const realPath = await fs.realpath(resolvedPath);
-        const noFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
-            ? fsSync.constants.O_NOFOLLOW
-            : 0;
-        handle = await fs.open(realPath, fsSync.constants.O_RDONLY | noFollow);
+        handle = await fs.open(realPath, resolveReadOpenFlags());
         const openedHandle = handle;
         const openedStat = await inspectFileIdentity(async () => {
             const stat = await openedHandle.stat({ bigint: true });

package/dist/secure-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAYrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAM1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAyLF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAarC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AA4LF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAe/B"}

package/dist/secure-file.js

@@ -1,16 +1,15 @@
-import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
 import { isPathInside, isSymlinkOpenError } from "./path.js";
 import { formatPermissionErrorDetail } from "./permission-exec.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
-const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 function isAbsolutePathname(value) {
     return (path.isAbsolute(value) ||
         (process.platform === "win32" &&
@@ -19,7 +18,7 @@ function isAbsolutePathname(value) {
 function label(options) {
     return options.label ?? "Secure file";
 }
-async function openSecureHandle(options) {
+async function openSecureHandle(options, maxBytes) {
     assertNoUnsafeDeviceReadPath(options.filePath);
     if (isWindowsNetworkPath(options.filePath, "win32") && !options.trust?.allowNetworkPath) {
         throw new FsSafeError("invalid-path", `${label(options)} must be a local absolute path.`);
@@ -32,15 +31,19 @@ async function openSecureHandle(options) {
             cause: err,
         });
     });
-    if (preStat.isDirectory()) {
-        throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
+    if (preStat.isSymbolicLink()) {
+        if (!options.trust?.allowSymlink) {
+            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+        }
     }
-    if (preStat.isSymbolicLink() && !options.trust?.allowSymlink) {
-        throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+    else if (!preStat.isFile()) {
+        throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
     }
     let handle;
     try {
-        handle = await fs.open(options.filePath, options.trust?.allowSymlink ? fsConstants.O_RDONLY : OPEN_READ_FLAGS);
+        handle = await fs.open(options.filePath, resolveReadOpenFlags({
+            followSymlinks: options.trust?.allowSymlink === true,
+        }));
     }
     catch (err) {
         if (isSymlinkOpenError(err)) {
@@ -65,8 +68,8 @@ async function openSecureHandle(options) {
         }, openedIdentity);
         const realPath = await fs.realpath(options.filePath);
         await inspectFileIdentity(() => fs.stat(realPath, { bigint: true }), openedIdentity);
-        if (options.io?.maxBytes !== undefined && openedStat.size > options.io.maxBytes) {
-            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
+        if (maxBytes !== undefined && openedStat.size > maxBytes) {
+            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${maxBytes}).`);
         }
         return { handle, pathStat: openedStat, realPath };
     }
@@ -165,11 +168,12 @@ async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
     }
 }
 export async function readSecureFile(options) {
-    const opened = await openSecureHandle(options);
+    const maxBytes = normalizeMaxBytes(options.io?.maxBytes);
+    const opened = await openSecureHandle(options, maxBytes);
     try {
         await assertTrustedDirs(options, opened.realPath);
         const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath);
-        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, options.io?.maxBytes);
+        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
         return { buffer, realPath: opened.realPath, stat: opened.pathStat, permissions };
     }
     finally {

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

@@ -0,0 +1,15 @@
+export declare function writeCallbackSibling<T>(params: {
+    tempPath: string;
+    write: (tempPath: string) => Promise<T>;
+    resolveFinalPath: (result: T) => string;
+    mode?: number;
+    /** Preserve the caller's historical best-effort mode behavior. */
+    ignoreModeError?: boolean;
+    maxBytes?: number;
+    syncTempFile: boolean;
+    syncParentDir: boolean;
+}): Promise<{
+    filePath: string;
+    result: T;
+}>;
+//# sourceMappingURL=sibling-staged-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAkCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CA6G3C"}

package/dist/sibling-staged-file.js

@@ -0,0 +1,148 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { serializePathWrite } from "./write-queue.js";
+function assertRegularFile(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink sibling temp not allowed");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "sibling temp must be a regular file");
+    }
+    if (stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", "sibling temp must have exactly one link");
+    }
+}
+async function inspectStage(inspect, expected) {
+    return await inspectFileIdentity(async () => {
+        const stat = await inspect();
+        assertRegularFile(stat);
+        return stat;
+    }, expected);
+}
+// Callback paths are not owned until all three admission observations agree.
+// Keep one descriptor and one exact identity through mode, sync, rename and cleanup.
+// Read/write access is needed only when the caller requests file synchronization.
+export async function writeCallbackSibling(params) {
+    const parent = path.dirname(params.tempPath);
+    const guard = await createAsyncDirectoryGuard(parent);
+    const parentIdentity = await inspectFileIdentity(() => fs.lstat(parent, { bigint: true }));
+    const assertParent = async () => {
+        await assertAsyncDirectoryGuard(guard);
+        await inspectFileIdentity(() => fs.lstat(parent, { bigint: true }), parentIdentity);
+    };
+    let handle;
+    let identity;
+    let unregister;
+    let renamed = false;
+    let failure;
+    const inspectPath = (pathname, expected) => inspectStage(() => fs.lstat(pathname, { bigint: true }), expected);
+    const assertCurrent = async (pathname) => {
+        await assertParent();
+        const opened = await inspectStage(() => handle.stat({ bigint: true }), identity);
+        const current = await inspectPath(pathname, opened);
+        if (params.maxBytes !== undefined &&
+            (opened.size > params.maxBytes || current.size > params.maxBytes)) {
+            throw new FsSafeError("too-large", `sibling temp exceeds maxBytes (${params.maxBytes})`);
+        }
+    };
+    try {
+        const result = await params.write(params.tempPath);
+        await assertParent();
+        const before = await inspectPath(params.tempPath);
+        try {
+            // No create/truncate flags; O_NONBLOCK also bounds a FIFO swap during open.
+            const access = params.syncTempFile ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+            handle = await fs.open(params.tempPath, access | resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (error?.code === "ELOOP") {
+                throw new FsSafeError("symlink", "symlink sibling temp not allowed", { cause: error });
+            }
+            throw error;
+        }
+        const opened = await inspectStage(() => handle.stat({ bigint: true }), before);
+        await inspectPath(params.tempPath, opened);
+        await assertParent();
+        identity = opened;
+        unregister = registerTempPathForExit(params.tempPath, { identity, singleLinkFile: true });
+        const filePath = path.resolve(params.resolveFinalPath(result));
+        if (path.dirname(filePath) !== parent) {
+            throw new Error("Final path must be in the sibling temp directory.");
+        }
+        if (filePath === params.tempPath) {
+            throw new FsSafeError("invalid-path", "final path must differ from the sibling temp path");
+        }
+        await serializePathWrite(filePath, async () => {
+            await assertCurrent(params.tempPath);
+            if (params.mode !== undefined) {
+                try {
+                    await handle.chmod(params.mode);
+                }
+                catch (error) {
+                    if (!params.ignoreModeError)
+                        throw error;
+                }
+            }
+            if (params.syncTempFile) {
+                await assertCurrent(params.tempPath);
+                try {
+                    await handle.sync();
+                }
+                catch (error) {
+                    if (error?.code !== "EPERM")
+                        throw error;
+                }
+            }
+            await assertCurrent(params.tempPath);
+            await fs.rename(params.tempPath, filePath);
+            // A later verification failure never authorizes rollback of the final name.
+            renamed = true;
+            unregister();
+            await assertCurrent(filePath);
+            if (params.syncParentDir)
+                await syncDirectoryBestEffort(parent);
+            await assertCurrent(filePath);
+        });
+        return { filePath, result };
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        try {
+            if (!renamed && identity) {
+                try {
+                    await assertParent();
+                    await inspectStage(() => handle.stat({ bigint: true }), identity);
+                    await inspectPath(params.tempPath, identity);
+                    await fs.unlink(params.tempPath);
+                    unregister?.();
+                }
+                catch (error) {
+                    // Preserve observed substitutes; retry only operational cleanup failures.
+                    if (error instanceof FsSafeError || error?.code === "ENOENT") {
+                        unregister?.();
+                    }
+                }
+            }
+        }
+        finally {
+            try {
+                await handle?.close();
+            }
+            catch (error) {
+                if (failure)
+                    throw new AggregateError([failure.error, error], "sibling publication and close failed");
+                throw error;
+            }
+        }
+    }
+}

package/dist/sibling-temp.d.ts

@@ -5,8 +5,11 @@ export type WriteSiblingTempFileOptions<T> = {
     tempPrefix?: string;
     dirMode?: number;
     chmodDir?: boolean;
+    /** Final file mode; omitted preserves the producer's mode. Applied through the retained descriptor. */
     mode?: number;
+    /** Sync the staged descriptor before rename; defaults to false. */
     syncTempFile?: boolean;
+    /** Best-effort parent directory sync after rename; defaults to false. */
     syncParentDir?: boolean;
 };
 export type WriteSiblingTempFileResult<T> = {

package/dist/sibling-temp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA8BF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CA0CxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AASF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAoBxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ChB"}

package/dist/sibling-temp.js

@@ -2,85 +2,40 @@ import crypto, { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
-import { syncDirectoryBestEffort } from "./directory-durability.js";
-import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { sanitizeUntrustedFileName } from "./filename.js";
+import { applyDirectoryMode } from "./replace-file-descriptor.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
-import { registerTempPathForExit } from "./temp-cleanup.js";
+import { writeCallbackSibling } from "./sibling-staged-file.js";
+import { tempFile } from "./temp-target.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { serializePathWrite } from "./write-queue.js";
 function buildTempPath(dir, tempPrefix) {
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
         label: "sibling temp prefix",
     });
     return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
 }
-async function syncFileBestEffort(filePath) {
-    const handle = await fs.open(filePath, "r+");
-    try {
-        await handle.sync();
-    }
-    catch (error) {
-        if (error.code !== "EPERM") {
-            throw error;
-        }
-    }
-    finally {
-        await handle.close();
-    }
-}
-function assertFinalPathIsSibling(dir, filePath) {
-    const resolvedDir = path.resolve(dir);
-    const resolvedFile = path.resolve(filePath);
-    if (path.dirname(resolvedFile) !== resolvedDir) {
-        throw new Error("Final path must be in the sibling temp directory.");
-    }
-}
 export async function writeSiblingTempFile(options) {
     const dir = path.resolve(options.dir);
     await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
     if (options.chmodDir !== false) {
-        await fs.chmod(dir, options.dirMode ?? 0o700).catch(() => undefined);
-    }
-    const dirGuard = await createAsyncDirectoryGuard(dir);
-    const tempPath = buildTempPath(dir, options.tempPrefix);
-    const unregisterTempPath = registerTempPathForExit(tempPath);
-    let tempExists = false;
-    try {
-        tempExists = true;
-        const result = await options.writeTemp(tempPath);
-        unregisterTempPath.setIdentity(await fs.lstat(tempPath, { bigint: true }));
-        if (options.mode !== undefined) {
-            await fs.chmod(tempPath, options.mode).catch(() => undefined);
-        }
-        if (options.syncTempFile) {
-            await syncFileBestEffort(tempPath);
-        }
-        const filePath = path.resolve(options.resolveFinalPath(result));
-        assertFinalPathIsSibling(dir, filePath);
-        await serializePathWrite(filePath, async () => {
-            await withAsyncDirectoryGuards([dirGuard], async () => {
-                await fs.rename(tempPath, filePath);
-            });
-            tempExists = false;
-            unregisterTempPath();
-            if (options.mode !== undefined) {
-                await fs.chmod(filePath, options.mode).catch(() => undefined);
-            }
-            if (options.syncParentDir) {
-                await syncDirectoryBestEffort(dir);
-            }
+        await applyDirectoryMode({
+            fsModule: fs,
+            dirPath: dir,
+            mode: options.dirMode ?? 0o700,
+            ignoreChmodError: true,
         });
-        return { filePath, result };
-    }
-    finally {
-        if (tempExists) {
-            await fs.rm(tempPath, { force: true }).catch(() => undefined);
-        }
-        unregisterTempPath();
     }
+    return await writeCallbackSibling({
+        tempPath: buildTempPath(dir, options.tempPrefix),
+        write: options.writeTemp,
+        resolveFinalPath: options.resolveFinalPath,
+        mode: options.mode,
+        ignoreModeError: true,
+        syncTempFile: options.syncTempFile === true,
+        syncParentDir: options.syncParentDir === true,
+    });
 }
 function buildSiblingTempPath(params) {
     const id = crypto.randomUUID();
@@ -107,18 +62,20 @@ export async function writeViaSiblingTempPath(params) {
         throw new Error("Target path is outside the allowed root");
     }
     const rootGuard = await createAsyncDirectoryGuard(rootDir);
-    const tempDir = await fs.mkdtemp(path.join(resolveSecureTempRoot({
-        fallbackPrefix: "fs-safe-output",
-        unsafeFallbackLabel: "sibling temp output dir",
-        warn: () => undefined,
-    }), "fs-safe-output-"));
-    const tempPath = buildSiblingTempPath({
-        targetPath: path.join(tempDir, path.basename(targetPath)),
-        fallbackFileName: params.fallbackFileName ?? "output.bin",
-        tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+    const workspace = await tempFile({
+        rootDir: resolveSecureTempRoot({
+            fallbackPrefix: "fs-safe-output",
+            unsafeFallbackLabel: "sibling temp output dir",
+            warn: () => undefined,
+        }),
+        prefix: "fs-safe-output",
     });
-    const unregisterTempPath = registerTempPathForExit(tempDir, { recursive: true });
     try {
+        const tempPath = buildSiblingTempPath({
+            targetPath: path.join(workspace.dir, path.basename(targetPath)),
+            fallbackFileName: params.fallbackFileName ?? "output.bin",
+            tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+        });
         await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
         await params.writeTemp(tempPath);
         await assertAsyncDirectoryGuard(rootGuard);
@@ -127,7 +84,6 @@ export async function writeViaSiblingTempPath(params) {
         await assertAsyncDirectoryGuard(rootGuard);
     }
     finally {
-        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { });
-        unregisterTempPath();
+        await workspace.cleanup();
     }
 }

package/dist/sidecar-lock-acquire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAO3C,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAsP5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAKA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA4S5B"}