@openclaw/fs-safe 0.2.6 → 0.3.0

package/dist/root-impl.js

@@ -9,11 +9,14 @@ import { FsSafeError } from "./errors.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 { 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 +26,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);
@@ -216,6 +220,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 +232,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 +263,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 +273,7 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
             overwrite: false,
         });
     }
@@ -278,6 +296,7 @@ class RootHandle {
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
         });
     }
     async exists(relativePath) {
@@ -321,6 +340,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 +357,7 @@ class RootHandle {
             if (canFallbackFromPythonError(error)) {
                 await movePathFallback(this.context, {
                     fromRelative,
+                    denyMutations,
                     overwrite: options.overwrite ?? false,
                     toRelative,
                 });
@@ -413,20 +439,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 +479,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,
@@ -669,6 +608,7 @@ async function appendFileInRoot(root, params) {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
         mode: params.mode,
+        denyMutations: params.denyMutations,
         truncateExisting: false,
         append: true,
     });
@@ -696,8 +636,8 @@ async function appendFileInRoot(root, params) {
         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,7 +685,7 @@ 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 {
@@ -801,7 +741,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 +785,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 +844,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 +865,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 +879,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 +959,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 +1057,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 +1103,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 +1177,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-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

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside, isPathRelativeEscape } from "./path.js";
 import { root as openRoot } from "./root.js";
 function invalidPath(scopeLabel) {
     return {
@@ -9,6 +9,10 @@ function invalidPath(scopeLabel) {
         error: `Invalid path: must stay within ${scopeLabel}`,
     };
 }
+function pathStaysWithinRoot(rootDir, candidatePath) {
+    const relative = path.relative(rootDir, candidatePath);
+    return Boolean(relative) && !isPathRelativeEscape(relative);
+}
 async function resolveRealPathIfExists(targetPath) {
     try {
         return await fs.realpath(targetPath);
@@ -58,11 +62,14 @@ export function resolvePathWithinRoot(params) {
         if (!params.defaultFileName) {
             return { ok: false, error: "path is required" };
         }
-        return { ok: true, path: path.join(root, params.defaultFileName) };
+        const defaultPath = path.resolve(root, params.defaultFileName);
+        if (!pathStaysWithinRoot(root, defaultPath)) {
+            return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
+        }
+        return { ok: true, path: defaultPath };
     }
     const resolved = path.resolve(root, raw);
-    const rel = path.relative(root, resolved);
-    if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    if (!pathStaysWithinRoot(root, resolved)) {
         return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
     }
     return { ok: true, path: resolved };
@@ -118,7 +125,7 @@ async function resolveNearestExistingPath(targetPath) {
 }
 async function assertNoSymlinkSegments(params) {
     const relative = path.relative(params.rootDir, params.targetPath);
-    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         throw new Error(`Invalid path: must stay within ${params.scopeLabel}`);
     }
     let current = params.rootDir;
@@ -195,6 +202,10 @@ export async function ensureDirectoryWithinRoot(params) {
                     }
                 }
             }
+            const currentReal = await fs.realpath(current);
+            if (!isPathInside(rootReal, currentReal)) {
+                return invalidPath(params.scopeLabel);
+            }
         }
         const targetReal = await fs.realpath(targetPath);
         if (!isPathInside(rootReal, targetReal)) {

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/secret-file.d.ts

@@ -4,6 +4,7 @@ export declare const PRIVATE_SECRET_FILE_MODE = 384;
 export type SecretFileReadOptions = {
     maxBytes?: number;
     rejectSymlink?: boolean;
+    rejectHardlinks?: boolean;
 };
 export declare function readSecretFileSync(filePath: string, label: string, options?: SecretFileReadOptions): string;
 export declare function tryReadSecretFileSync(filePath: string | undefined, label: string, options?: SecretFileReadOptions): string | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAqHF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoID,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,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;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+ChB"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAkIF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAcpB;AAoID,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,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;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+ChB"}

package/dist/secret-file.js

@@ -13,6 +13,10 @@ export const PRIVATE_SECRET_FILE_MODE = 0o600;
 function normalizeSecretReadError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
+function secretPathErrorCode(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
 function resolveUserPath(input) {
     return resolveHomeRelativePath(input);
 }
@@ -31,7 +35,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         const normalized = normalizeSecretReadError(error);
         return {
             ok: false,
-            code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+            code: secretPathErrorCode(error),
             error: normalized,
             message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };
@@ -45,7 +49,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
                 const normalized = normalizeSecretReadError(error);
                 return {
                     ok: false,
-                    code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+                    code: secretPathErrorCode(error),
                     error: normalized,
                     message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
                 };
@@ -66,6 +70,13 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
             message: `${label} file at ${resolvedPath} must be a regular file.`,
         };
     }
+    if (options.rejectHardlinks !== false && previewStat.nlink > 1) {
+        return {
+            ok: false,
+            code: "hardlink",
+            message: `${label} file at ${resolvedPath} must not be hardlinked.`,
+        };
+    }
     if (previewStat.size > maxBytes) {
         return {
             ok: false,
@@ -76,6 +87,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
     const opened = openPinnedFileSync({
         filePath: resolvedPath,
         rejectPathSymlink: options.rejectSymlink,
+        rejectHardlinks: options.rejectHardlinks !== false,
         maxBytes,
     });
     if (!opened.ok) {
@@ -126,7 +138,15 @@ export function tryReadSecretFileSync(filePath, label, options = {}) {
         return undefined;
     }
     const result = readSecretFileOutcomeSync(filePath, label, options);
-    return result.ok ? result.secret : undefined;
+    if (result.ok) {
+        return result.secret;
+    }
+    if (result.code === "not-found") {
+        return undefined;
+    }
+    throw new FsSafeError(result.code, result.message, {
+        cause: result.error,
+    });
 }
 function isRelativeEscape(relativePath) {
     return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);

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

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

package/dist/sidecar-lock.js

@@ -34,8 +34,11 @@ async function readLockSnapshot(lockPath) {
             return { raw, payload: null, stat };
         }
     }
-    catch {
-        return null;
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
     }
 }
 function snapshotMatches(current, observed) {
@@ -86,7 +89,10 @@ async function removeStaleLockIfAllowed(params) {
     try {
         await fs.rm(params.lockPath, { force: true });
     }
-    catch {
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return "changed";
+        }
         return "not-approved";
     }
     return "removed";

package/dist/symlink-parents.js

@@ -1,12 +1,12 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isNotFoundPathError } from "./path.js";
+import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 function resolvePathWalk(params) {
     const root = path.resolve(params.rootDir);
     const target = path.resolve(params.targetPath);
     const relative = path.relative(root, target);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {
             return null;
         }

package/docs/errors.md

@@ -30,6 +30,7 @@ class FsSafeError extends Error {
 ```ts
 type FsSafeErrorCode =
   | "already-exists"
+  | "denied-path"
   | "hardlink"
   | "helper-failed"
   | "helper-unavailable"
@@ -55,6 +56,7 @@ 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. |
 | `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. |

package/docs/python-helper.md

@@ -62,12 +62,12 @@ Node-only mode still keeps the important application-level guardrails:
 - root-relative path validation;
 - canonical root checks;
 - no-follow opens where Node/platform support exists;
-- file identity checks around reads and writes where a safe Node fallback exists;
-- atomic sibling-temp replacement on fallback platforms;
+- file identity checks around reads and writes;
+- atomic sibling-temp replacement;
 - hardlink/symlink policy checks where the API requests them;
 - byte limits and structured `FsSafeError` failures.
 
-What gets weaker is the POSIX defense against another same-UID process swapping a parent directory between validation and mutation. Write paths that need fd-relative parent commits now fail closed when the helper is disabled or unavailable; other operations such as `root().move()`, `root().remove()`, and `root().mkdir()` may still rely on Node path operations plus pre/post checks instead of parent-fd syscalls.
+What gets weaker is the POSIX defense against another same-UID process swapping a parent directory between validation and mutation. Without fd-relative mutation, `root().move()`, `root().remove()`, `root().mkdir()`, and some write paths rely on Node path operations plus pre/post checks instead of parent-fd syscalls.
 
 That is usually acceptable when the root directory is only writable by the trusted application user. It is not the right posture if untrusted local processes can race writes in the same tree and you are relying on `fs-safe` as part of the security boundary.