@blamejs/pki 0.6.13 → 0.6.15

package/lib/schema-all.js

@@ -46,200 +46,89 @@ var crmf = require("./schema-crmf");
 var cmp = require("./schema-cmp");
 var csrattrs = require("./schema-csrattrs");
 var attrcert = require("./schema-attrcert");
-// smime is a companion decoder for CMS signed-attribute values and not a top-level
-// format: it has no self-describing DER root (an ESS attribute value is a bare
-// SEQUENCE) so it is deliberately absent from FORMATS / the detect-and-route
-// `parse`; it is reached only by explicit OID dispatch on a CMS attribute.
 var smime = require("./schema-smime");
-// cmc is likewise a COMPANION decoder, for the same reason arrived at from the
-// other direction: a CMC message's outer DER root IS a CMS ContentInfo, which
-// `cms.matches` already claims below. A `cmc` FORMATS row would either shadow CMS
-// or be shadowed by it, and there is no structurally disjoint root to detect --
-// the discriminator is the encapsulated content type, one layer in. So it is
-// reached by explicit call, or by dispatching on
-// `pki.schema.cms.parse(der).encapContentInfo.eContentType`, and exports no
-// `matches` for nobody to call.
 var cmc = require("./schema-cmc");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
 var PemError = frameworkError.PemError;
 
-// The shared parse-entry opts for the orchestrator: label-agnostic PEM unwrap
-// (any block type routes), the schema/* error family. Detection needs a decoded
-// root, so the coerced bytes are what gets routed to the matched format. The
-// ber mode lets a BER-encoded PFX (the dominant real-world .p12 shape) decode
-// far enough to detect; a BER input matching a strict-DER-only format still
-// fails typed inside that format's own parse.
 var ENTRY = { pemLabel: null, PemError: PemError, ErrorClass: SchemaError, prefix: "schema", what: "input", ber: true };
 
-// REGISTRY -- each format is declarative data: a name, a `detect(root)` that
-// recognizes the decoded DER root as this format's outer structure, and the
-// member's own `parse`. Adding a format is a table entry, not new dispatch
-// logic. Order matters: the most specific detector wins, so a new member is
-// inserted ahead of any more-permissive one.
 var FORMATS = [
   {
-    // CMS ContentInfo (RFC 5652 sec. 3) -- the only registered root that leads with an
-    // OBJECT IDENTIFIER child (a SEQUENCE of exactly 2: contentType OID + a
-    // context [0] EXPLICIT content wrapper). Disjoint from the INTEGER-first pkcs8
-    // and the tbs-SEQUENCE-first signed-envelope trio, so it detects unambiguously.
-    // A non-SignedData content type routes here and gets a precise
-    // cms/unsupported-content-type instead of schema/unknown-format.
     name: "cms",
     module: cms,
     detect: cms.matches,
     parse: function (input) { return cms.parse(input); },
   },
   {
-    // TimeStampResp ::= SEQUENCE { status PKIStatusInfo, timeStampToken OPTIONAL } --
-    // a SEQUENCE of 1-2 whose first child is a PKIStatusInfo SEQUENCE whose own first
-    // child is an INTEGER status. This detector is a strict REFINEMENT of the
-    // ocsp-request one (both are SEQUENCE-of-1-2 with a SEQUENCE first child), so it
-    // MUST be checked first: a tokenless TimeStampResp (a bare PKIStatusInfo) would
-    // otherwise be shadowed by ocsp-request, whereas an OCSPRequest's tbsRequest never
-    // leads with a universal INTEGER and so never matches here (RFC 3161 sec. 2.4.2). A
-    // bare timestamp token is a CMS ContentInfo and routes to cms; a bare TSTInfo is
-    // an internal payload (reached via pki.schema.tsp.parseTstInfo).
     name: "tsp",
     module: tsp,
     detect: tsp.matches,
     parse: function (input) { return tsp.parse(input); },
   },
   {
-    // CertReqMessages ::= SEQUENCE SIZE(1..MAX) OF CertReqMsg (RFC 4211 sec. 3): a
-    // SEQUENCE whose first CertReqMsg's CertRequest leads with a universal INTEGER
-    // (certReqId) then a universal SEQUENCE (certTemplate). Leads with a SEQUENCE
-    // like the signed-envelope trio and the ocsp-request, but the INTEGER-then-
-    // SEQUENCE pair at that depth is disjoint from both. Registered AHEAD of
-    // ocsp-request: a single-message CertReqMessages is the only remaining overlap
-    // with the ocsp-request detector, and crmf's deeper probe is the more specific.
     name: "crmf",
     module: crmf,
     detect: crmf.matches,
     parse: function (input) { return crmf.parse(input); },
   },
   {
-    // PKIMessage ::= SEQUENCE { header PKIHeader, body PKIBody [0..26],
-    // protection [0]?, extraCerts [1]? } (RFC 9810 sec. 5.1): a SEQUENCE of 2-4
-    // whose first child is a >=3-child SEQUENCE leading with a bare INTEGER
-    // (pvno) and whose second child is context-constructed [0..26]. Order is
-    // load-bearing here: a 2-child PKIMessage whose body is ir [0] also
-    // satisfies the shallow ocsp-request probe below (k[0] SEQUENCE +
-    // k[1] context-[0]), while no OCSPRequest satisfies this detector (its
-    // tbsRequest never leads with a bare INTEGER), so cmp MUST sit ahead of
-    // ocsp-request for the pair to dispatch deterministically.
     name: "cmp",
     module: cmp,
     detect: cmp.matches,
     parse: function (input) { return cmp.parse(input); },
   },
   {
-    // CsrAttrs ::= SEQUENCE SIZE (0..MAX) OF AttrOrOID (RFC 8951 sec. 3.5): a
-    // SEQUENCE whose every child is a bare universal OID or an Attribute (a
-    // universal SEQUENCE of exactly 2: OID + SET). A 1-2-element all-Attribute
-    // CsrAttrs satisfies the permissive ocsp-request probe below (SEQUENCE +
-    // constructed first child), and the empty 30 00 is a CsrAttrs no other root
-    // accepts -- so csrattrs is the strict refinement and MUST sit ahead of
-    // ocsp-request, the same resolution tsp / cmp use. Disjoint from cmp (whose
-    // body child is context-[0..26], never a universal OID/Attribute).
     name: "csrattrs",
     module: csrattrs,
     detect: csrattrs.matches,
     parse: function (input) { return csrattrs.parse(input); },
   },
   {
-    // OCSPRequest ::= SEQUENCE { tbsRequest SEQUENCE, optionalSignature [0] EXPLICIT
-    // OPTIONAL }: a SEQUENCE of 1-2 whose first child is the tbsRequest SEQUENCE.
-    // Leads with a SEQUENCE like the signed-envelope trio, but is excluded by arity
-    // (the trio is exactly 3 children; an OCSPRequest is 1-2). Checked after tsp,
-    // whose detector is a strict refinement (RFC 6960 sec. 4.1.1), and after cmp,
-    // whose 2-child ir-body shape this probe would otherwise shadow.
     name: "ocsp-request",
     module: ocsp,
     detect: ocsp.matchesRequest,
     parse: function (input) { return ocsp.parseRequest(input); },
   },
   {
-    // OCSPResponse ::= SEQUENCE { responseStatus ENUMERATED, responseBytes [0]
-    // EXPLICIT OPTIONAL }: the only registered root that leads with an ENUMERATED
-    // child, so it is disjoint from every other format (RFC 6960 sec. 4.2.1).
     name: "ocsp-response",
     module: ocsp,
     detect: ocsp.matchesResponse,
     parse: function (input) { return ocsp.parseResponse(input); },
   },
   {
-    // PKCS#12 PFX ::= SEQUENCE { version INTEGER, authSafe ContentInfo, macData
-    // OPTIONAL }: INTEGER-first like pkcs8, so the discriminators are deeper.
-    // children[1] is a ContentInfo (SEQUENCE of exactly 2: OID + [0] constructed,
-    // a shape a PrivateKeyInfo's AlgorithmIdentifier never presents) and
-    // children[2] is a MacData SEQUENCE or absent (pkcs8 requires an OCTET STRING
-    // there). Shape-disjoint from pkcs8, and registered ahead of it as the more
-    // specific probe (RFC 7292 sec. 4). A BER-encoded PFX detects through the
-    // orchestrator's BER decode fallback and routes here.
     name: "pkcs12",
     module: pkcs12,
     detect: pkcs12.matches,
     parse: function (input) { return pkcs12.parse(input); },
   },
   {
-    // PKCS#8 PrivateKeyInfo / OneAsymmetricKey: a SEQUENCE whose first child is an
-    // INTEGER (version) and third an OCTET STRING (privateKey); disjoint from the
-    // signed-envelope trio. (EncryptedPrivateKeyInfo is deliberately not
-    // auto-routed: its SEQUENCE{SEQUENCE, OCTET STRING} shape is ambiguous, since a
-    // PKCS#1 DigestInfo is identical, so structural detection cannot classify it
-    // without a validated encryption-algorithm discriminator, which arrives with
-    // the PBES layer. It is reached explicitly via pki.schema.pkcs8.parseEncrypted.)
     name: "pkcs8",
     module: pkcs8,
     detect: pkcs8.matches,
     parse: function (input) { return pkcs8.parse(input); },
   },
   {
-    // CertificationRequest ::= SEQUENCE { certificationRequestInfo,
-    // signatureAlgorithm, signature }: the same outer 3-element shape,
-    // distinguished by a CertificationRequestInfo of exactly four children
-    // ending in the IMPLICIT [0] attributes element. Checked first because that
-    // detector is the most specific and mutually exclusive with the others.
     name: "csr",
     module: csr,
     detect: csr.matches,
     parse: function (input) { return csr.parse(input); },
   },
   {
-    // AttributeCertificate ::= SEQUENCE { acinfo, signatureAlgorithm, signatureValue }
-    // -- the signed-envelope trio, recognized by an acinfo that LEADS WITH a bare
-    // INTEGER version and carries a 2-GeneralizedTime attrCertValidityPeriod at
-    // children[5] (RFC 5755, section 4.1). Order-independent versus crl / x509 / csr:
-    // a v2 acinfo puts the AlgorithmIdentifier at the position where their probes
-    // require a bare Time / a 2-Time Validity / a 4-child CRI, and none of their tbs
-    // shapes carry the 2-GeneralizedTime marker at children[5].
     name: "attrcert",
     module: attrcert,
     detect: attrcert.matches,
     parse: function (input) { return attrcert.parse(input); },
   },
   {
-    // AttributeCertificateV1 (X.509-1997, RFC 5652, section 10.2) -- the obsolete
-    // predecessor whose acInfo LEADS WITH the subject CHOICE (context [0]/[1]).
-    // Recognized and deferred with a precise attrcert/legacy-v1-not-supported rather
-    // than routed to a wrong format. ORDER IS LOAD-BEARING against x509: a [0]-subject
-    // v1 AC ALSO satisfies x509.matches (the [0] child reads as the certificate's
-    // EXPLICIT version marker, putting the 2-GeneralizedTime attrCertValidityPeriod at
-    // the Validity probe offset), so this entry MUST sit ahead of x509 for first-match
-    // dispatch to defer it here. children[1] == SEQUENCE keeps a v3 certificate (whose
-    // [0] version is followed by an INTEGER serialNumber) from matching in the other
-    // direction.
     name: "attrcert-v1",
     module: attrcert,
     detect: attrcert.matchesV1,
     parse: function (input) { return attrcert.parseV1(input); },
   },
   {
-    // CertificateList ::= SEQUENCE { tbsCertList, signatureAlgorithm,
-    // signatureValue }: the same outer shape as a certificate, distinguished
-    // by its tbsCertList (a bare Time at the certificate's Validity position).
     name: "crl",
     module: crl,
     detect: crl.matches,
@@ -248,9 +137,6 @@ var FORMATS = [
   {
     name: "x509",
     module: x509,
-    // Certificate, identified by a Validity (SEQUENCE of two Times) inside the
-    // tbs, so a CSR or other 3-element signed envelope is not misclassified as a
-    // certificate (it falls through to schema/unknown-format).
     detect: x509.matches,
     parse: function (input) { return x509.parse(input); },
   },
@@ -293,9 +179,6 @@ function all() { return FORMATS.map(function (f) { return f.name; }); }
  *   var parsed = pki.schema.parse(der);  // cert -> the pki.schema.x509 shape
  */
 function parse(input) {
-  // Coerce + decode via the shared parse-entry, then route the COERCED DER (a
-  // PEM string/Buffer is already unwrapped, so the matched format parses DER
-  // directly and never re-treats the armor as DER).
   var der = pkix.coerceToDer(input, ENTRY);
   var root = pkix.decodeRoot(der, ENTRY);
   for (var i = 0; i < FORMATS.length; i++) {
@@ -336,14 +219,9 @@ function detectFormat(input) {
   return null;
 }
 
-// Curated public surface: each format exposes only its operator primitives. The
-// `matches` detector is internal dispatch infrastructure (used by FORMATS above),
-// not an operator API, so it is NOT re-exported here.
 module.exports = {
   engine: engine,
   x509: { parse: x509.parse, pemDecode: x509.pemDecode, pemEncode: x509.pemEncode },
-  // C509 is CBOR, not DER: an explicit-call surface only, NOT added to FORMATS / the detect-and-route
-  // parse() below (which detect DER shapes). No pemDecode/pemEncode -- C509 is binary CBOR.
   c509: { parse: c509.parse, encode: c509.encode },
   crl:  { parse: crl.parse,  pemDecode: crl.pemDecode, pemEncode: crl.pemEncode },
   csr:  { parse: csr.parse,  pemDecode: csr.pemDecode, pemEncode: csr.pemEncode },

package/lib/schema-attrcert.js

@@ -40,8 +40,6 @@ var pkix = require("./schema-pkix");
 var oid = require("./oid");
 var guard = require("./guard-all");
 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 object-digest types resolve.
 var _hasOwn = intrinsic.hasOwn;
 var frameworkError = require("./framework-error");
 
@@ -55,20 +53,11 @@ var TAGS = asn1.TAGS;
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var EXTENSIONS = pkix.extensions(NS);
 
-// AttCertVersion ::= INTEGER { v2(1) }, a bare mandatory INTEGER (not the x509
-// [0] EXPLICIT DEFAULT shape). The only legal value is v2, surfaced as 2.
 var VERSION = pkix.versionReader(NS, { "1": 2 });
 
-// ---- shared leaves ---------------------------------------------------
 
-// AttCertValidityPeriod times are GeneralizedTime (RFC 5755 sec. 4.2.6) -- a UTCTime is
-// rejected. Non-fractional YYYYMMDDHHMMSSZ is enforced by the codec.
 var GENERALIZED_TIME = pkix.generalizedTime(NS, { code: "attrcert/bad-time", message: "AttCertValidityPeriod times must be GeneralizedTime (RFC 5755 sec. 4.2.6)" });
 
-// digestedObjectType ::= ENUMERATED { publicKey(0), publicKeyCert(1),
-// otherObjectTypes(2) } (RFC 5755 sec. 4.1). An undefined value is rejected; a
-// non-ENUMERATED tag fails at the codec (asn1/*).
-// objectDigestInfo digested-object-type names -- single source pki.C.NAMES.OBJECT_DIGEST_TYPE.
 var ODT_NAMES = constants.NAMES.OBJECT_DIGEST_TYPE;
 var DIGESTED_OBJECT_TYPE = schema.decode(function (n, ctx) {
   var v = asn1.read.enumerated(n);
@@ -76,22 +65,13 @@ var DIGESTED_OBJECT_TYPE = schema.decode(function (n, ctx) {
   if (!_hasOwn(ODT_NAMES, k)) {
     throw ctx.E("attrcert/bad-digested-object-type", "digestedObjectType " + k + " is not a defined value (RFC 5755 sec. 4.1)");
   }
-  // RFC 5755 sec. 7.3 -- a conformant AC MUST NOT use otherObjectTypes(2); the digested
-  // object is limited to a public key or a public-key certificate, so reject it
-  // fail-closed instead of parsing a digest whose object type is unidentifiable.
   if (k === "2") {
     throw ctx.E("attrcert/bad-digested-object-type", "otherObjectTypes(2) MUST NOT be used (RFC 5755 sec. 7.3)");
   }
   return { code: Number(v), name: ODT_NAMES[k] };
 });
 
-// ---- IssuerSerial / ObjectDigestInfo ---------------------------------
 
-// IssuerSerial ::= SEQUENCE { issuer GeneralNames, serial CertificateSerialNumber,
-// issuerUID UniqueIdentifier OPTIONAL } (RFC 5755 sec. 4.1). Reached as an IMPLICIT
-// [n] node (Holder [0] / V2Form [0]) whose tag replaces the SEQUENCE tag, so the
-// shape assertion is "constructed" (the tag is pinned by the enclosing trailing);
-// a context [n] PRIMITIVE node has no children and fails closed here.
 var ISSUER_SERIAL = schema.seq([
   schema.field("issuer", pkix.generalNames(NS, { code: "attrcert/bad-issuer-serial" })),
   schema.field("serial", schema.integerLeaf()),
@@ -108,9 +88,6 @@ var ISSUER_SERIAL = schema.seq([
   },
 });
 
-// ObjectDigestInfo ::= SEQUENCE { digestedObjectType ENUMERATED, otherObjectTypeID
-// OBJECT IDENTIFIER OPTIONAL, digestAlgorithm AlgorithmIdentifier, objectDigest BIT
-// STRING } (RFC 5755 sec. 4.1). otherObjectTypeID is present only for otherObjectTypes(2).
 var OBJECT_DIGEST_INFO = schema.seq([
   schema.field("digestedObjectType", DIGESTED_OBJECT_TYPE),
   schema.optional("otherObjectTypeID", schema.oidLeaf(), { whenUniversal: [TAGS.OBJECT_IDENTIFIER] }),
@@ -120,15 +97,9 @@ var OBJECT_DIGEST_INFO = schema.seq([
   assert: "constructed", code: "attrcert/bad-object-digest-info", what: "ObjectDigestInfo",
   build: function (m, ctx) {
     var t = m.fields.digestedObjectType.value;
-    // otherObjectTypeID identifies a non-certificate object type, meaningful only with
-    // otherObjectTypes(2) -- which RFC 5755 sec. 7.3 forbids (rejected at the leaf above) --
-    // so a present otherObjectTypeID is never valid here and is rejected fail-closed.
     if (m.fields.otherObjectTypeID.present) {
       throw ctx.E("attrcert/bad-object-digest-info", "otherObjectTypeID is only valid with otherObjectTypes(2), which RFC 5755 sec. 7.3 forbids");
     }
-    // The objectDigest is a whole-octet digest over the identified object; a
-    // non-octet-aligned BIT STRING is malformed (RFC 5755 sec. 4.1) and has no
-    // in-tree verify layer to catch it later, so reject it at parse.
     guard.crypto.assertOctetAligned(m.fields.objectDigest.value, ctx.E, "attrcert/bad-object-digest-info", "objectDigest");
     return {
       digestedObjectType: t,
@@ -139,13 +110,7 @@ var OBJECT_DIGEST_INFO = schema.seq([
   },
 });
 
-// ---- Holder / AttCertIssuer / V2Form ---------------------------------
 
-// Holder ::= SEQUENCE { baseCertificateID [0] IMPLICIT IssuerSerial OPTIONAL,
-// entityName [1] IMPLICIT GeneralNames OPTIONAL, objectDigestInfo [2] IMPLICIT
-// ObjectDigestInfo OPTIONAL } (RFC 5755 sec. 4.1). All three are IMPLICIT + OPTIONAL;
-// the profile RECOMMENDS exactly one, but the parser surfaces all three (null when
-// absent) and does not enforce the cardinality.
 var HOLDER = schema.seq([
   schema.trailing([
     { tag: 0, name: "baseCertificateID", schema: ISSUER_SERIAL },
@@ -163,13 +128,6 @@ var HOLDER = schema.seq([
   },
 });
 
-// V2Form ::= SEQUENCE { issuerName GeneralNames OPTIONAL, baseCertificateID [0]
-// IMPLICIT IssuerSerial OPTIONAL, objectDigestInfo [1] IMPLICIT ObjectDigestInfo
-// OPTIONAL } (RFC 5755 sec. 4.1). Reached via the AttCertIssuer CHOICE on a context [0]
-// node, so the shape is "constructed". The build enforces the sec. 4.2.3 issuer
-// profile MUSTs: every field is syntactically OPTIONAL, but a conformant AC's
-// issuerName is present with one and only one GeneralName (a non-empty
-// directoryName) and baseCertificateID / objectDigestInfo are absent.
 var V2_FORM = schema.seq([
   schema.optional("issuerName", pkix.generalNames(NS, { code: "attrcert/bad-issuer-name" }), { whenUniversal: [TAGS.SEQUENCE] }),
   schema.trailing([
@@ -189,9 +147,6 @@ var V2_FORM = schema.seq([
     if (issuerName.names[0].tagNumber !== 4) {
       throw ctx.E("attrcert/bad-issuer-name", "the issuerName GeneralName must be a directoryName [4] (RFC 5755 sec. 4.2.3)");
     }
-    // directoryName [4] EXPLICIT wraps exactly one Name (the shared GeneralName
-    // grammar validated that); a zero-RDN Name is an empty DN identifying no
-    // issuer, which sec. 4.2.3 forbids.
     var dirName = asn1.decode(issuerName.names[0].bytes).children[0];
     if (!dirName.children || dirName.children.length < 1) {
       throw ctx.E("attrcert/bad-issuer-name", "the issuerName directoryName must be a non-empty distinguished name (RFC 5755 sec. 4.2.3)");
@@ -203,10 +158,6 @@ var V2_FORM = schema.seq([
   },
 });
 
-// AttCertIssuer ::= CHOICE { v1Form GeneralNames, v2Form [0] IMPLICIT V2Form } (RFC
-// 5755 sec. 4.1). A universal SEQUENCE is the (obsolete but structurally recognizable)
-// v1Form, which a conformant AC MUST NOT use (sec. 4.2.3). The arm is recognized and
-// rejected with a precise verdict instead of mis-dispatched; a context [0] is v2Form.
 var ATT_CERT_ISSUER = schema.choice([
   { when: { tagClass: "universal", tagNumber: TAGS.SEQUENCE },
     schema: schema.decode(function (n, ctx) {
@@ -215,10 +166,7 @@ var ATT_CERT_ISSUER = schema.choice([
   { when: { tagClass: "context", tagNumber: 0 }, schema: V2_FORM },
 ], { code: "attrcert/bad-issuer" });
 
-// ---- validity + attributes -------------------------------------------
 
-// AttCertValidityPeriod ::= SEQUENCE { notBeforeTime GeneralizedTime, notAfterTime
-// GeneralizedTime } (RFC 5755 sec. 4.2.6).
 var VALIDITY = schema.seq([
   schema.field("notBeforeTime", GENERALIZED_TIME),
   schema.field("notAfterTime", GENERALIZED_TIME),
@@ -227,20 +175,13 @@ var VALIDITY = schema.seq([
   build: function (m) { return { notBeforeTime: m.fields.notBeforeTime.value, notAfterTime: m.fields.notAfterTime.value }; },
 });
 
-// attributes ::= SEQUENCE OF Attribute (RFC 5755 sec. 4.2.7), which MUST be non-empty and
-// each AttributeType OID unique. Order-preserving (SEQUENCE OF, not SET OF).
 var ATTRIBUTES = schema.seqOf(pkix.attribute(NS), {
   assert: "sequence", min: 1, code: "attrcert/bad-attributes", what: "attributes",
   unique: function (it) { return it.value.result.type; }, dupCode: "attrcert/duplicate-attribute",
   build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
 });
 
-// ---- AttributeCertificateInfo / AttributeCertificate -----------------
 
-// AttributeCertificateInfo ::= SEQUENCE { version, holder, issuer, signature
-// AlgorithmIdentifier, serialNumber, attrCertValidityPeriod, attributes,
-// issuerUniqueID OPTIONAL, extensions OPTIONAL } (RFC 5755 sec. 4.1). The tbs body the
-// signed envelope wraps; the cross-field invariants live in the envelope build.
 var ACINFO = schema.seq([
   schema.field("version", VERSION),
   schema.field("holder", HOLDER),
@@ -253,24 +194,15 @@ var ACINFO = schema.seq([
   schema.optional("extensions", EXTENSIONS, { whenUniversal: [TAGS.SEQUENCE] }),
 ], { assert: "sequence", code: "attrcert/bad-acinfo", what: "AttributeCertificateInfo" });
 
-// AttributeCertificate ::= SEQUENCE { acinfo, signatureAlgorithm, signatureValue
-// BIT STRING }, the shared SIGNED envelope (RFC 5755 sec. 4.1). The AC-specific
-// invariants (sec. 4.2.4 sig-alg agreement, sec. 4.2.5 positive-and-<=20-octet serialNumber)
-// run in the build; the envelope owns the SEQUENCE-of-3 shape + signature extraction.
 var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
   code: "attrcert/not-an-attribute-certificate", what: "AttributeCertificate",
   build: function (e, ctx) {
     var acinfo = e.tbsMatch;
 
-    // RFC 5755 sec. 4.2.4 -- the outer signatureAlgorithm MUST equal acinfo.signature.
     if (!e.outerSignatureAlgorithmBytes.equals(acinfo.fields.signature.node.bytes)) {
       throw ctx.E("attrcert/bad-signature-algorithm", "signatureAlgorithm must match AttributeCertificateInfo.signature (RFC 5755 sec. 4.2.4)");
     }
 
-    // RFC 5755 sec. 4.2.5 -- serialNumber MUST be a positive INTEGER of at most 20 content
-    // octets. Positive excludes both a negative (DER sign bit set) and zero (a minimal
-    // INTEGER 0 is a single 0x00 octet, and the codec already rejected any non-minimal
-    // zero). Surface it lossless (BigInt) + as hex.
     var serialNode = acinfo.fields.serialNumber.node;
     var sc = serialNode.content;
     if (sc.length === 0 || (sc[0] & 0x80) !== 0 || (sc.length === 1 && sc[0] === 0)) {
@@ -280,22 +212,14 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
       throw ctx.E("attrcert/bad-serial-number", "serialNumber must not exceed 20 content octets (RFC 5755 sec. 4.2.5)");
     }
 
-    // AttCertIssuer is a CHOICE whose v1Form arm rejects at the leaf (sec. 4.2.3), so
-    // the surviving arm is always v2Form. The { form, v2Form, v1Form } shape is
-    // kept stable for consumers keying off `form`.
     var issuer = { form: "v2Form", v2Form: acinfo.fields.issuer.value.result, v1Form: null };
 
-    // RFC 5755 sec. 4.4 -- decode each attribute's value(s) additively: a recognized attribute type
-    // gains `decoded` (parallel to `values`); an unrecognized type falls back to { opaque, bytes } so
-    // the parse never fails on an unknown attribute, and a recognized-but-malformed value fails closed.
     var attributes = acinfo.fields.attributes.value.result;
     attributes.forEach(function (a) {
       var dec = _ATTR_VALUE_DECODERS[a.type];
       a.decoded = a.values.map(function (v) { return dec ? dec(v) : { opaque: true, bytes: v }; });
     });
 
-    // RFC 5755 sec. 4.3 -- decode each AC extension additively (extensions[i].decoded), same opaque
-    // fallback + fail-closed-on-malformed contract as the attributes above.
     var extField = acinfo.fields.extensions;
     var extensions = (extField && extField.present) ? extField.value.result : [];
     extensions.forEach(function (x) {
@@ -304,7 +228,7 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
     });
 
     return {
-      version:               acinfo.fields.version.value,     // 2
+      version:               acinfo.fields.version.value,
       holder:                acinfo.fields.holder.value.result,
       issuer:                issuer,
       signatureAlgorithm:    e.signatureAlgorithm,
@@ -321,7 +245,6 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
   },
 });
 
-// ---- parse -----------------------------------------------------------
 
 /**
  * @primitive  pki.schema.attrcert.parse
@@ -365,23 +288,13 @@ function _legacyV1Error() {
 
 function _parseAc(input) {
   var root = pkix.decodeRoot(pkix.coerceToDer(input, PARSE_OPTS), PARSE_OPTS);
-  // A well-formed legacy AttributeCertificateV1 gets the advertised, stable
-  // attrcert/legacy-v1-not-supported on the DIRECT path too -- not a low-level asn1/*
-  // tag error from attempting the v2 walk -- so a direct caller of this entry sees the
-  // same error family for the recognized-but-deferred form as the orchestrator does.
   if (matchesV1(root)) throw _legacyV1Error();
   return schema.walk(ATTRIBUTE_CERTIFICATE, root, NS).result;
 }
 
-// Recording, because pki.attrcert.verify reaches a verdict from this result: the signed byte range,
-// the holder the privileges attach to and the attributes themselves are separate properties here,
-// so the record is what binds them to one another.
 var parse = guard.parsed.recordingParser("attributeCertificate", _parseAc,
   AttrCertError, "attrcert/bad-input", "an attribute certificate");
 
-// The obsolete X.509-1997 AttributeCertificateV1 (RFC 5652 sec. 10.2) is recognized and
-// deferred: decode the envelope (so a malformed input still fails as bad DER), then
-// throw the precise diagnostic rather than routing it to a wrong format.
 function parseV1(input) {
   pkix.decodeRoot(pkix.coerceToDer(input, PARSE_OPTS), PARSE_OPTS);
   throw _legacyV1Error();
@@ -440,11 +353,6 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? n
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "ATTRIBUTE CERTIFICATE", PemError); }
 
-// matches(root): a v2 AttributeCertificate is the signed-envelope trio whose acinfo
-// LEADS WITH a bare universal INTEGER version (== v2 = 1, NOT the x509 [0] EXPLICIT
-// wrapper) and whose attrCertValidityPeriod at children[5] is a SEQUENCE of exactly
-// two GeneralizedTime (RFC 5755 sec. 4.2.6 forbids UTCTime) -- a marker no cert / CRL /
-// CSR presents at that position. Disjoint from matchesV1 by the children[0] tag class.
 function matches(root) {
   var acinfo = pkix.signedEnvelopeTbs(root);
   if (!acinfo) return false;
@@ -457,11 +365,6 @@ function matches(root) {
   return v.children.every(function (t) { return schema.isUniversal(t, TAGS.GENERALIZED_TIME); });
 }
 
-// matchesV1(root): the obsolete AttributeCertificateV1 -- its acInfo (version DEFAULT
-// v1 OMITTED) LEADS WITH the subject CHOICE (a context [0]/[1]), and its children[1]
-// is the issuer GeneralNames (a universal SEQUENCE). The children[1] == SEQUENCE test
-// keeps it disjoint from a v3 certificate (whose [0] EXPLICIT version is followed by
-// an INTEGER serialNumber), so v1-vs-cert dispatch is order-independent.
 function matchesV1(root) {
   var acinfo = pkix.signedEnvelopeTbs(root);
   if (!acinfo) return false;
@@ -471,12 +374,6 @@ function matchesV1(root) {
   return schema.isUniversal(k[1], TAGS.SEQUENCE);
 }
 
-// ---- RFC 5755 sec. 4.4 attribute-value decoders ----------------------
-// A per-attribute-type decoder table (mirroring pkix.certExtensionDecoders): each takes the raw
-// AttributeValue TLV Buffer and returns a structured value, throwing a typed attrcert/bad-* error on
-// any non-conformant shape. Composes pkix's shared imperative helpers + generalName/generalNames.
-// A single GeneralName decodes as the walk OBJECT itself (gn.tagNumber / gn.value); generalNames
-// (plural) returns { names:[...] } on .result.
 var _AV = pkix._decodeHelpers(NS);
 var _decodeTop = _AV.decodeTop, _seqChildren = _AV.seqChildren, _readInt = _AV.readInt, _Oav = _AV.O;
 var _GN = pkix.generalName(NS, { decodeValue: true, code: "attrcert/bad-general-name" });
@@ -492,19 +389,11 @@ function _oneGN(node, code) {
   return { tagNumber: gn.tagNumber, value: gn.value };
 }
 
-// readGeneralName(der) -> { tagNumber, value }, the shape every GeneralName in a parsed attribute
-// certificate is surfaced in.
-//
-// @internal -- exported so a verifier comparing a caller's GeneralName against one this module
-// decoded puts BOTH sides through this one decoder. A second decoder would be a second set of
-// per-form conventions, and a comparison whose two halves were produced by different rules is a
-// comparison of the rules rather than of the names.
+// @internal
 function readGeneralName(der, code) {
   return _oneGN(asn1.decode(der), code || "attrcert/bad-input");
 }
 
-// SvceAuthInfo ::= SEQUENCE { service GeneralName, ident GeneralName, authInfo OCTET STRING OPTIONAL }
-// -- authenticationInfo (sec. 4.4.1) allows authInfo; accessIdentity (sec. 4.4.2) MUST omit it.
 function _svceAuthInfo(authInfoAllowed, code) {
   return function (buf) {
     var kids = _seqChildren(buf, code, "SvceAuthInfo");
@@ -521,8 +410,6 @@ function _svceAuthInfo(authInfoAllowed, code) {
   };
 }
 
-// IetfAttrSyntax ::= SEQUENCE { policyAuthority [0] IMPLICIT GeneralNames OPTIONAL,
-//   values SEQUENCE OF CHOICE { octets OCTET STRING, oid OBJECT IDENTIFIER, string UTF8String } }
 function _ietfAttrSyntax(buf) {
   var C = "attrcert/bad-ietf-attr";
   var kids = _seqChildren(buf, C, "IetfAttrSyntax");
@@ -544,7 +431,6 @@ function _ietfAttrSyntax(buf) {
   return { policyAuthority: policyAuthority, values: values, homogeneous: Object.keys(kinds).length === 1 };
 }
 
-// RoleSyntax ::= SEQUENCE { roleAuthority [0] IMPLICIT GeneralNames OPTIONAL, roleName [1] EXPLICIT GeneralName }
 function _role(buf) {
   var C = "attrcert/bad-role";
   var kids = _seqChildren(buf, C, "RoleSyntax");
@@ -557,9 +443,6 @@ function _role(buf) {
   return { roleAuthority: roleAuthority, roleName: _oneGN(rn.children[0], C) };
 }
 
-// Clearance ::= SEQUENCE { policyId OBJECT IDENTIFIER, classList ClassList DEFAULT {unclassified},
-//   securityCategories SET OF SecurityCategory OPTIONAL }.
-// ClassList ::= BIT STRING { unmarked(0), unclassified(1), restricted(2), confidential(3), secret(4), topSecret(5) }.
 var _CLASSLIST_NAMES = ["unmarked", "unclassified", "restricted", "confidential", "secret", "topSecret"];
 function _decodeClassList(node, C) {
   var bs;
@@ -574,7 +457,6 @@ function _decodeClassList(node, C) {
   }
   return { names: names, flags: flags, reservedBits: reserved };
 }
-// SecurityCategory ::= SEQUENCE { type [0] IMPLICIT OBJECT IDENTIFIER, value [1] EXPLICIT ANY }.
 function _securityCategory(node, C) {
   if (!_isU(node, TAGS.SEQUENCE) || !node.children || node.children.length !== 2) throw NS.E(C, "a SecurityCategory must be a SEQUENCE of a type and a value");
   var typeNode = node.children[0], valueNode = node.children[1];
@@ -589,7 +471,7 @@ function _clearance(buf) {
   if (!kids.length || kids.length > 3) throw NS.E(C, "Clearance must be a SEQUENCE { policyId, classList?, securityCategories? }");
   if (!_isU(kids[0], TAGS.OBJECT_IDENTIFIER)) throw NS.E(C, "Clearance policyId must be an OBJECT IDENTIFIER");
   var policyId; try { policyId = asn1.read.oid(kids[0]); } catch (e) { throw NS.E(C, "Clearance policyId must be an OBJECT IDENTIFIER", e); }
-  var classList = { names: ["unclassified"], flags: { unclassified: true }, reservedBits: [] }, i = 1;   // DEFAULT {unclassified}
+  var classList = { names: ["unclassified"], flags: { unclassified: true }, reservedBits: [] }, i = 1;
   if (kids[i] && _isU(kids[i], TAGS.BIT_STRING)) {
     classList = _decodeClassList(kids[i], C);
     if (classList.names.length === 1 && classList.flags.unclassified && !classList.reservedBits.length) {
@@ -611,21 +493,13 @@ function _clearance(buf) {
 var _ATTR_VALUE_DECODERS = {};
 _ATTR_VALUE_DECODERS[_Oav("role")] = _role;
 _ATTR_VALUE_DECODERS[_Oav("clearance")] = _clearance;
-// RFC 5755 sec. 4.4.6 requires decoding the legacy RFC 3281 id-at-clearance too (the X.501
-// selected-attribute-types arc, an alias of "clearance" -- built from arcs, never a dotted literal).
 _ATTR_VALUE_DECODERS[oid.fromArcs([2, 5, 1, 5, 55])] = _clearance;
 _ATTR_VALUE_DECODERS[_Oav("authenticationInfo")] = _svceAuthInfo(true, "attrcert/bad-svce-auth-info");
 _ATTR_VALUE_DECODERS[_Oav("accessIdentity")] = _svceAuthInfo(false, "attrcert/bad-access-identity");
 _ATTR_VALUE_DECODERS[_Oav("chargingIdentity")] = _ietfAttrSyntax;
 _ATTR_VALUE_DECODERS[_Oav("group")] = _ietfAttrSyntax;
 
-// ---- RFC 5755 sec. 4.3 AC-extension decoders -------------------------
-// A per-extension-OID decoder table for the AC-specific extensions (kept in the AC domain, not the
-// shared cert-extension table, because Targets/TargetCert reuse the local IssuerSerial). Each takes
-// the raw extnValue content Buffer and returns a structured value, fail-closed with a typed error.
 
-// AuditIdentity ::= OCTET STRING (sec. 4.3.1) -- an opaque audit tag, unconstrained (no SIZE), so an
-// empty OCTET STRING (04 00) is valid; only the OCTET STRING type is enforced.
 function _acAuditIdentity(buf) {
   var C = "attrcert/bad-audit-identity";
   var n = _decodeTop(buf, C, "AuditIdentity");
@@ -633,8 +507,6 @@ function _acAuditIdentity(buf) {
   return Buffer.concat([asn1.read.octetString(n)]);
 }
 
-// NoRevAvail syntax is NULL (sec. 4.3.6: '0500'H is the DER encoding) -- the extnValue OCTET STRING
-// contains a DER NULL. An empty or any-other-shape value is malformed and fails closed.
 function _noRevAvail(buf) {
   var C = "attrcert/bad-no-rev-avail";
   var n = _decodeTop(buf, C, "NoRevAvail");
@@ -642,8 +514,6 @@ function _noRevAvail(buf) {
   return { noRevAvail: true };
 }
 
-// Target ::= CHOICE { targetName [0] GeneralName, targetGroup [1] GeneralName, targetCert [2] TargetCert }.
-// [0]/[1] wrap a GeneralName CHOICE (EXPLICIT); [2] is an IMPLICIT TargetCert SEQUENCE.
 function _acTargetCert(node, C) {
   if (!node.children || !node.children.length) throw NS.E(C, "a targetCert [2] must be a non-empty TargetCert SEQUENCE");
   var out = { kind: "targetCert", targetCertificate: null, targetName: null, certDigestInfo: null }, i = 0;
@@ -664,14 +534,10 @@ function _acTarget(node, C, allowTargetCert) {
   }
   throw NS.E(C, "a Target must be [0] targetName, [1] targetGroup, or [2] targetCert");
 }
-// Targets ::= SEQUENCE OF Target -- decode a Targets SEQUENCE node into an array of Target.
 function _acDecodeTargets(node, C, allowTargetCert) {
   if (!_isU(node, TAGS.SEQUENCE) || !node.children || !node.children.length) throw NS.E(C, "Targets must be a non-empty SEQUENCE OF Target");
   return node.children.map(function (t) { return _acTarget(t, C, allowTargetCert); });
 }
-// Both targetInformation (sec. 4.3.2) and ProxyInfo (sec. 7.4) are SEQUENCE OF Targets -- an outer
-// SEQUENCE whose every element is itself a Targets (SEQUENCE OF Target). A conforming issuer emits one
-// Targets, but users MUST accept several. proxying additionally forbids the targetCert [2] alternative.
 function _seqOfTargets(buf, C, allowTargetCert) {
   var kids = _seqChildren(buf, C, "SEQUENCE OF Targets");
   if (!kids.length) throw NS.E(C, "a SEQUENCE OF Targets must be non-empty");
@@ -680,9 +546,6 @@ function _seqOfTargets(buf, C, allowTargetCert) {
 function _targetInformation(buf) { return _seqOfTargets(buf, "attrcert/bad-targets", true); }
 function _acProxying(buf) { return _seqOfTargets(buf, "attrcert/bad-proxy-info", false); }
 
-// AAControls ::= SEQUENCE { pathLenConstraint INTEGER (0..MAX) OPTIONAL, permittedAttrs [0] AttrSpec
-//   OPTIONAL, excludedAttrs [1] AttrSpec OPTIONAL, permitUnSpecified BOOLEAN DEFAULT TRUE }.
-// AttrSpec ::= SEQUENCE OF OBJECT IDENTIFIER (the [0]/[1] IMPLICIT tag replaces the SEQUENCE tag).
 function _acAttrSpec(node, C) {
   if (!node.children) throw NS.E(C, "an AttrSpec must be a SEQUENCE OF OBJECT IDENTIFIER");
   return node.children.map(function (o) {
@@ -714,12 +577,7 @@ _AC_EXT_DECODERS[_Oav("noRevAvail")] = _noRevAvail;
 _AC_EXT_DECODERS[_Oav("aaControls")] = _aaControls;
 _AC_EXT_DECODERS[_Oav("acProxying")] = _acProxying;
 
-// @internal -- validate a pre-encoded AC attribute value / AC extension value against the SAME decoder
-// the parser runs, so the attrcert-sign escape hatches (a caller's pre-encoded Attribute / Extension DER)
-// cannot embed a structurally-malformed recognized value the strict parser would then reject. `type` /
-// `extnOid` are dotted-OID strings; `valueDer` / `extnValueDer` are the raw AttributeValue / extnValue
-// content Buffers (exactly what the parse loop passes). An unrecognized type returns null (stays opaque,
-// no validation); a recognized-but-malformed value throws the frozen attrcert/bad-* code.
+// @internal
 function validateAttributeValue(type, valueDer) {
   var dec = _ATTR_VALUE_DECODERS[type];
   return dec ? dec(valueDer) : null;