From 7a98d44041b6d391a4de809e718318cc7c9cb8f3 Mon Sep 17 00:00:00 2001
From: Jude Kwashie <judekwashie70@gmail.com>
Date: Tue, 19 May 2026 14:12:12 +0000
Subject: [PATCH] docs(auth): clarify behavior of password reset email with
 email enumeration protection enabled

---
 docs/auth/manage-users.md                                 | 5 +++++
 .../firebase_auth/lib/src/firebase_auth.dart              | 7 ++++++-
 .../platform_interface_firebase_auth.dart                 | 8 ++++++--
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/docs/auth/manage-users.md b/docs/auth/manage-users.md
index 9584abf35454..5b52742175fa 100644
--- a/docs/auth/manage-users.md
+++ b/docs/auth/manage-users.md
@@ -162,6 +162,11 @@ await FirebaseAuth.instance
     .sendPasswordResetEmail(email: "user@example.com");
 ```
 
+Note: If
+[email enumeration protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
+is enabled for your Firebase project, `sendPasswordResetEmail()` may complete
+without throwing an error even when the email address is not registered. This is
+expected Firebase Auth behavior to prevent revealing whether an email exists.
 You can customize the email template that is used in Authentication section of
 the [Firebase console](https://console.firebase.google.com/), on the Email Templates page.
 See [Email Templates](https://support.google.com/firebase/answer/7000714) in
diff --git a/packages/firebase_auth/firebase_auth/lib/src/firebase_auth.dart b/packages/firebase_auth/firebase_auth/lib/src/firebase_auth.dart
index 109b31adba51..2f4ebe4258f4 100644
--- a/packages/firebase_auth/firebase_auth/lib/src/firebase_auth.dart
+++ b/packages/firebase_auth/firebase_auth/lib/src/firebase_auth.dart
@@ -297,6 +297,10 @@ class FirebaseAuth extends FirebasePluginPlatform implements FirebaseService {
   /// To complete the password reset, call [confirmPasswordReset] with the code supplied
   /// in the email sent to the user, along with the new password specified by the user.
   ///
+  /// If email enumeration protection is enabled for the Firebase project, this
+  /// method may complete successfully even when the email does not correspond
+  /// to an existing user.
+  ///
   /// May throw a [FirebaseAuthException] with the following error codes:
   ///
   /// - **auth/invalid-email**\
@@ -312,7 +316,8 @@ class FirebaseAuth extends FirebasePluginPlatform implements FirebaseService {
   /// - **auth/unauthorized-continue-uri**\
   ///   The domain of the continue URL is not whitelisted. Whitelist the domain in the Firebase console.
   /// - **auth/user-not-found**\
-  ///   Thrown if there is no user corresponding to the email address. Note: This exception is no longer thrown when enabling email enumeration protection.
+  ///   Thrown if there is no user corresponding to the email address. Note: This
+  ///   exception is not thrown when email enumeration protection is enabled.
   Future<void> sendPasswordResetEmail({
     required String email,
     ActionCodeSettings? actionCodeSettings,
diff --git a/packages/firebase_auth/firebase_auth_platform_interface/lib/src/platform_interface/platform_interface_firebase_auth.dart b/packages/firebase_auth/firebase_auth_platform_interface/lib/src/platform_interface/platform_interface_firebase_auth.dart
index ab9062fb57ba..60377db69238 100644
--- a/packages/firebase_auth/firebase_auth_platform_interface/lib/src/platform_interface/platform_interface_firebase_auth.dart
+++ b/packages/firebase_auth/firebase_auth_platform_interface/lib/src/platform_interface/platform_interface_firebase_auth.dart
@@ -313,8 +313,12 @@ abstract class FirebaseAuthPlatform extends PlatformInterface {
   }
 
   /// Triggers the Firebase Authentication backend to send a password-reset
-  /// email to the given email address, which must correspond to an existing
-  /// user of your app.
+  /// email to the given email address.
+  ///
+  /// If email enumeration protection is enabled for the Firebase project, this
+  /// method may complete successfully even when the email does not correspond
+  /// to an existing user. This prevents apps from using password reset requests
+  /// to discover registered email addresses.
   Future<void> sendPasswordResetEmail(
     String email, [
     ActionCodeSettings? actionCodeSettings,