@openclaw/fs-safe 0.6.0 → 0.7.1

package/docs/archive.md

@@ -23,7 +23,7 @@ await extractArchive({
   archivePath: "/srv/uploads/plugin.zip",
   destDir: "/srv/workspace/plugins/plugin",
   kind: "zip",                        // optional; resolveArchiveKind() can infer
-  timeoutMs: 15_000,                  // hard ceiling for the whole extraction
+  timeoutMs: 15_000,                  // hard budget; active destination mutation is joined
   stripComponents: 0,                 // tar-style strip-leading-dirs
   entryModes: "clamp",                // default; use "preserve" for archive rwx bits
   entryFilter: ({ path, kind, size }) => "extract",
@@ -45,7 +45,7 @@ await extractArchive({
 type ExtractArchiveOptions = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
-  timeoutMs: number;            // positive wall-clock cap; <= 0/non-finite disables it
+  timeoutMs: number;            // positive wall-clock budget; <= 0/non-finite disables it
   kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
@@ -68,8 +68,8 @@ private staging tree; ZIP applies the same policy to `unixPermissions`.
 Native extraction is deliberately split into two phases. Rust first reports an
 entry manifest without creating paths. TypeScript validates paths, applies
 `stripComponents`, filters, limits, and mode policy, then passes an explicit
-accepted-entry plan back to Rust. Rust only performs decompression and the
-fd-relative `mkdirBeneath`/exclusive-open writes. This keeps policy identical
+accepted-entry plan back to Rust. Rust owns raw-stream admission, decompression,
+and fd-relative `mkdirBeneath`/exclusive-open writes. This keeps filter policy identical
 between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected.
@@ -82,11 +82,29 @@ toward `maxEntries` and undergo traversal validation. JavaScript TAR extraction
 passes node-tar this accepted output path with its own stripping disabled, so
 depth checks, collision checks, writes, and mode application agree.
 
-An `entryFilter` sees the validated effective archive path **before stripping**
-(including a local PAX `path` override), entry kind, and declared size.
+An `entryFilter` sees the validated **canonical effective archive path before
+stripping**, entry kind, and declared size. On every JavaScript and native
+ZIP/TAR backend (including gzip and native zstd/bzip2), backslashes become `/`,
+empty and `.` components are removed, and trailing separators are removed from
+directory paths. For example, `./pkg//state\cache/value` is presented as
+`pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
+spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
+Unicode Path names use the same canonicalization.
+
+Raw paths undergo traversal, absolute/drive-path, and NUL validation **before**
+canonicalization; normalization cannot turn an unsafe path into an accepted
+one. Stripping and output collision checks use this same canonical identity.
+Filters that compare exact strings should use canonical pre-strip paths,
+including directory names without a trailing `/`.
 Returning `"skip"` rejects the whole archive unless `onFiltered` is
-explicitly `"skip-entry"`. Path traversal and archive-wide entry-count checks
-still apply to skipped entries.
+explicitly `"skip-entry"`. Runtime values other than `"reject-archive"` and
+`"skip-entry"` reject before extraction starts instead of falling through to
+skip behavior. Path traversal and archive-wide entry-count checks still apply
+to skipped entries.
+`maxEntryBytes` and `maxExtractedBytes` charge only entries accepted after
+stripping and filtering. Skipping a large member does not consume these payload
+budgets. The separate complete-stream decoded limit still applies to all TAR
+content, including skipped or fully stripped members.
 
 For example, a fleet restore can omit regenerated cache entries while rejecting
 any other policy mismatch by default:
@@ -111,14 +129,33 @@ If skipping was not explicitly part of the restore contract, omit
 `onFiltered`; the first `"skip"` then rejects the complete archive with
 `ArchiveSecurityError("entry-filtered")`.
 
-Policy rejection is prompt on both implementations. The JavaScript TAR path
-owns the file stream and aborts node-tar through a pipeline on filter, path,
-link, limit, validation, or timeout failure, which destroys both ends instead
-of leaving a paused parser to drain indefinitely. The native path finishes its
-bounded manifest read before TypeScript policy evaluation, so a rejected plan
-never starts the extraction worker.
-
-If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline.
+Both TAR implementations finish bounded admission before TypeScript policy
+evaluation, so a rejected plan never starts extraction. The JavaScript path
+owns the extraction file stream and aborts node-tar through a pipeline on
+parser disagreement, validation, or timeout failure, destroying both ends
+instead of leaving a paused parser to drain indefinitely.
+
+TAR character devices, block devices, and FIFOs are presented to the filter as
+`kind: "other"`. Accepted entries of these types reject with
+`ArchiveSecurityError("entry-link")`; an explicit `"skip-entry"` filter can omit
+them. GNU typeflag `D` (`GNUDumpDir`) is a directory on both backends, including
+its filter kind, canonical path, and directory creation policy. Its declared
+body size follows the existing TAR strip/filter payload budgets; dump contents
+are not restored as files.
+
+Unsupported logical TAR records, including volume headers (`V`), Solaris ACL
+records (`A`), inodes (`I`), continuations (`M`), and unrecognized typeflags,
+still undergo entry counting, raw/effective path validation, stripping, depth
+and output collision checks in physical order. Each remaining record reaches
+`entryFilter` once with its canonical pre-strip path, `kind: "other"`, and
+declared effective size. A filter skip rejects with `"entry-filtered"` unless
+`onFiltered: "skip-entry"` is explicit. Accepted unsupported records are safely
+omitted and do not consume output payload budgets. This applies even when the
+underlying TAR parser suppresses the record. GNU long names describe one such
+record and are then cleared; local PAX on unsupported types and GNU sparse
+`S` records retain their existing fail-closed format policy.
+
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
 
 ### Limits
 
@@ -126,8 +163,8 @@ If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and thr
 type ArchiveExtractLimits = {
   maxArchiveBytes?: number;     // refuse if archivePath stat'd size exceeds this
   maxEntries?: number;          // refuse before extracting if entry count > this
-  maxExtractedBytes?: number;   // refuse mid-stream if total extracted bytes > this
-  maxEntryBytes?: number;       // refuse a single entry larger than this
+  maxExtractedBytes?: number;   // cap total payload bytes accepted after strip/filter
+  maxEntryBytes?: number;       // cap one accepted entry after strip/filter
   maxMetaEntryBytes?: number;   // refuse one PAX/GNU metadata body above this
   maxEntryPathComponents?: number; // bound output path depth after stripComponents
 };
@@ -142,13 +179,24 @@ A limit violation throws `ArchiveLimitError`. Its constant and string code are:
 | `ARCHIVE_SIZE_EXCEEDS_LIMIT` | `archive-size-exceeds-limit` |
 | `ENTRY_COUNT_EXCEEDS_LIMIT` | `archive-entry-count-exceeds-limit` |
 | `EXTRACTED_SIZE_EXCEEDS_LIMIT` | `archive-extracted-size-exceeds-limit` |
+| `DECODED_SIZE_EXCEEDS_LIMIT` | `archive-decoded-size-exceeds-limit` |
 | `ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT` | `archive-entry-extracted-size-exceeds-limit` |
 | `META_ENTRY_SIZE_EXCEEDS_LIMIT` | `archive-meta-entry-size-exceeds-limit` |
 | `ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT` | `archive-entry-path-components-exceeds-limit` |
 | `MANIFEST_SIZE_EXCEEDS_LIMIT` | `archive-manifest-size-exceeds-limit` |
 
-`MANIFEST_SIZE_EXCEEDS_LIMIT` is retained in the public compatibility union;
-no current public extractor emits it.
+`MANIFEST_SIZE_EXCEEDS_LIMIT` is an active internal TAR admission limit, shared
+by JavaScript and native extraction and bounded reads. Each logical member,
+including ignored, filtered, and fully stripped members, charges
+`64 + 2 * UTF-8 byte length of its effective pre-strip path` before emission or
+retention. PAX/GNU metadata headers do not themselves charge a member cost.
+The allowance is independent of `maxArchiveBytes`: derive a per-member path
+allowance of `max(256, min(maxMetaEntryBytes, max(1, maxEntryPathComponents) * 256))`,
+apply the same 64-byte overhead and doubled path cost, multiply by `maxEntries`,
+and cap the total at 64 MiB using saturating arithmetic. Zero and very large
+public limits remain deterministic. There is no public `maxManifestBytes`
+option; this charged manifest budget supplements the decoded and metadata
+limits rather than bounding the complete process heap.
 
 Catch and branch on the code to surface a meaningful response to the caller.
 
@@ -165,9 +213,91 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 - **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. Destination symlink swaps are checked with the selected platform mechanism; non-Linux routes retain the best-effort race window documented in the [security model](security-model.md#containment-guarantees-by-platform).
 - **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
 - **Corrupt ZIP payloads:** streamed output must match both the central-directory CRC and declared uncompressed size before it can leave private staging.
-- **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
+- **Corrupt gzip streams:** truncated compressed bodies, missing trailers, and checksum failures reject before extraction publishes files or an entry read returns bytes, on both JavaScript and native backends.
+- **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget for non-mutating work. Extraction is aborted on overrun; if a destination mutation is already in flight, that mutation and rollback are joined before rejection so archive-controlled publication cannot continue afterward.
 - **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before either TAR implementation buffers them. It understands octal and base-256 fixed sizes and validates bounded local PAX bodies before using their size overrides for member framing. Original archive bytes remain unchanged.
 
+### Raw TAR framing
+
+Extraction and bounded reads admit the complete decoded TAR stream through the
+raw meter before either backend's TAR parser runs. This applies to plain TAR,
+gzip, and native-supported zstd/bzip2, without changing native-mode availability
+or fallback policy. The existing TypeScript and Rust meters enforce the same
+framing rules before parser normalization:
+
+- Every nonzero header must have a valid unsigned octal checksum, delimited
+  within its field. Checksum validation precedes metadata allocation and member
+  policy. Fixed name, prefix, and linkname fields require strict UTF-8 and NUL
+  padding. Raw hardlink (`1`) and symlink (`2`) headers require a nonempty
+  linkname; every other type, including PAX/GNU metadata, requires an empty
+  linkname. This check precedes metadata handling and member/filter policy.
+- Directory (`5`), hardlink (`1`), and symlink (`2`) raw headers must declare
+  zero body bytes, whether or not local PAX metadata is present. Valid zero-size
+  links remain subject to the existing link/filter policy.
+- EOF requires two consecutive, complete 512-byte zero blocks at a header
+  boundary. A header after just one zero block, a missing/partial EOF marker,
+  and any nonzero bytes after EOF reject. Additional zero padding after EOF may
+  have any byte length within the decoded ceiling; zero blocks inside a declared
+  member body are payload.
+- Headers and padded bodies must be complete. Size fields accept unsigned
+  octal with ASCII-space/NUL padding or supported positive base-256 encoding;
+  malformed numbers and non-padding bytes after a NUL reject. Raw sizes and
+  padded sizes must fit `Number.MAX_SAFE_INTEGER`, even with PAX overrides,
+  before member budgets are considered.
+
+Framing failures use `ArchiveFormatError("archive-header-invalid")`, except
+invalid UTF-8 or nonzero bytes after the first NUL in fixed name, linkname,
+and USTAR prefix fields, which use `ArchiveSecurityError("entry-path")`.
+Missing linknames on links and nonempty linknames on non-links still use the
+format error. PAX `x` and GNU long-name/long-link `L`/`K` payloads retain their
+existing support and metadata limits; the zero-body rule is not applied to all
+non-regular types.
+PAX effective sizes still determine regular-member framing. Admission preserves
+the input bytes, and all entry/path/byte limits and extraction deadlines remain
+in force. Native inspection now completes this admission pass before parsing,
+requiring one additional streaming read/decompression pass.
+JavaScript admission reports an ordered logical-member manifest from the raw
+meter, bounded by entry-count, manifest, and decoded limits. Policy runs once
+over that manifest; extraction checks parser-visible members against the
+accepted decisions before writing. Original member names and USTAR prefixes
+are validated even when overridden, and non-padding bytes after a fixed path
+field's NUL terminator reject rather than hiding an unsafe suffix.
+Both meters enforce the 255-byte component ceiling under NFC and NFD before
+metadata replaces a raw path, including Hangul decomposition expansion.
+Native extraction and entry reads also drain their metered readers through
+physical EOF after parser traversal, before completing directory modes,
+publishing staged files, or returning the requested bytes. Finding the requested
+member or reaching the parser's logical EOF cannot bypass trailing validation.
+
+The raw meter enforces `maxEntries` before consuming each logical member's body,
+including members later skipped by filtering or stripping. PAX/GNU metadata
+headers do not count as members; their payloads use `maxMetaEntryBytes`.
+The meter does not receive `maxEntryBytes` or `maxExtractedBytes`: those payload
+budgets apply only after strip/filter acceptance, using declared effective
+sizes and excluding block padding. JavaScript's entry checker and the native
+accepted-plan builder retain this shared policy. Every TAR admission/parser
+pass has a separate absolute decoded ceiling:
+`maxExtractedBytes + maxArchiveBytes`, safely clamped to
+`Number.MAX_SAFE_INTEGER` (768 MiB with defaults). It counts every admitted
+decoded byte: headers, bodies, metadata, all block padding, both EOF blocks,
+and zero padding after EOF. It bounds complete decoding before parser policy,
+including all filtered/stripped content; cumulative metadata and zero tails
+cannot bypass this bound. Exceeding this ceiling throws
+`ArchiveLimitError("archive-decoded-size-exceeds-limit")`.
+
+The same TypeScript helper derives the ceiling for JavaScript and every native
+TAR pass. Before selecting a backend, it caps internal metadata/decoded limits at
+`Number.MAX_SAFE_INTEGER` and logical entry counts at `2^32 - 1`. Larger finite
+options such as `Number.MAX_VALUE` remain valid; high-level payload budgets keep
+their large values. The decoded ceiling uses clamped `maxExtractedBytes` and
+archive overhead with safe addition. Ordinary limits, including
+zero and the existing defaulting/rounding rules, retain their behavior.
+There is no new public option. This is an absolute decoded admission
+cap, not a decompression-ratio policy; bounded stream/codec read-ahead remains.
+After this complete preflight, the JavaScript backend disables node-tar's
+independent ratio threshold so it cannot reject data that the native backend
+accepts within the same absolute limits.
+
 ### Bounded local PAX support
 
 Extraction and single-entry reads accept one nonempty local POSIX `x` header
@@ -175,8 +305,8 @@ Extraction and single-entry reads accept one nonempty local POSIX `x` header
 directory, symlink, or hardlink. `path`, `linkpath`, and `size` override that
 member only. Effective paths still pass traversal validation before stripping,
 then the output paths pass depth and collision checks. The filter receives the
-effective pre-strip path, followed by link policy checks. PAX never permits link
-creation. Effective sizes drive framing, filters, and the existing output-byte
+canonical effective pre-strip path, followed by link policy checks. PAX never
+permits link creation. Effective sizes drive framing, filters, and the existing output-byte
 budgets; `maxEntries` still counts members, not their metadata headers.
 
 Records must have exact byte lengths, ASCII keys, a final newline, and no
@@ -206,13 +336,38 @@ Global `g`, old `X`, old GNU `N`, empty/dangling/repeated local headers, mixed
 PAX/GNU extension chains, unknown keys, charset declarations, ACL extensions,
 and all sparse extensions (including `GNU.sparse.*`, `SCHILY.filetype`,
 `SCHILY.realsize`, and `SCHILY.size`) fail closed with
-`ArchiveFormatError("archive-header-invalid")`. Standalone GNU long-name `L`
-and long-link `K` support is unchanged. GNU sparse extension blocks are still
+`ArchiveFormatError("archive-header-invalid")`. GNU sparse extension blocks are still
 metered in 512-byte units before rejection, preserving metadata-limit errors
 for excessive chains. The per-body `maxMetaEntryBytes` limit bounds PAX storage
 and duplicate-key state; one local header per member prevents local metadata
 chains without introducing a new limit or changing defaults.
 
+### Bounded GNU long names and links
+
+Both raw meters buffer GNU long-name `L` and long-link `K` bodies within
+`maxMetaEntryBytes` before either TAR parser runs. A body must contain a nonempty
+UTF-8 name, with either no NUL or exactly one terminal NUL. Embedded NULs,
+additional terminal NULs, bytes after a NUL, and invalid UTF-8 reject with
+`ArchiveFormatError("archive-header-invalid")`. The meters preserve original
+archive bytes, including the optional terminator and block padding.
+
+One logical member may have at most one `L` and one `K`, in either order.
+Repeated metadata of either kind, mixed PAX/GNU chains in either direction,
+and GNU metadata without a following member reject with the same format error.
+Pending metadata is cleared only when its described member is admitted;
+metadata records do not count toward `maxEntries`.
+
+An `L` name undergoes raw-path validation before parser normalization, stripping,
+or filtering; unsafe paths reject with `ArchiveSecurityError("entry-path")`.
+The validated name remains pending until its described header arrives. An
+effective name ending in `/` or `\` requires raw directory type `5` or `D`;
+other types reject with `ArchiveFormatError` before filtering, preventing the
+parsers from disagreeing about a member's type.
+`K` validates encoding and NUL structure without authorizing link creation.
+Normal link/filter policy still governs the described member. Canonical
+pre-strip filter paths, decoded-stream ceilings, and physical EOF checks apply
+to plain/gzip TAR and native zstd/bzip2 alike.
+
 ## `resolveArchiveKind`
 
 ```ts
@@ -259,11 +414,28 @@ await extractArchive({
 regular-file entry into a bounded `Buffer` without extracting a tree. It pins
 and privately stages the archive input, rejects link, directory, and duplicate
 entries, verifies ZIP CRC and declared size,
-and throws `ArchiveLimitError` if decompressed bytes exceed `maxBytes`. ZIP
+and throws `ArchiveLimitError` if the requested entry's output exceeds
+`maxBytes`. ZIP output within that cap must match the declared uncompressed
+size exactly; either a shorter or longer payload throws
+`ArchiveFormatError("archive-header-invalid")` before bytes are returned on
+both JavaScript and native backends.
+For TAR, `maxBytes` applies only to that requested entry: a larger
+unrequested member remains valid within the default archive admission limits.
+TAR traversal uses default entry-count, compressed-input, and metadata limits,
+plus the 768 MiB decoded ceiling derived from default extracted/archive byte
+limits. It does not apply payload budgets to unrequested members. ZIP
 inputs retain the archive subpath's 256 MiB compressed-input ceiling.
 With a native binding it uses the same Rust decoders as extraction, including
 zstd and bzip2 TAR. Without native it retains the JS ZIP/TAR/gzip implementation.
 
+Requested paths and effective member names use extraction's canonical pre-strip
+identity: backslashes become `/`, and repeated separators and `.` components
+are removed after raw-path validation. For example, `./pkg//value` and
+`pkg\value` both address `pkg/value`, including supported GNU/PAX and ZIP
+Unicode Path names. Case and Unicode spelling are preserved. Requests ending
+in `/` or `\` still reject as non-files. Canonical duplicate members reject
+before an unrelated requested entry can be returned.
+
 ```ts
 const rawManifest = await readArchiveEntry(uploadPath, "package/manifest.json", {
   maxBytes: 64 * 1024,
@@ -308,6 +480,10 @@ import {
 - `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
 - `isWindowsDrivePath(value)` — detects drive-relative segments such as `C:secret` or `nested/C:secret` that should be rejected.
 
+Validate attacker-controlled paths before calling normalization or stripping
+helpers. After validation, `stripArchivePath(entryPath, 0)` returns the canonical
+pre-strip identity used by extraction filters (or `null` for an empty path).
+
 ## Common patterns
 
 ### Extract an upload, surface budget violations

package/docs/atomic.md

@@ -48,6 +48,7 @@ type ReplaceFileAtomicOptions = {
   copyFallbackRestore?: "restore-original" | "none"; // default: "none"
   maxRestoreBytes?: number;          // required with "restore-original"
   destinationHardlinks?: "reject"; // default unset (no destination nlink policy)
+  renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
   syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
   throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
@@ -58,7 +59,7 @@ type ReplaceFileAtomicOptions = {
 
 ### `beforeRename`
 
-Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer:
+Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer. The helper retains the staged descriptor and exact bigint identity across the hook; replacing, deleting, hardlinking, or changing the temp entry to a non-regular file is rejected before publication:
 
 ```ts
 await replaceFileAtomic({
@@ -70,7 +71,15 @@ await replaceFileAtomic({
 });
 ```
 
-If `beforeRename` throws, the rename is skipped and the temp file is removed — the destination is unchanged.
+If `beforeRename` throws, the rename is skipped and the owned temp file is removed — the destination is unchanged. Cleanup unlinks only the exact admitted single-link file; a substitute observed at the temp name is preserved and removed from cleanup authority. The same identity is rechecked before every rename retry, when entering copy fallback, and at the final name after rename. A post-rename verification failure reports the race without rolling back or deleting the published name.
+
+Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
+
+### FUSE mounts and unstable rename identity
+
+Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
+
+This is the same explicit weaker contract available on `Root` writes: cooperating writers are serialized, stale locks fail closed, and mismatched content is rejected after publication without rollback. A same-authority actor that ignores the advisory lock can still substitute another file with identical bytes, so do not use this compatibility policy in directories writable by untrusted same-UID processes.
 
 ### `EPERM` and copy fallback
 

package/docs/durability.md

@@ -90,7 +90,7 @@ target fails with `FsSafeError("path-mismatch")`.
 ## Exclusive file publication
 
 `publishFileExclusive()` materializes one file without clobbering an existing
-target. It pins the source with `O_NOFOLLOW`, optionally verifies
+target. It pins the source with nonblocking `O_NOFOLLOW`, optionally verifies
 `expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
 parent directory.
 

package/docs/file-store.md

@@ -31,6 +31,8 @@ const cache = fileStore({
 });
 ```
 
+Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
+
 Use `private: true` for credentials, auth profiles, tokens, and other private
 state. Private mode keeps the same `FileStore` shape but routes writes through
 the secret-file atomic path, refusing symlink parent components and re-asserting

package/docs/install.md

@@ -92,9 +92,9 @@ native targets and npm-compatible OS, CPU, and Linux libc filters install only
 the matching binary. Consumers do not run a native build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
 non-archive fallback-capable operations working in `auto` or `off`. Native-only
-features, including retained-directory staging, atomic `rename-noreplace`,
-zstd/bzip2 TAR handling, and Windows private-directory creation, remain
-unavailable. Operations needing the binding in `require` mode fail with
+features, including strict owned-tree temp cleanup, retained-directory staging,
+atomic `rename-noreplace`, zstd/bzip2 TAR handling, and Windows private-directory
+creation, remain unavailable. Operations needing the binding in `require` mode fail with
 `helper-unavailable` when the matching package is absent or incompatible.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
@@ -127,7 +127,11 @@ FS_SAFE_NATIVE_MODE=off      # auto | off | require
 Disabling native loading keeps fallback-capable operations working through Node path
 operations guarded by lexical and canonical checks plus identity verification.
 Use `require` when native-backed operations must fail instead of falling back.
-The exact boundary is documented in [native helper policy](native-helper.md).
+Temp workspaces retain compatible JavaScript quarantine cleanup in `auto` and
+`off`. Set `cleanupSafety: "require-bounded"` to reject before child creation
+unless native no-replace quarantine and descriptor-bounded tree removal are
+available. See the [temp workspace contract](temp.md#private-temp-workspaces). The exact boundary
+for other operations is documented in [native helper policy](native-helper.md).
 
 ## Verify the install
 

package/docs/json.md

@@ -135,10 +135,17 @@ where lower latency matters more than crash-durability.
 
 Synchronous variant. It pretty-prints with two spaces, appends a newline,
 creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
-directory best-effort. It has no options bag. On `EPERM`/`EEXIST`, its legacy
-compatibility path may replace by copy rather than atomic rename; use the async
-`writeJson()`/`replaceFileAtomic()` surfaces when fallback policy must be
-explicit.
+directory best-effort. File-mode tightening carries the staged bigint identity
+through rename and applies `fchmod` only when the reopened descriptor and current
+pathname still name that same single-link regular file; a swap is preserved and
+skips this best-effort step. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+compatibility path removes the existing destination and retries the staged-file
+rename, so that fallback is temporarily non-atomic while retaining the staged
+file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces
+when fallback policy must be explicit.
+
+Its private sibling temporary name is independent of the destination basename,
+so staging does not lengthen a valid destination filename.
 
 ```ts
 writeJsonSync("./prefs.json", { theme: "dark" });

package/docs/native-helper.md

@@ -31,6 +31,18 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 
 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.
 
+[`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
+remain available in every mode. Their default compatible cleanup uses guarded
+JavaScript quarantine when owned native tree removal is unavailable.
+`cleanupSafety: "require-bounded"` instead rejects before child creation unless
+no-replace quarantine plus descriptor-relative owned-tree removal are available.
+On Linux, admission probes the exact `openat2` child-directory flags, including
+`RESOLVE_NO_XDEV`, at runtime. An unavailable or denied probe selects compatible
+JavaScript cleanup even in global `require` mode; `require-bounded` rejects before
+child creation.
+Already-created strict workspaces retain their binding
+and descriptors across later mode changes.
+
 [`stageFileInDirectory()`](staged-file.md) always requires native support on
 Linux/macOS and rejects before creation when off, unavailable, or missing the
 required capability. Windows is unsupported for this lifecycle. This does not
@@ -44,9 +56,9 @@ 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`, `renameat`, 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. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- 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. 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, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed.
 
 Native primitives back create-only and replacing pinned writes, async sidecar creation,
 guarded publication, archive acceleration, and direct Windows ACL operations.

package/docs/native.md

@@ -64,12 +64,39 @@ 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.
+A raw meter sits between decompression and the TAR crate, with matching
+TypeScript admission before node-tar. It parses 512-byte headers and bounded
+local PAX `x` metadata, using supported effective sizes to locate the following
+member body. GNU long-name/link `L`/`K` payloads remain
+supported. `maxMetaEntryBytes` bounds each metadata body before allocation;
+unsupported global/old metadata and sparse forms fail closed rather than being
+interpreted as ordinary members. See [bounded local PAX support](archive.md#bounded-local-pax-support).
+
+Every raw pass receives only TypeScript's resolved `maxEntries`,
+`maxMetaEntryBytes`, and `maxDecodedBytes`. Shared resolution caps metadata and
+decoded byte fields at JavaScript's safe-integer maximum and entry counts at
+`2^32 - 1` before backend selection. Large finite limits remain accepted;
+native conversion mirrors those caps and rejects malformed non-finite or
+negative direct-call values before casting. Logical member headers count
+before filtering/stripping; metadata records do not. `maxEntryBytes` and
+`maxExtractedBytes` remain exclusively in TypeScript's accepted-plan builder,
+after strip/filter policy, and are absent from the raw meter's interface.
+Bounded reads use the default count/metadata/decoded bounds; public `maxBytes`
+bounds only the requested output. TypeScript derives the internal decoded cap
+by safely adding `maxExtractedBytes` and `maxArchiveBytes`, clamped to the safe
+integer maximum. Every native pass receives that same cap and charges headers,
+metadata, bodies, padding, EOF blocks, and trailing zeros. It rejects overflow
+with `archive-decoded-size-exceeds-limit`; no ratio policy is implied.
+Extraction and entry reads drain the metered reader through physical EOF after
+TAR iteration. Trailing framing or decoded-limit failures propagate before
+directory modes are finalized, staging is published, or selected bytes return.
+Native reads stop at framing boundaries so a rejected header does not request
+its body from the decoder; codec buffering can still read ahead internally.
+Inspection finishes the complete bounded framing pass before parsing. Directory
+and link bodies, missing two-block EOF, and nonzero trailers reject on both
+backends, as detailed in [raw TAR framing](archive.md#raw-tar-framing). Raw and
+padded sizes above JavaScript's safe-integer maximum reject as invalid framing
+before applying member budgets, including when local PAX overrides the size.
 
 ## Publication and hashing
 

package/docs/output.md

@@ -48,6 +48,8 @@ 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.
 
+`maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables it. Invalid values reject before the producer or filesystem staging runs.
+
 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.
@@ -56,9 +58,12 @@ through the package's filename sanitizer; `fallbackFileName` supplies the name
 when nothing remains. This removes traversal, device-name, and invalid-character
 hazards but does not trim Windows-normalized trailing dots or spaces; reject or
 rewrite those when cross-platform filename uniqueness matters.
-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.
+`staging: "workspace"` passes the sanitized basename to the producer.
+`staging: "sibling"` embeds that basename in its randomized temporary name.
+The final target and returned `path` use the destination basename, sanitized
+when needed as described above. Guarded temporary files used only inside
+fs-safe have independent names so their length does not grow with the
+destination basename.
 
 ## Choosing a staging mode
 
@@ -80,6 +85,14 @@ rename. If an error leaves the sibling temp in place and immediate cleanup
 fails, its verified identity remains registered for a best-effort process-exit
 cleanup retry.
 
+Sibling staging shares the [callback sibling owner](temp.md#sibling-temp-writes):
+it checks exact pre-open, descriptor, and current-path identities, retains the
+descriptor through publication, and never chmods or reads a replacement by path.
+Cleanup preserves unverified paths, including partial output when the callback
+throws before admission. Native-off and Windows operation remain supported with
+the platform limits and non-atomic rename/unlink identity checks described there.
+When `mode` is omitted, output-sibling staging preserves the producer's mode.
+
 ## Why not pass the final path to the library?
 
 If a target parent can be swapped after validation, handing an external library

package/docs/public-api.md

@@ -69,9 +69,12 @@ The file-lock diagnostics surface includes `FileLockHeldEntry`,
 manager controls; production code should not use them as lock recovery.
 
 Standalone walkers use the `WalkEntryKind` and `WalkSymlinkPolicy` unions.
-Private workspaces expose `TempPathIdentityReceipt` and the
-`TempWorkspaceCleanupResult` union so callers can distinguish removal,
-absence, and identity mismatch.
+Private workspaces expose `TempPathIdentityReceipt`,
+`TempWorkspaceCleanupResult`, and `TempWorkspaceCleanupSafety` so callers can
+distinguish outcomes and select compatible or required bounded-tree cleanup.
+Strict workspace creation requires native no-replace quarantine plus retained
+parent/workspace descriptors; see the
+[creation and cleanup contract](temp.md#private-temp-workspaces).
 
 ## Atomic replacement and durability
 

package/docs/quickstart.md

@@ -145,7 +145,7 @@ await withTempWorkspace({ rootDir: "/srv/jobs/tmp", prefix: "build-" }, async (w
 });
 ```
 
-The directory is mode `0700`, sits under a per-user secure temp root, and is removed when the callback returns or throws. See [Temp workspaces](temp.md).
+The directory is mode `0700` under the caller-provided root, and cleanup runs when the callback returns or throws. Compatible cleanup remains available without native support; pass `cleanupSafety: "require-bounded"` to require native no-replace quarantine and descriptor-bounded tree removal before creating a child. Cleanup preserves raced or ambiguous entries under a private quarantine name. See the [temp workspace compatibility and security contract](temp.md#private-temp-workspaces).
 
 ## Where to next
 

package/docs/reading.md

@@ -89,7 +89,7 @@ type RootReadOptions = {
 };
 ```
 
-`maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory.
+`maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
 
 `nonBlockingRead` remains as a compatibility hint. Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
 

package/docs/regular-file.md

@@ -64,7 +64,11 @@ processLog(result.buffer);
 ```
 
 The result is `{ buffer, stat }`. Missing files preserve the normal `ENOENT`
-shape; non-regular targets throw.
+shape; non-regular targets throw. Reads compare exact bigint identities from the
+preview, opened descriptor, and current path before consuming bytes; the returned
+`stat` remains numeric Node `Stats`. Unknown Windows identities receive one
+re-inspection without reopening; persistent unknowns or replacements throw
+`FsSafeError("path-mismatch")`.
 
 Throws `FsSafeError` with code `too-large` if the file exceeds `maxBytes`. Other I/O errors propagate as `NodeJS.ErrnoException`.
 
@@ -101,7 +105,10 @@ type AppendRegularFileOptions = {
 };
 ```
 
-The helper refuses symlink and hardlinked final targets. With
+The helper refuses symlink and hardlinked final targets. Preview, opened
+descriptor, and current pathname identities remain exact bigints through the
+append boundary; rounded-equal replacements and persistent unknown Windows
+identities reject before chmod or writing bytes. With
 `rejectSymlinkParents: true`, it also rejects symlinked ancestor directories.
 
 ### `appendRegularFileSync(options)`