@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-boundary.js

@@ -0,0 +1,182 @@
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
+function windowsComparablePath(value, normalize) {
+    const original = normalize
+        ? path.win32.normalize(value.replaceAll("/", "\\"))
+        : value.replaceAll("/", "\\");
+    if (/^\\\\\?\\UNC\\/i.test(original)) {
+        return {
+            original,
+            comparison: `\\\\${original.slice(8)}`,
+            originalIndex: (comparisonIndex) => comparisonIndex + 6,
+        };
+    }
+    if (original.startsWith("\\\\?\\")) {
+        return {
+            original,
+            comparison: original.slice(4),
+            originalIndex: (comparisonIndex) => comparisonIndex + 4,
+        };
+    }
+    return { original, comparison: original, originalIndex: (comparisonIndex) => comparisonIndex };
+}
+function trimWindowsTrailingSeparators(value) {
+    const rootLength = path.win32.parse(value).root.length;
+    let end = value.length;
+    while (end > rootLength && value[end - 1] === "\\")
+        end -= 1;
+    return value.slice(0, end);
+}
+function trimWindowsLeadingSeparators(value) {
+    let start = 0;
+    while (value[start] === "\\")
+        start += 1;
+    return value.slice(start);
+}
+function exactWindowsRootPrefix(rootPath, candidatePath) {
+    const root = trimWindowsTrailingSeparators(rootPath.replaceAll("/", "\\"));
+    const candidate = candidatePath.replaceAll("/", "\\");
+    let relativePath;
+    if (candidate === root) {
+        relativePath = "";
+    }
+    else {
+        const rootWithSep = root.endsWith("\\") ? root : `${root}\\`;
+        if (!candidate.startsWith(rootWithSep))
+            return undefined;
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+    }
+    return {
+        admission: "exact",
+        candidateRootPath: root,
+        path: relativePath === "" ? root : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`,
+        relativePath,
+    };
+}
+function windowsRootPrefix(rootPath, candidatePath) {
+    const exact = exactWindowsRootPrefix(rootPath, candidatePath);
+    if (exact)
+        return exact;
+    const trusted = windowsComparablePath(rootPath, true);
+    const supplied = windowsComparablePath(candidatePath, false);
+    const root = trimWindowsTrailingSeparators(trusted.original);
+    const rootComparison = trimWindowsTrailingSeparators(trusted.comparison);
+    const candidate = supplied.comparison;
+    if (!path.win32.isAbsolute(supplied.original))
+        return undefined;
+    let relativePath;
+    let candidateRootPath;
+    let admission;
+    if (candidate === rootComparison) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "exact";
+    }
+    else if (candidate.toLowerCase() === rootComparison.toLowerCase()) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "identity";
+    }
+    else {
+        const rootWithSep = rootComparison.endsWith("\\") ? rootComparison : `${rootComparison}\\`;
+        const candidatePrefix = candidate.slice(0, rootWithSep.length);
+        if (candidatePrefix === rootWithSep) {
+            admission = "exact";
+        }
+        else if (candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()) {
+            admission = "identity";
+        }
+        else {
+            return undefined;
+        }
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+        candidateRootPath = supplied.original.slice(0, supplied.originalIndex(rootComparison.length));
+    }
+    const rebasedPath = relativePath === ""
+        ? root
+        : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`;
+    return { candidateRootPath, path: rebasedPath, relativePath, admission };
+}
+function exactRootIdentity(rootPath, expected) {
+    if (typeof expected?.dev === "bigint" && typeof expected.ino === "bigint") {
+        return { dev: expected.dev, ino: expected.ino };
+    }
+    const observed = inspectDirectoryIdentitySync(rootPath);
+    return { dev: observed.dev, ino: observed.ino };
+}
+/**
+ * Admit a path at a trusted directory boundary.
+ *
+ * On Windows, an exact structural prefix is allocation-only and performs no
+ * filesystem observation. A match which depends on case folding is accepted
+ * only when the candidate prefix names the exact trusted root object. Accepted
+ * paths are always returned under the trusted root spelling.
+ */
+export function admitPathInsideRoot(params) {
+    // Some platform-fallback tests intentionally spoof process.platform while
+    // retaining Node's POSIX path module. A single-slash absolute root remains
+    // unambiguously POSIX; double-slash and slash-backslash roots are reserved
+    // for the synthetic Windows namespace cases below.
+    const usesPosixBoundary = process.platform !== "win32" || (path.sep === "/" &&
+        params.rootPath.startsWith("/") &&
+        params.rootPath[1] !== "/" &&
+        params.rootPath[1] !== "\\");
+    if (usesPosixBoundary) {
+        if (params.rootPath.startsWith("/") &&
+            params.candidatePath.startsWith("/") &&
+            !params.candidatePath.includes("/..") &&
+            (params.candidatePath === params.rootPath ||
+                (params.candidatePath.startsWith(params.rootPath) &&
+                    (params.rootPath.endsWith("/") || params.candidatePath[params.rootPath.length] === "/")))) {
+            const relativeStart = params.rootPath.endsWith("/")
+                ? params.rootPath.length
+                : params.rootPath.length + 1;
+            return {
+                admission: "exact",
+                path: params.candidatePath,
+                relativePath: params.candidatePath === params.rootPath
+                    ? ""
+                    : params.candidatePath.slice(relativeStart),
+            };
+        }
+        const root = path.resolve(params.rootPath);
+        const candidate = path.resolve(params.candidatePath);
+        const relativePath = path.relative(root, candidate);
+        if (isPathRelativeEscape(relativePath))
+            return undefined;
+        return { path: candidate, relativePath: relativePath === "." ? "" : relativePath, admission: "exact" };
+    }
+    const match = windowsRootPrefix(params.rootPath, params.candidatePath);
+    if (!match)
+        return undefined;
+    const admitted = () => ({
+        admission: match.admission,
+        path: match.path,
+        relativePath: match.relativePath,
+    });
+    if (match.admission === "exact")
+        return admitted();
+    const cached = params.identityCache?.get(match.candidateRootPath);
+    if (cached !== undefined)
+        return cached ? admitted() : undefined;
+    try {
+        const expected = exactRootIdentity(params.rootPath, params.rootIdentity);
+        const candidateRootPath = params.resolveCandidateRoot
+            ? realpathSync.native(match.candidateRootPath)
+            : match.candidateRootPath;
+        if (params.inspectCandidateRoot) {
+            params.inspectCandidateRoot(candidateRootPath, expected);
+        }
+        else {
+            inspectDirectoryIdentitySync(candidateRootPath, expected);
+        }
+        params.identityCache?.set(match.candidateRootPath, true);
+        return admitted();
+    }
+    catch {
+        params.identityCache?.set(match.candidateRootPath, false);
+        return undefined;
+    }
+}

package/dist/root-context.d.ts

@@ -1,5 +1,8 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard, type DirectoryObservationGuard } from "./directory-guard.js";
 export type RootContext = {
     rootDir: string;
+    rootGuard?: AsyncDirectoryGuard<BigIntStats>;
     rootIdentity: {
         dev: number;
         ino: number;
@@ -16,7 +19,15 @@ export declare function assertValidRootDestinationPath(relativePath: string): vo
 export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
 export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
 export declare function rootRelativeReadPath(root: RootContext, filePath: string): string;
-export declare function assertRootIdentityCurrent(root: RootContext): Promise<void>;
+export declare function assertRootIdentityCurrentSync(root: RootContext, observe?: (stat: fs.BigIntStats) => void): void;
+export declare function assertRootIdentityCurrent(root: RootContext, observe?: (stat: fs.BigIntStats) => void): Promise<void>;
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export declare function createRootObservationGuard(root: RootContext): Promise<DirectoryObservationGuard | undefined>;
 export declare function resolvePathInRoot(root: RootContext, relativePath: string, options?: {
     aliasErrorCode?: "outside-workspace" | "path-alias";
     allowFinalSymlink?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAetF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBhF;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhF;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqDtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC/B,MAAM,sBAAsB,CAAC;AAuB9B,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAOtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiC9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyBhF;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,GACvC,IAAI,CAmBN;AAED,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,GACvC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAYhD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuEtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}

package/dist/root-context.js

@@ -1,18 +1,24 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { extendDirectoryObservationGuard, inspectDirectoryIdentitySync, inspectDirectoryObservationSync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
 import { realpathSync } from "./realpath.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function hasExactRootIdentity(identity) {
+    return typeof identity.dev === "bigint" && typeof identity.ino === "bigint";
+}
 export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
 export function assertValidRootRelativePath(relativePath) {
     assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
+    assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
 }
 export function assertValidRootDestinationPath(relativePath) {
     assertValidRootRelativePath(relativePath);
@@ -26,29 +32,42 @@ const WINDOWS_PARENT_COMPONENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export async function expandRelativePathWithHome(relativePath) {
     const homeOnly = relativePath === "~";
     const homePrefix = relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"));
-    if (!homeOnly && !homePrefix)
+    if (!homeOnly && !homePrefix) {
+        assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
         return relativePath;
+    }
     const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    assertNoWindowsPathAlias(rawHome, "filesystem", "home path uses a Windows filesystem namespace alias");
     if (cachedHomePath?.raw !== rawHome) {
         let realHome = rawHome;
         try {
-            realHome = realpathSync.native(rawHome);
+            realHome = realpathSync.native(pathForWindowsFilesystem(rawHome));
         }
         catch {
             // If the home dir cannot be canonicalized, keep lexical expansion behavior.
         }
         cachedHomePath = { raw: rawHome, real: realHome };
     }
-    return homeOnly ? cachedHomePath.real : `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
+    if (homeOnly) {
+        assertNoWindowsPathAlias(cachedHomePath.real, "filesystem", "home path uses a Windows filesystem namespace alias");
+        return cachedHomePath.real;
+    }
+    const expanded = `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    return expanded;
 }
 export async function resolveRootContext(rootDir) {
     assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
-    const lexicalRoot = path.resolve(rootDir);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
+    const lexicalRoot = resolvePathPreservingWindowsRoot(rootDir);
+    assertNoWindowsPathAlias(lexicalRoot, "filesystem", "root dir uses a Windows filesystem namespace alias");
     let rootReal;
+    let rootStat;
     let rootIdentity;
     try {
-        rootReal = realpathSync.native(rootDir);
-        const rootStat = await inspectFileIdentity(() => {
+        rootReal = realpathSync.native(pathForWindowsFilesystem(rootDir));
+        assertNoWindowsPathAlias(rootReal, "filesystem", "canonical root path uses a Windows filesystem namespace alias");
+        rootStat = await inspectFileIdentity(() => {
             const stat = fs.statSync(rootReal, { bigint: true });
             if (!stat.isDirectory())
                 throw new FsSafeError("invalid-path", "root dir is not a directory");
@@ -67,6 +86,7 @@ export async function resolveRootContext(rootDir) {
     }
     return {
         rootDir: lexicalRoot,
+        rootGuard: { dir: rootReal, realPath: rootReal, stat: rootStat },
         rootIdentity,
         rootReal,
         rootWithSep: ensureTrailingSep(rootReal),
@@ -77,11 +97,21 @@ export function rootRelativeReadPath(root, filePath) {
     if (!absoluteInput)
         return filePath;
     const raw = process.platform === "win32" ? filePath.replaceAll("/", path.sep) : filePath;
-    for (const base of [root.rootDir, root.rootReal]) {
+    const bases = root.rootDir === root.rootReal ? [root.rootReal] : [root.rootDir, root.rootReal];
+    for (const base of bases) {
+        if (process.platform === "win32") {
+            const admitted = admitPathInsideRoot({
+                rootPath: base,
+                candidatePath: raw,
+                rootIdentity: root.rootIdentity,
+                resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
+            });
+            if (admitted)
+                return admitted.relativePath;
+            continue;
+        }
         const prefix = ensureTrailingSep(base);
-        const matches = process.platform === "win32"
-            ? raw.slice(0, prefix.length).toLowerCase() === prefix.toLowerCase()
-            : raw.startsWith(prefix);
+        const matches = raw.startsWith(prefix);
         if (matches) {
             let start = prefix.length;
             while (raw[start] === path.sep)
@@ -91,11 +121,12 @@ export function rootRelativeReadPath(root, filePath) {
     }
     return raw;
 }
-export async function assertRootIdentityCurrent(root) {
+export function assertRootIdentityCurrentSync(root, observe) {
     let current;
     try {
         if (typeof root.rootIdentity.dev === "bigint" && typeof root.rootIdentity.ino === "bigint") {
-            await inspectDirectoryIdentity(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            const stat = inspectDirectoryIdentitySync(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            observe?.(stat);
             return;
         }
         current = fs.lstatSync(root.rootReal);
@@ -109,11 +140,36 @@ export async function assertRootIdentityCurrent(root) {
         throw rootPathChangedError();
     }
 }
+export async function assertRootIdentityCurrent(root, observe) {
+    assertRootIdentityCurrentSync(root, observe);
+}
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export async function createRootObservationGuard(root) {
+    const rootIdentity = root.rootIdentity;
+    if (!hasExactRootIdentity(rootIdentity)) {
+        await assertRootIdentityCurrent(root);
+        return undefined;
+    }
+    try {
+        const observed = await inspectDirectoryObservationSync(root.rootReal, rootIdentity);
+        return extendDirectoryObservationGuard(observed, root.rootReal, root.rootReal);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
+    }
+}
 export async function resolvePathInRoot(root, relativePath, options) {
     assertValidRootRelativePath(relativePath);
     await assertRootIdentityCurrent(root);
     const expanded = await expandRelativePathWithHome(relativePath);
-    let resolved = path.resolve(root.rootWithSep, expanded);
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    let resolved = resolvePathFromBasePreservingWindowsRoot(root.rootWithSep, expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", "resolved path uses a Windows filesystem namespace alias");
     if (!options?.resolveCanonical && !isPathInside(root.rootWithSep, resolved)) {
         throw outsideWorkspaceError();
     }
@@ -123,11 +179,13 @@ export async function resolvePathInRoot(root, relativePath, options) {
     const rawAbsolutePath = path.isAbsolute(expanded)
         ? expanded
         : `${root.rootWithSep}${expanded}`;
+    assertNoWindowsPathAlias(rawAbsolutePath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
     try {
         const resolution = {
             absolutePath: rawAbsolutePath,
             rootPath: root.rootReal,
             rootCanonicalPath: root.rootReal,
+            rootIdentity: root.rootIdentity,
             boundaryLabel: "root",
             policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
             rejectSymlinks: options?.rejectSymlinks,
@@ -142,8 +200,23 @@ export async function resolvePathInRoot(root, relativePath, options) {
                 throw new FsSafeError("path-alias", "parent traversal resolves differently through a symlink");
             }
         }
-        if (options?.resolveCanonical)
+        if (options?.resolveCanonical) {
             resolved = checked.canonicalPath;
+        }
+        else {
+            // resolveRootPath preserves ordinary caller spelling as part of its
+            // public receipt. Re-admit the exact normalized spelling before it is
+            // reused for Root I/O: on a case-sensitive Windows directory it may
+            // otherwise name a distinct case-folded sibling after raw traversal.
+            const admitted = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: checked.absolutePath,
+                rootIdentity: root.rootIdentity,
+            });
+            if (!admitted)
+                throw outsideWorkspaceError();
+            resolved = admitted.path;
+        }
     }
     catch (error) {
         if (error instanceof FsSafeError && error.code === "symlink") {

package/dist/root-directory-creation.d.ts

@@ -0,0 +1,13 @@
+import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { RootContext } from "./root-context.js";
+/**
+ * Complete the common Root.mkdir case with one exact existing parent. This is
+ * optional evidence: every uncertain probe returns to the ordered root walk.
+ */
+export declare function tryMkdirAtExactParent(root: RootContext, targetPath: string, mutationAdmission: PinnedWriteMutationAdmission): Promise<boolean>;
+export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission): Promise<string>;
+export declare function mkdirPathFallback(root: RootContext, resolved: {
+    rootReal: string;
+    resolved: string;
+}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission): Promise<void>;
+//# sourceMappingURL=root-directory-creation.d.ts.map

package/dist/root-directory-creation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-directory-creation.d.ts","sourceRoot":"","sources":["../src/root-directory-creation.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoDrD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,4BAA4B,GAC9C,OAAO,CAAC,OAAO,CAAC,CAoGlB;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,iBAAiB,CAAC,EAAE,4BAA4B,GAC/C,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,cAAc,UAAQ,EACtB,iBAAiB,CAAC,EAAE,4BAA4B,GAC/C,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/root-directory-creation.js

@@ -0,0 +1,212 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
+import { hasNodeErrorCode } from "./path.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function mutationWalkOptions(mutationAdmission, operationTarget, assertBeforeMutation) {
+    const session = assertBeforeMutation === undefined
+        ? mutationAdmission.beginSharedParentWalk?.()
+        : undefined;
+    return {
+        dispose: () => session?.dispose(),
+        options: {
+            rejectSymlinks: mutationAdmission.rejectParentSymlinks,
+            revalidateParentAfterBeforeComponent: true,
+            retainedTargetPath: session?.retainedTargetPath,
+            synchronousAuthorizationIncludesFence: session !== undefined,
+            afterCreateComponent: session?.advanceCreatedDirectory,
+            beforeCreateComponent: (componentPath, prospectiveDirectory, retainedTargetPath, parent) => {
+                const targetPath = retainedTargetPath ?? operationTarget(prospectiveDirectory);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: componentPath,
+                    phase: "parent-create",
+                });
+                return session?.tryAuthorizeAtParent(request, parent) ??
+                    (session?.authorize(request) ?? mutationAdmission.authorize(request));
+            },
+            beforeUseComponent: async (_componentPath, prospectiveDirectory, retainedTargetPath) => {
+                const targetPath = retainedTargetPath ?? operationTarget(prospectiveDirectory);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                await (session?.authorize(request) ?? mutationAdmission.authorize(request));
+            },
+        },
+    };
+}
+/**
+ * Complete the common Root.mkdir case with one exact existing parent. This is
+ * optional evidence: every uncertain probe returns to the ordered root walk.
+ */
+export async function tryMkdirAtExactParent(root, targetPath, mutationAdmission) {
+    if (getFsSafeTestHooks()?.beforeRootFallbackMutation)
+        return false;
+    if (typeof root.rootIdentity.dev !== "bigint" ||
+        typeof root.rootIdentity.ino !== "bigint" ||
+        root.rootIdentity.dev === 0n || root.rootIdentity.ino === 0n)
+        return false;
+    const rootIdentity = Object.freeze({
+        dev: root.rootIdentity.dev,
+        ino: root.rootIdentity.ino,
+    });
+    const session = mutationAdmission.beginSharedParentWalk?.();
+    if (!session)
+        return false;
+    try {
+        if (path.resolve(session.retainedTargetPath) !== path.resolve(targetPath))
+            return false;
+        const parentPath = path.dirname(targetPath);
+        let parentGuard;
+        try {
+            parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+        }
+        catch {
+            return false;
+        }
+        try {
+            fsSync.lstatSync(targetPath, { bigint: true });
+            return false;
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                return false;
+        }
+        const admittedParent = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: parentPath,
+            rootIdentity,
+        });
+        if (admittedParent?.admission !== "exact" || admittedParent.path !== parentPath ||
+            parentGuard.realPath !== parentPath)
+            return false;
+        await session.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+        try {
+            fsSync.lstatSync(targetPath, { bigint: true });
+            return false;
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                return false;
+        }
+        assertSyncDirectoryGuard(parentGuard);
+        const createAdmission = session.tryAuthorizeAtParent(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent-create",
+        }), checkedMutationDirectory(parentPath, parentGuard.realPath, parentGuard.stat));
+        if (!createAdmission)
+            return false;
+        try {
+            await fs.mkdir(targetPath);
+        }
+        catch (error) {
+            if (hasNodeErrorCode(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        const observeCreated = async () => {
+            const childGuard = await createAsyncDirectoryGuard(targetPath, { bigint: true });
+            const parentAfter = inspectDirectoryIdentitySync(parentPath, parentGuard.stat);
+            assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+            const admittedChild = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: childGuard.realPath,
+                rootIdentity,
+            });
+            if (childGuard.realPath !== targetPath || childGuard.dir !== targetPath ||
+                admittedChild?.admission !== "exact" || admittedChild.path !== targetPath) {
+                throw new FsSafeError("path-mismatch", "created directory changed during operation");
+            }
+            return { childGuard, parentAfter };
+        };
+        try {
+            const created = await observeCreated();
+            if (session.advanceCreatedDirectory(Object.freeze({
+                admission: createAdmission,
+                parent: checkedMutationDirectory(parentPath, parentGuard.realPath, created.parentAfter),
+                child: checkedMutationDirectory(targetPath, created.childGuard.realPath, created.childGuard.stat),
+            })))
+                return true;
+        }
+        catch {
+            // Post-create observations are optional receipt evidence. The directory
+            // was already created, so renew ordered admission without a second mkdir.
+        }
+        await session.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+        assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+        assertFinalSymlinkRejected(targetPath, true);
+        const refreshed = await observeCreated();
+        await assertAsyncDirectoryGuard(parentGuard);
+        await assertAsyncDirectoryGuard(refreshed.childGuard);
+        assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+        return true;
+    }
+    finally {
+        session.dispose();
+    }
+}
+export async function prepareRootWriteTarget(root, targetPath, assertBeforeMutation, mutationAdmission) {
+    const basename = path.basename(targetPath);
+    const baseParams = {
+        rootReal: root.rootReal,
+        rootIdentity: root.rootIdentity,
+        targetPath: path.dirname(targetPath),
+        assertBeforeMutation,
+    };
+    const mutationWalk = mutationAdmission
+        ? mutationWalkOptions(mutationAdmission, (prospectiveParent) => path.join(prospectiveParent, basename), assertBeforeMutation)
+        : undefined;
+    let parentPath;
+    try {
+        parentPath = await mkdirPathComponentsWithGuards(mutationWalk ? {
+            ...baseParams,
+            ...mutationWalk.options,
+        } : baseParams);
+    }
+    finally {
+        mutationWalk?.dispose();
+    }
+    // Continue through the guarded walk's real parent instead of re-entering
+    // the original path through a symlinked component.
+    return path.join(parentPath, basename);
+}
+export async function mkdirPathFallback(root, resolved, assertBeforeMutation, rejectSymlinks = false, mutationAdmission) {
+    const baseParams = {
+        rootReal: resolved.rootReal, targetPath: resolved.resolved, assertBeforeMutation,
+        rootIdentity: root.rootIdentity,
+        rejectSymlinks,
+        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
+    };
+    const mutationWalk = mutationAdmission
+        ? mutationWalkOptions(mutationAdmission, (prospectiveDirectory) => prospectiveDirectory, assertBeforeMutation)
+        : undefined;
+    try {
+        await mkdirPathComponentsWithGuards(mutationWalk ? {
+            ...baseParams,
+            ...mutationWalk.options,
+            rejectSymlinks: rejectSymlinks || mutationAdmission.rejectParentSymlinks,
+        } : baseParams);
+    }
+    finally {
+        mutationWalk?.dispose();
+    }
+}