@ideem/zsm-client-sdk 2.8.1 → 2.9.1

package/UMFAClientBase.js

@@ -1,356 +1 @@
-import eventCoordinator from './EventCoordinator.js';
-import {zsmPluginManager}   from './PluginManager.js';
-import { encodeUserIdentifier } from './encodeUserIdentifier.js';
-
-// [J]    The lines modified during the concatenation of the PKP Plugin into the Core SDK have been marked with a
-// [J]    `[J]` comment, to make it easier to identify during code review and for cross-platform porting purposes.
-// [J]    They can all be removed en masse by replacing `/ *\/\/ [J].*/gm` with `""` (and SHOULD be pre-publish).
-
-class UMFAClientBase  {
-    /**
-     * Base class for UMFAClient, providing methods for user enrollment and authentication.
-     * @constructor
-     * @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');
-        this.zsmAPI                  = new WebAuthnClient(config);
-
-        this.checkEnrollment         = this.checkEnrollment.bind(this);
-        this.enroll                  = this.enroll.bind(this);
-        this.authenticate            = this.authenticate.bind(this);
-                                                                                                                            // [J] Note that only EXPOSED methods are BOUND in the constructor
-        this.checkAllEnrollments     = this.checkAllEnrollments.bind(this);                                                 // [J] Migrated from PKP Plugin
-        this.passkeyPlusEnroll       = this.passkeyPlusEnroll.bind(this);                                                   // [J] Migrated from PKP Plugin
-        this.passkeyPlusAuthenticate = this.passkeyPlusAuthenticate.bind(this);                                             // [J] Migrated from PKP Plugin
-
-        this.unenroll                = this.unenroll.bind(this);
-        this.resetDevice             = this.resetDevice.bind(this);
-
-        eventCoordinator.update('UMFAClientBase', 'READY');
-    }
-
-    get userIdentifier()    { return this.zsmAPI.userIdentifier; }
-    get credentialID()      { return this.zsmAPI.credentialID;   }
-
-    /**
-     * @name            typeChecks
-     * @description     Performs type and value checks on the userIdentifier and userVerification parameters for the enroll and authenticate methods, and normalizes the userVerification value
-     * @param           {string}                    methodName          The name of the method calling typeChecks, used for error messages
-     * @param           {string}                    userIdentifier      The identifier for the user, required to be a non-empty string
-     * @param           {string|boolean|null}       userVerification        The level of user verification required for authentication, can be a boolean or a string ("preferred", "prevented", "required", "discouraged")
-     * @param           {string}                    addlUVStates        Additional acceptable user verification states to be added to the check against the userVerification parameter, passed as a comma-separated string (e.g. "zsm,re-enroll,reenroll")
-     * @returns         {Object}                                        An object containing the validated and normalized userIdentifier and userVerification values
-     * @throws          {TypeError}                                     If the userIdentifier is not provided, is empty, or is not a string
-     * @throws          {TypeError}                                     If the userVerification value is not a boolean or an accepted string value
-     * @memberOf        UMFAClientBase
-     */
-    typeChecks(methodName, userIdentifier, userVerification=null, addlUVStates="") {
-        if(!userIdentifier) throw new TypeError(`[UMFAClient] :: ${methodName} :: A userIdentifier String or Object is required! Received: ${userIdentifier} (type: ${typeof userIdentifier}).`);
-        let enrollmentDetails;
-        if(typeof userIdentifier === 'object') {
-            enrollmentDetails = {...userIdentifier};
-            userIdentifier = userIdentifier.userIdentifier;
-        }
-
-        if(userVerification != null){
-            if(typeof userVerification === 'boolean') userVerification = (userVerification === true) ? "preferred" : "prevented";
-            else if(typeof userVerification === 'string') userVerification = userVerification.toLowerCase();
-            else throw new TypeError(`[UMFAClient] :: ${methodName} :: userVerification must be a boolean or string. Received type: ${typeof userVerification}.`);
-
-            const uvList = ['preferred', 'required', 'discouraged', 'prevented', ...addlUVStates.split(/, ?/g).filter(Boolean)];
-            const uvRE = new RegExp(`^(${uvList.join('|')})$`);
-            if(!uvRE.test(userVerification)) throw new TypeError(`[UMFAClient] :: ${methodName} :: userVerification must be one of the following Strings: "${uvList.join('", "')}"). Received: ${userVerification}.`);
-        }
-        userIdentifier = encodeUserIdentifier(userIdentifier);                                                               // [J] Encode the userIdentifier before it is used in any downstream operations (no-op stub pending hash algorithm selection)
-        let retVal = { userIdentifier, userVerification };
-        if(enrollmentDetails) retVal = { enrollmentDetails, ...retVal };                                                   // If the userIdentifier was passed in as part of an enrollmentDetails object, we want to preserve the other fields on that object and pass them downstream with the updated userIdentifier value
-        return retVal;
-    }
-
-    /**
-     * @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
-     */
-    async checkIdentity    (userIdentifier, primeEnroll) { return this.zsmAPI.checkIdentity(encodeUserIdentifier(userIdentifier), primeEnroll); }
-
-    /**
-     * @name            checkEnrollment
-     * @description     Checks if a ZSM credential is enrolled on the device for the specified user
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @returns         {Promise<Object>|boolean}                       Resolves with the enrollment details or false if not enrolled, or an error if checking fails
-     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                         If an error occurs while checking enrollment
-     * @memberOf        UMFAClientBase
-     */
-    async checkEnrollment(userIdentifier) {                                                                                 // [J] Removing now-useless second parameter, as the checkAllEnrollments method returns all details; checkEnrollment returns ONLY the credential ID
-        ({ userIdentifier } = this.typeChecks('checkEnrollment', userIdentifier));
-        const enrollmentStatus = await this.zsmAPI.webauthnRetrieve(userIdentifier);
-
-        return enrollmentStatus;
-    }
-
-    /**
-     * @name            checkAllEnrollments
-     * @description     Pass-through method to call WebAuthnClient's webauthnRetrieveAll
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @returns         {Promise<Object>}                               Returns the full enrollment details for the user
-     * @memberOf        UMFAClientBase
-     */
-    async checkAllEnrollments(userIdentifier, forceRemoteCheck=false) { return this.zsmAPI.webauthnRetrieveAll(encodeUserIdentifier(userIdentifier), forceRemoteCheck); }                   // [J] Migrated from PKP Plugin
-
-    /**
-     * @name            enroll
-     * @description     Enrolls a user by creating a ZSM credential on the device
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @param           {string}                    userVerification        The level of user verification required for authentication (true/"preferred", false/"prevented", "required", "discouraged", "zsm", or "re-enroll"/"reenroll")
-     * @returns         {Promise<Object>|boolean}                       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
-     * @throws          {Error}                                         If the object returned from the ZSM API is not valid (no credential)
-     * @memberOf        UMFAClientBase
-     */
-    async enroll(userIdentifier, userVerification="prevented") {                                                                 // [J] This method has been merged with the PKP Plugin's enroll method
-        ({ userIdentifier, userVerification } = this.typeChecks('enroll', userIdentifier, userVerification, 'zsm,re-enroll,reenroll'));
-        const isPasskeyReenrollment    = /^re-?enroll$/.test(userVerification);                                                              // Is this a forced PKP re-enrollment?
-        const attemptPasskeyPlusEnroll = isPasskeyReenrollment || /^(preferred|required)$/.test(userVerification);                                                   // [J] Does the userVerification value indicate that Passkeys+ enrollment should be attempted alongside ZSM enrollment?
-        const continueOnPasskeyFailure = (userVerification === 'preferred');
-
-        let pkpEnrollmentResult, enrollmentDetails;
-        if(attemptPasskeyPlusEnroll) {
-            enrollmentDetails = await this.checkAllEnrollments(userIdentifier);
-            try {
-                if(!enrollmentDetails.passkeySupported) {                                                                             // If Passkeys+ is not supported, but required, throw an error immediately
-                    if(!continueOnPasskeyFailure)                                                                                      // ...and if the userVerification is "required", fail the entire enrollment operation...
-                        return new Error(`[UMFAClient] :: enroll :: Passkeys+ is required for enrollment (userVerification set to "required"), but this device does not support Passkeys+. User ${userIdentifier} cannot be enrolled. Please use a Passkeys+-compatible device to enroll.`);
-                    else
-                        console.warn(`[UMFAClient] :: enroll :: Passkeys+ enrollment has been requested, but this device does not support Passkeys+. User ${userIdentifier} will be enrolled with ZSM-only credentials. Please use a Passkeys+-compatible device to enroll with Passkeys+ in the future.`);
-                } else if (isPasskeyReenrollment) {                                                                                    // Current state doesn't matter. User has specified a new passkey is to be added...
-                    if (!enrollmentDetails.zsmCredentialID && !enrollmentDetails.hasLocalPasskey)                                  //   ... so, unless the user doesn't have credentials AT ALL...
-                        return new Error(`[UMFAClient] :: enroll :: Cannot RE-enroll user's passkey; user ${userIdentifier} is not currently enrolled with either ZSM or Passkeys+ credentials. To enroll the user, call enroll with a userVerification value of "preferred", "required", or "discouraged".`);
-                    pkpEnrollmentResult = await this.passkeyPlusEnroll(enrollmentDetails, 'required');                                 //   ... we trigger the Passkeys+ enrollment flow. Failure mode behavior is static: either passkey works or boot them entirely.
-
-                } else if (enrollmentDetails.zsmCredentialID && enrollmentDetails.hasLocalPasskey) {                               // ZSM: ✅ | PKP: ✅ | Remote PKP: ✅  - User already fully-registered; fail the operation.
-                    return new Error(`[UMFAClient] :: enroll :: User ${userIdentifier} is already enrolled with both ZSM and Passkeys+ credentials. To authenticate one or both credential, call the authenticate method.`);
-
-                } else if ((enrollmentDetails instanceof Error || enrollmentDetails === false) ||
-                           (!enrollmentDetails.zsmCredentialID && !enrollmentDetails.hasLocalPasskey)) {                           // ZSM: ❌ | PKP: ❌ | Remote PKP: ❌  - Dual enrollment for both ZSM and PKP...
-                    pkpEnrollmentResult = await this.passkeyPlusEnroll(enrollmentDetails, userVerification);                           // ...so we attempt Passkeys+ enrollment. Failure mode behavior is dictated by userVerification
-
-                } else if (enrollmentDetails.zsmCredentialID && !enrollmentDetails.hasLocalPasskey) {                              // ZSM: ✅ | PKP: ❌ | Remote PKP: ❌  - User has ZSM only...
-                    pkpEnrollmentResult = await this.addPasskeyToZSMCredential(enrollmentDetails, userVerification);                   // ...so we attempt to add Passkeys+ to existing ZSM credential. Failure mode behavior is dictated by userVerification
-
-                } else if (!enrollmentDetails.zsmCredentialID && enrollmentDetails.pkpCredential) {                      // ZSM: ❌ | PKP: ✅ | Remote PKP: ✅ - User ONLY has a (remote) passkey (which the checkAllEnrollments bootstrapped down to local)...
-                    pkpEnrollmentResult = await this.addZSMToPasskeyCredential(enrollmentDetails, userVerification);                   // ...so we attempt to add ZSM credential to existing Passkeys+ credential. Failure mode behavior is dictated by userVerification
-                }
-                return (pkpEnrollmentResult === undefined) 
-                       ? new Error(`[UMFAClient] :: enroll :: Unexpected PKP flow: PKP enrollment attempted but no result was returned for user ${userIdentifier}.`) 
-                       : pkpEnrollmentResult;
-            //TODO: Determine the cause of the passkey failure and tailor the below error message accordingly (currently only handles NotAllowedError: user cancellation/timeout/failure).
-            } catch (pkpError) {                                                                                                       // If the passkey portion of the operation fails (for ANY reason)...
-                console.error('ENROLL FLOW :: PASSKEY OPERATION FAILED ::', pkpError);
-                if (!continueOnPasskeyFailure)                                                                                         // ...and the userVerification is "required", return an error to fail the entire enrollment operation...
-                    return new Error(`[UMFAClient] :: enroll :: The passkey portion of the Passkeys+ enrollment failed for user ${userIdentifier} with error: ${pkpError.message || pkpError}. Since userVerification is set to "${userVerification}", the entire enrollment process has failed. You may: retry, downgrade the userVerification mandate to "preferred" or "discouraged" to allow for ZSM-only enrollment.`);
-            }
-        }
-
-        // The code below handles ZSM-only enrollments, as well as providing the "fallback-to-ZSM-only" behavior for acceptable Passkeys+ failures (e.g. userVerification === "preferred")
-        let localZSMCredentialID;
-        if(enrollmentDetails?.zsmCredentialID) localZSMCredentialID = enrollmentDetails?.zsmCredentialID                           // No sense in hitting the ZSM credential check if we already have the enrollment details from the pkp section, above...
-        else localZSMCredentialID = await this.checkEnrollment(userIdentifier);                                                        //   ...but if we didn't, let's check the local-only operation for the credential ID
-
-        if(typeof localZSMCredentialID === 'string') {                                                                                 // If the user is ALREADY enrolled with a ZSM credential, fail the operation
-            return new Error(`[UMFAClient] :: enroll :: User ${userIdentifier} is already enrolled with a ZSM credential. To authenticate it, call the authenticate method.`);
-        }
-
-        await this.zsmAPI.checkIdentity(userIdentifier, true);                                                                         // [J] This checkIdentity call "primes" the enrollment on the server & sets credentialID/userIdentifier on the zsmAPI instance
-        const createResult = await this.zsmAPI.webauthnCreate(userIdentifier);                                                         // Perform the vanilla ZSM enrollment.
-        if(createResult instanceof Error)                                                                                              // Should the operation fail...
-            return new Error(`[UMFAClient] :: enroll :: Unable to enroll ${userIdentifier}!\nDetails:\n${createResult?.message || createResult}`, {cause: createResult?.stack});
-        return createResult;                                                                                                           // ...otherwise, all operations either succeeded or failed acceptably, so we return the result of the ZSM enrollment 
-    }
-    
-    /**
-     * @name            authenticate
-     * @description     Authenticates a user by retrieving their ZSM credential
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @param           {string}                    userVerification        The level of user verification required for authentication (true/"preferred", false/"prevented", "required", "discouraged", "zsm")
-     * @returns         {Promise<Object>}                               Resolves with the authentication result or an error if authentication fails
-     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                         If an error occurs during authentication
-     * @memberOf        UMFAClientBase
-     */
-    async authenticate (userIdentifier, userVerification="prevented") {                                                         // [J] This method has been merged with the PKP Plugin's authenticate method
-        ({ userIdentifier, userVerification } = this.typeChecks('authenticate', userIdentifier, userVerification, 'zsm'));
-
-        
-        const attemptPasskeyPlusAuth = /^(preferred|required)$/.test(userVerification);                                                   // [J] Does the userVerification value indicate that Passkeys+ enrollment should be attempted alongside ZSM enrollment?
-        const continueOnPasskeyFailure = (userVerification === 'preferred');
-        
-        // Passkeys+ Operations
-        let pkpAuthResult, enrollmentDetails;
-        if(attemptPasskeyPlusAuth) {
-            enrollmentDetails = await this.checkAllEnrollments(userIdentifier);
-
-            if(!enrollmentDetails.zsmCredentialID) {                                                                         // [J] Field names updated to match cleanFinalData
-
-                return new Error(`[UMFAClient] :: authenticate :: User ${userIdentifier} must be enrolled with a ZSM credential before authenticating. Please enroll the user first.`);
-            } else if (!enrollmentDetails.passkeySupported) {
-
-                return new Error(`[UMFAClient] :: authenticate :: User ${userIdentifier} is not eligible for Passkeys+ authentication; their device does not support passkey authentication. To authenticate, call the authenticate method with userVerification set to "preferred", "discouraged", or "prevented"/"zsm". To enroll with Passkeys+, call enroll with userVerification set to "preferred" or "required" on a Passkeys+-compatible device.`);
-            } else if(!enrollmentDetails.hasLocalPasskey) {
-
-                return new Error(`[UMFAClient] :: authenticate :: User ${userIdentifier} must be enrolled with both ZSM and Passkeys+ credentials to authenticate using Passkeys+ (userVerification set to a non-prevented value).`);
-            } else if(attemptPasskeyPlusAuth) {
-
-                try {
-                    pkpAuthResult = await this.passkeyPlusAuthenticate(enrollmentDetails, userVerification);
-
-                } catch (pkpError) {
-                    if (!continueOnPasskeyFailure) return new Error(`[UMFAClient] :: authenticate :: The passkey portion of the Passkeys+ authentication failed for user ${userIdentifier} with error: ${pkpError.message || pkpError}. Since userVerification is set to "${userVerification}", the entire authentication process has failed. You may: retry or downgrade the userVerification mandate to "preferred" or "discouraged" to allow for ZSM-only authentication.`);
-                }
-                return (pkpAuthResult === undefined)
-                       ? new Error(`[UMFAClient] :: authenticate :: Unexpected PKP flow: PKP authentication attempted but no result was returned for user ${userIdentifier}.`)
-                       : pkpAuthResult;
-            }
-        }
-
-        // The code below handles ZSM-only enrollments, as well as providing the "fallback-to-ZSM-only" behavior for acceptable Passkeys+ failures (e.g. userVerification === "preferred")
-        let localZSMCredentialID;
-        if(enrollmentDetails?.zsmCredentialID) localZSMCredentialID = enrollmentDetails?.zsmCredentialID                           // No sense in hitting the ZSM credential check if we already have the enrollment details from the pkp section, above...
-        else localZSMCredentialID = await this.checkEnrollment(userIdentifier);                                                        //   ...but if we didn't, let's check the local-only operation for the credential ID
-        
-        const userIsEnrolled = typeof localZSMCredentialID === 'string';
-        if(userIsEnrolled === false) return new Error(`[UMFAClient] :: authenticate :: ${userIdentifier} is not enrolled. To authenticate the user, please enroll them first by calling the enroll method.`);
-
-        const authCredential = await this.zsmAPI.webauthnPartialGet(userIdentifier);
-        return authCredential?.credential??authCredential;
-    }
-    
-    async addPasskey(userIdentifier, userVerification="required") {
-        let enrollmentDetails;
-        ({ userIdentifier, userVerification, enrollmentDetails } = this.typeChecks('addPasskey', userIdentifier, userVerification, 're-enroll,reenroll'));
-
-
-        let passkeyAddResult;
-        if(!enrollmentDetails) passkeyAddResult = await this.addPasskeyToZSMCredential((enrollmentDetails || userIdentifier), userVerification);
-        else                   passkeyAddResult = await this.zsmAPI.pkpCreate((enrollmentDetails || userIdentifier), userVerification);
-        return passkeyAddResult;
-    }
-
-    // PKP Methods ============================================================================================================
-    // [J] These were migrated from PKP Plugin with minimal adjustments to fit into the UMFAClientBase class structure and flow
-    /**
-     * @name            passkeyPlusEnroll
-     * @description     Creates a Passkeys+ credential for the user, if the user is not already enrolled, then creates a ZSM credential
-     * @param           {string}                userIdentifier      The identifier for the user
-     * @param           {string}                userVerification        Accepts "required", "preferred", "discouraged", to be passed into the Passkey ceremony
-     * @returns         {Promise<Object>}                           The results of the call to WebAuthnClient's pkpCreate method or an Error
-     * @throws          {Error}                                     If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                     If an error occurs during Passkeys+ enrollment
-     * @memberOf        UMFAClientBase
-     */
-    async passkeyPlusEnroll (userIdentifier, userVerification="preferred") {
-
-        ({ userIdentifier, userVerification } = this.typeChecks('passkeyPlusEnroll', userIdentifier, userVerification, 're-enroll,reenroll'));
-
-        const pkpCreateResult = await this.zsmAPI.pkpCreate(userIdentifier, userVerification);
-
-        return pkpCreateResult;
-    }
-
-    /**
-     * @name            passkeyPlusAuthenticate
-     * @description     Authenticates a user using Passkeys+ credentials
-     * @param           {string}                userIdentifier      The identifier for the user
-     * @param           {string}                userVerification        Accepts "required", "preferred", "discouraged", to be passed into the Passkey ceremony
-     * @returns         {Promise<Object>}                           The results of the call to WebAuthnClient's pkpAuthenticate method or an Error
-     * @throws          {Error}                                     If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                     If an error occurs during Passkeys+ authentication
-     * @memberOf        UMFAClientBase
-     */
-    async passkeyPlusAuthenticate (userIdentifier, userVerification="preferred") {
-
-        let enrollmentDetails = null;
-        ({ userIdentifier, userVerification, enrollmentDetails } = this.typeChecks('passkeyPlusAuthenticate', userIdentifier, userVerification, 're-enroll,reenroll'));
-        if(!enrollmentDetails) enrollmentDetails = await this.checkAllEnrollments(userIdentifier, true);
-
-        // console.log('userIdentifier, userVerification, enrollmentDetails :', userIdentifier, userVerification, enrollmentDetails);
-
-        // const enrollmentDetails = await this.checkAllEnrollments(userIdentifier);
-        const pkpAuthResult     = await this.zsmAPI.pkpAuthenticate(enrollmentDetails, userVerification, !enrollmentDetails.zsmCredentialID);  // [J] Field name updated to match cleanFinalData
-        return pkpAuthResult;
-    }
-
-    /**
-     * @name            addZSMToPasskeyCredential
-     * @description     Adds a ZSM credential for a user who already has Passkeys+ credentials registered on another device.
-     * @param           {string}                userIdentifier      The identifier for the user.
-     * @param           {string}                userVerification        Accepts "required", "preferred", "discouraged", to be passed into the Passkey ceremony.
-     * @returns         {Promise<Object>}                           Completed ZSM + Passkeys+ authentication result.
-     * @throws          {Error}                                     If no Passkeys+ credentials are found for the user on another device.
-     * @memberOf        UMFAClientBase
-     */
-    async addZSMToPasskeyCredential (userIdentifier, userVerification) {
-        ({ userIdentifier } = this.typeChecks('addZSMToPasskeyCredential', userIdentifier));
-
-        const passkeyPreauth = await this.passkeyPlusAuthenticate(userIdentifier);
-        return passkeyPreauth;
-    }
-
-    /**
-     * @name            addPasskeyToZSMCredential
-     * @description     Adds a Passkeys+ credential for a user who already has a local ZSM credential.
-     * @param           {string}                userIdentifier      The identifier for the user.
-     * @param           {string}                userVerification        Accepts "required", "preferred", "discouraged", to be passed into the Passkey ceremony.
-     * @returns         {Promise<Object>}                           Completed ZSM + Passkeys+ authentication result.
-     * @throws          {Error}                                     If no ZSM credentials are found for the user on another device.
-     * @memberOf        UMFAClientBase
-     */
-    async addPasskeyToZSMCredential (userIdentifier, userVerification="preferred") {
-
-        let enrollmentDetails = null;
-        ({ userIdentifier, userVerification, enrollmentDetails } = this.typeChecks('addPasskeyToZSMCredential', userIdentifier, userVerification, 're-enroll,reenroll'));
-
-        const pkpAddPasskeyResult = await this.zsmAPI.pkpAddPasskeyCredential((enrollmentDetails || userIdentifier), userVerification);
-
-        return pkpAddPasskeyResult;
-    }
-
-    // Delete/Decouple Methods ================================================================================================
-    /**
-     * @name            unenroll
-     * @description     Unenrolls a user by removing their ZSM credential from the device
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @returns         {Promise<boolean>}                              Resolves with true if unenrollment was successful, false if the user was not enrolled, or an error if unenrollment fails
-     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                         If an error occurs during unenrollment
-     * @memberOf        UMFAClientBase
-     */
-    async unenroll(userIdentifier) {
-        ({ userIdentifier } = this.typeChecks('unenroll', userIdentifier));
-
-        let userIsEnrolled                  = await this.checkEnrollment(userIdentifier);
-        if(userIsEnrolled === false)        return false;
-        let unenrollResult                  = await this.zsmAPI.unbindFromDevice(userIdentifier);
-        if(unenrollResult instanceof Error) throw(`Unable to unenroll ${userIdentifier}'s identity from this device.\nDetails:\n${unenrollResult}`);
-        return unenrollResult === true;
-    }
-
-    /**
-     * @name            resetDevice
-     * @description     Pass-through method to call WebAuthnClient's webauthnReset
-     * @returns         {Promise<void>}                               No results are returned
-     * @memberOf        UMFAClientBase, WebAuthnClient
-     */
-    async resetDevice() { this.zsmAPI.webauthnReset(); }
-}
-
-export default UMFAClientBase;
+import e from"./EventCoordinator.js";import{zsmPluginManager as t}from"./PluginManager.js";import{encodeUserIdentifier as r}from"./encodeUserIdentifier.js";export default class{constructor(r){e.reset(),e.update("UMFAClientBase"),this.config=r;const s=t.classes("WEBAUTHNCLIENT");this.zsmAPI=new s(r),this.checkEnrollment=this.checkEnrollment.bind(this),this.enroll=this.enroll.bind(this),this.authenticate=this.authenticate.bind(this),this.checkAllEnrollments=this.checkAllEnrollments.bind(this),this.passkeyPlusEnroll=this.passkeyPlusEnroll.bind(this),this.passkeyPlusAuthenticate=this.passkeyPlusAuthenticate.bind(this),this.unenroll=this.unenroll.bind(this),this.resetDevice=this.resetDevice.bind(this),e.update("UMFAClientBase","READY")}get userIdentifier(){return this.zsmAPI.userIdentifier}get credentialID(){return this.zsmAPI.credentialID}typeChecks(e,t,s=null,i=""){if(!t)throw new TypeError(`[UMFAClient] :: ${e} :: A userIdentifier String or Object is required! Received: ${t} (type: ${typeof t}).`);let n;if("object"==typeof t&&(n={...t},t=t.userIdentifier),null!=s){if("boolean"==typeof s)s=!0===s?"preferred":"prevented";else{if("string"!=typeof s)throw new TypeError(`[UMFAClient] :: ${e} :: userVerification must be a boolean or string. Received type: ${typeof s}.`);s=s.toLowerCase()}const t=["preferred","required","discouraged","prevented",...i.split(/, ?/g).filter(Boolean)];if(!new RegExp(`^(${t.join("|")})$`).test(s))throw new TypeError(`[UMFAClient] :: ${e} :: userVerification must be one of the following Strings: "${t.join('", "')}"). Received: ${s}.`)}let a={userIdentifier:t=r(t),userVerification:s};return n&&(a={enrollmentDetails:n,...a}),a}async allowBrowserObserversToSettle(){"undefined"!=typeof window&&("function"==typeof requestAnimationFrame&&await new Promise(e=>requestAnimationFrame(e)),await new Promise(e=>setTimeout(e,0)))}async checkIdentity(e,t){return this.zsmAPI.checkIdentity(r(e),t)}async checkEnrollment(e){({userIdentifier:e}=this.typeChecks("checkEnrollment",e));return await this.zsmAPI.webauthnRetrieve(e)}async checkAllEnrollments(e,t=!1){return this.zsmAPI.webauthnRetrieveAll(r(e),t)}async enroll(e,t="prevented"){await this.allowBrowserObserversToSettle(),({userIdentifier:e,userVerification:t}=this.typeChecks("enroll",e,t,"zsm,re-enroll,reenroll"));const r=/^re-?enroll$/.test(t),s="preferred"===t;let i,n,a;if(r||/^(preferred|required)$/.test(t)){n=await this.checkAllEnrollments(e);try{if(n.passkeySupported)if(r){if(!n.zsmCredentialID&&!n.hasLocalPasskey)return new Error(`[UMFAClient] :: enroll :: Cannot RE-enroll user's passkey; user ${e} is not currently enrolled with either ZSM or Passkeys+ credentials. To enroll the user, call enroll with a userVerification value of "preferred", "required", or "discouraged".`);i=await this.passkeyPlusEnroll(n,"required")}else{if(n.zsmCredentialID&&n.hasLocalPasskey)return new Error(`[UMFAClient] :: enroll :: User ${e} is already enrolled with both ZSM and Passkeys+ credentials. To authenticate one or both credential, call the authenticate method.`);n instanceof Error||!1===n||!n.zsmCredentialID&&!n.hasLocalPasskey?i=await this.passkeyPlusEnroll(n,t):n.zsmCredentialID&&!n.hasLocalPasskey?i=await this.addPasskeyToZSMCredential(n,t):!n.zsmCredentialID&&n.pkpCredential&&(i=await this.addZSMToPasskeyCredential(n,t))}else{if(!s)return new Error(`[UMFAClient] :: enroll :: Passkeys+ is required for enrollment (userVerification set to "required"), but this device does not support Passkeys+. User ${e} cannot be enrolled. Please use a Passkeys+-compatible device to enroll.`);console.warn(`[UMFAClient] :: enroll :: Passkeys+ enrollment has been requested, but this device does not support Passkeys+. User ${e} will be enrolled with ZSM-only credentials. Please use a Passkeys+-compatible device to enroll with Passkeys+ in the future.`)}return void 0===i?new Error(`[UMFAClient] :: enroll :: Unexpected PKP flow: PKP enrollment attempted but no result was returned for user ${e}.`):i}catch(r){if(console.error("ENROLL FLOW :: PASSKEY OPERATION FAILED ::",r),!s)return new Error(`[UMFAClient] :: enroll :: The passkey portion of the Passkeys+ enrollment failed for user ${e} with error: ${r.message||r}. Since userVerification is set to "${t}", the entire enrollment process has failed. You may: retry, downgrade the userVerification mandate to "preferred" or "discouraged" to allow for ZSM-only enrollment.`)}}if(a=n?.zsmCredentialID?n?.zsmCredentialID:await this.checkEnrollment(e),"string"==typeof a)return new Error(`[UMFAClient] :: enroll :: User ${e} is already enrolled with a ZSM credential. To authenticate it, call the authenticate method.`);await this.zsmAPI.checkIdentity(e,!0);const l=await this.zsmAPI.webauthnCreate(e);return l instanceof Error?new Error(`[UMFAClient] :: enroll :: Unable to enroll ${e}!\nDetails:\n${l?.message||l}`,{cause:l?.stack}):l}async authenticate(e,t="prevented"){await this.allowBrowserObserversToSettle(),({userIdentifier:e,userVerification:t}=this.typeChecks("authenticate",e,t,"zsm"));const r=/^(preferred|required)$/.test(t),s="preferred"===t;let i,n,a;if(r){if(n=await this.checkAllEnrollments(e),!n.zsmCredentialID)return new Error(`[UMFAClient] :: authenticate :: User ${e} must be enrolled with a ZSM credential before authenticating. Please enroll the user first.`);if(!n.passkeySupported)return new Error(`[UMFAClient] :: authenticate :: User ${e} is not eligible for Passkeys+ authentication; their device does not support passkey authentication. To authenticate, call the authenticate method with userVerification set to "preferred", "discouraged", or "prevented"/"zsm". To enroll with Passkeys+, call enroll with userVerification set to "preferred" or "required" on a Passkeys+-compatible device.`);if(!n.hasLocalPasskey)return new Error(`[UMFAClient] :: authenticate :: User ${e} must be enrolled with both ZSM and Passkeys+ credentials to authenticate using Passkeys+ (userVerification set to a non-prevented value).`);if(r){try{i=await this.passkeyPlusAuthenticate(n,t)}catch(r){if(!s)return new Error(`[UMFAClient] :: authenticate :: The passkey portion of the Passkeys+ authentication failed for user ${e} with error: ${r.message||r}. Since userVerification is set to "${t}", the entire authentication process has failed. You may: retry or downgrade the userVerification mandate to "preferred" or "discouraged" to allow for ZSM-only authentication.`)}return void 0===i?new Error(`[UMFAClient] :: authenticate :: Unexpected PKP flow: PKP authentication attempted but no result was returned for user ${e}.`):i}}a=n?.zsmCredentialID?n?.zsmCredentialID:await this.checkEnrollment(e);if(!1===("string"==typeof a))return new Error(`[UMFAClient] :: authenticate :: ${e} is not enrolled. To authenticate the user, please enroll them first by calling the enroll method.`);const l=await this.zsmAPI.webauthnPartialGet(e);return l?.credential??l}async addPasskey(e,t="required"){let r,s;return await this.allowBrowserObserversToSettle(),({userIdentifier:e,userVerification:t,enrollmentDetails:r}=this.typeChecks("addPasskey",e,t,"re-enroll,reenroll")),s=r?await this.zsmAPI.pkpCreate(r||e,t):await this.addPasskeyToZSMCredential(r||e,t),s}async passkeyPlusEnroll(e,t="preferred"){await this.allowBrowserObserversToSettle(),({userIdentifier:e,userVerification:t}=this.typeChecks("passkeyPlusEnroll",e,t,"re-enroll,reenroll"));return await this.zsmAPI.pkpCreate(e,t)}async passkeyPlusAuthenticate(e,t="preferred"){await this.allowBrowserObserversToSettle();let r=null;({userIdentifier:e,userVerification:t,enrollmentDetails:r}=this.typeChecks("passkeyPlusAuthenticate",e,t,"re-enroll,reenroll")),r||(r=await this.checkAllEnrollments(e,!0));return await this.zsmAPI.pkpAuthenticate(r,t,!r.zsmCredentialID)}async addZSMToPasskeyCredential(e,t){({userIdentifier:e}=this.typeChecks("addZSMToPasskeyCredential",e));return await this.passkeyPlusAuthenticate(e)}async addPasskeyToZSMCredential(e,t="preferred"){let r=null;({userIdentifier:e,userVerification:t,enrollmentDetails:r}=this.typeChecks("addPasskeyToZSMCredential",e,t,"re-enroll,reenroll"));return await this.zsmAPI.pkpAddPasskeyCredential(r||e,t)}async unenroll(e){if(({userIdentifier:e}=this.typeChecks("unenroll",e)),!1===await this.checkEnrollment(e))return!1;let t=await this.zsmAPI.unbindFromDevice(e);if(t instanceof Error)throw`Unable to unenroll ${e}'s identity from this device.\nDetails:\n${t}`;return!0===t}async resetDevice(){this.zsmAPI.webauthnReset()}}

package/Utils.js

@@ -1,44 +1 @@
-/**
- * @name            b64urlToBuf
- * @description     Converts a Base64 URL-encoded string to an ArrayBuffer.
- * @param           {string}                b64url              The Base64 URL-encoded string to convert.
- * @returns         {ArrayBuffer}                               The converted ArrayBuffer.
- * @throws          {TypeError}                                 Throws a TypeError if the input is not a valid Base64 URL-encoded string.
- * @example         b64urlToBuf('c29tZV9iYXNlNjRfdGVzdA')       // Converts to ArrayBuffer
- * @see             https://developer.mozilla.org/en-US/docs/Web/API/Base64/Using_Base64_encoding#base64url, https://developer.mozilla.org/en-US/docs/Web/API/atob, https://developer.mozilla.org/en-US/docs/Web/API/Uint8Array, https://developer.mozilla.org/en-US/docs/Web/API/ArrayBuffer
- * @memberof        Utils
- */
-const b64urlToBuf = (b64url) => {
-    if (typeof b64url !== 'string' || b64url.length === 0)
-        throw new TypeError(`[Utils] :: b64urlToBuf :: This method expects a base64 encoded string as input. Received: "${b64url}" (of type ${typeof b64url} and length ${b64url.length}).`);
-
-    const padded = (b64url + '====').slice(0, -b64url.length % 4);
-
-    const binary = atob(padded.replace(/-/g, '+').replace(/_/g, '/'));
-    
-    const buffer = Uint8Array.from(binary, c => c.charCodeAt(0)).buffer;
-    
-    return buffer;
-}
-
-/**
- * @name            toObject
- * @description     Recursively converts potentially-nested data structures (Map, Array, Object) to a plain object.
- * @                This is in use specifically because of wasm-bindgen's proclivity to OCCASIONALLY return Map objects instead of plain objects.
- * @param           {any}                   inp                 The input data structure to convert.
- * @returns         {Object}                                    The converted plain object.
- * @throws          {TypeError}                                 Throws a TypeError if the input is not a valid data structure.
- * @example         toObject(new Map([['key', 'value']]))
- * @memberof        Utils
- */
-const toObject = (inp) => {
-  if (inp === null || typeof inp !== 'object') return inp;                                          // Primitives & functions pass through
-
-  if (inp instanceof Map) return Object.fromEntries([...inp].map(([k, v]) => [k, toObject(v)]));    // Recursively convert Map's nodes
-
-  if (Array.isArray(inp)) return inp.map(toObject);                                                 // Recursively convert arrays' nodes
-
-  return Object.fromEntries(Object.entries(inp).map(([k, v]) => [k, toObject(v)]));                 // Recursively convert plain objects' nodes
-};
-
-export { b64urlToBuf, toObject };
+const e=e=>{if("string"!=typeof e||0===e.length)throw new TypeError(`[Utils] :: b64urlToBuf :: This method expects a base64 encoded string as input. Received: "${e}" (of type ${typeof e} and length ${e.length}).`);const t=(e+"====").slice(0,-e.length%4),r=atob(t.replace(/-/g,"+").replace(/_/g,"/"));return Uint8Array.from(r,e=>e.charCodeAt(0)).buffer},t=e=>null===e||"object"!=typeof e?e:e instanceof Map?Object.fromEntries([...e].map(([e,r])=>[e,t(r)])):Array.isArray(e)?e.map(t):Object.fromEntries(Object.entries(e).map(([e,r])=>[e,t(r)]));export{e as b64urlToBuf,t as toObject};