@ideem/zsm-client-sdk
Version:
ZSM makes 2FA easy and invisible for everyone, all the time, using advanced cryptography like MPC to establish cryptographic proof of the origin of any transaction or login attempt, while eliminating opportunities for social engineering. ZSM has no relian
338 lines (287 loc) • 28.9 kB
JavaScript
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;