@openclaw/fs-safe 0.8.0 → 0.8.2

package/docs/archive.md

@@ -2,15 +2,12 @@
 
 `@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. When the native binding is available for the current platform, Rust streams ZIP, TAR, gzip, zstd, and bzip2 while TypeScript remains the sole policy owner; every accepted output is created fd-relative in a private staging root. Extraction then merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
 
-The guarded JavaScript fallback uses optional runtime dependencies: `jszip` for
-ZIP and `tar` for TAR/gzip. The native path does not use those packages. Installs
-that omit optional dependencies can still import this subpath and use the
-native path or pure path/limit helpers.
-
-Some package managers and CI installs skip optional dependencies
-(`--no-optional`, `--omit=optional`, or equivalent). If an archive helper throws
-that an optional archive dependency is not installed, install `jszip` and/or
-`tar` explicitly in the consuming package.
+TAR admission uses one Rust core compiled into both the native binding and a
+bundled, import-free WebAssembly module. The guarded JavaScript fallback uses
+that module for TAR/gzip and optional `jszip` for ZIP. TAR needs no optional
+parser dependency, runtime download, install script, or consumer Rust toolchain.
+Installs omitting optional dependencies can import every public subpath and use
+TAR/gzip in `auto` or `off`; ZIP fallback still requires `jszip`.
 
 ```ts
 import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
@@ -68,12 +65,12 @@ directories; ZIP UNIX creator records with zero attributes are explicit zero,
 while non-UNIX ZIP records use the absent-metadata defaults.
 
 TAR mode fields containing only NUL/ASCII-space padding use absent defaults.
-Native extraction also recognizes GNU binary modes, including signed values,
-within node-tar's JavaScript safe-integer range before masking permission bits.
-Malformed or unsupported mode representations retain existing decoder behavior:
-native falls back to zero, while JavaScript may default, parse an octal prefix,
-or reject. These representations are not newly admitted or standardized by the
-mode repair; raw framing and other numeric-field checks remain unchanged.
+Both backends recognize GNU binary modes, including signed values,
+within JavaScript's safe-integer range before masking permission bits.
+Malformed or unsupported mode fields consistently fall back to zero, matching
+the former native behavior. This replaces JavaScript's decoder-dependent octal
+prefix parsing, defaulting, or rejection for malformed fields. Ordinary octal,
+absent, explicit zero, and supported GNU binary fields retain their behavior.
 
 Final modes remain separate from private working staging permissions: files
 stay `0o600` and directories `0o700` until publication. Files receive their final
@@ -112,8 +109,8 @@ normalizing separators. For example, `./pkg/hello.txt` with
 `stripComponents: 1` extracts to `hello.txt` on both backends. Entries with no
 remaining components are skipped before the filter callback, but still count
 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.
+copies the admitted payload range to this accepted output path, so depth checks,
+collision checks, writes, and mode application agree.
 
 An `entryFilter` sees the validated **canonical effective archive path before
 stripping**, entry kind, and declared size. On every JavaScript and native
@@ -127,6 +124,12 @@ 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.
+On Windows, archive admission also rejects reserved device segments such as
+`NUL`, `CON.txt`, and `nul .txt` with `ArchiveSecurityError("entry-path")`,
+before extraction or bounded member reads. Ignored trailing spaces in the stem
+before an extension do not bypass this check. Ordinary members with these names
+remain valid on POSIX; this is a host-specific device guard, not a portable-name
+restriction.
 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
@@ -162,11 +165,10 @@ If skipping was not explicitly part of the restore contract, omit
 `onFiltered`; the first `"skip"` then rejects the complete archive with
 `ArchiveSecurityError("entry-filtered")`.
 
-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.
+Both TAR routes finish bounded admission before TypeScript policy evaluation,
+so a rejected plan never starts extraction. The JavaScript path owns its input,
+decoder, and WASM parser streams, joining their teardown on validation, write,
+or timeout failure.
 
 TAR character devices, block devices, and FIFOs are presented to the filter as
 `kind: "other"`. Accepted entries of these types reject with
@@ -183,8 +185,7 @@ 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
+omitted and do not consume output payload budgets. The shared core admits these records explicitly. 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.
 
@@ -219,7 +220,7 @@ type ArchiveExtractLimits = {
 };
 ```
 
-Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The same resolved 1 MiB metadata default applies to the native and WASM core.
 
 A limit violation throws `ArchiveLimitError`. Its constant and string code are:
 
@@ -262,17 +263,17 @@ 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.
-- **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.
+- **Gzip container integrity:** every concatenated gzip member must have a complete valid header, body, CRC32, and ISIZE trailer. A completed member may be followed by all-zero compressed-container padding (including system-tar stdout padding), bounded by the original archive-byte limit. The padding must remain zero through physical EOF; nonzero bytes or another member after padding reject. Truncation and corruption reject before publication or selected bytes return on both backends. Compressed padding is separate from decoded TAR EOF and does not bypass its checks.
 - **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.
+- **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before buffering their bodies. 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,
+shared Rust core. 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:
+or fallback policy. The native and WASM builds enforce the same
+framing rules:
 
 - Every nonzero header must have a valid unsigned octal checksum, delimited
   within its field. Checksum validation precedes metadata allocation and member
@@ -301,22 +302,28 @@ 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.
+PAX effective sizes determine regular-member framing. Admission preserves input
+bytes and emits an ordered manifest with exact effective names, types, modes,
+sizes, and decoded payload offsets. TypeScript owns filtering, stripping,
+collisions, permissions, and accepted-output limits. Executors replay admitted
+ranges from the immutable staged input; no second TAR parser interprets PAX,
+GNU names, or payload lengths. Native writes remain descriptor-relative;
+JavaScript writes use the shared guarded private staging and pinned-write helpers.
+
+Original member names and USTAR prefixes are validated even when overridden.
+Non-padding bytes after a fixed path field's NUL terminator reject. The core
+enforces the 255-byte component ceiling under NFC and NFD, including Hangul
+expansion. Every replay drains and validates physical EOF before publication or
+returning selected bytes. Unrequested, filtered, and stripped members cannot
+bypass validation. Decompression remains streaming; no complete decoded archive
+is retained in memory or written to a decoded spool.
+
+The WASM transport has a fixed 64 KiB input buffer, one pending member event,
+and a 256 MiB maximum linear memory per isolated parser instance. Metadata is
+bounded before allocation; allocation failure rejects. Stream backpressure
+bounds queued chunks, and completion/error destroys the instance's parser
+state. The manifest retains the existing charged budget below; linear memory
+is an additional execution resource bound, not a new public limit option.
 
 The raw meter enforces `maxEntries` before consuming each logical member's body,
 including members later skipped by filtering or stripping. PAX/GNU metadata
@@ -343,9 +350,7 @@ 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.
+There is no independent TAR parser decompression-ratio threshold.
 
 ### Bounded local PAX support
 
@@ -359,13 +364,14 @@ permits link creation. Effective sizes drive framing, filters, and the existing
 budgets; `maxEntries` still counts members, not their metadata headers.
 
 Records must have exact byte lengths, ASCII keys, a final newline, and no
-duplicate keys, embedded newlines, or unconsumed bytes. Structural `path` and
-`linkpath` values and ownership names must be nonempty printable ASCII. A PAX
-member's raw name, USTAR prefix, and raw link target must also be printable
-ASCII; raw link targets must be present only on links, even when overridden.
-Unicode
-PAX structural text is deliberately unsupported because the underlying parsers
-do not agree when UTF-8 is split across input chunks. `size`, `uid`, and `gid`
+duplicate keys or unconsumed bytes. `path` and `linkpath` must be nonempty strict
+UTF-8 without NUL. Unicode, a leading BOM, numeric-looking names, and embedded
+newlines preserve their exact spelling; newlines inside a byte-counted value
+are data. Windows filesystem filename restrictions still apply during creation.
+Ownership names retain the existing nonempty printable-ASCII contract. Raw name,
+USTAR prefix, and link fields still require strict UTF-8 and NUL padding even
+when metadata overrides them. Raw link targets must be present only on links.
+`size`, `uid`, and `gid`
 must be canonical unsigned decimal safe integers (zero is valid; signs, leading
 zeros, fractions, and exponents are not). Padded member sizes must also fit the
 safe integer range. Raw and effective directory/link sizes must both be zero;
@@ -378,8 +384,7 @@ with optional fractional digits, within JavaScript's Date range), `uid`, `gid`,
 destination. `LIBARCHIVE.xattr.*` and `SCHILY.xattr.*` with nonempty ASCII
 alphanumeric/dot/underscore/hyphen suffixes are also accepted as inert metadata,
 never restored as extended attributes. Their values are byte-counted and may
-contain NUL or non-UTF8 bytes, including macOS provenance metadata; embedded
-newlines are rejected because they can disrupt downstream record parsing.
+contain NUL, non-UTF8 bytes, or newlines, including macOS provenance metadata.
 
 Global `g`, old `X`, old GNU `N`, empty/dangling/repeated local headers, mixed
 PAX/GNU extension chains, unknown keys, charset declarations, ACL extensions,
@@ -393,11 +398,11 @@ 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
+The shared core buffers GNU long-name `L` and long-link `K` bodies within
+`maxMetaEntryBytes`. 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
+`ArchiveFormatError("archive-header-invalid")`. The core preserves 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.

package/docs/contributing.md

@@ -19,7 +19,16 @@ manager version declared in `package.json`.
 pnpm build
 ```
 
-Runs `tsc -p tsconfig.json`. Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
+Runs TypeScript compilation and builds the portable Rust TAR parser for
+`wasm32-unknown-unknown`. Contributors need Rust (the native crate's declared
+minimum or newer) and `rustup target add wasm32-unknown-unknown`; Alpine's
+packaged toolchain uses `rust-wasm`. `pnpm archive:wasm` rebuilds just the parser.
+The import-free asset lands at `dist/archive-parser.wasm`; source tests and
+compiled consumers both resolve that generated artifact. Run `pnpm build`
+before source tests in a fresh checkout. Do not commit `dist/` or built WASM.
+Consumers receive the asset in the npm package and need no compiler.
+
+Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
 ## Test
 
@@ -59,8 +68,33 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+### Real TAR producers
+
+After installing the freshly packed root (and optionally its freshly built host
+binding) in a disposable consumer, run:
+
+```bash
+pnpm archive:producer-smoke ./consumer off
+pnpm archive:producer-smoke ./consumer require
+```
+
+This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
+with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
+then the installed package API for exact payload hashes and bounded reads.
+It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
+The `require` command must resolve the freshly packed native binding; the
+`off` command uses the installed WASM asset. No live user files are read.
+
 ### Native consumer installs
 
+The CI Node 24 and native jobs also run `node scripts/device-path-proof.mjs off`
+and `node scripts/device-path-proof.mjs require` against the built package.
+This extracts real ZIP files and checks bounded member reads, preserving reserved
+device-like names on POSIX while rejecting them and ignored-space aliases on
+Windows. It also verifies ordinary secret reads and typed device-path rejection
+without replacing filesystem functions. Run after `pnpm build`, and build the
+host binding with `pnpm native:build` before the `require` case.
+
 After `pnpm build` and a fresh `pnpm native:build`, run `pnpm package:smoke`.
 It packs the real root and host binding, then runs root-only npm and the
 declared pnpm version against a disposable loopback registry. The root's exact

package/docs/install.md

@@ -85,7 +85,7 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 ## Runtime dependencies
 
-`@openclaw/fs-safe` lists `jszip` and `tar` as optional dependencies for JavaScript ZIP/TAR [archive extraction](archive.md). They are loaded lazily; the JavaScript archive fallback requires the corresponding codec and reports a missing-optional-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser for guarded JavaScript TAR/gzip [archive extraction](archive.md), including installs with optional dependencies omitted. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
 
 There are no peer dependencies. Exact-version optional packages carry the seven
 native targets and npm-compatible OS, CPU, and Linux libc filters install only

package/docs/native-helper.md

@@ -29,6 +29,11 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 | `off` | Do not load a native package. 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. |
 
+TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
+of the same Rust parser used by native. `off` still disables native filesystem
+code; it does not disable this portable parser. ZIP fallback still requires
+optional `jszip`, and zstd/bzip2 remain native-only.
+
 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)

package/docs/native.md

@@ -64,13 +64,15 @@ 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 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).
+The `fs-safe-archive-core` Rust workspace crate owns TAR framing, paths, types,
+mode decoding, GNU metadata, and byte-counted local PAX records. The native
+binding and bundled WASM module compile the same source. No `tar::Archive` or
+Node TAR parser reinterprets admitted identities or sizes. Executors replay
+admitted payload ranges after complete bounded admission; native writes retain
+the platform's descriptor-relative primitives, while fallback writes retain
+the guarded Node staging/publication boundary. ZIP behavior is unchanged.
+`maxMetaEntryBytes` bounds bodies before allocation; unsupported global/old
+metadata and sparse forms fail closed. 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
@@ -88,11 +90,15 @@ 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
+admitted-range replay. Trailing framing or decoded-limit failures propagate before
 directory modes are finalized, staging is published, or selected bytes return.
+Native gzip uses the existing flate2 member decoder with an explicit bounded
+member/padding transition; JavaScript retains Node gunzip and validates its
+unconsumed compressed suffix. Only all-zero physical padding after a complete
+validated trailer is accepted, still within the original archive-byte budget.
 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
+Inspection finishes the complete bounded framing pass before returning its manifest. 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
@@ -155,7 +161,7 @@ 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. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. 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 same-privilege peer can replace a writable parent after a guard assertion but before Node resolves the pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
-| ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | JSZip/node-tar into a private stage, then the same guarded merge policy. |
+| ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | 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. |

package/docs/secret-file.md

@@ -91,6 +91,11 @@ credential must also fail on broad permissions or unexpected ownership.
 the same pinned-handle validation, byte cap, trimming, error codes, and strict
 versus missing-is-undefined naming semantics.
 
+Both readers reject known unsafe device and process-fd paths with `device-path`
+before inspection, and check the resolved target before opening it. This includes
+Windows reserved device names and ignored-space aliases such as `nul .txt`.
+Optional readers propagate this error instead of treating the secret as missing.
+
 Both sync and async readers compare lossless bigint identities from the preview,
 opened descriptor, resolved target, and current input path before reading. POSIX
 opens are nonblocking, so a raced FIFO is rejected by descriptor type instead of

package/docs/sidecar-lock.md

@@ -21,7 +21,7 @@ try {
 
 The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
 
-On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it.
+On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
 
 Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()`, uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) do not reliably run asynchronous Root cleanup and may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
 
@@ -82,6 +82,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
   parsePayload?: (raw: string) => unknown;
   lockRoot?: Root;
+  retainOnExit?: boolean;               // keep the sidecar across process exit (default false)
   onCompromised?: (info: { lockPath: string; normalizedTargetPath: string }) => void;
   compromiseCheckIntervalMs?: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -24,6 +24,7 @@
     "provenance": true
   },
   "files": [
+    "dist/archive-parser.wasm",
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
@@ -126,7 +127,7 @@
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
     "benchmark:publish": "pnpm build && node scripts/bench-publish.mjs",
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "build": "node scripts/prepack-build.mjs",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
     "prepack": "node scripts/prepack-build.mjs",
@@ -139,7 +140,7 @@
     "docs:check": "node scripts/check-doc-examples.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
     "native:build": "pnpm --filter @openclaw/fs-safe-native-build build",
-    "native:test": "cargo test --manifest-path native/Cargo.toml",
+    "native:test": "cargo test --workspace",
     "pack:check": "pnpm build && node scripts/check-pack.mjs",
     "public-api:update": "pnpm build && node scripts/check-pack.mjs --update-public-api",
     "package:collect": "node scripts/check-release-packages.mjs --output release-artifacts",
@@ -150,32 +151,34 @@
     "crabbox:hydrate": "crabbox actions hydrate",
     "crabbox:run": "crabbox run",
     "crabbox:stop": "crabbox stop",
-    "crabbox:warmup": "crabbox warmup"
+    "crabbox:warmup": "crabbox warmup",
+    "archive:wasm": "node scripts/build-archive-wasm.mjs",
+    "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.8.0",
-    "@openclaw/fs-safe-darwin-x64": "0.8.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.8.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.8.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.8.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.8.0",
-    "jszip": "^3.10.1",
-    "tar": "7.5.22"
+    "@openclaw/fs-safe-darwin-arm64": "0.8.2",
+    "@openclaw/fs-safe-darwin-x64": "0.8.2",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.2",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.2",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.2",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.2",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.2",
+    "jszip": "^3.10.1"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.4",
-    "@napi-rs/cli": "3.8.6",
+    "@napi-rs/cli": "3.9.0",
     "@types/node": "^26.4.1",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/coverage-v8": "5.0.0",
     "fast-check": "^4.9.0",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",
     "istanbul-reports": "3.2.0",
     "sigstore": "5.0.0",
+    "tar": "7.5.22",
     "typescript": "^7.0.2",
     "vite": "8.2.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22"

package/dist/archive-tar-admission.d.ts

@@ -1,7 +0,0 @@
-import type { TarEntryInfo } from "./archive-tar.js";
-export declare function rawTarMember(header: Buffer, size: number, effectivePath?: string): TarEntryInfo;
-export declare function createTarAdmissionPlan(manifest: readonly TarEntryInfo[], check: (entry: TarEntryInfo) => boolean, strip: number): {
-    consume(entry: TarEntryInfo): string | null;
-    finish(): void;
-};
-//# sourceMappingURL=archive-tar-admission.d.ts.map

package/dist/archive-tar-admission.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-tar-admission.d.ts","sourceRoot":"","sources":["../src/archive-tar-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAYrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAS/F;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,EACvC,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,IAAI,IAAI,CAAA;CAAE,CAmBjE"}

package/dist/archive-tar-admission.js

@@ -1,43 +0,0 @@
-import { ArchiveFormatError } from "./archive-errors.js";
-import { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
-import { readTarHeaderPaths } from "./archive-tar-header.js";
-// node-tar's normalFsTypes/ReadEntry switch. All other non-metadata types
-// bypass both its filter and entry event; they still belong to our manifest.
-// Header.decode normalizes NUL to "0" before choosing the emitted File type.
-const visibleTypes = new Map([
-    [0, "File"], [0x30, "File"], [0x31, "Link"], [0x32, "SymbolicLink"],
-    [0x33, "CharacterDevice"], [0x34, "BlockDevice"], [0x35, "Directory"],
-    [0x36, "FIFO"], [0x37, "ContiguousFile"], [0x44, "GNUDumpDir"],
-]);
-export function rawTarMember(header, size, effectivePath) {
-    const { name, prefix } = readTarHeaderPaths(header);
-    validateArchiveEntryPath(name);
-    validateArchiveEntryPath(prefix);
-    const rawPath = prefix ? `${prefix}/${name}` : name;
-    validateArchiveEntryPath(rawPath);
-    const path = effectivePath ?? rawPath;
-    validateArchiveEntryPath(path);
-    return { path, size, type: visibleTypes.get(header[156]) ?? "Unsupported" };
-}
-export function createTarAdmissionPlan(manifest, check, strip) {
-    const visible = [];
-    for (const entry of manifest) {
-        const accepted = check(entry);
-        if (entry.type !== "Unsupported") {
-            visible.push({ entry, output: accepted ? stripArchivePath(entry.path, strip) : null });
-        }
-    }
-    let index = 0;
-    const mismatch = () => new ArchiveFormatError("invalid TAR header: parser disagrees with raw admission");
-    return {
-        consume(actual) {
-            const expected = visible[index++];
-            if (!expected || expected.entry.type !== actual.type || expected.entry.size !== actual.size ||
-                stripArchivePath(expected.entry.path, 0) !== stripArchivePath(actual.path, 0))
-                throw mismatch();
-            return expected.output;
-        },
-        finish() { if (index !== visible.length)
-            throw mismatch(); },
-    };
-}

package/dist/archive-tar-gnu.d.ts

@@ -1,2 +0,0 @@
-export declare function validateGnuMetadata(body: Buffer, type: "L" | "K"): string;
-//# sourceMappingURL=archive-tar-gnu.d.ts.map

package/dist/archive-tar-gnu.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-tar-gnu.d.ts","sourceRoot":"","sources":["../src/archive-tar-gnu.ts"],"names":[],"mappings":"AAKA,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM,CAazE"}

package/dist/archive-tar-gnu.js

@@ -1,20 +0,0 @@
-import { ArchiveFormatError } from "./archive-errors.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
-// Keep the byte grammar aligned with native/src/tar_meter.rs. Parsers differ
-// on embedded NULs and malformed UTF-8, so validate before either sees a name.
-export function validateGnuMetadata(body, type) {
-    const value = body.at(-1) === 0 ? body.subarray(0, -1) : body;
-    if (!value.length || value.includes(0)) {
-        throw new ArchiveFormatError("invalid GNU metadata: empty name or embedded NUL");
-    }
-    let name;
-    try {
-        name = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(value);
-    }
-    catch {
-        throw new ArchiveFormatError("invalid GNU metadata: name is not valid UTF-8");
-    }
-    if (type === "L")
-        validateArchiveEntryPath(name);
-    return name;
-}

package/dist/archive-tar-header.d.ts

@@ -1,8 +0,0 @@
-export declare function validateTarChecksum(header: Buffer): void;
-export declare function readTarHeaderPaths(header: Buffer): {
-    name: string;
-    prefix: string;
-    linkname: string;
-};
-export declare function validateTarHeader(header: Buffer): void;
-//# sourceMappingURL=archive-tar-header.d.ts.map

package/dist/archive-tar-header.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-tar-header.d.ts","sourceRoot":"","sources":["../src/archive-tar-header.ts"],"names":[],"mappings":"AAGA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAWxD;AAcD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASrG;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAUtD"}