Add documentation and improve error handling for SensitiveInfo

Added detailed KDoc and Swift doc comments to core SensitiveInfo classes and methods for both Android and iOS, improving maintainability and developer understanding. Introduced custom exception handling for not-found errors on Android, with matching error mapping in the TypeScript bridge to return null for missing items. Updated the example app to better handle value inclusion and UI state. These changes enhance cross-platform consistency, error reporting, and code clarity.

Author: mCodex

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

@@ -25,13 +25,28 @@ import com.sensitiveinfo.internal.storage.PersistedMetadata
 import com.sensitiveinfo.internal.storage.SecureStorage
 import com.sensitiveinfo.internal.util.AliasGenerator
 import com.sensitiveinfo.internal.util.ReactContextHolder
+import com.sensitiveinfo.internal.util.SensitiveInfoException
 import com.sensitiveinfo.internal.util.ServiceNameResolver
 import com.sensitiveinfo.internal.util.accessControlFromPersisted
 import com.sensitiveinfo.internal.util.storageBackendFromPersisted
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import kotlin.text.Charsets
 
+/**
+ * Android implementation of the SensitiveInfo Nitro module.
+ *
+ * All calls happen on Nitro managed promises, so the JS side can simply import the generated
+ * functions:
+ *
+ * ```ts
+ * import { setItem } from 'react-native-sensitive-info'
+ * await setItem('bank-pin', '1234', { accessControl: 'secureEnclaveBiometry' })
+ * ```
+ *
+ * The class resolves the appropriate storage backend, encrypts values with the Android Keystore,
+ * and keeps metadata so JavaScript consumers always know which security tier saved an entry.
+ */
 class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
     private val applicationContext get() = ReactContextHolder.requireContext()
 
@@ -42,6 +57,11 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
     private val authenticator by lazy { BiometricAuthenticator() }
     private val cryptoManager by lazy { CryptoManager(authenticator) }
 
+    /**
+     * Encrypts and stores a secret for the requested service/key pair.
+     *
+     * @return Metadata describing the security level used, mirroring the JS `MutationResult` type.
+     */
     override fun setItem(request: SensitiveInfoSetRequest): Promise<MutationResult> {
         return Promise.async {
             val service = serviceResolver.resolve(request.service)
@@ -90,11 +110,15 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
         }
     }
 
+    /**
+     * Reads a single item; optionally decrypts the payload if JS requested the plaintext value.
+     */
     override fun getItem(request: SensitiveInfoGetRequest): Promise<SensitiveInfoItem?> {
         return Promise.async {
             val includeValue = request.includeValue ?: true
             val service = serviceResolver.resolve(request.service)
-            val entry = withContext(Dispatchers.IO) { storage.read(service, request.key) } ?: return@async null
+                        val entry = withContext(Dispatchers.IO) { storage.read(service, request.key) }
+                            ?: throw SensitiveInfoException.NotFound(request.key, service)
 
             val metadata = entry.metadata.toStorageMetadata() ?: fallbackMetadata(entry)
 
@@ -113,6 +137,9 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
         }
     }
 
+    /**
+     * Deletes a saved secret. If the underlying keystore alias becomes unused we dispose it as well.
+     */
     override fun deleteItem(request: SensitiveInfoDeleteRequest): Promise<Boolean> {
         return Promise.async {
             val service = serviceResolver.resolve(request.service)
@@ -125,6 +152,9 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
         }
     }
 
+    /**
+     * Lightweight existence check backed by the SharedPreferences metadata store.
+     */
     override fun hasItem(request: SensitiveInfoHasRequest): Promise<Boolean> {
         return Promise.async {
             val service = serviceResolver.resolve(request.service)
@@ -134,6 +164,9 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
         }
     }
 
+    /**
+     * Enumerates every entry in a service. When `includeValues` is false the secrets stay encrypted.
+     */
     override fun getAllItems(request: SensitiveInfoEnumerateRequest?): Promise<Array<SensitiveInfoItem>> {
         return Promise.async {
             val includeValues = request?.includeValues == true
@@ -160,6 +193,9 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
         }
     }
 
+    /**
+     * Clears an entire service namespace and purges any orphaned keystore aliases.
+     */
     override fun clearService(request: SensitiveInfoOptions?): Promise<Unit> {
         return Promise.async {
             val service = serviceResolver.resolve(request?.service)

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

@@ -14,6 +14,13 @@ import javax.crypto.Cipher
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 
+/**
+ * Coroutine-friendly wrapper around `BiometricPrompt` used by the Keystore flows.
+ *
+ * The helper always executes prompts on the main dispatcher and returns the cipher configured for
+ * the successful authentication. Cancellation propagates back to the calling coroutine, matching
+ * the surface used by the Nitro Promise bridge.
+ */
 internal class BiometricAuthenticator {
   suspend fun authenticate(
     prompt: AuthenticationPrompt?,
@@ -84,6 +91,7 @@ internal class BiometricAuthenticator {
       }
     } else {
       if (allowsDeviceCredential) {
+        @Suppress("DEPRECATION")
         builder.setDeviceCredentialAllowed(true)
       } else {
         builder.setNegativeButtonText(prompt?.cancel ?: DEFAULT_CANCEL)

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

@@ -4,6 +4,13 @@ import androidx.biometric.BiometricManager.Authenticators
 import com.margelo.nitro.sensitiveinfo.AccessControl
 import com.margelo.nitro.sensitiveinfo.SecurityLevel
 
+/**
+ * Determines which Android security primitives should back a requested access control.
+ *
+ * The resolver walks through a preference list, discarding options that are unavailable on the
+ * current device (e.g. no StrongBox, weak biometrics only). The resulting `AccessResolution`
+ * instructs the `CryptoManager` how to create or reopen the matching keystore key.
+ */
 internal class AccessControlResolver(
   private val availabilityResolver: SecurityAvailabilityResolver
 ) {
@@ -15,6 +22,7 @@ internal class AccessControlResolver(
     AccessControl.NONE
   )
 
+  /** Chooses the best available policy given the caller preference and hardware capabilities. */
   fun resolve(preferred: AccessControl?, strongBiometricsOnly: Boolean): AccessResolution {
     val availability = availabilityResolver.resolve()
     val ordered = orderPreferences(preferred)

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

@@ -20,11 +20,20 @@ import javax.crypto.spec.GCMParameterSpec
 private const val ANDROID_KEY_STORE = "AndroidKeyStore"
 private const val TRANSFORMATION = "AES/GCM/NoPadding"
 
+/**
+ * Handles Android Keystore interactions (AES/GCM keys, biometric gating, alias cleanup).
+ *
+ * Callers supply an alias and the resolved `AccessResolution` (which captures whether StrongBox,
+ * biometrics, or device credentials are required). The manager takes care of provisioning keys,
+ * invoking the biometric prompt, and transparently rebuilding the resolution for entries fetched
+ * from disk.
+ */
 internal class CryptoManager(
   private val authenticator: BiometricAuthenticator
 ) {
   private val keyStore: KeyStore = KeyStore.getInstance(ANDROID_KEY_STORE).apply { load(null) }
 
+  /** Encrypts data and returns the ciphertext plus generated IV. */
   suspend fun encrypt(
     alias: String,
     plaintext: ByteArray,
@@ -51,6 +60,7 @@ internal class CryptoManager(
     return EncryptionResult(ciphertext = ciphertext, iv = readyCipher.iv)
   }
 
+  /** Decrypts an item using the preconfigured alias, IV, and policy. */
   suspend fun decrypt(
     alias: String,
     ciphertext: ByteArray,
@@ -81,6 +91,7 @@ internal class CryptoManager(
     return readyCipher.doFinal(ciphertext)
   }
 
+  /** Best-effort removal of a keystore entry. */
   fun deleteKey(alias: String) {
     try {
       keyStore.deleteEntry(alias)
@@ -89,6 +100,12 @@ internal class CryptoManager(
     }
   }
 
+  /**
+   * Reconstructs the resolution for data loaded from SharedPreferences.
+   *
+   * This lets us decrypt entries that were encrypted on a previous run without re-reading
+   * the original access-control input, since the persisted metadata is authoritative.
+   */
   fun buildResolutionForPersisted(
     accessControl: AccessControl,
     securityLevel: SecurityLevel,
@@ -155,6 +172,7 @@ internal class CryptoManager(
       builder.setUserAuthenticationParameters(0, sanitized)
     } else {
       builder.setUserAuthenticationRequired(true)
+      @Suppress("DEPRECATION")
       builder.setUserAuthenticationValidityDurationSeconds(1)
     }
 

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

@@ -16,6 +16,13 @@ internal data class SecurityAvailabilitySnapshot(
   val deviceCredential: Boolean
 )
 
+/**
+ * Caches hardware capability checks (StrongBox, biometrics, device credential).
+ *
+ * The Android system calls here can be relatively expensive, so we memoize the result until the
+ * process restarts. JS can always request a fresh snapshot by calling
+ * `getSupportedSecurityLevels()`.
+ */
 internal class SecurityAvailabilityResolver(private val context: Context) {
   private val lock = ReentrantLock()
   private var cached: SecurityAvailabilitySnapshot? = null

android/src/main/java/com/sensitiveinfo/internal/storage/PersistedEntry.kt

@@ -3,6 +3,12 @@ package com.sensitiveinfo.internal.storage
 import org.json.JSONObject
 import android.util.Base64
 
+/**
+ * Serialized representation of an entry in SharedPreferences.
+ *
+ * `ciphertext` and `iv` remain optional so callers can cache metadata-only items (for example
+ * when a secret is hardware-gated and the user has not authenticated yet).
+ */
 internal data class PersistedEntry(
   val alias: String,
   val ciphertext: ByteArray?,

android/src/main/java/com/sensitiveinfo/internal/storage/PersistedMetadata.kt

@@ -9,6 +9,7 @@ import com.sensitiveinfo.internal.util.persistedName
 import com.sensitiveinfo.internal.util.securityLevelFromPersisted
 import com.sensitiveinfo.internal.util.storageBackendFromPersisted
 
+/** Mirrors the TypeScript `StorageMetadata` shape so we can round-trip metadata through JSON. */
 internal data class PersistedMetadata(
   val securityLevel: String,
   val backend: String,

android/src/main/java/com/sensitiveinfo/internal/storage/SecureStorage.kt

@@ -4,6 +4,10 @@ import android.content.Context
 import android.content.SharedPreferences
 import com.sensitiveinfo.internal.util.ServiceNameResolver
 
+/**
+ * Thin SharedPreferences wrapper. The real secret is stored in the Keystore; this component keeps
+ * the encrypted payload, IV, and metadata JSON on disk so we can enumerate entries cheaply.
+ */
 internal class SecureStorage(context: Context) {
   private val resolver = ServiceNameResolver(context)
   private val applicationContext = context.applicationContext

android/src/main/java/com/sensitiveinfo/internal/util/AliasGenerator.kt

@@ -3,6 +3,13 @@ package com.sensitiveinfo.internal.util
 import java.security.MessageDigest
 import java.util.Locale
 
+/**
+ * Produces deterministic Android Keystore alias names.
+ *
+ * Aliases follow the pattern `SensitiveInfo_v1_<serviceHash>_<policySignature>` so rotating
+ * security policies for a service results in new keys while keeping the old ones around for
+ * existing entries. The service hash keeps names short and filesystem safe.
+ */
 internal object AliasGenerator {
   private const val PREFIX = "SensitiveInfo_v1"
 
@@ -11,6 +18,6 @@ internal object AliasGenerator {
     val hash = digest.take(8).joinToString(separator = "") { byte ->
       String.format(Locale.US, "%02x", byte)
     }
-    return "$PREFIX_$hash_${accessSignature.lowercase(Locale.US)}"
+    return "${PREFIX}_${hash}_${accessSignature.lowercase(Locale.US)}"
   }
 }

android/src/main/java/com/sensitiveinfo/internal/util/EnumInterop.kt

@@ -4,6 +4,7 @@ import com.margelo.nitro.sensitiveinfo.AccessControl
 import com.margelo.nitro.sensitiveinfo.SecurityLevel
 import com.margelo.nitro.sensitiveinfo.StorageBackend
 
+/** Ensures enums round-trip between Kotlin and the generated TypeScript string literal unions. */
 internal fun AccessControl.persistedName(): String = when (this) {
   AccessControl.SECUREENCLAVEBIOMETRY -> "secureEnclaveBiometry"
   AccessControl.BIOMETRYCURRENTSET -> "biometryCurrentSet"