verifier-sdk-react-native

Table of Contents

• Licensing
• Features
• Getting started
• Usage
  • Verifier
  • Cache
  • Extensions
    • Mobile Credential
    • Ecosystem
  • Error handling

Licensing

Request or download the MATTR Pi SDK Trial Licence Agreement and the MATTR Customer Agreement and review these terms.

Features

• Verify credentials
• Refresh cached revocation lists and trusted issuers list
• Get the expiry date of the most-soon-to-expire item in the cache

Getting started

How to get access to MATTR Pi Verifier SDK

Refer to our SDK Docs landing page for step-by-step instructions to gain access to any of our SDKs.

Please reach out to us in case you need any assistance.

Install dependencies

Add this SDK as a dependency to the react native app:

yarn add @mattrglobal/verifier-sdk-react-native
Copy

The SDK relies on a set of peer dependencies that contain native libraries and iOS pods. With React Native >=0.60 these dependencies will be autolinked.

Install the peer dependencies:

yarn add @mattrglobal/react-native-cryptography@^1.1.0 react-native-securerandom@^1.0.1 react-native-fs@^2.20.0 react-native-secure-key-store@^2.0.10 react-native-get-random-values@^1.8.0 react-native-mmkv@^2.10.1
Copy

[!NOTE]
we tested with react-native 0.71.12

Usage

Verifier

Create a verifier:

import { init } from "@mattrglobal/verifier-sdk-react-native";

const initOptions: InitOptions = {
  issuerCacheTtl: 60000,
  revocationListCacheTtl: 60000,
  trustedIssuers: ["did:web:example.com"], // defaults to trust any issuer
  assertExpiry: true, // defaults to true
  assertNotBefore: true, // defaults to true
  checkRevocation: true, // defaults to true
};

const verifier = await init(initOptions);
Copy

Verify a credential:

const verifyResult = await verifier.compact.verify({ payload });

if (verifyResult.isErr()) {
  // Handle error from verifyResult.error
  return;
}

const { verified } = verifyResult.value;
Copy

Close the verifier:

console.log(verifier.isOpen()); // true

const closeVerifierResult = await verifier.close();

if (closeVerifierResult.isErr()) {
  // Handle error from closeVerifierResult.error
  return;
}

console.log(verifier.isOpen()); // false
Copy

Destroy the verifier:

await verifier.destroy();

console.log(verifier.isOpen()); // false
Copy

Cache

Get the cache expiry date:

const expiry = await verifier.compact.getCacheExpiry();
Copy

Refresh the items in the cache:

const refreshCacheResult = await verifier.compact.refreshCache();

if (refreshCacheResult.isErr()) {
  /**
   * The error contains the cache expiry date
   * This date may have changed after partial refresh
   */
  console.log(refreshCacheResult.error.expiryDate);
  // Handle error from refreshCacheResult.error
  return;
}

// New expiry date of the cache
const { expiryDate } = refreshCacheResult.value;
Copy

Refresh issuer items in the cache:

const refreshIssuerCacheResult = await verifier.compact.refreshIssuerCache();

if (refreshIssuerCacheResult.isErr()) {
  /**
   * The error contains the cache expiry date
   * This date may have changed after partial refresh
   */
  console.log(refreshIssuerCacheResult.error.expiryDate);
  // Handle error from refreshIssuerCacheResult.error
  return;
}

// New expiry date of the issuers cache
const { expiryDate } = refreshIssuerCacheResult.value;
Copy

Refresh revocation list items in the cache:

const refreshRevocationListCacheResult = await verifier.compact.refreshRevocationCache();

if (refreshRevocationListCacheResult.isErr()) {
  /**
   * The error contains the cache expiry date
   * This date may have changed after partial refresh
   */
  console.log(refreshRevocationListCacheResult.error.expiryDate);
  // Handle error from refreshRevocationListCacheResult.error
  return;
}

// New expiry date of the revocation list cache
const { expiryDate } = refreshRevocationListCacheResult.value;
Copy

Extensions

The following extensions are not included in the @mattrglobal/verifier-sdk-react-native package by default.

Mobile Credential

To enable Mobile Credentials features, install the following peer dependency in your app:

yarn add @mattrglobal/mobile-credential-verifier-react-native
Copy

Platform iOS

Mobile Credentials presentation utilises Bluetooth connection. Make sure the NSBluetoothAlwaysUsageDescription and NSBluetoothPeripheralUsageDescription descriptions are configured inside Info.plist.

Platform Android

Additional configuration steps are required to bundle the native libraries.

Kotlin Support

This React Native library is written in Kotlin, so you must enable the Kotlin Gradle plugin. If your project was generated using the official React Native 0.73.0 template, you might have it enabled already.

Open the android/build.gradle script and apply the following changes:

 buildscript {
   ext {
+    kotlinVersion = "1.9.0"

     buildToolsVersion = "34.0.0"
     minSdkVersion = 24
     compileSdkVersion = 34
     targetSdkVersion = 34
     ndkVersion = "25.1.8937393"
   }
   repositories {
     google()
     mavenCentral()
   }
   dependencies {
     classpath("com.android.tools.build:gradle")
     classpath("com.facebook.react:react-native-gradle-plugin")

+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    classpath("org.jetbrains.kotlin:kotlin-android-extensions:$kotlinVersion")
   }
 }
Copy

Open the android/app/build.gradle script and apply the following changes:

  apply plugin: "com.android.application"
+ apply plugin: "org.jetbrains.kotlin.android"
  apply plugin: "com.facebook.react"
Copy

Minimum requirements

• kotlinVersion >= 1.9.0
• minSdkVersion >= 24

Local Maven Repository

The precompiled MATTR Mobile Credentials Verifier Android Native SDK is provided in the published NPM package.

Open the android/build.gradle script and apply the following changes:

 allprojects {
   repositories {
     …
     google()
+    maven {
+      url = "$rootDir/../node_modules/@mattrglobal/mobile-credential-verifier-react-native/android/frameworks"
+    }
   }
 }
Copy

Enable extension

Include the Mobile Credentials verifier extension during initialisation:

import { init } from "@mattrglobal/verifier-sdk-react-native";
import MobileCredentialVerifier from "@mattrglobal/mobile-credential-verifier-react-native";

await init({ extensions: [MobileCredentialVerifier], walletId });
Copy

The SDK only verifies credentials that were issued by a trusted issuer. The trusted issuer certificates list can be managed directly with the following functions:

// Add new trusted issuer certificates
await verifier.mobile.addTrustedIssuerCertificates(certificates);

// Get all trusted certificates
const certificates = await verifier.mobile.getTrustedIssuerCertificates();

// Remove one of the trusted issuer certificate
await verifier.mobile.deleteTrustedIssuerCertificate(id);
Copy

The Mobile Credentials verifier supports requesting a credential from a holder device via Bluetooth. The following example shows how you could start a session and request a credential presentation from a holder device:

[!NOTE] Only one presentation session is allowed at a time. You must terminate the existing session before starting a new one.

// start a new presentation session
const createSessionResult = await verifier.mobile.createProximityPresentationSession({
  deviceEngagement: "mdoc:owBjMS4wAYIB2BhYS6QBAiABIVgg_t9K0BaXU27ynODS5q8OcvBZ4m1HFEQwl61lhRD2rdciWCA7hKLr_xN6_bdznDePa_yY1tGdHsc8ni_88uVuehRU-QKBgwIBowD1AfQKUMW8DfgLrUclmxp2InJCddk" // proximity presentation device engagement string
  onConnected: () => {
    // handle onConnect event
  },
  onSessionTerminated: () => {
    // handle onSessionTerminated event
  },
});

if (createSessionResult.isErr()) {
  const { error } = createSessionResult;
  // handle error scenarios
  return;
}

// Send session
const sendRequestResult = await verifier.mobile.sendProximityPresentationRequest({
  mobileCredentialRequests: [{
    docType: "org.iso.18013.5.1.mDL",
    namespaces: {
      "org.iso.18013.5.1": {
        family_name: false,
        driving_privileges: false,
      },
    },
  }],
});

if (sendRequestResult.isErr()) {
  const { error } = sendRequestResult;
  // handle error scenarios
  return;
}

const response = sendRequestResult.value;

// Terminate current active session
await verifier.mobile.terminateProximityPresentationSession();
Copy

Ecosystem

To enable Ecosystem features install the following peer dependency in your app:

yarn add @mattrglobal/ecosystem-sdk-react-native
Copy

And then include the Ecosystem SDK during initialisation:

import { init } from "@mattrglobal/verifier-sdk-react-native";
import Ecosystem from "@mattrglobal/ecosystem-sdk-react-native";

await init({ extensions: [Ecosystem], ecosystem: { url } });
Copy

On initialisation (see above) the internal storage is synced with the latest policy relevant to the provided ecosystem ID. If storage becomes out of sync, the SDK provides an option to manage the storage manually:

// storage can be synced manually
const syncResult = await verifier.ecosystem.sync({ reset: true });

// storage can be deleted manually
const deleteResult = await verifier.ecosystem.delete();
Copy

The main features of the Ecosystem SDK is to provide validation of a given credential and participant, who can be an issuer, a verifier or both. The SDK also checks whether the participant is authorised. This can be invoked with:

// validates the three aspects of the specified issuer
const validateIssuerResult = await Ecosystem.validateIssuer({ profile, identifier, type });

// validates the three aspects of the specified verifier
const validateVerifierResult = await Ecosystem.validateVerifier({ profile, identifier, type });
Copy

Error handling

Functions that are expected to have an error path return a Neverthrow Result type that represents either success (Ok) or failure (Err).

Although this pattern is more verbose, it encourages the handling of possible errors and reserves throwing exceptions for truly exceptional situations.

import { open } from "@mattrglobal/verifier-sdk-react-native";

const openVerifierResult = await open();

if (openVerifierResult.isErr()) {
  // Handle error from openVerifierResult.error
  return;
}

const verifier = openVerifierResult.value;
Copy

unwrap

A utility function is provided for convenience if you decide not to handle your errors as results. This function will simply throw an error if the function passed in returns a Result where Result.isErr() is true.

import { unwrap } from "@mattrglobal/verifier-sdk-react-native";

try {
  const verifier = unwrap(await open());
} catch (error) {
  // Handle thrown error
}
Copy

Change Log

3.0.0

BREAKING CHANGES

The following verifier initialisation parameters have been renamed to maintain consistency (the functionality is not affected by this change):

• The assertNotBefore parameter has been renamed to assertValidFrom.
• The assertExpiry parameter has been renamed to assertValidUntil.

Features

Introduced Mobile Credentials capabilities via extensions.

2.0.0

BREAKING CHANGES

The verifyCredential method had been split and moved into the separate compact and compactSemantic namespaces to simplify methods structure and usage. With this change trusted issuers and revocation lists are cached separately for these namespaces.

• See methods verifier.compact.verify and verifier.compactSemantic.verify

Features

Introduced Ecosystem capabilities via extensions.

1.0.0

Features

Introduced Compact and Compact Semantic Credentials verification capabilities.