@ideem/zsm-client-sdk 2.7.1 → 2.8.0

package/RelyingPartyBase.js

@@ -1,6 +1,7 @@
-import eventCoordinator from './EventCoordinator.js';
-import GLOBAL           from './GlobalScoping.js';
-import {uid2iid}        from './IdentityIndexing.js';
+import eventCoordinator          from './EventCoordinator.js';
+import GLOBAL                    from './GlobalScoping.js';
+import {uid2iid}                 from './IdentityIndexing.js';
+import { b64urlToBuf, toObject } from './Utils.js';
 
 
 eventCoordinator.update('RelyingPartyBase');
@@ -71,20 +72,20 @@ class RelyingPartyBase {
     /**
      * @name            clearEnrollmentCredentials
      * @description     Clears the enrollment credentials.
-     * @returns         {Promise<ZSMAPI>}  
+     * @returns         {Promise<ZSMAPI>}
      */
     clearEnrollmentCredentials () { return (this.publicKey = this.credentialID = null) };
     /**
      * @name            clearLoginCredentials
      * @description     Clears the login credentials.
      * @returns         {Promise<Void>}
-     * @todo            Verify nothing is calling this and remove it outright.  
+     * @todo            Verify nothing is calling this and remove it outright.
      */
     clearLoginCredentials () {};
     /**
      * @name            resetAll
      * @description     Resets all credentials.
-     * @returns         {Promise<Void>}                   
+     * @returns         {Promise<Void>}
      */
     resetAll () { return (this.clearLoginCredentials(), this.clearEnrollmentCredentials()); }
 
@@ -215,6 +216,155 @@ class RelyingPartyBase {
                 .then(result => result)
                 .catch(error => Promise.reject(new Error(error)));
     }
+
+    //! PASSKEYS PLUS RELYING PARTY METHODS =========================================================================================================================
+    /**
+     * @name            pkpRegistrationStart
+     * @description     Starts the registration process for a passkey using the Relying Party.
+     * @param           {string}                userIdentifier      The identifier for the user.
+     * @param           {string}                userVerified        Indicates if the user has been verified.
+     * @param           {string|null}           zsmCredChainID      (Optional) The ZSM Credential Chain ID for linking credentials.
+     * @returns         {Promise<Object>}                           Resolves with the Relying Party Challenge object.
+     * @throws          {Error}                                     If the Relying Party Challenge is not retrieved successfully.
+     * @throws          {Error}                                     If the public key is not found in the Relying Party Challenge.
+     * @throws          {Error}                                     If the user ID is not found in the Relying Party Challenge.
+     * @memberOf        RelyingPartyBase
+     */
+    async pkpRegistrationStart (userIdentifier, userVerified, zsmCredChainID = null) {
+        const requestBody = zsmCredChainID ? {chain_handoff: 'internal', chain_credential_id: zsmCredChainID} : {chain_handoff: 'internal'};
+        const paChallenge = await this.makePostRequest(`api/passkey/registration/create-identity-then-start`, requestBody)
+                .then(data   => {
+                    if(data.identity_id){
+                        GLOBAL.mpcConfig.consumer_id = data.identity_id;
+                        uid2iid(this.userIdentifier, data.identity_id);
+                    }
+                    return {publicKey:(this.publicKey = data.ccr.publicKey), identity_id:data.identity_id}
+                })
+                .then(result => result)
+                .catch(error => Promise.reject(new Error(error)));
+        if(!paChallenge)                   throw new Error(`[PK+ RelyingParty] :: pkpRegistrationStart :: Unable to retrieve Platform Authority Challenge from Relying Party Server!`);
+        if(!paChallenge?.publicKey)        throw new Error(`[PK+ RelyingParty] :: pkpRegistrationStart :: Platform Authority Challenge's Public Key was not found!`);
+
+        paChallenge.publicKey.challenge    = b64urlToBuf(paChallenge.publicKey.challenge);
+        if(!paChallenge?.publicKey?.user)  throw new Error(`[PK+ RelyingParty] :: pkpRegistrationStart :: User for the Platform Authority Challenge Public Key's user node was not found!`);
+
+        paChallenge.publicKey.user.id      = b64urlToBuf(paChallenge.publicKey.user.id);
+        return paChallenge;
+    }
+
+    /**
+     * @name            pkpRegistrationFinish
+     * @description     Completes the registration process for a passkey using the Relying Party.
+     * @param           {Object}                credential          The Platform Authenticator Credential object.
+     * @returns         {Promise<Object>}                           Resolves with the registration result.
+     * @throws          {TypeError}                                 If the Platform Authenticator Credential is not provided.
+     * @throws          {Error}                                     If the Platform Authenticator response is invalid.
+     * @memberOf        RelyingPartyBase
+     * @async
+     */
+    async pkpRegistrationFinish (credential) {
+        if (!credential) throw new TypeError('[PK+ RelyingParty] :: pkpRegistrationFinish :: No Platform Authenticator Credential provided!');
+
+        return this.makePostRequest(`api/passkey/registration/finish`, { credential })
+                .then(body => {
+                    this.credentialID = credential.rawId;
+                    return {credential, credentialID: this.credentialID, response: {credentialID: this.credentialID, ...body}};
+                })
+                .catch(err => {
+                    this.clearEnrollmentCredentials();
+                    throw new Error('[PK+ RelyingParty] :: pkpRegistrationFinish :: Unable to complete registration!', {cause: err});
+                });
+    }
+
+    /**
+     * @name            pkpAuthenticationStart
+     * @description     Starts the authentication process for a passkey using the Relying Party.
+     * @param           {object}                credentialData      The credential data object (cleanFinalData shape, possibly with userIdentifier attached).
+     * @returns         {Promise<Object>}                           Resolves with the Relying Party Challenge object.
+     * @throws          {TypeError}                                 If the Credential Data object is not provided.
+     * @throws          {Error}                                     If the Credential Data object does not contain valid IDs.
+     * @throws          {Error}                                     If the Relying Party Challenge is not retrieved successfully.
+     * @throws          {Error}                                     If the RCR challenge and/or publicKey is not found in the Relying Party Challenge.
+     * @throws          {Error}                                     If the allowCredentials and/or id is not found in the Relying Party Challenge.
+     * @memberOf        RelyingPartyBase
+     * @async
+     */
+    async pkpAuthenticationStart (credentialData) {
+
+        if(credentialData == null || typeof credentialData !== 'object')
+                throw new TypeError('[PK+ RelyingParty] :: pkpAuthenticationStart :: No Credential Data object provided!');
+        if(!credentialData.hasRemotePasskey && !credentialData.zsmCredentialID)                                                       // [J] Field names updated to match cleanFinalData
+                throw new Error('[PK+ RelyingParty] :: pkpAuthenticationStart :: Credential Data object does not contain a valid Passkeys+ Credential ID or ZSM Credential ID!');
+
+        const body = {
+                        credential_id       : credentialData?.pkpCredentialID,                                                                                      // [J] PKP credential ID not present in cleanFinalData; to be addressed when cleanFinalData is moved to post-RP boundary
+                        chain_credential_id : credentialData.zsmCredentialID,                                                          // [J] Was .zsmCredID
+                        chain_handoff       : credentialData?.chainHandoff   || 'internal',
+                        chain_challenge     : credentialData?.pkpCredential ? JSON.stringify(credentialData.pkpCredential) : null,
+                     };
+
+        let paChallenge = await this.makePostRequest( `api/passkey/authentication/start`, body)
+        if(paChallenge instanceof Error || !paChallenge)
+            throw new Error('[PK+ RelyingParty] :: pkpAuthenticationStart :: Unable to retrieve Platform Authority Challenge from Relying Party Server!', {cause: paChallenge});
+
+        paChallenge                       = toObject(paChallenge);
+
+        if(!paChallenge?.rcr ||
+           !paChallenge?.rcr?.publicKey)  throw new Error(`[PK+ RelyingParty] :: pkpAuthenticationStart :: Platform Authority's RCR challenge and/or publicKey was not found!`);
+
+        const paRCRPublicKey              = paChallenge.rcr.publicKey;
+        paRCRPublicKey.challenge          = b64urlToBuf(paRCRPublicKey.challenge);
+        const paAllowCredentials          = paRCRPublicKey.allowCredentials;
+
+        if(!paAllowCredentials ||
+            !paAllowCredentials[0]?.id)   throw new Error(`[PK+ RelyingParty] :: pkpAuthenticationStart :: Platform Authority Challenge's allowCredentials and/or id was not found!`);
+
+        paAllowCredentials[0].id           = b64urlToBuf(paAllowCredentials[0].id);
+
+        return paRCRPublicKey;
+    }
+
+    /**
+     * @name            pkpAuthenticationFinish
+     * @description     Completes the authentication process for a passkey using the Relying Party.
+     * @param           {Object}                paCredential        The Platform Authenticator Credential object.
+     * @returns         {Promise<Object>}                           Resolves with the authentication result.
+     * @throws          {Error}                                     If the Platform Authenticator Credential is not provided.
+     * @throws          {Error}                                     If the Platform Authenticator response is invalid.
+     * @memberOf        RelyingPartyBase
+     * @async
+     */
+    async pkpAuthenticationFinish (credential) {
+        if (!credential || typeof credential !== 'object') throw new Error('[PK+ RelyingParty] :: pkpAuthenticationFinish :: No Platform Authenticator Credential provided or is not an object!');
+        return this.makePostRequest(`api/passkey/authentication/finish`, { credential })
+                .then(body => ({credential, response: body}))
+                .catch(err => Promise.reject(new Error('[PK+ RelyingParty] :: pkpAuthenticationFinish :: Unable to complete authentication!', {cause: err})));
+    }
+
+
+    /**
+     * @name            getRemoteEnrollmentDetails
+     * @description     Retrieves remote enrollment details for a given user identifier.
+     * @param           {string}                userIdentifier      The user identifier.
+     * @param           {Object}                localDataPayload    The local data payload.
+     * @returns         {Promise<Object>}                           Resolves with the enrollment details.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+
+    async getRemoteEnrollmentDetails (userIdentifier, localDataPayload, bootstrap=false) {
+        // console.log('[CORE] :: [RelyingPartyBase] :: getRemoteEnrollmentDetails :: userIdentifier, localDataPayload', userIdentifier, localDataPayload);
+        const body = {
+            customer_defined_identifier: userIdentifier,
+        };
+        if(!bootstrap) {                                                                                                                        // [J] During the initial bootstrap, we want to minimize the data sent in this request to reduce the payload size and speed up the response; on subsequent calls, we can include the full localDataPayload for more informed server responses
+            // if(localDataPayload['zsm_credential_id']) body.zsmCredentialID = localDataPayload['zsm_credential_id'];                                       // [J] Field names updated to match cleanFinalData
+            // if(localDataPayload['passkey_credential_id']) body.pkpCredentialID = localDataPayload['passkey_credential_id'];                         // [J] Field names updated to match cleanFinalData
+        }
+
+        const response = await this.makePostRequest('/api/v1/enrollment-details', body);
+        // console.log('[CORE] :: [RelyingPartyBase] :: getRemoteEnrollmentDetails :: response', response);
+        return response;
+    }
 }
 //## END RelyingPartyBase =====================================================================================================================================
 

package/UMFAClientBase.js

@@ -1,5 +1,10 @@
 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  {
     /**
@@ -10,20 +15,62 @@ class UMFAClientBase  {
    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);
-        this.unenroll         = this.unenroll.bind(this);
-        this.resetDevice      = this.resetDevice.bind(this);
+        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
@@ -32,79 +79,252 @@ class UMFAClientBase  {
      * @returns         {Promise<Object>}                               Returns the results of zsmAPI.checkIdentity
      * @memberOf        FIDO2ClientBase, WebAuthnClient
      */
-    async checkIdentity    (userIdentifier, primeEnroll) { return this.zsmAPI.checkIdentity(userIdentifier, primeEnroll); }
+    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
-     * @param           {string}                    targetData          The type of data to retrieve ('id' for credential ID, 'all' for full details)
      * @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, targetData='id') {
-        try {
-            if(userIdentifier == null 
-                || userIdentifier === '')     throw new Error(`[UMFAClient] :: checkEnrollment :: A userIdentifier String is required! Received: ${userIdentifier}.`);
-            const enrollmentStatus = await this.zsmAPI.webauthnRetrieve(userIdentifier, targetData);
-
-            return enrollmentStatus;
-        } catch(e) {
-            return new Error(e.message || e || '[UMFAClient] :: checkEnrollment :: An error occurred while attempting to check enrollment.');
-        }
+    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) {
+    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.
 
-        // try {
-            if(userIdentifier == null 
-                || userIdentifier === '')     throw new Error(`[UMFAClient] :: enroll :: A userIdentifier String is required! Received: ${userIdentifier}.`);
-            const resultOfCheck = await this.zsmAPI.checkIdentity(userIdentifier, true);
+                } 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.`);
 
-            const createResult                = await this.zsmAPI.webauthnCreate(userIdentifier); 
+                } 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
 
-            if(createResult instanceof Error) throw(`[UMFAClient] :: enroll :: Unable to associate ${userIdentifier}'s identity with device profile.\nDetails:\n${createResult}`);
-            return createResult;
-        // }catch(e) {
-        //     return new Error(e.message || e || '[UMFAClient] :: enroll :: An error occurred during enrollment.');
-        // }
-    }
+                } 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) {
-        try {
-            if(userIdentifier == null 
-                || userIdentifier === '')     throw new Error(`[UMFAClient] :: authenticate :: A userIdentifier String is required! Received: ${userIdentifier}.`);
-            let userIsEnrolled                  = await this.checkEnrollment(userIdentifier);
-            if(userIsEnrolled === false)        throw(`${userIdentifier} is not enrolled.`);
-            let authCredential                  = await this.zsmAPI.webauthnPartialGet(userIdentifier);
-            return authCredential?.credential??authCredential;
-        }catch(e) {
-            return new Error(e.message || e || '[UMFAClient] :: authenticate :: An error occurred during authentication.');
+    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
@@ -115,15 +335,13 @@ class UMFAClientBase  {
      * @memberOf        UMFAClientBase
      */
     async unenroll(userIdentifier) {
-        try {
-            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;
-        } catch(e) {
-            return new Error(e.message || e || '[UMFAClient] :: unenroll :: An error occurred during unenrollment.');
-        }
+        ({ 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;
     }
 
     /**