@icedevml/react-native-host-card-emulation 0.2.2 → 0.4.0

package/README.md

@@ -8,10 +8,10 @@ Host Card Emulation Module for React Native on iOS and Android platforms.
 > in order to use this feature, which is managed by Apple. Read more in the official support article:
 > "[HCE-based contactless NFC transactions for apps in the European Economic Area (EEA)](https://developer.apple.com/support/hce-transactions-in-apps/)".
 
-> [!NOTE]  
-> Kindly please reference this project in your README if you are willing to create a derivative library.
-
 ## Prerequisites
+This package was designed for React Native [New Architecture](https://reactnative.dev/architecture/landing-page) only.
+Make sure that your project has it enabled. Note that the New Architecture is enabled by default for React Native 0.76+ projects.
+
 ### iOS
 1. Ensure that you are enrolled as organization (not individual) in Apple Developer Program, and that you are established in the European Economic Area (EEA).
 2. Ensure that you meet other [non-technical requirements imposed by Apple](https://developer.apple.com/support/hce-transactions-in-apps/#requirements-and-availability).
@@ -98,5 +98,65 @@ Install `@icedevml/react-native-host-card-emulation` package within your React N
 
 ## API Specification & Demo App
 
-* [module API (declarations)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/native-hce-module/js/NativeHCEModule.ts)
-* [demo app's code (example usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-hce-module-app/App.tsx)
+This module provides a uniform low-level HCE API for both mobile platforms.
+
+1. Subscribe to the event stream (there is a single global event stream for the entire module):
+   ```typescript
+   NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
+       switch (event.type) {
+           /* ... your handler here ... */
+       }
+   });
+   ```
+2. When user indicates that he wants to perform the HCE action, call the following function from the button's onClick routine:
+   ```typescript
+   await NativeHCEModule?.beginSession();
+   ```
+   This will emit `sessionStarted` event on both platforms. You can start the HCE straight from that event:
+   ```typescript
+   // inside NativeHCEModule?.onEvent handler's switch
+   case 'sessionStarted':
+       NativeHCEModule?.setSessionAlertMessage('Tap towards the reader');  // only for iOS, no-op in Android
+       await NativeHCEModule?.startHCE();
+       break;
+   ```
+3. Calling `startHCE()` causes:
+   * iOS: Launch of the NFC scan system UI. The smartphone will start listening for C-APDUs from the readers right after that UI appears on screen. The `readerDetected` event will be emitted as soon as the NFC tag field presence is observed. The `readerDeselected` event will be emitted if the reader is physically disconnected or a non-matching AID is selected by the reader.
+   * Android: No user interface appears (you have to implement it on your own scanning UI, within your app). The `readerDetected` event will be emitted as soon as the first matching SELECT AID command is observed. The `readerDeselected` event will be emitted if the reader is physically disconnected or a non-matching AID is selected by the reader.
+4. Optionally, you can handle `readerDetected` and `readerDeselected events to enhance user's experience.
+   ```typescript
+   // inside NativeHCEModule?.onEvent handler's switch
+   case 'readerDetected':
+       NativeHCEModule?.setSessionAlertMessage('Reader detected');  // only for iOS, no-op in Android
+       break;
+
+    case 'readerDeselected':
+        NativeHCEModule?.setSessionAlertMessage('Lost reader');  // only for iOS, no-op in Android
+        break;
+   ```
+5. Handle CAPDU
+   ```typescript
+   // inside NativeHCEModule?.onEvent handler's switch
+   case 'received':
+       NativeHCEModule?.setSessionAlertMessage('Keep holding the tag');
+
+       const capdu = Buffer.from(event.arg!, 'hex');
+       console.log('Received C-APDU, capdu.toString('hex'));
+   
+       // let's say we always want to respond with [0x0A] + Status Word 0x9000
+       await NativeHCEModule?.respondAPDU(Buffer.from([0x0A, 0x90, 0x00], "hex"));
+       break;
+   ```
+6. (iOS) Optionally, if you need to utilize `NFCPresentmentIntentAssertion` then at any time you can call:
+   ```typescript
+   NativeHCEModule?.acquireExclusiveNFC();
+   ```
+   Which will throw an exception if the presentment intent assertion was already acquired and is still valid 
+   (usually 15 seconds) or if the cooldown period for acquiring new assertion was not yet expired (usually also 15 seconds).
+
+> [!NOTE]
+> See [Demo App's Code (Example Library Usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-hce-module-app/App.tsx) example for more insignt about the library's API.
+
+> [!NOTE]
+> Raw native module's API specification is available in [packages/native-hce-module/js/NativeHCEModule.ts](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/native-hce-module/js/NativeHCEModule.ts).
+> Check it out in order to understand what methods you can call against the module and what are the expected parameters/return values.

package/android/src/main/java/com/itsecrnd/rtnhceandroid/AESGCMUtil.java

@@ -2,6 +2,13 @@ package com.itsecrnd.rtnhceandroid;
 
 import android.annotation.SuppressLint;
 
+import java.nio.charset.StandardCharsets;
+import java.security.InvalidAlgorithmParameterException;
+import java.security.InvalidKeyException;
+import java.security.NoSuchAlgorithmException;
+import java.security.SecureRandom;
+import java.util.Base64;
+
 import javax.crypto.BadPaddingException;
 import javax.crypto.Cipher;
 import javax.crypto.IllegalBlockSizeException;
@@ -10,15 +17,14 @@ import javax.crypto.NoSuchPaddingException;
 import javax.crypto.SecretKey;
 import javax.crypto.spec.GCMParameterSpec;
 
-import java.nio.charset.StandardCharsets;
-import java.security.InvalidAlgorithmParameterException;
-import java.security.InvalidKeyException;
-import java.security.NoSuchAlgorithmException;
-import java.security.SecureRandom;
-import java.util.Base64;
-
 @SuppressLint("NewApi")
 public class AESGCMUtil {
+    public static String randomString() {
+        byte[] rnd = new byte[32];
+        new SecureRandom().nextBytes(rnd);
+        return BinaryUtils.ByteArrayToHexString(rnd);
+    }
+
     public static SecretKey generateKey() {
         KeyGenerator keyGen;
         try {
@@ -30,12 +36,6 @@ public class AESGCMUtil {
         return keyGen.generateKey();
     }
 
-    public static byte[] generateNonce(int size) {
-        byte[] nonce = new byte[size];
-        new SecureRandom().nextBytes(nonce); // Fill nonce with random bytes
-        return nonce;
-    }
-
     public static String encryptData(SecretKey key, String plaintext) {
         try {
             byte[] iv = new byte[32];
@@ -49,14 +49,14 @@ public class AESGCMUtil {
             byte[] ciphertextBytes = cipher.doFinal(plaintextBytes);
 
             return Base64.getEncoder().encodeToString(iv) + ';' +
-                Base64.getEncoder().encodeToString(ciphertextBytes);
+                    Base64.getEncoder().encodeToString(ciphertextBytes);
         } catch (NoSuchPaddingException
                  | NoSuchAlgorithmException
                  | IllegalBlockSizeException
                  | InvalidAlgorithmParameterException
                  | BadPaddingException
                  | InvalidKeyException e) {
-            throw new RuntimeException(e);
+            throw new RuntimeException("Crypto error.", e);
         }
     }
 
@@ -83,7 +83,7 @@ public class AESGCMUtil {
                  | BadPaddingException
                  | InvalidKeyException
                  | NoSuchAlgorithmException e) {
-            throw new RuntimeException(e);
+            throw new RuntimeException("Crypto error.", e);
         }
     }
 }

package/android/src/main/java/com/itsecrnd/rtnhceandroid/BinaryUtils.java

@@ -30,7 +30,7 @@ public class BinaryUtils {
      * @return String, containing hexadecimal representation.
      */
     public static String ByteArrayToHexString(byte[] bytes) {
-        final char[] hexArray = {'0','1','2','3','4','5','6','7','8','9','A','B','C','D','E','F'};
+        final char[] hexArray = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'};
         char[] hexChars = new char[bytes.length * 2]; // Each byte has two hex characters (nibbles)
         int v;
         for (int j = 0; j < bytes.length; j++) {
@@ -59,7 +59,7 @@ public class BinaryUtils {
         for (int i = 0; i < len; i += 2) {
             // Convert each character into a integer (base-16), then bit-shift into place
             data[i / 2] = (byte) ((Character.digit(s.charAt(i), 16) << 4)
-                    + Character.digit(s.charAt(i+1), 16));
+                    + Character.digit(s.charAt(i + 1), 16));
         }
         return data;
     }

package/android/src/main/java/com/itsecrnd/rtnhceandroid/HCEService.java

@@ -1,22 +1,24 @@
 package com.itsecrnd.rtnhceandroid;
 
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_RECEIVE_C_APDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_SEND_R_APDU;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_DETECT;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_LOST;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_RECEIVE_C_APDU;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_SEND_R_APDU;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.KEY_AUTH;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.KEY_CAPDU;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.KEY_RAPDU;
 
 import android.content.BroadcastReceiver;
 import android.content.Context;
 import android.content.Intent;
 import android.content.IntentFilter;
 import android.nfc.cardemulation.HostApduService;
-import android.nfc.cardemulation.PollingFrame;
 import android.os.Build;
 import android.os.Bundle;
 import android.util.Log;
 
-import androidx.annotation.NonNull;
 import androidx.annotation.RequiresApi;
 
-import java.util.List;
 import java.util.Locale;
 
 import javax.crypto.SecretKey;
@@ -31,12 +33,20 @@ public class HCEService extends HostApduService {
     private final BroadcastReceiver receiver = new BroadcastReceiver() {
         @Override
         public void onReceive(Context context, Intent intent) {
-            String action = intent.getAction();
-
-            if (action != null && action.equals(INTENT_SEND_R_APDU)) {
-                String rapdu = AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("rapdu"));
-                byte[] dec = BinaryUtils.HexStringToByteArray(rapdu.toUpperCase(Locale.ROOT));
-                sendResponseApdu(dec);
+            try {
+                String action = intent.getAction();
+
+                if (action != null) {
+                    AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra(KEY_AUTH));
+
+                    if (action.equals(ACTION_SEND_R_APDU)) {
+                        String rapdu = AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra(KEY_RAPDU));
+                        byte[] dec = BinaryUtils.HexStringToByteArray(rapdu.toUpperCase(Locale.ROOT));
+                        sendResponseApdu(dec);
+                    }
+                }
+            } catch (Exception e) {
+                Log.e(TAG, "Failed to handle broadcast in HCEService.", e);
             }
         }
     };
@@ -45,29 +55,22 @@ public class HCEService extends HostApduService {
     public byte[] processCommandApdu(byte[] command, Bundle extras) {
         String capdu = AESGCMUtil.encryptData(encSecretKey, BinaryUtils.ByteArrayToHexString(command));
 
-        Intent intent = new Intent(INTENT_RECEIVE_C_APDU);
+        Intent intent = new Intent(ACTION_RECEIVE_C_APDU);
         intent.setPackage(getApplicationContext().getPackageName());
-        intent.putExtra("capdu", capdu);
+        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+        intent.putExtra(KEY_CAPDU, capdu);
         getApplicationContext().sendBroadcast(intent);
 
         return null;
     }
 
-    @Override
-    public void processPollingFrames(@NonNull List<PollingFrame> frames) {
-        super.processPollingFrames(frames);
-        Log.i(TAG, "Polling frames: " + frames.size());
-    }
-
     @Override
     public void onCreate() {
-        Log.d(TAG, "Starting service");
-
-        IntentFilter filter = new IntentFilter();
-        filter.addAction(INTENT_SEND_R_APDU);
+        Log.d(TAG, "HCEService onCreate");
 
+        String prefsName = getApplicationContext().getPackageName() + ".nativehcemodule";
         String encKey = getApplicationContext()
-                .getSharedPreferences("RTNHCEAndroidModuleBroadcastEnc", Context.MODE_PRIVATE)
+                .getSharedPreferences(prefsName, Context.MODE_PRIVATE)
                 .getString("encKey", "");
 
         if (encKey.isEmpty()) {
@@ -80,13 +83,25 @@ public class HCEService extends HostApduService {
         /*
          * See a comment about registerReceiver() in RTNHCEAndroidModule.
          */
+        IntentFilter filter = new IntentFilter();
+        filter.addAction(ACTION_SEND_R_APDU);
         getApplicationContext().registerReceiver(receiver, filter, RECEIVER_EXPORTED);
+
+        Intent intent = new Intent(ACTION_READER_DETECT);
+        intent.setPackage(getApplicationContext().getPackageName());
+        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+        getApplicationContext().sendBroadcast(intent);
     }
 
     @Override
     public void onDeactivated(int reason) {
-        Log.d(TAG, "Finishing service: " + reason);
+        Log.d(TAG, "HCEService onDeactivated: " + reason);
 
         getApplicationContext().unregisterReceiver(receiver);
+
+        Intent intent = new Intent(ACTION_READER_LOST);
+        intent.setPackage(getApplicationContext().getPackageName());
+        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+        getApplicationContext().sendBroadcast(intent);
     }
 }

package/android/src/main/java/com/itsecrnd/rtnhceandroid/IntentKeys.java

@@ -1,6 +1,11 @@
 package com.itsecrnd.rtnhceandroid;
 
 public class IntentKeys {
-    public static final String INTENT_RECEIVE_C_APDU = "com.itsecrnd.rtnhceandroid.receivecapdu";
-    public static final String INTENT_SEND_R_APDU = "com.itsecrnd.rtnhceandroid.sendrapdu";
+    public static final String ACTION_RECEIVE_C_APDU = "com.itsecrnd.rtnhceandroid.ACTION_RECEIVE_C_APDU";
+    public static final String ACTION_SEND_R_APDU = "com.itsecrnd.rtnhceandroid.ACTION_SEND_R_APDU";
+    public static final String ACTION_READER_DETECT = "com.itsecrnd.rtnhceandroid.ACTION_READER_DETECT";
+    public static final String ACTION_READER_LOST = "com.itsecrnd.rtnhceandroid.ACTION_READER_LOST";
+    public static final String KEY_AUTH = "auth";
+    public static final String KEY_CAPDU = "capdu";
+    public static final String KEY_RAPDU = "rapdu";
 }

package/android/src/main/java/com/itsecrnd/rtnhceandroid/RTNHCEAndroidModule.java

@@ -1,14 +1,17 @@
 package com.itsecrnd.rtnhceandroid;
 
 import static android.content.Context.RECEIVER_EXPORTED;
-
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_RECEIVE_C_APDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_SEND_R_APDU;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_DETECT;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_LOST;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_RECEIVE_C_APDU;
+import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_SEND_R_APDU;
 
 import android.content.BroadcastReceiver;
+import android.content.ComponentName;
 import android.content.Context;
 import android.content.Intent;
 import android.content.IntentFilter;
+import android.content.pm.PackageManager;
 import android.os.Build;
 import android.util.Log;
 
@@ -27,20 +30,55 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
     public static final String TAG = "RTNHCEAndroidModule";
     public static final String NAME = "NativeHCEModule";
 
+    private volatile boolean sessionRunning;
+    private volatile boolean hceRunning;
+    private volatile boolean hceBreakConnection;
+    private volatile boolean hceDeselected;
     private final SecretKey encSecretKey;
 
+    private void sendEvent(final String type, final String arg) {
+        WritableMap map = Arguments.createMap();
+        map.putString("type", type);
+        map.putString("arg", arg);
+        emitOnEvent(map);
+    }
+
     private final BroadcastReceiver receiver = new BroadcastReceiver() {
         @Override
         public void onReceive(Context context, Intent intent) {
-            String action = intent.getAction();
-
-            if (action != null && action.equals(INTENT_RECEIVE_C_APDU)) {
-                String capdu = AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("capdu"));
-
-                WritableMap map = Arguments.createMap();
-                map.putString("type", "received");
-                map.putString("arg", capdu);
-                emitOnEvent(map);
+            try {
+                String action = intent.getAction();
+
+                if (action != null) {
+                    AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("auth"));
+
+                    if (action.equals(ACTION_RECEIVE_C_APDU)) {
+                        String capdu = AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("capdu"));
+
+                        if (!hceBreakConnection && hceRunning) {
+                            sendEvent("received", capdu);
+                        } else {
+                            Intent rintent = new Intent(ACTION_SEND_R_APDU);
+                            rintent.setPackage(getReactApplicationContext().getPackageName());
+                            rintent.putExtra("auth", AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+                            rintent.putExtra("rapdu", AESGCMUtil.encryptData(encSecretKey, "6999"));
+                            getReactApplicationContext().getApplicationContext().sendBroadcast(rintent);
+                        }
+                    } else if (hceRunning && action.equals(ACTION_READER_DETECT)) {
+                        hceDeselected = false;
+                        sendEvent("readerDetected", "");
+                    } else if (action.equals(ACTION_READER_LOST)) {
+                        if (hceRunning && !hceBreakConnection && !hceDeselected) {
+                            // only if we haven't send a fake disconnect event already
+                            hceDeselected = true;
+                            sendEvent("readerDeselected", "");
+                        }
+
+                        hceBreakConnection = false;
+                    }
+                }
+            } catch (Exception e) {
+                Log.e(TAG, "Failed to handle broadcast in RTNHCEAndroidModule.", e);
             }
         }
     };
@@ -48,6 +86,10 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
     RTNHCEAndroidModule(ReactApplicationContext context) {
         super(context);
         String encKey;
+        this.sessionRunning = false;
+        this.hceRunning = false;
+        this.hceBreakConnection = false;
+        this.hceDeselected = true;
 
         try {
             encSecretKey = AESGCMUtil.generateKey();
@@ -56,14 +98,17 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
             throw new RuntimeException("Failed to generate encryption key.", e);
         }
 
+        String prefsName = getReactApplicationContext().getPackageName() + ".nativehcemodule";
         getReactApplicationContext()
-                .getSharedPreferences("RTNHCEAndroidModuleBroadcastEnc", Context.MODE_PRIVATE)
+                .getSharedPreferences(prefsName, Context.MODE_PRIVATE)
                 .edit()
                 .putString("encKey", encKey)
                 .commit();
 
         IntentFilter filter = new IntentFilter();
-        filter.addAction(INTENT_RECEIVE_C_APDU);
+        filter.addAction(ACTION_RECEIVE_C_APDU);
+        filter.addAction(ACTION_READER_DETECT);
+        filter.addAction(ACTION_READER_LOST);
 
         /*
          * FIXME It seems like those intents are not going through across this module and HostApduService.
@@ -78,6 +123,11 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         getReactApplicationContext().getApplicationContext().registerReceiver(receiver, filter, RECEIVER_EXPORTED);
     }
 
+    @Override
+    public void invalidate() {
+        getReactApplicationContext().getApplicationContext().unregisterReceiver(receiver);
+    }
+
     @Override
     @NonNull
     public String getName() {
@@ -86,46 +136,74 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public boolean isPlatformSupported() {
-        return true;
+        PackageManager pm = getReactApplicationContext().getPackageManager();
+        return pm.hasSystemFeature(PackageManager.FEATURE_NFC)
+            && pm.hasSystemFeature(PackageManager.FEATURE_NFC_HOST_CARD_EMULATION);
     }
 
     @Override
     public void acquireExclusiveNFC(Promise promise) {
-        promise.resolve(null);
+        promise.reject("err_platform_unsupported", "acquireExclusiveNFC() is not supported on Android.");
     }
 
     @Override
     public boolean isExclusiveNFC() {
+        // unsupported on Android, always false
         return false;
     }
 
     @Override
     public void beginSession(Promise promise) {
-        promise.resolve(null);
+        if (!this.sessionRunning) {
+            this.sessionRunning = true;
+            sendEvent("sessionStarted", "");
+            promise.resolve(null);
+        } else {
+            promise.reject("err_card_session_exists", "Session already exists.");
+        }
     }
 
     @Override
     public void setSessionAlertMessage(String message) {
-
+        // unsupported on Android, no-op
     }
 
     @Override
     public void invalidateSession() {
-
+        if (this.sessionRunning) {
+            this.sessionRunning = false;
+            sendEvent("sessionInvalidated", "userInvalidated");
+        }
     }
 
     @Override
     public boolean isSessionRunning() {
-        return true;
+        return this.sessionRunning;
     }
 
     @Override
     public void startHCE(Promise promise) {
+        if (this.hceRunning) {
+            promise.reject("err_start_emulation", "Error trying to start emulation. Emulation already started.");
+            return;
+        }
+
+        this.hceRunning = true;
         promise.resolve(null);
     }
 
     @Override
     public void stopHCE(String status, Promise promise) {
+        if (this.hceRunning) {
+            this.hceRunning = false;
+
+            if (!this.hceDeselected) {
+                this.hceDeselected = true;
+                this.hceBreakConnection = true;
+                sendEvent("readerDeselected", "");
+            }
+        }
+
         promise.resolve(null);
     }
 
@@ -133,8 +211,9 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
     public void respondAPDU(String rapdu, Promise promise) {
         String encRapdu = AESGCMUtil.encryptData(encSecretKey, rapdu);
 
-        Intent intent = new Intent(INTENT_SEND_R_APDU);
+        Intent intent = new Intent(ACTION_SEND_R_APDU);
         intent.setPackage(getReactApplicationContext().getPackageName());
+        intent.putExtra("auth", AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
         intent.putExtra("rapdu", encRapdu);
         getReactApplicationContext().getApplicationContext().sendBroadcast(intent);
 
@@ -143,6 +222,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public void isHCERunning(Promise promise) {
+        // unsupported on Android, always true
         promise.resolve(true);
     }
 }

package/android/src/main/java/com/itsecrnd/rtnhceandroid/RTNHCEAndroidPackage.java

@@ -40,7 +40,7 @@ public class RTNHCEAndroidPackage extends TurboReactPackage {
                             true, // hasConstants
                             false, // isCxxModule
                             true // isTurboModule
-            ));
+                    ));
             return moduleInfos;
         };
     }

package/ios/RTNHCEModuleIOSImpl.swift

@@ -170,7 +170,14 @@ extension Data {
 
   @objc public func startHCE(resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
     Task.init {
-      try await self.cardSession?.startEmulation()
+      do {
+        try await self.cardSession?.startEmulation()
+      } catch(let error) {
+        reject("err_start_emulation", "Error trying to start emulation. \(error)", nil)
+        return
+      }
+
+      resolve(nil)
     }
   }
 

package/js/NativeHCEModule.ts

@@ -1,7 +1,22 @@
 import type {TurboModule, CodegenTypes} from 'react-native';
 import {TurboModuleRegistry} from 'react-native';
 
-export type HCEModuleEventType = 'sessionStarted' | 'readerDetected' | 'readerDeselected' | 'received' | 'sessionInvalidated';
+export type HCEModuleEventType = 'sessionStarted'
+    | 'sessionInvalidated'
+    /**
+     * iOS: Whether the reader field was detected.
+     * Android: Whether the reader had sent the select command to us.
+     */
+    | 'readerDetected'
+    /**
+     * Whether our HCE app was deselected or the reader was lost.
+     */
+    | 'readerDeselected'
+    /**
+     * Received C-APDU (hex-encoded string in "arg" key) from the reader.
+     * Respond by calling respondAPDU(rapdu).
+     */
+    | 'received';
 export type HCEModuleStopReason = 'success' | 'failure';
 
 export type HCEModuleEvent = {
@@ -10,19 +25,62 @@ export type HCEModuleEvent = {
 }
 
 export interface Spec extends TurboModule {
+  /**
+   * Checks if a given smartphone supports required HCE features.
+   */
   isPlatformSupported(): boolean;
 
-  acquireExclusiveNFC(): Promise<boolean>;
+  /**
+   * iOS: Tries to acquire NFCPresentmentIntentAssertion.
+   * Android: Not supported (throws an exception).
+   */
+  acquireExclusiveNFC(): Promise<void>;
+  /**
+   * iOS: Whether the NFCPresentmentIntentAssertion is acquired and still valid.
+   * Android: Always false.
+   */
   isExclusiveNFC(): boolean;
 
+  /**
+   * Begin card operation session.
+   * iOS: Create CardSession.
+   * Android: Sets an internal flag that the session is open.
+   */
   beginSession(): Promise<void>;
+  /**
+   * iOS: Set alert message on the NFC system UI.
+   * Android: NO-OP.
+   */
   setSessionAlertMessage(message: string): void;
+  /**
+   * iOS: Invalidate CardSession.
+   * Android: Set an internal flag that the session is closed and disable HCE service.
+   */
   invalidateSession(): void;
+  /**
+   * iOS: Checks if CardSession is running.
+   * Android: Checks if an internal flag is set.
+   */
   isSessionRunning(): boolean;
 
+  /**
+   * iOS: Start the card emulation.
+   * Android: Enable HCE service.
+   */
   startHCE(): Promise<void>;
+  /**
+   * iOS: Stop the card emulation with "success"/"failure" UI status.
+   * Android: Disable HCE service.
+   */
   stopHCE(status: HCEModuleStopReason): Promise<void>;
+  /**
+   * Send R-APDU (hex-encoded string) as a response to the last received C-APDU event.
+   */
   respondAPDU(rapdu: string): Promise<void>;
+  /**
+   * iOS: Checks if the card emulation is running.
+   * Android: Checks if the HCE service is enabled.
+   */
   isHCERunning(): Promise<boolean>;
 
   readonly onEvent: CodegenTypes.EventEmitter<HCEModuleEvent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icedevml/react-native-host-card-emulation",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Host Card Emulation (HCE) React Native Turbo Module for iOS and Android platforms.",
   "react-native": "js/index",
   "source": "js/index",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Michal Leszczynski
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.