mbkauthe 3.4.0 → 4.0.0

package/README.md

@@ -1,35 +1,28 @@
-# MBKAuthe - Authentication System for Node.js
+# MBKAuthe - Node.js Authentication System
 
 [![Version](https://img.shields.io/npm/v/mbkauthe.svg)](https://www.npmjs.com/package/mbkauthe)
 [![License](https://img.shields.io/badge/License-GPL--2.0-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Publish to npm](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/publish.yml)
-[![CodeQL Advanced](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/codeql.yml)
-
-
-<p align="center">
-  <img height="64px" src="./public/icon.svg" alt="MBK Chat Platform" />
-</p>
+[![Publish](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/publish.yml)
 
 <p align="center">
-  <img src="https://skillicons.dev/icons?i=nodejs,express,postgres" />
-  <img height="48px" src="https://handlebarsjs.com/handlebars-icon.svg" alt="Handlebars" />
+  <img height="64px" src="./public/icon.svg" alt="MBKAuthe" />
 </p>
 
-**MBKAuthe** is a production-ready authentication system for Node.js applications. Built with Express and PostgreSQL, it provides secure authentication, 2FA, role-based access, and OAuth integration (GitHub & Google) out of the box.
+**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.
 
 ## ✨ Key Features
 
-- 🔐 Secure password authentication with PBKDF2 hashing
-- 🔑 PostgreSQL session management with cross-subdomain support
-- 📱 Optional TOTP-based 2FA with trusted device memory
-- 🔄 OAuth integration (GitHub & Google)
-- 👥 Role-based access control (SuperAdmin, NormalUser, Guest)
-- 🎯 Multi-application user management
-- 🛡️ CSRF protection & advanced rate limiting
-- 🚀 Easy Express.js integration
-- 🎨 Customizable Handlebars templates
-- 🔒 Enhanced security with session fixation prevention
+- Secure password authentication (PBKDF2)
+- PostgreSQL session management
+- Multi-session support (configurable concurrent sessions per user)
+- Optional TOTP-based 2FA with trusted devices
+- OAuth login (GitHub & Google)
+- Role-based access: SuperAdmin, NormalUser, Guest
+- CSRF protection & rate limiting
+- Easy Express.js integration
+- Customizable Handlebars templates
+- Session fixation prevention
 
 ## 📦 Installation
 
@@ -39,49 +32,15 @@ npm install mbkauthe
 
 ## 🚀 Quick Start
 
-**1. Configure Environment (.env)**
+**1. Configure Environment**
 
-```env
-APP_NAME=your-app
-SESSION_SECRET_KEY=your-secret-key
-MAIN_SECRET_TOKEN=api-token
-IS_DEPLOYED=false
-DOMAIN=localhost
-LOGIN_DB=postgresql://user:pass@localhost:5432/db
-
-# Optional Features
-MBKAUTH_TWO_FA_ENABLE=false
-COOKIE_EXPIRE_TIME=2
-
-# OAuth Configuration (Optional)
-GITHUB_LOGIN_ENABLED=false
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
-
-GOOGLE_LOGIN_ENABLED=false
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-```
-
-**2. Set Up Database**
-
-```sql
-CREATE TYPE role AS ENUM ('SuperAdmin', 'NormalUser', 'Guest');
-
-CREATE TABLE "Users" (
-    id SERIAL PRIMARY KEY,
-    "UserName" VARCHAR(50) NOT NULL UNIQUE,
-    "Password" VARCHAR(61) NOT NULL,
-    "Role" role DEFAULT 'NormalUser',
-    "Active" BOOLEAN DEFAULT FALSE,
-    "AllowedApps" JSONB DEFAULT '["mbkauthe"]',
-    "SessionId" VARCHAR(213),
-    created_at TIMESTAMP DEFAULT NOW(),
-    updated_at TIMESTAMP DEFAULT NOW()
-);
+```bash
+Copy-Item .env.example .env
 ```
+See [docs/env.md](docs/env.md).
 
-See [docs/db.md](docs/db.md) for complete schemas.
+**2. Set Up Database**  
+Run [docs/db.sql](docs/db.sql) to create tables and a default SuperAdmin (`support` / `12345678`). Change the password immediately. See [docs/db.md](docs/db.md).
 
 **3. Integrate with Express**
 
@@ -89,295 +48,86 @@ See [docs/db.md](docs/db.md) for complete schemas.
 import express from 'express';
 import mbkauthe, { validateSession, checkRolePermission } from 'mbkauthe';
 import dotenv from 'dotenv';
-
 dotenv.config();
 
-// App-specific configuration (as JSON string)
-process.env.mbkautheVar = JSON.stringify({
-    APP_NAME: process.env.APP_NAME,
-    SESSION_SECRET_KEY: process.env.SESSION_SECRET_KEY,
-    Main_SECRET_TOKEN: process.env.MAIN_SECRET_TOKEN,
-    IS_DEPLOYED: process.env.IS_DEPLOYED,
-    DOMAIN: process.env.DOMAIN,
-    LOGIN_DB: process.env.LOGIN_DB,
-    loginRedirectURL: '/dashboard'
-});
-
-// Optional shared configuration (useful for shared OAuth credentials across multiple projects)
-process.env.mbkauthShared = JSON.stringify({
-    GITHUB_CLIENT_ID: process.env.GITHUB_CLIENT_ID,
-    GITHUB_CLIENT_SECRET: process.env.GITHUB_CLIENT_SECRET,
-    GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
-    GOOGLE_CLIENT_SECRET: process.env.GOOGLE_CLIENT_SECRET
-});
-
-// MBKAuth prioritizes values in mbkautheVar, then mbkauthShared, then built-in defaults.
-
 const app = express();
-
-// Mount authentication routes
 app.use(mbkauthe);
 
-// Protected routes
-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', validateSession, (req, res) => res.send(`Welcome ${req.session.user.username}!`));
+app.get('/admin', validateSession, checkRolePermission(['SuperAdmin']), (req, res) => res.send('Admin Panel'));
 
 app.listen(3000);
 ```
 
-
-## 🧪 Testing & Git Hooks
-
-MBKAuthe includes comprehensive test coverage for all authentication features. **A pre-commit hook is provided to ensure code quality:**
-
-### Pre-commit Hook (Automatic Test Runner)
-
-- Located at `scripts/pre-commit` and `scripts/pre-commit` (Node.js, cross-platform)
-- Starts the dev server, runs all tests, and blocks commits if any test fails
-- The dev server is automatically stopped after tests complete
-- Ensures you never commit code that breaks tests
-
-### Git Hook Setup
-
-Hooks are auto-configured every time you run `npm run dev`, `npm test`, or `npm run test:watch` (see `scripts/setup-hooks.js`).
-
-If you ever need to manually set up hooks:
-
-```bash
-node scripts/setup-hooks.js
-```
-
-### Running Tests
+## 🧪 Testing
 
 ```bash
-# Run all tests (auto-configures hooks)
 npm test
-
-# Run tests in watch mode (auto-configures hooks)
 npm run test:watch
-
-# Run with development flags (auto-configures hooks)
 npm run dev
 ```
 
-**Test Coverage:**
-- ✅ Authentication flows (login, 2FA, logout)
-- ✅ OAuth integration (GitHub)
-- ✅ Session management and security
-- ✅ Role-based access control
-- ✅ API endpoints and error handling
-- ✅ CSRF protection and rate limiting
-- ✅ Static asset serving
-
-## 📂 Architecture (v3.0)
-
-```
-lib/
-├── config/          # Configuration & security
-├── database/        # PostgreSQL pool
-├── utils/           # Errors & response helpers
-├── middleware/      # Auth & session middleware
-└── routes/          # Auth, OAuth, misc routes
-```
-
-**Key Improvements in v3.0:**
-- Modular structure with clear separation of concerns
-- Organized config, database, utils, middleware, and routes
-- Better maintainability and scalability
-
 ## 🔧 Core API
 
-### Middleware
-
-```javascript
-// Session validation
-app.get('/protected', validateSession, handler);
-
-// Role checking
-app.get('/admin', validateSession, checkRolePermission(['SuperAdmin']), handler);
+- **Session Validation:** `validateSession`
+- **Role Check:** `checkRolePermission(['Role'])`
+- **Combined:** `validateSessionAndRole(['SuperAdmin', 'NormalUser'])`
+- **API Token Auth:** `authenticate(process.env.API_TOKEN)`
 
-// Combined
-import { validateSessionAndRole } from 'mbkauthe';
-app.get('/mod', validateSessionAndRole(['SuperAdmin', 'NormalUser']), handler);
-
-// API token auth
-import { authenticate } from 'mbkauthe';
-app.post('/api/data', authenticate(process.env.API_TOKEN), handler);
-```
+## 🔐 Security
 
-### Built-in Routes
-
-**Authentication Routes:**
-- `GET /login`, `/signin` - Redirect to main login page
-- `GET /mbkauthe/login` - Login page (8/min rate limit)
-- `POST /mbkauthe/api/login` - Login endpoint (8/min rate limit)
-- `POST /mbkauthe/api/logout` - Logout endpoint (10/min rate limit)
-- `GET /mbkauthe/2fa` - 2FA verification page (if enabled)
-- `POST /mbkauthe/api/verify-2fa` - 2FA verification API (5/min rate limit)
-
-**OAuth Routes:**
-- `GET /mbkauthe/api/github/login` - GitHub OAuth initiation (10/5min rate limit)
-- `GET /mbkauthe/api/github/login/callback` - GitHub OAuth callback
-- `GET /mbkauthe/api/google/login` - Google OAuth initiation (10/5min rate limit)
-- `GET /mbkauthe/api/google/login/callback` - Google OAuth callback
-
-**Information & Utility Routes:**
-- `GET /mbkauthe/info`, `/mbkauthe/i` - Version & config info (8/min rate limit)
-- `GET /mbkauthe/ErrorCode` - Error code documentation
-- `GET /mbkauthe/test` - Test authentication status (8/min rate limit)
-
-**Static Asset Routes:**
-- `GET /mbkauthe/main.js` - Client-side JavaScript utilities
-- `GET /mbkauthe/bg.webp` - Background image for auth pages
-- `GET /icon.svg` - Application SVG icon (root level)
-- `GET /favicon.ico`, `/icon.ico` - Application favicon
-
-**Admin API Routes:**
-- `POST /mbkauthe/api/terminateAllSessions` - Terminate all sessions (admin only)
-
-## 🔐 Security Features
-
-- **Rate Limiting**: Login (8/min), Logout (10/min), 2FA (5/min), OAuth (10/5min), Admin (3/5min)
-- **CSRF Protection**: All state-changing routes protected with token validation
-- **Secure Cookies**: httpOnly, sameSite, secure in production
-- **Password Hashing**: PBKDF2 with 100k iterations
-- **Session Security**: PostgreSQL-backed, automatic cleanup, session fixation prevention
-- **OAuth Security**: State validation, token expiry handling, secure callback validation
+- Rate limiting, CSRF protection, secure cookies
+- Password hashing (PBKDF2, 100k iterations)
+- PostgreSQL-backed sessions with automatic cleanup
+- OAuth with state validation and secure callbacks
 
 ## 📱 Two-Factor Authentication
 
-Enable with `MBKAUTH_TWO_FA_ENABLE=true`:
-
-```sql
-CREATE TABLE "TwoFA" (
-    "UserName" VARCHAR(50) PRIMARY KEY REFERENCES "Users"("UserName"),
-    "TwoFAStatus" BOOLEAN NOT NULL,
-    "TwoFASecret" TEXT
-);
-```
-
-Users can mark devices as trusted to skip 2FA for configurable duration.
+Enable via `MBKAUTH_TWO_FA_ENABLE=true`. Trusted devices can skip 2FA for a set duration.
 
 ## 🔄 OAuth Integration
 
-### GitHub OAuth
-
-**Setup:**
-
-1. Create GitHub OAuth App with callback: `https://yourdomain.com/mbkauthe/api/github/login/callback`
-2. Configure environment:
-```env
-GITHUB_LOGIN_ENABLED=true
-GITHUB_CLIENT_ID=your_client_id
-GITHUB_CLIENT_SECRET=your_client_secret
-```
-3. Create table:
-```sql
-CREATE TABLE user_github (
-    id SERIAL PRIMARY KEY,
-    user_name VARCHAR(50) REFERENCES "Users"("UserName"),
-    github_id VARCHAR(255) UNIQUE,
-    github_username VARCHAR(255),
-    access_token VARCHAR(255),
-    created_at TIMESTAMP DEFAULT NOW()
-);
-```
-
-### Google OAuth
-
-**Setup:**
-
-1. Create Google OAuth 2.0 Client in [Google Cloud Console](https://console.cloud.google.com/)
-2. Add authorized redirect URI: `https://yourdomain.com/mbkauthe/api/google/login/callback`
-3. Configure environment:
-```env
-GOOGLE_LOGIN_ENABLED=true
-GOOGLE_CLIENT_ID=your_client_id
-GOOGLE_CLIENT_SECRET=your_client_secret
-```
-4. Create table:
-```sql
-CREATE TABLE user_google (
-    id SERIAL PRIMARY KEY,
-    user_name VARCHAR(50) REFERENCES "Users"("UserName"),
-    google_id VARCHAR(255) UNIQUE,
-    google_email VARCHAR(255),
-    access_token VARCHAR(255),
-    created_at TIMESTAMP DEFAULT NOW()
-);
-```
-
-**Note:** Users must link their OAuth accounts before they can use OAuth login.
+**GitHub / Google OAuth:** Configure apps and credentials via `.env` or `mbkautheVar`. Users must link accounts before login.
 
 ## 🎨 Customization
 
-**Redirect URL:**
-```javascript
-process.env.mbkautheVar = JSON.stringify({
-    // ...
-    loginRedirectURL: '/dashboard'
-});
-```
-
-**Custom Views:** Create in `views/` directory:
-- `loginmbkauthe.handlebars` - Login page
-- `2fa.handlebars` - 2FA page
-- `Error/dError.handlebars` - Error page
-
-**Database Access:**
-```javascript
-import { dblogin } from 'mbkauthe';
-const result = await dblogin.query('SELECT * FROM "Users"');
-```
+- **Redirect URL:** `mbkautheVar={"loginRedirectURL":"/dashboard"}`
+- **Custom Views:** `views/loginmbkauthe.handlebars`, `2fa.handlebars`, `Error/dError.handlebars`
+- **Database Access:** `import { dblogin } from 'mbkauthe'; const result = await dblogin.query('SELECT * FROM "Users"');`
 
 ## 🚢 Deployment
 
-**Production Checklist:**
-- ✅ Set `IS_DEPLOYED=true`
-- ✅ Use strong secrets for SESSION_SECRET_KEY and Main_SECRET_TOKEN
-- ✅ Enable HTTPS
-- ✅ Configure correct DOMAIN
-- ✅ Set appropriate COOKIE_EXPIRE_TIME
-- ✅ Use environment variables for all secrets
-
-**Vercel:**
-
-Tip: On Vercel you can set `mbkauthShared` at the project or team level to share common OAuth credentials across multiple deployments. MBKAuth will use values from `mbkautheVar` first and fall back to `mbkauthShared`.
-```json
-{
-    "version": 2,
-    "builds": [{ "src": "index.js", "use": "@vercel/node" }],
-    "routes": [{ "src": "/(.*)", "dest": "/index.js" }]
-}
-```
+Checklist for production:
+- `IS_DEPLOYED=true`
+- Strong secrets for SESSION_SECRET_KEY & Main_SECRET_TOKEN
+- HTTPS enabled
+- Correct DOMAIN & COOKIE_EXPIRE_TIME
+- Use environment variables for all secrets
+
+**Vercel:** Supports shared OAuth credentials via `mbkauthShared`.
 
 ## 📚 Documentation
 
-- [API Documentation](docs/api.md) - Complete API reference
-- [Database Guide](docs/db.md) - Schema details  
-- [Environment Config](docs/env.md) - Configuration options
-- [Error Messages](docs/error-messages.md) - Error code reference
+- [API Reference](docs/api.md)
+- [Database Schema](docs/db.md)
+- [Environment Config](docs/env.md)
+- [Error Codes](docs/error-messages.md)
 
 ## 📝 License
 
-GNU General Public License v2.0 - see [LICENSE](LICENSE)
+GPL v2.0 — see [LICENSE](LICENSE)
 
 ## 👨‍💻 Author
 
 **Muhammad Bin Khalid**  
 📧 [support@mbktech.org](mailto:support@mbktech.org) | [chmuhammadbinkhalid28@gmail.com](mailto:chmuhammadbinkhalid28@gmail.com)  
-🔗 [@MIbnEKhalid](https://github.com/MIbnEKhalid)
+🔗 [GitHub @MIbnEKhalid](https://github.com/MIbnEKhalid)
 
 ## 🔗 Links
 
-- [npm Package](https://www.npmjs.com/package/mbkauthe)
-- [GitHub Repository](https://github.com/MIbnEKhalid/mbkauthe)
-- [Issues & Support](https://github.com/MIbnEKhalid/mbkauthe/issues)
+- [npm](https://www.npmjs.com/package/mbkauthe)
+- [GitHub](https://github.com/MIbnEKhalid/mbkauthe)
+- [Support](https://github.com/MIbnEKhalid/mbkauthe/issues)
 
 ---
 

package/docs/api.md

@@ -38,7 +38,7 @@ When a user logs in, MBKAuthe creates a session and sets the following cookies:
 | Cookie Name | Description | HttpOnly | Secure | SameSite |
 |------------|-------------|----------|--------|----------|
 | `mbkauthe.sid` | Session identifier | ✓ | Auto* | lax |
-| `sessionId` | User session ID | ✓ | Auto* | lax |
+| `sessionId` | Opaque session token (backed by `Sessions` table) | ✓ | Auto* | lax |
 | `username` | Username | ✗ | Auto* | lax |
 
 \* `secure` flag is automatically set to `true` in production when `IS_DEPLOYED=true`
@@ -46,7 +46,7 @@ When a user logs in, MBKAuthe creates a session and sets the following cookies:
 ### Session Lifetime
 
 - Default: 2 days (configurable via `COOKIE_EXPIRE_TIME`)
-- Sessions are stored in PostgreSQL
+- Application sessions are stored in the `Sessions` table in PostgreSQL
 - Sessions persist across subdomains in production
 
 ---
@@ -194,6 +194,39 @@ fetch('/mbkauthe/api/login', {
 
 ---
 
+#### `GET /mbkauthe/api/checkSession`
+
+Checks whether the current session (cookie-based) is valid. Returns a JSON response suitable for AJAX/SPA checks.
+
+**Authentication:** Requires a valid session cookie set by `/mbkauthe/api/login`.
+
+**Success Response (200 OK):**
+```json
+{
+  "sessionValid": true,
+  "expiry": "2025-12-27T12:34:56.000Z"
+}
+```
+
+**Error Responses (examples):**
+- 200 Session invalid ( { "sessionValid": false, "expiry": null } )
+- 500 Internal Server Error (rare)
+
+**Example Request:**
+```javascript
+fetch('/mbkauthe/api/checkSession')
+  .then(res => res.json())
+  .then(data => {
+    if (data.sessionValid) {
+      // session active, expiry available in data.expiry
+    } else {
+      // not authenticated
+    }
+  });
+```
+
+---
+
 #### `GET /mbkauthe/2fa`
 
 Renders the Two-Factor Authentication verification page.
@@ -759,16 +792,51 @@ app.get('/protected', validateSession, (req, res) => {
 - Verifies user is authorized for the current application
 - Redirects to login page if validation fails
 
+### 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', validateSession, 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
+  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)`

package/docs/db.md

@@ -170,11 +170,6 @@ GITHUB_CLIENT_SECRET=your_github_client_secret
 
 The GitHub login feature is now fully integrated into your mbkauthe system and ready to use!
 
-
-
-
-
-
 ## Database structure
 
 [<- Back](README.md)
@@ -198,7 +193,7 @@ The GitHub login feature is now fully integrated into your mbkauthe system and r
   - `Role` (ENUM): The role of the user. Possible values: `SuperAdmin`, `NormalUser`, `Guest`.
   - `Active` (BOOLEAN): Indicates whether the user account is active.
   - `HaveMailAccount` (BOOLEAN)(optional): Indicates if the user has a linked mail account.
-  - `SessionId` (TEXT): The session ID associated with the user.
+  - (SessionId removed) The application now stores multiple concurrent sessions in the `Sessions` table.
   - `GuestRole` (JSONB): Stores additional guest-specific role information in binary JSON format.
   - `AllowedApps`(JSONB): Array of applications the user is authorized to access.
 
@@ -215,19 +210,32 @@ CREATE TABLE "Users" (
     "Active" BOOLEAN DEFAULT FALSE,
     "HaveMailAccount" BOOLEAN DEFAULT FALSE,
     "AllowedApps" JSONB DEFAULT '["mbkauthe", "portal"]',
-    "SessionId" VARCHAR(213),
     "created_at" TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
     "updated_at" TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
     "last_login" TIMESTAMP WITH TIME ZONE
 );
 
 -- Add indexes for performance optimization
-CREATE INDEX IF NOT EXISTS idx_users_sessionid ON "Users" (LOWER("SessionId"));
 CREATE INDEX IF NOT EXISTS idx_users_username ON "Users" ("UserName");
 CREATE INDEX IF NOT EXISTS idx_users_active ON "Users" ("Active");
 CREATE INDEX IF NOT EXISTS idx_users_role ON "Users" ("Role");
 CREATE INDEX IF NOT EXISTS idx_users_last_login ON "Users" (last_login);
-CREATE INDEX IF NOT EXISTS idx_users_id_sessionid_active_role ON "Users" ("id", LOWER("SessionId"), "Active", "Role");
+
+-- Application Sessions table (stores multiple concurrent sessions per user)
+-- Note: this is separate from the express-session store table named "session"
+CREATE TABLE "Sessions" (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- requires pgcrypto or uuid-ossp
+  "UserName" VARCHAR(50) NOT NULL REFERENCES "Users"("UserName") ON DELETE CASCADE,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  expires_at TIMESTAMP WITH TIME ZONE,
+    meta JSONB
+);
+
+-- Indexes optimized by username instead of numeric user id
+CREATE INDEX IF NOT EXISTS idx_sessions_username ON "Sessions" ("UserName");
+CREATE INDEX IF NOT EXISTS idx_sessions_user_created ON "Sessions" ("UserName", created_at);
+
+**Multi-session behavior:** MBKAuthe supports multiple concurrent application sessions per user. The maximum number of concurrent sessions is controlled by `mbkautheVar.MAX_SESSIONS_PER_USER` (default: 5). When a new session would exceed that limit, the system prunes the oldest session(s) for that user (ordered by `created_at`) to keep the count within the configured maximum.
 ```
 
 **Password Storage Notes:**
@@ -250,12 +258,10 @@ CREATE TABLE "session" (
     sid VARCHAR(33) PRIMARY KEY NOT NULL,
     sess JSONB NOT NULL,
     expire TimeStamp WITH TIME ZONE Not Null,
-    last_activity TimeStamp WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
 );
 
 -- Add indexes for performance optimization
 CREATE INDEX IF NOT EXISTS idx_session_expire ON "session" ("expire");
-CREATE INDEX IF NOT EXISTS idx_session_last_activity ON "session" (last_activity);
 CREATE INDEX IF NOT EXISTS idx_session_user_id ON "session" ((sess->'user'->>'id'));
 ```
 
@@ -286,7 +292,7 @@ CREATE INDEX IF NOT EXISTS idx_twofa_username_status ON "TwoFA" ("UserName", "Tw
 
   - `id` (INTEGER, auto-increment, primary key): Unique identifier for each trusted device.
   - `UserName` (VARCHAR): The username of the device owner (foreign key to Users).
-  - `DeviceToken` (VARCHAR): Unique token identifying the trusted device.
+  - `DeviceToken` (VARCHAR): **HMAC-SHA256 hash** of the device token (raw token is only sent to the client in an httpOnly cookie and **not** stored in plaintext).
   - `DeviceName` (VARCHAR): Optional friendly name for the device.
   - `UserAgent` (TEXT): Browser/client user agent string.
   - `IpAddress` (VARCHAR): IP address when device was trusted.
@@ -320,22 +326,22 @@ To add new users to the `Users` table, use the following SQL queries:
 
 **For Raw Password Storage (EncPass=false):**
 ```sql
-        INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
-        VALUES ('support', '12345678', 'SuperAdmin', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
+        INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount", "GuestRole")
+        VALUES ('support', '12345678', 'SuperAdmin', true, false, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
 
-        INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
-        VALUES ('test', '12345678', 'NormalUser', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
+        INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount", "GuestRole")
+        VALUES ('test', '12345678', 'NormalUser', true, false, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
 ```
 
 **For Encrypted Password Storage (EncPass=true):**
 ```sql
         -- Note: You'll need to hash the password using the hashPassword function
         -- Example with pre-hashed password (PBKDF2 with username as salt)
-        INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
-        VALUES ('support', 'your_hashed_password_here', 'SuperAdmin', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
+        INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "GuestRole")
+        VALUES ('support', 'your_hashed_password_here', 'SuperAdmin', true, false, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
 
-        INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
-        VALUES ('test', 'your_hashed_password_here', 'NormalUser', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
+        INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "GuestRole")
+        VALUES ('test', 'your_hashed_password_here', 'NormalUser', true, false, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
 ```
 
 **Configuration Notes:**