react-native-dpop 0.1.0 → 0.3.0

package/README.md

@@ -10,13 +10,12 @@ React Native library for DPoP proof generation and key management.
 - 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.
 
 ## Platform Support
 
 - Android: supported.
-- iOS: planned.
-
-Current implementation throws on non-Android platforms.
+- iOS: supported.
 
 ## Installation
 
@@ -24,6 +23,12 @@ Current implementation throws on non-Android platforms.
 npm install react-native-dpop
 ```
 
+For iOS, install pods in your app project:
+
+```sh
+cd ios && pod install
+```
+
 ## Quick Start
 
 ```ts
@@ -39,6 +44,7 @@ const dpop = await DPoP.generateProof({
 const proof = dpop.proof;
 const thumbprint = await dpop.calculateThumbprint();
 const publicJwk = await dpop.getPublicKey('JWK');
+const isBound = await dpop.isBoundToAlias();
 ```
 
 ## API
@@ -48,6 +54,7 @@ const publicJwk = await dpop.getPublicKey('JWK');
 - `GenerateProofInput`
 - `DPoPProofContext`
 - `DPoPKeyInfo`
+- `SecureHardwareFallbackReason = 'UNAVAILABLE' | 'PROVIDER_ERROR' | 'POLICY_REJECTED' | 'UNKNOWN'`
 - `PublicJwk`
 - `PublicKeyFormat = 'JWK' | 'DER' | 'RAW'`
 
@@ -78,6 +85,7 @@ const publicJwk = await dpop.getPublicKey('JWK');
 Native errors are rejected with codes such as:
 
 - `ERR_DPOP_GENERATE_PROOF`
+- `ERR_DPOP_CALCULATE_THUMBPRINT`
 - `ERR_DPOP_PUBLIC_KEY`
 - `ERR_DPOP_SIGN_WITH_PRIVATE_KEY`
 - `ERR_DPOP_HAS_KEY_PAIR`
@@ -90,6 +98,16 @@ Native errors are rejected with codes such as:
 ## 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.

package/{Dpop.podspec → ReactNativeDPoP.podspec}

@@ -3,7 +3,8 @@ require "json"
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 
 Pod::Spec.new do |s|
-  s.name         = "Dpop"
+  s.name         = "ReactNativeDPoP"
+  s.module_name  = "ReactNativeDPoP"
   s.version      = package["version"]
   s.summary      = package["description"]
   s.homepage     = package["homepage"]
@@ -14,7 +15,10 @@ Pod::Spec.new do |s|
   s.source       = { :git => "https://github.com/Cirilord/react-native-dpop.git", :tag => "#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
-  s.private_header_files = "ios/**/*.h"
 
-  install_modules_dependencies(s)
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
 end

package/android/build.gradle

@@ -1,5 +1,5 @@
 buildscript {
-  ext.Dpop = [
+  ext.ReactNativeDPoP = [
     kotlinVersion: "2.0.21",
     minSdkVersion: 24,
     compileSdkVersion: 36,
@@ -11,7 +11,7 @@ buildscript {
       return rootProject.ext.get(prop)
     }
 
-    return Dpop[prop]
+    return ReactNativeDPoP[prop]
   }
 
   repositories {
@@ -33,7 +33,7 @@ apply plugin: "kotlin-android"
 apply plugin: "com.facebook.react"
 
 android {
-  namespace "com.dpop"
+  namespace "com.reactnativedpop"
 
   compileSdkVersion getExtOrDefault("compileSdkVersion")
 

package/android/src/main/java/com/{dpop → reactnativedpop}/DPoPKeyStore.kt

@@ -1,4 +1,4 @@
-package com.dpop
+package com.reactnativedpop
 
 import android.content.Context
 import android.content.pm.PackageManager
@@ -36,6 +36,14 @@ internal class DPoPKeyStore(private val context: Context) {
   companion object {
     private const val KEYSTORE_PROVIDER = "AndroidKeyStore"
     private const val EC_CURVE = "secp256r1"
+    private const val META_PREFS = "react_native_dpop_keystore_meta"
+    private const val META_STRONGBOX_FALLBACK_PREFIX = "strongbox_fallback_reason_"
+    private const val REASON_UNAVAILABLE = "UNAVAILABLE"
+    private const val REASON_PROVIDER_ERROR = "PROVIDER_ERROR"
+  }
+
+  private val metadataPrefs by lazy {
+    context.getSharedPreferences(META_PREFS, Context.MODE_PRIVATE)
   }
 
   private val keyStore: KeyStore by lazy {
@@ -46,6 +54,7 @@ internal class DPoPKeyStore(private val context: Context) {
     if (keyStore.containsAlias(alias)) {
       keyStore.deleteEntry(alias)
     }
+    clearStrongBoxFallbackReason(alias)
   }
 
   fun generateKeyPair(alias: String): Boolean {
@@ -56,16 +65,20 @@ internal class DPoPKeyStore(private val context: Context) {
     if (keyStore.containsAlias(alias)) {
       keyStore.deleteEntry(alias)
     }
+    clearStrongBoxFallbackReason(alias)
 
     val generator = KeyPairGenerator.getInstance(KeyProperties.KEY_ALGORITHM_EC, KEYSTORE_PROVIDER)
     if (isStrongBoxEnabled()) {
       try {
         generator.initialize(buildSpec(alias, useStrongBox = true))
         generator.generateKeyPair()
+        clearStrongBoxFallbackReason(alias)
         return true
       } catch (_: StrongBoxUnavailableException) {
+        storeStrongBoxFallbackReason(alias, REASON_UNAVAILABLE)
         // Fallback to hardware-backed keystore when StrongBox is unavailable.
       } catch (_: ProviderException) {
+        storeStrongBoxFallbackReason(alias, REASON_PROVIDER_ERROR)
         // Some devices expose StrongBox but fail during generation.
       }
     }
@@ -89,6 +102,12 @@ internal class DPoPKeyStore(private val context: Context) {
     return privateKey != null && publicKey != null
   }
 
+  fun isStrongBoxAvailable(): Boolean = isStrongBoxEnabled()
+
+  fun getStrongBoxFallbackReason(alias: String): String? {
+    return metadataPrefs.getString(strongBoxFallbackKey(alias), null)
+  }
+
   fun getKeyInfo(alias: String): KeyStoreKeyInfo {
     val keyPair = getKeyPair(alias)
     val keyFactory = KeyFactory.getInstance(keyPair.privateKey.algorithm, KEYSTORE_PROVIDER)
@@ -165,4 +184,14 @@ internal class DPoPKeyStore(private val context: Context) {
       false
     }
   }
+
+  private fun storeStrongBoxFallbackReason(alias: String, reason: String) {
+    metadataPrefs.edit().putString(strongBoxFallbackKey(alias), reason).apply()
+  }
+
+  private fun clearStrongBoxFallbackReason(alias: String) {
+    metadataPrefs.edit().remove(strongBoxFallbackKey(alias)).apply()
+  }
+
+  private fun strongBoxFallbackKey(alias: String): String = "$META_STRONGBOX_FALLBACK_PREFIX$alias"
 }

package/android/src/main/java/com/{dpop/DpopModule.kt → reactnativedpop/DPoPModule.kt}

@@ -1,4 +1,4 @@
-package com.dpop
+package com.reactnativedpop
 
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
@@ -8,8 +8,8 @@ import java.security.Signature
 import java.util.UUID
 import org.json.JSONObject
 
-class DpopModule(reactContext: ReactApplicationContext) :
-  NativeDpopSpec(reactContext) {
+class DPoPModule(reactContext: ReactApplicationContext) :
+  NativeReactNativeDPoPSpec(reactContext) {
   private val keyStore = DPoPKeyStore(reactContext)
 
   private fun resolveAlias(alias: String?): String {
@@ -70,26 +70,52 @@ class DpopModule(reactContext: ReactApplicationContext) :
     try {
       val effectiveAlias = resolveAlias(alias)
       if (!keyStore.hasKeyPair(effectiveAlias)) {
+        val fallbackReason = keyStore.getStrongBoxFallbackReason(effectiveAlias)
+        val hardwareAndroid = Arguments.createMap().apply {
+          putBoolean("strongBoxAvailable", keyStore.isStrongBoxAvailable())
+          putBoolean("strongBoxBacked", false)
+          if (fallbackReason != null) {
+            putString("strongBoxFallbackReason", fallbackReason)
+          } else {
+            putNull("strongBoxFallbackReason")
+          }
+        }
+        val hardware = Arguments.createMap().apply {
+          putMap("android", hardwareAndroid)
+        }
         val result = Arguments.createMap().apply {
           putString("alias", effectiveAlias)
           putBoolean("hasKeyPair", false)
+          putMap("hardware", hardware)
         }
         promise.resolve(result)
         return
       }
 
       val keyInfo = keyStore.getKeyInfo(effectiveAlias)
+      val 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)
+        }
+        if (fallbackReason != null) {
+          putString("strongBoxFallbackReason", fallbackReason)
+        } else {
+          putNull("strongBoxFallbackReason")
+        }
+      }
+      val hardware = Arguments.createMap().apply {
+        putMap("android", hardwareAndroid)
+      }
       val result = Arguments.createMap().apply {
         putString("alias", keyInfo.alias)
         putString("algorithm", keyInfo.algorithm)
         putString("curve", keyInfo.curve)
         putBoolean("hasKeyPair", true)
         putBoolean("insideSecureHardware", keyInfo.insideSecureHardware)
-        putBoolean("strongBoxAvailable", keyInfo.strongBoxAvailable)
-        putBoolean("strongBoxBacked", keyInfo.strongBoxBacked)
-        if (keyInfo.securityLevel != null) {
-          putInt("securityLevel", keyInfo.securityLevel)
-        }
+        putMap("hardware", hardware)
       }
       promise.resolve(result)
     } catch (e: Exception) {
@@ -297,6 +323,6 @@ class DpopModule(reactContext: ReactApplicationContext) :
 
   companion object {
     private const val DEFAULT_ALIAS = "react-native-dpop"
-    const val NAME = NativeDpopSpec.NAME
+    const val NAME = NativeReactNativeDPoPSpec.NAME
   }
 }

package/android/src/main/java/com/{dpop/DpopPackage.kt → reactnativedpop/DPoPPackage.kt}

@@ -1,4 +1,4 @@
-package com.dpop
+package com.reactnativedpop
 
 import com.facebook.react.BaseReactPackage
 import com.facebook.react.bridge.NativeModule
@@ -7,10 +7,10 @@ import com.facebook.react.module.model.ReactModuleInfo
 import com.facebook.react.module.model.ReactModuleInfoProvider
 import java.util.HashMap
 
-class DpopPackage : BaseReactPackage() {
+class DPoPPackage : BaseReactPackage() {
   override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
-    return if (name == DpopModule.NAME) {
-      DpopModule(reactContext)
+    return if (name == DPoPModule.NAME) {
+      DPoPModule(reactContext)
     } else {
       null
     }
@@ -18,9 +18,9 @@ class DpopPackage : BaseReactPackage() {
 
   override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
     mapOf(
-      DpopModule.NAME to ReactModuleInfo(
-        name = DpopModule.NAME,
-        className = DpopModule.NAME,
+      DPoPModule.NAME to ReactModuleInfo(
+        name = DPoPModule.NAME,
+        className = DPoPModule.NAME,
         canOverrideExistingModule = false,
         needsEagerInit = false,
         isCxxModule = false,

package/android/src/main/java/com/{dpop → reactnativedpop}/DPoPUtils.kt

@@ -1,4 +1,4 @@
-package com.dpop
+package com.reactnativedpop
 
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReadableArray

package/ios/DPoPKeyStore.swift

@@ -0,0 +1,134 @@
+import Foundation
+import Security
+
+struct DPoPKeyPairReference {
+  let privateKey: SecKey
+  let publicKey: SecKey
+}
+
+struct DPoPKeyInfo {
+  let alias: String
+  let algorithm: String
+  let curve: String
+  let hasKeyPair: Bool
+  let insideSecureHardware: Bool
+}
+
+final class DPoPKeyStore {
+  private let secureEnclave = SecureEnclaveKeyStore()
+  private let keychain = KeychainKeyStore()
+  private let fallbackReasonDefaults = UserDefaults.standard
+  private let fallbackReasonPrefix = "react_native_dpop_secure_enclave_fallback_reason_"
+  private lazy var secureEnclaveAvailable = secureEnclave.isAvailable()
+
+  func generateKeyPair(alias: String) throws {
+    try deleteKeyPair(alias: alias)
+
+    do {
+      try secureEnclave.generateKeyPair(alias: alias)
+      clearSecureEnclaveFallbackReason(alias: alias)
+    } catch {
+      storeSecureEnclaveFallbackReason(alias: alias, reason: mapSecureEnclaveFallbackReason(error))
+      try keychain.generateKeyPair(alias: alias)
+    }
+  }
+
+  func deleteKeyPair(alias: String) throws {
+    try secureEnclave.deleteKeyPair(alias: alias)
+    try keychain.deleteKeyPair(alias: alias)
+    clearSecureEnclaveFallbackReason(alias: alias)
+  }
+
+  func hasKeyPair(alias: String) -> Bool {
+    secureEnclave.hasKeyPair(alias: alias) || keychain.hasKeyPair(alias: alias)
+  }
+
+  func getKeyPair(alias: String) throws -> DPoPKeyPairReference {
+    if secureEnclave.hasKeyPair(alias: alias) {
+      return DPoPKeyPairReference(
+        privateKey: try secureEnclave.getPrivateKey(alias: alias),
+        publicKey: try secureEnclave.getPublicKey(alias: alias)
+      )
+    }
+
+    if keychain.hasKeyPair(alias: alias) {
+      return DPoPKeyPairReference(
+        privateKey: try keychain.getPrivateKey(alias: alias),
+        publicKey: try keychain.getPublicKey(alias: alias)
+      )
+    }
+
+    throw DPoPError.keyNotFound(alias: alias)
+  }
+
+  func getKeyInfo(alias: String) -> DPoPKeyInfo {
+    if secureEnclave.hasKeyPair(alias: alias) {
+      return DPoPKeyInfo(
+        alias: alias,
+        algorithm: "EC",
+        curve: "P-256",
+        hasKeyPair: true,
+        insideSecureHardware: true
+      )
+    }
+
+    if keychain.hasKeyPair(alias: alias) {
+      return DPoPKeyInfo(
+        alias: alias,
+        algorithm: "EC",
+        curve: "P-256",
+        hasKeyPair: true,
+        insideSecureHardware: false
+      )
+    }
+
+    return DPoPKeyInfo(
+      alias: alias,
+      algorithm: "EC",
+      curve: "P-256",
+      hasKeyPair: false,
+      insideSecureHardware: false
+    )
+  }
+
+  func isHardwareBacked(alias: String) -> Bool {
+    secureEnclave.isHardwareBacked(alias: alias)
+  }
+
+  func isSecureEnclaveAvailable() -> Bool {
+    secureEnclaveAvailable
+  }
+
+  func getSecureEnclaveFallbackReason(alias: String) -> String? {
+    fallbackReasonDefaults.string(forKey: fallbackReasonKey(alias: alias))
+  }
+
+  private func storeSecureEnclaveFallbackReason(alias: String, reason: String) {
+    fallbackReasonDefaults.set(reason, forKey: fallbackReasonKey(alias: alias))
+  }
+
+  private func clearSecureEnclaveFallbackReason(alias: String) {
+    fallbackReasonDefaults.removeObject(forKey: fallbackReasonKey(alias: alias))
+  }
+
+  private func fallbackReasonKey(alias: String) -> String {
+    "\(fallbackReasonPrefix)\(alias)"
+  }
+
+  private func mapSecureEnclaveFallbackReason(_ error: Error) -> String {
+    let nsError = error as NSError
+
+    if nsError.domain == NSOSStatusErrorDomain {
+      switch nsError.code {
+      case Int(errSecNotAvailable), Int(errSecUnimplemented):
+        return "UNAVAILABLE"
+      case Int(errSecAuthFailed), Int(errSecInteractionNotAllowed), Int(errSecUserCanceled):
+        return "POLICY_REJECTED"
+      default:
+        return "PROVIDER_ERROR"
+      }
+    }
+
+    return "UNKNOWN"
+  }
+}

package/ios/DPoPModule.h

@@ -0,0 +1,5 @@
+#import <React/RCTBridgeModule.h>
+
+@interface ReactNativeDPoP : NSObject <RCTBridgeModule>
+
+@end