@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,318 @@
+# 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.
+
+Read options are captured when the call starts. Mutating a shared options
+object while an asynchronous read is in flight cannot relax its link policy.
+
+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`.
+
+Caught `null` or `undefined` inspection and read failures are reported as
+structured errors with an `Error` cause carrying `"null"` or `"undefined"`,
+instead of an internal `TypeError` while inspecting the thrown value.
+
+A synchronous reader closes its descriptor once. A close failure preserves an
+earlier read or identity-validation error; after a successful read, the close
+failure is reported before trimming or rejecting empty content.
+
+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.
+
+Both secret writers capture top-level parameter values when called, before
+asynchronous filesystem preparation; a supplied byte buffer is captured by
+reference. A parameter getter throwing `null` or `undefined` rejects with that
+same value before filesystem inspection.
+
+On POSIX, both native and JavaScript writers verify actual `0o600` permission
+bits through the retained descriptor before writing content. A filesystem that
+reports successful chmod without enforcing those bits fails with
+`insecure-permissions` before any payload is written, including when an explicit
+`dirMode` permits other users to traverse the parent. The requested final `mode`
+is still applied after content writes, including restrictive and special-bit
+overrides. This mode-bit check does not require native ACL inspection; JavaScript
+secret writes remain available on macOS.
+
+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)
+  durable?: boolean;            // default true; false skips file and parent fsync
+};
+```
+
+`durable: false` preserves atomic publication, modes, and identity checks while
+skipping file and parent-directory `fsync` calls. Use it only for reconstructible
+data where lower latency matters more than crash-durability; private and JSON
+stores forward their durability policy here.
+
+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.
+
+If initial directory-descriptor admission fails, its original identity, ownership,
+or inspection error is preserved even when closing the rejected descriptor fails.
+Close failures after successful admission remain reportable.
+
+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.
+
+Its `durable` option also accepts `"file"`, matching `Root.create()`. This
+requires every file `fsync` to succeed, including on `EPERM`, while parent-directory
+synchronization remains best effort. The default and boolean options retain their
+existing behavior. `writeSecretFileAtomic()` continues to accept boolean durability.
+
+Strict file synchronization preserves the existing publication strategy and
+identity-checked cleanup. A failed file flush before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
+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,
+    durable: "file",
+  });
+} 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
+
+- On POSIX, the default `0600` file and `0700` directory modes restrict group and other access. They do not protect against processes with the same UID, root, attackers who can read process memory, or access granted by additional ACL entries.
+- Validation failures are tripwires, not authorization. Investigate before clearing a rejected credential file.
+- On POSIX, a file that still reports a mode other than `0600` after initialization is rejected with `insecure-permissions` before payload is written. Matching mode reports alone cannot prove that an arbitrary filesystem actually enforces those permissions.
+
+## 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,112 @@
+# 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 hardlink aliases using descriptor, pathname, and realpath link counts, then rechecks the descriptor after reading before returning bytes
+- 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 queries owner, DACL, and locality from the same open descriptor that supplies the bytes. Both native and system-command queries return the 32-bit volume serial and 64-bit file-index projection used by Node, which must equal Node's bigint descriptor receipt before its ACL facts are trusted. This avoids JavaScript number rounding but does not represent the full 128-bit file identity available on ReFS. Only the current user, LocalSystem, and built-in Administrators are trusted owner classes.
+
+Windows secure reads prefer the matching optional native package. In native `auto` or `off` mode, a missing binding or descriptor-inspection capability uses a packaged, readable PowerShell script and adjacent C# source to inspect the borrowed file handle. This route requires the [Windows security fallback prerequisites](install.md#windows-security-fallback), including permission to run the scripts under normal system policy. The command does not read file contents or reopen the pathname. Successful inspection waits for the child to exit and its output pipes to close. This emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per process for secure reads and adds PowerShell startup and compilation overhead to each inspection.
+
+Descriptor commands have a 30-second deadline. After a timeout or transport failure, fs-safe requests termination, waits at most one further second, and then rejects even if process exit or pipe closure remains unconfirmed. It closes its own output pipes and reports the observed exit separately from the termination attempt in the error cause. If the OS refuses termination, the child may retain its independently inherited Windows handle; closing the caller's descriptor cannot retarget that handle. No file bytes are returned from a failed inspection.
+
+Native `require` still rejects a missing binding or capability with `permission-unverified`, without starting a command. An available native helper's failure is terminal. On either route, fd-to-handle conversion failure, denied `READ_CONTROL`, a remote handle, incomplete descriptor, unsupported ACE form, or unavailable command support rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. The standalone reporting APIs in [`permissions`](permissions.md) retain their documented pathname fallbacks. `permissions.allowInsecure` remains the explicit escape hatch and bypasses the ACL query.
+
+Descriptor, pathname, and realpath identity checks use bigint stats internally to avoid JavaScript number rounding. 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.
+
+The helper synchronously snapshots the supplied options, including nested permission and I/O settings, the injection callback, and supplied injection environment values, before opening the file or reaching its first `await`. Mutating those objects after this snapshot does not change that read's policy. This is not an atomic snapshot at invocation entry: caller getters run during snapshot construction and can affect values or working directories that have not yet been captured. `trust.trustedDirs` must be an array with a valid length and an own string entry without null bytes at every index; malformed lengths or entries, including sparse entries filled by inherited properties, reject with `invalid-path` before filesystem admission. An omitted or empty array leaves the read unrestricted by directory.
+
+Relative trusted directories (including an empty string) are resolved to absolute lexical paths during this synchronous snapshot using Node's `path.resolve()` semantics. Windows drive-relative entries retain their per-drive current-directory semantics, and extended-length drive roots retain their root separator. Raw alternate-stream and filesystem-namespace aliases reject before normalization. Working-directory changes after the snapshot cannot redirect this allowlist. The existing realpath check still follows trusted-directory symlinks when it runs and falls back to the captured lexical path if realpath lookup fails; the allowlist does not pin directory identities.
+
+`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.
+
+On an actual Windows process with effective `platform: "win32"`, `inject.env` and `inject.exec` do not replace descriptor inspection. They remain available to simulated Windows checks on non-Windows hosts.
+
+`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, `trust.trustedDirs` contained malformed paths, or a Windows file path/trusted directory used an alternate-stream or filesystem-namespace alias. |
+| `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. |
+| `hardlink` | The descriptor, pathname, or realpath has more than one link. |
+| `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, including when descriptor-bound Windows inspection is unavailable. |
+| `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
+| `not-owned` | POSIX owner uid is not the process's effective uid. |
+| `too-large` | File size or bytes read exceeded `maxBytes`. |
+| `timeout` | `timeoutMs` elapsed while reading. |
+
+Windows descriptor-inspection failures are operational `permission-unverified`
+errors and refuse the read. The original native or descriptor-command exception is retained as
+`cause`; treat causes as restricted local diagnostic data. No pathname or ACL
+content is copied into the display message. Test adapters that simulate Windows
+on another operating system retain the standalone pathname inspector's
+structured command diagnostics (`ownerError`, `command`, `durationMs`,
+`timedOut`, `exitCode`, `signal`, and bounded escaped `stderr`). Actual Windows
+secure reads never invoke the injected pathname inspector: their optional
+command route inspects the borrowed descriptor instead. No retries are performed.
+
+## 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.