Multi-Factor Authentication

/**
 * Sets user MFA preferences for SMS and TOTP
 * @param smsMfaSettings - SMS MFA settings or null to disable
 * @param softwareTokenMfaSettings - TOTP MFA settings or null to disable
 * @param callback - Callback with result
 */
setUserMfaPreference(
  smsMfaSettings: IMfaSettings | null,
  softwareTokenMfaSettings: IMfaSettings | null,
  callback: NodeCallback<Error, string>
): void;

interface IMfaSettings {
  /** Whether this MFA method is preferred */
  PreferredMfa: boolean;
  /** Whether this MFA method is enabled */
  Enabled: boolean;
}

/**
 * Associates a software token (TOTP) with the user
 * @param callbacks - Callback handlers for the association process
 */
associateSoftwareToken(callbacks: {
  associateSecretCode: (secretCode: string) => void;
  onFailure: (err: any) => void;
}): void;

/**
 * Verifies software token setup with TOTP code
 * @param totpCode - TOTP code from authenticator app
 * @param friendlyDeviceName - Name for the TOTP device
 * @param callbacks - Success/failure callback handlers
 */
verifySoftwareToken(
  totpCode: string,
  friendlyDeviceName: string,
  callbacks: {
    onSuccess: (session: CognitoUserSession) => void;
    onFailure: (err: Error) => void;
  }
): void;

/**
 * Sends MFA code for verification during authentication
 * @param confirmationCode - MFA code (SMS or TOTP)
 * @param callbacks - Success/failure callback handlers
 * @param mfaType - Optional MFA type specification
 * @param clientMetadata - Optional client metadata for Lambda triggers
 */
sendMFACode(
  confirmationCode: string,
  callbacks: {
    onSuccess: (session: CognitoUserSession, userConfirmationNecessary?: boolean) => void;
    onFailure: (err: any) => void;
  },
  mfaType?: string,
  clientMetadata?: ClientMetadata
): void;

/**
 * Sends MFA type selection answer when multiple MFA options available
 * @param answerChallenge - Selected MFA type ('SMS' or 'SOFTWARE_TOKEN')
 * @param callbacks - Callback handlers with additional MFA flow options
 */
sendMFASelectionAnswer(
  answerChallenge: string,
  callbacks: {
    onSuccess: (session: CognitoUserSession) => void;
    onFailure: (err: any) => void;
    mfaRequired?: (challengeName: ChallengeName, challengeParameters: any) => void;
    totpRequired?: (challengeName: ChallengeName, challengeParameters: any) => void;
  }
): void;

// Setup TOTP MFA
cognitoUser.associateSoftwareToken({
  associateSecretCode: (secretCode) => {
    console.log("Setup your authenticator app with this secret:", secretCode);
    // Generate QR code: otpauth://totp/YourApp:username?secret=secretCode&issuer=YourApp
    
    const totpCode = prompt("Enter TOTP code from your authenticator app:");
    
    cognitoUser.verifySoftwareToken(totpCode, "My Phone", {
      onSuccess: (session) => {
        console.log("TOTP MFA setup successful");
        
        // Enable TOTP as preferred MFA
        cognitoUser.setUserMfaPreference(
          null, // Disable SMS MFA
          { PreferredMfa: true, Enabled: true }, // Enable TOTP MFA
          (err, result) => {
            if (err) {
              console.error("MFA preference update failed:", err);
              return;
            }
            console.log("TOTP MFA enabled as preferred method");
          }
        );
      },
      onFailure: (err) => {
        console.error("TOTP verification failed:", err);
      }
    });
  },
  onFailure: (err) => {
    console.error("TOTP association failed:", err);
  }
});

// Handle MFA during authentication
cognitoUser.authenticateUser(authDetails, {
  onSuccess: (session) => {
    console.log("Authentication successful without MFA");
  },
  onFailure: (err) => {
    console.error("Authentication failed:", err);
  },
  mfaRequired: (challengeName, challengeParameters) => {
    console.log("MFA required:", challengeName);
    const mfaCode = prompt("Enter MFA code:");
    
    cognitoUser.sendMFACode(mfaCode, {
      onSuccess: (session) => {
        console.log("MFA authentication successful");
      },
      onFailure: (err) => {
        console.error("MFA authentication failed:", err);
      }
    });
  },
  selectMFAType: (challengeName, challengeParameters) => {
    console.log("Select MFA type:", challengeParameters);
    const mfaType = prompt("Choose MFA: SMS or SOFTWARE_TOKEN");
    
    cognitoUser.sendMFASelectionAnswer(mfaType, {
      onSuccess: (session) => {
        console.log("MFA type selected successfully");
      },
      mfaRequired: (challengeName, params) => {
        const code = prompt("Enter MFA code:");
        cognitoUser.sendMFACode(code, {
          onSuccess: (session) => {
            console.log("Authentication complete");
          },
          onFailure: (err) => {
            console.error("MFA failed:", err);
          }
        });
      }
    });
  }
});

/**
 * Enables MFA for the user (deprecated - use setUserMfaPreference instead)
 * @param callback - Callback with result
 * @deprecated Use setUserMfaPreference instead
 */
enableMFA(callback: NodeCallback<Error, string>): void;

/**
 * Disables MFA for the user (deprecated - use setUserMfaPreference instead)
 * @param callback - Callback with result
 * @deprecated Use setUserMfaPreference instead
 */
disableMFA(callback: NodeCallback<Error, string>): void;

/**
 * Gets MFA options for the user (deprecated)
 * @param callback - Callback with MFA options
 * @deprecated Use getUserData instead
 */
getMFAOptions(callback: NodeCallback<Error, MFAOption[]>): void;

type ChallengeName = 
  | 'SMS_MFA'              // SMS-based MFA challenge
  | 'SOFTWARE_TOKEN_MFA'   // TOTP-based MFA challenge
  | 'SELECT_MFA_TYPE'      // User must select MFA method
  | 'MFA_SETUP';           // MFA setup required

interface MFAOption {
  /** Delivery medium for MFA */
  DeliveryMedium: 'SMS' | 'EMAIL';
  /** Attribute name used for delivery */
  AttributeName: string;
}