@blamejs/pki 0.6.13 → 0.6.15

package/lib/schema-ocsp.js

@@ -40,53 +40,30 @@ var oid = require("./oid");
 var constants = require("./constants");
 var frameworkError = require("./framework-error");
 var intrinsic = require("./guard-intrinsic");
-// Own-key membership through an operation taken at load. Written out, the question reads two
-// replaceable properties to answer one thing, and here it decides which response statuses and
-// revocation reasons are defined -- an admitted name names a status RFC 6960 never assigned.
 var _hasOwn = intrinsic.hasOwn;
 
 var OcspError = frameworkError.OcspError;
 var PemError = frameworkError.PemError;
 
-// The ocsp error namespace the schema engine walks under.
 var NS = pkix.makeNS("ocsp", OcspError, oid);
 
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
 var EXTENSIONS = pkix.extensions(NS);
 
-// Version ::= INTEGER { v1(0) }. OCSP defines only v1(0), which DER forbids
-// encoding (it is the DEFAULT), so ANY explicitly-encoded version is a fault; the
-// empty accept map rejects every value and absence yields the default 1.
 var VERSION = pkix.versionReader(NS, {});
 
-// id-pkix-ocsp-basic is the one ResponseBytes.responseType this build decodes; any
-// other is recognized-and-deferred. Resolved from the registry, never a literal.
 var OID_OCSP_BASIC = oid.byName("ocspBasic");
 
-// id-pkix-ocsp-nonce -- the request/response binding extension whose value syntax
-// RFC 9654 sec. 2.1 (updating RFC 6960 sec. 4.4.1) fixes to OCTET STRING (SIZE(1..128)).
 var OID_OCSP_NONCE = oid.byName("ocspNonce");
 
-// OCSPResponseStatus ::= ENUMERATED. Value 4 is "not used" and >= 7 is undefined,
-// so both are rejected (RFC 6960 sec. 4.2.1).
-// OCSPResponseStatus value names -- single source pki.C.NAMES.OCSP_STATUS.
 var STATUS_NAMES = constants.NAMES.OCSP_STATUS;
 
-// CRLReason ::= ENUMERATED. Value 7 is "not used"; the rest are RFC 5280
-// sec. 5.3.1. The legal set + names live once in pkix.CRL_REASON_NAMES (shared
-// with the CRL reasonCode decoder, which surfaces the numeric code).
 var CRL_REASONS = pkix.CRL_REASON_NAMES;
 
-// ---- shared leaves ---------------------------------------------------
 
-// A GeneralizedTime-only leaf. OCSP times (producedAt / thisUpdate / nextUpdate /
-// revocationTime) are GeneralizedTime, never UTCTime (RFC 6960); assert the tag
-// before the codec reads it so a UTCTime is rejected ocsp/bad-time.
 var GENERALIZED_TIME = pkix.generalizedTime(NS, { code: "ocsp/bad-time", message: "OCSP time must be a GeneralizedTime (RFC 6960)" });
 
-// OCSPResponseStatus decode-and-whitelist leaf. read.enumerated is tag-checked, so
-// an INTEGER-encoded status is rejected at the leaf (asn1/unexpected-tag).
 var OCSP_RESPONSE_STATUS = schema.decode(function (n, ctx) {
   var v = asn1.read.enumerated(n);
   var key = v.toString();
@@ -94,7 +71,6 @@ var OCSP_RESPONSE_STATUS = schema.decode(function (n, ctx) {
   return { code: Number(v), name: STATUS_NAMES[key] };
 });
 
-// CRLReason decode-and-whitelist leaf.
 var CRL_REASON = schema.decode(function (n, ctx) {
   var v = asn1.read.enumerated(n);
   var key = v.toString();
@@ -102,44 +78,20 @@ var CRL_REASON = schema.decode(function (n, ctx) {
   return CRL_REASONS[key];
 });
 
-// A certs [0] SEQUENCE OF Certificate element. Unlike the CMS CertificateChoices
-// (a tagged CHOICE), an OCSP certs element is a plain Certificate, a universal
-// SEQUENCE (RFC 5280 sec. 4.1), so assert that shape before surfacing its raw DER, and
-// reject a non-SEQUENCE element instead of reporting arbitrary bytes as a cert.
 function certificateBytes() {
   return pkix.rawNonEmptySequence(NS, { code: "ocsp/bad-certs", message: "each certs element must be a non-empty Certificate SEQUENCE (RFC 6960 sec. 4.1.1/sec. 4.2.1)" });
 }
 
-// requestorName [1] EXPLICIT GeneralName (RFC 6960 sec. 4.1.1), validated and surfaced raw
-// via the shared pkix.generalName primitive (RFC 5280 sec. 4.2.1.6), so a malformed
-// GeneralName fails closed and the OCSP + TSP parsers cannot drift on this grammar.
 var GENERAL_NAME_RAW = pkix.generalName(NS, { code: "ocsp/bad-requestor-name" });
 
-// An OCSP signature BIT STRING is a byte string handed to a cryptographic verifier,
-// so it MUST be octet-aligned (0 unused bits); a non-octet-aligned signature is
-// malformed. Shared by the request Signature and the BasicOCSPResponse.
 function _rawSignature(field) {
   var sig = field.value;
   if (sig.unusedBits !== 0) throw NS.E("ocsp/bad-signature", "an OCSP signature BIT STRING must be octet-aligned (0 unused bits)");
   return sig.bytes;
 }
 
-// certs [0] EXPLICIT SEQUENCE OF Certificate, each element raw. Shared by the
-// request Signature and the BasicOCSPResponse.
-// The certs list is capped: the delegated-responder authorization loop verifies
-// each candidate before the response signature is checked, so an unbounded list in
-// a relayed / stapled response would drive unbounded pre-auth signature verifies.
 var CERTS = schema.seqOf(certificateBytes(), { assert: "sequence", code: "ocsp/bad-certs", what: "certs", max: constants.LIMITS.OCSP_MAX_CERTS, maxCode: "ocsp/too-many-certs" });
 
-// Validate the OCSP protocol extension values in a decoded extension list,
-// applied to every extension surface (request / single-request / response /
-// single-response) so a hostile placement cannot dodge the syntax rule. The
-// nonce is the one extension whose value the module names: Nonce ::= OCTET
-// STRING (SIZE(1..128)) (RFC 9654 sec. 2.1, updating RFC 6960 sec. 4.4.1; the 128
-// upper bound is the RFC 9654 responder rule; RFC 8954's was 32). The decoded
-// nonce bytes are surfaced on the extension as `nonce` alongside the raw value;
-// other extension values stay opaque (an unknown extension is representable,
-// not a fault).
 function _validateOcspExtensions(list) {
   if (!list) return list;
   for (var i = 0; i < list.length; i++) {
@@ -159,11 +111,7 @@ function _validateOcspExtensions(list) {
   return list;
 }
 
-// ---- CertID (shared request + response) ------------------------------
 
-// CertID ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET
-// STRING, issuerKeyHash OCTET STRING, serialNumber CertificateSerialNumber }
-// (RFC 6960 sec. 4.1.1). The two hashes are surfaced raw for the caller to verify.
 var CERT_ID = schema.seq([
   schema.field("hashAlgorithm", ALGORITHM_IDENTIFIER),
   schema.field("issuerNameHash", schema.octetString()),
@@ -182,11 +130,7 @@ var CERT_ID = schema.seq([
   },
 });
 
-// ---- response tree ---------------------------------------------------
 
-// RevokedInfo ::= SEQUENCE { revocationTime GeneralizedTime, revocationReason [0]
-// EXPLICIT CRLReason OPTIONAL } (RFC 6960 sec. 4.2.1). Walked on the [1] IMPLICIT node,
-// so assert:"constructed" (the context tag replaced the universal SEQUENCE tag).
 var REVOKED_INFO = schema.seq([
   schema.field("revocationTime", GENERALIZED_TIME),
   schema.trailing([
@@ -202,9 +146,6 @@ var REVOKED_INFO = schema.seq([
   },
 });
 
-// CertStatus ::= CHOICE { good [0] IMPLICIT NULL, revoked [1] IMPLICIT RevokedInfo,
-// unknown [2] IMPLICIT NULL } (RFC 6960 sec. 4.2.1). good/unknown are primitive empty
-// context nodes; revoked is a constructed context [1] whose body is RevokedInfo.
 var CERT_STATUS = schema.choice([
   { when: { tagClass: "context", tagNumber: 0 }, schema: schema.implicitNull(0) },
   { when: { tagClass: "context", tagNumber: 1 }, schema: REVOKED_INFO },
@@ -219,11 +160,6 @@ function _shapeCertStatus(field) {
   return { type: "revoked", revocationTime: ri.revocationTime, revocationReason: ri.revocationReason };
 }
 
-// SingleResponse ::= SEQUENCE { certID, certStatus, thisUpdate GeneralizedTime,
-// nextUpdate [0] EXPLICIT GeneralizedTime OPTIONAL, singleExtensions [1] EXPLICIT
-// Extensions OPTIONAL } (RFC 6960 sec. 4.2.1). certStatus is consumed positionally
-// (before thisUpdate), so its context [0] good arm cannot be confused with the
-// trailing nextUpdate [0].
 var SINGLE_RESPONSE = schema.seq([
   schema.field("certID", CERT_ID),
   schema.field("certStatus", CERT_STATUS),
@@ -245,9 +181,6 @@ var SINGLE_RESPONSE = schema.seq([
   },
 });
 
-// ResponderID ::= CHOICE { byName [1] Name, byKey [2] KeyHash } (RFC 6960 sec. 4.2.1),
-// both EXPLICIT (the module is EXPLICIT TAGS). byKey is an EXPLICIT-wrapped universal
-// OCTET STRING (0xA2 04 ...) and not an IMPLICIT primitive [2].
 var RESPONDER_ID = schema.choice([
   { when: { tagClass: "context", tagNumber: 1 }, schema: schema.explicit(1, NAME, { code: "ocsp/bad-responder-id" }) },
   { when: { tagClass: "context", tagNumber: 2 }, schema: schema.explicit(2, schema.octetString(), { code: "ocsp/bad-responder-id" }) },
@@ -255,16 +188,11 @@ var RESPONDER_ID = schema.choice([
 
 function _shapeResponderID(field) {
   if (field.node.tagNumber === 1) return { byName: field.value.result };
-  // RFC 6960 sec. 4.2.1 -- KeyHash is the SHA-1 hash of the responder's public key, so a
-  // conformant byKey ResponderID is exactly 20 octets; reject any other length.
   var keyHash = field.value;
   if (keyHash.length !== 20) throw NS.E("ocsp/bad-responder-id", "ResponderID byKey (KeyHash) must be a 20-byte SHA-1 hash (RFC 6960 sec. 4.2.1)");
   return { byKey: keyHash };
 }
 
-// ResponseData ::= SEQUENCE { version [0] EXPLICIT DEFAULT v1, responderID,
-// producedAt GeneralizedTime, responses SEQUENCE OF SingleResponse,
-// responseExtensions [1] EXPLICIT Extensions OPTIONAL } (RFC 6960 sec. 4.2.1).
 var RESPONSE_DATA = schema.seq([
   schema.optional("version", VERSION, { tag: 0, explicit: true, default: 1, emptyCode: "ocsp/bad-version" }),
   schema.field("responderID", RESPONDER_ID),
@@ -286,10 +214,6 @@ var RESPONSE_DATA = schema.seq([
   },
 });
 
-// BasicOCSPResponse ::= SEQUENCE { tbsResponseData ResponseData, signatureAlgorithm
-// AlgorithmIdentifier, signature BIT STRING, certs [0] EXPLICIT SEQUENCE OF
-// Certificate OPTIONAL } (RFC 6960 sec. 4.2.1). tbsResponseData.node.bytes is the exact
-// signed region (no CMS-style re-tag divergence, the clean case).
 var BASIC_OCSP_RESPONSE = schema.seq([
   schema.field("tbsResponseData", RESPONSE_DATA),
   schema.field("signatureAlgorithm", ALGORITHM_IDENTIFIER),
@@ -315,10 +239,6 @@ var BASIC_OCSP_RESPONSE = schema.seq([
   },
 });
 
-// ResponseBytes ::= SEQUENCE { responseType OBJECT IDENTIFIER, response OCTET STRING }
-// (RFC 6960 sec. 4.2.1). For id-pkix-ocsp-basic the response OCTET STRING content is a
-// fresh DER BasicOCSPResponse (decoded + walked); an unknown responseType is
-// recognized-and-deferred with a precise ocsp/unsupported-response-type.
 var RESPONSE_BYTES = schema.seq([
   schema.field("responseType", schema.oidLeaf()),
   schema.field("response", schema.octetString()),
@@ -340,12 +260,6 @@ var RESPONSE_BYTES = schema.seq([
   },
 });
 
-// OCSPResponse ::= SEQUENCE { responseStatus OCSPResponseStatus, responseBytes [0]
-// EXPLICIT ResponseBytes OPTIONAL } (RFC 6960 sec. 4.2.1). The status <-> responseBytes
-// biconditional (successful iff responseBytes present) is the OCSP-specific
-// cross-field guard. The top-level reject code predates the
-// `<prefix>/not-a-<structure>` convention (ocsp/not-a-request follows it) and
-// stays frozen on the public error-code surface.
 var OCSP_RESPONSE = schema.seq([
   schema.field("responseStatus", OCSP_RESPONSE_STATUS),
   schema.optional("responseBytes", RESPONSE_BYTES, { tag: 0, explicit: true, emptyCode: "ocsp/bad-ocsp-response" }),
@@ -354,8 +268,6 @@ var OCSP_RESPONSE = schema.seq([
   build: function (m) {
     var status = m.fields.responseStatus.value;
     var present = m.fields.responseBytes.present;
-    // RFC 6960 sec. 4.2.1 -- a successful response MUST carry responseBytes; any other
-    // status MUST NOT (there is nothing to convey but the status).
     if (status.code === 0 && !present) throw NS.E("ocsp/bad-response-bytes", "a successful OCSPResponse must carry responseBytes (RFC 6960 sec. 4.2.1)");
     if (status.code !== 0 && present) throw NS.E("ocsp/bad-response-bytes", "a non-successful OCSPResponse must not carry responseBytes (RFC 6960 sec. 4.2.1)");
     var rb = present ? m.fields.responseBytes.value.result : null;
@@ -367,10 +279,7 @@ var OCSP_RESPONSE = schema.seq([
   },
 });
 
-// ---- request tree ----------------------------------------------------
 
-// Request ::= SEQUENCE { reqCert CertID, singleRequestExtensions [0] EXPLICIT
-// Extensions OPTIONAL } (RFC 6960 sec. 4.1.1).
 var REQUEST = schema.seq([
   schema.field("reqCert", CERT_ID),
   schema.trailing([
@@ -386,8 +295,6 @@ var REQUEST = schema.seq([
   },
 });
 
-// Signature ::= SEQUENCE { signatureAlgorithm AlgorithmIdentifier, signature BIT
-// STRING, certs [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL } (RFC 6960 sec. 4.1.1).
 var SIGNATURE = schema.seq([
   schema.field("signatureAlgorithm", ALGORITHM_IDENTIFIER),
   schema.field("signature", schema.bitString()),
@@ -405,10 +312,6 @@ var SIGNATURE = schema.seq([
   },
 });
 
-// TBSRequest ::= SEQUENCE { version [0] EXPLICIT DEFAULT v1, requestorName [1]
-// EXPLICIT GeneralName OPTIONAL, requestList SEQUENCE OF Request, requestExtensions
-// [2] EXPLICIT Extensions OPTIONAL } (RFC 6960 sec. 4.1.1). requestorName is surfaced
-// raw (GeneralName is a wide CHOICE with no factory yet).
 var TBS_REQUEST = schema.seq([
   schema.optional("version", VERSION, { tag: 0, explicit: true, default: 1, emptyCode: "ocsp/bad-version" }),
   schema.optional("requestorName", GENERAL_NAME_RAW, { tag: 1, explicit: true, emptyCode: "ocsp/bad-requestor-name" }),
@@ -429,9 +332,6 @@ var TBS_REQUEST = schema.seq([
   },
 });
 
-// OCSPRequest ::= SEQUENCE { tbsRequest TBSRequest, optionalSignature [0] EXPLICIT
-// Signature OPTIONAL } (RFC 6960 sec. 4.1.1). tbsRequest.node.bytes is the raw signed
-// region for external verification.
 var OCSP_REQUEST = schema.seq([
   schema.field("tbsRequest", TBS_REQUEST),
   schema.optional("optionalSignature", SIGNATURE, { tag: 0, explicit: true, emptyCode: "ocsp/not-a-request" }),
@@ -440,9 +340,6 @@ var OCSP_REQUEST = schema.seq([
   build: function (m) {
     var tbs = m.fields.tbsRequest.value.result;
     var optionalSignature = m.fields.optionalSignature.present ? m.fields.optionalSignature.value.result : null;
-    // RFC 6960 sec. 4.1.2 -- if the request is signed, the requestor SHALL specify its
-    // name in requestorName (the identity the signature binds to). A signed request
-    // without it is internally inconsistent; reject fail-closed.
     if (optionalSignature && tbs.requestorName === null) {
       throw NS.E("ocsp/missing-requestor-name", "a signed OCSPRequest must specify requestorName (RFC 6960 sec. 4.1.2)");
     }
@@ -522,11 +419,6 @@ var parseRequest = pkix.makeParser({ pemLabel: "OCSP REQUEST", PemError: PemErro
  *   res.responseStatus.name;                       // -> "successful"
  *   res.basicResponse.responses[0].certStatus.type; // -> "good" | "revoked" | "unknown"
  */
-// The result records the input it was derived from. A verdict verb reads the
-// signature, the algorithm that verifies it and the bytes it covers off this object as
-// three separate properties, and re-derives all three from the recorded input rather
-// than trusting the object it was handed -- so an object rebuilt or edited after
-// parsing cannot make the three describe different responses.
 var parseResponse = pkix.makeRecordingParser({ pemLabel: "OCSP RESPONSE", PemError: PemError, ErrorClass: OcspError, prefix: "ocsp", what: "OCSP response", topSchema: OCSP_RESPONSE, ns: NS }, "ocspResponse");
 
 /**
@@ -583,11 +475,6 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "OCSP RES
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "OCSP RESPONSE", PemError); }
 
-// An OCSPResponse root is the only registered structure that leads with an
-// ENUMERATED child (a SEQUENCE of 1-2: responseStatus + an optional context [0]
-// responseBytes). Every other root leads with a SEQUENCE (x509/crl/csr/ocsp-request),
-// an OBJECT IDENTIFIER (cms), or an INTEGER (pkcs8), so the detector is
-// unconditionally exclusive.
 function matchesResponse(root) {
   var T = asn1.TAGS;
   var k = pkix.rootSequenceChildren(root, 1, 2);
@@ -597,10 +484,6 @@ function matchesResponse(root) {
   return true;
 }
 
-// An OCSPRequest root is a SEQUENCE of 1-2 whose first child is the tbsRequest
-// SEQUENCE (optionally followed by a context [0] EXPLICIT signature). It leads with
-// a SEQUENCE like x509/crl/csr, but those require EXACTLY 3 children (the
-// signed-envelope trio), while an OCSPRequest is 1-2 -- so it is excluded by arity.
 function matchesRequest(root) {
   var T = asn1.TAGS;
   var k = pkix.rootSequenceChildren(root, 1, 2);

package/lib/schema-pkcs12.js

@@ -53,27 +53,22 @@ var PemError = frameworkError.PemError;
 var NS = pkix.makeNS("pkcs12", Pkcs12Error, oid);
 var TAGS = asn1.TAGS;
 
-// Content types (RFC 5652 sec. 4 / RFC 7292 sec. 4.1).
 var OID_DATA = oid.byName("data");
 var OID_SIGNED_DATA = oid.byName("signedData");
 var OID_ENVELOPED_DATA = oid.byName("envelopedData");
 var OID_ENCRYPTED_DATA = oid.byName("encryptedData");
-// Bag types (RFC 7292 sec. 4.2).
 var OID_KEY_BAG = oid.byName("keyBag");
 var OID_SHROUDED_KEY_BAG = oid.byName("pkcs8ShroudedKeyBag");
 var OID_CERT_BAG = oid.byName("certBag");
 var OID_CRL_BAG = oid.byName("crlBag");
 var OID_SECRET_BAG = oid.byName("secretBag");
 var OID_SAFE_CONTENTS_BAG = oid.byName("safeContentsBag");
-// CertBag / CRLBag discriminators (sec. 4.2.3-sec. 4.2.4).
 var OID_X509_CERTIFICATE = oid.byName("x509Certificate");
 var OID_SDSI_CERTIFICATE = oid.byName("sdsiCertificate");
 var OID_X509_CRL = oid.byName("x509CRL");
-// Bag attributes (sec. 4.2) + the RFC 9579 MacData arm.
 var OID_FRIENDLY_NAME = oid.byName("friendlyName");
 var OID_LOCAL_KEY_ID = oid.byName("localKeyId");
 var OID_PBMAC1 = oid.byName("pbmac1");
-// DigestInfo ::= SEQUENCE { digestAlgorithm AlgorithmIdentifier, digest OCTET STRING }.
 var DIGEST_INFO = schema.seq([
   schema.field("digestAlgorithm", pkix.algorithmIdentifier(NS)),
   schema.field("digest", schema.octetString()),
@@ -84,14 +79,8 @@ var DIGEST_INFO = schema.seq([
   },
 });
 
-// PBKDF2-params + PBMAC1-params (RFC 8018 sec. 5.2 / App. A.5, RFC 9579 sec. 4) constrained to the PBMAC1
-// profile -- keyLength MUST be present, the prf DEFAULT is enforced non-canonical. Shared with CMP PBMAC1
-// protection verification, so the reader lives once in schema-pkix (ns-parameterized) instead of a second
-// copy per format; composed here with the pkcs12 namespace so it emits pkcs12/bad-mac-data.
 var PBMAC1_PARAMS = pkix.pbmac1Params(NS);
 
-// MacData ::= SEQUENCE { mac DigestInfo, macSalt OCTET STRING,
-//                        iterations INTEGER DEFAULT 1 }.
 var MAC_DATA = schema.seq([
   schema.field("mac", DIGEST_INFO),
   schema.field("macSalt", schema.octetString()),
@@ -99,8 +88,6 @@ var MAC_DATA = schema.seq([
 ], {
   assert: "sequence", code: "pkcs12/bad-mac-data", what: "MacData",
   build: function (m, ctx) {
-    // X.690 sec. 11.5 -- a DEFAULT-valued component must be omitted from a DER
-    // encoding, so an explicitly-encoded iterations = 1 is non-canonical.
     var it = m.fields.iterations;
     var iterations = 1;
     if (it.present) {
@@ -111,8 +98,6 @@ var MAC_DATA = schema.seq([
     var di = m.fields.mac.value.result;
     var pbmac1 = null;
     if (di.digestAlgorithm.oid === OID_PBMAC1) {
-      // RFC 9579 sec. 4 -- the PBMAC1 algorithm identifier MUST carry PBMAC1-params
-      // (the KDF and MAC scheme a verifier needs live there, not in MacData).
       if (di.digestAlgorithm.parameters === null) {
         throw ctx.E("pkcs12/bad-mac-data", "a PBMAC1 MacData must carry PBMAC1-params (RFC 9579 sec. 4)");
       }
@@ -132,10 +117,6 @@ var MAC_DATA = schema.seq([
   },
 });
 
-// CertBag ::= SEQUENCE { certId OID, certValue [0] EXPLICIT ANY } (sec. 4.2.3):
-// x509Certificate wraps the DER certificate in an OCTET STRING; sdsiCertificate
-// is an IA5String. Both arms of the closed set are accepted; the value is
-// surfaced raw (byte-exact), never re-encoded or recursively parsed.
 var CERT_BAG = schema.seq([
   schema.field("certId", schema.oidLeaf()),
   schema.field("certValue", schema.explicit(0, schema.any(), { code: "pkcs12/bad-bag-value", what: "certValue" })),
@@ -157,7 +138,6 @@ var CERT_BAG = schema.seq([
   },
 });
 
-// CRLBag ::= SEQUENCE { crlId OID, crlValue [0] EXPLICIT ANY } (sec. 4.2.4).
 var CRL_BAG = schema.seq([
   schema.field("crlId", schema.oidLeaf()),
   schema.field("crlValue", schema.explicit(0, schema.any(), { code: "pkcs12/bad-bag-value", what: "crlValue" })),
@@ -172,9 +152,6 @@ var CRL_BAG = schema.seq([
   },
 });
 
-// SecretBag ::= SEQUENCE { secretTypeId OID, secretValue [0] EXPLICIT ANY }
-// (sec. 4.2.5). SecretTypes is an open set, so the type is surfaced by OID with
-// the value raw -- an unrecognized secret is representable, not a fault.
 var SECRET_BAG = schema.seq([
   schema.field("secretTypeId", schema.oidLeaf()),
   schema.field("secretValue", schema.explicit(0, schema.any(), { code: "pkcs12/bad-bag-value", what: "secretValue" })),
@@ -186,11 +163,6 @@ var SECRET_BAG = schema.seq([
   },
 });
 
-// SafeBag ::= SEQUENCE { bagId OID, bagValue [0] EXPLICIT ANY DEFINED BY bagId,
-//                        bagAttributes SET OF PKCS12Attribute OPTIONAL } (sec. 4.2).
-// The build surfaces the structural record (bagId + the inner value node +
-// decoded attributes); the bagId dispatch happens in _buildBag, where the
-// per-parse recursion state lives.
 var SAFE_BAG = schema.seq([
   schema.field("bagId", schema.oidLeaf()),
   schema.field("bagValue", schema.explicit(0, schema.any(), { code: "pkcs12/bad-bag-value", what: "bagValue" })),
@@ -210,16 +182,12 @@ var SAFE_BAG = schema.seq([
       for (var i = 0; i < items.length; i++) {
         var a = items[i].value.result;
         attributes.push(a);
-        // friendlyName / localKeyId are SINGLE VALUE TRUE (PKCS#9 / RFC 2985):
-        // exactly one value, at most one instance of each attribute.
         if (a.type === OID_FRIENDLY_NAME) {
           if (seen[a.type] || a.values.length !== 1) throw ctx.E("pkcs12/bad-friendly-name", "friendlyName carries exactly one BMPString value (PKCS#9 SINGLE VALUE)");
           friendlyName = _bmpValue(a.values[0], ctx);
         }
         if (a.type === OID_LOCAL_KEY_ID) {
           if (seen[a.type] || a.values.length !== 1) throw ctx.E("pkcs12/bad-local-key-id", "localKeyId carries exactly one OCTET STRING value (PKCS#9 SINGLE VALUE)");
-          // The value bytes are a raw wire slice out of a store whose content
-          // is normatively BER, so the re-decode follows the same BER rules.
           localKeyId = _octetContent(asn1.decode(a.values[0], { ber: true }), ctx, "a localKeyId value", "pkcs12/bad-local-key-id");
         }
         seen[a.type] = true;
@@ -235,15 +203,11 @@ var SAFE_BAG = schema.seq([
   },
 });
 
-// SafeContents ::= SEQUENCE OF SafeBag (sec. 4.2). Strictly a SEQUENCE: a SET OF
-// here is a known producer divergence and rejects.
 var SAFE_CONTENTS = schema.seqOf(SAFE_BAG, {
   code: "pkcs12/bad-safe-contents", what: "SafeContents",
   max: C.LIMITS.PKCS12_MAX_ELEMENTS, maxCode: "pkcs12/too-many-elements",
 });
 
-// AuthenticatedSafe ::= SEQUENCE OF ContentInfo (sec. 4.1), each element parsed
-// structurally here and dispatched by contentType in _dispatchSafes.
 var AS_ELEMENT = schema.seq([
   schema.field("contentType", schema.oidLeaf()),
   schema.field("content", schema.explicit(0, schema.any(), { code: "pkcs12/bad-safe-contentinfo", what: "safe ContentInfo content" })),
@@ -258,8 +222,6 @@ var AUTHENTICATED_SAFE = schema.seqOf(AS_ELEMENT, {
   max: C.LIMITS.PKCS12_MAX_ELEMENTS, maxCode: "pkcs12/too-many-elements",
 });
 
-// The authSafe ContentInfo (sec. 4): contentType is data (password integrity) or
-// signedData (public-key integrity) and nothing else.
 var AUTH_SAFE = schema.seq([
   schema.field("contentType", schema.oidLeaf()),
   schema.field("content", schema.explicit(0, schema.any(), { code: "pkcs12/bad-authsafe", what: "authSafe content" })),
@@ -270,8 +232,6 @@ var AUTH_SAFE = schema.seq([
   },
 });
 
-// PFX ::= SEQUENCE { version INTEGER {v3(3)}, authSafe ContentInfo,
-//                    macData MacData OPTIONAL } (sec. 4).
 var PFX = schema.seq([
   schema.field("version", pkix.versionReader(NS, { "3": 3 })),
   schema.field("authSafe", AUTH_SAFE),
@@ -283,18 +243,9 @@ var PFX = schema.seq([
     var authSafe = m.fields.authSafe.value.result;
     var macPresent = m.fields.macData.present;
     var mac = macPresent ? m.fields.macData.value.result : null;
-    // Every re-decode below shares one budget, so nesting chained across
-    // OCTET-STRING (and delegation) boundaries cannot restart the caps.
     var state = { budget: { remaining: C.LIMITS.PKCS12_MAX_REDECODES }, bagDepth: 0 };
 
     if (authSafe.contentType === OID_DATA) {
-      // sec. 5.1 step 5B -- the MAC covers the value octets of the id-data OCTET
-      // STRING (the AuthenticatedSafe encoding), excluding the TLV header.
-      // MacData itself is OPTIONAL in the PFX syntax: a store without it
-      // (OpenSSL `pkcs12 -export -nomac`) carries no integrity protection at
-      // all, which is a policy concern for the caller. It is surfaced as
-      // integrityMode "none", never rejected by a parser whose job is to
-      // surface integrity inputs and not to verify them.
       var macedBytes = _octetContent(authSafe.innerNode, ctx, "an id-data authSafe content", "pkcs12/bad-authsafe");
       var dispatched = _dispatchSafes(_walkAuthenticatedSafe(macedBytes, state, ctx), state, ctx);
       return {
@@ -303,7 +254,6 @@ var PFX = schema.seq([
       };
     }
     if (authSafe.contentType === OID_SIGNED_DATA) {
-      // sec. 4 integrity coherence: public-key integrity has no MacData.
       if (macPresent) throw ctx.E("pkcs12/bad-integrity-mode", "an id-signedData authSafe (public-key integrity) must omit macData (RFC 7292 sec. 4)");
       var signed = cms.walkSignedData(authSafe.innerNode);
       if (signed.encapContentInfo.eContentType !== OID_DATA) {
@@ -312,8 +262,6 @@ var PFX = schema.seq([
       if (signed.encapContentInfo.eContent === null) {
         throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must carry attached eContent (RFC 7292 sec. 4.1)");
       }
-      // A signer-less SignedData carries no integrity at all, the one thing
-      // public-key-integrity mode exists to provide.
       if (signed.signerInfos.length < 1) {
         throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must carry at least one SignerInfo (RFC 7292 sec. 4)");
       }
@@ -328,8 +276,6 @@ var PFX = schema.seq([
   },
 });
 
-// The value octets of a universal OCTET STRING node (a BER constructed string
-// arrives already reassembled to primitive content by the codec's ber mode).
 function _octetContent(node, ctx, what, code) {
   if (!(node && node.tagClass === "universal" && node.tagNumber === TAGS.OCTET_STRING && node.content)) {
     throw ctx.E(code || "pkcs12/bad-bag-value", what + " must be an OCTET STRING");
@@ -337,11 +283,6 @@ function _octetContent(node, ctx, what, code) {
   return node.content;
 }
 
-// RFC 7292 sec. 4.1 -- a privacy-mode safe wraps a SafeContents, so the encrypted
-// content's declared type must be id-data whichever CMS privacy structure
-// carries it, and the ciphertext must be attached: CMS permits a detached
-// EncryptedContentInfo, but here the ciphertext is the safe's contents, and a
-// safe without it holds nothing a passphrase could ever recover.
 function _privacySafe(content, ctx) {
   if (content.encryptedContentInfo.contentType !== OID_DATA) {
     throw ctx.E("pkcs12/bad-safe-contentinfo-type",
@@ -354,8 +295,6 @@ function _privacySafe(content, ctx) {
   return content;
 }
 
-// A PKCS#9 SINGLE-VALUE BMPString attribute value (friendlyName), decoded
-// UTF-16BE by the codec's string reader (even length + surrogate rules there).
 function _bmpValue(bytes, ctx) {
   var node = asn1.decode(bytes, { ber: true });
   if (!(node.tagClass === "universal" && node.tagNumber === TAGS.BMP_STRING)) {
@@ -364,7 +303,6 @@ function _bmpValue(bytes, ctx) {
   return asn1.read.string(node);
 }
 
-// Re-decode the AuthenticatedSafe blob (BER content region, budgeted).
 function _walkAuthenticatedSafe(bytes, state, ctx) {
   return schema.embeddedDer(AUTHENTICATED_SAFE, bytes, ctx, {
     code: "pkcs12/bad-der", what: "the AuthenticatedSafe", ber: true,
@@ -372,16 +310,8 @@ function _walkAuthenticatedSafe(bytes, state, ctx) {
   });
 }
 
-// Dispatch each AuthenticatedSafe element by contentType (sec. 4.1): id-data
-// carries plaintext SafeContents (re-decoded here); the two privacy modes are
-// full CMS structures validated by the CMS module on the already-decoded node
-// -- ciphertext stays opaque inside the CMS surface.
-// @internal -- re-parse a DECRYPTED privacy-safe's plaintext (a SafeContents ::= SEQUENCE OF SafeBag) through
-// the same strict SAFE_CONTENTS walk and bag dispatch the plaintext path uses, so a decrypted blob shares every
-// PKCS12_MAX_* cap and produces the identical bag records. Consumed by pki.pkcs12.open for an encrypted safe.
+// @internal
 function walkSafeContents(der) {
-  // PKCS#12 content regions are normatively BER (RFC 7292 sec. 4.1), so a decrypted SafeContents may use an
-  // indefinite-length SEQUENCE, exactly as the plaintext-safe path (_dispatchSafes) decodes it with ber:true.
   var walked = schema.walk(SAFE_CONTENTS, asn1.decode(der, { ber: true }), NS);
   var state = { budget: { remaining: C.LIMITS.PKCS12_MAX_REDECODES }, bagDepth: 0 };
   var bags = [];
@@ -405,9 +335,6 @@ function _dispatchSafes(asMatch, state, ctx) {
     } else if (el.contentType === OID_ENCRYPTED_DATA) {
       encryptedSafes.push({ type: "encryptedData", content: _privacySafe(cms.walkEncryptedData(el.innerNode), ctx) });
     } else if (el.contentType === OID_ENVELOPED_DATA) {
-      // Surface the raw EnvelopedData DER alongside the walked structure: public-key privacy opens by driving
-      // pki.cms.decrypt, which re-parses strict DER (it takes no pre-parsed object), so pkcs12.open reconstructs
-      // the ContentInfo around these bytes and never re-serializes the recipientInfos the integrity check trusts.
       encryptedSafes.push({ type: "envelopedData", content: _privacySafe(cms.walkEnvelopedData(el.innerNode), ctx), envelopedDataDer: el.innerNode.bytes });
     } else {
       throw ctx.E("pkcs12/bad-safe-contentinfo-type", "an AuthenticatedSafe element must be id-data, id-encryptedData, or id-envelopedData (RFC 7292 sec. 4.1), got " +
@@ -417,21 +344,15 @@ function _dispatchSafes(asMatch, state, ctx) {
   return { safeBags: safeBags, encryptedSafes: encryptedSafes };
 }
 
-// bagId dispatch (sec. 4.2, Appendix D). The bag-type set is closed: an
-// unrecognized bagId rejects. Key material delegates to the exported PKCS#8
-// parsers; cert / CRL / secret values are surfaced raw.
 function _buildBag(rec, state, ctx) {
   var bag = {
     type: null, bagId: rec.bagId,
     friendlyName: rec.friendlyName, localKeyId: rec.localKeyId, attributes: rec.attributes,
   };
-  // Key bags are walked from the decoded node, since their wire bytes may carry
-  // BER shapes the strict pkcs8 parse entry refuses, and the node already
-  // exists (no re-decode).
   if (rec.bagId === OID_KEY_BAG) {
     bag.type = "keyBag";
     bag.key = pkcs8.walkPrivateKeyInfo(rec.valueNode);
-    bag.keyDer = rec.valueNode.bytes;   // the raw PrivateKeyInfo DER (pki.pkcs12.open surfaces it verbatim)
+    bag.keyDer = rec.valueNode.bytes;
     return bag;
   }
   if (rec.bagId === OID_SHROUDED_KEY_BAG) {
@@ -458,8 +379,6 @@ function _buildBag(rec, state, ctx) {
     return bag;
   }
   if (rec.bagId === OID_SAFE_CONTENTS_BAG) {
-    // sec. 4.2.6 recursion -- bounded independently of the codec depth cap so a
-    // chain across re-decode boundaries cannot restart it.
     if (state.bagDepth + 1 > C.LIMITS.PKCS12_MAX_BAG_DEPTH) {
       throw ctx.E("pkcs12/too-deep", "safeContentsBag nesting exceeds the depth cap " + C.LIMITS.PKCS12_MAX_BAG_DEPTH);
     }
@@ -523,11 +442,6 @@ function _buildBag(rec, state, ctx) {
  *   var store = pki.schema.pkcs12.parse(der);
  *   store.safeBags.map(function (b) { return b.type; });
  */
-// The result records the input it was derived from. pki.pkcs12.verifyMac and open read
-// the MACed byte range and the bags returned as verified off this object as two
-// separate properties, and re-derive both from the recorded input rather than trusting
-// the object -- so "verify this" and "return that" cannot come to name different
-// stores, whether by rebuilding the object or by editing it after parsing.
 var parse = pkix.makeRecordingParser({
   pemLabel: "PKCS12", PemError: PemError, ErrorClass: Pkcs12Error,
   prefix: "pkcs12", what: "PFX", topSchema: PFX, ns: NS, ber: true,
@@ -576,11 +490,6 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "PKCS12",
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "PKCS12", PemError); }
 
-// A PFX root leads with a universal INTEGER (version), colliding with the
-// PKCS#8 detector on the first child -- so the discriminators are children[1]
-// (a ContentInfo: SEQUENCE of exactly 2, OID first, [0] constructed second --
-// a shape a PrivateKeyInfo's AlgorithmIdentifier never presents) and
-// children[2] (a SEQUENCE MacData or absent, never PKCS#8's OCTET STRING).
 function matches(root) {
   var k = pkix.rootSequenceChildren(root, 2, 3);
   if (!k) return false;