@mimik/api-helper 0.0.1

package/.eslintrc

@@ -0,0 +1,43 @@
+{
+  "plugins": [
+    "@mimik/document-env",
+    "@mimik/dependencies"
+  ],
+  "env": {
+    "node": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2020
+  },
+  "extends": "airbnb",
+  "rules": {
+    "import/no-extraneous-dependencies": ["error", { "devDependencies": true }],
+    "import/no-unresolved": ["error", { "amd": true, "commonjs": true, "caseSensitiveStrict": true }],
+    "brace-style": [1, "stroustrup", { "allowSingleLine": true }],
+    "no-confusing-arrow": [0], // arrow isnt confusing
+    "max-len": [1, 180, { "ignoreComments": true }],
+    "linebreak-style": 0,
+    "quotes": [1, "single"],
+    "semi": [1, "always"],
+    "no-process-env": ["error"],
+    "@mimik/document-env/validate-document-env": 2,
+    "@mimik/dependencies/case-sensitive": 2,
+    "@mimik/dependencies/no-cycles": 2,
+    "@mimik/dependencies/require-json-ext": 2
+  },
+  "settings":{
+    "react": {
+      "version": "detect"
+    }
+  },
+  "globals": {
+    "module": true,
+    "require": true,
+    "const": false,
+    "it": false,
+    "describe": false,
+    "before": true,
+    "after": true,
+    "JSON": true
+  }
+}

package/.nycrc

@@ -0,0 +1,4 @@
+{
+  "exclude": ["gulpfile.js"],
+  "reporter": ["lcov", "text"]
+}

package/README.md

@@ -0,0 +1,130 @@
+## Functions
+
+<dl>
+<dt><a href="#apiSetup">apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId)</a> ⇒ <code>Promise</code></dt>
+<dd><p>Setup the API to be use for a service</p>
+</dd>
+<dt><a href="#getAPIFile">getAPIFile(apiFilename, correlationId, options)</a> ⇒ <code>Promise</code></dt>
+<dd><p>Gets the API file from swaggerhub and store it in the give PATH location.</p>
+</dd>
+<dt><a href="#setupServerFiles">setupServerFiles(apiFilename, controllersDirectory, buidDirectory, correlationId, options)</a> ⇒ <code>Promise</code></dt>
+<dd><p>Setup and validates files for the server</p>
+</dd>
+<dt><a href="#validateSecuritySchemes">validateSecuritySchemes(apiDefinition, correlationId)</a> ⇒</dt>
+<dd><p>Validates the known SecuritySchemes: <code>SystemSecurity</code>, <code>AdminSecurity</code>, <code>UserSecurity</code>, <code>PeerSecurity</code>.</p>
+</dd>
+<dt><a href="#extractProperties">extractProperties(apiDefinition, controllersDirectory, buidDirectory, correlationId)</a> ⇒</dt>
+<dd><p>Extracts the properties from API definiton and creates a file binding the handler with the controller operations.</p>
+</dd>
+</dl>
+
+<a name="apiSetup"></a>
+
+## apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) ⇒ <code>Promise</code>
+Setup the API to be use for a service
+
+**Kind**: global function  
+**Returns**: <code>Promise</code> - .
+&fulfil {object} The API file itself.  
+**Category**: async  
+**Throws**:
+
+- <code>Promise</code> An error is thrown if the initiatilization failed.
+
+By default System and Admin security are automatically registered
+
+**Requires**: <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/swagger-helper</code>, <code>module:ajv-formats</code>, <code>module:fs</code>, <code>module:jsonwebtoken</code>, <code>module:lodash</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| setup | <code>object</code> | Object containing the apiFilename and the exisiting securitySchemes in the API definition. |
+| registeredOperations | <code>object</code> | List of the operation to register for the API. |
+| securityHandlers | <code>object</code> | List of the securityHandlers to add for the service. |
+| extraFormats | <code>object</code> | list of the formats to add for validatng properties. |
+| config | <code>object</code> | Configuration of the service. |
+| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+
+<a name="getAPIFile"></a>
+
+## getAPIFile(apiFilename, correlationId, options) ⇒ <code>Promise</code>
+Gets the API file from swaggerhub and store it in the give PATH location.
+
+**Kind**: global function  
+**Returns**: <code>Promise</code> - .
+&fulfil {object} The API file itself.  
+**Category**: async  
+**Throws**:
+
+- <code>Promise</code> An error is  thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file connot be saved.
+
+**Requires**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| apiFilename | <code>PATH.&lt;string&gt;</code> | Name of the file where the API file will be stored. |
+| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API. |
+
+<a name="setupServerFiles"></a>
+
+## setupServerFiles(apiFilename, controllersDirectory, buidDirectory, correlationId, options) ⇒ <code>Promise</code>
+Setup and validates files for the server
+
+**Kind**: global function  
+**Returns**: <code>Promise</code> - .
+&fulfil {object} The API file, the API filename, and the existing know security schemes.  
+**Category**: async  
+**Throws**:
+
+- <code>Promise</code> An error is thrown for many reasons assocated with getAPIFile or validateSecuritySchemes or extractProperties.
+
+**Requires**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| apiFilename | <code>PATH.&lt;string&gt;</code> | Name of the file where the API file will be stored. |
+| controllersDirectory | <code>PATH.&lt;string&gt;</code> | Directory to find the controller files. |
+| buidDirectory | <code>PATH.&lt;string&gt;</code> | = Directory where the register file will be stored. |
+| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API. |
+
+<a name="validateSecuritySchemes"></a>
+
+## validateSecuritySchemes(apiDefinition, correlationId) ⇒
+Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`.
+
+**Kind**: global function  
+**Returns**: An array of the know securitySchemes that are in the API definition.  
+**Category**: sync  
+**Throws**:
+
+- An error is thrown for the first validation fails.
+
+**Requires**: <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/response-helper</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| apiDefinition | <code>object</code> | JSON object containing the API definition. |
+| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+
+<a name="extractProperties"></a>
+
+## extractProperties(apiDefinition, controllersDirectory, buidDirectory, correlationId) ⇒
+Extracts the properties from API definiton and creates a file binding the handler with the controller operations.
+
+**Kind**: global function  
+**Returns**: null  
+**Category**: sync  
+**Throws**:
+
+- An error is thrown for many reasons, like operationId does not exist in controllers, controller dies not exist...
+
+**Requires**: <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| apiDefinition | <code>object</code> | JSON object containing the API definition. |
+| controllersDirectory | <code>PATH.&lt;string&gt;</code> | Directory to find the controller files. |
+| buidDirectory | <code>PATH.&lt;string&gt;</code> | = Directory where the register file will be stored. |
+| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+

package/index.js

@@ -0,0 +1,347 @@
+const { OpenAPIBackend } = require('openapi-backend');
+const fs = require('fs');
+const pathLib = require('path');
+const yaml = require('js-yaml');
+const _ = require('lodash');
+
+const logger = require('@mimik/sumologic-winston-logger');
+const { getRichError } = require('@mimik/response-helper');
+const { rpRetry } = require('@mimik/request-retry');
+
+const { saveProperties } = require('./lib/extract-helper');
+const { validateOauth2, validateApiKey } = require('./lib/oauthValidation-helper');
+const { ajvFormats } = require('./lib/ajvHelpers');
+const securityLib = require('./lib/securityHandlers');
+const baseHandlers = require('./lib/baseHandlers');
+const {
+  LOCAL,
+  SET_ON,
+  SECURITY_ON,
+  SECURITY_OFF,
+  X_ROUTER_CONTROLLER,
+  EXTENSION,
+  ADMIN_SECURITY,
+  SYSTEM_SECURITY,
+  PEER_SECURITY,
+  USER_SECURITY,
+  API_KEY_SECURITY,
+  CLIENT_CREDENTIALS,
+  IMPLICIT,
+  POSTFIX,
+  API_PROVIDER,
+  RESOLVED,
+} = require('./lib/common');
+
+/**
+ *
+ * Setup the API to be use for a service
+ *
+ * @function apiSetup
+ * @category async
+ * @requires @mimik/response-helper
+ * @requires @mimik/sumologic-winston-logger
+ * @requires @mimik/swagger-helper
+ * @requires ajv-formats
+ * @requires fs
+ * @requires jsonwebtoken
+ * @requires lodash
+ * @param {object} setup -  Object containing the apiFilename and the exisiting securitySchemes in the API definition.
+ * @param {object} registeredOperations - List of the operation to register for the API.
+ * @param {object} securityHandlers - List of the securityHandlers to add for the service.
+ * @param {object} extraFormats - list of the formats to add for validatng properties.
+ * @param {object} config - Configuration of the service.
+ * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
+ * @return {Promise}.
+ * &fulfil {object} The API file itself.
+ * @throws {Promise} An error is thrown if the initiatilization failed.
+ *
+ * By default System and Admin security are automatically registered
+ */
+const apiSetup = (setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) => {
+  const { apiFilename, existingSecuritySchemes } = setup;
+  const { SystemSecurity, AdminSecurity } = securityLib(config);
+  const api = new OpenAPIBackend({
+    definition: apiFilename,
+    apiRoot: config.serverSettings.basePath,
+    strict: true,
+    validate: true,
+    ajvOpts: {
+      allErrors: true,
+      verbose: true,
+    },
+    customizeAjv: ajvFormats(extraFormats),
+    handlers: baseHandlers,
+  });
+  let mode;
+
+  api.register(registeredOperations);
+  if (config && (config.nodeEnvironment.toLowerCase() !== LOCAL || config.serverSettings.securitySet === SET_ON)) {
+    mode = SECURITY_ON;
+  }
+  else {
+    logger.warn('security disabled: tokens will not be used and /me and /onbehalf will not work', correlationId);
+    mode = SECURITY_OFF;
+  }
+  api.registerSecurityHandler(SYSTEM_SECURITY, SystemSecurity[mode]);
+  api.registerSecurityHandler(ADMIN_SECURITY, AdminSecurity[mode]);
+  // api.registerSecurityHandler('ApiKeySecurity', ApiKeySecurity[mode]);
+  if (securityHandlers) {
+    const securityHandlerNames = Object.keys(securityHandlers);
+
+    existingSecuritySchemes.forEach((securityScheme) => {
+      if (!securityHandlerNames.includes(securityScheme)) throw getRichError('System', 'missing handler for security Scheme', { securityScheme });
+    });
+    Object.keys(securityHandlers).forEach((securityHandlerName) => {
+      api.registerSecurityHandler(securityHandlerName, securityHandlers[securityHandlerName][mode]);
+    });
+  }
+  else if (existingSecuritySchemes.length !== 0) throw getRichError('System', 'missing handlers for security Scheme', { existingSecuritySchemes });
+  api.init()
+    .catch((err) => {
+      throw getRichError('System', 'could not initialize the api', { api }, err);
+    });
+  return api;
+};
+
+/**
+ *
+ * Gets the API file from swaggerhub and store it in the give PATH location.
+ *
+ * @function getAPIFile
+ * @category async
+ * @requires @mimik/request-retry
+ * @requires @mimik/response-helper
+ * @requires @mimik/sumologic-winston-logger
+ * @requires fs
+ * @requires js-yaml
+ * @requires path
+ * @param {PATH.<string>} apiFilename -  Name of the file where the API file will be stored.
+ * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
+ * @param {object} options - Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API.
+ * @return {Promise}.
+ * &fulfil {object} The API file itself.
+ * @throws {Promise} An error is  thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file connot be saved.
+ */
+const getAPIFile = (apiFilename, correlationId, options) => {
+  logger.info('Getting API definition', correlationId);
+  try {
+    if (fs.existsSync(apiFilename)) {
+      logger.debug('API file already exists', { apiFilename }, correlationId);
+      let apiDefinition = fs.readFileSync(apiFilename, 'utf8');
+
+      try { apiDefinition = JSON.parse(apiDefinition); }
+      catch (errJSON) {
+        try { apiDefinition = yaml.load(apiDefinition); }
+        catch (errYaml) {
+          return Promise.reject(getRichError('System', 'wrong file format', { apiFilename }, errYaml));
+        }
+      }
+      return Promise.resolve(apiDefinition);
+    }
+  }
+  catch (err) {
+    return Promise.reject(getRichError('System', 'file system error', { apiFilename }, err));
+  }
+  let fileName;
+  let apiDirectory;
+
+  try { fileName = pathLib.basename(apiFilename); }
+  catch (err) { return Promise.reject(getRichError('System', 'file name error', { apiFilename }, err)); }
+  try { apiDirectory = pathLib.dirname(apiFilename); }
+  catch (err) { return Promise.reject(getRichError('System', 'directory name error', { apiFilename }, err)); }
+  const params = fileName.split('_');
+
+  if (params.length !== 4 || params[3] !== POSTFIX) {
+    return Promise.reject(getRichError('System', 'wrong api name', { apiFilename }));
+  }
+  try {
+    if (!fs.existsSync(apiDirectory)) {
+      logger.debug('Creating directory', { apiDirectory }, correlationId);
+      fs.mkdirSync(apiDirectory);
+    }
+  }
+  catch (err) {
+    return Promise.reject(getRichError('System', 'file system error', { apiDirectory }, err));
+  }
+  const url = `${API_PROVIDER}/${params[0]}/${params[1]}/${params[2]}?${RESOLVED}`;
+
+  logger.debug('API file does not exist, retrieving it', { url }, correlationId);
+  const opts = {
+    method: 'GET',
+    url,
+    headers: {
+      'x-correlation-id': correlationId,
+    },
+  };
+  if (options) {
+    if (options.apiKey) opts.headers = { Authorization: options.apiKey };
+    if (options.metrics) {
+      opts.metrics = options.metrics;
+      opts.metrics.url = url;
+    }
+  }
+  return rpRetry(opts)
+    .catch((err) => {
+      const error = err;
+
+      error.message = `${error.message} - { "apiFilename":"${apiFilename}"}`;
+      throw error;
+    })
+    .then((result) => {
+      try {
+        fs.writeFileSync(apiFilename, JSON.stringify(result, null, 2));
+      }
+      catch (err) {
+        throw getRichError('System', `file system error: ${err.message}`, { apiFilename }, err);
+      }
+      return result;
+    });
+};
+
+/**
+ *
+ * Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`.
+ *
+ * @function validateSecuritySchemes
+ * @category sync
+ * @requires @mimik/sumologic-winston-logger
+ * @requires @mimik/response-helper
+ * @param {object} apiDefinition - JSON object containing the API definition.
+ * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
+ * @return An array of the know securitySchemes that are in the API definition.
+ * @throws An error is thrown for the first validation fails.
+ */
+const validateSecuritySchemes = (apiDefinition, correlationId) => {
+  const existingSecuritySchemes = [];
+
+  if (apiDefinition.components?.securitySchemes) {
+    logger.info('validating known security schemes', correlationId);
+    const { securitySchemes } = apiDefinition.components;
+
+    validateOauth2(securitySchemes, ADMIN_SECURITY, CLIENT_CREDENTIALS);
+    validateOauth2(securitySchemes, SYSTEM_SECURITY, CLIENT_CREDENTIALS);
+    existingSecuritySchemes.push(validateOauth2(securitySchemes, PEER_SECURITY, CLIENT_CREDENTIALS));
+    existingSecuritySchemes.push(validateOauth2(securitySchemes, USER_SECURITY, IMPLICIT));
+    existingSecuritySchemes.push(validateApiKey(securitySchemes, API_KEY_SECURITY));
+  }
+  return existingSecuritySchemes;
+};
+
+/**
+ *
+ * Extracts the properties from API definiton and creates a file binding the handler with the controller operations.
+ *
+ * @function extractProperties
+ * @category sync
+ * @requires @mimik/response-helper
+ * @requires @mimik/sumologic-winston-logger
+ * @requires fs
+ * @param {object} apiDefinition - JSON object containing the API definition.
+ * @param {PATH.<string>} controllersDirectory - Directory to find the controller files.
+ * @param {PATH.<string>} buidDirectory = Directory where the register file will be stored.
+ * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
+ * @return null
+ * @throws An error is thrown for many reasons, like operationId does not exist in controllers, controller dies not exist...
+ */
+const extractProperties = (apiDefinition, controllersDirectory, buildDirectory, correlationId) => {
+  const result = {};
+  const { paths } = apiDefinition;
+  let controllersDirectoryName;
+
+  try { controllersDirectoryName = pathLib.basename(controllersDirectory); }
+  catch (err) {
+    throw getRichError('System', 'directory name error', { controllersDirectory }, err);
+  }
+  logger.info('creating handler link file', correlationId);
+  try {
+    if (!fs.existsSync(controllersDirectory)) {
+      throw getRichError('System', 'missing directory', { controllersDirectory });
+    }
+  }
+  catch (err) {
+    throw getRichError('System', 'file system error', { controllersDirectory }, err);
+  }
+  if (paths) {
+    const routes = Object.keys(paths);
+
+    routes.forEach((route) => {
+      const path = paths[route];
+      const verbs = Object.keys(path);
+
+      verbs.forEach((verb) => {
+        const operation = path[verb];
+
+        if (operation.operationId) {
+          if (!operation[X_ROUTER_CONTROLLER]) {
+            throw getRichError('System', 'missing property', { property: X_ROUTER_CONTROLLER });
+          }
+          else {
+            const controller = operation[X_ROUTER_CONTROLLER];
+            const controllerFilename = `${controllersDirectory}/${controller}${EXTENSION}`;
+
+            try {
+              if (!fs.existsSync(controllerFilename)) {
+                throw getRichError('System', 'missing controller file', { controllerFilename });
+              }
+            }
+            catch (err) {
+              throw getRichError('System', 'file system error', { controllerFilename }, err);
+            }
+            try {
+              const file = fs.readFileSync(controllerFilename, 'utf8');
+              if (!file.includes(`${operation.operationId},`)
+                 && !file.includes(`${operation.operationId}:`)
+                 && !file.includes(`module.exports = ${operation.operationId}`)) { // code must be linted before
+                throw getRichError('System', 'missing operationId in controller file', { controllerFilename, operationId: operation.operationId });
+              }
+            }
+            catch (err) {
+              throw getRichError('System', 'file system error', { controllerFilename, operationId: operation.operationId }, err);
+            }
+            if (!result[controller]) result[controller] = [operation.operationId];
+            else result[controller].push(operation.operationId);
+          }
+        }
+      });
+    });
+  }
+  saveProperties(result, buildDirectory, controllersDirectoryName, correlationId);
+};
+
+/**
+ *
+ * Setup and validates files for the server
+ *
+ * @function setupServerFiles
+ * @category async
+ * @requires @mimik/request-retry
+ * @requires @mimik/response-helper
+ * @requires @mimik/sumologic-winston-logger
+ * @requires fs
+ * @requires js-yaml
+ * @requires path
+ * @param {PATH.<string>} apiFilename -  Name of the file where the API file will be stored.
+ * @param {PATH.<string>} controllersDirectory - Directory to find the controller files.
+ * @param {PATH.<string>} buidDirectory = Directory where the register file will be stored.
+ * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
+ * @param {object} options - Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API.
+ * @return {Promise}.
+ * &fulfil {object} The API file, the API filename, and the existing know security schemes.
+ * @throws {Promise} An error is thrown for many reasons assocated with getAPIFile or validateSecuritySchemes or extractProperties.
+ */
+const setupServerFiles = (apiFilename, controllersDirectory, buildDirectory, correlationId, options) => getAPIFile(apiFilename, correlationId, options)
+  .then((apiDefinition) => {
+    const existingSecuritySchemes = _.compact(validateSecuritySchemes(apiDefinition, correlationId));
+
+    extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId);
+    return { apiDefinition, apiFilename, existingSecuritySchemes };
+  });
+
+module.exports = {
+  apiSetup,
+  securityLib,
+  getAPIFile,
+  validateSecuritySchemes,
+  extractProperties,
+  setupServerFiles,
+};

package/lib/ajvHelpers.js

@@ -0,0 +1,22 @@
+const addFormats = require('ajv-formats');
+
+const { DEFAULT_FORMATS } = require('./common');
+
+const ajvFormats = (origFormats) => (ajv) => {
+  const extraFormats = {};
+  const libFormats = DEFAULT_FORMATS;
+  let formats = origFormats;
+
+  if (!formats) formats = {};
+  Object.keys(formats).forEach((format) => {
+    if (!formats[format].type) libFormats.push(format);
+    else extraFormats[format] = formats[format];
+  });
+  addFormats(ajv, libFormats);
+  Object.keys(extraFormats).forEach((format) => ajv.addFormat(format, extraFormats[format]));
+  return ajv;
+};
+
+module.exports = {
+  ajvFormats,
+};

package/lib/baseHandlers.js

@@ -0,0 +1,88 @@
+const { rejectRequest } = require('@mimik/swagger-helper');
+
+const validationFail = (c, req, res) => {
+  const error = new Error('Failed schema validation');
+
+  error.statusCode = 400;
+  error.info = {
+    method: req.method,
+    path: req.url,
+    errors: c.validation.errors,
+    warnings: c.validation.warnings || [],
+  };
+  rejectRequest(error, c, res);
+};
+
+const notFound = (c, req, res) => {
+  const path = req.url;
+  const error = new Error(`path ${path} not defined in Swagger specification`);
+
+  error.statusCode = 404;
+  error.info = {
+    method: req.method,
+    path,
+  };
+  rejectRequest(error, c, res);
+};
+
+const unauthorizedHandler = (c, req, res) => {
+  let error = new Error('Unauthorized');
+
+  error.statusCode = 401;
+  const schemes = Object.keys(c.security);
+
+  delete schemes.authorized;
+  schemes.forEach((scheme) => {
+    if (c.security[scheme]?.error) error = c.security[scheme].error;
+  });
+  rejectRequest(error, c, res);
+};
+
+const notImplemented = (c, req, res) => {
+  const { method } = req;
+  const path = req.url;
+  const error = new Error(`${req.method} ${path} defined in Swagger specification, but no implemented`);
+
+  error.statusCode = 505;
+  error.info = {
+    method,
+    path,
+    operationId: c.operation.operationId,
+  };
+  rejectRequest(error, c, res);
+};
+
+const methodNotAllowed = (c, req, res) => {
+  const { method } = req;
+  const path = req.url;
+  const error = new Error(`path ${path} defined in Swagger specification, but the method ${method} is not defined`);
+
+  error.statusCode = 405;
+  error.info = {
+    method,
+    path,
+  };
+  rejectRequest(error, c, res);
+};
+
+/*
+const postResponseHandler = (c, req, res) => {
+  const valid = c.api.validateResponse(c.response, c.operation);
+  console.log('----->', c.response);
+  console.log('----->', valid);
+  if (valid.errors) {
+    // response validation failed
+    return res.status(502).json({ status: 502, err: valid.errors });
+  }
+  return res.status(200).json(c.response);
+};
+*/
+
+module.exports = {
+  validationFail,
+  notFound,
+  unauthorizedHandler,
+  notImplemented,
+  methodNotAllowed,
+  // postResponseHandler,
+};

package/lib/common.js

@@ -0,0 +1,80 @@
+const X_ROUTER_CONTROLLER = 'x-swagger-router-controller';
+const EXTENSION = '.js';
+const REGISTER = 'register';
+
+const OAUTH2 = 'oauth2';
+const API_KEY_IN = 'header';
+const API_KEY_NAME = 'apiKey';
+
+const ADMIN_SECURITY = 'AdminSecurity';
+const SYSTEM_SECURITY = 'SystemSecurity';
+const PEER_SECURITY = 'PeerSecurity';
+const USER_SECURITY = 'UserSecurity';
+const API_KEY_SECURITY = 'ApiKeySecurity';
+
+const CLIENT_CREDENTIALS = 'clientCredentials';
+const IMPLICIT = 'implicit';
+
+const POSTFIX = 'swagger.json';
+const API_PROVIDER = 'https://api.swaggerhub.com/apis';
+const RESOLVED = 'resolved=true';
+
+const LOCAL = 'local';
+const SET_ON = 'on';
+const SECURITY_ON = 'regular';
+const SECURITY_OFF = 'mock';
+
+const DEFAULT_FORMATS = ['date', 'time', 'date-time', 'byte', 'uuid', 'uri', 'email', 'ipv4', 'ipv6'];
+
+const AUTHORIZATION = 'authorization';
+const ADMIN = 'admin';
+const SUB_ADMIN = 'subAdmin';
+const CLIENT = '@clients';
+const NO_GENERIC = 'noGeneric';
+const ON_BEHALF = 'onBehalf';
+const CLAIMS_DEFINITION = 'Claims';
+const SCOPES_SEPARATOR = ' ';
+const SCOPE_CLAIMS_SEPARATOR = '::';
+const RESOURCE_SEPARATOR = ':';
+const CLAIMS_SEPARATOR = ',';
+const BEARERS = ['bearer', 'Bearer'];
+const USER = 'user';
+const CLUSTER = 'cluster';
+
+module.exports = {
+  X_ROUTER_CONTROLLER,
+  EXTENSION,
+  REGISTER,
+  OAUTH2,
+  API_KEY_IN,
+  API_KEY_NAME,
+  ADMIN_SECURITY,
+  SYSTEM_SECURITY,
+  PEER_SECURITY,
+  USER_SECURITY,
+  API_KEY_SECURITY,
+  CLIENT_CREDENTIALS,
+  IMPLICIT,
+  POSTFIX,
+  API_PROVIDER,
+  RESOLVED,
+  LOCAL,
+  SET_ON,
+  SECURITY_ON,
+  SECURITY_OFF,
+  DEFAULT_FORMATS,
+  AUTHORIZATION,
+  ADMIN,
+  SUB_ADMIN,
+  CLIENT,
+  NO_GENERIC,
+  ON_BEHALF,
+  CLAIMS_DEFINITION,
+  SCOPES_SEPARATOR,
+  SCOPE_CLAIMS_SEPARATOR,
+  RESOURCE_SEPARATOR,
+  CLAIMS_SEPARATOR,
+  BEARERS,
+  USER,
+  CLUSTER,
+};

package/lib/extract-helper.js

@@ -0,0 +1,58 @@
+const fs = require('fs');
+
+const { getRichError } = require('@mimik/response-helper');
+const logger = require('@mimik/sumologic-winston-logger');
+
+const { EXTENSION, REGISTER } = require('./common');
+
+const saveProperties = (extractResult, buildDirectory, controllersDirectoryName, correlationId) => {
+  try {
+    if (!fs.existsSync(buildDirectory)) {
+      logger.debug('creating directory', { buildDirectory }, correlationId);
+      fs.mkdirSync(buildDirectory);
+    }
+  }
+  catch (err) {
+    throw getRichError('System', 'file system error', { buildDirectory }, err);
+  }
+  const filename = `${buildDirectory}/${REGISTER}${EXTENSION}`;
+  try {
+    if (fs.existsSync(filename)) {
+      logger.debug('removing file', { filename }, correlationId);
+      fs.unlinkSync(filename);
+    }
+  }
+  catch (err) {
+    throw getRichError('System', 'file system error', { filename }, err);
+  }
+  const controllers = Object.keys(extractResult);
+  const operationIds = [];
+  let stringToSave = '';
+  let itemToSave;
+
+  controllers.forEach((controller) => {
+    itemToSave = '';
+    extractResult[controller].forEach((operationId) => {
+      itemToSave = `${itemToSave}  ${operationId},\n`;
+      operationIds.push(operationId);
+    });
+    stringToSave = `${stringToSave}const {\n${itemToSave}} = require('../${controllersDirectoryName}/${controller}');\n`;
+  });
+  stringToSave = `${stringToSave}\nmodule.exports = {\n`;
+  itemToSave = '';
+  operationIds.forEach((operationId) => {
+    itemToSave = `${itemToSave}  ${operationId},\n`;
+  });
+  stringToSave = `${stringToSave}${itemToSave}};\n`;
+  logger.info(`creating ${filename}`, { filename }, correlationId);
+  try {
+    fs.writeFileSync(filename, stringToSave);
+  }
+  catch (err) {
+    throw getRichError('System', `file system error: ${err.message}`, { filename }, err);
+  }
+};
+
+module.exports = {
+  saveProperties,
+};

package/lib/oauthValidation-helper.js

@@ -0,0 +1,40 @@
+const { getRichError } = require('@mimik/response-helper');
+
+const { OAUTH2, API_KEY_IN, API_KEY_NAME } = require('./common');
+
+const validateOauth2 = (securitySchemes, securityType, flow) => {
+  if (securitySchemes) {
+    const security = securitySchemes[securityType];
+
+    if (security) {
+      if (security.type !== OAUTH2) {
+        throw getRichError('System', `auth type is not ${OAUTH2}`, { securityType, receivedAuth: security.type, expectedAuth: OAUTH2 });
+      }
+      if (!security.flows[flow]) {
+        throw getRichError('System', 'no flow type available', { securityType, flow });
+      }
+    }
+  }
+};
+
+const validateApiKey = (securitySchemes, securityType) => {
+  if (securitySchemes) {
+    const security = securitySchemes[securityType];
+
+    if (security) {
+      if (security.in !== API_KEY_IN) {
+        throw getRichError('System', `apikey security must be in ${API_KEY_IN}`, { securityType, receivedIn: security.in, expectedIn: API_KEY_IN });
+      }
+      if (security.name !== API_KEY_NAME) {
+        throw getRichError('System', `apikey security must be named ${API_KEY_NAME}`, { securityType, receivedName: security.name, expectedName: API_KEY_NAME });
+      }
+      return securityType;
+    }
+  }
+  return null;
+};
+
+module.exports = {
+  validateOauth2,
+  validateApiKey,
+};

package/lib/securityHandlers.js

@@ -0,0 +1,345 @@
+const jwt = require('jsonwebtoken');
+const _ = require('lodash');
+
+const { TOKEN_PARAMS } = require('@mimik/swagger-helper');
+const {
+  AUTHORIZATION,
+  ADMIN,
+  SUB_ADMIN,
+  CLIENT,
+  NO_GENERIC,
+  ON_BEHALF,
+  CLAIMS_DEFINITION,
+  SCOPES_SEPARATOR,
+  SCOPE_CLAIMS_SEPARATOR,
+  RESOURCE_SEPARATOR,
+  CLAIMS_SEPARATOR,
+  BEARERS,
+  USER,
+  CLUSTER,
+  API_KEY_NAME,
+  ADMIN_SECURITY,
+  SYSTEM_SECURITY,
+  USER_SECURITY,
+} = require('./common');
+
+const getScopes = (c, securityType) => {
+  let scopes = [];
+
+  c.operation.security.forEach((security) => {
+    if (security[securityType]) scopes = scopes.concat(security[securityType]);
+  });
+  return scopes;
+};
+
+const getError = (message, statusCode) => {
+  const error = new Error(message);
+
+  error.statusCode = statusCode;
+  return error;
+};
+
+const checkToken = (authToken) => {
+  let token;
+
+  try { token = jwt.decode(authToken); }
+  catch (err) {
+    err.statusCode = 401;
+    throw err;
+  }
+  if (!token) {
+    throw getError('invalid token', 401);
+  }
+  return token;
+};
+
+const checkHeaders = (headers) => {
+  if (!headers) {
+    throw getError('missing header', 401);
+  }
+  const authNames = Object.keys(headers).filter((key) => key.toLowerCase() === AUTHORIZATION);
+  const authNamesLength = authNames.length;
+
+  if (authNamesLength === 0) {
+    throw getError(`missing ${AUTHORIZATION} header`, 401);
+  }
+  if (authNamesLength !== 1) {
+    throw getError(`duplicated ${AUTHORIZATION} header`, 401);
+  }
+  const auth = headers[authNames[0]].split(' ');
+
+  if (!BEARERS.includes(auth[0]) || auth.length !== 2) {
+    throw getError(`authorization type incorrect: ${auth[0]}`, 401);
+  }
+  return auth[1];
+};
+
+const checkScopes = (tokenScopes, defScopes, definition) => {
+  if (!tokenScopes) {
+    throw new Error('no scope in authorization token');
+  }
+  let claims = [];
+  let onBehalf = false;
+
+  if (defScopes && defScopes.length !== 0) {
+    const currentScopes = tokenScopes.split(SCOPES_SEPARATOR);
+    const intersects = [];
+    let resourceIndex = 1;
+
+    currentScopes.forEach((currentScope) => {
+      const analyzedScope = currentScope.split(SCOPE_CLAIMS_SEPARATOR);
+      const analyzedResource = analyzedScope[0].split(RESOURCE_SEPARATOR);
+
+      if (analyzedResource[0] === ON_BEHALF) {
+        onBehalf = true;
+        resourceIndex = 2; // legacy handling
+      }
+
+      if (defScopes.includes(analyzedScope[0])) {
+        if (analyzedScope[1]) {
+          const includedDefinitionName = `${analyzedResource[resourceIndex]}${CLAIMS_DEFINITION}`;
+
+          if (!definition.components || !definition.components.schemas) {
+            throw getError(`missing ${includedDefinitionName} definition: no definitions`, 500);
+          }
+          const includedDefinition = definition.components.schemas[includedDefinitionName];
+
+          if (!includedDefinition) {
+            throw getError(`missing ${includedDefinitionName} definition`, 500);
+          }
+          const includedClaims = analyzedScope[1].split(CLAIMS_SEPARATOR);
+          const definitionClaims = Object.keys(includedDefinition);
+          const claimsIntersects = _.intersection(includedClaims, definitionClaims);
+
+          if (claimsIntersects.length !== includedClaims.length) {
+            throw getError(`incorrect claims included: ${_.difference(includedClaims, claimsIntersects)}`, 403);
+          }
+          claims = claims.concat(claimsIntersects);
+        }
+        intersects.push(analyzedScope[0]);
+      }
+    });
+    if (intersects.length === 0) {
+      throw getError(`incorrect scopes: ${tokenScopes}`, 403);
+    }
+  }
+  return { onBehalf, claims };
+};
+
+module.exports = (config) => {
+  const verifyTokenClientCredentials = (authToken) => {
+    const { server, generic } = config.security;
+    const options = {
+      audience: (generic.audience === NO_GENERIC) ? server.audience : generic.audience,
+      issuer: server.issuer,
+      // subject: `${config.serverSettings.id}@clients`,
+    };
+
+    try { jwt.verify(authToken, (generic.key === NO_GENERIC) ? server.accessKey : generic.key, options); }
+    catch (err) {
+      if (generic.previousKey) { // backward compatibility
+        try { jwt.verify(authToken, generic.previousKey, options); }
+        catch (secondErr) {
+          secondErr.statusCode = 403;
+          throw secondErr;
+        }
+      }
+      else {
+        err.statusCode = 403;
+        throw err;
+      }
+    }
+  };
+
+  const verifyTokenImplicit = (authToken) => {
+    const { implicit, generic, server } = config.security;
+    const options = {
+      audience: (implicit && implicit.audience) || server.audience,
+      issuer: (implicit && implicit.issuer) || server.issuer,
+    };
+
+    try { jwt.verify(authToken, (implicit && implicit.key) || ((generic.key === NO_GENERIC) ? server.accessKey : generic.key), options); }
+    catch (err) {
+      err.statusCode = 403;
+      throw err;
+    }
+  };
+
+  const AdminSecurity = {
+    regular: (c, req) => {
+      const authToken = checkHeaders(req.headers);
+      const token = checkToken(authToken);
+      const { request } = c;
+
+      if (token.subType !== ADMIN && token.subType !== SUB_ADMIN) {
+        throw getError('invalid token: wrong type', 403);
+      }
+      if (token.subType === SUB_ADMIN) {
+        if (!token.cust) {
+          throw getError('invalid token: no customer', 403);
+        }
+      }
+      else if (token.sub !== `${config.security.admin.externalId}${CLIENT}`) {
+        throw getError(`jwt subject invalid: ${token.sub}`, 403);
+      }
+      verifyTokenClientCredentials(authToken);
+      const scopeResult = checkScopes(token.scope, getScopes(c, ADMIN_SECURITY), c.api.definition);
+
+      req[TOKEN_PARAMS.claims] = scopeResult.claims;
+      request[TOKEN_PARAMS.claims] = scopeResult.claims;
+      if (token.subType) {
+        req[TOKEN_PARAMS.tokenType] = token.subType;
+        request[TOKEN_PARAMS.tokenType] = token.subType;
+      }
+      if (token.sub) {
+        req[TOKEN_PARAMS.clientId] = token.sub;
+        request[TOKEN_PARAMS.clientId] = token.sub;
+      }
+      if (token.cust) {
+        req[TOKEN_PARAMS.customer] = token.cust;
+        request[TOKEN_PARAMS.customer] = token.cust;
+      }
+      return true;
+    },
+    mock: (c, req) => {
+      const { request } = c;
+
+      req[TOKEN_PARAMS.claims] = ['dummyClaims'];
+      req[TOKEN_PARAMS.tokenType] = ADMIN;
+      req[TOKEN_PARAMS.clientId] = 'dummyClientId';
+      req[TOKEN_PARAMS.customer] = 'dummyCustomer';
+      request[TOKEN_PARAMS.claims] = ['dummyClaims'];
+      request[TOKEN_PARAMS.tokenType] = ADMIN;
+      request[TOKEN_PARAMS.clientId] = 'dummyClientId';
+      request[TOKEN_PARAMS.customer] = 'dummyCustomer';
+      return true;
+    },
+  };
+
+  const SystemSecurity = {
+    regular: (c, req) => {
+      const authToken = checkHeaders(req.headers);
+      const token = checkToken(authToken);
+      const { request } = c;
+
+      if (token.subType === ADMIN || token.subType === SUB_ADMIN) {
+        throw getError('invalid token: wrong type', 403);
+      }
+      verifyTokenClientCredentials(authToken);
+      const scopeResult = checkScopes(token.scope, getScopes(c, SYSTEM_SECURITY), c.api.definition);
+
+      if (scopeResult.onBehalf) {
+        req[TOKEN_PARAMS.onBehalf] = true;
+        request[TOKEN_PARAMS.onBehalf] = true;
+      }
+      req[TOKEN_PARAMS.claims] = scopeResult.claims;
+      request[TOKEN_PARAMS.claims] = scopeResult.claims;
+      if (token.subType) {
+        req[TOKEN_PARAMS.tokenType] = token.subType;
+        request[TOKEN_PARAMS.tokenType] = token.subType;
+      }
+      if (token.sub) {
+        req[TOKEN_PARAMS.clientId] = token.sub;
+        request[TOKEN_PARAMS.clientId] = token.sub;
+      }
+      if (token.cust) {
+        req[TOKEN_PARAMS.customer] = token.cust;
+        request[TOKEN_PARAMS.customer] = token.cust;
+      }
+      if (token.type === CLUSTER) {
+        req[TOKEN_PARAMS.cluster] = true;
+        request[TOKEN_PARAMS.cluster] = true;
+      }
+      return true;
+    },
+    mock: (c, req) => {
+      const { request } = c;
+
+      req[TOKEN_PARAMS.claims] = ['dummyClaims'];
+      req[TOKEN_PARAMS.tokenType] = 'dummyServiceType';
+      req[TOKEN_PARAMS.clientId] = 'dummyClientId';
+      req[TOKEN_PARAMS.customer] = 'dummyCustomer';
+      request[TOKEN_PARAMS.claims] = ['dummyClaims'];
+      request[TOKEN_PARAMS.tokenType] = 'dummyServiceType';
+      request[TOKEN_PARAMS.clientId] = 'dummyClientId';
+      request[TOKEN_PARAMS.customer] = 'dummyCustomer';
+      return true;
+    },
+  };
+
+  const UserSecurity = {
+    regular: (c, req) => {
+      const authToken = checkHeaders(req.headers);
+      const token = checkToken(authToken);
+      const { request } = c;
+
+      verifyTokenImplicit(authToken);
+      const scopeResult = checkScopes(token.scope, getScopes(c, USER_SECURITY), c.api.definition);
+
+      if (scopeResult.onBehalf) {
+        req[TOKEN_PARAMS.onBehalf] = true;
+        request[TOKEN_PARAMS.onBehalf] = true;
+      }
+      req[TOKEN_PARAMS.claims] = scopeResult.claims;
+      request[TOKEN_PARAMS.claims] = scopeResult.claims;
+      req[TOKEN_PARAMS.tokenType] = USER;
+      request[TOKEN_PARAMS.tokenType] = USER;
+      if (token.sub) {
+        req[TOKEN_PARAMS.userId] = token.sub;
+        request[TOKEN_PARAMS.userId] = token.sub;
+      }
+      if (token.azp) {
+        req[TOKEN_PARAMS.appId] = token.azp;
+        request[TOKEN_PARAMS.appId] = token.azp;
+      }
+      if (token.may_act && token.may_act.sub) {
+        req[TOKEN_PARAMS.onBehalfId] = token.sub;
+        request[TOKEN_PARAMS.onBehalfId] = token.sub;
+        req[TOKEN_PARAMS.userId] = token.may_act.sub;
+        request[TOKEN_PARAMS.userId] = token.may_act.sub;
+      }
+      return true;
+    },
+    mock: (c, req) => {
+      const { request } = c;
+
+      req[TOKEN_PARAMS.claims] = ['dummyClaims'];
+      req[TOKEN_PARAMS.userId] = 'dummyUserId';
+      req[TOKEN_PARAMS.appId] = 'dummyAppId';
+      req[TOKEN_PARAMS.tokenType] = USER;
+      request[TOKEN_PARAMS.claims] = ['dummyClaims'];
+      request[TOKEN_PARAMS.userId] = 'dummyUserId';
+      request[TOKEN_PARAMS.appId] = 'dummyAppId';
+      request[TOKEN_PARAMS.tokenType] = USER;
+      return true;
+    },
+  };
+
+  const ApiKeySecurity = {
+    regular: (c, req) => {
+      const apiKey = req.headers ? req.headers[API_KEY_NAME.toLowerCase()] : null;
+      const { request } = c;
+
+      if (config.security.apiKeys.includes(apiKey)) {
+        req[API_KEY_NAME] = apiKey;
+        request[API_KEY_NAME] = apiKey;
+        return true;
+      }
+      throw getError('invalid API key', 401);
+    },
+    mock: (c, req) => {
+      const { request } = c;
+
+      req[API_KEY_NAME] = 'dummyApiKey';
+      request[API_KEY_NAME] = 'dummyApiKey';
+      return true;
+    },
+  };
+
+  return {
+    AdminSecurity,
+    SystemSecurity,
+    UserSecurity,
+    ApiKeySecurity,
+  };
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mimik/api-helper",
+  "version": "0.0.1",
+  "description": "helper for openAPI backend and mimik service",
+  "main": "index.js",
+  "scripts": {
+    "lint": "eslint --ignore-path .gitignore .",
+    "docs": "jsdoc2md index.js > README.md",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "test-ci": "echo \"Error: no test specified\" && exit 0",
+    "prepublishOnly": "npm run docs && npm run lint && npm run test-ci",
+    "commit-ready": "npm run docs && npm run lint && npm run test-ci",
+    "prepare": "husky install"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run commit-ready",
+      "pre-push": "npm run test"
+    }
+  },
+  "keywords": [
+    "mimik",
+    "microservice",
+    "openAPI"
+  ],
+  "author": "mimik technology inc <support@mimik.com> (https://developer.mimik.com/)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/mimiktech/api-helper"
+  },
+  "dependencies": {
+    "@mimik/request-helper":"^1.7.8",
+    "@mimik/request-retry": "^2.1.4",
+    "@mimik/response-helper": "^2.6.3",
+    "@mimik/sumologic-winston-logger": "^1.6.15",
+    "@mimik/swagger-helper": "^3.0.5",
+    "ajv-formats": "^3.0.0-rc.0",
+    "js-yaml":"^4.1.0",
+    "jsonwebtoken": "^9.0.0",
+    "lodash": "^4.17.21", 
+    "openapi-backend": "^5.9.1"
+  },
+  "devDependencies": {
+    "@mimik/eslint-plugin-dependencies": "^2.4.5",
+    "@mimik/eslint-plugin-document-env": "^1.0.5",
+    "eslint": "8.38.0",
+    "eslint-config-airbnb": "19.0.4",
+    "eslint-plugin-import": "2.27.5",
+    "eslint-plugin-jsx-a11y": "6.7.1",
+    "eslint-plugin-react": "7.32.2",
+    "eslint-plugin-react-hooks": "4.6.0",
+    "husky": "8.0.3",
+    "jsdoc-to-markdown": "8.0.0"
+  }
+}