@openclaw/fs-safe 0.5.1 → 0.5.3

package/dist/deny-mutations.js

@@ -1,41 +1,8 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
-async function pathExists(filePath) {
-    try {
-        await fs.lstat(filePath);
-        return true;
-    }
-    catch (err) {
-        if (!isNotFoundPathError(err)) {
-            throw err;
-        }
-        return false;
-    }
-}
-async function resolvePathViaExistingAncestor(targetPath) {
-    const normalized = path.resolve(targetPath);
-    let cursor = normalized;
-    const missingSuffix = [];
-    while (path.dirname(cursor) !== cursor && !(await pathExists(cursor))) {
-        missingSuffix.unshift(path.basename(cursor));
-        cursor = path.dirname(cursor);
-    }
-    if (!(await pathExists(cursor))) {
-        return normalized;
-    }
-    try {
-        const resolvedAncestor = path.resolve(await fs.realpath(cursor));
-        return missingSuffix.length === 0
-            ? resolvedAncestor
-            : path.resolve(resolvedAncestor, ...missingSuffix);
-    }
-    catch {
-        return normalized;
-    }
-}
-async function comparablePaths(rawPath) {
+import { assertNoNulPathInput, isPathInside } from "./path.js";
+import { resolvePathViaExistingAncestor } from "./root-path-existing.js";
+export async function resolveMutationComparablePaths(rawPath) {
     assertNoNulPathInput(rawPath, "path contains a NUL byte");
     const resolved = path.resolve(rawPath);
     return new Set([resolved, await resolvePathViaExistingAncestor(resolved)]);
@@ -64,9 +31,9 @@ export async function assertMutationNotDenied(filePath, policy, options = {}) {
     if (!hasPolicyEntries(policy)) {
         return;
     }
-    const targetPaths = await comparablePaths(filePath);
+    const targetPaths = await resolveMutationComparablePaths(filePath);
     for (const deniedPath of policyPathEntries(policy.paths)) {
-        const deniedPaths = await comparablePaths(deniedPath);
+        const deniedPaths = await resolveMutationComparablePaths(deniedPath);
         for (const target of targetPaths) {
             for (const denied of deniedPaths) {
                 if (isSamePath(denied, target) ||
@@ -77,7 +44,7 @@ export async function assertMutationNotDenied(filePath, policy, options = {}) {
         }
     }
     for (const deniedPrefix of policyPathEntries(policy.prefixes)) {
-        const deniedPaths = await comparablePaths(deniedPrefix);
+        const deniedPaths = await resolveMutationComparablePaths(deniedPrefix);
         for (const target of targetPaths) {
             for (const denied of deniedPaths) {
                 if (isPathInside(denied, target) ||

package/dist/device-path.d.ts

@@ -7,6 +7,7 @@ export type UnsafeDeviceReadPathOptions = {
     cwd?: string;
     platform?: NodeJS.Platform;
 };
+export declare const WINDOWS_RESERVED_DEVICE_NAMES: ReadonlySet<string>;
 export declare function matchUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): UnsafeDeviceReadPathMatch | undefined;
 export declare function isUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): boolean;
 export declare function assertNoUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): void;

package/dist/device-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-path.d.ts","sourceRoot":"","sources":["../src/device-path.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,UAAU,GACV,gBAAgB,CAAC;AAErB,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,0BAA0B,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAgIF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,2BAAgC,GACxC,yBAAyB,GAAG,SAAS,CAWvC;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAET;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CAON"}
+{"version":3,"file":"device-path.d.ts","sourceRoot":"","sources":["../src/device-path.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,UAAU,GACV,gBAAgB,CAAC;AAErB,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,0BAA0B,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAcF,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,CAgC5D,CAAC;AAkFH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,2BAAgC,GACxC,yBAAyB,GAAG,SAAS,CAWvC;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAET;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CAON"}

package/dist/device-path.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { trySafeFileURLToPath } from "./local-file-access.js";
+import { isFileUrl, trySafeFileURLToPath } from "./local-file-access.js";
 const POSIX_BLOCKED_DEVICE_PATHS = new Set([
     "/dev/zero",
     "/dev/random",
@@ -12,7 +12,7 @@ const POSIX_BLOCKED_DEVICE_PATHS = new Set([
     "/dev/tty",
     "/dev/console",
 ]);
-const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
+export const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
     "CON",
     "PRN",
     "AUX",
@@ -67,11 +67,11 @@ function trimTrailingWindowsIgnoredChars(value) {
     }
     return end === value.length ? value : value.slice(0, end);
 }
-function candidateReadPaths(filePath) {
-    if (!filePath.startsWith("file://")) {
+function candidateReadPaths(filePath, platform) {
+    if (!isFileUrl(filePath)) {
         return [filePath];
     }
-    const parsed = trySafeFileURLToPath(filePath);
+    const parsed = trySafeFileURLToPath(filePath, platform);
     return parsed === undefined ? [filePath] : [filePath, parsed];
 }
 function normalizePosixPath(filePath, cwd) {
@@ -114,7 +114,7 @@ function matchWindowsDeviceReadPath(filePath) {
 }
 export function matchUnsafeDeviceReadPath(filePath, options = {}) {
     const platform = options.platform ?? process.platform;
-    for (const candidate of candidateReadPaths(filePath)) {
+    for (const candidate of candidateReadPaths(filePath, platform)) {
         const match = platform === "win32"
             ? matchWindowsDeviceReadPath(candidate)
             : matchPosixDeviceReadPath(candidate, options.cwd);

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

@@ -1 +1 @@
-{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAQrC,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAMzF;AAED,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzF;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAMxE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAQxE;AAED,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAcpB"}
+{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AASrC,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAMzF;AAED,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzF;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAMxE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAQxE;AAED,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAcpB"}

package/dist/directory-guard.js

@@ -4,17 +4,18 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { isNotFoundPathError } from "./path.js";
+import { directoryComponentNotDirectoryError } from "./root-errors.js";
 export async function createAsyncDirectoryGuard(dir) {
     const stat = await fs.lstat(dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new FsSafeError("not-file", "directory component must be a directory");
+        throw directoryComponentNotDirectoryError();
     }
     return { dir, realPath: await fs.realpath(dir), stat };
 }
 export async function assertAsyncDirectoryGuard(guard) {
     const stat = await fs.lstat(guard.dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new FsSafeError("not-file", "directory component must be a directory");
+        throw directoryComponentNotDirectoryError();
     }
     if (!sameFileIdentity(stat, guard.stat) || (await fs.realpath(guard.dir)) !== guard.realPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
@@ -23,14 +24,14 @@ export async function assertAsyncDirectoryGuard(guard) {
 export function createSyncDirectoryGuard(dir) {
     const stat = fsSync.lstatSync(dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new FsSafeError("not-file", "directory component must be a directory");
+        throw directoryComponentNotDirectoryError();
     }
     return { dir, realPath: fsSync.realpathSync(dir), stat };
 }
 export function assertSyncDirectoryGuard(guard) {
     const stat = fsSync.lstatSync(guard.dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new FsSafeError("not-file", "directory component must be a directory");
+        throw directoryComponentNotDirectoryError();
     }
     if (!sameFileIdentity(stat, guard.stat) || fsSync.realpathSync(guard.dir) !== guard.realPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");

package/dist/error-detail.d.ts

@@ -0,0 +1,2 @@
+export declare function formatErrorDetail(value: string): string;
+//# sourceMappingURL=error-detail.d.ts.map

package/dist/error-detail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-detail.d.ts","sourceRoot":"","sources":["../src/error-detail.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD"}

package/dist/error-detail.js

@@ -0,0 +1,4 @@
+const UNSAFE_ERROR_DETAIL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu;
+export function formatErrorDetail(value) {
+    return value.replace(UNSAFE_ERROR_DETAIL_CHARACTERS, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type FsSafeErrorCode = "already-exists" | "denied-path" | "device-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "secret-exists" | "store-reentrant-update" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+export type FsSafeErrorCode = "already-exists" | "denied-path" | "device-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "read-failed" | "secret-exists" | "store-reentrant-update" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
 export type FsSafeErrorCategory = "policy" | "operational";
 export type FsSafeErrorDetails = Readonly<Record<string, unknown>>;
 export declare function categorizeFsSafeError(code: FsSafeErrorCode): FsSafeErrorCategory;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,UAAU,GACV,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,WAAW,GACX,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,uBAAuB,GACvB,eAAe,GACf,wBAAwB,GACxB,SAAS,GACT,SAAS,GACT,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAC3D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAUnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAEhF;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAEtC,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAAO,EAOhE;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,UAAU,GACV,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,WAAW,GACX,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,uBAAuB,GACvB,aAAa,GACb,eAAe,GACf,wBAAwB,GACxB,SAAS,GACT,SAAS,GACT,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAC3D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAcnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAEhF;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAEtC,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAAO,EAOhE;CACF"}

package/dist/errors.js

@@ -1,7 +1,11 @@
 const OPERATIONAL_CODES = new Set([
     "helper-failed",
     "helper-unavailable",
+    "not-empty",
+    "not-found",
+    "not-removable",
     "permission-unverified",
+    "read-failed",
     "timeout",
     "unsupported-platform",
 ]);

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

@@ -1 +1 @@
-{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAcF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,GACrD,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAsCD,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAElF"}
+{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAcF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,GACrD,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AA2CD,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAElF"}

package/dist/file-hash.js

@@ -59,7 +59,10 @@ async function hashPath(filePath) {
         if (!opened.isFile()) {
             throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
         }
-        if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(opened, current)) {
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            !sameFileIdentity(before, opened) ||
+            !sameFileIdentity(opened, current)) {
             throw new FsSafeError("path-mismatch", "SHA-256 path changed while opening");
         }
         return await hashFileHandle(handle);

package/dist/file-lock-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-lock-sync.d.ts","sourceRoot":"","sources":["../src/file-lock-sync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAOL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,KAAK,CAAC;KAC1B,KAAK,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAiGF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CA6IpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAC7C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAOH"}
+{"version":3,"file":"file-lock-sync.d.ts","sourceRoot":"","sources":["../src/file-lock-sync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAOL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAGjC,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,KAAK,CAAC;KAC1B,KAAK,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AA0IF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CAuJpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAC7C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAOH"}

package/dist/file-lock-sync.js

@@ -2,8 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { readSidecarLockSnapshotSync, relativeSidecarLockPath, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
-import { computeSidecarLockDelayMs, sidecarLockPayloadIsStale, } from "./sidecar-lock-policy.js";
+import { computeSidecarLockDelayMs, sidecarLockPayloadCreatedAtMs, } from "./sidecar-lock-policy.js";
+import { sleepSync } from "./timing.js";
 const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
+const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
+const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
 function getSyncHeldLocks() {
     const globalWithState = globalThis;
     if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
@@ -11,6 +14,36 @@ function getSyncHeldLocks() {
     }
     return globalWithState[SYNC_HELD_LOCKS_KEY];
 }
+function releaseAllSyncHeldLocks() {
+    const heldLocks = getSyncHeldLocks();
+    for (const [normalizedTargetPath, held] of heldLocks) {
+        if (held.timer) {
+            clearInterval(held.timer);
+            held.timer = undefined;
+        }
+        try {
+            fs.closeSync(held.fd);
+        }
+        catch {
+            // Best-effort process-exit cleanup.
+        }
+        try {
+            removeSidecarLockIfUnchangedSync(held.lockPath, held.snapshot);
+        }
+        catch {
+            // A surviving sidecar fails closed and can be reclaimed by policy.
+        }
+        heldLocks.delete(normalizedTargetPath);
+    }
+}
+function ensureSyncExitCleanupRegistered() {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY])
+        return;
+    globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
+    globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = releaseAllSyncHeldLocks;
+    process.on("exit", releaseAllSyncHeldLocks);
+}
 function verifySyncHeldLock(held) {
     const current = readSidecarLockSnapshotSync(held.lockPath, held.parsePayload);
     return !!current && sidecarLockSnapshotMatches(current, held.snapshot);
@@ -71,8 +104,9 @@ function boundedLockPath(lockPath, lockRoot) {
     return path.join(parentReal, path.basename(resolved));
 }
 function defaultShouldReclaim(payload, lockPath, staleMs, nowMs) {
-    if (sidecarLockPayloadIsStale(payload, staleMs, nowMs))
-        return true;
+    const createdAtMs = sidecarLockPayloadCreatedAtMs(payload);
+    if (createdAtMs !== null)
+        return nowMs - createdAtMs > staleMs;
     try {
         return nowMs - fs.statSync(lockPath).mtimeMs > staleMs;
     }
@@ -80,8 +114,16 @@ function defaultShouldReclaim(payload, lockPath, staleMs, nowMs) {
         return true;
     }
 }
-function sleep(milliseconds) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+function reclaimGuardExists(reclaimGuardPath) {
+    try {
+        fs.lstatSync(reclaimGuardPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
 }
 export function acquireFileLockSync(targetPath, options) {
     const normalizedTargetPath = normalizeTargetPath(targetPath);
@@ -99,7 +141,25 @@ export function acquireFileLockSync(targetPath, options) {
     const retry = options.retry ?? {};
     const startedAt = Date.now();
     let attempt = 0;
+    const reclaimGuardPath = `${lockPath}.reclaim`;
+    const waitForRetry = () => {
+        const elapsed = Date.now() - startedAt;
+        const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
+        if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
+            throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                code: "file_lock_timeout",
+                lockPath,
+                normalizedTargetPath,
+            });
+        }
+        sleepSync(computeSidecarLockDelayMs(retry, attempt));
+        attempt += 1;
+    };
     while (true) {
+        if (reclaimGuardExists(reclaimGuardPath)) {
+            waitForRetry();
+            continue;
+        }
         let fd;
         try {
             const payload = options.payload();
@@ -126,6 +186,7 @@ export function acquireFileLockSync(targetPath, options) {
                 snapshot,
             };
             heldLocks.set(normalizedTargetPath, createdHeld);
+            ensureSyncExitCleanupRegistered();
             const returnedHandle = createSyncHeldLockHandle(createdHeld);
             if (options.onCompromised && (options.compromiseCheckIntervalMs ?? 0) > 0) {
                 createdHeld.timer = setInterval(() => {
@@ -151,20 +212,12 @@ export function acquireFileLockSync(targetPath, options) {
             if (error.code !== "EEXIST")
                 throw error;
             if (heldLocks.has(normalizedTargetPath)) {
-                const elapsed = Date.now() - startedAt;
-                const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
-                if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
-                    throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                        code: "file_lock_timeout",
-                        lockPath,
-                        normalizedTargetPath,
-                    });
-                }
-                sleep(computeSidecarLockDelayMs(retry, attempt));
-                attempt += 1;
+                waitForRetry();
                 continue;
             }
-            const snapshot = readSidecarLockSnapshotSync(lockPath, options.parsePayload);
+            const snapshot = readSidecarLockSnapshotSync(lockPath, options.parsePayload, {
+                rejectNonFile: true,
+            });
             if (!snapshot)
                 continue;
             const nowMs = Date.now();
@@ -187,18 +240,28 @@ export function acquireFileLockSync(targetPath, options) {
                         raw: snapshot.raw,
                         payload: snapshot.payload,
                     })) {
-                    const reclaimGuard = `${lockPath}.reclaim`;
+                    let ownsReclaimGuard = false;
                     try {
-                        fs.mkdirSync(reclaimGuard);
+                        fs.mkdirSync(reclaimGuardPath);
+                        ownsReclaimGuard = true;
                         if (removeSidecarLockIfUnchangedSync(lockPath, snapshot))
                             continue;
                     }
-                    finally {
-                        try {
-                            fs.rmdirSync(reclaimGuard);
+                    catch (reclaimError) {
+                        if (reclaimError.code !== "EEXIST") {
+                            throw reclaimError;
                         }
-                        catch {
-                            // A surviving reclaim guard fails closed.
+                        waitForRetry();
+                        continue;
+                    }
+                    finally {
+                        if (ownsReclaimGuard) {
+                            try {
+                                fs.rmdirSync(reclaimGuardPath);
+                            }
+                            catch {
+                                // A surviving reclaim guard fails closed.
+                            }
                         }
                     }
                 }
@@ -208,17 +271,7 @@ export function acquireFileLockSync(targetPath, options) {
                     normalizedTargetPath,
                 });
             }
-            const elapsed = Date.now() - startedAt;
-            const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
-            if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
-                throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                    code: "file_lock_timeout",
-                    lockPath,
-                    normalizedTargetPath,
-                });
-            }
-            sleep(computeSidecarLockDelayMs(retry, attempt));
-            attempt += 1;
+            waitForRetry();
         }
     }
 }

package/dist/file-store-boundary.d.ts

@@ -22,4 +22,10 @@ export declare function ensureParentSync(params: {
     filePath: string;
     mode: number;
 }): SyncParentGuard;
+export declare function ensureStoreDirectorySync(params: {
+    rootDir: string;
+    targetDir: string;
+    mode: number;
+    messagePrefix: "private store" | "store";
+}): SyncParentGuard;
 //# sourceMappingURL=file-store-boundary.d.ts.map

package/dist/file-store-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store-boundary.d.ts","sourceRoot":"","sources":["../src/file-store-boundary.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAA4C,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGhF,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAOjD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,IAAI,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+CD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAuC1D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAWrE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAwClB"}
+{"version":3,"file":"file-store-boundary.d.ts","sourceRoot":"","sources":["../src/file-store-boundary.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAA4C,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGhF,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAOjD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,IAAI,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+CD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAuC1D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAWrE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAOlB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC;CAC1C,GAAG,eAAe,CAyDlB"}

package/dist/file-store-boundary.js

@@ -5,6 +5,7 @@ import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { assertSyncDirectoryGuard as assertDirectoryGuardSync, createSyncDirectoryGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { isPathInside, isPathRelativeEscape } from "./path.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
@@ -128,8 +129,16 @@ function chmodDirectorySyncBestEffort(dir, mode) {
     }
 }
 export function ensureParentSync(params) {
+    return ensureStoreDirectorySync({
+        rootDir: params.rootDir,
+        targetDir: path.dirname(path.resolve(params.filePath)),
+        mode: params.mode,
+        messagePrefix: "store",
+    });
+}
+export function ensureStoreDirectorySync(params) {
     const rootDir = path.resolve(params.rootDir);
-    const dir = path.dirname(path.resolve(params.filePath));
+    const dir = path.resolve(params.targetDir);
     const relative = path.relative(rootDir, dir);
     if (isPathRelativeEscape(relative)) {
         throw new FsSafeError("outside-workspace", "file path escapes store root");
@@ -137,7 +146,7 @@ export function ensureParentSync(params) {
     syncFs.mkdirSync(rootDir, { recursive: true, mode: params.mode });
     const rootStat = syncFs.lstatSync(rootDir);
     if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-        throw new FsSafeError("not-file", `store root must be a directory: ${rootDir}`);
+        throw new FsSafeError("not-file", `${params.messagePrefix} root must be a directory: ${rootDir}`);
     }
     const rootReal = syncFs.realpathSync(rootDir);
     chmodDirectorySyncBestEffort(rootDir, params.mode);
@@ -147,7 +156,7 @@ export function ensureParentSync(params) {
         try {
             const stat = syncFs.lstatSync(current);
             if (stat.isSymbolicLink() || !stat.isDirectory()) {
-                throw new FsSafeError("not-file", `store directory component must be a directory: ${current}`);
+                throw new FsSafeError("not-file", `${params.messagePrefix} directory component must be a directory: ${current}`);
             }
         }
         catch (error) {
@@ -156,9 +165,15 @@ export function ensureParentSync(params) {
             }
             syncFs.mkdirSync(current, { mode: params.mode });
         }
+        const currentRootStat = syncFs.lstatSync(rootDir);
+        const currentRootReal = syncFs.realpathSync(rootDir);
         const currentReal = syncFs.realpathSync(current);
-        if (!isPathInside(rootReal, currentReal)) {
-            throw new FsSafeError("outside-workspace", "store directory escapes root");
+        if (currentRootStat.isSymbolicLink() ||
+            !currentRootStat.isDirectory() ||
+            !sameFileIdentity(rootStat, currentRootStat) ||
+            currentRootReal !== rootReal ||
+            !isPathInside(rootReal, currentReal)) {
+            throw new FsSafeError("outside-workspace", `${params.messagePrefix} directory escapes root`);
         }
         chmodDirectorySyncBestEffort(current, params.mode);
     }

package/dist/file-store-sync-write.d.ts

@@ -0,0 +1,9 @@
+export declare function writeFileSyncAtomic(params: {
+    rootDir: string;
+    filePath: string;
+    content: string | Uint8Array;
+    privateMode: boolean;
+    dirMode: number;
+    mode: number;
+}): string;
+//# sourceMappingURL=file-store-sync-write.d.ts.map

package/dist/file-store-sync-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store-sync-write.d.ts","sourceRoot":"","sources":["../src/file-store-sync-write.ts"],"names":[],"mappings":"AAuBA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CA+ET"}

package/dist/file-store-sync-write.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { assertSyncDirectoryGuard, ensureParentSync, ensureStoreDirectorySync, } from "./file-store-boundary.js";
+import { isPathInside } from "./path.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
+    return ensureStoreDirectorySync({
+        rootDir,
+        targetDir,
+        mode,
+        messagePrefix: "private store",
+    });
+}
+export function writeFileSyncAtomic(params) {
+    const filePath = path.resolve(params.filePath);
+    if (!isPathInside(params.rootDir, filePath)) {
+        throw new FsSafeError("outside-workspace", "file path escapes store root");
+    }
+    let parentGuard;
+    if (params.privateMode) {
+        parentGuard = ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
+        try {
+            const stat = fs.lstatSync(filePath);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new FsSafeError("not-file", `private store target must be a regular file: ${filePath}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+    else {
+        parentGuard = ensureParentSync({
+            rootDir: params.rootDir,
+            filePath,
+            mode: params.dirMode,
+        });
+    }
+    const tempPath = path.join(parentGuard?.dir ?? path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
+    let tempExists = false;
+    try {
+        getFsSafeTestHooks()?.beforeFileStoreSyncPrivateWrite?.(filePath);
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
+        fs.writeFileSync(tempPath, params.content, { flag: "wx", mode: params.mode });
+        tempExists = true;
+        try {
+            fs.chmodSync(tempPath, params.mode);
+        }
+        catch {
+            // Best-effort on platforms that do not enforce POSIX modes.
+        }
+        const tempStat = fs.lstatSync(tempPath);
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
+        fs.renameSync(tempPath, filePath);
+        tempExists = false;
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
+        try {
+            const publishedStat = fs.lstatSync(filePath);
+            if (publishedStat.isSymbolicLink() ||
+                !publishedStat.isFile() ||
+                publishedStat.nlink > 1 ||
+                !sameFileIdentity(tempStat, publishedStat)) {
+                throw new FsSafeError("path-mismatch", "store target changed after write");
+            }
+        }
+        catch (error) {
+            if (error instanceof FsSafeError) {
+                throw error;
+            }
+            throw new FsSafeError("path-mismatch", "store target changed after write", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        return filePath;
+    }
+    finally {
+        if (tempExists) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch {
+                // Best-effort cleanup after write failure.
+            }
+        }
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAA4B,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAOnE,OAAO,EAAmB,KAAK,oBAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAItG,OAAO,EAAQ,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAOpG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,CACH,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,WAAW,CACT,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3E,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5E,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/F,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxF,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1B,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACrB,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,CACP,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,SAAS,CACP,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,qBAAqB,GAAG;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9D,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACtF,YAAY,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI,CAAC;IACvF,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC/F,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IAChG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IACpG,SAAS,CACP,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,qBAAqB,GAAG;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9D,MAAM,CAAC;CACX,CAAC;AA+HF,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAoM9D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAqEtE"}