MIRACL Trust Client JS Library

Installation

MIRACL Trust Client JS Library is available as an NPM package.

``sh
npm install --save @miracl/client-js
`

You can include the library in your build toolchain either as an ECMAScript or a
CommonJS module. The library provides both a Node-style callback interface and a
promise interface.

ESM:

`js
// Callback interface
import MIRACLTrust from "@miracl/client-js";
// Promise interface
import MIRACLTrust from "@miracl/client-js/promise";
`

CJS:

`js
// Callback interface
const MIRACLTrust = require("@miracl/client-js");
// Promise interface
const MIRACLTrust = require("@miracl/client-js/promise");
`

You can also use the pre-built browser version located in the dist/ directory:

`html




`

Usage

$3

To configure the library:

1. Create an application in the MIRACL Trust platform. For information about how
to do it, see the
Getting Started
guide.
2. Create a new instance of MIRACLTrust and pass the configuration as an object:

`js
const mcl = new MIRACLTrust({
projectUrl: "", // required
projectId: "", // required
seed: "hexEncodedRandomNumberGeneratorSeed", // required
userStorage: localStorage, // required
deviceName: "Name of Device",
cors: true,
});
`

The seed is used for initializing the random number generator necessary for the
security of the authentication protocol. Here is an example implementation
compatible with most browsers:

`js
function getLocalEntropy() {
const crypto = window.crypto || window.msCrypto;

if (typeof crypto === "undefined") {
throw new Error("Crypto API unavailable");
}

const buffer = new Uint32Array(8);
crypto.getRandomValues(buffer);

let entropyHex = "";
for (let i = 0; i < buffer.length; i++) {
entropyHex = entropyHex + buffer[i].toString(16);
}

return entropyHex;
}
`

$3

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

- Custom User Verification
- Built-in Email 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:

Promise:

`js
try {
const result = await mcl.sendVerificationEmail(userId);
console.log(result);
} catch (err) {
// Handle any potential errors
}
`

Callback:

`js
mcl.sendVerificationEmail(userId, function (err, result) {
if (err) {
// Handle any potential errors
}

console.log(result);
});
`

Then, a verification email is sent, and a response 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 code. Then, ask the end 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 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.

$3

1. To register the mobile device, get an activation token using the
getActivationToken method and the received Verification URL:

Promise:

`js
try {
const result = await mcl.getActivationToken(
"https://yourdomain.com/verification/confirmation?userId=alice@miracl.com&code=theVerificationCode",
);
console.log(result.actToken);
} catch (err) {
switch (error.message) {
case "Unsuccessful verification":
break;
default:
// Handle any unexpected errors
}
}
`

Callback:

`js
mcl.getActivationToken(
"https://yourdomain.com/verification/confirmation?userId=alice@miracl.com&code=theVerificationCode",
function callback(err, result) {
if (err) {
switch (error.message) {
case "Unsuccessful verification":
break;
default:
// Handle any unexpected errors
}
}

console.log(result.actToken);
},
);
`

An "Unsuccessful verification" error can be returned if the code is invalid or
expired.

2. Pass the User ID (email or any string you use for identification) and
activation token to the register method.

Promise:

`js
try {
const result = await mcl.register(userId, actToken, function (passPin) {
// Here you need to prompt the user for their PIN
// and then call the passPin argument with the value
passPin(pin);
});
console.log(result);
} catch (err) {
// Handle any potential errors
}
`

Callback:

`js
mcl.register(
userId,
actToken,
function (passPin) {
// Here you need to prompt the user for their PIN
// and then call the passPin argument with the value
passPin(pin);
},
function callback(err) {
if (err) {
// Handle any potential errors
}
},
);
`

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 when you want to reset your
authentication PIN code.

$3

MIRACL Trust Client JS Library offers two options:

- Authenticate users on the same application
- Authenticate users on another application

#### Authenticate users on the same application

The authenticate method generates a
JWT authentication token for а
registered user.

Promise:

`js
try {
const result = await mcl.authenticate(userId, pin);
console.log(result.jwt);
} catch (err) {
switch (error.message) {
case "Unsuccessful authentication":
break;
case "Revoked":
break;
default:
// Handle any unexpected errors
}
}
`

Callback:

`js
mcl.authenticate(userId, pin, function callback(err, result) {
if (err) {
switch (error.message) {
case "Unsuccessful authentication":
break;
case "Revoked":
break;
default:
// Handle any unexpected errors
}
}

// The JWT in the result needs to be verified by your back end
// to ensure that the authentication was successful
console.log(result.jwt);
});
`

"Unsuccessful authentication" is returned when there is a discrepancy in the
cryptographic calculations between the client and the server. This may be due to
an incorrect PIN input or an issue with the token.

"Revoked" is returned after the third consecutive failed authentication attempt,
and for any subsequent attempts after the revocation. This error may also occur
if the device registration has been explicitly revoked by an administrator via
the MIRACL Trust Console or through the revocation API.

After the JWT authentication token is generated, it needs to be sent to the
application server for verification.

#### Authenticate users on another application

When using the library to build a hybrid mobile application, you can use it as
an authenticator to authenticate a user on another application or device. There
are three options:

- Authenticate with AppLink

Use the authenticateWithAppLink method:

`js
try {
await mcl.authenticateWithAppLink(userId, appLink, pin);
} catch (err) {
// Handle any potential errors
}
`

- Authenticate with QR code

Use the authenticateWithQRCode method:

`js
try {
await mcl.authenticateWithQRCode(userId, qrCode, pin);
} catch (err) {
// Handle any potential errors
}
`

- Authenticate with a push notification

Use the authenticateWithNotificationPayload method:

`js
try {
await mcl.authenticateWithNotificationPayload(pushNotificationPayload, pin);
} catch (err) {
// Handle any potential errors
}
`

For more information about authenticating users on separate applications and
devices, see
Cross-Device Authentication.

$3

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 library, we refer to it as ‘Signing’.

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

Promise:

`js
try {
const signature = await mcl.sign(
userId,
pin,
documentHash,
documentTimestamp,
);
console.log(signature);
} catch (err) {
// Handle any potential errors
}
`

Callback:

`js
mcl.sign(
userId,
pin,
documentHash,
documentTimestamp,
function callback(err, signature) {
if (err) {
// Handle any potential errors
return;
}

console.log(signature);
},
);
`

The signature needs to be verified. This is done when the signature is sent to
the application server, which then makes an HTTP call to the
POST /dvs/verify
endpoint. If the MIRACL Trust platform returns status code 200, the
certificate entry in the response body indicates that signing is successful.

$3

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

To generate a QuickCode, call the generateQuickCode method:

Promise:

`js
try {
const result = await mcl.generateQuickCode(userId, pin);
console.log(result.code);
} catch (err) {
// Handle any potential errors
}
`

Callback:

`js
mcl.generateQuickCode(userId, pin, function callback(err, result) {
if (err) {
// Handle any potential errors
}

console.log(result.code);
});
`

$3

When instantiated, the library automatically initialises a user management
object, which can be accessed via the MIRACLTrust.users property and includes
the following methods:

#### List

To retrieve all registered User IDs on the current device, use the list
method:

`js
const list = mcl.users.list();
`

#### Еxists

To check if a User ID is already registered on the device, use the exists
method:

`js
const exists = mcl.users.exists("alice@miracl.com");
`

#### Remove

To delete the registration on the current device for a specified User ID, use
the remove method:

`js
mcl.users.remove("alice@miracl.com");
``

> Note that this only affects the device on which it's executed. Any other
> registered devices will still be able to authenticate.