@openclaw/fs-safe 0.5.6 → 0.6.0

package/dist/root-paths.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
 import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError, isPathInside, isPathRelativeEscape } from "./path.js";
+import { assertNoNulPathInput, hasNodeErrorCode, isNodeError, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
 import { root as openRoot } from "./root.js";
 function invalidPath(scopeLabel) {
     return {
@@ -126,7 +127,7 @@ async function resolveNearestExistingPath(targetPath) {
 async function assertNoSymlinkSegments(params) {
     const relative = path.relative(params.rootDir, params.targetPath);
     if (isPathRelativeEscape(relative)) {
-        throw new Error(`Invalid path: must stay within ${params.scopeLabel}`);
+        throw new FsSafeError("outside-workspace", `Invalid path: must stay within ${params.scopeLabel}`);
     }
     let current = params.rootDir;
     for (const segment of relative.split(path.sep).filter(Boolean)) {
@@ -134,10 +135,10 @@ async function assertNoSymlinkSegments(params) {
         try {
             const stat = await fs.lstat(current);
             if (stat.isSymbolicLink()) {
-                throw new Error(`Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
+                throw new FsSafeError("symlink", `Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
             }
             if (!stat.isDirectory()) {
-                throw new Error(`Invalid path: existing segment must be a directory within ${params.scopeLabel}`);
+                throw new FsSafeError("not-file", `Invalid path: existing segment must be a directory within ${params.scopeLabel}`);
             }
         }
         catch (err) {
@@ -149,28 +150,29 @@ async function assertNoSymlinkSegments(params) {
     }
 }
 export async function ensureDirectoryWithinRoot(params) {
-    const lexical = resolvePathWithinRoot({
-        rootDir: params.rootDir,
-        requestedPath: params.requestedPath,
-        scopeLabel: params.scopeLabel,
-        defaultFileName: params.defaultDirName,
-    });
-    if (!lexical.ok) {
-        return lexical;
-    }
-    const rootDir = path.resolve(params.rootDir);
-    const targetPath = path.resolve(lexical.path);
+    const scopeLabel = formatErrorDetail(params.scopeLabel.slice(0, 80));
     try {
+        assertNoNulPathInput(params.rootDir);
+        assertNoNulPathInput(params.requestedPath);
+        if (!params.requestedPath.trim())
+            assertNoNulPathInput(params.defaultDirName ?? "");
+        const lexical = resolvePathWithinRoot({
+            ...params, scopeLabel, defaultFileName: params.defaultDirName,
+        });
+        if (!lexical.ok)
+            return lexical;
+        const rootDir = path.resolve(params.rootDir);
+        const targetPath = lexical.path;
         const rootStat = await fs.lstat(rootDir);
         if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-            return invalidPath(params.scopeLabel);
+            return invalidPath(scopeLabel);
         }
-        await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel: params.scopeLabel });
+        await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
         const rootReal = await fs.realpath(rootDir);
         const nearestExistingPath = await resolveNearestExistingPath(targetPath);
         const nearestExistingReal = await fs.realpath(nearestExistingPath);
         if (!isPathInside(rootReal, nearestExistingReal)) {
-            return invalidPath(params.scopeLabel);
+            return invalidPath(scopeLabel);
         }
         const relative = path.relative(rootDir, targetPath);
         let current = rootDir;
@@ -180,7 +182,7 @@ export async function ensureDirectoryWithinRoot(params) {
                 try {
                     const stat = await fs.lstat(current);
                     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-                        return invalidPath(params.scopeLabel);
+                        return invalidPath(scopeLabel);
                     }
                     break;
                 }
@@ -192,10 +194,7 @@ export async function ensureDirectoryWithinRoot(params) {
                         await fs.mkdir(current, { mode: params.mode });
                     }
                     catch (mkdirErr) {
-                        if (isNotFoundPathError(mkdirErr)) {
-                            throw mkdirErr;
-                        }
-                        if (mkdirErr.code === "EEXIST") {
+                        if (hasNodeErrorCode(mkdirErr, "EEXIST")) {
                             continue;
                         }
                         throw mkdirErr;
@@ -204,17 +203,27 @@ export async function ensureDirectoryWithinRoot(params) {
             }
             const currentReal = await fs.realpath(current);
             if (!isPathInside(rootReal, currentReal)) {
-                return invalidPath(params.scopeLabel);
+                return invalidPath(scopeLabel);
             }
         }
         const targetReal = await fs.realpath(targetPath);
         if (!isPathInside(rootReal, targetReal)) {
-            return invalidPath(params.scopeLabel);
+            return invalidPath(scopeLabel);
         }
         return { ok: true, path: targetPath };
     }
-    catch {
-        return invalidPath(params.scopeLabel);
+    catch (cause) {
+        if ((cause instanceof FsSafeError && cause.category === "policy") ||
+            hasNodeErrorCode(cause, "ENOTDIR")) {
+            return invalidPath(scopeLabel);
+        }
+        // Native messages include unbounded paths; display only bounded errno metadata.
+        const code = isNodeError(cause) && typeof cause.code === "string"
+            ? formatErrorDetail(cause.code.slice(0, 40)) : "filesystem operation failed";
+        const syscall = isNodeError(cause) && typeof cause.syscall === "string"
+            ? ` during ${formatErrorDetail(cause.syscall.slice(0, 40))}` : "";
+        const diagnostic = new FsSafeError("helper-failed", `Could not prepare ${scopeLabel}: ${code}${syscall}`, { cause });
+        return { ok: false, error: diagnostic.message, diagnostic };
     }
 }
 export function resolvePathsWithinRoot(params) {

package/dist/root-write-verification.d.ts

@@ -0,0 +1,11 @@
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import type { PublishedWriteIdentity } from "./pinned-write.js";
+import { type RootContext } from "./root-context.js";
+export declare function verifyAtomicWriteResult(params: {
+    root: RootContext;
+    targetPath: string;
+    fd: number;
+    expectedIdentity: PublishedWriteIdentity;
+    parentGuard: AsyncDirectoryGuard;
+}): Promise<void>;
+//# sourceMappingURL=root-write-verification.d.ts.map

package/dist/root-write-verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-verification.d.ts","sourceRoot":"","sources":["../src/root-write-verification.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAK3F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,WAAW,EAAE,mBAAmB,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6EhB"}

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":"AAWA,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,CAsER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;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"}

package/dist/secret-file.js

@@ -9,155 +9,81 @@ import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.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 = options.maxBytes ?? 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;
+    }
     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);

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":"AAMA,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,CAgEjB;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

@@ -2,98 +2,76 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { readFileHandleBounded } from "./bounded-read.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 { 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 = options.maxBytes ?? 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;
+    }
     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.` };
+        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"}