@blamejs/pki 0.5.15 → 0.5.17

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-all.js

@@ -67,6 +67,7 @@ var compress = require("./guard-compress");
 var secret = require("./guard-secret");
 var parsed = require("./guard-parsed");
 var async_ = require("./guard-async");
+var intrinsic = require("./guard-intrinsic");
 
 module.exports = {
   bytes:  bytes,
@@ -85,4 +86,5 @@ module.exports = {
   secret: secret,
   parsed: parsed,
   async:  async_,
+  intrinsic: intrinsic,
 };

package/lib/guard-async.js

@@ -1,6 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
+
+// The two settle operations, taken at load and uncurried so the call sites read no property of
+// them. These are how a synchronous fault becomes the rejection this guard promises, so a replaced
+// `reject` returning a resolved promise turns a refusal into a pass at the one place the exit shape
+// is decided. See guard-intrinsic for the whole captured set.
+var _intrinsic = require("./guard-intrinsic");
+var _resolve = _intrinsic.uncurry(_intrinsic.promiseResolve);
+var _reject = _intrinsic.uncurry(_intrinsic.promiseReject);
+var _Promise = Promise;
 //
 // @internal -- no operator-facing namespace. The documented surface is every verb whose
 // @signature says `-> Promise<...>`; this is how each of them refuses.
@@ -29,9 +38,12 @@
 //   test/layer-0-primitives/promise-contract.test.js, which reads every `-> Promise<` @signature out
 //   of lib/ and calls each verb to prove the refusal arrives as a rejection. A new verb is in
 //   scope the day it is documented, so no list here can go stale.
+// Both taken at load. These are how a synchronous fault becomes the rejection this guard promises,
+// so a replaced `reject` returning a resolved promise turns a refusal into a pass at the one place
+// the exit shape is decided. See guard-intrinsic for the whole captured set.
 function deferred(body) {
-  try { return Promise.resolve(body()); }
-  catch (e) { return Promise.reject(e); }
+  try { return _resolve(_Promise, body()); }
+  catch (e) { return _reject(_Promise, e); }
 }
 
 module.exports = { deferred: deferred };