@openclaw/fs-safe 0.1.0 → 0.1.2

package/docs/testing.md

@@ -0,0 +1,168 @@
+# Testing
+
+`@openclaw/fs-safe/test-hooks` exposes a small set of test-only injection points. They are inert in production: the hooks only activate when `process.env.NODE_ENV === "test"`. Outside test mode, calls to set hooks are no-ops, so leaking a test setup line into production is safe but ineffective.
+
+```ts
+import {
+  __setFsSafeTestHooksForTest,
+  type FsSafeTestHooks,
+} from "@openclaw/fs-safe/test-hooks";
+```
+
+The double-underscore prefix is a deliberate "hands off" signal: production code should never import this module. ESLint or your equivalent linter should flag it.
+
+## When to reach for hooks
+
+- Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
+- Force Node-only behavior without uninstalling Python from your runners.
+- Inject latency to test cancellation/timeout paths.
+
+If you don't need to inject a race, you don't need hooks — most tests should drive the library through normal calls and assert on observable behavior.
+
+## Hooks API
+
+```ts
+type FsSafeTestHooks = {
+  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+  afterOpen?: (filePath: string, handle: import("node:fs/promises").FileHandle) => Promise<void> | void;
+};
+
+function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
+function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
+```
+
+Hooks are called at well-defined points in the library's hot paths:
+
+- **`afterPreOpenLstat`** — runs after the pre-open `lstat`. A common use is to swap the path's target via `fs.symlink`/`fs.unlink` to drive a TOCTOU race.
+- **`beforeOpen`** — runs before `fs.open` with the exact flags the root read path will use.
+- **`afterOpen`** — runs after the file handle is opened. Useful to wrap handle methods or inject a size race before a stream is consumed.
+
+`__setFsSafeTestHooksForTest(undefined)` clears all hooks. Always clean up between tests.
+
+## Example: simulate a TOCTOU swap
+
+```ts
+import { describe, it, beforeEach, afterEach, expect } from "vitest";
+import { mkdtemp, mkdir, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(os.tmpdir(), "fs-safe-toctou-"));
+  await writeFile(path.join(dir, "real.txt"), "secret");
+  await writeFile(path.join(dir, "decoy.txt"), "decoy");
+});
+afterEach(async () => {
+  __setFsSafeTestHooksForTest(undefined);
+  await rm(dir, { recursive: true, force: true });
+});
+
+it("rejects a swap between resolve and open", async () => {
+  const fs = await root(dir, { symlinks: "reject" });
+
+  __setFsSafeTestHooksForTest({
+    afterPreOpenLstat: async (absPath) => {
+      // swap real.txt for a symlink to decoy.txt right before the open
+      await unlink(absPath);
+      await symlink(path.join(dir, "decoy.txt"), absPath);
+    },
+  });
+
+  await expect(fs.read("real.txt")).rejects.toMatchObject({
+    name: "FsSafeError",
+    code: expect.stringMatching(/symlink|path-mismatch/),
+  });
+});
+```
+
+The `code` may be `symlink` (caught at open by `O_NOFOLLOW`) or `path-mismatch` (caught by the post-open identity check) depending on platform — both are correct refusals.
+
+## Example: force Node-only fallback behavior
+
+```ts
+import { configureFsSafePython } from "@openclaw/fs-safe/config";
+
+beforeEach(() => {
+  configureFsSafePython({ mode: "off" });
+});
+
+afterEach(() => {
+  configureFsSafePython({ mode: "auto", pythonPath: undefined });
+});
+
+it("runs without the Python helper", async () => {
+  const fs = await root(dir);
+  await fs.write("file.txt", "ok");
+  await expect(fs.readText("file.txt")).resolves.toBe("ok");
+});
+```
+
+## Cleanup is mandatory
+
+Hooks set by `__setFsSafeTestHooksForTest` persist across tests until explicitly cleared. Always clear in `afterEach` (or your test framework's equivalent) — leaked hooks will silently change behavior in unrelated tests and cause maddening intermittent failures.
+
+```ts
+import { afterEach } from "vitest";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+afterEach(() => {
+  __setFsSafeTestHooksForTest(undefined);
+});
+```
+
+A global hook clear in your test setup file is a good safety net.
+
+## Patterns for testing fs-safe-using code
+
+You usually don't need hooks. Most tests follow this shape:
+
+```ts
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { root } from "@openclaw/fs-safe";
+
+let dir: string;
+let fs: Awaited<ReturnType<typeof root>>;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(os.tmpdir(), "my-feature-"));
+  fs = await root(dir, { symlinks: "reject", hardlinks: "reject", mkdir: true });
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+it("writes and reads through the boundary", async () => {
+  await fs.write("notes/today.txt", "hello");
+  expect(await fs.readText("notes/today.txt")).toBe("hello");
+});
+```
+
+For tests that need a private temp workspace, [`withTempWorkspace`](temp.md) makes the setup-and-teardown story trivial.
+
+## Repo test shards
+
+Run the full local gate before handoff:
+
+```sh
+pnpm check
+```
+
+Run only the security boundary corpus while iterating on root/path/archive/temp hardening:
+
+```sh
+pnpm test:security
+```
+
+`pnpm check` also runs `pnpm lint:file-size`. New source and test files should stay under 500 lines. Existing larger files have explicit budgets in `scripts/check-file-size.mjs`; do not increase those budgets as part of unrelated work.
+
+## See also
+
+- [Security model](security-model.md) — what the boundary is supposed to defend; design tests around the same threats.
+- [`root()`](root.md) — the surface most tests will exercise.
+- [Temp workspaces](temp.md) — `withTempWorkspace` for cleanup-on-exit test directories.

package/docs/timing.md

@@ -0,0 +1,121 @@
+# Timing
+
+`withTimeout(promise, timeoutMs, labelOrOptions?)` is a small helper for putting a wall-clock ceiling on an async operation. It rejects with a synthetic timeout error after `timeoutMs` and clears its internal timer when the wrapped promise settles first.
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+```
+
+## Signature
+
+```ts
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  labelOrOptions?: string | {
+    label?: string;
+    message?: string;
+    createError?: () => Error;
+  },
+): Promise<T>;
+```
+
+If `timeoutMs` is `0`, negative, `Infinity`, or `NaN`, the helper is a no-op and simply awaits the original promise.
+
+## Examples
+
+### Simple ceiling
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+
+const buf = await withTimeout(
+  fs.readFile("/srv/big.bin"),
+  5_000,
+  "read big.bin",
+);
+```
+
+If the read doesn't resolve within 5 seconds, the returned promise rejects with `Error: read big.bin timed out after 5000ms`. The underlying `fs.readFile` continues until Node finishes it — `withTimeout` does not cancel the wrapped work, only the wait.
+
+### Custom message
+
+```ts
+await withTimeout(work(), 5_000, {
+  message: "build did not finish in time",
+});
+```
+
+### Custom error factory
+
+```ts
+class BuildTimeout extends Error {}
+
+await withTimeout(work(), 5_000, {
+  createError: () => new BuildTimeout("build timeout (5s)"),
+});
+```
+
+`createError` is called when the timer fires; the returned error is what the promise rejects with. Use this when callers branch on `instanceof` or want a custom `cause`.
+
+## Cancellation
+
+`withTimeout` does **not** abort the wrapped operation when the timer fires — it just stops waiting. If you need real cancellation, the wrapped operation must opt into an `AbortSignal` itself:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(), 5_000);
+
+try {
+  const res = await fetch(url, { signal: controller.signal });
+  // ...
+} finally {
+  clearTimeout(timer);
+}
+```
+
+For the common "I want a deadline AND cancellation" shape, use `AbortSignal.timeout(ms)` directly — it's the standard library's answer and handles both at once.
+
+## Patterns
+
+### Bound a credential refresh
+
+```ts
+const fresh = await withTimeout(
+  refreshToken(currentRefresh),
+  5_000,
+  "refresh oauth token",
+);
+await writeSecretFileAtomic({ rootDir, filePath, content: JSON.stringify(fresh) });
+```
+
+### Compose with archive extraction
+
+```ts
+import { extractArchive } from "@openclaw/fs-safe/archive";
+
+await extractArchive({
+  archivePath,
+  destDir,
+  kind: "zip",
+  timeoutMs: 30_000,
+});
+```
+
+`extractArchive` already takes `timeoutMs` and uses `withTimeout` internally — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
+
+### Disable in tests
+
+When unit-testing flaky code, you might want to disable the timeout. Pass `0`:
+
+```ts
+await withTimeout(work(), process.env.NODE_ENV === "test" ? 0 : 5_000, "work");
+```
+
+Better, gate it from the caller — `withTimeout(p, 0, ...)` returns the promise as-is.
+
+## See also
+
+- [Archive extraction](archive.md) — `extractArchive` already takes `timeoutMs`.
+- [File lock](sidecar-lock.md) — retry policy is a different form of bounded waiting.
+- [`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) — standard-library cancellation when you need to *abort*, not just *give up*.

package/docs/types.md

@@ -0,0 +1,155 @@
+# Types
+
+The types most callers reach for. Shared data shapes are exported from `@openclaw/fs-safe/types`; method-specific option/result types live next to their subpath.
+
+```ts
+import type {
+  BasePathOptions,
+  DirEntry,
+  FastPathMode,
+  PathStat,
+  SafeEncoding,
+} from "@openclaw/fs-safe/types";
+```
+
+## `PathStat`
+
+```ts
+type PathStat = {
+  kind: "file" | "directory" | "symlink" | "fifo" | "socket" | "blockDevice" | "characterDevice" | "unknown";
+  size: number;       // bytes
+  mtimeMs: number;    // milliseconds since epoch
+  mode: number;       // POSIX mode bits
+  nlink: number;      // hardlink count
+};
+```
+
+The shape returned by `Root.stat()`. A trimmed view of `node:fs.Stats` — only the fields the boundary cares about. Use `kind` instead of inspecting the various `is*` methods on a Node `Stats` object; it covers every case in one switchable string.
+
+## `DirEntry`
+
+```ts
+type DirEntry = PathStat & {
+  name: string;       // base name within the listed directory
+};
+```
+
+Returned by `Root.list(rel, { withFileTypes: true })`. Includes the same `kind`/`size`/etc as `PathStat`, plus the entry's `name`.
+
+## `BasePathOptions`
+
+```ts
+type BasePathOptions = {
+  fastPathMode?: FastPathMode;
+};
+
+type FastPathMode = "auto" | "never" | "require";
+```
+
+Options shared by helpers that can take a "fast path" (use cheaper syscalls when the input is already absolute and clearly inside scope). The default is `"auto"` — let the helper pick. Force `"never"` in tests if you want to exercise the slow path. Force `"require"` if you need to assert that the fast path is taken (the helper throws if it can't).
+
+Most callers don't need to touch this.
+
+## `SafeEncoding`
+
+```ts
+type SafeEncoding = BufferEncoding | null;
+```
+
+Used by helpers that accept either an encoding (returning a string) or `null` (returning a `Buffer`). The Node `BufferEncoding` type is widened to include `null` for "give me bytes."
+
+## `OpenResult` / `ReadResult`
+
+Returned by `Root.open()` and `Root.read()`:
+
+```ts
+type OpenResult = {
+  handle: import("node:fs/promises").FileHandle;
+  realPath: string;
+  stat: import("node:fs").Stats;
+};
+
+type ReadResult = {
+  buffer: Buffer;
+  realPath: string;
+  stat: import("node:fs").Stats;
+};
+```
+
+`realPath` is the canonical real path the read or open landed on, after symlink resolution; `stat` is the verified `fstat` result.
+
+## `RootDefaults` / `RootOptions`
+
+```ts
+type RootDefaults = {
+  hardlinks?: "reject" | "allow";
+  maxBytes?: number;
+  mkdir?: boolean;
+  mode?: number;
+  nonBlockingRead?: boolean;
+  symlinks?: "reject" | "follow-within-root";
+};
+
+type RootOptions = {
+  rootDir: string;
+  defaults?: RootDefaults;
+};
+```
+
+`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these.
+
+## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
+
+```ts
+type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+type RootWriteOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+  encoding?: BufferEncoding;
+  overwrite?: boolean;
+};
+type RootCopyOptions = Pick<RootDefaults, "maxBytes" | "mkdir" | "mode"> & {
+  sourceHardlinks?: "reject" | "allow";
+};
+type RootOpenWritableOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+  writeMode?: "replace" | "append" | "update";
+};
+type RootWriteJsonOptions = RootWriteOptions & {
+  replacer?: Parameters<typeof JSON.stringify>[1];
+  space?: Parameters<typeof JSON.stringify>[2];
+  trailingNewline?: boolean;
+};
+type RootAppendOptions = RootWriteOptions & {
+  prependNewlineIfNeeded?: boolean;
+};
+```
+
+Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
+
+## `SymlinkPolicy` / `HardlinkPolicy`
+
+```ts
+type SymlinkPolicy = "reject" | "follow-within-root";
+type HardlinkPolicy = "reject" | "allow";
+```
+
+The two policy unions you'll see throughout. `"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for both symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+
+## `FsSafeErrorCode` / `FsSafeErrorCategory`
+
+```ts
+type FsSafeErrorCode =
+  | "already-exists" | "hardlink" | "helper-failed" | "helper-unavailable"
+  | "insecure-permissions" | "invalid-path" | "not-empty" | "not-file"
+  | "not-found" | "not-owned" | "not-removable" | "outside-workspace"
+  | "path-alias" | "path-mismatch" | "permission-unverified"
+  | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+```
+
+Closed union you switch on. See the [Errors](errors.md) reference for what each one means.
+
+`FsSafeError.category` is `"policy"` for unsafe input/target-state failures and `"operational"` for environment/runtime failures.
+
+## See also
+
+- [`root()`](root.md) — how `RootDefaults` and `Root*Options` are used.
+- [Errors](errors.md) — the closed code union in context.
+- [Reading](reading.md), [Writing](writing.md) — option shapes per verb.

package/docs/walk.md

@@ -0,0 +1,63 @@
+# Directory walking
+
+`walkDirectory()` and `walkDirectorySync()` provide budget-bounded directory scans for callers that would otherwise hand-roll recursive `readdir()` loops. The bounds are `maxDepth` and `maxEntries`; this helper does not create a security boundary. Use [`root()`](root.md) when the path itself is caller-influenced.
+
+```ts
+import { walkDirectory } from "@openclaw/fs-safe/walk";
+
+const scan = await walkDirectory("/safe/workspace", {
+  maxDepth: 3,
+  maxEntries: 10_000,
+  symlinks: "skip",
+  include: (entry) => entry.kind === "file",
+  descend: (entry) => entry.name !== ".git",
+});
+
+if (scan.truncated) {
+  throw new Error("workspace scan exceeded entry budget");
+}
+```
+
+## Result
+
+```ts
+type WalkDirectoryResult = {
+  entries: WalkDirectoryEntry[];
+  scannedEntryCount: number;
+  truncated: boolean;
+};
+
+type WalkDirectoryEntry = {
+  name: string;
+  path: string;
+  relativePath: string;
+  depth: number;
+  kind: "file" | "directory" | "symlink" | "other";
+  dirent: import("node:fs").Dirent;
+};
+```
+
+`depth` starts at `1` for direct children of `rootDir`. `relativePath` is always relative to the supplied root. `scannedEntryCount` counts directory entries examined, including entries filtered out by `include`.
+
+## Options
+
+```ts
+type WalkDirectoryOptions = {
+  maxDepth?: number;
+  maxEntries?: number;
+  symlinks?: "skip" | "follow" | "include";
+  include?: (entry: WalkDirectoryEntry) => boolean;
+  descend?: (entry: WalkDirectoryEntry) => boolean;
+};
+```
+
+`symlinks` defaults to `"skip"`. `"include"` returns symlink entries without following them. `"follow"` resolves symlinks with `stat()` and may descend into linked directories, so use it only when that is intentional. Already-visited real directories are skipped so symlink cycles do not recurse forever.
+
+`include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
+
+Unreadable directories are skipped. This makes the helper suitable for best-effort inventories and pruning jobs; use a stricter root-bounded operation when every entry must be accounted for.
+
+## See also
+
+- [`fileStore`](file-store.md) — managed stores use bounded walking for pruning.
+- [Path scopes](path-scope.md) — boundary checks for known absolute paths.