@openclaw/fs-safe 0.1.1 → 0.2.0

package/docs/secret-file.md

@@ -0,0 +1,154 @@
+# Secret files
+
+Helpers for reading and writing credentials. Files are written at mode `0o600`, dirs at `0o700`, with a maximum read size to avoid OOM on bogus input.
+
+```ts
+import {
+  readSecretFileSync,
+  tryReadSecretFileSync,
+  writeSecretFileAtomic,
+  DEFAULT_SECRET_FILE_MAX_BYTES,
+  PRIVATE_SECRET_DIR_MODE,
+  PRIVATE_SECRET_FILE_MODE,
+} from "@openclaw/fs-safe/secret";
+```
+
+## When to use these vs `writeJson`
+
+| Use these when | Use `writeJson` when |
+|---|---|
+| The file is a credential (token, key, password). | The file is application state. |
+| You want the parent directory created at `0o700` if missing. | You don't care about the parent directory mode. |
+| You want a hard size cap on reads (to defend against bogus input). | You're reading bounded JSON state. |
+| Mode `0o600` is mandatory, not just nice. | Mode is whatever umask gives you. |
+
+## Constants
+
+```ts
+DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;  // 16 KiB
+PRIVATE_SECRET_DIR_MODE = 0o700;
+PRIVATE_SECRET_FILE_MODE = 0o600;
+```
+
+The 16 KiB cap is intentionally aggressive — credentials should be small. If you need bigger, pass `maxBytes` explicitly.
+
+## Reading
+
+### `tryReadSecretFileSync(filePath, label, options?)`
+
+The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing, empty, unreadable, too large, or rejected by the validation checks.
+
+```ts
+import { tryReadSecretFileSync } from "@openclaw/fs-safe/secret";
+
+const token = tryReadSecretFileSync("/var/lib/app/auth.token", "auth token");
+if (token) {
+  useToken(token);
+} else {
+  await reauthenticate();
+}
+```
+
+### `readSecretFileSync(filePath, label, options?)`
+
+Strict reader. Throws `FsSafeError` when the file is missing, too large, empty, unreadable, or rejected by the validation checks. Use when failing loudly is the right call:
+
+```ts
+const token = readSecretFileSync("/var/lib/app/auth.token");
+```
+
+### Read options
+
+```ts
+type SecretFileReadOptions = {
+  maxBytes?: number;         // default DEFAULT_SECRET_FILE_MAX_BYTES (16 KiB)
+  rejectSymlink?: boolean;
+};
+```
+
+The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read.
+
+## Writing
+
+### `writeSecretFileAtomic(params)`
+
+Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file at `mode` (default `0o600`), atomically renames over the destination, and re-asserts the file mode after rename.
+
+```ts
+import { writeSecretFileAtomic } from "@openclaw/fs-safe/secret";
+
+await writeSecretFileAtomic({
+  rootDir: "/var/lib/app",
+  filePath: "/var/lib/app/auth.token",
+  content: token,
+});
+```
+
+### Parameters
+
+```ts
+type WriteSecretFileParams = {
+  rootDir: string;             // trusted root directory (created at dirMode if missing)
+  filePath: string;             // absolute path; must be inside rootDir
+  content: string | Uint8Array;
+  mode?: number;                // file mode for the new file (default PRIVATE_SECRET_FILE_MODE = 0o600)
+  dirMode?: number;             // mode for the root and intermediate dirs (default PRIVATE_SECRET_DIR_MODE = 0o700)
+};
+```
+
+The directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. The helper enforces that every component matches `dirMode` — wider permissions on an existing directory cause the write to fail. Audit and tighten existing secret directories yourself.
+
+For more permissive credentials, override `mode`:
+
+```ts
+await writeSecretFileAtomic({
+  rootDir: "/var/lib/app",
+  filePath: "/var/lib/app/readonly.token",
+  content: token,
+  mode: 0o400, // tighter than the default
+});
+```
+
+## Common patterns
+
+### Load on boot, reauthenticate on miss
+
+```ts
+const token = tryReadSecretFileSync("/var/lib/app/auth.token", "auth token");
+if (!token) await runOauthFlow();
+```
+
+### Refresh and persist a token
+
+```ts
+const fresh = await refreshToken(currentRefresh);
+await writeSecretFileAtomic({
+  rootDir: "/var/lib/app",
+  filePath: "/var/lib/app/auth.token",
+  content: JSON.stringify(fresh),
+});
+```
+
+### Compose with `withTimeout`
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+
+await withTimeout(
+  writeSecretFileAtomic({ rootDir, filePath, content }),
+  5_000,
+  "persist auth token",
+);
+```
+
+## Threat model notes
+
+- These helpers protect the secret file from **other processes with the same UID** that respect filesystem permissions. They do not defend against root or against attackers who can read process memory.
+- Validation failures are tripwires, not authorization. Investigate before clearing a rejected credential file.
+- If the destination directory is on a tmpfs that does not honor mode bits, the helpers will set the mode bits but the OS may ignore them. Audit your platform.
+
+## See also
+
+- [JSON files](json.md) — `writeJson` accepts `mode: 0o600` for non-secret JSON state.
+- [Atomic writes](atomic.md) — the lower-level `replaceFileAtomic` used by these helpers.
+- [Private file-store mode](private-file-store.md) — root-bounded JSON+text stores using secret-file write policy.

package/docs/secure-file.md

@@ -0,0 +1,82 @@
+# Secure file reads
+
+`readSecureFile()` is for absolute file paths that should be treated like credentials or other sensitive local inputs. It is stricter than `fs.readFile()` and different from `root().read()`: the file path is absolute, but the read is still fd-pinned and permission-checked before bytes are returned.
+
+```ts
+import { readSecureFile } from "@openclaw/fs-safe/secure-file";
+
+const { buffer, realPath, permissions } = await readSecureFile({
+  filePath: "/var/lib/app/auth.token",
+  label: "auth token",
+  trust: { trustedDirs: ["/var/lib/app"] },
+  io: { maxBytes: 16 * 1024, timeoutMs: 5_000 },
+});
+```
+
+## Checks
+
+The helper:
+
+- requires a local absolute path and rejects UNC/network paths by default
+- rejects directories and, by default, symlink paths
+- opens the file before reading and verifies the opened fd still matches the path and realpath
+- optionally requires the real path to live under one of `trust.trustedDirs`
+- rejects hard-to-verify or unsafe permissions unless `permissions.allowInsecure` is set
+- rejects files owned by another POSIX uid
+- enforces `maxBytes` before and after reading
+- closes the handle on success, error, and timeout
+
+On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper uses the ACL inspection helpers from [`permissions`](permissions.md) and refuses the read if ACLs cannot be verified.
+
+## Options
+
+```ts
+type SecureFileReadOptions = {
+  filePath: string;
+  label?: string;
+  trust?: {
+    trustedDirs?: string[];
+    allowSymlink?: boolean;
+    allowNetworkPath?: boolean;
+  };
+  permissions?: {
+    allowInsecure?: boolean;
+    allowReadableByOthers?: boolean;
+  };
+  inject?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    exec?: PermissionExec;
+  };
+  io?: {
+    maxBytes?: number;
+    timeoutMs?: number;
+  };
+};
+```
+
+`permissions.allowInsecure` is a migration escape hatch. Prefer fixing permissions and using [`formatPermissionRemediation`](permissions.md) to show the user what to run. `trust.allowNetworkPath` is off by default because UNC paths are remote authority, not local filesystem input. `inject` is for tests and platform adapters; production callers usually leave it unset.
+
+## Errors
+
+`readSecureFile()` throws `FsSafeError` with codes such as:
+
+| Code | Meaning |
+|---|---|
+| `invalid-path` | `filePath` was not a local absolute path. |
+| `not-found` | The path could not be stat'd before open. |
+| `not-file` | The opened target is not a regular file. |
+| `symlink` | The path is a symlink and `trust.allowSymlink` is false. |
+| `path-mismatch` | The path or realpath changed between open and verification. |
+| `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
+| `permission-unverified` | Required mode/ACL checks could not be completed. |
+| `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
+| `not-owned` | POSIX owner uid is not the current process uid. |
+| `too-large` | File size or bytes read exceeded `maxBytes`. |
+| `timeout` | `timeoutMs` elapsed while reading. |
+
+## See also
+
+- [Permissions](permissions.md) — standalone POSIX mode and Windows ACL checks.
+- [Secret files](secret-file.md) — mode-0600 credential read/write helpers.
+- [Reading](reading.md) — root-bounded relative reads.

package/docs/security-model.md

@@ -0,0 +1,99 @@
+# Security model
+
+`fs-safe` is a library-level guardrail: a capability-style root handle for Node.js code that handles untrusted relative paths. It assumes the calling process already has whatever filesystem permissions it needs and aims to stop trivial path tricks from broadening that authority. It is not a sandbox and does not replace operating-system isolation.
+
+The same shape exists in other languages: Go's [`os.Root` / `OpenInRoot`](https://go.dev/blog/osroot) and Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std) both expose a root handle whose operations refuse to escape it. `fs-safe` is the Node-side equivalent: a single `root()` capability that carries the boundary across every read, write, move, and remove, instead of leaving each call site to redo `path.resolve(...).startsWith(...)` and hope.
+
+## Threat model
+
+You hand a `root()` boundary to a piece of code that takes caller-controlled relative paths. The library defends against a caller that:
+
+- supplies `..` traversal segments to escape the boundary
+- supplies an absolute path where a relative one is expected
+- replaces a path component with a symlink between check and use (TOCTOU)
+- replaces the destination directory with a symlink right before a write
+- creates a hardlink that aliases an out-of-tree inode and asks you to read or replace it
+- triggers a partial write that leaves a half-written file at the destination
+- ships an archive with `..` paths, absolute paths, or symlinks pointing outside the destination
+
+It does **not** defend against:
+
+- a process running with permissions to write anywhere on the filesystem and choosing to ignore the library
+- another process with the same UID racing to mutate the same directory between two separate `fs-safe` calls — the boundary is per-call, not per-session
+- traversal across filesystem boundaries, bind mounts, device files, `/proc`-style virtual filesystems, or any other path your process can normally access from inside the root
+- container escape, TOCTOU between fork and exec of helpers, or kernel-level vulnerabilities
+- semantic content checks: file types, archive payload schemas, signature verification
+
+If you need full sandboxing, run the worker under reduced privileges (uid, container, seccomp, chroot, jail) and use `fs-safe` inside the sandbox to keep the worker honest about its own workspace.
+
+## Defenses, by failure mode
+
+### Path traversal and absolute paths
+
+Every relative path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Inputs containing `..`, leading `/` (without `pathScope` opt-in), or that resolve outside the root throw `outside-workspace`.
+
+### Symlinks (read side)
+
+`open()` and `read()` use `fs.open` with `O_NOFOLLOW` on POSIX where available. The library then `fstat`s the open fd and `realpath`s the original input, asserting the two refer to the same inode (`sameFileIdentity`). A symlink swap that happens between resolve and open will fail at the identity check rather than silently following the new target.
+
+Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is still inside the root. The default is `"reject"`.
+
+### Symlinks (write side)
+
+Writes use a sibling-temp + rename helper that opens the parent directory by fd, then performs the rename `at` the parent fd. Replacing the parent directory with a symlink between the parent-fd open and the rename does not divert the write.
+
+### Hardlink aliasing
+
+When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink > 1`, on the conservative assumption that a hardlinked file might alias an out-of-tree inode. This is defense-in-depth: the link count check is best-effort and platform-dependent. Treat it as a tripwire, not authorization.
+
+### TOCTOU between resolve and use
+
+`resolve()`, `exists()`, `stat()`, and `list()` are explicitly **not** race-resistant — they answer a question and return. To act on a path with race resistance, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. They re-pin the path identity at the point of use.
+
+### Atomic writes
+
+`replaceFileAtomic` writes to a sibling temp file in the destination directory, optionally `fsync`s it, optionally `fsync`s the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path.
+
+Within one process, async writes to the same target are queued so their temp-write/rename phases do not overlap. Cross-process writers still need an external protocol such as the sidecar lock helpers.
+
+### Archive extraction
+
+`extractArchive` first stages into a private temp directory (mode 0700) outside the destination, validates each entry path against `..` and absolute prefixes, refuses link-type entries by default, enforces entry count and byte budgets, and only then merges the staged tree into the destination through the same boundary checks used by direct writes.
+
+## What "library-level" means
+
+A library cannot revoke its own caller's authority. If your code chooses to bypass `fs-safe` and call `fs.writeFile` directly with the same path, you bypass the defenses too. The contract `fs-safe` enforces is: *every filesystem operation that touches caller-controlled input goes through the boundary*. That contract is yours to keep.
+
+The library does not modify or constrain the global Node.js `fs` namespace, and it does not patch the runtime. Other code in the same process retains its normal filesystem authority.
+
+## Platform notes
+
+- **POSIX (Linux, macOS):** Best-defended path. Uses `O_NOFOLLOW`, fd identity checks, and one persistent Python helper process for fd-relative `unlinkat` / `mkdirat` / `renameat` / parent-fd write operations. Configure `FS_SAFE_PYTHON_MODE=require` when helper startup must fail closed, or `off` when you need a no-Python runtime. See [Python helper policy](python-helper.md).
+- **Windows:** Falls back to the safest Node-level behavior available. `O_NOFOLLOW` is not honored. Some fd-relative POSIX hardening is unavailable. The library does the path canonicalization, identity, and atomic-rename checks it can.
+
+The library does not advertise different security guarantees per platform — it advertises the same surface and relies on the strongest mechanism the platform offers.
+
+## Limitations to keep in mind
+
+| Limitation | What it means |
+|---|---|
+| Not ambient authority removal | Code that can import `node:fs` can still bypass the handle. Keep caller-controlled path operations behind `root()` by convention, review, and tests. |
+| Absolute paths are escape hatches | APIs that accept or return absolute paths exist for audit, ingest, and advanced composition. Prefer root-relative names in normal application flow. |
+| Not a mount/device boundary | `root()` keeps path traversal inside the directory tree; it does not make device files, bind mounts, or virtual filesystems safe to expose. |
+| Per-call, not per-session | Another process with the same privileges can still mutate the tree between two separate calls. Use one verb method for the operation you need to make race-resistant. |
+| Hardlink rejection is best-effort | Link-count checks depend on platform metadata. Treat `hardlinks: "reject"` as a tripwire, not an authorization primitive. |
+| Mode bits are not a full policy engine | `replaceFileAtomic` and secret-file helpers set requested modes, but you should still set umask and inspect modes when policy requires it. |
+| Archive extraction is path safety, not content safety | Unsafe entry paths and links are rejected; malicious payload contents remain your application layer's problem. |
+| Helper failures degrade fd-relative hardening | `helper-unavailable` falls back in `auto` mode and fails closed in `require` mode. Atomicity and identity checks remain, but parent-directory swaps between validation and mutation are less tightly pinned without the helper. |
+
+## Recommended deployment shape
+
+- Run worker code under a dedicated UID with the smallest filesystem privileges that still allow the worker to do its job.
+- Mount the workspace directory writable; mount everything else read-only or not at all.
+- Use `fs-safe`'s `root()` for that workspace.
+- For credentials, use [secret files](secret-file.md) (mode 0600 in mode-0700 dirs) rather than the workspace.
+- For scratch space, use a [private temp workspace](temp.md) — don't reuse the workspace root.
+
+## Reporting 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.

package/docs/sidecar-lock.md

@@ -0,0 +1,230 @@
+# File lock
+
+`acquireFileLock()` and `withFileLock()` provide a cross-process file lock with retry and process-exit cleanup. The lock is implemented as a sidecar file (e.g. `state.json` ↔ `state.json.lock`) — only one acquirer can create the sidecar with `O_CREAT | O_EXCL` at a time.
+
+```ts
+import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
+
+const handle = await acquireFileLock("/var/lib/app/state.json", {
+  managerKey: "snapshot",
+  staleMs: 5 * 60_000,
+  payload: async () => ({ pid: process.pid, host: os.hostname() }),
+});
+try {
+  // ...exclusive work on /var/lib/app/state.json...
+} finally {
+  await handle.release();
+}
+```
+
+## Why sidecar?
+
+The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
+
+The library installs a `process.on("exit")` handler that releases all currently-held locks synchronously, so well-behaved exits leave no stale sidecars. Crashed holders leave their sidecar behind; remove those through an application-owned recovery path after you have proved the holder cannot still be writing.
+
+## API
+
+```ts
+function acquireFileLock<TPayload>(
+  targetPath: string,
+  options: FileLockAcquireOptions<TPayload>,
+): Promise<FileLockHandle>;
+
+function withFileLock<T, TPayload>(
+  targetPath: string,
+  options: FileLockAcquireOptions<TPayload>,
+  fn: () => Promise<T>,
+): Promise<T>;
+
+function createFileLockManager(key: string): FileLockManager;
+```
+
+`managerKey` is an optional identifier used to keep state isolated across multiple lock domains in the same process. Use distinct keys for distinct domains (`"snapshot"`, `"compact"`, `"build"`). If omitted, fs-safe derives one from the target path.
+
+## Acquire options
+
+```ts
+type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
+  managerKey?: string;                   // optional in-process manager namespace
+  lockPath?: string;                     // override; defaults to `${targetPath}.lock`
+  staleMs?: number;                      // default 30_000
+  timeoutMs?: number;                    // overall acquire deadline; default unbounded
+  retry?: FileLockRetryOptions;
+  staleRecovery?: "fail-closed";         // default
+  allowReentrant?: boolean;              // if this process already holds it, increment a count instead of failing
+  payload: () => TPayload | Promise<TPayload>;
+  shouldReclaim?: (params: {
+    lockPath: string;
+    normalizedTargetPath: string;
+    payload: Record<string, unknown> | null;
+    staleMs: number;
+    nowMs: number;
+    heldByThisProcess: boolean;
+  }) => boolean | Promise<boolean>;
+  metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
+};
+
+type FileLockRetryOptions = {
+  retries?: number;       // number of retry attempts after the first failure
+  factor?: number;        // exponential backoff factor (default 2)
+  minTimeout?: number;    // initial delay (ms)
+  maxTimeout?: number;    // delay cap (ms)
+  randomize?: boolean;    // jitter
+};
+```
+
+`payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+
+## Release handle
+
+```ts
+type FileLockHandle = {
+  lockPath: string;
+  normalizedTargetPath: string;
+  release: () => Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+};
+```
+
+Always release in a `finally`:
+
+```ts
+const handle = await acquireFileLock(targetPath, {
+  staleMs: 60_000,
+  payload: () => ({ pid: process.pid }),
+});
+try {
+  await doExclusiveWork();
+} finally {
+  await handle.release();
+}
+```
+
+If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed instead of deleting by path, because Node cannot atomically bind that deletion to the file that was inspected.
+
+## `withFileLock` — common shape made one-liner
+
+```ts
+const result = await withFileLock(
+  "/var/lib/app/state.json",
+  {
+    managerKey: "compact",
+    staleMs: 30_000,
+    payload: () => ({ pid: process.pid, what: "compact" }),
+  },
+  async () => {
+    return await runCompaction();
+  },
+);
+```
+
+Acquires, runs `fn`, releases regardless of success/failure. Returns the result of `fn`.
+
+## Long-lived managers
+
+Most callers should use `acquireFileLock()` or `withFileLock()`. Use `createFileLockManager(key)` only when a long-lived service needs diagnostics or lifecycle control over locks it currently holds:
+
+```ts
+const locks = createFileLockManager("session-writes");
+const handle = await locks.acquire(sessionPath, {
+  staleMs: 60_000,
+  payload: () => ({ pid: process.pid }),
+});
+
+for (const held of locks.heldEntries()) {
+  console.log(held.lockPath, held.acquiredAt);
+}
+
+await handle.release();
+await locks.drain();
+```
+
+## Stale policy: `shouldReclaim`
+
+The default policy treats locks whose `createdAt` is older than `staleMs` as stale. Pass a custom callback when you want a richer notion of "is the holder still alive":
+
+```ts
+import { kill } from "node:process";
+
+const handle = await acquireFileLock(targetPath, {
+  staleMs: 60_000,
+  payload: () => ({ pid: process.pid }),
+  shouldReclaim: ({ payload, nowMs, staleMs }) => {
+    if (!payload) return true;
+    const pid = Number(payload.pid);
+    if (!Number.isFinite(pid)) return true;
+    try {
+      kill(pid, 0);
+      return false;                     // process still alive — keep waiting
+    } catch {
+      return true;                      // process gone — fail closed for recovery
+    }
+  },
+});
+```
+
+`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result does not delete the sidecar; it lets the acquire loop stop waiting once the retry/timeout policy says to give up.
+
+## What sidecar locks defend against
+
+- **Two processes writing the same file at once.** `acquire` serializes the critical section.
+- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks fail closed because safe compare-and-unlink is not available through Node's path APIs.
+- **Race between simultaneous acquire attempts.** `O_CREAT | O_EXCL` ensures one wins.
+
+## What they do **not** defend against
+
+- **Misbehaving holders that ignore the lock.** Locks are advisory — only callers that go through `acquire` are bound.
+- **Automatic stale lock deletion.** If a process crashes, use the payload and your own supervisor/process table to decide when to remove the sidecar.
+- **Multi-host coordination over network filesystems.** Behavior depends on the underlying filesystem's `O_EXCL` semantics; treat as best-effort.
+
+## Common patterns
+
+### Compact under lock
+
+```ts
+await withFileLock(
+  "/var/lib/app/db.sqlite",
+  {
+    staleMs: 30_000,
+    payload: () => ({ pid: process.pid, what: "compact" }),
+  },
+  async () => {
+    await runCompaction();
+  },
+);
+```
+
+### Try once, give up if held
+
+```ts
+try {
+  await withFileLock(
+    targetPath,
+    { staleMs: 30_000, retry: { retries: 0 }, payload: () => ({ pid: process.pid }) },
+    async () => await work(),
+  );
+} catch (err) {
+  console.log("another process is doing this; skipping");
+}
+```
+
+### Wait politely with backoff
+
+```ts
+await withFileLock(
+  targetPath,
+  {
+    staleMs: 60_000,
+    timeoutMs: 30_000,
+    retry: { retries: 30, minTimeout: 100, maxTimeout: 5_000, factor: 1.7, randomize: true },
+    payload: () => ({ pid: process.pid }),
+  },
+  async () => await work(),
+);
+```
+
+## See also
+
+- [Atomic writes](atomic.md) — single-writer atomicity that often replaces the need for a lock entirely.
+- `createAsyncLock` from `@openclaw/fs-safe/advanced` — in-process serialization for a single Node process.

package/docs/store.md

@@ -0,0 +1,77 @@
+---
+title: Store
+description: "Overview of @openclaw/fs-safe/store: fileStore, fileStoreSync, and jsonStore."
+---
+
+# `@openclaw/fs-safe/store`
+
+The `store` subpath bundles two managed wrappers around the same safe-write primitives `root()` uses:
+
+```ts
+import {
+  ensureJsonDurableQueueDirs,
+  fileStore,
+  fileStoreSync,
+  jsonStore,
+  loadPendingJsonDurableQueueEntries,
+  resolveJsonDurableQueueEntryPaths,
+  writeJsonDurableQueueEntry,
+  type FileStore,
+  type FileStoreOptions,
+  type FileStoreSync,
+  type JsonStore,
+  type JsonStoreOptions,
+} from "@openclaw/fs-safe/store";
+```
+
+| Helper | Use it for |
+|---|---|
+| [`fileStore()`](file-store.md) | Multi-file directories with safe relative paths, size limits, atomic replacement, stream writes, copy-in, and TTL-based pruning. |
+| `fileStoreSync()` | Synchronous variant of `fileStore()` for places that genuinely cannot await. |
+| [`jsonStore()`](json-store.md) | A single keyed JSON state file with explicit fallback, atomic writes, and optional sidecar locking around read-modify-write updates. |
+| Durable JSON queue helpers | Append/load/ack JSON entry files using atomic writes and delivered markers. |
+| [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for credentials, tokens, and per-agent state at `0600` files under `0700` directories. |
+
+`fileStore().json("rel.json")` and `jsonStore({ filePath })` are intentionally separate primitives. Use `fileStore().json(...)` when JSON state lives alongside other files in the same managed directory; use `jsonStore({ filePath })` when you have a single absolute path and want the keyed JSON shape directly.
+
+## Picking a shape
+
+- **Multi-file directory under one root** — reach for `fileStore()`. It exposes `write`, `writeJson`, `writeText`, `writeStream`, `read*`, `open`, `copyIn`, `remove`, and `pruneExpired` against safe relative paths.
+- **One JSON state file** — reach for `jsonStore({ filePath })`. Its `update()` and `updateOr()` methods cover the merge-into-defaults and read-modify-write cases.
+- **Credentials or tokens** — pass `private: true` to `fileStore()`. Same store shape; writes route through the secret-file atomic path with `0600`/`0700` permissions.
+- **Durable work queues** — use the durable JSON queue helpers when each work item is a standalone JSON file and acknowledgement is represented by moving it through a short-lived `.delivered` marker.
+
+## Durable JSON queues
+
+The durable queue helpers are intentionally low-level. They do not decide retry,
+dedupe, or recovery policy; they just provide the filesystem mechanics that
+several queue implementations otherwise rewrite by hand.
+
+```ts
+await ensureJsonDurableQueueDirs({ queueDir, failedDir });
+
+const paths = resolveJsonDurableQueueEntryPaths(queueDir, id);
+await writeJsonDurableQueueEntry({
+  filePath: paths.jsonPath,
+  entry,
+  tempPrefix: "queue",
+});
+
+const pending = await loadPendingJsonDurableQueueEntries({ queueDir, tempPrefix: "queue" });
+```
+
+`id` must be a single safe path segment: non-empty, not dot-prefixed, and made
+from letters, numbers, `_`, `-`, and `.`. Slashes, backslashes, NUL bytes, `.`,
+and `..` are rejected.
+
+Use `ackJsonDurableQueueEntry()` after durable processing succeeds and
+`moveJsonDurableQueueEntryToFailed()` when the caller wants to quarantine an
+entry for inspection.
+
+## Related pages
+
+- [`fileStore`](file-store.md) — full API for the multi-file store.
+- [`jsonStore`](json-store.md) — single-file JSON store with locking.
+- [Private file-store mode](private-file-store.md) — credential-shaped variant.
+- [JSON files](json.md) — lower-level `readJson` / `writeJson` helpers.
+- [Atomic writes](atomic.md) — what `fileStore` and `jsonStore` use under the hood.