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

package/android/src/main/java/com/ioreactnativeiso18013/IoReactNativeIso18013Module.kt

@@ -9,8 +9,6 @@ import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.ReadableType
 import com.facebook.react.bridge.WritableMap
-import com.facebook.react.bridge.WritableNativeMap
-import com.ioreactnativeiso18013.IoReactNativeCborModule.Companion.ERROR_USER_INFO_KEY
 import it.pagopa.io.wallet.proximity.OpenID4VP
 import it.pagopa.io.wallet.proximity.bluetooth.BleRetrievalMethod
 import it.pagopa.io.wallet.proximity.qr_code.QrEngagement
@@ -32,12 +30,12 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
 
   /**
    * Starts the proximity flow by allocating the necessary resources and initializing the Bluetooth stack.
-   * Resolves to true or rejects if an error occurs.
-   * @param peripheralMode - Whether the device is in peripheral mode. Defaults to true
-   * @param centralClientMode - Whether the device is in central client mode. Defaults to false
-   * @param clearBleCache - Whether the BLE cache should be cleared. Defaults to true
-   * @param certificates - Two-dimensional array of base64 strings representing DER encoded X.509 certificate which are used to authenticate the verifier app
-   * @param promise - The promise which will be resolved in case of success or rejected in case of failure.
+   * Resolves to true or rejects with an error code defined in [ModuleErrorCodes].
+   * @param peripheralMode whether the device is in peripheral mode. Defaults to true
+   * @param centralClientMode whether the device is in central client mode. Defaults to false
+   * @param clearBleCache whether the BLE cache should be cleared. Defaults to true
+   * @param certificates two-dimensional array of base64 strings representing DER encoded X.509 certificate which are used to authenticate the verifier app
+   * @param promise the promise which will be resolved in case of success or rejected in case of failure.
    */
   @ReactMethod
   fun start(
@@ -64,37 +62,14 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
       setupProximityHandler()
       promise.resolve(true)
     } catch (e: Exception) {
-      print(e)
-      ModuleException.START_ERROR.reject(
-        promise,
-        Pair(ERROR_KEY, getExceptionMessageOrEmpty(e))
-      )
+      promise.reject(ModuleErrorCodes.START_ERROR, e.message, e)
     }
   }
 
-  /**
-   * Utility function to parse an array coming from the React Native Bridge into an ArrayList
-   * of ByteArray representing DER encoded X.509 certificates.
-   * @param certificates - Two-dimensional array of base64 strings representing DER encoded X.509 certificate
-   * @returns An ArrayList of ByteArray representing DER encoded X.509 certificates.
-   * @throws ClassCastException if the element in the array is not a string
-   */
-  private fun parseCertificates(certificates: ReadableArray): List<List<ByteArray>> =
-    (0 until certificates.size())
-      .mapNotNull { chainIndex -> certificates.getArray(chainIndex) }
-      .map { chain ->
-        (0 until chain.size())
-          .mapNotNull { certIndex ->
-            chain.takeIf { it.getType(certIndex) == ReadableType.String }
-              ?.getString(certIndex)
-              ?.let { Base64Utils.decodeBase64(it) }
-          }
-      }
-
   /**
    * Creates a QR code to be scanned in order to initialize the presentation.
-   * Resolves with the QR code strings.
-   * @param promise - The promise which will be resolved in case of success or rejected in case of failure.
+   * Resolves with a string containing the QR code or rejects with an error code defined in [ModuleErrorCodes].
+   * @param promise the promise which will be resolved in case of success or rejected in case of failure.
    */
   @ReactMethod
   fun getQrCodeString(promise: Promise) {
@@ -103,20 +78,19 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
         val qrCodeString = it.getQrCodeString()
         promise.resolve(qrCodeString)
       } ?: run {
-        ModuleException.QR_ENGAGEMENT_NOT_DEFINED_ERROR.reject(promise)
+        promise.reject(ModuleErrorCodes.QR_ENGAGEMENT_NOT_DEFINED,NOT_INITIALIZED_ERROR_MESSAGE)
       }
     } catch (e: Exception) {
-      ModuleException.GET_QR_CODE_ERROR.reject(
-        promise,
-        Pair(ERROR_KEY, getExceptionMessageOrEmpty(e))
-      )
+      promise.reject(ModuleErrorCodes.GET_QR_CODE_ERROR, e.message, e)
     }
   }
 
   /**
    * Closes the bluetooth connection and clears any resource.
-   * It resolves to true after closing the connection.
-   * @param promise - The promise which will be resolved in case of success or rejected in case of failure.
+   * Resolves to true after closing the connection or rejects with an error code
+   * defined in [ModuleErrorCodes].
+   * @param promise the promise which will be resolved in case of success or rejected
+   * in case of failure.
    */
   @ReactMethod
   fun close(promise: Promise) {
@@ -125,21 +99,21 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
       deviceRetrievalHelper?.disconnect()
       promise.resolve(true)
     } catch (e: Exception) {
-      ModuleException.CLOSE_ERROR.reject(
-        promise,
-        Pair(ERROR_KEY, getExceptionMessageOrEmpty(e))
-      )
+      promise.reject(ModuleErrorCodes.CLOSE_ERROR, message=e.message, e)
     }
   }
 
   /**
-   * Sends an error response during the presentation according to the SessionData status codes defined in table 20 of the ISO18013-5 standard.
-   * @param code - The status error to be sent is a long type but the bridge only maps double values. It is converted to a long.
+   * 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 with an error code defined in [ModuleErrorCodes].
+   * @param code the status error to be sent is a long type but the bridge only maps
+   * double values. It is converted to a long.
    * The accepted values are defined in ``SessionDataStatus`` as follows:
    *  10 -> Error: session encryption
    *  11 -> Error: CBOR decoding
    *  20 -> Session termination
-   * @param promise - The promise which will be resolved in case of success or rejected in case of failure.
+   * @param promise the promise which will be resolved in case of success or rejected in case of failure.
    */
   @ReactMethod
   fun sendErrorResponse(code: Double, promise: Promise) {
@@ -150,37 +124,46 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
           it.sendErrorResponse(sessionDataStatus)
           promise.resolve(true)
         } else {
-          ModuleException.SEND_ERROR_RESPONSE_ERROR.reject(
-            promise,
-            Pair(ERROR_KEY, "Invalid status code")
-          )
+          promise.reject(ModuleErrorCodes.SEND_ERROR_RESPONSE_ERROR, message="Invalid status code")
         }
       } ?: run {
-        ModuleException.QR_ENGAGEMENT_NOT_DEFINED_ERROR.reject(promise)
+        promise.reject(ModuleErrorCodes.QR_ENGAGEMENT_NOT_DEFINED, message=NOT_INITIALIZED_ERROR_MESSAGE)
       }
     } catch (e: Exception) {
-      ModuleException.SEND_ERROR_RESPONSE_ERROR.reject(
-        promise,
-        Pair(ERROR_KEY, getExceptionMessageOrEmpty(e))
-      )
+      promise.reject(ModuleErrorCodes.SEND_ERROR_RESPONSE_ERROR, message=e.message, e)
     }
   }
 
   /**
    * Generates a response which can later be sent with {sendResponse} with the provided
    * CBOR documents and the requested attributes.
-   * @param documents - A {ReadableArray} containing documents. Each document is defined as a map containing:
+   * Resolves with a base64 encoded response or rejects with an error code defined in [ModuleErrorCodes].
+   * @param documents [ReadableArray] containing documents. Each document is defined as a map containing:
    * - issuerSignedContent which is a base64 or base64url encoded string representing the credential;
    * - alias which is the alias of the key used to sign the credential;
    * - docType which is the document type.
-   * @param fieldRequestedAndAccepted - The string containing the requested attributes. This is based on the request
-   * provided by the {onDocumentRequestReceived} callback.
-   * @param promise - The promise which will be resolved in case of success or rejected in case of failure.
+   * @param acceptedFields A dictionary of elements, where each element must adhere to a Map<String, Map<String, Map<String,Boolean>>>.
+   * 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,
+   *        "given_name_national_character": true,
+   *        "family_name_national_character": true,
+   *        "given_name": true,
+   *      },
+   *      {...}
+   *    },
+   *   {...}
+   * }
+   * ```
+   * @param promise The promise which will be resolved in case of success or rejected in case of failure.
    */
   @ReactMethod
   fun generateResponse(
     documents: ReadableArray,
-    fieldRequestedAndAccepted: ReadableMap,
+    acceptedFields: ReadableMap,
     promise: Promise
   ) {
     try {
@@ -190,37 +173,32 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
 
         val sessionTranscript = devHelper.sessionTranscript()
         val responseGenerator = ResponseGenerator(sessionTranscript)
+        val parsedAcceptedFields = parseAcceptedFields(acceptedFields)
         responseGenerator.createResponse(docRequestedList,
-          fieldRequestedAndAccepted.toString(),
+          parsedAcceptedFields,
           object : ResponseGenerator.Response {
             override fun onResponseGenerated(response: ByteArray) {
               promise.resolve(Base64Utils.encodeBase64(response))
             }
 
             override fun onError(message: String) {
-              ModuleException.GENERATE_RESPONSE_ERROR.reject(
-                promise,
-                Pair(ERROR_KEY, message)
-              )
+              promise.reject(ModuleErrorCodes.GENERATE_RESPONSE_ERROR, message)
             }
           })
       } ?: run {
-        ModuleException.DRH_NOT_DEFINED.reject(promise)
+        promise.reject(ModuleErrorCodes.DRH_NOT_DEFINED, message=NOT_INITIALIZED_ERROR_MESSAGE)
       }
     } catch (e: Exception) {
-      ModuleException.GENERATE_RESPONSE_ERROR.reject(
-        promise,
-        Pair(ERROR_KEY, getExceptionMessageOrEmpty(e))
-      )
+      promise.reject(ModuleErrorCodes.GENERATE_RESPONSE_ERROR, message=e.message, e)
     }
   }
 
   /**
    * Sends a response containing the documents and the fields which the user decided to present generated by {generateResponse}.
-   * It resolves to true after sending the response, otherwise it rejects if an error occurs while decoding the response.
    * Currently there's not evidence of the verifier app responding to this request, thus we don't handle the response.
-   * @param response - A base64 encoded string containing the response generated by {generateResponse}
-   * @param promise - The promise which will be resolved in case of success or rejected in case of failure.
+   * Resolves with a true boolean in case of success or rejects with an error code defined in [ModuleErrorCodes].
+   * @param response base64 encoded string containing the response generated by {generateResponse}
+   * @param promise the promise which will be resolved in case of success or rejected in case of failure.
    */
   @ReactMethod
   fun sendResponse(response: String, promise: Promise) {
@@ -231,70 +209,77 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
         promise.resolve(true)
       }
         ?: run {
-          ModuleException.QR_ENGAGEMENT_NOT_DEFINED_ERROR.reject(promise)
+          promise.reject(ModuleErrorCodes.QR_ENGAGEMENT_NOT_DEFINED, message=NOT_INITIALIZED_ERROR_MESSAGE)
         }
     } catch (e: Exception) {
-      ModuleException.SEND_RESPONSE_ERROR.reject(
-        promise,
-        Pair(ERROR_KEY, getExceptionMessageOrEmpty(e))
-      )
+      promise.reject(ModuleErrorCodes.SEND_RESPONSE_ERROR, e.message, e)
     }
   }
 
+  /**
+   * Generates a CBOR encoded device response for ISO 18013-7 mDL remote presentation using OID4VP.
+   * Resolves with the base64 encoded device response or rejects with an error code
+   * defined in [ModuleErrorCodes].
+   * @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 [ReadableArray] containing documents. Each document is defined as a map containing:
+   * - issuerSignedContent which is a base64 or base64url encoded string representing the credential;
+   * - alias which is the alias of the key used to sign the credential;
+   * - docType which is the document type.
+   * @param acceptedFields dictionary of elements, where each element must adhere to a Map<String, Map<String, Map<String,Boolean>>>.
+   * 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,
+   *        "given_name_national_character": true,
+   *        "family_name_national_character": true,
+   *        "given_name": true,
+   *      }
+   *    }
+   * }
+   * ```
+   * @param promise the promise which will be resolved in case of success or rejected in case of failure.
+   */
   @ReactMethod
   fun generateOID4VPDeviceResponse(
     clientId: String, responseUri: String, authorizationRequestNonce: String,
     mdocGeneratedNonce: String, documents: ReadableArray,
-    fieldRequestedAndAccepted: String, promise: Promise
+    acceptedFields: ReadableMap, promise: Promise
   ) {
-    val sessionTranscript = try {
-      OpenID4VP(
-        clientId,
-        responseUri,
-        authorizationRequestNonce,
-        mdocGeneratedNonce
-      ).createSessionTranscript()
-    } catch (e: Exception) {
-      ModuleException.UNABLE_TO_GENERATE_TRANSCRIPT.reject(
-        promise,
-        Pair(ERROR_USER_INFO_KEY, e.message.orEmpty())
-      )
-      return
-    }
+    try {
+      val sessionTranscript =
+        OpenID4VP(
+          clientId,
+          responseUri,
+          authorizationRequestNonce,
+          mdocGeneratedNonce
+        ).createSessionTranscript()
 
-    val documentsParsed = try {
-      parseDocRequested(documents)
-    } catch (e: Exception) {
-      ModuleException.INVALID_DOC_REQUESTED.reject(
-        promise,
-        Pair(ERROR_USER_INFO_KEY, e.message.orEmpty())
-      )
-      return
-    }
+      val documentsParsed =
+        parseDocRequested(documents)
+
+      val parsedAcceptedFields = parseAcceptedFields(acceptedFields)
 
-    try {
       val responseGenerator = ResponseGenerator(sessionTranscript)
       responseGenerator.createResponse(
         documentsParsed,
-        fieldRequestedAndAccepted,
+        parsedAcceptedFields,
         object : ResponseGenerator.Response {
           override fun onResponseGenerated(response: ByteArray) {
             promise.resolve(Base64Utils.encodeBase64(response))
           }
 
           override fun onError(message: String) {
-            ModuleException.UNABLE_TO_GENERATE_RESPONSE.reject(
-              promise,
-              Pair(ERROR_USER_INFO_KEY, message)
-            )
+            promise.reject(ModuleErrorCodes.GENERATE_OID4VP_RESPONSE_ERROR, message)
           }
         }
       )
     } catch (e: Exception) {
-      ModuleException.UNABLE_TO_GENERATE_RESPONSE.reject(
-        promise,
-        Pair(ERROR_USER_INFO_KEY, e.message.orEmpty())
-      )
+      promise.reject(ModuleErrorCodes.GENERATE_OID4VP_RESPONSE_ERROR, e.message, e)
     }
   }
 
@@ -339,41 +324,6 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
     })
   }
 
-  /**
-   * Utility function which extracts the document shape we expect to receive from the bridge
-   * in the one expected by {DocRequested}.
-   * @param documents - A {ReadableArray} containing documents. Each document is defined as a map containing:
-   * - issuerSignedContent which is a base64 or base64url encoded string representing the credential;
-   * - alias which is the alias of the key used to sign the credential;
-   * - docType which is the document type.
-   * @returns An array containing a {DocRequested} object for each document in {documents}
-   * @throws IllegalArgumentException if the provided document doesn't adhere to the expected format
-   */
-  private fun parseDocRequested(documents: ReadableArray): Array<DocRequested> {
-    return (0 until documents.size()).map { i ->
-      val entry = documents.getMap(i)
-        ?: throw IllegalArgumentException("Entry in ReadableArray is null")
-
-      val alias = entry.getString("alias")
-      val issuerSignedContentStr = entry.getString("issuerSignedContent")
-      val docType = entry.getString("docType")
-
-      if (
-        alias == null || entry.getType("alias") != ReadableType.String ||
-        issuerSignedContentStr == null || entry.getType("issuerSignedContent") != ReadableType.String ||
-        docType == null || entry.getType("docType") != ReadableType.String
-      ) throw IllegalArgumentException("Unable to decode the provided documents")
-
-      val issuerSignedContent = Base64Utils.decodeBase64AndBase64Url(issuerSignedContentStr)
-
-      DocRequested(
-        issuerSignedContent,
-        alias,
-        docType
-      )
-    }.toTypedArray()
-  }
-
   /**
    * Wrapper function to send an event via `RCTEventEmitter`
    * @param eventName - The event name
@@ -398,44 +348,165 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
     */
   }
 
-  private enum class ModuleException(
-    val ex: Exception
-  ) {
-    /** ISO18013-5 related errors **/
-    DRH_NOT_DEFINED(Exception("DRH_NOT_DEFINED")),
-    QR_ENGAGEMENT_NOT_DEFINED_ERROR(Exception("QR_ENGAGEMENT_NOT_DEFINED_ERROR")),
-    START_ERROR(Exception("START_ERROR")),
-    GET_QR_CODE_ERROR(Exception("GET_QR_CODE_ERROR")),
-    GENERATE_RESPONSE_ERROR(Exception("GENERATE_RESPONSE_ERROR")),
-    SEND_RESPONSE_ERROR(Exception("SEND_RESPONSE_ERROR")),
-    SEND_ERROR_RESPONSE_ERROR(Exception("SEND_ERROR_RESPONSE_ERROR")),
-    CLOSE_ERROR(Exception("CLOSE_ERROR")),
-
-    /** ISO18013-7 related errors **/
-    UNABLE_TO_GENERATE_RESPONSE(Exception("UNABLE_TO_GENERATE_RESPONSE")),
-    UNABLE_TO_GENERATE_TRANSCRIPT(Exception("UNABLE_TO_GENERATE_TRANSCRIPT")),
-    INVALID_DOC_REQUESTED(Exception("INVALID_DOC_REQUESTED")),
-    GENERATE_OID4VP_DEVICE_RESPONSE_FAILED(Exception("GENERATE_OID4VP_DEVICE_RESPONSE_FAILED"));
-
-    fun reject(
-      promise: Promise, vararg args: Pair<String, String>
-    ) {
-      exMap(*args).let {
-        promise.reject(it.first, ex.message, it.second)
-      }
+  companion object {
+    const val NAME = "IoReactNativeIso18013"
+    const val NOT_INITIALIZED_ERROR_MESSAGE = "Resources not initialized properly, call the start method before this one."
+
+    // Errors which this module uses to reject a promise
+    private object ModuleErrorCodes {
+      // ISO18013-5 related errors
+      const val DRH_NOT_DEFINED = "DRH_NOT_DEFINED"
+      const val QR_ENGAGEMENT_NOT_DEFINED = "QR_ENGAGEMENT_NOT_DEFINED"
+      const val START_ERROR = "START_ERROR"
+      const val GET_QR_CODE_ERROR = "GET_QR_CODE_ERROR"
+      const val GENERATE_RESPONSE_ERROR = "GENERATE_RESPONSE_ERROR"
+      const val SEND_RESPONSE_ERROR = "SEND_RESPONSE_ERROR"
+      const val SEND_ERROR_RESPONSE_ERROR = "SEND_ERROR_RESPONSE_ERROR"
+      const val CLOSE_ERROR = "CLOSE_ERROR"
+
+      // ISO18013-7 related errors
+      const val GENERATE_OID4VP_RESPONSE_ERROR = "GENERATE_OID4VP_RESPONSE_ERROR"
     }
 
-    private fun exMap(vararg args: Pair<String, String>): Pair<String, WritableMap> {
-      val writableMap = WritableNativeMap()
-      args.forEach { writableMap.putString(it.first, it.second) }
-      return Pair(this.ex.message ?: "UNKNOWN", writableMap)
+    /**
+     * Utility function which checks if the input map is consistent with what we expects before parsing
+     * it to a string.
+     * It loops through each credential and each namespace, checking if the accepted fields contain
+     * a boolean value.
+     * @param acceptedFields - A map contained the accepted fields to be presented with the following shape:
+     * {
+     * "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,
+     *    },
+     *    {...}
+     *   },
+     *   {...}
+     * }
+     * @throw IllegalArgumentException if the ReadableMap is not consistent or contains an invalid value
+     * @returns String representation of [acceptedFields]
+     */
+    fun parseAcceptedFields(acceptedFields: ReadableMap): String {
+      try {
+        // Loop for each credential and throw if something different than map is found
+        acceptedFields.entryIterator.forEach { credentialEntry ->
+          val credentialName = credentialEntry.key
+          val credentialValue = credentialEntry.value
+          if (credentialValue !is ReadableMap) {
+            throw IllegalArgumentException("Credential '$credentialName' must be a map")
+          }
+
+          // If no namespace is found then throw
+          if(!credentialValue.entryIterator.hasNext()){
+            throw IllegalArgumentException("Credential '$credentialName' must define at least one namespace")
+          }
+
+          // Loop for each namespace in credential and throw if something different than map is found
+          credentialValue.entryIterator.forEach { namespaceEntry ->
+            val namespaceName = namespaceEntry.key
+            val namespaceValue = namespaceEntry.value
+            if (namespaceValue !is ReadableMap) {
+              throw IllegalArgumentException("Namespace '$namespaceName' in credential '$credentialName' must be a map")
+            }
+
+            // If no field is found then throw
+            if(!namespaceValue.entryIterator.hasNext()){
+              throw IllegalArgumentException("Credential '$credentialName' with namespace `$namespaceName` must define at least one field")
+            }
+
+            // Loop for each field in namespace and throw if something different than boolean is found
+            namespaceValue.entryIterator.forEach { fieldEntry ->
+              val fieldName = fieldEntry.key
+              val fieldValue = fieldEntry.value
+              if (fieldValue !is Boolean) {
+                throw IllegalArgumentException("Field '$fieldName' in namespace '$namespaceName' of credential '$credentialName' must be a boolean")
+              }
+            }
+          }
+        }
+        // If no exception is thrown then we can convert it to string
+        return acceptedFields.toString()
+      } catch (e: Exception) {
+        throw IllegalArgumentException("Failed to parse accepted fields: ${e.message}", e)
+      }
     }
-  }
 
-  private fun getExceptionMessageOrEmpty(e: Exception): String = e.message ?: ""
+    /**
+     * Utility function which extracts the document shape we expect to receive from the bridge
+     * in the one expected by {DocRequested}.
+     * @param documents a {ReadableArray} containing documents. Each document is defined as a map containing:
+     * - issuerSignedContent which is a base64 or base64url encoded string representing the credential;
+     * - alias which is the alias of the key used to sign the credential;
+     * - docType which is the document type.
+     * @returns an array containing a {DocRequested} object for each document in {documents}
+     * @throws IllegalArgumentException if the provided document doesn't adhere to the expected format
+     */
+    fun parseDocRequested(documents: ReadableArray): Array<DocRequested> {
+      return try {
+        (0 until documents.size()).map { i ->
+          val entry = documents.getMap(i)
+            ?: throw IllegalArgumentException("Entry at index $i in ReadableArray is null")
+          val alias = entry.getString("alias")
+          val issuerSignedContentStr = entry.getString("issuerSignedContent")
+          val docType = entry.getString("docType")
+
+          if (
+            alias == null || entry.getType("alias") != ReadableType.String ||
+            issuerSignedContentStr == null || entry.getType("issuerSignedContent") != ReadableType.String ||
+            docType == null || entry.getType("docType") != ReadableType.String
+          ) throw IllegalArgumentException("Unable to decode the provided documents at index $i")
+
+          val issuerSignedContent = Base64Utils.decodeBase64AndBase64Url(issuerSignedContentStr)
+
+          DocRequested(
+            issuerSignedContent,
+            alias,
+            docType
+          )
+        }.toTypedArray()
+      } catch (e: Exception) {
+        throw IllegalArgumentException("Failed to parse documents: ${e.message}", e)
+      }
+    }
 
-  companion object {
-    const val NAME = "IoReactNativeIso18013"
-    const val ERROR_KEY = "error"
+    /**
+     * Utility function to parse an array coming from the React Native Bridge into an ArrayList
+     * of ByteArray representing DER encoded X.509 certificates.
+     * @param certificates two-dimensional array of base64 strings representing DER encoded X.509 certificate
+     * @returns ArrayList of ByteArray representing DER encoded X.509 certificates.
+     * @throws IllegalArgumentException if an element in the array is not base64 encoded
+     */
+    fun parseCertificates(certificates: ReadableArray): List<List<ByteArray>> =
+      /** Map the chain arrays and remove null entries. On each chain call the getArray method which
+       * can throw and if it does rethrow an exception with information on its position
+       */
+      (0 until certificates.size()).mapNotNull { chainIndex ->
+        val chain = runCatching { certificates.getArray(chainIndex) }
+          .getOrElse { throw IllegalArgumentException("Certificate chain at $chainIndex is not an array", it) }
+          ?: throw IllegalArgumentException("Certificate chain at index $chainIndex is null")
+
+        /**
+         * Map each chain certificate and remove null entries. On each certificate call the getString
+         * method which can throw and if it does rethrow an exception with information on its position
+         */
+        (0 until chain.size()).mapNotNull { certIndex ->
+          val base64 = runCatching { chain.getString(certIndex) }
+            .getOrElse { throw IllegalArgumentException("Failed to get certificate string at chain $chainIndex, cert $certIndex", it) }
+            ?: throw java.lang.IllegalArgumentException("Certificate at index $certIndex is null")
+
+          /**
+           * Decode the base64 string for each mapped certificate and if an error occurs rethrow
+           * an exception with information on its position
+           */
+          runCatching {
+            Base64Utils.decodeBase64(base64)
+          }.getOrElse {
+            throw IllegalArgumentException("Certificate at index $certIndex in the chain at index $chainIndex is not a valid base64 string", it)
+          }
+        }
+      }
   }
 }

package/android/src/test/java/com/ioreactnativeiso18013/Base64UtilsTest.kt

@@ -0,0 +1,66 @@
+package com.ioreactnativeiso18013
+import org.junit.Assert.assertThrows
+import org.junit.Test
+
+data class Base64Data(
+  val array: ByteArray,
+  val string: String
+)
+
+class Base64UtilsTest {
+  private val base64 = Base64Data(
+    array = byteArrayOf(116, 101, 115, 116),
+    string = "dGVzdA=="
+  )
+
+  private val base64url = Base64Data(
+    array = byteArrayOf(60, 60, 63, 63, 63, 62, 62),
+    string = "PDw/Pz8+Pg=="
+  )
+
+  private val invalidBase64 = "123~"
+
+  @Test
+  fun `should convert a base64url string into a byte array`() {
+    val decodedArray = Base64Utils.decodeBase64AndBase64Url(base64url.string)
+    assert(decodedArray.contentEquals(base64url.array))
+  }
+
+  @Test
+  fun `should convert a base64 string into a byte array`() {
+    val decodedArray = Base64Utils.decodeBase64AndBase64Url(base64.string)
+    assert(decodedArray.contentEquals(base64.array))
+  }
+
+  @Test
+  fun `should throw IllegalArgumentException with an invalid string while decoding base64 or base64url string`() {
+    assertThrows(
+      IllegalArgumentException::class.java
+    ) {
+      Base64Utils.decodeBase64AndBase64Url(invalidBase64)
+    }
+  }
+
+    @Test
+    fun `should encode a byte array into a base64 string`() {
+      val encodedArray = Base64Utils.encodeBase64(base64.array)
+      assert(encodedArray == base64.string)
+    }
+
+
+    @Test
+    fun `should decode a base64 string into a byte array`() {
+      val encodedArray = Base64Utils.decodeBase64(base64.string)
+      assert(encodedArray.contentEquals(base64.array))
+    }
+
+    @Test
+    fun `should throw IllegalArgumentException with an invalid string while decoding base64`() {
+      assertThrows(
+        IllegalArgumentException::class.java
+      ) {
+        Base64Utils.decodeBase64(invalidBase64)
+      }
+    }
+}
+