Introduce authenticated flows

Author: itaihanski

README.md

@@ -283,19 +283,27 @@ Make sure the Activity running the flow is a `SINGLE_TOP` activity, to avoid any
 unexpected UX. Run the flow by creating a `DescopeFlow.Runner`:
 
 ```kotlin
-Descope.flow.create(
+val runner = Descope.flow.create(
     flowUrl = "<URL_FOR_FLOW_IN_SETUP_#1>",
     deepLinkUrl = "<URL_FOR_APP_LINK_IN_SETUP_#2>",
     backupCustomScheme = "<OPTIONAL_CUSTOM_SCHEME_FROM_SETUP_#2>"
-).start(this@MainActivity)
+)
+
+// Starting an authentication flow
+runner.start(this@MainActivity)
+
+// Starting a flow for an authenticated user
+Descope.sessionManager.session?.run {
+    runner.start(this@MainActivity, "flow-id", refreshJwt)
+}
 ```
 
 When supporting Magic Links the `resume` function must be called. In your authentication Activity
 inside the `onCreate` method:
 
 ```kotlin
-intent?.getStringExtra("descopeFlowUri")?.run {
-    Descope.flow.currentRunner?.resume(this@AuthActivity, this)
+intent?.data?.let { incomingUri ->
+    Descope.flow.currentRunner?.resume(this@AuthActivity, incomingUri)
 }
 ```
 

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

@@ -427,6 +427,15 @@ internal class DescopeClient(internal val config: DescopeConfig) : HttpClient(co
             "codeVerifier" to codeVerifier,
         ),
     )
+    
+    suspend fun flowPrime(flowId: String, refreshJwt: String): FlowPrimeResponse = post(
+        route = "flow/prime",
+        decoder = FlowPrimeResponse::fromJson,
+        headers = authorization(refreshJwt),
+        body = mapOf(
+            "flowId" to flowId,
+        ),
+    )
 
     // Others
 

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

@@ -210,3 +210,18 @@ internal data class SsoServerResponse(
         }
     }
 }
+
+internal data class FlowPrimeResponse(
+    val codeVerifier: String,
+    val codeChallenge: String,
+) {
+    companion object {
+        @Suppress("UNUSED_PARAMETER")
+        fun fromJson(json: String, cookies: List<HttpCookie>) = JSONObject(json).run {
+            FlowPrimeResponse(
+                codeVerifier = getString("codeVerifier"),
+                codeChallenge = getString("codeChallenge"),
+            )
+        }
+    }
+}

descopesdk/src/main/java/com/descope/internal/routes/Flow.kt

@@ -4,18 +4,16 @@ import android.content.Context
 import android.net.Uri
 import androidx.browser.customtabs.CustomTabsIntent
 import com.descope.internal.http.DescopeClient
+import com.descope.internal.others.toBase64
 import com.descope.internal.others.with
 import com.descope.sdk.DescopeFlow
 import com.descope.sdk.DescopeLogger.Level.Info
 import com.descope.types.AuthenticationResponse
 import com.descope.types.DescopeException
 import com.descope.types.Result
 import java.security.MessageDigest
-import kotlin.io.encoding.Base64
-import kotlin.io.encoding.ExperimentalEncodingApi
 import kotlin.random.Random
 
-@OptIn(ExperimentalEncodingApi::class)
 internal class Flow(
     override val client: DescopeClient
 ) : Route, DescopeFlow {
@@ -44,27 +42,27 @@ internal class Flow(
             Random.nextBytes(randomBytes)
 
             // codeVerifier == base64(randomBytes)
-            codeVerifier = Base64.UrlSafe.encode(randomBytes)
+            codeVerifier = randomBytes.toBase64()
 
             // hash bytes using sha256
             val md = MessageDigest.getInstance("SHA-256")
             val hashed = md.digest(randomBytes)
 
             // codeChallenge == base64(sha256(randomBytes))
-            val codeChallenge = Base64.UrlSafe.encode(hashed)
+            val codeChallenge = hashed.toBase64()
 
-            // embed into url parameters
-            val uriBuilder = Uri.parse(flowUrl).buildUpon()
-                .appendQueryParameter("ra-callback", deepLinkUrl)
-                .appendQueryParameter("ra-challenge", codeChallenge)
-                .appendQueryParameter("ra-initiator", "android")
-            backupCustomScheme?.let {
-                uriBuilder.appendQueryParameter("ra-backup-callback", it)
-            }
-            val uri = uriBuilder.build()
+            startFlowViaBrowser(codeChallenge, context)
+        }
 
-            // launch via chrome custom tabs
-            launchUri(context, uri)
+        override suspend fun start(context: Context, flowId: String, refreshJwt: String) {
+            val primeResponse = client.flowPrime(flowId, refreshJwt)
+            // use server generated verifier and challenge
+            codeVerifier = primeResponse.codeVerifier
+            startFlowViaBrowser(primeResponse.codeChallenge, context)
+        }
+
+        override fun start(context: Context, flowId: String, refreshJwt: String, callback: (Result<Unit>) -> Unit) = wrapCoroutine(callback) {
+            start(context, flowId, refreshJwt)
         }
 
         override fun resume(context: Context, incomingUriString: String) {
@@ -92,6 +90,22 @@ internal class Flow(
         override fun exchange(incomingUri: Uri, callback: (Result<AuthenticationResponse>) -> Unit) = wrapCoroutine(callback) {
             exchange(incomingUri)
         }
+        
+        // Internal
+
+        private fun startFlowViaBrowser(codeChallenge: String, context: Context) {
+            val uriBuilder = Uri.parse(flowUrl).buildUpon()
+                .appendQueryParameter("ra-callback", deepLinkUrl)
+                .appendQueryParameter("ra-challenge", codeChallenge)
+                .appendQueryParameter("ra-initiator", "android")
+            backupCustomScheme?.let {
+                uriBuilder.appendQueryParameter("ra-backup-callback", it)
+            }
+            val uri = uriBuilder.build()
+
+            // launch via chrome custom tabs
+            launchUri(context, uri)
+        }
 
     }
 

descopesdk/src/main/java/com/descope/sdk/Routes.kt

@@ -854,6 +854,25 @@ interface DescopeFlow {
          */
         fun start(context: Context)
 
+        /**
+         * Start a flow for a currently authenticated user from the current [context].
+         * 
+         * Use this version of start if the user has an **active session**.
+         * Note: This is an asynchronous operation that performs network requests before and
+         * opening the browser. It is thus recommended to switch the
+         * user interface to a loading state before calling this function, otherwise the user
+         * might accidentally interact with the app when the authentication view is not
+         * being displayed.
+         *
+         * @param context the context launching the authentication flow.
+         * @param flowId the ID of the flow to run
+         * @param refreshJwt the refreshJwt from an active [DescopeSession]. 
+         */
+        suspend fun start(context: Context, flowId: String, refreshJwt: String)
+
+        /** @see start (async version) */
+        fun start(context: Context, flowId: String, refreshJwt: String, callback: (Result<Unit>) -> Unit)
+
         /**
          * Resumes an ongoing flow after a redirect back to the app.
          * This is required for *Magic Link only* at this stage.