@openclaw/fs-safe 0.5.1 → 0.5.2

package/dist/root-path-symlink.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveSymlinkHopPath(symlinkPath: string): Promise<string>;
+export declare function resolveSymlinkHopPathSync(symlinkPath: string): string;
+//# sourceMappingURL=root-path-symlink.d.ts.map

package/dist/root-path-symlink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-path-symlink.d.ts","sourceRoot":"","sources":["../src/root-path-symlink.ts"],"names":[],"mappings":"AAmBA,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQhF;AAED,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE"}

package/dist/root-path-symlink.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
+import { resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
+function normalizeSymlinkResolutionError(error) {
+    if (isSymlinkOpenError(error)) {
+        throw new FsSafeError("symlink", "symlink path could not be resolved", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (!isNotFoundPathError(error))
+        throw error;
+}
+export async function resolveSymlinkHopPath(symlinkPath) {
+    try {
+        return path.resolve(await fsp.realpath(symlinkPath));
+    }
+    catch (error) {
+        normalizeSymlinkResolutionError(error);
+        const linkTarget = await fsp.readlink(symlinkPath);
+        return resolvePathViaExistingAncestor(path.resolve(path.dirname(symlinkPath), linkTarget));
+    }
+}
+export function resolveSymlinkHopPathSync(symlinkPath) {
+    try {
+        return path.resolve(fs.realpathSync(symlinkPath));
+    }
+    catch (error) {
+        normalizeSymlinkResolutionError(error);
+        const linkTarget = fs.readlinkSync(symlinkPath);
+        return resolvePathViaExistingAncestorSync(path.resolve(path.dirname(symlinkPath), linkTarget));
+    }
+}

package/dist/root-path.d.ts

@@ -20,6 +20,7 @@ type ResolveRootPathParams = {
     boundaryLabel: string;
     intent?: RootPathIntent;
     policy?: RootPathAliasPolicy;
+    rejectSymlinks?: boolean;
     skipLexicalRootCheck?: boolean;
     rootCanonicalPath?: string;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,kCAAkC,EAAE,MAAM,yBAAyB,CAAC;AAE7E,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CA+BnF"}
+{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,kCAAkC,EAAE,MAAM,yBAAyB,CAAC;AAE7E,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAsCD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CAMnF"}

package/dist/root-path.js

@@ -1,9 +1,13 @@
 import fs from "node:fs";
 import fsp from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
-import { isNotFoundPathError, isPathInside, isPathRelativeEscape } from "./path.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
 import { resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
+import { resolveSymlinkHopPath, resolveSymlinkHopPathSync } from "./root-path-symlink.js";
+import { assertNoDriveRelativePathSegments } from "./safe-path-segment.js";
+import { shortPath } from "./short-path.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
 export const ROOT_PATH_ALIAS_POLICIES = {
     strict: Object.freeze({
@@ -16,6 +20,15 @@ export const ROOT_PATH_ALIAS_POLICIES = {
     }),
 };
 export async function resolveRootPath(params) {
+    try {
+        return await resolveRootPathInternal(params);
+    }
+    catch (error) {
+        throw sanitizeRootPathError(error);
+    }
+}
+async function resolveRootPathInternal(params) {
+    assertValidRootPathInputs(params);
     const rootPath = path.resolve(params.rootPath);
     const absolutePath = path.resolve(params.absolutePath);
     const rootCanonicalPath = params.rootCanonicalPath
@@ -46,6 +59,15 @@ export async function resolveRootPath(params) {
     });
 }
 export function resolveRootPathSync(params) {
+    try {
+        return resolveRootPathSyncInternal(params);
+    }
+    catch (error) {
+        throw sanitizeRootPathError(error);
+    }
+}
+function resolveRootPathSyncInternal(params) {
+    assertValidRootPathInputs(params);
     const rootPath = path.resolve(params.rootPath);
     const absolutePath = path.resolve(params.absolutePath);
     const rootCanonicalPath = params.rootCanonicalPath
@@ -75,6 +97,29 @@ export function resolveRootPathSync(params) {
         rootCanonicalPath: context.rootCanonicalPath,
     });
 }
+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 assertNoEmbeddedDriveRelativeSegment(filePath, label) {
+    if (process.platform !== "win32") {
+        return;
+    }
+    const root = path.parse(filePath).root;
+    assertNoDriveRelativePathSegments(filePath.slice(root.length).replaceAll("\\", "/"), label);
+}
 function isPromiseLike(value) {
     return Boolean(value &&
         (typeof value === "object" || typeof value === "function") &&
@@ -93,6 +138,15 @@ function createLexicalTraversalState(params) {
         preserveFinalSymlink: false,
     };
 }
+function createLexicalTraversalContext(params) {
+    return {
+        state: createLexicalTraversalState(params),
+        resolveParams: params.params,
+        rootPath: params.rootPath,
+        rootCanonicalPath: params.rootCanonicalPath,
+        absolutePath: params.absolutePath,
+    };
+}
 function splitTraversalSegments(value) {
     return value
         .split(process.platform === "win32" ? /[\\/]+/ : /\/+/)
@@ -116,149 +170,97 @@ function rawPathRelativeToRoot(rootPath, candidatePath) {
         : candidatePrefix === rootWithSep;
     return prefixMatches ? candidate.slice(rootWithSep.length) : undefined;
 }
-function assertLexicalCursorInsideBoundary(params) {
+function assertLexicalCursorInsideBoundary(context, candidatePath) {
     assertInsideBoundary({
-        boundaryLabel: params.params.boundaryLabel,
-        rootCanonicalPath: params.rootCanonicalPath,
-        candidatePath: params.candidatePath,
-        absolutePath: params.absolutePath,
+        boundaryLabel: context.resolveParams.boundaryLabel,
+        rootCanonicalPath: context.rootCanonicalPath,
+        candidatePath,
+        absolutePath: context.absolutePath,
     });
 }
-function applyMissingSuffixToCanonicalCursor(params) {
-    const missingSuffix = params.state.segments.slice(params.missingFromIndex);
+function applyMissingSuffixToCanonicalCursor(context, missingFromIndex) {
+    const missingSuffix = context.state.segments.slice(missingFromIndex);
     for (const segment of missingSuffix) {
-        advanceCanonicalCursorForSegment({
-            state: params.state,
-            segment,
-            rootCanonicalPath: params.rootCanonicalPath,
-            params: params.params,
-            absolutePath: params.absolutePath,
-        });
+        advanceCanonicalCursorForSegment(context, segment);
     }
 }
-function advanceCanonicalCursorForSegment(params) {
-    params.state.canonicalCursor = path.resolve(params.state.canonicalCursor, params.segment);
-    assertLexicalCursorInsideBoundary({
-        params: params.params,
-        rootCanonicalPath: params.rootCanonicalPath,
-        candidatePath: params.state.canonicalCursor,
-        absolutePath: params.absolutePath,
-    });
+function advanceCanonicalCursorForSegment(context, segment) {
+    context.state.canonicalCursor = path.resolve(context.state.canonicalCursor, segment);
+    assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
 }
-function finalizeLexicalResolution(params) {
-    assertLexicalCursorInsideBoundary({
-        params: params.params,
-        rootCanonicalPath: params.rootCanonicalPath,
-        candidatePath: params.state.canonicalCursor,
-        absolutePath: params.absolutePath,
-    });
+function finalizeLexicalResolution(context, kind) {
+    assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
     return buildResolvedRootPath({
-        absolutePath: params.absolutePath,
-        canonicalPath: params.state.canonicalCursor,
-        rootPath: params.rootPath,
-        rootCanonicalPath: params.rootCanonicalPath,
-        kind: params.kind,
+        absolutePath: context.absolutePath,
+        canonicalPath: context.state.canonicalCursor,
+        rootPath: context.rootPath,
+        rootCanonicalPath: context.rootCanonicalPath,
+        kind,
     });
 }
-function handleLexicalLstatFailure(params) {
-    if (!isNotFoundPathError(params.error)) {
+function handleLexicalLstatFailure(context, error, missingFromIndex) {
+    if (!isNotFoundPathError(error)) {
         return false;
     }
-    applyMissingSuffixToCanonicalCursor({
-        state: params.state,
-        missingFromIndex: params.missingFromIndex,
-        rootCanonicalPath: params.rootCanonicalPath,
-        params: params.resolveParams,
-        absolutePath: params.absolutePath,
-    });
+    applyMissingSuffixToCanonicalCursor(context, missingFromIndex);
     return true;
 }
-function handleLexicalStatReadFailure(params) {
-    if (handleLexicalLstatFailure({
-        error: params.error,
-        state: params.state,
-        missingFromIndex: params.missingFromIndex,
-        rootCanonicalPath: params.rootCanonicalPath,
-        resolveParams: params.resolveParams,
-        absolutePath: params.absolutePath,
-    })) {
+function handleLexicalStatReadFailure(context, error, missingFromIndex) {
+    if (handleLexicalLstatFailure(context, error, missingFromIndex)) {
         return null;
     }
-    throw params.error;
+    throw error;
 }
-function handleLexicalStatDisposition(params) {
+function handleLexicalStatDisposition(context, params) {
     if (!params.isSymbolicLink) {
-        advanceCanonicalCursorForSegment({
-            state: params.state,
-            segment: params.segment,
-            rootCanonicalPath: params.rootCanonicalPath,
-            params: params.resolveParams,
-            absolutePath: params.absolutePath,
-        });
+        advanceCanonicalCursorForSegment(context, params.segment);
         return "continue";
     }
-    if (params.state.allowFinalSymlink && params.isLast) {
-        params.state.preserveFinalSymlink = true;
-        advanceCanonicalCursorForSegment({
-            state: params.state,
-            segment: params.segment,
-            rootCanonicalPath: params.rootCanonicalPath,
-            params: params.resolveParams,
-            absolutePath: params.absolutePath,
-        });
+    if (context.resolveParams.rejectSymlinks === true && params.isLast) {
+        throw new FsSafeError("symlink", "symlink path component not allowed");
+    }
+    if (context.state.allowFinalSymlink && params.isLast) {
+        context.state.preserveFinalSymlink = true;
+        advanceCanonicalCursorForSegment(context, params.segment);
         return "break";
     }
     return "resolve-link";
 }
-function applyResolvedSymlinkHop(params) {
-    if (!isPathInside(params.rootCanonicalPath, params.linkCanonical)) {
+function applyResolvedSymlinkHop(context, linkCanonical) {
+    if (!isPathInside(context.rootCanonicalPath, linkCanonical)) {
         throw symlinkEscapeError({
-            boundaryLabel: params.boundaryLabel,
-            rootCanonicalPath: params.rootCanonicalPath,
-            symlinkPath: params.state.lexicalCursor,
+            boundaryLabel: context.resolveParams.boundaryLabel,
+            rootCanonicalPath: context.rootCanonicalPath,
+            symlinkPath: context.state.lexicalCursor,
         });
     }
-    params.state.canonicalCursor = params.linkCanonical;
-    params.state.lexicalCursor = params.linkCanonical;
+    context.state.canonicalCursor = linkCanonical;
+    context.state.lexicalCursor = linkCanonical;
 }
-function readLexicalStat(params) {
+function readLexicalStat(context, params) {
     try {
-        const stat = params.read(params.state.lexicalCursor);
+        const stat = params.read(context.state.lexicalCursor);
         if (isPromiseLike(stat)) {
-            return Promise.resolve(stat).catch((error) => handleLexicalStatReadFailure({ ...params, error }));
+            return Promise.resolve(stat).catch((error) => handleLexicalStatReadFailure(context, error, params.missingFromIndex));
         }
         return stat;
     }
     catch (error) {
-        return handleLexicalStatReadFailure({ ...params, error });
+        return handleLexicalStatReadFailure(context, error, params.missingFromIndex);
     }
 }
-function resolveAndApplySymlinkHop(params) {
-    const linkCanonical = params.resolveLinkCanonical(params.state.lexicalCursor);
+function resolveAndApplySymlinkHop(context, params) {
+    const linkCanonical = params.resolveLinkCanonical(context.state.lexicalCursor);
     if (isPromiseLike(linkCanonical)) {
-        return Promise.resolve(linkCanonical).then((value) => applyResolvedSymlinkHop({
-            state: params.state,
-            linkCanonical: value,
-            rootCanonicalPath: params.rootCanonicalPath,
-            boundaryLabel: params.boundaryLabel,
-        }));
-    }
-    applyResolvedSymlinkHop({
-        state: params.state,
-        linkCanonical,
-        rootCanonicalPath: params.rootCanonicalPath,
-        boundaryLabel: params.boundaryLabel,
-    });
+        return Promise.resolve(linkCanonical).then((value) => {
+            applyResolvedSymlinkHop(context, value);
+        });
+    }
+    applyResolvedSymlinkHop(context, linkCanonical);
 }
-function applyParentTraversalStep(params) {
-    params.state.lexicalCursor = path.resolve(params.state.lexicalCursor, "..");
-    advanceCanonicalCursorForSegment({
-        state: params.state,
-        segment: "..",
-        rootCanonicalPath: params.rootCanonicalPath,
-        params: params.resolveParams,
-        absolutePath: params.absolutePath,
-    });
+function applyParentTraversalStep(context) {
+    context.state.lexicalCursor = path.resolve(context.state.lexicalCursor, "..");
+    advanceCanonicalCursorForSegment(context, "..");
 }
 function* iterateLexicalTraversal(state) {
     for (let idx = 0; idx < state.segments.length; idx += 1) {
@@ -268,32 +270,22 @@ function* iterateLexicalTraversal(state) {
     }
 }
 async function resolveRootPathLexicalAsync(params) {
-    const state = createLexicalTraversalState(params);
-    const sharedStepParams = {
-        state,
-        rootCanonicalPath: params.rootCanonicalPath,
-        resolveParams: params.params,
-        absolutePath: params.absolutePath,
-    };
+    const context = createLexicalTraversalContext(params);
+    const { state } = context;
     for (const { idx, segment, isLast } of iterateLexicalTraversal(state)) {
         if (segment === "..") {
-            applyParentTraversalStep({
-                ...sharedStepParams,
-                resolveParams: params.params,
-            });
+            applyParentTraversalStep(context);
             continue;
         }
         state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        const stat = await readLexicalStat({
-            ...sharedStepParams,
+        const stat = await readLexicalStat(context, {
             missingFromIndex: idx,
             read: (cursor) => fsp.lstat(cursor),
         });
         if (!stat) {
             break;
         }
-        const disposition = handleLexicalStatDisposition({
-            ...sharedStepParams,
+        const disposition = handleLexicalStatDisposition(context, {
             isSymbolicLink: stat.isSymbolicLink(),
             segment,
             isLast,
@@ -304,41 +296,29 @@ async function resolveRootPathLexicalAsync(params) {
         if (disposition === "break") {
             break;
         }
-        await resolveAndApplySymlinkHop({
-            state,
-            rootCanonicalPath: params.rootCanonicalPath,
-            boundaryLabel: params.params.boundaryLabel,
+        await resolveAndApplySymlinkHop(context, {
             resolveLinkCanonical: (cursor) => resolveSymlinkHopPath(cursor),
         });
+        if (context.resolveParams.rejectSymlinks === true) {
+            throw new FsSafeError("symlink", "symlink path component not allowed");
+        }
     }
     const kind = await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
-    return finalizeLexicalResolution({
-        ...params,
-        state,
-        kind,
-    });
+    return finalizeLexicalResolution(context, kind);
 }
 function resolveRootPathLexicalSync(params) {
-    const state = createLexicalTraversalState(params);
+    const context = createLexicalTraversalContext(params);
+    const { state } = context;
     for (let idx = 0; idx < state.segments.length; idx += 1) {
         const segment = state.segments[idx] ?? "";
         const isLast = idx === state.segments.length - 1;
         if (segment === "..") {
-            applyParentTraversalStep({
-                state,
-                rootCanonicalPath: params.rootCanonicalPath,
-                resolveParams: params.params,
-                absolutePath: params.absolutePath,
-            });
+            applyParentTraversalStep(context);
             continue;
         }
         state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        const maybeStat = readLexicalStat({
-            state,
+        const maybeStat = readLexicalStat(context, {
             missingFromIndex: idx,
-            rootCanonicalPath: params.rootCanonicalPath,
-            resolveParams: params.params,
-            absolutePath: params.absolutePath,
             read: (cursor) => fs.lstatSync(cursor),
         });
         if (isPromiseLike(maybeStat)) {
@@ -348,14 +328,10 @@ function resolveRootPathLexicalSync(params) {
         if (!stat) {
             break;
         }
-        const disposition = handleLexicalStatDisposition({
-            state,
+        const disposition = handleLexicalStatDisposition(context, {
             isSymbolicLink: stat.isSymbolicLink(),
             segment,
             isLast,
-            rootCanonicalPath: params.rootCanonicalPath,
-            resolveParams: params.params,
-            absolutePath: params.absolutePath,
         });
         if (disposition === "continue") {
             continue;
@@ -363,22 +339,18 @@ function resolveRootPathLexicalSync(params) {
         if (disposition === "break") {
             break;
         }
-        const maybeApplied = resolveAndApplySymlinkHop({
-            state,
-            rootCanonicalPath: params.rootCanonicalPath,
-            boundaryLabel: params.params.boundaryLabel,
+        const maybeApplied = resolveAndApplySymlinkHop(context, {
             resolveLinkCanonical: (cursor) => resolveSymlinkHopPathSync(cursor),
         });
         if (isPromiseLike(maybeApplied)) {
             throw new Error("Unexpected async symlink resolution");
         }
+        if (context.resolveParams.rejectSymlinks === true) {
+            throw new FsSafeError("symlink", "symlink path component not allowed");
+        }
     }
     const kind = getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
-    return finalizeLexicalResolution({
-        ...params,
-        state,
-        kind,
-    });
+    return finalizeLexicalResolution(context, kind);
 }
 function resolveCanonicalOutsideLexicalPath(params) {
     return params.outsideLexicalCanonicalPath ?? params.absolutePath;
@@ -549,36 +521,3 @@ function pathEscapeError(params) {
 function symlinkEscapeError(params) {
     return new Error(`Symlink escapes ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.symlinkPath)}`);
 }
-function shortPath(value) {
-    const home = os.homedir();
-    if (value.startsWith(home)) {
-        return `~${value.slice(home.length)}`;
-    }
-    return value;
-}
-async function resolveSymlinkHopPath(symlinkPath) {
-    try {
-        return path.resolve(await fsp.realpath(symlinkPath));
-    }
-    catch (error) {
-        if (!isNotFoundPathError(error)) {
-            throw error;
-        }
-        const linkTarget = await fsp.readlink(symlinkPath);
-        const linkAbsolute = path.resolve(path.dirname(symlinkPath), linkTarget);
-        return resolvePathViaExistingAncestor(linkAbsolute);
-    }
-}
-function resolveSymlinkHopPathSync(symlinkPath) {
-    try {
-        return path.resolve(fs.realpathSync(symlinkPath));
-    }
-    catch (error) {
-        if (!isNotFoundPathError(error)) {
-            throw error;
-        }
-        const linkTarget = fs.readlinkSync(symlinkPath);
-        const linkAbsolute = path.resolve(path.dirname(symlinkPath), linkTarget);
-        return resolvePathViaExistingAncestorSync(linkAbsolute);
-    }
-}

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

@@ -1 +1 @@
-{"version":3,"file":"root-walk.d.ts","sourceRoot":"","sources":["../src/root-walk.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,oBAAoB,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,8BAA8B,GAAG,OAAO,GAAG,iBAAiB,CAAC;AACzE,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,MAAM,GAAG,cAAc,CAAC;AAC5E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;AACnE,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAExF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACpD;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,yBAAyB,CAAC;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,qBAAqB,CAAC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;CACnD,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACnF,CAAC;AAqBF,wBAAuB,QAAQ,CAC7B,IAAI,EAAE,kBAAkB,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,aAAa,CAAC,CAgG/B"}
+{"version":3,"file":"root-walk.d.ts","sourceRoot":"","sources":["../src/root-walk.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,oBAAoB,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,8BAA8B,GAAG,OAAO,GAAG,iBAAiB,CAAC;AACzE,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,MAAM,GAAG,cAAc,CAAC;AAC5E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;AACnE,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAExF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACpD;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,yBAAyB,CAAC;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,qBAAqB,CAAC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;CACnD,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACnF,CAAC;AAqBF,wBAAuB,QAAQ,CAC7B,IAAI,EAAE,kBAAkB,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,aAAa,CAAC,CAsH/B"}

package/dist/root-walk.js

@@ -22,6 +22,17 @@ function limitEntry(relativePath) {
     return { relativePath, kind: "truncated", size: 0 };
 }
 export async function* walkRoot(root, relativePath, options) {
+    if (!["skip", "follow-within-root"].includes(options.symlinkPolicy)) {
+        throw new TypeError(`invalid root walk symlink policy: ${String(options.symlinkPolicy)}`);
+    }
+    if (options.limitBehavior !== undefined &&
+        !["truncate", "throw"].includes(options.limitBehavior)) {
+        throw new TypeError(`invalid root walk limit behavior: ${String(options.limitBehavior)}`);
+    }
+    if (options.onDirectoryError !== undefined &&
+        !["throw", "skip-and-report"].includes(options.onDirectoryError)) {
+        throw new TypeError(`invalid root walk directory error behavior: ${String(options.onDirectoryError)}`);
+    }
     const maxDepth = validateBudget("maxDepth", options.maxDepth);
     const maxEntries = validateBudget("maxEntries", options.maxEntries);
     const visitedDirectories = new Set();
@@ -49,6 +60,7 @@ export async function* walkRoot(root, relativePath, options) {
                 return;
             }
             visitedDirectories.add(resolvedDirectory.canonicalPath);
+            options.signal?.throwIfAborted();
             const listingDirectory = path
                 .relative(root.rootReal, resolvedDirectory.canonicalPath)
                 .split(path.sep)
@@ -56,11 +68,14 @@ export async function* walkRoot(root, relativePath, options) {
             entries = await root.list(listingDirectory, { withFileTypes: true });
         }
         catch (error) {
+            // Cancellation is never a recoverable directory read failure.
+            options.signal?.throwIfAborted();
             if ((options.onDirectoryError ?? "throw") === "throw")
                 throw error;
             yield { relativePath: directory, kind: "directory-error", size: 0, error };
             return;
         }
+        options.signal?.throwIfAborted();
         for (const entry of entries) {
             options.signal?.throwIfAborted();
             const child = directory

package/dist/safe-path-segment.d.ts

@@ -2,6 +2,8 @@ export type SafePathSegmentOptions = {
     allowDotPrefix?: boolean;
     label?: string;
 };
+export declare function isDriveRelativePath(value: string): boolean;
+export declare function assertNoDriveRelativePathSegments(value: string, label: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
 export declare function sanitizeSafePathSegment(value: string, fallback: string, options?: SafePathSegmentOptions): string;

package/dist/safe-path-segment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-path-segment.d.ts","sourceRoot":"","sources":["../src/safe-path-segment.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAcF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAaT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAUR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAWR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAeR"}
+{"version":3,"file":"safe-path-segment.d.ts","sourceRoot":"","sources":["../src/safe-path-segment.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtF;AAcD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAaT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAUR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAWR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAeR"}

package/dist/safe-path-segment.js

@@ -1,7 +1,19 @@
 import { FsSafeError } from "./errors.js";
 const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
 const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+// Windows treats "C:name" as relative to the drive's current directory even
+// though path.win32.isAbsolute() reports false.
+const DRIVE_RELATIVE_PREFIX = /^[A-Za-z]:(?![\\/])/;
 const HYPHEN_CHAR_CODE = 0x2d;
+export function isDriveRelativePath(value) {
+    return DRIVE_RELATIVE_PREFIX.test(value);
+}
+export function assertNoDriveRelativePathSegments(value, label) {
+    if (value.split("/").some(isDriveRelativePath)) {
+        throw new FsSafeError("invalid-path", `${label} must not contain a drive letter`);
+    }
+    return value;
+}
 function trimHyphenEdges(value) {
     let start = 0;
     let end = value.length;

package/dist/secret-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAqIF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAcpB;AAoID,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAyDF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAExF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYzF"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAoIF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAcpB;AAoID,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAkEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}