@openclaw/fs-safe 0.1.1 → 0.2.0

package/docs/config.md

@@ -0,0 +1,94 @@
+---
+title: Config
+description: "Process-global defaults for optional fs-safe helpers."
+---
+
+# `@openclaw/fs-safe/config`
+
+Process-global configuration knobs for optional fs-safe helpers. The Python helper policy is described in the [Python helper policy](python-helper.md); this page is the API reference.
+
+```ts
+import {
+  configureFsSafePython,
+  configureFsSafeLocks,
+  getFsSafePythonConfig,
+  getFsSafeLockConfig,
+  type FsSafeLockConfig,
+  type FsSafePythonConfig,
+  type FsSafePythonMode,
+} from "@openclaw/fs-safe/config";
+```
+
+These functions are also re-exported from the main entry point. Prefer the subpath when you only need helper configuration and want the smallest import surface.
+
+## `configureFsSafePython(config)`
+
+```ts
+function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
+
+type FsSafePythonConfig = {
+  mode: FsSafePythonMode;
+  pythonPath?: string;
+};
+
+type FsSafePythonMode = "auto" | "off" | "require";
+```
+
+Set the process-global policy. Calls merge into the existing override config, so passing `{ pythonPath: "/usr/bin/python3" }` keeps any previously set `mode`. Configure once at startup, before the first `root()` call — switching modes mid-process is supported but the helper may already be running.
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Default. Use the helper when it starts; fall back to Node-only behavior if Python is missing or fails to start. |
+| `off` | Never spawn the helper. Read/write/move use Node fallbacks plus pre/post identity checks. |
+| `require` | Fail closed if the helper cannot start. Operations that need the helper raise `FsSafeError("helper-unavailable")`. |
+
+## `getFsSafePythonConfig()`
+
+```ts
+function getFsSafePythonConfig(): FsSafePythonConfig;
+```
+
+Return the effective configuration: programmatic overrides win, then env vars, then the package default (`auto`).
+
+## `configureFsSafeLocks(config)`
+
+```ts
+function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
+
+type FsSafeLockConfig = {
+  staleRecovery: "fail-closed";
+  staleMs?: number;
+  timeoutMs?: number;
+  retry?: FileLockRetryOptions;
+};
+```
+
+Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
+
+`staleRecovery` currently supports `"fail-closed"` only. Stale third-party sidecars are not deleted by path because Node cannot atomically bind that deletion to the file that was inspected.
+
+## `getFsSafeLockConfig()`
+
+```ts
+function getFsSafeLockConfig(): FsSafeLockConfig;
+```
+
+Return the current sidecar lock defaults.
+
+## Environment variables
+
+The same policy can be set without code:
+
+```bash
+FS_SAFE_PYTHON_MODE=auto      # auto | off | require | true | false | on | off | 1 | 0 | never | required
+FS_SAFE_PYTHON=/usr/bin/python3
+```
+
+OpenClaw compatibility aliases are accepted: `OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`, `OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`. Programmatic overrides via `configureFsSafePython` always win.
+
+## Related pages
+
+- [Python helper policy](python-helper.md) — when to pick `auto`, `off`, or `require`, and what each mode protects.
+- [File lock](sidecar-lock.md) — the per-resource lock API that consumes lock defaults.
+- [Root API](root.md) — the API whose POSIX hardening the helper backs.
+- [Errors](errors.md) — `helper-unavailable` and `helper-failed`.

package/docs/contributing.md

@@ -0,0 +1,80 @@
+# Contributing
+
+The `fs-safe` repo lives at [github.com/openclaw/fs-safe](https://github.com/openclaw/fs-safe). Contributions welcome — issues, bug reports, focused PRs.
+
+## Local setup
+
+```bash
+git clone https://github.com/openclaw/fs-safe.git
+cd fs-safe
+pnpm install
+```
+
+Node 20.11 or newer. The dev toolchain uses pnpm; `npm install` works too but pnpm is what the lockfile is keyed against.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Runs `tsc -p tsconfig.json`. Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
+
+## Test
+
+```bash
+pnpm test
+```
+
+Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
+
+```bash
+pnpm test test/archive.test.ts
+```
+
+Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
+
+## Format and types
+
+The repo doesn't ship a separate lint config; `tsc --noEmit` (run by `pnpm build`) is the type gate. Format with your editor's TypeScript Language Server defaults — keep diffs tight.
+
+## Docs
+
+The docs site is rendered from `docs/*.md` by `scripts/build-docs-site.mjs`. Build locally to preview:
+
+```bash
+node scripts/build-docs-site.mjs
+open dist/docs-site/index.html
+```
+
+The build validates internal links and embedded anchors. Broken links fail the build — fix them before pushing.
+
+Adding a new doc page:
+
+1. Create `docs/<page>.md`. Use a leading `# Title` heading.
+2. Add the page to the appropriate section in `scripts/build-docs-site.mjs` (`sections` array near the top).
+3. Cross-link from `docs/index.md` if it's a major surface.
+4. Re-run the local build.
+
+Internal links use relative `*.md` paths — the builder rewrites them to the rendered HTML. Code fences support GitHub-flavored markdown.
+
+## PRs
+
+Small, focused PRs land faster. The general shape:
+
+- One concern per PR. Bug fixes separate from new APIs.
+- A regression test for every bug fix where the test framework can express it.
+- A changelog entry under `## Unreleased` when behavior visibly changes.
+- For new public APIs: a docs page in `docs/` plus a sidebar entry.
+
+## Releases
+
+Release process lives in the maintainer's runbook. External contributors don't need to do anything beyond getting the PR merged.
+
+## Reporting security issues
+
+Suspected security issues belong in private disclosure first. See [`SECURITY.md`](https://github.com/openclaw/fs-safe/blob/main/SECURITY.md) in the repo for the current contact path. Don't open a public issue for a credential-stealing or sandbox-escape bug — coordinate the disclosure first.
+
+## License
+
+By contributing you agree that your contributions are licensed under the project's [MIT license](https://github.com/openclaw/fs-safe/blob/main/LICENSE).

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,77 @@
+---
+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 and lock-option defaults. |
+| [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. |
+| [`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`](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 fail-closed stale-lock handling. |
+| [`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).