Merge feature/ENG-1111/mfa-lambda (#211)

* first lambda type

* reduce client blast radius (#204)

* MFA lambda configuration (#205)

* ENG-3487: Tenant-scoped IdPs (#202)

* update domain for tenantId on IdPs (#199)
* add tenantId to IdP lookup by managed domain response (#201)

* Merge wied03/ENG-3602/mfa-lambda-invocation (#206)

* propagate client changes

* client code update from Javadoc

* Merge wied03/ENG-3603/mfa-retrieve-status-post (#207)

* propagate client changes

* client code update from Javadoc

* client generation/new method

* better method name

* missing client stuff

* redo client again

* Merge wied03/ENG-3608/mfa-change-password (#210)

* add IP address client overload

* forgot to update method names

* naming advice

* mfa lambda

* Change function name and parameters

* PR feedback - lambda classses - new package and names

* keep value as mfaTrust within lambda

* pass raw JWT all the way in

* Lambda signature - registration out of context, action and app in

* Change context.encodedJWT to context.accessToken

* rename token to accessToken on status API

---------

Co-authored-by: Jaret Hendrickson <jaret.hendrickson+github@fusionauth.io>
Co-authored-by: Spencer Witt <3409780+spwitt@users.noreply.github.com>
Co-authored-by: Jaret Hendrickson <jaret.hendrickson@fusionauth.io>

Author: 3 people

src/FusionAuthClient.ts

@@ -232,6 +232,26 @@ export class FusionAuthClient {
         .go();
   }
 
+  /**
+   * Check to see if the user must obtain a Trust Token Id in order to complete a change password request.
+   * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
+   * your password, you must obtain a Trust Token by completing a Two-Factor Step-Up authentication.
+   * 
+   * An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API.
+   *
+   * @param {string} changePasswordId The change password Id used to find the user. This value is generated by FusionAuth once the change password workflow has been initiated.
+   * @param {string} ipAddress (Optional) IP address of the user changing their password. This is used for MFA risk assessment.
+   * @returns {Promise<ClientResponse<void>>}
+   */
+  checkChangePasswordUsingIdAndIPAddress(changePasswordId: string, ipAddress: string): Promise<ClientResponse<void>> {
+    return this.startAnonymous<void, Errors>()
+        .withUri('/api/user/change-password')
+        .withUriSegment(changePasswordId)
+        .withParameter('ipAddress', ipAddress)
+        .withMethod("GET")
+        .go();
+  }
+
   /**
    * Check to see if the user must obtain a Trust Token Id in order to complete a change password request.
    * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
@@ -250,6 +270,26 @@ export class FusionAuthClient {
         .go();
   }
 
+  /**
+   * Check to see if the user must obtain a Trust Token Id in order to complete a change password request.
+   * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
+   * your password, you must obtain a Trust Token by completing a Two-Factor Step-Up authentication.
+   * 
+   * An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API.
+   *
+   * @param {string} encodedJWT The encoded JWT (access token).
+   * @param {string} ipAddress (Optional) IP address of the user changing their password. This is used for MFA risk assessment.
+   * @returns {Promise<ClientResponse<void>>}
+   */
+  checkChangePasswordUsingJWTAndIPAddress(encodedJWT: string, ipAddress: string): Promise<ClientResponse<void>> {
+    return this.startAnonymous<void, Errors>()
+        .withUri('/api/user/change-password')
+        .withAuthorization('Bearer ' + encodedJWT)
+        .withParameter('ipAddress', ipAddress)
+        .withMethod("GET")
+        .go();
+  }
+
   /**
    * Check to see if the user must obtain a Trust Request Id in order to complete a change password request.
    * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
@@ -268,6 +308,26 @@ export class FusionAuthClient {
         .go();
   }
 
+  /**
+   * Check to see if the user must obtain a Trust Request Id in order to complete a change password request.
+   * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
+   * your password, you must obtain a Trust Request Id by completing a Two-Factor Step-Up authentication.
+   * 
+   * An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API.
+   *
+   * @param {string} loginId The loginId (email or username) of the User that you intend to change the password for.
+   * @param {string} ipAddress (Optional) IP address of the user changing their password. This is used for MFA risk assessment.
+   * @returns {Promise<ClientResponse<void>>}
+   */
+  checkChangePasswordUsingLoginIdAndIPAddress(loginId: string, ipAddress: string): Promise<ClientResponse<void>> {
+    return this.start<void, Errors>()
+        .withUri('/api/user/change-password')
+        .withParameter('loginId', loginId)
+        .withParameter('ipAddress', ipAddress)
+        .withMethod("GET")
+        .go();
+  }
+
   /**
    * Check to see if the user must obtain a Trust Request Id in order to complete a change password request.
    * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
@@ -288,6 +348,28 @@ export class FusionAuthClient {
         .go();
   }
 
+  /**
+   * Check to see if the user must obtain a Trust Request Id in order to complete a change password request.
+   * When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change
+   * your password, you must obtain a Trust Request Id by completing a Two-Factor Step-Up authentication.
+   * 
+   * An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API.
+   *
+   * @param {string} loginId The loginId of the User that you intend to change the password for.
+   * @param {Array<String>} loginIdTypes The identity types that FusionAuth will compare the loginId to.
+   * @param {string} ipAddress (Optional) IP address of the user changing their password. This is used for MFA risk assessment.
+   * @returns {Promise<ClientResponse<void>>}
+   */
+  checkChangePasswordUsingLoginIdAndLoginIdTypesAndIPAddress(loginId: string, loginIdTypes: Array<String>, ipAddress: string): Promise<ClientResponse<void>> {
+    return this.start<void, Errors>()
+        .withUri('/api/user/change-password')
+        .withParameter('loginId', loginId)
+        .withParameter('loginIdTypes', loginIdTypes)
+        .withParameter('ipAddress', ipAddress)
+        .withMethod("GET")
+        .go();
+  }
+
   /**
    * Make a Client Credentials grant request to obtain an access token.
    *
@@ -3853,6 +3935,24 @@ export class FusionAuthClient {
         .go();
   }
 
+  /**
+   * Retrieve a user's two-factor status.
+   * 
+   * This can be used to see if a user will need to complete a two-factor challenge to complete a login,
+   * and optionally identify the state of the two-factor trust across various applications. This operation
+   * provides more payload options than retrieveTwoFactorStatus.
+   *
+   * @param {TwoFactorStatusRequest} request The request object that contains all the information used to check the status.
+   * @returns {Promise<ClientResponse<TwoFactorStatusResponse>>}
+   */
+  retrieveTwoFactorStatusWithRequest(request: TwoFactorStatusRequest): Promise<ClientResponse<TwoFactorStatusResponse>> {
+    return this.start<TwoFactorStatusResponse, Errors>()
+        .withUri('/api/two-factor/status')
+        .withJSONBody(request)
+        .withMethod("POST")
+        .go();
+  }
+
   /**
    * Retrieves the user for the given Id.
    *
@@ -5974,6 +6074,7 @@ export interface AuthenticationTokenConfiguration extends Enableable {
 export interface LambdaConfiguration {
   accessTokenPopulateId?: UUID;
   idTokenPopulateId?: UUID;
+  multiFactorRequirementId?: UUID;
   samlv2PopulateId?: UUID;
   selfServiceRegistrationValidationId?: UUID;
   userinfoPopulateId?: UUID;
@@ -6840,6 +6941,19 @@ export enum ContentStatus {
   REJECTED = "REJECTED"
 }
 
+/**
+ * Represents the inbound lambda parameter 'context' for MFA Required lambdas.
+ */
+export interface Context {
+  accessToken?: string;
+  action?: MultiFactorAction;
+  application?: Application;
+  authenticationThreats?: Array<AuthenticationThreats>;
+  eventInfo?: EventInfo;
+  mfaTrust?: Trust;
+  policies?: Policies;
+}
+
 /**
  * A number identifying a cryptographic algorithm. Values should be registered with the <a
  * href="https://www.iana.org/assignments/cose/cose.xhtml#algorithms">IANA COSE Algorithms registry</a>
@@ -9067,7 +9181,8 @@ export enum LambdaType {
   SCIMServerUserResponseConverter = "SCIMServerUserResponseConverter",
   SelfServiceRegistrationValidation = "SelfServiceRegistrationValidation",
   UserInfoPopulate = "UserInfoPopulate",
-  LoginValidation = "LoginValidation"
+  LoginValidation = "LoginValidation",
+  MFARequirement = "MFARequirement"
 }
 
 /**
@@ -9426,6 +9541,15 @@ export interface MonthlyActiveUserReportResponse {
   total?: number;
 }
 
+/**
+ * Communicate various actions/contexts in which multi-factor authentication can be used.
+ */
+export enum MultiFactorAction {
+  changePassword = "changePassword",
+  login = "login",
+  stepUp = "stepUp"
+}
+
 /**
  * @author Daniel DeGroff
  */
@@ -9871,6 +9995,15 @@ export interface PhoneUnverifiedOptions {
   behavior?: UnverifiedBehavior;
 }
 
+/**
+ * Represents the inbound lambda parameter 'policies' for MFA Required lambdas.
+ */
+export interface Policies {
+  applicationLoginPolicy?: MultiFactorLoginPolicy;
+  applicationMultiFactorTrustPolicy?: ApplicationMultiFactorTrustPolicy;
+  tenantLoginPolicy?: MultiFactorLoginPolicy;
+}
+
 /**
  * @author Michael Sleevi
  */
@@ -10101,6 +10234,7 @@ export interface ReactorStatus {
   expiration?: string;
   licenseAttributes?: Record<string, string>;
   licensed?: boolean;
+  multiFactorLambdas?: ReactorFeatureStatus;
   scimServer?: ReactorFeatureStatus;
   tenantManagerApplication?: ReactorFeatureStatus;
   threatDetection?: ReactorFeatureStatus;
@@ -10322,6 +10456,14 @@ export interface Requirable extends Enableable {
   required?: boolean;
 }
 
+/**
+ * Represents the inbound lambda parameter 'result' for MFA Required lambdas.
+ */
+export interface RequiredLambdaResult {
+  required?: boolean;
+  sendSuspiciousLoginEvent?: boolean;
+}
+
 /**
  * Interface describing the need for CORS configuration.
  *
@@ -10874,6 +11016,7 @@ export interface TenantFormConfiguration {
  */
 export interface TenantLambdaConfiguration {
   loginValidationId?: UUID;
+  multiFactorRequirementId?: UUID;
   scimEnterpriseUserRequestConverterId?: UUID;
   scimEnterpriseUserResponseConverterId?: UUID;
   scimGroupRequestConverterId?: UUID;
@@ -11275,6 +11418,26 @@ export enum TransactionType {
   AbsoluteMajority = "AbsoluteMajority"
 }
 
+/**
+ * Represents the inbound lambda parameter 'mfaTrust' inside the 'context' parameter for MFA Required lambdas.
+ */
+export interface Trust {
+  applicationId?: UUID;
+  attributes?: Record<string, string>;
+  expirationInstant?: number;
+  id?: string;
+  insertInstant?: number;
+  startInstants?: StartInstant;
+  state?: Record<string, any>;
+  tenantId?: UUID;
+  userId?: UUID;
+}
+
+export interface StartInstant {
+  applications?: Record<UUID, number>;
+  tenant?: number;
+}
+
 /**
  * @author Brett Guy
  */
@@ -11434,6 +11597,17 @@ export interface TwoFactorStartResponse {
   twoFactorId?: string;
 }
 
+/**
+ * Check the status of two-factor authentication for a user, with more options than on a GET request.
+ */
+export interface TwoFactorStatusRequest extends BaseEventRequest {
+  accessToken?: string;
+  action?: MultiFactorAction;
+  applicationId?: UUID;
+  twoFactorTrustId?: string;
+  userId?: UUID;
+}
+
 /**
  * @author Daniel DeGroff
  */