@blamejs/core 0.13.30 → 0.13.31

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.31 (2026-05-28) — **Circuit-breaker onStateChange callback now fires; mcp / vault-aad doc corrections.** b.circuitBreaker documented an `onStateChange` callback (both an option and an `onStateChange(handler)` registration method) plus a state-change payload, but the callback was never invoked — only an observability event fired. The callback is now implemented: it fires on every transition with `{ name, from, to, at }`, the registration method works, and a non-function handler is rejected at construction. The same primitive's docs are corrected to name the real accessor (`getState()`, not `state()`) and drop a never-read `audit` option. Plus two doc-only corrections: b.mcp.toolResult.sanitize described composing b.guardHtml / b.ai.input.classify (it uses built-in detection) and documented a `classifyInput` option it never read; and b.vault.aad's prose said HKDF-SHAKE256 where the derivation is SHAKE256 (the AEAD AAD-binding itself is unchanged and sound). **Fixed:** *`b.circuitBreaker` onStateChange callback is invoked on every transition* — The `onStateChange` option and the `onStateChange(handler)` registration method are now wired: each registered handler is called with `{ name, from, to, at }` on every state transition (closed→open, open→half, half→closed/open), alongside the existing `breaker.state.change` observability event. A non-function `onStateChange` is rejected at construction. Previously the documented callback never fired. The docs are also corrected to name the real state accessor `getState()` (there is a `state` property, so `state()` was never a method) and to drop a never-read `audit` option. · *`b.mcp.toolResult.sanitize` documents its actual detection and options* — The prose said the sanitizer composes `b.guardHtml`'s strict profile and `b.ai.input.classify`; it uses built-in dangerous-HTML and prompt-injection-marker detection. The `@opts` also listed a `classifyInput` override the function never read. The prose now describes the built-in detection and the unwired `classifyInput` option is removed. The fail-closed refusal behavior (default `posture: "refuse"`) is unchanged. · *`b.vault.aad` derivation named correctly (SHAKE256)* — The module prose described the per-binding key derivation as HKDF-SHAKE256; it is SHAKE256 over the vault root concatenated with the binding inputs (no HKDF extract/expand). The AEAD AAD-binding to (table, row, column, schema version) — the file's actual security guarantee — is unchanged and sound; only the KDF name in the doc was wrong.
+
 - v0.13.30 (2026-05-28) — **Doc corrections in the safe-* parsers (defaults, an error code, an example, a status list).** Four documentation corrections in the safe-* input parsers; no code behavior changed. The parsers' enforced limits and controls are unchanged — these align the docs with what the code already does. b.safeMime.parse's documented default transfer-encoding allowlist listed `binary`, which is excluded by default (opt-in per RFC 3030 BINARYMIME). b.safeDecompress documented a refusal code (`output-too-large`) it never emits — an absolute-size bomb surfaces under `decompress-failed`. b.safeSmtp.findDotTerminator's example output was off by one. b.safeIcap's intro status-code summary omitted 404 / 405 / 408 (the detailed block already listed them). **Fixed:** *`b.safeMime.parse` documents the actual default transfer-encoding allowlist* — The `@opts` default listed `7bit/8bit/binary/qp/base64`, but `binary` is deliberately excluded by default (RFC 3030 BINARYMIME is opt-in); the default is `7bit/8bit/quoted-printable/base64`. The doc now matches, so operators don't expect inbound `Content-Transfer-Encoding: binary` parts to pass without opting in. · *`b.safeDecompress` names the real absolute-size-bomb refusal code* — The refusal-posture list documented `safe-decompress/output-too-large` for a bomb-by-absolute-size, but that code is never emitted — zlib's `maxOutputLength` throws before allocation and the failure surfaces as `safe-decompress/decompress-failed`. The doc now names the code an operator branching on the result will actually see (the ratio, output-byte, and compressed-input caps are unchanged and enforced). · *`b.safeSmtp.findDotTerminator` example output corrected* — The example claimed the `\r\n.\r\n` terminator in `"Hello world.\r\n.\r\n"` is at index 13; it is at index 12. The example now shows 12 (the implementation was already correct). · *`b.safeIcap` intro status-code summary lists 404 / 405 / 408* — The intro summary said only `100 / 200 / 204 / 400 / 403 / 5xx` are honored, but the parser also accepts `404 / 405 / 408` (legitimate RFC 3507 §4.3.3 codes, already listed in the detailed `parse` block). The intro summary now matches.
 
 - v0.13.29 (2026-05-28) — **Doc corrections: AI Act disclosure kind values, SQS queue model, age-gate coupling.** Documentation corrections. The most actionable: b.middleware.aiActDisclosure's @opts listed two EU AI Act transparency `kind` values (`deepfake` and `synthetic-content`) that the middleware does not accept, so they threw at construction; the accepted values use the hyphenated Art. 50 spellings (e.g. `deep-fake`) and include a text-public-interest variant the enum omitted — an operator copying the documented values crashed a compliance middleware at boot. The b.queue docs implied the SQS backend is driven by the generic b.queue.consume loop like local/redis; SQS is actually an SQS-native adapter (complete/fail by message receipt handle, server-side redrive) driven directly, and the docs now say so. b.middleware.ageGate's `requireAge` 451 floor is documented as taking effect only alongside `consentRequired` (it was silently inert without it). Plus a compose-pipeline @since and a flag-context @related correction. No code behavior changed. **Fixed:** *`b.middleware.aiActDisclosure` documents the accepted `kind` values* — The `@opts` listed `kind` as `ai-interaction | deepfake | emotion-recognition | biometric-categorisation | synthetic-content`. Two of those — `deepfake` and `synthetic-content` — are not accepted and threw at construction; the EU AI Act Art. 50 values use hyphenated spellings (e.g. `deep-fake`, the generated-content variant) and include `ai-text-public-interest`, which the documented enum omitted. The `@opts` now lists the full set the middleware accepts. · *`b.queue` SQS backend documented as SQS-native, not consume-driven* — The module docs implied the `sqs` backend is interchangeable with `local`/`redis` under the generic `b.queue.consume` loop. SQS is an SQS-native adapter: `complete` / `fail` act on the message's `receiptHandle` (returned by `lease()`, threaded back by the caller), and DLQ + visibility-expiry are handled server-side by the queue's RedrivePolicy. The docs now state that `sqs` is driven directly (lease → handle → complete/fail) rather than by `b.queue.consume`, and does not use the framework DLQ / sweep. · *`b.middleware.ageGate` documents the `requireAge` / `consentRequired` coupling* — `requireAge` (the HTTP 451 legal floor) is evaluated within the consent classification, so it takes effect only when `consentRequired` is also set — `requireAge` alone, with `consentRequired: null`, never classifies a request as below-threshold and the 451 never fires. The `@opts` and prose now state this coupling instead of presenting `requireAge` as a standalone threshold. · *Smaller doc corrections* — `b.middleware.composePipeline`'s `@since` is corrected to 0.9.43 (its actual ship version). `b.middleware.flagContext`'s `@related` pointed at a non-existent `b.flagClient.getBoolean`; it now references `b.flag.create`.

package/lib/circuit-breaker.js

@@ -36,8 +36,10 @@ var retryHelper = require("./retry");
  * Build a circuit-breaker. Returns a CircuitBreaker instance with
  * `wrap(fn)` (executes `fn` if the breaker is closed; throws an
  * `Error` with `code: "CIRCUIT_OPEN"` + `isObjectStoreError: true` +
- * `permanent: false` when open), `state()`, `reset()`, and
- * `onStateChange(handler)` listener registration. Pass-through
+ * `permanent: false` when open), `getState()`, `reset()`, and
+ * `onStateChange(handler)` listener registration (the handler, and the
+ * `onStateChange` opt, receive `{ name, from, to, at }` on every
+ * transition). Pass-through
  * factory: identical instance shape to `b.retry.CircuitBreaker`,
  * with the framework's `create(opts)` vocabulary.
  *
@@ -53,8 +55,8 @@ var retryHelper = require("./retry");
  *   failureThreshold: number,    // failures in the closed state before opening
  *   cooldownMs:       number,    // milliseconds the breaker stays open before probing
  *   successThreshold: number,    // probe successes required to close from half-open
- *   audit:            Object,    // optional b.audit instance for state-change emission
- *   onStateChange:    Function,  // ({ name, from, to, at }) → void
+ *   onStateChange:    Function,  // ({ name, from, to, at }) → void; also emits the
+ *                                //   `breaker.state.change` observability event
  *
  * @example
  *   var cb = b.circuitBreaker.create({

package/lib/mcp.js

@@ -399,10 +399,10 @@ function serverGuard(opts) {
  * exfiltration endpoints. The framework's defense:
  *
  *   - Strip / refuse executable HTML (`<script>` / `<iframe>` /
- *     `javascript:` URLs) — composes b.guardHtml's strict profile
+ *     `javascript:` URLs) via built-in dangerous-HTML detection
  *   - Refuse known prompt-injection markers ("ignore previous
  *     instructions", "system: you are now ...", role-claim prefixes)
- *     — composes b.ai.input.classify
+ *     via a built-in injection-marker matcher
  *   - Cap text length so a tool can't blow the host's context window
  *     out from under it
  *   - Refuse content with `image_url` / `audio_url` / `resource_link`
@@ -418,7 +418,6 @@ function serverGuard(opts) {
  *     posture?:        "refuse" | "sanitize" | "audit-only",  // default "refuse"
  *     maxTextBytes?:   number,    // default 64 KiB per content block
  *     allowedHosts?:   string[],  // for image/audio/resource_link refs
- *     classifyInput?:  fn(text)→{verdict, score} | null,      // default b.ai.input.classify
  *   }
  *
  * @example

package/lib/retry.js

@@ -187,6 +187,10 @@ function _validateBreakerOpts(name, opts) {
     throw new TypeError("retry.CircuitBreaker: successThreshold must be a positive integer, got " +
       typeof opts.successThreshold + " " + JSON.stringify(opts.successThreshold));
   }
+  if (opts.onStateChange != null && typeof opts.onStateChange !== "function") {
+    throw new TypeError("retry.CircuitBreaker: onStateChange must be a function, got " +
+      typeof opts.onStateChange);
+  }
 }
 
 // ---- Public surface ----
@@ -381,6 +385,19 @@ class CircuitBreaker {
     this.consecutiveFailures = 0;
     this.consecutiveSuccesses = 0;
     this.openedAt = 0;
+    this._stateListeners = [];
+    if (typeof merged.onStateChange === "function") this._stateListeners.push(merged.onStateChange);
+  }
+
+  // Register a state-change listener. Called with { name, from, to, at }
+  // on every transition (same payload the constructor's onStateChange
+  // opt receives). Returns this for chaining.
+  onStateChange(handler) {
+    if (typeof handler !== "function") {
+      throw new TypeError("retry.CircuitBreaker.onStateChange: handler must be a function, got " + typeof handler);
+    }
+    this._stateListeners.push(handler);
+    return this;
   }
 
   // Wrap an async function. The breaker observes outcomes and may fail-fast.
@@ -415,7 +432,16 @@ class CircuitBreaker {
   _transition(from, to) {
     if (from === to) return;
     this.state = to;
+    var at = Date.now();
     _emitEvent("breaker.state.change", 1, { name: this.name, from: from, to: to });
+    if (this._stateListeners.length > 0) {
+      var payload = { name: this.name, from: from, to: to, at: at };
+      for (var i = 0; i < this._stateListeners.length; i++) {
+        // Best-effort: a throwing listener must not derail the breaker's
+        // own state machine (the transition has already been applied).
+        try { this._stateListeners[i](payload); } catch (_e) { /* drop-silent */ }
+      }
+    }
   }
 
   _onSuccess() {

package/lib/vault-aad.js

@@ -35,8 +35,8 @@
  *   .isAadSealed(value) → boolean
  *
  * Per the framework's security-first stance:
- *   - Symmetric key derivation uses HKDF-SHAKE256 (matching the
- *     vault's KDF) over the vault root key concatenated with the
+ *   - Symmetric key derivation uses SHAKE256 (matching the vault's
+ *     KDF) over the vault root key concatenated with the
  *     canonicalized AAD.
  *   - AEAD: XChaCha20-Poly1305 with the AAD threaded into the tag.
  *   - 24-byte nonce, generated fresh per-seal via

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.30",
+  "version": "0.13.31",
   "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:1f064530-435e-44b8-9aad-0b35cd7d93b0",
+  "serialNumber": "urn:uuid:8b9568ba-9033-4b96-9ef8-bf087633e14d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T00:56:19.365Z",
+    "timestamp": "2026-05-29T01:34:10.018Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.30",
+      "bom-ref": "@blamejs/core@0.13.31",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.30",
+      "version": "0.13.31",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.30",
+      "purl": "pkg:npm/%40blamejs/core@0.13.31",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.30",
+      "ref": "@blamejs/core@0.13.31",
       "dependsOn": []
     }
   ]