feat: MFA Enrollment (SMS)

auth/src/main/java/com/firebase/ui/auth/compose/mfa/SmsEnrollmentHandler.kt

@@ -0,0 +1,372 @@
+/*
+ * Copyright 2025 Google Inc. All Rights Reserved.
+ *
+ * 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 com.firebase.ui.auth.compose.mfa
+
+import com.firebase.ui.auth.compose.configuration.auth_provider.AuthProvider
+import com.google.firebase.auth.FirebaseAuth
+import com.google.firebase.auth.FirebaseUser
+import com.google.firebase.auth.MultiFactorAssertion
+import com.google.firebase.auth.PhoneAuthCredential
+import com.google.firebase.auth.PhoneAuthProvider
+import com.google.firebase.auth.PhoneMultiFactorGenerator
+import kotlinx.coroutines.tasks.await
+
+/**
+ * Handler for SMS multi-factor authentication enrollment.
+ *
+ * This class manages the complete SMS enrollment flow, including:
+ * - Sending SMS verification codes to phone numbers
+ * - Resending codes with timer support
+ * - Verifying SMS codes entered by users
+ * - Finalizing enrollment with Firebase Authentication
+ *
+ * This handler uses the existing [AuthProvider.Phone.verifyPhoneNumberAwait] infrastructure
+ * for sending and verifying SMS codes, ensuring consistency with the primary phone auth flow.
+ *
+ * **Usage:**
+ * ```kotlin
+ * val handler = SmsEnrollmentHandler(auth, user)
+ *
+ * // Step 1: Send verification code
+ * val session = handler.sendVerificationCode("+1234567890")
+ *
+ * // Step 2: Display masked phone number and wait for user input
+ * val masked = session.getMaskedPhoneNumber()
+ *
+ * // Step 3: If needed, resend code after timer expires
+ * val newSession = handler.resendVerificationCode(session)
+ *
+ * // Step 4: Verify the code entered by the user
+ * val verificationCode = "123456" // From user input
+ * handler.enrollWithVerificationCode(session, verificationCode, "My Phone")
+ * ```
+ *
+ * @property auth The [FirebaseAuth] instance
+ * @property user The [FirebaseUser] to enroll in SMS MFA
+ *
+ * @since 10.0.0
+ * @see TotpEnrollmentHandler
+ * @see AuthProvider.Phone.verifyPhoneNumberAwait
+ */
+class SmsEnrollmentHandler(
+    private val auth: FirebaseAuth,
+    private val user: FirebaseUser
+) {
+    private val phoneProvider = AuthProvider.Phone(
+        defaultNumber = null,
+        defaultCountryCode = null,
+        allowedCountries = null,
+        smsCodeLength = SMS_CODE_LENGTH,
+        timeout = VERIFICATION_TIMEOUT_SECONDS,
+        isInstantVerificationEnabled = true
+    )
+    /**
+     * Sends an SMS verification code to the specified phone number.
+     *
+     * This method initiates the SMS enrollment process by sending a verification code
+     * to the provided phone number. The code will be sent via SMS and should be
+     * displayed to the user for entry.
+     *
+     * **Important:** The user must re-authenticate before calling this method if their
+     * session is not recent. Use [FirebaseUser.reauthenticate] if needed.
+     *
+     * @param phoneNumber The phone number in E.164 format (e.g., "+1234567890")
+     * @return An [SmsEnrollmentSession] containing the verification ID and metadata
+     * @throws Exception if the user needs to re-authenticate, phone number is invalid,
+     *                   or SMS sending fails
+     *
+     * @see resendVerificationCode
+     * @see SmsEnrollmentSession.getMaskedPhoneNumber
+     */
+    suspend fun sendVerificationCode(phoneNumber: String): SmsEnrollmentSession {
+        require(isValidPhoneNumber(phoneNumber)) {
+            "Phone number must be in E.164 format (e.g., +1234567890)"
+        }
+
+        val multiFactorSession = user.multiFactor.session.await()
+        val result = phoneProvider.verifyPhoneNumberAwait(
+            auth = auth,
+            phoneNumber = phoneNumber,
+            multiFactorSession = multiFactorSession,
+            forceResendingToken = null
+        )
+
+        return when (result) {
+            is AuthProvider.Phone.VerifyPhoneNumberResult.AutoVerified -> {
+                SmsEnrollmentSession(
+                    verificationId = "", // Not needed when auto-verified
+                    phoneNumber = phoneNumber,
+                    forceResendingToken = null,
+                    sentAt = System.currentTimeMillis(),
+                    autoVerifiedCredential = result.credential
+                )
+            }
+            is AuthProvider.Phone.VerifyPhoneNumberResult.NeedsManualVerification -> {
+                SmsEnrollmentSession(
+                    verificationId = result.verificationId,
+                    phoneNumber = phoneNumber,
+                    forceResendingToken = result.token,
+                    sentAt = System.currentTimeMillis()
+                )
+            }
+        }
+    }
+
+    /**
+     * Resends the SMS verification code to the phone number.
+     *
+     * This method uses the force resending token from the original session to
+     * explicitly request a new SMS code. This should only be called after the
+     * [RESEND_DELAY_SECONDS] has elapsed to respect rate limits.
+     *
+     * @param session The original [SmsEnrollmentSession] from [sendVerificationCode]
+     * @return A new [SmsEnrollmentSession] with updated verification ID and timestamp
+     * @throws Exception if resending fails or if the session doesn't have a resend token
+     *
+     * @see sendVerificationCode
+     */
+    suspend fun resendVerificationCode(session: SmsEnrollmentSession): SmsEnrollmentSession {
+        require(session.forceResendingToken != null) {
+            "Cannot resend code without a force resending token"
+        }
+
+        val multiFactorSession = user.multiFactor.session.await()
+        val result = phoneProvider.verifyPhoneNumberAwait(
+            auth = auth,
+            phoneNumber = session.phoneNumber,
+            multiFactorSession = multiFactorSession,
+            forceResendingToken = session.forceResendingToken
+        )
+
+        return when (result) {
+            is AuthProvider.Phone.VerifyPhoneNumberResult.AutoVerified -> {
+                SmsEnrollmentSession(
+                    verificationId = "", // Not needed when auto-verified
+                    phoneNumber = session.phoneNumber,
+                    forceResendingToken = session.forceResendingToken,
+                    sentAt = System.currentTimeMillis(),
+                    autoVerifiedCredential = result.credential
+                )
+            }
+            is AuthProvider.Phone.VerifyPhoneNumberResult.NeedsManualVerification -> {
+                SmsEnrollmentSession(
+                    verificationId = result.verificationId,
+                    phoneNumber = session.phoneNumber,
+                    forceResendingToken = result.token,
+                    sentAt = System.currentTimeMillis()
+                )
+            }
+        }
+    }
+
+    /**
+     * Verifies an SMS code and completes the enrollment process.
+     *
+     * This method creates a multi-factor assertion using the provided session and
+     * verification code, then enrolls the user in SMS MFA with Firebase Authentication.
+     *
+     * @param session The [SmsEnrollmentSession] from [sendVerificationCode] or [resendVerificationCode]
+     * @param verificationCode The 6-digit code from the SMS message
+     * @param displayName Optional friendly name for this MFA factor (e.g., "My Phone")
+     * @throws Exception if the verification code is invalid or if enrollment fails
+     *
+     * @see sendVerificationCode
+     * @see resendVerificationCode
+     */
+    suspend fun enrollWithVerificationCode(
+        session: SmsEnrollmentSession,
+        verificationCode: String,
+        displayName: String? = null
+    ) {
+        require(isValidCodeFormat(verificationCode)) {
+            "Verification code must be 6 digits"
+        }
+
+        val credential = session.autoVerifiedCredential
+            ?: PhoneAuthProvider.getCredential(session.verificationId, verificationCode)
+
+        val multiFactorAssertion = PhoneMultiFactorGenerator.getAssertion(credential)
+        user.multiFactor.enroll(multiFactorAssertion, displayName).await()
+    }
+
+    /**
+     * Validates that a verification code has the correct format for SMS.
+     *
+     * This method performs basic client-side validation to ensure the code:
+     * - Is not null or empty
+     * - Contains only digits
+     * - Has exactly 6 digits (the standard SMS code length)
+     *
+     * **Note:** This does not verify the code against the server. Use
+     * [enrollWithVerificationCode] to perform actual verification with Firebase.
+     *
+     * @param code The verification code to validate
+     * @return `true` if the code has a valid format, `false` otherwise
+     */
+    fun isValidCodeFormat(code: String): Boolean {
+        return code.isNotBlank() &&
+                code.length == SMS_CODE_LENGTH &&
+                code.all { it.isDigit() }
+    }
+
+    /**
+     * Validates that a phone number is in the correct E.164 format.
+     *
+     * E.164 format requirements:
+     * - Starts with "+"
+     * - Followed by 1-15 digits
+     * - No spaces, hyphens, or other characters
+     * - Minimum 4 digits total (country code + subscriber number)
+     *
+     * Examples of valid numbers:
+     * - +1234567890 (US)
+     * - +447911123456 (UK)
+     * - +33612345678 (France)
+     *
+     * @param phoneNumber The phone number to validate
+     * @return `true` if the phone number is in E.164 format, `false` otherwise
+     */
+    fun isValidPhoneNumber(phoneNumber: String): Boolean {
+        return phoneNumber.matches(Regex("^\\+[1-9]\\d{3,14}$"))
+    }
+
+    companion object {
+        /**
+         * The standard length for SMS verification codes.
+         */
+        const val SMS_CODE_LENGTH = 6
+
+        /**
+         * The verification timeout in seconds for phone authentication.
+         * This is how long Firebase will wait for auto-verification before
+         * falling back to manual code entry.
+         */
+        const val VERIFICATION_TIMEOUT_SECONDS = 60L
+
+        /**
+         * The recommended delay in seconds before allowing code resend.
+         * This prevents users from spamming the resend functionality and
+         * respects carrier rate limits.
+         */
+        const val RESEND_DELAY_SECONDS = 30
+
+        /**
+         * The Firebase factor ID for SMS multi-factor authentication.
+         */
+        const val FACTOR_ID = PhoneMultiFactorGenerator.FACTOR_ID
+    }
+}
+
+/**
+ * Represents an active SMS enrollment session with verification state.
+ *
+ * This class holds all the information needed to complete an SMS enrollment,
+ * including the verification ID, phone number, and resend token.
+ *
+ * @property verificationId The verification ID from Firebase
+ * @property phoneNumber The phone number being verified in E.164 format
+ * @property forceResendingToken Optional token for resending the SMS code
+ * @property sentAt Timestamp in milliseconds when the code was sent
+ * @property autoVerifiedCredential Optional credential if auto-verification succeeded
+ *
+ * @since 10.0.0
+ */
+data class SmsEnrollmentSession(
+    val verificationId: String,
+    val phoneNumber: String,
+    val forceResendingToken: PhoneAuthProvider.ForceResendingToken?,
+    val sentAt: Long,
+    val autoVerifiedCredential: PhoneAuthCredential? = null
+) {
+    /**
+     * Returns a masked version of the phone number for display purposes.
+     *
+     * Masks the middle digits of the phone number while keeping the country code
+     * and last few digits visible for user confirmation.
+     *
+     * Examples:
+     * - "+1234567890" → "+1••••••890"
+     * - "+447911123456" → "+44•••••••456"
+     *
+     * @return The masked phone number string
+     */
+    fun getMaskedPhoneNumber(): String {
+        return maskPhoneNumber(phoneNumber)
+    }
+
+    /**
+     * Checks if the resend delay has elapsed since the code was sent.
+     *
+     * @param delaySec The delay in seconds (default: [SmsEnrollmentHandler.RESEND_DELAY_SECONDS])
+     * @return `true` if enough time has passed to allow resending
+     */
+    fun canResend(delaySec: Int = SmsEnrollmentHandler.RESEND_DELAY_SECONDS): Boolean {
+        val elapsed = (System.currentTimeMillis() - sentAt) / 1000
+        return elapsed >= delaySec
+    }
+
+    /**
+     * Returns the remaining seconds until resend is allowed.
+     *
+     * @param delaySec The delay in seconds (default: [SmsEnrollmentHandler.RESEND_DELAY_SECONDS])
+     * @return The number of seconds remaining, or 0 if resend is already allowed
+     */
+    fun getRemainingResendSeconds(delaySec: Int = SmsEnrollmentHandler.RESEND_DELAY_SECONDS): Int {
+        val elapsed = (System.currentTimeMillis() - sentAt) / 1000
+        return maxOf(0, delaySec - elapsed.toInt())
+    }
+}
+
+/**
+ * Masks the middle digits of a phone number for privacy.
+ *
+ * The function keeps the country code (first 1-3 characters after +) and
+ * the last 2-4 digits visible, masking everything in between with bullets.
+ * Longer phone numbers show more last digits for better user confirmation.
+ *
+ * Examples:
+ * - "+1234567890" → "+1••••••890" (11 chars, last 3 digits)
+ * - "+447911123456" → "+44•••••••456" (13 chars, last 3 digits)
+ * - "+33612345678" → "+33•••••••678" (12 chars, last 3 digits)
+ * - "+8861234567890" → "+88••••••••7890" (14+ chars, last 4 digits)
+ *
+ * @param phoneNumber The phone number to mask in E.164 format
+ * @return The masked phone number string
+ */
+fun maskPhoneNumber(phoneNumber: String): String {
+    if (!phoneNumber.startsWith("+") || phoneNumber.length < 8) {
+        return phoneNumber
+    }
+
+    // Determine country code length (typically 1-3 digits after +)
+    val digitsOnly = phoneNumber.substring(1) // Remove +
+    val countryCodeLength = when {
+        digitsOnly.length > 10 -> 2 // Likely 2-digit country code
+        digitsOnly[0] == '1' -> 1 // North America
+        else -> 2 // Most other countries
+    }
+
+    val countryCode = phoneNumber.substring(0, countryCodeLength + 1) // Include +
+    // Keep last 3-4 digits visible, with longer numbers showing more
+    val lastDigitsCount = when {
+        phoneNumber.length >= 14 -> 4 // Long numbers show 4 digits
+        phoneNumber.length >= 11 -> 3 // Medium numbers show 3 digits
+        else -> 2 // Short numbers show 2 digits
+    }
+    val lastDigits = phoneNumber.takeLast(lastDigitsCount)
+    val maskedLength = phoneNumber.length - countryCode.length - lastDigitsCount
+
+    return "$countryCode${"•".repeat(maskedLength)}$lastDigits"
+}