fix(auth): Better type hierarchies for Auth API (#1294)

* fix(auth): Better type heirarchies for Auth API * fix: Moved factorId back to the base types * fix: Updated API report * fix: Fixed a grammar error in comment * fix: Update to comment text

Author: hiranya911

etc/firebase-admin.api.md

@@ -113,11 +113,7 @@ export namespace auth {
  tenantManager(): TenantManager;
  }
  export type AuthFactorType = 'phone';
- export interface AuthProviderConfig {
- displayName?: string;
- enabled: boolean;
- providerId: string;
- }
+ export type AuthProviderConfig = SAMLAuthProviderConfig | OIDCAuthProviderConfig;
  export interface AuthProviderConfigFilter {
  maxResults?: number;
  pageToken?: string;
@@ -151,11 +147,23 @@ export namespace auth {
  verifyIdToken(idToken: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
  verifySessionCookie(sessionCookie: string, checkForRevocation?: boolean): Promise<DecodedIdToken>;
  }
- export interface CreateMultiFactorInfoRequest {
+ export interface BaseAuthProviderConfig {
+ displayName?: string;
+ enabled: boolean;
+ providerId: string;
+ }
+ export interface BaseCreateMultiFactorInfoRequest {
+ displayName?: string;
+ factorId: string;
+ }
+ export interface BaseUpdateMultiFactorInfoRequest {
  displayName?: string;
+ enrollmentTime?: string;
  factorId: string;
+ uid?: string;
  }
- export interface CreatePhoneMultiFactorInfoRequest extends CreateMultiFactorInfoRequest {
+ export type CreateMultiFactorInfoRequest = CreatePhoneMultiFactorInfoRequest;
+ export interface CreatePhoneMultiFactorInfoRequest extends BaseCreateMultiFactorInfoRequest {
  phoneNumber: string;
  }
  export interface CreateRequest extends UpdateRequest {
@@ -245,7 +253,7 @@ export namespace auth {
  code?: boolean;
  idToken?: boolean;
  }
- export interface OIDCAuthProviderConfig extends AuthProviderConfig {
+ export interface OIDCAuthProviderConfig extends BaseAuthProviderConfig {
  clientId: string;
  clientSecret?: string;
  issuer: string;
@@ -272,7 +280,7 @@ export namespace auth {
  // (undocumented)
  providerUid: string;
  }
- export interface SAMLAuthProviderConfig extends AuthProviderConfig {
+ export interface SAMLAuthProviderConfig extends BaseAuthProviderConfig {
  callbackURL?: string;
  idpEntityId: string;
  rpEntityId: string;
@@ -323,13 +331,8 @@ export namespace auth {
  }
  // (undocumented)
  export type UpdateAuthProviderRequest = SAMLUpdateAuthProviderRequest | OIDCUpdateAuthProviderRequest;
- export interface UpdateMultiFactorInfoRequest {
- displayName?: string;
- enrollmentTime?: string;
- factorId: string;
- uid?: string;
- }
- export interface UpdatePhoneMultiFactorInfoRequest extends UpdateMultiFactorInfoRequest {
+ export type UpdateMultiFactorInfoRequest = UpdatePhoneMultiFactorInfoRequest;
+ export interface UpdatePhoneMultiFactorInfoRequest extends BaseUpdateMultiFactorInfoRequest {
  phoneNumber: string;
  }
  export interface UpdateRequest {

src/auth/auth-api-request.ts

@@ -1480,7 +1480,12 @@ export abstract class AbstractAuthRequestHandler {
  }
 
  // Build the signupNewUser request.
- const request: any = deepCopy(properties);
+ type SignUpNewUserRequest = CreateRequest & {
+ photoUrl?: string | null;
+ localId?: string;
+ mfaInfo?: AuthFactorInfo[];
+ };
+ const request: SignUpNewUserRequest = deepCopy(properties);
  // Rewrite photoURL to photoUrl.
  if (typeof request.photoURL !== 'undefined') {
  request.photoUrl = request.photoURL;
@@ -1496,14 +1501,14 @@ export abstract class AbstractAuthRequestHandler {
  if (validator.isNonEmptyArray(request.multiFactor.enrolledFactors)) {
  const mfaInfo: AuthFactorInfo[] = [];
  try {
- request.multiFactor.enrolledFactors.forEach((multiFactorInfo: any) => {
+ request.multiFactor.enrolledFactors.forEach((multiFactorInfo) => {
  // Enrollment time and uid are not allowed for signupNewUser endpoint.
  // They will automatically be provisioned server side.
- if (multiFactorInfo.enrollmentTime) {
+ if ('enrollmentTime' in multiFactorInfo) {
  throw new FirebaseAuthError(
  AuthClientErrorCode.INVALID_ARGUMENT,
  '"enrollmentTime" is not supported when adding second factors via "createUser()"');
- } else if (multiFactorInfo.uid) {
+ } else if ('uid' in multiFactorInfo) {
  throw new FirebaseAuthError(
  AuthClientErrorCode.INVALID_ARGUMENT,
  '"uid" is not supported when adding second factors via "createUser()"');

src/auth/index.ts

@@ -112,7 +112,7 @@ export namespace auth {
  }
 
  /**
- * Interface representing the common properties of a user enrolled second factor.
+ * Interface representing the common properties of a user-enrolled second factor.
  */
  export interface MultiFactorInfo {
 
@@ -143,7 +143,7 @@ export namespace auth {
  }
 
  /**
- * Interface representing a phone specific user enrolled second factor.
+ * Interface representing a phone specific user-enrolled second factor.
  */
  export interface PhoneMultiFactorInfo extends MultiFactorInfo {
 
@@ -336,10 +336,10 @@ export namespace auth {
  }
 
  /**
- * Interface representing common properties of a user enrolled second factor
+ * Interface representing common properties of a user-enrolled second factor
  * for an `UpdateRequest`.
  */
- export interface UpdateMultiFactorInfoRequest {
+ export interface BaseUpdateMultiFactorInfoRequest {
 
  /**
  * The ID of the enrolled second factor. This ID is unique to the user. When not provided,
@@ -364,17 +364,23 @@ export namespace auth {
  }
 
  /**
- * Interface representing a phone specific user enrolled second factor
+ * Interface representing a phone specific user-enrolled second factor
  * for an `UpdateRequest`.
  */
- export interface UpdatePhoneMultiFactorInfoRequest extends UpdateMultiFactorInfoRequest {
+ export interface UpdatePhoneMultiFactorInfoRequest extends BaseUpdateMultiFactorInfoRequest {
 
  /**
  * The phone number associated with a phone second factor.
  */
  phoneNumber: string;
  }
 
+ /**
+ * Type representing the properties of a user-enrolled second factor
+ * for an `UpdateRequest`.
+ */
+ export type UpdateMultiFactorInfoRequest = | UpdatePhoneMultiFactorInfoRequest;
+
  /**
  * Interface representing the properties to update on the provided user.
  */
@@ -443,10 +449,10 @@ export namespace auth {
  }
 
  /**
- * Interface representing base properties of a user enrolled second factor for a
+ * Interface representing base properties of a user-enrolled second factor for a
  * `CreateRequest`.
  */
- export interface CreateMultiFactorInfoRequest {
+ export interface BaseCreateMultiFactorInfoRequest {
 
  /**
  * The optional display name for an enrolled second factor.
@@ -460,17 +466,23 @@ export namespace auth {
  }
 
  /**
- * Interface representing a phone specific user enrolled second factor for a
+ * Interface representing a phone specific user-enrolled second factor for a
  * `CreateRequest`.
  */
- export interface CreatePhoneMultiFactorInfoRequest extends CreateMultiFactorInfoRequest {
+ export interface CreatePhoneMultiFactorInfoRequest extends BaseCreateMultiFactorInfoRequest {
 
  /**
  * The phone number associated with a phone second factor.
  */
  phoneNumber: string;
  }
 
+ /**
+ * Type representing the properties of a user-enrolled second factor
+ * for a `CreateRequest`.
+ */
+ export type CreateMultiFactorInfoRequest = | CreatePhoneMultiFactorInfoRequest;
+
  /**
  * Interface representing the properties to set on a new user record to be
  * created.
@@ -1221,7 +1233,7 @@ export namespace auth {
  /**
  * The base Auth provider configuration interface.
  */
- export interface AuthProviderConfig {
+ export interface BaseAuthProviderConfig {
 
  /**
  * The provider ID defined by the developer.
@@ -1249,7 +1261,7 @@ export namespace auth {
  * Auth provider configuration interface. A SAML provider can be created via
  * {@link auth.Auth.createProviderConfig `createProviderConfig()`}.
  */
- export interface SAMLAuthProviderConfig extends AuthProviderConfig {
+ export interface SAMLAuthProviderConfig extends BaseAuthProviderConfig {
 
  /**
  * The SAML IdP entity identifier.
@@ -1301,7 +1313,7 @@ export namespace auth {
  export interface OAuthResponseType {
  /**
  * Whether ID token is returned from IdP's authorization endpoint.
- */ 
+ */
  idToken?: boolean;
 
  /**
@@ -1315,7 +1327,7 @@ export namespace auth {
  * provider configuration interface. An OIDC provider can be created via
  * {@link auth.Auth.createProviderConfig `createProviderConfig()`}.
  */
- export interface OIDCAuthProviderConfig extends AuthProviderConfig {
+ export interface OIDCAuthProviderConfig extends BaseAuthProviderConfig {
 
  /**
  * This is the required client ID used to confirm the audience of an OIDC
@@ -1347,13 +1359,19 @@ export namespace auth {
  * The OIDC provider's client secret to enable OIDC code flow.
  */
  clientSecret?: string;
- 
+
  /**
  * The OIDC provider's response object for OAuth authorization flow.
  */
  responseType?: OAuthResponseType;
  }
 
+ /**
+ * The Auth provider configuration type.
+ * {@link auth.Auth.createProviderConfig `createProviderConfig()`}.
+ */
+ export type AuthProviderConfig = SAMLAuthProviderConfig | OIDCAuthProviderConfig;
+
  /**
  * The request interface for updating a SAML Auth provider. This is used
  * when updating a SAML provider's configuration via
@@ -1440,7 +1458,7 @@ export namespace auth {
  * If not provided, the existing configuration's value is not modified.
  */
  clientSecret?: string;
- 
+
  /**
  * The OIDC provider's response object for OAuth authorization flow.
  */

test/unit/auth/auth-api-request.spec.ts

@@ -1425,12 +1425,6 @@ AUTH_REQUEST_HANDLER_TESTS.forEach((handler) => {
  factorId: 'phone',
  enrollmentTime: new Date().toUTCString(),
  },
- {
- uid: 'mfaUid2',
- phoneNumber: '+16505550002',
- displayName: 'Personal phone number',
- factorId: 'phone',
- },
  ],
  },
  customClaims: { admin: true },