@openclaw/fs-safe 0.1.1 → 0.2.0

package/docs/path.md

@@ -0,0 +1,191 @@
+# Path helpers
+
+`@openclaw/fs-safe/path` is the lower-level lexical and canonical path surface — useful when you have your own logic that needs to know "is this path inside that directory" without going through `root()` or `pathScope()`.
+
+```ts
+import {
+  isPathInside,
+  isPathInsideWithRealpath,
+  isWithinDir,
+  resolveSafeBaseDir,
+  safeRealpathSync,
+  safeStatSync,
+  assertNoNulPathInput,
+  isNotFoundPathError,
+  isSymlinkOpenError,
+  hasNodeErrorCode,
+} from "@openclaw/fs-safe/path";
+```
+
+Only `root()`, `FsSafeError`, and the Python helper config live on the main entry. Path helpers are deliberately a subpath import so the main entry stays small.
+
+## Boundary checks
+
+### `isPathInside(rootDir, target)`
+
+Pure lexical check. Returns `true` if `target` is `rootDir` itself or a descendant, after normalizing both inputs. **Does not** touch the filesystem — does not follow symlinks.
+
+```ts
+isPathInside("/srv/uploads", "/srv/uploads/photo.jpg");      // true
+isPathInside("/srv/uploads", "/srv/uploads/../escape.txt");  // false
+isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
+isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
+```
+
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison.
+
+### `isPathInsideWithRealpath(rootDir, target, opts?)`
+
+Synchronous. Same as `isPathInside`, but resolves both inputs through `realpath` first. Use this when you want the canonical answer and either input might be a symlink.
+
+```ts
+isPathInsideWithRealpath("/srv/uploads", "/srv/symlink-to-elsewhere"); // false
+```
+
+```ts
+type Options = {
+  requireRealpath?: boolean;            // default true
+  cache?: Map<string, string>;
+};
+```
+
+Does not throw on missing inputs — `realpath` failures are absorbed by the underlying `safeRealpathSync`. By default (`requireRealpath: true`) the function returns `false` when either input cannot be resolved. Pass `{ requireRealpath: false }` to fall back to the lexical answer from `isPathInside` instead.
+
+### `isWithinDir(rootDir, targetPath)`
+
+Convenience wrapper around `isPathInside`. Same semantics, different name kept for callers that prefer the noun phrase.
+
+### `resolveSafeBaseDir(rootDir)`
+
+Resolve a base directory to an absolute, normalized form ready for prefix comparison. Pre-normalized directories make subsequent `isPathInside` checks unambiguous.
+
+```ts
+const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads"
+```
+
+## Realpath and stat
+
+### `safeRealpathSync(targetPath, cache?)`
+
+Synchronous `realpath` that returns `null` instead of throwing on any error. Pass an optional `Map<string, string>` to cache results across calls within a single operation.
+
+```ts
+const real = safeRealpathSync("/srv/uploads/photo.jpg");
+if (real === null) return notFound();
+```
+
+All `realpath` failures collapse to `null` — there is no distinction between `ENOENT`, `EACCES`, and other I/O errors. Use `fs.realpathSync` directly if you need to branch on the error code.
+
+### `safeStatSync(targetPath)`
+
+Synchronous `stat` that returns `null` instead of throwing on missing paths. Returns `Stats` on success.
+
+```ts
+const stat = safeStatSync("/srv/uploads/photo.jpg");
+if (!stat?.isFile()) return notFound();
+```
+
+### `assertNoNulPathInput(filePath, message?)`
+
+Throws `FsSafeError` with code `invalid-path` when a path string contains an embedded NUL byte. Use it before calling Node `fs` APIs directly; Node's native error can include raw path text in the message.
+
+## Error inspection
+
+### `isNotFoundPathError(err)`
+
+`true` if the error is a `NodeJS.ErrnoException` with code `ENOENT` (file or directory missing).
+
+```ts
+try {
+  await fs.readFile(p);
+} catch (err) {
+  if (isNotFoundPathError(err)) return null;
+  throw err;
+}
+```
+
+### `isSymlinkOpenError(err)`
+
+`true` if the error indicates a symlink-related open failure (typically `ELOOP` or platform-specific symlink rejections from `O_NOFOLLOW`).
+
+### `hasNodeErrorCode(err, code)`
+
+Generic helper. `true` if `err` is a `NodeJS.ErrnoException` with the matching `code` string.
+
+```ts
+if (hasNodeErrorCode(err, "EACCES")) return reply(403);
+```
+
+## When to use these vs `root()`
+
+| Path helpers | `root()` |
+|---|---|
+| Pure functions over absolute path strings. | Boundary handle with method-style I/O. |
+| No I/O performed (except `safeRealpathSync`/`safeStatSync`). | Every method goes to disk. |
+| Fits inside other helpers / validation pipelines. | Standalone consumer of caller-supplied paths. |
+
+If you're writing a validator that says "is this safe?" without performing the operation, the path helpers are the right tool. If you're going to perform the read or write, use `root()` so the boundary check is fused with the operation.
+
+## Common patterns
+
+### "Resolve, then assert it's inside my dir"
+
+```ts
+import { isPathInsideWithRealpath, isNotFoundPathError } from "@openclaw/fs-safe/path";
+
+let canonical: string;
+try {
+  canonical = await fs.realpath(input);
+} catch (err) {
+  if (isNotFoundPathError(err)) return reply(404);
+  throw err;
+}
+if (!isPathInsideWithRealpath("/srv/uploads", canonical)) {
+  return reply(403);
+}
+```
+
+### Cache realpaths in a request scope
+
+```ts
+const cache = new Map<string, string>();
+for (const p of inputs) {
+  const real = safeRealpathSync(p, cache);
+  if (real && isPathInside(root, real)) keep.push(real);
+}
+```
+
+### Branch on `ENOENT` vs other errors
+
+```ts
+try {
+  return await fs.readFile(p);
+} catch (err) {
+  if (isNotFoundPathError(err)) return null;
+  if (hasNodeErrorCode(err, "EACCES")) return null;
+  throw err;
+}
+```
+
+## Path-policy helpers
+
+`path-policy.ts` exposes two assertions used by `root()` internally; they are exported for callers building their own helpers:
+
+```ts
+import {
+  assertNoPathAliasEscape,
+  assertNoHardlinkedFinalPath,
+  PATH_ALIAS_POLICIES,
+} from "@openclaw/fs-safe/advanced";
+```
+
+- `assertNoPathAliasEscape({ rootRealPath, candidatePath, policy })` — async. Asserts the candidate's resolved real path is inside the root. Configurable via `PATH_ALIAS_POLICIES` (which currently ships only the default `"strict"` policy).
+- `assertNoHardlinkedFinalPath({ filePath })` — async. Throws if the file at `filePath` has `nlink > 1`.
+
+Use these when writing a custom helper that wants the same guards `root()` uses but with different surrounding logic.
+
+## See also
+
+- [`root()`](root.md) — the high-level boundary that uses these checks internally.
+- [`pathScope()`](path-scope.md) — `Result`-style scope checks.
+- [Reading](reading.md) — `Root.read()` and friends use `isPathInside` + identity checks.

package/docs/permissions.md

@@ -0,0 +1,95 @@
+# Permissions
+
+`@openclaw/fs-safe/permissions` contains the curated mode and permission inspection helpers used by secure file reads and by applications that want to report actionable permission problems.
+
+```ts
+import {
+  formatPermissionDetail,
+  formatPermissionRemediation,
+  inspectPathPermissions,
+} from "@openclaw/fs-safe/permissions";
+
+const perms = await inspectPathPermissions("/var/lib/app/auth.token");
+console.log(formatPermissionDetail("/var/lib/app/auth.token", perms));
+if (perms.ok && (perms.groupReadable || perms.worldReadable)) {
+  console.log(
+    formatPermissionRemediation({
+      targetPath: "/var/lib/app/auth.token",
+      perms,
+      isDir: false,
+      posixMode: 0o600,
+    }),
+  );
+}
+```
+
+## POSIX helpers
+
+```ts
+safeStat(path);
+inspectPathPermissions(path, options?);
+formatPermissionDetail(path, check);
+formatPermissionRemediation({ targetPath, perms, isDir, posixMode });
+modeBits(mode);
+formatOctal(bits);
+isWorldWritable(bits);
+isGroupWritable(bits);
+isWorldReadable(bits);
+isGroupReadable(bits);
+```
+
+`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below.
+
+## Advanced Windows ACL helpers
+
+The low-level Windows ACL parser and `icacls` command builders live in `@openclaw/fs-safe/advanced`:
+
+```ts
+import {
+  createIcaclsResetCommand,
+  formatIcaclsResetCommand,
+  formatWindowsAclSummary,
+  inspectWindowsAcl,
+  parseIcaclsOutput,
+  resolveWindowsUserPrincipal,
+  summarizeWindowsAcl,
+} from "@openclaw/fs-safe/advanced";
+
+inspectWindowsAcl(path, { env, exec });
+parseIcaclsOutput(output, targetPath);
+summarizeWindowsAcl(entries, env);
+formatWindowsAclSummary(summary);
+formatIcaclsResetCommand(targetPath, { isDir, env });
+createIcaclsResetCommand(targetPath, { isDir, env });
+resolveWindowsUserPrincipal(env);
+```
+
+The default Windows inspector calls `icacls.exe /sid` and classifies principals as trusted, world, or group. Trusted defaults include the current user, SYSTEM, and Administrators. The parser is on the advanced surface so tests and CLIs can process captured `icacls` output without spawning a process.
+
+Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
+
+## Types
+
+```ts
+type PermissionCheck = {
+  ok: boolean;
+  isSymlink: boolean;
+  isDir: boolean;
+  mode: number | null;
+  bits: number | null;
+  source: "posix" | "windows-acl" | "unknown";
+  worldWritable: boolean;
+  groupWritable: boolean;
+  worldReadable: boolean;
+  groupReadable: boolean;
+  aclSummary?: string;
+  error?: string;
+};
+```
+
+`ok: false` means the path itself could not be inspected. `ok: true` with `source: "unknown"` means basic stat information was available, but the platform-specific permission source could not be verified.
+
+## See also
+
+- [Secure file reads](secure-file.md) — fd-pinned reads that enforce these checks.
+- [Errors](errors.md) — permission-related `FsSafeError` codes.

package/docs/private-file-store.md

@@ -0,0 +1,45 @@
+# Private file-store mode
+
+Private state is not a separate store family. Use `fileStore({ private: true })`
+when a directory holds credentials, tokens, auth profiles, or other private
+JSON/text state.
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const store = fileStore({ rootDir: "/var/lib/app", private: true });
+
+await store.writeJson("state.json", state);
+const loaded = await store.readJsonIfExists<State>("state.json");
+```
+
+## Behavior
+
+- Writes create parent directories at `0o700` and files at `0o600` unless you
+  pass stricter `dirMode` / `mode` options.
+- Private-mode writes route through the secret-file atomic path, which refuses
+  symlink parent components and re-asserts mode after rename.
+- `readText()` and `readJson()` are strict and throw on missing files.
+- `readTextIfExists()` and `readJsonIfExists()` return `null` on missing files.
+- `write()`, `writeText()`, `writeJson()`, `writeStream()`, and `copyIn()` all
+  keep the same root-relative `FileStore` shape.
+
+## Sync writes
+
+Use `fileStoreSync({ private: true })` for boot paths or sync-only integration
+points:
+
+```ts
+import { fileStoreSync } from "@openclaw/fs-safe/store";
+
+fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json", config);
+```
+
+The sync store intentionally exposes a smaller surface: path resolution,
+lenient reads, and atomic text/JSON writes.
+
+## See also
+
+- [`fileStore`](file-store.md) — full store API.
+- [Secret files](secret-file.md) — standalone credential file reads and writes.
+- [JSON files](json.md) — strict/lenient JSON helpers without a bound store.

package/docs/python-helper.md

@@ -0,0 +1,103 @@
+---
+title: Python helper policy
+description: "How fs-safe uses its optional persistent Python helper, how to configure it, and what Node-only mode changes."
+---
+
+# Python helper policy
+
+`fs-safe` is a Node library. On POSIX systems, it can optionally keep one persistent Python helper process for filesystem operations that Node does not expose ergonomically as fd-relative APIs.
+
+The helper is not a sandbox and does not add new authority. It uses the same process user and the same filesystem permissions as your Node process. Its job is narrower: reduce race windows around parent-directory mutations after a root boundary has already been chosen.
+
+## Default
+
+The package default is:
+
+```ts
+configureFsSafePython({ mode: "auto" });
+```
+
+`auto` means:
+
+- use the helper for supported POSIX operations when it starts successfully;
+- fall back to Node-only behavior when Python is missing, disabled by the host, or unavailable;
+- keep the public API working in ordinary desktop, CI, Docker, and bundled-app environments.
+
+Applications can choose a stricter or simpler policy before the first filesystem operation:
+
+```ts
+import { configureFsSafePython } from "@openclaw/fs-safe/config";
+
+configureFsSafePython({ mode: "off" });     // never spawn Python
+configureFsSafePython({ mode: "require" }); // fail closed if helper cannot start
+```
+
+Environment variables provide the same policy:
+
+```bash
+FS_SAFE_PYTHON_MODE=auto      # auto | off | require
+FS_SAFE_PYTHON=/usr/bin/python3
+```
+
+OpenClaw compatibility aliases are accepted too: `OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`, `OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`.
+
+## What the helper does
+
+Node's `fs` API is path-string oriented. It exposes `O_NOFOLLOW`, file handles, and some identity checks, but not a complete ergonomic `openat` / `renameat` / `unlinkat` / `mkdirat` surface for every operation `root()` needs.
+
+The helper fills that gap for supported POSIX operations:
+
+- stat/list paths relative to an already-open root directory;
+- create directories while walking from a pinned parent;
+- remove entries relative to a pinned parent;
+- move entries with fd-relative rename semantics;
+- run parent-fd write paths used by atomic replacement helpers.
+
+`fs-safe` sends requests to the helper over a JSON-lines protocol. It is one persistent process per Node process, not one Python spawn per filesystem call.
+
+## What you lose with `mode: "off"`
+
+Node-only mode still keeps the important application-level guardrails:
+
+- root-relative path validation;
+- canonical root checks;
+- no-follow opens where Node/platform support exists;
+- file identity checks around reads and writes;
+- atomic sibling-temp replacement;
+- hardlink/symlink policy checks where the API requests them;
+- byte limits and structured `FsSafeError` failures.
+
+What gets weaker is the POSIX defense against another same-UID process swapping a parent directory between validation and mutation. Without fd-relative mutation, `root().move()`, `root().remove()`, `root().mkdir()`, and some write paths rely on Node path operations plus pre/post checks instead of parent-fd syscalls.
+
+That is usually acceptable when the root directory is only writable by the trusted application user. It is not the right posture if untrusted local processes can race writes in the same tree and you are relying on `fs-safe` as part of the security boundary.
+
+## Choosing a mode
+
+| Mode | Use when |
+|---|---|
+| `auto` | You want the strongest available POSIX path when Python exists, but installs should still work without it. This is the package default. |
+| `off` | You want deterministic Node-only behavior, no Python process, or a runtime that forbids spawning Python. |
+| `require` | The fd-relative helper is part of your security posture and startup/runtime should fail closed if it is unavailable. |
+
+If you deploy with `require`, set `FS_SAFE_PYTHON` to an absolute interpreter path and test it in the same container, bundle, service manager, or sandbox that runs your app.
+
+## Application defaults
+
+Libraries should normally leave the package default alone. Applications can set a process-global policy once at startup:
+
+```ts
+import { configureFsSafePython } from "@openclaw/fs-safe/config";
+
+if (!process.env.FS_SAFE_PYTHON_MODE) {
+  configureFsSafePython({ mode: "off" });
+}
+```
+
+This is the right shape for apps that want to make Python an explicit operator choice while still letting deployment env vars opt back into `auto` or `require`.
+
+## Related pages
+
+- [Security model](security-model.md) — what `root()` does and does not promise.
+- [Root API](root.md) — root-bounded read/write/move/remove methods.
+- [Errors](errors.md) — `helper-unavailable` and `helper-failed` handling.
+- [Testing](testing.md) — forcing helper modes in tests.

package/docs/quickstart.md

@@ -0,0 +1,147 @@
+# Quickstart
+
+Five minutes. By the end you will have a working `root()` and know how to read, write, atomically replace, and unpack an archive — without your code being able to escape the workspace.
+
+If you have used Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), this is the same shape: a capability-style handle that carries the boundary across every operation. The first thing to internalize is that you stop reasoning about *paths* and start reasoning about *the handle*.
+
+## 1. Build a root
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const fs = await root("/srv/jobs/incoming", {
+  hardlinks: "reject",  // refuse files that are hardlinks of out-of-tree inodes
+  symlinks: "reject",   // refuse to traverse a symlink during open
+  mkdir: true,          // create missing parent dirs on write
+});
+```
+
+`root()` resolves the directory through the real filesystem (so symlinked roots become canonical) and verifies it exists. The defaults you pass apply to every call below; per-call options override them.
+
+If the root directory itself does not exist yet, `root()` throws `FsSafeError` with code `not-found`. Either create the directory before calling `root()`, or call `await fs.ensureRoot()` after a successful `root()` to create empty subpaths.
+
+## 2. Read and write text
+
+```ts
+await fs.write("notes/today.txt", "hello\n");
+const text = await fs.readText("notes/today.txt");
+```
+
+Writes use a sibling temp file plus `rename`, so a partial write never appears at the destination. Reads open with `O_NOFOLLOW` where available and verify the opened fd matches the path identity before returning the buffer.
+
+`create()` is the don't-clobber variant of `write()` and throws `already-exists` when the target is already there:
+
+```ts
+await fs.create("notes/README.md", "seed\n"); // throws if it already exists
+```
+
+## 3. JSON, with parsing
+
+```ts
+type Config = { tokens: string[]; updatedAt: string };
+
+await fs.writeJson("state/config.json", { tokens: [], updatedAt: new Date().toISOString() }, {
+  space: 2,
+});
+
+const config = await fs.readJson<Config>("state/config.json");
+```
+
+`writeJson` stringifies and writes atomically. `readJson` reads through the same boundary and parses; validate the shape at your application boundary if it came from a less-trusted source.
+
+## 4. Move and remove
+
+```ts
+await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true });
+await fs.remove("notes/archive/today.txt");
+```
+
+`move()` defaults to no clobber. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+
+## 5. Inspect
+
+```ts
+const here = await fs.exists("state/config.json"); // boolean
+const stat = await fs.stat("state/config.json");   // { kind, size, mtimeMs, ... }
+const names = await fs.list("state");              // string[]
+const entries = await fs.list("state", { withFileTypes: true }); // DirEntry[]
+```
+
+`exists`, `stat`, and `list` are boundary-checked but **do not pin a later operation** to the same filesystem object. For race-resistant reads or writes, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` — they pin the path identity at the point of use.
+
+## 6. Catch escapes
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (err instanceof FsSafeError && err.code === "outside-workspace") {
+    // log, count, drop the request
+  } else {
+    throw err;
+  }
+}
+```
+
+Error codes are a closed union — branch on `err.code` instead of matching message text. The full list lives in the [Errors](errors.md) reference.
+
+## 7. Replace a config file atomically
+
+```ts
+import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceFileAtomic({
+  filePath: "/srv/jobs/incoming/state/config.json",
+  content: JSON.stringify(state, null, 2),
+  mode: 0o600,
+  syncTempFile: true,
+  syncParentDir: true,
+});
+```
+
+Use `replaceFileAtomic` directly when you have an absolute path you trust and want sibling-temp + rename without going through `root()`. See [Atomic writes](atomic.md).
+
+## 8. Unpack a ZIP
+
+```ts
+import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
+
+const kind = resolveArchiveKind("upload.zip");
+if (!kind) throw new Error("unsupported archive");
+
+await extractArchive({
+  archivePath: "/srv/jobs/incoming/uploads/upload.zip",
+  destDir: "/srv/jobs/incoming/extracted",
+  kind,
+  timeoutMs: 15_000,
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+  },
+});
+```
+
+Extraction stages into a private dir and merges through the same boundary used by direct writes, so a symlinked entry can't trick the merge into following an out-of-tree path. See [Archive extraction](archive.md).
+
+## 9. Get a private scratch directory
+
+```ts
+import { withTempWorkspace } from "@openclaw/fs-safe/temp";
+
+await withTempWorkspace({ rootDir: "/srv/jobs/tmp", prefix: "build-" }, async (workspace) => {
+  await fs.copyIn("input.bin", "/tmp/source.bin");
+  // ...do work in workspace.dir; auto-cleaned on exit
+});
+```
+
+The directory is mode `0700`, sits under a per-user secure temp root, and is removed when the callback returns or throws. See [Temp workspaces](temp.md).
+
+## Where to next
+
+- [Security model](security-model.md) — exactly what the boundary defends against, what it does not.
+- [Root API](root.md) — every method on the `Root` handle, including streaming and reader callbacks.
+- [Errors](errors.md) — the full code union and what each one means.