@mojaloop/sdk-scheme-adapter 11.18.8

package/InboundServer/index.js

@@ -0,0 +1,205 @@
+/**************************************************************************
+ *  (C) Copyright ModusBox Inc. 2019 - All rights reserved.               *
+ *                                                                        *
+ *  This file is made available under the terms of the license agreement  *
+ *  specified in the corresponding source code repository.                *
+ *                                                                        *
+ *  ORIGINAL AUTHOR:                                                      *
+ *       James Bush - james.bush@modusbox.com                             *
+ **************************************************************************/
+
+const Koa = require('koa');
+
+const assert = require('assert').strict;
+const https = require('https');
+const http = require('http');
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+const EventEmitter = require('events');
+
+const { WSO2Auth } = require('@mojaloop/sdk-standard-components');
+
+const Validate = require('../lib/validate');
+const router = require('../lib/router');
+const handlers = require('./handlers');
+const middlewares = require('./middlewares');
+
+class InboundApi extends EventEmitter {
+    constructor(conf, logger, cache, validator) {
+        super({ captureExceptions: true });
+        this._conf = conf;
+        this._cache = cache;
+        this._wso2 = {
+            auth: new WSO2Auth({
+                ...conf.wso2.auth,
+                logger,
+                tlsCreds: conf.mutualTLS.outboundRequests.enabled && conf.mutualTLS.outboundRequests.creds,
+            }),
+            retryWso2AuthFailureTimes: conf.wso2.requestAuthFailureRetryTimes,
+        };
+        this._wso2.auth.on('error', (msg) => {
+            this.emit('error', 'WSO2 auth error in InboundApi', msg);
+        });
+
+        if (conf.validateInboundJws) {
+            this._jwsVerificationKeys = InboundApi._GetJwsKeys(conf.jwsVerificationKeysDirectory);
+        }
+        this._api = InboundApi._SetupApi({
+            conf,
+            logger,
+            validator,
+            cache,
+            jwsVerificationKeys: this._jwsVerificationKeys,
+            wso2: this._wso2,
+        });
+    }
+
+    async start() {
+        this._startJwsWatcher();
+        if (!this._conf.testingDisableWSO2AuthStart) {
+            await this._wso2.auth.start();
+        }
+    }
+
+    stop() {
+        this._wso2.auth.stop();
+        if (this._keyWatcher) {
+            this._keyWatcher.close();
+            this._keyWatcher = null;
+        }
+    }
+
+    callback() {
+        return this._api.callback();
+    }
+
+    _startJwsWatcher() {
+        const FS_EVENT_TYPES = {
+            CHANGE: 'change',
+            RENAME: 'rename'
+        };
+        const watchHandler = async (eventType, filename) => {
+            // On most platforms, 'rename' is emitted whenever a filename appears or disappears in the directory.
+            // From: https://nodejs.org/docs/latest/api/fs.html#fs_fs_watch_filename_options_listener
+            if (path.extname(filename) !== '.pem') {
+                return;
+            }
+            const keyName = path.basename(filename, '.pem');
+            const keyPath = path.join(this._conf.jwsVerificationKeysDirectory, filename);
+            if (eventType === FS_EVENT_TYPES.RENAME) {
+                if (fs.existsSync(keyPath)) {
+                    this._jwsVerificationKeys[keyName] = await fs.promises.readFile(keyPath);
+                } else {
+                    delete this._jwsVerificationKeys[keyName];
+                }
+            } else if (eventType === FS_EVENT_TYPES.CHANGE) {
+                this._jwsVerificationKeys[keyName] = await fs.promises.readFile(keyPath);
+            }
+        };
+        if (this._conf.jwsVerificationKeysDirectory) {
+            this._keyWatcher = fs.watch(this._conf.jwsVerificationKeysDirectory, watchHandler);
+        }
+    }
+
+    static _SetupApi({ conf, logger, validator, cache, jwsVerificationKeys, wso2 }) {
+        const api = new Koa();
+
+        api.use(middlewares.createErrorHandler(logger));
+        api.use(middlewares.createRequestIdGenerator());
+        api.use(middlewares.createHeaderValidator(logger));
+        if (conf.validateInboundJws) {
+            const jwsExclusions = conf.validateInboundPutPartiesJws ? [] : ['putParties'];
+            api.use(middlewares.createJwsValidator(logger, jwsVerificationKeys, jwsExclusions));
+        }
+
+        api.use(middlewares.applyState({ cache, wso2, conf }));
+        api.use(middlewares.createLogger(logger));
+        api.use(middlewares.createRequestValidator(validator));
+        api.use(middlewares.assignFspiopIdentifier());
+        if (conf.enableTestFeatures) {
+            api.use(middlewares.cacheRequest(cache));
+        }
+        api.use(router(handlers));
+        api.use(middlewares.createResponseBodyHandler());
+
+        api.context.resourceVersions = conf.resourceVersions;
+
+        return api;
+    }
+
+    static _GetJwsKeys(fromDir) {
+        const keys = {};
+        if (fromDir) {
+            fs.readdirSync(fromDir)
+                .filter(f => f.endsWith('.pem'))
+                .forEach(f => {
+                    const keyName = path.basename(f, '.pem');
+                    const keyPath = path.join(fromDir, f);
+                    keys[keyName] = fs.readFileSync(keyPath);
+                });
+        }
+        return keys;
+    }
+}
+
+class InboundServer extends EventEmitter {
+    constructor(conf, logger, cache) {
+        super({ captureExceptions: true });
+        this._conf = conf;
+        this._validator = new Validate();
+        this._logger = logger;
+        this._api = new InboundApi(
+            conf,
+            this._logger.push({ component: 'api' }),
+            cache,
+            this._validator
+        );
+        this._api.on('error', (...args) => {
+            this.emit('error', ...args);
+        });
+        this._server = this._createServer(
+            conf.mutualTLS.inboundRequests.enabled,
+            conf.mutualTLS.inboundRequests.creds,
+            this._api.callback()
+        );
+    }
+
+    async start() {
+        assert(!this._server.listening, 'Server already listening');
+        const specPath = path.join(__dirname, 'api.yaml');
+        const apiSpecs = yaml.load(fs.readFileSync(specPath));
+        await this._validator.initialise(apiSpecs);
+        await this._api.start();
+        await new Promise((resolve) => this._server.listen(this._conf.inboundServerPort, resolve));
+        this._logger.log(`Serving inbound API on port ${this._conf.inboundServerPort}`);
+    }
+
+    async stop() {
+        if (this._server) {
+            await new Promise(resolve => this._server.close(resolve));
+            this._server = null;
+        }
+        if (this._api) {
+            await this._api.stop();
+            this._api = null;
+        }
+        this._logger.log('inbound shut down complete');
+    }
+
+    _createServer(tlsEnabled, tlsCreds, handler) {
+        if (!tlsEnabled) {
+            return http.createServer(handler);
+        }
+
+        const inboundHttpsOpts = {
+            ...tlsCreds,
+            requestCert: true,
+            rejectUnauthorized: true // no effect if requestCert is not true
+        };
+        return https.createServer(inboundHttpsOpts, handler);
+    }
+
+}
+
+module.exports = InboundServer;

package/InboundServer/middlewares.js

@@ -0,0 +1,426 @@
+/**************************************************************************
+ *  (C) Copyright ModusBox Inc. 2019 - All rights reserved.               *
+ *                                                                        *
+ *  This file is made available under the terms of the license agreement  *
+ *  specified in the corresponding source code repository.                *
+ *                                                                        *
+ *  ORIGINAL AUTHOR:                                                      *
+ *       James Bush - james.bush@modusbox.com                             *
+ **************************************************************************/
+
+const coBody = require('co-body');
+
+const randomPhrase = require('../lib/randomphrase');
+const { Jws, Errors } = require('@mojaloop/sdk-standard-components');
+const {
+    parseAcceptHeader,
+    parseContentTypeHeader,
+    protocolVersionsMap
+} = require('@mojaloop/central-services-shared').Util.HeaderValidation;
+const {
+    defaultProtocolResources,
+    defaultProtocolVersions,
+    errorMessages
+} = require('@mojaloop/central-services-shared').Util.Hapi.FSPIOPHeaderValidation;
+
+/**
+ * Log raw to console as a last resort
+ * @return {Function}
+ */
+const createErrorHandler = (logger) => async (ctx, next) => {
+    try {
+        await next();
+    } catch (err) {
+        // TODO: return a 500 here if the response has not already been sent?
+        logger.push({ err }).log('Error caught in catchall');
+    }
+};
+
+
+/**
+ * tag each incoming request with the FSPIOP identifier from it's path or body
+ * @return {Function}
+ */
+const assignFspiopIdentifier = () => async (ctx, next) => {
+    const getters = {
+        '/authorizations/{ID}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+        },
+        '/bulkQuotes': {
+            post: () => ctx.request.body.bulkQuoteId,
+        },
+        '/bulkQuotes/{ID}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+        },
+        '/bulkQuotes/{ID}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/bulkTransfers': {
+            post: () => ctx.request.body.bulkTransferId,
+        },
+        '/bulkTransfers/{ID}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+        },
+        '/bulkTransfers/{ID}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/participants/{ID}': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/participants/{Type}/{ID}': {
+            get: () => ctx.state.path.params.ID,
+        },
+        '/participants/{Type}/{ID}/{SubId}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+        },
+        '/participants/{Type}/{ID}/{SubId}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/participants/{ID}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/parties/{Type}/{ID}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+        },
+        '/parties/{Type}/{ID}/{SubId}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+        },
+        '/parties/{Type}/{ID}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/parties/{Type}/{ID}/{SubId}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/quotes': {
+            post: () => ctx.request.body.quoteId,
+        },
+        '/quotes/{ID}': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/quotes/{ID}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/transfers': {
+            post: () => ctx.request.body.transferId,
+        },
+        '/transfers/{ID}': {
+            get: () => ctx.state.path.params.ID,
+            put: () => ctx.state.path.params.ID,
+            patch: () => ctx.state.path.params.ID,
+        },
+        '/transfers/{ID}/error': {
+            put: () => ctx.state.path.params.ID,
+        },
+        '/transactionRequests': {
+            post: () => ctx.request.body.transactionRequestId,
+        },
+        '/transactionRequests/{ID}': {
+            put: () => ctx.state.path.params.ID,
+        }
+    }[ctx.state.path.pattern];
+    if (getters) {
+        const getter = getters[ctx.method.toLowerCase()];
+        if (getter) {
+            ctx.state.fspiopId = getter(ctx.request);
+        }
+    }
+    await next();
+};
+
+
+/**
+ * cache incoming requests and callbacks
+ * @return {Function}
+ */
+const cacheRequest = (cache) => async (ctx, next) => {
+    if (ctx.state.fspiopId) {
+        const req = {
+            headers: ctx.request.headers,
+            data: ctx.request.body,
+        };
+        const prefix = ctx.method.toLowerCase() === 'put' ? cache.CALLBACK_PREFIX : cache.REQUEST_PREFIX;
+        const res = await cache.set(`${prefix}${ctx.state.fspiopId}`, req);
+        ctx.state.logger.push({ res }).log('Caching request');
+    }
+    await next();
+};
+
+
+/**
+ * tag each incoming request with a unique identifier
+ * @return {Function}
+ */
+const createRequestIdGenerator = () => async (ctx, next) => {
+    ctx.request.id = randomPhrase();
+    await next();
+};
+
+
+/**
+ * Deal with mojaloop API content type headers, treat as JSON
+ * This is based on the Hapi header validation plugin found in `central-services-shared`
+ * Since `sdk-scheme-adapter` uses Koa instead of Hapi we convert the plugin
+ * into middleware
+ * @param logger
+ * @return {Function}
+ */
+//
+const createHeaderValidator = (logger) => async (
+    ctx,
+    next,
+    resources = defaultProtocolResources,
+    supportedProtocolVersions = defaultProtocolVersions
+) => {
+    const request = ctx.request;
+
+    // First, extract the resource type from the path
+    const resource = request.path.replace(/^\//, '').split('/')[0];
+
+    // Only validate requests for the requested resources
+    if (!resources.includes(resource)) {
+        return await next();
+    }
+
+    // Always validate the accept header for a get request, or optionally if it has been
+    // supplied
+    if (request.method.toLowerCase() === 'get' || request.headers.accept) {
+        if (request.headers.accept === undefined) {
+            ctx.response.status = Errors.MojaloopApiErrorCodes.MISSING_ELEMENT.httpStatusCode;
+            ctx.response.body = new Errors.MojaloopFSPIOPError(
+                Errors.MojaloopApiErrorObjectFromCode(Errors.MojaloopApiErrorCodes.MISSING_ELEMENT.httpStatusCode),
+                errorMessages.REQUIRE_ACCEPT_HEADER,
+                null,
+                Errors.MojaloopApiErrorCodes.MISSING_ELEMENT
+            ).toApiErrorObject();
+            return;
+        }
+        const accept = parseAcceptHeader(resource, request.headers.accept);
+        if (!accept.valid) {
+            ctx.response.status = Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX.httpStatusCode;
+            ctx.response.body = new Errors.MojaloopFSPIOPError(
+                Errors.MojaloopApiErrorObjectFromCode(Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX.httpStatusCode),
+                errorMessages.INVALID_ACCEPT_HEADER,
+                null,
+                Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX
+            ).toApiErrorObject();
+            return;
+        }
+        if (!supportedProtocolVersions.some(supportedVer => accept.versions.has(supportedVer))) {
+            ctx.response.status = Errors.MojaloopApiErrorCodes.UNACCEPTABLE_VERSION.httpStatusCode;
+            ctx.response.body = new Errors.MojaloopFSPIOPError(
+                Errors.MojaloopApiErrorObjectFromCode(Errors.MojaloopApiErrorCodes.UNACCEPTABLE_VERSION.httpStatusCode),
+                errorMessages.REQUESTED_VERSION_NOT_SUPPORTED,
+                null,
+                Errors.MojaloopApiErrorCodes.UNACCEPTABLE_VERSION,
+                protocolVersionsMap
+            ).toApiErrorObject();
+            return;
+        }
+    }
+
+    // Always validate the content-type header
+    if (request.headers['content-type'] === undefined) {
+        ctx.response.status = Errors.MojaloopApiErrorCodes.MISSING_ELEMENT.httpStatusCode;
+        ctx.response.body = new Errors.MojaloopFSPIOPError(
+            Errors.MojaloopApiErrorObjectFromCode(Errors.MojaloopApiErrorCodes.MISSING_ELEMENT.httpStatusCode),
+            errorMessages.REQUIRE_CONTENT_TYPE_HEADER,
+            null,
+            Errors.MojaloopApiErrorCodes.MISSING_ELEMENT,
+            protocolVersionsMap
+        ).toApiErrorObject();
+        return;
+    }
+
+    const contentType = parseContentTypeHeader(resource, request.headers['content-type']);
+    if (!contentType.valid) {
+        ctx.response.status = Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX.httpStatusCode;
+        ctx.response.body = new Errors.MojaloopFSPIOPError(
+            Errors.MojaloopApiErrorObjectFromCode(Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX.httpStatusCode),
+            errorMessages.INVALID_CONTENT_TYPE_HEADER,
+            null,
+            Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX
+        ).toApiErrorObject();
+        return;
+    }
+    if (!supportedProtocolVersions.includes(contentType.version)) {
+        ctx.response.status = Errors.MojaloopApiErrorCodes.UNACCEPTABLE_VERSION.httpStatusCode;
+        ctx.response.body = new Errors.MojaloopFSPIOPError(
+            Errors.MojaloopApiErrorObjectFromCode(Errors.MojaloopApiErrorCodes.UNACCEPTABLE_VERSION.httpStatusCode),
+            errorMessages.SUPPLIED_VERSION_NOT_SUPPORTED,
+            null,
+            Errors.MojaloopApiErrorCodes.UNACCEPTABLE_VERSION,
+            protocolVersionsMap
+        ).toApiErrorObject();
+        return;
+    }
+
+    try {
+        ctx.request.body = await coBody.json(ctx.req);
+    }
+    catch(err) {
+        // error parsing body
+        logger.push({ err }).log('Error parsing body');
+        ctx.response.status = Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX.httpStatusCode;
+        ctx.response.body = new Errors.MojaloopFSPIOPError(err, err.message, null,
+            Errors.MojaloopApiErrorCodes.MALFORMED_SYNTAX).toApiErrorObject();
+        return;
+    }
+    await next();
+};
+
+
+/**
+ *
+ * @param logger
+ * @param keys {Object}  JWS verification keys
+ * @param exclusions {string[]} Requests to exclude from validation. Possible values: "putParties"
+ * @return {Function}
+ */
+const createJwsValidator = (logger, keys, exclusions) => {
+    const jwsValidator = new Jws.validator({
+        logger: logger,
+        validationKeys: keys,
+    });
+    // JWS validation for incoming requests
+    return async (ctx, next) => {
+        try {
+            // we skip inbound JWS validation on PUT /parties requests if our config flag
+            // is set to do so.
+            if (exclusions.includes('putParties')
+                    && ctx.request.method === 'PUT'
+                    && ctx.request.path.startsWith('/parties/')) {
+                logger.log('Skipping jws validation on put parties. config flag is set');
+                return await next();
+            }
+
+            // we dont check signatures on GET requests
+            // todo: validate this requirement. No state is mutated by GETs but
+            // there are potential security issues if message origin is used to
+            // determine permission sets i.e. what is "readable"
+            if(ctx.request.method !== 'GET') {
+                logger.push({ request: ctx.request, body: ctx.request.body }).log('Validating JWS');
+                jwsValidator.validate(ctx.request, logger);
+            }
+
+        }
+        catch(err) {
+            logger.push({ err }).log('Inbound request failed JWS validation');
+
+            ctx.response.status = 400;
+            ctx.response.body = new Errors.MojaloopFSPIOPError(
+                err, err.message, null, Errors.MojaloopApiErrorCodes.INVALID_SIGNATURE
+            ).toApiErrorObject();
+            return;
+        }
+        await next();
+    };
+};
+
+
+/**
+ * Add request state.
+ * TODO: this should probably be app context:
+ * https://github.com/koajs/koa/blob/master/docs/api/index.md#appcontext
+ * @param sharedState
+ * @return {Function}
+ */
+const applyState = (sharedState) => async (ctx, next) => {
+    Object.assign(ctx.state, {
+        ...sharedState,
+        conf: {
+            ...sharedState.conf,
+            tls: sharedState?.conf?.mutualTLS?.outboundRequests,
+        }
+    });
+    await next();
+};
+
+
+/**
+ * Add a log context for each request, log the receipt and handling thereof
+ * @param logger
+ * @return {Function}
+ */
+const createLogger = (logger) => async (ctx, next) => {
+    ctx.state.logger = logger.push({ request: {
+        id: ctx.request.id,
+        path: ctx.path,
+        method: ctx.method
+    }});
+    ctx.state.logger.push({ body: ctx.request.body }).log('Request received');
+    try {
+        await next();
+    } catch (err) {
+        ctx.state.logger.push(err).log('Error');
+    }
+    await ctx.state.logger.log('Request processed');
+};
+
+
+/**
+ * Add validation for each inbound request
+ * @param validator
+ * @return {Function}
+ */
+const createRequestValidator = (validator) => async (ctx, next) => {
+    ctx.state.logger.log('Validating request');
+    try {
+        ctx.state.path = validator.validateRequest(ctx, ctx.state.logger);
+        ctx.state.logger.log('Request passed validation');
+        await next();
+    } catch (err) {
+        ctx.state.logger.push({ err }).log('Request failed validation.');
+        // send a mojaloop spec error response
+        ctx.response.status = err.httpStatusCode || 400;
+
+        if(err instanceof Errors.MojaloopFSPIOPError) {
+            // this is a specific mojaloop spec error
+            ctx.response.body = err.toApiErrorObject();
+            return;
+        }
+
+        // generic mojaloop spec validation error
+        ctx.response.body = {
+            errorInformation: {
+                errorCode: '3100',
+                errorDescription: `${err.dataPath ? err.dataPath + ' ' : ''}${err.message}`
+            }
+        };
+    }
+};
+
+
+/**
+ * Override Koa's default behaviour of returning the status code as text in the body. If we
+ * haven't defined the body, we want it empty. Note that if setting this to null, Koa appears
+ * to override the status code with a 204. This is correct behaviour in the sense that the
+ * status code correctly corresponds to the content (none) but unfortunately the Mojaloop API
+ * does not respect this convention and requires a 200.
+ * @return {Function}
+ */
+const createResponseBodyHandler = () => async (ctx, next) => {
+    if (ctx.response.body === undefined) {
+        ctx.response.body = '';
+    }
+    return await next();
+};
+
+
+module.exports = {
+    applyState,
+    assignFspiopIdentifier,
+    cacheRequest,
+    createErrorHandler,
+    createRequestIdGenerator,
+    createHeaderValidator,
+    createJwsValidator,
+    createLogger,
+    createRequestValidator,
+    createResponseBodyHandler,
+};