@openclaw/fs-safe 0.1.0 → 0.1.2

package/docs/errors.md

@@ -0,0 +1,154 @@
+# Errors
+
+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.
+
+```ts
+import { FsSafeError, type FsSafeErrorCode } from "@openclaw/fs-safe";
+```
+
+## Shape
+
+```ts
+class FsSafeError extends Error {
+  readonly name: "FsSafeError";
+  readonly code: FsSafeErrorCode;
+  readonly category: "policy" | "operational";
+
+  constructor(code: FsSafeErrorCode, message: string, options?: { cause?: unknown });
+}
+```
+
+`cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
+
+`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.
+
+## Code union
+
+```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";
+```
+
+## Code reference
+
+| Code | When it fires | Common causes |
+|---|---|---|
+| `already-exists` | `create()`, `createJson()`, `move({ overwrite: false })`. | Target file or directory already at the destination. |
+| `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
+| `helper-failed` | Internal POSIX helper failed after startup. | Inspect `cause`; retrying may be unsafe if the operation may have partially completed. |
+| `helper-unavailable` | Persistent Python helper was disabled or could not be spawned. | `FS_SAFE_PYTHON_MODE=off`, Python missing in PATH, restricted sandbox. `auto` falls back where possible; `require` fails closed. |
+| `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. |
+| `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. |
+| `not-owned` | A secure file owner check failed. | File is owned by another UID. |
+| `not-removable` | `remove()` couldn't `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit. |
+| `outside-workspace` | Path resolves outside the configured root. | `..` traversal; absolute path outside the root; symlink resolved out. |
+| `path-alias` | A path alias check failed (e.g. canonical-real-path moved out of the root). | Symlink resolution lands outside the root. |
+| `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. |
+| `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` | Read exceeded `maxBytes`. | Caller gave a too-permissive file or didn't size-cap correctly. |
+| `unsupported-platform` | The requested operation is not supported on the current platform. | E.g. POSIX-only helper invoked on Windows. |
+
+## Branching
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (!(err instanceof FsSafeError)) throw err;
+  switch (err.code) {
+    case "outside-workspace":
+      return reply(400, "path escapes workspace");
+    case "already-exists":
+      return reply(409, "exists");
+    case "too-large":
+      return reply(413, "too large");
+    case "not-found":
+      return reply(404, "missing");
+    case "symlink":
+    case "hardlink":
+    case "path-mismatch":
+    case "path-alias":
+      return reply(400, "unsafe path");
+    default:
+      throw err;
+  }
+}
+```
+
+The compiler will flag missing cases when you exhaust the union — keep your switch up-to-date as the library adds new codes.
+
+## 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:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await op();
+} catch (err) {
+  if (err instanceof FsSafeError) {
+    handleFsSafe(err);
+    return;
+  }
+  if ((err as NodeJS.ErrnoException).code === "EACCES") {
+    handleAccess();
+    return;
+  }
+  throw err;
+}
+```
+
+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.
+
+## Specialty errors
+
+A handful of helpers throw their own typed errors instead of `FsSafeError`:
+
+- `JsonFileReadError` — thrown by [`readJson`](json.md). Carries `cause` so you can distinguish missing (`ENOENT`) from invalid (`SyntaxError`).
+- `ArchiveLimitError` — thrown by [`extractArchive`](archive.md) when an archive size, entry count, or extracted-byte budget is exceeded. The `code` field uses `ARCHIVE_LIMIT_ERROR_CODE` constants (e.g. `"ARCHIVE_SIZE_EXCEEDS_LIMIT"`).
+- `ArchiveSecurityError` — thrown by extraction when an entry path violates safety rules (traversal, drive prefix, blocked link type). The `code` field uses `ArchiveSecurityErrorCode` values.
+
+These are exported from their respective subpaths.
+
+## Why `FsSafeError`?
+
+Two reasons it isn't a richer hierarchy of subclasses:
+
+1. **Switch on `code`, don't `instanceof` a tree.** `code` is a closed string union the TypeScript compiler can exhaust-check. Subclasses make `instanceof` ladders that drift over time.
+2. **One catch handler.** Library callers often want a single "is this an `fs-safe` failure?" gate before deciding what to do — `instanceof FsSafeError` plus a switch is the cleanest expression of that.
+
+## See also
+
+- [`root()`](root.md) — every method documents the codes it can throw.
+- [Reading](reading.md) — read-path codes.
+- [Writing](writing.md) — write-path codes.
+- [Archive extraction](archive.md) — `ArchiveLimitError` and `ArchiveSecurityError`.

package/docs/file-store.md

@@ -0,0 +1,213 @@
+# 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
+});
+```
+
+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 | Buffer, 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.
+
+`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`.
+
+## `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.
+
+## 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/docs/index.md

@@ -0,0 +1,76 @@
+---
+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.
+- **Designing a workspace feature.** Read the [Security model](security-model.md) before you trust the boundary, the [Python helper policy](python-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 inside a trusted directory. |
+| [`@openclaw/fs-safe/config`](config.md) | Process-global Python helper configuration (`configureFsSafePython`, `getFsSafePythonConfig`). |
+| [Python helper policy](python-helper.md) | Choose `auto`, `off`, or `require` for POSIX fd-relative hardening. |
+| [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
+| [`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`](walk.md) | Budget-bounded recursive directory scan with symlink policy and filters. |
+| [`extractArchive`](archive.md) | ZIP/TAR extraction with size, count, link, and traversal limits. |
+| [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
+| [Permissions](permissions.md) | POSIX mode and Windows ACL inspection/remediation helpers. |
+| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and stale-lock recovery. |
+| [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
+| [`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. |
+
+## 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/docs/install-path.md

@@ -0,0 +1,167 @@
+# 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-3f2a..."
+safePathSegmentHashed("plugin\\v1");                 // "plugin-v1-91c4..."  (different hash; same safe form)
+safePathSegmentHashed("Über@");                       // "ber-9aae..."
+safePathSegmentHashed("");                           // "skill"  (empty fallback)
+safePathSegmentHashed(".");                          // "skill"
+```
+
+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.
+
+## 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.