@openclaw/fs-safe 0.19.0 → 0.20.0

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, unverified } 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);
 }
@@ -76,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");
@@ -112,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)
@@ -156,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;
@@ -180,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;
@@ -193,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;
@@ -221,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 {
@@ -260,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"));
@@ -282,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();
@@ -298,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,5 +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

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

package/docs/archive.md

@@ -211,6 +211,14 @@ loading, including failure. Public preflight still returns ordinary JSZip entry
 objects, with directory keys ending in `/` and recognizable symlink type bits.
 Compressed data is retained even for declared-zero entries, so an empty-size
 claim cannot bypass payload-size or CRC verification during extraction or reads.
+Extraction and bounded reads retain the admitted CRC and size independently of
+mutable decoder objects, so later decoder changes cannot redefine the expected
+payload integrity. Public preflight archives retain ordinary JSZip mutation
+and entry-reading behavior.
+Portable bounded reads select the admitted canonical name and reject a selected
+decoder entry that no longer belongs to that archive and name before reading its
+payload. Extraction retains the admitted names and physical order independently
+of later changes to the decoder's public `files` object.
 
 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

package/docs/atomic.md

@@ -295,9 +295,9 @@ semantics. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
 temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
-It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
-you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
-or custom copy-fallback policy.
+It delegates to `replaceFileAtomic()` with a smaller call shape, including its
+pre-publication hook and staging-prefix options. Use `replaceFileAtomic()` when
+you need mode preservation or a custom copy-fallback policy.
 
 ```ts
 import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
@@ -317,9 +317,17 @@ type WriteTextAtomicOptions = {
   dirMode?: number;          // parent mode (default 0o777 masked by process umask)
   trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  tempPrefix?: string;       // default ".fs-safe-replace"
 };
 ```
 
+`beforeRename` is awaited after the complete text is staged and before
+publication, with the same [stage identity and refusal cleanup](#beforerename)
+checks as `replaceFileAtomic`. Pass `tempPrefix` to identify staged files; it
+uses the same prefix validation, including rejection of empty prefixes and path
+separators.
+
 `durable: false` keeps the sibling-temp replace/rename behavior but skips the
 temp-file and parent-directory `fsync` calls. Use it only for reconstructible
 metadata where lower latency matters more than crash-durability.

package/docs/contributing.md

@@ -70,6 +70,36 @@ Consumers receive the asset in the npm package and need no compiler.
 
 Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
+### Linux GNU release bindings
+
+GNU x64 and arm64 artifacts use Zig 0.16.0 and `cargo-zigbuild` 0.23.4 with an
+explicit glibc 2.28 target, independent of the runner's libc. This matches the
+Node Linux runtime baseline and supports RHEL 8-family users without adding a
+second legacy package. Run the same build and ABI gate used in CI and releases:
+
+```bash
+cargo install cargo-zigbuild --version 0.23.4 --locked
+rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs x86_64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs aarch64-unknown-linux-gnu
+```
+
+These commands require Zig on `PATH` and GNU `objdump`. They build the N-API
+cdylib with `cargo zigbuild --target <triple>.2.28`, copy it to the existing
+`artifacts/fs-safe-native.<platform>.node` name, and reject any GLIBC symbol
+requirement above 2.28 before upload. The gate also rejects missing or unknown
+GLIBC versions. To inspect an existing binding, use
+`node scripts/check-linux-glibc.mjs <binding.node>`.
+
+`pnpm native:build` remains a host-toolchain development build; it does not
+establish the GNU release ABI floor.
+
+On Linux x64 with Docker, run `pnpm build`, copy the GNU x64 artifact from
+`artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
+`bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
+artifact and run native security and no-replace move tests in Rocky Linux 8
+(glibc 2.28). GNU arm64 is cross-built and symbol-checked in the same CI matrix.
+
 ## Test
 
 ```bash

package/docs/install.md

@@ -134,6 +134,16 @@ when the matching package is absent, incompatible, or disabled.
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
 
+### Older Linux kernels and seccomp
+
+The native addon supports kernels without `openat2` (before Linux 5.6) and
+containers returning `ENOSYS` or probe-time `EPERM` for that syscall. Beneath
+opens use a guarded no-follow component walk and report `best-effort`.
+Nested no-clobber moves retain atomic `renameat2(RENAME_NOREPLACE)` and exact
+identity checks; keep native mode enabled. Strict bounded cleanup still
+requires `openat2` with `RESOLVE_NO_XDEV` and reports `helper-unavailable`
+without it. See [Linux capability behavior and limits](native.md#linux-without-openat2).
+
 ### Windows security fallback
 
 Windows raw owner/DACL inspection, private-directory creation, and secure-file
@@ -161,6 +171,24 @@ available native operation's error never triggers a command retry. See
 
 ## Native helper policy
 
+### Supported native platforms
+
+Prebuilt bindings cover Linux x64/arm64 (GNU glibc **2.28 or newer**, or musl),
+macOS x64/arm64, and Windows x64. The GNU baseline includes RHEL 8, Rocky Linux 8,
+and AlmaLinux 8. A compatible Node 22+ runtime and the kernel/filesystem features
+required by each operation are still necessary; a loadable addon alone does not
+guarantee every native capability. Systems older than glibc 2.28 are outside the
+GNU binary support floor.
+
+A missing or incompatible optional binding (including `ERR_DLOPEN_FAILED` from
+glibc) does not prevent importing fs-safe. In `auto`, supported JavaScript/WASM
+fallbacks remain available. Native-only operations such as the default
+no-clobber `Root.move()` still fail closed with `helper-unavailable`; `require`
+also rejects fallback-capable operations and retains the binding load error as
+the cause.
+
+### Loading modes
+
 The platform native binaries provide fd-relative open/link/mkdir primitives,
 atomic no-replace rename, and file identity checks. The default is `auto`: use
 the matching binary when it loads, otherwise use the guarded JavaScript path

package/docs/native-helper.md

@@ -103,7 +103,7 @@ clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Without `openat2`, beneath opens use the [no-follow component walk](native.md#linux-without-openat2) with exact identity checks and report `best-effort`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup still requires `openat2` with `RESOLVE_NO_XDEV` and fails closed when unavailable.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
 - Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
@@ -139,11 +139,12 @@ for the exact difference.
 The guarded JavaScript mutation path is detection-based, not containment-atomic.
 If a same-privilege peer can replace a writable parent after its identity guard
 but before Node resolves a pathname mutation, the mutation can land outside the
-intended root before the post-operation guard throws. Select `require` rather
-than `auto` or `off` when that concurrent attacker is part of the threat model.
+intended root before the post-operation guard throws. Native `require` ensures the addon is present, but does not require a
+`kernel-atomic` resolver; inspect containment and use OS isolation when that
+concurrent attacker is part of the threat model.
 
 `openBeneath()` returns `{ fd, containment }`. `containment` is
-`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for the Linux fallback, macOS and
 Windows. Public JavaScript root open/read/writable results also expose the
 field and report `"best-effort"`; the label reports mechanism, not policy.
 

package/docs/native.md

@@ -43,6 +43,7 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 - Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
   `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+  Without `openat2`, beneath opens use the [guarded fallback](#linux-without-openat2).
 - macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
   components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
   pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
@@ -85,6 +86,49 @@ privately owned empty ACL. Unsupported, malformed, and failed inspection is not
 reported as absence. These facts do not classify individual ACE permissions or
 prove volume ownership enforcement; each caller applies its own security policy.
 
+## Linux without openat2
+
+Linux kernels before 5.6 and containers whose seccomp policy denies `openat2`
+can keep native mode `auto` or `require`. The addon caches one harmless
+`openat2(".")` capability probe per process. `ENOSYS`, or `EPERM` on that probe,
+selects the native `openat` fallback. An `EPERM`/`EACCES` from an application
+operation is still a permission error and never triggers a retry. Install
+syscall filters before the first native operation; a later `ENOSYS` fails with
+`ENOTSUP`, rather than changing the cached mechanism during a call.
+
+The fallback opens each directory relative to a retained descriptor with
+`O_PATH | O_DIRECTORY | O_NOFOLLOW`, compares exact device/inode/type identities,
+and rechecks the retained parent chain before and after the final no-follow
+open. It rejects all symlink components, including procfs magic links, even
+when the low-level caller requests symlink following. Public Root policy and
+canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+identity fences remain in place. `openBeneath()` reports `best-effort`: these
+identity samples detect replacements but cannot make a multi-component walk
+atomic against a hostile process renaming directories between samples. This
+is the same documented containment class as the macOS and JavaScript paths;
+applications requiring atomic beneath resolution must check the result or use
+OS isolation. Rejection after a mutating open does not promise rollback.
+
+Nested no-clobber `Root.move()` still admits both parents and uses
+`renameat2(RENAME_NOREPLACE)`. Existing destinations are never overwritten.
+That separate syscall/filesystem capability remains required; if unavailable,
+the operation fails with `helper-unavailable`. Turning native mode `off` still
+disables no-clobber moves because Node has no equivalent atomic rename API.
+
+Bounded owned-tree cleanup deliberately has no `openat` fallback:
+`RESOLVE_NO_XDEV` rejects bind mounts even when device numbers match, which
+ordinary identity checks cannot reproduce. `cleanupSafety: "require-bounded"`
+fails before workspace creation with `helper-unavailable`; low-level cleanup
+opens report `ENOTSUP`. Compatible cleanup retains its documented behavior.
+Low-level `O_TMPFILE` anonymous opens also fail before creation with `ENOTSUP`
+in the fallback, because named-entry identity checks cannot verify an unnamed
+file. Public staged-write APIs use exclusive named files and remain available.
+
+For tests, set `FS_SAFE_TEST_NO_OPENAT2=1` before starting Node to force the
+fallback (including bounded-cleanup refusal). It is read only at the first
+capability probe. It has no effect on macOS or Windows.
+See [Linux fallback testing](testing.md#linux-openat2-fallback).
+
 ## Archives
 
 Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
@@ -252,7 +296,7 @@ See [Root containment guarantees](security-model.md#containment-guarantees-by-pl
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` on Linux and `best-effort` on macOS and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` with Linux `openat2` and `best-effort` with the guarded Linux fallback, macOS, and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | Rust streaming decode and fd-relative output creation. | Bundled WASM codecs feed the shared Rust TAR parser, then guarded private staging and the same merge policy; no optional codec dependency. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |

package/docs/permissions.md

@@ -185,6 +185,72 @@ the same raw ACE projection. Native `require` rejects either absence with
 query's failure is terminal. The existing coarse `inspectPathPermissions()` API
 still owns its compatibility fallback and trust classification.
 
+### Asynchronous batches
+
+Use `readOwnerAndDaclBatch()` when several paths, such as a directory and its
+ancestors, need inspection without blocking the caller's event loop:
+
+```ts
+import { readOwnerAndDaclBatch } from "@openclaw/fs-safe/permissions";
+
+const facts = await readOwnerAndDaclBatch(stagingDirectories, { timeoutMs: 60_000 });
+```
+
+```ts
+function readOwnerAndDaclBatch(
+  paths: readonly string[],
+  options?: { timeoutMs?: number },
+): Promise<OwnerAndDaclResult[]>;
+```
+
+Results use the same raw fact shape and SID spelling as `readOwnerAndDacl()`.
+They correspond one-for-one to input order, including duplicate paths. An empty
+array returns `[]` without dispatch. Other platforms return an
+`unsupported-platform` result for each path. Query failures, malformed facts,
+or missing/reordered response rows reject the entire batch; no partial facts
+are returned. Null DACLs, incomplete ACE lists and nonlocal observations remain
+raw facts for the caller's policy to evaluate.
+
+The call captures paths, options and native mode before awaiting. Windows
+relative paths are anchored to the current directory or selected drive at
+entry, without normalizing their remaining `.` or `..` components. Empty,
+nonstring, sparse or NUL-containing path entries and Windows namespace aliases
+reject before dispatch. The UTF-8 JSON input is limited to 16 MiB.
+
+An available native capability runs all queries in one isolated process using
+the current runtime executable. Its resolved native mode is forwarded explicitly;
+Node preload and module-search environment overrides are not inherited. An
+available native query's failure is terminal. In `auto` when the binding or
+capability is absent, or in `off`, one packaged PowerShell process reads the
+path array from stdin and compiles the existing C# bridge once. Native `require`
+rejects missing support before launching a process. No route launches one
+process per path or wraps synchronous parent-process queries in promises.
+
+`timeoutMs` defaults to 60,000 and applies to the whole process, including
+startup and fallback compilation. It must be an integer from 1 through
+2,147,483,647. Combined stdout and stderr are limited to 16 MiB. Success waits
+for process exit and both output pipes to close. Timeout and transport failure
+request termination, then retain the existing one-second settlement grace.
+The error's `processExitConfirmed` field, also retained in its cause receipt,
+distinguishes observed exit from an unconfirmed termination attempt. An
+unconfirmed child can still be reading after rejection; the operation returns
+no facts and owns no output files or artifact cleanup. Neither timing out nor
+receiving a successful kill request is reported as confirmed exit.
+
+The PowerShell fallback encodes and budgets each result while collecting it,
+instead of retaining every descriptor graph until the entire batch finishes.
+An encoded response that would exceed 16 MiB rejects with `too-large` before
+inspecting later paths. A query failure observed earlier retains its original
+error, and no partial facts are returned. Duplicate paths remain independent
+observations. This bounds accumulated encoded results, not total process memory:
+the current descriptor and row, decoded input, and runtime overhead still exist.
+
+Batch observations are point-in-time pathname facts, not a snapshot or a
+retained filesystem capability. The caller still owns ancestry trust, principal
+policy and authorization for subsequent operations. Existing singular queries
+and other command operations retain their 30-second deadline, 1 MiB output
+budget and documented failure behavior.
+
 ## Private directories
 
 ```ts

package/docs/public-api.md

@@ -41,6 +41,11 @@ The lexical path surface additionally exports `isNodeError`,
 `UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
 `UnsafeDeviceReadPathReason`.
 
+`isPathRelativeEscape()` rejects absolute paths and relative paths that step
+above their starting directory at any point. Contained paths such as
+`dir/../file` remain relative. It accepts both separators on Windows; on POSIX,
+a backslash remains a literal filename character.
+
 The advanced root-file primitive exports `OpenRootFileParams`,
 `OpenRootFileSyncParams`, `RootFileOpenResult`, and
 `RootFileOpenFailureReason`. These are composition types for callers building
@@ -100,7 +105,8 @@ best-effort cleanup helper used by those queue flows.
 Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
 Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
 descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
-`WindowsAceFlags`.
+`WindowsAceFlags`. `readOwnerAndDaclBatch()` returns those same facts in input
+order through an isolated asynchronous batch with a whole-process timeout.
 
 Secure reads split their option and result shapes into
 `SecureFileTrustOptions`, `SecureFilePermissionOptions`,