react-native-dpop 0.3.0 → 1.0.0

package/README.md

@@ -4,18 +4,19 @@ React Native library for DPoP proof generation and key management.
 
 ## Features
 
-- Generate DPoP proofs (`dpop+jwt`) signed with ES256.
-- Manage key pairs in the device keystore (create, rotate, delete).
-- Export public key in `JWK`, `DER`, or `RAW` format.
-- Calculate JWK thumbprint (`SHA-256`, base64url).
-- Verify if a proof is bound to a given key alias.
-- Retrieve non-sensitive key metadata (hardware-backed, StrongBox info, etc.).
-- iOS key storage uses Secure Enclave when available, with Keychain fallback.
+- Generate DPoP proofs (`dpop+jwt`) signed with ES256
+- Manage key pairs in the platform keystore
+- Export the public key as `JWK`, `DER`, or `RAW`
+- Calculate JWK thumbprints (`SHA-256`, base64url)
+- Verify whether a proof is bound to a given key alias
+- Retrieve non-sensitive key metadata, including secure hardware details
+- Use Secure Enclave on iOS when available, with Keychain fallback
+- Prefer StrongBox on Android when available, with hardware-backed fallback
 
-## Platform Support
+## Platform support
 
-- Android: supported.
-- iOS: supported.
+- Android
+- iOS
 
 ## Installation
 
@@ -23,66 +24,172 @@ React Native library for DPoP proof generation and key management.
 npm install react-native-dpop
 ```
 
-For iOS, install pods in your app project:
+For iOS:
 
 ```sh
 cd ios && pod install
 ```
 
-## Quick Start
+## Quick start
 
 ```ts
 import { DPoP } from 'react-native-dpop';
 
-const dpop = await DPoP.generateProof({
+const dPoP = await DPoP.generateProof({
   htu: 'https://api.example.com/token',
   htm: 'POST',
   accessToken: 'ACCESS_TOKEN',
-  nonce: 'server-nonce',
+  nonce: 'SERVER_NONCE',
+  requireHardwareBacked: true,
 });
 
-const proof = dpop.proof;
-const thumbprint = await dpop.calculateThumbprint();
-const publicJwk = await dpop.getPublicKey('JWK');
-const isBound = await dpop.isBoundToAlias();
+const proof = dPoP.proof;
+const thumbprint = await dPoP.getPublicKeyThumbprint();
+const publicJwk = await dPoP.getPublicKey('JWK');
+const keyInfo = await DPoP.getKeyInfo();
 ```
 
 ## API
 
-### Types
-
-- `GenerateProofInput`
-- `DPoPProofContext`
-- `DPoPKeyInfo`
-- `SecureHardwareFallbackReason = 'UNAVAILABLE' | 'PROVIDER_ERROR' | 'POLICY_REJECTED' | 'UNKNOWN'`
-- `PublicJwk`
-- `PublicKeyFormat = 'JWK' | 'DER' | 'RAW'`
-
-### `DPoP` static methods
+### Static methods
 
 - `DPoP.generateProof(input): Promise<DPoP>`
+- `DPoP.buildDPoPHeaders(input): Promise<DPoPHeaders>`
 - `DPoP.assertHardwareBacked(alias?): Promise<void>`
 - `DPoP.deleteKeyPair(alias?): Promise<void>`
 - `DPoP.getKeyInfo(alias?): Promise<DPoPKeyInfo>`
 - `DPoP.hasKeyPair(alias?): Promise<boolean>`
 - `DPoP.rotateKeyPair(alias?): Promise<void>`
 
-### `DPoP` instance fields
+### Instance members
 
 - `proof: string`
 - `proofContext: DPoPProofContext`
 - `alias?: string`
-
-### `DPoP` instance methods
-
-- `calculateThumbprint(): Promise<string>`
 - `getPublicKey(format): Promise<PublicJwk | string>`
-- `signWithDpopPrivateKey(payload): Promise<string>`
+- `getPublicKeyThumbprint(): Promise<string>`
+- `signWithDPoPPrivateKey(payload): Promise<string>`
 - `isBoundToAlias(alias?): Promise<boolean>`
 
-## Error Codes
+### `signWithDPoPPrivateKey()`
+
+`signWithDPoPPrivateKey()` reuses the same private key pair managed by the DPoP alias. It does not create or use a separate signing key.
+
+This means:
+
+- the signature is produced with the same key material used for DPoP proofs
+- the active alias determines which private key is used
+- if the alias points to a hardware-backed key, the same hardware-backed key is reused
+- if the alias points to a fallback software-backed key, the same fallback key is reused
+
+Recommended usage:
+
+- use this only when you intentionally want to sign arbitrary payloads with the same DPoP key
+- avoid treating it as a general-purpose application signing API
+- if you need a different trust boundary or lifecycle, use a different alias or a different key management flow
+
+### Main types
+
+- `GenerateProofInput`
+- `DPoPHeaders`
+- `DPoPProofContext`
+- `DPoPKeyInfo`
+- `PublicJwk`
+- `PublicKeyFormat = 'JWK' | 'DER' | 'RAW'`
+- `SecureHardwareFallbackReason = 'UNAVAILABLE' | 'PROVIDER_ERROR' | 'POLICY_REJECTED' | 'UNKNOWN'`
+- `AndroidSecurityLevelName = 'SOFTWARE' | 'TRUSTED_ENVIRONMENT' | 'STRONGBOX'`
+- `IOSSecurityLevelName = 'SOFTWARE' | 'SECURE_ENCLAVE'`
+
+## `getKeyInfo()`
+
+`getKeyInfo()` returns shared fields plus platform-specific hardware metadata.
+
+```ts
+type DPoPKeyInfo = {
+  alias: string;
+  hasKeyPair: boolean;
+  algorithm?: string;
+  curve?: string;
+  insideSecureHardware?: boolean;
+  hardware?: {
+    android?: {
+      strongBoxAvailable: boolean;
+      strongBoxBacked: boolean;
+      securityLevel?: number;
+      securityLevelName?: 'SOFTWARE' | 'TRUSTED_ENVIRONMENT' | 'STRONGBOX';
+      strongBoxFallbackReason?: 'UNAVAILABLE' | 'PROVIDER_ERROR' | 'POLICY_REJECTED' | 'UNKNOWN' | null;
+    };
+    ios?: {
+      secureEnclaveAvailable: boolean;
+      secureEnclaveBacked: boolean;
+      securityLevel?: number | null;
+      securityLevelName?: 'SOFTWARE' | 'SECURE_ENCLAVE';
+      secureEnclaveFallbackReason?: 'UNAVAILABLE' | 'PROVIDER_ERROR' | 'POLICY_REJECTED' | 'UNKNOWN' | null;
+    };
+  };
+};
+```
+
+### Security level semantics
+
+- `securityLevel = 1`
+  Software-backed key material
+- `securityLevel = 2`
+  Hardware-backed key material
+  On Android this usually means TEE
+  On iOS this means Secure Enclave
+- `securityLevel = 3`
+  Android StrongBox-backed key
+- `securityLevel = null`
+  No key material available, or the native platform did not report a numeric level
+
+### Fallback semantics
+
+- On Android, the library tries StrongBox first when available
+- On iOS, the library tries Secure Enclave first when available
+- Fallback reasons are sanitized enums rather than raw native errors
+- On iOS Simulator, `secureEnclaveFallbackReason` is expected to be `UNAVAILABLE`
+
+## `buildDPoPHeaders()`
+
+`buildDPoPHeaders()` generates a proof and returns request headers ready to use.
 
-Native errors are rejected with codes such as:
+```ts
+const headers = await DPoP.buildDPoPHeaders({
+  htu: 'https://api.example.com/token',
+  htm: 'POST',
+  accessToken: 'ACCESS_TOKEN',
+});
+
+// {
+//   DPoP: '<proof>',
+//   Authorization: 'DPoP ACCESS_TOKEN',
+// }
+```
+
+If `accessToken` is omitted, only the `DPoP` header is returned.
+
+## Notes
+
+- Default alias: `react-native-dpop`
+- `htm` is normalized to uppercase
+- `ath` is derived from `accessToken` when provided
+- `jti` and `iat` are auto-generated when omitted
+- `requireHardwareBacked` forces proof generation to fail instead of silently persisting a software-backed fallback key
+- For React Native 0.75 on Android, the library ensures `iat` is sent as a number to avoid an older bridge nullability issue with `Double`
+
+## Example apps
+
+This repository includes two example apps:
+
+- `examples/v0.75`
+- `examples/v0.83`
+
+The root `example` script points to `examples/v0.83`.
+
+## Errors
+
+Native rejections use codes such as:
 
 - `ERR_DPOP_GENERATE_PROOF`
 - `ERR_DPOP_CALCULATE_THUMBPRINT`
@@ -95,23 +202,6 @@ Native errors are rejected with codes such as:
 - `ERR_DPOP_ASSERT_HARDWARE_BACKED`
 - `ERR_DPOP_IS_BOUND_TO_ALIAS`
 
-## Notes
-
-- If no alias is provided, the default alias is `react-native-dpop`.
-- `getKeyInfo` returns cross-platform fields and platform-specific details in `hardware`:
-  - Android: `hardware.android.strongBoxAvailable`, `hardware.android.strongBoxBacked`, `hardware.android.securityLevel`, `hardware.android.strongBoxFallbackReason`
-  - iOS: `hardware.ios.secureEnclaveAvailable`, `hardware.ios.secureEnclaveBacked`, `hardware.ios.securityLevel`, `hardware.ios.secureEnclaveFallbackReason`
-- Fallback reasons are sanitized enums (no raw native error): `UNAVAILABLE`, `PROVIDER_ERROR`, `POLICY_REJECTED`, `UNKNOWN`.
-- `securityLevel` semantics:
-  - `null`: no key material available (or not reported)
-  - `1`: not backed by secure enclave/strong dedicated hardware
-  - `2`: hardware-backed (iOS Secure Enclave, Android typically TEE)
-  - `3`: Android-only StrongBox (when reported by the device)
-- On iOS, `securityLevel` is normalized by this library (`2` for Secure Enclave-backed keys, `1` for Keychain fallback), not a native Apple numeric level API.
-- `htm` is normalized to uppercase in proof generation.
-- `ath` is derived from `accessToken` (`SHA-256`, base64url) when provided.
-- `jti` and `iat` are auto-generated when omitted.
-
 ## Contributing
 
 - [Development workflow](CONTRIBUTING.md#development-workflow)

package/ReactNativeDPoP.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  s.platforms    = { :ios => min_ios_version_supported }
+  s.platforms    = { :ios => "14.0" }
   s.source       = { :git => "https://github.com/Cirilord/react-native-dpop.git", :tag => "#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"

package/android/src/main/java/com/reactnativedpop/DPoPKeyStore.kt

@@ -28,6 +28,7 @@ internal data class KeyStoreKeyInfo(
   val curve: String,
   val insideSecureHardware: Boolean,
   val securityLevel: Int?,
+  val securityLevelName: String,
   val strongBoxAvailable: Boolean,
   val strongBoxBacked: Boolean
 )
@@ -112,6 +113,8 @@ internal class DPoPKeyStore(private val context: Context) {
     val keyPair = getKeyPair(alias)
     val keyFactory = KeyFactory.getInstance(keyPair.privateKey.algorithm, KEYSTORE_PROVIDER)
     val keyInfo = keyFactory.getKeySpec(keyPair.privateKey, KeyInfo::class.java)
+    val strongBoxAvailable = isStrongBoxEnabled()
+    val strongBoxBacked = strongBoxAvailable && readStrongBoxBacked(keyInfo)
 
     return KeyStoreKeyInfo(
       alias = alias,
@@ -119,8 +122,9 @@ internal class DPoPKeyStore(private val context: Context) {
       curve = "P-256",
       insideSecureHardware = keyInfo.isInsideSecureHardware,
       securityLevel = readSecurityLevel(keyInfo),
-      strongBoxAvailable = isStrongBoxEnabled(),
-      strongBoxBacked = readStrongBoxBacked(keyInfo)
+      securityLevelName = readSecurityLevelName(keyInfo, strongBoxBacked),
+      strongBoxAvailable = strongBoxAvailable,
+      strongBoxBacked = strongBoxBacked
     )
   }
 
@@ -172,6 +176,23 @@ internal class DPoPKeyStore(private val context: Context) {
     }
   }
 
+  private fun readSecurityLevelName(keyInfo: KeyInfo, strongBoxBacked: Boolean): String {
+    val securityLevel = readSecurityLevel(keyInfo)
+
+    return when (securityLevel) {
+      1 -> "SOFTWARE"
+      2 -> "TRUSTED_ENVIRONMENT"
+      3 -> "STRONGBOX"
+      else -> {
+        when {
+          strongBoxBacked -> "STRONGBOX"
+          keyInfo.isInsideSecureHardware -> "TRUSTED_ENVIRONMENT"
+          else -> "SOFTWARE"
+        }
+      }
+    }
+  }
+
   private fun readStrongBoxBacked(keyInfo: KeyInfo): Boolean {
     if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) {
       return false

package/android/src/main/java/com/reactnativedpop/DPoPModule.kt

@@ -12,10 +12,49 @@ class DPoPModule(reactContext: ReactApplicationContext) :
   NativeReactNativeDPoPSpec(reactContext) {
   private val keyStore = DPoPKeyStore(reactContext)
 
+  companion object {
+    private const val DEFAULT_ALIAS = "react-native-dpop"
+    const val NAME = NativeReactNativeDPoPSpec.NAME
+    private const val UNKNOWN_STRONGBOX_FALLBACK_REASON = "UNKNOWN"
+    private val RESERVED_DPOP_CLAIMS = setOf("ath", "htm", "htu", "iat", "jti", "nonce")
+  }
+
   private fun resolveAlias(alias: String?): String {
     return alias ?: DEFAULT_ALIAS
   }
 
+  private fun ensureKeyPair(alias: String, requireHardwareBacked: Boolean): Unit {
+    var generatedInThisCall = false
+
+    if (!keyStore.hasKeyPair(alias)) {
+      keyStore.generateKeyPair(alias)
+      generatedInThisCall = true
+    }
+
+    if (requireHardwareBacked && !keyStore.isHardwareBacked(alias)) {
+      if (generatedInThisCall) {
+        keyStore.deleteKeyPair(alias)
+      }
+      throw IllegalStateException("Hardware-backed key required for alias: $alias")
+    }
+  }
+
+  private fun resolveStrongBoxFallbackReason(
+    strongBoxAvailable: Boolean,
+    strongBoxBacked: Boolean,
+    fallbackReason: String?
+  ): String? {
+    if (fallbackReason != null) {
+      return fallbackReason
+    }
+
+    return if (strongBoxAvailable && !strongBoxBacked) {
+      UNKNOWN_STRONGBOX_FALLBACK_REASON
+    } else {
+      null
+    }
+  }
+
   override fun assertHardwareBacked(alias: String?, promise: Promise) {
     try {
       val effectiveAlias = resolveAlias(alias)
@@ -35,27 +74,6 @@ class DPoPModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun calculateThumbprint(alias: String?, promise: Promise) {
-    try {
-      val effectiveAlias = resolveAlias(alias)
-      if (!keyStore.hasKeyPair(effectiveAlias)) {
-        keyStore.generateKeyPair(effectiveAlias)
-      }
-
-      val keyPair = keyStore.getKeyPair(effectiveAlias)
-      val coordinates = DPoPUtils.getPublicCoordinates(keyPair.publicKey)
-      val thumbprint = DPoPUtils.calculateThumbprint(
-        kty = "EC",
-        crv = "P-256",
-        x = coordinates.first,
-        y = coordinates.second
-      )
-      promise.resolve(thumbprint)
-    } catch (e: Exception) {
-      promise.reject("ERR_DPOP_CALCULATE_THUMBPRINT", e.message, e)
-    }
-  }
-
   override fun deleteKeyPair(alias: String?, promise: Promise) {
     try {
       val effectiveAlias = resolveAlias(alias)
@@ -70,9 +88,14 @@ class DPoPModule(reactContext: ReactApplicationContext) :
     try {
       val effectiveAlias = resolveAlias(alias)
       if (!keyStore.hasKeyPair(effectiveAlias)) {
-        val fallbackReason = keyStore.getStrongBoxFallbackReason(effectiveAlias)
+        val strongBoxAvailable = keyStore.isStrongBoxAvailable()
+        val fallbackReason = resolveStrongBoxFallbackReason(
+          strongBoxAvailable = strongBoxAvailable,
+          strongBoxBacked = false,
+          fallbackReason = keyStore.getStrongBoxFallbackReason(effectiveAlias)
+        )
         val hardwareAndroid = Arguments.createMap().apply {
-          putBoolean("strongBoxAvailable", keyStore.isStrongBoxAvailable())
+          putBoolean("strongBoxAvailable", strongBoxAvailable)
           putBoolean("strongBoxBacked", false)
           if (fallbackReason != null) {
             putString("strongBoxFallbackReason", fallbackReason)
@@ -93,13 +116,18 @@ class DPoPModule(reactContext: ReactApplicationContext) :
       }
 
       val keyInfo = keyStore.getKeyInfo(effectiveAlias)
-      val fallbackReason = keyStore.getStrongBoxFallbackReason(effectiveAlias)
+      val fallbackReason = resolveStrongBoxFallbackReason(
+        strongBoxAvailable = keyInfo.strongBoxAvailable,
+        strongBoxBacked = keyInfo.strongBoxBacked,
+        fallbackReason = keyStore.getStrongBoxFallbackReason(effectiveAlias)
+      )
       val hardwareAndroid = Arguments.createMap().apply {
         putBoolean("strongBoxAvailable", keyInfo.strongBoxAvailable)
         putBoolean("strongBoxBacked", keyInfo.strongBoxBacked)
         if (keyInfo.securityLevel != null) {
           putInt("securityLevel", keyInfo.securityLevel)
         }
+        putString("securityLevelName", keyInfo.securityLevelName)
         if (fallbackReason != null) {
           putString("strongBoxFallbackReason", fallbackReason)
         } else {
@@ -173,6 +201,27 @@ class DPoPModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  override fun getPublicKeyThumbprint(alias: String?, promise: Promise) {
+    try {
+      val effectiveAlias = resolveAlias(alias)
+      if (!keyStore.hasKeyPair(effectiveAlias)) {
+        keyStore.generateKeyPair(effectiveAlias)
+      }
+
+      val keyPair = keyStore.getKeyPair(effectiveAlias)
+      val coordinates = DPoPUtils.getPublicCoordinates(keyPair.publicKey)
+      val thumbprint = DPoPUtils.getPublicKeyThumbprint(
+        kty = "EC",
+        crv = "P-256",
+        x = coordinates.first,
+        y = coordinates.second
+      )
+      promise.resolve(thumbprint)
+    } catch (e: Exception) {
+      promise.reject("ERR_DPOP_CALCULATE_THUMBPRINT", e.message, e)
+    }
+  }
+
   override fun hasKeyPair(alias: String?, promise: Promise) {
     try {
       val effectiveAlias = resolveAlias(alias)
@@ -206,7 +255,7 @@ class DPoPModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun signWithDpopPrivateKey(payload: String, alias: String?, promise: Promise) {
+  override fun signWithDPoPPrivateKey(payload: String, alias: String?, promise: Promise) {
     try {
       val effectiveAlias = resolveAlias(alias)
       if (!keyStore.hasKeyPair(effectiveAlias)) {
@@ -235,13 +284,12 @@ class DPoPModule(reactContext: ReactApplicationContext) :
     jti: String?,
     iat: Double?,
     alias: String?,
+    requireHardwareBacked: Boolean,
     promise: Promise
   ) {
     try {
       val effectiveAlias = resolveAlias(alias)
-      if (!keyStore.hasKeyPair(effectiveAlias)) {
-        keyStore.generateKeyPair(effectiveAlias)
-      }
+      ensureKeyPair(effectiveAlias, requireHardwareBacked)
 
       val keyPair = keyStore.getKeyPair(effectiveAlias)
       val coordinates = DPoPUtils.getPublicCoordinates(keyPair.publicKey)
@@ -281,6 +329,9 @@ class DPoPModule(reactContext: ReactApplicationContext) :
         val keys = additionalJson.keys()
         while (keys.hasNext()) {
           val key = keys.next()
+          if (RESERVED_DPOP_CLAIMS.contains(key)) {
+            throw IllegalArgumentException("additional must not override reserved DPoP claim: $key")
+          }
           payload.put(key, additionalJson.get(key))
         }
       }
@@ -320,9 +371,4 @@ class DPoPModule(reactContext: ReactApplicationContext) :
       promise.reject("ERR_DPOP_GENERATE_PROOF", e.message, e)
     }
   }
-
-  companion object {
-    private const val DEFAULT_ALIAS = "react-native-dpop"
-    const val NAME = NativeReactNativeDPoPSpec.NAME
-  }
 }

package/android/src/main/java/com/reactnativedpop/DPoPPackage.kt

@@ -5,7 +5,6 @@ import com.facebook.react.bridge.NativeModule
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.module.model.ReactModuleInfo
 import com.facebook.react.module.model.ReactModuleInfoProvider
-import java.util.HashMap
 
 class DPoPPackage : BaseReactPackage() {
   override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
@@ -19,12 +18,13 @@ class DPoPPackage : BaseReactPackage() {
   override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
     mapOf(
       DPoPModule.NAME to ReactModuleInfo(
-        name = DPoPModule.NAME,
-        className = DPoPModule.NAME,
-        canOverrideExistingModule = false,
-        needsEagerInit = false,
-        isCxxModule = false,
-        isTurboModule = true
+        DPoPModule.NAME,
+        DPoPModule::class.java.name,
+        false,
+        false,
+        false,
+        false,
+        true
       )
     )
   }

package/android/src/main/java/com/reactnativedpop/DPoPUtils.kt

@@ -18,12 +18,6 @@ internal object DPoPUtils {
     return Base64.getUrlEncoder().withoutPadding().encodeToString(input)
   }
 
-  internal fun calculateThumbprint(kty: String, crv: String, x: String, y: String): String {
-    val canonicalJwk = """{"crv":"$crv","kty":"$kty","x":"$x","y":"$y"}"""
-    val hash = MessageDigest.getInstance("SHA-256").digest(canonicalJwk.toByteArray(Charsets.UTF_8))
-    return base64UrlEncode(hash)
-  }
-
   internal fun derToJose(derSignature: ByteArray, partLength: Int = 32): ByteArray {
     if (derSignature.isEmpty() || derSignature[0].toInt() != 0x30) {
       throw IllegalArgumentException("Invalid DER signature format")
@@ -65,6 +59,12 @@ internal object DPoPUtils {
     return Pair(x, y)
   }
 
+  internal fun getPublicKeyThumbprint(kty: String, crv: String, x: String, y: String): String {
+    val canonicalJwk = """{"crv":"$crv","kty":"$kty","x":"$x","y":"$y"}"""
+    val hash = MessageDigest.getInstance("SHA-256").digest(canonicalJwk.toByteArray(Charsets.UTF_8))
+    return base64UrlEncode(hash)
+  }
+
   internal fun hashAccessToken(accessToken: String): String {
     val hash = MessageDigest.getInstance("SHA-256").digest(accessToken.toByteArray(Charsets.UTF_8))
     return base64UrlEncode(hash)

package/ios/DPoPKeyStore.swift

@@ -19,6 +19,7 @@ final class DPoPKeyStore {
   private let keychain = KeychainKeyStore()
   private let fallbackReasonDefaults = UserDefaults.standard
   private let fallbackReasonPrefix = "react_native_dpop_secure_enclave_fallback_reason_"
+  private let unavailableFallbackReason = "UNAVAILABLE"
   private lazy var secureEnclaveAvailable = secureEnclave.isAvailable()
 
   func generateKeyPair(alias: String) throws {
@@ -92,7 +93,7 @@ final class DPoPKeyStore {
   }
 
   func isHardwareBacked(alias: String) -> Bool {
-    secureEnclave.isHardwareBacked(alias: alias)
+    secureEnclaveAvailable && secureEnclave.isHardwareBacked(alias: alias)
   }
 
   func isSecureEnclaveAvailable() -> Bool {
@@ -100,7 +101,15 @@ final class DPoPKeyStore {
   }
 
   func getSecureEnclaveFallbackReason(alias: String) -> String? {
-    fallbackReasonDefaults.string(forKey: fallbackReasonKey(alias: alias))
+    if !secureEnclaveAvailable && keychain.hasKeyPair(alias: alias) {
+      return unavailableFallbackReason
+    }
+
+    if let storedReason = fallbackReasonDefaults.string(forKey: fallbackReasonKey(alias: alias)) {
+      return storedReason
+    }
+
+    return nil
   }
 
   private func storeSecureEnclaveFallbackReason(alias: String, reason: String) {