Implement native biometric dialog invocation
epic-biometric-session-authentication-core-services-task-003 — Implement the core method in BiometricAuthService that invokes the native biometric authentication dialog via LocalAuthIntegration (local_auth Flutter plugin). Handles platform-specific dialog configuration for iOS (Face ID / Touch ID) and Android (fingerprint / face unlock), passes localized reason strings, and captures the raw platform result for further processing.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Use an _isAuthenticating boolean flag (or a Completer) to implement the concurrent call guard. Set it to true at the start of authenticate() and reset in a try/finally block. Pass AuthenticationOptions(stickyAuth: true, useErrorDialogs: true, biometricOnly: true) — biometricOnly: true ensures the OS does not offer a PIN/password fallback dialog itself (the Flutter app handles fallback via BiometricAuthFallbackRequired instead, giving full control of the UX). Map PlatformException error codes to BiometricAuthResult subtypes using flutter_local_auth's documented error codes: 'NotAvailable', 'NotEnrolled', 'LockedOut', 'PermanentlyLockedOut', 'UserCancel', 'UserFallback'.
Log unknown error codes to a diagnostic service (not analytics) with the sanitized message only. For localizedReason, accept it as a parameter rather than hardcoding — the caller (BLoC) retrieves it from the app's AppLocalizations. The biometric dialog invocation integrates with the Supabase session re-authentication flow: on BiometricAuthSuccess, the caller should call supabase.auth.refreshSession() to validate the session is still active before granting access.
Testing Requirements
Unit tests in test/services/biometric_auth_service_test.dart extending the test file from task-002. New test cases: (1) authenticate() when checkBiometricCapability returns unavailable → returns BiometricAuthUnavailable without calling authenticate on LocalAuthIntegration; (2) LocalAuthIntegration.authenticate returns true → BiometricAuthSuccess; (3) LocalAuthIntegration.authenticate returns false with cancellation error code → BiometricAuthCancelled; (4) LocalAuthIntegration.authenticate returns false with locked-out error code → BiometricAuthFailure; (5) LocalAuthIntegration.authenticate signals fallback (passcodeNotSet / notAvailable error codes) → BiometricAuthFallbackRequired; (6) concurrent call guard: second call while first is in-progress returns BiometricAuthFailure immediately without calling LocalAuthIntegration again. All tests use MockLocalAuthIntegration. Manual testing required on physical iOS device (Face ID and Touch ID) and physical Android device (fingerprint) — document results in test checklist.
Multiple concurrent callers (e.g., SessionResumeManager and a background sync service) could simultaneously detect a near-expired token and each invoke SupabaseSessionManager.refreshSession(), causing duplicate refresh API calls and potentially a token invalidation race condition on the Supabase Auth server. This can result in one caller receiving a valid refreshed token while another receives a 401, causing intermittent authentication failures.
Mitigation & Contingency
Mitigation: Implement a single-flight pattern inside SupabaseSessionManager so that concurrent refresh calls coalesce into one in-flight request. Use a Dart Completer or AsyncMemoizer to ensure all waiters receive the same refreshed token. Write a concurrent integration test to validate the single-flight behaviour.
Contingency: If the single-flight pattern introduces deadlocks or timeout complexity, fall back to a mutex-based lock with a 10-second timeout, logging a warning if the lock is held longer than expected, and triggering a full re-login if the refresh ultimately fails.
Supabase Row-Level Security policies evaluate the JWT claims (user_id, role, org_id) on every query. If the refreshed token contains stale or changed claims — for example if a coordinator's role was updated server-side — RLS may silently block data access even though the session appears valid from the client's perspective, causing confusing empty screens rather than an authentication error.
Mitigation & Contingency
Mitigation: After every token refresh, decode the new JWT and compare key claims (role, org_id) with the cached values. If claims have changed, emit a session-claims-changed event that triggers a role re-resolution and navigation reset. Document this behaviour in the SupabaseSessionManager API contract.
Contingency: If claims drift is detected in production and causes data visibility issues, provide a force-refresh mechanism in the UI (pull-to-refresh on home screen) that clears cached role state and re-fetches from Supabase, accompanied by a user-visible toast indicating the session was refreshed.
Allowing session resumption from cached local token when offline introduces a window where a revoked or invalidated session can still grant app access. For example, if a coordinator deactivates a peer mentor's account while the mentor is offline, the mentor continues to have access until connectivity is restored and the token is validated server-side.
Mitigation & Contingency
Mitigation: Set a maximum offline grace period (e.g., 24 hours) stored alongside the token in SecureSessionStorage. If the grace period is exceeded, force a full credential re-login regardless of connectivity status. Scope offline access to read-only operations only, requiring connectivity for any write that reaches Supabase.
Contingency: If the offline grace period logic is found to be insufficient for compliance, implement remote session invalidation via a lightweight push notification that clears SecureSessionStorage even when the app is backgrounded, using FCM with a data-only message.