@openclaw/fs-safe 0.2.5 → 0.2.7

package/dist/secret-file.d.ts

@@ -4,6 +4,7 @@ export declare const PRIVATE_SECRET_FILE_MODE = 384;
 export type SecretFileReadOptions = {
     maxBytes?: number;
     rejectSymlink?: boolean;
+    rejectHardlinks?: boolean;
 };
 export declare function readSecretFileSync(filePath: string, label: string, options?: SecretFileReadOptions): string;
 export declare function tryReadSecretFileSync(filePath: string | undefined, label: string, options?: SecretFileReadOptions): string | undefined;

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;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"}

package/dist/secret-file.js

@@ -1,18 +1,22 @@
-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;
 function normalizeSecretReadError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
+function secretPathErrorCode(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
 function resolveUserPath(input) {
     return resolveHomeRelativePath(input);
 }
@@ -31,7 +35,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         const normalized = normalizeSecretReadError(error);
         return {
             ok: false,
-            code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+            code: secretPathErrorCode(error),
             error: normalized,
             message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };
@@ -45,7 +49,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
                 const normalized = normalizeSecretReadError(error);
                 return {
                     ok: false,
-                    code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+                    code: secretPathErrorCode(error),
                     error: normalized,
                     message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
                 };
@@ -66,6 +70,13 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
             message: `${label} file at ${resolvedPath} must be a regular file.`,
         };
     }
+    if (options.rejectHardlinks !== false && previewStat.nlink > 1) {
+        return {
+            ok: false,
+            code: "hardlink",
+            message: `${label} file at ${resolvedPath} must not be hardlinked.`,
+        };
+    }
     if (previewStat.size > maxBytes) {
         return {
             ok: false,
@@ -76,6 +87,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
     const opened = openPinnedFileSync({
         filePath: resolvedPath,
         rejectPathSymlink: options.rejectSymlink,
+        rejectHardlinks: options.rejectHardlinks !== false,
         maxBytes,
     });
     if (!opened.ok) {
@@ -126,17 +138,28 @@ export function tryReadSecretFileSync(filePath, label, options = {}) {
         return undefined;
     }
     const result = readSecretFileOutcomeSync(filePath, label, options);
-    return result.ok ? result.secret : undefined;
+    if (result.ok) {
+        return result.secret;
+    }
+    if (result.code === "not-found") {
+        return undefined;
+    }
+    throw new FsSafeError(result.code, result.message, {
+        cause: result.error,
+    });
+}
+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 +174,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 +243,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 +261,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 +281,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/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;AA2OF,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

@@ -34,8 +34,11 @@ async function readLockSnapshot(lockPath) {
             return { raw, payload: null, stat };
         }
     }
-    catch {
-        return null;
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
     }
 }
 function snapshotMatches(current, observed) {
@@ -86,7 +89,10 @@ async function removeStaleLockIfAllowed(params) {
     try {
         await fs.rm(params.lockPath, { force: true });
     }
-    catch {
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return "changed";
+        }
         return "not-approved";
     }
     return "removed";

package/dist/symlink-parents.js

@@ -1,12 +1,12 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isNotFoundPathError } from "./path.js";
+import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 function resolvePathWalk(params) {
     const root = path.resolve(params.rootDir);
     const target = path.resolve(params.targetPath);
     const relative = path.relative(root, target);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {
             return null;
         }

package/dist/temp-target.js

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

package/docs/secret-file.md

@@ -36,7 +36,7 @@ The 16 KiB cap is intentionally aggressive — credentials should be small. If y
 
 ### `tryReadSecretFileSync(filePath, label, options?)`
 
-The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing, empty, unreadable, too large, or rejected by the validation checks.
+The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing or blank. Validation failures, unreadable files, oversized files, symlinks, and hardlinks throw `FsSafeError` so callers fail closed on suspicious credential state.
 
 ```ts
 import { tryReadSecretFileSync } from "@openclaw/fs-safe/secret";
@@ -63,10 +63,11 @@ const token = readSecretFileSync("/var/lib/app/auth.token");
 type SecretFileReadOptions = {
   maxBytes?: number;         // default DEFAULT_SECRET_FILE_MAX_BYTES (16 KiB)
   rejectSymlink?: boolean;
+  rejectHardlinks?: boolean; // default true
 };
 ```
 
-The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read.
+The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read. Hardlinks are rejected by default so another in-tree name cannot alias the credential; pass `rejectHardlinks: false` only when you explicitly trust that layout.
 
 ## Writing
 

package/docs/timing.md

@@ -102,7 +102,7 @@ await extractArchive({
 });
 ```
 
-`extractArchive` already takes `timeoutMs` and uses `withTimeout` internally — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
+`extractArchive` already takes `timeoutMs` and carries its own abort signal/deadline checks — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
 
 ### Disable in tests
 

package/package.json

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