@blamejs/pki 0.5.7 → 0.5.8

package/lib/pbes2.js

@@ -2,12 +2,12 @@
 // Copyright (c) blamejs contributors
 "use strict";
 //
-// @internal -- the RFC 8018 PBES2 / PBKDF2 primitives, the ONE home shared by pki.cms EncryptedData / PWRI
+// @internal -- the RFC 8018 PBES2 / PBKDF2 primitives, the single home shared by pki.cms EncryptedData / PWRI
 // password encryption and pki.key EncryptedPrivateKeyInfo (RFC 5958). Error-factory-parameterized like the
-// guard family: every reject goes through the CALLER's `E(code, msg, cause)` full-code factory plus a domain
-// `prefix`, so pki.cms keeps cms/* codes and pki.key keeps key/* codes off ONE implementation. Extracted
-// behavior-preservingly from cms-encrypt.js + cms-decrypt.js -- the shipped CMS PBES2 tests are the guard.
-// A shape here that CANNOT route through a guard stays with its caller; the reusable PBES2 shape lives here
+// guard family: every reject goes through the caller's `E(code, msg, cause)` full-code factory plus a domain
+// `prefix`, so pki.cms keeps cms/* codes and pki.key keeps key/* codes off one implementation. Extracted
+// behavior-preservingly from cms-encrypt.js and cms-decrypt.js; the shipped CMS PBES2 tests are the guard.
+// A shape here that cannot route through a guard stays with its caller; the reusable PBES2 shape lives here
 // so a fourth copy (the drift a reviewer flags) cannot re-accrete.
 
 var nodeCrypto = require("crypto");
@@ -26,7 +26,7 @@ var PRF_NODE_BY_NAME = { hmacWithSHA1: "sha1", hmacWithSHA256: "sha256", hmacWit
 var PRF_NODE_BY_OID = {}; Object.keys(PRF_NODE_BY_NAME).forEach(function (n) { PRF_NODE_BY_OID[O(n)] = PRF_NODE_BY_NAME[n]; });
 
 // content-encryption OID -> AES key bits (CBC + GCM). The PBES2 encryptionScheme + CMS content cipher table.
-// CONTENT_MODE rides the SAME rows so a cipher can never be present for its key length but absent for its
+// CONTENT_MODE rides the same rows so a cipher can never be present for its key length but absent for its
 // mode: key length alone does not distinguish an AEAD cipher from a plain one, and a consumer that resolves
 // only the length would open content in the wrong mode whenever the two happen to share a key size.
 var CONTENT_KEYBITS = {}, CONTENT_MODE = {};
@@ -79,8 +79,8 @@ function pbkdf2ParamsSeq(salt, iterations, prf) {
 }
 
 // The PBES2 AlgorithmIdentifier: SEQUENCE { id-PBES2, SEQUENCE { keyDerivationFunc PBKDF2, encryptionScheme } }.
-// The ONE home for the CMS EncryptedData contentEncryptionAlgorithm AND the RFC 5958 EncryptedPrivateKeyInfo
-// encryptionAlgorithm -- both wrap the same PBES2 structure around a PBKDF2 KDF plus an AES-CBC scheme whose
+// The single home for the CMS EncryptedData contentEncryptionAlgorithm and the RFC 5958 EncryptedPrivateKeyInfo
+// encryptionAlgorithm: both wrap the same PBES2 structure around a PBKDF2 KDF plus an AES-CBC scheme whose
 // IV rides in the encryptionScheme parameter. `cipherName` is a registry NAME (an AES-CBC OID name).
 function pbes2AlgId(salt, iterations, prf, cipherName, iv) {
   var kdf = b.sequence([b.oid(O("pbkdf2")), pbkdf2ParamsSeq(salt, iterations, prf)]);
@@ -100,7 +100,7 @@ function seqChildren(paramsDer, minLen, what, E, prefix) {
   return requireChildren(asn1.decode(paramsDer), minLen, what, E, prefix);
 }
 
-// Strict PBKDF2-params decode: salt (capped BEFORE derivation), iterationCount (positiveInt31 + cap, downward-
+// Strict PBKDF2-params decode: salt (capped before derivation), iterationCount (positiveInt31 + cap, downward-
 // overridable via a validated-positive-int opts.maxIterations so Math.min(NaN, cap) cannot silently disable
 // the DoS cap), prf. Returns { salt, iterations, prfNode }.
 function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
@@ -131,7 +131,7 @@ function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
   return { salt: salt, iterations: iterations, prfNode: prfNode };
 }
 
-// AES-CBC content encryption / decryption (PKCS#7 pad). decrypt's final() throws on bad pad -- the caller
+// 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) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
@@ -155,9 +155,9 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   var iterations = assertIterations(opts.iterations == null ? 2048 : opts.iterations, E, prefix);
   var salt = opts.salt != null ? assertSalt(opts.salt, E, prefix) : nodeCrypto.randomBytes(16);
   var iv = opts.iv != null ? opts.iv : nodeCrypto.randomBytes(16);
-  // The derived key is this module's allocation and protects the caller's plaintext -- a private key
-  // in the pkcs8 / pkcs12 callers -- so it is cleared once the encryption has consumed it. pwBytes is
-  // NOT: the caller formatted it and may still own the buffer.
+  // The derived key is this module's allocation and protects the caller's plaintext (a private key
+  // in the pkcs8 and pkcs12 callers), so it is cleared once the encryption has consumed it. pwBytes
+  // 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) };
@@ -202,7 +202,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
     }
     throw E(prefix + "/bad-algorithm-parameters", "malformed PBES2 parameters", e);
   }
-  // Charge the shared budget BEFORE deriving, so the work is refused rather than performed.
+  // Charge the shared budget before deriving, so the work is refused instead of performed.
   if (budget) {
     budget.rounds -= pb.iterations;
     if (budget.rounds < 0) throw E(prefix + "/iteration-limit", "the aggregate PBKDF2 key-derivation work exceeds the budget (a hostile many-element input)");
@@ -218,7 +218,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
 function _hmacAlgId(name) { return b.sequence([b.oid(O(name)), b.nullValue()]); }
 
 // The id-PBMAC1 AlgorithmIdentifier: id-PBMAC1 + PBMAC1-params { keyDerivationFunc PBKDF2, messageAuthScheme
-// HMAC } -- the byte-exact inverse of schema-pkcs12 / schema-cmp's PBMAC1_PARAMS. `desc` = { salt,
+// HMAC }, the byte-exact inverse of schema-pkcs12 / schema-cmp's PBMAC1_PARAMS. `desc` = { salt,
 // iterationCount, keyLength, prfName, macName }. The prf is omitted iff it equals the default hmacWithSHA1.
 function pbmac1AlgId(desc) {
   var pbkdf2Params = [b.octetString(desc.salt), b.integer(BigInt(desc.iterationCount)), b.integer(BigInt(desc.keyLength))];
@@ -238,7 +238,7 @@ function pbmac1(pwBytes, salt, iterationCount, keyLength, prfHash, macHash, mess
   }).then(function (bits) {
     // The derived MAC key is this function's allocation, in two forms: the ArrayBuffer deriveBits
     // returned and the Buffer view over it that is imported. Clearing the view clears both, and it
-    // runs whether the signing succeeds or throws -- the sibling PBES2 encrypt/decrypt above clear
+    // runs whether the signing succeeds or throws. The sibling PBES2 encrypt/decrypt above clear
     // their derived keys, and every PBMAC1 consumer (PKCS#12 build and verification) inherits this.
     var mk = Buffer.from(bits);
     return subtle.importKey("raw", mk, { name: "HMAC", hash: macHash }, false, ["sign"]).then(function (hmacKey) {

package/lib/pkcs12-build.js

@@ -17,20 +17,20 @@
  */
 //
 // The PBES2 bag encryption and the PBMAC1 MAC compose the shared lib/pbes2.js home (the same PBKDF2 + AES-CBC
-// + HMAC primitives pki.cms and pki.key use), fed PKCS#12 App. B.1-formatted password bytes -- NOT the CMS
+// + HMAC primitives pki.cms and pki.key use), fed PKCS#12 App. B.1-formatted password bytes, never the CMS
 // UTF-8 encoding, the single most common PKCS#12 interop failure. The classic Appendix B.2 KDF (ID=3, the MAC
 // integrity purpose) is bespoke PKCS#12 crypto with no in-tree equivalent, built here as one primitive and
-// cross-checked against OpenSSL. The MAC is computed over the CONTENT octets of the id-data authSafe OCTET
-// STRING (excluding its TLV header) -- exactly the parser's `macedBytes`, the canonical off-by-the-header
-// trap designed out. Public-key integrity (an id-signedData authSafe -- a CMS SignedData over the exact
+// cross-checked against OpenSSL. The MAC is computed over the content octets of the id-data authSafe OCTET
+// STRING (excluding its TLV header), exactly the parser's `macedBytes`, the canonical off-by-the-header
+// trap designed out. Public-key integrity (an id-signedData authSafe, a CMS SignedData over the exact
 // AuthenticatedSafe, no MacData) is produced by composing pki.cms.sign and verified on open by pki.cms.verify
 // as the integrity gate before any bag is trusted; the signer is surfaced, never trust-chained (the caller's
 // pki.path.validate step). Public-key PRIVACY (an id-envelopedData safe encrypting the SafeContents to a
 // recipient public key, RFC 7292 sec. 3.1) is produced by composing pki.cms.encrypt (AES-CBC EnvelopedData,
-// never GCM/AuthEnvelopedData) and opened by composing pki.cms.decrypt with the recipient key -- AFTER the
+// never GCM/AuthEnvelopedData) and opened by composing pki.cms.decrypt with the recipient key, after the
 // integrity gate, with every recipient-side fault collapsed to the uniform pkcs12/decrypt-failed. Privacy is
 // independent of integrity: all four combinations (password/public-key integrity x password/public-key privacy)
-// are permitted, and the recipient key is a privacy credential only -- never a MAC key, signer, or PBES2 password.
+// are permitted, and the recipient key is a privacy credential only: never a MAC key, signer, or PBES2 password.
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
@@ -55,13 +55,13 @@ var PemError = frameworkError.PemError;
 function O(n) { return oid.byName(n); }
 function _err(code, msg, cause) { return new Pkcs12Error(code, msg, cause); }
 
-// PKCS#12 integrity/privacy defaults (named, not call-site literals -- rule 12).
+// PKCS#12 integrity/privacy defaults, named here so no call site writes them as literals (rule 12).
 var DEFAULT_MAC_ITER = 2048;
 var DEFAULT_PBMAC1_ITER = 2048;
 var MAC_SALT_BYTES = 8;
-var MAX_PBMAC1_KEYLEN = 1024;   // an HMAC key beyond a hash block is pointless -- bound the derived length
-// Both MAC paths cap iterations to bound the SYNCHRONOUS derivation that blocks the event loop, but at
-// different counts BECAUSE the per-iteration cost differs by ~5x -- the two ceilings target a comparable
+var MAX_PBMAC1_KEYLEN = 1024;   // an HMAC key beyond a hash block is pointless, so bound the derived length
+// Both MAC paths cap iterations to bound the synchronous derivation that blocks the event loop, but at
+// different counts, because the per-iteration cost differs by ~5x: the two ceilings target a comparable
 // ~1-2 second wall-clock budget, not inconsistent DoS budgets. The classic Appendix B KDF is a hand-rolled
 // JS hash loop (a createHash per iteration, ~1.1us each, so 1e6 ~= 1s); PBMAC1 derives via native
 // crypto.pbkdf2Sync (one FFI call, ~0.2us per iteration, so the shared C.LIMITS.PBKDF2_MAX_ITERATIONS of 1e7
@@ -69,12 +69,12 @@ var MAX_PBMAC1_KEYLEN = 1024;   // an HMAC key beyond a hash block is pointless
 // pkcs12-local (its KDF is bespoke here) while PBMAC1 reuses the toolkit-wide PBKDF2 ceiling. 1e6 is ~500x
 // the OpenSSL default (2048) yet still bounds the loop to ~1 second.
 var CLASSIC_MAC_MAX_ITERATIONS = 1000000;
-// The AGGREGATE cap on synchronous KDF work across a single open() -- rounds summed over every encrypted
+// The aggregate cap on synchronous KDF work across a single open(): rounds summed over every encrypted
 // bag and safe, whichever scheme it uses: the legacy App. B KDF (its block count x iterations) and PBKDF2
 // alike. The per-bag iteration cap resets per bag, so a hostile store that duplicates a costly bag up to the
 // parser's 1024-element limit would otherwise block the event loop for minutes; this bounds the total to
-// ~the classic MAC ceiling. It covers BOTH schemes because covering only the legacy one left the modern
-// path -- the one every current producer emits -- free to multiply its cap by the element limit.
+// ~the classic MAC ceiling. It covers both schemes because covering only the legacy one left the modern
+// path (the one every current producer emits) free to multiply its cap by the element limit.
 // A conforming store runs only a few thousand rounds (its handful of bags at ~2048 iterations).
 var KDF_MAX_ROUNDS = CLASSIC_MAC_MAX_ITERATIONS;
 
@@ -104,10 +104,10 @@ var DIGEST_NAME = { sha1: "sha1", sha256: "sha256", sha384: "sha384", sha512: "s
 // is taken verbatim as already-formatted bytes (an escape hatch for a caller that pre-encodes).
 function _p12Password(pw) { return _p12PasswordOwned(pw).bytes; }
 
-// An ABSENT password is refused rather than encoded as the empty one. The two are not the same
+// An absent password is refused, never encoded as the empty one. The two are not the same
 // credential, and the difference is invisible at the call site: a caller who misspells the option,
 // or threads it through a layer that drops it, otherwise gets a store whose private key is
-// protected by nothing and no error anywhere saying so. The empty password remains available --
+// protected by nothing and no error anywhere saying so. The empty password remains available:
 // it just has to be asked for, as "".
 var _MISSING_PASSWORD = "a password must be a string, Buffer, or Uint8Array -- an omitted password " +
   "is not the empty password; pass \"\" to use the empty one deliberately";
@@ -116,8 +116,8 @@ var _MISSING_PASSWORD = "a password must be a string, Buffer, or Uint8Array -- a
 // capability cannot arrive with its option silently ignored at this boundary.
 var _INTEGRITY_OPTS = { mode: 1, signer: 1, signers: 1, certificates: 1, sid: 1, signingTime: 1 };
 
-// The same encoding, reporting OWNERSHIP -- mirroring pbes2.passwordBytesOwned. A caller-supplied
-// Buffer is returned AS-IS and is BORROWED: clearing it would destroy the caller's own credential,
+// The same encoding, reporting ownership, mirroring pbes2.passwordBytesOwned. A caller-supplied
+// Buffer is returned as-is and is borrowed: clearing it would destroy the caller's own credential,
 // which is a worse defect than leaving a copy readable. Every other input is re-encoded into a
 // buffer this module allocated, which it must clear once a derivation has consumed it.
 function _p12PasswordOwned(pw) {
@@ -125,9 +125,9 @@ function _p12PasswordOwned(pw) {
   return { bytes: _p12Encode(pw), owned: true };
 }
 function _p12Encode(pw) {
-  // A view first, so a detached backing store is a reject rather than an empty password; then a COPY,
-  // because everything this function returns is reported OWNED and gets zeroized after derivation --
-  // handing back a view of a caller's Uint8Array would wipe the caller's own credential.
+  // A view first, so a detached backing store is a reject and never an empty password; then a copy,
+  // because everything this function returns is reported owned and gets zeroized after derivation,
+  // and handing back a view of a caller's Uint8Array would wipe the caller's own credential.
   if (Buffer.isBuffer(pw) || pw instanceof Uint8Array) return guard.bytes.snapshot(pw, Pkcs12Error, "pkcs12/bad-input", "the password");
   if (typeof pw !== "string") throw _err("pkcs12/bad-input", _MISSING_PASSWORD);
   var out = Buffer.alloc(pw.length * 2 + 2);   // + the 2-byte NULL terminator
@@ -141,12 +141,12 @@ function _p12Encode(pw) {
 }
 
 // The password bytes for the RFC 8018 PBES2 bag ciphers and the RFC 9579 PBMAC1 MAC. Although RFC 9579 sec. 6
-// specifies the BMPString encoding here too, OpenSSL and NSS -- and thus the interoperable ecosystem -- feed
+// specifies the BMPString encoding here too, OpenSSL and NSS (and thus the interoperable ecosystem) feed
 // PBKDF2 the raw UTF-8 password for these modern schemes (confirmed byte-for-byte against `openssl pkcs12`),
 // reserving the BMPString+NULL form for the bespoke Appendix B KDF only. A file we emit must open in OpenSSL,
 // so the modern schemes use UTF-8 here; only the classic Appendix B MAC uses `_p12Password`.
-// The UTF-8 encoding, reporting OWNERSHIP -- the sibling of _p12PasswordOwned, and it exists
-// for the same reason. A caller-supplied Buffer is BORROWED and left alone; every other input is
+// The UTF-8 encoding, reporting ownership: the sibling of _p12PasswordOwned, and it exists
+// for the same reason. A caller-supplied Buffer is borrowed and left alone; every other input is
 // re-encoded into a buffer this module allocated, and a plaintext password copy this module made
 // is cleared once the derivation has consumed it. Without it the App. B.1 copy taken from the same
 // argument in the same call was wiped while this one was not.
@@ -171,7 +171,7 @@ function _blockFill(src, blockSize) {
 }
 
 // RFC 7292 Appendix B.2 KDF: derive `nBytes` of key material for purpose `id` (1 = cipher key, 2 = IV,
-// 3 = MAC) from the App. B.1 password bytes + salt over `iterations` rounds of `hashName`. NOT PBKDF2. The
+// 3 = MAC) from the App. B.1 password bytes + salt over `iterations` rounds of `hashName`. This is not PBKDF2. The
 // block count c = ceil(nBytes/u): the MAC always requests exactly the hash output u (c = 1, one diversified,
 // salted, iterated hash), while a legacy-PBE cipher key wider than u (e.g. 24-byte 3-key-3DES from SHA-1's
 // 20-byte output, c = 2) exercises the multi-block feedback (step 6C: I = (I + B + 1) mod 2^(8v) between
@@ -181,7 +181,7 @@ function _p12Kdf(hashName, id, pwBytes, salt, iterations, nBytes) {
   var uv = P12_KDF_UV[hashName], u = uv.u, v = uv.v;
   var D = Buffer.alloc(v, id);                                          // step 1: v copies of the ID diversifier
   // Each fill is a full block-repeated copy of the salt / password; only their concatenation is
-  // used, so the sources are cleared rather than abandoned.
+  // used, so the sources are cleared and never abandoned.
   var sFill = _blockFill(salt, v), pFill = _blockFill(pwBytes, v);
   var I = Buffer.concat([sFill, pFill]);                                // steps 2-4: I = S || P
   guard.secret.zeroizeAll([sFill, pFill], Pkcs12Error, "pkcs12/bad-input", "a key-derivation fill");
@@ -206,7 +206,7 @@ function _p12Kdf(hashName, id, pwBytes, salt, iterations, nBytes) {
     }
     guard.secret.zeroize(A, Pkcs12Error, "pkcs12/bad-input", "a key-derivation block");
   }
-  // I is S || P -- it carries the password bytes -- and is finished with here.
+  // I is S || P, so it carries the password bytes, and is finished with here.
   guard.secret.zeroize(I, Pkcs12Error, "pkcs12/bad-input", "the key-derivation input block");
   // Step 8 is "the first nBytes of A", but returning a SUBARRAY would hand back a view over a
   // larger allocation: a caller clearing what it received would leave the rest of the final digest
@@ -358,7 +358,7 @@ function _pbeOpts(enc) {
   };
 }
 
-// SafeContents ::= SEQUENCE OF SafeBag (ordered, NOT a SET OF).
+// SafeContents ::= SEQUENCE OF SafeBag (ordered, and not a SET OF).
 function _buildSafeContents(bags, opts, depth) {
   if (!Array.isArray(bags)) throw _err("pkcs12/bad-input", "bags must be an array");
   if (bags.length > C.LIMITS.PKCS12_MAX_ELEMENTS) throw _err("pkcs12/bad-input", "a SafeContents exceeds the element cap " + C.LIMITS.PKCS12_MAX_ELEMENTS);
@@ -366,13 +366,13 @@ function _buildSafeContents(bags, opts, depth) {
 }
 
 // One AuthenticatedSafe element: a plaintext id-data ContentInfo, an id-encryptedData ContentInfo whose
-// EncryptedData is the PBES2 encryption of the SafeContents (RFC 7292 sec. 5.1 step 2A/2B), or -- for
-// PUBLIC-KEY privacy (sec. 3.1) -- an id-envelopedData ContentInfo whose CMS EnvelopedData encrypts the
+// EncryptedData is the PBES2 encryption of the SafeContents (RFC 7292 sec. 5.1 step 2A/2B), or, for
+// public-key privacy (sec. 3.1), an id-envelopedData ContentInfo whose CMS EnvelopedData encrypts the
 // SafeContents to one or more recipient public keys. Async because the envelope path awaits pki.cms.encrypt.
 async function _buildAuthSafeElement(sc, opts) {
   if (!sc || typeof sc !== "object") throw _err("pkcs12/bad-input", "each safeContents entry must be an object");
-  // A privacy directive is honored whenever its field is PRESENT (even if falsy). A present-but-falsy `recipients`
-  // or `encrypt` (null / false / "") is a configuration error that intended privacy -- it must fail closed, NEVER
+  // A privacy directive is honored whenever its field is present (even if falsy). A present-but-falsy `recipients`
+  // or `encrypt` (null / false / "") is a configuration error that intended privacy, so it must fail closed and never
   // silently fall through to a plaintext id-data safe that would emit the bags in cleartext (privacy downgraded to
   // none while still producing a valid MAC-protected PFX). Omit the field entirely for a genuinely plaintext safe.
   var hasRecipients = sc.recipients !== undefined;
@@ -381,10 +381,10 @@ async function _buildAuthSafeElement(sc, opts) {
   var safeContentsDer = _buildSafeContents(sc.bags || [], opts, 0);
   if (hasRecipients) {
     if (!Array.isArray(sc.recipients) || !sc.recipients.length) throw _err("pkcs12/bad-input", "safeContents.recipients must be a non-empty array of recipient descriptors (RFC 5652 sec. 6.1)");
-    // Public-key privacy admits only CERTIFICATE recipients (ktri / kari / kemri -- RSA / ECDH / X25519 / X448 /
-    // ML-KEM, dispatched off the cert key). A password (pwri) or KEK (kekri) recipient is NOT public-key privacy
-    // and pki.pkcs12.open (which forwards only { recipientKey, recipientCert } to cms.decrypt) cannot reopen it --
-    // so reject it here rather than emit a store the toolkit's own reader cannot process. (Re-open: pwri/kekri
+    // Public-key privacy admits only certificate recipients (ktri / kari / kemri: RSA / ECDH / X25519 / X448 /
+    // ML-KEM, dispatched off the cert key). A password (pwri) or KEK (kekri) recipient is not public-key privacy
+    // and pki.pkcs12.open (which forwards only { recipientKey, recipientCert } to cms.decrypt) cannot reopen it,
+    // so reject it here and never emit a store the toolkit's own reader cannot process. (Re-open: pwri/kekri
     // privacy when open forwards the full cms.decrypt key-material model.)
     sc.recipients.forEach(function (r) {
       if (!r || typeof r !== "object" || r.cert == null) throw _err("pkcs12/bad-input", "a public-key privacy recipient must be a certificate recipient { cert } (a password or KEK recipient is not public-key privacy and cannot be reopened by pkcs12.open)");
@@ -474,9 +474,9 @@ function _normalizeSpec(spec, opts) {
     (spec.ca || []).forEach(function (ca) { certBags.push({ type: "cert", cert: ca }); });
     var sc = [];
     if (enveloped) {
-      // Public-key-privacy convenience: the cert bags + a PLAINTEXT keyBag in ONE recipient-enveloped safe (the
+      // Public-key-privacy convenience: the cert bags plus a plaintext keyBag in one recipient-enveloped safe (the
       // envelope supplies confidentiality; there is no recipient-encrypted key-bag type, RFC 7292 sec. 4.2). The
-      // caller password, if any, remains the MAC (integrity) password -- privacy and integrity are independent.
+      // caller password, if any, remains the MAC (integrity) password; privacy and integrity are independent.
       var bags = certBags.slice();
       if (spec.key != null) bags.push({ type: "key", key: spec.key, friendlyName: spec.friendlyName, localKeyId: spec.localKeyId });
       sc.push({ recipients: opts.recipientCerts.map(function (c) { return { cert: c }; }), bags: bags });
@@ -505,7 +505,7 @@ function _normalizeSpec(spec, opts) {
  * plaintext or PBES2-encrypted `SafeContents` of key / shroudedKey / cert / crl / secret / nested
  * safeContents bags. Keys and certs are validated before wrapping. Password integrity (the default) MACs the
  * AuthenticatedSafe with a classic Appendix B HMAC or an RFC 9579 PBMAC1. Public-key integrity
- * (`opts.integrity.mode: "public-key"`) instead wraps the AuthenticatedSafe in a CMS SignedData -- a
+ * (`opts.integrity.mode: "public-key"`) instead wraps the AuthenticatedSafe in a CMS SignedData: a
  * signature from a keypair, no MacData (RFC 7292 sec. 4). Privacy (PBES2 bag encryption via `password`) is
  * independent of the integrity mode. The store is re-parsed before return.
  *
@@ -675,33 +675,33 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  * @defends pkcs12-unauthenticated-decrypt (CWE-347), pbes2-padding-oracle (CWE-208)
  * @related pki.pkcs12.build, pki.pkcs12.verifyMac, pki.schema.pkcs12.parse
  *
- * Read a PKCS#12 store: verify its integrity FIRST -- a password store's MAC, or a public-key store's CMS
- * SignedData signature (RFC 7292 sec. 4 / 5.1 -- never trust a bag from a store whose integrity check fails) --
- * then decrypt every PBES2 privacy safe and pkcs8ShroudedKeyBag with the password -- and every id-envelopedData
- * (public-key privacy) safe with `opts.recipientKey` (RFC 7292 sec. 3.1, via `pki.cms.decrypt`) -- returning a
- * structured bundle `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` -- each private key as PKCS#8
+ * Read a PKCS#12 store: verify its integrity first (a password store's MAC, or a public-key store's CMS
+ * SignedData signature, per RFC 7292 sec. 4 / 5.1, so no bag from a store whose integrity check fails is trusted),
+ * then decrypt every PBES2 privacy safe and pkcs8ShroudedKeyBag with the password, and every id-envelopedData
+ * (public-key privacy) safe with `opts.recipientKey` (RFC 7292 sec. 3.1, via `pki.cms.decrypt`), returning a
+ * structured bundle `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` with each private key as PKCS#8
  * `PrivateKeyInfo` DER (re-validated), each certificate / CRL / secret as raw DER, all carrying their
  * `friendlyName` / `localKeyId` for pairing. `pfx` is the store's DER `Buffer`, a PEM string, or an
- * unmodified `pki.schema.pkcs12.parse` result; a REBUILT parsed store is refused, since the bytes whose
+ * unmodified `pki.schema.pkcs12.parse` result; a rebuilt parsed store is refused, since the bytes whose
  * integrity is checked and the bags returned as checked are separate properties of it.
  *
  * A MAC-less store is refused (`pkcs12/no-integrity`) unless `opts.allowUnauthenticated` is set. A public-key
  * integrity store is verified through `pki.cms.verify` before any bag is trusted; a signature failure is
  * `pkcs12/signature-invalid`, and `signers` carries the per-signer verdict `[{ ok, sid, cert }]` (`null` in
- * password / MAC-less mode). The signer is surfaced, NEVER trust-chained -- anchoring `signers[i].cert` to a
+ * password / MAC-less mode). The signer is surfaced, never trust-chained: anchoring `signers[i].cert` to a
  * trust root is the caller's `pki.path.validate` step (the out-of-path signer contract). Privacy is
  * independent of integrity, so the bag `password` still decrypts a public-key store's bags; a wrong bag
  * password there is the uniform `pkcs12/decrypt-failed` (no MAC to catch it first). Bags encrypted under
- * PBES2 (AES-CBC), or the RFC 7292 App. C legacy schemes an `openssl pkcs12 -legacy` store uses -- 3-key /
- * 2-key Triple-DES-CBC and 40-/128-bit RC2-CBC (the App. B KDF over the BMPString password, RC2 via an in-tree
- * RFC 2268 cipher) -- are decrypted; the legacy RC4 schemes are named and refused.
+ * PBES2 (AES-CBC), or the RFC 7292 App. C legacy schemes an `openssl pkcs12 -legacy` store uses (3-key /
+ * 2-key Triple-DES-CBC and 40-/128-bit RC2-CBC, the App. B KDF over the BMPString password, RC2 via an in-tree
+ * RFC 2268 cipher), are decrypted; the legacy RC4 schemes are named and refused.
  *
  * @opts
- *   - `allowUnauthenticated` (boolean) -- open a MAC-less store anyway (result carries `macVerified: false`).
- *   - `signerCerts` (array of cert DER) -- signer certificate(s) for a public-key store built with `certificates: false` (forwarded to `pki.cms.verify`).
- *   - `recipientKey` (PKCS#8 DER|PEM) + `recipientCert` (cert DER|PEM, or `recipientIndex`) -- decrypt an id-envelopedData (public-key privacy) safe. The recipient key is a privacy credential only; a wrong key / tampered envelope is the uniform `pkcs12/decrypt-failed`, and an enveloped safe with no `recipientKey` is `pkcs12/no-recipient-key`.
- *   - `maxIterations` (number) -- lower the PBKDF2 / MAC iteration cap for this call (downward-only).
- *   - `keys` (string) -- `der` (default) or `crypto` (also `pki.key.import` each private key to a CryptoKey).
+ *   - `allowUnauthenticated` (boolean): open a MAC-less store anyway (result carries `macVerified: false`).
+ *   - `signerCerts` (array of cert DER): signer certificate(s) for a public-key store built with `certificates: false` (forwarded to `pki.cms.verify`).
+ *   - `recipientKey` (PKCS#8 DER|PEM) + `recipientCert` (cert DER|PEM, or `recipientIndex`): decrypt an id-envelopedData (public-key privacy) safe. The recipient key is a privacy credential only; a wrong key / tampered envelope is the uniform `pkcs12/decrypt-failed`, and an enveloped safe with no `recipientKey` is `pkcs12/no-recipient-key`.
+ *   - `maxIterations` (number): lower the PBKDF2 / MAC iteration cap for this call (downward-only).
+ *   - `keys` (string): `der` (default) or `crypto` (also `pki.key.import` each private key to a CryptoKey).
  *   - `importAlgorithm` -- forwarded to `pki.key.import` for the ambiguous RSA / EC arms when `keys: crypto`.
  * @example
  *   var pair = await pki.key.generate("Ed25519");

package/lib/pki-build.js

@@ -6,7 +6,7 @@
 // binds a domain namespace once and returns the shared PKIX producing primitives every signer module
 // composes: the distinguished-name encoder, the GeneralName + RFC 5280 sec. 4.2.1 extension-value
 // encoders, the embedded-input validators (a raw Name / a SubjectPublicKeyInfo / a pre-encoded Extension
-// run through the SAME parser the decoder uses), the sign-scheme bridge, and the post-sign signature
+// run through the same parser the decoder uses), the sign-scheme bridge, and the post-sign signature
 // self-check (the key-match / proof-of-possession verify). Each is parameterized on the CALLER's error
 // class + code prefix, so pki.x509.sign keeps x509/* codes and pki.csr.sign keeps csr/*.
 
@@ -64,7 +64,7 @@ function makeBuilder(ctx) {
   }
   function encodeAtv(attrName, value) {
     if (value == null || value === "") throw E("bad-name", "the " + attrName + " attribute value must be a non-empty string");
-    // oid.byName returns undefined (does not throw) for an unrecognized name -- reject it explicitly.
+    // For an unrecognized name oid.byName returns undefined and does not throw, so reject explicitly.
     var typeOid = O(attrName);
     if (typeOid == null) throw E("bad-name", "unknown distinguished-name attribute " + JSON.stringify(attrName));
     var valueTlv;
@@ -119,8 +119,8 @@ function makeBuilder(ctx) {
       case "uniformResourceIdentifier": case "uri": return b.contextPrimitive(6, ia5Content(v));
       case "iPAddress":
         // Accept a dotted-quad / colon-hex string (packed to its 4/16 network octets) as well as a
-        // pre-packed Buffer, so an iPAddress SAN reads like dNSName/URI rather than forcing the caller
-        // to pack octets by hand (RFC 5280 sec. 4.2.1.6 -- a GeneralName iPAddress is a bare host address).
+        // pre-packed Buffer, so an iPAddress SAN reads like dNSName/URI and the caller does not pack
+        // octets by hand (a GeneralName iPAddress is a bare host address, RFC 5280 sec. 4.2.1.6).
         var ipBuf = v;
         if (typeof v === "string") {
           ipBuf = ipUtils.packIpLiteral(v);
@@ -144,15 +144,15 @@ function makeBuilder(ctx) {
     return b.namedBitString(positions);
   }
   // Resolve an OID token to a dotted-decimal OID: a registered name via the registry, OR a raw dotted-OID
-  // string accepted directly (an unregistered KeyPurposeId / policy OID -- BIMI, document-signing, vendor
-  // purposes -- is a common valid input). A token that is neither fails closed (never silently accept a
+  // string accepted directly (an unregistered KeyPurposeId / policy OID for BIMI, document-signing or a
+  // vendor purpose is a common valid input). A token that is neither fails closed (never silently accept a
   // typo'd name); a dotted string that passes the shape check is still arc-validated by b.oid's encoder.
   function _resolveOid(n, label) {
     var dotted = O(n);
     if (dotted != null) return dotted;
     if (typeof n === "string" && DOTTED_OID_RE.test(n)) {
       // The regex fixes the general shape; b.oid's encoder is the authoritative X.660 arc-bounds check
-      // (a first arc 0/1 caps the second at 39; an arc must DER-encode). A failure there is THIS producer's
+      // (a first arc 0/1 caps the second at 39; an arc must DER-encode). A failure there is this producer's
       // bad-input, not a leaked oid/* code, so every shared-builder consumer keeps its own error contract.
       try { b.oid(n); }
       catch (e) { throw E("bad-input", "invalid " + label + " OID " + JSON.stringify(n) + " (violates the X.660 arc bounds)", e); }
@@ -184,7 +184,7 @@ function makeBuilder(ctx) {
   function extAki(keyid) { return b.sequence([b.contextPrimitive(0, keyid)]); }   // keyIdentifier [0] IMPLICIT OCTET STRING
   // GeneralNames ::= SEQUENCE SIZE(1..MAX) OF GeneralName. With no implicitTag it is a universal SEQUENCE
   // (subjectAltName / issuerAltName / IssuerSerial.issuer). With an implicitTag it is a context-constructed
-  // [n] whose tag REPLACES the SEQUENCE tag (RFC 5755 IMPLICIT TAGS -- Holder.entityName [1],
+  // [n] whose tag REPLACES the SEQUENCE tag (RFC 5755 IMPLICIT TAGS: Holder.entityName [1],
   // RoleSyntax.roleAuthority [0], IetfAttrSyntax.policyAuthority [0]); the [n] node's children ARE the
   // GeneralName members, no inner SEQUENCE wrapper.
   function encodeGeneralNames(entries, implicitTag) {
@@ -213,7 +213,8 @@ function makeBuilder(ctx) {
   }
 
   // The SHA-1 subjectKeyIdentifier (RFC 5280 sec. 4.2.1.2 method 1): SHA-1 of the subjectPublicKey BIT
-  // STRING CONTENT (past the unused-bits octet), NOT the whole SPKI or the BIT STRING TLV.
+  // STRING content, taken past the unused-bits octet. Hashing the whole SPKI or the BIT STRING TLV
+  // gives a different, wrong identifier.
   function spkiKeyId(spkiDer) {
     var keyBytes = asn1.read.bitString(asn1.decode(spkiDer).children[1]).bytes;
     // RFC 5280 sec. 4.2.1.2 method 1 DEFINES the subjectKeyIdentifier as the SHA-1 of the
@@ -233,7 +234,7 @@ function makeBuilder(ctx) {
     if (Buffer.isBuffer(v) || v instanceof Uint8Array) return guard.bytes.snapshot(v, ErrorClass, ctx.prefix + "/bad-input", what);
     throw E("bad-input", what + " must be a DER Buffer");
   }
-  // Full validation of an embedded SubjectPublicKeyInfo via the SAME parser the decoder uses.
+  // Full validation of an embedded SubjectPublicKeyInfo, walked through the parser the decoder uses.
   function assertValidSpki(spkiDer, what) {
     var node;
     try { node = asn1.decode(spkiDer); }
@@ -344,10 +345,11 @@ function makeBuilder(ctx) {
     return { subjectPublicKeyInfo: { algorithm: { oid: keyOid, parameters: alg.children.length > 1 ? alg.children[1].bytes : undefined } } };
   }
 
-  // Confirm the produced signature verifies under `spki` -- key-type-agnostic (a PKCS#8 key, a WebCrypto
-  // CryptoKey, or any signer), where deriving-and-comparing the public key cannot (a non-extractable
-  // CryptoKey has no exportable public half). This is the x509 chain self-check AND the CSR proof of
-  // possession. Composite verifies both components. Returns a promise for composite, sync-throws for classical.
+  // Confirm the produced signature verifies under `spki`. This works for any key type (a PKCS#8
+  // key, a WebCrypto CryptoKey, or any signer), where deriving-and-comparing the public key cannot
+  // (a non-extractable CryptoKey has no exportable public half). This is the x509 chain self-check
+  // AND the CSR proof of possession. Composite verifies both components. Returns a promise for
+  // composite, sync-throws for classical.
   function assertSignatureVerifies(preimage, sig, spki, scheme) {
     if (scheme.composite) {
       return compositeSig.compositeVerify(spki, sig, preimage, scheme.composite, ErrorClass, code("unsupported-algorithm"), code("bad-input")).then(function (r) {
@@ -394,11 +396,11 @@ function tbsNameField(cert, which) {
   return tbs.children[(hasVersion ? 1 : 0) + (which === "subject" ? 4 : 2)].bytes;
 }
 
-// The serialNumber of a parsed X.509 certificate, read from the SIGNED bytes rather than off the
-// object. Same tbs layout as above, and the same reason: where a producer binds an identity to an
-// existing certificate, that identity is issuer AND serial together. Deriving one from the bytes
-// and reading the other from the object lets the halves name different certificates -- a Holder
-// whose issuer is genuine and whose serial is whatever the caller wrote.
+// The serialNumber of a parsed X.509 certificate, read from the SIGNED bytes. Same tbs layout as
+// above, and the same reason: where a producer binds an identity to an existing certificate, that
+// identity is issuer AND serial together. Deriving one from the bytes and reading the other from
+// the object lets the halves name different certificates, producing a Holder whose issuer is
+// genuine and whose serial is whatever the caller wrote.
 function tbsSerialNumber(cert) {
   var tbs = asn1.decode(cert.tbsBytes);
   var hasVersion = tbs.children[0].tagClass === "context" && tbs.children[0].tagNumber === 0;

package/lib/rc2.js

@@ -8,7 +8,7 @@
 //
 // rc2 -- a from-scratch RFC 2268 RC2-CBC. OpenSSL 3.x moved RC2 to the legacy provider (not loaded by Node),
 // so node:crypto cannot decrypt these bags; this in-tree primitive fills that single gap (Hard rule #1: own
-// code, no npm hop -- MANIFEST stays empty; a lib primitive like webcrypto.js, not a lib/vendor/ bundle). The
+// code, no npm hop, so MANIFEST stays empty; it is a lib primitive alongside webcrypto.js, outside lib/vendor/). The
 // RFC 2268 sec. 5 known-answer vectors pin the cipher; the `openssl -legacy` store is the end-to-end KAT.
 
 // RFC 2268 sec. 2: PITABLE, a fixed 256-byte permutation of the digits of pi used by the key schedule.

package/lib/rfc3339.js

@@ -41,13 +41,13 @@ function parse(v, E, code, label) {
   return new Date(v);
 }
 
-// RFC 3339 sec. 5.6 `full-date`: a calendar date with NO time component. A distinct production from
-// the date-time above, and deliberately a separate pair of functions rather than a flag: a consumer
+// RFC 3339 sec. 5.6 `full-date`: a calendar date with no time component. A distinct production from
+// the date-time above, and deliberately a separate pair of functions instead of a flag: a consumer
 // that expects one and is handed the other has a malformed value, not a permissible variant.
 var FULL_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 
 // isValidDate(v) -> boolean: v is a syntactically well-formed AND calendar-valid RFC 3339 full-date.
-// Calendar validity matters as much as shape -- "2021-02-30" parses as a Date in JS by rolling over
+// Calendar validity matters as much as shape: "2021-02-30" parses as a Date in JS by rolling over
 // into March, so a shape-only check would silently accept a day that does not exist.
 function isValidDate(v) {
   if (typeof v !== "string") return false;
@@ -61,8 +61,8 @@ function isValidDate(v) {
 }
 
 // parseDate(v, E, code, label) -> Date at UTC midnight. Anchored explicitly at UTC ("T00:00:00Z")
-// rather than left to `new Date("YYYY-MM-DD")`, so the instant does not shift with the host time
-// zone -- a freshness or rollback comparison must not depend on where it runs.
+// instead of left to `new Date("YYYY-MM-DD")`, so the instant does not shift with the host time
+// zone. A freshness or rollback comparison must not depend on where it runs.
 function parseDate(v, E, code, label) {
   if (!isValidDate(v)) throw E(code, (label || "the value") + " is not a valid RFC 3339 full-date (YYYY-MM-DD)");
   return new Date(v + "T00:00:00Z");