feat: add mfa totp to the email otp flow

[blakecduncan]

Pull Request Checklist

• Did you add new tests and confirm existing tests pass? (yarn test)
• Did you update relevant docs? (docs are found in the site folder, and guidelines for updating/adding docs can be found in the contribution guide)
• Do your commits follow the Conventional Commits standard?
• Does your PR title also follow the Conventional Commits standard?
• If you have a breaking change, is it correctly reflected in your commit message? (e.g. feat!: breaking change)
• Did you run lint (yarn lint:check) and fix any issues? (yarn lint:write)
• Did you follow the contribution guidelines?

---

New api

// Setting up MFA

const client = new AlchemySignerWebClient(...)

// Get existing MFA factors
const { factors } = await client.getMfaFactors();

// 1. User already signed in

// Enable TOTP MFA
// Returns factor details including ID and setup information
const result = await client.enableMfa({
  factorType: "totp"
});

// result contains:
// {
//   factorId: "factor-id-123",
//   factorType: "totp",
//   factorTotpUrl: "otpauth://totp/Example:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Example"
// }

// Verify the MFA setup by providing the factor ID and verification code
await client.verifyMfa({
  factorId: result.factorId,
  factorCode: "123456"
});

// Disable MFA by providing an array of factor IDs to remove
await client.disableMfa({
  factors: [result.factorId]
});

Authenticating (email + otp)

// Create a webclient
const client = new AlchemySignerWebClient(...)

// Get the signer
const signer = await client?.account.getSigner();

signer.on("mfaStatusChanged", async (status) => {
  if (status === AlchemyMfaStatus.REQUIRED) {
    const factors = await client.getMfaFactors();
    console.log("MFA is required with factors:", factors);
    // Store factors for later use
  }
});

await signer.authenticate({
  type: "email",
  emailMode: "otp",
  email: "[email protected]",
});
 
if (signer.getMfaStatus() === AlchemyMfaStatus.REQUIRED) {
  // Prompt for totp

  // later once the user has entered the code from their email
  await signer.authenticate({
    type: "otp",
    otpCode: "123456",
    multiFactor: {
      factorId: "factor-id-123",
      challange: { code },
    }
  });
} else {
  // Regular OTP flow
  await signer.authenticate({
    type: "otp",
    otpCode: "123456"
  });
}

Authenticating (email + magic link)

// send the email and inclue mfa challenge
await signer.authenticate({
  type: "email",
  emailMode: "magicLink",
  email: "[email protected]",
  multiFactor: {
     factorId: "factor-id-123",
     challange: { code },
   }
});
 
// later once the user has clicked the link
const url = new URL(window.location.href);
const bundle = url.searchParams.get("bundle");
if (!bundle) {
  throw new Error("No bundle found in URL");
}
 
await signer.authenticate({
  type: "email",
  bundle,
});

---

PR-Codex overview

This PR primarily focuses on enhancing the multi-factor authentication (MFA) functionality in the @account-kit/signer package. It introduces new types, methods, and documentation related to MFA, ensuring better handling and management of MFA factors.

Detailed summary

• Added isMfaRequired to TemporarySession type.
• Introduced AlchemyMfaStatus enum with values NOT_REQUIRED and REQUIRED.
• Added methods for managing MFA: getMfaFactors, addMfa, verifyMfa, and removeMfa in BaseSignerClient and AlchemySignerWebClient.
• Updated RNSignerClient to override MFA methods with errors if not implemented.
• Enhanced documentation for MFA-related methods across multiple .mdx files.
• Updated state management to incorporate MFA status in the BaseAlchemySigner.

✨ Ask PR-Codex anything about this PR by commenting with /codex {your question}

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
aa-sdk-site	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 27, 2025 6:56pm
aa-sdk-ui-demo	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 27, 2025 6:56pm

[blakecduncan]

This whole method should probably be broken up into multiple methods but I figured I could do that as a separate task if we want to circle back to it

[rthomare]

fyi @moldy530 @iykazrji

[rthomare]

Does this need a 3rd state of "completed"?

[rthomare]

I guess looking at some of Josh's PRs it might also need a "disabled"

[blakecduncan]

I think there are two separate states at play here. The state of the mfa factor and whether or not a user requires mfa on login.

I was thinking that AlchemyMfaStatus would be the User level required/not required at sign in state.

[rthomare]

is this just AlchemyMfaStatus?

[blakecduncan]

Yeah good catch

[rthomare]

Worth gut checking to see if this request already includes the jwt in the headers? https://github.com/alchemyplatform/aa-sdk/blob/008812b0/account-kit/signer/src/client/base.ts#L374 We might not even need to have the stamped request object in there.

[blakecduncan]

Just checked and when the api call is made, the jwt is undefined

[rthomare]

On thing we may have forgetten is specifying which type of multifactor @0xfourzerofour. We might want that as a parameter here just for the sake of future proofing.