@openclaw/fs-safe 0.2.4 → 0.2.6

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-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-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/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/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/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/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/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/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.