@openclaw/fs-safe 0.7.1 → 0.8.0

package/dist/root-write-verification.d.ts

@@ -1,4 +1,4 @@
-import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { PublishedWriteIdentity } from "./pinned-write.js";
 import { type RootContext } from "./root-context.js";
 export declare function verifyAtomicWriteResult(params: {
@@ -6,6 +6,7 @@ export declare function verifyAtomicWriteResult(params: {
     targetPath: string;
     fd: number;
     expectedIdentity: PublishedWriteIdentity;
-    parentGuard: AsyncDirectoryGuard;
+    expectedMode?: number;
+    parentGuard: AnyAsyncDirectoryGuard;
 }): Promise<void>;
 //# sourceMappingURL=root-write-verification.d.ts.map

package/dist/root-write-verification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-write-verification.d.ts","sourceRoot":"","sources":["../src/root-write-verification.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAK3F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,WAAW,EAAE,mBAAmB,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6EhB"}
+{"version":3,"file":"root-write-verification.d.ts","sourceRoot":"","sources":["../src/root-write-verification.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAK9F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFhB"}

package/dist/root-write-verification.js

@@ -35,6 +35,12 @@ export async function verifyAtomicWriteResult(params) {
             throw new FsSafeError("path-mismatch", "descriptor changed during write");
         }
         assertFile(stat);
+        if (process.platform !== "win32" && params.expectedMode !== undefined) {
+            const actualMode = Number(stat.mode & 4095n);
+            if (actualMode !== params.expectedMode) {
+                throw new Error(`Private secret file ${params.targetPath} has insecure permissions ${actualMode.toString(8)}.`);
+            }
+        }
         return stat;
     };
     try {

package/dist/secret-file.d.ts

@@ -1,3 +1,5 @@
+import { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type SecretFileReadOptions } from "./secret-read-policy.js";
 export declare const PRIVATE_SECRET_DIR_MODE = 448;
 export declare const PRIVATE_SECRET_FILE_MODE = 384;
@@ -10,6 +12,13 @@ type SecretFileWriteParams = {
     mode?: number;
     dirMode?: number;
 };
+export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): Promise<{
+    mode: number;
+    rootGuard: AsyncDirectoryGuard<BigIntStats>;
+    parentGuard: AsyncDirectoryGuard<BigIntStats>;
+    fileName: string;
+    finalFilePath: string;
+}>;
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
 export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAwER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AAkID,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAkEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAM/C,OAAO,EAAkF,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAShJ,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAwER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AA8JD,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAYF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAuBD;AAuDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}

package/dist/secret-file.js

@@ -1,18 +1,20 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 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 { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
+import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
+import { assertOwnedDirectory } from "./directory-mode-owner.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 { ensureTrailingSep } from "./root-context.js";
+import { verifyAtomicWriteResult } from "./root-write-verification.js";
 import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
-import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
@@ -104,95 +106,131 @@ function assertRealPathWithinRoot(rootDir, targetPath) {
         throw new Error(`Private secret path must stay under ${rootDir}.`);
     }
 }
-async function enforcePrivatePathMode(resolvedPath, expectedMode, kind) {
-    if (process.platform === "win32") {
-        return;
+async function createPrivateDirectory(directory, mode) {
+    try {
+        await fsp.mkdir(directory, { mode });
+        return true;
     }
-    await fsp.chmod(resolvedPath, expectedMode);
-    const stat = await fsp.stat(resolvedPath);
-    const actualMode = stat.mode & 0o777;
-    if (actualMode !== expectedMode) {
-        throw new Error(`Private secret ${kind} ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
     }
 }
-async function enforcePrivateFileIdentityAndMode(resolvedPath, expectedIdentity, expectedMode) {
-    const handle = await fsp.open(resolvedPath, resolveReadOpenFlags());
-    try {
-        const openedStat = await handle.stat();
-        if (!openedStat.isFile() || !sameFileIdentity(openedStat, expectedIdentity)) {
-            throw new FsSafeError("path-mismatch", "private secret file changed during write");
-        }
-        const pathStat = await fsp.lstat(resolvedPath);
-        if (pathStat.isSymbolicLink() || !sameFileIdentity(pathStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", "private secret path changed during write");
-        }
-        if (process.platform !== "win32") {
-            await handle.chmod(expectedMode);
-            const chmodStat = await handle.stat();
-            const actualMode = chmodStat.mode & 0o777;
-            if (actualMode !== expectedMode) {
-                throw new Error(`Private secret file ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
-            }
-            const refreshedPathStat = await fsp.lstat(resolvedPath);
-            if (refreshedPathStat.isSymbolicLink() || !sameFileIdentity(refreshedPathStat, chmodStat)) {
-                throw new FsSafeError("path-mismatch", "private secret path changed during mode check");
-            }
+async function enforcePrivateDirectoryMode(params) {
+    if (process.platform === "win32")
+        return;
+    const stat = await inspectDirectoryIdentity(params.realPath, params.identity);
+    if (!params.created) {
+        const actualMode = Number(stat.mode & 4095n);
+        if (actualMode !== params.mode) {
+            throw new FsSafeError("insecure-permissions", `Private secret directory ${JSON.stringify(params.realPath)} has insecure permissions ${actualMode.toString(8)}.`);
         }
+        return;
+    }
+    const ownerUid = process.geteuid?.();
+    if (ownerUid === undefined) {
+        throw new FsSafeError("helper-unavailable", "secret directory initialization requires owner identity");
+    }
+    const owner = await pinNodeDirectoryForMode(params.realPath, {
+        expectedIdentity: params.identity,
+        ownerUid,
+    });
+    try {
+        await owner.apply(params.mode, { beforeChmod: params.beforeChmod });
     }
     finally {
-        await handle.close().catch(() => undefined);
+        await owner.close();
     }
 }
+async function inspectPrivateDirectory(directory, kind) {
+    return await inspectFileIdentity(async () => {
+        const stat = await fsp.lstat(directory, { bigint: true });
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Private secret ${kind} ${directory} must not be a symlink.`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`Private secret ${kind} ${directory} must be a directory.`);
+        }
+        return stat;
+    });
+}
 async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     const resolvedRoot = path.resolve(rootDir);
     const resolvedTarget = path.resolve(targetDir);
-    await fsp.mkdir(resolvedRoot, { recursive: true, mode });
-    const rootStat = await fsp.lstat(resolvedRoot);
-    if (rootStat.isSymbolicLink()) {
-        throw new Error(`Private secret root ${resolvedRoot} must not be a symlink.`);
-    }
-    if (!rootStat.isDirectory()) {
-        throw new Error(`Private secret root ${resolvedRoot} must be a directory.`);
+    let rootStat = await inspectPrivateDirectory(resolvedRoot, "root").catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+        return undefined;
+    });
+    let createdRoot = false;
+    if (!rootStat) {
+        try {
+            createdRoot = await createPrivateDirectory(resolvedRoot, mode);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await fsp.mkdir(path.dirname(resolvedRoot), { recursive: true, mode });
+            createdRoot = await createPrivateDirectory(resolvedRoot, mode);
+        }
+        rootStat = await inspectPrivateDirectory(resolvedRoot, "root");
     }
-    const rootGuard = await createAsyncDirectoryGuard(resolvedRoot);
-    await enforcePrivatePathMode(rootGuard.realPath, mode, "directory");
+    const rootGuard = await createAsyncDirectoryGuard(resolvedRoot, { bigint: true });
+    assertOwnedDirectory(rootStat, rootGuard.stat);
+    await enforcePrivateDirectoryMode({
+        realPath: rootGuard.realPath, identity: rootStat, mode, created: createdRoot,
+        beforeChmod: () => assertAsyncDirectoryGuard(rootGuard),
+    });
     await assertAsyncDirectoryGuard(rootGuard);
     if (resolvedTarget === resolvedRoot) {
-        return { rootGuard, targetReal: rootGuard.realPath };
+        return { rootGuard, parentGuard: rootGuard };
     }
     assertPathWithinRoot(resolvedRoot, resolvedTarget);
     const resolvedRootReal = rootGuard.realPath;
     let current = resolvedRoot;
+    let targetGuard = rootGuard;
     for (const segment of path
         .relative(resolvedRoot, resolvedTarget)
         .split(path.sep)
         .filter(Boolean)) {
         current = path.join(current, segment);
-        const parentGuard = await createAsyncDirectoryGuard(path.dirname(current));
-        await assertAsyncDirectoryGuard(rootGuard);
-        try {
-            const stat = await fsp.lstat(current);
-            if (stat.isSymbolicLink()) {
-                throw new Error(`Private secret directory component ${current} must not be a symlink.`);
-            }
-            if (!stat.isDirectory()) {
-                throw new Error(`Private secret directory component ${current} must be a directory.`);
+        const parentGuard = targetGuard;
+        let created = false;
+        let identity;
+        while (true) {
+            await assertAsyncDirectoryGuard(rootGuard);
+            await assertAsyncDirectoryGuard(parentGuard);
+            try {
+                identity = await inspectPrivateDirectory(current, "directory component");
+                break;
             }
-        }
-        catch (error) {
-            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
-                throw error;
+            catch (error) {
+                if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+                    throw error;
+                }
+                await assertAsyncDirectoryGuard(parentGuard);
+                created = await createPrivateDirectory(current, mode);
+                // EEXIST grants no initialization authority; both outcomes need fresh type checks.
             }
-            await assertAsyncDirectoryGuard(parentGuard);
-            await fsp.mkdir(current, { mode });
         }
-        const currentReal = await fsp.realpath(current);
-        assertRealPathWithinRoot(resolvedRootReal, currentReal);
-        await enforcePrivatePathMode(currentReal, mode, "directory");
+        const currentGuard = await createAsyncDirectoryGuard(current, { bigint: true });
+        assertOwnedDirectory(identity, currentGuard.stat);
+        assertRealPathWithinRoot(resolvedRootReal, currentGuard.realPath);
+        await enforcePrivateDirectoryMode({
+            realPath: currentGuard.realPath, identity, mode, created,
+            beforeChmod: async () => {
+                await assertAsyncDirectoryGuard(parentGuard);
+                await assertAsyncDirectoryGuard(rootGuard);
+                await assertAsyncDirectoryGuard(currentGuard);
+            },
+        });
         await assertAsyncDirectoryGuard(parentGuard);
         await assertAsyncDirectoryGuard(rootGuard);
+        await assertAsyncDirectoryGuard(currentGuard);
+        targetGuard = currentGuard;
     }
-    return { rootGuard, targetReal: await fsp.realpath(resolvedTarget) };
+    return { rootGuard, parentGuard: targetGuard };
 }
 async function secretFileWriteQueueKey(filePath) {
     try {
@@ -203,19 +241,29 @@ async function secretFileWriteQueueKey(filePath) {
         return path.resolve(filePath);
     }
 }
-async function materializeSecretFileAtomic(params, createOnly) {
+// Internal preparation for private writers and their pre-write locks; not lasting authorization.
+export async function prepareSecretFileWrite(params) {
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
     const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
     const resolvedRoot = path.resolve(params.rootDir);
     const resolvedFile = path.resolve(params.filePath);
     assertPathWithinRoot(resolvedRoot, resolvedFile);
+    for (const [kind, value] of [["file", mode], ["directory", dirMode]]) {
+        if (!Number.isInteger(value) || value < 0 || value > 0o7777) {
+            throw new FsSafeError("invalid-path", `Private secret ${kind} mode must be an integer between 0o0000 and 0o7777.`);
+        }
+    }
     const intendedParentDir = path.dirname(resolvedFile);
-    const { rootGuard, targetReal } = await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
+    const { rootGuard, parentGuard } = await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
     await assertAsyncDirectoryGuard(rootGuard);
-    assertRealPathWithinRoot(rootGuard.realPath, targetReal);
-    const parentGuard = await createAsyncDirectoryGuard(targetReal);
+    await assertAsyncDirectoryGuard(parentGuard);
+    assertRealPathWithinRoot(rootGuard.realPath, parentGuard.realPath);
     const fileName = path.basename(resolvedFile);
-    const finalFilePath = path.join(targetReal, fileName);
+    const finalFilePath = path.join(parentGuard.realPath, fileName);
+    return { mode, rootGuard, parentGuard, fileName, finalFilePath };
+}
+async function materializeSecretFileAtomic(params, createOnly) {
+    const { mode, rootGuard, parentGuard, fileName, finalFilePath } = await prepareSecretFileWrite(params);
     try {
         const stat = await fsp.lstat(finalFilePath);
         if (createOnly) {
@@ -235,7 +283,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
     }
     await assertAsyncDirectoryGuard(rootGuard);
     await assertAsyncDirectoryGuard(parentGuard);
-    const identity = await runPinnedWriteHelper({
+    await runPinnedWriteHelper({
         rootPath: parentGuard.realPath,
         relativeParentPath: "",
         basename: fileName,
@@ -244,10 +292,24 @@ async function materializeSecretFileAtomic(params, createOnly) {
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
+        verifyPublished: async (fd, expectedIdentity, publishedParentGuard) => {
+            await assertAsyncDirectoryGuard(rootGuard);
+            await assertAsyncDirectoryGuard(parentGuard);
+            await verifyAtomicWriteResult({
+                root: {
+                    rootDir: rootGuard.dir,
+                    rootReal: rootGuard.realPath,
+                    rootWithSep: ensureTrailingSep(rootGuard.realPath),
+                    rootIdentity: { dev: rootGuard.stat.dev, ino: rootGuard.stat.ino },
+                },
+                targetPath: finalFilePath,
+                fd,
+                expectedIdentity,
+                expectedMode: mode,
+                parentGuard: publishedParentGuard,
+            });
+        },
     });
-    await assertAsyncDirectoryGuard(rootGuard);
-    await assertAsyncDirectoryGuard(parentGuard);
-    await enforcePrivateFileIdentityAndMode(finalFilePath, identity, mode);
 }
 export async function writeSecretFileAtomic(params) {
     const canonicalPath = await secretFileWriteQueueKey(params.filePath);

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

@@ -1 +1 @@
-{"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"}
+{"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;AAwBD,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,7 +2,7 @@ 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 { sanitizeUntrustedFileName } from "./filename.js";
+import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
 import { applyDirectoryMode } from "./replace-file-descriptor.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
@@ -42,8 +42,14 @@ function buildSiblingTempPath(params) {
     const safePrefix = assertSafePathPrefix(params.tempPrefix, {
         label: "sibling temp prefix",
     });
-    const safeTail = sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName);
-    return path.join(path.dirname(params.targetPath), `${safePrefix}${id}-${safeTail}.part`);
+    const prefix = `${safePrefix}${id}-`;
+    const suffix = ".part";
+    const safeTail = fitFileNameToPortableComponent({
+        prefix,
+        fileName: sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName),
+        suffix,
+    });
+    return path.join(path.dirname(params.targetPath), `${prefix}${safeTail}${suffix}`);
 }
 export async function writeViaSiblingTempPath(params) {
     const rootDir = await fs

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":"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"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAOA,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;AAqBF,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,CA+S5B"}

package/dist/sidecar-lock-acquire.js

@@ -1,15 +1,25 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
+import { fileObservation } from "./file-observation.js";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
 import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
-async function resolveNormalizedTargetPath(targetPath) {
+async function resolveNormalizedTargetPath(targetPath, lockRoot) {
     const resolved = path.resolve(targetPath);
     const dir = path.dirname(resolved);
+    if (lockRoot) {
+        // The target is an arbitration key, not necessarily inside the lock Root.
+        // Leave parent creation to the Root-backed sidecar write.
+        await lockRoot.resolve(".");
+        const parent = await canonicalPathFromExistingAncestor(dir);
+        await lockRoot.resolve(".");
+        return path.join(parent, path.basename(resolved));
+    }
     await fs.mkdir(dir, { recursive: true });
     try {
         return path.join(await fs.realpath(dir), path.basename(resolved));
@@ -23,7 +33,7 @@ export async function acquireSidecarLock(options, context) {
     validateSidecarLockRetryOptions(retry);
     validateSidecarLockTimeoutMs(options.timeoutMs);
     context.ensureExitCleanupRegistered();
-    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
+    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
     let held = context.held.get(normalizedTargetPath);
     if (held &&
@@ -47,7 +57,6 @@ export async function acquireSidecarLock(options, context) {
         }
     }
     const startedAt = Date.now();
-    const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let ownsReclaimGuard = false;
     let attempt = 0;
@@ -59,7 +68,7 @@ export async function acquireSidecarLock(options, context) {
         if ((options.timeoutMs !== undefined &&
             options.timeoutMs !== Number.POSITIVE_INFINITY &&
             elapsed >= options.timeoutMs) ||
-            (maxRetries !== undefined && attempt >= maxRetries)) {
+            (retry.retries !== undefined && attempt >= retry.retries)) {
             throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
                 code: "file_lock_timeout",
                 lockPath,
@@ -101,10 +110,14 @@ export async function acquireSidecarLock(options, context) {
                 if (options.lockRoot) {
                     const lockRoot = options.lockRoot;
                     const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
+                    const observation = fileObservation();
                     try {
-                        await lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
+                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 }));
                     }
                     catch (error) {
+                        // Only this invocation's failed exclusive open grants denial retry authority.
+                        lockFileCreateDenied = observation.has(error, `exclusive-create:${lockPath}`) &&
+                            isTransientLockFileDenial(error, lockPath);
                         if (error instanceof FsSafeError && error.code === "already-exists") {
                             throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
                         }

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

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

package/dist/sidecar-lock-reclaim.js

@@ -30,10 +30,12 @@ export function readSidecarLockOwnershipToken(raw) {
 }
 export function serializeSidecarLockPayload(payload) {
     const ownershipToken = createSidecarLockOwnershipToken();
-    return {
-        raw: `${JSON.stringify(payload, null, 2)}\n${ownershipToken}\n`,
-        ownershipToken,
-    };
+    const raw = `${JSON.stringify(payload, null, 2)}\n${ownershipToken}\n`;
+    const bytes = Buffer.byteLength(raw, "utf8");
+    if (bytes > MAX_LOCK_PAYLOAD_BYTES) {
+        throw new FsSafeError("too-large", `sidecar lock payload exceeds limit of ${MAX_LOCK_PAYLOAD_BYTES} bytes (got ${bytes})`);
+    }
+    return { raw, ownershipToken };
 }
 export function relativeSidecarLockPath(lockRoot, lockPath) {
     const resolved = path.resolve(lockPath);

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAsLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAmNjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAU3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -7,6 +7,7 @@ import { createSuppressedError } from "./suppressed-error.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
 const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
+const GLOBAL_BEFORE_EXIT_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanup");
 function getGlobalManagers() {
     const globalWithState = globalThis;
     if (!globalWithState[GLOBAL_STATE_KEY]) {
@@ -117,6 +118,29 @@ function ensureGlobalExitCleanupRegistered() {
     globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
     process.on("exit", cleanup);
 }
+function ensureGlobalBeforeExitCleanupRegistered() {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY]) {
+        return globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY];
+    }
+    // Independent of the exit registration, which an older package copy may own.
+    const lifecycle = { armed: false };
+    globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
+    process.on("beforeExit", () => {
+        if (!lifecycle.armed)
+            return;
+        // Cleanup itself schedules I/O; retry only after another acquisition.
+        lifecycle.armed = false;
+        for (const state of getGlobalManagers().values()) {
+            for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {
+                if (held.lockRoot) {
+                    void releaseHeldLock(state, normalizedTargetPath, held, { force: true }).catch(() => undefined);
+                }
+            }
+        }
+    });
+    return lifecycle;
+}
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
     if (current !== held) {
@@ -158,6 +182,7 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     }
 }
 function handleForHeldLock(state, normalizedTargetPath, held) {
+    ensureGlobalBeforeExitCleanupRegistered().armed = true;
     return createHeldSidecarLockHandle({
         normalizedTargetPath,
         held,
@@ -170,6 +195,7 @@ export function createSidecarLockManager(key) {
         state.cleanupRegistered = true;
         state.reclaimCleanupRegistered = true;
         ensureGlobalExitCleanupRegistered();
+        ensureGlobalBeforeExitCleanupRegistered().armed = true;
     }
     async function acquire(options) {
         return await acquireSidecarLock(options, {

package/dist/write-open-flags.d.ts

@@ -0,0 +1,5 @@
+import fsSync from "node:fs";
+export declare function resolveNonblockingWriteFlag(constants?: Partial<Pick<typeof fsSync.constants, "O_NONBLOCK">>): number;
+export declare function isNonRegularWriteOpenError(error: unknown, filePath: string, flags: number): Promise<boolean>;
+export declare function isNonRegularWriteOpenErrorSync(error: unknown, filePath: string, flags: number): boolean;
+//# sourceMappingURL=write-open-flags.d.ts.map

package/dist/write-open-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}

package/dist/write-open-flags.js

@@ -0,0 +1,35 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { hasNodeErrorCode } from "./path.js";
+export function resolveNonblockingWriteFlag(constants = fsSync.constants) {
+    return process.platform !== "win32" && typeof constants.O_NONBLOCK === "number"
+        ? constants.O_NONBLOCK
+        : 0;
+}
+function isNonblockingWriteEnxio(error, flags) {
+    return hasNodeErrorCode(error, "ENXIO") &&
+        (flags & (fsSync.constants.O_WRONLY | fsSync.constants.O_RDWR)) === fsSync.constants.O_WRONLY &&
+        (flags & resolveNonblockingWriteFlag()) !== 0;
+}
+// A no-reader FIFO rejects a nonblocking write-only open before fstat is possible.
+// Reclassify only a confirmed non-regular path; inconclusive races keep the errno.
+export async function isNonRegularWriteOpenError(error, filePath, flags) {
+    if (!isNonblockingWriteEnxio(error, flags))
+        return false;
+    try {
+        return !(await fs.lstat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isNonRegularWriteOpenErrorSync(error, filePath, flags) {
+    if (!isNonblockingWriteEnxio(error, flags))
+        return false;
+    try {
+        return !fsSync.lstatSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/docs/advanced.md

@@ -49,7 +49,7 @@ root-path result helpers.
 | `assertAbsolutePathInput` | – | Validate a caller-supplied absolute path string. |
 | `ensureAbsoluteDirectory`, `EnsureAbsoluteDirectoryOptions`, `EnsureAbsoluteDirectoryResult` | – | Create a trusted absolute directory path one segment at a time, rejecting symlink or non-directory segments. |
 | `canonicalPathFromExistingAncestor`, `findExistingAncestor` | – | Canonicalize without requiring the leaf to exist. |
-| `resolveAbsolutePathForRead`, `resolveAbsolutePathForWrite`, `ResolvedAbsolutePath`, `ResolvedWritableAbsolutePath`, `AbsolutePathSymlinkPolicy` | – | Validate an absolute path against a symlink policy before opening. |
+| `resolveAbsolutePathForRead`, `resolveAbsolutePathForWrite`, `ResolvedAbsolutePath`, `ResolvedWritableAbsolutePath`, `AbsolutePathSymlinkPolicy` | – | Validate an absolute path against a symlink policy before opening; strict writes reject dangling symlink components rather than treating them as missing. |
 
 `ensureAbsoluteDirectory()` is for paths you already intend to trust as absolute
 locations, such as a configured output root. It does not enforce a root boundary;