[local_auth] Differentiate iOS authentication errors (#9705)

okorohelijah · web-flow · commit f0b272645902 · 2025-08-06T08:36:14.000-07:00
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.  [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
diff --git a/packages/local_auth/local_auth_darwin/CHANGELOG.md b/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.
diff --git a/packages/local_auth/local_auth_darwin/darwin/Tests/FLALocalAuthPluginTests.swift b/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()
diff --git a/packages/local_auth/local_auth_darwin/darwin/local_auth_darwin/Sources/local_auth_darwin/LocalAuthPlugin.swift b/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(
diff --git a/packages/local_auth/local_auth_darwin/darwin/local_auth_darwin/Sources/local_auth_darwin/messages.g.swift b/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.
diff --git a/packages/local_auth/local_auth_darwin/lib/local_auth_darwin.dart b/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);
     }
   }
 
diff --git a/packages/local_auth/local_auth_darwin/lib/src/messages.g.dart b/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.
diff --git a/packages/local_auth/local_auth_darwin/pigeons/messages.dart b/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 {
diff --git a/packages/local_auth/local_auth_darwin/pubspec.yaml b/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
diff --git a/packages/local_auth/local_auth_darwin/test/local_auth_darwin_test.dart b/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';
