@openclaw/fs-safe 0.2.7 → 0.4.0

package/docs/install.md

@@ -1,6 +1,6 @@
 # Install
 
-`fs-safe` is published to npm as `@openclaw/fs-safe`. It targets Node 20.11 or newer, ships ESM only, and works on macOS, Linux, and Windows.
+`fs-safe` is published to npm as `@openclaw/fs-safe`. It targets Node 22 or newer, ships ESM only, and works on macOS, Linux, and Windows.
 
 ## Package managers
 
@@ -22,13 +22,13 @@ bun add @openclaw/fs-safe
 
 ## Node version
 
-Minimum **Node 20.11**. The package uses `fs.promises`, `fs.constants.O_NOFOLLOW` where available, and `node:stream/promises`. Earlier Node releases will fail at import time.
+Minimum **Node 22**. The package uses `fs.promises`, `fs.constants.O_NOFOLLOW` where available, and `node:stream/promises`. Earlier Node releases will fail at import time.
 
 Verify the runtime:
 
 ```bash
 node --version
-# v20.11.0 or newer
+# v22.0.0 or newer
 ```
 
 ## TypeScript

package/docs/path.md

@@ -11,6 +11,8 @@ import {
   safeRealpathSync,
   safeStatSync,
   assertNoNulPathInput,
+  assertNoUnsafeDeviceReadPath,
+  isUnsafeDeviceReadPath,
   isNotFoundPathError,
   isSymlinkOpenError,
   hasNodeErrorCode,
@@ -89,6 +91,17 @@ if (!stat?.isFile()) return notFound();
 
 Throws `FsSafeError` with code `invalid-path` when a path string contains an embedded NUL byte. Use it before calling Node `fs` APIs directly; Node's native error can include raw path text in the message.
 
+### `assertNoUnsafeDeviceReadPath(filePath, options?)`
+
+Throws `FsSafeError` with code `device-path` when a read target is a known unsafe device or process-fd path. The built-in read/open helpers call this automatically before opening files; use it only when you are building your own read primitive.
+
+```ts
+assertNoUnsafeDeviceReadPath("/dev/zero"); // throws on POSIX
+isUnsafeDeviceReadPath("/dev/fd/0");       // true on POSIX
+```
+
+The check is intentionally not a normal consumer policy knob. Safe read APIs reject these targets by default because they can block forever, stream indefinitely, or alias process file descriptors.
+
 ## Error inspection
 
 ### `isNotFoundPathError(err)`

package/docs/reading.md

@@ -17,10 +17,11 @@ Regardless of shape, every read goes through the same boundary checks:
 1. Resolve the relative path against the canonical real root.
 2. Reject anything that escapes the root (`outside-workspace`).
 3. Reject `..` segments and absolute inputs (unless via `readAbsolute` with an in-root absolute path).
-4. Open with `O_NOFOLLOW` where available. A symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
-5. Stat the open fd and compare to the resolved path's identity (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
-6. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
-7. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
+4. Reject known unsafe device and process-fd paths before opening (`device-path`).
+5. Open with `O_NOFOLLOW` where available. A symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
+6. Stat the open fd and compare to the resolved path's identity (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
+7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
+8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
 ## Read shapes
 
@@ -160,6 +161,7 @@ try {
 - **`outside-workspace`** — relative path escaped the root, or `readAbsolute` got an absolute path outside.
 - **`not-found`** — the file is gone.
 - **`not-file`** — you read a directory or a non-regular file (FIFO, socket, …).
+- **`device-path`** — the path targets a known unsafe device or process fd path.
 - **`symlink`** — a path component is a symlink and the policy is `reject`.
 - **`path-mismatch`** — opened fd identity did not match the resolved path. Almost always a TOCTOU swap by something else.
 - **`hardlink`** — `hardlinks: "reject"` saw `nlink > 1`.

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
 
@@ -65,13 +71,13 @@ fs.write(rel, data, options?)            // overwrite-ok atomic write
 fs.create(rel, data, options?)           // throws "already-exists" if target exists
 fs.writeJson(rel, value, options?)       // JSON.stringify + atomic write
 fs.createJson(rel, value, options?)      // create() variant of writeJson
-fs.append(rel, data, options?)           // append text/buffer; respects mkdir default
+fs.append(rel, data, options?)           // append text/buffer; syncs before close
 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
@@ -131,7 +139,9 @@ Every method throws `FsSafeError` with a `code`. Branch on `err.code`, not messa
 | `outside-workspace` | The input resolves outside the root, or contains a `..` segment that would escape it. |
 | `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, …). |
+| `device-path` | A read/open target is a known unsafe device or process-fd path. |
 | `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

@@ -13,6 +13,7 @@ You hand a `root()` boundary to a piece of code that takes caller-controlled rel
 - replaces a path component with a symlink between check and use (TOCTOU)
 - replaces the destination directory with a symlink right before a write
 - creates a hardlink that aliases an out-of-tree inode and asks you to read or replace it
+- asks a read/open primitive to target a known unsafe device or process-fd path
 - triggers a partial write that leaves a half-written file at the destination
 - ships an archive with `..` paths, absolute paths, or symlinks pointing outside the destination
 
@@ -20,7 +21,7 @@ It does **not** defend against:
 
 - a process running with permissions to write anywhere on the filesystem and choosing to ignore the library
 - another process with the same UID racing to mutate the same directory between two separate `fs-safe` calls — the boundary is per-call, not per-session
-- traversal across filesystem boundaries, bind mounts, device files, `/proc`-style virtual filesystems, or any other path your process can normally access from inside the root
+- arbitrary traversal across filesystem boundaries, bind mounts, or virtual filesystems beyond the known unsafe read device paths
 - container escape, TOCTOU between fork and exec of helpers, or kernel-level vulnerabilities
 - semantic content checks: file types, archive payload schemas, signature verification
 
@@ -50,6 +51,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.
@@ -79,7 +84,7 @@ The library does not advertise different security guarantees per platform — it
 |---|---|
 | Not ambient authority removal | Code that can import `node:fs` can still bypass the handle. Keep caller-controlled path operations behind `root()` by convention, review, and tests. |
 | Absolute paths are escape hatches | APIs that accept or return absolute paths exist for audit, ingest, and advanced composition. Prefer root-relative names in normal application flow. |
-| Not a mount/device boundary | `root()` keeps path traversal inside the directory tree; it does not make device files, bind mounts, or virtual filesystems safe to expose. |
+| Not a mount boundary | `root()` keeps path traversal inside the directory tree and blocks known unsafe read device paths, but it does not make bind mounts or virtual filesystems safe to expose wholesale. |
 | Per-call, not per-session | Another process with the same privileges can still mutate the tree between two separate calls. Use one verb method for the operation you need to make race-resistant. |
 | Hardlink rejection is best-effort | Link-count checks depend on platform metadata. Treat `hardlinks: "reject"` as a tripwire, not an authorization primitive. |
 | Mode bits are not a full policy engine | `replaceFileAtomic` and secret-file helpers set requested modes, but you should still set umask and inspect modes when policy requires it. |

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,13 @@ 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" | "device-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/walk.md

@@ -25,6 +25,7 @@ type WalkDirectoryResult = {
   entries: WalkDirectoryEntry[];
   scannedEntryCount: number;
   truncated: boolean;
+  failedDirs?: WalkDirectoryFailure[];
 };
 
 type WalkDirectoryEntry = {
@@ -35,10 +36,19 @@ type WalkDirectoryEntry = {
   kind: "file" | "directory" | "symlink" | "other";
   dirent: import("node:fs").Dirent;
 };
+
+type WalkDirectoryFailure = {
+  path: string;
+  relativePath: string;
+  depth: number;
+  error: unknown;
+};
 ```
 
 `depth` starts at `1` for direct children of `rootDir`. `relativePath` is always relative to the supplied root. `scannedEntryCount` counts directory entries examined, including entries filtered out by `include`.
 
+`walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose `realpath`/`readdir` threw, so its contents are absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
+
 ## Options
 
 ```ts
@@ -55,7 +65,7 @@ type WalkDirectoryOptions = {
 
 `include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
 
-Unreadable directories are skipped. This makes the helper suitable for best-effort inventories and pruning jobs; use a stricter root-bounded operation when every entry must be accounted for.
+Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
 ## See also
 

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?)`
 
@@ -75,14 +93,14 @@ type RootWriteJsonOptions = {
 
 ### `fs.append(rel, data, options?)`
 
-Open in append mode, write, close. Honors `mkdir` for the parent directory. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
+Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);
 await fs.append("notes/scratch.md", "* new bullet", { prependNewlineIfNeeded: true });
 ```
 
-For high-volume logging, consider [`openWritable`](#openwritable) and a long-lived append handle.
+For high-volume logging, consider [`openWritable`](#openwritable) and a long-lived append handle. Direct append-mode writes preserve kernel append semantics, but they are not atomic against external rotators that rename or unlink the target.
 
 ### `fs.copyIn(rel, sourceAbsPath, options?)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {
@@ -97,29 +97,34 @@
       "default": "./dist/test-hooks.js"
     }
   },
+  "optionalDependencies": {
+    "jszip": "^3.10.1",
+    "tar": "7.5.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.20",
+    "@vitest/coverage-v8": "4.1.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
-    "prepack": "node scripts/prepack-build.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
     "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test",
-    "docs:site": "node scripts/build-docs-site.mjs"
-  },
-  "optionalDependencies": {
-    "jszip": "^3.10.1",
-    "tar": "7.5.13"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.19",
-    "@vitest/coverage-v8": "4.1.6",
-    "typescript": "^5.8.3",
-    "vitest": "^4.1.6"
-  },
-  "engines": {
-    "node": ">=20.11"
+    "docs:site": "node scripts/build-docs-site.mjs",
+    "check:changed": "pnpm run check",
+    "test:changed": "pnpm run test",
+    "crabbox:hydrate": "crabbox actions hydrate",
+    "crabbox:run": "crabbox run",
+    "crabbox:stop": "crabbox stop",
+    "crabbox:warmup": "crabbox warmup"
   }
-}
+}