@openclaw/fs-safe 0.4.6 → 0.5.0

package/docs/migrating-to-0.5.md

@@ -0,0 +1,196 @@
+---
+title: Migrating to 0.5
+description: "Ordered checklist for moving a 0.4 consumer from the Python helper to native mode and adopting the 0.5 API contracts."
+---
+
+# Migrating from 0.4 to 0.5
+
+Use this checklist from top to bottom. Version 0.5 replaces the Python worker,
+changes the default archive mode policy, and adds explicit contracts for
+publication, walking, locks, secrets, and native-only features. Nothing in this
+guide requires a Rust toolchain: all supported native binaries are prebuilt and
+bundled in `@openclaw/fs-safe`.
+
+## 1. Update the package and runtime
+
+- Run on Node.js 22 or newer.
+- Update `@openclaw/fs-safe` and regenerate every lock or shrinkwrap file your
+  deployment consumes.
+- Keep optional dependencies enabled if you want JavaScript ZIP/TAR support.
+  Native loading no longer depends on optional packages because all seven
+  binaries ship in `@openclaw/fs-safe`. An install that omits optional packages
+  can still import fs-safe, but missing JS archive decoders fail with actionable
+  errors.
+
+If you call `resolveRootPath()` or `resolveRootPathSync()` directly, upgrade to
+0.5: versions through 0.4.7 could approve an in-root symlink traversal that
+resolved outside the root. `root()` handles were not affected. See the
+[affected versions and exposure](security-model.md#affected-versions-exposure).
+
+## 2. Replace Python helper configuration
+
+Change startup configuration before the first filesystem operation:
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });
+```
+
+| Remove from 0.4 | Use in 0.5 |
+|---|---|
+| `configureFsSafePython({ mode })` | `configureFsSafeNative({ mode })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; bundled native binaries do not use an interpreter |
+
+The old names warn once and map `auto`, `off`, or `require` so a shipped 0.4
+deployment does not silently change policy. Interpreter paths are ignored and
+Python is never spawned. Treat that warning as an upgrade diagnostic, not as a
+second supported helper path.
+
+Choose the production mode deliberately:
+
+- `auto` keeps guarded JavaScript fallbacks when a binding is unavailable.
+- `off` makes fallback testing deterministic.
+- `require` fails with `helper-unavailable` instead of weakening an operation
+  that expected native support.
+
+See [Native helper policy](native-helper.md) and
+[Native architecture](native.md).
+
+## 3. Audit every archive call
+
+The 0.5 default is `entryModes: "clamp"`. Directories become `0o755`; files
+become `0o644` or `0o755` when owner-execute was archived. Set
+`entryModes: "preserve"` explicitly only if your 0.4 consumer intentionally
+relied on archived rwx bits. Setuid, setgid, sticky bits, and archived ownership
+are never restored.
+
+```ts
+await extractArchive({
+  archivePath: uploadPath,
+  destDir: restoreRoot,
+  timeoutMs: 30_000,
+  entryModes: "clamp",
+  entryFilter: (entry) =>
+    entry.path.startsWith("snapshot/cache/") ? "skip" : "extract",
+  onFiltered: "skip-entry",
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 64,
+  },
+});
+```
+
+Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
+explicit. Zstd and bzip2 TAR are native-only; ZIP, TAR, and gzip retain guarded
+JavaScript implementations. Catch `ArchiveLimitError` by its code, including
+`archive-entry-path-components-exceeds-limit` for deep implicit-directory
+attacks. See [Archive extraction](archive.md).
+
+## 4. Pick a publication failure policy
+
+`publishFileExclusive()` never replaces an existing target. Choose a strategy
+and decide what a post-create directory-sync failure means to your application:
+
+```ts
+await publishFileExclusive({
+  sourcePath: stagedArchive,
+  targetPath: finalArchive,
+  strategy: "link-or-copy",
+  onSyncFailure: "preserve",
+});
+```
+
+`rollback` is the default: an unchanged target created by this call is removed
+when directory sync throws. `preserve` keeps a complete but possibly
+non-durable target and reports `cleanup: "preserved"` plus
+`directorySync: { status: "failed", code? }` in the typed error. Backup
+archives commonly need `preserve`; transactional protocols that expose only
+durably committed names usually want `rollback`. See
+[Directory durability](durability.md).
+
+## 5. Replace recursive scans with an explicit walk policy
+
+Use `Root.walk()` for caller-controlled relative paths. Every examined entry
+consumes the budget even when filtered:
+
+```ts
+for await (const entry of workspace.walk("memory", {
+  maxDepth: 12,
+  maxEntries: 50_000,
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath.endsWith("/.git")
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    reportIncompleteSubtree(entry.relativePath, entry.error);
+    continue;
+  }
+  indexEntry(entry);
+}
+```
+
+The default directory-error policy remains `throw`. See
+[Directory walking](walk.md).
+
+## 6. Adopt the focused concurrency and secret APIs
+
+- Use `acquireFileLockSync()` only in synchronous boot or migration code; retry
+  waits block the thread. Request-serving paths should use `withFileLock()`.
+- Remove the `allowReentrant` boolean from async file-lock options. If a logical
+  holder intentionally nests acquisition, pass the same operation-scoped
+  `reentrantOwner` string to each acquisition; different or missing owners
+  contend normally. Never replace the boolean with a process-wide constant.
+  Locked and unlocked `jsonStore` mutations serialize by canonical file path
+  and do not opt into lock reentrancy; nested same-file mutations from an update
+  callback fail with `store-reentrant-update`, so return the complete value from
+  the outer callback instead.
+- Use `createSecretFileAtomic()` for first-writer-wins credentials and catch
+  `secret-exists`; use `writeSecretFileAtomic()` only when replacement is the
+  intended protocol.
+- Async `readSecretFile()` is strict; `tryReadSecretFile()` returns `undefined`
+  only for missing or blank content and still rejects suspicious files.
+- Check `tempWorkspace.cleanup()` results when ownership matters;
+  `identity-mismatch` deliberately preserves a replacement path.
+
+See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
+[Temp workspaces](temp.md).
+
+## 7. Gate native-only features
+
+`createPrivateDirectory()` is Windows-only and native-only because a pathname
+fallback cannot promise the same creation-time DACL. Zstd/bzip2 extraction and
+`strategy: "rename-noreplace"` are also native-only. Test the unavailable path
+instead of assuming installation always succeeds.
+
+## 8. Run both behavior families in CI
+
+For each consumer workflow that matters:
+
+1. Run once with `FS_SAFE_NATIVE_MODE=auto` on every supported OS.
+2. Run once with `FS_SAFE_NATIVE_MODE=off` to prove the JavaScript fallback.
+3. Run native-required or native-only cases with `FS_SAFE_NATIVE_MODE=require`.
+4. Exercise archive traversal/link/depth limits, publication sync failure, and
+   partial-walk reporting with production-shaped fixtures.
+
+For downstream staging and backup consumers:
+
+- [ ] Replace private whole-file hashing with `sha256File(path | FileHandle)`
+      from `durability`; native mode keeps digest work off the event loop and
+      the JavaScript fallback remains streaming.
+- [ ] If Windows trust policy depends on exact principals, consume
+      `readOwnerAndDacl()` from `permissions`, reject incomplete/null/remote
+      descriptors as your policy requires, skip inherit-only ACEs where
+      appropriate, and apply the application's own SID allowlist.
+
+The [Testing](testing.md) page documents the test hooks and mode setup used by
+fs-safe itself.

package/docs/native-helper.md

@@ -0,0 +1,85 @@
+---
+title: Native helper policy
+description: "How fs-safe loads its bundled native filesystem primitives and how auto, require, and off affect guarded fallbacks."
+---
+
+# Native helper policy
+
+`@openclaw/fs-safe` itself contains seven prebuilt binaries for Linux x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. The loader selects `dist/native/<target>/fs-safe-native.node` without optional platform packages, downloads, postinstall scripts, or a consumer Rust build. Carrying every target makes the npm tarball larger, but every installation receives the same complete artifact.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
+```
+
+The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_SAFE_NATIVE_MODE`. Accepted values are `auto`, `off`, `require`, `true`, `false`, `on`, `never`, `required`, `1`, and `0`.
+
+## Modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Prefer native primitives when the current bundled binary loads; otherwise silently use the guarded JavaScript path. |
+| `off` | Do not load a bundled binary. Use the guarded JavaScript path deterministically. |
+| `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
+
+Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
+
+## Native boundary
+
+The bundled native layer exposes policy-free filesystem mechanisms: beneath-root
+open/mkdir/link, no-replace rename, identity reads, archive decode/execution,
+clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
+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` and `renameat2(RENAME_NOREPLACE)`.
+- 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. No-replace publication uses `renameatx_np(RENAME_EXCL)`.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement disabled.
+
+Native primitives back create-only pinned writes, async sidecar creation,
+guarded publication, archive acceleration, and direct Windows ACL operations.
+Equivalent JavaScript paths remain available for documented fallback-capable
+features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
+for the exact difference.
+
+`openBeneath()` returns `{ fd, containment }`. `containment` is
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+Windows. Public JavaScript root open/read/writable results also expose the
+field and report `"best-effort"`; the label reports mechanism, not policy.
+
+## Migration from the Python helper
+
+Version 0.5 removes the Python worker and interpreter-path selection. The mode
+contract is unchanged, so migrate startup configuration directly:
+
+| Python helper configuration | Native replacement |
+|---|---|
+| `configureFsSafePython({ mode: "auto" })` | `configureFsSafeNative({ mode: "auto" })` |
+| `configureFsSafePython({ mode: "off" })` | `configureFsSafeNative({ mode: "off" })` |
+| `configureFsSafePython({ mode: "require" })` | `configureFsSafeNative({ mode: "require" })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, and the OpenClaw interpreter-path aliases | Remove; prebuilt bindings do not use an interpreter path |
+
+In 0.5, `configureFsSafePython` and the legacy Python environment names
+remain only as an upgrade bridge. On the first config read they emit one
+`DeprecationWarning` with code `FS_SAFE_PYTHON_DEPRECATED`, state the mapped
+native mode, and then apply that mode. A legacy interpreter path without an
+explicit mode maps to `auto` and the path itself is ignored. Native config has
+the normal precedence over legacy environment config.
+
+There is no silent alias and no Python execution fallback. The bridge exists
+only to make shipped 0.4 configuration visible and predictable while the
+consumer performs its 0.5 upgrade.
+
+## Related pages
+
+- [Config](config.md)
+- [Security model](security-model.md)
+- [Writing](writing.md)
+- [File locks](sidecar-lock.md)
+- [Durability](durability.md)
+- [Migrating to 0.5](migrating-to-0.5.md)

package/docs/native.md

@@ -0,0 +1,134 @@
+---
+title: Native architecture
+description: "The bundled native bindings, fd-relative beneath model, platform mechanisms, loader security, and JavaScript fallback contract."
+---
+
+# Native architecture
+
+`@openclaw/fs-safe` bundles native bindings that supply mechanisms Node does
+not expose directly. The Rust layer is deliberately not a second policy engine.
+TypeScript owns trusted-root selection, path validation, archive filtering,
+budgets, modes, identity fencing, cleanup decisions, and error normalization.
+Rust receives already-decided relative operations and performs the smallest
+platform syscall sequence that can preserve the boundary.
+
+Every operation that has an equivalent safe Node implementation keeps that
+guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
+run postinstall code, or fetch binaries. The npm tarball carries all seven
+supported targets, so it is larger than a per-platform package by design.
+Native-only formats and creation-time Windows DACL guarantees fail explicitly
+instead of substituting a weaker implementation.
+
+## The beneath model
+
+A trusted directory descriptor is the capability. Native operations accept
+that descriptor plus a validated relative path and never reconstruct authority
+from a process working directory. Newly created files use exclusive creation,
+and TypeScript compares descriptor, pathname, and expected identities before
+accepting results.
+
+Conceptually, a caller grants authority to an already-open root—not to a path
+string that can be reinterpreted later:
+
+```text
+validated Root handle
+  └─ relative components (untrusted)
+       └─ open/link/mkdir beneath the handle
+            └─ compare descriptor + pathname + expected identity
+```
+
+The TypeScript layer validates and decides. The native layer never decides
+whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
+
+- Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
+  `mkdirat`/`linkat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+- 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,
+  but directory rename races mean the result remains `best-effort`, not
+  race-atomic. macOS uses `renameatx_np(RENAME_EXCL)` and permits
+  `fclonefileat` in an owned, non-shared parent. The clone is normalized inside
+  a private staging directory: flags, ACLs, extended attributes, and broad mode
+  bits are cleared before no-replace publication.
+- Windows uses handle-relative `NtCreateFile` with `OBJ_DONT_REPARSE` and
+  `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
+  hardlink operations stay rooted in already-open handles. Owner/DACL reads
+  use `GetSecurityInfo`; private directories receive their protected DACL in
+  the `CreateDirectoryW` call itself.
+
+## Archives
+
+Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
+returns a bounded manifest. TypeScript applies the shared path, filter, strip,
+mode, and byte policies and returns an index-bound extraction plan. Rust then
+creates only those planned entries beneath a private staging descriptor.
+
+A fixed-512-byte pass-through meter sits between decompression and the TAR
+crate. It reads only header type and octal/base-256 size fields. It never parses
+metadata content. Oversized GNU long-name/link metadata is rejected before
+buffering; PAX size overrides and GNU sparse entries are rejected as
+unmeterable rather than guessed. The JavaScript node-tar path receives the same
+`maxMetaEntryBytes` value and a matching fixed-header preflight.
+
+## Publication and hashing
+
+Exclusive publication tries a hardlink, then a copy-on-write clone, Linux
+`copy_file_range`, and finally the existing asynchronous JavaScript byte loop.
+All routes preserve `wx` semantics and the same source/target identity and
+SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
+workers rather than the JavaScript event loop.
+
+## Mode semantics
+
+| Mode | Native loading | Fallback |
+|---|---|---|
+| `auto` | Try once, cache the result | Use guarded JavaScript when unavailable |
+| `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
+| `off` | Never attempt a binding load | Always use guarded JavaScript |
+
+The one exception is functionality with no safe JavaScript implementation:
+zstd/bzip2 TAR and Windows private-directory creation fail with
+`helper-unavailable` when native support is absent or off.
+
+## JavaScript fallback guarantees and delta
+
+Public policy does not change with the selected mechanism: traversal and link
+rejection, archive filters/limits/modes, exclusive target creation, source and
+target identity fencing, publication cleanup receipts, and secret/lock policy
+remain TypeScript-owned. What changes is the syscall strength or availability:
+
+| Capability | Native path | Guarded JavaScript path |
+|---|---|---|
+| Root-relative opens/mutations | Descriptor-relative beneath operations. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. 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. A hostile same-UID peer has a wider pathname race window. |
+| ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | JSZip/node-tar into a private stage, then the same guarded merge policy. |
+| Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
+| 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. |
+| `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. | Established .NET/`icacls` inspection fallback for coarse permission checks; raw ACE facts are native-only. |
+| Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
+
+Use `off` in CI to keep the fallback contract exercised. Use `require` when a
+deployment depends on the stronger mechanism or a native-only feature; do not
+infer native loading from timing.
+
+## Loader security
+
+Importing fs-safe never executes a child process. Linux libc selection uses
+the Node process report, conventional musl library filenames, and the ELF
+`PT_INTERP` field of `process.execPath`. If all probes are inconclusive, the
+loader conservatively attempts the bundled glibc binary and lets normal module
+loading fail into `auto` fallback. The loader requires only
+`dist/native/<target>/fs-safe-native.node`; it never probes optional packages,
+downloads code, or runs a postinstall step. A missing or incompatible binary
+silently selects the JavaScript fallback in `auto`, throws typed
+`helper-unavailable` in `require`, and is never inspected in `off`. Tests reject
+`child_process`, `exec`, or `spawn` usage in the loader.
+
+## Related pages
+
+- [Native helper policy](native-helper.md)
+- [Security model](security-model.md)
+- [Archive extraction](archive.md)
+- [Durability](durability.md)
+- [Permissions](permissions.md)
+- [Migrating to 0.5](migrating-to-0.5.md)

package/docs/output.md

@@ -16,10 +16,10 @@ await writeExternalFileWithinRoot({
 });
 ```
 
-The external writer never receives the final destination path. It receives a
-private temp file path instead. After the callback returns, fs-safe copies that
-staged file into the requested target through the same root boundary used by
-`Root.copyIn()`.
+The external writer receives a staged path instead of the final destination.
+The default private-workspace mode finalizes through `Root.copyIn()`. An
+opt-in sibling mode stages in the destination directory and atomically renames
+the completed file over the target.
 
 ## Signature
 
@@ -34,6 +34,8 @@ type ExternalFileWriteOptions<T = void> = {
   write: (filePath: string) => Promise<T>;
   maxBytes?: number;
   mode?: number;
+  staging?: "workspace" | "sibling"; // default: "workspace"
+  fallbackFileName?: string;          // safe staged-name fallback
 };
 
 type ExternalFileWriteResult<T = void> = {
@@ -46,18 +48,42 @@ The requested `path` must name a file. Missing destination parents are created
 by the helper because the operation is "produce this output file under the
 root"; callers should choose the filename before calling this API.
 
-Use `maxBytes` when the external producer can create arbitrarily large files.
-Use `mode` when the finalized file needs a specific POSIX mode. Both are
-enforced during the `Root.copyIn()` finalization step, after the external writer
-has produced the staged file and before the final target is committed.
+Use `maxBytes` when the external producer can create arbitrarily large files,
+and `mode` when the finalized file needs a specific POSIX mode. Both staging
+modes enforce them after the producer returns and before committing the target.
+Requested basenames containing C0/C1 controls or Windows-invalid characters are
+sanitized portably; `fallbackFileName` supplies the name when nothing remains.
+The same sanitized basename is used for producer staging, guarded internal
+temps, the final rename target, and the returned `path`; raw and staged names
+never diverge.
+
+## Choosing a staging mode
+
+`staging: "workspace"` is the default. The producer writes in private temp
+storage, then fs-safe copies through the guarded root boundary. Choose it when
+the temp and destination filesystems may differ, or when an externally produced
+partial file must never appear in the destination directory. The final target
+still appears only after guarded finalization.
+
+`staging: "sibling"` gives the producer a randomized temp path in the target
+directory. Choose it only when that directory itself is the approved writable
+boundary and same-filesystem atomic replacement is required. After the callback
+returns, fs-safe pins and validates the staged regular file, rejects hardlinks
+and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
+over the target. Existing files and symlink entries are replaced without
+following their contents or referents. The parent identity is guarded across
+the operation and the parent directory is synchronized best-effort after
+rename.
 
 ## Why not pass the final path to the library?
 
 If a target parent can be swapped after validation, handing an external library
 the final path can make the library write outside the intended root before
-fs-safe has a chance to finalize or reject the operation. This helper stages in
-a private temp workspace first, then finalizes with `Root.copyIn()`. That keeps
-the trust-boundary write inside fs-safe's root-aware copy/atomic-write path.
+fs-safe has a chance to finalize or reject the operation. Workspace staging
+keeps the trust-boundary write inside fs-safe's root-aware copy/atomic-write
+path. Sibling staging intentionally shifts the writable boundary to the
+destination directory, while keeping pathname validation, staged-file identity
+checks, and the final rename under fs-safe's control.
 
 ## Browser download example
 

package/docs/path.md

@@ -19,7 +19,7 @@ import {
 } from "@openclaw/fs-safe/path";
 ```
 
-Only `root()`, `FsSafeError`, and the Python helper config live on the main entry. Path helpers are deliberately a subpath import so the main entry stays small.
+Only `root()`, `FsSafeError`, and the native helper config live on the main entry. Path helpers are deliberately a subpath import so the main entry stays small.
 
 ## Boundary checks
 

package/docs/permissions.md

@@ -64,7 +64,88 @@ createIcaclsResetCommand(targetPath, { isDir, env });
 resolveWindowsUserPrincipal(env);
 ```
 
-The default Windows inspector calls `icacls.exe /sid` and classifies principals as trusted, world, or group. Trusted defaults include the current user, SYSTEM, and Administrators. The parser is on the advanced surface so tests and CLIs can process captured `icacls` output without spawning a process.
+The fallback Windows inspector calls `icacls.exe <path>` using its supported
+path-only inspection syntax and classifies principals as trusted, world, or
+group. Trusted defaults include the current user, SYSTEM, and Administrators.
+The parser is on the advanced surface so tests and CLIs can process captured
+`icacls` output without spawning a process.
+
+When the bundled native binding is available, `inspectPathPermissions()`
+reads the owner and DACL directly with Windows security APIs. It classifies the
+current user, LocalSystem, and built-in Administrators as trusted and reports
+the world/group read/write facts consumed by secure reads. Descriptor forms it
+cannot classify equivalently fall back to the established owner/.NET and
+`icacls` path; `mode: "off"` exercises that fallback deterministically.
+
+## Policy-free owner and DACL facts
+
+`readOwnerAndDacl()` exposes the direct Windows descriptor facts needed by a
+consumer that owns a principal allowlist. It deliberately does not decide
+which SID is trusted or calculate effective access. For example, snapshot
+staging can reject an incomplete descriptor and ignore inherit-only ACEs before
+applying its own exact SID policy:
+
+```ts
+import { readOwnerAndDacl } from "@openclaw/fs-safe/permissions";
+
+const facts = readOwnerAndDacl(stagingDirectory);
+if (facts.status === "unsupported-platform") {
+  throw new Error(`Windows ACL facts unavailable on ${facts.platform}`);
+}
+if (!facts.isLocal || !facts.daclPresent || !facts.complete) {
+  throw new Error("staging DACL cannot be evaluated completely");
+}
+
+for (const ace of facts.aces) {
+  if (ace.flags.inheritOnly) continue;
+  if (!trustedSids.has(ace.sid)) {
+    throw new Error(`unexpected staging principal: ${ace.sid}`);
+  }
+  evaluateMaskAndDenyOrder(ace.aceType, ace.mask);
+}
+```
+
+On Windows the supported result contains `ownerSid`, `currentUserSid`,
+`daclPresent`, `isLocal`, `complete`, `unsupportedAceTypes`, and ordered basic
+allow/deny `aces`. `currentUserSid` is the process token's `TokenUser` SID, so
+callers can compare it with the owner or their own allowlist without fs-safe
+applying trust policy. Each ACE has `{ sid, mask, aceType, flags }`; `flags`
+retains the raw byte and decoded
+`objectInherit`, `containerInherit`, `noPropagateInherit`, `inheritOnly`,
+`inherited`, `successfulAccess`, and `failedAccess` facts. SID strings are
+lowercase Windows SID notation. `daclPresent: false` represents a null DACL,
+which grants unrestricted access; it must not be mistaken for an empty DACL.
+
+Object-specific and other ACE layouts are not guessed: they are omitted,
+`complete` becomes false, and their numeric types appear in
+`unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
+Non-Windows systems return `{ status: "unsupported-platform", platform }`.
+Windows requires the bundled native binding; if it is unavailable or forced
+off, the call throws `FsSafeError("helper-unavailable")`. The existing coarse
+`inspectPathPermissions()` API still owns its compatibility fallback and trust
+classification.
+
+## Private directories
+
+```ts
+import path from "node:path";
+import { createPrivateDirectory } from "@openclaw/fs-safe/permissions";
+
+const sqliteDirectory =
+  "C:\\Users\\me\\AppData\\Local\\OpenClaw\\private-databases";
+await createPrivateDirectory(sqliteDirectory);
+await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
+```
+
+On Windows with native support, this creates the directory and applies a
+protected owner + LocalSystem + Administrators full-control DACL directly with
+an atomic security descriptor; no PowerShell or `icacls` process is launched.
+This API is Windows-only and native-only; it fails closed with
+`FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
+or when the binding is unavailable. POSIX callers should create private
+directories through their existing trusted-root creation policy rather than a
+pathname-only compatibility shim. Existing Windows permission inspection still
+retains its .NET/`icacls` compatibility fallback.
 
 Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
 
@@ -96,3 +177,5 @@ type PermissionCheck = {
 
 - [Secure file reads](secure-file.md) — fd-pinned reads that enforce these checks.
 - [Errors](errors.md) — permission-related `FsSafeError` codes.
+- [Native architecture](native.md) — direct Windows security descriptor mechanisms.
+- [Migrating to 0.5](migrating-to-0.5.md) — native-only feature checklist.

package/docs/quickstart.md

@@ -67,7 +67,7 @@ const names = await fs.list("state");              // string[]
 const entries = await fs.list("state", { withFileTypes: true }); // DirEntry[]
 ```
 
-`exists`, `stat`, and `list` are boundary-checked but **do not pin a later operation** to the same filesystem object. For race-resistant reads or writes, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` — they pin the path identity at the point of use.
+`exists`, `stat`, and `list` are boundary-checked but **do not pin a later operation** to the same filesystem object. For operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. Linux native beneath opens are kernel-atomic; other mechanisms remain best-effort as documented in the [security model](security-model.md#containment-guarantees-by-platform).
 
 ## 6. Catch escapes
 
@@ -121,7 +121,10 @@ await extractArchive({
     maxEntries: 50_000,
     maxExtractedBytes: 512 * 1024 * 1024,
     maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 64,
   },
+  entryModes: "clamp",
 });
 ```
 
@@ -133,7 +136,7 @@ Extraction stages into a private dir and merges through the same boundary used b
 import { withTempWorkspace } from "@openclaw/fs-safe/temp";
 
 await withTempWorkspace({ rootDir: "/srv/jobs/tmp", prefix: "build-" }, async (workspace) => {
-  await fs.copyIn("input.bin", "/tmp/source.bin");
+  await workspace.copyIn("input.bin", "/tmp/source.bin");
   // ...do work in workspace.dir; auto-cleaned on exit
 });
 ```

package/docs/reading.md

@@ -3,7 +3,7 @@
 The `Root` handle exposes five read shapes. Pick the narrowest one that gives you what you need — narrower shapes do less work and surface fewer footguns.
 
 ```ts
-const result = await fs.read("notes/today.txt");        // { buffer, realPath, stat }
+const result = await fs.read("notes/today.txt");        // { buffer, containment, realPath, stat }
 const text   = await fs.readText("notes/today.txt");    // string
 const bytes  = await fs.readBytes("image.png");         // Buffer
 const json   = await fs.readJson<Config>("config.json"); // T
@@ -30,7 +30,7 @@ Regardless of shape, every read goes through the same boundary checks:
 The full result. Use it when you need both the bytes and the verified `realPath` or `stat`:
 
 ```ts
-const { buffer, realPath, stat } = await fs.read("notes/today.txt");
+const { buffer, containment, realPath, stat } = await fs.read("notes/today.txt");
 console.log(`${stat.size} bytes at ${realPath}`);
 ```
 
@@ -63,7 +63,7 @@ For tighter control over malformed-or-missing JSON, use the standalone helpers i
 
 ### `fs.open(rel, options?)`
 
-Returns a `FileHandle` plus the verified `realPath` and `stat`. Use this for streaming or partial reads, and **always close the handle**:
+Returns a `FileHandle` plus `containment: "best-effort"`, the verified `realPath`, and `stat`. Use this for streaming or partial reads, and **always close the handle**:
 
 ```ts
 const opened = await fs.open("large.log");
@@ -121,7 +121,7 @@ if (await fs.exists("notes/today.txt")) {
 }
 ```
 
-A symlink swap between `exists` and `readText` is caught by the read; the boundary is per-call.
+A symlink swap between `exists` and `readText` is checked again by the read; the boundary and its documented race window are per-call.
 
 ## Streaming patterns