MIRACL Trust Flutter Plugin

The MIRACL Trust Flutter Plugin provides the following functionalities:

• User ID Verification
• Registration
• Authentication
• Signing
• Cross-Device Session
• QuickCode
• User Management

This plugin implements method-channel communication with MIRACL’s iOS and Android SDKs. It leverages the Pigeon framework to generate type-safe method-channel communication.

System Requirements

• iOS 13+
• Android API 21+

Installation

Add flutter_miracl_sdk to pubspec.yaml:

dependencies:
    flutter_miracl_sdk: ^0.12.0

If your application uses Cocoapods as an iOS dependency manager, add the MIRACL Trust iOS SDK podspec source to your Podfile:

source 'https://github.com/miracl/cocoapods-specs'
source 'https://github.com/CocoaPods/Specs'

For more information on how to work with Cocoapods sources check the documentation.

Usage

Import

Add this import to your dart file:

import 'package:flutter_miracl_sdk/flutter_miracl_sdk.dart';

Plugin Configuration

To configure the plugin:

1. Create an account in the MIRACL Trust platform. For information about how to do it, see the Getting Started guide.

2. Call the initialize method with a configuration created by the Configuration class using your project properties:

   final configuration = Configuration(
      projectId: "Project Id",
      projectUrl: "Project Domain"
   );
   
   await MIRACLTrust.initialize(configuration);

   Call the initialize method as early as possible in the application lifecycle, and avoid creating instance before that; otherwise, an assertion will be triggered.

Obtain instance of the plugin

To obtain an instance of the plugin, call the constructor:

MIRACLTrust miraclTrust = MIRACLTrust();

Exception handling

Most plugin methods can throw exceptions spcific for the operation. Each exception includes a code enum that indicates the origin of the exception (e.g., unsuccessful authentication).

Although exception handling is not mandatory in Dart, it is highly recommended that MIRACL Trust methods be wrapped in try/catch statements.

User ID Verification

To register a new User ID, you need to verify it. MIRACL offers two options for that:

• Custom User Verification

• Built-in User Verification

  With this type of verification, the end user's email address serves as the User ID. Currently, MIRACL Trust provides two kinds of built-in email verification methods:

  • Email Link (default)
  • Email Code

  Start the verification by calling the sendVerificationEmail method:

  try {
    final emailVerificationResponse = await miraclTrust.sendVerificationEmail(userId);
  } on EmailVerificationException catch(e) {
    // Handle the exception here.
  }

  Then, a verification email is sent, and a EmailVerificationResponse with backoff and email verification method is returned.

  If the verification method you have chosen for your project is:

  • Email Code:

    You must check the email verification method in the response.

    • If the end user is registering for the first time or resetting their PIN, an email with a verification code will be sent, and the email verification method in the response will be EmailVerificationMethod.code. Then, ask the user to enter the code in the application.

    • If the end user has already registered another device with the same User ID, a Verification URL will be sent, and the verification method in the response will be EmailVerificationMethod.link. In this case, proceed as described for the Email Link verification method below.

  • Email Link: Your application must open when the end user follows the Verification URL in the email. To ensure proper deep linking behaviour on mobile applications, check this guide package. To associate your application with the email Verification URL, use the Android association field in Mobile Applications under Configuration in the MIRACL Trust Portal.

Registration

1. To register the mobile device, get an activation token. This happens in two different ways, depending on the type of verification.

   • Custom User Verification or Email Link:

     After the application recieves the Verification URL, it must confirm the verification by passing it to the getActivationTokenByURI method:

     try {
       final activationTokenResponse = await miraclTrust.getActivationTokenByURI(verificationURL);
     } on ActivationTokenException catch(e) {
       // Handle the exception here.
     }

   • Email Code:

     When the end user enters the verification code, the application must confirm the verification by passing it to the getActivationTokenByUserIdAndCode method:

     try {
       final activationTokenResponse =
          await miraclTrust.getActivationTokenByUserIdAndCode(userId, code);
     } on ActivationTokenException catch(e) {
       // Handle the exception here.
     }

2. Pass the User ID (email or any string you use for identification), activation token (received from verification) and the user-entered PIN code to the register method:

    try {
      final user = await miraclTrust.register(
          userId,
          activationTokenResponse.activationToken,
          pin
      );
    } on RegistrationException catch(e) {
      // Handle the exception here.
    }

   If you call the register method with the same User ID more than once, the User ID will be overridden. Therefore, you can use it to reset your authentication PIN code.

Authentication

То authenticate users on your mobile application, call the authenticate method. If the authentication is successful, a JWT authentication token is generated for a registered user.

try {
  final token = await miraclTrust.authenticate(user, pin);
  // Send token to your server for verification.
} on AuthenticationException catch(e) {
  // Handle the exception here.
}

After the JWT authentication token is generated, it must be sent to the application server for verification. Then, the application server verifies the token signature using the MIRACL Trust JWKS endpoint and the audience claim, which in this case is the application Project ID.

Signing

DVS stands for Designated Verifier Signature, which is a protocol for cryptographic signing of documents. For more information, see Designated Verifier Signature. In the context of this plugin, we refer to it as 'Signing'.

To sign a document, use the sign method as follows:

try {
  final signingResult = await miraclTrust.sign(user, message, pin);
} on SigningException catch(e) {
  // Handle the exception here.
}

The signature must be verified by sending it to the application server, which then makes a call to the POST /dvs/verify endpoint. If the MIRACL Trust platform returns a status code 200, the certificate entry in the response body indicates that the signing is successful.

Cross-Device Session

The MIRACL Trust Flutter Plugin provides an API for handling cross-device sessions initiated from external applications, allowing users to authenticate or sign documents on a mobile device. A cross-device session is created by calling the createCrossDeviceSession method of the MIRACL Trust Client JS Library. Then it can be fetched via deep links, QR codes, or push notifications. Once the cross-device session is successfully fetched, you can proceed to authenticate the end user or sign a document using the corresponding SDK methods. If the session is no longer needed, you can abort it to cancel the current cross-device operation.

Fetch the Cross-Device Session

Depending on how the cross-device session is initiated, there are three options to fetch it:

• Via deep link

  Use the getCrossDeviceSessionFromLink method:

  try {
    final crossDeviceSession = await miraclTrust.getCrossDeviceSessionFromLink(link);
    // Use the crossDeviceSession to authenticate or sign.
  } on CrossDeviceSessionException catch(e) {
    // Handle the exception here.
  }

• Via QR code:

  Use the getCrossDeviceSessionFromQRCode method:

  try {
    final crossDeviceSession = await miraclTrust.getCrossDeviceSessionFromQRCode(qrCode);
    // Use the crossDeviceSession to authenticate or sign.
  } on CrossDeviceSessionException catch(e) {
    // Handle the exception here.
  }

• Via push notification:

  Use the getCrossDeviceSessionFromPushNotificationPayload method:

  try {
    final crossDeviceSession = await miraclTrust.getCrossDeviceSessionFromPushNotificationPayload(payload);
    // Use the crossDeviceSession to authenticate or sign.
  } on CrossDeviceSessionException catch(e) {
    // Handle the exception here.
  }

After fetching the cross-device session, you can proceed with either authentication or document signing. To determine which operation the session is intended for, check its type property.

Authenticate with the Cross-Device Session

Authenticate using the authenticateCrossDeviceSession method:

try {
  await miraclTrust.authenticateCrossDeviceSession(crossDeviceSession, user, pin);
  // The cross-device session is authenticated.
} on AuthenticationException catch(e) {
  // Handle the exception here.
}

Sign with the Cross-Device Session

Sign a document using the signCrossDeviceSession method:

try {
  await miraclTrust.signCrossDeviceSession(crossDeviceSession, user, pin);
  // The cross-device session is signed.
} on SigningException catch(e) {
  // Handle the exception here.
}

Abort the Cross-Device Session

To cancel the handling of the cross-device session, call the abortCrossDeviceSession method:

try {
  await miraclTrust.abortCrossDeviceSession(crossDeviceSession);
  // The cross-device session is aborted.
} on CrossDeviceSession catch(e) {
  // Handle the exception here.
}

QuickCode

QuickCode is a way to register another device without going through the verification process.

To generate a QuickCode, call the generateQuickCode method with an already registered User object:

try {
  final quickCode = await miraclTrust.generateQuickCode(user, pin);
} on QuickCodeException catch(e) {
  // Handle the exception here.
}

User Management

The MIRACL Trust Flutter plugin provides several methods for managing users registered on a device. These operations allow you to retrieve user information or delete previously registered users.

Get a registered user

To retrieve a specific registered user by their User ID, use the getUser method:

try {
  final user = await miraclTrust.getUser(userId);
  if (user != null) {
    // User exists.
  } else {
    // No user registered with this User ID.
  }
} catch (e) {
  // Cannot retrieve the user due to an error.
}

Get all registered users

To obtain the list of all users registered on а device, call the getUsers method:

try {
  final users = await miraclTrust.getUsers();
  // Handle list of registered users.
} catch (e) {
  // Cannot retrieve users due to an error.
}

Delete a registered user

To delete a previously registered user from a device, call the delete method:

try {
  await miraclTrust.delete(user);
  // User deleted successfully.
} catch (e) {
  // Cannot delete the user due to an error.
}

FAQ

1. What is Activation Token?

   Activation Token is the value that links the verification flow with the registration flow. The value is returned by the verification flow and needs to be passed to the register method so the platform can verify it. Here are the options for that:

   • Custom User Verification
   • Built-in User Verification

2. What is Project ID?

   Project ID is a common identifier of applications in the MIRACL Trust platform that share a single owner.

   You can find the Project ID value in the MIRACL Trust Portal:

   1. Go to trust.miracl.cloud.
   2. Log in or create a new User ID.
   3. Select your project.
   4. In the CONFIGURATION section, go to General.
   5. Copy the Project ID value.