[local_auth] Adopt structured errors - platform interface

packages/local_auth/local_auth_platform_interface/CHANGELOG.md

@@ -1,5 +1,7 @@
-## NEXT
+## 1.1.0
 
+* Adds `LocalAuthException` to allow for consistent, structured exceptions
+  across platform implementations.
 * Updates minimum supported SDK version to Flutter 3.29/Dart 3.7.
 
 ## 1.0.10

packages/local_auth/local_auth_platform_interface/lib/local_auth_platform_interface.dart

@@ -7,7 +7,7 @@ import 'package:plugin_platform_interface/plugin_platform_interface.dart';
 import 'default_method_channel_platform.dart';
 import 'types/types.dart';
 
-export 'package:local_auth_platform_interface/types/types.dart';
+export 'types/types.dart';
 
 /// The interface that implementations of local_auth must implement.
 ///
@@ -40,7 +40,13 @@ abstract class LocalAuthPlatform extends PlatformInterface {
   /// Authenticates the user with biometrics available on the device while also
   /// allowing the user to use device authentication - pin, pattern, passcode.
   ///
-  /// Returns true if the user successfully authenticated, false otherwise.
+  /// Returns true if the user successfully authenticated. Returns false if
+  /// the authentication completes, but the user failed the challenge with no
+  /// further effects. Platform implementations should throw a
+  /// [LocalAuthException] for any other outcome, such as errors, cancelation,
+  /// or lockout. This may mean that for some platforms, the implementation will
+  /// never return false (e.g., if the only standard outcomes are success,
+  /// cancelation, or temporary lockout due to too many retries).
   ///
   /// [localizedReason] is the message to show to user while prompting them
   /// for authentication. This is typically along the lines of: 'Please scan
@@ -50,11 +56,6 @@ abstract class LocalAuthPlatform extends PlatformInterface {
   /// customize messages in the dialogs.
   ///
   /// Provide [options] for configuring further authentication related options.
-  ///
-  /// Throws a [PlatformException] if there were technical problems with local
-  /// authentication (e.g. lack of relevant hardware). This might throw
-  /// [PlatformException] with error code [otherOperatingSystem] on the iOS
-  /// simulator.
   Future<bool> authenticate({
     required String localizedReason,
     required Iterable<AuthMessages> authMessages,

packages/local_auth/local_auth_platform_interface/lib/types/auth_exception.dart

@@ -0,0 +1,125 @@
+// Copyright 2013 The Flutter Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/foundation.dart';
+
+/// An exception thrown by the plugin when there is authentication failure, or
+/// some other error.
+@immutable
+class LocalAuthException implements Exception {
+  /// Creates a new exception with the given information.
+  const LocalAuthException({
+    required this.code,
+    this.description,
+    this.details,
+  });
+
+  /// The type of failure.
+  final LocalAuthExceptionCode code;
+
+  /// A human-readable description of the failure.
+  final String? description;
+
+  /// Any additional details about the failure.
+  final Object? details;
+
+  @override
+  String toString() =>
+      '${objectRuntimeType(this, 'LocalAuthException')}(code ${code.name}, $description, $details)';
+}
+
+/// Types of [LocalAuthException]s, as indicated by [LocalAuthException.code].
+///
+/// Adding new values to this enum in the future will *not* be considered a
+/// breaking change, so clients should not assume they can exhaustively match
+/// exception codes. Clients should always include a default or other fallback.
+enum LocalAuthExceptionCode {
+  /// An authentication operation is already in progress, and has not completed.
+  ///
+  /// A new authentication cannot be started while the Future for a previous
+  /// authentication is still outstanding.
+  authInProgress,
+
+  /// UI needs to be displayed, but could not be.
+  ///
+  /// For example, this can be returned on Android if a call tries to show UI
+  /// when no Activity is available.
+  uiUnavailable,
+
+  /// The operation was canceled by the user.
+  userCanceled,
+
+  /// The operation was canceled due to a device-specific timeout.
+  timeout,
+
+  /// The operation was canceled by a system event.
+  ///
+  /// For example, on mobile this may be returned if the application is
+  /// backgrounded during authentication.
+  systemCanceled,
+
+  /// The device has no credentials configured.
+  ///
+  /// For example, on mobile this would be returned if the device has no
+  /// enrolled biometrics and no fallback authentication mechanism set such as
+  /// a passcode, pin, or pattern.
+  noCredentialsSet,
+
+  /// The device is capable of biometric authentication, but no biometrics are
+  /// enrolled.
+  noBiometricsEnrolled,
+
+  /// The device does not have biometric hardware.
+  noBiometricHardware,
+
+  /// The device has, or can have, biometric hardware, but none is currently
+  /// available.
+  ///
+  /// Examples include:
+  /// - Hardware that is currently in use by another application.
+  /// - Devices that have previously paired with bluetooth biometric hardware,
+  ///   but are not currently paired to it.
+  ///
+  /// Devices that could have removable hardware attached may return either this
+  /// or [noBiometricHardware] depending on the platform implementation.
+  /// Platforms should generally only return this code if the system provides
+  /// information indicating that the device has previously had such hardware.
+  biometricHardwareTemporarilyUnavailable,
+
+  /// Authentication has temporarily been locked out, and should be re-attempted
+  /// later.
+  ///
+  /// For example, devices may return this error after too many failed
+  /// authentication attempts.
+  temporaryLockout,
+
+  /// Biometric authentication has been locked until some other authentication
+  /// has succeeded.
+  ///
+  /// Applications that do not require biometric authentication should generally
+  /// handle this error by re-attempting authentication with fallback to
+  /// non-biometrics allowed. Applications that require biometrics should
+  /// prompt users to resolve the lockout.
+  biometricLockout,
+
+  /// The user indicated via system-provided UI that they want to use a fallback
+  /// authentication option instead of biometrics.
+  ///
+  /// Whether this can be returned depends on the platform implementation and
+  /// the authentication configuration options. Applications should generally
+  /// handle this error by offering the user an alternate authentication option.
+  userRequestedFallback,
+
+  /// The authentication attempt failed due to some device-level error.
+  ///
+  /// The [LocalAuthException.description] should contain more details about the
+  /// error.
+  deviceError,
+
+  /// The authentication attempt failed due to some unknown or unexpected error.
+  ///
+  /// The [LocalAuthException.description] should contain more details about the
+  /// error.
+  unknownError,
+}

packages/local_auth/local_auth_platform_interface/lib/types/auth_options.dart

@@ -21,6 +21,9 @@ class AuthenticationOptions {
   /// take the user to settings to add one. Anything that is not user fixable,
   /// such as no biometric sensor on device, will still result in
   /// a [PlatformException].
+  // This parameter still exists for backwards compatibility with local_auth
+  // 2.x, but implementers targeting local_auth 3.x or later should ignore it,
+  // as it will always be false.
   final bool useErrorDialogs;
 
   /// Used when the application goes into background for any reason while the

packages/local_auth/local_auth_platform_interface/lib/types/types.dart

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+export 'auth_exception.dart';
 export 'auth_messages.dart';
 export 'auth_options.dart';
 export 'biometric_type.dart';

packages/local_auth/local_auth_platform_interface/pubspec.yaml

@@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/local_auth/lo
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+local_auth%22
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 1.0.10
+version: 1.1.0
 
 environment:
   sdk: ^3.7.0

packages/local_auth/local_auth_platform_interface/test/default_method_channel_platform_test.dart

@@ -114,7 +114,6 @@ void main() {
           localizedReason: 'Insecure',
           options: const AuthenticationOptions(
             sensitiveTransaction: false,
-            useErrorDialogs: false,
             biometricOnly: true,
           ),
         );
@@ -123,7 +122,7 @@ void main() {
             'authenticate',
             arguments: <String, dynamic>{
               'localizedReason': 'Insecure',
-              'useErrorDialogs': false,
+              'useErrorDialogs': true,
               'stickyAuth': false,
               'sensitiveTransaction': false,
               'biometricOnly': true,
@@ -157,24 +156,44 @@ void main() {
         await localAuthentication.authenticate(
           authMessages: <AuthMessages>[],
           localizedReason: 'Insecure',
-          options: const AuthenticationOptions(
-            sensitiveTransaction: false,
-            useErrorDialogs: false,
-          ),
+          options: const AuthenticationOptions(sensitiveTransaction: false),
         );
         expect(log, <Matcher>[
           isMethodCall(
             'authenticate',
             arguments: <String, dynamic>{
               'localizedReason': 'Insecure',
-              'useErrorDialogs': false,
+              'useErrorDialogs': true,
               'stickyAuth': false,
               'sensitiveTransaction': false,
               'biometricOnly': false,
             },
           ),
         ]);
       });
+
+      test(
+        'legacy useErrorDialogs is passed for backward compatibility.',
+        () async {
+          await localAuthentication.authenticate(
+            authMessages: <AuthMessages>[],
+            localizedReason: 'Insecure',
+            options: const AuthenticationOptions(useErrorDialogs: false),
+          );
+          expect(log, <Matcher>[
+            isMethodCall(
+              'authenticate',
+              arguments: <String, dynamic>{
+                'localizedReason': 'Insecure',
+                'useErrorDialogs': false,
+                'stickyAuth': false,
+                'sensitiveTransaction': true,
+                'biometricOnly': false,
+              },
+            ),
+          ]);
+        },
+      );
     });
   });
 }