@blamejs/core 0.13.28 → 0.13.29

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- 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.
 
 - v0.13.27 (2026-05-28) — **Documentation corrected across api-encrypt, mail-crypto, mail-store, and calendar.** A set of JSDoc corrections where the documented contract had drifted from the code. The most actionable: b.middleware.apiEncrypt's @opts named the keypair fields secretKey / ecSecretKey, but the middleware requires privateKey / ecPrivateKey (the shape b.crypto.generateEncryptionKeyPair returns), so a keypair built from the docs threw INVALID_KEYPAIR at construction; the same block documented a wrong custom-nonceStore interface and an example calling a non-existent b.crypto.keypair(). Also corrected: the b.mail.crypto facade and the PGP module described S/MIME sign/verify and PGP encrypt/decrypt/WKD as deferred when they ship and are live; b.mail.crypto.smime.checkCert documented a return shape whose field names did not match what it returns; and b.mailStore.create listed a destroy method it does not expose. No code behavior changed — only the docs were wrong. **Fixed:** *`b.middleware.apiEncrypt` options documented with the correct field names* — The `@opts` listed the keypair as `{ publicKey, secretKey, ecPublicKey, ecSecretKey }`, but the middleware requires `{ publicKey, privateKey, ecPublicKey, ecPrivateKey }` — the shape `b.crypto.generateEncryptionKeyPair()` returns — and threw `INVALID_KEYPAIR` for the documented shape. The custom `nonceStore` interface was documented as `{ has, add, prune }` but the middleware calls `{ checkAndInsert, purgeExpired, close }`, and the example called a non-existent `b.crypto.keypair()`. All three now match the implementation (`b.crypto.generateEncryptionKeyPair()`). · *`b.mail.crypto` S/MIME and PGP availability described accurately* — The `b.mail.crypto` facade said S/MIME `sign()` / `verify()` were deferred, and the PGP module's intro said in-process encrypt / decrypt and WKD discovery would 'ship in v0.10.14'. All of these are implemented and live (PGP encrypt/decrypt/WKD were promoted to the stable surface in v0.11.32; S/MIME sign/verify/verifyAll run on the `b.cms` substrate). The docs now describe them as available; the genuinely-deferred PGP v6-signature-packet support remains noted as deferred. · *`b.mail.crypto.smime.checkCert` return shape documented correctly* — The doc and example described the result as `{ subjectCN, issuerCN, validFrom, validTo, keyAlg, keyBits, sigAlg }`; the function returns `{ subject, issuer, validFrom, validTo, sigAlgName, sigAlgOid, keyType, fingerprint256 }` (full DN strings, no key-size field). The documented shape now matches. · *`b.mailStore.create` method list matches the returned handle* — The doc listed a `destroy` method the handle does not expose and omitted `search` / `moveMessages` / `hardExpunge` that it does. The list now reflects the actual methods. · *Smaller doc corrections* — `b.calendar` fromIcal / toIcal / validate now document that they also handle Task (VTODO), Note (VJOURNAL), and Group, not just Event. `b.middleware.requireAuth`'s `prefersJson` default is documented as Accept / X-Requested-With only (Content-Type is intentionally not a signal, as the module already noted). The default CSP nonce is 24 base64 chars (16 bytes), not 22. `b.mail.bimi`'s returned `evidenceDocument` is noted as echoed from the operator-supplied option rather than pulled from the certificate.

package/lib/middleware/age-gate.js

@@ -53,16 +53,20 @@ var AgeGateError = defineClass("AgeGateError", { alwaysPermanent: true });
  * Classifies the request against an operator-supplied age predicate
  * and applies COPPA / UK Children's Code / California AADC defaults
  * (no-store cache, no-referrer, X-Privacy-Posture header) for
- * below-threshold + unknown-age requests. When `requireAge` is set
- * and the request is below threshold without a parental-consent
- * record, refuses with HTTP 451. Every classification decision is
- * audited.
+ * below-threshold + unknown-age requests. `requireAge` is the hard
+ * legal floor: a request classified below threshold without a
+ * parental-consent record is refused with HTTP 451. It is evaluated
+ * within the consent classification, so it takes effect only when
+ * `consentRequired` is also set (that is what classifies a request as
+ * below-threshold); `requireAge` alone, with `consentRequired: null`,
+ * never classifies a request as below-threshold and so the 451 never
+ * fires. Every classification decision is audited.
  *
  * @opts
  *   {
  *     getAge:             function(req): number|null,  // required
- *     requireAge:         number|null,                  // 451 below this
- *     consentRequired:    number|null,                  // require consent below
+ *     requireAge:         number|null,                  // 451 floor; requires consentRequired set
+ *     consentRequired:    number|null,                  // require consent below; enables below-threshold classification
  *     hasParentalConsent: function(req): boolean,
  *     skipPaths:          string[],
  *     errorMessage:       string,

package/lib/middleware/ai-act-disclosure.js

@@ -60,7 +60,7 @@ var audit     = lazyRequire(function () { return require("../audit"); });
  *
  * @opts
  *   {
- *     kind:         "ai-interaction"|"deepfake"|"emotion-recognition"|"biometric-categorisation"|"synthetic-content",
+ *     kind:         "ai-interaction"|"ai-generated-content"|"emotion-recognition"|"biometric-categorisation"|"deep-fake"|"ai-text-public-interest",
  *     deployerName: string,
  *     policyUri:    string,
  *     mode:         "header"|"html",   // default "header"

package/lib/middleware/compose-pipeline.js

@@ -104,7 +104,7 @@ var CANONICAL_POSITIONS = Object.freeze({
 /**
  * @primitive b.middleware.composePipeline
  * @signature b.middleware.composePipeline(entries, opts?)
- * @since     0.9.44
+ * @since     0.9.43
  * @status    stable
  * @related   b.middleware.requestId, b.middleware.requireAuth, b.middleware.idempotencyKey
  *

package/lib/middleware/flag-context.js

@@ -34,7 +34,7 @@ var contextMod = lazyRequire(function () { return require("../flag-evaluation-co
  * @primitive b.middleware.flagContext
  * @signature b.middleware.flagContext(opts)
  * @since     0.1.0
- * @related   b.flagClient.getBoolean
+ * @related   b.flag.create
  *
  * Extracts an OpenFeature evaluation context onto `req.flagCtx` so
  * downstream handlers and multiple flag clients read a consistent

package/lib/queue.js

@@ -17,6 +17,18 @@
  *   and `nats` are listed as deferred and surface a clear error if
  *   selected.
  *
+ *   `local` and `redis` are driven by the generic `b.queue.consume`
+ *   loop and the lifecycle below (framework-side leasing, deterministic
+ *   backoff, DLQ, and the sweep timer). `sqs` is an SQS-native adapter
+ *   with a different model: `complete` / `fail` delete or re-deliver by
+ *   the message's `receiptHandle` (returned by `lease()`, threaded back
+ *   by the caller), and DLQ + visibility-expiry are handled server-side
+ *   by the SQS queue's RedrivePolicy — so `sqs` is driven directly
+ *   (lease → handle → complete/fail), not by `b.queue.consume`, and it
+ *   does not use the framework DLQ / sweep described below. See
+ *   `lib/queue-sqs.js` for its action map and the features that require
+ *   operator wiring.
+ *
  *   Job lifecycle:
  *     enqueued (status='pending', availableAt set by delaySeconds)
  *       ↓ availableAt reached + consumer leases
@@ -271,7 +283,11 @@ function enqueue(queueName, payload, opts) {
  * through `handler(job, ctx)`. Handler resolution marks the job
  * `done`; rejection bumps the attempt counter and either re-pends
  * with deterministic exponential backoff (1s base, 5min cap, no
- * jitter) or routes to the DLQ when `attempts >= maxAttempts`.
+ * jitter) or routes to the DLQ when `attempts >= maxAttempts`. This
+ * loop drives the `local` and `redis` backends; the `sqs` backend uses
+ * SQS-native receipt-handle complete/fail and server-side redrive and
+ * is driven directly rather than by this consumer (see the module
+ * intro).
  *
  * Returns a consumer state handle whose `.cancel()` aborts the poll
  * loop immediately (without waiting for the next `pollIntervalMs`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.28",
+  "version": "0.13.29",
   "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:23932d34-331e-44c1-9a55-5d959a713e9c",
+  "serialNumber": "urn:uuid:1b2ee4db-fd00-4369-8863-c2ad23ac201b",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-28T23:40:53.813Z",
+    "timestamp": "2026-05-29T00:21:21.126Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.28",
+      "bom-ref": "@blamejs/core@0.13.29",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.28",
+      "version": "0.13.29",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.28",
+      "purl": "pkg:npm/%40blamejs/core@0.13.29",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.28",
+      "ref": "@blamejs/core@0.13.29",
       "dependsOn": []
     }
   ]