@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/replace-file.js

@@ -2,20 +2,17 @@ import { randomUUID } from "node:crypto";
 import syncFs, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { assertDestinationHardlinkPolicy, assertDestinationHardlinkPolicySync, copyFallbackReplace, copyFallbackReplaceSync, } from "./replace-file-copy-fallback.js";
 import { applyDirectoryMode, applyDirectoryModeSync, syncDirectoryBestEffort, syncDirectoryBestEffortSync, writeTempFile, writeTempFileSync, } from "./replace-file-descriptor.js";
+import { inheritedRegularFileMode } from "./replace-file-mode.js";
 import { atomicExpectedContentHash, validateRenameIdentity, withAtomicRenameIdentityLock, withAtomicRenameIdentityLockSync, } from "./replace-file-rename-policy.js";
 import { AsyncAtomicTempOwner, SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
-function isRetryableRenameError(error) {
-    return error.code === "EBUSY";
-}
-function isPermissionRenameError(error) {
-    const code = error.code;
-    return code === "EPERM" || code === "EEXIST";
-}
+import { hasErrorCode, readErrorCode } from "./file-cleanup.js";
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         if (attempt > 0)
@@ -25,11 +22,12 @@ async function renameWithRetry(params) {
             return { method: "rename" };
         }
         catch (error) {
-            if (isRetryableRenameError(error) && attempt < params.maxRetries) {
+            const code = readErrorCode(error);
+            if (code === "EBUSY" && attempt < params.maxRetries) {
                 await sleep(params.baseDelayMs * 2 ** attempt);
                 continue;
             }
-            if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
+            if (params.copyFallbackOnPermissionError && (code === "EPERM" || code === "EEXIST")) {
                 await copyFallbackReplace({
                     fsModule: params.fsModule,
                     src: params.src,
@@ -56,11 +54,12 @@ function renameWithRetrySync(params) {
             return { method: "rename" };
         }
         catch (error) {
-            if (isRetryableRenameError(error) && attempt < params.maxRetries) {
+            const code = readErrorCode(error);
+            if (code === "EBUSY" && attempt < params.maxRetries) {
                 sleepSync(params.baseDelayMs * 2 ** attempt);
                 continue;
             }
-            if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
+            if (params.copyFallbackOnPermissionError && (code === "EPERM" || code === "EEXIST")) {
                 copyFallbackReplaceSync({
                     fsModule: params.fsModule,
                     src: params.src,
@@ -83,6 +82,7 @@ function validateReplaceFilePath(filePath) {
     if (!filePath || filePath.includes("\0")) {
         throw new Error("Atomic replace file path must be non-empty.");
     }
+    return admitStandalonePublicationPath(filePath, "atomic replace path uses a Windows filesystem namespace alias");
 }
 function validateRestoreOptions(options) {
     if (options.copyFallbackRestore !== "restore-original")
@@ -99,20 +99,25 @@ function buildReplaceTempPath(filePath, tempPrefix) {
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-replace", { label: "atomic replace temp prefix" });
     return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
 }
-async function resolveMode(options) {
+async function resolveMode(options, filePath) {
     const defaultMode = options.mode ?? 0o600;
     if (!options.preserveExistingMode) {
         return defaultMode;
     }
-    const stat = await (options.fileSystem?.promises ?? fs).stat(options.filePath).catch((error) => {
-        if (error.code === "ENOENT") {
-            return null;
+    const fsModule = options.fileSystem?.promises ?? fs;
+    let stat;
+    try {
+        stat = fsModule === fs ? syncFs.lstatSync(filePath) : await fsModule.lstat(filePath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return defaultMode;
         }
         throw error;
-    });
-    return stat ? stat.mode : defaultMode;
+    }
+    return stat ? inheritedRegularFileMode(stat) : defaultMode;
 }
-function resolveModeSync(options) {
+function resolveModeSync(options, filePath) {
     const defaultMode = options.mode ?? 0o600;
     if (!options.preserveExistingMode) {
         return defaultMode;
@@ -120,14 +125,14 @@ function resolveModeSync(options) {
     const fsModule = options.fileSystem ?? syncFs;
     let stat;
     try {
-        stat = fsModule.statSync(options.filePath);
+        stat = fsModule.lstatSync(filePath);
     }
     catch (error) {
-        if (error.code !== "ENOENT") {
+        if (!hasErrorCode(error, "ENOENT")) {
             throw error;
         }
     }
-    return stat ? stat.mode : defaultMode;
+    return stat ? inheritedRegularFileMode(stat) : defaultMode;
 }
 function missingFchmodSyncError() {
     return new TypeError("fileSystem.fchmodSync is required when mode, dirMode, or preserveExistingMode is specified");
@@ -137,33 +142,34 @@ export async function replaceFileAtomic(options) {
 }
 // Internal owner hook: keep directory durability inside publication verification and serialization.
 export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
-    const filePath = options.filePath;
-    validateReplaceFilePath(filePath);
+    const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
-    validateRenameIdentity(options.renameIdentity);
+    const renameIdentity = options.renameIdentity;
+    validateRenameIdentity(renameIdentity);
     return await serializePathWrite(path.resolve(filePath), async () => {
-        if (options.renameIdentity !== "verify-content-with-lock") {
-            return await replaceFileAtomicUnserialized(options, syncParent);
+        if (renameIdentity !== "verify-content-with-lock") {
+            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent);
         }
-        await (options.fileSystem?.promises ?? fs).mkdir(path.dirname(filePath), {
+        const fsModule = options.fileSystem?.promises ?? fs;
+        const dir = path.dirname(filePath);
+        await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, {
             recursive: true,
             mode: options.dirMode ?? 0o700,
         });
-        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, syncParent));
+        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent));
     });
 }
-async function replaceFileAtomicUnserialized(options, syncParent) {
-    const filePath = options.filePath;
+async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent) {
     const fsModule = options.fileSystem?.promises ?? fs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
-    const mode = await resolveMode(options);
-    const expectedHash = atomicExpectedContentHash(options.renameIdentity, options.content);
+    const mode = await resolveMode(options, filePath);
+    const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
-        await fsModule.mkdir(dir, { recursive: true, mode: dirMode });
+        await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
         tempOwner.start();
         tempOwner.adopt(await writeTempFile({
@@ -219,38 +225,39 @@ async function replaceFileAtomicUnserialized(options, syncParent) {
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         await tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }
 }
 export function replaceFileAtomicSync(options) {
-    const filePath = options.filePath;
-    validateReplaceFilePath(filePath);
+    const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
-    validateRenameIdentity(options.renameIdentity);
-    if (options.renameIdentity !== "verify-content-with-lock") {
-        return replaceFileAtomicSyncUnserialized(options);
+    const renameIdentity = options.renameIdentity;
+    validateRenameIdentity(renameIdentity);
+    if (renameIdentity !== "verify-content-with-lock") {
+        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity);
     }
-    (options.fileSystem ?? syncFs).mkdirSync(path.dirname(filePath), {
+    const fsModule = options.fileSystem ?? syncFs;
+    const dir = path.dirname(filePath);
+    fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, {
         recursive: true,
         mode: options.dirMode ?? 0o700,
     });
-    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options));
+    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity));
 }
-function replaceFileAtomicSyncUnserialized(options) {
-    const filePath = options.filePath;
+function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
-    const mode = resolveModeSync(options);
-    const expectedHash = atomicExpectedContentHash(options.renameIdentity, options.content);
+    const mode = resolveModeSync(options, filePath);
+    const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const fchmodSync = options.fileSystem?.fchmodSync ?? (options.fileSystem === undefined ? syncFs.fchmodSync : undefined);
     if (!fchmodSync &&
         (options.mode !== undefined ||
@@ -260,9 +267,9 @@ function replaceFileAtomicSyncUnserialized(options) {
     }
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new SyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
-        fsModule.mkdirSync(dir, { recursive: true, mode: dirMode });
+        fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
         tempOwner.start();
         tempOwner.adopt(writeTempFileSync({
@@ -316,13 +323,13 @@ function replaceFileAtomicSyncUnserialized(options) {
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }

package/node_modules/@openclaw/fs-safe/dist/retained-directory-replacement.d.ts

@@ -0,0 +1,25 @@
+import type { BigIntStats } from "node:fs";
+import type { NativeBinding, NativeOwnedTreeRemovalResult } from "./native-binding.js";
+type RenameBinding = NativeBinding & Required<Pick<NativeBinding, "renameNoReplaceWithIdentity">>;
+export type RetainedReplacementParent = Readonly<{
+    path: string;
+    realPath: string;
+    identity: Pick<BigIntStats, "dev" | "ino">;
+}>;
+export declare class RetainedDirectoryReplacement {
+    #private;
+    private constructor();
+    static requireBinding(): RenameBinding;
+    static retain(params: {
+        targetParent: RetainedReplacementParent;
+        stagedParent: RetainedReplacementParent;
+        originalTarget?: Readonly<{
+            path: string;
+            identity: Pick<BigIntStats, "dev" | "ino">;
+        }>;
+    }, binding?: RenameBinding): RetainedDirectoryReplacement;
+    renameNoReplace(sourceParent: "staged" | "target", sourceBasename: string, targetBasename: string, expectedSource: Pick<BigIntStats, "dev" | "ino">): void;
+    removeOriginal(backupBasename: string): Promise<NativeOwnedTreeRemovalResult["outcome"]>;
+    close(): void;
+}
+export {};

package/node_modules/@openclaw/fs-safe/dist/retained-directory-replacement.js

@@ -0,0 +1,193 @@
+import fsSync from "node:fs";
+import { assertDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+function helperUnavailable(message, cause) {
+    return new FsSafeError("helper-unavailable", message, {
+        ...(cause instanceof Error ? { cause } : {}),
+    });
+}
+function copyOperationalCode(target, source) {
+    const code = source?.code;
+    if (typeof code === "string") {
+        Object.defineProperty(target, "code", { configurable: true, value: code });
+    }
+}
+function primaryWithCloseFailure(error, closeError, message) {
+    const cause = new AggregateError([error, closeError], message);
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, {
+            cause,
+            ...(error.details ? { details: error.details } : {}),
+        });
+    }
+    const wrapped = new Error(message, { cause });
+    copyOperationalCode(wrapped, error);
+    return wrapped;
+}
+function supportsRename(binding) {
+    return typeof binding?.renameNoReplaceWithIdentity === "function";
+}
+function supportsCleanup(binding) {
+    return typeof binding.ownedTreeRemovalAvailable === "function" &&
+        typeof binding.removeOwnedTree === "function";
+}
+function closeDescriptors(descriptors) {
+    const errors = [];
+    const closed = new Set();
+    for (const fd of descriptors) {
+        if (fd === undefined || closed.has(fd))
+            continue;
+        closed.add(fd);
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1) {
+        throw new AggregateError(errors, "retained directory replacement descriptors failed to close");
+    }
+}
+const retainedDirectoryOpenFlags = fsSync.constants.O_RDONLY |
+    fsSync.constants.O_DIRECTORY |
+    fsSync.constants.O_NOFOLLOW |
+    fsSync.constants.O_NONBLOCK;
+function openRetainedDirectory(label, expected) {
+    let fd;
+    try {
+        fd = fsSync.openSync(expected.path, retainedDirectoryOpenFlags);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "EACCES" || code === "EPERM") {
+            const purpose = label === "original target"
+                ? "original target for bounded cleanup"
+                : label;
+            throw helperUnavailable(`atomic directory replacement cannot retain the ${purpose}`, error);
+        }
+        throw error;
+    }
+    try {
+        const descriptor = fsSync.fstatSync(fd, { bigint: true });
+        if (!descriptor.isDirectory()) {
+            throw new FsSafeError("not-file", `directory replacement ${label} must be a directory`);
+        }
+        if (descriptor.dev !== expected.identity.dev || descriptor.ino !== expected.identity.ino) {
+            throw new FsSafeError("path-mismatch", `directory replacement ${label} changed during admission`);
+        }
+        assertDirectoryIdentitySync(expected.path, {
+            dev: expected.identity.dev,
+            ino: expected.identity.ino,
+            ...(expected.realPath === undefined ? {} : { realPath: expected.realPath }),
+        });
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (closeError) {
+            throw primaryWithCloseFailure(error, closeError, `directory replacement ${label} admission and close failed`);
+        }
+        throw error;
+    }
+    return fd;
+}
+export class RetainedDirectoryReplacement {
+    #binding;
+    #originalDirectoryFd;
+    #stagedParentFd;
+    #targetParentFd;
+    #cleanupUsed = false;
+    #closed = false;
+    constructor(binding, targetParentFd, stagedParentFd, originalDirectoryFd) {
+        this.#binding = binding;
+        this.#targetParentFd = targetParentFd;
+        this.#stagedParentFd = stagedParentFd;
+        this.#originalDirectoryFd = originalDirectoryFd;
+    }
+    static requireBinding() {
+        const binding = getNativeBinding();
+        if (!supportsRename(binding)) {
+            throw helperUnavailable("atomic directory replacement requires native identity-fenced no-replace rename support");
+        }
+        return binding;
+    }
+    static retain(params, binding = RetainedDirectoryReplacement.requireBinding()) {
+        let targetParentFd;
+        let stagedParentFd;
+        let originalDirectoryFd;
+        try {
+            targetParentFd = openRetainedDirectory("target parent", params.targetParent);
+            stagedParentFd = params.stagedParent.path === params.targetParent.path
+                ? targetParentFd
+                : openRetainedDirectory("staged parent", params.stagedParent);
+            if (params.originalTarget) {
+                if (!supportsCleanup(binding)) {
+                    throw helperUnavailable("replacing an existing directory requires native bounded owned-tree cleanup");
+                }
+                let available = false;
+                try {
+                    available = binding.ownedTreeRemovalAvailable(targetParentFd) === true;
+                }
+                catch (error) {
+                    throw helperUnavailable("native owned-tree cleanup capability probe failed", error);
+                }
+                if (!available) {
+                    throw helperUnavailable("native owned-tree cleanup is unavailable for the target parent");
+                }
+                originalDirectoryFd = openRetainedDirectory("original target", {
+                    path: params.originalTarget.path,
+                    identity: params.originalTarget.identity,
+                });
+            }
+            return new RetainedDirectoryReplacement(binding, targetParentFd, stagedParentFd, originalDirectoryFd);
+        }
+        catch (error) {
+            try {
+                closeDescriptors([originalDirectoryFd, stagedParentFd, targetParentFd]);
+            }
+            catch (closeError) {
+                throw primaryWithCloseFailure(error, closeError, "retained directory replacement admission and descriptor close failed");
+            }
+            throw error;
+        }
+    }
+    renameNoReplace(sourceParent, sourceBasename, targetBasename, expectedSource) {
+        if (this.#closed) {
+            throw new FsSafeError("path-mismatch", "retained directory rename authority is unavailable");
+        }
+        this.#binding.renameNoReplaceWithIdentity(sourceParent === "staged" ? this.#stagedParentFd : this.#targetParentFd, sourceBasename, this.#targetParentFd, targetBasename, expectedSource.dev, expectedSource.ino);
+    }
+    async removeOriginal(backupBasename) {
+        if (this.#closed || this.#cleanupUsed || this.#originalDirectoryFd === undefined ||
+            !supportsCleanup(this.#binding)) {
+            throw new FsSafeError("path-mismatch", "retained owned-tree cleanup authority is unavailable");
+        }
+        this.#cleanupUsed = true;
+        const result = await this.#binding.removeOwnedTree(this.#targetParentFd, backupBasename, this.#originalDirectoryFd);
+        if (result.errorCode) {
+            if (result.errorCode === "path-mismatch") {
+                throw new FsSafeError("path-mismatch", result.errorMessage ?? "native owned-tree cleanup lost retained identity");
+            }
+            throw Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), { code: result.errorCode });
+        }
+        if (result.outcome !== "removed" && result.outcome !== "preserved") {
+            throw helperUnavailable("native owned-tree cleanup returned an invalid result");
+        }
+        return result.outcome;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        closeDescriptors([
+            this.#originalDirectoryFd,
+            this.#stagedParentFd,
+            this.#targetParentFd,
+        ]);
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/root-boundary.d.ts

@@ -0,0 +1,29 @@
+export declare function sameNormalizedPathSpelling(left: string, right: string): boolean;
+export type RootBoundaryIdentity = Readonly<{
+    dev: number | bigint;
+    ino: number | bigint;
+}>;
+export type AdmittedRootPath = Readonly<{
+    path: string;
+    relativePath: string;
+    admission: "exact" | "identity";
+}>;
+/**
+ * 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 declare function admitPathInsideRoot(params: {
+    rootPath: string;
+    candidatePath: string;
+    rootIdentity?: RootBoundaryIdentity;
+    resolveCandidateRoot?: boolean;
+    identityCache?: Map<string, boolean>;
+    inspectCandidateRoot?: (candidateRootPath: string, expected: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>) => void;
+}): AdmittedRootPath | undefined;

package/node_modules/@openclaw/fs-safe/dist/root-boundary.js

@@ -0,0 +1,186 @@
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
+export function sameNormalizedPathSpelling(left, right) {
+    // Preserve case on Windows, where individual directories can be case-sensitive.
+    return path.resolve(left) === path.resolve(right);
+}
+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;
+    }
+}