Refactor crypto and storage for modern access control

Introduces AccessResolution and KeyAuthenticationStrategy for unified key management and authentication across Android API levels. Updates SecureStorage and PersistedEntry to store and handle richer metadata, supports biometric/device credential configuration, and adds LegacyCryptoManager for migration compatibility. Refactors encryption/decryption flows to use new abstractions and improves error handling and metadata persistence.

Author: mCodex

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

@@ -155,7 +155,8 @@ class SensitiveInfoModule(reactContext: ReactApplicationContext) :
                     key = key,
                     value = value,
                     service = service,
-                    accessControl = accessControl
+                    accessControl = accessControl,
+                    authenticationPrompt = authenticationPrompt
                 )
 
                 // Return metadata to JavaScript

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

@@ -5,6 +5,8 @@ import com.sensitiveinfo.internal.storage.SecureStorage
 import com.sensitiveinfo.internal.storage.StorageResult
 import com.sensitiveinfo.internal.storage.StorageMetadata
 import com.sensitiveinfo.internal.util.SensitiveInfoException
+import com.sensitiveinfo.internal.util.ActivityContextHolder
+import com.sensitiveinfo.internal.auth.AuthenticationPrompt
 
 /**
  * HybridSensitiveInfo.kt
@@ -57,7 +59,10 @@ import com.sensitiveinfo.internal.util.SensitiveInfoException
  */
 class HybridSensitiveInfo(private val context: Context) {
 
-    private val storage = SecureStorage(context)
+    private val storage = SecureStorage(
+        context = context,
+        activity = ActivityContextHolder.getActivity()
+    )
 
     /**
      * Stores a secret in secure storage with optional biometric protection.
@@ -125,7 +130,8 @@ class HybridSensitiveInfo(private val context: Context) {
         key: String,
         value: String,
         service: String? = null,
-        accessControl: String? = null
+        accessControl: String? = null,
+        authenticationPrompt: AuthenticationPrompt? = null
     ): StorageResult {
         // Validate inputs
         if (key.isEmpty()) {
@@ -136,14 +142,13 @@ class HybridSensitiveInfo(private val context: Context) {
         }
 
         try {
-            // Simply delegate to storage
-            // The biometric prompt will be shown automatically by AndroidKeyStore
-            // when the key is used during encryption
+            // Delegate to storage and await the suspend function
             val storageMetadata = storage.setItem(
                 key = key,
                 value = value,
                 service = service,
-                accessControl = accessControl
+                accessControl = accessControl,
+                prompt = authenticationPrompt
             )
 
             return StorageResult(
@@ -197,7 +202,7 @@ class HybridSensitiveInfo(private val context: Context) {
      * @throws SensitiveInfoException.UserCancelled if user cancels biometric prompt
      * @throws SensitiveInfoException.KeystoreUnavailable if key not accessible
      */
-    fun getItem(key: String, service: String? = null): StorageResult? {
+    suspend fun getItem(key: String, service: String? = null): StorageResult? {
         if (key.isEmpty()) {
             throw SensitiveInfoException.InvalidConfiguration("key", "Cannot be empty")
         }

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

@@ -0,0 +1,52 @@
+package com.sensitiveinfo.internal.crypto
+
+import com.sensitiveinfo.internal.util.AccessControl
+import com.sensitiveinfo.internal.util.SecurityLevel
+
+/**
+ * Encapsulates all security configuration for a single key.
+ *
+ * **Purpose:**
+ * This is the SINGLE SOURCE OF TRUTH for how a key should be created and used.
+ * It includes:
+ * - What authentication is required
+ * - Which authenticators are allowed
+ * - Whether to use StrongBox
+ * - Whether to invalidate on biometric enrollment change
+ *
+ * **Determinism:**
+ * When decrypting an entry, AccessResolution is reconstructed from persisted
+ * metadata. Using the SAME resolution ensures decryption works identically
+ * to encryption.
+ *
+ * **API Abstraction:**
+ * The resolution describes WHAT we want (e.g., "biometric + StrongBox").
+ * KeyAuthenticationStrategy describes HOW to achieve it for each API level.
+ */
+internal data class AccessResolution(
+    val accessControl: AccessControl,
+    val securityLevel: SecurityLevel,
+    val requiresAuthentication: Boolean,
+    val allowedAuthenticators: Int,
+    val useStrongBox: Boolean,
+    val invalidateOnEnrollment: Boolean
+) {
+    /**
+     * Generates unique signature for this resolution.
+     *
+     * Used as part of the key alias to ensure different access controls
+     * use different keys.
+     */
+    val signature: String
+        get() = buildString {
+            append(accessControl.name)
+            append('_')
+            append(if (requiresAuthentication) '1' else '0')
+            append('_')
+            append(allowedAuthenticators)
+            append('_')
+            append(if (useStrongBox) '1' else '0')
+            append('_')
+            append(if (invalidateOnEnrollment) '1' else '0')
+        }
+}