@ideem/zsm-client-sdk 2.4.0 → 2.5.0

package/RelyingParty.js

@@ -0,0 +1,15 @@
+import eventCoordinator from './EventCoordinator.js';
+import RelyingPartyBase from './RelyingPartyBase.js';
+
+eventCoordinator.update('RelyingParty');
+
+//## BEGIN RelyingParty ===================================================================================================================================
+class RelyingParty extends RelyingPartyBase {
+    constructor(host, apiKey, applicationID, appEnvironment, usePasskeys) {
+        super(host, apiKey, applicationID, appEnvironment, (usePasskeys != 'undefined' && usePasskeys != undefined && usePasskeys))
+        eventCoordinator.update('RelyingParty', 'READY');
+    }
+}
+//## END RelyingParty =====================================================================================================================================
+
+export default RelyingParty;

package/RelyingPartyBase.js

@@ -0,0 +1,197 @@
+import eventCoordinator from './EventCoordinator.js';
+import GLOBAL           from './GlobalScoping.js';
+import {uid2iid}        from './IdentityIndexing.js';
+
+eventCoordinator.update('RelyingPartyBase');
+
+function tracePrimer (obj=false) {
+    const traceBase = [[new Date().toISOString(), "TRACEPRIMER"]]
+    return (obj) ? {"trace": traceBase} : traceBase;
+}
+
+//## BEGIN RelyingPartyBase ===================================================================================================================================
+class RelyingPartyBase {
+    /**
+    * Constructs a RelyingParty object.
+    * @param {string} host - The URL of the relying party server.
+    * @param {string} apiKey - The API key for authentication.
+    * @param {string} applicationID - The ID of the application.
+    */
+    constructor(host, apiKey, applicationID, appEnvironment, useOrigin) {
+        this.host                      = host;
+        this.apiKey                    = apiKey;
+        this.applicationId             = applicationID;
+        this.appEnvironment            = appEnvironment || null;
+        this.customerDefinedIdentifier = undefined;
+        this.publicKey                 = undefined;
+        this.identityID                = undefined;
+        this.credentialID              = undefined;
+        this.traceId                   = undefined;
+        this.xhrHeaders                = { 'Content-Type' : 'application/json' };
+        this.addlRelyingPartyBodyProps = useOrigin ? {use_origin: "true"} : {};
+        eventCoordinator.update('RelyingPartyBase', 'READY');
+    }
+
+    get userIdentifier()             { return this.customerDefinedIdentifier; }
+    set userIdentifier(v)            { return this.customerDefinedIdentifier = v; }
+
+    /**
+     * @name            makePostRequest
+     * @description     Performs an HTTP POST request
+     * @param           {string}          url       The URL to send the request to.
+     * @param           {Object}          body      The request body data.
+     * @param           {Object}          headers   Additional headers for the request.
+     * @param           {string}          method    The HTTP method to use (default is 'POST').
+     * @returns         {Promise<Object>}  Resolves with the response data.
+     */
+    makePostRequest (url, body={}, headers={}, method='POST') {
+        url  = `${this.host.endsWith('/') ? this.host.slice(0,-1) : this.host}/${url.startsWith('/') ? url.slice(1) : url}`;
+        body = ((typeof body === 'object') ? body : {});
+        if(this.appEnvironment) body = Object.assign(body, {environment: this.appEnvironment});
+        body = Object.assign({ customer_defined_identifier : this.customerDefinedIdentifier,  application_id : this.applicationId }, body, this.addlRelyingPartyBodyProps, tracePrimer(true));
+        let fetchObj = {
+            method,
+            headers : Object.assign(this.xhrHeaders, ((!headers?.Authorization) ? {'Authorization': `Bearer ${this.apiKey}`} : {}), headers),
+            body    : JSON.stringify(body)
+        };
+        return  fetch(url, fetchObj)
+                .then(response => response.ok
+                                ? response.json()
+                                : response.json().then(errData => { throw new Error(`[RelyingParty] :: makePostRequest :: Request failed: ${response.statusText}, ${JSON.stringify(errData)}`) })
+                )
+
+                .then(response => {
+                    GLOBAL.dispatchEvent(new CustomEvent("AuthResponse", {bubbles: true, cancelable: false, detail: response }));
+                    return response;
+                });
+    }
+
+    /**
+     * @name            clearEnrollmentCredentials
+     * @description     Clears the enrollment credentials.
+     * @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.  
+     */
+    clearLoginCredentials () {};
+    /**
+     * @name            resetAll
+     * @description     Resets all credentials.
+     * @returns         {Promise<Void>}                   
+     */
+    resetAll () { return (this.clearLoginCredentials(), this.clearEnrollmentCredentials()); }
+
+    /**
+     * @name            registrationStart
+     * @description     Sends a login request to the server.
+     * @returns         {Promise<Object>}                           Resolves with publicKey object used in the subsequent Crypto Server API call.
+     */
+    registrationStart () {
+        return this.makePostRequest("api/webauthn/registration/start")
+                .then(data   => {
+                    if(data.identity_id){
+                        GLOBAL.mpcConfig.consumer_id = data.identity_id;
+                        uid2iid(this.userIdentifier, data.identity_id);
+                    }
+                    return (this.publicKey = data.ccr.publicKey)
+                })
+                .then(result => result)
+                .catch(error => Promise.reject((error instanceof Error) ? error : new Error(error)));
+    }
+    /**
+     * @name            registrationFinish
+     * @description     Completes WebAuthn registration by sending the credential to the server.
+     * @param           {Object}                credential          The credential information to finalize registration.
+     * @returns         {Promise<Object>}                           Resolves with the registered credential.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+    registrationFinish (credential) {
+        return  this.makePostRequest("api/webauthn/registration/finish", { credential })
+                .then(()         => (this.credentialID = credential.rawId, credential))
+                .then(credential => credential)
+                .catch(error     => (this.clearEnrollmentCredentials(), Promise.reject((error instanceof Error) ? error : new Error(error))))
+
+    }
+
+    /**
+     * @name            authenticationStart
+     * @description     Starts the authentication process by sending a request to the server.
+     * @param           {String}                 credential_id      The ID of the credential to use for authentication.
+     * @returns         {Promise<Object>}                           Resolves with the authentication challenge.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+    authenticationStart (credential_id=this.credentialID) {
+        return  (credential_id != null)
+                ? this.makePostRequest( "api/webauthn/authentication/start", { credential_id })
+                        .then(result => result)
+                : (Promise.reject(new Error("[RelyingParty] :: authenticationStart :: No user ID or credential ID provided")))
+    }
+
+    /**
+     * @name            authenticationFinish
+     * @description     Completes the authentication process by sending the credential to the server.
+     * @param           {Object}                 credential         The credential information to finalize authentication.
+     * @returns         {Promise<Object>}                           Resolves with the authentication result.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+    authenticationFinish (credential) {
+        return  this.makePostRequest("api/webauthn/authentication/finish", { credential })
+                .then(result => result)
+                .catch(error => Promise.reject((error instanceof Error) ? error : new Error(error)));
+    }
+
+    /**
+     * @name            createIdentityThenRegistrationStart
+     * @description     UMFA-OPTIMIZED FLOW: Creates a server-side Identity and then starts the WebAuthn Registration challenge automatically.
+     * @returns         {Promise<Object>}                           Resolves with an object containing the publicKey and identity_id.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+    createIdentityThenRegistrationStart() {
+        return  this.makePostRequest("api/webauthn/registration/create-identity-then-start")
+                .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((error instanceof Error) ? error : new Error(error)));
+    }
+
+    /**
+     * @name            registrationFinishAuthenticationStart
+     * @description     UMFA-OPTIMIZED FLOW: Completes WebAuthn registration by sending the credential to the server.
+     * @param           {Object}                credential          The credential information to finalize registration.
+     * @returns         {Promise<Object>}                           Resolves with the registered credential.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+    registrationFinishAuthenticationStart (credential) {
+        return  this.makePostRequest("api/webauthn/registration/finish-then-authentication-start", { credential })
+                .then(result     => (this.credentialID = credential.rawId, result))
+                .then(credential => credential)
+                .catch(error     => (this.clearEnrollmentCredentials(), Promise.reject((error instanceof Error) ? error : new Error(error))));
+    }
+
+    /**
+     * @name            checkServerSideIdentity
+     * @description     Checks if an identity exists on the server and creates one if it doesn't.
+     * @param           {boolean}               createNewIdentity   Whether to create a new identity if one doesn't exist.
+     * @returns         {Promise<Object>}                           Resolves with the server response.
+     * @throws          {Error}                                     Throws an error if the request fails.
+     */
+    checkServerSideIdentity (createNewIdentity) {
+        createNewIdentity = createNewIdentity ? { create_new_identity: "true" } : {};
+        return  this.makePostRequest("api/umfa/check-identity", createNewIdentity)
+                .then(result => result)
+                .catch(error => Promise.reject(error));
+    }
+}
+//## END RelyingPartyBase =====================================================================================================================================
+
+export default RelyingPartyBase;

package/UMFAClient.js

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

package/UMFAClientBase.js

@@ -0,0 +1,125 @@
+import eventCoordinator from './EventCoordinator.js';
+import {zsmPluginManager}   from './PluginManager.js';
+
+class UMFAClientBase  {
+    /**
+     * Base class for UMFAClient, providing methods for user enrollment and authentication.
+     * @constructor
+     * @param {Object} config - The configuration for ZSM initialization (ref: ./zsm_app_config.json)
+    */
+   constructor(config) {
+        if(eventCoordinator.done) 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);
+        eventCoordinator.update('UMFAClientBase', 'READY');
+    }
+
+    get userIdentifier()    { return this.zsmAPI.userIdentifier; }
+    get credentialID()      { return this.zsmAPI.credentialID;   }
+
+    /**
+     * @name            checkEnrollment
+     * @description     Checks if a ZSM credential is enrolled on the device for the specified user
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<Object>|boolean}                       Resolves with the enrollment details or false if not enrolled, or an error if checking fails
+     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
+     * @throws          {Error}                                         If an error occurs while checking enrollment
+     * @memberOf        UMFAClientBase
+     */
+    async checkEnrollment(userIdentifier) {
+        try {
+            if(userIdentifier == null 
+                || userIdentifier === '')     throw new Error(`[UMFAClient] :: checkEnrollment :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+            return await this.zsmAPI.webauthnRetrieve(userIdentifier);
+        } catch(e) {
+            return new Error(e.message || e || '[UMFAClient] :: checkEnrollment :: An error occurred while attempting to check enrollment.');
+        }
+    }
+
+    /**
+     * @name            enroll
+     * @description     Enrolls a user by creating a ZSM credential on the device
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @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) {
+        try {
+            if(userIdentifier == null 
+                || userIdentifier === '')     throw new Error(`[UMFAClient] :: enroll :: A userIdentifier String is required! Received: ${userIdentifier}.`);
+            
+            const userIsEnrolled              = await this.checkEnrollment(userIdentifier);
+            if(userIsEnrolled !== false)      return false;
+
+            const createResult                = await this.zsmAPI.webauthnCreateThenPartialGet(userIdentifier);
+            if(createResult instanceof Error) throw(`[UMFAClient] :: enroll :: Unable to associate ${userIdentifier}'s identity with device profile.\nDetails:\n${createResult}`);
+            if(!createResult?.credential)     throw(`[UMFAClient] :: enroll :: Unable to acquire authentication token for ${userIdentifier}!`);
+            return createResult.credential;
+        }catch(e) {
+            return new Error(e.message || e || '[UMFAClient] :: enroll :: An error occurred during enrollment.');
+        }
+    }
+
+    /**
+     * @name            authenticate
+     * @description     Authenticates a user by retrieving their ZSM credential
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @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;
+        }catch(e) {
+            return new Error(e.message || e || '[UMFAClient] :: authenticate :: An error occurred during authentication.');
+        }
+    }
+    
+    /**
+     * @name            unenroll
+     * @description     Unenrolls a user by removing their ZSM credential from the device
+     * @param           {string}                    userIdentifier      The identifier for the user
+     * @returns         {Promise<boolean>}                              Resolves with true if unenrollment was successful, false if the user was not enrolled, or an error if unenrollment fails
+     * @throws          {Error}                                         If the userIdentifier is not provided or is empty
+     * @throws          {Error}                                         If an error occurs during unenrollment
+     * @memberOf        UMFAClientBase
+     */
+    async unenroll(userIdentifier) {
+        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.');
+        }
+    }
+
+    /**
+     * @name            resetDevice
+     * @description     Pass-through method to call WebAuthnClient's webauthnReset
+     * @returns         {Promise<void>}                               No results are returned
+     * @memberOf        UMFAClientBase, WebAuthnClient
+     */
+    async resetDevice() { this.zsmAPI.webauthnReset(); }
+}
+
+export default UMFAClientBase;

package/Utils.js

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