@blamejs/pki 0.6.13 → 0.6.15

package/lib/schema-cmc.js

@@ -53,7 +53,6 @@ var TAGS = asn1.TAGS;
 function E(code, message, cause) { return new CmcError(code, message, cause); }
 function O(name) { return oid.byName(name); }
 
-// Registry constants -- never a dotted literal in a format module.
 var OID_PKI_DATA = O("id-cct-PKIData");
 var OID_PKI_RESPONSE = O("id-cct-PKIResponse");
 var OID_STATUS_INFO = O("id-cmc-statusInfo");
@@ -61,21 +60,13 @@ var OID_STATUS_INFO_V2 = O("id-cmc-statusInfoV2");
 var OID_RESPONSE_BODY = O("id-cmc-responseBody");
 var OID_RA_IDENTITY_WITNESS = O("id-cmc-raIdentityWitness");
 
-// BodyPartID ::= INTEGER (0..4294967295), RFC 5272 sec. 3.2.2.
 var BODY_PART_MAX = 4294967295n;
 
-// CMCStatus ::= INTEGER { success(0), failed(2), pending(3), noSupport(4),
-// confirmRequired(5), popRequired(6), partial(7) }, RFC 5272 sec. 6.1.3.
-// 1 is reserved: it is neither a success nor a failure, so it is refused and
-// never folded into either.
 var STATUS_BY_VALUE = {
   0: "success", 2: "failed", 3: "pending", 4: "noSupport",
   5: "confirmRequired", 6: "popRequired", 7: "partial",
 };
 
-// CMCFailInfo ::= INTEGER { ... }, RFC 5272 sec. 6.1.4. Values outside this set
-// are surfaced numerically and never refused: sec. 6.1.4 reserves 1000..1999
-// for private extended reasons, so an unknown number is legal data.
 var FAIL_INFO_BY_VALUE = {
   0: "badAlg", 1: "badMessageCheck", 2: "badRequest", 3: "badTime", 4: "badCertId",
   5: "unsupportedExt", 6: "mustArchiveKeys", 7: "badIdentity", 8: "popRequired",
@@ -83,35 +74,18 @@ var FAIL_INFO_BY_VALUE = {
   13: "authDataFail",
 };
 
-// The CMS content types a Full PKI Request / Response may ride in, per RFC 5272
-// sec. 3.2 ("encapsulated in either a SignedData or an AuthenticatedData") and
-// sec. 4.2, which says the same of the response.
-// The names are the OID registry's, read off `oid.name(...)` and never taken from the
-// spec's prose: RFC 5652 calls the type AuthenticatedData, the registry row is
-// `authData`, and hard-coding the prose spelling would reject every conforming
-// AuthenticatedData response while looking correct.
 var CMC_CARRIERS = { signedData: 1, authData: 1 };
 
-// Control PLACEMENT -- RFC 6402 sec. 2.5 / 2.6 give two MUSTs about where a
-// control may appear. An OID-keyed table states them once, in the shape of the
-// shipped CMS attribute-placement registry, so a new placement rule is a row.
 var CONTROL_PLACEMENT = {};
-CONTROL_PLACEMENT[OID_RESPONSE_BODY] = "pkiResponse";      // sec. 2.6: never in a PKIData
-CONTROL_PLACEMENT[OID_RA_IDENTITY_WITNESS] = "pkiData";    // sec. 2.5: never in a PKIResponse
+CONTROL_PLACEMENT[OID_RESPONSE_BODY] = "pkiResponse";
+CONTROL_PLACEMENT[OID_RA_IDENTITY_WITNESS] = "pkiData";
 
-// ---- leaves ----------------------------------------------------------
 
-// A BodyPartID read + bounded + narrowed atomically. `guard.range.int` takes
-// BigInt bounds and returns a Number only when the value is inside them, so an
-// out-of-range identifier can never reach the caller as a silently-truncated int.
 function readBodyPartId(node, label) {
   var v = asn1.read.integer(node);
   return guard.range.int(v, 0n, BODY_PART_MAX, E, "cmc/bad-body-part-id", label || "a BodyPartID");
 }
 
-// The identity of an element, where 0 is reserved (RFC 5272 sec. 3.2.2: "The
-// bodyPartID value of 0 is reserved for use as the reference to the current
-// PKIData object"). A REFERENCE may be 0; an identity may not.
 function readBodyPartIdentity(node) {
   var id = readBodyPartId(node, "a body part identity");
   if (id === 0) {
@@ -121,16 +95,7 @@ function readBodyPartIdentity(node) {
   return id;
 }
 
-// ---- controls --------------------------------------------------------
 
-// TaggedAttribute ::= SEQUENCE { bodyPartID BodyPartID, attrType OBJECT
-// IDENTIFIER, attrValues SET OF AttributeValue }, RFC 5272 sec. 3.2.1.1.
-// attrValues are surfaced raw: this decoder does not know every control, and
-// PD7's "fail on an unrecognized control" binds the server, not a client reading
-// a response, so an unknown value is data to hand on, never a fault.
-//
-// The placement rule is not checked here: it depends on which message the control
-// sits in, which the enclosing walk knows and this shape does not.
 var TAGGED_ATTRIBUTE = schema.seq([
   schema.field("bodyPartID", schema.decode(readBodyPartIdentity)),
   schema.field("attrType", schema.oidLeaf()),
@@ -149,8 +114,6 @@ var TAGGED_ATTRIBUTE = schema.seq([
   },
 });
 
-// RFC 6402 sec. 2.5 / 2.6 give two MUSTs about WHERE a control may appear, and
-// both are one-directional. Applied against the enclosing message kind.
 function assertControlPlacement(control, where) {
   var placement = CONTROL_PLACEMENT[control.attrType];
   if (placement && placement !== where) {
@@ -160,11 +123,7 @@ function assertControlPlacement(control, where) {
   }
 }
 
-// ---- status controls -------------------------------------------------
 
-// BodyPartReference ::= CHOICE { bodyPartID BodyPartID, bodyPartPath BodyPartPath }
-// (an INTEGER and a SEQUENCE, so the arms are tag-disjoint). BodyPartPath is
-// SEQUENCE SIZE(1..MAX), so an empty one is malformed, never "no path".
 function parseBodyPartReference(node) {
   if (node.tagClass === "universal" && node.tagNumber === TAGS.INTEGER) {
     return { bodyPartID: readBodyPartId(node), bodyPartPath: null };
@@ -178,33 +137,8 @@ function parseBodyPartReference(node) {
   throw E("cmc/bad-status-info", "a BodyPartReference must be a BodyPartID INTEGER or a BodyPartPath SEQUENCE");
 }
 
-/**
- * OtherStatusInfo ::= CHOICE { failInfo CMCFailInfo, pendInfo PendInfo,
- *                              extendedFailInfo SEQUENCE { ... } }
- *
- * The load-bearing ambiguity. RFC 5272 App A and RFC 6402 App A.1 (the 1988
- * module) leave `extendedFailInfo` UNTAGGED, so it collides with `pendInfo` --
- * both are a bare SEQUENCE. RFC 6402 App A.2 (the 2008 module) tags it `[1]`.
- * Both encodings occur on the wire, so both are decoded:
- *
- *   universal INTEGER   -> failInfo
- *   context [1]         -> extendedFailInfo (2008 module)
- *   universal SEQUENCE  -> disambiguate on the first child's tag:
- *                            OCTET STRING -> pendInfo  (PendInfo ::= SEQUENCE
- *                              { pendToken OCTET STRING, pendTime GeneralizedTime })
- *                            OBJECT IDENTIFIER -> extendedFailInfo
- *   anything else       -> refuse
- *
- * The final arm is the point: a shape that matches neither rule is REFUSED, not
- * guessed at. Guessing here would attach a failure reason, or a pending token,
- * that the responder never sent.
- */
+
 function parseOtherStatusInfo(node, version) {
-  // The extendedFailInfo arm belongs to CMCStatusInfoV2 alone. RFC 5272 sec. 6.1.1
-  // gives the v1 otherInfo exactly two arms, `CHOICE { failInfo CMCFailInfo,
-  // pendInfo PendInfo }`, so accepting the third here would read a failure
-  // verdict out of a v1 control that cannot legally express one, and the
-  // disambiguation below would be answering a question v1 never asks.
   var extendedAllowed = version !== 1;
   if (node.tagClass === "universal" && node.tagNumber === TAGS.INTEGER) {
     var v = asn1.read.integer(node);
@@ -216,13 +150,6 @@ function parseOtherStatusInfo(node, version) {
       throw E("cmc/bad-status-info",
         "a v1 CMCStatusInfo otherInfo is failInfo or pendInfo only; the [1] extendedFailInfo arm is CMCStatusInfoV2's (RFC 5272 sec. 6.1.1)");
     }
-    // IMPLICIT, so the [1] REPLACES the SEQUENCE tag and its children are the
-    // failInfoOID / failInfoValue directly -- there is no inner SEQUENCE to
-    // unwrap. Both RFC 6402 modules are IMPLICIT: A.1 (rfc6402.txt:805) and A.2
-    // (rfc6402.txt:1314) each open `DEFINITIONS IMPLICIT TAGS ::=`, and the
-    // EXPLICIT-override rule does not apply here because the tagged type is a
-    // plain SEQUENCE, not a CHOICE or an open type. Reading this arm as
-    // EXPLICIT would reject every conforming 2008-module response.
     return { failInfo: null, failInfoName: null, pendInfo: null, extendedFailInfo: readExtendedFailInfo(node.children, "[1] extendedFailInfo") };
   }
   if (node.tagClass === "universal" && node.tagNumber === TAGS.SEQUENCE && node.constructed) {
@@ -230,9 +157,6 @@ function parseOtherStatusInfo(node, version) {
     if (!first) throw E("cmc/ambiguous-status-info", "an empty OtherStatusInfo SEQUENCE matches neither pendInfo nor extendedFailInfo");
     if (first.tagClass === "universal" && first.tagNumber === TAGS.OCTET_STRING) {
       if (node.children.length !== 2) throw E("cmc/bad-status-info", "PendInfo must be { pendToken, pendTime }");
-      // pendTime is a GeneralizedTime specifically, so assert the tag and do not
-      // accept either time form: a UTCTime here is a different encoding, and
-      // reading it anyway would let a two-digit year through the retry clock.
       var timeNode = node.children[1];
       if (timeNode.tagClass !== "universal" || timeNode.tagNumber !== TAGS.GENERALIZED_TIME) {
         throw E("cmc/bad-status-info", "PendInfo pendTime must be a GeneralizedTime (RFC 5272 sec. 6.1.1)");
@@ -255,10 +179,6 @@ function parseOtherStatusInfo(node, version) {
   throw E("cmc/bad-status-info", "OtherStatusInfo must be a CMCFailInfo INTEGER, a PendInfo SEQUENCE, or an extendedFailInfo");
 }
 
-// ExtendedFailInfo ::= SEQUENCE { failInfoOID OBJECT IDENTIFIER, failInfoValue ANY }
-// The OID is surfaced raw and never mapped onto a CMCFailInfo: RFC 5272 sec.
-// 6.1.1 makes internalCAError only a MAY for an unrecognized extended error, and
-// synthesizing it would report a reason the responder did not send.
 function readExtendedFailInfo(children, what) {
   if (!children || children.length !== 2) {
     throw E("cmc/bad-status-info", what + " must be SEQUENCE { failInfoOID, failInfoValue }");
@@ -266,12 +186,6 @@ function readExtendedFailInfo(children, what) {
   return { failInfoOID: asn1.read.oid(children[0]), failInfoValueBytes: children[1].bytes };
 }
 
-// CMCStatusInfoV2 ::= SEQUENCE { cMCStatus, bodyList SEQUENCE SIZE(1..MAX) OF
-//   BodyPartReference, statusString UTF8String OPTIONAL, otherInfo OPTIONAL }
-// The v1 CMCStatusInfo is the same shape with a SEQUENCE OF BodyPartID bodyList
-// and no extendedFailInfo arm; both are decoded into one surface so a caller
-// reads one ordered list of verdicts (RFC 5272 sec. 6.1: a client MUST cope with
-// several status controls).
 function parseStatusInfo(valueDer, version, bodyPartID) {
   var root = asn1.decode(valueDer);
   if (root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE || !root.constructed) {
@@ -284,8 +198,6 @@ function parseStatusInfo(valueDer, version, bodyPartID) {
   var statusNum = guard.range.int(statusValue, 0n, 0xFFFFFFFFn, E, "cmc/bad-status", "a CMCStatus");
   var statusName = STATUS_BY_VALUE[statusNum];
   if (!statusName) {
-    // 1 is reserved and everything above 7 is unassigned. An unknown status is
-    // not a verdict in either direction, so it is refused and never mapped.
     throw E("cmc/bad-status", "unknown CMCStatus " + statusNum + " (1 is reserved; RFC 5272 sec. 6.1.3)");
   }
 
@@ -300,17 +212,10 @@ function parseStatusInfo(valueDer, version, bodyPartID) {
     return version === 2 ? parseBodyPartReference(c) : { bodyPartID: readBodyPartId(c), bodyPartPath: null };
   });
 
-  // The two OPTIONAL tail fields are ORDERED by the ASN.1: statusString precedes
-  // otherInfo. Tracking only "have I seen a statusString yet" would accept them
-  // reversed -- a second encoding of a structure DER admits exactly one encoding
-  // of -- so the walk refuses anything once otherInfo has been consumed.
   var statusString = null, other = null, sawOther = false;
   for (var i = 2; i < kids.length; i++) {
     var k = kids[i];
     if (k.tagClass === "universal" && k.tagNumber === TAGS.UTF8_STRING && statusString === null && !sawOther) {
-      // read.string, not a per-type reader: the codec exposes one strict text reader
-      // for the DirectoryString family and there is no `read.utf8`. The tag is
-      // already asserted UTF8String above, so this decodes exactly that.
       statusString = asn1.read.string(k);
       continue;
     }
@@ -334,11 +239,6 @@ function parseStatusInfo(valueDer, version, bodyPartID) {
   return out;
 }
 
-// The cross-field coupling (RFC 5272 sec. 6.1.1 / 6.1.2): failInfo and
-// extendedFailInfo are "present only if cMCStatus contains the value failed",
-// and pendInfo "MUST be populated for a cMCStatus value of pending or partial".
-// A message whose status and detail disagree is refused, never reconciled:
-// the two halves would otherwise let a caller read a verdict neither field states.
 function _assertStatusCoherent(s) {
   var isFailed = s.status === "failed";
   var isPending = s.status === "pending" || s.status === "partial";
@@ -356,19 +256,7 @@ function _assertStatusCoherent(s) {
   }
 }
 
-// ---- tagged requests -------------------------------------------------
-
-// TaggedRequest ::= CHOICE { tcr [0] TaggedCertificationRequest,
-//                           crm [1] CertReqMsg,
-//                           orm [2] SEQUENCE { bodyPartID, requestMessageType,
-//                                              requestMessageValue } }
-// The CMC module is IMPLICIT TAGS, so each context tag REPLACES the arm's own
-// universal tag: the [0] node's direct children are the TaggedCertificationRequest
-// fields, not a nested SEQUENCE. An EXPLICIT encoding is therefore a different
-// (and invalid) message, which is what C5 pins.
-// An IMPLICIT context-tagged constructed node re-encoded under the universal
-// SEQUENCE tag it stands in for. IMPLICIT tagging REPLACES the tag and leaves the
-// content untouched, so restoring it is exactly a re-headering of the same bytes.
+
 function _asUniversalSequence(node) {
   var headerLen = node.header.end - node.header.start;
   return asn1.encode(0x00, true, TAGS.SEQUENCE, node.bytes.subarray(headerLen));
@@ -379,7 +267,6 @@ function parseTaggedRequest(node) {
     throw E("cmc/bad-tagged-request", "a TaggedRequest must be a context-tagged constructed CHOICE arm (RFC 5272 sec. 3.2.1.2)");
   }
   if (node.tagNumber === 0) {
-    // TaggedCertificationRequest ::= SEQUENCE { bodyPartID, certificationRequest }
     if (node.children.length !== 2) {
       throw E("cmc/bad-tagged-request", "a tcr arm is [0] IMPLICIT { bodyPartID, certificationRequest }; the module is IMPLICIT TAGS, so an EXPLICIT wrapper is not this arm");
     }
@@ -394,23 +281,6 @@ function parseTaggedRequest(node) {
     };
   }
   if (node.tagNumber === 1) {
-    // crm [1] IMPLICIT CertReqMsg.
-    //
-    // This arm still has a body part IDENTITY, and it is not a separate field:
-    // RFC 5272 sec. 3.2.2 says "Body part identifiers are encoded in the
-    // certReqIds field for CertReqMsg objects (in a TaggedRequest) or in the
-    // bodyPartID field of the other objects", and sec. 6.5.2 repeats it
-    // ("... either the bodyPartID of a TaggedCertificationRequest (PKCS #10) or
-    // the certReqId of the CertRequest within a CertReqMsg (CRMF)"). So the
-    // certReqId is read here and carried into the same whole-message uniqueness
-    // check every other body part is bound by; returning null would silently
-    // exempt this arm from it.
-    //
-    //   CertReqMsg  ::= SEQUENCE { certReq CertRequest, popo OPTIONAL, regInfo OPTIONAL }
-    //   CertRequest ::= SEQUENCE { certReqId INTEGER, certTemplate CertTemplate, ... }
-    //
-    // Only the identity is decoded here; the CertReqMsg's own conformance is
-    // pki.schema.crmf's to enforce, and duplicating it would fork the rules.
     var certReq = node.children[0];
     if (!certReq || certReq.tagClass !== "universal" || certReq.tagNumber !== TAGS.SEQUENCE || !certReq.constructed) {
       throw E("cmc/bad-tagged-request", "a crm arm is [1] IMPLICIT CertReqMsg, whose first element is a CertRequest SEQUENCE");
@@ -421,9 +291,6 @@ function parseTaggedRequest(node) {
     return {
       arm: "crm", bodyPartID: readBodyPartIdentity(certReq.children[0]),
       certificationRequestBytes: null,
-      // Re-tagged from the IMPLICIT [1] back to the universal SEQUENCE the CRMF
-      // parser expects: handing back the context-tagged bytes would produce a
-      // structure no CertReqMsg reader accepts.
       certReqMsgBytes: _asUniversalSequence(node),
       requestMessageType: null, requestMessageValueBytes: null,
     };
@@ -442,12 +309,7 @@ function parseTaggedRequest(node) {
   throw E("cmc/bad-tagged-request", "unknown TaggedRequest alternative [" + node.tagNumber + "] (RFC 5272 sec. 3.2.1.2)");
 }
 
-// ---- body-part identity ----------------------------------------------
 
-// RFC 5272 sec. 3.2.2: "The body part identifier MUST be unique within a single
-// PKIData or PKIResponse." The scope is the whole message: a checker that ran
-// per-sequence would accept a control and a request that collide, which is
-// exactly the shape B2 pins.
 function assertUniqueBodyPartIds(ids) {
   var seen = Object.create(null);
   for (var i = 0; i < ids.length; i++) {
@@ -460,21 +322,7 @@ function assertUniqueBodyPartIds(ids) {
   }
 }
 
-// ---- the two message bodies ------------------------------------------
-
-// The two message bodies as engine schemas. Declaring them means the engine owns
-// the positional reads, the field arity and the SET-OF ordering (the bug class
-// a hand-rolled cursor keeps reintroducing), while the rules that genuinely span
-// fields (whole-message body-part uniqueness, control placement, the status
-// cross-checks) run in the build / the caller, which is where they can see
-// everything they need.
-// A repeat's walk result is the match object `{ node, items: [{ node, value }] }`,
-// so each of these carries a `build` that flattens it to the plain list the
-// enclosing build wants. The three differ by what an item's `value` IS, which is
-// decided by the item schema:
-//   - a `seq` item walks to its own MATCH, so its build output is at .value.result
-//   - a `decode` leaf walks straight to whatever its function returned
-//   - an `any` item walks to the node, whose .bytes is the raw TLV
+
 function builtList(match) { return match.items.map(function (i) { return i.value.result; }); }
 function decodedList(match) { return match.items.map(function (i) { return i.value; }); }
 function rawList(match) { return match.items.map(function (i) { return i.node.bytes; }); }
@@ -484,26 +332,12 @@ var CONTROL_SEQUENCE = schema.seqOf(TAGGED_ATTRIBUTE,
 var REQ_SEQUENCE = schema.seqOf(schema.decode(parseTaggedRequest),
   { code: "cmc/bad-tagged-request", what: "a reqSequence", build: decodedList });
 
-// TaggedContentInfo ::= SEQUENCE { bodyPartID, contentInfo } (RFC 5272 sec.
-// 3.2.1.3) and OtherMsg ::= SEQUENCE { bodyPartID, otherMsgType, otherMsgValue }
-// (sec. 3.2.1.4). Neither payload is interpreted here (the ContentInfo is a
-// CMS object the caller decodes, the OtherMsg value is by definition arbitrary),
-// but both carry a body part identity, and sec. 3.2.2's uniqueness rule covers
-// "each element of a PKIData or PKIResponse". Decoding just the identifier is
-// what lets that rule cover them without this layer claiming to understand the
-// payload.
 var TAGGED_CONTENT_INFO = schema.seq([
   schema.field("bodyPartID", schema.decode(readBodyPartIdentity)),
   schema.field("contentInfo", schema.any()),
 ], {
   assert: "sequence", arity: { exact: 2 }, code: "cmc/bad-cms-sequence", what: "a TaggedContentInfo",
   build: function (m) {
-    // The payload stays raw, since this layer does not decode a content type it may
-    // not know, but it must still be a ContentInfo: SEQUENCE { contentType
-    // OBJECT IDENTIFIER, content [0] EXPLICIT ANY OPTIONAL } (RFC 5652 sec. 3).
-    // Surfacing an INTEGER, or anything else that cannot be one, as a content
-    // info would hand the caller a "CMS message" no CMS reader will accept, which
-    // is not the same thing as a content type this decoder happens not to handle.
     var ci = m.fields.contentInfo.value;
     var kids = ci.children || [];
     var lead = kids[0];
@@ -511,23 +345,11 @@ var TAGGED_CONTENT_INFO = schema.seq([
       throw E("cmc/bad-cms-sequence",
         "a TaggedContentInfo carries a CMS ContentInfo, which leads with its contentType OBJECT IDENTIFIER (RFC 5652 sec. 3)");
     }
-    // Read the contentType; do not merely inspect its tag. An OBJECT IDENTIFIER
-    // TLV can carry content no OID reader will accept (empty, or a subidentifier
-    // padded to a non-minimal encoding) and a tag check waves both through. The
-    // toolkit's own CMS parser refuses them, so accepting them here would let the
-    // builder sign a "CMS message" pki.schema.cms.parse will not read back. The
-    // VALUE is still not interpreted: this layer only establishes that there is a
-    // content type to interpret.
     try { asn1.read.oid(lead); }
     catch (e) {
       throw E("cmc/bad-cms-sequence",
         "a TaggedContentInfo carries a CMS ContentInfo, whose contentType must be a readable OBJECT IDENTIFIER (RFC 5652 sec. 3)", e);
     }
-    // The whole envelope, not just its first field: content is `[0] EXPLICIT ANY
-    // DEFINED BY contentType OPTIONAL`, so at most one more element and it is that
-    // tag. An INTEGER sitting where the content belongs, or a third field, is not
-    // a ContentInfo any CMS reader will take, and stopping at the leading OID
-    // would surface it as one.
     if (kids.length > 2) {
       throw E("cmc/bad-cms-sequence",
         "a CMS ContentInfo is { contentType, [0] EXPLICIT content OPTIONAL }; this carries " +
@@ -539,10 +361,6 @@ var TAGGED_CONTENT_INFO = schema.seq([
         throw E("cmc/bad-cms-sequence",
           "a CMS ContentInfo's second field is the [0] EXPLICIT content (RFC 5652 sec. 3)");
       }
-      // EXPLICIT wraps exactly one value (X.690 sec. 8.14). Checking the tag alone
-      // would let an empty wrapper, or one holding several values, read as a content
-      // info: shapes pki.schema.cms.parse refuses as cms/not-a-content-info, so the
-      // builder's readback would pass a message its own CMS reader will not accept.
       if (!content.children || content.children.length !== 1) {
         throw E("cmc/bad-cms-sequence",
           "a ContentInfo's [0] EXPLICIT content wraps exactly one value, got " +
@@ -568,9 +386,6 @@ var OTHER_MSG = schema.seq([
   },
 });
 
-// PKIData ::= SEQUENCE { controlSequence, reqSequence, cmsSequence,
-//   otherMsgSequence }, RFC 5272 sec. 3.2.1. All four are mandatory though each
-// may be empty, so `arity: { exact: 4 }` is the rule, not a convenience.
 var PKI_DATA = schema.seq([
   schema.field("controlSequence", CONTROL_SEQUENCE),
   schema.field("reqSequence", REQ_SEQUENCE),
@@ -588,17 +403,11 @@ var PKI_DATA = schema.seq([
       requests: m.fields.reqSequence.value.result,
       cmsSequence: m.fields.cmsSequence.value.result,
       otherMsgs: m.fields.otherMsgSequence.value.result,
-      // The raw reqSequence TLV, tag and length included: the Identity Proof V2
-      // witness is computed over exactly these bytes "encoded exactly as it
-      // appears in the Full PKI Request" (RFC 5272 sec. 6.2.1), so it is taken
-      // off the matched node, never re-encoded from the decoded requests.
       reqSequenceBytes: m.fields.reqSequence.node.bytes,
     };
   },
 });
 
-// PKIResponse ::= SEQUENCE { controlSequence, cmsSequence, otherMsgSequence } --
-// RFC 5272 sec. 4.2.1. THREE fields: there is no reqSequence in a response.
 var PKI_RESPONSE = schema.seq([
   schema.field("controlSequence", CONTROL_SEQUENCE),
   schema.field("cmsSequence", schema.seqOf(TAGGED_CONTENT_INFO,
@@ -620,10 +429,6 @@ var PKI_RESPONSE = schema.seq([
   },
 });
 
-// Collect the status controls out of an already-parsed control list, in wire
-// order. Absence is not an error: RFC 5272 sec. 6.1.2 says "If no status exists
-// for a Simple or Full PKI Request, then the value of success is assumed", so a
-// response with no status control is a successful one.
 function _collectStatuses(controls) {
   var out = [];
   for (var i = 0; i < controls.length; i++) {
@@ -638,21 +443,12 @@ function _collectStatuses(controls) {
   return out;
 }
 
-// The cross-cutting rules that a per-field walk cannot see: where each control is
-// allowed to appear, which of them are status verdicts, which are unrecognized
-// (surfaced, never a fault), and the whole-message body-part uniqueness.
 function _finishBody(body, where) {
   for (var i = 0; i < body.controls.length; i++) assertControlPlacement(body.controls[i], where);
   body.statuses = _collectStatuses(body.controls);
   body.unhandled = body.controls.filter(function (c) {
     return c.attrType !== OID_STATUS_INFO && c.attrType !== OID_STATUS_INFO_V2 && c.attrName === null;
   });
-  // RFC 5272 sec. 3.2.2 scopes uniqueness to "each element of a PKIData or
-  // PKIResponse", and four element kinds carry an identity. Enumerated here in
-  // one place so the rule cannot hold for some of them and quietly lapse for the
-  // rest: controls (sec. 3.2.1.1), requests (sec. 3.2.1.2, the tcr/orm
-  // bodyPartID and the crm arm's certReqId), content infos (sec. 3.2.1.3) and
-  // other messages (sec. 3.2.1.4).
   var ids = [];
   function collect(list) { for (var j = 0; j < list.length; j++) ids.push(list[j].bodyPartID); }
   collect(body.controls);
@@ -745,20 +541,9 @@ function parsePkiResponse(input) {
  *   pki.schema.cmc.parse(der).kind;   // "pkiData"
  */
 function parse(input) {
-  // Bytes or an already-parsed CMS? Decided by a POSITIVE marker of the parsed
-  // shape, never by "it is an object" -- a Uint8Array is an object too, so the
-  // looser test routes perfectly good DER to the parsed branch, where it has no
-  // content type and is refused as not-CMC while the identical Buffer parses.
-  // encapContentInfo is the field this function goes on to read, so requiring it
-  // is the same question the code below already asks.
   var parsedCms = (input && typeof input === "object" && !ArrayBuffer.isView(input) &&
     !guard.bytes.isByteSource(input) && input.encapContentInfo != null)
     ? input : cms.parse(input);
-  // The CARRIER is part of the identity, not just the encapsulated content type.
-  // RFC 5272 sec. 3.2 / 4.2 admit a SignedData or an AuthenticatedData; other CMS
-  // types also expose an encapContentInfo (CompressedData does), and dispatching
-  // on the inner OID alone would accept an unsigned, unauthenticated wrapper as a
-  // Full PKI message.
   if (CMC_CARRIERS[parsedCms.contentTypeName] !== 1) {
     throw E("cmc/not-cmc",
       "a Full PKI Request / Response is carried in a CMS SignedData or AuthenticatedData, got " +