React Native WalletSecure 🔐 (Android Only)

Securely store and retrieve cryptographic keys in the Android Keystore with biometric or device credential authentication.
Perfect for wallets, password managers, or any app that needs per-use biometric unlock for sensitive data.

✨ Features

• 🔑 AES key storage in Android Keystore
• 🔒 Biometric (fingerprint, face, device PIN/pattern) authentication per use
• 📱 Works on Android (API 24+)
• 🔄 StrongBox backed keys on supported devices, with automatic fallback
• 🛡 High-level encryption and secure storage

📦 Installation

# Add package
yarn add react-native-walletsecure

# or
npm install react-native-walletsecure

For local development:

yarn add file:../react-native-walletsecure

⚡ Usage

import React, { useState } from 'react';
import { View, Button, Text } from 'react-native';
import WalletSecure from 'react-native-walletsecure';

export default function App() {
  const [key, setKey] = useState<string | null>(null);

  const handleSave = async () => {
    await WalletSecure.storeKey(
      'my_wallet_key',
      'super-secret-private-key',
      { title: 'Unlock to store', subtitle: 'Biometric required' },
      true, // allow device credential fallback
    );
  };

  const handleGetKey = async () => {
    const value = await WalletSecure.retrieveKey(
      'my_wallet_key',
      { title: 'Unlock to view key' },
      true,
    );
    setKey(value);
  };

  return (
    <View>
      <Button title="Save Key" onPress={handleSave} />
      <Button title="Get Key" onPress={handleGetKey} />
      <Text>Stored Key: {key}</Text>
    </View>
  );
}

🛠 API Reference

WalletSecure.storeKey(alias, value, promptConfig?, allowDeviceCredential?)

Store a string securely.

• alias (string) → unique identifier for the key.
• value (string) → string to encrypt and save.
• promptConfig (object) → { title, subtitle } shown in biometric prompt.
• allowDeviceCredential (boolean) → allow PIN/pattern fallback. Default: true.

WalletSecure.retrieveKey(alias, promptConfig?, allowDeviceCredential?)

Retrieve a previously stored value.

• Shows biometric/device credential prompt before returning.
• Returns the decrypted string.

WalletSecure.deleteKey(alias)

Deletes a stored key by alias.

⚠️ Notes

• ✅ Only Android is supported right now. iOS support may come later.
• On Android, StrongBoxUnavailableException may occur if StrongBox isn’t available → the library auto-falls back to normal keystore.
• Minimum requirement: Android API 24+
• Biometric prompts may vary across manufacturers (Samsung, Pixel, etc.).

🧪 Development (Local Testing)

1. In your test app:

   yarn add file:../react-native-walletsecure

2. Start Metro bundler with symlink support:

   yarn start --reset-cache

3. Rebuild app after native changes:

   cd android && ./gradlew clean && cd ..
   yarn android

🤝 Contributing

PRs and issues are welcome! If you’d like to improve Android support or add new features, feel free to open a pull request.

📄 License

MIT © 2025