@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/root-write-verification.js

@@ -0,0 +1,91 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { resolveOpenedFileRealPathForFd } from "./opened-realpath.js";
+import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+export async function verifyAtomicWriteResult(params) {
+    let needsPathOpen = false;
+    const assertFile = (stat) => {
+        if (stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", "symlink not allowed");
+        }
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        if (!sameFileIdentity(stat, params.expectedIdentity)) {
+            throw new FsSafeError("path-mismatch", "path changed during write");
+        }
+        if (stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+    };
+    const assertPath = (stat) => {
+        assertFile(stat);
+        needsPathOpen ||= process.platform === "win32" && (stat.dev === 0n || stat.ino === 0n);
+    };
+    const assertDescriptor = (fd = params.fd) => {
+        const stat = fsSync.fstatSync(fd, { bigint: true });
+        // Only Windows pathname stats may have unknown identity; fd stats must match exactly.
+        if (params.expectedIdentity.dev !== stat.dev || params.expectedIdentity.ino !== stat.ino) {
+            throw new FsSafeError("path-mismatch", "descriptor changed during write");
+        }
+        assertFile(stat);
+        return stat;
+    };
+    try {
+        // This descriptor remains owned by the writer, even when final mode forbids opens.
+        const stat = assertDescriptor();
+        assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+        const realPath = await resolveOpenedFileRealPathForFd(params.fd, stat, params.targetPath);
+        assertPath(await fs.stat(realPath, { bigint: true }));
+        if (!isPathInside(params.root.rootWithSep, realPath)) {
+            throw outsideWorkspaceError();
+        }
+        await assertAsyncDirectoryGuard(params.parentGuard);
+        await assertRootIdentityCurrent(params.root);
+        // Recheck after canonical resolution and directory checks, including late links.
+        assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+        assertDescriptor();
+        if (needsPathOpen) {
+            // A retained fd cannot prove that an opaque Windows pathname still names it.
+            // Reopen only for publication verification: the writer's exact identity is
+            // independent proof unavailable to ordinary readers. Never read any bytes.
+            assertNoUnsafeDeviceReadPath(params.targetPath);
+            const opened = await fs.open(params.targetPath, resolveReadOpenFlags()).catch((error) => {
+                if (isSymlinkOpenError(error)) {
+                    throw new FsSafeError("symlink", "symlink open blocked", { cause: error });
+                }
+                if (hasNodeErrorCode(error, "EISDIR")) {
+                    throw new FsSafeError("not-file", "not a file");
+                }
+                throw error;
+            });
+            try {
+                const reopenedStat = assertDescriptor(opened.fd);
+                assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+                const reopenedPath = await resolveOpenedFileRealPathForFd(opened.fd, reopenedStat, params.targetPath);
+                assertPath(await fs.stat(reopenedPath, { bigint: true }));
+                if (!isPathInside(params.root.rootWithSep, reopenedPath)) {
+                    throw outsideWorkspaceError();
+                }
+                await assertAsyncDirectoryGuard(params.parentGuard);
+                await assertRootIdentityCurrent(params.root);
+                assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+                assertDescriptor(opened.fd);
+            }
+            finally {
+                await opened.close().catch(() => undefined);
+            }
+        }
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            throw fileNotFoundError();
+        throw error;
+    }
+}

package/dist/secret-file.d.ts

@@ -1,11 +1,6 @@
-export declare const DEFAULT_SECRET_FILE_MAX_BYTES: number;
+import { type SecretFileReadOptions } from "./secret-read-policy.js";
 export declare const PRIVATE_SECRET_DIR_MODE = 448;
 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;
 type SecretFileWriteParams = {

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAaA,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;AAyIF,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,KAAK,qBAAqB,GAAG;IAC3B,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,CAAC;AAkEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAwER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AAkID,KAAK,qBAAqB,GAAG;IAC3B,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,CAAC;AAkEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}

package/dist/secret-file.js

@@ -3,161 +3,91 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
+import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.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);
-}
-function readSecretFileOutcomeSync(filePath, label, options = {}) {
-    const trimmedPath = filePath.trim();
-    const resolvedPath = resolveUserPath(trimmedPath);
+export function readSecretFileSync(filePath, label, options = {}) {
+    const resolvedPath = resolveHomeRelativePath(filePath.trim());
     if (!resolvedPath) {
-        return { ok: false, code: "invalid-path", message: `${label} file path is empty.` };
+        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
+    });
+    function inspectInput(symlinkMessage) {
+        const stat = options.rejectSymlink
+            ? fs.lstatSync(resolvedPath, { bigint: true })
+            : fs.statSync(resolvedPath, { bigint: true });
+        if (options.rejectSymlink && stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", symlinkMessage);
+        }
+        return stat;
     }
-    const maxBytes = options.maxBytes ?? DEFAULT_SECRET_FILE_MAX_BYTES;
     let previewStat;
     try {
-        previewStat = fs.lstatSync(resolvedPath);
+        previewStat = inspectFileIdentitySync(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {
-        const normalized = normalizeSecretReadError(error);
-        return {
-            ok: false,
-            code: secretPathErrorCode(error),
-            error: normalized,
-            message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
-        };
-    }
-    if (previewStat.isSymbolicLink()) {
-        if (!options.rejectSymlink) {
-            try {
-                previewStat = fs.statSync(resolvedPath);
-            }
-            catch (error) {
-                const normalized = normalizeSecretReadError(error);
-                return {
-                    ok: false,
-                    code: secretPathErrorCode(error),
-                    error: normalized,
-                    message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
-                };
-            }
-        }
-        else {
-            return {
-                ok: false,
-                code: "symlink",
-                message: `${label} file at ${resolvedPath} must not be a symlink.`,
-            };
-        }
-    }
-    if (!previewStat.isFile()) {
-        return {
-            ok: false,
-            code: "not-file",
-            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,
-            code: "too-large",
-            message: `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.`,
-        };
+        throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
     }
+    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, options.rejectHardlinks !== false);
     const opened = openPinnedFileSync({
         filePath: resolvedPath,
         rejectPathSymlink: options.rejectSymlink,
         rejectHardlinks: options.rejectHardlinks !== false,
     });
     if (!opened.ok) {
-        const error = normalizeSecretReadError(opened.reason === "validation" ? new Error("security validation failed") : opened.error);
-        return {
-            ok: false,
-            code: opened.reason === "path" ? "not-found" : "path-mismatch",
-            error,
-            message: `Failed to read ${label} file at ${resolvedPath}: ${String(error)}`,
-        };
+        throw secretReadError(opened.reason === "path" ? "not-found" : "path-mismatch", "read", label, resolvedPath, opened.reason === "validation" ? new Error("security validation failed") : opened.error);
     }
+    let raw;
     try {
-        if (!sameFileIdentity(previewStat, opened.stat)) {
-            const error = new FsSafeError("path-mismatch", "security validation failed");
-            return {
-                ok: false,
-                code: "path-mismatch",
-                error,
-                message: `Failed to read ${label} file at ${resolvedPath}: ${String(error)}`,
-            };
-        }
-        const raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
-        const secret = raw.trim();
-        if (!secret) {
-            return {
-                ok: false,
-                code: "invalid-path",
-                message: `${label} file at ${resolvedPath} is empty.`,
-            };
-        }
-        return { ok: true, secret };
+        const openedIdentity = inspectFileIdentitySync(() => {
+            const stat = fs.fstatSync(opened.fd, { bigint: true });
+            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+                throw new FsSafeError("path-mismatch", "security validation failed");
+            }
+            return stat;
+        }, previewStat);
+        inspectFileIdentitySync(() => {
+            const stat = fs.lstatSync(opened.path, { bigint: true });
+            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+                throw new FsSafeError("path-mismatch", "security validation failed");
+            }
+            return stat;
+        }, openedIdentity);
+        inspectFileIdentitySync(() => inspectInput("secret path became a symlink"), openedIdentity);
+        raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
     }
     catch (error) {
-        const normalized = normalizeSecretReadError(error);
-        return {
-            ok: false,
-            code: error instanceof FsSafeError ? error.code : "read-failed",
-            error: normalized,
-            message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
-        };
+        throw secretReadError(error instanceof FsSafeError ? error.code : "read-failed", "read", label, resolvedPath, error);
     }
     finally {
         fs.closeSync(opened.fd);
     }
-}
-export function readSecretFileSync(filePath, label, options = {}) {
-    const result = readSecretFileOutcomeSync(filePath, label, options);
-    if (result.ok) {
-        return result.secret;
-    }
-    throw new FsSafeError(result.code, result.message, {
-        cause: result.error,
-    });
+    return trimSecretFileContent(raw, label, resolvedPath);
 }
 export function tryReadSecretFileSync(filePath, label, options = {}) {
     if (!filePath?.trim()) {
         return undefined;
     }
-    const result = readSecretFileOutcomeSync(filePath, label, options);
-    if (result.ok) {
-        return result.secret;
+    try {
+        return readSecretFileSync(filePath, label, options);
     }
-    if (result.code === "not-found") {
-        return undefined;
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "not-found")
+            return undefined;
+        throw error;
     }
-    throw new FsSafeError(result.code, result.message, {
-        cause: result.error,
-    });
 }
 function isRelativeEscape(relativePath) {
     return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
@@ -186,8 +116,7 @@ async function enforcePrivatePathMode(resolvedPath, expectedMode, kind) {
     }
 }
 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);
+    const handle = await fsp.open(resolvedPath, resolveReadOpenFlags());
     try {
         const openedStat = await handle.stat();
         if (!openedStat.isFile() || !sameFileIdentity(openedStat, expectedIdentity)) {

package/dist/secret-read-async.d.ts

@@ -1,4 +1,4 @@
-import { type SecretFileReadOptions } from "./secret-file.js";
+import { type SecretFileReadOptions } from "./secret-read-policy.js";
 export declare function readSecretFile(filePath: string, label: string, options?: SecretFileReadOptions): Promise<string>;
 export declare function tryReadSecretFile(filePath: string | undefined, label: string, options?: SecretFileReadOptions): Promise<string | undefined>;
 //# sourceMappingURL=secret-read-async.d.ts.map

package/dist/secret-read-async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AA0F1B,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B"}
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA8DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/secret-read-async.js

@@ -1,99 +1,78 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
-import { DEFAULT_SECRET_FILE_MAX_BYTES, } from "./secret-file.js";
-function pathErrorCode(error) {
-    const code = error.code;
-    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
-}
-async function readSecretFileOutcome(filePath, label, options) {
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+export async function readSecretFile(filePath, label, options = {}) {
     const resolvedPath = resolveHomeRelativePath(filePath.trim());
     if (!resolvedPath) {
-        return { ok: false, code: "invalid-path", message: `${label} file path is empty.` };
+        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
+    });
+    async function inspectInput(symlinkMessage) {
+        const stat = options.rejectSymlink
+            ? await fs.lstat(resolvedPath, { bigint: true })
+            : await fs.stat(resolvedPath, { bigint: true });
+        if (options.rejectSymlink && stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", symlinkMessage);
+        }
+        return stat;
     }
-    const maxBytes = options.maxBytes ?? DEFAULT_SECRET_FILE_MAX_BYTES;
     let previewStat;
     try {
-        previewStat = await fs.lstat(resolvedPath);
-        if (previewStat.isSymbolicLink()) {
-            if (options.rejectSymlink) {
-                return { ok: false, code: "symlink", message: `${label} file at ${resolvedPath} must not be a symlink.` };
-            }
-            previewStat = await fs.stat(resolvedPath);
-        }
+        previewStat = await inspectFileIdentity(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {
-        const normalized = error instanceof Error ? error : new Error(String(error));
-        return {
-            ok: false,
-            code: pathErrorCode(error),
-            error: normalized,
-            message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
-        };
-    }
-    if (!previewStat.isFile()) {
-        return { ok: false, code: "not-file", 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, code: "too-large", message: `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.` };
+        throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
     }
+    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, options.rejectHardlinks !== false);
     let handle;
+    let raw;
     try {
         const realPath = await fs.realpath(resolvedPath);
-        const noFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
-            ? fsSync.constants.O_NOFOLLOW
-            : 0;
-        handle = await fs.open(realPath, fsSync.constants.O_RDONLY | noFollow);
-        const openedStat = await handle.stat();
-        const pathStat = await fs.lstat(realPath);
-        if (!openedStat.isFile() ||
-            !pathStat.isFile() ||
-            !sameFileIdentity(previewStat, openedStat) ||
-            !sameFileIdentity(pathStat, openedStat) ||
-            (options.rejectHardlinks !== false && openedStat.nlink > 1)) {
-            throw new FsSafeError("path-mismatch", "security validation failed");
-        }
-        const secret = (await readFileHandleBounded(handle, maxBytes)).toString("utf8").trim();
-        return secret
-            ? { ok: true, secret }
-            : { ok: false, code: "invalid-path", message: `${label} file at ${resolvedPath} is empty.` };
+        handle = await fs.open(realPath, resolveReadOpenFlags());
+        const openedHandle = handle;
+        const openedStat = await inspectFileIdentity(async () => {
+            const stat = await openedHandle.stat({ bigint: true });
+            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+                throw new FsSafeError("path-mismatch", "security validation failed");
+            }
+            return stat;
+        }, previewStat);
+        await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(realPath, { bigint: true });
+            if (!stat.isFile())
+                throw new FsSafeError("path-mismatch", "security validation failed");
+            return stat;
+        }, openedStat);
+        await inspectFileIdentity(() => inspectInput("secret path became a symlink"), openedStat);
+        raw = (await readFileHandleBounded(handle, maxBytes)).toString("utf8");
     }
     catch (error) {
-        const normalized = error instanceof Error ? error : new Error(String(error));
-        return {
-            ok: false,
-            code: error instanceof FsSafeError
-                ? error.code
-                : pathErrorCode(error) === "not-found"
-                    ? "not-found"
-                    : "read-failed",
-            error: normalized,
-            message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
-        };
+        throw secretReadError(error instanceof FsSafeError
+            ? error.code
+            : secretPathErrorCode(error) === "not-found" ? "not-found" : "read-failed", "read", label, resolvedPath, error);
     }
     finally {
         await handle?.close().catch(() => undefined);
     }
-}
-export async function readSecretFile(filePath, label, options = {}) {
-    const result = await readSecretFileOutcome(filePath, label, options);
-    if (result.ok)
-        return result.secret;
-    throw new FsSafeError(result.code, result.message, { cause: result.error });
+    return trimSecretFileContent(raw, label, resolvedPath);
 }
 export async function tryReadSecretFile(filePath, label, options = {}) {
     if (!filePath?.trim())
         return undefined;
-    const result = await readSecretFileOutcome(filePath, label, options);
-    if (result.ok)
-        return result.secret;
-    if (result.code === "not-found")
-        return undefined;
-    throw new FsSafeError(result.code, result.message, { cause: result.error });
+    try {
+        return await readSecretFile(filePath, label, options);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "not-found")
+            return undefined;
+        throw error;
+    }
 }

package/dist/secret-read-policy.d.ts

@@ -0,0 +1,13 @@
+import type { BigIntStats } from "node:fs";
+import { FsSafeError, type FsSafeErrorCode } from "./errors.js";
+export declare const DEFAULT_SECRET_FILE_MAX_BYTES: number;
+export type SecretFileReadOptions = {
+    maxBytes?: number;
+    rejectSymlink?: boolean;
+    rejectHardlinks?: boolean;
+};
+export declare function secretPathErrorCode(error: unknown): FsSafeErrorCode;
+export declare function secretReadError(code: FsSafeErrorCode, action: "inspect" | "read", label: string, resolvedPath: string, error: unknown): FsSafeError;
+export declare function assertSecretFilePreview(stat: BigIntStats, label: string, resolvedPath: string, maxBytes: number, rejectHardlinks: boolean): void;
+export declare function trimSecretFileContent(raw: string, label: string, resolvedPath: string): string;
+//# sourceMappingURL=secret-read-policy.d.ts.map

package/dist/secret-read-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-read-policy.d.ts","sourceRoot":"","sources":["../src/secret-read-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAGnE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,GAAG,MAAM,EAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,WAAW,CAGb;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,OAAO,GACvB,IAAI,CAUN;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM9F"}

package/dist/secret-read-policy.js

@@ -0,0 +1,28 @@
+import { FsSafeError } from "./errors.js";
+export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
+export function secretPathErrorCode(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
+export function secretReadError(code, action, label, resolvedPath, error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return new FsSafeError(code, `Failed to ${action} ${label} file at ${resolvedPath}: ${String(cause)}`, { cause });
+}
+export function assertSecretFilePreview(stat, label, resolvedPath, maxBytes, rejectHardlinks) {
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", `${label} file at ${resolvedPath} must be a regular file.`, { cause: undefined });
+    }
+    if (rejectHardlinks && stat.nlink > 1n) {
+        throw new FsSafeError("hardlink", `${label} file at ${resolvedPath} must not be hardlinked.`, { cause: undefined });
+    }
+    if (stat.size > maxBytes) {
+        throw new FsSafeError("too-large", `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.`, { cause: undefined });
+    }
+}
+export function trimSecretFileContent(raw, label, resolvedPath) {
+    const secret = raw.trim();
+    if (!secret) {
+        throw new FsSafeError("invalid-path", `${label} file at ${resolvedPath} is empty.`, { cause: undefined });
+    }
+    return secret;
+}

package/dist/secret.d.ts

@@ -1,3 +1,4 @@
-export { createSecretFileAtomic, DEFAULT_SECRET_FILE_MAX_BYTES, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, type SecretFileReadOptions, } from "./secret-file.js";
+export { createSecretFileAtomic, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
+export { DEFAULT_SECRET_FILE_MAX_BYTES, type SecretFileReadOptions } from "./secret-read-policy.js";
 export { readSecretFile, tryReadSecretFile } from "./secret-read-async.js";
 //# sourceMappingURL=secret.d.ts.map

package/dist/secret.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,6BAA6B,EAAE,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/secret.js

@@ -1,2 +1,3 @@
-export { createSecretFileAtomic, DEFAULT_SECRET_FILE_MAX_BYTES, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
+export { createSecretFileAtomic, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
+export { DEFAULT_SECRET_FILE_MAX_BYTES } from "./secret-read-policy.js";
 export { readSecretFile, tryReadSecretFile } from "./secret-read-async.js";

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;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;AAgLF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/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;AAarC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,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;AA4LF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAe/B"}