@ideem/zsm-client-sdk 2.6.0 → 2.6.2

package/CHANGELOG.md

@@ -1,19 +1,38 @@
-ZSM Client SDK for Browser Apps
-Latest version: v2.5.0
-Latest release date: Aug 29, 2025
+# ZSM Client SDK for Browser Apps
 
 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: 
+- Documentation: https://docs.useideem.com/pkp 
 - Support: support@useideem.com 
 
 ## Known Issues
-- 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.
+- None at this time.
 
 ----
+## Release 2.6.2 - December 19, 2025 [ NPM PACKAGE RELEASE ] **[ LATEST ]**
+- Hotfix release to address an issue with the Passkeys+ plugin integration.
 
-## Release 2.5.0 - Aug 29, 2025 [ NPM PACKAGE RELEASE ] **[ LATEST ]**
+## Release 2.6.1 - December 16, 2025 [ NPM PACKAGE RELEASE ]
+- Minor bug fixes and improvements
+- Minor alteration to initialization process to remove the need to provide a `userIdentifier` when initializing (all method calls now provide the update).
+- Improvements to EventCoordinator:
+  - Streamlined onReset to ensure that all events are set to "PENDING" state.
+  - Improved onReady handling to ensure accurate state representation.
+  - Enhanced error handling and reporting mechanisms.
+- Improvements to NPM packaging and distribution process for use with additional package managers and build tools.
+- Reduced complexity of `zsm_app_config.json` file by:
+  - Removing _necessity_ of `use_passkeys` and `use_origin` properties (now auto-detected based on environment and browser capabilities).
+  - Simplifying host URL configuration down to a `region` property; host URLs are now auto-generated based on region although previous syntax is still supported for backward compatibility.
+
+## Release 2.6.0 - November 26, 2025 [ NPM PACKAGE RELEASE ]
+- Support of updated Passkeys plugin that provides migration scenarios for ZSM to Passkeys+ and boostrapping of new device using existing passkey. 
+
+## Release 2.5.1 - October 6, 2025 [ NPM PACKAGE RELEASE ] 
+- Minor improvements
+
+## Release 2.5.0 - Aug 29, 2025 [ NPM PACKAGE RELEASE ] 
 - 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

package/EventCoordinator.js

@@ -52,6 +52,13 @@ class EventCoordinator {
     set coreReady(value) { this.coreSDKClass.ready          = !!value;             }
     set coreErrs(value)  { this.coreSDKClass.containsErrors = !!value;             }
 
+    /**
+     * @name            setCoreSDKClass
+     * @description     Sets the core SDK class reference on the EventCoordinator instance, and defines its "finished" method.
+     * @param           {string}            classDesc       The name of the client class being initialized (UMFAClient or FIDO2Client).
+     * @param           {Object}            classRef        The reference to the core SDK class being initialized.
+     * @returns         {void}
+     */
     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
@@ -63,6 +70,12 @@ class EventCoordinator {
         this.specifyClient(classDesc);                                          // ... finally, specify the client class that is being initialized.
     }
 
+    /**
+     * @name            specifyClient
+     * @description     Specifies the active client class (UMFAClient or FIDO2Client) being initialized.
+     * @param           {string}            selectedClient     The name of the client class being initialized (UMFAClient or FIDO2Client).
+     * @returns         {void}
+     */
     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.`);
@@ -74,6 +87,12 @@ class EventCoordinator {
         }
     }
 
+    /**
+     * @name            summarizeEventStack
+     * @description     Logs a summary of the current event stack to the console.
+     * @param           {...any}            triggerData     Additional data to include in the log (e.g., the event that triggered the update).
+     * @returns         {void}
+     */
     summarizeEventStack (...triggerData) {
         let summaryObject = this.object,
             { client, containsErrors, done } = this;
@@ -102,6 +121,14 @@ class EventCoordinator {
         GLOBAL.dispatchEvent(new CustomEvent(eventName, { detail: eventDetail }));
     }
 
+    /**
+     * @name            update
+     * @description     Updates the status of a specific event in the event stack.
+     * @param           {string}            classDesc       The name of the event to update.
+     * @param           {string}            eventStatus     The new status for the event (accepts: UNREGISTERED, PENDING, READY, ERROR).
+     * @throws          {TypeError}                         If the classDesc is invalid or eventStatus is not one of the allowed values.
+     * @returns         {Object}                            Returns the updated event stack object.
+     */
     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.`);
@@ -175,7 +202,7 @@ class EventCoordinator {
      * @returns         {Object}                            Returns the reset event stack object.
      */
     reset() {
-        this._eventStack = new Map(this.cleanState);
+        this._eventStack.keys().forEach(key=>this._eventStack.set(key,'PENDING'));
         if(window && window?.queueMicrotask) {
             queueMicrotask(() => this.dispatchEvent('ZSMClientEventStackReset', { stack: this.object }));
         } else  this.dispatchEvent('ZSMClientEventStackReset', { stack: this.object });

package/FIDO2ClientBase.js

@@ -8,7 +8,7 @@ class FIDO2ClientBase {
      * @param {Object} config - The configuration for the FIDO2Client
     */
    constructor(config) {
-        if(eventCoordinator.done) eventCoordinator.reset();
+        eventCoordinator.reset();
         eventCoordinator.update('FIDO2ClientBase');
         this.config           = config;
         const WebAuthnClient  = zsmPluginManager.classes('WEBAUTHNCLIENT');

package/README.md

@@ -19,7 +19,7 @@ TypeScript.  These resources include documentation and example applications.
 Ideem support, <a href="mailto:support@useideem.com">support@useideem.com</a>, to obtain a unique Application ID.
 
 ### Documentation
-Documentation for this SDK can be found at: https://docs.useideem.com/sdk/browser/index.html. The documentation covers interfaces provided for FIDO2 Authenticator and Universal MFA integrations.  
+Documentation for this SDK can be found at: https://docs.useideem.com/pkp. The documentation covers interfaces provided for FIDO2 Authenticator and Universal MFA integrations.  
 
 ### Demos
 You can view demos of the FIDO2 Authenticator and Universal MFA Capabilities online at <a href="https://demo.useideem.com">https://demo.useideem.com</a>.
@@ -34,4 +34,4 @@ You can receive support and get your questions answered by emailing <a href="mai
 Please refer to the LICENSE file in this directory for the license governing the use of this SDK.
 
 ### Release Notes
-Please refer to the RELEASE_NOTES.txt file in this directory for the release notes of this SDK.
+Please refer to the CHANGELOG.md file in this directory for the release notes of this SDK.

package/UMFAClientBase.js

@@ -8,6 +8,7 @@ class UMFAClientBase  {
      * @param {Object} config - The configuration for ZSM initialization (ref: ./zsm_app_config.json)
     */
    constructor(config) {
+        eventCoordinator.reset();
         eventCoordinator.update('UMFAClientBase');
         this.config           = config;
         const WebAuthnClient  = zsmPluginManager.classes('WEBAUTHNCLIENT');

package/WebAuthnClientBase.js

@@ -22,7 +22,12 @@ class WebAuthnClientBase {
         // Helper function to standardize URL format (ensuring it's parsable and ends with a '/')
         const cleanURL = (url) => URL.canParse(url) ? new URL(url).origin + '/' : false;
 
-        const baseConfig         = {
+        if(config?.region){
+            config.authenticator_host_url ||= config.authenticator_host = `https://zsm-authenticator-${config.region}.useideem.com/`;
+            config.zsm_host_url           ||= config.zsm_host           = `https://zsm-${config.region}.useideem.com/`;
+        }
+
+        const baseConfig = {
             "application_id"           : "",
             "api_key"                  : "",
             "host_url"                 : "https://zsm-authenticator-demo.useideem.com/",
@@ -30,9 +35,15 @@ class WebAuthnClientBase {
             "log_level"                : 'Debug',
             "request_timeout_ms"       : 300000,
             "retry_count"              : 0,
-            "consumer_id"              : ""
+            "consumer_id"              : "",
+            "use_passkeys"             : true
         };
 
+        if(config?.use_passkeys===false || config?.use_origin===false){
+            delete config.use_passkeys;
+            delete config.use_origin;
+        }
+
         this.zsmApi       = undefined;    // The ZSM API instance (read: WASM-driven Crypto Module)
         this.relyingParty = undefined;    // The Relying Party instance (read: ZSM Authenticator API)
         this.status       = undefined;    // The status of the WebAuthnClientBase
@@ -108,7 +119,6 @@ class WebAuthnClientBase {
      */
     async initializeZsm () {
         if(GLOBAL.mpcConfig.consumer_id !== this.MPCConfig.consumer_id) {
-            // console.log('GLOBAL.mpcConfig :', Object.assign({},GLOBAL.mpcConfig));
             await this.zsmApi.configure(GLOBAL.mpcConfig);
             this.MPCConfig = await Object.assign({}, GLOBAL.mpcConfig);
             await uid2iid(this.config.consumer_id, this.MPCConfig.consumer_id);
@@ -127,7 +137,10 @@ class WebAuthnClientBase {
     */
 
     async checkIdentity (userIdentifier, primeEnroll=false) {
-
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: checkIdentity :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
+        
         try {
             const resultOfCheck = await this.relyingParty.checkServerSideIdentity(primeEnroll);
 
@@ -156,6 +169,9 @@ class WebAuthnClientBase {
      * @throws          {Error}                                     Throws a COUNTED error if unable to verify the credential with the Relying Party Server.
      */
     async webauthnCreate (userIdentifier) {
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: webauthnCreate :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
 
         await this.initializeZsm('webauthnCreate');
 
@@ -200,22 +216,25 @@ class WebAuthnClientBase {
      * @throws          {Error}                                     Throws an error if the user ID or token is missing from the response body.
      */
     async webauthnCreateMpcThenFinish (userIdentifier, publicKey, pairing_token) {
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: webauthnCreateMpcThenFinish :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
         this.status = 'ENROLLMENT_STARTING';
-        await this.initializeZsm('webauthnCreate');
+        await this.initializeZsm('webauthnCreateMpcThenFinish');
 
         let createResponse = await this.zsmApi.webauthn_create(publicKey, pairing_token, userIdentifier, tracePrimer());
-        if(!createResponse) throw new Error('[WebAuthnClient - mpc_round] :: webauthnCreate :: Unable to obtain response from Crypto Server!');
+        if(!createResponse) throw new Error('[WebAuthnClient - mpc_round] :: webauthnCreateMpcThenFinish :: Unable to obtain response from Crypto Server!');
 
         createResponse = toObject(createResponse);
         GLOBAL.dispatchEvent(new CustomEvent("MPCResponse", {bubbles: true, cancelable: false, detail: createResponse }));
 
-        if(!createResponse?.result)            throw new Error('[WebAuthnClient - mpc_round] :: webauthnCreate :: Unable to obtain credential from Crypto Server!');
-        if(!createResponse?.result?.response)  throw new Error('[WebAuthnClient - mpc_round] :: webauthnCreate :: Unable to acquire attestation object!');
+        if(!createResponse?.result)            throw new Error('[WebAuthnClient - mpc_round] :: webauthnCreateMpcThenFinish :: Unable to obtain credential from Crypto Server!');
+        if(!createResponse?.result?.response)  throw new Error('[WebAuthnClient - mpc_round] :: webauthnCreateMpcThenFinish :: Unable to acquire attestation object!');
 
         const credential = createResponse.result;
 
         const registrationResult = await this.relyingParty.registrationFinish(credential);
-        if (!registrationResult) throw new Error('[WebAuthnClient] :: webauthnCreate :: Unable to verify credential Relying Party Server!');
+        if (!registrationResult) throw new Error('[WebAuthnClient] :: webauthnCreateMpcThenFinish :: Unable to verify credential Relying Party Server!');
 
         return registrationResult.credential;
     };
@@ -233,6 +252,9 @@ class WebAuthnClientBase {
      * @throws          {Error}                                     Throws an error if the user ID or token is missing from the response body.
      */
     async webauthnGet (userIdentifier) {
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: webauthnGet :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
 
         await this.initializeZsm('webauthnGet');
         const credentialId = await this.webauthnRetrieve(userIdentifier, true);
@@ -296,6 +318,9 @@ class WebAuthnClientBase {
      * @throws          {Error}                                     Throws an error if an uncaught/unhandled error occurs while retrieving the credential.
      */
     async webauthnRetrieve (userIdentifier) {
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: webauthnRetrieve :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
         this.credentialID = null;
 
         this.initializeZsm('webauthnRetrieve');
@@ -311,39 +336,6 @@ class WebAuthnClientBase {
         this.credentialID = response?.result['zsm_credential_id']??null;
         return this.credentialID || false;
     };
-//     async webauthnRetrieve (userIdentifier, targetData='id') {
-//         this.credentialID = null;
-// 
-//         this.initializeZsm('webauthnRetrieve');
-//         let credentialIdentifier     = await iid4uid(userIdentifier),
-//             requestedData            = {};
-//         GLOBAL.mpcConfig.consumer_id = credentialIdentifier;
-// 
-//         let response      = await this.zsmApi.webauthn_retrieve(userIdentifier);
-//             response      = toObject(response);
-// 
-//         if (response?.error || !response?.result) return false;
-//         
-//         this.credentialID = response?.result['zsm_credential_id']??null;
-// 
-//         if([undefined,true,false,null,'','id'].includes(targetData)) {
-//             return this.credentialID;
-//         } 
-//         let pkpCred = await iid4uid(`pk:${userIdentifier}`);
-//         if(pkpCred === `pk:${userIdentifier}`) pkpCred = undefined;
-//         requestedData = { 
-//             userIdentifier,
-//             zsmCredID        : this.credentialID, 
-//             hasZSMCred       : (this.credentialID != null), 
-//             pkpCredID        : pkpCred, 
-//             hasLocalPasskey       : (typeof pkpCred === 'string' && pkpCred !== ''),
-//             hasRemotePasskey : (typeof pkpCred === 'object')
-//         };
-//         if (targetData === "all") {
-//             return requestedData;
-//         }
-//         return response?.[targetData] ?? response?.result?.[targetData] ?? requestedData?.[targetData] ?? null;
-//     };
 
     /**
      * @name            webauthnPartialGet
@@ -357,6 +349,9 @@ class WebAuthnClientBase {
      * @emits           {CustomEvent}                              Emits a "MPCResponse" event with the mpcResponse data.
      */
     async webauthnPartialGet (userIdentifier) {
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: webauthnPartialGet :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
         this.status = 'AUTHENTICATION_STARTING';
         await this.initializeZsm('webauthnPartialGet');
 
@@ -399,6 +394,9 @@ class WebAuthnClientBase {
      * @throws          {Error<UnenrollError>}                     Throws an UnenrollError if a credential matching userIdentifier IS stored on the device, but was unable to be removed.
      */
     async unbindFromDevice (userIdentifier) {
+        if(userIdentifier == null 
+            || userIdentifier === '')         return new Error(`[WebAuthnClient] :: unbindFromDevice :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+        if(userIdentifier && typeof userIdentifier === 'string') this.userIdentifier = userIdentifier;
         this.status = 'UNENROLL_STARTING';
         if(userIdentifier !== this.userIdentifier) return false;
         await this.initializeZsm('unbindFromDevice');

package/package.json

@@ -1,72 +1,70 @@
 {
-    "name": "@ideem/zsm-client-sdk",
-    "version": "2.6.0",
-    "description": "ZSM makes 2FA easy and invisible for everyone, all the time, using advanced cryptography like MPC to establish cryptographic proof of the origin of any transaction or login attempt, while eliminating opportunities for social engineering. ZSM has no reliance on specific hardware. Our cryptographic module has completed FIPS 140-3 NIST approved lab testing, is FIDO2-ready, and is on the Modules In Progress (MIP) list. Superior Usability. no opt-in, no codes, no downloads, no authenticator apps. Better Security.",
-    "author": "@JJ (Jason Jurusz) <jj@useideem.com>/<nerdy.deeds@done.cheap>",
-    "keywords": [
-        "ideem",
-        "zsm",
-        "zsm-client-sdk",
-        "UMFAClient",
-        "FIDO2Client",
-        "library",
-        "UMFA",
-        "FIDO2",
-        "client",
-        "authentication",
-        "javascript",
-        "multi-factor",
-        "webauthn",
-        "authentication",
-        "security",
-        "cryptography",
-        "MPC",
-        "FIPS",
-        "NIST",
-        "FIDO2-ready",
-        "Modules In Progress",
-        "MIP"
-    ],
-    "type": "module",
-    "main": "./ZSMClientSDK.js",
-    "scripts": {
-        "start": "echo 'This is the Ideem SDK library, not a freestanding application. There is no start script defined. To use, import the library into a browser application.' 1>&2",
-        "version": "echo \"$(npm pkg get name | tr -d \\\") current version: $(npm pkg get version | tr -d \\\")\""
-    },
-    "collaborators": [
-        "Joel Teply <joel@useideem.com>",
-        "Todd Decker <todd@useideem.com>",
-        "Brian Koziel <brian@useideem.com>"
-    ],
-    "license": "SEE LICENSE IN LICENSE",
-    "repository": {
-        "type": "git",
-        "url": "github : useideem/vHSM"
-    },
-    "homepage": "https://useideem.com",
-    "bugs": "https://github.com/useideem/vHSM/issues",
-    "files": [
-        "./ErrorHandler.js",
-        "./EventCoordinator.js",
-        "./FIDO2Client.js",
-        "./FIDO2ClientBase.js",
-        "./GlobalScoping.js",
-        "./IdentityIndexing.js",
-        "./package.json",
-        "./PluginManager.js",
-        "./RelyingParty.js",
-        "./RelyingPartyBase.js",
-        "./shims/",
-        "./UMFAClient.js",
-        "./UMFAClientBase.js",
-        "./Utils.js",
-        "./WASMRustInterface.js",
-        "./WebAuthnClient.js",
-        "./WebAuthnClientBase.js",
-        "./ZSMClientSDK.js",
-        "./CHANGELOG.md",
-        "./LICENSE",
-        "./README.md"
-    ],
-    "sideEffects": false
+    "name"          : "@ideem/zsm-client-sdk",
+    "version"       : "2.6.2",
+    "description"   : "ZSM makes 2FA easy and invisible for everyone, all the time, using advanced cryptography like MPC to establish cryptographic proof of the origin of any transaction or login attempt, while eliminating opportunities for social engineering. ZSM has no reliance on specific hardware. Our cryptographic module has completed FIPS 140-3 NIST approved lab testing, is FIDO2-ready, and is on the Modules In Progress (MIP) list. Superior Usability. no opt-in, no codes, no downloads, no authenticator apps. Better Security.",
+    "author"        : "Jason Jurusz <jj@useideem.com>",
+    "keywords"      : [ "ideem", "zsm", "zsm-client-sdk", "umfaclient", "fido2client", "library", "umfa", "fido", "fido2", "client", "javascript", "multifactor", "multi-factor", "webauthn", "authentication", "security", "cryptography", "mpc", "fips", "nist", "mip", "passkeys" ],
+    "type"          : "module",
+    "main"          : "./ZSMClientSDK.js",
+    "exports"       : {
+                        "."      : "./ZSMClientSDK.js",
+                        "./*"    : "./*.js",
+                        "./*.js" : "./*.js"
+                      },
+
+    "scripts"       : {
+                        "start"       : "echo 'This is the Ideem SDK library, not a freestanding application. There is no start script defined. To use, import the library into a browser application.' 1>&2",
+                        "showVersion" : "echo \"$(npm pkg get name | tr -d \\\") current version: $(npm pkg get version | tr -d \\\")\""
+                    },
+    "collaborators" : [
+                        "Joel Teply <joel@useideem.com>",
+                        "Todd Decker <todd@useideem.com>",
+                        "Brian Koziel <brian@useideem.com>"
+                    ],
+    "license"       : "LicenseRef-Ideem",
+    "repository"    : {
+                        "type" : "git",
+                        "url"  : "git+https://github.com/useideem/vHSM.git"
+                    },
+    "homepage"      : "https://useideem.com",
+    "bugs"          : "https://github.com/useideem/vHSM/issues",
+    "files"         : [
+                        "./shims/",
+                        "./ErrorHandler.js",
+                        "./EventCoordinator.js",
+                        "./FIDO2Client.js",
+                        "./FIDO2ClientBase.js",
+                        "./GlobalScoping.js",
+                        "./IdentityIndexing.js",
+                        "./PluginManager.js",
+                        "./RelyingParty.js",
+                        "./RelyingPartyBase.js",
+                        "./UMFAClient.js",
+                        "./UMFAClientBase.js",
+                        "./Utils.js",
+                        "./WASMRustInterface.js",
+                        "./WebAuthnClient.js",
+                        "./WebAuthnClientBase.js",
+                        "./ZSMClientSDK.js",
+                        "./CHANGELOG.md",
+                        "./LICENSE",
+                        "./README.md"
+                    ],
+    "sideEffects"   : [
+                        "./EventCoordinator.js",
+                        "./FIDO2Client.js",
+                        "./FIDO2ClientBase.js",
+                        "./GlobalScoping.js",
+                        "./IdentityIndexing.js",
+                        "./PluginManager.js",
+                        "./RelyingParty.js",
+                        "./RelyingPartyBase.js",
+                        "./UMFAClient.js",
+                        "./UMFAClientBase.js",
+                        "./Utils.js",
+                        "./WASMRustInterface.js",
+                        "./WebAuthnClient.js",
+                        "./WebAuthnClientBase.js",
+                        "./ZSMClientSDK.js"
+                    ]
 }