@blamejs/pki 0.4.9 → 0.4.11

package/lib/webauthn.js

@@ -35,6 +35,7 @@ var edwardsPoint = require("./edwards-point");
 var guard = require("./guard-all");
 var jose = require("./jose");
 var pathValidate = require("./path-validate");
+var mds = require("./webauthn-mds");
 var nodeCrypto = require("crypto");
 
 var WebauthnError = frameworkError.WebauthnError;
@@ -388,6 +389,23 @@ function _requireAttShape(attStmt, allowed, required) {
 // future format declares its shape here instead of loosening the shared envelope check.
 var ATT_STMT_MAJOR = { compound: 4 };
 
+// Which attestation formats put the AAGUID under their signature. A registry row rather than a
+// branch, so adding a format forces the question to be answered for it rather than inheriting the
+// permissive default. Every format signs over authenticatorData (which contains the AAGUID) except
+// fido-u2f, whose sec. 8.6 verificationData is assembled from named fields and omits it.
+// The question is asked PER FORMAT, and answered for the element being judged -- never once for a
+// whole statement. A compound mixes formats, and a single answer would be wrong in both directions:
+// it would either trust a u2f element's unsigned AAGUID, or refuse to look a packed element up by
+// the very AAGUID its own signature covers.
+var _AAGUID_SIGNED_BY_FMT = Object.assign(Object.create(null), { "fido-u2f": false });
+function _aaguidIsSigned(fmt) { return _AAGUID_SIGNED_BY_FMT[fmt] !== false; }
+
+// The options pki.webauthn.verify recognises. Null-prototype, so a caller-supplied key cannot
+// resolve to an inherited Object member and read as recognised.
+var _VERIFY_OPTS = Object.assign(Object.create(null), {
+  time: 1, metadata: 1, tpmPolicy: 1, safetyNetRoots: 1, verifySafetyNetJws: 1, requireCtsProfileMatch: 1,
+});
+
 // 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
@@ -500,7 +518,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)");
@@ -537,7 +558,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;
     });
   },
 
@@ -562,7 +591,10 @@ var VERIFIERS = {
     if (!Array.isArray(roots) || roots.length === 0) {
       throw _err("webauthn/safetynet-no-root", "verifying an android-safetynet attestation requires opts.safetyNetRoots -- the Google root(s) to anchor the x5c chain to; this library bundles none (WebAuthn 8.5)");
     }
-    if (opts.time !== undefined) guard.time.assertValid(opts.time, WebauthnError, "webauthn/bad-input", "opts.time");
+    // The guard rejects through a (code, message) FACTORY. Handing it the error CLASS makes the
+    // reject path raise "class constructor cannot be invoked without new" -- a raw, untyped throw
+    // escaping a public verb, on the branch a valid-input test never takes.
+    if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
 
     // 8.5 attStmt syntax: safetynetStmtFormat = { ver: text, response: bytes }. `ver` is READ but
     // never gated on -- 8.5 states it is reserved for future use.
@@ -624,6 +656,10 @@ var VERIFIERS = {
     // specification does not state. They are relying-party policy, so they are surfaced on the result
     // for a caller to act on, and enforced here only when the caller explicitly asks. A caller that
     // asks and finds them missing or false gets a refusal, never a silent pass.
+    // The instant the service chain is judged at, resolved below once the signature has authenticated
+    // the timestamp it comes from, and carried out on the result so a later check of the same path
+    // uses the same one rather than resetting to the current clock.
+    var chainAt;
     var signals = {
       ctsProfileMatch: payload.ctsProfileMatch, basicIntegrity: payload.basicIntegrity,
       timestampMs: payload.timestampMs, apkPackageName: payload.apkPackageName,
@@ -646,14 +682,18 @@ var VERIFIERS = {
       // signature just verified under the leaf, so it is authenticated rather than caller-asserted.
       // Precedence: an explicit opts.time (the caller knows when the registration happened) beats
       // the signed timestamp, which beats now (a response that carries no usable timestamp).
-      var at = opts.time !== undefined ? opts.time
+      chainAt = opts.time !== undefined ? opts.time
         : (typeof payload.timestampMs === "number" && isFinite(payload.timestampMs) && payload.timestampMs > 0
           ? new Date(payload.timestampMs) : undefined);
-      return _safetyNetChainTrusted(chain, roots, at);
+      return _safetyNetChainTrusted(chain, roots, chainAt);
     }).then(function () {
       // 8.5 bullet 5: attestation type Basic, trust path x5c.
       var res = _result("android-safetynet", "Basic", chain, att);
       res.safetyNet = signals;
+      // The instant this chain was judged at, surfaced so any later check of the SAME path uses the
+      // same one. A stored response's service chain has usually expired by now, and re-validating
+      // it against the current clock would refuse a registration that was valid when it was made.
+      if (chainAt !== undefined) res.chainValidatedAt = chainAt;
       return res;
     });
   },
@@ -790,7 +830,12 @@ function _safetyNetChainTrusted(chain, roots, time) {
       }
       return pathValidate.validate(path, {
         time: when,
-        trustAnchor: { name: anchorCert.subject, publicKey: anchorCert.subjectPublicKeyInfo.bytes, algorithm: anchorCert.signatureAlgorithm.oid },
+        // The anchor's own KEY algorithm and its parameters, not the algorithm its issuer signed it
+        // with: the validator carries these forward as the working public key, and a certificate
+        // below the anchor may inherit its key parameters from them.
+        trustAnchor: { name: anchorCert.subject, publicKey: anchorCert.subjectPublicKeyInfo.bytes,
+          algorithm: anchorCert.subjectPublicKeyInfo.algorithm.oid,
+          parameters: anchorCert.subjectPublicKeyInfo.algorithm.parameters },
       }).then(function (r) { return !!(r && r.valid); }, function () { return false; });
     };
   });
@@ -848,10 +893,11 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *   certInfo Name/extraData, the android KeyDescription, the fido-u2f verificationData).
  *   Chaining the returned `trustPath` (the x5c certificates in `pki.path.validate`
  *   order -- anchor-adjacent first, leaf last) to a trusted root is the caller's
- *   step: anchor it with `pki.path.validate` against roots you pin. Resolving an
- *   authenticator's root from its aaguid via the FIDO Metadata Service, plus the
- *   chain-to-anchor call, are not built in yet -- re-open when the caller supplies an
- *   explicit trusted-root set or a FIDO MDS BLOB (`opts.mdsBlob`) to bind the path.
+ *   step. Two ways to take it: anchor the path with `pki.path.validate` against roots
+ *   you pin, or pass `opts.metadata` -- a `pki.webauthn.verifyMetadataBlob` result --
+ *   and the authenticator's registered attestation roots are resolved from its aaguid
+ *   and the trust path is required to reach one, so an unlisted or revoked model is
+ *   refused rather than reported as verified.
  *
  * @example
  *   var res = await pki.webauthn.verify(attestationObject, clientDataHash, {});
@@ -861,6 +907,16 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  */
 function verify(attestationObject, clientDataHash, opts) {
   opts = opts || {};
+  // Every option here either GATES the verdict or supplies the trust material a gate needs, so a
+  // misspelled key is not a harmless no-op: `metdata` leaves the metadata gate switched off and the
+  // call returns a pass the caller believes was checked against the catalogue. Reject an
+  // unrecognised key at the boundary, and validate the one shared option every arm reads, so a bad
+  // instant is a config fault here rather than a trust failure reported from deep inside a chain.
+  try {
+    if (!_isPlainObject(opts)) throw _err("webauthn/bad-input", "opts must be an object");
+    guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "webauthn/bad-input", "opts has an unknown key ");
+    if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+  } catch (e) { return Promise.reject(e); }
   if (!Buffer.isBuffer(clientDataHash) || clientDataHash.length !== 32) {
     return Promise.reject(_err("webauthn/bad-input", "clientDataHash must be a 32-byte SHA-256 digest"));
   }
@@ -876,12 +932,265 @@ 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"));
-  return Promise.resolve().then(function () { return verifier(att, clientDataHash, opts); });
+  // 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); })
+    .then(function (res) { return opts.metadata === undefined ? res : _applyMetadata(res, att, opts); });
+}
+
+// WebAuthn sec. 7.1 step 22-23: having verified the attestation, look the authenticator model up in
+// the metadata and require its trust path to chain to one of the roots that model is registered
+// with. The metadata must be a verifyMetadataBlob RESULT, never raw bytes -- accepting bytes here
+// would let an unverified BLOB decide which roots are acceptable, which is the whole question.
+function _applyMetadata(res, att, opts) {
+  var md = opts.metadata;
+  // Provenance, not shape: only a catalogue this toolkit actually verified may decide which roots
+  // an authenticator is allowed to chain to. Recognising it by its property names would accept a
+  // hand-built object, or one restored from a cache an attacker can write -- neither of which has
+  // been through the signature and chain checks that give the catalogue its authority.
+  if (!mds.isVerifiedResult(md)) {
+    throw _err("webauthn/bad-input", "opts.metadata must be a pki.webauthn.verifyMetadataBlob result, not a raw BLOB");
+  }
+  // A compound attestation (sec. 8.9) deliberately carries an EMPTY top-level trust path, because
+  // its elements yield independent chains with no single ordered path -- each element's own path is
+  // on its entry in `compound`. Treating that empty path as "nothing to anchor" would refuse every
+  // compound attestation outright, including ones whose certificate-bearing elements all chain to
+  // the model's registered roots. So the paths to check are the elements'.
+  // Each path travels WITH the format that produced it, because the format is what decides which
+  // identifier may name its entry -- and a compound mixes formats. A compound's elements are
+  // independent claims: a packed element's AAGUID is signed while a fido-u2f element's is not, so a
+  // single choice for the whole statement is wrong in both directions. It would push the packed
+  // element down the certificate-identifier path (where a conforming entry indexed only by its
+  // AAGUID is not found), or trust the u2f element's unsigned AAGUID.
+  var paths = (res.fmt === "compound" && Array.isArray(res.compound))
+    ? res.compound.filter(function (el) { return el.trustPath && el.trustPath.length; })
+      .map(function (el) { return { tp: el.trustPath, fmt: el.fmt, at: el.chainValidatedAt }; })
+    : (res.trustPath && res.trustPath.length ? [{ tp: res.trustPath, fmt: res.fmt, at: res.chainValidatedAt }] : []);
+  // An attestation with no trust path at all (`none`, or a self-attestation) has nothing to anchor,
+  // so a caller who asked for metadata enforcement must be told it could not be applied rather than
+  // receiving a pass that looks like it was.
+  if (!paths.length) {
+    throw _err("webauthn/metadata-not-applicable", "opts.metadata was supplied, but this attestation carries no trust path to anchor (format '" + res.fmt + "')");
+  }
+  // The catalogue's two key spaces are DISJOINT, and which one applies is decided by what the
+  // authenticator declares -- never by trying one and falling back to the other. An authenticator
+  // that declares a signed model identity is looked up by it and by nothing else, so a model the
+  // catalogue does not list is refused instead of being resolved out of the U2F key space under
+  // some other authenticator's entry.
+  var aaguid = mds.aaguidToString(att.authData.aaguid);
+  // The aaguid may only select the entry when the attestation SIGNATURE covers it. For fido-u2f it
+  // does not -- sec. 8.6 signs 0x00 || rpIdHash || clientDataHash || credentialId || publicKeyU2F,
+  // which excludes the field entirely -- so those 16 bytes are attacker-editable. Trusting them
+  // there does not merely misreport a model: setting them to a LISTED model that shares the
+  // vendor's registered root makes the forged statement resolve to that model's entry, skipping the
+  // real U2F entry's own key-identifier lookup and, with it, its status reports. A revoked
+  // authenticator would present itself as its healthy sibling. So for that format the certificate
+  // key identifier decides, whatever the field says.
+  // Every path is resolved and enforced against ITS OWN entry, by the identifier ITS OWN format
+  // allows. A compound carries independent claims and its element order is not signed, so choosing
+  // one entry for the whole statement would let that order decide whose status report is consulted:
+  // a healthy element listed first would suppress a revoked sibling's report while both still
+  // anchor successfully. Each path answers for itself, and all of them must pass.
+  var applied = [];
+  function govern(info) {
+    var tp = info.tp;
+    var declared = _aaguidIsSigned(info.fmt) && aaguid && aaguid !== mds.ZERO_AAGUID;
+    var entry, identifier;
+    if (declared) {
+      entry = mds.metadataFor(md, aaguid);
+      identifier = "aaguid " + aaguid;
+    } else {
+      // No signed model identity: keyed by the attestation certificate instead. A path is
+      // anchor-adjacent first, so that certificate is its LAST element -- the one whose key the
+      // catalogue identifies, not the root it chains to.
+      var keyId = mds.certKeyIdentifier(tp[tp.length - 1]);
+      entry = mds.metadataForKeyIdentifier(md, keyId);
+      identifier = "attestation certificate key identifier " + keyId;
+    }
+    if (!entry) throw _err("webauthn/metadata-not-found", "no metadata entry matches this authenticator (" + identifier + ")");
+    // The attestation certificate is passed in so a report that names a single certificate is
+    // judged against the one actually presented, rather than denying every device the entry covers.
+    if (mds.statusDenied(entry, md, tp[tp.length - 1], at)) {
+      throw _err("webauthn/metadata-status", "the metadata entry for " + identifier + " carries a disqualifying status report");
+    }
+    var anchors = mds.metadataAnchors(entry);
+    if (!anchors.length) throw _err("webauthn/metadata-no-anchor", "the metadata entry for " + identifier + " supplies no attestation root certificate");
+    applied.push({ entry: entry, anchors: anchors, identifier: identifier });
+    return { anchors: anchors, identifier: identifier };
+  }
+  // A path must VALIDATE to one of the roots its own model registered -- signature chaining,
+  // validity, constraints -- not merely resemble one. A name comparison against the top of the path
+  // would accept any certificate asserting the registered issuer's name, which is the assertion an
+  // attacker controls; and certificate equality is not the question either, since a registered root
+  // normally ISSUES the attestation certificate rather than being it. So this composes the same
+  // path validation the BLOB's own chain goes through. chainToAnchor takes leaf-first and a trust
+  // path is anchor-adjacent first, so the order is reversed on the way in.
+  //
+  // opts.time was validated at the entry, so this instant is usable: an unusable one reaching the
+  // path validator would be absorbed by the chain walk and reported as an authenticator trust
+  // failure, which is the wrong verdict for a caller's configuration mistake.
+  var at = opts.time !== undefined ? opts.time : new Date();
+  // The catalogue's own freshness is re-established HERE, at the instant it is being used to decide
+  // trust -- not only at the instant it was parsed. A verified result is a plain object a caller may
+  // hold and reuse indefinitely, so a catalogue fetched before its nextUpdate and then reused a
+  // month afterwards would otherwise keep authorizing an authenticator whose status reports have
+  // since revoked it, which is exactly what nextUpdate exists to prevent. The caller's original
+  // allowStale decision rides on the result, so opting out stays opted out.
+  mds.assertFresh(md, at, "the metadata supplied as opts.metadata");
+  // EVERY path must pass, not merely one of them: for a compound attestation each element is an
+  // independent claim, and accepting the whole because one element anchored would let an
+  // unanchored -- or revoked -- element ride along on its neighbour's trust.
+  return paths.reduce(function (p, info) {
+    return p.then(function () {
+      var g = govern(info);
+      // A path is re-validated at the instant its own format already judged it at, when the format
+      // established one from signed data. An android-safetynet response carries its signing time and
+      // its service chain has usually expired since; resetting to the current clock here would
+      // refuse the very registration the format verifier just accepted. An explicit opts.time still
+      // wins, since the caller knows when the registration happened. The catalogue's own expiry is a
+      // separate question and is judged above, against the caller's instant rather than this one.
+      var pathAt = opts.time !== undefined ? opts.time : (info.at || at);
+      return mds.chainToAnchor(info.tp.slice().reverse(), g.anchors, pathAt,
+        "attestation trust path for " + g.identifier + " (against the roots its metadata entry registers)");
+    });
+  }, Promise.resolve())
+    .then(function () {
+      // The ENTRY's aaguid, not the authenticator's raw field: for a U2F authenticator that field is
+      // all zeroes, which means "no model identity" -- reporting it back as though it were one would
+      // hand the caller a value that matches nothing and reads like an identifier. `entries` lists
+      // every entry that governed a path, which for a compound is one per certificate-bearing
+      // element; `entry` is the first, and equals the only one for every other format.
+      var primary = applied[0];
+      res.metadata = { aaguid: primary.entry.aaguid, keyIdentifiers: primary.entry.keyIdentifiers || [],
+        entry: primary.entry, entries: applied.map(function (a) { return a.entry; }),
+        anchors: primary.anchors.length };
+      return res;
+    });
+}
+
+// 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;
 
+/**
+ * @primitive pki.webauthn.verifyMetadataBlob
+ * @signature pki.webauthn.verifyMetadataBlob(blob, opts) -> Promise<{ no, nextUpdate, entries, byAaguid }>
+ * @since 0.4.11
+ * @status experimental
+ * @spec FIDO Metadata Service v3.0 sec. 3.1, RFC 7515
+ * @related pki.webauthn.verify, pki.webauthn.metadataFor
+ *
+ * Verify a FIDO Metadata Service BLOB -- the signed catalogue of every registered
+ * authenticator model, its attestation roots, and its certification status -- and
+ * return its entries indexed by aaguid for lookup. `blob` is caller-supplied bytes or
+ * a string; retrieval is out of scope, so this never touches the network.
+ *
+ * The BLOB is a JWS. Its signature is checked under the certificate in its own header,
+ * that chain is validated to one of `opts.rootCertificates`, and only THEN is the
+ * payload read -- a BLOB that does not verify never reaches the JSON parser. `no` must
+ * exceed `opts.previousNo` (rollback) and `nextUpdate` must not have passed
+ * (freshness). Every failure is a typed `webauthn/metadata-*` throw, never a partial
+ * result.
+ *
+ * @intro No FIDO root ships with this toolkit and there is no trust-on-first-use:
+ *   which metadata authority to trust is the operator's decision, exactly as a root
+ *   store is for `pki.path.validate`. Supply the FIDO Alliance root you pin.
+ *
+ * @opts
+ *   - `rootCertificates` -- REQUIRED. The trust anchors the BLOB's own signing chain
+ *     must reach. A certificate, PEM, or DER bytes.
+ *   - `time` -- the instant freshness is judged at. Defaults to now.
+ *   - `previousNo` -- the sequence number of the BLOB you already hold. A BLOB whose
+ *     `no` is not greater is refused as a rollback.
+ *   - `requireRollbackCheck` -- require `previousNo`, so a caller cannot skip the
+ *     rollback check by forgetting to pass it.
+ *   - `allowStale` -- accept a BLOB past its `nextUpdate`. Off by default.
+ *   - `statusPolicy` -- which status reports disqualify an authenticator: `"any"`
+ *     (default -- any disqualifying report ever filed), `"latest-by-date"` (only the
+ *     most recent report counts, so a later remediation clears an earlier revocation),
+ *     or a function receiving the raw report array and returning true to deny.
+ *   - `rejectUnknownStatus` -- treat a status this toolkit does not recognise as
+ *     disqualifying. Off by default: the specification requires an unknown status be
+ *     ignored rather than failed on.
+ *
+ * @example
+ *   var md = await pki.webauthn.verifyMetadataBlob(mdsBlobBytes, {
+ *     rootCertificates: [fidoRootDer],
+ *     previousNo: 41,          // refuse a replay of a BLOB you have already superseded
+ *   });
+ *   md.no;                     // 42 (the sequence number this BLOB carries)
+ *   md.entries.length;         // every authenticator model the catalogue lists
+ *   // then bind an attestation to the roots its own model registered:
+ *   // await pki.webauthn.verify(attestationObject, clientDataHash, { metadata: md });
+ */
+
+/**
+ * @primitive pki.webauthn.metadataFor
+ * @signature pki.webauthn.metadataFor(metadata, identifier) -> entry | null
+ * @since 0.4.11
+ * @status experimental
+ * @spec FIDO Metadata Service v3.0 sec. 3.1.1
+ * @related pki.webauthn.verifyMetadataBlob, pki.webauthn.metadataAnchors
+ *
+ * The verified metadata entry for an authenticator model, or `null` when the BLOB
+ * lists none. `metadata` is a `verifyMetadataBlob` RESULT, never raw bytes -- so a
+ * lookup can never be answered out of a BLOB nobody verified.
+ *
+ * `identifier` is whichever of the catalogue's two key spaces names the authenticator:
+ * its aaguid, or -- for a U2F authenticator, which carries none -- the key identifier
+ * of its attestation certificate (RFC 5280 sec. 4.2.1.2 method 1, 40 hex digits). The
+ * two are disjoint by shape, so the form is dispatched on rather than guessed at, and
+ * anything matching neither is a miss. The all-zero aaguid means "this authenticator
+ * declares no model identity" and matches nothing.
+ *
+ * @example
+ *   var entry = pki.webauthn.metadataFor(mdsMetadata, mdsAaguid);
+ *   entry.statusReports[0].status;   // "FIDO_CERTIFIED_L1"
+ *   pki.webauthn.metadataFor(mdsMetadata, "00000000-0000-0000-0000-000000000000");   // null
+ */
+
+/**
+ * @primitive pki.webauthn.metadataAnchors
+ * @signature pki.webauthn.metadataAnchors(entry) -> [certificate]
+ * @since 0.4.11
+ * @status experimental
+ * @spec FIDO Metadata Service v3.0 sec. 3.1.1
+ * @related pki.webauthn.metadataFor, pki.path.validate
+ *
+ * The parsed attestation root certificates a metadata entry registers -- the anchors an
+ * attestation from that model must chain to. Decoding is per entry rather than for the
+ * whole BLOB on purpose: a handful of certificates in the live metadata do not parse
+ * under a strict decoder, and decoding everything up front would let one vendor's
+ * malformed root refuse the entire catalogue for every other authenticator in it.
+ *
+ * @example
+ *   var anchors = pki.webauthn.metadataAnchors(mdsEntry);
+ *   anchors.length;              // the attestation roots this model registered
+ *   anchors[0].subject;          // the decoded root DN
+ *   // chain an attestation's trustPath to them:
+ *   // await pki.path.validate(res.trustPath, { trustAnchors: anchors, time: mdsTime });
+ */
+
 module.exports = {
   parseAttestationObject: parseAttestationObject,
   verify: verify,
+  verifyMetadataBlob: mds.verifyMetadataBlob,
+  metadataFor: mds.metadataFor,
+  metadataAnchors: mds.metadataAnchors,
 };

package/lib/x509-sign.js

@@ -131,8 +131,8 @@ function _buildExtensions(extSpec, ctx) {
   if (typeof extSpec !== "object") throw _err("x509/bad-input", "extensions must be an object or an array of pre-encoded Extension DER");
   // Reject a typo'd / unsupported extension key at config-time rather than silently dropping it (a
   // misspelled `keyUsag` would otherwise omit keyUsage). A custom extension goes in the array form.
-  Object.keys(extSpec).forEach(function (k) {
-    if (!KNOWN_EXT_KEYS[k]) throw _err("x509/bad-input", "unknown extension " + JSON.stringify(k) + " in the extensions spec; pass a pre-encoded Extension DER via the array form for a custom extension");
+  guard.identifier.assertKnownKeys(extSpec, KNOWN_EXT_KEYS, _err, "x509/bad-input", function (k) {
+    return "unknown extension " + JSON.stringify(k) + " in the extensions spec; pass a pre-encoded Extension DER via the array form for a custom extension";
   });
 
   var bc = extSpec.basicConstraints;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "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:1f0429a5-9e2b-4cc8-a67f-6357968a0774",
+  "serialNumber": "urn:uuid:37941dc8-becd-4983-b264-d6897e595ed1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-09T01:33:39.618Z",
+    "timestamp": "2026-08-09T10:47:07.155Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.4.9",
+      "bom-ref": "@blamejs/pki@0.4.11",
       "type": "application",
       "name": "pki",
-      "version": "0.4.9",
+      "version": "0.4.11",
       "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.9",
+      "purl": "pkg:npm/%40blamejs/pki@0.4.11",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.4.9",
+      "ref": "@blamejs/pki@0.4.11",
       "dependsOn": []
     }
   ]