feat(clerk-js,shared): add experimental trusted device resources

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: mikepitre

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

@@ -0,0 +1,12 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add experimental support for trusted device (biometric credential) resources in native apps:
+
+- `signIn.create({ strategy: 'trusted_device', trustedDeviceId })` and `signIn.attemptFirstFactor({ strategy: 'trusted_device', trustedDeviceId, clientData, signature, algorithm: 'ES256' })` are now typed and supported. The challenge to sign is exposed on `signIn.firstFactorVerification.trustedDeviceChallenge`.
+- `User` gains `__experimental_getBiometricCredentials()`, `__experimental_prepareBiometricCredential()`, `__experimental_attemptBiometricCredential()` and `__experimental_revokeBiometricCredential()` for managing a user's enrolled biometric credentials.
+- The environment's auth config now exposes `nativeSettings`, indicating whether trusted device sign-in and enrollment prompts are enabled.
+
+These APIs are experimental and may change in future minor releases.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
     { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "124.5KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "322.25KB" },
-    { "path": "./dist/clerk.native.js", "maxSize": "80KB" },
+    { "path": "./dist/clerk.native.js", "maxSize": "82KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
     { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

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,9 @@ 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);
+    if (data.native_settings !== undefined) {
+      this.nativeSettings = nativeSettingsFromJSON(data.native_settings);
+    }
     return this;
   }
 
@@ -36,6 +47,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): 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/TrustedDeviceChallenge.ts

@@ -0,0 +1,35 @@
+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,
+    // FAPI returns this timestamp in seconds, unlike most resource timestamps.
+    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,
+  };
+}

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

@@ -1,8 +1,10 @@
 import { getFullName } from '@clerk/shared/internal/clerk-js/user';
 import { isDevelopmentFromPublishableKey } from '@clerk/shared/keys';
 import type {
+  AttemptBiometricCredentialParams,
   BackupCodeJSON,
   BackupCodeResource,
+  BiometricCredentialResource,
   CreateEmailAddressParams,
   CreateExternalAccountParams,
   CreatePhoneNumberParams,
@@ -23,10 +25,12 @@ import type {
   OrganizationMembershipResource,
   PasskeyResource,
   PhoneNumberResource,
+  PrepareBiometricCredentialParams,
   RemoveUserPasswordParams,
   SetProfileImageParams,
   TOTPJSON,
   TOTPResource,
+  TrustedDeviceChallengeResource,
   UpdateUserMetadataParams,
   UpdateUserParams,
   UpdateUserPasswordParams,
@@ -45,6 +49,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import { BackupCode } from './BackupCode';
 import {
   BaseResource,
+  BiometricCredential,
   DeletedObject,
   EmailAddress,
   EnterpriseAccount,
@@ -229,6 +234,26 @@ export class User extends BaseResource implements UserResource {
     return new BackupCode(json);
   };
 
+  __experimental_getBiometricCredentials = (): Promise<BiometricCredentialResource[]> => {
+    return BiometricCredential.list();
+  };
+
+  __experimental_prepareBiometricCredential = (
+    params: PrepareBiometricCredentialParams,
+  ): Promise<TrustedDeviceChallengeResource> => {
+    return BiometricCredential.prepare(params);
+  };
+
+  __experimental_attemptBiometricCredential = (
+    params: AttemptBiometricCredentialParams,
+  ): Promise<BiometricCredentialResource> => {
+    return BiometricCredential.attempt(params);
+  };
+
+  __experimental_revokeBiometricCredential = (biometricCredentialId: string): Promise<BiometricCredentialResource> => {
+    return BiometricCredential.revoke(biometricCredentialId);
+  };
+
   update = async (params: UpdateUserParams): Promise<UserResource> => {
     const { unsafeMetadata, ...rest } = params;
     const hasMetadata = unsafeMetadata !== undefined;

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

@@ -11,6 +11,7 @@ import type {
   SignUpVerificationsJSON,
   SignUpVerificationsJSONSnapshot,
   SignUpVerificationsResource,
+  TrustedDeviceChallengeResource,
   VerificationJSON,
   VerificationJSONSnapshot,
   VerificationResource,
@@ -19,6 +20,7 @@ import type {
 
 import { unixEpochToDate } from '../../utils/date';
 import { BaseResource } from './internal';
+import { trustedDeviceChallengeFromJSON, trustedDeviceChallengeToJSON } from './TrustedDeviceChallenge';
 
 export class Verification extends BaseResource implements VerificationResource {
   pathRoot = '';
@@ -33,6 +35,7 @@ export class Verification extends BaseResource implements VerificationResource {
   error: ClerkAPIError | null = null;
   verifiedAtClient: string | null = null;
   channel?: PhoneCodeChannel;
+  trustedDeviceChallenge: TrustedDeviceChallengeResource | null = null;
 
   constructor(data: VerificationJSON | VerificationJSONSnapshot | null) {
     super();
@@ -59,6 +62,7 @@ export class Verification extends BaseResource implements VerificationResource {
       this.expireAt = unixEpochToDate(data.expire_at || undefined);
       this.error = data.error ? new ClerkAPIError(data.error) : null;
       this.channel = data.channel || undefined;
+      this.trustedDeviceChallenge = trustedDeviceChallengeFromJSON(data.trusted_device_challenge);
     }
     return this;
   }
@@ -76,6 +80,9 @@ export class Verification extends BaseResource implements VerificationResource {
       expire_at: this.expireAt?.getTime() || null,
       error: errorToJSON(this.error),
       verified_at_client: this.verifiedAtClient,
+      ...(this.trustedDeviceChallenge && {
+        trusted_device_challenge: trustedDeviceChallengeToJSON(this.trustedDeviceChallenge),
+      }),
     };
   }
 }

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

@@ -14,6 +14,7 @@ describe('AuthConfig', () => {
     expect(authConfig.claimedAt).toBeNull();
     expect(authConfig.reverification).toBe(false);
     expect(authConfig.singleSessionMode).toBe(false);
+    expect(authConfig.nativeSettings).toBeNull();
   });
 
   it('initializes with provided values', () => {
@@ -47,6 +48,43 @@ describe('AuthConfig', () => {
       reverification: true,
       single_session_mode: true,
       session_minter: false,
+      native_settings: null,
+    });
+  });
+
+  describe('native_settings', () => {
+    const nativeSettingsJSON = {
+      object: 'native_settings' as const,
+      api_enabled: true,
+      trusted_device_sign_in_enabled: true,
+      trusted_device_enrollment_prompt_after_sign_in_enabled: false,
+      trusted_device_enrollment_prompt_after_sign_up_enabled: true,
+    };
+
+    it('parses native settings', () => {
+      const authConfig = new AuthConfig({ native_settings: nativeSettingsJSON });
+
+      expect(authConfig.nativeSettings).toEqual({
+        apiEnabled: true,
+        trustedDeviceSignInEnabled: true,
+        trustedDeviceEnrollmentPromptAfterSignInEnabled: false,
+        trustedDeviceEnrollmentPromptAfterSignUpEnabled: true,
+      });
+    });
+
+    it('round-trips native settings through the snapshot', () => {
+      const snapshot = new AuthConfig({ native_settings: nativeSettingsJSON }).__internal_toSnapshot();
+
+      expect(snapshot.native_settings).toEqual(nativeSettingsJSON);
+      expect(new AuthConfig(snapshot).nativeSettings).toEqual(
+        new AuthConfig({ native_settings: nativeSettingsJSON }).nativeSettings,
+      );
+    });
+
+    it('treats null native settings as null', () => {
+      const authConfig = new AuthConfig({ native_settings: null });
+
+      expect(authConfig.nativeSettings).toBeNull();
     });
   });
 });