@blamejs/core 0.12.13 → 0.12.15

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.15 (2026-05-23) — **`b.safeArchive.extract` auto-unwraps v0.12.10 recipient and v0.12.11 passphrase envelopes inline.** The safeArchive orchestrator's `format: "auto"` sniffer recognises `BAWRP` (v0.12.10 recipient) and `BAWPP` (v0.12.11 passphrase) envelope magics and routes through `b.archive.unwrap` / `b.archive.unwrapWithPassphrase` inline before re-sniffing the inner format. Operators pass `opts.recipient` (or `opts.passphrase`) alongside `source` + `destination` and get a single extract() call regardless of envelope shape. Missing the matching key opt surfaces a structured `safe-archive/no-recipient-for-wrap` / `safe-archive/no-passphrase-for-wrap` refusal upfront rather than a downstream crypto error. **Added:** *`b.safeArchive.extract` auto-unwraps wrap envelopes* — The sniffer at byte 0-4 recognises `BAWRP` (returns `format: "wrap-recipient"`) and `BAWPP` (returns `format: "wrap-passphrase"`). The extract path collects the sealed adapter into a Buffer, routes through `b.archive.unwrap` (recipient) or `b.archive.unwrapWithPassphrase` (passphrase), wraps the inner bytes in a buffer adapter, re-sniffs the inner format, and dispatches to the appropriate `b.archive.read.*` reader. A wrap-around-tar.gz envelope round-trips through wrap → unwrap → gunzip → untar with no operator intervention beyond passing the key opt. **Security:** *Missing-key opt refused upfront with structured error* — When the sniffer identifies a wrap envelope but the operator hasn't supplied `opts.recipient` (BAWRP) or `opts.passphrase` (BAWPP), extract refuses with `safe-archive/no-recipient-for-wrap` / `safe-archive/no-passphrase-for-wrap` BEFORE any decryption attempt. Operators wiring extract behind an HTTP boundary get a typed refusal instead of a leaked crypto-level error.
+
+- v0.12.14 (2026-05-23) — **`b.archive.sniffEnvelope(bytes)` — identify recipient vs passphrase vs raw payload without attempting decryption.** Small helper closing a gap in the archive-wrap surface. `b.archive.sniffEnvelope(bytes)` reads the first 5 bytes of a buffer and returns one of `"recipient"` (v0.12.10 BAWRP envelope), `"passphrase"` (v0.12.11 BAWPP envelope), or `"none"` (raw payload or unrelated bytes). The sniff does NO cryptographic work — no Argon2id round, no decapsulation, no allocation beyond a 5-byte ASCII compare — so it's safe to call on adversarial input. Operators dispatching between unwrap paths get a clean predicate instead of trial-decrypting under multiple key candidates. **Added:** *`b.archive.sniffEnvelope(bytes)` — magic-byte envelope identifier* — Returns `"recipient"` (BAWRP / v0.12.10 hybrid PQC envelope), `"passphrase"` (BAWPP / v0.12.11 Argon2id + XChaCha20 envelope), or `"none"` (raw archive bytes / unrelated payload). Accepts Buffer + Uint8Array; non-buffer / null / undefined / empty-buffer inputs return `"none"` upfront. Operators wire the result into a switch that dispatches to the matching unwrap primitive — no trial decryption, no per-key candidate attempts.
+
 - v0.12.13 (2026-05-23) — **`b.backup.bundleAdapterStorage.objectStoreAdapter` — wraps any `b.objectStore` backend (local / SigV4 / GCS / Azure-Blob) into the backup-adapter contract; closes the v0.11.2 "any custom backend" promise.** `b.backup.bundleAdapterStorage.objectStoreAdapter(client, opts)` adapts a `b.objectStore`-shaped client into the `{ writeFile, readFile, listKeys, deleteKey, hasKey }` adapter contract that `bundleAdapterStorage` consumes. Operators wire any of the four shipped object-store backends (`protocol: "local"` / `"sigv4"` for S3+MinIO / `"gcs"` / `"azure-blob"`) through the same recipient / passphrase wrap layers shipped in v0.12.10 and v0.12.11 — the bundle bytes hit the object-store `put` as an opaque envelope. `opts.prefix` namespaces every key under a fixed root inside the bucket so operators sharing a bucket across deployments keep listings scoped. Closes the deferral surfaced in v0.11.2 JSDoc and the v0.12.10 release-notes follow-up list: "S3 or any custom backend" is now wired with no operator-supplied adapter glue. **Added:** *`b.backup.bundleAdapterStorage.objectStoreAdapter(client, opts?)` — object-store-backed bundle storage* — Adapts any `b.objectStore.buildBackend({ protocol })` client (local / sigv4 / gcs / azure-blob) into the `{ writeFile, readFile, listKeys, deleteKey, hasKey }` adapter contract. NOT_FOUND errors from the underlying client translate to `backup/no-key` for the readFile path and to idempotent return-without-throw for deleteKey (matching the fsAdapter contract). hasKey routes through `client.head(key)` — NOT_FOUND → false; any other error propagates so operators can distinguish network failure from missing-key. Composes transparently with v0.12.10 `cryptoStrategy: "recipient"` and v0.12.11 `cryptoStrategy: "passphrase"` — the wrap envelope is the bytes hitting the object-store put. · *`opts.prefix` — per-deployment key namespacing inside the bucket* — Operators sharing one bucket across multiple deployments (per-environment / per-tenant / per-region) pass distinct prefixes so listings stay scoped. The prefix gets a trailing slash inserted automatically; traversal segments (`..`) and NUL bytes refused upfront with `backup/bad-arg` so a misconfigured prefix can't escape the operator's intended scope. listKeys strips the prefix on return so the adapter surface looks identical to the fsAdapter — operators switching backends don't see key-shape drift. **Security:** *Key path validation — traversal + NUL byte refusal at every adapter call* — Every `_scopedKey(key)` invocation refuses keys containing `..` traversal segments or NUL bytes upfront with `backup/bad-key` so a misconfigured bundleId or an attacker-controlled value never reaches the underlying `client.put(...)` / `client.get(...)`. Matches the same defensive posture the fsAdapter carries against operator-supplied key shapes.
 
 - v0.12.12 (2026-05-23) — **`b.ai.disclosure.chatbot` + `b.ai.disclosure.deepfake` + `b.ai.disclosure.emotion` — EU AI Act Art. 50 transparency obligations (calendar-locked 2026-08-02) with US-CA AB-853 + China CAC GenAI cross-walk.** EU AI Act Art. 50 transparency primitives land ahead of the 2026-08-02 enforcement deadline. `b.ai.disclosure.chatbot(session, opts)` emits the Art. 50(1) first-contact "you are interacting with an AI system" disclosure with placement control (`first-message` / `always` / `on-request`). `b.ai.disclosure.deepfake(content, { contentType, placement, jurisdiction })` emits the Art. 50(4) synthetic-content label + machine-readable metadata payload for image / audio / video / text. `b.ai.disclosure.emotion({ systemType })` emits the Art. 50(3) emotion-recognition / biometric-categorisation notice. Each primitive emits a tamper-evident `ai-act/*-disclosure-applied` audit event so the compliance trail backs the user-facing notice. Cross-jurisdiction cross-walk lives in `opts.jurisdiction`: `"eu"` (default), `"us-ca"` adds AB-853 §22949.91 to the cross-walk array, `"cn"` adds CAC GenAI Measures Art. 12. The deepfake primitive returns a `schema: "c2pa-v1.4-ready"` metadata field that the v0.12.21 `b.contentCredentials` C2PA adapter will consume when it lands — this patch ships the label markup + schema; the C2PA manifest emission is the next composition. **Added:** *`b.ai.disclosure.chatbot(session, opts)` — Art. 50(1) first-contact disclosure* — Operators interacting with natural persons via an AI system get a primitive that emits the "you are interacting with an AI system" notice + audits the emission. `placement` opts: `"first-message"` (default — emit on first contact only, tracked via `session.aiDisclosureEmitted`), `"always"` (every response), `"on-request"` (operator wires their own trigger). Returns `{ text, language, jurisdiction, placement, shouldEmit, article, regulation }` — `shouldEmit` is the operator-consumable boolean for response-wire-up logic. · *`b.ai.disclosure.deepfake(content, opts)` — Art. 50(4) synthetic-content label* — Operators emitting model-generated or model-manipulated content get a primitive that returns both the visible label markup AND the machine-readable metadata payload. `contentType: "image" | "audio" | "video" | "text"` is required; `placement: "label" | "metadata" | "both"` (default `"both"`) controls what the primitive populates. The metadata payload includes `schema: "c2pa-v1.4-ready"` — the v0.12.21 `b.contentCredentials` C2PA adapter will consume this schema field when it lands. `crossWalk` array carries `["eu-ai-act/Art. 50(4)"]` plus the per-jurisdiction reference (AB-853 §22949.91 / CAC GenAI Art. 12). · *`b.ai.disclosure.emotion(opts)` — Art. 50(3) emotion-recognition / biometric-categorisation notice* — Operators deploying emotion-recognition or biometric-categorisation systems get the consent-flow notice primitive. `systemType: "emotion" | "biometric-categorisation"` (default `"emotion"`) selects which Art. 50(3) sub-obligation applies. Returns the notice payload + emits an `ai-act/emotion-disclosure-applied` audit event. · *Cross-jurisdiction cross-walk: EU + US-CA + China in a single primitive* — The `opts.jurisdiction` opt accepts `"eu"` (default — Regulation (EU) 2024/1689), `"us-ca"` (California AB-853 effective 2026), or `"cn"` (China CAC GenAI Measures). The chatbot + deepfake primitives both honour the cross-walk: the deepfake response's `crossWalk` array carries every jurisdiction-specific legal reference the same emission satisfies, so operators serving multi-region traffic emit one notice + audit one event + reference all applicable regimes. **Security:** *Drop-silent audit emission preserves the disclosure path under audit-bus failure* — If `opts.audit` is supplied but its `safeEmit` throws (network bus down, audit-sign chain malformed), the disclosure primitive still returns the user-facing notice payload. The Art. 50 obligation is the user-facing notice itself; the audit emission is a parallel best-effort chain-of-custody record. Refusing the disclosure to defend the audit chain would fail the wrong direction — the regulatory contract is satisfied by emitting the notice. Matches the framework's `audit.safeEmit` drop-silent contract for hot-path observability sinks. **Migration:** *C2PA manifest emission lands in v0.12.21* — The deepfake primitive's metadata payload includes a `schema: "c2pa-v1.4-ready"` field that the v0.12.21 `b.contentCredentials` adapter will consume. Operators emitting image / audio / video for v0.12.12-0.12.20 get the label markup + structured metadata; the actual C2PA manifest (signed JUMBF assertion chain) is the next composition layer.

package/lib/archive-wrap.js

@@ -240,6 +240,63 @@ function _isPassphraseMagic(buf) {
     buf.slice(0, 5).toString("ascii") === ARCH_PASSPHRASE_MAGIC;
 }
 
+/**
+ * @primitive b.archive.sniffEnvelope
+ * @signature b.archive.sniffEnvelope(bytes)
+ * @since     0.12.14
+ * @status    stable
+ * @related   b.archive.wrap, b.archive.unwrap, b.archive.wrapWithPassphrase, b.archive.unwrapWithPassphrase
+ *
+ * Identify the envelope shape carried by a buffer without attempting
+ * decryption. Returns one of:
+ *   - `"recipient"` — `BAWRP` header (v0.12.10 hybrid PQC envelope).
+ *     Operator routes through `b.archive.unwrap(bytes, { recipient })`.
+ *   - `"passphrase"` — `BAWPP` header (v0.12.11 Argon2id + XChaCha20
+ *     envelope). Operator routes through
+ *     `b.archive.unwrapWithPassphrase(bytes, { passphrase })`.
+ *   - `"none"` — no archive-wrap envelope magic. The bytes are
+ *     either raw archive content (gz / tar / zip) or an unrelated
+ *     payload; operator routes to the appropriate `b.archive.read.*`
+ *     primitive (or refuses entirely).
+ *
+ * The sniff is byte 0-4 inspection ONLY — no cryptographic work,
+ * no allocation beyond a 5-byte ASCII compare. Safe to call on
+ * adversarial input.
+ *
+ * @example
+ *   var kind = b.archive.sniffEnvelope(payloadBytes);
+ *   switch (kind) {
+ *     case "recipient":  return b.archive.unwrap(payloadBytes, { recipient });
+ *     case "passphrase": return b.archive.unwrapWithPassphrase(payloadBytes, { passphrase });
+ *     case "none":       return payloadBytes;
+ *   }
+ */
+function sniffEnvelope(bytes) {
+  if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+    return "none";
+  }
+  // Codex P2A on v0.12.14 PR #165 — `Buffer.from(uint8Array)` copies
+  // the entire input, turning a constant-time 5-byte probe into an
+  // O(n) allocation. Use the zero-copy view form so the sniff is
+  // truly cheap regardless of input size.
+  var buf = Buffer.isBuffer(bytes)
+    ? bytes
+    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buf.length < 5) return "none";
+  // Codex P2B on v0.12.14 PR #165 — match on the 5-byte ASCII magic
+  // alone, NOT on the full header (which requires version + saltLen
+  // bytes). A truncated envelope (`BAWRP` + nothing else) is still a
+  // recipient envelope; the unwrap call surfaces the truncation with
+  // a structured `archive-wrap/truncated-envelope` error. Returning
+  // "none" on truncated input would misclassify damaged envelopes as
+  // raw payload and the operator's dispatch switch would skip the
+  // wrap error path entirely.
+  var magic = buf.slice(0, 5).toString("ascii");
+  if (magic === ARCH_WRAP_MAGIC) return "recipient";
+  if (magic === ARCH_PASSPHRASE_MAGIC) return "passphrase";
+  return "none";
+}
+
 /**
  * @primitive b.archive.wrapWithPassphrase
  * @signature b.archive.wrapWithPassphrase(bytes, opts)
@@ -438,6 +495,7 @@ module.exports = {
   unwrap:                unwrap,
   wrapWithPassphrase:    wrapWithPassphrase,
   unwrapWithPassphrase:  unwrapWithPassphrase,
+  sniffEnvelope:         sniffEnvelope,
   ArchiveWrapError:      ArchiveWrapError,
   // Exposed for sibling modules + sniffer
   _isWrapMagic:          _isWrapMagic,

package/lib/archive.js

@@ -556,6 +556,7 @@ module.exports = {
   unwrap:               archiveWrap.unwrap,
   wrapWithPassphrase:   archiveWrap.wrapWithPassphrase,
   unwrapWithPassphrase: archiveWrap.unwrapWithPassphrase,
+  sniffEnvelope:        archiveWrap.sniffEnvelope,
   ArchiveError:      ArchiveError,
   TarError:          archiveTar.TarError,
   ArchiveGzError:    archiveGz.ArchiveGzError,

package/lib/safe-archive.js

@@ -47,6 +47,7 @@ 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"); });
+var archiveWrap = lazyRequire(function () { return require("./archive-wrap"); });
 
 // ---- Format sniffing ----------------------------------------------------
 
@@ -93,6 +94,10 @@ async function _sniffMagic(adapter) {
   if (head.length >= 5) {
     var prefix = head.slice(0, 5).toString("utf8");
     if (prefix === MAGIC_ENCPACKED) return { format: "encryptPacked" };
+    // v0.12.15 — archive-wrap recipient envelope (v0.12.10 / BAWRP).
+    if (prefix === "BAWRP") return { format: "wrap-recipient" };
+    // v0.12.15 — archive-wrap passphrase envelope (v0.12.11 / BAWPP).
+    if (prefix === "BAWPP") return { format: "wrap-passphrase" };
   }
   // tar — "ustar" at offset 257 within the first 512-byte header.
   if (head.length >= 263) {
@@ -102,6 +107,22 @@ async function _sniffMagic(adapter) {
   return { format: "unknown" };
 }
 
+// Collect a random-access adapter's bytes into a Buffer. Used by
+// the v0.12.15 auto-unwrap path so the envelope can be decrypted
+// inline + the inner bytes re-fed to a buffer adapter for format
+// re-sniffing. Adapters expose `size` + `range(offset, length)`.
+async function _collectSourceBytes(source) {
+  var size = source.size;
+  if (size == null && typeof source.resolveSize === "function") {
+    size = await source.resolveSize();
+  }
+  if (typeof size !== "number" || size < 0) {
+    throw new SafeArchiveError("safe-archive/bad-source",
+      "_collectSourceBytes: source adapter did not report a numeric size");
+  }
+  return source.range(0, size);
+}
+
 // ---- Public extract orchestrator ----------------------------------------
 
 /**
@@ -180,6 +201,50 @@ async function extract(opts) {
       var sniff = await _sniffMagic(source);
       format = sniff.format;
     }
+    // v0.12.15 — auto-unwrap path. When the sniffer identifies a
+    // wrap envelope, unwrap inline + re-sniff the inner bytes so
+    // operators get a single extract() call regardless of envelope
+    // shape. Operator must supply opts.recipient or opts.passphrase
+    // matching the envelope kind.
+    if (format === "wrap-recipient" || format === "wrap-passphrase") {
+      var sealedBytes = await _collectSourceBytes(source);
+      var inner;
+      if (format === "wrap-recipient") {
+        if (!opts.recipient) {
+          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
+            "extract: source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
+            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
+        }
+        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
+      } else {
+        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
+          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
+            "extract: source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
+            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
+        }
+        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
+      }
+      // Codex P1 on v0.12.15 PR #166 — close the original source
+      // adapter BEFORE replacing it. When opts.source was a string
+      // path, the fs adapter opened a file descriptor; overwriting
+      // `source` loses the close reference and the descriptor
+      // leaks across repeated extract() calls (eventually EMFILE
+      // under load). The outer finally still closes whatever
+      // `source` points at, but the original handle needs explicit
+      // release here.
+      if (typeof source.close === "function" && typeof opts.source === "string") {
+        try { source.close(); } catch (_e) { /* drop-silent */ }
+      }
+      // Codex P2 on v0.12.15 PR #166 — forward opts.signal to the
+      // inner buffer adapter so abort propagation stays intact
+      // across the unwrap boundary. Without it, an abort raised
+      // after unwrapping would no longer cancel inner range()
+      // calls, breaking the documented signal contract for
+      // large wrapped archives.
+      source = archiveAdapters().buffer(inner, { signal: opts.signal });
+      var innerSniff = await _sniffMagic(source);
+      format = innerSniff.format;
+    }
     var reader;
     if (format === "zip") {
       reader = archiveRead().zip(source, {
@@ -210,8 +275,8 @@ async function extract(opts) {
       });
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "extract: format=" + JSON.stringify(format) + " — v0.12.9 ships ZIP + tar + tar.gz " +
-        "(encryptPacked-wrap lands v0.12.10)");
+        "extract: format=" + JSON.stringify(format) + " — v0.12.9 ships ZIP + tar + tar.gz; " +
+        "v0.12.10/v0.12.11 added wrap-recipient + wrap-passphrase envelopes (auto-unwrap as of v0.12.15)");
     }
     var result = await reader.extract({
       destination:    opts.destination,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.13",
+  "version": "0.12.15",
   "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:ab401616-3671-455e-8dbd-edc2385efd48",
+  "serialNumber": "urn:uuid:73e48489-0fa1-477f-b6f3-eec74e9ba65f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T02:05:49.624Z",
+    "timestamp": "2026-05-24T03:18:46.285Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.13",
+      "bom-ref": "@blamejs/core@0.12.15",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.13",
+      "version": "0.12.15",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.13",
+      "purl": "pkg:npm/%40blamejs/core@0.12.15",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.13",
+      "ref": "@blamejs/core@0.12.15",
       "dependsOn": []
     }
   ]