@blamejs/core 0.13.21 → 0.13.23

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.13.20 (2026-05-27) — **`b.archive.wrap` can seal an archive for a tenant with no key-pair to manage — `recipient: "tenant"`.** b.archive.wrap previously sealed only to an explicit hybrid-PQC key-pair or a peer certificate; the documented recipient: "tenant" strategy threw. It now works: pass { recipient: "tenant", tenantId } and the archive is sealed under a deterministic per-tenant key derived from the vault root (SHAKE256 KDF) with XChaCha20-Poly1305, the tenant id mixed into the AEAD additional-authenticated-data so one tenant's envelope cannot be opened under another tenant's key. There is no recipient key-pair for the operator to generate, store, or rotate — b.archive.unwrap re-derives the key from the same tenantId. Rotating the vault re-keys every tenant (rotation intent is re-seal). The derivation is exposed directly as b.agent.tenant.derivedKey(tenantId, purpose) for operators who need the raw per-tenant key for their own AEAD. Requires an initialized vault. **Added:** *`b.archive.wrap` / `b.archive.unwrap` `recipient: "tenant"` — per-tenant archive sealing, no key-pair* — `b.archive.wrap(bytes, { recipient: "tenant", tenantId })` seals under a deterministic per-tenant key derived from the vault root with XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha-03) and a SHAKE256 KDF (FIPS 202); the tenant id is bound into the AEAD AAD so a tenant-A envelope cannot decrypt under tenant-B's key even if an attacker swaps envelope headers. `b.archive.unwrap(sealed, { recipient: "tenant", tenantId })` (or just `{ tenantId }`) re-derives the key and recovers the bytes — no recipient key-pair to manage. The tenant envelope carries a distinct version byte so it is never fed to the hybrid-KEM decrypt path. The static-key and peer-cert recipient strategies are unchanged. · *`b.agent.tenant.derivedKey(tenantId, purpose)` — direct per-tenant key derivation* — The deterministic, domain-separated per-tenant key derivation (vault root + tenantId + purpose, SHAKE256, NUL-separated) is now exported at the module level, returning a 64-char hex key. Previously reachable only as a method on a created tenant manager; operators who need the raw key for their own AEAD can now call it directly. Throws if the vault is not initialized.

package/lib/archive-read.js

@@ -51,6 +51,8 @@ var ArchiveReadError = defineClass("ArchiveReadError", { alwaysPermanent: true }
 var guardFilename = lazyRequire(function () { return require("./guard-filename"); });
 var guardArchive  = lazyRequire(function () { return require("./guard-archive"); });
 var safeDecompress = lazyRequire(function () { return require("./safe-decompress"); });
+var safeBuffer     = lazyRequire(function () { return require("./safe-buffer"); });
+var archiveAdapters = lazyRequire(function () { return require("./archive-adapters"); });
 
 // ---- Wire-format constants ------------------------------------------------
 // Aligned with the write-side `lib/archive.js`. APPNOTE.TXT § references
@@ -775,29 +777,31 @@ function zip(adapter, opts) {
  * @status    experimental
  * @related   b.archive.read.zip, b.archive.adapters.trustedStream
  *
- * Forward-scan-only ZIP reader for trusted Readable sources. No
- * central-directory comparison — operators reaching for this primitive
- * are declaring they own the producer (e.g. piping their own
- * `b.archive.zip().toStream()` output back into a reader for round-trip
- * verification).
+ * ZIP reader for a Readable source — pass `b.archive.adapters.trustedStream(readable)`
+ * instead of buffering the stream yourself. The bytes are collected
+ * into a size-capped buffer (1 GiB hard ceiling, like the tar
+ * trusted-stream reader) and then read through the same bomb-cap /
+ * path-traversal / entry-policy decode as the random-access reader, so
+ * `bombPolicy`, `guardProfile`, `entryTypePolicy`, and `audit` all
+ * apply. "Trusted" means the source size is bounded by the operator —
+ * the collection ceiling is the only guard against an unbounded
+ * producer; adversarial archives are still fully bomb-capped on decode.
  *
- * NOT YET IMPLEMENTED: the streaming LFH walker is not built —
- * `inspect()` / `entries()` / `extract()` throw
- * `archive-read/trusted-stream-*-deferred`, and `bombPolicy` / `audit`
- * are accepted but not yet honored. Re-opens when a streaming
- * consumer needs it. Until then, collect the stream into a buffer and
- * use the random-access reader, which is the supported path for both
- * trusted round-trip verification and adversarial input.
+ * The collection ceiling means this is not zero-buffer streaming (the
+ * whole archive is held in memory, capped); a future bounded-memory
+ * forward-inflate walker would lift that, shared with the tar reader.
  *
  * @opts
- *   bombPolicy:       { ... },   // reserved — not yet honored
- *   audit:            b.audit,   // reserved — not yet honored
+ *   bombPolicy:       { maxEntries, maxEntryDecompressedBytes,
+ *                       maxTotalDecompressedBytes, maxExpansionRatio },
+ *   entryTypePolicy:  { ... },
+ *   guardProfile:     "strict" | "balanced" | "permissive",
+ *   audit:            b.audit,
  *
  * @example
- *   // Supported path: buffer the stream, then read random-access.
- *   var bytes  = await someStreamToBuffer(producedZipStream);
- *   var reader = b.archive.read.zip(b.archive.adapters.buffer(bytes));
+ *   var reader  = b.archive.read.zip.fromTrustedStream(b.archive.adapters.trustedStream(readable));
  *   var entries = await reader.inspect();
+ *   void entries;
  */
 function fromTrustedStream(adapter, opts) {
   if (!adapter || adapter.kind !== "trusted-sequential") {
@@ -805,36 +809,45 @@ function fromTrustedStream(adapter, opts) {
       "fromTrustedStream: adapter must come from b.archive.adapters.trustedStream(readable)");
   }
   opts = opts || {};
-  var bombPolicy = _normalizeBombPolicy(opts.bombPolicy);
-  void bombPolicy;
-
-  // The streaming LFH walker is not built — only the API surface +
-  // adapter validation exist. Extraction via streaming inflate +
-  // data-descriptor scanning re-opens when a streaming consumer needs
-  // it; until then the supported path is to buffer the stream and use
-  // the random-access reader (which handles both trusted round-trip
-  // verification and adversarial input).
-  async function inspect() {
-    throw new ArchiveReadError("archive-read/trusted-stream-inspect-deferred",
-      "fromTrustedStream.inspect() is not implemented — collect the stream into a buffer and " +
-      "use b.archive.read.zip(b.archive.adapters.buffer(bytes))");
+
+  // Collect the Readable into a size-capped buffer once (tar-parity:
+  // boundedChunkCollector with a 1 GiB ceiling), then delegate to the
+  // random-access reader so the full bomb-cap / guard / audit decode
+  // applies. Lazy + memoized — construction stays cheap and the stream
+  // is consumed only on the first method call.
+  var readerPromise = null;
+  function _reader() {
+    if (!readerPromise) {
+      readerPromise = (async function () {
+        var collector = safeBuffer().boundedChunkCollector({
+          maxBytes:   C.BYTES.gib(1),
+          errorClass: ArchiveReadError,
+          sizeCode:   "archive-read/trusted-stream-too-large",
+        });
+        for await (var chunk of adapter.readable) { collector.push(chunk); }
+        return zip(archiveAdapters().buffer(collector.result()), opts);
+      })();
+    }
+    return readerPromise;
   }
 
+  async function inspect() { return (await _reader()).inspect(); }
   async function* entries() {
-    throw new ArchiveReadError("archive-read/trusted-stream-entries-deferred",
-      "fromTrustedStream.entries() is not implemented — collect into a buffer and use the random-access reader");
+    var r = await _reader();
+    for await (var e of r.entries()) { yield e; }
   }
-
-  async function extract() {
-    throw new ArchiveReadError("archive-read/trusted-stream-extract-deferred",
-      "fromTrustedStream.extract() is not implemented — collect into a buffer and use the random-access reader");
+  async function extract(extractOpts) { return (await _reader()).extract(extractOpts); }
+  async function* extractEntries(extractOpts) {
+    var r = await _reader();
+    for await (var e of r.extractEntries(extractOpts)) { yield e; }
   }
 
   return {
-    kind:    "zip-trusted-sequential",
-    inspect: inspect,
-    entries: entries,
-    extract: extract,
+    kind:           "zip-trusted-sequential",
+    inspect:        inspect,
+    entries:        entries,
+    extract:        extract,
+    extractEntries: extractEntries,
   };
 }
 

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.21",
+  "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:28562fda-52a1-4d96-ad78-e3c056763938",
+  "serialNumber": "urn:uuid:a0f54545-2664-4289-8bd2-f3db973d437a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-27T23:30:24.926Z",
+    "timestamp": "2026-05-28T08:15:53.205Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.21",
+      "bom-ref": "@blamejs/core@0.13.23",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.21",
+      "version": "0.13.23",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.21",
+      "purl": "pkg:npm/%40blamejs/core@0.13.23",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.21",
+      "ref": "@blamejs/core@0.13.23",
       "dependsOn": []
     }
   ]