fix: adopt withAuthTab() to fix spurious USER_CANCELLED on Android

EXAMPLES.md

@@ -2783,6 +2783,8 @@ On Android, web authentication defaults to a Custom Tab, which shows a read-only
 
 > **Platform Support:** Android only. This option is ignored on iOS and web.
 
+> **Note:** Since v6, Android web authentication uses **Auth Tab** by default — a Custom Tab launch mode that delivers proper `ActivityResult` callbacks instead of inferring cancellation from lifecycle events. This fixes the spurious `USER_CANCELLED` error ([#1584](https://github.com/auth0/react-native-auth0/issues/1584)) when users tap Chrome's minimize button (Chrome 122+). Auth Tab requires **Chrome 137 or later**; on older browser versions it automatically falls back to a standard Custom Tab. Auth Tab is the default launch mode for regular Custom Tabs, whereas TWA is opt-in and renders full-screen with no URL bar. Because they use different launch mechanisms, enabling `useTrustedWebActivity: true` makes TWA take precedence and Auth Tab is not used. Note also that [`ephemeralSession: true`](#ephemeral-sessions) is honoured on both Auth Tab and a plain Custom Tab (on a browser that supports ephemeral browsing), but a TWA does **not** support it — so enabling `useTrustedWebActivity: true` disables ephemeral browsing.
+
 ### Required setup
 
 TWA will only render full-screen if your app's signing certificate is registered with your Auth0 tenant. Without this, Digital Asset Links verification fails and the flow falls back to a Custom Tab.
@@ -2843,11 +2845,11 @@ Pass `ephemeralSession: true` to run web authentication in an isolated browser s
 **Behaviour:**
 
 - **iOS:** sets `prefersEphemeralWebBrowserSession` on `ASWebAuthenticationSession`. Because there is no shared cookie to consent to, this also suppresses the SSO alert box. Requires iOS 13+.
-- **Android:** opens the Custom Tab with ephemeral browsing. Requires **Chrome 136+** or another browser that supports it; on unsupported browsers a warning is logged and the flow falls back to a regular Custom Tab — login still completes, but the session is not ephemeral.
+- **Android:** opens the browser (Auth Tab or a plain Custom Tab) with ephemeral browsing. Requires **Chrome 136+** or another browser that supports it; on unsupported browsers a warning is logged and the flow falls back to a regular (non-ephemeral) session — login still completes, but the session is not ephemeral.
 
 > **Platform Support:** iOS and Android. This option is ignored on web.
 
-> **Warning:** On Android, `ephemeralSession` and [`useTrustedWebActivity`](#trusted-web-activity-android) are effectively mutually exclusive. A Trusted Web Activity does not support ephemeral browsing, so if you enable both, TWA takes precedence and the session will **not** be ephemeral. Pick one.
+> **Warning:** On Android, ephemeral browsing is supported on both [Auth Tab](#trusted-web-activity-android) (the default launch mode since v6) and a plain Custom Tab, as long as the browser supports ephemeral browsing (Chrome 136+). A [Trusted Web Activity](#trusted-web-activity-android) does **not** support it, so when `useTrustedWebActivity: true` is set the session will **not** be ephemeral. On a browser too old to support ephemeral browsing, a warning is logged and the session is not ephemeral.
 
 > **Note:** Android support for ephemeral sessions was added in v6. In earlier versions the option was accepted but only took effect on iOS.
 

MIGRATION_GUIDE.md

@@ -59,7 +59,7 @@ npx expo prebuild --clean
 
 ### 3. Android: minSdk 26 & JDK 17 ✅
 
-v6 adopts **Auth0.Android 4.0.1**, which raises the SDK's build floors. These are inherited by your app.
+v6 adopts **Auth0.Android 4.1.0**, which raises the SDK's build floors. These are inherited by your app.
 
 | Setting        | v5.x  | v6.0        |
 | :------------- | :---- | :---------- |
@@ -199,7 +199,21 @@ await authorize(
 );
 ```
 
-Two further Android caveats: the fallback above means you should keep calling `clearSession` unless you can guarantee the browser honours the ephemeral request, and `ephemeralSession` has no effect when `useTrustedWebActivity` is also enabled (a Trusted Web Activity cannot browse ephemerally, so TWA wins). See [Ephemeral Sessions](EXAMPLES.md#ephemeral-sessions) for details.
+Two further Android caveats: the fallback above means you should keep calling `clearSession` unless you can guarantee the browser honours the ephemeral request, and ephemeral browsing is supported on Auth Tab (the new default, see below) and plain Custom Tabs but **not** on a Trusted Web Activity. So with `useTrustedWebActivity` enabled the session is not ephemeral; on Auth Tab or a plain Custom Tab it is ephemeral as long as the browser supports it (Chrome 136+). See [Ephemeral Sessions](EXAMPLES.md#ephemeral-sessions) for details.
+
+#### Auth Tab is now the default Android web authentication launch mode
+
+Auth0.Android 4.0's Auth Tab launch path delivers a real `ActivityResult` from the Custom Tab instead of inferring cancellation from activity lifecycle events. This fixes a long-standing Android bug ([#1584](https://github.com/auth0/react-native-auth0/issues/1584)) where tapping Chrome's minimize button (available in Chrome 122+) would incorrectly reject `authorize()` with `USER_CANCELLED` while leaving the browser alive as a "zombie" — so when the user returned and completed login, the redirect was dropped and credentials never arrived.
+
+**What changed:** `authorize()` and `clearSession()` now call `withAuthTab()` by default on Android. The iOS flow is unchanged; web is unaffected.
+
+**Browser support:** Auth Tab requires **Chrome 137 or later**. On older browser versions it automatically falls back to a standard Custom Tab, so login and logout still work.
+
+**Impact:** Most apps see no difference — login and logout work as before, but the minimize-button bug is fixed. The launch path is slightly different internally (Chrome Custom Tabs launched via Auth Tab rather than plain Custom Tabs), but this is transparent to user-facing behavior.
+
+**✅ Action Required:** None for most apps. The change is entirely internal to the Android implementation. If you encounter issues on a specific browser (Edge, Brave, Firefox), test across browsers and report findings — Auth Tab has been validated with Chrome.
+
+> **Note:** Real user cancellation (back button, dismiss gesture) still rejects with `USER_CANCELLED` as expected — only the spurious rejection from the minimize button is fixed.
 
 #### `SSOCredentials.expiresIn` is now `expiresAt`
 

android/build.gradle

@@ -78,7 +78,7 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "androidx.browser:browser:1.10.0"
-  implementation 'com.auth0.android:auth0:4.0.1'
+  implementation 'com.auth0.android:auth0:4.1.0'
 
   testImplementation 'junit:junit:4.13.2'
   testImplementation 'com.squareup.okhttp3:mockwebserver:4.12.0'

android/src/main/java/com/auth0/react/A0Auth0Module.kt

@@ -219,6 +219,15 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
             // Ephemeral browsing only applies to the Custom Tab path; the TWA intent
             // builder ignores it, so TWA wins when both options are set.
             if (ephemeralSession == true) { withEphemeralBrowsing() }
+
+            // Auth Tab delivers a real ActivityResult instead of inferring cancellation
+            // from lifecycle, fixing spurious USER_CANCELLED when Chrome minimize is tapped.
+            // Auth Tab requires Chrome 137+; older browsers fall back to a standard Custom Tab.
+            //
+            // Note: [withAuthTab] and [withTrustedWebActivity] are mutually exclusive. If both are set,
+            // TWA takes precedence and Auth Tab will not be used. They rely on different underlying
+            // launch mechanisms and cannot be combined.
+            withAuthTab()
         }
 
         builder.withParameters(cleanedParameters)
@@ -520,6 +529,14 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
             builder.withTrustedWebActivity()
         }
 
+        // Auth Tab for logout flow as well (same rationale as authorize).
+        // Auth Tab requires Chrome 137+; older browsers fall back to a standard Custom Tab.
+        //
+        // Note: [withAuthTab] and [withTrustedWebActivity] are mutually exclusive. If both are set,
+        // TWA takes precedence and Auth Tab will not be used. They rely on different underlying
+        // launch mechanisms and cannot be combined.
+        builder.withAuthTab()
+
         redirectUri?.let { builder.withReturnToUrl(it) }
 
         allowedBrowserPackages?.let { packages ->