@blamejs/pki 0.6.13 → 0.6.15

package/lib/validator-all.js

@@ -1,37 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. This is lib composition only; the
-// documented surface is the primitives whose type handling composes these validators.
-//
-// 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 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
-//                                     -- the COMPLETE WebAuthn credential COSE_Key rule
-//                                        set (RFC 9052/9053 + WebAuthn sec. 6.5.1 +
-//                                        CTAP2 canonical + on-curve), one home
-//   validator.sig.ecdsaDerToP1363     -- the COMPLETE order-aware DER ECDSA-Sig-Value
-//                                        conformance (RFC 3279 + X.690 strict-DER +
-//                                        FIPS 186-5 [1,n-1], CVE-2022-21449) + raw r||s
-//   validator.attcert.packedCert / .aikCert / .aaguidExt / .requireV3 / .assertNotCa
-//                                     -- the WebAuthn attestation-certificate profile
-//                                        (sec. 8.2.1 packed, sec. 8.3.1 TPM AIK), one home
-//   validator.keydesc.androidKeyDescription
-//                                     -- the Android Key Attestation KeyDescription
-//                                        (AOSP schema + WebAuthn sec. 8.4.1), one home
-//   validator.tpm.parsePubArea / .parseCertInfo / .pubKeyEqualsCose
-//                                     -- the TPM 2.0 pubArea/certInfo structure conformance
-//                                        + key binding (WebAuthn sec. 8.3 + TCG Part 2), one home
-//
-// Each validator is enforced by the validator-reinlined codebase-patterns detector: a
-// lib function that re-inlines a type's characteristic validation shape (declared on the
+// @internal
 // validator via @validator-shape) is flagged, so a new format module cannot re-derive a
-// partial subset and reintroduce the drift the validator exists to prevent.
 
 var cose = require("./validator-cose");
 var sig = require("./validator-sig");

package/lib/validator-attcert.js

@@ -1,62 +1,27 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the verifier whose
-// attestation-certificate handling composes this validator (pki.webauthn).
-//
-// validator-attcert -- the SINGLE home for "does this X.509 leaf meet the WebAuthn
-// 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. The version
-// check belongs to the profile, not to whichever verifier reaches it first.
-//
-// The caller supplies its parsed certificate + an extension-accessor object `exts`
-// { find(cert, oidName) -> rawExt|null, decode(cert, oidName) -> {critical, value}|null }
-// so this validator stays decoupled from any one format's extension-decoder namespace, and
-// its typed error CONSTRUCTOR E + domain code (a distinct mismatchCode for aaguidExt).
-//
-// Rule set (gap-checked verbatim against WebAuthn sec. 8.2.1 + sec. 8.3.1 + RFC 5280):
-//   - requireV3:  the leaf MUST be X.509 v3 (packed 8.2.1, AIK 8.3.1).
-//   - assertNotCa: the leaf MUST carry basicConstraints with cA=FALSE (present, not merely
-//     "not cA=true": a genuine CA or unconstrained leaf must not be repurposed as a leaf).
-//   - packedCert: v3 + non-CA + subject sets C, O, OU="Authenticator Attestation", CN.
-//   - aikCert:    v3 + non-CA + EMPTY subject + EKU contains tcg-kp-AIKCertificate + SAN
-//     directoryName carries tpmManufacturer/tpmModel/tpmVersion (TPMv2-EK-Profile 3.2.9).
-//   - aaguidExt:  the id-fido-gen-ce-aaguid extension, if present, MUST NOT be critical and
-//     MUST equal the authenticatorData aaguid (a 16-byte OCTET STRING inside the ext OCTET
-//     STRING). Absence is tolerated; presence must match.
+// @internal
 
 var oid = require("./oid");
 var asn1 = require("./asn1-der");
 var guard = require("./guard-all");
 
-// Does this extended-key-usage list assert the given purpose? The answer decides whether a
-// certificate qualifies as the kind the rule names, so it goes through the membership guard
-// instead of a prototype method. See guard-list.
 var _asserts = guard.list.contains;
 
-// requireV3(cert, E, code) -- the leaf attestation certificate MUST be X.509 v3.
 // @enforced-by behavioral -- a version-field check has no rename-proof code shape; the RED
-// vector (a non-v3 attestation leaf rejected) is the guard.
 function requireV3(cert, E, code) {
   if (cert.version !== 3) throw new E(code, "an attestation certificate must be X.509 version 3");
 }
 
-// assertNotCa(cert, exts, E, code) -- the leaf MUST carry basicConstraints with cA=FALSE.
 // @enforced-by behavioral -- a basicConstraints cA gate has no rename-proof code shape; the
-// RED vector (a CA-asserting or constraint-omitting attestation leaf rejected) is the guard.
 function assertNotCa(cert, exts, E, code) {
   var bc = exts.decode(cert, "basicConstraints");
   if (!bc) throw new E(code, "an attestation leaf certificate MUST carry a basicConstraints extension (WebAuthn 8.2.1 / 8.3.1)");
   if (bc.value && bc.value.cA === true) throw new E(code, "an attestation leaf certificate MUST NOT be a CA (basicConstraints cA=true)");
 }
 
-// packedCert(cert, exts, E, code) -- the complete WebAuthn 8.2.1 packed attestation-cert
-// profile (v3 + non-CA + the four subject attributes).
 // @enforced-by behavioral -- the subject-attribute + OU-literal checks are WebAuthn 8.2.1
-// business rules with no rename-proof code shape; the RED vectors (missing C/O/CN, wrong OU,
-// CA=true, non-v3) are the guard.
 function packedCert(cert, exts, E, code) {
   requireV3(cert, E, code);
   assertNotCa(cert, exts, E, code);
@@ -70,18 +35,12 @@ function packedCert(cert, exts, E, code) {
   }
 }
 
-// aikCert(cert, exts, E, code) -- the complete WebAuthn 8.3.1 TPM AIK attestation-cert
-// profile (v3 + non-CA + empty subject + tcg-kp-AIKCertificate EKU + the tcg SAN attributes).
 // @enforced-by behavioral -- the empty-subject + EKU + SAN-attribute checks are WebAuthn
-// 8.3.1 business rules with no rename-proof code shape; the RED vectors are the guard.
 function aikCert(cert, exts, E, code) {
   requireV3(cert, E, code);
   assertNotCa(cert, exts, E, code);
   if ((cert.subject.rdns || []).length !== 0) throw new E(code, "the tpm AIK certificate subject MUST be empty (WebAuthn 8.3.1)");
   var eku = exts.decode(cert, "extKeyUsage");
-  // The purpose test IS the rule that makes this an AIK certificate, so it is decided by comparison
-  // rather than by a prototype method: a replaced `indexOf` reports the purpose present on any
-  // certificate and an ordinary leaf is accepted as a TPM attestation key.
   if (!eku || !Array.isArray(eku.value) || !_asserts(eku.value, oid.byName("tcgKpAikCertificate"))) {
     throw new E(code, "the tpm AIK certificate lacks the tcg-kp-AIKCertificate extended key purpose (WebAuthn 8.3.1)");
   }
@@ -96,13 +55,10 @@ function aikCert(cert, exts, E, code) {
   }
 }
 
-// aaguidExt(cert, aaguid, exts, E, code, mismatchCode) -- the id-fido-gen-ce-aaguid
-// extension, if present, MUST NOT be critical and MUST equal the authenticatorData aaguid.
 // @enforced-by behavioral -- an optional-extension equality check has no rename-proof code
-// shape; the RED vectors (a critical ext, a non-matching aaguid) are the guard.
 function aaguidExt(cert, aaguid, exts, E, code, mismatchCode) {
   var ext = exts.find(cert, "idFidoGenCeAaguid");
-  if (!ext) return;   // absence is tolerated; presence must match
+  if (!ext) return;
   if (ext.critical) throw new E(code, "the id-fido-gen-ce-aaguid extension MUST NOT be critical (WebAuthn 8.2.1)");
   var val;
   try { val = asn1.read.octetString(asn1.decode(ext.value)); }

package/lib/validator-cose.js

@@ -1,44 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// verifiers whose credential-key handling composes this validator (pki.webauthn).
-//
-// validator-cose -- the SINGLE home for "is this a conformant WebAuthn credential
-// COSE_Key" (RFC 9052 sec. 7 structure + RFC 9053 EC2/OKP/RSA key parameters + the
-// CTAP2 canonical-CBOR profile WebAuthn sec. 6.5.1 imposes). Sibling to the guard
-// family: where a guard owns a CVE-class fail-closed defense once, a validator owns a
-// decoded TYPE's COMPLETE conformance rule set once, so a format module composes the
-// 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.
-//
-// Interface mirrors the guard family: (subject, E, code) where E is the caller's typed
-// error CONSTRUCTOR and code its domain code, so every boundary keeps its own
-// domain/reason (a future COSE consumer passes its own E + code).
-//
-// 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, 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
-//     size. OKP (kty 1): crv (-1) == Ed25519(6)/Ed448(7), x (-2) length == the key size.
-//     RSA (kty 3): n (-1), e (-2) present + non-empty.
-//   - 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 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
-//     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.
+// @internal
 
 var cbor = require("./cbor-det");
 var asn1 = require("./asn1-der");
@@ -46,56 +9,27 @@ var oid = require("./oid");
 var edwardsPoint = require("./edwards-point");
 var nodeCrypto = require("crypto");
 
-// COSE EC2 curve (label -1) -> the fixed field-element byte length x/y carry, and the
-// named-curve OID a certificate on that curve declares.
-var EC2_CRV_LEN = { 1: 32, 2: 48, 3: 66 };   // P-256 / P-384 / P-521
+var EC2_CRV_LEN = { 1: 32, 2: 48, 3: 66 };
 var EC2_CRV_OID = { 1: "prime256v1", 2: "secp384r1", 3: "secp521r1" };
-// COSE OKP curve (label -1) -> its RFC 8410 named-key OID + fixed public-key length.
 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 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
-// NIST SP 800-57 agree on; nothing in the field emits less, so the floor refuses forgeable keys
-// without refusing real ones. The exponent bound is a work bound, not a security one.
 var RSA_MIN_MODULUS_BITS = 2048;
 var RSA_MAX_EXPONENT_BYTES = 8;
-// The modulus BIT length. A byte count is not one: minimally encoded, a 256-byte modulus whose
-// leading byte is 0x01 is 2041 bits, and would clear a floor expressed in bytes while sitting below
-// the floor that floor exists to state. The leading byte is non-zero by the minimal-encoding check
-// above, so its position fixes the total.
 function _modulusBits(n) { return (n.length - 1) * 8 + (32 - Math.clz32(n[0])); }
 
 var ALG_PROFILE = {
   "-7": { kty: 2, crv: 1 }, "-35": { kty: 2, crv: 2 }, "-36": { kty: 2, crv: 3 },
   "-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 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 },
 };
 
-// credentialKey(node, E, code) -> the decoded + validated credential public key
-// { kty, alg, crv?, x?, y?, n?, e? }, or throws new E(code, ...). The complete COSE_Key
-// conformance gate for a WebAuthn credential key; a format module MUST route a credential
-// key through here, never re-inline the kty/alg/crv/length/canonical/profile/on-curve
-// checks.
 // @enforced-by validator-shape-reinlined
 // @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
-// 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
-  // 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); } }
   var ktyN = cbor.read.mapGet(node, 1), algN = cbor.read.mapGet(node, 3);
@@ -107,8 +41,6 @@ function credentialKey(node, E, code, unsupportedCode) {
   var key = { kty: Number(kty), alg: Number(algv) };
   if (kty === 2n) {
     key.crv = ii(-1) != null ? Number(ii(-1)) : null;
-    // WebAuthn EC2 credential keys MUST use the uncompressed point form: y (-3) is the full
-    // y-coordinate byte string, never a CBOR bool sign bit (WebAuthn sec. alg identifier).
     var yNode = cbor.read.mapGet(node, -3);
     if (yNode && yNode.majorType === 7) throw bad("an EC2 credential key must use the uncompressed point form (a compressed y sign-bit is not permitted for WebAuthn)");
     key.x = ib(-2); key.y = ib(-3);
@@ -122,19 +54,6 @@ 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 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
-    // 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
-    // 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)");
     if (key.e[0] === 0) throw bad("an RSA COSE_Key exponent (-2) must be minimally encoded, with no leading zero byte (RFC 8230 sec. 4)");
     var modulusBits = _modulusBits(key.n);
@@ -142,67 +61,24 @@ function credentialKey(node, E, code, unsupportedCode) {
       throw bad("an RSA COSE_Key modulus (-1) is " + modulusBits + " bits, below the " +
         RSA_MIN_MODULUS_BITS + "-bit minimum");
     }
-    // e must be odd and greater than 1: RSA needs gcd(e, phi(n)) = 1, so an even exponent is not a
-    // valid RSA public exponent at all, and 1 is the degenerate case above. Bounded on the way in
-    // 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
-    // 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");
   } else {
     throw bad("unsupported COSE_Key kty " + Number(kty));
   }
-  // CANONICAL CTAP2 COSE_Key: exactly the type's parameters, nothing more.
   var expectedParams = kty === 2n ? 5 : 4;
   if (node.children.length !== expectedParams) throw bad("the COSE_Key carries parameters beyond the canonical set for its key type (WebAuthn sec. 6.5.1)");
   return assertKeyMaterial(key, E, code, unsupportedCode);
 }
 
-// assertKeyMaterial(key, E, code, unsupportedCode) -> key | throws
-//
-// The rules about the KEY, split from the rules about its CBOR encoding, because the
-// toolkit accepts a stored credential key in two forms and both reach a signature
-// verification. `pki.webauthn.verifyAssertion` takes the COSE bytes or the object
-// `pki.webauthn.verify` returned; the bytes went through every check below and the
-// object went through none, so the same 1-byte modulus was refused as a credential key
-// in one form and imported for verification in the other. A caller stores whichever
-// 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
-// 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
-//   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.
-  //
-  // 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 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. 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;
@@ -211,11 +87,6 @@ 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
-  // 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.
   key.kty = Number(key.kty);
   key.alg = Number(key.alg);
   if (key.crv !== undefined && key.crv !== null) key.crv = Number(key.crv);
@@ -239,41 +110,21 @@ function assertKeyMaterial(key, E, code, unsupportedCode) {
   } 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 neighboring 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 behavior.
   if (!prof) throw new E(unsupportedCode || code, "unsupported credential key algorithm " + key.alg);
   if (prof.kty !== key.kty) throw bad("credential key algorithm " + key.alg + " is inconsistent with key type " + key.kty);
   if (prof.crv != null && prof.crv !== key.crv) throw bad("credential key algorithm " + key.alg + " requires a different curve");
-  // ON-CURVE: import the SPKI so OpenSSL validates the EC point on its curve. An off-curve
-  // 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
-  // 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;
 }
 
-// toSpki(key, E, code) -> a self-contained SubjectPublicKeyInfo DER for a validated COSE
-// key, so a credential key and a certificate key import/compare by one path.
 // @enforced-by behavioral -- an SPKI encoding of a validated COSE key has no rename-proof
-// code shape distinct from the ecPublicKey/rsaEncryption OID-name tokens that legitimately
-// recur in the oid registry + inspect renderer; its consumers route through
-// validatorCose.toSpki and credentialKey calls it on the on-curve path, so the webauthn
-// KAT round-trip (a real SPKI imports + verifies) is the behavioral guard.
 function toSpki(key, E, code) {
   function bad(msg) { return new E(code, msg); }
   if (key.kty === 2 && key.x && key.y) {
     var curveOid = EC2_CRV_OID[key.crv];
-    // Coverage residual -- toSpki only receives a credentialKey-validated key; EC2 crv is
-    // already gated to {1,2,3} by EC2_CRV_LEN, the exact EC2_CRV_OID keyset, so curveOid is
-    // always defined.
     if (!curveOid) throw bad("unsupported EC2 curve " + key.crv);
     var b = asn1.build;
     return b.sequence([
@@ -292,8 +143,6 @@ function toSpki(key, E, code) {
     var eb = asn1.build;
     return eb.sequence([eb.sequence([eb.oid(oid.byName(OKP_CRV[key.crv].oid))]), eb.bitString(key.x)]);
   }
-  // Coverage residual -- a credentialKey-validated key always matches one of the three forms
-  // above; this fallthrough is defensive depth.
   throw bad("cannot build an SPKI for this COSE key type");
 }
 

package/lib/validator-keydesc.js

@@ -1,35 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the verifier whose
-// android-key handling composes this validator (pki.webauthn).
-//
-// validator-keydesc -- the SINGLE home for the Android Key Attestation KeyDescription
-// conformance (the AOSP key-attestation schema + WebAuthn sec. 8.4.1 authorization-list
-// checks). Sibling to the guard family: a validator owns a decoded TYPE's COMPLETE
-// conformance rule set once, so the four 8.4.1 checks cannot lose a gate to drift.
-//
-// The caller supplies its parsed certificate + an extension-accessor `exts`
-// { find(cert, oidName) -> rawExt|null } + its typed error CONSTRUCTOR E with two codes: a
-// STRUCTURAL `code` (a malformed KeyDescription is bad input) and a semantic `failCode` (a
-// well-formed description that fails an 8.4.1 MUST is a failed verification).
-//
-// Rule set (gap-checked verbatim against WebAuthn sec. 8.4.1 + the AOSP KeyDescription
-// schema):
-//   - KeyDescription is a positional SEQUENCE; attestationChallenge (position 4) MUST equal
-//     clientDataHash.
-//   - 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.
+// @internal
 
 var asn1 = require("./asn1-der");
 
-// The EXPLICIT-unwrapped value node for a [tag] field of an AuthorizationList (a SEQUENCE
-// of context-tagged OPTIONAL fields with non-contiguous tag numbers), or null when absent.
 function _alGet(seqNode, tag) {
   if (!seqNode || !seqNode.children) return null;
   for (var i = 0; i < seqNode.children.length; i++) {
@@ -53,33 +28,22 @@ function _purposeUnion(a, b, E, code) {
   return out;
 }
 
-// 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
-// WebAuthn 8.4.1 business rules with no rename-proof code shape; the RED vectors (challenge
-// mismatch, allApplications present, origin != GENERATED, purpose != SIGN, and the empty-
-// authorization-list spec vector) are the guard.
 function androidKeyDescription(cert, clientDataHash, exts, E, code, failCode) {
   var ext = exts.find(cert, "keyDescription");
   if (!ext) throw new E(code, "the android-key attestation certificate is missing the key-description extension (WebAuthn 8.4.1)");
   var kd;
   try { kd = asn1.decode(ext.value); } catch (e) { throw new E(code, "the android KeyDescription is not decodable", e); }
   if (!kd.children || kd.children.length < 8) throw new E(code, "the android KeyDescription is not a positional 8-field SEQUENCE");
-  // (1) attestationChallenge (position 4) == clientDataHash.
   var challenge;
   try { challenge = asn1.read.octetString(kd.children[4]); } catch (e) { throw new E(code, "the android attestationChallenge is not an OCTET STRING", e); }
   if (!challenge.equals(clientDataHash)) throw new E(failCode, "the android attestationChallenge does not equal clientDataHash");
   var softwareEnforced = kd.children[6], hardwareEnforced = kd.children[7];
-  // (2) [600] allApplications MUST be ABSENT in both lists.
   if (_alGet(softwareEnforced, 600) || _alGet(hardwareEnforced, 600)) throw new E(failCode, "android allApplications MUST be absent (WebAuthn 8.4.1)");
-  // (3) origin == KM_ORIGIN_GENERATED (0) over the union: at least one list declares it,
-  // and every list that declares one says GENERATED.
   var origins = [_alGet(softwareEnforced, 702), _alGet(hardwareEnforced, 702)].filter(Boolean);
   if (!origins.length || !origins.every(function (o) { return _alInt(o, E, code) === 0n; })) {
     throw new E(failCode, "android key origin is not KM_ORIGIN_GENERATED in every authorization list that declares it (WebAuthn 8.4.1)");
   }
-  // (4) purpose == exactly { KM_PURPOSE_SIGN (2) } over the union.
   var purposes = _purposeUnion(softwareEnforced, hardwareEnforced, E, code);
   if (purposes.length !== 1 || purposes[0] !== 2n) {
     throw new E(failCode, "android key purpose is not exactly KM_PURPOSE_SIGN (WebAuthn 8.4.1)");

package/lib/validator-sig.js

@@ -1,38 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the verifiers
-// whose ECDSA signature handling composes this validator (pki.webauthn).
-//
-// 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 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 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.
+// @internal
 
 var asn1 = require("./asn1-der");
 
-// rawToEcdsaDer(raw, coordLen) -> the canonical DER ECDSA-Sig-Value SEQUENCE { r, s } for a raw
-// r||s signature (IEEE P1363, the WebCrypto sign() output). The inverse of ecdsaDerToP1363: a
-// signer composes this so the emitted ECDSA signature is canonical DER (minimally-encoded
-// INTEGERs via the build layer), never a hand-built SEQUENCE that could re-introduce a
-// non-minimal encoding. A config-time TypeError guards a mis-sized raw signature at entry.
 // @enforced-by behavioral -- a DER ECDSA-Sig-Value BUILD has no rename-proof code shape distinct
-// from generic sequence([integer,integer]); the round-trip vectors (build -> ecdsaDerToP1363
-// identity) and the cms.sign ECDSA KATs are the guard.
 function rawToEcdsaDer(raw, coordLen) {
   if (!Buffer.isBuffer(raw) || typeof coordLen !== "number" || coordLen <= 0 || raw.length !== coordLen * 2) {
     throw new TypeError("rawToEcdsaDer: raw signature must be a Buffer of exactly 2*coordLen bytes");
@@ -42,7 +15,6 @@ function rawToEcdsaDer(raw, coordLen) {
   return asn1.build.sequence([asn1.build.integer(r), asn1.build.integer(s)]);
 }
 
-// The curve group orders n -- a valid ECDSA signature has r, s in [1, n-1].
 var CURVE_FIELD_BYTES = { "P-256": 32, "P-384": 48, "P-521": 66 };
 var CURVE_ORDER = {
   "P-256": BigInt("0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551"),
@@ -50,18 +22,7 @@ var CURVE_ORDER = {
   "P-521": BigInt("0x01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409"),
 };
 
-// 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
-// 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
-// the order). A non-minimal, negative, zero, over-size, or >= n coordinate fails closed.
 // @enforced-by behavioral -- a DER ECDSA-Sig-Value decode has no rename-proof code shape distinct
-// from generic 2-child-SEQUENCE content access; the RED conformance vectors (r/s = 0, r/s >= n,
-// non-minimal, negative, over-size) and the cms / ct / composite / path / webauthn ECDSA KATs are
-// the guard.
 function ecdsaDerToP1363(der, curve, E, code) {
   var width = CURVE_FIELD_BYTES[curve];
   var order = CURVE_ORDER[curve];
@@ -72,9 +33,6 @@ 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 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); }
@@ -85,9 +43,6 @@ function ecdsaDerToP1363(der, curve, E, code) {
     var hex = v.toString(16);
     if (hex.length % 2) hex = "0" + hex;
     var buf = Buffer.from(hex, "hex");
-    // Coverage residual -- unreachable: a component needing more than `width` bytes is >=
-    // 2^(8*width) > n (the curve order n < 2^(8*width) for P-256/384/521), so it is already
-    // rejected by the r/s >= order check above; this width guard is a defense-in-depth backstop.
     if (buf.length > width) throw new E(code, "ECDSA signature component wider than the curve field");
     var out = Buffer.alloc(width);
     buf.copy(out, width - buf.length);