@openclaw/fs-safe 0.1.1 → 0.1.2

package/docs/path-scope.md

@@ -0,0 +1,130 @@
+# pathScope()
+
+`pathScope()` is an advanced helper with the same boundary semantics as `root()`, but it operates on **absolute paths** the caller already trusts and returns plain `{ ok, path }` results instead of throwing. Use it when you want the boundary check up front before handing an absolute path to another library.
+
+```ts
+import { pathScope } from "@openclaw/fs-safe/advanced";
+
+const uploads = pathScope("/srv/uploads", { label: "uploads directory" });
+
+const photo = uploads.resolve("user/photo.jpg");
+if (!photo.ok) throw new Error(photo.error);
+
+await sharp(photo.path).resize(800).toFile(/* … */);
+```
+
+## When to reach for it
+
+`root()` is the right answer when you want method-style I/O (`fs.write`, `fs.readText`). `pathScope()` is the right answer when:
+
+- You're handing absolute paths to **other libraries** that take absolute path strings (Sharp, FFmpeg, `tar`, native modules) and just want the boundary check up front.
+- You want to validate user-supplied paths in bulk and return a typed `Result` rather than catching exceptions.
+- You want the scope's `label` to appear in the error message: `"Invalid path: must stay within uploads directory"`.
+
+## Signature
+
+```ts
+function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
+
+type PathScopeOptions = {
+  label: string;          // appears in error messages
+};
+
+type PathScopeResolveOptions = {
+  defaultName?: string;   // used when the requested path is empty
+};
+
+type PathResult = { ok: true; path: string } | { ok: false; error: string };
+type PathsResult = { ok: true; paths: string[] } | { ok: false; error: string };
+
+type PathScope = {
+  rootDir: string;
+  label: string;
+  resolve(requestedPath: string, options?: PathScopeResolveOptions): PathResult;
+  resolveAll(requestedPaths: string[]): PathsResult;
+  existing(requestedPaths: string[]): Promise<PathsResult>;
+  files(requestedPaths: string[]): Promise<PathsResult>;
+  writable(requestedPath: string, options?: PathScopeResolveOptions): Promise<PathResult>;
+  ensureDir(requestedPath: string, options?: PathScopeResolveOptions & { mode?: number }): Promise<PathResult>;
+};
+```
+
+## Methods
+
+### `resolve(rel, options?)`
+
+Synchronous, lexical only — no filesystem touch. Resolves the relative path against `rootDir` and verifies the result stays inside the scope. Use when you only need the path string:
+
+```ts
+const r = uploads.resolve("user/photo.jpg");
+if (!r.ok) return reply(400, r.error);
+console.log(r.path); // /srv/uploads/user/photo.jpg
+```
+
+If the requested path is empty, `defaultName` (when set) is used.
+
+### `resolveAll(rels)`
+
+Synchronous bulk resolve. Returns `{ ok: true, paths }` if every input is in scope, or `{ ok: false, error }` on the first failure.
+
+### `existing(rels)`
+
+Async. Like `resolveAll`, but additionally allows trusted absolute paths whose `realpath` is inside the scope. Useful when callers pass either a relative path or an absolute path you've already validated.
+
+### `files(rels)`
+
+Async. Strict variant: every input must already exist as a regular file inside the scope, with `nlink === 1`. Symlinked entries are rejected.
+
+### `writable(rel, options?)`
+
+Async. Resolves a writable target: ensures the parent directory exists inside the scope, refuses targets whose existing inode is a symlink or hardlinked, and returns the absolute path to use for the write.
+
+```ts
+const t = await uploads.writable("reports/2026/05/report.pdf");
+if (!t.ok) return reply(400, t.error);
+await fs.writeFile(t.path, body);
+```
+
+### `ensureDir(rel, options?)`
+
+Async. `mkdir -p` inside the scope. Walks each segment, refuses any symlink in the path, creates missing directories. Optional `mode` sets the directory mode.
+
+```ts
+const dir = await uploads.ensureDir("inbox", { mode: 0o755 });
+if (!dir.ok) return reply(500, dir.error);
+```
+
+## Result type vs throwing
+
+`pathScope` returns `{ ok: true, path }` / `{ ok: false, error }` instead of throwing. This makes it pleasant to use at validation boundaries:
+
+```ts
+function handle(req: Req, res: Res) {
+  const r = uploads.resolve(req.body.path);
+  if (!r.ok) return res.status(400).json({ error: r.error });
+  return doWork(r.path);
+}
+```
+
+For exception-flavored APIs, use `root()` instead — it throws `FsSafeError` with a typed `code`.
+
+## Combine with `root()`
+
+A common pattern at the edge of an HTTP handler: validate the input with `pathScope`, do the I/O with `root()`:
+
+```ts
+const uploads = pathScope("/srv/uploads", { label: "uploads" });
+const fs = await root("/srv/uploads", { hardlinks: "reject" });
+
+const r = uploads.resolve(req.body.path);
+if (!r.ok) return reply(400, r.error);
+const rel = path.relative(fs.rootReal, r.path);
+
+const text = await fs.readText(rel);
+```
+
+## See also
+
+- [`root()`](root.md) — method-style boundary that throws on failure.
+- [Path helpers](path.md) — `isPathInside`, `safeRealpathSync`, `isWithinDir` for ad-hoc checks.
+- [Errors](errors.md) — error semantics (note: `pathScope` returns errors, doesn't throw).

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.