Add public methods to support TOTP as a multi-factor provider.

common/api-review/auth.api.md

@@ -361,6 +361,7 @@ export class FacebookAuthProvider extends BaseOAuthProvider {
 // @public
 export const FactorId: {
     readonly PHONE: "phone";
+    readonly TOTP: "totp";
 };
 
 // @public
@@ -745,6 +746,10 @@ export function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?
 // @public
 export function signOut(auth: Auth): Promise<void>;
 
+// @public
+export interface TotpMultiFactorAssertion extends MultiFactorAssertion {
+}
+
 // @public
 export class TwitterAuthProvider extends BaseOAuthProvider {
     constructor();

packages/auth/src/mfa/assertions/totp.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { TotpSecret } from '../../platform_browser/mfa/assertions/totp';
+import {
+  TotpMultiFactorAssertion,
+  MultiFactorSession,
+  FactorId
+} from '../../model/public_types';
+/**
+ * Provider for generating a {@link TotpMultiFactorAssertion}.
+ *
+ * @public
+ */
+export class TotpMultiFactorGenerator {
+  /**
+   * Provides a {@link TotpMultiFactorAssertion} to confirm ownership of
+   * the totp(Time-based One Time Password) second factor.
+   * This assertion is used to complete enrollment in TOTP second factor.
+   *
+   * @param secret {@link TotpSecret}.
+   * @param oneTimePassword One-time password from TOTP App.
+   * @returns A {@link TotpMultiFactorAssertion} which can be used with
+   * {@link MultiFactorUser.enroll}.
+   */
+  static assertionForEnrollment(
+    _secret: TotpSecret,
+    _oneTimePassword: string
+  ): TotpMultiFactorAssertion {
+    throw new Error('Unimplemented');
+  }
+  /**
+   * Provides a {@link TotpMultiFactorAssertion} to confirm ownership of the totp second factor.
+   * This assertion is used to complete signIn with TOTP as the second factor.
+   *
+   * @param enrollmentId identifies the enrolled TOTP second factor.
+   * @param otp One-time password from TOTP App.
+   * @returns A {@link TotpMultiFactorAssertion} which can be used with
+   * {@link MultiFactorResolver.resolveSignIn}.
+   */
+  static assertionForSignIn(
+    _enrollmentId: string,
+    _otp: string
+  ): TotpMultiFactorAssertion {
+    throw new Error('Unimplemented');
+  }
+  /**
+   * Returns a promise to {@link TOTPSecret} which contains the TOTP shared secret key and other parameters.
+   * Creates a TOTP secret as part of enrolling a TOTP second factor.
+   * Used for generating a QRCode URL or inputting into a TOTP App.
+   * This method uses the auth instance corresponding to the user in the multiFactorSession.
+   *
+   * @param session A link to {@MultiFactorSession}.
+   * @returns A promise to {@link TotpSecret}.
+   */
+  static async generateSecret(
+    _session: MultiFactorSession
+  ): Promise<TotpSecret> {
+    throw new Error('Unimplemented');
+  }
+  /**
+   * The identifier of the TOTP second factor: `totp`.
+   */
+  static FACTOR_ID = FactorId.TOTP;
+}

packages/auth/src/model/enum_maps.ts

@@ -22,7 +22,8 @@
  */
 export const FactorId = {
   /** Phone as second factor */
-  PHONE: 'phone'
+  PHONE: 'phone',
+  TOTP: 'totp'
 } as const;
 
 /**

packages/auth/src/model/public_types.ts

@@ -543,7 +543,8 @@ export interface AuthProvider {
  */
 export const enum FactorId {
   /** Phone as second factor */
-  PHONE = 'phone'
+  PHONE = 'phone',
+  TOTP = 'totp'
 }
 
 /**
@@ -1227,3 +1228,12 @@ export interface Dependencies {
    */
   errorMap?: AuthErrorMap;
 }
+
+/**
+ * The class for asserting ownership of a totp second factor. Provided by
+ * {@link TotpMultiFactorGenerator.assertion}.
+ *
+ * @public
+ */
+
+export interface TotpMultiFactorAssertion extends MultiFactorAssertion {}

packages/auth/src/platform_browser/mfa/assertions/totp.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Stores the shared secret key and other parameters to generate time-based OTPs.
+ * Implements methods to retrieve the shared secret key, generate a QRCode URL.
+ * @public
+ */
+export class TotpSecret {
+  /**
+   * Constructor for TotpSecret.
+   * @param secretKey - Shared secret key/seed used for enrolling in TOTP MFA and generating otps.
+   * @param hashingAlgorithm - Hashing algorithm used.
+   * @param codeLength - Length of the one-time passwords to be generated.
+   * @param codeIntervalSeconds - The interval (in seconds) when the OTP codes should change.
+   */
+  constructor(
+    readonly secretKey: string,
+    readonly hashingAlgorithm: string,
+    readonly codeLength: number,
+    readonly codeIntervalSeconds: number
+  ) {}
+  /**
+   * Returns a QRCode URL as described in
+   * https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+   * This can be displayed to the user as a QRCode to be scanned into a TOTP App like Google Authenticator.
+   * If the optional parameters are unspecified, an accountName of "<firebaseAppName>:<userEmail> and issuer of <firebaseAppName> are used.
+   *
+   * @param accountName the name of the account/app along with a user identifier.
+   * @param issuer issuer of the TOTP(likely the app name).
+   * @returns A QRCode URL string.
+   */
+  generateQrCodeUrl(_accountName?: string, _issuer?: string): string {
+    throw new Error('Unimplemented');
+  }
+}