mbkauthe 4.8.2 → 4.8.4

package/README.md

@@ -11,7 +11,9 @@
   <img height="64px" src="./public/logo.png" alt="MBKAuthe" />
 </p>
 
-**MBKAuthe** is a production-ready authentication system for Node.js with Express and PostgreSQL. Features include secure login, 2FA, role-based access, OAuth (GitHub & Google), multi-session support, and multi-app user management.
+**MBKAuthe** is an open source package focused on login, authentication, and validating sessions for your desired apps in Node.js with Express and PostgreSQL. It provides secure login, session validation, 2FA, role/app access checks, OAuth (GitHub & Google), multi-session support, and related authentication flows.
+
+> **Note:** MBKAuthe is intentionally limited to authentication and session validation. The full user/permission/dashboard management system is a separate product called **MBKCore**, developed by MBKTech and not currently open source. Access to MBKCore is currently available only to the MBKTech team, and we may refine it and consider open sourcing it in the future.
 
 ## Todo
 - Currently, for every request to a protected page, a database query is made to retrieve authentication information (allowed apps, username, session ID, role, etc.). We should implement a caching mechanism to reduce this overhead, but also find a way to allow administrators to log users out and update permissions in near real-time.
@@ -54,15 +56,15 @@ Run [docs/db.sql](docs/db.sql) to create tables and a default SuperAdmin (`suppo
 
 ```javascript
 import express from 'express';
-import mbkauthe, { validateSession, checkRolePermission } from 'mbkauthe';
+import mbkauthe, { sessVal, roleChk } from 'mbkauthe';
 import dotenv from 'dotenv';
 dotenv.config();
 
 const app = express();
 app.use(mbkauthe);
 
-app.get('/dashboard', validateSession, (req, res) => res.send(`Welcome ${req.session.user.username}!`));
-app.get('/admin', validateSession, checkRolePermission(['SuperAdmin']), (req, res) => res.send('Admin Panel'));
+app.get('/dashboard', sessVal, (req, res) => res.send(`Welcome ${req.session.user.username}!`));
+app.get('/admin', sessVal, roleChk(['SuperAdmin']), (req, res) => res.send('Admin Panel'));
 
 app.listen(3000);
 ```
@@ -78,10 +80,27 @@ npm run dev
 ## 🔧 Core API
 
 - **Session Validation:** `validateSession`
-- **Role Check:** `checkRolePermission(['Role'])`
-- **Combined:** `validateSessionAndRole(['SuperAdmin', 'NormalUser'])`
+- **Role Check:** `checkRolePermission(['Role'])`/`roleChk(['Role'])`
+- **Combined:** `validateSessionAndRole(['SuperAdmin', 'NormalUser'])`/`sessRole(['SuperAdmin', 'NormalUser'])`
 - **API Token Auth:** `authenticate(process.env.API_TOKEN)`
 
+## 🧾 JSON Responses (HTML vs JSON)
+
+Most browser page routes render HTML on auth errors, while API/AJAX-style requests receive JSON error responses.
+
+MBKAuthe treats a request as **JSON** (and returns JSON errors) when any of the following apply:
+
+- 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` looks like a non-browser client (e.g., `curl`, `wget`, `Postman`)
+- `User-Agent: json` (explicitly forces JSON responses)
+
+**Example (force JSON errors):**
+```bash
+curl -i -H "User-Agent: json" http://localhost:3000/mbkauthe/test
+```
+
 ## 🧰 Diagnostics (dev only)
 
 These are only mounted when `process.env.env === "dev"`:

package/docs/api.md

@@ -57,12 +57,12 @@ Authorization: Bearer <your_api_token>
 
 **1. Backend Implementation (Express):**
 
-Even when using API tokens, the `validateSession` middleware hydrates `req.session.user` for consistency, allowing you to use the same route logic for both browser and API clients.
+Even when using API tokens, the `validateSession`/`sessVal` middleware hydrates `req.session.user` for consistency, allowing you to use the same route logic for both browser and API clients.
 
 ```javascript
-import { validateSession } from 'mbkauthe';
+import { sessVal } from 'mbkauthe';
 
-app.get('/api/protected-resource', validateSession, (req, res) => {
+app.get('/api/protected-resource', sessVal, (req, res) => {
   // Access user info populated from the token
   const user = req.session.user; // { id, username, role, ... }
   
@@ -1398,15 +1398,15 @@ Both GitHub and Google OAuth implementations include:
 
 ## Middleware Reference
 
-### `validateSession`
+### `validateSession`/`sessRole`
 
 Validates that the user has an active session.
 
 **Usage:**
 ```javascript
-import { validateSession } from 'mbkauthe';
+import { sessRole } from 'mbkauthe';
 
-app.get('/protected', validateSession, (req, res) => {
+app.get('/protected', sessRole, (req, res) => {
   // User is authenticated
   const user = req.session.user;
   // user contains: { id, username, UserName, role, Role, sessionId }
@@ -1422,6 +1422,21 @@ app.get('/protected', validateSession, (req, res) => {
 - 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).
@@ -1440,7 +1455,7 @@ Use this helper when you need to refresh the values stored in `req.session.user`
 import { reloadSessionUser } from 'mbkauthe';
 
 // After updating profile data
-app.post('/mbkauthe/api/update-profile', validateSession, async (req, res) => {
+app.post('/mbkauthe/api/update-profile', sessRole, async (req, res) => {
   // ... update profiledata.FullName in DB ...
   const refreshed = await reloadSessionUser(req, res);
   if (!refreshed) {
@@ -1469,7 +1484,7 @@ req.session.user = {
 These cookies allow front-end UI to display a friendly name without making extra requests to the server.
 ---
 
-### `checkRolePermission(requiredRole, notAllowed)`
+### `checkRolePermission(requiredRole, notAllowed)`/`roleChk `
 
 Checks if the authenticated user has the required role.
 
@@ -1479,15 +1494,15 @@ Checks if the authenticated user has the required role.
 
 **Usage:**
 ```javascript
-import { validateSession, checkRolePermission } from 'mbkauthe';
+import { sessVal, roleChk } from 'mbkauthe';
 
 // Only SuperAdmin can access
-app.get('/admin', validateSession, checkRolePermission('SuperAdmin'), (req, res) => {
+app.get('/admin', sessVal, roleChk('SuperAdmin'), (req, res) => {
   res.send('Admin panel');
 });
 
 // Any authenticated user except Guest
-app.get('/content', validateSession, checkRolePermission('Any', 'Guest'), (req, res) => {
+app.get('/content', sessVal, roleChk('Any', 'Guest'), (req, res) => {
   res.send('Protected content');
 });
 ```
@@ -1501,7 +1516,7 @@ app.get('/content', validateSession, checkRolePermission('Any', 'Guest'), (req,
 
 ---
 
-### `validateSessionAndRole(requiredRole, notAllowed)`
+### `validateSessionAndRole(requiredRole, notAllowed)`/`sessRole`
 
 Combined middleware for session validation and role checking.
 
@@ -1511,17 +1526,17 @@ Combined middleware for session validation and role checking.
 
 **Usage:**
 ```javascript
-import { validateSessionAndRole } from 'mbkauthe';
+import { sessRole, roleChk } from 'mbkauthe';
 
 // Validate session AND check role in one middleware
-app.get('/moderator', validateSessionAndRole('SuperAdmin'), (req, res) => {
+app.get('/moderator', sessRole('SuperAdmin'), (req, res) => {
   res.send('Moderator panel');
 });
 ```
 
 **Equivalent to:**
 ```javascript
-app.get('/moderator', validateSession, checkRolePermission('SuperAdmin'), (req, res) => {
+app.get('/moderator', sessVal, roleChk('SuperAdmin'), (req, res) => {
   res.send('Moderator panel');
 });
 ```
@@ -1603,12 +1618,15 @@ app.post('/api/data', authenticate(process.env.API_TOKEN), (req, res) => {
 
 **Headers Required:**
 ```
-Authorization: your-secret-token
+Authorization: Bearer your-secret-token
 ```
 
+You can also send the raw token without the `Bearer` prefix.
+
 **Behavior:**
 - Checks `Authorization` header
-- Compares with provided token
+- 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
 
 ---
@@ -1658,7 +1676,7 @@ const app = express();
 app.use(mbkauthe);
 
 // Protected route
-app.get('/dashboard', validateSession, (req, res) => {
+app.get('/dashboard', sessVal, (req, res) => {
   res.send(`Welcome ${req.session.user.username}!`);
 });
 
@@ -1672,12 +1690,12 @@ app.listen(3000, () => {
 ### Role-Based Access Control
 
 ```javascript
-import { validateSession, checkRolePermission, validateSessionAndRole } from 'mbkauthe';
+import { sessVal, roleChk, sessRole } from 'mbkauthe';
 
 // Method 1: Separate middleware
 app.get('/admin', 
-  validateSession, 
-  checkRolePermission('SuperAdmin'), 
+  sessVal, 
+  roleChk('SuperAdmin'), 
   (req, res) => {
     res.send('Admin panel');
   }
@@ -1685,7 +1703,7 @@ app.get('/admin',
 
 // Method 2: Combined middleware
 app.get('/admin', 
-  validateSessionAndRole('SuperAdmin'), 
+  sessRole('SuperAdmin'), 
   (req, res) => {
     res.send('Admin panel');
   }
@@ -1693,8 +1711,8 @@ app.get('/admin',
 
 // Allow any role except Guest
 app.get('/content', 
-  validateSession,
-  checkRolePermission('Any', 'Guest'),
+  sessVal,
+  roleChk('Any', 'Guest'),
   (req, res) => {
     res.send('Content for registered users');
   }
@@ -1702,7 +1720,7 @@ app.get('/content',
 
 // Multiple roles (using separate middleware)
 app.get('/moderator',
-  validateSession,
+  sessVal,
   (req, res, next) => {
     if (['SuperAdmin', 'NormalUser'].includes(req.session.user.role)) {
       next();
@@ -1743,7 +1761,7 @@ app.post('/api/admin/terminate-sessions',
 
 // Protected API endpoint (requires session)
 app.get('/api/user/profile', 
-  validateSession,
+  sessVal,
   async (req, res) => {
     const { username } = req.session.user;
     
@@ -1835,7 +1853,7 @@ async function logout() {
 import { dblogin } from 'mbkauthe';
 
 // Custom query using the database pool
-app.get('/api/users', validateSession, checkRolePermission('SuperAdmin'), async (req, res) => {
+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'

package/docs/auth-flows.mmd

@@ -1,10 +1,10 @@
 %%{init: {"themeVariables": {"fontFamily": "Arial, Helvetica, sans-serif", "primaryTextColor": "#333333", "secondaryTextColor": "#333333", "background": "#ffffff"}}}%%
 flowchart TD
-  A[Client POST /api/login - payload: username password redirect] --> B[Validate input length & format]
+  A[Client POST /mbkauthe/api/login - payload: username password redirect] --> B[Validate input length & format]
   B -->|invalid| Aerr[400 - missing/invalid]
   B --> C[Query Users and TwoFA status]
   C -->|no user| U404[401 - invalid credentials]
-  C --> D[Compare password - EncPass or raw]
+  C --> D[Compare password hash ]
   D -->|fail| P401[401 - incorrect password]
   D -->|ok| E[Check account Active and app authorization]
   E -->|inactive| I403[403 - account inactive]
@@ -27,7 +27,7 @@ flowchart TD
   Gtrust --> RESP
 
 %% 2FA
-  A2[Client POST /api/verify-2fa - payload: token trustDevice] --> B2[Ensure req.session.preAuthUser exists]
+  A2[Client POST /mbkauthe/api/verify-2fa - payload: token trustDevice] --> B2[Ensure req.session.preAuthUser exists]
   B2 -->|missing| Err401[401 - session not found]
   B2 --> C2[Validate token format - 6 digits]
   C2 --> D2[Fetch TwoFA secret from DB for username]
@@ -39,7 +39,7 @@ flowchart TD
 %% completeLoginProcess & validateSession kept separate for clarity
 
 %% Logout
-  L1[Client POST /api/logout] --> L2{req.session.user exists?}
+  L1[Client POST /mbkauthe/api/logout] --> L2{req.session.user exists?}
   L2 -->|no| Lerr[400 - Not logged in]
   L2 -->|yes| L3[Delete app Sessions row and session store row]
   L3 --> L4[removeAccountFromCookie]
@@ -47,7 +47,7 @@ flowchart TD
   L5 --> LResp[200 - logout successful]
 
 %% Account-sessions
-  AS1[Client GET /api/account-sessions] --> AS2[readAccountListFromCookie]
+  AS1[Client GET /mbkauthe/api/account-sessions] --> AS2[readAccountListFromCookie]
   AS2 -->|empty| ASresp[Return empty accounts and currentSessionId]
   AS2 --> AS3[For each stored account: validate each stored session via fetchActiveSession]
   AS3 -->|invalid| AS4[invalidate DB session and remove account from cookie]
@@ -55,7 +55,7 @@ flowchart TD
   AS5 --> ASresp2[Return accounts and currentSessionId]
 
 %% Switch session
-  SS1[Client POST /api/switch-session] --> SS2[Validate sessionId format]
+  SS1[Client POST /mbkauthe/api/switch-session] --> SS2[Validate sessionId format]
   SS2 -->|invalid| SSerr400[400 - Invalid session id]
   SS2 --> SS3[Check sessionId in readAccountListFromCookie]
   SS3 -->|missing| SSerr403[403 - Account not available on this device]
@@ -66,7 +66,7 @@ flowchart TD
   SS6 --> SSresp[200 - success with username fullName redirect]
 
 %% Logout-all
-  LA1[Client POST /api/logout-all] --> LA2[readAccountListFromCookie]
+  LA1[Client POST /mbkauthe/api/logout-all] --> LA2[readAccountListFromCookie]
   LA2 --> LA3[Collect sessionIds; add currentSession if present]
   LA3 --> LA4[Delete Sessions rows by ids]
   LA4 --> LA5[Delete session store row for current session]
@@ -74,9 +74,9 @@ flowchart TD
   LA6 --> LAresp[200 - All accounts logged out]
 
 %% OAuth
-  O1[Client GET /api/provider/login?redirect=...] --> O2[Server create CSRF token and save to session.oauthCsrfToken and oauthRedirect]
+  O1[Client GET /mbkauthe/api/github/login or /mbkauthe/api/google/login?redirect=...] --> O2[Server create CSRF token and save to session.oauthCsrfToken and oauthRedirect]
   O2 --> O3[passport.authenticate -> redirect to provider auth page]
-  O3 --> O4[Provider redirects back to /api/provider/login/callback with state and auth code]
+  O3 --> O4[Provider redirects back to /mbkauthe/api/github/login/callback or /mbkauthe/api/google/login/callback with state and auth code]
   O4 --> O5[validateOAuthCallback: compare state with session.oauthCsrfToken]
   O5 -->|invalid| Oerr[403 - CSRF mismatch]
   O5 -->|valid| O6[passport.authenticate -> locate linked user record]

package/docs/auth-processes.mmd

@@ -0,0 +1,71 @@
+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