@openclaw/fs-safe 0.2.4 → 0.2.5

package/dist/pinned-python.js

@@ -87,6 +87,85 @@ def reject_unsafe_endpoint(st):
     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)
+        if not chunk:
+            break
+        view = memoryview(chunk)
+        while view:
+            written = os.write(dest_fd, view)
+            if written <= 0:
+                raise OSError(errno.EIO, "short write")
+            view = view[written:]
+
+def write_all(fd, data):
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        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:
+        os.link(name, new_name, src_dir_fd=source_fd, dst_dir_fd=target_fd, follow_symlinks=False)
+        linked = True
+        os.unlink(name, dir_fd=source_fd)
+    except Exception:
+        if linked:
+            try: os.unlink(new_name, dir_fd=target_fd)
+            except FileNotFoundError: pass
+        raise
+    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
+    try:
+        if expected is not None:
+            source_stat = os.fstat(source_fd)
+            if source_stat.st_dev != expected.st_dev or source_stat.st_ino != expected.st_ino:
+                raise RuntimeError("fs-safe-source-mismatch")
+        dest_fd = os.open(basename, WRITE_FLAGS, mode, dir_fd=target_parent_fd)
+        copy_bytes(source_fd, dest_fd)
+        os.fsync(dest_fd)
+        success = True
+    finally:
+        os.close(source_fd)
+        if dest_fd is not None:
+            os.close(dest_fd)
+        if dest_fd is not None and not success:
+            try: os.unlink(basename, dir_fd=target_parent_fd)
+            except FileNotFoundError: pass
+    if unlink_source:
+        try:
+            os.unlink(source_name, dir_fd=source_parent_fd)
+        except Exception:
+            try: os.unlink(basename, dir_fd=target_parent_fd)
+            except FileNotFoundError: pass
+            raise
+
+def commit_temp_file(parent_fd, temp_name, basename, overwrite, mode):
+    if overwrite:
+        os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
+    else:
+        try:
+            os.link(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False)
+            os.unlink(temp_name, dir_fd=parent_fd)
+        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)
+
 def stat_path(root_fd, payload):
     relative = payload.get("relativePath", "")
     segments = split_relative(relative)
@@ -161,7 +240,18 @@ def rename_path(root_fd, payload):
     try:
         from_stat = os.lstat(from_base, dir_fd=from_parent_fd)
         reject_unsafe_endpoint(from_stat)
-        if not payload.get("overwrite", True):
+        overwrite = payload.get("overwrite", True)
+        if not overwrite and stat.S_ISREG(from_stat.st_mode):
+            try:
+                link_no_replace(from_base, to_base, from_parent_fd, to_parent_fd)
+            except OSError as exc:
+                if not link_unsupported(exc):
+                    raise
+                copy_file_no_replace(from_parent_fd, from_base, to_parent_fd, to_base, stat.S_IMODE(from_stat.st_mode), from_stat, True)
+            return None
+        if not overwrite and stat.S_ISDIR(from_stat.st_mode):
+            raise RuntimeError("fs-safe-directory-noreplace-unsupported")
+        if not overwrite:
             try:
                 os.lstat(to_base, dir_fd=to_parent_fd)
                 raise FileExistsError(errno.EEXIST, "destination exists", to_base)
@@ -206,16 +296,11 @@ def write_path(root_fd, payload):
             except FileNotFoundError:
                 pass
         temp_name, temp_fd = create_temp_file(parent_fd, basename, mode)
-        view = memoryview(data)
-        while view:
-            written = os.write(temp_fd, view)
-            if written <= 0:
-                raise OSError(errno.EIO, "short write")
-            view = view[written:]
+        write_all(temp_fd, data)
         os.fsync(temp_fd)
         os.close(temp_fd)
         temp_fd = None
-        os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
+        commit_temp_file(parent_fd, temp_name, basename, overwrite, mode)
         temp_name = None
         os.fsync(parent_fd)
         result_stat = os.stat(basename, dir_fd=parent_fd, follow_symlinks=False)
@@ -248,12 +333,6 @@ def copy_path(root_fd, payload):
         if max_bytes >= 0 and source_stat.st_size > max_bytes:
             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)))
-        if not overwrite:
-            try:
-                os.lstat(basename, dir_fd=parent_fd)
-                raise FileExistsError(errno.EEXIST, "destination exists", basename)
-            except FileNotFoundError:
-                pass
         temp_name, temp_fd = create_temp_file(parent_fd, basename, mode)
         written_bytes = 0
         while True:
@@ -272,7 +351,7 @@ def copy_path(root_fd, payload):
         os.fsync(temp_fd)
         os.close(temp_fd)
         temp_fd = None
-        os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
+        commit_temp_file(parent_fd, temp_name, basename, overwrite, mode)
         temp_name = None
         os.fsync(parent_fd)
         result_stat = os.stat(basename, dir_fd=parent_fd, follow_symlinks=False)
@@ -396,6 +475,9 @@ 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-directory-noreplace-unsupported")) {
+        return new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    }
     if (code === "FileNotFoundError" || errno === 2) {
         return new FsSafeError("not-found", "file not found");
     }
@@ -413,19 +495,19 @@ function mapWorkerError(response) {
     }
     return new FsSafeError("helper-failed", message);
 }
-function rejectPending(error) {
-    if (!worker) {
+function rejectPending(error, targetWorker = worker) {
+    if (!targetWorker || worker !== targetWorker) {
         return;
     }
-    setWorkerRef(worker, false);
-    for (const pending of worker.pending.values()) {
+    setWorkerRef(targetWorker, false);
+    for (const pending of targetWorker.pending.values()) {
         pending.reject(error);
     }
-    worker.pending.clear();
+    targetWorker.pending.clear();
     worker = null;
 }
-function handleWorkerLine(line) {
-    if (!worker || !line.trim()) {
+function handleWorkerLine(currentWorker, line) {
+    if (worker !== currentWorker || !line.trim()) {
         return;
     }
     let decoded;
@@ -433,11 +515,11 @@ function handleWorkerLine(line) {
         decoded = JSON.parse(line);
     }
     catch {
-        rejectPending(new FsSafeError("helper-failed", `pinned helper returned invalid JSON: ${line}`));
+        rejectPending(new FsSafeError("helper-failed", `pinned helper returned invalid JSON: ${line}`), currentWorker);
         return;
     }
     if (typeof decoded !== "object" || decoded === null || !("id" in decoded)) {
-        rejectPending(new FsSafeError("helper-failed", "pinned helper returned invalid response"));
+        rejectPending(new FsSafeError("helper-failed", "pinned helper returned invalid response"), currentWorker);
         return;
     }
     const response = decoded;
@@ -445,13 +527,13 @@ function handleWorkerLine(line) {
     if (id === undefined) {
         return;
     }
-    const pending = worker.pending.get(id);
+    const pending = currentWorker.pending.get(id);
     if (!pending) {
         return;
     }
-    worker.pending.delete(id);
-    if (worker.pending.size === 0) {
-        setWorkerRef(worker, false);
+    currentWorker.pending.delete(id);
+    if (currentWorker.pending.size === 0) {
+        setWorkerRef(currentWorker, false);
     }
     if (response.ok === true) {
         pending.resolve(response.result);
@@ -467,28 +549,28 @@ function getWorker() {
     const child = spawn(resolvePython(), ["-u", "-c", PINNED_PYTHON_WORKER_SOURCE], {
         stdio: ["pipe", "pipe", "pipe"],
     });
-    worker = { child, pending: new Map(), stderr: "", stdoutBuffer: "" };
+    const currentWorker = { child, pending: new Map(), stderr: "", stdoutBuffer: "" };
+    worker = currentWorker;
     child.stdout.setEncoding("utf8");
     child.stderr.setEncoding("utf8");
     child.stdout.on("data", (chunk) => {
-        const current = worker;
-        if (!current) {
+        if (worker !== currentWorker) {
             return;
         }
-        current.stdoutBuffer += chunk;
+        currentWorker.stdoutBuffer += chunk;
         for (;;) {
-            const newline = current.stdoutBuffer.indexOf("\n");
+            const newline = currentWorker.stdoutBuffer.indexOf("\n");
             if (newline < 0) {
                 break;
             }
-            const line = current.stdoutBuffer.slice(0, newline);
-            current.stdoutBuffer = current.stdoutBuffer.slice(newline + 1);
-            handleWorkerLine(line);
+            const line = currentWorker.stdoutBuffer.slice(0, newline);
+            currentWorker.stdoutBuffer = currentWorker.stdoutBuffer.slice(newline + 1);
+            handleWorkerLine(currentWorker, line);
         }
     });
     child.stderr.on("data", (chunk) => {
-        if (worker) {
-            worker.stderr = `${worker.stderr}${chunk}`.slice(-4096);
+        if (worker === currentWorker) {
+            currentWorker.stderr = `${currentWorker.stderr}${chunk}`.slice(-4096);
         }
     });
     child.once("error", (error) => {
@@ -497,17 +579,17 @@ function getWorker() {
             : error instanceof Error
                 ? error
                 : new Error(String(error));
-        rejectPending(mapped);
+        rejectPending(mapped, currentWorker);
     });
     child.once("close", (code, signal) => {
-        const stderr = worker?.stderr.trim();
-        rejectPending(new FsSafeError("helper-failed", stderr || `pinned helper exited with code ${code ?? "null"} (${signal ?? "?"})`));
+        const stderr = currentWorker.stderr.trim();
+        rejectPending(new FsSafeError("helper-failed", stderr || `pinned helper exited with code ${code ?? "null"} (${signal ?? "?"})`), currentWorker);
     });
     process.once("exit", () => {
         child.kill("SIGTERM");
     });
-    setWorkerRef(worker, false);
-    return worker;
+    setWorkerRef(currentWorker, false);
+    return currentWorker;
 }
 function setRefable(value, ref) {
     if (!value) {

package/dist/root-impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-impl.d.ts","sourceRoot":"","sources":["../src/root-impl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"root-impl.d.ts","sourceRoot":"","sources":["../src/root-impl.ts"],"names":[],"mappings":"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"}

package/dist/root-impl.js

@@ -20,6 +20,7 @@ import { resolveRootPath } from "./root-path.js";
 import { assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, } from "./root-context.js";
 import { isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { stringifyJsonDocument } from "./json-stringify.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { serializePathWrite } from "./write-queue.js";
 function logWarn(message) {
@@ -260,12 +261,12 @@ class RootHandle {
     }
     async writeJson(relativePath, data, options = {}) {
         const { replacer, space, trailingNewline = true, ...writeOptions } = options;
-        const json = JSON.stringify(data, replacer, space);
+        const json = stringifyJsonDocument(data, replacer, space);
         await this.write(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
     }
     async createJson(relativePath, data, options = {}) {
         const { replacer, space, trailingNewline = true, ...writeOptions } = options;
-        const json = JSON.stringify(data, replacer, space);
+        const json = stringifyJsonDocument(data, replacer, space);
         await this.create(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
     }
     async copyIn(relativePath, sourcePath, options = {}) {
@@ -1050,6 +1051,9 @@ async function movePathFallback(root, params) {
     if (sourceStat.isFile() && sourceStat.nlink > 1) {
         throw new FsSafeError("hardlink", "hardlinked path not allowed");
     }
+    if (!params.overwrite && sourceStat.isDirectory()) {
+        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    }
     if (!params.overwrite) {
         try {
             await fs.lstat(target.resolved);

package/dist/root-paths.js

@@ -62,7 +62,7 @@ export function resolvePathWithinRoot(params) {
     }
     const resolved = path.resolve(root, raw);
     const rel = path.relative(root, resolved);
-    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+    if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
         return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
     }
     return { ok: true, path: resolved };
@@ -118,7 +118,7 @@ async function resolveNearestExistingPath(targetPath) {
 }
 async function assertNoSymlinkSegments(params) {
     const relative = path.relative(params.rootDir, params.targetPath);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
         throw new Error(`Invalid path: must stay within ${params.scopeLabel}`);
     }
     let current = params.rootDir;
@@ -266,7 +266,10 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
     const rootDir = path.resolve(params.rootDir);
     const rootRealPath = await resolveRealPathIfExists(rootDir);
     const root = rootRealPath ? await openRoot(rootDir) : undefined;
-    const isInRoot = (relativePath) => Boolean(relativePath) && !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+    const isInRoot = (relativePath) => Boolean(relativePath) &&
+        relativePath !== ".." &&
+        !relativePath.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relativePath);
     const resolveExistingRelativePath = async (requestedPath) => {
         const raw = requestedPath.trim();
         const lexicalPathResult = resolvePathWithinRoot({
@@ -316,6 +319,25 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
         }
         catch (err) {
             if (allowMissingFallback && err instanceof FsSafeError && err.code === "not-found") {
+                if (!rootRealPath) {
+                    resolvedPaths.push(pathResult.fallbackPath);
+                    continue;
+                }
+                try {
+                    await assertNoSymlinkSegments({
+                        rootDir,
+                        targetPath: pathResult.fallbackPath,
+                        scopeLabel: params.scopeLabel,
+                    });
+                    const existingPath = await resolveNearestExistingPath(pathResult.fallbackPath);
+                    const existingRealPath = await fs.realpath(existingPath);
+                    if (!isPathInside(rootRealPath, existingRealPath)) {
+                        return invalidPath(params.scopeLabel);
+                    }
+                }
+                catch {
+                    return invalidPath(params.scopeLabel);
+                }
                 resolvedPaths.push(pathResult.fallbackPath);
                 continue;
             }

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

@@ -1 +1 @@
-{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAUrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAkKF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAa/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAUrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAsKF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAa/B"}

package/dist/secure-file.js

@@ -9,7 +9,9 @@ import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadab
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
 const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 function isAbsolutePathname(value) {
-    return path.isAbsolute(value) || isWindowsDriveLetterPath(value, "win32") || isWindowsNetworkPath(value, "win32");
+    return (path.isAbsolute(value) ||
+        (process.platform === "win32" &&
+            (isWindowsDriveLetterPath(value, "win32") || isWindowsNetworkPath(value, "win32"))));
 }
 function label(options) {
     return options.label ?? "Secure file";

package/dist/timing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CAuBZ"}
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/dist/timing.js

@@ -12,7 +12,14 @@ export async function withTimeout(promise, timeoutMs, labelOrOptions = {
         return await Promise.race([
             promise,
             new Promise((_, reject) => {
-                timeoutId = setTimeout(() => reject(createError()), timeoutMs);
+                timeoutId = setTimeout(() => {
+                    try {
+                        reject(createError());
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }, timeoutMs);
             }),
         ]);
     }

package/docs/index.md

@@ -64,7 +64,7 @@ await fs.remove("notes/archive/today.txt");
 | [`extractArchive`](archive.md) | ZIP/TAR extraction with size, count, link, and traversal limits. |
 | [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
 | [Permissions](permissions.md) | POSIX mode and Windows ACL inspection/remediation helpers. |
-| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
+| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry, fail-closed stale-lock handling, and opt-in caller-approved stale removal. |
 | [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
 | [`pathScope()`](path-scope.md) | Lower-level absolute-path boundary helper; lives behind `@openclaw/fs-safe/advanced`. |
 | [`@openclaw/fs-safe/advanced`](advanced.md) | Directory of lower-level composition helpers (path scopes, regular-file I/O, install paths, sibling-temp writes, …). |

package/docs/json-store.md

@@ -53,7 +53,7 @@ type JsonStoreLockOptions = {
   staleMs?: number;     // default 30_000
   timeoutMs?: number;   // default 30_000
   retry?: FileLockRetryOptions;
-  staleRecovery?: "fail-closed";
+  staleRecovery?: "fail-closed" | "remove-if-unchanged";
   managerKey?: string;  // default `fs-safe.json-store:<filePath>`
 };
 
@@ -141,6 +141,8 @@ When `lock` is falsy, `read` / `write` / `update` are unlocked. The `update` sha
 
 Process-wide lock defaults from `configureFsSafeLocks()` apply only after locking is explicitly enabled. They do not make JSON stores lock by default.
 
+JSON store locks do not expose `shouldRemoveStaleLock`, so `staleRecovery: "remove-if-unchanged"` cannot remove a stale sidecar by itself. Use the lower-level [file lock](sidecar-lock.md) API when your application needs custom owner-liveness checks and caller-approved stale-lock removal.
+
 The default `managerKey` namespaces the in-process `FileLockManager` per absolute file path, so two `jsonStore` calls on the same file share lock state automatically.
 
 ## Common patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {
@@ -99,7 +99,7 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
     "prepack": "node scripts/prepack-build.mjs",
@@ -115,9 +115,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.19",
-    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/coverage-v8": "4.1.6",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.4"
+    "vitest": "^4.1.6"
   },
   "engines": {
     "node": ">=20.11"

package/dist/archive-utils.d.ts

@@ -1,3 +0,0 @@
-export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
-export declare function fileExists(filePath: string): Promise<boolean>;
-//# sourceMappingURL=archive-utils.d.ts.map

package/dist/archive-utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-utils.d.ts","sourceRoot":"","sources":["../src/archive-utils.ts"],"names":[],"mappings":"AAEA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE"}

package/dist/archive-utils.js

@@ -1,26 +0,0 @@
-import fs from "node:fs/promises";
-export async function withTimeout(promise, timeoutMs, label) {
-    let timeoutId;
-    try {
-        return await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-                timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-            }),
-        ]);
-    }
-    finally {
-        if (timeoutId) {
-            clearTimeout(timeoutId);
-        }
-    }
-}
-export async function fileExists(filePath) {
-    try {
-        await fs.stat(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/boundary-file-read.d.ts

@@ -1,44 +0,0 @@
-import fs from "node:fs";
-import type { PathAliasPolicy } from "./path-alias-guards.js";
-import { type SafeOpenSyncAllowedType, type SafeOpenSyncFailureReason } from "./safe-open-sync.js";
-type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
-export type BoundaryFileOpenFailureReason = SafeOpenSyncFailureReason | "validation";
-export type BoundaryFileOpenResult = {
-    ok: true;
-    path: string;
-    fd: number;
-    stat: fs.Stats;
-    rootRealPath: string;
-} | {
-    ok: false;
-    reason: BoundaryFileOpenFailureReason;
-    error?: unknown;
-};
-export type BoundaryFileOpenFailure = Extract<BoundaryFileOpenResult, {
-    ok: false;
-}>;
-export type OpenBoundaryFileSyncParams = {
-    absolutePath: string;
-    rootPath: string;
-    boundaryLabel: string;
-    rootRealPath?: string;
-    maxBytes?: number;
-    rejectHardlinks?: boolean;
-    allowedType?: SafeOpenSyncAllowedType;
-    skipLexicalRootCheck?: boolean;
-    ioFs?: BoundaryReadFs;
-};
-export type OpenBoundaryFileParams = OpenBoundaryFileSyncParams & {
-    aliasPolicy?: PathAliasPolicy;
-};
-export declare function canUseBoundaryFileOpen(ioFs: typeof fs): boolean;
-export declare function openBoundaryFileSync(params: OpenBoundaryFileSyncParams): BoundaryFileOpenResult;
-export declare function matchBoundaryFileOpenFailure<T>(failure: BoundaryFileOpenFailure, handlers: {
-    path?: (failure: BoundaryFileOpenFailure) => T;
-    validation?: (failure: BoundaryFileOpenFailure) => T;
-    io?: (failure: BoundaryFileOpenFailure) => T;
-    fallback: (failure: BoundaryFileOpenFailure) => T;
-}): T;
-export declare function openBoundaryFile(params: OpenBoundaryFileParams): Promise<BoundaryFileOpenResult>;
-export {};
-//# sourceMappingURL=boundary-file-read.d.ts.map

package/dist/boundary-file-read.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"boundary-file-read.d.ts","sourceRoot":"","sources":["../src/boundary-file-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,yBAAyB,GAAG,YAAY,CAAC;AAErF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAErF,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,GAAG;IAChE,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW/D;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,sBAAsB,CAuB/F;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,OAAO,EAAE,uBAAuB,EAChC,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IACrD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;CACnD,GACA,CAAC,CAUH;AAoDD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,sBAAsB,CAAC,CAsBjC"}