Decouple JWT invalidated delivery and document threading

OperationRepo: on FAIL_UNAUTHORIZED, invalidate JWT and re-queue before
notifying the app; invoke setJwtInvalidatedHandler synchronously with
try/catch so listener failures do not hit executeOperations outer catch.
UserManager.fireJwtInvalidated performs the single async hop (SupervisorJob
+ Dispatchers.Default) with Otel-style launch try/catch and per-listener
isolation.

IdentityVerificationService: call forceExecuteOperations before
fireJwtInvalidated on HYDRATE.

Documentation: IOperationRepo handler runs on the op-repo thread and must
return quickly; public API documents background-thread delivery for
IUserJwtInvalidatedListener, addUserJwtInvalidatedListener, and
UserJwtInvalidatedEvent (LiveData postValue guidance).

Tests: FAIL_UNAUTHORIZED JWT handler coverage; no artificial delay after sync repo handler.

Author: nan-li

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/IOneSignal.kt

@@ -256,6 +256,8 @@ interface IOneSignal {
      * Add a listener that will be called when a user's JWT is invalidated (e.g. expired
      * or rejected by the server). Use this to provide a fresh token via [updateUserJwt].
      *
+     * The listener is invoked on a background thread; see [IUserJwtInvalidatedListener].
+     *
      * @param listener The listener to add.
      */
     fun addUserJwtInvalidatedListener(listener: IUserJwtInvalidatedListener)

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/IUserJwtInvalidatedListener.kt

@@ -2,14 +2,16 @@ package com.onesignal
 
 /**
  * Implement this interface and provide an instance to [OneSignal.addUserJwtInvalidatedListener]
- * in order to receive control when the JWT for the current user is invalidated.
+ * to be notified when the JWT for a user is invalidated.
  *
+ * Callbacks are delivered on a background thread.
  */
 interface IUserJwtInvalidatedListener {
     /**
-     * Called when the JWT is invalidated
+     * Called when the JWT is invalidated for [UserJwtInvalidatedEvent.externalId].
+     * Invoked on a background thread; see [IUserJwtInvalidatedListener] class documentation.
      *
-     * @param event The user JWT that expired.
+     * @param event Describes which user's JWT was invalidated.
      */
     fun onUserJwtInvalidated(event: UserJwtInvalidatedEvent)
 }

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/OneSignal.kt

@@ -360,6 +360,8 @@ object OneSignal {
      * Add a listener that will be called when a user's JWT is invalidated (e.g. expired
      * or rejected by the server). Use this to provide a fresh token via [updateUserJwt].
      *
+     * The listener is invoked on a background thread; see [IUserJwtInvalidatedListener].
+     *
      * @param listener The listener to add.
      */
     @JvmStatic

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/UserJwtInvalidatedEvent.kt

@@ -1,9 +1,8 @@
 package com.onesignal
 
 /**
- * The event passed into [IUserJwtInvalidatedListener.onUserJwtInvalidated], it provides access
- * to the external ID whose JWT has just been invalidated.
- *
+ * The event passed into [IUserJwtInvalidatedListener.onUserJwtInvalidated]. Delivery occurs on
+ * a background thread; see [IUserJwtInvalidatedListener].
  */
 class UserJwtInvalidatedEvent(
     val externalId: String,

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/core/internal/config/impl/IdentityVerificationService.kt

@@ -42,18 +42,21 @@ internal class IdentityVerificationService(
 
         val useIV = model.useIdentityVerification
 
+        var jwtInvalidatedExternalId: String? = null
         if (useIV == true) {
             Logging.debug("IdentityVerificationService: IV enabled, purging anonymous operations")
             _operationRepo.removeOperationsWithoutExternalId()
 
             val externalId = _identityModelStore.model.externalId
             if (externalId != null && _jwtTokenStore.getJwt(externalId) == null) {
-                Logging.debug("IdentityVerificationService: IV enabled but no JWT for $externalId, firing invalidated event")
-                _userManager.fireJwtInvalidated(externalId)
+                Logging.debug("IdentityVerificationService: IV enabled but no JWT for $externalId, will fire invalidated event after queue wake")
+                jwtInvalidatedExternalId = externalId
             }
         }
 
         _operationRepo.forceExecuteOperations()
+
+        jwtInvalidatedExternalId?.let { _userManager.fireJwtInvalidated(it) }
     }
 
     override fun onModelUpdated(

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/core/internal/operations/IOperationRepo.kt

@@ -54,6 +54,10 @@ interface IOperationRepo {
      * Register a handler to be called when a runtime 401 Unauthorized response
      * invalidates a JWT. This allows the caller to notify the developer so they
      * can supply a fresh token via [OneSignal.updateUserJwt].
+     *
+     * The handler is invoked synchronously on the operation repo thread immediately
+     * after JWT invalidation and re-queue. It must return quickly; defer heavy work
+     * to another thread. The SDK default handler only schedules listener delivery.
      */
     fun setJwtInvalidatedHandler(handler: ((String) -> Unit)?)
 }

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/core/internal/operations/impl/OperationRepo.kt

@@ -247,6 +247,13 @@ internal class OperationRepo(
         }
     }
 
+    private fun dispatchJwtInvalidatedToApp(externalId: String) {
+        _jwtInvalidatedHandler?.let { handler ->
+            runCatching { handler(externalId) }
+                .onFailure { Logging.warn("Failed to run JWT invalidated handler for externalId=$externalId", it) }
+        }
+    }
+
     internal suspend fun executeOperations(ops: List<OperationQueueItem>) {
         try {
             val startingOp = ops.first()
@@ -280,11 +287,11 @@ internal class OperationRepo(
                     val externalId = startingOp.operation.externalId
                     if (externalId != null) {
                         _jwtTokenStore.invalidateJwt(externalId)
-                        _jwtInvalidatedHandler?.invoke(externalId)
                         Logging.warn("Operation execution failed with 401 Unauthorized, JWT invalidated for user: $externalId. Operations re-queued.")
                         synchronized(queue) {
                             ops.reversed().forEach { queue.add(0, it) }
                         }
+                        dispatchJwtInvalidatedToApp(externalId)
                     } else {
                         Logging.warn("Operation execution failed with 401 Unauthorized for anonymous user. Operations dropped.")
                         ops.forEach { _operationModelStore.remove(it.operation.id) }

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/user/internal/UserManager.kt

@@ -24,6 +24,10 @@ import com.onesignal.user.state.IUserStateObserver
 import com.onesignal.user.state.UserChangedState
 import com.onesignal.user.state.UserState
 import com.onesignal.user.subscriptions.IPushSubscription
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
 
 internal open class UserManager(
     private val _subscriptionManager: ISubscriptionManager,
@@ -47,6 +51,10 @@ internal open class UserManager(
     val changeHandlersNotifier = EventProducer<IUserStateObserver>()
     private val jwtInvalidatedNotifier = EventProducer<IUserJwtInvalidatedListener>()
 
+    // Coroutine scope for async JWT invalidated listener delivery (non-blocking)
+    private val jwtInvalidatedAppCallbackScope =
+        CoroutineScope(SupervisorJob() + Dispatchers.Default)
+
     fun addJwtInvalidatedListener(listener: IUserJwtInvalidatedListener) {
         jwtInvalidatedNotifier.subscribe(listener)
     }
@@ -55,9 +63,31 @@ internal open class UserManager(
         jwtInvalidatedNotifier.unsubscribe(listener)
     }
 
+    /**
+     * Schedules [IUserJwtInvalidatedListener] delivery on a background dispatcher so HYDRATE and
+     * operation-repo paths can finish internal work before app code runs.
+     */
+    @Suppress("TooGenericExceptionCaught")
     fun fireJwtInvalidated(externalId: String) {
-        jwtInvalidatedNotifier.fire {
-            it.onUserJwtInvalidated(UserJwtInvalidatedEvent(externalId))
+        // Deliver asynchronously (non-blocking)
+        jwtInvalidatedAppCallbackScope.launch {
+            try {
+                jwtInvalidatedNotifier.fire { listener ->
+                    try {
+                        listener.onUserJwtInvalidated(UserJwtInvalidatedEvent(externalId))
+                    } catch (t: Throwable) {
+                        Logging.warn(
+                            "onUserJwtInvalidated listener threw for externalId=$externalId",
+                            t,
+                        )
+                    }
+                }
+            } catch (t: Throwable) {
+                Logging.warn(
+                    "Failed to deliver JWT invalidated event for externalId=$externalId",
+                    t,
+                )
+            }
         }
     }
 

OneSignalSDK/onesignal/core/src/test/java/com/onesignal/core/internal/operations/OperationRepoTests.kt

@@ -960,6 +960,62 @@ class OperationRepoTests : FunSpec({
         handlerCalledWith shouldBe "test-user"
     }
 
+    test("FAIL_UNAUTHORIZED still re-queues when JWT invalidated handler throws") {
+        val configModelStore =
+            MockHelper.configModelStore {
+                it.useIdentityVerification = true
+            }
+        val identityModelStore =
+            MockHelper.identityModelStore {
+                it.externalId = "test-user"
+            }
+        val jwtTokenStore = mockk<JwtTokenStore>(relaxed = true)
+        every { jwtTokenStore.getJwt("test-user") } returns "valid-jwt"
+
+        val operationModelStore =
+            run {
+                val operationStoreList = mutableListOf<Operation>()
+                val mock = mockk<OperationModelStore>()
+                every { mock.loadOperations() } just runs
+                every { mock.list() } answers { operationStoreList.toList() }
+                every { mock.add(any()) } answers { operationStoreList.add(firstArg<Operation>()) }
+                every { mock.remove(any()) } answers {
+                    val id = firstArg<String>()
+                    operationStoreList.removeIf { it.id == id }
+                }
+                mock
+            }
+
+        val executor = mockk<IOperationExecutor>()
+        every { executor.operations } returns listOf("DUMMY_OPERATION")
+        coEvery { executor.execute(any()) } returns
+            ExecutionResponse(ExecutionResult.FAIL_UNAUTHORIZED) andThen
+            ExecutionResponse(ExecutionResult.SUCCESS)
+
+        val operationRepo =
+            OperationRepo(
+                listOf(executor),
+                operationModelStore,
+                configModelStore,
+                Time(),
+                getNewRecordState(configModelStore),
+                jwtTokenStore,
+                identityModelStore,
+            )
+
+        operationRepo.setJwtInvalidatedHandler { throw IllegalStateException("app callback failed") }
+
+        val operation = mockOperation()
+        every { operation.externalId } returns "test-user"
+
+        operationRepo.start()
+        val response = operationRepo.enqueueAndWait(operation)
+
+        response shouldBe true
+        verify { jwtTokenStore.invalidateJwt("test-user") }
+        coVerify(exactly = 2) { executor.execute(any()) }
+    }
+
     test("FAIL_UNAUTHORIZED drops operations for anonymous user") {
         // Given
         val mocks = Mocks()