@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/walk.js

@@ -2,6 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { realpathSync } from "./realpath.js";
+import { pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 function validateWalkBudget(name, value) {
     if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
         throw new RangeError(`${name} must be a non-negative safe integer`);
@@ -29,11 +30,10 @@ function shouldStop(result, options) {
 }
 function buildEntry(params) {
     const fullPath = params.fullPath;
-    const relativePath = path.relative(params.rootDir, fullPath) || params.dirent.name;
     return {
         name: params.dirent.name,
         path: fullPath,
-        relativePath,
+        relativePath: params.relativePath,
         depth: params.depth,
         kind: params.kind ?? kindForDirent(params.dirent),
         dirent: params.dirent,
@@ -70,7 +70,7 @@ function resolveKind(fullPath, dirent, symlinks) {
 }
 export function walkDirectorySync(rootDir, options = {}) {
     validateWalkOptions(options);
-    const root = path.resolve(rootDir);
+    const root = resolvePathPreservingWindowsRoot(rootDir);
     const symlinks = options.symlinks ?? "skip";
     const result = {
         entries: [],
@@ -79,12 +79,13 @@ export function walkDirectorySync(rootDir, options = {}) {
         failedDirs: [],
     };
     const visitedDirs = new Set();
-    function visit(dir, depth) {
+    function visit(dir, relativeDir, depth) {
         if (options.maxDepth !== undefined && depth > options.maxDepth)
             return;
         let realDir;
+        const operationPath = pathForWindowsFilesystem(dir);
         try {
-            realDir = realpathSync(dir);
+            realDir = realpathSync(operationPath);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -95,7 +96,7 @@ export function walkDirectorySync(rootDir, options = {}) {
         visitedDirs.add(realDir);
         let entries;
         try {
-            entries = fsSync.readdirSync(dir, { withFileTypes: true });
+            entries = fsSync.readdirSync(operationPath, { withFileTypes: true });
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -111,25 +112,26 @@ export function walkDirectorySync(rootDir, options = {}) {
             const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
-            const entry = buildEntry({ rootDir: root, fullPath, dirent, depth, kind });
+            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
             if (options.include?.(entry) ?? true) {
                 result.entries.push(entry);
             }
             if (kind === "directory" &&
                 (options.maxDepth === undefined || depth < options.maxDepth) &&
                 (options.descend?.(entry) ?? true)) {
-                visit(fullPath, depth + 1);
+                visit(fullPath, relativePath, depth + 1);
                 if (result.truncated)
                     return;
             }
         }
     }
-    visit(root, 1);
+    visit(root, "", 1);
     return result;
 }
 export async function walkDirectory(rootDir, options = {}) {
     validateWalkOptions(options);
-    const root = path.resolve(rootDir);
+    const root = resolvePathPreservingWindowsRoot(rootDir);
     const symlinks = options.symlinks ?? "skip";
     const result = {
         entries: [],
@@ -138,12 +140,13 @@ export async function walkDirectory(rootDir, options = {}) {
         failedDirs: [],
     };
     const visitedDirs = new Set();
-    async function visit(dir, depth) {
+    async function visit(dir, relativeDir, depth) {
         if (options.maxDepth !== undefined && depth > options.maxDepth)
             return;
         let realDir;
+        const operationPath = pathForWindowsFilesystem(dir);
         try {
-            realDir = realpathSync.native(dir);
+            realDir = realpathSync.native(operationPath);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -154,7 +157,7 @@ export async function walkDirectory(rootDir, options = {}) {
         visitedDirs.add(realDir);
         let entries;
         try {
-            entries = await fs.readdir(dir, { withFileTypes: true });
+            entries = await fs.readdir(operationPath, { withFileTypes: true });
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -170,19 +173,20 @@ export async function walkDirectory(rootDir, options = {}) {
             const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
-            const entry = buildEntry({ rootDir: root, fullPath, dirent, depth, kind });
+            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
             if (options.include?.(entry) ?? true) {
                 result.entries.push(entry);
             }
             if (kind === "directory" &&
                 (options.maxDepth === undefined || depth < options.maxDepth) &&
                 (options.descend?.(entry) ?? true)) {
-                await visit(fullPath, depth + 1);
+                await visit(fullPath, relativePath, depth + 1);
                 if (result.truncated)
                     return;
             }
         }
     }
-    await visit(root, 1);
+    await visit(root, "", 1);
     return result;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA+C/B"}
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmD/B"}

package/dist/windows-owner.js

@@ -1,5 +1,6 @@
 import { formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
+import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
 const TRUSTED_OWNER_SIDS = new Set(["s-1-5-18", "s-1-5-32-544"]);
 function normalizeSid(value) {
@@ -47,6 +48,10 @@ function parseWindowsAclFacts(parsed) {
     return { daclPresent: parsed.daclPresent, aces };
 }
 export async function inspectWindowsOwner(params) {
+    if (hasWindowsPathAlias(params.targetPath, "filesystem", "win32")) {
+        const error = new Error("Path uses a Windows filesystem namespace alias");
+        return { error: String(error), errorCause: error };
+    }
     let command = "";
     let startedAt = performance.now();
     try {

package/dist/windows-path-alias.d.ts

@@ -0,0 +1,39 @@
+import { FsSafeError } from "./errors.js";
+export type WindowsPathAliasKind = "filesystem" | "relative";
+/**
+ * Capture an ordinary Windows drive-relative path without normalizing its raw
+ * suffix. This is only for public APIs whose existing contract accepts such
+ * paths; callers must still run namespace-alias admission on the result.
+ */
+export declare function anchorWindowsDriveRelativePath(value: string): string;
+/**
+ * Resolve a path without letting Node erase the separator from an exact
+ * extended-length drive root such as `\\?\C:\`. Bare `\\?\C:` input remains
+ * unchanged so the surrounding alias admission rejects it.
+ */
+export declare function resolvePathPreservingWindowsRoot(value: string): string;
+/**
+ * Preserve a namespaced drive root after a caller has already resolved the
+ * input. This lets admission fast paths keep exactly one live path.resolve
+ * call while retaining the same root-repair behavior as the general helper.
+ */
+export declare function repairResolvedWindowsRoot(value: string, resolved: string): string;
+/**
+ * Resolve path segments against a base while preserving a namespaced drive
+ * root when Node normalizes a legitimate rooted input back to that root.
+ * Raw bare namespace drives stay bare so admission checks still reject them.
+ */
+export declare function resolvePathFromBasePreservingWindowsRoot(base: string, ...segments: string[]): string;
+/**
+ * Adapt an admitted namespaced drive root for Node's Windows filesystem layer.
+ * Node removes the root separator from these paths during filesystem dispatch,
+ * so use the equivalent ordinary drive root for the operation. This is not an
+ * admission check: callers must validate attacker-controlled input first.
+ */
+export declare function pathForWindowsFilesystem(value: string): string;
+/** Returns true when a Windows pathname can address an alternate filesystem namespace. */
+export declare function hasWindowsPathAlias(value: string, kind: WindowsPathAliasKind, platform?: NodeJS.Platform | string): boolean;
+export declare function assertNoWindowsPathAliasForPlatform(value: string, kind: WindowsPathAliasKind, message: string, platform: NodeJS.Platform | string | undefined): void;
+export declare function assertNoWindowsPathAlias(value: string, kind?: WindowsPathAliasKind, message?: string, platform?: NodeJS.Platform | string): void;
+export declare function isWindowsPathAliasError(error: unknown): error is FsSafeError;
+//# sourceMappingURL=windows-path-alias.d.ts.map

package/dist/windows-path-alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-path-alias.d.ts","sourceRoot":"","sources":["../src/windows-path-alias.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,CAAC;AAsD7D;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYpE;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUtE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUjF;AAED;;;;GAIG;AACH,wBAAgB,wCAAwC,CACtD,IAAI,EAAE,MAAM,EACZ,GAAG,QAAQ,EAAE,MAAM,EAAE,GACpB,MAAM,CAgBR;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkB9D;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,oBAAoB,EAC1B,QAAQ,GAAE,MAAM,CAAC,QAAQ,GAAG,MAAyB,GACpD,OAAO,CAMT;AAED,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,GAAG,SAAS,GAC7C,IAAI,CAMN;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,oBAAmC,EACzC,OAAO,SAAmD,EAC1D,QAAQ,GAAE,MAAM,CAAC,QAAQ,GAAG,MAAyB,GACpD,IAAI,CAMN;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAE5E"}

package/dist/windows-path-alias.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+const COLON = 0x3a;
+const FORWARD_SLASH = 0x2f;
+const BACKSLASH = 0x5c;
+const DOT = 0x2e;
+const QUESTION_MARK = 0x3f;
+function isAsciiLetter(code) {
+    return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a);
+}
+function isSeparator(code) {
+    return code === FORWARD_SLASH || code === BACKSLASH;
+}
+function rootedDriveColonIndex(value) {
+    if (value.length >= 3 &&
+        isAsciiLetter(value.charCodeAt(0)) &&
+        value.charCodeAt(1) === COLON &&
+        isSeparator(value.charCodeAt(2))) {
+        return 1;
+    }
+    if (value.length >= 7 &&
+        isSeparator(value.charCodeAt(0)) &&
+        isSeparator(value.charCodeAt(1)) &&
+        (value.charCodeAt(2) === QUESTION_MARK || value.charCodeAt(2) === DOT) &&
+        isSeparator(value.charCodeAt(3)) &&
+        isAsciiLetter(value.charCodeAt(4)) &&
+        value.charCodeAt(5) === COLON &&
+        isSeparator(value.charCodeAt(6))) {
+        return 5;
+    }
+    return -1;
+}
+function isBareWindowsNamespaceDrive(value) {
+    return (value.length === 6 &&
+        isSeparator(value.charCodeAt(0)) &&
+        isSeparator(value.charCodeAt(1)) &&
+        (value.charCodeAt(2) === QUESTION_MARK || value.charCodeAt(2) === DOT) &&
+        isSeparator(value.charCodeAt(3)) &&
+        isAsciiLetter(value.charCodeAt(4)) &&
+        value.charCodeAt(5) === COLON);
+}
+/**
+ * Capture an ordinary Windows drive-relative path without normalizing its raw
+ * suffix. This is only for public APIs whose existing contract accepts such
+ * paths; callers must still run namespace-alias admission on the result.
+ */
+export function anchorWindowsDriveRelativePath(value) {
+    if (process.platform !== "win32" || path.isAbsolute(value))
+        return value;
+    if (value.length < 2 ||
+        !isAsciiLetter(value.charCodeAt(0)) ||
+        value.charCodeAt(1) !== COLON) {
+        return value;
+    }
+    const drive = value.slice(0, 2);
+    const base = path.resolve(drive);
+    return `${base}${path.sep}${value.slice(2)}`;
+}
+/**
+ * Resolve a path without letting Node erase the separator from an exact
+ * extended-length drive root such as `\\?\C:\`. Bare `\\?\C:` input remains
+ * unchanged so the surrounding alias admission rejects it.
+ */
+export function resolvePathPreservingWindowsRoot(value) {
+    if (value.length === 7 &&
+        process.platform === "win32" &&
+        rootedDriveColonIndex(value) === 5) {
+        return value.includes("/") ? value.replaceAll("/", "\\") : value;
+    }
+    const resolved = path.resolve(value);
+    return repairResolvedWindowsRoot(value, resolved);
+}
+/**
+ * Preserve a namespaced drive root after a caller has already resolved the
+ * input. This lets admission fast paths keep exactly one live path.resolve
+ * call while retaining the same root-repair behavior as the general helper.
+ */
+export function repairResolvedWindowsRoot(value, resolved) {
+    if (resolved.length === 6 &&
+        process.platform === "win32" &&
+        isBareWindowsNamespaceDrive(resolved) &&
+        !hasWindowsPathAlias(value, "filesystem")) {
+        return `${resolved}\\`;
+    }
+    return resolved;
+}
+/**
+ * Resolve path segments against a base while preserving a namespaced drive
+ * root when Node normalizes a legitimate rooted input back to that root.
+ * Raw bare namespace drives stay bare so admission checks still reject them.
+ */
+export function resolvePathFromBasePreservingWindowsRoot(base, ...segments) {
+    const resolved = path.resolve(base, ...segments);
+    if (resolved.length !== 6 ||
+        process.platform !== "win32" ||
+        !isBareWindowsNamespaceDrive(resolved)) {
+        return resolved;
+    }
+    if (hasWindowsPathAlias(base, "filesystem") ||
+        segments.some((segment) => hasWindowsPathAlias(segment, "filesystem"))) {
+        return resolved;
+    }
+    return `${resolved}\\`;
+}
+/**
+ * Adapt an admitted namespaced drive root for Node's Windows filesystem layer.
+ * Node removes the root separator from these paths during filesystem dispatch,
+ * so use the equivalent ordinary drive root for the operation. This is not an
+ * admission check: callers must validate attacker-controlled input first.
+ */
+export function pathForWindowsFilesystem(value) {
+    if (process.platform !== "win32" ||
+        rootedDriveColonIndex(value) !== 5) {
+        return value;
+    }
+    if (value.length === 7) {
+        return `${value[4]}:\\`;
+    }
+    const resolved = path.resolve(value);
+    if (isBareWindowsNamespaceDrive(resolved) &&
+        !hasWindowsPathAlias(value, "filesystem")) {
+        return `${resolved[4]}:\\`;
+    }
+    return value;
+}
+/** Returns true when a Windows pathname can address an alternate filesystem namespace. */
+export function hasWindowsPathAlias(value, kind, platform = process.platform) {
+    if (platform !== "win32")
+        return false;
+    const firstColon = value.indexOf(":");
+    if (firstColon === -1)
+        return false;
+    if (kind === "relative")
+        return true;
+    return firstColon !== rootedDriveColonIndex(value) || value.indexOf(":", firstColon + 1) !== -1;
+}
+export function assertNoWindowsPathAliasForPlatform(value, kind, message, platform) {
+    if (hasWindowsPathAlias(value, kind, platform)) {
+        throw new FsSafeError("invalid-path", message, {
+            details: { reason: "windows-path-alias" },
+        });
+    }
+}
+export function assertNoWindowsPathAlias(value, kind = "filesystem", message = "path uses a Windows filesystem namespace alias", platform = process.platform) {
+    if (hasWindowsPathAlias(value, kind, platform)) {
+        throw new FsSafeError("invalid-path", message, {
+            details: { reason: "windows-path-alias" },
+        });
+    }
+}
+export function isWindowsPathAliasError(error) {
+    return error instanceof FsSafeError && error.details?.reason === "windows-path-alias";
+}

package/docs/advanced.md

@@ -32,7 +32,9 @@ The exports group into a handful of themes. Each documented helper has its own p
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
+| `resolvePathPrefixSync`, `ResolvedPathPrefix` | [path-prefix.md](path-prefix.md) | Follow physical symlink targets and return a canonical existing prefix with the raw missing suffix; propagate uncertain resolution failures. |
 | `probePathCaseInsensitiveSync`, `ProbePathCaseOptions` | [path-case.md](path-case.md) | Observe local ASCII-case behavior with explicit read-only mode and owned temporary-probe cleanup. |
+| `probePathSuffixAliasesSync`, `ProbePathSuffixAliasesOptions` | [path-suffix-aliases.md](path-suffix-aliases.md) | Observe selected missing suffix aliases with bounded temporary directory probes; ambiguity, dynamic budget exhaustion, or incomplete cleanup returns `undefined`. |
 
 `ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? })`
 returns `{ ok: true, path }` or `{ ok: false, error: string, diagnostic?: FsSafeError }`.
@@ -77,6 +79,11 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
+`pathExists()` and `pathExistsSync()` intentionally retain ordinary `stat`
+semantics and are not caller-path admission boundaries. Validate an untrusted
+path with the boundary appropriate to the operation before using these
+existence probes.
+
 `openRootFile()` and `openRootFileSync()` compare exact bigint identities before
 open, on the retained descriptor, and on the current resolved path. Their `stat`
 receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` for
@@ -84,6 +91,24 @@ receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` fo
 Windows identities receive one re-inspection without reopening, then fail
 validation if still unknown.
 
+On Windows, these existing-object readers retain their historical support for a
+leading drive-relative spelling such as `C:existing.txt`: it is anchored to that
+drive before confinement and namespace admission. Additional colons remain in
+the anchored spelling, so alternate-stream and directory-index aliases are still
+rejected before opening.
+
+These adapters also capture the canonical root directory's exact bigint identity
+before component traversal. Immediately before transferring descriptor ownership,
+they check that root, freshly canonicalize the consumed pathname, admit the fresh
+spelling under the captured root, compare a no-follow canonical-leaf observation
+with the retained descriptor, and check the root again. Boundary or identity drift
+is a validation failure and the descriptor is closed. A custom `ioFs` supplies
+these observations; the built-in adapter uses fs-safe's native realpath wrapper.
+On Windows, the built-in adapter binds native root spelling before traversal,
+including supplied `rootRealPath`, and returns that spelling in its root receipt.
+This is an operation-local detection fence, not atomic confinement against a peer
+that can keep racing pathname bindings.
+
 The explicit `symlinks` policy takes precedence over the existing `rejectSymlinks`
 boolean. Without `symlinks`, `rejectSymlinks: false` retains its existing behavior
 of following contained links, and omission still rejects all symlink components.
@@ -96,6 +121,8 @@ byte limit. Continuation buffers grow only after filling with actual bytes,
 up to the byte budget plus its probe; file-size hints cannot force that growth.
 Unknown-size inputs start with at most 64 KiB. This avoids per-chunk copies and
 a final concatenation when a file exceeds the initial allocation.
+Regular files that report a size of zero, such as virtual files, continue through
+positive short reads until actual EOF or byte-limit overflow.
 
 The bounded descriptor helpers start at the descriptor's current offset and
 leave ownership with the caller. They are intended for the second half of a
@@ -133,7 +160,7 @@ component is followed by another segment, both helpers throw
 
 | Export | Page | Notes |
 |---|---|---|
-| `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
+| `safeDirName`, `safePathSegmentHashed`, `safePathSegmentHashedV2`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories; use V2 for untrusted identifier mappings. |
 | `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
 | `resolveHomeRelativePath` | – | Expand a leading `~` before resolving `.` and `..`; tildes inside relative paths stay literal. |
 

package/docs/archive.md

@@ -139,7 +139,29 @@ accepted-entry plan back to Rust. Rust owns raw-stream admission, decompression,
 and fd-relative `mkdirBeneath`/exclusive-open writes. This keeps filter policy identical
 between native and JavaScript paths rather than reimplementing it in Rust.
 
-ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
+ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
+
+ZIP admission establishes each entry's kind before callbacks: a high-word UNIX
+symlink type takes precedence regardless of creator, followed by the DOS directory
+bit, the exact UNIX directory type, or a terminal slash/backslash. Native manifests
+must agree with this kind, physical index, size, known path, and UNIX-creator mode
+before extraction or any member read. Bounded ZIP reads retain this metadata from
+their single admission pass without another input copy or scan.
+
+Portable ZIP preflight, extraction, and reads also check the decoded kind against
+admission. Unsupported JSZip metadata rejects with `ArchiveFormatError` before
+filters, including UNIX-only directory attributes without a terminal slash or DOS
+directory bit, backslash-only directory names without directory attributes, and
+non-UNIX creators whose high-word symlink mode JSZip does not expose. Symlinks that
+the decoder represents faithfully remain subject to the existing filter and
+blocked-link policy. UNIX creator metadata and permission defaults remain as
+described above.
+
+Within one ZIP entry, identical local and central name bytes reuse the same
+decoded validation. Unicode Path admission is shared only when both the raw names
+and the complete Unicode fields match; different fields still verify their own
+CRC and interpretation. Shared backing memory is checked independently. Decoded
+name validation is not reused across entries or archives.
 
 `stripComponents` removes leading nonempty, non-`.` path components after
 normalizing separators. For example, `./pkg/hello.txt` with
@@ -226,7 +248,7 @@ omitted and do not consume output payload budgets. The shared core admits these
 record and are then cleared; local PAX on unsupported types and GNU sparse
 `S` records retain their existing fail-closed format policy.
 
-If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. On Windows, archive source and destination filesystem paths reject NTFS alternate-stream and directory-index namespace spellings such as `file:stream` and `dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
 
 Extraction captures the destination's lossless filesystem identity before any
 entry filter runs and retains that capability through final publication. If a
@@ -315,6 +337,11 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget for non-mutating work. Extraction is aborted on overrun; if a destination mutation is already in flight, that mutation and rollback are joined before rejection so archive-controlled publication cannot continue afterward.
 - **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before buffering their bodies. It understands octal and base-256 fixed sizes and validates bounded local PAX bodies before using their size overrides for member framing. Original archive bytes remain unchanged.
 
+Native gzip, zstd, and bzip2 readers check cancellation before refilling
+compressed input and before each decoded read, including buffered output. These checks
+apply to file extraction and in-memory member reads; they cannot interrupt an
+already-running filesystem read or a decoder step using already-buffered input.
+
 ### Raw TAR framing
 
 Extraction and bounded reads admit the complete decoded TAR stream through the

package/docs/atomic.md

@@ -1,6 +1,6 @@
 # Atomic writes
 
-`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have an absolute path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
+`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have a path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
 
 ```ts
 import {
@@ -20,6 +20,14 @@ On POSIX, the parent is opened with no-follow and directory-only flags, checked
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
 
+Relative paths retain their literal suffix so `.` and `..` keep Node's existing
+filesystem semantics. On Windows, an ordinary drive-relative destination such
+as `C:.\\state.json` is captured at entry by anchoring the drive's current
+directory without normalizing that suffix. The anchored absolute spelling is
+used for staging, locks, callbacks, publication, and cleanup. Any additional
+colon remains visible and is rejected as a filesystem namespace alias before
+I/O; malformed namespace-drive spellings remain rejected.
+
 ```ts
 import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
 
@@ -174,6 +182,8 @@ await replaceDirectoryAtomic({
 The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
 Concurrent replacements of the same resolved target are serialized inside the
 current process so their backup, commit, and cleanup phases cannot interleave.
+On Windows, ordinary drive-relative staged and target paths are anchored at
+entry before namespace-alias admission and resolution.
 `backupPrefix`, when supplied, is sanitized as one path prefix and cannot contain
 path separators or NUL bytes; the generated backup tail is randomized.
 
@@ -248,6 +258,8 @@ await movePathWithCopyFallback({
 ```
 
 Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+On Windows, ordinary drive-relative `from` and `to` paths are anchored at entry;
+publication receipts report the resulting absolute destination.
 The hardlink policy is captured when the move starts. Changing or reusing the
 options object later does not change the policy of an in-flight move.
 `sourceHardlinks: "reject"` performs a recursive preflight capped at 50,000
@@ -260,7 +272,19 @@ the preflight cap fails with `FsSafeError("too-large")`.
 If another writer changes source entries during the fallback, the staged copy
 throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
-`ESTALE`. When allowed source names are hardlinks to the same inode, each owned
+`ESTALE`. Directory manifests retain an exact bigint device/inode receipt from
+copy admission. Each directory is rechecked after traversal, and the source root
+is checked again before publication. Cleanup checks the same receipt before
+removing children, then invokes mutation authority and rechecks the receipt and
+directory type immediately before removal. Unknown Windows identity
+components get at most one retry that retains known components; persistent
+ambiguity fails closed before further removal. A directory that disappeared or
+was replaced during child cleanup is reported as stale; an observed replacement
+is preserved. Unrelated children
+added to the original directory are preserved while unchanged copied children
+are still removed. These pathname checks remain best-effort: they cannot make
+the final identity check and removal atomic against another process.
+When allowed source names are hardlinks to the same inode, each owned
 unlink is verified through a remaining manifested alias and its exact resulting
 identity becomes the next cleanup receipt. This accounts for the operation's
 own link-count and ctime changes without suppressing unexpected external
@@ -337,7 +361,7 @@ preserves the existing move and source-identity behavior.
 
 | `Root` methods | `atomic` helpers |
 |---|---|
-| Take relative paths, bound to a `rootDir`. | Take absolute paths, no boundary. |
+| Take relative paths, bound to a `rootDir`. | Take trusted absolute or relative paths, no boundary. |
 | Throw `FsSafeError` with `code`. | Throw `FsSafeError` *or* the underlying `NodeJS.ErrnoException`, depending on failure point. |
 | Atomicity, mode, hooks, fsync are sane defaults. | Caller controls all of the above. |
 | `mkdir`, identity check, hardlink reject built in. | No root boundary; `movePathWithCopyFallback` has explicit `sourceHardlinks` policy, while other helpers expose their own narrower checks. |

package/docs/contributing.md

@@ -76,7 +76,10 @@ setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a se
 removing directories. Run shared-state corpora sequentially with a deadline per
 payload. Keep child-process liveness limits separate from fixture preparation.
 The Windows CI slow-copy proof runs the real package-copy process-exit test with a
-six-second copy delay, retaining its four-second child deadline:
+16-second copy delay, a 10-second child deadline, a 15-second test deadline, and
+60-second setup and teardown hook budgets. Other hosts retain the ordinary
+six-second delay, four-second child deadline, five-second test deadline, and
+30-second hook budgets:
 
 ```bash
 pnpm build

package/docs/copy.md

@@ -64,7 +64,7 @@ Automatic copying does not recover from permission errors, I/O errors, cancellat
 
 On Windows, automatic byte copying uses the native binding when available to transfer data between the already-checked file handles in chunks of at most 1 MiB, with smaller buffers for small files. This accelerates NTFS and cross-volume copies without reopening source or destination pathnames. The native worker finishes before its descriptors are closed or cancellation is reported. `clone: "never"` and native-disabled copies use JavaScript read/write loops with reusable buffers: at most 1 MiB per active file on Windows, or 128 KiB elsewhere. Both paths share the file-worker budget across sibling directories, wait for all admitted writes after cancellation or failure, and restore directory timestamps after their descendants finish. Completed directory traversals awaiting writes or metadata are bounded by concurrency; ancestors remain pinned while traversing their children.
 
-On Linux, automatic byte copying also uses the native binding when available. It reads in 1 MiB chunks and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
+On Linux, automatic byte copying also uses the native binding when available. It reads in chunks up to 1 MiB, using smaller buffers for smaller source-size hints, and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
 
 Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
 
@@ -97,6 +97,9 @@ const bytes = await copyFileHandle(sourceHandle, targetHandle, {
 
 `CopyFileHandleOptions` contains optional `maxBytes`, `signal`, `onChunk`, and
 `assertBeforeMutation`. The result is the actual byte count copied through EOF.
+The four options are selected once before descriptor inspection; later mutation
+of the options object cannot replace the active budget, signal, observer, or
+mutation-authority callback.
 The byte limit is not a prefix length: excess data rejects with `too-large`,
 including data added after admission. Omitted limits are unlimited; Root's
 default read cap does not apply. Zero accepts only an empty source. Invalid

package/docs/durability.md

@@ -53,6 +53,14 @@ propagate.
 discard both unsupported outcomes and failures. Use them only when the primary
 write remains useful without a crash-durability promise.
 
+On Windows, pathname inputs and supplied directory receipts reject NTFS
+alternate-stream and directory-index namespace spellings before opening,
+creating, hashing, or publishing anything. This applies to directory
+durability, `publishFileExclusive()`, and the pathname overloads of
+`sha256File()` and `sha256FileSync()`; the already-open `FileHandle` and
+borrowed numeric file-descriptor overloads are unchanged. Ordinary colon-bearing
+POSIX paths remain valid.
+
 ## Pinned directories
 
 `pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
@@ -94,6 +102,12 @@ target. It pins the source with nonblocking `O_NOFOLLOW`, optionally verifies
 `expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
 parent directory.
 
+Trusted relative source and target paths are resolved to absolute paths before
+authority checks. On Windows, ordinary drive-relative operands are anchored at
+entry before namespace-alias admission. A caller-supplied `parentReceipt` must
+still name the resolved target parent and is not relaxed by this compatibility
+rule.
+
 For example, a backup archive is complete before publication. If directory
 sync fails, keeping that complete file is more useful than conditionally
 deleting it by pathname:
@@ -242,8 +256,10 @@ When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
 positioned reads in chunks of up to 256 KiB but updates Node's `Hash` on the JavaScript
-thread. Both paths stream constant-size buffers rather than loading the file
-into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+thread. Both paths stream bounded buffers rather than loading the file into memory.
+The fallback sizes its scratch buffer to small files and grows it if a stale
+size hint is exceeded, while still probing for actual EOF and byte-limit overflow.
+Native mode `require` keeps its usual fail-closed loader semantics.
 
 ### Synchronous hashing