@openclaw/fs-safe 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.6 - 2026-05-17
+
+### Security and Correctness
+
+- Harden DeepSec-reported temp path handling, private secret writes, pinned helper commits, fallback mkdir writes, and dot-prefixed root relative paths against symlink, race, and relative-path edge cases.
+
 ## 0.2.5 - 2026-05-16
 
 ### Security and Correctness

package/README.md

@@ -66,18 +66,15 @@ before first use when you need a strict environment policy:
 import { configureFsSafePython } from "@openclaw/fs-safe";
 
 configureFsSafePython({ mode: "auto" });    // default: use helper, fall back if unavailable
-configureFsSafePython({ mode: "off" });     // never spawn Python; use Node fallbacks
+configureFsSafePython({ mode: "off" });     // never spawn Python; writes that need it fail closed
 configureFsSafePython({ mode: "require" }); // fail closed if helper cannot start
 ```
 
 Equivalent env vars: `FS_SAFE_PYTHON_MODE=auto|off|require` and
-`FS_SAFE_PYTHON=/path/to/python3`. Without Python, `fs-safe` keeps lexical and
-canonical root checks, no-follow opens, atomic temp+rename writes, and
-post-write identity verification. What you lose is the strongest POSIX
-fd-relative protection against a same-process-user racer swapping parent
-directories between validation and mutation. Windows already uses the Node
-fallback path. See the [Python helper policy](docs/python-helper.md) for
-deployment guidance.
+`FS_SAFE_PYTHON=/path/to/python3`. On POSIX, disabling or losing the helper now
+fails closed for root write paths that require fd-relative parent commits.
+Windows already uses the Node fallback path. See the
+[Python helper policy](docs/python-helper.md) for deployment guidance.
 
 ## Quick start
 
@@ -435,7 +432,7 @@ Current `FsSafeErrorCode` values are `already-exists`, `hardlink`, `helper-faile
 - root-bounded APIs resolve paths against a configured root and reject canonical escapes
 - reads open with `O_NOFOLLOW` where available, then verify fd identity matches the path identity before returning the buffer or handle
 - writes use pinned parent-directory helpers and atomic replacement on POSIX, with verified post-write identity
-- `remove`, `mkdir`, `move`, `stat`, `list`, and parent-fd writes use one persistent fd-relative Python helper on POSIX, with Node fallbacks when the helper is disabled or unavailable
+- `remove`, `mkdir`, `move`, `stat`, `list`, and parent-fd writes use one persistent fd-relative Python helper on POSIX; security-sensitive writes fail closed when that helper is disabled or unavailable
 - archive extraction stages into a private directory and merges through the same boundary checks used by direct writes
 
 ## Limitations

package/dist/file-store-boundary.js

@@ -5,7 +5,7 @@ import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { assertSyncDirectoryGuard as assertDirectoryGuardSync, createSyncDirectoryGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { isPathInside } from "./path.js";
+import { isPathInside, isPathRelativeEscape } from "./path.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 function parentRelativePath(relativePath) {
@@ -131,7 +131,7 @@ export function ensureParentSync(params) {
     const rootDir = path.resolve(params.rootDir);
     const dir = path.dirname(path.resolve(params.filePath));
     const relative = path.relative(rootDir, dir);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         throw new FsSafeError("outside-workspace", "file path escapes store root");
     }
     syncFs.mkdirSync(rootDir, { recursive: true, mode: params.mode });

package/dist/guarded-mkdir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAaA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChB"}
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAWA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}

package/dist/guarded-mkdir.js

@@ -2,17 +2,17 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { isPathRelativeEscape } from "./path.js";
 function isSameOrChildPath(candidate, parent) {
-    return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
-}
-function isPathEscape(relativePath) {
-    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+    const parentPrefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
+    return candidate === parent || candidate.startsWith(parentPrefix);
 }
 export async function mkdirPathComponentsWithGuards(params) {
     const root = path.resolve(params.rootReal);
+    const rootCanonical = path.resolve(await fs.realpath(root));
     const target = path.resolve(params.targetPath);
     const relative = path.relative(root, target);
-    if (isPathEscape(relative)) {
+    if (isPathRelativeEscape(relative)) {
         throw new FsSafeError("outside-workspace", "directory is outside workspace root");
     }
     let current = root;
@@ -35,7 +35,7 @@ export async function mkdirPathComponentsWithGuards(params) {
         }
         // Node's recursive mkdir follows symlinks in missing components. Build one
         // segment at a time and realpath-check each segment before descending.
-        if (!isSameOrChildPath(path.resolve(await fs.realpath(next)), root)) {
+        if (!isSameOrChildPath(path.resolve(await fs.realpath(next)), rootCanonical)) {
             throw new FsSafeError("outside-workspace", "directory escaped workspace root");
         }
         await createAsyncDirectoryGuard(next);

package/dist/path.d.ts

@@ -6,6 +6,7 @@ export declare function assertNoNulPathInput(filePath: string, message?: string)
 export declare function isNotFoundPathError(value: unknown): boolean;
 export declare function isSymlinkOpenError(value: unknown): boolean;
 export declare function isPathInside(root: string, target: string): boolean;
+export declare function isPathRelativeEscape(relativePath: string): boolean;
 export declare function resolveSafeBaseDir(rootDir: string): string;
 export declare function isWithinDir(rootDir: string, targetPath: string): boolean;
 export declare function safeRealpathSync(targetPath: string, cache?: Map<string, string>): string | null;

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAUzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA4BlE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAUzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA4BlE;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}

package/dist/path.js

@@ -55,6 +55,9 @@ export function isPathInside(root, target) {
     const firstSegment = relative.split(path.posix.sep)[0];
     return relative === "" || (firstSegment !== ".." && !path.isAbsolute(relative));
 }
+export function isPathRelativeEscape(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
 export function resolveSafeBaseDir(rootDir) {
     const resolved = path.resolve(rootDir);
     return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;

package/dist/pinned-python.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinned-python.d.ts","sourceRoot":"","sources":["../src/pinned-python.ts"],"names":[],"mappings":"AAwZA,KAAK,qBAAqB,GACtB,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAiBZ,wBAAgB,gCAAgC,IAAI,IAAI,CAQvD;AA2ND,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE;IACxD,SAAS,EAAE,qBAAqB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4Bb;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAK3D;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAarF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIjE"}
+{"version":3,"file":"pinned-python.d.ts","sourceRoot":"","sources":["../src/pinned-python.ts"],"names":[],"mappings":"AA2ZA,KAAK,qBAAqB,GACtB,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAiBZ,wBAAgB,gCAAgC,IAAI,IAAI,CAQvD;AAiOD,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE;IACxD,SAAS,EAAE,qBAAqB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4Bb;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAK3D;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAarF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEjE"}

package/dist/pinned-python.js

@@ -3,26 +3,20 @@ import fsSync from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { getFsSafePythonConfig } from "./pinned-python-config.js";
 const PINNED_PYTHON_WORKER_SOURCE = String.raw `
-import base64
-import errno
-import json
-import os
-import secrets
-import stat
-import sys
-
+import base64, errno, json, os, secrets, stat, sys
 DIR_FLAGS = os.O_RDONLY
 if hasattr(os, "O_DIRECTORY"):
     DIR_FLAGS |= os.O_DIRECTORY
 if hasattr(os, "O_NOFOLLOW"):
     DIR_FLAGS |= os.O_NOFOLLOW
 READ_FLAGS = os.O_RDONLY
+if hasattr(os, "O_NONBLOCK"):
+    READ_FLAGS |= os.O_NONBLOCK
 if hasattr(os, "O_NOFOLLOW"):
     READ_FLAGS |= os.O_NOFOLLOW
 WRITE_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL
 if hasattr(os, "O_NOFOLLOW"):
     WRITE_FLAGS |= os.O_NOFOLLOW
-
 def split_relative(value):
     if value in ("", "."):
         return []
@@ -35,10 +29,8 @@ def split_relative(value):
         if part == "..":
             raise OSError(errno.EPERM, "path traversal is not allowed")
     return parts
-
 def open_dir(path_value, dir_fd=None):
     return os.open(path_value, DIR_FLAGS, dir_fd=dir_fd)
-
 def walk_dir(root_fd, segments, mkdir_enabled=False):
     current_fd = os.dup(root_fd)
     try:
@@ -56,14 +48,12 @@ def walk_dir(root_fd, segments, mkdir_enabled=False):
     except Exception:
         os.close(current_fd)
         raise
-
 def parent_and_basename(root_fd, relative):
     segments = split_relative(relative)
     if not segments:
         raise OSError(errno.EPERM, "operation requires a non-root path")
     parent_fd = walk_dir(root_fd, segments[:-1])
     return parent_fd, segments[-1]
-
 def encode_stat(st):
     mode = st.st_mode
     return {
@@ -79,14 +69,12 @@ def encode_stat(st):
         "size": st.st_size,
         "uid": st.st_uid,
     }
-
 def reject_unsafe_endpoint(st):
     mode = st.st_mode
     if stat.S_ISLNK(mode):
         raise OSError(errno.ELOOP, "symlink endpoint is not allowed")
     if stat.S_ISREG(mode) and st.st_nlink > 1:
         raise OSError(errno.EPERM, "hardlinked file endpoint is not allowed")
-
 def copy_bytes(source_fd, dest_fd):
     while True:
         chunk = os.read(source_fd, 65536)
@@ -98,7 +86,6 @@ def copy_bytes(source_fd, dest_fd):
             if written <= 0:
                 raise OSError(errno.EIO, "short write")
             view = view[written:]
-
 def write_all(fd, data):
     view = memoryview(data)
     while view:
@@ -106,11 +93,9 @@ def write_all(fd, data):
         if written <= 0:
             raise OSError(errno.EIO, "short write")
         view = view[written:]
-
 def link_unsupported(exc):
     unsupported = (errno.EPERM, errno.EOPNOTSUPP, getattr(errno, "ENOTSUP", errno.EOPNOTSUPP))
     return getattr(exc, "errno", None) in unsupported
-
 def link_no_replace(name, new_name, source_fd, target_fd):
     linked = False
     try:
@@ -125,11 +110,9 @@ def link_no_replace(name, new_name, source_fd, target_fd):
     os.fsync(source_fd)
     if source_fd != target_fd:
         os.fsync(target_fd)
-
 def copy_file_no_replace(source_parent_fd, source_name, target_parent_fd, basename, mode, expected=None, unlink_source=False):
     source_fd = os.open(source_name, READ_FLAGS, dir_fd=source_parent_fd)
-    dest_fd = None
-    success = False
+    dest_fd = None; success = False; dest_stat = None
     try:
         if expected is not None:
             source_stat = os.fstat(source_fd)
@@ -138,6 +121,7 @@ def copy_file_no_replace(source_parent_fd, source_name, target_parent_fd, basena
         dest_fd = os.open(basename, WRITE_FLAGS, mode, dir_fd=target_parent_fd)
         copy_bytes(source_fd, dest_fd)
         os.fsync(dest_fd)
+        dest_stat = os.fstat(dest_fd)
         success = True
     finally:
         os.close(source_fd)
@@ -153,19 +137,40 @@ def copy_file_no_replace(source_parent_fd, source_name, target_parent_fd, basena
             try: os.unlink(basename, dir_fd=target_parent_fd)
             except FileNotFoundError: pass
             raise
-
-def commit_temp_file(parent_fd, temp_name, basename, overwrite, mode):
+    return dest_stat
+def same_identity(left, right):
+    return left.st_dev == right.st_dev and left.st_ino == right.st_ino
+def verify_temp_name(parent_fd, temp_name, expected_stat):
+    current_stat = os.lstat(temp_name, dir_fd=parent_fd)
+    if stat.S_ISLNK(current_stat.st_mode) or not same_identity(current_stat, expected_stat):
+        raise RuntimeError("fs-safe-temp-mismatch")
+def verify_committed_temp(parent_fd, basename, expected_stat):
+    final_stat = os.lstat(basename, dir_fd=parent_fd)
+    if not stat.S_ISLNK(final_stat.st_mode) and same_identity(final_stat, expected_stat):
+        return final_stat
+    try: os.unlink(basename, dir_fd=parent_fd)
+    except FileNotFoundError: pass
+    raise RuntimeError("fs-safe-temp-mismatch")
+def commit_temp_file(parent_fd, temp_name, basename, overwrite, mode, expected_stat):
+    verify_temp_name(parent_fd, temp_name, expected_stat)
     if overwrite:
         os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
+        return verify_committed_temp(parent_fd, basename, expected_stat)
     else:
         try:
             os.link(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False)
+            final_stat = verify_committed_temp(parent_fd, basename, expected_stat)
             os.unlink(temp_name, dir_fd=parent_fd)
+            return final_stat
         except OSError as exc:
             if not link_unsupported(exc):
                 raise
-            copy_file_no_replace(parent_fd, temp_name, parent_fd, basename, mode, unlink_source=True)
-
+            return copy_file_no_replace(parent_fd, temp_name, parent_fd, basename, mode, expected_stat, True)
+def assert_expected_root(root_fd, payload):
+    if "rootDev" in payload or "rootIno" in payload:
+        root_stat = os.fstat(root_fd)
+        if root_stat.st_dev != int(payload["rootDev"]) or root_stat.st_ino != int(payload["rootIno"]):
+            raise RuntimeError("fs-safe-root-mismatch")
 def stat_path(root_fd, payload):
     relative = payload.get("relativePath", "")
     segments = split_relative(relative)
@@ -179,7 +184,6 @@ def stat_path(root_fd, payload):
         return encode_stat(st)
     finally:
         os.close(parent_fd)
-
 def readdir_path(root_fd, payload):
     dir_fd = walk_dir(root_fd, split_relative(payload.get("relativePath", "")))
     try:
@@ -195,12 +199,9 @@ def readdir_path(root_fd, payload):
         return entries
     finally:
         os.close(dir_fd)
-
 def mkdirp_path(root_fd, payload):
     dir_fd = walk_dir(root_fd, split_relative(payload.get("relativePath", "")), mkdir_enabled=True)
-    os.close(dir_fd)
-    return None
-
+    os.close(dir_fd); return None
 def remove_tree(parent_fd, basename):
     st = os.lstat(basename, dir_fd=parent_fd)
     if stat.S_ISDIR(st.st_mode) and not stat.S_ISLNK(st.st_mode):
@@ -213,7 +214,6 @@ def remove_tree(parent_fd, basename):
         os.rmdir(basename, dir_fd=parent_fd)
     else:
         os.unlink(basename, dir_fd=parent_fd)
-
 def remove_path(root_fd, payload):
     parent_fd, basename = parent_and_basename(root_fd, payload.get("relativePath", ""))
     try:
@@ -296,14 +296,15 @@ def write_path(root_fd, payload):
             except FileNotFoundError:
                 pass
         temp_name, temp_fd = create_temp_file(parent_fd, basename, mode)
+        os.fchmod(temp_fd, mode)
         write_all(temp_fd, data)
         os.fsync(temp_fd)
+        temp_stat = os.fstat(temp_fd)
         os.close(temp_fd)
         temp_fd = None
-        commit_temp_file(parent_fd, temp_name, basename, overwrite, mode)
+        result_stat = commit_temp_file(parent_fd, temp_name, basename, overwrite, mode, temp_stat)
         temp_name = None
         os.fsync(parent_fd)
-        result_stat = os.stat(basename, dir_fd=parent_fd, follow_symlinks=False)
         return {"dev": result_stat.st_dev, "ino": result_stat.st_ino}
     finally:
         if temp_fd is not None:
@@ -334,6 +335,7 @@ def copy_path(root_fd, payload):
             raise RuntimeError("fs-safe-too-large:%d:%d" % (max_bytes, source_stat.st_size))
         parent_fd = walk_dir(root_fd, split_relative(payload.get("relativeParentPath", "")), bool(payload.get("mkdir", True)))
         temp_name, temp_fd = create_temp_file(parent_fd, basename, mode)
+        os.fchmod(temp_fd, mode)
         written_bytes = 0
         while True:
             chunk = os.read(source_fd, 65536)
@@ -349,12 +351,12 @@ def copy_path(root_fd, payload):
                     raise OSError(errno.EIO, "short write")
                 view = view[written:]
         os.fsync(temp_fd)
+        temp_stat = os.fstat(temp_fd)
         os.close(temp_fd)
         temp_fd = None
-        commit_temp_file(parent_fd, temp_name, basename, overwrite, mode)
+        result_stat = commit_temp_file(parent_fd, temp_name, basename, overwrite, mode, temp_stat)
         temp_name = None
         os.fsync(parent_fd)
-        result_stat = os.stat(basename, dir_fd=parent_fd, follow_symlinks=False)
         return {"dev": result_stat.st_dev, "ino": result_stat.st_ino}
     finally:
         os.close(source_fd)
@@ -371,6 +373,7 @@ def copy_path(root_fd, payload):
 def run_operation(operation, root_path, payload):
     root_fd = open_dir(root_path)
     try:
+        assert_expected_root(root_fd, payload)
         if operation == "stat":
             return stat_path(root_fd, payload)
         if operation == "readdir":
@@ -475,6 +478,12 @@ function mapWorkerError(response) {
     if (message.includes("fs-safe-source-mismatch")) {
         return new FsSafeError("path-mismatch", "source path changed during copy");
     }
+    if (message.includes("fs-safe-temp-mismatch")) {
+        return new FsSafeError("path-mismatch", "temp path changed during write");
+    }
+    if (message.includes("fs-safe-root-mismatch")) {
+        return new FsSafeError("path-mismatch", "root path changed during operation");
+    }
     if (message.includes("fs-safe-directory-noreplace-unsupported")) {
         return new FsSafeError("invalid-path", "directory moves require overwrite: true");
     }
@@ -655,9 +664,7 @@ export function validatePinnedOperationPayload(payload) {
     }
 }
 export function isPinnedHelperUnavailable(error) {
-    return error instanceof Error &&
-        "code" in error &&
-        error.code === "helper-unavailable";
+    return error instanceof Error && "code" in error && error.code === "helper-unavailable";
 }
 function validatePinnedRelativePath(relativePath) {
     if (relativePath.length === 0 || relativePath === ".") {

package/dist/pinned-write.d.ts

@@ -1,4 +1,4 @@
-import { type Readable } from "node:stream";
+import type { Readable } from "node:stream";
 import type { FileIdentityStat } from "./file-identity.js";
 type PinnedWriteInput = {
     kind: "buffer";
@@ -17,6 +17,7 @@ export declare function runPinnedWriteHelper(params: {
     overwrite?: boolean;
     maxBytes?: number;
     input: PinnedWriteInput;
+    rootIdentity?: FileIdentityStat;
 }): Promise<FileIdentityStat>;
 export declare function runPinnedCopyHelper(params: {
     rootPath: string;
@@ -28,6 +29,7 @@ export declare function runPinnedCopyHelper(params: {
     maxBytes?: number;
     sourcePath: string;
     sourceIdentity: FileIdentityStat;
+    rootIdentity?: FileIdentityStat;
 }): Promise<FileIdentityStat>;
 export {};
 //# sourceMappingURL=pinned-write.d.ts.map

package/dist/pinned-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAS3D,KAAK,gBAAgB,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAuFzC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;CACzB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuC5B;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoB5B"}
+{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAW3D,KAAK,gBAAgB,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AA6EzC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwC5B;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,gBAAgB,CAAC;IACjC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqB5B"}

package/dist/pinned-write.js

@@ -2,11 +2,11 @@ import { randomUUID } from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { Transform } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { createNearestExistingDirectoryGuard } from "./directory-guard.js";
+import { createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
 import { assertPinnedPythonOperationAvailable, runPinnedPythonOperation, validatePinnedOperationPayload, } from "./pinned-python.js";
 function byteLength(input, encoding) {
@@ -28,29 +28,21 @@ function assertWithinMaxBytes(bytes, maxBytes) {
         throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
     }
 }
-function createMaxBytesTransform(maxBytes) {
-    if (maxBytes === undefined) {
-        return undefined;
-    }
+async function writeStreamToHandle(stream, handle, maxBytes) {
     let bytes = 0;
-    return new Transform({
-        transform(chunk, _encoding, callback) {
-            bytes += chunk.byteLength;
-            if (bytes > maxBytes) {
-                callback(new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`));
-                return;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.byteLength;
+        assertWithinMaxBytes(bytes, maxBytes);
+        let offset = 0;
+        while (offset < buffer.byteLength) {
+            const { bytesWritten } = await handle.write(buffer, offset, buffer.byteLength - offset);
+            if (bytesWritten <= 0) {
+                throw new FsSafeError("helper-failed", "fallback stream write made no progress");
             }
-            callback(null, chunk);
-        },
-    });
-}
-async function pipelineWithMaxBytes(stream, destination, maxBytes) {
-    const limiter = createMaxBytesTransform(maxBytes);
-    if (limiter) {
-        await pipeline(stream, limiter, destination);
-        return;
+            offset += bytesWritten;
+        }
     }
-    await pipeline(stream, destination);
 }
 async function inputToBase64(input, maxBytes) {
     if (input.kind === "buffer") {
@@ -75,7 +67,7 @@ export async function runPinnedWriteHelper(params) {
         relativeParentPath: params.relativeParentPath,
     });
     if (getFsSafePythonConfig().mode === "off") {
-        return await runPinnedWriteFallback(params);
+        return await runPinnedWriteFallbackOrThrow(params);
     }
     if (params.input.kind === "stream") {
         try {
@@ -83,7 +75,7 @@ export async function runPinnedWriteHelper(params) {
         }
         catch (error) {
             if (canFallbackFromPythonError(error)) {
-                return await runPinnedWriteFallback(params);
+                return await runPinnedWriteFallbackOrThrow(params, error);
             }
             throw error;
         }
@@ -96,6 +88,7 @@ export async function runPinnedWriteHelper(params) {
         mode: params.mode || 0o600,
         overwrite: params.overwrite !== false,
         relativeParentPath: params.relativeParentPath,
+        ...(params.rootIdentity ? { rootDev: params.rootIdentity.dev, rootIno: params.rootIdentity.ino } : {}),
     };
     try {
         return await runPinnedPythonOperation({
@@ -106,7 +99,7 @@ export async function runPinnedWriteHelper(params) {
     }
     catch (error) {
         if (canFallbackFromPythonError(error)) {
-            return await runPinnedWriteFallback(params);
+            return await runPinnedWriteFallbackOrThrow(params, error);
         }
         throw error;
     }
@@ -126,22 +119,29 @@ export async function runPinnedCopyHelper(params) {
             mode: params.mode || 0o600,
             overwrite: params.overwrite !== false,
             relativeParentPath: params.relativeParentPath,
+            ...(params.rootIdentity ? { rootDev: params.rootIdentity.dev, rootIno: params.rootIdentity.ino } : {}),
             sourceDev: params.sourceIdentity.dev,
             sourceIno: params.sourceIdentity.ino,
             sourcePath: params.sourcePath,
         },
     });
 }
+async function runPinnedWriteFallbackOrThrow(params, cause) {
+    if (process.platform !== "win32") {
+        throw new FsSafeError("helper-unavailable", "Python helper is required for pinned writes on this platform", { cause });
+    }
+    return await runPinnedWriteFallback(params);
+}
 async function runPinnedWriteFallback(params) {
     const parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
-    const parentGuard = await createNearestExistingDirectoryGuard(params.rootPath, parentPath);
     if (params.mkdir) {
-        await withAsyncDirectoryGuards([parentGuard], async () => {
-            await fs.mkdir(parentPath, { recursive: true });
-        });
+        await mkdirPathComponentsWithGuards({ rootReal: params.rootPath, targetPath: parentPath });
     }
+    const parentGuard = params.mkdir
+        ? await createAsyncDirectoryGuard(parentPath)
+        : await createNearestExistingDirectoryGuard(params.rootPath, parentPath);
     const targetPath = path.join(parentPath, params.basename);
     if (params.overwrite === false) {
         let handle = await withAsyncDirectoryGuards([parentGuard], async () => await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode), {
@@ -163,7 +163,7 @@ async function runPinnedWriteFallback(params) {
                 }
             }
             else {
-                await pipelineWithMaxBytes(params.input.stream, handle.createWriteStream(), params.maxBytes);
+                await writeStreamToHandle(params.input.stream, handle, params.maxBytes);
             }
             const stat = await handle.stat();
             created = false;
@@ -184,7 +184,9 @@ async function runPinnedWriteFallback(params) {
             ? fsSync.constants.O_NOFOLLOW
             : 0);
     let handle;
-    let handleClosedByStream = false;
+    let tempStat;
+    let targetStat;
+    let renamed = false;
     try {
         handle = await fs.open(tempPath, tempFlags, params.mode);
         if (params.input.kind === "buffer") {
@@ -197,27 +199,34 @@ async function runPinnedWriteFallback(params) {
             }
         }
         else {
-            const writable = handle.createWriteStream();
-            writable.once("close", () => {
-                handleClosedByStream = true;
-            });
-            await pipelineWithMaxBytes(params.input.stream, writable, params.maxBytes);
+            await writeStreamToHandle(params.input.stream, handle, params.maxBytes);
         }
-        if (!handleClosedByStream) {
-            await handle.close().catch(() => undefined);
-            handle = undefined;
+        tempStat = await handle.stat();
+        const tempPathStat = await fs.lstat(tempPath);
+        if (tempPathStat.isSymbolicLink() || !sameFileIdentity(tempPathStat, tempStat)) {
+            throw new FsSafeError("path-mismatch", "fallback temp path changed during write");
         }
+        const expectedTempStat = tempStat;
+        await handle.close().catch(() => undefined);
+        handle = undefined;
         await withAsyncDirectoryGuards([parentGuard], async () => {
             await fs.rename(tempPath, targetPath);
+            renamed = true;
+            targetStat = await fs.lstat(targetPath);
+            if (targetStat.isSymbolicLink() || !sameFileIdentity(targetStat, expectedTempStat)) {
+                throw new FsSafeError("path-mismatch", "fallback target changed during write");
+            }
         });
     }
     catch (error) {
-        if (handle && !handleClosedByStream) {
-            await handle.close().catch(() => undefined);
+        await handle?.close().catch(() => undefined);
+        if (!renamed) {
+            await fs.rm(tempPath, { force: true }).catch(() => undefined);
         }
-        await fs.rm(tempPath, { force: true }).catch(() => undefined);
         throw error;
     }
-    const stat = await fs.stat(targetPath);
-    return { dev: stat.dev, ino: stat.ino };
+    if (!targetStat) {
+        throw new FsSafeError("path-mismatch", "fallback target was not verified");
+    }
+    return { dev: targetStat.dev, ino: targetStat.ino };
 }

package/dist/root-path.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside, isPathRelativeEscape } from "./path.js";
 export const ROOT_PATH_ALIAS_POLICIES = {
     strict: Object.freeze({
         allowFinalSymlinkForUnlink: false,
@@ -531,7 +531,7 @@ function relativeInsideRoot(rootPath, targetPath) {
     if (!relative || relative === ".") {
         return "";
     }
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         return "";
     }
     return relative;

package/dist/secret-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAqHF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoFD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhB"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAqHF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoID,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+ChB"}

package/dist/secret-file.js

@@ -1,12 +1,12 @@
-import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
-import { createAsyncDirectoryGuard } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
+import { runPinnedWriteHelper } from "./pinned-write.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
@@ -128,15 +128,18 @@ export function tryReadSecretFileSync(filePath, label, options = {}) {
     const result = readSecretFileOutcomeSync(filePath, label, options);
     return result.ok ? result.secret : undefined;
 }
+function isRelativeEscape(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
 function assertPathWithinRoot(rootDir, targetPath) {
     const relative = path.relative(rootDir, targetPath);
-    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (!relative || isRelativeEscape(relative)) {
         throw new Error(`Private secret path must stay under ${rootDir}.`);
     }
 }
 function assertRealPathWithinRoot(rootDir, targetPath) {
     const relative = path.relative(rootDir, targetPath);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isRelativeEscape(relative)) {
         throw new Error(`Private secret path must stay under ${rootDir}.`);
     }
 }
@@ -151,30 +154,62 @@ async function enforcePrivatePathMode(resolvedPath, expectedMode, kind) {
         throw new Error(`Private secret ${kind} ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
     }
 }
+async function enforcePrivateFileIdentityAndMode(resolvedPath, expectedIdentity, expectedMode) {
+    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0;
+    const handle = await fsp.open(resolvedPath, fs.constants.O_RDONLY | noFollowFlag);
+    try {
+        const openedStat = await handle.stat();
+        if (!openedStat.isFile() || !sameFileIdentity(openedStat, expectedIdentity)) {
+            throw new FsSafeError("path-mismatch", "private secret file changed during write");
+        }
+        const pathStat = await fsp.lstat(resolvedPath);
+        if (pathStat.isSymbolicLink() || !sameFileIdentity(pathStat, openedStat)) {
+            throw new FsSafeError("path-mismatch", "private secret path changed during write");
+        }
+        if (process.platform !== "win32") {
+            await handle.chmod(expectedMode);
+            const chmodStat = await handle.stat();
+            const actualMode = chmodStat.mode & 0o777;
+            if (actualMode !== expectedMode) {
+                throw new Error(`Private secret file ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
+            }
+            const refreshedPathStat = await fsp.lstat(resolvedPath);
+            if (refreshedPathStat.isSymbolicLink() || !sameFileIdentity(refreshedPathStat, chmodStat)) {
+                throw new FsSafeError("path-mismatch", "private secret path changed during mode check");
+            }
+        }
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
 async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     const resolvedRoot = path.resolve(rootDir);
     const resolvedTarget = path.resolve(targetDir);
+    await fsp.mkdir(resolvedRoot, { recursive: true, mode });
+    const rootStat = await fsp.lstat(resolvedRoot);
+    if (rootStat.isSymbolicLink()) {
+        throw new Error(`Private secret root ${resolvedRoot} must not be a symlink.`);
+    }
+    if (!rootStat.isDirectory()) {
+        throw new Error(`Private secret root ${resolvedRoot} must be a directory.`);
+    }
+    const rootGuard = await createAsyncDirectoryGuard(resolvedRoot);
+    await enforcePrivatePathMode(rootGuard.realPath, mode, "directory");
+    await assertAsyncDirectoryGuard(rootGuard);
     if (resolvedTarget === resolvedRoot) {
-        await fsp.mkdir(resolvedRoot, { recursive: true, mode });
-        const rootStat = await fsp.lstat(resolvedRoot);
-        if (rootStat.isSymbolicLink()) {
-            throw new Error(`Private secret root ${resolvedRoot} must not be a symlink.`);
-        }
-        if (!rootStat.isDirectory()) {
-            throw new Error(`Private secret root ${resolvedRoot} must be a directory.`);
-        }
-        await enforcePrivatePathMode(resolvedRoot, mode, "directory");
-        return;
+        return { rootGuard, targetReal: rootGuard.realPath };
     }
     assertPathWithinRoot(resolvedRoot, resolvedTarget);
-    await ensurePrivateDirectory(resolvedRoot, resolvedRoot, mode);
-    const resolvedRootReal = await fsp.realpath(resolvedRoot);
+    const resolvedRootReal = rootGuard.realPath;
     let current = resolvedRoot;
     for (const segment of path
         .relative(resolvedRoot, resolvedTarget)
         .split(path.sep)
         .filter(Boolean)) {
         current = path.join(current, segment);
+        const parentGuard = await createAsyncDirectoryGuard(path.dirname(current));
+        await assertAsyncDirectoryGuard(rootGuard);
         try {
             const stat = await fsp.lstat(current);
             if (stat.isSymbolicLink()) {
@@ -188,12 +223,16 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
             if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
                 throw error;
             }
+            await assertAsyncDirectoryGuard(parentGuard);
             await fsp.mkdir(current, { mode });
         }
         const currentReal = await fsp.realpath(current);
         assertRealPathWithinRoot(resolvedRootReal, currentReal);
         await enforcePrivatePathMode(currentReal, mode, "directory");
+        await assertAsyncDirectoryGuard(parentGuard);
+        await assertAsyncDirectoryGuard(rootGuard);
     }
+    return { rootGuard, targetReal: await fsp.realpath(resolvedTarget) };
 }
 export async function writeSecretFileAtomic(params) {
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
@@ -202,13 +241,12 @@ export async function writeSecretFileAtomic(params) {
     const resolvedFile = path.resolve(params.filePath);
     assertPathWithinRoot(resolvedRoot, resolvedFile);
     const intendedParentDir = path.dirname(resolvedFile);
-    await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
-    const resolvedRootReal = await fsp.realpath(resolvedRoot);
-    const parentDir = await fsp.realpath(intendedParentDir);
-    assertRealPathWithinRoot(resolvedRootReal, parentDir);
-    const parentGuard = await createAsyncDirectoryGuard(parentDir);
+    const { rootGuard, targetReal } = await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
+    await assertAsyncDirectoryGuard(rootGuard);
+    assertRealPathWithinRoot(rootGuard.realPath, targetReal);
+    const parentGuard = await createAsyncDirectoryGuard(targetReal);
     const fileName = path.basename(resolvedFile);
-    const finalFilePath = path.join(parentDir, fileName);
+    const finalFilePath = path.join(targetReal, fileName);
     try {
         const stat = await fsp.lstat(finalFilePath);
         if (stat.isSymbolicLink()) {
@@ -223,31 +261,19 @@ export async function writeSecretFileAtomic(params) {
             throw error;
         }
     }
-    const tempPath = path.join(parentDir, `.tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString("hex")}`);
-    let createdTemp = false;
-    try {
-        const handle = await fsp.open(tempPath, "wx", mode);
-        createdTemp = true;
-        try {
-            await handle.writeFile(params.content);
-        }
-        finally {
-            await handle.close();
-        }
-        await enforcePrivatePathMode(tempPath, mode, "file");
-        const refreshedParentReal = await fsp.realpath(intendedParentDir);
-        if (refreshedParentReal !== parentDir) {
-            throw new Error(`Private secret parent directory changed during write for ${finalFilePath}.`);
-        }
-        await withAsyncDirectoryGuards([parentGuard], async () => {
-            await fsp.rename(tempPath, finalFilePath);
-        });
-        createdTemp = false;
-        await enforcePrivatePathMode(finalFilePath, mode, "file");
-    }
-    finally {
-        if (createdTemp) {
-            await fsp.unlink(tempPath).catch(() => undefined);
-        }
-    }
+    await assertAsyncDirectoryGuard(rootGuard);
+    await assertAsyncDirectoryGuard(parentGuard);
+    const identity = await runPinnedWriteHelper({
+        rootPath: parentGuard.realPath,
+        relativeParentPath: "",
+        basename: fileName,
+        mkdir: false,
+        mode,
+        overwrite: true,
+        input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
+        rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
+    });
+    await assertAsyncDirectoryGuard(rootGuard);
+    await assertAsyncDirectoryGuard(parentGuard);
+    await enforcePrivateFileIdentityAndMode(finalFilePath, identity, mode);
 }

package/dist/temp-target.js

@@ -52,7 +52,7 @@ async function cleanupTempDir(dir, onCleanupError) {
     }
 }
 function resolveTempRoot(rootDir) {
-    return rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" });
+    return path.resolve(rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" }));
 }
 export async function tempFile(params) {
     const rootDir = resolveTempRoot(params.rootDir);

package/docs/python-helper.md

@@ -62,12 +62,12 @@ 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;
+- file identity checks around reads and writes where a safe Node fallback exists;
+- atomic sibling-temp replacement on fallback platforms;
 - 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.
+What gets weaker is the POSIX defense against another same-UID process swapping a parent directory between validation and mutation. Write paths that need fd-relative parent commits now fail closed when the helper is disabled or unavailable; other operations such as `root().move()`, `root().remove()`, and `root().mkdir()` may still 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.
 

package/docs/root.md

@@ -102,15 +102,14 @@ operations that Node's `fs` API does not expose ergonomically.
 ```ts
 import { configureFsSafePython } from "@openclaw/fs-safe/config";
 
-configureFsSafePython({ mode: "off" });     // Node-only fallback path
+configureFsSafePython({ mode: "off" });     // disable helper; some writes fail closed
 configureFsSafePython({ mode: "require" }); // fail if fd-relative helper unavailable
 ```
 
-`auto` is the default. Configure the mode before creating roots. Without the
-helper, root methods still run, but same-UID races that swap parent directories
-between validation and mutation are harder to close completely. Use `require`
-when that downgrade should be treated as a deployment failure. See
-[Python helper policy](python-helper.md) for deployment guidance.
+`auto` is the default. Configure the mode before creating roots. On POSIX,
+write methods that require fd-relative parent commits fail closed without the
+helper. Use `require` when any helper loss should be treated as a deployment
+failure. See [Python helper policy](python-helper.md) for deployment guidance.
 
 ### Properties
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {