biometric_vault

Use when adding the biometric_vault Flutter package to an app or wiring a feature on top of it - storing tokens, passwords, or keys behind Face ID / Touch ID / fingerprint / device-credential authentication, building an app-lock gate, choosing StorageFileInitOptions, or setting the package up for Android, iOS, macOS, Linux, Windows, or web. Not for debugging an existing integration that fails at runtime (use troubleshoot-biometric-vault) and not for converting an app from the biometric_storage package (use migrate-from-biometric-storage).

Use when a Flutter app that currently uses the biometric_storage package (by authpass / Herbert Poul) should switch to biometric_vault - replacing the dependency, converting BiometricStorage/BiometricStorageFile/IosPromptInfo code, or when stored secrets from biometric_storage must survive the switch. Also applies when biometric_vault reads return null after such a switch. Not for fresh integrations without biometric_storage history (use integrate-biometric-vault).

Use when writing or fixing Dart/Flutter tests for app code that uses the biometric_vault package - unit or widget tests that must run without a device or emulator, tests simulating authentication failures (user cancellation, lockout, storage invalidation), or tests failing with MissingPluginException on the biometric_vault channel. Not for testing the plugin's own native implementations.

Use when an app using the biometric_vault Flutter package misbehaves at runtime - AuthException codes such as failedToStart or lockedOut, StorageInvalidatedException after users change biometric enrollment, SecurityError -34018 on macOS, reads returning null unexpectedly, prompts not appearing or appearing twice, silent-writes stores where writes succeed while reads keep failing, or biometric flows that behave differently on the iOS simulator than on real devices. Not for first-time package setup (use integrate-biometric-vault) and not for converting an app from biometric_storage (use migrate-from-biometric-storage).

Runtime verification recipe for biometric_vault - build, launch, and drive the plugin end to end on the iOS simulator with controllable biometry state.