[local_auth] Differentiate iOS authentication errors (#9705)

On iOS, the plugin previously returned a generic `NotAvailable`
PlatformException for several distinct failure conditions. This made
it impossible for developers to handle specific cases e.g user
cancellation.

This change ensures the plugin returns specific error codes for distinct
user actions on iOS:

- Returns UserCancelled when a user cancels the authentication prompt.
- Returns UserFallback when a user selects the fallback option (e.g.,
"Enter Password").
- Returns BiometricNotAvailable when the device does not have biometrics
enabled or available.

Fixes flutter/flutter#148942

## Pre-Review Checklist

- [X] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [X] I read the [Tree Hygiene] page, which explains my
responsibilities.
- [X] I read and followed the [relevant style guides] and ran [the
auto-formatter].
- [X] I signed the [CLA].
- [X] The title of the PR starts with the name of the package surrounded
by square brackets, e.g. `[shared_preferences]`
- [X] I [linked to at least one issue that this PR fixes] in the
description above.
- [X] I updated `pubspec.yaml` with an appropriate new version according
to the [pub versioning philosophy], or I have commented below to
indicate which [version change exemption] this PR falls under[^1].
- [X] I updated `CHANGELOG.md` to add a description of the change,
[following repository CHANGELOG style], or I have commented below to
indicate which [CHANGELOG exemption] this PR falls under[^1].
- [X] I updated/added any relevant documentation (doc comments with
`///`).
- [X] I added new tests to check the change I am making, or I have
commented below to indicate which [test exemption] this PR falls
under[^1].
- [X] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

[^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.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/packages/blob/main/CONTRIBUTING.md
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md
[relevant style guides]:
https://github.com/flutter/packages/blob/main/CONTRIBUTING.md#style
[the auto-formatter]:
https://github.com/flutter/packages/blob/main/script/tool/README.md#format-code
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[linked to at least one issue that this PR fixes]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#overview
[pub versioning philosophy]: https://dart.dev/tools/pub/versioning
[version change exemption]:
https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#version
[following repository CHANGELOG style]:
https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style
[CHANGELOG exemption]:
https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog
[test exemption]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#tests

Author: okorohelijah

packages/local_auth/local_auth_darwin/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.6.0
+
+*  Provides more specific error codes on iOS for authentication failures.
+    * `LockedOut` is now returned for biometric lockout.
+    * `UserCancelled` is now returned when the user cancels the prompt.
+    * `UserFallback` is now returned when the user selects the fallback option.
+
 ## 1.5.0
 
 * Converts implementation to Swift.

packages/local_auth/local_auth_darwin/darwin/Tests/FLALocalAuthPluginTests.swift

@@ -266,6 +266,99 @@ class LocalAuthPluginTests: XCTestCase {
     self.waitForExpectations(timeout: timeout)
   }
 
+  @MainActor
+  func testFailedAuthWithErrorUserCancelled() {
+    let stubAuthContext = StubAuthContext()
+    let alertFactory = StubAlertFactory()
+    let viewProvider = StubViewProvider()
+    let plugin = LocalAuthPlugin(
+      contextFactory: StubAuthContextFactory(contexts: [stubAuthContext]),
+      alertFactory: alertFactory,
+      viewProvider: viewProvider)
+
+    let strings = createAuthStrings()
+    stubAuthContext.evaluateError = NSError(
+      domain: "LocalAuthentication", code: LAError.userCancel.rawValue)
+
+    let expectation = expectation(description: "Result is called for user cancel")
+    plugin.authenticate(
+      options: AuthOptions(biometricOnly: false, sticky: false, useErrorDialogs: false),
+      strings: strings
+    ) { resultDetails in
+      XCTAssertTrue(Thread.isMainThread)
+      switch resultDetails {
+      case .success(let successDetails):
+        XCTAssertEqual(successDetails.result, .errorUserCancelled)
+      case .failure(let error):
+        XCTFail("Unexpected error: \(error)")
+      }
+      expectation.fulfill()
+    }
+    self.waitForExpectations(timeout: timeout)
+  }
+
+  @MainActor
+  func testFailedAuthWithErrorUserFallback() {
+    let stubAuthContext = StubAuthContext()
+    let alertFactory = StubAlertFactory()
+    let viewProvider = StubViewProvider()
+    let plugin = LocalAuthPlugin(
+      contextFactory: StubAuthContextFactory(contexts: [stubAuthContext]),
+      alertFactory: alertFactory,
+      viewProvider: viewProvider)
+
+    let strings = createAuthStrings()
+    stubAuthContext.evaluateError = NSError(
+      domain: "LocalAuthentication", code: LAError.userFallback.rawValue)
+
+    let expectation = expectation(description: "Result is called for user fallback")
+    plugin.authenticate(
+      options: AuthOptions(biometricOnly: false, sticky: false, useErrorDialogs: false),
+      strings: strings
+    ) { resultDetails in
+      XCTAssertTrue(Thread.isMainThread)
+      switch resultDetails {
+      case .success(let successDetails):
+        XCTAssertEqual(successDetails.result, .errorUserFallback)
+      case .failure(let error):
+        XCTFail("Unexpected error: \(error)")
+      }
+      expectation.fulfill()
+    }
+    self.waitForExpectations(timeout: timeout)
+  }
+
+  @MainActor
+  func testFailedAuthWithErrorBiometricNotAvailable() {
+    let stubAuthContext = StubAuthContext()
+    let alertFactory = StubAlertFactory()
+    let viewProvider = StubViewProvider()
+    let plugin = LocalAuthPlugin(
+      contextFactory: StubAuthContextFactory(contexts: [stubAuthContext]),
+      alertFactory: alertFactory,
+      viewProvider: viewProvider)
+
+    let strings = createAuthStrings()
+    stubAuthContext.canEvaluateError = NSError(
+      domain: "LocalAuthentication", code: LAError.biometryNotAvailable.rawValue)
+
+    let expectation = expectation(description: "Result is called for biometric not available")
+    plugin.authenticate(
+      options: AuthOptions(biometricOnly: false, sticky: false, useErrorDialogs: false),
+      strings: strings
+    ) { resultDetails in
+      XCTAssertTrue(Thread.isMainThread)
+      switch resultDetails {
+      case .success(let successDetails):
+        XCTAssertEqual(successDetails.result, .errorBiometricNotAvailable)
+      case .failure(let error):
+        XCTFail("Unexpected error: \(error)")
+      }
+      expectation.fulfill()
+    }
+    self.waitForExpectations(timeout: timeout)
+  }
+
   @MainActor
   func testFailedWithUnknownErrorCode() {
     let stubAuthContext = StubAuthContext()

packages/local_auth/local_auth_darwin/darwin/local_auth_darwin/Sources/local_auth_darwin/LocalAuthPlugin.swift

@@ -381,6 +381,12 @@ public final class LocalAuthPlugin: NSObject, FlutterPlugin, LocalAuthApi, @unch
         return
       }
       result = errorCode == .passcodeNotSet ? .errorPasscodeNotSet : .errorNotEnrolled
+    case .userCancel:
+      result = .errorUserCancelled
+    case .userFallback:
+      result = .errorUserFallback
+    case .biometryNotAvailable:
+      result = .errorBiometricNotAvailable
     case .biometryLockout:
       DispatchQueue.main.async { [weak self] in
         self?.showAlert(

packages/local_auth/local_auth_darwin/darwin/local_auth_darwin/Sources/local_auth_darwin/messages.g.swift

@@ -1,7 +1,7 @@
 // Copyright 2013 The Flutter Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-// Autogenerated from Pigeon (v25.3.2), do not edit directly.
+// Autogenerated from Pigeon (v25.5.0), do not edit directly.
 // See also: https://pub.dev/packages/pigeon
 
 import Foundation
@@ -141,6 +141,12 @@ enum AuthResult: Int {
   case errorNotEnrolled = 3
   /// No passcode is set.
   case errorPasscodeNotSet = 4
+  /// The user cancelled the authentication.
+  case errorUserCancelled = 5
+  /// The user tapped the "Enter Password" fallback.
+  case errorUserFallback = 6
+  /// The user biometrics is disabled.
+  case errorBiometricNotAvailable = 7
 }
 
 /// Pigeon equivalent of the subset of BiometricType used by iOS.

packages/local_auth/local_auth_darwin/lib/local_auth_darwin.dart

@@ -75,6 +75,21 @@ class LocalAuthDarwin extends LocalAuthPlatform {
             code: 'PasscodeNotSet',
             message: resultDetails.errorMessage,
             details: resultDetails.errorDetails);
+      case AuthResult.errorUserCancelled:
+        throw PlatformException(
+            code: 'UserCancelled',
+            message: resultDetails.errorMessage,
+            details: resultDetails.errorDetails);
+      case AuthResult.errorBiometricNotAvailable:
+        throw PlatformException(
+            code: 'BiometricNotAvailable',
+            message: resultDetails.errorMessage,
+            details: resultDetails.errorDetails);
+      case AuthResult.errorUserFallback:
+        throw PlatformException(
+            code: 'UserFallback',
+            message: resultDetails.errorMessage,
+            details: resultDetails.errorDetails);
     }
   }
 

packages/local_auth/local_auth_darwin/lib/src/messages.g.dart

@@ -1,7 +1,7 @@
 // Copyright 2013 The Flutter Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-// Autogenerated from Pigeon (v25.3.2), do not edit directly.
+// Autogenerated from Pigeon (v25.5.0), do not edit directly.
 // See also: https://pub.dev/packages/pigeon
 // ignore_for_file: public_member_api_docs, non_constant_identifier_names, avoid_as, unused_import, unnecessary_parenthesis, prefer_null_aware_operators, omit_local_variable_types, unused_shown_name, unnecessary_import, no_leading_underscores_for_local_identifiers
 
@@ -49,6 +49,15 @@ enum AuthResult {
 
   /// No passcode is set.
   errorPasscodeNotSet,
+
+  /// The user cancelled the authentication.
+  errorUserCancelled,
+
+  /// The user tapped the "Enter Password" fallback.
+  errorUserFallback,
+
+  /// The user biometrics is disabled.
+  errorBiometricNotAvailable,
 }
 
 /// Pigeon equivalent of the subset of BiometricType used by iOS.

packages/local_auth/local_auth_darwin/pigeons/messages.dart

@@ -49,6 +49,15 @@ enum AuthResult {
 
   /// No passcode is set.
   errorPasscodeNotSet,
+
+  /// The user cancelled the authentication.
+  errorUserCancelled,
+
+  /// The user tapped the "Enter Password" fallback.
+  errorUserFallback,
+
+  /// The user biometrics is disabled.
+  errorBiometricNotAvailable,
 }
 
 class AuthOptions {

packages/local_auth/local_auth_darwin/pubspec.yaml

@@ -2,7 +2,7 @@ name: local_auth_darwin
 description: iOS implementation of the local_auth plugin.
 repository: https://github.com/flutter/packages/tree/main/packages/local_auth/local_auth_darwin
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+local_auth%22
-version: 1.5.0
+version: 1.6.0
 
 environment:
   sdk: ^3.6.0
@@ -32,7 +32,7 @@ dev_dependencies:
   flutter_test:
     sdk: flutter
   mockito: ^5.4.4
-  pigeon: ^25.3.2
+  pigeon: ^26.0.0
 
 topics:
   - authentication

packages/local_auth/local_auth_darwin/test/local_auth_darwin_test.dart

@@ -372,6 +372,71 @@ void main() {
                     errorDetails)));
       });
 
+      test('converts errorUserCancelled to PlatformException', () async {
+        const String errorMessage = 'The user cancelled authentication.';
+        const String errorDetails = 'com.apple.LocalAuthentication';
+        when(api.authenticate(any, any)).thenAnswer((_) async =>
+            AuthResultDetails(
+                result: AuthResult.errorUserCancelled,
+                errorMessage: errorMessage,
+                errorDetails: errorDetails));
+
+        expect(
+            () async => plugin.authenticate(
+                localizedReason: 'reason', authMessages: <AuthMessages>[]),
+            throwsA(isA<PlatformException>()
+                .having(
+                    (PlatformException e) => e.code, 'code', 'UserCancelled')
+                .having(
+                    (PlatformException e) => e.message, 'message', errorMessage)
+                .having((PlatformException e) => e.details, 'details',
+                    errorDetails)));
+      });
+
+      test('converts errorUserFallback to PlatformException', () async {
+        const String errorMessage = 'The user chose to use the fallback.';
+        const String errorDetails = 'com.apple.LocalAuthentication';
+        when(api.authenticate(any, any)).thenAnswer((_) async =>
+            AuthResultDetails(
+                result: AuthResult.errorUserFallback,
+                errorMessage: errorMessage,
+                errorDetails: errorDetails));
+
+        expect(
+            () async => plugin.authenticate(
+                localizedReason: 'reason', authMessages: <AuthMessages>[]),
+            throwsA(isA<PlatformException>()
+                .having((PlatformException e) => e.code, 'code', 'UserFallback')
+                .having(
+                    (PlatformException e) => e.message, 'message', errorMessage)
+                .having((PlatformException e) => e.details, 'details',
+                    errorDetails)));
+      });
+
+      test('converts errorBiometricNotAvailable to PlatformException',
+          () async {
+        const String errorMessage =
+            'Biometrics are not available on this device.';
+        const String errorDetails = 'com.apple.LocalAuthentication';
+        when(api.authenticate(any, any)).thenAnswer((_) async =>
+            AuthResultDetails(
+                result: AuthResult.errorBiometricNotAvailable,
+                errorMessage: errorMessage,
+                errorDetails: errorDetails));
+
+        expect(
+            () async => plugin.authenticate(
+                localizedReason: 'reason', authMessages: <AuthMessages>[]),
+            throwsA(isA<PlatformException>()
+                // The code here should match what you defined in your Dart switch statement.
+                .having((PlatformException e) => e.code, 'code',
+                    'BiometricNotAvailable')
+                .having(
+                    (PlatformException e) => e.message, 'message', errorMessage)
+                .having((PlatformException e) => e.details, 'details',
+                    errorDetails)));
+      });
+
       test('converts errorPasscodeNotSet to legacy PlatformException',
           () async {
         const String errorMessage = 'a message';