@skillswaveca/nova-shared-libraries 3.9.2 → 3.10.0

package/docs-base/package-info.js

@@ -1,25 +1,31 @@
 export const packageInfo = [
   {
     "name": "@skillswaveca/nova-utils",
-    "version": "3.9.1",
+    "version": "3.9.2",
     "description": "A collection of random utils used in nova repos",
     "docsPath": "./nova-utils/index.html"
   },
+  {
+    "name": "nova-router",
+    "version": "2.0.0",
+    "description": "An extended Koa router that enables better validation",
+    "docsPath": "./nova-router/index.html"
+  },
   {
     "name": "@skillswaveca/nova-model",
-    "version": "3.9.1",
+    "version": "3.9.2",
     "description": "Nova model stuff",
     "docsPath": "./nova-model/index.html"
   },
   {
     "name": "@skillswaveca/nova-middleware",
-    "version": "3.9.1",
+    "version": "3.9.2",
     "description": "A collection of middleware used by nova projects",
     "docsPath": "./nova-middleware/index.html"
   },
   {
     "name": "@skillswaveca/nova-drivers",
-    "version": "3.9.1",
+    "version": "3.9.2",
     "description": "Some helper drivers for AWS services",
     "docsPath": "./drivers/index.html"
   }

package/index.js

@@ -1,6 +1,7 @@
 export * from './packages/nova-utils/src/tenant-utils.js';
 export * from './packages/nova-utils/src/logger.js';
 export * from './packages/nova-utils/src/config.js';
+export * from './packages/nova-router/src/nova-router.js';
 export * from './packages/nova-middleware/src/oauth-middleware.js';
 export * from './packages/nova-middleware/src/distributed-logging-middleware.js';
 export * from './packages/drivers/src/wave.js';

package/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-shared-libraries",
   "description": "A monorepo of shared libraries for Nova projects.",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "main": "index.js",
   "license": "MIT",
   "keywords": [],
@@ -14,6 +14,7 @@
     "@aws-sdk/client-sqs": "^3.682.0",
     "@aws-sdk/client-ssm": "^3.682.0",
     "@aws-sdk/lib-dynamodb": "^3.682.0",
+    "@koa/router": "^13.1.0",
     "aws-xray-sdk-core": "^3.6.0",
     "jsonwebtoken": "^9.0.2",
     "jwk-to-pem": "^2.0.5",

package/packages/drivers/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-drivers",
   "description": "Some helper drivers for AWS services",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/nova-middleware/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-middleware",
   "description": "A collection of middleware used by nova projects",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/nova-model/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-model",
   "description": "Nova model stuff",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/nova-router/README.md

@@ -0,0 +1,5 @@
+# nova-router
+
+## Description
+An extended Koa router that enables better validation
+

package/packages/nova-router/index.js

@@ -0,0 +1 @@
+export * from './src/nova-router.js';

package/packages/nova-router/package.json

@@ -0,0 +1,18 @@
+{
+  "type": "module",
+  "name": "nova-router",
+  "description": "An extended Koa router that enables better validation",
+  "repository": "https://github.com/SkillsWave/nova-shared-libraries",
+  "version": "3.10.0",
+  "main": "index.js",
+  "scripts": {
+    "pre-release": "pnpm run create-index",
+    "create-index": "node ../../scripts/create-index.js",
+    "generate-docs": "documentation build src/** -f html -o docs",
+    "test": "mocha --parallel 'test/**/*.test.js'"
+  },
+  "author": "SkillsWave",
+  "license": "UNLICENSED",
+  "devDependencies": {},
+  "dependencies": {}
+}

package/packages/nova-router/src/nova-router.js

@@ -0,0 +1,293 @@
+import Router from '@koa/router';
+
+export const CATCH_ALL_SCOPE = 'all';
+
+/**
+ * NovaRouter is a custom router class that extends a base Router class.
+ * It provides additional functionality for input validation and scope checking
+ * on various HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and ALL).
+ *
+ * @class NovaRouter
+ *
+ * NOTE: Each of the routing functions follow the same signature.
+ *
+ * @param {string} path - The path for which the middleware function is invoked.
+ * @param {Object} middlewareConfig - Configuration object for middleware.
+ * @param {function} [middlewareConfig.validator] - A function that validates the input.
+ * It should be an async function that takes the context as an argument and throws an error with a property 'errors'.
+ * 'errors' should be either an array of error messages or null.
+ * @param {string[]} [middlewareConfig.scopes] - An array of required scopes.
+ * @param {...function} middleware - The middleware functions to execute once the input is validated.
+ *
+ * @example
+ * const middlewareConfig = {
+ *     validator: RouterValidator.Schema({
+ *       queryValidator: // params validator here
+ *       paramsValidator: // params validator here
+ *       bodyValidator: // body validator here
+ *     }),
+ *     scopes: ['scope1', 'scope2']
+ *  };
+ *
+ */
+export class NovaRouter extends Router {
+    _createInputValidatorMiddleware(inputValidator) {
+        return async(context, next) => {
+            if (typeof inputValidator !== 'function') {
+                const message = `[${context.request.method}] ${context.request.url} does not have a valid input validator`;
+                context.log.error(message);
+
+                context.status = 500;
+                context.body = {
+                    message,
+                };
+                return;
+            }
+
+            try {
+                await inputValidator(context);
+            } catch (error) {
+                context.status = 400;
+                context.body = {
+                    errors: error.errors,
+                    body: context.request.body,
+                    query: context.request.query,
+                    params: context.params,
+                };
+                return;
+            }
+            await next();
+        };
+    }
+
+    /**
+     * Generates a middleware that checks if the user has the required scopes.
+     *
+     * @param scopes
+     * @returns {(function(*, *): Promise<void>)|*}
+     * @private
+     */
+    _createScopesMiddleware(scopes) {
+        if (!scopes || scopes.length === 0) return async(context, next) => {
+            if (!context.state.scopes.includes(CATCH_ALL_SCOPE)) {
+                context.status = 403;
+                context.body = {
+                    message: 'Missing required scopes',
+                    requiredScopes: [CATCH_ALL_SCOPE],
+                    userScopes: context.state.scopes,
+                };
+                return;
+            }
+            await next();
+        };
+        return async(context, next) => {
+            // If the user has the catch-all scope, allow the request
+            if (!context.state.scopes.includes(CATCH_ALL_SCOPE)) {
+                const userScopes = context.state.scopes;
+                const missingScopes = scopes.filter(scope => !userScopes.includes(scope));
+                if (missingScopes.length > 0) {
+                    context.status = 403;
+                    context.body = {
+                        message: 'Missing required scopes',
+                        requiredScopes: scopes,
+                        userScopes,
+                    };
+                    return;
+                }
+            }
+            await next();
+        };
+    }
+
+    /**
+     * Constructs multiple middleware functions based on the given middleware configuration.
+     * @param middlewareInput
+     * @private
+     */
+    _constructMiddleware(middlewareInput) {
+        const { scopes, validator } = middlewareInput;
+
+        const ret = [];
+        ret.push(this._createScopesMiddleware(scopes));
+
+        if (validator) {
+            const middleware = this._createInputValidatorMiddleware(validator);
+            if (middleware) ret.push(middleware);
+        }
+        return ret;
+    }
+
+    /**
+     * Use given middleware.
+     *
+     * Middleware run in the order they are defined by `.use()`. They are invoked
+     * sequentially, requests start at the first middleware and work their way
+     * "down" the middleware stack.
+     *
+     * router.use('/path', middlewareConfig, middleware1, middleware2);
+     */
+    use(...args) {
+        let updatedArgs = [];
+        if (typeof args[0] === 'string') {
+            const middleware = this._constructMiddleware(args[1]);
+            updatedArgs = [
+                ...args.slice(0, 1),
+                ...middleware,
+                ...args.slice(2),
+            ];
+        }
+
+        super.use(...updatedArgs);
+    }
+
+    /**
+     * Registers a GET request handler with input validation.
+     *
+     * router.get('/path', middlewareConfig, middleware1, middleware2);
+     */
+    get(path, middlewareConfig, ...middleware) {
+        super.get(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a POST request handler with input validation.
+     *
+     * router.post('/path', middlewareConfig, middleware1, middleware2);
+     */
+    post(path, middlewareConfig, ...middleware) {
+        super.post(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a PUT request handler with input validation.
+     *
+     * router.put('/path', middlewareConfig, middleware1, middleware2);
+     */
+    put(path, middlewareConfig, ...middleware) {
+        super.put(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a PATCH request handler with input validation.
+     *
+     * router.patch('/path', middlewareConfig, middleware1, middleware2);
+     */
+    patch(path, middlewareConfig, ...middleware) {
+        super.patch(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a DELETE request handler with input validation.
+     *
+     * router.delete('/path', middlewareConfig, middleware1, middleware2);
+     */
+    delete(path, middlewareConfig, ...middleware) {
+        super.delete(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a HEAD request handler with input validation.
+     *
+     * router.head('/path', middlewareConfig, middleware1, middleware2);
+     */
+    head(path, middlewareConfig, ...middleware) {
+        super.head(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a OPTIONS request handler with input validation.
+     *
+     * router.options('/path', middlewareConfig, middleware1, middleware2);
+     */
+    options(path, middlewareConfig, ...middleware) {
+        super.options(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a DELETE request handler with input validation.
+     *
+     * router.del('/path', middlewareConfig, middleware1, middleware2);
+     */
+    del(path, middlewareConfig, ...middleware) {
+        super.del(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+
+    /**
+     * Registers a request handler for all HTTP verb with input validation.
+     *
+     * router.all('/path', middlewareConfig, middleware1, middleware2);
+     */
+    all(path, middlewareConfig, ...middleware) {
+        super.all(path, ...this._constructMiddleware(middlewareConfig), ...middleware);
+    }
+}
+
+export class ValidationError extends Error {
+    constructor(errors) {
+        super('There was a validation error');
+        this.name = 'ValidationError';
+        this.errors = errors;
+    }
+}
+
+export const RouterValidator = {
+    None: () => {
+        return () => {
+            return;
+        };
+    },
+
+    /**
+     * Defines a schema for validating the request input.
+     *
+     * @typedef {Object} Validators
+     * @param {Yup.Schema} bodyValidator - Yup schema used to validate the body object.
+     * @param {Yup.Schema} queryValidator - Yup schema used to validate the query object.
+     * @param {Yup.Schema} paramsValidator - Yup schema used to validate the params object.
+     * @example
+     * RouterValidator.Schema({
+     *   queryValidator: object({
+     *     from: number().min(0).integer(),
+     *     size: number().positive().integer().max(1000),
+     *     filters: object({
+     *       providers: array().of(string().uuid()),
+     *       statuses: array().of(string()),
+     *       activities: array().of(string().uuid()),
+     *       employers: array().of(string().uuid()),
+     *     }).json(),
+     *     sort: object({
+     *       colName: string(),
+     *       order: string().oneOf(['asc', 'desc']),
+     *     }).json(),
+     *     includeAggregations: boolean(),
+     *   }),
+     * })
+     */
+    Schema: ({ bodyValidator, queryValidator, paramsValidator }) => {
+        return context => {
+            const promises = [];
+
+            if (queryValidator) {
+                if (!context.request.query) {
+                    throw new ValidationError(['Missing query parameters']);
+                }
+
+                promises.push(queryValidator.validate(context.request.query, { abortEarly: false }));
+            }
+
+            if (bodyValidator) {
+                if (!context.request.body) {
+                    throw new ValidationError(['Missing body']);
+                }
+
+                promises.push(bodyValidator.validate(context.request.body, { abortEarly: false }));
+            }
+
+            if (paramsValidator) {
+                promises.push(paramsValidator.validate(context.params, { abortEarly: false }));
+            }
+
+            return Promise.all(promises);
+        };
+    },
+};

package/packages/nova-utils/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-utils",
   "description": "A collection of random utils used in nova repos",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",