@blamejs/pki 0.4.15 → 0.5.0

package/lib/webauthn.js

@@ -304,7 +304,7 @@ function _findExt(cert, oidName) {
  * @primitive pki.webauthn.parseAttestationObject
  * @signature pki.webauthn.parseAttestationObject(bytes) -> { fmt, attStmt, authData, authDataBytes }
  * @since 0.2.5
- * @status experimental
+ * @status stable
  * @spec W3C WebAuthn Level 3 sec. 6.5.4 / 6.1
  * @related pki.webauthn.verify
  *
@@ -316,6 +316,8 @@ function _findExt(cert, oidName) {
  * A malformed object throws `webauthn/bad-attestation-object`.
  *
  * @example
+ *   // requires: `attestationObject` -- the CBOR bytes a browser returns from
+ *   // navigator.credentials.create(), i.e. credential.response.attestationObject
  *   var att = pki.webauthn.parseAttestationObject(attestationObject);
  *   att.fmt;                               // "packed"
  *   att.authData.credentialPublicKey.kty;  // 2 (EC2)
@@ -404,8 +406,279 @@ function _aaguidIsSigned(fmt) { return _AAGUID_SIGNED_BY_FMT[fmt] !== false; }
 // 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,
+  expectedRpId: 1, requireUserPresence: 1, requireUserVerification: 1, allowedAlgorithms: 1,
+  rootCertificates: 1,
+});
+
+// Anchor an attestation's trust path to roots the CALLER pins. The metadata route
+// resolves an authenticator's roots from the catalogue that registered it, which is
+// the stronger source -- but it only reaches models the catalogue lists, and some
+// are not there: Apple does not publish its authenticators to the FIDO Metadata
+// Service, and the Google hardware-attestation roots are distributed by Google. For
+// those formats the catalogue route resolves nothing, so without this there is no
+// way to anchor them at all and a trust path comes back unchecked. (android-safetynet
+// already had its own `safetyNetRoots` for the same reason; this is that carve-out
+// made general.)
+//
+// PRECEDENCE, stated rather than implied: `metadata` governs when it is supplied,
+// because a model's own registered roots are a stronger claim than a static pin, and
+// its status reports can disqualify a model these roots would still accept.
+// `rootCertificates` is the fallback for the models the catalogue does not cover.
+// Supplying both is not an error -- it is the ordinary configuration for a relying
+// party that accepts MDS-listed authenticators AND Apple.
+// The caller's pinned roots are copied SYNCHRONOUSLY, at the entry point, because
+// they are not read until the attestation verifier has resolved -- a later promise
+// turn. Both the ARRAY and each DER buffer in it stay caller-owned across that gap,
+// so a caller that recycles the array or overwrites a certificate's bytes in between
+// would have the attestation anchored against the replacement roots while the verdict
+// still reports `anchoredTo: "rootCertificates"` (CWE-367 reaching a wrong trust
+// decision). Same defence, and the same reason, as the assertion input's snapshot.
+// Shape faults are NOT raised here: the array is validated where it is consumed, so
+// supplying a malformed pin alongside a metadata catalogue that answers keeps failing
+// exactly where it did before.
+// A parsed certificate is a tree of plain objects, arrays and Buffers, and the anchor
+// comparison downstream reads its `subject` and `subjectPublicKeyInfo` -- both nested
+// Buffers the caller still owns. Copying only the top-level array would leave those
+// aliased, so the parsed form is deep-copied: every Buffer is duplicated and every
+// container rebuilt, while the value types a parsed certificate carries (Date for a
+// validity bound, BigInt for a serial) are preserved rather than flattened.
+//
+// The depth bound is a RECURSION BACKSTOP set far above any real certificate, never the
+// precision mechanism -- a bound tuned to today's shapes silently rejects a legitimate root
+// the moment a deeper one appears. A measured certificate reaches depth 5, and the deepest
+// structure the profile allows -- a certificate policy whose qualifier carries a UserNotice
+// with a noticeRef and its noticeNumbers -- lands near 12, so a cap of 12 would sit exactly
+// on a conforming root. This is set well clear of that; it exists only so a cyclic or hostile
+// object cannot recurse without end.
+function _cloneParsed(v, depth) {
+  if (depth > 64) throw _err("webauthn/bad-input", "opts.rootCertificates[] is nested too deeply to be a parsed certificate");
+  if (Buffer.isBuffer(v) || v instanceof Uint8Array) return Buffer.from(v);
+  if (Array.isArray(v)) return v.map(function (x) { return _cloneParsed(x, depth + 1); });
+  if (v instanceof Date) return new Date(v.getTime());
+  if (v && typeof v === "object") {
+    var out = {};
+    Object.keys(v).forEach(function (k) { out[k] = _cloneParsed(v[k], depth + 1); });
+    return out;
+  }
+  return v;   // string, number, boolean, bigint, null, undefined -- all immutable
+}
+
+// A caller-owned byte argument, copied so nothing downstream reads bytes the caller can still
+// rewrite. Every byte form the parsers accept is covered -- an ArrayBuffer or a DataView arrives
+// by the same door as a Buffer, and leaving those aliased would reopen the window for exactly the
+// inputs that came in by the wider one. Anything else passes through untouched so this cannot
+// change which inputs are accepted; the parser downstream still names a wrong type.
+function _snapshotBytes(v, label) {
+  if (ArrayBuffer.isView(v) || v instanceof ArrayBuffer) {
+    return guard.bytes.snapshotSource(v, WebauthnError, "webauthn/bad-input", label);
+  }
+  return v;
+}
+
+function _snapshotRoots(supplied) {
+  if (!Array.isArray(supplied)) return supplied;
+  return supplied.map(function (root) {
+    if (Buffer.isBuffer(root) || root instanceof Uint8Array) {
+      return guard.bytes.snapshot(root, WebauthnError, "webauthn/bad-input", "opts.rootCertificates[]");
+    }
+    if (root && typeof root === "object") return _cloneParsed(root, 0);
+    return root;   // a PEM string is immutable
+  });
+}
+
+// `supplied` is the SNAPSHOT taken at the entry point, never `opts.rootCertificates`
+// read afresh here -- that re-read is the window this guard closes. `opts` is still
+// threaded for the non-aliasing options (the validation time).
+// `vopts` is `verify`'s NORMALIZED options object, never the caller's -- the parameter is
+// named for that so a future caller cannot hand it the live one without noticing. Everything
+// it reads was captured synchronously at the entry.
+function _applyCallerRoots(res, supplied, vopts, onlyPaths) {
+  if (!Array.isArray(supplied) || !supplied.length) {
+    throw _err("webauthn/bad-input", "opts.rootCertificates must be a non-empty array of root certificates (DER, PEM, or parsed)");
+  }
+  // DER, PEM or an already-parsed certificate, decoded HERE -- the anchor comparison
+  // downstream reads a certificate's subject and key, so a raw buffer reaching it
+  // would fault on a field it does not have rather than naming the caller's mistake.
+  // The same three forms opts.safetyNetRoots takes, since it is the same question.
+  var roots = supplied.map(function (root, i) {
+    var cert;
+    try { cert = (Buffer.isBuffer(root) || typeof root === "string") ? x509.parse(root) : root; }
+    catch (e) { throw _err("webauthn/bad-input", "opts.rootCertificates[" + i + "] is not a decodable certificate", e); }
+    if (!cert || !cert.subject || !cert.subjectPublicKeyInfo) {
+      throw _err("webauthn/bad-input", "opts.rootCertificates[" + i + "] is not a certificate");
+    }
+    return cert;
+  });
+  // Same rule the metadata route applies: a compound element carrying no
+  // certificates makes no claim there is anything to anchor, so it is not a reason to
+  // refuse the statement -- but `anchoredTo` alone would then say "anchored" over a
+  // statement it did not wholly cover. The coverage is reported instead.
+  // `onlyPaths`, when given, is the set of paths the CATALOGUE did not cover -- the
+  // fallback is for exactly those. Applying it to the whole statement instead would
+  // re-judge an element the catalogue already governed against roots that have nothing
+  // to do with it: a compound holding one listed element (chaining to the root its own
+  // metadata entry registers) beside one unlisted element (chaining to a caller pin) would
+  // be refused, because the listed element does not chain to the pin. That is the
+  // documented "MDS-listed authenticators AND Apple" configuration, and each element is
+  // still anchored to something the caller trusts -- just not all to the same thing.
+  var paths = onlyPaths || ((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, at: el.chainValidatedAt }; })
+    : (res.trustPath && res.trustPath.length ? [{ tp: res.trustPath, at: res.chainValidatedAt }] : []));
+  // Coverage is ACCUMULATED across routes, not overwritten by whichever ran last. When
+  // `onlyPaths` is given the metadata route already anchored the rest and recorded that here,
+  // so reporting the fallback's own count would say 1 of 2 for a statement whose two elements
+  // were both anchored -- one by the catalogue, one by the pin. A caller enforcing
+  // `anchored === total` would then reject the mixed configuration this fallback exists to
+  // support, and the verdict would understate the trust evaluation it actually performed.
+  if (!onlyPaths) {
+    res.anchoredElements = { total: (res.fmt === "compound" && Array.isArray(res.compound)) ? res.compound.length : 1,
+      anchored: paths.length };
+  }
+  // `none` and a self-attestation carry no certificates, so there is nothing to
+  // anchor -- and a caller who asked for anchoring is told it could not be applied
+  // rather than handed a pass that looks like it was. Same rule the metadata route
+  // states, for the same reason.
+  if (!paths.length) {
+    throw _err("webauthn/anchor-not-applicable",
+      "opts.rootCertificates was supplied, but this attestation carries no trust path to anchor (format '" + res.fmt + "')");
+  }
+  var at = vopts.time !== undefined ? vopts.time : new Date();
+  // EVERY path, not merely one: a compound's elements are independent claims, and
+  // accepting the whole because one element anchored would let an unanchored element
+  // ride along on its neighbour's trust.
+  return paths.reduce(function (p, info) {
+    return p.then(function () {
+      var pathAt = vopts.time !== undefined ? vopts.time : (info.at || at);
+      return mds.chainToAnchor(info.tp.slice().reverse(), roots, pathAt,
+        "attestation trust path (against the roots supplied as opts.rootCertificates)");
+    });
+  }, Promise.resolve()).then(function () {
+    res.anchoredTo = _anchoredRoutes(res, "rootCertificates");
+    return res;
+  });
+}
+
+// android-safetynet anchors through a route of its own. The verifier REQUIRES
+// `opts.safetyNetRoots` (8.5) and refuses the statement unless the x5c chain validates to
+// one of them, so by the time a verdict is composed that element's path HAS been anchored --
+// without either `metadata` or `rootCertificates` being involved. Counting only those two
+// routes reports `anchoredTo: null` over it, whose documented meaning is that nobody checked
+// the path, so a caller enforcing `anchoredTo !== null` would refuse an attestation this
+// library did in fact anchor. Every route that contributed is named.
+function _safetyNetAnchored(res) {
+  if (res.fmt === "android-safetynet") return 1;
+  if (res.fmt === "compound" && Array.isArray(res.compound)) {
+    return res.compound.filter(function (el) { return el && el.fmt === "android-safetynet"; }).length;
+  }
+  return 0;
+}
+
+// `base` is whichever of the two caller-selected routes ran, or null when neither did.
+// Routes are named in a stable order so a caller may compare the string.
+function _anchoredRoutes(res, base) {
+  var routes = base ? base.split("+") : [];
+  if (_safetyNetAnchored(res) && routes.indexOf("safetyNetRoots") < 0) routes.push("safetyNetRoots");
+  return routes.length ? routes.join("+") : null;
+}
+
+// ---- ceremony binding (WebAuthn sec. 7.1 / 7.2) ------------------------------
+//
+// The attestation and assertion procedures verify a SIGNATURE. What makes a
+// response acceptable is a separate set of checks the relying party owns, because
+// only it knows what it asked for: the challenge it issued, the origin the browser
+// reported, the RP ID it operates under, and the user-presence / user-verification
+// policy it requires. A verifier that answers only the first question, under a name
+// that sounds like the second, is the shape of every phishing-resistant login that
+// turns out not to be -- an attestation naming ANOTHER RP, with user presence
+// clear, is a perfectly sound statement about a credential the caller must not
+// accept.
+//
+// So the checks this layer CAN make are offered here, opt-in, and every verdict
+// reports which of them actually ran. The challenge and the origin stay with the
+// caller: they live in clientDataJSON, which the caller already holds and compares
+// against state only it has.
+var _BINDING_OPTS = Object.assign(Object.create(null), {
+  expectedRpId: 1, requireUserPresence: 1, requireUserVerification: 1, allowedAlgorithms: 1,
 });
 
+function _assertBool(v, name) {
+  if (typeof v !== "boolean") throw _err("webauthn/bad-input", "opts." + name + " must be a boolean");
+}
+
+// Runs the bindings the caller asked for and reports EACH one's status: `true` it
+// was checked and holds, `false` it was not asked for. A caller reading the verdict
+// can therefore tell a check that passed from one that never ran -- the distinction
+// the single `verified` boolean could not express.
+function _applyBindings(authData, coseKey, opts) {
+  var checked = { rpId: false, userPresence: false, userVerification: false, algorithm: false };
+  if (opts.expectedRpId !== undefined) {
+    if (typeof opts.expectedRpId !== "string" || !opts.expectedRpId.length) {
+      throw _err("webauthn/bad-input", "opts.expectedRpId must be a non-empty RP ID string");
+    }
+    // Compared in constant time and by full value, like every other identity
+    // comparison in this toolkit -- a prefix must not read as a match.
+    if (!guard.crypto.constantTimeEqual(_sha("sha256", Buffer.from(opts.expectedRpId, "utf8")),
+      Buffer.from(authData.rpIdHash))) {
+      throw _err("webauthn/rp-id-mismatch",
+        "the authenticatorData rpIdHash is not SHA-256 of opts.expectedRpId, so this response was " +
+        "produced for a different relying party (WebAuthn sec. 7.1 step 13 / sec. 7.2 step 15)");
+    }
+    checked.rpId = true;
+  }
+  if (opts.requireUserPresence !== undefined) {
+    _assertBool(opts.requireUserPresence, "requireUserPresence");
+    if (opts.requireUserPresence && !authData.flags.up) {
+      throw _err("webauthn/user-presence-required",
+        "opts.requireUserPresence is set and the authenticatorData User Present (UP) flag is clear " +
+        "(WebAuthn sec. 7.1 step 14 / sec. 7.2 step 16)");
+    }
+    checked.userPresence = opts.requireUserPresence;
+  }
+  if (opts.requireUserVerification !== undefined) {
+    _assertBool(opts.requireUserVerification, "requireUserVerification");
+    if (opts.requireUserVerification && !authData.flags.uv) {
+      throw _err("webauthn/user-verification-required",
+        "opts.requireUserVerification is set and the authenticatorData User Verified (UV) flag is clear " +
+        "(WebAuthn sec. 7.1 step 15 / sec. 7.2 step 17)");
+    }
+    checked.userVerification = opts.requireUserVerification;
+  }
+  // COSE alg -65535 is RSASSA-PKCS1-v1_5 with SHA-1, and a credential key may name
+  // it -- which would make SHA-1 the signature algorithm of every login that
+  // credential ever performs. Refused unless the caller lists it, so supporting a
+  // legacy authenticator is a decision someone wrote down rather than the default.
+  // (This is the CREDENTIAL key's algorithm. A legacy TPM attestation STATEMENT
+  // signed with RS1 is a different field and is still verified, since refusing it
+  // would reject the authenticator's own evidence about itself.)
+  var alg65535Allowed = Array.isArray(opts.allowedAlgorithms) && opts.allowedAlgorithms.indexOf(-65535) !== -1;
+  if (coseKey && coseKey.alg === -65535 && !alg65535Allowed) {
+    throw _err("webauthn/algorithm-not-allowed",
+      "the credential public key declares COSE algorithm -65535 (RSASSA-PKCS1-v1_5 with SHA-1); every " +
+      "signature made by this credential would use SHA-1, so it is refused unless opts.allowedAlgorithms " +
+      "names -65535 explicitly");
+  }
+  // The rest of algorithm policy is the RP's, declared to the browser as
+  // pubKeyCredParams, and nothing in the response proves what was offered -- so it
+  // is checked only when the caller states the list.
+  if (opts.allowedAlgorithms !== undefined) {
+    if (!Array.isArray(opts.allowedAlgorithms) || !opts.allowedAlgorithms.length ||
+        // isSafeInteger, not isInteger: a value above 2^53 is not held exactly as a
+        // Number, so one written that way is not the identifier the caller meant --
+        // and no COSE algorithm identifier lives out there anyway.
+        !opts.allowedAlgorithms.every(function (a) { return typeof a === "number" && Number.isSafeInteger(a); })) {
+      throw _err("webauthn/bad-input", "opts.allowedAlgorithms must be a non-empty array of COSE algorithm integers");
+    }
+    var alg = coseKey && coseKey.alg;
+    if (opts.allowedAlgorithms.indexOf(alg) === -1) {
+      throw _err("webauthn/algorithm-not-allowed",
+        "the credential public key declares COSE algorithm " + alg + ", which is not in opts.allowedAlgorithms");
+    }
+    checked.algorithm = true;
+  }
+  return checked;
+}
+
 // 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
@@ -849,8 +1122,26 @@ function _safetyNetChainTrusted(chain, roots, time) {
 // `chain` is the x5c order (leaf-first); trustPath is surfaced in pki.path.validate
 // order (anchor-adjacent first, target/leaf last) so the caller passes it straight
 // to the path validator without re-ordering. The input array is not mutated.
+// `attestationVerified`, not `verified`: this says the attestation STATEMENT is
+// sound, which is not the same claim as "this registration is acceptable". The
+// ceremony bindings the caller may also have asked for are reported separately, in
+// `bindingChecked`, so a field that passed can be told from one that never ran.
+// It also carries everything a relying party must STORE to finish registration and
+// run a later login: the credentialId it will look the credential up by, the
+// credential public key that will verify assertions, and the signCount that is the
+// starting point for the sec. 7.2 step 21 counter rule. Leaving those out sent the
+// caller back to parse the attestation object a second time for values this call
+// had already decoded -- and a login cannot be verified without them.
 function _result(fmt, attestationType, chain, att) {
-  return { verified: true, fmt: fmt, attestationType: attestationType, trustPath: (chain || []).slice().reverse(), aaguid: att.authData.aaguid, credentialPublicKey: att.authData.credentialPublicKey };
+  return {
+    attestationVerified: true, fmt: fmt, attestationType: attestationType,
+    trustPath: (chain || []).slice().reverse(),
+    aaguid: att.authData.aaguid,
+    credentialId: att.authData.credentialId,
+    credentialPublicKey: att.authData.credentialPublicKey,
+    signCount: att.authData.signCount,
+    flags: att.authData.flags,
+  };
 }
 
 // Decode the Apple extension AppleAnonymousAttestation ::= SEQUENCE { nonce [1]
@@ -858,9 +1149,19 @@ function _result(fmt, attestationType, chain, att) {
 function _appleNonce(extValue) {
   var seq;
   try { seq = asn1.decode(extValue); } catch (e) { throw _err("webauthn/bad-att-cert", "the apple attestation extension is not decodable", e); }
-  var tagged = seq.children && seq.children[0];
-  if (!tagged || tagged.tagClass !== "context" || tagged.tagNumber !== 1 || !tagged.children || !tagged.children[0]) {
-    throw _err("webauthn/bad-att-cert", "the apple attestation extension is not SEQUENCE { [1] OCTET STRING }");
+  // ARITY IS PART OF THE DECLARED SHAPE. Reading the first child and ignoring the rest
+  // accepts a certificate carrying a second, unchecked value beside the nonce -- and this
+  // extension exists precisely to carry the value the attestation binds to, so an
+  // ambiguous encoding of it is not a shape this verifier gets to pick a reading from.
+  // The type is one SEQUENCE of exactly one field, and the EXPLICIT wrapper holds exactly
+  // one value; anything else is refused rather than partially read.
+  var isSeq = seq.tagClass === "universal" && seq.tagNumber === asn1.TAGS.SEQUENCE;
+  if (!isSeq || !seq.children || seq.children.length !== 1) {
+    throw _err("webauthn/bad-att-cert", "the apple attestation extension is not SEQUENCE { [1] OCTET STRING } (expected exactly one field)");
+  }
+  var tagged = seq.children[0];
+  if (!tagged || tagged.tagClass !== "context" || tagged.tagNumber !== 1 || !tagged.children || tagged.children.length !== 1) {
+    throw _err("webauthn/bad-att-cert", "the apple attestation extension is not SEQUENCE { [1] OCTET STRING } (expected one EXPLICIT [1] value)");
   }
   try { return asn1.read.octetString(tagged.children[0]); } catch (e) { throw _err("webauthn/bad-att-cert", "the apple attestation nonce is not an OCTET STRING", e); }
 }
@@ -875,11 +1176,11 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
 
 /**
  * @primitive pki.webauthn.verify
- * @signature pki.webauthn.verify(attestationObject, clientDataHash, opts) -> Promise<{ verified, fmt, attestationType, trustPath, aaguid, credentialPublicKey }>
+ * @signature pki.webauthn.verify(attestationObject, clientDataHash, opts) -> Promise<{ attestationVerified, fmt, attestationType, trustPath, anchoredTo, anchoredElements, aaguid, credentialId, credentialPublicKey, signCount, flags, bindingChecked }>
  * @since 0.2.5
- * @status experimental
- * @spec W3C WebAuthn Level 3 sec. 8
- * @related pki.webauthn.parseAttestationObject
+ * @status stable
+ * @spec W3C WebAuthn Level 3 sec. 8 / sec. 7.1
+ * @related pki.webauthn.parseAttestationObject, pki.webauthn.parseClientData, pki.webauthn.verifyAssertion
  *
  * Verify a WebAuthn attestation statement: the attestation signature over
  * `authenticatorData || clientDataHash` and (for the x5c formats) the format's
@@ -888,22 +1189,61 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  * throws a typed `webauthn/*` error; a signature that does not verify is a
  * `webauthn/verify-failed` verdict, never a silent pass.
  *
+ * The verdict field is `attestationVerified`, and the name is the point: a sound
+ * attestation statement is not the same claim as an acceptable registration. The
+ * statement says nothing about WHICH relying party asked for it, or whether a user
+ * was present -- so an attestation naming another origin's RP ID, with user presence
+ * clear, is perfectly sound and must not be registered. Supply `expectedRpId`,
+ * `requireUserPresence`, `requireUserVerification` and `allowedAlgorithms` and those
+ * are checked here; `bindingChecked` reports which ran, so a check that passed can be
+ * told from one that never happened. The CHALLENGE and the ORIGIN live in
+ * clientDataJSON -- read them with `pki.webauthn.parseClientData`, which compares
+ * them against the state only the relying party has.
+ *
+ * The verdict also carries what a relying party must STORE to run a later login:
+ * `credentialId`, `credentialPublicKey` and the initial `signCount`.
+ *
  * @intro This verifies the attestation STATEMENT -- the signature and the format's
  *   structural bindings (the x5c leaf key == credential key, the apple nonce, the tpm
  *   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. 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.
+ *   order -- anchor-adjacent first, leaf last) to a trusted root is a separate step,
+ *   and there are three ways to take it. Pass `opts.metadata` -- a
+ *   `pki.webauthn.verifyMetadataBlob` result -- and the authenticator's registered
+ *   attestation roots are resolved from its own identifier and the trust path is
+ *   required to reach one, so an unlisted or revoked model is refused rather than
+ *   reported as verified. Pass `opts.rootCertificates` and the path is required to
+ *   validate to a root you pin: this is what anchors the formats the catalogue does
+ *   not cover, since Apple does not publish its authenticators to the FIDO Metadata
+ *   Service and the Google hardware-attestation roots come from Google. Or anchor
+ *   `trustPath` yourself with `pki.path.validate`. Supplying both options is the
+ *   ordinary configuration for a relying party that accepts MDS-listed authenticators
+ *   AND Apple; `metadata` governs when present, because a model's own registered
+ *   roots are a stronger claim than a static pin and its status reports can
+ *   disqualify a model those roots would still accept. `anchoredTo` reports which
+ *   route ran, naming every route that contributed and joining them with `+` when more
+ *   than one did -- `"metadata"`, `"rootCertificates"`, and `"safetyNetRoots"` for the
+ *   android-safetynet chain, which anchors through the roots that format requires whether
+ *   or not either other route was asked for. It is `null` only when nothing anchored the
+ *   path. On the mixed metadata/pinned-root route `metadata` still carries the
+ *   entries that governed, so the stronger half of the decision stays auditable rather
+ *   than being flattened into the pinned-root half. `anchoredElements` reports how much of the
+ *   statement it covered. That matters for a compound attestation (sec. 8.9), whose
+ *   elements are independent claims: an element carrying no certificates makes no
+ *   claim there is anything to anchor, so it is not a reason to refuse the statement,
+ *   but it does mean "anchored" covered fewer elements than the statement holds.
  *
  * @example
- *   var res = await pki.webauthn.verify(attestationObject, clientDataHash, {});
- *   res.verified;         // true (statement signature + bindings hold)
- *   res.attestationType;  // "Basic"
- *   // anchor res.trustPath to your pinned roots with pki.path.validate
+ *   // requires: `attestationObject` from navigator.credentials.create(), and
+ *   // `clientDataHash` = SHA-256 of the matching credential.response.clientDataJSON
+ *   var res = await pki.webauthn.verify(attestationObject, clientDataHash, {
+ *     expectedRpId: "example.com", requireUserPresence: true,
+ *   });
+ *   res.attestationVerified;    // true (statement signature + bindings hold)
+ *   res.bindingChecked.rpId;    // true -- this response names example.com
+ *   res.attestationType;        // "Basic"
+ *   // store res.credentialId / res.credentialPublicKey / res.signCount for logins,
+ *   // and anchor res.trustPath to your pinned roots with pki.path.validate
  */
 function verify(attestationObject, clientDataHash, opts) {
   opts = opts || {};
@@ -921,6 +1261,22 @@ function verify(attestationObject, clientDataHash, opts) {
     return Promise.reject(_err("webauthn/bad-input", "clientDataHash must be a 32-byte SHA-256 digest"));
   }
   var att;
+  // Both byte inputs are snapshotted BEFORE anything reads them, for the same reason the trust
+  // anchors are: the attestation statement is not evaluated until a later promise turn, and both
+  // stay caller-owned across that gap. The attestation object is copied before it is parsed, not
+  // after, because the parse surfaces its byte fields as VIEWS -- the authenticator data the
+  // signature covers, the statement, the credential key -- so copying afterwards would leave every
+  // one of them pointing at bytes the caller can still rewrite. The clientDataHash is what binds
+  // the statement to this ceremony; a caller who overwrote it in that gap would have the signature
+  // checked against a challenge and origin nobody agreed to, and the verdict would still report a
+  // sound attestation. A DataView or ArrayBuffer comes in by the same door and is copied too.
+  var attBytes, cdh;
+  try {
+    attBytes = _snapshotBytes(attestationObject, "attestationObject");
+    cdh = _snapshotBytes(clientDataHash, "clientDataHash");
+  } catch (e) { return Promise.reject(e); }
+  attestationObject = attBytes;
+  clientDataHash = cdh;
   try { att = parseAttestationObject(attestationObject); } catch (e) { return Promise.reject(e); }
   // A registration attestation MUST carry attestedCredentialData (the AT flag): the
   // whole point is to bind the attestation to a credential public key. Reject an
@@ -940,8 +1296,91 @@ function verify(attestationObject, clientDataHash, opts) {
   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); });
+  // The ceremony bindings run BEFORE the statement is evaluated: a response
+  // produced for another relying party, or without the user presence the caller
+  // requires, is not a message this call should spend a signature verification on
+  // -- and refusing it early keeps the "acceptable" question ahead of the "sound"
+  // one, which is the order sec. 7.1 puts them in.
+  // ONE normalized options object, built synchronously here. Nothing past this point reads
+  // the caller's `opts` again -- not the values, and not the presence tests that pick which
+  // trust policy runs.
+  //
+  // Fixing this per-field does not converge. The verifier resolves in a later turn, so every
+  // field the deferred path touches stays caller-owned across that gap, and each repair that
+  // snapshotted one more field left the next one aliased: the roots, then the safetynet
+  // roots, then the routing test beside them, then the metadata routing test, then the
+  // validation instant. They are not separate bugs, they are one window, and the way to
+  // close a window is to stop reading through it rather than to copy one more thing across.
+  //
+  // `Object.assign` captures every own field by value at this instant, which fixes both the
+  // values and the `!== undefined` presence tests derived from them. The two root arrays get
+  // a deeper copy because their CONTENTS are caller-owned too. `metadata` is captured by
+  // reference: a verified catalogue can hold thousands of entries and copying it per
+  // registration is a real cost, so reassignment can no longer swap it, while mutation of
+  // the object it points at remains open and is tracked separately.
+  var bindingChecked, vopts;
+  try {
+    bindingChecked = _applyBindings(att.authData, att.authData.credentialPublicKey, opts);
+    vopts = Object.assign({}, opts, {
+      rootCertificates: _snapshotRoots(opts.rootCertificates),
+      safetyNetRoots: _snapshotRoots(opts.safetyNetRoots),
+    });
+  } catch (e) { return Promise.reject(e); }
+  return Promise.resolve().then(function () { return verifier(att, clientDataHash, vopts); })
+    .then(function (res) {
+      // Metadata governs when supplied; caller roots are the fallback for the models
+      // the catalogue does not cover. Whichever ran, the verdict SAYS which -- so a
+      // caller can tell an anchored trust path from one nobody checked, rather than
+      // inferring it from which option they happened to pass.
+      if (vopts.metadata === undefined) {
+        if (vopts.rootCertificates !== undefined) return _applyCallerRoots(res, vopts.rootCertificates, vopts);
+        res.anchoredTo = _anchoredRoutes(res, null);
+        // Coverage is reported whenever anything WAS anchored, for the same reason the other
+        // routes report it: `anchoredTo` alone cannot say how much of a compound it covered.
+        var sn = _safetyNetAnchored(res);
+        if (sn) {
+          res.anchoredElements = { total: (res.fmt === "compound" && Array.isArray(res.compound)) ? res.compound.length : 1,
+            anchored: sn };
+        }
+        return res;
+      }
+      return Promise.resolve().then(function () { return _applyMetadata(res, att, vopts); })
+        .then(function (out) { out.anchoredTo = _anchoredRoutes(out, "metadata"); return out; }, function (e) {
+          // A catalogue MISS is the case pinned roots exist for: the combined
+          // configuration is exactly "MDS-listed authenticators AND Apple", and Apple
+          // is in no catalogue, so failing here would make the documented pairing
+          // unusable for the very models it was added to reach.
+          //
+          // A catalogue DENIAL is not a miss and never falls through. If the model IS
+          // listed and its entry disqualifies it -- a revoked status report, a trust
+          // path that does not reach the roots that model registered -- then the
+          // catalogue has spoken about this authenticator, and letting a static pin
+          // overrule it would turn the stronger source into the weaker one.
+          if (!e || e.code !== "webauthn/metadata-not-found" || vopts.rootCertificates === undefined) throw e;
+          // Only the elements the catalogue did not cover fall back. The listed ones were
+          // already governed AND chain-validated to the roots their own entries register, so
+          // re-judging them against an unrelated pin would refuse the combined configuration
+          // this fallback exists to support.
+          return Promise.resolve(_applyCallerRoots(res, vopts.rootCertificates, vopts, e.missedPaths))
+            .then(function (out) {
+              // Report BOTH routes. The pinned roots covered only the elements the catalogue
+              // missed; the rest were governed by their metadata entries and chain-validated
+              // against the roots those entries register. Saying "rootCertificates" alone
+              // would attribute the whole evaluation to the weaker half and lose the entries
+              // an auditor needs to see. `anchoredTo` names both, and the governed entries
+              // are surfaced exactly as the pure-metadata route surfaces them.
+              var applied = e.appliedEntries || [];
+              if (!applied.length) return out;
+              var primary = applied[0];
+              out.metadata = { aaguid: primary.entry.aaguid, keyIdentifiers: primary.entry.keyIdentifiers || [],
+                entry: primary.entry, entries: applied.map(function (a) { return a.entry; }),
+                anchors: primary.anchors.length };
+              out.anchoredTo = _anchoredRoutes(out, "metadata+rootCertificates");
+              return out;
+            });
+        });
+    })
+    .then(function (res) { res.bindingChecked = bindingChecked; return res; });
 }
 
 // WebAuthn sec. 7.1 step 22-23: having verified the attestation, look the authenticator model up in
@@ -968,10 +1407,19 @@ function _applyMetadata(res, att, opts) {
   // 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.
+  // A compound's elements are independent claims (sec. 8.9), and one carrying no
+  // certificates -- a `none` or self element -- makes no attestation claim there is
+  // anything to anchor. Refusing the whole statement over it would reject a
+  // conforming compound whose certificate-bearing elements do chain; enforcing over
+  // the rest and saying nothing would report catalogue enforcement over a statement
+  // it did not wholly reach. So the elements that CAN be governed are, and the
+  // coverage is reported (`anchoredElements`) rather than left to be assumed.
   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 }] : []);
+  res.anchoredElements = { total: (res.fmt === "compound" && Array.isArray(res.compound)) ? res.compound.length : 1,
+    anchored: paths.length };
   // 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.
@@ -1046,9 +1494,45 @@ function _applyMetadata(res, att, opts) {
   // 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) {
+  // Govern EVERY path BEFORE any is chain-validated, and let the SEVEREST outcome decide
+  // rather than the first one reached. A compound's elements are independent claims and
+  // its element order is NOT signed, so aborting on the first failure lets that order pick
+  // which element the catalogue gets to speak about. The asymmetry that makes it exploitable
+  // is that the errors are not equal: `metadata-not-found` is the one outcome the caller may
+  // fall back to pinned roots on, and that fallback covers the WHOLE statement. So an element
+  // the catalogue does not list, placed first, would raise the fallback error and a listed
+  // sibling carrying a disqualifying status report would never be consulted -- the unlisted
+  // element laundering the revoked one. A denial therefore outranks a miss wherever each sits:
+  // a miss is only reported once every other path has been governed and none of them objected.
+  var governed = [];
+  var missed = null;
+  var missedPaths = [];
+  for (var gi = 0; gi < paths.length; gi++) {
+    try {
+      governed.push({ info: paths[gi], g: govern(paths[gi]) });
+    } catch (ge) {
+      // WHICH paths missed is carried with the error, not just THAT one did. The caller's
+      // pinned-root fallback is for the elements the catalogue did not cover, and it cannot
+      // tell which those were from the verdict alone -- every element looks the same there.
+      if (ge && ge.code === "webauthn/metadata-not-found") { missed = missed || ge; missedPaths.push(paths[gi]); continue; }
+      throw ge;   // a status denial, a missing anchor, any other governance failure: terminal
+    }
+  }
+  // The miss carries BOTH halves: which paths the catalogue did not cover, and which entries
+  // it did govern. Without the second the fallback can only describe its own half, so a
+  // mixed-route verdict would attribute the whole evaluation to the pinned roots and drop the
+  // metadata-backed part entirely -- the stronger half, and the one an auditor most needs.
+  if (missed) { missed.missedPaths = missedPaths; missed.appliedEntries = applied; }
+  // The miss is NOT reported yet. Resolving an entry is only half of governance: the other
+  // half is that the path must actually VALIDATE to the roots that entry registers, and that
+  // runs below. Reporting the miss here would skip it for every listed element -- so a listed
+  // element whose path reaches the caller's pinned roots but NOT its own registered roots
+  // would ride out on the unlisted sibling's fallback, which is that same bypass moved one
+  // phase down. Every listed element is chain-validated first, and only then may a miss be
+  // raised.
+  return governed.reduce(function (p, item) {
     return p.then(function () {
-      var g = govern(info);
+      var g = item.g, info = item.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
@@ -1061,6 +1545,12 @@ function _applyMetadata(res, att, opts) {
     });
   }, Promise.resolve())
     .then(function () {
+      // Every LISTED element has now been fully governed -- entry resolved, status checked, and its
+      // path validated to that entry's own registered roots. A miss recorded above may finally be
+      // reported, and the caller's pinned-roots fallback is reachable only from here: a statement
+      // whose listed elements all satisfied their catalogue entries, with a sibling the catalogue
+      // simply does not cover.
+      if (missed) throw missed;
       // 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
@@ -1092,7 +1582,7 @@ void constants;
  * @primitive pki.webauthn.verifyMetadataBlob
  * @signature pki.webauthn.verifyMetadataBlob(blob, opts) -> Promise<{ no, nextUpdate, entries, byAaguid }>
  * @since 0.4.11
- * @status experimental
+ * @status stable
  * @spec FIDO Metadata Service v3.0 sec. 3.1, RFC 7515
  * @related pki.webauthn.verify, pki.webauthn.metadataFor
  *
@@ -1130,6 +1620,8 @@ void constants;
  *     ignored rather than failed on.
  *
  * @example
+ *   // requires: `mdsBlobBytes` -- the signed BLOB from https://mds3.fidoalliance.org/
+ *   // -- and `fidoRootDer`, the FIDO Alliance root certificate it chains to
  *   var md = await pki.webauthn.verifyMetadataBlob(mdsBlobBytes, {
  *     rootCertificates: [fidoRootDer],
  *     previousNo: 41,          // refuse a replay of a BLOB you have already superseded
@@ -1144,7 +1636,7 @@ void constants;
  * @primitive pki.webauthn.metadataFor
  * @signature pki.webauthn.metadataFor(metadata, identifier) -> entry | null
  * @since 0.4.11
- * @status experimental
+ * @status stable
  * @spec FIDO Metadata Service v3.0 sec. 3.1.1
  * @related pki.webauthn.verifyMetadataBlob, pki.webauthn.metadataAnchors
  *
@@ -1160,6 +1652,8 @@ void constants;
  * declares no model identity" and matches nothing.
  *
  * @example
+ *   // requires: `mdsMetadata` -- a verifyMetadataBlob RESULT (never raw bytes, so a
+ *   // lookup cannot be answered out of an unverified BLOB) -- and the model's aaguid
  *   var entry = pki.webauthn.metadataFor(mdsMetadata, mdsAaguid);
  *   entry.statusReports[0].status;   // "FIDO_CERTIFIED_L1"
  *   pki.webauthn.metadataFor(mdsMetadata, "00000000-0000-0000-0000-000000000000");   // null
@@ -1169,7 +1663,7 @@ void constants;
  * @primitive pki.webauthn.metadataAnchors
  * @signature pki.webauthn.metadataAnchors(entry) -> [certificate]
  * @since 0.4.11
- * @status experimental
+ * @status stable
  * @spec FIDO Metadata Service v3.0 sec. 3.1.1
  * @related pki.webauthn.metadataFor, pki.path.validate
  *
@@ -1180,6 +1674,7 @@ void constants;
  * malformed root refuse the entire catalogue for every other authenticator in it.
  *
  * @example
+ *   // requires: `mdsEntry` -- one entry from a verified BLOB, as metadataFor returns
  *   var anchors = pki.webauthn.metadataAnchors(mdsEntry);
  *   anchors.length;              // the attestation roots this model registered
  *   anchors[0].subject;          // the decoded root DN
@@ -1187,9 +1682,383 @@ void constants;
  *   // await pki.path.validate(res.trustPath, { trustAnchors: anchors, time: mdsTime });
  */
 
+// ---- public: parseClientData -------------------------------------------------
+
+// The two ceremony types, fixed by the spec -- `webauthn.create` for registration
+// and `webauthn.get` for authentication. This is NOT relying-party policy: a
+// registration response replayed into a login (or the reverse) is a real attack,
+// and which one a caller is finishing is known at the call site, never negotiated.
+var CLIENT_DATA_TYPE = Object.assign(Object.create(null), { "webauthn.create": 1, "webauthn.get": 1 });
+
+/**
+ * @primitive pki.webauthn.parseClientData
+ * @signature pki.webauthn.parseClientData(bytes, opts?) -> { type, challenge, origin, crossOrigin, topOrigin, checked }
+ * @since 0.5.0
+ * @status experimental
+ * @spec W3C WebAuthn Level 3 sec. 5.8.1 / 7.1 / 7.2
+ * @defends webauthn-ceremony-confusion (CWE-345)
+ * @related pki.webauthn.verify, pki.webauthn.verifyAssertion
+ *
+ * Decode the `clientDataJSON` a ceremony returns -- the half of a WebAuthn response
+ * the signature covers by digest but that no signature check ever looks inside.
+ * Parsed through the shared fail-closed JSON guard (bounded bytes and depth,
+ * fatal UTF-8, duplicate members refused, no prototype pollution), because these
+ * are bytes an attacker chose. `challenge` is returned DECODED from base64url as a
+ * Buffer, so a caller compares raw bytes and never two spellings of the same
+ * value; `type`, `origin`, `crossOrigin` and `topOrigin` come back as they were.
+ *
+ * Supply `expectedType`, `expectedChallenge` and `expectedOrigin` and each is
+ * checked here -- the challenge in constant time and by full value. `checked`
+ * reports which ran, so a check that passed is distinguishable from one that never
+ * happened. `expectedType` is worth setting on every call: the ceremony a response
+ * belongs to is fixed, and accepting a `webauthn.create` where a `webauthn.get` was
+ * expected is a credential-registration response replayed as a login.
+ *
+ * @opts
+ *   expectedType      -- "webauthn.create" or "webauthn.get"
+ *   expectedChallenge -- the challenge bytes this ceremony issued (Buffer)
+ *   expectedOrigin    -- the origin string, or an array of acceptable origins
+ *
+ * @example
+ *   // requires: `clientDataJSON` -- credential.response.clientDataJSON;
+ *   // `issuedChallenge` -- the random bytes this server sent
+ *   var cd = pki.webauthn.parseClientData(clientDataJSON, {
+ *     expectedType: "webauthn.get",
+ *     expectedChallenge: issuedChallenge,
+ *     expectedOrigin: "https://example.com",
+ *   });
+ *   cd.checked.challenge;   // true -- the issued challenge came back
+ *   cd.crossOrigin;         // false
+ */
+function parseClientData(bytes, opts) {
+  opts = opts || {};
+  if (!_isPlainObject(opts)) throw _err("webauthn/bad-input", "opts must be an object");
+  guard.identifier.assertKnownKeys(opts, _CLIENT_DATA_OPTS, _err, "webauthn/bad-input", "opts has an unknown key ");
+  if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+    throw _err("webauthn/bad-input", "clientDataJSON must be the RAW Buffer or Uint8Array, not a parsed object");
+  }
+  var doc = guard.json.parse(Buffer.from(bytes), _err, {
+    maxBytes: constants.LIMITS.JSON_MAX_BYTES, maxDepth: constants.LIMITS.JSON_MAX_DEPTH,
+    badJson: "webauthn/bad-client-data", tooDeep: "webauthn/bad-client-data",
+    duplicateMember: "webauthn/bad-client-data", tooLarge: "webauthn/bad-client-data",
+    badInput: "webauthn/bad-input", label: "clientDataJSON",
+  });
+  if (!_isPlainObject(doc)) throw _err("webauthn/bad-client-data", "clientDataJSON is not a JSON object (WebAuthn sec. 5.8.1)");
+  if (typeof doc.type !== "string" || CLIENT_DATA_TYPE[doc.type] !== 1) {
+    throw _err("webauthn/bad-client-data",
+      "clientDataJSON type must be \"webauthn.create\" or \"webauthn.get\", got " + JSON.stringify(doc.type) +
+      " (WebAuthn sec. 5.8.1)");
+  }
+  if (typeof doc.origin !== "string" || !doc.origin.length) {
+    throw _err("webauthn/bad-client-data", "clientDataJSON carries no origin (WebAuthn sec. 5.8.1)");
+  }
+  if (typeof doc.challenge !== "string" || !doc.challenge.length) {
+    throw _err("webauthn/bad-client-data", "clientDataJSON carries no challenge (WebAuthn sec. 5.8.1)");
+  }
+  // base64url, and STRICTLY: the challenge is a comparison key, so an encoding the
+  // decoder had to guess at would let two spellings of one value both "match".
+  var challenge;
+  try {
+    challenge = guard.encoding.base64url(doc.challenge, constants.LIMITS.JSON_MAX_BYTES, _err,
+      "webauthn/bad-client-data", "the clientDataJSON challenge");
+  } catch (e) {
+    if (e && e.code === "webauthn/bad-client-data") throw e;
+    throw _err("webauthn/bad-client-data", "the clientDataJSON challenge is not base64url (WebAuthn sec. 5.8.1)", e);
+  }
+  if (doc.crossOrigin !== undefined && typeof doc.crossOrigin !== "boolean") {
+    throw _err("webauthn/bad-client-data", "clientDataJSON crossOrigin must be a boolean when present (WebAuthn sec. 5.8.1)");
+  }
+  // A present-but-malformed topOrigin is refused rather than reported as absent. It
+  // is the top-level origin of a cross-origin ceremony -- something a caller makes a
+  // policy decision on -- so "the sender wrote something that is not an origin" and
+  // "the sender said nothing" must not arrive as the same `null`.
+  if (doc.topOrigin !== undefined && (typeof doc.topOrigin !== "string" || !doc.topOrigin.length)) {
+    throw _err("webauthn/bad-client-data", "clientDataJSON topOrigin must be a non-empty string when present (WebAuthn sec. 5.8.1)");
+  }
+
+  var checked = { type: false, challenge: false, origin: false };
+  if (opts.expectedType !== undefined) {
+    if (CLIENT_DATA_TYPE[opts.expectedType] !== 1) {
+      throw _err("webauthn/bad-input", "opts.expectedType must be \"webauthn.create\" or \"webauthn.get\"");
+    }
+    if (doc.type !== opts.expectedType) {
+      throw _err("webauthn/client-data-mismatch",
+        "this is a " + doc.type + " response and a " + opts.expectedType + " one was expected -- a response " +
+        "from the other ceremony (WebAuthn sec. 7.1 step 8 / sec. 7.2 step 11)");
+    }
+    checked.type = true;
+  }
+  if (opts.expectedChallenge !== undefined) {
+    if (!Buffer.isBuffer(opts.expectedChallenge) && !(opts.expectedChallenge instanceof Uint8Array)) {
+      throw _err("webauthn/bad-input", "opts.expectedChallenge must be the raw challenge bytes");
+    }
+    if (!guard.crypto.constantTimeEqual(Buffer.from(opts.expectedChallenge), challenge)) {
+      throw _err("webauthn/client-data-mismatch",
+        "the clientDataJSON challenge is not the one this ceremony issued (WebAuthn sec. 7.1 step 9 / sec. 7.2 step 12)");
+    }
+    checked.challenge = true;
+  }
+  if (opts.expectedOrigin !== undefined) {
+    var allowed = Array.isArray(opts.expectedOrigin) ? opts.expectedOrigin : [opts.expectedOrigin];
+    if (!allowed.length || !allowed.every(function (o) { return typeof o === "string" && o.length; })) {
+      throw _err("webauthn/bad-input", "opts.expectedOrigin must be a non-empty origin string, or an array of them");
+    }
+    // Compared WHOLE and case-sensitively as the serialization it is. A prefix or
+    // suffix test is how "https://example.com.attacker.tld" passes for
+    // "https://example.com".
+    if (allowed.indexOf(doc.origin) === -1) {
+      throw _err("webauthn/client-data-mismatch",
+        "the clientDataJSON origin " + JSON.stringify(doc.origin) + " is not one this relying party accepts " +
+        "(WebAuthn sec. 7.1 step 10 / sec. 7.2 step 13)");
+    }
+    checked.origin = true;
+  }
+  return {
+    type: doc.type, challenge: challenge, origin: doc.origin,
+    crossOrigin: doc.crossOrigin === undefined ? false : doc.crossOrigin,
+    topOrigin: doc.topOrigin === undefined ? null : doc.topOrigin,
+    checked: checked,
+  };
+}
+var _CLIENT_DATA_OPTS = Object.assign(Object.create(null), {
+  expectedType: 1, expectedChallenge: 1, expectedOrigin: 1,
+});
+
+// ---- public: parseAuthenticatorData / verifyAssertion ------------------------
+
+/**
+ * @primitive pki.webauthn.parseAuthenticatorData
+ * @signature pki.webauthn.parseAuthenticatorData(bytes) -> { rpIdHash, flags, signCount, aaguid, credentialId, credentialPublicKey, extensions }
+ * @since 0.5.0
+ * @status experimental
+ * @spec W3C WebAuthn Level 3 sec. 6.1
+ * @related pki.webauthn.verifyAssertion, pki.webauthn.parseAttestationObject
+ *
+ * Decode a BARE authenticatorData, fail-closed -- the form an authentication
+ * assertion returns, with no attestation-object wrapper around it. Same parser the
+ * registration path uses: the 37-byte minimum, the reserved (RFU) flag bits, the
+ * Backup State / Backup Eligibility rule, the 1..1023 credentialId bound, a
+ * credential public key that must be one well-formed COSE_Key, and extensions that
+ * must be exactly one CBOR map when the ED flag is set and absent when it is clear.
+ * `flags` is decoded to `{ up, uv, be, bs, at, ed }`. An assertion normally has the
+ * AT flag clear, so `aaguid` / `credentialId` / `credentialPublicKey` are null.
+ * Malformed input throws `webauthn/bad-auth-data`.
+ *
+ * @example
+ *   // requires: `authenticatorData` -- credential.response.authenticatorData from
+ *   // navigator.credentials.get()
+ *   var ad = pki.webauthn.parseAuthenticatorData(authenticatorData);
+ *   ad.flags.up;      // true when the user was present
+ *   ad.signCount;     // the authenticator's counter for this credential
+ */
+function parseAuthenticatorData(bytes) {
+  if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+    throw _err("webauthn/bad-input", "authenticatorData must be a Buffer or Uint8Array");
+  }
+  return _parseAuthData(guard.bytes.snapshotSource(bytes, WebauthnError, "webauthn/bad-input", "authenticatorData"), _err);
+}
+
+// The options pki.webauthn.verifyAssertion recognises, null-prototype for the same
+// reason _VERIFY_OPTS is.
+var _ASSERT_OPTS = Object.assign(Object.create(null), {
+  authenticatorData: 1, clientDataHash: 1, clientDataJSON: 1, signature: 1,
+  credentialPublicKey: 1, previousSignCount: 1,
+  expectedRpId: 1, requireUserPresence: 1, requireUserVerification: 1, allowedAlgorithms: 1,
+  expectedChallenge: 1, expectedOrigin: 1,
+});
+
+/**
+ * @primitive pki.webauthn.verifyAssertion
+ * @signature pki.webauthn.verifyAssertion(input) -> Promise<{ signatureVerified, signCount, signCountChecked, flags, rpIdHash, bindingChecked }>
+ * @since 0.5.0
+ * @status experimental
+ * @spec W3C WebAuthn Level 3 sec. 7.2
+ * @defends webauthn-assertion-forgery (CWE-347)
+ * @related pki.webauthn.parseAuthenticatorData, pki.webauthn.verify
+ *
+ * Verify an authentication assertion's signature: the authenticator signs
+ * `authenticatorData || SHA-256(clientDataJSON)` as RAW bytes with the credential
+ * key registered earlier -- no COSE_Sign1 wrapper, so a COSE message verifier is
+ * the wrong tool and fails on structure before it ever reaches the signature. An
+ * ES256 assertion signature is an ASN.1 DER `SEQUENCE { r, s }`, converted here
+ * with the same order-aware reader the attestation path uses, so an r or s outside
+ * `[1, n-1]` is refused rather than normalized.
+ *
+ * `signatureVerified`, not `verified`: this establishes that the holder of the
+ * registered credential key produced this response. What makes the response
+ * ACCEPTABLE is the sec. 7.2 binding, and the caller owns most of it. Supply
+ * `expectedRpId`, `requireUserPresence`, `requireUserVerification` and
+ * `allowedAlgorithms` and they are checked here -- `bindingChecked` reports which
+ * ones ran, so a check that passed is distinguishable from one that never
+ * happened. The CHALLENGE and the ORIGIN stay with the caller: both live in
+ * clientDataJSON and are compared against state only the relying party has.
+ *
+ * Pass `previousSignCount` (the value stored at registration or the last login) and
+ * the sec. 7.2 step 21 counter rule is applied: a counter that fails to advance is
+ * a cloned authenticator and is refused, except for the `0`/`0` case an
+ * authenticator that does not implement a counter reports. Without it the counter
+ * is surfaced and not judged, and `signCountChecked` says so.
+ *
+ * @opts
+ *   authenticatorData -- the raw bytes from the assertion (Buffer)
+ *   clientDataJSON    -- the raw clientDataJSON bytes; its SHA-256 is what the signature covers
+ *   clientDataHash    -- the 32-byte digest instead, when the caller already has it
+ *   signature         -- the assertion signature bytes
+ *   credentialPublicKey -- the stored COSE key (as parseAttestationObject surfaced it)
+ *   previousSignCount -- the stored counter, enabling the sec. 7.2 step 21 rule
+ *   expectedRpId, requireUserPresence, requireUserVerification, allowedAlgorithms -- the bindings above
+ *
+ * @example
+ *   // requires: `assertion` -- credential.response from navigator.credentials.get();
+ *   // `storedKey` -- the COSE credentialPublicKey kept at registration
+ *   var res = await pki.webauthn.verifyAssertion({
+ *     authenticatorData: assertion.authenticatorData,
+ *     clientDataJSON: assertion.clientDataJSON,
+ *     signature: assertion.signature,
+ *     credentialPublicKey: storedKey,
+ *     expectedRpId: "example.com", requireUserPresence: true,
+ *   });
+ *   res.signatureVerified;      // true
+ *   res.bindingChecked.rpId;    // true -- the rpIdHash matched example.com
+ *   // the challenge and origin in clientDataJSON are still yours to compare
+ */
+// A private copy of the assertion inputs. Only what the caller can still write to
+// is copied: the byte fields, the descriptor itself, and the option arrays. The
+// COSE key is a decoded object the caller supplies from its own storage; it is
+// shallow-copied so a swapped field cannot reach the verification, which is the
+// mutation this can defend against without deep-copying an arbitrary object.
+function _snapshotAssertion(input) {
+  if (!_isPlainObject(input)) throw _err("webauthn/bad-input", "pki.webauthn.verifyAssertion takes an options object");
+  guard.identifier.assertKnownKeys(input, _ASSERT_OPTS, _err, "webauthn/bad-input", "verifyAssertion input has an unknown key ");
+  var out = {}, k;
+  for (k in input) { if (Object.prototype.hasOwnProperty.call(input, k)) out[k] = input[k]; }
+  ["authenticatorData", "clientDataJSON", "clientDataHash", "signature", "expectedChallenge"].forEach(function (f) {
+    if (Buffer.isBuffer(out[f]) || out[f] instanceof Uint8Array || out[f] instanceof ArrayBuffer) {
+      out[f] = guard.bytes.snapshotSource(out[f], WebauthnError, "webauthn/bad-input", f);
+    }
+  });
+  if (_isPlainObject(out.credentialPublicKey)) {
+    var key = {}, kk;
+    for (kk in out.credentialPublicKey) {
+      if (!Object.prototype.hasOwnProperty.call(out.credentialPublicKey, kk)) continue;
+      var v = out.credentialPublicKey[kk];
+      key[kk] = (Buffer.isBuffer(v) || v instanceof Uint8Array) ? Buffer.from(v) : v;
+    }
+    out.credentialPublicKey = key;
+  }
+  if (Array.isArray(out.allowedAlgorithms)) out.allowedAlgorithms = out.allowedAlgorithms.slice();
+  if (Array.isArray(out.expectedOrigin)) out.expectedOrigin = out.expectedOrigin.slice();
+  return out;
+}
+
+function verifyAssertion(input) {
+  // Every byte this verdict depends on is COPIED here, synchronously, before
+  // anything defers. The descriptor is the caller's object and the buffers in it
+  // are the caller's memory: a caller that reuses or zeroizes them on the line
+  // after this call has already changed them before the deferred body would run,
+  // and an assertion that did not verify could be replaced by one that does. The
+  // same rule pki.cmc.verify applies to a response, for the same reason.
+  var frozen;
+  try { frozen = _snapshotAssertion(input); } catch (e) { return Promise.reject(e); }
+  return Promise.resolve().then(function () {
+    input = frozen;
+    var authData = parseAuthenticatorData(input.authenticatorData);
+    if (!Buffer.isBuffer(input.signature) && !(input.signature instanceof Uint8Array)) {
+      throw _err("webauthn/bad-input", "signature must be a Buffer or Uint8Array");
+    }
+    // The two forms of the same input, and NEITHER is inferred from the other's
+    // absence: supplying both invites them to disagree, and picking one would make
+    // the signature cover something the caller did not mean.
+    var haveJson = input.clientDataJSON !== undefined, haveHash = input.clientDataHash !== undefined;
+    if (haveJson === haveHash) {
+      throw _err("webauthn/bad-input", "verifyAssertion takes exactly one of clientDataJSON or clientDataHash");
+    }
+    var clientDataHash, clientData = null;
+    if (haveJson) {
+      if (!Buffer.isBuffer(input.clientDataJSON) && !(input.clientDataJSON instanceof Uint8Array)) {
+        throw _err("webauthn/bad-input", "clientDataJSON must be a Buffer or Uint8Array (the RAW bytes, not a parsed object)");
+      }
+      // Given the JSON, this verb reads it -- the ceremony TYPE is checked
+      // unconditionally, because which ceremony a response belongs to is fixed by
+      // the spec rather than chosen by the caller, and a registration response
+      // replayed as a login is exactly what that check stops. The challenge and
+      // origin are checked when the caller supplies what it issued.
+      clientData = parseClientData(input.clientDataJSON, {
+        expectedType: "webauthn.get",
+        expectedChallenge: input.expectedChallenge,
+        expectedOrigin: input.expectedOrigin,
+      });
+      clientDataHash = _sha("sha256", Buffer.from(input.clientDataJSON));
+    } else {
+      if (input.expectedChallenge !== undefined || input.expectedOrigin !== undefined) {
+        throw _err("webauthn/bad-input",
+          "expectedChallenge / expectedOrigin are checked against clientDataJSON, which this call did not " +
+          "supply -- pass clientDataJSON instead of clientDataHash, or check them yourself");
+      }
+      if (!Buffer.isBuffer(input.clientDataHash) || input.clientDataHash.length !== 32) {
+        throw _err("webauthn/bad-input", "clientDataHash must be a 32-byte SHA-256 digest");
+      }
+      clientDataHash = Buffer.from(input.clientDataHash);
+    }
+    var coseKey = input.credentialPublicKey;
+    if (!_isPlainObject(coseKey)) {
+      throw _err("webauthn/bad-input", "credentialPublicKey must be the stored COSE key object");
+    }
+    var bindingChecked = _applyBindings(authData, coseKey, input);
+    // The counter's SHAPE is a config-time question and is answered here; whether it
+    // advanced is a question about the message, and that is asked only after the
+    // signature holds -- see below.
+    var prev = input.previousSignCount;
+    if (prev !== undefined && (typeof prev !== "number" || !Number.isSafeInteger(prev) || prev < 0 || prev > 0xFFFFFFFF)) {
+      throw _err("webauthn/bad-input", "previousSignCount must be an integer in 0..4294967295");
+    }
+    // The signed message is the CONCATENATION, in that order, of the
+    // authenticatorData exactly as it arrived and the clientDataJSON digest.
+    var message = Buffer.concat([Buffer.from(input.authenticatorData), clientDataHash]);
+    var spki = _coseKeyToSpki(coseKey);
+    return _verifySig(coseKey.alg, Buffer.from(input.signature), spki, message, _err).then(function (ok) {
+      if (!ok) {
+        throw _err("webauthn/bad-signature",
+          "the assertion signature does not verify under the stored credential public key (WebAuthn sec. 7.2 step 20)");
+      }
+      // sec. 7.2 step 21, and only NOW. A counter that fails to advance means two
+      // authenticators hold one credential -- an alarm a relying party acts on, by
+      // locking the account or revoking the credential. Judging it before the
+      // signature would let anyone raise that alarm with arbitrary bytes, so the
+      // counter is read only out of an assertion that proved to be authentic. The
+      // 0/0 case is an authenticator that implements no counter, which is permitted.
+      var signCountChecked = false;
+      if (prev !== undefined) {
+        if (!(prev === 0 && authData.signCount === 0) && authData.signCount <= prev) {
+          throw _err("webauthn/sign-count-not-advanced",
+            "the assertion signCount " + authData.signCount + " does not advance past the stored " + prev +
+            ", which is the signal of a cloned authenticator (WebAuthn sec. 7.2 step 21)");
+        }
+        signCountChecked = true;
+      }
+      return {
+        signatureVerified: true,
+        signCount: authData.signCount,
+        signCountChecked: signCountChecked,
+        flags: authData.flags,
+        rpIdHash: authData.rpIdHash,
+        extensions: authData.extensions,
+        // The decoded clientData when this call was given the JSON, so a caller that
+        // still owes itself a comparison has the values without re-parsing; null
+        // when only the digest was supplied and there was nothing to read.
+        clientData: clientData,
+        bindingChecked: bindingChecked,
+      };
+    });
+  });
+}
+
 module.exports = {
   parseAttestationObject: parseAttestationObject,
+  parseAuthenticatorData: parseAuthenticatorData,
+  parseClientData: parseClientData,
   verify: verify,
+  verifyAssertion: verifyAssertion,
   verifyMetadataBlob: mds.verifyMetadataBlob,
   metadataFor: mds.metadataFor,
   metadataAnchors: mds.metadataAnchors,