Create and verify EBSI-compliant W3C Verifiable Credentials in JWT format.
This library extends the @transmute/json-web-signature and @transmute/vc.js libraries by applying additional validation rules. For more details, see VC Framework.
Notes:
- this library implements the VC Data Model 1.1 specification.
- this library only supports
2020-12
JSON Schemas.
Installation
Using npm:
npm i --save @cef-ebsi/verifiable-credential
Using yarn:
yarn add @cef-ebsi/verifiable-credential
Usage
By default, the library fetches data from the upcoming APIs. Make sure to configure the ebsiEnvConfig
option according to your needs. See more details below.
Creating JWTs
Prerequisites
In order to create a valid JWT, the issuer must either be:
- a Legal Entity (
did:ebsi
method). In this case, the issuer must also be registered in the DID Registry and in the Trusted Issuers Registry. - a Natural Person (
did:key
method).
Creating a Verifiable Credential as a Legal Entity
Create an EbsiIssuer
object to sign JWTs:
import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential";
const issuer = {
did: "did:ebsi:zxaYaUtb8pvoAtYNWbKcveg",
kid: "did:ebsi:zxaYaUtb8pvoAtYNWbKcveg#CHxYzOqt38Sx6YBfPYhiEdgcwzWk9ty7k0LBa6h70nc",
alg: "ES256K",
publicKeyJwk: {
kty: "EC",
crv: "secp256k1",
x: "YsWJUlskYA_wdyKG8z1LYFICL-KNO7fE3WO5-z7dFa4",
y: "uo7ddu68ZY7YBreYNY0GQm-bgz6Xf3zXba0Bk0MgMWI",
},
privateKeyJwk: {
kty: "EC",
crv: "secp256k1",
x: "YsWJUlskYA_wdyKG8z1LYFICL-KNO7fE3WO5-z7dFa4",
y: "uo7ddu68ZY7YBreYNY0GQm-bgz6Xf3zXba0Bk0MgMWI",
d: "<ECC private key>",
},
} satisfies EbsiIssuer;
Specify a payload matching the EbsiVerifiableAttestation
interface:
import {
createVerifiableCredentialJwt,
type EbsiVerifiableAttestation,
} from "@cef-ebsi/verifiable-credential";
const vcPayload = {
"@context": ["https://www.w3.org/2018/credentials/v1"],
id: "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
type: ["VerifiableCredential", "VerifiableAttestation"],
issuer: "did:ebsi:zxaYaUtb8pvoAtYNWbKcveg",
issuanceDate: "2021-11-01T00:00:00Z",
validFrom: "2021-11-01T00:00:00Z",
validUntil: "2050-11-01T00:00:00Z",
expirationDate: "2031-11-30T00:00:00Z",
issued: "2021-10-30T00:00:00Z",
credentialSubject: {
id: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsNgeztBFXEB9FUZCoufTjXiTUZYKkcP36i2XAQCphfxBwvXG4dAaF6pdwhrMGyaLMC81fU5ECMnt4VgMQpwh3sn5vSbUpwoaTBME78noXJaTLgkCv5KkM6VgGTfWUjH8Z2",
},
credentialSchema: {
id: "https://api-pilot.ebsi.eu/trusted-schemas-registry/v3/schemas/z3MgUFUkb722uq4x3dv5yAJmnNmzDFeK5UC8x83QoeLJM",
type: "FullJsonSchemaValidator2021",
},
termsOfUse: {
id: "https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:zxaYaUtb8pvoAtYNWbKcveg/attributes/b40fd9b404418a44d2d9911377a03130dde450eb546c755b5b80acd782902e6d",
type: "IssuanceCertificate",
},
} satisfies EbsiVerifiableAttestation;
Specify the options to validate the issuer and credential:
import type { CreateVerifiableCredentialOptions } from "@cef-ebsi/verifiable-credential";
const options = {
// REQUIRED. EBSI URI Authority ([userinfo "@"] host [":" port])
ebsiAuthority: "api-pilot.ebsi.eu",
// OPTIONAL. EBSI environment configuration.
// This option allows you to override the default URLs (TIR, DIDR, TSR).
ebsiEnvConfig: {
didRegistry: "https://api-pilot.ebsi.eu/did-registry/v5/identifiers",
trustedIssuersRegistry:
"https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers",
trustedPoliciesRegistry:
"https://api-pilot.ebsi.eu/trusted-policies-registry/v3/users",
},
// OPTIONAL. Timeout after which the requests made by the library will fail. Default: 15 seconds
timeout: 15_000,
// OPTIONAL. List of trusted hostnames. To be used if the Core Services APIs are hosted on a custom host for instance.
// If `trustedHostnames` is not defined, the default trusted domains are: "api-test.ebsi.eu", "api-conformance.ebsi.eu", and "api-pilot.ebsi.eu"
// trustedHostnames: ["api.example.net"],
// OPTIONAL. Determines whether to validate the Verifiable Credential payload or not.
// Validation is active by default.
// Note: even when skipValidation is set to true, the payload must be a valid EBSI Verifiable Attestation.
skipValidation: false,
// OPTIONAL. Determines whether to validate the accreditations of the VC issuer or not.
// Validation is active by default.
skipAccreditationsValidation: false,
// OPTIONAL. Determines whether to validate the credential status or not.
// Validation is active by default.
skipStatusValidation: false,
} satisfies CreateVerifiableCredentialOptions;
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);
// eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QiLCJraWQiOiJkaWQ6ZWJzaTp6eGFZYVV0Yjhwdm9BdFlOV2JLY3ZlZyNDSHhZek9xdDM4U3g2WUJmUFloaUVkZ2N3eldrOXR5N2swTEJhNmg3MG5jIn0.eyJqdGkiOiJ1cm46dXVpZDowMDNhMWRkOC1hNWQyLTQyZWYtODE4Mi1lOTIxYzBhOWYyY2QiLCJzdWIiOiJkaWQ6a2V5OnoyZG16RDgxY2dQeDhWa2k3SmJ1dU1tRllyV1BnWW95dHlrVVozZXlxaHQxajlLYnNOZ2V6dEJGWEVCOUZVWkNvdWZUalhpVFVaWUtrY1AzNmkyWEFRQ3BoZnhCd3ZYRzRkQWFGNnBkd2hyTUd5YUxNQzgxZlU1RUNNbnQ0VmdNUXB3aDNzbjV2U2JVcHdvYVRCTUU3OG5vWEphVExna0N2NUtrTTZWZ0dUZldVakg4WjIiLCJpc3MiOiJkaWQ6ZWJzaTp6eGFZYVV0Yjhwdm9BdFlOV2JLY3ZlZyIsIm5iZiI6MTYzNTcyNDgwMCwiZXhwIjoxOTUzNzYzMjAwLCJpYXQiOjE2MzU1NTIwMDAsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sImlkIjoidXJuOnV1aWQ6MDAzYTFkZDgtYTVkMi00MmVmLTgxODItZTkyMWMwYTlmMmNkIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIlZlcmlmaWFibGVBdHRlc3RhdGlvbiJdLCJpc3N1ZXIiOiJkaWQ6ZWJzaTp6eGFZYVV0Yjhwdm9BdFlOV2JLY3ZlZyIsImlzc3VhbmNlRGF0ZSI6IjIwMjEtMTEtMDFUMDA6MDA6MDBaIiwidmFsaWRGcm9tIjoiMjAyMS0xMS0wMVQwMDowMDowMFoiLCJ2YWxpZFVudGlsIjoiMjA1MC0xMS0wMVQwMDowMDowMFoiLCJleHBpcmF0aW9uRGF0ZSI6IjIwMzEtMTEtMzBUMDA6MDA6MDBaIiwiaXNzdWVkIjoiMjAyMS0xMC0zMFQwMDowMDowMFoiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic05nZXp0QkZYRUI5RlVaQ291ZlRqWGlUVVpZS2tjUDM2aTJYQVFDcGhmeEJ3dlhHNGRBYUY2cGR3aHJNR3lhTE1DODFmVTVFQ01udDRWZ01RcHdoM3NuNXZTYlVwd29hVEJNRTc4bm9YSmFUTGdrQ3Y1S2tNNlZnR1RmV1VqSDhaMiJ9LCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjMvc2NoZW1hcy96M01nVUZVa2I3MjJ1cTR4M2R2NXlBSm1uTm16REZlSzVVQzh4ODNRb2VMSk0iLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn0sInRlcm1zT2ZVc2UiOnsiaWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L3RydXN0ZWQtaXNzdWVycy1yZWdpc3RyeS92NS9pc3N1ZXJzL2RpZDplYnNpOnp4YVlhVXRiOHB2b0F0WU5XYktjdmVnL2F0dHJpYnV0ZXMvYjQwZmQ5YjQwNDQxOGE0NGQyZDk5MTEzNzdhMDMxMzBkZGU0NTBlYjU0NmM3NTViNWI4MGFjZDc4MjkwMmU2ZCIsInR5cGUiOiJJc3N1YW5jZUNlcnRpZmljYXRlIn19fQ.I8Im8azp0pSnM4z_jqGTTfYUg7K802POR2LTJftVfjYtMt82Cik2Z_KGOG7dHhx13R6VGVZKg9134ke1bKhtPw
Creating a Verifiable Credential as a Natural Person
Create an EbsiIssuer
object to sign JWTs:
import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential";
const issuer = {
did: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsALgKJNpKj7U9jdYAHu3nxJ4fonckTBBGWELRpHJZ9dBKRzGebbNYTz6bWtaTM3zyyWnrkfb8w5owU1ECw2W7u1Rz2B5MgocMnnaa9wzDB3paEQvcgth9ErYawbNu9MLLc",
kid: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsALgKJNpKj7U9jdYAHu3nxJ4fonckTBBGWELRpHJZ9dBKRzGebbNYTz6bWtaTM3zyyWnrkfb8w5owU1ECw2W7u1Rz2B5MgocMnnaa9wzDB3paEQvcgth9ErYawbNu9MLLc#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsALgKJNpKj7U9jdYAHu3nxJ4fonckTBBGWELRpHJZ9dBKRzGebbNYTz6bWtaTM3zyyWnrkfb8w5owU1ECw2W7u1Rz2B5MgocMnnaa9wzDB3paEQvcgth9ErYawbNu9MLLc",
alg: "ES256",
publicKeyJwk: {
kty: "EC",
x: "myPoRDa5QONxWQ2rB3OJ7ftHlRDWQHhbNH7ra2Y1-i0",
y: "q00oUQjzvETQkjCM2F22dvChyqXKa0wsiVGLd--yz5Y",
crv: "P-256",
},
privateKeyJwk: {
kty: "EC",
x: "myPoRDa5QONxWQ2rB3OJ7ftHlRDWQHhbNH7ra2Y1-i0",
y: "q00oUQjzvETQkjCM2F22dvChyqXKa0wsiVGLd--yz5Y",
crv: "P-256",
d: "nxski1rN7qCb36d0r9oLliyujYEkEmex4YThvx_VOUc",
},
} satisfies EbsiIssuer;
Specify a payload matching the EbsiVerifiableAttestation
interface:
import {
createVerifiableCredentialJwt,
type EbsiVerifiableAttestation,
} from "@cef-ebsi/verifiable-credential";
const vcPayload = {
"@context": ["https://www.w3.org/2018/credentials/v1"],
id: "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
type: ["VerifiableCredential", "VerifiableAttestation"],
issuer:
"did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsALgKJNpKj7U9jdYAHu3nxJ4fonckTBBGWELRpHJZ9dBKRzGebbNYTz6bWtaTM3zyyWnrkfb8w5owU1ECw2W7u1Rz2B5MgocMnnaa9wzDB3paEQvcgth9ErYawbNu9MLLc",
issuanceDate: "2021-11-01T00:00:00Z",
validFrom: "2021-11-01T00:00:00Z",
validUntil: "2050-11-01T00:00:00Z",
expirationDate: "2031-11-30T00:00:00Z",
issued: "2021-10-30T00:00:00Z",
credentialSubject: {
id: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbrDgYJoht124ErdE8UUmbXR1gE7MnCayN6VZNuVMBZH2MfNVvbHJNYiHfWBWp3E3X5JnJYadaaL8pyJWh1a6JYpAkDKhUtefYDNZcv3BdDMvfp7auC1DVjs8ECRmKPPCw7r",
},
credentialSchema: {
id: "https://api-pilot.ebsi.eu/trusted-schemas-registry/v3/schemas/z3MgUFUkb722uq4x3dv5yAJmnNmzDFeK5UC8x83QoeLJM",
type: "FullJsonSchemaValidator2021",
},
} satisfies EbsiVerifiableAttestation;
Specify the options to validate the issuer and credential:
import type { CreateVerifiableCredentialOptions } from "@cef-ebsi/verifiable-credential";
const options = {
// REQUIRED. EBSI URI Authority ([userinfo "@"] host [":" port])
ebsiAuthority: "api-pilot.ebsi.eu",
// OPTIONAL. EBSI environment configuration.
// This option allows you to override the default URLs (TIR, DIDR, TSR).
ebsiEnvConfig: {
didRegistry: "https://api-pilot.ebsi.eu/did-registry/v5/identifiers",
trustedIssuersRegistry:
"https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers",
trustedPoliciesRegistry:
"https://api-pilot.ebsi.eu/trusted-policies-registry/v3/users",
},
// OPTIONAL. Timeout after which the requests made by the library will fail. Default: 15 seconds
timeout: 15_000,
// OPTIONAL. List of trusted hostnames. To be used if the Core Services APIs are hosted on a custom host for instance.
// If `trustedHostnames` is not defined, the default trusted domains are: "api-test.ebsi.eu", "api-conformance.ebsi.eu", and "api-pilot.ebsi.eu"
trustedHostnames: ["api.example.net"],
// OPTIONAL. Determines whether to validate the Verifiable Credential payload or not.
// Validation is active by default.
// Note: even when skipValidation is set to true, the payload must be a valid EBSI Verifiable Attestation.
skipValidation: false,
// OPTIONAL. Determines whether to validate the accreditations of the VC issuer or not.
// Validation is active by default.
skipAccreditationsValidation: false,
// OPTIONAL. Determines whether to validate the credential status or not.
// Validation is active by default.
skipStatusValidation: false,
} satisfies CreateVerifiableCredentialOptions;
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);
// eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0FMZ0tKTnBLajdVOWpkWUFIdTNueEo0Zm9uY2tUQkJHV0VMUnBISlo5ZEJLUnpHZWJiTllUejZiV3RhVE0zenl5V25ya2ZiOHc1b3dVMUVDdzJXN3UxUnoyQjVNZ29jTW5uYWE5d3pEQjNwYUVRdmNndGg5RXJZYXdiTnU5TUxMYyN6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzQUxnS0pOcEtqN1U5amRZQUh1M254SjRmb25ja1RCQkdXRUxScEhKWjlkQktSekdlYmJOWVR6NmJXdGFUTTN6eXlXbnJrZmI4dzVvd1UxRUN3Mlc3dTFSejJCNU1nb2NNbm5hYTl3ekRCM3BhRVF2Y2d0aDlFcllhd2JOdTlNTExjIn0.eyJqdGkiOiJ1cm46dXVpZDowMDNhMWRkOC1hNWQyLTQyZWYtODE4Mi1lOTIxYzBhOWYyY2QiLCJzdWIiOiJkaWQ6a2V5OnoyZG16RDgxY2dQeDhWa2k3SmJ1dU1tRllyV1BnWW95dHlrVVozZXlxaHQxajlLYnJEZ1lKb2h0MTI0RXJkRThVVW1iWFIxZ0U3TW5DYXlONlZaTnVWTUJaSDJNZk5WdmJISk5ZaUhmV0JXcDNFM1g1Sm5KWWFkYWFMOHB5SldoMWE2SllwQWtES2hVdGVmWUROWmN2M0JkRE12ZnA3YXVDMURWanM4RUNSbUtQUEN3N3IiLCJpc3MiOiJkaWQ6a2V5OnoyZG16RDgxY2dQeDhWa2k3SmJ1dU1tRllyV1BnWW95dHlrVVozZXlxaHQxajlLYnNBTGdLSk5wS2o3VTlqZFlBSHUzbnhKNGZvbmNrVEJCR1dFTFJwSEpaOWRCS1J6R2ViYk5ZVHo2Yld0YVRNM3p5eVducmtmYjh3NW93VTFFQ3cyVzd1MVJ6MkI1TWdvY01ubmFhOXd6REIzcGFFUXZjZ3RoOUVyWWF3Yk51OU1MTGMiLCJuYmYiOjE2MzU3MjQ4MDAsImV4cCI6MTk1Mzc2MzIwMCwiaWF0IjoxNjM1NTUyMDAwLCJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJpZCI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJWZXJpZmlhYmxlQXR0ZXN0YXRpb24iXSwiaXNzdWVyIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzQUxnS0pOcEtqN1U5amRZQUh1M254SjRmb25ja1RCQkdXRUxScEhKWjlkQktSekdlYmJOWVR6NmJXdGFUTTN6eXlXbnJrZmI4dzVvd1UxRUN3Mlc3dTFSejJCNU1nb2NNbm5hYTl3ekRCM3BhRVF2Y2d0aDlFcllhd2JOdTlNTExjIiwiaXNzdWFuY2VEYXRlIjoiMjAyMS0xMS0wMVQwMDowMDowMFoiLCJ2YWxpZEZyb20iOiIyMDIxLTExLTAxVDAwOjAwOjAwWiIsInZhbGlkVW50aWwiOiIyMDUwLTExLTAxVDAwOjAwOjAwWiIsImV4cGlyYXRpb25EYXRlIjoiMjAzMS0xMS0zMFQwMDowMDowMFoiLCJpc3N1ZWQiOiIyMDIxLTEwLTMwVDAwOjAwOjAwWiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JyRGdZSm9odDEyNEVyZEU4VVVtYlhSMWdFN01uQ2F5TjZWWk51Vk1CWkgyTWZOVnZiSEpOWWlIZldCV3AzRTNYNUpuSllhZGFhTDhweUpXaDFhNkpZcEFrREtoVXRlZllETlpjdjNCZERNdmZwN2F1QzFEVmpzOEVDUm1LUFBDdzdyIn0sImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L3RydXN0ZWQtc2NoZW1hcy1yZWdpc3RyeS92My9zY2hlbWFzL3ozTWdVRlVrYjcyMnVxNHgzZHY1eUFKbW5ObXpERmVLNVVDOHg4M1FvZUxKTSIsInR5cGUiOiJGdWxsSnNvblNjaGVtYVZhbGlkYXRvcjIwMjEifX19.BArwMltlr61I9Pg_SOtewJJF6IfDbo0I2RHFQtM7JPQ8ZWjmPuIU2sH7SnT1yTPC_xWFvmG363U6DNFChnpvGQ
Verifying JWTs
Prerequisites
Verify a VC JWT using the verifyCredentialJwt
function:
import {
verifyCredentialJwt,
type VerifyCredentialOptions,
} from "@cef-ebsi/verifiable-credential";
const vcJwt =
"eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QiLCJraWQiOiJkaWQ6ZWJzaTp6eGFZYVV0Yjhwdm9BdFlOV2JLY3ZlZyNDSHhZek9xdDM4U3g2WUJmUFloaUVkZ2N3eldrOXR5N2swTEJhNmg3MG5jIn0.eyJqdGkiOiJ1cm46dXVpZDowMDNhMWRkOC1hNWQyLTQyZWYtODE4Mi1lOTIxYzBhOWYyY2QiLCJzdWIiOiJkaWQ6a2V5OnoyZG16RDgxY2dQeDhWa2k3SmJ1dU1tRllyV1BnWW95dHlrVVozZXlxaHQxajlLYnNOZ2V6dEJGWEVCOUZVWkNvdWZUalhpVFVaWUtrY1AzNmkyWEFRQ3BoZnhCd3ZYRzRkQWFGNnBkd2hyTUd5YUxNQzgxZlU1RUNNbnQ0VmdNUXB3aDNzbjV2U2JVcHdvYVRCTUU3OG5vWEphVExna0N2NUtrTTZWZ0dUZldVakg4WjIiLCJpc3MiOiJkaWQ6ZWJzaTp6eGFZYVV0Yjhwdm9BdFlOV2JLY3ZlZyIsIm5iZiI6MTYzNTcyNDgwMCwiZXhwIjoxOTUzNzYzMjAwLCJpYXQiOjE2MzU1NTIwMDAsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sImlkIjoidXJuOnV1aWQ6MDAzYTFkZDgtYTVkMi00MmVmLTgxODItZTkyMWMwYTlmMmNkIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIlZlcmlmaWFibGVBdHRlc3RhdGlvbiJdLCJpc3N1ZXIiOiJkaWQ6ZWJzaTp6eGFZYVV0Yjhwdm9BdFlOV2JLY3ZlZyIsImlzc3VhbmNlRGF0ZSI6IjIwMjEtMTEtMDFUMDA6MDA6MDBaIiwidmFsaWRGcm9tIjoiMjAyMS0xMS0wMVQwMDowMDowMFoiLCJ2YWxpZFVudGlsIjoiMjA1MC0xMS0wMVQwMDowMDowMFoiLCJleHBpcmF0aW9uRGF0ZSI6IjIwMzEtMTEtMzBUMDA6MDA6MDBaIiwiaXNzdWVkIjoiMjAyMS0xMC0zMFQwMDowMDowMFoiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic05nZXp0QkZYRUI5RlVaQ291ZlRqWGlUVVpZS2tjUDM2aTJYQVFDcGhmeEJ3dlhHNGRBYUY2cGR3aHJNR3lhTE1DODFmVTVFQ01udDRWZ01RcHdoM3NuNXZTYlVwd29hVEJNRTc4bm9YSmFUTGdrQ3Y1S2tNNlZnR1RmV1VqSDhaMiJ9LCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjMvc2NoZW1hcy96M01nVUZVa2I3MjJ1cTR4M2R2NXlBSm1uTm16REZlSzVVQzh4ODNRb2VMSk0iLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn0sInRlcm1zT2ZVc2UiOnsiaWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L3RydXN0ZWQtaXNzdWVycy1yZWdpc3RyeS92NS9pc3N1ZXJzL2RpZDplYnNpOnp4YVlhVXRiOHB2b0F0WU5XYktjdmVnL2F0dHJpYnV0ZXMvYjQwZmQ5YjQwNDQxOGE0NGQyZDk5MTEzNzdhMDMxMzBkZGU0NTBlYjU0NmM3NTViNWI4MGFjZDc4MjkwMmU2ZCIsInR5cGUiOiJJc3N1YW5jZUNlcnRpZmljYXRlIn19fQ.I8Im8azp0pSnM4z_jqGTTfYUg7K802POR2LTJftVfjYtMt82Cik2Z_KGOG7dHhx13R6VGVZKg9134ke1bKhtPw";
const options = {
// REQUIRED. EBSI URI Authority ([userinfo "@"] host [":" port])
ebsiAuthority: "api-pilot.ebsi.eu",
// OPTIONAL. EBSI environment configuration.
// This option allows you to override the default URLs (TIR, DIDR, TSR).
ebsiEnvConfig: {
didRegistry: "https://api-pilot.ebsi.eu/did-registry/v5/identifiers",
trustedIssuersRegistry:
"https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers",
trustedPoliciesRegistry:
"https://api-pilot.ebsi.eu/trusted-policies-registry/v3/users",
},
// OPTIONAL. Timeout after which the requests made by the library will fail. Default: 15 seconds
timeout: 15_000,
// OPTIONAL. List of trusted hostnames. To be used if the Core Services APIs are hosted on a custom host for instance.
// If `trustedHostnames` is not defined, the default trusted domains are: "api-test.ebsi.eu", "api-conformance.ebsi.eu", and "api-pilot.ebsi.eu"
trustedHostnames: ["api.example.net"],
// OPTIONAL. Unix timestamp. Optional comparison date.
// For the JWT to be valid, `nbf` ≤ `validAt` ≤ `exp`.
validAt: 1686048193,
// OPTIONAL. Determines whether or not to validate the issuer's accreditations when `termsOfUse` is missing. Default: false
validateAccreditationWithoutTermsOfUse: false,
// OPTIONAL. Determines whether to validate the accreditations of the VC issuer or not.
// Validation is active by default.
skipAccreditationsValidation: false,
// OPTIONAL. Determines whether to validate the credential status or not.
// Validation is active by default.
skipStatusValidation: false,
} satisfies VerifyCredentialOptions;
const verifiedVc = await verifyCredentialJwt(vcJwt, options);
console.log(verifiedVc);
/*
{
'@context': [ 'https://www.w3.org/2018/credentials/v1' ],
id: 'urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd',
type: [ 'VerifiableCredential', 'VerifiableAttestation' ],
issuer: 'did:ebsi:zxaYaUtb8pvoAtYNWbKcveg',
issuanceDate: '2021-11-01T00:00:00Z',
validFrom: '2021-11-01T00:00:00Z',
validUntil: '2050-11-01T00:00:00Z',
expirationDate: '2031-11-30T00:00:00Z',
issued: '2021-10-30T00:00:00Z',
credentialSubject: {
id: 'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsNgeztBFXEB9FUZCoufTjXiTUZYKkcP36i2XAQCphfxBwvXG4dAaF6pdwhrMGyaLMC81fU5ECMnt4VgMQpwh3sn5vSbUpwoaTBME78noXJaTLgkCv5KkM6VgGTfWUjH8Z2'
},
credentialSchema: {
id: 'https://api-pilot.ebsi.eu/trusted-schemas-registry/v3/schemas/z3MgUFUkb722uq4x3dv5yAJmnNmzDFeK5UC8x83QoeLJM',
type: 'FullJsonSchemaValidator2021'
},
termsOfUse: {
id: 'https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:zxaYaUtb8pvoAtYNWbKcveg/attributes/b40fd9b404418a44d2d9911377a03130dde450eb546c755b5b80acd782902e6d',
type: 'IssuanceCertificate'
}
}
*/
Verification process
The verification of the credentials is performed using the following process:
- Header
- The
alg
property must beES256
,ES256K
,Ed25519
, orEdDSA
. - The
kid
property must contain the DID of the issuer and the fragment identifier allowing to know which verification method to use.
- Basic properties in the payload
- The payload must contain a
vc
property containing an EBSI Verifiable Attestation. - The
iss
property must match the VC issuervc.issuer
. - The
sub
property must match the VC credential subjectvc.credentialSubject.id
. - The
jti
property must match the VC IDvc.id
. - The
iat
property must refer to the date in VC issuedvc.issued
. - The
nbf
property must refer to the date in VC valid fromvc.validFrom
. - The
exp
property mush refer to date in VC expiration datevc.expirationDate
in the case it is defined.
- Signature
- The signature must be validated against the verification method from the DID document corresponding to the VC JWT
kid
header.
- Extra validations to the VC payload
- Validation of
@context
. - Validation of
type
. - Validation of dates.
- Issuer in Trusted Issuers Registry
If the issuer is a Legal Entity:
- The issuer must be registered in the Trusted Issuers Registry.
Additionally, if the VC is an attestation with accreditation:
- The VC must contain a
termsOfUse
property pointing to the accreditations of the issuer. - The issuer must be accredited to issue the types present in the credential.
- Credential subject
- The credential subject must be a valid DID, using either the
did:ebsi
v1 method (Legal Entity) or thedid:key
method (Natural Person).
- Credential schema
- The VC credential schema(s) must link to valid EBSI credential schemas, registered in the Trusted Schemas Registry.
- The credential payload is validated against the aforementioned JSON Schemas.
Axios config defaults
The library uses the global axios instance to make HTTP requests. If needed, you can specify config defaults. More information on axios configuration can be found here.
For instance, if you want to override the default HTTPS agent with a custom agent using https-proxy-agent, you can do it like so:
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";
axios.defaults.httpsAgent = new HttpsProxyAgent("http://168.63.76.32:3128");
Try it online
The VC & VP validator tool uses the @cef-ebsi/verifiable-credential
to verify VC JWTs.