@blamejs/core 0.12.12 → 0.12.13

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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.
 
 - v0.12.11 (2026-05-23) — **`b.archive.wrapWithPassphrase` + `b.archive.unwrapWithPassphrase` — Argon2id + XChaCha20-Poly1305 archive envelope + `b.backup` `cryptoStrategy: "passphrase"` with HIPAA / PCI-DSS 128-bit entropy floor.** Passphrase wrap lands as the second `b.archive` envelope strategy alongside v0.12.10's recipient wrap. `b.archive.wrapWithPassphrase(bytes, { passphrase, minEntropyBits })` produces a `BAWPP`-prefixed envelope under Argon2id (RFC 9106; framework-default 64 MiB / 3 iterations / 4 parallelism) key derivation with XChaCha20-Poly1305 AEAD; each envelope carries its own fresh salt in the wire format (5-byte magic + 1-byte version + 1-byte saltLen + salt + 24-byte nonce + ciphertext+tag) so KDF parameters can rotate in future minors without per-envelope version bumps. `b.archive.unwrapWithPassphrase(sealed, { passphrase })` verifies the `BAWPP` header before any Argon2id compute so non-envelope inputs fail with `archive-wrap/bad-magic` rather than burning the KDF on bad bytes. `b.backup.bundleAdapterStorage({ cryptoStrategy: "passphrase", passphrase })` composes the wrap layer transparently — bundle bytes hitting the adapter's `writeFile` are an opaque passphrase-derived envelope. Default `passphraseMinEntropyBits: 80` matches OWASP strong-password guidance; HIPAA + PCI-DSS postures raise the floor to 128 bits automatically (matching the framework's existing crypto-grade-password discipline for sealed-storage). The recipient strategy from v0.12.10 + passphrase strategy from v0.12.11 + plaintext strategy from v0.12.7 cover the operator's posture matrix: HIPAA / PCI-DSS pick recipient or passphrase; non-regulated deployments may stay on `"none"` when the storage layer is itself the protective boundary. **Added:** *`b.archive.wrapWithPassphrase(bytes, { passphrase, minEntropyBits })` — Argon2id-derived archive envelope* — Composes `b.backupCrypto.encryptWithFreshSalt(bytes, passphrase)` (Argon2id KDF + XChaCha20-Poly1305 AEAD, fresh per-envelope salt) and prepends a 7-byte `BAWPP` envelope header (5-byte magic + 1-byte version + 1-byte saltLen) so format sniffers can identify passphrase wrap output without trial KDF work. Entropy estimate uses observed-alphabet bit-count (the standard NIST/OWASP character-class approximation). `minEntropyBits` defaults to 80; the gate refuses upfront with `archive-wrap/weak-passphrase` when the estimate falls short. · *`b.archive.unwrapWithPassphrase(sealed, { passphrase })` — inverse with magic-check upfront* — Verifies the 7-byte `BAWPP` header (magic + version + saltLen) before any cryptographic work so non-envelope inputs (raw archives, recipient-wrap envelopes, truncated buffers) fail with `archive-wrap/bad-magic` / `archive-wrap/bad-version` / `archive-wrap/truncated-envelope` rather than wasting Argon2id compute. Routes through `b.backupCrypto.decryptWithPassphrase(encrypted, passphrase, saltHex)` so the framework's locked Argon2id parameters apply. · *`b.backup.bundleAdapterStorage({ cryptoStrategy: "passphrase", passphrase })` — Argon2id-keyed bundle storage* — Composes `b.archive.wrapWithPassphrase` transparently — every `writeBundle` payload is wrapped before `adapter.writeFile`; every `readBundle` payload is unwrapped after `adapter.readFile`. The `passphraseMinEntropyBits` opt defaults to 80 (OWASP strong-password floor); HIPAA + PCI-DSS postures raise the floor to 128 bits automatically. Passphrase + directory format combination refused upfront (same contract as recipient + directory). Wire-format envelope on disk is opaque ciphertext — no information leakage about archive contents through the storage adapter. · *HIPAA + PCI-DSS postures raise entropy floor to 128 bits under passphrase strategy* — `bundleAdapterStorage({ posture: "hipaa", cryptoStrategy: "passphrase", passphrase })` enforces `passphraseMinEntropyBits >= 128` regardless of the operator-supplied opt. The 128-bit floor matches the framework's existing crypto-grade-password discipline for sealed-storage cells. Operators sourcing passphrases from a CSPRNG (`b.crypto.generateBytes(16).toString("base64url")` → ~128 bits) pass without issue; operators typing dictionary phrases trip the gate. **Security:** *Magic-check before KDF work — non-envelope inputs can't burn Argon2id compute* — Adversarial inputs that look like passphrase envelopes but aren't (random bytes, recipient envelopes, raw archives) fail at byte 0-4 (magic check) rather than after a 64 MiB Argon2id round. Operators handing user-supplied bundles to readBundle on a server with concurrent load get bounded refusal latency rather than worst-case KDF compute under a chosen-bytes attack.

package/lib/backup/index.js

@@ -1497,6 +1497,194 @@ bundleAdapterStorage.fsAdapter = function (fsOpts) {
   };
 };
 
+// ---- v0.12.13: objectStoreAdapter ----------------------------------------
+
+/**
+ * @primitive b.backup.bundleAdapterStorage.objectStoreAdapter
+ * @signature b.backup.bundleAdapterStorage.objectStoreAdapter(client, opts?)
+ * @since     0.12.13
+ * @status    stable
+ * @related   b.backup.bundleAdapterStorage, b.objectStore
+ *
+ * Wraps a `b.objectStore`-shaped client into the
+ * `{ writeFile, readFile, listKeys, deleteKey, hasKey }` adapter
+ * contract that `bundleAdapterStorage` consumes. The client must
+ * expose `put(key, body) → Promise<{ size }>`, `get(key) →
+ * Promise<Buffer>`, `head(key) → Promise<{ size, ... }>`,
+ * `delete(key) → Promise<boolean>`, and `list(prefix, opts?) →
+ * Promise<{ items: [{ key, size, ... }], truncated }>` — the
+ * shape produced by `b.objectStore.buildBackend({ protocol: ... })`
+ * for the local / SigV4 / GCS / Azure-Blob backends.
+ *
+ * `opts.prefix` namespaces every key under a fixed root inside the
+ * bucket — operators sharing a bucket across multiple deployments
+ * pass distinct prefixes so listings stay scoped.
+ *
+ * `opts.list` is the operator-tunable `{ maxResults, ... }` pass-
+ * through forwarded to the underlying `client.list` call (defaults
+ * to whatever the backend's `list` defaults to — typically 1000).
+ *
+ * Closes the v0.12.10 deferral: "S3 / MinIO / Azure / GCS-backed
+ * backups" promised since v0.11.2 JSDoc.
+ *
+ * @opts
+ *   prefix:  string,    // namespace every key under this prefix in the bucket
+ *   list:    { maxResults: number },   // forwarded to client.list opts
+ *
+ * @example
+ *   var client = b.objectStore.buildBackend({
+ *     protocol: "local",
+ *     rootDir:  "/var/backups",
+ *   });
+ *   var storage = b.backup.bundleAdapterStorage({
+ *     adapter:        b.backup.bundleAdapterStorage.objectStoreAdapter(client),
+ *     format:         "tar.gz",
+ *     cryptoStrategy: "recipient",
+ *     recipient:      pair,
+ *   });
+ *   // bundle bytes hit the object-store backend's put(); restore
+ *   // path composes through unwrap + read.gz + read.tar.
+ */
+bundleAdapterStorage.objectStoreAdapter = function (client, osOpts) {
+  if (!client || typeof client !== "object") {
+    throw new BackupError("backup/bad-adapter",
+      "objectStoreAdapter: client is required (a b.objectStore-shaped object with put / get / head / delete / list)");
+  }
+  var required = ["put", "get", "head", "delete", "list"];
+  for (var i = 0; i < required.length; i += 1) {
+    if (typeof client[required[i]] !== "function") {
+      throw new BackupError("backup/bad-adapter",
+        "objectStoreAdapter: client missing method '" + required[i] + "'");
+    }
+  }
+  osOpts = osOpts || {};
+  var prefix = "";
+  if (osOpts.prefix !== undefined && osOpts.prefix !== null) {
+    if (typeof osOpts.prefix !== "string") {
+      throw new BackupError("backup/bad-arg",
+        "objectStoreAdapter: opts.prefix must be a string");
+    }
+    if (osOpts.prefix.indexOf("..") !== -1 || osOpts.prefix.indexOf("\u0000") !== -1) {
+      throw new BackupError("backup/bad-arg",
+        "objectStoreAdapter: opts.prefix contains traversal segment or NUL byte");
+    }
+    // Strip trailing slashes without a backtracking regex (CodeQL
+    // js/polynomial-redos flagged `/\/+$/`, which is linear in
+    // practice but flagged conservatively). Walk back from the end
+    // and slice once.
+    var endIdx = osOpts.prefix.length;
+    while (endIdx > 0 && osOpts.prefix.charCodeAt(endIdx - 1) === 0x2f) endIdx -= 1;  // 0x2f = "/"
+    prefix = osOpts.prefix.slice(0, endIdx);
+    if (prefix.length > 0) prefix += "/";
+  }
+  var listOpts = osOpts.list || {};
+
+  function _scopedKey(key) {
+    if (typeof key !== "string" || key.length === 0) {
+      throw new BackupError("backup/bad-key",
+        "objectStoreAdapter: key must be a non-empty string");
+    }
+    if (key.indexOf("..") !== -1 || key.indexOf("\u0000") !== -1) {
+      throw new BackupError("backup/bad-key",
+        "objectStoreAdapter: key contains traversal segment or NUL byte");
+    }
+    return prefix + key;
+  }
+
+  return {
+    async writeFile(key, bytes) {
+      if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+        throw new BackupError("backup/bad-arg",
+          "objectStoreAdapter.writeFile: bytes must be a Buffer or Uint8Array");
+      }
+      await client.put(_scopedKey(key), Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
+    },
+    async readFile(key) {
+      var scoped = _scopedKey(key);
+      try {
+        var body = await client.get(scoped);
+        return Buffer.isBuffer(body) ? body : Buffer.from(body);
+      } catch (e) {
+        // b.objectStore surfaces NOT_FOUND via the framework's
+        // err.code === "NOT_FOUND" convention — translate to the
+        // backup adapter contract's no-key error.
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          throw new BackupError("backup/no-key",
+            "objectStoreAdapter: key not found: " + JSON.stringify(key));
+        }
+        throw e;
+      }
+    },
+    async listKeys(keyPrefix) {
+      // _scopedKey rejects empty strings; for list(prefix) we want
+      // to allow listing the whole bundle root. Compose the
+      // prefix manually so `listKeys("")` enumerates everything
+      // under the operator-supplied namespace.
+      var realScoped = prefix + (keyPrefix || "");
+      // Codex P1 on v0.12.13 PR #164 — object-store backends page
+      // results (default 1000 keys). Without continuation, listKeys
+      // silently dropped bundles past page 1 — listBundles missed
+      // them, deleteBundle skipped them. Follow the
+      // truncated / continuationToken contract until every page
+      // is consumed. PAGINATION_CAP guards against a runaway
+      // server returning truncated:true forever (defense-in-depth;
+      // shipped backends honour the contract).
+      var PAGINATION_CAP = 1000;                                                      // allow:raw-byte-literal — page count cap, not byte count
+      var out = [];
+      var token = null;
+      var pages = 0;
+      do {
+        var pageOpts = Object.assign({}, listOpts);
+        if (token) pageOpts.continuationToken = token;
+        var result = await client.list(realScoped, pageOpts);
+        var items = result && result.items ? result.items : (Array.isArray(result) ? result : []);
+        for (var i = 0; i < items.length; i += 1) {
+          var k = typeof items[i] === "string" ? items[i] : items[i].key;
+          if (typeof k !== "string") continue;
+          if (prefix.length > 0 && k.indexOf(prefix) === 0) {
+            out.push(k.slice(prefix.length));
+          } else {
+            out.push(k);
+          }
+        }
+        token = result && result.continuationToken ? result.continuationToken : null;
+        if (!result || result.truncated !== true) break;
+        if (!token) break;                                                            // truncated:true without continuationToken — stop to avoid spin
+        pages += 1;
+        if (pages > PAGINATION_CAP) {
+          throw new BackupError("backup/list-pagination-runaway",
+            "objectStoreAdapter.listKeys: backend returned >" + PAGINATION_CAP +
+            " pages without exhausting; refusing to spin (operator should narrow the prefix or raise opts.list.maxResults)");
+        }
+      } while (true);
+      return out;
+    },
+    async deleteKey(key) {
+      try {
+        await client.delete(_scopedKey(key));
+      } catch (e) {
+        // drop-silent on NOT_FOUND — adapter contract is idempotent
+        // delete (fsAdapter same shape).
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          return;
+        }
+        throw e;
+      }
+    },
+    async hasKey(key) {
+      try {
+        await client.head(_scopedKey(key));
+        return true;
+      } catch (e) {
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          return false;
+        }
+        throw e;
+      }
+    },
+  };
+};
+
 // ---- v0.12.8: migrate ----------------------------------------------------
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "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:c9470d27-8ecf-46a8-8a75-2a26724c7831",
+  "serialNumber": "urn:uuid:ab401616-3671-455e-8dbd-edc2385efd48",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T22:09:15.262Z",
+    "timestamp": "2026-05-24T02:05:49.624Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.12",
+      "bom-ref": "@blamejs/core@0.12.13",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.12",
+      "version": "0.12.13",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.12",
+      "purl": "pkg:npm/%40blamejs/core@0.12.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.12",
+      "ref": "@blamejs/core@0.12.13",
       "dependsOn": []
     }
   ]