mbkauthe 3.3.0 → 3.4.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/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/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/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.4.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",