@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,252 @@
+# Install
+
+`fs-safe` is published to npm as `@openclaw/fs-safe`. It targets Node 22 or newer, ships ESM only, and works on macOS, Linux, and Windows.
+
+## Package managers
+
+```bash
+pnpm add @openclaw/fs-safe
+```
+
+```bash
+npm install @openclaw/fs-safe
+```
+
+```bash
+yarn add @openclaw/fs-safe
+```
+
+```bash
+bun add @openclaw/fs-safe
+```
+
+## Node version
+
+Minimum **Node 22**. The package uses `fs.promises`, `fs.constants.O_NOFOLLOW` where available, and `node:stream/promises`. Earlier Node releases will fail at import time.
+
+Verify the runtime:
+
+```bash
+node --version
+# v22.0.0 or newer
+```
+
+## Bun runtime
+
+Bun 1.4.2 can run the same public APIs and load the matching native package.
+On macOS and Linux, fs-safe uses its Rust N-API addon to call the system
+`realpath` implementation for native resolution. Ordinary resolution follows
+Node's component walk, including lexical normalization of expanded symlink
+targets, in Rust, with a 1,024-link expansion limit that returns `ELOOP` for
+excessive or cyclic expansion. This works around Bun path-resolution defects that
+otherwise reject restrictive permissions and confuse literal POSIX backslashes
+with directory separators. The OS still resolves symlinks and canonical file
+names; fs-safe retains its confinement and file-identity checks.
+
+This works with `bun --jitless` and needs no runtime FFI or JIT. Use native mode
+`auto` or `require` with the matching addon installed. `FS_SAFE_NATIVE_MODE=off`
+still disables all addon loading; `auto` without the addon falls back to Bun's
+resolver. Those configurations retain Bun 1.4.2's limitations with restrictive
+permissions, sockets, literal backslashes, and symlink/parent traversal. Use
+Node if you need full compatibility without the addon. On Bun POSIX, `require`
+also rejects canonicalization when the addon or its canonicalizer is unavailable.
+
+Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
+recursive directory creation receives an absolute spelling that preserves raw
+path components, working around its rejection of existing relative `.` and `..`
+directories. Windows native descriptor-relative operations require Bun to expose
+the paired libuv descriptor bridge from its host executable; a missing or partial
+bridge fails explicitly with `ENOTSUP`. Public paths and caller-supplied filesystem
+adapters remain unchanged.
+
+The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
+The adapter can be removed when the supported Bun baseline includes that fix.
+Run native compatibility checks with `pnpm test:bun:native` after building the
+package and addon. See [contributing](contributing.md) for the Node/pnpm toolchain
+and the broader diagnostic suite.
+
+## TypeScript
+
+Types ship with the package — no `@types/openclaw__fs-safe` needed. The `exports` map in `package.json` provides typed entries for every subpath:
+
+```ts
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import { writeJson } from "@openclaw/fs-safe/json";
+import { extractArchive } from "@openclaw/fs-safe/archive";
+```
+
+A working `tsconfig.json` for consumers:
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "node18",
+    "moduleResolution": "node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Subpath exports
+
+Use the main entry for the common surface, or the focused subpaths when you want a leaner import or to depend on a narrower contract:
+
+| Subpath | Contents |
+|---|---|
+| `@openclaw/fs-safe` | Common root, config, output, lock, native-mode, and error exports. |
+| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, and root-walk types. |
+| `@openclaw/fs-safe/config` | Process-global native helper and lock defaults. |
+| `@openclaw/fs-safe/path` | `isPathInside`, `safeRealpathSync`, `isWithinDir`, error helpers. |
+| `@openclaw/fs-safe/output` | Guarded staging/finalization for libraries that require an absolute output path. |
+| `@openclaw/fs-safe/json` | `tryReadJson`, `readJson`, `readJsonIfExists`, `writeJson`, sync variants. |
+| `@openclaw/fs-safe/store` | `fileStore()`, `fileStoreSync()`, and `jsonStore<T>()`. |
+| `@openclaw/fs-safe/secret` | Secret file read/write helpers. |
+| `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `writeTextAtomic`, `replaceDirectoryAtomic`, `movePathWithCopyFallback`. |
+| `@openclaw/fs-safe/durability` | Pinned directories, strict sync, durable directory creation, exclusive publication, and streaming SHA-256. |
+| `@openclaw/fs-safe/temp` | `tempWorkspace`, `withTempWorkspace`, sync variants, `resolveSecureTempRoot`. |
+| `@openclaw/fs-safe/secure-file` | `readSecureFile` for pinned absolute file reads with permissions checks. |
+| `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types. |
+| `@openclaw/fs-safe/permissions` | POSIX mode helpers, Windows ACL inspection/remediation, raw owner/ACE facts, and private-directory creation. |
+| `@openclaw/fs-safe/walk` | `walkDirectory`, `walkDirectorySync`, related types. Budget-bounded, not root-bounded. |
+| `@openclaw/fs-safe/archive` | `extractArchive`, `readArchiveEntry`, kind resolution, policy types, limits, and preflight helpers. |
+| `@openclaw/fs-safe/advanced` | Lower-level composition helpers: path scopes, root-file open, install paths, local-root readers, temp-file targets, sibling-temp writes, regular-file helpers, `pathExists`, `withTimeout`, and related advanced types. This surface is less stable than the focused public subpaths. |
+| `@openclaw/fs-safe/errors` | `FsSafeError`, `FsSafeErrorCode`. |
+| `@openclaw/fs-safe/types` | Shared types: `DirEntry`, `PathStat`, `BasePathOptions`, … |
+| `@openclaw/fs-safe/test-hooks` | Test-only hooks for injecting races. Active under `NODE_ENV=test`. |
+
+## Runtime dependencies
+
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser and zstd/bzip2 codecs for guarded [archive extraction and bounded entry reads](archive.md). Plain TAR, gzip, zstd, and bzip2 work in `off` and missing-native `auto`, including installs with all optional dependencies omitted; gzip uses Node's built-in decoder. These archive fallbacks need no runtime interpreter, download, or consumer compiler. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability. Native `require` remains strict, and an available native operation's failure never triggers a WASM retry.
+
+There are no peer dependencies. Exact-version optional packages carry the seven
+native targets and npm-compatible OS, CPU, and Linux libc filters install only
+the matching binary. Consumers do not run a Rust build, download code at
+runtime, or execute a postinstall step. Omitting optional dependencies keeps
+fallback-capable operations working in `auto` or `off`. Native-only
+features, including strict owned-tree temp cleanup, retained-directory staging,
+and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
+when the matching package is absent, incompatible, or disabled.
+No-clobber `Root.move()` preserves a native loader failure in the error's
+`cause`, including the original missing-library or incompatible-glibc diagnostic.
+
+Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
+before deploying with native mode `require` or native-only features.
+
+### Older Linux kernels and seccomp
+
+The native addon supports kernels without `openat2` (before Linux 5.6) and
+containers returning `ENOSYS` or probe-time `EPERM` for that syscall. Beneath
+opens use a guarded no-follow component walk and report `best-effort`.
+Nested no-clobber moves retain atomic `renameat2(RENAME_NOREPLACE)` and exact
+identity checks; keep native mode enabled. Strict bounded cleanup still
+requires `openat2` with `RESOLVE_NO_XDEV` and reports `helper-unavailable`
+without it. See [Linux capability behavior and limits](native.md#linux-without-openat2).
+
+### Windows security fallback
+
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+reads work without the addon in `auto` or `off` mode when system Windows
+PowerShell and its .NET `Add-Type` compilation support are available. The package
+ships a readable, fixed `.ps1` driver and adjacent `.cs` source and invokes the
+driver with Windows PowerShell `-File`. Paths are passed as data. The fallback
+does not generate helper scripts at runtime or use an encoded launcher.
+The driver addresses built-in commands by module name and limits module
+discovery to PowerShell's bundled system modules, avoiding broad command
+discovery scans during each helper startup.
+
+Normal PowerShell execution policy and Microsoft Defender policy must permit
+the packaged scripts, including their use of `Add-Type`. The package does not
+bypass restrictions, change policies, or add exclusions. Unsupported or
+disallowed command execution fails closed.
+
+The fallback preserves private DACLs at creation and inspects the same open
+handle that supplies secure-file bytes. Each capability emits a path-free
+`FS_SAFE_NATIVE_FALLBACK` warning once per process; each call adds PowerShell
+startup and compilation overhead. Execution or compilation failure also fails
+closed. Native `require` still rejects a missing binding or capability, and an
+available native operation's error never triggers a command retry. See
+[Permissions](permissions.md) and [Secure file reads](secure-file.md).
+
+## Native helper policy
+
+### Supported native platforms
+
+Prebuilt bindings cover Linux x64/arm64 (GNU glibc **2.28 or newer**, or musl),
+macOS x64/arm64, and Windows x64. The GNU baseline includes RHEL 8, Rocky Linux 8,
+and AlmaLinux 8. A compatible Node 22+ runtime and the kernel/filesystem features
+required by each operation are still necessary; a loadable addon alone does not
+guarantee every native capability. Systems older than glibc 2.28 are outside the
+GNU binary support floor.
+
+A missing or incompatible optional binding (including `ERR_DLOPEN_FAILED` from
+glibc) does not prevent importing fs-safe. In `auto`, supported JavaScript/WASM
+fallbacks remain available. Native-only operations such as the default
+no-clobber `Root.move()` still fail closed with `helper-unavailable`; `require`
+also rejects fallback-capable operations and retains the binding load error as
+the cause.
+
+### Loading modes
+
+The platform native binaries provide fd-relative open/link/mkdir primitives,
+atomic no-replace rename, and file identity checks. The default is `auto`: use
+the matching binary when it loads, otherwise use the guarded JavaScript path
+where a safe fallback exists. Native-only operations fail with
+`helper-unavailable`.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
+configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
+```
+
+Environment variables are read at runtime:
+
+```bash
+FS_SAFE_NATIVE_MODE=off      # auto | off | require
+```
+
+`OPENCLAW_FS_SAFE_NATIVE_MODE` is also accepted.
+
+Disabling native loading keeps fallback-capable operations working through Node path
+operations guarded by lexical and canonical checks plus identity verification.
+Use `require` when native-backed operations must fail instead of falling back.
+Temp workspaces retain compatible JavaScript quarantine cleanup in `auto` and
+`off`. Set `cleanupSafety: "require-bounded"` to reject before child creation
+unless native no-replace quarantine and descriptor-bounded tree removal are
+available. See the [temp workspace contract](temp.md#private-temp-workspaces). The exact boundary
+for other operations is documented in [native helper policy](native-helper.md).
+
+## Verify the install
+
+```ts
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import os from "node:os";
+import path from "node:path";
+
+const dir = path.join(os.tmpdir(), "fs-safe-smoke");
+await import("node:fs/promises").then((fs) => fs.mkdir(dir, { recursive: true }));
+
+const fs = await root(dir);
+await fs.write("hello.txt", "ok\n");
+console.log(await fs.readText("hello.txt"));
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (err instanceof FsSafeError) console.log("blocked:", err.code);
+}
+```
+
+If the script prints `ok` followed by `blocked: outside-workspace`, your install is healthy.
+
+## Next
+
+- [Quickstart](quickstart.md) — write, read, atomic, temp.
+- [Security model](security-model.md) — what the boundary defends against.
+- [Errors](errors.md) — the closed code union you'll be catching.

package/node_modules/@openclaw/fs-safe/docs/json-store.md

@@ -0,0 +1,240 @@
+# JSON store
+
+`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the single-path
+convenience wrapper for `fileStore(...).json(...)`: a small read-modify-write
+handle around a single JSON file. It bakes in atomic writes, explicit fallback
+reads, and optional cross-process locking via
+[`acquireFileLock`](sidecar-lock.md).
+
+```ts
+import { jsonStore } from "@openclaw/fs-safe/store";
+
+const settings = jsonStore<{ theme: "light" | "dark"; volume: number }>({
+  filePath: "/var/lib/app/settings.json",
+});
+
+const current = await settings.readOr({ theme: "dark", volume: 0.7 });
+await settings.write({ ...current, volume: 1 });
+await settings.updateOr({ theme: "dark", volume: 0.7 }, (prev) => ({ ...prev, theme: "light" }));
+```
+
+If you already have a store/root context, prefer binding the JSON file from that
+store:
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const files = fileStore({ rootDir: "/var/lib/app", private: true });
+const settings = files.json<Settings>("settings.json", { lock: true });
+```
+
+## When to reach for it
+
+- You have a single JSON state file and want `read / readOr / readRequired / write / update` semantics.
+- You want every write atomic at file mode `0o600` and parents at `0o700` by default.
+- You want optional cross-process locking with one boolean.
+
+For ad-hoc read/write of multiple JSON files, use the standalone helpers in
+[`json`](json.md). For object-style storage of many files at known modes, use
+[`fileStore`](file-store.md) and bind JSON files with `store.json(rel)`.
+
+## Factory: `jsonStore<T>(options)`
+
+```ts
+type JsonStoreOptions<T> = {
+  filePath: string;
+  dirMode?: number;                                // default 0o700
+  mode?: number;                                   // default 0o600
+  durable?: boolean;                              // default true
+  trailingNewline?: boolean;                       // default true
+  lock?: boolean | JsonStoreLockOptions;           // false / undefined = no lock
+};
+
+type JsonStoreLockOptions = {
+  staleMs?: number;     // default 30_000
+  timeoutMs?: number;   // default 30_000
+  retry?: FileLockRetryOptions;
+  staleRecovery?: "fail-closed" | "remove-if-unchanged";
+  managerKey?: string;  // default `fs-safe.json-store:<filePath>`
+};
+
+type JsonStore<T> = {
+  readonly filePath: string;
+  read(): Promise<T | undefined>;
+  readOr(fallback: T): Promise<T>;
+  readRequired(): Promise<T>;
+  write(value: T): Promise<void>;
+  update(run: (current: T | undefined) => T | Promise<T>): Promise<T>;
+  updateOr(fallback: T, run: (current: T) => T | Promise<T>): Promise<T>;
+};
+```
+
+`jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
+`fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
+On Windows, the factory rejects NTFS alternate-stream and directory-index
+namespace spellings before preparing its private parent. An ordinary
+drive-relative path is anchored at entry and `store.filePath` exposes the
+resulting absolute path; ordinary colon-bearing POSIX paths remain valid.
+
+`durable: false` keeps sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. The default
+is `true`, subject to platform sync support. This store-level policy applies
+to `write`, `update`, and `updateOr`; these methods have no per-call options.
+For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
+file store's durability, while omission or `undefined` inherits it. Modes,
+identity checks, mutation serialization, and sidecar locking are unchanged.
+
+Each `write`, `update`, or `updateOr` invocation captures the retained options'
+`durable` and `trailingNewline` values before queueing, locking, reading, or
+calling the updater. Changes to those options affect later invocations only,
+including when a mutation is waiting behind another operation.
+
+The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
+
+## `read()`
+
+Returns the parsed contents, or `undefined` if the file does not exist. Invalid JSON throws (via [`readJsonIfExists`](json.md)).
+
+```ts
+const state = await store.read();
+```
+
+## `readOr(fallback)`
+
+Returns the parsed contents or the per-call fallback. Object fallbacks are cloned so callers can safely mutate the returned value:
+
+```ts
+const state = await store.readOr(defaultState);
+```
+
+## `readRequired()`
+
+Strict disk read. Throws when the file is missing or invalid:
+
+```ts
+const state = await store.readRequired();
+```
+
+## `write(value)`
+
+Atomic JSON write at `mode` (default `0o600`), creating parent dirs at `dirMode` (default `0o700`) if needed. When `lock: true` is set, takes the sidecar lock for the duration of the write.
+
+```ts
+await store.write({ ...state, lastSeen: Date.now() });
+```
+
+## `update(run)`
+
+Read, transform, write — under the lock if locking is enabled. Returns the new value:
+
+```ts
+const next = await store.update((prev) => ({ count: (prev?.count ?? 0) + 1 }));
+```
+
+`run` is async-friendly. The whole `read → run → write` sequence is serialized
+by canonical file path inside the process. With locking enabled, the sidecar
+lock is acquired inside that queue, so concurrent updaters from different
+processes serialize cleanly too.
+
+Do not call `write()`, `update()`, or `updateOr()` for the same file from inside
+an update callback. That nested mutation cannot run until the outer update
+finishes, so `jsonStore` rejects it immediately with
+`FsSafeError("store-reentrant-update")`. Return the complete next value from the
+outer callback instead. The check follows Node async context, including promise
+and `queueMicrotask` boundaries.
+
+Use `update(run)` when missing state is part of your model. Use `updateOr(fallback, run)` when the missing-file case should start from a concrete value and you want to merge into defaults:
+
+```ts
+const next = await store.updateOr({ count: 0 }, (prev) => ({ count: prev.count + 1 }));
+```
+
+## Locking
+
+Set `lock: true` for default behavior, or pass an options object to tune:
+
+```ts
+const counter = jsonStore<{ count: number }>({
+  filePath: "/var/lib/app/counter.json",
+  lock: {
+    staleMs: 60_000,
+    timeoutMs: 10_000,
+    staleRecovery: "fail-closed",
+    retry: { retries: 30, minTimeout: 100, maxTimeout: 5_000, randomize: true },
+  },
+});
+```
+
+When `lock` is falsy, writes and updates still serialize inside this process by
+canonical file path, including across separate `jsonStore` handles. They offer
+no concurrency guarantees if another process also writes to the file.
+
+Process-wide lock defaults from `configureFsSafeLocks()` apply only after locking is explicitly enabled. They do not make JSON stores lock by default.
+
+JSON store locks fail closed on stale sidecars by default. Opt-in `staleRecovery: "remove-if-unchanged"` requires caller approval and uses the same exclusive reclaim guard as the low-level sidecar-lock API.
+
+The default `managerKey` namespaces the `FileLockManager` per absolute file
+path. The JSON-store queue is independent of the manager key, so separate
+handles and custom lock-manager namespaces still cannot overlap mutations of
+the same canonical file path inside one process.
+
+## Common patterns
+
+### Per-feature settings file
+
+```ts
+type Settings = { theme: "light" | "dark"; muted: boolean };
+
+const settings = jsonStore<Settings>({
+  filePath: path.join(homedir(), ".myapp/settings.json"),
+});
+
+// Read on boot
+applySettings(await settings.readOr({ theme: "dark", muted: false }));
+
+// Toggle on UI action
+await settings.update((prev) => {
+  const current = prev ?? { theme: "dark", muted: false };
+  return { ...current, muted: !current.muted };
+});
+```
+
+### Cross-process counter
+
+```ts
+const counter = jsonStore<{ count: number }>({
+  filePath: "/var/lib/app/counter.json",
+  lock: true,
+});
+
+const { count } = await counter.updateOr({ count: 0 }, (prev) => ({ count: prev.count + 1 }));
+console.log("now at", count);
+```
+
+### Migration on boot
+
+```ts
+const config = jsonStore<Config>({ filePath });
+const current = await config.readOr(defaultConfig);
+if (current.version !== CURRENT_VERSION) {
+  await config.write(migrate(current));
+}
+```
+
+## Difference from raw `writeJson` / `readJsonIfExists`
+
+| `jsonStore` | Raw helpers |
+|---|---|
+| Read-modify-write in one call (`update`). | Compose `readJsonIfExists` + `writeJson` yourself. |
+| Optional cross-process lock with one flag. | Manage `withFileLock` yourself. |
+| Explicit `readOr` / `updateOr` fallbacks. | Caller handles `null` and clones. |
+| Mode/dirMode locked per store. | Per-call. |
+
+`jsonStore` is the right shape when one file owns one piece of state and many call sites read or update it. For one-off writes, the raw helpers are leaner.
+
+## See also
+
+- [JSON files](json.md) — the standalone helpers `jsonStore` is built on.
+- [File lock](sidecar-lock.md) — the cross-process lock used when `lock: true`.
+- [File store](file-store.md) — the multi-file equivalent of this surface.