@icedevml/react-native-host-card-emulation 0.9.2 → 1.0.0

package/js/NativeHCEModule.ts

@@ -1,152 +1,70 @@
+/**
+ * Raw native module specification.
+ *
+ * NOTE: This is an internal API, don't use it directly. Use the `HCE` object exported from
+ * the package's entry point instead, it guarantees that every C-APDU is responded to exactly once.
+ */
+
 import type {CodegenTypes, TurboModule} from 'react-native';
 import {TurboModuleRegistry} from 'react-native';
 
-export type HCEModuleEventType =
-    'sessionStarted'
-    | 'sessionInvalidated'
-    /**
-     * iOS: Whether the reader field was detected.
-     * Android: Whether the reader had sent the select command to us.
-     */
-    | 'readerDetected'
-    /**
-     * Whether our HCE app was deselected or the reader was lost.
-     */
-    | 'readerDeselected'
-    /**
-     * Received C-APDU (hex-encoded string in "arg" key) from the reader.
-     * Respond by calling respondAPDU(rapdu).
-     */
-    | 'received'
-    /**
-     * 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'
-    /**
-     * 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
-  arg: string | null,
-}
-
-export type HCEModuleBackgroundEvent = {
-  type: HCEModuleBackgroundEventType
-  arg: string | null,
-  audience: string,
-}
-
-export interface Spec extends TurboModule {
-  /**
-   * Checks if a given smartphone supports required HCE features.
-   */
-  isPlatformSupported(): boolean;
-
+export type NativeHCEEvent = {
   /**
-   * iOS: Tries to acquire NFCPresentmentIntentAssertion.
-   * Android: Not supported (throws an exception).
+   * Foreground session ID (generated by JS) or background session ID (generated by native code).
    */
-  acquireExclusiveNFC(): Promise<void>;
-  /**
-   * iOS: Release NFCPresentmentIntentAssertion object.
-   * Android: Not supported (no-op).
-   */
-  releaseExclusiveNFC(): void;
+  sessionId: string;
   /**
-   * iOS: Whether the NFCPresentmentIntentAssertion is acquired and still valid.
-   * Android: Always false.
+   * One of: 'sessionStarted', 'readerDetected', 'readerLost', 'apdu', 'sessionInvalidated'.
    */
-  isExclusiveNFC(): boolean;
-
+  type: string;
   /**
-   * Begin card operation session.
-   * iOS: Create CardSession.
-   * Android: Sets an internal flag that the session is open.
+   * 'apdu' only: identifier that has to be passed back to respondApdu(), otherwise 0.
    */
-  beginSession(): Promise<void>;
+  apduId: number;
   /**
-   * iOS: Set alert message on the NFC system UI.
-   * Android: NO-OP.
+   * 'apdu' only: hex-encoded C-APDU, otherwise empty string.
    */
-  setSessionAlertMessage(message: string): void;
+  command: string;
   /**
-   * iOS: Invalidate CardSession.
-   * Android: Set an internal flag that the session is closed and disable HCE service.
+   * 'apdu' only: whether the device was locked when the C-APDU was received, otherwise false.
    */
-  invalidateSession(): void;
+  deviceLocked: boolean;
   /**
-   * iOS: Checks if CardSession is running.
-   * Android: Checks if an internal flag is set.
+   * 'sessionInvalidated' only: the reason of invalidation, otherwise empty string.
    */
-  isSessionRunning(): boolean;
+  reason: string;
+};
 
-  /**
-   * iOS: Start the card emulation.
-   * Android: Enable HCE service.
-   */
-  startHCE(): Promise<void>;
-  /**
-   * iOS: Stop the card emulation with "success"/"failure" UI status.
-   * Android: Disable HCE service.
-   */
-  stopHCE(status: HCEModuleStopReason): Promise<void>;
-  /**
-   * Send R-APDU (hex-encoded string) as a response to the last received C-APDU event.
-   * Set handle=null when calling this function from foreground app.
-   */
-  respondAPDU(handle: string | null, rapdu: string): Promise<void>;
-  /**
-   * iOS: Checks if the card emulation is running.
-   * Android: Checks if the HCE service is enabled.
-   */
-  isHCERunning(): Promise<boolean>;
+export type NativeHCECapabilities = {
+  platform: string;
+  hceSupported: boolean;
+  nfcEnabled: boolean;
+  eligible: boolean;
+  backgroundSupported: boolean;
+  presentmentSupported: boolean;
+};
 
-  /**
-   * Android: Report that the JS headless task is ready to handle HCE interaction in the background.
-   * NOTE: Don't call this API directly, use wrapper hceBackground.ts:createBackgroundHCE.
-   * See demo app or README.md for example wrapper usage.
-   */
-  beginBackgroundHCE(handle: string): boolean;
+export interface Spec extends TurboModule {
+  getCapabilities(): Promise<NativeHCECapabilities>;
 
-  /**
-   * Android: Report the background HCE interaction was finished.
-   * NOTE: Don't call this API directly, use wrapper hceBackground.ts:createBackgroundHCE.
-   * See demo app or README.md for example wrapper usage.
-   */
-  finishBackgroundHCE(handle: string): boolean;
+  beginSession(sessionId: string, allowWhenLocked: boolean): Promise<void>;
+  invalidateSession(sessionId: string): void;
+  setSessionAlertMessage(sessionId: string, message: string): void;
 
-  /**
-   * Event handler for foreground HCE interactions.
-   */
-  readonly onEvent: CodegenTypes.EventEmitter<HCEModuleEvent>;
+  startEmulation(sessionId: string): Promise<void>;
+  stopEmulation(sessionId: string, status: string): Promise<void>;
+  isEmulationRunning(sessionId: string): Promise<boolean>;
 
-  /**
-   * Event handler for background HCE interactions.
-   * NOTE: Don't subscribe to that handler directly, use wrapper hceBackground.ts:createBackgroundHCE.
-   * See demo app or README.md for example wrapper usage.
-   */
-  readonly onBackgroundEvent: CodegenTypes.EventEmitter<HCEModuleBackgroundEvent>;
+  respondApdu(sessionId: string, apduId: number, rapdu: string): Promise<void>;
+
+  acquireExclusiveNFC(): Promise<void>;
+  releaseExclusiveNFC(): void;
+  isExclusiveNFC(): boolean;
+
+  setBackgroundHandlerRegistered(registered: boolean, allowWhenLocked: boolean): void;
+  backgroundSessionReady(sessionId: string): boolean;
+
+  readonly onEvent: CodegenTypes.EventEmitter<NativeHCEEvent>;
 }
 
-export default TurboModuleRegistry.getEnforcing<Spec>(
-  'NativeHCEModule',
-);
+export default TurboModuleRegistry.getEnforcing<Spec>('NativeHCEModule');

package/js/background.ts

@@ -0,0 +1,168 @@
+import {AppRegistry, Platform} from 'react-native';
+
+import NativeHCEModule from './NativeHCEModule';
+import {
+  addSessionListener,
+  callHandler,
+  HCEError,
+  processApdu,
+  reportError,
+  resolveHandlerOptions,
+  SerialQueue,
+} from './internal';
+import type {
+  BackgroundAppState,
+  BackgroundHandlerFactory,
+  BackgroundHandlerOptions,
+  BackgroundHandlers,
+} from './types';
+
+// must match HCEManager.BACKGROUND_TASK_KEY on the native side
+const BACKGROUND_TASK_KEY = 'handleBackgroundHCECall';
+
+interface BackgroundRegistration {
+  factory: BackgroundHandlerFactory;
+  handlerTimeout: number;
+}
+
+let currentRegistration: BackgroundRegistration | null = null;
+let taskRegistered = false;
+
+if (Platform.OS === 'android') {
+  /*
+   Until the JS side declares whether it has a background handler, the native side holds the
+   interactions instead of rejecting them, as React Native might still be evaluating the bundle.
+   The handler is registered at the top level of the entry file, so the timer fires after that.
+   */
+  setTimeout(() => {
+    if (!taskRegistered) {
+      NativeHCEModule.setBackgroundHandlerRegistered(false, true);
+    }
+  }, 0);
+}
+
+interface BackgroundTaskData {
+  sessionId?: string;
+  appState?: string;
+}
+
+async function runBackgroundTask(data: BackgroundTaskData): Promise<void> {
+  const sessionId = data?.sessionId;
+  const registration = currentRegistration;
+
+  if (!sessionId || !registration) {
+    // finishing the task makes the native side reject the C-APDUs of this interaction
+    return;
+  }
+
+  const {factory, handlerTimeout} = registration;
+  const appState: BackgroundAppState = data.appState === 'foreground' ? 'foreground' : 'background';
+  const queue = new SerialQueue();
+  let handlers: BackgroundHandlers | null = null;
+
+  /*
+   The task lives until the reader is lost. Once it resolves, React Native finishes the headless
+   task and the native side stops routing C-APDUs of this interaction to JS.
+   */
+  await new Promise<void>(resolve => {
+    let finished = false;
+    let removeListener = () => {};
+
+    const finish = () => {
+      if (!finished) {
+        finished = true;
+        removeListener();
+        resolve();
+      }
+    };
+
+    removeListener = addSessionListener(sessionId, event => {
+      const h = handlers;
+
+      if (!h || finished) {
+        return;
+      }
+
+      if (event.type === 'apdu') {
+        queue.push(() => processApdu(sessionId, event, h.onApdu, h.onError, handlerTimeout));
+      } else if (event.type === 'readerLost') {
+        const onReaderLost = h.onReaderLost;
+        queue
+          .push(() => callHandler('onReaderLost()', () => onReaderLost?.(), handlerTimeout))
+          .catch(e => reportError(h.onError, e))
+          .finally(finish);
+      }
+    });
+
+    (async () => {
+      try {
+        const created = await callHandler(
+          'The background handler factory',
+          () => factory({sessionId, appState}),
+          handlerTimeout,
+        );
+
+        if (!created || typeof created.onApdu !== 'function') {
+          throw new HCEError('err_invalid_argument', 'The background handler factory must return an object with onApdu().');
+        }
+
+        handlers = created;
+      } catch (e) {
+        reportError(undefined, e);
+        finish();
+        return;
+      }
+
+      // the native side starts delivering events (including the queued C-APDU) from now on
+      if (!NativeHCEModule.backgroundSessionReady(sessionId)) {
+        // the reader was already lost
+        finish();
+      }
+    })();
+  });
+}
+
+/**
+ * Android: Register the handler of HCE interactions that happen while the app has no session
+ * with running emulation - i.e. the app is in background, not running at all or it's in foreground
+ * without an active session (check BackgroundContext.appState).
+ *
+ * Call it once, at the top level of the app's entry file (index.js), before AppRegistry.registerComponent().
+ * Calling it again replaces the previous factory and its options. No-op on iOS.
+ */
+export function registerBackgroundHandler(
+  factory: BackgroundHandlerFactory,
+  options: BackgroundHandlerOptions = {},
+): void {
+  if (Platform.OS !== 'android') {
+    return;
+  }
+
+  if (typeof factory !== 'function') {
+    throw new HCEError('err_invalid_argument', 'The background handler factory must be a function.');
+  }
+
+  const {handlerTimeout, allowWhenLocked} = resolveHandlerOptions(options);
+  currentRegistration = {factory, handlerTimeout};
+
+  if (!taskRegistered) {
+    AppRegistry.registerHeadlessTask(BACKGROUND_TASK_KEY, () => runBackgroundTask);
+    taskRegistered = true;
+  }
+
+  NativeHCEModule.setBackgroundHandlerRegistered(true, allowWhenLocked);
+}
+
+/**
+ * Android: Stop handling interactions in background, until registerBackgroundHandler() is called again.
+ * The readers then receive an error status word unless there is a session with running emulation.
+ * Interactions that have already started are served until the reader is lost. No-op on iOS.
+ */
+export function unregisterBackgroundHandler(): void {
+  if (Platform.OS !== 'android') {
+    return;
+  }
+
+  currentRegistration = null;
+  NativeHCEModule.setBackgroundHandlerRegistered(false, true);
+}

package/js/index.ts

@@ -0,0 +1,49 @@
+import NativeHCEModule from './NativeHCEModule';
+import {registerBackgroundHandler, unregisterBackgroundHandler} from './background';
+import {bytesToHex, HCEError, hexToBytes} from './internal';
+import {beginSession} from './session';
+import type {HCECapabilities, HCEPlatform} from './types';
+
+async function getCapabilities(): Promise<HCECapabilities> {
+  const caps = await NativeHCEModule.getCapabilities();
+
+  return {
+    platform: caps.platform as HCEPlatform,
+    hceSupported: caps.hceSupported,
+    nfcEnabled: caps.nfcEnabled,
+    eligible: caps.eligible,
+    backgroundSupported: caps.backgroundSupported,
+    presentmentSupported: caps.presentmentSupported,
+  };
+}
+
+export const HCE = {
+  /**
+   * Check what the device supports. Always check it before beginning a session.
+   */
+  getCapabilities,
+  beginSession,
+  registerBackgroundHandler,
+  unregisterBackgroundHandler,
+
+  /**
+   * iOS: Acquire NFCPresentmentIntentAssertion (exclusive NFC access for a limited time).
+   * Android: Not supported, rejects with err_platform_unsupported.
+   */
+  acquireExclusiveNFC: (): Promise<void> => NativeHCEModule.acquireExclusiveNFC(),
+  /**
+   * iOS: Release NFCPresentmentIntentAssertion.
+   * Android: No-op.
+   */
+  releaseExclusiveNFC: (): void => NativeHCEModule.releaseExclusiveNFC(),
+  /**
+   * iOS: Whether NFCPresentmentIntentAssertion is acquired and still valid.
+   * Android: Always false.
+   */
+  isExclusiveNFC: (): boolean => NativeHCEModule.isExclusiveNFC(),
+};
+
+export default HCE;
+
+export {HCEError, bytesToHex, hexToBytes};
+export * from './types';

package/js/internal.ts

@@ -0,0 +1,218 @@
+import type {EventSubscription} from 'react-native';
+
+import NativeHCEModule, {NativeHCEEvent} from './NativeHCEModule';
+import type {ApduHandler, HandlerOptions, ResponseAPDU} from './types';
+
+// ISO 7816-4: no precise diagnosis
+const SW_NO_PRECISE_DIAGNOSIS = '6F00';
+const HEX_CHARS = '0123456789ABCDEF';
+
+const DEFAULT_HANDLER_TIMEOUT = 10000;
+// setTimeout() fires immediately when the delay doesn't fit in a signed 32-bit integer
+const MAX_HANDLER_TIMEOUT = 0x7fffffff;
+
+export class HCEError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'HCEError';
+    this.code = code;
+  }
+}
+
+export function bytesToHex(bytes: ResponseAPDU): string {
+  let out = '';
+
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+
+    if (!Number.isInteger(b) || b < 0 || b > 0xff) {
+      throw new HCEError('err_invalid_rapdu', `Invalid byte value at index ${i}: ${b}`);
+    }
+
+    out += HEX_CHARS[b >> 4] + HEX_CHARS[b & 0x0f];
+  }
+
+  return out;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new HCEError('err_invalid_hex', 'Invalid hex string.');
+  }
+
+  const out = new Uint8Array(hex.length / 2);
+
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+
+  return out;
+}
+
+export function reportError(onError: ((error: unknown) => void) | undefined, error: unknown) {
+  if (onError) {
+    try {
+      onError(error);
+      return;
+    } catch (e) {
+      console.warn('[HCE] onError handler threw', e);
+    }
+  }
+
+  console.warn('[HCE] handler error', error);
+}
+
+export function isErrorCode(error: unknown, code: string): boolean {
+  return typeof error === 'object' && error !== null && (error as {code?: unknown}).code === code;
+}
+
+export interface ResolvedHandlerOptions {
+  // milliseconds, 0 stands for no timeout
+  handlerTimeout: number;
+  allowWhenLocked: boolean;
+}
+
+export function resolveHandlerOptions(options: HandlerOptions): ResolvedHandlerOptions {
+  const {handlerTimeout = DEFAULT_HANDLER_TIMEOUT, allowWhenLocked = true} = options;
+
+  if (
+    typeof handlerTimeout !== 'number' ||
+    !(handlerTimeout === Infinity || (handlerTimeout >= 0 && handlerTimeout <= MAX_HANDLER_TIMEOUT))
+  ) {
+    throw new HCEError(
+      'err_invalid_argument',
+      `handlerTimeout must be a number of milliseconds between 0 and ${MAX_HANDLER_TIMEOUT} or Infinity.`,
+    );
+  }
+
+  if (typeof allowWhenLocked !== 'boolean') {
+    throw new HCEError('err_invalid_argument', 'allowWhenLocked must be a boolean.');
+  }
+
+  return {handlerTimeout: handlerTimeout === Infinity ? 0 : handlerTimeout, allowWhenLocked};
+}
+
+/**
+ * Call the handler and wait for its result, but at most `timeout` milliseconds (0 = no limit).
+ * The handler can't be cancelled, its late result (or error) is ignored.
+ */
+export function callHandler<T>(name: string, handler: () => T | PromiseLike<T>, timeout: number): Promise<T> {
+  // also turns a synchronous exception into a rejection
+  const result = new Promise<T>(resolve => resolve(handler()));
+
+  if (timeout === 0) {
+    return result;
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new HCEError('err_handler_timeout', `${name} has not finished within ${timeout} ms.`));
+    }, timeout);
+
+    result.then(
+      value => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      error => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Runs the pushed tasks one after another, so that the event handlers never interleave.
+ */
+export class SerialQueue {
+  private tail: Promise<void> = Promise.resolve();
+
+  push(task: () => unknown): Promise<void> {
+    const result = this.tail.then(async () => {
+      await task();
+    });
+    this.tail = result.catch(() => {});
+    return result;
+  }
+}
+
+/**
+ * Pass the C-APDU to the handler and always respond to it: with the handler's result
+ * or with an error status word if the handler has failed.
+ */
+export async function processApdu(
+  sessionId: string,
+  event: NativeHCEEvent,
+  onApdu: ApduHandler,
+  onError: ((error: unknown) => void) | undefined,
+  timeout: number,
+): Promise<void> {
+  let response: string;
+
+  try {
+    const result = await callHandler(
+      'onApdu()',
+      () =>
+        onApdu({
+          id: event.apduId,
+          command: hexToBytes(event.command),
+          deviceLocked: event.deviceLocked,
+        }),
+      timeout,
+    );
+
+    if (result == null || typeof result.length !== 'number' || result.length < 2) {
+      throw new HCEError('err_invalid_rapdu', 'onApdu() must return at least 2 bytes (the status word).');
+    }
+
+    response = bytesToHex(result);
+  } catch (e) {
+    reportError(onError, e);
+    response = SW_NO_PRECISE_DIAGNOSIS;
+  }
+
+  try {
+    await NativeHCEModule.respondApdu(sessionId, event.apduId, response);
+  } catch (e) {
+    // the reader was lost or the session was closed in the meantime, that's expected
+    if (!isErrorCode(e, 'err_stale_apdu')) {
+      reportError(onError, e);
+    }
+  }
+}
+
+type SessionListener = (event: NativeHCEEvent) => void;
+
+const sessionListeners = new Map<string, SessionListener>();
+let subscription: EventSubscription | null = null;
+
+function dispatchEvent(event: NativeHCEEvent) {
+  const listener = sessionListeners.get(event.sessionId);
+
+  if (listener) {
+    listener(event);
+  } else if (event.type === 'apdu') {
+    // nobody is listening, don't leave the reader waiting
+    NativeHCEModule.respondApdu(event.sessionId, event.apduId, SW_NO_PRECISE_DIAGNOSIS).catch(() => {});
+  }
+}
+
+/**
+ * There is a single native event stream, the events are routed to listeners by session ID.
+ */
+export function addSessionListener(sessionId: string, listener: SessionListener): () => void {
+  if (!subscription) {
+    subscription = NativeHCEModule.onEvent(dispatchEvent);
+  }
+
+  sessionListeners.set(sessionId, listener);
+
+  return () => {
+    if (sessionListeners.get(sessionId) === listener) {
+      sessionListeners.delete(sessionId);
+    }
+  };
+}