@blamejs/pki 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.5 — 2026-08-15
+
+A verdict is computed over the bytes the parser read, an identity is derived from the bytes that carry it, and the guards match no patterns.
+
+### Changed
+
+- The package resolves one entry point. require("@blamejs/pki") is unchanged; a path INTO the package, such as require("@blamejs/pki/lib/schema-x509"), no longer resolves. Every module under lib/ carries @internal in its own header and none has ever appeared in the API snapshot that freezes the public surface -- they were reachable because the package declared no exports map, not because they were offered, and one of them mints the provenance record the integrity verbs above rely on. Everything the internals do is on pki.*: the decoders are pki.schema.<format>.parse, the codec is pki.asn1, the OID registry is pki.oid, the error classes are pki.errors. MIGRATING.md carries the recipe.
+- pki.merkle, pki.jose, pki.hpke, pki.smime and pki.est refuse an option they do not recognize, which completes the toolkit -- every module that takes options now does. A misspelled option is the one input that reads as an omission rather than as a value, so the caller who asked for something stricter gets the looser default and is told nothing: a misspelled psk leaves an HPKE psk-mode setup with no pre-shared key, a misspelled key leaves pki.jose.verify accepting whichever key the message names, a misspelled leafIndex leaves a Merkle inclusion proof about a leaf the caller never chose, a misspelled strictMicalg accepts the S/MIME digest mismatch it was set to reject, and a misspelled expectedRecipientKeyId drops the recipient pin on an EST server-generated private key. The accepted set is per verb rather than per module, because the surfaces differ -- form means something to pki.smime.sign and nothing to pki.smime.encrypt, strict cannot run on pki.est.cacerts at all, and HPKE's two ends read the same object from opposite sides, so senderPublicKey does nothing at the sender and senderKey nothing at the recipient. A merged set would accept each verb's options everywhere and reproduce the silence in a wider form, which is why an option passed to the wrong end of an HPKE exchange is refused with a message saying where it belongs rather than ignored -- the caller who passed it usually believes they authenticated something. Four options pki.smime.sign has always forwarded (hcp, sid, signedAttributes, additionalSignedAttributes) and EST's auth object are now documented; they worked before and were absent from the reference.
+- The guards match no patterns. A guard runs on the most hostile input the toolkit sees, and a pattern engine's cost on a rejecting string is a property of the pattern rather than of the length -- the one thing a caller's size cap cannot bound. Nine patterns across five guards are now explicit character walks, each one pass. Three carried a second defect settled by the rewrite: the whitespace fold above, a JSON number grammar written twice (once as the scan and once as a pattern re-matching what the scan had just read), and an RFC 4514 escape that ran a pattern replace and then a second loop over the same attacker-supplied value.
+
+### Fixed
+
+- A claimed-parsed structure must carry every field the matching pki.schema parser produces. The rule already existed at one door -- pki.path.build refused a partial claimed-parsed certificate -- while pki.path.validate, which build hands its result to, tested only for a truthy tbsBytes and passed the object into the RFC 5280 sec. 6.1 walk. Eleven doors now share it: pki.path.validate and build, pki.path.crlChecker, pki.crl.verify / isRevoked and the issuer of pki.crl.sign, the issuer of pki.x509.sign, pki.attrcert.sign, pki.ocsp's certificate argument, pki.lint, and the caller root certificates pki.webauthn takes for attestation and for android-safetynet. Completeness is measured against the parser rather than against what any one verb reads, because a field absent from an object is not a field with a safe default: an extension entry with no critical property read as non-critical, so a certificate rejected for an unknown critical extension when passed as bytes validated when passed as an object; a missing serialNumber surfaced as an error from the ASN.1 layer; and a missing issuer.bytes produced an OCSP request whose issuerNameHash covered nothing. Passing bytes, PEM, or the parser's own unmodified output is unaffected.
+- A certificate or CRL a verdict is taken from is re-derived from the bytes its parser read. pki.path.validate and build, pki.path.crlChecker, pki.crl.verify and pki.crl.isRevoked all reach a decision, and completeness alone cannot carry one: a certificate is one signature over one byte range, but a parsed certificate presents that range, the signature, and every field the range encodes as separate properties. Keep a real CA certificate's signed bytes and signature and replace only its subjectPublicKeyInfo, and every field is well-formed, the signature verifies over the original range, and the substituted key is then what verifies the next certificate in the chain -- a forged chain built out of a genuine certificate. Emptying extensions is the same move against basicConstraints, keyUsage, name constraints and the unknown-critical rule; emptying a CRL's revokedCertificates leaves a correctly signed CRL reporting a revoked certificate as good. pki.schema.x509.parse and pki.schema.crl.parse now record what they read, these verbs parse it again from that record, and a certificate or CRL a caller assembled rather than parsed is refused. Passing bytes, PEM, or the parser's own unmodified output is unaffected.
+- pki.ocsp.verify, pki.path.verifyOcspResponse, pki.pkcs12.verifyMac and pki.pkcs12.open compute their verdict over the bytes the parser read. A signature check has three parts -- the signature, the algorithm that verifies it, and the byte range it covers -- and on a parsed response all three are separate properties: pair a real CA's signature over a certificate that CA issued with that certificate's own signed bytes and algorithm, relabel the three, and every part of the check passes for a response the responder never produced. A PKCS#12 store has the same shape with two parts, the range the MAC covers and the bags handed back as verified, so one object could say verify this and return that. The parsers now record what they parsed and these verbs re-derive from that record, so an object edited or rebuilt after parsing is not what the verdict describes. Passing the parser's own result still works and is unchanged.
+- pki.attrcert.sign derives both halves of a Holder's identity from the signed bytes. Issuer and serial together ARE the identity being bound; the issuer was decoded from tbsBytes while the serial was read off the object, so a parsed certificate with one field replaced produced a Holder naming a real issuer with a serial nobody issued.
+- pki.trust.anchor answers from what the store read. A root program's metadata -- these purposes, until this date -- is a statement about a KEY, so an entry rebuilt with a substituted publicKey carried the program's word onto a key it never saw; the (name, key) pair is now re-derived from the certificate the store parsed, and an entry carrying store metadata without that provenance is refused. The purposes and distrust dates come from the same place and are copied on the way out, so neither editing a store entry nor writing through a returned anchor changes what that anchor authorizes -- pki.trust.anchor(entry).purposes.serverAuth = true no longer opens a gate the store never opened, and an anchor reports the store's bits and dates however the caller has since handled the entry. A caller asserting their own bare (name, key) anchor carries no metadata and is unaffected.
+- A private key decoded for the crypto engine is wiped once the engine has imported it. A signer or recipient key may be given as a Buffer, a Uint8Array, or a PEM string; the first is the caller's own memory and is used in place, while the other two are decoded into a new buffer inside the toolkit -- a second copy of a private key, which until now stayed readable in the heap until the garbage collector happened to reuse the page. It is cleared on the failure path too, so a malformed key or a tampered message is not a way to leave one behind. A Buffer you supply is never written to: it is yours, you still hold it, and clearing it would destroy the key rather than protect it.
+- pki.webauthn.verifyAssertion holds both accepted forms of a stored credential key to the same rules. The COSE bytes went through the curve and length rules, the 2048-bit RSA modulus floor and the exponent checks; the object form went through none, so one key was refused in one form and imported for signature verification in the other. Which form a relying party stores is a question about what their datastore round-trips, not about how carefully their credential is checked.
+- A certificate's keyUsage is read the same way at every boundary that asks what the certificate may do. keyUsage is a NamedBitList, so DER drops its trailing zero bits (X.690 sec. 11.2.2) and RFC 5280 sec. 4.2.1.3 requires at least one bit set. Four boundaries read the bits themselves and applied neither rule, so one certificate could be authorized in one place and called malformed everywhere else: pki.crl.verify accepting a CRL signer, pki.tsp.verify accepting a timestamp authority, pki.cms.encrypt accepting a recipient, and the FIDO metadata reader accepting the leaf that signs a catalogue.
+- The distinguished-name comparison that decides name chaining, revocation-issuer matching and name constraints folds the four ASCII whitespace characters X.520's caseIgnoreMatch names, and no others. It had been collapsing whitespace with a pattern, which also folds vertical tab, form feed, no-break space and every Unicode space separator -- equating names X.520 keeps distinct.
+
 ## v0.5.4 — 2026-08-15
 
 A path verdict says whether revocation was ever established, a trust anchor's own distrust metadata can no longer sit inert, and a CRL is asked what only a certificate can answer.

package/MIGRATING.md

@@ -7,3 +7,34 @@ Some breaking changes cannot warn at runtime: an on-disk format break or a wire-
 ## No active deprecations
 
 The toolkit has no `deprecate()`-marked surface awaiting removal.
+
+---
+
+## Out-of-band breaking changes
+
+Listed newest-first.
+
+### v0.5.5 — `require("@blamejs/pki/lib/...")`
+
+The package resolves one entry point; a path into the package no longer resolves.
+
+`require("@blamejs/pki")` and `import ... from "@blamejs/pki"` are unchanged. What no
+longer resolves is a path INTO the package:
+
+```
+require("@blamejs/pki/lib/schema-x509")   // ERR_PACKAGE_PATH_NOT_EXPORTED
+```
+
+Every module under `lib/` carries `@internal` in its own header and none has ever appeared
+in the API snapshot that freezes the public surface. They were reachable because the package
+declared no `exports` map, not because they were offered -- and one of them mints the
+provenance record the OCSP and PKCS#12 integrity verbs rely on, which reachable from outside
+could be minted for any object.
+
+Everything the internals do is on `pki.*`: the decoders are `pki.schema.<format>.parse`, the
+codec is `pki.asn1`, the OID registry is `pki.oid`, the error classes are `pki.errors`. If you
+are reaching for something with no `pki.*` route, that is a gap worth reporting rather than a
+module worth importing -- the internals change shape between patch releases and carry no
+compatibility promise.
+
+`require("@blamejs/pki/package.json")` still resolves, for tooling that reads the version.

package/lib/attrcert-sign.js

@@ -83,12 +83,13 @@ var _tbsNameBytes = pkiBuild.tbsNameField;   // the AA issuerName / holder baseC
 // Parse a certificate DER/PEM (or accept a parsed certificate), re-typing a raw x509/* parse fault to the
 // attrcert domain so a malformed AA cert / holder cert surfaces attrcert/*, not a foreign CertificateError.
 function _parseCert(cert, what) {
-  if (!Buffer.isBuffer(cert) && typeof cert !== "string") {
-    if (!cert || !cert.tbsBytes) throw _err("attrcert/bad-input", what + " must be a certificate DER/PEM or a parsed certificate");
-    return cert;
-  }
-  try { return x509.parse(cert); }
-  catch (e) { if (e instanceof AttrCertError) throw e; throw _err("attrcert/bad-input", what + " is not a well-formed certificate", e); }
+  // Re-derived from the bytes its parser read. Issuer and serial together ARE the Holder's identity,
+  // so a certificate assembled from parts could bind an attribute certificate to a holder that no
+  // issuer ever named.
+  return guard.parsed.acceptDerived(cert, "certificate", function (bytes) {
+    try { return x509.parse(bytes); }
+    catch (e) { if (e instanceof AttrCertError) throw e; throw _err("attrcert/bad-input", what + " is not a well-formed certificate", e); }
+  }, _err, "attrcert/bad-input", what);
 }
 // The raw content octets of an OBJECT IDENTIFIER (past its own tag+len) -- the body of a [0] IMPLICIT OID.
 function _oidContent(name) {
@@ -149,8 +150,11 @@ function _encodeHolder(holder) {
   if (holder.fromCertificate != null) {
     // Bind to a public-key certificate's identity: baseCertificateID = { issuer = the PKC's issuer DN as a
     // directoryName, serial = the PKC serialNumber } (RFC 5755 sec. 4.1 / 7.3).
+    // BOTH halves from the signed bytes. issuer and serial together ARE the identity, so deriving
+    // the issuer from tbsBytes while reading the serial off the object let the two name different
+    // certificates: a Holder with a genuine issuer DN and whatever serial the caller wrote.
     var pkc = _parseCert(holder.fromCertificate, "holder.fromCertificate");
-    var content = _issuerSerialContent({ issuer: [{ directoryName: _tbsNameBytes(pkc, "issuer") }], serial: pkc.serialNumber });
+    var content = _issuerSerialContent({ issuer: [{ directoryName: _tbsNameBytes(pkc, "issuer") }], serial: pkiBuild.tbsSerialNumber(pkc) });
     return b.sequence([b.contextConstructed(0, content)]);
   }
   // objectDigestInfo [2] IMPLICIT ObjectDigestInfo.

package/lib/cmp-session.js

@@ -129,12 +129,24 @@ function _boundedPool(base, added) {
 // the unsigned extraCerts ordering, so a corrupted-signature copy sharing a valid issuer's TBS must NOT collapse
 // onto it and evict the valid one. Returns null when the identity cannot be derived; a NON-deduped entry is safe
 // (a redundant slot), a wrong merge (dropping a distinct or the only valid certificate) is not.
+// The identity comes from the SAME derivation every other certificate door uses: the bytes the
+// parser recorded, never the fields of the object handed in. This is a dedupe rather than a verdict,
+// and no collision attack on it is apparent -- carrying another certificate's exact tbsBytes AND
+// signature means being that certificate. But "no attack is apparent" is the reasoning that put a
+// completeness-only door on nine deciding boundaries, so it is not the reasoning this uses: one
+// derivation for certificates, everywhere, and the exceptions have to argue for themselves.
+//
+// Failure returns null rather than throwing, which is this function's own contract and is why the
+// door is wrapped: an underivable identity is a redundant pool slot, while a wrong merge (dropping
+// a distinct or the only valid certificate) is not. So a rebuilt entry simply does not dedupe.
 function _certIdentity(cert) {
   try {
-    var p = (cert && Buffer.isBuffer(cert.tbsBytes)) ? cert : x509.parse(cert);   // x509.parse accepts a DER Buffer OR a PEM string
-    if (!p || !Buffer.isBuffer(p.tbsBytes)) return null;
-    return p.tbsBytes.toString("base64") + "|" + (p.signatureValue && p.signatureValue.bytes ? p.signatureValue.bytes.toString("base64") : "");
-  } catch (_e) { return null; }
+    var p = guard.parsed.acceptDerived(cert, "certificate", x509.parse, _err, "cmp/bad-input", "a pool certificate");
+    if (!guard.parsed.isCert(p)) return null;
+    return p.tbsBytes.toString("base64") + "|" + p.signatureValue.bytes.toString("base64");
+  } catch (_e) {
+    return null;   // underivable: kept as its own slot, never merged onto another certificate's
+  }
 }
 
 // A canonical identity for a SubjectPublicKeyInfo: the algorithm OID + the AlgorithmIdentifier parameters +
@@ -383,12 +395,13 @@ function session(opts) {
     var _es = opts.expectedSender;
     try {
       if (_es && Buffer.isBuffer(_es.tbsBytes)) {   // the documented already-parsed form (pki.schema.x509.parse output), detected like _certIdentity
-        // A Buffer tbsBytes alone is NOT a complete parsed certificate: senderBoundToCert dereferences subject /
-        // subjectAltName, so a partial object (e.g. { tbsBytes }) would pass here and then throw a raw TypeError
-        // mid-transaction, consuming the one-shot session for a local config error. Validate the FULL shape now
-        // with the same coerceCert check the path engine applies to every parsed-cert input.
-        if (_engine && _engine.coerceCert) _engine.coerceCert(_es);
-        _expectedSenderCert = _es;
+        // The door's RETURN is what gets pinned, not the object handed in. coerceCert re-derives the
+        // certificate from the bytes its parser read, so calling it only as a check and then storing
+        // the caller's object keeps every edit the re-derivation exists to discard: this pin is
+        // compared against each response signer's subject and SAN, so an edited one would accept a
+        // different CMP signer than the caller meant to pin. A validator that normalizes has its
+        // return value as its contract -- using it as a predicate throws that contract away.
+        _expectedSenderCert = (_engine && _engine.coerceCert) ? _engine.coerceCert(_es) : _es;
       }
       else if (Buffer.isBuffer(_es) || _es instanceof Uint8Array) { _expectedSenderDer = Buffer.from(_es); _expectedSenderCert = x509.parse(_expectedSenderDer); }
       else if (typeof _es === "string") { _expectedSenderDer = x509.pemDecode(_es); _expectedSenderCert = x509.parse(_expectedSenderDer); }

package/lib/cmp-verify.js

@@ -506,11 +506,19 @@ async function _verifySignature(m, protectedPart, protectionAlg, protection, opt
 // A canonical certificate identity (tbs + signature) for the extraCerts pool dedup: it keys a Buffer /
 // Uint8Array (parse) and an already-parsed candidate object identically (path.build accepts both forms), so
 // an extraCert duplicating a caller intermediate is dropped regardless of which representation the caller used.
+// The key is derived from the bytes the parser recorded, through the same door every other
+// certificate boundary uses -- never from the fields of the object handed in. Deriving it from a
+// caller-shaped object would let two different certificates collapse onto one key, which is the one
+// outcome this must not have. Failure returns null (the caller's contract here): an underivable
+// identity leaves a redundant pool slot, which is safe, while a wrong merge is not.
 function _certKey(c) {
-  var p = c;
-  if (Buffer.isBuffer(c) || c instanceof Uint8Array) { try { p = x509.parse(c); } catch (_e) { return null; } }
-  if (!p || !p.tbsBytes) return null;
-  return p.tbsBytes.toString("base64") + "|" + (p.signatureValue && p.signatureValue.bytes ? p.signatureValue.bytes.toString("base64") : "");
+  try {
+    var p = guard.parsed.acceptDerived(c, "certificate", x509.parse, _err, "cmp/bad-input", "a pool certificate");
+    if (!guard.parsed.isCert(p)) return null;
+    return p.tbsBytes.toString("base64") + "|" + p.signatureValue.bytes.toString("base64");
+  } catch (_e) {
+    return null;   // underivable: kept as its own slot, never merged onto another certificate's
+  }
 }
 
 async function _chainSigner(signer, m, opts, extra) {

package/lib/cms-decrypt.js

@@ -211,41 +211,55 @@ async function _acquireCek(ri, km, opts) {
 // ktri: OAEP or PKCS#1 v1.5 (v1.5 = decrypt-only + RFC 3218 implicit rejection).
 async function _ktriCek(ri, km) {
   var kea = ri.keyEncryptionAlgorithm;
-  var keyDer = _normKeyDer(km.key);
-  if (kea.oid === O("rsaesOaep")) {
-    var hash = _oaepHashFromParams(kea.parameters);
-    var pub = await subtle.importKey("pkcs8", keyDer, { name: "RSA-OAEP", hash: hash }, false, ["decrypt"]);
-    return Buffer.from(await subtle.decrypt({ name: "RSA-OAEP" }, pub, ri.encryptedKey));
-  }
-  if (kea.oid === O("rsaEncryption")) {
-    // RFC 3218 sec. 2.3.2 implicit rejection: NEVER surface a v1.5 failure here. Any decode fault
-    // yields a fresh random CEK of the content-alg length; the mismatch emerges at stage 3.
-    var keyObj = nodeCrypto.createPrivateKey({ key: keyDer, format: "der", type: "pkcs8" });
-    try { return nodeCrypto.privateDecrypt({ key: keyObj, padding: nodeCrypto.constants.RSA_PKCS1_PADDING }, ri.encryptedKey); }
-    catch (_e) { return null; } // signal: use a random CEK (length decided at open time)
+  var k = _normKeyDer(km.key);
+  // The wipe is in a `finally` so it happens on the reject path too: a message crafted to fail the
+  // unwrap must not be a way to leave the key copy in memory.
+  try {
+    if (kea.oid === O("rsaesOaep")) {
+      var hash = _oaepHashFromParams(kea.parameters);
+      var pub = await subtle.importKey("pkcs8", k.der, { name: "RSA-OAEP", hash: hash }, false, ["decrypt"]);
+      return Buffer.from(await subtle.decrypt({ name: "RSA-OAEP" }, pub, ri.encryptedKey));
+    }
+    if (kea.oid === O("rsaEncryption")) {
+      // RFC 3218 sec. 2.3.2 implicit rejection: NEVER surface a v1.5 failure here. Any decode fault
+      // yields a fresh random CEK of the content-alg length; the mismatch emerges at stage 3.
+      var keyObj = nodeCrypto.createPrivateKey({ key: k.der, format: "der", type: "pkcs8" });
+      try { return nodeCrypto.privateDecrypt({ key: keyObj, padding: nodeCrypto.constants.RSA_PKCS1_PADDING }, ri.encryptedKey); }
+      catch (_e) {
+        return null; // signal: use a random CEK (length decided at open time)
+      }
+    }
+    // Coverage residual: reachable only from a hostile message (our encrypt emits only OAEP; OpenSSL
+    // emits OAEP or rsaEncryption) -- a fail-closed reject the fuzz harness exercises.
+    throw _err("cms/unsupported-algorithm", "unsupported ktri keyEncryptionAlgorithm " + kea.oid);
+  } finally {
+    _releaseKeyDer(k);
   }
-  // Coverage residual: reachable only from a hostile message (our encrypt emits only OAEP; OpenSSL
-  // emits OAEP or rsaEncryption) -- a fail-closed reject the fuzz harness exercises.
-  throw _err("cms/unsupported-algorithm", "unsupported ktri keyEncryptionAlgorithm " + kea.oid);
 }
 
 // kari: reconstruct Z from the originatorKey + recipient private key, KDF -> KEK, AES-KW unwrap.
 async function _kariCek(ri, km) {
-  var keyDer = _normKeyDer(km.key);
-  var kea = ri.keyEncryptionAlgorithm;
-  var wrapAlg = _kariWrap(kea);
-  var scheme = kea.oid;
-  var origSpki = _originatorSpki(ri.originator);
-  // Unwrap THIS recipient's RecipientEncryptedKey (matched by rid), not element 0 -- a kari may list
-  // several recipients under one ephemeral key.
-  var rek = (km.cert != null && _kariRekFor(ri, x509.parse(_normCertDer(km.cert)))) || ri.recipientEncryptedKeys[0];
-  var kekBytes = WRAP_KEK_LENGTHS[wrapAlg.oid];
-  if (!kekBytes) throw _err("cms/unsupported-algorithm", "unsupported kari key-wrap");
-  var ukm = ri.ukm || null;
+  // The copy is taken and the protected region opens IMMEDIATELY. Everything between them would
+  // otherwise be an unprotected window, and it is not a narrow one: reading the wrap algorithm, the
+  // originator's key, the recipient's certificate and the matching RecipientEncryptedKey all parse
+  // attacker-supplied structure and all throw on malformed input. A message crafted to fail any one
+  // of them would be a way to leave the key copy in the heap -- the exact outcome the wipe is for.
+  var k = _normKeyDer(km.key);
   // The agreement secret and the KEK derived from it are both allocated here; one `finally` clears
   // whichever branch produced them, including when the unwrap below throws on a tampered key.
   var kek, z, mz;
   try {
+    var keyDer = k.der;
+    var kea = ri.keyEncryptionAlgorithm;
+    var wrapAlg = _kariWrap(kea);
+    var scheme = kea.oid;
+    var origSpki = _originatorSpki(ri.originator);
+    // Unwrap THIS recipient's RecipientEncryptedKey (matched by rid), not element 0 -- a kari may list
+    // several recipients under one ephemeral key.
+    var rek = (km.cert != null && _kariRekFor(ri, x509.parse(_normCertDer(km.cert)))) || ri.recipientEncryptedKeys[0];
+    var kekBytes = WRAP_KEK_LENGTHS[wrapAlg.oid];
+    if (!kekBytes) throw _err("cms/unsupported-algorithm", "unsupported kari key-wrap");
+    var ukm = ri.ukm || null;
     if (_isMont(origSpki)) {
       var mont = _montName(origSpki);
       var recipPriv = await subtle.importKey("pkcs8", keyDer, { name: mont.name }, false, ["deriveBits"]);
@@ -275,6 +289,7 @@ async function _kariCek(ri, km) {
     return await _aesKwUnwrap(kek, rek.encryptedKey);
   } finally {
     guard.secret.zeroizeAll([z, mz, kek], CmsError, "cms/bad-input", "the key-agreement shared secret");
+    _releaseKeyDer(k);
   }
 }
 
@@ -333,7 +348,12 @@ async function _kemriCek(ri, km) {
   var kekBytes = Number(k.kekLength);
   var wrapAlg = k.wrap;
   if (WRAP_KEK_LENGTHS[wrapAlg.oid] !== kekBytes) throw _fail(); // M29 re-check on the consumer path
-  var priv = await subtle.importKey("pkcs8", _normKeyDer(km.key), { name: wcName }, false, ["decapsulateBits"]);
+  // The decapsulation key copy is released as soon as the engine has imported it -- the import is
+  // the only thing that reads it, so its lifetime does not need to span the decapsulation below.
+  var keyCopy = _normKeyDer(km.key);
+  var priv;
+  try { priv = await subtle.importKey("pkcs8", keyCopy.der, { name: wcName }, false, ["decapsulateBits"]); }
+  finally { _releaseKeyDer(keyCopy); }
   var ss = null, kek = null, ssAb = null, kekAb = null;
   try {
     // The engine hands back an ArrayBuffer it allocated, and the Buffer below is a copy of it. Both
@@ -706,12 +726,33 @@ async function _verifyAuthenticatedData(parsed, km, opts) {
 //   * the `macKey == null` half of the random-key substitution fires only for a hand-crafted RSA v1.5
 //     ktri (this producer emits OAEP); its behaviour is identical to the tested below-floor path (a
 //     random key -> the MAC verify fails uniformly), so the < 16 vector covers the substitution.
+// _normKeyDer(key) -> { der, owned } -- the recipient private key as PKCS#8 DER, and whether the
+// buffer is one THIS module made.
+//
+// The distinction decides who may wipe it. A caller handing in their own Buffer keeps a live
+// reference and will use it again; wiping that would destroy the key out from under them. The other
+// two forms produce a NEW buffer here -- a Uint8Array is copied, a PEM string is decoded -- and that
+// buffer is a second copy of a private key which nothing else can reach, so it lives until the
+// garbage collector happens to reuse the page unless this module clears it.
+//
+// Returning the flag rather than always copying keeps the caller's buffer un-duplicated: making our
+// own copy of every key so we could uniformly wipe it would ADD a copy of the secret to solve the
+// problem of having one.
 function _normKeyDer(key) {
-  if (Buffer.isBuffer(key)) return key;
-  if (key instanceof Uint8Array) return Buffer.from(key);
-  if (typeof key === "string") { try { return pkcs8.pemDecode(key); } catch (e) { throw _err("cms/bad-input", "the recipient private-key PEM could not be decoded", e); } }
+  if (Buffer.isBuffer(key)) return { der: key, owned: false };
+  if (key instanceof Uint8Array) return { der: Buffer.from(key), owned: true };
+  if (typeof key === "string") {
+    var der;
+    try { der = pkcs8.pemDecode(key); }
+    catch (e) { throw _err("cms/bad-input", "the recipient private-key PEM could not be decoded", e); }
+    return { der: der, owned: true };
+  }
   throw _err("cms/bad-input", "the recipient private key must be a PKCS#8 DER Buffer or PEM string");
 }
+// Wipe a key buffer this module owns. A no-op for the caller's own Buffer, which is theirs.
+function _releaseKeyDer(k) {
+  if (k && k.owned) guard.secret.zeroize(k.der, CmsError, "cms/bad-input", "the recipient private-key copy");
+}
 function _normCertDer(cert) {
   if (Buffer.isBuffer(cert)) return cert;
   if (cert instanceof Uint8Array) return Buffer.from(cert);

package/lib/crl-sign.js

@@ -375,9 +375,10 @@ function _buildRevoked(entryList, isDelta) {
 // ---- the primitives --------------------------------------------------------
 
 function _parseIssuerCert(cert) {
-  var parsed = (Buffer.isBuffer(cert) || typeof cert === "string") ? x509Schema.parse(cert) : cert;
-  if (!parsed || !parsed.tbsBytes || !parsed.subjectPublicKeyInfo) throw _err("crl/bad-input", "issuer.cert must be a certificate DER/PEM or a parsed certificate");
-  return parsed;
+  // The issuer certificate decides who may have signed this CRL: its key verifies the signature and
+  // its keyUsage says whether it may sign CRLs at all. A caller-assembled one could carry a real
+  // CA's name and cRLSign bit beside a substituted key, so it is re-derived like every other.
+  return guard.parsed.acceptDerived(cert, "certificate", x509Schema.parse, _err, "crl/bad-input", "issuer.cert");
 }
 
 // RFC 5280 sec. 4.2.1.3 -- a certificate whose key signs CRLs asserts the cRLSign keyUsage bit. When the
@@ -508,10 +509,15 @@ function _sign(spec, issuer, opts) {
  */
 function sign(spec, issuer, opts) { return Promise.resolve().then(function () { return _sign(spec, issuer, opts); }); }
 
+// A CRL these verbs answer from is re-derived from the bytes its parser read. Completeness -- every
+// field present with the right type -- is not enough for a verdict: the signature covers a byte
+// range, while the revocation list and the scope extensions are separate properties of the parsed
+// object. Keep a correctly signed CRL's `tbsBytes` and signature and empty `revokedCertificates`,
+// and the signature still verifies while `isRevoked` answers from the edited list. An emptied
+// `crlExtensions` does the same to scope: a shard that may only speak for some reasons, or a delta
+// that may not answer alone, becomes one that answers for everything.
 function _coerceCrl(crl) {
-  if (Buffer.isBuffer(crl) || typeof crl === "string") return crlSchema.parse(crl);
-  if (crl && typeof crl === "object" && crl.tbsBytes && crl.signatureValue && crl.signatureAlgorithm) return crl;
-  throw _err("crl/bad-input", "crl must be a CRL DER Buffer, a PEM string, or a parsed CRL (from pki.schema.crl.parse)");
+  return guard.parsed.acceptDerived(crl, "crl", crlSchema.parse, _err, "crl/bad-input", "the CRL");
 }
 
 // The issuer's key AND, when the caller supplied a certificate rather than a bare key, the
@@ -523,7 +529,13 @@ function _resolveIssuer(issuer) {
   if (Buffer.isBuffer(issuer)) { _assertValidSpki(issuer, "issuer SPKI"); return { spki: issuer, cert: null }; }
   if (issuer.cert != null) { var ic = _parseIssuerCert(issuer.cert); return { spki: ic.subjectPublicKeyInfo.bytes, cert: ic }; }
   if (issuer.publicKey != null) { var spki = _reqDer(issuer.publicKey, "issuer.publicKey"); _assertValidSpki(spki, "issuer.publicKey"); return { spki: spki, cert: null }; }
-  if (issuer.subjectPublicKeyInfo && issuer.subjectPublicKeyInfo.bytes) return { spki: issuer.subjectPublicKeyInfo.bytes, cert: issuer };   // a parsed certificate
+  // A parsed certificate passed directly. It reaches the same identity and cRLSign checks the
+  // { cert } form does, so it goes through the same door: an object carrying an SPKI but missing
+  // the subject those checks compare would decide them on undefined.
+  if (issuer.subjectPublicKeyInfo && issuer.subjectPublicKeyInfo.bytes) {
+    var pc = _parseIssuerCert(issuer);
+    return { spki: pc.subjectPublicKeyInfo.bytes, cert: pc };
+  }
   throw _err("crl/bad-input", "issuer must be { cert }, { publicKey } (SPKI DER), or a raw SPKI Buffer");
 }
 

package/lib/est.js

@@ -86,6 +86,59 @@ var OID_TEMPLATE = oid.byName("certificationRequestInfoTemplate");
 
 var OPERATIONS = ["cacerts", "simpleenroll", "simplereenroll", "fullcmc", "serverkeygen", "csrattrs"];
 
+// ---- the option surface each verb accepts -----------------------------------
+//
+// A misspelled option reads as an omission rather than as a value: nothing is out of range and
+// nothing fails to parse, so the caller who asked for something stricter gets the looser default
+// and is told nothing. That is worst here, where the options carry the security posture of a
+// network exchange -- a misspelled `tls` leaves the anchors unset (the no-anchors refusal names
+// the missing pin, so this one is caught), a misspelled `strict` accepts the extra certificates it
+// was set to reject, a misspelled `expectedRecipientKeyId` drops a recipient pin on a
+// server-generated private key, and a misspelled `oldCert` fails the re-enrollment outright.
+//
+// Every network verb shares the client surface, because every one of them goes through _client and
+// the redirect / authentication plumbing it drives. The per-verb tables extend it rather than
+// restating it, so a key added to the client reaches every verb at once and none of them drifts.
+var CLIENT_OPTS = {
+  transport: 1, tls: 1, label: 1, timeout: 1, maxResponseBytes: 1, maxRedirects: 1, now: 1,
+  auth: 1, username: 1, password: 1, allowCrossOriginRedirect: 1,
+};
+function _withClient(extra) {
+  var out = {};
+  Object.keys(CLIENT_OPTS).forEach(function (k) { out[k] = 1; });
+  Object.keys(extra || {}).forEach(function (k) { out[k] = 1; });
+  return out;
+}
+// `strict` is enroll-only: _certsResult reads it after the /cacerts branch has already returned, so
+// accepting it on cacerts would advertise a check that cannot run there.
+var CACERTS_OPTS = _withClient(null);
+var SIMPLEENROLL_OPTS = _withClient({ strict: 1 });
+var SIMPLEREENROLL_OPTS = _withClient({ strict: 1, oldCert: 1 });
+// expectedRecipientKind is NOT here: it is derived from the CSR's own advertised attribute, never
+// taken from the caller, so listing it would offer a pin that nothing reads.
+var SERVERKEYGEN_OPTS = _withClient({
+  requestedEncryption: 1, expectedRecipientKeyId: 1, expectedRecipientIssuerSerial: 1,
+});
+var CSRATTRS_OPTS = _withClient(null);
+var FULLCMC_OPTS = _withClient({
+  transactionId: 1, senderNonce: 1, dataReturn: 1,
+  responderCerts: 1, responseRecipient: 1, allowUnverifiedResponse: 1,
+});
+// The two verbs that take options without going near the network.
+var CLASSIFY_OPTS = { op: 1, now: 1 };
+var PATHS_OPTS = { label: 1 };
+var PARSE_SERVERKEYGEN_OPTS = {
+  requestedEncryption: 1, expectedRecipientKeyId: 1, expectedRecipientKind: 1,
+  expectedRecipientIssuerSerial: 1,
+};
+
+function _knownOpts(opts, known, verb) {
+  guard.identifier.assertKnownKeys(opts, known, E, "est/bad-input", function (k) {
+    return "unknown option " + JSON.stringify(k) + " for pki.est." + verb + " -- accepted: " +
+      Object.keys(known).sort().join(", ");
+  });
+}
+
 // ---- the RFC 8951 sec. 3/3.1 transfer codec (CTE-header-blind) -----------
 
 /**
@@ -397,6 +450,7 @@ function _partMediaType(contentType) {
 
 function parseServerKeygenResponse(body, contentType, opts) {
   opts = opts || {};
+  _knownOpts(opts, PARSE_SERVERKEYGEN_OPTS, "parseServerKeygenResponse");
   var parts = splitMultipartMixed(body, contentType);
   if (parts.length !== 2) throw E("est/bad-multipart", "a serverkeygen response must have exactly two parts (RFC 7030 sec. 4.4.2)");
   var keyPart = null, certPart = null, encrypted = false;
@@ -524,6 +578,7 @@ var NOT_IMPLEMENTED_OPS = { fullcmc: 1 };
  */
 function classifyResponse(status, headers, body, opts) {
   opts = opts || {};
+  _knownOpts(opts, CLASSIFY_OPTS, "classifyResponse");
   var op = opts.op;
   // Fail closed on an operation whose response this client cannot validate:
   // A named op this client cannot validate is a typo, not a pass. An
@@ -618,6 +673,7 @@ function classifyResponse(status, headers, body, opts) {
  */
 function paths(baseUrl, opts) {
   opts = opts || {};
+  _knownOpts(opts, PATHS_OPTS, "paths");
   var prefix = String(baseUrl).replace(/\/+$/, "") + "/.well-known/est";
   if (opts.label != null) {
     var label = String(opts.label);
@@ -1152,6 +1208,11 @@ function fullcmc(baseUrl, request, opts) {
   var der, wanted, sent;
   try {
     if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw E("est/bad-input", "pki.est.fullcmc options must be an object");
+    // Inside the try, so the refusal is a REJECTION like every other failure of this verb: it is
+    // documented as Promise-returning, and a synchronous throw escapes the `.catch(...)` a caller
+    // has already written. It stays in the synchronous capture rather than moving into a later turn,
+    // because that is what closes the race described above.
+    _knownOpts(opts, FULLCMC_OPTS, "fullcmc");
     der = _cmcRequestDer(request);
     // Confirm this IS a Full PKI Request before any of it goes over the wire. The
     // bytes are about to be labelled `smime-type=CMC-request`, so a PKIResponse or
@@ -1750,6 +1811,10 @@ function _enroll(op, baseUrl, csrInput, opts) {
  *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }.
  *   - `label` -- an OPTIONAL CA label path segment; `timeout` / `maxResponseBytes` / `maxRedirects` -- budgets.
  *   - `now` -- receipt time (epoch ms) to render a 202 Retry-After HTTP-date as seconds.
+ *   - `auth` -- HTTP authentication: `{ scheme: "basic" | "digest", username, password, allowMD5, allowLegacyQop, maxStaleRetries }`.
+ *     There is no `"auto"`: the scheme is chosen here, not by whatever a server offers. `username` / `password`
+ *     at the top level are the older form and mean Basic. Answered only after the transport authenticated the server.
+ *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on an unsafe method.
  * @example
  *   // a live CA uses the default pki.transport.https; here an injected transport returns a canned bag
  *   var r = await pki.est.cacerts("https://ca.example",
@@ -1759,6 +1824,11 @@ function _enroll(op, baseUrl, csrInput, opts) {
 function cacerts(baseUrl, opts) {
   opts = opts || {};
   return Promise.resolve().then(function () {
+    // Inside the promise, like every other refusal these verbs make. They are documented as
+    // Promise-returning, so a caller writes `.catch(...)` -- and a check that throws synchronously
+    // escapes that catch entirely, turning a misspelled option into an uncaught exception rather
+    // than the rejection the caller is already handling.
+    _knownOpts(opts, CACERTS_OPTS, "cacerts");
     return _client("cacerts", "GET", baseUrl, null, { accept: "application/pkcs7-mime" }, opts);
   }).then(function (res) { return _certsResult("cacerts", res, opts, null); });
 }
@@ -1795,7 +1865,10 @@ function cacerts(baseUrl, opts) {
  */
 function simpleenroll(baseUrl, csrInput, opts) {
   opts = opts || {};
-  return Promise.resolve().then(function () { return _enroll("simpleenroll", baseUrl, csrInput, opts); });
+  return Promise.resolve().then(function () {
+    _knownOpts(opts, SIMPLEENROLL_OPTS, "simpleenroll");
+    return _enroll("simpleenroll", baseUrl, csrInput, opts);
+  });
 }
 
 /**
@@ -1826,6 +1899,7 @@ function simpleenroll(baseUrl, csrInput, opts) {
 function simplereenroll(baseUrl, csrInput, opts) {
   opts = opts || {};
   return Promise.resolve().then(function () {
+    _knownOpts(opts, SIMPLEREENROLL_OPTS, "simplereenroll");
     if (!opts.oldCert) throw E("est/bad-input", "simplereenroll requires opts.oldCert (the certificate being renewed, RFC 7030 sec. 4.2.2)");
     reenrollGuard(opts.oldCert, _csrDer(csrInput));   // est/reenroll-* on mismatch, BEFORE the POST
     return _enroll("simplereenroll", baseUrl, csrInput, opts);
@@ -1989,6 +2063,7 @@ async function _serverkeygenResult(res, opts, derived) {
 function serverkeygen(baseUrl, csrInput, opts) {
   opts = opts || {};
   return Promise.resolve().then(function () {
+    _knownOpts(opts, SERVERKEYGEN_OPTS, "serverkeygen");
     var csrDer = _csrDer(csrInput);
     var derived = _serverkeygenEncryptionFromCsr(csrDer);
     if (opts.requestedEncryption !== undefined && !!opts.requestedEncryption !== derived.requestedEncryption) throw E("est/bad-input", "opts.requestedEncryption (" + !!opts.requestedEncryption + ") contradicts the CSR's advertised key-encryption attribute (" + derived.requestedEncryption + ") (RFC 7030 sec. 4.4.1)");
@@ -2056,6 +2131,7 @@ function _csrattrsResult(res, opts) {
 function csrattrs(baseUrl, opts) {
   opts = opts || {};
   return Promise.resolve().then(function () {
+    _knownOpts(opts, CSRATTRS_OPTS, "csrattrs");
     return _client("csrattrs", "GET", baseUrl, null, { accept: "application/csrattrs" }, opts);
   }).then(function (res) { return _csrattrsResult(res, opts); });
 }

package/lib/guard-all.js

@@ -40,6 +40,10 @@
 //   guard.header.assertField          -- emitted MIME/RFC 5322 header field name +
 //                                        value integrity (CR/LF/NUL header-injection
 //                                        defence, CWE-93)
+//   guard.parsed.accept               -- a CLAIMED-parsed structure carries every
+//                                        field the consuming code dereferences
+//                                        (type confusion / unverified provenance,
+//                                        CWE-843 / CWE-345)
 //
 // Each shape is enforced by a codebase-patterns detector: the characteristic
 // token of a guard (the Buffer.from(x.buffer, byteOffset) re-view, the
@@ -60,6 +64,7 @@ var identifier = require("./guard-identifier");
 var header = require("./guard-header");
 var compress = require("./guard-compress");
 var secret = require("./guard-secret");
+var parsed = require("./guard-parsed");
 
 module.exports = {
   bytes:  bytes,
@@ -75,4 +80,5 @@ module.exports = {
   header: header,
   compress: compress,
   secret: secret,
+  parsed: parsed,
 };