biometric_secure_vault 1.0.0

Secure key-value storage gated by biometric authentication with change detection and PIN fallback.

Biometric Secure Vault

Secure key-value storage for Flutter that gates sensitive data access behind biometric authentication (FaceID, Fingerprint, or Iris).

Overview

Storing sensitive data like authentication tokens or private keys in standard storage is a security risk. This package ensures that data stored in the platform's secure hardware (Keychain on iOS, Keystore on Android) is only released after a successful biometric challenge.

Key Features

• Hardware-Gated Access: Cryptographically tie data retrieval to a successful biometric scan.
• Change Detection: Detect if the device's biometric set has been modified (e.g., a new fingerprint added) since the last write.
• Passcode Fallback: Optional support for device PIN/Pattern if biometrics are unavailable.
• Type-Safe Results: Uses sealed classes to handle success, cancellation, lockouts, and security events without boilerplate.

Setup

Android

Add the biometric permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC" />

Your MainActivity must extend FlutterFragmentActivity:

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
}

iOS

Add the FaceID usage description to your Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>We use FaceID to securely access your account credentials.</string>

Usage

Check Device Capabilities

final vault = BiometricVaultImpl();
final availability = await vault.checkAvailability();

availability.when(
  available: () => /* Hardware ready */,
  noHardware: () => /* No biometric sensor */,
  notEnrolled: () => /* No fingerprints/faces registered */,
  unsupported: () => /* OS version too old or restricted */,
);

Writing a Secret

await vault.write(
  key: 'session_token',
  value: 'xyz_123_auth',
  promptMessage: 'Authenticate to secure your session',
  allowDevicePassword: true, // Allow PIN/Pattern fallback
);

Reading a Secret

final result = await vault.read(
  key: 'session_token',
  promptMessage: 'Authenticate to log in',
);

result.when(
  success: (token) => print('Got token: $token'),
  biometricsChanged: () => print('Biometric set modified. Re-login required.'),
  userCanceled: () => print('User dismissed prompt'),
  lockout: () => print('Too many attempts. Locked out.'),
  empty: () => print('No data found'),
  failure: (error) => print('Error: $error'),
  permanentlyLockout: () => print('Sensor permanently locked'),
);

Monitoring Security Changes

Use hasBiometricsChanged() to detect if new fingerprints or faces were added to the device since your last write. This is a critical check for high-security applications to prevent unauthorized entry via a shared device.

if (await vault.hasBiometricsChanged()) {
  // Clear the vault and force a password login
  await vault.clear();
}

Result Handling

The VaultResult class provides an exhaustive way to handle every platform edge case. Using .when() ensures you've accounted for user cancellations, hardware lockouts, and security set changes.

Additional Information

For issues, feature requests, or contributions, please visit the GitHub Repository.