@openclaw/fs-safe 0.5.1 → 0.5.2

package/docs/atomic.md

@@ -14,7 +14,9 @@ import {
 
 ## `replaceFileAtomic` / `replaceFileAtomicSync`
 
-Write `content` to a sibling temp file in the destination directory, optionally `fsync` the temp file, optionally `fsync` the parent directory after rename, then atomically rename over the destination.
+Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
+
+On POSIX, the parent is opened with no-follow and directory-only flags, checked against its pre-open identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
 
@@ -36,18 +38,19 @@ await replaceFileAtomic({
 type ReplaceFileAtomicOptions = {
   filePath: string;                 // destination
   content: string | Uint8Array;
-  dirMode?: number;                 // mode for parent dirs created by the helper
-  mode?: number;                    // explicit mode for the new file (e.g. 0o600)
-  preserveExistingMode?: boolean;   // copy mode from existing destination, when present
-  tempPrefix?: string;
-  renameMaxRetries?: number;
-  renameRetryBaseDelayMs?: number;
-  copyFallbackOnPermissionError?: boolean;
+  dirMode?: number;                 // parent-directory mode (POSIX; default 0o700)
+  mode?: number;                    // new-file mode (default 0o600)
+  preserveExistingMode?: boolean;   // copy existing mode; default false
+  tempPrefix?: string;              // default ".fs-safe-replace"
+  renameMaxRetries?: number;        // EBUSY retries; default 0
+  renameRetryBaseDelayMs?: number;  // exponential base; default 50
+  copyFallbackOnPermissionError?: boolean; // default false
   copyFallbackRestore?: "restore-original" | "none"; // default: "none"
   maxRestoreBytes?: number;          // required with "restore-original"
-  destinationHardlinks?: "reject";
-  syncTempFile?: boolean;           // fsync(temp) before rename
-  syncParentDir?: boolean;          // fsync(parent) after rename (POSIX only)
+  destinationHardlinks?: "reject"; // default unset (no destination nlink policy)
+  syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
+  syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
+  throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -87,9 +90,10 @@ The default `copyFallbackRestore: "none"` preserves the existing fallback
 contract: a failed copy can leave a partial destination. For state files where
 preserving the old bytes is more important, choose `"restore-original"` and set
 an explicit `maxRestoreBytes` memory budget. If the destination exists, fs-safe
-snapshots it through a pinned descriptor, overwrites through that same
-descriptor, and synchronizes the result. Any write or sync failure triggers a
-restore and another sync through the same descriptor.
+snapshots it through a pinned descriptor, overwrites and mode-adjusts through
+that same descriptor, and synchronizes the result. Any write, mode, or sync
+failure triggers a byte-and-mode restore and another sync through the same
+descriptor.
 
 Restore failures are `FsSafeError("helper-failed")` values with typed
 `details.cleanup` set to `"restored"` or `"restore-failed"`. An original larger
@@ -99,7 +103,10 @@ fallback.
 
 ### Sync variant
 
-`replaceFileAtomicSync` accepts the same options shape, with the obvious removal of the async-only hooks. Use it inside synchronous boot paths or test setup code.
+`replaceFileAtomicSync` accepts the same base options, a synchronous
+`beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
+synchronous boot paths or test setup code. It returns the same
+`{ method: "rename" | "copy-fallback" }` receipt as the async variant.
 
 ## `replaceDirectoryAtomic`
 
@@ -115,13 +122,17 @@ await replaceDirectoryAtomic({
 ```
 
 The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
+Concurrent replacements of the same resolved target are serialized inside the
+current process so their backup, commit, and cleanup phases cannot interleave.
+`backupPrefix`, when supplied, is sanitized as one path prefix and cannot contain
+path separators or NUL bytes; the generated backup tail is randomized.
 
 Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 ## `writeTextAtomic`
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
-temp file, temp fsync, rename, parent fsync, and final chmod best-effort.
+temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
 It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
 you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
 or custom copy-fallback policy.
@@ -141,8 +152,8 @@ Options:
 ```ts
 type WriteTextAtomicOptions = {
   mode?: number;             // file mode (default 0o600)
-  dirMode?: number;          // mode for parent dirs created on demand
-  trailingNewline?: boolean; // append "\n" if missing
+  dirMode?: number;          // parent mode (default 0o777 masked by process umask)
+  trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
 };
 ```
@@ -157,7 +168,14 @@ Rename a path. If the rename fails with `EXDEV` (cross-device), fall back to
 copying into a staged sibling path, renaming that staged path into place, and
 then removing only the source entries that were copied. The fallback avoids
 buffering regular files into memory and does not tighten the destination parent
-directory mode.
+directory mode. Staged file modes are applied through their still-open handles.
+If descriptor-bound mode application fails, the staged path is removed and the
+move fails before publication. A transient staged-path cleanup failure retains
+an identity-bound process-exit cleanup retry.
+On POSIX, staged directory modes are applied through no-follow directory
+descriptors; on Windows, Node cannot portably open those descriptors and no
+pathname `chmod` fallback is attempted, so directory modes remain subject to
+Windows' `mkdir(mode)` behavior.
 
 ```ts
 import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
@@ -212,6 +230,17 @@ await replaceFileAtomic({
 });
 ```
 
+The synchronous injectable interface has one optional descriptor-mode operation:
+
+```ts
+type ReplaceFileAtomicSyncFileSystem = {
+  // other required operations omitted
+  fchmodSync?: typeof import("node:fs").fchmodSync;
+};
+```
+
+The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. On POSIX, that `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
+
 ## See also
 
 - [`root()`](root.md) — when you want method-style writes with the boundary baked in.

package/docs/errors.md

@@ -2,6 +2,10 @@
 
 Every failure that's the library's job to surface lands as an `FsSafeError` with a closed `code` union you can branch on. Catch by code, not by message text — messages may change, codes will not.
 
+Path and archive-entry details embedded in diagnostics escape control characters
+as `\\uXXXX` sequences. This keeps attacker-controlled names on one log line;
+the escaped message is for diagnosis, not for reconstructing the original path.
+
 ```ts
 import { FsSafeError, type FsSafeErrorCode } from "@openclaw/fs-safe";
 ```
@@ -50,8 +54,17 @@ destination.
 
 `category` separates caller-policy failures from operational failures:
 
-- `"policy"` — unsafe input or target state, such as `outside-workspace`, `symlink`, `hardlink`, or `too-large`.
-- `"operational"` — environment/runtime failures, such as helper startup, platform support, timeout, or unverifiable permissions.
+- `"policy"` — unsafe input or target state rejected by a safety policy, such as `outside-workspace`, `symlink`, `hardlink`, or `too-large`.
+- `"operational"` — routine filesystem outcomes or environment/runtime failures, such as `not-found`, `not-empty`, `not-removable`, helper startup, platform support, timeout, or unverifiable permissions.
+
+Routine absence or inability to remove a path does not by itself indicate a
+filesystem boundary violation. Branch on the specific code when the distinction
+between those operational outcomes matters.
+
+The operational set is exactly `helper-failed`, `helper-unavailable`,
+`not-empty`, `not-found`, `not-removable`, `permission-unverified`, `timeout`,
+and `unsupported-platform`. Every other current `FsSafeErrorCode`, including
+`store-reentrant-update`, is categorized as `policy`.
 
 ## Code union
 
@@ -75,6 +88,7 @@ type FsSafeErrorCode =
   | "path-mismatch"
   | "permission-unverified"
   | "secret-exists"
+  | "store-reentrant-update"
   | "symlink"
   | "timeout"
   | "too-large"
@@ -92,7 +106,7 @@ type FsSafeErrorCode =
 | `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
 | `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, missing/incompatible bundled binary, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
 | `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
-| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable. | Caller didn't validate input; input was a network path on Windows. |
+| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable. | Caller didn't validate input; input was a network path on Windows, a drive-relative segment in a portable relative path or store key, or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain legal POSIX drive-like names. |
 | `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
 | `not-file` | Read or copy targeted a non-regular file. | Target was a directory, FIFO, socket, device. |
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). | Typical missing-file case. |
@@ -103,10 +117,11 @@ type FsSafeErrorCode =
 | `path-mismatch` | Post-open identity check failed: the opened fd does not match the resolved path. | TOCTOU — something else swapped the path between resolve and open. |
 | `permission-unverified` | A secure file check could not verify required permissions. | Windows ACL inspection failed; POSIX ownership/mode was unavailable. |
 | `secret-exists` | `createSecretFileAtomic()` found an existing final path. | First-writer-wins secret creation lost a race or the credential was already initialized. |
+| `store-reentrant-update` | A `JsonStore.update()` callback called `update()` or `updateOr()` for the same canonical store before returning. | Reentrant mutation would deadlock or lose an update; return the complete next value from the outer callback. |
 | `symlink` | Path component is a symlink, policy is `reject`. | Caller followed a symlink they shouldn't have, or `symlinks: "reject"` is set. |
 | `timeout` | An operation with a wall-clock budget overran. | Secure file read or timed operation exceeded `timeoutMs`. |
 | `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
-| `unsupported-platform` | The requested operation is not supported on the current platform. | E.g. POSIX-only helper invoked on Windows. |
+| `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
 
 ## Branching
 
@@ -138,11 +153,13 @@ try {
 }
 ```
 
-The compiler will flag missing cases when you exhaust the union — keep your switch up-to-date as the library adds new codes.
+The `default` above deliberately rethrows unknown codes, so it remains safe as
+the union grows. If you want the compiler to flag every newly added code, end
+an exhaustive switch with a `never` assertion instead of a general `default`.
 
 ## Distinguishing from `NodeJS.ErrnoException`
 
-Some failures bubble up as native Node errors (e.g. `EACCES`, `EISDIR`, `EBUSY`) when they don't map cleanly to a library code. Inspect both:
+Some failures bubble up as native Node errors (e.g. `EACCES`, `EPERM`, `EISDIR`, `EBUSY`) when they don't map cleanly to a library code. Inspect both:
 
 ```ts
 import { FsSafeError } from "@openclaw/fs-safe";
@@ -154,7 +171,8 @@ try {
     handleFsSafe(err);
     return;
   }
-  if ((err as NodeJS.ErrnoException).code === "EACCES") {
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code === "EACCES" || code === "EPERM") {
     handleAccess();
     return;
   }
@@ -164,6 +182,12 @@ try {
 
 A common pattern is to wrap your domain code in a single try/catch that maps both shapes to your application's typed error format.
 
+On Windows, access-denied failures from native root/open filesystem operations
+use `EPERM` to match Node/libuv and the JavaScript fallback. Security-descriptor
+inspection has its own failure surface. Older fs-safe versions could report
+`EACCES` for the same root/open condition, so consumers spanning versions
+should accept both codes.
+
 ## Specialty errors
 
 A handful of helpers throw their own typed errors instead of `FsSafeError`:

package/docs/file-store.md

@@ -43,7 +43,7 @@ type FileStore = {
   readonly rootDir: string;
   path(relativePath: string): string;
   root(): Promise<Root>;
-  write(rel, data: string | Buffer, options?): Promise<string>;
+  write(rel, data: string | Uint8Array, options?): Promise<string>;
   writeStream(rel, stream: Readable, options?): Promise<string>;
   copyIn(rel, sourcePath: string, options?): Promise<string>;
   open(rel, options?): Promise<OpenResult>;
@@ -64,6 +64,15 @@ type FileStore = {
 
 `path()` returns the absolute path the store would use, after asserting it stays inside `rootDir`. Useful for logging or for handing to other libraries.
 
+Every `relativePath` is a portable store key, including keys passed to reads,
+`exists`, and `remove`. A segment with a Windows drive-relative spelling such
+as `C:name` (including an embedded segment such as `a/C:name`) throws
+`invalid-path` on every platform. This prevents a key created on POSIX from
+aliasing a different file when the store is moved to Windows. Colons elsewhere,
+such as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain valid.
+Keys with surrounding whitespace also throw `invalid-path`; the store never
+silently trims one caller-supplied key onto another key.
+
 `root()` returns a [`Root`](root.md) handle for the same directory when you need the full surface (move, list, mkdir). It's a fresh handle per call and is safe to call frequently.
 
 ## Writes

package/docs/filename.md

@@ -1,9 +1,9 @@
 # Filenames
 
-`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one portable path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
+`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
 
 ```ts
-import { sanitizeUntrustedFileName } from "@openclaw/fs-safe";
+import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
 
 const safe = sanitizeUntrustedFileName(req.body.fileName, "upload");
 await fs.write(`uploads/${safe}`, body);
@@ -24,9 +24,12 @@ In order:
 3. **Strip non-portable characters.** C0/C1 controls (`0x00`–`0x1f`, `0x7f`–`0x9f`) and the Windows-invalid set `< > : " / \\ | ? *` are removed on every platform.
 4. **Trim again.**
 5. If the result is empty, `"."`, or `".."`, return `fallbackName`.
-6. **Truncate.** If the cleaned segment is longer than 200 characters, take the first 200.
+6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
+7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
 
-That's it. The function stays intentionally small: it produces one traversal-free segment whose characters work across the common POSIX and Windows filename surfaces.
+That's it. The function stays intentionally small: it removes traversal and
+the most obvious cross-platform device and character hazards, but it is not a
+complete portable-filename or uniqueness policy.
 
 ## Examples
 
@@ -38,35 +41,33 @@ sanitizeUntrustedFileName("a\u0000b\tc", "upload");       // "abc"
 sanitizeUntrustedFileName("   ", "fallback");              // "fallback"
 sanitizeUntrustedFileName(".", "fallback");                // "fallback"
 sanitizeUntrustedFileName("..", "fallback");               // "fallback"
-sanitizeUntrustedFileName("a".repeat(300), "x");           // 200-char "aaa..."
+sanitizeUntrustedFileName("CON", "fallback");              // "CON_"
+sanitizeUntrustedFileName("nul.txt", "fallback");          // "nul_.txt"
+sanitizeUntrustedFileName("aux.c", "fallback");            // "aux_.c"
+sanitizeUntrustedFileName("conin$", "fallback");           // "conin$_"
+sanitizeUntrustedFileName("a".repeat(300), "x");          // 200-char "aaa..."
 ```
 
 ## What it does **not** do
 
 The function is deliberately narrow. It will not:
 
-- Reject Windows reserved names (`CON`, `PRN`, `AUX`, `NUL`, `COM1..9`, `LPT1..9`).
 - Replace leading dots (so a name like `.config` stays hidden on POSIX systems).
-- Trim trailing dots or spaces (Windows tolerates them silently).
+- Trim trailing dots. Surrounding spaces are removed by the documented trim
+  steps, but Windows-normalized dot/space spellings can still alias; reject or
+  rewrite them when Windows portability or cross-platform migration matters.
 - Add an extension or change case.
 - Validate file *content*. To enforce an extension allow-list, check after sanitization.
 - Deduplicate against existing files. Append a random suffix if you need uniqueness.
 
-If your domain needs stricter handling, layer it on top:
-
-```ts
-const trimmed = sanitizeUntrustedFileName(input, "upload");
-const noWindowsReserved = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..+)?$/i.test(trimmed)
-  ? "upload"
-  : trimmed;
-```
+Windows reserved basenames are handled by the default portability pass; callers no longer need to layer a separate reserved-name recipe on top.
 
 ## Common patterns
 
 ### Make a unique filename
 
 ```ts
-import { sanitizeUntrustedFileName } from "@openclaw/fs-safe";
+import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
 import { randomUUID } from "node:crypto";
 
 const base = sanitizeUntrustedFileName(req.body.fileName, "upload");

package/docs/index.md

@@ -69,6 +69,7 @@ await fs.remove("notes/archive/today.txt");
 | [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |
 | [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
 | [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
+| [Public API inventory](public-api.md) | Complete runtime/type export cross-check against the generated declarations. |
 | [`pathScope()`](path-scope.md) | Lower-level absolute-path boundary helper; lives behind `@openclaw/fs-safe/advanced`. |
 | [`@openclaw/fs-safe/advanced`](advanced.md) | Directory of lower-level composition helpers (path scopes, regular-file I/O, install paths, sibling-temp writes, …). |
 | [`@openclaw/fs-safe/test-hooks`](test-hooks.md) | Test-only injection hooks for reproducing open/lstat races. |

package/docs/install-path.md

@@ -95,16 +95,19 @@ Returns a directory-safe segment **plus** a short content hash when sanitization
 
 ```ts
 safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
-safePathSegmentHashed("plugin/v1");                  // "plugin-v1-3f2a..."
-safePathSegmentHashed("plugin\\v1");                 // "plugin-v1-91c4..."  (different hash; same safe form)
-safePathSegmentHashed("Über@");                       // "ber-9aae..."
-safePathSegmentHashed("");                           // "skill"  (empty fallback)
-safePathSegmentHashed(".");                          // "skill"
+safePathSegmentHashed("plugin/v1");                  // "plugin-v1-d9ef8af2eb"
+safePathSegmentHashed("plugin\\v1");                 // "plugin-v1-bed33f465b"
+safePathSegmentHashed("Über@");                       // "ber-e392bba2b3"
+safePathSegmentHashed("");                           // "skill-e3b0c44298"
+safePathSegmentHashed(".");                          // "skill-cdb4ee2aea"
 ```
 
 The sanitization is more aggressive than `safeDirName`: any character not in `[A-Za-z0-9._-]` becomes `-`, runs of `-` collapse, leading and trailing `-` are stripped, the empty/`.`/`..` fallback is `"skill"`. Long results are truncated to 50 chars before the hash is appended.
 
-The hash is the first 10 hex chars of `sha256(originalInput)`. It guarantees that two distinct inputs which sanitize to the same string yield distinct outputs.
+The suffix is the first 10 hex characters of `sha256(trimmedInput)`. It makes
+collisions between distinct trimmed inputs unlikely, but it is a 40-bit
+identifier rather than a mathematical uniqueness guarantee. Inputs that differ
+only by surrounding whitespace intentionally map to the same output.
 
 ## Common patterns
 

package/docs/json.md

@@ -133,7 +133,12 @@ where lower latency matters more than crash-durability.
 
 ### `writeJsonSync(pathname, data)`
 
-Synchronous variant. Convenience wrapper that uses the sync atomic-write path with sensible defaults.
+Synchronous variant. It pretty-prints with two spaces, appends a newline,
+creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
+directory best-effort. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+compatibility path may replace by copy rather than atomic rename; use the async
+`writeJson()`/`replaceFileAtomic()` surfaces when fallback policy must be
+explicit.
 
 ```ts
 writeJsonSync("./prefs.json", { theme: "dark" });
@@ -187,7 +192,8 @@ const state = await readJsonIfExists<State>("./state.json");
 
 | Throw / return | When |
 |---|---|
-| `null` (lenient reads) | File missing or contents are not valid JSON. |
+| `null` from `tryReadJson` / `tryReadJsonSync` | Any read or parse failure. |
+| `null` from `readJsonIfExists` | File is missing; invalid or unreadable input still throws. |
 | `JsonFileReadError` | `readJson` or `readJsonIfExists` saw unreadable or invalid input. Inspect `cause`. |
 | Native `NodeJS.ErrnoException` | Lower-level fs errors not wrapped. |
 

package/docs/local-roots.md

@@ -1,11 +1,9 @@
 # Local roots
 
-`local-roots` is a small set of helpers for code that holds a list of trusted base directories ("roots") and wants to look up an absolute path or a relative-to-some-root reference against any of them.
-
-The shape covers two needs:
-
-- "Resolve this path string to an absolute path that lives inside one of the configured roots, or refuse it."
-- "Read this path, where it could be `/abs/path`, `~/relative`, `file://…`, or simply the basename of a file in one of my roots."
+The local-roots helpers accept a file path plus a list of trusted absolute
+directories and return the first canonical root that contains the file. Use
+them when configuration may name one of several approved media, cache, or
+workspace roots.
 
 ```ts
 import {
@@ -14,92 +12,102 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-## Shape of a "roots input"
+## Input shape
 
-Both helpers take roots as either an array of strings or a `LocalRootsInputOptions` record. Each root is an absolute path the caller already trusts:
+Both helpers take one options object. `filePath` may be absolute, home-relative,
+relative to the current working directory, or a local `file://` URL. Relative
+inputs are resolved exactly as Node resolves them; they are not searched as a
+basename under each root.
 
 ```ts
 type LocalRootsInputOptions = {
-  roots: string[];                    // absolute paths
-  allowAbsolute?: boolean;            // accept absolute inputs (default true)
-  allowFileUrls?: boolean;            // accept file:// URLs (default true)
-  expandHome?: boolean;               // expand ~ in inputs (default true)
+  filePath: string;
+  roots: readonly string[]; // trusted absolute paths, checked in order
+  label?: string;           // used in validation errors
 };
 ```
 
-If a root is a symlink, it is canonicalized at lookup time. The helpers work in the order roots are listed: the first root that contains the resolved path wins.
-
-## `resolveLocalPathFromRootsSync(input, options)`
+Roots may use `~` or local `file://` spellings, but each resolved root must be
+absolute. Existing root symlinks are canonicalized before containment is
+checked. Invalid root entries throw `FsSafeError("invalid-path")`; an invalid
+`file://` input throws `Error`. A path that is valid but does not fall inside
+any usable root returns `null`.
 
-Synchronous resolution. Returns:
+## `resolveLocalPathFromRootsSync(options)`
 
 ```ts
-type LocalRootsPathResult =
-  | { ok: true; absolutePath: string; rootDir: string; relativePath: string }
-  | { ok: false; reason: "outside-roots" | "invalid-input" };
+type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+  allowMissing?: boolean; // default false
+  requireFile?: boolean;  // default false
+};
+
+type LocalRootsPathResult = {
+  path: string; // canonical candidate path
+  root: string; // canonical containing root
+};
 ```
 
+For an existing upload:
+
 ```ts
 import { resolveLocalPathFromRootsSync } from "@openclaw/fs-safe/advanced";
 
-const r = resolveLocalPathFromRootsSync("photo.jpg", {
+const r = resolveLocalPathFromRootsSync({
+  filePath: "/srv/uploads/photo.jpg",
   roots: ["/srv/uploads", "/srv/cache"],
+  requireFile: true,
 });
 
-if (!r.ok) return reply(400, r.reason);
-console.log(r.absolutePath);  // /srv/uploads/photo.jpg (assuming it's there)
-console.log(r.rootDir);       // /srv/uploads
-console.log(r.relativePath);  // photo.jpg
+if (!r) throw new Error("photo is outside the configured roots");
+console.log(r.path); // canonical path to photo.jpg
+console.log(r.root); // canonical /srv/uploads
 ```
 
-### Resolution order
-
-For each candidate input:
-
-1. If the input is a `file://` URL and `allowFileUrls` is true, decode to an absolute path.
-2. If the input begins with `~/` and `expandHome` is true, expand to the user's home dir.
-3. If the input is absolute (`/...` or Windows drive) and `allowAbsolute` is true, accept it as-is and check it falls under one of the roots.
-4. Otherwise, treat the input as relative and resolve it against each root in order until one contains the resulting path.
-
-If no root contains the result, returns `{ ok: false, reason: "outside-roots" }`.
-
-`"invalid-input"` covers empty strings, embedded NULs, encoded `..` traversal, Windows network paths (`\\server\share`), and other constructs that should not be resolved at all.
+By default the candidate must exist. `allowMissing: true` instead canonicalizes
+the nearest existing ancestor and validates the missing tail, which is useful
+when selecting a future output location. `requireFile: true` rejects existing
+directories and other non-file leaves. Dangling symlinks and candidates whose
+ancestors cannot be canonicalized are rejected rather than treated as safe
+missing paths.
 
-## `readLocalFileFromRoots(input, options)`
+## `readLocalFileFromRoots(options)`
 
-Async. Resolves through the same logic, then reads the file via [`Root`](root.md) so the read benefits from boundary checks, `O_NOFOLLOW`, and fd identity verification.
+The asynchronous helper opens the candidate through the matched [`Root`](root.md),
+so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
+the read itself.
 
 ```ts
+type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+  hardlinks?: "reject" | "allow";
+  maxBytes?: number;
+  nonBlockingRead?: boolean;
+  symlinks?: "reject" | "follow-within-root";
+};
+
 type LocalRootsReadResult = ReadResult & {
-  rootDir: string;
-  relativePath: string;
+  root: string; // canonical containing root
 };
+```
 
-const r = await readLocalFileFromRoots("photo.jpg", {
+```ts
+const r = await readLocalFileFromRoots({
+  filePath: "/srv/uploads/photo.jpg",
   roots: ["/srv/uploads", "/srv/cache"],
   maxBytes: 8 * 1024 * 1024,
 });
-if (!r) return reply(404);
+if (!r) throw new Error("photo is missing, unreadable, or outside the roots");
 process.stdout.write(r.buffer);
 ```
 
-The result extends `ReadResult` (`{ buffer, realPath, stat }`) with the matched `rootDir` and the path relative to it. Returns `null` if the input doesn't resolve into any root or the file is missing.
-
-### Read options
-
-```ts
-type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
-  hardlinks?: "reject" | "allow";
-  maxBytes?: number;
-  symlinks?: "reject" | "follow-within-root";
-};
-```
-
-The read-side options are forwarded to `Root` for the actual read.
+The helper returns `null` when no configured root can be opened or no safe read
+succeeds. This intentionally collapses missing, outside-root, and per-root read
+failures; use a single `Root` directly when the caller must distinguish those
+outcomes. Omitting `maxBytes` preserves `Root`'s 16 MiB default.
 
-## `local-file-access` companions
+## File URL and Windows-path companions
 
-The `local-file-access` module (re-exported from `@openclaw/fs-safe/advanced`) supplies a few small helpers for input normalization that the roots helpers use under the hood. They are also useful on their own:
+The advanced surface also exports the normalization helpers used around this
+API:
 
 ```ts
 import {
@@ -113,52 +121,20 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-- `safeFileURLToPath(fileUrl)` — `url.fileURLToPath` with explicit error throwing. Refuses URLs that decode to network paths.
-- `trySafeFileURLToPath(fileUrl)` — same, returns `undefined` instead of throwing.
-- `isWindowsDriveLetterPath(p, platform?)` — true for `C:\...` style absolute paths when the platform is Windows.
-- `isWindowsNetworkPath(p, platform?)` — true for `\\server\share` and `//server/share` style paths when the platform is Windows.
-- `assertNoWindowsNetworkPath(p, label?)` — throws if it is.
-- `basenameFromMediaSource(source?)` — best-effort filename extraction from URLs / data URIs / paths, for naming downloaded media.
-- `hasEncodedFileUrlSeparator(pathname)` — true for paths containing percent-encoded `/` (`%2F` / `%5C`), which often indicate traversal attempts.
-
-## Common patterns
-
-### Multi-root config: search project, then user, then system
-
-```ts
-const text = await readLocalFileFromRoots(name, {
-  roots: [path.join(projectDir, "templates"), path.join(homedir(), ".app/templates"), "/etc/app/templates"],
-  allowAbsolute: false,  // only resolve names, never absolute paths
-  maxBytes: 256 * 1024,
-});
-```
-
-### Validate a file:// URL at the API boundary
-
-```ts
-import { safeFileURLToPath, isWindowsNetworkPath } from "@openclaw/fs-safe/advanced";
-
-let abs: string;
-try {
-  abs = safeFileURLToPath(req.body.fileUrl);
-} catch {
-  return reply(400, "invalid file URL");
-}
-if (isWindowsNetworkPath(abs)) return reply(400, "network paths not allowed");
-```
-
-### Deny absolute, allow relative-only
-
-```ts
-const r = resolveLocalPathFromRootsSync(input, {
-  roots: ["/srv/workspace"],
-  allowAbsolute: false,
-  allowFileUrls: false,
-});
-```
+- `safeFileURLToPath(fileUrl)` parses a local file URL and refuses remote hosts
+  or paths that decode to Windows network paths.
+- `trySafeFileURLToPath(fileUrl)` returns `undefined` instead of throwing.
+- `isWindowsDriveLetterPath()` and `isWindowsNetworkPath()` classify Windows
+  absolute and network spellings.
+- `assertNoWindowsNetworkPath()` throws for a network path on Windows.
+- `basenameFromMediaSource()` extracts a best-effort filename from a URL, data
+  URI, or path.
+- `hasEncodedFileUrlSeparator()` detects percent-encoded slash or backslash
+  spellings.
 
 ## See also
 
-- [`root()`](root.md) — single-root variant of this multi-root setup.
-- [Path helpers](path.md) — `isPathInside`, `safeRealpathSync` for ad-hoc checks.
-- [`pathScope()`](path-scope.md) — single-root with `Result`-style returns.
+- [`root()`](root.md) — use when one trusted root should preserve individual
+  failure codes.
+- [Path helpers](path.md) — lexical and canonical containment primitives.
+- [`pathScope()`](path-scope.md) — result-shaped single-root validation.