@pagopa/io-react-native-iso18013 0.4.0 → 0.5.0

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

@@ -1,7 +1,6 @@
 import { NativeEventEmitter, Platform } from 'react-native';
-import type { AcceptedFields } from './request';
 import { IoReactNativeIso18013 } from '..';
-import type { RequestedDocument } from '../types';
+import type { AcceptedFields, RequestedDocument } from '../types';
 
 const eventEmitter = new NativeEventEmitter(IoReactNativeIso18013);
 
@@ -40,10 +39,12 @@ export enum ErrorCode {
 
 /**
  * Starts the proximity flow by allocating the necessary resources and initializing the Bluetooth stack.
+ * 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
+ * @throws {ModuleError} in case of error which can be parsed with {@link ModuleErrorSchema}
  */
 export function start(
   config: {
@@ -68,32 +69,41 @@ export function start(
 }
 
 /**
- * Gets the QR code string this method is responsible for initializing the connection and retrieving the QR code string
+ * 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 QR engagement
+ * Closes the bluetooth connection and clears any resource.
+ * Resolves to true after closing the connection or rejects in case of error.
+ * @throws {ModuleError} in case of error which can be parsed with {@link ModuleErrorSchema}
  */
 export function close(): Promise<boolean> {
   return IoReactNativeIso18013.close();
 }
 
 /**
- * Sends an error response to the verifier app.
+ * Sends an error response during the presentation according to the SessionData status codes
+ * defined in table 20 of the ISO18013-5 standard.
+ * Resolves to true or rejects in case of error.
  * The error code must be one of the `ErrorCode` enum values.
  * @param code - The error code to be sent to the verifier app.
+ * @throws {ModuleError} in case of error which can be parsed with {@link ModuleErrorSchema}
  */
 export function sendErrorResponse(code: ErrorCode): Promise<boolean> {
   return IoReactNativeIso18013.sendErrorResponse(code);
 }
 
 /**
- * Generates a response that will be sent to the verifier app containing the requested data
- * @param documents - An array of `Document` which contains the requested data received from the `onDocumentRequestReceived` event
+ * Generates a response which can later be sent with {sendResponse} with the provided CBOR documents and the requested attributes.
+ * Resolves with a base64 encoded response or rejects in case of error.
+ * @param documents - An array of `RequestedDocument` which contains the requested data received from the `onDocumentRequestReceived` event
  * @param acceptedFields - The accepted fields which will be presented to the verifier app. See the type definition for more details.
+ * @throws {ModuleError} in case of error which can be parsed with {@link ModuleErrorSchema}
  * @returns A base64 encoded response to be sent to the verifier app via `sendResponse`
  */
 export function generateResponse(
@@ -104,9 +114,11 @@ export function generateResponse(
 }
 
 /**
- * Sends the response generated through the `generateResponse` method to the verifier app.
+ * Sends a response containing the documents and the fields which the user decided to present generated by {@link generateResponse}.
  * Currently there's not evidence of the verifier app responding to this request, thus we don't handle the response.
+ * Resolves with a true boolean in case of success or rejects in case of error.
  * @param response - The base64 encoded response to be sent to the verifier app.
+ * @throws {ModuleError} in case of failure which can be parsed with {@link ModuleErrorSchema}
  */
 export function sendResponse(response: string): Promise<boolean> {
   return IoReactNativeIso18013.sendResponse(response);

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

@@ -43,25 +43,3 @@ export type VerifierRequest = z.infer<typeof VerifierRequest>;
 export const parseVerifierRequest = (input: unknown): VerifierRequest => {
   return VerifierRequest.parse(input);
 };
-
-/**
- * This is the type definition for the accepted fields that will be presented to the verifier app.
- * It contains of a nested object structure, where the outermost key represents the credential doctype.
- * The inner dictionary contains namespaces, and for each namespace, there is another dictionary mapping requested claims to a boolean value,
- * which indicates whether the user is willing to present the corresponding claim. Example:
- * `{
- *    "org.iso.18013.5.1.mDL": {
- *      "org.iso.18013.5.1": {
- *        "hair_colour": true, // Indicates the user is willing to present this claim
- *        "given_name_national_character": true,
- *        "family_name_national_character": true,
- *        "given_name": true,
- *     }
- *    }
- *  }`
- **/
-export type AcceptedFields = {
-  [credential: string]: {
-    [namespace: string]: { [field: string]: boolean };
-  };
-};

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

@@ -1,51 +1,47 @@
-## ISO18013-7
+# ISO18013-7
 
-This module provides methods to obtain data structures necessary for the processes defined in the `ISO-18013` standard.
+This library provides a React Native module based on [iso18013-android](https://github.com/pagopa/iso18013-android) and [iso18013-ios](https://github.com/pagopa/iso18013-ios) which allows mDL remote presentation according to the ISO 18013-7 standard.
 
 ```typescript
-import { ISO18013_7 } from '@pagopa/io-react-native-cbor';
+import { ISO18013_7 } from '@pagopa/io-react-native-iso18013';
 ```
 
-### Methods
+## Methods
 
 #### `generateOID4VPDeviceResponse`
 
-Generates CBOR of the _Device Response_ containing all the claims that have been chosen to be presented during an _OID4VP_ session.
-
-Returns a `Promise` which resolves to a `string` containing the CBOR of the **Device Response** object or rejects with an instance of `CoseFailure` in case of failures.
+Returns a string containing the CBOR of the **Device Response** object.
 
 ```typescript
-try {
-  const result = await ISO18013_7.generateOID4VPDeviceResponse(
-    clientId,
-    responseUri,
-    authorizationRequestNonce,
-    mdocGeneratedNonce,
-    documents,
-    fieldRequestedAndAccepted
-  );
-} catch (error: any) {
-  const { message, userInfo } = e as CoseFailure;
-}
-```
-
-#### Signature
+import { ISO18013_7 } from '@pagopa/io-react-native-iso18013';
 
-```typescript
-type RequestedDocument = {
-    issuerSignedContent : string,
-    alias : string,
-    docType : string
-}
+const documents = [
+  {
+    issuerSignedContent: 'base64url-or-base64-encoded-content',
+    alias: 'key-alias',
+    docType: 'docType',
+  },
+];
+
+const acceptedFields = {
+  'org.iso.18013.5.1.mDL': {
+    'org.iso.18013.5.1': {
+      hair_colour: true,
+      given_name_national_character: true,
+      family_name_national_character: true,
+      given_name: true,
+    },
+  },
+};
 
-export const generateOID4VPDeviceResponse = async (
-  clientId: string,
-  responseUri: string,
-  authorizationRequestNonce: string,
-  mdocGeneratedNonce: string,
-  documents: Array<RequestedDocument>,
-  fieldRequestedAndAccepted: Record<string, any> | string
-) : Promise<string> => {...};
+const result = await ISO18013_7.generateOID4VPDeviceResponse(
+  clientId,
+  responseUri,
+  authorizationRequestNonce,
+  mdocGeneratedNonce,
+  documents,
+  acceptedFields
+);
 ```
 
 ## Errors

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

@@ -5,4 +5,4 @@ export {
   type ModuleErrorCodes,
 } from './error';
 
-export { type RequestedDocument } from '../types';
+export { type RequestedDocument, type AcceptedFields } from '../types';

package/src/iso18013/iso18013-7/remote.ts

@@ -1,17 +1,17 @@
 import { IoReactNativeIso18013 } from '..';
+import type { AcceptedFields } from '../iso18013-5';
 import type { RequestedDocument } from '../types';
 
 /**
- *
- * @param clientId extracted from OID4VP session
- * @param responseUri extracted from OID4VP session
- * @param authorizationRequestNonce extracted from OID4VP session
- * @param mdocGeneratedNonce To be generated
- * @param documents An Array of {@link DocRequested}
- * @param fieldRequestedAndAccepted extracted from OID4VP session, it's a record of claims
- *                                  accepted for disclosure or its stringification
- * @throws {OID4VPFailure} in case of failure
- * @returns the Device Response in CBOR format
+ * Generates a CBOR device response for ISO 18013-7 mDL remote presentation using OID4VP.
+ * @param clientId - the client id extracted from OID4VP session
+ * @param responseUri - the response URI extracted from OID4VP session
+ * @param authorizationRequestNonce - the authorization request nonce extracted from OID4VP session
+ * @param mdocGeneratedNonce - the mdoc generated nonce to be generated
+ * @param documents - an array of {@link RequestedDocument}
+ * @param acceptedFields - a record of claims accepted for disclosure or its stringification extracted from OID4VP session
+ * @throws {ModuleError} in case of failure which can be parsed with {@link ModuleErrorSchema}
+ * @returns a base64 encoded device response
  */
 export const generateOID4VPDeviceResponse = async (
   clientId: string,
@@ -19,7 +19,7 @@ export const generateOID4VPDeviceResponse = async (
   authorizationRequestNonce: string,
   mdocGeneratedNonce: string,
   documents: Array<RequestedDocument>,
-  fieldRequestedAndAccepted: Record<string, any> | string
+  acceptedFields: AcceptedFields
 ): Promise<string> => {
   return await IoReactNativeIso18013.generateOID4VPDeviceResponse(
     clientId,
@@ -27,8 +27,6 @@ export const generateOID4VPDeviceResponse = async (
     authorizationRequestNonce,
     mdocGeneratedNonce,
     documents,
-    typeof fieldRequestedAndAccepted === 'string'
-      ? fieldRequestedAndAccepted
-      : JSON.stringify(fieldRequestedAndAccepted)
+    acceptedFields
   );
 };

package/src/iso18013/types.ts

@@ -14,3 +14,27 @@ export type RequestedDocument = {
   alias: string;
   docType: string;
 };
+
+/**
+ * This is the type definition for the accepted fields that will be presented to the verifier app.
+ * It contains of a nested object structure, where the outermost key represents the credential doctype.
+ * The inner dictionary contains namespaces, and for each namespace, there is another dictionary mapping requested claims to a boolean value,
+ * which indicates whether the user is willing to present the corresponding claim. Example:
+ * `{
+ *    "org.iso.18013.5.1.mDL": {
+ *      "org.iso.18013.5.1": {
+ *        "hair_colour": true, // Indicates the user is willing to present this claim
+ *        "given_name_national_character": true,
+ *        "family_name_national_character": true,
+ *        "given_name": true,
+ *     },
+ *     {...}
+ *    },
+ *    {...}
+ *  }`
+ **/
+export type AcceptedFields = {
+  [credential: string]: {
+    [namespace: string]: { [field: string]: boolean };
+  };
+};