@blamejs/pki 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.4.8 — 2026-08-08
+
+A stored android-safetynet WebAuthn attestation can be re-verified in full -- the signature, the registration binding, and the certificate chain -- behind an opt-in and against a root the caller supplies.
+
+### Added
+
+- pki.webauthn.verify verifies the android-safetynet attestation format, which it previously refused as unsupported. Enable it with opts.verifySafetyNetJws and supply the Google root(s) to anchor the chain to as opts.safetyNetRoots -- both are required, and with either missing the call is refused rather than falling back to a weaker check. The format is off by default and this library bundles no root, because the service that produced these statements is retired and choosing a trust anchor on a caller's behalf is not this library's decision to make. A caller who does not enable it sees the same result as before.
+- Every binding the specification states is checked, and each failure names which one: the response must be a three-part JWS whose algorithm is RS256, its signature must verify under the certificate in its own header, its nonce must match this registration's authenticator data and client data, the certificate must be issued to attest.android.com, and the chain must validate to one of the supplied roots. The algorithm is pinned rather than read from the token, so a statement cannot select its own verification algorithm. The hostname is matched exactly against the certificate's subject alternative name, falling back to its common name only when it carries no alternative name at all -- a name merely ending in attest.android.com does not pass. The chain goes through full path validation, so an expired or otherwise non-conforming certificate cannot pass on a signature alone. On success the result reports attestation type Basic with the embedded chain as its trust path.
+- Device-integrity signals in the response -- whether the device passed the compatibility test suite, the reported timestamp, the requesting package -- are deliberately not gated on, because the specification does not make them part of attestation verification. They remain relying-party policy.
+
 ## v0.4.7 — 2026-08-08
 
 One certificate now renders one distinguished-name string whichever parser read it -- a C509 certificate's subject and issuer strings joined their components without the separating space every other parser in the toolkit uses.

package/lib/constants.js

@@ -297,6 +297,15 @@ var LIMITS = {
   // terminates but exhausts memory. This matches PATH_MAX_CERTS: a chain longer than the path
   // validator will ever accept has nothing to offer, so refusing it at the decoder is free.
   TLS_CERT_MAX_ENTRIES: 100,
+  // A WebAuthn android-safetynet attestation statement carries the SafetyNet response as a JWS
+  // compact serialization: two small JSON objects plus a signature, with the certificate chain
+  // inline in the header. Real ones run a few kilobytes. The cap bounds the text decode before the
+  // string is materialized, so an oversized statement is refused rather than allocated (CWE-770).
+  SAFETYNET_JWS_MAX_BYTES: BYTES.kib(64),
+  // One x5c entry is a single DER certificate; PATH_MAX_CERT_BYTES is the ceiling the path
+  // validator already applies to any certificate it will accept, and an entry above it could not
+  // chain even if it decoded.
+  SAFETYNET_CERT_MAX_BYTES: BYTES.kib(64),
   // ACME challenge token entropy floor (RFC 8555 sec. 8, errata 6950): >= 128
   // bits of base64url is >= 22 characters. A shorter token is refused before use.
   ACME_TOKEN_MIN_CHARS: 22,

package/lib/webauthn.js

@@ -8,8 +8,8 @@
  * @intro Trust evaluation of a W3C WebAuthn (Level 3) / passkey attestation: parse
  *   the attestation object + authenticatorData, decode the COSE credential public
  *   key, and verify each defined attestation-statement format (packed, tpm,
- *   android-key, apple, fido-u2f, none) -- the attestation-statement signature and
- *   each format's structural bindings. The attestation CBOR is decoded by the strict,
+ *   android-key, apple, fido-u2f, none, and android-safetynet behind an opt-in) --
+ *   the attestation-statement signature and each format's structural bindings. The attestation CBOR is decoded by the strict,
  *   fail-closed `pki.cbor` codec (WebAuthn keys are CTAP2-canonical), the signature by
  *   `pki.webcrypto`. Chaining the returned x5c trust path to a caller-pinned root via
  *   `pki.path.validate` is the caller's step: this module verifies the statement, not
@@ -31,6 +31,9 @@ var webcrypto = require("./webcrypto");
 var constants = require("./constants");
 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 nodeCrypto = require("crypto");
 
 var WebauthnError = frameworkError.WebauthnError;
@@ -517,6 +520,122 @@ var VERIFIERS = {
     });
   },
 
+  // android-safetynet (WebAuthn 8.5): the attStmt carries a SafetyNet JWS ("response") whose payload
+  // binds a nonce to this registration and whose x5c header chains to a Google root.
+  //
+  // OFF BY DEFAULT, and anchored only by the caller. Google retired the SafetyNet Attestation API, so
+  // nothing mints these any more -- the surviving use is a relying party re-checking attestations it
+  // stored years ago. Enabling a format whose producer is gone, against a root this library chose,
+  // would widen what every caller trusts for no live benefit; so the caller opts in AND supplies the
+  // root. With the opt off the verdict is byte-identical to the one this format had before the arm
+  // existed. There is no bundled root and no trust-on-first-use.
+  "android-safetynet": function (att, clientDataHash, opts) {
+    opts = opts || {};
+    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;
+    if (!Array.isArray(roots) || roots.length === 0) {
+      throw _err("webauthn/safetynet-no-root", "verifying an android-safetynet attestation requires opts.safetyNetRoots -- the Google root(s) to anchor the x5c chain to; this library bundles none (WebAuthn 8.5)");
+    }
+    if (opts.time !== undefined) guard.time.assertValid(opts.time, WebauthnError, "webauthn/bad-input", "opts.time");
+
+    // 8.5 attStmt syntax: safetynetStmtFormat = { ver: text, response: bytes }. `ver` is READ but
+    // never gated on -- 8.5 states it is reserved for future use.
+    _requireAttShape(att.attStmt, ["ver", "response"], ["ver", "response"]);
+    _attRead(att.attStmt, "ver", cbor.read.textString, "a text string");
+    var responseBytes = _attRead(att.attStmt, "response", cbor.read.byteString, "a byte string");
+    if (!responseBytes.length) throw _err("webauthn/bad-att-stmt", "the android-safetynet response is empty");
+
+    // RFC 7515 sec. 3.1 Compact Serialization: exactly three base64url segments.
+    var segs = guard.text.decode(responseBytes, constants.LIMITS.SAFETYNET_JWS_MAX_BYTES, WebauthnError, "webauthn/bad-att-stmt", "the android-safetynet response").split(".");
+    if (segs.length !== 3) throw _err("webauthn/bad-att-stmt", "the android-safetynet response is not a three-part JWS compact serialization (RFC 7515 sec. 3.1)");
+    var header, payload, sigBytes;
+    try {
+      header = jose.parseJson(jose.base64url.decode(segs[0]));
+      payload = jose.parseJson(jose.base64url.decode(segs[1]));
+      sigBytes = Buffer.from(jose.base64url.decode(segs[2]));
+    } catch (e) { throw _err("webauthn/bad-att-stmt", "the android-safetynet response is not a decodable JWS", e); }
+    // A JWS segment must decode to a JSON OBJECT. `null`, a number, a string and an array are all
+    // valid JSON, so the parse succeeds and every later field read would be a raw TypeError escaping
+    // this module's typed contract -- the caller's error handling would never see a webauthn/* code.
+    if (!_isPlainObject(header) || !_isPlainObject(payload)) {
+      throw _err("webauthn/bad-att-stmt", "the android-safetynet JWS header and payload must each be a JSON object");
+    }
+
+    // Pin the algorithm rather than reading it from the token: an attacker-chosen alg is the JWS
+    // algorithm-confusion class, and SafetyNet only ever signed RS256.
+    if (header.alg !== "RS256") throw _err("webauthn/unsupported-algorithm", "the android-safetynet JWS alg must be RS256, got " + JSON.stringify(header.alg));
+    if (!Array.isArray(header.x5c) || header.x5c.length === 0) {
+      throw _err("webauthn/bad-att-stmt", "the android-safetynet JWS header carries no x5c certificate chain (RFC 7515 sec. 4.1.6)");
+    }
+    // x5c entries are STANDARD base64 (RFC 7515 sec. 4.1.6), not base64url like the segments.
+    var chain = header.x5c.map(function (entry, i) {
+      if (typeof entry !== "string") throw _err("webauthn/bad-att-stmt", "the android-safetynet x5c entry " + i + " is not a string");
+      var der;
+      try { der = guard.encoding.base64(entry, constants.LIMITS.SAFETYNET_CERT_MAX_BYTES, WebauthnError, "webauthn/bad-att-stmt", "an android-safetynet x5c entry"); }
+      catch (e) { throw _err("webauthn/bad-att-stmt", "the android-safetynet x5c entry " + i + " is not canonical base64", e); }
+      try { return x509.parse(der); }
+      catch (e) { throw _err("webauthn/bad-att-cert", "the android-safetynet x5c entry " + i + " is not a decodable certificate", e); }
+    });
+    var leaf = chain[0];
+
+    // 8.5 bullet 3: nonce == STANDARD Base64 of SHA-256(authenticatorData || clientDataHash). Note
+    // standard base64 (+/=), NOT base64url -- and the digest is over the raw concatenation.
+    var wantNonce = _sha("sha256", Buffer.concat([att.authDataBytes, clientDataHash])).toString("base64");
+    if (typeof payload.nonce !== "string" || !guard.crypto.constantTimeEqual(Buffer.from(payload.nonce, "utf8"), Buffer.from(wantNonce, "utf8"))) {
+      throw _err("webauthn/safetynet-nonce-mismatch", "the android-safetynet nonce does not bind this authenticatorData and clientDataHash (WebAuthn 8.5)");
+    }
+
+    // 8.5 bullet 4 (via the SafetyNet documentation): the response must come from the SafetyNet
+    // service, which is established by the leaf being issued to attest.android.com AND the chain
+    // validating to a Google root. The hostname alone proves nothing until the chain is anchored.
+    if (!_safetyNetHostnameOk(leaf)) {
+      throw _err("webauthn/safetynet-bad-hostname", "the android-safetynet x5c leaf is not issued to attest.android.com (WebAuthn 8.5)");
+    }
+
+    // The device-integrity signals are NOT part of the 8.5 verification procedure -- its five bullets
+    // never mention them -- so gating the attestation verdict on them would invent a requirement the
+    // specification does not state. They are relying-party policy, so they are surfaced on the result
+    // for a caller to act on, and enforced here only when the caller explicitly asks. A caller that
+    // asks and finds them missing or false gets a refusal, never a silent pass.
+    var signals = {
+      ctsProfileMatch: payload.ctsProfileMatch, basicIntegrity: payload.basicIntegrity,
+      timestampMs: payload.timestampMs, apkPackageName: payload.apkPackageName,
+      apkCertificateDigestSha256: payload.apkCertificateDigestSha256, advice: payload.advice,
+    };
+    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) {
+      if (!ok) throw _err("webauthn/verify-failed", "the android-safetynet JWS signature does not verify under the x5c leaf key");
+      // WHEN to judge the chain. These attestations are historical by construction -- the service is
+      // retired -- so a leaf that was valid when the response was signed is routinely expired now,
+      // and judging it against the current clock would refuse every genuine stored registration.
+      // The response carries its own signing time, and by this point that value is covered by the
+      // signature just verified under the leaf, so it is authenticated rather than caller-asserted.
+      // Precedence: an explicit opts.time (the caller knows when the registration happened) beats
+      // the signed timestamp, which beats now (a response that carries no usable timestamp).
+      var at = opts.time !== undefined ? opts.time
+        : (typeof payload.timestampMs === "number" && isFinite(payload.timestampMs) && payload.timestampMs > 0
+          ? new Date(payload.timestampMs) : undefined);
+      return _safetyNetChainTrusted(chain, roots, at);
+    }).then(function () {
+      // 8.5 bullet 5: attestation type Basic, trust path x5c.
+      var res = _result("android-safetynet", "Basic", chain, att);
+      res.safetyNet = signals;
+      return res;
+    });
+  },
+
   // none (WebAuthn 8.7): the authenticator provides no attestation. attStmt MUST be
   // an empty map; there is no statement to verify, so the result carries no trust
   // path. The credential public key still binds via authenticatorData (AT flag).
@@ -530,6 +649,71 @@ var VERIFIERS = {
   },
 };
 
+// A decoded JSON value that is safe to read named members off. JSON.parse yields null, numbers,
+// strings and arrays too, and a member read on any of those would leave this module's typed error
+// contract as a raw TypeError.
+function _isPlainObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
+
+// WebAuthn 8.5 (via the SafetyNet documentation): the JWS leaf is issued to attest.android.com.
+// Checked on the SAN dNSName entries first -- the name a TLS-style certificate is actually issued
+// to -- falling back to the commonName only when the certificate carries no SAN at all, the way a
+// hostname match has been specified since RFC 6125. Compared case-insensitively (a DNS name is
+// case-insensitive) and exactly: no wildcard, no suffix match, so attest.android.com.evil.test
+// cannot pass.
+function _safetyNetHostnameOk(leaf) {
+  var want = "attest.android.com";
+  // Decoded through the SAME shared pkix extension decoder every other format here uses, so the
+  // general-name parse cannot drift from the rest of the toolkit.
+  var san = _decodeExt(leaf, "subjectAltName");
+  var entries = san && Array.isArray(san.value) ? san.value : [];
+  var dns = entries.filter(function (gn) { return gn && gn.type === "dNSName" && typeof gn.value === "string"; });
+  // A SAN carrying dNSName entries is authoritative: the commonName is not consulted at all.
+  if (dns.length) return dns.some(function (gn) { return gn.value.toLowerCase() === want; });
+  // rdns is a sequence of RDNs, each a set of attribute/value pairs -- hence the nested walk.
+  return leaf.subject.rdns.some(function (rdn) {
+    return rdn.some(function (atv) {
+      return atv.name === "commonName" && typeof atv.value === "string" && atv.value.toLowerCase() === want;
+    });
+  });
+}
+
+// WebAuthn 8.5 (via the SafetyNet documentation): the x5c chain must validate to a Google root the
+// CALLER supplied. Every anchor is tried because a caller may hold several Google roots across a
+// 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.
+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 anchorCert;
+      try { anchorCert = Buffer.isBuffer(root) || 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,
+        trustAnchor: { name: anchorCert.subject, publicKey: anchorCert.subjectPublicKeyInfo.bytes, algorithm: anchorCert.signatureAlgorithm.oid },
+      }).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)");
+  });
+}
+
 // `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.

package/package.json

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

package/sbom.cdx.json

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