@blamejs/pki 0.6.14 → 0.6.16

package/lib/schema-smime.js

@@ -55,23 +55,12 @@ var TAGS = asn1.TAGS;
 
 var ALGID = pkix.algorithmIdentifier(NS);
 
-// Registry constants -- never a dotted literal in a format module.
 var OID_SHA1 = oid.byName("sha1");
 var OID_SHA256 = oid.byName("sha256");
 var OID_SIGNING_CERTIFICATE = oid.byName("signingCertificate");
 var OID_SIGNING_CERTIFICATE_V2 = oid.byName("signingCertificateV2");
 var OID_SMIME_CAPABILITIES = oid.byName("smimeCapabilities");
 
-// IssuerSerial ::= SEQUENCE { issuer GeneralNames, serialNumber CertificateSerialNumber }
-// (RFC 5035 App A). A bare universal SEQUENCE of exactly two fields, distinct
-// from the RFC 5755 attribute-certificate IssuerSerial (three fields, reached
-// IMPLICIT-tagged), so declared per-format. `issuer` composes the shared
-// GeneralNames factory (every CHOICE arm validated + surfaced raw, SIZE 1..MAX)
-// and is surfaced unchanged here: the RFC 5035 sec. 5 directoryName narrowing applies
-// only to a non-attribute (public-key) certificate reference, and an ESSCertID
-// entry may reference an attribute certificate whose issuer is a full GeneralNames.
-// The first cert is known to be the signing public-key cert (RFC 5035 sec. 3), so the
-// directoryName rule is enforced in the SigningCertificate build and not here.
 var GENERAL_NAME_DIRECTORY = 4;
 var ISSUER_SERIAL = schema.seq([
   schema.field("issuer", pkix.generalNames(NS, { code: "smime/bad-general-names" })),
@@ -87,11 +76,6 @@ var ISSUER_SERIAL = schema.seq([
   },
 });
 
-// RFC 5035 sec. 5: the signing certificate (certs[0], the public-key cert that made
-// the signature per sec. 3) MUST identify its issuer as exactly one directoryName [4].
-// Additional certs[1..] may reference attribute certificates, whose issuer is a
-// GeneralNames -- left unconstrained (a verifier-tier profile concern). `fail`
-// throws the caller's code.
 function assertSignerIssuerIsDirectoryName(certs, fail) {
   if (!certs.length || !certs[0].issuerSerial) return;
   var names = certs[0].issuerSerial.issuer.names;
@@ -100,9 +84,6 @@ function assertSignerIssuerIsDirectoryName(certs, fail) {
   }
 }
 
-// PolicyInformation ::= SEQUENCE { policyIdentifier CertPolicyId,
-//   policyQualifiers SEQUENCE OF PolicyQualifierInfo OPTIONAL } (RFC 5280 sec. 4.2.1.4).
-// Decode the policy OID (+ registry name); surface policyQualifiers raw.
 var POLICY_INFORMATION = schema.seq([
   schema.field("policyIdentifier", schema.oidLeaf()),
   schema.optional("policyQualifiers", schema.any(), { whenUniversal: [TAGS.SEQUENCE] }),
@@ -111,9 +92,6 @@ var POLICY_INFORMATION = schema.seq([
   build: function (m, ctx) {
     var qualifiers = null;
     if (m.fields.policyQualifiers.present) {
-      // The qualifier body stays raw (per the ESS scope), but the RFC 5280
-      // sec. 4.2.1.4 structure is validated fail-closed by the shared assertion, the
-      // same PolicyInformation shape the certificatePolicies decoder enforces.
       var q = m.fields.policyQualifiers.node;
       pkix.assertPolicyQualifiers(q, function (msg, cause) { throw ctx.E("smime/bad-policy-information", msg, cause); });
       qualifiers = q.bytes;
@@ -125,17 +103,11 @@ var POLICY_INFORMATION = schema.seq([
     };
   },
 });
-// policies SEQUENCE OF PolicyInformation OPTIONAL -- order-preserving; the ASN.1
-// module carries no SIZE bound, so an explicitly present but empty list is legal.
 var POLICIES = schema.seqOf(POLICY_INFORMATION, {
   assert: "sequence", min: 0, code: "smime/bad-policies", what: "policies",
   build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
 });
 
-// ESSCertID ::= SEQUENCE { certHash Hash, issuerSerial IssuerSerial OPTIONAL }
-// (RFC 5035 sec. 5.4.2). Hash ::= OCTET STRING; for v1 it is the SHA-1 hash of the
-// whole certificate with no algorithm field, so the hash algorithm is synthesized
-// as the implied SHA-1 to make v1 shape-compatible with v2 for a verifier.
 var ESS_CERT_ID = schema.seq([
   schema.field("certHash", schema.octetString()),
   schema.optional("issuerSerial", ISSUER_SERIAL, { whenUniversal: [TAGS.SEQUENCE] }),
@@ -150,11 +122,6 @@ var ESS_CERT_ID = schema.seq([
   },
 });
 
-// ESSCertIDv2 ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier DEFAULT
-//   {algorithm id-sha256}, certHash Hash, issuerSerial IssuerSerial OPTIONAL }
-// (RFC 5035 sec. 5.4.1 / sec. 4). The mandatory certHash OCTET STRING pivots between the
-// two optional SEQUENCEs, so a leading SEQUENCE is hashAlgorithm and a leading
-// OCTET STRING means hashAlgorithm defaulted.
 var ESS_CERT_ID_V2 = schema.seq([
   schema.optional("hashAlgorithm", ALGID, { whenUniversal: [TAGS.SEQUENCE] }),
   schema.field("certHash", schema.octetString()),
@@ -165,12 +132,6 @@ var ESS_CERT_ID_V2 = schema.seq([
     var hashAlgorithm;
     if (m.fields.hashAlgorithm.present) {
       var alg = m.fields.hashAlgorithm.value.result;
-      // X.690 sec. 11.5: a DEFAULT value MUST be omitted in DER. The default is
-      // {algorithm id-sha256, parameters ABSENT}; an explicit encoding byte-equal
-      // to it is a non-canonical DEFAULT and is rejected fail-closed (the
-      // structured-value analogue of the primitive-DEFAULT rejection the toolkit
-      // already enforces). A present hashAlgorithm carrying a redundant NULL
-      // parameters is not byte-equal to the params-absent default and decodes.
       if (alg.oid === OID_SHA256 && alg.parameters === null) {
         throw ctx.E("smime/non-canonical-default",
           "ESSCertIDv2 hashAlgorithm equal to the DEFAULT {algorithm id-sha256} MUST be omitted (X.690 sec. 11.5)");
@@ -187,10 +148,6 @@ var ESS_CERT_ID_V2 = schema.seq([
   },
 });
 
-// SigningCertificate ::= SEQUENCE { certs SEQUENCE OF ESSCertID,
-//   policies SEQUENCE OF PolicyInformation OPTIONAL } (RFC 5035 sec. 5.4.2). certs is
-// order-preserving (RFC 5035 sec. 3 makes the first element the signing certificate)
-// and non-empty (an empty certs cannot name a signing cert).
 function signingCertificateSchema(essCertId, code, what) {
   return schema.seq([
     schema.field("certs", schema.seqOf(essCertId, { assert: "sequence", min: 1, code: "smime/bad-certs", what: "certs" })),
@@ -210,10 +167,6 @@ function signingCertificateSchema(essCertId, code, what) {
 var SIGNING_CERTIFICATE = signingCertificateSchema(ESS_CERT_ID, "smime/bad-signing-certificate", "SigningCertificate");
 var SIGNING_CERTIFICATE_V2 = signingCertificateSchema(ESS_CERT_ID_V2, "smime/bad-signing-certificate-v2", "SigningCertificateV2");
 
-// SMIMECapability ::= SEQUENCE { capabilityID OBJECT IDENTIFIER,
-//   parameters ANY DEFINED BY capabilityID OPTIONAL } (RFC 8551 sec. 2.5.2). Distinct
-// domain from AlgorithmIdentifier though isomorphic -- surfaced as capabilityID +
-// raw parameters (the ANY-DEFINED-BY interpretation is a negotiation concern).
 var SMIME_CAPABILITY = schema.seq([
   schema.field("capabilityID", schema.oidLeaf()),
   schema.optional("parameters", schema.any(), { whenAny: true }),
@@ -227,8 +180,6 @@ var SMIME_CAPABILITY = schema.seq([
     };
   },
 });
-// SMIMECapabilities ::= SEQUENCE OF SMIMECapability, ordered by preference
-// (RFC 8551 sec. 2.5.2), never sorted; an empty list is legal.
 var SMIME_CAPABILITIES = schema.seqOf(SMIME_CAPABILITY, {
   assert: "sequence", min: 0, code: "smime/bad-capabilities", what: "SMIMECapabilities",
   build: function (m) { return { capabilities: m.items.map(function (it) { return it.value.result; }) }; },
@@ -334,11 +285,6 @@ function decodeAttribute(attr) {
   if (!attr || typeof attr !== "object" || typeof attr.type !== "string" || !Array.isArray(attr.values)) {
     throw new SmimeError("smime/bad-input", "decodeAttribute expects a CMS attribute { type, values }");
   }
-  // Route on the attribute OID FIRST. The single-AttributeValue MUST (RFC 8551
-  // sec. 2.5.2) is specific to the ESS / SMIMECapabilities attributes, so it is
-  // enforced only inside the known-type branch; an unknown / custom attribute
-  // recognize-and-defers with its raw values intact regardless of value count
-  // (its own cardinality rules are not this decoder's to enforce).
   if (attr.type === OID_SIGNING_CERTIFICATE || attr.type === OID_SIGNING_CERTIFICATE_V2 || attr.type === OID_SMIME_CAPABILITIES) {
     if (attr.values.length !== 1) {
       throw new SmimeError("smime/multi-valued-attribute",

package/lib/schema-tsp.js

@@ -49,47 +49,28 @@ var NS = pkix.makeNS("tsp", TspError, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var EXTENSION = pkix.extension(NS);
 
-// TSTInfo.version is INTEGER { v1(1) }; the only legal value is 1.
 var VERSION = pkix.versionReader(NS, { "1": 1 });
 
-// id-ct-TSTInfo is the eContentType that identifies a timestamp token (RFC 3161
-// sec. 2.4.2); resolved from the registry, never a dotted literal.
 var OID_TST_INFO = oid.byName("tSTInfo");
 
-// The ESS certificate-identifier attributes: RFC 3161 sec. 2.4.2 requires the TSA
-// certificate identifier as a SigningCertificate signed attribute; RFC 5816
-// additionally permits SigningCertificateV2.
 var OID_SIGNING_CERT = oid.byName("signingCertificate");
 var OID_SIGNING_CERT_V2 = oid.byName("signingCertificateV2");
 
 var TAGS = asn1.TAGS;
 
-// PKIFailureInfo ::= BIT STRING NamedBitList (RFC 3161 sec. 2.4.2). bit 0 is the MSB of
-// the first content octet; a set bit outside the named set is surfaced by index.
 var FAILURE_BITS = {
   0: "badAlg", 2: "badRequest", 5: "badDataFormat", 14: "timeNotAvailable",
   15: "unacceptedPolicy", 16: "unacceptedExtension", 17: "addInfoNotAvailable", 25: "systemFailure",
 };
 
-// ---- shared leaves ---------------------------------------------------
 
-// GeneralizedTime-only leaf. RFC 3161 sec. 2.4.2 requires genTime to be GeneralizedTime,
-// never UTCTime; assert the tag before the (fractional-capable) codec read.
-// RFC 3161 genTime may carry sub-second precision (X.690 sec. 11.7 fractional profile).
 var GEN_TIME = pkix.generalizedTime(NS, { code: "tsp/bad-gentime", message: "genTime must be a GeneralizedTime (RFC 3161 sec. 2.4.2)", allowFractional: true });
 
-// tsa [0] EXPLICIT GeneralName (RFC 3161 sec. 2.4.2), validated and surfaced raw via the
-// shared pkix.generalName primitive (RFC 5280 sec. 4.2.1.6), which checks the chosen
-// alternative's form and content so a malformed GeneralName fails closed.
 var GENERAL_NAME_RAW = pkix.generalName(NS, { code: "tsp/bad-tsa" });
 
-// A PKIFreeText element MUST be a UTF8String (RFC 3161 sec. 2.4.2).
 var UTF8_TEXT = pkix.utf8Text(NS, { code: "tsp/bad-status-info", message: "PKIFreeText elements must be UTF8String" });
 
-// ---- MessageImprint --------------------------------------------------
 
-// MessageImprint ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, hashedMessage
-// OCTET STRING } (RFC 3161 sec. 2.4.1). hashedMessage is a digest, surfaced raw.
 var MESSAGE_IMPRINT = schema.seq([
   schema.field("hashAlgorithm", ALGORITHM_IDENTIFIER),
   schema.field("hashedMessage", schema.octetString()),
@@ -100,11 +81,7 @@ var MESSAGE_IMPRINT = schema.seq([
   },
 });
 
-// ---- Accuracy --------------------------------------------------------
 
-// Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] IMPLICIT INTEGER
-// (1..999) OPTIONAL, micros [1] IMPLICIT INTEGER (1..999) OPTIONAL } (RFC 3161
-// sec. 2.4.2). Every sub-field is optional; a missing one defaults to 0.
 var ACCURACY = schema.seq([
   schema.optional("seconds", schema.integerLeaf(), { whenUniversal: [TAGS.INTEGER] }),
   schema.trailing([
@@ -117,20 +94,13 @@ var ACCURACY = schema.seq([
     function sub(f) {
       if (!f.present) return 0;
       var v = f.value;
-      // millis / micros are constrained to 1..999 (RFC 3161 sec. 2.4.2); 0 is also
-      // excluded (and non-canonical for a positive count).
       if (v < 1n || v > 999n) throw NS.E("tsp/bad-accuracy", "Accuracy millis/micros must be in 1..999");
       return Number(v);
     }
-    // Accuracy is the +/- deviation added to and subtracted from genTime (RFC
-    // 3161 sec. 2.4.2), so a negative seconds inverts the time window a verifier
-    // computes -- the same semantically-impossible class as a 0 millis/micros.
     if (m.fields.seconds.present && m.fields.seconds.value < 0n) {
       throw NS.E("tsp/bad-accuracy", "Accuracy seconds must not be negative (RFC 3161 sec. 2.4.2)");
     }
     return {
-      // seconds is an unbounded INTEGER -- keep it lossless as a BigInt (millis /
-      // micros are constrained to 1..999, so Number is exact for those).
       seconds: m.fields.seconds.present ? m.fields.seconds.value : 0n,
       millis: sub(m.fields.millis),
       micros: sub(m.fields.micros),
@@ -138,12 +108,7 @@ var ACCURACY = schema.seq([
   },
 });
 
-// ---- TSTInfo ---------------------------------------------------------
 
-// TSTInfo ::= SEQUENCE { version, policy, messageImprint, serialNumber, genTime,
-// accuracy OPTIONAL, ordering DEFAULT FALSE, nonce OPTIONAL, tsa [0] EXPLICIT
-// GeneralName OPTIONAL, extensions [1] IMPLICIT Extensions OPTIONAL } (RFC 3161
-// sec. 2.4.2). The five mandatory fields come first; the optionals are consumed by tag.
 var TST_INFO = schema.seq([
   schema.field("version", VERSION),
   schema.field("policy", schema.oidLeaf()),
@@ -160,7 +125,6 @@ var TST_INFO = schema.seq([
 ], {
   assert: "sequence", code: "tsp/bad-tst-info", what: "TSTInfo",
   build: function (m, ctx) {
-    // ordering BOOLEAN DEFAULT FALSE -- an explicit FALSE must be omitted (DER).
     if (m.fields.ordering.present && m.fields.ordering.value === false) {
       throw NS.E("tsp/bad-ordering", "ordering is BOOLEAN DEFAULT FALSE -- an explicit FALSE must be omitted");
     }
@@ -174,11 +138,7 @@ var TST_INFO = schema.seq([
       serialNumber: m.fields.serialNumber.value,
       serialNumberHex: m.fields.serialNumber.node.content.toString("hex"),
       genTime: m.fields.genTime.value,
-      // genTime is surfaced as a millisecond-precision Date; genTimeFraction is the
-      // exact fractional-seconds digits (lossless for sub-millisecond precision), or
-      // null when genTime carries no fraction.
       genTimeFraction: (function () {
-        // /\.(\d+)Z$/ : the fractional-seconds digits before a trailing "Z" (the "." and "Z" excluded), or null.
         var s = m.fields.genTime.node.content.toString("latin1"), n = s.length;
         if (n < 3 || s.charAt(n - 1) !== "Z") return null;
         var dot = s.lastIndexOf(".");
@@ -197,10 +157,7 @@ var TST_INFO = schema.seq([
   },
 });
 
-// ---- PKIStatusInfo / TimeStampResp -----------------------------------
 
-// PKIStatusInfo ::= SEQUENCE { status PKIStatus (INTEGER), statusString PKIFreeText
-// OPTIONAL, failInfo PKIFailureInfo OPTIONAL } (RFC 3161 sec. 2.4.2, from RFC 4210).
 var PKI_STATUS_INFO = schema.seq([
   schema.field("status", schema.integerLeaf()),
   schema.optional("statusString", schema.seqOf(UTF8_TEXT, { assert: "sequence", min: 1, code: "tsp/bad-status-info", what: "statusString" }), { whenUniversal: [TAGS.SEQUENCE] }),
@@ -209,7 +166,6 @@ var PKI_STATUS_INFO = schema.seq([
   assert: "sequence", code: "tsp/bad-status-info", what: "PKIStatusInfo",
   build: function (m) {
     var status = m.fields.status.value;
-    // PKIStatus ::= INTEGER { granted(0) .. revocationNotification(5) }.
     if (status < 0n || status > 5n) throw NS.E("tsp/bad-status", "PKIStatus " + status + " is outside 0..5 (RFC 3161 sec. 2.4.2)");
     var failInfo = null;
     if (m.fields.failInfo.present) {
@@ -225,18 +181,10 @@ var PKI_STATUS_INFO = schema.seq([
   },
 });
 
-// X.690 sec. 11.2.2 -- a BIT STRING typed with a NamedBitList (PKIFailureInfo) MUST have
-// all trailing 0 bits removed under DER: no trailing all-zero content octet, and the
-// declared unusedBits must sit exactly below the lowest set bit of the last octet (so
-// the encoding is minimal). The empty value encodes as 0 content octets, 0 unusedBits.
 function _assertMinimalNamedBits(unusedBits, bytes) {
   schema.assertMinimalNamedBits(unusedBits, bytes, function (m) { throw NS.E("tsp/bad-failinfo", m); });
 }
 
-// Decode the set NamedBitList bits to their RFC 3161 names (bit 0 = MSB of byte 0).
-// A set bit outside the defined set is an unsupported PKIFailureInfo value, and a client
-// MUST error on a failInfo it does not understand (RFC 3161 sec. 2.4.2), so reject it
-// instead of surfacing an opaque "bitN".
 function _namedBits(bytes) {
   var out = [];
   for (var i = 0; i < bytes.length * 8; i++) {
@@ -249,11 +197,6 @@ function _namedBits(bytes) {
   return out;
 }
 
-// TimeStampResp ::= SEQUENCE { status PKIStatusInfo, timeStampToken TimeStampToken
-// OPTIONAL } (RFC 3161 sec. 2.4.2). There is NO version field. The token is a CMS
-// ContentInfo, decoded via cms.parse; the status-to-token coupling is load-bearing.
-// The top-level reject code predates the `<prefix>/not-a-<structure>` convention
-// and stays frozen on the public error-code surface.
 var TIME_STAMP_RESP = schema.seq([
   schema.field("status", PKI_STATUS_INFO),
   schema.optional("timeStampToken", schema.any(), { whenUniversal: [TAGS.SEQUENCE] }),
@@ -262,17 +205,10 @@ var TIME_STAMP_RESP = schema.seq([
   build: function (m) {
     var status = m.fields.status.value.result;
     var present = m.fields.timeStampToken.present;
-    // RFC 3161 sec. 2.4.2 -- granted / grantedWithMods carry a token; any other status
-    // (rejection / waiting / revocation*) MUST NOT.
     var granted = status.status === 0 || status.status === 1;
     if (granted && !present) throw NS.E("tsp/missing-token", "a granted TimeStampResp must carry a timeStampToken (RFC 3161 sec. 2.4.2)");
     if (!granted && present) throw NS.E("tsp/unexpected-token", "a non-granted TimeStampResp must not carry a timeStampToken (RFC 3161 sec. 2.4.2)");
-    // failInfo is the reason a request was rejected, so it is present only when the
-    // status is rejection(2), never on granted(0/1) nor on waiting / revocation* (3/4/5).
     if (status.status !== 2 && status.failInfo) throw NS.E("tsp/unexpected-failinfo", "failInfo is present only when the status is rejection(2) (RFC 3161 sec. 2.4.2)");
-    // A granted response's timeStampToken MUST be a well-formed TimeStampToken, so
-    // decode it (composing the CMS parser) instead of surfacing arbitrary SEQUENCE
-    // bytes as a token; a malformed token fails the response parse.
     return {
       status: status.status,
       statusString: status.statusString,
@@ -282,13 +218,7 @@ var TIME_STAMP_RESP = schema.seq([
   },
 });
 
-// ---- TimeStampReq ----------------------------------------------------
 
-// TimeStampReq ::= SEQUENCE { version INTEGER { v1(1) }, messageImprint MessageImprint,
-// reqPolicy TSAPolicyId OPTIONAL, nonce INTEGER OPTIONAL, certReq BOOLEAN DEFAULT FALSE,
-// extensions [0] IMPLICIT Extensions OPTIONAL } (RFC 3161 sec. 2.4.1). version + messageImprint
-// are mandatory; the three optionals are consumed by universal tag (OID / INTEGER / BOOLEAN),
-// then the [0] extensions. certReq DEFAULT FALSE follows the TSTInfo.ordering explicit-FALSE rule.
 var TIME_STAMP_REQ = schema.seq([
   schema.field("version", VERSION),
   schema.field("messageImprint", MESSAGE_IMPRINT),
@@ -301,7 +231,6 @@ var TIME_STAMP_REQ = schema.seq([
 ], {
   assert: "sequence", code: "tsp/bad-request", what: "TimeStampReq",
   build: function (m, ctx) {
-    // certReq BOOLEAN DEFAULT FALSE -- an explicit FALSE must be omitted under DER.
     if (m.fields.certReq.present && m.fields.certReq.value === false) {
       throw NS.E("tsp/bad-request", "certReq is BOOLEAN DEFAULT FALSE -- an explicit FALSE must be omitted (DER)");
     }
@@ -437,23 +366,13 @@ var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: Ts
  *   token.signerInfo.sid;    // -> the TSA signer identifier
  */
 function parseToken(input) {
-  // De-armor with TSP's label-agnostic PEM rules first (RFC 3161 has no standard
-  // label), THEN hand DER to the CMS parser -- otherwise cms.parse would reject any
-  // PEM block not labeled "CMS" before the TSP checks run.
   var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: TspError, prefix: "tsp" });
-  // Wrap the CMS decode so tsp.parse / parseToken keep their typed-TspError contract --
-  // a malformed token surfaces tsp/bad-token, not a bare cms/* error.
   var signed;
   try { signed = cms.parse(der); }
   catch (e) {
     if (e instanceof TspError) throw e;
     throw new TspError("tsp/bad-token", "the timeStampToken did not decode as a CMS SignedData: " + ((e && e.message) || String(e)), e);
   }
-  // cms.parse decodes every CMS content type; a TimeStampToken MUST be a
-  // SignedData (RFC 3161 sec. 2.4.2). Gate on the dispatched content type before
-  // any SignedData-only field access -- an AuthenticatedData / EnvelopedData
-  // whose eContentType happens to be id-ct-TSTInfo would otherwise reach a raw
-  // TypeError on the absent signerInfos.
   if (signed.contentTypeName !== "signedData") {
     throw new TspError("tsp/not-signed-data", "a TimeStampToken must be a CMS SignedData, got " + (signed.contentTypeName || signed.contentType));
   }
@@ -465,12 +384,6 @@ function parseToken(input) {
   if (signed.signerInfos.length !== 1) {
     throw new TspError("tsp/multi-signer", "a TimeStampToken must contain exactly one (TSA) signerInfo (RFC 3161 sec. 2.4.2)");
   }
-  // RFC 3161 sec. 2.4.2 / RFC 5816 -- the TSA certificate identifier MUST be present
-  // as a SigningCertificate (or SigningCertificateV2) signed attribute. Presence
-  // is a structural token property, same altitude as the single-signer rule; the
-  // hash-vs-certificate BINDING stays a verification-layer concern. signedAttrs
-  // is non-null here: the CMS parse already required it for a non-id-data
-  // eContentType (RFC 5652 sec. 5.3), and the eContentType is id-ct-TSTInfo.
   var signedAttrs = signed.signerInfos[0].signedAttrs || [];
   var hasSigningCert = false;
   for (var a = 0; a < signedAttrs.length; a++) {
@@ -485,9 +398,6 @@ function parseToken(input) {
     if (e instanceof TspError) throw e;
     throw new TspError("tsp/bad-der", "the encapsulated TSTInfo did not decode: " + ((e && e.message) || String(e)), e);
   }
-  // Surface the RAW eContent (the exact DER a verifier hashes for the CMS
-  // message-digest signed attribute) alongside the decoded TSTInfo -- a re-serialized
-  // tstInfo may not byte-match, so the raw bytes are the verification feed.
   return { tstInfo: tstInfo.result, eContent: encap.eContent, signerInfo: signed.signerInfos[0], certificates: signed.certificates };
 }
 
@@ -508,9 +418,7 @@ function parseToken(input) {
  *   var pemText = pki.schema.tsp.pemEncode(req, "TSP REQUEST");
  *   var der = pki.schema.tsp.pemDecode(pemText);
  */
-// Decode a raw GeneralName TLV (the tsa field and the ESS issuerSerial issuer are surfaced raw) into
-// { tagClass, tagNumber, value } -- for a directoryName [4] the value is a decoded Name { rdns },
-// so a verifier canonically compares it (guard.name.dnEqual) rather than by raw bytes. @internal.
+// @internal
 function decodeGeneralName(bytes) {
   return schema.embeddedDer(pkix.generalName(NS, { decodeValue: true, code: "tsp/bad-tsa" }), bytes, NS, { code: "tsp/bad-tsa", what: "GeneralName" });
 }
@@ -535,10 +443,6 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || null, Pem
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
 
-// A TimeStampResp root is a SEQUENCE of 1-2 whose first child is a PKIStatusInfo (a
-// SEQUENCE whose own first child is an INTEGER status). Disjoint from the OID-first
-// CMS ContentInfo, the INTEGER-first PKCS#8 key, and the exactly-3 signed-envelope
-// trio, so it detects unambiguously regardless of registry order.
 function matches(root) {
   var k = pkix.rootSequenceChildren(root, 1, 2);
   if (!k) return false;
@@ -551,9 +455,9 @@ function matches(root) {
 
 module.exports = {
   parse: parse,
-  parseResponse: parse,   // TimeStampResp parsing == parse; named for symmetry with parseRequest
+  parseResponse: parse,
   parseRequest: parseRequest,
-  decodeGeneralName: decodeGeneralName,   // @internal -- the verifier's tsa / issuerSerial DN decode
+  decodeGeneralName: decodeGeneralName,   // @internal
   parseTstInfo: parseTstInfo,
   parseToken: parseToken,
   pemDecode: pemDecode,

package/lib/schema-x509.js

@@ -39,7 +39,6 @@ var pkix = require("./schema-pkix");
 var CertificateError = frameworkError.CertificateError;
 var PemError = frameworkError.PemError;
 
-// ---- PEM -------------------------------------------------------------
 
 /**
  * @primitive  pki.schema.x509.pemDecode
@@ -83,22 +82,12 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? n
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
 
-// ---- helpers ---------------------------------------------------------
 
-// The x509 error namespace the schema engine walks under: prefix names the
-// error family and E constructs the typed CertificateError. The shared PKIX
-// sub-schemas (AlgorithmIdentifier, Name, Extension) live in lib/pkix-schema.js
-// as ns-parameterized factories so crl.js / cms.js reuse them while emitting
-// their own crl/*, cms/* codes; here they are instantiated under this NS.
 var NS = pkix.makeNS("x509", CertificateError, oid);
 
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
 
-// Validity ::= SEQUENCE { notBefore Time, notAfter Time } -- the outer tag is
-// asserted (a SET-tagged body is a different ASN.1 type, not a Validity).
-// pkix.time enforces the RFC 5280 sec. 4.1.2.5 encoding cutover on decode: a
-// validity date through 2049 must be UTCTime, GeneralizedTime is 2050 onward.
 var VALIDITY = schema.seq([
   schema.field("notBefore", pkix.time(NS)),
   schema.field("notAfter", pkix.time(NS)),
@@ -107,24 +96,12 @@ var VALIDITY = schema.seq([
   build: function (m) { return { notBefore: m.fields.notBefore.value, notAfter: m.fields.notAfter.value }; },
 });
 
-// SubjectPublicKeyInfo -- the shared pkix.spki factory under the x509 NS.
 var SPKI = pkix.spki(NS);
 
 var EXTENSIONS = pkix.extensions(NS);
 
-// Version ::= INTEGER { v1(0), v2(1), v3(2) }, [0] EXPLICIT DEFAULT v1. Read as a
-// BigInt so an out-of-range value can't coerce to a float; reject an explicitly-
-// encoded v1 (DER forbids encoding the DEFAULT).
-// version ::= INTEGER { v1(0), v2(1), v3(2) } inside a [0] EXPLICIT DEFAULT v1 --
-// DER forbids encoding the default, so 0 is rejected; 1->v2, 2->v3.
 var CERTIFICATE_VERSION = pkix.versionReader(NS, { "1": 2, "2": 3 });
 
-// TBSCertificate ::= SEQUENCE { version [0] EXPLICIT DEFAULT v1, serialNumber
-// INTEGER, signature AlgorithmIdentifier, issuer Name, validity Validity,
-// subject Name, subjectPublicKeyInfo SubjectPublicKeyInfo, issuerUniqueID [1]
-// IMPLICIT OPTIONAL, subjectUniqueID [2] IMPLICIT OPTIONAL, extensions [3]
-// EXPLICIT OPTIONAL }. The trailing fields are at-most-once, in increasing tag
-// order (the engine enforces it); only extensions are surfaced.
 var CERTIFICATE_TBS = schema.seq([
   schema.optional("version", CERTIFICATE_VERSION, { tag: 0, explicit: true, emptyCode: "x509/bad-version", default: 1 }),
   schema.field("serialNumber", schema.integerLeaf()),
@@ -134,49 +111,33 @@ var CERTIFICATE_TBS = schema.seq([
   schema.field("subject", NAME),
   schema.field("subjectPublicKeyInfo", SPKI),
   schema.trailing([
-    // RFC 5280 sec. 4.1.2.8 -- the unique identifiers are [n] IMPLICIT BIT
-    // STRING (context PRIMITIVE, unusedBits validated), never an EXPLICIT wrap.
     { tag: 1, name: "issuerUniqueID", schema: schema.implicitBitString(1) },
     { tag: 2, name: "subjectUniqueID", schema: schema.implicitBitString(2) },
     { tag: 3, name: "extensions", schema: EXTENSIONS, explicit: true, emptyCode: "x509/bad-extensions" },
   ], { minTag: 1, maxTag: 3, unexpectedCode: "x509/bad-tbs", orderCode: "x509/bad-tbs" }),
 ], { assert: "sequence", code: "x509/bad-tbs", what: "tbsCertificate" });
 
-// Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue
-// BIT STRING }. The build runs the RFC 5280 cross-field checks (sec. 4.1.1.2 sig-alg
-// agreement, sec. 4.1.2.4 non-empty issuer, sec. 4.1.2.9 extensions-only-in-v3) after the
-// structural walk, then assembles the public parse result. Raw-byte accessors
-// (serialNumberHex, tbsBytes, sig-alg agreement) read off the match-tree nodes.
-// Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue }
-// -- the shared SIGNED envelope. The certificate-specific invariants (outer==inner
-// signatureAlgorithm agreement, non-empty issuer, v3-only extensions) live in the
-// build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
 var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
   code: "x509/not-a-certificate", what: "Certificate",
   build: function (e, ctx) {
-    var tbs = e.tbsMatch; // CERTIFICATE_TBS seq-match (no build)
+    var tbs = e.tbsMatch;
 
-    // RFC 5280 sec. 4.1.1.2 -- outer signatureAlgorithm MUST equal tbsCertificate.signature.
     if (!e.outerSignatureAlgorithmBytes.equals(tbs.fields.signature.node.bytes)) {
       throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 sec. 4.1.1.2)");
     }
 
-    var version = tbs.fields.version.value; // 1 (default) | 2 | 3
+    var version = tbs.fields.version.value;
     var issuer = tbs.fields.issuer.value.result;
-    // RFC 5280 sec. 4.1.2.4 -- issuer MUST be non-empty (an empty subject is permitted, sec. 4.1.2.6).
     if (!issuer.rdns.length) {
       throw ctx.E("x509/bad-issuer", "issuer must be a non-empty distinguished name");
     }
 
     var extField = tbs.fields.extensions;
     var hasExtensions = !!(extField && extField.present);
-    // RFC 5280 sec. 4.1.2.9 -- extensions appear only in a v3 certificate.
     if (hasExtensions && version !== 3) {
       throw ctx.E("x509/bad-version", "extensions are only permitted in a v3 certificate");
     }
 
-    // RFC 5280 sec. 4.1.2.8 -- issuerUniqueID / subjectUniqueID MUST NOT
-    // appear when the version is 1; they require a v2 or v3 certificate.
     if ((tbs.fields.issuerUniqueID.present || tbs.fields.subjectUniqueID.present) && version < 2) {
       throw ctx.E("x509/bad-version", "issuerUniqueID/subjectUniqueID require a v2 or v3 certificate (RFC 5280 sec. 4.1.2.8)");
     }
@@ -199,7 +160,6 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
   },
 });
 
-// ---- parse -----------------------------------------------------------
 
 /**
  * @primitive  pki.schema.x509.parse
@@ -232,34 +192,15 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
  *   cert.validity.notAfter;          // Date
  *   cert.signatureAlgorithm.name;    // "Ed25519" (the algorithm the issuer signed with)
  */
-// The parser RECORDS the bytes it read, off the returned object, so a verb that computes a verdict
-// can re-derive from them instead of trusting the object it was handed.
-//
-// Completeness alone cannot carry a certificate's meaning. A certificate is one signature over one
-// byte range, but a parsed certificate presents that range (`tbsBytes`), the signature, and every
-// field the range encodes as separate properties. Keep a real CA certificate's signed bytes and
-// signature and replace only `subjectPublicKeyInfo`, and the signature check still passes over the
-// original range while the substituted key is what gets used to verify the next certificate in the
-// chain -- a forged chain out of a genuine certificate. Emptying `extensions` is the same move
-// against basicConstraints, keyUsage, name constraints, and the unknown-critical rule.
-//
-// Recording the source is what makes the object safe to accept: the verdict verbs parse it again
-// from these bytes, so anything done to the object afterwards is discarded rather than believed.
 var parse = pkix.makeRecordingParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS }, "certificate");
 
-// matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
-// share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the
-// tbs: a certificate has a Validity -- a SEQUENCE of exactly two Time values -- at
-// position [serial, signature, issuer, VALIDITY] after the optional [0] version.
-// A CSR's certificationRequestInfo has subjectPublicKeyInfo there (no Validity),
-// and a CRL leads with a bare Time; neither matches. Used by the orchestrator.
 function matches(root) {
   var TAGS = asn1.TAGS;
   var tbs = pkix.signedEnvelopeTbs(root);
   if (!tbs) return false;
   var kids = tbs.children;
-  var i = schema.isContext(kids[0], 0) ? 1 : 0; // optional [0] version
-  var validity = kids[i + 3]; // serial(i), signature(i+1), issuer(i+2), validity(i+3)
+  var i = schema.isContext(kids[0], 0) ? 1 : 0;
+  var validity = kids[i + 3];
   return schema.isUniversal(validity, TAGS.SEQUENCE) &&
     !!validity.children && validity.children.length === 2 &&
     validity.children.every(function (t) {