feat: add trusted-device (biometric) sign-in

[swolfand]

Summary

Port of clerk-ios#486 to Android. Adds trusted-device (biometric) sign-in: users can enroll their device while signed in, then sign back in with the system biometric prompt instead of their regular first factor.

Fixes MOBILE-587.

How it works

Enrollment generates a biometric-gated EC P-256 key in the Android Keystore and registers its public key (ES256 JWK) with Clerk via POST me/trusted_devices/prepare → sign challenge → POST me/trusted_devices/attempt. Sign-in creates a trusted_device sign-in attempt, signs the returned challenge with the local key behind a BiometricPrompt (CryptoObject-bound, per-use auth), and completes the first factor. The private key never leaves the device.

What's included

clerk-android-api

• New com.clerk.api.trusteddevice package: TrustedDevice, TrustedDeviceChallenge, TrustedDeviceAvailability, TrustedDevicePolicy models; Keystore key manager; encrypted local credential metadata store (on StorageHelper); and the TrustedDevices domain exposed as Clerk.trustedDevices (enroll, signIn, revoke, list, availability, server reconciliation, stale-credential cleanup)
• TrustedDeviceApi: GET/POST me/trusted_devices (+ /prepare, /attempt), DELETE me/trusted_devices/{id}, POST client/trusted_devices/validate
• Public entry points: Clerk.auth.signInWithTrustedDevice() and SignIn.CreateParams.Strategy.TrustedDevice
• Plumbing: trusted_device strategy constant, Verification.trustedDeviceChallenge, Factor.trustedDeviceId, per-error meta on the Error model, native_settings on auth_config with public Clerk getters, new USE_BIOMETRIC permission, and the androidx.biometric dependency (capability checks only — the prompt itself uses the framework API so Compose-only hosts don't need FragmentActivity)

clerk-android-ui

• Auth start: "Continue with biometrics" button (shown when the feature is enabled, a validated local credential exists, and mode isn't sign-up), with "Last used" badge support via a new LastUsedAuth.TrustedDevice case
• Post-auth enrollment prompt: new AuthDestination.TrustedDeviceEnrollment screen offered after sign-in/sign-up per the dashboard prompt settings, with per-user "seen" persistence (sign-in flow only, matching iOS)
• User profile → Security: "Biometric sign-in" toggle section that enrolls/revokes the device credential
• Account deletion forgets local trusted-device credentials

Policy mapping (iOS → Android)

iOS policy	Android key spec
biometryCurrentSet	BIOMETRIC_STRONG, invalidated by new biometric enrollment
biometryAny	BIOMETRIC_STRONG, survives enrollment changes
biometryOrDevicePasscode (default)	BIOMETRIC_STRONG | DEVICE_CREDENTIAL on API 30+; biometric-only on API 28–29

Deliberate deviations from the iOS PR

• No installation marker (Clerk+Installation.swift): iOS needs it because Keychain items survive uninstall; Android Keystore keys don't. Stale metadata restored via auto-backup self-heals through the missing-key cleanup path.
• Enrollment prompt only fires when no session tasks are pending — Android's reactive session-task router would immediately push task screens over it, so iOS's "enrollment before tasks" ordering isn't reproducible here.
• Generic "biometrics" wording and fingerprint icon instead of Face ID / Touch ID display names (Android can't reliably distinguish modalities).
• Devices below API 28 report UNSUPPORTED_PLATFORM (framework BiometricPrompt requirement; minSdk is 24).

Testing

• Unit tests: model serialization (incl. native_settings present/absent), Retrofit path/field contracts for all five endpoints, local credential store round-trips + malformed-record resilience, LastUsedAuth trusted-device cases
• Paparazzi snapshots recorded for the security-screen toggle section (light/dark)
• spotlessCheck, detekt (no new issues), :source:api:test, :source:ui:testDebug all pass

Reviewer notes / open items

• Needs on-device verification against an instance with the trusted-device feature flag enabled — the biometric prompt, FAPI contract, and response envelopes couldn't be exercised in unit tests. In particular, the GET me/trusted_devices list decode follows the SDK's existing plain-array convention for List<T> responses; worth confirming FAPI doesn't wrap it in the {response, client} envelope for this endpoint.
• New strings are English-only (tools:ignore="MissingTranslation"); the 14 locale files need translations as a follow-up.

🤖 Generated with Claude Code

Note

Add biometric trusted-device sign-in and enrollment to Android

• Introduces a new TrustedDevices subsystem (Clerk.trustedDevices) that manages the full lifecycle of biometric-gated device credentials: enrollment, sign-in, revocation, local credential storage, and server validation.
• Adds Android Keystore–backed EC P-256 key generation and biometric prompt signing via DefaultTrustedDeviceKeyManager, with DER-to-raw signature conversion and per-policy authenticator gating.
• Extends the auth start screen with a "Continue with biometrics" button and post-auth enrollment prompt (TrustedDeviceEnrollmentView) that routes users through biometric enrollment after sign-in or sign-up.
• Adds a trusted-device toggle to the User Profile security screen, and cleans up local credentials on account deletion.
• Introduces Clerk.isAuthFlowCompleteFlow to track when SDK-owned post-auth steps (e.g. enrollment prompt) are complete, replacing manual session/task tracking in WorkbenchAuthGate and the prebuilt UI sample.
• Risk: biometric key creation and signing require API 28+; device credential fallback for key operations requires API 30+.

🖇️ Linked Issues

Implements MOBILE-587 — Add Biometrics to Android.

📊 Macroscope summarized 65190ad. 7 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[macroscopeapp]

🟠 High api/Clerk.kt:1125

Clerk.reset() calls resetAuthFlowState() which clears the pending flags but leaves authFlowRegistrationId set. After reinitialization, a completed sign-in still flows through holdAuthFlowCompletion, which sees the stale registration ID and sets isAuthFlowComplete to false, blocking the UI from transitioning to authenticated content until the old AuthFlowRegistration is closed. Clear authFlowRegistrationId in resetAuthFlowState() so the stale registration can no longer hold the flow pending.

Suggested change

	private fun resetAuthFlowState() {
	pendingAuthFlowCompletion = null
	setAuthFlowPending(false)
	}
	private fun resetAuthFlowState() {
	authFlowRegistrationId = null
	pendingAuthFlowCompletion = null
	setAuthFlowPending(false)
	}

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @source/api/src/main/kotlin/com/clerk/api/Clerk.kt around lines 1125-1128:

`Clerk.reset()` calls `resetAuthFlowState()` which clears the pending flags but leaves `authFlowRegistrationId` set. After reinitialization, a completed sign-in still flows through `holdAuthFlowCompletion`, which sees the stale registration ID and sets `isAuthFlowComplete` to `false`, blocking the UI from transitioning to authenticated content until the old `AuthFlowRegistration` is closed. Clear `authFlowRegistrationId` in `resetAuthFlowState()` so the stale registration can no longer hold the flow pending.