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

package/README.md

@@ -23,7 +23,17 @@ Make sure that your project has it enabled. Note that the New Architecture is en
 *(no prerequisite steps are required for Android)*
 
 ## Installation
-Install `@icedevml/react-native-host-card-emulation` package within your React Native project. Then, follow the subsections below for each platform that you need to support.
+Install this package within your React Native project:
+
+```
+yarn add @icedevml/react-native-host-card-emulation
+```
+or using npm
+```
+npm install --save @icedevml/react-native-host-card-emulation
+```
+
+Afterwards, follow the subsections below for each platform that you need to support.
 
 ### iOS
 1. Make sure to set up a proper signing team and bundle identifier in "Signing & Capabilities" configuration section of your project.
@@ -54,7 +64,8 @@ Install `@icedevml/react-native-host-card-emulation` package within your React N
       ...
 
    +  <uses-permission android:name="android.permission.NFC" />
-   +  <uses-feature android:name="android.hardware.nfc.hce" android:required="true" />
+   +  <!-- set required="true" if your app would be entirely useless on devices without HCE support -->
+   +  <uses-feature android:name="android.hardware.nfc.hce" android:required="false" />
 
       ...
 
@@ -68,7 +79,7 @@ Install `@icedevml/react-native-host-card-emulation` package within your React N
    +      android:name="com.itsecrnd.rtnhceandroid.HCEService"
    +      android:exported="true"
    +      android:enabled="true"
-   +      android:permission="android.permission.BIND_NFC_SERVICE" >
+   +      android:permission="android.permission.BIND_NFC_SERVICE">
    +      <intent-filter>
    +        <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />
    +        <category android:name="android.intent.category.DEFAULT"/>
@@ -100,19 +111,35 @@ Install `@icedevml/react-native-host-card-emulation` package within your React N
 
 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):
+> [!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.
+
+> [!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.
+
+### Quick start guide
+
+1. Subscribe to the event stream. There is a single global event stream, so you can subscribe early and remain subscribed to events for the entire application's lifetime.
    ```typescript
-   NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
-       switch (event.type) {
-           /* ... your handler here ... */
+   useEffect(() => {
+       const subscription = NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
+           switch (event.type) {
+               /* ... implement event handlers here ... */
+           }
+       });
+
+       // cleanup the event listener when the effect is unmounted
+       return () => {
+           subscription.remove();
        }
-   });
+   }, []);
    ```
-2. When user indicates that he wants to perform the HCE action, call the following function from the button's onClick routine:
+2. When user indicates that he/she 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:
+   This will emit `sessionStarted` event right after the function call, on both iOS and Android platforms. After the session is started, you can decide to start HCE emulation right away in the event handler:
    ```typescript
    // inside NativeHCEModule?.onEvent handler's switch
    case 'sessionStarted':
@@ -120,10 +147,10 @@ This module provides a uniform low-level HCE API for both mobile platforms.
        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.
+   Calling `await NativeHCEModule?.startHCE()` causes:
+   * iOS: Your smartphone will start listening for C-APDUs (Command APDUs originating from reader devices) right after that function is called, which will be additionally indicated by the operating system popping out the NFC scanning user interface prompt.
+   * Android: HCE commands will be forwarded to your application from that point on. No specific user interface is displayed (you have to implement it on your own, within your app).
+3. Optionally, you can handle `readerDetected` and `readerDeselected` events to enhance user's experience.
    ```typescript
    // inside NativeHCEModule?.onEvent handler's switch
    case 'readerDetected':
@@ -134,29 +161,86 @@ This module provides a uniform low-level HCE API for both mobile platforms.
         NativeHCEModule?.setSessionAlertMessage('Lost reader');  // only for iOS, no-op in Android
         break;
    ```
-5. Handle CAPDU
+   For those events, trigger mechanisms are platform dependent:
+   * iOS: The `readerDetected` event will be emitted as soon as the NFC reader's 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: 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. Receive incoming C-APDU and respond to it:
    ```typescript
    // inside NativeHCEModule?.onEvent handler's switch
    case 'received':
-       NativeHCEModule?.setSessionAlertMessage('Keep holding the tag');
+       NativeHCEModule?.setSessionAlertMessage('Keep holding the tag');  // only for iOS, no-op on Android
 
+       // decode incoming C-APDU to bytes
        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
+       // for the demo purposes, we always want to respond with [0x0A] + status code 0x9000 (success)
        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:
+   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.
+
+### iOS: Acquiring exclusive NFC access
+
+If you need to utilize `NFCPresentmentIntentAssertion` for enhanced user experience, call:
+```typescript
+NativeHCEModule?.acquireExclusiveNFC();
+```
+This function will acquire an exclusive NFC access for 15 seconds. On system services or other applications will be able to interfere with NFC during that period. For example, the NFC background tag reading will be disabled so it would not generate any distracting notifications.
+
+This function will throw an exception if:
+* the presentment intent assertion was already acquired and is still active;
+* you are in the cooldown period where you are not allowed to acquire the presentment intent assertion (cooldown is 15 seconds after the previous assertion had expired);
+* the feature is not supported or the device is not eligible for whatever reason;
+
+Call `NativeHCEModule?.isExclusiveNFC()` to check if exclusive NFC access is still active.
+
+### Android: Handle HCE calls when the app is not running
+
+Exclusively on Android platform it is possible to handle Host Card Emulation even when the app is not running in foreground.
+In such case, no user interface will be available, the handler will run in headless mode. This is still extremely useful in certain cases,
+for instance - your app may emulate an NDEF tag even when it's not launched on the foreground.
+
+1. Register `handleBackgroundHCECall` headless task in your app's `index.js`:
    ```typescript
-   NativeHCEModule?.acquireExclusiveNFC();
+   AppRegistry.registerHeadlessTask('handleBackgroundHCECall', () => {
+      return async () => {
+         return await runBackground();
+      }
+   });
+   ```
+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) => {
+         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();
+       break;
+   ```
+4. Implement the actual APDU handler that will process the C-APDU and generate a response.
+   ```typescript
+   case 'received':
+       // decode incoming C-APDU to bytes
+       const capdu = Buffer.from(event.arg!, 'hex');
+       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"));
+       break;
    ```
-   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.
+### More resources
 
-> [!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.
+* [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)

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

@@ -1,107 +1,235 @@
+/*
+ * Some of the code inspired by:
+ * https://github.com/appidea/react-native-hce
+ * https://github.com/transistorsoft/react-native-background-fetch
+ */
+
 package com.itsecrnd.rtnhceandroid;
 
-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 static com.facebook.react.jstasks.HeadlessJsTaskContext.Companion;
 
-import android.content.BroadcastReceiver;
+import android.app.ActivityManager;
 import android.content.Context;
-import android.content.Intent;
-import android.content.IntentFilter;
 import android.nfc.cardemulation.HostApduService;
 import android.os.Build;
 import android.os.Bundle;
 import android.util.Log;
 
+import androidx.annotation.NonNull;
 import androidx.annotation.RequiresApi;
 
+import com.facebook.react.ReactApplication;
+import com.facebook.react.ReactHost;
+import com.facebook.react.ReactInstanceEventListener;
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.ReactContext;
+import com.facebook.react.bridge.UiThreadUtil;
+import com.facebook.react.jstasks.HeadlessJsTaskConfig;
+import com.facebook.react.jstasks.HeadlessJsTaskContext;
+import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
+
+import java.util.List;
 import java.util.Locale;
 
-import javax.crypto.SecretKey;
-import javax.crypto.spec.SecretKeySpec;
-
 @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
-public class HCEService extends HostApduService {
+public class HCEService extends HostApduService implements ReactInstanceEventListener, HCEServiceCallback {
     private static final String TAG = "HCEService";
 
-    private SecretKey encSecretKey;
-
-    private final BroadcastReceiver receiver = new BroadcastReceiver() {
-        @Override
-        public void onReceive(Context context, Intent intent) {
-            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);
+    private boolean isForeground;
+    private RTNHCEAndroidModule hceModule;
+    private byte[] pendingCAPDU;
+    private volatile boolean needsResponse;
+
+    private boolean isAppOnForeground(Context context) {
+        /*
+         We need to check if app is in foreground otherwise the app will crash.
+         https://stackoverflow.com/questions/8489993/check-android-application-is-in-foreground-or-not
+         */
+        ActivityManager activityManager = (ActivityManager) context.getSystemService(Context.ACTIVITY_SERVICE);
+        List<ActivityManager.RunningAppProcessInfo> appProcesses =
+                activityManager.getRunningAppProcesses();
+        if (appProcesses == null) {
+            return false;
+        }
+        final String packageName = context.getPackageName();
+        for (ActivityManager.RunningAppProcessInfo appProcess : appProcesses) {
+            if (appProcess.importance ==
+                    ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND &&
+                    appProcess.processName.equals(packageName)) {
+                return true;
             }
         }
-    };
+        return false;
+    }
+
+    @Override
+    public void onBackgroundHCEInit() {
+        Log.d(TAG, "HCEService:onBackgroundHCEInit");
+
+        if (pendingCAPDU != null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit send pendingCAPDU");
+            hceModule.sendBackgroundEvent("received", BinaryUtils.ByteArrayToHexString(pendingCAPDU));
+            pendingCAPDU = null;
+        }
+    }
 
     @Override
-    public byte[] processCommandApdu(byte[] command, Bundle extras) {
-        String capdu = AESGCMUtil.encryptData(encSecretKey, BinaryUtils.ByteArrayToHexString(command));
+    public void onRespondAPDU(String rapdu) {
+        Log.d(TAG, "HCEService:onRespondAPDU");
+
+        if (!needsResponse) {
+            Log.d(TAG, "HCEService:onRespondAPDU not waiting for a response");
+            throw new IllegalStateException();
+        }
+
+        needsResponse = false;
+        sendResponseApdu(BinaryUtils.HexStringToByteArray(rapdu));
+    }
 
-        Intent intent = new Intent(ACTION_RECEIVE_C_APDU);
-        intent.setPackage(getApplicationContext().getPackageName());
-        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
-        intent.putExtra(KEY_CAPDU, capdu);
-        getApplicationContext().sendBroadcast(intent);
+    @Override
+    public byte[] processCommandApdu(byte[] command, Bundle extras) {
+        Log.d(TAG, "HCEService:processCommandApdu");
+        String capdu = BinaryUtils.ByteArrayToHexString(command).toUpperCase(Locale.ROOT);
+
+        if (isForeground) {
+            if (hceModule._isHCERunning() && !hceModule.isHCEBrokenConnection()) {
+                Log.d(TAG, "HCEService:processCommandApdu foreground sendEvent received");
+                needsResponse = true;
+                hceModule.sendEvent("received", capdu);
+            } else {
+                Log.d(TAG, "HCEService:processCommandApdu foreground respond 6999");
+                return new byte[] { (byte) 0x69, (byte) 0x99 };
+            }
+        } else {
+            if (hceModule != null && hceModule.isHCEBackgroundHandlerReady()) {
+                Log.d(TAG, "HCEService:processCommandApdu background sendBackgroundEvent received");
+                needsResponse = true;
+                hceModule.sendBackgroundEvent("received", capdu);
+            } else {
+                Log.d(TAG, "HCEService:processCommandApdu background pendingCAPDU");
+                needsResponse = true;
+                pendingCAPDU = command;
+            }
+        }
 
         return null;
     }
 
     @Override
     public void onCreate() {
-        Log.d(TAG, "HCEService onCreate");
+        Log.d(TAG, "HCEService:onCreate");
 
-        String prefsName = getApplicationContext().getPackageName() + ".nativehcemodule";
-        String encKey = getApplicationContext()
-                .getSharedPreferences(prefsName, Context.MODE_PRIVATE)
-                .getString("encKey", "");
+        ReactHost reactHost = ((ReactApplication) getApplication()).getReactHost();
 
-        if (encKey.isEmpty()) {
-            throw new RuntimeException("Failed to load encKey.");
+        if (reactHost == null) {
+            throw new RuntimeException("BUG! getReactHost() returned null.");
         }
 
-        byte[] bArr = BinaryUtils.HexStringToByteArray(encKey);
-        encSecretKey = new SecretKeySpec(bArr, 0, bArr.length, "AES");
+        isForeground = isAppOnForeground(getApplicationContext());
+        pendingCAPDU = null;
+        hceModule = null;
+        needsResponse = false;
 
-        /*
-         * 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);
+        if (isForeground) {
+            Log.d(TAG, "HCEService:onCreate foreground");
+
+            ReactContext reactContext = reactHost.getCurrentReactContext();
+
+            if (reactContext == null) {
+                throw new RuntimeException("BUG! getCurrentReactContext() returned null in foreground.");
+            }
+
+            this.hceModule = ((RTNHCEAndroidModule) reactContext.getNativeModule("NativeHCEModule"));
+
+            if (this.hceModule == null) {
+                throw new RuntimeException("BUG! getNativeModule() returned null in foreground.");
+            }
+
+            this.hceModule.setHCEService(this);
+
+            if (this.hceModule._isHCERunning()) {
+                this.hceModule.sendEvent("readerDetected", "");
+            } else {
+                this.hceModule.setHCEBrokenConnection();
+            }
+        } else {
+            ReactContext reactContext = reactHost.getCurrentReactContext();
+            Log.d(TAG, "HCEService:onCreate background");
+
+            if (reactContext == null) {
+                reactHost.addReactInstanceEventListener(this);
+                reactHost.start();
+            } else {
+                setupRunJSTask(reactContext);
+            }
+        }
     }
 
     @Override
     public void onDeactivated(int reason) {
-        Log.d(TAG, "HCEService onDeactivated: " + reason);
+        Log.d(TAG, "HCEService:onDeactivated: " + reason);
+        needsResponse = false;
 
-        getApplicationContext().unregisterReceiver(receiver);
+        if (isForeground) {
+            if (this.hceModule != null && !this.hceModule.isHCEBrokenConnection()) {
+                this.hceModule.sendEvent("readerDeselected", "");
+            }
+        } else {
+            this.hceModule.sendBackgroundEvent("readerDeselected", "");
+        }
+
+        if (this.hceModule != null) {
+            this.hceModule.setHCEService(null);
+        }
+    }
+
+    @Override
+    public void onReactContextInitialized(@NonNull ReactContext reactContext) {
+        HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
+        headlessJsTaskContext.addTaskEventListener(new HeadlessJsTaskEventListener() {
+            @Override
+            public void onHeadlessJsTaskStart(int i) {
+                Log.d(TAG, "HCEService:HeadlessJsTaskEventListener:onHeadlessJsTaskStart: " + i);
+            }
+
+            @Override
+            public void onHeadlessJsTaskFinish(int i) {
+                Log.d(TAG, "HCEService:HeadlessJsTaskEventListener:onHeadlessJsTaskFinish: " + i);
+            }
+        });
+
+        setupRunJSTask(reactContext);
+    }
+
+    public void setupRunJSTask(@NonNull ReactContext reactContext) {
+        hceModule = (RTNHCEAndroidModule) reactContext.getNativeModule("NativeHCEModule");
+
+        if (hceModule == null) {
+            throw new RuntimeException("BUG! getNativeModule() returned null in background.");
+        }
+
+        hceModule.setHCEService(this);
+
+        UiThreadUtil.runOnUiThread(new Runnable() {
+            @Override
+            public void run() {
+                Log.d(TAG, "HCEService:setupRunJSTask:runOnUiThread startTask");
+                HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
+                headlessJsTaskContext.startTask(
+                        new HeadlessJsTaskConfig(
+                                "handleBackgroundHCECall",
+                                Arguments.fromBundle(new Bundle()),
+                                15000,
+                                false // not allowed in foreground
+                        ));
+            }
+        });
+    }
+
+    @Override
+    public void onDestroy() {
+        super.onDestroy();
 
-        Intent intent = new Intent(ACTION_READER_LOST);
-        intent.setPackage(getApplicationContext().getPackageName());
-        intent.putExtra(KEY_AUTH, AESGCMUtil.encryptData(encSecretKey, AESGCMUtil.randomString()));
-        getApplicationContext().sendBroadcast(intent);
+        Log.d(TAG, "HCEService:onDestroy");
     }
 }

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

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

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

@@ -1,16 +1,5 @@
 package com.itsecrnd.rtnhceandroid;
 
-import static android.content.Context.RECEIVER_EXPORTED;
-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;
@@ -23,137 +12,118 @@ import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.WritableMap;
 
-import javax.crypto.SecretKey;
-
-@RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
 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 volatile boolean hceBrokenConnection;
 
-    private void sendEvent(final String type, final String arg) {
-        WritableMap map = Arguments.createMap();
-        map.putString("type", type);
-        map.putString("arg", arg);
-        emitOnEvent(map);
-    }
+    private volatile boolean hceBackgroundReady;
 
-    private final BroadcastReceiver receiver = new BroadcastReceiver() {
-        @Override
-        public void onReceive(Context context, Intent intent) {
-            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);
-            }
-        }
-    };
+    private HCEServiceCallback serviceCb;
 
     RTNHCEAndroidModule(ReactApplicationContext context) {
         super(context);
-        String encKey;
+
+        this.serviceCb = null;
+
         this.sessionRunning = false;
         this.hceRunning = false;
-        this.hceBreakConnection = false;
         this.hceDeselected = true;
-
-        try {
-            encSecretKey = AESGCMUtil.generateKey();
-            encKey = BinaryUtils.ByteArrayToHexString(encSecretKey.getEncoded());
-        } catch (Exception e) {
-            throw new RuntimeException("Failed to generate encryption key.", e);
-        }
-
-        String prefsName = getReactApplicationContext().getPackageName() + ".nativehcemodule";
-        getReactApplicationContext()
-                .getSharedPreferences(prefsName, Context.MODE_PRIVATE)
-                .edit()
-                .putString("encKey", encKey)
-                .commit();
-
-        IntentFilter filter = new IntentFilter();
-        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.
-         * This happens even though those things are within the same application and package.
-         * It also seems like there is no way to bind HostApduService (or it's a skill issue).
-         *
-         * For now we will just encrypt&authenticate all messages using AES/GCM and use exported
-         * receivers. This is not a perfect solution but it is going to be secure and sufficient for now.
-         *
-         * If somebody knows a better way then any pull requests would be greatly appreciated.
-         */
-        getReactApplicationContext().getApplicationContext().registerReceiver(receiver, filter, RECEIVER_EXPORTED);
+        this.hceBrokenConnection = false;
+        this.hceBackgroundReady = false;
     }
 
     @Override
     public void invalidate() {
-        getReactApplicationContext().getApplicationContext().unregisterReceiver(receiver);
+        Log.d(TAG, "RTNHCEAndroidModule:invalidate");
     }
 
     @Override
     @NonNull
     public String getName() {
+        Log.d(TAG, "RTNHCEAndroidModule:getName");
         return RTNHCEAndroidModule.NAME;
     }
 
+    void sendEvent(final String type, final String arg) {
+        Log.d(TAG, "RTNHCEAndroidModule:sendEvent");
+        WritableMap map = Arguments.createMap();
+        map.putString("type", type);
+        map.putString("arg", arg);
+        emitOnEvent(map);
+    }
+
+    void sendBackgroundEvent(final String type, final String arg) {
+        Log.d(TAG, "RTNHCEAndroidModule:sendBackgroundEvent");
+        WritableMap map = Arguments.createMap();
+        map.putString("type", type);
+        map.putString("arg", arg);
+        emitOnBackgroundEvent(map);
+    }
+
+    boolean _isHCERunning() {
+        return this.hceRunning;
+    }
+
+    void setHCEBrokenConnection() {
+        this.hceBrokenConnection = true;
+    }
+
+    boolean isHCEBackgroundHandlerReady() {
+        return this.hceBackgroundReady;
+    }
+
+    boolean isHCEBrokenConnection() {
+        return this.hceBrokenConnection;
+    }
+
+    void setHCEService(HCEServiceCallback serviceCallback) {
+        Log.d(TAG, "RTNHCEAndroidModule:setHCEService");
+
+        this.serviceCb = serviceCallback;
+        this.hceDeselected = true;
+        this.hceBackgroundReady = false;
+        this.hceBrokenConnection = false;
+    }
+
     @Override
     public boolean isPlatformSupported() {
+        Log.d(TAG, "RTNHCEAndroidModule:isPlatformSupported");
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            return false;
+        }
+
         PackageManager pm = getReactApplicationContext().getPackageManager();
         return pm.hasSystemFeature(PackageManager.FEATURE_NFC)
-            && pm.hasSystemFeature(PackageManager.FEATURE_NFC_HOST_CARD_EMULATION);
+                && pm.hasSystemFeature(PackageManager.FEATURE_NFC_HOST_CARD_EMULATION);
     }
 
     @Override
     public void acquireExclusiveNFC(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:acquireExclusiveNFC");
         promise.reject("err_platform_unsupported", "acquireExclusiveNFC() is not supported on Android.");
     }
 
     @Override
     public boolean isExclusiveNFC() {
+        Log.d(TAG, "RTNHCEAndroidModule:isExclusiveNFC");
         // unsupported on Android, always false
         return false;
     }
 
     @Override
     public void beginSession(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:beginSession");
+
+        if (!isPlatformSupported()) {
+            promise.reject("err_platform_unsupported", "Unsupported Android version or missing NFC/HCE feature.");
+            return;
+        }
+
         if (!this.sessionRunning) {
             this.sessionRunning = true;
             sendEvent("sessionStarted", "");
@@ -165,41 +135,70 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public void setSessionAlertMessage(String message) {
+        Log.d(TAG, "RTNHCEAndroidModule:setSessionAlertMessage");
         // unsupported on Android, no-op
     }
 
     @Override
     public void invalidateSession() {
+        Log.d(TAG, "RTNHCEAndroidModule:invalidateSession");
         if (this.sessionRunning) {
+            this.hceRunning = false;
             this.sessionRunning = false;
+            this.hceBrokenConnection = true;
             sendEvent("sessionInvalidated", "userInvalidated");
         }
     }
 
     @Override
     public boolean isSessionRunning() {
+        Log.d(TAG, "RTNHCEAndroidModule:isSessionRunning");
         return this.sessionRunning;
     }
 
+    @Override
+    public void initBackgroundHCE(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:initBackgroundHCE");
+
+        this.hceBackgroundReady = true;
+
+        promise.resolve(null);
+
+        this.serviceCb.onBackgroundHCEInit();
+    }
+
     @Override
     public void startHCE(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:startHCE");
+        if (!this.sessionRunning) {
+            promise.reject("err_no_session", "No session is active.");
+            return;
+        }
+
         if (this.hceRunning) {
             promise.reject("err_start_emulation", "Error trying to start emulation. Emulation already started.");
             return;
         }
 
         this.hceRunning = true;
+        this.hceBrokenConnection = false;
         promise.resolve(null);
     }
 
     @Override
     public void stopHCE(String status, Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:stopHCE");
+        if (!this.sessionRunning) {
+            promise.reject("err_no_session", "No session is active.");
+            return;
+        }
+
         if (this.hceRunning) {
             this.hceRunning = false;
 
             if (!this.hceDeselected) {
                 this.hceDeselected = true;
-                this.hceBreakConnection = true;
+                this.hceBrokenConnection = true;
                 sendEvent("readerDeselected", "");
             }
         }
@@ -207,22 +206,36 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         promise.resolve(null);
     }
 
+    @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
     @Override
     public void respondAPDU(String rapdu, Promise promise) {
-        String encRapdu = AESGCMUtil.encryptData(encSecretKey, rapdu);
+        Log.d(TAG, "RTNHCEAndroidModule:respondAPDU");
+
+        if (!this.hceBackgroundReady) {
+            if (!this.sessionRunning) {
+                promise.reject("err_no_session", "No session is active.");
+                return;
+            } else if (!this.hceRunning) {
+                promise.reject("err_no_hce", "HCE is not running.");
+                return;
+            }
+        }
 
-        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);
+        Log.d(TAG, "respondAPDU(): Send to service");
+
+        try {
+            serviceCb.onRespondAPDU(rapdu);
+        } catch (IllegalStateException e) {
+            promise.reject("err_no_capdu", "There is no C-APDU to respond to at the time.");
+            return;
+        }
 
         promise.resolve(null);
     }
 
     @Override
     public void isHCERunning(Promise promise) {
-        // unsupported on Android, always true
-        promise.resolve(true);
+        Log.d(TAG, "RTNHCEAndroidModule:isHCERunning");
+        promise.resolve(this.hceRunning);
     }
 }

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

@@ -1,9 +1,6 @@
 package com.itsecrnd.rtnhceandroid;
 
-import android.os.Build;
-
 import androidx.annotation.Nullable;
-import androidx.annotation.RequiresApi;
 
 import com.facebook.react.TurboReactPackage;
 import com.facebook.react.bridge.NativeModule;
@@ -14,7 +11,6 @@ import com.facebook.react.module.model.ReactModuleInfoProvider;
 import java.util.HashMap;
 import java.util.Map;
 
-@RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
 public class RTNHCEAndroidPackage extends TurboReactPackage {
     @Nullable
     @Override

package/ios/RTNHCEModuleIOS.mm

@@ -86,6 +86,10 @@
     }
 }
 
+- (void)initBackgroundHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
+    reject(@"err_platform_unsupported", @"Background HCE is not supported on iOS.", nil);
+}
+
 - (void)startHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
     if (@available(iOS 17.4, *)) {
         return [hcemoduleios startHCEWithResolve:resolve reject:reject];

package/ios/RTNHCEModuleIOSImpl.swift

@@ -13,13 +13,8 @@ extension StringProtocol {
 }
 
 extension Data {
-  struct HexEncodingOptions: OptionSet {
-    let rawValue: Int
-    static let upperCase = HexEncodingOptions(rawValue: 1 << 0)
-  }
-
-  func hexEncodedString(options: HexEncodingOptions = []) -> String {
-    let format = options.contains(.upperCase) ? "%02hhX" : "%02hhx"
+  func hexEncodedString() -> String {
+    let format = "%02hhX"
     return map { String(format: format, $0) }.joined()
   }
 }

package/js/NativeHCEModule.ts

@@ -1,7 +1,8 @@
 import type {TurboModule, CodegenTypes} from 'react-native';
 import {TurboModuleRegistry} from 'react-native';
 
-export type HCEModuleEventType = 'sessionStarted'
+export type HCEModuleEventType =
+    'sessionStarted'
     | 'sessionInvalidated'
     /**
      * iOS: Whether the reader field was detected.
@@ -19,11 +20,20 @@ export type HCEModuleEventType = 'sessionStarted'
     | 'received';
 export type HCEModuleStopReason = 'success' | 'failure';
 
+export type HCEModuleBackgroundEventType =
+    'readerDeselected'
+    | 'received';
+
 export type HCEModuleEvent = {
   type: HCEModuleEventType
   arg: string | null,
 }
 
+export type HCEModuleBackgroundEvent = {
+  type: HCEModuleBackgroundEventType
+  arg: string | null,
+}
+
 export interface Spec extends TurboModule {
   /**
    * Checks if a given smartphone supports required HCE features.
@@ -63,6 +73,8 @@ export interface Spec extends TurboModule {
    */
   isSessionRunning(): boolean;
 
+  initBackgroundHCE(): Promise<void>;
+
   /**
    * iOS: Start the card emulation.
    * Android: Enable HCE service.
@@ -84,6 +96,7 @@ export interface Spec extends TurboModule {
   isHCERunning(): Promise<boolean>;
 
   readonly onEvent: CodegenTypes.EventEmitter<HCEModuleEvent>;
+  readonly onBackgroundEvent: CodegenTypes.EventEmitter<HCEModuleBackgroundEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>(

package/package.json

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

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

@@ -1,89 +0,0 @@
-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;
-import javax.crypto.KeyGenerator;
-import javax.crypto.NoSuchPaddingException;
-import javax.crypto.SecretKey;
-import javax.crypto.spec.GCMParameterSpec;
-
-@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 {
-            keyGen = KeyGenerator.getInstance("AES");
-        } catch (NoSuchAlgorithmException e) {
-            throw new RuntimeException("Failed to get AES algorithm.", e);
-        }
-        keyGen.init(256);
-        return keyGen.generateKey();
-    }
-
-    public static String encryptData(SecretKey key, String plaintext) {
-        try {
-            byte[] iv = new byte[32];
-            new SecureRandom().nextBytes(iv);
-
-            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
-            GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(128, iv);
-            cipher.init(Cipher.ENCRYPT_MODE, key, gcmParameterSpec);
-
-            byte[] plaintextBytes = plaintext.getBytes(StandardCharsets.UTF_8);
-            byte[] ciphertextBytes = cipher.doFinal(plaintextBytes);
-
-            return Base64.getEncoder().encodeToString(iv) + ';' +
-                    Base64.getEncoder().encodeToString(ciphertextBytes);
-        } catch (NoSuchPaddingException
-                 | NoSuchAlgorithmException
-                 | IllegalBlockSizeException
-                 | InvalidAlgorithmParameterException
-                 | BadPaddingException
-                 | InvalidKeyException e) {
-            throw new RuntimeException("Crypto error.", e);
-        }
-    }
-
-    public static String decryptData(SecretKey key, String ciphertext) {
-        try {
-            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
-            String[] parts = ciphertext.split(";");
-
-            if (parts.length != 2) {
-                throw new IllegalArgumentException("Invalid ciphertext parameter.");
-            }
-
-            byte[] iv = Base64.getDecoder().decode(parts[0]);
-            byte[] ciphertextBytes = Base64.getDecoder().decode(parts[1]);
-
-            GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(128, iv);
-            cipher.init(Cipher.DECRYPT_MODE, key, gcmParameterSpec);
-
-            byte[] plaintextBytes = cipher.doFinal(ciphertextBytes);
-            return new String(plaintextBytes, StandardCharsets.UTF_8);
-        } catch (NoSuchPaddingException
-                 | IllegalBlockSizeException
-                 | InvalidAlgorithmParameterException
-                 | BadPaddingException
-                 | InvalidKeyException
-                 | NoSuchAlgorithmException e) {
-            throw new RuntimeException("Crypto error.", e);
-        }
-    }
-}

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

@@ -1,11 +0,0 @@
-package com.itsecrnd.rtnhceandroid;
-
-public class IntentKeys {
-    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";
-}