zk_vault 0.1.3

Zero-Knowledge style secure storage for Flutter/Dart applications with platform KMS integration

ZK Vault

A Zero-Knowledge style secure storage package for Flutter/Dart applications with hardware-backed platform KMS integration.

Features

• AES-256-GCM Encryption: All data is encrypted using industry-standard AES-256-GCM
• Hardware-Backed Security: Production-ready integration with Android Keystore and iOS Secure Enclave
• Biometric Authentication: Optional biometric requirement for vault access with platform-native prompts
• StrongBox Support: Automatic StrongBox utilization on supported Android devices (API 28+)
• Zero-Knowledge Architecture: Master keys never stored in plaintext on disk
• Atomic Operations: All storage operations are atomic with integrity checking
• Memory Security: Secure key clearing and memory management

Platform Support

Platform	Hardware KMS	Biometric Auth	Min Version
Android	✅ Keystore + StrongBox	✅ BiometricPrompt	API 21+
iOS	✅ Secure Enclave	✅ Touch/Face ID	iOS 11+
Mock	⚠️ Testing only	✅ Simulated	Any

Quick Start

import 'package:zk_vault/zk_vault.dart';

// Use hardware-backed KMS (recommended for production)
final vault = await ZKVault.open(
  'my_secure_vault',
  requireBiometric: true,
  kms: NativePlatformKMS(), // Uses Android Keystore or iOS Secure Enclave
);

// Store encrypted data
final secretData = Uint8List.fromList('My secret message'.codeUnits);
await vault.set('secret_key', secretData);

// Retrieve data (may prompt for biometric auth)
final retrievedData = await vault.get('secret_key');
if (retrievedData != null) {
  final message = String.fromCharCodes(retrievedData);
  print('Retrieved: $message');
}

// Check hardware capabilities
final kms = NativePlatformKMS();
print('Hardware-backed: ${await kms.isHardwareBacked()}');
print('Biometric available: ${await kms.isBiometricAvailable()}');

// Lock and destroy
await vault.lock();
await vault.destroy();

Setup

Android Setup

1. Add biometric dependency to android/app/build.gradle:

dependencies {
    implementation 'androidx.biometric:biometric:1.2.0'
}

2. Update minimum SDK in android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 21  // Required for AndroidKeyStore
    }
}

3. Add biometric permission to android/app/src/main/AndroidManifest.xml:

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

iOS Setup

1. Add biometric usage description to ios/Runner/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to secure your vault data</string>

2. Set minimum deployment target in ios/Runner.xcodeproj or ios/Podfile:

# ios/Podfile
platform :ios, '11.0'

3. Enable Keychain Sharing (if needed) in Xcode project capabilities.

API Reference

ZKVault Methods

• static Future<ZKVault> open(String vaultId, {bool requireBiometric = false, PlatformKMS? kms}) - Opens or creates a vault
• Future<void> set(String key, Uint8List value) - Stores encrypted data
• Future<Uint8List?> get(String key) - Retrieves and decrypts data
• Future<bool> contains(String key) - Checks if key exists
• Future<void> delete(String key) - Deletes a key-value pair
• Future<List<String>> keys() - Lists all stored keys
• Future<void> lock() - Locks vault and clears master key from memory
• Future<void> destroy() - Permanently destroys vault and all data

PlatformKMS Implementations

NativePlatformKMS (Production)

final kms = NativePlatformKMS();
final vault = await ZKVault.open('vault_id', kms: kms, requireBiometric: true);

MockPlatformKMS (Testing)

final kms = MockPlatformKMS();
final vault = await ZKVault.open('test_vault', kms: kms);

Exceptions

• VaultLockedException - Thrown when accessing a locked vault
• IntegrityException - Thrown when data integrity checks fail
• SecureEnclaveUnavailableException - Thrown when hardware security is unavailable

Security Implementation

Android Security Features

• KeyStore Integration: RSA-2048 keys generated in AndroidKeyStore
• StrongBox Support: Automatic utilization on supported devices (Pixel 3+, etc.)
• Biometric Authentication: BiometricPrompt with hardware-bound Cipher operations
• User Authentication: Keys require biometric unlock for each use when requireBiometric=true

iOS Security Features

• Secure Enclave: ECDSA P-256 keys generated directly in Secure Enclave
• ECIES Encryption: Elliptic Curve Integrated Encryption Scheme for key wrapping
• Biometric Protection: SecAccessControl with .biometryCurrentSet enforcement
• Hardware Isolation: Keys never leave Secure Enclave boundaries

Storage Security

• Wrapped Master Keys: Platform KMS encrypts 256-bit AES master keys
• Atomic File Operations: Temporary file + rename prevents corruption
• Application Sandbox: Files stored in app-specific directories via path_provider
• Memory Clearing: Master keys zeroed on lock/destroy operations

Testing

Unit Tests

flutter test

Device Integration Tests

Android Emulator

# Enable fingerprint on emulator
adb -e emu finger touch 1

# Run example app
flutter run example/lib/main.dart

iOS Simulator

# Enable biometrics in simulator
# Simulator > Features > Face ID / Touch ID > Enrolled

flutter run example/lib/main.dart

Physical Device Testing

# Ensure biometric enrollment on device
flutter run example/lib/main.dart

# Check logs for native KMS behavior
flutter logs

Migration from Mock to Native KMS

Step 1: Update Dependencies

# pubspec.yaml - already included
dependencies:
  zk_vault: ^0.1.1

Step 2: Replace KMS Implementation

// Before (mock)
final vault = await ZKVault.open('vault_id');

// After (native)
final vault = await ZKVault.open(
  'vault_id', 
  kms: NativePlatformKMS(),
  requireBiometric: true,
);

Step 3: Handle Exceptions

try {
  final vault = await ZKVault.open('vault_id', kms: NativePlatformKMS());
} on SecureEnclaveUnavailableException {
  // Fallback to mock KMS or show error
  final vault = await ZKVault.open('vault_id', kms: MockPlatformKMS());
}

Troubleshooting

Android Issues

"Biometric authentication failed"

• Ensure device has enrolled fingerprint/face
• Check minSdkVersion >= 21 in build.gradle
• Verify androidx.biometric dependency

"StrongBox not available"

• Normal on older devices (< API 28)
• Check logs: "StrongBox not available for zk_vault_master_key"

iOS Issues

"Secure Enclave unavailable"

• Ensure device has Secure Enclave (iPhone 5s+, not simulator)
• Check deployment target >= iOS 11.0
• Verify app signing and entitlements

"Face ID permission denied"

• Add NSFaceIDUsageDescription to Info.plist
• Re-run app after adding description

Debug Logging

Android (Logcat)

adb logcat | grep ZkVaultKmsPlugin

iOS (Console)

# Check device logs in Xcode Console or
flutter logs --verbose

Example App

cd example
flutter run

The example app demonstrates:

• Native KMS vs Mock KMS comparison
• Biometric authentication flows
• Hardware capability detection
• Error handling patterns

Publishing Notes

This package is production-ready with:

• ✅ Full native KMS implementation (Android + iOS)
• ✅ Comprehensive test coverage
• ✅ Hardware-backed security
• ✅ Biometric authentication
• ✅ Documentation and examples

Published at: https://pub.dev/packages/zk_vault

License

MIT License - see LICENSE file for details.

Integration tests (how-to)

Use these quick steps to run the integration tests locally. The example/ app contains the integration test harness under example/integration_test/.

Android emulator

# Start an Android emulator (or connect a device)
flutter emulators --launch <name>  # optional if you already started one

# If your emulator supports fingerprint, simulate a fingerprint touch when prompted
adb -s 127.0.0.1:6555 emu finger touch 1

# From the project root run the example integration test
cd example
flutter drive --driver=test_driver/integration_test.dart --target=integration_test/zk_vault_integration_test.dart -d 127.0.0.1:6555

iOS simulator / device

# Enroll biometrics in the Simulator: Simulator > Features > Face ID / Touch ID > Enrolled

# Run the example app tests (simulator/device must be connected)
cd example
flutter drive --driver=test_driver/integration_test.dart --target=integration_test/zk_vault_integration_test.dart -d <device-id>

Notes

• The integration tests detect absence of native KMS and will continue (log/skip) on emulators without hardware-backed keys.
• For full native KMS validation, run the tests on a real device with biometrics enrolled.

Publishing & GitHub Release

• After pushing a release tag (e.g. v0.1.3) create a GitHub Release using the RELEASE_NOTES_v0.1.3.md content and attach the same tag. The repository has already been tagged and pushed for v0.1.3.