APIHub configuration (RFC-100)

Document Maintainers: Andi Gabriel Tan 2024. List of other contributors in Annex. 1.

Copyright: MIT license

Copyright © 2018-2024 Axiologic Research and Contributors.

This document is licensed under MIT license.

Abstract

This RFC provides Documentation for the implementation of the APIHub and its configuration.

Purpose

APIHub is an HTTP server that offers functionality to the OpenDSU SDK (typically openDSU wallets): encrypted bricks storage, blockchain anchoring, message queues (DID centered), KeySSI notifications, BDNS, and access to smart contracts. All these functionalities are grouped as "components'' that expose various endpoints.

Most of the components are associated with “blockchain domains”, and the endpoints are typically in the form of: “component/blockchainDomain/action/params”

Figure 1: APIHub

APIHub is extensible in the sense that you can add new components. However, this should not be abused. When possible, the components rely on “external adapters” in the sense that they delegate the actual implementation to some external systems that offer stronger implementation of the expected logic. To support the OpenDSU programmers' experience (make the development cycle faster and avoid the installation of many external systems), all the components have a basic implementation that does not require an external system. For example, APIHub offers a simulated blockchain for anchoring and a simulated message queue. Sometimes, these “simulated” systems are good enough even for production but of course, do not offer all the expected properties (for example, the simulated blockchain is just a single node ledger).

1. APIHub Configuration

Figure 2: APIHub Workspace Configuration

1.1 Main configuration - file apihub.json

The location from where the apihub.json file is read from the env variable is PSK_CONFIG_LOCATION. If this variable is not set, then the default configuration is used. Any custom configuration added to the apihub.json file will be merged with the default config of APIHub. By doing this, the apihub.json can contain only the settings that need to be changed.

The apihub.json file content needs to be JSON valid. Any mistakes during editing of this file can generate strange behaviors of the APIHub, like components not loading, wrong components configuration etc.

APIHub Configuration entries Description  
storage The folder in which the APIHub server stores its files. The path can be relative or absolute. The path is resolved using path.resolve from NodeJS. When a relative path is used, it is relative to the PrivateSky folder.
Default: {$PSK_ROOT_INSTALATION_FOLDER}/tmp		  
sslFolder The folder in which APIHub looks for SSL certificates when started. If the folder contains certificates, the APIHub is started as an HTTPS server; otherwise, APIHub is an HTTP server. By default, APIHub is an HTTP server (sslFolder is empty). If SSL certificates are copied into the sslFolder, then APIHub is started as an HTTPS server.The path can be relative or absolute. The path is resolved using path.resolve from NodeJS. When a relative path is used, it is relative to the PrivateSky folder.
If sslFolder is set up, then server.cert and server.key files are used.
Note: Even if APIHUB can be configured to use HTTPS, we recommend using a proxy (like Nginx) for this.		  
port The port that the server uses to listen for requests.
Default: 8080		  
host If the host is omitted, the server will accept connections on the unspecified IPv6 address when IPv6 is available or the unspecified IPv4 address (0.0.0.0) otherwise.
In most operating systems, listening to the unspecified IPv6 address may cause the net. The server to also listen on the unspecified IPv4 address (0.0.0.0).
Default:0.0.0.0		  
preventRateLimit A flag that determines if the APIHub’s throttling component is enabled.
Default: true (means that throttling is disabled)		  
activeComponents An array that contains the names of the services/components that the server provides/uses.
Important note: staticServer component should be the last in the activeComponents list because the server loads the middlewares in the order they are declared in activeComponents and staticServer handles the requests not processed by the other middlewares.		  
componentsConfig An object that contains the service’s configurations. Each service declared in activeComponents should have the module property componentsConfig set. The module property is either a file system path to a module that contains the service or the name of a PrivateSky module. When you add a new component in the active components list you need to point to the index file that needs to be loaded.
“activeComponents”: […“mq”…],
“componentsConfig”: {
“mq”:{
“module”: “./components/mqHub”,
“function”: “MQHub”,
}
}.
If the index file set up by the “module” property doesn’t export only one method then we need to provide the “function” property to indicate which method needs to be called.The method exported by the module will be called with the server object that gives access to register new endpoints or middlewares.		  
CORS An object that contains the headers that are added on every OPTIONS response by the CORS middleware.
Default: {
“Access-Control-Allow-Methods” : “POST, GET, PUT, DELETE, OPTIONS”
“Access-Control-Allow-Credentials” : true,
“Access-Control-Max-Age” : ‘3600’,
“Access-Control-Allow-Headers” : “Content-Type,
Content-Length, X-Content-Length, Access-Control-Allow-Origin, User-Agent, Authorization”}
Example:
“CORS”: {
“Access-Control-Allow-Methods”: “POST, GET, PUT, DELETE, OPTIONS”,
“Access-Control-Allow-Origin”: “example.com”
}		  
tokenBucket Experimental feature for throttling
Default: “tokenBucket”: {
“cost”: {
“low”: 10
medium”: 100
“high”: 500
}, “error”: {
“limitExceeded”: “error_limit_exceeded”,
“badArgument”: “error_bad_argument”
},
“startTokens”: 6000,
“tokenValuePerTime”: 10,
“unitOfTime”: 100
}.
  
enableInstallationDetails A flag which determines if the endpoint /installation-details is enabled which returns information about the commit SHA of the privatesky and workspace projects.
<p style='text-align: justify;'>Default</p>: true
Output example of the /installation-details endpoint
{
“ePI-workspace”: {
“commitNo”: “bcsdc3”,
“commitMessage”: “new freeze version”
},
privatesky”: {
“commitNo”: “1f0dfec”
“commitMessage”: “new freeze version”
}
}		  
enableRequestLogger A flag that specifies if each request that arrives at the server is logged.
Default: true
Log format: {$interface}:{$port} - [${timestamp}] {$HTTPMethodName}:{$path} {$status} {$duration}
Output example:
127.0.0.1:8080 - [2022-02-09T08:23:01.390Z]
PUT:/bricking/vault/put-brick 201 1.359ms.		  
enableOAuth A flag that specifies if the SSO component is enabled.
Default: false
Notes: For extra information about the SSO integration, please read the chapter “Access control to APIHUB services by SSO integration”.		  
enableLocalhostAuthorization A flag that specifies if authentication is required when SSO is enabled and the APIHub server runs on localhost.
Default: false		  
skipOAuth An array of paths that do not require authentication when the SSO component is enabled.
Default: []		  
responseHeaders An object that contains the headers that are added on every server response.
Default: {}
Example:
“responseHeaders”: {
“X-Frame-Options”: “SAMEORIGIN”,
“X-XSS-Protection”: “1; mode=block”
}		  
oauthConfig A flag that specifies if the OAuth flow is done on the client or on the server. The integration is based on Authentication code flow with pkce.
Default: false		  
readOnlyFile Specify the name (may include path to the file if need it) of the file that signals the APIHub instance to transition into readonly mode.
When the system is in readonly mode, all requests using HTTP methods other than GET will receive a 405 status code response.
Default: readonly		  
readOnlyInterval In milliseconds, the number used to set the interval for checking the conditions to enter readonly mode is defined.
Default: 60000 msec		  
workers The APIHub can start in cluster mode*, and the number of workers can be specified.
* Not all APIHub components are ready yet to be available in cluster mode.
Default: 1		  

1.2 Blockchain Domain-specific configuration

The Blockchain Domain-specific configuration can override any apihub.json config for the specific domain. Except for the following configurations, there are some specific component settings that can also be added to the domain-specific configuration. Scroll down for each component's custom configuration possibilities.

Configuration Description
enable The list of APIHub components enabled for the current domain.
For example, even if the MQ component is present in the apihubConfig.activeComponents list, the MQs are not active by default for any domains. Thus, in the domain-specific configuration, we need to enable it, just for those domains that need this feature.

1.3 Access control to APIHub services by using SSO integration

SSO integration is optional but could add a new level of security to the OpenDSU wallets. The SSO component is disabled by default but, when enabled, it will check the configured endpoints against the existence of the appropriate JWT token. The SSO component is working with an SSO Adapter for an external SSO Provider. The SSO Provider will offer the actual user management. The SSO component exposes the following endpoints:

  • getAuthToken: require as input a refresh token
  • login: returns a refresh token
  • getEncryptedProfile
  • updateEncryptedProfile
  • getSecurityPolicies:
    • enabled: true or false
    • type of login
    • return a URL for login if the login should happen in the SSO provider
    • encryptedProfile (true or false)

Figure 3: TrustLoader

The TrustLoader will check if the SSO is enabled and, if it is, it will display a login page (user, password). On successful login, it will receive a refreshed token that will be saved in the wallet (in environment.js). OpenDSU SDK will check if SSO is enabled by looking for the refresh token in its environment. If it is available, it will request an Authentication Token. After that, OpenDSU SDK will send an authentication token at each request. Each domain configuration will have a list of endpoints that require SSO authentication.

The SSO Adapter and the SSO Provider should be deployed as distinct containers. The main benefit of the SSO Adapter is that it isolates dependencies on any specific SSO protocol. This way, the APIHub code remains clean and independent from the particularities of the actual implementations.

1.4 Trust loader specific configuration and conventions

Configuration Description
appName The name of application.
vault Specifies where the bricks and anchors for the vault domain are stored. If vault: server, the bricks, and anchors are stored in the APIHub server; if vault: browser, the anchors and bricks are stored in the browser’s indexedDb.
agent mobile, browser
System The system on which the application is running (IOS, Android, or any).
browser The browser in which the application is running (Chrome, Firefox, or any).
mode The wallet’s authentication mode (autologin, dev-secure, secure). In autologin mode, the authentication is skipped; in dev-secure mode, the default credentials are used for authentication, and in secure mode, no default credentials are used.
vaultDomain The domain used as a vault (anchoring wallets).
didDomain The domain used to store for OpenDSU did methods.
enclaveType The type of enclave used for storing private keys (MemoryEnclave, WalletDBEnclave, ApihubProxy, HighSecurityProxy). By default enclaveType is MemoryEnclave.
sw A flag that specifies if the service workers are enabled for the current wallet.
pwa A flag that specifies if the current wallet is a PWA.

2. Components

Components Description
Anchoring Allows writing and reading of anchors for DSUs.
Bricking Allow writing and reading of bricks for DSUs.
BDNS Returns anchoring and bricking endpoints for each blockchain.
Logging Logs every request that arrives on the server.
Static Server Resolves requests that are not processed by the other components.
Files Uploader Allows uploading and downloading files.
Service Workers Simulator No domain.
Installation Info Returns the commit number and message for the OpenDSU installation used to run the APIHub server.
Message Queues Allow the writing, deleting, and reading of messages in and from a channel.
Notifications Allow subscribing for and publishing messages based on KeySSIs.
Smart Contracts Allow the execution of commands in a domain.

3. Components specific configuration

3.1 Anchoring component configuration

APIHub Configuration Description
anchoring Each domain needs to have configured which anchoring strategies is used.
Current options: “FS” or “ETH”. Other options under development are “FSX” and “Fabric”.
Example of how to configure FS anchoring strategy:
“anchoring”: {
“type”: “FS”,
}
Example of how to configure ETH/Quorum anchoring strategy:
“anchoring”: {
“type”: “ETH”,
“option”: {
“endpoint”: “http(s)://host:port”
}
anchoringStrategy default BricksLedgerAnchoringStrategy

3.2 Bricking component configuration

Bricking Configuration Description
module  
BrickingStorageStrategy default FSBrick
Service Worker Simulator Description
iframeHandlerDsuBootPath  
Configuration Description
module  

3.3 Message Queue Component Configuration

This APIHub component offers a MQ implementation that uses DID to identify the resources. Exposes a list of endpoints for sending and receiving messages towards message queues.

Message Queues Description
mq_strategyName Options:
MQ_FS_Strategy = stores the messages to a path specified using mq_fsStrategyStorageFolder
mq_fsStrategyStorageFolder If MQ_FS_Strategy is used, this config needs to be set in order to define where all the messages are persisted.
Default value
{$apihubConfig.storageFolder}/mqs/{$domainName}
mq_fsMessageMaxSize Max size of a message. Default value 10 * 1024
mq_fsQueueLength Length of a message queue. Default value 100.
mq_client_timeout The timeout value for the client requests that will wait for the queue to have a message for them.
Default value 60 sec. Keep in mind that other gateways may be configured with a 30-second timeout and will close the request with a Gateway timeout error.
mq_throttling Throttling limit for each queue. Default value 2. Not used for the moment.
mq_allow_unregistered_did Boolean variable that enables unregistered DIDs to use the queues.
Default value false

Contributors

  1. Axiologic Research: New content and improvements. Original texts under PharmaLedger Association and Novartis funding. MIT licensed content accordingly with the contracts. Publish and maintain the www.opendsu.org site.

  2. PharmaLedger Project: Review, feedback, observations, new content, and corrections MIT licensed accordingly with the consortium agreements.

  3. PrivateSky Research Project: MIT licensed content accordingly with the contracts. https://profs.info.uaic.ro/~ads/PrivateSky/

Annex 1. Contributors

Current Editors Email
Sînică Alboaie sinica.alboaie@axiologic.net
Cosmin Ursache cosmin@axiologic.net
Teodor Lupu teodor@axiologic.net
Andi-Gabriel Țan andi@axiologic.net
Contributors Axiologic Research Email
Adrian Ganga adrian@axiologic.net
Andi-Gabriel Țan andi@axiologic.net
Cosmin Ursache cosmin@axiologic.net
Daniel Sava daniel@axiologic.net
Nicoleta Mihalache nicoleta@axiologic.net
Valentin Gérard valentin@axiologic.net
PrivateSky Contributors Email
Alex Sofronie alsofronie@gmail.com (DPO)
Cosmin Ursache cos.ursache@gmail.com (UAIC)
Daniel Sava sava.dumitru.daniel@gmail.com (HVS, AQS)
Daniel Visoiu visoiu.daniel.g@gmail.com (SGiant)
Lenuța Alboaie lalboaie@gmail.com (UAIC)
Rafael Mastaleru rafael@rms.ro (RMS)
Sînică Alboaie salboaie@gmail.com (UAIC)
Vlad Balmos vlad.balmos@gmail.com (Code932)
PharmaLedger Contributors Email
Ana Balan bam@rms.ro (RMS)
Bogdan Mastahac mab@rms.ro (RMS)
Cosmin Ursache cos@rms.ro (RMS)
Rafael Mastaleru raf@rms.ro (RMS)