@openclaw/fs-safe/advancedComposition 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, 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 hereThe 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 pathsExport Page Notes pathScope, PathScope, PathScopeOptions, PathScopeResolveOptionspath-scope.md Absolute-path boundary helper with Result-shaped returns. ensureDirectoryWithinRoot– Create a directory while enforcing the root boundary. resolvePathWithinRoot, resolvePathsWithinRoot– Resolve one or many relative paths against a trusted root. resolveExistingPathsWithinRoot, resolveStrictExistingPathsWithinRoot– Same, but require the targets to exist. resolveWritablePathWithinRoot– Resolve a write target inside a root. resolveRootPath, resolveRootPathSync, ResolvedRootPath, ROOT_PATH_ALIAS_POLICIES, RootPathAliasPolicy– Resolve a root directory honoring alias policy. resolvePathViaExistingAncestorSync– Walk to an existing ancestor for paths whose tail does not yet exist.
# Absolute path helpersExport Page Notes assertAbsolutePathInput– Validate a caller-supplied absolute path string. ensureAbsoluteDirectory, EnsureAbsoluteDirectoryOptions, EnsureAbsoluteDirectoryResult– Create a trusted absolute directory path one segment at a time, rejecting symlink or non-directory segments. canonicalPathFromExistingAncestor, findExistingAncestor– Canonicalize without requiring the leaf to exist. resolveAbsolutePathForRead, resolveAbsolutePathForWrite, ResolvedAbsolutePath, ResolvedWritableAbsolutePath, AbsolutePathSymlinkPolicy– Validate an absolute path against a symlink policy before opening.
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 identityExport Page Notes openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, related types– Low-level no-follow open routed through the root-file path. appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, statRegularFile, statRegularFileSync, resolveRegularFileAppendFlags, AppendRegularFileOptions, RegularFileStatResultregular-file.md Type-checked regular-file I/O. sameFileIdentity, FileIdentityStat– Compare two stats for same-inode equality. pathExists, pathExistsSync– Boolean existence check that does not throw on ENOENT. assertNoSymlinkParents, assertNoSymlinkParentsSync, AssertNoSymlinkParentsOptions– Reject paths whose ancestor chain contains symlinks. assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, PathAliasPolicy– Hardlink/alias defense building blocks.
# Local roots and file URLsExport Page Notes resolveLocalPathFromRootsSync, readLocalFileFromRoots, related options/result typeslocal-roots.md Resolve a path against a list of allowed local roots. assertNoWindowsNetworkPath, basenameFromMediaSource, hasEncodedFileUrlSeparator, isWindowsDriveLetterPath, isWindowsNetworkPath, safeFileURLToPath, trySafeFileURLToPath– Defensive helpers around Windows paths and file:// URLs.
# Install paths and filenamesExport Page Notes safeDirName, safePathSegmentHashed, resolveSafeInstallDir, assertCanonicalPathWithinBaseinstall-path.md Build install-target directories from caller-supplied identifiers. sanitizeUntrustedFileNamefilename.md Coerce an untrusted string into a safe filename. resolveHomeRelativePath– Expand ~-prefixed paths.
# Temp targets and sibling-temp writesExport Page Notes tempFile, withTempFile, TempFile, buildRandomTempFilePath, sanitizeTempFileNametemp.md One-file temp primitive; prefer tempWorkspace from @openclaw/fs-safe/temp for the stable surface. writeSiblingTempFile, writeViaSiblingTempPath, WriteSiblingTempFileOptions, WriteSiblingTempFileResult– Sibling-temp write building block used by replaceFileAtomic.
# PermissionsExport Page Notes formatPosixModepermissions.md Format a POSIX mode bitmask. inspectWindowsAcl, summarizeWindowsAcl, formatWindowsAclSummary, parseIcaclsOutput, resolveWindowsUserPrincipal, createIcaclsResetCommand, formatIcaclsResetCommand, IcaclsResetCommandOptions, PermissionExec, WindowsAclEntry, WindowsAclSummarypermissions.md Windows ACL inspection and remediation.
# Concurrency, timing, trashExport Page Notes createAsyncLock– In-process async lock (separate from cross-process file locks). withTimeouttiming.md Wrap a promise with a timeout that raises FsSafeError("timeout"). movePathToTrash, MovePathToTrashOptions– Best-effort move to the platform trash.
# StabilityItems 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 — every helper here surfaces failures as FsSafeError.Security model — what the underlying boundary checks promise. Previous Timing Next Test hooks