Biometric Auth Screen — Face ID and fingerprint prompt
epic-bankid-vipps-login-ui-task-007 — Implement the Biometric Authentication Screen using the Flutter local_auth package. The screen must show a branded prompt explaining why biometric authentication is requested, trigger the OS-native Face ID or fingerprint dialog, and pass the authentication result to BiometricAuthService. The screen must only display on subsequent logins after initial BankID or Vipps authentication has completed successfully.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Guard the route to this screen in the router configuration: use a redirect that checks BiometricAuthService.isEnrolledUser() and reroutes to the method selector if false. This prevents direct navigation to the biometric screen by non-enrolled users. The local_auth.authenticate() call must include localizedReason: 'Sign in to [App Name]' — this string appears in the OS prompt and must be concise and clear. Trigger the OS dialog in initState via a post-frame callback to ensure the branded screen renders first: WidgetsBinding.instance.addPostFrameCallback((_) => _triggerBiometric()).
Handle the case where the user is on a device that does not support biometrics by checking local_auth.isDeviceSupported() on screen entry and immediately navigating to the method selector. The BiometricEnrollmentRecord stored in flutter_secure_storage should be written after the first successful BankID or Vipps login (in those respective services), not in this screen — this screen only reads the record to gate access. When biometrics become unavailable after the screen is shown (race condition on older devices), catch the PlatformException from local_auth and transition to the unavailable state gracefully. Do not implement custom retry logic — rely on the OS-provided retry flow from local_auth, which handles the OS-enforced attempt limits.
Testing Requirements
Unit tests for BiometricAuthService: (1) isEnrolledUser() returns false when no enrollment record exists; (2) authenticate() calls local_auth.authenticate() with correct parameters; (3) detects Face ID vs fingerprint from getAvailableBiometrics() response; (4) handles LocalAuthException with correct BiometricAuthState transition. Widget tests using mocked local_auth: (1) assert biometric type-specific copy is rendered correctly for Face ID and fingerprint scenarios; (2) simulate successful authentication → assert navigation to main screen; (3) simulate failed authentication → assert fallback UI appears; (4) tap 'Use a different sign-in method' → assert navigation back to method selector; (5) simulate unavailability (biometrics removed) → assert explanatory message and redirect. Platform permission tests: assert NSFaceIDUsageDescription key is present in iOS Info.plist. Manual device testing: test on physical iPhone with Face ID, physical iPhone with Touch ID, and physical Android with fingerprint reader.
BankID on mobile uses a WebView or external app redirect that has known compatibility issues with Flutter's WebView package on certain Android versions. BankID's JavaScript-heavy broker pages may also trigger CSP or mixed-content errors in a Flutter WebView, preventing the authentication flow from completing.
Mitigation & Contingency
Mitigation: Use the flutter_inappwebview package (more mature than webview_flutter for complex OAuth pages) and validate BankID WebView rendering on the broker's test environment before integrating with the service layer. Prefer external browser redirect where the broker supports it.
Contingency: If WebView approach fails for certain BankID brokers, implement the full external browser redirect + deep link callback pattern as the primary flow and treat WebView as a fallback only.
The OAuth redirect flows (both Vipps and BankID) temporarily move the user outside the Flutter app into an external browser or the Vipps/BankID app. Screen reader users may lose focus context during this transition and become disoriented when the app callback returns them to the loading state, failing the WCAG 2.2 AA mandate.
Mitigation & Contingency
Mitigation: Implement explicit accessibility announcements (live region announcements) at each transition point: when launching the external flow ('Opening Vipps'), during the loading wait state ('Waiting for Vipps confirmation'), and on return ('Login successful' or 'Login failed — please try again'). Test with VoiceOver on iOS and TalkBack on Android during development.
Contingency: If OAuth transition accessibility is unresolvable on a specific platform, add an explicit accessibility user guide in the onboarding flow explaining the external app redirect behavior to set user expectations.
Biometric UI varies significantly across devices — Face ID (iPhone), fingerprint sensor (most Android), front-facing camera biometrics (some Android), and devices with no biometrics at all. Flutter's local_auth handles the OS dialog but the surrounding UI must gracefully handle all these cases, and testing coverage for all permutations is difficult.
Mitigation & Contingency
Mitigation: Use local_auth's getAvailableBiometrics() to detect the exact biometric type and render appropriate iconography (Face ID icon vs. fingerprint icon). For devices with no biometrics, skip the biometric screen entirely and route directly to full re-authentication.
Contingency: If a specific device configuration produces unexpected local_auth behavior in production, implement a user-accessible toggle in Settings to disable biometric login entirely, routing those users to the standard BankID/Vipps flow without biometrics.