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

package/README.md

@@ -10,12 +10,17 @@ npm install @pagopa/io-react-native-iso18013
 
 ## Usage
 
-Each module is documented in its own README file:
+This library includes two native modules for both iOS and Android:
 
-- [ISO18013-5](src/iso18013/iso18013-5/README.md): Proximity presentation according to the ISO 18013-5 standard;
-- [ISO18013-7](src/iso18013/iso18013-7/README.md): Remote presentation according to the ISO 18013-7 standard;
-- [CBOR](src/cbor/cbor/README.md): Decoding of CBOR data into readable objects;
-- [COSE](src/cbor/cose/README.md): Management of COSE verify and sign operations.
+- [IoReactNativeIso18013](src/iso18013/iso18013-5/proximity.ts) for ISO 18013-5 and ISO 18013-7 implementations;
+- [IoReactNativeCbor](src/cbor/cbor.ts) for CBOR and COSE implementations.
+
+On the javascript side, the library exposes the following modules:
+
+- [ISO18013-5](src/iso18013/iso18013-5/README.md): Proximity presentation according to the ISO 18013-5 standard which is part of the `IoReactNativeIso18013` module;
+- [ISO18013-7](src/iso18013/iso18013-7/README.md): Remote presentation according to the ISO 18013-7 standard which is part of the `IoReactNativeIso18013` module;
+- [CBOR](src/cbor/cbor/README.md): Decoding of CBOR data into readable objects which is part of the `IoReactNativeCbor` module;
+- [COSE](src/cbor/cose/README.md): Management of COSE verify and sign operations which is part of the `IoReactNativeCbor` module.
 
 ## Contributing
 

package/android/build.gradle

@@ -65,6 +65,12 @@ android {
     sourceCompatibility JavaVersion.VERSION_1_8
     targetCompatibility JavaVersion.VERSION_1_8
   }
+
+   testOptions {
+      unitTests.all {
+          useJUnit()
+      }
+    }
 }
 
 repositories {
@@ -79,5 +85,5 @@ dependencies {
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "it.pagopa.io.wallet.proximity:proximity:2.1.0"
   implementation "it.pagopa.io.wallet.cbor:cbor:1.3.0"
+  testImplementation('junit:junit:4.13.2')
 }
-

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

@@ -16,6 +16,13 @@ class IoReactNativeCborModule(reactContext: ReactApplicationContext) :
     return NAME
   }
 
+  /**
+   * Decode base64 or base64url encoded CBOR data to JSON object.
+   * Resolves with a string containing the parsed data or rejects with an error code
+   * defined in [ModuleErrorCodes].
+   * This method does not handle nested CBOR data, which will need additional parsing.
+   * @param data the base64 or base64url encoded CBOR string
+   */
   @ReactMethod
   fun decode(data: String, promise: Promise) {
     try {
@@ -27,75 +34,100 @@ class IoReactNativeCborModule(reactContext: ReactApplicationContext) :
     }
   }
 
-
-    @ReactMethod
-    fun decodeDocuments(data: String, promise: Promise) {
-      try {
-        val buffer = Base64Utils.decodeBase64AndBase64Url(data)
-        CBorParser(buffer).documentsCborToJson(separateElementIdentifier = true, onComplete = {
-          promise.resolve(it)
-        }, onError = { e ->
-          promise.reject(ModuleErrorCodes.DECODE_DOCUMENTS_ERROR, e.message, e)
-        })
-      } catch (e: Exception) {
+  /**
+   * Decode base64 or base64url encoded mDOC-CBOR data to a JSON object.
+   * Resolves with a string containing the parsed data or rejects with an error code
+   * @param data the base64 or base64url encoded mDOC-CBOR string
+   */
+  @ReactMethod
+  fun decodeDocuments(data: String, promise: Promise) {
+    try {
+      val buffer = Base64Utils.decodeBase64AndBase64Url(data)
+      CBorParser(buffer).documentsCborToJson(separateElementIdentifier = true, onComplete = {
+        promise.resolve(it)
+      }, onError = { e ->
         promise.reject(ModuleErrorCodes.DECODE_DOCUMENTS_ERROR, e.message, e)
-      }
+      })
+    } catch (e: Exception) {
+      promise.reject(ModuleErrorCodes.DECODE_DOCUMENTS_ERROR, e.message, e)
     }
+  }
 
-    @ReactMethod
-    fun decodeIssuerSigned(issuerSigned: String, promise: Promise) {
-      try {
-        val buffer =
-          Base64Utils.decodeBase64AndBase64Url(issuerSigned)
-        val result =
-          CBorParser(buffer).issuerSignedCborToJson(separateElementIdentifier = true) ?: run {
-            // We don't have the exact error here for some reason
-            promise.reject(
-              ModuleErrorCodes.DECODE_ISSUER_SIGNED_ERROR,
-              "An error occurred while decoding the issuer signed content"
-            )
-          }
-        promise.resolve(result)
-      } catch (e: Exception) {
-        promise.reject(ModuleErrorCodes.DECODE_ISSUER_SIGNED_ERROR, e.message, e)
-      }
+  /**
+   * Decode base64 or base64url encoded issuerSigned attribute part of an mDOC-CBOR.
+   * @param data the base64 or base64url encoded mDOC-CBOR containing the issuerSigned data string
+   * Resolves with a string containing the parsed data or rejects with an error code
+   * defined in [ModuleErrorCodes].
+   */
+  @ReactMethod
+  fun decodeIssuerSigned(data: String, promise: Promise) {
+    try {
+      val buffer =
+        Base64Utils.decodeBase64AndBase64Url(data)
+      val result =
+        CBorParser(buffer).issuerSignedCborToJson(separateElementIdentifier = true) ?: run {
+          // We don't have the exact error here for some reason
+          promise.reject(
+            ModuleErrorCodes.DECODE_ISSUER_SIGNED_ERROR,
+            "An error occurred while decoding the issuer signed content"
+          )
+        }
+      promise.resolve(result)
+    } catch (e: Exception) {
+      promise.reject(ModuleErrorCodes.DECODE_ISSUER_SIGNED_ERROR, e.message, e)
     }
+  }
 
-    @ReactMethod
-    fun sign(payload: String, keyTag: String, promise: Promise){
+  /**
+   * Sign base64 encoded data with COSE and return the COSE-Sign1 object in base64 encoding.
+   * Resolves with a string containing the COSE-Sign1 object in base64 encoding or rejects with an
+   * error code defined in [ModuleErrorCodes].
+   * @param data the base64 or base64url encoded payload to sign
+   * @param keyTag the alias of the key to use for signing.
+   */
+  @ReactMethod
+  fun sign(data: String, keyTag: String, promise: Promise) {
     try {
-      val data = Base64Utils.decodeBase64AndBase64Url(payload)
-        val result = COSEManager().signWithCOSE(
-          data = data,
-          alias = keyTag
-        )
-        when (result) {
-          is SignWithCOSEResult.Failure -> {
-            // We don't have a throwable to pass here from the onError callback
-            promise.reject(ModuleErrorCodes.SIGN_ERROR, result.reason.msg)
-          }
-          is SignWithCOSEResult.Success -> {
-            promise.resolve(Base64Utils.encodeBase64(result.signature))
-          }
+      val buffer = Base64Utils.decodeBase64AndBase64Url(data)
+      val result = COSEManager().signWithCOSE(
+        data = buffer,
+        alias = keyTag
+      )
+      when (result) {
+        is SignWithCOSEResult.Failure -> {
+          // We don't have a throwable to pass here from the onError callback
+          promise.reject(ModuleErrorCodes.SIGN_ERROR, result.reason.msg)
+        }
+
+        is SignWithCOSEResult.Success -> {
+          promise.resolve(Base64Utils.encodeBase64(result.signature))
         }
-      } catch (e: Exception) {
-        promise.reject(ModuleErrorCodes.SIGN_ERROR, e.message, e)
       }
+    } catch (e: Exception) {
+      promise.reject(ModuleErrorCodes.SIGN_ERROR, e.message, e)
     }
+  }
 
-    @ReactMethod
-    fun verify(sign1Data: String, publicKey: ReadableMap, promise: Promise) {
-      try {
-      val data = Base64Utils.decodeBase64AndBase64Url(sign1Data)
-        val result = COSEManager().verifySign1FromJWK(
-          dataSigned = data,
-          jwk = publicKey.toString()
-        )
-        promise.resolve(result)
-      } catch (e: Exception) {
-       promise.reject(ModuleErrorCodes.VERIFY_ERROR, e.message, e)
-      }
+  /**
+   * Verifies a COSE-Sign1 object with the provided public key.
+   * Resolves with a boolean indicating whether or not the verification succeeded or not or rejects
+   * with an error code defined in [ModuleErrorCodes].
+   * @param data the COSE-Sign1 object in base64 or base64url encoding
+   * @param publicKey the public key in JWK format
+   */
+  @ReactMethod
+  fun verify(data: String, publicKey: ReadableMap, promise: Promise) {
+    try {
+      val buffer = Base64Utils.decodeBase64AndBase64Url(data)
+      val result = COSEManager().verifySign1FromJWK(
+        dataSigned = buffer,
+        jwk = publicKey.toString()
+      )
+      promise.resolve(result)
+    } catch (e: Exception) {
+      promise.reject(ModuleErrorCodes.VERIFY_ERROR, e.message, e)
     }
+  }
 
   companion object {
     const val NAME = "IoReactNativeCbor"

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

@@ -30,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(
@@ -66,48 +66,10 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
     }
   }
 
-  /**
-   * 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 IllegalArgumentException if an element in the array is not base64 encoded
-   */
-  private 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)
-        }
-      }
-    }
-
-
   /**
    * 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) {
@@ -125,8 +87,10 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
 
   /**
    * 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) {
@@ -140,13 +104,16 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
   }
 
   /**
-   * 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) {
@@ -170,18 +137,33 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
   /**
    * 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 {
@@ -191,8 +173,9 @@ 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))
@@ -212,10 +195,10 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
 
   /**
    * 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) {
@@ -233,11 +216,39 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
     }
   }
 
+  /**
+   * 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
   ) {
     try {
       val sessionTranscript =
@@ -251,10 +262,12 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
       val documentsParsed =
         parseDocRequested(documents)
 
+      val parsedAcceptedFields = parseAcceptedFields(acceptedFields)
+
       val responseGenerator = ResponseGenerator(sessionTranscript)
       responseGenerator.createResponse(
         documentsParsed,
-        fieldRequestedAndAccepted,
+        parsedAcceptedFields,
         object : ResponseGenerator.Response {
           override fun onResponseGenerated(response: ByteArray) {
             promise.resolve(Base64Utils.encodeBase64(response))
@@ -311,44 +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 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)
-    }
-  }
-
   /**
    * Wrapper function to send an event via `RCTEventEmitter`
    * @param eventName - The event name
@@ -392,5 +367,146 @@ class IoReactNativeIso18013Module(reactContext: ReactApplicationContext) :
       // ISO18013-7 related errors
       const val GENERATE_OID4VP_RESPONSE_ERROR = "GENERATE_OID4VP_RESPONSE_ERROR"
     }
+
+    /**
+     * 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)
+      }
+    }
+
+    /**
+     * 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)
+      }
+    }
+
+    /**
+     * 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)
+          }
+        }
+      }
   }
 }