feat(flow): native cancellation signals and typed bridge errors (#329)

Author: itaihanski

descopesdk/src/main/java/com/descope/android/DescopeFlowBridge.kt

@@ -19,6 +19,7 @@ import com.descope.internal.others.debug
 import com.descope.internal.others.error
 import com.descope.internal.others.info
 import com.descope.internal.others.isUnsafeEnabled
+import com.descope.internal.others.parseServerError
 import com.descope.internal.others.stringOrEmptyAsNull
 import com.descope.internal.others.with
 import com.descope.internal.routes.isWebAuthnSupported
@@ -103,8 +104,15 @@ internal class FlowBridge(val webView: WebView) {
     }
 
     private fun bridgeOnError(error: String) {
+        val parsed = parseServerError(error)
+        val exception = when {
+            parsed == null -> DescopeException.flowFailed.with(message = error)
+            // Convert server flow cancellation to local flow cancellation for cohesive error handling
+            parsed.code == "E102122" -> DescopeException.flowCancelled.with(message = parsed.message)
+            else -> parsed
+        }
         handler.post {
-            listener?.onError(DescopeException.flowFailed.with(message = error))
+            listener?.onError(exception)
         }
     }
 

descopesdk/src/main/java/com/descope/android/DescopeFlowCoordinator.kt

@@ -299,6 +299,7 @@ class DescopeFlowCoordinator(val webView: WebView) {
         } catch (e: DescopeException) {
             if (e == DescopeException.oauthNativeCancelled) {
                 logger.info("OAuth native canceled")
+                sendResponse(FlowBridgeResponse.Failure("OAuthNativeCancelled"))
                 return
             }
             logger.error("OAuth native failed", e)
@@ -310,9 +311,14 @@ class DescopeFlowCoordinator(val webView: WebView) {
         pendingDeepLinkType = request.variant
         logger.info("Launching custom tab for ${request.variant}")
         try {
-            launchCustomTab(webView.context, request.startUrl, flow?.presentation?.createCustomTabsIntent(webView.context))
+            launchCustomTab(webView.context, request.startUrl, flow?.presentation?.createCustomTabsIntent(webView.context)) {
+                // Custom tab dismissed by the user before completing the auth flow.
+                pendingDeepLinkType = null
+                sendResponse(FlowBridgeResponse.Failure("WebAuthCancelled"))
+            }
         } catch (e: DescopeException) {
             logger.error("Failed to launch custom tab", e)
+            pendingDeepLinkType = null
             sendResponse(FlowBridgeResponse.Failure("CustomTabFailure"))
         }
     }
@@ -325,6 +331,7 @@ class DescopeFlowCoordinator(val webView: WebView) {
         } catch (e: DescopeException) {
             if (e == DescopeException.passkeyCancelled) {
                 logger.info("Passkeys canceled")
+                sendResponse(FlowBridgeResponse.Failure("PasskeyCancelled"))
                 return
             }
             val failure = when (e) {
@@ -353,6 +360,7 @@ class DescopeFlowCoordinator(val webView: WebView) {
         } catch (e: DescopeException) {
             if (e == DescopeException.passkeyCancelled) {
                 logger.info("Passkeys canceled")
+                sendResponse(FlowBridgeResponse.Failure("PasskeyCancelled"))
                 return
             }
             val failure = when (e) {

descopesdk/src/main/java/com/descope/android/DescopeHelperActivity.kt

@@ -30,6 +30,7 @@ class DescopeHelperActivity : Activity() {
         // interfere with user input, etc.
         if (listenForClose) {
             listenForClose = false
+            activityHelper.onCustomTabCanceled()
             finish()
         } else {
             listenForClose = true

descopesdk/src/main/java/com/descope/android/Utils.kt

@@ -27,12 +27,12 @@ fun sendViewIntent(context: Context, uri: Uri) {
 
 // Custom Tab
 
-fun launchCustomTab(context: Context, url: String, customTabsIntent: CustomTabsIntent? = null) {
-    launchCustomTab(context, url.toUri(), customTabsIntent)
+fun launchCustomTab(context: Context, url: String, customTabsIntent: CustomTabsIntent? = null, onCancel: (() -> Unit)? = null) {
+    launchCustomTab(context, url.toUri(), customTabsIntent, onCancel)
 }
 
-fun launchCustomTab(context: Context, uri: Uri, customTabsIntent: CustomTabsIntent? = null) {
-    activityHelper.openCustomTab(context, customTabsIntent ?: defaultCustomTabIntent(), uri)
+fun launchCustomTab(context: Context, uri: Uri, customTabsIntent: CustomTabsIntent? = null, onCancel: (() -> Unit)? = null) {
+    activityHelper.openCustomTab(context, customTabsIntent ?: defaultCustomTabIntent(), uri, onCancel)
 }
 
 internal fun defaultCustomTabIntent(): CustomTabsIntent {

descopesdk/src/main/java/com/descope/internal/http/ClientErrors.kt

@@ -1,21 +1,7 @@
 package com.descope.internal.http
 
-import com.descope.internal.others.toMap
 import com.descope.internal.others.with
 import com.descope.types.DescopeException
-import org.json.JSONObject
-
-internal fun parseServerError(response: String): DescopeException? {
-    try {
-        val map = JSONObject(response).toMap()
-        val code = map["errorCode"] as? String ?: return null
-        val desc = map["errorDescription"] as? String ?: "Descope server error"
-        val message = map["errorMessage"] as? String
-        return DescopeException(code = code, desc = desc, message = message)
-    } catch (_: Exception) {
-        return null
-    }
-}
 
 internal fun exceptionFromResponseCode(code: Int): DescopeException? {
     val desc = failureFromResponseCode(code) ?: return null

descopesdk/src/main/java/com/descope/internal/http/DescopeClient.kt

@@ -1,6 +1,7 @@
 package com.descope.internal.http
 
 import com.descope.android.SystemInfo
+import com.descope.internal.others.parseServerError
 import com.descope.sdk.DescopeConfig
 import com.descope.sdk.DescopeSdk
 import com.descope.types.DeliveryMethod

descopesdk/src/main/java/com/descope/internal/others/ActivityHelper.kt

@@ -10,14 +10,18 @@ import com.descope.types.DescopeException
 
 internal interface ActivityHelper {
     val customTabsIntent: CustomTabsIntent?
-    fun openCustomTab(context: Context, customTabsIntent: CustomTabsIntent, url: Uri)
+    // onCancel is registered JIT (lifecycle-bound to this custom-tab launch) so
+    // it doesn't outlive the tab and can't be hijacked by a different caller.
+    fun openCustomTab(context: Context, customTabsIntent: CustomTabsIntent, url: Uri, onCancel: (() -> Unit)? = null)
     fun closeCustomTab(context: Context)
+    fun onCustomTabCanceled()
 }
 
 internal val activityHelper = object : ActivityHelper {
+    private var cancelCallback: (() -> Unit)? = null
     override var customTabsIntent: CustomTabsIntent? = null
 
-    override fun openCustomTab(context: Context, customTabsIntent: CustomTabsIntent, url: Uri) {
+    override fun openCustomTab(context: Context, customTabsIntent: CustomTabsIntent, url: Uri, onCancel: (() -> Unit)?) {
         this.customTabsIntent = customTabsIntent
         if (!isBrowserSupported(context, url)) {
             throw DescopeException.customTabFailed.with(message = "No browser application was found")
@@ -30,11 +34,13 @@ internal val activityHelper = object : ActivityHelper {
         } catch (e: Exception) {
             throw DescopeException.customTabFailed.with(message = "Failed to open custom tab from context", cause = e)
         }
+        this.cancelCallback = onCancel
     }
 
     override fun closeCustomTab(context: Context) {
         if (this.customTabsIntent == null) return
         this.customTabsIntent = null
+        this.cancelCallback = null
         val intent = Intent(context, DescopeHelperActivity::class.java)
         intent.flags = Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP
         try {
@@ -44,6 +50,11 @@ internal val activityHelper = object : ActivityHelper {
         }
     }
 
+    override fun onCustomTabCanceled() {
+        cancelCallback?.invoke()
+        cancelCallback = null
+    }
+
     private fun isBrowserSupported(context: Context, uri: Uri): Boolean {
         val intent = Intent(Intent.ACTION_VIEW, uri)
         val component = intent.resolveActivity(context.packageManager)

descopesdk/src/main/java/com/descope/internal/others/Errors.kt

@@ -1,10 +1,23 @@
 package com.descope.internal.others
 
 import com.descope.types.DescopeException
+import org.json.JSONObject
 
 internal fun DescopeException.with(desc: String? = null, message: String? = null, cause: Throwable? = null) = DescopeException(
     code = code,
     desc = desc ?: this.desc,
     message = message ?: this.message,
     cause = cause ?: this.cause,
 )
+
+internal fun parseServerError(response: String): DescopeException? {
+    try {
+        val map = JSONObject(response).toMap()
+        val code = map["errorCode"] as? String ?: return null
+        val desc = map["errorDescription"] as? String ?: "Descope server error"
+        val message = map["errorMessage"] as? String
+        return DescopeException(code = code, desc = desc, message = message)
+    } catch (_: Exception) {
+        return null
+    }
+}

descopesdk/src/test/java/com/descope/types/DescopeExceptionTest.kt

@@ -1,8 +1,9 @@
 package com.descope.types
 
-import com.descope.internal.http.parseServerError
+import com.descope.internal.others.parseServerError
 import org.json.JSONObject
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
 import org.junit.Assert.fail
 import org.junit.Test
 
@@ -22,5 +23,24 @@ class DescopeExceptionTest {
             else -> fail("wrong when clause")
         }
     }
-    
+
+    @Test
+    fun error_message_preserved() {
+        val payload = JSONObject().apply {
+            put("errorCode", "E102122")
+            put("errorDescription", "Flow aborted")
+            put("errorMessage", "User canceled")
+        }.toString()
+        val exception = parseServerError(payload)
+        assertEquals("E102122", exception?.code)
+        assertEquals("Flow aborted", exception?.desc)
+        assertEquals("User canceled", exception?.message)
+    }
+
+    @Test
+    fun invalid_error_payload_parsing() {
+        assertNull(parseServerError("not a json error"))
+        assertNull(parseServerError(JSONObject().apply { put("errorMessage", "no code here") }.toString()))
+    }
+
 }