🏠 Overview › ✅ Implementation Tasks ›✅ epic-biometric-session-authentication-foundation-task-009

Register LocalAuthIntegration as Riverpod provider

epic-biometric-session-authentication-foundation-task-009 — Create a Riverpod provider for LocalAuthIntegration following the same conventions used for SecureSessionStorage in task-008. Expose the provider so that the BiometricAuthService and other dependents can consume LocalAuthIntegration without direct instantiation, enabling easy mocking in tests.

high priority low complexity backend pending backend specialist Tier 3

Acceptance Criteria

A top-level Riverpod provider named localAuthIntegrationProvider is declared and exposes an ILocalAuthIntegration instance
The provider is a Provider<ILocalAuthIntegration> consistent with secureSessionStorageProvider conventions
The LocalAuthentication() instance from the local_auth package is created inside the provider factory
The provider file is co-located with secureSessionStorageProvider or in the shared infrastructure providers directory
The provider is globally scoped with no autoDispose (authentication state must survive navigation)
All downstream consumers (BiometricAuthService provider, etc.) read localAuthIntegrationProvider via ref.read or ref.watch — no direct instantiation
A test override via ProviderContainer(overrides: [localAuthIntegrationProvider.overrideWithValue(fakeAuth)]) works correctly

Technical Requirements

frameworks
Flutter
Riverpod (flutter_riverpod)
local_auth
apis
Riverpod Provider
LocalAuthentication constructor
data models
ILocalAuthIntegration
LocalAuthIntegrationImpl
performance requirements
Provider creation is synchronous — LocalAuthentication() constructor is lightweight
No keepAlive concerns — provider is stateless infrastructure
security requirements
LocalAuthentication instance must not be shared across isolates
Provider must not retain authentication results in memory

Execution Context

Execution Tier
Tier 3

Tier 3 - 413 tasks

Can start after Tier 2 completes

Implementation Notes

Mirror the structure of secureSessionStorageProvider exactly for consistency. If riverpod_generator is used, annotate with @Riverpod(keepAlive: true). Place in the same providers file or directory as the storage provider to keep infrastructure wiring centralised. The BiometricAuthService provider (a future task) will read both secureSessionStorageProvider and localAuthIntegrationProvider via ref.read inside its own provider factory — this task is purely the leaf node in that dependency graph.

Testing Requirements

Unit test using ProviderContainer: (1) localAuthIntegrationProvider resolves without throwing, (2) overriding with a fake ILocalAuthIntegration is reflected when a dependent provider reads localAuthIntegrationProvider. These tests are wiring-only — behavioural coverage is in task-011.

Component
Local Auth Integration
infrastructure low
Dependencies (1)
Implement the LocalAuthIntegration class wrapping the local_auth LocalAuthentication instance. Expose: isAvailable() returning Future<bool>, getAvailableBiometrics() returning Future<List<BiometricType>>, authenticate(localizedReason: String) returning Future<Result<void, LocalAuthFailure>>. Translate BiometricType values from local_auth enums to the domain BiometricType enum. Use the LocalAuthFailure mapper from task-006. epic-biometric-session-authentication-foundation-task-007
Epic Risks (3)
high impact medium prob technical

iOS Keychain access requires correct entitlement configuration and provisioning profile setup. Misconfigured entitlements cause silent failures in CI/CD and on physical devices, where the plugin appears to work in the simulator but fails at runtime. This can delay foundation delivery and block all downstream epics.

Mitigation & Contingency

Mitigation: Add a dedicated integration test running on a physical iOS device early in the epic. Document required entitlements and provisioning steps in a developer runbook. Validate Keychain access in the CI pipeline using an iOS simulator with correct entitlements enabled.

Contingency: If Keychain entitlements cannot be resolved quickly, temporarily use in-memory storage behind the SecureSessionStorage interface to unblock downstream epics, then resolve the Keychain issue in a hotfix before release.

medium impact medium prob dependency

The Flutter local_auth plugin has a history of breaking API changes between major versions, and its Android implementation depends on BiometricPrompt which behaves differently across Android API levels (23-34). An incompatible plugin version or unexpected Android API behaviour can cause authentication failures on a significant portion of the target device fleet.

Mitigation & Contingency

Mitigation: Pin local_auth to a specific stable version in pubspec.yaml. Test against Android API levels 23, 28, and 33 in the CI matrix. Review the plugin changelog and migration guide before adopting any version bump.

Contingency: If the pinned version proves incompatible with target devices, evaluate flutter_local_auth_android as a replacement or fork the plugin adapter to isolate the breaking surface.

high impact low prob security

If users upgrade from a version of the app that stored session data in non-encrypted storage (SharedPreferences), a migration path is required. Failing to migrate silently leaves old tokens in plain storage, creating a security gap and potentially causing confusing authentication state on first launch of the new version.

Mitigation & Contingency

Mitigation: Audit existing storage usage across the codebase before writing SecureSessionStorage. If legacy plain storage keys exist, implement a one-time migration routine that reads from SharedPreferences, writes to Keychain/Keystore, and deletes the plain-text entry.

Contingency: If migration is discovered late, ship the migration as a mandatory patch release before the biometric feature is enabled for users, and add a startup check that blocks biometric opt-in until migration is confirmed complete.

Quick Links
All Tasks Execution Plan