@openclaw/fs-safe 0.10.0 → 0.12.0

package/dist/secure-file-windows.js

@@ -0,0 +1,186 @@
+import { FsSafeError } from "./errors.js";
+import { recordFileObservationFailure } from "./file-observation.js";
+import { getNativeBinding } from "./native.js";
+const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
+const SID_RE = /^s-\d+-\d+(?:-\d+)+$/;
+const OWNER_CLASSES = new Set(["current-user", "system", "administrators", "foreign"]);
+const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
+const SYSTEM_SID = "s-1-5-18";
+const ADMINISTRATORS_SID = "s-1-5-32-544";
+const WORLD_SIDS = new Set([
+    "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
+    "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
+]);
+const GENERIC_READ = 0x8000_0000;
+const GENERIC_WRITE = 0x4000_0000;
+const GENERIC_ALL = 0x1000_0000;
+const DELETE_ACCESS = 0x0001_0000;
+const WRITE_DAC = 0x0004_0000;
+const WRITE_OWNER = 0x0008_0000;
+const FILE_READ_DATA = 0x0000_0001;
+const FILE_WRITE_DATA = 0x0000_0002;
+const FILE_APPEND_DATA = 0x0000_0004;
+const FILE_READ_EA = 0x0000_0008;
+const FILE_WRITE_EA = 0x0000_0010;
+const FILE_DELETE_CHILD = 0x0000_0040;
+const FILE_READ_ATTRIBUTES = 0x0000_0080;
+const FILE_WRITE_ATTRIBUTES = 0x0000_0100;
+function permissionUnverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
+}
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isUint32(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff;
+}
+function parseIdentity(value) {
+    if (typeof value !== "string")
+        identityMismatch();
+    const match = IDENTITY_RE.exec(value);
+    if (!match)
+        identityMismatch();
+    return {
+        dev: BigInt(`0x${match[1]}`),
+        ino: BigInt(`0x${match[2]}`),
+    };
+}
+function validateFlags(value) {
+    if (!isRecord(value))
+        return false;
+    const raw = value.raw;
+    if (!isUint32(raw) || (raw & ~0xdf) !== 0)
+        return false;
+    const fields = [
+        ["objectInherit", 0x01], ["containerInherit", 0x02],
+        ["noPropagateInherit", 0x04], ["inheritOnly", 0x08], ["inherited", 0x10],
+        ["successfulAccess", 0x40], ["failedAccess", 0x80],
+    ];
+    return fields.every(([field, bit]) => typeof value[field] === "boolean" && value[field] === ((raw & bit) !== 0));
+}
+function validateAce(value) {
+    return isRecord(value) && typeof value.sid === "string" && SID_RE.test(value.sid) &&
+        isUint32(value.mask) && (value.aceType === "allow" || value.aceType === "deny") &&
+        validateFlags(value.flags);
+}
+function canRead(mask) {
+    return (mask & (GENERIC_ALL | GENERIC_READ | FILE_READ_DATA | FILE_READ_EA |
+        FILE_READ_ATTRIBUTES)) !== 0;
+}
+function canWrite(mask) {
+    return (mask & (GENERIC_ALL | GENERIC_WRITE | FILE_WRITE_DATA | FILE_APPEND_DATA |
+        FILE_WRITE_EA | FILE_WRITE_ATTRIBUTES | FILE_DELETE_CHILD | DELETE_ACCESS |
+        WRITE_DAC | WRITE_OWNER)) !== 0;
+}
+function expectedOwnerClass(facts) {
+    if (facts.ownerSid === facts.currentUserSid)
+        return "current-user";
+    if (facts.ownerSid === SYSTEM_SID)
+        return "system";
+    if (facts.ownerSid === ADMINISTRATORS_SID)
+        return "administrators";
+    return "foreign";
+}
+function validateSecurity(value) {
+    if (!isRecord(value))
+        permissionUnverified("Windows descriptor ACL facts were malformed");
+    const facts = value;
+    const booleans = [
+        "worldWritable", "groupWritable", "worldReadable", "groupReadable",
+        "fallbackRequired", "daclPresent", "isLocal", "aceListComplete",
+    ];
+    if (!booleans.every((field) => typeof facts[field] === "boolean") ||
+        typeof facts.ownerSid !== "string" || !SID_RE.test(facts.ownerSid) ||
+        typeof facts.currentUserSid !== "string" || !SID_RE.test(facts.currentUserSid) ||
+        typeof facts.ownerClass !== "string" || !OWNER_CLASSES.has(facts.ownerClass) ||
+        !Array.isArray(facts.unsupportedAceTypes) ||
+        !facts.unsupportedAceTypes.every(isUint32) ||
+        !Array.isArray(facts.aces) || !facts.aces.every(validateAce)) {
+        permissionUnverified("Windows descriptor ACL facts were malformed");
+    }
+    if (facts.ownerClass !== expectedOwnerClass(facts)) {
+        permissionUnverified("Windows descriptor owner facts were inconsistent");
+    }
+    if (facts.fallbackRequired || !facts.isLocal || !facts.aceListComplete ||
+        facts.unsupportedAceTypes.length !== 0) {
+        permissionUnverified("Windows descriptor ACL facts were incomplete or unsupported");
+    }
+    if (!facts.daclPresent && facts.aces.length !== 0) {
+        permissionUnverified("Windows descriptor DACL facts were inconsistent");
+    }
+    return facts;
+}
+function validatePermissionSummary(facts) {
+    let worldReadable = !facts.daclPresent;
+    let worldWritable = !facts.daclPresent;
+    let groupReadable = false;
+    let groupWritable = false;
+    const trustedSids = new Set([facts.currentUserSid, SYSTEM_SID, ADMINISTRATORS_SID]);
+    for (const ace of facts.aces) {
+        if (ace.aceType !== "allow" || ace.flags.inheritOnly || trustedSids.has(ace.sid))
+            continue;
+        const world = WORLD_SIDS.has(ace.sid);
+        if (world) {
+            worldReadable ||= canRead(ace.mask);
+            worldWritable ||= canWrite(ace.mask);
+        }
+        else {
+            groupReadable ||= canRead(ace.mask);
+            groupWritable ||= canWrite(ace.mask);
+        }
+    }
+    if (facts.worldReadable !== worldReadable || facts.worldWritable !== worldWritable ||
+        facts.groupReadable !== groupReadable || facts.groupWritable !== groupWritable) {
+        permissionUnverified("Windows descriptor ACL summary was inconsistent");
+    }
+}
+export function inspectSecureWindowsDescriptor(params) {
+    let native;
+    try {
+        native = getNativeBinding();
+    }
+    catch (cause) {
+        permissionUnverified("Windows descriptor ACL verification requires the matching native helper", cause);
+    }
+    const inspect = native?.inspectWindowsSecureFileHandle;
+    if (typeof inspect !== "function") {
+        permissionUnverified("Windows descriptor ACL verification requires an up-to-date native helper");
+    }
+    let result;
+    try {
+        result = inspect.call(native, params.fd);
+    }
+    catch (cause) {
+        permissionUnverified("Windows descriptor ACL verification failed", cause);
+    }
+    if (!isRecord(result))
+        permissionUnverified("Windows descriptor ACL facts were malformed");
+    const observed = parseIdentity(result.identity);
+    if (observed.dev !== params.identity.dev || observed.ino !== params.identity.ino) {
+        identityMismatch();
+    }
+    const facts = validateSecurity(result.security);
+    validatePermissionSummary(facts);
+    return {
+        ok: true,
+        isSymlink: false,
+        isDir: params.stat.isDirectory(),
+        mode: typeof params.stat.mode === "number" ? params.stat.mode : null,
+        bits: null,
+        source: "windows-acl",
+        worldWritable: facts.worldWritable,
+        groupWritable: facts.groupWritable,
+        worldReadable: facts.worldReadable,
+        groupReadable: facts.groupReadable,
+        ownerSid: facts.ownerSid,
+        ownerTrusted: TRUSTED_OWNER_CLASSES.has(facts.ownerClass),
+        aclSummary: `native descriptor owner=${facts.ownerClass} world=` +
+            `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
+            `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
+    };
+}

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,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAa7C,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAI1B,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;AAmMF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAe/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAc/D,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,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;AAuNF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CA6B/B"}

package/dist/secure-file.js

@@ -9,8 +9,10 @@ import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-acc
 import { isPathInside, isSymlinkOpenError } from "./path.js";
 import { formatPermissionErrorDetail } from "./permission-exec.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
 import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectSecureWindowsDescriptor } from "./secure-file-windows.js";
 import { scheduleTimeout } from "./timing.js";
 function isAbsolutePathname(value) {
     return (path.isAbsolute(value) ||
@@ -20,6 +22,11 @@ function isAbsolutePathname(value) {
 function label(options) {
     return options.label ?? "Secure file";
 }
+function assertNotHardlinked(options, stat) {
+    if (stat.nlink > 1n) {
+        throw new FsSafeError("hardlink", `${label(options)} must not be hardlinked: ${options.filePath}`);
+    }
+}
 async function openSecureHandle(options, maxBytes) {
     assertNoUnsafeDeviceReadPath(options.filePath);
     if (isWindowsNetworkPath(options.filePath, "win32") && !options.trust?.allowNetworkPath) {
@@ -63,6 +70,7 @@ async function openSecureHandle(options, maxBytes) {
             throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
         }
         const openedIdentity = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }));
+        assertNotHardlinked(options, openedIdentity);
         await inspectFileIdentity(async () => {
             const pathStat = options.trust?.allowSymlink
                 ? fsSync.statSync(options.filePath, { bigint: true })
@@ -70,14 +78,19 @@ async function openSecureHandle(options, maxBytes) {
             if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
                 throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
             }
+            assertNotHardlinked(options, pathStat);
             return pathStat;
         }, openedIdentity);
-        const realPath = fsSync.realpathSync.native(options.filePath);
-        await inspectFileIdentity(() => fsSync.statSync(realPath, { bigint: true }), openedIdentity);
+        const realPath = realpathSync.native(options.filePath);
+        await inspectFileIdentity(() => {
+            const realPathStat = fsSync.statSync(realPath, { bigint: true });
+            assertNotHardlinked(options, realPathStat);
+            return realPathStat;
+        }, openedIdentity);
         if (maxBytes !== undefined && openedStat.size > maxBytes) {
             throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${maxBytes}).`);
         }
-        return { handle, pathStat: openedStat, realPath };
+        return { handle, identity: openedIdentity, pathStat: openedStat, realPath };
     }
     catch (err) {
         await handle.close().catch(() => undefined);
@@ -91,7 +104,7 @@ async function assertTrustedDirs(options, realPath) {
     const trusted = await Promise.all(options.trust.trustedDirs.map(async (dir) => {
         const resolved = path.resolve(dir);
         try {
-            return fsSync.realpathSync.native(resolved);
+            return realpathSync.native(resolved);
         }
         catch {
             return resolved;
@@ -116,13 +129,15 @@ function inspectOpenedPermissions(stat, platform) {
         groupReadable: isGroupReadable(bits),
     };
 }
-async function assertSecurePermissions(options, stat, realPath) {
+async function assertSecurePermissions(options, stat, realPath, identity, fd) {
     if (options.permissions?.allowInsecure) {
         return undefined;
     }
     const platform = options.inject?.platform ?? process.platform;
     const permissions = platform === "win32"
-        ? await inspectPathPermissions(realPath, options.inject)
+        ? process.platform === "win32"
+            ? inspectSecureWindowsDescriptor({ fd, identity, stat })
+            : await inspectPathPermissions(realPath, options.inject)
         : inspectOpenedPermissions(stat, platform);
     const reason = permissions.error ? `: ${formatPermissionErrorDetail(permissions.error)}` : "";
     const diagnostics = {
@@ -182,8 +197,13 @@ export async function readSecureFile(options) {
     const opened = await openSecureHandle(options, maxBytes);
     try {
         await assertTrustedDirs(options, opened.realPath);
-        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath);
+        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath, opened.identity, opened.handle.fd);
         const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
+        const finalIdentity = await inspectFileIdentity(() => fsSync.fstatSync(opened.handle.fd, { bigint: true }), opened.identity);
+        if (!finalIdentity.isFile()) {
+            throw new FsSafeError("not-file", `${label(options)} must remain a file: ${options.filePath}`);
+        }
+        assertNotHardlinked(options, finalIdentity);
         return { buffer, realPath: opened.realPath, stat: opened.pathStat, permissions };
     }
     finally {

package/dist/secure-temp-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAOA,KAAK,aAAa,GAAG;IACnB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA8JnF"}
+{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAQA,KAAK,aAAa,GAAG;IACnB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA+JnF"}

package/dist/secure-temp-dir.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { tmpdir as getOsTmpDir } from "node:os";
 import path from "node:path";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 function isNodeErrorWithCode(err, code) {
     return (typeof err === "object" &&
@@ -17,7 +18,7 @@ export function resolveSecureTempRoot(options) {
     const accessSync = options.accessSync ?? fs.accessSync;
     const chmodSync = options.chmodSync ?? fs.chmodSync;
     const lstatSync = options.lstatSync ?? fs.lstatSync;
-    const mkdirSync = options.mkdirSync ?? fs.mkdirSync;
+    const mkdirSync = options.mkdirSync ?? ((directory, mkdirOptions) => fs.mkdirSync(recursiveMkdirPath(directory), mkdirOptions));
     const warn = options.warn ?? ((message) => console.warn(message));
     const warningPrefix = options.warningPrefix ?? "[fs-safe]";
     const unsafeFallbackLabel = options.unsafeFallbackLabel ?? "secure temp dir";

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

@@ -1,6 +1,8 @@
+export declare function assertCallbackTempPathDeviceSafe(tempPath: string): void;
 export declare function writeCallbackSibling<T>(params: {
     tempPath: string;
     write: (tempPath: string) => Promise<T>;
+    producerIsolation?: "private-directory";
     resolveFinalPath: (result: T) => string;
     mode?: number;
     /** Preserve the caller's historical best-effort mode behavior. */

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

@@ -1 +1 @@
-{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAmCA,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,CAyG3C"}
+{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAuCA,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIvE;AAmCD,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,iBAAiB,CAAC,EAAE,mBAAmB,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,CAgH3C"}

package/dist/sibling-staged-file.js

@@ -2,12 +2,15 @@ import { syncFileBestEffort } from "./file-sync.js";
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { root } from "./root.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+import { createOwnedTempFile } from "./temp-target.js";
 import { serializePathWrite } from "./write-queue.js";
 function assertRegularFile(stat) {
     if (stat.isSymbolicLink()) {
@@ -27,17 +30,45 @@ async function inspectStage(inspect, expected) {
         return stat;
     }, expected);
 }
+export function assertCallbackTempPathDeviceSafe(tempPath) {
+    if (isWindowsReservedDeviceName(tempPath)) {
+        throw new FsSafeError("invalid-path", "callback temp path uses a reserved Windows device name");
+    }
+}
+// Own the workspace before the producer can leave partial output. The finished
+// file still enters the ordinary sibling admission and publication lifecycle.
+async function writeIsolatedProducer(params) {
+    const targetRoot = await root(path.dirname(params.tempPath));
+    const { target, identity } = await createOwnedTempFile({
+        rootDir: targetRoot.rootReal,
+        prefix: "fs-safe-output",
+        fileName: path.basename(params.tempPath),
+    });
+    const assertCurrent = () => {
+        params.assertParent();
+        assertDirectoryIdentitySync(target.dir, { ...identity, realPath: target.dir });
+    };
+    try {
+        assertCurrent();
+        const result = await params.write(target.path);
+        assertCurrent();
+        await targetRoot.move(path.relative(targetRoot.rootReal, target.path), path.basename(params.tempPath), {
+            assertBeforeMutation: assertCurrent,
+        });
+        return result;
+    }
+    finally {
+        await target.cleanup();
+    }
+}
 // 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) {
+    assertCallbackTempPathDeviceSafe(params.tempPath);
     const parent = path.dirname(params.tempPath);
-    const guard = await createAsyncDirectoryGuard(parent);
-    const parentIdentity = await inspectFileIdentity(() => fsSync.lstatSync(parent, { bigint: true }));
-    const assertParent = async () => {
-        await assertAsyncDirectoryGuard(guard);
-        await inspectFileIdentity(() => fsSync.lstatSync(parent, { bigint: true }), parentIdentity);
-    };
+    const guard = await createAsyncDirectoryGuard(parent, { bigint: true });
+    const assertParent = () => assertAsyncDirectoryGuard(guard);
     let handle;
     let identity;
     let unregister;
@@ -54,7 +85,17 @@ export async function writeCallbackSibling(params) {
         }
     };
     try {
-        const result = await params.write(params.tempPath);
+        const result = params.producerIsolation === "private-directory"
+            ? await writeIsolatedProducer({
+                tempPath: params.tempPath,
+                write: params.write,
+                assertParent: () => assertDirectoryIdentitySync(parent, {
+                    dev: guard.stat.dev,
+                    ino: guard.stat.ino,
+                    realPath: guard.realPath,
+                }),
+            })
+            : await params.write(params.tempPath);
         await assertParent();
         const before = await inspectPath(params.tempPath);
         try {

package/dist/sibling-temp.d.ts

@@ -1,6 +1,8 @@
 export type WriteSiblingTempFileOptions<T> = {
     dir: string;
     writeTemp: (tempPath: string) => Promise<T>;
+    /** Own a private sibling workspace before invoking the producer. */
+    producerIsolation?: "private-directory";
     resolveFinalPath: (result: T) => string;
     tempPrefix?: string;
     dirMode?: number;

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,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,CA6ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAeA,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,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,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,CAqBxC;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,CA8ChB"}

package/dist/sibling-temp.js

@@ -1,14 +1,15 @@
 import crypto, { randomUUID } from "node:crypto";
-import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
 import { applyDirectoryMode } from "./replace-file-descriptor.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
-import { writeCallbackSibling } from "./sibling-staged-file.js";
+import { assertCallbackTempPathDeviceSafe, writeCallbackSibling } from "./sibling-staged-file.js";
 import { tempFile } from "./temp-target.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function buildTempPath(dir, tempPrefix) {
@@ -19,7 +20,7 @@ function buildTempPath(dir, tempPrefix) {
 }
 export async function writeSiblingTempFile(options) {
     const dir = path.resolve(options.dir);
-    await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true, mode: options.dirMode ?? 0o700 });
     if (options.chmodDir !== false) {
         await applyDirectoryMode({
             fsModule: fs,
@@ -31,6 +32,7 @@ export async function writeSiblingTempFile(options) {
     return await writeCallbackSibling({
         tempPath: buildTempPath(dir, options.tempPrefix),
         write: options.writeTemp,
+        producerIsolation: options.producerIsolation,
         resolveFinalPath: options.resolveFinalPath,
         mode: options.mode,
         ignoreModeError: true,
@@ -55,7 +57,7 @@ function buildSiblingTempPath(params) {
 export async function writeViaSiblingTempPath(params) {
     let rootDir;
     try {
-        rootDir = fsSync.realpathSync.native(path.resolve(params.rootDir));
+        rootDir = realpathSync.native(path.resolve(params.rootDir));
     }
     catch {
         rootDir = path.resolve(params.rootDir);
@@ -63,7 +65,7 @@ export async function writeViaSiblingTempPath(params) {
     const requestedTargetPath = path.resolve(params.targetPath);
     let targetPath;
     try {
-        const realDir = fsSync.realpathSync.native(path.dirname(requestedTargetPath));
+        const realDir = realpathSync.native(path.dirname(requestedTargetPath));
         targetPath = path.join(realDir, path.basename(requestedTargetPath));
     }
     catch {
@@ -91,6 +93,7 @@ export async function writeViaSiblingTempPath(params) {
             fallbackFileName: params.fallbackFileName ?? "output.bin",
             tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
         });
+        assertCallbackTempPathDeviceSafe(tempPath);
         await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
         await params.writeTemp(tempPath);
         await assertAsyncDirectoryGuard(rootGuard);

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":"AAQA,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;AAI5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEvF,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,OAAO,CAAC;IACvB,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,CAqT5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAUA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAW3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEvF,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,OAAO,CAAC;IACvB,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,CA6T5B"}

package/dist/sidecar-lock-acquire.js

@@ -5,9 +5,11 @@ import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
 import { fileObservation } from "./file-observation.js";
 import { readFileHandleBounded } from "./bounded-read.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.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 { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockRetryOptions, validateSidecarLockCompromiseCheckIntervalMs, 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";
 import { sleep } from "./timing.js";
@@ -22,9 +24,9 @@ async function resolveNormalizedTargetPath(targetPath, lockRoot) {
         await lockRoot.resolve(".");
         return path.join(parent, path.basename(resolved));
     }
-    await fs.mkdir(dir, { recursive: true });
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
     try {
-        return path.join(fsSync.realpathSync.native(dir), path.basename(resolved));
+        return path.join(realpathSync.native(dir), path.basename(resolved));
     }
     catch {
         return resolved;
@@ -34,6 +36,8 @@ export async function acquireSidecarLock(options, context) {
     const retry = options.retry ?? {};
     validateSidecarLockRetryOptions(retry);
     validateSidecarLockTimeoutMs(options.timeoutMs);
+    validateSidecarLockStaleMs(options.staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(options.compromiseCheckIntervalMs);
     context.ensureExitCleanupRegistered();
     const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
@@ -54,7 +58,7 @@ export async function acquireSidecarLock(options, context) {
             options.reentrantOwner !== undefined &&
             held.reentrantOwner !== undefined &&
             options.reentrantOwner === held.reentrantOwner) {
-            held.refCount += 1;
+            held.refCount = (held.refCount ?? 1) + 1;
             // Retention is monotonic: any same-owner request to keep the sidecar on
             // exit upgrades the held lock; a later default acquisition never revokes it.
             if (options.retainOnExit === true) {
@@ -153,7 +157,7 @@ export async function acquireSidecarLock(options, context) {
                     try {
                         handle =
                             (await createNativeExclusiveFile(lockPath, 0o600)) ??
-                                (await fs.open(lockPath, "wx"));
+                                (await fs.open(lockPath, "wx", 0o600));
                     }
                     catch (createError) {
                         lockFileCreateDenied = isTransientLockFileDenial(createError, lockPath);
@@ -194,7 +198,11 @@ export async function acquireSidecarLock(options, context) {
                 const returnedHandle = context.handleForHeldLock(normalizedTargetPath, createdHeld);
                 const interval = options.compromiseCheckIntervalMs;
                 if (options.onCompromised && interval !== undefined && interval > 0) {
+                    let compromiseCheckInFlight = false;
                     createdHeld.compromiseTimer = setInterval(() => {
+                        if (compromiseCheckInFlight)
+                            return;
+                        compromiseCheckInFlight = true;
                         void returnedHandle
                             .verifyStillHeld()
                             .catch(() => false)
@@ -204,6 +212,9 @@ export async function acquireSidecarLock(options, context) {
                                 createdHeld.compromiseTimer = undefined;
                                 options.onCompromised?.({ lockPath, normalizedTargetPath });
                             }
+                        })
+                            .finally(() => {
+                            compromiseCheckInFlight = false;
                         });
                     }, interval);
                     createdHeld.compromiseTimer.unref();

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

@@ -1,6 +1,8 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
 export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
+export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
+export declare function validateSidecarLockCompromiseCheckIntervalMs(intervalMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}
+{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAUvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAO5E;AAED,wBAAgB,4CAA4C,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAOjG;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}

package/dist/sidecar-lock-policy.js

@@ -1,4 +1,5 @@
 import fsSync from "node:fs";
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 function assertFiniteNonNegative(value, label) {
     if (!Number.isFinite(value) || value < 0) {
         throw new RangeError(`${label} must be a finite non-negative number`);
@@ -27,6 +28,22 @@ export function validateSidecarLockTimeoutMs(timeoutMs) {
         return;
     assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
 }
+export function validateSidecarLockStaleMs(staleMs) {
+    // The lower-level sidecar manager historically treats an omitted threshold
+    // as disabling age-based reclamation. Its public type requires a number, but
+    // retain that fail-closed runtime behavior for JavaScript callers and older
+    // consumers.
+    if (staleMs === undefined || staleMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(staleMs, "lock staleMs");
+}
+export function validateSidecarLockCompromiseCheckIntervalMs(intervalMs) {
+    if (intervalMs === undefined || intervalMs === 0)
+        return;
+    if (!Number.isFinite(intervalMs) || intervalMs < 1 || intervalMs > MAX_TIMER_DELAY_MS) {
+        throw new RangeError(`lock compromiseCheckIntervalMs must be 0 or a finite number between 1 and ${MAX_TIMER_DELAY_MS}`);
+    }
+}
 export function computeSidecarLockDelayMs(retry, attempt) {
     validateSidecarLockRetryOptions(retry);
     const minTimeout = retry.minTimeout ?? 50;

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,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;AAsIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAuFD,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;eAkBL,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":"AAWA,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;AAmIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAyFD,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;eAkBL,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"}