Local Auth Integration
Component Detail
Description
Thin adapter around the Flutter local_auth package that abstracts platform-specific configuration for iOS (Face ID / Touch ID) and Android (fingerprint / face unlock). Provides a clean async API consumed by BiometricAuthService, hiding package-level permission handling.
local-auth-integration
Summaries
Local Auth Integration delivers seamless biometric login across iOS and Android devices, enabling users to authenticate with Face ID, Touch ID, or fingerprint unlock instead of passwords. This directly reduces friction at the login step, improving user retention and session continuity metrics. By abstracting platform-specific permission complexity, it ensures compliance with Apple and Google security guidelines out of the box, reducing the risk of App Store or Play Store rejections. The investment in this adapter pays dividends by making biometric authentication a stable, reusable capability that any future feature requiring identity verification can leverage without additional platform engineering effort.
Local Auth Integration is a low-complexity adapter component with no external service dependencies, making it a low-risk deliverable. Development effort is primarily focused on correctly configuring iOS NSFaceIDUsageDescription and Android USE_BIOMETRIC permission declarations in platform build files — tasks that are well-documented but require careful QA across real devices. Testing must cover at minimum four device scenarios: iOS Face ID, iOS Touch ID, Android fingerprint, and Android face unlock. Simulator testing is insufficient for biometric flows; physical device access must be planned in the test environment.
No runtime blockers exist since this component has zero dependencies on other services, so it can be developed and tested in isolation early in the sprint.
Local Auth Integration is a thin wrapper around the Flutter local_auth package, exposing a typed Dart async API that isolates all platform-specific concerns from the rest of the application. The four core methods — isDeviceSupported(), getAvailableBiometrics(), authenticate(), and cancelAuthentication() — map directly to local_auth primitives but return domain-level types. BiometricType enumeration abstracts platform enum differences between iOS and Android. LocalAuthException subtypes are translated to application-level domain error codes, preventing local_auth-specific exceptions from leaking into business logic layers.
This component has no dependencies and is consumed exclusively by BiometricAuthService. iOS integration requires NSFaceIDUsageDescription in Info.plist; Android requires USE_BIOMETRIC in AndroidManifest.xml. Evolution considerations include handling degraded biometric states (e.g., too many failed attempts) by surfacing structured error codes rather than raw plugin exceptions.
Responsibilities
- Wrap local_auth plugin with typed Dart interfaces
- Handle iOS NSFaceIDUsageDescription and Android USE_BIOMETRIC permission declarations
- Provide platform-agnostic BiometricType enumeration
- Translate LocalAuthException subtypes to domain error codes
Interfaces
isDeviceSupported()
getAvailableBiometrics()
authenticate(LocalizedReason, AuthOptions)
cancelAuthentication()
Relationships
Used Integrations (1)
External integrations and APIs this component relies on