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

.changeset/rude-poets-beam.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-expo": minor
+---
+
+Introduce support for LocalAuthentication with `useLocalCredentials`.

packages/expo/package.json

@@ -65,17 +65,29 @@
  "@types/react": "*",
  "@types/react-dom": "*",
  "expo-auth-session": "^5.4.0",
+ "expo-local-authentication": "^13.5.0",
+ "expo-secure-store": "^12.4.0",
  "expo-web-browser": "^12.8.2",
  "react-native": "^0.73.9",
  "typescript": "*"
  },
  "peerDependencies": {
  "expo-auth-session": ">=5",
+ "expo-local-authentication": ">=13.5.0",
+ "expo-secure-store": ">=12.4.0",
  "expo-web-browser": ">=12.5.0",
  "react-native": ">=0.73",
  "react": ">=18",
  "react-dom": ">=18"
  },
+ "peerDependenciesMeta": {
+ "expo-secure-store": {
+ "optional": true
+ },
+ "expo-local-authentication": {
+ "optional": true
+ }
+ },
  "engines": {
  "node": ">=18.17.0"
  },

packages/expo/src/hooks/index.ts

@@ -12,3 +12,4 @@ export {
 } from '@clerk/clerk-react';
 
 export * from './useOAuth';
+export * from './useLocalCredentials';

packages/expo/src/hooks/useLocalCredentials/index.tsx

@@ -0,0 +1 @@
+export { useLocalCredentials } from './useLocalCredentials';

packages/expo/src/hooks/useLocalCredentials/shared.ts

@@ -0,0 +1,37 @@
+import type { SignInResource } from '@clerk/types';
+
+type LocalCredentials = {
+ /**
+ * The identifier of the credentials to be stored on the device. It can be a username, email, phone number, etc.
+ */
+ identifier?: string;
+ /**
+ * The password for the identifier to be stored on the device. If an identifier already exists on the device passing only password would update the password for the stored identifier.
+ */
+ password: string;
+};
+
+type BiometricType = 'fingerprint' | 'face-recognition';
+
+type LocalCredentialsReturn = {
+ setCredentials: (creds: LocalCredentials) => Promise<void>;
+ hasCredentials: boolean;
+ userOwnsCredentials: boolean | null;
+ clearCredentials: () => Promise<void>;
+ authenticate: () => Promise<SignInResource>;
+ biometricType: BiometricType | null;
+};
+
+const LocalCredentialsInitValues: LocalCredentialsReturn = {
+ setCredentials: () => Promise.resolve(),
+ hasCredentials: false,
+ userOwnsCredentials: null,
+ clearCredentials: () => Promise.resolve(),
+ // @ts-expect-error Initial value cannot return what the type expects
+ authenticate: () => Promise.resolve({}),
+ biometricType: null,
+};
+
+export { LocalCredentialsInitValues };
+
+export type { LocalCredentials, BiometricType, LocalCredentialsReturn };

packages/expo/src/hooks/useLocalCredentials/useLocalCredentials.ts

@@ -0,0 +1,216 @@
+import { useClerk, useSignIn, useUser } from '@clerk/clerk-react';
+import type { SignInResource } from '@clerk/types';
+import { AuthenticationType, isEnrolledAsync, supportedAuthenticationTypesAsync } from 'expo-local-authentication';
+import {
+ deleteItemAsync,
+ getItem,
+ getItemAsync,
+ setItemAsync,
+ WHEN_PASSCODE_SET_THIS_DEVICE_ONLY,
+} from 'expo-secure-store';
+import { useEffect, useState } from 'react';
+
+import { errorThrower } from '../../utils';
+import type { BiometricType, LocalCredentials, LocalCredentialsReturn } from './shared';
+
+const useEnrolledBiometric = () => {
+ const [isEnrolled, setIsEnrolled] = useState(false);
+
+ useEffect(() => {
+ let ignore = false;
+
+ void isEnrolledAsync().then(res => {
+ if (ignore) {
+ return;
+ }
+ setIsEnrolled(res);
+ });
+
+ return () => {
+ ignore = true;
+ };
+ }, []);
+
+ return isEnrolled;
+};
+
+const useAuthenticationType = () => {
+ const [authenticationType, setAuthenticationType] = useState<BiometricType | null>(null);
+
+ useEffect(() => {
+ let ignore = false;
+
+ void supportedAuthenticationTypesAsync().then(numericTypes => {
+ if (ignore) {
+ return;
+ }
+ if (numericTypes.length === 0) {
+ return;
+ }
+
+ if (
+ numericTypes.includes(AuthenticationType.IRIS) ||
+ numericTypes.includes(AuthenticationType.FACIAL_RECOGNITION)
+ ) {
+ setAuthenticationType('face-recognition');
+ } else {
+ setAuthenticationType('fingerprint');
+ }
+ });
+
+ return () => {
+ ignore = true;
+ };
+ }, []);
+
+ return authenticationType;
+};
+
+const useUserOwnsCredentials = ({ storeKey }: { storeKey: string }) => {
+ const { user } = useUser();
+ const [userOwnsCredentials, setUserOwnsCredentials] = useState(false);
+
+ const getUserCredentials = (storedIdentifier: string | null): boolean => {
+ if (!user || !storedIdentifier) {
+ return false;
+ }
+
+ const identifiers = [
+ user.emailAddresses.map(e => e.emailAddress),
+ user.phoneNumbers.map(p => p.phoneNumber),
+ ].flat();
+
+ if (user.username) {
+ identifiers.push(user.username);
+ }
+ return identifiers.includes(storedIdentifier);
+ };
+
+ useEffect(() => {
+ let ignore = false;
+ getItemAsync(storeKey)
+ .catch(() => null)
+ .then(res => {
+ if (ignore) {
+ return;
+ }
+ setUserOwnsCredentials(getUserCredentials(res));
+ });
+
+ return () => {
+ ignore = true;
+ };
+ }, [storeKey, user]);
+
+ return [userOwnsCredentials, setUserOwnsCredentials] as const;
+};
+
+/**
+ * Exposes utilities that allow for storing and accessing an identifier, and it's password securely on the device.
+ * In order to access the stored credentials, the end user will be prompted to verify themselves via biometrics.
+ */
+export const useLocalCredentials = (): LocalCredentialsReturn => {
+ const { isLoaded, signIn } = useSignIn();
+ const { publishableKey } = useClerk();
+
+ const key = `__clerk_local_auth_${publishableKey}_identifier`;
+ const pkey = `__clerk_local_auth_${publishableKey}_password`;
+ const [hasLocalAuthCredentials, setHasLocalAuthCredentials] = useState(!!getItem(key));
+ const [userOwnsCredentials, setUserOwnsCredentials] = useUserOwnsCredentials({ storeKey: key });
+ const hasEnrolledBiometric = useEnrolledBiometric();
+ const authenticationType = useAuthenticationType();
+
+ const biometricType = hasEnrolledBiometric ? authenticationType : null;
+
+ const setCredentials = async (creds: LocalCredentials) => {
+ if (!(await isEnrolledAsync())) {
+ return;
+ }
+
+ if (creds.identifier && !creds.password) {
+ return errorThrower.throw(
+ `useLocalCredentials: setCredentials() A password is required when specifying an identifier.`,
+ );
+ }
+
+ if (creds.identifier) {
+ await setItemAsync(key, creds.identifier);
+ }
+
+ const storedIdentifier = await getItemAsync(key).catch(() => null);
+
+ if (!storedIdentifier) {
+ return errorThrower.throw(
+ `useLocalCredentials: setCredentials() an identifier should already be set in order to update its password.`,
+ );
+ }
+
+ setHasLocalAuthCredentials(true);
+ await setItemAsync(pkey, creds.password, {
+ keychainAccessible: WHEN_PASSCODE_SET_THIS_DEVICE_ONLY,
+ requireAuthentication: true,
+ });
+ };
+
+ const clearCredentials = async () => {
+ await Promise.all([deleteItemAsync(key), deleteItemAsync(pkey)]);
+ setHasLocalAuthCredentials(false);
+ setUserOwnsCredentials(false);
+ };
+
+ const authenticate = async (): Promise<SignInResource> => {
+ if (!isLoaded) {
+ return errorThrower.throw(
+ `useLocalCredentials: authenticate() Clerk has not loaded yet. Wait for clerk to load before calling this function`,
+ );
+ }
+ const identifier = await getItemAsync(key).catch(() => null);
+ if (!identifier) {
+ return errorThrower.throw(`useLocalCredentials: authenticate() the identifier could not be found`);
+ }
+ const password = await getItemAsync(pkey).catch(() => null);
+
+ if (!password) {
+ return errorThrower.throw(`useLocalCredentials: authenticate() cannot retrieve a password for ${identifier}`);
+ }
+
+ return signIn.create({
+ strategy: 'password',
+ identifier,
+ password,
+ });
+ };
+
+ return {
+ /**
+ * Stores the provided credentials on the device if the device has enrolled biometrics.
+ * The end user needs to have a passcode set in order for the credentials to be stored, and those credentials will be removed if the passcode gets removed.
+ * @param credentials A [`LocalCredentials`](#localcredentials) object.
+ * @return A promise that will reject if value cannot be stored on the device.
+ */
+ setCredentials,
+ /**
+ * A Boolean that indicates if there are any credentials stored on the device.
+ */
+ hasCredentials: hasLocalAuthCredentials,
+ /**
+ * A Boolean that indicates if the stored credentials belong to the signed in uer. When there is no signed-in user the value will always be `false`.
+ */
+ userOwnsCredentials,
+ /**
+ * Removes the stored credentials from the device.
+ * @return A promise that will reject if value cannot be deleted from the device.
+ */
+ clearCredentials,
+ /**
+ * Attempts to read the stored credentials and creates a sign in attempt with the password strategy.
+ * @return A promise with a SignInResource if the stored credentials were accessed, otherwise the promise will reject.
+ */
+ authenticate,
+ /**
+ * Indicates the supported enrolled biometric authenticator type.
+ * Can be `facial-recognition`, `fingerprint` or null.
+ */
+ biometricType,
+ };
+};

packages/expo/src/hooks/useLocalCredentials/useLocalCredentials.web.ts

@@ -0,0 +1,6 @@
+import type { LocalCredentialsReturn } from './shared';
+import { LocalCredentialsInitValues } from './shared';
+
+export const useLocalCredentials = (): LocalCredentialsReturn => {
+ return LocalCredentialsInitValues;
+};