# VerificaC19 SDK for Node.js
Official VerificaC19 SDK implementation for Node.js ([official SDKs list](https://github.com/ministero-salute/it-dgc-verificac19-sdk-onboarding#lista-librerie)).
*Read this in other languages: [Italian 🇮🇹](https://github.com/italia/verificac19-sdk/blob/master/README.it.md).*
## Requirements
- Node.js version >= 12.x
- MongoDB version >= 5.x (used to store CRL)
## Installation
```sh
npm i verificac19-sdk
```
## Usage
### Setup CRL environment
CRL data will be stored in a MongoDB database. This repository provides a simple
`docker-compose.yml` file (dev instance) with a replica set. By default the
connection string is `mongodb://root:example@localhost:27017/VC19?authSource=admin`.
If you want to change it as [dotenv](https://www.npmjs.com/package/dotenv) is used for environment variables managment, you must create a `.env` file in your root folder and set `VC19_MONGODB_URL` value.
👉🏻 See an example [examples/.env](https://github.com/italia/verificac19-sdk/blob/master/examples/.env).
⚠️ If you don't want to use MongoDB to store CRL,
read [how to write your own CRL management system](https://github.com/italia/verificac19-sdk/blob/master/docs/en/CUSTOM_CRL.md).
### Download and cache rules, CRL data and DSCs
You can download and cache rules, CRL data and DSCs using `Service` module.
```js
const {Service} = require('verificac19-sdk');
const main = async () => {
await Service.updateAll();
}
```
⚠️ By default rules and DSCs will be cached in a folder called `.cache`,
to change it, set `VC19_CACHE_FOLDER` inside your `.env` file.
⏱ By default `updateAll` is allowed to fetch new data every 24 hours.
To change this value, set `VC19_UPDATE_HOURS` inside your `.env` file.
👉🏻 See an example [examples/syncdata.js](https://github.com/italia/verificac19-sdk/blob/master/examples/syncdata.js).
### Verify a DCC
You can load a DCC from an image or from a raw string using `Certificate` module.
```js
const {Certificate} = require('verificac19-sdk');
const main = async () => {
const myDCCfromImage = await Certificate.fromImage('./data/myDCC.png');
const myDCCfromRaw = await Certificate.fromRaw('HC1:6BF+70790T9WJWG.FKY*4GO0.O1CV2...etc..');
}
```
Loaded DCC has the following structure:
```js
{
person: {
standardisedFamilyName: 'MUSTERMANN',
familyName: 'Mustermann',
standardisedGivenName: 'ERIKA',
givenName: 'Erika'
},
dateOfBirth: '1964-08-12',
kid: 'TH15154F4k3K1D=',
exemptions: [ ... ], // Array of exemptions (if any)
vaccinations: [ ... ], // Array of vaccinations (if any)
tests: [ ... ], // Array of tests (if any)
recoveryStatements: [ ... ], // Array of recovery statements (if any)
dcc: DCCObject // from dcc-utils https://github.com/ministero-salute/dcc-utils
}
```
👉🏻 `fromImage` and `fromRaw` methods may rise `CertificateParsingError`.
You can verify a DCC using `Validator` module.
```js
const {Certificate, Validator} = require('verificac19-sdk');
const main = async () => {
const myDCC = await Certificate.fromImage('./data/myDCC.png');
const validationResult = await Validator.validate(myDCC);
}
```
`Validator.validate` returns an object containing `person` name,
`date_of_birth`, `code` and a `message` alongside the `result`
```js
{
person: 'Erika Mustermann',
date_of_birth: '1964-08-12',
code: 'NOT_VALID',
result: false,
message: 'Test Result is expired at : 2021-05-22T12:34:56.000Z'
}
```
you can compare the resulting `code` with `Validator.codes` values
| | Code | Description | Result |
|-| --------------- | ---------------------------------------- | ------ |
|✅| VALID | Certificate is valid | `true` |
|⚠️| TEST_NEEDED | Test needed if verification mode is BOOSTER_DGP | `false` |
|❌| NOT_VALID | Certificate is not valid | `false` |
|❌| NOT_VALID_YET | Certificate is not valid yet | `false` |
|❌| REVOKED | Certificate is revoked | `false` |
|❌| NOT_EU_DCC | Certificate is not an EU DCC | `false` |
for example
```js
const validationResult = await Validator.validate(dccTest);
console.log(validationResult.code === Validator.codes.NOT_VALID);
```
👉🏻 `validate` method may rise `CertificateVerificationError` (e.g. when cache is
not ready yet).
👉🏻 See an example [examples/verifydccs.js](https://github.com/italia/verificac19-sdk/blob/master/examples/verifydccs.js).
### Verification mode
If you want to change verification mode and verify whether a certificate is a
Super Green Pass or not, you need to pass `Validator.mode.SUPER_DGP` to
`Validator.validate` method.
```js
const result = await Validator.validate(dcc, Validator.mode.SUPER_DGP);
```
| Code | Description |
| ---------------- | ---------------------------------------- |
| NORMAL_DGP | Normal verification (default value) |
| SUPER_DGP | Super Green Pass verification |
| VISITORS_RSA_DGP | RSA Visitors (ex BOOSTER_DGP verification mode) |
[DECRETO-LEGGE 4 febbraio 2022, n. 5](https://www.gazzettaufficiale.it/eli/id/2022/02/04/22G00014/sg)
### Alternative methods
To update rules and DSCs you can also use `updateRules`,
`updateSignaturesList` and `updateSignatures` methods
```js
const {Service} = require('verificac19-sdk');
const main = async () => {
await Service.setUp();
await Service.updateRules();
await Service.updateSignaturesList();
await Service.updateSignatures();
await Service.updateCRL();
await Service.tearDown();
}
```
To verify a DCC you can also use `Validator.checkRules` and
`Validator.checkSignature` methods.
```js
const {Certificate, Validator} = require('verificac19-sdk');
const main = async () => {
const myDCC = await Certificate.fromImage('./data/myDCC.png');
const rulesOk = await Validator.checkRules(myDCC).result;
const signatureOk = await Validator.checkSignature(myDCC);
}
```
## Development
### Install dependencies
```sh
npm i
```
### Run tests
Run mongodb services using Docker
```sh
docker-compose up
```
Set `VC19_CACHE_FOLDER` and run tests
```sh
npm run test
```
## Authors
Copyright (c) 2021 - Andrea Stagi
Parts of the core code have been written by [Area servizi ICT, Politecnico di Milano](https://www.ict.polimi.it/).
## Contributors
Here is a list of contributors. Thank you to everyone involved for improving this project, day by day.
## License
VerificaC19-SDK for Node.js is available under the [MIT](https://opensource.org/licenses/mit-license.php) license.