Registry / auth-security / react-native-passkey

react-native-passkey

JSON →
library3.3.3jsnpmunverified

react-native-passkey provides native Passkey support for React Native applications targeting iOS 15.0+ and Android API 28+. It bridges WebAuthn API calls to the native platform credential managers, enabling secure, passwordless authentication. The package is currently at version 3.3.3 and maintains an active release cadence, with several minor and patch releases in the past year addressing fixes, updates, and new features like PRF extension support and improved error handling. A key differentiator is its direct native integration, abstracting away the platform-specific complexities of FIDO2 attestation and assertion, and offering support for advanced features like `largeBlob` and `authenticatorSelection` options. It ships with TypeScript types, facilitating safer development. The library works by taking FIDO2 attestation/assertion requests (typically from a backend) and handling the native UI and cryptographic operations, returning FIDO2 results for server verification.

npm install react-native-passkey
INSTALL
IMPORT
SIG · REACT-NATIVE-PASSK
R
react-native-passkey
auth-securityjavascriptv3.3.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Passkey
✓ import { Passkey } from 'react-native-passkey';
✗ const Passkey = require('react-native-passkey');
The primary entry point for all Passkey operations. Use named import.
PasskeyCreateResult
✓ import type { PasskeyCreateResult } from 'react-native-passkey';
✗ import { PasskeyCreateResult } from 'react-native-passkey';
This is a TypeScript type for the result of `Passkey.create()`. Use `import type` for type-only imports to prevent bundling issues in some environments.
PasskeyGetResult
✓ import type { PasskeyGetResult } from 'react-native-passkey';
This is a TypeScript type for the result of `Passkey.get()`. Similar to PasskeyCreateResult, use `import type`.

This quickstart demonstrates how to check for Passkey support and initiate the creation of a new Passkey. It simulates fetching a FIDO2 attestation request from a backend and then uses `Passkey.create()` to prompt the user, subsequently sending the result back for verification. Replace `EXAMPLE_BACKEND_URL` with your actual FIDO2 server endpoint.

import { Passkey } from 'react-native-passkey'; import React, { useState, useEffect } from 'react'; import { View, Text, Button, Alert, ActivityIndicator, StyleSheet } from 'react-native'; const EXAMPLE_BACKEND_URL = process.env.PASSKEY_SERVER_URL ?? 'https://your-passkey-server.com'; const PasskeyDemo = () => { const [isSupported, setIsSupported] = useState<boolean | null>(null); const [isLoading, setIsLoading] = useState(false); useEffect(() => { setIsSupported(Passkey.isSupported()); }, []); const handleCreatePasskey = async () => { if (!isSupported) { Alert.alert('Not Supported', 'Passkeys are not supported on this device.'); return; } setIsLoading(true); try { // This request would typically come from your backend // For demo, we'll simulate a simple registration request const registrationChallengeResponse = await fetch(`${EXAMPLE_BACKEND_URL}/register/challenge`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'demoUser' + Date.now() }) }); const requestJson = await registrationChallengeResponse.json(); console.log('FIDO2 attestation request:', JSON.stringify(requestJson, null, 2)); const result = await Passkey.create(JSON.stringify(requestJson)); // Send the result to your server for verification const verificationResponse = await fetch(`${EXAMPLE_BACKEND_URL}/register/verify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(result) }); const verificationResult = await verificationResponse.json(); if (verificationResult.verified) { Alert.alert('Success', 'Passkey created and verified!'); } else { Alert.alert('Error', 'Passkey creation failed verification.'); } } catch (error: any) { console.error('Passkey creation error:', error); Alert.alert('Error', `Failed to create Passkey: ${error.message}`); } finally { setIsLoading(false); } }; return ( <View style={styles.container}> <Text style={styles.title}>Passkey Demo</Text> {isSupported === null ? ( <ActivityIndicator size="large" /> ) : ( <Text style={styles.status}>Passkey Supported: {isSupported ? 'Yes' : 'No'}</Text> )} <Button title="Create New Passkey" onPress={handleCreatePasskey} disabled={isLoading || !isSupported} /> {isLoading && <ActivityIndicator size="small" style={styles.spinner} />} </View> ); }; const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20, }, title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20, }, status: { fontSize: 18, marginBottom: 20, }, spinner: { marginTop: 10 } }); export default PasskeyDemo;
Debug
Known issues
breakingVersion 3.0.0 introduced significant restructuring of the iOS native code for improved maintainability. While specific breaking API changes are not explicitly listed beyond 'Support for more request options', this indicates a major internal overhaul that might affect custom native module integrations or debugging if not purely using the JS API.
fix
Review the official documentation and migration guides for v3.0.0. Ensure your FIDO2 request payloads align with the new supported options for `excludeCredentials`, `includeCredentials`, and `authenticatorSelection`.
affects: >=3.0.0
breakingThe return type for `largeBlob.blob` was changed in v3.3.3 from a string-keyed dictionary to a plain array. This directly impacts how applications process the `largeBlob` extension data if they rely on specific dictionary keys.
fix
Update your application logic to expect `largeBlob.blob` as a plain array. Ensure your backend verification also handles this change correctly. Review the TypeScript type definitions for `largeBlob`.
affects: >=3.3.3
gotchaIncorrect error handling was fixed in v3.3.2, which previously returned generic errors instead of specific FIDO2 error types like 'UserCancelled' or 'RequestFailed'. This means older versions might not provide sufficient detail for user-facing error messages or retry logic.
fix
Upgrade to v3.3.2 or newer to receive more accurate and descriptive error messages. Implement robust `try/catch` blocks around `Passkey.create()` and `Passkey.get()` to handle specific error strings or codes that now correctly propagate.
affects: <3.3.2
gotchaBoth iOS and Android require specific associated domain configurations (Apple App Site Association and Digital Asset Links respectively) on your web server and within your app's native project settings. Failing to configure these correctly will prevent Passkey functionality from working.
fix
Follow the detailed setup instructions in the README for both iOS (Xcode 'Associated Domains' capability and `apple-app-site-association` file on your domain) and Android (AndroidManifest and `assetlinks.json` file on your domain). Ensure the `team id`, `bundle identifier`, and `SHA256_cert_fingerprints` are correct.
affects: >=1.0.0
deprecatedEarly beta versions (e.g., 3.0.0-beta2) had issues with TypeScript type definitions and return types for `Passkey.create()` and `Passkey.get()`. While fixed in later RCs and stable releases, using very old beta versions might lead to type mismatches or runtime errors.
fix
Avoid using pre-release beta versions, or upgrade to a stable 3.x.x release (e.g., 3.0.0 or later) which includes fixes for TypeScript types and return values.
affects: <3.0.0-rc
Errors
Common errors & fixes
Error: Passkeys are not supported on this device.
The device's operating system version is below the minimum requirement (iOS 15.0+ or Android API 28+), or the device does not have hardware support for FIDO2/Passkeys.
fix
Check `Passkey.isSupported()` before attempting Passkey operations. Inform the user if their device does not meet the requirements. Consider fallback authentication methods.
Error: The given origin is not associated with this application.
The associated domain configuration (Apple App Site Association for iOS or Digital Asset Links for Android) is incorrect or missing on your web server or in your application's native project settings.
fix
Verify that your `apple-app-site-association` (iOS) or `assetlinks.json` (Android) file is correctly served at `/.well-known/` on your domain, and that its content matches your app's bundle ID/team ID (iOS) or package name/certificate SHA256 fingerprints (Android). For iOS, ensure the 'Associated Domains' capability is added in Xcode with `webcredentials:yourdomain.com`.
Invariant Violation: `new NativeEventEmitter()` was called with a non-null argument without the native module.
The native module for react-native-passkey is not correctly linked or initialized. This can happen if `pod install` was not run for iOS, or if there are caching issues in React Native.
fix
For iOS, navigate to your `ios` directory and run `pod install`. For both platforms, try clearing React Native caches: `npx react-native start --reset-cache`, and then rebuild your application: `npx react-native run-ios` or `npx react-native run-android`.
Error: No matching credentials found.
During a Passkey assertion (login) request, the device could not find a previously registered Passkey that matches the criteria provided in the FIDO2 assertion request (e.g., `allowCredentials`).
fix
Ensure the `allowCredentials` array in your FIDO2 assertion request contains valid `id` values for Passkeys previously registered by the user. If the user hasn't registered a Passkey on that device, this is expected. Guide the user to register a Passkey first or use a fallback authentication method.
Upgrade
Version history
3.3.3latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React Native applications.
react-nativerequiredPeer dependency for React Native applications.
Agent activity
16 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources