@blamejs/pki 0.4.8 → 0.4.10

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.10 — 2026-08-09
+
+A TPM attestation now reports the credential key's own object attributes and access policy, so a relying party can require the properties it cares about -- a key bound to one TPM, generated by that TPM, not duplicable -- instead of taking the attestation on trust.
+
+### Added
+
+- A verified TPM attestation reports the credential key's object attributes as named flags, the raw attribute word, and the key's access-policy digest. Previously both fields were read past and discarded, so a relying party that wanted to know whether the key was bound to its TPM had to re-parse the public area itself.
+- opts.tpmPolicy requires any of those attributes by name, in either direction -- an attribute may be required set or required clear -- and refuses the attestation naming which one disagreed. A single profile, hardware-bound, is the shorthand for the six attributes every genuine attestation examined agrees on: the key is bound to one TPM and one parent, the TPM generated it, it can sign, and it is neither a restricted key nor an X.509 signing key. An explicit attribute layers over the profile, so one flag can be overridden without losing the rest. Three attributes are deliberately absent from it, because they differ across genuine authenticators and requiring any of them would reject working hardware.
+- The policy also covers the key's access policy: requiring that one is present at all rather than the empty policy, and requiring it to be one of an allow-list of digests, compared in constant time. Two structural opt-ins are available for callers who want them: rejecting an attribute word that sets a bit the specification reserves, and rejecting attribute combinations the specification does not define.
+- A mistyped policy is refused when it is set, not ignored: an unknown key at any level, an unknown profile, an unknown attribute name, a non-boolean value, or an allow-list entry that is not a certificate digest all fail immediately, so a typo can never silently disable the check a caller believes they enabled. Names that every JavaScript object inherits are not accepted as policy names either, since a lookup would otherwise report them as recognised and leave the policy applying nothing. Requiring that the TPM generated the key without also requiring the key be non-duplicable is refused for the same reason -- on its own it establishes nothing, because the key could have been imported.
+- Requesting a TPM policy also requires an attestation that can satisfy it. The policy is evaluated against the TPM public area, which only a TPM attestation carries, so an attestation in any other format would never reach it -- a relying party that demanded a TPM-bound key would have accepted a credential with no attestation at all. Such a request is now refused up front, naming the format, and a compound attestation qualifies only when it actually contains a TPM statement.
+
+### Fixed
+
+- Calendar dates without a time are now read through the same strict reader as full timestamps, rejecting a date that does not exist rather than rolling it into the following month the way the language would. A day such as the thirtieth of February is refused instead of silently becoming the second of March, and a parsed date is anchored to UTC so a freshness or expiry comparison does not shift with the host's time zone.
+
+## v0.4.9 — 2026-08-08
+
+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/rfc3339.js

@@ -41,4 +41,31 @@ function parse(v, E, code, label) {
   return new Date(v);
 }
 
-module.exports = { isValid: isValid, parse: parse };
+// RFC 3339 sec. 5.6 `full-date`: a calendar date with NO time component. A distinct production from
+// the date-time above, and deliberately a separate pair of functions rather than a flag: a consumer
+// that expects one and is handed the other has a malformed value, not a permissible variant.
+var FULL_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+// isValidDate(v) -> boolean: v is a syntactically well-formed AND calendar-valid RFC 3339 full-date.
+// Calendar validity matters as much as shape -- "2021-02-30" parses as a Date in JS by rolling over
+// into March, so a shape-only check would silently accept a day that does not exist.
+function isValidDate(v) {
+  if (typeof v !== "string") return false;
+  var m = FULL_DATE_RE.exec(v);
+  if (!m) return false;
+  var year = +m[1], month = +m[2], day = +m[3];
+  if (month < 1 || month > 12) return false;
+  var leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  var daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day >= 1 && day <= daysInMonth[month - 1];
+}
+
+// parseDate(v, E, code, label) -> Date at UTC midnight. Anchored explicitly at UTC ("T00:00:00Z")
+// rather than left to `new Date("YYYY-MM-DD")`, so the instant does not shift with the host time
+// zone -- a freshness or rollback comparison must not depend on where it runs.
+function parseDate(v, E, code, label) {
+  if (!isValidDate(v)) throw E(code, (label || "the value") + " is not a valid RFC 3339 full-date (YYYY-MM-DD)");
+  return new Date(v + "T00:00:00Z");
+}
+
+module.exports = { isValid: isValid, parse: parse, isValidDate: isValidDate, parseDate: parseDate };

package/lib/validator-tpm.js

@@ -27,6 +27,7 @@
 //     coordinate by a leading 0x00), the RSA exponent over its full UINT32 width.
 
 var ByteReader = require("./byte-reader");
+var guard = require("./guard-all");
 
 var TPM_GENERATED_VALUE = 0xff544347;
 var TPM_ST_ATTEST_CERTIFY = 0x8017;
@@ -52,15 +53,47 @@ function _symDef(r) { if (r.u16() !== TPM_ALG.NULL) { r.u16(); r.u16(); } }
 // UINT16 hashAlg) follows for the signing/kdf schemes in scope.
 function _scheme(r) { if (r.u16() !== TPM_ALG.NULL) { r.u16(); } }
 
+// TPMA_OBJECT bit positions (TPM 2.0 Part 2 sec. 8.3.2, Table 33). A data row set, not a switch:
+// a bit index absent here is reserved by definition, and the reserved mask below is its complement
+// over the positions Table 33 marks "shall be zero" (bits 0, 3, 15:12 and 31:20).
+// Null-prototype: every one of these tables is indexed by a CALLER-SUPPLIED name, and an inherited
+// member ("constructor", "toString", "__proto__") would resolve to a truthy non-value. In a lookup
+// that decides whether a name is known, that reads as "known" and the caller's policy silently
+// applies nothing at all -- a fail-open. Applied to all three tables here, not only the one where
+// it was noticed.
+var TPMA_OBJECT_BITS = Object.assign(Object.create(null), {
+  fixedTPM: 1, stClear: 2, fixedParent: 4, sensitiveDataOrigin: 5, userWithAuth: 6,
+  adminWithPolicy: 7, firmwareLimited: 8, svnLimited: 9, noDA: 10,
+  encryptedDuplication: 11, restricted: 16, decrypt: 17, sign: 18, x509sign: 19,
+});
+var TPMA_OBJECT_RESERVED = 0xfff0f009;
+
+// _decodeAttributes(oa) -> the named booleans of a TPMA_OBJECT word.
+// @enforced-by behavioral -- a bit-position table lookup has no rename-proof code shape; the RED
+// vectors (each named bit read off a real attestation, and the sign-bit case) are the guard.
+function _decodeAttributes(oa) {
+  var out = {};
+  Object.keys(TPMA_OBJECT_BITS).forEach(function (n) { out[n] = ((oa >>> TPMA_OBJECT_BITS[n]) & 1) === 1; });
+  return out;
+}
+
 // parsePubArea(buf, E, code) -> the decoded TPMT_PUBLIC (WebAuthn 8.3 item 17-20).
 // @enforced-by behavioral -- a packed TPM structure decode has no rename-proof code shape;
 // the RED vectors (trailing bytes, an unsupported type, a truncated TPM2B) are the guard.
 function parsePubArea(buf, E, code) {
   var r = new ByteReader(buf, 0, buf.length, E, code);
   var type = r.u16(), nameAlg = r.u16();
-  r.u32();                       // objectAttributes (full policy validation deferred)
-  r.vector(2, 0, null);          // authPolicy TPM2B_DIGEST
-  var pub = { type: type, nameAlg: nameAlg, nameAlgBytes: buf.subarray(2, 4) };
+  // objectAttributes (TPM 2.0 Part 2 sec. 8.3.2 Table 33) and authPolicy (Table 87) are SURFACED,
+  // not gated: WebAuthn sec. 8.3 constrains only the `parameters` and `unique` fields of pubArea,
+  // so enforcing these would invent a conformance rule. A relying party that wants them applies its
+  // own policy, which it cannot do to a field it never sees. The bytes are trustworthy by the time
+  // a caller reads them -- pubArea is hashed into certInfo.attested.name, which the AIK signature
+  // covers, and both are verified before the result is built.
+  var objectAttributes = r.u32();
+  var authPolicy = r.vector(2, 0, null);   // a zero-length digest IS the Empty Policy, not "absent"
+  var pub = { type: type, nameAlg: nameAlg, nameAlgBytes: buf.subarray(2, 4),
+    objectAttributes: objectAttributes >>> 0, attributes: _decodeAttributes(objectAttributes),
+    authPolicy: authPolicy };
   if (type === TPM_ALG.RSA) {
     _symDef(r);                  // symmetric TPMT_SYM_DEF_OBJECT
     _scheme(r);                  // scheme TPMT_RSA_SCHEME
@@ -127,8 +160,148 @@ function pubKeyEqualsCose(pub, cose, E, mismatchCode, code) {
   throw new E(code, "unsupported TPM pubArea key type");
 }
 
+// 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
+// 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), {
+  "hardware-bound": { fixedTPM: true, fixedParent: true, sensitiveDataOrigin: true, sign: true, restricted: false, x509sign: false },
+});
+var _TPM_POLICY_KEYS = Object.assign(Object.create(null), { profile: 1, objectAttributes: 1, reservedBitsClear: 1, consistency: 1, authPolicy: 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.
+// @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.
+function normalizeObjectAttributePolicy(policy, E, code) {
+  if (policy === undefined) return null;
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) throw new E(code, "opts.tpmPolicy must be an object");
+  Object.keys(policy).forEach(function (k) {
+    if (!_TPM_POLICY_KEYS[k]) throw new E(code, "opts.tpmPolicy has an unknown key " + JSON.stringify(k));
+  });
+  var want = {};
+  if (policy.profile !== undefined) {
+    var preset = TPM_POLICY_PROFILES[policy.profile];
+    if (!preset) throw new E(code, "opts.tpmPolicy.profile " + JSON.stringify(policy.profile) + " is not a defined profile");
+    Object.keys(preset).forEach(function (n) { want[n] = preset[n]; });
+  }
+  // An explicit map layers OVER the preset, so a caller can keep the profile and override one bit.
+  var explicit = policy.objectAttributes;
+  if (explicit !== undefined) {
+    if (!explicit || typeof explicit !== "object" || Array.isArray(explicit)) throw new E(code, "opts.tpmPolicy.objectAttributes must be an object");
+    Object.keys(explicit).forEach(function (n) {
+      if (TPMA_OBJECT_BITS[n] === undefined) throw new E(code, "opts.tpmPolicy.objectAttributes has an unknown attribute " + JSON.stringify(n));
+      if (typeof explicit[n] !== "boolean") throw new E(code, "opts.tpmPolicy.objectAttributes." + n + " must be a boolean");
+      want[n] = explicit[n];
+    });
+  }
+  // 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.
+  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)");
+  }
+  ["reservedBitsClear", "consistency"].forEach(function (k) {
+    if (policy[k] !== undefined && typeof policy[k] !== "boolean") throw new E(code, "opts.tpmPolicy." + k + " must be a boolean");
+  });
+  var ap = policy.authPolicy;
+  var allow = null;
+  if (ap !== undefined) {
+    if (!ap || typeof ap !== "object" || Array.isArray(ap)) throw new E(code, "opts.tpmPolicy.authPolicy must be an object");
+    // The nested keys are enumerated for the same reason the top-level ones are: a misspelled
+    // `alow` would leave the allow-list unset, and the assertion would then impose no digest
+    // restriction at all -- the caller's policy silently doing nothing.
+    Object.keys(ap).forEach(function (k) {
+      if (k !== "present" && k !== "allow") throw new E(code, "opts.tpmPolicy.authPolicy has an unknown key " + JSON.stringify(k));
+    });
+    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
+      // 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.
+      allow = ap.allow.map(function (entry, i) {
+        if (Buffer.isBuffer(entry)) return entry;
+        if (typeof entry !== "string" || entry.length === 0 || entry.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(entry)) {
+          throw new E(code, "opts.tpmPolicy.authPolicy.allow[" + i + "] must be a Buffer or an even-length hex string");
+        }
+        return Buffer.from(entry, "hex");
+      });
+    }
+  }
+  return { objectAttributes: want, reservedBitsClear: policy.reservedBitsClear === true,
+    consistency: policy.consistency === true,
+    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
+// 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
+// reserved-bit mask across the sign bit, the restricted sign+decrypt combination, the over-long
+// digest, the Empty Policy, and the allow-list miss) are the guard.
+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".
+  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)");
+  }
+  if (policy.consistency) {
+    // sec. 8.3.3.11, verbatim: "This attribute shall not be SET in any object that has fixedTPM
+    // SET." A key that cannot leave its TPM cannot be duplicated, so requiring its duplication be
+    // encrypted describes an object that cannot exist.
+    if (pub.attributes.encryptedDuplication && pub.attributes.fixedTPM) {
+      throw new E(structuralCode, "the TPMT_PUBLIC objectAttributes sets encryptedDuplication on an object with fixedTPM SET (TPM 2.0 Part 2 sec. 8.3.3.11)");
+    }
+    // sec. 8.3.3.16/.17: a restricted key is a TPM-internal key, and the two use bits are a choice
+    // -- a restricted object that both signs and decrypts is not a defined combination.
+    if (pub.attributes.sign && pub.attributes.decrypt && pub.attributes.restricted) {
+      throw new E(structuralCode, "the TPMT_PUBLIC objectAttributes sets restricted with both sign and decrypt (TPM 2.0 Part 2 sec. 8.3.3)");
+    }
+    // A TPM2B_DIGEST carries at most a SHA-512 digest.
+    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
+    // 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.
+  }
+  Object.keys(policy.objectAttributes).forEach(function (name) {
+    var want = policy.objectAttributes[name];
+    if (pub.attributes[name] !== want) {
+      throw new E(policyCode, "the TPM credential key has " + name + " " + (pub.attributes[name] ? "SET" : "CLEAR") +
+        "; opts.tpmPolicy requires it " + (want ? "SET" : "CLEAR"));
+    }
+  });
+  var ap = policy.authPolicy;
+  if (!ap) return;
+  if (ap.present === true && pub.authPolicy.length === 0) {
+    throw new E(policyCode, "the TPM credential key carries the Empty Policy; opts.tpmPolicy.authPolicy.present requires a policy digest");
+  }
+  if (ap.allow) {
+    // Every entry was decoded and validated at config time, so this compares digests only.
+    var got = pub.authPolicy;
+    var ok = ap.allow.some(function (want) {
+      return want.length === got.length && guard.crypto.constantTimeEqual(want, got);
+    });
+    if (!ok) throw new E(policyCode, "the TPM credential key authPolicy is not in opts.tpmPolicy.authPolicy.allow");
+  }
+}
+
 module.exports = {
   parsePubArea: parsePubArea,
+  TPMA_OBJECT_BITS: TPMA_OBJECT_BITS,
+  decodeObjectAttributes: _decodeAttributes,
+  normalizeObjectAttributePolicy: normalizeObjectAttributePolicy,
+  assertObjectAttributePolicy: assertObjectAttributePolicy,
   parseCertInfo: parseCertInfo,
   pubKeyEqualsCose: pubKeyEqualsCose,
   TPM_ALG_HASH: TPM_ALG_HASH,

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); }
@@ -479,7 +500,10 @@ var VERIFIERS = {
 
   // tpm (WebAuthn 8.3): decode certInfo/pubArea, enforce magic/type/extraData/Name,
   // bind pubArea to the credential key, and verify sig over certInfo with the AIK.
-  tpm: function (att, clientDataHash) {
+  tpm: function (att, clientDataHash, opts) {
+    // Config-time: a malformed or mistyped tpmPolicy is a caller error, caught before any parsing so
+    // a typo cannot silently disable the check the caller believes they enabled.
+    var tpmPolicy = validator.tpm.normalizeObjectAttributePolicy((opts || {}).tpmPolicy, WebauthnError, "webauthn/bad-input");
     _requireAttShape(att.attStmt, ["ver", "alg", "sig", "certInfo", "pubArea", "x5c"], ["ver", "alg", "sig", "certInfo", "pubArea", "x5c"]);
     var verN = cbor.read.mapGet(att.attStmt, "ver");
     if (!verN || verN.majorType !== 3 || cbor.read.textString(verN) !== "2.0") throw _err("webauthn/bad-att-stmt", "tpm attestation 'ver' MUST be \"2.0\" (WebAuthn 8.3)");
@@ -516,7 +540,15 @@ var VERIFIERS = {
       if (!ok) throw _err("webauthn/verify-failed", "the tpm attestation signature does not verify over certInfo under the AIK");
       _checkAikCert(aik);   // 8.3.1
       _checkAaguidExt(aik, att.authData.aaguid);   // 8.3.1: aaguid ext, if present, MUST match
-      return _result("tpm", "AttCA", chain, att);
+      // The TPMT_PUBLIC object attributes and authPolicy are properties of the credential key that
+      // sec. 8.3 does not constrain -- it bounds only pubArea's `parameters` and `unique`. They are
+      // surfaced for relying-party policy, and gated only when the caller supplies opts.tpmPolicy.
+      // Applied AFTER the signature and Name checks, so the bytes being judged are ones the AIK
+      // signature already covers rather than attacker-chosen input.
+      validator.tpm.assertObjectAttributePolicy(pub, tpmPolicy, WebauthnError, "webauthn/tpm-policy", "webauthn/bad-tpm");
+      var tpmRes = _result("tpm", "AttCA", chain, att);
+      tpmRes.tpm = { objectAttributes: pub.objectAttributes, attributes: pub.attributes, authPolicy: pub.authPolicy };
+      return tpmRes;
     });
   },
 
@@ -572,6 +604,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 +669,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).
@@ -789,9 +887,29 @@ function verify(attestationObject, clientDataHash, opts) {
   }
   var verifier = VERIFIERS[att.fmt];
   if (!verifier) return Promise.reject(_err("webauthn/unsupported-format", "attestation statement format '" + att.fmt + "' is not supported"));
+  // A policy about TPM key properties is checked INSIDE the tpm arm, so an attestation in any other
+  // format would never reach it and the policy would silently apply to nothing -- a caller who
+  // demanded a TPM-bound key would accept a `none` attestation instead. The requirement therefore
+  // belongs at the dispatch, where it can refuse a format that cannot satisfy it, not in the arm
+  // that only runs once that format was already chosen.
+  if (opts.tpmPolicy !== undefined && !_formatCanSatisfyTpmPolicy(att)) {
+    return Promise.reject(_err("webauthn/tpm-policy", "opts.tpmPolicy requires a TPM attestation, but this attestation is format '" + att.fmt + "', which carries no TPM public area"));
+  }
   return Promise.resolve().then(function () { return verifier(att, clientDataHash, opts); });
 }
 
+// Only an attestation that actually carries a TPM public area can satisfy a TPM policy: the tpm
+// format directly, or a compound holding at least one tpm element (whose own arm applies it).
+function _formatCanSatisfyTpmPolicy(att) {
+  if (att.fmt === "tpm") return true;
+  if (att.fmt !== "compound") return false;
+  return (att.attStmt.children || []).some(function (el) {
+    if (!el || el.majorType !== 5) return false;
+    var fN = cbor.read.mapGet(el, "fmt");
+    return !!fN && fN.majorType === 3 && cbor.read.textString(fN) === "tpm";
+  });
+}
+
 void constants;
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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:d2b1e2eb-a5be-45c0-b69c-dd481476df78",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-08T23:49:55.172Z",
+    "timestamp": "2026-08-09T03:25:40.339Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.4.8",
+      "bom-ref": "@blamejs/pki@0.4.10",
       "type": "application",
       "name": "pki",
-      "version": "0.4.8",
+      "version": "0.4.10",
       "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.10",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.4.8",
+      "ref": "@blamejs/pki@0.4.10",
       "dependsOn": []
     }
   ]