@blamejs/pki 0.4.8 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.4.9 — 2026-08-09
+
+A WebAuthn compound attestation now verifies -- every nested statement must pass, so a wrapper cannot launder a failed attestation behind one that succeeds -- and the certificate chains an attestation carries are bounded by count, not only by size.
+
+### Added
+
+- pki.webauthn.verify verifies the compound attestation format, which it previously refused as unsupported. Every nested statement must verify for the attestation to verify -- the specification leaves the threshold to relying-party policy, and this is the fail-closed reading of it. The result reports attestation type Compound and carries each element's own verdict, attestation type and certificate chain in order, so a caller applies its own policy to the parts rather than to a merged verdict that could overstate or understate any of them. The combined trust path is empty by construction: several elements produce several independent chains, and presenting them as one ordered path would misrepresent what was validated.
+- The nested statements are held to the format's own syntax: at least two of them, each exactly a format identifier and a statement, each identifier matched case-sensitively against the supported set, and none of them compound -- the specification spells that exclusion out, so nesting is impossible by construction rather than by a depth counter. Which CBOR shape a statement takes is now a property of the format rather than a fixed rule, so accommodating the array-shaped compound statement leaves every other format's contract unchanged, and a compound presented in the older map shape is refused.
+
+### Fixed
+
+- The number of certificates an attestation may carry is now bounded. Both the attestation statement's certificate array and a JSON Web Signature certificate header capped the size of each certificate but not how many there were, so a statement could present thousands of small certificates and each one cost a parse and, downstream, a full path validation -- work far out of proportion to the bytes on the wire. A single bound now covers every place a chain arrives, set well above any real attestation chain.
+
 ## v0.4.8 — 2026-08-08
 
 A stored android-safetynet WebAuthn attestation can be re-verified in full -- the signature, the registration binding, and the certificate chain -- behind an opt-in and against a root the caller supplies.

package/lib/constants.js

@@ -297,6 +297,19 @@ var LIMITS = {
   // terminates but exhausts memory. This matches PATH_MAX_CERTS: a chain longer than the path
   // validator will ever accept has nothing to offer, so refusing it at the decoder is free.
   TLS_CERT_MAX_ENTRIES: 100,
+  // The most nested statements a WebAuthn compound attestation (sec. 8.9) may carry. The syntax
+  // says "2*" -- unbounded -- so this is a resource bound this toolkit chooses, NOT a spec MUST.
+  // The CBOR parse caps bound the decode; they do not bound the crypto, and each element costs a
+  // signature verification plus, for some formats, a full certificate-path validation. Seven
+  // non-compound formats are registered, so a conforming statement carrying one of each is 7.
+  WEBAUTHN_COMPOUND_MAX_STATEMENTS: 16,
+  // The most certificates a WebAuthn attestation chain may carry, in an attStmt x5c array or a JWS
+  // x5c header. A real attestation chain is one to four; the byte ceiling on a single entry does
+  // not bound the COUNT, so an array of thousands of small certificates is an unbounded parse and
+  // signature-check fanout (CWE-770) that terminates but costs far more CPU than wire. This is a
+  // resource bound this toolkit chooses -- no specification states it -- and it is far tighter than
+  // PATH_MAX_CERTS because an attestation chain is not a general PKI path.
+  WEBAUTHN_X5C_MAX_CERTS: 10,
   // A WebAuthn android-safetynet attestation statement carries the SafetyNet response as a JWS
   // compact serialization: two small JSON objects plus a signature, with the certificate chain
   // inline in the header. Real ones run a few kilobytes. The cap bounds the text decode before the

package/lib/webauthn.js

@@ -8,8 +8,9 @@
  * @intro Trust evaluation of a W3C WebAuthn (Level 3) / passkey attestation: parse
  *   the attestation object + authenticatorData, decode the COSE credential public
  *   key, and verify each defined attestation-statement format (packed, tpm,
- *   android-key, apple, fido-u2f, none, and android-safetynet behind an opt-in) --
- *   the attestation-statement signature and each format's structural bindings. The attestation CBOR is decoded by the strict,
+ *   android-key, apple, fido-u2f, none, compound, and android-safetynet behind an
+ *   opt-in) -- the attestation-statement signature and each format's structural
+ *   bindings. The attestation CBOR is decoded by the strict,
  *   fail-closed `pki.cbor` codec (WebAuthn keys are CTAP2-canonical), the signature by
  *   `pki.webcrypto`. Chaining the returned x5c trust path to a caller-pinned root via
  *   `pki.path.validate` is the caller's step: this module verifies the statement, not
@@ -327,11 +328,16 @@ function parseAttestationObject(bytes) {
   // (WebAuthn 6.5.4); an extra top-level key is a non-canonical envelope, rejected.
   if (root.children.length !== 3 || !fmtN || !attStmtN || !authDataN) throw _err("webauthn/bad-attestation-object", "the attestation object must be exactly { fmt, attStmt, authData }");
   if (fmtN.majorType !== 3) throw _err("webauthn/bad-attestation-object", "attestation object 'fmt' must be a text string");
-  // attStmt is the attestation statement, a CBOR map keyed by field name (WebAuthn 6.5.4);
-  // a non-map attStmt is a malformed attestation OBJECT, rejected here rather than deferred
-  // to a format verifier -- a non-map value (e.g. a CBOR array, whose children are single
-  // nodes, not { key, value } pairs) must never reach the per-field statement walk.
-  if (attStmtN.majorType !== 5) throw _err("webauthn/bad-attestation-object", "attestation object 'attStmt' must be a CBOR map");
+  // attStmt is the attestation statement, a CBOR map keyed by field name (WebAuthn 6.5.4) for every
+  // format but one: sec. 8.9 gives compound an ARRAY of nested statements. Which shape a format
+  // takes is a registry row, not a branch, so adding a format cannot silently widen the envelope
+  // for the others -- a non-map value (whose children are single nodes, not { key, value } pairs)
+  // must never reach the per-field statement walk of a format that expects a map.
+  var wantMajor = ATT_STMT_MAJOR[cbor.read.textString(fmtN)];
+  if (wantMajor === undefined) wantMajor = 5;
+  if (attStmtN.majorType !== wantMajor) {
+    throw _err("webauthn/bad-attestation-object", "attestation object 'attStmt' must be a CBOR " + (wantMajor === 4 ? "array" : "map") + " for format " + JSON.stringify(cbor.read.textString(fmtN)));
+  }
   if (authDataN.majorType !== 2) throw _err("webauthn/bad-attestation-object", "attestation object 'authData' must be a byte string");
   var authDataBytes = cbor.read.byteString(authDataN);
   return {
@@ -377,9 +383,24 @@ function _requireAttShape(attStmt, allowed, required) {
   Object.keys(have).forEach(function (k) { if (allowed.indexOf(k) === -1) throw _err("webauthn/bad-att-stmt", "the attestation statement carries an unexpected field '" + k + "'"); });
   required.forEach(function (k) { if (!have[k]) throw _err("webauthn/bad-att-stmt", "the attestation statement is missing the '" + k + "' field"); });
 }
+// The CBOR major type each format's attStmt takes. Every format uses a map (5) except compound,
+// whose sec. 8.9 syntax is an array of nested statements. A data row rather than a branch, so a
+// future format declares its shape here instead of loosening the shared envelope check.
+var ATT_STMT_MAJOR = { compound: 4 };
+
+// One bound for every attestation certificate chain, wherever it arrives from -- an attStmt x5c
+// array or a JWS x5c header. Capping the bytes of a single entry does not bound the COUNT, and the
+// cost of an entry is a DER parse plus, downstream, a signature check or a path validation. Kept in
+// one place so a new chain-bearing format cannot reintroduce the unbounded fanout.
+function _requireX5cCount(n) {
+  if (n > constants.LIMITS.WEBAUTHN_X5C_MAX_CERTS) {
+    throw _err("webauthn/bad-att-stmt", "an attestation certificate chain carries " + n + " certificates, above the " + constants.LIMITS.WEBAUTHN_X5C_MAX_CERTS + " this toolkit will parse");
+  }
+}
 function _readX5c(attStmt) {
   var x5cN = cbor.read.mapGet(attStmt, "x5c");
   if (!x5cN || x5cN.majorType !== 4 || !x5cN.children || !x5cN.children.length) throw _err("webauthn/bad-att-stmt", "x5c must be a non-empty array of certificates");
+  _requireX5cCount(x5cN.children.length);
   return x5cN.children.map(function (c) {
     var der;
     try { der = cbor.read.byteString(c); } catch (e) { throw _err("webauthn/bad-att-stmt", "an x5c entry must be a byte string", e); }
@@ -572,6 +593,7 @@ var VERIFIERS = {
     if (!Array.isArray(header.x5c) || header.x5c.length === 0) {
       throw _err("webauthn/bad-att-stmt", "the android-safetynet JWS header carries no x5c certificate chain (RFC 7515 sec. 4.1.6)");
     }
+    _requireX5cCount(header.x5c.length);
     // x5c entries are STANDARD base64 (RFC 7515 sec. 4.1.6), not base64url like the segments.
     var chain = header.x5c.map(function (entry, i) {
       if (typeof entry !== "string") throw _err("webauthn/bad-att-stmt", "the android-safetynet x5c entry " + i + " is not a string");
@@ -636,6 +658,71 @@ var VERIFIERS = {
     });
   },
 
+  // compound (WebAuthn 8.9): the attStmt is an ARRAY of nested attestation statements, each
+  // verified over the SAME authenticatorData and clientDataHash as the outer object. sec. 8.9
+  // leaves the acceptance threshold to relying-party policy ("if validation fails for one or more
+  // subStmt, decide the appropriate result based on RP policy"); this toolkit's policy is
+  // fail-closed -- EVERY element must verify, because accepting a compound whose strong element
+  // failed and whose `none` element passed would let a wrapper launder a failed attestation.
+  compound: function (att, clientDataHash, opts) {
+    var kids = att.attStmt.children || [];
+    // sec. 8.9 syntax `2*`: at least two nested statements, or it is not a compound.
+    if (kids.length < 2) throw _err("webauthn/bad-att-stmt", "a compound attestation statement must carry at least two nested statements (WebAuthn 8.9)");
+    // Not a spec rule: a resource bound this toolkit chooses. The CBOR caps bound the PARSE; they
+    // do not bound the crypto, and each element costs a signature verify plus, for some formats, a
+    // certificate-chain path validation.
+    if (kids.length > constants.LIMITS.WEBAUTHN_COMPOUND_MAX_STATEMENTS) {
+      throw _err("webauthn/bad-att-stmt", "a compound attestation statement carries " + kids.length + " nested statements, above the " + constants.LIMITS.WEBAUTHN_COMPOUND_MAX_STATEMENTS + " this toolkit will verify");
+    }
+    var elements = kids.map(function (el, i) {
+      // sec. 8.9: nonCompoundAttStmt = { $$attStmtType } -- each element is exactly { fmt, attStmt }.
+      if (!el || el.majorType !== 5) throw _err("webauthn/bad-att-stmt", "compound element " + i + " must be a CBOR map { fmt, attStmt } (WebAuthn 8.9)");
+      var fN = cbor.read.mapGet(el, "fmt"), sN = cbor.read.mapGet(el, "attStmt");
+      if (el.children.length !== 2 || !fN || !sN) throw _err("webauthn/bad-att-stmt", "compound element " + i + " must be exactly { fmt, attStmt } (WebAuthn 8.9)");
+      if (fN.majorType !== 3) throw _err("webauthn/bad-att-stmt", "compound element " + i + " 'fmt' must be a text string");
+      var f = cbor.read.textString(fN);
+      // sec. 8.9 spells the element type `.ne "compound"`: nesting is forbidden by the syntax
+      // itself, which is what fixes the evaluation depth at one. No depth parameter is needed --
+      // and adding one would imply a nesting this format does not have.
+      if (f === "compound") throw _err("webauthn/bad-att-stmt", "a compound attestation statement must not nest another compound (WebAuthn 8.9)");
+      // sec. 8.1: identifiers match case-sensitively, which the registry lookup already is.
+      var v = VERIFIERS[f];
+      if (!v) throw _err("webauthn/unsupported-format", "compound element " + i + " uses unsupported attestation statement format '" + f + "'");
+      var wantMajor = ATT_STMT_MAJOR[f] === undefined ? 5 : ATT_STMT_MAJOR[f];
+      if (sN.majorType !== wantMajor) throw _err("webauthn/bad-att-stmt", "compound element " + i + " 'attStmt' has the wrong CBOR shape for format '" + f + "'");
+      // Each element verifies against the OUTER authenticatorData: sec. 8.9 passes the same
+      // verification-procedure inputs down, so an element cannot bind a different credential.
+      return { fmt: f, index: i, att: { fmt: f, attStmt: sN, authData: att.authData, authDataBytes: att.authDataBytes } };
+    });
+    // Sequential, not Promise.all: a compound may hold many elements, and each can cost a
+    // signature verify plus a full path validation. Fanning them out concurrently would turn one
+    // attestation into a burst of crypto work.
+    var out = [];
+    return elements.reduce(function (p, e) {
+      return p.then(function () {
+        // The verifier is CALLED inside the promise chain, not evaluated as an argument to
+        // Promise.resolve: most arms do their structural checks synchronously, so an argument-
+        // position call would let those throws escape the handler below and reach the caller
+        // bare -- the same failure reported with the element's context or without it, depending
+        // only on whether it happened before or after the first await.
+        return Promise.resolve().then(function () { return VERIFIERS[e.fmt](e.att, clientDataHash, opts); })
+          .then(function (r) { out.push(r); }, function (err) {
+            throw _err("webauthn/compound-element-failed", "compound element " + e.index + " (format '" + e.fmt + "') did not verify", err);
+          });
+      });
+    }, Promise.resolve()).then(function () {
+      // sec. 8.9 lists the supported attestation type as "Any" and authorises returning
+      // "implementation-specific values representing any combination of outputs". A distinct type
+      // rather than a merge: collapsing to the strongest element would let a wrapper upgrade a
+      // caller's attestationType check, and collapsing to the weakest would spuriously fail one.
+      // The trust path is empty because two elements yield two independent chains and there is no
+      // single ordered path -- each element's own path is on its entry in `compound`.
+      var res = _result("compound", "Compound", [], att);
+      res.compound = out;
+      return res;
+    });
+  },
+
   // none (WebAuthn 8.7): the authenticator provides no attestation. attStmt MUST be
   // an empty map; there is no statement to verify, so the result carries no trust
   // path. The credential public key still binds via authenticatorData (AT flag).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:4a21ad89-1930-46c8-811e-74c422b23db6",
+  "serialNumber": "urn:uuid:1f0429a5-9e2b-4cc8-a67f-6357968a0774",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-08T23:49:55.172Z",
+    "timestamp": "2026-08-09T01:33:39.618Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.4.8",
+      "bom-ref": "@blamejs/pki@0.4.9",
       "type": "application",
       "name": "pki",
-      "version": "0.4.8",
+      "version": "0.4.9",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.4.8",
+      "purl": "pkg:npm/%40blamejs/pki@0.4.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.4.8",
+      "ref": "@blamejs/pki@0.4.9",
       "dependsOn": []
     }
   ]