feat: implement integrity hardening for sensitive data storage

- Added HMAC-SHA256 integrity tags to entries, enhancing tamper detection.
- Introduced AES-GCM AAD for additional security against cross-entry attacks.
- Implemented zeroization of plaintext buffers post-use on both platforms.
- Updated error handling to include IntegrityViolationError for tampering cases.
- Enhanced metadata structure to include integrity tags and AAD usage flags.
- Updated tests to verify integrity tag propagation and error handling for integrity violations.

Co-authored-by: Copilot <copilot@github.com>

Author: mCodex

CHANGELOG.md

@@ -3,6 +3,13 @@
 ### Features
 
 * **rotation:** Add versioned key rotation via `rotateKeys()` and `getKeyVersion()` with lazy re-encryption on read. New `useKeyRotation` hook exposes the same flow declaratively.
+* **security hardening:** Defense-in-depth pass — non-breaking, applied transparently to new writes and via lazy upgrade on rotation:
+  - HMAC-SHA256 integrity tag bound to every entry's metadata + ciphertext, surfaced on `StorageMetadata.integrityTag`. Tampering with SharedPreferences/Keychain attributes now raises `IntegrityViolationError` (`E_INTEGRITY_VIOLATION`) before any biometric prompt is shown.
+  - AES-GCM AAD on Android binds ciphertext to `service|key|v<version>`, defeating cross-entry swap attacks.
+  - `setUnlockedDeviceRequired(true)` on every Android Keystore key (API 28+), mirroring iOS's `kSecAttrAccessibleWhenUnlocked` semantics.
+  - Plaintext byte buffers are zeroized after use on both platforms.
+  - Constant-time HMAC comparison via `MessageDigest.isEqual` / manual `UInt8` XOR fold.
+  - Backwards compatible: entries written by earlier versions decode without verification and are upgraded on the next write or rotation.
 * **errors:** New typed error classes (`SensitiveInfoError`, `NotFoundError`, `AuthenticationCanceledError`, `IntegrityViolationError`, `KeyInvalidatedError`, `RotationFailedError`) with `code` discriminants and `instanceof` predicates. Importable from the `react-native-sensitive-info/errors` subpath.
 * **tree-shaking:** `"sideEffects": false` everywhere; the package now publishes three focused subpath entries (`.`, `/hooks`, `/errors`). The default export has been removed — import only the helpers you use.
 * **nitro 0.35:** Regenerated against `nitrogen@0.35.5` and `react-native-nitro-modules@0.35.5`.

README.md

@@ -308,10 +308,15 @@ function RotationButton() {
 | --- | --- | --- |
 | Master key | Android Keystore (`AES/GCM`, StrongBox when available) | Secure Enclave-gated (P-256) + AES-GCM |
 | Authentication | BiometricPrompt (Class 3 preferred), device credential fallback | LAContext / Face ID / Touch ID / Optic ID |
-| At-rest integrity | AES-GCM authentication tag | AES-GCM authentication tag |
+| At-rest integrity | AES-GCM tag **+** HMAC-SHA256 metadata tag (Keystore-bound) | AES-GCM tag **+** HMAC-SHA256 metadata tag (Keychain-stored, after-first-unlock) |
+| Replay / swap defense | AES-GCM AAD bound to `service\|key\|v<version>` | Keychain `kSecAttrService` + `kSecAttrAccount` binding |
+| Device-state gating | `setUnlockedDeviceRequired(true)` on every key (API 28+) | `kSecAttrAccessibleWhenUnlocked*` defaults |
+| Plaintext lifetime | Buffers zeroized after encrypt/decrypt | `Data` buffers zeroized via `memset_s` |
 | Key rotation | Versioned Keystore aliases, lazy re-encryption | Versioned Keychain metadata, lazy re-wrap (preserves original access control) |
 | Error classification | Typed `SensitiveInfoError` subclasses via `/errors` subpath | Same |
 
+> **Tamper detection:** every read recomputes the HMAC over the persisted `(service, key, version, accessControl, securityLevel, timestamp, ciphertext, iv)` tuple. A mismatch raises `IntegrityViolationError` (`E_INTEGRITY_VIOLATION`) **before** any biometric prompt fires, so spoofed entries can never trigger user authentication. Entries written by older library versions (no `integrityTag`) are accepted on first read and upgraded on the next write or rotation.
+
 Typed errors can be imported from the `/errors` subpath for tree-shakeable error handling:
 
 ```tsx

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

@@ -10,14 +10,18 @@ import com.sensitiveinfo.internal.auth.BiometricAuthenticator
 import com.sensitiveinfo.internal.crypto.AccessControlResolver
 import com.sensitiveinfo.internal.crypto.AccessResolution
 import com.sensitiveinfo.internal.crypto.CryptoManager
+import com.sensitiveinfo.internal.crypto.IntegrityInput
+import com.sensitiveinfo.internal.crypto.MetadataIntegrity
 import com.sensitiveinfo.internal.crypto.SecurityAvailabilityResolver
 import com.sensitiveinfo.internal.storage.KeyVersionRegistry
 import com.sensitiveinfo.internal.storage.PersistedEntry
 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.persistedName
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -41,7 +45,8 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
     val accessControlResolver: AccessControlResolver,
     val securityAvailabilityResolver: SecurityAvailabilityResolver,
     val serviceNameResolver: ServiceNameResolver,
-    val keyVersionRegistry: KeyVersionRegistry
+    val keyVersionRegistry: KeyVersionRegistry,
+    val integrity: MetadataIntegrity
   )
 
   @Volatile
@@ -67,7 +72,8 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
           accessControlResolver = accessControlResolver,
           securityAvailabilityResolver = securityAvailabilityResolver,
           serviceNameResolver = serviceNameResolver,
-          keyVersionRegistry = KeyVersionRegistry(ctx)
+          keyVersionRegistry = KeyVersionRegistry(ctx),
+          integrity = MetadataIntegrity()
         ).also { built ->
           dependencies = built
         }
@@ -84,10 +90,26 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
       val alias = AliasGenerator.aliasFor(service, request.key, version)
 
       val plaintext = request.value.toByteArray(Charsets.UTF_8)
-      val encryption = deps.cryptoManager.encrypt(alias, plaintext, resolved, request.authenticationPrompt)
+      val aad = aadFor(service, request.key, version)
+      val encryption = deps.cryptoManager.encrypt(
+        alias, plaintext, resolved, request.authenticationPrompt, aad
+      )
 
-      val metadata = buildMetadata(resolved.securityLevel, resolved.accessControl, version)
-      val entry = buildEntry(alias, encryption.ciphertext, encryption.iv, metadata, resolved, version)
+      val timestamp = System.currentTimeMillis() / 1000.0
+      val tag = deps.integrity.sign(
+        integrityInputFor(
+          service, request.key, version,
+          resolved.accessControl, resolved.securityLevel,
+          timestamp, encryption.iv, encryption.ciphertext
+        )
+      )
+      val metadata = buildMetadata(
+        resolved.securityLevel, resolved.accessControl, version, timestamp, tag
+      )
+      val entry = buildEntry(
+        alias, encryption.ciphertext, encryption.iv, metadata, resolved, version,
+        usesAad = true, integrityTag = tag
+      )
 
       deps.storage.save(service, request.key, entry)
 
@@ -104,7 +126,7 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
         ?: return@async emptyItem(request.key, service)
 
       val includeValue = request.includeValue == true
-      val decrypted = if (includeValue) decryptEntry(deps, entry, request.authenticationPrompt) else null
+      val decrypted = if (includeValue) decryptEntry(deps, entry, request.authenticationPrompt, service, request.key) else null
       val upgraded = if (includeValue && decrypted != null) {
         maybeReEncrypt(deps, service, request.key, entry, decrypted, request.authenticationPrompt)
       } else {
@@ -155,7 +177,7 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
       entries.mapNotNull { (key, entry) ->
         try {
           val value = if (includeValues) {
-            runCatching { decryptEntry(deps, entry, request?.authenticationPrompt) }.getOrNull()
+            runCatching { decryptEntry(deps, entry, request?.authenticationPrompt, service, key) }.getOrNull()
           } else {
             null
           }
@@ -240,36 +262,66 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
   private fun buildMetadata(
     securityLevel: SecurityLevel,
     accessControl: AccessControl,
-    keyVersion: Int
+    keyVersion: Int,
+    timestamp: Double = System.currentTimeMillis() / 1000.0,
+    integrityTag: String? = null
   ): StorageMetadata = StorageMetadata(
     securityLevel = securityLevel,
     backend = StorageBackend.ANDROIDKEYSTORE,
     accessControl = accessControl,
-    timestamp = System.currentTimeMillis() / 1000.0,
+    timestamp = timestamp,
     keyVersion = keyVersion.toDouble(),
-    integrityTag = null
+    integrityTag = integrityTag
   )
 
   private fun fallbackMetadata(keyVersion: Int = KeyVersionRegistry.INITIAL_VERSION): StorageMetadata =
     buildMetadata(SecurityLevel.SOFTWARE, AccessControl.NONE, keyVersion)
 
+  private fun aadFor(service: String, key: String, version: Int): ByteArray =
+    "$service|$key|v$version".toByteArray(Charsets.UTF_8)
+
+  /** Single source of truth for HMAC integrity inputs. */
+  private fun integrityInputFor(
+    service: String,
+    key: String,
+    version: Int,
+    accessControl: AccessControl,
+    securityLevel: SecurityLevel,
+    timestamp: Double,
+    iv: ByteArray,
+    ciphertext: ByteArray
+  ): IntegrityInput = IntegrityInput(
+    service = service,
+    key = key,
+    keyVersion = version,
+    accessControl = accessControl.persistedName(),
+    securityLevel = securityLevel.persistedName(),
+    timestamp = timestamp,
+    iv = iv,
+    ciphertext = ciphertext
+  )
+
   private fun buildEntry(
     alias: String,
     ciphertext: ByteArray,
     iv: ByteArray,
     metadata: StorageMetadata,
     resolved: AccessResolution,
-    keyVersion: Int
+    keyVersion: Int,
+    usesAad: Boolean = false,
+    integrityTag: String? = null
   ): PersistedEntry = PersistedEntry(
     alias = alias,
     ciphertext = ciphertext,
     iv = iv,
-    metadata = PersistedMetadata.from(metadata),
+    metadata = PersistedMetadata.from(metadata, integrityTag),
     authenticators = resolved.allowedAuthenticators,
     requiresAuthentication = resolved.requiresAuthentication,
     invalidateOnEnrollment = resolved.invalidateOnEnrollment,
     useStrongBox = resolved.useStrongBox,
-    keyVersion = keyVersion
+    keyVersion = keyVersion,
+    usesAad = usesAad,
+    integrityTag = integrityTag
   )
 
   private fun emptyItem(key: String, service: String): Variant_NullType_SensitiveInfoItem {
@@ -292,7 +344,9 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
   private suspend fun decryptEntry(
     deps: Dependencies,
     entry: PersistedEntry,
-    prompt: AuthenticationPrompt?
+    prompt: AuthenticationPrompt?,
+    service: String,
+    key: String
   ): String? {
     if (entry.ciphertext == null || entry.iv == null) return null
     val metadata = entry.metadata.toStorageMetadata()
@@ -304,8 +358,33 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
       invalidateOnEnrollment = entry.invalidateOnEnrollment,
       useStrongBox = entry.useStrongBox
     )
-    val plaintext = deps.cryptoManager.decrypt(entry.alias, entry.ciphertext, entry.iv, resolution, prompt)
-    return String(plaintext, Charsets.UTF_8)
+
+    // Verify integrity *before* decrypting so a tampered envelope never reaches AES-GCM and never
+    // triggers a biometric prompt. Legacy entries (integrityTag == null) are accepted and will be
+    // upgraded on next write/rotation.
+    if (entry.integrityTag != null && metadata != null) {
+      val ok = deps.integrity.verify(
+        integrityInputFor(
+          service, key, entry.keyVersion,
+          metadata.accessControl, metadata.securityLevel,
+          metadata.timestamp, entry.iv, entry.ciphertext
+        ),
+        entry.integrityTag
+      )
+      if (!ok) {
+        throw SensitiveInfoException.IntegrityViolation(key, service)
+      }
+    }
+
+    val aad = if (entry.usesAad) aadFor(service, key, entry.keyVersion) else null
+    val plaintext = deps.cryptoManager.decrypt(
+      entry.alias, entry.ciphertext, entry.iv, resolution, prompt, aad
+    )
+    return try {
+      String(plaintext, Charsets.UTF_8)
+    } finally {
+      plaintext.fill(0)
+    }
   }
 
   private suspend fun maybeReEncrypt(
@@ -343,9 +422,25 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
       invalidateOnEnrollment = entry.invalidateOnEnrollment,
       useStrongBox = entry.useStrongBox
     )
-    val encryption = deps.cryptoManager.encrypt(newAlias, plaintext.toByteArray(Charsets.UTF_8), resolved, prompt)
-    val metadata = buildMetadata(resolved.securityLevel, resolved.accessControl, targetVersion)
-    val upgraded = buildEntry(newAlias, encryption.ciphertext, encryption.iv, metadata, resolved, targetVersion)
+    val encryption = deps.cryptoManager.encrypt(
+      newAlias, plaintext.toByteArray(Charsets.UTF_8), resolved, prompt,
+      aadFor(service, key, targetVersion)
+    )
+    val timestamp = System.currentTimeMillis() / 1000.0
+    val tag = deps.integrity.sign(
+      integrityInputFor(
+        service, key, targetVersion,
+        resolved.accessControl, resolved.securityLevel,
+        timestamp, encryption.iv, encryption.ciphertext
+      )
+    )
+    val metadata = buildMetadata(
+      resolved.securityLevel, resolved.accessControl, targetVersion, timestamp, tag
+    )
+    val upgraded = buildEntry(
+      newAlias, encryption.ciphertext, encryption.iv, metadata, resolved, targetVersion,
+      usesAad = true, integrityTag = tag
+    )
     deps.storage.save(service, key, upgraded)
     if (newAlias != entry.alias) {
       deps.cryptoManager.deleteKey(entry.alias)
@@ -362,7 +457,7 @@ class HybridSensitiveInfo : HybridSensitiveInfoSpec() {
     var count = 0
     for ((key, entry) in deps.storage.readAll(service)) {
       if (entry.keyVersion >= targetVersion) continue
-      val plaintext = runCatching { decryptEntry(deps, entry, prompt) }.getOrNull() ?: continue
+      val plaintext = runCatching { decryptEntry(deps, entry, prompt, service, key) }.getOrNull() ?: continue
       runCatching {
         reEncryptEntry(deps, service, key, entry, plaintext, targetVersion, prompt)
         count += 1

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

@@ -39,7 +39,8 @@ internal class CryptoManager(
     alias: String,
     plaintext: ByteArray,
     resolution: AccessResolution,
-    prompt: AuthenticationPrompt?
+    prompt: AuthenticationPrompt?,
+    aad: ByteArray? = null
   ): EncryptionResult {
     val key = getOrCreateKey(alias, resolution)
     val cipher = Cipher.getInstance(TRANSFORMATION)
@@ -74,8 +75,15 @@ internal class CryptoManager(
       throw error
     }
 
-    val ciphertext = readyCipher.doFinal(plaintext)
-    return EncryptionResult(ciphertext = ciphertext, iv = readyCipher.iv)
+    if (aad != null) {
+      readyCipher.updateAAD(aad)
+    }
+    return try {
+      val ciphertext = readyCipher.doFinal(plaintext)
+      EncryptionResult(ciphertext = ciphertext, iv = readyCipher.iv)
+    } finally {
+      plaintext.fill(0)
+    }
   }
 
   /** Decrypts an item using the preconfigured alias, IV, and policy. */
@@ -84,7 +92,8 @@ internal class CryptoManager(
     ciphertext: ByteArray,
     iv: ByteArray,
     resolution: AccessResolution,
-    prompt: AuthenticationPrompt?
+    prompt: AuthenticationPrompt?,
+    aad: ByteArray? = null
   ): ByteArray {
     val key = getOrCreateKey(alias, resolution)
     val cipher = Cipher.getInstance(TRANSFORMATION)
@@ -134,6 +143,9 @@ internal class CryptoManager(
       throw error
     }
 
+    if (aad != null) {
+      readyCipher.updateAAD(aad)
+    }
     return readyCipher.doFinal(ciphertext)
   }
 
@@ -199,6 +211,16 @@ internal class CryptoManager(
       }
     }
 
+    // Defense in depth: require the device to be unlocked at the moment of use, mirroring iOS's
+    // `kSecAttrAccessibleWhenUnlocked` default. Available on API 28+.
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+      try {
+        builder.setUnlockedDeviceRequired(true)
+      } catch (_: Throwable) {
+        // Older OEM forks may reject this on devices without a screen lock. Best-effort.
+      }
+    }
+
     val spec = builder.build()
     keyGenerator.init(spec)
     return try {