@openclaw/fs-safe 0.4.7 → 0.5.0

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
 

package/docs/root.md

@@ -44,15 +44,30 @@ Every method on the returned handle accepts paths relative to the root and rejec
 ### Reads
 
 ```ts
-fs.read(rel, options?)         // { buffer, realPath, stat }
+fs.read(rel, options?)         // { buffer, containment, realPath, stat }
 fs.readBytes(rel, options?)    // Buffer
 fs.readText(rel, options?)     // string
 fs.readJson<T>(rel, options?)  // parsed T
-fs.open(rel, options?)         // { handle, realPath, stat, [Symbol.asyncDispose] }
+fs.open(rel, options?)         // { handle, containment, realPath, stat, [Symbol.asyncDispose] }
 fs.readAbsolute(absPath, options?) // ReadResult; absPath must already be inside the root
 fs.reader(options?)            // (path) => Promise<Buffer>; useful for loader APIs
+fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kind, size }>
 ```
 
+`walk()` is the incremental, root-bounded recursive scan. It supports entry and
+depth budgets, cancellation, and `symlinkPolicy: "skip" |
+"follow-within-root"`. Budget exhaustion yields a `"truncated"` marker by
+default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
+Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
+`"skip-subtree"`. `"skip"` omits the current entry but still descends into a
+directory; `"skip-subtree"` omits a directory and all of its descendants.
+Directory reads remain fail-fast by default. With
+`onDirectoryError: "skip-and-report"`, the iterator instead yields
+`{ relativePath, kind: "directory-error", size: 0, error }` and continues with
+the remaining tree.
+See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
+with the standalone best-effort walkers.
+
 `open()` returns a Node `FileHandle` for streaming. Prefer `await using` for cleanup:
 
 ```ts
@@ -64,6 +79,10 @@ await using opened = await fs.open("large.log");
 }
 ```
 
+`open()`, `read()`, and `openWritable()` results include
+`containment: "best-effort"`. The field reports the mechanism used; see the
+[security model](security-model.md#containment-guarantees-by-platform).
+
 ### Writes
 
 ```ts
@@ -100,25 +119,22 @@ fs.resolve(rel)                  // absolute path inside the root, after canonic
 
 These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
 
-## Python helper mode
+## Native helper mode
 
-On POSIX, mutation and inspection methods that need fd-relative directory
-operations go through one persistent Python helper process. This avoids a
-spawn-per-call cost while still using `openat`/`renameat`/`unlinkat`-style
-operations that Node's `fs` API does not expose ergonomically.
+Create-only writes prefer the bundled native helper for fd-relative opens and
+atomic no-replace rename. Operations without native wiring retain their guarded
+JavaScript implementations.
 
 ```ts
-import { configureFsSafePython } from "@openclaw/fs-safe/config";
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
-configureFsSafePython({ mode: "off" });     // Node-only fallback path
-configureFsSafePython({ mode: "require" }); // fail if fd-relative helper unavailable
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript path
+configureFsSafeNative({ mode: "require" }); // fail if the binding is unavailable
 ```
 
-`auto` is the default. Configure the mode before creating roots. Without the
-helper, root methods still run, but same-UID races that swap parent directories
-between validation and mutation are harder to close completely. Use `require`
-when that downgrade should be treated as a deployment failure. See
-[Python helper policy](python-helper.md) for deployment guidance.
+`auto` is the default. Configure the mode before creating roots. See the
+[native helper policy](native-helper.md) for supported platforms, the native
+surface, and the precise fallback boundary.
 
 ### Properties
 

package/docs/secret-file.md

@@ -4,7 +4,10 @@ Helpers for reading and writing credentials. Files are written at mode `0o600`,
 
 ```ts
 import {
+  createSecretFileAtomic,
+  readSecretFile,
   readSecretFileSync,
+  tryReadSecretFile,
   tryReadSecretFileSync,
   writeSecretFileAtomic,
   DEFAULT_SECRET_FILE_MAX_BYTES,
@@ -54,7 +57,7 @@ if (token) {
 Strict reader. Throws `FsSafeError` when the file is missing, too large, empty, unreadable, or rejected by the validation checks. Use when failing loudly is the right call:
 
 ```ts
-const token = readSecretFileSync("/var/lib/app/auth.token");
+const token = readSecretFileSync("/var/lib/app/auth.token", "auth token");
 ```
 
 ### Read options
@@ -69,6 +72,24 @@ type SecretFileReadOptions = {
 
 The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read. Hardlinks are rejected by default so another in-tree name cannot alias the credential; pass `rejectHardlinks: false` only when you explicitly trust that layout.
 
+`readSecretFile()` and `tryReadSecretFile()` are asynchronous counterparts with
+the same pinned-handle validation, byte cap, trimming, error codes, and strict
+versus missing-is-undefined naming semantics.
+
+Use the async strict reader when a service cannot start safely without the
+credential:
+
+```ts
+import { readSecretFile } from "@openclaw/fs-safe/secret";
+
+const signingKey = await readSecretFile(
+  "/var/lib/app/keys/webhook-signing.key",
+  "webhook signing key",
+  { maxBytes: 8 * 1024, rejectSymlink: true },
+);
+startWebhookVerifier(signingKey);
+```
+
 ## Writing
 
 ### `writeSecretFileAtomic(params)`
@@ -99,6 +120,33 @@ type WriteSecretFileParams = {
 
 The directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. The helper enforces that every component matches `dirMode` — wider permissions on an existing directory cause the write to fail. Audit and tighten existing secret directories yourself.
 
+### `createSecretFileAtomic(params)`
+
+This create-only sibling has the same directory, mode, pinned-write, and
+post-write verification policy. Final materialization uses exclusive create;
+if anything already occupies the target path it throws
+`FsSafeError("secret-exists")` without modifying that entry. Use the distinct
+name when first-writer-wins is part of the credential protocol.
+
+For example, two onboarding requests may race to install the first refresh
+token. Exactly one should win, and the loser must not overwrite it:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+import { createSecretFileAtomic } from "@openclaw/fs-safe/secret";
+
+try {
+  await createSecretFileAtomic({
+    rootDir: "/var/lib/app/credentials",
+    filePath: "/var/lib/app/credentials/provider.refresh-token",
+    content: refreshToken,
+  });
+} catch (error) {
+  if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;
+  // Another initializer won. Read and validate the installed credential.
+}
+```
+
 For more permissive credentials, override `mode`:
 
 ```ts
@@ -153,3 +201,4 @@ await withTimeout(
 - [JSON files](json.md) — `writeJson` accepts `mode: 0o600` for non-secret JSON state.
 - [Atomic writes](atomic.md) — the lower-level `replaceFileAtomic` used by these helpers.
 - [Private file-store mode](private-file-store.md) — root-bounded JSON+text stores using secret-file write policy.
+- [Migrating to 0.5](migrating-to-0.5.md) — strict/try reads and create-only adoption checklist.

package/docs/security-model.md

@@ -4,6 +4,19 @@
 
 The same shape exists in other languages: Go's [`os.Root` / `OpenInRoot`](https://go.dev/blog/osroot) and Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std) both expose a root handle whose operations refuse to escape it. `fs-safe` is the Node-side equivalent: a single `root()` capability that carries the boundary across every read, write, move, and remove, instead of leaving each call site to redo `path.resolve(...).startsWith(...)` and hope.
 
+## Affected versions / exposure
+
+In published releases through 0.4.7, the exported `resolveRootPath()` and
+`resolveRootPathSync()` helpers validated a lexically normalized path spelling.
+A caller-supplied path traversing an in-root symlink could therefore pass
+validation while resolving outside the root. Version 0.5 fixes this with
+component-wise alias resolution, resolving each alias before applying later
+path components.
+
+`root()` handles were **not** affected: their operations have contained this
+case since `5ddca80`. Exposure is limited to consumers that call
+`resolveRootPath()` or `resolveRootPathSync()` directly.
+
 ## Threat model
 
 You hand a `root()` boundary to a piece of code that takes caller-controlled relative paths. The library defends against a caller that:
@@ -31,7 +44,7 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-Every relative path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Inputs containing `..`, leading `/` (without `pathScope` opt-in), or that resolve outside the root throw `outside-workspace`.
+Every relative path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal that escapes, leading `/` (without `pathScope` opt-in), or any canonical result outside the root throws `outside-workspace`.
 
 ### Symlinks (read side)
 
@@ -49,7 +62,7 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 ### TOCTOU between resolve and use
 
-`resolve()`, `exists()`, `stat()`, and `list()` are explicitly **not** race-resistant — they answer a question and return. To act on a path with race resistance, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. They re-pin the path identity at the point of use.
+`resolve()`, `exists()`, `stat()`, and `list()` are explicitly advisory — they answer a question and return. To act on a path with operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. The containment table below states which opens are kernel-atomic and which remain best-effort.
 
 ### Denied mutations
 
@@ -84,12 +97,20 @@ A library cannot revoke its own caller's authority. If your code chooses to bypa
 
 The library does not modify or constrain the global Node.js `fs` namespace, and it does not patch the runtime. Other code in the same process retains its normal filesystem authority.
 
-## Platform notes
+## Containment guarantees by platform
+
+`openBeneath()` and JavaScript open results report one of two factual containment classes:
+
+| Mechanism | Reported containment | Boundary |
+|---|---|---|
+| Linux native | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| macOS native | `best-effort` | macOS 15.4 and newer use `O_RESOLVE_BENEATH` first; older kernels use the guarded `openat(O_NOFOLLOW)` component walk. Both verify the opened descriptor with `F_GETPATH`. |
+| Windows native | `best-effort` | Handle-relative `NtCreateFile` rejects reparse points, but this package does not claim a Linux-style atomic beneath guarantee. |
+| JavaScript fallback | `best-effort` | Canonical checks, no-follow opens where Node exposes them, and post-open identity checks form a check-then-use sequence. |
 
-- **POSIX (Linux, macOS):** Best-defended path. Uses `O_NOFOLLOW`, fd identity checks, and one persistent Python helper process for fd-relative `unlinkat` / `mkdirat` / `renameat` / parent-fd write operations. Configure `FS_SAFE_PYTHON_MODE=require` when helper startup must fail closed, or `off` when you need a no-Python runtime. See [Python helper policy](python-helper.md).
-- **Windows:** Falls back to the safest Node-level behavior available. `O_NOFOLLOW` is not honored. Some fd-relative POSIX hardening is unavailable. The library does the path canonicalization, identity, and atomic-rename checks it can.
+The macOS `F_GETPATH` verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after `O_RESOLVE_BENEATH` or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains `best-effort` on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.
 
-The library does not advertise different security guarantees per platform — it advertises the same surface and relies on the strongest mechanism the platform offers.
+The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containment`. Those root APIs currently report `best-effort`; direct native `openBeneath()` reports the platform value above. No-replace publication uses `renameat2(RENAME_NOREPLACE)` on Linux, `renameatx_np(RENAME_EXCL)` on macOS, and `FileRenameInfoEx` with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.
 
 ## Limitations to keep in mind
 
@@ -98,11 +119,11 @@ The library does not advertise different security guarantees per platform — it
 | Not ambient authority removal | Code that can import `node:fs` can still bypass the handle. Keep caller-controlled path operations behind `root()` by convention, review, and tests. |
 | Absolute paths are escape hatches | APIs that accept or return absolute paths exist for audit, ingest, and advanced composition. Prefer root-relative names in normal application flow. |
 | Not a mount boundary | `root()` keeps path traversal inside the directory tree and blocks known unsafe read device paths, but it does not make bind mounts or virtual filesystems safe to expose wholesale. |
-| Per-call, not per-session | Another process with the same privileges can still mutate the tree between two separate calls. Use one verb method for the operation you need to make race-resistant. |
+| Per-call, not per-session | Another process with the same privileges can still mutate the tree between calls, and best-effort mechanisms retain documented same-call race windows. Use one verb method to minimize the window and inspect its reported containment class. |
 | Hardlink rejection is best-effort | Link-count checks depend on platform metadata. Treat `hardlinks: "reject"` as a tripwire, not an authorization primitive. |
 | Mode bits are not a full policy engine | `replaceFileAtomic` and secret-file helpers set requested modes, but you should still set umask and inspect modes when policy requires it. |
 | Archive extraction is path safety, not content safety | Unsafe entry paths and links are rejected; malicious payload contents remain your application layer's problem. |
-| Helper failures degrade fd-relative hardening | `helper-unavailable` falls back in `auto` mode and fails closed in `require` mode. Atomicity and identity checks remain, but parent-directory swaps between validation and mutation are less tightly pinned without the helper. |
+| Native package unavailable | `helper-unavailable` falls back in `auto` mode and fails closed in `require` mode for native-backed operations. Guarded JavaScript atomicity and identity checks remain. |
 | FUSE mounts with rename-unstable inode numbers | Some FUSE mounts (rclone is a confirmed example) do not preserve source inode identity at the rename destination. The explicit `renameIdentity: "verify-content-with-lock"` compatibility mode verifies content under a cooperative lock for that boundary only; subsequent path identity checks and the default remain strict. See [Writing](writing.md) for the weaker opt-in contract. |
 
 ## Recommended deployment shape