@openclaw/fs-safe 0.2.7 → 0.4.0

package/dist/root-impl.js

@@ -6,14 +6,18 @@ import { pipeline } from "node:stream/promises";
 import { createBoundedReadStream } from "./bounded-read-stream.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { syncDirectoryBestEffort } from "./fsync.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
+import { assertMutationNotDenied, mergeDenyMutationPolicies, } from "./deny-mutations.js";
+import { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 import { isPinnedPathHelperSpawnError, runPinnedPathHelper } from "./pinned-path.js";
 import { runPinnedCopyHelper, runPinnedWriteHelper } from "./pinned-write.js";
 import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
 import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
-import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
+import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
+import { readOpenedFileSafely } from "./read-opened-file.js";
 import { helperReaddir, helperStat, runPinnedHelper, } from "./pinned-helper.js";
 import { pathStatFromStats } from "./path-stat.js";
 import { resolveRootPath } from "./root-path.js";
@@ -23,6 +27,7 @@ import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { serializePathWrite } from "./write-queue.js";
+export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 function logWarn(message) {
     if (process.env.FS_SAFE_DEBUG_WARNINGS === "1") {
         console.warn(message);
@@ -46,20 +51,16 @@ const OPEN_APPEND_CREATE_FLAGS = fsConstants.O_RDWR |
     fsConstants.O_EXCL |
     (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 export const DEFAULT_ROOT_MAX_BYTES = 16 * 1024 * 1024;
-function closeHandleForDispose(handle) {
-    return handle.close().catch(() => undefined);
-}
 function openResult(params) {
     return {
         handle: params.handle,
         realPath: params.realPath,
         stat: params.stat,
-        [Symbol.asyncDispose]: async () => {
-            await closeHandleForDispose(params.handle);
-        },
+        [Symbol.asyncDispose]: () => params.handle.close().catch(() => undefined),
     };
 }
 async function openVerifiedLocalFile(filePath, options) {
+    assertNoUnsafeDeviceReadPath(filePath);
     const fsSafeTestHooks = getFsSafeTestHooks();
     // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
     // results that get sent to messaging channels). See openclaw/openclaw#31186.
@@ -216,6 +217,7 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
             append: writeMode === "append",
             truncateExisting: writeMode === "replace",
         });
@@ -227,18 +229,29 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
         });
     }
-    async remove(relativePath) {
+    async remove(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
-        await removePathInRoot(this.context, relativePath);
+        await removePathInRoot(this.context, {
+            relativePath,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+        });
     }
-    async mkdir(relativePath) {
+    async mkdir(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
-        await mkdirPathInRoot(this.context, { relativePath });
+        await mkdirPathInRoot(this.context, {
+            relativePath,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+        });
     }
-    async ensureRoot() {
-        await mkdirPathInRoot(this.context, { relativePath: "", allowRoot: true });
+    async ensureRoot(options = {}) {
+        await mkdirPathInRoot(this.context, {
+            relativePath: "",
+            allowRoot: true,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+        });
     }
     async write(relativePath, data, options = {}) {
         await writeFileInRoot(this.context, {
@@ -247,6 +260,7 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
         });
     }
     async create(relativePath, data, options = {}) {
@@ -256,6 +270,7 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
             overwrite: false,
         });
     }
@@ -278,6 +293,7 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
         });
     }
     async exists(relativePath) {
@@ -321,6 +337,12 @@ class RootHandle {
     async move(fromRelative, toRelative, options = {}) {
         assertValidRootRelativePath(fromRelative);
         assertValidRootRelativePath(toRelative);
+        const denyMutations = mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations);
+        await assertMoveMutationAllowed(this.context, {
+            fromRelative,
+            toRelative,
+            denyMutations,
+        });
         try {
             await runPinnedHelper("rename", this.rootReal, {
                 from: fromRelative,
@@ -332,6 +354,7 @@ class RootHandle {
             if (canFallbackFromPythonError(error)) {
                 await movePathFallback(this.context, {
                     fromRelative,
+                    denyMutations,
                     overwrite: options.overwrite ?? false,
                     toRelative,
                 });
@@ -413,20 +436,6 @@ export async function openLocalFileSafely(params) {
     assertNoNulPathInput(params.filePath, "file path contains a NUL byte");
     return await openVerifiedLocalFile(params.filePath);
 }
-async function readOpenedFileSafely(params) {
-    if (params.maxBytes !== undefined && params.opened.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${params.opened.stat.size})`);
-    }
-    const buffer = await params.opened.handle.readFile();
-    if (params.maxBytes !== undefined && buffer.byteLength > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${buffer.byteLength})`);
-    }
-    return {
-        buffer,
-        realPath: params.opened.realPath,
-        stat: params.opened.stat,
-    };
-}
 function emitWriteBoundaryWarning(reason) {
     logWarn(`security: fs-safe write boundary warning (${reason})`);
 }
@@ -467,82 +476,9 @@ async function verifyAtomicWriteResult(params) {
         await opened.handle.close().catch(() => { });
     }
 }
-export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
-    const handleStat = await handle.stat();
-    const fdCandidates = process.platform === "linux"
-        ? [`/proc/self/fd/${handle.fd}`, `/dev/fd/${handle.fd}`]
-        : process.platform === "win32"
-            ? []
-            : [`/dev/fd/${handle.fd}`];
-    for (const fdPath of fdCandidates) {
-        try {
-            const fdRealPath = await fs.realpath(fdPath);
-            const fdRealStat = await fs.stat(fdRealPath);
-            if (sameFileIdentity(handleStat, fdRealStat)) {
-                return fdRealPath;
-            }
-        }
-        catch {
-            // try next fd path
-        }
-    }
-    try {
-        const ioRealPath = await fs.realpath(ioPath);
-        const ioRealStat = await fs.stat(ioRealPath);
-        if (sameFileIdentity(handleStat, ioRealStat)) {
-            return ioRealPath;
-        }
-    }
-    catch (err) {
-        if (!isNotFoundPathError(err)) {
-            throw err;
-        }
-    }
-    const parentResolved = await resolveOpenedFileRealPathFromParent(handleStat, ioPath);
-    if (parentResolved) {
-        return parentResolved;
-    }
-    throw new FsSafeError("path-mismatch", "unable to resolve opened file path");
-}
-async function resolveOpenedFileRealPathFromParent(handleStat, ioPath) {
-    let parentReal;
-    try {
-        parentReal = await fs.realpath(path.dirname(ioPath));
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            return null;
-        }
-        throw err;
-    }
-    let entries;
-    try {
-        entries = await fs.readdir(parentReal);
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            return null;
-        }
-        throw err;
-    }
-    for (const entry of entries.toSorted()) {
-        const candidatePath = path.join(parentReal, entry);
-        try {
-            const candidateStat = await fs.lstat(candidatePath);
-            if (candidateStat.isFile() && sameFileIdentity(handleStat, candidateStat)) {
-                return await fs.realpath(candidatePath);
-            }
-        }
-        catch (err) {
-            if (!isNotFoundPathError(err)) {
-                throw err;
-            }
-        }
-    }
-    return null;
-}
 async function openWritableFileInRoot(root, params) {
     const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath);
+    await assertMutationNotDenied(resolved, params.denyMutations);
     try {
         await assertNoPathAliasEscape({
             absolutePath: resolved,
@@ -649,9 +585,7 @@ async function openWritableFileInRoot(root, params) {
             createdForWrite,
             realPath,
             stat,
-            [Symbol.asyncDispose]: async () => {
-                await closeHandleForDispose(handle);
-            },
+            [Symbol.asyncDispose]: () => handle.close().catch(() => undefined),
         };
     }
     catch (err) {
@@ -669,6 +603,7 @@ async function appendFileInRoot(root, params) {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
         mode: params.mode,
+        denyMutations: params.denyMutations,
         truncateExisting: false,
         append: true,
     });
@@ -687,17 +622,22 @@ async function appendFileInRoot(root, params) {
         }
         if (typeof params.data === "string") {
             await target.handle.appendFile(`${prefix}${params.data}`, params.encoding ?? "utf8");
-            return;
         }
-        const payload = prefix.length > 0 ? Buffer.concat([Buffer.from(prefix, "utf8"), params.data]) : params.data;
-        await target.handle.appendFile(payload);
+        else {
+            const payload = prefix.length > 0 ? Buffer.concat([Buffer.from(prefix, "utf8"), params.data]) : params.data;
+            await target.handle.appendFile(payload);
+        }
+        await target.handle.sync();
+        if (target.createdForWrite) {
+            await syncDirectoryBestEffort(path.dirname(target.realPath));
+        }
     }
     finally {
         await target.handle.close().catch(() => { });
     }
 }
-async function removePathInRoot(root, relativePath) {
-    const resolved = await resolvePinnedRemovePathInRoot(root, relativePath);
+async function removePathInRoot(root, params) {
+    const resolved = await resolvePinnedRemovePathInRoot(root, params.relativePath, params.denyMutations);
     if (process.platform === "win32") {
         await removePathFallback(resolved);
         return;
@@ -745,44 +685,47 @@ async function writeFileInRoot(root, params) {
         });
         return;
     }
-    const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode);
+    const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
     await serializePathWrite(pinned.targetPath, async () => {
-        let identity;
-        try {
-            identity = await runPinnedWriteHelper({
-                rootPath: pinned.rootReal,
-                relativeParentPath: pinned.relativeParentPath,
-                basename: pinned.basename,
-                mkdir: params.mkdir !== false,
-                mode: params.mode ?? pinned.mode,
-                overwrite: params.overwrite,
-                input: {
-                    kind: "buffer",
-                    data: params.data,
-                    encoding: params.encoding,
-                },
-            });
-        }
-        catch (error) {
-            if (params.overwrite === false && isAlreadyExistsError(error)) {
-                throw new FsSafeError("already-exists", "file already exists", {
-                    cause: error instanceof Error ? error : undefined,
-                });
-            }
-            throw normalizePinnedWriteError(error);
-        }
-        try {
-            await verifyAtomicWriteResult({
-                root,
-                targetPath: pinned.targetPath,
-                expectedIdentity: identity,
+        await commitPinnedWriteInRoot(root, pinned, params);
+    });
+}
+async function commitPinnedWriteInRoot(root, pinned, params) {
+    let identity;
+    try {
+        identity = await runPinnedWriteHelper({
+            rootPath: pinned.rootReal,
+            relativeParentPath: pinned.relativeParentPath,
+            basename: pinned.basename,
+            mkdir: params.mkdir !== false,
+            mode: params.mode ?? pinned.mode,
+            overwrite: params.overwrite,
+            input: {
+                kind: "buffer",
+                data: params.data,
+                encoding: params.encoding,
+            },
+        });
+    }
+    catch (error) {
+        if (params.overwrite === false && isAlreadyExistsError(error)) {
+            throw new FsSafeError("already-exists", "file already exists", {
+                cause: error instanceof Error ? error : undefined,
             });
         }
-        catch (err) {
-            emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
-            throw err;
-        }
-    });
+        throw normalizePinnedWriteError(error);
+    }
+    try {
+        await verifyAtomicWriteResult({
+            root,
+            targetPath: pinned.targetPath,
+            expectedIdentity: identity,
+        });
+    }
+    catch (err) {
+        emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
+        throw err;
+    }
 }
 async function copyFileInRoot(root, params) {
     assertValidRootRelativePath(params.relativePath);
@@ -801,7 +744,7 @@ async function copyFileInRoot(root, params) {
             });
             return;
         }
-        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode);
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
         await serializePathWrite(pinned.targetPath, async () => {
             let identity;
             try {
@@ -845,8 +788,9 @@ async function copyFileInRoot(root, params) {
         await source.handle.close().catch(() => { });
     }
 }
-async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode) {
+async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations) {
     const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, relativePath);
+    await assertMutationNotDenied(resolved, denyMutations);
     try {
         await assertNoPathAliasEscape({
             absolutePath: resolved,
@@ -903,12 +847,16 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode)
 async function resolvePinnedPathInRoot(root, params) {
     return await resolvePinnedOperationPathInRoot(root, {
         allowRoot: params.allowRoot,
+        denyMutations: params.denyMutations,
+        protectDenyMutationAncestors: false,
         relativePath: params.relativePath,
         policy: PATH_ALIAS_POLICIES.strict,
     });
 }
-async function resolvePinnedRemovePathInRoot(root, relativePath) {
+async function resolvePinnedRemovePathInRoot(root, relativePath, denyMutations) {
     return await resolvePinnedOperationPathInRoot(root, {
+        denyMutations,
+        protectDenyMutationAncestors: true,
         relativePath,
         policy: PATH_ALIAS_POLICIES.unlinkTarget,
     });
@@ -920,6 +868,7 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     });
     const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
     if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
+        await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations);
         return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
     }
     const firstSegment = relativeResolved.split(path.sep)[0];
@@ -933,6 +882,9 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     if (!isPathInside(resolved.rootWithSep, resolved.canonicalPath)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }
+    await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations, {
+        protectAncestors: params.protectDenyMutationAncestors,
+    });
     return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
 async function resolvePinnedRootPathInRoot(root, params) {
@@ -1010,13 +962,21 @@ async function listPathFallback(root, relativePath, withFileTypes) {
         throw error;
     }
 }
+async function assertMoveMutationAllowed(root, params) {
+    const source = await resolvePathInRoot(root, params.fromRelative);
+    await assertMutationNotDenied(source.resolved, params.denyMutations, { protectAncestors: true });
+    const target = await resolvePathInRoot(root, params.toRelative);
+    await assertMutationNotDenied(target.resolved, params.denyMutations, { protectAncestors: true });
+}
 async function movePathFallback(root, params) {
     const source = await resolvePathInRoot(root, params.fromRelative);
+    await assertMutationNotDenied(source.resolved, params.denyMutations, { protectAncestors: true });
     await resolvePinnedRootPathInRoot(root, {
         relativePath: params.fromRelative,
         policy: PATH_ALIAS_POLICIES.strict,
     });
     const target = await resolvePathInRoot(root, params.toRelative);
+    await assertMutationNotDenied(target.resolved, params.denyMutations, { protectAncestors: true });
     await resolvePinnedRootPathInRoot(root, {
         relativePath: params.toRelative,
         policy: PATH_ALIAS_POLICIES.unlinkTarget,
@@ -1100,6 +1060,7 @@ async function writeFileFallback(root, params) {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
         mode: params.mode,
+        denyMutations: params.denyMutations,
         truncateExisting: false,
     });
     const destinationPath = target.realPath;
@@ -1145,6 +1106,7 @@ async function writeFileFallback(root, params) {
 }
 async function writeMissingFileFallback(root, params) {
     const { rootReal, resolved } = await resolvePathInRoot(root, params.relativePath);
+    await assertMutationNotDenied(resolved, params.denyMutations);
     try {
         await assertNoPathAliasEscape({
             absolutePath: resolved,
@@ -1218,6 +1180,7 @@ async function copyFileFallback(root, params, source) {
             relativePath: params.relativePath,
             mkdir: params.mkdir,
             mode: params.mode,
+            denyMutations: params.denyMutations,
             truncateExisting: false,
         });
         const destinationPath = target.realPath;

package/dist/root.d.ts

@@ -1,2 +1,2 @@
-export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, 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-impl.js";
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type DenyMutationPolicy, type HardlinkPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, 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";
 //# 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,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,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,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,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"}

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,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAUrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAsKF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAa/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAWrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAuKF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAa/B"}

package/dist/secure-file.js

@@ -1,6 +1,7 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
@@ -17,6 +18,7 @@ function label(options) {
     return options.label ?? "Secure file";
 }
 async function openSecureHandle(options) {
+    assertNoUnsafeDeviceReadPath(options.filePath);
     if (isWindowsNetworkPath(options.filePath, "win32") && !options.trust?.allowNetworkPath) {
         throw new FsSafeError("invalid-path", `${label(options)} must be a local absolute path.`);
     }

package/dist/walk.d.ts

@@ -16,11 +16,22 @@ export type WalkDirectoryOptions = {
     include?: (entry: WalkDirectoryEntry) => boolean;
     descend?: (entry: WalkDirectoryEntry) => boolean;
 };
+export type WalkDirectoryFailure = {
+    path: string;
+    relativePath: string;
+    depth: number;
+    error: unknown;
+};
 export type WalkDirectoryResult = {
     entries: WalkDirectoryEntry[];
     scannedEntryCount: number;
     truncated: boolean;
+    failedDirs?: WalkDirectoryFailure[];
+};
+type WalkDirectoryResultWithFailures = WalkDirectoryResult & {
+    failedDirs: WalkDirectoryFailure[];
 };
-export declare function walkDirectorySync(rootDir: string, options?: WalkDirectoryOptions): WalkDirectoryResult;
-export declare function walkDirectory(rootDir: string, options?: WalkDirectoryOptions): Promise<WalkDirectoryResult>;
+export declare function walkDirectorySync(rootDir: string, options?: WalkDirectoryOptions): WalkDirectoryResultWithFailures;
+export declare function walkDirectory(rootDir: string, options?: WalkDirectoryOptions): Promise<WalkDirectoryResultWithFailures>;
+export {};
 //# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AA8DF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAiDrB;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAiD9B"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA8EF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAwDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAwD1C"}

package/dist/walk.js

@@ -25,6 +25,15 @@ function buildEntry(params) {
         dirent: params.dirent,
     };
 }
+function recordFailedDir(result, root, dir, depth, error) {
+    const relativePath = path.relative(root, dir);
+    result.failedDirs.push({
+        path: dir,
+        relativePath,
+        depth: relativePath === "" ? 0 : depth - 1,
+        error,
+    });
+}
 function resolveSyncKind(fullPath, dirent, symlinks) {
     const kind = kindForDirent(dirent);
     if (kind !== "symlink")
@@ -68,7 +77,12 @@ async function resolveAsyncKind(fullPath, dirent, symlinks) {
 export function walkDirectorySync(rootDir, options = {}) {
     const root = path.resolve(rootDir);
     const symlinks = options.symlinks ?? "skip";
-    const result = { entries: [], scannedEntryCount: 0, truncated: false };
+    const result = {
+        entries: [],
+        scannedEntryCount: 0,
+        truncated: false,
+        failedDirs: [],
+    };
     const visitedDirs = new Set();
     function visit(dir, depth) {
         if (options.maxDepth !== undefined && depth > options.maxDepth)
@@ -77,7 +91,8 @@ export function walkDirectorySync(rootDir, options = {}) {
         try {
             realDir = fsSync.realpathSync(dir);
         }
-        catch {
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
             return;
         }
         if (visitedDirs.has(realDir))
@@ -87,7 +102,8 @@ export function walkDirectorySync(rootDir, options = {}) {
         try {
             entries = fsSync.readdirSync(dir, { withFileTypes: true });
         }
-        catch {
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
             return;
         }
         for (const dirent of entries) {
@@ -119,7 +135,12 @@ export function walkDirectorySync(rootDir, options = {}) {
 export async function walkDirectory(rootDir, options = {}) {
     const root = path.resolve(rootDir);
     const symlinks = options.symlinks ?? "skip";
-    const result = { entries: [], scannedEntryCount: 0, truncated: false };
+    const result = {
+        entries: [],
+        scannedEntryCount: 0,
+        truncated: false,
+        failedDirs: [],
+    };
     const visitedDirs = new Set();
     async function visit(dir, depth) {
         if (options.maxDepth !== undefined && depth > options.maxDepth)
@@ -128,7 +149,8 @@ export async function walkDirectory(rootDir, options = {}) {
         try {
             realDir = await fs.realpath(dir);
         }
-        catch {
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
             return;
         }
         if (visitedDirs.has(realDir))
@@ -138,7 +160,8 @@ export async function walkDirectory(rootDir, options = {}) {
         try {
             entries = await fs.readdir(dir, { withFileTypes: true });
         }
-        catch {
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
             return;
         }
         for (const dirent of entries) {

package/docs/contributing.md

@@ -10,7 +10,7 @@ cd fs-safe
 pnpm install
 ```
 
-Node 20.11 or newer. The dev toolchain uses pnpm; `npm install` works too but pnpm is what the lockfile is keyed against.
+Node 22 or newer. The dev toolchain uses pnpm; `npm install` works too but pnpm is what the lockfile is keyed against.
 
 ## Build
 

package/docs/errors.md

@@ -30,6 +30,8 @@ class FsSafeError extends Error {
 ```ts
 type FsSafeErrorCode =
   | "already-exists"
+  | "denied-path"
+  | "device-path"
   | "hardlink"
   | "helper-failed"
   | "helper-unavailable"
@@ -55,6 +57,8 @@ type FsSafeErrorCode =
 | Code | When it fires | Common causes |
 |---|---|---|
 | `already-exists` | `create()`, `createJson()`, `move({ overwrite: false })`. | Target file or directory already at the destination. |
+| `denied-path` | A root mutation matched `denyMutations.paths` or `denyMutations.prefixes`. | Caller configured application-sensitive paths that must not be written, removed, moved, or created. |
+| `device-path` | A read/open target is a known unsafe device or process-fd path. | `/dev/zero`, `/dev/random`, `/dev/stdin`, `/dev/fd/*`, `/proc/*/fd/*`, or a Windows reserved device name. |
 | `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
 | `helper-failed` | Internal POSIX helper failed after startup. | Inspect `cause`; retrying may be unsafe if the operation may have partially completed. |
 | `helper-unavailable` | Persistent Python helper was disabled or could not be spawned. | `FS_SAFE_PYTHON_MODE=off`, Python missing in PATH, restricted sandbox. `auto` falls back where possible; `require` fails closed. |
@@ -93,6 +97,7 @@ try {
     case "not-found":
       return reply(404, "missing");
     case "symlink":
+    case "device-path":
     case "hardlink":
     case "path-mismatch":
     case "path-alias":