mbkauthe 5.0.0 → 5.0.2

package/docs/reference/api/examples.md

@@ -0,0 +1,251 @@
+# Code Examples
+
+[Back to API index](../api.md) | [Back to docs index](../../README.md) | [Back to project README](../../../README.md)
+
+## Code Examples
+
+### Basic Integration
+
+```javascript
+import express from 'express';
+import mbkauthe, { validateSession } from 'mbkauthe';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+// Configure MBKAuthe
+process.env.mbkautheVar = JSON.stringify({
+  APP_NAME: process.env.APP_NAME,
+  SESSION_SECRET_KEY: process.env.SESSION_SECRET_KEY,
+  IS_DEPLOYED: process.env.IS_DEPLOYED,
+  DOMAIN: process.env.DOMAIN,
+  LOGIN_DB: process.env.LOGIN_DB,
+  MBKAUTH_TWO_FA_ENABLE: process.env.MBKAUTH_TWO_FA_ENABLE,
+  COOKIE_EXPIRE_TIME: process.env.COOKIE_EXPIRE_TIME || 2,
+  loginRedirectURL: '/dashboard'
+});
+
+const app = express();
+
+// Mount MBKAuthe routes
+app.use(mbkauthe);
+
+// Protected route
+app.get('/dashboard', sessVal, (req, res) => {
+  res.send(`Welcome ${req.session.user.username}!`);
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+---
+
+### Role-Based Access Control
+
+```javascript
+import { sessVal, roleChk, sessRole } from 'mbkauthe';
+
+// Method 1: Separate middleware
+app.get('/admin', sessVal, roleChk('SuperAdmin'), (req, res) => {
+    res.send('Admin panel');
+  }
+);
+
+// Method 2: Combined middleware
+app.get('/admin', sessRole('SuperAdmin'), (req, res) => {
+    res.send('Admin panel');
+  }
+);
+
+// Allow any role except Guest
+app.get('/content', sessVal, roleChk('Any', 'Guest'), (req, res) => {
+    res.send('Content for registered users');
+  }
+);
+
+// Multiple roles (using separate middleware)
+app.get('/moderator', sessVal, (req, res, next) => {
+    if (['SuperAdmin', 'NormalUser'].includes(req.session.user.role)) {
+      next();
+    } else {
+      res.status(403).send('Access denied');
+    }
+  },
+  (req, res) => {
+    res.send('Moderator panel');
+  }
+);
+```
+
+---
+
+### API Authentication
+
+```javascript
+import { authenticate } from 'mbkauthe';
+
+// Simple token authentication
+app.post('/api/webhook',  authenticate(process.env.WEBHOOK_SECRET), (req, res) => {
+    // Process webhook
+    res.json({ received: true });
+  }
+);
+
+// Admin API with token authentication
+app.post('/api/admin/terminate-sessions', authenticate(process.env.MAIN_SECRET_TOKEN),  async (req, res) => {
+    // Terminate all sessions
+    res.json({ success: true });
+  }
+);
+
+// Protected API endpoint (requires session)
+app.get('/api/user/profile',  sessVal, async (req, res) => {
+    const { username } = req.session.user;
+    
+    // Fetch user profile
+    const profile = await getUserProfile(username);
+    
+    res.json({ success: true, profile });
+  }
+);
+```
+
+---
+
+### Client-Side Login
+
+```javascript
+// Login form submission
+document.getElementById('loginForm').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  
+  const username = document.getElementById('username').value;
+  const password = document.getElementById('password').value;
+  
+  try {
+    const response = await fetch('/mbkauthe/api/login', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ username, password })
+    });
+    
+    const data = await response.json();
+    
+    if (data.success) {
+      if (data.twoFactorRequired) {
+        // Redirect to 2FA page
+        window.location.href = '/mbkauthe/2fa';
+      } else {
+        // Login successful, redirect
+        window.location.href = data.redirectUrl || '/dashboard';
+      }
+    } else {
+      alert(data.message || 'Login failed');
+    }
+  } catch (error) {
+    console.error('Login error:', error);
+    alert('An error occurred during login');
+  }
+});
+```
+
+---
+
+### Client-Side Logout
+
+```javascript
+async function logout() {
+  // Get CSRF token from page
+  const csrfToken = document.querySelector('[name="_csrf"]').value;
+  
+  try {
+    const response = await fetch('/mbkauthe/api/logout', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ _csrf: csrfToken })
+    });
+    
+    const data = await response.json();
+    
+    if (data.success) {
+      window.location.href = '/mbkauthe/login';
+    } else {
+      alert('Logout failed: ' + data.message);
+    }
+  } catch (error) {
+    console.error('Logout error:', error);
+  }
+}
+```
+
+---
+
+### Database Access
+
+```javascript
+import { dblogin } from 'mbkauthe';
+
+// Custom query using the database pool
+app.get('/api/users', sessVal, roleChk('SuperAdmin'), async (req, res) => {
+  try {
+    const result = await dblogin.query(
+      'SELECT id, "UserName", "Role", "Active" FROM "Users" ORDER BY id'
+    );
+    
+    res.json({ 
+      success: true, 
+      users: result.rows 
+    });
+  } catch (error) {
+    console.error('Database error:', error);
+    res.status(500).json({ 
+      success: false, 
+      message: 'Internal Server Error' 
+    });
+  }
+});
+```
+
+---
+
+### Error Handling
+
+```javascript
+// Custom error handler
+app.use((err, req, res, next) => {
+  console.error('Error:', err);
+  
+  if (err.code === 'EBADCSRFTOKEN') {
+    return res.status(403).json({ 
+      success: false, 
+      message: 'Invalid CSRF token' 
+    });
+  }
+  
+  res.status(500).json({ 
+    success: false, 
+    message: 'Internal Server Error' 
+  });
+});
+
+// 404 handler
+app.use((req, res) => {
+  res.status(404).render('Error/dError.handlebars', {
+    layout: false,
+    code: 404,
+    error: 'Not Found',
+    message: 'The requested page was not found.',
+    pagename: 'Home',
+    page: '/',
+  });
+});
+```
+
+---
+

package/docs/reference/api/middleware.md

@@ -0,0 +1,239 @@
+# Middleware
+
+[Back to API index](../api.md) | [Back to docs index](../../README.md) | [Back to project README](../../../README.md)
+
+## Middleware Reference
+
+### `validateSession`/`sessRole`
+
+Validates that the user has an active session.
+
+**Usage:**
+```javascript
+import { sessRole } from 'mbkauthe';
+
+app.get('/protected', sessRole, (req, res) => {
+  // User is authenticated
+  const user = req.session.user;
+  // user contains: { id, username, UserName, role, Role, sessionId }
+  res.send(`Welcome ${user.username}!`);
+});
+```
+
+**Behavior:**
+- Checks for active session in `req.session.user`
+- Attempts to restore session from `sessionId` cookie if session not found
+- Validates session against database
+- Checks if user account is still active
+- Verifies user is authorized for the current application
+- Redirects to login page if validation fails
+
+**JSON vs HTML error responses:**
+
+When `validateSession` fails, MBKAuthe will either render an HTML error/login page (browser flow) or return a JSON error response (API/AJAX flow). A request is treated as **JSON** when any of these are true:
+
+- URL/path starts with `/mbkauthe/api/` or `/api/`
+- `X-Requested-With: XMLHttpRequest`
+- `Accept` indicates JSON (e.g., `application/json`) and does not explicitly prefer `text/html`
+- `User-Agent` matches a non-browser client (e.g., `curl`, `wget`, `Postman`, `Insomnia`)
+- `User-Agent: json` (explicitly forces JSON responses)
+
+**Example (force JSON errors on a page route):**
+```bash
+curl -i -H "User-Agent: json" http://localhost:3000/mbkauthe/test
+```
+
+### reloadSessionUser(req, res)
+
+Use this helper when you need to refresh the values stored in `req.session.user` from the authoritative database record (for example, after a profile update that changes FullName, or when session expiration policies are updated).
+
+- Behavior:
+  - Validates the session against the database (sessionId, active)
+  - Updates `req.session.user` fields: `username`, `role`, `allowedApps`, `fullname`
+  - Uses cached `fullName` cookie if available; falls back to querying `profiledata`
+  - Syncs `username`, `fullName`, and `sessionId` cookies for client display
+  - If the session is invalid (sessionId mismatch, inactive account, or unauthorized), it destroys the session and clears cookies
+
+- Returns: `Promise<boolean>` — `true` if session was refreshed and still valid, `false` if session was invalidated or reload failed.
+
+- Example:
+```javascript
+import { reloadSessionUser } from 'mbkauthe';
+
+// After updating profile data
+app.post('/mbkauthe/api/update-profile', sessRole, async (req, res) => {
+  // ... update profiledata.FullName in DB ...
+  const refreshed = await reloadSessionUser(req, res);
+  if (!refreshed) {
+    return res.status(401).json({ success: false, message: 'Session invalidated' });
+  }
+  res.json({ success: true, fullname: req.session.user.fullname });
+});
+```
+
+**Session Object:**
+```javascript
+req.session.user = {
+  id: 1,                    // User ID
+  username: "john.doe",     // Username (login name)
+  fullname: "John Doe",     // Optional display name fetched from profiledata
+  role: "NormalUser",       // User role
+  sessionId: "abc123...",   // 64-char hex session ID
+}
+```
+
+**Session Cookie Sync:**
+- The middleware sets non-httpOnly cookies for client display:
+  - `username` — the login username (exposed for UI)
+  - `fullName` — the display name (falls back to username if not available)
+
+These cookies allow front-end UI to display a friendly name without making extra requests to the server.
+---
+
+### `checkRolePermission(requiredRole, notAllowed)`/`roleChk `
+
+Checks if the authenticated user has the required role.
+
+**Parameters:**
+- `requiredRole` (string) - Required role: `"SuperAdmin"`, `"NormalUser"`, `"Guest"`, `"member"`, or `"Any"`/`"any"`
+- `notAllowed` (string, optional) - Role that is explicitly not allowed
+
+**Usage:**
+```javascript
+import { sessVal, roleChk } from 'mbkauthe';
+
+// Only SuperAdmin can access
+app.get('/admin', sessVal, roleChk('SuperAdmin'), (req, res) => {
+  res.send('Admin panel');
+});
+
+// Any authenticated user except Guest
+app.get('/content', sessVal, roleChk('Any', 'Guest'), (req, res) => {
+  res.send('Protected content');
+});
+```
+
+**Behavior:**
+- Checks if user is authenticated first
+- Fetches user role from database
+- Returns 403 if user has `notAllowed` role
+- Returns 403 if user doesn't have `requiredRole` (unless role is "Any")
+- Calls `next()` if authorized
+
+---
+
+### `validateSessionAndRole(requiredRole, notAllowed)`/`sessRole`
+
+Combined middleware for session validation and role checking.
+
+**Parameters:**
+- `requiredRole` (string) - Required role
+- `notAllowed` (string, optional) - Role that is explicitly not allowed
+
+**Usage:**
+```javascript
+import { sessRole, roleChk } from 'mbkauthe';
+
+// Validate session AND check role in one middleware
+app.get('/moderator', sessRole('SuperAdmin'), (req, res) => {
+  res.send('Moderator panel');
+});
+```
+
+**Equivalent to:**
+```javascript
+app.get('/moderator', sessVal, roleChk('SuperAdmin'), (req, res) => {
+  res.send('Moderator panel');
+});
+```
+
+---
+
+### Strict validation helpers
+
+For endpoints that must reject API token-based authentication and only accept browser session cookies, MBKAuthe exposes two strict helpers:
+
+- `strictValidateSession`/`strictSessVal` — same as `validateSession`, but rejects requests that provide `Authorization` headers (API tokens) and returns `401` when a token is used.
+- `strictValidateSessionAndRole(requiredRole, notAllowed)`/`strictSessRole` — combined helper that behaves like `validateSessionAndRole` but enforces strict (cookie-only) authentication.
+
+**Usage examples:**
+```javascript
+import { strictSessVal, strictSessRole } from 'mbkauthe';
+
+// Accept only cookie sessions
+app.get('/sensitive', strictSessVal, (req, res) => {
+  res.send('Sensitive data');
+});
+
+// Validate session AND role, using cookie-only authentication
+app.get('/admin', strictSessRole('SuperAdmin'), (req, res) => {
+  res.send('Admin');
+});
+```
+
+---
+
+### Response Utilities
+
+MBKAuthe exports small helpers to assist with page rendering and context:
+
+- `getUserContext(req)` — returns a lightweight context object for templates: `{ userLoggedIn, isuserlogin, username, fullname, role, allowedApps }`.
+- `renderPage(req, res, fileLocation, layout = true, data = {})` — renders a template with the user/context merged into the data; returns a Promise and yields the typical Express `res.render` behavior.
+- `renderError(res, req, options)` — renders the standardized error page; note the signature is `(res, req, options)` and `options` follow the `ErrorRenderOptions` described in the types.
+
+**Example:**
+
+```javascript
+import { getUserContext, renderPage, renderError } from 'mbkauthe';
+
+app.get('/dashboard', (req, res) => {
+  const ctx = getUserContext(req);
+  return renderPage(req, res, 'info', true, { greeting: 'Hello', ...ctx });
+});
+
+app.get('/err', (req, res) => {
+  return renderError(res, req, {
+    layout: false,
+    code: 500,
+    error: "Internal Server Error",
+    message: "Simulated 500 Error",
+    details: "This is a simulated 500 error page for testing purposes.",
+    pagename: "Home",
+    page: "/mbkauthe/login",
+  });
+});
+```
+
+---
+
+### `authenticate(token)`
+
+API authentication middleware for server-to-server communication.
+
+**Parameters:**
+- `token` (string) - Secret token for authentication
+
+**Usage:**
+```javascript
+import { authenticate } from 'mbkauthe';
+
+app.post('/api/data', authenticate(process.env.API_TOKEN), (req, res) => {
+  res.json({ data: 'Protected API data' });
+});
+```
+
+**Headers Required:**
+```
+Authorization: Bearer your-secret-token
+```
+
+You can also send the raw token without the `Bearer` prefix.
+
+**Behavior:**
+- Checks `Authorization` header
+- Extracts the token (strips optional `Bearer` prefix)
+- Compares the provided token to the expected token using a timing-safe SHA-256 hash comparison
+- Returns 401 if token doesn't match
+
+---
+

package/docs/reference/api/operations.md

@@ -0,0 +1,52 @@
+# Operational Reference
+
+[Back to API index](../api.md) | [Back to docs index](../../README.md) | [Back to project README](../../../README.md)
+
+## Error Codes
+
+### HTTP Status Codes
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 200 | OK | Successful request |
+| 400 | Bad Request | Invalid input data |
+| 401 | Unauthorized | Authentication required or failed |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Server-side error |
+
+---
+
+## Security Best Practices
+
+1. **Always use HTTPS in production** - Set `IS_DEPLOYED=true` and ensure your server uses SSL/TLS
+2. **Keep SESSION_SECRET_KEY secure** - Use a strong, randomly generated key
+3. **Enable 2FA for sensitive applications** - Set `MBKAUTH_TWO_FA_ENABLE=true`
+4. **Validate all user input** - Never trust client-side data
+5. **Use rate limiting** - Already implemented for authentication endpoints
+6. **Keep dependencies updated** - Regularly update npm packages
+7. **Monitor for security vulnerabilities** - Use `npm audit`
+8. **Use prepared statements** - Prevent SQL injection (already implemented)
+9. **Implement proper logging** - Track authentication events
+10. **Regular security audits** - Review code and configurations
+
+---
+
+## Rate Limits
+
+| Endpoint | Limit | Window |
+|----------|-------|--------|
+| `/mbkauthe/api/login` | 8 requests | 1 minute |
+| `/mbkauthe/api/logout` | 10 requests | 1 minute |
+| `/mbkauthe/api/verify-2fa` | 5 requests | 1 minute |
+| `/mbkauthe/api/github/login` | 10 requests | 5 minutes |
+| `/mbkauthe/api/github/login/callback` | 10 requests | 5 minutes |
+| `/mbkauthe/login` | 8 requests | 1 minute |
+| `/mbkauthe/info` | 8 requests | 1 minute |
+| `/mbkauthe/test` | 8 requests | 1 minute |
+
+Rate limits are applied per IP address. Logged-in users are exempt from some rate limits (e.g., login page rate limit).
+
+---
+

package/docs/reference/api.md

@@ -0,0 +1,19 @@
+# API Reference
+
+[Back to docs index](../README.md) | [Back to project README](../../README.md)
+
+The API reference is split by responsibility so each source file stays focused and easy to review.
+
+## Sections
+
+- [Authentication and sessions](api/authentication.md) - session cookies, API tokens, and session lifetime.
+- [Endpoints](api/endpoints.md) - public routes, protected routes, multi-account routes, information routes, diagnostics, and OAuth routes.
+- [Middleware](api/middleware.md) - `sessVal`, `roleChk`, strict session helpers, render helpers, and token authentication.
+- [Code examples](api/examples.md) - Express integration, role checks, API auth, client login/logout, database access, and error handling.
+- [Operational reference](api/operations.md) - HTTP status codes, security best practices, and rate limits.
+
+## Related Reference
+
+- [Error codes](error-codes.md)
+- [Database guide](../guides/database.md)
+- [Configuration guide](../guides/configuration.md)

package/docs/{error-messages.md → reference/error-codes.md}

@@ -1,5 +1,7 @@
 # Error Messages & Codes
 
+[Back to docs index](../README.md) | [Back to project README](../../README.md)
+
 MBKAuthe provides a comprehensive error messaging system with standardized error codes and user-friendly messages.
 
 ## Overview

package/lib/createTable.js

@@ -12,7 +12,7 @@ async function main() {
 
   console.log("[mbkauthe] Starting schema creation...");
 
-  const schemaPath = path.resolve(__dirname, "../docs/db.sql");
+  const schemaPath = path.resolve(__dirname, "../docs/schema/db.sql");
 
   console.log(`[mbkauthe] Schema file: ${schemaPath}`);
 
@@ -118,4 +118,4 @@ async function main() {
   }
 }
 
-main();
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkauthe",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "MBKTech's reusable authentication system for Node.js applications.",
   "main": "index.js",
   "type": "module",
@@ -10,8 +10,8 @@
     "create-tables": "node lib/createTable.js",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-    "render:mermaid": "npx @mermaid-js/mermaid-cli -i docs/auth-flows.mmd -o docs/images/auth-flows.svg",
-    "render:mermaid:png": "npx @mermaid-js/mermaid-cli -i docs/auth-flows.mmd -o docs/images/auth-flows.png -s 20"
+    "render:mermaid": "npx @mermaid-js/mermaid-cli -i docs/diagrams/auth-flows.mmd -o docs/images/auth-flows.svg",
+    "render:mermaid:png": "npx @mermaid-js/mermaid-cli -i docs/diagrams/auth-flows.mmd -o docs/images/auth-flows.png -s 20"
   },
   "imports": {
     "#pool.js": "./lib/pool.js",
@@ -53,6 +53,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@mermaid-js/mermaid-cli": "^11.15.0",
     "bytes": "^3.1.2",
     "connect-pg-simple": "^10.0.0",
     "content-type": "^1.0.5",

package/docs/auth-processes.mmd

@@ -1,71 +0,0 @@
-sequenceDiagram
-    participant C as Client
-    participant S as Server
-    participant DB as Database
-
-    rect rgb(235, 245, 255)
-        Note over C, DB: Authentication Flow
-
-        C->>S: POST /login (username, password)
-        S->>S: Validate payload format
-        S->>DB: Query User & 2FA status
-        DB-->>S: User Data (Password Hash, 2FA Enabled)
-        S->>S: Compare Hash (PasswordEnc)
-
-        alt 2FA Enabled & Device Not Trusted
-            S-->>C: 200 (twoFactorRequired: true)
-
-            C->>S: POST /verify-2fa (TOTP Token)
-            S->>DB: Fetch TOTP Secret
-            DB-->>S: Secret Key
-            S->>S: Verify TOTP
-        end
-
-        Note over S, DB: completeLoginProcess
-
-        S->>DB: Delete old sessions & Prune max sessions
-        S->>S: Regenerate Session ID
-        S->>DB: Insert new Session row
-        S->>DB: Update Users.last_login
-
-        S-->>C: 200 Success (Set Encrypted Cookies)
-    end
-
-    rect rgb(245, 245, 245)
-        Note over C, DB: Request Authentication Middleware Flow
-
-        C->>S: Request + Auth (Cookie or Bearer Token)
-
-        rect rgb(240, 240, 240)
-            Note over S, DB: Token Path (API)
-
-            alt Header: Bearer mbk_token
-                S->>S: Hash Token
-                S->>DB: Query ApiTokens JOIN Users
-
-                alt Valid & Not Expired
-                    S->>DB: Update last_used
-                    S->>S: Authorize Scope
-                else Invalid/Expired
-                    S-->>C: 401 Unauthorized
-                end
-            end
-        end
-
-        rect rgb(220, 230, 250)
-            Note over S, DB: Session Path (Web)
-
-            alt Cookie: sessionId exists
-                S->>DB: Query Sessions JOIN Users
-                DB-->>S: Session Data + User Status
-
-                alt Session Valid & User Active
-                    S->>S: Sync Cookies & Update session.user
-                    S->>S: Proceed to Route
-                else Session Expired/User Inactive
-                    S->>S: Destroy Session & Clear Cookies
-                    S-->>C: 403 Forbidden
-                end
-            end
-        end
-    end