@blamejs/core 0.12.8 → 0.12.9

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.9 (2026-05-23) — **`b.archive.gz` + `b.archive.read.gz` — gzip composition with `b.safeDecompress` bomb caps + `b.backup` `tar.gz` bundle format + `sha-to-tag verify` fetches `origin/main`.** gzip lands as the composition layer over the archive family. `b.archive.gz(bytes)` produces an RFC 1952 gzip stream with the same `toBuffer()` / `toAdapter(adapter)` / `digest()` shape every archive builder ships, and `b.archive.read.gz(adapter, opts)` reads it back through `b.safeDecompress` so a malicious `tar.gz` fails the gzip-layer bomb cap (1 GiB output / 100× ratio defaults) before the tar walker ever sees a decompressed byte. The reader exposes `toBuffer()` / `asTar(opts)` / `asZip(opts)` so operators can hand the decompressed bytes directly to a downstream archive reader without a round-trip through disk. `b.archive.tar().toGzip(adapter, opts)` is the write-side convenience for the most common combination. `b.backup.bundleAdapterStorage({ format: "tar.gz" })` adds gzip compression on the wire — bundle sizes drop ~3-5× on text-heavy backups (databases, JSON exports, mail spools); the readback path detects the format from the storage key suffix and composes `b.safeDecompress` automatically. The `sha-to-tag verify` workflow now explicitly fetches `origin/main` before walking the first-parent history, fixing a stale-ref bug that silently failed v0.12.6 through v0.12.8 tag verifications (the publish workflow itself was unaffected; the gate is independent). **Added:** *`b.archive.gz(bytes)` — standalone gzip write builder* — RFC 1952 gzip envelope with the standard archive-builder shape. `toBuffer()` returns the compressed bytes; `toAdapter(adapter)` writes through any writable adapter (fs / object-store / http) that exposes `.write(bytes)` + optional `.close()`; `digest()` returns a SHA3-512 hex hash of the compressed payload for operator integrity logs. `opts.level` accepts 0-9 (zlib default 6). Composes cleanly under `b.archive.tar().toGzip(adapter)` / `b.archive.zip()` for tar.gz / zip.gz convenience. · *`b.archive.read.gz(adapter, opts)` — gunzip reader with `b.safeDecompress` bomb caps* — Every decompression routes through `b.safeDecompress({ algorithm: "gzip", maxOutputBytes, maxRatio })` so a hostile gzip stream fails the bomb gate before any downstream parsing happens. Defaults: `maxDecompressedBytes` = 1 GiB, `maxExpansionRatio` = 100×. The reader exposes three downstream entry points: `toBuffer()` returns the raw decompressed bytes; `asTar(opts)` returns a `b.archive.read.tar` reader over the decompressed payload; `asZip(opts)` returns a `b.archive.read.zip` reader. `fromGzip` is the documented alias the spec uses (operators may reach for either). Refuses non-gzip input upfront via the `0x1f 0x8b` magic check (`archive-gz/bad-magic`). · *`b.archive.tar().toGzip(adapter, opts)` — tar.gz write convenience* — Pipes the tar builder's `toBuffer()` through `b.archive.gz()` and writes the resulting gzip envelope to a writable adapter. Equivalent to `b.archive.gz(t.toBuffer()).toAdapter(adapter)` but lets the operator stay in the tar-builder fluent chain when composing under fs / object-store / http adapters. · *`b.backup.bundleAdapterStorage({ format: "tar.gz" })` — compressed-on-the-wire bundles* — Adds gzip compression to the v0.12.8 tar bundle format. Bundle sizes drop ~3-5× on text-heavy backups (databases, JSON exports, mail spools); binary-heavy backups (compressed databases, encrypted archives) see ~1.0-1.1×. Read paths auto-detect via the `<bundleId>/bundle.tar.gz` storage key suffix and route through `b.safeDecompress` on readback. The v0.12.8 `maxBundleBytes` cap continues to gate against pathological projected-uncompressed sizes; `tar.gz` does not bypass it. · *`b.safeArchive.extract({ format: "tar.gz" })` — explicit tar.gz dispatch* — Operators handed a `.tar.gz` upload pass `format: "tar.gz"` explicitly; the orchestrator composes `b.archive.read.gz` → `.asTar()` and feeds the standard tar bomb-policy + entry-type-policy + guardProfile through. Defer-with-condition: auto-sniff for tar.gz (peek inside the gzip envelope for ustar magic at offset 257 of the decompressed prefix) lands when operator demand surfaces; today operators with `auto` mode on a `.tar.gz` payload get `format-unsupported gzip` with the explicit-format hint in the error message. **Fixed:** *`sha-to-tag verify` workflow fetches `origin/main` before first-parent walk* — The release-tag integrity gate runs on every `v*` tag push and verifies the tag's commit SHA appears on `main`'s first-parent history. `actions/checkout` was being asked for full history of the tag ref alone — `origin/main` wasn't fetched as a side effect, so `git rev-list --first-parent origin/main | grep -qx "$SHA"` walked a stale (or absent) ref and falsely refused. The check now explicitly fetches `origin/main` after checkout so the walk sees the current squash-merge HEAD. Affected releases (v0.12.6 / v0.12.7 / v0.12.8) had publish workflows that completed normally — `sha-to-tag verify` is an independent gate that was silently failing alongside successful publishes; nothing about the published artifacts was wrong. **Security:** *Bomb caps ride at the gz layer, not the tar/zip layer* — The decompression gate is enforced BEFORE the downstream archive reader sees any bytes — a hostile `tar.gz` that would decompress to 10 GiB of zero-filled tar entries fails the 1 GiB `maxDecompressedBytes` default cap during gunzip, never reaching the tar walker. Operators with legitimately large compressed archives pass `maxDecompressedBytes` higher; the framework refuses without an explicit opt-in. RFC 1952 §2.3.1 magic enforcement prevents content-type confusion (gzip-pretending-to-be-something-else inputs). **Detectors:** *`archive-gz-without-safedecompress` — direct `node:zlib` gunzip in `lib/` must compose `b.safeDecompress`* — Mirrors the v0.11.5 must-compose pattern: any `lib/` call to `zlib.gunzipSync` / `zlib.createGunzip` / `gunzip` outside `lib/archive-gz.js` (which IS the canonical gunzip site, with `b.safeDecompress` wired in) must carry an `allow:archive-gz-without-safedecompress` marker explaining why the bomb gate is bypassed. The detector locks the contract so v0.13+ work that touches a gzip-handling primitive can't quietly drop the cap.
+
 - v0.12.8 (2026-05-23) — **`b.archive.tar` + `b.archive.read.tar` — POSIX pax tar format end-to-end + `b.guardArchive.tarEntryPolicy` + `b.backup` tar bundle default.** Tar lands as the second format in the archive family. `b.archive.tar()` builds POSIX pax archives (ustar magic + pax extended headers for >100-char names, >8 GiB sizes, nanosecond mtime); `b.archive.read.tar(adapter)` walks the 512-byte block sequence with the same bomb-cap + path-traversal + entry-type defenses that ZIP read shipped at v0.12.7. Tar's natively-streamable shape means `b.archive.adapters.trustedStream(readable)` is a first-class extract path here (no CD-walk required since tar has no central directory; sequential header-by-header is the canonical adversarial-safe path). `b.guardArchive.tarEntryPolicy` ships as the tar-specific entry-shape policy beyond `entryTypePolicy` — handles typeflag 0/5 (regular/directory) by default, refuses 1/2 (hardlink/symlink) unless `allowDangerous` is set with the realpath-on-link-target dual-check, and refuses 3/4/6/7 (char-device/block-device/FIFO/contiguous-file) unconditionally. `b.backup.bundleAdapterStorage({ format: "tar" })` becomes the default for new bundles — directory-tree format stays available via `format: "directory"` for back-compat with v0.12.7 bundles. `b.backup.migrate(from, to)` one-shot helper converts v0.12.7 directory bundles to v0.12.8 tar bundles transparently. `b.safeArchive.extract({ source, destination, format: "auto" })` now sniffs ustar magic at offset 257 inside the first 512-byte block and dispatches to the tar reader automatically. CVE coverage extends to the tar class: CVE-2026-23745 / 2026-24842 (node-tar symlink+hardlink path resolution), CVE-2025-4517 PATH_MAX TOCTOU (the v0.12.7 dual-check carries through), CVE-2025-11001/11002 (symlink TOCTOU on extract), CVE-2024-12905 / 2025-48387 (tar-fs traversal), CVE-2025-4138/4330 (Python tarfile data filter bypass). **Added:** *`b.archive.tar()` — POSIX pax write builder* — Mirrors `b.archive.zip()`'s contract: `addFile(name, content, opts?)` + `addDirectory(name, opts?)` + `toBuffer()` + `toStream(writable)` + `toAdapter(adapter)` + `digest()`. Emits ustar-magic 512-byte header blocks with the standard 11-field prefix (name / mode / uid / gid / size / mtime / chksum / typeflag / linkname / magic / version / uname / gname / devmajor / devminor / prefix). Names >100 chars + sizes >8 GiB + mtime with nanosecond precision get a pax extended header (typeflag=x) preceding the entry; the extended header records (per POSIX.1-2001 §4.18) carry the `path` / `size` / `mtime` / `atime` / `ctime` fields that overflow ustar's fixed widths. Determinism opts: `{ fixedMtime: 0, ignoreOrder: false }` for reproducible builds (matches the ZIP write side). · *`b.archive.read.tar(adapter, opts)` — sequential + random-access tar reader* — Walks 512-byte header blocks in order. `inspect()` enumerates entries without decompressing; `extract({ destination })` decompresses entry-by-entry with the same bomb-cap + path-traversal + entry-type defenses as ZIP read. Trusted-stream adapters are first-class here — tar has no central directory, so sequential header-by-header walk IS the canonical adversarial-safe path (`b.archive.adapters.trustedStream(readable)` and `b.archive.adapters.fs/buffer/objectStore/http` all flow through the same reader). Per-entry path safety routes through `b.guardFilename.verifyExtractionPath` (the v0.12.7 dual-check). Refuses to overwrite pre-existing destination files (carries the v0.12.7 atomic-rollback contract). · *`b.guardArchive.tarEntryPolicy(opts)` — tar-specific entry-type policy* — Defaults: typeflag 0 (regular file) + 5 (directory) extract; typeflag 1 (hardlink) + 2 (symlink) refused unless `allowDangerous: { symlinks: true, hardlinks: true }` is set; typeflag 3 (char-device) + 4 (block-device) + 6 (FIFO) + 7 (contiguous-file) refused unconditionally. When `allowDangerous` is set, link target is routed through `b.guardFilename.verifyExtractionPath` against the extraction root — the realpath-on-link-target check defends the CVE-2026-23745 / 24842 node-tar class where the safety check and creation logic diverged on path resolution. Pax extended-header (x) + global-header (g) entries consumed by the reader (merged into the following entry's metadata); operators never see them as standalone entries. · *`b.backup.bundleAdapterStorage({ format: "tar" })` — tar bundle becomes default* — New bundles ship as a single tar archive instead of a directory tree. Restore via `b.archive.read.tar` (with the operator-supplied adapter routing the bytes). `format: "directory"` opts back into the v0.12.7 layout for operators with existing bundles. `format: "tar"` is the new default; `b.backup.diskStorage` stays back-compat at the legacy directory-tree format. · *`b.backup.migrate(opts)` — directory → tar bundle migration* — One-shot helper that walks an operator's directory-tree-format bundle (v0.12.7 layout) and writes the same content as a tar-format bundle via the v0.12.8 bundleAdapterStorage. Idempotent: re-running on an already-migrated bundle is a no-op. Source bundle stays in place until the migrate succeeds; operators with explicit transition windows pass `{ deleteSourceOnSuccess: true }` to opt into the inline replace. · *`b.safeArchive.extract({ format: "auto" })` recognizes tar* — Format auto-sniff now dispatches `ustar` magic at offset 257 inside the first 512-byte header block to the tar reader. ZIP magic + tar magic + GZIP magic (v0.12.9) live in the same sniff path; operators with mixed-format pipelines pass `format: "auto"` once + the orchestrator picks the right reader. **Security:** *Symlink + hardlink path resolution (CVE-2026-23745 / CVE-2026-24842 node-tar class)* — node-tar < 7.5.7 / ≤ 7.5.2 shipped a divergence between its hardlink safety check (which used one path resolution) and its hardlink creation logic (which used another). When `allowDangerous: { hardlinks: true }` is set, blamejs routes the link target through `b.guardFilename.verifyExtractionPath` — the SAME primitive that the eventual `link()` call resolves against — so check + create agree by construction. Symlink targets same shape. · *Path traversal (CVE-2024-12905 / CVE-2025-48387 tar-fs + CVE-2025-4138 / 4330 Python tarfile data filter bypass)* — Every entry name passes through `b.guardFilename.verifyExtractionPath` — the v0.12.7 dual-check that refuses pre-resolve names > PATH_MAX (4096 bytes) AND verifies the string-normalize + `fs.realpath` resolutions agree on the same final path. Defends the CVE-2025-4517 / 4138 / 4330 class where the operator's path resolution and the kernel's diverge silently past PATH_MAX. · *Symlink TOCTOU on extract (CVE-2025-11001 / CVE-2025-11002 7-Zip class)* — When `allowDangerous: { symlinks: true }` opts symlinks in, the reader resolves the link target via `verifyExtractionPath` against the extraction root BEFORE calling `fs.symlink` — so the resolved target is inside the trust boundary by construction. The v0.12.7 atomic-rollback contract carries through: any single entry failure aborts the whole extract + cleans up only newly-created files (pre-existing destination files refused at the pre-write check). **Detectors:** *`tar-extract-allow-dangerous-without-link-target-check`* — Flags any `b.archive.read.tar(adapter).extract({ allowDangerous: ... })` call site in `lib/` that doesn't route the link target through `b.guardFilename.verifyExtractionPath` against the extraction root. Forces the dual-check discipline at every allow-dangerous opt-in — operators with hardlink / symlink extract needs see the realpath check at the call site. · *`tar-entry-typeflag-without-policy`* — Flags `lib/archive-tar.js` extract code paths that switch on typeflag without composing `b.guardArchive.tarEntryPolicy` for the type-allowlist decision. Locks the shape: every typeflag dispatch goes through the policy, never inline. · *`backup-migrate-without-source-preserve`* — Flags `b.backup.migrate(opts)` call sites that pass `deleteSourceOnSuccess: true` without an operator-stated justification comment. Default is preserve-source; deletes need an explicit reason. **References:** [POSIX.1-2001 pax extended format (IEEE 1003.1)](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html) · [CVE-2026-23745 — node-tar symlink+hardlink path resolution](https://www.sentinelone.com/vulnerability-database/cve-2026-23745/) · [CVE-2026-24842 — node-tar hardlink path resolution](https://github.com/advisories/GHSA-34x7-hfp2-rc4v) · [CVE-2025-4517 — Python tarfile PATH_MAX bypass (CVSS 9.4)](https://nvd.nist.gov/vuln/detail/CVE-2025-4517) · [CVE-2025-4138 / CVE-2025-4330 — Python tarfile data filter](https://github.com/0xDTC/CVE-2025-4138-4517-POC) · [CVE-2025-11001 / CVE-2025-11002 — 7-Zip symlink TOCTOU on extract](https://www.sentinelone.com/vulnerability-database/cve-2025-11001/) · [CVE-2024-12905 / CVE-2025-48387 — node-tar-fs path traversal](https://vulert.com/vuln-db/debian-11-node-tar-fs-193050)
 
 - v0.12.7 (2026-05-23) — **`b.archive.read` — random-access ZIP reader + adapter substrate + `b.safeArchive.extract` orchestrator.** The framework's ZIP primitive grows a read side. `b.archive.read.zip(adapter, opts)` walks the central directory, validates LFH/CD coherence (defeats the malformed-zip / Zip Slip CD-skew class), bounds decompression with operator-declared bomb caps (per-entry size, total bytes, expansion ratio, entry count), and refuses path-traversal + symlink-shaped entries before any byte hits the destination. The adapter contract (`{ size, range(offset, length) }` for random-access; `{ readable }` for the trusted-stream fallback) unifies how operators feed bytes in — local files, `b.objectStore` buckets, HTTP Range fetches, and in-memory buffers all compose the same reader. `b.safeArchive.extract({ source, destination, ... })` ships as the one-liner orchestrator that combines read + guardArchive + path-safety + bomb caps + extract for the common `untar a hostile archive into a quarantine directory` shape. `b.guardArchive` gains `inspect(adapter)` (entry-list enumeration that doesn't decompress), `zipBombPolicy(...)` and `entryTypePolicy(...)` policy-object builders so operators can declare their cap set once + reuse it. `b.guardFilename.verifyExtractionPath(name, root, opts?)` adds the dual-check (string-normalize + `fs.realpath`-agreement) that defends the CVE-2025-4517 PATH_MAX TOCTOU class — refuses paths > 4096 bytes BEFORE the kernel's realpath truncation hits, then verifies the string and fs resolution agree on the same final path. `b.backup` gains `bundleAdapterStorage(adapter, opts)` — the first non-disk transport backend; substrate for the v0.12.8 tar bundle format + v0.12.11 objectStoreStorage. Closes the no-MVP gap from v0.5.15 where `b.archive` shipped write-only and the operator-facing JSDoc explicitly punted reading + extraction to yauzl / `unzip`. **Added:** *`b.archive.read.zip(adapter, opts)` — random-access ZIP reader* — Walks the end-of-central-directory record, validates every CD entry against its LFH (offset / size / CRC / method / name agreement), and emits an iterator of `{ name, size, compressedSize, crc, method, mtime, isEncrypted, externalAttrs, extraFields }` entries. `inspect()` returns the entry list without decompressing — operators wire `b.guardArchive` against the inspect output before paying a single decompress cycle. `extract({ destination, ... })` decompresses entry-by-entry via `node:zlib` raw inflate, routes every path through `b.guardFilename.verifyExtractionPath`, and enforces zip-bomb caps as a streaming abort (the partial extract is fs.rm-ed before the error throws). Composes the existing `lib/archive.js` write-side CRC + signature constants — no duplicated wire-format knowledge. · *Adapter contract — `b.archive.adapters.{fs,objectStore,http,buffer,trustedStream}`* — One shape for source bytes: `{ size: <number>, range(offset, length): Promise<Buffer> }` for random-access, or `{ readable: Readable }` for the explicit trust-stream fallback. `fs(path)` opens a file descriptor + range-reads. `objectStore(client, key)` composes the v0.4.23 `b.objectStore` Range-GET path. `http(url, opts)` composes `b.httpClient` with `Range: bytes=N-M` headers + 206 verification. `buffer(buf)` slices a Buffer in-memory. `trustedStream(readable)` accepts a Node Readable for the rare case the operator can vouch for the source. The same contract feeds `b.safeArchive.extract` and `b.backup.bundleAdapterStorage`. · *`b.safeArchive.extract({ source, destination, ... })` — one-liner safe extraction* — Combines `b.archive.read` + `b.guardArchive` inspect + `b.guardFilename.verifyExtractionPath` + bomb caps + post-extract destination-rebase verification. Refuses the entire archive when any single entry trips a policy (atomic — no half-extracted state on the destination). Operators who want fine-grained control reach for the lower-level primitives directly; `b.safeArchive.extract` covers the 90%-case `extract this hostile-shaped archive into a quarantine directory` workflow. Returns `{ entries: [...], destinationRoot, bytesExtracted, auditTrail }` on success. · *`b.guardArchive.inspect(adapter, opts)` + `zipBombPolicy(...)` + `entryTypePolicy(...)`* — `inspect(adapter)` is the bridge between the read primitive and the existing `validateEntries` gate — runs the read primitive's inspect phase, hands the entry list to `validateEntries`, and returns the merged `{ entries, issues, decisions }` so the caller decides whether to proceed. `zipBombPolicy({ maxEntries, maxEntryDecompressedBytes, maxTotalDecompressedBytes, maxExpansionRatio })` and `entryTypePolicy({ symlinks, hardlinks, devices, fifos, sockets })` are policy-object builders so operators declare the cap set once + reuse across call sites. Each policy carries its own `audit.posture` annotation that propagates through `b.agent.postureChain`. · *`b.guardFilename.verifyExtractionPath(name, root, opts?)` — dual-check path safety* — Companion to the existing `b.guardArchive.checkExtractionPath` (string-only check the gate keeps portable). `verifyExtractionPath` couples to `fs.realpath` deliberately: refuses paths whose pre-resolve string already exceeds 4096 bytes (defends the CVE-2025-4517 PATH_MAX TOCTOU class — `os.path.realpath`-style truncation can't reach the kernel before our refuse fires), then verifies the string-normalized result and the `fs.realpath`-resolved result agree on the same final path. Disagreement throws `guard-filename/extraction-path-toctou`. The string-check stays the canonical portable gate; this primitive is the deeper fs-coupled check the framework's read primitive wires in by default. · *`b.backup.bundleAdapterStorage(adapter, opts)` — adapter-driven storage backend* — First non-disk backend for `b.backup`. Walks the bundle directory file-by-file and writes through the v0.12.7 adapter contract — `fs` adapter behaves identically to `diskStorage` (which stays for back-compat), `buffer` adapter emits the bundle into an in-memory representation, custom adapters can route to anything that satisfies the contract. Substrate for the v0.12.8 tar bundle format (which folds the directory tree into a single tar stream) and the v0.12.11 `objectStoreStorage` (which composes `b.archive.adapters.objectStore` for S3 / MinIO / Azure / GCS-backed backups). Backup manifest layout unchanged — restore code keeps working byte-for-byte against bundles produced by either backend. **Security:** *Zip Slip class (CVE-2025-3445 / 11569 / 23084 / 27210 / 11001 / 11002 / 26960 / 4517 / 4138 / 4330 + 2024 jszip / mholt/archiver / Python tarfile / node-tar / 7-zip)* — Every archive-read entry's name passes through `b.guardFilename.verifyExtractionPath` before any decompression. Path-traversal segments (`..`, leading `/` or `\`, drive-letter prefixes, null bytes, overlong UTF-8) are refused; Windows reserved names + NTFS ADS suffixes are refused; the realpath-agreement check defends the CVE-2025-4517 PATH_MAX TOCTOU class. Symlink and hardlink entries are refused unconditionally under the default `entryTypePolicy`; operators with a legitimate need opt into `allowSymlinks: true` / `allowHardlinks: true` and get the entries routed through an additional `b.guardArchive` realpath-on-target check. · *Decompression-bomb class (CVE-2025-0725, OWASP zip-bomb top-cases)* — `b.archive.read.zip.extract` enforces four caps in parallel: `maxEntries` (entry-count), `maxEntryDecompressedBytes` (per-entry size), `maxTotalDecompressedBytes` (aggregate across the archive), and `maxExpansionRatio` (compressed → decompressed ratio cap, default 100:1). Each cap aborts the extract as soon as the bound is exceeded; the destination directory is `fs.rm`-ed before the error throws so a partial extract never lingers on disk. The `b.safeDecompress` primitive (v0.11.5) is the underlying inflate gate — same defense surface, same audit-trail. · *LFH/CD skew + malformed-ZIP DoS* — The CD walk verifies every entry's local-file-header against the central-directory record (offset / size / CRC / method / name agreement). Mismatches throw `archive/cd-skew` before any byte decompresses. Defends the malformed-zip class where a hostile producer points CD entries at LFH locations that don't match the CD claim — the prior write-only path had no exposure to this class; the new read path closes it. **Detectors:** *`archive-read-without-bomb-caps`* — Flags `b.archive.read.zip(adapter)` call sites in `lib/` that don't pass an explicit `bombPolicy` or `maxTotalDecompressedBytes`. Forces the cap-declaration discipline at call sites — operators see the bomb-cap surface every time they reach for the read primitive. · *`archive-extract-without-guard`* — Flags `b.archive.read.zip(...).extract({ destination, ... })` call sites that don't compose `b.safeArchive.extract` (the orchestrator) AND don't pass an explicit `b.guardArchive.inspect` precheck. Per-file lib/ surface forces operators to either use the orchestrator OR explicitly opt into per-step composition with a written justification. · *`archive-adapter-without-error-path`* — Flags adapter implementations (any export shape matching `{ size, range }` / `{ readable }`) that don't propagate AbortSignal or refuse to throw on partial-read truncation. Forces the cancellation-discipline so a slow / hostile source can't block extraction indefinitely. · *`safe-archive-extract-bypass`* — Flags any composition in `lib/` that builds the safeArchive pipeline (`read.zip(...).extract({ destination, ... })` + bomb caps + guard) inline instead of calling `b.safeArchive.extract`. The orchestrator owns the audit-emission shape; bypassing it means audit gaps. **References:** [APPNOTE.TXT (PKWARE ZIP File Format Specification)](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) · [CVE-2025-3445 — mholt/archiver Zip Slip](https://github.com/advisories/GHSA-7vpp-9cxj-q8gv) · [CVE-2025-4517 — Python tarfile PATH_MAX bypass (CVSS 9.4)](https://nvd.nist.gov/vuln/detail/CVE-2025-4517) · [CVE-2025-11001 / CVE-2025-11002 — 7-Zip directory-traversal RCE](https://www.sentinelone.com/vulnerability-database/cve-2025-11001/) · [CVE-2025-11569 — cross-zip directory traversal](https://security.snyk.io/vuln/SNYK-JS-CROSSZIP-6105396) · [CVE-2026-23745 / CVE-2026-24842 — node-tar symlink + hardlink bypass](https://github.com/advisories/GHSA-34x7-hfp2-rc4v) · [OWASP Zip Slip + zip-bomb reference](https://snyk.io/research/zip-slip-vulnerability) · [USENIX WOOT'19 — A better zip bomb (Fifield)](https://www.usenix.org/conference/woot19/presentation/fifield)

package/lib/archive-gz.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * archive-gz — gzip composition primitives. Sibling of lib/archive.js
+ * (ZIP write), lib/archive-read.js (ZIP read), lib/archive-tar.js (tar
+ * write), and lib/archive-tar-read.js (tar read). The @module block
+ * lives on lib/archive.js; this file declares only @primitive entries
+ * under the b.archive namespace (`b.archive.gz` write, `b.archive.read.gz`
+ * read). Bomb defenses ride with the read path: every read.gz call
+ * composes b.safeDecompress with the framework's default caps (1 GiB
+ * output / 100× ratio).
+ */
+
+var zlib = require("node:zlib");
+var nodeCrypto = require("node:crypto");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var safeBuffer = require("./safe-buffer");
+var { defineClass } = require("./framework-error");
+
+var ArchiveGzError = defineClass("ArchiveGzError", { alwaysPermanent: true });
+
+var safeDecompress = lazyRequire(function () { return require("./safe-decompress"); });
+var archiveAdapters = lazyRequire(function () { return require("./archive-adapters"); });
+var archiveRead = lazyRequire(function () { return require("./archive-read"); });
+var archiveTarRead = lazyRequire(function () { return require("./archive-tar-read"); });
+
+// gzip magic — RFC 1952 §2.2 ("ID1=0x1f, ID2=0x8b").
+var GZIP_MAGIC_0 = 0x1f;                                                              // allow:raw-byte-literal — RFC 1952 §2.2 ID1
+var GZIP_MAGIC_1 = 0x8b;                                                              // allow:raw-byte-literal — RFC 1952 §2.2 ID2
+
+var DEFAULT_MAX_OUTPUT_BYTES = C.BYTES.gib(1);
+var DEFAULT_MAX_RATIO = 100;
+
+function _isGzipMagic(buf) {
+  return buf.length >= 2 && buf[0] === GZIP_MAGIC_0 && buf[1] === GZIP_MAGIC_1;
+}
+
+/**
+ * @primitive b.archive.gz
+ * @signature b.archive.gz(bytes, opts?)
+ * @since     0.12.9
+ * @status    stable
+ * @related   b.archive.read.gz, b.safeDecompress
+ *
+ * Wrap a buffer in a gzip envelope. Returns a builder with the same
+ * write surface as the other `b.archive` builders — `toBuffer()` /
+ * `toAdapter(adapter)` / `digest()` — so gzip slots into the same
+ * downstream sinks (object-store + filesystem + http adapters).
+ *
+ * Composes `b.archive.tar().toGzip(adapter)` / `b.archive.zip().
+ * toGzip(adapter)` indirectly: those convenience methods call this
+ * primitive after materializing their archive bytes.
+ *
+ * @opts
+ *   level:  number,    // 0-9, default 6 (zlib default).
+ *
+ * @example
+ *   var compressed = b.archive.gz(Buffer.from("hello world")).toBuffer();
+ *   // → 31-byte gzip stream
+ */
+function gz(bytes, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+    throw new ArchiveGzError("archive-gz/bad-input",
+      "gz: input must be a Buffer or Uint8Array");
+  }
+  var input = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  var level = opts.level;
+  if (level !== undefined &&
+      (typeof level !== "number" || level < 0 || level > 9)) {
+    throw new ArchiveGzError("archive-gz/bad-arg",
+      "gz: opts.level must be a number 0-9; got " + JSON.stringify(level));
+  }
+  var compressed = null;
+  function _materialize() {
+    if (compressed !== null) return compressed;
+    var zopts = {};
+    if (typeof level === "number") zopts.level = level;
+    compressed = zlib.gzipSync(input, zopts);
+    return compressed;
+  }
+  return {
+    toBuffer: function () { return _materialize(); },
+    toAdapter: async function (adapter) {
+      if (!adapter || typeof adapter.write !== "function") {
+        throw new ArchiveGzError("archive-gz/bad-adapter",
+          "gz.toAdapter: adapter must be writable (no .write method)");
+      }
+      var buf = _materialize();
+      await adapter.write(buf);
+      if (typeof adapter.close === "function") await adapter.close();
+    },
+    digest: function () {
+      return nodeCrypto.createHash("sha3-512")
+        .update(_materialize())
+        .digest("hex");
+    },
+    get compressedBytes() { return _materialize().length; },
+  };
+}
+
+/**
+ * @primitive b.archive.read.gz
+ * @signature b.archive.read.gz(adapter, opts)
+ * @since     0.12.9
+ * @status    stable
+ * @related   b.archive.gz, b.safeDecompress, b.archive.read.tar, b.archive.read.zip
+ *
+ * Read a gzip stream from an adapter, surface it as either raw bytes
+ * (`toBuffer()`) or as a hand-off to a downstream archive reader
+ * (`asTar()` / `asZip()`). Every decompression composes
+ * `b.safeDecompress` with framework-default caps — `maxOutputBytes`
+ * (1 GiB) and `maxExpansionRatio` (100×) — so a hostile `tar.gz`
+ * fails the gz gate before any tar parsing happens.
+ *
+ * @opts
+ *   maxDecompressedBytes:  number,   // default 1 GiB
+ *   maxExpansionRatio:     number,   // default 100×
+ *   audit:                 object,
+ *
+ * @example
+ *   var reader = b.archive.read.gz(b.archive.adapters.fs("./bundle.tar.gz"));
+ *   var tarReader = reader.asTar();
+ *   var result = await tarReader.extract({ destination: "./out" });
+ */
+function readGz(adapter, opts) {
+  opts = opts || {};
+  if (!adapter || typeof adapter !== "object") {
+    throw new ArchiveGzError("archive-gz/bad-adapter",
+      "read.gz: adapter is required");
+  }
+  var maxOutputBytes = opts.maxDecompressedBytes !== undefined
+    ? opts.maxDecompressedBytes
+    : DEFAULT_MAX_OUTPUT_BYTES;
+  var maxRatio = opts.maxExpansionRatio !== undefined
+    ? opts.maxExpansionRatio
+    : DEFAULT_MAX_RATIO;
+  var decompressed = null;
+
+  async function _collect() {
+    if (adapter.kind === "random-access") {
+      var size = adapter.size;
+      if (size == null && typeof adapter.resolveSize === "function") {
+        size = await adapter.resolveSize();
+      }
+      if (typeof size !== "number" || size === 0) {
+        throw new ArchiveGzError("archive-gz/empty-input",
+          "read.gz: adapter reports empty payload");
+      }
+      return adapter.range(0, size);
+    }
+    if (adapter.kind === "trusted-sequential") {
+      var collector = safeBuffer.boundedChunkCollector({
+        maxBytes:   maxOutputBytes,
+        errorClass: ArchiveGzError,
+        sizeCode:   "archive-gz/trusted-stream-too-large",
+      });
+      for await (var chunk of adapter.readable) collector.push(chunk);
+      return collector.result();
+    }
+    throw new ArchiveGzError("archive-gz/bad-adapter",
+      "read.gz: adapter kind " + JSON.stringify(adapter.kind) + " not supported");
+  }
+
+  async function _materialize() {
+    if (decompressed !== null) return decompressed;
+    var compressed = await _collect();
+    if (!_isGzipMagic(compressed)) {
+      throw new ArchiveGzError("archive-gz/bad-magic",
+        "read.gz: input does not start with gzip magic 0x1f 0x8b");
+    }
+    decompressed = safeDecompress().safeDecompress(compressed, {
+      algorithm:          "gzip",
+      maxOutputBytes:     maxOutputBytes,
+      maxCompressedBytes: compressed.length,
+      maxRatio:           maxRatio,
+      audit:              opts.audit,
+    });
+    return decompressed;
+  }
+
+  return {
+    toBuffer: async function () { return _materialize(); },
+    asTar: function (tarOpts) {
+      tarOpts = tarOpts || {};
+      return {
+        inspect: async function () {
+          var bytes = await _materialize();
+          var reader = archiveTarRead().tar(
+            archiveAdapters().buffer(bytes), tarOpts);
+          return reader.inspect();
+        },
+        extract: async function (extractOpts) {
+          var bytes = await _materialize();
+          var reader = archiveTarRead().tar(
+            archiveAdapters().buffer(bytes), tarOpts);
+          return reader.extract(extractOpts);
+        },
+      };
+    },
+    asZip: function (zipOpts) {
+      zipOpts = zipOpts || {};
+      return {
+        inspect: async function () {
+          var bytes = await _materialize();
+          var reader = archiveRead().zip(
+            archiveAdapters().buffer(bytes), zipOpts);
+          return reader.inspect();
+        },
+        extract: async function (extractOpts) {
+          var bytes = await _materialize();
+          var reader = archiveRead().zip(
+            archiveAdapters().buffer(bytes), zipOpts);
+          return reader.extract(extractOpts);
+        },
+      };
+    },
+  };
+}
+
+module.exports = {
+  gz:                gz,
+  read:              { gz: readGz },
+  ArchiveGzError:    ArchiveGzError,
+  // Exposed for sibling modules
+  _isGzipMagic:      _isGzipMagic,
+  GZIP_MAGIC_0:      GZIP_MAGIC_0,
+  GZIP_MAGIC_1:      GZIP_MAGIC_1,
+};

package/lib/archive-tar.js

@@ -70,12 +70,18 @@
 var nodeStream = require("node:stream");
 var streamPromises = require("node:stream/promises");
 var C = require("./constants");
+var lazyRequire = require("./lazy-require");
 var { defineClass } = require("./framework-error");
 
 var TarError = defineClass("TarError", { alwaysPermanent: true });
 
 void streamPromises; void nodeStream;
 
+// Lazy because archive-gz lazy-imports archive-tar-read (sibling read
+// module) — a top-of-file `require("./archive-gz")` would create a
+// load-order cycle that depends on file-walk order.
+var archiveGz = lazyRequire(function () { return require("./archive-gz"); });
+
 // ---- Wire-format constants -----------------------------------------------
 
 var BLOCK_SIZE = C.BYTES.bytes(512);     // tar block size (POSIX)
@@ -498,12 +504,20 @@ function tarBuilder() {
     return nodeCrypto.createHash("sha3-512").update(toBuffer()).digest("hex");
   }
 
+  async function toGzip(adapter, gzOpts) {
+    // Convenience composition: materialize the tar then wrap through
+    // b.archive.gz. archive-gz is lazy-required at module top to break
+    // the load-order cycle with archive-tar-read.
+    return archiveGz().gz(toBuffer(), gzOpts || {}).toAdapter(adapter);
+  }
+
   return {
     addFile:      addFile,
     addDirectory: addDirectory,
     toBuffer:     toBuffer,
     toStream:     toStream,
     toAdapter:    toAdapter,
+    toGzip:       toGzip,
     digest:       digest,
     get entryCount() { return entries.length; },
   };

package/lib/archive.js

@@ -545,15 +545,20 @@ function zip() {
 var archiveRead = require("./archive-read");
 var archiveTar = require("./archive-tar");
 var archiveTarRead = require("./archive-tar-read");
+var archiveGz = require("./archive-gz");
 
 module.exports = {
-  zip:           zip,
-  tar:           archiveTar.tar,
-  ArchiveError:  ArchiveError,
-  TarError:      archiveTar.TarError,
+  zip:             zip,
+  tar:             archiveTar.tar,
+  gz:              archiveGz.gz,
+  ArchiveError:    ArchiveError,
+  TarError:        archiveTar.TarError,
+  ArchiveGzError:  archiveGz.ArchiveGzError,
   read: {
     zip:                 archiveRead.zip,
     tar:                 archiveTarRead.tar,
+    gz:                  archiveGz.read.gz,
+    fromGzip:            archiveGz.read.gz,
     ArchiveReadError:    archiveRead.ArchiveReadError,
     DEFAULT_BOMB_POLICY: archiveRead.DEFAULT_BOMB_POLICY,
     DEFAULT_ENTRY_TYPE_POLICY: archiveRead.DEFAULT_ENTRY_TYPE_POLICY,

package/lib/backup/index.js

@@ -1064,9 +1064,9 @@ function bundleAdapterStorage(opts) {
   // operator-supplied so a single backup engine can transition over
   // time + b.backup.migrate() handles the directory → tar conversion.
   var format = opts.format || "tar";
-  if (format !== "tar" && format !== "directory") {
+  if (format !== "tar" && format !== "tar.gz" && format !== "directory") {
     throw new BackupError("backup/bad-format",
-      "bundleAdapterStorage: format must be \"tar\" (default) or \"directory\" (legacy v0.12.7)");
+      "bundleAdapterStorage: format must be \"tar\" (default) | \"tar.gz\" (v0.12.9 compressed) | \"directory\" (legacy v0.12.7)");
   }
   // Codex P2 on v0.12.8 PR #159 — tar mode builds the whole archive
   // in memory before adapter.writeFile because the v0.12.8 adapter
@@ -1111,13 +1111,16 @@ function bundleAdapterStorage(opts) {
   }
 
   // Tar-format bundle storage stores the whole bundle as a single
-  // key under `<bundleId>/bundle.tar`. The marker is named that way
-  // so listBundles + hasBundle can locate either format by key
+  // key under `<bundleId>/bundle.tar` (or `<bundleId>/bundle.tar.gz`
+  // for the v0.12.9 compressed variant). The marker is named that
+  // way so listBundles + hasBundle can locate either format by key
   // prefix walk.
   var TAR_KEY_SUFFIX = "/bundle.tar";
+  var TAR_GZ_KEY_SUFFIX = "/bundle.tar.gz";
 
   function _hasBundleKey(bundleId, format) {
     if (format === "tar") return adapter.hasKey(bundleId + TAR_KEY_SUFFIX);
+    if (format === "tar.gz") return adapter.hasKey(bundleId + TAR_GZ_KEY_SUFFIX);
     return adapter.hasKey(bundleId + "/manifest.json");
   }
 
@@ -1134,9 +1137,12 @@ function bundleAdapterStorage(opts) {
         throw new BackupError("backup/bundle-exists",
           "writeBundle: bundle '" + bundleId + "' already exists in storage");
       }
-      if (format === "tar") {
+      if (format === "tar" || format === "tar.gz") {
         // Pack the source-directory tree into a single tar archive +
-        // store under one key. Composes b.archive.tar.
+        // store under one key. Composes b.archive.tar (+ b.archive.gz
+        // for the tar.gz variant which adds gzip compression on the
+        // wire). Bundle sizes drop ~3-5× on text-heavy backups
+        // (databases, JSON exports, mail spools) under tar.gz.
         //
         // Codex P2 on v0.12.8 PR #159 — tar bytes are materialized in
         // memory because the v0.12.8 adapter contract is bytes-in
@@ -1165,8 +1171,11 @@ function bundleAdapterStorage(opts) {
           var bytes = nodeFs.readFileSync(nodePath.join(sourceDir, rel));
           t.addFile(rel, bytes);
         }
-        var tarBytes = t.toBuffer();
-        await adapter.writeFile(bundleId + TAR_KEY_SUFFIX, tarBytes);
+        var keySuffix = format === "tar.gz" ? TAR_GZ_KEY_SUFFIX : TAR_KEY_SUFFIX;
+        var payloadBytes = format === "tar.gz"
+          ? archiveLazy().gz(t.toBuffer()).toBuffer()
+          : t.toBuffer();
+        await adapter.writeFile(bundleId + keySuffix, payloadBytes);
         return;
       }
       // Directory format (v0.12.7 layout).
@@ -1184,14 +1193,36 @@ function bundleAdapterStorage(opts) {
           "readBundle: destDir already exists: " + destDir);
       }
       // Detect which format this bundle is in — operators with mixed
-      // pre-v0.12.8 + post-v0.12.8 bundles can read either back.
+      // pre-v0.12.8 + post-v0.12.8 (+ v0.12.9 tar.gz) bundles can read
+      // every flavor back.
       var hasTar = await adapter.hasKey(bundleId + TAR_KEY_SUFFIX);
+      var hasTarGz = await adapter.hasKey(bundleId + TAR_GZ_KEY_SUFFIX);
       var hasManifest = await adapter.hasKey(bundleId + "/manifest.json");
-      if (!hasTar && !hasManifest) {
+      if (!hasTar && !hasTarGz && !hasManifest) {
         throw new BackupError("backup/bundle-not-found",
           "readBundle: '" + bundleId + "' not in storage");
       }
       atomicFile.ensureDir(destDir);
+      if (hasTarGz) {
+        // Codex P1/P2 on v0.12.9 PR #160 — propagate maxBundleBytes
+        // to the gz restore path + disable the expansion-ratio cap.
+        // archive.read.gz defaults (1 GiB output / 100× ratio) are
+        // bomb-defense settings appropriate for adversarial input;
+        // this is a SELF-AUTHORED bundle the writeBundle path
+        // produced under maxBundleBytes — the restore contract is
+        // "decompress to at most what was permitted on write." A
+        // zero-filled DB file can easily hit >100× compression
+        // ratio; without these opts the same primitive writes
+        // bundles it can't read back.
+        var gzBytes = await adapter.readFile(bundleId + TAR_GZ_KEY_SUFFIX);
+        var gzReader = archiveLazy().read.gz(archiveAdaptersLazy().buffer(gzBytes), {
+          maxDecompressedBytes: maxBundleBytes,
+          maxExpansionRatio:    0,
+        });
+        var tarReader = gzReader.asTar();
+        await tarReader.extract({ destination: destDir });
+        return;
+      }
       if (hasTar) {
         var tarBytes = await adapter.readFile(bundleId + TAR_KEY_SUFFIX);
         var reader = archiveLazy().read.tar(archiveAdaptersLazy().buffer(tarBytes));
@@ -1217,7 +1248,13 @@ function bundleAdapterStorage(opts) {
         }
         atomicFile.ensureDir(nodePath.dirname(destPath));
         var bytes = await adapter.readFile(key);
-        nodeFs.writeFileSync(destPath, bytes);
+        // Exclusive-create (wx) carries the v0.12.7 atomic-rollback
+        // contract: readBundle refuses to overwrite pre-existing
+        // files at destPath. Combined with the upfront destDir check
+        // above (refuses if destDir already exists), the only way
+        // wx fires here is a symlink swap between ensureDir and write
+        // — which the framework refuses rather than following.
+        nodeFs.writeFileSync(destPath, bytes, { flag: "wx", mode: 0o600 });
       }
     },
     async listBundles() {
@@ -1264,12 +1301,15 @@ function bundleAdapterStorage(opts) {
     async hasBundle(bundleId) {
       _ensureBundleId(bundleId);
       // Format-aware: check the storage layout's marker key. Tar
-      // bundles store under <bid>/bundle.tar; directory bundles store
-      // under <bid>/manifest.json. Operators with a mixed bundle set
-      // (some tar, some directory) get true for either.
+      // bundles store under <bid>/bundle.tar; tar.gz bundles store
+      // under <bid>/bundle.tar.gz; directory bundles store under
+      // <bid>/manifest.json. Operators with a mixed bundle set
+      // (some tar, some tar.gz, some directory) get true for any.
       var tarKey = bundleId + TAR_KEY_SUFFIX;
+      var tarGzKey = bundleId + TAR_GZ_KEY_SUFFIX;
       var dirKey = bundleId + "/manifest.json";
       if (await adapter.hasKey(tarKey)) return true;
+      if (await adapter.hasKey(tarGzKey)) return true;
       if (await adapter.hasKey(dirKey)) return true;
       return false;
     },

package/lib/safe-archive.js

@@ -46,6 +46,7 @@ var SafeArchiveError = defineClass("SafeArchiveError", { alwaysPermanent: true }
 var archiveRead = lazyRequire(function () { return require("./archive-read"); });
 var archiveAdapters = lazyRequire(function () { return require("./archive-adapters"); });
 var archiveTarRead = lazyRequire(function () { return require("./archive-tar-read"); });
+var archiveGz = lazyRequire(function () { return require("./archive-gz"); });
 
 // ---- Format sniffing ----------------------------------------------------
 
@@ -194,10 +195,23 @@ async function extract(opts) {
         guardProfile:    opts.guardProfile,
         audit:           opts.audit,
       });
+    } else if (format === "tar.gz") {
+      // gzip envelope around tar — safeDecompress caps run on the gz
+      // layer before the tar walker ever sees a decompressed byte.
+      reader = archiveGz().read.gz(source, {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxExpansionRatio:    opts.maxExpansionRatio,
+        audit:                opts.audit,
+      }).asTar({
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "extract: format=" + JSON.stringify(format) + " — v0.12.8 ships ZIP + tar " +
-        "(gz lands v0.12.9, encryptPacked-wrap lands v0.12.10)");
+        "extract: format=" + JSON.stringify(format) + " — v0.12.9 ships ZIP + tar + tar.gz " +
+        "(encryptPacked-wrap lands v0.12.10)");
     }
     var result = await reader.extract({
       destination:    opts.destination,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:4e14c3b7-7b58-4756-ba67-d2bcef61b25b",
+  "serialNumber": "urn:uuid:f5a3cd7a-802d-4f55-ba59-958f474f38a0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T16:36:21.469Z",
+    "timestamp": "2026-05-23T17:58:07.192Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.8",
+      "bom-ref": "@blamejs/core@0.12.9",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.8",
+      "version": "0.12.9",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.8",
+      "purl": "pkg:npm/%40blamejs/core@0.12.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.8",
+      "ref": "@blamejs/core@0.12.9",
       "dependsOn": []
     }
   ]