@openclaw/fs-safe 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0 - 2026-05-21
+
+### Features
+
+- Add opt-in `denyMutations` policies with exact `paths` and subtree `prefixes` so callers can protect application-sensitive files from root write, copy, move, remove, mkdir, and writable-open operations. (#20; thanks @amknight)
+
+### Security and Correctness
+
+- Retry async JSON reads (`readJson`, `readJsonIfExists`, `tryReadJson`) up to five attempts with 50ms exponential backoff when the file is rotated mid-read by an atomic rename, and tag the underlying race as `FsSafeError("path-mismatch")` so callers can distinguish transient swaps from corruption. (#19; thanks @yetval)
+
 ## 0.2.7 - 2026-05-20
 
 ### Security and Correctness

package/README.md

@@ -155,7 +155,18 @@ await using opened = await fs.openWritable("logs/current.log", { writeMode: "app
 }
 ```
 
-`nonBlockingRead` is the only I/O scheduling knob in `RootDefaults`; it applies to read/open operations because it changes how file descriptors are opened. Filesystem safety policy remains explicit through `hardlinks` and `symlinks`.
+`nonBlockingRead` is the only I/O scheduling knob in `RootDefaults`; it applies to read/open operations because it changes how file descriptors are opened. Filesystem safety policy remains explicit through `hardlinks`, `symlinks`, and `denyMutations`.
+
+```ts
+const locked = await root("/srv/workspace", {
+  denyMutations: {
+    paths: ["/srv/workspace/.env"],
+    prefixes: ["/srv/workspace/.ssh"],
+  },
+});
+
+await locked.write(".env", "token"); // FsSafeError code "denied-path"
+```
 
 `stat()`, `exists()`, and `list()` are boundary-checked, but they cannot pin a later operation to the same filesystem object. Use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` for operations that must be race-resistant at the point of use.
 

package/dist/deny-mutations.d.ts

@@ -0,0 +1,11 @@
+export type DenyMutationPolicy = {
+    paths?: readonly string[];
+    prefixes?: readonly string[];
+};
+type DenyMutationCheckOptions = {
+    protectAncestors?: boolean;
+};
+export declare function assertMutationNotDenied(filePath: string, policy: DenyMutationPolicy | undefined, options?: DenyMutationCheckOptions): Promise<void>;
+export declare function mergeDenyMutationPolicies(defaultPolicy: DenyMutationPolicy | undefined, callPolicy: DenyMutationPolicy | undefined): DenyMutationPolicy | undefined;
+export {};
+//# sourceMappingURL=deny-mutations.d.ts.map

package/dist/deny-mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deny-mutations.d.ts","sourceRoot":"","sources":["../src/deny-mutations.ts"],"names":[],"mappings":"AAmDA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAqBF,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,kBAAkB,GAAG,SAAS,EAC7C,UAAU,EAAE,kBAAkB,GAAG,SAAS,GACzC,kBAAkB,GAAG,SAAS,CAWhC"}

package/dist/deny-mutations.js

@@ -0,0 +1,102 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+async function pathExists(filePath) {
+    try {
+        await fs.lstat(filePath);
+        return true;
+    }
+    catch (err) {
+        if (!isNotFoundPathError(err)) {
+            throw err;
+        }
+        return false;
+    }
+}
+async function resolvePathViaExistingAncestor(targetPath) {
+    const normalized = path.resolve(targetPath);
+    let cursor = normalized;
+    const missingSuffix = [];
+    while (path.dirname(cursor) !== cursor && !(await pathExists(cursor))) {
+        missingSuffix.unshift(path.basename(cursor));
+        cursor = path.dirname(cursor);
+    }
+    if (!(await pathExists(cursor))) {
+        return normalized;
+    }
+    try {
+        const resolvedAncestor = path.resolve(await fs.realpath(cursor));
+        return missingSuffix.length === 0
+            ? resolvedAncestor
+            : path.resolve(resolvedAncestor, ...missingSuffix);
+    }
+    catch {
+        return normalized;
+    }
+}
+async function comparablePaths(rawPath) {
+    assertNoNulPathInput(rawPath, "path contains a NUL byte");
+    const resolved = path.resolve(rawPath);
+    return new Set([resolved, await resolvePathViaExistingAncestor(resolved)]);
+}
+function isSamePath(left, right) {
+    return isPathInside(left, right) && isPathInside(right, left);
+}
+function hasPolicyEntries(policy) {
+    return Boolean(policy?.paths?.length || policy?.prefixes?.length);
+}
+function policyPathEntries(entries) {
+    const paths = [];
+    for (const entry of entries ?? []) {
+        if (entry.length === 0) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty");
+        }
+        assertNoNulPathInput(entry, "deny mutation path contains a NUL byte");
+        if (!path.isAbsolute(entry)) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be absolute");
+        }
+        paths.push(entry);
+    }
+    return paths;
+}
+export async function assertMutationNotDenied(filePath, policy, options = {}) {
+    if (!hasPolicyEntries(policy)) {
+        return;
+    }
+    const targetPaths = await comparablePaths(filePath);
+    for (const deniedPath of policyPathEntries(policy.paths)) {
+        const deniedPaths = await comparablePaths(deniedPath);
+        for (const target of targetPaths) {
+            for (const denied of deniedPaths) {
+                if (isSamePath(denied, target) ||
+                    (options.protectAncestors === true && isPathInside(target, denied))) {
+                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+                }
+            }
+        }
+    }
+    for (const deniedPrefix of policyPathEntries(policy.prefixes)) {
+        const deniedPaths = await comparablePaths(deniedPrefix);
+        for (const target of targetPaths) {
+            for (const denied of deniedPaths) {
+                if (isPathInside(denied, target) ||
+                    (options.protectAncestors === true && isPathInside(target, denied))) {
+                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+                }
+            }
+        }
+    }
+}
+export function mergeDenyMutationPolicies(defaultPolicy, callPolicy) {
+    if (!defaultPolicy) {
+        return callPolicy;
+    }
+    if (!callPolicy) {
+        return defaultPolicy;
+    }
+    return {
+        paths: [...(defaultPolicy.paths ?? []), ...(callPolicy.paths ?? [])],
+        prefixes: [...(defaultPolicy.prefixes ?? []), ...(callPolicy.prefixes ?? [])],
+    };
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type FsSafeErrorCode = "already-exists" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+export type FsSafeErrorCode = "already-exists" | "denied-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
 export type FsSafeErrorCategory = "policy" | "operational";
 export declare function categorizeFsSafeError(code: FsSafeErrorCode): FsSafeErrorCategory;
 export declare class FsSafeError extends Error {

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,UAAU,GACV,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,WAAW,GACX,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,uBAAuB,GACvB,SAAS,GACT,SAAS,GACT,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAU3D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAEhF;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;gBAE3B,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMtF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,aAAa,GACb,UAAU,GACV,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,WAAW,GACX,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,uBAAuB,GACvB,SAAS,GACT,SAAS,GACT,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAU3D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAEhF;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;gBAE3B,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMtF"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, } from "./errors.js";
-export { DEFAULT_ROOT_MAX_BYTES, root, type HardlinkPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
+export { DEFAULT_ROOT_MAX_BYTES, 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.js";
 export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
 export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";

package/dist/index.d.ts.map

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

package/dist/json.d.ts.map

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

package/dist/json.js

@@ -1,10 +1,49 @@
 import { randomUUID } from "node:crypto";
 import fsSync from "node:fs";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
-import { readRegularFile, readRegularFileSync } from "./regular-file.js";
+import { readRegularFile, readRegularFileSync, statRegularFile } from "./regular-file.js";
 import { openRootFileSync } from "./root-file.js";
 import { writeTextAtomic } from "./text-atomic.js";
+const READ_RETRY_MAX_ATTEMPTS = 5;
+const READ_RETRY_BASE_DELAY_MS = 50;
+function isRetryableReadError(err, options) {
+    if (err instanceof FsSafeError && err.code === "path-mismatch") {
+        return true;
+    }
+    if (options.retryOpenRaceErrors !== true) {
+        return false;
+    }
+    const code = getErrorCode(err);
+    return code === "ENOENT" || code === "EPERM";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function readRegularFileWithRetry(filePath, options = {}) {
+    let lastErr;
+    for (let attempt = 0; attempt < READ_RETRY_MAX_ATTEMPTS; attempt++) {
+        try {
+            return (await readRegularFile({ filePath })).buffer;
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryableReadError(err, options) || attempt === READ_RETRY_MAX_ATTEMPTS - 1) {
+                throw err;
+            }
+            await sleep(READ_RETRY_BASE_DELAY_MS * Math.pow(2, attempt));
+        }
+    }
+    throw lastErr;
+}
+async function readRegularFileIfExistsWithRetry(filePath) {
+    const initial = await statRegularFile(filePath);
+    if (initial.missing) {
+        return null;
+    }
+    return await readRegularFileWithRetry(filePath, { retryOpenRaceErrors: true });
+}
 const JSON_FILE_MODE = 0o600;
 const JSON_DIR_MODE = 0o700;
 const SUPPORTS_SYNC_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants;
@@ -200,7 +239,11 @@ export function readRootJsonObjectSync(options) {
 }
 export async function tryReadJson(filePath) {
     try {
-        const raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
+        const buffer = await readRegularFileIfExistsWithRetry(filePath);
+        if (buffer === null) {
+            return null;
+        }
+        const raw = buffer.toString("utf8");
         return JSON.parse(raw);
     }
     catch {
@@ -210,7 +253,7 @@ export async function tryReadJson(filePath) {
 export async function readJson(filePath) {
     let raw;
     try {
-        raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
+        raw = (await readRegularFileWithRetry(filePath, { retryOpenRaceErrors: true })).toString("utf8");
     }
     catch (err) {
         throw new JsonFileReadError(filePath, "read", err);
@@ -225,7 +268,11 @@ export async function readJson(filePath) {
 export async function readJsonIfExists(filePath) {
     let raw;
     try {
-        raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
+        const buffer = await readRegularFileIfExistsWithRetry(filePath);
+        if (buffer === null) {
+            return null;
+        }
+        raw = buffer.toString("utf8");
     }
     catch (err) {
         if (getErrorCode(err) === "ENOENT") {

package/dist/opened-realpath.d.ts

@@ -0,0 +1,3 @@
+import type { FileHandle } from "node:fs/promises";
+export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
+//# sourceMappingURL=opened-realpath.d.ts.map

package/dist/opened-realpath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opened-realpath.d.ts","sourceRoot":"","sources":["../src/opened-realpath.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAoCjB"}

package/dist/opened-realpath.js

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+export async function 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;
+}

package/dist/read-opened-file.d.ts

@@ -0,0 +1,18 @@
+import type { Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export type ReadResult = {
+    buffer: Buffer;
+    realPath: string;
+    stat: Stats;
+};
+type OpenedFile = {
+    handle: FileHandle;
+    realPath: string;
+    stat: Stats;
+};
+export declare function readOpenedFileSafely(params: {
+    opened: OpenedFile;
+    maxBytes?: number;
+}): Promise<ReadResult>;
+export {};
+//# sourceMappingURL=read-opened-file.d.ts.map

package/dist/read-opened-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-opened-file.d.ts","sourceRoot":"","sources":["../src/read-opened-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBtB"}

package/dist/read-opened-file.js

@@ -0,0 +1,15 @@
+import { FsSafeError } from "./errors.js";
+export 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,
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAQ7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AA2DD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAgC3C;AA6CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAoBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}
+{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAS7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AA2DD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAiD3C;AA6CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAoBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}

package/dist/regular-file.js

@@ -1,6 +1,7 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertNoSymlinkParents, assertNoSymlinkParentsSync } from "./symlink-parents.js";
@@ -95,12 +96,31 @@ export async function readRegularFile(params) {
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
         throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
     }
-    const handle = await fs.open(params.filePath, resolveRegularFileReadFlags());
+    let handle;
+    try {
+        handle = await fs.open(params.filePath, resolveRegularFileReadFlags());
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+        }
+        throw err;
+    }
     try {
         const stat = await handle.stat();
+        let pathStat;
+        try {
+            pathStat = await fs.lstat(params.filePath);
+        }
+        catch (err) {
+            if (isNotFoundPathError(err)) {
+                throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+            }
+            throw err;
+        }
         verifyStableReadTarget({
             filePath: params.filePath,
-            pathStat: await fs.lstat(params.filePath),
+            pathStat,
             postOpenStat: stat,
             preOpenStat: result.stat,
         });
@@ -126,7 +146,7 @@ function verifyStableReadTarget(params) {
     }
     if (!sameFileIdentity(params.preOpenStat, params.postOpenStat) ||
         !sameFileIdentity(params.pathStat, params.postOpenStat)) {
-        throw new Error(`File changed during read: ${params.filePath}`);
+        throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
     }
 }
 function readOpenedRegularFileSync(params) {

package/dist/root-impl.d.ts

@@ -1,17 +1,17 @@
 import type { Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
+import { type DenyMutationPolicy } from "./deny-mutations.js";
+import { type ReadResult } from "./read-opened-file.js";
 import type { DirEntry, PathStat } from "./types.js";
+export type { DenyMutationPolicy } from "./deny-mutations.js";
+export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
+export type { ReadResult } from "./read-opened-file.js";
 export type OpenResult = {
     handle: FileHandle;
     realPath: string;
     stat: Stats;
     [Symbol.asyncDispose](): Promise<void>;
 };
-export type ReadResult = {
-    buffer: Buffer;
-    realPath: string;
-    stat: Stats;
-};
 export type RootOptions = {
     rootDir: string;
     defaults?: RootDefaults;
@@ -24,19 +24,20 @@ export type RootDefaults = {
     maxBytes?: number;
     mkdir?: boolean;
     mode?: number;
+    denyMutations?: DenyMutationPolicy;
     nonBlockingRead?: boolean;
     symlinks?: SymlinkPolicy;
 };
 export type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
 export type RootOpenOptions = Omit<RootReadOptions, "maxBytes">;
-export type RootWriteOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+export type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
     encoding?: BufferEncoding;
     overwrite?: boolean;
 };
-export type RootOpenWritableOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+export type RootOpenWritableOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
     writeMode?: WritableOpenMode;
 };
-export type RootCopyOptions = Pick<RootDefaults, "maxBytes" | "mkdir" | "mode"> & {
+export type RootCopyOptions = Pick<RootDefaults, "denyMutations" | "maxBytes" | "mkdir" | "mode"> & {
     sourceHardlinks?: HardlinkPolicy;
 };
 export type RootWriteJsonOptions = RootWriteOptions & {
@@ -49,6 +50,11 @@ export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite">;
 export type RootAppendOptions = RootWriteOptions & {
     prependNewlineIfNeeded?: boolean;
 };
+export type RootMoveOptions = Pick<RootDefaults, "denyMutations"> & {
+    overwrite?: boolean;
+};
+export type RootRemoveOptions = Pick<RootDefaults, "denyMutations">;
+export type RootMkdirOptions = Pick<RootDefaults, "denyMutations">;
 export declare const DEFAULT_ROOT_MAX_BYTES: number;
 export interface Root {
     readonly rootDir: string;
@@ -69,9 +75,9 @@ export interface Root {
     reader(options?: RootReadOptions): (filePath: string) => Promise<Buffer>;
     openWritable(relativePath: string, options?: RootOpenWritableOptions): Promise<WritableOpenResult>;
     append(relativePath: string, data: string | Buffer, options?: RootAppendOptions): Promise<void>;
-    remove(relativePath: string): Promise<void>;
-    mkdir(relativePath: string): Promise<void>;
-    ensureRoot(): Promise<void>;
+    remove(relativePath: string, options?: RootRemoveOptions): Promise<void>;
+    mkdir(relativePath: string, options?: RootMkdirOptions): Promise<void>;
+    ensureRoot(options?: RootMkdirOptions): Promise<void>;
     write(relativePath: string, data: string | Buffer, options?: RootWriteOptions): Promise<void>;
     create(relativePath: string, data: string | Buffer, options?: RootCreateOptions): Promise<void>;
     writeJson(relativePath: string, data: unknown, options?: RootWriteJsonOptions): Promise<void>;
@@ -85,9 +91,7 @@ export interface Root {
     list(relativePath: string, options: {
         withFileTypes: true;
     }): Promise<DirEntry[]>;
-    move(fromRelative: string, toRelative: string, options?: {
-        overwrite?: boolean;
-    }): Promise<void>;
+    move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
 }
 export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 export declare function readLocalFileSafely(params: {
@@ -104,5 +108,4 @@ export type WritableOpenResult = {
     stat: Stats;
     [Symbol.asyncDispose](): Promise<void>;
 };
-export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
 //# sourceMappingURL=root-impl.d.ts.map

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

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

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.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/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/root.md

@@ -19,17 +19,23 @@ function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
+  denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
   mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append
   mode?: number;                   // file mode applied to new writes; per-call override available
   nonBlockingRead?: boolean;       // schedule reads on a worker; useful for large files
   symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
 };
+
+type DenyMutationPolicy = {
+  paths?: readonly string[];
+  prefixes?: readonly string[];
+};
 ```
 
 `root()` resolves the directory through the real filesystem. A symlinked input becomes the canonical path; a non-existent root throws `FsSafeError` with code `not-found`, and malformed or non-directory roots throw `invalid-path`.
 
-`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only.
+`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only, except `denyMutations`: root and per-call deny entries are merged so a call cannot clear a root-level deny.
 
 ## The `Root` interface
 
@@ -69,9 +75,9 @@ fs.append(rel, data, options?)           // append text/buffer; respects mkdir d
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
 fs.move(from, to, options?)              // rename within the root; defaults to no clobber
-fs.remove(rel)                           // unlink file or rmdir empty directory
-fs.mkdir(rel)                            // mkdir -p (creates missing parents)
-fs.ensureRoot()                          // accepts "" / "." as the root itself
+fs.remove(rel, options?)                 // unlink file or rmdir empty directory
+fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
+fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 ```
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
@@ -80,6 +86,8 @@ fs.ensureRoot()                          // accepts "" / "." as the root itself
 
 `openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
 
+All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
+
 ### Inspection (advisory)
 
 ```ts
@@ -132,6 +140,7 @@ Every method throws `FsSafeError` with a `code`. Branch on `err.code`, not messa
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). |
 | `not-file` | A read or copy targeted a non-regular file (directory, FIFO, socket, …). |
 | `already-exists` | `create()` or `move()` without `overwrite` hit an existing target. |
+| `denied-path` | A mutation target matched `denyMutations.paths` or `denyMutations.prefixes`. |
 | `symlink` | A path component is a symlink, and the call's `symlinks` policy is `reject`. |
 | `hardlink` | The target's `nlink > 1` and `hardlinks` policy is `reject`. |
 | `path-mismatch` | Post-open identity check failed — the opened fd does not match the resolved path. |

package/docs/security-model.md

@@ -50,6 +50,10 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 `resolve()`, `exists()`, `stat()`, and `list()` are explicitly **not** race-resistant — they answer a question and return. To act on a path with race resistance, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. They re-pin the path identity at the point of use.
 
+### Denied mutations
+
+`denyMutations` is an opt-in application policy for `root()` mutation methods. It blocks exact absolute paths with `paths` and whole subtrees with `prefixes`, merging root defaults with per-call entries so a call cannot clear root-level denies. This is not an OS permission boundary: code with access to `node:fs`, a shell, or another process with the same filesystem privileges can bypass it.
+
 ### Atomic writes
 
 `replaceFileAtomic` writes to a sibling temp file in the destination directory, optionally `fsync`s it, optionally `fsync`s the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path.

package/docs/types.md

@@ -82,6 +82,7 @@ type ReadResult = {
 
 ```ts
 type RootDefaults = {
+  denyMutations?: DenyMutationPolicy;
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   mkdir?: boolean;
@@ -90,26 +91,31 @@ type RootDefaults = {
   symlinks?: "reject" | "follow-within-root";
 };
 
+type DenyMutationPolicy = {
+  paths?: readonly string[];
+  prefixes?: readonly string[];
+};
+
 type RootOptions = {
   rootDir: string;
   defaults?: RootDefaults;
 };
 ```
 
-`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these.
+`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` is the exception: root and per-call deny entries are merged.
 
 ## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };
-type RootCopyOptions = Pick<RootDefaults, "maxBytes" | "mkdir" | "mode"> & {
+type RootCopyOptions = Pick<RootDefaults, "denyMutations" | "maxBytes" | "mkdir" | "mode"> & {
   sourceHardlinks?: "reject" | "allow";
 };
-type RootOpenWritableOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+type RootOpenWritableOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
   writeMode?: "replace" | "append" | "update";
 };
 type RootWriteJsonOptions = RootWriteOptions & {
@@ -120,6 +126,11 @@ type RootWriteJsonOptions = RootWriteOptions & {
 type RootAppendOptions = RootWriteOptions & {
   prependNewlineIfNeeded?: boolean;
 };
+type RootMoveOptions = Pick<RootDefaults, "denyMutations"> & {
+  overwrite?: boolean;
+};
+type RootRemoveOptions = Pick<RootDefaults, "denyMutations">;
+type RootMkdirOptions = Pick<RootDefaults, "denyMutations">;
 ```
 
 Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
@@ -137,11 +148,12 @@ The two policy unions you'll see throughout. `"reject"` is conservative; `"follo
 
 ```ts
 type FsSafeErrorCode =
-  | "already-exists" | "hardlink" | "helper-failed" | "helper-unavailable"
-  | "insecure-permissions" | "invalid-path" | "not-empty" | "not-file"
-  | "not-found" | "not-owned" | "not-removable" | "outside-workspace"
-  | "path-alias" | "path-mismatch" | "permission-unverified"
-  | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+  | "already-exists" | "denied-path" | "hardlink" | "helper-failed"
+  | "helper-unavailable" | "insecure-permissions" | "invalid-path"
+  | "not-empty" | "not-file" | "not-found" | "not-owned"
+  | "not-removable" | "outside-workspace" | "path-alias"
+  | "path-mismatch" | "permission-unverified" | "symlink"
+  | "timeout" | "too-large" | "unsupported-platform";
 ```
 
 Closed union you switch on. See the [Errors](errors.md) reference for what each one means.

package/docs/writing.md

@@ -24,6 +24,24 @@ await fs.mkdir("snapshots/2026/05");
 
 A failure at any point either leaves the destination at its previous contents or surfaces an `FsSafeError` — never a partially-written file at the destination path.
 
+## Denying mutations
+
+All mutation verbs accept `denyMutations?: DenyMutationPolicy`, either as a root default or per-call option:
+
+```ts
+const fs = await root("/srv/workspace", {
+  denyMutations: {
+    paths: ["/srv/workspace/.env"],
+    prefixes: ["/srv/workspace/.ssh"],
+  },
+});
+
+await fs.write(".env", "x");       // throws FsSafeError code "denied-path"
+await fs.remove(".ssh/id_rsa");    // throws FsSafeError code "denied-path"
+```
+
+`paths` blocks exact absolute paths. `prefixes` blocks absolute paths and everything below them. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a mutation through a symlinked ancestor to a denied path is still denied. Root-level and per-call policies are additive; per-call policy can add denies, but cannot clear root defaults.
+
 ## Write verbs
 
 ### `fs.write(rel, data, options?)`
@@ -35,7 +53,7 @@ await fs.write("state/last-run.json", JSON.stringify(run));
 await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 ```
 
-`data` accepts `string | Buffer`. `options` are `{ encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean }`. `mode` sets the file's POSIX mode; if omitted, falls back to the `mode` from `RootDefaults` and then to umask. `overwrite` defaults to `true`; set it to `false` for the same no-clobber behavior as `create()`.
+`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean }`. `mode` sets the file's POSIX mode; if omitted, falls back to the `mode` from `RootDefaults` and then to umask. `overwrite` defaults to `true`; set it to `false` for the same no-clobber behavior as `create()`.
 
 ### `fs.create(rel, data, options?)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {