@blamejs/pki 0.5.7 → 0.5.9

package/lib/schema-all.js

@@ -11,13 +11,13 @@
  *
  * @intro
  *   The schema family: a declarative ASN.1 structure-schema engine and the
- *   per-format parsers built on it. Every format -- from X.509 certificates
- *   and CRLs through CMS, OCSP, timestamps, and PKCS#12 stores; `all()`
- *   enumerates the registered set -- is a member that COMPOSES the
+ *   per-format parsers built on it. Every format, from X.509 certificates
+ *   and CRLs through CMS, OCSP, timestamps, and PKCS#12 stores (`all()`
+ *   enumerates the registered set), is a member that composes the
  *   shared engine and the shared PKIX sub-schemas (AlgorithmIdentifier, Name,
- *   Extension), so a structural rule -- bounds-checked positional reads,
+ *   Extension), so a structural rule (bounds-checked positional reads,
  *   optional / tagged field ordering, SET-OF uniqueness, fail-closed typed
- *   errors -- is defined once in the engine and no format can reintroduce the
+ *   errors) is defined once in the engine and no format can reintroduce the
  *   class of bug it prevents.
  *
  *   `parse` is the orchestrator: hand it DER (or PEM) and it detects which
@@ -45,8 +45,8 @@ 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, NOT a top-level
-// format -- it has no self-describing DER root (an ESS attribute value is a bare
+// 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");
@@ -84,7 +84,7 @@ var FORMATS = [
     // 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 rather than schema/unknown-format.
+    // cms/unsupported-content-type instead of schema/unknown-format.
     name: "cms",
     module: cms,
     detect: cms.matches,
@@ -106,7 +106,7 @@ var FORMATS = [
     parse: function (input) { return tsp.parse(input); },
   },
   {
-    // CertReqMessages ::= SEQUENCE SIZE(1..MAX) OF CertReqMsg (RFC 4211 sec. 3) -- a
+    // 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-
@@ -120,13 +120,13 @@ var FORMATS = [
   },
   {
     // PKIMessage ::= SEQUENCE { header PKIHeader, body PKIBody [0..26],
-    // protection [0]?, extraCerts [1]? } (RFC 9810 sec. 5.1) -- a SEQUENCE of 2-4
+    // 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
+    // (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
+    // 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,
@@ -134,7 +134,7 @@ var FORMATS = [
     parse: function (input) { return cmp.parse(input); },
   },
   {
-    // CsrAttrs ::= SEQUENCE SIZE (0..MAX) OF AttrOrOID (RFC 8951 sec. 3.5) -- a
+    // 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 +
@@ -149,10 +149,10 @@ var FORMATS = [
   },
   {
     // OCSPRequest ::= SEQUENCE { tbsRequest SEQUENCE, optionalSignature [0] EXPLICIT
-    // OPTIONAL } -- a SEQUENCE of 1-2 whose first child is the tbsRequest SEQUENCE.
+    // 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,
+    // (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,
@@ -161,7 +161,7 @@ var FORMATS = [
   },
   {
     // OCSPResponse ::= SEQUENCE { responseStatus ENUMERATED, responseBytes [0]
-    // EXPLICIT OPTIONAL } -- the only registered root that leads with an ENUMERATED
+    // 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,
@@ -170,8 +170,8 @@ var FORMATS = [
   },
   {
     // 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 --
+    // 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
@@ -183,11 +183,11 @@ var FORMATS = [
     parse: function (input) { return pkcs12.parse(input); },
   },
   {
-    // PKCS#8 PrivateKeyInfo / OneAsymmetricKey -- SEQUENCE whose first child is an
+    // 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 -- a
-    // PKCS#1 DigestInfo is identical -- so structural detection cannot classify it
+    // 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",
@@ -197,8 +197,8 @@ var FORMATS = [
   },
   {
     // CertificationRequest ::= SEQUENCE { certificationRequestInfo,
-    // signatureAlgorithm, signature } -- the same outer 3-element shape,
-    // distinguished by a CertificationRequestInfo of EXACTLY four children
+    // 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",
@@ -237,7 +237,7 @@ var FORMATS = [
   },
   {
     // CertificateList ::= SEQUENCE { tbsCertList, signatureAlgorithm,
-    // signatureValue } -- the same outer shape as a certificate, distinguished
+    // 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,
@@ -247,8 +247,8 @@ var FORMATS = [
   {
     name: "x509",
     module: x509,
-    // Certificate -- identified by a Validity (SEQUENCE of two Times) inside the
-    // tbs, so a CSR / other 3-element signed envelope is NOT misclassified as a
+    // 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); },
@@ -312,11 +312,11 @@ function parse(input) {
  * @related     pki.schema.parse, pki.schema.all
  *
  * Detect which registered PKI format `input` (a DER `Buffer` or PEM string)
- * encodes and return its name -- one of `pki.schema.all()` -- WITHOUT parsing it,
+ * encodes and return its name, one of `pki.schema.all()`, without parsing it,
  * or `null` when the decoded bytes match no registered format. This is the
  * detection half of `pki.schema.parse`, running the same authoritative `FORMATS`
  * ordering, exposed for a caller (e.g. `pki.inspect.any`) that needs the format
- * name rather than the parsed result. Input that does not decode as DER throws the
+ * name instead of the parsed result. Input that does not decode as DER throws the
  * same coercion / decode error `parse` throws.
  *
  * @example

package/lib/schema-attrcert.js

@@ -29,7 +29,7 @@
  *
  * @card
  *   Parse DER / PEM RFC 5755 attribute certificates into holder, issuer,
- *   validity, attributes, and extensions -- validated GeneralNames, raw verifier
+ *   validity, attributes, and extensions: validated GeneralNames, raw verifier
  *   inputs, legacy v1 recognize-and-defer, fail-closed.
  */
 
@@ -51,7 +51,7 @@ 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
+// 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 });
 
@@ -62,7 +62,7 @@ var VERSION = pkix.versionReader(NS, { "1": 2 });
 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
+// 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;
@@ -74,7 +74,7 @@ var DIGESTED_OBJECT_TYPE = schema.decode(function (n, ctx) {
   }
   // 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 rather than parse a digest whose object type is unidentifiable.
+  // 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)");
   }
@@ -164,8 +164,8 @@ var HOLDER = schema.seq([
 // 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.
+// 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([
@@ -201,8 +201,8 @@ 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 rather than mis-dispatched; a context [0] is v2Form.
+// 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) {
@@ -223,7 +223,7 @@ 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) -- MUST be non-empty and
+// 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",
@@ -250,7 +250,7 @@ var ACINFO = schema.seq([
 ], { 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
+// 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, {
@@ -265,7 +265,7 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
 
     // 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 -- the codec already rejected any non-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;
@@ -386,7 +386,7 @@ function parseV1(input) {
  * @related    pki.schema.attrcert.parse
  *
  * Extract the DER bytes from a PEM block (default label
- * `ATTRIBUTE CERTIFICATE`, the OpenSSL armor -- the canonical-label default
+ * `ATTRIBUTE CERTIFICATE`, the OpenSSL armor and the canonical-label default
  * every sibling format applies). Pass a `label` to enforce a different block
  * type, or an explicit `null` to take the first block of any type. Throws
  * `PemError` on a missing / mismatched envelope or a non-base64 body.