@blamejs/core 0.13.29 → 0.13.31

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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`.
 
 - v0.13.28 (2026-05-28) — **Queue retry backoff now applies on the Redis backend; static-serve path-containment edge closed.** Two behavioral fixes plus doc corrections. The Redis queue backend silently discarded the documented retry backoff: b.queue.consume passes the delay as `{ retryDelayMs }` (the shape the local backend reads), but the Redis backend's fail() accepted only a bare-number third argument, so the object failed its numeric check and the delay was forced to 0 — a failing job re-leased immediately instead of waiting 1s/2s/4s/…, a retry storm under failure. The Redis backend now accepts the object form, so the exponential backoff applies as documented (verified by an integration test against real Redis). Separately, b.router.serveStatic's path-containment check used a bare string prefix, so a sibling directory whose name extends the root (root `/srv/public` vs `/srv/public-evil`) could pass; it now anchors on a path separator. Also: b.fileUpload now surfaces (via an observability counter) when a configured content-safety gate is skipped because an upload streamed past the reassembly cap, and documents that boundary; and b.cookies.parse's example output is corrected. **Fixed:** *Redis queue backend honors the documented retry backoff* — `b.queue.consume` re-pends a failed job with deterministic exponential backoff (1s base, 5min cap) by calling the backend's `fail()` with `{ retryDelayMs }`. The Redis backend's `fail()` accepted only a bare-number third argument, so the object failed its `typeof === "number"` check and the delay was reset to 0 — a failing job became immediately re-leasable, hot-looping instead of backing off. `fail()` now accepts both the object form (as the local backend does) and a bare number, so the backoff applies on Redis. An integration test against real Redis pins it. · *`b.router.serveStatic` path-containment anchors on a separator* — The containment check was `resolvedPath.startsWith(root)`, which a sibling directory sharing the root's name as a prefix (root `/srv/public` vs `/srv/public-evil`) could satisfy. It now requires the resolved path to equal `root` or start with `root + path.sep`, closing the sibling-prefix edge (`b.staticServe.create` remains the hardened serving path, with realpath + filename gating). · *`b.fileUpload` surfaces content-safety gate skips on oversized streamed uploads* — The byte-level content-safety gate inspects the reassembled buffer, so it runs on uploads up to `maxStreamReassemblyBytes` (default 64 MiB); a larger upload is handed to `onFinalize` as a stream and the byte-content gate is skipped (MIME-sniff and filename gates still run). That skip now emits a `fileUpload.content_safety_skipped_streamed` observability counter instead of passing silently, and the limit is documented. To guarantee content-gating of a type, cap `maxFileBytes` at or below `maxStreamReassemblyBytes`. · *`b.cookies.parse` example output corrected* — The example claimed `theme=%22dark%22` parses to `theme: "dark"`, but quote-stripping runs before percent-decoding, so the literal quotes survive. The example now uses `theme=dark%20mode` → `theme: "dark mode"`, which demonstrates percent-decoding without the quote-strip-ordering quirk.

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/safe-decompress.js

@@ -37,8 +37,9 @@
  *     - Any algorithm not in the allowlist (including operator-typo'd).
  *
  *   Refusal posture:
- *     - `safe-decompress/output-too-large`     — bomb-by-absolute-size
- *       (zlib's own `maxOutputLength` already refuses before alloc)
+ *     - `safe-decompress/decompress-failed`    — bomb-by-absolute-size
+ *       (zlib's own `maxOutputLength` refuses before alloc; the throw is
+ *       caught and surfaced under this code)
  *     - `safe-decompress/ratio-exceeded`       — expansion > `maxRatio`
  *       (zlib accepted the bytes; our post-decompress ratio check
  *       refuses, freeing the bytes immediately)

package/lib/safe-icap.js

@@ -37,8 +37,9 @@
  *       `\r\n`; intermediaries that accept bare-LF then desync against
  *       this parser).
  *     - **Status-code allowlist** — only `100` / `200` / `204` / `400`
- *       / `403` / 5xx are honored. RFC 3507 §4.3.3 enumerates these as
- *       the legal ICAP response codes; an unexpected `1xx` continuation
+ *       / `403` / `404` / `405` / `408` / 5xx are honored. RFC 3507
+ *       §4.3.3 enumerates these as the legal ICAP response codes; an
+ *       unexpected `1xx` continuation
  *       or `3xx` redirect is refused because it's a classic header-
  *       injection class (attacker smuggles `ICAP/1.0 100 X-Inject:`
  *       through a permissive proxy).

package/lib/safe-mime.js

@@ -125,7 +125,7 @@ var DEFAULT_TRANSFER_ENCODINGS = Object.freeze([
  *   maxBodyBytes:             number,     // default 25 MiB
  *   maxMessageBytes:          number,     // default 50 MiB
  *   charsetAllowlist:         string[],   // default UTF-8 / US-ASCII / common legacy 8-bit
- *   transferEncodingAllowlist: string[],  // default 7bit/8bit/binary/qp/base64
+ *   transferEncodingAllowlist: string[],  // default 7bit/8bit/quoted-printable/base64 (binary is opt-in, RFC 3030 BINARYMIME)
  *
  * @example
  *   var msg = b.safeMime.parse(messageBuffer);

package/lib/safe-smtp.js

@@ -61,7 +61,7 @@ var SafeSmtpError = defineClass("SafeSmtpError", { alwaysPermanent: true });
  * @example
  *   var body = Buffer.from("Hello world.\r\n.\r\n");
  *   b.safeSmtp.findDotTerminator(body);
- *   // → 13  (index of \r in \r\n.\r\n)
+ *   // → 12  (index of \r in the terminating \r\n.\r\n)
  *
  *   b.safeSmtp.findDotTerminator(Buffer.from("incomplete body"));
  *   // → -1

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.29",
+  "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:1b2ee4db-fd00-4369-8863-c2ad23ac201b",
+  "serialNumber": "urn:uuid:8b9568ba-9033-4b96-9ef8-bf087633e14d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T00:21:21.126Z",
+    "timestamp": "2026-05-29T01:34:10.018Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.29",
+      "bom-ref": "@blamejs/core@0.13.31",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.29",
+      "version": "0.13.31",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.29",
+      "purl": "pkg:npm/%40blamejs/core@0.13.31",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.29",
+      "ref": "@blamejs/core@0.13.31",
       "dependsOn": []
     }
   ]