@worldcertscom/oa-verify NPM

@worldcertscom/oa-verify

Library to verify any OpenAttestation document. This library implements the verifier ADR.

Installation

npm install @worldcertscom/oa-verify

Usage

import { documentRopstenValidWithToken } from "./test/fixtures/v2/documentRopstenValidWithToken";
import { verify, isValid } from "@worldcertscom/oa-verify";

const fragments = await verify(documentRopstenValidWithToken);
console.log(fragments); // see below
console.log(isValid(fragments)); // display true

[
  {
    "data": true,
    "name": "OpenAttestationHash",
    "status": "VALID",
    "type": "DOCUMENT_INTEGRITY"
  },
  {
    "data": {
      "details": [
        {
          "address": "0xe59877ac86c0310e9ddaeb627f42fdee5f793fbe",
          "minted": true
        }
      ],
      "mintedOnAll": true
    },
    "name": "OpenAttestationEthereumTokenRegistryStatus",
    "status": "VALID",
    "type": "DOCUMENT_STATUS"
  },
  {
    "name": "OpenAttestationEthereumDocumentStoreStatus",
    "reason": {
      "code": 4,
      "codeString": "SKIPPED",
      "message": "Document issuers doesn't have \"documentStore\" or \"certificateStore\" property or DOCUMENT_STORE method"
    },
    "status": "SKIPPED",
    "type": "DOCUMENT_STATUS"
  },
  {
    "name": "OpenAttestationDidSignedDocumentStatus",
    "reason": {
      "code": 0,
      "codeString": "SKIPPED",
      "message": "Document was not signed by DID directly"
    },
    "status": "SKIPPED",
    "type": "DOCUMENT_STATUS"
  },
  {
    "data": [
      {
        "location": "example.tradetrust.io",
        "status": "VALID",
        "value": "0xe59877ac86c0310e9ddaeb627f42fdee5f793fbe"
      }
    ],
    "name": "OpenAttestationDnsTxtIdentityProof",
    "status": "VALID",
    "type": "ISSUER_IDENTITY"
  },
  {
    "name": "OpenAttestationDnsDidIdentityProof",
    "reason": {
      "code": 0,
      "codeString": "SKIPPED",
      "message": "Document was not issued using DNS-DID"
    },
    "status": "SKIPPED",
    "type": "ISSUER_IDENTITY"
  }
]

Advanced usage

Environment Variables

INFURA_API_KEY: let you provide your own INFURA API key.

Switching network

You may build the verifier to verify against a custom network by either:

providing your own web3 provider
specifying the network name (provider will be using the default ones)

To provide your own provider:

const verify = verificationBuilder(openAttestationVerifiers, { provider: customProvider });

To specify network:

const verify = verificationBuilder(openAttestationVerifiers, { network: "ropsten" });

Specify resolver

oa-verify exposes a method, called createResolver that allows you to easily create custom resolvers, to resolve DIDs:

import {
  createResolver,
  verificationBuilder,
  openAttestationVerifiers
} from '@govtechsg/oa-verify';

const resolver = createResolver({
  networks: [{ name: 'my-network', rpcUrl: 'https://my-private-chain/besu', registry: '0xaE5a9b9...' }],
});

const verify = verificationBuilder(openAttestationVerifiers, { resolver });

At the moment, oa-verify supports two did resolvers:

Verify

By default the provided verify method performs multiple checks on a document

for the type DOCUMENT_STATUS: it runs OpenAttestationEthereumDocumentStoreStatus and OpenAttestationEthereumTokenRegistryStatus verifiers
for the type DOCUMENT_INTEGRITY: it runs OpenAttestationHash verifier
for the type ISSUER_IDENTITY: it runs OpenAttestationDnsTxt verifier

All those verifiers are exported as openAttestationVerifiers

You can build your own verify method or you own verifiers:

import { verificationBuilder, openAttestationVerifiers } from "@worldcertscom/oa-verify";

// creating your own verify using default exported verifiers
const verify = verificationBuilder(openAttestationVerifiers); // this verify is equivalent to the one exported by the library
const verify = verificationBuilder([openAttestationVerifiers[0], openAttestationVerifiers[1]]); // this verify only run 2 verifiers

// creating your own verify using custom verifier
import { verificationBuilder, openAttestationVerifiers, Verifier } from "@worldcertscom/oa-verify";
const customVerifier: Verifier = {
  skip: () => {
    // return a SkippedVerificationFragment if the verifier should be skipped or throw an error if it should always run
  },
  test: () => {
    // return true or false
  },
  verify: async (document) => {
    // perform checks and returns a fragment
  },
};

// create your own verify function with all verifiers and your custom one
const verify = verificationBuilder([...openAttestationVerifiers, customVerifier]);

isValid

By default, isValid perform checks on every types that exists for a fragment:

DOCUMENT_STATUS
DOCUMENT_INTEGRITY
ISSUER_IDENTITY it ensures that for every types, there is at least one VALID fragment and no INVALID or ERROR fragment.

The function allow to specify as a second parameters the list of types on which to perform the checks

import { documentRopstenValidWithCertificateStore } from "./test/fixtures/v2/documentRopstenValidWithCertificateStore";
import { verify, isValid } from "@worldcertscom/oa-verify";

const fragments = verify(documentRopstenValidWithCertificateStore, { network: "ropsten" });
isValid(fragments); // display false because ISSUER_IDENTITY is INVALID
isValid(fragments, ["DOCUMENT_INTEGRITY", "DOCUMENT_STATUS"]); // display true because those types are VALID

Utils and types

Overview

Various utilities and types are available to assert the correctness of fragments. Each verification method exports types for the fragment, and the data associated with the fragment.

fragment types are available in 4 flavors: VALID, INVALID, SKIPPED, and ERROR.
VALID and INVALID fragment data are available in 2 flavors most of the time, one for each version of OpenAttestation.

This library provides types and utilities to:

get a specific fragment from all the fragments returned by the verify method
narrow down to a specific type of fragment
narrow down to a specific fragment data

Let's see how to use it

Example

import {utils} from "@govtechsg/oa-verify";
const fragments = verify(documentRopstenValidWithCertificateStore, { network: "ropsten" });
// return the correct fragment, correctly typed
const fragment = utils.getOpenAttestationEthereumTokenRegistryStatusFragment(fragments)

if(utils.isValidFragment(fragment)) {
    // guard to narrow to the valid fragment type
    const {data} = fragment;
    if (ValidTokenRegistryDataV2.guard(data)) {
        // data is correctly typed here
    }
}

Note that in the example above, using utils.isValidFragment might be unnecessary. It's possible to use directly ValidTokenRegistryDataV2.guard over the data.