fix: Handle configuration changes during WebAuth flow to prevent memory leak

EXAMPLES.md

@@ -322,9 +322,58 @@ WebAuthProvider.logout(account)
 
             })
 ```
-> [!NOTE]  
+> [!NOTE]
 > DPoP is supported only on Android version 6.0 (API level 23) and above. Trying to use DPoP in any older versions will result in an exception.
 
+## Handling Configuration Changes During Authentication
+
+When the Activity is destroyed during authentication due to a configuration change (e.g. device rotation, locale change, dark mode toggle), the SDK caches the authentication result internally. Use `consumePendingLoginResult()` or `consumePendingLogoutResult()` in your `onResume()` to recover it.
+
+```kotlin
+class LoginActivity : AppCompatActivity() {
+
+    private val loginCallback = object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+            // Handle successful login
+        }
+        override fun onFailure(error: AuthenticationException) {
+            // Handle error
+        }
+    }
+
+    private val logoutCallback = object : Callback<Void?, AuthenticationException> {
+        override fun onSuccess(result: Void?) {
+            // Handle successful logout
+        }
+        override fun onFailure(error: AuthenticationException) {
+            // Handle error
+        }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        // Recover any result that arrived while the Activity was being recreated
+        WebAuthProvider.consumePendingLoginResult(loginCallback)
+        WebAuthProvider.consumePendingLogoutResult(logoutCallback)
+    }
+
+    fun onLoginClick() {
+        WebAuthProvider.login(account)
+            .withScheme("demo")
+            .start(this, loginCallback)
+    }
+
+    fun onLogoutClick() {
+        WebAuthProvider.logout(account)
+            .withScheme("demo")
+            .start(this, logoutCallback)
+    }
+}
+```
+
+> [!NOTE]
+> If you use the `suspend fun await()` API from a ViewModel coroutine scope, the Activity is never captured in the callback chain, so you do not need `consumePending*` calls.
+
 ## Authentication API
 
 The client provides methods to authenticate the user against the Auth0 server.

V4_MIGRATION_GUIDE.md

@@ -25,6 +25,8 @@ v4 of the Auth0 Android SDK includes significant build toolchain updates, update
 - [**Dependency Changes**](#dependency-changes)
   + [Gson 2.8.9 → 2.11.0](#️-gson-289--2110-transitive-dependency)
   + [DefaultClient.Builder](#defaultclientbuilder)
+- [**New APIs**](#new-apis)
+  + [Handling Configuration Changes During Authentication](#handling-configuration-changes-during-authentication)
 
 ---
 
@@ -295,6 +297,46 @@ The legacy constructor is deprecated but **not removed** — existing code will
 and run. Your IDE will show a deprecation warning with a suggested `ReplaceWith` quick-fix to
 migrate to the Builder.
 
+## New APIs
+
+### Handling Configuration Changes During Authentication
+
+v4 fixes a memory leak and lost callback issue when the Activity is destroyed during authentication
+(e.g. device rotation, locale change, dark mode toggle). The SDK wraps the callback in a
+`LifecycleAwareCallback` that observes the host Activity/Fragment lifecycle. When `onDestroy` fires,
+the reference to the callback is immediately nulled out so the destroyed Activity is no longer held
+in memory.
+
+If the authentication result arrives while the Activity is being recreated, it is cached internally.
+Use `consumePendingLoginResult()` or `consumePendingLogoutResult()` in your `onResume()` to recover it:
+
+```kotlin
+class LoginActivity : AppCompatActivity() {
+    private val callback = object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) { /* handle credentials */ }
+        override fun onFailure(error: AuthenticationException) { /* handle error */ }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        // Recover result that arrived during configuration change
+        WebAuthProvider.consumePendingLoginResult(callback)
+    }
+
+    fun onLoginClick() {
+        WebAuthProvider.login(account)
+            .withScheme("myapp")
+            .start(this, callback)
+    }
+}
+```
+
+For logout flows, use `WebAuthProvider.consumePendingLogoutResult(callback)` in the same way.
+
+> **Note:** If you use the `suspend fun await()` API from a ViewModel coroutine scope, the
+> Activity is never captured in the callback chain, so you do not need `consumePending*` calls.
+> See the sample app for a ViewModel-based example.
+
 ## Getting Help
 
 If you encounter issues during migration:

auth0/src/main/java/com/auth0/android/provider/LifecycleAwareCallback.kt

@@ -0,0 +1,53 @@
+package com.auth0.android.provider
+
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import com.auth0.android.authentication.AuthenticationException
+import com.auth0.android.callback.Callback
+
+/**
+ * Wraps a user-provided callback and observes the Activity/Fragment lifecycle.
+ * When the host is destroyed (e.g. config change), [inner] is set to null so
+ * the destroyed Activity is no longer referenced by the SDK.
+ *
+ * If a result arrives after [inner] has been cleared, the [onDetached] lambda
+ * is invoked to cache the result for later recovery via consumePending*Result().
+ *
+ * @param S the success type (Credentials for login, Void? for logout)
+ * @param inner the user's original callback
+ * @param lifecycleOwner the Activity or Fragment whose lifecycle to observe
+ * @param onDetached called when a result arrives but the callback is already detached
+ */
+internal class LifecycleAwareCallback<S>(
+    @Volatile private var inner: Callback<S, AuthenticationException>?,
+    lifecycleOwner: LifecycleOwner,
+    private val onDetached: (success: S?, error: AuthenticationException?) -> Unit,
+) : Callback<S, AuthenticationException>, DefaultLifecycleObserver {
+
+    init {
+        lifecycleOwner.lifecycle.addObserver(this)
+    }
+
+    override fun onSuccess(result: S) {
+        val cb = inner
+        if (cb != null) {
+            cb.onSuccess(result)
+        } else {
+            onDetached(result, null)
+        }
+    }
+
+    override fun onFailure(error: AuthenticationException) {
+        val cb = inner
+        if (cb != null) {
+            cb.onFailure(error)
+        } else {
+            onDetached(null, error)
+        }
+    }
+
+    override fun onDestroy(owner: LifecycleOwner) {
+        inner = null
+        owner.lifecycle.removeObserver(this)
+    }
+}

auth0/src/main/java/com/auth0/android/provider/OAuthManager.kt

@@ -29,6 +29,7 @@ internal class OAuthManager(
     @get:VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
     internal val dPoP: DPoP? = null
 ) : ResumableManager() {
+
     private val parameters: MutableMap<String, String>
     private val headers: MutableMap<String, String>
     private val ctOptions: CustomTabsOptions

auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt

@@ -6,6 +6,7 @@ import android.net.Uri
 import android.os.Bundle
 import android.util.Log
 import androidx.annotation.VisibleForTesting
+import androidx.lifecycle.LifecycleOwner
 import com.auth0.android.Auth0
 import com.auth0.android.annotation.ExperimentalAuth0Api
 import com.auth0.android.authentication.AuthenticationException
@@ -18,6 +19,7 @@ import kotlinx.coroutines.suspendCancellableCoroutine
 import kotlinx.coroutines.withContext
 import java.util.Locale
 import java.util.concurrent.CopyOnWriteArraySet
+import java.util.concurrent.atomic.AtomicReference
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
@@ -39,6 +41,62 @@ public object WebAuthProvider {
     internal var managerInstance: ResumableManager? = null
         private set
 
+    /**
+     * Represents a pending authentication or logout result that arrived while
+     * the original callback was no longer reachable (e.g. Activity destroyed
+     * during a configuration change).
+     */
+    internal sealed class PendingResult<out S, out E> {
+        data class Success<S>(val result: S) : PendingResult<S, Nothing>()
+        data class Failure<E>(val error: E) : PendingResult<Nothing, E>()
+    }
+
+    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+    internal val pendingLoginResult =
+        AtomicReference<PendingResult<Credentials, AuthenticationException>?>(null)
+
+    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+    internal val pendingLogoutResult =
+        AtomicReference<PendingResult<Void?, AuthenticationException>?>(null)
+
+    /**
+     * Check for and consume a pending login result that arrived during a configuration change.
+     * Call this in your Activity's `onResume()` to recover results that were delivered while the
+     * Activity was being recreated (e.g. due to screen rotation).
+     *
+     * @param callback the callback to deliver the pending result to
+     * @return true if a pending result was found and delivered, false otherwise
+     */
+    @JvmStatic
+    public fun consumePendingLoginResult(callback: Callback<Credentials, AuthenticationException>): Boolean {
+        val result = pendingLoginResult.getAndSet(null) ?: return false
+        when (result) {
+            is PendingResult.Success -> callback.onSuccess(result.result)
+            is PendingResult.Failure -> callback.onFailure(result.error)
+        }
+        resetManagerInstance()
+        return true
+    }
+
+    /**
+     * Check for and consume a pending logout result that arrived during a configuration change.
+     * Call this in your Activity's `onResume()` to recover results that were delivered while the
+     * Activity was being recreated (e.g. due to screen rotation).
+     *
+     * @param callback the callback to deliver the pending result to
+     * @return true if a pending result was found and delivered, false otherwise
+     */
+    @JvmStatic
+    public fun consumePendingLogoutResult(callback: Callback<Void?, AuthenticationException>): Boolean {
+        val result = pendingLogoutResult.getAndSet(null) ?: return false
+        when (result) {
+            is PendingResult.Success -> callback.onSuccess(result.result)
+            is PendingResult.Failure -> callback.onFailure(result.error)
+        }
+        resetManagerInstance()
+        return true
+    }
+
     @JvmStatic
     public fun addCallback(callback: Callback<Credentials, AuthenticationException>) {
         callbacks += callback
@@ -242,6 +300,27 @@ public object WebAuthProvider {
          * @see AuthenticationException.isAuthenticationCanceled
          */
         public fun start(context: Context, callback: Callback<Void?, AuthenticationException>) {
+            pendingLogoutResult.set(null)
+
+            val effectiveCallback = if (context is LifecycleOwner) {
+                LifecycleAwareCallback<Void?>(
+                    inner = callback,
+                    lifecycleOwner = context as LifecycleOwner,
+                    onDetached = { _: Void?, error: AuthenticationException? ->
+                        if (error != null) {
+                            pendingLogoutResult.set(PendingResult.Failure(error))
+                        } else {
+                            pendingLogoutResult.set(PendingResult.Success(null))
+                        }
+                    }
+                )
+            } else {
+                callback
+            }
+            startInternal(context, effectiveCallback)
+        }
+
+        internal fun startInternal(context: Context, callback: Callback<Void?, AuthenticationException>) {
             resetManagerInstance()
             if (!ctOptions.hasCompatibleBrowser(context.packageManager)) {
                 val ex = AuthenticationException(
@@ -286,7 +365,7 @@ public object WebAuthProvider {
         ) {
             return withContext(coroutineContext) {
                 suspendCancellableCoroutine { continuation ->
-                    start(context, object : Callback<Void?, AuthenticationException> {
+                    startInternal(context, object : Callback<Void?, AuthenticationException> {
                         override fun onSuccess(result: Void?) {
                             continuation.resume(Unit)
                         }
@@ -592,6 +671,29 @@ public object WebAuthProvider {
         public fun start(
             context: Context,
             callback: Callback<Credentials, AuthenticationException>
+        ) {
+            pendingLoginResult.set(null)
+            val effectiveCallback = if (context is LifecycleOwner) {
+                LifecycleAwareCallback<Credentials>(
+                    inner = callback,
+                    lifecycleOwner = context as LifecycleOwner,
+                    onDetached = { success: Credentials?, error: AuthenticationException? ->
+                        if (success != null) {
+                            pendingLoginResult.set(PendingResult.Success(success))
+                        } else if (error != null) {
+                            pendingLoginResult.set(PendingResult.Failure(error))
+                        }
+                    }
+                )
+            } else {
+                callback
+            }
+            startInternal(context, effectiveCallback)
+        }
+
+        internal fun startInternal(
+            context: Context,
+            callback: Callback<Credentials, AuthenticationException>
         ) {
             resetManagerInstance()
             if (!ctOptions.hasCompatibleBrowser(context.packageManager)) {
@@ -665,7 +767,9 @@ public object WebAuthProvider {
         ): Credentials {
             return withContext(coroutineContext) {
                 suspendCancellableCoroutine { continuation ->
-                    start(context, object : Callback<Credentials, AuthenticationException> {
+                    // Use startInternal directly — the anonymous callback captures only the
+                    // coroutine continuation, not an Activity, so lifecycle wrapping is not needed
+                    startInternal(context, object : Callback<Credentials, AuthenticationException> {
                         override fun onSuccess(result: Credentials) {
                             continuation.resume(result)
                         }