@openclaw/fs-safe 0.18.2 → 0.20.0

package/dist/symlink-parents.js

@@ -3,24 +3,46 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isPathRelativeEscape } from "./path.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function outsideRootError(params, root) {
+    return new Error(`${params.messagePrefix ?? "Path"} must stay under ${root}.`);
+}
+function pathSegments(value) {
+    return value.split(process.platform === "win32" ? /[/\\]+/ : /\/+/)
+        .filter((segment) => segment.length > 0 && segment !== ".");
+}
+function rawTargetSegments(root, targetPath) {
+    // Resolve only the drive/root or cwd, never the caller's dotdot segments.
+    const targetRoot = path.parse(targetPath).root;
+    const base = resolvePathPreservingWindowsRoot(targetRoot || ".");
+    const absoluteTarget = `${base}${path.sep}${targetPath.slice(targetRoot.length)}`;
+    const rootSegments = pathSegments(root);
+    const targetSegments = pathSegments(absoluteTarget);
+    const fold = (segment) => process.platform === "win32" ? segment.toLowerCase() : segment;
+    if (rootSegments.some((segment, index) => fold(segment) !== fold(targetSegments[index] ?? ""))) {
+        return undefined;
+    }
+    return targetSegments.slice(rootSegments.length);
+}
 function resolvePathWalk(params) {
     const rawRootDir = params.rootDir;
     assertNoWindowsPathAlias(rawRootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
     const rawTargetPath = params.targetPath;
     assertNoWindowsPathAlias(rawTargetPath, "filesystem", "target path uses a Windows filesystem namespace alias");
     const root = resolvePathPreservingWindowsRoot(rawRootDir);
-    const target = resolvePathPreservingWindowsRoot(rawTargetPath);
-    const relative = path.relative(root, target);
+    const lexicalTarget = resolvePathPreservingWindowsRoot(rawTargetPath);
+    const relative = path.relative(root, lexicalTarget);
     if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {
             return null;
         }
-        throw new Error(`${params.messagePrefix ?? "Path"} must stay under ${root}.`);
+        throw outsideRootError(params, root);
     }
-    return {
-        root,
-        segments: relative && relative !== "." ? relative.split(path.sep).filter(Boolean) : [],
-    };
+    const segments = rawTargetSegments(root, rawTargetPath);
+    // A spelling outside the root must not fall back to a normalized walk that
+    // could erase a symlink before the filesystem receives the original path.
+    if (!segments)
+        throw outsideRootError(params, root);
+    return { root, segments };
 }
 function formatUnsafePath(params, current) {
     return `${params.messagePrefix ?? "Path"} must not traverse symlinked directory: ${current}`;
@@ -28,18 +50,39 @@ function formatUnsafePath(params, current) {
 export async function assertNoSymlinkParents(params) {
     assertNoSymlinkParentsSync(params);
 }
+function isFilesystemRoot(root) {
+    return root === path.parse(root).root;
+}
 export function assertNoSymlinkParentsSync(params) {
     const walk = resolvePathWalk(params);
     if (!walk) {
         return;
     }
     let current = walk.root;
+    // `..` may only undo a real directory this walk already lstat'd.
+    const walked = [];
     for (const [index, segment] of walk.segments.entries()) {
+        if (segment === "..") {
+            const top = walked[walked.length - 1];
+            if (top?.kind === "dir") {
+                walked.pop();
+                current = walked[walked.length - 1]?.path ?? walk.root;
+                continue;
+            }
+            if (top?.kind === "symlink") {
+                throw new Error(formatUnsafePath(params, top.path));
+            }
+            if (!isFilesystemRoot(walk.root)) {
+                throw outsideRootError(params, walk.root);
+            }
+            continue;
+        }
         current = path.join(current, segment);
         try {
             const stat = fsSync.lstatSync(current);
             if (stat.isSymbolicLink()) {
                 if (params.allowRootChildSymlink && path.dirname(current) === walk.root) {
+                    walked.push({ path: current, kind: "symlink" });
                     continue;
                 }
                 throw new Error(formatUnsafePath(params, current));
@@ -47,9 +90,17 @@ export function assertNoSymlinkParentsSync(params) {
             if ((params.requireDirectories || index < walk.segments.length - 1) && !stat.isDirectory()) {
                 throw new FsSafeError("not-file", `${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
             }
+            if (stat.isDirectory()) {
+                walked.push({ path: current, kind: "dir" });
+            }
         }
         catch (err) {
             if (hasNodeErrorCode(err, "ENOENT") && params.allowMissing !== false) {
+                // Win32 can cancel a nonexistent component before filesystem lookup.
+                // Returning early would leave later, reachable symlinks unchecked.
+                if (process.platform === "win32" && walk.segments.slice(index + 1).includes("..")) {
+                    throw new FsSafeError("invalid-path", `${params.messagePrefix ?? "Path"} must not cancel a missing directory: ${current}`);
+                }
                 return;
             }
             throw err;

package/dist/temp-target.js

@@ -4,7 +4,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { suffixWindowsReservedDeviceName } from "./filename.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
-import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
+import { assertSafePathSegment, normalizeSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges, } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { hasNodeErrorCode } from "./path.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
@@ -60,7 +60,9 @@ function sanitizeExtension(extension) {
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {
-    return suffixWindowsReservedDeviceName(sanitizeSafePathSegment(path.basename(fileName)) ?? "download.bin");
+    // Suffix reserved stems before admission so CON.txt stays CON_.txt.
+    const suffixed = suffixWindowsReservedDeviceName(normalizeSafePathSegment(path.basename(fileName)));
+    return sanitizeSafePathSegment(suffixed) ?? "download.bin";
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);

package/dist/temp-workspace-owner.js

@@ -14,13 +14,6 @@ function isNativeCleanupBinding(binding) {
         typeof binding.removeOwnedTreeSync === "function" &&
         typeof binding.ownedTreeRemovalAvailable === "function";
 }
-function nativeRemovalError(result) {
-    if (!result.errorCode)
-        return undefined;
-    return Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
-        code: result.errorCode,
-    });
-}
 export class TempWorkspaceCleanupCapability {
     binding;
     parent;
@@ -309,8 +302,10 @@ export class TempWorkspaceCleanupOwner {
         this.#capability.assertCurrent();
     }
     #mapRemoval(result) {
-        const error = nativeRemovalError(result);
-        if (error) {
+        if (result.errorCode) {
+            const error = Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
+                code: result.errorCode,
+            });
             if (error.code === "path-mismatch")
                 return "indeterminate";
             throw error;

package/dist/test-hooks.d.ts

@@ -25,7 +25,7 @@ export type FsSafeTestHooks = {
     beforeTempWorkspaceNativeRemovalSync?: (quarantinePath: string) => void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
-    beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
+    beforePublishDirectorySync?: NonNullable<FsSafeTestHooks["afterPublishTargetCreated"]>;
 };
 export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;

package/dist/text-atomic.d.ts

@@ -1,4 +1,5 @@
-export type WriteTextAtomicOptions = {
+import { type ReplaceFileAtomicOptions } from "./replace-file.js";
+export type WriteTextAtomicOptions = Pick<ReplaceFileAtomicOptions, "beforeRename" | "tempPrefix"> & {
     mode?: number;
     dirMode?: number;
     trailingNewline?: boolean;

package/dist/text-atomic.js

@@ -12,5 +12,7 @@ export async function writeTextAtomic(filePath, content, options) {
         copyFallbackOnPermissionError: true,
         syncTempFile: durable,
         syncParentDir: durable,
+        beforeRename: options?.beforeRename,
+        tempPrefix: options?.tempPrefix,
     });
 }

package/dist/trash.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { assertSyncDirectoryGuard, createSyncDirectoryGuard } from "./directory-guard.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
 import { realpathSync } from "./realpath.js";
@@ -72,6 +73,22 @@ function resolveTrashTargetPath(targetPath) {
     assertNoTrashPathAlias(resolvedPath, "target path");
     return { path: resolvedPath, resolved: true };
 }
+function resolveTrashEntryParent(lexicalTarget, targetPath) {
+    const lexicalParent = path.dirname(lexicalTarget);
+    assertNoTrashPathAlias(lexicalParent, "target path");
+    let realParent;
+    try {
+        // The renamed name lives in this parent. rename follows intermediate
+        // symlinks, so a lexical parent inside an allowed root is not enough.
+        realParent = realpathSync.native(lexicalParent);
+    }
+    catch {
+        throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
+    }
+    const resolvedParent = path.resolve(realParent);
+    assertNoTrashPathAlias(resolvedParent, "target path");
+    return resolvedParent;
+}
 function assertAllowedTrashTarget(targetPath, allowedRoots) {
     assertNoTrashPathAlias(targetPath, "target path");
     const lexicalTarget = path.resolve(targetPath);
@@ -79,11 +96,19 @@ function assertAllowedTrashTarget(targetPath, allowedRoots) {
     const stat = fs.lstatSync(lexicalTarget);
     const resolvedTarget = resolveTrashTargetPath(targetPath);
     const resolvedTargetPath = resolvedTarget.path;
-    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => resolvedTargetPath !== root && isSameOrChildPath(resolvedTargetPath, root));
+    const parent = createSyncDirectoryGuard(path.dirname(lexicalTarget));
+    // Admit the directory entry only when its parent really stays inside an
+    // allowed root. Do not admit it because the symlink target is inside.
+    const resolvedParent = resolveTrashEntryParent(lexicalTarget, targetPath);
+    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => isSameOrChildPath(resolvedParent, root));
     if (!isAllowed) {
         throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
     }
+    // Sync and native realpath can use different Windows short-name spellings.
+    // Recheck the retained guard around native containment instead of comparing them.
+    assertSyncDirectoryGuard(parent);
     return {
+        parent,
         path: lexicalTarget,
         realPath: resolvedTargetPath,
         realPathResolved: resolvedTarget.resolved,
@@ -91,6 +116,7 @@ function assertAllowedTrashTarget(targetPath, allowedRoots) {
     };
 }
 function assertTrashTargetGuard(guard) {
+    assertSyncDirectoryGuard(guard.parent);
     const stat = fs.lstatSync(guard.path);
     if (!sameFileIdentity(stat, guard.stat)) {
         throw new Error(`Refusing to trash path after it changed: ${guard.path}`);

package/dist/walk.d.ts

@@ -20,12 +20,9 @@ export type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "
     include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
     descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
 };
-export type WalkDirectoryFailure = {
-    path: string;
-    relativePath: string;
-    depth: number;
+export type WalkDirectoryFailure = Pick<WalkDirectoryEntry & {
     error: unknown;
-};
+}, "path" | "relativePath" | "depth" | "error">;
 export type WalkDirectoryResult = {
     entries: WalkDirectoryEntry[];
     scannedEntryCount: number;

package/dist/windows-owner.d.ts

@@ -9,7 +9,6 @@ export type WindowsOwnerSummary = Omit<PermissionFailureFields & {
     daclPresent?: boolean;
     aces?: WindowsOwnerAce[];
     aclError?: string;
-    remote?: boolean;
     trusted?: boolean;
 }, never>;
 export type WindowsOwnerAce = {

package/dist/windows-owner.js

@@ -87,7 +87,6 @@ export async function inspectWindowsOwner(params) {
             sid: ownerSid,
             currentUserSid,
             ...parseWindowsAclFacts(parsed),
-            remote,
             trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
         };
     }

package/dist/windows-security-bridge.cs

@@ -312,6 +312,10 @@ public static partial class FsSafeWindowsBridge {
       }
     }
   }
+  static object InspectPath(string path) {
+    // Raw reporting retains ACL facts when locality is unknown; admission remains strict.
+    using(var handle=Open(path,0x00020080,false)) return Security(handle,false);
+  }
   public static object Execute(string operation,string path) {
     try {
       object result;
@@ -323,10 +327,8 @@ public static partial class FsSafeWindowsBridge {
           Require(!handle.IsInvalid,"EBADF","inherited file handle is unavailable");
           result=Row("identity",Identity(handle),"security",Security(handle));
         }
-      } else if(operation=="path") {
-        // Raw reporting retains ACL facts when locality is unknown; admission remains strict.
-        using(var handle=Open(path,0x00020080,false)) result=Security(handle,false);
-      } else throw new Failure("EINVAL","unknown Windows security operation");
+      } else if(operation=="path") result=InspectPath(path);
+      else throw new Failure("EINVAL","unknown Windows security operation");
       return Row("ok",true,"result",result);
     } catch(Failure error) { return Row("ok",false,"code",error.Code,"message",error.Message); }
       catch(Exception) { return Row("ok",false,"code","EIO","message","Windows security descriptor processing failed"); }

package/dist/windows-security-bridge.ps1

@@ -1,6 +1,6 @@
 param(
   [Parameter(Mandatory = $true)]
-  [ValidateSet('path', 'descriptor', 'create', 'directory', 'protect-file', 'verify-file')]
+  [ValidateSet('path', 'paths', 'descriptor', 'create', 'directory', 'protect-file', 'verify-file')]
   [string] $Operation
 )
 
@@ -11,5 +11,80 @@ $env:PSModulePath = [IO.Path]::Combine($PSHOME, 'Modules')
 [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
 
 Microsoft.PowerShell.Utility\Add-Type -LiteralPath ([IO.Path]::Combine($PSScriptRoot, 'windows-security-bridge.cs'))
-$targetPath = [Environment]::GetEnvironmentVariable('FS_SAFE_WINDOWS_SECURITY_PATH')
-[FsSafeWindowsBridge]::Execute($Operation, $targetPath) | Microsoft.PowerShell.Utility\ConvertTo-Json -Depth 8 -Compress
+if ($Operation -eq 'paths') {
+  $reply = $null
+  $limit = 16 * 1024 * 1024
+  try {
+    $inputStream = [Console]::OpenStandardInput()
+    $inputBytes = [IO.MemoryStream]::new()
+    try {
+      $buffer = [byte[]]::new(8192)
+      while (($read = $inputStream.Read($buffer, 0, $buffer.Length)) -gt 0) {
+        if ($inputBytes.Length + $read -gt $limit) {
+          throw 'Windows security path batch exceeds the input budget'
+        }
+        $inputBytes.Write($buffer, 0, $read)
+      }
+      $inputJson = [Text.UTF8Encoding]::new($false, $true).GetString($inputBytes.ToArray())
+    } finally {
+      $inputBytes.Dispose()
+      $inputStream.Dispose()
+    }
+    if (-not $inputJson.TrimStart().StartsWith('[')) {
+      throw 'Windows security paths must be a JSON array'
+    }
+    # Validate the whole document before wrapping it; the wrapper keeps empty,
+    # singleton, and nested arrays intact on Windows PowerShell 5.1.
+    $null = Microsoft.PowerShell.Utility\ConvertFrom-Json -InputObject $inputJson
+    $request = Microsoft.PowerShell.Utility\ConvertFrom-Json -InputObject ('{"paths":' + $inputJson + '}')
+    if ($request.paths -isnot [array]) {
+      throw 'Windows security paths must be a JSON array'
+    }
+    for ($index = 0; $index -lt $request.paths.Length; $index++) {
+      $value = $request.paths[$index]
+      if ($value -isnot [string] -or $value.Length -eq 0 -or $value.IndexOf([char]0) -ge 0) {
+        throw 'Windows security paths must be nonempty strings without NUL bytes'
+      }
+    }
+  } catch {
+    $reply = @{ ok = $false; code = 'EINVAL'; message = 'Invalid Windows security path batch' }
+  }
+  if ($null -eq $reply) {
+    $utf8 = [Console]::OutputEncoding
+    $prefix = '{"ok":true,"result":['
+    $suffix = ']}'
+    $bytes = $utf8.GetByteCount($prefix) + $utf8.GetByteCount($suffix)
+    $encoded = [Text.StringBuilder]::new($prefix)
+    $separator = ''
+    foreach ($pathname in $request.paths) {
+      try {
+        $reply = [FsSafeWindowsBridge]::Execute('path', $pathname)
+      } catch {
+        $reply = @{ ok = $false; code = 'EINVAL'; message = 'Invalid Windows security path batch' }
+      }
+      if (-not $reply.ok) { break }
+      $rowJson = Microsoft.PowerShell.Utility\ConvertTo-Json -InputObject ([ordered]@{ path = $pathname; security = $reply.result }) -Depth 8 -Compress
+      $reply = $null
+      $nextBytes = $bytes + $separator.Length + $utf8.GetByteCount($rowJson)
+      if ($nextBytes -gt $limit) {
+        $rowJson = $null
+        $reply = @{ ok = $false; code = 'too-large'; message = 'Windows security batch exceeded its output budget' }
+        break
+      }
+      [void]$encoded.Append($separator).Append($rowJson)
+      $bytes = $nextBytes
+      $separator = ','
+      $rowJson = $null
+    }
+    if ($null -eq $reply) {
+      [void]$encoded.Append($suffix)
+      [Console]::Write($encoded.ToString())
+      return
+    }
+    $encoded = $null
+  }
+} else {
+  $targetPath = [Environment]::GetEnvironmentVariable('FS_SAFE_WINDOWS_SECURITY_PATH')
+  $reply = [FsSafeWindowsBridge]::Execute($Operation, $targetPath)
+}
+$reply | Microsoft.PowerShell.Utility\ConvertTo-Json -Depth 8 -Compress

package/dist/windows-security-command.d.ts

@@ -1,6 +1,14 @@
 import type { NativeWindowsDescriptorSecurityFacts, NativeWindowsSecurityFacts } from "./native-binding.js";
+import type { FsSafeNativeMode } from "./native-config.js";
+import { type DescriptorFacts } from "./windows-security-facts.js";
+export declare const WINDOWS_SECURITY_BATCH_MAX_BYTES: number;
 /** Cleanup must preserve stages still reachable by an unsettled command. */
 export declare function hasUnsettledWindowsSecurityCommand(error: unknown): boolean;
+export declare function readWindowsSecurityFactsBatch(paths: readonly string[], options: {
+    timeoutMs: number;
+    native: boolean;
+    mode: FsSafeNativeMode;
+}): Promise<DescriptorFacts[]>;
 export declare function readWindowsSecurityFactsCommand(targetPath: string): NativeWindowsSecurityFacts;
 export declare function inspectWindowsDescriptorCommand(fd: number): Promise<NativeWindowsDescriptorSecurityFacts>;
 export declare function createPrivateWindowsDirectoryCommand(targetPath: string, expectedParentIdentity?: string): Promise<{

package/dist/windows-security-command.js

@@ -3,10 +3,11 @@ import { fileURLToPath } from "node:url";
 import { FsSafeError } from "./errors.js";
 import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
-import { parseWindowsSecurityCommandFacts } from "./windows-security-facts.js";
+import { parseWindowsOwnerAndDaclFacts, parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
+export const WINDOWS_SECURITY_BATCH_MAX_BYTES = 16 * 1024 * 1024;
 function isFullIdentity(identity) {
     return typeof identity === "string" && identity.length === 49 && FULL_IDENTITY.test(identity);
 }
@@ -50,9 +51,6 @@ function command(operation, params) {
         },
     };
 }
-function unverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -79,6 +77,10 @@ function parseReplyValue(stdout, operation) {
         unverified("Windows security command returned an incomplete response");
     }
     if (!response.ok) {
+        if (operation === "paths" &&
+            (response.code === "helper-unavailable" || response.code === "too-large") && typeof response.message === "string") {
+            throw new FsSafeError(response.code, response.message);
+        }
         const codes = new Set(["EACCES", "EPERM", "EEXIST", "ENOENT", "ENOTSUP", "EIO", "EBADF", "ELOOP", "ENOTDIR", "EINVAL", "ENOSPC", "EBUSY"]);
         if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
             unverified("Windows security command returned an invalid failure");
@@ -115,13 +117,13 @@ class WindowsSecurityCommandError extends PermissionCommandError {
     timedOut;
     creationOutcome;
     processExitConfirmed;
-    constructor(file, durationMs, receipt, timedOut) {
-        super(file, durationMs, receipt);
+    constructor(file, durationMs, receipt, timedOut, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+        super(file, durationMs, receipt, timeoutMs);
         this.timedOut = timedOut;
         this.creationOutcome = receipt.creationOutcome;
         this.processExitConfirmed = receipt.processExitConfirmed;
         if (timedOut)
-            this.message = `Windows permission inspection timed out after ${DEFAULT_PERMISSION_EXEC_TIMEOUT_MS}ms`;
+            this.message = `Windows permission inspection timed out after ${timeoutMs}ms`;
         if (!receipt.processExitConfirmed)
             this.message += "; process exit was not confirmed";
         else if (!receipt.outputClosed)
@@ -159,11 +161,12 @@ export function hasUnsettledWindowsSecurityCommand(error) {
     return pending.length > 0;
 }
 function ignoreLateError() { }
-async function execute(operation, params) {
-    const { file, args, env } = command(operation, params);
+async function execute(operation, params, request) {
+    const selected = request ?? command(operation, params);
+    const { file, args, env, input, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, maxOutputBytes = MAX_OUTPUT_BYTES } = selected;
     const startedAt = performance.now();
     return await new Promise((resolve, reject) => {
-        const child = spawn(file, args, { windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"] });
+        const child = spawn(file, args, { windowsHide: true, env, stdio: [input === undefined ? params.fd ?? "ignore" : "pipe", "pipe", "pipe"] });
         const output = [];
         const errors = [];
         let bytes = 0;
@@ -183,7 +186,7 @@ async function execute(operation, params) {
         const timeout = setTimeout(() => {
             timedOut = true;
             fail(deadlineError());
-        }, DEFAULT_PERMISSION_EXEC_TIMEOUT_MS);
+        }, timeoutMs);
         const finish = (outputClosed) => {
             if (settled)
                 return;
@@ -196,6 +199,18 @@ async function execute(operation, params) {
             child.removeListener("error", onChildError);
             child.on("error", ignoreLateError);
             const cleanupErrors = [];
+            if (input !== undefined && child.stdin) {
+                child.stdin.removeListener("error", fail);
+                child.stdin.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        child.stdin.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
             for (const [stream, collect] of [[child.stdout, collectOutput], [child.stderr, collectErrors]]) {
                 if (!stream)
                     continue;
@@ -224,7 +239,7 @@ async function execute(operation, params) {
                     cause: failure, pid: child.pid ?? null, code: exitCode, signal: exitSignal, stderr: Buffer.concat(errors),
                     processExitConfirmed, outputClosed, terminationSignalSent, terminationError, cleanupErrors,
                     ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
-                }, timedOut));
+                }, timedOut, timeoutMs));
             }
             else {
                 try {
@@ -263,7 +278,7 @@ async function execute(operation, params) {
             if (failed || settled)
                 return;
             bytes += chunk.length;
-            if (bytes <= MAX_OUTPUT_BYTES)
+            if (bytes <= maxOutputBytes)
                 chunks.push(chunk);
             else
                 fail(new Error("Windows security command exceeded its output budget"));
@@ -285,7 +300,7 @@ async function execute(operation, params) {
         };
         const onClose = (code, signal) => {
             onExit(code, signal);
-            if (!failed && performance.now() - startedAt >= DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+            if (!failed && performance.now() - startedAt >= timeoutMs) {
                 timedOut = true;
                 failed = true;
                 failure = deadlineError();
@@ -301,11 +316,47 @@ async function execute(operation, params) {
         child.stderr?.on("error", fail);
         child.stdout?.on("data", collectOutput);
         child.stderr?.on("data", collectErrors);
-        if (!child.stdout || !child.stderr) {
+        if (!child.stdout || !child.stderr || (input !== undefined && !child.stdin)) {
             // Node reports spawn errors on nextTick, which can follow the current microtask.
             missingPipes = setImmediate(() => { if (!failed && !settled)
                 fail(new Error("Windows security command output pipes are unavailable")); });
         }
+        if (input !== undefined && child.stdin) {
+            child.stdin.on("error", fail);
+            try {
+                child.stdin.end(input, "utf8");
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+    });
+}
+export async function readWindowsSecurityFactsBatch(paths, options) {
+    const invocation = command("paths", {});
+    const request = {
+        ...invocation,
+        input: JSON.stringify(paths),
+        timeoutMs: options.timeoutMs,
+        maxOutputBytes: WINDOWS_SECURITY_BATCH_MAX_BYTES,
+    };
+    if (options.native) {
+        request.file = process.execPath;
+        request.args = ["--", fileURLToPath(new URL("./owner-dacl-batch-worker.js", import.meta.url))];
+        request.env = {
+            ...Object.fromEntries(Object.entries(invocation.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH", "FS_SAFE_OWNER_DACL_BATCH_MODE"].includes(key.toUpperCase()))),
+            FS_SAFE_OWNER_DACL_BATCH_MODE: options.mode,
+        };
+    }
+    const response = await execute("paths", {}, request);
+    if (!Array.isArray(response) || response.length !== paths.length) {
+        unverified("Windows security command returned an incomplete path batch");
+    }
+    return response.map((row, index) => {
+        if (!record(row) || row.path !== paths[index]) {
+            unverified("Windows security command returned a mismatched path batch");
+        }
+        return parseWindowsOwnerAndDaclFacts(row.security);
     });
 }
 export function readWindowsSecurityFactsCommand(targetPath) {

package/dist/windows-security-facts.d.ts

@@ -1,4 +1,8 @@
 import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+export type DescriptorFacts = Pick<NativeWindowsSecurityFacts, "ownerSid" | "currentUserSid" | "daclPresent" | "isLocal" | "aceListComplete" | "unsupportedAceTypes" | "aces">;
+export declare function unverified(message: string, cause?: unknown): never;
+/** Validate policy-free observations crossing the isolated batch transport. */
+export declare function parseWindowsOwnerAndDaclFacts(value: unknown): DescriptorFacts;
 /** Raw reporting retains unknown flag bits; secure admission validates them below. */
 export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
 /** Native and command observations share the same fail-closed admission policy. */

package/dist/windows-security-facts.js

@@ -6,8 +6,8 @@ const WORLD_SIDS = new Set([
     "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
     "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
 ]);
-function unverified(message) {
-    throw new FsSafeError("permission-unverified", message);
+export function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -46,6 +46,10 @@ function validateDescriptor(value, allowUnknownFlags) {
     }
     return value;
 }
+/** Validate policy-free observations crossing the isolated batch transport. */
+export function parseWindowsOwnerAndDaclFacts(value) {
+    return validateDescriptor(value, true);
+}
 function summarize(facts) {
     const ownerClass = facts.ownerSid === facts.currentUserSid ? "current-user"
         : facts.ownerSid === SYSTEM_SID ? "system"

package/docs/advanced.md

@@ -80,7 +80,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
-| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
+| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks, inspecting raw segments before `..` normalization. A `..` may undo an inspected real directory, but cannot leave the root or undo an allowed root-child symlink. Raw paths outside the root that normalize inside are rejected. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
 `pathExists()` and `pathExistsSync()` intentionally retain ordinary `stat`
@@ -240,6 +240,7 @@ atomic replacement, use [`Root.write()`](writing.md).
 | Export | Page | Notes |
 |---|---|---|
 | `stageFileInDirectory`, `StagedFile`, `StagedFileReceipt`, `PublishedFileReceipt`, `StagedFilePublication`, `StagedFileCleanupReceipt`, `StagedFileFailureDetails` | [staged-file.md](staged-file.md) | Native-required Linux/macOS lifecycle retaining the original directory for abort cleanup. |
+| `retainSymlinkInDirectory`, `StagedSymlink`, `StagedSymlinkExpected`, `StagedSymlinkReceipt`, `PublishedSymlinkReceipt`, `StagedSymlinkPublication`, `StagedSymlinkRemoval`, `StagedSymlinkCleanupReceipt`, `StagedSymlinkFailureDetails` | [staged-symlink.md](staged-symlink.md) | Native-required retained symlink identity, no-replace publication and explicit recovery; never same-target ownership adoption. |
 | `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
 | `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Callback-produced file staging: verified sibling publication or private-workspace copy through a root. |
 
@@ -256,7 +257,7 @@ atomic replacement, use [`Root.write()`](writing.md).
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
 | `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `Error` by default, or an error supplied by `createError`. |
-| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
+| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. Allowed roots constrain the real parent of the moved entry, including symlinks; the referent is not moved. Parent identity is rechecked before mutation. |
 
 ## Stability