@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

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

@@ -0,0 +1,266 @@
+# 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 = {
+  durable?: boolean;               // fsync write/create/writeJson/createJson/append; default true
+  hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
+  denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
+  maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
+  mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
+  mode?: number;                   // file mode applied to new writes; per-call override available
+  nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
+  renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
+  symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
+};
+
+type DenyMutationPolicy = {
+  paths?: readonly string[];
+  prefixes?: readonly string[];
+};
+```
+
+`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, except `denyMutations`: root and per-call deny entries are merged so a call cannot clear a root-level deny.
+
+Every `maxBytes` value must be a non-negative safe integer or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` explicitly disables the cap. An omitted or explicitly `undefined` per-call value preserves the configured Root default instead of clearing it.
+
+## 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, containment, realPath, stat }
+fs.readBytes(rel, options?)    // Buffer
+fs.readText(rel, options?)     // string
+fs.readJson<T>(rel, options?)  // parsed T
+fs.open(rel, options?)         // { handle, containment, 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
+fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kind, size }>
+```
+
+`walk()` is the incremental, root-bounded recursive scan. It supports entry and
+depth budgets, cancellation, and `symlinkPolicy: "skip" |
+"follow-within-root"`. Budget exhaustion yields a `"truncated"` marker by
+default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
+Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
+`"skip-subtree"`. `"skip"` omits the current entry but still descends into a
+directory; `"skip-subtree"` omits a directory and all of its descendants.
+Directory reads remain fail-fast by default. With
+`onDirectoryError: "skip-and-report"`, the iterator instead yields
+`{ relativePath, kind: "directory-error", size: 0, error }` and continues with
+the remaining tree.
+See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
+with the standalone best-effort walkers.
+
+`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);
+  }
+}
+```
+
+`open()`, `read()`, and `openWritable()` results include
+`containment: "best-effort"`. The field reports the mechanism used; see the
+[security model](security-model.md#containment-guarantees-by-platform).
+
+The read methods also accept an absolute spelling that already resolves inside
+the root. `readAbsolute()` and `reader()` make that intent explicit and accept
+both the configured root spelling and its canonical real path when the Root was
+created through a directory symlink or Windows junction. An absolute path
+outside the root is still rejected.
+
+### 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; syncs before close by 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, options?)                 // unlink file or rmdir empty directory
+fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
+fs.ensureRoot(options?)                  // 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`).
+
+These five methods also accept `durable?: boolean`: the per-call value overrides
+`Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
+`undefined` per-call value preserves the root default. `durable: false` keeps
+the existing publication behavior, modes, and identity checks but skips file
+and parent-directory fsync calls. Use it only for reconstructible data: a crash
+may lose the write or leave the previous file. See [Writing](writing.md#write-options)
+for platform details.
+
+`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`.
+
+Root operations that choose a new destination reject a leading Windows
+drive-relative spelling such as `C:name` on every platform. This applies to
+`write`, `create`, `append`, `openWritable`, `mkdir`, `copyIn`, and the
+destination argument of `move`. In particular, `copyIn(path.basename(source),
+source)` can reject a legal POSIX basename such as `c:photo.png`; callers that
+derive portable destination names from host files must sanitize or map that
+basename first.
+
+`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.
+
+All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
+
+### 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.
+
+`resolve()` is the exception to the existing-object rule: because it selects a
+location for later use, it rejects a leading drive-relative spelling. Reads,
+`stat`, `exists`, `list`, `walk`, `remove`, and the source argument of `move`
+accept an existing POSIX filename such as `c:notes.txt`. For `move`, only the
+new destination name is subject to the portable guard.
+
+## Native helper mode
+
+Create-only writes prefer the platform native helper for fd-relative opens and
+atomic no-replace rename. Operations without native wiring retain their guarded
+JavaScript implementations.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript path
+configureFsSafeNative({ mode: "require" }); // fail if the binding is unavailable
+```
+
+`auto` is the default. Configure the mode before creating roots. See the
+[native helper policy](native-helper.md) for supported platforms, the native
+surface, and the precise fallback boundary.
+
+### 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
+
+Boundary and policy failures throw `FsSafeError` with a `code`. Parsing callbacks
+and underlying filesystem operations can also surface `SyntaxError` or native
+`NodeJS.ErrnoException` values. Branch on `err.code`, not message text, after
+checking `err instanceof FsSafeError`. Common fs-safe codes:
+
+| Code | When it fires |
+|---|---|
+| `invalid-path` | The input path is malformed, including embedded NUL bytes. Portable relative-path helpers and `FileStore` keys reject drive-relative segments; Root destination and resolution operations reject a leading drive-relative spelling such as `C:name`. |
+| `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, …). |
+| `device-path` | A read/open target is a known unsafe device or process-fd path. |
+| `already-exists` | `create()` or `move()` without `overwrite` hit an existing target. |
+| `denied-path` | A mutation target matched `denyMutations.paths` or `denyMutations.prefixes`. |
+| `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/node_modules/@openclaw/fs-safe/docs/secret-file.md

@@ -0,0 +1,273 @@
+# 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 {
+  createSecretFileAtomic,
+  readSecretFile,
+  readSecretFileSync,
+  tryReadSecretFile,
+  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` and the private parent policy are mandatory. | Standalone `writeJson` also defaults to `0o600`, but it does not enforce the secret-directory ownership and permission policy. |
+
+## 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 missing-is-optional reader. It returns the trimmed secret string, or
+`undefined` when the `filePath` argument is absent/blank or the target does not
+exist. An existing empty file is invalid and throws, as do unreadable,
+oversized, symlink, hardlink, and other validation failures.
+
+```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", "auth token");
+```
+
+### Read options
+
+```ts
+type SecretFileReadOptions = {
+  maxBytes?: number;         // default DEFAULT_SECRET_FILE_MAX_BYTES (16 KiB)
+  rejectSymlink?: boolean;   // default false
+  rejectHardlinks?: boolean; // default true
+};
+```
+
+`maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap, `Infinity` disables it, and omitted or explicitly `undefined` values preserve the 16 KiB default.
+
+The reader trims the file content and rejects empty results. Symlink paths are
+followed and pinned by default; set `rejectSymlink: true` when the pathname
+itself must not be an alias. Hardlinks are rejected by default so another
+in-tree name cannot alias the credential; pass `rejectHardlinks: false` only
+when you explicitly trust that layout.
+
+These readers do not enforce ownership or mode bits on an existing file. Their
+read contract covers pinned identity, file type, link policy, and byte bounds;
+the `0o600` guarantee belongs to the write helpers below. Use
+[`readSecureFile`](secure-file.md) when reading an externally managed
+credential must also fail on broad permissions or unexpected ownership.
+
+`readSecretFile()` and `tryReadSecretFile()` are asynchronous counterparts with
+the same pinned-handle validation, byte cap, trimming, error codes, and strict
+versus missing-is-undefined naming semantics.
+
+Both readers reject known unsafe device and process-fd paths with `device-path`
+before inspection, and check the resolved target before opening it. This includes
+Windows reserved device names and ignored-space aliases such as `nul .txt`.
+Optional readers propagate this error instead of treating the secret as missing.
+
+Both sync and async readers compare lossless bigint identities from the preview,
+opened descriptor, resolved target, and current input path before reading. POSIX
+opens are nonblocking, so a raced FIFO is rejected by descriptor type instead of
+waiting for a writer. An
+allowed symlink must still point to the opened file. On Windows, a zero device
+or inode is unverified: that inspection is retried once without reopening the
+file, preserving known identity components and link checks. Definite mismatches
+and persistent ambiguity fail with `path-mismatch`; optional reads do not treat
+these failures as missing files.
+
+If an already validated descriptor fails while reading, both readers throw an
+operational `FsSafeError` with `code: "read-failed"`; inspect `cause` for the
+underlying Node filesystem code such as `EIO`.
+
+Use the async strict reader when a service cannot start safely without the
+credential:
+
+```ts
+import { readSecretFile } from "@openclaw/fs-safe/secret";
+
+const signingKey = await readSecretFile(
+  "/var/lib/app/keys/webhook-signing.key",
+  "webhook signing key",
+  { maxBytes: 8 * 1024, rejectSymlink: true },
+);
+startWebhookVerifier(signingKey);
+```
+
+## Writing
+
+### `writeSecretFileAtomic(params)`
+
+Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
+
+Concurrent writes to distinct leaves may share creation of a missing parent.
+After a parent-creation race, the helper re-inspects the entry and requires a
+non-symlink directory, then revalidates root/parent guards, containment, and
+the requested directory mode before writing either leaf.
+
+Publication verification borrows the writer's still-open descriptor to check
+the exact file identity, regular-file and link policy, requested POSIX mode,
+and root/parent ancestry before the writer closes it. All `0o7777` mode bits
+must match, including explicitly requested special bits; unexpected special
+bits are rejected. POSIX mode overrides such as `0o000` and `0o200` do not
+require read permission or a readonly reopen, and verification does not widen
+the final mode. Windows retains pathname-identity verification without enforcing
+POSIX mode bits; its native writer checks the reopened descriptor against the
+original lossless file identity before changing the final mode.
+
+Failed JavaScript fallback writes attempt cleanup while retaining the original
+descriptor and only after checking parent and file identities. Native cleanup
+also compares lossless parent and file identities. Unverifiable paths are left
+for caller-managed cleanup, and cleanup failures do not replace the original
+write error. These are best-effort identity checks followed by name-based
+removal, not atomic conditional unlink. A publication-verification failure
+after a completed write does not authorize deleting the published file.
+
+```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 full POSIX directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. Existing directories, including another creator's `EEXIST` winner, must already match `dirMode` exactly or the write fails with `insecure-permissions`; they are never chmod-repaired. An explicitly requested directory mode such as `0o2750` preserves its setgid bit. Audit and adjust existing secret directories yourself. The admitted directory guards are retained through traversal and the final writer/lock handoff; a fresh pathname lookup cannot silently authorize a replacement. The caller must still trust the selected root and its owners; matching permission bits alone do not establish that trust.
+
+Directory admission and its retained guards use lossless bigint identities, including through private locks and native writes. On Windows, an unknown zero device or inode gets one reinspection that retains known components; a definite mismatch or persistent ambiguity fails with `path-mismatch` rather than authorizing a replacement.
+
+Both mode options must resolve to integers between `0o0000` and `0o7777`; invalid values fail with `invalid-path` before directory creation or file publication. Windows validates the options but does not enforce POSIX permission bits.
+
+After this operation wins directory creation, initialization uses a pinned descriptor bound to the admitted identity and effective user, with ancestor checks before chmod. It does not chmod the caller's pathname. Creation and descriptor admission are separate operations, not an atomic create-and-pin guarantee. A raced directory that has not reached its requested mode yet is rejected rather than repaired; callers may retry after its creator finishes initialization.
+
+Initialization fails closed if the platform cannot safely pin a created directory. In particular, a non-root macOS process cannot pin a new `000` directory produced by `umask(0o777)`; the write fails without repairing that directory or writing a secret. Restrictive masks retaining owner search permission remain usable. Linux x64/arm64 can use the guarded `O_PATH`/procfs descriptor route where available. There is no unguarded pathname-chmod fallback, and a failure may leave a created directory for caller-managed cleanup.
+
+### `createSecretFileAtomic(params)`
+
+This create-only sibling has the same directory, mode, pinned-write, and
+post-write verification policy. Final materialization uses exclusive create;
+if anything already occupies the target path it throws
+`FsSafeError("secret-exists")` without modifying that entry. Use the distinct
+name when first-writer-wins is part of the credential protocol.
+
+Distinct leaves can share missing-parent creation without a `secret-exists`
+error. Concurrent creates at the same leaf still have exactly one winner;
+the loser receives `secret-exists` and leaves the winner's bytes intact.
+
+For example, two onboarding requests may race to install the first refresh
+token. Exactly one should win, and the loser must not overwrite it:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+import { createSecretFileAtomic } from "@openclaw/fs-safe/secret";
+
+try {
+  await createSecretFileAtomic({
+    rootDir: "/var/lib/app/credentials",
+    filePath: "/var/lib/app/credentials/provider.refresh-token",
+    content: refreshToken,
+  });
+} catch (error) {
+  if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;
+  // Another initializer won. Read and validate the installed credential.
+}
+```
+
+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.
+- [Migrating to 0.5](migrating-to-0.5.md) — strict/try reads and create-only adoption checklist.

package/node_modules/@openclaw/fs-safe/docs/secure-file.md

@@ -0,0 +1,100 @@
+# 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 every non-regular preview and, by default, symlink paths
+- opens POSIX paths no-follow and nonblocking before reading, then verifies the opened fd still matches the path and realpath; a FIFO swap cannot block before `timeoutMs` owns the byte read
+- 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.
+
+Descriptor, pathname, and realpath identity checks use lossless bigint stats internally. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
+
+## 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;
+  };
+};
+```
+
+`io.maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables the cap. Invalid limits reject before filesystem admission.
+
+`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.
+
+`permissions.allowInsecure` bypasses only permission checks. Neither it nor `inject.platform` changes filesystem identity verification, which always uses the actual process platform. `trust.allowSymlink` permits an alias but still requires its target and realpath to match the opened descriptor.
+
+## 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, or filesystem identity could not be verified after bounded re-inspection. |
+| `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. |
+
+Windows inspection failures remain operational `permission-unverified` errors
+and still refuse the read. Their message includes the underlying reason when
+available. `details` includes `ownerError` for owner-query failures and, when
+command diagnostics are available, `command`, `durationMs`, `timedOut`,
+`exitCode`, `signal`, and `stderr`. Reasons and stderr are control-character
+escaped and limited to 400 characters each (including a truncation marker).
+No stdout or target file contents are copied into these display diagnostics.
+The original inspection exception is retained as `cause`; built-in command
+errors also retain their original execFile exception in the cause chain.
+Treat causes as restricted local diagnostic data. No retries are performed,
+and verification order and rejection conditions are unchanged.
+
+## 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.