feat: P3 — Phone Provider Integration

Author: demolaf

auth/src/main/java/com/firebase/ui/auth/compose/AuthState.kt

@@ -20,6 +20,8 @@ import com.google.firebase.auth.AuthCredential
 import com.google.firebase.auth.AuthResult
 import com.google.firebase.auth.FirebaseUser
 import com.google.firebase.auth.MultiFactorResolver
+import com.google.firebase.auth.PhoneAuthCredential
+import com.google.firebase.auth.PhoneAuthProvider
 
 /**
  * Represents the authentication state in Firebase Auth UI.
@@ -252,6 +254,74 @@ abstract class AuthState private constructor() {
         override fun toString(): String = "AuthState.EmailSignInLinkSent"
     }
 
+    /**
+     * Phone number was automatically verified via SMS instant verification.
+     *
+     * This state is emitted when Firebase Phone Authentication successfully retrieves
+     * and verifies the SMS code automatically without user interaction. This happens
+     * when Google Play services can detect the incoming SMS message.
+     *
+     * @property credential The [PhoneAuthCredential] that can be used to sign in the user
+     *
+     * @see PhoneNumberVerificationRequired for the manual verification flow
+     */
+    class SMSAutoVerified(val credential: PhoneAuthCredential) : AuthState() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is SMSAutoVerified) return false
+            return credential == other.credential
+        }
+
+        override fun hashCode(): Int {
+            var result = credential.hashCode()
+            result = 31 * result + credential.hashCode()
+            return result
+        }
+
+        override fun toString(): String =
+            "AuthState.SMSAutoVerified(credential=$credential)"
+    }
+
+    /**
+     * Phone number verification requires manual code entry.
+     *
+     * This state is emitted when Firebase Phone Authentication cannot instantly verify
+     * the phone number and sends an SMS code that the user must manually enter. This is
+     * the normal flow when automatic SMS retrieval is not available or fails.
+     *
+     * **Resending codes:**
+     * To allow users to resend the verification code (if they didn't receive it),
+     * call [FirebaseAuthUI.verifyPhoneNumber] again with:
+     * - `isForceResendingTokenEnabled = true`
+     * - `forceResendingToken` from this state
+     *
+     * @property verificationId The verification ID to use when submitting the code.
+     *                          This must be passed to [FirebaseAuthUI.submitVerificationCode].
+     * @property forceResendingToken Token that can be used to resend the SMS code if needed
+     *
+     */
+    class PhoneNumberVerificationRequired(
+        val verificationId: String,
+        val forceResendingToken: PhoneAuthProvider.ForceResendingToken,
+    ) : AuthState() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is PhoneNumberVerificationRequired) return false
+            return verificationId == other.verificationId &&
+                    forceResendingToken == other.forceResendingToken
+        }
+
+        override fun hashCode(): Int {
+            var result = verificationId.hashCode()
+            result = 31 * result + forceResendingToken.hashCode()
+            return result
+        }
+
+        override fun toString(): String =
+            "AuthState.PhoneNumberVerificationRequired(verificationId=$verificationId, " +
+                    "forceResendingToken=$forceResendingToken)"
+    }
+
     companion object {
         /**
          * Creates an Idle state instance.

auth/src/main/java/com/firebase/ui/auth/compose/configuration/auth_provider/AuthProvider.kt

@@ -28,17 +28,25 @@ import com.firebase.ui.auth.util.Preconditions
 import com.firebase.ui.auth.util.data.ContinueUrlBuilder
 import com.firebase.ui.auth.util.data.PhoneNumberUtils
 import com.firebase.ui.auth.util.data.ProviderAvailability
+import com.google.firebase.FirebaseException
 import com.google.firebase.auth.ActionCodeSettings
 import com.google.firebase.auth.EmailAuthProvider
 import com.google.firebase.auth.FacebookAuthProvider
 import com.google.firebase.auth.FirebaseAuth
 import com.google.firebase.auth.GithubAuthProvider
 import com.google.firebase.auth.GoogleAuthProvider
+import com.google.firebase.auth.MultiFactorSession
+import com.google.firebase.auth.PhoneAuthCredential
+import com.google.firebase.auth.PhoneAuthOptions
 import com.google.firebase.auth.PhoneAuthProvider
 import com.google.firebase.auth.TwitterAuthProvider
 import com.google.firebase.auth.UserProfileChangeRequest
 import com.google.firebase.auth.actionCodeSettings
 import kotlinx.coroutines.tasks.await
+import java.util.concurrent.TimeUnit
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+import kotlin.coroutines.suspendCoroutine
 
 @AuthUIConfigurationDsl
 class AuthProvidersBuilder {
@@ -202,9 +210,7 @@ abstract class AuthProvider(open val providerId: String) {
             val KEY_IDP_SECRET = stringPreferencesKey("com.firebase.ui.auth.data.client.idpSecret")
         }
 
-        internal fun validate(
-            isAnonymousUpgradeEnabled: Boolean = false
-        ) {
+        internal fun validate(isAnonymousUpgradeEnabled: Boolean = false) {
             if (isEmailLinkSignInEnabled) {
                 val actionCodeSettings = requireNotNull(emailLinkActionCodeSettings) {
                     "ActionCodeSettings cannot be null when using " +
@@ -304,8 +310,36 @@ abstract class AuthProvider(open val providerId: String) {
         /**
          * Enables automatic retrieval of the SMS code. Defaults to true.
          */
+        // TODO(demolaf): is this meant to be isSMSAutoFillInputFieldEnabled?
         val isAutoRetrievalEnabled: Boolean = true
     ) : AuthProvider(providerId = Provider.PHONE.id) {
+        /**
+         * Sealed class representing the result of phone number verification.
+         *
+         * Phone verification can complete in two ways:
+         * - [AutoVerified]: SMS was instantly retrieved and verified by the Firebase SDK
+         * - [NeedsManualVerification]: SMS code was sent, user must manually enter it
+         */
+        internal sealed class VerifyPhoneNumberResult {
+            /**
+             * Instant verification succeeded via SMS auto-retrieval.
+             *
+             * @property credential The [PhoneAuthCredential] that can be used to sign in
+             */
+            class AutoVerified(val credential: PhoneAuthCredential) : VerifyPhoneNumberResult()
+
+            /**
+             * Instant verification failed, manual code entry required.
+             *
+             * @property verificationId The verification ID to use when submitting the code
+             * @property token Token for resending the verification code
+             */
+            class NeedsManualVerification(
+                val verificationId: String,
+                val token: PhoneAuthProvider.ForceResendingToken,
+            ) : VerifyPhoneNumberResult()
+        }
+
         internal fun validate() {
             defaultNumber?.let {
                 check(PhoneNumberUtils.isValid(it)) {
@@ -329,6 +363,71 @@ abstract class AuthProvider(open val providerId: String) {
                 }
             }
         }
+
+        /**
+         * Internal coroutine-based wrapper for Firebase Phone Authentication verification.
+         *
+         * This method wraps the callback-based Firebase Phone Auth API into a suspending function
+         * using Kotlin coroutines. It handles the Firebase [PhoneAuthProvider.OnVerificationStateChangedCallbacks]
+         * and converts them into a [VerifyPhoneNumberResult].
+         *
+         * **Callback mapping:**
+         * - `onVerificationCompleted` → [VerifyPhoneNumberResult.AutoVerified]
+         * - `onCodeSent` → [VerifyPhoneNumberResult.NeedsManualVerification]
+         * - `onVerificationFailed` → throws the exception
+         *
+         * This is a private helper method used by [verifyPhoneNumber]. Callers should use
+         * [verifyPhoneNumber] instead as it handles state management and error handling.
+         *
+         * @param auth The [FirebaseAuth] instance to use for verification
+         * @param phoneNumber The phone number to verify in E.164 format
+         * @param multiFactorSession Optional [MultiFactorSession] for MFA enrollment. When provided,
+         * Firebase verifies the phone number for enrolling as a second authentication factor
+         * instead of primary sign-in. Pass null for standard phone authentication.
+         * @param forceResendingToken Optional token from previous verification for resending
+         *
+         * @return [VerifyPhoneNumberResult] indicating auto-verified or manual verification needed
+         * @throws FirebaseException if verification fails
+         */
+        internal suspend fun verifyPhoneNumberAwait(
+            auth: FirebaseAuth,
+            phoneNumber: String,
+            multiFactorSession: MultiFactorSession? = null,
+            forceResendingToken: PhoneAuthProvider.ForceResendingToken?,
+        ): VerifyPhoneNumberResult = suspendCoroutine { continuation ->
+            val options = PhoneAuthOptions.newBuilder(auth)
+                .setPhoneNumber(phoneNumber)
+                .requireSmsValidation(!isInstantVerificationEnabled)
+                .setTimeout(timeout, TimeUnit.SECONDS)
+                .setCallbacks(object : PhoneAuthProvider.OnVerificationStateChangedCallbacks() {
+                    override fun onVerificationCompleted(credential: PhoneAuthCredential) {
+                        continuation.resume(VerifyPhoneNumberResult.AutoVerified(credential))
+                    }
+
+                    override fun onVerificationFailed(e: FirebaseException) {
+                        continuation.resumeWithException(e)
+                    }
+
+                    override fun onCodeSent(
+                        verificationId: String,
+                        token: PhoneAuthProvider.ForceResendingToken,
+                    ) {
+                        continuation.resume(
+                            VerifyPhoneNumberResult.NeedsManualVerification(
+                                verificationId,
+                                token
+                            )
+                        )
+                    }
+                })
+            if (forceResendingToken != null) {
+                options.setForceResendingToken(forceResendingToken)
+            }
+            if (multiFactorSession != null) {
+                options.setMultiFactorSession(multiFactorSession)
+            }
+            PhoneAuthProvider.verifyPhoneNumber(options.build())
+        }
     }
 
     /**