@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/root-impl.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./fsync.js";
@@ -9,7 +10,7 @@ import { sameFileIdentity, sameFileIdentityForCleanup, } from "./file-identity.j
 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 +26,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 +77,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,38 +135,30 @@ 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);
+        await fsSafeTestHooks?.afterOpenedPathIdentityCheck?.(filePath, handle);
+        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 openResult({ handle, realPath, stat });
+            return realStat;
+        }, identity);
+        return { opened: openResult({ handle, realPath, stat }), identity };
     }
     catch (err) {
         await handle.close().catch(() => { });
@@ -212,8 +212,7 @@ class RootHandle {
     async read(relativePath, options = {}) {
         return await readFileInRoot(this.context, {
             relativePath,
-            ...readDefaults(this.defaults),
-            ...options,
+            ...mergeReadOptions(this.defaults, options),
         });
     }
     async readBytes(relativePath, options = {}) {
@@ -229,8 +228,7 @@ class RootHandle {
     async readAbsolute(filePath, options = {}) {
         return await readPathInRoot(this.context, {
             filePath,
-            ...readDefaults(this.defaults),
-            ...options,
+            ...mergeReadOptions(this.defaults, options),
         });
     }
     reader(options = {}) {
@@ -315,13 +313,14 @@ class RootHandle {
     }
     async copyIn(relativePath, sourcePath, options = {}) {
         assertValidRootDestinationPath(relativePath);
+        const { maxBytes, ...copyOptions } = this.mutationOptions(options);
         await copyFileInRoot(this.context, {
             sourcePath,
             relativePath,
-            maxBytes: this.defaults.maxBytes,
+            maxBytes: normalizeMaxBytes(maxBytes, { defaultValue: this.defaults.maxBytes }),
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
-            ...this.mutationOptions(options),
+            ...copyOptions,
         });
     }
     async exists(relativePath) {
@@ -371,12 +370,24 @@ class RootHandle {
 function readDefaults(defaults) {
     return {
         hardlinks: defaults.hardlinks,
-        maxBytes: defaults.maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
+        maxBytes: normalizeMaxBytes(defaults.maxBytes, { defaultValue: DEFAULT_ROOT_MAX_BYTES }),
         nonBlockingRead: defaults.nonBlockingRead,
         symlinks: defaults.symlinks,
     };
 }
+function mergeReadOptions(defaults, options) {
+    const merged = readDefaults(defaults);
+    if (options.hardlinks !== undefined)
+        merged.hardlinks = options.hardlinks;
+    merged.maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: merged.maxBytes });
+    if (options.nonBlockingRead !== undefined)
+        merged.nonBlockingRead = options.nonBlockingRead;
+    if (options.symlinks !== undefined)
+        merged.symlinks = options.symlinks;
+    return merged;
+}
 export async function root(rootDir, defaults = {}) {
+    normalizeMaxBytes(defaults.maxBytes);
     return new RootHandle(await resolveRootContext(rootDir), defaults);
 }
 async function openFileInRoot(root, params) {
@@ -387,10 +398,10 @@ async function openFileInRoot(root, params) {
     });
     let opened;
     try {
-        opened = await openVerifiedLocalFile(resolved, {
+        ({ opened } = await openVerifiedLocalFile(resolved, {
             nonBlockingRead: params.nonBlockingRead,
             symlinks: params.symlinks,
-        });
+        }));
     }
     catch (err) {
         if (err instanceof FsSafeError) {
@@ -432,9 +443,10 @@ async function readPathInRoot(root, params) {
     });
 }
 export async function readLocalFileSafely(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
     const opened = await openLocalFileSafely({ filePath: params.filePath });
     try {
-        return await readOpenedFileSafely({ opened, maxBytes: params.maxBytes });
+        return await readOpenedFileSafely({ opened, maxBytes });
     }
     finally {
         await opened.handle.close().catch(() => { });
@@ -442,7 +454,7 @@ export async function readLocalFileSafely(params) {
 }
 export async function openLocalFileSafely(params) {
     assertNoNulPathInput(params.filePath, "file path contains a NUL byte");
-    return await openVerifiedLocalFile(params.filePath);
+    return (await openVerifiedLocalFile(params.filePath)).opened;
 }
 function emitWriteBoundaryWarning(reason) {
     logWarn(`security: fs-safe write boundary warning (${reason})`);
@@ -474,26 +486,13 @@ async function writeTempFileForAtomicReplace(params) {
             await tempHandle.writeFile(params.data);
         }
         return {
-            identity: await tempHandle.stat(),
-            cleanupIdentity: await tempHandle.stat({ bigint: true }),
+            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) {
@@ -709,9 +708,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,
@@ -722,9 +721,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;
@@ -736,22 +753,11 @@ 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);
     assertNoNulPathInput(params.sourcePath, "source path contains a NUL byte");
-    const source = await openVerifiedLocalFile(params.sourcePath, {
+    const { opened: source, identity: sourceIdentity } = await openVerifiedLocalFile(params.sourcePath, {
         hardlinks: params.sourceHardlinks,
     });
     if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
@@ -762,7 +768,7 @@ async function copyFileInRoot(root, params) {
         await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
             const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
             await serializePathWrite(pinned.targetPath, async () => {
-                await assertCopySourceCurrent(source);
+                await assertCopySourceCurrent(source, sourceIdentity);
                 let identity;
                 try {
                     identity = await runPinnedWriteHelper({
@@ -781,7 +787,7 @@ async function copyFileInRoot(root, params) {
                     throw normalizePinnedWriteError(error);
                 }
                 try {
-                    await assertCopySourcePathCurrent(source);
+                    await assertCopySourcePathCurrent(source, sourceIdentity);
                 }
                 catch (error) {
                     await removePathIfIdentityUnchanged(pinned.targetPath, identity).catch(() => undefined);
@@ -794,18 +800,18 @@ async function copyFileInRoot(root, params) {
         await source.handle.close().catch(() => { });
     }
 }
-async function assertCopySourceCurrent(source) {
-    const opened = await source.handle.stat();
-    if (!sameFileIdentity(opened, source.stat)) {
-        throw new FsSafeError("path-mismatch", "copy source descriptor changed");
-    }
-    await assertCopySourcePathCurrent(source);
+async function assertCopySourceCurrent(source, identity) {
+    await inspectFileIdentity(() => source.handle.stat({ bigint: true }), identity);
+    await assertCopySourcePathCurrent(source, identity);
 }
-async function assertCopySourcePathCurrent(source) {
-    const current = await fs.lstat(source.realPath);
-    if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, source.stat)) {
-        throw new FsSafeError("path-mismatch", "copy source path changed");
-    }
+async function assertCopySourcePathCurrent(source, identity) {
+    await inspectFileIdentity(async () => {
+        const current = await fs.lstat(source.realPath, { bigint: true });
+        if (current.isSymbolicLink() || !current.isFile()) {
+            throw new FsSafeError("path-mismatch", "copy source path changed");
+        }
+        return current;
+    }, identity);
 }
 async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
@@ -863,7 +869,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) {
@@ -1108,6 +1114,7 @@ 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);
@@ -1115,14 +1122,15 @@ async function writeFileFallback(root, params) {
             tempPath,
             data: params.data,
             encoding: params.encoding,
-            mode: mode || 0o600,
+            mode,
         });
-        unregisterTempPath.setIdentity(written.cleanupIdentity);
+        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 {
@@ -1130,6 +1138,8 @@ async function writeFileFallback(root, params) {
                 root,
                 targetPath: destinationPath,
                 expectedIdentity: written.identity,
+                fd: written.handle.fd,
+                parentGuard: destinationGuard,
             });
         }
         catch (err) {
@@ -1138,6 +1148,7 @@ async function writeFileFallback(root, params) {
         }
     }
     finally {
+        await writtenHandle?.close().catch(() => undefined);
         if (tempPath) {
             await fs.rm(tempPath, { force: true }).catch(() => { });
         }
@@ -1155,19 +1166,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);
@@ -1179,15 +1193,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,
@@ -1196,6 +1215,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":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW1C,KAAK,iBAAiB,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACtD,KAAK,eAAe,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAC3D,KAAK,4BAA4B,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AACF,KAAK,4BAA4B,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,iBAAiB,CAAC;AACtF,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AACF,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CACL,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,uBAAuB,GAChC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,4BAA4B,CAAC;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAC1E,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACvE,QAAQ,CACN,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,SAAS,CACP,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,uBAAuB,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B,CAAC;AA4DF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAkB5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAiCrE;AAuDD,wBAAsB,yBAAyB,CAAC,MAAM,EAAE;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,eAAe,CAAC,CA2E3B;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,4BAA4B,CAc9B;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAAC,4BAA4B,CAAC,CAEvC;AAED,wBAAsB,oCAAoC,CACxD,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAAC,4BAA4B,CAAC,CAEvC;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAwC/E"}

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