@openclaw/fs-safe 0.1.1 → 0.2.0

package/dist/trash.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
+import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 const TRASH_DESTINATION_COLLISION_CODES = new Set(["EEXIST", "ENOTEMPTY", "ERR_FS_CP_EEXIST"]);
 const TRASH_DESTINATION_RETRY_LIMIT = 4;
 function getFsErrorCode(error) {
@@ -18,28 +21,56 @@ function isSameOrChildPath(candidate, parent) {
     return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
 }
 function resolveAllowedTrashRoots(allowedRoots) {
-    const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])].map((root) => {
+    const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])].flatMap((root) => {
+        const lexicalRoot = path.resolve(root);
         try {
-            return path.resolve(fs.realpathSync.native(root));
+            // Keep both spellings: broken symlink targets cannot be realpathed and
+            // may only compare equal to the caller's lexical allowed root.
+            return [path.resolve(fs.realpathSync.native(root)), lexicalRoot];
         }
         catch {
-            return path.resolve(root);
+            return [lexicalRoot];
         }
     });
     return [...new Set(roots)];
 }
-function assertAllowedTrashTarget(targetPath, allowedRoots) {
-    let resolvedTargetPath = path.resolve(targetPath);
+function resolveTrashTargetPath(targetPath) {
     try {
-        resolvedTargetPath = path.resolve(fs.realpathSync.native(targetPath));
+        return { path: path.resolve(fs.realpathSync.native(targetPath)), resolved: true };
     }
     catch {
-        // The subsequent move will surface missing or inaccessible targets.
+        // Broken symlinks are valid trash targets. Fall back to the lexical path,
+        // then rely on lstat identity so the move renames the symlink itself.
+        return { path: path.resolve(targetPath), resolved: false };
     }
+}
+function assertAllowedTrashTarget(targetPath, allowedRoots) {
+    const stat = fs.lstatSync(path.resolve(targetPath));
+    const resolvedTarget = resolveTrashTargetPath(targetPath);
+    const resolvedTargetPath = resolvedTarget.path;
     const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => resolvedTargetPath !== root && isSameOrChildPath(resolvedTargetPath, root));
     if (!isAllowed) {
         throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
     }
+    return {
+        path: path.resolve(targetPath),
+        realPath: resolvedTargetPath,
+        realPathResolved: resolvedTarget.resolved,
+        stat,
+    };
+}
+function assertTrashTargetGuard(guard) {
+    const stat = fs.lstatSync(guard.path);
+    if (!sameFileIdentity(stat, guard.stat)) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+    const current = resolveTrashTargetPath(guard.path);
+    if (guard.realPathResolved && (!current.resolved || current.path !== guard.realPath)) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+    if (!guard.realPathResolved && current.resolved) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
 }
 function resolveTrashDir() {
     const homeDir = os.homedir();
@@ -86,9 +117,11 @@ function reserveTrashDestination(trashDir, base, timestamp) {
     }
     return resolveContainedPath(container, base);
 }
-function movePathToDestination(targetPath, dest) {
+function movePathToDestination(target, dest) {
+    getFsSafeTestHooks()?.beforeTrashMove?.(target.path, dest);
+    assertTrashTargetGuard(target);
     try {
-        fs.renameSync(targetPath, dest);
+        guardedRenameSync({ from: target.path, to: dest });
         return true;
     }
     catch (error) {
@@ -100,8 +133,10 @@ function movePathToDestination(targetPath, dest) {
         }
     }
     try {
-        fs.cpSync(targetPath, dest, { recursive: true, force: false, errorOnExist: true });
-        fs.rmSync(targetPath, { recursive: true, force: false });
+        assertTrashTargetGuard(target);
+        fs.cpSync(target.path, dest, { recursive: true, force: false, errorOnExist: true });
+        assertTrashTargetGuard(target);
+        guardedRmSync({ target: target.path, recursive: true, force: false, verifyAfter: false });
         return true;
     }
     catch (error) {
@@ -114,12 +149,12 @@ function movePathToDestination(targetPath, dest) {
 export async function movePathToTrash(targetPath, options = {}) {
     // Avoid resolving external trash helpers through the service PATH during cleanup.
     const base = trashBaseName(targetPath);
-    assertAllowedTrashTarget(targetPath, options.allowedRoots);
+    const target = assertAllowedTrashTarget(targetPath, options.allowedRoots);
     const trashDir = resolveTrashDir();
     const timestamp = Date.now();
     for (let attempt = 0; attempt < TRASH_DESTINATION_RETRY_LIMIT; attempt += 1) {
         const dest = reserveTrashDestination(trashDir, base, timestamp);
-        if (movePathToDestination(targetPath, dest)) {
+        if (movePathToDestination(target, dest)) {
             return dest;
         }
     }

package/docs/advanced.md

@@ -0,0 +1,110 @@
+---
+title: Advanced
+description: "Lower-level composition helpers under @openclaw/fs-safe/advanced. Less stable than focused public subpaths."
+---
+
+# `@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`, `errors`). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.
+
+```ts
+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
+
+| Export | Page | Notes |
+|---|---|---|
+| `pathScope`, `PathScope`, `PathScopeOptions`, `PathScopeResolveOptions` | [path-scope.md](path-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 helpers
+
+| Export | 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 identity
+
+| Export | 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`, `RegularFileStatResult` | [regular-file.md](regular-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 URLs
+
+| Export | Page | Notes |
+|---|---|---|
+| `resolveLocalPathFromRootsSync`, `readLocalFileFromRoots`, related options/result types | [local-roots.md](local-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 filenames
+
+| Export | Page | Notes |
+|---|---|---|
+| `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
+| `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
+| `resolveHomeRelativePath` | – | Expand `~`-prefixed paths. |
+
+### Temp targets and sibling-temp writes
+
+| Export | Page | Notes |
+|---|---|---|
+| `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.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`. |
+
+### Permissions
+
+| Export | Page | Notes |
+|---|---|---|
+| `formatPosixMode` | [permissions.md](permissions.md) | Format a POSIX mode bitmask. |
+| `inspectWindowsAcl`, `summarizeWindowsAcl`, `formatWindowsAclSummary`, `parseIcaclsOutput`, `resolveWindowsUserPrincipal`, `createIcaclsResetCommand`, `formatIcaclsResetCommand`, `IcaclsResetCommandOptions`, `PermissionExec`, `WindowsAclEntry`, `WindowsAclSummary` | [permissions.md](permissions.md) | Windows ACL inspection and remediation. |
+
+### Concurrency, timing, trash
+
+| Export | Page | Notes |
+|---|---|---|
+| `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
+| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `FsSafeError("timeout")`. |
+| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform 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](https://github.com/openclaw/fs-safe) and we will discuss promoting it to a focused subpath.
+
+## Related pages
+
+- [Root API](root.md) — built on top of these helpers.
+- [Errors](errors.md) — every helper here surfaces failures as `FsSafeError`.
+- [Security model](security-model.md) — what the underlying boundary checks promise.

package/docs/archive.md

@@ -0,0 +1,199 @@
+# Archive extraction
+
+`@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. Extraction stages into a private directory and merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
+
+Archive extraction uses optional runtime dependencies: `jszip` for ZIP and `tar`
+for TAR. Installs that omit optional dependencies can still import this subpath,
+inspect archive kinds, and use pure path/limit helpers, but extraction or ZIP
+loading fails with a clear message until the matching optional dependency is
+installed.
+
+Some package managers and CI installs skip optional dependencies
+(`--no-optional`, `--omit=optional`, or equivalent). If an archive helper throws
+that an optional archive dependency is not installed, install `jszip` and/or
+`tar` explicitly in the consuming package.
+
+```ts
+import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
+```
+
+## `extractArchive`
+
+```ts
+await extractArchive({
+  archivePath: "/srv/uploads/plugin.zip",
+  destDir: "/srv/workspace/plugins/plugin",
+  kind: "zip",                        // optional; resolveArchiveKind() can infer
+  timeoutMs: 15_000,                  // hard ceiling for the whole extraction
+  stripComponents: 0,                 // tar-style strip-leading-dirs
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+  },
+});
+```
+
+### Parameters
+
+```ts
+type ExtractArchiveParams = {
+  archivePath: string;          // absolute path to the archive
+  destDir: string;              // absolute destination directory; must already exist
+  timeoutMs: number;            // wall-clock cap; throws on overrun
+  kind?: ArchiveKind;           // "zip" | "tar"; inferred from filename when omitted
+  stripComponents?: number;     // strip N leading dirs from entry paths
+  tarGzip?: boolean;            // when archive is .tar.gz/.tgz
+  limits?: ArchiveExtractLimits;
+  logger?: ArchiveLogger;       // { info?, warn? }
+};
+```
+
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names).
+
+### Limits
+
+```ts
+type ArchiveExtractLimits = {
+  maxArchiveBytes?: number;     // refuse if archivePath stat'd size exceeds this
+  maxEntries?: number;          // refuse before extracting if entry count > this
+  maxExtractedBytes?: number;   // refuse mid-stream if total extracted bytes > this
+  maxEntryBytes?: number;       // refuse a single entry larger than this
+};
+```
+
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`). They are conservative — pass explicit values when you know your domain's actual ceiling.
+
+A limit violation throws `ArchiveLimitError`. The error's code is one of:
+
+```ts
+ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_BYTES_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.ENTRY_BYTES_EXCEEDS_LIMIT
+```
+
+Catch and branch on the code to surface a meaningful response to the caller.
+
+## What it defends against
+
+- **Path traversal:** entries with `..`, absolute paths, or Windows drive prefixes are rejected (`ArchiveSecurityError`).
+- **Symlink/hardlink entries:** rejected by default. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
+- **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. A symlink swap in the destination tree mid-merge is caught.
+- **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
+- **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
+
+## `resolveArchiveKind`
+
+```ts
+import { resolveArchiveKind, type ArchiveKind } from "@openclaw/fs-safe/archive";
+
+const kind = resolveArchiveKind("upload.zip"); // "zip"
+const tar = resolveArchiveKind("upload.tar.gz"); // "tar"
+const unknown = resolveArchiveKind("upload.bin"); // undefined
+```
+
+Recognizes:
+
+- `*.zip` → `"zip"`
+- `*.tar`, `*.tar.gz`, `*.tgz`, `*.tar.bz2`, `*.tbz`, `*.tbz2` → `"tar"`
+
+Returns `undefined` for unknown extensions; check the result before calling `extractArchive` if the filename is caller-controlled.
+
+## Lower-level building blocks
+
+The archive subpath also exports the helpers `extractArchive` is built on. Most callers will not need them, but they are stable and documented:
+
+| Function | Purpose |
+|---|---|
+| `withStagedArchiveDestination(opts)` | Creates a private staging dir outside the destination, calls your `run(stagingDir)`, then cleans it up. |
+| `mergeExtractedTreeIntoDestination(opts)` | The merge step alone — staged tree → destination through boundary checks. |
+| `prepareArchiveDestinationDir(destDir)` | Canonicalizes and asserts the destination directory. |
+| `prepareArchiveOutputPath(opts)` | Resolves a single entry's output path against the staging dir. |
+| `loadZipArchiveWithPreflight(opts)` | Loads a JSZip with size/entry-count preflight before unzipping. |
+| `readZipCentralDirectoryEntryCount(path)` | Returns the entry count from a ZIP's central directory without reading any payloads. |
+| `createTarEntryPreflightChecker(opts)` | Returns a per-entry checker for use as a `tar.x` `onReadEntry` hook. |
+
+These let you build custom extractors that share the same safety machinery — for example, a streaming uploader that wants to refuse archives with too many entries before reading any payloads.
+
+## Path helpers
+
+`archive-entry` exports a handful of low-level helpers for entry-path normalization:
+
+```ts
+import {
+  isWindowsDrivePath,
+  normalizeArchiveEntryPath,
+  resolveArchiveOutputPath,
+  stripArchivePath,
+  validateArchiveEntryPath,
+} from "@openclaw/fs-safe/archive";
+```
+
+- `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, drive-prefixed, or otherwise unsafe entry paths.
+- `normalizeArchiveEntryPath(raw)` — POSIX-normalizes the entry path (forward slashes, no `.` segments).
+- `stripArchivePath(entryPath, n)` — strip the leading N path components, returning `null` if not enough remain.
+- `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
+- `isWindowsDrivePath(value)` — detects `C:\…` style entries that should be rejected.
+
+## Common patterns
+
+### Extract an upload, surface budget violations
+
+```ts
+import { extractArchive, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE } from "@openclaw/fs-safe/archive";
+
+try {
+  await extractArchive({
+    archivePath: upload.path,
+    destDir: targetDir,
+    kind: "zip",
+    timeoutMs: 30_000,
+    limits: {
+      maxArchiveBytes: 100 * 1024 * 1024,
+      maxEntries: 10_000,
+      maxExtractedBytes: 200 * 1024 * 1024,
+      maxEntryBytes: 50 * 1024 * 1024,
+    },
+  });
+} catch (err) {
+  if (err instanceof ArchiveLimitError) {
+    return reply(413, { code: err.code, message: err.message });
+  }
+  throw err;
+}
+```
+
+### Decide kind from MIME, not filename
+
+```ts
+const kind: ArchiveKind = mime === "application/zip" ? "zip" : "tar";
+await extractArchive({ archivePath, destDir, kind, timeoutMs: 10_000 });
+```
+
+### Stage to private dir, then commit as a directory
+
+```ts
+import { withTempWorkspace } from "@openclaw/fs-safe/temp";
+import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
+
+await withTempWorkspace({ rootDir: "/srv/site/tmp", prefix: "extract-" }, async (ws) => {
+  await extractArchive({
+    archivePath: upload.path,
+    destDir: ws.dir,
+    timeoutMs: 30_000,
+  });
+  await replaceDirectoryAtomic({
+    stagedDir: ws.dir,
+    targetDir: "/srv/site/plugin",
+  });
+});
+```
+
+## See also
+
+- [Atomic writes](atomic.md) — `replaceDirectoryAtomic` for staged directory replacement.
+- [Temp workspaces](temp.md) — extract into a private workspace and commit as one step.
+- [Errors](errors.md) — `FsSafeError` codes the underlying writes can raise.
+- [`extractArchive` source](https://github.com/openclaw/fs-safe/blob/main/src/archive.ts).

package/docs/atomic.md

@@ -0,0 +1,191 @@
+# Atomic writes
+
+`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have an absolute path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
+
+```ts
+import {
+  replaceFileAtomic,
+  replaceFileAtomicSync,
+  writeTextAtomic,
+  replaceDirectoryAtomic,
+  movePathWithCopyFallback,
+} from "@openclaw/fs-safe/atomic";
+```
+
+## `replaceFileAtomic` / `replaceFileAtomicSync`
+
+Write `content` to a sibling temp file in the destination directory, optionally `fsync` the temp file, optionally `fsync` the parent directory after rename, then atomically rename over the destination.
+
+Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
+
+```ts
+import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceFileAtomic({
+  filePath: "/srv/workspace/state.json",
+  content: JSON.stringify(state, null, 2),
+  mode: 0o600,
+  syncTempFile: true,
+  syncParentDir: true,
+});
+```
+
+### Options
+
+```ts
+type ReplaceFileAtomicOptions = {
+  filePath: string;                 // destination
+  content: string | Uint8Array;
+  dirMode?: number;                 // mode for parent dirs created by the helper
+  mode?: number;                    // explicit mode for the new file (e.g. 0o600)
+  preserveExistingMode?: boolean;   // copy mode from existing destination, when present
+  tempPrefix?: string;
+  renameMaxRetries?: number;
+  renameRetryBaseDelayMs?: number;
+  copyFallbackOnPermissionError?: boolean;
+  syncTempFile?: boolean;           // fsync(temp) before rename
+  syncParentDir?: boolean;          // fsync(parent) after rename (POSIX only)
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
+};
+```
+
+### `beforeRename`
+
+Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer:
+
+```ts
+await replaceFileAtomic({
+  filePath: "/srv/workspace/config.toml",
+  content: rendered,
+  beforeRename: async ({ filePath }) => {
+    await fs.copyFile(filePath, `${filePath}.bak`); // snapshot existing
+  },
+});
+```
+
+If `beforeRename` throws, the rename is skipped and the temp file is removed — the destination is unchanged.
+
+### `EPERM` and copy fallback
+
+On systems where `rename` fails with `EPERM`/`EEXIST`, pass
+`copyFallbackOnPermissionError: true` to fall back to a non-atomic copy
+replacement. The fallback removes the old destination, opens the replacement
+with exclusive/no-follow flags where the platform supports them, and refuses
+known symlink destinations so it does not write through a replaced destination
+link.
+
+### Sync variant
+
+`replaceFileAtomicSync` accepts the same options shape, with the obvious removal of the async-only hooks. Use it inside synchronous boot paths or test setup code.
+
+## `replaceDirectoryAtomic`
+
+Atomically swap one directory's contents with another, using a temporary backup during the swap.
+
+```ts
+import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceDirectoryAtomic({
+  stagedDir: "/srv/workspace/staging/snapshot-2026-05-05",
+  targetDir: "/srv/workspace/snapshot",
+});
+```
+
+The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
+
+Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
+
+## `writeTextAtomic`
+
+Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
+temp file, temp fsync, rename, parent fsync, and final chmod best-effort.
+It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
+you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
+or custom copy-fallback policy.
+
+```ts
+import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
+
+await writeTextAtomic("/srv/workspace/rendered.md", rendered, {
+  mode: 0o600,
+  dirMode: 0o700,
+  trailingNewline: true,
+});
+```
+
+Options:
+
+```ts
+type WriteTextAtomicOptions = {
+  mode?: number;             // file mode (default 0o600)
+  dirMode?: number;          // mode for parent dirs created on demand
+  trailingNewline?: boolean; // append "\n" if missing
+  durable?: boolean;         // default true; false skips temp/parent fsync
+};
+```
+
+`durable: false` keeps the sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability.
+
+## `movePathWithCopyFallback`
+
+Rename a path. If the rename fails with `EXDEV` (cross-device), fall back to
+copying into a staged sibling path, renaming that staged path into place, and
+then removing only the source entries that were copied. The fallback avoids
+buffering regular files into memory and does not tighten the destination parent
+directory mode.
+
+```ts
+import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
+
+await movePathWithCopyFallback({
+  from: "/srv/cache/blob.bin",
+  sourceHardlinks: "reject",
+  to: "/srv/persistent/blob.bin",
+});
+```
+
+Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+If another writer changes source entries during the fallback, the staged copy
+throws `ESTALE` before commit when possible. If the destination has already
+been committed, cleanup still preserves the changed source entries and throws
+`ESTALE`.
+
+## Difference from `root()`
+
+| `Root` methods | `atomic` helpers |
+|---|---|
+| Take relative paths, bound to a `rootDir`. | Take absolute paths, no boundary. |
+| Throw `FsSafeError` with `code`. | Throw `FsSafeError` *or* the underlying `NodeJS.ErrnoException`, depending on failure point. |
+| Atomicity, mode, hooks, fsync are sane defaults. | Caller controls all of the above. |
+| `mkdir`, identity check, hardlink reject built in. | No identity check, no hardlink reject — pair with [path helpers](path.md) if you need them. |
+
+Use `Root` when the path is caller-controlled. Use `atomic` when the path is fully under your control and you want explicit knobs.
+
+## Test injection
+
+Both `replaceFileAtomic` and `replaceFileAtomicSync` accept a `fileSystem` option that overrides the small set of `fs` calls they make. Pass a stub in unit tests to assert order, simulate `EPERM`, or capture the temp filename:
+
+```ts
+const ops: string[] = [];
+await replaceFileAtomic({
+  filePath: "/tmp/x",
+  content: "hi",
+  fileSystem: {
+    promises: {
+      ...realFs,
+      writeFile: async (...args) => { ops.push("write"); return realFs.writeFile(...args); },
+      rename: async (...args) => { ops.push("rename"); return realFs.rename(...args); },
+    },
+  },
+});
+```
+
+## See also
+
+- [`root()`](root.md) — when you want method-style writes with the boundary baked in.
+- [JSON files](json.md) — JSON/text helpers built on sibling-temp replacement.
+- [Temp workspaces](temp.md) — for staging-then-swap directory builds.
+- [Errors](errors.md) — code union for failures.