feat(expo): move biometric credentials to JS with @clerk/expo-biometrics

.changeset/experimental-trusted-device-resources.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add experimental APIs for biometric sign-in in native apps. This includes the `trusted_device` strategy for sign-in and session reverification, `nativeSettings` on the auth config, and `__experimental_` methods on `User` for managing biometric credentials. These may change in minor releases.

.changeset/expo-biometrics-package.md

@@ -0,0 +1,20 @@
+---
+'@clerk/expo': minor
+'@clerk/expo-biometrics': minor
+---
+
+Introduce `@clerk/expo-biometrics`, a new package that `useBiometricCredentials()` now requires. Install it and rebuild your app:
+
+```sh
+npx expo install @clerk/expo-biometrics
+```
+
+If it's missing, the hook throws an error with these same steps.
+
+Import the hook from `@clerk/expo/biometrics`:
+
+```ts
+import { useBiometricCredentials } from '@clerk/expo/biometrics';
+```
+
+Importing it from `@clerk/expo` still works, but it logs a deprecation warning and will be removed in the next major version.

.github/workflows/expo-native-build.yml

@@ -10,6 +10,7 @@ on:
       - 'integration/templates/expo-native/**'
       - 'integration/tests/expo-native/**'
       - 'packages/expo/**'
+      - 'packages/expo-biometrics/**'
       - 'packages/expo-google-signin/**'
   workflow_dispatch:
 
@@ -84,6 +85,7 @@ jobs:
               turbo.json \
               packages/clerk-js \
               packages/expo \
+              packages/expo-biometrics \
               packages/expo-google-signin \
               packages/react \
               packages/shared \
@@ -121,10 +123,11 @@ jobs:
       - name: Build and pack Clerk packages
         if: steps.native-build-cache.outputs.cache-hit != 'true'
         run: |
-          pnpm --filter @clerk/expo... build
+          pnpm --filter @clerk/expo... --filter @clerk/expo-biometrics build
           mkdir -p "$SDK_PACK_DIR"
           pnpm --filter @clerk/expo pack --pack-destination "$SDK_PACK_DIR"
           pnpm --filter @clerk/expo-google-signin pack --pack-destination "$SDK_PACK_DIR"
+          pnpm --filter @clerk/expo-biometrics pack --pack-destination "$SDK_PACK_DIR"
 
       - name: Install fixture dependencies
         if: steps.native-build-cache.outputs.cache-hit != 'true'
@@ -138,7 +141,8 @@ jobs:
           # [0-9] keeps this glob off the clerk-expo-google-signin tarball.
           SDK_TARBALL="$(ls "$SDK_PACK_DIR"/clerk-expo-[0-9]*.tgz)"
           GOOGLE_SIGNIN_TARBALL="$(ls "$SDK_PACK_DIR"/clerk-expo-google-signin-*.tgz)"
-          pnpm add "$SDK_TARBALL" "$GOOGLE_SIGNIN_TARBALL" -w
+          BIOMETRICS_TARBALL="$(ls "$SDK_PACK_DIR"/clerk-expo-biometrics-*.tgz)"
+          pnpm add "$SDK_TARBALL" "$GOOGLE_SIGNIN_TARBALL" "$BIOMETRICS_TARBALL" -w
           # expo-dev-client makes even release builds boot into the dev
           # launcher (unreachable Metro in CI), which stalls every Maestro
           # flow on a blank screen. Skip it on e2e jobs only.
@@ -209,6 +213,15 @@ jobs:
         working-directory: ${{ env.FIXTURE_DIR }}
         run: pnpm build:android
 
+      # The module's Robolectric tests need an Expo host project for expo-modules-core, so they run in the fixture.
+      # The packed module leaves out its tests, so they are copied in from the repo.
+      - name: Test expo-biometrics Android module
+        if: matrix.platform == 'android' && steps.native-build-cache.outputs.cache-hit != 'true'
+        working-directory: ${{ env.FIXTURE_DIR }}/android
+        run: |
+          cp -R "$GITHUB_WORKSPACE/packages/expo-biometrics/android/src/test" "$(readlink -f ../node_modules/@clerk/expo-biometrics)/android/src/"
+          ./gradlew :clerk-expo-biometrics:testDebugUnitTest
+
       - name: Prebuild iOS fixture
         if: matrix.platform == 'ios' && steps.native-build-cache.outputs.cache-hit != 'true'
         working-directory: ${{ env.FIXTURE_DIR }}

integration/templates/expo-native/App.tsx

@@ -4,6 +4,7 @@ import { tokenCache } from '@clerk/expo/token-cache';
 import { useState } from 'react';
 import { Button, Modal, StyleSheet, Text, View } from 'react-native';
 
+import { BiometricAvailabilityButton } from './components/BiometricAvailabilityButton';
 import { GoogleSignInButton } from './components/GoogleSignInButton';
 
 const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY;
@@ -64,6 +65,7 @@ function NativeBuildFixture() {
         onPress={() => setIsAuthOpen(true)}
       />
       {!isSignedIn && <GoogleSignInButton />}
+      {!isSignedIn && <BiometricAvailabilityButton />}
       {isSignedIn && (
         <Button
           testID='open-embedded-profile-button'

integration/templates/expo-native/components/BiometricAvailabilityButton.tsx

@@ -0,0 +1,27 @@
+import { useBiometricCredentials } from '@clerk/expo/biometrics';
+import { useState } from 'react';
+import { Button, Text } from 'react-native';
+
+export function BiometricAvailabilityButton() {
+  const { getAvailability } = useBiometricCredentials();
+  const [result, setResult] = useState<string | null>(null);
+
+  return (
+    <>
+      <Button
+        testID='biometric-availability-button'
+        title='Check biometric availability'
+        onPress={() => {
+          void getAvailability().then(
+            availability => setResult(`biometric availability: ${availability.unavailableReason ?? 'available'}`),
+            (error: unknown) => {
+              const message = error instanceof Error ? error.message : String(error);
+              setResult(`biometric availability failed: ${message.replace(/\s+/g, ' ')}`);
+            },
+          );
+        }}
+      />
+      {result && <Text testID='biometric-availability-result'>{result}</Text>}
+    </>
+  );
+}

integration/tests/expo-native/flows/biometric-availability.yaml

@@ -0,0 +1,9 @@
+appId: com.clerk.exponativebuildfixture
+name: useBiometricCredentials reaches the expo-biometrics native module
+---
+- runFlow: subflows/open-app.yaml
+- tapOn:
+    id: 'biometric-availability-button'
+- extendedWaitUntil:
+    visible: 'biometric availability: .*'
+    timeout: 15000

packages/clerk-js/bundlewatch.config.json

@@ -1,8 +1,8 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "554KB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "124.5KB" },
+    { "path": "./dist/clerk.js", "maxSize": "556KB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "83KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "126KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "322.25KB" },
     { "path": "./dist/clerk.native.js", "maxSize": "82KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },

packages/clerk-js/src/core/resources/AuthConfig.ts

@@ -1,4 +1,11 @@
-import type { AuthConfigJSON, AuthConfigJSONSnapshot, AuthConfigResource, PhoneCodeChannel } from '@clerk/shared/types';
+import type {
+  AuthConfigJSON,
+  AuthConfigJSONSnapshot,
+  AuthConfigResource,
+  NativeSettingsJSON,
+  NativeSettingsResource,
+  PhoneCodeChannel,
+} from '@clerk/shared/types';
 
 import { unixEpochToDate } from '../../utils/date';
 import { BaseResource } from './internal';
@@ -9,6 +16,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
   singleSessionMode: boolean = false;
   preferredChannels: Record<string, PhoneCodeChannel> | null = null;
   sessionMinter: boolean = false;
+  nativeSettings: NativeSettingsResource | null = null;
 
   public constructor(data: Partial<AuthConfigJSON> | null = null) {
     super();
@@ -25,6 +33,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
     this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
     this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
     this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
+    this.nativeSettings = this.withDefault(nativeSettingsFromJSON(data.native_settings), this.nativeSettings);
     return this;
   }
 
@@ -36,6 +45,32 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
       reverification: this.reverification,
       single_session_mode: this.singleSessionMode,
       session_minter: this.sessionMinter,
+      native_settings: nativeSettingsToJSON(this.nativeSettings),
     };
   }
 }
+
+function nativeSettingsFromJSON(data: NativeSettingsJSON | null | undefined): NativeSettingsResource | null {
+  if (!data) {
+    return null;
+  }
+  return {
+    apiEnabled: data.api_enabled,
+    trustedDeviceSignInEnabled: data.trusted_device_sign_in_enabled,
+    trustedDeviceEnrollmentPromptAfterSignInEnabled: data.trusted_device_enrollment_prompt_after_sign_in_enabled,
+    trustedDeviceEnrollmentPromptAfterSignUpEnabled: data.trusted_device_enrollment_prompt_after_sign_up_enabled,
+  };
+}
+
+function nativeSettingsToJSON(settings: NativeSettingsResource | null): NativeSettingsJSON | null {
+  if (!settings) {
+    return null;
+  }
+  return {
+    object: 'native_settings',
+    api_enabled: settings.apiEnabled,
+    trusted_device_sign_in_enabled: settings.trustedDeviceSignInEnabled,
+    trusted_device_enrollment_prompt_after_sign_in_enabled: settings.trustedDeviceEnrollmentPromptAfterSignInEnabled,
+    trusted_device_enrollment_prompt_after_sign_up_enabled: settings.trustedDeviceEnrollmentPromptAfterSignUpEnabled,
+  };
+}

packages/clerk-js/src/core/resources/BiometricCredential.ts

@@ -0,0 +1,117 @@
+import type {
+  AttemptBiometricCredentialParams,
+  BiometricCredentialJSON,
+  BiometricCredentialJSONSnapshot,
+  BiometricCredentialPlatform,
+  BiometricCredentialResource,
+  BiometricCredentialStatus,
+  PrepareBiometricCredentialParams,
+  TrustedDeviceAlgorithm,
+  TrustedDeviceChallengeJSON,
+  TrustedDeviceChallengeResource,
+} from '@clerk/shared/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+import { trustedDeviceChallengeFromJSON } from './TrustedDeviceChallenge';
+
+const PATH_ROOT = '/me/biometric_credentials';
+
+function toEnrollmentBody(params: PrepareBiometricCredentialParams | AttemptBiometricCredentialParams) {
+  const { publicKeyJwk, ...rest } = params;
+  return {
+    ...rest,
+    publicKeyJwk: typeof publicKeyJwk === 'string' ? publicKeyJwk : JSON.stringify(publicKeyJwk),
+  };
+}
+
+export class BiometricCredential extends BaseResource implements BiometricCredentialResource {
+  id!: string;
+  pathRoot = PATH_ROOT;
+  platform!: BiometricCredentialPlatform;
+  appIdentifier!: string;
+  name: string | null = null;
+  algorithm!: TrustedDeviceAlgorithm;
+  status!: BiometricCredentialStatus;
+  lastUsedAt: Date | null = null;
+  revokedAt: Date | null = null;
+  createdAt!: Date;
+  updatedAt!: Date;
+
+  public constructor(data: BiometricCredentialJSON | BiometricCredentialJSONSnapshot) {
+    super();
+    this.fromJSON(data);
+  }
+
+  static async list(): Promise<BiometricCredentialResource[]> {
+    const json = (await BaseResource._fetch({ path: PATH_ROOT, method: 'GET' }))
+      ?.response as unknown as BiometricCredentialJSON[];
+    return (json || []).map(credential => new BiometricCredential(credential));
+  }
+
+  static async prepare(params: PrepareBiometricCredentialParams): Promise<TrustedDeviceChallengeResource> {
+    const json = (
+      await BaseResource._fetch({
+        path: `${PATH_ROOT}/prepare`,
+        method: 'POST',
+        body: toEnrollmentBody(params) as any,
+      })
+    )?.response as unknown as TrustedDeviceChallengeJSON;
+    return trustedDeviceChallengeFromJSON(json) as TrustedDeviceChallengeResource;
+  }
+
+  static async attempt(params: AttemptBiometricCredentialParams): Promise<BiometricCredentialResource> {
+    const json = (
+      await BaseResource._fetch({
+        path: `${PATH_ROOT}/attempt`,
+        method: 'POST',
+        body: toEnrollmentBody(params) as any,
+      })
+    )?.response as unknown as BiometricCredentialJSON;
+    return new BiometricCredential(json);
+  }
+
+  static async revoke(biometricCredentialId: string): Promise<BiometricCredentialResource> {
+    const json = (
+      await BaseResource._fetch({
+        path: `${PATH_ROOT}/${biometricCredentialId}`,
+        method: 'DELETE',
+      })
+    )?.response as unknown as BiometricCredentialJSON;
+    return new BiometricCredential(json);
+  }
+
+  protected fromJSON(data: BiometricCredentialJSON | BiometricCredentialJSONSnapshot | null): this {
+    if (!data) {
+      return this;
+    }
+
+    this.id = data.id;
+    this.platform = data.platform;
+    this.appIdentifier = data.app_identifier;
+    this.name = data.name ?? null;
+    this.algorithm = data.algorithm;
+    this.status = data.status;
+    this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+    this.revokedAt = data.revoked_at ? unixEpochToDate(data.revoked_at) : null;
+    this.createdAt = unixEpochToDate(data.created_at);
+    this.updatedAt = unixEpochToDate(data.updated_at);
+    return this;
+  }
+
+  public __internal_toSnapshot(): BiometricCredentialJSONSnapshot {
+    return {
+      object: 'trusted_device',
+      id: this.id,
+      platform: this.platform,
+      app_identifier: this.appIdentifier,
+      name: this.name,
+      algorithm: this.algorithm,
+      status: this.status,
+      last_used_at: this.lastUsedAt?.getTime() ?? null,
+      revoked_at: this.revokedAt?.getTime() ?? null,
+      created_at: this.createdAt.getTime(),
+      updated_at: this.updatedAt.getTime(),
+    };
+  }
+}

packages/clerk-js/src/core/resources/Session.ts

@@ -270,6 +270,9 @@ export class Session extends BaseResource implements SessionResource {
       case 'passkey':
         config = {};
         break;
+      case 'trusted_device':
+        config = { trustedDeviceId: factor.trustedDeviceId };
+        break;
       case 'enterprise_sso':
         config = {
           emailAddressId: factor.emailAddressId,

packages/clerk-js/src/core/resources/TrustedDeviceChallenge.ts

@@ -0,0 +1,34 @@
+import type { TrustedDeviceChallengeJSON, TrustedDeviceChallengeResource } from '@clerk/shared/types';
+
+export function trustedDeviceChallengeFromJSON(
+  data: TrustedDeviceChallengeJSON | null | undefined,
+): TrustedDeviceChallengeResource | null {
+  if (!data) {
+    return null;
+  }
+  return {
+    challenge: data.challenge,
+    challengeId: data.challenge_id,
+    trustedDeviceId: data.trusted_device_id ?? null,
+    clientData: data.client_data,
+    expiresAt: data.expires_at ? new Date(data.expires_at * 1000) : null,
+    algorithm: data.algorithm,
+  };
+}
+
+export function trustedDeviceChallengeToJSON(
+  challenge: TrustedDeviceChallengeResource | null,
+): TrustedDeviceChallengeJSON | null {
+  if (!challenge) {
+    return null;
+  }
+  return {
+    object: 'trusted_device_challenge',
+    challenge: challenge.challenge,
+    challenge_id: challenge.challengeId,
+    ...(challenge.trustedDeviceId ? { trusted_device_id: challenge.trustedDeviceId } : {}),
+    client_data: challenge.clientData,
+    expires_at: challenge.expiresAt ? Math.floor(challenge.expiresAt.getTime() / 1000) : 0,
+    algorithm: challenge.algorithm,
+  };
+}