@blamejs/pki 0.5.7 → 0.5.8

package/lib/validator-sig.js

@@ -7,21 +7,21 @@
 //
 // validator-sig -- the SINGLE home for "is this a conformant DER ECDSA-Sig-Value", and
 // its conversion to the raw r||s (IEEE P1363) form a WebCrypto verify expects. Sibling to
-// the guard family: a validator owns a decoded TYPE's COMPLETE conformance rule set once,
-// so a format module composes it rather than hand-decoding a 2-INTEGER SEQUENCE into r/s
+// the guard family: a validator owns a decoded type's complete conformance rule set once,
+// so a format module composes it instead of hand-decoding a two-INTEGER SEQUENCE into r/s
 // and forgetting a strict-DER check (the drift a validator exists to prevent).
 //
 // Interface mirrors the guard family: (subject, ..., E, code) where E is the caller's
 // typed error CONSTRUCTOR and code its domain code.
 //
 // Rule set (gap-checked verbatim against RFC 3279 sec. 2.2.3 + X.690 sec. 8.3 + SEC1):
-//   - ECDSA-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER } -- a universal SEQUENCE with
-//     EXACTLY two children.
-//   - r and s are each a PRIMITIVE, MINIMALLY-ENCODED (X.690 sec. 8.3.2 -- no redundant
-//     leading 0x00/0xFF), POSITIVE integer. Reading through the strict DER integer reader
-//     enforces the primitive + minimal-encoding rules; the value is then range-checked
+//   - ECDSA-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }, a universal SEQUENCE with
+//     exactly two children.
+//   - r and s are each a primitive, minimally-encoded (X.690 sec. 8.3.2, no redundant
+//     leading 0x00/0xFF), positive integer. Reading through the strict DER integer reader
+//     enforces the primitive and minimal-encoding rules; the value is then range-checked
 //     positive (r,s >= 1) and bounded by the curve field size. A non-minimal, zero,
-//     negative, or over-size coordinate fails closed -- never normalized-and-accepted.
+//     negative, or over-size coordinate fails closed, never normalized-and-accepted.
 
 var asn1 = require("./asn1-der");
 
@@ -52,8 +52,8 @@ var CURVE_ORDER = {
 
 // ecdsaDerToP1363(der, curve, E, code) -> the DER ECDSA-Sig-Value converted to raw r||s (P1363),
 // each coordinate left-padded to the curve field width, rejecting r or s outside [1, n-1] against
-// the curve ORDER (CVE-2022-21449 "Psychic Signatures" -- the r/s = 0 case AND the >= n upper
-// bound). `curve` is a WebCrypto namedCurve (P-256/384/521). This is the SINGLE ECDSA-Sig-Value
+// the curve order (CVE-2022-21449 "Psychic Signatures": the r/s = 0 case and the >= n upper
+// bound). `curve` is a WebCrypto namedCurve (P-256/384/521). This is the single ECDSA-Sig-Value
 // conformance gate every curve-aware verifier routes through: it enforces the complete strict-DER
 // rule set (2-INTEGER SEQUENCE, minimal encoding) AND the order bound, so a verifier never
 // hand-decodes the SEQUENCE (skipping minimality) nor bounds r/s only by the field size (missing
@@ -72,9 +72,9 @@ function ecdsaDerToP1363(der, curve, E, code) {
   if (n.tagClass !== "universal" || n.tagNumber !== asn1.TAGS.SEQUENCE || !n.children || n.children.length !== 2) {
     throw new E(code, "ECDSA signature must be a SEQUENCE of exactly two INTEGERs");
   }
-  // Wrap the strict DER integer reads (they enforce PRIMITIVE + MINIMAL encoding) so a non-minimal /
-  // constructed / empty INTEGER surfaces the CALLER's typed code, not a raw asn1/* -- the complete DER
-  // conformance rule set, gated together with the order bound below.
+  // Wrap the strict DER integer reads (they enforce primitive and minimal encoding) so a non-minimal,
+  // constructed or empty INTEGER surfaces the caller's typed code and not a raw asn1/*. That is the
+  // complete DER conformance rule set, gated together with the order bound below.
   var r, s;
   try { r = asn1.read.integer(n.children[0]); } catch (e) { throw new E(code, "ECDSA signature r is not a minimally-encoded DER INTEGER", e); }
   try { s = asn1.read.integer(n.children[1]); } catch (e) { throw new E(code, "ECDSA signature s is not a minimally-encoded DER INTEGER", e); }

package/lib/validator-tls.js

@@ -14,12 +14,12 @@
 // Every field is unsigned big-endian, packed with no padding, in the TLS presentation
 // language: `uintN` is a fixed-width integer and `opaque<min..max>` is a length prefix wide
 // enough for `max` followed by exactly that many bytes. The caller supplies its typed error
-// CONSTRUCTOR E (a validator takes a class -- `new E(code, msg)` -- where the guard family
+// constructor E (a validator takes a class, `new E(code, msg)`, where the guard family
 // takes a factory) plus the `codes` its domain uses for each fault.
 //
 // Rule set (verbatim against RFC 8879 sec. 4 and RFC 8446 sec. 4.4.2):
 //   - compressedCertificate: uint16 algorithm, uint24 uncompressed_length, then
-//     opaque compressed_certificate_message<1..2^24-1> -- the minimum of 1 makes an EMPTY
+//     opaque compressed_certificate_message<1..2^24-1>, where the minimum of 1 makes an empty
 //     compressed body a framing violation, which matters because the three decompressors do
 //     not agree on what empty input means. Bytes after the vector are rejected: one chain
 //     must have exactly one encoding.
@@ -34,19 +34,19 @@
 // codec's policy and stay with the codec.
 //
 // The RFC 8446 sec. 4.4.2 / sec. 4.2 rules that bind a Certificate-message DECODER, and where
-// each one lands -- enumerated so the ones deliberately NOT enforced are a recorded decision
-// rather than an oversight:
+// each one lands, enumerated so the ones deliberately left unenforced are a recorded decision
+// and not an oversight:
 //   ENFORCED here:
 //     - RawPublicKey carries at most one CertificateEntry (sec. 4.4.2).
 //     - No extension type appears twice in one extension block (sec. 4.2).
 //     - Every vector's framing, its declared minimum, and no trailing bytes at either level.
-//   NOT ENFORCED, deliberately:
+//   Not enforced, deliberately:
 //     - "The sender's certificate MUST come in the first CertificateEntry" is about which
 //       certificate a consumer treats as the leaf, not about framing. Entries are surfaced in
-//       wire order and never reordered, so the caller sees exactly what arrived -- and the same
+//       wire order and never reordered, so the caller sees exactly what arrived, and the same
 //       section tells implementations to tolerate extraneous certificates and arbitrary
 //       orderings beyond the first, so refusing any order here would be wrong.
-//     - "The server's certificate_list MUST always be non-empty" is conditioned on the SENDER's
+//     - "The server's certificate_list MUST always be non-empty" is conditioned on the sender's
 //       role: a client legitimately sends an empty list when it has no certificate to offer.
 //       This decoder has no role, so an empty list decodes to zero entries and the caller, which
 //       does know the role, decides.
@@ -54,7 +54,7 @@
 //       extension's own contents (a status_request body being a CertificateStatus) need the
 //       negotiation state and the extension's semantics. Neither exists here: extension values
 //       are surfaced raw.
-//     - The OpenPGP certificate type is unreachable rather than checked -- the only accepted
+//     - The OpenPGP certificate type is unreachable, not checked: the only accepted
 //       types are X509 and RawPublicKey, and anything else is refused at the entry point.
 
 var C = require("./constants");
@@ -78,8 +78,8 @@ function compressedCertificate(view, E, codes) {
   var r = new ByteReader(view, 0, view.length, E, codes.truncated);
   var algorithm = r.u16(codes.truncated);
   var uncompressedLength = r.u24(codes.truncated);
-  // opaque compressed_certificate_message<1..2^24-1> -- minimum 1, so an empty body is a
-  // framing violation rather than something a decompressor gets to interpret.
+  // opaque compressed_certificate_message<1..2^24-1>, minimum 1, so an empty body is a
+  // framing violation and not something a decompressor gets to interpret.
   var body = r.vector(3, 1, MAX_VECTOR_24, codes.framing);
   if (!r.atEnd()) {
     throw new E(codes.trailing, "the CompressedCertificate carries " + r.remaining() +
@@ -92,7 +92,7 @@ function compressedCertificate(view, E, codes) {
 // Extension a uint16 type plus a uint16-prefixed value, so the vector is a whole number of them and
 // the smallest is 4 bytes. Walking it is what keeps a malformed Certificate message from passing as
 // structurally valid: a one-byte vector cannot be an Extension, and accepting the bytes opaquely
-// would report it as well-formed. Each record's value is surfaced raw -- this decodes the framing,
+// would report it as well-formed. Each record's value is surfaced raw: this decodes the framing,
 // never the extension's own contents.
 function _extensionRecords(view, E, codes) {
   var r = new ByteReader(view, 0, view.length, E, codes.truncated);

package/lib/validator-tpm.js

@@ -112,7 +112,7 @@ function parsePubArea(buf, E, code) {
     throw new E(code, "unsupported TPMT_PUBLIC type 0x" + type.toString(16));
   }
   // TPMT_PUBLIC ends with `unique`; trailing bytes mean a malformed pubArea (and would
-  // perturb the TPM Name hash), so fail closed rather than silently ignore them.
+  // perturb the TPM Name hash), so the decode fails closed on them.
   if (!r.atEnd()) throw new E(code, "pubArea has trailing bytes after the unique field (WebAuthn 8.3)");
   return pub;
 }
@@ -148,7 +148,7 @@ function pubKeyEqualsCose(pub, cose, E, mismatchCode, code) {
     return;
   }
   if (pub.type === TPM_ALG.RSA) {
-    // Compare the exponent as an unsigned integer over its FULL width (a UINT32 up to
+    // Compare the exponent as an unsigned integer over its full width (a UINT32 up to
     // 0xFFFFFFFF); a fixed 3-byte re-encode would silently truncate an exponent > 0xFFFFFF
     // and let a mismatched key pass (WebAuthn 8.3 item 22).
     var e = _uintBytes(pub.exponent >>> 0);
@@ -161,7 +161,7 @@ function pubKeyEqualsCose(pub, cose, E, mismatchCode, code) {
 }
 
 // The one defined preset: the six TPMA_OBJECT bits every genuine attestation observed sets the same
-// way. `decrypt`, `noDA` and `userWithAuth` are deliberately absent -- they DIFFER across real
+// way. `decrypt`, `noDA` and `userWithAuth` are deliberately absent: they differ across real
 // Windows Hello statements, so requiring any of them rejects working hardware. A second preset
 // would be policy invention; a caller who wants different bits spells them out.
 var TPM_POLICY_PROFILES = Object.assign(Object.create(null), {
@@ -171,7 +171,7 @@ var _TPM_POLICY_KEYS = Object.assign(Object.create(null), { profile: 1, objectAt
 var _AUTH_POLICY_KEYS = Object.assign(Object.create(null), { present: 1, allow: 1 });
 
 // Config-time validation of opts.tpmPolicy: a typo must never silently disable a check, so an
-// unknown key or attribute name throws at the boundary rather than being ignored.
+// unknown key or attribute name throws at the boundary.
 // @enforced-by behavioral -- an opts-shape validator has no rename-proof code shape; the RED
 // vectors (unknown key, unknown profile, unknown attribute, non-boolean value, and the
 // sensitiveDataOrigin-without-fixedTPM rule) are the guard.
@@ -196,8 +196,8 @@ function normalizeObjectAttributePolicy(policy, E, code) {
     });
   }
   // sec. 8.3.3.5 NOTE 1: sensitiveDataOrigin only asserts the TPM generated the key when fixedTPM
-  // is also SET -- otherwise the object could have been imported. Demanding it alone asserts
-  // nothing, so say so at config time rather than letting a caller believe it is protected.
+  // is also SET; otherwise the object could have been imported. Demanding it alone asserts
+  // nothing, and a caller who thinks otherwise should hear it at config time.
   if (want.sensitiveDataOrigin === true && want.fixedTPM !== true) {
     throw new E(code, "opts.tpmPolicy requires sensitiveDataOrigin without fixedTPM; on its own it does not establish that the TPM generated the key (TPM 2.0 Part 2 sec. 8.3.3.5)");
   }
@@ -215,15 +215,16 @@ function normalizeObjectAttributePolicy(policy, E, code) {
     if (ap.present !== undefined && typeof ap.present !== "boolean") throw new E(code, "opts.tpmPolicy.authPolicy.present must be a boolean");
     if (ap.allow !== undefined) {
       if (!Array.isArray(ap.allow)) throw new E(code, "opts.tpmPolicy.authPolicy.allow must be an array");
-      // Decode every entry HERE, at config time, rather than inside the comparison. Node's hex
-      // decoder is permissive: it stops at the first character that is not a hex digit, so
-      // "<digest>zz" decodes back to the digest and a non-string decodes to an empty buffer --
-      // either of which could match a key this policy was written to exclude, including the
+      // Every entry is decoded here, at config time, so the comparison only ever sees bytes.
+      // Node's hex decoder is permissive: it stops at the first character that is not a hex
+      // digit, so "<digest>zz" decodes back to the digest and a non-string decodes to an empty
+      // buffer. Either could match a key this policy was written to exclude, including the
       // Empty Policy. An entry that is not a Buffer or a canonical even-length hex string is a
-      // caller error, and it fails here rather than becoming a digest nobody intended.
-      // Through guard.encoding.hex, which owns the alphabet, the even-length rule and the
-      // canonical round-trip -- the same three checks written here by hand, and now written
-      // once. It also decodes, so the hex path cannot validate one string and decode another.
+      // caller error; it fails here, before it can become a digest nobody intended.
+      // The decoding runs through guard.encoding.hex, which owns the alphabet, the even-length
+      // rule and the canonical round-trip. Those three checks were once written out here by hand
+      // and now live in one place. It also decodes, so the hex path cannot validate one string
+      // and decode another.
       allow = ap.allow.map(function (entry, i) {
         if (Buffer.isBuffer(entry)) return guard.bytes.snapshot(entry, E, code, "opts.tpmPolicy.authPolicy.allow[" + i + "]");
         var label = "opts.tpmPolicy.authPolicy.allow[" + i + "]";
@@ -240,8 +241,8 @@ function normalizeObjectAttributePolicy(policy, E, code) {
     authPolicy: ap ? { present: ap.present === true, allow: allow } : null };
 }
 
-// Apply a normalized policy to a parsed pubArea. Nothing here is a WebAuthn sec. 8.3 requirement --
-// that section constrains only pubArea's `parameters` and `unique` fields -- so every rule runs
+// Apply a normalized policy to a parsed pubArea. Nothing here is a WebAuthn sec. 8.3 requirement,
+// since that section constrains only pubArea's `parameters` and `unique` fields. Every rule runs
 // only because a caller asked for it by name.
 // @enforced-by behavioral -- an opt-gated policy gate has no rename-proof code shape, and there is
 // no general vector shape to detect: the RED vectors (each required bit in both directions, the
@@ -251,7 +252,7 @@ function assertObjectAttributePolicy(pub, policy, E, policyCode, structuralCode)
   if (!policy) return;
   var oa = pub.objectAttributes >>> 0;
   // Bit 31 lies inside the reserved mask, so the AND must be coerced back to unsigned: a bare
-  // `oa & 0xfff0f009` is a signed int32 and would read negative rather than "a bit is set".
+  // `oa & 0xfff0f009` is a signed int32, and a negative result would not read as "a bit is set".
   if (policy.reservedBitsClear && ((oa & TPMA_OBJECT_RESERVED) >>> 0) !== 0) {
     throw new E(structuralCode, "the TPMT_PUBLIC objectAttributes sets a reserved bit (TPM 2.0 Part 2 sec. 8.3.2 Table 33: shall be zero)");
   }
@@ -271,8 +272,8 @@ function assertObjectAttributePolicy(pub, policy, E, policyCode, structuralCode)
     if (pub.authPolicy.length > 64) {
       throw new E(structuralCode, "the TPMT_PUBLIC authPolicy is " + pub.authPolicy.length + " octets, above the 64-octet TPM2B_DIGEST maximum");
     }
-    // The REMAINING sec. 8.3.3 "shall" statements are all parent-relative -- fixedTPM, stClear and
-    // encryptedDuplication are each constrained against the value the object's PARENT carries. An
+    // The remaining sec. 8.3.3 "shall" statements are all parent-relative. fixedTPM, stClear and
+    // encryptedDuplication are each constrained against the value the object's parent carries. An
     // attestation presents one public area and no parent, so a verifier cannot evaluate them at
     // all; they are not omitted by oversight, they are unverifiable from what is on the wire.
   }