feat(api): send DPoP proofs on every request and recover from a lost or foreign key

source/api/api/api.api

@@ -8,6 +8,7 @@ public final class com/clerk/api/Clerk {
 	public static final field INSTANCE Lcom/clerk/api/Clerk;
 	public final fun attachActivity (Landroid/app/Activity;)V
 	public final fun clearDeviceToken (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public final fun deleteDeviceKey (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun getActiveSession ()Lcom/clerk/api/session/Session;
 	public final fun getActiveUser ()Lcom/clerk/api/user/User;
 	public final fun getAppVersionSupportResets ()Lkotlinx/coroutines/flow/StateFlow;

source/api/src/main/kotlin/com/clerk/api/Clerk.kt

@@ -1092,6 +1092,20 @@ public object Clerk {
   public fun setDeviceToken(token: String?, expected: String?): Boolean =
     configurationManager.setDeviceToken(deviceToken = token, expectedDeviceToken = expected)
 
+  /**
+   * Deletes this device's signing key from the Android Keystore, whatever state the key is in.
+   *
+   * If this runtime signs requests, the next request signs with a new key, so FAPI rejects a device
+   * token bound to the old key and the user is signed out. A runtime that does not sign, because
+   * shared session sync is on or the key was unavailable at [initialize], keeps not signing until
+   * the next [initialize]. Intended for debug tools that test how the SDK recovers from a lost key.
+   *
+   * @return true if the stored key is gone; false if Clerk is not initialized or the Keystore
+   *   refused the delete.
+   */
+  @FrameworkIntegrationApi
+  public suspend fun deleteDeviceKey(): Boolean = configurationManager.deleteDeviceKey()
+
   // endregion
 
   // region Internal Methods
@@ -1236,6 +1250,10 @@ public object Clerk {
     configurationManager.fenceClientResponsesAfterSharedDeviceTokenChange()
   }
 
+  internal fun dropDeviceToken(deviceToken: String) {
+    configurationManager.setDeviceToken(deviceToken = null, expectedDeviceToken = deviceToken)
+  }
+
   internal fun isClientResponseCurrent(
     requestDeviceToken: String?,
     responseDeviceToken: String?,

source/api/src/main/kotlin/com/clerk/api/SharedSessionSyncConfig.kt

@@ -8,6 +8,11 @@ package com.clerk.api
  * only its client, environment, and device-token state through a signature-checked content
  * provider.
  *
+ * An app that enables shared session sync does not bind its client to a device key, because a
+ * sibling app cannot sign with a key it does not hold. If an earlier release of the app ran without
+ * shared session sync and bound the client, the first launch with it enabled drops that token, and
+ * the user signs in again once.
+ *
  * Example:
  * ```kotlin
  * Clerk.initialize(

source/api/src/main/kotlin/com/clerk/api/configuration/ConfigurationManager.kt

@@ -14,6 +14,9 @@ import com.clerk.api.appversion.UpdateRequiredViewLauncher
 import com.clerk.api.biometriccredential.BiometricCredentialStorage
 import com.clerk.api.configuration.connectivity.NetworkConnectivityMonitor
 import com.clerk.api.configuration.lifecycle.AppLifecycleListener
+import com.clerk.api.devicekey.DeviceKeyFactory
+import com.clerk.api.devicekey.DeviceKeyHolder
+import com.clerk.api.dpop.ServerClock
 import com.clerk.api.locale.LocaleProvider
 import com.clerk.api.log.ClerkLogger
 import com.clerk.api.network.ClerkApi
@@ -29,10 +32,13 @@ import com.clerk.api.session.GetTokenOptions
 import com.clerk.api.session.Session
 import com.clerk.api.session.SessionTokenFetcher
 import com.clerk.api.session.fetchToken
+import com.clerk.api.sharedsession.SharedSessionSyncCoordinator
 import com.clerk.api.storage.StorageHelper
 import com.clerk.api.storage.StorageKey
 import java.lang.ref.WeakReference
 import java.util.concurrent.atomic.AtomicInteger
+import kotlin.time.Clock
+import kotlin.time.Duration
 import kotlin.time.Duration.Companion.seconds
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
@@ -59,6 +65,8 @@ import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withTimeout
 import kotlinx.coroutines.withTimeoutOrNull
 
+internal val SHARED_STORAGE_RELOAD_WAIT: Duration = 2.seconds
+
 internal class ConfigurationManager(
   private val scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
 ) {
@@ -113,6 +121,8 @@ internal class ConfigurationManager(
 
   private val sharedDeviceTokenFenceGeneration = AtomicInteger()
 
+  @Volatile private var deviceKeyHolder: DeviceKeyHolder? = null
+
   private enum class RefreshMode {
     INITIALIZATION,
     DEVICE_TOKEN_UPDATE,
@@ -231,10 +241,19 @@ internal class ConfigurationManager(
       config = options?.sharedSessionSync,
     )
     BiometricCredentialStorage.initialize(context.applicationContext)
+    val deviceKeyHolder = DeviceKeyHolder { DeviceKeyFactory.create(context.applicationContext) }
+    this.deviceKeyHolder = deviceKeyHolder
+    val deviceBinding =
+      scope.resolveDeviceBinding(
+        sharedSessionSync = options?.sharedSessionSync != null,
+        holder = deviceKeyHolder,
+      )
     ClerkApi.configure(
       baseUrl = Clerk.baseUrl,
       context = context.applicationContext,
       customHeaders = options?.customHeaders.orEmpty(),
+      deviceBinding = deviceBinding,
+      serverClock = ServerClock(Clock.System),
     )
     hasConfigured = true
     configureConnectivityMonitor(context.applicationContext)
@@ -252,9 +271,9 @@ internal class ConfigurationManager(
         expectedConfigurationVersion = configuredVersion,
       )
     if (!restoreLocalState(configuredVersion)) return@launch
+    Clerk.sharedSessionSyncCoordinator?.let { adoptSiblingStateThenDropDeviceBoundToken(it) }
     activeSessionWatchJob = startTokenRefreshWhenASessionBecomesActive()
     Clerk.biometricCredentials.retryPendingLocalCredentialCleanup()
-    Clerk.sharedSessionSyncCoordinator?.reloadFromSharedStorage()
     val dataRefreshJob = async {
       refreshClientAndEnvironment(attempt, RefreshMode.INITIALIZATION)
     }
@@ -283,8 +302,57 @@ internal class ConfigurationManager(
     return true
   }
 
+  private suspend fun adoptSiblingStateThenDropDeviceBoundToken(
+    coordinator: SharedSessionSyncCoordinator
+  ) {
+    awaitSiblingReloadWithin(coordinator, SHARED_STORAGE_RELOAD_WAIT)
+    dropDeviceBoundToken()
+  }
+
+  private suspend fun awaitSiblingReloadWithin(
+    coordinator: SharedSessionSyncCoordinator,
+    wait: Duration,
+  ) {
+    val reload = scope.async { coordinator.reloadFromSharedStorage() }
+    try {
+      if (withTimeoutOrNull(wait) { reload.await() } == null) {
+        ClerkLogger.w(
+          "Shared session sync: siblings did not answer within $wait, starting without them"
+        )
+      }
+    } catch (e: CancellationException) {
+      throw e
+    } catch (e: Exception) {
+      ClerkLogger.w(
+        "Shared session sync: reload failed, starting without siblings: ${e.javaClass.name}"
+      )
+    }
+  }
+
+  private fun dropDeviceBoundToken() {
+    val deviceToken = StorageHelper.loadValue(StorageKey.DEVICE_TOKEN) ?: return
+    if (!isDeviceBound(deviceToken)) return
+    ClerkLogger.i("Dropping a device-bound token: shared session sync keeps this client unbound")
+    setDeviceToken(deviceToken = null, expectedDeviceToken = deviceToken)
+  }
+
   fun isConfigured(): Boolean = hasConfigured
 
+  suspend fun deleteDeviceKey(): Boolean = scope.async { deleteDeviceKeyNow() }.await()
+
+  private fun deleteDeviceKeyNow(): Boolean {
+    val holder = deviceKeyHolder
+    val context = context?.get()
+    if (holder == null || context == null) return false
+    return try {
+      holder.deleteKey { DeviceKeyFactory.delete(context) }.getOrThrow()
+      true
+    } catch (e: Exception) {
+      ClerkLogger.w("Failed to delete the device key: ${e.javaClass.name}")
+      false
+    }
+  }
+
   @Synchronized
   fun reset() {
     configurationVersion += 1
@@ -300,6 +368,7 @@ internal class ConfigurationManager(
     refreshJobSessionId = null
     activeSessionWatchJob = null
     context = null
+    deviceKeyHolder = null
     storageInitialized = false
     hasConfigured = false
     storedOptions = null