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

package/README.md

@@ -67,7 +67,7 @@ Install `@icedevml/react-native-host-card-emulation` package within your React N
    +    <service
    +      android:name="com.itsecrnd.rtnhceandroid.HCEService"
    +      android:exported="true"
-   +      android:enabled="false"
+   +      android:enabled="true"
    +      android:permission="android.permission.BIND_NFC_SERVICE" >
    +      <intent-filter>
    +        <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />
@@ -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/HCEService.java

@@ -1,9 +1,12 @@
 package com.itsecrnd.rtnhceandroid;
 
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_READER_DETECT;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_READER_LOST;
-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;
@@ -34,10 +37,10 @@ public class HCEService extends HostApduService {
                 String action = intent.getAction();
 
                 if (action != null) {
-                    AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("auth"));
+                    AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra(KEY_AUTH));
 
-                    if (action.equals(INTENT_SEND_R_APDU)) {
-                        String rapdu = AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("rapdu"));
+                    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);
                     }
@@ -52,10 +55,10 @@ 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("auth", AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
-        intent.putExtra("capdu", capdu);
+        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+        intent.putExtra(KEY_CAPDU, capdu);
         getApplicationContext().sendBroadcast(intent);
 
         return null;
@@ -81,12 +84,12 @@ public class HCEService extends HostApduService {
          * See a comment about registerReceiver() in RTNHCEAndroidModule.
          */
         IntentFilter filter = new IntentFilter();
-        filter.addAction(INTENT_SEND_R_APDU);
+        filter.addAction(ACTION_SEND_R_APDU);
         getApplicationContext().registerReceiver(receiver, filter, RECEIVER_EXPORTED);
 
-        Intent intent = new Intent(INTENT_READER_DETECT);
+        Intent intent = new Intent(ACTION_READER_DETECT);
         intent.setPackage(getApplicationContext().getPackageName());
-        intent.putExtra("auth", AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
         getApplicationContext().sendBroadcast(intent);
     }
 
@@ -96,9 +99,9 @@ public class HCEService extends HostApduService {
 
         getApplicationContext().unregisterReceiver(receiver);
 
-        Intent intent = new Intent(INTENT_READER_LOST);
+        Intent intent = new Intent(ACTION_READER_LOST);
         intent.setPackage(getApplicationContext().getPackageName());
-        intent.putExtra("auth", AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
+        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
         getApplicationContext().sendBroadcast(intent);
     }
 }

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

@@ -1,8 +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 INTENT_READER_DETECT = "com.itsecrnd.rtnhceandroid.readerdetect";
-    public static final String INTENT_READER_LOST = "com.itsecrnd.rtnhceandroid.readerlost";
+    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,10 +1,10 @@
 package com.itsecrnd.rtnhceandroid;
 
 import static android.content.Context.RECEIVER_EXPORTED;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_READER_DETECT;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.INTENT_READER_LOST;
-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;
@@ -30,20 +30,11 @@ 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 boolean sessionOpen;
-
-    private void toggleHceService(Boolean enabled) {
-        getReactApplicationContext()
-                .getPackageManager()
-                .setComponentEnabledSetting(
-                        new ComponentName(getReactApplicationContext(), HCEService.class),
-                        enabled
-                                ? PackageManager.COMPONENT_ENABLED_STATE_ENABLED
-                                : PackageManager.COMPONENT_ENABLED_STATE_DISABLED,
-                        PackageManager.DONT_KILL_APP
-                );
-    }
 
     private void sendEvent(final String type, final String arg) {
         WritableMap map = Arguments.createMap();
@@ -61,13 +52,29 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
                 if (action != null) {
                     AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("auth"));
 
-                    if (action.equals(INTENT_RECEIVE_C_APDU)) {
+                    if (action.equals(ACTION_RECEIVE_C_APDU)) {
                         String capdu = AESGCMUtil.decryptData(encSecretKey, intent.getStringExtra("capdu"));
-                        sendEvent("received", capdu);
-                    } else if (action.equals(INTENT_READER_DETECT)) {
+
+                        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(INTENT_READER_LOST)) {
-                        sendEvent("readerDeselected", "");
+                    } 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) {
@@ -78,10 +85,11 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     RTNHCEAndroidModule(ReactApplicationContext context) {
         super(context);
-
-        this.sessionOpen = false;
-
         String encKey;
+        this.sessionRunning = false;
+        this.hceRunning = false;
+        this.hceBreakConnection = false;
+        this.hceDeselected = true;
 
         try {
             encSecretKey = AESGCMUtil.generateKey();
@@ -98,9 +106,9 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
                 .commit();
 
         IntentFilter filter = new IntentFilter();
-        filter.addAction(INTENT_RECEIVE_C_APDU);
-        filter.addAction(INTENT_READER_DETECT);
-        filter.addAction(INTENT_READER_LOST);
+        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.
@@ -115,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() {
@@ -135,18 +148,18 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public boolean isExclusiveNFC() {
-        // unsupported on Android
+        // unsupported on Android, always false
         return false;
     }
 
     @Override
     public void beginSession(Promise promise) {
-        if (this.sessionOpen) {
-            promise.reject("err_card_session_exists", "Session already exists.");
-        } else {
-            this.sessionOpen = true;
-            promise.resolve(null);
+        if (!this.sessionRunning) {
+            this.sessionRunning = true;
             sendEvent("sessionStarted", "");
+            promise.resolve(null);
+        } else {
+            promise.reject("err_card_session_exists", "Session already exists.");
         }
     }
 
@@ -157,37 +170,48 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public void invalidateSession() {
-        toggleHceService(false);
-        this.sessionOpen = false;
-        sendEvent("sessionInvalidated", "");
+        if (this.sessionRunning) {
+            this.sessionRunning = false;
+            sendEvent("sessionInvalidated", "userInvalidated");
+        }
     }
 
     @Override
     public boolean isSessionRunning() {
-        return this.sessionOpen;
+        return this.sessionRunning;
     }
 
     @Override
     public void startHCE(Promise promise) {
-        toggleHceService(true);
+        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) {
-        toggleHceService(false);
+        if (this.hceRunning) {
+            this.hceRunning = false;
+
+            if (!this.hceDeselected) {
+                this.hceDeselected = true;
+                this.hceBreakConnection = true;
+                sendEvent("readerDeselected", "");
+            }
+        }
+
         promise.resolve(null);
     }
 
     @Override
     public void respondAPDU(String rapdu, Promise promise) {
-        if (!this.sessionOpen) {
-            return;
-        }
-
         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);
@@ -198,10 +222,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public void isHCERunning(Promise promise) {
-        int enabledSetting = getReactApplicationContext()
-                .getPackageManager()
-                .getComponentEnabledSetting(new ComponentName(getReactApplicationContext(), HCEService.class));
-
-        promise.resolve(enabledSetting == PackageManager.COMPONENT_ENABLED_STATE_ENABLED);
+        // unsupported on Android, always true
+        promise.resolve(true);
     }
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icedevml/react-native-host-card-emulation",
-  "version": "0.3.0",
+  "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",