mbkauthe 2.5.0 → 3.0.0

package/lib/utils/errors.js

@@ -0,0 +1,257 @@
+/**
+ * Centralized error messages and error codes for mbkauthe
+ * Provides consistent, user-friendly error messages across the application
+ */
+
+// Error codes for different scenarios
+export const ErrorCodes = {
+  // Authentication errors (600-699)
+  INVALID_CREDENTIALS: 601,
+  USER_NOT_FOUND: 602,
+  INCORRECT_PASSWORD: 603,
+  ACCOUNT_INACTIVE: 604,
+  APP_NOT_AUTHORIZED: 605,
+  
+  // 2FA errors (700-799)
+  TWO_FA_REQUIRED: 701,
+  TWO_FA_INVALID_TOKEN: 702,
+  TWO_FA_NOT_CONFIGURED: 703,
+  TWO_FA_EXPIRED: 704,
+  
+  // Session errors (800-899)
+  SESSION_EXPIRED: 801,
+  SESSION_INVALID: 802,
+  SESSION_NOT_FOUND: 803,
+  
+  // Authorization errors (900-999)
+  INSUFFICIENT_PERMISSIONS: 901,
+  ROLE_NOT_ALLOWED: 902,
+  
+  // Input validation errors (1000-1099)
+  MISSING_REQUIRED_FIELD: 1001,
+  INVALID_USERNAME_FORMAT: 1002,
+  INVALID_PASSWORD_LENGTH: 1003,
+  INVALID_TOKEN_FORMAT: 1004,
+  
+  // Rate limiting (1100-1199)
+  RATE_LIMIT_EXCEEDED: 1101,
+  
+  // Server errors (1200-1299)
+  INTERNAL_SERVER_ERROR: 1201,
+  DATABASE_ERROR: 1202,
+  CONFIGURATION_ERROR: 1203,
+  
+  // GitHub OAuth errors (1300-1399)
+  GITHUB_NOT_LINKED: 1301,
+  GITHUB_AUTH_FAILED: 1302,
+  OAUTH_STATE_MISMATCH: 1303,
+};
+
+// User-friendly error messages
+export const ErrorMessages = {
+  // Authentication
+  [ErrorCodes.INVALID_CREDENTIALS]: {
+    message: "Invalid username or password",
+    userMessage: "The username or password you entered is incorrect. Please try again.",
+    hint: "Check your spelling and make sure Caps Lock is off"
+  },
+  [ErrorCodes.USER_NOT_FOUND]: {
+    message: "User account not found",
+    userMessage: "We couldn't find an account with that username.",
+    hint: "Please check the username and try again"
+  },
+  [ErrorCodes.INCORRECT_PASSWORD]: {
+    message: "Incorrect password",
+    userMessage: "The password you entered is incorrect.",
+    hint: "Make sure you're using the correct password for this account"
+  },
+  [ErrorCodes.ACCOUNT_INACTIVE]: {
+    message: "Account is inactive",
+    userMessage: "Your account has been deactivated.",
+    hint: "Please contact your administrator to reactivate your account"
+  },
+  [ErrorCodes.APP_NOT_AUTHORIZED]: {
+    message: "Not authorized for this application",
+    userMessage: "You don't have permission to access this application.",
+    hint: "Contact your administrator if you believe this is an error"
+  },
+  
+  // 2FA
+  [ErrorCodes.TWO_FA_REQUIRED]: {
+    message: "Two-factor authentication required",
+    userMessage: "Please enter your 6-digit authentication code.",
+    hint: "Check your authenticator app for the code"
+  },
+  [ErrorCodes.TWO_FA_INVALID_TOKEN]: {
+    message: "Invalid 2FA code",
+    userMessage: "The authentication code you entered is incorrect.",
+    hint: "Make sure you're using the latest code from your authenticator app"
+  },
+  [ErrorCodes.TWO_FA_NOT_CONFIGURED]: {
+    message: "2FA not configured",
+    userMessage: "Two-factor authentication is not set up for your account.",
+    hint: "Contact your administrator to enable 2FA"
+  },
+  [ErrorCodes.TWO_FA_EXPIRED]: {
+    message: "2FA code expired",
+    userMessage: "The authentication code has expired.",
+    hint: "Please use a fresh code from your authenticator app"
+  },
+  
+  // Session
+  [ErrorCodes.SESSION_EXPIRED]: {
+    message: "Session expired",
+    userMessage: "Your session has expired. Please log in again.",
+    hint: "This happens when you've been inactive for too long"
+  },
+  [ErrorCodes.SESSION_INVALID]: {
+    message: "Invalid session",
+    userMessage: "Your session is no longer valid. Please log in again.",
+    hint: "This may happen if you logged in from another device"
+  },
+  [ErrorCodes.SESSION_NOT_FOUND]: {
+    message: "Session not found",
+    userMessage: "Please log in to continue.",
+    hint: "You need to be logged in to access this page"
+  },
+  
+  // Authorization
+  [ErrorCodes.INSUFFICIENT_PERMISSIONS]: {
+    message: "Insufficient permissions",
+    userMessage: "You don't have permission to perform this action.",
+    hint: "Contact your administrator if you need access"
+  },
+  [ErrorCodes.ROLE_NOT_ALLOWED]: {
+    message: "Role not allowed",
+    userMessage: "Your account role doesn't have access to this feature.",
+    hint: "This feature requires a different permission level"
+  },
+  
+  // Input Validation
+  [ErrorCodes.MISSING_REQUIRED_FIELD]: {
+    message: "Required field missing",
+    userMessage: "Please fill in all required fields.",
+    hint: "Username and password are required"
+  },
+  [ErrorCodes.INVALID_USERNAME_FORMAT]: {
+    message: "Invalid username format",
+    userMessage: "Please enter a valid username.",
+    hint: "Username must be 1-255 characters"
+  },
+  [ErrorCodes.INVALID_PASSWORD_LENGTH]: {
+    message: "Invalid password length",
+    userMessage: "Password must be at least 8 characters long.",
+    hint: "Please use a password with 8 or more characters"
+  },
+  [ErrorCodes.INVALID_TOKEN_FORMAT]: {
+    message: "Invalid token format",
+    userMessage: "Please enter a valid 6-digit code.",
+    hint: "The code should be 6 numbers from your authenticator app"
+  },
+  
+  // Rate Limiting
+  [ErrorCodes.RATE_LIMIT_EXCEEDED]: {
+    message: "Too many requests",
+    userMessage: "Too many attempts. Please try again later.",
+    hint: "Wait a few minutes before trying again"
+  },
+  
+  // Server Errors
+  [ErrorCodes.INTERNAL_SERVER_ERROR]: {
+    message: "Internal server error",
+    userMessage: "Something went wrong on our end.",
+    hint: "Please try again later or contact support if the problem persists"
+  },
+  [ErrorCodes.DATABASE_ERROR]: {
+    message: "Database error",
+    userMessage: "We're experiencing technical difficulties.",
+    hint: "Please try again in a few moments"
+  },
+  [ErrorCodes.CONFIGURATION_ERROR]: {
+    message: "Configuration error",
+    userMessage: "The service is temporarily unavailable.",
+    hint: "Please contact your administrator"
+  },
+  
+  // GitHub OAuth
+  [ErrorCodes.GITHUB_NOT_LINKED]: {
+    message: "GitHub account not linked",
+    userMessage: "Your GitHub account is not linked to any user account.",
+    hint: "Please link your GitHub account in your profile settings first"
+  },
+  [ErrorCodes.GITHUB_AUTH_FAILED]: {
+    message: "GitHub authentication failed",
+    userMessage: "We couldn't authenticate you with GitHub.",
+    hint: "Please try again or use username/password login"
+  },
+  [ErrorCodes.OAUTH_STATE_MISMATCH]: {
+    message: "OAuth state mismatch",
+    userMessage: "Authentication verification failed.",
+    hint: "Please try logging in again"
+  },
+};
+
+/**
+ * Get error details by error code
+ * @param {number} errorCode - The error code
+ * @param {Object} customData - Optional custom data to merge with error
+ * @returns {Object} Error details with message, userMessage, and hint
+ */
+export function getErrorByCode(errorCode, customData = {}) {
+  const errorDetails = ErrorMessages[errorCode] || {
+    message: "An error occurred",
+    userMessage: "An unexpected error occurred. Please try again.",
+    hint: "Contact support if this problem continues"
+  };
+  
+  return {
+    errorCode,
+    ...errorDetails,
+    ...customData
+  };
+}
+
+/**
+ * Create a standardized error response
+ * @param {number} statusCode - HTTP status code
+ * @param {number} errorCode - Application error code
+ * @param {Object} customData - Optional custom data
+ * @returns {Object} Standardized error response
+ */
+export function createErrorResponse(statusCode, errorCode, customData = {}) {
+  const error = getErrorByCode(errorCode, customData);
+  
+  return {
+    success: false,
+    statusCode,
+    errorCode: error.errorCode,
+    message: error.userMessage || error.message,
+    hint: error.hint,
+    timestamp: new Date().toISOString(),
+    ...customData
+  };
+}
+
+/**
+ * Log error with consistent format
+ * @param {string} context - Context where error occurred
+ * @param {number} errorCode - Error code
+ * @param {Object} additionalInfo - Additional info to log
+ */
+export function logError(context, errorCode, additionalInfo = {}) {
+  const error = getErrorByCode(errorCode);
+  console.error(`[mbkauthe] ${context}:`, {
+    errorCode,
+    message: error.message,
+    ...additionalInfo,
+    timestamp: new Date().toISOString()
+  });
+}
+
+export default {
+  ErrorCodes,
+  ErrorMessages,
+  getErrorByCode,
+  createErrorResponse,
+  logError
+};

package/lib/utils/response.js

@@ -0,0 +1,21 @@
+import { mbkautheVar, packageJson } from "../config/index.js";
+
+// Helper function to render error pages consistently
+export const renderError = (res, { code, error, message, page, pagename, details }) => {
+    res.status(code);
+    const renderData = {
+        layout: false,
+        code,
+        error,
+        message,
+        page,
+        pagename,
+        app: mbkautheVar.APP_NAME,
+        version: packageJson.version
+    };
+
+    // Add optional parameters if provided
+    if (details !== undefined) renderData.details = details;
+
+    return res.render("Error/dError.handlebars", renderData);
+};

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "mbkauthe",
-  "version": "2.5.0",
+  "version": "3.0.0",
   "description": "MBKTech's reusable authentication system for Node.js applications.",
   "main": "index.js",
   "type": "module",
+  "types": "index.d.ts",
   "scripts": {
     "dev": "cross-env test=dev nodemon index.js"
   },
@@ -20,7 +21,7 @@
     "security"
   ],
   "author": "Muhammad Bin Khalid <support@mbktech.org>",
-  "license": "MPL-2.0",
+  "license": "GPL-2.0",
   "bugs": {
     "url": "https://github.com/MIbnEKhalid/mbkauthe/issues"
   },
@@ -49,6 +50,8 @@
     "url": "^0.11.4"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.19.1",
     "cross-env": "^7.0.3",
     "nodemon": "^3.1.11"
   }

package/public/main.js

@@ -25,7 +25,7 @@ async function logout() {
       alert(result.message);
     }
   } catch (error) {
-    console.error("Error during logout:", error);
+    console.error("[mbkauthe] Error during logout:", error);
     alert(`Logout failed: ${error.message}`);
   }
 }
@@ -64,7 +64,7 @@ async function nuclearCacheClear() {
           return Promise.resolve();
         }));
       } catch (error) {
-        console.error("Error clearing IndexedDB:", error);
+        console.error("[mbkauthe] Error clearing IndexedDB:", error);
       }
     }
 
@@ -84,7 +84,7 @@ async function nuclearCacheClear() {
     window.location.reload();
 
   } catch (error) {
-    console.error('Nuclear cache clear failed:', error);
+    console.error('[mbkauthe] Nuclear cache clear failed:', error);
     window.location.reload(true);
   }
 }
@@ -103,7 +103,7 @@ function checkSession() {
         window.location.reload(); // Reload the page to update the session status
       }
     })
-    .catch((error) => console.error("Error checking session:", error));
+    .catch((error) => console.error("[mbkauthe] Error checking session:", error));
 }
 // Call validateSession every 2 minutes (120000 milliseconds)
 // setInterval(checkSession, validateSessionInterval);

package/views/Error/dError.handlebars

@@ -55,7 +55,7 @@
       color: var(--accent);
       text-decoration: none;
       transition: var(--transition);
-      margin: 0 15px;
+      margin: 0 auto;
       font-size: 1rem;
       font-weight: 600;
     }

package/views/errorCodes.handlebars

@@ -0,0 +1,341 @@
+<!DOCTYPE html>
+<html lang="en">
+
+{{> head}}
+
+<body>
+    {{> header}}
+
+    <style>
+        .container {
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 2rem;
+            padding-top: 100px;
+        }
+
+        .page-header {
+            text-align: center;
+            padding: 3rem 0 2rem;
+            border-bottom: 2px solid rgba(0, 184, 148, 0.3);
+        }
+
+        .page-header h1 {
+            font-size: 2.5rem;
+            color: var(--accent);
+            margin-bottom: 0.5rem;
+        }
+
+        .page-header p {
+            font-size: 1.1rem;
+            color: var(--text-light);
+        }
+
+        .search-box {
+            margin-bottom: 2rem;
+            position: sticky;
+            top: 70px;
+            background: transparent;
+            backdrop-filter: blur(10px);
+            padding: 1rem 0;
+            z-index: 100;
+            border-bottom: 1px solid rgba(0, 184, 148, 0.2);
+        }
+
+        .search-input {
+            width: 100%;
+            padding: 1rem 1.5rem;
+            background: rgba(255, 255, 255, 0.05);
+            border: 2px solid rgba(0, 184, 148, 0.3);
+            border-radius: 8px;
+            color: #e0f7fa;
+            font-size: 1rem;
+            transition: all 0.3s ease;
+        }
+
+        .search-input:focus {
+            outline: none;
+            border-color: #00b894;
+            background: rgba(255, 255, 255, 0.08);
+        }
+
+        .search-input::placeholder {
+            color: #b2dfdb;
+            opacity: 0.6;
+        }
+
+        .category {
+            margin-bottom: 3rem;
+        }
+
+        .category-header {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+            margin-bottom: 1.5rem;
+            padding: 1rem;
+            background: rgba(0, 184, 148, 0.1);
+            border-left: 4px solid #00b894;
+            border-radius: 4px;
+        }
+
+        .category-header h2 {
+            font-size: 1.8rem;
+            color: var(--accent);
+        }
+
+        .category-header .range {
+            font-size: 1rem;
+            color: var(--text-light);
+            font-weight: normal;
+        }
+
+        .error-card {
+            background: rgba(10, 20, 20, 0.8);
+            border: 1px solid rgba(0, 184, 148, 0.2);
+            border-radius: 8px;
+            padding: 1.5rem;
+            margin-bottom: 1.5rem;
+            transition: all 0.3s ease;
+            scroll-margin-top: 100px;
+        }
+
+        .error-card:hover {
+            border-color: #00b894;
+            box-shadow: 0 4px 20px rgba(0, 184, 148, 0.2);
+            transform: translateY(-2px);
+        }
+
+        .error-header {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+            margin-bottom: 1rem;
+        }
+
+        .error-code {
+            background: var(--warning);
+            color: var(--darker);
+            padding: 0.5rem 1rem;
+            border-radius: 6px;
+            font-weight: bold;
+            font-size: 1.1rem;
+        }
+
+        .error-name {
+            color: var(--accent);
+            font-size: 1.3rem;
+            font-weight: 600;
+        }
+
+        .error-message {
+            color: var(--text);
+            font-size: 1.1rem;
+            margin-bottom: 0.75rem;
+            padding-left: 1rem;
+            border-left: 3px solid rgba(0, 184, 148, 0.3);
+        }
+
+        .error-hint {
+            background: rgba(255, 209, 102, 0.1);
+            color: var(--warning);
+            padding: 0.75rem 1rem;
+            border-radius: 6px;
+            border-left: 3px solid var(--warning);
+            font-size: 0.95rem;
+            margin-top: 0.75rem;
+        }
+
+
+
+        .no-results {
+            text-align: center;
+            padding: 3rem;
+            color: var(--text-light);
+            font-size: 1.2rem;
+        }
+
+        .back-to-top {
+            position: fixed;
+            bottom: 2rem;
+            right: 2rem;
+            background: var(--accent);
+            color: var(--darker);
+            width: 50px;
+            height: 50px;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 1.5rem;
+            cursor: pointer;
+            box-shadow: 0 4px 20px rgba(0, 184, 148, 0.3);
+            transition: all 0.3s ease;
+            opacity: 0;
+            pointer-events: none;
+        }
+
+        .back-to-top.visible {
+            opacity: 1;
+            pointer-events: all;
+        }
+
+        .back-to-top:hover {
+            transform: translateY(-5px);
+            box-shadow: 0 6px 25px rgba(0, 184, 148, 0.4);
+        }
+
+        @media (max-width: 768px) {
+            .page-header h1 {
+                font-size: 2rem;
+            }
+
+            .category-header h2 {
+                font-size: 1.5rem;
+            }
+
+            .error-card {
+                padding: 1rem;
+            }
+
+            .error-header {
+                flex-direction: column;
+                align-items: flex-start;
+            }
+        }
+    </style>
+
+    <div class="container">
+        <div class="page-header">
+            <h1>🔐 MBKAuthe Error Codes</h1>
+            <p>Complete reference guide for all error codes and their solutions</p>
+        </div>
+
+        <div class="search-box">
+            <input type="text" class="search-input" id="searchInput" placeholder="Search by error code, name, or description...">
+        </div>
+
+        <div id="errorContainer">
+            {{#each errorCategories}}
+            <div class="category" data-category="{{this.category}}">
+                <div class="category-header">
+                    <h2>{{this.icon}} {{this.name}}</h2>
+                    <span class="range">{{this.range}}</span>
+                </div>
+
+                {{#each this.errors}}
+                <div class="error-card" id="error-{{this.code}}" data-search="{{this.code}} {{this.name}} {{this.message}} {{this.userMessage}} {{this.hint}}">
+                    <div class="error-header">
+                        <span class="error-code">{{this.code}}</span>
+                        <span class="error-name">{{this.name}}</span>
+                    </div>
+                    <div class="error-message">
+                        {{this.userMessage}}
+                    </div>
+                    <div class="error-hint">
+                        💡 {{this.hint}}
+                    </div>
+                </div>
+                {{/each}}
+            </div>
+            {{/each}}
+        </div>
+
+        <div class="no-results" id="noResults" style="display: none;">
+            No error codes found matching your search.
+        </div>
+    </div>
+
+    <div class="back-to-top" id="backToTop">↑</div>
+
+    <script>
+        // Search functionality
+        const searchInput = document.getElementById('searchInput');
+        const errorCards = document.querySelectorAll('.error-card');
+        const categories = document.querySelectorAll('.category');
+        const noResults = document.getElementById('noResults');
+
+        searchInput.addEventListener('input', function() {
+            const searchTerm = this.value.toLowerCase().trim();
+            let hasResults = false;
+
+            if (!searchTerm) {
+                // Show all cards and categories
+                errorCards.forEach(card => card.style.display = 'block');
+                categories.forEach(cat => cat.style.display = 'block');
+                noResults.style.display = 'none';
+                return;
+            }
+
+            // Search through error cards
+            errorCards.forEach(card => {
+                const searchData = card.getAttribute('data-search').toLowerCase();
+                if (searchData.includes(searchTerm)) {
+                    card.style.display = 'block';
+                    hasResults = true;
+                } else {
+                    card.style.display = 'none';
+                }
+            });
+
+            // Hide/show categories based on visible cards
+            categories.forEach(category => {
+                const visibleCards = category.querySelectorAll('.error-card[style="display: block;"]');
+                if (visibleCards.length > 0) {
+                    category.style.display = 'block';
+                } else {
+                    category.style.display = 'none';
+                }
+            });
+
+            noResults.style.display = hasResults ? 'none' : 'block';
+        });
+
+        // Back to top button
+        const backToTop = document.getElementById('backToTop');
+
+        window.addEventListener('scroll', function() {
+            if (window.pageYOffset > 300) {
+                backToTop.classList.add('visible');
+            } else {
+                backToTop.classList.remove('visible');
+            }
+        });
+
+        backToTop.addEventListener('click', function() {
+            window.scrollTo({ top: 0, behavior: 'smooth' });
+        });
+
+        // Handle hash navigation
+        function scrollToError() {
+            if (window.location.hash) {
+                let targetId = window.location.hash.substring(1);
+                
+                // If hash doesn't start with "error-", add it
+                if (!targetId.startsWith('error-') && /^\d+$/.test(targetId)) {
+                    targetId = 'error-' + targetId;
+                }
+                
+                const targetElement = document.getElementById(targetId);
+                if (targetElement) {
+                    setTimeout(() => {
+                        targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                        targetElement.style.background = 'rgba(0, 184, 148, 0.2)';
+                        targetElement.style.transition = 'background 0.3s ease';
+                        setTimeout(() => {
+                            targetElement.style.background = '';
+                        }, 2000);
+                    }, 100);
+                }
+            }
+        }
+
+        // Scroll on page load
+        scrollToError();
+
+        // Scroll when hash changes
+        window.addEventListener('hashchange', scrollToError);
+    </script>
+</body>
+
+</html>