Device & MFA Management

/**
 * Associate a software token for TOTP MFA
 * Initiates setup process for authenticator apps like Google Authenticator
 */
class AssociateSoftwareTokenCommand {
  constructor(input: AssociateSoftwareTokenCommandInput);
}

interface AssociateSoftwareTokenCommandInput {
  /** Access token for authenticated user */
  AccessToken?: string;
  
  /** Session token for unauthenticated flows */
  Session?: string;
}

interface AssociateSoftwareTokenCommandOutput {
  /** Secret code for setting up authenticator app */
  SecretCode?: string;
  
  /** Session token for continuing the flow */
  Session?: string;
}

/**
 * Verify software token to complete TOTP MFA setup
 * Confirms the authenticator app is correctly configured
 */
class VerifySoftwareTokenCommand {
  constructor(input: VerifySoftwareTokenCommandInput);
}

interface VerifySoftwareTokenCommandInput {
  /** Access token for authenticated user */
  AccessToken?: string;
  
  /** Session token for unauthenticated flows */
  Session?: string;
  
  /** TOTP code from authenticator app */
  UserCode: string;
  
  /** Friendly name for the MFA device */
  FriendlyDeviceName?: string;
}

/**
 * Set user's MFA preferences
 * Configure which MFA methods are enabled and preferred
 */
class SetUserMFAPreferenceCommand {
  constructor(input: SetUserMFAPreferenceCommandInput);
}

interface SetUserMFAPreferenceCommandInput {
  /** SMS MFA settings */
  SMSMfaSettings?: SMSMfaSettingsType;
  
  /** Software token MFA settings */
  SoftwareTokenMfaSettings?: SoftwareTokenMfaSettingsType;
  
  /** Access token for authenticated user */
  AccessToken: string;
}

interface SMSMfaSettingsType {
  /** Whether SMS MFA is enabled */
  Enabled?: boolean;
  
  /** Whether SMS MFA is the preferred method */
  PreferredMfa?: boolean;
}

interface SoftwareTokenMfaSettingsType {
  /** Whether software token MFA is enabled */
  Enabled?: boolean;
  
  /** Whether software token MFA is the preferred method */
  PreferredMfa?: boolean;
}

import {
  CognitoIdentityProviderClient,
  AssociateSoftwareTokenCommand,
  VerifySoftwareTokenCommand,
  SetUserMFAPreferenceCommand
} from "@aws-sdk/client-cognito-identity-provider";

const client = new CognitoIdentityProviderClient({ region: "us-east-1" });

// 1. Start TOTP setup
const associateResult = await client.send(new AssociateSoftwareTokenCommand({
  AccessToken: "user-access-token"
}));

console.log("Setup QR code with this secret:", associateResult.SecretCode);

// 2. Verify setup with code from authenticator app
const verifyResult = await client.send(new VerifySoftwareTokenCommand({
  AccessToken: "user-access-token",
  UserCode: "123456", // Code from authenticator app
  FriendlyDeviceName: "My Phone"
}));

// 3. Set MFA preferences
await client.send(new SetUserMFAPreferenceCommand({
  AccessToken: "user-access-token",
  SoftwareTokenMfaSettings: {
    Enabled: true,
    PreferredMfa: true
  },
  SMSMfaSettings: {
    Enabled: false,
    PreferredMfa: false
  }
}));

/**
 * List devices for the authenticated user
 * Returns all remembered and tracked devices
 */
class ListDevicesCommand {
  constructor(input: ListDevicesCommandInput);
}

interface ListDevicesCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
  
  /** Maximum number of devices to return */
  Limit?: number;
  
  /** Pagination token for retrieving more devices */
  PaginationToken?: string;
}

interface ListDevicesCommandOutput {
  /** Array of user devices */
  Devices?: DeviceType[];
  
  /** Pagination token for retrieving more results */
  PaginationToken?: string;
}

/**
 * Get information about a specific device
 * Returns detailed device metadata and status
 */
class GetDeviceCommand {
  constructor(input: GetDeviceCommandInput);
}

interface GetDeviceCommandInput {
  /** Device key identifier */
  DeviceKey: string;
  
  /** Access token for authenticated user */
  AccessToken?: string;
}

interface GetDeviceCommandOutput {
  /** Device information and metadata */
  Device: DeviceType;
}

interface DeviceType {
  /** Unique device key */
  DeviceKey?: string;
  
  /** Device attributes (name, type, etc.) */
  DeviceAttributes?: AttributeType[];
  
  /** Date when device was created */
  DeviceCreateDate?: Date;
  
  /** Date when device was last modified */
  DeviceLastModifiedDate?: Date;
  
  /** Date when device was last authenticated */
  DeviceLastAuthenticatedDate?: Date;
}

/**
 * Confirm device for tracking
 * Opts device into tracking and remembering for future logins
 */
class ConfirmDeviceCommand {
  constructor(input: ConfirmDeviceCommandInput);
}

interface ConfirmDeviceCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
  
  /** Device key to confirm */
  DeviceKey: string;
  
  /** Device secret verifier configuration */
  DeviceSecretVerifierConfig?: DeviceSecretVerifierConfigType;
  
  /** Friendly name for the device */
  DeviceName?: string;
}

/**
 * Forget a device (stop tracking)
 * Removes device from tracking and requires re-authentication
 */
class ForgetDeviceCommand {
  constructor(input: ForgetDeviceCommandInput);
}

interface ForgetDeviceCommandInput {
  /** Access token for authenticated user */
  AccessToken?: string;
  
  /** Device key to forget */
  DeviceKey: string;
}

/**
 * Update device status (remembered/not_remembered)
 * Change whether device is remembered for future logins
 */
class UpdateDeviceStatusCommand {
  constructor(input: UpdateDeviceStatusCommandInput);
}

interface UpdateDeviceStatusCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
  
  /** Device key to update */
  DeviceKey: string;
  
  /** New remembered status for device */
  DeviceRememberedStatus?: DeviceRememberedStatusType;
}

type DeviceRememberedStatusType = "remembered" | "not_remembered";

/**
 * Start WebAuthn credential registration
 * Initiates process for registering FIDO2 security keys or biometric authentication
 */
class StartWebAuthnRegistrationCommand {
  constructor(input: StartWebAuthnRegistrationCommandInput);
}

interface StartWebAuthnRegistrationCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
}

interface StartWebAuthnRegistrationCommandOutput {
  /** Credential creation options for WebAuthn API */
  CredentialCreationOptions: Record<string, any>;
}

/**
 * Complete WebAuthn credential registration
 * Finalizes registration with credential from WebAuthn API
 */
class CompleteWebAuthnRegistrationCommand {
  constructor(input: CompleteWebAuthnRegistrationCommandInput);
}

interface CompleteWebAuthnRegistrationCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
  
  /** Credential response from WebAuthn API */
  Credential: Record<string, any>;
}

/**
 * List WebAuthn credentials for user
 * Returns all registered FIDO2 credentials
 */ 
class ListWebAuthnCredentialsCommand {
  constructor(input: ListWebAuthnCredentialsCommandInput);
}

interface ListWebAuthnCredentialsCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
  
  /** Maximum number of credentials to return */
  MaxResults?: number;
  
  /** Pagination token for retrieving more credentials */
  NextToken?: string;
}

interface ListWebAuthnCredentialsCommandOutput {
  /** Array of WebAuthn credentials */
  Credentials?: WebAuthnCredentialType[];
  
  /** Pagination token for retrieving more results */
  NextToken?: string;
}

interface WebAuthnCredentialType {
  /** Credential ID */
  CredentialId?: string;
  
  /** Friendly name for the credential */
  FriendlyCredentialName?: string;
  
  /** Relying party ID */
  RelyingPartyId?: string;
  
  /** Authenticator attachment type */
  AuthenticatorAttachment?: string;
  
  /** Authenticator transport methods */
  AuthenticatorTransports?: string[];
  
  /** Date when credential was created */
  CreatedAt?: Date;
}

/**
 * Delete WebAuthn credential
 * Removes a FIDO2 credential from user's account
 */
class DeleteWebAuthnCredentialCommand {
  constructor(input: DeleteWebAuthnCredentialCommandInput);
}

interface DeleteWebAuthnCredentialCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
  
  /** Credential ID to delete */
  CredentialId: string;
}

/**
 * Get user's available authentication factors
 * Returns all configured MFA methods and capabilities
 */
class GetUserAuthFactorsCommand {
  constructor(input: GetUserAuthFactorsCommandInput);
}

interface GetUserAuthFactorsCommandInput {
  /** Access token for authenticated user */
  AccessToken: string;
}

interface GetUserAuthFactorsCommandOutput {
  /** Username of the user */
  Username?: string;
  
  /** Preferred MFA setting */
  PreferredMfaSetting?: string;
  
  /** List of enabled MFA settings */
  UserMFASettingList?: string[];
  
  /** Available authentication factors */
  ConfiguredUserAuthFactors?: AuthFactorType[];
}

interface AuthFactorType {
  /** Type of authentication factor */
  FactorType?: string;
  
  /** Name of the factor */
  FactorName?: string;
  
  /** Last used timestamp */
  LastUsedDate?: Date;
}

import {
  CognitoIdentityProviderClient,
  ListDevicesCommand,
  ConfirmDeviceCommand,
  AssociateSoftwareTokenCommand,
  VerifySoftwareTokenCommand,
  SetUserMFAPreferenceCommand,
  StartWebAuthnRegistrationCommand,
  CompleteWebAuthnRegistrationCommand,
  GetUserAuthFactorsCommand
} from "@aws-sdk/client-cognito-identity-provider";

const client = new CognitoIdentityProviderClient({ region: "us-east-1" });
const accessToken = "user-access-token";

// 1. List current devices
const devices = await client.send(new ListDevicesCommand({
  AccessToken: accessToken
}));

console.log("Current devices:", devices.Devices?.length);

// 2. Set up TOTP MFA
const totpSetup = await client.send(new AssociateSoftwareTokenCommand({
  AccessToken: accessToken
}));

// User scans QR code or enters secret: totpSetup.SecretCode
// After user configures authenticator app:

const totpVerify = await client.send(new VerifySoftwareTokenCommand({
  AccessToken: accessToken,
  UserCode: "123456", // Code from authenticator app
  FriendlyDeviceName: "iPhone Authenticator"
}));

// 3. Enable TOTP as preferred MFA
await client.send(new SetUserMFAPreferenceCommand({
  AccessToken: accessToken,
  SoftwareTokenMfaSettings: {
    Enabled: true,
    PreferredMfa: true
  }
}));

// 4. Set up WebAuthn (FIDO2) credential
const webauthnStart = await client.send(new StartWebAuthnRegistrationCommand({
  AccessToken: accessToken
}));

// Use WebAuthn API in browser:
// const credential = await navigator.credentials.create({
//   publicKey: webauthnStart.CredentialCreationOptions
// });

// Complete registration (after WebAuthn ceremony):
// await client.send(new CompleteWebAuthnRegistrationCommand({
//   AccessToken: accessToken,
//   Credential: credential
// }));

// 5. Get all configured auth factors
const authFactors = await client.send(new GetUserAuthFactorsCommand({
  AccessToken: accessToken
}));

console.log("Available auth factors:", authFactors.ConfiguredUserAuthFactors);
console.log("Preferred MFA:", authFactors.PreferredMfaSetting);

/**
 * Get device information (admin operation)
 * Retrieve device details for any user with admin privileges
 */
class AdminGetDeviceCommand {
  constructor(input: AdminGetDeviceCommandInput);
}

interface AdminGetDeviceCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Username of the device owner */
  Username: string;
  
  /** Device key identifier */
  DeviceKey: string;
}

/**
 * List user's devices (admin operation)
 * Retrieve all devices for a specific user with admin privileges
 */
class AdminListDevicesCommand {
  constructor(input: AdminListDevicesCommandInput);
}

interface AdminListDevicesCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Username to list devices for */
  Username: string;
  
  /** Maximum number of devices to return */
  Limit?: number;
  
  /** Pagination token for retrieving next page */
  PaginationToken?: string;
}

/**
 * Forget a device (admin operation)
 * Remove device from trusted devices list for a user
 */
class AdminForgetDeviceCommand {
  constructor(input: AdminForgetDeviceCommandInput);
}

interface AdminForgetDeviceCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Username of the device owner */
  Username: string;
  
  /** Device key to forget */
  DeviceKey: string;
}

/**
 * Update device status (admin operation)
 * Change device status (remembered/not_remembered) for a user's device
 */
class AdminUpdateDeviceStatusCommand {
  constructor(input: AdminUpdateDeviceStatusCommandInput);
}

interface AdminUpdateDeviceStatusCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Username of the device owner */
  Username: string;
  
  /** Device key to update */
  DeviceKey: string;
  
  /** New device status */
  DeviceRememberedStatus?: DeviceRememberedStatusType;
}