@openclaw/fs-safe 0.12.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`);
@@ -69,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: [],
@@ -82,8 +83,9 @@ export function walkDirectorySync(rootDir, options = {}) {
         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);
@@ -94,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);
@@ -129,7 +131,7 @@ export function walkDirectorySync(rootDir, options = {}) {
 }
 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: [],
@@ -142,8 +144,9 @@ export async function walkDirectory(rootDir, options = {}) {
         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);

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.

package/docs/archive.md

@@ -139,7 +139,23 @@ 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
@@ -232,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
@@ -321,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/copy.md

@@ -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:

package/docs/errors.md

@@ -38,6 +38,14 @@ class FsSafeError extends Error {
 
 `cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
 
+Guarded write preparation describes permission, read-only filesystem, and disk-space
+failures with messages such as `permission denied (EACCES)` or
+`no space left on device (ENOSPC)`. Other errno failures include their code in
+`filesystem write failed (EIO)`. These wrappers retain the existing `invalid-path`
+code and `policy` category for compatibility, along with the original `cause`;
+they do not expose native message text or paths. Already-classified `FsSafeError`
+instances and missing-path errors keep their existing classification.
+
 `details` is an operation-specific receipt, not an alternate error code. For
 example, `publishFileExclusive()` uses it to report the failing phase, created
 target identity, cleanup decision, and failed directory-sync outcome. Narrow
@@ -114,7 +122,7 @@ type FsSafeErrorCode =
 | `device-path` | A read/open target is a known unsafe device or process-fd path. | `/dev/zero`, `/dev/random`, `/dev/stdin`, `/dev/fd/*`, `/proc/*/fd/*`, or a Windows reserved device name. |
 | `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
 | `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
-| `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
+| `helper-unavailable` | A required native binding or bounded primitive could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, `FS_SAFE_NATIVE_MODE=off`, or a no-clobber `Root.move()` without safe native parent admission. `auto` falls back only where a safe fallback exists. |
 | `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
 | `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
 | `not-empty` | Nonrecursive `remove()` on a non-empty directory, or new children appeared during recursive removal. | Use bounded `recursive: true` removal or coordinate concurrent writers. |
@@ -136,11 +144,11 @@ type FsSafeErrorCode =
 
 Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
 
-Pathname `sha256File()` also reports `path-mismatch` when pre-open, descriptor,
-or current-path identity remains unknown after one bounded Windows retry, even
-if the file is benign. It never reopens to recover identity. Preview symlinks
-report `symlink`, preview or descriptor non-files report `not-file`, and a
-current-path symlink or non-file reports `path-mismatch`.
+Pathname `sha256File()` and `sha256FileSync()` also report `path-mismatch` when
+pre-open, descriptor, or current-path identity remains unknown after one bounded
+Windows retry, even if the file is benign. Neither reopens to recover identity.
+Preview symlinks report `symlink`, preview or descriptor non-files report
+`not-file`, and a current-path symlink or non-file reports `path-mismatch`.
 
 ## Branching
 

package/docs/file-store.md

@@ -90,13 +90,16 @@ or converts one caller-supplied key onto another:
   are rejected.
 - Windows drive-relative segments such as `C:name` or `C:` are rejected
   anywhere in a key, including `a/C:name`.
+- On Windows, every other colon is rejected too, preventing a key from naming
+  an NTFS alternate stream or directory-index alias. POSIX keeps accepting
+  ordinary colon-bearing segments that are not drive-relative spellings.
 - No segment may end in an ASCII dot or space.
 
 Violations report `invalid-path` when key validation is reached. Ordinary nested
 keys, NFC Unicode such as `café/日本語.txt`, `.hidden`, `a..b`, and internal spaces
-such as `internal space/a b.txt` are accepted. Colons elsewhere, such as the
-timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid; filesystem
-success still depends on the platform and the underlying Root policies.
+such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
+as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
+Windows rejects that spelling as stream syntax.
 
 Validation retains each method's operation order. Async reads, `exists`, and
 `remove` open the root first: if the root is missing, strict methods report
@@ -136,6 +139,24 @@ its exact publication identity cannot be verified. There is no equal-content
 fallback. The published entry remains present, so callers must inspect or
 recover that outcome instead of assuming the write did not occur.
 
+Synchronous directory creation retains exact bigint receipts for the store root
+and every parent component. On POSIX, an existing or newly created directory
+whose complete requested mode differs is reopened without following the final
+name, checked against its receipt and parent chain, and finalized through that
+descriptor. A concurrent root or parent replacement is rejected without
+applying the mode to the replacement. Directories already at the requested mode
+skip the descriptor and mode operation. Windows retains its bounded `mkdir`
+mode request and identity checks without relying on directory descriptors or a
+pathname `chmod`, because Node does not enforce POSIX directory modes there.
+
+Node does not expose a portable, `fchmod`-capable search-only directory
+descriptor on Linux. If a mismatched existing directory, or one created under
+an owner-read-removing umask, cannot be opened for reading, the synchronous
+store therefore fails closed with `permission-unverified`; it never falls back
+to pathname `chmod`. On supported macOS x64/arm64 hosts it also tries an
+`O_SEARCH` descriptor, so owner-searchable directories can still be repaired.
+Directories with neither usable read nor search access remain fail-closed.
+
 | Method | Durability support |
 |---|---|
 | `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |

package/docs/filename.md

@@ -17,22 +17,27 @@ function sanitizeUntrustedFileName(fileName: string, fallbackName: string): stri
 
 ## What it does
 
-In order:
+The primary name goes through this pipeline first:
 
-1. **Trim** whitespace. If the result is empty, return `fallbackName`.
+1. **Trim** whitespace. An empty result is unusable.
 2. **Strip path components.** Apply `path.posix.basename` then `path.win32.basename` so neither `foo/bar.txt` nor `foo\bar.txt` survives — only the final segment remains.
 3. **Strip non-portable characters.** C0/C1 controls (`0x00`–`0x1f`, `0x7f`–`0x9f`) and the Windows-invalid set `< > : " / \\ | ? *` are removed on every platform.
 4. **Trim again.**
-5. If the result is empty, `"."`, or `".."`, return `fallbackName`.
-6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
-7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
+5. An empty result, `"."`, or `".."` is unusable.
+6. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
+7. **Make the final name device-safe.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension on every platform. If the suffix would exceed 200 code units, the unsuffixed tail is shortened first, so truncation cannot recreate a device name.
+
+Only when the primary name is unusable does `fallbackName` go through the same
+nonrecursive pipeline. A safe fallback is preserved exactly; path components,
+controls, reserved device names, and overlong fallback names receive the same
+treatment as the primary name. If both candidates are unusable, the function
+returns the fixed safe literal `"file"`.
 
 If truncation itself exposes a reserved-device basename after Windows ignores
 trailing spaces or dots, the result is shortened once more and receives the
 same underscore suffix. A name that reaches the sanitization branch therefore
 remains at most 200 UTF-16 code units and is never a Windows reserved-device
-alias. `fallbackName` is returned verbatim for empty or path-alias input, so
-callers must supply a fallback that already satisfies their filename policy.
+alias. Fallback names pass through the same checks before they can be returned.
 
 That's it. The function stays intentionally small: it removes traversal and
 the most obvious cross-platform device and character hazards, but it is not a
@@ -48,6 +53,8 @@ sanitizeUntrustedFileName("a\u0000b\tc", "upload");       // "abc"
 sanitizeUntrustedFileName("   ", "fallback");              // "fallback"
 sanitizeUntrustedFileName(".", "fallback");                // "fallback"
 sanitizeUntrustedFileName("..", "fallback");               // "fallback"
+sanitizeUntrustedFileName("<>", "../../etc/passwd");       // "passwd"
+sanitizeUntrustedFileName("<>", "../..");                  // "file"
 sanitizeUntrustedFileName("CON", "fallback");              // "CON_"
 sanitizeUntrustedFileName("nul.txt", "fallback");          // "nul_.txt"
 sanitizeUntrustedFileName("aux.c", "fallback");            // "aux_.c"