@openclaw/fs-safe 0.5.5 → 0.6.0

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

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

package/dist/secure-file.js

@@ -4,10 +4,11 @@ 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";
 import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
 import { isPathInside, isSymlinkOpenError } from "./path.js";
+import { formatPermissionErrorDetail } from "./permission-exec.js";
 import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
 const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 function isAbsolutePathname(value) {
@@ -52,20 +53,18 @@ async function openSecureHandle(options) {
         if (!openedStat.isFile()) {
             throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
         }
-        const pathStat = options.trust?.allowSymlink
-            ? await fs.stat(options.filePath)
-            : await fs.lstat(options.filePath);
-        if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
-        }
-        if (!sameFileIdentity(pathStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", `${label(options)} changed during open.`);
-        }
+        const openedIdentity = await inspectFileIdentity(() => handle.stat({ bigint: true }));
+        await inspectFileIdentity(async () => {
+            const pathStat = options.trust?.allowSymlink
+                ? await fs.stat(options.filePath, { bigint: true })
+                : await fs.lstat(options.filePath, { bigint: true });
+            if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+            }
+            return pathStat;
+        }, openedIdentity);
         const realPath = await fs.realpath(options.filePath);
-        const realStat = await fs.stat(realPath);
-        if (!sameFileIdentity(realStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", `${label(options)} real path changed during open.`);
-        }
+        await inspectFileIdentity(() => fs.stat(realPath, { bigint: true }), openedIdentity);
         if (options.io?.maxBytes !== undefined && openedStat.size > options.io.maxBytes) {
             throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
         }
@@ -111,11 +110,21 @@ async function assertSecurePermissions(options, stat, realPath) {
     const permissions = platform === "win32"
         ? await inspectPathPermissions(realPath, options.inject)
         : inspectOpenedPermissions(stat, platform);
+    const reason = permissions.error ? `: ${formatPermissionErrorDetail(permissions.error)}` : "";
+    const diagnostics = {
+        ...(permissions.errorCause !== undefined ? { cause: permissions.errorCause } : {}),
+        ...(permissions.ownerError || permissions.errorDetail ? {
+            details: {
+                ...(permissions.ownerError ? { ownerError: formatPermissionErrorDetail(permissions.ownerError) } : {}),
+                ...permissions.errorDetail,
+            },
+        } : {}),
+    };
     if (!permissions.ok) {
-        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}`);
+        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}${reason}`, diagnostics);
     }
     if (platform === "win32" && permissions.source === "unknown") {
-        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}.`);
+        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}${reason || "."}`, diagnostics);
     }
     if (platform === "win32" && permissions.ownerTrusted !== true) {
         throw new FsSafeError(permissions.ownerTrusted === false ? "not-owned" : "permission-unverified", `${label(options)} owner could not be trusted on Windows: ${realPath}`);

package/dist/sibling-temp.js

@@ -51,7 +51,7 @@ export async function writeSiblingTempFile(options) {
     try {
         tempExists = true;
         const result = await options.writeTemp(tempPath);
-        unregisterTempPath.setIdentity(await fs.lstat(tempPath));
+        unregisterTempPath.setIdentity(await fs.lstat(tempPath, { bigint: true }));
         if (options.mode !== undefined) {
             await fs.chmod(tempPath, options.mode).catch(() => undefined);
         }

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAO3C,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAmP5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAO3C,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAsP5B"}

package/dist/sidecar-lock-acquire.js

@@ -133,7 +133,10 @@ export async function acquireSidecarLock(options, context) {
                 const interval = options.compromiseCheckIntervalMs;
                 if (options.onCompromised && interval !== undefined && interval > 0) {
                     createdHeld.compromiseTimer = setInterval(() => {
-                        void returnedHandle.verifyStillHeld().then((stillHeld) => {
+                        void returnedHandle
+                            .verifyStillHeld()
+                            .catch(() => false)
+                            .then((stillHeld) => {
                             if (!stillHeld && createdHeld.compromiseTimer) {
                                 clearInterval(createdHeld.compromiseTimer);
                                 createdHeld.compromiseTimer = undefined;

package/dist/staged-directory.d.ts

@@ -0,0 +1,16 @@
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { StagedFileReceipt } from "./staged-file-types.js";
+type DirectorySnapshot = StagedFileReceipt["directory"];
+export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>): boolean;
+export declare function describeStagedDirectory(fd: number, pathname: string): DirectorySnapshot;
+export declare function assertStagedDirectoryCurrent(receipt: DirectorySnapshot): void;
+export declare function openStagedDirectory(directory: string | DirectoryReceipt): {
+    fd: number;
+    receipt: DirectorySnapshot;
+};
+export {};
+//# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}

package/dist/staged-directory.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+export function exactIdentityMatches(expected, actual) {
+    return ["dev", "ino"].every((key) => {
+        const value = expected[key];
+        return (typeof value === "bigint" || Number.isSafeInteger(value)) && BigInt(value) === actual[key];
+    });
+}
+export function describeStagedDirectory(fd, pathname) {
+    const identity = fs.fstatSync(fd, { bigint: true });
+    if (!identity.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const receipt = Object.freeze({
+        path: path.resolve(pathname),
+        realPath: fs.realpathSync(pathname),
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
+    });
+    assertStagedDirectoryCurrent(receipt);
+    return receipt;
+}
+export function assertStagedDirectoryCurrent(receipt) {
+    const current = fs.lstatSync(receipt.path, { bigint: true });
+    if (!current.isDirectory() || !exactIdentityMatches(receipt.identity, current) ||
+        fs.realpathSync(receipt.path) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+}
+export function openStagedDirectory(directory) {
+    // Copy supplied facts before any asynchronous work; receipts are not authority.
+    const pathname = path.resolve(typeof directory === "string" ? directory : directory.path);
+    const expected = typeof directory === "string" ? undefined : {
+        realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
+    };
+    const before = fs.lstatSync(pathname, { bigint: true });
+    if (!before.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a real directory");
+    }
+    if (expected && (!exactIdentityMatches(expected, before) || fs.realpathSync(pathname) !== expected.realPath)) {
+        throw new FsSafeError("path-mismatch", "stale staging directory receipt");
+    }
+    const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const receipt = describeStagedDirectory(fd, pathname);
+        if (!exactIdentityMatches(before, receipt.identity)) {
+            throw new FsSafeError("path-mismatch", "staging directory changed while opening");
+        }
+        return { fd, receipt };
+    }
+    catch (error) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "staging directory admission and close failed");
+        }
+        throw error;
+    }
+}