@blamejs/pki 0.5.6 → 0.5.8

package/lib/schema-csr.js

@@ -25,7 +25,7 @@
  *   certificate/CRL guards.
  *
  * @card
- *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields -- subject DN,
+ *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields: subject DN,
  *   public key, requested attributes, signature, fail-closed.
  */
 
@@ -45,14 +45,14 @@ var NS = pkix.makeNS("csr", CsrError, oid);
 var NAME = pkix.name(NS);
 var SPKI = pkix.spki(NS);
 
-// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 sec. 4.1). A BARE
-// mandatory INTEGER whose ONLY legal value is 0 -- the inverse of the cert/CRL
+// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 sec. 4.1). A bare
+// mandatory INTEGER whose one legal value is 0, the inverse of the cert/CRL
 // readers, which reject 0 as the DER-forbidden default. Surface v1 as 1. A
 // cert-shaped [0] EXPLICIT wrapper at this position makes asn1.read.integer throw
 // asn1/* (fail-closed).
 var CSR_VERSION = pkix.versionReader(NS, { "0": 1 });
 
-// Attribute ::= SEQUENCE { type OID, values SET OF ANY } -- the shared pkix factory
+// Attribute ::= SEQUENCE { type OID, values SET OF ANY }, the shared pkix factory
 // under the csr NS (values raw DER, SET SIZE(1..MAX), no uniqueness). The same
 // factory serves the PKCS#8 private-key attributes.
 var ATTRIBUTE = pkix.attribute(NS);
@@ -76,8 +76,8 @@ var DIRECTORY_STRING_TAGS = [
 var RECOGNIZED_ATTRIBUTE_VALUE = {};
 RECOGNIZED_ATTRIBUTE_VALUE[oid.byName("extensionRequest")] = function (node, ctx) {
   // Surface the requested extensions decoded (same {oid,name,critical,value}
-  // shape as a certificate's extensions) so a CA pipeline -- and the EST
-  // re-enroll guard -- reads them off the attribute instead of re-walking the
+  // shape as a certificate's extensions) so a CA pipeline, and the EST
+  // re-enroll guard, read them off the attribute instead of re-walking the
   // raw Extensions bytes. Returned as an enrichment merged onto the attribute.
   try { return { extensions: schema.walk(EXTENSIONS, node, ctx).result }; }
   catch (e) {
@@ -101,7 +101,7 @@ RECOGNIZED_ATTRIBUTE_VALUE[oid.byName("challengePassword")] = function (node, ct
 //   subjectPKInfo SubjectPublicKeyInfo, attributes [0] IMPLICIT SET OF Attribute }.
 // attributes is a REQUIRED field (a CRI omitting [0] is a missing-required-field
 // fault, not silently accepted) modeled as an IMPLICIT [0] SET OF with min:0 (an
-// empty attributes SET is legal). subject MAY be empty -- no non-empty-DN guard.
+// empty attributes SET is legal). subject MAY be empty, so there is no non-empty-DN guard.
 var CERTIFICATION_REQUEST_INFO = schema.seq([
   schema.field("version", CSR_VERSION),
   schema.field("subject", NAME),
@@ -134,11 +134,11 @@ var CERTIFICATION_REQUEST_INFO = schema.seq([
 });
 
 // CertificationRequest ::= SEQUENCE { certificationRequestInfo, signatureAlgorithm,
-//   signature BIT STRING } -- the shared SIGNED envelope. DIVERGENCE from the
-// cert/CRL builders: OMIT the outer-vs-inner signatureAlgorithm agreement check
-// (the CRI has no inner signature AlgorithmIdentifier) and the non-empty-subject
-// guard (a CSR subject MAY be empty). The omission is structural -- this build
-// simply never references the agreement bytes.
+//   signature BIT STRING }, the shared SIGNED envelope. It diverges from the
+// cert/CRL builders by omitting the outer-vs-inner signatureAlgorithm agreement
+// check (the CRI has no inner signature AlgorithmIdentifier) and the
+// non-empty-subject guard (a CSR subject MAY be empty). The omission is
+// structural: this build simply never references the agreement bytes.
 var CERTIFICATION_REQUEST = pkix.signedEnvelope(NS, CERTIFICATION_REQUEST_INFO, {
   code: "csr/not-a-certification-request", what: "CertificationRequest",
   build: function (e) {

package/lib/schema-csrattrs.js

@@ -12,7 +12,7 @@
  *   The EST CSR Attributes wire format per RFC 8951 sec. 3.5 (the RFC 7030
  *   sec. 4.5.2 ASN.1 was syntactically broken, erratum 4384) with the RFC 9908
  *   template structures. `parse` turns a DER `Buffer` into
- *   `{ items }` -- `CsrAttrs ::= SEQUENCE SIZE (0..MAX) OF AttrOrOID`, where
+ *   `{ items }`, where `CsrAttrs ::= SEQUENCE SIZE (0..MAX) OF AttrOrOID` and
  *   `AttrOrOID ::= CHOICE { oid OBJECT IDENTIFIER, attribute Attribute }`
  *   disambiguates on the universal tag. An empty SEQUENCE is a COMPLETE valid
  *   document ("no additional information desired"). Each item surfaces its
@@ -31,7 +31,7 @@
  *   attributes carrying at most one `id-aa-extensionReqTemplate` and never both
  *   extension-request kinds. Template PRIORITY (a client that understands the
  *   template ignores the legacy elements, RFC 9908 sec. 4) is a `pki.est` builder
- *   rule, not a parse rejection -- parse surfaces everything.
+ *   rule, not a parse rejection: parse surfaces everything.
  *
  *   There is NO `pemDecode` / `pemEncode`: no RFC 7468 label exists for
  *   CsrAttrs; the wire encoding is bare RFC 4648 base64 handled by the EST
@@ -55,9 +55,9 @@ var NS = pkix.makeNS("csrattrs", CsrattrsError, oid);
 var T = asn1.TAGS;
 
 // The base Attribute is SET SIZE(1..MAX); ATTRIBUTE_KEYTYPE lowers the floor to 0
-// ONLY for the ecPublicKey / rsaEncryption key-type hints, whose empty values SET
-// means "any key of this type" (RFC 9908 sec. 3.2). Every other attribute -- and
-// every template inner attribute -- keeps the non-empty floor, so an empty
+// only for the ecPublicKey / rsaEncryption key-type hints, whose empty values SET
+// means "any key of this type" (RFC 9908 sec. 3.2). Every other attribute, and
+// every template inner attribute, keeps the non-empty floor, so an empty
 // challengePassword or unknown attribute still fails closed.
 // ATTRIBUTE keeps the base SET SIZE(1..MAX); ATTRIBUTE_OPTIONAL_VALUES lowers the
 // floor to 0. Only the recognized NON-KEY attributes that require a value
@@ -109,7 +109,7 @@ var TEMPLATE_VERSION = schema.decode(function (n, ctx) {
   return 0;
 }, function () { return asn1.build.integer(0n); });
 
-// SingleAttributeTemplate ::= SEQUENCE { type OID, value ANY OPTIONAL } -- a
+// SingleAttributeTemplate ::= SEQUENCE { type OID, value ANY OPTIONAL }, where a
 // value-absent element means "the client fills this in" (RFC 9908 sec. 3.4). The
 // trailing OPTIONAL ANY is the algorithmIdentifier-parameters shape.
 var SINGLE_ATTR_TEMPLATE = schema.seq([
@@ -136,14 +136,14 @@ var NAME_TEMPLATE = schema.seqOf(RDN_TEMPLATE, {
 });
 
 // SubjectPublicKeyInfoTemplate ::= SEQUENCE { algorithm AlgorithmIdentifier,
-//   subjectPublicKey BIT STRING OPTIONAL } -- the key is OPTIONAL (present ONLY
-//   as an RSA modulus-size placeholder), so pkix.spki (key required, arity 2)
+//   subjectPublicKey BIT STRING OPTIONAL }, where the key is OPTIONAL (present
+//   only as an RSA modulus-size placeholder), so pkix.spki (key required, arity 2)
 //   cannot be reused.
 var SPKI_TEMPLATE = schema.seq([
   schema.field("algorithm", ALGORITHM_IDENTIFIER),
   schema.optional("placeholderKey", schema.bitString(), { whenUniversal: [T.BIT_STRING] }),
 ], {
-  // subjectPKInfo is [0] IMPLICIT (RFC 9908 sec. 3.4) -- the context tag replaces
+  // subjectPKInfo is [0] IMPLICIT (RFC 9908 sec. 3.4), so the context tag replaces
   // the universal SEQUENCE tag, so the node is context-[0] constructed and its
   // children are read directly (the pwri keyDerivationAlgorithm [0] precedent).
   assert: "implicit", implicitTag: 0, arity: { min: 1, max: 2 }, code: "csrattrs/bad-spki-template", what: "SubjectPublicKeyInfoTemplate",
@@ -154,7 +154,7 @@ var SPKI_TEMPLATE = schema.seq([
 });
 
 // ExtensionTemplate ::= SEQUENCE { extnID OID, critical BOOLEAN DEFAULT FALSE,
-//   extnValue OCTET STRING OPTIONAL } -- extnValue absent means "client supplies";
+//   extnValue OCTET STRING OPTIONAL }, where extnValue absent means "client supplies";
 //   an explicit critical FALSE is non-DER (BOOLEAN DEFAULT FALSE). Not reusable
 //   from pkix.extension (whose extnValue is required), so the DER-critical rule
 //   is applied here directly.
@@ -245,15 +245,15 @@ function _enrichAttribute(item, ctx) {
     item.extensions = schema.walk(EXTENSIONS, asn1.decode(item.values[0]), ctx).result;
   } else if (item.oid === OID_EC_PUBLIC_KEY) {
     // A key-type hint's values SET is empty ("any curve") or a singleton naming
-    // ONE curve (RFC 9908 sec. 3.2); a multi-valued SET is ambiguous -- fail
-    // closed rather than letting DER ordering pick the advertised constraint.
+    // one curve (RFC 9908 sec. 3.2); a multi-valued SET is ambiguous, so it fails
+    // closed instead of letting DER ordering pick the advertised constraint.
     if (item.values.length > 1) throw ctx.E("csrattrs/bad-key-type-attr", "an ecPublicKey attribute values must be empty or a SET of exactly one named-curve OBJECT IDENTIFIER (RFC 9908 sec. 3.2)");
     if (item.values.length === 1) {
       try { item.curve = asn1.read.oid(asn1.decode(item.values[0])); }
       catch (e) { throw ctx.E("csrattrs/bad-key-type-attr", "an ecPublicKey attribute value must be a named-curve OBJECT IDENTIFIER (RFC 9908 sec. 3.2)", e); }
     }
   } else if (item.oid === OID_RSA_ENCRYPTION) {
-    // Empty ("any size") or a singleton naming ONE key size; reject a multi-valued SET.
+    // Empty ("any size") or a singleton naming one key size; reject a multi-valued SET.
     if (item.values.length > 1) throw ctx.E("csrattrs/bad-key-type-attr", "an rsaEncryption attribute values must be empty or a SET of exactly one INTEGER key size (RFC 9908 sec. 3.2)");
     if (item.values.length === 1) {
       var sz;
@@ -292,12 +292,12 @@ var ATTR_OR_OID = schema.decode(function (n, ctx) {
   throw ctx.E("csrattrs/bad-attr-or-oid", "each CsrAttrs element must be an OBJECT IDENTIFIER or an Attribute SEQUENCE (RFC 8951 sec. 3.5)");
 }, function (item) {
   // Paired encoder (one structure, both directions): reconstruct from the arm's
-  // identifying fields + raw values -- the typed enrichment is decode-only.
+  // identifying fields plus raw values, since the typed enrichment is decode-only.
   if (item.kind === "oid") return asn1.build.oid(item.oid);
   return asn1.build.sequence([asn1.build.oid(item.oid), asn1.build.set(item.values)]);
 });
 
-// CsrAttrs ::= SEQUENCE SIZE (0..MAX) OF AttrOrOID. min:0 -- an empty SEQUENCE is
+// CsrAttrs ::= SEQUENCE SIZE (0..MAX) OF AttrOrOID. min:0, because an empty SEQUENCE is
 // a complete valid document. The cross-element MUSTs (RFC 9908 sec. 3.2 single
 // id-ExtensionReq; sec. 3.4 single template) are enforced in the build.
 var CSR_ATTRS = schema.seqOf(ATTR_OR_OID, {
@@ -325,7 +325,7 @@ var CSR_ATTRS = schema.seqOf(ATTR_OR_OID, {
  * @related    pki.schema.parse, pki.est.buildEnrollAttributes
  *
  * Parse a DER `Buffer` of EST CSR Attributes (`CsrAttrs`, RFC 8951 sec. 3.5) into
- * `{ items }`. Each item is `{ kind, oid, name }` -- `kind` `"oid"` for a bare
+ * `{ items }`. Each item is `{ kind, oid, name }`, with `kind` `"oid"` for a bare
  * OID, `"attribute"` for an `Attribute`, which adds raw `values` plus, for the
  * RFC 9908 meaningful types, `extensions` (id-ExtensionReq), `curve` / `keySize`
  * (EC / RSA key-type conventions), or `template` (the request-info template). An

package/lib/schema-engine.js

@@ -21,7 +21,7 @@
  *   base the certificate parser (and, later, CRL / CMS) composes.
  *
  * @card
- *   Declarative ASN.1 structure schemas + one walk engine -- the shared base the
+ *   Declarative ASN.1 structure schemas plus one walk engine: the shared base the
  *   certificate / CRL / CMS parsers compose instead of hand-writing.
  */
 
@@ -96,7 +96,7 @@ function _assertArity(schema, kids, ctx) {
 // the OID / INTEGER / string reads). `decode(fn)` hands the whole node to fn,
 // which owns its try/catch and code mapping. `any()` yields the node itself.
 
-// Leaves carry BOTH directions: `read(node) -> value` and `write(value) -> DER TLV`,
+// Leaves carry both directions: `read(node) -> value` and `write(value) -> DER TLV`,
 // so a single leaf definition drives decode (walk) and encode (build). A [tag]
 // IMPLICIT leaf's write emits the context-tagged TLV directly, mirroring its read.
 function _implicitIntContent(v) { return asn1.decode(asn1.build.integer(v)).content; }
@@ -105,19 +105,19 @@ function integerLeaf()    { return { kind: "leaf", read: asn1.read.integer, writ
 function boolean()        { return { kind: "leaf", read: asn1.read.boolean, write: function (v) { return asn1.build.boolean(v); } }; }
 function octetString()    { return { kind: "leaf", read: asn1.read.octetString, write: function (v) { return asn1.build.octetString(v); } }; }
 function bitString()      { return { kind: "leaf", read: function (n) { var b = asn1.read.bitString(n); return { unusedBits: b.unusedBits, bytes: b.bytes }; }, write: function (v) { return asn1.build.bitString(v.bytes, v.unusedBits); } }; }
-// A [tag] IMPLICIT BIT STRING leaf (context-class primitive) -- the primitive-leaf
+// A [tag] IMPLICIT BIT STRING leaf (context-class primitive), the primitive-leaf
 // counterpart to implicitSetOf, for e.g. the PKCS#8 publicKey [1] (RFC 5958 sec. 2).
 function implicitBitString(tag) { return { kind: "leaf", read: function (n) { var b = asn1.read.bitStringImplicit(n, tag); return { unusedBits: b.unusedBits, bytes: b.bytes }; }, write: function (v) { return asn1.build.contextPrimitive(tag, Buffer.concat([Buffer.from([v.unusedBits]), v.bytes])); } }; }
-// A [tag] IMPLICIT OCTET STRING leaf (context-class primitive) -- the sibling of
+// A [tag] IMPLICIT OCTET STRING leaf (context-class primitive), the sibling of
 // implicitBitString, for e.g. the CMS SignerIdentifier subjectKeyIdentifier [0]
 // (RFC 5652 sec. 5.3). Yields the raw content bytes.
 function implicitOctetString(tag) { return { kind: "leaf", read: function (n) { return asn1.read.octetStringImplicit(n, tag); }, write: function (v) { return asn1.build.contextPrimitive(tag, v); } }; }
-// A [tag] IMPLICIT NULL leaf (context-class primitive, empty content) -- the sibling
+// A [tag] IMPLICIT NULL leaf (context-class primitive, empty content), the sibling
 // of implicitBitString/implicitOctetString, for e.g. the OCSP CertStatus good [0] /
 // unknown [2] arms (RFC 6960 sec. 4.2.1). Yields null; rejects a constructed or
 // non-empty [tag] node fail-closed.
 function implicitNull(tag) { return { kind: "leaf", read: function (n) { return asn1.read.nullImplicit(n, tag); }, write: function () { return asn1.build.contextPrimitive(tag, Buffer.alloc(0)); } }; }
-// A [tag] IMPLICIT INTEGER leaf (context-class primitive) -- the integer sibling of
+// A [tag] IMPLICIT INTEGER leaf (context-class primitive), the integer sibling of
 // implicitBitString, for the RFC 3161 Accuracy millis [0] / micros [1] fields
 // (context-tagged primitive INTEGERs). Yields a BigInt; a constructed or wrong-tag
 // node fails asn1/* at the codec.
@@ -152,14 +152,14 @@ function optional(name, schema, opts) {
   opts = opts || {};
   // How the optional field is recognized at its position:
   //   - default:       a context [tag] (the certificate version [0] shape).
-  //   - tags:          a context tag in the set -- an OPTIONAL field whose type is
+  //   - tags:          a context tag in the set, for an OPTIONAL field whose type is
   //     itself a CHOICE of several context alternatives, e.g. the CRMF CertReqMsg
   //     popo ProofOfPossession ([0]..[3]) sitting before the universal-SEQUENCE
   //     regInfo (RFC 4211 sec. 3), where ANY of the CHOICE's tags marks it present.
-  //   - whenUniversal: the next element iff its UNIVERSAL tag is in the set --
+  //   - whenUniversal: the next element iff its universal tag is in the set, for
   //     the CRL TBSCertList shape (bare INTEGER version, Time nextUpdate,
-  //     SEQUENCE revokedCertificates), disambiguated by tag, not a context [n].
-  //   - whenAny:       the next element whatever its tag -- an OPTIONAL ANY like
+  //     SEQUENCE revokedCertificates), disambiguated by tag and not a context [n].
+  //   - whenAny:       the next element whatever its tag, for an OPTIONAL ANY like
   //     AlgorithmIdentifier.parameters.
   // The recognizer lets _walkSeq CONSUME the element so a closed sequence can
   // reject whatever is left over (without it, a trailing ANY looks unconsumed).
@@ -172,7 +172,7 @@ function optional(name, schema, opts) {
         : function (n) { return isContext(n, opts.tag); };
   // default/defaultCode: `default` binds the DEFAULT value when the field is
   // absent. `defaultCode` opts the field into the X.690 sec. 11.5 walk-side reject
-  // (DER: a component equal to its DEFAULT shall not be included) -- a present
+  // (DER: a component equal to its DEFAULT shall not be included), so a present
   // value equal to `default` (strict equality; Buffers by bytes) fails with
   // that code, so each format keeps its own reject-code family.
   return { fkind: "optional", name: name, schema: schema, tag: opts.tag, match: match,
@@ -224,7 +224,7 @@ function setOf(item, opts) {
 function setOfUnique(item, keyFn, opts) {
   return setOf(item, Object.assign({ unique: keyFn }, opts || {}));
 }
-// [tag] IMPLICIT SET OF item -- the context tag REPLACES the universal SET tag,
+// [tag] IMPLICIT SET OF item: the context tag replaces the universal SET tag,
 // so the node is a context-class constructed [tag] whose direct children are the
 // items (RFC 2986 sec. 4.1 CSR attributes). No inner SET, no EXPLICIT unwrap.
 function implicitSetOf(tag, item, opts) {
@@ -233,9 +233,9 @@ function implicitSetOf(tag, item, opts) {
            min: opts.min, max: opts.max, maxCode: opts.maxCode,
            unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
 }
-// [tag] IMPLICIT SEQUENCE OF item -- the context tag REPLACES the universal SEQUENCE
+// [tag] IMPLICIT SEQUENCE OF item: the context tag replaces the universal SEQUENCE
 // tag, so the node is a context-class constructed [tag] whose direct children are the
-// items. Order-preserving: the SEQUENCE-OF sibling of implicitSetOf WITHOUT the SET
+// items. Order-preserving: the SEQUENCE-OF sibling of implicitSetOf without the SET
 // ascending-DER-order rule (RFC 3161 extensions [1] IMPLICIT Extensions).
 function implicitSeqOf(tag, item, opts) {
   opts = opts || {};
@@ -262,7 +262,7 @@ function implicitSeqOf(tag, item, opts) {
  * supplies the typed-error constructor, the error-code family prefix, and the
  * OID registry a build fn resolves names through.
  *
- * The schema is assembled from the combinators this module exports -- structural
+ * The schema is assembled from the combinators this module exports: structural
  * (`seq` / `field` / `optional` / `explicit` / `trailing` / `seqOf` / `setOf` /
  * `setOfUnique` / `implicitSeqOf` / `implicitSetOf` / `choice`) and value
  * (`oidLeaf` / `integerLeaf` / `boolean` / `octetString` / `bitString` /
@@ -473,8 +473,8 @@ function _encFail(message) { throw new Error("schema.encode: " + message); }
  * @spec       X.690, X.680
  * @related    pki.schema.engine.walk
  *
- * Encode a structural value to canonical DER by interpreting the SAME schema
- * `walk` decodes -- the constructor direction. `value` mirrors the schema: a `seq`
+ * Encode a structural value to canonical DER by interpreting the same schema
+ * `walk` decodes, in the constructor direction. `value` mirrors the schema: a `seq`
  * takes `{ fieldName: value }`, a leaf its natural JS value (an OID string, a
  * BigInt, a `{ unusedBits, bytes }` BIT STRING, a `Date`), a `repeat` an array, a
  * `choice` `{ arm, value }`. EXPLICIT wrappers and IMPLICIT `[tag]` retagging are
@@ -610,7 +610,7 @@ function _encodeChoice(schema, value, ctx) {
  * @opts
  *   code:       string,   // typed code wrapping a codec failure (required)
  *   what:       string,   // human label for the wrapped message
- *   ber:        boolean,  // default false -- BER content region (RFC 7292 sec. 4.1)
+ *   ber:        boolean,  // default false; BER content region (RFC 7292 sec. 4.1)
  *   budget:     object,   // { remaining: n } shared across a parse's re-decodes
  *   budgetCode: string,   // typed code when the budget is exhausted
  *

package/lib/schema-ocsp.js

@@ -10,7 +10,7 @@
  *
  * @intro
  *   OCSP request and response handling per RFC 6960 (sec. 4.1 OCSPRequest, sec. 4.2
- *   OCSPResponse). Two entry points -- `parseRequest` and `parseResponse` -- turn a
+ *   OCSPResponse). Two entry points, `parseRequest` and `parseResponse`, turn a
  *   DER or PEM message into a structured object. A response is a two-stage
  *   OID-dispatch: `OCSPResponse` carries an ENUMERATED `responseStatus` and an
  *   OPTIONAL `responseBytes`; when the `responseType` is `id-pkix-ocsp-basic` its
@@ -18,7 +18,7 @@
  *   decoded and walked, so the per-certificate statuses surface structurally.
  *
  *   OCSP is a signed protocol: the bytes an external verifier must hash are surfaced
- *   RAW and never re-serialized. `tbsRequestBytes` and `tbsResponseDataBytes` are the
+ *   raw and never re-serialized. `tbsRequestBytes` and `tbsResponseDataBytes` are the
  *   exact on-wire `tbsRequest` / `ResponseData` TLVs; each `CertID` surfaces its
  *   `issuerNameHash` / `issuerKeyHash` as raw octets, and the responder's `byKey`
  *   hash and the raw `signature` bytes are left for the caller to verify. Embedded
@@ -63,12 +63,12 @@ var OID_OCSP_BASIC = oid.byName("ocspBasic");
 // 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,
+// 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
+// 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;
@@ -98,14 +98,14 @@ var CRL_REASON = schema.decode(function (n, ctx) {
 });
 
 // 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 rather than reporting arbitrary bytes as a cert.
+// (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 + surfaced raw
+// 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" });
@@ -119,18 +119,18 @@ function _rawSignature(field) {
   return sig.bytes;
 }
 
-// certs [0] EXPLICIT SEQUENCE OF Certificate -- each element raw. Shared by the
+// 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
+// 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 --
+// 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
+// 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,
@@ -240,9 +240,9 @@ var SINGLE_RESPONSE = schema.seq([
   },
 });
 
-// ResponderID ::= CHOICE { byName [1] Name, byKey [2] KeyHash } (RFC 6960 sec. 4.2.1) --
+// 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 ...), NOT an IMPLICIT primitive [2].
+// 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" }) },
@@ -284,7 +284,7 @@ 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).
+// 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),

package/lib/schema-pkcs12.js

@@ -10,8 +10,8 @@
  *
  * @intro
  *   PKCS#12 (PFX) key-and-certificate store handling per RFC 7292. `parse`
- *   decodes a `.p12` / `.pfx` container -- the personal-information-exchange
- *   format OpenSSL, Windows CAPI, macOS Keychain, and NSS emit -- into its
+ *   decodes a `.p12` / `.pfx` container, the personal-information-exchange
+ *   format OpenSSL, Windows CAPI, macOS Keychain, and NSS emit, into its
  *   bags: private keys (delegated to the PKCS#8 parser), shrouded keys
  *   (algorithm surfaced, ciphertext kept opaque), certificates, CRLs,
  *   secrets, and nested safe contents, each with its `friendlyName` /
@@ -33,7 +33,7 @@
  *
  * @card
  *   Parse DER / BER / PEM RFC 7292 PKCS#12 (PFX) stores into key / cert /
- *   CRL / secret bags with their attributes -- keys via the PKCS#8 parser,
+ *   CRL / secret bags with their attributes: keys via the PKCS#8 parser,
  *   encrypted safes via CMS, MAC inputs surfaced raw for external
  *   verification, fail-closed.
  */
@@ -86,7 +86,7 @@ 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) rather than a second
+// 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);
 
@@ -235,14 +235,14 @@ var SAFE_BAG = schema.seq([
   },
 });
 
-// SafeContents ::= SEQUENCE OF SafeBag (sec. 4.2). Strictly a SEQUENCE -- a SET OF
+// 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
+// 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()),
@@ -292,9 +292,9 @@ var PFX = schema.seq([
       // 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 -- surfaced as
-      // integrityMode "none", never rejected by a parser that surfaces
-      // integrity inputs rather than verifying them.
+      // 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 {
@@ -312,7 +312,7 @@ 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
+      // 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)");
@@ -340,7 +340,7 @@ function _octetContent(node, ctx, what, code) {
 // 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 -- a
+// 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) {
@@ -377,10 +377,10 @@ function _walkAuthenticatedSafe(bytes, state, ctx) {
 // 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 + bag dispatch the plaintext path uses, so a decrypted blob shares every
+// 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.
 function walkSafeContents(der) {
-  // PKCS#12 content regions are normatively BER (RFC 7292 sec. 4.1) -- a decrypted SafeContents may use an
+  // 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 };
@@ -407,7 +407,7 @@ function _dispatchSafes(asMatch, state, 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 rather than re-serializing the recipientInfos the integrity check trusts.
+      // 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 " +
@@ -425,7 +425,7 @@ function _buildBag(rec, state, ctx) {
     type: null, bagId: rec.bagId,
     friendlyName: rec.friendlyName, localKeyId: rec.localKeyId, attributes: rec.attributes,
   };
-  // Key bags are walked from the DECODED node -- their wire bytes may carry
+  // 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) {
@@ -493,17 +493,17 @@ function _buildBag(rec, state, ctx) {
  * decoded onto `pbmac1` (`{ kdf: { salt, iterationCount, keyLength, prfOid,
  * prfName }, schemeOid, schemeName }`) with `hashParameters` keeping the raw
  * bytes, and `macedBytes` is the exact byte range the HMAC covers),
- * `"none"` (id-data authSafe without MacData -- the shape
+ * `"none"` (id-data authSafe without MacData, the shape
  * `openssl pkcs12 -export -nomac` emits; `mac` is `null` and the store
  * carries no integrity protection, a policy decision left to the caller),
- * or `"public-key"` (id-signedData authSafe -- the CMS SignedData surfaced
+ * or `"public-key"` (id-signedData authSafe, the CMS SignedData surfaced
  * on `authSafeSigned`, signature not verified here). Each of `safeBags` is
  * `{ type, bagId, friendlyName, localKeyId, attributes }` plus its arm:
  * a `keyBag` carries `key` (the PKCS#8 parse), a `pkcs8ShroudedKeyBag`
  * carries `encrypted` (algorithm surfaced, ciphertext opaque), `certBag` /
  * `crlBag` / `secretBag` carry their values raw and byte-exact, and a
  * `safeContentsBag` carries `nested` bags. Encrypted / enveloped safes are
- * surfaced structurally on `encryptedSafes` via the CMS module -- recipient
+ * surfaced structurally on `encryptedSafes` via the CMS module: recipient
  * infos and algorithms decoded, ciphertext never parsed. MAC verification
  * and bag decryption are passphrase operations for an external layer; the
  * inputs are surfaced exactly.
@@ -512,7 +512,7 @@ function _buildBag(rec, state, ctx) {
  * `Asn1Error` when the underlying encoding is malformed. Faults inside a
  * delegated CMS structure (a signedData authSafe, an encrypted / enveloped
  * safe) surface as `CmsError` (`cms/*`) and inside a key bag as `Pkcs8Error`
- * (`pkcs8/*`) -- all `PkiError` subclasses.
+ * (`pkcs8/*`), all of them `PkiError` subclasses.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -542,7 +542,7 @@ var parse = pkix.makeRecordingParser({
  * @related    pki.schema.pkcs12.parse
  *
  * Extract the DER bytes from a PEM block (default label `PKCS12`). A
- * `.p12` / `.pfx` file is almost always binary -- the PEM path is a
+ * `.p12` / `.pfx` file is almost always binary, so the PEM path is a
  * convenience for stores that transit text channels.
  *
  * @example

package/lib/schema-pkcs8.js

@@ -12,7 +12,7 @@
  *   PKCS#8 private-key handling per RFC 5208 sec. 5 (PrivateKeyInfo) and RFC 5958 sec. 2
  *   (OneAsymmetricKey). `parse` turns a DER or PEM (`PRIVATE KEY`) key into a
  *   structured object: version, the private-key algorithm identifier, the raw
- *   private-key bytes, the optional attributes, and -- for a v2 OneAsymmetricKey --
+ *   private-key bytes, the optional attributes, and (for a v2 OneAsymmetricKey)
  *   the optional public key. It composes the same schema engine and shared PKIX
  *   sub-schemas (AlgorithmIdentifier, Attribute) the other parsers use.
  *
@@ -46,7 +46,7 @@ var NS = pkix.makeNS("pkcs8", Pkcs8Error, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var ATTRIBUTE = pkix.attribute(NS);
 
-// version ::= INTEGER { v1(0), v2(1) } -- 0 and 1 are both LEGAL (the divergence
+// version ::= INTEGER { v1(0), v2(1) }, where 0 and 1 are both legal (the divergence
 // from every other reader; cert/CRL reject 0, CSR accepts only 0). Surface as the
 // RFC's vN number.
 var PKCS8_VERSION = pkix.versionReader(NS, { "0": 1, "1": 2 });