Improve activity resolution and authentication handling

Refactored activity resolution to use ActivityContextHolder as a fallback throughout the sensitive info module and internal classes, improving reliability when currentActivity is unavailable. Enhanced CryptoManager to support universal authentication flows for both encryption and decryption, handling Android version differences. Moved StorageResult to its own file and updated usages for clarity. Improved biometric authentication handling for API 28 and below, ensuring consistent user prompts and fallback logic.

Author: mCodex

android/src/main/java/com/sensitiveinfo/SensitiveInfoModule.kt

@@ -9,6 +9,7 @@ import com.facebook.react.bridge.Arguments
 import com.sensitiveinfo.internal.HybridSensitiveInfo
 import com.sensitiveinfo.internal.auth.AuthenticationPrompt
 import com.sensitiveinfo.internal.util.SensitiveInfoException
+import com.sensitiveinfo.internal.util.ActivityContextHolder
 import androidx.fragment.app.FragmentActivity
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -104,12 +105,26 @@ import kotlinx.coroutines.launch
 class SensitiveInfoModule(reactContext: ReactApplicationContext) :
     ReactContextBaseJavaModule(reactContext) {
 
-    private val sensitiveInfo: HybridSensitiveInfo
     private val coroutineScope = CoroutineScope(Dispatchers.Main)
 
-    init {
+    /**
+     * Lazy initialization of HybridSensitiveInfo with runtime activity resolution.
+     *
+     * **Why lazy?**
+     * - reactContext.currentActivity might be null at module initialization
+     * - Activity becomes available after the app starts
+     * - We get the activity dynamically when first needed
+     *
+     * **Activity Resolution**:
+     * 1. First try: reactContext.currentActivity
+     * 2. Fallback: ActivityContextHolder.getActivity()
+     * 3. If both null: BiometricAuthenticator will handle gracefully
+     */
+    private val sensitiveInfo: HybridSensitiveInfo by lazy {
         val activity = reactContext.currentActivity as? FragmentActivity
-        sensitiveInfo = HybridSensitiveInfo(
+            ?: ActivityContextHolder.getActivity()
+        
+        HybridSensitiveInfo(
             context = reactContext,
             activity = activity
         )

android/src/main/java/com/sensitiveinfo/internal/HybridSensitiveInfo.kt

@@ -285,18 +285,8 @@ class HybridSensitiveInfo(
         }
 
         return try {
-            val storageResult = storage.getItem(key, service)
-            storageResult?.let { result ->
-                StorageResult(
-                    value = result.value,
-                    metadata = StorageMetadata(
-                        securityLevel = result.metadata.securityLevel,
-                        accessControl = result.metadata.accessControl,
-                        backend = result.metadata.backend,
-                        timestamp = result.metadata.timestamp
-                    )
-                )
-            }
+            // storage.getItem() already returns StorageResult with metadata
+            storage.getItem(key, service)
         } catch (e: SensitiveInfoException) {
             throw e
         } catch (e: Exception) {

android/src/main/java/com/sensitiveinfo/internal/auth/BiometricAuthenticator.kt

@@ -7,6 +7,7 @@ import androidx.biometric.BiometricManager.Authenticators
 import androidx.biometric.BiometricPrompt
 import androidx.fragment.app.FragmentActivity
 import com.sensitiveinfo.internal.util.SensitiveInfoException
+import com.sensitiveinfo.internal.util.ActivityContextHolder
 import java.util.concurrent.Executor
 import java.util.concurrent.Executors
 import javax.crypto.Cipher
@@ -256,25 +257,36 @@ internal class BiometricAuthenticator(
         cipher: Cipher? = null,
         allowDeviceCredential: Boolean = true
     ): Cipher? {
+        // Get the current activity (from constructor or from ActivityContextHolder)
+        val currentActivity = activity ?: ActivityContextHolder.getActivity()
+        
+        if (currentActivity == null) {
+            throw SensitiveInfoException.ActivityUnavailable(
+                "FragmentActivity not available. " +
+                "Make sure to call ActivityContextHolder.setActivity() from MainActivity.onCreate(). " +
+                "Error: Authentication required an active fragmentActivity"
+            )
+        }
+
         // Determine which authentication method to use based on API level and availability
         val supportsInlineDeviceCredential = allowDeviceCredential && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q
         val allowLegacyDeviceCredential = allowDeviceCredential && Build.VERSION.SDK_INT < Build.VERSION_CODES.Q
 
         // Special handling for API 28 (Android 9): Biometric may not be available
         if (allowLegacyDeviceCredential && !canUseBiometric()) {
             // Biometric not available, try device credential manually
-            val success = DeviceCredentialPromptFragment.authenticate(activity, prompt)
+            val success = DeviceCredentialPromptFragment.authenticate(currentActivity, prompt)
             if (success) return cipher
             throw SensitiveInfoException.AuthenticationCanceled()
         }
 
         // Try BiometricPrompt (primary method for API 30+)
         return try {
-            authenticateWithBiometricPrompt(prompt, cipher, supportsInlineDeviceCredential)
+            authenticateWithBiometricPrompt(currentActivity, prompt, cipher, supportsInlineDeviceCredential)
         } catch (error: SensitiveInfoException) {
             // BiometricPrompt failed, try legacy device credential fallback
             if (allowLegacyDeviceCredential && error !is SensitiveInfoException.AuthenticationCanceled) {
-                val success = DeviceCredentialPromptFragment.authenticate(activity, prompt)
+                val success = DeviceCredentialPromptFragment.authenticate(currentActivity, prompt)
                 if (success) return cipher
             }
             throw error
@@ -301,6 +313,7 @@ internal class BiometricAuthenticator(
      * - API 30: Can use BIOMETRIC_STRONG | DEVICE_CREDENTIAL
      * - API 28-29: Only BIOMETRIC_STRONG available (no official device credential in BiometricPrompt)
      *
+     * @param fragmentActivity Required FragmentActivity for BiometricPrompt rendering
      * @param prompt User-facing prompt configuration
      * @param cipher Optional cipher to authenticate
      * @param supportsInlineDeviceCredential Whether to allow device credential in BiometricPrompt
@@ -309,6 +322,7 @@ internal class BiometricAuthenticator(
      * @throws SensitiveInfoException on authentication failure
      */
     private suspend fun authenticateWithBiometricPrompt(
+        fragmentActivity: FragmentActivity,
         prompt: AuthenticationPrompt,
         cipher: Cipher?,
         supportsInlineDeviceCredential: Boolean
@@ -394,7 +408,7 @@ internal class BiometricAuthenticator(
             }
 
             // Create and show BiometricPrompt
-            val biometricPrompt = BiometricPrompt(activity, executor, callback)
+            val biometricPrompt = BiometricPrompt(fragmentActivity, executor, callback)
 
             // Handle coroutine cancellation (user dismisses prompt)
             continuation.invokeOnCancellation {

android/src/main/java/com/sensitiveinfo/internal/crypto/CryptoManager.kt

@@ -46,10 +46,18 @@ internal class CryptoManager(
      *
      * **Workflow:**
      * 1. Get or create key using the resolution
-     * 2. Initialize AES-GCM cipher (generates random IV)
-     * 3. If authentication required, show BiometricPrompt
-     * 4. Encrypt data
-     * 5. Return ciphertext + IV
+     * 2. Determine authentication strategy based on Android version
+     * 3. If authentication required:
+     *    - **Android 10+ (API 29+)** → Authenticate *with* a cipher (keystore gated)
+     *    - **Android 7-9 (API 24-28)** → Authenticate *before* crypto (app gated)
+     * 4. Initialize AES-GCM cipher and encrypt
+     * 5. Return ciphertext + IV (12-byte GCM nonce)
+     *
+     * **Universal Authentication Model**:
+     * - Android 10+ benefits from hardware-backed key authentication via `CryptoObject`
+     * - Android 7-9 perform a manual biometric/credential prompt before using the key
+     * - Both paths guarantee that the caller experiences an authentication UI whenever
+     *   `AccessResolution.requiresAuthentication == true`
      *
      * @param alias Unique key identifier
      * @param plaintext Data to encrypt (UTF-8 string converted to bytes)
@@ -70,36 +78,54 @@ internal class CryptoManager(
             // Step 1: Get or create key with proper authentication configuration
             val key = getOrCreateKey(alias, resolution)
 
-            // Step 2: Initialize cipher (generates random IV automatically)
+            // Step 2: Prepare cipher and authentication strategy
             val cipher = Cipher.getInstance(TRANSFORMATION)
-            cipher.init(Cipher.ENCRYPT_MODE, key)
+            val requiresAuth = resolution.requiresAuthentication
+            val supportsKeystoreAuth = requiresAuth && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q
+            val deviceCredentialAllowed =
+                (resolution.allowedAuthenticators and Authenticators.DEVICE_CREDENTIAL) != 0
+            val resolvedPrompt = prompt ?: AuthenticationPrompt(title = "Authenticate")
 
-            // Step 3: Get the IV that was generated
-            val iv = cipher.iv
+            val workingCipher = when {
+                !requiresAuth -> {
+                    cipher.init(Cipher.ENCRYPT_MODE, key)
+                    cipher
+                }
+                supportsKeystoreAuth -> {
+                    val auth = authenticator ?: throw SensitiveInfoException.EncryptionFailed(
+                        "Biometric authenticator unavailable",
+                        IllegalStateException("No authenticator configured")
+                    )
+                    cipher.init(Cipher.ENCRYPT_MODE, key)
+                    val authenticatedCipher = auth.authenticate(
+                        prompt = resolvedPrompt,
+                        cipher = cipher,
+                        allowDeviceCredential = deviceCredentialAllowed
+                    ) ?: cipher
+                    authenticatedCipher
+                }
+                else -> {
+                    val auth = authenticator ?: throw SensitiveInfoException.EncryptionFailed(
+                        "Biometric authenticator unavailable",
+                        IllegalStateException("No authenticator configured")
+                    )
+                    // Android 7-9: authenticate first (no CryptoObject), then proceed
+                    auth.authenticate(
+                        prompt = resolvedPrompt,
+                        cipher = null,
+                        allowDeviceCredential = deviceCredentialAllowed
+                    )
+                    cipher.init(Cipher.ENCRYPT_MODE, key)
+                    cipher
+                }
+            }
+
+            val iv = workingCipher.iv
                 ?: throw SensitiveInfoException.EncryptionFailed(
                     "Cipher did not generate IV",
                     Exception("cipher.iv returned null")
                 )
-
-            // Step 4: If authentication is required, show biometric prompt
-            val readyCipher = if (resolution.requiresAuthentication) {
-                val resolvedPrompt = prompt ?: AuthenticationPrompt(title = "Authenticate")
-                val deviceCredentialAllowed =
-                    (resolution.allowedAuthenticators and Authenticators.DEVICE_CREDENTIAL) != 0
-                authenticator?.authenticate(
-                    prompt = resolvedPrompt,
-                    cipher = cipher,
-                    allowDeviceCredential = deviceCredentialAllowed
-                ) ?: throw SensitiveInfoException.EncryptionFailed(
-                    "Biometric authenticator unavailable",
-                    IllegalStateException("No authenticator configured")
-                )
-            } else {
-                cipher
-            }
-
-            // Step 5: Encrypt the plaintext
-            val ciphertext = readyCipher.doFinal(plaintext)
+            val ciphertext = workingCipher.doFinal(plaintext)
 
             EncryptionResult(ciphertext = ciphertext, iv = iv)
         } catch (e: SensitiveInfoException) {
@@ -132,11 +158,17 @@ internal class CryptoManager(
      * Decrypts ciphertext using stored IV and key from alias.
      *
      * **Workflow:**
-     * 1. Get existing key from keystore
-     * 2. Initialize AES-GCM cipher with stored IV
-     * 3. If authentication required, show BiometricPrompt
-     * 4. Decrypt data (automatically verifies GCM auth tag)
-     * 5. Return plaintext
+     * 1. Validate IV and fetch key from AndroidKeyStore
+     * 2. Determine authentication strategy based on Android version
+     * 3. If authentication required:
+     *    - **Android 10+ (API 29+)** → Authenticate *with* the decrypt cipher
+     *    - **Android 7-9 (API 24-28)** → Authenticate *before* initializing the cipher
+     * 4. Initialize AES-GCM cipher with stored IV
+     * 5. Decrypt (verifies GCM tag automatically)
+     *
+     * **Universal Authentication Model** mirrors encrypt(): caller always sees an
+     * authentication prompt when required, while the keystore flow remains stable on
+     * older devices.
      *
      * @param alias Unique key identifier (must match encryption)
      * @param ciphertext Encrypted data (includes 16-byte GCM auth tag)
@@ -174,30 +206,50 @@ internal class CryptoManager(
                 )
             }
 
-            // Step 3: Initialize cipher with stored IV
+            // Step 3: Prepare cipher and authentication strategy
             val cipher = Cipher.getInstance(TRANSFORMATION)
             val spec = GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv)
-            cipher.init(Cipher.DECRYPT_MODE, key, spec)
+            val requiresAuth = resolution.requiresAuthentication
+            val supportsKeystoreAuth = requiresAuth && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q
+            val deviceCredentialAllowed =
+                (resolution.allowedAuthenticators and Authenticators.DEVICE_CREDENTIAL) != 0
+            val resolvedPrompt = prompt ?: AuthenticationPrompt(title = "Authenticate")
 
-            // Step 4: If authentication is required, show biometric prompt
-            val readyCipher = if (resolution.requiresAuthentication) {
-                val resolvedPrompt = prompt ?: AuthenticationPrompt(title = "Authenticate")
-                val deviceCredentialAllowed =
-                    (resolution.allowedAuthenticators and Authenticators.DEVICE_CREDENTIAL) != 0
-                authenticator?.authenticate(
-                    prompt = resolvedPrompt,
-                    cipher = cipher,
-                    allowDeviceCredential = deviceCredentialAllowed
-                ) ?: throw SensitiveInfoException.DecryptionFailed(
-                    "Biometric authenticator unavailable",
-                    IllegalStateException("No authenticator configured")
-                )
-            } else {
-                cipher
+            val workingCipher = when {
+                !requiresAuth -> {
+                    cipher.init(Cipher.DECRYPT_MODE, key, spec)
+                    cipher
+                }
+                supportsKeystoreAuth -> {
+                    val auth = authenticator ?: throw SensitiveInfoException.DecryptionFailed(
+                        "Biometric authenticator unavailable",
+                        IllegalStateException("No authenticator configured")
+                    )
+                    cipher.init(Cipher.DECRYPT_MODE, key, spec)
+                    val authenticatedCipher = auth.authenticate(
+                        prompt = resolvedPrompt,
+                        cipher = cipher,
+                        allowDeviceCredential = deviceCredentialAllowed
+                    ) ?: cipher
+                    authenticatedCipher
+                }
+                else -> {
+                    val auth = authenticator ?: throw SensitiveInfoException.DecryptionFailed(
+                        "Biometric authenticator unavailable",
+                        IllegalStateException("No authenticator configured")
+                    )
+                    auth.authenticate(
+                        prompt = resolvedPrompt,
+                        cipher = null,
+                        allowDeviceCredential = deviceCredentialAllowed
+                    )
+                    cipher.init(Cipher.DECRYPT_MODE, key, spec)
+                    cipher
+                }
             }
 
             // Step 5: Decrypt and verify auth tag (fails if tag doesn't match)
-            readyCipher.doFinal(ciphertext)
+            workingCipher.doFinal(ciphertext)
         } catch (e: SensitiveInfoException) {
             throw e
         } catch (e: KeyPermanentlyInvalidatedException) {

android/src/main/java/com/sensitiveinfo/internal/crypto/KeyAuthenticationStrategy.kt

@@ -58,18 +58,14 @@ internal object KeyAuthenticationStrategy {
                 applyApi29(builder, resolution)
             }
             Build.VERSION.SDK_INT >= Build.VERSION_CODES.P -> {
-                // API 28: Use deprecated timeout-based authentication
+                // API 28: Manual pre-authentication (see applyApi28)
                 applyApi28(builder, resolution)
             }
             else -> {
-                // API 21-27: No biometric support in keystore
-                // Fallback to plain key without authentication
-                // The resolution should have been downgraded by AccessControlResolver
-                // but we handle it gracefully here
-                throw SensitiveInfoException.EncryptionFailed(
-                    "Biometric authentication not supported on API ${Build.VERSION.SDK_INT}",
-                    Exception("Minimum API for biometric keystore protection is 28")
-                )
+                // API 21-27: Hardware-enforced authentication unavailable.
+                // We still present biometric/device credential prompts at the
+                // application layer, but the key itself cannot enforce auth.
+                builder.setUserAuthenticationRequired(false)
             }
         }
     }
@@ -117,26 +113,30 @@ internal object KeyAuthenticationStrategy {
 
     /**
      * API 28 (Android 9): No setUserAuthenticationParameters.
-     * Must use deprecated setUserAuthenticationValidityDurationSeconds.
-     *
-     * This is problematic because:
+     * Can't use timeout-based authentication because:
      * 1. The timeout is rarely shown to users as a prompt
-     * 2. It's deprecated in API 30+
-     * 3. It doesn't integrate well with BiometricPrompt
+     * 2. Cipher.init() must happen within the timeout window (impractical)
+     * 3. It's deprecated in API 30+
+     * 4. It doesn't integrate well with BiometricPrompt
+     *
+     * **Solution**: Don't require authentication at the KEY level.
+     * Instead, rely on BiometricPrompt at the APPLICATION level (CryptoManager).
+     * The workflow:
+     * 1. Create key WITHOUT authentication requirement
+     * 2. In CryptoManager, always show BiometricPrompt if authentication needed
+     * 3. BiometricPrompt happens at app level, not key level
+     * 4. This provides the same security: user must authenticate to access the secret
+     * 5. But it works reliably on Android 9
      *
-     * Solution: Use a 1-second timeout as a marker that auth WAS required.
-     * The BiometricAuthenticator will handle the actual biometric prompt separately.
+     * On Android 9, if the resolution requires authentication, we downgrade the key
+     * to not require authentication, and rely on app-level BiometricPrompt instead.
      */
     private fun applyApi28(
         builder: KeyGenParameterSpec.Builder,
         resolution: AccessResolution
     ) {
-        builder.setUserAuthenticationRequired(true)
-        
-        // Can't use setUserAuthenticationParameters on API 28
-        // Use timeout-based instead (deprecated, but necessary for API 28)
-        @Suppress("DEPRECATION")
-        builder.setUserAuthenticationValidityDurationSeconds(1)
+        // Android 9 relies on application-level authentication; keystore auth is disabled.
+        builder.setUserAuthenticationRequired(false)
     }
 
     /**