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

[utkrishtsahu]

Changes

When the Activity is destroyed during a WebAuth login or logout flow due to a configuration change (e.g. device rotation, locale change, dark mode toggle), the SDK previously retained a strong reference to the destroyed Activity via the static WebAuthProvider.managerInstance → OAuthManager/LogoutManager → callback chain, causing a memory leak. Additionally, the authentication result was delivered to the destroyed Activity's callback, which could crash or silently fail.

Root cause: WebAuthProvider.managerInstance is a static field. OAuthManager and LogoutManager held a strong reference to the callback, which captured the Activity/Fragment this. On configuration change, the old Activity was destroyed but never garbage collected because of this reference chain.

What changed:

• LifecycleAwareCallback (new): A DefaultLifecycleObserver wrapper around the user's callback. It observes the host Activity/Fragment lifecycle and sets inner = null immediately and deterministically when onDestroy fires — breaking the memory leak chain without relying on GC timing. If a result arrives after onDestroy, it is routed to the onDetached lambda instead of the dead callback.
• OAuthManager: Retains a strong callback reference (no change). The leak is prevented upstream by LifecycleAwareCallback.
• LogoutManager: Same — strong reference retained, leak prevented upstream.
• WebAuthProvider: login().start() and logout().start() now wrap the callback in LifecycleAwareCallback when the context is a LifecycleOwner. Added the following new public APIs:
  • consumePendingLoginResult(callback) — Checks for and atomically delivers a cached login result to the provided callback. Returns true if a pending result was found and delivered.
  • consumePendingLogoutResult(callback) — Same for logout results.
  • PendingResult<S, E> (internal sealed class) — Represents a cached Success or Failure result, stored in an AtomicReference for thread safety.
• EXAMPLES.md: Added "Handling Configuration Changes During Authentication" section with usage example.
• V4_MIGRATION_GUIDE.md: Added documentation under "New APIs" section with accurate description of LifecycleAwareCallback.

Usage:

override fun onResume() {
    super.onResume()
    WebAuthProvider.consumePendingLoginResult(loginCallback)
    WebAuthProvider.consumePendingLogoutResult(logoutCallback)
}

No existing public APIs were removed, deprecated, or changed in signature. The suspend fun await() API is unaffected since it calls startInternal() directly and does not go through LifecycleAwareCallback.

Testing

Unit tests added (19 new tests in WebAuthProviderTest.kt):

• shouldConsumePendingLoginSuccessResult
• shouldConsumePendingLoginFailureResult
• shouldReturnFalseWhenNoPendingLoginResult
• shouldNotConsumeLoginResultTwice
• shouldConsumePendingLogoutSuccessResult
• shouldConsumePendingLogoutFailureResult
• shouldReturnFalseWhenNoPendingLogoutResult
• shouldNotConsumeLogoutResultTwice
• shouldCacheLoginResultWhenLifecycleCallbackIsDetachedOnDestroy
• shouldCacheLoginFailureWhenLifecycleCallbackIsDetachedOnDestroy
• shouldCacheLogoutSuccessWhenLifecycleCallbackIsDetachedOnDestroy
• shouldCacheLogoutFailureWhenLifecycleCallbackIsDetachedOnDestroy
• shouldDeliverDirectlyWhenLifecycleCallbackIsAlive
• shouldDeliverFailureDirectlyWhenLifecycleCallbackIsAlive
• shouldDeliverLogoutDirectlyWhenLifecycleCallbackIsAlive
• shouldRegisterAsLifecycleObserverOnInit
• shouldUnregisterLifecycleObserverOnDestroy
• shouldClearPendingLoginResultOnNewLoginStart
• shouldClearPendingLogoutResultOnNewLogoutStart
  All existing unit tests pass without modification.

Manual testing performed on device (Android 14):

• Scenario 1 — Normal login (no rotation): result delivered directly via callback ✅
• Scenario 2 — Rotate during login (callback path): result cached → recovered via consumePendingLoginResult() in onResume() ✅
• Scenario 3 — Rotate during login (await() coroutine path): coroutine continuation survives rotation, result delivered without consumePending ✅
• Scenario 4 — Process death during login: state restored from Bundle via OAuthManager.fromState(), result delivered via addCallback listeners ✅
• Scenario 5 — Rotate during logout (callback path): result cached → recovered via consumePendingLogoutResult() in onResume() ✅
• Scenario 6 — Rotate then cancel login: cancellation cached → consumePendingLoginResult() delivers the error correctly ✅
• Scenario 7 — Normal logout (no rotation): result delivered directly ✅

Checklist

• I have read the Auth0 general contribution guidelines

• I have read the Auth0 Code of Conduct

• All existing and new tests complete without errors