@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/output.js

@@ -7,6 +7,7 @@ import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./fil
 import { isPathInside } from "./path.js";
 import { root } from "./root.js";
 import { tempFile } from "./temp-target.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const NON_PORTABLE_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
 function tempFileNameForTarget(targetPath, fallbackFileName) {
     const fallback = sanitizeUntrustedFileName(fallbackFileName ?? "output.bin", "output.bin");
@@ -51,8 +52,12 @@ function assertFileTargetPath(targetPath) {
 }
 export async function writeExternalFileWithinRoot(options) {
     const maxBytes = normalizeMaxBytes(options.maxBytes);
-    const targetRoot = await root(options.rootDir);
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "output root uses a Windows filesystem namespace alias");
     const requestedTargetPath = options.path;
+    assertNoWindowsPathAlias(path.dirname(requestedTargetPath), "filesystem", "output target parent uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
+    const targetRoot = await root(rootDir);
     if (requestedTargetPath.length === 0) {
         throw new FsSafeError("invalid-path", "target path is required");
     }
@@ -64,7 +69,9 @@ export async function writeExternalFileWithinRoot(options) {
     });
     assertFileTargetPath(rawTargetPath);
     const targetPath = sanitizedTargetPath(rawTargetPath, options.fallbackFileName);
+    assertNoWindowsPathAlias(targetPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = await targetRoot.resolve(targetPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     if (options.staging === "sibling") {
         const parentPath = path.dirname(targetPath);
         if (parentPath !== ".") {
@@ -74,7 +81,7 @@ export async function writeExternalFileWithinRoot(options) {
         const result = await writeExternalFileViaSibling({
             finalPath: siblingFinalPath,
             write: options.write,
-            producerIsolation: options.producerIsolation,
+            producerIsolation,
             fallbackFileName: options.fallbackFileName,
             maxBytes,
             mode: options.mode,
@@ -99,7 +106,7 @@ export async function writeExternalFileWithinRoot(options) {
         await staged.cleanup();
     }
 }
-function buildSiblingTempPath(targetPath, fallbackFileName) {
+function buildSiblingTempName(targetPath, fallbackFileName) {
     const prefix = `.fs-safe-output-${process.pid}-${randomUUID()}-`;
     const suffix = ".part";
     const safeTail = fitFileNameToPortableComponent({
@@ -107,12 +114,15 @@ function buildSiblingTempPath(targetPath, fallbackFileName) {
         fileName: tempFileNameForTarget(targetPath, fallbackFileName),
         suffix,
     });
-    return path.join(path.dirname(targetPath), `${prefix}${safeTail}${suffix}`);
+    return `${prefix}${safeTail}${suffix}`;
 }
 async function writeExternalFileViaSibling(params) {
+    assertNoWindowsPathAlias(params.finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = path.resolve(params.finalPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const { result } = await writeCallbackSibling({
-        tempPath: buildSiblingTempPath(finalPath, params.fallbackFileName),
+        tempDir: path.dirname(finalPath),
+        tempName: buildSiblingTempName(finalPath, params.fallbackFileName),
         write: params.write,
         producerIsolation: params.producerIsolation,
         resolveFinalPath: () => finalPath,

package/dist/overwrite-file-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overwrite-file-handle.d.ts","sourceRoot":"","sources":["../src/overwrite-file-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,4FAA4F;AAC5F,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAoCf"}
+{"version":3,"file":"overwrite-file-handle.d.ts","sourceRoot":"","sources":["../src/overwrite-file-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,4FAA4F;AAC5F,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/overwrite-file-handle.js

@@ -4,6 +4,10 @@ import { readFileWindowFully } from "./positional-read.js";
 import { writeAllToFile } from "./write-file-handle.js";
 /** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
 export async function overwriteFileHandle(handle, data, options = {}) {
+    // Snapshot caller-owned admission before the first await. Preserve the
+    // former method-call receiver while preventing a later getter mutation from
+    // replacing authority after rollback preparation.
+    const beforeWrite = options.beforeWrite;
     const payload = data.subarray(0, data.byteLength);
     const payloadBytes = payload.byteLength;
     const stat = await handle.stat();
@@ -19,7 +23,7 @@ export async function overwriteFileHandle(handle, data, options = {}) {
     if (await readFileWindowFully(handle, originalPrefix, 0) !== prefixBytes) {
         throw new FsSafeError("read-failed", "file ended before overwrite rollback preparation completed");
     }
-    assertSynchronousCallbackResult(options.beforeWrite?.(), "beforeWrite");
+    assertSynchronousCallbackResult(beforeWrite === undefined ? undefined : Reflect.apply(beforeWrite, options, []), "beforeWrite");
     let prefixStarted = false;
     try {
         // Leave existing bytes intact until any additional storage has been written.

package/dist/owner-dacl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner-dacl.d.ts","sourceRoot":"","sources":["../src/owner-dacl.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,yBAAyB,EAAE,CAAC;CACnC,GACD;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B,CAAC;AAEN,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CA6BvE"}
+{"version":3,"file":"owner-dacl.d.ts","sourceRoot":"","sources":["../src/owner-dacl.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,yBAAyB,EAAE,CAAC;CACnC,GACD;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B,CAAC;AAEN,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAmCvE"}

package/dist/owner-dacl.js

@@ -1,9 +1,11 @@
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function readOwnerAndDacl(targetPath) {
     if (process.platform !== "win32") {
         return { status: "unsupported-platform", platform: process.platform };
     }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
     const native = getNativeBinding();
     if (!native) {
         throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require the matching optional native platform package; " +

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

@@ -1 +1 @@
-{"version":3,"file":"path-policy.d.ts","sourceRoot":"","sources":["../src/path-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB"}
+{"version":3,"file":"path-policy.d.ts","sourceRoot":"","sources":["../src/path-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAKxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB"}

package/dist/path-policy.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
 import { isNotFoundPathError } from "./path.js";
 import { shortPath } from "./error-detail.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
 export async function assertNoPathAliasEscape(params) {
     const resolved = await resolveRootPath({
@@ -25,9 +26,13 @@ export async function assertNoHardlinkedFinalPath(params) {
     if (params.allowFinalHardlinkForUnlink) {
         return;
     }
+    const filePath = params.filePath;
+    const root = params.root;
+    const boundaryLabel = params.boundaryLabel;
+    assertNoWindowsPathAlias(filePath);
     let stat;
     try {
-        stat = fs.statSync(params.filePath);
+        stat = fs.statSync(filePath);
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
@@ -39,6 +44,6 @@ export async function assertNoHardlinkedFinalPath(params) {
         return;
     }
     if (stat.nlink > 1) {
-        throw new Error(`Hardlinked path is not allowed under ${params.boundaryLabel} (${shortPath(params.root)}): ${shortPath(params.filePath)}`);
+        throw new Error(`Hardlinked path is not allowed under ${boundaryLabel} (${shortPath(root)}): ${shortPath(filePath)}`);
     }
 }

package/dist/path-prefix.d.ts

@@ -0,0 +1,7 @@
+export type ResolvedPathPrefix = {
+    readonly absolutePath: string;
+    readonly existingPath: string;
+    readonly unresolvedSegments: readonly string[];
+};
+export declare function resolvePathPrefixSync(input: string): ResolvedPathPrefix;
+//# sourceMappingURL=path-prefix.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path-prefix.d.ts","sourceRoot":"","sources":["../src/path-prefix.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD,CAAC;AAkBF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAsDvE"}

package/dist/path-prefix.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
+import { assertNoNulPathInput, hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { absolutePathWithRawSegments } from "./root-path-existing.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rawRoot(absolutePath) {
+    if (path.sep === "\\" && /^\\\\[?.]\\UNC\\/i.test(absolutePath)) {
+        // Node parses only the namespace prefix as the root of an extended UNC path.
+        const shareRoot = path.parse(`\\\\${absolutePath.slice(8)}`).root;
+        return absolutePath.slice(0, shareRoot.length + 6);
+    }
+    return path.parse(absolutePath).root;
+}
+function resolutionError(code, absolutePath) {
+    const detail = code === "ELOOP" ? "too many symbolic links" : "not a directory";
+    return Object.assign(new Error(`${code}: ${detail}, resolvePathPrefix ${formatErrorDetail(absolutePath)}`), {
+        code, syscall: "resolvePathPrefix", path: absolutePath,
+    });
+}
+export function resolvePathPrefixSync(input) {
+    assertNoNulPathInput(input);
+    const absolutePath = absolutePathWithRawSegments(input);
+    let resolved = rawRoot(absolutePath);
+    const remaining = absolutePath.slice(resolved.length).split(path.sep);
+    const visitedStates = new Set();
+    let symlinkHops = 0;
+    while (remaining.length > 0) {
+        const segment = remaining.shift();
+        if (segment === "")
+            continue;
+        if (segment === "." || segment === "..") {
+            const atRoot = resolved === rawRoot(resolved);
+            const lookup = segment === ".." && atRoot ? "." : segment;
+            // lstat(dir) does not test search permission, and realpath may erase dots.
+            const operationBase = pathForWindowsFilesystem(resolved);
+            fs.lstatSync(`${operationBase}${operationBase.endsWith(path.sep) ? "" : path.sep}${lookup}`, { bigint: true });
+            if (segment === ".." && !atRoot)
+                resolved = path.dirname(resolved);
+            continue;
+        }
+        const candidate = path.join(resolved, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(candidate, { bigint: true });
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                throw error;
+            return {
+                absolutePath,
+                existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)),
+                unresolvedSegments: [segment, ...remaining],
+            };
+        }
+        if (!stat.isSymbolicLink()) {
+            if (!stat.isDirectory() && remaining.length > 0)
+                throw resolutionError("ENOTDIR", absolutePath);
+            resolved = candidate;
+            continue;
+        }
+        const state = JSON.stringify([String(stat.dev), String(stat.ino), candidate, remaining]);
+        if (symlinkHops >= 64 || visitedStates.has(state))
+            throw resolutionError("ELOOP", absolutePath);
+        visitedStates.add(state);
+        symlinkHops++;
+        const target = fs.readlinkSync(candidate);
+        const rawTarget = path.sep === "\\" ? target.replaceAll("/", "\\") : target;
+        if (path.isAbsolute(rawTarget)) {
+            const targetRoot = rawRoot(rawTarget);
+            // A rooted Windows link target uses the link's drive/share, not cwd's.
+            resolved = path.sep === "\\" && targetRoot === "\\" ? rawRoot(resolved) : targetRoot;
+            remaining.unshift(...rawTarget.slice(targetRoot.length).split(path.sep));
+        }
+        else {
+            // A target's parent traversal applies after resolving its preceding links.
+            remaining.unshift(...rawTarget.split(path.sep));
+        }
+    }
+    return { absolutePath, existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)), unresolvedSegments: [] };
+}

package/dist/path-scope-lexical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-scope-lexical.d.ts","sourceRoot":"","sources":["../src/path-scope-lexical.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAUF,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,2BAA2B,EACnC,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAiB3D"}
+{"version":3,"file":"path-scope-lexical.d.ts","sourceRoot":"","sources":["../src/path-scope-lexical.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAUF,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,2BAA2B,EACnC,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA4B3D"}

package/dist/path-scope-lexical.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { isPathInside, isPathRelativeEscape } from "./path.js";
+import { hasWindowsPathAlias, resolvePathFromBasePreservingWindowsRoot } from "./windows-path-alias.js";
 function pathStaysWithinRoot(rootDir, candidatePath) {
     if (process.platform !== "win32") {
         return candidatePath !== rootDir && isPathInside(rootDir, candidatePath);
@@ -8,20 +9,29 @@ function pathStaysWithinRoot(rootDir, candidatePath) {
     return Boolean(relative) && !isPathRelativeEscape(relative);
 }
 export function resolvePathWithinNormalizedRoot(params, root) {
-    const raw = params.requestedPath.trim();
+    const requestedPath = params.requestedPath;
+    const defaultFileName = params.defaultFileName;
+    const scopeLabel = params.scopeLabel;
+    if (hasWindowsPathAlias(params.rootDir, "filesystem") ||
+        hasWindowsPathAlias(root, "filesystem") ||
+        hasWindowsPathAlias(requestedPath, "filesystem") ||
+        (defaultFileName !== undefined && hasWindowsPathAlias(defaultFileName, "filesystem"))) {
+        return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+    }
+    const raw = requestedPath.trim();
     if (!raw) {
-        if (!params.defaultFileName) {
+        if (!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}` };
+        const defaultPath = resolvePathFromBasePreservingWindowsRoot(root, defaultFileName);
+        if (hasWindowsPathAlias(defaultPath, "filesystem") || !pathStaysWithinRoot(root, defaultPath)) {
+            return { ok: false, error: `Invalid path: must stay within ${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}` };
+    const resolved = resolvePathFromBasePreservingWindowsRoot(root, raw);
+    if (hasWindowsPathAlias(resolved, "filesystem") || !pathStaysWithinRoot(root, resolved)) {
+        return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
     }
     return { ok: true, path: resolved };
 }

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

@@ -0,0 +1,7 @@
+export type PathSegmentRoute = Readonly<{
+    joined: string;
+    offsets: readonly number[];
+}>;
+export declare function createPathSegmentRoute(segments: readonly string[]): PathSegmentRoute;
+export declare function joinPathSegmentRoute(base: string, route: PathSegmentRoute, offset: number, tail?: string): string;
+//# sourceMappingURL=path-segment-route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path-segment-route.d.ts","sourceRoot":"","sources":["../src/path-segment-route.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CAAC,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAUpF;AAID,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAMR"}

package/dist/path-segment-route.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+export function createPathSegmentRoute(segments) {
+    const offsets = new Array(segments.length + 1);
+    let cursor = 0;
+    for (let index = 0; index < segments.length; index += 1) {
+        offsets[index] = cursor;
+        cursor += segments[index].length;
+        if (index + 1 < segments.length)
+            cursor += path.sep.length;
+    }
+    offsets[segments.length] = cursor;
+    return Object.freeze({ joined: segments.join(path.sep), offsets: Object.freeze(offsets) });
+}
+// Select the immutable suffix by character offset so callers perform at most
+// one path normalization without copying a shrinking segment array.
+export function joinPathSegmentRoute(base, route, offset, tail) {
+    const start = route.offsets[offset];
+    if (start === undefined)
+        throw new RangeError("path segment offset is outside the route");
+    const suffix = route.joined.slice(start);
+    if (suffix)
+        return tail === undefined ? path.join(base, suffix) : path.join(base, suffix, tail);
+    return tail === undefined ? base : path.join(base, tail);
+}

package/dist/path-suffix-aliases.d.ts

@@ -0,0 +1,10 @@
+export type ProbePathSuffixAliasesOptions = {
+    directory: string;
+    left: string;
+    right: string;
+    /** Synchronous caller policy for differing NFC pairs not equivalent under ASCII case folding. */
+    shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+/** Observe bounded missing suffix aliases; the caller owns caching and ambiguity policy. */
+export declare function probePathSuffixAliasesSync(options: ProbePathSuffixAliasesOptions): boolean | undefined;
+//# sourceMappingURL=path-suffix-aliases.d.ts.map

package/dist/path-suffix-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-suffix-aliases.d.ts","sourceRoot":"","sources":["../src/path-suffix-aliases.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1E,CAAC;AA6UF,4FAA4F;AAC5F,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,GAAG,SAAS,CA8CtG"}