[local_auth] Adopt structured errors, and remove useErrorDialogs (#9981)

Switches from `PlatformException`s to new `LocalAuthException`s, which contain structured error information (specifically, a code that is a documented enum, rather than a list of magic strings that are used inconsistently and not all documented), bringing the plugin into alignment with [our current best practices](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#platform-exception-handling. In addition to being clearer and easier to use for clients, this adds significantly more granular error codes than we currently have, which allows clients to better handle specific cases.

Since this must be done as a breaking change (since the current `PlatformException`s are a combination of documented and de-facto API), this batches another breaking change, which is removing the error dialogs from the plugin, for the reasons described in flutter/flutter#175125.

Since this is adding far more specific error codes, the PR also makes the internal change of passing essentially all native failure cases across the language boundary and then doing mapping to the cross-platform codes in Dart code, in keeping with our general recent practice of moving logic to the Dart side when there's no need for it to be native.

Fixes flutter/flutter#113687
Fixes flutter/flutter#175125
Fixes flutter/flutter#151513
Fixes flutter/flutter#132757
Fixes flutter/flutter#148947
Fixes flutter/flutter#173506
Fixes flutter/flutter#174191
Closes flutter/flutter#96646
Fixes flutter/flutter#117810
Closes flutter/flutter#141283
Closes flutter/flutter#173142

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: stuartmorgan-g

packages/local_auth/local_auth/CHANGELOG.md

@@ -1,7 +1,19 @@
-## NEXT
-
+## 3.0.0
+
+* **BREAKING CHANGES:**
+  * Throws `LocalAuthException`s rather than `PlatformException`s for most
+    failures cases, allowing structured error handling using the specific
+    `LocalAuthExceptionCode` values.
+  * Replaces `AuthenticationOptions` in `authenticate` with specific parameters.
+    * `AuthenticationOptions.stickyAuth` corresponds to
+      `persistAcrossBackgrounding`.
+    * `AuthenticationOptions.useErrorDialogs` has no replacement, as specific
+      error-handling UI should be up to plugin clients to determine. Callers
+      should use the new structured error codes to detect and handle failure
+      modes that used to have native dialogs.
 * Updates minimum supported SDK version to Flutter 3.29/Dart 3.7.
-* Updates README to reflect that only Android API 24+ is supported.
+* Updates README to reflect that Android older than API 24 and iOS older than
+  13.0 are no longer supported.
 
 ## 2.3.0
 

packages/local_auth/local_auth/README.md

@@ -10,7 +10,7 @@ fingerprint or facial recognition.
 
 |             | Android | iOS   | macOS  | Windows     |
 |-------------|---------|-------|--------|-------------|
-| **Support** | SDK 24+ | 12.0+ | 10.14+ | Windows 10+ |
+| **Support** | SDK 24+ | 13.0+ | 10.14+ | Windows 10+ |
 
 ## Usage
 
@@ -50,8 +50,8 @@ types and only check that some biometric is enrolled:
 
 <?code-excerpt "readme_excerpts.dart (Enrolled)"?>
 ```dart
-final List<BiometricType> availableBiometrics =
-    await auth.getAvailableBiometrics();
+final List<BiometricType> availableBiometrics = await auth
+    .getAvailableBiometrics();
 
 if (availableBiometrics.isNotEmpty) {
   // Some biometrics are enrolled.
@@ -66,72 +66,34 @@ if (availableBiometrics.contains(BiometricType.strong) ||
 
 ### Options
 
-The `authenticate()` method uses biometric authentication when possible, but
-also allows fallback to pin, pattern, or passcode.
+#### Requiring Biometrics
 
-<?code-excerpt "readme_excerpts.dart (AuthAny)"?>
-```dart
-try {
-  final bool didAuthenticate = await auth.authenticate(
-    localizedReason: 'Please authenticate to show account balance',
-  );
-  // ···
-} on PlatformException {
-  // ...
-}
-```
-
-To require biometric authentication, pass `AuthenticationOptions` with
-`biometricOnly` set to `true`.
+The `authenticate()` method uses biometric authentication when possible, but
+by default also allows fallback to pin, pattern, or passcode. To require
+biometric authentication, set `biometricOnly` to `true`.
 
 <?code-excerpt "readme_excerpts.dart (AuthBioOnly)"?>
 ```dart
 final bool didAuthenticate = await auth.authenticate(
   localizedReason: 'Please authenticate to show account balance',
-  options: const AuthenticationOptions(biometricOnly: true),
+  biometricOnly: true,
 );
 ```
 
 *Note*: `biometricOnly` is not supported on Windows since the Windows implementation's underlying API (Windows Hello) doesn't support selecting the authentication method.
 
-#### Dialogs
+#### Background Handling
 
-The plugin provides default dialogs for the following cases:
+On mobile platforms, authentication may be canceled by the system if the app
+is backgrounded. This might happen if the user receives a phone call before
+they get a chance to authenticate, for example. Setting
+`persistAcrossBackgrounding` to true will cause the plugin to instead wait until
+the app is foregrounded again, retry the authentication, and only return once
+that new attempt completes.
 
-1. Passcode/PIN/Pattern Not Set: The user has not yet configured a passcode on
-   iOS or PIN/pattern on Android.
-2. Biometrics Not Enrolled: The user has not enrolled any biometrics on the
-   device.
-
-If a user does not have the necessary authentication enrolled when
-`authenticate` is called, they will be given the option to enroll at that point,
-or cancel authentication.
-
-If you don't want to use the default dialogs, set the `useErrorDialogs` option
-to `false` to have `authenticate` immediately return an error in those cases.
-
-<?code-excerpt "readme_excerpts.dart (NoErrorDialogs)"?>
-```dart
-import 'package:local_auth/error_codes.dart' as auth_error;
-// ···
-    try {
-      final bool didAuthenticate = await auth.authenticate(
-        localizedReason: 'Please authenticate to show account balance',
-        options: const AuthenticationOptions(useErrorDialogs: false),
-      );
-      // ···
-    } on PlatformException catch (e) {
-      if (e.code == auth_error.notAvailable) {
-        // Add handling of no hardware here.
-      } else if (e.code == auth_error.notEnrolled) {
-        // ...
-      } else {
-        // ...
-      }
-    }
-```
+#### Dialog customization
 
-If you want to customize the messages in the dialogs, you can pass
+If you want to customize the messages in the system dialogs, you can pass
 `AuthMessages` for each platform you support. These are platform-specific, so
 you will need to import the platform-specific implementation packages. For
 instance, to customize Android and iOS:
@@ -158,29 +120,26 @@ each platform.
 
 ### Exceptions
 
-`authenticate` throws `PlatformException`s in many error cases. See
-`error_codes.dart` for known error codes that you may want to have specific
-handling for. For example:
+`authenticate` throws `LocalAuthException`s in most failure cases. See
+`LocalAuthExceptionCodes` for known error codes that you may want to have
+specific handling for. For example:
 
 <?code-excerpt "readme_excerpts.dart (ErrorHandling)"?>
 ```dart
-import 'package:flutter/services.dart';
-import 'package:local_auth/error_codes.dart' as auth_error;
 import 'package:local_auth/local_auth.dart';
 // ···
   final LocalAuthentication auth = LocalAuthentication();
   // ···
     try {
       final bool didAuthenticate = await auth.authenticate(
         localizedReason: 'Please authenticate to show account balance',
-        options: const AuthenticationOptions(useErrorDialogs: false),
       );
       // ···
-    } on PlatformException catch (e) {
-      if (e.code == auth_error.notEnrolled) {
+    } on LocalAuthException catch (e) {
+      if (e.code == LocalAuthExceptionCode.noBiometricHardware) {
         // Add handling of no hardware here.
-      } else if (e.code == auth_error.lockedOut ||
-          e.code == auth_error.permanentlyLockedOut) {
+      } else if (e.code == LocalAuthExceptionCode.temporaryLockout ||
+          e.code == LocalAuthExceptionCode.biometricLockout) {
         // ...
       } else {
         // ...
@@ -287,12 +246,3 @@ the Android theme directly in `android/app/src/main/AndroidManifest.xml`:
 	</application>
 ...
 ```
-
-## Sticky Auth
-
-You can set the `stickyAuth` option on the plugin to true so that plugin does not
-return failure if the app is put to background by the system. This might happen
-if the user receives a phone call before they get a chance to authenticate. With
-`stickyAuth` set to false, this would result in plugin returning failure result
-to the Dart app. If set to true, the plugin will retry authenticating when the
-app resumes.

packages/local_auth/local_auth/example/lib/main.dart

@@ -34,11 +34,9 @@ class _MyAppState extends State<MyApp> {
     super.initState();
     auth.isDeviceSupported().then(
       (bool isSupported) => setState(
-        () =>
-            _supportState =
-                isSupported
-                    ? _SupportState.supported
-                    : _SupportState.unsupported,
+        () => _supportState = isSupported
+            ? _SupportState.supported
+            : _SupportState.unsupported,
       ),
     );
   }
@@ -86,16 +84,27 @@ class _MyAppState extends State<MyApp> {
       });
       authenticated = await auth.authenticate(
         localizedReason: 'Let OS determine authentication method',
-        options: const AuthenticationOptions(stickyAuth: true),
+        persistAcrossBackgrounding: true,
       );
       setState(() {
         _isAuthenticating = false;
       });
+    } on LocalAuthException catch (e) {
+      print(e);
+      setState(() {
+        _isAuthenticating = false;
+        if (e.code != LocalAuthExceptionCode.userCanceled &&
+            e.code != LocalAuthExceptionCode.systemCanceled) {
+          _authorized =
+              'Error - ${e.code.name}${e.description != null ? ': ${e.description}' : ''}';
+        }
+      });
+      return;
     } on PlatformException catch (e) {
       print(e);
       setState(() {
         _isAuthenticating = false;
-        _authorized = 'Error - ${e.message}';
+        _authorized = 'Unexpected error - ${e.message}';
       });
       return;
     }
@@ -118,20 +127,29 @@ class _MyAppState extends State<MyApp> {
       authenticated = await auth.authenticate(
         localizedReason:
             'Scan your fingerprint (or face or whatever) to authenticate',
-        options: const AuthenticationOptions(
-          stickyAuth: true,
-          biometricOnly: true,
-        ),
+        persistAcrossBackgrounding: true,
+        biometricOnly: true,
       );
       setState(() {
         _isAuthenticating = false;
         _authorized = 'Authenticating';
       });
+    } on LocalAuthException catch (e) {
+      print(e);
+      setState(() {
+        _isAuthenticating = false;
+        if (e.code != LocalAuthExceptionCode.userCanceled &&
+            e.code != LocalAuthExceptionCode.systemCanceled) {
+          _authorized =
+              'Error - ${e.code.name}${e.description != null ? ': ${e.description}' : ''}';
+        }
+      });
+      return;
     } on PlatformException catch (e) {
       print(e);
       setState(() {
         _isAuthenticating = false;
-        _authorized = 'Error - ${e.message}';
+        _authorized = 'Unexpected Error - ${e.message}';
       });
       return;
     }

packages/local_auth/local_auth/example/lib/readme_excerpts.dart

@@ -9,10 +9,6 @@
 
 import 'package:flutter/material.dart';
 // #docregion ErrorHandling
-import 'package:flutter/services.dart';
-// #docregion NoErrorDialogs
-import 'package:local_auth/error_codes.dart' as auth_error;
-// #enddocregion NoErrorDialogs
 // #docregion CanCheck
 import 'package:local_auth/local_auth.dart';
 // #enddocregion CanCheck
@@ -64,8 +60,8 @@ class _MyAppState extends State<MyApp> {
 
   Future<void> getEnrolledBiometrics() async {
     // #docregion Enrolled
-    final List<BiometricType> availableBiometrics =
-        await auth.getAvailableBiometrics();
+    final List<BiometricType> availableBiometrics = await auth
+        .getAvailableBiometrics();
 
     if (availableBiometrics.isNotEmpty) {
       // Some biometrics are enrolled.
@@ -79,68 +75,30 @@ class _MyAppState extends State<MyApp> {
     // #enddocregion Enrolled
   }
 
-  Future<void> authenticate() async {
-    // #docregion AuthAny
-    try {
-      final bool didAuthenticate = await auth.authenticate(
-        localizedReason: 'Please authenticate to show account balance',
-      );
-      // #enddocregion AuthAny
-      print(didAuthenticate);
-      // #docregion AuthAny
-    } on PlatformException {
-      // ...
-    }
-    // #enddocregion AuthAny
-  }
-
   Future<void> authenticateWithBiometrics() async {
     // #docregion AuthBioOnly
     final bool didAuthenticate = await auth.authenticate(
       localizedReason: 'Please authenticate to show account balance',
-      options: const AuthenticationOptions(biometricOnly: true),
+      biometricOnly: true,
     );
     // #enddocregion AuthBioOnly
     print(didAuthenticate);
   }
 
-  Future<void> authenticateWithoutDialogs() async {
-    // #docregion NoErrorDialogs
-    try {
-      final bool didAuthenticate = await auth.authenticate(
-        localizedReason: 'Please authenticate to show account balance',
-        options: const AuthenticationOptions(useErrorDialogs: false),
-      );
-      // #enddocregion NoErrorDialogs
-      print(didAuthenticate ? 'Success!' : 'Failure');
-      // #docregion NoErrorDialogs
-    } on PlatformException catch (e) {
-      if (e.code == auth_error.notAvailable) {
-        // Add handling of no hardware here.
-      } else if (e.code == auth_error.notEnrolled) {
-        // ...
-      } else {
-        // ...
-      }
-    }
-    // #enddocregion NoErrorDialogs
-  }
-
   Future<void> authenticateWithErrorHandling() async {
     // #docregion ErrorHandling
     try {
       final bool didAuthenticate = await auth.authenticate(
         localizedReason: 'Please authenticate to show account balance',
-        options: const AuthenticationOptions(useErrorDialogs: false),
       );
       // #enddocregion ErrorHandling
       print(didAuthenticate ? 'Success!' : 'Failure');
       // #docregion ErrorHandling
-    } on PlatformException catch (e) {
-      if (e.code == auth_error.notEnrolled) {
+    } on LocalAuthException catch (e) {
+      if (e.code == LocalAuthExceptionCode.noBiometricHardware) {
         // Add handling of no hardware here.
-      } else if (e.code == auth_error.lockedOut ||
-          e.code == auth_error.permanentlyLockedOut) {
+      } else if (e.code == LocalAuthExceptionCode.temporaryLockout ||
+          e.code == LocalAuthExceptionCode.biometricLockout) {
         // ...
       } else {
         // ...

packages/local_auth/local_auth/example/pubspec.yaml

@@ -3,8 +3,8 @@ description: Demonstrates how to use the local_auth plugin.
 publish_to: none
 
 environment:
-  sdk: ^3.7.0
-  flutter: ">=3.29.0"
+  sdk: ^3.9.0
+  flutter: ">=3.35.0"
 
 dependencies:
   flutter:
@@ -16,8 +16,8 @@ dependencies:
     # The example app is bundled with the plugin so we use a path dependency on
     # the parent directory to use the current plugin's version.
     path: ../
-  local_auth_android: ^1.0.0
-  local_auth_darwin: ^1.2.1
+  local_auth_android: ^2.0.0
+  local_auth_darwin: ^2.0.0
 
 dev_dependencies:
   build_runner: ^2.1.10