@blamejs/core 0.13.22 → 0.13.23

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.23 (2026-05-28) — **Documentation corrected to match actual behavior across several primitives.** A set of JSDoc / doc-comment corrections where the documented contract had drifted from what the code does. No behavior changes — the implementations already behaved as now documented; only the docs were wrong. The most operator-relevant is the JWT signer doc: an expiring token signed without an explicit jti receives an auto-minted 128-bit jti (so the replay-defense path has the jti it needs), which the sign-opts doc previously denied. Also corrected: did.resolve's unsupported-method error now names did:jwk (always supported); b.cose.verify is marked stable to match its stable sign sibling and the CWT / EAT / SCITT / mdoc verifiers built on it; b.linkHeader.serialize's doc now states every parameter value is double-quoted; b.auth.saml verifyResponse's documented return shape now lists inResponseTo and issuer (both always returned); and the rate-limit custom-backend contract drops a gc member the middleware never invoked. **Fixed:** *JWT signer doc now describes the auto-minted jti on expiring tokens* — `b.auth.jwt.sign`'s opts doc claimed that omitting `jti` adds no jti. In fact, when a token carries an `exp` and no operator-supplied `jti`, the signer auto-mints a random 128-bit `jti` so a replay-protected token always carries the identifier `verify`'s replay store requires. The doc now describes this; pass an explicit `jti` for a deterministic value. Behavior is unchanged. · *`b.did.resolve` unsupported-method error now names did:jwk* — The thrown error for an unsupported DID method listed only `did:key` and `did:web`, omitting `did:jwk`, which `resolve` fully supports. The message now reads `(did:key, did:jwk, and did:web only)`. · *`b.cose.verify` marked stable* — `b.cose.verify` carried `@status experimental` while its `b.cose.sign` sibling is stable and the CWT / EAT / SCITT / mdoc verifiers that depend on it are stable and shipped. The verifier is the same maturity as the rest of the COSE_Sign1 round-trip; its status now reflects that. · *`b.linkHeader.serialize` doc matches its quoting behavior* — The doc said parameters are token-encoded when they fit RFC 7230 token grammar and double-quoted otherwise. The serializer always double-quotes every value (valid under RFC 8288, and required for space-separated multi-rel and media-type values). The doc now states that. · *`b.auth.saml` verifyResponse documented return shape lists all fields* — The prose and the example each omitted a different field that `verifyResponse` always returns. The documented shape now lists all of `nameId`, `nameIdFormat`, `sessionIndex`, `attributes`, `audience`, `inResponseTo`, and `issuer`. · *rate-limit custom-backend contract is `{ take, reset }`* — The custom-backend opts doc listed a `gc` member that the middleware never reads or invokes (the runtime contract is `take` / `reset` / `close`, and the error message already said `{ take, reset }`). The documented shape now matches; an operator-supplied `gc` was always silently ignored. · *`b.mail.agent.create` doc no longer lists consumer as a method* — The created agent's method list named `consumer`, which is not a method on the returned object — the queue consumer is the sibling export `b.mail.agent.consumer`. The doc now says so.
+
 - v0.13.22 (2026-05-27) — **`b.archive.read.zip.fromTrustedStream` reads a ZIP from a Readable — no longer an experimental stub.** fromTrustedStream was an experimental stub whose inspect / entries / extract methods threw, forcing callers to buffer the stream themselves and use the random-access reader. It now works, with the same shape as the tar trusted-stream reader: pass b.archive.adapters.trustedStream(readable) and the bytes are collected into a size-capped buffer (1 GiB hard ceiling) and read through the same bomb-cap, path-traversal, and entry-type decode as the random-access reader — so bombPolicy, guardProfile, entryTypePolicy, and audit all apply, and inspect / entries / extract / extractEntries all return data. This is a bounded-memory reader (the archive is held in memory under the ceiling), not zero-buffer streaming; a future forward-inflate walker shared with the tar reader would lift the ceiling. **Added:** *`b.archive.read.zip.fromTrustedStream` now reads — `inspect` / `entries` / `extract` / `extractEntries`* — The ZIP trusted-stream reader is implemented (was an experimental stub that threw). Pass `b.archive.adapters.trustedStream(readable)` to read a ZIP straight from a Node Readable without buffering it yourself. The stream is collected into a size-capped buffer (1 GiB ceiling, matching `b.archive.read.tar`'s trusted-stream reader) and decoded through the same adversarial-safe path as the random-access reader, so `bombPolicy` / `guardProfile` / `entryTypePolicy` / `audit` are honored on decode. Adversarial archives remain fully bomb-capped; "trusted" refers only to the source-size bound. A non-trusted-stream adapter is refused with `archive-read/bad-adapter`.
 
 - v0.13.21 (2026-05-27) — **`b.cose.exportKey` — serialize a public key as a COSE_Key, the inverse of `b.cose.importKey`.** b.cose could import a COSE_Key (RFC 9052 §7) into a node:crypto key for verification, but had no way to produce one — so a key used with b.cose.sign could not be shipped to a verifier in COSE form without hand-building the CBOR map. b.cose.exportKey(keyObject, opts?) closes the round-trip: it serializes an EC2 (P-256 / P-384 / P-521) or OKP (Ed25519) public key as the CBOR-encoded COSE_Key map, with optional alg and kid common parameters. A private key has its public half exported; unsupported curves / key types are refused rather than emitting a COSE_Key no verifier here would accept. The bytes round-trip through b.cose.importKey, and feed the mdoc MSO / COSE_Key header / SCITT / C2PA verification-key paths. **Added:** *`b.cose.exportKey(keyObject, { alg?, kid? })` — KeyObject → COSE_Key (RFC 9052 §7)* — Serialize a `node:crypto` public key as the CBOR-encoded COSE_Key map — the inverse of `b.cose.importKey`. Supports EC2 (P-256 / P-384 / P-521) and OKP (Ed25519), the same key types `b.cose.verify` accepts; `opts.alg` (e.g. `"ES256"`) and `opts.kid` populate the COSE_Key alg (label 3) and kid (label 2) common parameters. A private key exports its public half; unsupported curves / key types throw rather than producing a COSE_Key no verifier would accept. `b.cose.importKey(b.cbor.decode(exportKey(k)))` round-trips, so a key signed with `b.cose.sign` can be shipped to a verifier as bytes — the mdoc MSO / COSE_Key header / SCITT / C2PA verification-key paths.

package/lib/archive-wrap.js

@@ -370,7 +370,7 @@ function sniffEnvelope(bytes) {
  * @signature b.archive.wrapWithPassphrase(bytes, opts)
  * @since     0.12.11
  * @status    stable
- * @related   b.archive.unwrapWithPassphrase, b.archive.wrap, b.backupCrypto
+ * @related   b.archive.unwrapWithPassphrase, b.archive.wrap
  *
  * Wrap archive bytes in a passphrase-derived envelope. The envelope
  * wire format is the framework's standard Argon2id (RFC 9106) +

package/lib/auth/jwt.js

@@ -48,10 +48,13 @@
  *   subject:      claims.sub override
  *   expiresInSec: relative exp (claims.exp = now + expiresInSec)
  *   notBeforeSec: relative nbf (claims.nbf = now + notBeforeSec)
- *   jti:          claims.jti override (string; if missing, no jti is added —
- *                  the framework doesn't auto-mint without an operator request
- *                  since jti has uniqueness/replay-tracking semantics that
- *                  belong at the application layer)
+ *   jti:          claims.jti override (string). When omitted, a random
+ *                  128-bit jti is auto-minted if (and only if) the token
+ *                  carries an exp — so a replay-protected token always
+ *                  has the jti the verifier's replay store requires,
+ *                  closing the silent hole where a sign without jti would
+ *                  never replay-protect. Pass an explicit jti for a
+ *                  deterministic value.
  *   now:          test-time clock injection (epoch milliseconds)
  *
  * Verify opts:

package/lib/auth/saml.js

@@ -415,7 +415,7 @@ function create(opts) {
    * (Response-level OR Assertion-level signature), the assertion's
    * SubjectConfirmation Bearer constraints, and Conditions audience
    * + time bounds. Returns `{ nameId, nameIdFormat, sessionIndex,
-   * attributes, audience, inResponseTo }`.
+   * attributes, audience, inResponseTo, issuer }`.
    *
    * @opts
    *   {
@@ -428,7 +428,7 @@ function create(opts) {
    *     var info = sp.verifyResponse(req.body.SAMLResponse, {
    *       expectedInResponseTo: req.session.samlRequestId,
    *     });
-   *     // → { nameId, nameIdFormat, sessionIndex, attributes, audience, issuer }
+   *     // → { nameId, nameIdFormat, sessionIndex, attributes, audience, inResponseTo, issuer }
    *   });
    */
   function verifyResponse(samlResponseB64, vopts) {

package/lib/cose.js

@@ -227,7 +227,7 @@ async function sign(payload, opts) {
  * @primitive b.cose.verify
  * @signature b.cose.verify(coseSign1, opts)
  * @since     0.12.33
- * @status    experimental
+ * @status    stable
  * @related   b.cose.sign, b.cbor.decode
  *
  * Verify a COSE_Sign1 (RFC 9052) and return its payload + headers.

package/lib/did.js

@@ -365,7 +365,7 @@ function resolve(did, opts) {
     return { didDocument: docW, verificationMethods: _extractVerificationMethods(docW) };
   }
 
-  throw new DidError("did/unsupported-method", "did.resolve: unsupported DID method '" + parsed.method + "' (did:key and did:web only)");
+  throw new DidError("did/unsupported-method", "did.resolve: unsupported DID method '" + parsed.method + "' (did:key, did:jwk, and did:web only)");
 }
 
 // Import a publicKeyJwk after allowlisting its kty/crv — a DID document

package/lib/link-header.js

@@ -125,8 +125,9 @@ function _serParam(name, value) {
  * Build an HTTP <code>Link</code> header value from an array of
  * <code>{ uri, rel, params? }</code> (or a single such object). The URI
  * is angle-bracketed, <code>rel</code> (string or array) is emitted
- * first, and parameters are token-valued when they fit RFC 7230 token
- * grammar or double-quoted otherwise. Useful for emitting standard REST
+ * first, and every parameter value is double-quoted (always valid under
+ * RFC 8288, and required for space-separated multi-rel and media-type
+ * values like <code>text/html</code>). Useful for emitting standard REST
  * pagination links.
  *
  * @example

package/lib/mail-agent.js

@@ -156,8 +156,10 @@ var COMPOSE_HINT = Object.freeze({
  * @related   b.mailStore, b.mail.agent.consumer
  *
  * Create the agent facade. Returns an object with read / write / sieve
- * / identity / mdn / export / import / consumer methods. Reads stay
- * synchronous-shaped via promises; writes audit on completion.
+ * / identity / mdn / export / import methods. Reads stay
+ * synchronous-shaped via promises; writes audit on completion. (The
+ * queue consumer is the sibling export <code>b.mail.agent.consumer</code>,
+ * not a method on this object.)
  *
  * @opts
  *   store:        b.mailStore instance,    // required

package/lib/middleware/rate-limit.js

@@ -36,7 +36,7 @@
  *     header:          true                    // set X-RateLimit-* response headers
  *     skipPaths:       []                      // string-prefix or regex matchers
  *     scope:           'global' | 'per-route'  (default 'global')
- *     backend:         'memory' (default) | 'cluster' | { take, reset, gc? }
+ *     backend:         'memory' (default) | 'cluster' | { take, reset }
  *     algorithm:       'token-bucket' (default) | 'fixed-window'
  *                                              // memory backend only; ignored
  *                                              // for cluster backend (which is
@@ -366,7 +366,7 @@ function _resolveBackend(opts) {
  *     header:          boolean,          // default true
  *     skipPaths:       Array<string|RegExp>,
  *     scope:           "global"|"per-route",
- *     backend:         "memory"|"cluster"|{ take, reset, gc },
+ *     backend:         "memory"|"cluster"|{ take, reset },
  *     algorithm:       "token-bucket"|"fixed-window",
  *     burst:           number,
  *     refillPerSecond: number,

package/lib/tsa.js

@@ -183,7 +183,8 @@ function buildRequest(data, opts) {
     nonce = Buffer.isBuffer(opts.nonce) ? opts.nonce : nodeCrypto.randomBytes(8);  // allow:raw-byte-literal — RFC 3161 nonce: 64-bit random
     children.push(asn1.writeInteger(nonce));
   }
-  // certReq DEFAULT FALSE — only encode when true (the default we want).
+  // certReq DEFAULTS TRUE (RFC 3161 §2.4.1) — encode the boolean unless
+  // the caller explicitly opts out with certReq:false.
   var certReq = opts.certReq !== false;
   if (certReq) children.push(asn1.writeBoolean(true));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.22",
+  "version": "0.13.23",
   "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:81d23e48-6a96-4d2b-ac47-bada0b15cf1f",
+  "serialNumber": "urn:uuid:a0f54545-2664-4289-8bd2-f3db973d437a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-28T00:00:09.259Z",
+    "timestamp": "2026-05-28T08:15:53.205Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.22",
+      "bom-ref": "@blamejs/core@0.13.23",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.22",
+      "version": "0.13.23",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.22",
+      "purl": "pkg:npm/%40blamejs/core@0.13.23",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.22",
+      "ref": "@blamejs/core@0.13.23",
       "dependsOn": []
     }
   ]