feat(mfa): Add MFA endpoints for TOTP setup

Because:

* We will be wrapping TOTP creation flow with an MFA guard, this sets up the backend support

This commit:

* Adds MFA-variants of the TOTP setup endpoints
* Adds and updates unit tests
* Adds integration tests for the MFA routes
* Adds docs for the new endpoints and a bit of extra docs for the original session-token-based endpoints
* Adds a little mail helper to obtain the MFA code in tests

Issue #FXA-12229

Author: vpomerleau

packages/fxa-auth-client/lib/client.ts

@@ -1763,6 +1763,24 @@ export default class AuthClient {
     );
   }
 
+  /**
+   * @deprecated Use createTotpTokenWithJwt instead
+   *
+   * Create a TOTP secret for the account (session-token variant).
+   *
+   * Requires a verified session token. Returns the QR code URL and shared
+   * secret used to enroll an authenticator app, and optionally a set of
+   * recovery codes.
+   *
+   * Note: Maintained for legacy/inline setup flows. For new integrations,
+   * prefer the MFA JWT variant.
+   *
+   * @param sessionToken - Verified session token for the signed-in user
+   * @param options - Optional request options
+   * @param options.metricsContext - Optional metrics context for telemetry
+   * @param headers - Optional additional request headers
+   * @returns Promise resolving to `{ qrCodeUrl, secret }`
+   */
   async createTotpToken(
     sessionToken: hexstring,
     options: {
@@ -1776,6 +1794,49 @@ export default class AuthClient {
     return this.sessionPost('/totp/create', sessionToken, options, headers);
   }
 
+  /**
+   * Create a new TOTP secret (JWT variant).
+   *
+   * Requires an MFA JWT with scope `mfa:2fa`. Returns the QR code URL,
+   * the shared secret, and optionally recovery codes when requested.
+   *
+   * @param jwt MFA access token including `mfa:2fa` scope
+   * @param options Optional request options
+   * @param options.metricsContext Optional metrics context for telemetry
+   * @param headers Optional extra headers
+   * @returns Promise resolving to `{ qrCodeUrl, secret }`
+   */
+  async createTotpTokenWithJwt(
+    jwt: string,
+    options: {
+      metricsContext?: MetricsContext;
+    } = {},
+    headers?: Headers
+  ): Promise<{
+    qrCodeUrl: string;
+    secret: string;
+  }> {
+    return this.jwtPost('/mfa/totp/create', jwt, options, headers);
+  }
+
+  /**
+   * @deprecated Use verifyTotpSetupCodeWithJwt instead
+   * Verify the authenticator code for the in-progress TOTP setup.
+   *
+   * Validates a 6-digit code generated by the app using the secret returned by
+   * `createTotpToken`. This does not finalize setup; call `completeTotpSetup`
+   * to activate TOTP.
+   *
+   * Note: Maintained for legacy/inline setup flows. For new integrations,
+   * prefer the MFA JWT variant.
+   *
+   * @param sessionToken - Verified session token for the signed-in user
+   * @param code - 6-digit code from the authenticator app
+   * @param options - Optional request options
+   * @param options.metricsContext - Optional metrics context for telemetry
+   * @param headers - Optional additional request headers
+   * @returns Promise resolving to `{ success: boolean }`
+   */
   async verifyTotpSetupCode(
     sessionToken: hexstring,
     code: string,
@@ -1790,6 +1851,49 @@ export default class AuthClient {
     );
   }
 
+  /**
+   * Verify a TOTP setup code against the in-progress secret (JWT variant).
+   *
+   * Requires an MFA JWT with scope `mfa:2fa`. On success, marks the setup
+   * as verified in Redis and refreshes TTLs.
+   *
+   * @param jwt MFA access token including `mfa:2fa` scope
+   * @param code The 6-digit authenticator app code
+   * @param options Optional request options
+   * @param options.metricsContext Optional metrics context for telemetry
+   * @param headers Optional extra headers
+   * @returns Promise resolving to `{ success: boolean }`
+   */
+  async verifyTotpSetupCodeWithJwt(
+    jwt: string,
+    code: string,
+    options: { metricsContext?: MetricsContext } = {},
+    headers?: Headers
+  ): Promise<{ success: boolean }> {
+    return this.jwtPost(
+      '/mfa/totp/setup/verify',
+      jwt,
+      { code, ...options },
+      headers
+    );
+  }
+
+  /**
+   * @deprecated Use completeTotpSetupWithJwt instead
+   * Finalize TOTP setup for the account.
+   *
+   * Marks the verified in-progress secret as the active second factor.
+   *
+   * Note: Maintained for legacy/inline setup flows. For new integrations,
+   * prefer the MFA JWT variant.
+   *
+   * @param sessionToken - Verified session token for the signed-in user
+   * @param options - Optional request options
+   * @param options.service - Optional service name
+   * @param options.metricsContext - Optional metrics context for telemetry
+   * @param headers - Optional additional request headers
+   * @returns Promise resolving to `{ success: boolean }`
+   */
   async completeTotpSetup(
     sessionToken: hexstring,
     options: { service?: string; metricsContext?: MetricsContext } = {},
@@ -1803,6 +1907,31 @@ export default class AuthClient {
     );
   }
 
+  /**
+   * Complete TOTP setup after successful code verification (JWT variant).
+   *
+   * Requires an MFA JWT with scope `mfa:2fa`. Validates the verification
+   * flag for the current secret and persists the enabled, verified token.
+   *
+   * @param jwt MFA access token including `mfa:2fa` scope
+   * @param options Optional request options
+   * @param options.metricsContext Optional metrics context for telemetry
+   * @param headers Optional extra headers
+   * @returns Promise resolving to `{ success: boolean }`
+   */
+  async completeTotpSetupWithJwt(
+    jwt: string,
+    options: { metricsContext?: MetricsContext } = {},
+    headers?: Headers
+  ): Promise<{ success: boolean }> {
+    return this.jwtPost(
+      '/mfa/totp/setup/complete',
+      jwt,
+      { ...options },
+      headers
+    );
+  }
+
   /**
    * @deprecated Use startReplaceTotpTokenWithJwt instead
    * Initiates the TOTP replacement flow using a session token
@@ -1831,29 +1960,6 @@ export default class AuthClient {
     );
   }
 
-  /**
-   * @deprecated Use confirmReplaceTotpTokenWithJwt instead
-   * Confirms TOTP replacement by verifying the code for the in-progress secret.
-   * Requires a verified session token.
-   *
-   * @param sessionToken - required, must be a verified session token
-   * @param code - 6-digit authenticator app code to validate the new secret
-   * @param headers - Optional additional headers for the request
-   * @returns A promise that resolves when the replacement has been accepted
-   */
-  async confirmReplaceTotpToken(
-    sessionToken: hexstring,
-    code: string,
-    headers?: Headers
-  ): Promise<void> {
-    return this.sessionPost(
-      '/totp/replace/confirm',
-      sessionToken,
-      { code },
-      headers
-    );
-  }
-
   /**
    * Initiates the TOTP replacement flow using an MFA JWT.
    * Requires a JWT with scope `mfa:2fa` and returns data to
@@ -1877,6 +1983,29 @@ export default class AuthClient {
     return this.jwtPost('/mfa/totp/replace/start', jwt, options, headers);
   }
 
+  /**
+   * @deprecated Use confirmReplaceTotpTokenWithJwt instead
+   * Confirms TOTP replacement by verifying the code for the in-progress secret.
+   * Requires a verified session token.
+   *
+   * @param sessionToken - required, must be a verified session token
+   * @param code - 6-digit authenticator app code to validate the new secret
+   * @param headers - Optional additional headers for the request
+   * @returns A promise that resolves when the replacement has been accepted
+   */
+  async confirmReplaceTotpToken(
+    sessionToken: hexstring,
+    code: string,
+    headers?: Headers
+  ): Promise<void> {
+    return this.sessionPost(
+      '/totp/replace/confirm',
+      sessionToken,
+      { code },
+      headers
+    );
+  }
+
   /**
    * Confirms TOTP replacement by verifying the code for the in-progress secret.
    * Requires a valid MFA JWT scoped to the action (e.g. `mfa:2fa`).

packages/fxa-auth-server/docs/swagger/totp-api.ts

@@ -21,6 +21,18 @@ const TOTP_CREATE_POST = {
   ],
 };
 
+const MFA_TOTP_CREATE_POST = {
+  ...TAGS_TOTP,
+  description: '/mfa/totp/create',
+  notes: [
+    dedent`
+      🔒 Authenticated with MFA JWT (scope: mfa:2fa)
+
+      Create a new randomly generated TOTP token for a user if they do not currently have one. This variant requires an MFA JWT and is intended for flows that have already passed MFA requirements.
+    `,
+  ],
+};
+
 const TOTP_DESTROY_POST = {
   ...TAGS_TOTP,
   description: '/totp/destroy',
@@ -153,6 +165,18 @@ const TOTP_SETUP_VERIFY_POST = {
   ],
 };
 
+const MFA_TOTP_SETUP_VERIFY_POST = {
+  ...TAGS_TOTP,
+  description: '/mfa/totp/setup/verify',
+  notes: [
+    dedent`
+      🔒 Authenticated with MFA JWT (scope: mfa:2fa)
+
+      Verifies an authenticator app code against the in-progress TOTP secret stored in Redis during setup, using an MFA JWT. On success, marks the setup as verified in Redis and aligns TTLs.
+    `,
+  ],
+};
+
 const TOTP_SETUP_COMPLETE_POST = {
   ...TAGS_TOTP,
   description: '/totp/setup/complete',
@@ -165,9 +189,22 @@ const TOTP_SETUP_COMPLETE_POST = {
   ],
 };
 
+const MFA_TOTP_SETUP_COMPLETE_POST = {
+  ...TAGS_TOTP,
+  description: '/mfa/totp/setup/complete',
+  notes: [
+    dedent`
+      🔒 Authenticated with MFA JWT (scope: mfa:2fa)
+
+      Completes TOTP setup (JWT variant) by validating the Redis verification flag for the current secret, then persisting the secret to the database as enabled and verified. Cleans up temporary Redis entries.
+    `,
+  ],
+};
+
 const API_DOCS = {
   SESSION_VERIFY_TOTP_POST,
   TOTP_CREATE_POST,
+  MFA_TOTP_CREATE_POST,
   TOTP_DESTROY_POST,
   MFA_TOTP_DESTROY_POST,
   TOTP_EXISTS_GET,
@@ -178,7 +215,9 @@ const API_DOCS = {
   MFA_TOTP_REPLACE_START_POST,
   MFA_TOTP_REPLACE_CONFIRM_POST,
   TOTP_SETUP_VERIFY_POST,
+  MFA_TOTP_SETUP_VERIFY_POST,
   TOTP_SETUP_COMPLETE_POST,
+  MFA_TOTP_SETUP_COMPLETE_POST,
 };
 
 export default API_DOCS;