@openclaw/fs-safe 0.1.1 → 0.1.2

package/docs/install.md

@@ -0,0 +1,150 @@
+# 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.
+
+## Package managers
+
+```bash
+pnpm add @openclaw/fs-safe
+```
+
+```bash
+npm install @openclaw/fs-safe
+```
+
+```bash
+yarn add @openclaw/fs-safe
+```
+
+```bash
+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.
+
+Verify the runtime:
+
+```bash
+node --version
+# v20.11.0 or newer
+```
+
+## TypeScript
+
+Types ship with the package — no `@types/openclaw__fs-safe` needed. The `exports` map in `package.json` provides typed entries for every subpath:
+
+```ts
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import { writeJson } from "@openclaw/fs-safe/json";
+import { extractArchive } from "@openclaw/fs-safe/archive";
+```
+
+A working `tsconfig.json` for consumers:
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "node18",
+    "moduleResolution": "node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Subpath exports
+
+Use the main entry for the common surface, or the focused subpaths when you want a leaner import or to depend on a narrower contract:
+
+| Subpath | Contents |
+|---|---|
+| `@openclaw/fs-safe` | Small common surface: `root`, root types, and errors. |
+| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, related types. |
+| `@openclaw/fs-safe/config` | Process-global Python helper configuration. |
+| `@openclaw/fs-safe/path` | `isPathInside`, `safeRealpathSync`, `isWithinDir`, error helpers. |
+| `@openclaw/fs-safe/json` | `tryReadJson`, `readJson`, `readJsonIfExists`, `writeJson`, sync variants. |
+| `@openclaw/fs-safe/store` | `fileStore()`, `fileStoreSync()`, and `jsonStore<T>()`. |
+| `@openclaw/fs-safe/secret` | Secret file read/write helpers. |
+| `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `writeTextAtomic`, `replaceDirectoryAtomic`, `movePathWithCopyFallback`. |
+| `@openclaw/fs-safe/temp` | `tempWorkspace`, `withTempWorkspace`, sync variants, `resolveSecureTempRoot`. |
+| `@openclaw/fs-safe/secure-file` | `readSecureFile` for pinned absolute file reads with permissions checks. |
+| `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types. |
+| `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection/remediation helpers. |
+| `@openclaw/fs-safe/walk` | `walkDirectory`, `walkDirectorySync`, related types. Budget-bounded, not root-bounded. |
+| `@openclaw/fs-safe/archive` | `extractArchive`, `resolveArchiveKind`, limits, preflight helpers. |
+| `@openclaw/fs-safe/advanced` | Lower-level composition helpers: path scopes, root-file open, install paths, local-root readers, temp-file targets, sibling-temp writes, regular-file helpers, `pathExists`, `withTimeout`, and related advanced types. This surface is less stable than the focused public subpaths. |
+| `@openclaw/fs-safe/errors` | `FsSafeError`, `FsSafeErrorCode`. |
+| `@openclaw/fs-safe/types` | Shared types: `DirEntry`, `PathStat`, `BasePathOptions`, … |
+| `@openclaw/fs-safe/test-hooks` | Test-only hooks for injecting races. Active under `NODE_ENV=test`. |
+
+## Runtime dependencies
+
+`@openclaw/fs-safe` lists `jszip` and `tar` as optional dependencies for [archive extraction](archive.md). They are loaded lazily and only required when ZIP/TAR helpers run. Installs that omit optional dependencies can still import and use every non-archive subpath; archive calls fail with a clear missing-optional-dependency message.
+
+There are no peer dependencies and no native build step.
+
+## Python helper policy
+
+On POSIX, `root()` uses one persistent Python helper process for the
+fd-relative operations Node does not expose cleanly. The default is `auto`: use
+the helper when it starts, fall back to Node-only behavior when it is disabled
+or unavailable.
+
+```ts
+import { configureFsSafePython } from "@openclaw/fs-safe/config";
+
+configureFsSafePython({ mode: "auto" });    // default
+configureFsSafePython({ mode: "off" });     // never spawn Python
+configureFsSafePython({ mode: "require" }); // fail closed if unavailable
+```
+
+Environment variables are read at runtime:
+
+```bash
+FS_SAFE_PYTHON_MODE=off      # auto | off | require
+FS_SAFE_PYTHON=/usr/bin/python3
+```
+
+OpenClaw compatibility aliases are also accepted:
+`OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`,
+`OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`.
+
+Disabling Python keeps the public API working, but downgrades POSIX mutation
+hardening from fd-relative syscalls to Node path operations guarded by lexical
+and canonical checks plus identity verification. Use `require` for
+security-sensitive deployments where that downgrade should be a startup/runtime
+failure instead of a fallback. The full tradeoff is documented in
+[Python helper policy](python-helper.md).
+
+## Verify the install
+
+```ts
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import os from "node:os";
+import path from "node:path";
+
+const dir = path.join(os.tmpdir(), "fs-safe-smoke");
+await import("node:fs/promises").then((fs) => fs.mkdir(dir, { recursive: true }));
+
+const fs = await root(dir);
+await fs.write("hello.txt", "ok\n");
+console.log(await fs.readText("hello.txt"));
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (err instanceof FsSafeError) console.log("blocked:", err.code);
+}
+```
+
+If the script prints `ok` followed by `blocked: outside-workspace`, your install is healthy.
+
+## Next
+
+- [Quickstart](quickstart.md) — write, read, atomic, temp.
+- [Security model](security-model.md) — what the boundary defends against.
+- [Errors](errors.md) — the closed code union you'll be catching.

package/docs/json-store.md

@@ -0,0 +1,200 @@
+# JSON store
+
+`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the absolute-path
+convenience wrapper for `fileStore(...).json(...)`: a small read-modify-write
+handle around a single JSON file. It bakes in atomic writes, explicit fallback
+reads, and optional cross-process locking via
+[`acquireFileLock`](sidecar-lock.md).
+
+```ts
+import { jsonStore } from "@openclaw/fs-safe/store";
+
+const settings = jsonStore<{ theme: "light" | "dark"; volume: number }>({
+  filePath: "/var/lib/app/settings.json",
+});
+
+const current = await settings.readOr({ theme: "dark", volume: 0.7 });
+await settings.write({ ...current, volume: 1 });
+await settings.updateOr({ theme: "dark", volume: 0.7 }, (prev) => ({ ...prev, theme: "light" }));
+```
+
+If you already have a store/root context, prefer binding the JSON file from that
+store:
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const files = fileStore({ rootDir: "/var/lib/app", private: true });
+const settings = files.json<Settings>("settings.json", { lock: true });
+```
+
+## When to reach for it
+
+- You have a single JSON state file and want `read / readOr / readRequired / write / update` semantics.
+- You want every write atomic at file mode `0o600` and parents at `0o700` by default.
+- You want optional cross-process locking with one boolean.
+
+For ad-hoc read/write of multiple JSON files, use the standalone helpers in
+[`json`](json.md). For object-style storage of many files at known modes, use
+[`fileStore`](file-store.md) and bind JSON files with `store.json(rel)`.
+
+## Factory: `jsonStore<T>(options)`
+
+```ts
+type JsonStoreOptions<T> = {
+  filePath: string;
+  dirMode?: number;                                // default 0o700
+  mode?: number;                                   // default 0o600
+  trailingNewline?: boolean;                       // default true
+  lock?: boolean | JsonStoreLockOptions;           // false / undefined = no lock
+};
+
+type JsonStoreLockOptions = {
+  staleMs?: number;     // default 30_000
+  timeoutMs?: number;   // default 30_000
+  retry?: FileLockRetryOptions;
+  managerKey?: string;  // default `fs-safe.json-store:<filePath>`
+};
+
+type JsonStore<T> = {
+  readonly filePath: string;
+  read(): Promise<T | undefined>;
+  readOr(fallback: T): Promise<T>;
+  readRequired(): Promise<T>;
+  write(value: T): Promise<void>;
+  update(run: (current: T | undefined) => T | Promise<T>): Promise<T>;
+  updateOr(fallback: T, run: (current: T) => T | Promise<T>): Promise<T>;
+};
+```
+
+`jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
+`fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
+
+The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
+
+## `read()`
+
+Returns the parsed contents, or `undefined` if the file does not exist. Invalid JSON throws (via [`readJsonIfExists`](json.md)).
+
+```ts
+const state = await store.read();
+```
+
+## `readOr(fallback)`
+
+Returns the parsed contents or the per-call fallback. Object fallbacks are cloned so callers can safely mutate the returned value:
+
+```ts
+const state = await store.readOr(defaultState);
+```
+
+## `readRequired()`
+
+Strict disk read. Throws when the file is missing or invalid:
+
+```ts
+const state = await store.readRequired();
+```
+
+## `write(value)`
+
+Atomic JSON write at `mode` (default `0o600`), creating parent dirs at `dirMode` (default `0o700`) if needed. When `lock: true` is set, takes the sidecar lock for the duration of the write.
+
+```ts
+await store.write({ ...state, lastSeen: Date.now() });
+```
+
+## `update(run)`
+
+Read, transform, write — under the lock if locking is enabled. Returns the new value:
+
+```ts
+const next = await store.update((prev) => ({ count: (prev?.count ?? 0) + 1 }));
+```
+
+`run` is async-friendly. The whole `read → run → write` sequence runs inside one `withLock` call, so concurrent updaters from different processes serialize cleanly.
+
+Use `update(run)` when missing state is part of your model. Use `updateOr(fallback, run)` when the missing-file case should start from a concrete value and you want to merge into defaults:
+
+```ts
+const next = await store.updateOr({ count: 0 }, (prev) => ({ count: prev.count + 1 }));
+```
+
+## Locking
+
+Set `lock: true` for default behavior, or pass an options object to tune:
+
+```ts
+const counter = jsonStore<{ count: number }>({
+  filePath: "/var/lib/app/counter.json",
+  lock: {
+    staleMs: 60_000,
+    timeoutMs: 10_000,
+    retry: { retries: 30, minTimeout: 100, maxTimeout: 5_000, randomize: true },
+  },
+});
+```
+
+When `lock` is falsy, `read` / `write` / `update` are unlocked. The `update` shape is still useful — it gives you a single function for the read-modify-write pattern — but it offers no concurrency guarantees if other processes also write to the file.
+
+The default `managerKey` namespaces the in-process `FileLockManager` per absolute file path, so two `jsonStore` calls on the same file share lock state automatically.
+
+## Common patterns
+
+### Per-feature settings file
+
+```ts
+type Settings = { theme: "light" | "dark"; muted: boolean };
+
+const settings = jsonStore<Settings>({
+  filePath: path.join(homedir(), ".myapp/settings.json"),
+});
+
+// Read on boot
+applySettings(await settings.readOr({ theme: "dark", muted: false }));
+
+// Toggle on UI action
+await settings.update((prev) => {
+  const current = prev ?? { theme: "dark", muted: false };
+  return { ...current, muted: !current.muted };
+});
+```
+
+### Cross-process counter
+
+```ts
+const counter = jsonStore<{ count: number }>({
+  filePath: "/var/lib/app/counter.json",
+  lock: true,
+});
+
+const { count } = await counter.updateOr({ count: 0 }, (prev) => ({ count: prev.count + 1 }));
+console.log("now at", count);
+```
+
+### Migration on boot
+
+```ts
+const config = jsonStore<Config>({ filePath });
+const current = await config.readOr(defaultConfig);
+if (current.version !== CURRENT_VERSION) {
+  await config.write(migrate(current));
+}
+```
+
+## Difference from raw `writeJson` / `readJsonIfExists`
+
+| `jsonStore` | Raw helpers |
+|---|---|
+| Read-modify-write in one call (`update`). | Compose `readJsonIfExists` + `writeJson` yourself. |
+| Optional cross-process lock with one flag. | Manage `withFileLock` yourself. |
+| Explicit `readOr` / `updateOr` fallbacks. | Caller handles `null` and clones. |
+| Mode/dirMode locked per store. | Per-call. |
+
+`jsonStore` is the right shape when one file owns one piece of state and many call sites read or update it. For one-off writes, the raw helpers are leaner.
+
+## See also
+
+- [JSON files](json.md) — the standalone helpers `jsonStore` is built on.
+- [File lock](sidecar-lock.md) — the cross-process lock used when `lock: true`.
+- [File store](file-store.md) — the multi-file equivalent of this surface.

package/docs/json.md

@@ -0,0 +1,158 @@
+# JSON files
+
+`@openclaw/fs-safe/json` is the standalone JSON surface: strict and lenient read variants plus atomic JSON writes.
+
+```ts
+import {
+  tryReadJson,
+  readJson,
+  readJsonIfExists,
+  readJsonSync,
+  tryReadJsonSync,
+  writeJson,
+  writeJsonSync,
+  JsonFileReadError,
+} from "@openclaw/fs-safe/json";
+```
+
+## Three reads, three failure shapes
+
+Same input, three distinct contracts — pick the one whose error story matches your call site:
+
+```ts
+await readJson<T>("./manifest.json");      // throws JsonFileReadError on missing or invalid
+await readJsonIfExists<T>("./cache.json"); // returns null on missing; throws on invalid
+await tryReadJson<T>("./optional.json");   // returns null on missing or invalid
+```
+
+| Helper | Missing file | Invalid JSON |
+|---|---|---|
+| `readJson` | throws | throws |
+| `readJsonIfExists` | `null` | throws |
+| `tryReadJson` | `null` | `null` |
+
+Use `readJson` when missing-or-malformed is a programmer error you want to surface immediately. Use `readJsonIfExists` when "file not there" is normal but malformed bytes should still page someone. Use `tryReadJson` when neither outcome should crash the caller.
+
+`JsonFileReadError` carries `cause` so you can inspect whether the underlying failure was an `ENOENT`, a `SyntaxError`, or something else.
+
+## Reading
+
+### `readJson<T>(filePath)`
+
+Async strict reader. Throws `JsonFileReadError` on missing or invalid input. The cast is unchecked — validate the shape with your own schema (zod, valibot, …) if it came from an untrusted source.
+
+```ts
+const manifest = await readJson<Manifest>("./manifest.json");
+```
+
+### `readJsonIfExists<T>(filePath)`
+
+Async semi-lenient reader. Returns `null` if the file is missing; throws `JsonFileReadError` if the file exists but cannot be parsed.
+
+```ts
+const cache = (await readJsonIfExists<Cache>("./cache.json")) ?? freshCache();
+```
+
+### `tryReadJson<T>(filePath)`
+
+Async lenient reader. Returns `null` for any failure (missing, unreadable, invalid). The "no fuss" sibling.
+
+```ts
+const optional = (await tryReadJson<Settings>("./settings.json")) ?? defaults;
+```
+
+### `readJsonSync<T>(filePath)`
+
+Synchronous strict reader. Throws `JsonFileReadError` on missing or invalid input, matching the async `readJson` contract.
+
+### `tryReadJsonSync<T>(pathname)`
+
+Synchronous, generic, lenient. Returns `T | null`. Useful in boot paths where you want a typed result without async.
+
+## Writing
+
+### `writeJson(filePath, value, options?)`
+
+Async atomic JSON write. `JSON.stringify(value, null, 2)` + sibling-temp + rename. Defaults to file mode `0o600`.
+
+```ts
+await writeJson("./state.json", state, { trailingNewline: true });
+```
+
+Options:
+
+```ts
+type WriteJsonOptions = {
+  mode?: number;             // file mode (default 0o600)
+  dirMode?: number;          // mode for parent dirs created on demand
+  trailingNewline?: boolean; // append "\n" if missing (default false)
+};
+```
+
+### `writeJsonSync(pathname, data)`
+
+Synchronous variant. Convenience wrapper that uses the sync atomic-write path with sensible defaults.
+
+```ts
+writeJsonSync("./prefs.json", { theme: "dark" });
+```
+
+For atomic text writes, use [`writeTextAtomic`](atomic.md) from `@openclaw/fs-safe/atomic`. For in-process serialization, use `createAsyncLock` from the advanced surface, or prefer [`jsonStore`](json-store.md) when you want a JSON-specific read-modify-write helper.
+
+## Common patterns
+
+### Read-modify-write
+
+```ts
+const state = (await readJsonIfExists<State>("./state.json")) ?? initialState();
+state.lastRun = Date.now();
+await writeJson("./state.json", state, { mode: 0o600, dirMode: 0o700 });
+```
+
+### Atomic with secure mode
+
+For credentials or other sensitive JSON, write at mode `0o600`:
+
+```ts
+await writeJson("./auth.json", token, { mode: 0o600, dirMode: 0o700 });
+```
+
+For higher-assurance secrets, prefer the dedicated [secret-file helpers](secret-file.md) — they create the parent directory at `0o700` if missing.
+
+### Strict load on boot
+
+```ts
+let manifest: Manifest;
+try {
+  manifest = await readJson<Manifest>("./manifest.json");
+} catch (err) {
+  if (err instanceof JsonFileReadError) {
+    console.error("manifest unreadable:", err.cause);
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+### Concurrent readers, single writer
+
+```ts
+const state = await readJsonIfExists<State>("./state.json");
+// missing returns null; malformed JSON still throws
+```
+
+## Error reference
+
+| Throw / return | When |
+|---|---|
+| `null` (lenient reads) | File missing or contents are not valid JSON. |
+| `JsonFileReadError` | `readJson` or `readJsonIfExists` saw unreadable or invalid input. Inspect `cause`. |
+| Native `NodeJS.ErrnoException` | Lower-level fs errors not wrapped. |
+
+## See also
+
+- [JSON store](json-store.md) — a single-file state wrapper with explicit per-call fallback (`readOr` / `updateOr`) and optional sidecar locking.
+- [Atomic writes](atomic.md) — lower-level sibling-temp replacement helpers.
+- [Secret files](secret-file.md) — JSON-or-text writes with mode 0600 in mode 0700 dirs.
+- [Private file-store mode](private-file-store.md) — root-bounded JSON+text state stores.
+- [File lock](sidecar-lock.md) — cross-process coordination.

package/docs/local-roots.md

@@ -0,0 +1,164 @@
+# 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."
+
+```ts
+import {
+  readLocalFileFromRoots,
+  resolveLocalPathFromRootsSync,
+} from "@openclaw/fs-safe/advanced";
+```
+
+## Shape of a "roots input"
+
+Both helpers take roots as either an array of strings or a `LocalRootsInputOptions` record. Each root is an absolute path the caller already trusts:
+
+```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)
+};
+```
+
+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)`
+
+Synchronous resolution. Returns:
+
+```ts
+type LocalRootsPathResult =
+  | { ok: true; absolutePath: string; rootDir: string; relativePath: string }
+  | { ok: false; reason: "outside-roots" | "invalid-input" };
+```
+
+```ts
+import { resolveLocalPathFromRootsSync } from "@openclaw/fs-safe/advanced";
+
+const r = resolveLocalPathFromRootsSync("photo.jpg", {
+  roots: ["/srv/uploads", "/srv/cache"],
+});
+
+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
+```
+
+### 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.
+
+## `readLocalFileFromRoots(input, 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.
+
+```ts
+type LocalRootsReadResult = ReadResult & {
+  rootDir: string;
+  relativePath: string;
+};
+
+const r = await readLocalFileFromRoots("photo.jpg", {
+  roots: ["/srv/uploads", "/srv/cache"],
+  maxBytes: 8 * 1024 * 1024,
+});
+if (!r) return reply(404);
+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.
+
+## `local-file-access` 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:
+
+```ts
+import {
+  assertNoWindowsNetworkPath,
+  basenameFromMediaSource,
+  hasEncodedFileUrlSeparator,
+  isWindowsDriveLetterPath,
+  isWindowsNetworkPath,
+  safeFileURLToPath,
+  trySafeFileURLToPath,
+} 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,
+});
+```
+
+## 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.