feat(expo): add biometric reverification

[seanperez29]

Description

Adds useBiometricCredentials().reverify() for first-, second-, and multi-factor verification of active sessions on iOS and Android. The result includes the verification status and synchronized JavaScript session. Completed verification clears cached session tokens and fetches a fresh token without creating another session.

New biometric enrollments default to biometry_current_set, requiring biometrics without device-passcode fallback and invalidating the key when the enrolled biometric set changes. Existing credentials retain their original policies. Android reverification requires biometry_current_set; incompatible credentials return biometric_credential_policy_incompatible so apps can offer another verification method.

Checklist

• pnpm test runs as expected.
• pnpm 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: 9c1ddfc

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

This PR includes changesets to release 1 package

Name	Type
@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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 21, 2026 9:57pm UTC
swingset	Ready	Preview	Sep 21, 2026 9:57pm UTC

[coderabbitai]

Understand this PR’s impact

Explore downstream dependencies and potential security impact with Blast Radius.

View blast radius →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: 30b990ff-a061-4d29-b40d-03a0180d1fa8

📥 Commits

Reviewing files that changed from the base of the PR and between 05ee87c and 9c1ddfc.

📒 Files selected for processing (1)

• packages/expo/README.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/cli (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)

💤 Files with no reviewable changes (1)

• packages/expo/README.md

Included review availability: 9 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

---

📝 Walkthrough

Walkthrough

The change adds reverify() to Expo biometric credentials. It defines public and native result types, validates active sessions, synchronizes session state, and refreshes tokens after completed verification. iOS and Android native bridges perform session verification and map statuses and errors. The default enrollment policy changes to biometry_current_set. Tests cover supported platforms, session changes, synchronization, errors, and older native builds. Documentation and a minor changeset describe the new flow.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 12 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: adding biometric reverification to the Expo package.
Description check	✅ Passed	The description directly explains the new reverify API, supported verification levels, platform behavior, token refresh, credential policies, and related errors.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9829

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9829

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9829

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9829

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9829

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9829

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9829

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9829

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9829

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9829

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9829

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9829

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9829

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9829

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@9829

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9829

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9829

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9829

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9829

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9829

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9829

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9829

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9829

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9829

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9829

commit: 9c1ddfc

[github-actions]

API Changes Report

Generated by Break Check on 2026-09-21T21:58:57.130Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	2
🔴 Breaking changes	0
🟡 Non-breaking changes	3
🟢 Additions	2

🤖 This report was reviewed by claude-sonnet-4-6.

---

@clerk/expo

Current version: 4.6.8
Recommended bump: MINOR → 4.7.0

🟡 Non-breaking Changes (2)

Modified: BiometricCredentialErrorCode

- export type BiometricCredentialErrorCode = 'environment_unavailable' | 'unsupported_platform' | 'biometric_authentication_unavailable' | 'biometric_authentication_canceled' | 'biometric_authentication_failed' | 'key_generation_failed' | 'key_not_found' | 'key_invalidated' | 'invalid_public_key' | 'public_key_export_failed' | 'unsupported_algorithm' | 'signing_failed' | 'key_deletion_failed' | 'invalid_trusted_device_policy' | 'E_TRUSTED_DEVICE_AVAILABILITY_FAILED' | 'E_TRUSTED_DEVICE_LIST_FAILED' | 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED' | 'E_TRUSTED_DEVICE_REVOCATION_FAILED' | 'E_TRUSTED_DEVICE_SIGN_IN_FAILED' | (string & {});
+ export type BiometricCredentialErrorCode = 'environment_unavailable' | 'unsupported_platform' | 'biometric_authentication_unavailable' | 'biometric_authentication_canceled' | 'biometric_authentication_failed' | 'key_generation_failed' | 'key_not_found' | 'key_invalidated' | 'invalid_public_key' | 'public_key_export_failed' | 'unsupported_algorithm' | 'signing_failed' | 'key_deletion_failed' | 'invalid_trusted_device_policy' | 'biometric_credential_policy_incompatible' | 'invalid_reverification_level' | 'biometric_reverification_session_unavailable' | 'E_BIOMETRIC_REVERIFICATION_FAILED' | 'E_TRUSTED_DEVICE_AVAILABILITY_FAILED' | 'E_TRUSTED_DEVICE_LIST_FAILED' | 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED' | 'E_TRUSTED_DEVICE_REVOCATION_FAILED' | 'E_TRUSTED_DEVICE_SIGN_IN_FAILED' | (string & {});

Static analyzer: Breaking change in type alias BiometricCredentialErrorCode: Type changed: 'E_TRUSTED_DEVICE_AVAILABILITY_FAILED'|'E_TRUSTED_DEVICE_ENROLLMENT_FAILED'|'E_TRUSTED_DEVICE_LIST_FAILED'|'E_TRUSTED_D… → 'E_BIOMETRIC_REVERIFICATION_FAILED'|'E_TRUSTED_DEVICE_AVAILABILITY_FAILED'|'E_TRUSTED_DEVICE_ENROLLMENT_FAILED'|'E_TRUS…

🔤 Suggestion-only union change: the union keeps its string&{} arm, which absorbs every string; the changed arms (removed: none; added: 'biometric_credential_policy_incompatible', 'invalid_reverification_level', 'biometric_reverification_session_unavailable', 'E_BIOMETRIC_REVERIFICATION_FAILED') only affect editor autocomplete, so no well-typed consumer is affected. Set downgradeAbsorbingArmUnions: false to keep these breaking.

🤖 AI review (confirmed) (100%): The union contains the absorbing arm string & {}, which already accepts every string value; adding new literal arms ('biometric_credential_policy_incompatible', 'invalid_reverification_level', 'biometric_reverification_session_unavailable', 'E_BIOMETRIC_REVERIFICATION_FAILED') only improves autocomplete and does not change the assignable set in either variance direction.

Modified: UseBiometricCredentialsReturn

// ... 3 unchanged lines elided ...
      enroll: (params?: EnrollBiometricCredentialParams) => Promise<BiometricCredential>;
      revoke: (id: string) => Promise<BiometricCredential>;
      signIn: (params?: SignInWithBiometricsParams) => Promise<BiometricSignInResult>;
+     reverify: (params?: ReverifyWithBiometricsParams) => Promise<BiometricReverificationResult>;
  };

Static analyzer: Breaking change in type alias UseBiometricCredentialsReturn: Type changed: {getAvailability:(params?:import("@clerk/expo").GetBiometricCredentialAvailabilityParams)=>!Promise:interface<import("@… → {getAvailability:(params?:import("@clerk/expo").GetBiometricCredentialAvailabilityParams)=>!Promise:interface<import("@…

🤖 AI review (reclassified as non-breaking) (95%): The only change to UseBiometricCredentialsReturn is the addition of a new optional-equivalent method reverify on a type that is returned (output) from useBiometricCredentials(); existing consumers who read/destructure this object are unaffected because they never referenced reverify before and the type is output-only.

🟢 Additions (2)

Added: BiometricReverificationResult

+ export type BiometricReverificationResult = {
+     id: string | null;
+     status: SessionVerificationStatus | (string & {});
+     level: SessionVerificationLevel | (string & {});
+     session: SessionResource;
+ };

Added type alias BiometricReverificationResult

Added: ReverifyWithBiometricsParams

+ export type ReverifyWithBiometricsParams = {
+     level?: SessionVerificationLevel;
+     reason?: string;
+ };

Added type alias ReverifyWithBiometricsParams

---

@clerk/ui

Current version: 1.33.1
Recommended bump: MINOR → 1.34.0

Subpath ./themes/experimental

🟡 Non-breaking Changes (1)

Modified: createTheme

// ... 4 unchanged lines elided ...
      theme: InternalTheme;
    }) => Elements);
    theme?: (BaseTheme | BaseTheme[]) | undefined;
-   options?: import("@clerk/ui/internal").Options | undefined;
-   variables?: import("@clerk/ui/internal").Variables | undefined;
-   captcha?: import("@clerk/ui/internal").CaptchaAppearanceOptions | undefined;
+   options?: Options | undefined;
+   variables?: Variables | undefined;
+   captcha?: CaptchaAppearanceOptions | undefined;
    cssLayerName?: string | undefined;
  }

Static analyzer: Breaking change in function createTheme: Return type changed: {__type:"prebuilt_appearance";name?:string;elements?:!unknown|((params:{theme:import("@clerk/ui").~InternalTheme;})=>!unknown);theme?:(!unknown|!unknown[])|undefined;options?:import("@clerk/ui/internal").Options|undefined;variables?:import("@clerk/ui/internal").Variables|undefined;captcha?:import("@clerk/ui/internal").CaptchaAppearanceOptions|undefined;cssLayerName?:string|undefined;} → {__type:"prebuilt_appearance";name?:string;elements?:((params:{theme:import("@clerk/ui").~InternalTheme;})=>import("@clerk/ui").~Elements)|import("@clerk/ui").~Elements;theme?:(import("@clerk/ui").~BaseTheme|import("@clerk/ui").~BaseTheme[])|undefined;options?:import("@clerk/ui").~Options|undefined;variables?:import("@clerk/ui").~Variables|undefined;captcha?:import("@clerk/ui").~CaptchaAppearanceOptions|undefined;cssLayerName?:string|undefined;}

🤖 AI review (reclassified as non-breaking) (85%): The before and after snippets show structurally identical return types; the only difference is that Options, Variables, and CaptchaAppearanceOptions are now imported from @clerk/ui (a public entry point) rather than @clerk/ui/internal (unknown resolvability). Per rule 13, replacing a potentially non-resolvable specifier with a public one is a repair, not a break — no well-typed consumer relying on the old types from @clerk/ui/internal is harmed since those types were potentially unresolvable, and the structural shape is identical.

---

Report generated by Break Check

_{Last ran on 9c1ddfc.}

[wobsoriano]

AI-assisted findings, checked against the pinned native SDKs:

Multi-factor reverification

Both native bridges return after a single verifyWithBiometrics call. If the first factor returns needs_second_factor, reverify() returns an incomplete result with no way to continue that attempt. Calling it again starts a new verification. Can the bridge run the second factor when the first result requires it?

iOS passcode fallback

On iOS, reverification can select an older credential enrolled with biometry_or_device_passcode. clerk-ios 1.5.5 does not reject that policy, so the device passcode can complete reverification. Android requires biometry_current_set. Can iOS enforce the same requirement? This may need a clerk-ios change because the local policy is internal to that SDK.

Manual review otherwise looks good 👍