[local_auth] Differentiate iOS authentication errors

[okorohelijah]

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

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• 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¹.
• 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¹.
• I updated/added any relevant documentation (doc comments with ///).
• 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¹.
• 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. 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.

Footnotes

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. ↩ ↩² ↩³

[gemini-code-assist]

Code Review

This pull request enhances iOS authentication error handling by mapping native LAError codes to more specific PlatformExceptions, improving the developer experience. The changes are well-structured and include new test cases for the added error conditions. I've provided feedback to improve code clarity and maintainability, primarily focusing on code style and formatting in the generated files, as well as enum ordering.

[LouiseHsu]

I took a quick skim and it looks pretty good, but I think this PR might need tests added to https://github.com/flutter/packages/blob/main/packages/local_auth/local_auth_darwin/darwin/Tests/FLALocalAuthPluginTests.swift ?

[stuartmorgan-g]

Changing the codes of existing exceptions is potentially client-breaking. Is there a compelling reason this needs to be done as a semi-breaking change just for iOS, still using the anti-pattern of requiring clients to do string matching against magic, undocumented string values, rather than doing a full breaking change to correctly fix this across all implemenations?

[okorohelijah]

@stuartmorgan-g Please can you clarify what you mean ? I don't think i altered any original exceptions - I only added more exceptions

[stuartmorgan-g]

I don't think i altered any original exceptions

How so? The PR description lists three cases where a specific case used to have one exception code, and now has a different code. Anyone who has code trying to handle those cases by matching the exception code string (e.g., by providing a list of possible problems to the user) will now not have that code triggered.

It's true that the old situation wasn't good and this allows for better handler targeting going forward, but this change could still require people to update their code, and it seems less than ideal to do that twice (once with this change, and then again later to use consistent, structured exceptions) rather than going directly to the final state.

[okorohelijah]

@stuartmorgan-g I appreciate you taking the time to clarify. I apologize my PR description was not clear (i have updated it).

My approach is that since so many different errors were all funneled into the generic NotAvailable code, I am simply adding new, more specific exceptions(there were no previous implementations of these exceptions)

However, I now understand your point that this is a semi-breaking change in the sense that developers who were previously handling a user cancellation by checking for e.code == 'NotAvailable' would find that their logic no longer triggers after this change, as they would now need to check for the new, more specific code.

[LouiseHsu]

left a minor comment on the changelog, but otherwise lgtm!

[stuartmorgan-g]

LGTM