@ideem/zsm-client-sdk 2.8.1 → 2.9.1

package/FIDO2ClientBase.js

@@ -1,337 +1,3 @@
-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 FIDO2ClientBase {
-    /**
-     * @constructor
-     * @param {Object} config - The configuration for the FIDO2Client
-    */
-   constructor(config) {
-        eventCoordinator.reset();
-        eventCoordinator.update('FIDO2ClientBase');
-        this.config           = config;
-        const WebAuthnClient  = zsmPluginManager.classes('WEBAUTHNCLIENT');
-        this.zsmAPI           = new WebAuthnClient(config);
-
-        this.checkEnrollment  = this.checkEnrollment.bind(this);
-        this.checkIdentity    = this.checkIdentity.bind(this);
-        this.webauthnRetrieve = this.webauthnRetrieve.bind(this);
-        this.webauthnDelete   = this.webauthnDelete.bind(this);
-        this.resetDevice      = this.resetDevice.bind(this);
-        this.webauthnCreate   = this.webauthnCreate.bind(this);
-        this.webauthnGet      = this.webauthnGet.bind(this);
-                                                                                                                            // [J] Note that only EXPOSED methods are BOUND in the constructor
-        this.checkAllEnrollments       = this.checkAllEnrollments.bind(this);                                                // [J] Migrated from PKP Plugin
-        this.webauthnPasskeyPlusCreate = this.webauthnPasskeyPlusCreate.bind(this);                                          // [J] Migrated from PKP Plugin
-        this.webauthnPasskeyPlusGet    = this.webauthnPasskeyPlusGet.bind(this);                                             // [J] Migrated from PKP Plugin
-
-        eventCoordinator.update('FIDO2ClientBase', '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 userVerified parameters for the webauthnCreate and webauthnGet methods, and normalizes the userVerified 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}       userVerified        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 userVerified parameter, passed as a comma-separated string (e.g. "zsm,re-enroll,reenroll")
-     * @returns         {Object}                                        An object containing the validated and normalized userIdentifier and userVerified values
-     * @throws          {TypeError}                                     If the userIdentifier is not provided, is empty, or is not a string
-     * @throws          {TypeError}                                     If the userVerified value is not a boolean or an accepted string value
-     * @memberOf        FIDO2ClientBase
-     */
-    typeChecks(methodName, userIdentifier, userVerified=null, addlUVStates="") {
-        if(!userIdentifier) throw new TypeError(`[FIDO2Client] :: ${methodName} :: A userIdentifier String is required! Received: ${userIdentifier} (type: ${typeof userIdentifier}).`);
-        let enrollmentDetails;
-        if(typeof userIdentifier === 'object') {
-            enrollmentDetails = {...userIdentifier};
-            userIdentifier = userIdentifier.userIdentifier;
-        }
-
-        if(userVerified != null){
-            if(typeof userVerified === 'boolean') userVerified = (userVerified === true) ? "preferred" : "prevented";
-            else if(typeof userVerified === 'string') userVerified = userVerified.toLowerCase();
-            else throw new TypeError(`[FIDO2Client] :: ${methodName} :: userVerified must be a boolean or string. Received type: ${typeof userVerified}.`);
-
-            const uvList = ['preferred', 'required', 'discouraged', 'prevented', ...addlUVStates.split(/, ?/g).filter(Boolean)];
-            const uvRE = new RegExp(`^(${uvList.join('|')})$`);
-            if(!uvRE.test(userVerified)) throw new TypeError(`[FIDO2Client] :: ${methodName} :: userVerified must be one of the following Strings: "${uvList.join('", "')}"). Received: ${userVerified}.`);
-        }
-        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, userVerified };
-        if(enrollmentDetails) retVal = { enrollmentDetails, ...retVal };
-        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        FIDO2ClientBase
-     */
-    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        FIDO2ClientBase
-     */
-    async checkAllEnrollments(userIdentifier, forceRemoteCheck=false) { return this.zsmAPI.webauthnRetrieveAll(encodeUserIdentifier(userIdentifier), forceRemoteCheck); }                   // [J] Migrated from PKP Plugin
-
-    /**
-     * @name            webauthnRetrieve
-     * @description     Pass-through method to call WebAuthnClient's webauthnRetrieve
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @returns         {Promise<Object>}                               Returns the results of zsmAPI.webauthnRetrieve
-     * @memberOf        FIDO2ClientBase, WebAuthnClient
-     */
-    webauthnRetrieve (userIdentifier) { return this.zsmAPI.webauthnRetrieve(encodeUserIdentifier(userIdentifier)); }
-
-    /**
-     * @name            webauthnDelete
-     * @description     Pass-through method to call WebAuthnClient's unbindFromDevice
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @returns         {Promise<Object>}                               Returns the results of zsmAPI.unbindFromDevice
-     * @memberOf        FIDO2ClientBase, WebAuthnClient
-     */
-    webauthnDelete   (userIdentifier) { return this.zsmAPI.unbindFromDevice(encodeUserIdentifier(userIdentifier)); }
-
-    /**
-     * @name            resetDevice
-     * @description     Pass-through method to call WebAuthnClient's webauthnReset
-     * @returns         {Promise<void>}                               No results are returned
-     * @memberOf        FIDO2ClientBase, WebAuthnClient
-     */
-    async resetDevice      ()               { this.zsmAPI.webauthnReset(); }
-
-    /**
-     * @name            webauthnCreate
-     * @description     Enrolls a user by creating a ZSM credential on the device
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @param           {string}                    userVerified        The level of user verification required for authentication (true/"preferred", false/"prevented", "required", "discouraged")
-     * @returns         {Promise<Object>|Error}                         Resolves with the created credential, false if user is already enrolled, or an error if enrollment fails
-     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                         If an error occurs during enrollment
-     * @memberOf        FIDO2ClientBase
-     */
-    async webauthnCreate (userIdentifier, userVerified="prevented") {                                                       // [J] This method has been merged with the PKP Plugin's __webauthnCreate method
-        ({ userIdentifier, userVerified } = this.typeChecks('webauthnCreate', userIdentifier, userVerified, 'zsm,re-enroll,reenroll'));
-        const isPasskeyReenrollment    = /^re-?enroll$/.test(userVerified);                                                              // Is this a forced PKP re-enrollment?
-        const attemptPasskeyPlusEnroll = isPasskeyReenrollment || /^(preferred|required)$/.test(userVerified);                            // [J] Does the userVerified value indicate that Passkeys+ enrollment should be attempted alongside ZSM enrollment?
-        const continueOnPasskeyFailure = (userVerified === '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 userVerified is "required", fail the entire enrollment operation...
-                        return new Error(`[FIDO2Client] :: webauthnCreate :: Passkeys+ is required for enrollment (userVerified 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(`[FIDO2Client] :: webauthnCreate :: 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(`[FIDO2Client] :: webauthnCreate :: Cannot RE-enroll user's passkey; user ${userIdentifier} is not currently enrolled with either ZSM or Passkeys+ credentials. To enroll the user, call webauthnCreate with a userVerified value of "preferred", "required", or "discouraged".`);
-                    pkpEnrollmentResult = await this.webauthnPasskeyPlusCreate(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: Y | PKP: Y | Remote PKP: Y  - User already fully-registered; fail the operation.
-                    return new Error(`[FIDO2Client] :: webauthnCreate :: User ${userIdentifier} is already enrolled with both ZSM and Passkeys+ credentials. To authenticate one or both credential, call the webauthnGet method.`);
-
-                } else if ((enrollmentDetails instanceof Error || enrollmentDetails === false) ||
-                           (!enrollmentDetails.zsmCredentialID && !enrollmentDetails.hasLocalPasskey)) {                                // ZSM: N | PKP: N | Remote PKP: N  - Dual enrollment for both ZSM and PKP...
-                    pkpEnrollmentResult = await this.webauthnPasskeyPlusCreate(enrollmentDetails, userVerified);                        // ...so we attempt Passkeys+ enrollment. Failure mode behavior is dictated by userVerified
-
-                } else if (enrollmentDetails.zsmCredentialID && !enrollmentDetails.hasLocalPasskey) {                                   // ZSM: Y | PKP: N | Remote PKP: N  - User has ZSM only...
-                    pkpEnrollmentResult = await this.webauthnBindPasskeyToZSM(enrollmentDetails, userVerified);                         // ...so we attempt to add Passkeys+ to existing ZSM credential. Failure mode behavior is dictated by userVerified
-
-                } else if (!enrollmentDetails.zsmCredentialID && enrollmentDetails.pkpCredential) {                                     // ZSM: N | PKP: Y | Remote PKP: Y - User ONLY has a (remote) passkey (which the checkAllEnrollments bootstrapped down to local)...
-                    pkpEnrollmentResult = await this.webauthnBindZSMToPasskey(enrollmentDetails, userVerified);                         // ...so we attempt to add ZSM credential to existing Passkeys+ credential. Failure mode behavior is dictated by userVerified
-                }
-                return (pkpEnrollmentResult === undefined)
-                       ? new Error(`[FIDO2Client] :: webauthnCreate :: 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 userVerified is "required", return an error to fail the entire enrollment operation...
-                    return new Error(`[FIDO2Client] :: webauthnCreate :: The passkey portion of the Passkeys+ enrollment failed for user ${userIdentifier} with error: ${pkpError.message || pkpError}. Since userVerified is set to "${userVerified}", the entire enrollment process has failed. You may: retry, downgrade the userVerified 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. userVerified === "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(`[FIDO2Client] :: webauthnCreate :: User ${userIdentifier} is already enrolled with a ZSM credential. To authenticate it, call the webauthnGet 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(`[FIDO2Client] :: webauthnCreate :: 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            webauthnGet
-     * @description     Retrieves the ZSM credential for the specified user
-     * @param           {string}                    userIdentifier      The identifier for the user
-     * @param           {string}                    userVerified        The level of user verification required for authentication (true/"preferred", false/"prevented", "required", "discouraged")
-     * @returns         {Promise<Object>}                               The ZSM credential for the user
-     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
-     * @throws          {Error}                                         If an error occurs during credential retrieval
-     * @memberOf        FIDO2ClientBase
-     */
-    async webauthnGet (userIdentifier, userVerified="prevented") {                                                          // [J] This method has been merged with the PKP Plugin's __webauthnGet method
-        ({ userIdentifier, userVerified } = this.typeChecks('webauthnGet', userIdentifier, userVerified, 'zsm'));
-
-
-        const attemptPasskeyPlusAuth = /^(preferred|required)$/.test(userVerified);                                                   // [J] Does the userVerified value indicate that Passkeys+ authentication should be attempted alongside ZSM authentication?
-        const continueOnPasskeyFailure = (userVerified === '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(`[FIDO2Client] :: webauthnGet :: User ${userIdentifier} must be enrolled with a ZSM credential before authenticating. Please enroll the user first.`);
-            } else if (!enrollmentDetails.passkeySupported) {
-
-                return new Error(`[FIDO2Client] :: webauthnGet :: User ${userIdentifier} is not eligible for Passkeys+ authentication; their device does not support passkey authentication. To authenticate, call the webauthnGet method with userVerified set to "preferred", "discouraged", or "prevented"/"zsm". To enroll with Passkeys+, call webauthnCreate with userVerified set to "preferred" or "required" on a Passkeys+-compatible device.`);
-            } else if(!enrollmentDetails.hasLocalPasskey) {
-
-                return new Error(`[FIDO2Client] :: webauthnGet :: User ${userIdentifier} must be enrolled with both ZSM and Passkeys+ credentials to authenticate using Passkeys+ (userVerified set to a non-prevented value).`);
-            } else if(attemptPasskeyPlusAuth) {
-
-                try {
-                    pkpAuthResult = await this.webauthnPasskeyPlusGet(enrollmentDetails, userVerified);
-
-                } catch (pkpError) {
-                    if (!continueOnPasskeyFailure) return new Error(`[FIDO2Client] :: webauthnGet :: The passkey portion of the Passkeys+ authentication failed for user ${userIdentifier} with error: ${pkpError.message || pkpError}. Since userVerified is set to "${userVerified}", the entire authentication process has failed. You may: retry or downgrade the userVerified mandate to "preferred" or "discouraged" to allow for ZSM-only authentication.`);
-                }
-                return (pkpAuthResult === undefined)
-                       ? new Error(`[FIDO2Client] :: webauthnGet :: Unexpected PKP flow: PKP authentication attempted but no result was returned for user ${userIdentifier}.`)
-                       : pkpAuthResult;
-            }
-        }
-
-        // The code below handles ZSM-only authentications, as well as providing the "fallback-to-ZSM-only" behavior for acceptable Passkeys+ failures (e.g. userVerified === "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(`[FIDO2Client] :: webauthnGet :: ${userIdentifier} is not enrolled. To authenticate the user, please enroll them first by calling the webauthnCreate method.`);
-
-        const authCredential = await this.zsmAPI.webauthnPartialGet(userIdentifier);
-        return authCredential?.credential??authCredential;
-    }
-
-    //! PASSKEYS PLUS FIDO2 CLIENT METHODS ==============================================================================================================================
-    // [J] These were migrated from PKP Plugin with minimal adjustments to fit into the FIDO2ClientBase class structure and flow
-
-    /**
-     * @name            webauthnPasskeyPlusCreate
-     * @description     Creates a Passkeys+ credential for the user, then creates a ZSM credential
-     * @param           {string}                userIdentifier      The identifier for the user
-     * @param           {string}                userVerified        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+ creation
-     * @memberOf        FIDO2ClientBase
-     */
-    async webauthnPasskeyPlusCreate (userIdentifier, userVerified="preferred") {
-        ({ userIdentifier, userVerified } = this.typeChecks('webauthnPasskeyPlusCreate', userIdentifier, userVerified, 're-enroll,reenroll'));     // [J] Replaced manual check with typeChecks
-
-        const pkpCreateResult = await this.zsmAPI.pkpCreate(userIdentifier, userVerified);
-
-        return pkpCreateResult;
-    }
-
-    /**
-     * @name            webauthnPasskeyPlusGet
-     * @description     Authenticates a ZSM credential on the device for the specified user
-     * @param           {string}                userIdentifier      The identifier for the user
-     * @param           {string}                userVerified        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        FIDO2ClientBase
-     */
-    async webauthnPasskeyPlusGet (userIdentifier, userVerified="preferred") {
-
-        let enrollmentDetails = null;
-        ({ userIdentifier, userVerified, enrollmentDetails } = this.typeChecks('webauthnPasskeyPlusGet', userIdentifier, userVerified, 're-enroll,reenroll'));
-        if(!enrollmentDetails) enrollmentDetails = await this.checkAllEnrollments(userIdentifier, true);
-
-        const pkpAuthResult     = await this.zsmAPI.pkpAuthenticate(enrollmentDetails, userVerified, !enrollmentDetails.zsmCredentialID);  // [J] Field name updated to match cleanFinalData
-        return pkpAuthResult;
-    }
-
-    /**
-     * @name            webauthnBindZSMToPasskey
-     * @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.
-     * @returns         {Promise<Object>}                           Completed ZSM + Passkeys+ authentication result.
-     * @throws          {Error}                                     If no Passkeys+ credentials are found for the user on another device.
-     * @memberOf        FIDO2ClientBase
-     */
-    async webauthnBindZSMToPasskey (userIdentifier, userVerified) {
-        ({ userIdentifier } = this.typeChecks('webauthnBindZSMToPasskey', userIdentifier));
-
-        const passkeyPreauth = await this.webauthnPasskeyPlusGet(userIdentifier);
-        return passkeyPreauth;
-    }
-
-    /**
-     * @name            webauthnBindPasskeyToZSM
-     * @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}                userVerified        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        FIDO2ClientBase
-     */
-    async webauthnBindPasskeyToZSM (userIdentifier, userVerified="preferred") {
-        let enrollmentDetails = null;
-        ({ userIdentifier, userVerified, enrollmentDetails } = this.typeChecks('webauthnBindPasskeyToZSM', userIdentifier, userVerified, 're-enroll,reenroll'));      // [J] Replaced manual check with typeChecks
-
-        const pkpAddPasskeyResult = await this.zsmAPI.pkpAddPasskeyCredential((enrollmentDetails || userIdentifier), userVerified);
-
-        return pkpAddPasskeyResult;
-    }
-}
-
-export default FIDO2ClientBase;
+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("FIDO2ClientBase"),this.config=r;const s=t.classes("WEBAUTHNCLIENT");this.zsmAPI=new s(r),this.checkEnrollment=this.checkEnrollment.bind(this),this.checkIdentity=this.checkIdentity.bind(this),this.webauthnRetrieve=this.webauthnRetrieve.bind(this),this.webauthnDelete=this.webauthnDelete.bind(this),this.resetDevice=this.resetDevice.bind(this),this.webauthnCreate=this.webauthnCreate.bind(this),this.webauthnGet=this.webauthnGet.bind(this),this.checkAllEnrollments=this.checkAllEnrollments.bind(this),this.webauthnPasskeyPlusCreate=this.webauthnPasskeyPlusCreate.bind(this),this.webauthnPasskeyPlusGet=this.webauthnPasskeyPlusGet.bind(this),e.update("FIDO2ClientBase","READY")}get userIdentifier(){return this.zsmAPI.userIdentifier}get credentialID(){return this.zsmAPI.credentialID}typeChecks(e,t,s=null,n=""){if(!t)throw new TypeError(`[FIDO2Client] :: ${e} :: A userIdentifier String is required! Received: ${t} (type: ${typeof t}).`);let i;if("object"==typeof t&&(i={...t},t=t.userIdentifier),null!=s){if("boolean"==typeof s)s=!0===s?"preferred":"prevented";else{if("string"!=typeof s)throw new TypeError(`[FIDO2Client] :: ${e} :: userVerified must be a boolean or string. Received type: ${typeof s}.`);s=s.toLowerCase()}const t=["preferred","required","discouraged","prevented",...n.split(/, ?/g).filter(Boolean)];if(!new RegExp(`^(${t.join("|")})$`).test(s))throw new TypeError(`[FIDO2Client] :: ${e} :: userVerified must be one of the following Strings: "${t.join('", "')}"). Received: ${s}.`)}let a={userIdentifier:t=r(t),userVerified:s};return i&&(a={enrollmentDetails:i,...a}),a}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)}webauthnRetrieve(e){return this.zsmAPI.webauthnRetrieve(r(e))}webauthnDelete(e){return this.zsmAPI.unbindFromDevice(r(e))}async resetDevice(){this.zsmAPI.webauthnReset()}async webauthnCreate(e,t="prevented"){({userIdentifier:e,userVerified:t}=this.typeChecks("webauthnCreate",e,t,"zsm,re-enroll,reenroll"));const r=/^re-?enroll$/.test(t),s="preferred"===t;let n,i,a;if(r||/^(preferred|required)$/.test(t)){i=await this.checkAllEnrollments(e);try{if(i.passkeySupported)if(r){if(!i.zsmCredentialID&&!i.hasLocalPasskey)return new Error(`[FIDO2Client] :: webauthnCreate :: Cannot RE-enroll user's passkey; user ${e} is not currently enrolled with either ZSM or Passkeys+ credentials. To enroll the user, call webauthnCreate with a userVerified value of "preferred", "required", or "discouraged".`);n=await this.webauthnPasskeyPlusCreate(i,"required")}else{if(i.zsmCredentialID&&i.hasLocalPasskey)return new Error(`[FIDO2Client] :: webauthnCreate :: User ${e} is already enrolled with both ZSM and Passkeys+ credentials. To authenticate one or both credential, call the webauthnGet method.`);i instanceof Error||!1===i||!i.zsmCredentialID&&!i.hasLocalPasskey?n=await this.webauthnPasskeyPlusCreate(i,t):i.zsmCredentialID&&!i.hasLocalPasskey?n=await this.webauthnBindPasskeyToZSM(i,t):!i.zsmCredentialID&&i.pkpCredential&&(n=await this.webauthnBindZSMToPasskey(i,t))}else{if(!s)return new Error(`[FIDO2Client] :: webauthnCreate :: Passkeys+ is required for enrollment (userVerified 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(`[FIDO2Client] :: webauthnCreate :: 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===n?new Error(`[FIDO2Client] :: webauthnCreate :: Unexpected PKP flow: PKP enrollment attempted but no result was returned for user ${e}.`):n}catch(r){if(console.error("ENROLL FLOW :: PASSKEY OPERATION FAILED ::",r),!s)return new Error(`[FIDO2Client] :: webauthnCreate :: The passkey portion of the Passkeys+ enrollment failed for user ${e} with error: ${r.message||r}. Since userVerified is set to "${t}", the entire enrollment process has failed. You may: retry, downgrade the userVerified mandate to "preferred" or "discouraged" to allow for ZSM-only enrollment.`)}}if(a=i?.zsmCredentialID?i?.zsmCredentialID:await this.checkEnrollment(e),"string"==typeof a)return new Error(`[FIDO2Client] :: webauthnCreate :: User ${e} is already enrolled with a ZSM credential. To authenticate it, call the webauthnGet method.`);await this.zsmAPI.checkIdentity(e,!0);const l=await this.zsmAPI.webauthnCreate(e);return l instanceof Error?new Error(`[FIDO2Client] :: webauthnCreate :: Unable to enroll ${e}!\nDetails:\n${l?.message||l}`,{cause:l?.stack}):l}async webauthnGet(e,t="prevented"){({userIdentifier:e,userVerified:t}=this.typeChecks("webauthnGet",e,t,"zsm"));const r=/^(preferred|required)$/.test(t),s="preferred"===t;let n,i,a;if(r){if(i=await this.checkAllEnrollments(e),!i.zsmCredentialID)return new Error(`[FIDO2Client] :: webauthnGet :: User ${e} must be enrolled with a ZSM credential before authenticating. Please enroll the user first.`);if(!i.passkeySupported)return new Error(`[FIDO2Client] :: webauthnGet :: User ${e} is not eligible for Passkeys+ authentication; their device does not support passkey authentication. To authenticate, call the webauthnGet method with userVerified set to "preferred", "discouraged", or "prevented"/"zsm". To enroll with Passkeys+, call webauthnCreate with userVerified set to "preferred" or "required" on a Passkeys+-compatible device.`);if(!i.hasLocalPasskey)return new Error(`[FIDO2Client] :: webauthnGet :: User ${e} must be enrolled with both ZSM and Passkeys+ credentials to authenticate using Passkeys+ (userVerified set to a non-prevented value).`);if(r){try{n=await this.webauthnPasskeyPlusGet(i,t)}catch(r){if(!s)return new Error(`[FIDO2Client] :: webauthnGet :: The passkey portion of the Passkeys+ authentication failed for user ${e} with error: ${r.message||r}. Since userVerified is set to "${t}", the entire authentication process has failed. You may: retry or downgrade the userVerified mandate to "preferred" or "discouraged" to allow for ZSM-only authentication.`)}return void 0===n?new Error(`[FIDO2Client] :: webauthnGet :: Unexpected PKP flow: PKP authentication attempted but no result was returned for user ${e}.`):n}}a=i?.zsmCredentialID?i?.zsmCredentialID:await this.checkEnrollment(e);if(!1===("string"==typeof a))return new Error(`[FIDO2Client] :: webauthnGet :: ${e} is not enrolled. To authenticate the user, please enroll them first by calling the webauthnCreate method.`);const l=await this.zsmAPI.webauthnPartialGet(e);return l?.credential??l}
+//! PASSKEYS PLUS FIDO2 CLIENT METHODS ==============================================================================================================================
+async webauthnPasskeyPlusCreate(e,t="preferred"){({userIdentifier:e,userVerified:t}=this.typeChecks("webauthnPasskeyPlusCreate",e,t,"re-enroll,reenroll"));return await this.zsmAPI.pkpCreate(e,t)}async webauthnPasskeyPlusGet(e,t="preferred"){let r=null;({userIdentifier:e,userVerified:t,enrollmentDetails:r}=this.typeChecks("webauthnPasskeyPlusGet",e,t,"re-enroll,reenroll")),r||(r=await this.checkAllEnrollments(e,!0));return await this.zsmAPI.pkpAuthenticate(r,t,!r.zsmCredentialID)}async webauthnBindZSMToPasskey(e,t){({userIdentifier:e}=this.typeChecks("webauthnBindZSMToPasskey",e));return await this.webauthnPasskeyPlusGet(e)}async webauthnBindPasskeyToZSM(e,t="preferred"){let r=null;({userIdentifier:e,userVerified:t,enrollmentDetails:r}=this.typeChecks("webauthnBindPasskeyToZSM",e,t,"re-enroll,reenroll"));return await this.zsmAPI.pkpAddPasskeyCredential(r||e,t)}}

package/GlobalScoping.js

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

package/IdentityIndexing.js

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

package/PKPUtils.js

@@ -1,61 +1 @@
-/**
-    @name           decodeAttestationObject
-    @description    Decodes a CBOR-encoded attestation object buffer into a JavaScript object (CBOR map of 3 entries (0xA3)) with properties 'fmt', 'attStmt', and 'authData'.
-    @param          {ArrayBuffer}       buffer      The CBOR-encoded attestation object.
-    @returns        {Object}                        The decoded attestation object with properties 'fmt', 'attStmt', and 'authData'.
-    @throws         {Error}                         If the first byte does not indicate a CBOR map of 3 entries.
-    @throws         {Error}                         If the major type of a value is unsupported.
-    @throws         {Error}                         If the input buffer is not a valid CBOR-encoded attestation object.
-*/
-function decodeAttestationObject(buffer) {
-    try {
-        if (!buffer)                                                                                                        // IF the buffer argument is missing...
-            throw new TypeError("Invalid input");                                                                           //   ...throw an error
-
-        if (buffer instanceof Uint8Array)                                                                                   // IF the buffer argument is a Uint8Array...
-            buffer = buffer.buffer;                                                                                         //   ...convert it to an ArrayBuffer
-        if (!(buffer instanceof ArrayBuffer))                                                                               // IF the buffer argument is (STILL) not an ArrayBuffer...
-            throw new TypeError("Invalid input");                                                                           //   ...throw an error
-
-        if (!buffer || !(buffer instanceof ArrayBuffer))                                                                    // IF the buffer argument is missing or not an ArrayBuffer...
-            throw new TypeError("Invalid input");                                                                           //   ...throw an error
-        const view = new DataView(buffer);                                                                                  // Create a DataView to read the buffer argument (CBOR is a binary format)
-        const attObj = {};                                                                                                  // Create an object to hold the decoded attestation object
-        let offset = 0;                                                                                                     // Create an offset counter to track our position in the buffer
-
-        // Expect a CBOR map of 3 entries (0xA3)
-        const type = view.getUint8(offset++);                                                                               // Read the first byte to determine the major type
-        if (type !== 0xA3) throw new Error("Unexpected format");                                                            // Since we expect a map with 3 key-value pairs, throw an error if not found
-
-        for (let i = 0; i < 3; i++) {                                                                                       // Iterate over the 3 key-value pairs...
-            const keyLen = view.getUint8(offset++) - 0x60;                                                                  // Read the length of the key (CBOR short string)
-
-            const key = new TextDecoder()                                                                                   // Isolate out the key by initializing a TextDecoder...
-                            .decode(new Uint8Array(buffer, offset, keyLen));                                                // ...and decoding the buffered CBOR short string into it
-
-            offset += keyLen;                                                                                               // Move offset past the key by the length of the key
-
-            const majorType = view.getUint8(offset);                                                                        // Read the major type of the value
-
-            offset++;                                                                                                       // Move past the major type byte
-
-            if (majorType === 0x58) {                                                                                       // IF the major type's value is a byte string with length in next byte...
-                const len = view.getUint8(offset++);                                                                        //   ...read the length of the byte string...
-                attObj[key] = new Uint8Array(buffer, offset, len);                                                          //   ...extract the byte string...
-                offset += len;                                                                                              //   ...and increment offset by length.
-            } else if (majorType >= 0x60 && majorType < 0x78) {                                                             // OTHERWISE, if major type's value is a short string (for 'fmt')
-                const len = majorType - 0x60;                                                                               //   ...determine length from major type...
-                attObj[key] = new TextDecoder()                                                                             //   ...and initialize a TextDecoder...
-                                .decode(new Uint8Array(buffer, offset, len));                                               //   ...decoding the buffered CBOR short string into it
-                offset += len;                                                                                              //   ...finally, increment offset by length
-            } else if (majorType === 0xA0) {                                                                                // OTHERWISE, if major type's value is an empty map
-                attObj[key] = {};                                                                                           //   ...and assign an empty object
-            } else throw new Error("Unsupported type");                                                                     // OTHERWISE, throw an error
-        }
-        return attObj;                                                                                                      // return the decoded attestation object
-    } catch (e) {
-        throw new Error("[Utils] :: decodeAttestationObject :: Failed to decode attestation object: " + e.message);
-    }
-}
-
-export { decodeAttestationObject };
+function e(e){try{if(!e)throw new TypeError("Invalid input");if(e instanceof Uint8Array&&(e=e.buffer),!(e instanceof ArrayBuffer))throw new TypeError("Invalid input");if(!(e&&e instanceof ArrayBuffer))throw new TypeError("Invalid input");const t=new DataView(e),r={};let n=0;if(163!==t.getUint8(n++))throw new Error("Unexpected format");for(let o=0;o<3;o++){const o=t.getUint8(n++)-96,i=(new TextDecoder).decode(new Uint8Array(e,n,o));n+=o;const a=t.getUint8(n);if(n++,88===a){const o=t.getUint8(n++);r[i]=new Uint8Array(e,n,o),n+=o}else if(a>=96&&a<120){const t=a-96;r[i]=(new TextDecoder).decode(new Uint8Array(e,n,t)),n+=t}else{if(160!==a)throw new Error("Unsupported type");r[i]={}}}return r}catch(e){throw new Error("[Utils] :: decodeAttestationObject :: Failed to decode attestation object: "+e.message)}}export{e as decodeAttestationObject};