@openclaw/fs-safe 0.4.1 → 0.4.2

package/dist/regular-file.js

@@ -1,6 +1,7 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
@@ -19,44 +20,6 @@ function resolveRegularFileReadFlags() {
             ? fsSync.constants.O_NOFOLLOW
             : 0));
 }
-async function readFileHandleBounded(params) {
-    if (params.maxBytes === undefined) {
-        return await params.handle.readFile();
-    }
-    const chunks = [];
-    const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, Math.max(1, params.maxBytes + 1)));
-    let total = 0;
-    while (true) {
-        const { bytesRead } = await params.handle.read(scratch, 0, scratch.length, null);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total += bytesRead;
-        if (total > params.maxBytes) {
-            throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
-        }
-        chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
-    }
-}
-function readFileDescriptorBounded(params) {
-    if (params.maxBytes === undefined) {
-        return fsSync.readFileSync(params.fd);
-    }
-    const chunks = [];
-    const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, Math.max(1, params.maxBytes + 1)));
-    let total = 0;
-    while (true) {
-        const bytesRead = fsSync.readSync(params.fd, scratch, 0, scratch.length, null);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total += bytesRead;
-        if (total > params.maxBytes) {
-            throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
-        }
-        chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
-    }
-}
 export async function statRegularFile(filePath) {
     let stat;
     try {
@@ -96,7 +59,7 @@ export async function readRegularFile(params) {
         throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
     }
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
+        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${result.stat.size})`);
     }
     let handle;
     try {
@@ -127,15 +90,13 @@ export async function readRegularFile(params) {
             preOpenStat: result.stat,
         });
         if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-            throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
+            throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${stat.size})`);
         }
         // With a byte cap, avoid readFile(): a raced file growth would allocate
         // the oversized content before the post-read check could reject it.
-        const buffer = await readFileHandleBounded({
-            handle,
-            filePath: params.filePath,
-            maxBytes: params.maxBytes,
-        });
+        const buffer = params.maxBytes === undefined
+            ? await handle.readFile()
+            : await readFileHandleBounded(handle, params.maxBytes);
         return { buffer, stat };
     }
     finally {
@@ -160,15 +121,13 @@ function readOpenedRegularFileSync(params) {
         preOpenStat: params.preOpenStat,
     });
     if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-        throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
+        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${stat.size})`);
     }
     // Keep capped sync reads incremental for the same reason as async reads:
     // readFileSync(fd) would buffer a raced oversized file before throwing.
-    const buffer = readFileDescriptorBounded({
-        fd: params.fd,
-        filePath: params.filePath,
-        maxBytes: params.maxBytes,
-    });
+    const buffer = params.maxBytes === undefined
+        ? fsSync.readFileSync(params.fd)
+        : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
     return { buffer, stat };
 }
 export function readRegularFileSync(params) {
@@ -178,7 +137,7 @@ export function readRegularFileSync(params) {
         throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
     }
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw new Error(`File exceeds ${params.maxBytes} bytes: ${params.filePath}`);
+        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${result.stat.size})`);
     }
     const fd = fsSync.openSync(params.filePath, resolveRegularFileReadFlags());
     try {

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

@@ -1 +1 @@
-{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAID,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB9E;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAQtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAID,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB9E;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAQtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}

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

@@ -1 +1 @@
-{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAMA,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;;CAS3B,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CA+BnF;AAmkBD,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6B7E"}
+{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAMA,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CA+BnF;AAmkBD,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6B7E"}

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;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAkIF,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,CAcpB;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"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAWA,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;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAqIF,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,CAcpB;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,6 +1,7 @@
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
@@ -100,7 +101,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         };
     }
     try {
-        const raw = fs.readFileSync(opened.fd, "utf8");
+        const raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
         const secret = raw.trim();
         if (!secret) {
             return {
@@ -115,7 +116,9 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         const normalized = normalizeSecretReadError(error);
         return {
             ok: false,
-            code: "invalid-path",
+            code: error instanceof FsSafeError && error.code === "too-large"
+                ? "too-large"
+                : "invalid-path",
             error: normalized,
             message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };

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;AAWrC,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;AAuKF,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;AAYrC,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;AA0KF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}

package/dist/secure-file.js

@@ -1,6 +1,7 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { readFileHandleBounded } from "./bounded-read.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
@@ -129,14 +130,15 @@ async function assertSecurePermissions(options, stat, realPath) {
     }
     return permissions;
 }
-async function readHandleWithTimeout(handle, timeoutMs) {
+async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
+    const read = () => maxBytes === undefined ? handle.readFile() : readFileHandleBounded(handle, maxBytes);
     if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-        return await handle.readFile();
+        return await read();
     }
     let timeout;
     try {
         return await Promise.race([
-            handle.readFile(),
+            read(),
             new Promise((_resolve, reject) => {
                 timeout = setTimeout(() => {
                     void handle.close().catch(() => undefined);
@@ -155,10 +157,7 @@ export async function readSecureFile(options) {
     try {
         await assertTrustedDirs(options, opened.realPath);
         const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath);
-        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs);
-        if (options.io?.maxBytes !== undefined && buffer.byteLength > options.io.maxBytes) {
-            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
-        }
+        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, options.io?.maxBytes);
         return { buffer, realPath: opened.realPath, stat: opened.pathStat, permissions };
     }
     finally {

package/dist/sidecar-lock.d.ts

@@ -5,7 +5,10 @@ export type SidecarLockRetryOptions = {
     maxTimeout?: number;
     randomize?: boolean;
 };
-export type SidecarLockStaleRecovery = "fail-closed" | "remove-if-unchanged";
+export type SidecarLockStaleRecovery = "fail-closed"
+/** @deprecated Stale locks now always fail closed. */
+ | "remove-if-unchanged";
+/** @deprecated Stale-removal callbacks are retained for source compatibility but are not invoked. */
 export type SidecarLockStaleSnapshot = {
     lockPath: string;
     normalizedTargetPath: string;
@@ -29,6 +32,7 @@ export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>>
         nowMs: number;
         heldByThisProcess: boolean;
     }) => boolean | Promise<boolean>;
+    /** @deprecated Stale locks now always fail closed; this callback is not invoked. */
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
     metadata?: Record<string, unknown>;
 };

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,aAAa,GAAG,qBAAqB,CAAC;AAE7E,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CACtB,QAAQ,EAAE,wBAAwB,KAC/B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAiPF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAW3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAiIL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock.js

@@ -67,36 +67,6 @@ async function lockSnapshotStillPresent(lockPath, observed) {
     const current = await readLockSnapshot(lockPath);
     return !!current && !!observed && snapshotMatches(current, observed);
 }
-async function removeStaleLockIfAllowed(params) {
-    if (!params.shouldRemoveStaleLock) {
-        return "not-approved";
-    }
-    if (params.snapshot.raw === undefined) {
-        return "not-approved";
-    }
-    if (!(await params.shouldRemoveStaleLock({
-        lockPath: params.lockPath,
-        normalizedTargetPath: params.normalizedTargetPath,
-        raw: params.snapshot.raw,
-        payload: params.snapshot.payload,
-    }))) {
-        return "not-approved";
-    }
-    const current = await readLockSnapshot(params.lockPath);
-    if (!current || !snapshotMatches(current, params.snapshot)) {
-        return "changed";
-    }
-    try {
-        await fs.rm(params.lockPath, { force: true });
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            return "changed";
-        }
-        return "not-approved";
-    }
-    return "removed";
-}
 function snapshotMatchesSync(lockPath, observed) {
     try {
         const stat = fsSync.lstatSync(lockPath);
@@ -281,18 +251,9 @@ export function createSidecarLockManager(key) {
                     if (!(await lockSnapshotStillPresent(lockPath, snapshot))) {
                         continue;
                     }
-                    const staleRecovery = options.staleRecovery ?? "fail-closed";
-                    if (staleRecovery === "remove-if-unchanged") {
-                        const removal = await removeStaleLockIfAllowed({
-                            lockPath,
-                            normalizedTargetPath,
-                            snapshot,
-                            shouldRemoveStaleLock: options.shouldRemoveStaleLock,
-                        });
-                        if (removal === "removed" || removal === "changed") {
-                            continue;
-                        }
-                    }
+                    // A pathname recheck followed by unlink is not atomic: a fresh lock
+                    // can replace the observed file in between. Legacy recovery inputs
+                    // remain accepted, but third-party stale locks always fail closed.
                     throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
                         code: "file_lock_stale",
                         lockPath,

package/docs/advanced.md

@@ -55,6 +55,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 
 | Export | Page | Notes |
 |---|---|---|
+| `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level no-follow open routed through the root-file path. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
@@ -62,6 +63,25 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
+The bounded descriptor helpers start at the descriptor's current offset and
+leave ownership with the caller. They are intended for the second half of a
+safe read: first open and validate the path using the boundary appropriate to
+your application, then read the already-pinned descriptor without trusting a
+possibly stale size check.
+
+```ts
+import fs from "node:fs";
+import { readFileDescriptorBoundedSync } from "@openclaw/fs-safe/advanced";
+
+const fd = fs.openSync(filePath, "r");
+try {
+  const bytes = readFileDescriptorBoundedSync(fd, 256 * 1024);
+  consume(bytes);
+} finally {
+  fs.closeSync(fd);
+}
+```
+
 ### Local roots and file URLs
 
 | Export | Page | Notes |

package/docs/config.md

@@ -56,7 +56,7 @@ Return the effective configuration: programmatic overrides win, then env vars, t
 function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
 
 type FsSafeLockConfig = {
-  staleRecovery: "fail-closed" | "remove-if-unchanged";
+  staleRecovery: "fail-closed" | "remove-if-unchanged"; // legacy value also fails closed
   staleMs?: number;
   timeoutMs?: number;
   retry?: FileLockRetryOptions;
@@ -65,7 +65,7 @@ type FsSafeLockConfig = {
 
 Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
 
-`staleRecovery` defaults to `"fail-closed"`. `"remove-if-unchanged"` is available for callers that also pass `shouldRemoveStaleLock`; fs-safe re-reads the observed sidecar and removes it only when the raw content and file identity still match.
+`staleRecovery` defaults to `"fail-closed"`. The deprecated `"remove-if-unchanged"` value remains accepted for source and configuration compatibility, but behaves as `"fail-closed"`. fs-safe never removes a stale third-party lock during acquisition because a pathname recheck followed by unlink cannot prevent deleting a replacement lock.
 
 ## `getFsSafeLockConfig()`
 

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, fail-closed stale-lock handling, and opt-in caller-approved stale removal. |
+| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
 | [`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" | "remove-if-unchanged";
+  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // legacy value also fails closed
   managerKey?: string;  // default `fs-safe.json-store:<filePath>`
 };
 
@@ -141,7 +141,7 @@ 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.
+JSON store locks always fail closed on stale sidecars. The deprecated `staleRecovery: "remove-if-unchanged"` value remains accepted for compatibility, but it behaves as `"fail-closed"` and never removes the lock.
 
 The default `managerKey` namespaces the in-process `FileLockManager` per absolute file path, so two `jsonStore` calls on the same file share lock state automatically.
 

package/docs/json.md

@@ -40,15 +40,22 @@ Use `readJson` when missing-or-malformed is a programmer error you want to surfa
 
 ## Reading
 
-### `readJson<T>(filePath)`
+### `readJson<T>(filePath, options?)`
 
 Async strict reader. Throws `JsonFileReadError` on missing or invalid input. The cast is unchecked — validate the shape with your own schema (zod, valibot, …) if it came from an untrusted source.
 
 ```ts
 const manifest = await readJson<Manifest>("./manifest.json");
+const smallManifest = await readJson<Manifest>("./manifest.json", {
+  maxBytes: 256 * 1024,
+});
 ```
 
-### `readJsonIfExists<T>(filePath)`
+All standalone readers accept `{ maxBytes?: number }`. When set, the read is
+incremental and consumes no more than `maxBytes + 1` bytes before rejecting, so
+file growth after the initial stat cannot cause an unbounded allocation.
+
+### `readJsonIfExists<T>(filePath, options?)`
 
 Async semi-lenient reader. Returns `null` if the file is missing; throws `JsonFileReadError` if the file exists but cannot be parsed.
 
@@ -56,7 +63,7 @@ Async semi-lenient reader. Returns `null` if the file is missing; throws `JsonFi
 const cache = (await readJsonIfExists<Cache>("./cache.json")) ?? freshCache();
 ```
 
-### `tryReadJson<T>(filePath)`
+### `tryReadJson<T>(filePath, options?)`
 
 Async lenient reader. Returns `null` for any failure (missing, unreadable, invalid). The "no fuss" sibling.
 
@@ -64,11 +71,11 @@ Async lenient reader. Returns `null` for any failure (missing, unreadable, inval
 const optional = (await tryReadJson<Settings>("./settings.json")) ?? defaults;
 ```
 
-### `readJsonSync<T>(filePath)`
+### `readJsonSync<T>(filePath, options?)`
 
 Synchronous strict reader. Throws `JsonFileReadError` on missing or invalid input, matching the async `readJson` contract.
 
-### `tryReadJsonSync<T>(pathname)`
+### `tryReadJsonSync<T>(pathname, options?)`
 
 Synchronous, generic, lenient. Returns `T | null`. Useful in boot paths where you want a typed result without async.
 
@@ -83,6 +90,7 @@ const result = readRootJsonObjectSync({
   rootDir: "/safe/workspace",
   relativePath: "plugin/openclaw.plugin.json",
   boundaryLabel: "plugin manifest",
+  maxBytes: 256 * 1024,
 });
 
 if (!result.ok) {

package/docs/regular-file.md

@@ -32,14 +32,14 @@ type RegularFileStatResult =
   | { missing: false; stat: Stats };
 ```
 
-A non-regular file (directory, FIFO, …) returns `{ missing: false }` with a `stat` whose `isFile()` is false — the helper does not throw, you decide what to do.
+A non-regular file (directory, FIFO, symlink, …) throws. Missing paths return
+`{ missing: true }`; existing regular files return `{ missing: false, stat }`.
 
 ```ts
 import { statRegularFile } from "@openclaw/fs-safe/advanced";
 
 const r = await statRegularFile("/var/log/app.log");
 if (r.missing) return;
-if (!r.stat.isFile()) throw new Error("expected a regular file");
 console.log(`size=${r.stat.size}`);
 ```
 
@@ -60,19 +60,11 @@ const result = await readRegularFile({
   filePath: "/var/log/app.log",
   maxBytes: 4 * 1024 * 1024,
 });
-if (result.missing) return null;
-if (!result.regular) throw new Error("not a regular file");
 processLog(result.buffer);
 ```
 
-Result shape:
-
-```ts
-type Result =
-  | { missing: true }
-  | { missing: false; regular: false; stat: Stats }
-  | { missing: false; regular: true; stat: Stats; buffer: Buffer };
-```
+The result is `{ buffer, stat }`. Missing files preserve the normal `ENOENT`
+shape; non-regular targets throw.
 
 Throws `FsSafeError` with code `too-large` if the file exceeds `maxBytes`. Other I/O errors propagate as `NodeJS.ErrnoException`.
 
@@ -91,9 +83,8 @@ import { appendRegularFile } from "@openclaw/fs-safe/advanced";
 
 await appendRegularFile({
   filePath: "/var/log/app.log",
-  data: `[${new Date().toISOString()}] ${line}\n`,
+  content: `[${new Date().toISOString()}] ${line}\n`,
   encoding: "utf8",
-  prependNewlineIfNeeded: true,
 });
 ```
 
@@ -102,28 +93,30 @@ await appendRegularFile({
 ```ts
 type AppendRegularFileOptions = {
   filePath: string;
-  data: string | Buffer;
-  encoding?: BufferEncoding;             // default utf8 when data is string
-  prependNewlineIfNeeded?: boolean;      // insert "\n" if file does not end with one
-  flags?: number;                         // raw open flags; default O_WRONLY | O_APPEND
-  mode?: number;                          // default 0o644 if file is created
+  content: string | Uint8Array;
+  encoding?: BufferEncoding; // default utf8 when content is string
+  maxFileBytes?: number;     // skip if the resulting file would exceed this
+  mode?: number;             // default 0o600
+  rejectSymlinkParents?: boolean;
 };
 ```
 
-`prependNewlineIfNeeded` reads the trailing byte of the existing file and prepends a `\n` to your data if it isn't already present. Useful for log appenders that want to preserve line boundaries even when callers forget the newline.
+The helper refuses symlink and hardlinked final targets. With
+`rejectSymlinkParents: true`, it also rejects symlinked ancestor directories.
 
 ### `appendRegularFileSync(options)`
 
 Synchronous. Same options.
 
-### `resolveRegularFileAppendFlags(append, truncateExisting)`
+### `resolveRegularFileAppendFlags()`
 
-Helper that returns the right open-flag bitmask for combinations of "append" / "truncate". Use it when you're building your own open path and want to match the append helpers' behavior:
+Helper that returns the append helpers' `O_WRONLY | O_APPEND | O_CREAT` flags,
+plus `O_NOFOLLOW` where the platform provides it:
 
 ```ts
 import { resolveRegularFileAppendFlags } from "@openclaw/fs-safe/advanced";
 
-const flags = resolveRegularFileAppendFlags(true, false); // O_WRONLY | O_APPEND | O_CREAT
+const flags = resolveRegularFileAppendFlags();
 ```
 
 ## Difference from `Root` methods
@@ -131,9 +124,9 @@ const flags = resolveRegularFileAppendFlags(true, false); // O_WRONLY | O_APPEND
 | `regular-file` | `Root` |
 |---|---|
 | Absolute paths only. | Relative to the root. |
-| No identity check post-open. | Identity check on every read/write. |
+| Verifies path and descriptor identity around reads. | Enforces the same checks within a trusted root. |
 | Caller must be confident the path is trusted. | Boundary check is automatic. |
-| Returns explicit `{missing, regular}` shape. | Throws `FsSafeError` with `code`. |
+| Stat reports missing explicitly; reads throw on missing/non-file. | Throws `FsSafeError` with `code`. |
 
 If your call site already trusts the path (it came from your own config, not a caller), `regular-file` is a thinner, faster surface. If the path is caller-influenced, prefer `root()` or wrap in [`pathScope()`](path-scope.md).
 
@@ -142,13 +135,15 @@ If your call site already trusts the path (it came from your own config, not a c
 ### Read a config file if it's there, else seed
 
 ```ts
-const r = await readRegularFile({ filePath: "/etc/app/config.json", maxBytes: 64 * 1024 });
-if (r.missing) {
+const info = await statRegularFile("/etc/app/config.json");
+if (info.missing) {
   await writeJson("/etc/app/config.json", defaultConfig);
-} else if (r.regular) {
-  applyConfig(JSON.parse(r.buffer.toString("utf8")));
 } else {
-  throw new Error("/etc/app/config.json is not a regular file");
+  const r = await readRegularFile({
+    filePath: "/etc/app/config.json",
+    maxBytes: 64 * 1024,
+  });
+  applyConfig(JSON.parse(r.buffer.toString("utf8")));
 }
 ```
 
@@ -156,7 +151,7 @@ if (r.missing) {
 
 ```ts
 const r = await statRegularFile(p);
-if (r.missing || !r.stat.isFile()) return false;
+if (r.missing) return false;
 return true;
 ```
 
@@ -164,7 +159,6 @@ return true;
 
 ```ts
 const r = await readRegularFile({ filePath: logPath, maxBytes: 1 * 1024 * 1024 });
-if (r.missing || !r.regular) return [];
 return r.buffer.toString("utf8").split("\n").slice(-100);
 ```