@blamejs/core 0.12.8 → 0.12.10

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.10 (2026-05-23) — **`b.archive.wrap` + `b.archive.unwrap` — recipient-encrypted archive envelopes (Flavor 1) + `b.backup` `cryptoStrategy: "recipient"` + HIPAA/PCI-DSS posture refusal.** Flavor 1 lands as the whole-archive recipient-wrap substrate. `b.archive.wrap(bytes, { recipient })` produces a sealed envelope under the framework's hybrid PQC seal (ML-KEM-1024 + P-384 ECDH + SHAKE256 + XChaCha20-Poly1305) prefixed with a 6-byte `BAWRP` archive-wrap header so format sniffers can identify wrap envelopes without trial decryption. `b.archive.unwrap(sealed, { recipient })` is the inverse with magic-check upfront so non-envelope inputs throw `archive-wrap/bad-magic` rather than a crypto-level error. Recipient strategies: static keypair (`{ publicKey, ecPublicKey }`) and peer-cert (`{ peerCertDer, peerKemPubkey }`); the tenant strategy lands in v0.12.11 alongside the backup-crypto refactor + per-tenant key resolution. `b.backup.bundleAdapterStorage({ cryptoStrategy: "recipient", recipient })` composes the wrap/unwrap layer transparently: the bytes hitting the adapter's `writeFile` are a `BAWRP`-prefixed envelope, never the raw tar / tar.gz / directory bundle. HIPAA + PCI-DSS postures refuse `cryptoStrategy: "none"` upfront with `backup/posture-requires-encryption` — the storage adapter cannot itself satisfy the encryption-at-rest requirement; the recipient envelope is the framework-side gate. Flavor 2 (per-entry ZIP wrap with the 0xBADC extra-field marker) and the backup-crypto refactor into `lib/_crypto-base.js` ship in v0.12.11. **Added:** *`b.archive.wrap(bytes, { recipient })` — recipient-encrypted archive envelope* — Composes `b.crypto.encrypt` (or `b.crypto.encryptEnvelopeAsCertPeer` for the peer-cert strategy) under the framework's hybrid PQC seal. The output is a Buffer carrying a 6-byte `BAWRP` archive-wrap header (5-byte magic + 1-byte version) followed by the base64-encoded envelope bytes. Recipient strategies: `{ publicKey, ecPublicKey }` for the static-keypair path (ML-KEM-1024 PEM + P-384 ECDH PEM); `{ peerCertDer, peerKemPubkey }` for the peer-cert path (extracts the P-384 half from the cert per `b.crypto.encryptEnvelopeAsCertPeer`). `"tenant"` returns `archive-wrap/tenant-strategy-deferred` upfront — that strategy lands in v0.12.11 with the per-tenant key resolution. · *`b.archive.unwrap(sealed, { recipient })` — inverse with upfront magic check* — Verifies the 6-byte `BAWRP` header before any cryptographic work so non-envelope inputs (raw archives, other-magic envelopes, truncated buffers) fail with `archive-wrap/bad-magic` / `archive-wrap/bad-version` rather than a downstream `crypto/*` error. Routes through `b.crypto.decrypt(envelope, recipient, { raw: true })` so binary archive payloads (gzip, ZIP, tar) round-trip losslessly — `raw: true` is the contract that preserves bytes vs the default utf-8 decoding. · *`b.backup.bundleAdapterStorage({ cryptoStrategy: "recipient", recipient })` — opt-in envelope storage* — `cryptoStrategy: "none"` (default, v0.12.7-9 behaviour) writes plaintext bundle bytes to the adapter — safe for storage layers that are themselves the protective boundary (S3 SSE, disk-encrypted hosts). `cryptoStrategy: "recipient"` requires `opts.recipient` and wraps every `writeBundle` payload through `b.archive.wrap` before `adapter.writeFile`; `readBundle` unwraps after `adapter.readFile`. The wrap layer sits OUTSIDE the gz / tar layers so the bundle on disk is opaque ciphertext under the operator-controlled recipient key. Passphrase strategy is deferred to v0.12.11 alongside the `_crypto-base.js` refactor. · *HIPAA + PCI-DSS posture refuses plaintext bundles* — `bundleAdapterStorage({ posture: "hipaa" })` (or `"pci-dss"`) refuses `cryptoStrategy: "none"` upfront with `backup/posture-requires-encryption` — adapter-storage's plaintext default cannot itself satisfy encryption-at-rest requirements. Operators under these postures pass `cryptoStrategy: "recipient"` + a recipient key. The refusal message includes the posture name + the strategy that fails so audit-trail operators see exactly which gate blocked the call. **Security:** *Wrap envelope is the framework's hybrid PQC seal — ML-KEM-1024 + P-384 ECDH + SHAKE256 + XChaCha20-Poly1305* — Defence-in-depth posture: a CRQC against ML-KEM-1024 alone still has to defeat the classical P-384 ECDH leg; a future ECDH break alone still has to defeat ML-KEM-1024. The 4-byte envelope header (magic + KEM ID + cipher ID + KDF ID) is bound as AEAD AAD so a header-substitution attack fails Poly1305 verification. `b.archive.wrap` prepends a separate 6-byte archive-wrap header BEFORE the base64 envelope so format sniffing can identify wrap output without trial decryption — non-envelope inputs are refused at byte 0-4 (magic check) instead of after fruitless decapsulation work. **Detectors:** *`backup-adapter-storage-without-posture-check` — postures that mandate encryption must propagate to `cryptoStrategy`* — When a primitive that wires `b.backup.bundleAdapterStorage` carries a `posture:` opt drawn from the HIPAA / PCI-DSS / etc. set, the same code path must propagate `cryptoStrategy: "recipient"` (or refuse before reaching writeBundle). The detector matches `bundleAdapterStorage({ ... posture: ... })` invocations in `lib/` and requires a matching `cryptoStrategy` opt; missing it surfaces during the codebase-patterns gate so a future caller can't silently drop the contract. **Migration:** *Flavor 2 — per-entry ZIP recipient wrap with 0xBADC extra-field* — Per-entry encryption inside the carrier ZIP (method=STORE with the encrypted bytes as the stored payload + a 0xBADC user-defined-range extra-field marker carrying the recipient hint). Inspect-without-decrypt is the operator value: entry list + name-safety gating happens BEFORE any key resolution. Lands in v0.12.11 alongside the backup-crypto refactor. · *`lib/_crypto-base.js` refactor — backup-crypto, Flavor 1, Flavor 2 share substrate* — The legacy per-file Argon2id + XChaCha20-Poly1305 path in `lib/backup/crypto.js` gets factored into a private `_crypto-base.js` helper so all three encryption flavors compose the same primitive set. No operator-visible API change; closes the each-feature-rolls-its-own-crypto smell. · *`cryptoStrategy: "passphrase"` + tenant strategy* — Passphrase strategy on `bundleAdapterStorage` (Argon2id-derived key + XChaCha20-Poly1305) and the `"tenant"` recipient string (composes `b.vault.derivedKey({ tenant, purpose: "archive-wrap" })`) both ship in v0.12.11. The v0.12.10 surface is the recipient substrate; v0.12.11 lights up the per-tenant + passphrase strategies that consume it.
+
+- 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-wrap.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * archive-wrap — recipient-based whole-archive encryption substrate
+ * for the b.archive family. Composes b.crypto.encrypt (ML-KEM-1024 +
+ * P-384 ECDH hybrid + SHAKE256 + XChaCha20-Poly1305 envelope) so
+ * archive bytes hitting an adapter can be a sealed envelope rather
+ * than the raw format.
+ *
+ * Operators compose explicitly for v0.12.10:
+ *
+ *   var sealed = b.archive.wrap(t.toBuffer(), { recipient: pubKeys });
+ *   await b.archive.adapters.fs(path).write(sealed);
+ *
+ *   var sealed = await fs.promises.readFile(path);
+ *   var bytes  = b.archive.unwrap(sealed, { recipient: privKeys });
+ *   var reader = b.archive.read.tar(b.archive.adapters.buffer(bytes));
+ *
+ * Builder-fluent composition (`tarBuilder.toAdapter(s3, { wrap: ... })`)
+ * + per-entry ZIP wrap (Flavor 2) land in v0.12.11 alongside the
+ * backup-crypto refactor; this patch ships the recipient substrate
+ * + the b.backup `cryptoStrategy: "recipient"` opt that consumes it.
+ */
+
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+
+var ArchiveWrapError = defineClass("ArchiveWrapError", { alwaysPermanent: true });
+
+var bCrypto = lazyRequire(function () { return require("./crypto"); });
+
+// Envelope magic — 5-byte ASCII prefix the safe-archive sniffer
+// recognises. Distinct from b.crypto.encrypt's base64 envelope so
+// archive-wrap output can carry an unambiguous "this is an archive
+// recipient-wrap envelope" magic before the operator-controlled
+// payload.
+var ARCH_WRAP_MAGIC = "BAWRP";                                                       // allow:raw-byte-literal — 5-byte ASCII archive-wrap envelope magic
+var ARCH_WRAP_VERSION = 0x01;                                                        // allow:raw-byte-literal — version byte
+var ARCH_WRAP_HEADER_BYTES = C.BYTES.bytes(6);                                        // magic(5) + version(1)
+
+/**
+ * @primitive b.archive.wrap
+ * @signature b.archive.wrap(bytes, opts)
+ * @since     0.12.10
+ * @status    stable
+ * @related   b.archive.unwrap, b.crypto.encrypt, b.backup.bundleAdapterStorage
+ *
+ * Wrap archive bytes in a recipient-encrypted envelope. The envelope
+ * is the framework's standard hybrid PQC seal (ML-KEM-1024 + P-384
+ * ECDH hybrid + SHAKE256 KDF + XChaCha20-Poly1305 AEAD) prefixed
+ * with a 6-byte archive-wrap header (`BAWRP` magic + version byte)
+ * so format sniffers can distinguish wrap envelopes from raw
+ * archives without trial decryption.
+ *
+ * Recipient strategies:
+ *   - static key  — `{ recipient: { publicKey, ecPublicKey } }` (ML-KEM-1024
+ *                   pubkey PEM + P-384 ECDH pubkey PEM).
+ *   - peer cert   — `{ recipient: { peerCertDer, peerKemPubkey } }` composes
+ *                   `b.crypto.encryptEnvelopeAsCertPeer` (extracts the
+ *                   P-384 half from the cert).
+ *   - tenant      — `{ recipient: "tenant", tenantId: "alpha" }` resolves
+ *                   the tenant's KEM keypair via `b.vault.derivedKey`
+ *                   (deferred to v0.12.11 alongside the backup
+ *                   `cryptoStrategy: "recipient"` adoption).
+ *
+ * @opts
+ *   recipient:  object | string,   // see strategies above; required
+ *   tenantId:   string,            // required when recipient === "tenant"
+ *
+ * @example
+ *   var pair   = b.crypto.generateEncryptionKeyPair();
+ *   var sealed = b.archive.wrap(tarBytes, { recipient: pair });
+ *   // sealed is a Buffer carrying BAWRP+version+envelope; write to
+ *   // any adapter sink. On read, hand to b.archive.unwrap with the
+ *   // matching privKeys to recover tarBytes.
+ */
+function wrap(bytes, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+    throw new ArchiveWrapError("archive-wrap/bad-input",
+      "wrap: bytes must be a Buffer or Uint8Array");
+  }
+  if (bytes.length === 0) {
+    throw new ArchiveWrapError("archive-wrap/empty-input",
+      "wrap: bytes is empty — nothing to seal");
+  }
+  if (!opts.recipient) {
+    throw new ArchiveWrapError("archive-wrap/no-recipient",
+      "wrap: opts.recipient is required (static key object | \"tenant\" string | peer-cert object)");
+  }
+  var envelope = _encryptForRecipient(bytes, opts);
+  // envelope is a base64 string from b.crypto.encrypt. Buffer it and
+  // prepend the 6-byte archive-wrap header so safeArchive's sniffer
+  // can identify it without attempting decryption.
+  var envelopeBuf = Buffer.from(envelope, "utf-8");
+  var header = Buffer.alloc(ARCH_WRAP_HEADER_BYTES);
+  header.write(ARCH_WRAP_MAGIC, 0, 5, "ascii");
+  header[5] = ARCH_WRAP_VERSION;
+  return Buffer.concat([header, envelopeBuf]);
+}
+
+/**
+ * @primitive b.archive.unwrap
+ * @signature b.archive.unwrap(sealed, opts)
+ * @since     0.12.10
+ * @status    stable
+ * @related   b.archive.wrap, b.crypto.decrypt
+ *
+ * Recover archive bytes from a recipient-encrypted envelope produced
+ * by `b.archive.wrap`. Verifies the 6-byte `BAWRP` header before
+ * attempting decryption so non-envelope inputs (raw archive bytes,
+ * other-magic envelopes) fail with `archive-wrap/bad-magic` rather
+ * than a crypto-level error.
+ *
+ * @opts
+ *   recipient:  object,   // { privateKey, ecPrivateKey } | { certPrivateKey, kemSecret }; required
+ *
+ * @example
+ *   var bytes  = b.archive.unwrap(sealed, { recipient: privPair });
+ *   var reader = b.archive.read.tar(b.archive.adapters.buffer(bytes));
+ */
+function unwrap(sealed, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(sealed) && !(sealed instanceof Uint8Array)) {
+    throw new ArchiveWrapError("archive-wrap/bad-input",
+      "unwrap: sealed must be a Buffer or Uint8Array");
+  }
+  if (sealed.length < ARCH_WRAP_HEADER_BYTES) {
+    throw new ArchiveWrapError("archive-wrap/bad-magic",
+      "unwrap: input shorter than 6-byte archive-wrap header");
+  }
+  var buf = Buffer.isBuffer(sealed) ? sealed : Buffer.from(sealed);
+  var magic = buf.slice(0, 5).toString("ascii");
+  if (magic !== ARCH_WRAP_MAGIC) {
+    throw new ArchiveWrapError("archive-wrap/bad-magic",
+      "unwrap: input does not start with archive-wrap magic " +
+      JSON.stringify(ARCH_WRAP_MAGIC) + "; got " + JSON.stringify(magic));
+  }
+  var version = buf[5];
+  if (version !== ARCH_WRAP_VERSION) {
+    throw new ArchiveWrapError("archive-wrap/bad-version",
+      "unwrap: archive-wrap version " + version + " not supported by this build");
+  }
+  if (!opts.recipient || typeof opts.recipient !== "object") {
+    throw new ArchiveWrapError("archive-wrap/no-recipient",
+      "unwrap: opts.recipient is required ({ privateKey, ecPrivateKey } " +
+      "for the static-key path, { certPrivateKey, kemSecret } for the peer-cert path)");
+  }
+  var envelope = buf.slice(ARCH_WRAP_HEADER_BYTES).toString("utf-8");
+  var plaintext;
+  try {
+    if (opts.recipient.certPrivateKey) {
+      // Cert-peer path: encryptEnvelopeAsCertPeer composed
+      // `encrypt(bytes, { publicKey, ecPublicKey })` where the
+      // ecPublicKey was extracted from the cert. The inverse passes
+      // the operator's kemSecret + certPrivateKey (P-384) through
+      // the same decrypt code path. raw:true preserves binary
+      // archive bytes losslessly.
+      plaintext = bCrypto().decrypt(envelope, {
+        privateKey:    opts.recipient.kemSecret,
+        ecPrivateKey:  opts.recipient.certPrivateKey,
+      }, { raw: true });
+    } else {
+      // raw:true returns the decrypted Buffer (lossless for arbitrary
+      // binary archive payloads — utf-8 string conversion would
+      // corrupt gzip / zip / tar bytes).
+      plaintext = bCrypto().decrypt(envelope, opts.recipient, { raw: true });
+    }
+  } catch (e) {
+    var err = new ArchiveWrapError("archive-wrap/decrypt-failed",
+      "unwrap: envelope decryption refused: " + ((e && e.message) || String(e)));
+    err.cause = e;
+    throw err;
+  }
+  return Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext);
+}
+
+function _encryptForRecipient(bytes, opts) {
+  var r = opts.recipient;
+  if (typeof r === "string") {
+    if (r === "tenant") {
+      // tenant strategy lands in v0.12.11 alongside the backup
+      // cryptoStrategy adoption — refuse cleanly for v0.12.10 so
+      // operators see the deferred-shape contract.
+      throw new ArchiveWrapError("archive-wrap/tenant-strategy-deferred",
+        "wrap: recipient: \"tenant\" lands in v0.12.11 alongside b.backup cryptoStrategy: \"recipient\" + per-tenant key resolution. For v0.12.10, pass an explicit { publicKey, ecPublicKey } recipient");
+    }
+    throw new ArchiveWrapError("archive-wrap/bad-recipient",
+      "wrap: recipient string " + JSON.stringify(r) + " not recognised; \"tenant\" deferred to v0.12.11");
+  }
+  if (r.peerCertDer || r.peerKemPubkey) {
+    if (!r.peerCertDer || !r.peerKemPubkey) {
+      throw new ArchiveWrapError("archive-wrap/bad-recipient",
+        "wrap: peer-cert strategy requires BOTH peerCertDer + peerKemPubkey");
+    }
+    return bCrypto().encryptEnvelopeAsCertPeer(bytes, {
+      peerCertDer:    r.peerCertDer,
+      peerKemPubkey:  r.peerKemPubkey,
+    });
+  }
+  if (r.publicKey) {
+    // Codex P2 on v0.12.10 PR #161 — b.crypto.encrypt falls back to
+    // ML-KEM-only when ecPublicKey is undefined (with a one-shot
+    // audit). For archive-wrap's recipient contract the hybrid leg
+    // (P-384 ECDH defence-in-depth backstop on top of ML-KEM-1024)
+    // is the documented behaviour; refuse upfront so partial
+    // recipient objects can't silently degrade the seal posture.
+    // Operators who genuinely want KEM-only call
+    // b.crypto.encryptMlkem768X25519 directly.
+    if (!r.ecPublicKey) {
+      throw new ArchiveWrapError("archive-wrap/hybrid-required",
+        "wrap: static-key recipient requires BOTH publicKey (ML-KEM-1024 PEM) " +
+        "and ecPublicKey (P-384 ECDH PEM). Partial recipients trip b.crypto.encrypt's " +
+        "ML-KEM-only fallback which silently degrades the hybrid contract this primitive promises.");
+    }
+    return bCrypto().encrypt(bytes, {
+      publicKey:    r.publicKey,
+      ecPublicKey:  r.ecPublicKey,
+    });
+  }
+  throw new ArchiveWrapError("archive-wrap/bad-recipient",
+    "wrap: recipient must be { publicKey, ecPublicKey } | { peerCertDer, peerKemPubkey } | \"tenant\"");
+}
+
+function _isWrapMagic(buf) {
+  return buf.length >= ARCH_WRAP_HEADER_BYTES &&
+    buf.slice(0, 5).toString("ascii") === ARCH_WRAP_MAGIC;
+}
+
+module.exports = {
+  wrap:             wrap,
+  unwrap:           unwrap,
+  ArchiveWrapError: ArchiveWrapError,
+  // Exposed for sibling modules + sniffer
+  _isWrapMagic:     _isWrapMagic,
+  ARCH_WRAP_MAGIC:  ARCH_WRAP_MAGIC,
+};

package/lib/archive.js

@@ -545,15 +545,24 @@ function zip() {
 var archiveRead = require("./archive-read");
 var archiveTar = require("./archive-tar");
 var archiveTarRead = require("./archive-tar-read");
+var archiveGz = require("./archive-gz");
+var archiveWrap = require("./archive-wrap");
 
 module.exports = {
-  zip:           zip,
-  tar:           archiveTar.tar,
-  ArchiveError:  ArchiveError,
-  TarError:      archiveTar.TarError,
+  zip:               zip,
+  tar:               archiveTar.tar,
+  gz:                archiveGz.gz,
+  wrap:              archiveWrap.wrap,
+  unwrap:            archiveWrap.unwrap,
+  ArchiveError:      ArchiveError,
+  TarError:          archiveTar.TarError,
+  ArchiveGzError:    archiveGz.ArchiveGzError,
+  ArchiveWrapError:  archiveWrap.ArchiveWrapError,
   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,61 @@ 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)");
+  }
+  // v0.12.10 — cryptoStrategy gates whether the bundle bytes are
+  // wrapped in a recipient envelope before adapter.writeFile.
+  //   "none"      — plaintext bundle (v0.12.7-9 behaviour). Safe
+  //                 for adapter-encrypted storage (S3 SSE,
+  //                 disk-encrypted hosts) where the storage layer
+  //                 itself is the protective boundary.
+  //   "recipient" — composes b.archive.wrap on write +
+  //                 b.archive.unwrap on read. Operator supplies
+  //                 `recipient: { publicKey, ecPublicKey }` (or
+  //                 a peer-cert recipient); the bundle bytes
+  //                 hitting the adapter are an opaque envelope.
+  //                 HIPAA / PCI-DSS postures (per
+  //                 BACKUP_ENCRYPTION_REQUIRED_POSTURES) REFUSE
+  //                 "none" + require "recipient".
+  var cryptoStrategy = opts.cryptoStrategy || "none";
+  if (cryptoStrategy !== "none" && cryptoStrategy !== "recipient") {
+    throw new BackupError("backup/bad-crypto-strategy",
+      "bundleAdapterStorage: cryptoStrategy must be \"none\" (default — adapter-encrypted storage) " +
+      "or \"recipient\" (v0.12.10 — wraps bundle bytes in a hybrid PQC envelope before writeFile). " +
+      "Passphrase strategy is deferred to v0.12.11.");
+  }
+  var recipient = opts.recipient;
+  if (cryptoStrategy === "recipient" && (!recipient || typeof recipient !== "object")) {
+    throw new BackupError("backup/no-recipient",
+      "bundleAdapterStorage: cryptoStrategy: \"recipient\" requires opts.recipient " +
+      "({ publicKey, ecPublicKey } for the hybrid PQC envelope OR { peerCertDer, peerKemPubkey } " +
+      "for the peer-cert envelope)");
+  }
+  // Codex P1 on v0.12.10 PR #161 — the wrap layer composes only
+  // with the tar / tar.gz writeBundle branches. Pairing recipient
+  // strategy with format: "directory" would silently write plaintext
+  // per-file payloads because the directory branch doesn't apply
+  // the envelope. Refuse the combination upfront so operators see
+  // the contract gap rather than discover it via disk inspection.
+  // Per-file recipient encryption for directory format is a v0.12.11
+  // follow-up alongside the _crypto-base.js refactor.
+  if (cryptoStrategy === "recipient" && format === "directory") {
+    throw new BackupError("backup/recipient-strategy-needs-bundled-format",
+      "bundleAdapterStorage: cryptoStrategy: \"recipient\" requires format: \"tar\" or \"tar.gz\". " +
+      "Directory format writes per-file plaintext to the adapter — the wrap layer composes only " +
+      "with tar / tar.gz bundles in v0.12.10. Per-file recipient encryption is a v0.12.11 follow-up.");
+  }
+  var posture = opts.posture;
+  if (posture && BACKUP_ENCRYPTION_REQUIRED_POSTURES.indexOf(posture) !== -1 &&
+      cryptoStrategy === "none") {
+    throw new BackupError("backup/posture-requires-encryption",
+      "bundleAdapterStorage: posture=" + JSON.stringify(posture) +
+      " requires cryptoStrategy: \"recipient\" (the adapter-storage layer cannot itself " +
+      "satisfy HIPAA / PCI-DSS encryption-at-rest with cryptoStrategy: \"none\"). " +
+      "The recipient+directory combination is refused separately so operators don't slip " +
+      "plaintext per-file payloads past the posture gate.");
   }
   // 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 +1163,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 +1189,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 +1223,14 @@ 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();
+        if (cryptoStrategy === "recipient") {
+          payloadBytes = archiveLazy().wrap(payloadBytes, { recipient: recipient });
+        }
+        await adapter.writeFile(bundleId + keySuffix, payloadBytes);
         return;
       }
       // Directory format (v0.12.7 layout).
@@ -1184,16 +1248,44 @@ 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);
+        if (cryptoStrategy === "recipient") {
+          gzBytes = archiveLazy().unwrap(gzBytes, { recipient: recipient });
+        }
+        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);
+        if (cryptoStrategy === "recipient") {
+          tarBytes = archiveLazy().unwrap(tarBytes, { recipient: recipient });
+        }
         var reader = archiveLazy().read.tar(archiveAdaptersLazy().buffer(tarBytes));
         await reader.extract({ destination: destDir });
         return;
@@ -1217,7 +1309,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 +1362,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;
     },
@@ -1301,7 +1402,15 @@ bundleAdapterStorage.fsAdapter = function (fsOpts) {
     async writeFile(key, bytes) {
       var path = _keyPath(key);
       atomicFile.ensureDir(nodePath.dirname(path));
-      nodeFs.writeFileSync(path, bytes);
+      // mode 0o600 matches the v0.12.9 directory-format readback
+      // discipline — backup payloads carry operator-owned bytes
+      // (potentially PHI / PCI / GDPR-scoped); owner-only is the
+      // strict posture. wx is not set here because writeFile is
+      // the storage primitive (operators legitimately rewrite the
+      // same key, e.g. resuming a multipart upload); upper layers
+      // (writeBundle's `bundle-exists` check) enforce no-overwrite
+      // at the bundle level.
+      nodeFs.writeFileSync(path, bytes, { mode: 0o600 });
     },
     async readFile(key) {
       var path = _keyPath(key);

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.10",
   "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:15ca08ce-3216-4a0c-bd31-d9c198e71e36",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T16:36:21.469Z",
+    "timestamp": "2026-05-23T19:05:59.300Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.8",
+      "bom-ref": "@blamejs/core@0.12.10",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.8",
+      "version": "0.12.10",
       "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.10",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.8",
+      "ref": "@blamejs/core@0.12.10",
       "dependsOn": []
     }
   ]