@openclaw/fs-safe 0.1.1 → 0.2.0

package/dist/archive.js

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -10,7 +9,7 @@ import { resolveArchiveKind } from "./archive-kind.js";
 import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import { createTarEntryPreflightChecker, readTarEntryInfo, } from "./archive-tar.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
-import { isNotFoundPathError } from "./path.js";
+import { writeSiblingTempFile } from "./sibling-temp.js";
 import { withTimeout } from "./timing.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
@@ -24,24 +23,6 @@ const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
     (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-async function cleanupPartialRegularFile(filePath) {
-    let stat;
-    try {
-        stat = await fs.lstat(filePath);
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            return;
-        }
-        throw err;
-    }
-    if (stat.isFile()) {
-        await fs.unlink(filePath).catch(() => undefined);
-    }
-}
-function buildArchiveAtomicTempPath(targetPath) {
-    return path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
-}
 const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
 const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
 function isZipSymlinkEntry(entry) {
@@ -80,23 +61,28 @@ async function writeZipFileEntry(params) {
     const readable = await readZipEntryStream(params.entry);
     const destinationPath = params.outPath;
     let tempHandle = null;
-    let tempPath = null;
     let handleClosedByStream = false;
     try {
-        tempPath = buildArchiveAtomicTempPath(destinationPath);
-        tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o666);
-        const writable = tempHandle.createWriteStream();
-        writable.once("close", () => {
-            handleClosedByStream = true;
+        await writeSiblingTempFile({
+            dir: path.dirname(destinationPath),
+            tempPrefix: `.${path.basename(destinationPath)}.fs-safe-archive`,
+            chmodDir: false,
+            writeTemp: async (tempPath) => {
+                tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o666);
+                const writable = tempHandle.createWriteStream();
+                writable.once("close", () => {
+                    handleClosedByStream = true;
+                });
+                await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), writable);
+                if (!handleClosedByStream) {
+                    await tempHandle.close().catch(() => undefined);
+                    handleClosedByStream = true;
+                }
+                tempHandle = null;
+                return destinationPath;
+            },
+            resolveFinalPath: (filePath) => filePath,
         });
-        await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), writable);
-        if (!handleClosedByStream) {
-            await tempHandle.close().catch(() => undefined);
-            handleClosedByStream = true;
-        }
-        tempHandle = null;
-        await fs.rename(tempPath, destinationPath);
-        tempPath = null;
         // Best-effort permission restore for zip entries created on unix.
         if (typeof params.entry.unixPermissions === "number") {
             const mode = params.entry.unixPermissions & 0o777;
@@ -106,17 +92,14 @@ async function writeZipFileEntry(params) {
         }
     }
     catch (err) {
-        if (tempPath) {
-            await fs.rm(tempPath, { force: true }).catch(() => undefined);
-        }
-        else {
-            await cleanupPartialRegularFile(destinationPath).catch(() => undefined);
-        }
+        // Failures here happen before the temp has been committed. The destination
+        // parent may already be untrusted, so cleanup must stay limited to temp state.
         throw err;
     }
     finally {
-        if (tempHandle && !handleClosedByStream) {
-            await tempHandle.close().catch(() => undefined);
+        const openTempHandle = tempHandle;
+        if (openTempHandle && !handleClosedByStream) {
+            await openTempHandle.close().catch(() => undefined);
         }
     }
 }

package/dist/bounded-read-stream.d.ts

@@ -0,0 +1,8 @@
+import { Transform } from "node:stream";
+export declare function createMaxBytesTransform(maxBytes: number): Transform;
+export declare function createBoundedReadStream(opened: {
+    handle: {
+        createReadStream(): NodeJS.ReadableStream;
+    };
+}, maxBytes: number | undefined): NodeJS.ReadableStream;
+//# sourceMappingURL=bounded-read-stream.d.ts.map

package/dist/bounded-read-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-read-stream.d.ts","sourceRoot":"","sources":["../src/bounded-read-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAkBnE;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE;IAAE,MAAM,EAAE;QAAE,gBAAgB,IAAI,MAAM,CAAC,cAAc,CAAA;KAAE,CAAA;CAAE,EACjE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,CAAC,cAAc,CAGvB"}

package/dist/bounded-read-stream.js

@@ -0,0 +1,20 @@
+import { Transform } from "node:stream";
+import { FsSafeError } from "./errors.js";
+export function createMaxBytesTransform(maxBytes) {
+    let bytes = 0;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            const buffer = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+            bytes += buffer.byteLength;
+            if (bytes > maxBytes) {
+                callback(new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`));
+                return;
+            }
+            callback(null, buffer);
+        },
+    });
+}
+export function createBoundedReadStream(opened, maxBytes) {
+    const stream = opened.handle.createReadStream();
+    return maxBytes === undefined ? stream : stream.pipe(createMaxBytesTransform(maxBytes));
+}

package/dist/config.d.ts

@@ -1,2 +1,3 @@
 export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/config.js

@@ -1 +1,2 @@
 export { configureFsSafePython, getFsSafePythonConfig, } from "./pinned-python-config.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/directory-guard.d.ts

@@ -0,0 +1,18 @@
+import type { Stats } from "node:fs";
+export type AsyncDirectoryGuard = {
+    dir: string;
+    realPath: string;
+    stat: Stats;
+};
+export type SyncDirectoryGuard = {
+    dir: string;
+    realPath: string;
+    stat: Stats;
+};
+export declare function createAsyncDirectoryGuard(dir: string): Promise<AsyncDirectoryGuard>;
+export declare function assertAsyncDirectoryGuard(guard: AsyncDirectoryGuard): Promise<void>;
+export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
+export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard): void;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string): Promise<AsyncDirectoryGuard>;
+export declare function createNearestExistingSyncDirectoryGuard(rootReal: string, targetPath: string): SyncDirectoryGuard;
+//# sourceMappingURL=directory-guard.d.ts.map

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

@@ -0,0 +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"}

package/dist/directory-guard.js

@@ -0,0 +1,70 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.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");
+    }
+    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");
+    }
+    if (!sameFileIdentity(stat, guard.stat) || (await fs.realpath(guard.dir)) !== guard.realPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
+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");
+    }
+    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");
+    }
+    if (!sameFileIdentity(stat, guard.stat) || fsSync.realpathSync(guard.dir) !== guard.realPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
+export async function createNearestExistingDirectoryGuard(rootReal, targetPath) {
+    let current = path.resolve(targetPath);
+    const root = path.resolve(rootReal);
+    while (current !== root) {
+        try {
+            return await createAsyncDirectoryGuard(current);
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error)) {
+                throw error;
+            }
+            current = path.dirname(current);
+        }
+    }
+    return await createAsyncDirectoryGuard(root);
+}
+export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
+    let current = path.resolve(targetPath);
+    const root = path.resolve(rootReal);
+    while (current !== root) {
+        try {
+            return createSyncDirectoryGuard(current);
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error)) {
+                throw error;
+            }
+            current = path.dirname(current);
+        }
+    }
+    return createSyncDirectoryGuard(root);
+}

package/dist/file-lock.d.ts

@@ -1,7 +1,9 @@
-import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions } from "./sidecar-lock.js";
+import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions, type SidecarLockStaleRecovery } from "./sidecar-lock.js";
 export type FileLockRetryOptions = SidecarLockRetryOptions;
-export type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath"> & {
+export type FileLockStaleRecovery = SidecarLockStaleRecovery;
+export type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath" | "staleMs"> & {
     managerKey?: string;
+    staleMs?: number;
 };
 export type FileLockHandle = SidecarLockHandle;
 export type FileLockHeldEntry = SidecarLockHeldEntry;

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

@@ -1 +1 @@
-{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAMF,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF"}
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,GAAG,SAAS,CACzB,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAmBF,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF"}

package/dist/file-lock.js

@@ -1,7 +1,18 @@
 import { createSidecarLockManager, } from "./sidecar-lock.js";
+import { getFsSafeLockConfig } from "./lock-config.js";
 function resolveFileLockManagerKey(targetPath, managerKey) {
     return managerKey ?? `fs-safe.file-lock:${targetPath}`;
 }
+function withLockDefaults(options) {
+    const defaults = getFsSafeLockConfig();
+    return {
+        ...options,
+        retry: options.retry ?? defaults.retry,
+        staleMs: options.staleMs ?? defaults.staleMs ?? 30_000,
+        staleRecovery: options.staleRecovery ?? defaults.staleRecovery,
+        timeoutMs: options.timeoutMs ?? defaults.timeoutMs,
+    };
+}
 export async function acquireFileLock(targetPath, options) {
     return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
         .acquire(targetPath, options);
@@ -15,11 +26,11 @@ export function createFileLockManager(key) {
     return {
         acquire: async (targetPath, options) => {
             const { managerKey: _managerKey, ...acquireOptions } = options;
-            return await manager.acquire({ ...acquireOptions, targetPath });
+            return await manager.acquire({ ...withLockDefaults(acquireOptions), targetPath });
         },
         withLock: async (targetPath, options, fn) => {
             const { managerKey: _managerKey, ...acquireOptions } = options;
-            return await manager.withLock({ ...acquireOptions, targetPath }, fn);
+            return await manager.withLock({ ...withLockDefaults(acquireOptions), targetPath }, fn);
         },
         drain: manager.drain,
         reset: manager.reset,

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

@@ -0,0 +1,25 @@
+import { type Readable } from "node:stream";
+import { type SyncDirectoryGuard } from "./directory-guard.js";
+import { type Root } from "./root.js";
+export type SyncParentGuard = SyncDirectoryGuard;
+export declare function ensureParentInRoot(scopedRoot: Root, relativePath: string, mode: number): Promise<void>;
+export declare function openWritableStoreRoot(params: {
+    rootDir: string;
+    dirMode: number;
+    maxBytes?: number;
+}): Promise<Root>;
+export declare function writeStreamToTempSource(params: {
+    stream: Readable;
+    maxBytes?: number;
+    mode: number;
+}): Promise<{
+    path: string;
+    cleanup: () => Promise<void>;
+}>;
+export declare function assertSyncDirectoryGuard(guard: SyncParentGuard): void;
+export declare function ensureParentSync(params: {
+    rootDir: string;
+    filePath: string;
+    mode: number;
+}): SyncParentGuard;
+//# sourceMappingURL=file-store-boundary.d.ts.map

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

@@ -0,0 +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"}

package/dist/file-store-boundary.js

@@ -0,0 +1,168 @@
+import syncFs from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+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 { isPathInside } from "./path.js";
+import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+function parentRelativePath(relativePath) {
+    const parent = path.posix.dirname(relativePath);
+    return parent === "." ? "" : parent;
+}
+export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
+    const parent = parentRelativePath(relativePath);
+    if (!parent) {
+        return;
+    }
+    await scopedRoot.mkdir(parent);
+    await chmodDirectoryInRootBestEffort(scopedRoot, parent, mode).catch(() => undefined);
+}
+export async function openWritableStoreRoot(params) {
+    await fs.mkdir(params.rootDir, { recursive: true, mode: params.dirMode });
+    await fs.chmod(params.rootDir, params.dirMode).catch(() => undefined);
+    return await root(params.rootDir, { hardlinks: "reject", maxBytes: params.maxBytes });
+}
+async function chmodDirectoryInRootBestEffort(scopedRoot, relativePath, mode) {
+    const dirPath = await scopedRoot.resolve(relativePath);
+    const directoryFlag = "O_DIRECTORY" in syncFs.constants ? syncFs.constants.O_DIRECTORY : 0;
+    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants
+        ? syncFs.constants.O_NOFOLLOW
+        : 0;
+    const handle = await fs.open(dirPath, syncFs.constants.O_RDONLY | directoryFlag | noFollowFlag);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isDirectory()) {
+            return;
+        }
+        const realPath = await resolveOpenedFileRealPathForHandle(handle, dirPath);
+        if (!isPathInside(scopedRoot.rootWithSep, realPath)) {
+            throw new FsSafeError("outside-workspace", "directory is outside store root");
+        }
+        await handle.chmod(mode).catch(() => undefined);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function createMaxBytesTransform(maxBytes) {
+    if (maxBytes === undefined) {
+        return undefined;
+    }
+    let total = 0;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buffer.byteLength;
+            if (total > maxBytes) {
+                callback(new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`));
+                return;
+            }
+            callback(null, buffer);
+        },
+    });
+}
+export async function writeStreamToTempSource(params) {
+    const tempRoot = resolveSecureTempRoot({
+        fallbackPrefix: "fs-safe-file-store",
+        unsafeFallbackLabel: "file store temp dir",
+        warn: () => undefined,
+    });
+    const dir = await fs.mkdtemp(path.join(tempRoot, "fs-safe-file-store-"));
+    const filePath = path.join(dir, "payload");
+    let handle = null;
+    let handleClosedByStream = false;
+    try {
+        handle = await fs.open(filePath, "wx", params.mode);
+        const writable = handle.createWriteStream();
+        writable.once("close", () => {
+            handleClosedByStream = true;
+        });
+        const limiter = createMaxBytesTransform(params.maxBytes);
+        if (limiter) {
+            await pipeline(params.stream, limiter, writable);
+        }
+        else {
+            await pipeline(params.stream, writable);
+        }
+        if (!handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
+        await fs.chmod(filePath, params.mode).catch(() => undefined);
+        return {
+            path: filePath,
+            cleanup: async () => {
+                await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+            },
+        };
+    }
+    catch (err) {
+        if (handle && !handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+export function assertSyncDirectoryGuard(guard) {
+    try {
+        assertDirectoryGuardSync(guard);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch") {
+            throw new FsSafeError("path-mismatch", "store directory changed during write", {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}
+function chmodDirectorySyncBestEffort(dir, mode) {
+    try {
+        syncFs.chmodSync(dir, mode);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+}
+export function ensureParentSync(params) {
+    const rootDir = path.resolve(params.rootDir);
+    const dir = path.dirname(path.resolve(params.filePath));
+    const relative = path.relative(rootDir, dir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new FsSafeError("outside-workspace", "file path escapes store root");
+    }
+    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}`);
+    }
+    const rootReal = syncFs.realpathSync(rootDir);
+    chmodDirectorySyncBestEffort(rootDir, params.mode);
+    let current = rootDir;
+    for (const segment of path.relative(rootDir, dir).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = syncFs.lstatSync(current);
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                throw new FsSafeError("not-file", `store directory component must be a directory: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            syncFs.mkdirSync(current, { mode: params.mode });
+        }
+        const currentReal = syncFs.realpathSync(current);
+        if (!isPathInside(rootReal, currentReal)) {
+            throw new FsSafeError("outside-workspace", "store directory escapes root");
+        }
+        chmodDirectorySyncBestEffort(current, params.mode);
+    }
+    const guard = createSyncDirectoryGuard(dir);
+    assertSyncDirectoryGuard(guard);
+    return guard;
+}

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

@@ -0,0 +1,12 @@
+export type FileStorePruneOptions = {
+    ttlMs: number;
+    recursive?: boolean;
+    maxDepth?: number;
+    pruneEmptyDirs?: boolean;
+};
+export declare function pruneExpiredStoreEntries(params: {
+    rootDir: string;
+    dirMode: number;
+    options: FileStorePruneOptions;
+}): Promise<void>;
+//# sourceMappingURL=file-store-prune.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-store-prune.d.ts","sourceRoot":"","sources":["../src/file-store-prune.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,qBAAqB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAsFhB"}

package/dist/file-store-prune.js

@@ -0,0 +1,86 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export async function pruneExpiredStoreEntries(params) {
+    const now = Date.now();
+    const recursive = params.options.recursive ?? false;
+    const maxDepth = params.options.maxDepth;
+    const pruneEmptyDirs = (recursive || maxDepth !== undefined) && (params.options.pruneEmptyDirs ?? false);
+    await fs.mkdir(params.rootDir, { recursive: true, mode: params.dirMode });
+    const rootReal = await fs.realpath(params.rootDir);
+    const scopedRoot = await root(rootReal);
+    const rootGuard = {
+        dir: rootReal,
+        realPath: rootReal,
+        stat: await fs.lstat(rootReal),
+    };
+    async function assertRootGuard() {
+        const stat = await fs.lstat(rootGuard.dir);
+        if (stat.isSymbolicLink() ||
+            !stat.isDirectory() ||
+            stat.dev !== rootGuard.stat.dev ||
+            stat.ino !== rootGuard.stat.ino ||
+            (await fs.realpath(rootGuard.dir)) !== rootGuard.realPath) {
+            throw new FsSafeError("path-mismatch", "store root changed during prune");
+        }
+    }
+    async function readStableDirectory(dir) {
+        const before = await fs.lstat(dir).catch(() => null);
+        if (!before || before.isSymbolicLink() || !before.isDirectory()) {
+            return null;
+        }
+        const real = await fs.realpath(dir).catch(() => null);
+        if (!real || !isPathInside(rootReal, real)) {
+            return null;
+        }
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => null);
+        if (!entries) {
+            return null;
+        }
+        const after = await fs.lstat(dir).catch(() => null);
+        if (!after || before.dev !== after.dev || before.ino !== after.ino) {
+            return null;
+        }
+        return entries;
+    }
+    async function pruneDir(dir, relativeDir, depth) {
+        const entries = await readStableDirectory(dir);
+        if (!entries) {
+            return false;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : 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 getFsSafeTestHooks()?.beforeFileStorePruneDescend?.(fullPath);
+                }
+                if (shouldDescend && (await pruneDir(fullPath, relativePath, depth + 1))) {
+                    await assertRootGuard();
+                    // Keep empty-dir pruning on the same root-bounded remove path as files;
+                    // the Root fallback handles empty directories without recursive delete.
+                    await scopedRoot.remove(relativePath).catch(() => undefined);
+                }
+                continue;
+            }
+            if (stat.isFile() && now - stat.mtimeMs > params.options.ttlMs) {
+                await assertRootGuard();
+                await scopedRoot.remove(relativePath).catch(() => undefined);
+            }
+        }
+        if (!pruneEmptyDirs) {
+            return false;
+        }
+        const remaining = await readStableDirectory(dir);
+        return remaining !== null && remaining.length === 0;
+    }
+    await pruneDir(rootReal, "", 0);
+}

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

@@ -0,0 +1,5 @@
+export declare function readFileStoreCopySource(params: {
+    sourcePath: string;
+    maxBytes?: number;
+}): Promise<Buffer>;
+//# sourceMappingURL=file-store-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-store-source.d.ts","sourceRoot":"","sources":["../src/file-store-source.ts"],"names":[],"mappings":"AAIA,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB"}

package/dist/file-store-source.js

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { readRegularFile } from "./regular-file.js";
+export async function readFileStoreCopySource(params) {
+    const sourceStat = await fs.lstat(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    if (params.maxBytes !== undefined && sourceStat.size > params.maxBytes) {
+        throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`);
+    }
+    try {
+        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
+            .buffer;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("regular file") || message.includes("not a regular file")) {
+            throw new FsSafeError("not-file", "source path is not a file", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        if (params.maxBytes !== undefined && message.includes(`exceeds ${params.maxBytes} bytes`)) {
+            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
+    }
+}