react-native-keychain

react-native-keychain gives React Native apps direct access to iOS Keychain and Android Keystore for storing usernames, passwords, and tokens without rolling custom encryption. It exposes a small TypeScript API for saving, retrieving, and resetting generic and internet credentials, and supports both the legacy Bridge and the New Architecture (TurboModules/Fabric).

Under the hood it offers fine-grained control over accessibility and biometric gating — Face ID, Touch ID, and Android biometric/fingerprint prompts can be required before credentials are released, and Android callers can choose among AES-GCM, AES-CBC, or RSA cipher storage strategies with hardware-backed security levels. The library is maintained actively and used in production by wallets like Rainbow and MetaMask Mobile, and financial apps like BlueWallet, where secure local credential storage is a hard requirement.

What You Get

• Unified setGenericPassword/getGenericPassword API backed by iOS Keychain and Android Keystore
• Internet credential storage keyed by server URL (setInternetCredentials/getInternetCredentials)
• Biometric and passcode gating via ACCESS_CONTROL (Face ID, Touch ID, Android biometric prompt)
• Selectable Android cipher storage (AES-GCM, AES-CBC, RSA) and hardware-backed SECURITY_LEVEL reporting
• Safari shared web credentials support on iOS
• Full TypeScript types and TurboModule support for React Native’s New Architecture

Common Use Cases

• Storing a user’s login/session token after authentication so a mobile app can silently re-auth on relaunch
• Gating a saved credential behind Face ID/Touch ID or Android biometrics before autofilling a login form
• Building a crypto wallet that needs hardware-backed key storage, following the Rainbow Wallet/MetaMask Mobile pattern
• Sharing web credentials between a website and its iOS app via Safari shared web credentials
• Migrating an app to React Native’s New Architecture while keeping secure storage working via TurboModules

Under The Hood

Architecture The library separates a thin cross-platform TypeScript surface (src/index.ts) from two independent native backends: an Objective-C++ bridge (ios/RNKeychainManager/RNKeychainManager.mm) that talks directly to Apple’s Security.framework, and a layered Kotlin implementation on Android (KeychainModule.kt delegating to a pluggable cipherStorage/ package - CipherStorageKeystoreAesGcm, CipherStorageKeystoreRsaEcb, CipherStorageKeystoreAesCbc - plus a resultHandler/ package that manages the interactive biometric prompt flow separately from non-interactive reads). Both backends implement a shared TurboModule spec (NativeKeychainManager.ts) with Bridge-mode fallback, so the public API and error codes stay identical across the old and new React Native architectures. Changing the core Spec interface requires updating both native implementations and the TypeScript wrapper in lockstep.

Tech Stack TypeScript in strict mode drives the public API on top of React Native’s Codegen/TurboModule system (RNKeychainSpec); the JS/TS layer is built via react-native-builder-bob into CommonJS, ESM, and typed declaration outputs. Android uses Kotlin with coroutines, AndroidX Biometric and DataStore, and the Android Keystore/BiometricPrompt APIs directly; iOS uses Objective-C++ against Security.framework and LocalAuthentication.framework, with a CocoaPods spec covering iOS, macOS Catalyst, tvOS, and visionOS targets. The workspace is managed with Yarn workspaces (example app and documentation site), with docs generated via TypeDoc into a versioned Docusaurus site.

Code Quality There are no unit tests for the JS layer, but the project relies on extensive end-to-end tests using Detox that exercise access control, storage types, and security levels against real emulators/simulators, run in CI across multiple Android API levels and iOS simulators via GitHub Actions. A separate workflow enforces linting and strict TypeScript typechecking on every push/PR. Error handling is systematic: both native sides map failures into a single standardized error-code enum rather than leaking raw platform exceptions, and the TypeScript wrapper functions are fully typed with inline documentation and examples.

API Design The public API is small and consistent - a dozen or so top-level functions share the same options-object-plus-enum pattern, so learning one function transfers directly to the rest. Every exported function carries inline documentation with a runnable example, and option normalization quietly fills in sensible defaults for biometric prompt copy so callers don’t need boilerplate. Nothing about the approach is architecturally novel - it’s a conventional native-module wrapper pattern - but the ergonomics are unusually polished for a bridge-style library: one import, one options object per call, consistent error codes, and versioned documentation spanning multiple major releases.