Implement TOTP MFA enrollment flows (#6598)

* Implement TOTP MFA enrollment.

This includes changes to mfa_info, addition of TotpMultiFactorImpl and unit tests.

* move all TOTP implementation into core/mfa/assertions.

We do not need to restrict this to platform_browser. SMS mfa is in platform_browser since it requires a recaptcha step.

* Include a reference to Auth in TotpSecret

This is cleaner than looking up the app and auth instance with getApp and getAuth.

* addressed review comments, added totp subdirectory.

Author: prameshj

common/api-review/auth.api.md

@@ -750,6 +750,10 @@ export function signOut(auth: Auth): Promise<void>;
 export interface TotpMultiFactorAssertion extends MultiFactorAssertion {
 }
 
+// @public
+export interface TotpMultiFactorInfo extends MultiFactorInfo {
+}
+
 // @public
 export class TwitterAuthProvider extends BaseOAuthProvider {
     constructor();

packages/auth/src/api/account_management/mfa.test.ts

@@ -27,7 +27,9 @@ import * as mockFetch from '../../../test/helpers/mock_fetch';
 import { ServerError } from '../errors';
 import {
   finalizeEnrollPhoneMfa,
+  finalizeEnrollTotpMfa,
   startEnrollPhoneMfa,
+  startEnrollTotpMfa,
   withdrawMfa
 } from './mfa';
 
@@ -89,7 +91,7 @@ describe('api/account_management/startEnrollPhoneMfa', () => {
 
     await expect(startEnrollPhoneMfa(auth, request)).to.be.rejectedWith(
       FirebaseError,
-      "Firebase: This user's credential isn't valid for this project. This can happen if the user's token has been tampered with, or if the user isn't for the project associated with this API key. (auth/invalid-user-token)."
+      'auth/invalid-user-token'
     );
     expect(mock.calls[0].request).to.eql(request);
   });
@@ -152,6 +154,139 @@ describe('api/account_management/finalizeEnrollPhoneMfa', () => {
     );
 
     await expect(finalizeEnrollPhoneMfa(auth, request)).to.be.rejectedWith(
+      FirebaseError,
+      'auth/invalid-verification-id'
+    );
+    expect(mock.calls[0].request).to.eql(request);
+  });
+});
+
+describe('api/account_management/startEnrollTotpMfa', () => {
+  const request = {
+    idToken: 'id-token',
+    totpEnrollmentInfo: {}
+  };
+
+  let auth: TestAuth;
+
+  beforeEach(async () => {
+    auth = await testAuth();
+    mockFetch.setUp();
+  });
+
+  afterEach(mockFetch.tearDown);
+
+  it('should POST to the correct endpoint', async () => {
+    const currentTime = new Date().toISOString();
+    const mock = mockEndpoint(Endpoint.START_MFA_ENROLLMENT, {
+      totpSessionInfo: {
+        sharedSecretKey: 'key123',
+        verificationCodeLength: 6,
+        hashingAlgorithm: 'SHA256',
+        periodSec: 30,
+        sessionInfo: 'session-info',
+        finalizeEnrollmentTime: currentTime
+      }
+    });
+
+    const response = await startEnrollTotpMfa(auth, request);
+    expect(response.totpSessionInfo.sharedSecretKey).to.eq('key123');
+    expect(response.totpSessionInfo.verificationCodeLength).to.eq(6);
+    expect(response.totpSessionInfo.hashingAlgorithm).to.eq('SHA256');
+    expect(response.totpSessionInfo.periodSec).to.eq(30);
+    expect(response.totpSessionInfo.sessionInfo).to.eq('session-info');
+    expect(response.totpSessionInfo.finalizeEnrollmentTime).to.eq(currentTime);
+    expect(mock.calls[0].request).to.eql(request);
+    expect(mock.calls[0].method).to.eq('POST');
+    expect(mock.calls[0].headers!.get(HttpHeader.CONTENT_TYPE)).to.eq(
+      'application/json'
+    );
+    expect(mock.calls[0].headers!.get(HttpHeader.X_CLIENT_VERSION)).to.eq(
+      'testSDK/0.0.0'
+    );
+  });
+
+  it('should handle errors', async () => {
+    const mock = mockEndpoint(
+      Endpoint.START_MFA_ENROLLMENT,
+      {
+        error: {
+          code: 400,
+          message: ServerError.INVALID_ID_TOKEN,
+          errors: [
+            {
+              message: ServerError.INVALID_ID_TOKEN
+            }
+          ]
+        }
+      },
+      400
+    );
+
+    await expect(startEnrollTotpMfa(auth, request)).to.be.rejectedWith(
+      FirebaseError,
+      'auth/invalid-user-token'
+    );
+    expect(mock.calls[0].request).to.eql(request);
+  });
+});
+
+describe('api/account_management/finalizeEnrollTotpMfa', () => {
+  const request = {
+    idToken: 'id-token',
+    displayName: 'my-otp-app',
+    totpVerificationInfo: {
+      sessionInfo: 'session-info',
+      verificationCode: 'code'
+    }
+  };
+
+  let auth: TestAuth;
+
+  beforeEach(async () => {
+    auth = await testAuth();
+    mockFetch.setUp();
+  });
+
+  afterEach(mockFetch.tearDown);
+
+  it('should POST to the correct endpoint', async () => {
+    const mock = mockEndpoint(Endpoint.FINALIZE_MFA_ENROLLMENT, {
+      idToken: 'id-token',
+      refreshToken: 'refresh-token'
+    });
+
+    const response = await finalizeEnrollTotpMfa(auth, request);
+    expect(response.idToken).to.eq('id-token');
+    expect(response.refreshToken).to.eq('refresh-token');
+    expect(mock.calls[0].request).to.eql(request);
+    expect(mock.calls[0].method).to.eq('POST');
+    expect(mock.calls[0].headers!.get(HttpHeader.CONTENT_TYPE)).to.eq(
+      'application/json'
+    );
+    expect(mock.calls[0].headers!.get(HttpHeader.X_CLIENT_VERSION)).to.eq(
+      'testSDK/0.0.0'
+    );
+  });
+
+  it('should handle errors', async () => {
+    const mock = mockEndpoint(
+      Endpoint.FINALIZE_MFA_ENROLLMENT,
+      {
+        error: {
+          code: 400,
+          message: ServerError.INVALID_SESSION_INFO,
+          errors: [
+            {
+              message: ServerError.INVALID_SESSION_INFO
+            }
+          ]
+        }
+      },
+      400
+    );
+
+    await expect(finalizeEnrollTotpMfa(auth, request)).to.be.rejectedWith(
       FirebaseError,
       'Firebase: The verification ID used to create the phone auth credential is invalid. (auth/invalid-verification-id).'
     );

packages/auth/src/api/account_management/mfa.ts

@@ -26,7 +26,7 @@ import { FinalizeMfaResponse } from '../authentication/mfa';
 import { AuthInternal } from '../../model/auth';
 
 /**
- * MFA Info as returned by the API
+ * MFA Info as returned by the API.
  */
 interface BaseMfaEnrollment {
   mfaEnrollmentId: string;
@@ -35,16 +35,21 @@ interface BaseMfaEnrollment {
 }
 
 /**
- * An MFA provided by SMS verification
+ * An MFA provided by SMS verification.
  */
 export interface PhoneMfaEnrollment extends BaseMfaEnrollment {
   phoneInfo: string;
 }
 
 /**
- * MfaEnrollment can be any subtype of BaseMfaEnrollment, currently only PhoneMfaEnrollment is supported
+ * An MFA provided by TOTP (Time-based One Time Password).
  */
-export type MfaEnrollment = PhoneMfaEnrollment;
+export interface TotpMfaEnrollment extends BaseMfaEnrollment {}
+
+/**
+ * MfaEnrollment can be any subtype of BaseMfaEnrollment, currently only PhoneMfaEnrollment and TotpMfaEnrollment are supported.
+ */
+export type MfaEnrollment = PhoneMfaEnrollment | TotpMfaEnrollment;
 
 export interface StartPhoneMfaEnrollmentRequest {
   idToken: string;
@@ -100,6 +105,66 @@ export function finalizeEnrollPhoneMfa(
     _addTidIfNecessary(auth, request)
   );
 }
+export interface StartTotpMfaEnrollmentRequest {
+  idToken: string;
+  totpEnrollmentInfo: {};
+  tenantId?: string;
+}
+
+export interface StartTotpMfaEnrollmentResponse {
+  totpSessionInfo: {
+    sharedSecretKey: string;
+    verificationCodeLength: number;
+    hashingAlgorithm: string;
+    periodSec: number;
+    sessionInfo: string;
+    finalizeEnrollmentTime: number;
+  };
+}
+
+export function startEnrollTotpMfa(
+  auth: AuthInternal,
+  request: StartTotpMfaEnrollmentRequest
+): Promise<StartTotpMfaEnrollmentResponse> {
+  return _performApiRequest<
+    StartTotpMfaEnrollmentRequest,
+    StartTotpMfaEnrollmentResponse
+  >(
+    auth,
+    HttpMethod.POST,
+    Endpoint.START_MFA_ENROLLMENT,
+    _addTidIfNecessary(auth, request)
+  );
+}
+
+export interface TotpVerificationInfo {
+  sessionInfo: string;
+  verificationCode: string;
+}
+export interface FinalizeTotpMfaEnrollmentRequest {
+  idToken: string;
+  totpVerificationInfo: TotpVerificationInfo;
+  displayName?: string | null;
+  tenantId?: string;
+}
+
+export interface FinalizeTotpMfaEnrollmentResponse
+  extends FinalizeMfaResponse {}
+
+export function finalizeEnrollTotpMfa(
+  auth: AuthInternal,
+  request: FinalizeTotpMfaEnrollmentRequest
+): Promise<FinalizeTotpMfaEnrollmentResponse> {
+  return _performApiRequest<
+    FinalizeTotpMfaEnrollmentRequest,
+    FinalizeTotpMfaEnrollmentResponse
+  >(
+    auth,
+    HttpMethod.POST,
+    Endpoint.FINALIZE_MFA_ENROLLMENT,
+    _addTidIfNecessary(auth, request)
+  );
+}
 
 export interface WithdrawMfaRequest {
   idToken: string;