This library helps you retrieve and validate the list of trusted nodes for a given EBSI environment.

Installation

Using npm:

npm i --save @cef-ebsi/trusted-nodes-list

Using yarn:

yarn add @cef-ebsi/trusted-nodes-list

Usage

This library exposes 2 main functions: getTrustedNodesList (recommended) and getTrustedNodesListFromSources.

getTrustedNodesList

Warning: the Bitbucket files fetcher doesn't work in a browser because the Bitbucket server doesn't allow cross-origin resource sharing (CORS). If you want to use the @cef-ebsi/trusted-nodes-list in a browser, please use getTrustedNodesListFromSources instead and define custom sources.

The function getTrustedNodesList will fetch the TNL JWTs from Bitbucket and GitLab — i.e. the default locations. Internally, it will pre-configure the 2 sources and pass them to getTrustedNodesListFromSources.

import { getTrustedNodesList } from "@cef-ebsi/trusted-nodes-list";

// The first parameter is the EBSI environment for which we want to retrieve a list of trusted nodes, e.g. "pilot
const trustedNodesList = await getTrustedNodesList("pilot");

// Optionally, you can pass a second parameter which may contain the Axios timeout (default: 30s) and whether Ajv should be used in verbose mode
const trustedNodesList = await getTrustedNodesList("pilot", {
  timeout: 10_000, // Default: 30_000
  verbose: true, // Default: false
});

// The result will look like this:
console.log(trustedNodesList);

/*
Displays:
{
  "list": {
    "chainId": 6179,
    "environment": "pilot",
    "id": "did:ebsi:ztMy7kLecXXvQwDzXYKLQ2j",
    "nodes": [
      {
        "apis": "https://api-pilot.ebsi.example.es",
        "country": "esp"
      },
      {
        "apis": "https://api-pilot.ebsi.example.mt",
        "country": "mlt"
      },
      {
        "apis": "https://api-pilot.ebsi.example2.es",
        "country": "esp"
      }
    ],
    "nodesTotal": 3,
    "version": 1
  },
  "raw": {
    "vc": "<raw VC JWT>",
    "vp": "<raw VP JWT>"
  }
}
*/

getTrustedNodesListFromSources

The function getTrustedNodesListFromSources lets you use custom sources. It is not recommended to use it. Please prefer using the preconfigured getTrustedNodesList function instead.

However, if you still want to use custom sources from where to retrieve the TNL JWTs, you should create a custom source class extending the Source interface, and pass it to the getTrustedNodesListFromSources function.

You can find an example of such a custom source in ./tests/helpers/fs-source.ts.

Try it

CORS issue

Because Bitbucket doesn't allow cross-origin resource sharing, we use a reverse proxy to fetch the files from Bitbucket.

In the interactive example below, we use a custom source which overrides the original BitbucketSource:

bitbucket-proxy-source.ts

import type { BitbucketSourceOptions } from "@cef-ebsi/trusted-nodes-list/sources/bitbucket";

import { BitbucketSource } from "@cef-ebsi/trusted-nodes-list/sources/bitbucket";

export class BitbucketProxySource extends BitbucketSource {
  constructor(network: string, options?: BitbucketSourceOptions) {
    super(network, options);
    this.displayName = "Bitbucket Proxy";
  }

  protected override url(path: string): string {
    const ref = "refs/heads/main";
    // This is the URL of our reverse proxy
    return `/bitbucket/proxy/${path}?at=${encodeURIComponent(ref)}`;
  }
}

We use the custom source alongside the original GitLabSource and we call getTrustedNodesListFromSources to get the Trusted Nodes List:

import { getTrustedNodesListFromSources } from "@cef-ebsi/trusted-nodes-list";
import { GitLabSource } from "@cef-ebsi/trusted-nodes-list/sources/gitlab";
import { BitbucketProxySource } from "./bitbucket-proxy-source.ts";

// Here's how we'd configure the sources and call the getTrustedNodesListFromSources function:
const env = "pilot";
const sources = [new BitbucketProxySource(env), new GitLabSource(env)];
const res = await getTrustedNodesListFromSources(sources, env);

You can try it now:

Select the Environment you want to work with

PilotConformanceTest