@blamejs/core 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.4 (2026-05-19) — **`b.audit.useStore({ record })` shadow store + WebSocket permessage-deflate bomb fix + 5 new codebase-patterns detectors + shape-matcher substrate.** **`b.audit.useStore({ record })`** registers an operator-supplied shadow store that receives a copy of every audit chain append AFTER the framework's tamper-evident chain commits. The operator's `record(row)` async function receives the fully-formed row — `{ _id, recordedAt, monotonicCounter, prevHash, rowHash, action, outcome, actorUserId, ..., metadata }` — so external destinations (AWS QLDB / Azure Confidential Ledger / Google Cloud Audit Logs / in-house WORM appliances / SIEM forwarders) see identical hashes for cross-store reconciliation. Shadow failures are drop-silent per [CLAUDE.md rule §5](https://github.com/blamejs/blamejs/blob/main/CLAUDE.md) — the framework chain is authoritative and already committed; an unreachable shadow surfaces via `b.observability` as the `audit.shadow_failed` event but never crashes the request path. Composes with HIPAA §164.312(b) / PCI-DSS Req 10.5.3 (separation-of-duties retention) / SOX §404 / SEC 17a-4 WORM postures. Pass `null` or `{ record: null }` to unregister. **WebSocket permessage-deflate bomb fix:** `lib/websocket.js` `_inflateMessage` previously called `zlib.inflateRawSync` without `maxOutputLength` — a malicious peer could ship a small compressed frame that exploded into gigabytes BEFORE the framework's post-decompression `maxMessageBytes` check ran. The inflate now passes `maxOutputLength: this.maxMessageBytes` so zlib refuses mid-decompress; same CVE-2024-zlib / CVE-2025-0725 amplification class the `gunzip-without-output-size-cap` detector defends elsewhere. **New codebase-patterns detectors:** (1) `test-promise-settimeout-sleep` (scans the `test/` tree — first detector under the new test-scope walker — for the `await new Promise(r => setTimeout(r, N))` shape forbidden by [CLAUDE.md §11b](https://github.com/blamejs/blamejs/blob/main/CLAUDE.md), with the migration backlog pre-allowlisted as a release-gate countdown); (2) `inflate-unzip-without-output-size-cap` (extends the v0.10.15 gunzip-cap detector to `zlib.inflateSync` / `inflateRawSync` / `unzipSync` / `createInflate` family — RFC 1951 deflate is the same bomb class); (3) `map-get-falsy-then-set-pre-node-26` (companion to `map-has-then-set-pre-node-26` — catches the `!M.get(k)` / `M.get(k) === undefined|null` semantically-identical variants); (4) `fs-existssync-then-read-toctou` (CodeQL `js/file-system-race` class — `fs.existsSync(p) + fs.readFile(p)` against the same path is symlink-swap-vulnerable; the canonical defense is `lib/atomic-file.js`'s open-by-fd-first pattern); (5) `buffer-from-string-on-auth-path` (flags `Buffer.from(String(x))` in `lib/` — auth-bearing sites become `b.safeBytes` migration targets in the next release). **Shape-matcher substrate** lands at `test/helpers/_shape-match.js` (test-only, never ships — `test/` is absent from package.json `files:` allowlist): token-aware traversal that tracks paren / brace / bracket depth + string / template-literal / regex / comment state, exposing `findCalls(source, calleeRegex)` / `findEnclosingTry(source, pos)` / `aliasesOf(source, chainRegex)`. Future releases convert the highest-bypass-risk regex-only detectors to AST-aware variants using this substrate, closing the class of regex-bypass via variable renaming / parens / line splits that surface-pattern detectors miss. **References:** [RFC 7692 §7.2.2 WebSocket permessage-deflate](https://www.rfc-editor.org/rfc/rfc7692#section-7.2.2) · [HIPAA §164.312(b) Audit Controls](https://www.law.cornell.edu/cfr/text/45/164.312) · [PCI-DSS v4.0 Req 10](https://www.pcisecuritystandards.org/) · [SEC 17a-4 WORM](https://www.sec.gov/files/rules/final/34-44238.pdf) · [SOX §404](https://www.sec.gov/about/laws/soa2002.pdf) · [CVE-2024-zlib decompression amplification](https://nvd.nist.gov/) · [CVE-2025-0725](https://nvd.nist.gov/vuln/detail/CVE-2025-0725) · [CodeQL js/file-system-race](https://codeql.github.com/codeql-query-help/javascript/js-file-system-race/).
+
 - v0.11.3 (2026-05-19) — **SPF `a` and `mx` mechanism dispatch + smaller deferral-condition cleanups.** `b.mail.spf.verify` now evaluates the `a` and `mx` mechanisms per [RFC 7208 §5.3 + §5.4](https://www.rfc-editor.org/rfc/rfc7208), including the dual-cidr-length syntax (`a:foo.example/24//64`, `mx//64`). Senders publishing `v=spf1 mx -all` or `v=spf1 a -all` previously permerrored against this framework even though those are the second-most-common SPF mechanisms in fielded policies; verification now resolves the operator-supplied A / AAAA / MX records (via the existing `dnsLookup` callback contract — which is now honored for every record type, not only TXT) and matches the connecting IP under the parsed cidr. MX expansion is capped at the RFC §4.6.4 limit of 10 hosts (over-limit = permerror); each MX-host A/AAAA expansion counts toward the 10-lookup global ceiling and the 2-lookup void-lookup sub-limit. Empty digit segments in the dual-cidr-length grammar (`a/`, `a//`, `mx/`, `mx//`, `a/24//`) permerror with an explanatory message — RFC §5.3/§5.4 grammar requires `1*DIGIT` after each slash, and accepting empty would over-authorize senders publishing `v=spf1 a/ -all` (would match every IP in the /32 of every A record). The `exists` (RFC §5.7) and `ptr` (RFC §5.5) mechanisms remain deferred — `exists` needs macro-string expansion (RFC §7) to be usable in fielded policies, `ptr` is "strongly discouraged" by the RFC and rarely seen — and each now permerrors with an explanatory message naming the RFC section and a practical operator-side mitigation. `b.mail.crypto.smime` `@card` and the v1-only-emits-metadata comment in `lib/mail-crypto-smime.js` are corrected to reflect that sign + verify shipped in v0.10.16 on the `b.cms` substrate (EFAIL-class encrypt/decrypt remains the only deferred slice). `b.acme.create.revokeCert({ useCertKey: true })` and the `BAD UID <subverb>` IMAP listener response now carry explicit re-open conditions + named operator escape hatches alongside the deferral. **New codebase-patterns detector `slice1-optional-parseint-silent-default`** flags the class — any `.slice(1)` followed by an `if (X.length > 0)` guard around `parseInt(X, 10)` MUST sit in a file that also carries an explicit empty-segment refusal phrasing, so future cidr-length / prefix-length / port-range parsers inherit the discipline automatically. **References:** [RFC 7208 §5.3 a mechanism](https://www.rfc-editor.org/rfc/rfc7208#section-5.3) · [RFC 7208 §5.4 mx mechanism](https://www.rfc-editor.org/rfc/rfc7208#section-5.4) · [RFC 7208 §4.6.4 DNS-lookup limits](https://www.rfc-editor.org/rfc/rfc7208#section-4.6.4) · [RFC 8551 S/MIME 4.0](https://www.rfc-editor.org/rfc/rfc8551.html) · [RFC 9051 IMAP4rev2 §6.4.9 UID](https://www.rfc-editor.org/rfc/rfc9051#section-6.4.9).
 
 - v0.11.2 (2026-05-19) — **Node 26 floor-bump preparation.** Today's `engines.node` floor is `>=24.14.1` and the framework runs cleanly on Node 26 (which satisfies the floor). This release ships the **prep** scaffolding so the future floor-bump slice (when Node 26 promotes to Active LTS and `>=26.x` becomes the floor) is mechanical. **`b.backup.diskStorage(opts)`** is the new canonical name for the local-filesystem backup storage backend; `b.backup.localStorage(opts)` continues to work and emits a one-time deprecation warning via `b.deprecate.alias`, with removal scheduled for the next major. The rename avoids the Node 26 platform-level `localStorage` global naming collision; the deprecation path follows the framework's stable upgrade policy (one minor with deprecation warnings before removal). **New codebase-patterns detector `map-get-or-insert-pre-node-26`** flags the `if (!m.has(k)) m.set(k, factory()); m.get(k)` shape that Node 26's `Map.prototype.getOrInsertComputed(key, factory)` replaces in a single call. The detector lands as an allowlist marker — every existing call site in `lib/` is allowlisted with the spec file as the migration target; new code post-this-patch trips the gate. When the floor bumps the allowlist is walked + the detector flips to enforce. **`test/integration/pqc-pkcs8-forward-compat.test.js`** captures the ML-KEM-1024 / ML-DSA-65 / ML-DSA-87 / SLH-DSA-SHAKE-256f / Ed25519 PKCS8 export-byte shape on the current Node, asserts the sign+verify / encap+decap roundtrip via a re-imported KeyObject, and embeds a Node-26-shape fixture that re-imports every run — so the forward-compat contract is testable today and the reverse-direction (Node-26-exported → Node-24-imported) test follows the floor-bump. **SECURITY.md gains a "Node 26 compatibility" section** documenting the `localStorage` global naming collision (bare references in operator handler code now resolve to a Node global rather than throwing `ReferenceError`) and the ML-KEM / ML-DSA seed-only PKCS8 export shape (Node-24-sealed material re-imports cleanly on Node 26; new material from Node 26 is seed-only — parallel Node 24 readers of the same sealed disk need a one-time migration when the writer moves). README "Requirements" line gains the matching Node 26 note. **References:** [Node.js v26 release notes](https://nodejs.org/en/blog/release/v26.0.0) · [TC39 Map.getOrInsertComputed](https://github.com/tc39/proposal-upsert) · [RFC 8032 §5.1 Ed25519 context parameter](https://www.rfc-editor.org/rfc/rfc8032.html#section-5.1).

package/lib/audit.js

@@ -68,6 +68,33 @@ var { AuditSegregationError, ClusterError } = require("./framework-error");
 
 var log = boot("audit");
 
+// External shadow-store callbacks are bounded by the same hot-path
+// timeout the framework's own SQL paths use. A stalled operator
+// network call that neither resolves nor rejects MUST NOT block the
+// audit critical path — b.audit.record() must return, emit/safeEmit
+// drains must not stall behind it. On timeout the shadow record is
+// dropped (audit.shadow_timeout observability event) and the
+// framework chain row remains committed. CLAUDE.md rule §5 drop-
+// silent posture for hot-path observability sinks.
+var EXTERNAL_STORE_TIMEOUT_MS = C.TIME.seconds(30);
+
+// External shadow store registered via `b.audit.useStore({ record })`.
+// When set, every successful framework chain.append also fires
+// `_externalStore.record(rowResult)` so operators can replicate audit
+// records to an immutable external destination (AWS QLDB, Azure
+// Confidential Ledger, Google Cloud Audit Logs, an in-house WORM
+// appliance, a SIEM, etc.) WITHOUT giving up the framework's tamper-
+// evident chain integrity. The framework's chain remains authoritative;
+// the operator's record receives the fully-formed row (logical fields +
+// `_id` + `recordedAt` + `monotonicCounter` + `prevHash` + `rowHash`).
+//
+// Shadow failures are drop-silent (rule §5 — hot-path observability
+// sinks must not crash the path that emitted them). An audit-shadow
+// failure surfaces via `b.observability` as `audit.shadow_failed`; the
+// framework chain row still committed and downstream verifyChain still
+// works against the framework store.
+var _externalStore = null;
+
 // Per-operation timeout for framework-state SQL. A misbehaving
 // external-db driver hanging on a query shouldn't hang audit forever.
 // 30s is generous for genuinely slow networks while still bounding
@@ -451,11 +478,132 @@ async function record(event) {
         metadata:          event.metadata ? JSON.stringify(event.metadata) : null,
         requestId:         event.requestId || null,
       };
-      return _chainWriter.append(logical);
+      var appended = await _chainWriter.append(logical);
+      // Operator-registered shadow store: replicate the fully-formed
+      // row to an immutable external destination. Drop-silent on
+      // failure (rule §5) — the framework chain is authoritative and
+      // already committed; the shadow is a best-effort archival.
+      // The operator's record receives the SAME object the framework
+      // returns to its caller, so external consumers see identical
+      // hashes / counters / ids for cross-store reconciliation.
+      if (_externalStore && typeof _externalStore.record === "function") {
+        // Bound the operator-supplied callback so a stalled network
+        // call can't hang the audit critical path. Timeout, throw,
+        // and resolve paths all converge on the framework chain row
+        // staying durable — the shadow is best-effort archival.
+        try {
+          await safeAsync.withTimeout(
+            Promise.resolve().then(function () { return _externalStore.record(appended); }),
+            EXTERNAL_STORE_TIMEOUT_MS,
+            { name: "audit.shadowRecord" }
+          );
+        } catch (e) {
+          var isTimeout = e && (e.code === "ETIMEDOUT" || /timeout/i.test(e.message || ""));
+          try {
+            observability.event(isTimeout ? "audit.shadow_timeout" : "audit.shadow_failed", {
+              action:           appended.action,
+              monotonicCounter: appended.monotonicCounter,
+              error:            (e && e.message) || String(e),
+              timeoutMs:        isTimeout ? EXTERNAL_STORE_TIMEOUT_MS : undefined,
+            });
+          } catch (_obs) { /* drop-silent — observability is itself hot-path */ }
+        }
+      }
+      return appended;
     }
   );
 }
 
+/**
+ * @primitive b.audit.useStore
+ * @signature b.audit.useStore({ record })
+ * @since     0.11.4
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.audit.record, b.audit.safeEmit
+ *
+ * Register an operator-supplied shadow store for every audit chain
+ * append. The framework's tamper-evident chain remains authoritative
+ * (HIPAA §164.312(b) / PCI-DSS Req 10 / SOX-404 / ISO 27001 A.12.4.1
+ * posture preserved); the operator's `record(row)` async function is
+ * called AFTER each successful framework chain.append with the FULL
+ * appended row — `{ _id, recordedAt, monotonicCounter, prevHash,
+ * rowHash, action, outcome, actorUserId, ..., metadata }` — so
+ * external consumers see identical hashes for cross-store
+ * reconciliation.
+ *
+ * Typical use: replicate audit records to an immutable external
+ * destination (AWS QLDB / Azure Confidential Ledger / Google Cloud
+ * Audit Logs / an in-house WORM appliance / a SIEM forwarder).
+ * Operators in regulated industries often need their audit trail in
+ * a destination outside the application's own database for
+ * separation-of-duties (PCI-DSS Req 10.5.3) or independent retention
+ * (HIPAA §164.312(b) / SEC 17a-4 WORM).
+ *
+ * Failure posture: if the operator's `record` throws / rejects /
+ * times out (30s hard cap — a stalled network call MUST NOT block
+ * the audit critical path), the shadow failure is surfaced via
+ * `b.observability` as either `audit.shadow_failed` (throw/reject)
+ * or `audit.shadow_timeout` (cap exceeded) with `{ action,
+ * monotonicCounter, error, timeoutMs }` metadata, and the framework
+ * chain append still succeeds (the row is durable in the framework's
+ * own table; the shadow is a best-effort archival). This is the
+ * rule §5 drop-silent posture for hot-path observability sinks — an
+ * unreachable / hanging shadow MUST NOT crash or stall the request
+ * path that triggered the audit attempt.
+ *
+ * Call this once at boot, BEFORE the first `b.audit.record` /
+ * `b.audit.emit` / `b.audit.safeEmit`. Switching stores on a running
+ * app strands every prior audit row in the previous shadow store —
+ * the framework chain has them, but the new shadow doesn't unless
+ * the operator backfills.
+ *
+ * Pass `null` (or `{ record: null }`) to unregister and revert to
+ * chain-only mode.
+ *
+ * @opts
+ *   record:  async function (row),       // operator's persistence callback
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   await b.vault.init({ dataDir: "/var/lib/blamejs", mode: "plaintext" });
+ *   await b.db.init({ dataDir: "/var/lib/blamejs" });
+ *   b.audit.useStore({
+ *     record: async function (row) {
+ *       // Replicate to AWS QLDB / Azure Confidential Ledger / etc.
+ *       await externalLedger.append({
+ *         id:               row._id,
+ *         recordedAt:       row.recordedAt,
+ *         monotonicCounter: row.monotonicCounter,
+ *         prevHash:         row.prevHash,
+ *         rowHash:          row.rowHash,
+ *         action:           row.action,
+ *         outcome:          row.outcome,
+ *         metadata:         row.metadata,
+ *       });
+ *     },
+ *   });
+ *   // Every b.audit.* append now also lands in externalLedger.
+ */
+function useStore(store) {
+  if (store === null || store === undefined) {
+    _externalStore = null;
+    return;
+  }
+  if (typeof store !== "object") {
+    throw new Error("audit.useStore: store must be an object with a record(row) function, or null to unregister");
+  }
+  // `{ record: null }` unregisters explicitly (mirrors the null arg path).
+  if (store.record === null || store.record === undefined) {
+    _externalStore = null;
+    return;
+  }
+  if (typeof store.record !== "function") {
+    throw new Error("audit.useStore: store.record must be an async function (row) => void");
+  }
+  _externalStore = store;
+}
+
 // ---- Query ----
 //
 // Plain-field criteria translate into derived-hash equality where the column
@@ -911,6 +1059,7 @@ async function verify(opts) {
 
 function _resetForTest() {
   registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
+  _externalStore = null;
   db.reset();
   _chainWriter._resetForTest();
   // Drop pending buffered emits and cancel the age-flush timer on the
@@ -1500,6 +1649,7 @@ function activePosture() { return _activePosture; }
 module.exports = {
   registerNamespace:    registerNamespace,
   record:               record,
+  useStore:             useStore,
   emit:                 emit,
   safeEmit:             safeEmit,
   applyPosture:         applyPosture,

package/lib/websocket.js

@@ -603,10 +603,17 @@ function _deflateMessage(payload, windowBits) {
   return raw;
 }
 
-function _inflateMessage(payload, windowBits) {
+function _inflateMessage(payload, windowBits, maxOutputBytes) {
   // Per RFC 7692 §7.2.2, append the 4-byte trailer before inflating.
+  // `maxOutputBytes` MUST be bounded by the caller's per-message cap so
+  // a malicious peer can't ship a small deflated frame that explodes
+  // into gigabytes before the framework's downstream size-check sees
+  // the inflated bytes. CVE-2024-zlib + CVE-2025-0725 bomb class.
   var withTrailer = Buffer.concat([payload, DEFLATE_TRAILING]);
-  return zlib.inflateRawSync(withTrailer, { windowBits: windowBits });
+  return zlib.inflateRawSync(withTrailer, {
+    windowBits:     windowBits,
+    maxOutputLength: maxOutputBytes,
+  });
 }
 
 // ---- Frame parser ----
@@ -1065,8 +1072,13 @@ class WebSocketConnection extends EventEmitter {
     // CLOSE_INVALID_PAYLOAD per §5.6 / §6 of RFC 6455.
     if (wasCompressed) {
       try {
-        data = _inflateMessage(data, this._permessageDeflate.clientMaxWindowBits);
+        data = _inflateMessage(data, this._permessageDeflate.clientMaxWindowBits,
+                                this.maxMessageBytes);
       } catch (e) {
+        // RFC 6455 §7.4.1 / §5.6 — protocol-level decode failure
+        // (including bomb-cap overrun via maxOutputLength) returns
+        // CLOSE_INVALID_PAYLOAD. The over-cap case never allocates the
+        // exploded bytes — zlib's maxOutputLength refuses mid-inflate.
         return this._abort(CLOSE_INVALID_PAYLOAD,
           "permessage-deflate inflate failed: " + ((e && e.message) || String(e)));
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "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.6",
-  "serialNumber": "urn:uuid:b5450662-adf2-4f43-baef-731a1c66e80f",
+  "serialNumber": "urn:uuid:3a3e9e86-231c-4b20-b40a-2d58ef84de56",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-19T17:04:46.477Z",
+    "timestamp": "2026-05-19T19:19:53.073Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.3",
+      "bom-ref": "@blamejs/core@0.11.4",
       "type": "library",
       "name": "blamejs",
-      "version": "0.11.3",
+      "version": "0.11.4",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.3",
+      "purl": "pkg:npm/%40blamejs/core@0.11.4",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.3",
+      "ref": "@blamejs/core@0.11.4",
       "dependsOn": []
     }
   ]