@mojaloop/sdk-scheme-adapter 12.0.0 → 12.1.0

package/jest.config.js

@@ -11,5 +11,8 @@ module.exports = {
             lines: 90
         }
     },
-    clearMocks: true
+    clearMocks: true,
+    moduleNameMapper: {
+        "^~/(.*)$": "<rootDir>/src/$1"
+    }
 };

package/package.json

@@ -1,27 +1,30 @@
 {
   "name": "@mojaloop/sdk-scheme-adapter",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "An adapter for connecting to Mojaloop API enabled switches.",
   "main": "index.js",
   "types": "index.d.ts",
   "engines": {
-    "node": ">=14.15"
+    "node": "=16.x"
+  },
+  "_moduleAliases": {
+    "~": "src"
   },
   "scripts": {
     "audit:resolve": "SHELL=sh resolve-audit --production",
     "audit:check": "SHELL=sh check-audit --production",
     "build": "npm run build:openapi; npm run build:dto:outbound",
     "build:openapi": "npm run build:openapi:inbound && npm run build:openapi:outbound",
-    "build:openapi:inbound": "openapi bundle --output ./InboundServer/api.yaml --ext yaml ./InboundServer/api_template.yaml",
-    "build:openapi:outbound": "openapi bundle --output ./OutboundServer/api.yaml --ext yaml ./OutboundServer/api_template/openapi.yaml",
-    "build:dto:outbound": "openapi-typescript ./OutboundServer/api.yaml --output ./OutboundServer/api_interfaces/openapi.d.ts",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
+    "build:openapi:inbound": "openapi bundle --output ./src/InboundServer/api.yaml --ext yaml ./src/InboundServer/api_template.yaml",
+    "build:openapi:outbound": "openapi bundle --output ./src/OutboundServer/api.yaml --ext yaml ./src/OutboundServer/api_template/openapi.yaml",
+    "build:dto:outbound": "openapi-typescript ./src/OutboundServer/api.yaml --output ./src/OutboundServer/api_interfaces/openapi.d.ts",
+    "lint": "eslint ./src/",
+    "lint:fix": "eslint ./src/ --fix",
     "test": "jest --ci --reporters=default --reporters=jest-junit --env=node test/unit/",
     "test:int": "jest --ci --reporters=default --reporters=jest-junit --env=node test/integration",
     "validate:api": "npm run validate:api:in; npm run validate:api:out",
-    "validate:api:in": "swagger-cli validate ./InboundServer/api.yaml",
-    "validate:api:out": "swagger-cli validate ./OutboundServer/api.yaml",
+    "validate:api:in": "swagger-cli validate ./src/InboundServer/api.yaml",
+    "validate:api:out": "swagger-cli validate ./src/OutboundServer/api.yaml",
     "updates:check": "npm run dep:check",
     "updates:update": "npm run dep:update && npm install",
     "dep:check": "npx ncu -e 2",
@@ -49,12 +52,6 @@
     "type": "git",
     "url": "git@github.com:mojaloop/sdk-scheme-adapter.git"
   },
-  "@comment dependencies": [
-    "koa2-oauth-server is an old unmaintained repo. It uses the now unsupported git protocol.",
-    "Please see https://github.blog/2021-09-01-improving-git-protocol-security-github/ for more information.",
-    "If you regenerate package-lock.json, you will manually have to update `git://` to `https://` on its",
-    "dependencies."
-  ],
   "dependencies": {
     "@koa/cors": "^3.1.0",
     "@mojaloop/central-services-error-handling": "11.3.0",
@@ -70,12 +67,15 @@
     "co-body": "^6.1.0",
     "dotenv": "^10.0.0",
     "env-var": "^7.0.1",
+    "express": "^4.17.2",
+    "fast-json-patch": "^3.1.1",
     "javascript-state-machine": "^3.1.0",
     "js-yaml": "^4.1.0",
     "json-schema-ref-parser": "^9.0.9",
     "koa": "^2.13.1",
     "koa-body": "^4.2.0",
-    "koa2-oauth-server": "^1.0.0",
+    "module-alias": "^2.2.2",
+    "oauth2-server": "^4.0.0-dev.2",
     "openapi-jsonschema-parameters": "^9.3.0",
     "promise-timeout": "^1.3.0",
     "redis": "^3.1.2",
@@ -96,7 +96,7 @@
     "jest": "^27.2.0",
     "jest-junit": "^12.2.0",
     "nock": "^13.1.3",
-    "npm-audit-resolver": "^2.3.1",
+    "npm-audit-resolver": "^3.0.0-0",
     "npm-check-updates": "^11.8.5",
     "openapi-response-validator": "^9.3.0",
     "openapi-typescript": "^4.0.2",

package/secrets/jwsSigningKey.key

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEowIBAAKCAQEA0eJEh3Op5p6x137lRkAsvmEBbd32dbRChrCUItZbtxjf/qfB
+yD5k8Hn4n4vbqzP8XSGS0f6KmNC+iRaP74HVgzAqc4Uid4J8dtSBq3VmucYQYzLc
+101QjuvD+SKmZwlw/q0PtulmqlASI2SbMfwcAraMi6ab7v5W4EGNeIPLEIo3BXsQ
+DTCWqiZb7aXkHkcY7sOjAzK/2bNGYFmAthdYrHzvCkqnJ7LAHX3Oj7rJea5MqtuN
+B9POZYaD10n9JuYWdwPqLrw6/hVgPSFEy+ulrVbXf54ZH0dfMThAYRvFrT81yulk
+H95JhXWGdi6cTp6t8LVOKFhnNfxjWw0Jayj9xwIDAQABAoIBADB2u/Y/CgNbr5sg
+DRccqHhJdAgHkep59kadrYch0knEL6zg1clERxCUSYmlxNKSjXp/zyQ4T46b3PNQ
+x2m5pDDHxXWpT10jP1Q9G7gYwuCw0IXnb8EzdB+cZ0M28g+myXW1RoSo/nDjTlzn
+1UJEgb9Kocd5cFZOWocr+9vRKumlZULMsA8yiNwlAfJHcMBM7acsa3myCqVhLyWt
+4BQylVuLFa+A6QzpMXEwFCq8EOXf07gl1XVzC6LJ1fTa9gVM3N+YE+oEXKrsHCxG
+/ACgKsjepL27QjJ7qvecWPP0F2LxEZYOm5tbXaKJTobzQUJHgUokanZMhjYprDsZ
+zumLw9kCgYEA/DUWcnLeImlfq/EYdhejkl3J+WX3vhS23OqVgY1amu7CZzaai6vt
+H0TRc8Zsbi4jgmFDU8PFzytP6qz6Tgom4R736z6oBi7bjnGyN17/NSbf+DaRVcM6
+vnZr7jNC2FJlECmIN+dkwUA/YCr2SA7hxZXM9mIYSc+6+glDiIO5Cf0CgYEA1Qo/
+uQbVHhW+Cp8H0kdMuhwUbkBquRrxRZlXS1Vrf3f9me9JLUy9UPWb3y3sKVurG5+O
+SIlr4hDcZyXdE198MtDMhBIGqU9ORSjppJDNDVvtt+n2FD4XmWIU70vKBJBivX0+
+Bow6yduis+p12fuvpvpnKCz8UjOgOQJhLZ4GQBMCgYBP6gpozVjxkm4ML2LO2IKt
++CXtbo/nnOysZ3BkEoQpH4pd5gFmTF3gUJAFnVPyPZBm2abZvejJ0jGKbLELVVAo
+eQWZdssK2oIbSo9r2CAJmX3SSogWorvUafWdDoUZwlHfoylUfW+BhHgQYsyS3JRR
+ZTwCveZwTPA0FgdeFE7niQKBgQCHaD8+ZFhbCejDqXb4MXdUJ3rY5Lqwsq491YwF
+huKPn32iNNQnJcqCxclv3iln1Cr6oLx34Fig1KSyLv/IS32OcuY635Y6UPznumxe
+u+aJIjADIILXNOwdAplZy6s4oWkRFaSx1rmbCa3tew2zImTv1eJxR76MpOGmupt3
+uiQw3wKBgFjBT/aVKdBeHeP1rIHHldQV5QQxZNkc6D3qn/oAFcwpj9vcGfRjQWjO
+ARzXM2vUWEet4OVn3DXyOdaWFR1ppehz7rAWBiPgsMg4fjAusYb9Mft1GMxMzuwT
+Oyqsp6pzAWFrCD3JAoTLxClV+j5m+SXZ/ItD6ziGpl/h7DyayrFZ
+-----END RSA PRIVATE KEY-----

package/secrets/jwsVerificationKeys/mojaloop-sdk.pem

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0eJEh3Op5p6x137lRkAs
+vmEBbd32dbRChrCUItZbtxjf/qfByD5k8Hn4n4vbqzP8XSGS0f6KmNC+iRaP74HV
+gzAqc4Uid4J8dtSBq3VmucYQYzLc101QjuvD+SKmZwlw/q0PtulmqlASI2SbMfwc
+AraMi6ab7v5W4EGNeIPLEIo3BXsQDTCWqiZb7aXkHkcY7sOjAzK/2bNGYFmAthdY
+rHzvCkqnJ7LAHX3Oj7rJea5MqtuNB9POZYaD10n9JuYWdwPqLrw6/hVgPSFEy+ul
+rVbXf54ZH0dfMThAYRvFrT81yulkH95JhXWGdi6cTp6t8LVOKFhnNfxjWw0Jayj9
+xwIDAQAB
+-----END PUBLIC KEY-----

package/secrets/jwsVerificationKeys/switch.pem

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvs6EjaQYxTPI2dS+L6zJ
+QhszHCP79huvCDPhy/BmTWI4350rjWiclBC/joy7BUGJszIVv6rrwbeN9OORHXwW
+0XSjcCEeksdkAee9kGvx/A2UcUOsQQ3A3IvoxJAv+HJSmCGeKsc2pMrelBtma54i
+1JBF6H+SwrcM0a+UVsADQXOzKuyiRYnkCEhZYHXAk7hM3cARvhYydqUnPehFccjS
+8v6sNTRZnqJ7z/XT3EKYkfizcCkHiV9elB/PGGzkFWLjHZVTC/+hK6WhFYGEktNb
+QfDuMA4mnZT37QZEL1PlhnFfjfnrnpjFjcFzKJ+hHRrHqA9FZlo6J9efnUn/VHVC
+sQIDAQAB
+-----END PUBLIC KEY-----

package/sequences.puml

@@ -0,0 +1,99 @@
+
+
+@startuml
+title Mojaloop SDK Interactions
+autonumber
+
+participant "DFSP Backend" as backend
+participant "ESB/PortX" as esb
+
+box "SDK"
+    participant "SDK Inbound Service" as sib
+    participant "SDK Outbound Service" as sob
+end box
+  
+
+participant "Switch" as sw
+
+
+note over sib, sob: All outbound between SDK and Switch have\nJWS added automatically
+note over sib, sob: All inbound from switch have JWS validated
+
+note over sib, sob: Mapping between scheme transaction types and DFSP\ntransaction types
+note over sib, sob: JWS and TLS keys managed by SDK
+
+== send money ==
+
+    backend -> sob: POST /transfers
+    
+    sob -> sw: GET /parties
+    sw -> sob: PUT /parties
+    sob -> sw: POST /quotes
+    sw -> sob: PUT /quotes
+    sob -> sw: POST /transfers
+    sw -> sob: PUT /transfers
+    
+    sob -> backend: HTTP 200
+
+== query transfer ==
+
+    backend -> sob: GET /transfers/{ID}
+    sob -> sw: GET /transfers/{ID}
+    sw -> sob: PUT /transfers/{ID}
+    sob -> backend: transfer info
+
+== receive money ==
+
+    sw -> sib: GET /parties
+    sib -> esb: GET /parties
+    esb -> backend: lookup user account
+    backend -> esb: user details
+    esb -> sib: user details
+    sib -> sw: PUT /parties
+    
+    sw -> sib: POST /quotes
+    
+    alt SDK handles quote request autonomously
+    
+    sib -> sib: calculate quote
+    
+    else backend calculates quote
+    
+    sib -> esb: POST /quotes
+    esb -> backend: quote request
+    backend -> esb: quote response
+    esb -> sib: quote response
+    
+    end
+    
+    sib -> sib: create ILP packet\ncalculate condition
+    
+    sib -> sw: PUT /quotes
+    
+    sw -> sib: POST /transfers
+    sib -> sib: validate ILP
+    sib -> esb: POST /transfers
+    esb -> backend: accept money?
+    
+    alt accepting money
+    
+        backend -> esb: OK
+        esb -> sib: OK
+        sib -> sib: calculate ILP fulfilment
+        sib -> sw: PUT /transfers
+        
+        sw -> sib: OK notification
+        sib -> esb: OK notification
+        esb -> backend: money received OK
+    
+    else not accepting money
+    
+        backend -> esb: NOK
+        esb -> sib: NOK
+        sib -> sw: PUT /transfers/{ID}/error
+    
+    end
+
+
+@enduml
+

package/src/ControlAgent/index.js

@@ -0,0 +1,221 @@
+/**************************************************************************
+ *  (C) Copyright ModusBox Inc. 2020 - All rights reserved.               *
+ *                                                                        *
+ *  This file is made available under the terms of the license agreement  *
+ *  specified in the corresponding source code repository.                *
+ *                                                                        *
+ *  ORIGINAL AUTHOR:                                                      *
+ *       Matt Kingston - matt.kingston@modusbox.com                       *
+ **************************************************************************/
+
+// This server has deliberately been written separate from any other server in the SDK. There is
+// some reasonable argument that it could be part of the outbound or test server. It has not been
+// incorporated in either as, at the time of writing, it is intended to be maintained in a
+// proprietary fork. Therefore, keeping it independent of other servers will avoid the maintenance
+// burden that would otherwise be associated with incorporating it with those.
+//
+// It inherits from the Server class from the 'ws' websocket library for Node, which in turn
+// inherits from EventEmitter. We exploit this to emit an event when a reconfigure message is sent
+// to this server. Then, when this server's reconfigure method is called, it reconfigures itself
+// and sends a message to all clients notifying them of the new application configuration.
+//
+// It expects new configuration to be supplied as an array of JSON patches. It therefore exposes
+// the current configuration to
+
+const assert = require('assert').strict;
+const ws = require('ws');
+const jsonPatch = require('fast-json-patch');
+const randomPhrase = require('~/lib/randomphrase');
+
+
+/**************************************************************************
+ * The message protocol messages, verbs, and errors
+ *************************************************************************/
+const MESSAGE = {
+    CONFIGURATION: 'CONFIGURATION',
+    ERROR: 'ERROR',
+};
+
+const VERB = {
+    READ: 'READ',
+    NOTIFY: 'NOTIFY',
+    PATCH: 'PATCH'
+};
+
+const ERROR = {
+    UNSUPPORTED_MESSAGE: 'UNSUPPORTED_MESSAGE',
+    UNSUPPORTED_VERB: 'UNSUPPORTED_VERB',
+    JSON_PARSE_ERROR: 'JSON_PARSE_ERROR',
+};
+
+/**************************************************************************
+ * Events emitted by the control client
+ *************************************************************************/
+const EVENT = {
+    RECONFIGURE: 'RECONFIGURE',
+};
+
+/**************************************************************************
+ * Private convenience functions
+ *************************************************************************/
+const serialise = JSON.stringify;
+const deserialise = (msg) => {
+    //reviver function
+    return JSON.parse(msg.toString(), (k, v) => {
+        if (
+            v !== null            &&
+          typeof v === 'object' &&
+          'type' in v           &&
+          v.type === 'Buffer'   &&
+          'data' in v           &&
+          Array.isArray(v.data)) {
+            return new Buffer(v.data);
+        }
+        return v;
+    });
+};
+
+const buildMsg = (verb, msg, data, id = randomPhrase()) => serialise({
+    verb,
+    msg,
+    data,
+    id,
+});
+
+const buildPatchConfiguration = (oldConf, newConf, id) => {
+    const patches = jsonPatch.compare(oldConf, newConf);
+    return buildMsg(VERB.PATCH, MESSAGE.CONFIGURATION, patches, id);
+};
+
+/**************************************************************************
+ * build
+ *
+ * Public object exposing an API to build valid protocol messages.
+ * It is not the only way to build valid messages within the protocol.
+ *************************************************************************/
+const build = {
+    CONFIGURATION: {
+        PATCH: buildPatchConfiguration,
+        READ: (id) => buildMsg(VERB.READ, MESSAGE.CONFIGURATION, {}, id),
+        NOTIFY: (config, id) => buildMsg(VERB.NOTIFY, MESSAGE.CONFIGURATION, config, id),
+    },
+    ERROR: {
+        NOTIFY: {
+            UNSUPPORTED_MESSAGE: (id) => buildMsg(VERB.NOTIFY, MESSAGE.ERROR, ERROR.UNSUPPORTED_MESSAGE, id),
+            UNSUPPORTED_VERB: (id) => buildMsg(VERB.NOTIFY, MESSAGE.ERROR, ERROR.UNSUPPORTED_VERB, id),
+            JSON_PARSE_ERROR: (id) => buildMsg(VERB.NOTIFY, MESSAGE.ERROR, ERROR.JSON_PARSE_ERROR, id),
+        }
+    },
+};
+
+/**************************************************************************
+ * Client
+ *
+ * The Control Client. Client for the websocket control API.
+ * Used to hot-restart the SDK.
+ *
+ * logger    - Logger- see SDK logger used elsewhere
+ * address   - address of control server
+ * port      - port of control server
+ *************************************************************************/
+class Client extends ws {
+    /**
+     * Consider this a private constructor.
+     * `Client` instances outside of this class should be created via the `Create(...args)` static method.
+     */
+    constructor({ address = 'localhost', port, logger, appConfig }) {
+        super(`ws://${address}:${port}`);
+        this._logger = logger;
+        this._appConfig = appConfig;
+    }
+
+    // Really only exposed so that a user can import only the client for convenience
+    get Build() {
+        return build;
+    }
+
+    static Create(...args) {
+        return new Promise((resolve, reject) => {
+            const client = new Client(...args);
+            client.on('open', () => resolve(client));
+            client.on('error', (err) => reject(err));
+            client.on('message', client._handle);
+        });
+    }
+
+    async send(msg) {
+        const data = typeof msg === 'string' ? msg : serialise(msg);
+        this._logger.push({ data }).log('Sending message');
+        return new Promise((resolve) => super.send.call(this, data, resolve));
+    }
+
+    // Receive a single message
+    async receive() {
+        return new Promise((resolve) => this.once('message', (data) => {
+            const msg = deserialise(data);
+            this._logger.push({ msg }).log('Received');
+            resolve(msg);
+        }));
+    }
+
+    // Close connection
+    async stop() {
+        this._logger.log('Control client shutting down...');
+        this.close();
+    }
+
+    reconfigure({ logger = this._logger, port = 0, appConfig = this._appConfig }) {
+        assert(port === this._socket.remotePort, 'Cannot reconfigure running port');
+        return () => {
+            this._logger = logger;
+            this._appConfig = appConfig;
+            this._logger.log('restarted');
+        };
+    }
+
+    // Handle incoming message from the server.
+    _handle(data) {
+        // TODO: json-schema validation of received message- should be pretty straight-forward
+        // and will allow better documentation of the API
+        let msg;
+        try {
+            msg = deserialise(data);
+        } catch (err) {
+            this._logger.push({ data }).log('Couldn\'t parse received message');
+            this.send(build.ERROR.NOTIFY.JSON_PARSE_ERROR());
+        }
+        this._logger.push({ msg }).log('Handling received message');
+        switch (msg.msg) {
+            case MESSAGE.CONFIGURATION:
+                switch (msg.verb) {
+                    case VERB.NOTIFY:
+                    case VERB.PATCH: {
+                        const dup = JSON.parse(JSON.stringify(this._appConfig)); // fast-json-patch explicitly mutates
+                        jsonPatch.applyPatch(dup, msg.data);
+                        this._logger.push({ oldConf: this._appConfig, newConf: dup }).log('Emitting new configuration');
+                        this.emit(EVENT.RECONFIGURE, dup);
+                        break;
+                    }
+                    default:
+                        this.send(build.ERROR.NOTIFY.UNSUPPORTED_VERB(msg.id));
+                        break;
+                }
+                break;
+            default:
+                this.send(build.ERROR.NOTIFY.UNSUPPORTED_MESSAGE(msg.id));
+                break;
+        }
+
+    }
+}
+
+
+
+module.exports = {
+    Client,
+    build,
+    MESSAGE,
+    VERB,
+    ERROR,
+    EVENT,
+};