@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-path.js

@@ -1,12 +1,18 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
-import { formatErrorDetail, shortPath } from "./error-detail.js";
+import { shortPath } from "./error-detail.js";
+import { pathEscapeError, sanitizeRootPathError, symlinkEscapeError } from "./root-path-errors.js";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
+import { isNativeDirectoryObservationGuard } from "./native-directory-observation.js";
+import { assertNoNulPathInput, isNotFoundPathError, isPathRelativeEscape, } from "./path.js";
 import { absolutePathWithRawSegments, rawPathRelativeToCanonicalRoot, resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
+import { admitPathInsideRoot, } from "./root-boundary.js";
+import { RootPathObservationError, captureRootPathObservedDirectory, createRootPathTraversalObservation, inspectRootPathTraversalEntry, } from "./root-path-observation.js";
 import { resolveSymlinkHopPath, resolveSymlinkHopPathSync } from "./root-path-symlink.js";
 import { assertNoDriveRelativePathSegments } from "./safe-path-segment.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
+export { RootPathObservationError, } from "./root-path-observation.js";
 export const ROOT_PATH_ALIAS_POLICIES = {
     strict: Object.freeze({
         allowFinalSymlinkForUnlink: false,
@@ -25,15 +31,47 @@ export async function resolveRootPath(params) {
         throw sanitizeRootPathError(error);
     }
 }
-async function resolveRootPathInternal(params) {
-    assertValidRootPathInputs(params);
-    params = { ...params, absolutePath: absolutePathWithRawSegments(params.absolutePath) };
-    const rootPath = path.resolve(params.rootPath);
-    const absolutePath = path.resolve(params.absolutePath);
-    const rootCanonicalPath = params.rootCanonicalPath
-        ? path.resolve(params.rootCanonicalPath)
+export async function resolveRootPathWithCanonicalRootObservation(params, observeRoot) {
+    try {
+        return await resolveRootPathInternal(params, undefined, undefined, observeRoot);
+    }
+    catch (error) {
+        throw sanitizeRootPathError(error);
+    }
+}
+async function resolveRootPathInternal(params, observationRequest, observationOutput, observeRoot, removalReceipts) {
+    const input = captureValidRootPathInputs(params);
+    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
+    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
+    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
+    const rootCanonicalPath = input.rootCanonicalPath
+        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
         : await resolvePathViaExistingAncestor(rootPath);
-    return resolveRootPathLexicalAsync(prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath));
+    assertNoWindowsPathAlias(rootPath);
+    assertNoWindowsPathAlias(absolutePath);
+    assertNoWindowsPathAlias(rootCanonicalPath);
+    observeRoot?.(rootCanonicalPath);
+    return resolveRootPathLexicalAsync(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath), observationRequest, observationOutput, removalReceipts);
+}
+export async function resolveRootPathWithObservation(params, request) {
+    const output = {};
+    try {
+        const resolved = await resolveRootPathInternal(params, request, output);
+        return output.receipt ? { resolved, receipt: output.receipt } : { resolved };
+    }
+    catch (error) {
+        throw sanitizeRootPathError(error);
+    }
+}
+// Removal receipts are separate from metadata observations and canonical-root
+// callbacks; the public resolver's options and result remain unchanged.
+export async function resolveRootPathForRemoval(params, receipts) {
+    try {
+        return await resolveRootPathInternal(params, undefined, undefined, undefined, receipts);
+    }
+    catch (error) {
+        throw sanitizeRootPathError(error);
+    }
 }
 export function resolveRootPathSync(params) {
     try {
@@ -43,46 +81,90 @@ export function resolveRootPathSync(params) {
         throw sanitizeRootPathError(error);
     }
 }
-function resolveRootPathSyncInternal(params) {
-    assertValidRootPathInputs(params);
-    params = { ...params, absolutePath: absolutePathWithRawSegments(params.absolutePath) };
-    const rootPath = path.resolve(params.rootPath);
-    const absolutePath = path.resolve(params.absolutePath);
-    const rootCanonicalPath = params.rootCanonicalPath
-        ? path.resolve(params.rootCanonicalPath)
+export function resolveRootPathSyncWithCanonicalRootObservation(params, observeRoot) {
+    try {
+        return resolveRootPathSyncInternal(params, observeRoot);
+    }
+    catch (error) {
+        throw sanitizeRootPathError(error);
+    }
+}
+function resolveRootPathSyncInternal(params, observeRoot) {
+    const input = captureValidRootPathInputs(params);
+    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
+    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
+    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
+    const rootCanonicalPath = input.rootCanonicalPath
+        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
         : resolvePathViaExistingAncestorSync(rootPath);
-    return resolveRootPathLexicalSync(prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath));
+    assertNoWindowsPathAlias(rootPath);
+    assertNoWindowsPathAlias(absolutePath);
+    assertNoWindowsPathAlias(rootCanonicalPath);
+    observeRoot?.(rootCanonicalPath);
+    return resolveRootPathLexicalSync(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath));
 }
-function prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath) {
-    let raw = params.absolutePath;
-    if (rawPathRelativeToRoot(rootPath, raw) === undefined) {
-        const relative = rawPathRelativeToRoot(rootCanonicalPath, raw)
+function prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath) {
+    let raw = rawAbsolutePath;
+    let trustedAbsolutePath = false;
+    const direct = admitRawPathInsideRoot(rootPath, raw, params.rootIdentity);
+    if (direct) {
+        raw = direct.path;
+        trustedAbsolutePath = direct.admission === "identity";
+    }
+    else {
+        const canonical = admitRawPathInsideRoot(rootCanonicalPath, raw, params.rootIdentity);
+        const relative = canonical?.relativePath
             ?? rawPathRelativeToCanonicalRoot(raw, rootCanonicalPath, params);
         if (relative === undefined) {
             throw pathEscapeError({ rootPath, absolutePath: raw, boundaryLabel: params.boundaryLabel });
         }
-        raw = `${rootPath}${path.sep}${relative}`;
+        trustedAbsolutePath = canonical?.admission === "identity";
+        raw = relative === "" ? rootPath : `${rootPath}${path.sep}${relative}`;
     }
     return {
-        params: raw === params.absolutePath ? params : { ...params, absolutePath: raw },
-        rootPath, rootCanonicalPath, absolutePath,
+        params,
+        rawAbsolutePath: raw,
+        rootPath,
+        rootCanonicalPath,
+        // Preserve the caller-spelling receipt for ordinary aliases. Only a
+        // Windows case-fold admission must return the identity-gated Root spelling,
+        // because downstream I/O must not reuse the ambiguous caller prefix.
+        absolutePath: trustedAbsolutePath ? resolvePathPreservingWindowsRoot(raw) : absolutePath,
+        observationEligible: raw === rawAbsolutePath && !trustedAbsolutePath,
     };
 }
-function sanitizeRootPathError(error) {
-    if (error instanceof Error) {
-        error.message = formatErrorDetail(error.message);
-    }
-    return error;
-}
-function assertValidRootPathInputs(params) {
-    assertNoNulPathInput(params.rootPath, "root path contains a NUL byte");
-    assertNoNulPathInput(params.absolutePath, "absolute path contains a NUL byte");
-    assertNoEmbeddedDriveRelativeSegment(params.rootPath, "root path");
-    assertNoEmbeddedDriveRelativeSegment(params.absolutePath, "absolute path");
-    if (params.rootCanonicalPath !== undefined) {
-        assertNoNulPathInput(params.rootCanonicalPath, "canonical root path contains a NUL byte");
-        assertNoEmbeddedDriveRelativeSegment(params.rootCanonicalPath, "canonical root path");
+function captureValidRootPathInputs(params) {
+    const rootPath = params.rootPath;
+    assertNoNulPathInput(rootPath, "root path contains a NUL byte");
+    const absolutePath = params.absolutePath;
+    assertNoNulPathInput(absolutePath, "absolute path contains a NUL byte");
+    assertNoWindowsPathAlias(rootPath, "filesystem", "root path uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(absolutePath, "filesystem", "absolute path uses a Windows filesystem namespace alias");
+    assertNoEmbeddedDriveRelativeSegment(rootPath, "root path");
+    assertNoEmbeddedDriveRelativeSegment(absolutePath, "absolute path");
+    const rootCanonicalPath = params.rootCanonicalPath;
+    if (rootCanonicalPath !== undefined) {
+        assertNoNulPathInput(rootCanonicalPath, "canonical root path contains a NUL byte");
+        assertNoWindowsPathAlias(rootCanonicalPath, "filesystem", "canonical root path uses a Windows filesystem namespace alias");
+        assertNoEmbeddedDriveRelativeSegment(rootCanonicalPath, "canonical root path");
     }
+    // Keep traversal policy with the admitted paths across ancestor and symlink
+    // resolution. Caller-owned flags and getters must not change a running walk.
+    const policy = params.policy;
+    const rootIdentity = params.rootIdentity;
+    return {
+        rootPath,
+        absolutePath,
+        rootCanonicalPath,
+        rootIdentity: rootIdentity == null ? undefined : { dev: rootIdentity.dev, ino: rootIdentity.ino },
+        boundaryLabel: params.boundaryLabel,
+        policy: policy == null ? undefined : {
+            allowFinalSymlinkForUnlink: policy.allowFinalSymlinkForUnlink,
+        },
+        rejectSymlinks: params.rejectSymlinks,
+        rejectFinalSymlink: params.rejectFinalSymlink,
+        rejectUnresolvedSymlinks: params.rejectUnresolvedSymlinks,
+    };
 }
 function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     if (process.platform !== "win32") {
@@ -92,13 +174,15 @@ function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     assertNoDriveRelativePathSegments(filePath.slice(root.length).replaceAll("\\", "/"), label);
 }
 function createLexicalTraversalState(params) {
-    const rawAbsolutePath = params.params.absolutePath;
-    const relative = rawPathRelativeToRoot(params.rootPath, rawAbsolutePath);
+    const rawAbsolutePath = params.rawAbsolutePath;
+    const relative = admitRawPathInsideRoot(params.rootPath, rawAbsolutePath, params.params.rootIdentity)?.relativePath;
     if (relative === undefined)
         throw new Error("Path traversal must begin at the root");
     const segments = splitTraversalSegments(relative);
     return {
         segments,
+        relativePath: relative,
+        reuseLexicalCanonical: false,
         finalComponentIndex: segments.findLastIndex((segment) => segment !== "."),
         allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
         canonicalCursor: params.rootCanonicalPath,
@@ -114,8 +198,16 @@ function createLexicalTraversalContext(params) {
         rootPath: params.rootPath,
         rootCanonicalPath: params.rootCanonicalPath,
         absolutePath: params.absolutePath,
+        observationEligible: params.observationEligible,
     };
 }
+function createLexicalTraversalObservation(context, request) {
+    const observation = createRootPathTraversalObservation(context, request);
+    if (observation && observation.targetIndex >= 0) {
+        context.state.reuseLexicalCanonical = true;
+    }
+    return observation;
+}
 function splitTraversalSegments(value) {
     const segments = value
         .split(process.platform === "win32" ? /[\\/]+/ : /\/+/)
@@ -124,38 +216,53 @@ function splitTraversalSegments(value) {
         segments.push(".");
     return segments;
 }
-function rawPathRelativeToRoot(rootPath, candidatePath) {
+function admitRawPathInsideRoot(rootPath, candidatePath, rootIdentity) {
     if (!path.isAbsolute(candidatePath)) {
         return undefined;
     }
-    const root = path.resolve(rootPath);
+    // Every caller supplies the already-resolved root selected by
+    // resolveRootPathInternal; resolving it again is redundant on each traversal.
+    const root = rootPath;
     const candidate = process.platform === "win32"
         ? candidatePath.replaceAll("/", path.sep)
         : candidatePath;
+    if (process.platform === "win32") {
+        return admitPathInsideRoot({ rootPath: root, candidatePath: candidate, rootIdentity });
+    }
     if (candidate === root) {
-        return "";
+        return { admission: "exact", path: candidate, relativePath: "" };
     }
     const rootWithSep = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
     const candidatePrefix = candidate.slice(0, rootWithSep.length);
-    const prefixMatches = process.platform === "win32"
-        ? candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()
-        : candidatePrefix === rootWithSep;
-    return prefixMatches ? candidate.slice(rootWithSep.length) : undefined;
+    return candidatePrefix === rootWithSep
+        ? {
+            admission: "exact",
+            path: candidate,
+            relativePath: candidate.slice(rootWithSep.length),
+        }
+        : undefined;
 }
 function assertLexicalCursorInsideBoundary(context, candidatePath) {
-    assertInsideBoundary({
+    return assertInsideBoundary({
         boundaryLabel: context.resolveParams.boundaryLabel,
         rootCanonicalPath: context.rootCanonicalPath,
+        rootIdentity: context.resolveParams.rootIdentity,
         candidatePath,
         absolutePath: context.absolutePath,
     });
 }
 function advanceCanonicalCursorForSegment(context, segment) {
-    context.state.canonicalCursor = path.resolve(context.state.canonicalCursor, segment);
-    assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
+    const candidatePath = context.state.reuseLexicalCanonical
+        ? context.state.lexicalCursor
+        : resolvePathFromBasePreservingWindowsRoot(context.state.canonicalCursor, segment);
+    context.state.canonicalCursor = assertLexicalCursorInsideBoundary(context, candidatePath);
+}
+function disableLexicalTraversalObservation(context, observation) {
+    observation.enabled = false;
+    context.state.reuseLexicalCanonical = false;
 }
 function finalizeLexicalResolution(context, kind) {
-    assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
+    context.state.canonicalCursor = assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
     return buildResolvedRootPath({
         absolutePath: context.absolutePath,
         canonicalPath: context.state.canonicalCursor,
@@ -181,18 +288,22 @@ function lexicalStatDisposition(params) {
     return params.allowFinalSymlink && params.isLast ? "break" : "resolve-link";
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
-    if (!isPathInside(context.rootCanonicalPath, linkCanonical)) {
+    let admitted;
+    try {
+        admitted = assertLexicalCursorInsideBoundary(context, linkCanonical);
+    }
+    catch {
         throw symlinkEscapeError({
             boundaryLabel: context.resolveParams.boundaryLabel,
             rootCanonicalPath: context.rootCanonicalPath,
             symlinkPath: context.state.lexicalCursor,
         });
     }
-    context.state.canonicalCursor = linkCanonical;
-    context.state.lexicalCursor = linkCanonical;
+    context.state.canonicalCursor = admitted;
+    context.state.lexicalCursor = admitted;
 }
 function applyParentTraversalStep(context) {
-    context.state.lexicalCursor = path.resolve(context.state.lexicalCursor, "..");
+    context.state.lexicalCursor = resolvePathFromBasePreservingWindowsRoot(context.state.lexicalCursor, "..");
     advanceCanonicalCursorForSegment(context, "..");
     if (context.state.missingDepth > 0)
         context.state.missingDepth -= 1;
@@ -205,12 +316,13 @@ function assertDirectoryBeforeMoreSegments(stat, pathname, isLast) {
 function assertResolvedLinkDirectory(pathname, isLast) {
     if (isLast)
         return;
-    const stat = fs.statSync(pathname);
+    const stat = fs.statSync(pathForWindowsFilesystem(pathname));
     assertDirectoryBeforeMoreSegments(stat, pathname, isLast);
 }
-async function resolveRootPathLexicalAsync(params) {
+async function resolveRootPathLexicalAsync(params, observationRequest, observationOutput, removalReceipts) {
     const context = createLexicalTraversalContext(params);
     const { state } = context;
+    const observation = createLexicalTraversalObservation(context, observationRequest);
     for (let idx = 0; idx < state.segments.length; idx += 1) {
         const segment = state.segments[idx] ?? "";
         const isLast = idx === state.segments.length - 1;
@@ -227,14 +339,56 @@ async function resolveRootPathLexicalAsync(params) {
             continue;
         }
         let stat;
+        let observed;
         try {
-            stat = fs.lstatSync(state.lexicalCursor);
+            if (removalReceipts && !isLast) {
+                const directoryStat = fs.lstatSync(pathForWindowsFilesystem(state.lexicalCursor), { bigint: true });
+                if (directoryStat.isDirectory() && !directoryStat.isSymbolicLink()) {
+                    removalReceipts.observeDirectory(state.lexicalCursor, directoryStat);
+                }
+                stat = directoryStat;
+            }
+            else {
+                const directorySlot = observation?.enabled === true && idx === observation.directoryIndex;
+                const targetSlot = observation?.enabled === true && idx === observation.targetIndex;
+                const observeExactly = directorySlot || targetSlot;
+                if (observeExactly) {
+                    observed = inspectRootPathTraversalEntry(state.lexicalCursor, directorySlot, observation);
+                }
+                stat = isNativeDirectoryObservationGuard(observed)
+                    ? undefined
+                    : observed?.stat ?? fs.lstatSync(state.lexicalCursor);
+            }
         }
         catch (error) {
+            if (observation?.enabled && observation.request.kind === "stat" &&
+                idx === observation.targetIndex && observation.directoryGuard) {
+                const parentReceipt = {
+                    kind: "stat-parent",
+                    rootGuard: observation.request.rootGuard,
+                    directoryGuard: observation.directoryGuard,
+                    directoryObserver: observation.directoryObserver,
+                    targetPath: state.lexicalCursor,
+                };
+                // Stop here: the generic missing-path fallback would re-admit a parent.
+                // Preserve observation-only versus ordinary traversal error precedence.
+                throw new RootPathObservationError(error instanceof RootPathObservationError ? error.error : sanitizeRootPathError(error), parentReceipt, !(error instanceof RootPathObservationError));
+            }
             if (handleLexicalLstatFailure(context, error, segment))
                 continue;
             throw error;
         }
+        if (isNativeDirectoryObservationGuard(observed)) {
+            advanceCanonicalCursorForSegment(context, segment);
+            captureRootPathObservedDirectory(observation, observed, state.lexicalCursor, state.canonicalCursor, context.rootCanonicalPath, context.resolveParams.rootIdentity);
+            if (idx === observation.targetIndex) {
+                observation.targetPath = state.canonicalCursor;
+                observation.target = observed;
+            }
+            continue;
+        }
+        if (!stat)
+            throw new Error("directory observation did not return metadata");
         const isSymbolicLink = stat.isSymbolicLink();
         if (!isSymbolicLink)
             assertDirectoryBeforeMoreSegments(stat, state.lexicalCursor, isLast);
@@ -248,10 +402,24 @@ async function resolveRootPathLexicalAsync(params) {
         if (disposition !== "resolve-link") {
             state.preserveFinalSymlink = disposition === "break";
             advanceCanonicalCursorForSegment(context, segment);
+            if (observation?.enabled && isSymbolicLink) {
+                disableLexicalTraversalObservation(context, observation);
+            }
+            if (observation?.enabled && idx === observation.directoryIndex) {
+                const captured = observed?.identity && captureRootPathObservedDirectory(observation, observed, state.canonicalCursor, state.canonicalCursor, context.rootCanonicalPath, context.resolveParams.rootIdentity);
+                if (!captured)
+                    disableLexicalTraversalObservation(context, observation);
+            }
+            if (observation?.enabled && idx === observation.targetIndex) {
+                observation.targetPath = state.canonicalCursor;
+                observation.target = observed?.identity ? observed : undefined;
+            }
             if (state.preserveFinalSymlink)
                 break;
             continue;
         }
+        if (observation?.enabled)
+            disableLexicalTraversalObservation(context, observation);
         const linkCanonical = await resolveSymlinkHopPath(state.lexicalCursor, {
             rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
         });
@@ -261,7 +429,26 @@ async function resolveRootPathLexicalAsync(params) {
         }
         assertResolvedLinkDirectory(linkCanonical, isLast);
     }
-    const kind = await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
+    const completeObservation = observation?.enabled === true && observation.directoryGuard !== undefined &&
+        observation.targetPath === state.canonicalCursor && observation.target !== undefined;
+    const kind = completeObservation
+        ? {
+            exists: true,
+            kind: isNativeDirectoryObservationGuard(observation.target)
+                ? "directory"
+                : toResolvedKind(observation.target.stat),
+        }
+        : await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
+    if (completeObservation && observationOutput) {
+        observationOutput.receipt = {
+            kind: observation.request.kind,
+            rootGuard: observation.request.rootGuard,
+            directoryGuard: observation.directoryGuard,
+            directoryObserver: observation.directoryObserver,
+            targetPath: observation.targetPath,
+            target: observation.target,
+        };
+    }
     return finalizeLexicalResolution(context, kind);
 }
 function resolveRootPathLexicalSync(params) {
@@ -333,9 +520,10 @@ function buildResolvedRootPath(params) {
 }
 async function getPathKind(absolutePath, preserveFinalSymlink) {
     try {
+        const operationPath = pathForWindowsFilesystem(absolutePath);
         const stat = preserveFinalSymlink
-            ? fs.lstatSync(absolutePath)
-            : fs.statSync(absolutePath);
+            ? fs.lstatSync(operationPath)
+            : fs.statSync(operationPath);
         return { exists: true, kind: toResolvedKind(stat) };
     }
     catch (error) {
@@ -347,7 +535,10 @@ async function getPathKind(absolutePath, preserveFinalSymlink) {
 }
 function getPathKindSync(absolutePath, preserveFinalSymlink) {
     try {
-        const stat = preserveFinalSymlink ? fs.lstatSync(absolutePath) : fs.statSync(absolutePath);
+        const operationPath = pathForWindowsFilesystem(absolutePath);
+        const stat = preserveFinalSymlink
+            ? fs.lstatSync(operationPath)
+            : fs.statSync(operationPath);
         return { exists: true, kind: toResolvedKind(stat) };
     }
     catch (error) {
@@ -370,7 +561,7 @@ function toResolvedKind(stat) {
     return "other";
 }
 function relativeInsideRoot(rootPath, targetPath) {
-    const relative = path.relative(path.resolve(rootPath), path.resolve(targetPath));
+    const relative = path.relative(resolvePathPreservingWindowsRoot(rootPath), resolvePathPreservingWindowsRoot(targetPath));
     if (!relative || relative === ".") {
         return "";
     }
@@ -380,14 +571,13 @@ function relativeInsideRoot(rootPath, targetPath) {
     return relative;
 }
 function assertInsideBoundary(params) {
-    if (isPathInside(params.rootCanonicalPath, params.candidatePath)) {
-        return;
+    const admitted = admitPathInsideRoot({
+        rootPath: params.rootCanonicalPath,
+        candidatePath: params.candidatePath,
+        rootIdentity: params.rootIdentity,
+    });
+    if (admitted) {
+        return admitted.path;
     }
     throw new Error(`Path resolves outside ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.absolutePath)}`);
 }
-function pathEscapeError(params) {
-    return new Error(`Path escapes ${params.boundaryLabel} (${shortPath(params.rootPath)}): ${shortPath(params.absolutePath)}`);
-}
-function symlinkEscapeError(params) {
-    return new Error(`Symlink escapes ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.symlinkPath)}`);
-}

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

@@ -0,0 +1,9 @@
+import { type ResolvePathWithinRootParams } from "./path-scope-lexical.js";
+export declare function resolvePathWithinRoot(params: ResolvePathWithinRootParams): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=root-paths-lexical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-paths-lexical.d.ts","sourceRoot":"","sources":["../src/root-paths-lexical.ts"],"names":[],"mappings":"AACA,OAAO,EAAmC,KAAK,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAU5G,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,2BAA2B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAgB3D"}

package/dist/root-paths-lexical.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { resolvePathWithinNormalizedRoot } from "./path-scope-lexical.js";
+import { hasWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function invalidPath(scopeLabel) {
+    return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+}
+export function resolvePathWithinRoot(params) {
+    const rootDir = params.rootDir;
+    if (typeof rootDir !== "string")
+        path.resolve(rootDir);
+    const requestedPath = params.requestedPath;
+    const scopeLabel = params.scopeLabel;
+    const defaultFileName = params.defaultFileName;
+    if (hasWindowsPathAlias(rootDir, "filesystem") ||
+        hasWindowsPathAlias(requestedPath, "filesystem") ||
+        (defaultFileName !== undefined &&
+            hasWindowsPathAlias(defaultFileName, "filesystem"))) {
+        return invalidPath(scopeLabel);
+    }
+    const root = resolvePathPreservingWindowsRoot(rootDir);
+    return resolvePathWithinNormalizedRoot({ rootDir, requestedPath, scopeLabel, defaultFileName }, root);
+}

package/dist/root-paths.d.ts

@@ -1,16 +1,10 @@
-import { FsSafeError } from "./errors.js";
+import { type DirectoryResult } from "./root-directory.js";
+export { resolvePathWithinRoot } from "./root-paths-lexical.js";
+export { ensureDirectoryWithinRoot } from "./root-directory.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[];
@@ -50,18 +44,6 @@ export type PathScope = {
         mode?: number;
     }): Promise<DirectoryResult>;
 };
-export declare function resolvePathWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultFileName?: string;
-}): {
-    ok: true;
-    path: string;
-} | {
-    ok: false;
-    error: string;
-};
 export declare function resolveWritablePathWithinRoot(params: {
     rootDir: string;
     requestedPath: string;
@@ -74,16 +56,8 @@ export declare function resolveWritablePathWithinRoot(params: {
     ok: false;
     error: string;
 }>;
-export declare function ensureDirectoryWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultDirName?: string;
-    mode?: number;
-}): 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>;
 export declare function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
-export {};
 //# sourceMappingURL=root-paths.d.ts.map

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":"AAgBA,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,KAAK,iBAAiB,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACtD,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;AAoEF,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,CA0CrE;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,4BAA4B,CA2B9B;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,CAyC/E"}