@simplewebauthn/server 13.2.3 → 13.3.0

package/esm/authentication/verifyAuthenticationResponse.d.ts

@@ -9,7 +9,7 @@ export type VerifyAuthenticationResponseOpts = Parameters<typeof verifyAuthentic
  *
  * **Options:**
  *
- * @param response - Response returned by **@simplewebauthn/browser**'s `startAssertion()`
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
  * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateAuthenticationOptions()`
  * @param expectedOrigin - Website URL (or array of URLs) that the registration should have occurred on
  * @param expectedRPID - RP ID (or array of IDs) that was specified in the registration options

package/esm/authentication/verifyAuthenticationResponse.js

@@ -10,7 +10,7 @@ import { isoBase64URL, isoUint8Array } from '../helpers/iso/index.js';
  *
  * **Options:**
  *
- * @param response - Response returned by **@simplewebauthn/browser**'s `startAssertion()`
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
  * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateAuthenticationOptions()`
  * @param expectedOrigin - Website URL (or array of URLs) that the registration should have occurred on
  * @param expectedRPID - RP ID (or array of IDs) that was specified in the registration options

package/esm/helpers/index.d.ts

@@ -13,5 +13,6 @@ export * from './toHash.js';
 export * from './validateCertificatePath.js';
 export * from './verifySignature.js';
 export * from './iso/index.js';
+export * from '../metadata/verifyMDSBlob.js';
 export * as cose from './cose.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/helpers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC"}

package/esm/helpers/index.js

@@ -13,4 +13,5 @@ export * from './toHash.js';
 export * from './validateCertificatePath.js';
 export * from './verifySignature.js';
 export * from './iso/index.js';
+export * from '../metadata/verifyMDSBlob.js';
 export * as cose from './cose.js';

package/esm/metadata/verifyMDSBlob.d.ts

@@ -0,0 +1,18 @@
+import type { MDSJWTPayload, MetadataStatement } from './mdsTypes.js';
+/**
+ * Perform authenticity and integrity verification of a
+ * [FIDO Metadata Service (MDS)](https://fidoalliance.org/metadata/)-compatible blob, and then
+ * extract the FIDO2 metadata statements included within. This method will make network requests
+ * for things like CRL checks.
+ *
+ * @param blob - A JWT downloaded from an MDS server (e.g. https://mds3.fidoalliance.org)
+ */
+export declare function verifyMDSBlob(blob: string): Promise<{
+    /** MetadataStatement entries within the verified blob */
+    statements: MetadataStatement[];
+    /** A JS `Date` instance of the verified blob's `payload.nextUpdate` string */
+    parsedNextUpdate: Date;
+    /** The verified blob's `payload` value */
+    payload: MDSJWTPayload;
+}>;
+//# sourceMappingURL=verifyMDSBlob.d.ts.map

package/esm/metadata/verifyMDSBlob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyMDSBlob.d.ts","sourceRoot":"","sources":["../../src/metadata/verifyMDSBlob.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAQpF;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,yDAAyD;IACzD,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,8EAA8E;IAC9E,gBAAgB,EAAE,IAAI,CAAC;IACvB,0CAA0C;IAC1C,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC,CAuDD"}

package/esm/metadata/verifyMDSBlob.js

@@ -0,0 +1,59 @@
+import { parseJWT } from './parseJWT.js';
+import { verifyJWT } from './verifyJWT.js';
+import { validateCertificatePath } from '../helpers/validateCertificatePath.js';
+import { convertCertBufferToPEM } from '../helpers/convertCertBufferToPEM.js';
+import { convertPEMToBytes } from '../helpers/convertPEMToBytes.js';
+import { SettingsService } from '../services/settingsService.js';
+/**
+ * Perform authenticity and integrity verification of a
+ * [FIDO Metadata Service (MDS)](https://fidoalliance.org/metadata/)-compatible blob, and then
+ * extract the FIDO2 metadata statements included within. This method will make network requests
+ * for things like CRL checks.
+ *
+ * @param blob - A JWT downloaded from an MDS server (e.g. https://mds3.fidoalliance.org)
+ */
+export async function verifyMDSBlob(blob) {
+    // Parse the JWT
+    const parsedJWT = parseJWT(blob);
+    const header = parsedJWT[0];
+    const payload = parsedJWT[1];
+    const headerCertsPEM = header.x5c.map(convertCertBufferToPEM);
+    try {
+        // Validate the certificate chain
+        const rootCerts = SettingsService.getRootCertificates({
+            identifier: 'mds',
+        });
+        await validateCertificatePath(headerCertsPEM, rootCerts);
+    }
+    catch (error) {
+        const _error = error;
+        // From FIDO MDS docs: "ignore the file if the chain cannot be verified or if one of the
+        // chain certificates is revoked"
+        throw new Error('BLOB certificate path could not be validated', { cause: _error });
+    }
+    // Verify the BLOB JWT signature
+    const leafCert = headerCertsPEM[0];
+    const verified = await verifyJWT(blob, convertPEMToBytes(leafCert));
+    if (!verified) {
+        // From FIDO MDS docs: "The FIDO Server SHOULD ignore the file if the signature is invalid."
+        throw new Error('BLOB signature could not be verified');
+    }
+    // Cache statements for FIDO2 devices
+    const statements = [];
+    for (const entry of payload.entries) {
+        // Only cache entries with an `aaguid`
+        if (entry.aaguid && entry.metadataStatement) {
+            statements.push(entry.metadataStatement);
+        }
+    }
+    // Convert the nextUpdate property into a Date so we can determine when to re-download
+    const [year, month, day] = payload.nextUpdate.split('-');
+    const parsedNextUpdate = new Date(parseInt(year, 10), 
+    // Months need to be zero-indexed
+    parseInt(month, 10) - 1, parseInt(day, 10));
+    return {
+        statements,
+        parsedNextUpdate,
+        payload,
+    };
+}

package/esm/services/metadataService.d.ts

@@ -13,7 +13,8 @@ interface MetadataService {
      *
      * @param opts.mdsServers An array of URLs to FIDO Alliance Metadata Service
      * (version 3.0)-compatible servers. Defaults to the official FIDO MDS server
-     * @param opts.statements An array of local metadata statements
+     * @param opts.statements An array of local metadata statements. Statements will be loaded but
+     * not refreshed
      * @param opts.verificationMode How MetadataService will handle unregistered AAGUIDs. Defaults to
      * `"strict"` which throws errors during registration response verification when an
      * unregistered AAGUID is encountered. Set to `"permissive"` to allow registration by
@@ -53,6 +54,10 @@ export declare class BaseMetadataService implements MetadataService {
      * Download and process the latest BLOB from MDS
      */
     private downloadBlob;
+    /**
+     * Verify and process the MDS metadata blob
+     */
+    private verifyBlob;
     /**
      * A helper method to pause execution until the service is ready
      */

package/esm/services/metadataService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadataService.d.ts","sourceRoot":"","sources":["../../src/services/metadataService.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAIV,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyBrD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAIvD,UAAU,eAAe;IACvB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE;QAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnF;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,gBAAgB,CAA8B;IAEhD,UAAU,CACd,IAAI,GAAE;QACJ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KAChC,GACL,OAAO,CAAC,IAAI,CAAC;IA+DV,YAAY,CAChB,MAAM,EAAE,MAAM,GAAG,WAAW,GAC3B,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA6DzC;;OAEG;YACW,YAAY;IAqE1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAgCvB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAWjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,eAA2C,CAAC"}
+{"version":3,"file":"metadataService.d.ts","sourceRoot":"","sources":["../../src/services/metadataService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA4B,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmCrD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAIvD,UAAU,eAAe;IACvB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE;QAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnF;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,gBAAgB,CAA8B;IAEhD,UAAU,CACd,IAAI,GAAE;QACJ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KAChC,GACL,OAAO,CAAC,IAAI,CAAC;IA4EV,YAAY,CAChB,MAAM,EAAE,MAAM,GAAG,WAAW,GAC3B,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA8DzC;;OAEG;YACW,YAAY;IAU1B;;OAEG;YACW,UAAU;IA8CxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgCvB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAWjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,eAA2C,CAAC"}

package/esm/services/metadataService.js

@@ -1,12 +1,15 @@
-import { validateCertificatePath } from '../helpers/validateCertificatePath.js';
-import { convertCertBufferToPEM } from '../helpers/convertCertBufferToPEM.js';
 import { convertAAGUIDToString } from '../helpers/convertAAGUIDToString.js';
-import { SettingsService } from './settingsService.js';
+import { verifyMDSBlob } from '../metadata/verifyMDSBlob.js';
 import { getLogger } from '../helpers/logging.js';
-import { convertPEMToBytes } from '../helpers/convertPEMToBytes.js';
 import { fetch } from '../helpers/fetch.js';
-import { parseJWT } from '../metadata/parseJWT.js';
-import { verifyJWT } from '../metadata/verifyJWT.js';
+/**
+ * An instance of `CachedMDS` that will not trigger attempts to refresh the associated entry's blob
+ */
+const NonRefreshingMDS = {
+    url: '',
+    no: 0,
+    nextUpdate: new Date(0),
+};
 const defaultURLMDS = 'https://mds.fidoalliance.org/'; // v3
 var SERVICE_STATE;
 (function (SERVICE_STATE) {
@@ -49,9 +52,14 @@ export class BaseMetadataService {
         });
     }
     async initialize(opts = {}) {
+        // Reset statement cache
+        this.statementCache = {};
         const { mdsServers = [defaultURLMDS], statements, verificationMode } = opts;
         this.setState(SERVICE_STATE.REFRESHING);
-        // If metadata statements are provided, load them into the cache first
+        /**
+         * If metadata statements are provided, load them into the cache first. These statements will
+         * not be refreshed when a stale one is detected.
+         */
         if (statements?.length) {
             let statementsAdded = 0;
             statements.forEach((statement) => {
@@ -63,25 +71,31 @@ export class BaseMetadataService {
                             statusReports: [],
                             timeOfLastStatusChange: '1970-01-01',
                         },
-                        url: '',
+                        url: NonRefreshingMDS.url,
                     };
                     statementsAdded += 1;
                 }
             });
             log(`Cached ${statementsAdded} local statements`);
         }
-        // If MDS servers are provided, then process them and add their statements to the cache
+        /**
+         * If MDS servers are provided, then download blobs from them, verify them, and then add their
+         * entries to the cache. Blobs loaded in this way will be refreshed when a stale entry within is
+         * detected.
+         */
         if (mdsServers?.length) {
             // Get a current count so we know how many new statements we've added from MDS servers
             const currentCacheCount = Object.keys(this.statementCache).length;
             let numServers = mdsServers.length;
             for (const url of mdsServers) {
                 try {
-                    await this.downloadBlob({
+                    const cachedMDS = {
                         url,
                         no: 0,
                         nextUpdate: new Date(0),
-                    });
+                    };
+                    const blob = await this.downloadBlob(cachedMDS);
+                    await this.verifyBlob(blob, cachedMDS);
                 }
                 catch (err) {
                     // Notify of the error and move on
@@ -128,7 +142,8 @@ export class BaseMetadataService {
             if (now > mds.nextUpdate) {
                 try {
                     this.setState(SERVICE_STATE.REFRESHING);
-                    await this.downloadBlob(mds);
+                    const blob = await this.downloadBlob(mds);
+                    await this.verifyBlob(blob, mds);
                 }
                 finally {
                     this.setState(SERVICE_STATE.READY);
@@ -151,40 +166,23 @@ export class BaseMetadataService {
     /**
      * Download and process the latest BLOB from MDS
      */
-    async downloadBlob(mds) {
-        const { url, no } = mds;
+    async downloadBlob(cachedMDS) {
+        const { url } = cachedMDS;
         // Get latest "BLOB" (FIDO's terminology, not mine)
         const resp = await fetch(url);
         const data = await resp.text();
-        // Parse the JWT
-        const parsedJWT = parseJWT(data);
-        const header = parsedJWT[0];
-        const payload = parsedJWT[1];
+        return data;
+    }
+    /**
+     * Verify and process the MDS metadata blob
+     */
+    async verifyBlob(blob, cachedMDS) {
+        const { url, no } = cachedMDS;
+        const { payload, parsedNextUpdate } = await verifyMDSBlob(blob);
         if (payload.no <= no) {
             // From FIDO MDS docs: "also ignore the file if its number (no) is less or equal to the
             // number of the last BLOB cached locally."
-            throw new Error(`Latest BLOB no. "${payload.no}" is not greater than previous ${no}`);
-        }
-        const headerCertsPEM = header.x5c.map(convertCertBufferToPEM);
-        try {
-            // Validate the certificate chain
-            const rootCerts = SettingsService.getRootCertificates({
-                identifier: 'mds',
-            });
-            await validateCertificatePath(headerCertsPEM, rootCerts);
-        }
-        catch (error) {
-            const _error = error;
-            // From FIDO MDS docs: "ignore the file if the chain cannot be verified or if one of the
-            // chain certificates is revoked"
-            throw new Error('BLOB certificate path could not be validated', { cause: _error });
-        }
-        // Verify the BLOB JWT signature
-        const leafCert = headerCertsPEM[0];
-        const verified = await verifyJWT(data, convertPEMToBytes(leafCert));
-        if (!verified) {
-            // From FIDO MDS docs: "The FIDO Server SHOULD ignore the file if the signature is invalid."
-            throw new Error('BLOB signature could not be verified');
+            throw new Error(`Latest BLOB no. ${payload.no} is not greater than previous no. ${no}`);
         }
         // Cache statements for FIDO2 devices
         for (const entry of payload.entries) {
@@ -193,17 +191,28 @@ export class BaseMetadataService {
                 this.statementCache[entry.aaguid] = { entry, url };
             }
         }
-        // Remember info about the server so we can refresh later
-        const [year, month, day] = payload.nextUpdate.split('-');
-        this.mdsCache[url] = {
-            ...mds,
-            // Store the payload `no` to make sure we're getting the next BLOB in the sequence
-            no: payload.no,
-            // Convert the nextUpdate property into a Date so we can determine when to re-download
-            nextUpdate: new Date(parseInt(year, 10), 
-            // Months need to be zero-indexed
-            parseInt(month, 10) - 1, parseInt(day, 10)),
-        };
+        if (url) {
+            // Remember info about the server so we can refresh later
+            this.mdsCache[url] = {
+                ...cachedMDS,
+                // Store the payload `no` to make sure we're getting the next BLOB in the sequence
+                no: payload.no,
+                // Remember when we need to refresh this blob
+                nextUpdate: parsedNextUpdate,
+            };
+        }
+        else {
+            /**
+             * This blob will not be refreshed, but we should still alert if the blob's `nextUpdate` is
+             * in the past
+             */
+            if (parsedNextUpdate < new Date()) {
+                // TODO (Feb 2026): It'd be more actionable for devs if a specific error was raised here,
+                // then this message was logged higher up when it can include the array index of the stale
+                // blob.
+                log(`⚠️ This MDS blob (serial: ${payload.no}) contains stale data as of ${parsedNextUpdate.toISOString()}. Please consider re-initializing MetadataService with a newer MDS blob.`);
+            }
+        }
     }
     /**
      * A helper method to pause execution until the service is ready

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplewebauthn/server",
-  "version": "13.2.3",
+  "version": "13.3.0",
   "description": "SimpleWebAuthn for Servers",
   "keywords": [
     "typescript",

package/script/authentication/verifyAuthenticationResponse.d.ts

@@ -9,7 +9,7 @@ export type VerifyAuthenticationResponseOpts = Parameters<typeof verifyAuthentic
  *
  * **Options:**
  *
- * @param response - Response returned by **@simplewebauthn/browser**'s `startAssertion()`
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
  * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateAuthenticationOptions()`
  * @param expectedOrigin - Website URL (or array of URLs) that the registration should have occurred on
  * @param expectedRPID - RP ID (or array of IDs) that was specified in the registration options

package/script/authentication/verifyAuthenticationResponse.js

@@ -13,7 +13,7 @@ const index_js_1 = require("../helpers/iso/index.js");
  *
  * **Options:**
  *
- * @param response - Response returned by **@simplewebauthn/browser**'s `startAssertion()`
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
  * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateAuthenticationOptions()`
  * @param expectedOrigin - Website URL (or array of URLs) that the registration should have occurred on
  * @param expectedRPID - RP ID (or array of IDs) that was specified in the registration options

package/script/helpers/index.d.ts

@@ -13,5 +13,6 @@ export * from './toHash.js';
 export * from './validateCertificatePath.js';
 export * from './verifySignature.js';
 export * from './iso/index.js';
+export * from '../metadata/verifyMDSBlob.js';
 export * as cose from './cose.js';
 //# sourceMappingURL=index.d.ts.map

package/script/helpers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC"}

package/script/helpers/index.js

@@ -42,4 +42,5 @@ __exportStar(require("./toHash.js"), exports);
 __exportStar(require("./validateCertificatePath.js"), exports);
 __exportStar(require("./verifySignature.js"), exports);
 __exportStar(require("./iso/index.js"), exports);
+__exportStar(require("../metadata/verifyMDSBlob.js"), exports);
 exports.cose = __importStar(require("./cose.js"));

package/script/metadata/verifyMDSBlob.d.ts

@@ -0,0 +1,18 @@
+import type { MDSJWTPayload, MetadataStatement } from './mdsTypes.js';
+/**
+ * Perform authenticity and integrity verification of a
+ * [FIDO Metadata Service (MDS)](https://fidoalliance.org/metadata/)-compatible blob, and then
+ * extract the FIDO2 metadata statements included within. This method will make network requests
+ * for things like CRL checks.
+ *
+ * @param blob - A JWT downloaded from an MDS server (e.g. https://mds3.fidoalliance.org)
+ */
+export declare function verifyMDSBlob(blob: string): Promise<{
+    /** MetadataStatement entries within the verified blob */
+    statements: MetadataStatement[];
+    /** A JS `Date` instance of the verified blob's `payload.nextUpdate` string */
+    parsedNextUpdate: Date;
+    /** The verified blob's `payload` value */
+    payload: MDSJWTPayload;
+}>;
+//# sourceMappingURL=verifyMDSBlob.d.ts.map

package/script/metadata/verifyMDSBlob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyMDSBlob.d.ts","sourceRoot":"","sources":["../../src/metadata/verifyMDSBlob.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAQpF;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,yDAAyD;IACzD,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,8EAA8E;IAC9E,gBAAgB,EAAE,IAAI,CAAC;IACvB,0CAA0C;IAC1C,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC,CAuDD"}

package/script/metadata/verifyMDSBlob.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMDSBlob = verifyMDSBlob;
+const parseJWT_js_1 = require("./parseJWT.js");
+const verifyJWT_js_1 = require("./verifyJWT.js");
+const validateCertificatePath_js_1 = require("../helpers/validateCertificatePath.js");
+const convertCertBufferToPEM_js_1 = require("../helpers/convertCertBufferToPEM.js");
+const convertPEMToBytes_js_1 = require("../helpers/convertPEMToBytes.js");
+const settingsService_js_1 = require("../services/settingsService.js");
+/**
+ * Perform authenticity and integrity verification of a
+ * [FIDO Metadata Service (MDS)](https://fidoalliance.org/metadata/)-compatible blob, and then
+ * extract the FIDO2 metadata statements included within. This method will make network requests
+ * for things like CRL checks.
+ *
+ * @param blob - A JWT downloaded from an MDS server (e.g. https://mds3.fidoalliance.org)
+ */
+async function verifyMDSBlob(blob) {
+    // Parse the JWT
+    const parsedJWT = (0, parseJWT_js_1.parseJWT)(blob);
+    const header = parsedJWT[0];
+    const payload = parsedJWT[1];
+    const headerCertsPEM = header.x5c.map(convertCertBufferToPEM_js_1.convertCertBufferToPEM);
+    try {
+        // Validate the certificate chain
+        const rootCerts = settingsService_js_1.SettingsService.getRootCertificates({
+            identifier: 'mds',
+        });
+        await (0, validateCertificatePath_js_1.validateCertificatePath)(headerCertsPEM, rootCerts);
+    }
+    catch (error) {
+        const _error = error;
+        // From FIDO MDS docs: "ignore the file if the chain cannot be verified or if one of the
+        // chain certificates is revoked"
+        throw new Error('BLOB certificate path could not be validated', { cause: _error });
+    }
+    // Verify the BLOB JWT signature
+    const leafCert = headerCertsPEM[0];
+    const verified = await (0, verifyJWT_js_1.verifyJWT)(blob, (0, convertPEMToBytes_js_1.convertPEMToBytes)(leafCert));
+    if (!verified) {
+        // From FIDO MDS docs: "The FIDO Server SHOULD ignore the file if the signature is invalid."
+        throw new Error('BLOB signature could not be verified');
+    }
+    // Cache statements for FIDO2 devices
+    const statements = [];
+    for (const entry of payload.entries) {
+        // Only cache entries with an `aaguid`
+        if (entry.aaguid && entry.metadataStatement) {
+            statements.push(entry.metadataStatement);
+        }
+    }
+    // Convert the nextUpdate property into a Date so we can determine when to re-download
+    const [year, month, day] = payload.nextUpdate.split('-');
+    const parsedNextUpdate = new Date(parseInt(year, 10), 
+    // Months need to be zero-indexed
+    parseInt(month, 10) - 1, parseInt(day, 10));
+    return {
+        statements,
+        parsedNextUpdate,
+        payload,
+    };
+}

package/script/services/metadataService.d.ts

@@ -13,7 +13,8 @@ interface MetadataService {
      *
      * @param opts.mdsServers An array of URLs to FIDO Alliance Metadata Service
      * (version 3.0)-compatible servers. Defaults to the official FIDO MDS server
-     * @param opts.statements An array of local metadata statements
+     * @param opts.statements An array of local metadata statements. Statements will be loaded but
+     * not refreshed
      * @param opts.verificationMode How MetadataService will handle unregistered AAGUIDs. Defaults to
      * `"strict"` which throws errors during registration response verification when an
      * unregistered AAGUID is encountered. Set to `"permissive"` to allow registration by
@@ -53,6 +54,10 @@ export declare class BaseMetadataService implements MetadataService {
      * Download and process the latest BLOB from MDS
      */
     private downloadBlob;
+    /**
+     * Verify and process the MDS metadata blob
+     */
+    private verifyBlob;
     /**
      * A helper method to pause execution until the service is ready
      */

package/script/services/metadataService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadataService.d.ts","sourceRoot":"","sources":["../../src/services/metadataService.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAIV,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyBrD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAIvD,UAAU,eAAe;IACvB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE;QAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnF;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,gBAAgB,CAA8B;IAEhD,UAAU,CACd,IAAI,GAAE;QACJ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KAChC,GACL,OAAO,CAAC,IAAI,CAAC;IA+DV,YAAY,CAChB,MAAM,EAAE,MAAM,GAAG,WAAW,GAC3B,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA6DzC;;OAEG;YACW,YAAY;IAqE1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAgCvB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAWjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,eAA2C,CAAC"}
+{"version":3,"file":"metadataService.d.ts","sourceRoot":"","sources":["../../src/services/metadataService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA4B,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmCrD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAIvD,UAAU,eAAe;IACvB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE;QAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnF;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,gBAAgB,CAA8B;IAEhD,UAAU,CACd,IAAI,GAAE;QACJ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KAChC,GACL,OAAO,CAAC,IAAI,CAAC;IA4EV,YAAY,CAChB,MAAM,EAAE,MAAM,GAAG,WAAW,GAC3B,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA8DzC;;OAEG;YACW,YAAY;IAU1B;;OAEG;YACW,UAAU;IA8CxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgCvB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAWjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,eAA2C,CAAC"}

package/script/services/metadataService.js

@@ -1,15 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetadataService = exports.BaseMetadataService = void 0;
-const validateCertificatePath_js_1 = require("../helpers/validateCertificatePath.js");
-const convertCertBufferToPEM_js_1 = require("../helpers/convertCertBufferToPEM.js");
 const convertAAGUIDToString_js_1 = require("../helpers/convertAAGUIDToString.js");
-const settingsService_js_1 = require("./settingsService.js");
+const verifyMDSBlob_js_1 = require("../metadata/verifyMDSBlob.js");
 const logging_js_1 = require("../helpers/logging.js");
-const convertPEMToBytes_js_1 = require("../helpers/convertPEMToBytes.js");
 const fetch_js_1 = require("../helpers/fetch.js");
-const parseJWT_js_1 = require("../metadata/parseJWT.js");
-const verifyJWT_js_1 = require("../metadata/verifyJWT.js");
+/**
+ * An instance of `CachedMDS` that will not trigger attempts to refresh the associated entry's blob
+ */
+const NonRefreshingMDS = {
+    url: '',
+    no: 0,
+    nextUpdate: new Date(0),
+};
 const defaultURLMDS = 'https://mds.fidoalliance.org/'; // v3
 var SERVICE_STATE;
 (function (SERVICE_STATE) {
@@ -52,9 +55,14 @@ class BaseMetadataService {
         });
     }
     async initialize(opts = {}) {
+        // Reset statement cache
+        this.statementCache = {};
         const { mdsServers = [defaultURLMDS], statements, verificationMode } = opts;
         this.setState(SERVICE_STATE.REFRESHING);
-        // If metadata statements are provided, load them into the cache first
+        /**
+         * If metadata statements are provided, load them into the cache first. These statements will
+         * not be refreshed when a stale one is detected.
+         */
         if (statements?.length) {
             let statementsAdded = 0;
             statements.forEach((statement) => {
@@ -66,25 +74,31 @@ class BaseMetadataService {
                             statusReports: [],
                             timeOfLastStatusChange: '1970-01-01',
                         },
-                        url: '',
+                        url: NonRefreshingMDS.url,
                     };
                     statementsAdded += 1;
                 }
             });
             log(`Cached ${statementsAdded} local statements`);
         }
-        // If MDS servers are provided, then process them and add their statements to the cache
+        /**
+         * If MDS servers are provided, then download blobs from them, verify them, and then add their
+         * entries to the cache. Blobs loaded in this way will be refreshed when a stale entry within is
+         * detected.
+         */
         if (mdsServers?.length) {
             // Get a current count so we know how many new statements we've added from MDS servers
             const currentCacheCount = Object.keys(this.statementCache).length;
             let numServers = mdsServers.length;
             for (const url of mdsServers) {
                 try {
-                    await this.downloadBlob({
+                    const cachedMDS = {
                         url,
                         no: 0,
                         nextUpdate: new Date(0),
-                    });
+                    };
+                    const blob = await this.downloadBlob(cachedMDS);
+                    await this.verifyBlob(blob, cachedMDS);
                 }
                 catch (err) {
                     // Notify of the error and move on
@@ -131,7 +145,8 @@ class BaseMetadataService {
             if (now > mds.nextUpdate) {
                 try {
                     this.setState(SERVICE_STATE.REFRESHING);
-                    await this.downloadBlob(mds);
+                    const blob = await this.downloadBlob(mds);
+                    await this.verifyBlob(blob, mds);
                 }
                 finally {
                     this.setState(SERVICE_STATE.READY);
@@ -154,40 +169,23 @@ class BaseMetadataService {
     /**
      * Download and process the latest BLOB from MDS
      */
-    async downloadBlob(mds) {
-        const { url, no } = mds;
+    async downloadBlob(cachedMDS) {
+        const { url } = cachedMDS;
         // Get latest "BLOB" (FIDO's terminology, not mine)
         const resp = await (0, fetch_js_1.fetch)(url);
         const data = await resp.text();
-        // Parse the JWT
-        const parsedJWT = (0, parseJWT_js_1.parseJWT)(data);
-        const header = parsedJWT[0];
-        const payload = parsedJWT[1];
+        return data;
+    }
+    /**
+     * Verify and process the MDS metadata blob
+     */
+    async verifyBlob(blob, cachedMDS) {
+        const { url, no } = cachedMDS;
+        const { payload, parsedNextUpdate } = await (0, verifyMDSBlob_js_1.verifyMDSBlob)(blob);
         if (payload.no <= no) {
             // From FIDO MDS docs: "also ignore the file if its number (no) is less or equal to the
             // number of the last BLOB cached locally."
-            throw new Error(`Latest BLOB no. "${payload.no}" is not greater than previous ${no}`);
-        }
-        const headerCertsPEM = header.x5c.map(convertCertBufferToPEM_js_1.convertCertBufferToPEM);
-        try {
-            // Validate the certificate chain
-            const rootCerts = settingsService_js_1.SettingsService.getRootCertificates({
-                identifier: 'mds',
-            });
-            await (0, validateCertificatePath_js_1.validateCertificatePath)(headerCertsPEM, rootCerts);
-        }
-        catch (error) {
-            const _error = error;
-            // From FIDO MDS docs: "ignore the file if the chain cannot be verified or if one of the
-            // chain certificates is revoked"
-            throw new Error('BLOB certificate path could not be validated', { cause: _error });
-        }
-        // Verify the BLOB JWT signature
-        const leafCert = headerCertsPEM[0];
-        const verified = await (0, verifyJWT_js_1.verifyJWT)(data, (0, convertPEMToBytes_js_1.convertPEMToBytes)(leafCert));
-        if (!verified) {
-            // From FIDO MDS docs: "The FIDO Server SHOULD ignore the file if the signature is invalid."
-            throw new Error('BLOB signature could not be verified');
+            throw new Error(`Latest BLOB no. ${payload.no} is not greater than previous no. ${no}`);
         }
         // Cache statements for FIDO2 devices
         for (const entry of payload.entries) {
@@ -196,17 +194,28 @@ class BaseMetadataService {
                 this.statementCache[entry.aaguid] = { entry, url };
             }
         }
-        // Remember info about the server so we can refresh later
-        const [year, month, day] = payload.nextUpdate.split('-');
-        this.mdsCache[url] = {
-            ...mds,
-            // Store the payload `no` to make sure we're getting the next BLOB in the sequence
-            no: payload.no,
-            // Convert the nextUpdate property into a Date so we can determine when to re-download
-            nextUpdate: new Date(parseInt(year, 10), 
-            // Months need to be zero-indexed
-            parseInt(month, 10) - 1, parseInt(day, 10)),
-        };
+        if (url) {
+            // Remember info about the server so we can refresh later
+            this.mdsCache[url] = {
+                ...cachedMDS,
+                // Store the payload `no` to make sure we're getting the next BLOB in the sequence
+                no: payload.no,
+                // Remember when we need to refresh this blob
+                nextUpdate: parsedNextUpdate,
+            };
+        }
+        else {
+            /**
+             * This blob will not be refreshed, but we should still alert if the blob's `nextUpdate` is
+             * in the past
+             */
+            if (parsedNextUpdate < new Date()) {
+                // TODO (Feb 2026): It'd be more actionable for devs if a specific error was raised here,
+                // then this message was logged higher up when it can include the array index of the stale
+                // blob.
+                log(`⚠️ This MDS blob (serial: ${payload.no}) contains stale data as of ${parsedNextUpdate.toISOString()}. Please consider re-initializing MetadataService with a newer MDS blob.`);
+            }
+        }
     }
     /**
      * A helper method to pause execution until the service is ready