# @worldcertscom/oa-verify

> [![CircleCI](https://circleci.com/gh/Open-Attestation/oa-verify.svg?style=svg)](https://circleci.com/gh/Open-Attestation/oa-verify)

Latest version **7.4.4** (published 2021-06-10) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @worldcertscom/oa-verify
pnpm add @worldcertscom/oa-verify
yarn add @worldcertscom/oa-verify
bun add @worldcertscom/oa-verify
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.4.4 |
| Published | 2021-06-10 |
| First published | 2020-12-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 13 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 7 |
| Maintainers | jtaynl, dassiorleando, reddysim |

## Links

- npm: https://www.npmjs.com/package/@worldcertscom/oa-verify
- Repository: https://github.com/Open-Attestation/oa-verify
- Homepage: https://github.com/Open-Attestation/oa-verify#readme
- Issues: https://github.com/Open-Attestation/oa-verify/issues
- npm.io page: https://npm.io/package/@worldcertscom/oa-verify

## Dependencies (13)

- [snyk](https://npm.io/package/snyk.md) ^1.576.0
- [axios](https://npm.io/package/axios.md) ^0.21.1
- [debug](https://npm.io/package/debug.md) ^4.3.1
- [ethers](https://npm.io/package/ethers.md) ^5.1.4
- [runtypes](https://npm.io/package/runtypes.md) ^6.3.0
- [node-cache](https://npm.io/package/node-cache.md) ^5.1.2
- [did-resolver](https://npm.io/package/did-resolver.md) ^3.1.0
- [web-did-resolver](https://npm.io/package/web-did-resolver.md) ^2.0.4
- [ethr-did-resolver](https://npm.io/package/ethr-did-resolver.md) ^4.3.3
- [@worldcertscom/dnsprove](https://npm.io/package/@worldcertscom/dnsprove.md) ^2.1.3
- [@govtechsg/document-store](https://npm.io/package/@govtechsg/document-store.md) ^2.2.1
- [@govtechsg/token-registry](https://npm.io/package/@govtechsg/token-registry.md) ^2.5.2
- [@govtechsg/open-attestation](https://npm.io/package/@govtechsg/open-attestation.md) ^5.2.3

## Recent versions

- 7.4.4 (latest) — 2021-06-10
- 7.0.2 — 2021-03-24
- 7.0.1 — 2021-03-23
- 7.0.0 — 2021-03-23
- 4.2.1-new — 2020-12-04
- 4.2.1 — 2020-12-04
- 3.1.2 — 2020-12-04

## README

# @worldcertscom/oa-verify

[![CircleCI](https://circleci.com/gh/Open-Attestation/oa-verify.svg?style=svg)](https://circleci.com/gh/Open-Attestation/oa-verify)

Library to verify any [OpenAttestation](https://github.com/Open-Attestation/open-attestation) document. This library implements [the verifier ADR](https://github.com/Open-Attestation/adr/blob/master/verifier.md).

## Installation

```sh
npm install @worldcertscom/oa-verify
```

## Usage

```typescript
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
```

```json
[
  {
    "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:

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

To provide your own provider:

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

To specify network:

```ts
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:

```ts
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:
- [web-did-resolver](https://github.com/decentralized-identity/web-did-resolver#readme)
- [ethd-did-resolver](https://github.com/decentralized-identity/ethr-did-resolver)

### 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:

```typescript
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

```typescript
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.

### List of utilities
- `getOpenAttestationHashFragment`
- `getOpenAttestationDidSignedDocumentStatusFragment`
- `getOpenAttestationEthereumDocumentStoreStatusFragment`
- `getOpenAttestationEthereumTokenRegistryStatusFragment`
- `getOpenAttestationDidIdentityProofFragment`
- `getOpenAttestationDnsDidIdentityProofFragment`
- `getOpenAttestationDnsTxtIdentityProofFragment`
- `getDocumentIntegrityFragments`
- `getDocumentStatusFragments`
- `getIssuerIdentityFragments`
- `isValidFragment`: type guard to filter only `VALID` fragment type
- `isInvalidFragment`: type guard to filter only `INVALID` fragment type
- `isErrorFragment`: type guard to filter only `ERROR` fragment type
- `isSkippedFragment`: type guard to filter only `SKIPPED` fragment type


## Development

For generating of test documents (for v3) you may use the script at `scripts/generate.v3.ts` by running `npm run generate:v3`.

## License

[GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html)

---
_Source: https://npm.io/package/@worldcertscom/oa-verify · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._