@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

package/node_modules/@openclaw/fs-safe/docs/file-store.md

@@ -0,0 +1,258 @@
+# File store
+
+`fileStore` is exported from `@openclaw/fs-safe/store`. It is a managed wrapper around `root()` for the common "store files under a directory at known modes, prune old ones, hand back absolute paths" pattern. Useful for caches, ingest staging, generated artifacts, anywhere the consumer wants object-style access plus stream and copy primitives.
+
+```ts
+import {
+  fileStore,
+  type FileStore,
+  type FileStoreOptions,
+  type FileStoreWriteOptions,
+  type FileStorePruneOptions,
+} from "@openclaw/fs-safe/store";
+```
+
+## When to reach for it
+
+- You want a single directory holding files written by your code, with consistent mode bits and atomic placement.
+- You want a `FileStore.write(rel, data)` / `read(rel)` / `pruneExpired(...)` interface.
+- You want to feed a stream into the store with a byte cap.
+- You don't need the full `Root` surface (move, list, mkdir, …); the store can hand you a real `Root` via `.root()` when you do.
+
+## Factory: `fileStore(options)`
+
+```ts
+const cache = fileStore({
+  rootDir: "/var/cache/app",
+  mode: 0o600,        // file mode for writes (default 0o600)
+  dirMode: 0o700,     // mode for parent directories created on demand (default 0o700)
+  maxBytes: 64 * 1024 * 1024, // optional: refuse writes/reads larger than this
+  private: true,      // use secret-file atomic writes for private state
+});
+```
+
+Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
+
+Use `private: true` for credentials, auth profiles, tokens, and other private
+state. Private mode keeps the same `FileStore` shape but routes writes through
+the secret-file atomic path, refusing symlink parent components and re-asserting
+mode after rename.
+
+Returns a `FileStore`:
+
+```ts
+type FileStore = {
+  readonly rootDir: string;
+  path(relativePath: string): string;
+  root(): Promise<Root>;
+  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>;
+  read(rel, options?): Promise<ReadResult>;
+  readBytes(rel, options?): Promise<Buffer>;
+  readText(rel, options?): Promise<string>;
+  readTextIfExists(rel, options?): Promise<string | null>;
+  readJson<T = unknown>(rel, options?): Promise<T>;
+  readJsonIfExists<T = unknown>(rel, options?): Promise<T | null>;
+  writeText(rel, data: string | Uint8Array, options?): Promise<string>;
+  writeJson(rel, data: unknown, options?): Promise<string>;
+  json<T = unknown>(rel, options?): JsonStore<T>;
+  remove(rel): Promise<void>;
+  exists(rel): Promise<boolean>;
+  pruneExpired(options: FileStorePruneOptions): Promise<void>;
+};
+```
+
+`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. The same lexical policy applies
+to every keyed async and sync method, including reads, `exists`, `remove`,
+`path()`, and `json()` construction, with either `private: false` or `true`.
+Keys must use their exact canonical spelling; the store never trims, normalizes,
+or converts one caller-supplied key onto another:
+
+- Keys are nonempty NFC Unicode strings without surrounding whitespace or NUL.
+- Segments are separated by a single forward slash. Empty segments, repeated or
+  trailing slashes, and complete `.` or `..` segments are rejected, including
+  `./b`, `a/./b`, and `a/../b`.
+- Every backslash is rejected on every platform, including a literal POSIX
+  `a\b` filename. POSIX and Windows absolute, rooted, UNC, and extended paths
+  are rejected.
+- Windows drive-relative segments such as `C:name` or `C:` are rejected
+  anywhere in a key, including `a/C:name`.
+- No segment may end in an ASCII dot or space.
+
+Violations report `invalid-path` when key validation is reached. Ordinary nested
+keys, NFC Unicode such as `café/日本語.txt`, `.hidden`, `a..b`, and internal spaces
+such as `internal space/a b.txt` are accepted. Colons elsewhere, such as the
+timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid; filesystem
+success still depends on the platform and the underlying Root policies.
+
+Validation retains each method's operation order. Async reads, `exists`, and
+`remove` open the root first: if the root is missing, strict methods report
+`not-found` and `readTextIfExists` / `readJsonIfExists` return `null`, even for an
+invalid key. With an existing root, those same invalid keys report `invalid-path`.
+Private `copyIn` checks and reads its source before validating the destination
+key, and `writeJson` serializes its value before validating the key. Key rejection
+therefore does not imply that no filesystem access or serialization occurred.
+
+`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
+
+Every write goes through `writeSiblingTempFile` — temp + rename, mode applied to file and parent dir, both `fsync`'d.
+
+### `write(rel, data, options?)`
+
+```ts
+const path = await cache.write("entries/2026/05/05.json", JSON.stringify(entry));
+```
+
+Buffer or string. Returns the final absolute path. Throws `too-large` if `data.byteLength` exceeds `maxBytes`.
+
+### `writeText(rel, data, options?)` / `writeJson(rel, data, options?)`
+
+Convenience wrappers over `write`. `writeJson` pretty-prints with a trailing newline by default and accepts `{ trailingNewline: false }` when the exact bytes matter.
+
+### `json<T>(rel, options?)`
+
+Returns a typed single-file JSON state helper for a file under this store. It
+inherits the store's root, mode, max-size, and private-write policy, then adds
+`readOr`, `readRequired`, `update`, `updateOr`, and optional sidecar locking:
+
+```ts
+const state = cache.json<State>("state/settings.json", { lock: true });
+await state.updateOr(defaultState, (current) => ({ ...current, enabled: true }));
+```
+
+Use this when one JSON file owns one piece of state. `jsonStore({ filePath })`
+is the absolute-path convenience wrapper for the same primitive.
+
+### `writeStream(rel, stream, options?)`
+
+```ts
+import { Readable } from "node:stream";
+const path = await cache.writeStream("downloads/blob.bin", Readable.from(remoteFetch));
+```
+
+Streams into a sibling temp with a running byte budget. Aborts the source stream with `too-large` if `maxBytes` is exceeded mid-stream — partial writes are cleaned up.
+
+### `copyIn(rel, sourcePath, options?)`
+
+```ts
+const path = await cache.copyIn("ingest/upload.bin", "/tmp/upload.bin");
+```
+
+One-shot ingest from an absolute source path. Source is checked for symlink/non-regular before copy. Same mode rules as `write`.
+
+### `FileStoreWriteOptions`
+
+Per-call overrides for the store-level defaults:
+
+```ts
+type FileStoreWriteOptions = {
+  dirMode?: number;
+  mode?: number;
+  maxBytes?: number;
+  tempPrefix?: string;  // override the default "." + basename
+};
+```
+
+## Reads
+
+`open`, `read`, `readBytes`, `readText`, and `readJson` delegate to a fresh `Root` with `hardlinks: "reject"` and the store's `maxBytes`. Same return shapes as `Root`.
+Async and sync reads both report `not-file` when the key names a directory;
+stable hardlinks and symlinks retain `hardlink` and `symlink`. The `IfExists`
+methods return their nullish result only for `not-found`. Operational filesystem
+read failures use `read-failed` with the Node error retained in `cause`.
+
+## `remove(rel)` / `exists(rel)`
+
+Forward to the underlying `Root`. `remove` unlinks files and `rmdir`s empty directories; non-empty dirs throw `not-empty`.
+
+## `pruneExpired(options)`
+
+Walk the store and delete files older than `options.ttlMs`:
+
+```ts
+await cache.pruneExpired({
+  ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+  recursive: true,
+  pruneEmptyDirs: true,
+});
+```
+
+Options:
+
+```ts
+type FileStorePruneOptions = {
+  ttlMs: number;
+  recursive?: boolean;       // default false (top-level only)
+  maxDepth?: number;         // bound recursion explicitly
+  pruneEmptyDirs?: boolean;  // also remove dirs that became empty (only with recursive/maxDepth)
+};
+```
+
+Symlinks are skipped. The walk is best-effort — failures on individual entries don't abort the whole prune. Compares against `mtimeMs`.
+
+## Difference from `Root`
+
+| `FileStore` | `Root` |
+|---|---|
+| Object-style with mode+dirMode baked in. | Method-style boundary; mode is per-call or per-default. |
+| `writeStream` with built-in byte budget. | Manual via `openWritable()`. |
+| `writeText` / `writeJson` return the final absolute path. | `Root.write` / `writeJson` return void. |
+| `copyIn` returns the final absolute path. | `Root.copyIn` returns void. |
+| `pruneExpired` walks by `mtime`. | No prune helper. |
+| Reads delegate via `Root` internally. | The boundary itself. |
+
+If you need richer ops (move, list, append, mkdir), call `store.root()` to get a `Root` and use that.
+
+`FileStore` owns portable key identity; `Root` owns filesystem confinement.
+Existing-object Root lookups intentionally retain broader confined path
+compatibility, including in-root absolute paths and parent-segment spellings,
+and literal backslashes on POSIX. FileStore rejects those spellings even when
+Root could resolve them safely inside the directory. This key policy does not
+change Root's containment checks or the absolute-path `jsonStore({ filePath })`
+contract.
+
+## Common patterns
+
+### Cache with TTL prune
+
+```ts
+const cache = fileStore({ rootDir: "/var/cache/app", maxBytes: 16 * 1024 * 1024 });
+
+await cache.writeStream(`${id}.bin`, fetchStream(id));
+
+// Background prune every hour
+setInterval(() => cache.pruneExpired({ ttlMs: 24 * 60 * 60 * 1000 }), 60 * 60 * 1000);
+```
+
+### Ingest pipeline
+
+```ts
+const ingest = fileStore({ rootDir: "/srv/ingest", mode: 0o644 });
+
+for (const upload of uploads) {
+  const dest = await ingest.copyIn(`raw/${upload.id}`, upload.tempPath, {
+    maxBytes: 200 * 1024 * 1024,
+  });
+  await enqueueProcess(dest);
+}
+```
+
+### Drop down to `Root` for moves
+
+```ts
+const root = await store.root();
+await root.move(`pending/${id}`, `done/${id}`);
+```
+
+## See also
+
+- [`root()`](root.md) — the boundary `FileStore` is built on; reach for it when you need move/list/append.
+- [JSON store](json-store.md) — the JSON-state-file equivalent of this surface.
+- [Atomic writes](atomic.md) — `writeSiblingTempFile` is what every write goes through.
+- [Temp workspaces](temp.md) — private scratch directories backed by `FileStore`.

package/node_modules/@openclaw/fs-safe/docs/filename.md

@@ -0,0 +1,96 @@
+# Filenames
+
+`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/advanced";
+
+const safe = sanitizeUntrustedFileName(req.body.fileName, "upload");
+await fs.write(`uploads/${safe}`, body);
+```
+
+## Signature
+
+```ts
+function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;
+```
+
+## What it does
+
+In order:
+
+1. **Trim** whitespace. If the result is empty, return `fallbackName`.
+2. **Strip path components.** Apply `path.posix.basename` then `path.win32.basename` so neither `foo/bar.txt` nor `foo\bar.txt` survives — only the final segment remains.
+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. **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 removes traversal and
+the most obvious cross-platform device and character hazards, but it is not a
+complete portable-filename or uniqueness policy.
+
+## Examples
+
+```ts
+sanitizeUntrustedFileName("notes.txt", "untitled");        // "notes.txt"
+sanitizeUntrustedFileName("../../etc/passwd", "upload");   // "passwd"
+sanitizeUntrustedFileName("foo\\bar.png", "upload");       // "bar.png"
+sanitizeUntrustedFileName("a\u0000b\tc", "upload");       // "abc"
+sanitizeUntrustedFileName("   ", "fallback");              // "fallback"
+sanitizeUntrustedFileName(".", "fallback");                // "fallback"
+sanitizeUntrustedFileName("..", "fallback");               // "fallback"
+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:
+
+- Replace leading dots (so a name like `.config` stays hidden on POSIX systems).
+- 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.
+
+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/advanced";
+import { randomUUID } from "node:crypto";
+
+const base = sanitizeUntrustedFileName(req.body.fileName, "upload");
+const unique = `${randomUUID()}-${base}`;
+await fs.write(`uploads/${unique}`, body);
+```
+
+### Restrict to a known set of extensions
+
+```ts
+const safe = sanitizeUntrustedFileName(req.body.fileName, "upload");
+const ext = path.extname(safe).toLowerCase();
+if (![".png", ".jpg", ".webp"].includes(ext)) return reply(400, "unsupported extension");
+```
+
+### Sanitize, then write through a `Root`
+
+```ts
+const safe = sanitizeUntrustedFileName(req.body.fileName, "upload");
+await fs.write(`uploads/${safe}`, body); // fs is a Root() handle; rejects traversal too
+```
+
+## See also
+
+- [Install path helpers](install-path.md) — `safeDirName`, `safePathSegmentHashed` for directory-segment sanitization.
+- [`root()`](root.md) — the boundary you'll write into after sanitizing.

package/node_modules/@openclaw/fs-safe/docs/index.md

@@ -0,0 +1,84 @@
+---
+title: Overview
+permalink: /
+description: "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths."
+---
+
+# fs-safe
+
+Trusted Node.js code that has to touch caller-controlled paths inside a directory it owns gets one boundary it can rely on. `root()` returns a capability-style handle that resolves every relative path against a real directory, refuses anything that escapes it, pins the file you opened, and verifies the write landed where you intended.
+
+Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. `root()` is the product; everything else in this doc set — JSON stores, atomic writes, secret files, archive extraction, temp workspaces — is supporting cast for the same boundary.
+
+## Why
+
+`path.resolve(root, input).startsWith(root)` validates a string. It does not pin the file you opened, defend against a symlink retarget between check and use, reject hardlinked aliases, or verify that a write landed where you intended after a rename. `fs-safe` does those things, packaged so every call site picks up the same defense without re-implementing it.
+
+This is a **library-level guardrail**, not OS-level isolation. It does not replace containers, seccomp, AppArmor, or filesystem permissions. It is for code that already runs with the privileges of its workspace and wants to stop trivial path tricks from escaping it. Typical fits: agent runtimes, plugin systems, upload extraction, local workspaces, CLIs — anywhere trusted code touches untrusted relative path names.
+
+## Hello world
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const fs = await root("/safe/workspace", {
+  hardlinks: "reject",
+  symlinks: "reject",
+  mkdir: true,
+});
+
+await fs.write("notes/today.txt", "hello\n");
+const text = await fs.readText("notes/today.txt");
+const parsed = await fs.readJson<{ users: string[] }>("config.json");
+await fs.copyIn("uploads/upload.png", "/tmp/upload.png");
+await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true });
+await fs.remove("notes/archive/today.txt");
+```
+
+## Pick your path
+
+- **First time?** [Install](install.md), then walk through the [Quickstart](quickstart.md). Five minutes from `pnpm add` to a working root.
+- **Upgrading from 0.4?** Follow [Migrating to 0.5](migrating-to-0.5.md) in order, including the archive clamp-default audit.
+- **Upgrading from 0.5?** Follow [Migrating to 0.6](migrating-to-0.6.md) to adopt platform-native optional packages.
+- **Designing a workspace feature.** Read the [Security model](security-model.md) before you trust the boundary, the [native helper policy](native-helper.md) before you pick deployment defaults, and the [Errors](errors.md) reference so you know what to catch.
+- **Replacing ad-hoc atomic writes.** Jump to [Atomic writes](atomic.md) or, for keyed JSON state, [JSON files](json.md).
+- **Extracting an upload.** Start at [Archive extraction](archive.md) — handles ZIP and TAR with traversal, link, count, and byte limits.
+- **Running an agent in a sandbox.** [Private temp workspaces](temp.md) plus [secret files](secret-file.md) cover the common scratch-and-credentials shape.
+- **Looking up a name.** Use the [reference](errors.md) section in the sidebar — every public function has a page.
+
+## What you get
+
+| Surface | Use it for |
+|---|---|
+| [`root()`](root.md) | One boundary for read/write/move/remove and bounded recursive walking inside a trusted directory. |
+| [`@openclaw/fs-safe/config`](config.md) | Process-global native helper and lock-option defaults. |
+| [Native helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for platform-native primitives. |
+| [Native architecture](native.md) | Understand the thin syscall layer, beneath model, platform mechanisms, and fallback boundary. |
+| [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
+| [`@openclaw/fs-safe/durability`](durability.md) | Pinned directory identities, durable creation, exclusive publication, streaming SHA-256, provenance receipts, and sync-failure policy. |
+| [`writeExternalFileWithinRoot`](output.md) | Stage external-library file output in private temp storage, then finalize under a root. |
+| [`writeJson` / `readJson*`](json.md) | JSON state files with strict and lenient read variants. |
+| [`@openclaw/fs-safe/store`](store.md) | Overview of `fileStore`, `fileStoreSync`, and `jsonStore`. |
+| [`jsonStore`](json-store.md) | Single JSON state file with explicit fallback, atomic writes, and optional locking. |
+| [`fileStore`](file-store.md) | Managed multi-file/blob store with modes, stream writes, copy-in, pruning, and private mode. |
+| [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
+| [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
+| [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
+| [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
+| [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |
+| [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
+| [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. |
+| [Migrating to 0.5](migrating-to-0.5.md) | End-to-end checklist for Python removal and 0.4 API behavior changes. |
+| [Migrating to 0.6](migrating-to-0.6.md) | Installer-policy checklist for the platform-native package split. |
+
+## Status
+
+Currently `0.x` — APIs are stable in shape but may be tightened before `1.0`. The [CHANGELOG](https://github.com/openclaw/fs-safe/blob/main/CHANGELOG.md) tracks visible changes. Issues and PRs at the [GitHub repo](https://github.com/openclaw/fs-safe).
+
+Released under the [MIT license](https://github.com/openclaw/fs-safe/blob/main/LICENSE).

package/node_modules/@openclaw/fs-safe/docs/install-path.md

@@ -0,0 +1,170 @@
+# Install paths
+
+Helpers for code that creates per-name install directories under a trusted base — typical for plugins, packages, snapshots, anywhere you want `<base>/<safe-name>/`. The combination of [`resolveSafeInstallDir`](#resolvesafeinstalldir) and [`assertCanonicalPathWithinBase`](#assertcanonicalpathwithinbase) gives you "compute the install path safely, then re-verify after creation."
+
+```ts
+import {
+  assertCanonicalPathWithinBase,
+  resolveSafeInstallDir,
+  safeDirName,
+  safePathSegmentHashed,
+} from "@openclaw/fs-safe/advanced";
+```
+
+## `resolveSafeInstallDir`
+
+```ts
+function resolveSafeInstallDir(params: {
+  baseDir: string;
+  id: string;
+  invalidNameMessage: string;
+  nameEncoder?: (id: string) => string;   // default safeDirName
+}): { ok: true; path: string } | { ok: false; error: string };
+```
+
+Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`.
+
+```ts
+const r = resolveSafeInstallDir({
+  baseDir: "/srv/plugins",
+  id: "@scope/my-plugin",
+  invalidNameMessage: "invalid plugin name",
+});
+if (!r.ok) return reply(400, r.error);
+
+await fs.mkdir(r.path, { recursive: true });
+```
+
+For ids whose default-sanitized form might collide (e.g. `"foo/bar"` and `"foo\\bar"` both map to `"foo__bar"`), pass `nameEncoder: safePathSegmentHashed` to append a content hash:
+
+```ts
+const r = resolveSafeInstallDir({
+  baseDir: "/srv/plugins",
+  id: untrustedId,
+  invalidNameMessage: "invalid plugin name",
+  nameEncoder: safePathSegmentHashed,
+});
+```
+
+The helper does **not** create the directory — it returns the path. Pair with `fs.mkdir`, [`Root.mkdir`](root.md), or `assertCanonicalPathWithinBase` before/after creation as needed.
+
+## `assertCanonicalPathWithinBase`
+
+Async. Verifies that a candidate absolute path's canonical real path stays inside the base. Useful as a post-`mkdir` check, or when you have an existing path you didn't compute yourself.
+
+```ts
+function assertCanonicalPathWithinBase(params: {
+  baseDir: string;
+  candidatePath: string;
+  boundaryLabel: string;
+}): Promise<void>;
+```
+
+Throws if the candidate resolves outside `baseDir` after `realpath`. The `boundaryLabel` is included in the error message ("Invalid path: must stay within {boundaryLabel}").
+
+```ts
+await assertCanonicalPathWithinBase({
+  baseDir: "/srv/plugins",
+  candidatePath: "/srv/plugins/my-plugin",
+  boundaryLabel: "plugin install dir",
+});
+```
+
+If the candidate does not exist, the helper validates the parent directory instead — useful for "the directory I'm about to create" semantics.
+
+## Segment sanitizers
+
+### `safeDirName`
+
+Returns a directory-safe segment derived from `input` by replacing `/` and `\` with `__`. Trims whitespace; returns an empty string if the input was only whitespace.
+
+```ts
+safeDirName("@scope/my-plugin");       // "@scope__my-plugin"
+safeDirName("../../etc");              // "..__..__etc"
+safeDirName("plugin-v1");              // "plugin-v1"
+safeDirName("");                       // ""
+```
+
+`safeDirName` does *not* try to be exhaustive about Windows-reserved names or special characters. It is purely a separator-stripping pass — `resolveSafeInstallDir` adds the boundary check on top so an `"../../etc"` input cannot escape `baseDir`.
+
+For stricter sanitization, use `safePathSegmentHashed`.
+
+### `safePathSegmentHashed`
+
+Returns a directory-safe segment **plus** a short content hash when sanitization changed the input or when the safe form is too long. Use this when input collisions matter:
+
+```ts
+safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
+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 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
+
+### Install a plugin
+
+```ts
+import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashed } from "@openclaw/fs-safe/advanced";
+import { extractArchive } from "@openclaw/fs-safe/archive";
+import fs from "node:fs/promises";
+
+const r = resolveSafeInstallDir({
+  baseDir: "/srv/plugins",
+  id: untrustedName,
+  invalidNameMessage: "invalid plugin name",
+  nameEncoder: safePathSegmentHashed,
+});
+if (!r.ok) return reply(400, r.error);
+
+await fs.mkdir(r.path, { recursive: true, mode: 0o755 });
+await assertCanonicalPathWithinBase({
+  baseDir: "/srv/plugins",
+  candidatePath: r.path,
+  boundaryLabel: "plugin install dir",
+});
+
+await extractArchive({
+  archivePath: pluginZip,
+  destDir: r.path,
+  kind: "zip",
+  timeoutMs: 30_000,
+});
+```
+
+### Per-version snapshot directories
+
+```ts
+const snap = resolveSafeInstallDir({
+  baseDir: "/srv/snapshots",
+  id: `${runId}-${version}`,
+  invalidNameMessage: "invalid snapshot id",
+});
+if (!snap.ok) throw new Error(snap.error);
+await fs.mkdir(snap.path, { recursive: true });
+```
+
+### Reject and log on bad input
+
+```ts
+const r = resolveSafeInstallDir({ baseDir, id, invalidNameMessage: "bad name" });
+if (!r.ok) {
+  logger.warn({ id, base: baseDir, error: r.error }, "rejected install attempt");
+  return reply(400, r.error);
+}
+```
+
+## See also
+
+- [`root()`](root.md) — when the install dir becomes a root for further writes.
+- [Filenames](filename.md) — `sanitizeUntrustedFileName` for file-name (not directory-name) sanitization.
+- [Archive extraction](archive.md) — extract into the install dir computed by these helpers.