@openclaw/fs-safe 0.10.0 → 0.11.0

package/dist/root-paths.d.ts.map

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

package/dist/root-paths.js

@@ -5,6 +5,7 @@ import { formatErrorDetail } from "./error-detail.js";
 import { FsSafeError } from "./errors.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNodeError, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
 import { root as openRoot } from "./root.js";
+import { realpathSync } from "./realpath.js";
 function invalidPath(scopeLabel) {
     return {
         ok: false,
@@ -12,12 +13,15 @@ function invalidPath(scopeLabel) {
     };
 }
 function pathStaysWithinRoot(rootDir, candidatePath) {
+    if (process.platform !== "win32") {
+        return candidatePath !== rootDir && isPathInside(rootDir, candidatePath);
+    }
     const relative = path.relative(rootDir, candidatePath);
     return Boolean(relative) && !isPathRelativeEscape(relative);
 }
 async function resolveRealPathIfExists(targetPath) {
     try {
-        return fsSync.realpathSync.native(targetPath);
+        return realpathSync.native(targetPath);
     }
     catch {
         return undefined;
@@ -29,7 +33,7 @@ async function resolveTrustedRootRealPath(rootDir) {
         if (!rootLstat.isDirectory() || rootLstat.isSymbolicLink()) {
             return undefined;
         }
-        return fsSync.realpathSync.native(rootDir);
+        return realpathSync.native(rootDir);
     }
     catch {
         return undefined;
@@ -50,7 +54,7 @@ async function validateCanonicalPathWithinRoot(params) {
         if (params.expect === "file" && candidateLstat.nlink > 1) {
             return "invalid";
         }
-        const candidateRealPath = fsSync.realpathSync.native(params.candidatePath);
+        const candidateRealPath = realpathSync.native(params.candidatePath);
         return isPathInside(params.rootRealPath, candidateRealPath) ? "ok" : "invalid";
     }
     catch (err) {
@@ -169,9 +173,9 @@ export async function ensureDirectoryWithinRoot(params) {
             return invalidPath(scopeLabel);
         }
         await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
-        const rootReal = fsSync.realpathSync.native(rootDir);
+        const rootReal = realpathSync.native(rootDir);
         const nearestExistingPath = await resolveNearestExistingPath(targetPath);
-        const nearestExistingReal = fsSync.realpathSync.native(nearestExistingPath);
+        const nearestExistingReal = realpathSync.native(nearestExistingPath);
         if (!isPathInside(rootReal, nearestExistingReal)) {
             return invalidPath(scopeLabel);
         }
@@ -202,12 +206,12 @@ export async function ensureDirectoryWithinRoot(params) {
                     }
                 }
             }
-            const currentReal = fsSync.realpathSync.native(current);
+            const currentReal = realpathSync.native(current);
             if (!isPathInside(rootReal, currentReal)) {
                 return invalidPath(scopeLabel);
             }
         }
-        const targetReal = fsSync.realpathSync.native(targetPath);
+        const targetReal = realpathSync.native(targetPath);
         if (!isPathInside(rootReal, targetReal)) {
             return invalidPath(scopeLabel);
         }
@@ -309,7 +313,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
             return lexicalPathResult;
         }
         try {
-            const resolvedExistingPath = fsSync.realpathSync.native(raw);
+            const resolvedExistingPath = realpathSync.native(raw);
             const relativePath = path.relative(rootRealPath, resolvedExistingPath);
             if (!isInRoot(relativePath)) {
                 return lexicalPathResult;
@@ -351,7 +355,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                         scopeLabel: params.scopeLabel,
                     });
                     const existingPath = await resolveNearestExistingPath(pathResult.fallbackPath);
-                    const existingRealPath = fsSync.realpathSync.native(existingPath);
+                    const existingRealPath = realpathSync.native(existingPath);
                     if (!isPathInside(rootRealPath, existingRealPath)) {
                         return invalidPath(params.scopeLabel);
                     }

package/dist/root-remove.d.ts

@@ -0,0 +1,5 @@
+import { type RootContext } from "./root-context.js";
+import type { RootRemoveOptions } from "./root-options.js";
+export declare function validateRemoveOptions(options: RootRemoveOptions): void;
+export declare function removePathInRootFallback(root: RootContext, targetPath: string, options: RootRemoveOptions): Promise<void>;
+//# sourceMappingURL=root-remove.d.ts.map

package/dist/root-remove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-remove.d.ts","sourceRoot":"","sources":["../src/root-remove.ts"],"names":[],"mappings":"AAeA,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAS3D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAgBtE;AA0CD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA6Lf"}

package/dist/root-remove.js

@@ -0,0 +1,286 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { assertMutationNotDenied } from "./deny-mutations.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { normalizeRemoveGuardError, normalizeRemovePathError, rootPathChangedError } from "./root-errors.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+const DEFAULT_MAX_ENTRIES = 100_000;
+const DEFAULT_MAX_DEPTH = 64;
+export function validateRemoveOptions(options) {
+    if (options.order !== undefined && options.order !== "filesystem" && options.order !== "sorted") {
+        throw new TypeError("remove order must be filesystem or sorted");
+    }
+    for (const key of ["maxEntries", "maxDepth"]) {
+        const value = options[key];
+        if (value !== undefined && value !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(value) || value < 0)) {
+            throw new RangeError(`${key} must be a non-negative safe integer`);
+        }
+    }
+    if (!options.recursive && (options.maxEntries !== undefined || options.maxDepth !== undefined)) {
+        throw new TypeError("remove budgets require recursive: true");
+    }
+    if (!options.recursive && options.order !== undefined) {
+        throw new TypeError("remove order requires recursive: true");
+    }
+}
+function assertNotAborted(signal) {
+    try {
+        signal?.throwIfAborted();
+    }
+    catch (error) {
+        // Preserve arbitrary abort reasons through Root's filesystem error mapping.
+        throw new MutationAuthorityError(error);
+    }
+}
+async function removeOne(root, targetPath, options) {
+    let guard;
+    try {
+        guard = await createAsyncDirectoryGuard(path.dirname(targetPath));
+    }
+    catch (error) {
+        if (options.force && isNotFoundPathError(error)) {
+            await assertRootIdentityCurrent(root);
+            assertNotAborted(options.signal);
+            return;
+        }
+        throw normalizeRemoveGuardError(error);
+    }
+    try {
+        await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("remove", targetPath);
+        await assertAsyncDirectoryGuard(guard);
+    }
+    catch (error) {
+        throw normalizeRemoveGuardError(error);
+    }
+    try {
+        const isDirectory = fsSync.lstatSync(targetPath).isDirectory();
+        assertFinalSymlinkRejected(targetPath, options.mutationSymlinks !== undefined);
+        assertNotAborted(options.signal);
+        options.assertBeforeMutation?.();
+        await (isDirectory ? fs.rmdir(targetPath) : fs.unlink(targetPath));
+    }
+    catch (error) {
+        if (!(options.force && isNotFoundPathError(error)))
+            throw normalizeRemovePathError(error);
+    }
+    await assertAsyncDirectoryGuard(guard).catch(error => { throw normalizeRemoveGuardError(error); });
+    assertNotAborted(options.signal);
+}
+export async function removePathInRootFallback(root, targetPath, options) {
+    assertNotAborted(options.signal);
+    if (!options.recursive) {
+        await removeOne(root, targetPath, options);
+        return;
+    }
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const details = (target, phase) => ({
+        operation: "remove",
+        phase,
+        relativePath: path.relative(targetPath, target),
+    });
+    let examined = 0;
+    const rootGuard = await createAsyncDirectoryGuard(root.rootReal, { bigint: true });
+    if (!sameFileIdentityForCleanup(rootGuard.stat, root.rootIdentity))
+        throw rootPathChangedError();
+    const guards = [rootGuard];
+    let ancestor = root.rootReal;
+    const parentRelative = path.relative(root.rootReal, path.dirname(targetPath));
+    for (const segment of parentRelative.split(path.sep).filter(Boolean)) {
+        ancestor = path.join(ancestor, segment);
+        let guard;
+        try {
+            guard = await createAsyncDirectoryGuard(ancestor, { bigint: true });
+        }
+        catch (error) {
+            if (isNotFoundPathError(error)) {
+                assertCurrent();
+                assertNotAborted(options.signal);
+                if (options.force)
+                    return;
+            }
+            throw normalizeRemoveGuardError(error);
+        }
+        if (!isPathInside(guard.realPath, ancestor) || !isPathInside(ancestor, guard.realPath)) {
+            throw new FsSafeError("path-mismatch", "removal ancestor changed during operation");
+        }
+        guards.push(guard);
+    }
+    function assertCurrent() {
+        for (const guard of guards) {
+            try {
+                assertSyncDirectoryGuard(guard);
+            }
+            catch (error) {
+                // force tolerates a vanished leaf, never a lost traversal boundary.
+                throw new FsSafeError("path-mismatch", "removal ancestor changed during operation", { cause: error });
+            }
+        }
+    }
+    const inspect = (target, expected) => {
+        assertCurrent();
+        try {
+            return inspectFileIdentitySync(() => fsSync.lstatSync(target, { bigint: true }), expected);
+        }
+        catch (error) {
+            if (options.force && isNotFoundPathError(error))
+                return;
+            throw normalizeRemovePathError(error, details(target, expected ? "remove" : "inspect"));
+        }
+    };
+    async function visit(target, depth, entryCounted = false) {
+        assertNotAborted(options.signal);
+        if ((!entryCounted && examined >= maxEntries) || depth > maxDepth) {
+            throw new FsSafeError("too-large", "recursive removal budget exceeded", {
+                details: details(target, "inspect"),
+            });
+        }
+        if (!entryCounted)
+            examined += 1;
+        await assertMutationNotDenied(target, options.denyMutations, { protectAncestors: true });
+        assertNotAborted(options.signal);
+        const initial = inspect(target);
+        if (!initial)
+            return;
+        assertFinalSymlinkRejected(target, options.mutationSymlinks !== undefined, details(target, "inspect"));
+        if (initial.isDirectory()) {
+            let directoryGuard;
+            try {
+                directoryGuard = await createAsyncDirectoryGuard(target, { bigint: true });
+            }
+            catch (error) {
+                assertCurrent();
+                assertNotAborted(options.signal);
+                if (options.force && isNotFoundPathError(error))
+                    return;
+                throw normalizeRemovePathError(error, details(target, "inspect"));
+            }
+            if (!isPathInside(directoryGuard.realPath, target) || !isPathInside(target, directoryGuard.realPath) ||
+                !sameFileIdentityForCleanup(directoryGuard.stat, initial)) {
+                throw new FsSafeError("path-mismatch", "removal directory changed during operation");
+            }
+            guards.push(directoryGuard);
+            try {
+                assertCurrent();
+                assertNotAborted(options.signal);
+                const handle = await fs.opendir(target, { bufferSize: 1 }).catch(error => {
+                    if (options.force && isNotFoundPathError(error)) {
+                        assertNotAborted(options.signal);
+                        return undefined;
+                    }
+                    throw normalizeRemovePathError(error, details(target, "enumerate"));
+                });
+                if (handle) {
+                    let failed = false;
+                    let operationError;
+                    try {
+                        let names = options.order === "sorted" ? [] : undefined;
+                        if (names && maxEntries === Infinity) {
+                            assertCurrent();
+                            assertNotAborted(options.signal);
+                            const snapshot = await fs.readdir(target).catch(error => {
+                                if (options.force && isNotFoundPathError(error))
+                                    return undefined;
+                                throw normalizeRemovePathError(error, details(target, "enumerate"));
+                            });
+                            assertNotAborted(options.signal);
+                            if (snapshot) {
+                                assertCurrent();
+                                names = snapshot;
+                                examined += names.length;
+                            }
+                        }
+                        else {
+                            while (true) {
+                                assertCurrent();
+                                assertNotAborted(options.signal);
+                                const entry = await handle.read().catch(error => {
+                                    if (options.force && isNotFoundPathError(error))
+                                        return undefined;
+                                    throw normalizeRemovePathError(error, details(target, "enumerate"));
+                                });
+                                if (entry === undefined) {
+                                    assertNotAborted(options.signal);
+                                    if (names)
+                                        names.length = 0;
+                                    break;
+                                }
+                                assertCurrent();
+                                assertNotAborted(options.signal);
+                                if (!entry)
+                                    break;
+                                if (names) {
+                                    if (examined >= maxEntries) {
+                                        throw new FsSafeError("too-large", "recursive removal budget exceeded", {
+                                            details: details(path.join(target, entry.name), "enumerate"),
+                                        });
+                                    }
+                                    examined += 1;
+                                    names.push(entry.name);
+                                }
+                                else {
+                                    await visit(path.join(target, entry.name), depth + 1);
+                                }
+                            }
+                        }
+                        if (names) {
+                            for (const name of names.sort()) {
+                                await visit(path.join(target, name), depth + 1, true);
+                            }
+                        }
+                    }
+                    catch (error) {
+                        failed = true;
+                        operationError = error instanceof MutationAuthorityError ? error.rejection : error;
+                        throw error;
+                    }
+                    finally {
+                        try {
+                            // Close before rmdir, including on Windows and after revocation.
+                            await handle.close();
+                        }
+                        catch (error) {
+                            const closeError = normalizeRemovePathError(error, details(target, "enumerate"));
+                            if (failed)
+                                throw createSuppressedError(closeError, operationError, "recursive removal and close both failed");
+                            throw closeError;
+                        }
+                    }
+                }
+            }
+            finally {
+                guards.pop();
+            }
+        }
+        // A tolerated missing-directory observation still rechecks its target and ancestors.
+        await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("remove", target);
+        await assertMutationNotDenied(target, options.denyMutations, { protectAncestors: true });
+        assertNotAborted(options.signal);
+        if (!inspect(target, initial))
+            return;
+        assertFinalSymlinkRejected(target, options.mutationSymlinks !== undefined, details(target, "remove"));
+        assertNotAborted(options.signal);
+        options.assertBeforeMutation?.();
+        try {
+            await (initial.isDirectory() ? fs.rmdir(target) : fs.unlink(target));
+        }
+        catch (error) {
+            if (!(options.force && isNotFoundPathError(error))) {
+                throw normalizeRemovePathError(error, details(target, "remove"));
+            }
+        }
+        assertCurrent();
+        assertNotAborted(options.signal);
+    }
+    await assertRootIdentityCurrent(root);
+    await visit(targetPath, 0);
+}

package/dist/root-symlink-policy.d.ts

@@ -1,3 +1,4 @@
+import { type FsSafeErrorDetails } from "./errors.js";
 export type SymlinkPolicy = "reject" | "follow-within-root" | "follow-parents-within-root";
 export type MutationSymlinkPolicy = "reject" | "follow-parents-within-root";
 export declare function readSymlinkResolution(symlinks: SymlinkPolicy | undefined): {
@@ -9,5 +10,5 @@ export declare function mutationSymlinkResolution(symlinks: MutationSymlinkPolic
     rejectFinalSymlink: boolean;
     resolveCanonical: boolean;
 };
-export declare function assertFinalSymlinkRejected(targetPath: string, reject: boolean | undefined): void;
+export declare function assertFinalSymlinkRejected(targetPath: string, reject: boolean | undefined, details?: FsSafeErrorDetails): void;
 //# sourceMappingURL=root-symlink-policy.d.ts.map

package/dist/root-symlink-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-symlink-policy.d.ts","sourceRoot":"","sources":["../src/root-symlink-policy.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,oBAAoB,GAAG,4BAA4B,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,4BAA4B,CAAC;AAE5E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS;IAErE,cAAc;IACd,kBAAkB;EAErB;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,SAAS;IAKjF,cAAc;IACd,kBAAkB;IAClB,gBAAgB;EAEnB;AAID,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAShG"}
+{"version":3,"file":"root-symlink-policy.d.ts","sourceRoot":"","sources":["../src/root-symlink-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGnE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,oBAAoB,GAAG,4BAA4B,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,4BAA4B,CAAC;AAE5E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS;IAErE,cAAc;IACd,kBAAkB;EAErB;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,SAAS;IAKjF,cAAc;IACd,kBAAkB;IAClB,gBAAgB;EAEnB;AAID,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CASN"}

package/dist/root-symlink-policy.js

@@ -19,12 +19,12 @@ export function mutationSymlinkResolution(symlinks) {
 }
 // Call after parent fences and immediately before the mutation. This is a
 // final-component check, not an atomic conditional rename against another process.
-export function assertFinalSymlinkRejected(targetPath, reject) {
+export function assertFinalSymlinkRejected(targetPath, reject, details) {
     if (!reject)
         return;
     try {
         if (fs.lstatSync(targetPath).isSymbolicLink()) {
-            throw new FsSafeError("symlink", "final symlink not allowed");
+            throw new FsSafeError("symlink", "final symlink not allowed", { details });
         }
     }
     catch (error) {

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

@@ -1 +1 @@
-{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AASA,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsClB"}
+{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AAUA,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsClB"}

package/dist/root-write-mode.js

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
 import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 // The caller has already resolved and guarded this write target.
@@ -30,7 +31,7 @@ export async function inheritWriteTargetMode(params) {
         try {
             // A parent can change after guarded resolution. Do not inherit metadata
             // from an outside inode, even if the parent is restored before publication.
-            const realPath = fsSync.realpathSync.native(params.targetPath);
+            const realPath = realpathSync.native(params.targetPath);
             if (!isPathInside(params.rootWithSep, realPath))
                 throw outsideWorkspaceError();
             await inspectFileIdentity(async () => {

package/dist/root.d.ts

@@ -1,6 +1,7 @@
-export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type DenyMutationPolicy, type HardlinkPolicy, type MutationSymlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root-impl.js";
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type DenyMutationPolicy, type HardlinkPolicy, type MutationSymlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root-impl.js";
 export type { RootCopyPublicationReceipt } from "./copy-publication.js";
 export type { CopyCloneMode } from "./copy-policy.js";
+export type { RootEntriesOptions } from "./root-entries.js";
 export type { ContainmentGuarantee } from "./containment.js";
 export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";
 //# sourceMappingURL=root.d.ts.map

package/dist/root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,kCAAkC,EAClC,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACxE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,kCAAkC,EAClC,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACxE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

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

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

package/dist/secret-file.js

@@ -1,6 +1,7 @@
 import fs, {} from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
@@ -166,7 +167,7 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
         catch (error) {
             if (error.code !== "ENOENT")
                 throw error;
-            await fsp.mkdir(path.dirname(resolvedRoot), { recursive: true, mode });
+            await fsp.mkdir(recursiveMkdirPath(path.dirname(resolvedRoot)), { recursive: true, mode });
             createdRoot = await createPrivateDirectory(resolvedRoot, mode);
         }
         rootStat = await inspectPrivateDirectory(resolvedRoot, "root");

package/dist/secret-read-async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAOA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/secret-read-async.js

@@ -4,6 +4,7 @@ import { readFileHandleBounded } from "./bounded-read.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 export async function readSecretFile(filePath, label, options = {}) {
@@ -29,7 +30,7 @@ export async function readSecretFile(filePath, label, options = {}) {
     let handle;
     let raw;
     try {
-        const realPath = fsSync.realpathSync.native(resolvedPath);
+        const realPath = realpathSync.native(resolvedPath);
         assertNoUnsafeDeviceReadPath(realPath);
         handle = await fs.open(realPath, resolveReadOpenFlags());
         const openedHandle = handle;

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

@@ -1 +1 @@
-{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAa7C,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAI1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAmMF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAe/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAc/D,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAI1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAmNF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAuB/B"}

package/dist/secure-file.js

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

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

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

package/dist/secure-temp-dir.js

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

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

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