feat(clerk-expo): Introduce support for LocalAuth with LocalCredentials

[panteliselef]

Description

This PR introduces a new hook API

import{useLocalCredentials,}from"@clerk/clerk-expo";const{
hasCredentials,// boolean
userOwnsCredentials,// boolean | null
biometricType,// "face-recognition" | "fingerprint" | null
setCredentials,// ({ identifier?: string, password: string }) => void
authenticate,// () => Promise<SignInResource>
clearCredentials,// () => Promise<void>}=useLocalCredentials();

Video of the new UX flow

RPReplay_Final1719504401.MP4

1.Example usage in a profile page

import{useUser,useClerk,useLocalCredentials,}from"@clerk/clerk-expo";exportdefaultfunctionPage(){const{ user }=useUser();const{ signOut }=useClerk();const{
hasCredentials,
clearCredentials,}=useLocalCredentials();return(<View><Text>Settings, {user?.emailAddresses[0].emailAddress}</Text><Buttontitle="Sign out"onPress={()=>signOut()}/>{hasCredentials&&<Buttontitle="Remove biometric credentials"onPress={()=>clearCredentials()}/>}</View>);}

1.Example usage in a custom sign in flow

import{useSignIn,useLocalCredentials,}from"@clerk/clerk-expo";import{Link,Stack,useRouter}from"expo-router";import{Text,TextInput,Button,View,TouchableOpacity,StyleSheet,}from"react-native";importReactfrom"react";import{SymbolView}from"expo-symbols";exportdefaultfunctionPage(){const{ signIn, setActive, isLoaded }=useSignIn();constrouter=useRouter();const[emailAddress,setEmailAddress]=React.useState("");const[password,setPassword]=React.useState("");const{ hasCredentials, setCredentials, authenticate, biometryType }=useLocalCredentials();constonSignInPress=React.useCallback(async(useLocal=false)=>{if(!isLoaded){return;}try{constsignInAttempt=hasCredentials&&useLocal
? awaitauthenticate()
: awaitsignIn.create({identifier: emailAddress,
password,});if(signInAttempt.status==="complete"){awaitsetActive({session: signInAttempt.createdSessionId});if(!(hasCredentials&&useLocal)){awaitsetCredentials({identifier: emailAddress,
password,})}// navigate away}else{// handle other statuses of sign in }}catch(err: any){// handle any other error}},[isLoaded,emailAddress,password]);return(<View><TextInputvalue={emailAddress}onChangeText={(emailAddress)=>setEmailAddress(emailAddress)}/><TextInputvalue={password}onChangeText={(password)=>setPassword(password)}/><Buttontitle="Sign In"onPress={()=>onSignInPress()}/>{hasCredentials&&biometryType&&(<TouchableOpacityonPress={()=>onSignInPress(true)}><SymbolViewname={biometryType==="face-recognition" ? "faceid" : "touchid"}type="monochrome"/></TouchableOpacity>)}</View>);}

Checklist

• npm test runs as expected.
• npm run build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 6b6308d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/clerk-expo	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[panteliselef]

!snapshot

[clerk-cookie]

Hey @panteliselef - the snapshot version command generated the following package versions:

Package	Version
@clerk/clerk-expo	1.3.0-snapshot.ve946474
gatsby-plugin-clerk	5.0.0-beta.45

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/clerk-expo

npm i @clerk/clerk-expo@1.3.0-snapshot.ve946474 --save-exact

gatsby-plugin-clerk

npm i gatsby-plugin-clerk@5.0.0-beta.45 --save-exact

[LauraBeatris]

❓If the device supports multiple authentication methods (fingerprint and facial recognition), are we prioritizing fingerprint here?

[panteliselef]

That's a very nice question, tbh my intention here was to have AuthenticationType.IRIS behave like face-recognition so i might need to reverse the logic, in order for iris/face have priority

[LauraBeatris]

💡Nit: Could we extract this interpolation to a separate function? Or perhaps type it, to avoid accidentally changing it or misspelling between individual variables.

[LauraBeatris]

❓Is the purpose of ignore to not re-fetch isEnrolledAsync?

[panteliselef]

So the intention is to avoid race conditions in a situation where the component gets unmounted but the promise resolves after the component is already unmounted.

[panteliselef]

!snapshot

[clerk-cookie]

Hey @panteliselef - the snapshot version command generated the following package versions:

Package	Version
@clerk/clerk-expo	2.1.0-snapshot.vff0337d

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/clerk-expo

npm i @clerk/clerk-expo@2.1.0-snapshot.vff0337d --save-exact

[octoper]

❓ Should we have something like isPlatformSupported in LocalCredentialsInitValues in order to be easier to check if the hook can be used on specific platforms like Web or a device that does not has any biometric support, as now it seems you will have to check if biometryType is null which is not so clear if you don't take a look at the code

[panteliselef]

For devices that do not support biometric, android and iOS fallback to PIN, and if a pin does not exist then biometricType will be null.

with biometricType you get the available authenticator and it is useful mostly for UI purposes. Displaying a Face ID or a touch ID icon for example.

Maybe simply changing the name to supportedBiometricType would do ?

We don't wanna indicate that the device can use biometric, but instead if we can use local authentication (biometric or not) in order to store credentials.

[octoper]

I was mostly referring for platforms that this will not work at all like web,the biometric support was just an example as I didn't know if this fallbacks to pin

[brkalow]

Need some JSDoc comments on exported methods, and left a few non-blocking comments. Nice work!

Feel free to dismiss if you address the comments during your day tomorrow.

[brkalow]

💡 It would be nice to (optionally?) set the credentials after a successful auth

[octoper]

💯