react-native-sensitive-info

Hardware-backed secure storage for React Native. Secrets are encrypted with AES-GCM, gated by biometrics or device credentials, and stored in the system Keychain (iOS) or Android Keystore behind a Promise-based API and React hooks.

[!NOTE] Upgrading from v5? See MIGRATION.md. v6 requires the New Architecture (RN 0.76+) and react-native-nitro-modules. Windows support was removed.

Table of contents

• 🧭 Platform support
• ⚙️ Installation
• ⚡️ Quick start
• ⚛️ React Hooks API
• 📚 API reference
• 🛡️ Security
• 🌳 Tree-shaking
• 🎮 Example app
• 🛠️ Development
• 🩺 Troubleshooting
• 🤝 Contributing
• 📄 License

🧭 Platform support

⚙️ Installation

npm install react-native-sensitive-info react-native-nitro-modules
# yarn add react-native-sensitive-info react-native-nitro-modules
# pnpm add react-native-sensitive-info react-native-nitro-modules

No manual linking required — Nitro handles autolinking.

🍏 iOS

Run pod install, then add to Info.plist if you use biometric prompts:

<key>NSFaceIDUsageDescription</key>
<string>Face ID is used to unlock secrets stored in the secure enclave.</string>

🤖 Android

Add to AndroidManifest.xml:

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

🧪 Expo

[!WARNING] Expo Go does not include native Nitro modules. Use a custom dev client or an EAS build.

Add the plugin to app.json, then run npx expo prebuild --clean:

{
  "expo": {
    "plugins": ["react-native-sensitive-info"]
  }
}

For a full Expo walkthrough see EXPO.md.

⚡️ Quick start

import { setItem, getItem, deleteItem } from 'react-native-sensitive-info'

// Write — uses the strongest available security policy by default
await setItem('session-token', 'abc123', { service: 'auth' })

// Read — returns value + metadata
const item = await getItem('session-token', { service: 'auth' })
console.log(item?.value)                  // 'abc123'
console.log(item?.metadata.securityLevel) // e.g. 'secureEnclave'

// Remove
await deleteItem('session-token', { service: 'auth' })

Building a component? The hooks API handles loading states, cleanup, and error boundaries.

⚛️ React Hooks API (Recommended)

import { Text, View, ActivityIndicator } from 'react-native'
import {
  useSecureStorage,
  useSecurityAvailability,
} from 'react-native-sensitive-info/hooks'

function SecretsView() {
  const { items, isLoading, error, saveSecret, removeSecret } =
    useSecureStorage({ service: 'myapp', includeValues: true })
  const { data: capabilities } = useSecurityAvailability()

  if (isLoading) return <ActivityIndicator />
  if (error) return <Text>Error: {error.message}</Text>

  return (
    <View>
      {items.map(item => (
        <Text key={item.key}>
          {item.key}: {item.value} ({item.metadata.securityLevel})
        </Text>
      ))}
      <Text>Biometry: {capabilities?.biometry ? 'available' : 'unavailable'}</Text>
    </View>
  )
}

All hooks auto-cancel in-flight requests on unmount. For advanced patterns and best practices see HOOKS.md.

📚 API reference

Common options:

Errors are typed — import predicates from react-native-sensitive-info/errors:

import {
  isAuthenticationCanceledError,
  isKeyInvalidatedError,
  isIntegrityViolationError,
} from 'react-native-sensitive-info/errors'

🛡️ Security

Every secret is encrypted with AES-GCM and bound to a hardware-protected key. Each entry carries an HMAC-SHA256 integrity tag recomputed on every read; a mismatch raises IntegrityViolationError before any biometric prompt fires.

For the full cryptographic model — key derivation, AAD binding, replay defense, and threat classification — see THREAT_MODEL.md.

🌳 Tree-shaking

All entry points are side-effect-free ("sideEffects": false). Import only what you use:

🎮 Example app

cd example && yarn install

yarn ios      # iOS
yarn android  # Android

🛠️ Development

yarn install    # Install dependencies
yarn codegen    # Regenerate Nitro bindings
yarn typecheck  # Type-check sources
yarn build      # Build distributable packages

🩺 Troubleshooting

• Biometric prompt never appears — use canUseAccessControl(policy) to check before writing and fall back to devicePasscode if needed.
• authentication failed on simulator — Secure Enclave and StrongBox are unavailable on simulators. Validate biometric policies on physical hardware.
• E_AUTH_CANCELED in error message — the user dismissed the prompt. Handle gracefully; hook state is not poisoned by cancellations.
• Undefined symbol on iOS — re-run pod install after upgrading to v6.

🤝 Contributing

Contributions are welcome!

• 🐛 Bugs — Open an issue with a minimal reproduction. Security vulnerabilities should be reported privately — see SECURITY.md.
• 💡 New features — Open an issue first to align on scope before writing code.
• 🔀 Pull requests — Run yarn test and yarn typecheck before submitting. Keep changes focused and reference the relevant issue.

Please review CODE_OF_CONDUCT.md before contributing.

📄 License

MIT © Mateus Andrade