@pagopa/io-react-native-iso18013 0.6.0 → 0.8.0

package/src/cbor/cose/README.md

@@ -11,20 +11,21 @@ import { COSE } from '@pagopa/io-react-native-iso18013';
 #### `sign`
 
 Signs base64 encoded data using COSE (CBOR Object Signing and Encryption).
-Returns a `Promise` which resolves to a `string` containing the COSE-Sign1 object in base64 encoding or rejects with an instance of `CoseFailure` in case of failures.
+Returns a `Promise` which resolves to a `string` containing the COSE-Sign1 object in base64 encoding or rejects with a `ModuleError` in case of failures.
 
 ```typescript
 try {
   const coseSign1 = await COSE.sign('base64EncodedData', 'keyTag');
 } catch (e) {
-  const { message, userInfo } = e as CoseFailure;
+  const parsedError = COSE.ModuleErrorSchema.parse(e);
+  console.log(parsedError.code, parsedError.message);
 }
 ```
 
 #### `verify`
 
 Verifies a COSE-Sign1 object using the provided public key.
-Returns a `Promise` which resolves to a `boolean` indicating if the signature is valid or rejects with an instance of `CoseFailure` in case of failures.
+Returns a `Promise` which resolves to a `boolean` indicating if the signature is valid or rejects with a `ModuleError` in case of failures.
 
 ```typescript
 // public key in JWK format
@@ -38,7 +39,8 @@ const publicKey = {
 try {
   const isValid = await COSE.verify('coseSign1Base64Data', publicKey);
 } catch (e) {
-  const { message, userInfo } = e as CoseFailure;
+  const parsedError = COSE.ModuleErrorSchema.parse(e);
+  console.log(parsedError.code, parsedError.message);
 }
 ```
 

package/src/iso18013/iso18013-5/README.md

@@ -9,27 +9,78 @@ yarn add @pagopa/io-react-native-iso18013
 cd ios && bundle exec pod install && cd ..
 ```
 
+## Permission
+
+This library uses Bluetooth capabilities in order to implement the proximity flow defined in the ISO 18013-5 standard. Thus, Bluetooth permissions must be added to the native projects.
+
+### Android
+
+Add the following permissions to your `AndroidManifest.xml`:
+
+```xml
+<!-- Required for Bluetooth on Android >=12 or SDK >=31 -->
+
+<!-- We defined the neverForLocation flag as we do not derive it from the Bluetooth -->
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+
+<!-- Required for Bluetooth on Android <=11 SDK <= 30 -->
+<uses-permission android:name="android.permission.BLUETOOTH"
+                  android:maxSdkVersion="30" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
+                  android:maxSdkVersion="30" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>
+```
+
+Please note that the `neverForLocation` flag of `BLUETOOTH_SCAN` indicates that the app does not derive location information from Bluetooth scans. However, you still need to include the `ACCESS_FINE_LOCATION` permission for Android versions <=11 (SDK <=30) to enable Bluetooth scanning.
+
+### iOS
+
+Add the following keys to your `Info.plist`:
+
+```xml
+<!-- Required for Bluetooth usage -->
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>$(PRODUCT_NAME) needs access BLE.</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>$(PRODUCT_NAME) needs access BLE.</string>
+<key>NSBluetoothScanUsageDescription</key>
+<string>$(PRODUCT_NAME) needs access to scan for nearby Bluetooth devices.</string>
+```
+
+More info can be found in the [official Android documentation](https://developer.android.com/develop/connectivity/bluetooth/bt-permissions).
+
 ## Events
 
 This library emits the following events:
 | Event | Payload | Description |
-|---------------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
-| onDeviceConnecting (iOS only) | `undefined` | Event dispatched when the verifier app is connecting |
+|---------------------------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| onQrCodeString | `{ data: string }` | Event dispatched when the QR Code payload is generated. Contains the QR code string to display. |
+| onNfcStarted | `undefined` | Event dispatched when NFC starts successfully. |
+| onNfcStopped | `undefined` | Event dispatched when NFC stops successfully. |
+| onDeviceConnecting | `undefined` | Event dispatched when the verifier app is connecting. |
 | onDeviceConnected | `undefined` | Event dispatched when the verifier app is connected. |
-| onDocumentRequestReceived | `{ data: string } \| undefined` | Event dispatched when the consumer app receives a new request, contained in the data payload. It can be parsed via the `parseVerifierRequest` provided [here](src/schema.ts). |
+| onDocumentRequestReceived | `{ data: string; retrievalMethod: RetrievalMethod }` | Event dispatched when the consumer app receives a new request. The `data` payload can be parsed via the `parseVerifierRequest` function. The `retrievalMethod` indicates whether BLE or NFC was used. |
 | onDeviceDisconnected | `undefined` | Event dispatched when the verifier app disconnects by sending the END (0x02) flag. |
-| onError | `{ error: string } \| undefined` | Event dispatched when an error occurs which is contained in the error payload. It can be parsed via the `parseError` provided [here](src/schema.ts). |
+| onError | `{ error?: string } \| undefined` | Event dispatched when an error occurs which is contained in the error payload. It can be parsed with `ISO18013_5.OnErrorPayloadSchema`. |
 
-The events flow is described in the following diagram:
+Where `RetrievalMethod` is defined as `'ble' | 'nfc'`.
+
+### QR Code engagement flow
+
+The events flow for QR Code engagement is described in the following diagram:
 
 ```mermaid
 flowchart LR
-    onDeviceConnecting["onDeviceConnecting *(iOS only)*"]
+    onQrCodeString["onQrCodeString"]
+    onDeviceConnecting["onDeviceConnecting"]
     onDeviceConnected["onDeviceConnected"]
     onDocumentRequestReceived["onDocumentRequestReceived"]
     onDeviceDisconnected["onDeviceDisconnected"]
     onError["onError"]
 
+    onQrCodeString -- "Verifier scan the QR Code" --> onDeviceConnecting
     onDeviceConnecting -- "Verifier app connects" --> onDeviceConnected
 
     onDeviceConnected -- "Verifier app sends request" --> onDocumentRequestReceived
@@ -40,6 +91,36 @@ flowchart LR
     onDocumentRequestReceived -- "Error status or abrupt disconnection" --> onError
 ```
 
+### NFC engagement flow
+
+The events flow for NFC engagement is described in the following diagram:
+
+```mermaid
+flowchart LR
+    onNfcStarted["onNfcStarted"]
+    onNfcStopped["onNfcStopped"]
+    onDeviceConnecting["onDeviceConnecting"]
+    onDeviceConnected["onDeviceConnected"]
+    onDocumentRequestReceived["onDocumentRequestReceived"]
+    onDeviceDisconnected["onDeviceDisconnected"]
+    onError["onError"]
+
+    onNfcStarted -- "Verifier taps NFC" --> onDeviceConnecting
+    onDeviceConnecting -- "Verifier app connects" --> onDeviceConnected
+
+    onDeviceConnected -- "Verifier app sends request" --> onDocumentRequestReceived
+    onDeviceConnected -- "Verifier sends END (0x02)" --> onDeviceDisconnected
+    onDeviceConnected -- "Error status or abrupt disconnection" --> onError
+
+    onDocumentRequestReceived -- "Verifier sends END (0x02)" --> onDeviceDisconnected
+    onDocumentRequestReceived -- "Error status or abrupt disconnection" --> onError
+
+    onError --> onNfcStopped
+    onDeviceDisconnected --> onNfcStopped
+```
+
+### Listen for events
+
 Listeners can be added using the `addListener` method and removed by using the returned reference by calling the `remove` method.
 
 ```typescript
@@ -52,6 +133,39 @@ const listener = ISO18013_5.addListener('event', () =>
 listener.remove();
 ```
 
+#### `onQrCodeString`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener(
+  'onQrCodeString',
+  (payload: ISO18013_5.EventsPayload['onQrCodeString']) => {
+    console.log('QR Code payload received: ', payload.data);
+  }
+);
+```
+
+#### `onNfcStarted`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener('onNfcStarted', () => {
+  console.log('NFC started and ready for engagement');
+});
+```
+
+#### `onNfcStopped`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener('onNfcStopped', () => {
+  console.log('NFC stopped');
+});
+```
+
 #### `onDeviceConnecting`
 
 ```typescript
@@ -117,13 +231,13 @@ ISO18013_5.addListener(
       if (!data || !data.error) {
         throw new Error('No error data received');
       }
-      const parsedError = parseError(data.error);
+      const parsedError = ISO18013_5.OnErrorPayloadSchema.parse(data.error);
       console.error(`onError: ${parsedError}`);
     } catch (e) {
       console.error('Error parsing onError data:', e);
     } finally {
       // Close the flow on error
-      await closeFlow();
+      await ISO18013_5.close();
     }
   }
 );
@@ -131,27 +245,37 @@ ISO18013_5.addListener(
 
 ## Methods
 
-#### `start`
+#### `startEngagement`
+
+Starts the proximity flow with the specified engagement and retrieval modes. By default enables both QR code and NFC engagement with both BLE and NFC retrieval. NFC engagement requires iOS 17.4+ on iOS and HCE support on Android.
 
-Starts the proximity flow and starts the bluetooth service. This method also accepts optional parameters to configure the initialization on Android, along with the possibility
-to specify a certificates of array to verify the reader app.
+| Parameter           | Platform    | Default              | Description                                                                                                               |
+| ------------------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `peripheralMode`    | Android     | `true`               | Whether the device is in peripheral mode                                                                                  |
+| `centralClientMode` | Android     | `false`              | Whether the device is in central client mode                                                                              |
+| `clearBleCache`     | Android     | `true`               | Whether the BLE cache should be cleared                                                                                   |
+| `certificates`      | Android/iOS | `[]`                 | Two-dimensional array of base64 strings representing DER encoded X.509 certificates used to authenticate the verifier app |
+| `engagementModes`   | Android/iOS | `['qrcode', 'nfc']`  | Array of engagement modes to activate (`'qrcode'` and/or `'nfc'`)                                                        |
+| `retrievalMethods`  | Android/iOS | `['ble', 'nfc']`     | Array of supported retrieval methods (`'ble'` and/or `'nfc'`)                                                             |
 
 ```typescript
 import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
 
-await ISO18013_5.start();
-```
-
-#### `getQrCodeString`
+// Starts both QR and NFC engagement with BLE and NFC retrieval (defaults)
+await ISO18013_5.startEngagement();
 
-Returns the QR code string which contains a base64url encoded CBOR object which encodes the bluetooth engagement data.
-It can be used to display the QR code in the UI which will be scanned by the verifier app.
-
-```typescript
-import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+// QR code engagement only (BLE retrieval)
+await ISO18013_5.startEngagement({
+  engagementModes: ['qrcode'],
+  retrievalMethods: ['ble'],
+});
 
-const qrCodeString = await ISO18013_5.getQrCodeString();
-console.log(qrCodeString);
+// NFC engagement only, with both retrieval methods
+await ISO18013_5.startEngagement({
+  engagementModes: ['nfc'],
+  retrievalMethods: ['ble', 'nfc'],
+  certificates: [['base64DerCert1']],
+});
 ```
 
 #### `generateResponse`
@@ -199,16 +323,15 @@ await ISO18013_5.sendResponse(response);
 Sends an error response to the verifier app. The supported error codes are defined in the Table 20 of the ISO 18013-5 standard and are coded in the `ErrorCode` enum.
 
 ```typescript
-import { ISO18013_5, ErrorCode } from '@pagopa/io-react-native-iso18013';
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
 
-await ISO18013_5.sendErrorResponse(ErrorCode.SESSION_ENCRYPTION);
+await ISO18013_5.sendErrorResponse(ISO18013_5.ErrorCode.SESSION_ENCRYPTION);
 ```
 
 #### `close`
 
-Closes the QR engagement by releasing the resources allocated during the `start` method.
+Closes the QR/NFC engagement by releasing the bluetooth connection and clearing any allocated resources.
 Before starting a new flow, it is necessary to call this method to ensure that the previous flow is properly closed.
-Listeners can be added using the `addListener` method and removed using the `removeListener` method.
 
 ```typescript
 import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
@@ -218,7 +341,7 @@ await ISO18013_5.close();
 
 ## Proximity Sequence Diagram
 
-This section describes a high level overview of the happy flow interactions between an app implementing the `io-react-native-proximity` library and a verifier app.
+This section describes a high level overview of the happy flow interactions between an app implementing the `io-react-native-iso18013` library and a verifier app.
 
 ```mermaid
 sequenceDiagram
@@ -227,9 +350,8 @@ sequenceDiagram
     participant verifier as Verifier App
 
     Note over proximity, verifier: If an error occurs during the flow, the onError callback is triggered
-    app->>+proximity: Calls start()
-    app->>+proximity: Calls getQrCode()
-    proximity-->>+app: QR code string
+    app->>+proximity: Calls startEngagement()
+    proximity->>+app: Triggers the onQrCodeString callback with QR code data
     app->>+app: Renders the QR code string
     verifier->>+app: Scans the QR code
     proximity->>+app: Triggers the onDeviceConnecting callback
@@ -266,17 +388,15 @@ sequenceDiagram
 
 This table contains the list of error codes that can be thrown by the `ISO18013_5` module which are mapped via the `ModuleErrorCodes` type:
 
-| Type                      | Platform    | Description                                                                  |
-| ------------------------- | ----------- | ---------------------------------------------------------------------------- |
-| DRH_NOT_DEFINED           | Android     | The device retrieval helper hasn't been initialized, call the `start` method |
-| QR_ENGAGEMENT_NOT_DEFINED | Android     | The QR engagement hasn't been initialized, call the `start` method           |
-| START_ERROR               | Android/iOS | An error occurred while initializing the required resources                  |
-| GET_QR_CODE_ERROR         | Android/iOS | An error occurred while generating the engagement QR code                    |
-| SEND_RESPONSE_ERROR       | Android/iOS | An error occurred while sending the response for the verifier app            |
-| SEND_ERROR_RESPONSE_ERROR | Android/iOS | An error occurred while sending the error response to the verifier app       |
-| GENERATE_RESPONSE_ERROR   | Android/iOS | An error occurred while generating the response for the verifier app         |
-| CLOSE_ERROR               | Android     | An error occured while closing the required resources                        |
-| EUNSPECIFIED              | Android     | Default error when no other error is specified                               |
+| Type                      | Platform    | Description                                                            |
+| ------------------------- | ----------- | ---------------------------------------------------------------------- |
+| DRH_NOT_DEFINED           | Android     | The device retrieval helper hasn't been initialized                    |
+| START_ERROR               | Android/iOS | An error occurred while starting the engagement                        |
+| SEND_RESPONSE_ERROR       | Android/iOS | An error occurred while sending the response for the verifier app      |
+| SEND_ERROR_RESPONSE_ERROR | Android/iOS | An error occurred while sending the error response to the verifier app |
+| GENERATE_RESPONSE_ERROR   | Android/iOS | An error occurred while generating the response for the verifier app   |
+| CLOSE_ERROR               | Android     | An error occurred while closing the required resources                 |
+| EUNSPECIFIED              | Android     | Default error when no other error is specified                         |
 
 An error can be parsed using the `ModuleErrorSchema` with type `ModuleErrorCodes` exposed by the `ISO18013_5` module. The error can be parsed as follows:
 

package/src/iso18013/iso18013-5/error.ts

@@ -13,9 +13,7 @@ export type OnErrorPayload = z.infer<typeof OnErrorPayloadSchema>;
  */
 const ModuleErrorCodesSchema = z.enum([
   'DRH_NOT_DEFINED', // Android only
-  'QR_ENGAGEMENT_NOT_DEFINED', // Android only
   'START_ERROR',
-  'GET_QR_CODE_ERROR',
   'SEND_RESPONSE_ERROR',
   'SEND_ERROR_RESPONSE_ERROR',
   'GENERATE_RESPONSE_ERROR',

package/src/iso18013/iso18013-5/index.ts

@@ -12,13 +12,14 @@ export {
   ErrorCode,
   type Events,
   type EventsPayload,
+  type EngagementMode,
+  type RetrievalMethod,
   addListener,
+  startEngagement,
   close,
   generateResponse,
-  getQrCodeString,
   sendErrorResponse,
   sendResponse,
-  start,
 } from './proximity';
 
 export { type RequestedDocument, type AcceptedFields } from '../types';

package/src/iso18013/iso18013-5/proximity.ts

@@ -6,17 +6,24 @@ const eventEmitter = new NativeEventEmitter(IoReactNativeIso18013);
 
 /**
  * Events emitted by the native module:
- * - `onDeviceConnecting`: (iOS only) Emitted when the device is connecting to the verifier app.
+ * - `onQrCodeString`: Emitted when the QR Code payload is generated.
+ * - `onNfcStarted`: Emitted when NFC starts successfully.
+ * - `onNfcStopped`: Emitted when NFC stops successfully.
+ * - `onDeviceConnecting`: Emitted when the device is connecting to the verifier app (QR and NFC flows on both iOS and Android).
  * - `onDeviceConnected`: Emitted when the device is connected to the verifier app.
- * - `onDocumentRequestReceived`: Emitted when a document request is received from the verifier app. Carries a payload containing the request data.
+ * - `onDocumentRequestReceived`: Emitted when a document request is received from the verifier app. Carries a payload containing the request data and the retrieval method.
  * - `onDeviceDisconnected`: Emitted when the device is disconnected from the verifier app.
  * - `onError`: Emitted when an error occurs. Carries a payload containing the error data.
  */
 export type EventsPayload = {
+  onQrCodeString: { data: string };
+  onNfcStarted: undefined;
+  onNfcStopped: undefined;
   onDeviceConnecting: undefined;
   onDeviceConnected: undefined;
   // The message payload is a JSON string that can be parsed into a `VerifierRequest` structure via `parseVerifierRequest`.
-  onDocumentRequestReceived: { data?: string } | undefined;
+  // When the request cannot be parsed, `data` may be an empty string.
+  onDocumentRequestReceived: { data: string; retrievalMethod: RetrievalMethod };
   onDeviceDisconnected: undefined;
   onError: { error?: string } | undefined;
 };
@@ -38,45 +45,67 @@ export enum ErrorCode {
 }
 
 /**
- * Starts the proximity flow by allocating the necessary resources and initializing the Bluetooth stack.
+ * Supported engagement modes for initiating the presentation session.
+ * - qrcode: the presentation session is initiated by scanning a QR code generated by the verifier app. The requested data is then retrieved via BLE communication between the user device and the verifier app.
+ * - nfc: the presentation session is initiated by tapping the user device on an NFC tag of the verifier app. The requested data is then retrieved via NFC or BLE communication between the user device and the verifier app.
+ */
+export type EngagementMode = 'qrcode' | 'nfc';
+
+/**
+ * Supported methods for retrieving the requested data from the user device.
+ * - ble: the requested data is retrieved via Bluetooth Low Energy communication between the user device and the verifier app.
+ * - nfc: the requested data is retrieved via NFC communication between the user device and the verifier app.
+ */
+export type RetrievalMethod = 'ble' | 'nfc';
+
+/**
+ * Starts proximity engagement with caller-controlled retrieval methods.
  * Resolves to true or rejects in case of error.
  * @param config.peripheralMode (Android only) - Whether the device is in peripheral mode. Defaults to true
  * @param config.centralClientMode (Android only) - Whether the device is in central client mode. Defaults to false
  * @param config.clearBleCache (Android only) - Whether the BLE cache should be cleared. Defaults to true
  * @param config.certificates - Two-dimensional array of base64 strings representing DER encoded X.509 certificate which are used to authenticate the verifier app
+ * @param config.engagementMethods - Array of engagements methods initiated. Defaults to ['qr', 'nfc']
+ * @param config.retrievalMethods - Array of supported retrieval methods. Defaults to ['ble', 'nfc']
  * @throws {ModuleError} in case of error which can be parsed with {@link ModuleErrorSchema}
  */
-export function start(
+export function startEngagement(
   config: {
     peripheralMode?: boolean;
     centralClientMode?: boolean;
     clearBleCache?: boolean;
-    certificates?: Array<Array<String>>;
+    certificates?: ReadonlyArray<ReadonlyArray<string>>;
+    engagementModes?: ReadonlyArray<EngagementMode>;
+    retrievalMethods?: ReadonlyArray<RetrievalMethod>;
   } = {}
 ): Promise<boolean> {
-  const { peripheralMode, centralClientMode, clearBleCache, certificates } =
-    config;
+  const {
+    peripheralMode = true,
+    centralClientMode = false,
+    clearBleCache = true,
+    certificates = [],
+    engagementModes = ['qrcode', 'nfc'],
+    retrievalMethods = ['ble', 'nfc'],
+  } = config;
+
   if (Platform.OS === 'ios') {
-    return IoReactNativeIso18013.start(certificates ? certificates : []);
+    return IoReactNativeIso18013.startEngagement(
+      certificates,
+      engagementModes,
+      retrievalMethods
+    );
   } else {
-    return IoReactNativeIso18013.start(
-      peripheralMode ? peripheralMode : true,
-      centralClientMode ? centralClientMode : false,
-      clearBleCache ? clearBleCache : true,
-      certificates ? certificates : []
+    return IoReactNativeIso18013.startEngagement(
+      peripheralMode,
+      centralClientMode,
+      clearBleCache,
+      certificates,
+      engagementModes,
+      retrievalMethods
     );
   }
 }
 
-/**
- * Creates a QR code to be scanned in order to initialize the presentation.
- * Resolves with a string containing the QR code or rejects in case of error.
- * @throws {ModuleError} in case of error which can be parsed with {@link ModuleErrorSchema}
- */
-export function getQrCodeString(): Promise<string> {
-  return IoReactNativeIso18013.getQrCodeString();
-}
-
 /**
  * Closes the bluetooth connection and clears any resource.
  * Resolves to true after closing the connection or rejects in case of error.

package/src/iso18013/iso18013-7/README.md

@@ -52,7 +52,7 @@ This table contains the list of error codes that can be thrown by the `ISO18013_
 | ------------------------------ | ----------- | ----------------------------------------------- |
 | GENERATE_OID4VP_RESPONSE_ERROR | Android/iOS | An error occurred while generating the response |
 
-An error can be parsed using the `ModuleErrorSchema` with type `ModuleErrorCodes` exposed by the `ISO18013_5` module. The error can be parsed as follows:
+An error can be parsed using the `ModuleErrorSchema` with type `ModuleErrorCodes` exposed by the `ISO18013_7` module. The error can be parsed as follows:
 
 ```typescript
 import { ISO18013_7 } from '@pagopa/io-react-native-iso18013';