Registry / auth-security / expo-better-auth-passkey

expo-better-auth-passkey

JSON →
library1.4.1jsnpmunverified

The `expo-better-auth-passkey` package provides native passkey (WebAuthn) support for applications built with Expo and `better-auth`. It acts as a drop-in replacement for `better-auth`'s standard `passkeyClient`, leveraging platform-specific APIs like Apple's `ASAuthorizationController` for iOS/macOS and Android's Credential Manager. This ensures a consistent passkey experience across web, iOS, and Android using a single codebase. The library, currently at version 1.4.1, maintains an active release schedule with updates addressing bug fixes and new features. Key differentiators include its seamless integration into both managed and bare Expo projects without requiring ejecting, a smart fallback to the web client for web builds, and a TypeScript-first approach with strict type mirroring for robust development.

npm install expo-better-auth-passkey
INSTALL
IMPORT
SIG · EXPO-BETTER-AUTH-P
E
expo-better-auth-passkey
auth-securityjavascriptv1.4.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

expoPasskeyClient
import { expoPasskeyClient } from 'expo-better-auth-passkey';
const expoPasskeyClient = require('expo-better-auth-passkey');
This is the primary named export for integrating native passkey support. Ensure you use ES module import syntax for modern React Native/Expo development.
createAuthClient
import { createAuthClient } from 'better-auth/react';
import createAuthClient from 'better-auth/react';
While not directly from `expo-better-auth-passkey`, `createAuthClient` from `better-auth/react` is essential for instantiating the auth client that uses `expoPasskeyClient`. It is a named export.
PasskeyPlugin
import type { PasskeyPlugin } from '@better-auth/passkey';
import { PasskeyPlugin } from '@better-auth/passkey';
For type-checking the passkey plugin object returned by `expoPasskeyClient()`, import `PasskeyPlugin` as a type from the core `@better-auth/passkey` package. `expoPasskeyClient` returns an object compatible with this plugin type.

Initializes a Better Auth client with native passkey support for Expo apps and demonstrates basic passkey registration and sign-in operations across supported platforms.

import { createAuthClient } from 'better-auth/react'; import { expoPasskeyClient } from 'expo-better-auth-passkey'; import { Platform } from 'react-native'; // Replace with your actual backend URL where Better Auth server is running const BASE_URL = process.env.BETTER_AUTH_API_URL || 'https://your-api.mydomain.com'; // Initialize the Better Auth client with the Expo Passkey plugin export const authClient = createAuthClient({ baseURL: BASE_URL, plugins: [ expoPasskeyClient(), // Add other Better Auth client plugins as needed (e.g., email, session) ], }); async function handlePasskeyOperations() { try { console.log(`Running on platform: ${Platform.OS}`); // Example: Register a new passkey with a descriptive name const addPasskeyResult = await authClient.passkey.addPasskey({ name: `My ${Platform.OS} Passkey` }); console.log('Passkey registered successfully:', addPasskeyResult); // Example: Sign in using an existing passkey // In a real application, you might first get the user's identifier (e.g., email) // before attempting passkey sign-in. const signInResult = await authClient.signIn.passkey({ email: 'user@example.com' }); console.log('Signed in with passkey successfully:', signInResult); } catch (error) { console.error('Passkey operation failed:', error); // Implement robust error handling, e.g., user cancellation, network issues, // or specific platform errors related to passkey APIs. } } // Execute the passkey operations handlePasskeyOperations();
Debug
Known issues
breakingThe parameter structure for `registerPasskey` (now `addPasskey`) and `authenticatePasskey` (now `signIn.passkey`) functions was updated in `v1.2.0`. Projects upgrading from earlier versions must review their usage of these methods.
fix
Review the official `better-auth` and `expo-better-auth-passkey` documentation for the updated parameter structures, specifically for `authClient.passkey.addPasskey()` and `authClient.signIn.passkey()`.
affects: >=1.2.0
gotchaFor iOS and macOS, the 'Associated Domains' capability must be enabled in your Xcode project or via `expo prebuild` config (`ios.associatedDomains`), and an `apple-app-site-association` file must be correctly hosted on your relying party domain.
fix
Add `webcredentials:your-auth-domain.com` to `ios.associatedDomains` in your `app.json` and ensure the `apple-app-site-association` file is correctly hosted and accessible at `https://your-auth-domain.com/.well-known/apple-app-site-association`.
affects: >=1.0.0
gotchaOn Android, the Credential Manager APIs used for native passkeys require Google Play Services version 23.30 or newer. Older device versions will not support native passkey operations.
fix
Inform users about the Google Play Services requirement or gracefully degrade to alternative authentication methods if the device doesn't meet the minimum version.
affects: >=1.0.0
gotchaYour Better Auth server must be configured correctly for passkeys, including `rpID`, `rpName`, `origin`, and crucially, `android:apk-key-hash` entries for Android builds and a comprehensive `trustedOrigins` list for all client entry points.
fix
Verify `rpID` matches your domain, `origin` is correct, and add `android:apk-key-hash:<BASE64_SHA256>` for all signing certificates to your Better Auth server passkey plugin configuration. Include all app schemes (e.g., `myapp://`, `https://localhost`) in `trustedOrigins`.
affects: >=1.0.0
gotchaPasskey operations fundamentally require a secure origin (HTTPS). Development environments should use tunneling services like ngrok or localhost HTTPS setup to avoid security errors.
fix
Ensure your `baseURL` and `origin` configurations on both client and server sides use HTTPS. For local development, set up HTTPS for your local server or use a tunnel for your API endpoint.
affects: >=1.0.0
gotchaA bug fix in v1.4.1 addressed an issue where `presentationAnchor` was not reliably running on the main thread, which could lead to UI freezes or native API call failures on older versions.
fix
Upgrade to `expo-better-auth-passkey@1.4.1` or newer to ensure correct `presentationAnchor` behavior and improve stability for native passkey interactions.
affects: >=1.0.0 <1.4.1
Errors
Common errors & fixes
ASAuthorizationError.Code.notKnown | ASAuthorizationError.Code.canceled | ASAuthorizationError.Code.invalidRequest on iOS
iOS Associated Domains capability is not enabled in Xcode/app.json, or the `apple-app-site-association` file is misconfigured/missing on the server.
fix
Verify `ios.associatedDomains` in `app.json` includes `webcredentials:your-rp-id.com` and that the `apple-app-site-association` file is correctly hosted and accessible at `https://your-rp-id.com/.well-known/apple-app-site-association`.
Passkey operation failed due to invalid relying party ID or origin configuration.
Mismatch between client-side `baseURL`/`rpID` and server-side `rpID`/`origin` parameters, or the client's origin is not in the server's `trustedOrigins` list.
fix
Cross-reference `rpID`, `rpName`, and `origin` values on your Better Auth server configuration with your app's domain. Ensure all client app schemes (e.g., `myapp://`, `https://localhost`) are explicitly included in `trustedOrigins` on the server.
SecurityException: Cannot use Credential Manager without a valid relying party ID configured / 'No Android package hash supplied in WebAuthn attestation options.'
Missing or incorrect `android:apk-key-hash` configuration on the Better Auth server for your Android app's signing certificate.
fix
Generate the correct Base64 SHA256 hash of your Android app's signing certificate and add it to the `android:apk-key-hash` array in your Better Auth server passkey plugin configuration.
TypeError: Cannot read properties of undefined (reading 'passkey') or 'addPasskey' of undefined
The `expoPasskeyClient()` plugin was not correctly added to the `plugins` array when calling `createAuthClient()`, or `authClient` was not properly initialized.
fix
Ensure `expoPasskeyClient()` is included in the `plugins` array passed to `createAuthClient({ plugins: [...] })` and that `authClient` is initialized before attempting passkey operations.
Upgrade
Version history
1.4.1latest on npm
Audit
Dependencies
better-authrequiredCore authentication framework this package extends and integrates with.
@better-auth/passkeyrequiredThe underlying passkey plugin it replaces/wraps for native functionality.
exporequiredRequired for Expo application environment and native module linking.
reactrequiredFundamental library for React Native components.
react-nativerequiredCore framework for building native mobile applications.
nanostoresrequiredRequired by `better-auth` and used implicitly by its plugin architecture.
Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources