@mimik/api-helper 1.0.2 → 1.1.0

package/README.md

@@ -11,7 +11,7 @@
 <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><p>Validates the known SecuritySchemes: <code>SystemSecurity</code>, <code>AdminSecurity</code>, <code>UserSecurity</code>, <code>PeerSecurity</code>, <code>ApiKeySecurity</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>
@@ -31,7 +31,14 @@ Setup the API to be use for a service
 
 - <code>Promise</code> An error is thrown if the initiatilization failed.
 
-By default System and Admin security are automatically registered
+For the security schemes, the following scheme names are reserved: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
+The secOptions in the options porperty passed when using `init` allows the folloing operations:
+- introduce a customer sevurity scheme, in this case secOptions contains: { newSecurityScheme: {function}newSecurityHandler },
+- disable a security scheme that is defined in the swagger API, in this case secOptions contains: { securitySchemeToDisable: { {boolean}notEnabled: true } },
+- overwite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }.
+If the secOptions is not present either to introduce, disable or overwrite a security scheme that is present in the swagger API file an error is generated.
+
+The default formats for validation are: `date`, `time`, `date-time`, `byte`, `uuid`, `uri`, `email`, `ipv4`, `ipv6`, `semver`, `ip`.
 
 **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>  
 
@@ -83,7 +90,7 @@ 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.  
+&fulfil {object} The API file, the API filename, the existing known security schemes and the defined security schemes.  
 **Category**: async  
 **Throws**:
 
@@ -102,10 +109,10 @@ Setup and validates files for the server
 <a name="validateSecuritySchemes"></a>
 
 ## validateSecuritySchemes(apiDefinition, correlationId) ⇒
-Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`.
+Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
 
 **Kind**: global function  
-**Returns**: An array of the know securitySchemes that are in the API definition.  
+**Returns**: An array of the known securitySchemes that are in the API definition.  
 **Category**: sync  
 **Throws**:
 

package/index.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const pathLib = require('path');
 const yaml = require('js-yaml');
 const compact = require('lodash.compact');
+const difference = require('lodash.difference');
 const SwaggerClient = require('swagger-client');
 const { Base64 } = require('js-base64');
 
@@ -65,11 +66,23 @@ const {
  * &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
+ * For the security schemes, the following scheme names are reserved: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
+ * The secOptions in the options porperty passed when using `init` allows the folloing operations:
+ * - introduce a customer sevurity scheme, in this case secOptions contains: { newSecurityScheme: {function}newSecurityHandler },
+ * - disable a security scheme that is defined in the swagger API, in this case secOptions contains: { securitySchemeToDisable: { {boolean}notEnabled: true } },
+ * - overwite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }.
+ * If the secOptions is not present either to introduce, disable or overwrite a security scheme that is present in the swagger API file an error is generated.
+ *
+ * The default formats for validation are: `date`, `time`, `date-time`, `byte`, `uuid`, `uri`, `email`, `ipv4`, `ipv6`, `semver`, `ip`.
  */
 const apiSetup = (setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) => {
-  const { apiFilename, existingSecuritySchemes } = setup;
-  const { SystemSecurity, AdminSecurity } = securityLib(config);
+  const { apiFilename, existingSecuritySchemes, definedSecuritySchemes } = setup;
+  const {
+    SystemSecurity,
+    AdminSecurity,
+    UserSecurity,
+    ApiKeySecurity,
+  } = securityLib(config);
   const api = new OpenAPIBackend({
     definition: apiFilename,
     apiRoot: config.serverSettings.basePath,
@@ -92,20 +105,35 @@ const apiSetup = (setup, registeredOperations, securityHandlers, extraFormats, c
     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]);
+  const appliedSecurities = [];
+  const registerDefault = (securitySchemeName, securityHandler) => {
+    if (existingSecuritySchemes.includes(securitySchemeName) && securityHandlers && !securityHandlers[securitySchemeName]) {
+      api.registerSecurityHandler(securitySchemeName, securityHandler);
+      appliedSecurities.push(securitySchemeName);
+    }
+  };
+
+  registerDefault(SYSTEM_SECURITY, SystemSecurity[mode]);
+  registerDefault(ADMIN_SECURITY, AdminSecurity[mode]);
+  registerDefault(USER_SECURITY, UserSecurity[mode]);
+  registerDefault(API_KEY_SECURITY, ApiKeySecurity[mode]);
+  const remainingSecurities = difference(definedSecuritySchemes, appliedSecurities);
+
   if (securityHandlers) {
     const securityHandlerNames = Object.keys(securityHandlers);
 
-    existingSecuritySchemes.forEach((securityScheme) => {
-      if (!securityHandlerNames.includes(securityScheme)) throw getRichError('System', 'missing handler for security Scheme', { securityScheme });
+    remainingSecurities.forEach((securityScheme) => {
+      if (!securityHandlerNames.includes(securityScheme) && !securityHandlers[securityScheme].notEnabled) {
+        throw getRichError('System', 'missing handler for security scheme', { securityScheme });
+      }
     });
     Object.keys(securityHandlers).forEach((securityHandlerName) => {
-      api.registerSecurityHandler(securityHandlerName, securityHandlers[securityHandlerName][mode]);
+      if (typeof securityHandlers[securityHandlerName][mode] === 'function') {
+        api.registerSecurityHandler(securityHandlerName, securityHandlers[securityHandlerName][mode]);
+      }
     });
   }
-  else if (existingSecuritySchemes.length !== 0) throw getRichError('System', 'missing handlers for security Scheme', { existingSecuritySchemes });
+  else if (remainingSecurities.length !== 0) throw getRichError('System', 'missing handlers for security schemes', { missingSecuritySchemes: remainingSecurities });
   api.init()
     .catch((err) => {
       throw getRichError('System', 'could not initialize the api', { api }, err);
@@ -290,7 +318,7 @@ const getAPIFile = (apiFilename, correlationId, options) => {
 
 /**
  *
- * Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`.
+ * Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
  *
  * @function validateSecuritySchemes
  * @category sync
@@ -298,7 +326,7 @@ const getAPIFile = (apiFilename, correlationId, options) => {
  * @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.
+ * @return An array of the known securitySchemes that are in the API definition.
  * @throws An error is thrown for the first validation fails.
  */
 const validateSecuritySchemes = (apiDefinition, correlationId) => {
@@ -308,8 +336,8 @@ const validateSecuritySchemes = (apiDefinition, correlationId) => {
     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, ADMIN_SECURITY, CLIENT_CREDENTIALS));
+    existingSecuritySchemes.push(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));
@@ -416,7 +444,7 @@ const extractProperties = (apiDefinition, controllersDirectory, buildDirectory,
  * @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.
+ * &fulfil {object} The API file, the API filename, the existing known security schemes and the defined 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)
@@ -424,7 +452,16 @@ const setupServerFiles = (apiFilename, controllersDirectory, buildDirectory, cor
     const existingSecuritySchemes = compact(validateSecuritySchemes(apiDefinition, correlationId));
 
     extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId);
-    return { apiDefinition, apiFilename, existingSecuritySchemes };
+    const schemes = apiDefinition.components?.securitySchemes;
+    let definedSecuritySchemes = [];
+
+    if (schemes) definedSecuritySchemes = Object.keys(schemes);
+    return {
+      apiDefinition,
+      apiFilename,
+      existingSecuritySchemes,
+      definedSecuritySchemes,
+    };
   });
 
 module.exports = {

package/lib/ajvHelpers.js

@@ -3,7 +3,16 @@ const addFormats = require('ajv-formats');
 const { DEFAULT_FORMATS } = require('./common');
 
 const ajvFormats = (origFormats) => (ajv) => {
-  const extraFormats = {};
+  const extraFormats = {
+    semver: {
+      type: 'string',
+      validate: /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,
+    },
+    ip: {
+      type: 'string',
+      validate: /((^\s*((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))\s*$)|(^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$))/,
+    },
+  };
   const libFormats = DEFAULT_FORMATS;
   let formats = origFormats;
 

package/lib/oauthValidation-helper.js

@@ -13,8 +13,10 @@ const validateOauth2 = (securitySchemes, securityType, flow) => {
       if (!security.flows[flow]) {
         throw getRichError('System', 'no flow type available', { securityType, flow });
       }
+      return securityType;
     }
   }
+  return null;
 };
 
 const validateApiKey = (securitySchemes, securityType) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mimik/api-helper",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "helper for openAPI backend and mimik service",
   "main": "index.js",
   "scripts": {
@@ -30,31 +30,31 @@
     "url": "https://bitbucket.org/mimiktech/api-helper"
   },
   "dependencies": {
-    "@mimik/request-helper":"^1.7.10",
+    "@mimik/request-helper":"^1.7.11",
     "@mimik/request-retry": "^3.0.1",
-    "@mimik/response-helper": "^3.0.1",
-    "@mimik/sumologic-winston-logger": "^1.6.20",
+    "@mimik/response-helper": "^3.1.0",
+    "@mimik/sumologic-winston-logger": "^1.6.21",
     "@mimik/swagger-helper": "^4.0.9",
-    "ajv-formats": "3.0.0-rc.0",
-    "js-base64": "3.7.5",
+    "ajv-formats": "3.0.1",
+    "js-base64": "3.7.7",
     "js-yaml":"4.1.0",
     "jsonwebtoken": "9.0.2",
     "lodash.compact": "3.0.1", 
     "lodash.difference": "4.5.0",
     "lodash.intersection": "4.4.0",
-    "openapi-backend": "5.10.5",
-    "swagger-client": "3.24.5"
+    "openapi-backend": "5.10.6",
+    "swagger-client": "3.28.2"
   },
   "devDependencies": {
     "@mimik/eslint-plugin-dependencies": "^2.4.6",
     "@mimik/eslint-plugin-document-env": "^1.0.6",
-    "eslint": "8.55.0",
+    "eslint": "8.57.0",
     "eslint-config-airbnb": "19.0.4",
-    "eslint-plugin-import": "2.29.0",
-    "eslint-plugin-jsx-a11y": "6.8.0",
-    "eslint-plugin-react": "7.33.2",
-    "eslint-plugin-react-hooks": "4.6.0",
-    "husky": "8.0.3",
-    "jsdoc-to-markdown": "8.0.0"
+    "eslint-plugin-import": "2.29.1",
+    "eslint-plugin-jsx-a11y": "6.9.0",
+    "eslint-plugin-react": "7.35.0",
+    "eslint-plugin-react-hooks": "4.6.2",
+    "husky": "9.1.4",
+    "jsdoc-to-markdown": "8.0.3"
   }
 }