binhend 2.2.12 → 2.3.1

package/index.js

@@ -8,10 +8,13 @@
 
 const path = require('path');
 
+
 //___ Run scripts ___//
 const moduleAlias = require('./packages/module-alias'); // path alias '@' for requiring modules: require('@/any/path') - use jsconfig.json
 moduleAlias.path('@binhend/*', [ path.join(__dirname, './packages') ]); // set path alias '@binhend' for all packages to call each others when 'npm install' in another project
 
+
+//___ Load packages ___//
 const server = require('./packages/core/src/server');
 const Router = require('./packages/core/src/Router');
 const { routes } = require('./packages/core/src/routes');
@@ -24,6 +27,7 @@ const { HTTPS } = require('./packages/https/src/https');
 
 const cors = require('./packages/middlewares/src/cors');
 const trycatch = require('./packages/middlewares/src/trycatch');
+const middlewares = require('./packages/middlewares');
 
 const { config, ConfigLoader } = require('./packages/config/src/configuration');
 
@@ -39,12 +43,14 @@ const validation = require('./packages/validation/src/typeValidation');
 const { WebBuild } = require('./packages/web/src/WebBuild');
 const { binh } = require('./packages/web/src/component.method');
 
+
+//___ Export packages ___//
 module.exports = {
     server, routes, Router,
 
     Bromise, HttpError, HttpCodes, HTTPS,
 
-    cors, trycatch,
+    cors, trycatch, middlewares,
 
     config, ConfigLoader,
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "binhend",
-    "version": "2.2.12",
+    "version": "2.3.1",
     "description": "",
     "main": "index.js",
     "author": "Nguyen Duc Binh",
@@ -15,10 +15,7 @@
     "scripts": {
         "test": "npm run test --workspace=test",
         "test:coverage": "npm run test:coverage --workspace=test",
-        "test:jest": "jest --config=test/jest.config.js",
-        "example-api": "node example_api PORT=5555",
-        "example-webcomp": "node example_webcomp",
-        "example-web2": "node example_web2"
+        "test:jest": "jest --config=test/jest.config.js"
     },
     "dependencies": {
         "express": "^4.17.1",

package/packages/middlewares/index.js

@@ -1,5 +1,7 @@
 module.exports = {
     cors: require('./src/cors'),
+    csrf: require('./src/csrf'),
+    authorize: require('./src/authorize'),
     parseCookies: require('./src/parseCookies'),
     parseBasicAuthToken: require('./src/parseBasicAuthToken'),
     trycatch: require('./src/trycatch'),

package/packages/middlewares/src/authorize.js

@@ -0,0 +1,157 @@
+
+const util = require('util');
+const must = require('@binhend/validation');
+const { HttpError, HttpCodes } = require('@binhend/utils');
+const { typeOf, isNumber, isFunction, isNullish } = require('@binhend/types');
+
+
+const Rules = Object.freeze({
+    OPTIONAL: 0
+});
+
+/**
+ * Auth - Function constructor for creating auth middleware builder
+ * 
+ * @constructor
+ * @param {Function} parseAuthPayload - Function to parse/verify auth payload from request
+ */
+function Auth(parseAuthPayload) {
+    if (!isFunction(parseAuthPayload)) {
+        throw new Error('Auth middleware requires a function to parse/verify auth payload from request.');
+    }
+
+    this.Rules = Rules;
+
+    /**
+     * Create auth middleware with pre-defined rules
+     * @param {Object} rules - Auth rules
+     * @returns {Function} Auth middleware
+     */
+    this.auth = function (rules) {
+        return async function (request, response, next) {
+            var payload, errorMessage;
+
+            try {
+                payload = parseAuthPayload(request);
+                payload = payload instanceof Promise ? await payload : payload; // the input function works properly for both sync and async
+                errorMessage = checkRuleViolation(rules, payload, request); // validate payload with rules
+            }
+            catch (error) {
+                if (rules === Rules.OPTIONAL) { // Auth is not strictly required
+                    next();
+                    return;
+                }
+                if (error instanceof HttpError) throw error;
+                else errorMessage = 'Auth payload might be invalid, expired or not provided';
+                console.error(
+                    `[BINHEND][AUTH] Failed parsing auth payload. Error:`,
+                    util.inspect(error, { showHidden: true, depth: null, colors: true })
+                );
+            }
+
+            if (errorMessage) {
+                console.error(`[BINHEND][AUTH] Access denied. ${errorMessage}.`);
+                throw new HttpError(HttpCodes.UNAUTHORIZED, 'Access denied. ' + errorMessage);
+            }
+
+            next();
+        };
+    };
+
+    this.payload = function (request) {
+        // Implementation ensure throwing error natively in router middleware or API controller,
+        // even when this method (.payload()) or the parsing handler (.parseAuthPayload()) is called with sync/async approach.
+        try {
+            var payload = parseAuthPayload(request);
+            return payload instanceof Promise ? payload.catch(handleError) : payload;
+        }
+        catch (error) {
+            handleError(error);
+        }
+
+        function handleError(error) {
+            if (error instanceof HttpError) throw error;
+            throw new HttpError(HttpCodes.UNAUTHORIZED, 'Access denied.');
+        }
+
+        // NTOICE: why not handle cache (e.g. request.user) for payload()?
+        // => side-effect might happens, outside logic could replace reference of request.user
+        // => payload() must be a trust source of returning auth payload (parsing again required)
+        // => users must handle cache in parseAuthPayload() by their own, also helpful to unify where cache is. (e.g. request.user, request.credentials, request.data, etc.)
+        // Bonus: if handling cache in, e.g. request.user, then should not use request.user elsewhere, but always calling payload() to get auth payload (cache) in an unified manner.
+    };
+
+    this.match = {
+        query: function (key) {
+            return (value, request) => value === request?.query?.[key];
+        },
+        params: function (key) {
+            return (value, request) => value === request?.params?.[key];
+        },
+        body: function (key) {
+            return (value, request) => value === request?.body?.[key];
+        }
+    };
+}
+
+function checkRuleViolation(rules, payload, request) {
+    var errorMessage;
+
+    if (isNullish(payload)) {
+        errorMessage = `Auth payload is null or undefined`;
+        return errorMessage;
+    }
+
+    rules = must.Object(rules, { default: {} });
+
+    for (const [key, expectedValue] of Object.entries(rules)) {
+
+        if (!payload.hasOwnProperty(key)) {
+            errorMessage = `Auth payload has no assignment for property: ${key}`;
+            break;
+        }
+
+        const actualValue = payload[key];
+
+        switch (typeOf(expectedValue)) {
+
+            case 'Array': // Handle array values (membership check)
+                const matchOneOfAllowedValues = expectedValue.includes(actualValue);
+                if (!matchOneOfAllowedValues) {
+                    errorMessage = `Expected ${key}: ${expectedValue.join('|')}. Got: ${actualValue}`;
+                }
+                break;
+
+            case 'Number': // Handle number values (minimum level check)
+                const reachMinNumber = isNumber(actualValue) && actualValue >= expectedValue;
+                if (!reachMinNumber) {
+                    errorMessage = `Minimum ${key} required: ${expectedValue}. Got: ${actualValue}`;
+                }
+                break;
+
+            case 'Function': // Handle function values (custom validation)
+                try {
+                    const isValidCheck = expectedValue(actualValue, request);
+                    if (!isValidCheck) errorMessage = `Custom validation failed for field: ${key}`;
+                }
+                catch (error) {
+                    errorMessage = `Custom validation error for field '${key}': ${error.message}`;
+                    if (error instanceof HttpError) throw error;
+                }
+                break;
+
+            default: // Handle all other types (exact match)
+                const matchExactValue = actualValue !== expectedValue;
+                if (!matchExactValue) {
+                    errorMessage = `Expected ${key}: ${expectedValue}. Got: ${actualValue}`;
+                }
+                break;
+        }
+
+        if (errorMessage) break;
+    }
+
+    return errorMessage;
+}
+
+module.exports = { Auth };

package/packages/middlewares/src/csrf.js

@@ -0,0 +1,89 @@
+const crypto = require('crypto');
+const types = require('@binhend/types');
+const validation = require('@binhend/validation');
+const { HttpCodes } = require('@binhend/utils');
+
+/**
+ * Utility function to generate CSRF token with expiry.
+ * 
+ * @returns {Object} { token, expiresAt }
+ */
+function generateTokenWithExpiry() {
+    const token = crypto.randomBytes(32).toString('hex');
+    const expiresAt = Date.now() + 15 * 60 * 1000; // 15 minutes expiry time
+    return JSON.stringify({ token, expiresAt });
+}
+
+/**
+ * Configurable middleware to verify and rotate CSRF tokens.
+ */
+module.exports = function (options = {}) {
+    // Prepare settings from custom and default options
+    const SAFE_HTTP_METHODS = validation.Array(options.safeMethods, { default: ['GET', 'HEAD', 'OPTIONS'] });
+    const CSRF_COOKIE_NAME = validation.String(options.cookie, { default: 'csrf_token' });
+    const CSRF_HEADER_NAME = validation.String(options.header, { default: 'X-CSRF-Token' });
+    const cookieSecure = validation.Boolean(options.secure, { default: true });
+    const cookieSameSite = validation.String(options.sameSite, { default: 'Strict' });
+    const cookiePath = validation.String(options.path);
+    const response = validation.Object(options.response);
+
+    // Finalize cookie options
+    const cookieOptions = {
+        httpOnly: false, // Client needs to read this
+        secure: cookieSecure,
+        sameSite: cookieSameSite
+    };
+
+    if (!types.isEmptyString(cookiePath)) {
+        cookieOptions.path = cookiePath;
+    }
+
+    // No return, but apply CSRF token for a response to client.
+    if (response) {
+        response.cookie(CSRF_COOKIE_NAME, generateTokenWithExpiry(), cookieOptions);
+        return;
+    }
+
+    // Return a middleware to protect route from CSRF attacks
+    return function (request, response, next) {
+        // Skip CSRF verification for safe methods
+        if (SAFE_HTTP_METHODS.includes(request.method)) {
+            return next();
+        }
+
+        // Read and check existence of CSRF token in header and cookie
+        const csrfCookie = request.cookies[CSRF_COOKIE_NAME];
+        const csrfHeader = request.get(CSRF_HEADER_NAME);
+
+        if (!csrfCookie || !csrfHeader) {
+            return response.status(HttpCodes.FORBIDDEN).json({ error: 'Missing CSRF token' });
+        }
+
+        // Validate token format
+        var parsed;
+
+        try {
+            parsed = JSON.parse(csrfCookie);
+        }
+        catch {
+            return response.status(HttpCodes.FORBIDDEN).json({ error: 'Malformed CSRF token' });
+        }
+
+        const { token, expiresAt } = parsed;
+
+        // Verify if the token in the header matches the cookie => valid
+        if (csrfHeader !== token) {
+            return response.status(403).json({ error: 'Invalid CSRF token' });
+        }
+
+        const isExpired = Date.now() > expiresAt;
+
+        // If the current token is expired (but valid), generate a new token and set it in the cookie
+        if (isExpired) {
+            const newTokenCSRF = generateTokenWithExpiry();
+            response.cookie(CSRF_COOKIE_NAME, newTokenCSRF, cookieOptions);
+        }
+
+        next(); // Proceed with the request
+    }
+};

package/index2.js

@@ -1,56 +0,0 @@
-/*
- * binhend
- * Copyright(c) 2023 Nguyen Duc Binh
- * 
- */
-
-'use strict';
-
-/** SERVER - Backend */
-const { server } = require('./src/server');
-const { ConfigLoader, config } = require('./src/configuration');
-const { HTTPS } = require('./src/https');
-
-const HttpError = require('./src/api/HttpError');
-const HttpCodes = require('./src/api/HttpCodes');
-
-const Router = require('./src/api/Router');
-const { routes, loadRoutes, buildRoutes, mapRoutes } = require('./src/api/routes');
-const trycatch = require('./src/api/trycatch');
-
-const cors = require('./src/middleware/cors');
-
-const createCSD = require('./src/csd');
-const crypto = require('./src/crypto');
-const types = require('./src/utils/types');
-const validation = require('./src/utils/validation');
-const typedefs = require('./src/utils/typedefs');
-const Bromise = require('./src/utils/Bromise.js');
-
-/** CLIENT - Frontend */
-const { WebBuild } = require('./src/web');
-const { binh } = require('./src/web/component.method');
-
-// Run scripts
-require('./src/alias-module');
-
-module.exports = {
-    server,
-    ConfigLoader, config,
-    HTTPS,
-    HttpError,
-    HttpCodes,
-    Router,
-    routes, buildRoutes, loadRoutes, mapRoutes,
-    trycatch,
-    cors,
-    createCSD,
-    crypto,
-    types,
-    typedefs,
-    validation,
-    Bromise,
-    WebBuild,
-    WebBuilder: WebBuild,
-    binh
-};

package/src/types/common.d.ts

@@ -1,10 +0,0 @@
-
-/**
- * @typedef {Object<string, any>} ObjectType
- */
-
-/**
- * @typedef {(Date|string|number)} DateType
- */
-
-export {};

package/src/types/index.d.ts

@@ -1,2 +0,0 @@
-
-export * from './common.d.ts';

package/src/utils/typedefs.js

@@ -1,31 +0,0 @@
-
-/**
- * @typedef {Object<string, any>} ObjectType
- */
-
-/**
- * Type definition for object accepting any extra properties
- *
- * @returns {ObjectType}
- */
-function ObjectType() { return this; }
-
-
-
-/**
- * @typedef {(Date|string|number)} DateType
- */
-
-/**
- * Type definition for date accepting any valid formats (string, number, date)
- *
- * @returns {DateType}
- */
-function DateType() { return this; }
-
-
-
-module.exports = {
-    ObjectType,
-    DateType
-};