@blamejs/pki 0.5.1 → 0.5.3

package/lib/webauthn.js

@@ -34,7 +34,6 @@ var validator = require("./validator-all");
 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");
 
@@ -73,7 +72,7 @@ function _isInteger(node) { return !!node && !node.constructed && node.tagClass
 // step rejects the attestation before the signature is evaluated. EdDSA (-8/-19/-53) is
 // absent by design: a TPM 2.0 AIK never signs with EdDSA, so such an attestation is
 // correctly refused.
-var COSE_ALG_HASH = { "-7": "sha256", "-9": "sha256", "-257": "sha256", "-37": "sha256", "-35": "sha384", "-51": "sha384", "-258": "sha384", "-36": "sha512", "-52": "sha512", "-259": "sha512", "-65535": "sha1" };
+var COSE_ALG_HASH = { "-7": "sha256", "-9": "sha256", "-257": "sha256", "-37": "sha256", "-35": "sha384", "-51": "sha384", "-258": "sha384", "-38": "sha384", "-36": "sha512", "-52": "sha512", "-259": "sha512", "-39": "sha512", "-65535": "sha1" };
 function _coseAlgHash(alg, E) {
   var h = COSE_ALG_HASH[String(alg)];
   if (!h) throw E("webauthn/unsupported-algorithm", "no hash mapping for COSE algorithm " + alg);
@@ -141,7 +140,51 @@ function _parseAuthData(buf, E) {
 // The complete COSE credential-key conformance rule set (kty/alg/crv/length/canonical/
 // profile/on-curve) lives in validator-cose, composed here so every credential key
 // routes through the one home -- never a per-format re-derivation of a partial subset.
-function _decodeCoseKey(node) { return validator.cose.credentialKey(node, WebauthnError, "webauthn/bad-cose-key"); }
+function _decodeCoseKey(node) {
+  return validator.cose.credentialKey(node, WebauthnError, "webauthn/bad-cose-key", "webauthn/unsupported-algorithm");
+}
+
+/**
+ * @primitive  pki.webauthn.parseCoseKey
+ * @signature  pki.webauthn.parseCoseKey(bytes) -> object
+ * @since      0.5.2
+ * @status     stable
+ * @spec       RFC 9052, W3C WebAuthn Level 3 sec. 6.5.1
+ * @related    pki.webauthn.verify, pki.webauthn.verifyAssertion
+ *
+ * Decode a bare COSE_Key -- the credential public key a relying party stored at
+ * registration -- back into the object `verifyAssertion` takes. `pki.webauthn.verify`
+ * returns that object, but the durable form is bytes: the object carries `Buffer`
+ * values, so a JSON round trip through a datastore yields
+ * `{"type":"Buffer","data":[...]}` rather than the object that went in, and existing
+ * credential stores already hold COSE bytes whoever wrote them. Without this the only
+ * routes into the decoder were `parseAttestationObject` and `parseAuthenticatorData`,
+ * both of which parse a CONTAINING structure -- so recovering a stored key meant
+ * fabricating an authenticatorData that never existed.
+ *
+ * The same validation the attestation path applies: the key type, the algorithm, the
+ * curve, and the coordinates are checked, and anything that is not a credential COSE
+ * key is refused with `webauthn/bad-cose-key`. `verifyAssertion` accepts either form
+ * for `credentialPublicKey`, so calling this first is a convenience rather than a step.
+ *
+ * @example
+ *   // requires: `attestationObject` / `clientDataHash` -- what a browser returns from a
+ *   // registration ceremony
+ *   var reg = await pki.webauthn.verify(attestationObject, clientDataHash, {});
+ *   var stored = reg.credentialPublicKeyBytes;   // the form a credential row holds
+ *   // ... at a login months later, read it back:
+ *   var key = pki.webauthn.parseCoseKey(stored);
+ *   key.alg;   // -> -7 for ES256
+ *   // verifyAssertion takes either form, so this parse is a convenience, not a step:
+ *   // pass `stored` straight as its credentialPublicKey.
+ */
+function parseCoseKey(bytes) {
+  var buf = _bytesArg(bytes, "the COSE key");
+  var node;
+  try { node = cbor.decode(buf); }
+  catch (e) { throw _err("webauthn/bad-cose-key", "the stored credential key is not decodable CBOR", e); }
+  return _decodeCoseKey(node);
+}
 
 // ---- signature verification bridge ------------------------------------------
 
@@ -165,7 +208,11 @@ var COSE_ALG = {
   "-257": { imp: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, verify: { name: "RSASSA-PKCS1-v1_5" }, ecdsa: 0 },
   "-258": { imp: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-384" }, verify: { name: "RSASSA-PKCS1-v1_5" }, ecdsa: 0 },
   "-259": { imp: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-512" }, verify: { name: "RSASSA-PKCS1-v1_5" }, ecdsa: 0 },
+  // RSASSA-PSS. The salt length is the hash length, the profile WebCrypto verifies and the one
+  // RFC 8230 sec. 2 fixes for the COSE PS* identifiers -- 32 / 48 / 64 bytes for SHA-256/384/512.
   "-37":  { imp: { name: "RSA-PSS", hash: "SHA-256" }, verify: { name: "RSA-PSS", saltLength: 32 }, ecdsa: 0 },
+  "-38":  { imp: { name: "RSA-PSS", hash: "SHA-384" }, verify: { name: "RSA-PSS", saltLength: 48 }, ecdsa: 0 },
+  "-39":  { imp: { name: "RSA-PSS", hash: "SHA-512" }, verify: { name: "RSA-PSS", saltLength: 64 }, ecdsa: 0 },
   // RS1 (RSASSA-PKCS1-v1_5 / SHA-1): a legacy COSE algorithm real Windows Hello TPM
   // authenticators emit in their attestation statement. VERIFY-only support -- the
   // toolkit never signs with SHA-1; it must still evaluate the attestations that
@@ -193,7 +240,7 @@ function _verifySig(alg, sig, spkiBytes, message, E) {
   // low-order (e.g. all-zeroes) key verifies a trivial signature -- so validate the OKP
   // point before verify. This covers EVERY key that signs a WebAuthn statement: the x5c
   // attestation-certificate key (packed/tpm/apple) AND the self-attestation credential key.
-  if (imp.name === "Ed25519" || imp.name === "Ed448") _requireValidEdPoint(spkiBytes, imp.name, E);
+  if (imp.name === "Ed25519" || imp.name === "Ed448") _requireValidEdPoint(spkiBytes, imp.name);
   var s = d.ecdsa ? _derEcdsaToRaw(sig, d.imp.namedCurve) : sig;
   return subtle.importKey("spki", spkiBytes, imp, false, ["verify"])
     .then(function (key) { return subtle.verify(ver, key, s, message); })
@@ -211,17 +258,14 @@ function _edName(spkiBytes, E) {
   if (!nm) throw E("webauthn/unsupported-algorithm", "unsupported EdDSA curve OID " + algOid);
   return nm;
 }
-// The raw Edwards point an OKP SPKI carries (its BIT STRING body, past the unused-bits
-// octet) MUST be a valid, full-order point -- reject an off-curve or low-order key before it
-// verifies a signature (WebCrypto import does not check it). Curve from the WebCrypto name.
-function _requireValidEdPoint(spkiBytes, name, E) {
-  var content;
-  try { content = asn1.decode(spkiBytes).children[1].content; }
-  catch (e) { throw E("webauthn/bad-signature", "the EdDSA public key is not a well-formed SPKI", e); }
-  var point = content && content.length ? content.subarray(1) : Buffer.alloc(0);
-  if (!edwardsPoint.validate(point, name === "Ed25519" ? 6 : 7)) {
-    throw E("webauthn/bad-signature", "the EdDSA public key is not a valid, full-order Edwards point");
-  }
+// The raw Edwards point an OKP SPKI carries MUST be a valid, full-order point -- reject an
+// off-curve or low-order key before it verifies a signature, which WebCrypto import will not do.
+// Routed through edwards-point's own SPKI entry rather than extracting the point here: that module
+// documents itself as the one home every EdDSA verify path takes an SPKI through, and this was the
+// path that had its own copy. Keeping a second extraction is how one route comes to be guarded and
+// the next one written is not.
+function _requireValidEdPoint(spkiBytes, name) {
+  edwardsPoint.validateSpki(spkiBytes, name === "Ed25519" ? 6 : 7, WebauthnError, "webauthn/bad-signature");
 }
 
 // A validated COSE credential key -> a self-contained SPKI the WebCrypto import
@@ -244,11 +288,39 @@ function _certEcCurveOid(cert, E) {
   try { return asn1.read.oid(asn1.decode(params)); }
   catch (e) { throw E("webauthn/key-mismatch", "the attestation certificate EC curve is not a valid OBJECT IDENTIFIER", e); }
 }
+// Which certificate key ALGORITHMS a credential key of each COSE type may be carried by. Two keys
+// are the same key only if they are the same KIND of key: the bytes alone do not say what a key is,
+// and for the Edwards curves they cannot -- an X25519 key-agreement key and an Ed25519 signing key
+// are both 32 raw bytes, so a certificate declaring the former would otherwise compare equal to a
+// credential key declaring the latter and be accepted as its attestation certificate. The EC2
+// branch already asked this question as a curve check; asking it only there left the two key types
+// whose confusion is undetectable from the material to be decided on the material alone.
+// A row per COSE key type, keyed the way every other algorithm decision in this toolkit is.
+function _certKeyAlgNames(cose) {
+  if (cose.kty === 2) return ["ecPublicKey"];
+  // An RSA key may be carried under the general OID or under id-RSASSA-PSS, which restricts it to
+  // PSS but is the same key (RFC 4055 sec. 1.2).
+  if (cose.kty === 3) return ["rsaEncryption", "rsassaPss"];
+  if (cose.kty === 1) {
+    var okp = validator.cose.OKP_CRV[cose.crv];
+    return okp ? [okp.oid] : [];
+  }
+  return [];
+}
+function _assertCertKeyAlgorithm(cert, cose, E) {
+  var alg = (cert.subjectPublicKeyInfo && cert.subjectPublicKeyInfo.algorithm) || {};
+  var want = _certKeyAlgNames(cose);
+  if (!want.length || want.indexOf(alg.name) < 0) {
+    throw E("webauthn/key-mismatch", "the attestation certificate carries a " + JSON.stringify(alg.name) +
+      " key, which is not the kind of key the credential public key declares");
+  }
+}
 // A void assert: throws webauthn/key-mismatch on any inequality, returns nothing on
 // success (called for its throw side-effect, like the other _check* asserts).
 function _certPubKeyEqualsCose(cert, cose, E) {
   var raw = cert.subjectPublicKeyInfo && cert.subjectPublicKeyInfo.publicKey && cert.subjectPublicKeyInfo.publicKey.bytes;
   if (!raw) throw E("webauthn/key-mismatch", "the attestation certificate exposes no public key");
+  _assertCertKeyAlgorithm(cert, cose, E);
   if (cose.kty === 2) {
     // The certificate's declared EC curve MUST equal the credential key's curve --
     // a curve substitution is a different key even if the coordinate bytes line up.
@@ -408,8 +480,15 @@ 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,
+  clientDataJSON: 1, expectedChallenge: 1, expectedOrigin: 1, expectedTopOrigin: 1,
 });
 
+// The boolean switches whose only reader sits inside ONE format's arm, so nothing else would ever
+// examine them. The binding switches are absent because _applyBindings owns their type and runs on
+// every format and on the assertion path too -- a second copy of that rule here would be a second
+// place for it to drift.
+var _FORMAT_SCOPED_BOOLEAN_OPTS = ["verifySafetyNetJws", "requireCtsProfileMatch"];
+
 // 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
@@ -464,22 +543,34 @@ function _cloneParsed(v, depth) {
 }
 
 // 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) {
+// rewrite, and accepted in every form the W3C BufferSource contract defines.
+//
+// ONE accepted set, for every byte argument on this namespace. The forms differed per argument
+// before -- an attestation object took an ArrayBuffer while the clientDataHash beside it took only
+// a Buffer -- and the caller producing both is the same one: `crypto.subtle.digest` returns an
+// ArrayBuffer, so the natural way to compute that hash produced a value this verb refused. Which
+// forms an argument accepts is not a per-argument decision; it is the namespace's contract, and it
+// is made once here.
+//
+// Anything that is not a BufferSource is refused BY NAME, rather than passed down to be described
+// by whichever parser reaches it first.
+function _isBufferSource(v) { return ArrayBuffer.isView(v) || v instanceof ArrayBuffer; }
+function _bytesArg(v, label) {
+  if (_isBufferSource(v)) {
     return guard.bytes.snapshotSource(v, WebauthnError, "webauthn/bad-input", label);
   }
-  return v;
+  throw _err("webauthn/bad-input", label + " must be a BufferSource (a Buffer, a typed-array view, or an ArrayBuffer)");
 }
 
 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[]");
+    // Every byte form, tested BEFORE the parsed-object branch: a DataView is an object too, so a
+    // narrower byte test does not merely miss the copy -- it sends those bytes down the branch for
+    // parsed certificates, which deep-copies a typed array field by field into something that is no
+    // longer a certificate at all.
+    if (_isBufferSource(root)) {
+      return guard.bytes.snapshotSource(root, WebauthnError, "webauthn/bad-input", "opts.rootCertificates[]");
     }
     if (root && typeof root === "object") return _cloneParsed(root, 0);
     return root;   // a PEM string is immutable
@@ -502,7 +593,7 @@ function _applyCallerRoots(res, supplied, vopts, onlyPaths) {
   // 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; }
+    try { cert = _isBufferSource(root) ? x509.parse(guard.bytes.source(root, WebauthnError, "webauthn/bad-input", "opts.rootCertificates[" + i + "]")) : (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");
@@ -598,10 +689,6 @@ function _anchoredRoutes(res, base) {
 // 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");
 }
@@ -854,10 +941,8 @@ var VERIFIERS = {
   // existed. There is no bundled root and no trust-on-first-use.
   "android-safetynet": function (att, clientDataHash, opts) {
     opts = opts || {};
+    // The type is settled at the entry point, so what remains here is the opt-in itself.
     if (opts.verifySafetyNetJws !== true) {
-      if (opts.verifySafetyNetJws !== undefined && typeof opts.verifySafetyNetJws !== "boolean") {
-        throw _err("webauthn/bad-input", "opts.verifySafetyNetJws must be a boolean");
-      }
       throw _err("webauthn/unsupported-format", "attestation statement format 'android-safetynet' is not supported");
     }
     var roots = opts.safetyNetRoots;
@@ -941,9 +1026,6 @@ var VERIFIERS = {
     if (opts.requireCtsProfileMatch === true && signals.ctsProfileMatch !== true) {
       throw _err("webauthn/safetynet-cts-profile", "the android-safetynet response reports ctsProfileMatch " + JSON.stringify(signals.ctsProfileMatch) + ", and opts.requireCtsProfileMatch demands true");
     }
-    if (opts.requireCtsProfileMatch !== undefined && typeof opts.requireCtsProfileMatch !== "boolean") {
-      throw _err("webauthn/bad-input", "opts.requireCtsProfileMatch must be a boolean");
-    }
 
     return _verifySig(-257, sigBytes, leaf.subjectPublicKeyInfo.bytes,
       Buffer.from(segs[0] + "." + segs[1], "ascii"), _err).then(function (ok) {
@@ -1082,41 +1164,28 @@ function _safetyNetHostnameOk(leaf) {
 // rotation; the first that validates wins, and if none does the attestation is refused. The chain
 // goes through the full path validator rather than a signature-only walk, so an expired, revoked-by-
 // policy, or otherwise non-conforming intermediate cannot slip past on a signature alone.
+// The caller's roots are the only thing this function owns: their SHAPE is its own config-time
+// contract, so a root that is not a decodable certificate is named by its index here. Anchoring
+// itself is the namespace's one walk (webauthn-mds), which every other chain in this module already
+// reaches its anchors through -- including the anchor-stripping rule, which this had a slightly
+// different and weaker copy of. Each root is resolved BEFORE the walk starts, so a malformed entry
+// is a config fault whatever position it sits in, rather than one that only surfaces when the roots
+// before it happen to fail.
 function _safetyNetChainTrusted(chain, roots, time) {
-  var ordered = chain.slice().reverse();          // path.validate takes anchor-adjacent first
-  var when = time === undefined ? new Date() : time;
-  var attempts = roots.map(function (root, i) {
-    return function () {
+  var anchors;
+  try {
+    anchors = roots.map(function (root, i) {
       var anchorCert;
-      try { anchorCert = Buffer.isBuffer(root) || typeof root === "string" ? x509.parse(root) : root; }
+      try { anchorCert = _isBufferSource(root) ? x509.parse(guard.bytes.source(root, WebauthnError, "webauthn/bad-input", "opts.safetyNetRoots[" + i + "]")) : (typeof root === "string" ? x509.parse(root) : root); }
       catch (e) { throw _err("webauthn/bad-input", "opts.safetyNetRoots[" + i + "] is not a decodable certificate", e); }
       if (!anchorCert || !anchorCert.subject || !anchorCert.subjectPublicKeyInfo) {
         throw _err("webauthn/bad-input", "opts.safetyNetRoots[" + i + "] is not a certificate");
       }
-      // An x5c chain conventionally carries the root as its last entry. The anchor is supplied
-      // separately and is what establishes trust, so drop a trailing self-issued certificate that
-      // IS this anchor rather than validating it against itself as a path element.
-      var path = ordered.slice();
-      if (path.length > 1 && guard.name.dnEqual(path[0].subject, anchorCert.subject) &&
-          guard.name.dnEqual(path[0].issuer, path[0].subject)) {
-        path = path.slice(1);
-      }
-      return pathValidate.validate(path, {
-        time: when,
-        // 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; });
-    };
-  });
-  return attempts.reduce(function (p, next) {
-    return p.then(function (done) { return done ? true : next(); });
-  }, Promise.resolve(false)).then(function (trusted) {
-    if (!trusted) throw _err("webauthn/safetynet-cert-untrusted", "the android-safetynet x5c chain does not validate to any supplied root (opts.safetyNetRoots)");
-  });
+      return anchorCert;
+    });
+  } catch (e) { return Promise.reject(e); }
+  return mds.chainToAnchor(chain, anchors, time === undefined ? new Date() : time,
+    "android-safetynet x5c certificate chain", "webauthn/safetynet-cert-untrusted");
 }
 
 // `chain` is the x5c order (leaf-first); trustPath is surfaced in pki.path.validate
@@ -1139,8 +1208,23 @@ function _result(fmt, attestationType, chain, att) {
     aaguid: att.authData.aaguid,
     credentialId: att.authData.credentialId,
     credentialPublicKey: att.authData.credentialPublicKey,
+    // The same key in the form that SURVIVES STORAGE. The decoded object carries Buffers, so a JSON
+    // round trip through a datastore returns {"type":"Buffer","data":[...]} rather than what went
+    // in; the COSE bytes are what a credential row actually holds. Returning only the object left
+    // the caller re-parsing the attestation object to recover bytes this call had already isolated.
+    credentialPublicKeyBytes: att.authData.credentialPublicKeyBytes,
     signCount: att.authData.signCount,
     flags: att.authData.flags,
+    // The RP ID hash and the authenticator extension outputs, for the same reason the key bytes
+    // above are here: this call decoded them and the caller needs them. Extension outputs arrive
+    // at REGISTRATION and nowhere else -- credProtect (whether this credential is
+    // user-verification-required for the rest of its life), credProps.rk (whether it is
+    // discoverable), credBlob, minPinLength, hmac-secret/prf -- so a relying party that must
+    // persist them had to re-parse the attestation object to read values already in hand.
+    // `verifyAssertion` returns both; the registration verdict returning less made the two halves
+    // of one lifecycle disagree about what they hand back.
+    rpIdHash: att.authData.rpIdHash,
+    extensions: att.authData.extensions,
   };
 }
 
@@ -1176,7 +1260,7 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
 
 /**
  * @primitive pki.webauthn.verify
- * @signature pki.webauthn.verify(attestationObject, clientDataHash, opts) -> Promise<{ attestationVerified, fmt, attestationType, trustPath, anchoredTo, anchoredElements, aaguid, credentialId, credentialPublicKey, signCount, flags, bindingChecked }>
+ * @signature pki.webauthn.verify(attestationObject, clientDataHash?, opts?) -> Promise<{ attestationVerified, fmt, attestationType, trustPath, anchoredTo, aaguid, credentialId, credentialPublicKey, credentialPublicKeyBytes, signCount, flags, rpIdHash, extensions, bindingChecked, clientData }>
  * @since 0.2.5
  * @status stable
  * @spec W3C WebAuthn Level 3 sec. 8 / sec. 7.1
@@ -1184,11 +1268,19 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *
  * Verify a WebAuthn attestation statement: the attestation signature over
  * `authenticatorData || clientDataHash` and (for the x5c formats) the format's
- * certificate requirements. `clientDataHash` is the SHA-256 of the serialized client
- * data, supplied by the relying party. Resolves the attestation type + trust path or
+ * certificate requirements. Resolves the attestation type + trust path or
  * throws a typed `webauthn/*` error; a signature that does not verify is a
  * `webauthn/verify-failed` verdict, never a silent pass.
  *
+ * Give it the client data in exactly one of the two forms, neither inferred from the
+ * other's absence: the raw `opts.clientDataJSON`, or the SHA-256 digest of it as the
+ * second argument. Given the JSON, this reads it -- the ceremony TYPE is checked
+ * unconditionally, because which ceremony a response belongs to is fixed by the
+ * specification rather than chosen by a caller, and a login response replayed into a
+ * registration is exactly what that check stops. The challenge, origin and top-level
+ * origin are checked when you supply what you issued, and `clientData.checked` reports
+ * which ran. Given only the digest, nothing reads it and `clientData` is null.
+ *
  * 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
@@ -1196,12 +1288,20 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  * 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.
+ * told from one that never happened.
+ *
+ * Four more fields appear only where they mean something, rather than as nulls on every
+ * verdict: `metadata` when the catalogue governed, `anchoredElements` when a trust path
+ * was anchored, `compound` for a sec. 8.9 statement's per-element results, and
+ * `safetyNet` with `chainValidatedAt` for an android-safetynet response.
  *
  * The verdict also carries what a relying party must STORE to run a later login:
- * `credentialId`, `credentialPublicKey` and the initial `signCount`.
+ * `credentialId`, `credentialPublicKey` and the initial `signCount`. The credential key
+ * comes back in both forms: the decoded object, and `credentialPublicKeyBytes`, which is
+ * what a credential row should hold -- the object carries `Buffer` values, so a JSON round
+ * trip through a datastore returns `{"type":"Buffer","data":[...]}` rather than the object
+ * that went in. `pki.webauthn.parseCoseKey` reads those bytes back, and
+ * `verifyAssertion` accepts either form.
  *
  * @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
@@ -1233,19 +1333,48 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *   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.
  *
+ * @opts
+ *   clientDataJSON    -- the RAW clientDataJSON bytes; supply this OR the digest argument
+ *   expectedChallenge -- the challenge bytes this ceremony issued (needs clientDataJSON)
+ *   expectedOrigin    -- the origin string, or an array of acceptable origins
+ *   expectedTopOrigin -- the acceptable top-level origin(s), or null to require an
+ *                        unframed ceremony
+ *   expectedRpId      -- the RP ID whose SHA-256 the authenticatorData must carry
+ *   requireUserPresence / requireUserVerification -- the flags this registration requires
+ *   allowedAlgorithms -- the COSE algorithms this relying party accepts
+ *   metadata          -- a verifyMetadataBlob result; the model's own roots govern
+ *   rootCertificates  -- trust anchors you pin, for the models no catalogue lists
+ *   time              -- the instant certificate validity is judged at
+ *   tpmPolicy         -- required TPM key properties; refuses a non-TPM attestation
+ *   safetyNetRoots / verifySafetyNetJws / requireCtsProfileMatch -- the
+ *                        android-safetynet opt-in, its Google roots, and the
+ *                        device-integrity demand
+ *
  * @example
- *   // requires: `attestationObject` from navigator.credentials.create(), and
- *   // `clientDataHash` = SHA-256 of the matching credential.response.clientDataJSON
- *   var res = await pki.webauthn.verify(attestationObject, clientDataHash, {
+ *   // requires: `attestationObject` and `clientDataJSON` from
+ *   // navigator.credentials.create(), and `issuedChallenge` -- the bytes you sent
+ *   var res = await pki.webauthn.verify(attestationObject, {
+ *     clientDataJSON: clientDataJSON,
+ *     expectedChallenge: issuedChallenge,
+ *     expectedOrigin: "https://example.com",
  *     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,
+ *   res.attestationVerified;      // true (statement signature + bindings hold)
+ *   res.clientData.checked.type;  // true -- this really is a registration response
+ *   res.bindingChecked.rpId;      // true -- this response names example.com
+ *   res.attestationType;          // "Basic"
+ *   // store res.credentialId / res.credentialPublicKeyBytes / res.signCount for logins,
  *   // and anchor res.trustPath to your pinned roots with pki.path.validate
  */
 function verify(attestationObject, clientDataHash, opts) {
+  // Two call shapes, disjoint by shape so neither is guessed at: the digest positionally, or an
+  // options object carrying the clientDataJSON it is computed from. A Buffer IS an object, so the
+  // question has to be asked as "is this not bytes?" -- the disjointness is between a BufferSource
+  // and everything else, and testing only the second half swallows the ordinary two-argument call.
+  if (opts === undefined && clientDataHash !== undefined &&
+      !_isBufferSource(clientDataHash) && _isPlainObject(clientDataHash)) {
+    opts = clientDataHash; clientDataHash = undefined;
+  }
   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
@@ -1255,11 +1384,25 @@ function verify(attestationObject, clientDataHash, opts) {
   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 ");
+    // ONE read of the caller's object, HERE, and nothing below ever touches it again. Not a
+    // precaution about mutation across the deferred verification -- that was already the reason for
+    // the copy this replaces -- but about the reads themselves: a gate that reads `opts.x` to decide
+    // whether a demand was made, and a later step that reads `opts.x` again to act on it, are two
+    // reads of a value the caller still owns, and an accessor makes them disagree. The value that
+    // was CHECKED must be the value that is USED, which means checking and using the same copy.
+    // `Object.assign` takes every own enumerable field by value at this instant, which resolves any
+    // accessor exactly once.
+    opts = Object.assign({}, opts);
     if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+    // The boolean switches are typed HERE rather than in the arm that reads them. Validated only
+    // inside the android-safetynet arm, `requireCtsProfileMatch: "true"` reaching any other format
+    // is never examined at all -- a truthy string that demands nothing, silently accepted. A
+    // recognised key with an unusable value is the same class of caller mistake as an unrecognised
+    // key, and belongs at the same boundary.
+    _FORMAT_SCOPED_BOOLEAN_OPTS.forEach(function (k) {
+      if (opts[k] !== undefined && typeof opts[k] !== "boolean") throw _err("webauthn/bad-input", "opts." + k + " must be a boolean");
+    });
   } 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"));
-  }
   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
@@ -1270,10 +1413,49 @@ function verify(attestationObject, clientDataHash, opts) {
   // 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;
+  var attBytes, cdh, clientData = null;
   try {
-    attBytes = _snapshotBytes(attestationObject, "attestationObject");
-    cdh = _snapshotBytes(clientDataHash, "clientDataHash");
+    attBytes = _bytesArg(attestationObject, "attestationObject");
+    // The two forms of the same input, and NEITHER is inferred from the other's absence -- the
+    // same rule verifyAssertion applies, because it is the same question. Supplying both invites
+    // them to disagree, and picking one would make the attestation cover something the caller did
+    // not mean.
+    var haveJson = opts.clientDataJSON !== undefined, haveHash = clientDataHash !== undefined;
+    if (haveJson === haveHash) {
+      throw _err("webauthn/bad-input", "verify takes exactly one of clientDataJSON or the clientDataHash argument");
+    }
+    if (haveJson) {
+      // The bytes are taken ONCE and both the reading and the hashing use that copy. Checking one
+      // value and hashing another would bind the attestation to client data the ceremony checks
+      // never saw -- the check and the use have to be of the same bytes.
+      var cdjBytes = _bytesArg(opts.clientDataJSON, "opts.clientDataJSON");
+      // Given the JSON, the ceremony TYPE is checked unconditionally. Which ceremony a response
+      // belongs to is fixed by the specification rather than chosen by the caller, and a login
+      // response replayed into a registration is exactly what that check stops -- so registration
+      // gets the same non-negotiable rule the login path already had. Without this door there was
+      // no way to apply it at registration at all: the hash is opaque, and the caller was left to
+      // compare a value the attestation never bound.
+      clientData = parseClientData(cdjBytes, {
+        expectedType: "webauthn.create",
+        expectedChallenge: opts.expectedChallenge,
+        expectedOrigin: opts.expectedOrigin,
+        expectedTopOrigin: opts.expectedTopOrigin,
+      });
+      cdh = _sha("sha256", cdjBytes);
+    } else {
+      // Every expectation the clientData reader would have answered is unanswerable from a bare
+      // digest, so each is refused rather than left silently uncompared.
+      if (opts.expectedChallenge !== undefined || opts.expectedOrigin !== undefined ||
+          opts.expectedTopOrigin !== undefined) {
+        throw _err("webauthn/bad-input",
+          "expectedChallenge / expectedOrigin / expectedTopOrigin are checked against clientDataJSON, which this call " +
+          "did not supply -- pass opts.clientDataJSON instead of the clientDataHash argument, or check them yourself");
+      }
+      cdh = _bytesArg(clientDataHash, "clientDataHash");
+      // The LENGTH is checked on the normalized copy, so the digest is 32 bytes whichever form it
+      // arrived in -- not only when it arrived as a Buffer.
+      if (cdh.length !== 32) throw _err("webauthn/bad-input", "clientDataHash must be a 32-byte SHA-256 digest");
+    }
   } catch (e) { return Promise.reject(e); }
   attestationObject = attBytes;
   clientDataHash = cdh;
@@ -1293,9 +1475,17 @@ function verify(attestationObject, clientDataHash, opts) {
   // 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)) {
+  if (opts.tpmPolicy !== undefined && !_formatCarries(att, "tpm")) {
     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"));
   }
+  // The same rule, and the same reason, for the one other option that DEMANDS rather than supplies:
+  // ctsProfileMatch is an android-safetynet device-integrity signal, so no other format's statement
+  // carries one to test. Checked only inside that arm, a caller who demanded a CTS-matching device
+  // would get a pass from a `packed` or `none` attestation that was never asked the question.
+  // A caller who passes `false` demands nothing and is not refused.
+  if (opts.requireCtsProfileMatch === true && !_formatCarries(att, "android-safetynet")) {
+    return Promise.reject(_err("webauthn/safetynet-cts-profile", "opts.requireCtsProfileMatch requires an android-safetynet attestation, but this attestation is format '" + att.fmt + "', whose statement carries no device-integrity signals"));
+  }
   // 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
@@ -1327,6 +1517,14 @@ function verify(attestationObject, clientDataHash, opts) {
     });
   } catch (e) { return Promise.reject(e); }
   return Promise.resolve().then(function () { return verifier(att, clientDataHash, vopts); })
+    .then(function (res) {
+      // What the clientData reader found, on the verdict rather than left for the caller to
+      // recompute -- the same field the login verdict carries, for the same reason: `checked` is
+      // where a comparison that ran is told from one that never did. Null when the caller supplied
+      // only the digest, which is the honest answer: nothing read it.
+      res.clientData = clientData;
+      return res;
+    })
     .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
@@ -1467,7 +1665,10 @@ function _applyMetadata(res, att, opts) {
     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);
+    // The same three inputs the status check above used. metadataAnchors makes the same decision
+    // for the callers who reach it directly, so handing it different inputs is how the two readings
+    // would come to disagree about the same entry.
+    var anchors = mds.metadataAnchors(entry, { metadata: md, time: at, certificate: tp[tp.length - 1] });
     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 };
@@ -1564,15 +1765,20 @@ function _applyMetadata(res, att, opts) {
     });
 }
 
-// Only an attestation that actually carries a TPM public area can satisfy a TPM policy: the tpm
-// format directly, or a compound holding at least one tpm element (whose own arm applies it).
-function _formatCanSatisfyTpmPolicy(att) {
-  if (att.fmt === "tpm") return true;
+// Does this attestation carry a statement of the named format -- as the whole statement, or as one
+// element of a compound (sec. 8.9), whose own arm would apply a policy about that format?
+//
+// Every option that DEMANDS something only one format can produce asks this same question, so it is
+// asked in one place: a demand about a TPM public area and a demand about an android-safetynet
+// device-integrity signal differ only in the format they name. Answering it per option is how the
+// second one comes to be answered only for the simple case and not for a compound.
+function _formatCarries(att, fmt) {
+  if (att.fmt === fmt) 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";
+    return !!fN && fN.majorType === 3 && cbor.read.textString(fN) === fmt;
   });
 }
 
@@ -1580,7 +1786,7 @@ void constants;
 
 /**
  * @primitive pki.webauthn.verifyMetadataBlob
- * @signature pki.webauthn.verifyMetadataBlob(blob, opts) -> Promise<{ no, nextUpdate, entries, byAaguid }>
+ * @signature pki.webauthn.verifyMetadataBlob(blob, opts) -> Promise<{ no, legalHeader, nextUpdate, stale, allowStale, rollbackChecked, previousNo, entries, byAaguid, byKeyIdentifier, statusPolicy, rejectUnknownStatus }>
  * @since 0.4.11
  * @status stable
  * @spec FIDO Metadata Service v3.0 sec. 3.1, RFC 7515
@@ -1598,6 +1804,12 @@ void constants;
  * (freshness). Every failure is a typed `webauthn/metadata-*` throw, never a partial
  * result.
  *
+ * The result says which of those rules actually ran, so a catalogue held for a while can
+ * still answer for itself: `stale` and `allowStale` for freshness, `rollbackChecked` and
+ * the `previousNo` it was compared against for rollback, `statusPolicy` and
+ * `rejectUnknownStatus` for the status reading every later lookup will use. A rule that
+ * did not run reads as not-run rather than as passed.
+ *
  * @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.
@@ -1661,21 +1873,40 @@ void constants;
 
 /**
  * @primitive pki.webauthn.metadataAnchors
- * @signature pki.webauthn.metadataAnchors(entry) -> [certificate]
+ * @signature pki.webauthn.metadataAnchors(entry, opts?) -> [certificate]
  * @since 0.4.11
  * @status stable
  * @spec FIDO Metadata Service v3.0 sec. 3.1.1
+ * @defends webauthn-revoked-authenticator-accepted (CWE-299)
  * @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
+ * attestation from that model must chain to. An entry whose status reports disqualify
+ * the model registers none: the catalogue exists to say which authenticators are still
+ * trusted, so handing back the roots of one it has revoked would answer a different
+ * question than the caller asked. That refusal is `webauthn/metadata-status`.
+ *
+ * The judgement uses whatever the caller supplies and the strictest reading of what it
+ * does not: pass the verified `metadata` and its own `statusPolicy` governs and its
+ * freshness is re-checked, pass `time` and reports are judged as of that instant, pass
+ * the `certificate` an attestation actually presented and a report naming a single
+ * certificate is judged against that one rather than denying every device the entry
+ * covers. With none of them: any disqualifying report denies, judged now.
+ *
+ * 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.
  *
+ * @opts
+ *   metadata    -- the verifyMetadataBlob result the entry came from
+ *   time        -- the instant the status reports are judged at (default: now)
+ *   certificate -- the attestation certificate presented, for a report that names one
+ *
  * @example
- *   // requires: `mdsEntry` -- one entry from a verified BLOB, as metadataFor returns
- *   var anchors = pki.webauthn.metadataAnchors(mdsEntry);
+ *   // requires: `mdsMetadata` -- a verifyMetadataBlob result; `mdsEntry` -- one of its
+ *   // entries, as metadataFor returns; `mdsTime` -- the instant to judge at
+ *   var anchors = pki.webauthn.metadataAnchors(mdsEntry, { metadata: mdsMetadata, time: mdsTime });
  *   anchors.length;              // the attestation roots this model registered
  *   anchors[0].subject;          // the decoded root DN
  *   // chain an attestation's trustPath to them:
@@ -1707,17 +1938,29 @@ var CLIENT_DATA_TYPE = Object.assign(Object.create(null), { "webauthn.create": 1
  * 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`
+ * Supply `expectedType`, `expectedChallenge`, `expectedOrigin` and
+ * `expectedTopOrigin` and each is checked here -- the challenge in constant time
+ * and by full value, the origins whole and case-sensitively. `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.
  *
+ * In a cross-origin ceremony `origin` is the framed document's and `topOrigin` is
+ * the page that framed it, so a relying party that allows framing at all should say
+ * which pages may do it. `expectedTopOrigin: null` requires an unframed ceremony,
+ * which an origin list cannot express. Whether a ceremony was framed is stated by
+ * BOTH `crossOrigin` and `topOrigin` and is only usable when they agree: a response
+ * declaring itself cross-origin does not satisfy `null` by omitting the origin, and
+ * one that does not declare itself cross-origin makes no framing claim for an origin
+ * list to accept.
+ *
  * @opts
  *   expectedType      -- "webauthn.create" or "webauthn.get"
- *   expectedChallenge -- the challenge bytes this ceremony issued (Buffer)
+ *   expectedChallenge -- the challenge bytes this ceremony issued (BufferSource)
  *   expectedOrigin    -- the origin string, or an array of acceptable origins
+ *   expectedTopOrigin -- the acceptable top-level origin(s), or null to require an
+ *                        unframed ceremony
  *
  * @example
  *   // requires: `clientDataJSON` -- credential.response.clientDataJSON;
@@ -1734,9 +1977,9 @@ 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");
-  }
+  // The RAW bytes, not a parsed object: this reader decides on the exact octets the authenticator
+  // signed over, and re-serializing a parsed object would decide on different ones.
+  bytes = _bytesArg(bytes, "clientDataJSON");
   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",
@@ -1776,7 +2019,7 @@ function parseClientData(bytes, opts) {
     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 };
+  var checked = { type: false, challenge: false, origin: false, topOrigin: 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\"");
@@ -1789,10 +2032,7 @@ function parseClientData(bytes, opts) {
     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)) {
+    if (!guard.crypto.constantTimeEqual(_bytesArg(opts.expectedChallenge, "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)");
     }
@@ -1813,6 +2053,48 @@ function parseClientData(bytes, opts) {
     }
     checked.origin = true;
   }
+  // The top-level origin of a cross-origin ceremony. It is surfaced either way, but a value a
+  // relying party only READS is a value nobody compares: `origin` in a cross-origin ceremony is the
+  // iframe's, and the top-level page that framed it is the one the security decision is actually
+  // about. Given what it accepts, this compares it the same way as `origin` -- whole, case
+  // sensitive, against a list -- so the two cannot drift into different matching rules.
+  //
+  // The three cases are kept apart rather than collapsed. An expectation of `null` means "this
+  // ceremony must NOT be framed", which is a real policy and cannot be expressed by an origin list;
+  // a response carrying no topOrigin against a list of acceptable ones is not framed at all, so the
+  // list has nothing to accept and the ceremony is refused rather than passed.
+  if (opts.expectedTopOrigin !== undefined) {
+    var wantTop = opts.expectedTopOrigin;
+    // Whether the ceremony was framed is stated by TWO fields, and the answer is only usable when
+    // they agree. `crossOrigin` says a framing happened; `topOrigin` names the page that did it.
+    // Reading one and not the other lets a response that declares itself cross-origin, but omits
+    // the origin, satisfy a policy of "must not be framed" -- it answers the caller's question with
+    // the field it left out rather than the one it filled in.
+    var framed = doc.crossOrigin === true;
+    if (wantTop === null) {
+      if (framed || doc.topOrigin !== undefined) {
+        throw _err("webauthn/client-data-mismatch",
+          "the clientDataJSON describes a cross-origin ceremony (crossOrigin " + JSON.stringify(doc.crossOrigin) +
+          ", topOrigin " + JSON.stringify(doc.topOrigin === undefined ? null : doc.topOrigin) +
+          "), and this relying party requires an unframed one (WebAuthn sec. 5.8.1)");
+      }
+    } else {
+      var allowedTop = Array.isArray(wantTop) ? wantTop : [wantTop];
+      if (!allowedTop.length || !allowedTop.every(function (o) { return typeof o === "string" && o.length; })) {
+        throw _err("webauthn/bad-input", "opts.expectedTopOrigin must be null, a non-empty origin string, or an array of them");
+      }
+      // Allow-listing the pages that may frame this ceremony is a statement about a framed one. A
+      // response that does not say it was framed makes no such claim to match against, so the list
+      // has nothing to accept -- and treating its absent topOrigin as a pass would report a check
+      // that decided nothing.
+      if (!framed || allowedTop.indexOf(doc.topOrigin) === -1) {
+        throw _err("webauthn/client-data-mismatch",
+          "the clientDataJSON topOrigin " + JSON.stringify(doc.topOrigin === undefined ? null : doc.topOrigin) +
+          " (crossOrigin " + JSON.stringify(doc.crossOrigin) + ") is not a framing this relying party accepts (WebAuthn sec. 5.8.1)");
+      }
+    }
+    checked.topOrigin = true;
+  }
   return {
     type: doc.type, challenge: challenge, origin: doc.origin,
     crossOrigin: doc.crossOrigin === undefined ? false : doc.crossOrigin,
@@ -1821,14 +2103,14 @@ function parseClientData(bytes, opts) {
   };
 }
 var _CLIENT_DATA_OPTS = Object.assign(Object.create(null), {
-  expectedType: 1, expectedChallenge: 1, expectedOrigin: 1,
+  expectedType: 1, expectedChallenge: 1, expectedOrigin: 1, expectedTopOrigin: 1,
 });
 
 // ---- public: parseAuthenticatorData / verifyAssertion ------------------------
 
 /**
  * @primitive pki.webauthn.parseAuthenticatorData
- * @signature pki.webauthn.parseAuthenticatorData(bytes) -> { rpIdHash, flags, signCount, aaguid, credentialId, credentialPublicKey, extensions }
+ * @signature pki.webauthn.parseAuthenticatorData(bytes) -> { rpIdHash, flags, signCount, aaguid, credentialId, credentialPublicKey, credentialPublicKeyBytes, extensions }
  * @since 0.5.0
  * @status experimental
  * @spec W3C WebAuthn Level 3 sec. 6.1
@@ -1852,10 +2134,7 @@ var _CLIENT_DATA_OPTS = Object.assign(Object.create(null), {
  *   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);
+  return _parseAuthData(_bytesArg(bytes, "authenticatorData"), _err);
 }
 
 // The options pki.webauthn.verifyAssertion recognises, null-prototype for the same
@@ -1864,12 +2143,12 @@ 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,
+  expectedChallenge: 1, expectedOrigin: 1, expectedTopOrigin: 1,
 });
 
 /**
  * @primitive pki.webauthn.verifyAssertion
- * @signature pki.webauthn.verifyAssertion(input) -> Promise<{ signatureVerified, signCount, signCountChecked, flags, rpIdHash, bindingChecked }>
+ * @signature pki.webauthn.verifyAssertion(input) -> Promise<{ signatureVerified, signCount, signCountChecked, flags, rpIdHash, extensions, bindingChecked, clientData }>
  * @since 0.5.0
  * @status experimental
  * @spec W3C WebAuthn Level 3 sec. 7.2
@@ -1932,22 +2211,31 @@ function _snapshotAssertion(input) {
   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]; }
+  // The SAME set of byte forms the arguments accept. A snapshot list narrower than the accept list
+  // leaves whatever falls in the gap aliased across the yield -- which is the one input a widened
+  // accept list newly admits, so the two must be written from one predicate.
   ["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 (_isBufferSource(out[f])) out[f] = guard.bytes.snapshotSource(out[f], WebauthnError, "webauthn/bad-input", f);
   });
-  if (_isPlainObject(out.credentialPublicKey)) {
+  // The BYTES form first. A Buffer satisfies the plain-object test below, so leaving it to that
+  // branch copies its numeric indices into a `{0:.., 1:..}` object that is no longer a key at all
+  // -- the stored credential silently becoming something the SPKI builder cannot read. It is
+  // snapshotted here for the same reason the other byte inputs are: it is read after a yield.
+  if (_isBufferSource(out.credentialPublicKey)) {
+    out.credentialPublicKey = guard.bytes.snapshotSource(out.credentialPublicKey, WebauthnError,
+      "webauthn/bad-input", "credentialPublicKey");
+  } else 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;
+      key[kk] = _isBufferSource(v) ? guard.bytes.snapshotSource(v, WebauthnError, "webauthn/bad-input", "credentialPublicKey." + kk) : v;
     }
     out.credentialPublicKey = key;
   }
   if (Array.isArray(out.allowedAlgorithms)) out.allowedAlgorithms = out.allowedAlgorithms.slice();
   if (Array.isArray(out.expectedOrigin)) out.expectedOrigin = out.expectedOrigin.slice();
+  if (Array.isArray(out.expectedTopOrigin)) out.expectedTopOrigin = out.expectedTopOrigin.slice();
   return out;
 }
 
@@ -1963,9 +2251,7 @@ function verifyAssertion(input) {
   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");
-    }
+    input.signature = _bytesArg(input.signature, "signature");
     // 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.
@@ -1975,9 +2261,7 @@ function verifyAssertion(input) {
     }
     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)");
-      }
+      input.clientDataJSON = _bytesArg(input.clientDataJSON, "clientDataJSON");
       // 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
@@ -1987,22 +2271,32 @@ function verifyAssertion(input) {
         expectedType: "webauthn.get",
         expectedChallenge: input.expectedChallenge,
         expectedOrigin: input.expectedOrigin,
+        expectedTopOrigin: input.expectedTopOrigin,
       });
       clientDataHash = _sha("sha256", Buffer.from(input.clientDataJSON));
     } else {
-      if (input.expectedChallenge !== undefined || input.expectedOrigin !== undefined) {
+      // Every expectation this verb forwards to the clientData reader is unanswerable without the
+      // JSON, so each is refused here rather than silently going uncompared. The list is the
+      // forwarded set above; a new expectation added there is added here too.
+      if (input.expectedChallenge !== undefined || input.expectedOrigin !== undefined ||
+          input.expectedTopOrigin !== 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");
+          "expectedChallenge / expectedOrigin / expectedTopOrigin are checked against clientDataJSON, which this call " +
+          "did not supply -- pass clientDataJSON instead of clientDataHash, or check them yourself");
       }
-      clientDataHash = Buffer.from(input.clientDataHash);
+      clientDataHash = _bytesArg(input.clientDataHash, "clientDataHash");
+      if (clientDataHash.length !== 32) throw _err("webauthn/bad-input", "clientDataHash must be a 32-byte SHA-256 digest");
     }
+    // Either form a relying party can be holding. `verify` hands back the parsed object, but the
+    // durable form is BYTES: the object carries Buffers, so a JSON round trip through a datastore
+    // returns {"type":"Buffer","data":[...]} rather than what went in, and every existing credential
+    // store already holds the COSE bytes. Accepting only the object made a caller fabricate an
+    // authenticatorData that never existed just to reach their own key.
     var coseKey = input.credentialPublicKey;
-    if (!_isPlainObject(coseKey)) {
-      throw _err("webauthn/bad-input", "credentialPublicKey must be the stored COSE key object");
+    if (Buffer.isBuffer(coseKey) || ArrayBuffer.isView(coseKey) || coseKey instanceof ArrayBuffer) {
+      coseKey = parseCoseKey(coseKey);
+    } else if (!_isPlainObject(coseKey)) {
+      throw _err("webauthn/bad-input", "credentialPublicKey must be the stored COSE key -- the object pki.webauthn.verify returned, or its COSE bytes");
     }
     var bindingChecked = _applyBindings(authData, coseKey, input);
     // The counter's SHAPE is a config-time question and is answered here; whether it
@@ -2027,14 +2321,26 @@ function verifyAssertion(input) {
       // 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.
+      // THREE outcomes, kept apart, because this field's only purpose is to tell a relying party
+      // whether it has cloned-authenticator detection on this credential:
+      //   false           -- not requested; no previousSignCount was supplied
+      //   "not-supported" -- requested, but the authenticator implements no counter (the 0/0 case
+      //                      sec. 7.2 permits), so the comparison was deliberately skipped
+      //   true            -- requested and performed
+      // Reporting `true` for the waived case claimed a detection that cannot happen, and a bare
+      // `false` there would be indistinguishable from never having asked.
       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)");
+        if (prev === 0 && authData.signCount === 0) {
+          signCountChecked = "not-supported";
+        } else {
+          if (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;
         }
-        signCountChecked = true;
       }
       return {
         signatureVerified: true,
@@ -2057,6 +2363,7 @@ module.exports = {
   parseAttestationObject: parseAttestationObject,
   parseAuthenticatorData: parseAuthenticatorData,
   parseClientData: parseClientData,
+  parseCoseKey: parseCoseKey,
   verify: verify,
   verifyAssertion: verifyAssertion,
   verifyMetadataBlob: mds.verifyMetadataBlob,