Skip to main content

Verifiable Credential

Create and verify EBSI-compliant W3C Verifiable Credentials in JWT format with the @cef-ebsi/verifiable-credential library.

This library extends the @transmute/json-web-signature and @transmute/vc.js libraries by applying additional validation rules. For more details, see EBSI Verifiable Credentials Playbook for Early Adopters.

Note: this library only supports draf-07 JSON Schemas.

info

The following documentation is related to the version v2 of the @cef-ebsi/verifiable-credential library. It is meant to be used with the latest EBSI APIs.

If you use the legacy EBSI APIs, check the documentation about the v1 of the library.

Installation

Using npm:

$ npm i --save @cef-ebsi/verifiable-credential

Using yarn:

$ yarn add @cef-ebsi/verifiable-credential

Usage

Creating JWTs

Prerequisites

Create an EbsiIssuer object to sign JWTs:

import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential";

const issuer: EbsiIssuer = {
did: "did:ebsi:zgPs5MVWHwJJb4g9kZvYf3e",
kid: "did:ebsi:zgPs5MVWHwJJb4g9kZvYf3e#keys-1",
publicKeyJwk: <JWK>,
privateKeyJwk: <JWK>,
alg: "ES256K",
};

In order to create a valid JWT:

  1. This issuer MUST be registered in the Trusted Issuers Registry.

Creating a Verifiable Credential

Specify a payload matching the EbsiVerifiableAttestation interface:

import { createVerifiableCredentialJwt } from "@cef-ebsi/verifiable-credential";
import type { EbsiVerifiableAttestation } from "@cef-ebsi/verifiable-credential";

const vcPayload: EbsiVerifiableAttestation = {
"@context": ["https://www.w3.org/2018/credentials/v1"],
id: "urn:did:123456",
type: ["VerifiableCredential", "VerifiableAttestation", "VerifiableId"],
issuer: "did:ebsi:zgPs5MVWHwJJb4g9kZvYf3e",
issuanceDate: "2021-11-01T00:00:00Z",
validFrom: "2021-11-01T00:00:00Z",
credentialSubject: {
id: "did:ebsi:zYud7H5Wvf9ksRUrmTrFo9D",
personalIdentifier: "IT/DE/1234",
familyName: "Castafiori",
firstName: "Bianca",
dateOfBirth: "1930-10-01",
},
credentialSchema: {
id: "https://api.preprod.ebsi.eu/trusted-schemas-registry/v2/schemas/0x14b05b9213dbe7d343ec1fe1d3c8c739a3f3dc5a59bae55eb38fa0c295124f49",
type: "FullJsonSchemaValidator2021",
},
expirationDate: "2031-11-30T00:00:00Z",
issued: "2021-10-30T00:00:00Z",
};

Specify the options to validate the issuer and credential:

const options = {
// EBSI URI Authority ([userinfo "@"] host [":" port])
ebsiAuthority: "api.preprod.ebsi.eu",
};

Create a JWT by signing it with the previously configured issuer using the createVerifiableCredentialJwt function:

const vcJwt = await createVerifiableCredentialJwt(vcPayload, issuer, options);
console.log(vcJwt);
// eyJraWQiOiJkaWQ6ZWJzaTp6Z1Bz...j9Pv1HSIR9aPXIVRMGYfjhmQH8oSM03g

Verifying JWTs

Prerequisites

Pass in a VC JWT to verify using the verifyCredentialJwt function:

import { verifyCredentialJwt } from "@cef-ebsi/verifiable-credential";

const vcJwt = "eyJraWQiOiJkaWQ6ZWJzaTp6Z1Bz...j9Pv1HSIR9aPXIVRMGYfjhmQH8oSM03g";

const options = {
// EBSI URI Authority ([userinfo "@"] host [":" port])
ebsiAuthority: "api.preprod.ebsi.eu",
};

const verifiedVc = await verifyCredentialJwt(vcJwt, options);

console.log(verifiedVc);
/*
{
"@context": ["https://www.w3.org/2018/credentials/v1"],
id: "urn:did:123456",
type: ["VerifiableCredential", "VerifiableAttestation", "VerifiableId"],
issuer: "did:ebsi:zgPs5MVWHwJJb4g9kZvYf3e",
issuanceDate: "2021-11-01T00:00:00Z",
validFrom: "2021-11-01T00:00:00Z",
credentialSubject: {
id: "did:ebsi:zYud7H5Wvf9ksRUrmTrFo9D",
personalIdentifier: "IT/DE/1234",
familyName: "Castafiori",
firstName: "Bianca",
dateOfBirth: "1930-10-01",
},
credentialSchema: {
id: "https://api.preprod.ebsi.eu/trusted-schemas-registry/v2/schemas/0x14b05b9213dbe7d343ec1fe1d3c8c739a3f3dc5a59bae55eb38fa0c295124f49",
type: "FullJsonSchemaValidator2021",
},
expirationDate: "2031-11-30T00:00:00Z",
issued: "2021-10-30T00:00:00Z",
}
*/

Try it online

The VC & VP validator tool uses the @cef-ebsi/verifiable-credential to verify VC JWTs.