@blamejs/pki 0.5.16 → 0.5.17

package/CHANGELOG.md

@@ -4,7 +4,22 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.5.16 — 2026-08-20
+## v0.5.17 — 2026-08-20
+
+A failed integrity check destroys the plaintext it recovered, AuthEnvelopedData validates the attributes it is asked to authenticate, and every refusal names the rule it is actually applying.
+
+### Changed
+
+- The refusals for a content cipher in the wrong container now cite the rule they apply. RFC 5083 sec. 2 defines `AuthEnvelopedData` in terms of a content-authenticated-encryption algorithm; it never names GCM, and RFC 5084 sec. 3.1 defines AES-CCM for that content type. Saying the standard required GCM sent an operator to argue with a specification that says the opposite. The check now draws the line the RFC draws -- authenticated versus not -- and an AES-CCM message is declined separately, by name, as an algorithm this toolkit does not implement rather than as an unrecognized OID. Error codes are unchanged.
+- Documentation pages at pkijs.com carry the expanded name of the format they describe in the title and heading, so a page about CMS says Cryptographic Message Syntax rather than three letters that mean a content management system elsewhere. The sitemap now reports each page's real last-changed date, taken from the commit that last touched the source it is generated from, and omits the date where it is unknown instead of reporting the build time. The home page gained runnable examples for the six things people most often arrive wanting to do.
+
+### Fixed
+
+- A failed AEAD integrity check now destroys the plaintext it recovered. `update` returns the complete recovered plaintext and `final` is what decides whether the message was authentic at all, so on a forged `AuthEnvelopedData` the plaintext existed in full before anything had judged it, and the buffer was then dropped unreferenced and unzeroed. RFC 5083 sec. 1 requires it to be destroyed. The success path leaked too, less visibly: joining the two halves copies them, leaving the first buffer as a second complete copy of the plaintext that the caller never receives and nothing else would ever clear. Both exits are now cleared, at every cipher the toolkit runs -- CMS content decryption and the RFC 3211 password-recipient unwrap, PBES2, HPKE `open`, PKCS#12 safe decryption, and the AES-GCM, AES-CBC, AES-CTR and AES-KW paths of the WebCrypto engine.
+- `pki.cms.encrypt` validates the authenticated attributes a caller supplies for an `AuthEnvelopedData` before it MACs them. Each must be a well-formed `Attribute SEQUENCE { type, non-empty SET OF value }` with no repeated type (RFC 5652 sec. 5.3). `AuthenticatedData` had enforced this all along; `AuthEnvelopedData` accepted whatever it was handed and emitted it, so a malformed attribute reached the wire with the MAC already computed over it and the operator learned of it from a peer's parser rather than from the builder.
+- `pki.cms.encrypt` refuses a `message-digest` attribute in an `AuthEnvelopedData`'s `authAttrs`. Its value is the unencrypted one-way hash of the plaintext, so disclosing it alongside the ciphertext enables content tracking and confirms a guessed plaintext against a message that was encrypted to prevent exactly that (RFC 5083 sec. 2.1 and sec. 5). Decryption still accepts one, since another implementation may legitimately emit it; the toolkit will not produce one. `AuthenticatedData` is unaffected -- it builds and MACs its own `message-digest` by design (RFC 5652 sec. 9.2).
+
+## v0.5.16 — 2026-08-19
 
 `pki.cmp.verify` reads every option at the call, and every guard takes what it needs from the runtime when it loads, so code a caller runs afterwards cannot change what a verification decides.
 

package/lib/acme.js

@@ -5,6 +5,7 @@
  * @module     pki.acme
  * @nav        Protocols
  * @title      ACME
+ * @fullname   ACME (RFC 8555) certificate issuance
  * @order      20
  * @slug       acme
  *

package/lib/asn1-der.js

@@ -5,6 +5,7 @@
  * @module     pki.asn1
  * @nav        Core
  * @title      ASN.1 / DER
+ * @fullname   ASN.1 and DER: a strict encoder and decoder
  * @order      30
  * @featured   true
  * @slug       asn1

package/lib/attrcert-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.attrcert
  * @nav        Signing
  * @title      Attribute certificates
+ * @fullname   X.509 attribute certificates (RFC 5755)
  * @intro The RFC 5755 attribute-certificate producing side. `pki.attrcert.sign` builds an
  *   `AttributeCertificateInfo` binding a Holder to a set of privilege attributes (role, clearance,
  *   group, ...) over a validity window, signs it with an Attribute Authority's private key, and emits an

package/lib/cbor-det.js

@@ -5,6 +5,7 @@
  * @module     pki.cbor
  * @nav        Core
  * @title      CBOR (deterministic)
+ * @fullname   Deterministic CBOR encoding and decoding (RFC 8949)
  * @order      35
  * @slug       cbor
  *

package/lib/cmc-verify.js

@@ -5,6 +5,7 @@
  * @module     pki.cmc
  * @nav        Enrollment
  * @title      CMC
+ * @fullname   CMC (Certificate Management over CMS, RFC 5272)
  * @intro Interpret an RFC 5272 Full PKI Response. `verify(response, sent)` takes the response
  *   a CA returned and the state the client retained from its request, binds the two together
  *   (transaction identifier, the Sender/Recipient Nonce echo, the Data Return echo), reads the

package/lib/cmp-build.js

@@ -6,6 +6,7 @@
  * @module     pki.cmp
  * @nav        Signing
  * @title      Certificate management protocol messages
+ * @fullname   CMP (Certificate Management Protocol, RFC 4210)
  * @intro The RFC 9810 Certificate Management Protocol producing side. `pki.cmp.build` assembles a
  *   `PKIMessage` -- a `PKIHeader` (sender / recipient / transaction metadata), a `PKIBody` carrying one
  *   request or transaction (an `ir` / `cr` / `kur` certificate request via `pki.crmf.build`, a `p10cr`

package/lib/cms-decrypt.js

@@ -29,6 +29,10 @@ var subtle = webcrypto.webcrypto.subtle;
 var CmsError = frameworkError.CmsError;
 var WRAP_KEK_LENGTHS = schemaCms.WRAP_KEK_LENGTHS;
 var KEM_CT_LENGTHS = schemaCms.KEM_CT_LENGTHS;
+// The parser's own AEAD table: the single place that decides whether a content-encryption OID names
+// an authenticated encryption algorithm, so the container-vs-mode rule below cannot drift from the
+// parameter validation that accepted the message.
+var AEAD_ALGS = schemaCms.AEAD_ALGS;
 
 function O(n) { return oid.byName(n); }
 function _err(code, message, cause) { return new CmsError(code, message, cause); }
@@ -397,26 +401,45 @@ async function _kemriCek(ri, km) {
 }
 
 // The declared cipher MODE must match the container's authentication model: an AEAD cipher belongs in
-// AuthEnvelopedData and a plain CBC cipher in EnvelopedData (RFC 5083 sec. 2.1 / RFC 5084 sec. 3). Key
-// length alone does not separate them, so without this an EnvelopedData naming AES-GCM was opened as
-// unauthenticated CBC while the result still reported the AEAD algorithm, telling the caller the
-// content was authenticated when nothing had authenticated it. The mirror case dereferenced AEAD
-// parameters the parser leaves null for a non-AEAD algorithm, faulting instead of failing closed.
-// An unresolvable OID is left to _openContent, which names it as the unsupported algorithm it is.
+// AuthEnvelopedData and a plain CBC cipher in EnvelopedData (RFC 5083 sec. 2). Key length alone does
+// not separate them, so without this an EnvelopedData naming AES-GCM was opened as unauthenticated CBC
+// while the result still reported the AEAD algorithm, telling the caller the content was authenticated
+// when nothing had authenticated it. The mirror case dereferenced AEAD parameters the parser leaves
+// null for a non-AEAD algorithm, faulting instead of failing closed.
+//
+// The line drawn here is AEAD-vs-not, which is the line RFC 5083 draws. GCM-vs-CBC is a narrower
+// line this toolkit draws, because AES-GCM is the only AEAD it implements, and stating the narrower
+// one as though the RFC required it sends an operator to argue with a specification that says the
+// opposite: RFC 5084 sec. 3.1 defines AES-CCM for this content type. So an AEAD reaching the right
+// container passes here even when decryption will later decline it, and it is _openContent that says
+// why, by name. An unresolvable OID is left to _openContent too, as the unsupported algorithm it is.
 function _assertContentCipherMode(eci, ct) {
   var oidStr = eci.contentEncryptionAlgorithm.oid;
-  if (!CONTENT_MODE[oidStr]) return;
-  var wantMode = ct === "authEnvelopedData" ? "gcm" : "cbc";
-  if (CONTENT_MODE[oidStr] !== wantMode) {
-    throw _err("cms/unsupported-algorithm", "contentEncryptionAlgorithm " + oidStr + " is not a " + wantMode.toUpperCase() + " cipher, which " + ct + " requires (RFC 5083 sec. 2.1 / RFC 5084 sec. 3)");
+  var isAead = guard.intrinsic.hasOwn(AEAD_ALGS, oidStr);
+  if (!isAead && !guard.intrinsic.hasOwn(CONTENT_MODE, oidStr)) return;
+  if (ct === "authEnvelopedData") {
+    if (isAead) return;
+    throw _err("cms/unsupported-algorithm", "contentEncryptionAlgorithm " + oidStr + " is not an authenticated encryption algorithm, which authEnvelopedData requires (RFC 5083 sec. 2)");
   }
+  if (!isAead) return;
+  throw _err("cms/unsupported-algorithm", "contentEncryptionAlgorithm " + oidStr + " is an authenticated encryption algorithm, which belongs in an authEnvelopedData rather than a " + ct + " (RFC 5083 sec. 2)");
 }
 
 // ---- stage 3: open the content (uniform failure) ---------------------------
 async function _openContent(parsed, eci, cek, ct) {
   var alg = eci.contentEncryptionAlgorithm;
-  var keyBits = CONTENT_KEYBITS[alg.oid];
-  if (!keyBits) throw _err("cms/unsupported-algorithm", "unsupported contentEncryptionAlgorithm " + alg.oid);
+  var keyBits = guard.intrinsic.hasOwn(CONTENT_KEYBITS, alg.oid) ? CONTENT_KEYBITS[alg.oid] : 0;
+  if (!keyBits) {
+    // AES-CCM parses completely here -- registered OIDs, the sec. 3.1 nonce bound, the seven legal
+    // ICV lengths -- and is then declined, because AES-GCM is the only AEAD this toolkit implements
+    // for content encryption. Saying only "unsupported <oid>" is what an operator also sees for an
+    // OID nothing in the toolkit recognizes, and the two call for different things: one is a
+    // capability gap to route around, the other is a malformed or exotic message.
+    if (guard.intrinsic.hasOwn(AEAD_ALGS, alg.oid) && AEAD_ALGS[alg.oid] === "ccm") {
+      throw _err("cms/unsupported-algorithm", "contentEncryptionAlgorithm " + alg.oid + " is AES-CCM. RFC 5084 sec. 3.1 permits it for this content type; this toolkit implements AES-GCM only for content encryption");
+    }
+    throw _err("cms/unsupported-algorithm", "unsupported contentEncryptionAlgorithm " + alg.oid);
+  }
   if (eci.encryptedContent == null) throw _err("cms/no-encrypted-content", "the message has no encryptedContent (detached; supply it out of band)");
   // A null CEK (v1.5 implicit rejection) or a wrong-length CEK -> a fresh random key of the right
   // length, so the failure surfaces here as the uniform verdict, never earlier.
@@ -435,7 +458,7 @@ async function _openContent(parsed, eci, cek, ct) {
     }
     var iv = asn1.read.octetString(asn1.decode(alg.parameters));
     if (iv.length !== 16) throw _fail();
-    return pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits);
+    return pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits, CmsError, "cms/decrypt-failed");
   } catch (e) {
     if (e instanceof CmsError && e.code !== "cms/decrypt-failed") throw e;
     throw _fail();
@@ -450,7 +473,10 @@ function _gcmOpen(cek, nonce, ct, tag, aad, keyBits, icvLen) {
   var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-gcm", cek, nonce, { authTagLength: icvLen });
   d.setAuthTag(tag);
   if (aad && aad.length) d.setAAD(aad);
-  return Buffer.concat([d.update(ct), d.final()]); // final() throws on tag mismatch -> uniform
+  // final() throws on a tag mismatch, and update() has already produced the whole plaintext by
+  // then. RFC 5083 sec. 1 requires a receiver whose integrity check fails to DESTROY the plaintext,
+  // not merely withhold it, so the intermediate is cleared on both exits.
+  return guard.secret.cipherFinish(d, ct, CmsError, "cms/decrypt-failed", "the recovered content");
 }
 
 // ---- EncryptedData (sec. 8) ------------------------------------------------
@@ -465,7 +491,7 @@ async function _decryptEncryptedData(parsed, km, opts) {
   var cek = guard.bytes.view(km.cek, CmsError, "cms/bad-input", "cek");
   if (cek.length !== keyBits / 8) throw _err("cms/bad-input", "the supplied cek length does not match the content algorithm");
   var iv = asn1.read.octetString(asn1.decode(alg.parameters));
-  try { return _originFields({ content: pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "cek", recipientIndex: -1, contentEncryptionAlgorithm: alg.name || alg.oid, authenticated: false }, null, null); }
+  try { return _originFields({ content: pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits, CmsError, "cms/decrypt-failed"), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "cek", recipientIndex: -1, contentEncryptionAlgorithm: alg.name || alg.oid, authenticated: false }, null, null); }
   catch (_e) { throw _fail(); }
 }
 async function _decryptPbes2(parsed, eci, km, opts) {
@@ -497,7 +523,7 @@ async function _decryptPbes2(parsed, eci, km, opts) {
   var key;
   try { key = nodeCrypto.pbkdf2Sync(pwE.bytes, pb.salt, pb.iterations, keyBits / 8, pb.prfNode); }
   finally { if (pwE.owned) guard.secret.zeroize(pwE.bytes, CmsError, "cms/bad-input", "the password encoding"); }
-  try { return _originFields({ content: pbes2.cbcDecrypt(key, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "password", recipientIndex: -1, contentEncryptionAlgorithm: oid.name(encOid) || encOid, authenticated: false }, null, null); }
+  try { return _originFields({ content: pbes2.cbcDecrypt(key, iv, eci.encryptedContent, keyBits, CmsError, "cms/decrypt-failed"), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "password", recipientIndex: -1, contentEncryptionAlgorithm: oid.name(encOid) || encOid, authenticated: false }, null, null); }
   catch (_e) { throw _fail(); }
   finally { guard.secret.zeroize(key, CmsError, "cms/bad-input", "the password-derived content-encryption key"); }
 }
@@ -548,27 +574,30 @@ function _pwriUnwrap(kek, wrapped, iv, keyBits) {
   // pass2 = CBC(kek, iv2 = pass1[last block], pass1). Recover pass1's last block by decrypting the
   // last ciphertext block (ECB) and XORing the previous ciphertext block, a standard CBC last-
   // block decrypt that needs no IV, then CBC-decrypt pass2 under that recovered iv2 to get pass1.
-  var ecb = nodeCrypto.createDecipheriv("aes-" + keyBits + "-ecb", kek, Buffer.alloc(0)); ecb.setAutoPadding(false);
-  var lastDec = Buffer.concat([ecb.update(wrapped.subarray(n - blk)), ecb.final()]);
-  var iv2 = Buffer.alloc(blk);
-  for (var i = 0; i < blk; i++) iv2[i] = lastDec[i] ^ wrapped[n - 2 * blk + i];
-  var d1 = nodeCrypto.createDecipheriv(alg, kek, iv2); d1.setAutoPadding(false);
-  var pass1 = Buffer.concat([d1.update(wrapped), d1.final()]);
-  var d2 = nodeCrypto.createDecipheriv(alg, kek, iv); d2.setAutoPadding(false);
-  // body is the recovered plaintext block: it holds the CEK. The caller receives an independent
-  // copy, so the block is cleared on every exit, including the two validation rejects, which are
-  // the paths an attacker induces by tampering with the wrapped key.
-  var body = Buffer.concat([d2.update(pass1), d2.final()]);
+  // Every intermediate below is derived from the KEK and reveals key material, so all three are
+  // named before the try and cleared in one finally. pass1 and body hold the wrapped key in the
+  // clear; lastDec is pass1's final block, recovered ahead of it. The two validation rejects are
+  // inside the same scope because they are the paths an attacker induces by tampering with the
+  // wrapped key, and they are where an unswept intermediate would otherwise be abandoned.
+  var lastDec = null, pass1 = null, body = null;
   try {
+    var ecb = nodeCrypto.createDecipheriv("aes-" + keyBits + "-ecb", kek, Buffer.alloc(0)); ecb.setAutoPadding(false);
+    lastDec = guard.secret.cipherFinish(ecb, wrapped.subarray(n - blk), CmsError, "cms/decrypt-failed", "the recovered CBC last block");
+    var iv2 = Buffer.alloc(blk);
+    for (var i = 0; i < blk; i++) iv2[i] = lastDec[i] ^ wrapped[n - 2 * blk + i];
+    var d1 = nodeCrypto.createDecipheriv(alg, kek, iv2); d1.setAutoPadding(false);
+    pass1 = guard.secret.cipherFinish(d1, wrapped, CmsError, "cms/decrypt-failed", "the PWRI first-pass plaintext");
+    var d2 = nodeCrypto.createDecipheriv(alg, kek, iv); d2.setAutoPadding(false);
+    body = guard.secret.cipherFinish(d2, pass1, CmsError, "cms/decrypt-failed", "the PWRI plaintext block");
     var count = body[0];
     if (count < 1 || count + 4 > body.length) throw _fail();
     var cek = body.subarray(4, 4 + count);
     var bad = 0;
     for (var j = 0; j < 3; j++) bad |= (body[1 + j] ^ 0xff) ^ cek[j]; // complement check bytes
     if (bad !== 0) throw _fail();
-    return Buffer.from(cek);
+    return Buffer.from(cek);   // the caller's copy, independent of the block cleared below
   } finally {
-    guard.secret.zeroizeAll([body, pass1], CmsError, "cms/bad-input", "the PWRI plaintext block");
+    guard.secret.zeroizeAll([body, pass1, lastDec], CmsError, "cms/bad-input", "the PWRI plaintext block");
   }
 }
 // Coverage residual (the unsupported-algorithm throw arm of each lookup below: _hashW3c,

package/lib/cms-encrypt.js

@@ -351,10 +351,10 @@ function _pwriWrapIv(kek, cek, iv) {
   var wk = _pwriFormat(cek);
   try {
     var c1 = nodeCrypto.createCipheriv("aes-256-cbc", kek, iv); c1.setAutoPadding(false);
-    var pass1 = Buffer.concat([c1.update(wk), c1.final()]);
+    var pass1 = guard.secret.cipherFinish(c1, wk, CmsError, "cms/bad-input", "the PWRI first-pass ciphertext");
     var iv2 = pass1.subarray(pass1.length - 16);
     var c2 = nodeCrypto.createCipheriv("aes-256-cbc", kek, iv2); c2.setAutoPadding(false);
-    return Buffer.concat([c2.update(pass1), c2.final()]);
+    return guard.secret.cipherFinish(c2, pass1, CmsError, "cms/bad-input", "the PWRI wrapped key");
   } finally {
     guard.secret.zeroize(wk, CmsError, "cms/bad-input", "the PWRI plaintext block");
   }
@@ -432,11 +432,48 @@ function _emit(inner, ctName, opts) {
 
 function _envelopedData(contentBytes, cek, ca, contentType, riNodes, recips) {
   var iv = nodeCrypto.randomBytes(16);
-  var enc = pbes2.cbcEncrypt(cek, iv, contentBytes, ca.keyBits);
+  var enc = pbes2.cbcEncrypt(cek, iv, contentBytes, ca.keyBits, CmsError, "cms/bad-input");
   var eci = b.sequence([b.oid(O(contentType)), b.sequence([b.oid(O(ca.oid)), b.octetString(iv)]), b.contextPrimitive(0, enc)]);
   return b.sequence([b.integer(BigInt(_envelopedVersion(recips, false))), b.setOf(riNodes), eci]);
 }
 
+// Every authenticated attribute this module MACs -- auto-built or caller-supplied, in either content
+// type that carries them -- MUST be a well-formed Attribute SEQUENCE { type OBJECT IDENTIFIER,
+// non-empty SET OF value } with no repeated type (RFC 5652 sec. 5.3). Rejecting here means a
+// malformed attribute never reaches the wire; leaving it to the wire means the operator learns from
+// a peer's parser that the message they built is unreadable, with the MAC already computed over it.
+//
+// `forbidden` names an attribute type this particular content type must not emit, with the clause
+// that says so. It is a parameter rather than a constant because the same attribute is required in
+// one content type and discouraged in the other: AuthenticatedData MACs its own message-digest by
+// design (RFC 5652 sec. 9.2), while for AuthEnvelopedData that value is the unencrypted hash of a
+// plaintext the message exists to conceal (RFC 5083 sec. 2.1 / sec. 5).
+function _assertAuthAttrs(pairs, forbidden) {
+  var seenTypes = {};
+  pairs.forEach(function (p) {
+    var node;
+    try { node = asn1.decode(p); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute is not well-formed DER", e); }
+    if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children || node.children.length !== 2 ||
+      node.children[1].tagClass !== "universal" || node.children[1].tagNumber !== asn1.TAGS.SET ||
+      !node.children[1].children || node.children[1].children.length < 1) {
+      throw _err("cms/bad-input", "an authenticated attribute must be an Attribute SEQUENCE { type, non-empty SET OF value } (RFC 5652)");
+    }
+    var t;
+    try { t = asn1.read.oid(node.children[0]); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute type is not an OBJECT IDENTIFIER", e); }
+    if (guard.intrinsic.hasOwn(seenTypes, t)) throw _err("cms/bad-input", "authenticated attributes must not repeat an attribute type (RFC 5652): " + t);
+    seenTypes[t] = 1;
+    if (forbidden && t === forbidden.oid) throw _err("cms/bad-input", forbidden.why);
+  });
+}
+
+// The one attribute AuthEnvelopedData declines to emit. Its value is the unencrypted one-way hash of
+// the plaintext, so disclosing it enables content tracking and confirms a guessed plaintext against
+// a message that was encrypted to prevent exactly that.
+var AUTH_ENVELOPED_FORBIDDEN = {
+  oid: O("messageDigest"),
+  why: "authAttrs must not carry the message-digest attribute in an AuthEnvelopedData: its value is the unencrypted hash of the plaintext, which enables content tracking and confirmation of a guessed plaintext (RFC 5083 sec. 2.1, sec. 5)",
+};
+
 function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, recips) {
   var nonce = nodeCrypto.randomBytes(12);
   var authAttrsDer = null, aad = Buffer.alloc(0);
@@ -446,6 +483,7 @@ function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, r
     throw _err("cms/bad-input", "AuthEnvelopedData with a non-data contentType requires authAttrs (RFC 5083 sec. 2.1)");
   }
   if (opts.authAttrs && opts.authAttrs.length) {
+    _assertAuthAttrs(opts.authAttrs, AUTH_ENVELOPED_FORBIDDEN);
     // authAttrs are transmitted [1] IMPLICIT but MACed under the EXPLICIT SET OF tag (RFC 5083 sec. 2.2).
     var setOf = b.setOf(opts.authAttrs);
     aad = setOf; authAttrsDer = b.contextConstructed(1, setOf.subarray(_tlvHeaderLen(setOf)));
@@ -475,7 +513,7 @@ function _encryptedData(contentBytes, desc, ca, contentType, opts, cek) {
   } else {
     throw _err("cms/bad-input", "EncryptedData needs a single { cek } or { password } descriptor");
   }
-  var enc = pbes2.cbcEncrypt(encKey, iv, contentBytes, ca.keyBits);
+  var enc = pbes2.cbcEncrypt(encKey, iv, contentBytes, ca.keyBits, CmsError, "cms/bad-input");
   var eci = b.sequence([b.oid(O(contentType)), contentAlgNode, b.contextPrimitive(0, enc)]);
   var inner = b.sequence([b.integer(0n), eci]);
   return _emit(inner, "encryptedData", opts);
@@ -495,7 +533,7 @@ function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
   var key = nodeCrypto.pbkdf2Sync(password, salt, iterations, ca.keyBits / 8, pbes2.prfNodeByName(prf, _err, "cms"));
   if (pwOwn2.owned) guard.secret.zeroize(password, CmsError, "cms/bad-input", "the password encoding");
   try {
-    var enc = pbes2.cbcEncrypt(key, iv, contentBytes, ca.keyBits);
+    var enc = pbes2.cbcEncrypt(key, iv, contentBytes, ca.keyBits, CmsError, "cms/bad-input");
     var contentAlg = pbes2.pbes2AlgId(salt, iterations, prf, ca.oid, iv);
     var eci = b.sequence([b.oid(O(contentType)), contentAlg, b.contextPrimitive(0, enc)]);
     var inner = b.sequence([b.integer(0n), eci]);
@@ -509,7 +547,7 @@ function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
 function _gcmEncrypt(key, nonce, plaintext, aad, keyBits, tagLen) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-gcm", key, nonce, { authTagLength: tagLen });
   if (aad && aad.length) c.setAAD(aad);
-  var ct = Buffer.concat([c.update(plaintext), c.final()]);
+  var ct = guard.secret.cipherFinish(c, plaintext, CmsError, "cms/bad-input", "a content-encryption intermediate");
   return { ct: ct, tag: c.getAuthTag() };
 }
 
@@ -573,24 +611,7 @@ async function authenticate(content, recipients, opts) {
         b.sequence([b.oid(O("messageDigest")), b.setOf([b.octetString(mdDigest)])]),
       ];
       if (opts.authAttrs && opts.authAttrs.length) pairs = pairs.concat(opts.authAttrs);
-      // Every authAttr (auto-built or caller-supplied) MUST be a well-formed Attribute SEQUENCE
-      // { type OBJECT IDENTIFIER, values SET OF } and each type appears at most once (RFC 5652), so a
-      // malformed or duplicate caller attribute is rejected before it is MACed and emitted, never left to
-      // fail an operator's parser downstream.
-      var seenTypes = {};
-      pairs.forEach(function (p) {
-        var node;
-        try { node = asn1.decode(p); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute is not well-formed DER", e); }
-        if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children || node.children.length !== 2 ||
-          node.children[1].tagClass !== "universal" || node.children[1].tagNumber !== asn1.TAGS.SET ||
-          !node.children[1].children || node.children[1].children.length < 1) {
-          throw _err("cms/bad-input", "an authenticated attribute must be an Attribute SEQUENCE { type, non-empty SET OF value } (RFC 5652)");
-        }
-        var t;
-        try { t = asn1.read.oid(node.children[0]); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute type is not an OBJECT IDENTIFIER", e); }
-        if (seenTypes[t]) throw _err("cms/bad-input", "authenticated attributes must not repeat an attribute type (RFC 5652): " + t);
-        seenTypes[t] = 1;
-      });
+      _assertAuthAttrs(pairs, null);
       var setOf = b.setOf(pairs);
       preimage = setOf;                                                            // MAC over the 0x31 SET OF
       authAttrsDer = b.contextConstructed(2, setOf.subarray(_tlvHeaderLen(setOf)));   // [2] IMPLICIT on the wire

package/lib/cms-sign.js

@@ -109,7 +109,7 @@ function _buildSid(cert, useSki) {
 function _buildSignedAttrs(pairs) {
   var seenTypes = {};
   var attrs = pairs.map(function (p) {
-    if (seenTypes[p.type]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    if (guard.intrinsic.hasOwn(seenTypes, p.type)) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
     seenTypes[p.type] = 1;
     return b.sequence([b.oid(p.type), b.set(p.values)]);
   });
@@ -147,8 +147,8 @@ function _buildUnsignedAttrs(list) {
   var pairs = _resolveAttrPairs(list, "an unsigned attribute value");
   var seen = {};
   pairs.forEach(function (p) {
-    if (UNSIGNED_FORBIDDEN[p.type]) throw _err("cms/bad-input", "the " + UNSIGNED_FORBIDDEN[p.type] + " attribute must not appear as an unsigned attribute (RFC 5652 sec. 11)");
-    if (seen[p.type]) throw _err("cms/bad-input", "unsignedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    if (guard.intrinsic.hasOwn(UNSIGNED_FORBIDDEN, p.type)) throw _err("cms/bad-input", "the " + UNSIGNED_FORBIDDEN[p.type] + " attribute must not appear as an unsigned attribute (RFC 5652 sec. 11)");
+    if (guard.intrinsic.hasOwn(seen, p.type)) throw _err("cms/bad-input", "unsignedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
     seen[p.type] = 1;
   });
   var setOf = b.set(pairs.map(function (p) { return b.sequence([b.oid(p.type), b.set(p.values)]); }));

package/lib/cms-verify.js

@@ -5,6 +5,7 @@
  * @module pki.cms
  * @nav        Verification
  * @title      CMS
+ * @fullname   CMS (Cryptographic Message Syntax) signing and verification
  * @intro Verify a CMS SignedData signature (RFC 5652 sec. 5) -- the structure S/MIME signed
  *   mail, RFC 3161 timestamp tokens, and code-signing all rest on. `verify(cms, opts)` parses
  *   the SignedData (over the strict `pki.schema.cms` codec), locates each SignerInfo's signer
@@ -1118,7 +1119,10 @@ var countersign = cmsSign.countersign;
  * @opts oaepHash      The RSAES-OAEP hash for ktri recipients: `"sha256"` (default) / `"sha384"` / `"sha512"`.
  * @opts keyIdentifier The recipient identifier form: `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
  * @opts ukm           User keying material (a Buffer) for kari / kemri recipients.
- * @opts authAttrs     Authenticated attributes (SET OF Attribute) for AuthEnvelopedData.
+ * @opts authAttrs     Authenticated attributes (SET OF Attribute) for AuthEnvelopedData. Each must be a
+ *   well-formed `Attribute SEQUENCE { type, non-empty SET OF value }` and no type may repeat (RFC 5652
+ *   sec. 5.3). `message-digest` is refused: its value is the unencrypted hash of the plaintext, which
+ *   enables content tracking and confirms a guessed plaintext (RFC 5083 sec. 2.1, sec. 5).
  * @opts pem           Return a PEM string instead of a DER Buffer.
  * @example
  *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };

package/lib/constants.js

@@ -5,6 +5,7 @@
  * @module     pki.C
  * @nav        Core
  * @title      Constants
+ * @fullname   Constants: size caps, time units and named bounds
  * @order      10
  * @featured   true
  * @slug       constants

package/lib/crl-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.crl
  * @nav        Signing
  * @title      CRLs
+ * @fullname   CRLs (certificate revocation lists): read, sign and shard
  * @intro The X.509 CRL producing side. `pki.crl.sign` builds a `TBSCertList`, signs it, and emits a
  *   `CertificateList` (RFC 5280 sec. 5) that `pki.schema.crl.parse`, `pki.path.crlChecker`, and OpenSSL
  *   all accept -- over any signature algorithm the toolkit registry resolves: RSA (PKCS#1 v1.5 / PSS),

package/lib/crmf-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.crmf
  * @nav        Signing
  * @title      Certificate request messages
+ * @fullname   CRMF (Certificate Request Message Format, RFC 4211)
  * @intro The RFC 4211 certificate-request-message producing side. `pki.crmf.build` assembles a
  *   `CertReqMessages` -- one or more `CertReqMsg`, each a `CertRequest` (a `CertTemplate` of the requested
  *   certificate fields plus optional controls) paired with a proof of possession. The common proof is a

package/lib/csr-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.csr
  * @nav        Signing
  * @title      Certification requests
+ * @fullname   CSRs (PKCS#10 certification requests): build, sign and verify
  * @intro The PKCS#10 certification-request producing side. `pki.csr.sign` builds a
  *   `CertificationRequestInfo`, signs it with the subject's own private key (proof of possession, since
  *   a CSR has no issuer), and emits a `CertificationRequest` (RFC 2986) that `pki.schema.csr.parse`,

package/lib/ct.js

@@ -5,6 +5,7 @@
  * @module     pki.ct
  * @nav        Transparency
  * @title      CT
+ * @fullname   Certificate Transparency (CT) logs and SCTs
  * @order      210
  * @slug       ct
  *

package/lib/est.js

@@ -5,6 +5,7 @@
  * @module     pki.est
  * @nav        Schema
  * @title      EST
+ * @fullname   EST (Enrollment over Secure Transport, RFC 7030)
  * @order      190
  * @slug       est
  *

package/lib/framework-error.js

@@ -5,6 +5,7 @@
  * @module     pki.errors
  * @nav        Core
  * @title      Errors
+ * @fullname   Error classes and the stable domain/reason codes they carry
  * @order      20
  * @slug       errors
  *

package/lib/guard-secret.js

@@ -38,6 +38,10 @@ var intrinsic = require("./guard-intrinsic");
 // wiping means; reading `call` off the captured function would let them decide it again, since
 // that function is still the one sitting on the prototype (see guard-intrinsic).
 var _fill = intrinsic.uncurry(Uint8Array.prototype.fill);
+// The join that produces the buffer cipherFinish hands back. Captured for the same reason as
+// the fill: a replaced `Buffer.concat` decides what the caller receives, and it would receive it
+// while the two intermediates this module is responsible for clearing were cleared as promised.
+var _concat = intrinsic.bufferConcat;
 
 // zeroize(value, ErrorClass, code, label) -> the same object, cleared.
 //   value      : a Buffer / TypedArray the TOOLKIT allocated, or null / undefined
@@ -94,4 +98,44 @@ function zeroizeAll(list, ErrorClass, code, label) {
   return list;
 }
 
-module.exports = { zeroize: zeroize, zeroizeAll: zeroizeAll };
+// cipherFinish(transform, input, ErrorClass, code, label) -> the output, as one fresh buffer
+//   transform : a node:crypto Cipher or Decipher the CALLER built and configured (key, iv, AAD,
+//               auth tag, padding mode). This guard performs the two calls and nothing else.
+//   input     : the bytes to feed it.
+//
+// The single place this toolkit runs a configured cipher to completion, because
+// `Buffer.concat([c.update(x), c.final()])` abandons a copy on BOTH of its exits and the leak is
+// invisible at the call site.
+//
+// On a DECIPHER the abandoned copy is plaintext. `update` returns the recovered plaintext while
+// `final` is what decides whether the message was authentic at all -- a GCM tag mismatch, a CBC
+// padding failure -- so on a forged message the whole plaintext exists before anything has judged
+// it, and the `concat` never runs: that buffer becomes unreferenced garbage holding readable
+// plaintext. RFC 5083 sec. 1 requires a receiver whose integrity check fails to destroy the
+// plaintext, and withholding it from the caller is not destroying it. On the success path `concat`
+// COPIES, so the update buffer is a second full copy the caller never receives and nothing else
+// will ever clear.
+//
+// It covers the ENCRYPT direction too, where the intermediates are ciphertext and clearing them
+// buys little. That is deliberate: any rule for which of the two directions must clear is a
+// judgment made at each call site, and the sites where it is wrong are the ones nobody re-reads.
+// One shape, cleared everywhere, needs no such judgment -- and the encrypt intermediates of a
+// key-wrap are not obviously worthless to an attacker either.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape \.update\s*\([\s\S]{0,300}?\)\s*,\s*[A-Za-z_$][\w$]*\s*\.\s*final\s*\(\s*\)
+function cipherFinish(transform, input, ErrorClass, code, label) {
+  var head = null, tail = null;
+  try {
+    head = transform.update(input);
+    tail = transform.final();
+    // Always a fresh copy, never `head` itself: the returned buffer belongs to the caller and the
+    // two intermediates have to be clearable independently of it.
+    return _concat([head, tail]);
+  } finally {
+    zeroize(head, ErrorClass, code, label);
+    zeroize(tail, ErrorClass, code, label);
+  }
+}
+
+module.exports = { zeroize: zeroize, zeroizeAll: zeroizeAll, cipherFinish: cipherFinish };

package/lib/hpke.js

@@ -5,6 +5,7 @@
  * @module pki.hpke
  * @nav        Protocols
  * @title      HPKE
+ * @fullname   HPKE (Hybrid Public Key Encryption, RFC 9180)
  * @intro Hybrid Public Key Encryption (RFC 9180) -- the standard construction
  *   behind TLS Encrypted Client Hello, MLS, and OHTTP that turns a recipient KEM
  *   public key into an encapsulated key plus an AEAD-encrypting context. This is
@@ -319,7 +320,7 @@ Context.prototype.seal = function (aad, pt) {
   var nonce = this._nonce();
   var c = nodeCrypto.createCipheriv(aead.cipher, this._key, nonce, { authTagLength: aead.Nt });
   if (aad && aad.length) c.setAAD(aad);
-  var body = concat([c.update(_buf(pt)), c.final()]);
+  var body = guard.secret.cipherFinish(c, _buf(pt), HpkeError, "hpke/bad-input", "a seal intermediate");
   var ct = concat([body, c.getAuthTag()]);
   this._inc();
   return ct;
@@ -335,7 +336,10 @@ Context.prototype.open = function (aad, ct) {
   if (aad && aad.length) d.setAAD(aad);
   d.setAuthTag(ct.subarray(ct.length - aead.Nt));
   var pt;
-  try { pt = concat([d.update(ct.subarray(0, ct.length - aead.Nt)), d.final()]); }
+  // Through the shared guard so the recovered plaintext is destroyed when the AEAD tag does not
+  // check out (RFC 9180 sec. 5.2 gives open one outcome on failure, and it is not a copy left in
+  // the heap), and so the success path's abandoned intermediate is cleared too.
+  try { pt = guard.secret.cipherFinish(d, ct.subarray(0, ct.length - aead.Nt), HpkeError, "hpke/bad-input", "the recovered plaintext"); }
   catch (e) { throw _err("hpke/open-failed", "AEAD authentication failed (RFC 9180 sec. 5.2)", e); }
   this._inc();
   return pt;

package/lib/http-transport.js

@@ -5,6 +5,7 @@
  * @module     pki.transport
  * @nav        Protocols
  * @title      Transport
+ * @fullname   HTTP transport for OCSP, CRL, EST and ACME requests
  * @order      195
  * @slug       transport
  *

package/lib/inspect.js

@@ -5,6 +5,7 @@
  * @module pki.inspect
  * @nav        Tooling
  * @title      Inspect
+ * @fullname   Inspect: render any PKI structure as readable text
  * @intro Human-readable inspection of a parsed certificate: the pure-JS
  *   equivalent of `openssl x509 -text`. `certificate(input)` ingests a PEM string,
  *   a DER Buffer, or an already-parsed certificate and returns a familiar

package/lib/jose.js

@@ -5,6 +5,7 @@
  * @module     pki.jose
  * @nav        Protocols
  * @title      JOSE (JWS / JWK)
+ * @fullname   JOSE: JWS signatures and JWK keys
  * @order      10
  * @slug       jose
  *

package/lib/key.js

@@ -5,6 +5,7 @@
  * @module     pki.key
  * @nav        Signing
  * @title      Keys
+ * @fullname   Key generation, import and export (RSA, EC, EdDSA, ML-DSA)
  * @intro The key-material lifecycle: export / import a private key as PKCS#8 (`OneAsymmetricKey`,
  *   RFC 5958) or a public key as SPKI (RFC 5280 sec. 4.1.2.7), encrypt / decrypt a private key under
  *   RFC 8018 PBES2 (`EncryptedPrivateKeyInfo`, PBKDF2 + AES-CBC-Pad), and `generate` /
@@ -138,7 +139,7 @@ async function encrypt(privateKey, password, opts) {
   try { dk = nodeCrypto.pbkdf2Sync(pwK.bytes, salt, iterations, keyBits / 8, prfNode); }
   finally { if (pwK.owned) guard.secret.zeroize(pwK.bytes, KeyError, "key/bad-input", "the password encoding"); }
   try {
-    var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits);
+    var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits, KeyError, "key/bad-input");
     var epki = b.sequence([pbes2.pbes2AlgId(salt, iterations, prf, cipherName, iv), b.octetString(ciphertext)]);
     pkcs8.parseEncrypted(epki);   // self-check: the produced EncryptedPrivateKeyInfo re-parses
     return opts.pem ? pkcs8.pemEncode(epki, "ENCRYPTED PRIVATE KEY") : epki;

package/lib/lint.js

@@ -5,6 +5,7 @@
  * @module pki.lint
  * @nav        Tooling
  * @title      Lint
+ * @fullname   Certificate linting against CA/Browser Forum requirements
  * @intro The certificate LINTING engine -- the zlint / pkilint of JavaScript. It walks an
  *   ALREADY-PARSED certificate (from `pki.schema.x509.parse`, whose extension values it
  *   decodes with the shared RFC 5280 decoders) and emits graded, advisory FINDINGS: each

package/lib/merkle.js

@@ -5,6 +5,7 @@
  * @module     pki.merkle
  * @nav        Transparency
  * @title      Merkle
+ * @fullname   Merkle trees: inclusion and consistency proofs (RFC 6962)
  * @order      220
  * @slug       merkle
  *

package/lib/ocsp.js

@@ -5,6 +5,7 @@
  * @module pki.ocsp
  * @nav        Revocation
  * @title      OCSP
+ * @fullname   OCSP (Online Certificate Status Protocol) revocation checking
  * @intro The producing + client-facing half of RFC 6960 Online Certificate Status Protocol:
  *   build a status request over a certificate (`pki.ocsp.buildRequest`), build and sign a status
  *   response as an authorized responder (`pki.ocsp.sign`), emit an unsigned error response

package/lib/oid.js

@@ -5,6 +5,7 @@
  * @module     pki.oid
  * @nav        Core
  * @title      Object Identifiers
+ * @fullname   OID registry: resolve object identifiers by name or dotted form
  * @order      40
  * @slug       oid
  *

package/lib/path-validate.js

@@ -6,6 +6,7 @@
  * @module pki.path
  * @nav Path validation
  * @title Certification path validation (RFC 5280 6)
+ * @fullname Certificate chain validation (RFC 5280 sec. 6 path validation)
  * @intro
  * RFC 5280 6 certification-path validation as a pure, re-entrant algorithm
  * over already-parsed certificates. `pki.path.validate(path, opts)` runs the

package/lib/pbes2.js

@@ -133,13 +133,21 @@ function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
 
 // AES-CBC content encryption / decryption (PKCS#7 pad). decrypt's final() throws on bad pad, and the caller
 // collapses that into its uniform decrypt-failed verdict.
-function cbcEncrypt(key, iv, plaintext, keyBits) {
+// cbcEncrypt(key, iv, plaintext, keyBits, E, code) -> the ciphertext.
+// Takes the caller's typed error for the same reason cbcDecrypt does: the cipher runs through the
+// shared guard, whose one throw has to keep the calling domain's own code.
+function cbcEncrypt(key, iv, plaintext, keyBits, E, code) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([c.update(plaintext), c.final()]);
+  return guard.secret.cipherFinish(c, plaintext, E, code, "a content-encryption intermediate");
 }
-function cbcDecrypt(key, iv, ct, keyBits) {
+// cbcDecrypt(key, iv, ct, keyBits, E, code) -> the recovered plaintext.
+// Takes the caller's typed error the way rc2.cbcDecrypt does, so a refusal keeps its own domain.
+function cbcDecrypt(key, iv, ct, keyBits, E, code) {
   var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([d.update(ct), d.final()]);
+  // A wrong key fails inside final(), on the padding check, and update() has by then produced every
+  // block but the last. Through the guard so that partial plaintext is cleared on both exits rather
+  // than abandoned readable on exactly the path an attacker induces.
+  return guard.secret.cipherFinish(d, ct, E, code, "the partially recovered plaintext");
 }
 
 // Higher-level PBES2 AES-CBC encrypt: derive an AES key from PRE-FORMATTED password bytes (the caller owns
@@ -160,11 +168,11 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   // is not cleared: the caller formatted it and may still own the buffer.
   var key = nodeCrypto.pbkdf2Sync(pwBytes, salt, iterations, keyBits / 8, prfNode);
   try {
-    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits) };
+    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits, E, prefix + "/bad-input") };
   } finally {
     // E is the caller's error FACTORY, not a class; guard-secret delegates its only throw to
-    // guard-bytes, which constructs.  yields the error the factory returns, so the
-    // currency is compatible -- and the throw is unreachable here regardless, because a freshly
+    // guard-bytes, which constructs. `new` on a factory yields the object the factory returns, so
+    // the currency is compatible -- and the throw is unreachable here regardless, because a freshly
     // allocated pbkdf2 buffer cannot be detached.
     guard.secret.zeroize(key, E, prefix + "/bad-input", "the password-derived encryption key");
   }
@@ -208,7 +216,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
     if (budget.rounds < 0) throw E(prefix + "/iteration-limit", "the aggregate PBKDF2 key-derivation work exceeds the budget (a hostile many-element input)");
   }
   var dk = nodeCrypto.pbkdf2Sync(pwBytes, pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
-  try { return cbcDecrypt(dk, iv, ciphertext, keyBits); }
+  try { return cbcDecrypt(dk, iv, ciphertext, keyBits, E, prefix + "/decrypt-failed"); }
   catch (_e) { throw E(prefix + "/decrypt-failed", "decryption failed"); }
   finally { guard.secret.zeroize(dk, E, prefix + "/bad-input", "the password-derived decryption key"); }
 }

package/lib/pkcs12-build.js

@@ -5,6 +5,7 @@
  * @module     pki.pkcs12
  * @nav        Signing
  * @title      PKCS#12
+ * @fullname   PKCS#12 keystores (.p12 and .pfx): build and open
  * @intro The PKCS#12 (.p12 / .pfx) producing side (RFC 7292, RFC 9579). `pki.pkcs12.build` assembles a
  *   password-integrity PFX -- key, certificate, CRL, and secret bags (shrouded keys and cert safes encrypted
  *   under RFC 8018 PBES2) wrapped in an AuthenticatedSafe, protected by either a classic Appendix B HMAC or
@@ -848,7 +849,7 @@ function _decryptLegacyPbe(ea, ct, password, opts, budget) {
   try {
     if (scheme.rc2) return rc2.cbcDecrypt(keyM, scheme.rc2, iv, ct, _err, "pkcs12/decrypt-failed");
     var d = nodeCrypto.createDecipheriv(scheme.cipher, keyM, iv);
-    return Buffer.concat([d.update(ct), d.final()]);
+    return guard.secret.cipherFinish(d, ct, Pkcs12Error, "pkcs12/bad-input", "the recovered safe contents");
   } catch (_e) { throw _err("pkcs12/decrypt-failed", "decryption failed"); }
   finally { guard.secret.zeroize(keyM, Pkcs12Error, "pkcs12/bad-input", "the password-derived decryption key"); }
 }

package/lib/schema-all.js

@@ -5,6 +5,7 @@
  * @module     pki.schema
  * @nav        Schema
  * @title      Schema
+ * @fullname   Format detection: parse DER without knowing the format first
  * @order      10
  * @featured   true
  * @slug       schema

package/lib/schema-c509.js

@@ -5,6 +5,7 @@
  * @module pki.schema.c509
  * @nav    Schema
  * @title  C509
+ * @fullname   C509 compact certificates (CBOR-encoded X.509)
  * @intro  C509 CBOR-encoded certificates (draft-ietf-cose-cbor-encoded-cert). A compact CBOR
  *   re-encoding of an X.509 v3 certificate: a deterministic-CBOR array of exactly 11 elements
  *   (10 TBS fields + the issuer signature). Two modes: c509CertificateType 2 is a natively-signed

package/lib/schema-csrattrs.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.csrattrs
  * @nav        Schema
  * @title      CSR Attributes
+ * @fullname   CSR attributes: what an EST server asks an enrollee to include
  * @order      185
  * @slug       csrattrs
  *

package/lib/schema-engine.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.engine
  * @nav        Schema
  * @title      Schema engine
+ * @fullname   ASN.1 schema engine: one definition drives encode and decode
  * @order      60
  *
  * @intro

package/lib/schema-pkcs8.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.pkcs8
  * @nav        Schema
  * @title      PKCS#8
+ * @fullname   PKCS#8 private keys, encrypted and unencrypted
  * @order      140
  * @slug       pkcs8
  *

package/lib/schema-smime.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.smime
  * @nav        Schema
  * @title      S/MIME (ESS)
+ * @fullname   S/MIME signed and encrypted mail, with ESS security labels
  * @order      180
  * @slug       smime
  *

package/lib/schema-tsp.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.tsp
  * @nav        Schema
  * @title      TSP
+ * @fullname   RFC 3161 timestamps (TSP): request, sign and verify
  * @order      170
  * @slug       tsp
  *

package/lib/schema-x509.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.x509
  * @nav        Schema
  * @title      X.509
+ * @fullname   X.509 certificates: parse, sign and inspect
  * @order      100
  * @featured   true
  * @slug       x509

package/lib/shbs.js

@@ -5,6 +5,7 @@
  * @module pki.shbs
  * @nav        Signatures
  * @title      Stateful hash-based
+ * @fullname   Stateful hash-based signatures: LMS and XMSS
  * @intro Stateful hash-based signature VERIFICATION -- HSS/LMS (RFC 8554),
  *   carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST
  *   SP 800-208. Verify only, by deliberate design: stateful hash-based signing

package/lib/sigstore.js

@@ -5,6 +5,7 @@
  * @module pki.sigstore
  * @nav        Supply chain
  * @title      Sigstore
+ * @fullname   Sigstore bundles: keyless signing and provenance
  * @intro Zero-dependency verifier for a Sigstore bundle, the exact artifact
  *   `npm publish --provenance` produces and the npm registry serves at its
  *   attestations API. A bundle is a keyless (Fulcio) signature over a DSSE-wrapped

package/lib/smime.js

@@ -5,6 +5,7 @@
  * @module     pki.smime
  * @nav        Messaging
  * @title      S/MIME
+ * @fullname   S/MIME signed and encrypted mail
  * @order      175
  * @slug       smime
  *

package/lib/tls-cert-compress.js

@@ -5,6 +5,7 @@
  * @module     pki.tls
  * @nav        Transparency
  * @title      TLS
+ * @fullname   TLS certificate compression (RFC 8879)
  * @order      215
  * @slug       tls
  *

package/lib/trust.js

@@ -5,6 +5,7 @@
  * @module     pki.trust
  * @nav        Path validation
  * @title      Trust-store ingestion
+ * @fullname   Trust stores: load and pin root certificate anchors
  * @order      230
  * @slug       trust
  *

package/lib/tsp-sign.js

@@ -5,6 +5,7 @@
  * @module     pki.tsp
  * @nav        Signing
  * @title      Timestamps
+ * @fullname   RFC 3161 trusted timestamps: request, sign and verify
  * @intro Create an RFC 3161 timestamp token. A TimeStampToken IS a CMS SignedData whose
  *   encapsulated content is a `TSTInfo` (the timestamped message imprint + trusted time), so
  *   `sign(messageImprint, tsa, opts)` builds the `TSTInfo`, attaches the RFC 3161 sec. 2.4.2

package/lib/webauthn.js

@@ -5,6 +5,7 @@
  * @module pki.webauthn
  * @nav        Validation
  * @title      WebAuthn
+ * @fullname   WebAuthn: verify registration attestation and assertions
  * @intro Trust evaluation of a W3C WebAuthn (Level 3) / passkey attestation: parse
  *   the attestation object + authenticatorData, decode the COSE credential public
  *   key, and verify each defined attestation-statement format (packed, tpm,

package/lib/webcrypto.js

@@ -5,6 +5,7 @@
  * @module     pki.webcrypto
  * @nav        Core
  * @title      WebCrypto
+ * @fullname   WebCrypto: a SubtleCrypto surface over node:crypto
  * @order      50
  * @featured   true
  * @slug       webcrypto
@@ -470,7 +471,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
       return _withSecretBytes(key, function (kb) {
         var cipher = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-gcm", kb, iv, { authTagLength: (alg.tagLength || 128) / 8 });
         if (aad) cipher.setAAD(aad);
-        var ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+        var ct = guard.secret.cipherFinish(cipher, buf, WebCryptoError, "webcrypto/operation", "an AES-GCM encrypt intermediate");
         return Buffer.concat([ct, cipher.getAuthTag()]);
       });
     }, "encrypt"));
@@ -480,7 +481,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var c2 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-cbc", kb, cbcIv);
-        return Buffer.concat([c2.update(buf), c2.final()]);
+        return guard.secret.cipherFinish(c2, buf, WebCryptoError, "webcrypto/operation", "an AES-CBC encrypt intermediate");
       });
     }, "encrypt"));
   }
@@ -490,7 +491,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var c3 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-ctr", kb, ctrCounter);
-        return Buffer.concat([c3.update(buf), c3.final()]);
+        return guard.secret.cipherFinish(c3, buf, WebCryptoError, "webcrypto/operation", "an AES-CTR encrypt intermediate");
       });
     }, "encrypt"));
   }
@@ -528,7 +529,9 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
         var d = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-gcm", kb, iv, { authTagLength: tagLen });
         if (gcmAad) d.setAAD(gcmAad);
         d.setAuthTag(tag);
-        return Buffer.concat([d.update(ct), d.final()]);
+        // The recovered plaintext exists in full before final() judges the tag, so a forged message
+        // would otherwise abandon a readable copy on the throw path.
+        return guard.secret.cipherFinish(d, ct, WebCryptoError, "webcrypto/operation", "the recovered AES-GCM plaintext");
       });
     }, "decrypt"));
   }
@@ -537,7 +540,7 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var d2 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-cbc", kb, cbcIv2);
-        return Buffer.concat([d2.update(buf), d2.final()]);
+        return guard.secret.cipherFinish(d2, buf, WebCryptoError, "webcrypto/operation", "the recovered AES-CBC plaintext");
       });
     }, "decrypt"));
   }
@@ -547,7 +550,7 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var d3 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-ctr", kb, ctrCounter2);
-        return Buffer.concat([d3.update(buf), d3.final()]);
+        return guard.secret.cipherFinish(d3, buf, WebCryptoError, "webcrypto/operation", "the recovered AES-CTR plaintext");
       });
     }, "decrypt"));
   }
@@ -874,7 +877,7 @@ SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey
     try {
       return _withSecretBytes(wrappingKey, function (wkBytes) {
         var c = nodeCrypto.createCipheriv("aes" + wrappingKey.algorithm.length + "-wrap", wkBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
-        return _toArrayBuffer(Buffer.concat([c.update(bytes), c.final()]));
+        return _toArrayBuffer(guard.secret.cipherFinish(c, bytes, WebCryptoError, "webcrypto/operation", "an AES-KW wrap intermediate"));
       });
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "wrapKey: AES-KW key wrap failed", e); }
   }
@@ -919,7 +922,7 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
     try {
       bytes = _withSecretBytes(unwrappingKey, function (kwBytes) {
         var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", kwBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
-        return Buffer.concat([d.update(wrapped), d.final()]);
+        return guard.secret.cipherFinish(d, wrapped, WebCryptoError, "webcrypto/operation", "the unwrapped key material");
       });
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "unwrapKey: AES-KW key unwrap failed (integrity or length)", e); }
   } else {

package/lib/x509-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.x509
  * @nav        Signing
  * @title      Certificates
+ * @fullname   X.509 certificates: parse, sign and inspect
  * @intro The X.509 certificate-issuance producing side. `pki.x509.sign` builds a `TBSCertificate`,
  *   signs it, and emits a `Certificate` (RFC 5280 sec. 4) that `pki.schema.x509.parse`,
  *   `pki.path.validate`, and OpenSSL all accept, self-signed or CA-signed, over any signature

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "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:4977fc76-9318-4187-883f-52d642638d7f",
+  "serialNumber": "urn:uuid:b8b3d2cf-001e-4a5b-8644-a627ed3ce3c5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-20T03:58:27.675Z",
+    "timestamp": "2026-08-20T14:50:41.972Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.16",
+      "bom-ref": "@blamejs/pki@0.5.17",
       "type": "application",
       "name": "pki",
-      "version": "0.5.16",
+      "version": "0.5.17",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.5.16",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.17",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.16",
+      "ref": "@blamejs/pki@0.5.17",
       "dependsOn": []
     }
   ]