docs(auth): clarify fetchSignInMethodsForEmail behavior with email enumeration protection (#8518)

* docs(auth): clarify fetchSignInMethodsForEmail behavior with email enumeration protection

This update enhances the JSDoc comment for fetchSignInMethodsForEmail by explaining its behavior when "Email Enumeration Protection" is enabled in Firebase Authentication settings (which is the default). It notes that the method may return an empty array even for existing accounts when called from an unauthenticated context. This clarification aims to prevent confusion and potential misuse that could lead to security vulnerabilities.

Author: No898

packages/auth/lib/index.d.ts

@@ -2096,18 +2096,27 @@ export namespace FirebaseAuthTypes {
     /**
      * Returns a list of authentication methods that can be used to sign in a given user (identified by its main email address).
      *
+     * ⚠️ Note:
+     * If "Email Enumeration Protection" is enabled in your Firebase Authentication settings (which is the default),
+     * this method may return an empty array even if the email is registered, especially when called from an unauthenticated context.
+     *
+     * This is a security measure to prevent leaking account existence via email enumeration attacks.
+     * Do not use the result of this method to directly inform the user whether an email is registered.
+     *
      * #### Example
      *
      * ```js
      * const methods = await firebase.auth().fetchSignInMethodsForEmail('[email protected]');
      *
-     * methods.forEach((method) => {
-     *   console.log(method);
-     * });
+     * if (methods.length > 0) {
+     *   // Likely a registered user — offer sign-in
+     * } else {
+     *   // Could be unregistered OR email enumeration protection is active — offer registration
+     * }
      * ```
      *
      * @error auth/invalid-email Thrown if the email address is not valid.
-     * @param email The users email address.
+     * @param email The user's email address.
      */
     fetchSignInMethodsForEmail(email: string): Promise<string[]>;