react-native-sensitive-info

April 30, 2026 · View on GitHub

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/Apple) or Android Keystore — all behind a simple Promise-based API and first-class 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.

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

🧭 Platform support

Platform	Minimum	Notes
React Native	0.76.0	New Architecture + `react-native-nitro-modules` required.
iOS	13.0	Add `NSFaceIDUsageDescription` to `Info.plist` for biometrics.
macOS	11.0	Catalyst and native macOS via system keychain.
visionOS	1.0	Secure Enclave-backed; biometric UX adapts to visionOS.
watchOS	7.0	Paired-device auth; storage syncs through watchOS keychain.
Android	API 23	StrongBox requires API 28+; falls back to strongest available authenticator.

⚙️ 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 — no useEffect boilerplate needed.

⚛️ 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>
  )
}

Hook	Use case
`useSecureStorage()`	List, add, and remove all secrets in a service.
`useSecret()`	Fetch a single secret with read/write mutations.
`useHasSecret()`	Lightweight existence check (no decryption).
`useSecurityAvailability()`	Query device capabilities (auto-cached).
`useKeyRotation()`	Rotate the master key for a service.
`useBiometryStatusWatcher()`	Subscribe to biometric enrollment-state transitions.

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

📚 API reference

Method	Description
`setItem(key, value, options?)`	Write a secret using the strongest available security policy.
`getItem(key, options?)`	Read a secret and its metadata. Pass `includeValue: false` to skip the payload.
`hasItem(key, options?)`	Check whether a secret exists (no biometric prompt).
`deleteItem(key, options?)`	Remove a secret. Returns `true` if something was deleted.
`getAllItems(options?)`	List all secrets in a service.
`clearService(options?)`	Remove every secret in a service namespace.
`getSupportedSecurityLevels()`	Snapshot of device capabilities (biometrics, Secure Enclave, StrongBox, …).
`canUseAccessControl(policy)`	Check whether a given access-control policy is supported on this device.
`rotateKeys(options?)`	Bump the active key version; subsequent reads transparently re-encrypt older entries.

Common options:

Option	Default	Description
`service`	bundle ID / `'default'`	Logical namespace for secrets.
`accessControl`	`'secureEnclaveBiometry'`	Preferred write policy; native layer picks the strongest supported fallback.
`authenticationPrompt`	—	Localized strings for biometric / device-credential prompts.
`iosSynchronizable`	`false`	Sync via iCloud Keychain.
`keychainGroup`	—	Custom Keychain access group.

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 — the Secure Enclave on Apple platforms and the Android Keystore (StrongBox when available). Each entry carries an HMAC-SHA256 integrity tag recomputed on every read; a mismatch raises IntegrityViolationError before any biometric prompt fires, so spoofed entries can never trigger user authentication.

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:

Subpath	Contents
`react-native-sensitive-info`	Core API (`setItem`, `getItem`, `hasItem`, `deleteItem`, `getAllItems`, `clearService`, `rotateKeys`, …)
`react-native-sensitive-info/hooks`	React hooks (`useSecureStorage`, `useSecret`, `useKeyRotation`, …)
`react-native-sensitive-info/errors`	Typed error classes and `instanceof` predicates

🎮 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.