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

Add flutter_secure_storage and local_auth dependencies

epic-biometric-session-authentication-foundation-task-001 — Add flutter_secure_storage and local_auth packages to pubspec.yaml. Pin to versions compatible with the project's Flutter SDK. Run pub get and verify no dependency conflicts with existing Supabase and Riverpod packages.

critical priority low complexity infrastructure pending infrastructure specialist Tier 0

Acceptance Criteria

flutter_secure_storage is added to pubspec.yaml under dependencies with a pinned version compatible with the project's current Flutter SDK
local_auth is added to pubspec.yaml under dependencies with a pinned version compatible with the project's current Flutter SDK
flutter pub get completes with exit code 0 and no version conflict errors in the output
No existing packages (supabase_flutter, flutter_riverpod, go_router) have their resolved versions changed by the addition
dart pub deps --style=tree shows both packages resolved without conflicts
A simple smoke test (import of both packages in a throwaway file) compiles without errors via flutter build apk --debug or flutter build ios --simulator
pubspec.lock is committed alongside pubspec.yaml so all team members use identical resolved versions

Technical Requirements

frameworks
Flutter SDK (verify minimum SDK constraint in pubspec.yaml before pinning versions)
flutter_secure_storage (^9.0.0 or latest compatible)
local_auth (^2.3.0 or latest compatible)
performance requirements
pub get must complete within 60 seconds on a standard CI machine
security requirements
Do not add dev-only packages to the main dependencies block — keep flutter_secure_storage and local_auth in the production dependencies section
Verify that neither package introduces transitive dependencies with known CVEs by checking pub.dev security advisories

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Before adding, check pub.dev for the latest stable version of both packages and verify their Flutter SDK compatibility ranges against the project's sdk constraint in pubspec.yaml. Add packages alphabetically within the dependencies block to maintain consistency. If the project uses Melos or a monorepo setup, ensure the packages are added to the correct package's pubspec.yaml (the mobile app package, not a shared library). After pub get, inspect the diff in pubspec.lock carefully — if more than 10 transitive packages changed versions, investigate before committing.

Common conflict: local_auth requires a minimum iOS deployment target of 9.0 and Android minSdk 21 — verify these are already satisfied in the project. Do not run flutter pub upgrade as part of this task — only add the two specified packages.

Testing Requirements

After running flutter pub get, run flutter analyze to confirm no new lint warnings are introduced by the added packages. Run flutter test to confirm the existing test suite still passes — no regressions from dependency additions. Verify the dependency resolution by running dart pub deps and confirming both packages appear in the resolved tree. No new test files are required for this task itself.

Component
Secure Session Storage
data low
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