mbkauthe 3.3.0 → 3.5.0

package/README.md

@@ -1,4 +1,4 @@
-# MBKAuthe v3.2 - Authentication System for Node.js
+# MBKAuthe - Authentication System for Node.js
 
 [![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)
@@ -16,7 +16,7 @@
   <img height="48px" src="https://handlebarsjs.com/handlebars-icon.svg" alt="Handlebars" />
 </p>
 
-**MBKAuth v3.2** 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 applications. Built with Express and PostgreSQL, it provides secure authentication, 2FA, role-based access, and OAuth integration (GitHub & Google) out of the box.
 
 ## ✨ Key Features
 
@@ -92,6 +92,7 @@ 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,
@@ -102,6 +103,16 @@ process.env.mbkautheVar = JSON.stringify({
     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
@@ -335,6 +346,8 @@ const result = await dblogin.query('SELECT * FROM "Users"');
 - ✅ 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,

package/docs/api.md

@@ -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/env.md

@@ -1,455 +1,110 @@
 # Environment Configuration Guide
 
 [← Back to README](README.md)
+This document describes the environment variables MBKAuth expects and keeps brief usage notes for each parameter. Validation and defaults are implemented in `lib/config/index.js` (it parses `mbkautheVar`, applies optional `mbkauthShared` fallbacks, normalizes values, and throws on validation failures).
 
-This guide explains how to configure your MBKAuth application using environment variables. Create a `.env` file in your project root and set the following variables according to your deployment needs.
+## How configuration is provided
+- Primary payload: `mbkautheVar` — a JSON string with app-specific keys.
+- Optional shared defaults: `mbkauthShared` — a JSON string used only for missing or empty keys.
+- Example: `mbkautheVar={"APP_NAME":"mbkauthe", ...}`
 
 ---
 
-## 📱 Application Settings
-
-### App Name Configuration
-```env
-APP_NAME=mbkauthe
-```
-
-**Description:** Defines the application identifier used for user access control.
-
-- **Purpose:** Distinguishes this application from others in your ecosystem
-- **Security:** Users are restricted to apps they're authorized for via the `AllowedApp` column in the Users table
-- **Required:** Yes
-
----
-
-## 🔐 Session Management
-
-### Session Configuration
-```env
-Main_SECRET_TOKEN=your-secure-token-number
-SESSION_SECRET_KEY=your-secure-random-key-here
-IS_DEPLOYED=false
-DOMAIN=localhost
-EncPass=false
-```
-
-#### Main_SECRET_TOKEN
-**Description:** Primary authentication token for secure operations.
-
-- **Security:** Use a secure numeric or alphanumeric token
-- **Purpose:** Used for internal authentication and validation processes
-- **Format:** Numeric or string value
-- **Required:** Yes
-
-**Example:** `Main_SECRET_TOKEN=123456789`
-
-#### SESSION_SECRET_KEY
-**Description:** Cryptographic key for session security.
-
-- **Security:** Use a strong, randomly generated key (minimum 32 characters)
-- **Generation:** Generate securely at [Generate Secret](https://generate-secret.vercel.app/32)
-- **Example:** `SESSION_SECRET_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`
-- **Required:** Yes
-
-#### IS_DEPLOYED
-**Description:** Deployment environment flag that affects session behavior.
-
-**Values:**
-- `true` - Production/deployed environment
-  - Sessions work across all subdomains of your specified domain
-  - **Important:** Login will NOT work on `localhost` when set to `true`
-- `false` - Local development environment
-  - Sessions work on localhost for development
-
-**Default:** `false`
-
-#### DOMAIN
-**Description:** Your application's domain name.
-
-**Configuration:**
-- **Production:** Set to your actual domain (e.g., `mbktech.com`)
-- **Development:** Use `localhost` or set `IS_DEPLOYED=false`
-- **Subdomains:** When `IS_DEPLOYED=true`, sessions are shared across all subdomains
-
-**Examples:**
-```env
-# Production
-DOMAIN=yourdomain.com
-IS_DEPLOYED=true
-
-# Development
-DOMAIN=localhost
-IS_DEPLOYED=false
-```
-
-#### EncPass
-**Description:** Controls whether passwords are stored and validated in encrypted format.
-
-**Values:**
-- `true` - Use encrypted password validation
-  - Passwords are hashed using PBKDF2 with the username as salt
-  - Compares against `PasswordEnc` column in Users table
-- `false` - Use raw password validation (default)
-  - Passwords are stored and compared in plain text
-  - Compares against `Password` column in Users table
-
-**Default:** `false`
-
-**Security Note:** Setting `EncPass=true` is recommended for production environments as it provides better security by storing hashed passwords instead of plain text.
-
-**Examples:**
-```env
-# Production (recommended)
-EncPass=true
-
-# Development
-EncPass=false
-```
-
-**Database Implications:**
-- When `EncPass=true`: The system uses the `PasswordEnc` column
-- When `EncPass=false`: The system uses the `Password` column
-- Ensure your database schema includes the appropriate column based on your configuration
-
----
-
-## 🗄️ Database Configuration
-
-### PostgreSQL Connection
-```env
-LOGIN_DB=postgresql://username:password@host:port/database_name
-```
-
-**Description:** PostgreSQL database connection string for user authentication.
-
-**Format:** `postgresql://[username]:[password]@[host]:[port]/[database]`
-
-**Examples:**
-```env
-# Local database
-LOGIN_DB=postgresql://admin:password123@localhost:5432/mbkauth_db
-
-# Remote database
-LOGIN_DB=postgresql://user:pass@db.example.com:5432/production_db
-
-# With SSL (recommended for production)
-LOGIN_DB=postgresql://user:pass@host:5432/db?sslmode=require
-```
-
-**Required:** Yes
-
----
-
-## 🔒 Two-Factor Authentication (2FA)
-
-### 2FA Configuration
-```env
-MBKAUTH_TWO_FA_ENABLE=false
-```
-
-**Description:** Enables or disables Two-Factor Authentication for enhanced security.
-
-**Values:**
-- `true` - Enable 2FA (recommended for production)
-- `false` - Disable 2FA (default)
-
-**Note:** When enabled, users will need to configure an authenticator app (Google Authenticator, Authy, etc.) for login.
-
----
-
-## 🔄 Redirect Configuration
-
-### Login Redirect URL
-```env
-loginRedirectURL=/mbkauthe/test
-```
-
-**Description:** Specifies the URL path where users are redirected after successful authentication.
-
-- **Purpose:** Controls post-login navigation flow
-- **Format:** URL path (relative or absolute)
-- **Default:** `/` (root path if not specified)
-- **Required:** No (optional configuration)
-
-**Examples:**
-```env
-# Redirect to dashboard
-loginRedirectURL=/dashboard
-
-# Redirect to specific app section
-loginRedirectURL=/mbkauthe/test
-
-# Redirect to home page
-loginRedirectURL=/
-
-# Redirect to external URL (if supported)
-loginRedirectURL=https://example.com/app
-```
-
----
-
-## 🍪 Cookie Settings
-
-### Cookie Expiration
-```env
-COOKIE_EXPIRE_TIME=2
-```
-
-**Description:** Sets how long authentication cookies remain valid.
-
-- **Unit:** Days
-- **Default:** `2` days
-- **Range:** 1-30 days (recommended)
-- **Security:** Shorter periods are more secure but require more frequent logins
-
-**Examples:**
-```env
-COOKIE_EXPIRE_TIME=1   # 1 day (high security)
-COOKIE_EXPIRE_TIME=7   # 7 days (balanced)
-COOKIE_EXPIRE_TIME=30  # 30 days (convenience)
-```
-
-### Device Trust Duration
-```env
-DEVICE_TRUST_DURATION_DAYS=7
-```
-
-**Description:** Sets how long a device remains trusted after successful authentication.
-
-- **Unit:** Days
-- **Default:** `7` days
-- **Purpose:** Controls device recognition and trust persistence
-- **Range:** 1-365 days (recommended)
-- **Behavior:** Trusted devices may skip certain authentication steps (like 2FA) during this period
-
-**Examples:**
-```env
-DEVICE_TRUST_DURATION_DAYS=1   # 1 day (high security)
-DEVICE_TRUST_DURATION_DAYS=7   # 1 week (balanced)
-DEVICE_TRUST_DURATION_DAYS=30  # 30 days (convenience)
-```
-
----
-
-## 🔐 OAuth Authentication
-
-### GitHub OAuth Authentication
-
-#### GitHub Login Configuration
-```env
-GITHUB_LOGIN_ENABLED=false
-GITHUB_CLIENT_ID=your-github-client-id
-GITHUB_CLIENT_SECRET=your-github-client-secret
-```
-
-##### GITHUB_LOGIN_ENABLED
-**Description:** Enables or disables GitHub OAuth login functionality.
-
-**Values:**
-- `true` - Enable GitHub login (users can authenticate via GitHub)
-- `false` - Disable GitHub login (default)
-
-**Required:** Yes (if using GitHub authentication)
-
-##### GITHUB_CLIENT_ID
-**Description:** OAuth application client ID from GitHub.
-
-- **Purpose:** Identifies your application to GitHub's OAuth service
-- **Format:** Alphanumeric string provided by GitHub
-- **Setup:** Obtain from [GitHub Developer Settings](https://github.com/settings/developers)
-- **Required:** Yes (when `GITHUB_LOGIN_ENABLED=true`)
-
-**Example:** `GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8`
-
-##### GITHUB_CLIENT_SECRET
-**Description:** OAuth application client secret from GitHub.
-
-- **Purpose:** Authenticates your application with GitHub's OAuth service
-- **Security:** Keep this secret secure and never commit to version control
-- **Format:** Alphanumeric string provided by GitHub
-- **Setup:** Generated when creating OAuth app in GitHub Developer Settings
-- **Required:** Yes (when `GITHUB_LOGIN_ENABLED=true`)
-
-**Example:** `GITHUB_CLIENT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0`
-
-#### Setting Up GitHub OAuth
-
-1. **Create GitHub OAuth App:**
-   - Go to [GitHub Developer Settings](https://github.com/settings/developers)
-   - Click "New OAuth App"
-   - Fill in application details:
-     - **Application name:** Your app name
-     - **Homepage URL:** `https://yourdomain.com` (or `http://localhost:3000` for dev)
-     - **Authorization callback URL:** `https://yourdomain.com/mbkauthe/api/github/login/callback`
-   - Click "Register application"
-
-2. **Copy Credentials:**
-   - Copy the **Client ID**
-   - Generate and copy the **Client Secret**
-
-3. **Configure Environment:**
-   ```env
-   GITHUB_LOGIN_ENABLED=true
-   GITHUB_CLIENT_ID=your-copied-client-id
-   GITHUB_CLIENT_SECRET=your-copied-client-secret
-   ```
+## Parameters (short descriptions)
+
+- APP_NAME
+  - Description: Application identifier used for access control.
+  - Example: `"APP_NAME":"mbkauthe"`
+  - Required: Yes
+
+- Main_SECRET_TOKEN
+  - Description: Primary token used for internal auth and validations.
+  - Example: `"Main_SECRET_TOKEN":"my-secret-token"`
+  - Required: Yes
+
+- SESSION_SECRET_KEY
+  - Description: Cryptographic key for sessions/cookies. Use a long random string.
+  - Example: `"SESSION_SECRET_KEY":"<32+ random chars>"`
+  - Required: Yes
+
+- IS_DEPLOYED
+  - Description: Deployment mode flag; affects cookie domain and localhost behavior.
+  - Values: `true` / `false` / `f` (normalized to strings)
+  - Example: `"IS_DEPLOYED":"false"`
+  - Required: Yes
+
+- DOMAIN
+  - Description: App domain (e.g., `localhost` or `yourdomain.com`). Required when deployed.
+  - Example: `"DOMAIN":"localhost"`
+  - Required: Yes
+
+- LOGIN_DB
+  - Description: PostgreSQL connection string for auth (must start with `postgresql://` or `postgres://`).
+  - Example: `"LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth"`
+  - Required: Yes
+
+- MBKAUTH_TWO_FA_ENABLE
+  - Description: Enable Two-Factor Authentication.
+  - Values: `true` / `false` / `f`
+  - Example: `"MBKAUTH_TWO_FA_ENABLE":"true"`
+  - Required: Yes
+
+- EncPass
+  - Description: When `true`, use hashed password column (`PasswordEnc`) instead of plain `Password`.
+  - Default: `false` (recommended `true` in production)
+  - Example: `"EncPass":"true"`
+  - Required: No
+
+- COOKIE_EXPIRE_TIME
+  - Description: Session cookie lifetime (days).
+  - Default: `2`
+  - Example: `"COOKIE_EXPIRE_TIME":7`
+  - Required: No
+
+- DEVICE_TRUST_DURATION_DAYS
+  - Description: Days a device remains trusted (skips some auth steps).
+  - Default: `7`
+  - Example: `"DEVICE_TRUST_DURATION_DAYS":30`
+  - Required: No
+
+- loginRedirectURL
+  - Description: Post-login redirect path.
+  - Default: `/dashboard`
+  - Example: `"loginRedirectURL":"/dashboard"`
+  - Required: No
+
+- GITHUB_LOGIN_ENABLED / GOOGLE_LOGIN_ENABLED
+  - Description: Enable OAuth providers.
+  - Default: `false`
+  - If `true`, corresponding `*_CLIENT_ID` and `*_CLIENT_SECRET` are required.
+
+- GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET / GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
+  - Description: OAuth credentials (put in `mbkautheVar` preferred, or `mbkauthShared`).
+  - Required when provider enabled.
 
 ---
 
-### Google OAuth Authentication
+## Quick examples
+Development (.env):
 
-#### Google Login Configuration
 ```env
-GOOGLE_LOGIN_ENABLED=false
-GOOGLE_CLIENT_ID=your-google-client-id
-GOOGLE_CLIENT_SECRET=your-google-client-secret
+mbkautheVar={"APP_NAME":"mbkauthe","Main_SECRET_TOKEN":"dev-token","SESSION_SECRET_KEY":"dev-secret","IS_DEPLOYED":"false","DOMAIN":"localhost","EncPass":"false","LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth_dev","MBKAUTH_TWO_FA_ENABLE":"false"}
+mbkauthShared={"GITHUB_LOGIN_ENABLED":"false"}
 ```
 
-##### GOOGLE_LOGIN_ENABLED
-**Description:** Enables or disables Google OAuth login functionality.
-
-**Values:**
-- `true` - Enable Google login (users can authenticate via Google)
-- `false` - Disable Google login (default)
-
-**Required:** Yes (if using Google authentication)
-
-##### GOOGLE_CLIENT_ID
-**Description:** OAuth 2.0 client ID from Google Cloud Console.
-
-- **Purpose:** Identifies your application to Google's OAuth service
-- **Format:** String ending in `.apps.googleusercontent.com`
-- **Setup:** Obtain from [Google Cloud Console](https://console.cloud.google.com/)
-- **Required:** Yes (when `GOOGLE_LOGIN_ENABLED=true`)
-
-**Example:** `GOOGLE_CLIENT_ID=123456789-abc123def456.apps.googleusercontent.com`
-
-##### GOOGLE_CLIENT_SECRET
-**Description:** OAuth 2.0 client secret from Google Cloud Console.
-
-- **Purpose:** Authenticates your application with Google's OAuth service
-- **Security:** Keep this secret secure and never commit to version control
-- **Format:** Alphanumeric string provided by Google
-- **Setup:** Generated when creating OAuth credentials in Google Cloud Console
-- **Required:** Yes (when `GOOGLE_LOGIN_ENABLED=true`)
-
-**Example:** `GOOGLE_CLIENT_SECRET=GOCSPX-abc123def456ghi789jkl012mno`
-
-#### Setting Up Google OAuth
-
-1. **Create Google Cloud Project:**
-   - Go to [Google Cloud Console](https://console.cloud.google.com/)
-   - Create a new project or select an existing one
-   - Enable the Google+ API (or People API)
-
-2. **Configure OAuth Consent Screen:**
-   - Navigate to "OAuth consent screen" in the sidebar
-   - Choose "External" user type (or "Internal" for Google Workspace)
-   - Fill in required app information
-   - Add your domain to authorized domains
-   - Save and continue
-
-3. **Create OAuth Credentials:**
-   - Navigate to "Credentials" in the sidebar
-   - Click "Create Credentials" > "OAuth 2.0 Client ID"
-   - Choose "Web application" as application type
-   - Add authorized JavaScript origins:
-     - `https://yourdomain.com`
-     - `http://localhost:3000` (for development)
-   - Add authorized redirect URIs:
-     - `https://yourdomain.com/mbkauthe/api/google/login/callback`
-     - `http://localhost:3000/mbkauthe/api/google/login/callback` (for development)
-   - Click "Create"
-
-4. **Copy Credentials:**
-   - Copy the **Client ID**
-   - Copy the **Client Secret**
+Production (short):
 
-5. **Configure Environment:**
-   ```env
-   GOOGLE_LOGIN_ENABLED=true
-   GOOGLE_CLIENT_ID=your-copied-client-id
-   GOOGLE_CLIENT_SECRET=your-copied-client-secret
-   ```
-
-### OAuth Security Notes
-
-- Use separate OAuth apps for development and production environments
-- Rotate client secrets periodically
-- Never expose client secrets in client-side code
-- Ensure callback URLs match exactly with OAuth provider configuration
-- Users must link their OAuth accounts before they can use OAuth login
-
----
-
-## 🚀 Quick Setup Examples
-
-### Development Environment
-```env
-# .env file for local development
-APP_NAME=mbkauthe
-Main_SECRET_TOKEN=dev-token-123
-SESSION_SECRET_KEY=dev-secret-key-change-in-production
-IS_DEPLOYED=false
-DOMAIN=localhost
-EncPass=false
-LOGIN_DB=postgresql://admin:password@localhost:5432/mbkauth_dev
-MBKAUTH_TWO_FA_ENABLE=false
-COOKIE_EXPIRE_TIME=7
-DEVICE_TRUST_DURATION_DAYS=7
-loginRedirectURL=/dashboard
-GITHUB_LOGIN_ENABLED=false
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
-```
-
-### Production Environment
 ```env
-# .env file for production deployment
-APP_NAME=mbkauthe
-Main_SECRET_TOKEN=your-secure-production-token
-SESSION_SECRET_KEY=your-super-secure-production-key-here
-IS_DEPLOYED=true
-DOMAIN=yourdomain.com
-EncPass=true
-LOGIN_DB=postgresql://dbuser:securepass@prod-db.example.com:5432/mbkauth_prod
-MBKAUTH_TWO_FA_ENABLE=true
-COOKIE_EXPIRE_TIME=2
-DEVICE_TRUST_DURATION_DAYS=7
-loginRedirectURL=/dashboard
-GITHUB_LOGIN_ENABLED=false
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
+mbkautheVar={"APP_NAME":"mbkauthe","Main_SECRET_TOKEN":"prod-token","SESSION_SECRET_KEY":"prod-secret","IS_DEPLOYED":"true","DOMAIN":"yourdomain.com","EncPass":"true","LOGIN_DB":"postgresql://dbuser:secure@db:5432/mbkauth_prod","MBKAUTH_TWO_FA_ENABLE":"true"}
 ```
 
 ---
 
-## ⚠️ Important Security Notes
-
-1. **Never commit your `.env` file** to version control
-2. **Use strong, unique secrets** for production environments
-3. **Enable HTTPS** when `IS_DEPLOYED=true`
-4. **Regularly rotate** your `SESSION_SECRET_KEY`
-5. **Use environment-specific databases** (separate dev/prod databases)
-6. **Enable 2FA** for production environments
-
----
-
-## 🔧 Troubleshooting
-
-### Common Issues
-
-**Login not working on localhost:**
-- Ensure `IS_DEPLOYED=false` for local development
-- Check that `DOMAIN=localhost`
-
-**Session not persisting:**
-- Verify `SESSION_SECRET_KEY` is set and consistent
-- Check cookie settings in your browser
-
-**Database connection errors:**
-- Verify database credentials and connection string format
-- Ensure database server is running and accessible
+## Rules & best practices
+- Boolean-like fields: use `"true"`, `"false"`, or `"f"` (the parser accepts booleans too and normalizes to strings).
+- Numeric fields: must be positive numbers (e.g., `COOKIE_EXPIRE_TIME`, `DEVICE_TRUST_DURATION_DAYS`).
+- `LOGIN_DB` must start with `postgresql://` or `postgres://`.
+- Never commit `.env` to source control and use HTTPS in production (when `IS_DEPLOYED=true`).
+- Use a >=32-char `SESSION_SECRET_KEY` and rotate secrets regularly.
 
-**2FA issues:**
-- Confirm authenticator app time is synchronized
-- Verify `MBKAUTH_TWO_FA_ENABLE` setting matches your setup
+For the exact validation messages and default application, consult `lib/config/index.js` (it will throw a comprehensive error if validation fails at startup).

package/index.d.ts

@@ -12,6 +12,7 @@ declare global {
       user?: {
         username: string;
         role: 'SuperAdmin' | 'NormalUser' | 'Guest';
+        fullname?: string;
       };
       userRole?: 'SuperAdmin' | 'NormalUser' | 'Guest';
     }
@@ -20,6 +21,7 @@ declare global {
       user?: {
         id: number;
         username: string;
+        fullname?: string;
         role: 'SuperAdmin' | 'NormalUser' | 'Guest';
         sessionId: string;
         allowedApps?: string[];
@@ -75,6 +77,7 @@ declare module 'mbkauthe' {
   export interface SessionUser {
     id: number;
     username: string;
+    fullname?: string;
     role: UserRole;
     sessionId: string;
     allowedApps?: string[];
@@ -209,6 +212,10 @@ declare module 'mbkauthe' {
 
   export function authenticate(token: string): AuthMiddleware;
 
+  // Reload session user values from DB and refresh cookies.
+  // Returns true when session is refreshed and valid, false if session invalidated.
+  export function reloadSessionUser(req: Request, res: Response): Promise<boolean>;
+
   // Utility Functions
   export function renderError(
     res: Response,

package/index.js

@@ -89,7 +89,10 @@ if (process.env.test !== "dev") {
     await checkVersion();
 }
 
-export { validateSession, checkRolePermission, validateSessionAndRole, authenticate } from "./lib/middleware/auth.js";
+export {
+    validateSession, validateApiSession, checkRolePermission,
+    validateSessionAndRole, authenticate, reloadSessionUser
+} from "./lib/middleware/auth.js";
 export { renderError } from "./lib/utils/response.js";
 export { dblogin } from "./lib/database/pool.js";
 export { ErrorCodes, ErrorMessages, getErrorByCode, createErrorResponse, logError } from "./lib/utils/errors.js";

package/lib/config/cookies.js

@@ -46,6 +46,7 @@ export const clearSessionCookies = (res) => {
     res.clearCookie("mbkauthe.sid", cachedClearCookieOptions);
     res.clearCookie("sessionId", cachedClearCookieOptions);
     res.clearCookie("username", cachedClearCookieOptions);
+    res.clearCookie("fullName", cachedClearCookieOptions);
     res.clearCookie("device_token", cachedClearCookieOptions);
 };
 

package/lib/config/index.js

@@ -28,37 +28,81 @@ function validateConfiguration() {
         throw new Error(`[mbkauthe] Configuration Error:\n  - ${errors.join('\n  - ')}`);
     }
 
-    // Parse and validate oAuthVar (optional fallback for OAuth settings)
-    let oAuthVar = null;
+    // Parse and validate mbkauthShared (optional fallback for shared settings)
+    let mbkauthShared = null;
     try {
-        if (process.env.oAuthVar) {
-            oAuthVar = JSON.parse(process.env.oAuthVar);
-            if (oAuthVar && typeof oAuthVar !== 'object') {
-                console.warn('[mbkauthe] oAuthVar is not a valid object, ignoring it');
-                oAuthVar = null;
+        if (process.env.mbkauthShared) {
+            mbkauthShared = JSON.parse(process.env.mbkauthShared);
+            if (mbkauthShared && typeof mbkauthShared !== 'object') {
+                console.warn('[mbkauthe] mbkauthShared is not a valid object, ignoring it');
+                mbkauthShared = null;
             } else {
-                console.log('[mbkauthe] oAuthVar detected and parsed successfully');
+                console.log('[mbkauthe] mbkauthShared detected and parsed successfully');
             }
         }
     } catch (error) {
-        console.warn('[mbkauthe] Invalid JSON in process.env.oAuthVar, ignoring it');
-        oAuthVar = null;
-    }
+        console.warn('[mbkauthe] Invalid JSON in process.env.mbkauthShared, ignoring it');
+        mbkauthShared = null;
+    }
+
+    // Merge fallback settings: for any key missing or empty in mbkautheVar, check mbkauthShared
+    const applyFallback = (source, sourceName) => {
+        if (!source) return;
+        Object.keys(source).forEach(key => {
+            const val = source[key];
+            if ((mbkautheVar[key] === undefined || (typeof mbkautheVar[key] === 'string' && mbkautheVar[key].trim() === '')) &&
+                val !== undefined && !(typeof val === 'string' && val.trim() === '')) {
+                mbkautheVar[key] = val;
+                console.log(`[mbkauthe] Using ${key} from ${sourceName}`);
+            }
+        });
+    };
+
+    applyFallback(mbkauthShared, 'mbkauthShared');
 
-    // Merge OAuth settings: use oAuthVar as fallback if values not in mbkautheVar
-    const oAuthKeys = [
-        'GITHUB_LOGIN_ENABLED', 'GITHUB_CLIENT_ID', 'GITHUB_CLIENT_SECRET',
-        'GOOGLE_LOGIN_ENABLED', 'GOOGLE_CLIENT_ID', 'GOOGLE_CLIENT_SECRET'
+    // Ensure specific keys are checked in mbkautheVar first, then mbkauthShared, then apply config defaults
+    const keysToCheck = [
+        "APP_NAME","DEVICE_TRUST_DURATION_DAYS","EncPass","Main_SECRET_TOKEN","SESSION_SECRET_KEY","IS_DEPLOYED",
+        "LOGIN_DB","MBKAUTH_TWO_FA_ENABLE","COOKIE_EXPIRE_TIME","DOMAIN","loginRedirectURL",
+        "GITHUB_LOGIN_ENABLED","GITHUB_CLIENT_ID","GITHUB_CLIENT_SECRET","GOOGLE_LOGIN_ENABLED","GOOGLE_CLIENT_ID","GOOGLE_CLIENT_SECRET"
     ];
-    
-    if (oAuthVar) {
-        oAuthKeys.forEach(key => {
-            if ((!mbkautheVar[key] || (typeof mbkautheVar[key] === 'string' && mbkautheVar[key].trim() === '')) && oAuthVar[key]) {
-                mbkautheVar[key] = oAuthVar[key];
-                console.log(`[mbkauthe] Using ${key} from oAuthVar`);
+
+    const defaults = {
+        DEVICE_TRUST_DURATION_DAYS: 7,
+        EncPass: 'false',
+        IS_DEPLOYED: 'false',
+        MBKAUTH_TWO_FA_ENABLE: 'false',
+        COOKIE_EXPIRE_TIME: 2,
+        loginRedirectURL: '/dashboard',
+        GITHUB_LOGIN_ENABLED: 'false',
+        GOOGLE_LOGIN_ENABLED: 'false'
+    };
+
+    keysToCheck.forEach(key => {
+        const current = mbkautheVar[key];
+        const isEmpty = current === undefined || (typeof current === 'string' && current.trim() === '');
+        if (isEmpty) {
+            if (mbkauthShared && mbkauthShared[key] !== undefined && !(typeof mbkauthShared[key] === 'string' && mbkauthShared[key].trim() === '')) {
+                mbkautheVar[key] = mbkauthShared[key];
+                console.log(`[mbkauthe] Using ${key} from mbkauthShared`);
+            } else if (defaults[key] !== undefined) {
+                mbkautheVar[key] = defaults[key];
+                console.log(`[mbkauthe] Using default value for ${key}`);
             }
-        });
-    }
+        }
+    });
+
+    // Normalize boolean-like values to consistent lowercase 'true'/'false' strings
+    ['GITHUB_LOGIN_ENABLED','GOOGLE_LOGIN_ENABLED','MBKAUTH_TWO_FA_ENABLE','IS_DEPLOYED','EncPass'].forEach(k => {
+        const val = mbkautheVar[k];
+        if (typeof val === 'boolean') {
+            mbkautheVar[k] = val ? 'true' : 'false';
+        } else if (typeof val === 'string') {
+            const norm = val.trim().toLowerCase();
+            // Accept 'f' as shorthand for false but normalize it to 'false'
+            mbkautheVar[k] = (norm === 'f') ? 'false' : norm;
+        }
+    });
 
     // Validate required keys
     // COOKIE_EXPIRE_TIME is not required but if provided must be valid, COOKIE_EXPIRE_TIME by default is 2 days
@@ -73,7 +117,7 @@ function validateConfiguration() {
     });
 
     // Validate IS_DEPLOYED value
-    if (mbkautheVar.IS_DEPLOYED && !['true', 'false', 'f'].includes(mbkautheVar.IS_DEPLOYED)) {
+    if (mbkautheVar.IS_DEPLOYED && !['true', 'false', 'f'].includes((mbkautheVar.IS_DEPLOYED + '').toLowerCase())) {
         errors.push("mbkautheVar.IS_DEPLOYED must be either 'true' or 'false' or 'f'");
     }
 

package/lib/middleware/auth.js

@@ -1,7 +1,7 @@
 import { dblogin } from "../database/pool.js";
 import { mbkautheVar } from "../config/index.js";
 import { renderError } from "../utils/response.js";
-import { clearSessionCookies } from "../config/cookies.js";
+import { clearSessionCookies, cachedCookieOptions } from "../config/cookies.js";
 
 async function validateSession(req, res, next) {
   if (!req.session.user) {
@@ -97,6 +97,160 @@ async function validateSession(req, res, next) {
   }
 }
 
+/**
+ * API-friendly session validation middleware
+ * Returns JSON error responses instead of rendering pages
+ */
+async function validateApiSession(req, res, next) {
+  if (!req.session.user) {
+    return res.status(401).json(createErrorResponse(401, ErrorCodes.SESSION_NOT_FOUND));
+  }
+
+  try {
+    const { id, sessionId, role, allowedApps } = req.session.user;
+
+    // Defensive checks for sessionId and allowedApps
+    if (!sessionId) {
+      console.warn(`[mbkauthe] Missing sessionId for user "${req.session.user.username}"`);
+      req.session.destroy();
+      clearSessionCookies(res);
+      return res.status(401).json(createErrorResponse(401, ErrorCodes.SESSION_EXPIRED));
+    }
+
+    // Normalize sessionId to lowercase for consistent comparison
+    const normalizedSessionId = sessionId.toLowerCase();
+
+    // Single optimized query to validate session and get role
+    const query = `SELECT "SessionId", "Active", "Role" FROM "Users" WHERE "id" = $1`;
+    const result = await dblogin.query({ name: 'validate-user-session-for-api', text: query, values: [id] });
+
+    const dbSessionId = result.rows.length > 0 && result.rows[0].SessionId ? String(result.rows[0].SessionId).toLowerCase() : null;
+    if (!dbSessionId || dbSessionId !== normalizedSessionId) {
+      if (result.rows.length > 0 && !result.rows[0].SessionId) {
+        console.warn(`[mbkauthe] DB sessionId is null for user "${req.session.user.username}"`);
+      }
+      console.log(`[mbkauthe] Session invalidated for user "${req.session.user.username}"`);
+      req.session.destroy();
+      clearSessionCookies(res);
+      return res.status(401).json(createErrorResponse(401, ErrorCodes.SESSION_INVALID));
+    }
+
+    if (!result.rows[0].Active) {
+      console.log(`[mbkauthe] Account is inactive for user "${req.session.user.username}"`);
+      req.session.destroy();
+      clearSessionCookies(res);
+      return res.status(401).json(createErrorResponse(401, ErrorCodes.ACCOUNT_INACTIVE));
+    }
+
+    if (role !== "SuperAdmin") {
+      // If allowedApps is not provided or not an array, treat as no access
+      const hasAllowedApps = Array.isArray(allowedApps) && allowedApps.length > 0;
+      if (!hasAllowedApps || !allowedApps.some(app => app && app.toLowerCase() === mbkautheVar.APP_NAME.toLowerCase())) {
+        console.warn(`[mbkauthe] User \"${req.session.user.username}\" is not authorized to use the application \"${mbkautheVar.APP_NAME}\"`);
+        req.session.destroy();
+        clearSessionCookies(res);
+        return res.status(401).json(createErrorResponse(401, ErrorCodes.APP_NOT_AUTHORIZED));
+      }
+    }
+
+    // Store user role in request for checkRolePermission to use
+    req.userRole = result.rows[0].Role;
+
+    next();
+  } catch (err) {
+    console.error("[mbkauthe] API session validation error:", err);
+    return res.status(500).json(createErrorResponse(500, ErrorCodes.INTERNAL_SERVER_ERROR));
+  }
+}
+
+/**
+ * Reload session user values from the database and refresh cookies.
+ * - Validates sessionId and active status
+ * - Updates `req.session.user` fields (username, role, allowedApps, fullname)
+ * - Uses cached `fullName` cookie when available, otherwise queries `profiledata`
+ * - Syncs `username`, `fullName` and `sessionId` cookies
+ * Returns: true if session refreshed and valid, false if session invalidated
+ */
+export async function reloadSessionUser(req, res) {
+  if (!req.session || !req.session.user || !req.session.user.id) return false;
+  try {
+    const { id, sessionId: currentSessionId } = req.session.user;
+
+    // Fetch fresh user record
+    const query = `SELECT id, "UserName", "Active", "Role", "AllowedApps", "SessionId" FROM "Users" WHERE id = $1`;
+    const result = await dblogin.query({ name: 'reload-session-user', text: query, values: [id] });
+
+    if (result.rows.length === 0) {
+      // User not found — invalidate session
+      req.session.destroy(() => {});
+      clearSessionCookies(res);
+      return false;
+    }
+
+    const row = result.rows[0];
+    const dbSessionId = row.SessionId ? String(row.SessionId).toLowerCase() : null;
+    if (!dbSessionId || dbSessionId !== String(currentSessionId).toLowerCase()) {
+      // Session invalidated in DB
+      req.session.destroy(() => {});
+      clearSessionCookies(res);
+      return false;
+    }
+
+    if (!row.Active) {
+      // Account is inactive
+      req.session.destroy(() => {});
+      clearSessionCookies(res);
+      return false;
+    }
+
+    // Authorization: ensure allowed for current app unless SuperAdmin
+    if (row.Role !== 'SuperAdmin') {
+      const allowedApps = row.AllowedApps;
+      const hasAllowedApps = Array.isArray(allowedApps) && allowedApps.length > 0;
+      if (!hasAllowedApps || !allowedApps.some(app => app && app.toLowerCase() === mbkautheVar.APP_NAME.toLowerCase())) {
+        req.session.destroy(() => {});
+        clearSessionCookies(res);
+        return false;
+      }
+    }
+
+    // Update session fields
+    req.session.user.username = row.UserName;
+    req.session.user.role = row.Role;
+    req.session.user.allowedApps = row.AllowedApps;
+
+    // Obtain fullname from client cookie cache when present else DB
+    if (req.cookies && req.cookies.fullName && typeof req.cookies.fullName === 'string') {
+      req.session.user.fullname = req.cookies.fullName;
+    } else {
+      try {
+        const prof = await dblogin.query({ name: 'reload-get-fullname', text: 'SELECT "FullName" FROM "profiledata" WHERE "UserName" = $1 LIMIT 1', values: [row.UserName] });
+        if (prof.rows.length > 0 && prof.rows[0].FullName) req.session.user.fullname = prof.rows[0].FullName;
+      } catch (profileErr) {
+        console.error('[mbkauthe] Error fetching fullname during reload:', profileErr);
+      }
+    }
+
+    // Persist session changes
+    await new Promise((resolve, reject) => req.session.save(err => err ? reject(err) : resolve()));
+
+    // Sync cookies for client UI (non-httpOnly)
+    try {
+      res.cookie('username', req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
+      res.cookie('fullName', req.session.user.fullname || req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
+      res.cookie('sessionId', req.session.user.sessionId, cachedCookieOptions);
+    } catch (cookieErr) {
+      // Ignore cookie setting errors, session is still refreshed
+      console.error('[mbkauthe] Error syncing cookies during reload:', cookieErr);
+    }
+
+    return true;
+  } catch (err) {
+    console.error('[mbkauthe] reloadSessionUser error:', err);
+    return false;
+  }
+}
+
 const checkRolePermission = (requiredRoles, notAllowed) => {
   return async (req, res, next) => {
     try {
@@ -173,5 +327,4 @@ const authenticate = (authentication) => {
   };
 };
 
-
-export { validateSession, checkRolePermission, validateSessionAndRole, authenticate };
+export { validateSession, validateApiSession, checkRolePermission, validateSessionAndRole, authenticate };

package/lib/middleware/index.js

@@ -85,6 +85,25 @@ export async function sessionRestorationMiddleware(req, res, next) {
           sessionId: normalizedSessionId,
           allowedApps: user.AllowedApps,
         };
+
+        // Use cached FullName from client cookie when available to avoid extra DB queries
+        if (req.cookies.fullName && typeof req.cookies.fullName === 'string') {
+          req.session.user.fullname = req.cookies.fullName;
+        } else {
+          // Fallback: attempt to fetch FullName from profiledata to populate session
+          try {
+            const profileRes = await dblogin.query({
+              name: 'restore-get-fullname',
+              text: 'SELECT "FullName" FROM "profiledata" WHERE "UserName" = $1 LIMIT 1',
+              values: [user.UserName]
+            });
+            if (profileRes.rows.length > 0 && profileRes.rows[0].FullName) {
+              req.session.user.fullname = profileRes.rows[0].FullName;
+            }
+          } catch (profileErr) {
+            console.error("[mbkauthe] Error fetching FullName during session restore:", profileErr);
+          }
+        }
       }
     } catch (err) {
       console.error("[mbkauthe] Session restoration error:", err);
@@ -99,8 +118,10 @@ export function sessionCookieSyncMiddleware(req, res, next) {
     // Only set cookies if they're missing or different
     if (req.cookies.sessionId !== req.session.user.sessionId) {
       res.cookie("username", req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
+      // Also expose FullName (fallback to username) for display in client-side UI
+      res.cookie("fullName", req.session.user.fullname || req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
       res.cookie("sessionId", req.session.user.sessionId, cachedCookieOptions);
     }
   }
   next();
-}
+}

package/lib/routes/auth.js

@@ -170,6 +170,20 @@ export async function completeLoginProcess(req, res, user, redirectUrl = null, t
       allowedApps: user.allowedApps || user.AllowedApps,
     };
 
+    // Attempt to fetch FullName from profiledata and store it in session for display purposes
+    try {
+      const profileResult = await dblogin.query({
+        name: 'login-get-fullname',
+        text: 'SELECT "FullName" FROM "profiledata" WHERE "UserName" = $1 LIMIT 1',
+        values: [username]
+      });
+      if (profileResult.rows.length > 0 && profileResult.rows[0].FullName) {
+        req.session.user.fullname = profileResult.rows[0].FullName;
+      }
+    } catch (profileErr) {
+      console.error("[mbkauthe] Error fetching FullName for user:", profileErr);
+    }
+
     if (req.session.preAuthUser) {
       delete req.session.preAuthUser;
     }
@@ -180,7 +194,9 @@ export async function completeLoginProcess(req, res, user, redirectUrl = null, t
         return res.status(500).json({ success: false, message: "Internal Server Error" });
       }
 
+      // Expose sessionId and display name to client for UI (fullName falls back to username)
       res.cookie("sessionId", sessionId, cachedCookieOptions);
+      res.cookie("fullName", req.session.user.fullname || username, { ...cachedCookieOptions, httpOnly: false });
 
       // Handle trusted device if requested
       if (trustDevice) {

package/lib/routes/misc.js

@@ -3,7 +3,7 @@ import fetch from 'node-fetch';
 import rateLimit from 'express-rate-limit';
 import { mbkautheVar, packageJson, appVersion } from "../config/index.js";
 import { renderError } from "../utils/response.js";
-import { authenticate, validateSession } from "../middleware/auth.js";
+import { authenticate, validateSession, validateApiSession } from "../middleware/auth.js";
 import { ErrorCodes, ErrorMessages } from "../utils/errors.js";
 import { dblogin } from "../database/pool.js";
 import { clearSessionCookies } from "../config/cookies.js";
@@ -90,6 +90,41 @@ router.get('/test', validateSession, LoginLimit, async (req, res) => {
   }
 });
 
+// API: check current session validity (JSON) — minimal response
+router.get('/api/checkSession', LoginLimit, async (req, res) => {
+  try {
+    if (!req.session?.user) {
+      return res.status(200).json({ sessionValid: false, expiry: null });
+    }
+
+    const { id, sessionId } = req.session.user;
+    if (!sessionId) {
+      req.session.destroy(() => { });
+      clearSessionCookies(res);
+      return res.status(200).json({ sessionValid: false, expiry: null });
+    }
+
+    const normalizedSessionId = String(sessionId).toLowerCase();
+    const result = await dblogin.query({ name: 'check-session-validity', text: 'SELECT "SessionId", "Active" FROM "Users" WHERE id = $1', values: [id] });
+
+    const dbSessionId = result.rows.length > 0 && result.rows[0].SessionId ? String(result.rows[0].SessionId).toLowerCase() : null;
+    if (!dbSessionId || dbSessionId !== normalizedSessionId || !result.rows[0].Active) {
+      req.session.destroy(() => { });
+      clearSessionCookies(res);
+      return res.status(200).json({ sessionValid: false, expiry: null });
+    }
+
+    // Fetch expiry timestamp from session table (connect-pg-simple)
+    const sessResult = await dblogin.query({ name: 'get-session-expiry', text: 'SELECT expire FROM "session" WHERE sid = $1', values: [req.sessionID] });
+    const expiry = sessResult.rows.length > 0 && sessResult.rows[0].expire ? new Date(sessResult.rows[0].expire).toISOString() : null;
+
+    return res.status(200).json({ sessionValid: true, expiry });
+  } catch (err) {
+    console.error('[mbkauthe] checkSession error:', err);
+    return res.status(200).json({ sessionValid: false, expiry: null });
+  }
+});
+
 // Error codes page
 router.get("/ErrorCode", (req, res) => {
   try {
@@ -251,12 +286,12 @@ router.post("/api/terminateAllSessions", AdminOperationLimit, authenticate(mbkau
   try {
     // Run both operations in parallel for better performance
     await Promise.all([
-      dblogin.query({ 
-        name: 'terminate-all-user-sessions', 
+      dblogin.query({
+        name: 'terminate-all-user-sessions',
         text: 'UPDATE "Users" SET "SessionId" = NULL WHERE "SessionId" IS NOT NULL'
       }),
-      dblogin.query({ 
-        name: 'terminate-all-db-sessions', 
+      dblogin.query({
+        name: 'terminate-all-db-sessions',
         text: 'DELETE FROM "session" WHERE expire > NOW()'
       })
     ]);

package/lib/routes/oauth.js

@@ -108,25 +108,43 @@ const createOAuthStrategy = async (provider, profile, done) => {
   }
 };
 
-// Configure GitHub Strategy for login
-passport.use('github-login', new GitHubStrategy({
-  clientID: mbkautheVar.GITHUB_CLIENT_ID,
-  clientSecret: mbkautheVar.GITHUB_CLIENT_SECRET,
-  callbackURL: '/mbkauthe/api/github/login/callback',
-  scope: ['user:email']
-}, (accessToken, refreshToken, profile, done) => 
-  createOAuthStrategy('GitHub', profile, done)
-));
-
-// Configure Google Strategy for login
-passport.use('google-login', new GoogleStrategy({
-  clientID: mbkautheVar.GOOGLE_CLIENT_ID,
-  clientSecret: mbkautheVar.GOOGLE_CLIENT_SECRET,
-  callbackURL: '/mbkauthe/api/google/login/callback',
-  scope: ['profile', 'email']
-}, (accessToken, refreshToken, profile, done) => 
-  createOAuthStrategy('Google', profile, done)
-));
+// Configure GitHub Strategy for login (only if enabled and configured)
+if ((mbkautheVar.GITHUB_LOGIN_ENABLED || "").toLowerCase() === "true") {
+  if (mbkautheVar.GITHUB_CLIENT_ID && mbkautheVar.GITHUB_CLIENT_SECRET) {
+    passport.use('github-login', new GitHubStrategy({
+      clientID: mbkautheVar.GITHUB_CLIENT_ID,
+      clientSecret: mbkautheVar.GITHUB_CLIENT_SECRET,
+      callbackURL: '/mbkauthe/api/github/login/callback',
+      scope: ['user:email']
+    }, (accessToken, refreshToken, profile, done) => 
+      createOAuthStrategy('GitHub', profile, done)
+    ));
+    console.log('[mbkauthe] GitHub OAuth strategy registered');
+  } else {
+    console.warn('[mbkauthe] GITHUB_LOGIN_ENABLED is true but GITHUB_CLIENT_ID/SECRET missing; skipping GitHub strategy registration');
+  }
+} else {
+  console.log('[mbkauthe] GitHub OAuth not enabled; skipping GitHub strategy registration');
+}
+
+// Configure Google Strategy for login (only if enabled and configured)
+if ((mbkautheVar.GOOGLE_LOGIN_ENABLED || "").toLowerCase() === "true") {
+  if (mbkautheVar.GOOGLE_CLIENT_ID && mbkautheVar.GOOGLE_CLIENT_SECRET) {
+    passport.use('google-login', new GoogleStrategy({
+      clientID: mbkautheVar.GOOGLE_CLIENT_ID,
+      clientSecret: mbkautheVar.GOOGLE_CLIENT_SECRET,
+      callbackURL: '/mbkauthe/api/google/login/callback',
+      scope: ['profile', 'email']
+    }, (accessToken, refreshToken, profile, done) => 
+      createOAuthStrategy('Google', profile, done)
+    ));
+    console.log('[mbkauthe] Google OAuth strategy registered');
+  } else {
+    console.warn('[mbkauthe] GOOGLE_LOGIN_ENABLED is true but GOOGLE_CLIENT_ID/SECRET missing; skipping Google strategy registration');
+  }
+} else {
+  console.log('[mbkauthe] Google OAuth not enabled; skipping Google strategy registration');
+}
 
 // Serialize/Deserialize user for OAuth login
 passport.serializeUser((user, done) => {

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "mbkauthe",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "MBKTech's reusable authentication system for Node.js applications.",
   "main": "index.js",
   "type": "module",
   "types": "index.d.ts",
   "scripts": {
-    "dev": "node scripts/setup-hooks.js && cross-env test=dev nodemon index.js",
-    "test": "node scripts/setup-hooks.js && node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:watch": "node scripts/setup-hooks.js && node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
+    "dev": "cross-env test=dev nodemon index.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"
   },
   "repository": {
     "type": "git",

package/test.spec.js

@@ -192,5 +192,20 @@ describe('mbkauthe Routes', () => {
         expect(response.headers['content-type']).toContain('application/json');
       }
     });
+
+    test('GET /mbkauthe/api/checkSession handles session check', async () => {
+      const response = await request(BASE_URL).get('/mbkauthe/api/checkSession');
+      expect(response.status).toBe(200);
+      expect(response.headers['content-type']).toContain('application/json');
+      expect(response.body).toHaveProperty('sessionValid');
+    });
+
+    test('POST /mbkauthe/api/logout handles logout', async () => {
+      const response = await request(BASE_URL).post('/mbkauthe/api/logout').send();
+      expect([200, 400, 401, 403, 429]).toContain(response.status);
+      if (response.status === 200) {
+        expect(response.headers['content-type']).toContain('application/json');
+      }
+    });
   });
 });