@blamejs/core 0.12.9 → 0.12.10

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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)

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

@@ -546,14 +546,18 @@ 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,
-  gz:              archiveGz.gz,
-  ArchiveError:    ArchiveError,
-  TarError:        archiveTar.TarError,
-  ArchiveGzError:  archiveGz.ArchiveGzError,
+  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,

package/lib/backup/index.js

@@ -1068,6 +1068,58 @@ function bundleAdapterStorage(opts) {
     throw new BackupError("backup/bad-format",
       "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
   // contract is bytes-in (no writeStream method). The OOM-prevention
@@ -1175,6 +1227,9 @@ function bundleAdapterStorage(opts) {
         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;
       }
@@ -1215,6 +1270,9 @@ function bundleAdapterStorage(opts) {
         // 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,
@@ -1225,6 +1283,9 @@ function bundleAdapterStorage(opts) {
       }
       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;
@@ -1341,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.9",
+  "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:f5a3cd7a-802d-4f55-ba59-958f474f38a0",
+  "serialNumber": "urn:uuid:15ca08ce-3216-4a0c-bd31-d9c198e71e36",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T17:58:07.192Z",
+    "timestamp": "2026-05-23T19:05:59.300Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.9",
+      "bom-ref": "@blamejs/core@0.12.10",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.9",
+      "version": "0.12.10",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.9",
+      "purl": "pkg:npm/%40blamejs/core@0.12.10",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.9",
+      "ref": "@blamejs/core@0.12.10",
       "dependsOn": []
     }
   ]