![EBSI Logo](https://ec.europa.eu/digital-building-blocks/sites/images/logo/default-space-logo.svg)

# Trusted Nodes List

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

## Table of Contents

1. [Installation](#installation)
2. [Usage](#usage)
3. [License](#license)

## Installation

```bash
npm i --save @europeum-ebsi/trusted-nodes-list
```

## Usage

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

### `getTrustedNodesList`

The function `getTrustedNodesList` will fetch the TNL JWTs from GitLab — i.e. the default location. Internally, it will pre-configure the source and pass it to `getTrustedNodesListFromSources`.

```typescript
import { getTrustedNodesList } from "@europeum-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)
const trustedNodesList = await getTrustedNodesList("pilot", {
  timeout: 10_000, // Default: 30_000
});

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

## License

Copyright (C) 2026 European Union

This program is free software: you can redistribute it and/or modify it under the terms of the EUROPEAN UNION PUBLIC LICENCE v. 1.2 as published by the European Union.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the EUROPEAN UNION PUBLIC LICENCE v. 1.2 for further details.

You should have received a copy of the EUROPEAN UNION PUBLIC LICENCE v. 1.2. along with this program. If not, see <https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12>.