@ideem/zsm-client-sdk 2.4.0 → 2.5.0

package/{RELEASE_NOTES.txt → CHANGELOG.md}

@@ -1,21 +1,57 @@
 ZSM Client SDK for Browser Apps
-Latest version: v2.3.0
-Latest release date: March 24, 2025
+Latest version: v2.5.0
+Latest release date: Aug 29, 2025
 
 The ZSM Client SDK for Browser Apps provides the resources needed to integrate Ideem's FIDO2 Authenticator
 and Universal MFA into a browser application. 
 
 ## Resources: 
-- UMFA Documentation: https://docs.useideem.com/umfa_sdk/browser/index.html
-- FIDO2 Documentation: https://docs.useideem.com/fido2_sdk/browser/index.html
 - Support: support@useideem.com 
 
 ## Known Issues
-- None
+- A corner-case exists in which a developer, using both the core SDK packages as well as the Passkeys+ SDK, may encounter conflicts if a ZSM credential is re-enrolled after the Passkeys+ credential has been enrolled. Dev team is aware of this issue and a fix is forthcoming. A safeguard has been implemented to prevent this issue from occurring accidentally but, in the immediate term, developers are advised to avoid re-enrolling ZSM credentials after Passkeys+ credentials have been enrolled.
 
 ----
 
-## Release 2.4.0 - May 1, 2025 [ NPM PACKAGE RELEASE ] **[ LATEST ]**
+## Release 2.5.0 - Aug 29, 2025 [ NPM PACKAGE RELEASE ] **[ LATEST ]**
+- Significant re-architecture of the SDK to improve performance and maintainability (non-breaking, but may alter existing implementations, if plugins are used)
+- Introduction of a new plugin system for easier integration of additional Ideem services
+    - Plugin system allows for dynamic loading and unloading of features
+    - Improved modularity and separation of concerns
+    - Enhanced error handling and recovery mechanisms
+    - Plugins can be easily added or removed without affecting the core SDK functionality
+    - Industry-leading implementation approach; no code changes or plugin registration required! Simply `import` the plugin and the functionality is available!
+    - Improved performance and reduced bundle size
+- Advanced event coordination capabilities
+    - Fine-grained control over event propagation and handling
+    - Support for complex event workflows and dependencies
+    - Asynchronous loading of SDK and its constituent components and plugins
+    - Optional `async`/`await` support for class constructors
+    - Optional `finished()` method introduced for better async flow control
+    - Optional callback method support for SDK initialization
+    - Optional global-scoped events emitted during SDK initialization and lifecycle
+- Relying Party improvements
+    - (RP) identification improvements
+    - (RP) configuration enhancements
+    - RP now single-instance when using Passkeys+; no need for secondary instance when using the same browser context
+- Error handling, reporting, logging, and recovery improvements
+    - Centralized error handling and recovery mechanisms
+    - Extended support for custom error types and structured error information
+    - Normalized error responses across SDK components
+- Significant improvements to documentation
+- Significant updates to sample apps
+- Automated shim polyfills introduced to simplify VanillaJS integrations using NPM packages (no more `importmap` configuration required!)
+- Significant updates to build process and tooling
+
+## Release 2.4.1 - May 5, 2025
+- Minor bug fixes and improvements
+- Updates to documentation
+- Updates to sample apps
+- Alters worker communication protocol to ensure that the worker is not blocked 
+  by the main thread and vice versa, while still ensuring that the initialization
+  of the worker is completed before any other operations are performed.
+
+## Release 2.4.0 - May 1, 2025
 - Minor bug fixes and improvements
 - Updates to documentation
 - Adds event emitters to the UMFAClient and FIDO2Client for on-the-fly initializations

package/EventCoordinator.js

@@ -0,0 +1,267 @@
+import GLOBAL from './GlobalScoping.js';
+
+// baseStack is a Map that holds the initial state of the event stack. It is defaulted to those classes that are ALWAYS present in the ZSMClient package, and
+// constitutes the minimum set of classes that are both expected in ALL permutations of the SDK, and which are REQUIRED for the ZSMClient package to function.
+// Additional classes are added contextually (their status STARTING at "PENDING") when the client app imports them, and CAN remove a baseStack entry entirely.
+// Each event inside represents a class used by the NPM Package's "main" export - ZSMClientSDK - and tracks its status throughout its initialization lifecycle
+// (status include: UNREGISTERED, PENDING, READY, or ERROR). Each time a class's status changes, the event stack is updated, and, once all classes reach their
+// respective READY statuses, the ZSMClient package is considered fully initialized, and a custom event is dispatched to notify the client app that the SDK is
+// finished loading and is ready for use. Additional possible event stack entries (at time of this writing) include: WORKER, PERFORMANCELOGGER, PASSKEYCLIENT.
+
+let baseStack = new Map([
+    ["SELECTEDCLIENT", "UNREGISTERED"], // Active client class - UMFAClient or FIDO2Client (dynamically set by client's import choice) - that's being imported
+    ["RELYINGPARTY",   "UNREGISTERED"], // The RelyingParty class (extended from RelyingPartyBase) used for registration/authentication calls to the RP Server
+    ["WEBAUTHNCLIENT", "UNREGISTERED"]  // The WebAuthnClient class (extended from WebAuthnClientBase) used to coordinate the MPCRound calls to the ZSM Server
+]);
+
+// EventCoordinator is a class instance that both represents and manages the event stack, allows for dynamically updating class initialization statuses (along
+// with dispatching the relevant custom events associated with those changes), and provides a means for additional, plug-in NPM Packages' classes to be added,
+// monitored, and included in the overall ZSMClient package's readiness state. Note: the act of importing EventCoordinator (or any other package, really) will
+// initialize it as a singleton, so it manages its own state, and there is no concern if it is imported multiple times; it always refers to the same instance.
+class EventCoordinator {
+    constructor(initialStack = baseStack) {
+        this.coreSDKClass    = null;                                    // The core SDK class that is user-facing (if any; usually ZSMClientSDK)
+        this._selectedClient = null;                                    // The active customer-facing SDK client (UMFAClient or FIDO2Client)
+        this._eventStack     = new Map(initialStack);                   // Clone the initialStack provided to ensure it isn't modified by reference
+        this.cleanState      = new Map(initialStack);                   // Store the initial state of the event stack as cleanState, so it can be reset later
+        
+        // Even if the GLOBAL scope does not support event dispatches, while we will not be able to dispatch events, we can still manage the app's event stack
+        this.scopeSupportsEventDispatch = (typeof GLOBAL.dispatchEvent === 'function' && typeof CustomEvent === 'function');
+    }
+    get supported()      { return this.scopeSupportsEventDispatch;                 }                    // Returns true/false if GLOBAL scope supports events
+    get statusOptions()  { return ['UNREGISTERED', 'PENDING', 'READY', 'ERROR'];   }                    // Returns the possible status options for events
+    get stack()          { return this._eventStack;                                }                    // Returns the current event stack as a Map
+    get length()         { return [...this._eventStack.keys()].length;             }                    // Returns count of all events in the stack
+    get keys()           { return [...this._eventStack.keys()];                    }                    // Returns array of event names in the stack
+    get values()         { return [...this._eventStack.values()];                  }                    // Returns array of event statuses in the stack
+    get entries()        { return [...this._eventStack.entries()];                 }                    // Returns array of [name, status] pairs in the stack
+    get object()         { return Object.fromEntries(this.entries);                }                    // Returns the event stack as a plain object
+    get unregistered()   { return this.lengthByStatus('UNREGISTERED');             }                    // Returns count of events with status "UNREGISTERED"
+    get pending()        { return this.lengthByStatus('PENDING');                  }                    // Returns count of events with status "PENDING"
+    get ready()          { return this.lengthByStatus('READY');                    }                    // Returns count of events with status "READY"
+    get error()          { return this.lengthByStatus('ERROR');                    }                    // Returns count of events with status "ERROR"
+    get incomplete()     { return this.length - this.ready;                        }                    // Returns count of events that are NOT "READY"
+    get containsErrors() { return this.error > 0;                                  }                    // Returns true/false if any events' status is "ERROR"
+    get done()           { return (this.ready === this.length);                    }                    // Returns true/false if all events are "READY"
+    get client()         { return this._selectedClient;                            }                    // Returns the currently selected client (UMFA/FIDO2)
+    get status()         { return this.containsErrors ? 'ERROR' 
+                                : this.done           ? 'READY'
+                                : !!this.unregistered ? 'INCOMPLETE REGISTRATIONS' 
+                                : 'PENDING';                                       }
+    set client(value)    { this._selectedClient = value;                           }                    // Returns the currently selected client (UMFA/FIDO2)
+    set coreReady(value) { this.coreSDKClass.ready          = !!value;             }
+    set coreErrs(value)  { this.coreSDKClass.containsErrors = !!value;             }
+
+    setCoreSDKClass(classDesc, classRef) {
+        const core = (this.coreSDKClass = classRef);                            // Set a reference to the core class on the singleton instance, then...
+        core.ready = false;                                                     // ... set its default ready state to false
+        core.containsErrors = false;                                            // ... set its default containsErrors state to false
+        Object.defineProperty(core, "finished", {                               // ... and define a "finished" function on the core object...
+            value: this.finished.bind(this),                                    //     ... binding it to the method on this singleton instance
+            enumerable: false, writable: false, configurable: false             //     ... and making it non-enumerable, non-writable, and non-configurable
+        });
+        this.specifyClient(classDesc);                                          // ... finally, specify the client class that is being initialized.
+    }
+
+    specifyClient(selectedClient) {
+        if (!selectedClient || typeof selectedClient !== 'string' || !selectedClient.length) 
+            throw new TypeError(`[ZSM EventCoordinator] :: specifyClient :: Invalid 'selectedClient' value: "${selectedClient}". 'selectedClient' is required and expects a String.`);
+
+        if (this.client == null) {
+            this._eventStack.delete('SELECTEDCLIENT');
+            this.cleanState.delete('SELECTEDCLIENT');
+            this.client = selectedClient.toUpperCase();
+        }
+    }
+
+    summarizeEventStack (...triggerData) {
+        let summaryObject = this.object,
+            { client, containsErrors, done } = this;
+
+        summaryObject[`counts (${this.length})`] = {
+            total        : this.length,
+            unregistered : this.unregistered,
+            pending      : this.pending,
+            ready        : this.ready,
+            error        : this.error
+        };
+
+        let opFn = (typeof console?.l === 'function') ? console.l : console.log;
+        opFn(`[ZSM EventCoordinator] :: Event Update!\n${(!!triggerData.length) ? `(ACTIVE EVENT: '${triggerData.join(': ')}')\n` : ''}  Status summary:\n`, Object.assign({client, containsErrors, done}, summaryObject));
+    }
+
+    /**
+     * @name            dispatchEvent
+     * @description     Dispatches a custom event with the given name and detail.
+     * @param           {string}            classDesc       The name of the event to dispatch.
+     * @param           {Object}            eventDetail     The detail object to attach to the event.
+     * @returns         {void}
+     */
+    dispatchEvent(eventName, eventDetail={}) {
+        if (!this.scopeSupportsEventDispatch) return;
+        GLOBAL.dispatchEvent(new CustomEvent(eventName, { detail: eventDetail }));
+    }
+
+    update (classDesc, eventStatus="PENDING") {    
+        if (!classDesc || typeof classDesc !== 'string' || !classDesc.length) 
+            throw new TypeError(`[ZSM EventCoordinator] :: update :: Invalid 'classDesc' value: "${classDesc}". 'classDesc' is required and expects a String.`);
+
+        if(classDesc === 'SELECTEDCLIENT'){
+            if(!this.client) throw new TypeError(`[ZSM EventCoordinator] :: update :: Status for 'SELECTEDCLIENT' cannot be updated until a client is specified!`);
+            classDesc = this.client;
+        }
+        classDesc = classDesc.toUpperCase();
+
+        eventStatus =  (!eventStatus || typeof eventStatus !== 'string' || !eventStatus.length) ? "PENDING" : eventStatus.toUpperCase();
+
+        if (!this.statusOptions.includes(eventStatus)) 
+            throw new TypeError(`[ZSM EventCoordinator] :: update :: Invalid 'eventStatus' value: "${eventStatus}". Accepts: ${this.statusOptions.join(', ')}.`);
+
+        this._eventStack.set(classDesc, eventStatus);
+
+        if( this.containsErrors ) {
+            const errorMsg = `[ZSM EventCoordinator] :: Initialization Error! :: The ZSMClient initialization contains errors and is unable to continue!]\nModules containing errors:\n  - ${this.byStatus('ERROR').join('\n  -')}.`;
+            this.coreErrs = true; // Set the core SDK class error state to true
+            if(window && window?.queueMicrotask) {
+                queueMicrotask(() => this.dispatchEvent('ZSMClientError', {
+                    message: errorMsg,
+                    modules: this.byStatus('ERROR')
+                }));
+            }else  this.dispatchEvent('ZSMClientError', { message: errorMsg, modules: this.object });
+            console.error(errorMsg);
+            return this.object; // don't throw here
+        }
+
+        if (this.done) {
+            this.coreReady = true; // Set the core SDK class ready state to true
+            if(window && window?.queueMicrotask) {
+                queueMicrotask(() => this.dispatchEvent('ZSMClientReady', {
+                    ready: true
+                }));
+            }else  this.dispatchEvent('ZSMClientReady', { ready: true });
+        }
+
+        if(GLOBAL.showEvents) this.summarizeEventStack(classDesc, eventStatus);
+        return this.object;
+    }
+    
+    /**
+     * @name            byStatus
+     * @description     Retrieves all event names that match a specific status.
+     * @param           {string}            eventStatus     The status to filter events by (accepts: UNREGISTERED, PENDING, READY, ERROR).
+     * @throws          {TypeError}                         If the eventStatus is invalid or not one of the allowed values.
+     * @returns         {Array}                             Returns an array of event names that match the specified status.
+     */
+    byStatus(eventStatus) {
+        if (!eventStatus || typeof eventStatus !== 'string' || !eventStatus.length || !["UNREGISTERED", "PENDING", "READY", "ERROR"].includes(eventStatus)) 
+            throw new Error(`[ZSM EventCoordinator] :: byStatus :: Invalid 'eventStatus' value: "${eventStatus}". Valid statuses are: UNREGISTERED, PENDING, READY, ERROR.`);
+        return [...this._eventStack.entries().flatMap(([k, v]) => (v === eventStatus) ? [k] : [])];
+    }
+
+    /**
+     * @name            lengthByStatus
+     * @description     Returns the count of events that match a specific status.
+     * @param           {string}            eventStatus     The status to filter events by (accepts: UNREGISTERED, PENDING, READY, ERROR).
+     * @throws          {TypeError}                         If the eventStatus is invalid or not one of the allowed values.
+     * @returns         {number}                            Returns the count of events with the specified status.
+     */
+    lengthByStatus(eventStatus) {
+        return this.byStatus(eventStatus).length || 0;
+    }
+
+    /**
+     * @name            reset
+     * @description     Resets the event stack to its initial state (cleanState).
+     * @returns         {Object}                            Returns the reset event stack object.
+     */
+    reset() {
+        this._eventStack = new Map(this.cleanState);
+        if(window && window?.queueMicrotask) {
+            queueMicrotask(() => this.dispatchEvent('ZSMClientEventStackReset', { stack: this.object }));
+        } else  this.dispatchEvent('ZSMClientEventStackReset', { stack: this.object });
+        return this.object;
+    }
+
+    /**
+     * @name            finished
+     * @description     Waits for the ZSMClient initialization to complete, either by checking the done state or by listening for the ZSMClientReady event.
+     * @param           {function|number}   callbackFnOrTimeout     A callback function to call when the initialization is done, or a timeout in milliseconds to wait before rejecting.
+     * @param           {function|any}      callbackFnOrFirstArg    An optional callback function to call when the initialization is done (if timeout is specified), or the first argument to pass to the callback function.
+     * @param           {array<any>}        args                    Additional arguments to pass to the callback function.
+     * @returns         {Promise<boolean>}                          Resolves to true if the initialization is done, or rejects with an error if it takes too long or contains errors.
+     * @throws          {Error}                                     If the initialization takes too long or contains errors.
+     * @throws          {Error}                                     If some portion of the initialization fails.
+     */
+    async finished(callbackFnOrTimeout, callbackFnOrFirstArg, ...args) {
+        if (this.done) return Promise.resolve(true);
+
+        let timeoutID,
+            callbackFn,
+            onSDKReady,
+            onSDKError,
+            terminatePoll = false, 
+            timeoutDuration = 20000;
+
+        if(!isNaN(callbackFnOrTimeout)) {
+            timeoutDuration = callbackFnOrTimeout;
+            if(typeof callbackFnOrFirstArg === 'function') {
+                callbackFn = callbackFnOrFirstArg;
+            }
+        }else if(typeof callbackFnOrTimeout === 'function') {
+            callbackFn = callbackFnOrTimeout;
+            args.unshift(callbackFnOrFirstArg);
+        }
+
+        return new Promise((resolve, reject) => {
+            onSDKReady = () => { 
+                terminatePoll = true;
+                if(callbackFn) callbackFn(...args);                                         // Call the callback function if provided
+                resolve(true);                                                              // Resolve the promise with a value of true
+            };
+            onSDKError = (e) => { 
+                terminatePoll = true;
+                reject(new Error(`[ZSM EventCoordinator] :: finished :: Initialization Error! :: ${e.message || e}\nModules containing errors:\n  - ${this.byStatus('ERROR').join('\n  -')}.`));
+            };
+            if (this.done) onSDKReady();
+            if (this.containsErrors) onSDKError({ detail: { modules: this.byStatus('ERROR') } });
+
+            const onTimeout = () => {
+                terminatePoll = true;
+                if (this.done) return;
+                reject(new Error("[ZSM EventCoordinator] :: Timeout Error: ZSMClient initialization took too long to complete. Please check your network connection or server status."));
+            };
+
+            timeoutID = setTimeout(onTimeout, timeoutDuration);
+
+            if (this.scopeSupportsEventDispatch) {
+                GLOBAL.addEventListener('ZSMClientReady', onSDKReady, { once: true });
+                GLOBAL.addEventListener('ZSMClientError', onSDKError, { once: true });
+            } else {
+                const poll = () => {
+                    if (this.done) {
+                        onSDKReady();
+                    } else if (this.containsErrors) {
+                        onSDKError("[ZSM EventCoordinator] :: finished :: Error: ZSMClient initialization contains errors and is unable to continue.");
+                    }
+                    else if (!terminatePoll) setTimeout(poll, 200);
+                };
+                poll();
+            }
+        })
+        .catch(err => {
+            throw new Error(`[ZSM EventCoordinator] :: finished :: Initialization Error! :: ${err.message || err}\nModules containing errors:\n  - ${this.byStatus('ERROR').join('\n  -')}.`);
+        })
+        .finally(() => {
+            clearTimeout(timeoutID);
+            if (this.scopeSupportsEventDispatch) {
+                GLOBAL.removeEventListener('ZSMClientReady', onSDKReady);
+                GLOBAL.removeEventListener('ZSMClientError', onSDKError);
+            }
+        });
+    }
+}
+
+const eventCoordinator = new EventCoordinator(); // Create a singleton instance of EventCoordinator
+
+export default eventCoordinator;
+export { eventCoordinator };

package/FIDO2Client.js

@@ -0,0 +1,15 @@
+import eventCoordinator from './EventCoordinator.js';
+import FIDO2ClientBase  from './FIDO2ClientBase.js';
+
+class FIDO2Client extends FIDO2ClientBase {
+    /**
+     * Constructs a FIDO2Client object by extending the FIDO2ClientBase class.
+     * @param {Object} config - The configuration for ZSM initialization (ref: ./zsm_app_config.json)
+     */
+    constructor(config) {
+        super(config);
+        eventCoordinator.update('FIDO2Client', 'READY');
+    }
+}
+
+export {FIDO2Client};

package/FIDO2ClientBase.js

@@ -0,0 +1,117 @@
+import eventCoordinator from './EventCoordinator.js';
+import {zsmPluginManager}   from './PluginManager.js';
+
+
+class FIDO2ClientBase {
+    /**
+     * @constructor
+     * @param {Object} config - The configuration for the FIDO2Client
+    */
+   constructor(config) {
+        if(eventCoordinator.done) eventCoordinator.reset();
+        eventCoordinator.update('FIDO2ClientBase');
+        this.config           = config;
+        const WebAuthnClient  = zsmPluginManager.classes('WEBAUTHNCLIENT');
+        this.zsmAPI           = new WebAuthnClient(config);
+        this.checkEnrollment  = this.checkEnrollment.bind(this);
+        this.checkIdentity    = this.checkIdentity.bind(this);
+        this.webauthnRetrieve = this.webauthnRetrieve.bind(this);
+        this.webauthnDelete   = this.webauthnDelete.bind(this);
+        this.resetDevice      = this.resetDevice.bind(this);
+        this.webauthnCreate   = this.webauthnCreate.bind(this);
+        this.webauthnGet      = this.webauthnGet.bind(this);
+        eventCoordinator.update('FIDO2ClientBase', 'READY');
+    }
+
+    get userIdentifier()    { return this.zsmAPI.userIdentifier; }
+    get credentialID()      { return this.zsmAPI.credentialID;   }
+
+    /**
+     * @name            checkEnrollment
+     * @description     Alias for webauthnRetrieve
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<Object>}                               Returns the result of webauthnRetrieve
+     * @memberOf        FIDO2ClientBase, WebAuthnClient
+     */
+    checkEnrollment  (userIdentifier) { return this.webauthnRetrieve(userIdentifier); }
+
+    /**
+     * @name            checkIdentity
+     * @description     Pass-through method to call WebAuthnClient's checkIdentity
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @param           {boolean}                   primeEnroll         Whether to create a new identity if it doesn't exist
+     * @returns         {Promise<Object>}                               Returns the results of zsmAPI.checkIdentity
+     * @memberOf        FIDO2ClientBase, WebAuthnClient
+     */
+    checkIdentity    (userIdentifier, primeEnroll) { return this.zsmAPI.checkIdentity(userIdentifier, primeEnroll); }
+
+    /**
+     * @name            webauthnRetrieve
+     * @description     Pass-through method to call WebAuthnClient's webauthnRetrieve
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<Object>}                               Returns the results of zsmAPI.webauthnRetrieve
+     * @memberOf        FIDO2ClientBase, WebAuthnClient
+     */
+    webauthnRetrieve (userIdentifier) { return this.zsmAPI.webauthnRetrieve(userIdentifier); }
+
+    /**
+     * @name            webauthnDelete
+     * @description     Pass-through method to call WebAuthnClient's unbindFromDevice
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<Object>}                               Returns the results of zsmAPI.unbindFromDevice
+     * @memberOf        FIDO2ClientBase, WebAuthnClient
+     */
+    webauthnDelete   (userIdentifier) { return this.zsmAPI.unbindFromDevice(userIdentifier); }
+
+    /**
+     * @name            resetDevice
+     * @description     Pass-through method to call WebAuthnClient's webauthnReset
+     * @returns         {Promise<void>}                               No results are returned
+     * @memberOf        FIDO2ClientBase, WebAuthnClient
+     */
+    resetDevice      ()               { this.zsmAPI.webauthnReset(); }
+
+    /**
+     * @name            webauthnCreate
+     * @description     Enrolls a user by creating a ZSM credential on the device
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<Object>|Error}                         Resolves with the created credential, false if user is already enrolled, or an error if enrollment fails
+     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
+     * @throws          {Error}                                         If an error occurs during enrollment
+     * @memberOf        FIDO2ClientBase
+     */
+    async webauthnCreate   (userIdentifier) { 
+        try {
+            if(userIdentifier == null 
+                || userIdentifier === '')     throw new Error(`[FIDO2Client] :: webauthnCreate :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+            
+            const createResult                = this.zsmAPI.webauthnCreate(userIdentifier); 
+            if(createResult instanceof Error) throw(`[FIDO2Client] :: webauthnCreate :: Unable to associate ${userIdentifier}'s identity with device profile.\nDetails:\n${createResult}`);
+            return createResult;
+        }catch(e) {
+            return new Error(e.message || e || '[FIDO2Client] :: webauthnCreate :: An error occurred during credential creation.');
+        }
+    }
+
+    /**
+     * @name            webauthnGet
+     * @description     Retrieves the ZSM credential for the specified user
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<Object>}                               The ZSM credential for the user
+     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
+     * @throws          {Error}                                         If an error occurs during credential retrieval
+     * @memberOf        FIDO2ClientBase
+     */
+    async webauthnGet      (userIdentifier) {
+        try {
+            if(userIdentifier == null 
+                || userIdentifier === '')     throw new Error(`[FIDO2Client] :: webauthnGet :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+            let authCredential = await this.zsmAPI.webauthnGet(userIdentifier);
+            return authCredential.credential;
+        }catch(e) {
+            return new Error(e.message || e || '[FIDO2Client] :: webauthnGet :: An error occurred during credential retrieval.');
+        }
+    }
+}
+
+export default FIDO2ClientBase;

package/GlobalScoping.js

@@ -0,0 +1,8 @@
+// Alias environment-specific global object
+const GLOBAL = typeof globalThis  !== "undefined" ? globalThis
+             : typeof self        !== "undefined" ? self
+             : typeof window      !== "undefined" ? window
+             : typeof global      !== "undefined" ? global
+             : (() => { throw new Error("[ZSM GlobalScoping] :: Unable to determine global scope!"); })();
+
+export default GLOBAL;

package/IdentityIndexing.js

@@ -0,0 +1,51 @@
+/**
+ * @file            IdentityIndexing.js
+ * @description     This module provides functions to bind a user identifier (UID) to an identity ID (IID) in IndexedDB and to retrieve the IID associated with a given UID.
+ * @author          Jason Jurusz for Ideem
+ * @version         1.0.0
+ * @exports         uid2iid, iid4uid
+ * @todo            Migrate this code into the WebAssembly module.
+ */
+
+/**
+ * @name            uid2iid
+ * @description     Binds a user identifier (UID) to an identity ID (IID) in IndexedDB.
+ * @param           {string}    uid     The user identifier (UID) to bind.
+ * @param           {string}    iid     The identity ID (IID) to bind to the UID.
+ * @throws          {Error}             If unable to bind UID to IID or if a DB Connection Error occurs.
+ * @returns         {void}
+ */
+function uid2iid(uid, iid) {
+    const idbInstance     = indexedDB.open("ideem", 1);
+    idbInstance.onerror   = (err=idbInstance.error) => { throw new Error(`[IdentityIndexing] :: uid2iid :: Unable to bind UID to IID:\n${err}`); }
+    idbInstance.onsuccess = (e, db=e.target.result) => {
+        const zsmTbl      = db.transaction("zsm", "readwrite");
+        const write       = zsmTbl.objectStore("zsm").put(iid, uid);
+        write.onsuccess   = () => (db.close());
+        write.onerror     = (err=write.error) => (db.close(), console.error(`[IdentityIndexing] :: uid2iid :: Unable to bind UID to IID:\n${err}`));
+    };
+}
+
+/**
+ * @name            iid4uid
+ * @description     Finds the identity ID for a given user identifier (UID) in IndexedDB.
+ * @param           {string}    uid     The user identifier (UID) to search for.
+ * @returns         {Promise<string>}   A promise that resolves to the identity ID (IID) associated with the UID, or the UID itself if not found.
+ * @throws          {Error}             If unable to search IndexedDB or if a DB Connection Error occurs.
+ */
+function iid4uid(uid) {
+    return new Promise((resolve, reject) => {
+        const idbInstance           = indexedDB.open("ideem", 1);
+        idbInstance.onupgradeneeded = (e, db=e.target.result) => { if (!db.objectStoreNames.contains("zsm")) db.createObjectStore("zsm");};
+        idbInstance.onerror         = (err=idbInstance.error) => { return reject(new Error(`[IdentityIndexing] :: iid4uid :: Unable to connect to IDB:\n${err}`)); }
+        idbInstance.onsuccess       = (e, db=e.target.result) => {
+            if(!db.objectStoreNames.contains("zsm")) return resolve(uid);
+            const zsmTbl            = db.transaction("zsm", "readonly");
+            const lookup            = zsmTbl.objectStore("zsm").get(uid);
+            lookup.onsuccess        = () => (db.close(), (lookup.result) ? resolve(lookup.result) : resolve(uid));
+            lookup.onerror          = (err=lookup.error) => (db.close(), console.error(`[IdentityIndexing] :: iid4uid :: Unable to find IID for UID:\n${err}`), reject(new Error(`[IdentityIndexing] :: iid4uid :: Unable to find IID for UID:\n${err}`)));
+        };
+    });
+}
+
+export { uid2iid, iid4uid };

package/PluginManager.js

@@ -0,0 +1,111 @@
+class PluginManager {
+    #sdkClassMap = new Map();           // Map of SDK class names to their implementations
+    #classCorpus = new Map();           // Map of plugin identities to their class maps
+    #status      = 'INITIALIZED';       // Indicates the current status of the plugin manager (INITIALIZED, SEEDED, FROZEN)
+
+    /**
+     * Returns whether the plugin manager is frozen.
+     * @returns         {boolean}                                       True if the plugin manager is frozen, false otherwise.
+     */
+    get isFrozen() {
+        return this.#status === 'FROZEN';
+    }
+
+    /**
+     * @name            classes
+     * @description     Retrieves the SDK class associated with the given class description.
+     * @param           {string}                    classDesc           The name of the class to retrieve.
+     * @returns         {Function}                                      The SDK class associated with the given name.
+     * @throws          {Error}                                         If the classDesc is not provided
+     * @throws          {Error}                                         If no class is registered for the given name.
+     */
+    classes (classDesc) {
+        if(this.#status === 'INITIALIZED')              throw new Error('[zsmPluginManager] :: classes :: collection accessor cannot be referenced before SOME classes are registered!');
+        if(!classDesc || typeof classDesc !== 'string') throw new Error(`[zsmPluginManager] :: classes :: collection accessor requires a valid class description (received ${typeof classDesc}: ${classDesc})!`);
+        classDesc = classDesc.toUpperCase();
+        if(!this.isFrozen){
+            console.warn('[zsmPluginManager] :: Freezing the plugin manager as the first class has been preemptively requested. No further plugins can be registered after this point.\nIf you feel you received this message unexpectedly, please ensure all plugins are imported before initializing (`new UMFAClient()` or `new FIDO2Client()`) a client.');
+            this.freezePlugins();
+        }
+        if(!this.#sdkClassMap.has(classDesc))           throw new Error(`[zsmPluginManager] :: classes :: No SDK class registered for: ${classDesc}`);
+        return this.#sdkClassMap.get(classDesc);
+    }
+
+    /**
+     * @name            seedClassMap
+     * @description     Seeds the class map with initial values.
+     * @param           {Object<string, Object>}  registeredObj       The key-value pairs to seed the class map with.
+     * @returns         {Map<string, Function>}                        A Map containing the seeded class definitions
+     */
+    seedClassMap(registeredObj) {
+        const constructedMap = new Map();
+        for (const [classDesc, ctor] of Object.entries(registeredObj.classDefs || {})) {
+            if(ctor) constructedMap.set(classDesc.toUpperCase(), ctor);
+        }
+        return constructedMap;
+    }
+
+    /**
+     * @name            registerPlugin
+     * @description     Registers a plugin with the plugin manager.
+     * @param           {string}                    pluginIdentity      The unique identity of the plugin.
+     * @param           {Object<string, Function>}  classObj            The class map for the plugin.
+     * @throws          {Error}                                         Throws an error if the plugin manager is frozen.
+     */
+    registerPlugin(pluginIdentity, classObj){
+        if (this.isFrozen) throw new Error('[zsmPluginManager] :: registerPlugin :: Cannot register plugin: PlugInManager is frozen!\nThis typically occurs when a plugin is imported after a client - UMFAClient or FIDO2Client - has already been initialized.\nMake sure to import all plugins before initializing (`new UMFAClient()` or `new FIDO2Client()`) a client.');
+        if (!pluginIdentity || typeof classObj !== 'object' || classObj == null)  throw new Error('[zsmPluginManager] :: registerPlugin :: pluginIdentity and class map object required');
+
+        this.#status = 'SEEDED';
+
+        this.#classCorpus.set(pluginIdentity.toUpperCase(), classObj);
+        console.info(`[zsmPluginManager] :: PluginManager :: Registered plugin "${pluginIdentity}".`);
+        return true;
+    }
+
+    /**
+     * @name            freezePlugins
+     * @description     Freezes the plugin manager, preventing further modifications.
+     */
+    freezePlugins(){
+        if (this.isFrozen) return;           // If the plugin manager is already frozen, bail.
+
+        // Below is the plug-in precedence resolution logic. As new plugins are registered, they may override core classes.
+        // As new plugins are DEVELOPED, they may introduce new classes or modify existing ones, and their extension/override logic must be declared below.
+        
+        // [CORE PACKAGE] Default all of the active classes to the "core" classes (set below this declaration)
+        const core = this.#classCorpus.get('CORE');
+        if (!core) throw new Error('[zsmPluginManager] :: freezePlugins :: Core not registered before freeze');
+        
+        const constructedMap = this.seedClassMap(core); // returns Map
+
+        // [PASSKEYS+ PLUGIN PACKAGE] If the "PASSKEYS+" plugin is registered, supercede the core classes with the passkeys classes
+        if(this.#classCorpus.has('PASSKEYS+')) {
+            const passkeysMap = this.#classCorpus.get('PASSKEYS+');
+            if (passkeysMap?.classDefs) for (const [k,v] of Object.entries(passkeysMap.classDefs)) constructedMap.set(k.toUpperCase(), v);
+        }
+        
+        // Apply class decorators (wrappers) AFTER overlays, if present in any of the registrations
+        const postConstructDecorators = [...this.#classCorpus.values()].filter(entry => entry.mode === 'DECORATOR');
+        if (postConstructDecorators.length) {
+            for (const modifier of postConstructDecorators) {
+                let { classDesc, postModFn } = modifier;
+                if (typeof postModFn !== 'function') throw new Error('[zsmPluginManager] :: freezePlugins :: Decorator must contain a valid function (received ' + typeof postModFn + ')');
+                
+                const baseCtor = constructedMap.get(classDesc.toUpperCase());
+                if (typeof baseCtor !== 'function') throw new Error(`[zsmPluginManager] :: freezePlugins :: Decorator targets unknown class "${classDesc}"`);
+                
+                const decorated = postModFn(baseCtor);
+                if (typeof decorated !== 'function') throw new Error('[zsmPluginManager] :: freezePlugins :: Decorator must return a constructor (received ' + typeof decorated + ')');
+                constructedMap.set(classDesc.toUpperCase(), decorated);
+            }
+        }
+        
+        this.#sdkClassMap = constructedMap;
+        this.#status = 'FROZEN';
+    }
+}
+
+const pluginManager = new PluginManager()
+
+export { pluginManager as zsmPluginManager };