[PM-41332] [BWA-260] fix: Recover from missing biometric key on Authenticator unlock

[stefan-jevtic]

🎟️ Tracking

Fixes #2732 (BWA-260)

📔 Objective

The Authenticator app can end up permanently locked behind a "Use Face ID to Unlock" button that does nothing when tapped.

Cause

getBiometricUnlockStatus() reports .available(_, enabled: true) from two independent sources: the device's biometry status, and the user's stored preference. Those can disagree. The stored preference survives an app reinstall and an iCloud restore; the biometric key in the keychain does not.

When the preference says enabled but the key is gone, AppCoordinator routes to the unlock screen, and VaultUnlockProcessor.unlockWithBiometrics() calls getUserAuthKey(), which throws BiometricsServiceError.getAuthKeyFailed. That error was funnelled into loadData(), which re-reads the same two unchanged sources and produces the same enabled status. Nothing in the state changes and no error surfaces.

The keychain lookup fails on a missing item, so iOS never presents a biometric prompt — which is why the button reads as completely unresponsive rather than as a failed scan. The key cannot be recovered, so every subsequent tap and every relaunch repeats the same dead end.

The reported workaround — revoking the app's biometrics permission in the Settings app — works because it flips the device half of the status to unavailable, so AppCoordinator skips the unlock screen entirely. It depends on iOS showing a Face ID toggle for the app, and iOS only shows that toggle once the app has evaluated a biometric policy at least once. A user who reinstalled before ever granting the permission has no toggle and no way back in (#2732 comment).

Fix

Handle BiometricsServiceError.getAuthKeyFailed explicitly: log it, clear the stale preference via setBiometricUnlockKey(authKey: nil), and complete auth.

This mirrors the recovery BitwardenShared's VaultUnlockProcessor already performs for the same error — the Authenticator's copy of that processor was simply missing the case. The end state is identical to what the Settings-app workaround produces today, so it grants no access the user cannot already obtain, and it reaches the users who currently have no workaround at all. Re-enabling biometric unlock from the app's own settings then goes through evaluateBiometricPolicy(), which requests the permission and writes a fresh key, so the toggle recovers properly instead of resurrecting the broken state.

Other error cases are unchanged: cancellation is still a no-op, and recoverable failures still fall through to loadData() so a retry stays possible.

Tests

Adds VaultUnlockProcessorTests, which did not previously exist for the Authenticator. It covers the lockout regression, the successful-unlock path, cancellation, a recoverable error, and the case where clearing the preference itself fails.

📸 Screenshots

Not applicable — no UI changes. The existing unlock screen is unchanged; it is now reached only when biometric unlock can actually succeed.

[CLAassistant]

All committers have signed the CLA.

[bitwarden-bot]

Thank you for your contribution! We've added this to our internal Community PR board for review.
ID: PM-41332
Link: https://bitwarden.atlassian.net/browse/PM-41332

Details on our contribution process can be found here: https://contributing.bitwarden.com/contributing/pull-requests/community-pr-process.