feat(auth): Add TOTP support in Project and Tenant config

etc/firebase-admin.auth.api.md

@@ -264,9 +264,23 @@ export interface ListUsersResult {
     users: UserRecord[];
 }
 
+// @public
+export class MultiFactorAuthConfig implements MultiFactorConfig {
+    // (undocumented)
+    readonly factorIds: AuthFactorType[];
+    // (undocumented)
+    readonly providerConfigs: MultiFactorProviderConfig[];
+    // (undocumented)
+    readonly state: MultiFactorConfigState;
+    // (undocumented)
+    toJSON(): object;
+    static validate(options: MultiFactorConfig): void;
+}
+
 // @public
 export interface MultiFactorConfig {
     factorIds?: AuthFactorType[];
+    providerConfigs?: MultiFactorProviderConfig[];
     state: MultiFactorConfigState;
 }
 
@@ -287,6 +301,12 @@ export abstract class MultiFactorInfo {
     readonly uid: string;
 }
 
+// @public
+export interface MultiFactorProviderConfig {
+    state: MultiFactorConfigState;
+    totpProviderConfig?: TotpMultiFactorProviderConfig;
+}
+
 // @public
 export class MultiFactorSettings {
     enrolledFactors: MultiFactorInfo[];
@@ -336,6 +356,7 @@ export class PhoneMultiFactorInfo extends MultiFactorInfo {
 
 // @public
 export class ProjectConfig {
+    readonly multiFactorConfig?: MultiFactorAuthConfig;
     readonly smsRegionConfig?: SmsRegionConfig;
     toJSON(): object;
 }
@@ -415,6 +436,11 @@ export class TenantManager {
     updateTenant(tenantId: string, tenantOptions: UpdateTenantRequest): Promise<Tenant>;
 }
 
+// @public
+export interface TotpMultiFactorProviderConfig {
+    adjacentIntervals?: number;
+}
+
 // @public
 export interface UidIdentifier {
     // (undocumented)
@@ -434,6 +460,7 @@ export interface UpdatePhoneMultiFactorInfoRequest extends BaseUpdateMultiFactor
 
 // @public
 export interface UpdateProjectConfigRequest {
+    multiFactorConfig?: MultiFactorConfig;
     smsRegionConfig?: SmsRegionConfig;
 }
 

src/auth/auth-config.ts

@@ -478,6 +478,7 @@ const AUTH_FACTOR_SERVER_TO_CLIENT_TYPE: {[key: string]: AuthFactorType} =
 export interface MultiFactorAuthServerConfig {
   state?: MultiFactorConfigState;
   enabledProviders?: AuthFactorServerType[];
+  providerConfigs?: MultiFactorProviderConfig[];
 }
 
 /**
@@ -506,6 +507,38 @@ export interface MultiFactorConfig {
    * Currently only ‘phone’ is supported.
    */
   factorIds?: AuthFactorType[];
+  /**
+   * A list of multi-factor provider specific config. 
+   * New MFA providers (except phone) will indicate enablement/disablement through this field.
+   */
+  providerConfigs?: MultiFactorProviderConfig[];
+}
+
+/**
+ * Interface representing Multi Factor Provider configuration. 
+ * This config is used to set second factor auth except for SMS. 
+ * Currently, only TOTP is supported.
+ */
+export interface MultiFactorProviderConfig {
+  /**
+   * Indicates whether this multi-factor provider is enabled/disabled. 
+   */
+  state: MultiFactorConfigState;
+  /**
+   * TOTP MultiFactor provider config.
+   */
+  totpProviderConfig?: TotpMultiFactorProviderConfig;
+}
+
+/**
+ * Interface representing configuration settings for TOTP second factor auth. 
+ */
+export interface TotpMultiFactorProviderConfig {
+  /**
+    *  The allowed number of adjacent intervals that will be used for verification
+    *  to avoid clock skew.
+   */
+  adjacentIntervals?: number;
 }
 
 /**
@@ -516,6 +549,7 @@ export class MultiFactorAuthConfig implements MultiFactorConfig {
 
   public readonly state: MultiFactorConfigState;
   public readonly factorIds: AuthFactorType[];
+  public readonly providerConfigs: MultiFactorProviderConfig[];
 
   /**
    * Static method to convert a client side request to a MultiFactorAuthServerConfig.
@@ -543,6 +577,9 @@ export class MultiFactorAuthConfig implements MultiFactorConfig {
         request.enabledProviders = [];
       }
     }
+    if (Object.prototype.hasOwnProperty.call(options, 'providerConfigs')) {
+      request.providerConfigs = options.providerConfigs;
+    }
     return request;
   }
 
@@ -551,10 +588,11 @@ export class MultiFactorAuthConfig implements MultiFactorConfig {
    *
    * @param options - The options object to validate.
    */
-  private static validate(options: MultiFactorConfig): void {
+  public static validate(options: MultiFactorConfig): void {
     const validKeys = {
       state: true,
       factorIds: true,
+      providerConfigs: true,
     };
     if (!validator.isNonNullObject(options)) {
       throw new FirebaseAuthError(
@@ -573,8 +611,8 @@ export class MultiFactorAuthConfig implements MultiFactorConfig {
     }
     // Validate content.
     if (typeof options.state !== 'undefined' &&
-        options.state !== 'ENABLED' &&
-        options.state !== 'DISABLED') {
+      options.state !== 'ENABLED' &&
+      options.state !== 'DISABLED') {
       throw new FirebaseAuthError(
         AuthClientErrorCode.INVALID_CONFIG,
         '"MultiFactorConfig.state" must be either "ENABLED" or "DISABLED".',
@@ -599,6 +637,46 @@ export class MultiFactorAuthConfig implements MultiFactorConfig {
         }
       });
     }
+
+    if (typeof options.providerConfigs !== 'undefined') {
+      if (!validator.isArray(options.providerConfigs)) {
+        throw new FirebaseAuthError(
+          AuthClientErrorCode.INVALID_CONFIG,
+          '"MultiFactorConfig.providerConfigs" must be an array of valid "MultiFactorProviderConfig."',
+        );
+      }
+      //Validate content of array.
+      options.providerConfigs.forEach((multiFactorProviderConfig) => {
+        if (typeof multiFactorProviderConfig === 'undefined' || !validator.isObject(multiFactorProviderConfig)) {
+          throw new FirebaseAuthError(
+            AuthClientErrorCode.INVALID_CONFIG,
+            `"${multiFactorProviderConfig}" is not a valid "MultiFactorProviderConfig" type.`
+          )
+        }
+        if (typeof multiFactorProviderConfig.state === 'undefined' ||
+          (multiFactorProviderConfig.state !== 'ENABLED' &&
+            multiFactorProviderConfig.state !== 'DISABLED')) {
+          throw new FirebaseAuthError(
+            AuthClientErrorCode.INVALID_CONFIG,
+            '"MultiFactorConfig.providerConfigs.state" must be either "ENABLED" or "DISABLED".',
+          )
+        }
+        // Since TOTP is the only provider config available right now, not defining it will lead into an error
+        if (typeof multiFactorProviderConfig.totpProviderConfig === 'undefined') {
+          throw new FirebaseAuthError(
+            AuthClientErrorCode.INVALID_CONFIG,
+            '"MultiFactorConfig.providerConfigs.totpProviderConfig" must be defined.'
+          )
+        }
+        if (typeof multiFactorProviderConfig.totpProviderConfig.adjacentIntervals !== 'undefined' &&
+          !validator.isNumber(multiFactorProviderConfig.totpProviderConfig.adjacentIntervals)) {
+          throw new FirebaseAuthError(
+            AuthClientErrorCode.INVALID_ARGUMENT,
+            '"MultiFactorConfig.providerConfigs.totpProviderConfig.adjacentIntervals" must be a valid number.'
+          )
+        }
+      });
+    }
   }
 
   /**
@@ -624,13 +702,28 @@ export class MultiFactorAuthConfig implements MultiFactorConfig {
         this.factorIds.push(AUTH_FACTOR_SERVER_TO_CLIENT_TYPE[enabledProvider]);
       }
     })
+    this.providerConfigs = [];
+    (response.providerConfigs || []).forEach((providerConfig) => {
+      if (typeof providerConfig !== 'undefined') {
+        if (typeof providerConfig.state === 'undefined' ||
+          typeof providerConfig.totpProviderConfig === 'undefined' ||
+          (typeof providerConfig.totpProviderConfig.adjacentIntervals !== 'undefined' &&
+            typeof providerConfig.totpProviderConfig.adjacentIntervals !== 'number')) {
+          throw new FirebaseAuthError(
+            AuthClientErrorCode.INTERNAL_ERROR,
+            'INTERNAL ASSERT FAILED: Invalid multi-factor configuration response');
+        }
+        this.providerConfigs.push(providerConfig);
+      }
+    })
   }
 
   /** @returns The plain object representation of the multi-factor config instance. */
   public toJSON(): object {
     return {
       state: this.state,
       factorIds: this.factorIds,
+      providerConfigs: this.providerConfigs,
     };
   }
 }

src/auth/index.ts

@@ -80,6 +80,7 @@ export {
   MultiFactorConfigState,
   MultiFactorCreateSettings,
   MultiFactorUpdateSettings,
+  MultiFactorProviderConfig,
   OAuthResponseType,
   OIDCAuthProviderConfig,
   OIDCUpdateAuthProviderRequest,
@@ -91,6 +92,8 @@ export {
   UpdateMultiFactorInfoRequest,
   UpdatePhoneMultiFactorInfoRequest,
   UpdateRequest,
+  TotpMultiFactorProviderConfig,
+  MultiFactorAuthConfig,
 } from './auth-config';
 
 export {

src/auth/project-config.ts

@@ -18,6 +18,9 @@ import { AuthClientErrorCode, FirebaseAuthError } from '../utils/error';
 import {
   SmsRegionsAuthConfig,
   SmsRegionConfig,
+  MultiFactorConfig,
+  MultiFactorAuthConfig,
+  MultiFactorAuthServerConfig,
 } from './auth-config';
 import { deepCopy } from '../utils/deep-copy';
 
@@ -29,6 +32,10 @@ export interface UpdateProjectConfigRequest {
    * The SMS configuration to update on the project.
    */
   smsRegionConfig?: SmsRegionConfig;
+  /**
+   * The multi-factor auth configuration to update on the project.
+   */
+  multiFactorConfig?: MultiFactorConfig;
 }
 
 /**
@@ -37,6 +44,7 @@ export interface UpdateProjectConfigRequest {
  */
 export interface ProjectConfigServerResponse {
   smsRegionConfig?: SmsRegionConfig;
+  mfa?: MultiFactorAuthServerConfig;
 }
 
 /**
@@ -45,6 +53,7 @@ export interface ProjectConfigServerResponse {
  */
 export interface ProjectConfigClientRequest {
   smsRegionConfig?: SmsRegionConfig;
+  mfa?: MultiFactorAuthServerConfig;
 }
 
 /**
@@ -57,13 +66,19 @@ export class ProjectConfig {
    * This is based on the calling code of the destination phone number.
    */
   public readonly smsRegionConfig?: SmsRegionConfig;
+  /**
+   * The Multi Factor Config for the project.
+   * Configures the multi factor settings for the project.
+   * Supports only phone and TOTP.
+   */
+  public readonly multiFactorConfig?: MultiFactorAuthConfig;
 
   /**
    * Validates a project config options object. Throws an error on failure.
    *
    * @param request - The project config options object to validate.
    */
-  private static validate(request: ProjectConfigClientRequest): void {
+  private static validate(request: UpdateProjectConfigRequest): void {
     if (!validator.isNonNullObject(request)) {
       throw new FirebaseAuthError(
         AuthClientErrorCode.INVALID_ARGUMENT,
@@ -72,6 +87,7 @@ export class ProjectConfig {
     }
     const validKeys = {
       smsRegionConfig: true,
+      multiFactorConfig: true,
     }
     // Check for unsupported top level attributes.
     for (const key in request) {
@@ -86,6 +102,11 @@ export class ProjectConfig {
     if (typeof request.smsRegionConfig !== 'undefined') {
       SmsRegionsAuthConfig.validate(request.smsRegionConfig);
     }
+
+    // Validate Multi Factor Config if provided
+    if (typeof request.multiFactorConfig !== 'undefined') {
+      MultiFactorAuthConfig.validate(request.multiFactorConfig);
+    }
   }
 
   /**
@@ -97,7 +118,14 @@ export class ProjectConfig {
    */
   public static buildServerRequest(configOptions: UpdateProjectConfigRequest): ProjectConfigClientRequest {
     ProjectConfig.validate(configOptions);
-    return configOptions as ProjectConfigClientRequest;
+    const request = configOptions as any;
+    if (configOptions.multiFactorConfig !== undefined) {
+      request.mfa = MultiFactorAuthConfig.buildServerRequest(configOptions.multiFactorConfig);
+    }
+    /**Backend API returns "mfa" in case of project config and "mfaConfig" in case of tenant config.
+    The SDK exposes it as multiFactorConfig always.*/
+    delete request.multiFactorConfig;
+    return request as ProjectConfigClientRequest;
   }
 
   /**
@@ -111,6 +139,11 @@ export class ProjectConfig {
     if (typeof response.smsRegionConfig !== 'undefined') {
       this.smsRegionConfig = response.smsRegionConfig;
     }
+    /**Backend API returns "mfa" in case of project config and "mfaConfig" in case of tenant config. 
+    The SDK exposes it as multiFactorConfig always.*/
+    if (typeof response.mfa !== 'undefined') {
+      this.multiFactorConfig = new MultiFactorAuthConfig(response.mfa);
+    }
   }
   /**
    * Returns a JSON-serializable representation of this object.
@@ -121,10 +154,14 @@ export class ProjectConfig {
     // JSON serialization
     const json = {
       smsRegionConfig: deepCopy(this.smsRegionConfig),
+      multiFactorConfig: deepCopy(this.multiFactorConfig),
     };
     if (typeof json.smsRegionConfig === 'undefined') {
       delete json.smsRegionConfig;
     }
+    if (typeof json.multiFactorConfig === 'undefined') {
+      delete json.multiFactorConfig;
+    }
     return json;
   }
 }