Client Auth

<!-- res/xml/portal_backup_rules.xml — Android 11 and below -->
<full-backup-content>
  <exclude domain="sharedpref" path="PortalAuth.xml" />
</full-backup-content>

<!-- res/xml/portal_data_extraction_rules.xml — Android 12 and later -->
<data-extraction-rules>
  <cloud-backup>
    <exclude domain="sharedpref" path="PortalAuth.xml" />
  </cloud-backup>
  <device-transfer>
    <exclude domain="sharedpref" path="PortalAuth.xml" />
  </device-transfer>
</data-extraction-rules>

<application
    ...
    android:fullBackupContent="@xml/portal_backup_rules"
    android:dataExtractionRules="@xml/portal_data_extraction_rules">
</application>

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">

  <!-- your existing MAIN/LAUNCHER intent-filter stays as it is -->

  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" android:host="auth" />
  </intent-filter>
</activity>

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="example.com" android:pathPrefix="/auth/callback" />
</intent-filter>

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    handleIntent(intent)
}

import io.portalhq.android.auth.PortalAuth
import io.portalhq.android.auth.data.MagicLinkConfig

// `by lazy`, not an eager initializer — see the warning below.
val portalAuth: PortalAuth by lazy {
    PortalAuth(
        authEnvironmentId = "YOUR_AUTH_ENVIRONMENT_ID",
        redirectUrl = "myapp://auth/callback",
        // Required only by sendMagicLink()
        magicLink = MagicLinkConfig(
            fromEmail = "hello@auth.example.com",
            templateId = "YOUR_TEMPLATE_ID",
        ),
        // Optional: whether the client Portal creates uses gas sponsorship
        // isAccountAbstracted = true,
    )
}

import io.portalhq.android.auth.data.AuthMethodsResult

private suspend fun loadMethods(): AuthMethodsResult {
    val methods = portalAuth.getMethods()

    Log.i("[PortalAuth]", "✅ enabled: ${methods.allowedAuthMethods}")
    Log.i("[PortalAuth]", "✅ autoCreateWallet: ${methods.autoCreateWallet}")

    return methods
}

import android.content.Intent
import android.net.Uri
import io.portalhq.android.auth.data.AuthMethod

private suspend fun signInWithProvider(method: AuthMethod) {
    val (authorizeUrl) = when (method) {
        AuthMethod.GOOGLE -> portalAuth.loginWithGoogle()
        AuthMethod.APPLE -> portalAuth.loginWithApple()
        else -> return
    }

    startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(authorizeUrl)))
}

private suspend fun sendMagicLink(input: String) {
    // The API requires a lowercase address and rejects anything else with a 400.
    val email = input.trim().lowercase()

    portalAuth.sendMagicLink(email)

    Log.i("[PortalAuth]", "✅ magic link sent — check $email")
}

import android.content.Intent
import android.os.Bundle
import android.util.Log
import androidx.lifecycle.lifecycleScope
import io.portalhq.android.auth.data.AuthResult
import io.portalhq.android.exceptions.PortalException
import java.io.IOException
import kotlinx.coroutines.launch

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    handleIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    // `singleTask` does not refresh getIntent() on its own.
    setIntent(intent)
    handleIntent(intent)
}

private fun handleIntent(incoming: Intent?) {
    val intent = incoming ?: return
    val url = intent.data?.toString() ?: return

    lifecycleScope.launch {
        try {
            val result = portalAuth.handleRedirect(url)

            // Not a Client Auth redirect — leave the Intent as it is so the rest
            // of your routing still sees it.
            if (result == null) return@launch

            // Consumed. Clear it so a process recreated with this Intent still
            // attached does not try to exchange the same grant a second time.
            intent.data = null
            setIntent(intent)

            when (result) {
                is AuthResult.TotpRequired -> promptForTotp(result)

                // Must be safe to run twice — see the warning below.
                is AuthResult.Authenticated -> onSignedIn(result.session)
            }
        } catch (e: PortalException.Auth.AuthenticationFailed) {
            Log.e("[PortalAuth]", "❌ the user did not complete the provider sign-in", e)
        } catch (e: IOException) {
            // The grant was not spent — leave the Intent in place so the redirect can be retried.
            Log.e("[PortalAuth]", "❌ network failure exchanging the redirect — retry", e)
        } catch (e: PortalException) {
            Log.e("[PortalAuth]", "❌ handleRedirect failed", e)
        }
    }
}

import io.portalhq.android.auth.PortalSession
import io.portalhq.android.auth.data.AuthResult
import java.io.IOException

private suspend fun verifyTotp(
    challenge: AuthResult.TotpRequired,
    code: String,
): PortalSession? = try {
    val result = portalAuth.verifyTotp(code, challenge.userJwt)

    // The same session the non-TOTP path returns. Pass it to Portal(credentials = …).
    result.session
} catch (e: IOException) {
    // Transport failure — the code was never checked, so the same code can be retried.
    Log.e("[PortalAuth]", "❌ verifyTotp could not reach Portal — retry", e)
    null
} catch (e: PortalException) {
    // A rejected code does not consume the userJwt, so prompting again is normal.
    Log.e("[PortalAuth]", "❌ verifyTotp failed — ask for the next code", e)
    null
}

import io.portalhq.android.Portal
import io.portalhq.android.auth.PortalSession

private fun createPortal(session: PortalSession): Portal {
    val portal = Portal(
        credentials = session,
        rpcConfig = mapOf("eip155:11155111" to YOUR_GATEWAY_URL),
    )

    portal.configureGoogleStorage(
        GDriveConfiguration(
            clientId = YOUR_GDRIVE_CLIENT_ID,
            signOutAfterUse = true,
            gDriveBackupOption = GDriveBackupOption.AppDataFolder,
        )
    )

    return portal
}

private suspend fun resolveWallet(portal: Portal) {
    if (portal.doesWalletExistOrThrow()) {
        if (portal.isWalletOnDeviceOrThrow()) {
            Log.i("[PortalAuth]", "✅ reusing the existing wallet")
        } else {
            // The wallet exists elsewhere — recover it. See Recover a wallet.
            Log.i("[PortalAuth]", "✅ wallet exists but is not on this device")
        }
        return
    }

    if (!portalAuth.getMethods().autoCreateWallet) {
        Log.i("[PortalAuth]", "✅ autoCreateWallet is off — not creating a wallet")
        return
    }

    portal.createWallet()
        .onSuccess { Log.i("[PortalAuth]", "✅ wallet created: $it") }
        .onFailure { Log.e("[PortalAuth]", "❌ createWallet failed", it) }
}

private suspend fun restore(): PortalSession? = try {
    val session = portalAuth.restoreSession()

    if (session == null) {
        Log.i("[PortalAuth]", "✅ nothing stored — show the sign-in screen")
    }

    session
} catch (e: PortalException.Auth.SessionStorageFailure) {
    // Storage itself failed this time. It may succeed on the next attempt.
    Log.e("[PortalAuth]", "❌ restoreSession failed", e)
    null
}

// Signing the current user out.
private suspend fun signOut(portal: Portal) {
    portal.clearSession()
}

// Clearing storage when there is no Portal to clear through.
private suspend fun clearStoredSession() {
    portalAuth.clearPersistedSession()
}

import io.portalhq.android.Portal
import io.portalhq.android.auth.PortalSession
import java.io.Closeable
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow

object PortalHolder {
    private val _sessionEnded = MutableStateFlow(false)
    val sessionEnded: StateFlow<Boolean> = _sessionEnded

    private var portal: Portal? = null
    private var subscription: Closeable? = null

    fun adopt(session: PortalSession): Portal = synchronized(this) {
        // Closed first: each Portal needs its own subscription, and the previous
        // one would otherwise stay reachable for the life of its session.
        subscription?.close()

        val created = createPortal(session)
        // Runs on whichever thread saw the 401 — record state, never touch UI.
        subscription = created.onSessionInvalidated { _sessionEnded.value = true }

        portal = created
        created
    }

    fun signedOut(): Unit = synchronized(this) {
        subscription?.close()
        subscription = null
        portal = null
        _sessionEnded.value = false
    }
}

import io.portalhq.android.exceptions.PortalException

/**
 * @param completingSignIn true when the failure came from handleRedirect() or
 *   verifyTotp(). A 400 means a spent or expired grant only there; anywhere else
 *   it is a rejected request and must not be reported as an expiry.
 */
private fun describe(error: Throwable, completingSignIn: Boolean): String = when (error) {
    is PortalException.Auth.AuthMethodUnavailable ->
        "That sign-in method is not available."

    is PortalException.Auth.AuthenticationFailed ->
        "Sign-in was not completed."

    is PortalException.Credentials.PortalCredentialError ->
        if (error.requiresReauthentication) {
            "Your session ended. Please sign in again."
        } else {
            "Could not read your session. Please try again."
        }

    is PortalException.Api.HttpBadRequest ->
        if (completingSignIn) {
            "That sign-in link has expired. Please start a new sign-in."
        } else {
            "That request was rejected. Please check your details and try again."
        }

    else -> "Something went wrong."
}