@openclaw/fs-safe 0.5.5 → 0.6.0

package/dist/root-impl.js

@@ -5,11 +5,11 @@ import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./fsync.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { sameFileIdentity, sameFileIdentityForCleanup, } from "./file-identity.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { assertMutationNotDenied, mergeDenyMutationPolicies, } from "./deny-mutations.js";
-import { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
+import { resolveOpenedFileRealPathForFd, resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy, } from "./pinned-write.js";
 import { getNativeBinding } from "./native.js";
 import { validatePinnedOperationPayload } from "./pinned-operation.js";
@@ -25,6 +25,8 @@ import { stringifyJsonDocument } from "./json-stringify.js";
 import { walkRoot } from "./root-walk.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { serializePathWrite } from "./write-queue.js";
+import { verifyAtomicWriteResult } from "./root-write-verification.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 function logWarn(message) {
     if (process.env.FS_SAFE_DEBUG_WARNINGS === "1") {
@@ -74,22 +76,27 @@ async function openVerifiedLocalFile(filePath, options) {
     assertNoUnsafeDeviceReadPath(filePath);
     const fsSafeTestHooks = getFsSafeTestHooks();
     let preOpenStat;
+    let observedBeforeOpen = false;
     // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
     // results that get sent to messaging channels). See openclaw/openclaw#31186.
     try {
-        preOpenStat = await fs.lstat(filePath);
-        if (preOpenStat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
-            throw new FsSafeError("symlink", "symlink not allowed");
-        }
-        if (!preOpenStat.isFile() && !preOpenStat.isSymbolicLink()) {
-            throw new FsSafeError("not-file", "not a file");
-        }
+        preOpenStat = await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(filePath, { bigint: true });
+            observedBeforeOpen = true;
+            if (stat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
+                throw new FsSafeError("symlink", "symlink not allowed");
+            }
+            if (!stat.isFile() && !stat.isSymbolicLink()) {
+                throw new FsSafeError("not-file", "not a file");
+            }
+            return stat;
+        });
     }
     catch (err) {
-        if (err instanceof FsSafeError) {
+        if (err instanceof FsSafeError || observedBeforeOpen) {
             throw err;
         }
-        // ENOENT and other lstat errors: fall through and let fs.open handle.
+        // Only an initial lookup failure falls through; a failed re-inspection aborts.
     }
     if (preOpenStat) {
         await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
@@ -127,37 +134,28 @@ async function openVerifiedLocalFile(filePath, options) {
         if (!stat.isFile()) {
             throw new FsSafeError("not-file", "not a file");
         }
-        if (preOpenStat &&
-            !preOpenStat.isSymbolicLink() &&
-            !sameFileIdentity(stat, preOpenStat)) {
-            throw new FsSafeError("path-mismatch", "path changed before open");
-        }
+        // Keep numeric Stats for the public receipt, never for identity verification.
+        const identity = await inspectFileIdentity(() => handle.stat({ bigint: true }), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined);
         if (options?.hardlinks === "reject" && stat.nlink > 1) {
             throw hardlinkedPathNotAllowedError();
         }
-        if (options?.symlinks === "follow-within-root") {
-            const pathStat = await fs.stat(filePath);
-            if (!sameFileIdentity(stat, pathStat)) {
-                throw new FsSafeError("path-mismatch", "path changed during read");
-            }
-        }
-        else {
-            const pathStat = await fs.lstat(filePath);
-            if (pathStat.isSymbolicLink()) {
+        await inspectFileIdentity(async () => {
+            const pathStat = options?.symlinks === "follow-within-root"
+                ? await fs.stat(filePath, { bigint: true })
+                : await fs.lstat(filePath, { bigint: true });
+            if (pathStat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
                 throw new FsSafeError("symlink", "symlink not allowed");
             }
-            if (!sameFileIdentity(stat, pathStat)) {
-                throw new FsSafeError("path-mismatch", "path changed during read");
+            return pathStat;
+        }, identity);
+        const realPath = await resolveOpenedFileRealPathForFd(handle.fd, identity, filePath);
+        await inspectFileIdentity(async () => {
+            const realStat = await fs.stat(realPath, { bigint: true });
+            if (options?.hardlinks === "reject" && realStat.nlink > 1n) {
+                throw hardlinkedPathNotAllowedError();
             }
-        }
-        const realPath = await resolveOpenedFileRealPathForHandle(handle, filePath);
-        const realStat = await fs.stat(realPath);
-        if (options?.hardlinks === "reject" && realStat.nlink > 1) {
-            throw hardlinkedPathNotAllowedError();
-        }
-        if (!sameFileIdentity(stat, realStat)) {
-            throw new FsSafeError("path-mismatch", "path mismatch");
-        }
+            return realStat;
+        }, identity);
         return openResult({ handle, realPath, stat });
     }
     catch (err) {
@@ -473,24 +471,14 @@ async function writeTempFileForAtomicReplace(params) {
         else {
             await tempHandle.writeFile(params.data);
         }
-        return await tempHandle.stat();
+        return {
+            handle: tempHandle,
+            identity: await tempHandle.stat({ bigint: true }),
+        };
     }
-    finally {
+    catch (error) {
         await tempHandle.close().catch(() => { });
-    }
-}
-async function verifyAtomicWriteResult(params) {
-    const opened = await openVerifiedLocalFile(params.targetPath, { hardlinks: "reject" });
-    try {
-        if (!sameFileIdentity(opened.stat, params.expectedIdentity)) {
-            throw new FsSafeError("path-mismatch", "path changed during write");
-        }
-        if (!isPathInside(params.root.rootWithSep, opened.realPath)) {
-            throw outsideWorkspaceError();
-        }
-    }
-    finally {
-        await opened.handle.close().catch(() => { });
+        throw error;
     }
 }
 async function resolveGuardedWritePathInRoot(root, params) {
@@ -706,9 +694,9 @@ async function writeFileInRoot(root, params) {
     });
 }
 async function commitPinnedWriteInRoot(root, pinned, params) {
-    let identity;
+    let verifyingPublication = false;
     try {
-        identity = await runPinnedWriteWithRenamePolicy({
+        await runPinnedWriteWithRenamePolicy({
             rootPath: pinned.rootReal,
             relativeParentPath: pinned.relativeParentPath,
             basename: pinned.basename,
@@ -719,9 +707,27 @@ async function commitPinnedWriteInRoot(root, pinned, params) {
             overwrite: params.overwrite,
             input: { kind: "buffer", data: params.data, encoding: params.encoding },
             rootIdentity: root.rootIdentity,
+            verifyPublished: async (fd, expectedIdentity, parentGuard) => {
+                verifyingPublication = true;
+                try {
+                    await verifyAtomicWriteResult({
+                        root,
+                        targetPath: pinned.targetPath,
+                        fd,
+                        expectedIdentity,
+                        parentGuard,
+                    });
+                }
+                catch (error) {
+                    emitWriteBoundaryWarning(`post-write verification failed: ${String(error)}`);
+                    throw error;
+                }
+            },
         });
     }
     catch (error) {
+        if (verifyingPublication)
+            throw error;
         const errorCode = error?.code;
         if (errorCode === "file_lock_stale" || errorCode === "file_lock_timeout") {
             throw error;
@@ -733,17 +739,6 @@ async function commitPinnedWriteInRoot(root, pinned, params) {
         }
         throw normalizePinnedWriteError(error);
     }
-    try {
-        await verifyAtomicWriteResult({
-            root,
-            targetPath: pinned.targetPath,
-            expectedIdentity: identity,
-        });
-    }
-    catch (err) {
-        emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
-        throw err;
-    }
 }
 async function copyFileInRoot(root, params) {
     assertValidRootRelativePath(params.relativePath);
@@ -807,7 +802,7 @@ async function assertCopySourcePathCurrent(source) {
 async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
     const current = await fs.lstat(targetPath);
-    if (current.isSymbolicLink() || !sameFileIdentity(current, identity)) {
+    if (current.isSymbolicLink() || !sameFileIdentityForCleanup(current, identity)) {
         return;
     }
     await withAsyncDirectoryGuards([parentGuard], async () => {
@@ -860,7 +855,7 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode,
         targetPath: resolved,
         relativeParentPath: path.posix.dirname(relativePosix) === "." ? "" : path.posix.dirname(relativePosix),
         basename,
-        mode: mode || 0o600,
+        mode,
     };
 }
 async function resolvePinnedPathInRoot(root, params) {
@@ -1105,28 +1100,32 @@ async function writeFileFallback(root, params) {
     const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
     let tempPath = null;
     let unregisterTempPath = null;
+    let writtenHandle;
     try {
         tempPath = buildAtomicWriteTempPath(destinationPath);
         unregisterTempPath = registerTempPathForExit(tempPath);
-        const writtenStat = await writeTempFileForAtomicReplace({
+        const written = await writeTempFileForAtomicReplace({
             tempPath,
             data: params.data,
             encoding: params.encoding,
-            mode: mode || 0o600,
+            mode,
         });
-        unregisterTempPath.setIdentity(writtenStat);
+        writtenHandle = written.handle;
+        unregisterTempPath.setIdentity(written.identity);
         const commitTempPath = tempPath;
         await withAsyncDirectoryGuards([destinationGuard], async () => {
             await fs.rename(commitTempPath, destinationPath);
+            tempPath = null;
         });
-        tempPath = null;
         unregisterTempPath();
         unregisterTempPath = null;
         try {
             await verifyAtomicWriteResult({
                 root,
                 targetPath: destinationPath,
-                expectedIdentity: writtenStat,
+                expectedIdentity: written.identity,
+                fd: written.handle.fd,
+                parentGuard: destinationGuard,
             });
         }
         catch (err) {
@@ -1135,6 +1134,7 @@ async function writeFileFallback(root, params) {
         }
     }
     finally {
+        await writtenHandle?.close().catch(() => undefined);
         if (tempPath) {
             await fs.rm(tempPath, { force: true }).catch(() => { });
         }
@@ -1152,19 +1152,22 @@ async function writeMissingFileFallback(root, params) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
     let created = false;
     let createdIdentity;
+    let writtenHandle;
+    let verifyingPublication = false;
     try {
         const { handle, writtenStat } = await withAsyncDirectoryGuards([parentGuard], async () => {
             const handle = await fs.open(targetPath, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
             created = true;
             try {
                 createdIdentity = await handle.stat();
+                const writtenStat = await handle.stat({ bigint: true });
                 if (typeof params.data === "string") {
                     await handle.writeFile(params.data, params.encoding ?? "utf8");
                 }
                 else {
                     await handle.writeFile(params.data);
                 }
-                return { handle, writtenStat: await handle.stat() };
+                return { handle, writtenStat };
             }
             catch (error) {
                 await handle.close().catch(() => undefined);
@@ -1176,15 +1179,20 @@ async function writeMissingFileFallback(root, params) {
                 await handle.close().catch(() => undefined);
             },
         });
-        await handle.close();
+        writtenHandle = handle;
+        created = false;
+        verifyingPublication = true;
         await verifyAtomicWriteResult({
             root,
             targetPath,
             expectedIdentity: writtenStat,
+            fd: handle.fd,
+            parentGuard,
         });
-        created = false;
     }
     catch (err) {
+        if (verifyingPublication)
+            throw err;
         if (hasNodeErrorCode(err, "EEXIST")) {
             throw new FsSafeError("already-exists", "file already exists", {
                 cause: err instanceof Error ? err : undefined,
@@ -1193,6 +1201,7 @@ async function writeMissingFileFallback(root, params) {
         throw err;
     }
     finally {
+        await writtenHandle?.close().catch(() => undefined);
         if (created && createdIdentity) {
             await removePathIfIdentityUnchanged(targetPath, createdIdentity).catch(() => undefined);
         }

package/dist/root-paths.d.ts

@@ -1,7 +1,16 @@
+import { FsSafeError } from "./errors.js";
 type InvalidPathResult = {
     ok: false;
     error: string;
 };
+type DirectoryResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+    diagnostic?: FsSafeError;
+};
 type ResolvePathsWithinRootParams = {
     rootDir: string;
     requestedPaths: string[];
@@ -39,13 +48,7 @@ export type PathScope = {
     }>;
     ensureDir(requestedPath: string, options?: PathScopeResolveOptions & {
         mode?: number;
-    }): Promise<{
-        ok: true;
-        path: string;
-    } | {
-        ok: false;
-        error: string;
-    }>;
+    }): Promise<DirectoryResult>;
 };
 export declare function resolvePathWithinRoot(params: {
     rootDir: string;
@@ -77,13 +80,7 @@ export declare function ensureDirectoryWithinRoot(params: {
     scopeLabel: string;
     defaultDirName?: string;
     mode?: number;
-}): Promise<{
-    ok: true;
-    path: string;
-} | {
-    ok: false;
-    error: string;
-}>;
+}): Promise<DirectoryResult>;
 export declare function resolvePathsWithinRoot(params: ResolvePathsWithinRootParams): ResolvePathsWithinRootResult;
 export declare function resolveExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function resolveStrictExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;

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

@@ -1 +1 @@
-{"version":3,"file":"root-paths.d.ts","sourceRoot":"","sources":["../src/root-paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"root-paths.d.ts","sourceRoot":"","sources":["../src/root-paths.ts"],"names":[],"mappings":"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"}

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