Define validatePassword endpoint for public API (#7409)

* Add validatePassword method with implementation TODO

Author: ch5zzy

common/api-review/auth.api.md

@@ -893,6 +893,9 @@ export interface UserMetadata {
 // @public
 export type UserProfile = Record<string, unknown>;
 
+// @public
+export function validatePassword(auth: Auth, password: string): Promise<PasswordValidationStatus>;
+
 // @public
 export function verifyBeforeUpdateEmail(user: User, newEmail: string, actionCodeSettings?: ActionCodeSettings | null): Promise<void>;
 

docs-devsite/auth.md

@@ -49,6 +49,7 @@ Firebase Authentication
 |  [signOut(auth)](./auth.md#signout) | Signs out the current user. |
 |  [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. |
 |  [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. |
+|  [validatePassword(auth, password)](./auth.md#validatepassword) | Validates the password against the password policy configured for the project or tenant. |
 |  [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. |
 |  <b>function(link...)</b> |
 |  [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. |
@@ -1080,6 +1081,39 @@ export declare function useDeviceLanguage(auth: Auth): void;
 
 void
 
+## validatePassword()
+
+Validates the password against the password policy configured for the project or tenant.
+
+If no tenant ID is set on the `Auth` instance, then this method will use the password policy configured for the project. Otherwise, this method will use the policy configured for the tenant. If a password policy has not been configured, then the default policy configured for all projects will be used.
+
+If an auth flow fails because a submitted password does not meet the password policy requirements and this method has previously been called, then this method will use the most recent policy available when called again.
+
+<b>Signature:</b>
+
+```typescript
+export declare function validatePassword(auth: Auth, password: string): Promise<PasswordValidationStatus>;
+```
+
+### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. |
+|  password | string | The password to validate. |
+
+<b>Returns:</b>
+
+Promise&lt;[PasswordValidationStatus](./auth.passwordvalidationstatus.md#passwordvalidationstatus_interface)<!-- -->&gt;
+
+### Example
+
+
+```javascript
+validatePassword(auth, 'some-password');
+
+```
+
 ## verifyPasswordResetCode()
 
 Checks a password reset code sent to the user by email or other out-of-band mechanism.

packages/auth/src/core/auth/auth_impl.ts

@@ -32,7 +32,8 @@ import {
   ErrorFn,
   NextFn,
   Unsubscribe,
-  PasswordPolicy
+  PasswordPolicy,
+  PasswordValidationStatus
 } from '../../model/public_types';
 import {
   createSubscribe,
@@ -427,6 +428,11 @@ export class AuthImpl implements AuthInternal, _FirebaseService {
     }
   }
 
+  async validatePassword(password: string): Promise<PasswordValidationStatus> {
+    // TODO(chazzy): Implement.
+    return Promise.reject(password);
+  }
+
   _getPasswordPolicy(): PasswordPolicy | null {
     if (this.tenantId === null) {
       return this._projectPasswordPolicy;

packages/auth/src/core/index.ts

@@ -23,7 +23,8 @@ import {
   User,
   CompleteFn,
   ErrorFn,
-  Unsubscribe
+  Unsubscribe,
+  PasswordValidationStatus
 } from '../model/public_types';
 import { _castAuth } from '../core/auth/auth_impl';
 
@@ -96,6 +97,37 @@ export function initializeRecaptchaConfig(auth: Auth): Promise<void> {
   return authInternal.initializeRecaptchaConfig();
 }
 
+/**
+ * Validates the password against the password policy configured for the project or tenant.
+ *
+ * @remarks
+ * If no tenant ID is set on the `Auth` instance, then this method will use the password
+ * policy configured for the project. Otherwise, this method will use the policy configured
+ * for the tenant. If a password policy has not been configured, then the default policy
+ * configured for all projects will be used.
+ *
+ * If an auth flow fails because a submitted password does not meet the password policy
+ * requirements and this method has previously been called, then this method will use the
+ * most recent policy available when called again.
+ *
+ * @example
+ * ```javascript
+ * validatePassword(auth, 'some-password');
+ * ```
+ *
+ * @param auth The {@link Auth} instance.
+ * @param password The password to validate.
+ *
+ * @public
+ */
+export async function validatePassword(
+  auth: Auth,
+  password: string
+): Promise<PasswordValidationStatus> {
+  const authInternal = _castAuth(auth);
+  return authInternal.validatePassword(password);
+}
+
 /**
  * Adds an observer for changes to the signed-in user's ID token.
  *

packages/auth/src/model/auth.ts

@@ -21,6 +21,7 @@ import {
   Config,
   EmulatorConfig,
   PasswordPolicy,
+  PasswordValidationStatus,
   PopupRedirectResolver,
   User
 } from './public_types';
@@ -103,4 +104,5 @@ export interface AuthInternal extends Auth {
   useDeviceLanguage(): void;
   signOut(): Promise<void>;
   initializeRecaptchaConfig(): Promise<void>;
+  validatePassword(password: string): Promise<PasswordValidationStatus>;
 }