@openclaw/fs-safe 0.1.1 → 0.2.0

package/dist/file-store.d.ts

@@ -1,4 +1,6 @@
 import type { Readable } from "node:stream";
+import { type FileStorePruneOptions } from "./file-store-prune.js";
+export type { FileStorePruneOptions } from "./file-store-prune.js";
 import { type JsonFileStoreOptions, type JsonStore } from "./json-document-store.js";
 import { type OpenResult, type ReadResult, type Root, type RootReadOptions } from "./root.js";
 export type FileStoreOptions = {
@@ -17,12 +19,6 @@ export type FileStoreWriteOptions = {
 export type FileStoreReadOptions = RootReadOptions & {
     encoding?: BufferEncoding;
 };
-export type FileStorePruneOptions = {
-    ttlMs: number;
-    recursive?: boolean;
-    maxDepth?: number;
-    pruneEmptyDirs?: boolean;
-};
 export type FileStore = {
     readonly rootDir: string;
     path(relativePath: string): string;

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

package/dist/file-store.js

@@ -2,13 +2,18 @@ import { randomUUID } from "node:crypto";
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { pipeline } from "node:stream/promises";
+import { createSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { pruneExpiredStoreEntries, } from "./file-store-prune.js";
+import { assertSyncDirectoryGuard, ensureParentInRoot, ensureParentSync, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { readFileStoreCopySource } from "./file-store-source.js";
 import { createJsonStore } from "./json-document-store.js";
 import { isPathInside, resolveSafeRelativePath } from "./path.js";
 import { root } from "./root.js";
+import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
+import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
-import { writeSiblingTempFile } from "./sibling-temp.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 function assertRelativePath(relativePath) {
     const raw = relativePath.trim();
     if (!raw) {
@@ -24,43 +29,65 @@ function assertStoreFilePath(rootDir, filePath) {
         throw new FsSafeError("outside-workspace", "file path escapes store root");
     }
 }
-async function ensureParent(filePath, mode) {
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true, mode });
-    await fs.chmod(dir, mode).catch(() => undefined);
-}
 function assertMaxBytes(size, maxBytes) {
     if (maxBytes !== undefined && size > maxBytes) {
         throw new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`);
     }
 }
 function isNotFound(error) {
+    if (!error) {
+        return false;
+    }
     return error instanceof FsSafeError
         ? error.code === "not-found"
         : error.code === "ENOENT" ||
             error.code === "ENOTDIR";
 }
+function handleSyncStoreReadOpenFailure(opened) {
+    return matchRootFileOpenFailure(opened, {
+        path: (failure) => {
+            if (isNotFound(failure.error)) {
+                return null;
+            }
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        validation: (failure) => {
+            // Validation failures mean the path existed but violated store policy
+            // (directory, hardlink, symlink race). Do not report them as missing.
+            throw new FsSafeError("path-mismatch", "store target failed read validation", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        fallback: (failure) => {
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+    });
+}
 async function copyIntoRoot(params) {
-    const destination = resolveStorePath(params.rootDir, params.relativePath);
+    const relativePath = assertRelativePath(params.relativePath);
+    const destination = resolveStorePath(params.rootDir, relativePath);
     const sourceStat = await fs.lstat(params.sourcePath);
     if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
         throw new FsSafeError("not-file", "source path is not a file");
     }
     assertMaxBytes(sourceStat.size, params.maxBytes);
-    await ensureParent(destination, params.dirMode ?? 0o700);
-    const result = await writeSiblingTempFile({
-        dir: path.dirname(destination),
-        dirMode: params.dirMode ?? 0o700,
+    const dirMode = params.dirMode ?? 0o700;
+    const scopedRoot = await openWritableStoreRoot({
+        rootDir: params.rootDir,
+        dirMode,
+        maxBytes: params.maxBytes,
+    });
+    await ensureParentInRoot(scopedRoot, relativePath, dirMode);
+    await scopedRoot.copyIn(relativePath, params.sourcePath, {
+        maxBytes: params.maxBytes,
+        mkdir: false,
         mode: params.mode ?? 0o600,
-        tempPrefix: params.tempPrefix ?? `.${path.basename(destination)}`,
-        writeTemp: async (tempPath) => {
-            await fs.copyFile(params.sourcePath, tempPath);
-        },
-        resolveFinalPath: () => destination,
-        syncTempFile: true,
-        syncParentDir: true,
     });
-    return result.filePath;
+    return destination;
 }
 export function fileStore(options) {
     const rootDir = path.resolve(options.rootDir);
@@ -72,7 +99,8 @@ export function fileStore(options) {
         return await root(rootDir, { hardlinks: "reject", maxBytes });
     }
     async function write(relativePath, data, writeOptions) {
-        const destination = resolveStorePath(rootDir, relativePath);
+        const safeRelativePath = assertRelativePath(relativePath);
+        const destination = resolveStorePath(rootDir, safeRelativePath);
         const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
         assertMaxBytes(content.byteLength, writeOptions?.maxBytes ?? maxBytes);
         if (privateMode) {
@@ -85,20 +113,18 @@ export function fileStore(options) {
             });
             return destination;
         }
-        await ensureParent(destination, writeOptions?.dirMode ?? dirMode);
-        const result = await writeSiblingTempFile({
-            dir: path.dirname(destination),
-            dirMode: writeOptions?.dirMode ?? dirMode,
+        const writeDirMode = writeOptions?.dirMode ?? dirMode;
+        const scopedRoot = await openWritableStoreRoot({
+            rootDir,
+            dirMode: writeDirMode,
+            maxBytes: writeOptions?.maxBytes ?? maxBytes,
+        });
+        await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
+        await scopedRoot.write(safeRelativePath, content, {
+            mkdir: false,
             mode: writeOptions?.mode ?? mode,
-            tempPrefix: writeOptions?.tempPrefix ?? `.${path.basename(destination)}`,
-            writeTemp: async (tempPath) => {
-                await fs.writeFile(tempPath, content);
-            },
-            resolveFinalPath: () => destination,
-            syncTempFile: true,
-            syncParentDir: true,
         });
-        return result.filePath;
+        return destination;
     }
     return {
         rootDir,
@@ -106,8 +132,9 @@ export function fileStore(options) {
         root: openRoot,
         write,
         writeStream: async (relativePath, stream, writeOptions) => {
-            const destination = resolveStorePath(rootDir, relativePath);
-            const limit = writeOptions?.maxBytes ?? maxBytes;
+            const safeRelativePath = assertRelativePath(relativePath);
+            const destination = resolveStorePath(rootDir, safeRelativePath);
+            const limit = writeOptions?.maxBytes ?? maxBytes ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
             if (privateMode) {
                 const chunks = [];
                 let total = 0;
@@ -126,43 +153,34 @@ export function fileStore(options) {
                 });
                 return destination;
             }
-            await ensureParent(destination, writeOptions?.dirMode ?? dirMode);
-            let total = 0;
-            const result = await writeSiblingTempFile({
-                dir: path.dirname(destination),
-                dirMode: writeOptions?.dirMode ?? dirMode,
+            const staged = await writeStreamToTempSource({
+                stream,
+                maxBytes: limit,
                 mode: writeOptions?.mode ?? mode,
-                tempPrefix: writeOptions?.tempPrefix ?? `.${path.basename(destination)}`,
-                writeTemp: async (tempPath) => {
-                    const writable = await fs.open(tempPath, "w", writeOptions?.mode ?? mode);
-                    try {
-                        const out = writable.createWriteStream();
-                        stream.on("data", (chunk) => {
-                            total += Buffer.byteLength(chunk);
-                            if (limit !== undefined && total > limit) {
-                                stream.destroy(new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`));
-                            }
-                        });
-                        await pipeline(stream, out);
-                    }
-                    finally {
-                        await writable.close().catch(() => undefined);
-                    }
-                },
-                resolveFinalPath: () => destination,
-                syncTempFile: true,
-                syncParentDir: true,
             });
-            return result.filePath;
+            try {
+                await copyIntoRoot({
+                    rootDir,
+                    relativePath: safeRelativePath,
+                    sourcePath: staged.path,
+                    maxBytes: limit,
+                    mode: writeOptions?.mode ?? mode,
+                    tempPrefix: writeOptions?.tempPrefix,
+                    dirMode: writeOptions?.dirMode ?? dirMode,
+                });
+            }
+            finally {
+                await staged.cleanup();
+            }
+            return destination;
         },
         copyIn: async (relativePath, sourcePath, writeOptions) => privateMode
             ? await (async () => {
-                const sourceStat = await fs.lstat(sourcePath);
-                if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-                    throw new FsSafeError("not-file", "source path is not a file");
-                }
-                assertMaxBytes(sourceStat.size, writeOptions?.maxBytes ?? maxBytes);
-                return await write(relativePath, await fs.readFile(sourcePath), writeOptions);
+                const buffer = await readFileStoreCopySource({
+                    sourcePath,
+                    maxBytes: writeOptions?.maxBytes ?? maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
+                });
+                return await write(relativePath, buffer, writeOptions);
             })()
             : await copyIntoRoot({
                 rootDir,
@@ -240,50 +258,10 @@ export function fileStore(options) {
             }, jsonOptions);
         },
         pruneExpired: async (pruneOptions) => {
-            const now = Date.now();
-            const recursive = pruneOptions.recursive ?? false;
-            const maxDepth = pruneOptions.maxDepth;
-            const pruneEmptyDirs = (recursive || maxDepth !== undefined) && (pruneOptions.pruneEmptyDirs ?? false);
-            async function pruneDir(dir, depth) {
-                const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-                for (const entry of entries) {
-                    const fullPath = path.join(dir, entry.name);
-                    const stat = await fs.lstat(fullPath).catch(() => null);
-                    if (!stat || stat.isSymbolicLink()) {
-                        continue;
-                    }
-                    if (stat.isDirectory()) {
-                        const shouldDescend = maxDepth !== undefined ? depth < maxDepth : recursive;
-                        if (shouldDescend && (await pruneDir(fullPath, depth + 1))) {
-                            await fs.rmdir(fullPath).catch(() => undefined);
-                        }
-                        continue;
-                    }
-                    if (stat.isFile() && now - stat.mtimeMs > pruneOptions.ttlMs) {
-                        await fs.rm(fullPath, { force: true }).catch(() => undefined);
-                    }
-                }
-                if (!pruneEmptyDirs) {
-                    return false;
-                }
-                const remaining = await fs.readdir(dir).catch(() => null);
-                return remaining !== null && remaining.length === 0;
-            }
-            await fs.mkdir(rootDir, { recursive: true, mode: dirMode });
-            await pruneDir(rootDir, 0);
+            await pruneExpiredStoreEntries({ rootDir, dirMode, options: pruneOptions });
         },
     };
 }
-function ensureParentSync(filePath, mode) {
-    const dir = path.dirname(filePath);
-    syncFs.mkdirSync(dir, { recursive: true, mode });
-    try {
-        syncFs.chmodSync(dir, mode);
-    }
-    catch {
-        // Best-effort on platforms that do not enforce POSIX modes.
-    }
-}
 function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
     const root = path.resolve(rootDir);
     const target = path.resolve(targetDir);
@@ -326,12 +304,16 @@ function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
             // Best-effort on platforms that do not enforce POSIX modes.
         }
     }
+    const guard = createSyncDirectoryGuard(target);
+    assertSyncDirectoryGuard(guard);
+    return guard;
 }
 function writeFileSyncAtomic(params) {
     const filePath = path.resolve(params.filePath);
     assertStoreFilePath(params.rootDir, filePath);
+    let parentGuard;
     if (params.privateMode) {
-        ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
+        parentGuard = ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
         try {
             const stat = syncFs.lstatSync(filePath);
             if (stat.isSymbolicLink() || !stat.isFile()) {
@@ -345,11 +327,19 @@ function writeFileSyncAtomic(params) {
         }
     }
     else {
-        ensureParentSync(filePath, params.dirMode);
+        parentGuard = ensureParentSync({
+            rootDir: params.rootDir,
+            filePath,
+            mode: params.dirMode,
+        });
     }
-    const tempPath = path.join(path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
+    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);
+        }
         syncFs.writeFileSync(tempPath, params.content, { flag: "wx", mode: params.mode });
         tempExists = true;
         try {
@@ -358,8 +348,14 @@ function writeFileSyncAtomic(params) {
         catch {
             // Best-effort on platforms that do not enforce POSIX modes.
         }
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
         syncFs.renameSync(tempPath, filePath);
         tempExists = false;
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
         try {
             syncFs.chmodSync(filePath, params.mode);
         }
@@ -403,22 +399,23 @@ export function fileStoreSync(options) {
         path: (relativePath) => resolveStorePath(rootDir, relativePath),
         readTextIfExists: (relativePath, readOptions) => {
             const targetPath = resolveStorePath(rootDir, relativePath);
+            const opened = openRootFileSync({
+                absolutePath: targetPath,
+                rootPath: rootDir,
+                boundaryLabel: "store root",
+                rejectHardlinks: privateMode,
+            });
+            if (!opened.ok) {
+                return handleSyncStoreReadOpenFailure(opened);
+            }
             try {
-                const stat = syncFs.lstatSync(targetPath);
-                if (stat.isSymbolicLink() || !stat.isFile()) {
-                    throw new FsSafeError("not-file", "store target is not a file");
-                }
-                assertMaxBytes(stat.size, readOptions?.maxBytes ?? maxBytes);
-                if (privateMode && stat.nlink > 1) {
-                    throw new FsSafeError("hardlink", "private store target must not be hardlinked");
-                }
-                return syncFs.readFileSync(targetPath, "utf8");
+                assertMaxBytes(opened.stat.size, readOptions?.maxBytes ?? maxBytes);
+                const raw = syncFs.readFileSync(opened.fd, "utf8");
+                assertMaxBytes(Buffer.byteLength(raw, "utf8"), readOptions?.maxBytes ?? maxBytes);
+                return raw;
             }
-            catch (error) {
-                if (isNotFound(error)) {
-                    return null;
-                }
-                throw error;
+            finally {
+                syncFs.closeSync(opened.fd);
             }
         },
         readJsonIfExists: (relativePath, readOptions) => {

package/dist/guarded-mkdir.d.ts

@@ -0,0 +1,6 @@
+export declare function mkdirPathComponentsWithGuards(params: {
+    rootReal: string;
+    targetPath: string;
+    beforeComponent?: (componentPath: string) => Promise<void> | void;
+}): Promise<void>;
+//# sourceMappingURL=guarded-mkdir.d.ts.map

package/dist/guarded-mkdir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAaA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChB"}

package/dist/guarded-mkdir.js

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+function isSameOrChildPath(candidate, parent) {
+    return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
+}
+function isPathEscape(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
+export async function mkdirPathComponentsWithGuards(params) {
+    const root = path.resolve(params.rootReal);
+    const target = path.resolve(params.targetPath);
+    const relative = path.relative(root, target);
+    if (isPathEscape(relative)) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    let current = root;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        const next = path.join(current, part);
+        const parentGuard = await createAsyncDirectoryGuard(current);
+        await params.beforeComponent?.(next);
+        await assertAsyncDirectoryGuard(parentGuard);
+        try {
+            await fs.mkdir(next);
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+        const stat = await fs.lstat(next);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new FsSafeError("not-file", "directory component must be a directory");
+        }
+        // Node's recursive mkdir follows symlinks in missing components. Build one
+        // segment at a time and realpath-check each segment before descending.
+        if (!isSameOrChildPath(path.resolve(await fs.realpath(next)), root)) {
+            throw new FsSafeError("outside-workspace", "directory escaped workspace root");
+        }
+        await createAsyncDirectoryGuard(next);
+        await assertAsyncDirectoryGuard(parentGuard);
+        current = next;
+    }
+}

package/dist/guarded-mutation.d.ts

@@ -0,0 +1,33 @@
+import { type AsyncDirectoryGuard, type SyncDirectoryGuard } from "./directory-guard.js";
+export declare function withAsyncDirectoryGuards<T>(guards: readonly AsyncDirectoryGuard[], mutate: () => Promise<T>, options?: {
+    verifyAfter?: boolean;
+    onPostGuardFailure?: (result: T, error: unknown) => Promise<void> | void;
+}): Promise<T>;
+export declare function withSyncDirectoryGuards<T>(guards: readonly SyncDirectoryGuard[], mutate: () => T, options?: {
+    verifyAfter?: boolean;
+}): T;
+export declare function guardedRename(params: {
+    from: string;
+    to: string;
+    targetRoot?: string;
+    verifyAfter?: boolean;
+}): Promise<void>;
+export declare function guardedRenameSync(params: {
+    from: string;
+    to: string;
+    targetRoot?: string;
+    verifyAfter?: boolean;
+}): void;
+export declare function guardedRm(params: {
+    target: string;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): Promise<void>;
+export declare function guardedRmSync(params: {
+    target: string;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): void;
+//# sourceMappingURL=guarded-mutation.d.ts.map

package/dist/guarded-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}

package/dist/guarded-mutation.js

@@ -0,0 +1,76 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, createNearestExistingSyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
+export async function withAsyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        await assertAsyncDirectoryGuard(guard);
+    }
+    const result = await mutate();
+    if (options.verifyAfter !== false) {
+        try {
+            for (const guard of guards) {
+                await assertAsyncDirectoryGuard(guard);
+            }
+        }
+        catch (error) {
+            if (options.onPostGuardFailure) {
+                try {
+                    // The mutation may have returned an owned resource before the post-guard
+                    // check detected a swapped directory. Give callers one chance to close
+                    // handles without letting cleanup hide the boundary failure.
+                    await options.onPostGuardFailure(result, error);
+                }
+                catch {
+                    // Preserve the boundary failure. Cleanup is best-effort.
+                }
+            }
+            throw error;
+        }
+    }
+    return result;
+}
+export function withSyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        assertSyncDirectoryGuard(guard);
+    }
+    const result = mutate();
+    if (options.verifyAfter !== false) {
+        for (const guard of guards) {
+            assertSyncDirectoryGuard(guard);
+        }
+    }
+    return result;
+}
+export async function guardedRename(params) {
+    const sourceGuard = await createAsyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = params.targetRoot
+        ? await createNearestExistingDirectoryGuard(params.targetRoot, path.dirname(params.to))
+        : await createAsyncDirectoryGuard(path.dirname(params.to));
+    await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
+        await fs.rename(params.from, params.to);
+    }, { verifyAfter: params.verifyAfter });
+}
+export function guardedRenameSync(params) {
+    const sourceGuard = createSyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = params.targetRoot
+        ? createNearestExistingSyncDirectoryGuard(params.targetRoot, path.dirname(params.to))
+        : createSyncDirectoryGuard(path.dirname(params.to));
+    withSyncDirectoryGuards([sourceGuard, targetGuard], () => fsSync.renameSync(params.from, params.to), { verifyAfter: params.verifyAfter });
+}
+export async function guardedRm(params) {
+    const guard = await createAsyncDirectoryGuard(path.dirname(params.target));
+    await withAsyncDirectoryGuards([guard], async () => {
+        await fs.rm(params.target, {
+            ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+            ...(params.force !== undefined ? { force: params.force } : {}),
+        });
+    }, { verifyAfter: params.verifyAfter });
+}
+export function guardedRmSync(params) {
+    const guard = createSyncDirectoryGuard(path.dirname(params.target));
+    withSyncDirectoryGuards([guard], () => fsSync.rmSync(params.target, {
+        ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+        ...(params.force !== undefined ? { force: params.force } : {}),
+    }), { verifyAfter: params.verifyAfter });
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, } from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, type HardlinkPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
 export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
+export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
 export { configureFsSafePython, getFsSafePythonConfig, } from "./pinned-python-config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/json-document-store.d.ts

@@ -1,8 +1,10 @@
 import type { FileLockRetryOptions } from "./file-lock.js";
+import type { SidecarLockStaleRecovery } from "./sidecar-lock.js";
 export type JsonStoreLockOptions = {
     staleMs?: number;
     timeoutMs?: number;
     retry?: FileLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
     managerKey?: string;
 };
 export type JsonFileStoreOptions = {

package/dist/json-document-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AAyBF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA0Dd"}
+{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA2Dd"}

package/dist/json-document-store.js

@@ -1,3 +1,4 @@
+import { getFsSafeLockConfig } from "./lock-config.js";
 import { createSidecarLockManager } from "./sidecar-lock.js";
 function cloneFallback(value) {
     if (value && typeof value === "object") {
@@ -10,11 +11,13 @@ function resolveLockOptions(filePath, options) {
         return null;
     }
     const lockOptions = options.lock === true ? {} : options.lock;
+    const defaults = getFsSafeLockConfig();
     return {
         managerKey: lockOptions.managerKey ?? `fs-safe.json-store:${filePath}`,
-        retry: lockOptions.retry ?? {},
-        staleMs: lockOptions.staleMs ?? 30_000,
-        timeoutMs: lockOptions.timeoutMs ?? 30_000,
+        retry: lockOptions.retry ?? defaults.retry ?? {},
+        staleMs: lockOptions.staleMs ?? defaults.staleMs ?? 30_000,
+        staleRecovery: lockOptions.staleRecovery ?? defaults.staleRecovery,
+        timeoutMs: lockOptions.timeoutMs ?? defaults.timeoutMs ?? 30_000,
     };
 }
 export function createJsonStore(adapter, options = {}) {
@@ -40,6 +43,7 @@ export function createJsonStore(adapter, options = {}) {
             staleMs: lockOptions.staleMs,
             timeoutMs: lockOptions.timeoutMs,
             retry: lockOptions.retry,
+            staleRecovery: lockOptions.staleRecovery,
             allowReentrant: true,
             payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
         }, run);