@openclaw/fs-safe/advanced

Composition primitives that OpenClaw uses to build higher-level APIs. They are public — semver applies — but treated as a less stable surface than the focused subpaths (root, json, store, temp, archive, durability, errors). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.

import {
  pathScope,
  withTimeout,
  pathExists,
  sanitizeUntrustedFileName,
  // …
} from "@openclaw/fs-safe/advanced";

#What lives here

The exports group into a handful of themes. Each documented helper has its own page; everything else is reference-only and tracked here.

#Path scopes and root paths

ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? }) returns { ok: true, path } or { ok: false, error: string, diagnostic?: FsSafeError }. It does not throw filesystem failures: operational failures carry a helper-failed diagnostic with the original cause and a bounded, escaped message naming the native code/syscall when available. Policy failures omit diagnostic. Missing parents already created before a failure remain in place. The diagnostic contract is specific to directory preparation, not the other root-path result helpers.

#Absolute path helpers

ensureAbsoluteDirectory() is for paths you already intend to trust as absolute locations, such as a configured output root. It does not enforce a root boundary; use pathScope().ensureDir() or ensureDirectoryWithinRoot() when the caller supplies a path that must stay under a root.

The helper returns { ok: false, code, error } for path-policy failures such as relative paths, symlinks, non-directories, or directory swaps during creation. Operational filesystem failures such as permissions or I/O errors are rethrown.

#Files and identity

pathExists() and pathExistsSync() intentionally retain ordinary stat semantics and are not caller-path admission boundaries. Validate an untrusted path with the boundary appropriate to the operation before using these existence probes.

openRootFile() and openRootFileSync() compare exact bigint identities before open, on the retained descriptor, and on the current resolved path. Their stat receipts remain numeric. Custom ioFs adapters must honor { bigint: true } for lstatSync and fstatSync; numeric identity responses fail validation. Unknown Windows identities receive one re-inspection without reopening, then fail validation if still unknown.

On Windows, these existing-object readers retain their historical support for a leading drive-relative spelling such as C:existing.txt: it is anchored to that drive before confinement and namespace admission. Additional colons remain in the anchored spelling, so alternate-stream and directory-index aliases are still rejected before opening.

These adapters also capture the canonical root directory's exact bigint identity before component traversal. Immediately before transferring descriptor ownership, they check that root, freshly canonicalize the consumed pathname, admit the fresh spelling under the captured root, compare a no-follow canonical-leaf observation with the retained descriptor, and check the root again. Boundary or identity drift is a validation failure and the descriptor is closed. A custom ioFs supplies these observations; the built-in adapter uses fs-safe's native realpath wrapper. On Windows, the built-in adapter binds native root spelling before traversal, including supplied rootRealPath, and returns that spelling in its root receipt. This is an operation-local detection fence, not atomic confinement against a peer that can keep racing pathname bindings.

The explicit symlinks policy takes precedence over the existing rejectSymlinks boolean. Without symlinks, rejectSymlinks: false retains its existing behavior of following contained links, and omission still rejects all symlink components.

The bounded descriptor helpers cap their initial speculative allocation at 16 MiB plus the overflow-probe byte, even when a file reports a much larger size. Regular files up to that size can return from one read without copying chunks; larger files and short reads continue incrementally under the same byte limit. Continuation buffers grow only after filling with actual bytes, up to the byte budget plus its probe; file-size hints cannot force that growth. Unknown-size inputs start with at most 64 KiB. This avoids per-chunk copies and a final concatenation when a file exceeds the initial allocation. Regular files that report a size of zero, such as virtual files, continue through positive short reads until actual EOF or byte-limit overflow.

The bounded descriptor helpers start at the descriptor's current offset and leave ownership with the caller. They are intended for the second half of a safe read: first open and validate the path using the boundary appropriate to your application, then read the already-pinned descriptor without trusting a possibly stale size check.

import fs from "node:fs";
import { readFileDescriptorBoundedSync } from "@openclaw/fs-safe/advanced";

const fd = fs.openSync(filePath, "r");
try {
  const bytes = readFileDescriptorBoundedSync(fd, 256 * 1024);
  consume(bytes);
} finally {
  fs.closeSync(fd);
}

For the symlink-parent guards, allowMissing defaults to true and permits the walk to stop only at an actually absent suffix. When an existing non-directory component is followed by another segment, both helpers throw FsSafeError("not-file") before the platform can expose that state as POSIX ENOTDIR or Windows ENOENT.

#Local roots and file URLs

#Install paths and filenames

#Temp targets and sibling-temp writes

#Permissions

#Concurrency, timing, trash

#Stability

Items in this surface can change shape between minor versions if a higher-level primitive needs them to. Pin to a minor version if you depend on a specific helper, or open an issue at the GitHub repo and we will discuss promoting it to a focused subpath.

#Related pages

• Root API — built on top of these helpers.
• Errors — shared filesystem error codes; generic timing helpers retain their documented error types.
• Security model — what the underlying boundary checks promise.