Class2BiometricAuthExtensions.kt

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package androidx.biometric.auth

import androidx.biometric.BiometricPrompt.AuthenticationResult
import androidx.fragment.app.Fragment
import androidx.fragment.app.FragmentActivity
import kotlinx.coroutines.suspendCancellableCoroutine
import java.util.concurrent.Executor

/**
 * Shows an authentication prompt to the user.
 *
 * @param host A wrapper for the component that will host the prompt.
 *
 * @return [AuthenticationResult] for a successful authentication.
 *
 * @throws AuthPromptErrorException  when an unrecoverable error has been encountered and
 * authentication has stopped.
 * @throws AuthPromptFailureException when an authentication attempt by the user has been rejected.
 *
 * @see Class2BiometricAuthPrompt.authenticate(AuthPromptHost, AuthPromptCallback)
 *
 * @sample androidx.biometric.samples.auth.class2BiometricAuth
 */
public suspend fun Class2BiometricAuthPrompt.authenticate(
    host: AuthPromptHost,
): AuthenticationResult {
    return suspendCancellableCoroutine { continuation ->
        val authPrompt = startAuthentication(
            host,
            Runnable::run,
            CoroutineAuthPromptCallback(continuation)
        )

        continuation.invokeOnCancellation {
            authPrompt.cancelAuthentication()
        }
    }
}

/**
 * Prompts the user to authenticate with a **Class 2** biometric (e.g. fingerprint, face, or iris).
 *
 * Note that **Class 3** biometrics are guaranteed to meet the requirements for **Class 2** and thus
 * will also be accepted.
 *
 * @param title The title to be displayed on the prompt.
 * @param negativeButtonText The label for the negative button on the prompt.
 * @param subtitle An optional subtitle to be displayed on the prompt.
 * @param description An optional description to be displayed on the prompt.
 * @param confirmationRequired Whether user confirmation should be required for passive biometrics.
 * @param executor An executor for [callback] methods. If `null`, these will run on the main thread.
 * @param callback The object that will receive and process authentication events.
 * @return An [AuthPrompt] handle to the shown prompt.
 *
 * @see Class2BiometricAuthPrompt
 */
public fun FragmentActivity.startClass2BiometricAuthentication(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt {
    return startClass2BiometricAuthenticationInternal(
        AuthPromptHost(this),
        title,
        negativeButtonText,
        subtitle,
        description,
        confirmationRequired,
        executor,
        callback
    )
}

/**
 * Prompts the user to authenticate with a **Class 2** biometric (e.g. fingerprint, face, or iris).
 *
 * Note that **Class 3** biometrics are guaranteed to meet the requirements for **Class 2** and thus
 * will also be accepted.
 *
 * @param title The title to be displayed on the prompt.
 * @param negativeButtonText The label for the negative button on the prompt.
 * @param subtitle An optional subtitle to be displayed on the prompt.
 * @param description An optional description to be displayed on the prompt.
 * @param confirmationRequired Whether user confirmation should be required for passive biometrics.
 *
 * @return [AuthenticationResult] for a successful authentication.
 *
 * @throws AuthPromptErrorException  when an unrecoverable error has been encountered and
 * authentication has stopped.
 * @throws AuthPromptFailureException when an authentication attempt by the user has been rejected.
 *
 * @see Class2BiometricAuthPrompt
 */
public suspend fun FragmentActivity.authenticateWithClass2Biometrics(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
): AuthenticationResult {
    val authPrompt = buildClass2BiometricAuthPrompt(
        title,
        negativeButtonText,
        subtitle,
        description,
        confirmationRequired,
    )

    return authPrompt.authenticate(AuthPromptHost(this))
}

/**
 * Prompts the user to authenticate with a **Class 2** biometric (e.g. fingerprint, face, or iris).
 *
 * Note that **Class 3** biometrics are guaranteed to meet the requirements for **Class 2** and thus
 * will also be accepted.
 *
 * @param title The title to be displayed on the prompt.
 * @param negativeButtonText The label for the negative button on the prompt.
 * @param subtitle An optional subtitle to be displayed on the prompt.
 * @param description An optional description to be displayed on the prompt.
 * @param confirmationRequired Whether user confirmation should be required for passive biometrics.
 * @param executor An executor for [callback] methods. If `null`, these will run on the main thread.
 * @param callback The object that will receive and process authentication events.
 * @return An [AuthPrompt] handle to the shown prompt.
 *
 * @see Class2BiometricAuthPrompt
 */
public fun Fragment.startClass2BiometricAuthentication(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt {
    return startClass2BiometricAuthenticationInternal(
        AuthPromptHost(this),
        title,
        negativeButtonText,
        subtitle,
        description,
        confirmationRequired,
        executor,
        callback
    )
}

/**
 * Prompts the user to authenticate with a **Class 2** biometric (e.g. fingerprint, face, or iris).
 *
 * Note that **Class 3** biometrics are guaranteed to meet the requirements for **Class 2** and thus
 * will also be accepted.
 *
 * @param title The title to be displayed on the prompt.
 * @param negativeButtonText The label for the negative button on the prompt.
 * @param subtitle An optional subtitle to be displayed on the prompt.
 * @param description An optional description to be displayed on the prompt.
 * @param confirmationRequired Whether user confirmation should be required for passive biometrics.
 *
 * @return [AuthenticationResult] for a successful authentication.
 *
 * @throws AuthPromptErrorException  when an unrecoverable error has been encountered and
 * authentication has stopped.
 * @throws AuthPromptFailureException when an authentication attempt by the user has been rejected.
 *
 * @see Class2BiometricAuthPrompt
 */
public suspend fun Fragment.authenticateWithClass2Biometrics(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
): AuthenticationResult {
    val authPrompt = buildClass2BiometricAuthPrompt(
        title,
        negativeButtonText,
        subtitle,
        description,
        confirmationRequired,
    )

    return authPrompt.authenticate(AuthPromptHost(this))
}

/**
 * Creates a [Class2BiometricAuthPrompt] with the given parameters.
 */
private fun buildClass2BiometricAuthPrompt(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
): Class2BiometricAuthPrompt = Class2BiometricAuthPrompt.Builder(title, negativeButtonText)
    .apply {
        subtitle?.let { setSubtitle(it) }
        description?.let { setDescription(it) }
        setConfirmationRequired(confirmationRequired)
    }
    .build()

/**
 * Creates a [Class2BiometricAuthPrompt] with the given parameters and starts authentication.
 */
private fun startClass2BiometricAuthenticationInternal(
    host: AuthPromptHost,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt {
    val prompt = buildClass2BiometricAuthPrompt(
        title,
        negativeButtonText,
        subtitle,
        description,
        confirmationRequired
    )

    return if (executor == null) {
        prompt.startAuthentication(host, callback)
    } else {
        prompt.startAuthentication(host, executor, callback)
    }
}