Client

The Client library serves to alleviate the Egendata integration complexity for Service providers.

For reference, the following example sites utilize the Client library:

Usage

The Client library is distributed via the NPM software registry and can be installed with:

npm install @egendata/client

Import and start using the Client library:

const client = require('@egendata/client');

// A key-value based storage module that implements the required interface methods listed below:
//   * keyValueStore.save(key, value, ttl)
//   * keyValueStore.load(key)
//   * keyValueStore.remove(key)
const keyValueStore = require('../services/keyValueStore')

// An example Client configuration
const config = {
  displayName: 'My service',
  description: 'A service that integrates with Egendata',
  iconURI: 'http://my-service-domain.com/icon.png',
  clientId: process.env.CLIENT_ID,
  operator: process.env.OPERATOR_URL,
  jwksPath: '/jwks',
  eventsPath: '/events',
  clientKey: process.env.PRIVATE_KEY,
  keyValueStore: keyValueStore,
  defaultPermissions: [
    {
      area: 'baseData',
      types: ['READ', 'WRITE'],
      purpose: 'Purpose of requesting permission.',
      description: 'Short description of requested permission.'
    }
  ]
}

// Create the Client which will be used all communication with Egendata Operator.
client.create(config)

Client configuration properties

Configuration property Data type Purpose
displayName string Name of this service/application
description string A short description of this Service
iconURI string A URI to this service’s logotype/icon
clientId string This is the identifier which this service will use to identify/register itself to the Operator with. Typically this will be the public https://domain:port this service is hosted on
operator string This is field specifies the https://domain:port to the central Operator service.
jwksPath string This field specifies where this service’s JWKS is exposed/found, e.g. /jwks
clientKey string This field specifies the private key(PEM/JWK) this service will use for encrypting- and signing of data.
keyValueStore object A reference to an object/adapter which can read, write and remove data to/from a storage. The keyValueStore must implement the following interface: keyValueStore.save(key, value, ttl), keyValueStore.load(key) and keyValueStore.remove(key).
defaultPermissions array An array of desired read/write permissions
defaultPermissions.#.area string An area describes where in the user’s PDS to store/read data from, e.g. baseData or experiences
defaultPermissions.#.types array An array that denotes which types of permissions are desired for this specific area. e.g. ['READ'], ['WRITE'] or both ['READ', 'WRITE']
defaultPermissions.#.purpose string A short purpose description of why this service requests this specific read/write permission, e.g. 'In order to create a CV using our website.'
defaultPermissions.#.description string _A short description of the area this permission request relates to, e.g. 'Personal information.'

Key Provider

The KeyProvider class is responsible for keeping track of known keys and tokens.

A configuration object must be passed into the KeyProvider constructor upon initialization. There are 5 configuration properties that affect the construction of the KeyProvider object.

  • config.clientKey
  • config.keyValueStore
  • config.keyOptions
  • config.jwksURI
  • config.alg

The KeyProvider will utilize the keyValueStorage property to read and write from/to an external storage. E.g. The Egendata Example-CV service provides an adapter for a locally hosted the Redis database. The KeyProvider assumes that three functions are defined in the referenced KeyValueStore object:

  • keyValueStorage.save(key, value, ttl)
  • keyValueStorage.load(key)
  • keyValueStorage.remove(key)

All values written by the KeyProvider to the external/referenced KeyValueStore are base64 encoded.

The Client signing key(aka. clientKey) is provided through the configuration parameter upon initialization of the Client. This client key is used for all signing done by this Client, however there are future ideas to implement different signing keys for different domains/areas and/or key rotation.

Key Value Store

In order to utilize the Egendata Client, one must first create a KeyValueStore object to be provided in the configuration to the Client constructor.

Interface definition

The following interface is expected to be implemented in the Service’s KeyValueStore object.

Function Description
save(key, value, ttl) • key: The lookup key of which this saved record will be identified by in persistent storage.
• value: The value to be stored in persistent storage.
• ttl: The KeyValueStore must respect the specified TTL(Time to live) of the saved record, as such it must be automatically removed from storage upon TTL expiry.
load(key) • key: The lookup key a record to load and return back to caller.
remove(key) • key: The lookup key of which all associated record(s) shall permanently removed from persistent storage.