@blamejs/pki 0.1.22 → 0.1.24

package/lib/schema-cmp.js

@@ -10,9 +10,9 @@
  *
  * @intro
  *   Certificate Management Protocol handling per RFC 9810 (which obsoletes
- *   RFC 4210 and RFC 9480). `parse` decodes a `PKIMessage` — the protected
+ *   RFC 4210 and RFC 9480). `parse` decodes a `PKIMessage` -- the protected
  *   transport envelope CMP enrollment, revocation, confirmation, and support
- *   exchanges ride — into its header (version, sender / recipient
+ *   exchanges ride -- into its header (version, sender / recipient
  *   GeneralNames including the NULL-DN anonymous form, nonces, transaction
  *   id, free text, general info), its body, its protection bits, and its
  *   extra certificates.
@@ -22,14 +22,14 @@
  *   CRMF parser; response, revocation, confirmation, error, general-message,
  *   and polling arms decode structurally (an encrypted certificate's
  *   EnvelopedData decodes via the CMS parser); every other defined arm is
- *   recognized and surfaced raw — `nested` messages are never auto-recursed.
+ *   recognized and surfaced raw -- `nested` messages are never auto-recursed.
  *   Protection is surfaced, not verified: the exact `headerBytes` and
  *   `bodyBytes` wire slices are exposed so an external verifier reconstructs
  *   the virtual ProtectedPart `SEQUENCE { header, body }` and checks the MAC
  *   or signature itself. DER-only, fail-closed.
  *
  * @card
- *   Parse DER / PEM RFC 9810 CMP PKIMessages — header, 27-arm body (requests
+ *   Parse DER / PEM RFC 9810 CMP PKIMessages -- header, 27-arm body (requests
  *   via CRMF, encrypted certs via CMS, the rest structural or raw),
  *   protection inputs surfaced byte-exact for external verification,
  *   fail-closed.
@@ -55,21 +55,10 @@ var OID_PKI_ARCHIVE_OPTIONS = oid.byName("pkiArchiveOptions");
 
 // ---- leaves -----------------------------------------------------------
 
-// CMP times are GeneralizedTime only (RFC 9810 §5.1.1).
-var GENERALIZED_TIME = schema.decode(function (n, ctx) {
-  if (n.tagClass !== "universal" || n.tagNumber !== TAGS.GENERALIZED_TIME) {
-    throw ctx.E("cmp/bad-time", "CMP times must be GeneralizedTime (RFC 9810 §5.1.1)");
-  }
-  return asn1.read.time(n);
-});
-
-// A PKIFreeText element MUST be a UTF8String (§5.1.1).
-var UTF8_TEXT = schema.decode(function (n, ctx) {
-  if (n.tagClass !== "universal" || n.tagNumber !== TAGS.UTF8_STRING) {
-    throw ctx.E("cmp/bad-freetext", "PKIFreeText elements must be UTF8String (RFC 9810 §5.1.1)");
-  }
-  return asn1.read.string(n);
-});
+// CMP times are GeneralizedTime only; PKIFreeText elements are UTF8String
+// (RFC 9810 sec. 5.1.1). Both ride the shared pkix leaf factories.
+var GENERALIZED_TIME = pkix.generalizedTime(NS, { code: "cmp/bad-time", message: "CMP times must be GeneralizedTime (RFC 9810 sec. 5.1.1)" });
+var UTF8_TEXT = pkix.utf8Text(NS, { code: "cmp/bad-freetext", message: "PKIFreeText elements must be UTF8String (RFC 9810 sec. 5.1.1)" });
 
 // PKIFreeText ::= SEQUENCE SIZE (1..MAX) OF UTF8String.
 var PKI_FREE_TEXT = schema.seqOf(UTF8_TEXT, {
@@ -77,17 +66,17 @@ var PKI_FREE_TEXT = schema.seqOf(UTF8_TEXT, {
   build: function (m) { return m.items.map(function (it) { return it.value; }); },
 });
 
-// PKIStatus ::= INTEGER {0..6} (§5.2.3) — a value whitelist, surfaced named.
+// PKIStatus ::= INTEGER {0..6} (sec. 5.2.3) -- a value whitelist, surfaced named.
 var PKI_STATUS_NAMES = ["accepted", "grantedWithMods", "rejection", "waiting",
   "revocationWarning", "revocationNotification", "keyUpdateWarning"];
 var PKI_STATUS = schema.decode(function (n, ctx) {
   var v = asn1.read.integer(n);
-  if (v < 0n || v > 6n) throw ctx.E("cmp/bad-status", "undefined PKIStatus " + v.toString() + " (RFC 9810 §5.2.3)");
+  if (v < 0n || v > 6n) throw ctx.E("cmp/bad-status", "undefined PKIStatus " + v.toString() + " (RFC 9810 sec. 5.2.3)");
   var code = Number(v);
   return { code: code, name: PKI_STATUS_NAMES[code] };
 });
 
-// PKIFailureInfo ::= BIT STRING named bits 0..26 (§5.2.3). X.690 §11.2.2:
+// PKIFailureInfo ::= BIT STRING named bits 0..26 (sec. 5.2.3). X.690 sec. 11.2.2:
 // a named-bit BIT STRING drops trailing zero bits, so the final carried bit
 // must be 1. Bits past 26 are extensible and surface as numeric indexes.
 var FAIL_INFO_NAMES = ["badAlg", "badMessageCheck", "badRequest", "badTime", "badCertId",
@@ -107,31 +96,22 @@ var PKI_FAILURE_INFO = schema.decode(function (n, ctx) {
   return { bits: bits, raw: bs };
 });
 
-// PollRep checkAfter is a delay in seconds — negative poisons scheduling, and
+// PollRep checkAfter is a delay in seconds -- negative poisons scheduling, and
 // the value surfaces as an exact number or not at all.
 var CHECK_AFTER = schema.decode(function (n, ctx) {
   var v = asn1.read.integer(n);
-  if (v < 0n || v > 2147483647n) throw ctx.E("cmp/bad-poll-rep", "checkAfter must be a non-negative delay in seconds (RFC 9810 §5.3.22)");
+  if (v < 0n || v > 2147483647n) throw ctx.E("cmp/bad-poll-rep", "checkAfter must be a non-negative delay in seconds (RFC 9810 sec. 5.3.22)");
   return Number(v);
 });
 
-// A raw certificate / CRL / publication-info element — surfaced byte-exact for
+// A raw certificate / CRL / publication-info element -- surfaced byte-exact for
 // downstream parsing, but structurally a universal SEQUENCE: a CMPCertificate
 // is a Certificate, and CertificateList / PKIPublicationInfo are SEQUENCEs, so
 // a primitive (an INTEGER) or wrong-tag element is not a valid structure and
 // rejects rather than handing arbitrary bytes to certificate processing. The
 // `code` names the containing structure (a shared leaf cannot know its context).
 function rawSequence(code) {
-  return schema.decode(function (n, ctx) {
-    // A Certificate, CertificateList, and PKIPublicationInfo are each a
-    // NON-EMPTY universal SEQUENCE — an empty SEQUENCE (0x30 0x00) has the
-    // right tag but is none of them, so require at least one child rather than
-    // surface a degenerate structure as certificate/CRL bytes.
-    if (!(n.tagClass === "universal" && n.tagNumber === TAGS.SEQUENCE && n.children && n.children.length >= 1)) {
-      throw ctx.E(code, "expected a non-empty universal SEQUENCE (Certificate / CertificateList / PKIPublicationInfo)");
-    }
-    return n.bytes;
-  });
+  return pkix.rawNonEmptySequence(NS, { code: code, message: "expected a non-empty universal SEQUENCE (Certificate / CertificateList / PKIPublicationInfo)" });
 }
 
 var GENERAL_NAME = pkix.generalName(NS, { decodeValue: true });
@@ -141,7 +121,7 @@ var EXTENSIONS = pkix.extensions(NS);
 // ---- header ------------------------------------------------------------
 
 // InfoTypeAndValue ::= SEQUENCE { infoType OID, infoValue ANY OPTIONAL }
-// (§5.1.1, §5.3.19). Recognized id-it types with a fixed value syntax are
+// (sec. 5.1.1, sec. 5.3.19). Recognized id-it types with a fixed value syntax are
 // validated (the CMS signed-attr value-syntax posture); all others surface
 // raw with the registry name resolving.
 var INFO_TYPE_AND_VALUE = schema.seq([
@@ -152,13 +132,13 @@ var INFO_TYPE_AND_VALUE = schema.seq([
   build: function (m, ctx) {
     var t = m.fields.infoType.value;
     var valueNode = m.fields.infoValue.present ? m.fields.infoValue.value : null;
-    // A recognized id-it type with a FIXED value syntax (RFC 9810 §5.1.1) MUST
-    // carry its infoValue — implicitConfirm a NULL, confirmWaitTime a
+    // A recognized id-it type with a FIXED value syntax (RFC 9810 sec. 5.1.1) MUST
+    // carry its infoValue -- implicitConfirm a NULL, confirmWaitTime a
     // GeneralizedTime, certProfile a SEQUENCE OF UTF8String. A missing value is
     // accepted only for the open / query id-it types (a bare OID in a genm body),
     // never for a type whose value syntax the RFC defines.
     if ((t === OID_IMPLICIT_CONFIRM || t === OID_CONFIRM_WAIT_TIME || t === OID_CERT_PROFILE) && valueNode === null) {
-      throw ctx.E("cmp/bad-info-value", "a recognized fixed-syntax id-it (implicitConfirm / confirmWaitTime / certProfile) must carry its infoValue (RFC 9810 §5.1.1)");
+      throw ctx.E("cmp/bad-info-value", "a recognized fixed-syntax id-it (implicitConfirm / confirmWaitTime / certProfile) must carry its infoValue (RFC 9810 sec. 5.1.1)");
     }
     if (valueNode !== null) {
       // A recognized id-it value is validated by CONTENT, not just tag: run the
@@ -167,30 +147,30 @@ var INFO_TYPE_AND_VALUE = schema.seq([
       // rejects rather than being surfaced as valid CMP.
       if (t === OID_IMPLICIT_CONFIRM) {
         if (!(valueNode.tagClass === "universal" && valueNode.tagNumber === TAGS.NULL)) {
-          throw ctx.E("cmp/bad-info-value", "an implicitConfirm value must be NULL (RFC 9810 §5.1.1.1)");
+          throw ctx.E("cmp/bad-info-value", "an implicitConfirm value must be NULL (RFC 9810 sec. 5.1.1.1)");
         }
         try { asn1.read.nullValue(valueNode); }
-        catch (e) { throw ctx.E("cmp/bad-info-value", "an implicitConfirm value must be an empty NULL (RFC 9810 §5.1.1.1)", e); }
+        catch (e) { throw ctx.E("cmp/bad-info-value", "an implicitConfirm value must be an empty NULL (RFC 9810 sec. 5.1.1.1)", e); }
       }
       if (t === OID_CONFIRM_WAIT_TIME) {
         if (!(valueNode.tagClass === "universal" && valueNode.tagNumber === TAGS.GENERALIZED_TIME)) {
-          throw ctx.E("cmp/bad-info-value", "a confirmWaitTime value must be a GeneralizedTime (RFC 9810 §5.1.1.2)");
+          throw ctx.E("cmp/bad-info-value", "a confirmWaitTime value must be a GeneralizedTime (RFC 9810 sec. 5.1.1.2)");
         }
         try { asn1.read.time(valueNode); }
-        catch (e) { throw ctx.E("cmp/bad-info-value", "a confirmWaitTime GeneralizedTime is malformed (RFC 9810 §5.1.1.2)", e); }
+        catch (e) { throw ctx.E("cmp/bad-info-value", "a confirmWaitTime GeneralizedTime is malformed (RFC 9810 sec. 5.1.1.2)", e); }
       }
       if (t === OID_CERT_PROFILE) {
         if (!(valueNode.tagClass === "universal" && valueNode.tagNumber === TAGS.SEQUENCE &&
               valueNode.children && valueNode.children.length >= 1)) {
-          throw ctx.E("cmp/bad-info-value", "a certProfile value must be a non-empty SEQUENCE OF UTF8String (RFC 9810 §5.1.1.4)");
+          throw ctx.E("cmp/bad-info-value", "a certProfile value must be a non-empty SEQUENCE OF UTF8String (RFC 9810 sec. 5.1.1.4)");
         }
         for (var i = 0; i < valueNode.children.length; i++) {
           var el = valueNode.children[i];
           if (!(el.tagClass === "universal" && el.tagNumber === TAGS.UTF8_STRING)) {
-            throw ctx.E("cmp/bad-info-value", "a certProfile element must be a UTF8String (RFC 9810 §5.1.1.4)");
+            throw ctx.E("cmp/bad-info-value", "a certProfile element must be a UTF8String (RFC 9810 sec. 5.1.1.4)");
           }
           try { asn1.read.string(el); }
-          catch (e) { throw ctx.E("cmp/bad-info-value", "a certProfile element must be a valid UTF8String (RFC 9810 §5.1.1.4)", e); }
+          catch (e) { throw ctx.E("cmp/bad-info-value", "a certProfile element must be a valid UTF8String (RFC 9810 sec. 5.1.1.4)", e); }
         }
       }
     }
@@ -204,7 +184,7 @@ var GENERAL_INFO = schema.seqOf(INFO_TYPE_AND_VALUE, {
 });
 
 // PKIHeader ::= SEQUENCE { pvno, sender, recipient, then EXPLICIT [0]..[8]
-// optionals, ascending, at-most-once } (§5.1.1).
+// optionals, ascending, at-most-once } (sec. 5.1.1).
 var PKI_HEADER = schema.seq([
   schema.field("pvno", pkix.versionReader(NS, { "1": 1, "2": 2, "3": 3 })),
   schema.field("sender", GENERAL_NAME),
@@ -243,7 +223,7 @@ var PKI_HEADER = schema.seq([
 
 // ---- decoded body arms ---------------------------------------------------
 
-// PKIStatusInfo ::= SEQUENCE { status, statusString OPTIONAL, failInfo OPTIONAL } (§5.2.3).
+// PKIStatusInfo ::= SEQUENCE { status, statusString OPTIONAL, failInfo OPTIONAL } (sec. 5.2.3).
 var PKI_STATUS_INFO = schema.seq([
   schema.field("status", PKI_STATUS),
   schema.optional("statusString", PKI_FREE_TEXT, { whenUniversal: [TAGS.SEQUENCE] }),
@@ -260,7 +240,7 @@ var PKI_STATUS_INFO = schema.seq([
 });
 
 // ErrorMsgContent ::= SEQUENCE { pKIStatusInfo, errorCode INTEGER OPTIONAL,
-// errorDetails PKIFreeText OPTIONAL } (§5.3.21).
+// errorDetails PKIFreeText OPTIONAL } (sec. 5.3.21).
 var ERROR_MSG_CONTENT = schema.seq([
   schema.field("pKIStatusInfo", PKI_STATUS_INFO),
   schema.optional("errorCode", schema.integerLeaf(), { whenUniversal: [TAGS.INTEGER] }),
@@ -277,7 +257,7 @@ var ERROR_MSG_CONTENT = schema.seq([
 });
 
 // CertStatus ::= SEQUENCE { certHash, certReqId, statusInfo OPTIONAL,
-// hashAlg [0] OPTIONAL } (§5.3.18). certReqId accepts the -1 sentinel.
+// hashAlg [0] OPTIONAL } (sec. 5.3.18). certReqId accepts the -1 sentinel.
 var CERT_STATUS = schema.seq([
   schema.field("certHash", schema.octetString()),
   schema.field("certReqId", schema.integerLeaf()),
@@ -297,22 +277,22 @@ var CERT_STATUS = schema.seq([
   },
 });
 
-// CertConfirmContent ::= SEQUENCE OF CertStatus — an EMPTY sequence is legal
-// (reject-all, §5.3.18), so no SIZE floor.
+// CertConfirmContent ::= SEQUENCE OF CertStatus -- an EMPTY sequence is legal
+// (reject-all, sec. 5.3.18), so no SIZE floor.
 var CERT_CONFIRM_CONTENT = schema.seqOf(CERT_STATUS, {
   code: "cmp/bad-cert-status", what: "CertConfirmContent",
   build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
 });
 
-// GenMsgContent / GenRepContent ::= SEQUENCE OF InfoTypeAndValue — no SIZE
-// bound, empty legal (§5.3.19/.20).
+// GenMsgContent / GenRepContent ::= SEQUENCE OF InfoTypeAndValue -- no SIZE
+// bound, empty legal (sec. 5.3.19/.20).
 var GEN_MSG_CONTENT = schema.seqOf(INFO_TYPE_AND_VALUE, {
   code: "cmp/bad-info-type-and-value", what: "GenMsgContent",
   build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
 });
 
 // RevDetails ::= SEQUENCE { certDetails CertTemplate, crlEntryDetails
-// Extensions OPTIONAL } (§5.3.9) — the CertTemplate interior (an IMPLICIT
+// Extensions OPTIONAL } (sec. 5.3.9) -- the CertTemplate interior (an IMPLICIT
 // TAGS module) is owned by the CRMF parser and walked NS-bound there.
 var CERT_TEMPLATE_LEAF = schema.decode(function (n) { return crmf.walkCertTemplate(n); });
 var REV_DETAILS = schema.seq([
@@ -344,7 +324,7 @@ var CERT_ID = schema.seq([
 });
 
 // RevRepContent ::= SEQUENCE { status SIZE(1..MAX), revCerts [0] OPTIONAL,
-// crls [1] OPTIONAL } (§5.3.10).
+// crls [1] OPTIONAL } (sec. 5.3.10).
 var REV_REP_CONTENT = schema.seq([
   schema.field("status", schema.seqOf(PKI_STATUS_INFO, {
     min: 1, code: "cmp/bad-rev-rep", what: "RevRep status",
@@ -372,49 +352,59 @@ var REV_REP_CONTENT = schema.seq([
 });
 
 // EncryptedKey ::= CHOICE { encryptedValue EncryptedValue (deprecated),
-// envelopedData [0] EnvelopedData } (§5.2.2). EncryptedKey is imported from
+// envelopedData [0] EnvelopedData } (sec. 5.2.2). EncryptedKey is imported from
 // the RFC 4211 CRMF module, which is IMPLICIT TAGS, so `envelopedData [0]` is
-// an IMPLICIT context tag REPLACING the EnvelopedData SEQUENCE tag — the [0]
+// an IMPLICIT context tag REPLACING the EnvelopedData SEQUENCE tag -- the [0]
 // node's children ARE the EnvelopedData fields, no inner wrapper. Retag it to
 // the universal SEQUENCE the CMS walker expects, exactly as the sibling CRMF
 // `encryptedKey [4] EnvelopedData` POP arm does (schema-crmf.js). The
-// deprecated encryptedValue arm surfaces RAW — never field-walked, so nothing
+// deprecated encryptedValue arm surfaces RAW -- never field-walked, so nothing
 // dereferences its optional interior (absent algorithm parameters crash
 // consumers that walk it blindly).
 var ENCRYPTED_KEY = schema.choice([
   { when: { tagClass: "universal", tagNumber: TAGS.SEQUENCE },
-    schema: schema.decode(function (n) { return { encryptedValue: n.bytes }; }) },
+    schema: schema.decode(function (n, ctx) {
+      // An RFC 4211 sec. 2 EncryptedValue REQUIRES encValue (its final BIT STRING
+      // field), so an EMPTY SEQUENCE has the right tag but is not any valid
+      // EncryptedValue -- require at least one child rather than surface a
+      // degenerate structure as encrypted certificate/key bytes (the same
+      // non-empty rule every raw-SEQUENCE surface in this module applies).
+      if (!(n.children && n.children.length >= 1)) {
+        throw ctx.E("cmp/bad-cert-response", "an EncryptedValue must be a non-empty SEQUENCE (RFC 4211 sec. 2)");
+      }
+      return { encryptedValue: n.bytes };
+    }) },
   { when: { tagClass: "context", tagNumber: 0 },
     schema: schema.decode(function (n, ctx) {
       var env;
-      // Wrap every EnvelopedData failure — a non-decodable retarget OR a CmsError
-      // from the composed walker — as the CMP domain error (with the original as
+      // Wrap every EnvelopedData failure -- a non-decodable retarget OR a CmsError
+      // from the composed walker -- as the CMP domain error (with the original as
       // the cause), so cmp.parse never escapes with a cms/* error for a malformed
       // PKIMessage (the same wrapping the sibling CRMF encryptedKey POP arm does).
       try { env = cms.walkEnvelopedData(asn1.decode(asn1.sequenceTlv(n))); }
       catch (e) {
-        throw ctx.E("cmp/bad-cert-response", "envelopedData [0] must be a well-formed IMPLICIT EnvelopedData (RFC 9810 §5.2.2)", e);
+        throw ctx.E("cmp/bad-cert-response", "envelopedData [0] must be a well-formed IMPLICIT EnvelopedData (RFC 9810 sec. 5.2.2)", e);
       }
-      // RFC 9810 §5.2.2 — a CMP EncryptedKey EnvelopedData is addressed to
+      // RFC 9810 sec. 5.2.2 -- a CMP EncryptedKey EnvelopedData is addressed to
       // exactly one recipient (the end entity for a delivered cert / key). CMS
       // permits RecipientInfos SET SIZE 1..MAX, so the single-recipient bound is
       // CMP's: more than one recipient is a malformed EncryptedKey.
       if (env.recipientInfos.length !== 1) {
-        throw ctx.E("cmp/bad-cert-response", "an EncryptedKey EnvelopedData must contain exactly one RecipientInfo (RFC 9810 §5.2.2)");
+        throw ctx.E("cmp/bad-cert-response", "an EncryptedKey EnvelopedData must contain exactly one RecipientInfo (RFC 9810 sec. 5.2.2)");
       }
       // The ciphertext IS the encrypted certificate / private key here, so an
-      // EnvelopedData with no ciphertext to decrypt — absent (detached, CMS
-      // permits it) OR present-but-empty — must reject (RFC 9810 §5.2.2/§5.3.4;
+      // EnvelopedData with no ciphertext to decrypt -- absent (detached, CMS
+      // permits it) OR present-but-empty -- must reject (RFC 9810 sec. 5.2.2/sec. 5.3.4;
       // the same rule the CRMF encryptedKey POP arm enforces).
       var ct = env.encryptedContentInfo.encryptedContent;
       if (ct === null || ct.length === 0) {
-        throw ctx.E("cmp/bad-cert-response", "an EncryptedKey envelopedData must carry non-empty attached ciphertext — its encryptedContent is the certificate/key payload (RFC 9810 §5.2.2)");
+        throw ctx.E("cmp/bad-cert-response", "an EncryptedKey envelopedData must carry non-empty attached ciphertext -- its encryptedContent is the certificate/key payload (RFC 9810 sec. 5.2.2)");
       }
       return { envelopedData: env };
     }) },
 ], { code: "cmp/bad-cert-response", what: "EncryptedKey" });
 
-// CertOrEncCert ::= CHOICE { certificate [0], encryptedCert [1] } (§5.3.4).
+// CertOrEncCert ::= CHOICE { certificate [0], encryptedCert [1] } (sec. 5.3.4).
 var CERT_OR_ENC_CERT = schema.choice([
   { when: { tagClass: "context", tagNumber: 0 },
     schema: schema.explicit(0, schema.decode(function (n, ctx) {
@@ -428,7 +418,7 @@ var CERT_OR_ENC_CERT = schema.choice([
 ], { code: "cmp/bad-cert-response", what: "CertOrEncCert" });
 
 // CertifiedKeyPair ::= SEQUENCE { certOrEncCert, privateKey [0] OPTIONAL,
-// publicationInfo [1] OPTIONAL } (§5.3.4).
+// publicationInfo [1] OPTIONAL } (sec. 5.3.4).
 var CERTIFIED_KEY_PAIR = schema.seq([
   schema.field("certOrEncCert", CERT_OR_ENC_CERT),
   schema.trailing([
@@ -448,7 +438,7 @@ var CERTIFIED_KEY_PAIR = schema.seq([
 });
 
 // CertResponse ::= SEQUENCE { certReqId INTEGER (the -1 sentinel is legal),
-// status PKIStatusInfo, certifiedKeyPair OPTIONAL, rspInfo OPTIONAL } (§5.3.4).
+// status PKIStatusInfo, certifiedKeyPair OPTIONAL, rspInfo OPTIONAL } (sec. 5.3.4).
 var CERT_RESPONSE = schema.seq([
   schema.field("certReqId", schema.integerLeaf()),
   schema.field("status", PKI_STATUS_INFO),
@@ -459,24 +449,24 @@ var CERT_RESPONSE = schema.seq([
   build: function (m, ctx) {
     var status = m.fields.status.value.result;
     var certifiedKeyPair = m.fields.certifiedKeyPair.present ? m.fields.certifiedKeyPair.value.result : null;
-    // RFC 9810 §5.3.4 — only one of the failInfo (in PKIStatusInfo) and
+    // RFC 9810 sec. 5.3.4 -- only one of the failInfo (in PKIStatusInfo) and
     // certifiedKeyPair fields can be present in a CertResponse: a rejection
     // carries no certificate. Accepting both lets a caller keying off
     // certifiedKeyPair process a certificate from a failed response.
     if (status.failInfo !== null && certifiedKeyPair !== null) {
       throw ctx.E("cmp/bad-cert-response",
-        "a CertResponse must not carry both failInfo and certifiedKeyPair (RFC 9810 §5.3.4)");
+        "a CertResponse must not carry both failInfo and certifiedKeyPair (RFC 9810 sec. 5.3.4)");
     }
     // A certifiedKeyPair is present ONLY when the status grants the certificate:
-    // accepted (0) or grantedWithMods (1). Any other status — rejection, waiting,
-    // the revocation / keyUpdate warnings — denies or defers the request, so a
+    // accepted (0) or grantedWithMods (1). Any other status -- rejection, waiting,
+    // the revocation / keyUpdate warnings -- denies or defers the request, so a
     // certificate under it is a malformed response even when no explicit failInfo
     // bit is set (a rejection is commonly signalled by status alone). Keying the
     // rule off failInfo presence alone would let a bare-rejection status ship a
-    // certificate (RFC 9810 §5.3.4).
+    // certificate (RFC 9810 sec. 5.3.4).
     if (certifiedKeyPair !== null && status.status.code !== 0 && status.status.code !== 1) {
       throw ctx.E("cmp/bad-cert-response",
-        "a CertResponse certifiedKeyPair is allowed only under a granting status (accepted or grantedWithMods) (RFC 9810 §5.3.4)");
+        "a CertResponse certifiedKeyPair is allowed only under a granting status (accepted or grantedWithMods) (RFC 9810 sec. 5.3.4)");
     }
     return {
       certReqId: m.fields.certReqId.value,
@@ -488,7 +478,7 @@ var CERT_RESPONSE = schema.seq([
 });
 
 // CertRepMessage ::= SEQUENCE { caPubs [1] OPTIONAL, response SEQUENCE OF
-// CertResponse } (§5.3.4) — the optional precedes the required field (the
+// CertResponse } (sec. 5.3.4) -- the optional precedes the required field (the
 // x509-version shape). caPubs surface raw: the parser confers NO trust.
 var CERT_REP_MESSAGE = schema.seq([
   schema.optional("caPubs", schema.seqOf(rawSequence("cmp/bad-cert-rep"), {
@@ -511,9 +501,9 @@ var CERT_REP_MESSAGE = schema.seq([
 
 // KeyRecRepContent ::= SEQUENCE { status PKIStatusInfo, newSigCert [0]
 // Certificate OPTIONAL, caCerts [1] SEQUENCE OF Certificate OPTIONAL,
-// keyPairHist [2] SEQUENCE OF CertifiedKeyPair OPTIONAL } (§5.3.8). The
+// keyPairHist [2] SEQUENCE OF CertifiedKeyPair OPTIONAL } (sec. 5.3.8). The
 // keyPairHist CertifiedKeyPairs can carry the same EnvelopedData form as the
-// enrollment responses, so krp is decoded (not surfaced raw) — the operator sees
+// enrollment responses, so krp is decoded (not surfaced raw) -- the operator sees
 // the status / key history and the cross-field EnvelopedData version check runs.
 var KEY_REC_REP_CONTENT = schema.seq([
   schema.field("status", PKI_STATUS_INFO),
@@ -540,7 +530,7 @@ var KEY_REC_REP_CONTENT = schema.seq([
   },
 });
 
-// PollReqContent / PollRepContent (§5.3.22) — certReqId may be -1.
+// PollReqContent / PollRepContent (sec. 5.3.22) -- certReqId may be -1.
 var POLL_REQ_ENTRY = schema.seq([
   schema.field("certReqId", schema.integerLeaf()),
 ], {
@@ -572,12 +562,12 @@ var POLL_REP_CONTENT = schema.seqOf(POLL_REP_ENTRY, {
 
 // ---- the 27-arm body dispatch ----------------------------------------------
 
-// Tag -> arm name, verbatim from the PKIXCMP-2023 module (§5.1.2). Every
+// Tag -> arm name, verbatim from the PKIXCMP-2023 module (sec. 5.1.2). Every
 // defined arm is at minimum recognized; a subset decodes structurally.
 var BODY_ARMS = ["ir", "ip", "cr", "cp", "p10cr", "popdecc", "popdecr", "kur", "kup",
   "krr", "krp", "rr", "rp", "ccr", "ccp", "ckuann", "cann", "rann", "crlann",
   "pkiconf", "nested", "genm", "genp", "error", "certConf", "pollReq", "pollRep"];
-// Arms carrying RFC 4211 CertReqMessages — walked by the CRMF parser.
+// Arms carrying RFC 4211 CertReqMessages -- walked by the CRMF parser.
 var CRMF_ARMS = { 0: true, 2: true, 7: true, 9: true, 13: true };
 // Arms with a structural schema here.
 var DECODED_ARMS = {
@@ -590,29 +580,30 @@ var DECODED_ARMS = {
 };
 
 // The open-CHOICE dispatch: tag -> arm name; walk where a schema exists;
-// surface every other defined arm raw as { arm, tag, bytes } — `decoded` is
+// surface every other defined arm raw as { arm, tag, bytes } -- `decoded` is
 // ABSENT (not null) on raw arms, so its presence discriminates decoded-empty
 // (pkiconf decodes to null) from recognized-undecoded. `nested` [20] is never
 // auto-recursed: a self-nesting tower amplifies per-level walk products, so
 // the operator re-feeds its bytes to parse explicitly.
 var BODY = schema.decode(function (n, ctx) {
   if (n.tagClass !== "context" || !n.children) {
-    throw ctx.E("cmp/bad-body", "PKIBody must be a constructed context-tagged CHOICE arm (RFC 9810 §5.1.2)");
+    throw ctx.E("cmp/bad-body", "PKIBody must be a constructed context-tagged CHOICE arm (RFC 9810 sec. 5.1.2)");
   }
   if (n.tagNumber < 0 || n.tagNumber > 26) {
-    throw ctx.E("cmp/bad-body", "PKIBody tag [" + n.tagNumber + "] is not a defined arm (RFC 9810 §5.1.2)");
+    throw ctx.E("cmp/bad-body", "PKIBody tag [" + n.tagNumber + "] is not a defined arm (RFC 9810 sec. 5.1.2)");
   }
   if (n.children.length !== 1) {
-    throw ctx.E("cmp/bad-body", "a PKIBody arm wraps exactly one value (X.690 §8.14)");
+    throw ctx.E("cmp/bad-body", "a PKIBody arm wraps exactly one value (X.690 sec. 8.14)");
   }
   var inner = n.children[0];
   var out = { arm: BODY_ARMS[n.tagNumber], tag: n.tagNumber, bytes: inner.bytes };
   if (CRMF_ARMS[n.tagNumber]) {
     // ccr [13] cross-certification: RFC 9810 Appendix D.6 profiles its template
-    // with signingAlg present and allows exactly one CertReqMsg (multiple
+    // with signingAlg present and version "v1 or v3" (both overriding RFC 4211
+    // sec. 5 for this one arm), and allows exactly one CertReqMsg (multiple
     // cross-certificates go in separate PKIMessages).
     var isCcr = n.tagNumber === 13;
-    out.decoded = crmf.walkCertReqMessages(inner, { allowSigningAlg: isCcr });
+    out.decoded = crmf.walkCertReqMessages(inner, { allowSigningAlg: isCcr, allowV1Version: isCcr });
     if (isCcr && out.decoded.messages.length !== 1) {
       throw ctx.E("cmp/bad-body", "a cross-certification request (ccr) must contain exactly one CertReqMsg (RFC 9810 Appendix D.6)");
     }
@@ -620,14 +611,14 @@ var BODY = schema.decode(function (n, ctx) {
     var match = schema.walk(DECODED_ARMS[n.tagNumber], inner, ctx);
     out.decoded = match.result;
   } else if (n.tagNumber === 19) {
-    // PKIConfirmContent ::= NULL (§5.3.16).
+    // PKIConfirmContent ::= NULL (sec. 5.3.16).
     if (!(inner.tagClass === "universal" && inner.tagNumber === TAGS.NULL)) {
-      throw ctx.E("cmp/bad-pkiconf", "PKIConfirmContent must be NULL (RFC 9810 §5.3.16)");
+      throw ctx.E("cmp/bad-pkiconf", "PKIConfirmContent must be NULL (RFC 9810 sec. 5.3.16)");
     }
-    // A NULL is well-formed only with empty content (X.690 §8.8.2); the tag check
+    // A NULL is well-formed only with empty content (X.690 sec. 8.8.2); the tag check
     // alone would surface a non-empty NULL as a valid confirmation.
     try { asn1.read.nullValue(inner); }
-    catch (e) { throw ctx.E("cmp/bad-pkiconf", "PKIConfirmContent must be an empty NULL (RFC 9810 §5.3.16)", e); }
+    catch (e) { throw ctx.E("cmp/bad-pkiconf", "PKIConfirmContent must be an empty NULL (RFC 9810 sec. 5.3.16)", e); }
     out.decoded = null;
   }
   return out;
@@ -635,20 +626,26 @@ var BODY = schema.decode(function (n, ctx) {
 
 // ---- the message envelope -----------------------------------------------------
 
-// PKIProtection ::= BIT STRING — raw bits for the external verifier.
+// PKIProtection ::= BIT STRING -- raw bits for the external verifier. Every
+// RFC 9481 MSG_SIG_ALG / MSG_MAC_ALG output is an octet string, so the BIT
+// STRING must be octet-aligned; with no in-tree CMP verify layer this is
+// enforced at parse (the posture the OCSP signature shares), fail-closed.
 var PROTECTION = schema.decode(function (n, ctx) {
   var bs;
   try { bs = asn1.read.bitString(n); }
-  catch (e) { throw ctx.E("cmp/bad-protection", "PKIProtection must be a BIT STRING (RFC 9810 §5.1.3)", e); }
+  catch (e) { throw ctx.E("cmp/bad-protection", "PKIProtection must be a BIT STRING (RFC 9810 sec. 5.1.3)", e); }
+  if (bs.unusedBits !== 0) {
+    throw ctx.E("cmp/bad-protection", "PKIProtection must be octet-aligned (0 unused bits) -- every RFC 9481 protection algorithm emits whole octets");
+  }
   return { unusedBits: bs.unusedBits, bytes: bs.bytes };
 });
 
 // PKIMessage ::= SEQUENCE { header, body, protection [0] OPTIONAL,
-// extraCerts [1] OPTIONAL } (§5.1). The build runs the two cross-checks that
-// span structures: protection presence <=> protectionAlg presence (§5.1.1,
+// extraCerts [1] OPTIONAL } (sec. 5.1). The build runs the two cross-checks that
+// span structures: protection presence <=> protectionAlg presence (sec. 5.1.1,
 // both directions), and a certConf hashAlg requires pvno cmp2021(3)
-// (§5.3.18). headerBytes / bodyBytes are the exact wire slices protection is
-// computed over (as DER-SEQUENCE(headerBytes || bodyBytes)) — surfaced raw,
+// (sec. 5.3.18). headerBytes / bodyBytes are the exact wire slices protection is
+// computed over (as DER-SEQUENCE(headerBytes || bodyBytes)) -- surfaced raw,
 // never re-encoded.
 var PKI_MESSAGE = schema.seq([
   schema.field("header", PKI_HEADER),
@@ -669,16 +666,16 @@ var PKI_MESSAGE = schema.seq([
     var extraCerts = m.fields.extraCerts.present ? m.fields.extraCerts.value.result : null;
     if ((protection !== null) !== (header.protectionAlg !== null)) {
       throw ctx.E("cmp/protection-alg-mismatch",
-        "protection bits and the header protectionAlg must be present together or absent together (RFC 9810 §5.1.1)");
+        "protection bits and the header protectionAlg must be present together or absent together (RFC 9810 sec. 5.1.1)");
     }
     if (body.arm === "certConf") {
       for (var i = 0; i < body.decoded.length; i++) {
         if (body.decoded[i].hashAlg !== null && header.pvno !== 3) {
-          throw ctx.E("cmp/bad-cert-status", "a certConf hashAlg requires CMP version cmp2021(3) (RFC 9810 §5.3.18)");
+          throw ctx.E("cmp/bad-cert-status", "a certConf hashAlg requires CMP version cmp2021(3) (RFC 9810 sec. 5.3.18)");
         }
       }
     }
-    // RFC 9810 §5.2.2 / §7 — EnvelopedData is cmp2021(3) syntax: a response
+    // RFC 9810 sec. 5.2.2 / sec. 7 -- EnvelopedData is cmp2021(3) syntax: a response
     // carrying it (an encryptedCert or a privateKey in the envelopedData form)
     // under pvno < 3 is a version mismatch, the same version gate the certConf
     // hashAlg rule applies. The deprecated EncryptedValue form is the pre-2021
@@ -698,17 +695,17 @@ var PKI_MESSAGE = schema.seq([
         (ckps[ck].encryptedCert && ckps[ck].encryptedCert.envelopedData !== undefined) ||
         (ckps[ck].privateKey && ckps[ck].privateKey.envelopedData !== undefined);
       if (usesEnveloped && header.pvno !== 3) {
-        throw ctx.E("cmp/bad-version", "a response carrying EnvelopedData (encryptedCert or privateKey) requires CMP version cmp2021(3) (RFC 9810 §5.2.2, §7)");
+        throw ctx.E("cmp/bad-version", "a response carrying EnvelopedData (encryptedCert or privateKey) requires CMP version cmp2021(3) (RFC 9810 sec. 5.2.2, sec. 7)");
       }
     }
-    // RFC 9810 §5.3.12 — a cross-certification response (ccp) reuses the
+    // RFC 9810 sec. 5.3.12 -- a cross-certification response (ccp) reuses the
     // CertRepMessage syntax "with the restriction that no encrypted private key
     // can be sent": cross-certification certifies an existing CA's public key,
     // so there is no key generation and CertifiedKeyPair.privateKey has no
     // meaning. Reject a ccp that carries one rather than surface the key
     // material; the field stays legal in the enrollment responses (ip/cp/kup).
     if (body.arm === "ccp" && body.decoded && body.decoded.response) {
-      // RFC 9810 Appendix D.6 — a one-way cross-certification response carries
+      // RFC 9810 Appendix D.6 -- a one-way cross-certification response carries
       // exactly one CertResponse (multiple cross-certificates go in separate
       // PKIMessages), the mirror of the ccr one-CertReqMsg rule.
       if (body.decoded.response.length !== 1) {
@@ -717,14 +714,14 @@ var PKI_MESSAGE = schema.seq([
       for (var c = 0; c < body.decoded.response.length; c++) {
         var ckpCcp = body.decoded.response[c].certifiedKeyPair;
         if (ckpCcp && ckpCcp.privateKey !== null) {
-          throw ctx.E("cmp/bad-cert-response", "a cross-certification response (ccp) must not carry an encrypted private key (RFC 9810 §5.3.12)");
+          throw ctx.E("cmp/bad-cert-response", "a cross-certification response (ccp) must not carry an encrypted private key (RFC 9810 sec. 5.3.12)");
         }
       }
     }
-    // RFC 9810 §5.3.11 — a cross-certification request (ccr) MUST NOT send the
+    // RFC 9810 sec. 5.3.11 -- a cross-certification request (ccr) MUST NOT send the
     // private key to the responding CA (the requesting CA generates and holds
-    // it). The private-key-carrying POP choices — encryptedKey (cmp2021) and the
-    // deprecated thisMessage (cmp2000) — are therefore forbidden in a ccr; the
+    // it). The private-key-carrying POP choices -- encryptedKey (cmp2021) and the
+    // deprecated thisMessage (cmp2000) -- are therefore forbidden in a ccr; the
     // MAC (dhMAC / agreeMAC) and indirect (subsequentMessage) methods carry no
     // key. Checked before the version gate so a ccr always gets the ccr verdict.
     if (body.arm === "ccr" && body.decoded && body.decoded.messages) {
@@ -734,10 +731,10 @@ var PKI_MESSAGE = schema.seq([
         // the private key.
         var ccrPopo = ccrMsg.popo;
         if (ccrPopo && (ccrPopo.method === "encryptedKey" || ccrPopo.method === "thisMessage")) {
-          throw ctx.E("cmp/bad-body", "a cross-certification request (ccr) must not send the private key — the " + ccrPopo.method + " POP choice is forbidden (RFC 9810 §5.3.11)");
+          throw ctx.E("cmp/bad-body", "a cross-certification request (ccr) must not send the private key -- the " + ccrPopo.method + " POP choice is forbidden (RFC 9810 sec. 5.3.11)");
         }
         // Via a control: a pkiArchiveOptions control with the encryptedPrivKey [0]
-        // arm is the other private-key transport (§5.2.8.3.1), likewise forbidden
+        // arm is the other private-key transport (sec. 5.2.8.3.1), likewise forbidden
         // in a ccr. The control value is the raw PKIArchiveOptions CHOICE; the
         // encryptedPrivKey arm is context tag [0].
         var controls = ccrMsg.certReq.controls;
@@ -746,15 +743,15 @@ var PKI_MESSAGE = schema.seq([
             if (controls[cn].type !== OID_PKI_ARCHIVE_OPTIONS) continue;
             var arch;
             try { arch = asn1.decode(controls[cn].value); }
-            catch (e) { throw ctx.E("cmp/bad-body", "a ccr pkiArchiveOptions control did not decode (RFC 9810 §5.3.11)", e); }
+            catch (e) { throw ctx.E("cmp/bad-body", "a ccr pkiArchiveOptions control did not decode (RFC 9810 sec. 5.3.11)", e); }
             if (arch.tagClass === "context" && arch.tagNumber === 0) {
-              throw ctx.E("cmp/bad-body", "a cross-certification request (ccr) must not send the private key — a pkiArchiveOptions encryptedPrivKey control is forbidden (RFC 9810 §5.3.11, §5.2.8.3.1)");
+              throw ctx.E("cmp/bad-body", "a cross-certification request (ccr) must not send the private key -- a pkiArchiveOptions encryptedPrivKey control is forbidden (RFC 9810 sec. 5.3.11, sec. 5.2.8.3.1)");
             }
           }
         }
       }
     }
-    // RFC 9810 §5.2.8.3 — the agreeMAC and encryptedKey POPOPrivKey choices are
+    // RFC 9810 sec. 5.2.8.3 -- the agreeMAC and encryptedKey POPOPrivKey choices are
     // cmp2021(3) syntax; a request (ir/cr/kur/krr/ccr) whose proof-of-possession
     // uses either under pvno < 3 is a version mismatch, the same gate the
     // response EnvelopedData rule applies. The CRMF walker surfaces the chosen
@@ -763,9 +760,9 @@ var PKI_MESSAGE = schema.seq([
       for (var q = 0; q < body.decoded.messages.length; q++) {
         var popo = body.decoded.messages[q].popo;
         if (popo && (popo.method === "agreeMAC" || popo.method === "encryptedKey") && header.pvno !== 3) {
-          throw ctx.E("cmp/bad-version", "a request POP using the agreeMAC or encryptedKey choice requires CMP version cmp2021(3) (RFC 9810 §5.2.8.3)");
+          throw ctx.E("cmp/bad-version", "a request POP using the agreeMAC or encryptedKey choice requires CMP version cmp2021(3) (RFC 9810 sec. 5.2.8.3)");
         }
-        // §5.2.8.3.1/§7 — the same key transport via a pkiArchiveOptions control
+        // sec. 5.2.8.3.1/sec. 7 -- the same key transport via a pkiArchiveOptions control
         // whose encryptedPrivKey [0] EXPLICIT wraps the envelopedData-form
         // EncryptedKey is cmp2021 syntax too (a ccr rejects the control outright
         // above; the other request arms are version-gated here).
@@ -776,13 +773,13 @@ var PKI_MESSAGE = schema.seq([
             var opt = asn1.decode(archCtrls[ac].value);
             if (opt.tagClass === "context" && opt.tagNumber === 0 && opt.children && opt.children.length >= 1 &&
                 opt.children[0].tagClass === "context" && opt.children[0].tagNumber === 0) {
-              throw ctx.E("cmp/bad-version", "a pkiArchiveOptions encryptedPrivKey using the EnvelopedData form requires CMP version cmp2021(3) (RFC 9810 §5.2.8.3.1, §7)");
+              throw ctx.E("cmp/bad-version", "a pkiArchiveOptions encryptedPrivKey using the EnvelopedData form requires CMP version cmp2021(3) (RFC 9810 sec. 5.2.8.3.1, sec. 7)");
             }
           }
         }
       }
     }
-    // RFC 9810 §5.1.1.4 — the certProfile name count is bounded by the message
+    // RFC 9810 sec. 5.1.1.4 -- the certProfile name count is bounded by the message
     // body: a p10cr carries at most one; an ir/cr/kur no more names than its
     // CertReqMsg count, a genm no more than its GenMsgContent InfoTypeAndValue
     // count (the names map positionally to the body entries). An overlong list
@@ -796,18 +793,37 @@ var PKI_MESSAGE = schema.seq([
         else if (body.decoded && body.decoded.messages) bodyCount = body.decoded.messages.length;
         else if (body.arm === "genm" && Array.isArray(body.decoded)) bodyCount = body.decoded.length;
         if (bodyCount !== null && profileCount > bodyCount) {
-          throw ctx.E("cmp/bad-info-value", "a certProfile carries " + profileCount + " profile name(s), more than the " + bodyCount + " the " + body.arm + " body permits (RFC 9810 §5.1.1.4)");
+          throw ctx.E("cmp/bad-info-value", "a certProfile carries " + profileCount + " profile name(s), more than the " + bodyCount + " the " + body.arm + " body permits (RFC 9810 sec. 5.1.1.4)");
         }
       }
     }
-    // RFC 9810 §5.3.13/§7 — the cAKeyUpdAnnV3 [0] RootCaKeyUpdateContent CA key
+    // RFC 9810 sec. 5.3.13/sec. 7 -- the cAKeyUpdAnnV3 [0] RootCaKeyUpdateContent CA key
     // update form is cmp2021(3) syntax; a ckuann using it under pvno < 3 is a
     // version mismatch. ckuann surfaces raw, so inspect its top-level tag: the
     // deprecated cAKeyUpdAnnV2 is a universal SEQUENCE, the v3 form is [0].
     if (body.arm === "ckuann" && header.pvno !== 3) {
       var caKeyUpd = asn1.decode(body.bytes);
       if (caKeyUpd.tagClass === "context" && caKeyUpd.tagNumber === 0) {
-        throw ctx.E("cmp/bad-version", "a ckuann using the cAKeyUpdAnnV3 [0] RootCaKeyUpdateContent form requires CMP version cmp2021(3) (RFC 9810 §5.3.13, §7)");
+        throw ctx.E("cmp/bad-version", "a ckuann using the cAKeyUpdAnnV3 [0] RootCaKeyUpdateContent form requires CMP version cmp2021(3) (RFC 9810 sec. 5.3.13, sec. 7)");
+      }
+    }
+    // RFC 9810 sec. 5.2.8.3.2/sec. 7 -- Challenge.encryptedRand [0] EnvelopedData is
+    // cmp2021(3) syntax (the replacement for the deprecated challenge field).
+    // popdecc surfaces raw, so inspect the already-decoded Challenges the same
+    // way the ckuann gate inspects its top-level tag: a Challenge carrying a
+    // context [0] (its only context-tagged field) under pvno < 3 is a version
+    // mismatch; a non-Challenges shape stays on the documented raw posture.
+    if (body.arm === "popdecc" && header.pvno !== 3) {
+      var challenges = asn1.decode(body.bytes);
+      if (challenges.tagClass === "universal" && challenges.tagNumber === TAGS.SEQUENCE && challenges.children) {
+        for (var chi = 0; chi < challenges.children.length; chi++) {
+          var chKids = challenges.children[chi].children;
+          for (var chf = 0; chKids && chf < chKids.length; chf++) {
+            if (chKids[chf].tagClass === "context" && chKids[chf].tagNumber === 0) {
+              throw ctx.E("cmp/bad-version", "a popdecc Challenge carrying encryptedRand [0] EnvelopedData requires CMP version cmp2021(3) (RFC 9810 sec. 5.2.8.3.2, sec. 7)");
+            }
+          }
+        }
       }
     }
     return {
@@ -832,7 +848,7 @@ var PKI_MESSAGE = schema.seq([
  * Parse a DER `Buffer` or a PEM string into a structured PKIMessage:
  * `{ header, headerBytes, body, bodyBytes, protection, extraCerts }`.
  * `header` carries `pvno` (1..3), `sender` / `recipient` (validated
- * GeneralNames — the anonymous NULL-DN form included), and the optional
+ * GeneralNames -- the anonymous NULL-DN form included), and the optional
  * `messageTime`, `protectionAlg`, `senderKID` / `recipKID`,
  * `transactionID`, `senderNonce` / `recipNonce`, `freeText`, and
  * `generalInfo` (recognized id-it types value-checked: implicitConfirm is
@@ -841,24 +857,29 @@ var PKI_MESSAGE = schema.seq([
  * (`ir` / `cr` / `kur` / `krr` / `ccr`) decode via the CRMF parser;
  * `ip` / `cp` / `kup` / `ccp` decode to `{ caPubs, response }` (an encrypted
  * certificate's EnvelopedData decodes via the CMS parser; the deprecated
- * EncryptedValue arm and `caPubs` surface raw — the parser confers no
+ * EncryptedValue arm and `caPubs` surface raw -- the parser confers no
  * trust); `krp` decodes to `{ status, newSigCert, caCerts, keyPairHist }`;
  * `rr` / `rp`, `genm` / `genp`, `error`, `certConf` (an empty
  * confirmation is the legal reject-all), and `pollReq` / `pollRep` decode
- * structurally; `pkiconf` decodes to `null`; every other defined arm —
+ * structurally; `pkiconf` decodes to `null`; every other defined arm --
  * `p10cr` (feed `body.bytes` to `pki.schema.csr.parse`), the
  * challenge-response and announcement arms, and `nested` (never
- * auto-recursed) — surfaces raw with `decoded` absent. `certReqId` values
+ * auto-recursed) -- surfaces raw with `decoded` absent. `certReqId` values
  * are BigInt and accept the protocol's -1 sentinel.
  *
- * Protection is surfaced, not verified: `protection` carries the raw BIT
- * STRING, and the MAC or signature is computed over the DER of the virtual
- * `ProtectedPart ::= SEQUENCE { header, body }` — reconstruct it as a DER
+ * Protection is surfaced, not verified: `protection` carries the raw,
+ * octet-aligned BIT STRING (unused bits are rejected at parse -- every
+ * RFC 9481 protection algorithm emits whole octets), and the MAC or
+ * signature is computed over the DER of the virtual
+ * `ProtectedPart ::= SEQUENCE { header, body }` -- reconstruct it as a DER
  * SEQUENCE wrapping exactly `headerBytes || bodyBytes`. `extraCerts` are
  * raw DER certificates and are NOT covered by protection.
  *
  * Throws `CmpError` when the bytes are not a well-formed PKIMessage, and
- * `Asn1Error` when the underlying DER is malformed.
+ * `Asn1Error` when the underlying DER is malformed. The request-arm interiors
+ * (`ir` / `cr` / `kur` / `krr` / `ccr`, and an `rr` entry's `certDetails`) are
+ * walked by the CRMF parser, so a malformed interior throws `CrmfError` with a
+ * `crmf/*` code -- all `PkiError` subclasses.
  *
  * @example
  *   var m = pki.schema.cmp.parse(der);
@@ -879,7 +900,7 @@ var parse = pkix.makeParser({
  * @related    pki.schema.cmp.parse
  *
  * Extract the DER bytes from a PEM block (default label `CMP`). CMP is
- * wire-DER over HTTP (RFC 9811) — the PEM path is a convenience for
+ * wire-DER over HTTP (RFC 9811) -- the PEM path is a convenience for
  * messages that transit text channels.
  *
  * @example
@@ -907,7 +928,7 @@ function pemEncode(der, label) { return pkix.pemEncode(der, label || "CMP", PemE
 // (PKIBody) is context-class constructed [0..26]. The one overlap in the
 // registry is one-directional: a 2-child PKIMessage with body ir [0] also
 // satisfies the shallow ocsp-request probe, so this detector registers AHEAD
-// of ocsp-request — while every real OCSPRequest fails here (its tbsRequest
+// of ocsp-request -- while every real OCSPRequest fails here (its tbsRequest
 // never leads with a bare INTEGER).
 function matches(root) {
   var k = pkix.rootSequenceChildren(root, 2, 4);