@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/guarded-mkdir.js

@@ -1,18 +1,76 @@
-import fsSync from "node:fs";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
-import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { directoryComponentNotDirectoryError, rootPathChangedError } from "./root-errors.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
-function isSameOrChildPath(candidate, parent) {
-    const parentPrefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
-    return candidate === parent || candidate.startsWith(parentPrefix);
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { checkedMutationDirectory } from "./pinned-mutation-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute, } from "./path-segment-route.js";
+function sameDirectoryFacts(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+function inspectGuardCurrent(parent) {
+    const stat = inspectDirectoryIdentitySync(parent.dir, parent.stat);
+    if (realpathSync.native(parent.dir) !== parent.realPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    return stat;
+}
+function observedGuard(parent) {
+    return checkedMutationDirectory(parent.dir, parent.realPath, parent.stat);
+}
+function createdDirectoryEvidence(admission, parent, childPath) {
+    try {
+        const parentAfter = inspectGuardCurrent(parent);
+        const childBefore = inspectDirectoryIdentitySync(childPath);
+        const realPath = realpathSync.native(childPath);
+        if (realPath !== childPath)
+            return undefined;
+        const childAfter = inspectDirectoryIdentitySync(childPath, childBefore);
+        if (!sameDirectoryFacts(childBefore, childAfter))
+            return undefined;
+        const child = checkedMutationDirectory(childPath, realPath, childAfter);
+        const receipt = Object.freeze({
+            admission,
+            parent: checkedMutationDirectory(parent.dir, parent.realPath, parentAfter),
+            child,
+        });
+        return Object.freeze({
+            receipt,
+            guard: Object.freeze({ dir: childPath, realPath, stat: childAfter }),
+        });
+    }
+    catch {
+        // Failed optional evidence leaves the existing ordered admission in charge.
+        return undefined;
+    }
+}
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function suppliedExactRootIdentity(identity) {
+    return typeof identity?.dev === "bigint" && typeof identity.ino === "bigint"
+        ? { dev: identity.dev, ino: identity.ino }
+        : undefined;
+}
+function assertGuardMatchesRootIdentity(guard, expected) {
+    if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
+        throw rootPathChangedError();
+    }
+}
+function isPromiseLike(value) {
+    return typeof value?.then === "function";
 }
 async function realpathOrThrowNotFile(target) {
     try {
-        return path.resolve(realpathSync.native(target));
+        const canonical = realpathSync.native(pathForWindowsFilesystem(target));
+        assertNoWindowsPathAlias(canonical, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+        return resolvePathPreservingWindowsRoot(canonical);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -30,39 +88,154 @@ async function realpathOrThrowNotFile(target) {
  * re-deriving it from the original, possibly-symlinked, lexical path.
  */
 export async function mkdirPathComponentsWithGuards(params) {
-    const root = path.resolve(params.rootReal);
-    const rootCanonical = path.resolve(realpathSync.native(root));
-    const target = path.resolve(params.targetPath);
-    const relative = path.relative(root, target);
-    if (isPathRelativeEscape(relative)) {
+    const rawRootReal = params.rootReal;
+    assertNoWindowsPathAlias(rawRootReal, "filesystem", "root directory uses a Windows filesystem namespace alias");
+    const rawTargetPath = params.targetPath;
+    assertNoWindowsPathAlias(rawTargetPath, "filesystem", "target directory uses a Windows filesystem namespace alias");
+    const root = resolvePathPreservingWindowsRoot(rawRootReal);
+    const target = resolvePathPreservingWindowsRoot(rawTargetPath);
+    const suppliedIdentity = suppliedExactRootIdentity(params.rootIdentity);
+    const configuredRootGuard = await createAsyncDirectoryGuard(root, { bigint: true });
+    const checkedRootIdentity = suppliedIdentity ?? {
+        dev: configuredRootGuard.stat.dev,
+        ino: configuredRootGuard.stat.ino,
+    };
+    assertGuardMatchesRootIdentity(configuredRootGuard, checkedRootIdentity);
+    assertNoWindowsPathAlias(configuredRootGuard.realPath);
+    const rootCanonical = resolvePathPreservingWindowsRoot(configuredRootGuard.realPath);
+    const rootGuard = rootCanonical === root
+        ? configuredRootGuard
+        : await createAsyncDirectoryGuard(rootCanonical, { bigint: true });
+    assertGuardMatchesRootIdentity(rootGuard, checkedRootIdentity);
+    const admissionParams = {
+        candidatePath: target,
+        rootIdentity: checkedRootIdentity,
+    };
+    // Derive the suffix from the caller's trusted root spelling first. The
+    // canonical spelling is also accepted after both names have been bound to
+    // the same exact root object above.
+    const admittedTarget = admitPathInsideRoot({ rootPath: root, ...admissionParams }) ??
+        (rootCanonical === root
+            ? undefined
+            : admitPathInsideRoot({ rootPath: rootCanonical, ...admissionParams }));
+    if (!admittedTarget || isPathRelativeEscape(admittedTarget.relativePath)) {
         throw new FsSafeError("outside-workspace", "directory is outside workspace root");
     }
-    let current = root;
-    for (const part of relative.split(path.sep).filter(Boolean)) {
+    let current = rootCanonical;
+    let currentGuard = rootGuard;
+    const parts = admittedTarget.relativePath.split(path.sep).filter(Boolean);
+    let partRoute;
+    let retainedTargetPath = params.retainedTargetPath &&
+        sameAbsolutePath(path.dirname(params.retainedTargetPath), target)
+        ? params.retainedTargetPath
+        : undefined;
+    let retainedParentPath = retainedTargetPath ? path.dirname(retainedTargetPath) : undefined;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
         const next = path.join(current, part);
-        const parentGuard = await createAsyncDirectoryGuard(current);
-        await assertAsyncDirectoryGuard(parentGuard);
+        const parentGuard = currentGuard;
+        assertNoWindowsPathAlias(parentGuard.realPath, "filesystem", "canonical parent directory uses a Windows filesystem namespace alias");
+        let created = false;
+        let createReceipt;
+        if (!params.revalidateParentAfterBeforeComponent) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
         await params.beforeComponent?.(next);
-        params.assertBeforeMutation?.();
-        try {
-            await fs.mkdir(next, { mode: params.mode });
+        if (params.revalidateParentAfterBeforeComponent) {
+            await assertAsyncDirectoryGuard(parentGuard);
         }
-        catch (error) {
-            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
-                throw error;
+        if (params.beforeCreateComponent) {
+            let missing = false;
+            try {
+                fsSync.lstatSync(next);
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                missing = true;
+            }
+            if (missing) {
+                let prospectiveParent = retainedParentPath;
+                if (!prospectiveParent) {
+                    partRoute ??= createPathSegmentRoute(parts);
+                    prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
+                }
+                const authorization = params.beforeCreateComponent(next, prospectiveParent, retainedTargetPath, observedGuard(parentGuard));
+                if (isPromiseLike(authorization)) {
+                    createReceipt = await authorization;
+                    await assertAsyncDirectoryGuard(parentGuard);
+                }
+                else {
+                    createReceipt = authorization;
+                    // A synchronous authorization must still end at a live pathname
+                    // fence immediately before the authority callback and mkdir.
+                    if (!params.synchronousAuthorizationIncludesFence)
+                        inspectGuardCurrent(parentGuard);
+                }
+                params.assertBeforeMutation?.();
+                // Authority callbacks are an explicit freshness boundary. Recheck the
+                // exact parent synchronously so no callback-observed authority is
+                // carried into a pathname mkdir after the parent was swapped.
+                inspectGuardCurrent(parentGuard);
+                try {
+                    await fs.mkdir(next, { mode: params.mode });
+                    created = true;
+                }
+                catch (error) {
+                    if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                        throw error;
+                    }
+                }
+            }
+        }
+        else {
+            params.assertBeforeMutation?.();
+            try {
+                await fs.mkdir(next, { mode: params.mode });
+            }
+            catch (error) {
+                if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                    throw error;
+                }
+            }
+        }
+        let createdAuthorization;
+        let createdEvidence;
+        if (created && createReceipt && params.afterCreateComponent) {
+            createdEvidence = createdDirectoryEvidence(createReceipt, parentGuard, next);
+            if (createdEvidence) {
+                createdAuthorization = params.afterCreateComponent(createdEvidence.receipt);
             }
         }
-        const stat = fsSync.lstatSync(next);
-        if ((params.rejectSymlinks && stat.isSymbolicLink()) || (!stat.isSymbolicLink() && !stat.isDirectory())) {
+        if (params.beforeUseComponent && !createdAuthorization) {
+            let prospectiveParent = retainedParentPath;
+            if (!prospectiveParent) {
+                partRoute ??= createPathSegmentRoute(parts);
+                prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
+            }
+            await params.beforeUseComponent(next, prospectiveParent, retainedTargetPath);
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        const stat = createdAuthorization ? undefined : fsSync.lstatSync(next);
+        if (stat && ((params.rejectSymlinks && stat.isSymbolicLink()) ||
+            (!stat.isSymbolicLink() && !stat.isDirectory()))) {
             throw directoryComponentNotDirectoryError();
         }
         // Node's recursive mkdir follows symlinks in missing components. Build one
         // segment at a time and realpath-check each segment before descending.
-        const nextReal = await realpathOrThrowNotFile(next);
-        if (!isSameOrChildPath(nextReal, rootCanonical)) {
+        const nextReal = createdAuthorization && createdEvidence
+            ? createdEvidence.receipt.child.canonicalPath
+            : await realpathOrThrowNotFile(next);
+        const admittedNextReal = admitPathInsideRoot({
+            rootPath: rootCanonical,
+            candidatePath: nextReal,
+            rootIdentity: checkedRootIdentity,
+        });
+        if (!admittedNextReal) {
             throw new FsSafeError("outside-workspace", "directory escaped workspace root");
         }
-        if (stat.isSymbolicLink()) {
+        const admittedNextPath = admittedNextReal.path;
+        if (stat?.isSymbolicLink()) {
             // An existing path component may legitimately be a symlink to a real
             // directory inside the root (e.g. a skill-bank layout). We already
             // verified above that it resolves inside the root, so treat the
@@ -72,18 +245,29 @@ export async function mkdirPathComponentsWithGuards(params) {
             // every subsequent segment. Callers that need the final directory
             // (e.g. to guard it themselves after this function returns) must use
             // the returned resolved path, not their own lexical parent path.
-            const targetStat = fsSync.statSync(nextReal);
+            const targetStat = fsSync.statSync(admittedNextPath);
             if (!targetStat.isDirectory()) {
                 throw directoryComponentNotDirectoryError();
             }
-            await createAsyncDirectoryGuard(nextReal);
+            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+            assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
             await assertAsyncDirectoryGuard(parentGuard);
-            current = nextReal;
+            retainedTargetPath = undefined;
+            retainedParentPath = undefined;
+            current = admittedNextPath;
             continue;
         }
-        await createAsyncDirectoryGuard(next);
-        await assertAsyncDirectoryGuard(parentGuard);
-        current = next;
+        if (createdAuthorization && createdEvidence) {
+            currentGuard = createdEvidence.guard;
+        }
+        else {
+            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+        }
+        assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+        if (!createdAuthorization || !createdEvidence) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        current = admittedNextPath;
     }
     return current;
 }

package/dist/guest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,yCAAyC,EAC1C,MAAM,0BAA0B,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,yCAAyC,IAAI,CAAC;AAE3D,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,QAmZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,yCAAyC,EAC1C,MAAM,0BAA0B,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,yCAAyC,IAAI,CAAC;AAE3D,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,QA8ZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}

package/dist/guest.js

@@ -57,7 +57,10 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "            except FileNotFoundError:",
     "                if not mkdir_enabled:",
     "                    raise",
-    "                os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                try:",
+    "                    os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                except FileExistsError:",
+    "                    pass  # The competing entry must still pass the no-follow directory open.",
     "                next_fd = open_dir(segment, dir_fd=current_fd)",
     "            os.close(current_fd)",
     "            current_fd = next_fd",
@@ -356,11 +359,19 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "        return",
     "    if stat.S_ISLNK(src_stat.st_mode):",
     "        link_target = os.readlink(src_basename, dir_fd=src_parent_fd)",
+    "        temp_dir_name, temp_dir_fd = create_staging_dir(dst_parent_fd)",
     "        try:",
-    "            os.unlink(dst_basename, dir_fd=dst_parent_fd)",
-    "        except FileNotFoundError:",
-    "            pass",
-    "        os.symlink(link_target, dst_basename, dir_fd=dst_parent_fd)",
+    "            os.symlink(link_target, 'link', dir_fd=temp_dir_fd)",
+    "            os.replace('link', dst_basename, src_dir_fd=temp_dir_fd, dst_dir_fd=dst_parent_fd)",
+    "        finally:",
+    "            try:",
+    "                try:",
+    "                    os.unlink('link', dir_fd=temp_dir_fd)",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            finally:",
+    "                os.close(temp_dir_fd)",
+    "            os.rmdir(temp_dir_name, dir_fd=dst_parent_fd)",
     "        os.unlink(src_basename, dir_fd=src_parent_fd)",
     "        os.fsync(dst_parent_fd)",
     "        os.fsync(src_parent_fd)",

package/dist/home-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAoBA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAwCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAaR"}
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAsCA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAOpB;AAwCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAIR;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AA4DD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAoBR"}

package/dist/home-dir.js

@@ -1,6 +1,17 @@
 import os from "node:os";
 import path from "node:path";
+import process from "node:process";
 import { normalizeOptionalString } from "./string-coerce.js";
+import { assertNoWindowsPathAlias, assertNoWindowsPathAliasForPlatform, repairResolvedWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const PATH_ALIAS_MESSAGE = "path uses a Windows filesystem namespace alias";
+function isOrdinaryRootedWindowsDrivePath(input) {
+    const drive = input.charCodeAt(0);
+    return input.length >= 3 &&
+        ((drive >= 0x41 && drive <= 0x5a) || (drive >= 0x61 && drive <= 0x7a)) &&
+        input.charCodeAt(1) === 0x3a &&
+        (input.charCodeAt(2) === 0x5c || input.charCodeAt(2) === 0x2f) &&
+        input.indexOf(":", 2) === -1;
+}
 function hasHomePrefix(input) {
     return input === "~" || input.startsWith("~/") ||
         (path.sep === "\\" && input.startsWith("~\\"));
@@ -17,7 +28,12 @@ function normalize(value) {
 }
 export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
     const raw = resolveRawHomeDir(env, homedir);
-    return raw ? path.resolve(raw) : undefined;
+    if (!raw)
+        return undefined;
+    assertNoWindowsPathAlias(raw, "filesystem", "home path uses a Windows filesystem namespace alias");
+    const resolved = resolvePathPreservingWindowsRoot(raw);
+    assertNoWindowsPathAlias(resolved, "filesystem", "home path uses a Windows filesystem namespace alias");
+    return resolved;
 }
 function resolveRawHomeDir(env, homedir) {
     const explicitHome = normalize(env.OPENCLAW_HOME);
@@ -56,7 +72,9 @@ function normalizeSafe(homedir) {
     }
 }
 export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
-    return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+    const resolved = resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+    assertNoWindowsPathAlias(resolved, "filesystem", "home path uses a Windows filesystem namespace alias");
+    return resolved;
 }
 export function expandHomePrefix(input, opts) {
     if (!hasHomePrefix(input)) {
@@ -70,17 +88,62 @@ export function expandHomePrefix(input, opts) {
     // Expand before normalizing so a following .. traverses the actual home.
     return path.join(home, input.slice(2));
 }
-export function resolveHomeRelativePath(input, opts) {
-    if (!input) {
-        return input;
-    }
-    if (!hasHomePrefix(input)) {
-        return path.resolve(input);
-    }
+function resolveExpandedHomePath(input, opts) {
     const expanded = expandHomePrefix(input, {
         home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
         env: opts?.env,
         homedir: opts?.homedir,
     });
-    return path.resolve(expanded);
+    const resolved = resolvePathPreservingWindowsRoot(expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", PATH_ALIAS_MESSAGE);
+    return resolved;
+}
+function admitFinalHomePath(resolved, platform) {
+    assertNoWindowsPathAliasForPlatform(resolved, "filesystem", PATH_ALIAS_MESSAGE, platform);
+    return resolved;
+}
+function finishOrdinaryHomePath(input, resolved) {
+    const resolvedPlatform = process.platform;
+    if (resolved === input && resolvedPlatform !== undefined)
+        return resolved;
+    return admitFinalHomePath(resolved, resolvedPlatform);
+}
+function repairAndFinishOrdinaryHomePath(input, resolved) {
+    return finishOrdinaryHomePath(input, repairResolvedWindowsRoot(input, resolved));
+}
+function resolveHomePathCold(input, opts, rawPlatform, ordinaryRawAdmitted) {
+    if (ordinaryRawAdmitted) {
+        return finishOrdinaryHomePath(input, resolvePathPreservingWindowsRoot(input));
+    }
+    assertNoWindowsPathAliasForPlatform(input, "filesystem", PATH_ALIAS_MESSAGE, rawPlatform);
+    if (!hasHomePrefix(input)) {
+        const resolved = resolvePathPreservingWindowsRoot(input);
+        // This cold branch was not admitted as an ordinary rooted drive. Recheck
+        // even an unchanged result because the live platform can change between
+        // raw admission and resolved-path admission. Passing undefined preserves
+        // the classifier's default process.platform read.
+        return admitFinalHomePath(resolved, process.platform);
+    }
+    return resolveExpandedHomePath(input, opts);
+}
+export function resolveHomeRelativePath(input, opts) {
+    if (!input) {
+        return input;
+    }
+    const rawPlatform = process.platform;
+    // Primitive ordinary drive paths have exactly one structural colon. Record
+    // that admission so an unchanged resolved string does not need rescanning.
+    const ordinaryRawAdmitted = rawPlatform === "win32" &&
+        typeof input === "string" &&
+        isOrdinaryRootedWindowsDrivePath(input);
+    // Keep the overwhelmingly common rooted-drive path close to path.resolve
+    // itself. Seven-byte inputs retain the general helper's observable
+    // namespace-root preflight; a rare six-byte result retains its repair.
+    if (!ordinaryRawAdmitted || input.length === 7) {
+        return resolveHomePathCold(input, opts, rawPlatform, ordinaryRawAdmitted);
+    }
+    const resolved = path.resolve(input);
+    return resolved.length === 6
+        ? repairAndFinishOrdinaryHomePath(input, resolved)
+        : finishOrdinaryHomePath(input, resolved);
 }

package/dist/install-path.d.ts

@@ -1,5 +1,11 @@
 export declare function safeDirName(input: string): string;
+/** Legacy readable encoding; distinct IDs can share a result. Use V2 for untrusted IDs. */
 export declare function safePathSegmentHashed(input: string): string;
+/**
+ * Versioned install-ID encoding: every trimmed ID receives a domain-separated
+ * SHA-256 digest. Only surrounding whitespace is intentionally equivalent.
+ */
+export declare function safePathSegmentHashedV2(input: string): string;
 export declare function resolveSafeInstallDir(params: {
     baseDir: string;
     id: string;

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

@@ -1 +1 @@
-{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAMA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAWA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA+B5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhB"}

package/dist/install-path.js

@@ -3,6 +3,7 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { isPathInside } from "./path.js";
 import { realpathSync } from "./realpath.js";
+import { hasWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export function safeDirName(input) {
     const trimmed = input.trim();
     if (!trimmed) {
@@ -10,6 +11,7 @@ export function safeDirName(input) {
     }
     return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
 }
+/** Legacy readable encoding; distinct IDs can share a result. Use V2 for untrusted IDs. */
 export function safePathSegmentHashed(input) {
     const trimmed = input.trim();
     const base = trimmed
@@ -26,11 +28,37 @@ export function safePathSegmentHashed(input) {
     }
     return safe;
 }
+/**
+ * Versioned install-ID encoding: every trimmed ID receives a domain-separated
+ * SHA-256 digest. Only surrounding whitespace is intentionally equivalent.
+ */
+export function safePathSegmentHashedV2(input) {
+    const hash = createHash("sha256")
+        .update("@openclaw/fs-safe:install-path:v2\0", "utf8")
+        // UTF-16LE preserves every JavaScript code unit, including lone surrogates.
+        .update(input.trim(), "utf16le")
+        .digest("hex");
+    return `id-v2-${hash}`;
+}
 export function resolveSafeInstallDir(params) {
+    const baseDir = params.baseDir;
+    if (hasWindowsPathAlias(baseDir, "filesystem")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
     const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
-    const targetDir = path.join(params.baseDir, encodedName);
-    const resolvedBase = path.resolve(params.baseDir);
+    if (hasWindowsPathAlias(encodedName, "relative")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    const targetDir = path.join(baseDir, encodedName);
+    if (hasWindowsPathAlias(targetDir, "filesystem")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    const resolvedBase = resolvePathPreservingWindowsRoot(baseDir);
     const resolvedTarget = path.resolve(targetDir);
+    if (hasWindowsPathAlias(resolvedBase, "filesystem") ||
+        hasWindowsPathAlias(resolvedTarget, "filesystem")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
     const relative = path.relative(resolvedBase, resolvedTarget);
     if (!relative ||
         relative === ".." ||
@@ -41,40 +69,58 @@ export function resolveSafeInstallDir(params) {
     return { ok: true, path: resolvedTarget };
 }
 export async function assertCanonicalPathWithinBase(params) {
-    const baseDir = path.resolve(params.baseDir);
-    const candidatePath = path.resolve(params.candidatePath);
+    const baseDirInput = params.baseDir;
+    const candidatePathInput = params.candidatePath;
+    const boundaryLabel = params.boundaryLabel;
+    const invalidPath = () => new Error(`Invalid path: must stay within ${boundaryLabel}`);
+    const assertAdmittedPath = (value) => {
+        if (hasWindowsPathAlias(value, "filesystem"))
+            throw invalidPath();
+    };
+    assertAdmittedPath(baseDirInput);
+    assertAdmittedPath(candidatePathInput);
+    const baseDir = resolvePathPreservingWindowsRoot(baseDirInput);
+    const candidatePath = resolvePathPreservingWindowsRoot(candidatePathInput);
+    assertAdmittedPath(baseDir);
+    assertAdmittedPath(candidatePath);
     if (!isPathInside(baseDir, candidatePath)) {
-        throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        throw invalidPath();
     }
-    const baseLstat = fsSync.lstatSync(baseDir);
+    const baseOperationPath = pathForWindowsFilesystem(baseDir);
+    const baseLstat = fsSync.lstatSync(baseOperationPath);
     if (baseLstat.isSymbolicLink()) {
-        const baseStat = fsSync.statSync(baseDir);
+        const baseStat = fsSync.statSync(baseOperationPath);
         if (!baseStat.isDirectory()) {
-            throw new Error(`Invalid ${params.boundaryLabel}: base directory must resolve to a directory`);
+            throw new Error(`Invalid ${boundaryLabel}: base directory must resolve to a directory`);
         }
     }
     else if (!baseLstat.isDirectory()) {
-        throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
+        throw new Error(`Invalid ${boundaryLabel}: base directory must be a directory`);
     }
-    const baseRealPath = realpathSync.native(baseDir);
+    const baseRealPath = realpathSync.native(baseOperationPath);
+    assertAdmittedPath(baseRealPath);
     const validateDirectory = async (dirPath) => {
-        const resolvedDirPath = path.resolve(dirPath);
-        const dirLstat = fsSync.lstatSync(dirPath);
+        assertAdmittedPath(dirPath);
+        const resolvedDirPath = resolvePathPreservingWindowsRoot(dirPath);
+        assertAdmittedPath(resolvedDirPath);
+        const operationPath = pathForWindowsFilesystem(dirPath);
+        const dirLstat = fsSync.lstatSync(operationPath);
         if (dirLstat.isSymbolicLink()) {
             if (resolvedDirPath !== baseDir) {
-                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+                throw new Error(`Invalid path: must stay within ${boundaryLabel}`);
             }
-            const dirStat = fsSync.statSync(dirPath);
+            const dirStat = fsSync.statSync(operationPath);
             if (!dirStat.isDirectory()) {
-                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+                throw new Error(`Invalid path: must stay within ${boundaryLabel}`);
             }
         }
         else if (!dirLstat.isDirectory()) {
-            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            throw new Error(`Invalid path: must stay within ${boundaryLabel}`);
         }
-        const dirRealPath = realpathSync.native(dirPath);
+        const dirRealPath = realpathSync.native(operationPath);
+        assertAdmittedPath(dirRealPath);
         if (!isPathInside(baseRealPath, dirRealPath)) {
-            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            throw invalidPath();
         }
     };
     try {
@@ -87,5 +133,7 @@ export async function assertCanonicalPathWithinBase(params) {
             throw err;
         }
     }
-    await validateDirectory(path.dirname(candidatePath));
+    const candidateParent = path.dirname(candidatePath);
+    assertAdmittedPath(candidateParent);
+    await validateDirectory(candidateParent);
 }

package/dist/json-durable-queue-ownership.d.ts

@@ -1,12 +1,20 @@
+import { type BigIntStats } from "node:fs";
 export type DurableQueueEntryPathsLike = {
     jsonPath: string;
     deliveredPath: string;
     processingPath?: string;
 };
+export type ValidatedDurableQueueEntryPaths = Readonly<{
+    jsonPath: string;
+    deliveredPath: string;
+    processingPath: string;
+}>;
+export declare function validateDurableQueueEntryPaths(paths: DurableQueueEntryPathsLike): ValidatedDurableQueueEntryPaths;
 export declare function durableQueueProcessingPath(paths: DurableQueueEntryPathsLike): string;
 export declare function claimDurableQueueEntry(paths: DurableQueueEntryPathsLike, options?: {
     skipUnowned?: boolean;
 }): Promise<string | null>;
+export declare function migrateDurableQueueEntry<T>(paths: DurableQueueEntryPathsLike, expected: BigIntStats, releaseReadPin: () => Promise<void>, run: (filePath: string, beforePublish: () => Promise<void>) => Promise<T>): Promise<T>;
 export declare function completeDeliveredQueueEntry(paths: DurableQueueEntryPathsLike): Promise<boolean>;
 export declare function acknowledgeDurableQueueEntry(paths: DurableQueueEntryPathsLike): Promise<void>;
 export declare function moveDurableQueueEntryToFailed(params: {

package/dist/json-durable-queue-ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAKpF;AA+DD,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,OAAO,CAAC,CAalB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI1D"}
+{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAEA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAUnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,QAAQ,CAAC;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAUH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,0BAA0B,GAChC,+BAA+B,CAkBjC;AAiBD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAIpF;AA0ED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,KAAK,EAAE,0BAA0B,EACjC,QAAQ,EAAE,WAAW,EACrB,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnC,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACxE,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,OAAO,CAAC,CAclB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDhB;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI1D"}