docs(auth): add documentation about errors code when Email Enumeration Protection is activated

docs/auth/password-auth.md

@@ -73,14 +73,28 @@ try {
     password: password
   );
 } on FirebaseAuthException catch (e) {
-  if (e.code == 'user-not-found') {
+  if (e.code == 'invalid-credential') {
+    // Email or password is incorrect. Projects with email enumeration
+    // protection enabled (the default since September 2023) return this
+    // code instead of 'user-not-found' or 'wrong-password'.
+    print('Invalid email or password.');
+  } else if (e.code == 'user-not-found') {
+    // Only returned when email enumeration protection is disabled.
     print('No user found for that email.');
   } else if (e.code == 'wrong-password') {
+    // Only returned when email enumeration protection is disabled.
     print('Wrong password provided for that user.');
   }
 }
 ```
 
+Note: Since September 2023, Firebase enables
+[email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+by default on new projects. With this feature enabled, `user-not-found` and
+`wrong-password` error codes are replaced by `invalid-credential` to prevent
+revealing whether an email address is registered. You can manage this setting in
+the Firebase console under **Authentication > Settings**.
+
 Caution: When a user uninstalls your app on iOS or macOS, the user's authentication
 state can persist between app re-installs, as the Firebase iOS SDK persists
 authentication state to the system keychain.

packages/firebase_auth/firebase_auth/lib/src/firebase_auth.dart

@@ -535,11 +535,19 @@ class FirebaseAuth extends FirebasePluginPlatform {
   ///  - Thrown if the email address is not valid.
   /// - **user-disabled**:
   ///  - Thrown if the user corresponding to the given email has been disabled.
-  /// - **user-not-found**:
+  /// - **user-not-found** _(deprecated)_:
   ///  - Thrown if there is no user corresponding to the given email.
-  /// - **wrong-password**:
+  ///    **Note:** This code is no longer returned on projects that have
+  ///    [email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+  ///    enabled (the default for new projects since September 2023).
+  ///    Use **invalid-credential** instead.
+  /// - **wrong-password** _(deprecated)_:
   ///  - Thrown if the password is invalid for the given email, or the account
   ///    corresponding to the email does not have a password set.
+  ///    **Note:** This code is no longer returned on projects that have
+  ///    [email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+  ///    enabled (the default for new projects since September 2023).
+  ///    Use **invalid-credential** instead.
   /// - **too-many-requests**:
   ///  - Thrown if the user sent too many requests at the same time, for security
   ///     the api will not allow too many attempts at the same time, user will have
@@ -550,11 +558,13 @@ class FirebaseAuth extends FirebasePluginPlatform {
   /// - **network-request-failed**:
   ///  - Thrown if there was a network request error, for example the user
   ///    doesn't have internet connection
-  /// - **INVALID_LOGIN_CREDENTIALS** or **invalid-credential**:
-  ///  - Thrown if the password is invalid for the given email, or the account
-  ///    corresponding to the email does not have a password set.
-  ///    Depending on if you are using firebase emulator or not the code is
-  ///    different
+  /// - **invalid-credential**:
+  ///  - Thrown if the email or password is incorrect. On projects with
+  ///    [email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+  ///    enabled (the default since September 2023), this replaces
+  ///    **user-not-found** and **wrong-password** to prevent revealing
+  ///    whether an account exists. On the Firebase emulator, the code may
+  ///    appear as **INVALID_LOGIN_CREDENTIALS**.
   /// - **operation-not-allowed**:
   ///  - Thrown if email/password accounts are not enabled. Enable
   ///    email/password accounts in the Firebase Console, under the Auth tab.

packages/firebase_auth/firebase_auth_platform_interface/lib/src/platform_interface/platform_interface_firebase_auth.dart

@@ -514,11 +514,19 @@ abstract class FirebaseAuthPlatform extends PlatformInterface {
   ///  - Thrown if the email address is not valid.
   /// - **user-disabled**:
   ///  - Thrown if the user corresponding to the given email has been disabled.
-  /// - **user-not-found**:
+  /// - **user-not-found** _(deprecated)_:
   ///  - Thrown if there is no user corresponding to the given email.
-  /// - **wrong-password**:
+  ///    **Note:** This code is no longer returned on projects that have
+  ///    [email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+  ///    enabled (the default for new projects since September 2023).
+  ///    Use **invalid-credential** instead.
+  /// - **wrong-password** _(deprecated)_:
   ///  - Thrown if the password is invalid for the given email, or the account
   ///    corresponding to the email does not have a password set.
+  ///    **Note:** This code is no longer returned on projects that have
+  ///    [email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+  ///    enabled (the default for new projects since September 2023).
+  ///    Use **invalid-credential** instead.
   /// - **too-many-requests**:
   ///  - Thrown if the user sent too many requests at the same time, for security
   ///     the api will not allow too many attempts at the same time, user will have
@@ -529,11 +537,13 @@ abstract class FirebaseAuthPlatform extends PlatformInterface {
   /// - **network-request-failed**:
   ///  - Thrown if there was a network request error, for example the user
   ///    doesn't have internet connection
-  /// - **INVALID_LOGIN_CREDENTIALS** or **invalid-credential**:
-  ///  - Thrown if the password is invalid for the given email, or the account
-  ///    corresponding to the email does not have a password set.
-  ///    Depending on if you are using firebase emulator or not the code is
-  ///    different
+  /// - **invalid-credential**:
+  ///  - Thrown if the email or password is incorrect. On projects with
+  ///    [email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+  ///    enabled (the default since September 2023), this replaces
+  ///    **user-not-found** and **wrong-password** to prevent revealing
+  ///    whether an account exists. On the Firebase emulator, the code may
+  ///    appear as **INVALID_LOGIN_CREDENTIALS**.
   /// - **operation-not-allowed**:
   ///  - Thrown if email/password accounts are not enabled. Enable
   ///    email/password accounts in the Firebase Console, under the Auth tab.