@openclaw/fs-safe 0.1.0 → 0.1.2

package/docs/root.md

@@ -0,0 +1,205 @@
+# root()
+
+`root()` is the primary entry point. It takes a trusted directory and returns a capability-style `Root` handle whose methods accept relative paths and refuse to escape the directory.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const fs = await root("/srv/workspace", {
+  hardlinks: "reject",
+  symlinks: "reject",
+  mkdir: true,
+});
+```
+
+## Signature
+
+```ts
+function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
+
+type RootDefaults = {
+  hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
+  maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
+  mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append
+  mode?: number;                   // file mode applied to new writes; per-call override available
+  nonBlockingRead?: boolean;       // schedule reads on a worker; useful for large files
+  symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
+};
+```
+
+`root()` resolves the directory through the real filesystem. A symlinked input becomes the canonical path; a non-existent root throws `FsSafeError` with code `not-found`, and malformed or non-directory roots throw `invalid-path`.
+
+`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only.
+
+## The `Root` interface
+
+Every method on the returned handle accepts paths relative to the root and rejects anything that would escape it.
+
+### Reads
+
+```ts
+fs.read(rel, options?)         // { buffer, realPath, stat }
+fs.readBytes(rel, options?)    // Buffer
+fs.readText(rel, options?)     // string
+fs.readJson<T>(rel, options?)  // parsed T
+fs.open(rel, options?)         // { handle, realPath, stat, [Symbol.asyncDispose] }
+fs.readAbsolute(absPath, options?) // ReadResult; absPath must already be inside the root
+fs.reader(options?)            // (path) => Promise<Buffer>; useful for loader APIs
+```
+
+`open()` returns a Node `FileHandle` for streaming. Prefer `await using` for cleanup:
+
+```ts
+await using opened = await fs.open("large.log");
+{
+  for await (const chunk of opened.handle.createReadStream()) {
+    process.stdout.write(chunk);
+  }
+}
+```
+
+### Writes
+
+```ts
+fs.write(rel, data, options?)            // overwrite-ok atomic write
+fs.create(rel, data, options?)           // throws "already-exists" if target exists
+fs.writeJson(rel, value, options?)       // JSON.stringify + atomic write
+fs.createJson(rel, value, options?)      // create() variant of writeJson
+fs.append(rel, data, options?)           // append text/buffer; respects mkdir default
+fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
+fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
+fs.move(from, to, options?)              // rename within the root; defaults to no clobber
+fs.remove(rel)                           // unlink file or rmdir empty directory
+fs.mkdir(rel)                            // mkdir -p (creates missing parents)
+fs.ensureRoot()                          // accepts "" / "." as the root itself
+```
+
+`write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
+
+`copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
+
+`openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
+
+### Inspection (advisory)
+
+```ts
+fs.exists(rel)                   // boolean
+fs.stat(rel)                     // PathStat
+fs.list(rel)                     // string[]
+fs.list(rel, { withFileTypes })  // DirEntry[]
+fs.resolve(rel)                  // absolute path inside the root, after canonicalization
+```
+
+These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
+
+## Python helper mode
+
+On POSIX, mutation and inspection methods that need fd-relative directory
+operations go through one persistent Python helper process. This avoids a
+spawn-per-call cost while still using `openat`/`renameat`/`unlinkat`-style
+operations that Node's `fs` API does not expose ergonomically.
+
+```ts
+import { configureFsSafePython } from "@openclaw/fs-safe/config";
+
+configureFsSafePython({ mode: "off" });     // Node-only fallback path
+configureFsSafePython({ mode: "require" }); // fail if fd-relative helper unavailable
+```
+
+`auto` is the default. Configure the mode before creating roots. Without the
+helper, root methods still run, but same-UID races that swap parent directories
+between validation and mutation are harder to close completely. Use `require`
+when that downgrade should be treated as a deployment failure. See
+[Python helper policy](python-helper.md) for deployment guidance.
+
+### Properties
+
+```ts
+fs.rootDir       // the directory you passed in
+fs.rootReal      // its canonical real path (after symlink resolution)
+fs.rootWithSep   // rootReal with a trailing separator, for prefix comparisons
+fs.defaults      // the RootDefaults you passed
+```
+
+## Failure semantics
+
+Every method throws `FsSafeError` with a `code`. Branch on `err.code`, not message text. Common codes:
+
+| Code | When it fires |
+|---|---|
+| `invalid-path` | The input path is malformed, including embedded NUL bytes. |
+| `outside-workspace` | The input resolves outside the root, or contains a `..` segment that would escape it. |
+| `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). |
+| `not-file` | A read or copy targeted a non-regular file (directory, FIFO, socket, …). |
+| `already-exists` | `create()` or `move()` without `overwrite` hit an existing target. |
+| `symlink` | A path component is a symlink, and the call's `symlinks` policy is `reject`. |
+| `hardlink` | The target's `nlink > 1` and `hardlinks` policy is `reject`. |
+| `path-mismatch` | Post-open identity check failed — the opened fd does not match the resolved path. |
+| `too-large` | Read exceeded `maxBytes`. |
+
+Full list in the [Errors](errors.md) reference.
+
+## Defaults vs per-call options
+
+Defaults reduce repetition; per-call options handle exceptions:
+
+```ts
+const fs = await root("/srv/workspace", {
+  symlinks: "reject",
+  hardlinks: "reject",
+  mkdir: true,
+});
+
+// Default: symlinks rejected.
+await fs.readText("config.toml");
+
+// One specific path needs to follow a symlink that lands inside the root.
+await fs.readText("links/current.log", { symlinks: "follow-within-root" });
+```
+
+Text helpers default to UTF-8. Pass `encoding` per call to `readText`, `readJson`, `write`, `create`, or `append` when you need another encoding.
+
+## Common patterns
+
+### Read-only loader
+
+```ts
+const fs = await root("/srv/workspace", { symlinks: "reject", hardlinks: "reject" });
+const load = fs.reader();
+const a = await load("notes/today.txt");        // relative
+const b = await load("/srv/workspace/state.bin"); // absolute, but inside the root
+```
+
+`fs.reader()` returns a `(path) => Promise<Buffer>` callback. Useful when wiring `fs-safe` into APIs that accept a generic loader function. Absolute paths outside the root are rejected with `outside-workspace`.
+
+### "Touch only if missing" seeding
+
+```ts
+try {
+  await fs.create("config/seed.json", initialJson);
+} catch (err) {
+  if (err instanceof FsSafeError && err.code === "already-exists") {
+    // existing config wins
+  } else {
+    throw err;
+  }
+}
+```
+
+### Replace + verify
+
+```ts
+await fs.write("state.json", JSON.stringify(state, null, 2));
+const echoed = await fs.readJson<State>("state.json");
+assertDeepEqual(echoed, state);
+```
+
+`write` is atomic, so the file is either old or new — never half-written. Re-reading lets you detect a parallel writer, if one exists.
+
+## See also
+
+- [Reading](reading.md) — read variants in depth, plus stream patterns.
+- [Writing](writing.md) — write/create/move/remove in depth.
+- [pathScope()](path-scope.md) — the same boundary semantics over an absolute path you already trust.
+- [Atomic writes](atomic.md) — the lower-level helpers used by `fs.write`.
+- [Errors](errors.md) — the closed code union you'll be catching.

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.