tar-xz 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# tar-xz
+
+## [Unreleased]
+
+## [6.1.0] - 2026-04-29
+
+### ⚠️ BREAKING CHANGES
+- redesign for v6 — universal stream-first API (#108) (tar-xz) ([b2c8a8c](https://github.com/oorabona/node-liblzma/commit/b2c8a8c))
+
+### Added
+- true streaming for Node extract()/list() — O(largest entry) (#113) (tar-xz) ([06a9937](https://github.com/oorabona/node-liblzma/commit/06a9937))
+- wire memlimit through N-API decoder (#112) (native) ([0d09200](https://github.com/oorabona/node-liblzma/commit/0d09200))
+- wire memlimit option through unxzAsync/unxz (#111) (wasm) ([6e2bc09](https://github.com/oorabona/node-liblzma/commit/6e2bc09))
+- adopt Changesets for monorepo versioning + changelog generation (ci) ([adfbc99](https://github.com/oorabona/node-liblzma/commit/adfbc99))
+- redesign for v6 — universal stream-first API (#108) (tar-xz) ⚠️ BREAKING ([b2c8a8c](https://github.com/oorabona/node-liblzma/commit/b2c8a8c))
+
+### Fixed
+- close Win32 symlink-swap TOCTOU with JS-pure 'wx'+retry fail-closed (#114) (tar-xz) ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- re-add @changesets/cli (was clobbered by pnpm add of changelog-github) (deps) ([6d76280](https://github.com/oorabona/node-liblzma/commit/6d76280))
+- use 'changeset' so the bin resolves with --ignore-scripts (ci) ([78b91f7](https://github.com/oorabona/node-liblzma/commit/78b91f7))
+- toAsyncIterable mis-dispatched Uint8Array via Symbol.iterator ([b2c8a8c](https://github.com/oorabona/node-liblzma/commit/b2c8a8c))
+- use always() in publish job to bypass skipped build (workspace target) (ci) ([2e08977](https://github.com/oorabona/node-liblzma/commit/2e08977))
+- pin pnpm/action-setup to v5 in refresh-lockfile (v6 corrupts lockfile) (ci) ([f39d603](https://github.com/oorabona/node-liblzma/commit/f39d603))
+- regenerate pnpm-lock.yaml (was broken with duplicate YAML document) (deps) ([e0c66ab](https://github.com/oorabona/node-liblzma/commit/e0c66ab))
+- use squash merge in Dependabot auto-merge (linear history required) (ci) ([f3aee60](https://github.com/oorabona/node-liblzma/commit/f3aee60))
+- point tar-xz demo Vite alias to browser entry ([8aea7ac](https://github.com/oorabona/node-liblzma/commit/8aea7ac))
+- point demo Vite alias to browser entry (fixes docs build) ([e86dba5](https://github.com/oorabona/node-liblzma/commit/e86dba5))
+
+### Changed
+- finalize WIN32-TOCTOU-2026-04-29 — promote spec, mark TODO done ([1ee9db4](https://github.com/oorabona/node-liblzma/commit/1ee9db4))
+- node-tar is pure JS and explicitly does NOT protect Windows ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 0 errors. Type-check: 0 errors. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 155 pass / 0 fail / 3 pre-existing skips. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 0 errors. Type-check: 0 errors. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 155 pass / 0 fail / 3 pre-existing skips (identical to pre-fix). ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 0 errors. Type-check: 0 errors. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- round 1 = 6 findings (3 M + 2 L + 1 misclassified), round 2 ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 155 pass / 0 fail / 3 pre-existing skips. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 0 errors. Type-check: 0 errors. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- round 1 = 6 findings, round 2 = 3, round 3 = 1, round 4 ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 155 pass / 0 fail / 3 pre-existing skips. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 0 errors. Type-check: 0 errors. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- round 1=6, round 2=3, round 3=1, round 4=3 (2 real Ms in ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 155 pass / 0 fail / 3 pre-existing skips. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- 0 errors. Type-check: 0 errors. ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- round 1=6, round 2=3, round 3=1, round 4=3 (2 real Ms ([b24040d](https://github.com/oorabona/node-liblzma/commit/b24040d))
+- refresh lockfile for latest transitive dependencies (deps) ([06e9590](https://github.com/oorabona/node-liblzma/commit/06e9590))
+- finally swallows cleanup errors on consumer-break, ([06a9937](https://github.com/oorabona/node-liblzma/commit/06a9937))
+- 150+3-skip pass; memory 3+1-skip pass. tsc + lint + build green. ([06a9937](https://github.com/oorabona/node-liblzma/commit/06a9937))
+- refresh lockfile for latest transitive dependencies (deps) ([f8f21d0](https://github.com/oorabona/node-liblzma/commit/f8f21d0))
+- - release-it (existing release.yml + .release-it.json) is retained for ([adfbc99](https://github.com/oorabona/node-liblzma/commit/adfbc99))
+- capture tar-xz v6 redesign in CHANGELOGs + TODO.md ([9abd0a2](https://github.com/oorabona/node-liblzma/commit/9abd0a2))
+- test fails on revert, passes on fix. ([b2c8a8c](https://github.com/oorabona/node-liblzma/commit/b2c8a8c))
+- release v5.0.1 (tar-xz) ([0c631f5](https://github.com/oorabona/node-liblzma/commit/0c631f5))
+- sync workspace package versions to npm registry (3.2.0 -> 5.0.0) ([900a055](https://github.com/oorabona/node-liblzma/commit/900a055))
+- refresh lockfile for latest transitive dependencies (deps) ([8345c25](https://github.com/oorabona/node-liblzma/commit/8345c25))
+- propagate anti-flake cleanup pattern to 3 high-risk integration tests ([f752664](https://github.com/oorabona/node-liblzma/commit/f752664))
+- add afterEach cleanup + timer tracking in error_recovery test (anti-flake) ([2d7f285](https://github.com/oorabona/node-liblzma/commit/2d7f285))
+- refresh lockfile for latest transitive dependencies (deps) ([bc7e804](https://github.com/oorabona/node-liblzma/commit/bc7e804))
+- refresh lockfile for latest transitive dependencies (deps) ([dedd2c1](https://github.com/oorabona/node-liblzma/commit/dedd2c1))
+- bump @vitest/ui (#106) (deps-dev) ([276f0b4](https://github.com/oorabona/node-liblzma/commit/276f0b4))
+- refresh lockfile for latest transitive dependencies (deps) ([8b7b5b9](https://github.com/oorabona/node-liblzma/commit/8b7b5b9))
+- ignore pnpm/action-setup v6+ in Dependabot (corrupts lockfile) (ci) ([fd2cf8c](https://github.com/oorabona/node-liblzma/commit/fd2cf8c))
+- refresh lockfile for latest transitive dependencies (deps) ([a01694e](https://github.com/oorabona/node-liblzma/commit/a01694e))
+- refresh lockfile for latest transitive dependencies (deps) ([e2eca27](https://github.com/oorabona/node-liblzma/commit/e2eca27))
+- refresh lockfile for latest transitive dependencies (deps) ([b1386e9](https://github.com/oorabona/node-liblzma/commit/b1386e9))
+- refresh lockfile for latest transitive dependencies (deps) ([1ba850e](https://github.com/oorabona/node-liblzma/commit/1ba850e))
+- refresh lockfile for latest transitive dependencies (deps) ([e66f8fb](https://github.com/oorabona/node-liblzma/commit/e66f8fb))
+- refresh lockfile for latest transitive dependencies (deps) ([fd906d6](https://github.com/oorabona/node-liblzma/commit/fd906d6))
+- refresh lockfile for latest transitive dependencies (deps) ([e085fa4](https://github.com/oorabona/node-liblzma/commit/e085fa4))
+- bump @vitest/ui in the dev-dependencies group (#95) (deps-dev) ([01e828c](https://github.com/oorabona/node-liblzma/commit/01e828c))
+- refresh lockfile for latest transitive dependencies (deps) ([cfe60ca](https://github.com/oorabona/node-liblzma/commit/cfe60ca))
+- refresh lockfile for latest transitive dependencies (deps) ([1d0dd42](https://github.com/oorabona/node-liblzma/commit/1d0dd42))
+- refresh lockfile for latest transitive dependencies (deps) ([775ed0f](https://github.com/oorabona/node-liblzma/commit/775ed0f))
+- refresh lockfile for latest transitive dependencies (deps) ([9a66903](https://github.com/oorabona/node-liblzma/commit/9a66903))
+- refresh lockfile for latest transitive dependencies (deps) ([3e2bd44](https://github.com/oorabona/node-liblzma/commit/3e2bd44))
+- refresh lockfile for latest transitive dependencies (deps) ([d3bea99](https://github.com/oorabona/node-liblzma/commit/d3bea99))
+
+### Removed
+- - extractToMemory() — replaced by extract() + entry.bytes() ([b2c8a8c](https://github.com/oorabona/node-liblzma/commit/b2c8a8c))
+
+## 6.0.0
+
+### Major Changes
+
+Complete API redesign. Universal stream-first design — same signatures in Node and Browser, built around `AsyncIterable<Uint8Array>`.
+
+#### New API
+
+- **Universal `create()`, `extract()`, `list()`** — identical signatures across Node and Browser.
+- **`tar-xz/file` subpath export** (Node only) — opt-in path-based helpers `createFile()`, `extractFile()`, `listFile()`. Keeps the core SRP-clean (no fs deps in the core).
+- **`AsyncIterable<TarEntryWithData>`** from `extract()` — entries yielded lazily; each carries a streaming `data` AsyncIterable plus `bytes()` and `text()` collector helpers.
+- **`TarInput` union type** — accepts `AsyncIterable<Uint8Array>`, `Iterable<Uint8Array>`, `Uint8Array`, `ArrayBuffer`, `ReadableStream<Uint8Array>` (Web), or `NodeJS.ReadableStream`.
+
+#### Security hardening
+
+Comprehensive symlink/path TOCTOU hardening (18 vectors audited and closed in a single consolidated commit, after 7 rounds of Copilot review):
+
+- Leaf symlink check (`target` itself, not just ancestors).
+- Ancestor symlink walk extended to FILE/DIRECTORY/SYMLINK/HARDLINK.
+- ENOENT correctly continues the ancestor walk instead of stopping.
+- Hardlink `linkSource` validated for symlink-leaf and symlink-ancestor.
+- `strip` option applied to both `name` and `linkname`.
+- Empty / NUL-bearing names and linknames rejected.
+- Dot-segment placeholder names (`.`, `./`, `..`) rejected.
+- Setuid/setgid/sticky bits stripped from extracted modes by default (mirrors GNU tar `--no-same-permissions`).
+- File extraction uses `fs.open(O_NOFOLLOW)` + fd-based `chmod`/`utimes` on POSIX — eliminates by-path TOCTOU window for permissions/timestamps.
+- `pipeline()` instead of `pipe()` so source errors propagate properly.
+- Threat-model documentation: concurrent attacker process is explicitly out of scope (POSIX `openat2(RESOLVE_BENEATH)` not exposed by Node).
+
+#### Removed
+
+- `extractToMemory()` — replaced by `extract()` + `entry.bytes()`.
+- `createTarXz()` / `extractTarXz()` / `listTarXz()` (browser-prefixed names) — replaced by unified `create()` / `extract()` / `list()`.
+- `BrowserCreateOptions` / `BrowserExtractOptions` — unified into single `CreateOptions` / `ExtractOptions`.
+- `ExtractedFile` — replaced by `TarEntryWithData`.
+
+#### Changed
+
+- Source files for `create()` use the new `TarSourceFile` shape: `{ name, source, mode?, mtime?, linkname? }`. `source` accepts `AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer | string` (string is a Node-only fs path).
+- `TarPack` / `TarUnpack` Transform classes are now internal; not exported from the package root.
+- Default compression preset is uniform: `6` (Node and Browser).
+
+#### Migration v5 → v6
+
+See [README.md § Migration v5 → v6](./README.md#migration-v5--v6) for full code examples.
+
+## 5.0.1
+
+### Patch Changes
+
+- Workspace package versions synchronized to npm registry (3.2.0 → 5.0.0). Internal infrastructure updates (CI workflows, lockfile maintenance, anti-flake test cleanup). No API changes.
+
+[Unreleased]: https://github.com/oorabona/node-liblzma/compare/v6.1.0...HEAD
+[v6.1.0]: https://github.com/oorabona/node-liblzma/releases/tag/v6.1.0
+[6.1.0]: https://github.com/oorabona/node-liblzma/releases/tag/v6.1.0

package/README.md

@@ -12,7 +12,7 @@ function names in both environments.
 ## Features
 
 - **Unified API** — `create`, `extract`, `list` work identically in Node.js and browsers
-- **Stream-shaped API** — all functions return `AsyncIterable<…>`; stream-shaped inputs accepted. Note: current Node `extract()`/`list()` implementations buffer internally — true streaming is a planned optimization
+- **Stream-shaped API** — all functions return `AsyncIterable<…>`; stream-shaped inputs accepted. Node `extract()`/`list()` now stream chunks as XZ decompresses them — memory stays O(largest single entry). v6.0.0 introduced the stream-first API contract; v6.1.0 delivers the planned optimization that fulfills it.
 - **Flexible input** — `extract()` and `list()` accept `AsyncIterable`, `Uint8Array`,
   `ArrayBuffer`, Web `ReadableStream`, or Node `ReadableStream`
 - **Flexible source** — `create()` accepts fs paths (Node), `Buffer`/`Uint8Array`, or
@@ -178,6 +178,35 @@ for (const entry of entries) {
 Do not import `tar-xz/file` in browser bundles — it imports `node:fs` and will
 fail at runtime. Use `create`/`extract`/`list` directly in browser code.
 
+## Security model
+
+`extractFile` enforces layered path-safety checks before writing any bytes to
+disk: traversal detection (`..` and absolute paths), leaf-symlink rejection
+(`O_NOFOLLOW` on POSIX), ancestor-symlink TOCTOU guard, hardlink validation,
+NUL/empty name rejection, and setuid/setgid/sticky-bit stripping.
+
+The TOCTOU mitigation differs by platform:
+
+**POSIX (Linux, macOS):** FILE entries are written through a file descriptor
+opened with `O_NOFOLLOW`. The fd is held open for the entire streaming write,
+so the window between the safety check and the last write is effectively zero.
+
+**Windows:** `O_NOFOLLOW` is not available. Extraction falls back to by-path
+stream operations (`createWriteStream`). With streaming delivery (v6.1.0), the
+window between the initial safety check and the last written byte scales with
+the entry's size — a co-tenant process that can modify `cwd` could race a
+symlink swap during this window.
+
+**Windows recommendation:** always extract to a directory owned exclusively by
+the calling process. Do not extract user-supplied archives into shared,
+world-writable, or `TEMP`-like directories on Windows.
+
+This gap is now closed: the Windows path uses `open(target, 'wx')` (atomic
+exclusive create) with an unlink+retry pattern for legitimate overwrites. If a symlink
+is injected between the unlink and the retry-open, extraction fails with a security error.
+All writes and metadata operations are fd-based. See [SECURITY.md](./SECURITY.md#windows-symlink-swap-toctou)
+for the full reparse-tag coverage table and user mitigations.
+
 ## Streaming Patterns
 
 ### Hash while creating

package/SECURITY.md

@@ -0,0 +1,103 @@
+# tar-xz Security Notes
+
+## Windows symlink-swap TOCTOU
+
+### Background
+
+On POSIX (Linux, macOS), `extractFile` opens each regular-file entry with
+`O_NOFOLLOW` (`O_CREAT | O_WRONLY | O_TRUNC | O_NOFOLLOW`). This ensures the
+kernel refuses to open a symlink at the leaf path, closing the symlink-swap
+attack window from the moment the file handle is opened.
+
+On Windows, `O_NOFOLLOW` is not available (libuv/Win32 does not expose it).
+Prior to this hardening, the Windows path used `createWriteStream(target)` — a
+by-path operation that could be redirected by a symlink injected between the
+upstream safety check and the final write.
+
+### What changed in this hardening
+
+The Windows extraction path now uses `open(target, 'wx', mode)` — the `'wx'`
+flag maps to `O_CREAT | O_EXCL` in libuv, an atomic "create or fail" syscall.
+Writes, `chmod`, and `utimes` are all performed through the resulting
+`FileHandle`, immune to any by-path swap after the open.
+
+The full sequence:
+
+1. **First `open('wx')`** — succeeds if the target does not exist (no prior
+   file or symlink at that path). All subsequent I/O via the file descriptor.
+2. **`EEXIST` on first open** — a regular file exists (legitimate re-extract
+   case): call `unlink(target)` then retry `open('wx')`.
+3. **`EEXIST` on retry** — a symlink (or other reparse point) was injected
+   between our `unlink` and our retry-open. Extraction is rejected with a
+   security error citing the entry name. No bytes are written.
+
+### Closed attack windows
+
+| Window | From → To | Status |
+|--------|-----------|--------|
+| W1 | `lstat` check → `open()` | Closed — atomic `'wx'` EEXIST-path detects injection |
+| W2 | `open()` → last byte written | Closed — fd-based `handle.write()` follows the inode, not the path |
+| W3 | last byte → `chmod` | Closed — `handle.chmod()` (fd-based) |
+| W4 | `chmod` → `utimes` | Closed — `handle.utimes()` (fd-based) |
+
+### Residual race
+
+The `open()` syscall itself is atomic at the OS level (sub-microsecond). A
+symlink injected **during** the `open()` syscall cannot win — the kernel either
+creates the new inode or returns `EEXIST` atomically. There is no window inside
+`open()`.
+
+### Reparse-point coverage table
+
+Windows supports several reparse-point types beyond `IO_REPARSE_TAG_SYMLINK`.
+The table below documents what each type means for the `'wx'` fail-closed contract:
+
+| Reparse tag | Detected by `lstat().isSymbolicLink()` | Behavior under `'wx'` | Risk level |
+|-------------|----------------------------------------|----------------------|------------|
+| `IO_REPARSE_TAG_SYMLINK` | **Yes** — rejected by upstream `ensureSafeTarget` before `'wx'` is attempted | n/a (caught upstream) | None |
+| `IO_REPARSE_TAG_MOUNT_POINT` (NTFS junction) | **No** — `lstat` returns `isSymbolicLink() === false` for junctions | `'wx'` returns `EEXIST` → `unlink` removes the junction → retry `'wx'` succeeds or attacker re-injects → security error | **Leaf protected** by `'wx'` EEXIST fail-closed |
+| OneDrive / cloud-files placeholders (`IO_REPARSE_TAG_CLOUD_FILES`, etc.) | **No** — cloud stubs look like regular files to `lstat` | `'wx'` returns `EEXIST` → handled via normal overwrite path (unlink + retry) | Low — cloud stubs are regular-file-like; write lands on the stub, which hydrates on access |
+| `IO_REPARSE_TAG_AF_UNIX` | **No** | `'wx'` returns `EEXIST` → unlink + retry path | Low — same as junction path |
+
+**Summary:** The only reparse type that can be present at the *leaf* target
+path and bypasses `isSymbolicLink()` is `IO_REPARSE_TAG_MOUNT_POINT`
+(NTFS junctions). The `'wx'` fail-closed pattern protects the leaf in all
+cases — if an attacker injects a junction between `unlink` and the retry-open,
+`'wx'` returns `EEXIST` and we throw the security error.
+
+**Ancestor junctions (residual risk):** The upstream `hasSymlinkAncestor`
+walk uses `lstat().isSymbolicLink()` and does not detect junctions in ancestor
+directories. This is a pre-existing limitation shared by `node-tar` and other
+pure-JS tar libraries. It is not introduced by this change. See "User
+mitigations" below.
+
+### Notes on hardlinks, case-insensitive NTFS, and ADS
+
+**Hardlinks:** A hardlink injected during the unlink+retry race creates a
+directory entry at the target path. Our retry `'wx'` returns `EEXIST` →
+security error (fail-closed). Pre-existing hardlinks are regular files that
+share an inode; `unlink` decrements the link count and our `'wx'` creates a
+new inode. Semantically correct.
+
+**Case-insensitive NTFS:** All path operations resolve to the same directory
+entry regardless of case. This is not a bypass vector — `path.resolve` produces
+a canonical path that is used consistently.
+
+**NTFS Alternate Data Streams (ADS):** Out of scope. ADS does not affect the
+default data stream. Tar entry names containing `:` are rejected upstream by
+path-traversal validation before reaching this code.
+
+### User mitigations
+
+For environments where even the residual ancestor-junction risk is unacceptable:
+
+1. **Restricted-ACL temp directory** — extract under a directory with an ACL
+   that prevents other users/processes from creating files or junctions inside
+   it. On Windows, use `CreateDirectory` + `SetSecurityInfo` to set a DACL
+   that grants write access only to the calling process's SID.
+2. **Prefer WSL for untrusted archives** — Windows Subsystem for Linux uses
+   the Linux VFS with full `O_NOFOLLOW` support. `extractFile` on WSL takes the
+   POSIX branch and is fully protected.
+3. **Verify archive origin** — do not extract archives from untrusted sources
+   into directories writable by other processes (world-writable temp dirs,
+   shared application data folders, etc.).

package/lib/node/extract.d.ts

@@ -2,7 +2,7 @@
  * Node.js TAR extraction with XZ decompression — v6 AsyncIterable API
  */
 import type { TarInputNode } from '../internal/to-async-iterable.js';
-import { type ExtractOptions, type TarEntryWithData } from '../types.js';
+import type { ExtractOptions, TarEntryWithData } from '../types.js';
 /**
  * Extract a tar.xz archive.
  *
@@ -20,7 +20,7 @@ import { type ExtractOptions, type TarEntryWithData } from '../types.js';
  * }
  * ```
  */
-export declare function extract(input: TarInputNode, options?: ExtractOptions): AsyncIterable<TarEntryWithData>;
+export declare function extract(input: TarInputNode, options?: ExtractOptions): AsyncGenerator<TarEntryWithData>;
 /**
  * Extract archive to memory (no disk writes)
  */

package/lib/node/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/node/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,gBAAgB,EAEtB,MAAM,aAAa,CAAC;AAgIrB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,OAAO,CAC5B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAAC,gBAAgB,CAAC,CAwBjC;AAED;;GAEG"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/node/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAY,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAkG9E;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAuB,OAAO,CAC5B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAAC,gBAAgB,CAAC,CA8HlC;AAED;;GAEG"}

package/lib/node/extract.js

@@ -1,124 +1,85 @@
 /**
  * Node.js TAR extraction with XZ decompression — v6 AsyncIterable API
  */
-import { Writable } from 'node:stream';
-import { calculatePadding } from '../tar/index.js';
 import { stripPath } from '../tar/utils.js';
-import { TarEntryType, } from '../types.js';
-import { parseNextHeader } from './tar-parser.js';
-import { collectAllChunks, decompressXz, runWritable } from './xz-helpers.js';
-/** Wrap a TarEntry + content Buffer into a TarEntryWithData. */
-function makeTarEntryWithData(entry, content) {
-    const u8 = new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
-    async function collectBytes() {
-        return u8;
-    }
-    async function collectText(encoding) {
-        const bytes = await collectBytes();
-        const enc = (encoding ?? 'utf-8');
-        return Buffer.from(bytes).toString(enc);
-    }
-    return {
-        ...entry,
-        data: (async function* () {
-            if (u8.length > 0)
-                yield u8;
-        })(),
-        bytes: collectBytes,
-        text: collectText,
-    };
-}
+import { parseTar } from './tar-parser.js';
+import { streamXz } from './xz-helpers.js';
 /**
- * Transform stream that unpacks TAR format
+ * Concatenate an array of Uint8Array chunks into a single Uint8Array.
+ * @internal
  */
-class TarUnpack extends Writable {
-    state = {
-        buffer: Buffer.alloc(0),
-        paxAttrs: null,
-        emptyBlockCount: 0,
+/**
+ * Wrap a TarEntry + a pull-callback for its content into a TarEntryWithData.
+ *
+ * The `dataPull` callback returns an `AsyncGenerator<Uint8Array>` that is
+ * backed by the outer `parseTar` generator. It is single-use — consuming it
+ * twice yields nothing on the second pass (JS AsyncGenerator default).
+ *
+ * `bytes()` throws if `entry.data` was already iterated — call `bytes()` before
+ * iterating `entry.data` if you need the full content (D-3 / F-2 contract).
+ * `text()` uses `Buffer.toString()` and accepts any `BufferEncoding` (including
+ * `'base64'`, `'hex'`, `'latin1'`) — same contract as the pre-v6.1.0 behavior.
+ * Holding a reference to the returned entry also holds the cached bytes; release
+ * the entry to allow GC.
+ */
+function makeTarEntryWithData(entry, dataPull) {
+    let cachedBytes = null;
+    let dataIterStarted = false;
+    const dataGen = dataPull(); // single-use generator
+    // Wrap dataGen so that direct iteration of `entry.data` is detected.
+    // When the consumer calls `for await (const chunk of entry.data)`, the
+    // wrapper sets `dataIterStarted = true` so that a subsequent `bytes()` call
+    // can throw instead of silently returning incomplete bytes.
+    // Wrap dataGen behind a plain AsyncIterable so that:
+    //   1. `for await` iteration sets `dataIterStarted = true` (F-2 guard)
+    //   2. The type is `AsyncIterable<Uint8Array>` — matching TarEntryWithData.data
+    //      and avoiding the `[Symbol.asyncDispose]` requirement that TS/lib.esnext
+    //      adds to the full `AsyncGenerator` interface (Explicit Resource Management).
+    const dataWrapper = {
+        [Symbol.asyncIterator]() {
+            dataIterStarted = true;
+            return dataGen;
+        },
+    };
+    return {
+        ...entry,
+        data: dataWrapper,
+        async bytes() {
+            if (cachedBytes !== null)
+                return cachedBytes;
+            if (dataIterStarted) {
+                throw new Error('entry.data already iterated; bytes() cannot recover full content — call bytes() before iterating entry.data');
+            }
+            dataIterStarted = true;
+            // Alloc-once optimisation: entry.size is known from the TAR header, so we
+            // pre-allocate a single buffer and set() each arriving chunk at its running
+            // offset. This halves peak memory vs the chunks-array-then-concat pattern
+            // (no intermediate array + final copy simultaneously resident).
+            if (entry.size === 0) {
+                cachedBytes = new Uint8Array(0);
+                return cachedBytes;
+            }
+            const buf = new Uint8Array(entry.size);
+            let offset = 0;
+            for await (const c of dataGen) {
+                if (offset + c.byteLength > entry.size) {
+                    // Malformed archive: chunk would write past the declared entry size.
+                    // Truncate at entry.size to avoid out-of-bounds writes and throw so
+                    // callers know the data is corrupt. Code matches the TAR_PARSER_INVARIANT
+                    // convention used in parseTar (corrupt archive detected at parse level).
+                    throw Object.assign(new Error(`tar: entry "${entry.name}" declared size ${entry.size} but received more bytes (offset ${offset} + chunk ${c.byteLength} = ${offset + c.byteLength})`), { code: 'TAR_PARSER_INVARIANT' });
+                }
+                buf.set(c, offset);
+                offset += c.byteLength;
+            }
+            cachedBytes = buf;
+            return cachedBytes;
+        },
+        async text(encoding) {
+            const raw = await this.bytes();
+            return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString((encoding ?? 'utf8'));
+        },
     };
-    currentEntry = null;
-    bytesRemaining = 0;
-    paddingRemaining = 0;
-    contentChunks = [];
-    entries = [];
-    _write(chunk, _encoding, callback) {
-        this.state.buffer = Buffer.concat([this.state.buffer, chunk]);
-        try {
-            this.processBuffer();
-            callback();
-        }
-        catch (error) {
-            callback(error);
-        }
-    }
-    /** Skip padding bytes that follow a file's content blocks. */
-    skipPadding() {
-        if (this.paddingRemaining <= 0) {
-            return false;
-        }
-        const skip = Math.min(this.paddingRemaining, this.state.buffer.length);
-        this.state.buffer = this.state.buffer.subarray(skip);
-        this.paddingRemaining -= skip;
-        return true;
-    }
-    /** Read file content bytes into `contentChunks`; finalize entry when done. */
-    readContent() {
-        if (this.bytesRemaining <= 0 || !this.currentEntry) {
-            return false;
-        }
-        const readSize = Math.min(this.bytesRemaining, this.state.buffer.length);
-        this.contentChunks.push(this.state.buffer.subarray(0, readSize));
-        this.state.buffer = this.state.buffer.subarray(readSize);
-        this.bytesRemaining -= readSize;
-        if (this.bytesRemaining === 0) {
-            const content = Buffer.concat(this.contentChunks);
-            this.entries.push({ ...this.currentEntry, content });
-            this.paddingRemaining = calculatePadding(this.currentEntry.size);
-            this.currentEntry = null;
-            this.contentChunks = [];
-        }
-        return true;
-    }
-    /** Push a no-content entry (directory, symlink, hardlink, empty file). */
-    pushEmptyEntry(entry) {
-        this.entries.push({ ...entry, content: Buffer.alloc(0) });
-    }
-    /** Dispatch a parsed entry: push immediately or prepare for content read. */
-    handleEntry(entry) {
-        if (entry.type === TarEntryType.DIRECTORY ||
-            entry.type === TarEntryType.SYMLINK ||
-            entry.type === TarEntryType.HARDLINK ||
-            entry.size === 0) {
-            this.pushEmptyEntry(entry);
-            return;
-        }
-        this.currentEntry = entry;
-        this.bytesRemaining = entry.size;
-        this.contentChunks = [];
-    }
-    processBuffer() {
-        while (this.state.buffer.length > 0) {
-            if (this.skipPadding())
-                continue;
-            if (this.readContent())
-                continue;
-            const result = parseNextHeader(this.state);
-            if (result.action === 'need-more-data' || result.action === 'end-of-archive')
-                break;
-            if (result.action === 'pax-consumed')
-                continue;
-            this.handleEntry(result.entry);
-        }
-    }
-    _final(callback) {
-        if (this.bytesRemaining > 0) {
-            callback(new Error(`Unexpected end of archive, ${this.bytesRemaining} bytes remaining`));
-        }
-        else {
-            callback();
-        }
-    }
 }
 /**
  * Extract a tar.xz archive.
@@ -137,23 +98,130 @@ class TarUnpack extends Writable {
  * }
  * ```
  */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: streaming generator with strip/filter/drain logic — complexity is intrinsic
 export async function* extract(input, options = {}) {
     const { strip = 0, filter } = options;
-    const chunks = await collectAllChunks(input);
-    const tarData = await decompressXz(chunks);
-    const tarUnpack = new TarUnpack();
-    await runWritable(tarUnpack, tarData);
-    for (const entry of tarUnpack.entries) {
-        const strippedName = stripPath(entry.name, strip);
-        if (!strippedName) {
-            continue;
+    const xzStream = streamXz(input);
+    const parser = parseTar(xzStream, 'extract');
+    // Lookahead: an event pulled from parseTar that hasn't been processed yet.
+    // This allows the data-generator to consume chunks and then "return" the
+    // terminating event (entry/end) for the outer loop to process.
+    let lookahead = null;
+    /** Pull next event from parser, respecting any pending lookahead. */
+    async function nextEvent() {
+        if (lookahead !== null) {
+            const ev = lookahead;
+            lookahead = null;
+            return { value: ev, done: false };
+        }
+        return parser.next();
+    }
+    /** Drain all remaining 'chunk' events for the current entry from parseTar.
+     *  The terminating 'entry' or 'end' event is stored in `lookahead`. */
+    async function drainChunks() {
+        while (true) {
+            const result = await parser.next();
+            if (result.done)
+                return;
+            if (result.value.kind !== 'chunk') {
+                lookahead = result.value;
+                return;
+            }
+        }
+    }
+    try {
+        while (true) {
+            const result = await nextEvent();
+            if (result.done)
+                break;
+            const ev = result.value;
+            if (ev.kind === 'end')
+                break;
+            if (ev.kind === 'chunk') {
+                // Stray chunk at outer-loop level is a parser invariant violation (D-5).
+                const err = new Error('parser invariant: chunk emitted before entry');
+                err.code = 'TAR_PARSER_INVARIANT';
+                throw err;
+            }
+            // ev.kind === 'entry'
+            const rawEntry = ev.entry;
+            const strippedName = stripPath(rawEntry.name, strip);
+            if (!strippedName) {
+                await drainChunks();
+                continue;
+            }
+            const strippedEntry = { ...rawEntry, name: strippedName };
+            if (filter && !filter(strippedEntry)) {
+                await drainChunks();
+                continue;
+            }
+            // Build a data generator that pulls 'chunk' events from the parseTar stream.
+            // When chunks are exhausted it stores the next 'entry'/'end' in `lookahead`.
+            // The outer generator is suspended at `yield entryWithData` while the consumer
+            // iterates this — natural backpressure.
+            let dataGenInFlight = false;
+            function makeDataGen() {
+                if (dataGenInFlight) {
+                    throw new Error('concurrent entry.data iteration is not supported');
+                }
+                dataGenInFlight = true;
+                return (async function* () {
+                    try {
+                        while (true) {
+                            const r = await parser.next();
+                            if (r.done)
+                                return;
+                            if (r.value.kind === 'chunk') {
+                                yield r.value.data;
+                            }
+                            else {
+                                // 'entry' or 'end' — store for outer loop.
+                                lookahead = r.value;
+                                return;
+                            }
+                        }
+                    }
+                    finally {
+                        dataGenInFlight = false;
+                    }
+                })();
+            }
+            const entryWithData = makeTarEntryWithData(strippedEntry, makeDataGen);
+            yield entryWithData;
+            // After the consumer advances past this entry, drain any remaining chunks
+            // that the consumer did not read (S-08 auto-drain, Case A per §12.4).
+            // If the data generator was fully consumed, lookahead is already set.
+            // If not, drain now.
+            if (lookahead === null) {
+                // Consumer did not fully iterate entry.data — drain remaining chunks.
+                try {
+                    await drainChunks();
+                }
+                catch (err) {
+                    // Decode/IO error during skipped data — swallow per D-2.
+                    // TAR_PARSER_INVARIANT always re-throws per D-5.
+                    if (err.code === 'TAR_PARSER_INVARIANT') {
+                        throw err;
+                    }
+                    // Swallow other errors from skipped data per D-2.
+                }
+            }
+        }
+    }
+    finally {
+        // Case B (consumer break): close parser, no drain needed.
+        // Swallow cleanup errors per D-2. TAR_PARSER_INVARIANT handling: per D-5 these
+        // should always re-throw, but noUnsafeFinally prohibits throw in finally.
+        // In practice a TAR_PARSER_INVARIANT during parser.return() is a bug in our own
+        // code, not in the caller's data — the iterator is already being abandoned, so
+        // the invariant error will surface on the NEXT use attempt, which is unreachable
+        // here. We swallow it the same as other cleanup errors.
+        try {
+            await parser.return(undefined);
         }
-        const strippedEntry = { ...entry, name: strippedName };
-        if (filter && !filter(strippedEntry)) {
-            continue;
+        catch {
+            // Swallow all cleanup errors per D-2.
         }
-        const entryContent = entry.content;
-        yield makeTarEntryWithData(strippedEntry, entryContent);
     }
 }
 /**