@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-paths.js

@@ -1,39 +1,44 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
 import path from "node:path";
-import { formatErrorDetail } from "./error-detail.js";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, hasNodeErrorCode, isNodeError, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
-import { root as openRoot } from "./root.js";
+import { isNotFoundPathError, isPathInside, } from "./path.js";
 import { realpathSync } from "./realpath.js";
+import { root as openRoot } from "./root.js";
+import { hasWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { resolvePathWithinRoot } from "./root-paths-lexical.js";
+import { resolvePathWithinNormalizedRoot } from "./path-scope-lexical.js";
+import { assertNoSymlinkSegments, ensureDirectoryWithinRoot, resolveNearestExistingPath, } from "./root-directory.js";
+export { resolvePathWithinRoot } from "./root-paths-lexical.js";
+export { ensureDirectoryWithinRoot } from "./root-directory.js";
 function invalidPath(scopeLabel) {
     return {
         ok: false,
         error: `Invalid path: must stay within ${scopeLabel}`,
     };
 }
-function pathStaysWithinRoot(rootDir, candidatePath) {
-    if (process.platform !== "win32") {
-        return candidatePath !== rootDir && isPathInside(rootDir, candidatePath);
-    }
-    const relative = path.relative(rootDir, candidatePath);
-    return Boolean(relative) && !isPathRelativeEscape(relative);
-}
+const INVALID_REAL_PATH = Symbol("invalid-real-path");
 async function resolveRealPathIfExists(targetPath) {
+    if (hasWindowsPathAlias(targetPath, "filesystem"))
+        return INVALID_REAL_PATH;
     try {
-        return realpathSync.native(targetPath);
+        const realPath = realpathSync.native(pathForWindowsFilesystem(targetPath));
+        return hasWindowsPathAlias(realPath, "filesystem") ? INVALID_REAL_PATH : realPath;
     }
     catch {
         return undefined;
     }
 }
 async function resolveTrustedRootRealPath(rootDir) {
+    if (hasWindowsPathAlias(rootDir, "filesystem"))
+        return undefined;
     try {
-        const rootLstat = fsSync.lstatSync(rootDir);
+        const operationPath = pathForWindowsFilesystem(rootDir);
+        const rootLstat = fsSync.lstatSync(operationPath);
         if (!rootLstat.isDirectory() || rootLstat.isSymbolicLink()) {
             return undefined;
         }
-        return realpathSync.native(rootDir);
+        const realPath = realpathSync.native(operationPath);
+        return hasWindowsPathAlias(realPath, "filesystem") ? undefined : realPath;
     }
     catch {
         return undefined;
@@ -41,7 +46,8 @@ async function resolveTrustedRootRealPath(rootDir) {
 }
 async function validateCanonicalPathWithinRoot(params) {
     try {
-        const candidateLstat = fsSync.lstatSync(params.candidatePath);
+        const operationPath = pathForWindowsFilesystem(params.candidatePath);
+        const candidateLstat = fsSync.lstatSync(operationPath);
         if (candidateLstat.isSymbolicLink()) {
             return "invalid";
         }
@@ -54,41 +60,33 @@ async function validateCanonicalPathWithinRoot(params) {
         if (params.expect === "file" && candidateLstat.nlink > 1) {
             return "invalid";
         }
-        const candidateRealPath = realpathSync.native(params.candidatePath);
+        const candidateRealPath = realpathSync.native(operationPath);
+        if (hasWindowsPathAlias(candidateRealPath, "filesystem"))
+            return "invalid";
         return isPathInside(params.rootRealPath, candidateRealPath) ? "ok" : "invalid";
     }
     catch (err) {
         return isNotFoundPathError(err) ? "not-found" : "invalid";
     }
 }
-export function resolvePathWithinRoot(params) {
-    const root = path.resolve(params.rootDir);
-    const raw = params.requestedPath.trim();
-    if (!raw) {
-        if (!params.defaultFileName) {
-            return { ok: false, error: "path is required" };
-        }
-        const defaultPath = path.resolve(root, params.defaultFileName);
-        if (!pathStaysWithinRoot(root, defaultPath)) {
-            return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
-        }
-        return { ok: true, path: defaultPath };
-    }
-    const resolved = path.resolve(root, raw);
-    if (!pathStaysWithinRoot(root, resolved)) {
-        return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
-    }
-    return { ok: true, path: resolved };
-}
 export async function resolveWritablePathWithinRoot(params) {
-    const lexical = resolvePathWithinRoot(params);
+    const rootDirInput = params.rootDir;
+    const requestedPathInput = params.requestedPath;
+    const scopeLabel = params.scopeLabel;
+    const defaultFileName = params.defaultFileName;
+    const lexical = resolvePathWithinRoot({
+        rootDir: rootDirInput,
+        requestedPath: requestedPathInput,
+        scopeLabel,
+        defaultFileName,
+    });
     if (!lexical.ok) {
         return lexical;
     }
-    const rootDir = path.resolve(params.rootDir);
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
     const rootRealPath = await resolveTrustedRootRealPath(rootDir);
     if (!rootRealPath) {
-        return invalidPath(params.scopeLabel);
+        return invalidPath(scopeLabel);
     }
     const requestedPath = lexical.path;
     const parentDir = path.dirname(requestedPath);
@@ -98,7 +96,7 @@ export async function resolveWritablePathWithinRoot(params) {
         expect: "directory",
     });
     if (parentStatus !== "ok") {
-        return invalidPath(params.scopeLabel);
+        return invalidPath(scopeLabel);
     }
     const targetStatus = await validateCanonicalPathWithinRoot({
         rootRealPath,
@@ -106,139 +104,33 @@ export async function resolveWritablePathWithinRoot(params) {
         expect: "file",
     });
     if (targetStatus === "invalid") {
-        return invalidPath(params.scopeLabel);
+        return invalidPath(scopeLabel);
     }
     return lexical;
 }
-async function resolveNearestExistingPath(targetPath) {
-    let current = path.resolve(targetPath);
-    while (true) {
-        try {
-            fsSync.lstatSync(current);
-            return current;
-        }
-        catch (err) {
-            if (!isNotFoundPathError(err)) {
-                throw err;
-            }
-        }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            throw new Error(`failed to resolve existing path for ${targetPath}`);
-        }
-        current = parent;
-    }
-}
-async function assertNoSymlinkSegments(params) {
-    const relative = path.relative(params.rootDir, params.targetPath);
-    if (isPathRelativeEscape(relative)) {
-        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)) {
-        current = path.join(current, segment);
-        try {
-            const stat = fsSync.lstatSync(current);
-            if (stat.isSymbolicLink()) {
-                throw new FsSafeError("symlink", `Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
-            }
-            if (!stat.isDirectory()) {
-                throw new FsSafeError("not-file", `Invalid path: existing segment must be a directory within ${params.scopeLabel}`);
-            }
-        }
-        catch (err) {
-            if (isNotFoundPathError(err)) {
-                return;
-            }
-            throw err;
-        }
-    }
-}
-export async function ensureDirectoryWithinRoot(params) {
-    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 = fsSync.lstatSync(rootDir);
-        if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-            return invalidPath(scopeLabel);
-        }
-        await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
-        const rootReal = realpathSync.native(rootDir);
-        const nearestExistingPath = await resolveNearestExistingPath(targetPath);
-        const nearestExistingReal = realpathSync.native(nearestExistingPath);
-        if (!isPathInside(rootReal, nearestExistingReal)) {
-            return invalidPath(scopeLabel);
-        }
-        const relative = path.relative(rootDir, targetPath);
-        let current = rootDir;
-        for (const segment of relative.split(path.sep).filter(Boolean)) {
-            current = path.join(current, segment);
-            while (true) {
-                try {
-                    const stat = fsSync.lstatSync(current);
-                    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-                        return invalidPath(scopeLabel);
-                    }
-                    break;
-                }
-                catch (err) {
-                    if (!isNotFoundPathError(err)) {
-                        throw err;
-                    }
-                    try {
-                        await fs.mkdir(current, { mode: params.mode });
-                    }
-                    catch (mkdirErr) {
-                        if (hasNodeErrorCode(mkdirErr, "EEXIST")) {
-                            continue;
-                        }
-                        throw mkdirErr;
-                    }
-                }
-            }
-            const currentReal = realpathSync.native(current);
-            if (!isPathInside(rootReal, currentReal)) {
-                return invalidPath(scopeLabel);
-            }
-        }
-        const targetReal = realpathSync.native(targetPath);
-        if (!isPathInside(rootReal, targetReal)) {
-            return invalidPath(scopeLabel);
-        }
-        return { ok: true, path: targetPath };
-    }
-    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) {
     const resolvedPaths = [];
+    let previousRootDir;
+    let previousResolvedRoot = "";
     for (const raw of params.requestedPaths) {
-        const pathResult = resolvePathWithinRoot({
+        const request = {
             rootDir: params.rootDir,
             requestedPath: raw,
             scopeLabel: params.scopeLabel,
-        });
+        };
+        // Each lexical request owns its admitted root without consuming later items.
+        if (typeof request.rootDir !== "string")
+            path.resolve(request.rootDir);
+        if (hasWindowsPathAlias(request.rootDir, "filesystem"))
+            return invalidPath(request.scopeLabel);
+        // Relative roots may follow cwd changes made by an input iterator or getter.
+        const resolvedRoot = process.platform !== "win32" && typeof request.rootDir === "string" &&
+            request.rootDir.startsWith("/") && request.rootDir === previousRootDir
+            ? previousResolvedRoot
+            : resolvePathPreservingWindowsRoot(request.rootDir);
+        previousRootDir = request.rootDir;
+        previousResolvedRoot = resolvedRoot;
+        const pathResult = resolvePathWithinNormalizedRoot(request, resolvedRoot);
         if (!pathResult.ok) {
             return { ok: false, error: pathResult.error };
         }
@@ -253,10 +145,11 @@ export async function resolveStrictExistingPathsWithinRoot(params) {
     return await resolveCheckedPathsWithinRoot(params, false);
 }
 export function pathScope(rootDir, options) {
-    const base = { rootDir, scopeLabel: options.label };
+    const label = options.label;
+    const base = { rootDir, scopeLabel: label };
     return {
         rootDir,
-        label: options.label,
+        label,
         resolve: (requestedPath, pathOptions) => resolvePathWithinRoot({
             ...base,
             requestedPath,
@@ -288,8 +181,19 @@ export function pathScope(rootDir, options) {
     };
 }
 async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
-    const rootDir = path.resolve(params.rootDir);
-    const rootRealPath = await resolveRealPathIfExists(rootDir);
+    const rootDirInput = params.rootDir;
+    const scopeLabel = params.scopeLabel;
+    if (hasWindowsPathAlias(rootDirInput, "filesystem")) {
+        return invalidPath(scopeLabel);
+    }
+    const requestedPaths = [...params.requestedPaths];
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    if (hasWindowsPathAlias(rootDir, "filesystem"))
+        return invalidPath(scopeLabel);
+    const rootRealPathResult = await resolveRealPathIfExists(rootDir);
+    if (rootRealPathResult === INVALID_REAL_PATH)
+        return invalidPath(scopeLabel);
+    const rootRealPath = rootRealPathResult;
     const root = rootRealPath ? await openRoot(rootDir) : undefined;
     const isInRoot = (relativePath) => Boolean(relativePath) &&
         relativePath !== ".." &&
@@ -300,7 +204,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
         const lexicalPathResult = resolvePathWithinRoot({
             rootDir,
             requestedPath,
-            scopeLabel: params.scopeLabel,
+            scopeLabel,
         });
         if (lexicalPathResult.ok) {
             return {
@@ -309,11 +213,17 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                 fallbackPath: lexicalPathResult.path,
             };
         }
-        if (!rootRealPath || !raw || !path.isAbsolute(raw)) {
+        if (!rootRealPath ||
+            !raw ||
+            !path.isAbsolute(raw) ||
+            hasWindowsPathAlias(raw, "filesystem")) {
             return lexicalPathResult;
         }
         try {
-            const resolvedExistingPath = realpathSync.native(raw);
+            const resolvedExistingPath = realpathSync.native(pathForWindowsFilesystem(raw));
+            if (hasWindowsPathAlias(resolvedExistingPath, "filesystem")) {
+                return lexicalPathResult;
+            }
             const relativePath = path.relative(rootRealPath, resolvedExistingPath);
             if (!isInRoot(relativePath)) {
                 return lexicalPathResult;
@@ -329,7 +239,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
         }
     };
     const resolvedPaths = [];
-    for (const raw of params.requestedPaths) {
+    for (const raw of requestedPaths) {
         const pathResult = await resolveExistingRelativePath(raw);
         if (!pathResult.ok) {
             return { ok: false, error: pathResult.error };
@@ -352,16 +262,17 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                     await assertNoSymlinkSegments({
                         rootDir,
                         targetPath: pathResult.fallbackPath,
-                        scopeLabel: params.scopeLabel,
+                        scopeLabel,
                     });
                     const existingPath = await resolveNearestExistingPath(pathResult.fallbackPath);
-                    const existingRealPath = realpathSync.native(existingPath);
-                    if (!isPathInside(rootRealPath, existingRealPath)) {
-                        return invalidPath(params.scopeLabel);
+                    const existingRealPath = realpathSync.native(pathForWindowsFilesystem(existingPath));
+                    if (hasWindowsPathAlias(existingRealPath, "filesystem") ||
+                        !isPathInside(rootRealPath, existingRealPath)) {
+                        return invalidPath(scopeLabel);
                     }
                 }
                 catch {
-                    return invalidPath(params.scopeLabel);
+                    return invalidPath(scopeLabel);
                 }
                 resolvedPaths.push(pathResult.fallbackPath);
                 continue;
@@ -369,12 +280,12 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
             if (err instanceof FsSafeError && err.code === "outside-workspace") {
                 return {
                     ok: false,
-                    error: `File is outside ${params.scopeLabel}`,
+                    error: `File is outside ${scopeLabel}`,
                 };
             }
             return {
                 ok: false,
-                error: `Invalid path: must stay within ${params.scopeLabel} and be a regular non-symlink file`,
+                error: `Invalid path: must stay within ${scopeLabel} and be a regular non-symlink file`,
             };
         }
         finally {

package/dist/root-read-admission.d.ts

@@ -0,0 +1,26 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type RootContext } from "./root-context.js";
+import type { HardlinkPolicy } from "./root-options.js";
+import type { SymlinkPolicy } from "./root-symlink-policy.js";
+export declare function inspectOpenedPathIdentitySync(filePath: string, symlinks: SymlinkPolicy | undefined): BigIntStats;
+type OwnedRootReadHandle = {
+    handle: FileHandle;
+    stat: {
+        nlink: number;
+    };
+};
+export declare function admitRootReadHandle<T extends OwnedRootReadHandle>(params: {
+    root: RootContext;
+    filePath: string;
+    opened: T;
+    identity: BigIntStats;
+    hardlinks?: HardlinkPolicy;
+    symlinks?: SymlinkPolicy;
+    beforeFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+    afterPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
+}): Promise<T & {
+    realPath: string;
+}>;
+export {};
+//# sourceMappingURL=root-read-admission.d.ts.map

package/dist/root-read-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-read-admission.d.ts","sourceRoot":"","sources":["../src/root-read-admission.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAmB9D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,GAAG,SAAS,GAClC,WAAW,CAQb;AA6CD,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACzB,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,mBAAmB,EAAE,MAAM,EAAE;IAC/E,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClF,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CACzE,GAAG,OAAO,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BpC"}

package/dist/root-read-admission.js

@@ -0,0 +1,94 @@
+import fsSync, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { openedPathResolutionError, recordOpenedFileFailure } from "./opened-file-failure.js";
+import { isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrentSync } from "./root-context.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function resolveFinalOpenedRealPath(filePath) {
+    try {
+        return realpathSync.native(filePath);
+    }
+    catch (error) {
+        // Windows can report a deleted-but-open file through either resolver
+        // failure. Only the same-descriptor unlink proof may consume this receipt.
+        if (process.platform === "win32" && error instanceof Error &&
+            ["EPERM", "EBADF"].includes(error.code ?? "")) {
+            throw openedPathResolutionError(error);
+        }
+        throw error;
+    }
+}
+export function inspectOpenedPathIdentitySync(filePath, symlinks) {
+    const stat = symlinks === "follow-within-root"
+        ? fsSync.statSync(filePath, { bigint: true })
+        : fsSync.lstatSync(filePath, { bigint: true });
+    if (stat.isSymbolicLink() && symlinks !== "follow-within-root") {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
+    return stat;
+}
+function assertRootReadAdmissionCurrent(params) {
+    assertRootIdentityCurrentSync(params.root);
+    const admittedPath = (() => {
+        try {
+            inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
+            const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
+            assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+            const admittedRealPath = admitPathInsideRoot({
+                rootPath: params.root.rootReal,
+                candidatePath: canonicalPath,
+                rootIdentity: params.root.rootIdentity,
+            });
+            if (!admittedRealPath) {
+                throw openedPathResolutionError(outsideWorkspaceError());
+            }
+            // This is a fresh no-follow observation even when canonicalPath and
+            // filePath have the same spelling; realpath may have raced a replacement.
+            inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
+            return admittedRealPath.path;
+        }
+        catch (error) {
+            throw isNotFoundPathError(error)
+                ? openedPathResolutionError(fileNotFoundError())
+                : error;
+        }
+    })();
+    params.afterPathIdentityCheck?.(params.filePath, params.handle);
+    assertRootIdentityCurrentSync(params.root);
+    return admittedPath;
+}
+export async function admitRootReadHandle(params) {
+    try {
+        if (params.hardlinks !== "allow" && params.opened.stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+        if (params.beforeFinalFence) {
+            await params.beforeFinalFence(params.filePath, params.opened.handle);
+        }
+        try {
+            const finalRealPath = assertRootReadAdmissionCurrent({
+                root: params.root,
+                filePath: params.filePath,
+                handle: params.opened.handle,
+                identity: params.identity,
+                symlinks: params.symlinks,
+                afterPathIdentityCheck: params.afterPathIdentityCheck,
+            });
+            return { ...params.opened, realPath: finalRealPath };
+        }
+        catch (error) {
+            if (params.identity.nlink <= 1n) {
+                await recordOpenedFileFailure(error, params.opened.handle, params.filePath, params.identity);
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        await params.opened.handle.close().catch(() => { });
+        throw error;
+    }
+}

package/dist/root-remove-identity.d.ts

@@ -0,0 +1,15 @@
+import type { BigIntStats } from "node:fs";
+type ExactDirectoryIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
+export type RemovalDirectoryAssertion = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+    numericDev?: number;
+    numericIno?: number;
+    platform: NodeJS.Platform;
+    realPath?: string;
+}>;
+export declare function createRemovalDirectoryAssertion(path: string, identity: ExactDirectoryIdentity, realPath?: string, platform?: NodeJS.Platform): RemovalDirectoryAssertion;
+export declare function assertRemovalDirectoryCurrent(assertion: RemovalDirectoryAssertion): void;
+export {};
+//# sourceMappingURL=root-remove-identity.d.ts.map

package/dist/root-remove-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-remove-identity.d.ts","sourceRoot":"","sources":["../src/root-remove-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,SAAS,CAAC;AAOlD,KAAK,sBAAsB,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;AAGzE,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAaH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,CAAC,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,yBAAyB,CAc3B;AA0DD,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,yBAAyB,GAAG,IAAI,CAUxF"}

package/dist/root-remove-identity.js

@@ -0,0 +1,89 @@
+import fsSync from "node:fs";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { directoryComponentNotDirectoryError } from "./root-errors.js";
+const MAX_SAFE_DIRECTORY_IDENTITY = BigInt(Number.MAX_SAFE_INTEGER);
+function identityMismatch(cause) {
+    return new FsSafeError("path-mismatch", "removal ancestor identity changed or could not be verified", {
+        cause: cause instanceof Error ? cause : undefined,
+    });
+}
+function safeIdentityNumber(value) {
+    if (value < 0n || value > MAX_SAFE_DIRECTORY_IDENTITY)
+        return undefined;
+    return Number(value);
+}
+export function createRemovalDirectoryAssertion(path, identity, realPath, platform = process.platform) {
+    const dev = safeIdentityNumber(identity.dev);
+    const ino = safeIdentityNumber(identity.ino);
+    const numeric = dev !== undefined && ino !== undefined &&
+        (platform !== "win32" || (dev !== 0 && ino !== 0));
+    return Object.freeze({
+        path,
+        dev: identity.dev,
+        ino: identity.ino,
+        numericDev: numeric ? dev : undefined,
+        numericIno: numeric ? ino : undefined,
+        platform,
+        realPath,
+    });
+}
+function assertDirectoryType(stat) {
+    if (typeof stat?.isDirectory !== "function" || typeof stat.isSymbolicLink !== "function") {
+        throw identityMismatch();
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw directoryComponentNotDirectoryError();
+}
+function assertExactObservation(stat, expected, platform) {
+    assertDirectoryType(stat);
+    if (typeof stat.dev !== "bigint" || typeof stat.ino !== "bigint")
+        throw identityMismatch();
+    if (platform === "win32" && (stat.dev === 0n || stat.ino === 0n))
+        throw identityMismatch();
+    if (stat.dev !== expected.dev || stat.ino !== expected.ino)
+        throw identityMismatch();
+}
+function assertNumericObservation(assertion) {
+    const stat = fsSync.lstatSync(assertion.path);
+    assertDirectoryType(stat);
+    if (!Number.isSafeInteger(stat.dev) || stat.dev < 0 ||
+        !Number.isSafeInteger(stat.ino) || stat.ino < 0) {
+        throw identityMismatch();
+    }
+    let unknown = false;
+    const observedDev = stat.dev;
+    const expectedDev = assertion.numericDev;
+    if (assertion.platform === "win32" && observedDev === 0) {
+        unknown = true;
+    }
+    else if (observedDev !== expectedDev) {
+        // Reject a known mismatch before considering an unknown companion field.
+        throw identityMismatch();
+    }
+    const observedIno = stat.ino;
+    const expectedIno = assertion.numericIno;
+    if (assertion.platform === "win32" && observedIno === 0) {
+        unknown = true;
+    }
+    else if (observedIno !== expectedIno) {
+        throw identityMismatch();
+    }
+    if (unknown) {
+        // The numeric lstat is the first observation. Permit one exact retry only,
+        // retaining every known component and the original exact admission receipt.
+        assertExactObservation(fsSync.lstatSync(assertion.path, { bigint: true }), assertion, assertion.platform);
+    }
+}
+export function assertRemovalDirectoryCurrent(assertion) {
+    if (assertion.numericDev !== undefined && assertion.numericIno !== undefined) {
+        assertNumericObservation(assertion);
+    }
+    else {
+        inspectDirectoryIdentitySync(assertion.path, assertion, undefined, assertion.platform);
+    }
+    if (assertion.realPath !== undefined && realpathSync.native(assertion.path) !== assertion.realPath) {
+        throw identityMismatch();
+    }
+}

package/dist/root-remove-receipt.d.ts

@@ -0,0 +1,17 @@
+import type { BigIntStats } from "node:fs";
+export type CapturedRemovalDirectory = Readonly<{
+    path: string;
+    stat: BigIntStats;
+}>;
+export declare class RemovalPathReceipts {
+    private rootStat;
+    private directories;
+    readonly observeRoot: (stat: BigIntStats) => void;
+    observeDirectory(dir: string, stat: BigIntStats): void;
+    complete(rootReal: string, targetPath: string): {
+        rootStat: BigIntStats;
+        parent: CapturedRemovalDirectory | undefined;
+        directories: readonly CapturedRemovalDirectory[];
+    } | undefined;
+}
+//# sourceMappingURL=root-remove-receipt.d.ts.map

package/dist/root-remove-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-remove-receipt.d.ts","sourceRoot":"","sources":["../src/root-remove-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAKH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,WAAW,CAAoD;IAEvE,QAAQ,CAAC,WAAW,SAAU,WAAW,KAAG,IAAI,CAA8B;IAE9E,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAIrD;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;QAC9C,QAAQ,EAAE,WAAW,CAAC;QACtB,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC;QAC7C,WAAW,EAAE,SAAS,wBAAwB,EAAE,CAAC;KAClD,GAAG,SAAS,CAiBZ;CACF"}