@blamejs/pki 0.5.7 → 0.5.8

package/lib/tls-cert-compress.js

@@ -15,18 +15,18 @@
  *   largest thing a handshake sends and matters most for post-quantum chains,
  *   where certificates grow by kilobytes. `parseCertificateMessage` decodes the
  *   RFC 8446 sec. 4.4.2 `Certificate` message itself, so a compressed chain
- *   arrives as certificate DER ready for `pki.schema.x509.parse` rather than as
+ *   arrives as certificate DER ready for `pki.schema.x509.parse` instead of as
  *   an opaque blob.
  *
- *   These are encoded in the TLS presentation language -- positional, tag-less,
- *   fixed-width big-endian integers and length-prefixed opaque vectors -- NOT
- *   ASN.1/DER, so this module composes the toolkit's bounded big-endian cursor
- *   rather than the DER schema engine.
+ *   These are encoded in the TLS presentation language (positional, tag-less,
+ *   fixed-width big-endian integers and length-prefixed opaque vectors) and not
+ *   in ASN.1/DER, so this module composes the toolkit's bounded big-endian cursor
+ *   in place of the DER schema engine.
  *
  *   Decompression is the attack surface and is fail-closed on both sides of the
  *   bound RFC 8879 sec. 5 requires: the decompressor is capped at the message's
- *   OWN declared uncompressed length (so a bomb is refused mid-stream, never
- *   allocated), and the output must then equal that length EXACTLY (which catches
+ *   own declared uncompressed length (so a bomb is refused mid-stream, never
+ *   allocated), and the output must then equal that length exactly (which catches
  *   the under-length direction a cap cannot see). The caller's policy cap applies
  *   independently, so a peer declaring 16 MiB does not get 16 MiB. This module
  *   decodes structure only -- it never verifies a certificate, builds a path, or
@@ -83,14 +83,14 @@ var LEVEL_OPT = {
   zstd: function (n) { var p = {}; p[zlib.constants.ZSTD_c_compressionLevel] = n; return { params: p }; },
 };
 
-// The names that are BOTH registered by RFC 8879 and reachable through the decompression
+// The names that are both registered by RFC 8879 and reachable through the decompression
 // guard on this runtime. An algorithm the guard cannot decompress must never be offered
-// or accepted -- advertising one would mean accepting a message we then cannot open.
+// or accepted: advertising one would mean accepting a message we then cannot open.
 var SUPPORTED = guard.compress.algorithms().filter(function (n) {
   return Object.prototype.hasOwnProperty.call(ALG_BY_NAME, n) && typeof COMPRESS[n] === "function";
 });
 
-// The minimum Certificate message size and the widest opaque<..2^24-1> vector -- both owned
+// The minimum Certificate message size and the widest opaque<..2^24-1> vector, both owned
 // by validator-tls, alongside the rest of the framing rule set. A declared
 // uncompressed_length below the minimum cannot be a Certificate message, and refusing it
 // also keeps a zero-length declaration away from the decompression cap, which is a positive
@@ -147,12 +147,12 @@ function _resolveAllowed(opts) {
  *
  * Decode an RFC 8879 sec. 4 `CompressedCertificate`: the `algorithm` code point, the
  * declared `uncompressedLength`, the recovered `certificateMessage` (the raw RFC 8446
- * sec. 4.4.2 `Certificate` message bytes, surfaced verbatim), and `certificate` -- that
+ * sec. 4.4.2 `Certificate` message bytes, surfaced verbatim), and `certificate`, that
  * message already decoded into its request context and per-entry certificate DER.
  *
  * The decompression bound is two-sided, as RFC 8879 sec. 5 requires. The decompressor is
  * capped at `min(uncompressedLength, policy cap)`, so a bomb is refused the moment its
- * output would exceed what the message itself declared -- it is never allocated. The
+ * output would exceed what the message itself declared, so it is never allocated. The
  * recovered length must then equal `uncompressedLength` exactly, which catches the
  * under-length direction no cap can see. A message that fails either way is refused;
  * RFC 8879 sec. 5 maps both to the `bad_certificate` alert, but they keep distinct codes
@@ -160,7 +160,7 @@ function _resolveAllowed(opts) {
  * diagnoses.
  *
  * An algorithm outside the RFC 8879 registry, one this runtime cannot decompress, or one
- * absent from `opts.allowedAlgorithms` is refused before any decompressor runs -- the
+ * absent from `opts.allowedAlgorithms` is refused before any decompressor runs, since the
  * algorithm MUST be one the receiver advertised (RFC 8879 sec. 4). An empty compressed
  * body is a framing violation (`opaque<1..2^24-1>`), not an empty certificate list.
  *
@@ -263,18 +263,18 @@ function decompressCertificate(bytes, opts) {
  * Decode an RFC 8446 sec. 4.4.2 `Certificate` message into its
  * `certificateRequestContext` (raw, empty in a server's handshake certificate) and its
  * `entries`. Each entry surfaces `certData` -- the certificate DER exactly as it appeared
- * on the wire, ready for `pki.schema.x509.parse` and never re-serialized -- plus the raw
+ * on the wire, ready for `pki.schema.x509.parse` and never re-serialized, plus the raw
  * `extensions` bytes that follow it and `extensionList`, those bytes decoded to their
  * RFC 8446 sec. 4.2 records (`type` and raw `data` per extension). The vector's framing is
- * validated rather than accepted opaquely, so a vector that cannot be a whole number of
+ * validated and not accepted opaquely, so a vector that cannot be a whole number of
  * Extensions is refused instead of being reported as a well-formed message.
  *
- * `certificate_type` is negotiated by a separate extension (RFC 7250) and is NOT present
+ * `certificate_type` is negotiated by a separate extension (RFC 7250) and is not present
  * in this message, so it cannot be inferred from the bytes. It is declared through
  * `opts.certificateType` and defaults to X509; under `"RawPublicKey"` the same slot is a
  * `SubjectPublicKeyInfo` and is surfaced as `spki` instead of `certData`.
  *
- * Throws `TlsError` with a stable `tls/*` code on any framing violation -- a lying vector
+ * Throws `TlsError` with a stable `tls/*` code on any framing violation: a lying vector
  * length, a field past its bound, or bytes trailing the entry list.
  *
  * @opts
@@ -330,7 +330,7 @@ function parseCertificateMessage(bytes, opts) {
  * through `decompressCertificate` and the recovered bytes compared to the input, so a
  * message this toolkit produces can never be one this toolkit's own decoder refuses.
  *
- * Throws `TlsError` with a stable `tls/*` code -- for an unknown algorithm, a message
+ * Throws `TlsError` with a stable `tls/*` code for an unknown algorithm, or a message
  * that cannot be framed (empty, or past the 2^24-1 ceiling either compressed or not).
  *
  * @opts

package/lib/trust.js

@@ -11,7 +11,7 @@
  * @intro
  *   Mozilla / CCADB root-program ingestion into constraint-carrying trust
  *   anchors. The bare root list (`tls.rootCertificates`) throws away exactly
- *   the metadata that decides WHICH roots may vouch for WHAT: the per-purpose
+ *   the metadata that decides which roots may vouch for what: the per-purpose
  *   trust bits (a root trusted for TLS is not thereby trusted for S/MIME) and
  *   the per-purpose distrust-after dates (a sunsetting root keeps validating
  *   already-issued certificates while certificates issued after the cutoff are
@@ -57,7 +57,7 @@ var PURPOSE_ATTRS = [
   ["CKA_TRUST_CODE_SIGNING", "codeSigning"],
 ];
 
-// The recognized CK_TRUST vocabulary. ONLY CKT_NSS_TRUSTED_DELEGATOR grants a
+// The recognized CK_TRUST vocabulary. Only CKT_NSS_TRUSTED_DELEGATOR grants a
 // purpose; the rest are recognized-but-untrusted (fail-closed: an absent or
 // non-delegator bit never defaults to trusted). A token outside this set is a
 // typed trust/bad-trust-value, never a silent false.
@@ -138,7 +138,7 @@ function _lexObjects(text) {
     var rawVal = m[3] !== undefined ? m[3].trim() : undefined;
     if (!type) throw E("trust/bad-block", "attribute line is missing its type token: " + name);
     if (!cur) {
-      // Refuse the block bomb BEFORE lexing another block's payloads.
+      // Refuse the block bomb before lexing another block's payloads.
       if (objects.length >= LIMITS.TRUST_MAX_OBJECTS) throw E("trust/bad-block", "certdata object count exceeds LIMITS.TRUST_MAX_OBJECTS");
       cur = { attrs: Object.create(null) };
     }
@@ -167,8 +167,8 @@ function _lexObjects(text) {
       if (rawVal === undefined || /\s/.test(rawVal)) throw E("trust/bad-block", name + " " + type + " must carry a single token value");
       entry = { type: type, value: rawVal };
     } else {
-      // An unknown value TYPE cannot be lexed safely (its value grammar is
-      // unknown) -- fail closed rather than guess past it.
+      // An unknown value type cannot be lexed safely (its value grammar is
+      // unknown), so fail closed instead of guessing past it.
       throw E("trust/bad-block", "unrecognized attribute type " + JSON.stringify(type) + " on " + name);
     }
     cur.attrs[name] = entry;
@@ -190,8 +190,8 @@ function _requireOctal(obj, name, what) {
   return a.bytes;
 }
 
-// The NSS distrust-after payload is the BARE ASCII of a YYMMDDHHMMSSZ UTCTime
-// (13 bytes) or a YYYYMMDDHHMMSSZ GeneralizedTime (15 bytes) -- no DER tag or
+// The NSS distrust-after payload is the bare ASCII of a YYMMDDHHMMSSZ UTCTime
+// (13 bytes) or a YYYYMMDDHHMMSSZ GeneralizedTime (15 bytes), with no DER tag or
 // length. Synthesize the minimal TLV and route it through the strict asn1
 // time reader so the Z-terminator / mandatory-seconds / component-rollover /
 // RFC 5280 sec. 4.1.2.5.1 2050-pivot rules are enforced once, never re-derived.
@@ -300,14 +300,14 @@ function _mkAnchor(cert, meta) {
     label: meta.label,
     mozillaCaPolicy: meta.mozillaCaPolicy,
   };
-  // A trust anchor IS the pair (name, key) -- RFC 5280 sec. 6.1.1 -- so those two fields are one
+  // A trust anchor is the pair (name, key) per RFC 5280 sec. 6.1.1, so those two fields are one
   // fact about one certificate, and they were derived here from one. `anchor()` re-derives them
-  // rather than reading them back, so an entry rebuilt with a substituted key cannot carry the
+  // instead of reading them back, so an entry rebuilt with a substituted key cannot carry the
   // store's NAME and its per-purpose trust metadata over to a key the store never vouched for.
   // Recorded off the object, so rebuilding the entry loses the record along with the binding.
-  // COPIED, not aliased. The record and the entry would otherwise hold the same Buffer and the same
-  // name object, so overwriting the entry's publicKey in place -- otherSpki.copy(entry.publicKey)
-  // for an equal-length key -- would overwrite the record with it, and re-deriving would hand back
+  // Copied, not aliased. The record and the entry would otherwise hold the same Buffer and the same
+  // name object, so overwriting the entry's publicKey in place (otherSpki.copy(entry.publicKey)
+  // for an equal-length key) would overwrite the record with it, and re-deriving would hand back
   // exactly the substituted key. A record that changes with the thing it is meant to pin is not one.
   //
   // The store's METADATA is recorded with them, and for the stronger reason: `purposes` IS the
@@ -334,7 +334,7 @@ var _DERIVED_FROM = new WeakMap();
 // The per-purpose distrust dates, with fresh Date objects. A Date is mutable, so handing back the
 // entry's own would let a consumer move the date this anchor is judged against.
 // The three trust bits, normalized to booleans. Read by the purpose gate and handed back on every
-// anchor, so it is built fresh from whichever source is authoritative rather than shared.
+// anchor, so it is built fresh from whichever source is authoritative and never shared.
 function _copyPurposes(src) {
   return {
     serverAuth: !!src && src.serverAuth === true,
@@ -352,13 +352,13 @@ function _copyDistrustAfter(src) {
   return out;
 }
 
-// A parsed Name, copied FAITHFULLY: every field the parser assigns, at every level, with nothing
-// mutable shared. Used on both sides of the record -- writing it in and handing it out -- so
+// A parsed Name, copied faithfully: every field the parser assigns, at every level, with nothing
+// mutable shared. Used on both sides of the record, writing it in and handing it out, so
 // neither direction shares an object with the caller.
 //
-// Faithful rather than "the fields the path validator reads", because this Name is handed back on
+// Faithful, not "the fields the path validator reads", because this Name is handed back on
 // pki.trust.anchor and is the same structure pki.schema.x509.parse produces. A copy that keeps the
-// subset one consumer needs silently degrades it for every other reader -- an attribute would lose
+// subset one consumer needs silently degrades it for every other reader: an attribute would lose
 // its registry `name`, so a caller walking anchor.name.rdns would see a different shape depending
 // on whether the anchor came from a store entry or straight from the parser. Each attribute value
 // is a string and so needs no copy of its own; the DER does.
@@ -396,11 +396,11 @@ function _anchorsAgree(x, y) {
     _datesEqual(x.distrustAfter, y.distrustAfter);
 }
 
-// Dedup by (subjectDer, publicKey): the SAME root appearing twice (a
-// duplicated block, or certdata + CCADB merged by the operator) collapses to
-// one anchor; a DISTINCT root that merely shares a subject DN has a different
-// key and survives. Two entries for one root that DISAGREE on trust metadata
-// are ambiguous -- fail closed rather than silently pick one.
+// Dedup by (subjectDer, publicKey): one root appearing twice (a duplicated
+// block, or certdata + CCADB merged by the operator) collapses to one anchor,
+// while a distinct root that merely shares a subject DN has a different key and
+// survives. Two entries for one root that disagree on trust metadata are
+// ambiguous, so they fail closed instead of silently picking one.
 function _dedupAnchors(anchors) {
   var seen = Object.create(null);
   var out = [];
@@ -443,7 +443,7 @@ function _dedupAnchors(anchors) {
  * dropped); a trust object with no certificate grants nothing. Malformed
  * octal, an oversized block, an unrecognized trust value, a mispaired or
  * ambiguous-duplicate block, or an undecodable distrust-after time throws a
- * typed `trust/*` error -- never a silently truncated or misattributed root.
+ * typed `trust/*` error, never a silently truncated or misattributed root.
  *
  * @example
  *   // Real input is the NSS certdata.txt read from disk; a one-root stream is
@@ -653,9 +653,9 @@ function _pemCell(cell) {
  * @defends    trust-metadata-misattribution (CWE-345), trust-store-parser-DoS (CWE-770)
  * @related    pki.trust.parseCertdata, pki.trust.anchor, pki.path.validate
  *
- * Parse a CCADB certificate-records CSV export into the SAME `Anchor` shape
+ * Parse a CCADB certificate-records CSV export into the same `Anchor` shape
  * `parseCertdata` produces, so downstream enforcement is source-agnostic.
- * Columns are located by header NAME -- never by position -- and unknown,
+ * Columns are located by header name, never by position, and unknown,
  * reordered, or extra columns are tolerated; a MISSING required column
  * (`Common Name or Certificate Name`, `Trust Bits`, `Distrust for TLS After
  * Date`, `Distrust for S/MIME After Date`, `PEM Info`) fails closed with
@@ -737,7 +737,7 @@ function parseCcadbCsv(text) {
  *
  * Turn a parsed trust-store entry into the `trustAnchor` object
  * `pki.path.validate` consumes: `{ name, publicKey, algorithm, parameters,
- * distrustAfter, purposes }` -- a straight hand-off (validate reads
+ * distrustAfter, purposes }`, a straight hand-off (validate reads
  * `distrustAfter` as a per-purpose map and `purposes` as the delegator set,
  * selected by its own `opts.checkPurpose`). With `opts.purpose` it
  * fail-fasts: an entry that is not a trusted delegator for that purpose
@@ -746,7 +746,7 @@ function parseCcadbCsv(text) {
  * authoritative gate stays inside `validate`).
  *
  * @opts
- *   purpose: string   // "serverAuth" | "emailProtection" | "codeSigning" -- fail-fast purpose check
+ *   purpose: string   // "serverAuth" | "emailProtection" | "codeSigning"; fail-fast purpose check
  *
  * @example
  *   var ca = await pki.key.generate("Ed25519");

package/lib/tsp-sign.js

@@ -51,7 +51,7 @@ var HASH_LEN = { sha256: 32, sha384: 48, sha512: 64 };
 // checker ran at all"; "undetermined" is "one ran and could not answer"; "waived" is an
 // undetermined one a caller chose to pass; "determined" is an explicit good-or-revoked answer.
 // Ranking them lets a caller trying several candidate paths keep the most established outcome any
-// of them reached, rather than whichever happened to run last.
+// of them reached. Order of evaluation then does not decide the answer.
 var _REVOCATION_RANK = { "false": 0, "undetermined": 1, "waived": 2, "determined": 3 };
 function _rankRevocation(v) {
   var r = _REVOCATION_RANK[String(v)];
@@ -61,7 +61,7 @@ function _moreEstablished(candidate, current) {
   return _rankRevocation(candidate) > _rankRevocation(current);
 }
 
-// A hash AlgorithmIdentifier { OID, NULL } -- messageImprint and ESSCertIDv2 hash algorithms
+// A hash AlgorithmIdentifier { OID, NULL }: messageImprint and ESSCertIDv2 hash algorithms
 // carry an explicit NULL parameter (the form RFC 3161 / RFC 5035 producers emit).
 function _hashAlgId(name) {
   if (!NODE_DIGEST[name]) throw _err("tsp/unsupported-algorithm", "unsupported hash algorithm " + JSON.stringify(name));
@@ -114,7 +114,7 @@ function _signingCertV2(certDer, hashName) {
  * @opts  serialNumber  REQUIRED -- a unique token serial number (a number or BigInt).
  * @opts  genTime       The trusted time (a `Date`). Default: now.
  * @opts  nonce         The request nonce to echo (a number or BigInt), for replay protection.
- * @opts  accuracy      `{ seconds?, millis?, micros? }` -- the genTime +/- accuracy.
+ * @opts  accuracy      The genTime +/- accuracy, as `{ seconds?, millis?, micros? }`.
  * @opts  ordering      Whether tokens from this TSA are strictly ordered in time (boolean).
  * @opts  certHashAlgorithm  The ESSCertIDv2 hash algorithm name. Default `sha256`.
  * @opts  sid / pem     Passed through to `pki.cms.sign` (signer identifier, PEM output).
@@ -250,7 +250,7 @@ function _assertImprint(mi) {
  * @related    pki.tsp.parseRequest, pki.tsp.sign
  *
  * Build an RFC 3161 `TimeStampReq` (sec. 2.4.1) over `messageImprint`
- * (`{ hashAlgorithm, hashedMessage }` -- the same shape `pki.tsp.sign` takes). `version` is 1;
+ * (`{ hashAlgorithm, hashedMessage }`, the same shape `pki.tsp.sign` takes). `version` is 1;
  * `certReq` is BOOLEAN DEFAULT FALSE, so it is emitted only when explicitly `true`. Returns DER
  * (or PEM when `opts.pem`).
  *
@@ -611,38 +611,38 @@ function _buildTsaChains(leaf, pool) {
  * @related    pki.tsp.sign, pki.cms.verify, pki.path.validate
  *
  * Verify an RFC 3161 TimeStampToken against the data it should cover. `token` is the token DER /
- * PEM (never a parsed object -- every checked field is read from the CMS-verified eContent, so a
- * mutated parsed structure cannot desynchronize the checks from the signed bytes). `data` is the
+ * PEM, never a parsed object: every checked field is read from the CMS-verified eContent, so a
+ * mutated parsed structure cannot desynchronize the checks from the signed bytes. `data` is the
  * original bytes (hashed under the token's messageImprint algorithm) or a precomputed
  * `{ hashAlgorithm, hashedMessage }`. Returns `{ valid, trusted, revocationChecked,
  * anchorConstraints, genTime, accuracy, serialNumber,
  * serialNumberHex, policy, nonce, tsa, tstInfo, signer, code?, reason? }`. `valid` is true only
  * when the CMS signature, the imprint match, the eContentType, the ESSCertID(V2) binding, the
  * RFC 3161 sec. 2.3 critical single-`timeStamping` extendedKeyUsage rule, the requested nonce (when
- * supplied), and -- when a `trustAnchor` is supplied -- the full out-of-path TSA-cert path
+ * supplied), and, when a `trustAnchor` is supplied, the full out-of-path TSA-cert path
  * validation all pass. A conformance / trust failure of a well-formed token is a
  * `{ valid:false, code }` verdict; malformed or config input throws a typed `TspError`.
  *
  * `trusted` is the second claim and is kept apart from the first. `valid` says the token's
  * signature and structural bindings hold; `trusted` says the timestamp authority chained to an
  * anchor this caller named. Without `trustAnchor` there is nothing to chain to and `trusted` is
- * `false` -- a definite answer rather than a missing one, on the refusal branch as well as the
- * accepting one. A timestamp is archived precisely to be re-read years later, and one boolean
+ * `false`: every branch, refusing and accepting alike, carries the field with a definite
+ * value. A timestamp is archived precisely to be re-read years later, and one boolean
  * cannot answer both questions then.
  *
  * `revocationChecked` is the third claim, for the same reason. Revocation runs only when a
- * `revocationChecker` is supplied, so a `trusted` token whose TSA was never checked against a CRL
- * or an OCSP responder reads identically to one established un-revoked -- unless the verdict says
- * which. It is `false` whenever no path ran at all. `anchorConstraints` carries whatever the anchor
+ * `revocationChecker` is supplied. Without a field naming which happened, a `trusted` token whose
+ * TSA was never checked against a CRL or an OCSP responder reads identically to one established
+ * un-revoked. It is `false` whenever no path ran at all. `anchorConstraints` carries whatever the anchor
  * itself constrained, from `pki.path.validate`.
  *
- * @opts  trustAnchor   Anchor `{ name, publicKey, algorithm }` -- runs `pki.path.validate` on the
+ * @opts  trustAnchor   Anchor `{ name, publicKey, algorithm }`. Runs `pki.path.validate` on the
  *                       TSA certificate chain ordered from the token's embedded certificates
  *                       (validity at genTime, requiredEku timeStamping, and revocation when a
- *                       `revocationChecker` is supplied -- `revocationChecked` reports which), so a
- *                       TSA under an intermediate CA validates, not only one directly under the
- *                       anchor. Omit to verify signature + imprint + binding + EKU only and anchor
- *                       the cert yourself.
+ *                       `revocationChecker` is supplied, with `revocationChecked` reporting which),
+ *                       so a TSA under an intermediate CA validates, not only one directly under
+ *                       the anchor. Omit to verify signature + imprint + binding + EKU only and
+ *                       anchor the cert yourself.
  * @opts  nonce         Require the token's TSTInfo.nonce to equal this (a number/BigInt).
  * @opts  reqPolicy     Require the token's policy to equal this (an OID name or dotted string).
  * @opts  certs         Out-of-band TSA certificates (an array of DER `Buffer`s) added to the signer

package/lib/validator-all.js

@@ -8,7 +8,7 @@
 // validator-all -- the validator-family orchestrator (schema-all's role for the
 // validator family, guard-all's role for the guards). It assembles the per-type
 // conformance validators into one namespaced surface every format module composes,
-// so a format depends on the family rather than re-deriving a decoded type's rule set
+// so a format depends on the family and no module re-derives a decoded type's rule set
 // inline (the drift that leaks a spec MUST out one review round at a time):
 //
 //   validator.cose.credentialKey / .toSpki

package/lib/validator-attcert.js

@@ -9,7 +9,7 @@
 // attestation-certificate profile" (WebAuthn sec. 8.2.1 packed, sec. 8.3.1 TPM AIK).
 // Sibling to the guard family: a validator owns a decoded TYPE's COMPLETE conformance rule
 // set once, so the packed and AIK profiles cannot drift apart or lose a gate (e.g. the v3
-// check that previously lived split out in the tpm verifier rather than in the profile).
+// check that previously lived split out in the tpm verifier, away from the profile).
 //
 // The caller supplies its parsed certificate + an extension-accessor object `exts`
 // { find(cert, oidName) -> rawExt|null, decode(cert, oidName) -> {critical, value}|null }

package/lib/validator-cose.js

@@ -10,7 +10,7 @@
 // CTAP2 canonical-CBOR profile WebAuthn sec. 6.5.1 imposes). Sibling to the guard
 // family: where a guard owns a CVE-class fail-closed defence once, a validator owns a
 // decoded TYPE's COMPLETE conformance rule set once, so a format module composes the
-// family rather than re-deriving a partial subset inline (the drift that leaks MUSTs
+// family instead of re-deriving a partial subset inline (the drift that leaks MUSTs
 // out one review round at a time). Enforced by the validator-shape-reinlined
 // codebase-patterns detector: a lib function that re-inlines COSE-key validation fires.
 //
@@ -20,7 +20,7 @@
 //
 // Rule set (gap-checked verbatim against RFC 9052 sec. 7 + RFC 9053 sec. 2/6 +
 // WebAuthn sec. 6.5.1 + the IANA COSE Key Type / Key Type Parameters registries):
-//   - kty (label 1) REQUIRED; value an integer (CTAP2 canonical -- a tstr kty/alg is
+//   - kty (label 1) REQUIRED; value an integer (CTAP2 canonical, so a tstr kty/alg is
 //     rejected as non-canonical for the WebAuthn profile).
 //   - alg (label 3) REQUIRED (the RP needs it to verify the later assertion).
 //   - EC2 (kty 2): crv (-1), x (-2), y (-3) all present; x/y length == the curve field
@@ -29,16 +29,16 @@
 //   - CANONICAL: EXACTLY the type's parameters, nothing more (EC2 = 5, OKP/RSA = 4) --
 //     rejects a padded key / a private "d" component / kid / key_ops (WebAuthn 6.5.1
 //     CTAP2 canonical, stricter than open COSE `* label => values`).
-//   - PROFILE: alg <-> kty (and, for EC2, alg <-> crv) consistent; -8 (EdDSA) is Ed25519
-//     ONLY; the RFC 9864 fully-specified ids (-9/-51/-52/-19/-53) are accepted.
-//   - COMPRESSED: an EC2 credential key MUST use the uncompressed point form (y is a full
-//     coordinate byte string, never a CBOR bool sign bit) -- WebAuthn sec. alg identifier.
+//   - PROFILE: alg <-> kty (and, for EC2, alg <-> crv) consistent; -8 (EdDSA) is only
+//     Ed25519; the RFC 9864 fully-specified ids (-9/-51/-52/-19/-53) are accepted.
+//   - COMPRESSED: an EC2 credential key MUST use the uncompressed point form, per WebAuthn
+//     sec. alg identifier: y is a full coordinate byte string, never a CBOR bool sign bit.
 //   - ON-CURVE: the public key point MUST be valid for its curve. For EC2 the SPKI is
 //     imported via node:crypto so OpenSSL validates the point (an off-curve or identity
-//     point fails to parse). For OKP, OpenSSL does NOT validate the Edwards point on
+//     point fails to parse). For OKP, OpenSSL does not validate the Edwards point on
 //     import (an all-zeroes key parses, and even verifies a trivial signature), so the
 //     point is checked explicitly via edwards-point (RFC 8032 decode + cofactor low-order
-//     rejection) -- an off-curve, non-canonical, or low-order OKP key fails closed.
+//     rejection). An off-curve, non-canonical, or low-order OKP key fails closed.
 
 var cbor = require("./cbor-det");
 var asn1 = require("./asn1-der");
@@ -54,7 +54,7 @@ var EC2_CRV_OID = { 1: "prime256v1", 2: "secp384r1", 3: "secp521r1" };
 var OKP_CRV = { 6: { oid: "Ed25519", len: 32 }, 7: { oid: "Ed448", len: 57 } };
 // alg (label 3) -> the key type (and, for EC2, curve) it pins. WebAuthn (sec. alg
 // identifier) adds guarantees over the open COSE registry: an ECDSA alg fixes its curve,
-// -8 (EdDSA) is Ed25519 ONLY, and the RFC 9864 fully-specified ids (-9 ESP256, -51 ESP384,
+// -8 (EdDSA) is only Ed25519, and the RFC 9864 fully-specified ids (-9 ESP256, -51 ESP384,
 // -52 ESP512, -19 Ed25519, -53 Ed448) each pin key type + curve. A verifier accepts the
 // fully-specified ids even though WebAuthn recommends against them for credential creation.
 // The RSA credential-key bounds. 2048 bits is the floor every current FIDO authenticator and
@@ -73,8 +73,8 @@ var ALG_PROFILE = {
   "-9": { kty: 2, crv: 1 }, "-51": { kty: 2, crv: 2 }, "-52": { kty: 2, crv: 3 },
   "-8": { kty: 1, crv: 6 }, "-19": { kty: 1, crv: 6 }, "-53": { kty: 1, crv: 7 },
   // RSASSA-PSS at all three strengths. PS256 alone left PS384/PS512 refused at PARSE time on a key
-  // that is perfectly well-formed -- the same bytes accepted under -37 -- so the refusal blamed the
-  // key rather than the algorithm, and a relying party migrating credential rows written by another
+  // that is perfectly well-formed (the same bytes accepted under -37), so the refusal blamed the
+  // key instead of the algorithm, and a relying party migrating credential rows written by another
   // implementation could not tell which of its stored keys this verifier would decline, or why.
   "-257": { kty: 3 }, "-258": { kty: 3 }, "-259": { kty: 3 },
   "-37": { kty: 3 }, "-38": { kty: 3 }, "-39": { kty: 3 }, "-65535": { kty: 3 },
@@ -89,12 +89,12 @@ var ALG_PROFILE = {
 // @validator-shape kty\s*===\s*2n
 // @validator-shape EC2_CRV_LEN|ALG_PROFILE
 // `unsupportedCode` is OPTIONAL and names the code raised when the key is well-formed but its
-// algorithm is not one this verifier implements -- a different fact from a malformed key. Omit it
+// algorithm is not one this verifier implements, a different fact from a malformed key. Omit it
 // and that case keeps raising `code`, so an existing caller sees no change.
 function credentialKey(node, E, code, unsupportedCode) {
   function bad(msg, cause) { return new E(code, msg, cause); }
   if (!node || node.majorType !== 5) throw bad("a COSE_Key must be a CBOR map (RFC 9052 sec. 7)");
-  // Every parameter read maps a wrong-type cbor/* fault to the caller's domain -- a
+  // Every parameter read maps a wrong-type cbor/* fault to the caller's domain: a
   // wrong-typed COSE label (x as an integer, kty as a string) is bad input, not a leak.
   function ib(label) { var n = cbor.read.mapGet(node, label); if (!n) return null; try { return cbor.read.byteString(n); } catch (e) { throw bad("COSE_Key parameter " + label + " must be a byte string", e); } }
   function ii(label) { var n = cbor.read.mapGet(node, label); if (!n) return null; try { return cbor.read.int(n); } catch (e) { throw bad("COSE_Key parameter " + label + " must be an integer", e); } }
@@ -122,17 +122,17 @@ function credentialKey(node, E, code, unsupportedCode) {
   } else if (kty === 3n) {
     key.n = ib(-1); key.e = ib(-2);
     if (!key.n || !key.n.length || !key.e || !key.e.length) throw bad("an RSA COSE_Key must carry n (-1) and e (-2)");
-    // The MATERIAL, not merely its presence -- the same standard the other two key types are held
-    // to, where EC2 pins x/y to the curve's field size and has the point validated on the curve,
+    // The material itself, not merely its presence: the same standard the other two key types are
+    // held to, where EC2 pins x/y to the curve's field size and has the point validated on the curve,
     // and OKP pins x to an exact length. Checking only presence let a 1-byte modulus and an
     // exponent of 1 through as conformant credential public keys, and both reach the WebCrypto
     // import, so they reach real signature verification. e = 1 makes RSA the identity function:
     // the "signature" is the message, and it verifies under any modulus.
-    // BOTH values first, before either is judged. RFC 8230 sec. 4 encodes n and e as unsigned
-    // big-endian integers with no leading zero, and every check below reads a byte LENGTH as though
+    // Both values first, before either is judged. RFC 8230 sec. 4 encodes n and e as unsigned
+    // big-endian integers with no leading zero, and every check below reads a byte length as though
     // it were a magnitude: the modulus floor, the exponent bound, and the exponent's value. A
     // padded encoding decouples the two, so `00 01` would be read as a two-byte exponent and skip
-    // the value check that refuses 1 -- the degenerate key the whole check exists to catch. (An EC2
+    // the value check that refuses 1, the degenerate key the whole check exists to catch. (An EC2
     // coordinate is the opposite case, fixed-width and zero-padded by definition, which is why this
     // rule is stated for the RSA parameters and not for x/y.)
     if (key.n[0] === 0) throw bad("an RSA COSE_Key modulus (-1) must be minimally encoded, with no leading zero byte (RFC 8230 sec. 4)");
@@ -147,9 +147,9 @@ function credentialKey(node, E, code, unsupportedCode) {
     // so a caller cannot hand over a megabyte of exponent for the modular exponentiation to chew.
     if (key.e.length > RSA_MAX_EXPONENT_BYTES) throw bad("an RSA COSE_Key exponent (-2) is longer than " + RSA_MAX_EXPONENT_BYTES + " bytes");
     if ((key.e[key.e.length - 1] & 1) === 0) throw bad("an RSA COSE_Key exponent (-2) must be odd");
-    // Minimal encoding above makes a one-byte e the ONLY way to express a value this small, so the
+    // Minimal encoding above makes a one-byte e the only way to express a value this small, so the
     // comparison is on the value and not on where it happens to sit.
-    if (key.e.length === 1 && key.e[0] <= 1) throw bad("an RSA COSE_Key exponent (-2) must be greater than 1 -- e = 1 makes RSA the identity function");
+    if (key.e.length === 1 && key.e[0] <= 1) throw bad("an RSA COSE_Key exponent (-2) must be greater than 1; e = 1 makes RSA the identity function");
   } else {
     throw bad("unsupported COSE_Key kty " + Number(kty));
   }
@@ -170,40 +170,39 @@ function credentialKey(node, E, code, unsupportedCode) {
 // form their datastore round-trips, which is not a choice about how carefully their
 // credential is checked.
 //
-// Everything above this line is about the ENCODING -- a CBOR map, integer labels, byte
-// strings, the canonical parameter count -- and can only be asked of bytes. Everything
+// Everything above this line is about the encoding (a CBOR map, integer labels, byte
+// strings, the canonical parameter count) and can only be asked of bytes. Everything
 // here is about the key, and is asked of both.
 //
 // @enforced-by behavioral -- key-material rules have no rename-proof code shape distinct
-//   from ordinary length and byte comparisons; the RED vectors that drive BOTH accepted
+//   from ordinary length and byte comparisons; the RED vectors that drive both accepted
 //   forms of a stored credential key (the COSE bytes and the object) through
 //   pki.webauthn.verifyAssertion with an undersized modulus, e = 1, a curve/length
 //   mismatch and a short OKP x are the guard.
 function assertKeyMaterial(key, E, code, unsupportedCode) {
   function bad(msg, cause) { return new E(code, msg, cause); }
   if (!key || typeof key !== "object") throw bad("a credential key must be a decoded COSE_Key object");
-  // ONE read of each field, into a plain object, before anything is checked or used.
+  // One read of each field, into a plain object, before anything is checked or used.
   //
-  // The object form comes from the caller, so any of these can be an accessor. One that THROWS
-  // turns a validation into a raw fault -- the thing this function exists to prevent -- and one
-  // that returns DIFFERENT values on successive reads makes the field that was checked and the
-  // field that is used two different values, which is the check defeated rather than merely
-  // reported badly. Reading each exactly once settles both, and settles them for every field
-  // rather than for the ones a particular branch happens to reach.
+  // The object form comes from the caller, so any of these can be an accessor. One that throws
+  // turns a validation into a raw fault, the thing this function exists to prevent, and one
+  // that returns different values on successive reads makes the field that was checked and the
+  // field that is used two different values, which defeats the check outright. Reading each
+  // exactly once settles both, for every field, not just the ones a particular branch reaches.
   try {
     key = { kty: key.kty, alg: key.alg, crv: key.crv, x: key.x, y: key.y, n: key.n, e: key.e };
   } catch (e) { throw bad("a credential key field could not be read", e); }
-  // Then the TYPE and the VALUE. BigInt() throws a raw TypeError on a Symbol and on undefined, and
-  // a raw RangeError on a fractional or non-finite number, so "it is a number" is not the check --
-  // "it is an integer" is. EVERY integer label the branches below read, not the two the dispatch
-  // happens to need first:
+  // Then the type and the value. BigInt() throws a raw TypeError on a Symbol and on undefined, and
+  // a raw RangeError on a fractional or non-finite number, so the check is not "it is a number";
+  // it is "it is an integer". Every integer label the branches below read, not the two the
+  // dispatch happens to need first:
   // crv indexes a lookup table, and a Symbol thrown at a property read is the same raw fault as a
   // Symbol thrown at BigInt(). The decoded form gets these from the CBOR reader, which has already
   // established them; the object form gets them from the caller, so this is where they are settled.
   // A BigInt is bounded too. COSE labels are small registry integers, and an unbounded one converts
-  // to Infinity, which then throws a raw RangeError at the next conversion -- the same defeat as a
-  // fractional number, reached by a value that IS an integer. "It is an integer" is not the whole
-  // check either; "it is an integer this code can carry" is.
+  // to Infinity, which then throws a raw RangeError at the next conversion: the same defeat as a
+  // fractional number, reached by a value that is an integer. So "it is an integer" is not the
+  // whole check either; "it is an integer this code can carry" is.
   var MAX = BigInt(Number.MAX_SAFE_INTEGER);
   function _isInt(v) {
     if (typeof v === "bigint") return v <= MAX && v >= -MAX;
@@ -212,8 +211,8 @@ function assertKeyMaterial(key, E, code, unsupportedCode) {
   if (!_isInt(key.kty)) throw bad("a COSE_Key kty (label 1) must be an integer");
   if (!_isInt(key.alg)) throw bad("a COSE_Key alg (label 3) must be an integer");
   if (key.crv !== undefined && key.crv !== null && !_isInt(key.crv)) throw bad("a COSE_Key crv (label -1) must be an integer");
-  // ONE representation from here down. A label may arrive as a Number or a BigInt -- a CBOR reader
-  // hands out BigInt, an object built in JavaScript is likelier to hold Number -- and everything
+  // One representation from here down. A label may arrive as a Number or a BigInt (a CBOR reader
+  // hands out BigInt; an object built in JavaScript is likelier to hold Number), and everything
   // below compares with === against the Number-keyed profile table and the curve tables. Accepting
   // both forms at the gate and then comparing only one is a check that answers by how the caller
   // happened to spell the value; the decoded arm normalizes here too, for the same reason.
@@ -236,14 +235,14 @@ function assertKeyMaterial(key, E, code, unsupportedCode) {
     if (bits < RSA_MIN_MODULUS_BITS) throw bad("an RSA COSE_Key modulus (-1) is " + bits + " bits, below the " + RSA_MIN_MODULUS_BITS + "-bit minimum");
     if (key.e.length > RSA_MAX_EXPONENT_BYTES) throw bad("an RSA COSE_Key exponent (-2) is longer than " + RSA_MAX_EXPONENT_BYTES + " bytes");
     if ((key.e[key.e.length - 1] & 1) === 0) throw bad("an RSA COSE_Key exponent (-2) must be odd");
-    if (key.e.length === 1 && key.e[0] <= 1) throw bad("an RSA COSE_Key exponent (-2) must be greater than 1 -- e = 1 makes RSA the identity function");
+    if (key.e.length === 1 && key.e[0] <= 1) throw bad("an RSA COSE_Key exponent (-2) must be greater than 1; e = 1 makes RSA the identity function");
   } else {
     throw bad("unsupported COSE_Key kty " + Number(key.kty));
   }
   // PROFILE: the declared alg must match the key type (and, for EC2, the curve).
   var prof = ALG_PROFILE[String(key.alg)];
-  // An algorithm this verifier does not implement is NOT a malformed key. The key can be perfectly
-  // well-formed -- the same bytes may parse under a neighbouring algorithm id -- and a relying
+  // An algorithm this verifier does not implement is not a malformed key. The key can be perfectly
+  // well-formed (the same bytes may parse under a neighbouring algorithm id), and a relying
   // party migrating credential rows written elsewhere needs to tell "I cannot check this
   // algorithm" from "these bytes are wrong", since only one of those is fixable by re-registering.
   // Callers that do not distinguish the two pass one code and keep the previous behaviour.
@@ -254,8 +253,8 @@ function assertKeyMaterial(key, E, code, unsupportedCode) {
   // x/y or the identity point fails to parse here.
   try { nodeCrypto.createPublicKey({ key: toSpki(key, E, code), format: "der", type: "spki" }); }
   catch (e) { throw bad("the credential public key point is not valid for its curve", e); }
-  // OpenSSL does NOT validate an OKP (Ed25519/Ed448) point on import -- an all-zeroes key
-  // parses, and even verifies a trivial signature -- so an OKP point needs an explicit
+  // OpenSSL does not validate an OKP (Ed25519/Ed448) point on import. An all-zeroes key
+  // parses, and even verifies a trivial signature, so an OKP point needs an explicit
   // on-curve + full-order (non-low-order) check (RFC 8032 decode + the cofactor check).
   if (Number(key.kty) === 1 && !edwardsPoint.validate(key.x, key.crv)) throw bad("the OKP credential public key is not a valid, full-order Edwards point");
   return key;

package/lib/validator-keydesc.js

@@ -19,12 +19,12 @@
 // schema):
 //   - KeyDescription is a positional SEQUENCE; attestationChallenge (position 4) MUST equal
 //     clientDataHash.
-//   - allApplications (tag 600) MUST be absent from BOTH the softwareEnforced (position 6)
+//   - allApplications (tag 600) MUST be absent from both the softwareEnforced (position 6)
 //     and teeEnforced (position 7) AuthorizationLists (the key MUST be scoped to the RP).
 //   - origin (tag 702) MUST equal KM_ORIGIN_GENERATED (0): at least one list declares it,
 //     and every list that declares one says GENERATED (a mixed IMPORTED/GENERATED key is
 //     contradictory and rejected).
-//   - purpose (tag 1) MUST be EXACTLY { KM_PURPOSE_SIGN (2) } over the union of the lists.
+//   - purpose (tag 1) MUST be exactly { KM_PURPOSE_SIGN (2) } over the union of the lists.
 
 var asn1 = require("./asn1-der");
 
@@ -53,7 +53,7 @@ function _purposeUnion(a, b, E, code) {
   return out;
 }
 
-// androidKeyDescription(cert, clientDataHash, exts, E, code, failCode) -- the complete
+// androidKeyDescription(cert, clientDataHash, exts, E, code, failCode) is the complete
 // WebAuthn 8.4.1 KeyDescription gate. A verifier MUST route the android-key description
 // through here, never re-derive a partial subset of the four checks inline.
 // @enforced-by behavioral -- the challenge / allApplications / origin / purpose checks are