Handle Android process death during web authentication

[utkrishtsahu]

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

📋 Changes

On Android devices with aggressive battery management (Samsung, Xiaomi, Huawei, Oppo, Vivo), the OS kills the app process while the user is in the browser completing Auth0 login. When the browser redirects back, the app restarts fresh and the in-memory PKCE callback is lost — the authorization code is never exchanged for tokens. In Auth0 tenant logs, a successful login ("s") appears but no corresponding token exchange.

The native Auth0.Android SDK (since v3.4.0, PR #784) already handles process death — AuthenticationActivity serializes OAuthManager state (PKCE code_verifier, state nonce) into the Activity Bundle and restores it on recreation. The recovered credentials are delivered via WebAuthProvider.addCallback(). The Flutter plugin never registered this callback, so recovered credentials were silently discarded.

What changed:

• Auth0FlutterPlugin.kt — Registers a processDeathCallback via WebAuthProvider.addCallback() / removeCallback() in Activity lifecycle methods. Includes a buffering mechanism: credentials recovered before the Dart isolate is ready are stored in pendingRecoveredCredentials and flushed when Dart sends webAuth#dartReady. The plugin now handles the webAuthMethodChannel directly (intercepting dartReady, delegating all other calls to webAuthCallHandler).
• auth0_flutter_web_auth_platform.dart — Added onCredentialsRecovered stream getter to the abstract platform interface.
• method_channel_auth0_flutter_web_auth.dart — Listens for native → Dart webAuth#onLoginResult method calls via setMethodCallHandler, emits credentials through a broadcast StreamController. Sends webAuth#dartReady in the constructor to signal readiness to the native side.
• web_authentication.dart — Exposes public Stream get onCredentialsRecovered API with documentation.
• README.md — Added "Android: Handle Process Death During Login" section with usage example, a Common Tasks bullet, and an API reference entry for onCredentialsRecovered.

New public API:

Stream<Credentials> get onCredentialsRecovered

Developer usage:

auth0.webAuthentication().onCredentialsRecovered.listen((credentials) {
  setState(() => _credentials = credentials);
});

📎 References

ESD-59215

🎯 Testing

Unit tests: Not added — the fix bridges native SDK behavior (WebAuthProvider.addCallback) that requires a real Android Activity lifecycle and process death simulation, which cannot be meaningfully unit tested.

Manual end-to-end testing (verified on Pixel 7a, device 38261JEHN01576):

1. Build and install the app with the fix: flutter build apk --debug
2. Add onCredentialsRecovered listener in your app's initState()
3. Launch the app, tap Login — browser opens with Auth0 Universal Login page
4. While the browser is showing, kill the app process:

adb shell am kill <your.package.name>
⚠️ "Don't keep activities" in Developer Options is not sufficient — it only destroys the Activity but keeps the process alive. You must use adb shell am kill to simulate true process death.

5.Complete login in the browser — the redirect fires, Android restores the app
6.Verify: onCredentialsRecovered stream emits credentials with valid accessToken, idToken, refreshToken, expiresAt, and tokenType

Test result: PASS — all token fields present, user authenticated successfully after process death recovery.