@openclaw/matrix 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,110 @@
+# 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; use [`safePathSegmentHashedV2`](install-path.md#safepathsegmenthashedv2) when mapping untrusted install IDs to separate directory names.
+
+```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
+
+The primary name goes through this pipeline first:
+
+1. **Trim** whitespace. An empty result is unusable.
+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. An empty result, `"."`, or `".."` is unusable.
+6. **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.
+7. **Make the final name device-safe.** 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 on every platform. If the suffix would exceed 200 code units, the unsuffixed tail is shortened first, so truncation cannot recreate a device name.
+
+Only when the primary name is unusable does `fallbackName` go through the same
+nonrecursive pipeline. A safe fallback is preserved exactly; path components,
+controls, reserved device names, and overlong fallback names receive the same
+treatment as the primary name. If both candidates are unusable, the function
+returns the fixed safe literal `"file"`.
+
+If truncation itself exposes a reserved-device basename after Windows ignores
+trailing spaces or dots, the result is shortened once more and receives the
+same underscore suffix. A name that reaches the sanitization branch therefore
+remains at most 200 UTF-16 code units and is never a Windows reserved-device
+alias. Fallback names pass through the same checks before they can be returned.
+
+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("<>", "../../etc/passwd");       // "passwd"
+sanitizeUntrustedFileName("<>", "../..");                  // "file"
+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) — legacy directory-segment sanitizers and `safePathSegmentHashedV2` for untrusted install IDs.
+- [`root()`](root.md) — the boundary you'll write into after sanitizing.

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

@@ -0,0 +1,152 @@
+# Guest filesystem source
+
+`@openclaw/fs-safe/guest` exports Python 3 source for filesystem operations in
+Linux and macOS guests that do not have Node installed. The host imports a
+string and passes it to its existing container, SSH, or process transport.
+Importing this subpath performs no I/O and launches no process.
+
+This is the filesystem engine extracted from OpenClaw's sandbox bridge. The
+caller still owns root admission, mount selection, read-only policy, canonical
+path authorization, live authority, argument framing, and process lifetime.
+Use [Root](root.md) for ordinary filesystem operations in the Node process.
+This source artifact is separate from the retired host-side Python worker
+described in [Migrating to 0.5](migrating-to-0.5.md).
+
+## Exports and requirements
+
+```ts
+import {
+  GUEST_FILESYSTEM_PYTHON,
+  GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE,
+  GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE,
+  GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON,
+} from "@openclaw/fs-safe/guest";
+```
+
+`GUEST_FILESYSTEM_PYTHON` is the complete single-invocation program. The two
+exit constants are `17` for an exclusive-create collision and `2` for a
+missing read parent or leaf after the root opens. Other nonzero statuses are
+errors; stderr is diagnostic text, not a structured error protocol.
+
+The guest needs Python 3 with `ctypes`, descriptor-relative POSIX operations,
+`O_DIRECTORY`, and `O_NOFOLLOW`. Linux and macOS are the supported guest
+platforms. The guest does not need fs-safe's Node package, native addon, Rust,
+or WASM. Native mode configuration in the host does not configure this program.
+
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON` contains just the
+`rename_no_replace(src_parent_fd, src_basename, dst_parent_fd, dst_basename)`
+definition. OpenClaw's workspace bootstrap consumes this same fragment when
+publishing a prepared workspace; exporting it avoids a second source owner.
+Its embedding program must import `ctypes`, `errno`, `os`, and `sys`, admit
+the descriptors and single-component names, and own cleanup and syncing.
+The fragment has no argument preflight of its own.
+
+On Linux it uses `renameat2(RENAME_NOREPLACE)`; on macOS it uses
+`renameatx_np(RENAME_EXCL)`. If Linux lacks that function or reports it as
+unsupported, it falls back to `link(..., follow_symlinks=False)`, leaving the
+source entry for caller cleanup. That fallback supports files, not directory
+publication. Existing destinations are never replaced by this fragment.
+
+## Invocation protocol
+
+Pass the source through `python3 -c` and arguments as literal argv elements.
+Do not concatenate untrusted values into a shell command. Transport adapters
+that require a shell must apply their existing quoting rules to every element.
+The following example uses an already admitted guest root and parent path:
+
+```ts
+import { spawnSync } from "node:child_process";
+import { GUEST_FILESYSTEM_PYTHON } from "@openclaw/fs-safe/guest";
+
+const result = spawnSync("python3", [
+  "-c", GUEST_FILESYSTEM_PYTHON,
+  "write", "/srv/admitted-workspace", "notes", "today.txt", "1",
+], { input: Buffer.from("hello\n"), timeout: 10_000 });
+if (result.error) throw result.error;
+if (result.status !== 0) throw new Error(result.stderr.toString());
+```
+
+All frames below start at `sys.argv[1]`. `root` is an admitted guest directory;
+`parent` and `directory` are paths relative to that root. An empty relative
+path selects the root itself. Flags are strings: `"1"` enables and `"0"`
+disables. Do not omit required fields.
+
+| Operation | Positional frame | Input / output |
+|---|---|---|
+| Read | `read root parent basename [maxBytes]` | Raw bytes on stdout; optional nonnegative integer byte limit. |
+| Write | `write root parent basename mkdir` | Raw stdin; atomically replaces a file entry. |
+| Create | `create root parent basename mkdir` | Raw stdin; exclusively publishes a completed file. |
+| Copy | `copy srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Regular-file copy, atomically replaces destination. |
+| Rename | `rename srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Rename with cross-device copy/delete fallback. |
+| Remove | `remove root parent basename recursive force` | Removes the leaf, or recursively removes its tree. |
+| Make directories | `mkdirp root directory` | Creates missing relative directory components. |
+| List directory | `readdir root directory` | JSON array of `{ name, isDirectory, isFile }`; both kind fields are false for symlinks and special entries; no sorting guarantee. |
+
+The complete program rejects empty, `.`, `..`, slash-containing, and NUL
+basenames before opening roots or creating parents. Both leaf operands of copy
+and rename are checked. Backslashes, colons, quotes, and newlines remain legal
+POSIX basename characters. Relative directory traversal rejects `..`; empty
+and `.` components are skipped. Supply admitted relative paths, not arbitrary
+absolute paths whose spelling happens to pass that component walk.
+
+## Boundary and operation behavior
+
+The supplied root spelling is trusted. Opening it does not prove the root is
+the mount or inode previously authorized by the caller. Basename syntax checks
+are not authorization. Callers must admit their roots and paths, preserve
+read-only shadows and live authority, and run the program inside the intended
+OS isolation boundary.
+
+Parent traversal and operation bodies use directory descriptors. Reads and
+copies refuse final symlinks, hardlinked files, and nonregular files. Bounded
+reads check both admitted size and consumed bytes; a growing file can produce
+partial stdout before rejection. Consumers must discard read output when the
+exit status indicates failure. Removal unlinks a final symlink without
+following it; rename moves symlink entries. Write and copy replace destination
+entries, including symlinks, without following them. A force removal tolerates
+a missing leaf but does not suppress failure to open its parent.
+
+Write preserves an existing regular file's mode and otherwise creates private
+files. Copy preserves the source mode. Exclusive create publishes a mode-0600
+file from a private staging directory. Staging names retain the `.openclaw-*`
+prefixes and use short random suffixes independent of the destination basename,
+so legal names near the filesystem's component limit also work for writes and
+cross-device moves.
+
+Cross-device symlink moves create the new link in a private destination-side
+staging directory before atomically replacing the destination. Link creation or
+publication failure preserves the existing destination and source link; ordinary
+failure cleanup removes the staging directory.
+
+Cross-device directory moves build a copy manifest and check it during source
+cleanup. Directory creation keeps the source mode subject to the guest's umask;
+mode `000` is not replaced with a default. A top-level mode-000 directory uses
+owner-only staging until publication, then restores zero through its retained
+descriptor. Reading a mode-000 source still requires sufficient OS privileges;
+the guest does not change source permissions to gain access. A permission error
+after publication preserves the source and published copy for reconciliation.
+Source changes can leave the published destination and some or all
+of the source. Regular-file and symlink move fallbacks unlink the source
+pathname after publication; they do not perform the directory manifest's
+identity checks. Directory cleanup also has check-to-unlink race windows.
+These mechanics do not promise content integrity against same-UID peers.
+
+## Failure, cancellation, and budgets
+
+Nonzero exit is not proof that nothing was published. A post-publication
+identity or sync failure, or cross-device source-cleanup failure, can leave a
+destination. The caller owns reconciliation and retry policy; do not assume
+it is safe to remove that destination or replay a mutation blindly.
+
+Ordinary Python failures run `finally` cleanup. There is no cancellation frame
+or signal handler. Process death closes descriptors, but forced termination
+can leave staging names. The transport owns termination, waiting for children
+to settle, and any application-specific recovery.
+
+Read byte limits are optional. Copy, write, recursive removal, directory
+listing, and cross-device tree moves have no byte, entry, or depth budget in
+this protocol. Recursive traversal and listing collect entries eagerly.
+Use caller-owned isolation and resource limits appropriate to the operation.
+The existing fsync sequence is preserved; this is not a recursive transaction,
+rollback facility, or a stronger durability guarantee than the underlying
+filesystem provides.

package/node_modules/@openclaw/fs-safe/docs/in-place-write.md

@@ -0,0 +1,81 @@
+---
+title: In-place writes
+description: "Replace bytes through a borrowed file handle while preserving its inode and attempting rollback on failure."
+---
+
+# In-place writes
+
+`overwriteFileHandle()` replaces a regular file's contents through a handle the
+caller already owns. Use it when replacing the inode would break hardlinked
+aliases, or when an existing writable file lives in a directory where the caller
+cannot create a sibling temporary file.
+
+```ts
+import { open } from "node:fs/promises";
+import { overwriteFileHandle } from "@openclaw/fs-safe/advanced";
+
+const handle = await open(filePath, "r+");
+try {
+  await overwriteFileHandle(handle, Buffer.from(nextContents, "utf8"), {
+    beforeWrite: () => assertCurrentOwner(),
+  });
+} finally {
+  await handle.close();
+}
+```
+
+## Contract
+
+```ts
+overwriteFileHandle(
+  handle: FileHandle,
+  data: Uint8Array,
+  options?: { beforeWrite?: () => void },
+): Promise<void>;
+```
+
+The handle must be readable and writable, refer to a regular file, and have been
+opened **without append mode**. Node cannot portably inspect a handle's append
+flag, and some operating systems ignore positioned-write offsets for append
+handles. Opening, path admission, symlink and hardlink policy, and closing remain
+the caller's responsibility. The helper never reopens or replaces the inode,
+changes the handle's current position, or closes it. Every hardlinked alias sees
+the in-place changes.
+
+The payload is borrowed, including its byte offset and length. Keep it unchanged,
+attached, and accessible until the returned promise settles. Do not close the
+handle or run concurrent I/O against the file, including through other aliases,
+during preparation, writing, or rollback. This helper does not acquire a lock.
+
+## Preparation, ordering, and failure
+
+The helper checks the file type and original size, then saves only the prefix
+that will be overwritten: `min(data.byteLength, originalSize)` bytes. A short
+prefix read fails with `FsSafeError("read-failed")` before writing. Memory for the
+backup is bounded by that prefix length; a short replacement of a large file does
+not read or buffer the untouched tail.
+
+After preparation, `beforeWrite` runs synchronously once. A thrown value is
+propagated unchanged without any file mutation. A Promise or thenable return is
+rejected with `TypeError`; asynchronous callbacks cannot admit a write. Once
+admitted, the operation finishes the write or its failure recovery without
+calling `beforeWrite` again. This callback is a whole-operation admission point,
+not the per-mutation `assertBeforeMutation` callback used by Root operations.
+It must not change the file, handle, or payload. There is no cancellation option.
+
+For growth, additional tail bytes are written before the existing prefix is
+touched. The prefix is then overwritten, completing partial writes. For shrinkage,
+truncation is last. If a write or truncation fails, the helper attempts to restore
+the saved prefix, if touched, and the original length. It waits for both recovery
+attempts and then rethrows the original error, even when recovery also fails.
+Zero-progress writes fail with `FsSafeError("helper-failed")`.
+
+Recovery is best effort, not atomic publication or a crash-recovery guarantee.
+Other observers can see intermediate contents; failed recovery can leave partial
+bytes. The helper does not chmod or synchronize the file or its directory.
+Normal filesystem effects such as timestamp updates or clearing special mode
+bits can still occur. Callers own any durability or broader transaction policy.
+
+The implementation uses Node positional reads and writes in every native mode;
+it does not load a native binding. Prefer [`Root.write`](writing.md) when atomic
+replacement and root-based path admission are the intended contract.

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

@@ -0,0 +1,87 @@
+---
+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. |
+| [`@openclaw/fs-safe/guest`](guest.md) | Python filesystem source for caller-owned guest transports, with admitted roots and descriptor-relative operations. |
+| [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. |
+| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
+| [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
+| [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
+| [`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,216 @@
+# 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,
+  safePathSegmentHashedV2,
+} 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 }`. On Windows, contained alternate-stream and filesystem-namespace aliases are rejected with the same result.
+
+```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 untrusted IDs that must occupy separate install directories, pass
+`nameEncoder: safePathSegmentHashedV2`. The default `safeDirName` and legacy
+`safePathSegmentHashed` can map distinct IDs to the same directory; the boundary
+check does not establish which ID owns an existing directory.
+
+```ts
+const r = resolveSafeInstallDir({
+  baseDir: "/srv/plugins-v2",
+  id: untrustedId,
+  invalidNameMessage: "invalid plugin name",
+  nameEncoder: safePathSegmentHashedV2,
+});
+```
+
+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`. On Windows it also throws for alternate-stream or filesystem-namespace aliases in the base, candidate, or canonical path. The `boundaryLabel` is included in the containment-shaped 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`.
+
+Use `safePathSegmentHashedV2` when distinct untrusted IDs need separate names.
+
+### `safePathSegmentHashedV2`
+
+```ts
+function safePathSegmentHashedV2(input: string): string;
+```
+
+Hashes every trimmed ID, including ordinary short names, into `id-v2-` followed
+by 64 lowercase hexadecimal SHA-256 digits. The result is always 70 ASCII bytes,
+contains no separators, and avoids Windows device names and ignored suffixes.
+There is no readable prefix to truncate and no unchanged-name branch. Distinct
+trimmed IDs, including an ID that looks like an encoded output, remain distinct
+unless their full SHA-256 digests collide. The lowercase ASCII output also
+preserves that distinction on case-insensitive and Unicode-normalizing volumes.
+
+The stable V2 digest recipe is SHA-256 of the UTF-8 bytes of
+`"@openclaw/fs-safe:install-path:v2\0"`, followed by the UTF-16LE bytes of
+`input.trim()`, without a byte-order mark. The NUL-terminated prefix separates
+this use of SHA-256 from other hash domains. UTF-16LE preserves exact JavaScript
+code units, including lone surrogates. Inputs are not case-folded or Unicode
+normalized. Surrounding whitespace, as removed by JavaScript `String.trim()`,
+is the only intentional equivalence; internal whitespace remains significant.
+
+```ts
+const segment = safePathSegmentHashedV2("plugin/v1"); // id-v2-<64 hex digits>
+safePathSegmentHashedV2(" plugin/v1 ") === segment;  // true
+safePathSegmentHashedV2("Plugin/v1") === segment;    // false
+```
+
+This encoder computes a name; it does not authorize access or prove ownership
+of a directory. Store the original trimmed ID in application-owned metadata and
+verify it before reusing an existing install directory. Keep each install tree
+on one encoding version. Switching to V2 changes existing paths: use a new base
+directory or explicitly migrate directories after verifying their recorded IDs.
+Do not silently fall back to a legacy path when the V2 path is missing.
+
+### `safePathSegmentHashed`
+
+Legacy readable encoding retained for path compatibility. It appends a short
+content hash when sanitization changed the input or when the safe form is too
+long; ordinary short names remain unchanged. Use V2 for new untrusted-ID mappings.
+
+```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)`. This is a
+40-bit identifier, and the hash is not applied to every ID: short generated
+outputs overlap with accepted literal inputs. Case variants can also share a
+directory on case-insensitive filesystems. Distinct IDs can therefore alias
+without a hash collision. Do not use this legacy encoder as an identity or
+authorization boundary for untrusted IDs. Inputs that differ only by surrounding
+whitespace intentionally map to the same output. Its output and the default
+encoder selected by `resolveSafeInstallDir` remain unchanged for compatibility.
+
+## Common patterns
+
+### Install a plugin
+
+```ts
+import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashedV2 } from "@openclaw/fs-safe/advanced";
+import { extractArchive } from "@openclaw/fs-safe/archive";
+import fs from "node:fs/promises";
+
+const r = resolveSafeInstallDir({
+  baseDir: "/srv/plugins-v2",
+  id: untrustedName,
+  invalidNameMessage: "invalid plugin name",
+  nameEncoder: safePathSegmentHashedV2,
+});
+if (!r.ok) return reply(400, r.error);
+
+await fs.mkdir(r.path, { recursive: true, mode: 0o755 });
+await assertCanonicalPathWithinBase({
+  baseDir: "/srv/plugins-v2",
+  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",
+  nameEncoder: safePathSegmentHashedV2,
+});
+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.