@icedevml/react-native-host-card-emulation 0.5.0 → 0.6.0

package/README.md

@@ -1,12 +1,17 @@
-# Package: React Native HCE Module
+# React Native Package: @icedevml/react-native-host-card-emulation
 
 Host Card Emulation Module for React Native on iOS and Android platforms.
 
+> [!NOTE]
+> Pull requests are welcome! Please [report an issue](https://github.com/icedevml/react-native-host-card-emulation/issues) if you are running into any difficulties.
+
 > [!IMPORTANT]  
 > As per Apple's policy, **Host Card Emulation feature is only available for users based in the European
 > Economic Area (EEA)** with an iPhone running iOS 17.4 or later. Applications require a special HCE entitlement
 > 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/)".
+>
+> However, you can still use this package without any limitations if you only want to cover for Android implementation.
 
 ## Prerequisites
 This package was designed for React Native [New Architecture](https://reactnative.dev/architecture/landing-page) only.
@@ -112,11 +117,11 @@ Afterwards, follow the subsections below for each platform that you need to supp
 This module provides a uniform low-level HCE API for both mobile platforms.
 
 > [!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).
+> Raw native module's API specification is available in [packages/host-card-emulation/js/NativeHCEModule.ts](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/host-card-emulation/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.
 
 > [!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.
+> See [Demo App's Code (Example Library Usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-ndef-app/App.tsx) example for more insignt about the library's API.
 
 ### Quick start guide
 
@@ -175,7 +180,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
        console.log('Received C-APDU, capdu.toString('hex'));
    
        // for the demo purposes, we always want to respond with [0x0A] + status code 0x9000 (success)
-       await NativeHCEModule?.respondAPDU(Buffer.from([0x0A, 0x90, 0x00], "hex"));
+       await NativeHCEModule?.respondAPDU(null, Buffer.from([0x0A, 0x90, 0x00], "hex"));
        break;
    ```
    You don't have to respond to the APDU right away from within the event handler, but please remember that the reader might time out if you will be lingering with the response for too long.
@@ -203,29 +208,34 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
 
 1. Register `handleBackgroundHCECall` headless task in your app's `index.js`:
    ```typescript
+   import { createBackgroundHCE } from '@icedevml/react-native-host-card-emulation/js/hceBackground';
+
    AppRegistry.registerHeadlessTask('handleBackgroundHCECall', () => {
-      return async () => {
-         return await runBackground();
+      return async (taskData) => {
+         return await runBackgroundHCETask(createBackgroundHCE(taskData.handle));
       }
    });
    ```
 2. Register onBackgroundEvent listener in your `runBackground()` function and call to `await NativeHCEModule?.initBackgroundHCE()` at the very end, after the event listener is fully set up.
    ```typescript
-   async function runBackground() {
-      let subscription = NativeHCEModule?.onBackgroundEvent(async (event: HCEModuleBackgroundEvent) => {
+   import { Buffer } from 'buffer/';
+   import {
+     ProcessBackgroundHCEFunc,
+   } from '@icedevml/react-native-host-card-emulation/js/hceBackground';
+
+   export default async function runBackgroundHCETask(processBackgroundHCE: ProcessBackgroundHCEFunc) {
+      processBackgroundHCE(async (event, respondAPDU) => {
          switch (event.type) {
             /* ... background HCE event handler here ... */
          }
       });
-   
-      await NativeHCEModule?.initBackgroundHCE();
    }
    ```
 3. Cleanup your event listener in `readerDeselected` -- this is obligatory because lack of proper cleanup will result in bugs and unexpected behavior.
    ```typescript
    case 'readerDeselected':
-       // cleanup, remove the event listener
-       subscription.remove();
+       // our application was deselected or the reader field was lost
+       // perform a cleanup of any resources here
        break;
    ```
 4. Implement the actual APDU handler that will process the C-APDU and generate a response.
@@ -236,11 +246,11 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
        console.log('Received C-APDU, capdu.toString('hex'));
       
        // for the demo purposes, we always want to respond with [0x0A] + status code 0x9000 (success)
-       await NativeHCEModule?.respondAPDU(Buffer.from([0x0A, 0x90, 0x00], "hex"));
+       await respondAPDU(Buffer.from([0x0A, 0x90, 0x00]).toString("hex"));
        break;
    ```
 
 ### More resources
 
-* [Module's API specification](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/native-hce-module/js/NativeHCEModule.ts)
-* [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)
+* [Module's API specification](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/host-card-emulation/js/NativeHCEModule.ts)
+* [Demo App's Code (Example Library Usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-ndef-app/App.tsx)

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

@@ -30,12 +30,14 @@ import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
 
 import java.util.List;
 import java.util.Locale;
+import java.util.UUID;
 
 @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
 public class HCEService extends HostApduService implements ReactInstanceEventListener, HCEServiceCallback {
     private static final String TAG = "HCEService";
 
     private boolean isForeground;
+    private String backgroundSessionUUID;
     private RTNHCEAndroidModule hceModule;
     private byte[] pendingCAPDU;
     private volatile boolean needsResponse;
@@ -63,20 +65,36 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
     }
 
     @Override
-    public void onBackgroundHCEInit() {
+    public void onBackgroundHCEInit(String handle) {
         Log.d(TAG, "HCEService:onBackgroundHCEInit");
 
+        if (handle == null && backgroundSessionUUID != null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit foreground call to background session");
+            throw new IllegalStateException();
+        } else if (handle != null && !handle.equals(backgroundSessionUUID)) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit mismatched background session handle");
+            throw new IllegalStateException();
+        }
+
         if (pendingCAPDU != null) {
             Log.d(TAG, "HCEService:onBackgroundHCEInit send pendingCAPDU");
-            hceModule.sendBackgroundEvent("received", BinaryUtils.ByteArrayToHexString(pendingCAPDU));
+            hceModule.sendBackgroundEvent(backgroundSessionUUID, "received", BinaryUtils.ByteArrayToHexString(pendingCAPDU));
             pendingCAPDU = null;
         }
     }
 
     @Override
-    public void onRespondAPDU(String rapdu) {
+    public void onRespondAPDU(String handle, String rapdu) {
         Log.d(TAG, "HCEService:onRespondAPDU");
 
+        if (handle == null && backgroundSessionUUID != null) {
+            Log.d(TAG, "HCEService:onRespondAPDU foreground call to background session");
+            throw new IllegalStateException();
+        } else if (handle != null && !handle.equals(backgroundSessionUUID)) {
+            Log.d(TAG, "HCEService:onRespondAPDU mismatched background session handle");
+            throw new IllegalStateException();
+        }
+
         if (!needsResponse) {
             Log.d(TAG, "HCEService:onRespondAPDU not waiting for a response");
             throw new IllegalStateException();
@@ -104,7 +122,7 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
             if (hceModule != null && hceModule.isHCEBackgroundHandlerReady()) {
                 Log.d(TAG, "HCEService:processCommandApdu background sendBackgroundEvent received");
                 needsResponse = true;
-                hceModule.sendBackgroundEvent("received", capdu);
+                hceModule.sendBackgroundEvent(backgroundSessionUUID, "received", capdu);
             } else {
                 Log.d(TAG, "HCEService:processCommandApdu background pendingCAPDU");
                 needsResponse = true;
@@ -132,6 +150,7 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
 
         if (isForeground) {
             Log.d(TAG, "HCEService:onCreate foreground");
+            this.backgroundSessionUUID = null;
 
             ReactContext reactContext = reactHost.getCurrentReactContext();
 
@@ -155,6 +174,7 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
         } else {
             ReactContext reactContext = reactHost.getCurrentReactContext();
             Log.d(TAG, "HCEService:onCreate background");
+            this.backgroundSessionUUID = UUID.randomUUID().toString();
 
             if (reactContext == null) {
                 reactHost.addReactInstanceEventListener(this);
@@ -175,7 +195,7 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
                 this.hceModule.sendEvent("readerDeselected", "");
             }
         } else {
-            this.hceModule.sendBackgroundEvent("readerDeselected", "");
+            this.hceModule.sendBackgroundEvent(backgroundSessionUUID, "readerDeselected", "");
         }
 
         if (this.hceModule != null) {
@@ -214,11 +234,13 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
             @Override
             public void run() {
                 Log.d(TAG, "HCEService:setupRunJSTask:runOnUiThread startTask");
+                Bundle argBundle = new Bundle();
+                argBundle.putString("handle", backgroundSessionUUID);
                 HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
                 headlessJsTaskContext.startTask(
                         new HeadlessJsTaskConfig(
                                 "handleBackgroundHCECall",
-                                Arguments.fromBundle(new Bundle()),
+                                Arguments.fromBundle(argBundle),
                                 15000,
                                 false // not allowed in foreground
                         ));

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

@@ -1,6 +1,6 @@
 package com.itsecrnd.rtnhceandroid;
 
 public interface HCEServiceCallback {
-    void onBackgroundHCEInit();
-    void onRespondAPDU(String rapdu);
+    void onBackgroundHCEInit(String handle);
+    void onRespondAPDU(String handle, String rapdu);
 }

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

@@ -57,9 +57,10 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         emitOnEvent(map);
     }
 
-    void sendBackgroundEvent(final String type, final String arg) {
+    void sendBackgroundEvent(final String audience, final String type, final String arg) {
         Log.d(TAG, "RTNHCEAndroidModule:sendBackgroundEvent");
         WritableMap map = Arguments.createMap();
+        map.putString("audience", audience);
         map.putString("type", type);
         map.putString("arg", arg);
         emitOnBackgroundEvent(map);
@@ -157,14 +158,17 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
     }
 
     @Override
-    public void initBackgroundHCE(Promise promise) {
-        Log.d(TAG, "RTNHCEAndroidModule:initBackgroundHCE");
+    public boolean beginBackgroundHCE(String handle) {
+        Log.d(TAG, "RTNHCEAndroidModule:beginBackgroundHCE");
 
-        this.hceBackgroundReady = true;
-
-        promise.resolve(null);
+        try {
+            this.serviceCb.onBackgroundHCEInit(handle);
+        } catch (IllegalStateException e) {
+            return false;
+        }
 
-        this.serviceCb.onBackgroundHCEInit();
+        this.hceBackgroundReady = true;
+        return true;
     }
 
     @Override
@@ -208,7 +212,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
     @Override
-    public void respondAPDU(String rapdu, Promise promise) {
+    public void respondAPDU(String handle, String rapdu, Promise promise) {
         Log.d(TAG, "RTNHCEAndroidModule:respondAPDU");
 
         if (!this.hceBackgroundReady) {
@@ -224,9 +228,9 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         Log.d(TAG, "respondAPDU(): Send to service");
 
         try {
-            serviceCb.onRespondAPDU(rapdu);
+            serviceCb.onRespondAPDU(handle, rapdu);
         } catch (IllegalStateException e) {
-            promise.reject("err_no_capdu", "There is no C-APDU to respond to at the time.");
+            promise.reject("err_illegal_state", "There is no C-APDU to respond to at the time or the provided handle is invalid.");
             return;
         }
 

package/ios/RTNHCEModuleIOS.mm

@@ -86,8 +86,8 @@
     }
 }
 
-- (void)initBackgroundHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
-    reject(@"err_platform_unsupported", @"Background HCE is not supported on iOS.", nil);
+- (nonnull NSNumber *)beginBackgroundHCE:(nonnull NSString *)handle {
+    return @0;
 }
 
 - (void)startHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
@@ -106,9 +106,9 @@
     }
 }
 
-- (void)respondAPDU:(nonnull NSString *)rapdu resolve:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
+- (void)respondAPDU:(NSString * _Nullable)handle rapdu:(nonnull NSString *)rapdu resolve:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
     if (@available(iOS 17.4, *)) {
-        return [hcemoduleios respondAPDUWithRapdu:rapdu resolve:resolve reject:reject];
+        return [hcemoduleios respondAPDUWithHandle:handle rapdu:rapdu resolve:resolve reject:reject];
     } else {
         reject(@"err_platform_unsupported", @"This iOS version does not support HCE.", nil);
     }

package/ios/RTNHCEModuleIOSImpl.swift

@@ -145,8 +145,13 @@ extension Data {
     }
   }
 
-  @objc public func respondAPDU(rapdu: NSString, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+  @objc public func respondAPDU(handle: NSString?, rapdu: NSString, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
     Task.init {
+      guard handle == nil else {
+        reject("err_illegal_state", "The provided handle is invalid.", nil)
+        return
+      }
+        
       guard let capdu = self.receivedCardAPDU else {
         reject("err_no_apdu_received", "There is no received APDU to respond to.", nil)
         return

package/js/NativeHCEModule.ts

@@ -32,6 +32,7 @@ export type HCEModuleEvent = {
 export type HCEModuleBackgroundEvent = {
   type: HCEModuleBackgroundEventType
   arg: string | null,
+  audience: string,
 }
 
 export interface Spec extends TurboModule {
@@ -73,7 +74,7 @@ export interface Spec extends TurboModule {
    */
   isSessionRunning(): boolean;
 
-  initBackgroundHCE(): Promise<void>;
+  beginBackgroundHCE(handle: string): boolean;
 
   /**
    * iOS: Start the card emulation.
@@ -88,7 +89,7 @@ export interface Spec extends TurboModule {
   /**
    * Send R-APDU (hex-encoded string) as a response to the last received C-APDU event.
    */
-  respondAPDU(rapdu: string): Promise<void>;
+  respondAPDU(handle: string | null, rapdu: string): Promise<void>;
   /**
    * iOS: Checks if the card emulation is running.
    * Android: Checks if the HCE service is enabled.

package/js/hceBackground.ts

@@ -0,0 +1,43 @@
+import NativeHCEModule, {HCEModuleBackgroundEvent} from "./NativeHCEModule";
+
+export interface BackgroundEventHandler {
+    (
+        event: HCEModuleBackgroundEvent,
+        respondAPDU: (rapdu: string) => Promise<void>,
+    ): Promise<void>
+}
+
+export interface ProcessBackgroundHCEFunc {
+    (
+        handler: BackgroundEventHandler
+    ): void
+}
+
+export const createBackgroundHCE = (handle: string) => {
+    const respondAPDU = (rapdu: string) => {
+        return NativeHCEModule.respondAPDU(handle, rapdu);
+    }
+
+    return (handler: BackgroundEventHandler) => {
+        const subscription = NativeHCEModule.onBackgroundEvent(async (event) => {
+            if (event.audience !== handle) {
+                // ignore
+                return;
+            }
+
+            try {
+                await handler(event, respondAPDU);
+            } catch (e) {
+                throw e;
+            } finally {
+                if (event.type === "readerDeselected") {
+                    subscription.remove();
+                }
+            }
+        });
+
+        if (!NativeHCEModule.beginBackgroundHCE(handle)) {
+            subscription.remove();
+        }
+    }
+}

package/package.json

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