@icedevml/react-native-host-card-emulation 0.8.1 → 0.9.0

package/README.md

@@ -25,7 +25,8 @@ Make sure that your project has it enabled. Note that the New Architecture is en
 5. Wait until the entitlement is approved by Apple.
 
 ### Android
-*(no prerequisite steps are required for Android)*
+1. Ensure that your app's `minSdkVersion` is at least 24 (Android 7.0). This is the floor imposed by React Native's New Architecture; the Host Card Emulation APIs used by this package are available since Android 5.1.
+2. Note that HCE availability also depends on the device hardware - always check `isPlatformSupported()` before starting a session.
 
 ## Installation
 Install this package within your React Native project:
@@ -101,7 +102,8 @@ Afterwards, follow the subsections below for each platform that you need to supp
    ```xml
    <host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
      android:description="@string/app_name"
-     android:requireDeviceUnlock="false">
+     android:requireDeviceUnlock="false"
+     android:requireDeviceScreenOn="true">
      <aid-group android:category="other"
        android:description="@string/app_name">
        <aid-filter android:name="F001020304" />
@@ -112,6 +114,13 @@ Afterwards, follow the subsections below for each platform that you need to supp
    ```
    Replace `F001020304`, `F00102030405`, `F0010203040506` with the ISO7816 AIDs that you want to support.
 
+   Keep `android:requireDeviceUnlock` set to `false` in any scenario, this is the way to avoid having system prompts
+   displayed by Android whenever the app is interacted with when the phone is locked. On the JavaScript/TypeScript side,
+   you will receive `deviceLocked`/`deviceUnlocked` events that will let you decide whether you want to allow the NFC
+   interaction or not.
+
+   For `android:requireDeviceScreenOn` - set it according to your use case.
+
 ## API Specification & Demo App
 
 This module provides a uniform low-level HCE API for both mobile platforms.
@@ -169,6 +178,20 @@ This module provides a uniform low-level HCE API for both mobile platforms.
    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.
+
+   The device lock state is reported through the `deviceLocked` and `deviceUnlocked` events, which are the only source of truth about it. One of them is always emitted before the `received` event of the first C-APDU of a session, so the state is known upfront.
+   ```typescript
+   case 'deviceLocked':
+       setDeviceLocked(true);
+       break;
+
+   case 'deviceUnlocked':
+       setDeviceLocked(false);
+       break;
+   ```
+   For the lock state events, trigger mechanisms are platform dependent:
+   * iOS: The event is always `deviceUnlocked` - it's impossible to communicate over HCE while the device is locked, so the state cannot change during a session.
+   * Android: The state is re-sampled whenever a C-APDU arrives and, if it differs from the one reported so far, the corresponding event is emitted straight before the `received` event of that C-APDU. C-APDUs are always forwarded - it is up to you to decide how to treat a locked device.
 4. Receive incoming C-APDU and respond to it:
    ```typescript
    // inside NativeHCEModule.onEvent handler's switch
@@ -232,14 +255,15 @@ 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';
+   import { BackgroundHCETaskData, createBackgroundHCE } from '@icedevml/react-native-host-card-emulation/js/hceBackground';
 
    AppRegistry.registerHeadlessTask('handleBackgroundHCECall', () => {
-      return async (taskData) => {
-         return await runBackgroundHCETask(createBackgroundHCE(taskData.handle));
+      return async (taskData: BackgroundHCETaskData) => {
+         return await runBackgroundHCETask(createBackgroundHCE(taskData));
       }
    });
    ```
+   Pass the whole `taskData` object to `createBackgroundHCE()`, so that it could be handed over to your event handler as its third argument. The device lock state is reported to your handler as `deviceLocked` and `deviceUnlocked` events: always before the `received` event of the first C-APDU of a session, and then again straight before the `received` event of any C-APDU during which a change of that state was noticed. C-APDUs are always forwarded - it is up to you to decide how to treat a locked device.
 2. Implement your background HCE handler by passing an event callback to `processBackgroundHCE()`:
    ```typescript
    import { Buffer } from 'buffer/';
@@ -250,7 +274,7 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
    export default async function runBackgroundHCETask(processBackgroundHCE: ProcessBackgroundHCEFunc) {
       // ... initialize any state keeping variables here ...
 
-      processBackgroundHCE(async (event, respondAPDU) => {
+      processBackgroundHCE(async (event, respondAPDU, taskData) => {
          switch (event.type) {
             /* ... background HCE event handler here ... */
          }

package/android/build.gradle

@@ -17,6 +17,12 @@ apply plugin: 'com.facebook.react'
 android {
     compileSdkVersion safeExtGet('compileSdkVersion', 33)
     namespace "com.itsecrnd.rtnhceandroid"
+
+    defaultConfig {
+        // API 24 is the floor imposed by React Native's New Architecture,
+        // the HCE APIs used here are available since API 22.
+        minSdkVersion safeExtGet('minSdkVersion', 24)
+    }
 }
 
 repositories {

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

@@ -9,6 +9,7 @@ package com.itsecrnd.rtnhceandroid;
 import static com.facebook.react.jstasks.HeadlessJsTaskContext.Companion;
 
 import android.app.ActivityManager;
+import android.app.KeyguardManager;
 import android.content.Context;
 import android.nfc.cardemulation.HostApduService;
 import android.os.Build;
@@ -32,15 +33,18 @@ import java.util.List;
 import java.util.Locale;
 import java.util.UUID;
 
-@RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
+@RequiresApi(api = Build.VERSION_CODES.N)
 public class HCEService extends HostApduService implements HCEServiceCallback {
     private static final String TAG = "HCEService";
 
     private boolean isForeground;
+    private volatile boolean isDeactivated;
     private String backgroundSessionUUID;
     private RTNHCEAndroidModule hceModule;
     private byte[] pendingCAPDU;
     private volatile boolean needsResponse;
+    private volatile Boolean reportedDeviceLocked;
+    private Boolean pendingDeviceLocked;
     private final HashMap<String, Integer> taskSessionIdMap;
 
     public HCEService() {
@@ -49,6 +53,31 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
         taskSessionIdMap = new HashMap<>();
     }
 
+    private boolean isDeviceLocked() {
+        /*
+         The KeyguardManager has to be obtained lazily, as the service's context
+         is not yet attached when the instance is being constructed.
+         */
+        KeyguardManager keyguardManager = (KeyguardManager) getSystemService(Context.KEYGUARD_SERVICE);
+        return keyguardManager != null && keyguardManager.isDeviceLocked();
+    }
+
+    private void reportDeviceLockState(boolean deviceLocked) {
+        if (reportedDeviceLocked != null && reportedDeviceLocked == deviceLocked) {
+            return;
+        }
+
+        reportedDeviceLocked = deviceLocked;
+        final String type = deviceLocked ? "deviceLocked" : "deviceUnlocked";
+        Log.d(TAG, "HCEService:reportDeviceLockState " + type);
+
+        if (isForeground) {
+            hceModule.sendEvent(type, "");
+        } else {
+            hceModule.sendBackgroundEvent(backgroundSessionUUID, type, "");
+        }
+    }
+
     private boolean isAppOnForeground(Context context) {
         /*
          We need to check if app is in foreground otherwise the app will crash.
@@ -86,6 +115,12 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
 
         if (pendingCAPDU != null) {
             Log.d(TAG, "HCEService:onBackgroundHCEInit send pendingCAPDU");
+
+            if (pendingDeviceLocked != null) {
+                reportDeviceLockState(pendingDeviceLocked);
+                pendingDeviceLocked = null;
+            }
+
             hceModule.sendBackgroundEvent(backgroundSessionUUID, "received", BinaryUtils.ByteArrayToHexString(pendingCAPDU));
             pendingCAPDU = null;
         }
@@ -118,6 +153,7 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
         HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
         headlessJsTaskContext.finishTask(taskId);
         taskSessionIdMap.remove(handle);
+        stopSelf();
     }
 
     @Override
@@ -144,11 +180,17 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
     @Override
     public byte[] processCommandApdu(byte[] command, Bundle extras) {
         Log.d(TAG, "HCEService:processCommandApdu");
+
+        if (isDeactivated) {
+            onCreate();
+        }
+
         String capdu = BinaryUtils.ByteArrayToHexString(command).toUpperCase(Locale.ROOT);
 
         if (isForeground) {
             if (hceModule._isHCERunning() && hceModule.isHCEActiveConnection()) {
                 Log.d(TAG, "HCEService:processCommandApdu foreground sendEvent received");
+                reportDeviceLockState(isDeviceLocked());
                 needsResponse = true;
                 hceModule.sendEvent("received", capdu);
             } else {
@@ -158,12 +200,14 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
         } else {
             if (hceModule != null && hceModule.isHCEBackgroundHandlerReady()) {
                 Log.d(TAG, "HCEService:processCommandApdu background sendBackgroundEvent received");
+                reportDeviceLockState(isDeviceLocked());
                 needsResponse = true;
                 hceModule.sendBackgroundEvent(backgroundSessionUUID, "received", capdu);
             } else {
                 Log.d(TAG, "HCEService:processCommandApdu background pendingCAPDU");
                 needsResponse = true;
                 pendingCAPDU = command;
+                pendingDeviceLocked = isDeviceLocked();
             }
         }
 
@@ -181,9 +225,12 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
         }
 
         isForeground = isAppOnForeground(getApplicationContext());
+        isDeactivated = false;
         pendingCAPDU = null;
+        pendingDeviceLocked = null;
         hceModule = null;
         needsResponse = false;
+        reportedDeviceLocked = null;
 
         if (isForeground) {
             Log.d(TAG, "HCEService:onCreate foreground");
@@ -242,6 +289,7 @@ public class HCEService extends HostApduService implements HCEServiceCallback {
     public void onDeactivated(int reason) {
         Log.d(TAG, "HCEService:onDeactivated: " + reason);
         needsResponse = false;
+        isDeactivated = true;
 
         if (isForeground) {
             if (this.hceModule != null && this.hceModule.isHCEActiveConnection()) {

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

@@ -104,7 +104,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
     @Override
     public boolean isPlatformSupported() {
         Log.d(TAG, "RTNHCEAndroidModule:isPlatformSupported");
-        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) {
             return false;
         }
 
@@ -239,7 +239,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         promise.resolve(null);
     }
 
-    @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
+    @RequiresApi(api = Build.VERSION_CODES.N)
     @Override
     public void respondAPDU(String handle, String rapdu, Promise promise) {
         Log.d(TAG, "RTNHCEAndroidModule:respondAPDU");

package/ios/RTNHCEModuleIOSImpl.swift

@@ -25,6 +25,7 @@ extension Data {
   var cardSessionInvalidated: Bool = true
   var presentmentIntent: NFCPresentmentIntentAssertion? = nil
   var receivedCardAPDU: CardSession.APDU? = nil
+  var deviceLockStateReported: Bool = false
 
   var emitOnEvent: ((NSString, NSString?) -> ())? = nil
 
@@ -105,6 +106,7 @@ extension Data {
       }
 
       self.cardSessionInvalidated = false
+      self.deviceLockStateReported = false
       resolve(nil)
 
       do {
@@ -121,6 +123,12 @@ extension Data {
             self.emitOnEvent!("readerDeselected", "")
 
           case .received(let cardAPDU):
+            if !self.deviceLockStateReported {
+              // it's impossible to communicate over HCE while the device is locked
+              self.deviceLockStateReported = true
+              self.emitOnEvent!("deviceUnlocked", "")
+            }
+
             self.receivedCardAPDU = cardAPDU
             self.emitOnEvent!("received", NSString(string:cardAPDU.payload.hexEncodedString()))
 

package/js/NativeHCEModule.ts

@@ -18,12 +18,32 @@ export type HCEModuleEventType =
      * Received C-APDU (hex-encoded string in "arg" key) from the reader.
      * Respond by calling respondAPDU(rapdu).
      */
-    | 'received';
+    | 'received'
+    /**
+     * The device lock state, always reported before the 'received' event of the
+     * first C-APDU of a session and then again whenever it changes.
+     *
+     * iOS: Always 'deviceUnlocked' - it's impossible to communicate over HCE while
+     * the device is locked, so the state cannot change during a session.
+     * Android: The state is sampled whenever a C-APDU arrives, so a change is
+     * reported straight before the 'received' event of the C-APDU during which it
+     * was noticed.
+     */
+    | 'deviceLocked'
+    | 'deviceUnlocked';
 export type HCEModuleStopReason = 'success' | 'failure';
 
 export type HCEModuleBackgroundEventType =
     'readerDeselected'
-    | 'received';
+    | 'received'
+    /**
+     * The device lock state, always reported before the 'received' event of the
+     * first C-APDU of a session and then again whenever it changes. The state is
+     * sampled whenever a C-APDU arrives, so a change is reported straight before
+     * the 'received' event of the C-APDU during which it was noticed.
+     */
+    | 'deviceLocked'
+    | 'deviceUnlocked';
 
 export type HCEModuleEvent = {
   type: HCEModuleEventType

package/js/hceBackground.ts

@@ -1,9 +1,21 @@
 import NativeHCEModule, {HCEModuleBackgroundEvent} from "./NativeHCEModule";
 
+/**
+ * Android: Data passed by the native side to the 'handleBackgroundHCECall' headless task.
+ * Pass it as-is to createBackgroundHCE().
+ */
+export interface BackgroundHCETaskData {
+    /**
+     * Handle of the background HCE session.
+     */
+    handle: string,
+}
+
 export interface BackgroundEventHandler {
     (
         event: HCEModuleBackgroundEvent,
         respondAPDU: (rapdu: string) => Promise<void>,
+        taskData: BackgroundHCETaskData,
     ): Promise<void>
 }
 
@@ -13,7 +25,18 @@ export interface ProcessBackgroundHCEFunc {
     ): void
 }
 
-export const createBackgroundHCE = (handle: string) => {
+/**
+ * Set up handling of a background HCE session.
+ *
+ * @param taskData Data received by the 'handleBackgroundHCECall' headless task. A bare handle
+ *                 string is accepted as well, for backwards compatibility.
+ */
+export const createBackgroundHCE = (taskData: BackgroundHCETaskData | string): ProcessBackgroundHCEFunc => {
+    const useTaskData: BackgroundHCETaskData = typeof taskData === "string"
+        ? {handle: taskData}
+        : taskData;
+    const handle = useTaskData.handle;
+
     const respondAPDU = (rapdu: string) => {
         return NativeHCEModule.respondAPDU(handle, rapdu);
     }
@@ -26,7 +49,7 @@ export const createBackgroundHCE = (handle: string) => {
             }
 
             try {
-                await handler(event, respondAPDU);
+                await handler(event, respondAPDU, useTaskData);
             } catch (e) {
                 throw e;
             } finally {

package/package.json

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