@openclaw/fs-safe 0.4.7 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.5.0 - 2026-07-27
+
+### Highlights
+
+- Add policy-driven archive entry filtering and mode handling, bounded single-entry archive reads, root-bounded async walking, synchronous sidecar locks, async secret reads, create-only secret writes, and exclusive file publication.
+- Add public streaming `sha256File(path | FileHandle)` hashing with optional async native acceleration, plus policy-free Windows owner/DACL facts with owner and current-process-user SIDs and per-ACE masks and inheritance flags.
+- Add native fd-relative ZIP and TAR extraction/read support with gzip, zstd, and bzip2 streaming; TypeScript evaluates the shared entry policy before Rust creates any output, and zstd/bzip2 report a typed native-required error when no binding is available.
+- Bound PAX, GNU long-name/link, and sparse metadata with one `maxMetaEntryBytes` policy shared by node-tar and the native fixed-header metering reader, including typed failures for oversized or malformed metadata.
+- Add `Root.walk()` subtree pruning and partial directory-error reporting for bounded best-effort consumers, plus a shared `maxEntryPathComponents` archive limit that rejects implicit-directory depth attacks before either extraction path creates output.
+- Bundle all seven prebuilt native binaries inside the single `@openclaw/fs-safe` package for fd-relative opens, guarded directory creation and hardlinks, atomic no-replace rename, and file identity checks. This deliberately increases the package size in exchange for deterministic installs with no optional platform packages, downloads, postinstall step, or consumer Rust build; unsupported platforms silently use the guarded JavaScript fallback in `auto` mode.
+
+### Security and Correctness
+
+- **Security — `resolveRootPath()` / `resolveRootPathSync()`:** Published releases through 0.4.7 validated a lexically normalized path spelling, so a caller-supplied path traversing an in-root symlink could pass validation while resolving outside the root. Version 0.5 fixes this with component-wise alias resolution. `root()` handles were **not** affected: their operations have contained this case since `5ddca80`, so exposure is limited to direct users of these two exported helpers.
+- Prefer macOS 15.4's `O_RESOLVE_BENEATH` for native opens, retain the guarded component walk on older kernels, and apply an `F_GETPATH` post-open escape detector to both routes without claiming rename-race atomicity.
+- Report open containment explicitly: native `openBeneath()` returns `{ fd, containment }` with `kernel-atomic` on Linux and `best-effort` on macOS/Windows, while JavaScript root open/read/writable results report `best-effort`.
+- Serialize async `jsonStore` writes and read-modify-write updates in-process by canonical store path before taking the cross-process sidecar lock, preventing overlapping `write`, `update`, and `updateOr` calls from silently losing updates; reject nested same-path mutations with typed `store-reentrant-update` errors. Thanks @yetval for reporting this.
+- Create `append`, `openWritable`, and fallback `copyIn` parents through guarded per-component walks and continue I/O through the resolved in-root parent, preventing symlink-swap races from creating directories outside the root while preserving valid in-root symlink parents. Thanks @yetval for reporting this.
+- Add pinned-destination hardlink rejection and bounded original-content restoration to `replaceFileAtomic()` and its sync variant, including typed `restored` / `restore-failed` receipts for torn copy-fallback writes.
+- Add sibling staging to `writeExternalFileWithinRoot()`: external producers can write a randomized file in the target directory for fsynced same-filesystem atomic replacement, while private workspace staging remains the cross-device-tolerant default; staged and final basenames share portable C0/C1 and Windows-invalid-character sanitization on every host.
+- Enforce `movePathWithCopyFallback({ sourceHardlinks: "reject" })` with a streaming, entry-capped recursive preflight before mutation, closing a shipped 0.4.x gap where the common same-filesystem rename bypassed the policy; approved trees commit through a fresh staged copy with open-time and post-copy link-count fences so a scan/rename race cannot publish a hardlinked inode.
+- Abort and tear down JavaScript TAR extraction immediately when entry policy, path validation, link rejection, or a budget fails, preventing node-tar from leaving a paused parser after rejected fleet-restore entries; both native and JavaScript paths now return the same typed archive-policy errors.
+- Attach a post-creation failure receipt to `publishFileExclusive()` errors with the failing phase, whether this call created the target, its observed identity, and whether cleanup removed, preserved, or could not classify the target.
+- Add `publishFileExclusive({ onSyncFailure: "rollback" | "preserve" })`: rollback remains the default, while preserve keeps a complete target after directory-sync failure and reports the failed sync outcome in the typed provenance receipt.
+- Close the pinned publication source on parent-pinning failure so every acquired descriptor is released on every exit path.
+- Remove the native loader's PATH-resolved `ldd` execution. Linux libc detection now uses the Node process report, conventional musl library filenames, and the Node executable's ELF interpreter without spawning a process at import time; an inconclusive probe conservatively attempts glibc and falls back normally in `auto` mode.
+- Default archive extraction to `entryModes: "clamp"`, normalizing directories to `0o755` and files to `0o644` or `0o755` while always stripping setuid, setgid, and sticky bits; use `"preserve"` to retain safe archived rwx bits.
+- Prefer native create-only commits, sidecar acquisition, hardlink publication, and the explicit `rename-noreplace` publication strategy when the platform binding is available, while retaining guarded JavaScript fallbacks for `auto` and `off` modes.
+- Accelerate exclusive publication fallbacks with macOS `fclonefileat`, Linux `FICLONE` and `copy_file_range`, then the unchanged JavaScript byte loop; all paths retain exclusive creation, identity fencing, mode normalization, and SHA-256 verification through an async native hash task when available.
+- Add direct Windows owner/DACL inspection and protected private-directory creation for the current owner, LocalSystem, and Administrators, while retaining the existing .NET/`icacls` behavior when native mode is unavailable, forced off, or encounters an unsupported descriptor form.
+- Keep the public private-directory creator Windows-only and native-only so POSIX pathname races or inherited ACLs cannot weaken its privacy guarantee.
+- Build Linux native opens on `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, macOS opens on an in-root `O_NOFOLLOW` component walk, and Windows opens on handle-relative `NtCreateFile` with reparse-point rejection.
+
+### Compatibility
+
+- Remove the unsound process-scoped `allowReentrant` async file-lock option and replace it with owner-scoped `reentrantOwner` for async and sync locks: only matching, explicitly defined logical owners reuse a canonical in-process lock, releases are reference-counted and idempotent, and different or absent owners contend normally. Callers that passed the boolean must either remove it or migrate intentional nesting to a per-operation owner key; `jsonStore` remains ownerless and rejects nested same-file mutations immediately.
+- Remove the persistent Python helper and its `pythonPath` configuration. Replace `configureFsSafePython`, `FS_SAFE_PYTHON_MODE`, and the OpenClaw Python aliases with `configureFsSafeNative` and `FS_SAFE_NATIVE_MODE`; 0.5 warns once and maps the former `auto`, `require`, and `off` policies solely as an upgrade bridge for shipped 0.4 consumers.
+- Add `publishFileExclusive({ strategy: "rename-noreplace" })`; this strategy requires the native helper, atomically moves the source, and never replaces an existing destination.
+
+### Docs and Tooling
+
+- Add an ordered 0.4-to-0.5 migration checklist and reconcile every new archive, native, publication, walk, lock, secret, permission, and temp-workspace contract with realistic examples and cross-links.
+- Convert the repository to a pnpm workspace, test the Rust crate on Linux, macOS, and Windows, and publish all platform bindings, the native loader, and the root package through one protected-tag release pipeline with npm provenance.
+- Replace unused napi-rs Android, FreeBSD, OpenHarmony, WASI, and unsupported-architecture loader branches with a checked-in loader for the seven packages actually published, and make publication benchmarks report the exercised clone/copy/JavaScript tier plus filesystem environment.
+
 ## 0.4.7 - 2026-07-24
 
 ### Features

package/README.md

@@ -10,7 +10,7 @@
 
 Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
 
-Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and refuses to escape — through `..`, symlink swaps, hardlink aliases, or TOCTOU rename races between check and use.
+Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and defends against `..`, symlink swaps, hardlink aliases, and TOCTOU rename races. The exact containment strength is reported per mechanism: Linux native opens are kernel-atomic; macOS, Windows, and JavaScript paths are best-effort.
 
 ```ts
 import { root } from "@openclaw/fs-safe";
@@ -26,7 +26,7 @@ Full docs and reference at **[fs-safe.io](https://fs-safe.io)**.
 
 ## Contents
 
-[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Directory durability](#directory-durability) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
+[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [0.5 migration](docs/migrating-to-0.5.md) · [Python migration](#migrating-from-the-python-helper) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Directory durability](#directory-durability) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
 
 ## Why this exists
 
@@ -45,11 +45,11 @@ The same idea has landed in other languages. Go [added `os.Root` and `OpenInRoot
 | `path.resolve().startsWith()` | string check only | – | – | – | – |
 | [`write-file-atomic`](https://www.npmjs.com/package/write-file-atomic) | – | ✓ | – | – | – |
 | Go [`os.Root`](https://go.dev/blog/osroot) / Rust [`cap-std`](https://github.com/bytecodealliance/cap-std) | ✓ | platform | ✓ | ✓ | – |
-| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **✓ (POSIX fd-relative)** | **✓ (ZIP/TAR)** |
+| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux atomic; others best-effort** | **✓ (ZIP/TAR; native zstd/bzip2)** |
 
 ## Not a sandbox
 
-This is a **library-level guardrail**, not OS-level isolation. It does not replace containers, seccomp, AppArmor, or filesystem permissions. It is for code that already runs with the privileges of its workspace and wants to stop trivial path tricks from escaping it. If your threat model is a hostile process, you need OS isolation; if your threat model is "an agent, plugin, upload handler, or CLI will eventually be tricked into writing somewhere it shouldn't," `fs-safe` catches that.
+This is a **library-level guardrail**, not OS-level isolation. It does not replace containers, seccomp, AppArmor, or filesystem permissions. It is for code that already runs with the privileges of its workspace and wants to stop trivial path tricks from escaping it. If your threat model is a hostile process, you need OS isolation; if your threat model is "an agent, plugin, upload handler, or CLI will eventually be tricked into writing somewhere it shouldn't," `fs-safe` catches that. The [security model](docs/security-model.md) describes the exact Linux, macOS, Windows, and JavaScript fallback guarantees and race boundaries.
 
 ## Install
 
@@ -59,27 +59,49 @@ pnpm add @openclaw/fs-safe
 
 Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. Archive helpers use optional `jszip` and `tar` dependencies for ZIP/TAR support; installs that omit optional dependencies can still use every non-archive subpath.
 
-On POSIX, `root()` uses one process-global persistent Python helper for the
-fd-relative operations Node does not expose ergonomically (`renameat`,
-`unlinkat`, recursive `mkdirat`-style walks, and parent-fd writes). Configure it
-before first use when you need a strict environment policy:
+The package bundles prebuilt native bindings for seven supported targets. They
+supply fd-relative and atomic no-replace primitives that Node does not expose
+directly. Configure the lazy loader before first use when you need a strict
+environment policy:
 
 ```ts
-import { configureFsSafePython } from "@openclaw/fs-safe";
+import { configureFsSafeNative } from "@openclaw/fs-safe";
 
-configureFsSafePython({ mode: "auto" });    // default: use helper, fall back if unavailable
-configureFsSafePython({ mode: "off" });     // never spawn Python; use best-effort Node fallbacks
-configureFsSafePython({ mode: "require" }); // fail closed if helper cannot start
+configureFsSafeNative({ mode: "auto" });    // default: native when available
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "require" }); // fail closed if the binding is unavailable
 ```
 
-Equivalent env vars: `FS_SAFE_PYTHON_MODE=auto|off|require` and
-`FS_SAFE_PYTHON=/path/to/python3`. Without Python, `fs-safe` keeps lexical and
-canonical root checks, no-follow opens, atomic temp+rename writes, and
-post-write identity verification. What you lose is the strongest POSIX
-fd-relative protection against a same-process-user racer swapping parent
-directories between validation and mutation. Windows already uses the Node
-fallback path. See the [Python helper policy](docs/python-helper.md) for
-deployment guidance.
+Equivalent env var: `FS_SAFE_NATIVE_MODE=auto|off|require`. All seven binaries
+ship inside `@openclaw/fs-safe`; there are no platform packages, postinstall
+steps, downloads, or consumer Rust builds. This makes the tarball larger than
+a per-platform package, but makes installation deterministic. On a platform
+without a bundled binary, `auto` silently retains lexical and canonical root
+checks, no-follow opens, guarded temp+rename writes, and post-write identity
+verification. See the [native
+helper policy](docs/native-helper.md) for the exact boundary and deployment
+tradeoff, and [native architecture](docs/native.md) for the platform mechanisms
+and policy ownership model.
+
+Open results report the mechanism's containment class as `"kernel-atomic"` or
+`"best-effort"`. Linux native `openBeneath()` is kernel-atomic; macOS, Windows,
+and guarded JavaScript results are best-effort. See the [security model](docs/security-model.md#containment-guarantees-by-platform) before using that fact in higher-level policy.
+
+## Migrating from the Python helper
+
+Version 0.5 replaces the persistent Python worker with bundled prebuilt native
+bindings. The modes map directly: `configureFsSafePython({ mode: "auto" })`
+becomes `configureFsSafeNative({ mode: "auto" })`, and likewise for `off` and
+`require`. Replace `FS_SAFE_PYTHON_MODE` with `FS_SAFE_NATIVE_MODE`; remove
+`pythonPath`, `FS_SAFE_PYTHON`, and interpreter provisioning because the native
+loader does not spawn Python.
+
+Version 0.5 retains the old function and documented `FS_SAFE_PYTHON*`
+and OpenClaw Python environment names emit one `FS_SAFE_PYTHON_DEPRECATED`
+warning and map the old mode to its native equivalent. They are migration
+bridges for shipped 0.4 consumers, not an alternate helper contract. Update
+startup configuration as part of the 0.5 upgrade rather than relying on the
+warning path. Follow the [0.5 migration checklist](docs/migrating-to-0.5.md).
 
 ## Quick start
 
@@ -170,36 +192,36 @@ const locked = await root("/srv/workspace", {
 await locked.write(".env", "token"); // FsSafeError code "denied-path"
 ```
 
-`stat()`, `exists()`, and `list()` are boundary-checked, but they cannot pin a later operation to the same filesystem object. Use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` for operations that must be race-resistant at the point of use.
+`stat()`, `exists()`, and `list()` are boundary-checked, but they cannot pin a later operation to the same filesystem object. Use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` for operation-local identity checks, and inspect `containment` when the platform distinction matters.
 
 ## Subpaths
 
-The main entry point is intentionally small: `root`, the root option/result
-types, and `FsSafeError`. Use subpaths for everything else. Low-level helpers
-that OpenClaw needs to compose higher-level APIs are grouped under
+The main entry point collects the common root, config, output, lock, native-mode,
+and error exports. Prefer focused subpaths when a consumer needs a narrower
+contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are grouped under
 `@openclaw/fs-safe/advanced` instead of being separate public leaf contracts.
 
 | Subpath | Contents |
 |---|---|
-| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, related types |
-| `@openclaw/fs-safe/config` | process-global Python helper configuration |
+| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, and root-bounded walking with pruning/error markers |
+| `@openclaw/fs-safe/config` | process-global native helper and lock defaults |
 | `@openclaw/fs-safe/path` | canonical path checks: `isPathInside`, `safeRealpathSync`, `isNotFoundPathError`, `isSymlinkOpenError` |
 | `@openclaw/fs-safe/json` | `tryReadJson`, `readJson`, `readJsonIfExists`, `writeJson`, sync variants |
 | `@openclaw/fs-safe/output` | `writeExternalFileWithinRoot` for external libraries that need a temp output path |
 | `@openclaw/fs-safe/store` | `fileStore`, `fileStoreSync`, and `jsonStore` |
-| `@openclaw/fs-safe/secret` | strict and try-style secret file read/write helpers |
+| `@openclaw/fs-safe/secret` | sync/async strict and try-style secret reads, atomic replace, and create-only secret writes |
 | `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `replaceFileAtomicSync`, `replaceDirectoryAtomic`, `movePathWithCopyFallback` |
-| `@openclaw/fs-safe/durability` | pinned directory identities, strict and best-effort directory sync, durable nested-directory creation |
+| `@openclaw/fs-safe/durability` | pinned directory identities, strict directory sync, durable nested-directory creation, exclusive publication, streaming SHA-256, provenance receipts, and sync-failure policy |
 | `@openclaw/fs-safe/temp` | `tempWorkspace`, `tempWorkspaceSync`, `withTempWorkspace`, `resolveSecureTempRoot` |
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
-| `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types |
-| `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection plus remediation formatting helpers |
+| `@openclaw/fs-safe/file-lock` | async/sync sidecar locks, root-bounded sidecars, ownership verification, and stale policy |
+| `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
 | `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
-| `@openclaw/fs-safe/archive` | `extractArchive`, `resolveArchiveKind`, `ArchiveLimitError`, preflight helpers |
+| `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, native gzip/zstd/bzip2, and bounded entry reads |
 | `@openclaw/fs-safe/advanced` | lower-level composition helpers such as path scopes, root-file open, bounded descriptor reads, install paths, filename sanitizing, temp-file targets, sibling-temp writes, local-root readers, regular-file helpers, `pathExists`, and `withTimeout`; less stable than focused public subpaths |
-| `@openclaw/fs-safe/errors` | `FsSafeError`, `FsSafeErrorCode` |
+| `@openclaw/fs-safe/errors` | `FsSafeError`, closed codes/categories, causes, and operation-specific details receipts |
 | `@openclaw/fs-safe/types` | shared types: `DirEntry`, `PathStat`, … |
-| `@openclaw/fs-safe/test-hooks` | hooks the test suite uses to inject races; only active under `NODE_ENV=test` |
+| `@openclaw/fs-safe/test-hooks` | hooks the test suite uses to inject races; registration requires `NODE_ENV=test` or `VITEST=true` |
 
 ## Failure semantics in the name
 
@@ -243,12 +265,18 @@ when creating a nested directory. Strict sync propagates real I/O failures and
 reports known Windows directory-flush limitations explicitly. Separate
 best-effort helpers preserve operations that do not promise crash durability.
 
+`publishFileExclusive()` adds no-clobber hardlink/copy/rename strategies and a
+typed post-creation receipt. Its `onSyncFailure` policy defaults to
+`"rollback"`; backup writers can choose `"preserve"` to keep a complete target
+when parent-directory sync fails, then inspect `details.directorySync` and
+retry or record the weaker durability state.
+
 See [Directory durability](docs/durability.md) for the receipt, pin lifecycle,
-creation callback, and platform contract.
+publication policy, creation callback, and platform contract.
 
 ## Atomic writes
 
-`replaceFileAtomic()` writes a sibling temp file, optionally fsyncs it, and renames it over the destination. Mode preservation, rename retry / copy fallback on `EPERM`, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved.
+`replaceFileAtomic()` writes a sibling temp file, optionally fsyncs it, and renames it over the destination. Mode preservation, pinned-destination hardlink rejection, rename retry / copy fallback on `EPERM`, bounded original-content restoration after a torn fallback, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved.
 
 ```ts
 import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
@@ -275,16 +303,19 @@ import { writeExternalFileWithinRoot } from "@openclaw/fs-safe/output";
 await writeExternalFileWithinRoot({
   rootDir: "/safe/workspace/downloads",
   path: "reports/today.pdf",
+  staging: "sibling",
   write: async (filePath) => {
     await download.saveAs(filePath);
   },
 });
 ```
 
-The callback receives a private temp file path, not the final destination. After
-the callback returns, fs-safe finalizes the staged file with `Root.copyIn()`,
-creating missing parents by default and rejecting traversal, symlink parent
-escapes, hardlinked final targets, and size-limit violations.
+The callback receives a staged path, not the final destination. The default
+`"workspace"` mode uses private temp storage plus `Root.copyIn()` for
+cross-device-tolerant finalization. `"sibling"` stages in the target directory,
+fsyncs the completed file, and atomically renames it over the target. Choose it
+when the destination directory is itself the writable boundary and atomic
+replacement matters.
 
 Use it when the final filename is known before the external writer runs. If the
 filename depends on sniffing the produced bytes, write to a private temp
@@ -406,6 +437,13 @@ for (const file of scan.entries) {
 
 Check `scan.truncated` before treating the result as complete, and `scan.failedDirs` to tell an incomplete scan (a directory that could not be read) from an empty one before pruning state from the listing.
 
+For caller-controlled paths, `Root.walk()` is the root-bounded async iterator.
+It supports entry/depth budgets, in-root symlink following, cancellation, and a
+truncation marker (or typed error) when a budget is reached. Its `entryFilter`
+can return `"skip-subtree"` to prune a directory, and
+`onDirectoryError: "skip-and-report"` yields typed `"directory-error"` markers
+while preserving entries from readable subtrees.
+
 ## Archive extraction
 
 `extractArchive()` handles ZIP and TAR behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets.
@@ -426,6 +464,7 @@ await extractArchive({
     maxEntries: 50_000,
     maxExtractedBytes: 512 * 1024 * 1024,
     maxEntryBytes: 256 * 1024 * 1024,
+    maxEntryPathComponents: 64,
   },
 });
 ```
@@ -474,19 +513,19 @@ if (err instanceof FsSafeError) {
 }
 ```
 
-Current `FsSafeErrorCode` values are `already-exists`, `denied-path`, `device-path`, `hardlink`, `helper-failed`, `helper-unavailable`, `invalid-path`, `insecure-permissions`, `not-empty`, `not-file`, `not-found`, `not-owned`, `not-removable`, `outside-workspace`, `path-alias`, `path-mismatch`, `permission-unverified`, `symlink`, `timeout`, `too-large`, and `unsupported-platform`.
+Current `FsSafeErrorCode` values are `already-exists`, `denied-path`, `device-path`, `hardlink`, `helper-failed`, `helper-unavailable`, `invalid-path`, `insecure-permissions`, `not-empty`, `not-file`, `not-found`, `not-owned`, `not-removable`, `outside-workspace`, `path-alias`, `path-mismatch`, `permission-unverified`, `secret-exists`, `symlink`, `timeout`, `too-large`, and `unsupported-platform`.
 
 ## Safety model
 
 - root-bounded APIs resolve paths against a configured root and reject canonical escapes
 - reads reject known unsafe device paths, open with `O_NOFOLLOW` where available, then verify fd identity matches the path identity before returning the buffer or handle
-- writes use pinned parent-directory helpers and atomic replacement on POSIX, with verified post-write identity
-- `remove`, `mkdir`, `move`, `stat`, `list`, and parent-fd writes use one persistent fd-relative Python helper on POSIX, with Node fallbacks when the helper is disabled or unavailable
+- create-only writes, sidecar acquisition, and exclusive publication prefer fd-relative native primitives, with verified guarded JavaScript fallbacks
+- `remove`, `mkdir`, `move`, `stat`, and `list` retain guarded JavaScript implementations with pre/post identity checks
 - archive extraction stages into a private directory and merges through the same boundary checks used by direct writes
 
 ## Limitations
 
-- Windows uses the safest Node-level behavior available; some fd-relative POSIX hardening is unavailable there.
+- Windows native opens are handle-relative and reject reparse points; operations without native wiring use the guarded Node implementation.
 - Hardlink rejection depends on platform metadata. Treat it as defense-in-depth, not authorization.
 - `fs-safe` does not validate file contents or archive payload semantics beyond filesystem safety constraints. Schemas, signatures, and authorization belong in the layer above.
 

package/dist/archive-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-entry.d.ts","sourceRoot":"","sources":["../src/archive-entry.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,IAAI,CAeN;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1F;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAQT"}
+{"version":3,"file":"archive-entry.d.ts","sourceRoot":"","sources":["../src/archive-entry.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,IAAI,CAkBN;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1F;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAWT"}

package/dist/archive-entry.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { ArchiveSecurityError } from "./archive-errors.js";
 import { resolveSafeBaseDir } from "./path.js";
 export function isWindowsDrivePath(value) {
     return /^[a-zA-Z]:[\\/]/.test(value);
@@ -11,15 +12,15 @@ export function validateArchiveEntryPath(entryPath, params) {
         return;
     }
     if (isWindowsDrivePath(entryPath)) {
-        throw new Error(`archive entry uses a drive path: ${entryPath}`);
+        throw new ArchiveSecurityError("entry-path", `archive entry uses a drive path: ${entryPath}`);
     }
     const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
     const escapeLabel = params?.escapeLabel ?? "destination";
     if (normalized === ".." || normalized.startsWith("../")) {
-        throw new Error(`archive entry escapes ${escapeLabel}: ${entryPath}`);
+        throw new ArchiveSecurityError("entry-path", `archive entry escapes ${escapeLabel}: ${entryPath}`);
     }
     if (path.posix.isAbsolute(normalized) || normalized.startsWith("//")) {
-        throw new Error(`archive entry is absolute: ${entryPath}`);
+        throw new ArchiveSecurityError("entry-path", `archive entry is absolute: ${entryPath}`);
     }
 }
 export function stripArchivePath(entryPath, stripComponents) {
@@ -41,7 +42,7 @@ export function resolveArchiveOutputPath(params) {
     const outPath = path.resolve(params.rootDir, params.relPath);
     const escapeLabel = params.escapeLabel ?? "destination";
     if (!outPath.startsWith(safeBase)) {
-        throw new Error(`archive entry escapes ${escapeLabel}: ${params.originalPath}`);
+        throw new ArchiveSecurityError("entry-path", `archive entry escapes ${escapeLabel}: ${params.originalPath}`);
     }
     return outPath;
 }

package/dist/archive-errors.d.ts

@@ -0,0 +1,11 @@
+export type ArchiveFormatErrorCode = "archive-header-invalid";
+export type ArchiveSecurityErrorCode = "destination-not-directory" | "destination-symlink" | "destination-symlink-traversal" | "entry-filtered" | "entry-link" | "entry-path";
+export declare class ArchiveSecurityError extends Error {
+    readonly code: ArchiveSecurityErrorCode;
+    constructor(code: ArchiveSecurityErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class ArchiveFormatError extends Error {
+    readonly code: ArchiveFormatErrorCode;
+    constructor(message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=archive-errors.d.ts.map

package/dist/archive-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-errors.d.ts","sourceRoot":"","sources":["../src/archive-errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,GAC/B,gBAAgB,GAChB,YAAY,GACZ,YAAY,CAAC;AAEjB,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IAExC,YAAY,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlF;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IAEtC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlD;CACF"}

package/dist/archive-errors.js

@@ -0,0 +1,16 @@
+export class ArchiveSecurityError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "ArchiveSecurityError";
+    }
+}
+export class ArchiveFormatError extends Error {
+    code;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ArchiveFormatError";
+        this.code = "archive-header-invalid";
+    }
+}

package/dist/archive-input.d.ts

@@ -0,0 +1,12 @@
+import type { ExtractionDeadline } from "./archive-deadline.js";
+import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
+export type StagedArchiveFile = {
+    path: string;
+    cleanup: () => Promise<void>;
+};
+export declare function stageArchiveFileForExtraction(params: {
+    archivePath: string;
+    limits: ResolvedArchiveExtractLimits;
+    deadline: ExtractionDeadline;
+}): Promise<StagedArchiveFile>;
+//# sourceMappingURL=archive-input.d.ts.map

package/dist/archive-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-input.d.ts","sourceRoot":"","sources":["../src/archive-input.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAM/E,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,4BAA4B,CAAC;IACrC,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8D7B"}

package/dist/archive-input.js

@@ -0,0 +1,72 @@
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeFileHandleFully } from "./archive-file-io.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, } from "./archive-limits.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { tempFile } from "./temp-target.js";
+async function closeFileHandle(handle) {
+    if (handle)
+        await handle.close().catch(() => undefined);
+}
+export async function stageArchiveFileForExtraction(params) {
+    params.deadline.check();
+    const sourcePath = path.resolve(params.archivePath);
+    const initialStat = await fs.lstat(sourcePath);
+    if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
+        throw new Error(`archive is not a regular file: ${params.archivePath}`);
+    }
+    if (initialStat.size > params.limits.maxArchiveBytes) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+    }
+    const noFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await fs.open(sourcePath, fsConstants.O_RDONLY | noFollow);
+    let staged;
+    let output;
+    try {
+        staged = await tempFile({
+            prefix: "fs-safe-archive-input",
+            fileName: path.basename(sourcePath),
+        });
+        const openedStat = await handle.stat();
+        const pathStat = await fs.lstat(sourcePath);
+        if (!openedStat.isFile() ||
+            pathStat.isSymbolicLink() ||
+            !pathStat.isFile() ||
+            !sameFileIdentity(initialStat, openedStat) ||
+            !sameFileIdentity(pathStat, openedStat)) {
+            throw new Error("archive changed during validation");
+        }
+        const flags = fsConstants.O_WRONLY |
+            fsConstants.O_CREAT |
+            fsConstants.O_EXCL |
+            (process.platform !== "win32" && "O_NOFOLLOW" in fsConstants
+                ? fsConstants.O_NOFOLLOW
+                : 0);
+        output = await fs.open(staged.path, flags, 0o600);
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let written = 0;
+        while (true) {
+            params.deadline.check();
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            written += bytesRead;
+            if (written > params.limits.maxArchiveBytes) {
+                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+            }
+            await writeFileHandleFully({ handle: output, buffer, bytes: bytesRead, deadline: params.deadline });
+        }
+        await output.close();
+        output = undefined;
+        return staged;
+    }
+    catch (error) {
+        await closeFileHandle(output);
+        await staged?.cleanup().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await closeFileHandle(handle);
+    }
+}

package/dist/archive-kind.d.ts

@@ -1,4 +1,4 @@
-export type ArchiveKind = "tar" | "zip";
+export type ArchiveKind = "tar" | "tar-bzip2" | "tar-zstd" | "zip";
 export declare function resolveArchiveKind(filePath: string): ArchiveKind | null;
 type ResolvePackedRootDirOptions = {
     rootMarkers?: string[];

package/dist/archive-kind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-kind.d.ts","sourceRoot":"","sources":["../src/archive-kind.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,CAAC;AAIxC,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CASvE;AAED,KAAK,2BAA2B,GAAG;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAkBF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,CAAC,CA4BjB"}
+{"version":3,"file":"archive-kind.d.ts","sourceRoot":"","sources":["../src/archive-kind.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;AAmBnE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAcvE;AAED,KAAK,2BAA2B,GAAG;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAkBF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,CAAC,CA4BjB"}

package/dist/archive-kind.js

@@ -1,12 +1,30 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
 const TAR_SUFFIXES = [".tgz", ".tar.gz", ".tar"];
+const NATIVE_TAR_SUFFIXES = [
+    { suffixes: [".tbz2", ".tbz", ".tar.bz2"], kind: "tar-bzip2" },
+    { suffixes: [".tzst", ".tar.zst", ".tar.zstd"], kind: "tar-zstd" },
+];
+function requireNativeArchiveKind(kind) {
+    if (!getNativeBinding()) {
+        throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding; ` +
+            "use FS_SAFE_NATIVE_MODE=auto or require on a supported platform");
+    }
+    return kind;
+}
 export function resolveArchiveKind(filePath) {
     const lower = normalizeLowercaseStringOrEmpty(filePath);
     if (lower.endsWith(".zip")) {
         return "zip";
     }
+    for (const { suffixes, kind } of NATIVE_TAR_SUFFIXES) {
+        if (suffixes.some((suffix) => lower.endsWith(suffix))) {
+            return requireNativeArchiveKind(kind);
+        }
+    }
     if (TAR_SUFFIXES.some((suffix) => lower.endsWith(suffix))) {
         return "tar";
     }

package/dist/archive-limits.d.ts

@@ -10,16 +10,25 @@ export type ArchiveExtractLimits = {
     maxExtractedBytes?: number;
     /** Max extracted bytes for a single file entry. */
     maxEntryBytes?: number;
+    /** Max bytes in one PAX, GNU long-name, or related TAR metadata entry. */
+    maxMetaEntryBytes?: number;
+    /** Max path components in one extracted entry after stripComponents. */
+    maxEntryPathComponents?: number;
 };
 export declare const DEFAULT_MAX_ARCHIVE_BYTES_ZIP: number;
 export declare const DEFAULT_MAX_ENTRIES = 50000;
 export declare const DEFAULT_MAX_EXTRACTED_BYTES: number;
 export declare const DEFAULT_MAX_ENTRY_BYTES: number;
+export declare const DEFAULT_MAX_META_ENTRY_BYTES: number;
+export declare const DEFAULT_MAX_ENTRY_PATH_COMPONENTS = 256;
 export declare const ARCHIVE_LIMIT_ERROR_CODE: {
     readonly ARCHIVE_SIZE_EXCEEDS_LIMIT: "archive-size-exceeds-limit";
     readonly ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit";
     readonly ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit";
     readonly EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit";
+    readonly META_ENTRY_SIZE_EXCEEDS_LIMIT: "archive-meta-entry-size-exceeds-limit";
+    readonly MANIFEST_SIZE_EXCEEDS_LIMIT: "archive-manifest-size-exceeds-limit";
+    readonly ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT: "archive-entry-path-components-exceeds-limit";
 };
 export type ArchiveLimitErrorCode = (typeof ARCHIVE_LIMIT_ERROR_CODE)[keyof typeof ARCHIVE_LIMIT_ERROR_CODE];
 export declare class ArchiveLimitError extends Error {
@@ -28,6 +37,7 @@ export declare class ArchiveLimitError extends Error {
 }
 export type ResolvedArchiveExtractLimits = Required<ArchiveExtractLimits>;
 export declare function resolveExtractLimits(limits?: ArchiveExtractLimits): ResolvedArchiveExtractLimits;
+export declare function assertArchiveEntryPathComponentsWithinLimit(entryPath: string, limits: ResolvedArchiveExtractLimits): void;
 export declare function assertArchiveEntryCountWithinLimit(entryCount: number, limits: ResolvedArchiveExtractLimits): void;
 export declare function createByteBudgetTracker(limits: ResolvedArchiveExtractLimits): {
     startEntry: () => void;

package/dist/archive-limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-limits.d.ts","sourceRoot":"","sources":["../src/archive-limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAoB,CAAC;AAC/D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,2BAA2B,QAAoB,CAAC;AAC7D,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAEzD,eAAO,MAAM,wBAAwB;aACnC,0BAA0B,EAAE,4BAA4B;aACxD,yBAAyB,EAAE,mCAAmC;aAC9D,kCAAkC,EAAE,4CAA4C;aAChF,4BAA4B,EAAE,sCAAsC;CAC5D,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAU3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC,YAAY,IAAI,EAAE,qBAAqB,EAItC;CACF;AAED,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAU1E,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,4BAA4B,CAQ9B;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,4BAA4B,QAKrC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG;IAC7E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAiCA;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,GAAG,SAAS,CAYZ"}
+{"version":3,"file":"archive-limits.d.ts","sourceRoot":"","sources":["../src/archive-limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAoB,CAAC;AAC/D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,2BAA2B,QAAoB,CAAC;AAC7D,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AACzD,eAAO,MAAM,4BAA4B,QAAc,CAAC;AACxD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD,eAAO,MAAM,wBAAwB;aACnC,0BAA0B,EAAE,4BAA4B;aACxD,yBAAyB,EAAE,mCAAmC;aAC9D,kCAAkC,EAAE,4CAA4C;aAChF,4BAA4B,EAAE,sCAAsC;aACpE,6BAA6B,EAAE,uCAAuC;aACtE,2BAA2B,EAAE,qCAAqC;aAClE,mCAAmC,EAAE,6CAA6C;CAC1E,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAgB3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC,YAAY,IAAI,EAAE,qBAAqB,EAItC;CACF;AAED,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAU1E,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,4BAA4B,CAY9B;AAED,wBAAgB,2CAA2C,CACzD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,4BAA4B,GACnC,IAAI,CASN;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,4BAA4B,QAKrC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG;IAC7E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAiCA;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,GAAG,SAAS,CAYZ"}

package/dist/archive-limits.js

@@ -3,17 +3,25 @@ export const DEFAULT_MAX_ARCHIVE_BYTES_ZIP = 256 * 1024 * 1024;
 export const DEFAULT_MAX_ENTRIES = 50_000;
 export const DEFAULT_MAX_EXTRACTED_BYTES = 512 * 1024 * 1024;
 export const DEFAULT_MAX_ENTRY_BYTES = 256 * 1024 * 1024;
+export const DEFAULT_MAX_META_ENTRY_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_ENTRY_PATH_COMPONENTS = 256;
 export const ARCHIVE_LIMIT_ERROR_CODE = {
     ARCHIVE_SIZE_EXCEEDS_LIMIT: "archive-size-exceeds-limit",
     ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit",
     ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit",
     EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit",
+    META_ENTRY_SIZE_EXCEEDS_LIMIT: "archive-meta-entry-size-exceeds-limit",
+    MANIFEST_SIZE_EXCEEDS_LIMIT: "archive-manifest-size-exceeds-limit",
+    ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT: "archive-entry-path-components-exceeds-limit",
 };
 const ARCHIVE_LIMIT_ERROR_MESSAGE = {
     [ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT]: "archive size exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT]: "archive entry count exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive entry extracted size exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive extracted size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT]: "archive metadata entry size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.MANIFEST_SIZE_EXCEEDS_LIMIT]: "archive manifest size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT]: "archive entry path components exceed limit",
 };
 export class ArchiveLimitError extends Error {
     code;
@@ -37,8 +45,18 @@ export function resolveExtractLimits(limits) {
         maxEntries: clampLimit(limits?.maxEntries) ?? DEFAULT_MAX_ENTRIES,
         maxExtractedBytes: clampLimit(limits?.maxExtractedBytes) ?? DEFAULT_MAX_EXTRACTED_BYTES,
         maxEntryBytes: clampLimit(limits?.maxEntryBytes) ?? DEFAULT_MAX_ENTRY_BYTES,
+        maxMetaEntryBytes: clampLimit(limits?.maxMetaEntryBytes) ?? DEFAULT_MAX_META_ENTRY_BYTES,
+        maxEntryPathComponents: clampLimit(limits?.maxEntryPathComponents) ?? DEFAULT_MAX_ENTRY_PATH_COMPONENTS,
     };
 }
+export function assertArchiveEntryPathComponentsWithinLimit(entryPath, limits) {
+    const components = entryPath
+        .split(/[\\/]+/u)
+        .filter((component) => component.length > 0 && component !== ".").length;
+    if (components > limits.maxEntryPathComponents) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT);
+    }
+}
 export function assertArchiveEntryCountWithinLimit(entryCount, limits) {
     if (entryCount > limits.maxEntries) {
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT);