docs(auth,functions): document all FirebaseAuthException and FirebaseFunctionsException codes

docs/auth/phone-auth.md

@@ -34,7 +34,7 @@ Before starting with Phone Authentication, ensure you have followed these steps:
 **Note**; Phone number sign-in is only available for use on real devices and the web. To test your authentication flow on device emulators,
 please see [Testing](#testing).
 
-## iOS: reCAPTCHA SDK and Identity Platform
+## iOS: reCAPTCHA SDK and Identity Platform {:#ios-recaptcha-sdk-and-identity-platform}
 
 On **iOS**, phone sign-in can fail with `FirebaseAuthException` code **`recaptcha-sdk-not-linked`** (for example: *The reCAPTCHA SDK is not linked to your app*).
 That error is raised by the **native Firebase iOS Auth** SDK when your Firebase / **Identity Platform** configuration expects **reCAPTCHA Enterprise**

packages/cloud_functions/cloud_functions_platform_interface/lib/src/firebase_functions_exception.dart

@@ -8,6 +8,53 @@ import 'package:meta/meta.dart';
 
 /// Generic exception related to Cloud Functions. Check the error code
 /// and message for more details.
+///
+/// [code] is one of the following strings:
+///
+/// - **cancelled**: The operation was cancelled (typically by the caller).
+/// - **unknown**: Unknown error or an error from a different error domain.
+/// - **invalid-argument**: The client specified an invalid argument. Unlike
+///   `failed-precondition`, this indicates arguments that are problematic
+///   regardless of the state of the system.
+/// - **deadline-exceeded**: The deadline expired before the operation could
+///   complete, for example because the call exceeded
+///   `HttpsCallableOptions.timeout`. For operations that change the state of
+///   the system, this may be returned even if the operation completed.
+/// - **not-found**: A requested resource was not found. On Android and Apple
+///   platforms, this is also the code when the function does not exist, for
+///   example because of a wrong name or region.
+/// - **already-exists**: A resource that the function attempted to create
+///   already exists.
+/// - **permission-denied**: The caller does not have permission to execute
+///   the operation.
+/// - **resource-exhausted**: A resource has been exhausted, such as a
+///   per-user quota.
+/// - **failed-precondition**: The operation was rejected because the system
+///   is not in a state required for its execution.
+/// - **aborted**: The operation was aborted, typically due to a concurrency
+///   issue such as a transaction abort.
+/// - **out-of-range**: The operation was attempted past the valid range.
+/// - **unimplemented**: The operation is not implemented, or not supported or
+///   enabled.
+/// - **internal**: An internal error. This is also the code when the function
+///   throws an error that is not an `HttpsError`. On web, network and CORS
+///   failures, including calling a function that does not exist, are reported
+///   with this code.
+/// - **unavailable**: The service is currently unavailable. This is usually
+///   transient and can be retried with a backoff. On Android, network errors
+///   are reported with this code. On Apple platforms they are reported as
+///   `unknown`.
+/// - **data-loss**: Unrecoverable data loss or corruption.
+/// - **unauthenticated**: The request does not have valid authentication
+///   credentials for the operation.
+///
+/// When a callable function throws an `HttpsError`, [code] is the error's
+/// code, [message] its message and [details] its details. See
+/// [Handle errors](https://firebase.google.com/docs/functions/callable#handle-errors-client).
+///
+/// Errors from `HttpsCallable.stream` are reported with these codes on web
+/// only. On Apple platforms, stream errors have the code `unknown`. On
+/// Android, a stream that fails ends without an error.
 class FirebaseFunctionsException extends FirebaseException
     implements Exception {
   // ignore: public_member_api_docs

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

@@ -230,9 +230,6 @@ class FirebaseAuth extends FirebasePlugin implements FirebaseService {
   /// - **network-request-failed**:
   ///  - Thrown if there was a network request error, for example the user
   ///    doesn't have internet connection
-  /// - **operation-not-allowed**:
-  ///  - Thrown if email/password accounts are not enabled. Enable
-  ///    email/password accounts in the Firebase Console, under the Auth tab.
   Future<UserCredential> createUserWithEmailAndPassword({
     required String email,
     required String password,
@@ -303,19 +300,19 @@ class FirebaseAuth extends FirebasePlugin implements FirebaseService {
   ///
   /// May throw a [FirebaseAuthException] with the following error codes:
   ///
-  /// - **auth/invalid-email**\
+  /// - **invalid-email**\
   ///   Thrown if the email address is not valid.
-  /// - **auth/missing-android-pkg-name**\
+  /// - **missing-android-pkg-name**\
   ///   An Android package name must be provided if the Android app is required to be installed.
-  /// - **auth/missing-continue-uri**\
+  /// - **missing-continue-uri**\
   ///   A continue URL must be provided in the request.
-  /// - **auth/missing-ios-bundle-id**\
+  /// - **missing-ios-bundle-id**\
   ///   An iOS Bundle ID must be provided if an App Store ID is provided.
-  /// - **auth/invalid-continue-uri**\
+  /// - **invalid-continue-uri**\
   ///   The continue URL provided in the request is invalid.
-  /// - **auth/unauthorized-continue-uri**\
+  /// - **unauthorized-continue-uri**\
   ///   The domain of the continue URL is not whitelisted. Whitelist the domain in the Firebase console.
-  /// - **auth/user-not-found**\
+  /// - **user-not-found**\
   ///   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({
@@ -327,9 +324,8 @@ class FirebaseAuth extends FirebasePlugin implements FirebaseService {
 
   /// Sends a sign in with email link to provided email address.
   ///
-  /// 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.
+  /// To complete the sign-in, call [signInWithEmailLink] with the email
+  /// address and the link supplied in the email sent to the user.
   ///
   /// The [handleCodeInApp] of [actionCodeSettings] must be set to `true`
   /// otherwise an [ArgumentError] will be thrown.
@@ -585,8 +581,8 @@ class FirebaseAuth extends FirebasePlugin implements FirebaseService {
   ///    [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**.
+  ///    whether an account exists. Older versions of the native SDKs
+  ///    reported **invalid-login-credentials** instead.
   /// - **operation-not-allowed**:
   ///  - Thrown if email/password accounts are not enabled. Enable
   ///    email/password accounts in the Firebase Console, under the Auth tab.
@@ -853,8 +849,8 @@ class FirebaseAuth extends FirebasePlugin implements FirebaseService {
   /// 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.
   ///
-  /// Returns a map with the following keys:
-  /// - **status**: A boolean indicating if the password is valid.
+  /// Returns a [PasswordValidationStatus] with the following fields:
+  /// - **isValid**: A boolean indicating if the password is valid.
   /// - **passwordPolicy**: The password policy used to validate the password.
   /// - **meetsMinPasswordLength**: A boolean indicating if the password meets the minimum length requirement.
   /// - **meetsMaxPasswordLength**: A boolean indicating if the password meets the maximum length requirement.
@@ -865,18 +861,10 @@ class FirebaseAuth extends FirebasePlugin implements FirebaseService {
   ///
   /// A [FirebaseAuthException] maybe thrown with the following error code:
   /// - **invalid-password**:
-  ///  - Thrown if the password is invalid.
-  /// - **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
-  /// - **operation-not-allowed**:
-  ///  - Thrown if email/password accounts are not enabled. Enable
-  ///    email/password accounts in the Firebase Console, under the Auth tab.
+  ///  - Thrown if the password is `null` or empty.
+  ///
+  /// An [Exception] is thrown if the password policy cannot be fetched, for
+  /// example because of a network error.
   Future<PasswordValidationStatus> validatePassword(
     FirebaseAuth auth,
     String? password,

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

@@ -163,20 +163,16 @@ class User {
   ///    user, an `email` and `credential` ([AuthCredential]) fields are also
   ///    provided. You have to link the credential to the existing user with
   ///    that email if you wish to continue signing in with that credential. To
-  ///    do so, sign in to `email` via one of
-  ///    the providers returned and then [User.linkWithCredential] the original
-  ///    credential to that newly signed in user.
+  ///    do so, sign in to `email` with the provider the account already uses
+  ///    and then [User.linkWithCredential] the original credential to that
+  ///    newly signed in user.
   /// - **operation-not-allowed**:
   ///  - Thrown if you have not enabled the provider in the Firebase Console. Go
   ///    to the Firebase Console for your project, in the Auth section and the
   ///    Sign in Method tab and configure the provider.
   /// - **invalid-email**:
   ///  - Thrown if the email used in a [EmailAuthProvider.credential] is
   ///    invalid.
-  /// - **invalid-email**:
-  ///  - Thrown if the password used in a [EmailAuthProvider.credential] is not
-  ///    correct or when the user associated with the email does not have a
-  ///    password.
   /// - **invalid-verification-code**:
   ///  - Thrown if the credential is a [PhoneAuthProvider.credential] and the
   ///    verification code of the credential is not valid.

packages/firebase_auth/firebase_auth_platform_interface/lib/src/firebase_auth_exception.dart

@@ -9,6 +9,16 @@ import 'auth_credential.dart';
 
 /// Generic exception related to Firebase Authentication. Check the error code
 /// and message for more details.
+///
+/// [code] is a lowercase, hyphen-separated string such as `invalid-email` or
+/// `network-request-failed`, without an `auth/` or `ERROR_` prefix. The set of
+/// codes depends on the platform, because most codes come from the native
+/// Firebase SDK. See
+/// [Error Handling](https://firebase.google.com/docs/auth/flutter/errors) for
+/// the list of codes and the platforms that throw them.
+///
+/// When a user must complete a second factor to sign in, the subclass
+/// `FirebaseAuthMultiFactorException` is thrown.
 class FirebaseAuthException extends FirebaseException implements Exception {
   // ignore: public_member_api_docs
   @protected

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

@@ -241,9 +241,6 @@ 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
-  /// - **operation-not-allowed**:
-  ///  - Thrown if email/password accounts are not enabled. Enable
-  ///    email/password accounts in the Firebase Console, under the Auth tab.
   Future<UserCredentialPlatform> createUserWithEmailAndPassword(
     String email,
     String password,
@@ -555,8 +552,8 @@ abstract class FirebaseAuthPlatform extends PlatformInterface {
   ///    [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**.
+  ///    whether an account exists. Older versions of the native SDKs
+  ///    reported **invalid-login-credentials** instead.
   /// - **operation-not-allowed**:
   ///  - Thrown if email/password accounts are not enabled. Enable
   ///    email/password accounts in the Firebase Console, under the Auth tab.