🔑 nemo_crypto_keystore #

A cross-platform, OS-level MasterKeyCache adapter for the Nemo Crypto ecosystem.

This package enables silent and biometric unlock (FaceID / TouchID / Fingerprint) by securely caching the raw master key within the operating system's native secure storage. Built on top of flutter_secure_storage.

🌍 Platform Support #

Because it relies on native OS APIs, the exact security guarantees depend on the platform:

🛡️ About Nemo Crypto #

Nemo Crypto is an architecture for local-first, end-to-end encrypted (E2EE) applications. By default, unlocking a Nemo Keyring requires passing the user's passphrase through a heavy Argon2id derivation function.

This package (nemo_crypto_keystore) provides the MasterKeyCache interface, allowing you to bypass the passphrase prompt for returning users by delegating the security trust to the operating system's hardware protection (like the Secure Enclave or Trusted Execution Environment).

🚀 Installation #

dependencies:
  nemo_crypto: ^0.1.0
  nemo_crypto_keystore: ^0.1.0

🛠️ Usage #

Pass the KeystoreMasterKeyCache to your Keyring during initialization.

Strict Biometric Unlock #

This configuration generates the key with hardware-backed biometric requirements. The OS automatically handles the prompt UI and enforcement.

import 'package:nemo_crypto/nemo_crypto.dart';
import 'package:nemo_crypto_keystore/nemo_crypto_keystore.dart';

void main() async {
  await Nemo.initialize();

  // 1. Configure the Cache Adapter
  final cache = KeystoreMasterKeyCache.biometric(
    android: const AndroidBiometricOptions(
      title: 'Unlock Secure Store',
      subtitle: 'Verify your identity to access your encryption keys',
      cancel: 'Cancel',
    ),
  );

  // 2. Plug the cache into the Keyring
  final keyring = Keyring(myWrapStore, cache: cache);

  // 3. Attempt silent unlock (Triggers OS biometric prompt)
  await keyring.init(trySilentUnlock: true);

  if (keyring.isUnlocked) {
    print('Store unlocked via Biometrics!');
  } else {
    print('Access denied or cache empty. Fallback to passphrase prompt.');
  }
}

Silent Device Unlock (Default) #

If you don't require explicit biometric confirmation every time the app opens, use the default constructor. The OS will automatically release the key as long as the device itself is unlocked.

final cache = KeystoreMasterKeyCache();
final keyring = Keyring(myWrapStore, cache: cache);

Manual Cache Management #

You can programmatically revoke biometric access (e.g., when a user logs out, or disables the "Use FaceID" toggle in your app's settings):

await keyring.forgetCachedKey();

To re-enable it later after verifying their passphrase:

await keyring.cacheMasterKey();

📖 Further Reading #

For full documentation on how to encrypt data, manage the Vault, and configure the core Keyring, visit the Main Workspace Repository.