fix(auth): only exit auth flow on AuthState.Finished, not per-provider Cancelled

Author: demolaf

auth/src/main/java/com/firebase/ui/auth/AuthFlowController.kt

@@ -70,8 +70,8 @@ import java.util.concurrent.atomic.AtomicBoolean
  *                     is AuthState.Error -> {
  *                         // Handle error
  *                     }
- *                     is AuthState.Cancelled -> {
- *                         // User cancelled
+ *                     is AuthState.Finished -> {
+ *                         // Flow was ended via authController.cancel()
  *                     }
  *                     else -> {}
  *                 }
@@ -93,7 +93,7 @@ import java.util.concurrent.atomic.AtomicBoolean
  * **Lifecycle Management:**
  * - [createIntent] - Generate Intent to start the auth flow Activity
  * - [start] - Alternative to launch the flow (for Activity context)
- * - [cancel] - Cancel the ongoing auth flow, transitions to [AuthState.Cancelled]
+ * - [cancel] - End the ongoing auth flow, transitions to [AuthState.Finished]
  * - [dispose] - Release all resources (coroutines, listeners). Call in onDestroy()
  *
  * @property authUI The [FirebaseAuthUI] instance managing authentication
@@ -120,7 +120,8 @@ class AuthFlowController internal constructor(
      * - [AuthState.Loading] - Authentication in progress
      * - [AuthState.Success] - User signed in successfully
      * - [AuthState.Error] - Authentication error occurred
-     * - [AuthState.Cancelled] - User cancelled the flow
+     * - [AuthState.Cancelled] - User cancelled a single sign-in attempt, flow stays open
+     * - [AuthState.Finished] - Flow was ended via [cancel]
      * - [AuthState.RequiresMfa] - Multi-factor authentication required
      * - [AuthState.RequiresEmailVerification] - Email verification required
      */
@@ -195,7 +196,7 @@ class AuthFlowController internal constructor(
     /**
      * Cancels the ongoing authentication flow.
      *
-     * This method transitions the auth state to [AuthState.Cancelled] and
+     * This method transitions the auth state to [AuthState.Finished] and
      * signals the auth flow to terminate. The auth flow Activity will finish
      * and return [Activity.RESULT_CANCELED].
      *
@@ -211,7 +212,7 @@ class AuthFlowController internal constructor(
      */
     fun cancel() {
         checkNotDisposed()
-        authUI.updateAuthState(AuthState.Cancelled)
+        authUI.updateAuthState(AuthState.Finished)
     }
 
     /**

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

@@ -120,13 +120,33 @@ abstract class AuthState private constructor() {
 
     /**
      * Authentication was cancelled by the user.
+     *
+     * This is a normal, in-flow outcome (e.g. dismissing a provider's sign-in sheet) -
+     * it does not end the authentication flow. UI hosting the flow resets to its
+     * starting screen rather than exiting.
+     *
+     * @see Finished for programmatically ending the whole flow
      */
     class Cancelled internal constructor() : AuthState() {
         override fun equals(other: Any?): Boolean = other is Cancelled
         override fun hashCode(): Int = javaClass.hashCode()
         override fun toString(): String = "AuthState.Cancelled"
     }
 
+    /**
+     * The authentication flow was ended programmatically (e.g. via
+     * [AuthFlowController.cancel]) and should exit entirely.
+     *
+     * Unlike [Cancelled], which represents the user backing out of a single
+     * sign-in attempt while staying in the flow, [Finished] terminates the whole
+     * flow - the hosting Activity finishes with `RESULT_CANCELED`.
+     */
+    class Finished internal constructor() : AuthState() {
+        override fun equals(other: Any?): Boolean = other is Finished
+        override fun hashCode(): Int = javaClass.hashCode()
+        override fun toString(): String = "AuthState.Finished"
+    }
+
     /**
      * Multi-factor authentication is required to complete sign-in.
      *
@@ -337,5 +357,12 @@ abstract class AuthState private constructor() {
          */
         @JvmStatic
         val Cancelled: Cancelled = Cancelled()
+
+        /**
+         * Creates a Finished state instance.
+         * @return A new [Finished] state
+         */
+        @JvmStatic
+        val Finished: Finished = Finished()
     }
 }

auth/src/main/java/com/firebase/ui/auth/FirebaseAuthActivity.kt

@@ -36,7 +36,9 @@ import java.util.concurrent.ConcurrentHashMap
  *
  * This activity displays the [FirebaseAuthScreen] composable and manages
  * the authentication flow lifecycle. It automatically finishes when the user
- * signs in successfully or cancels the flow.
+ * signs in successfully or the flow is ended (e.g. via [AuthFlowController.cancel]).
+ * A user backing out of a single provider's sign-in attempt does not finish the
+ * activity - it resets to the starting screen instead.
  *
  * **Do not launch this Activity directly.**
  * Use [AuthFlowController] to start the auth flow:
@@ -116,8 +118,8 @@ class FirebaseAuthActivity : ComponentActivity() {
                         setResult(RESULT_OK, resultIntent)
                         finish()
                     }
-                    is AuthState.Cancelled -> {
-                        // User cancelled the flow
+                    is AuthState.Finished -> {
+                        // Flow was ended programmatically (e.g. AuthFlowController.cancel())
                         setResult(RESULT_CANCELED)
                         finish()
                     }

auth/src/test/java/com/firebase/ui/auth/AuthFlowControllerTest.kt

@@ -201,7 +201,7 @@ class AuthFlowControllerTest {
     // =============================================================================================
 
     @Test
-    fun `cancel() updates state to Cancelled`() = runTest {
+    fun `cancel() updates state to Finished`() = runTest {
         val controller = authUI.createAuthFlow(configuration)
 
         // Cancel the flow
@@ -213,8 +213,8 @@ class AuthFlowControllerTest {
         // Collect first state after cancel
         val state = controller.authStateFlow.first()
 
-        // Should be Cancelled state
-        assertThat(state).isInstanceOf(AuthState.Cancelled::class.java)
+        // Should be Finished state
+        assertThat(state).isInstanceOf(AuthState.Finished::class.java)
     }
 
     @Test
@@ -438,9 +438,9 @@ class AuthFlowControllerTest {
         // Advance test scheduler to process all pending coroutines
         testScheduler.advanceUntilIdle()
 
-        // Verify cancelled state
+        // Verify finished state
         val state = controller.authStateFlow.first()
-        assertThat(state).isInstanceOf(AuthState.Cancelled::class.java)
+        assertThat(state).isInstanceOf(AuthState.Finished::class.java)
 
         // Dispose
         controller.dispose()

auth/src/test/java/com/firebase/ui/auth/FirebaseAuthActivityTest.kt

@@ -313,18 +313,18 @@ class FirebaseAuthActivityTest {
     }
 
     // =============================================================================================
-    // Auth State Cancelled Tests
+    // Auth State Cancelled/Finished Tests
     // =============================================================================================
 
     @Test
-    fun `activity finishes with RESULT_CANCELED on Cancelled state`() = runTest {
+    fun `activity finishes with RESULT_CANCELED on Finished state`() = runTest {
         val intent = FirebaseAuthActivity.createIntent(applicationContext, configuration)
         val controller = Robolectric.buildActivity(FirebaseAuthActivity::class.java, intent)
 
         val activity = controller.create().start().resume().get()
 
-        // Update to Cancelled state
-        authUI.updateAuthState(AuthState.Cancelled)
+        // Update to Finished state (e.g. AuthFlowController.cancel())
+        authUI.updateAuthState(AuthState.Finished)
 
         shadowOf(Looper.getMainLooper()).idle()
 
@@ -336,6 +336,22 @@ class FirebaseAuthActivityTest {
         assertThat(shadowActivity.resultCode).isEqualTo(Activity.RESULT_CANCELED)
     }
 
+    @Test
+    fun `activity does not finish on Cancelled state`() = runTest {
+        val intent = FirebaseAuthActivity.createIntent(applicationContext, configuration)
+        val controller = Robolectric.buildActivity(FirebaseAuthActivity::class.java, intent)
+
+        val activity = controller.create().start().resume().get()
+
+        // User backed out of a single provider's sign-in attempt (e.g. dismissed
+        // the Google Credential Manager sheet) - the flow should stay open.
+        authUI.updateAuthState(AuthState.Cancelled)
+
+        shadowOf(Looper.getMainLooper()).idle()
+
+        assertThat(activity.isFinishing).isFalse()
+    }
+
     // =============================================================================================
     // Auth State Error Tests
     // =============================================================================================