mbkauthe 3.0.0 → 3.2.0

package/README.md

@@ -1,4 +1,4 @@
-# MBKAuthe v3.0 - Authentication System for Node.js
+# MBKAuthe v3.2 - 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,19 +16,20 @@
   <img height="48px" src="https://handlebarsjs.com/handlebars-icon.svg" alt="Handlebars" />
 </p>
 
-**MBKAuth v3.0** is a production-ready authentication system for Node.js applications. Built with Express and PostgreSQL, it provides secure authentication, 2FA, role-based access, and GitHub OAuth out of the box.
+**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.
 
 ## ✨ Key Features
 
 - 🔐 Secure password authentication with PBKDF2 hashing
 - 🔑 PostgreSQL session management with cross-subdomain support
 - 📱 Optional TOTP-based 2FA with trusted device memory
-- 🔄 GitHub OAuth integration
+- 🔄 OAuth integration (GitHub & Google)
 - 👥 Role-based access control (SuperAdmin, NormalUser, Guest)
 - 🎯 Multi-application user management
-- 🛡️ CSRF protection & rate limiting
+- 🛡️ CSRF protection & advanced rate limiting
 - 🚀 Easy Express.js integration
 - 🎨 Customizable Handlebars templates
+- 🔒 Enhanced security with session fixation prevention
 
 ## 📦 Installation
 
@@ -48,10 +49,18 @@ IS_DEPLOYED=false
 DOMAIN=localhost
 LOGIN_DB=postgresql://user:pass@localhost:5432/db
 
-# Optional
+# 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**
@@ -110,6 +119,30 @@ app.get('/admin', validateSession, checkRolePermission(['SuperAdmin']), (req, re
 app.listen(3000);
 ```
 
+## 🧪 Testing
+
+MBKAuthe includes comprehensive test coverage for all authentication features:
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode (auto-rerun on changes)
+npm run test:watch
+
+# Run with development flags
+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)
 
 ```
@@ -148,22 +181,42 @@ app.post('/api/data', authenticate(process.env.API_TOKEN), handler);
 
 ### Built-in Routes
 
-- `GET /mbkauthe/login` - Login page
+**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 page (if enabled)
-- `POST /mbkauthe/api/verify-2fa` - 2FA verification (5/min rate limit)
-- `GET /mbkauthe/api/github/login` - GitHub OAuth
-- `GET /mbkauthe/info` - Version & config info
-- `GET /mbkauthe/ErrorCode` - Error documentation
+- `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)
-- **CSRF Protection**: All POST routes protected
+- **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 Security**: PostgreSQL-backed, automatic cleanup, session fixation prevention
+- **OAuth Security**: State validation, token expiry handling, secure callback validation
 
 ## 📱 Two-Factor Authentication
 
@@ -179,7 +232,9 @@ CREATE TABLE "TwoFA" (
 
 Users can mark devices as trusted to skip 2FA for configurable duration.
 
-## 🔄 GitHub OAuth
+## 🔄 OAuth Integration
+
+### GitHub OAuth
 
 **Setup:**
 
@@ -202,6 +257,32 @@ CREATE TABLE user_github (
 );
 ```
 
+### 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.
+
 ## 🎨 Customization
 
 **Redirect URL:**
@@ -245,8 +326,9 @@ const result = await dblogin.query('SELECT * FROM "Users"');
 ## 📚 Documentation
 
 - [API Documentation](docs/api.md) - Complete API reference
-- [Database Guide](docs/db.md) - Schema details
+- [Database Guide](docs/db.md) - Schema details  
 - [Environment Config](docs/env.md) - Configuration options
+- [Error Messages](docs/error-messages.md) - Error code reference
 
 ## 📝 License
 

package/docs/api.md

@@ -55,14 +55,66 @@ When a user logs in, MBKAuthe creates a session and sets the following cookies:
 
 ### Public Endpoints
 
+#### `GET /login`
+
+Redirect route that forwards to the main login page.
+
+**Rate Limit:** No rate limiting applied
+
+**Query Parameters:**
+- All query parameters are preserved and forwarded
+
+**Response:** 302 redirect to `/mbkauthe/login`
+
+**Example:**
+```
+GET /login?redirect=/dashboard
+→ Redirects to: /mbkauthe/login?redirect=/dashboard
+```
+
+---
+
+#### `GET /signin`
+
+Alias redirect route that forwards to the main login page.
+
+**Rate Limit:** No rate limiting applied
+
+**Query Parameters:**
+- All query parameters are preserved and forwarded
+
+**Response:** 302 redirect to `/mbkauthe/login`
+
+**Example:**
+```
+GET /signin
+→ Redirects to: /mbkauthe/login
+```
+
+---
+
 #### `GET /mbkauthe/login`
 
-Renders the login page.
+Renders the main login page.
+
+**Rate Limit:** 8 requests per minute (exempt for logged-in users)
+
+**CSRF Protection:** Required (token included in form)
 
 **Query Parameters:**
 - `redirect` (optional) - URL to redirect after successful login
 
-**Response:** HTML page
+**Response:** HTML page with login form
+
+**Template Variables:**
+- `githubLoginEnabled` - Whether GitHub OAuth is enabled
+- `googleLoginEnabled` - Whether Google OAuth is enabled
+- `customURL` - Redirect URL after login
+- `userLoggedIn` - Whether user is already authenticated
+- `username` - Current username if logged in
+- `version` - MBKAuthe version
+- `appName` - Application name
+- `csrfToken` - CSRF protection token
 
 **Example:**
 ```
@@ -275,13 +327,17 @@ fetch('/mbkauthe/api/logout', {
 
 Terminates all active sessions across all users (admin only).
 
-**Authentication:** API token required
+**Authentication:** API token required (via `authenticate` middleware)
+
+**Rate Limit:** 3 requests per 5 minutes
 
 **Headers:**
 ```
-Authorization: your-api-token
+Authorization: your-main-secret-token
 ```
 
+**Request Body:** None required
+
 **Success Response (200 OK):**
 ```json
 {
@@ -298,16 +354,29 @@ Authorization: your-api-token
 | 500 | Failed to terminate sessions |
 | 500 | Internal Server Error |
 
+**Implementation Details:**
+- Clears all user session IDs in the database (`Users` table) where sessions exist
+- Deletes all active session records from the `session` table  
+- Destroys the current request session
+- Clears session cookies
+- Runs database operations in parallel for better performance
+- Uses optimized queries with WHERE clauses to avoid unnecessary updates
+
 **Example Request:**
 ```javascript
 fetch('/mbkauthe/api/terminateAllSessions', {
   method: 'POST',
   headers: {
-    'Authorization': 'your-secret-token',
+    'Authorization': process.env.MAIN_SECRET_TOKEN,
+    'Content-Type': 'application/json'
   }
 })
 .then(response => response.json())
-.then(data => console.log(data));
+.then(data => {
+  if (data.success) {
+    console.log('All sessions terminated successfully');
+  }
+});
 ```
 
 ---
@@ -363,6 +432,10 @@ GET /mbkauthe/ErrorCode
 
 Serves the client-side JavaScript file containing helper functions for authentication operations.
 
+**Rate Limit:** No rate limiting applied
+
+**Cache:** Cached for 1 year (max-age=31536000)
+
 **Purpose:** Provides frontend JavaScript utilities including:
 - `logout()` - Logout function with confirmation dialog and cache clearing
 - `logoutuser()` - Alias for logout function
@@ -396,46 +469,20 @@ Serves the client-side JavaScript file containing helper functions for authentic
 - Clears cookies
 - Forces page reload
 
-
----
-
-#### `GET /mbkauthe/ErrorCode`
-
-Displays comprehensive error code documentation with descriptions and user messages.
-
-**Response:** HTML page showing:
-- All error codes organized by category
-- Error code ranges (Authentication, 2FA, Session, Authorization, etc.)
-- User-friendly messages and hints for each error
-- Dynamically generated from `lib/utils/errors.js`
-
-**Categories:**
-- **600-699**: Authentication Errors
-- **700-799**: Two-Factor Authentication Errors
-- **800-899**: Session Management Errors
-- **900-999**: Authorization Errors
-- **1000-1099**: Input Validation Errors
-- **1100-1199**: Rate Limiting Errors
-- **1200-1299**: Server Errors
-- **1300-1399**: OAuth Errors
-
-**Note:** This page is automatically synchronized with the error definitions in the codebase. Adding new errors only requires updating `lib/utils/errors.js` and the category code array.
-
-**Usage:**
-```
-GET /mbkauthe/ErrorCode
-```
-
 ---
 
 #### `GET /icon.svg`
 
-Serves the application's SVG icon file.
+Serves the application's SVG icon file from the root level.
+
+**Rate Limit:** No rate limiting applied
 
 **Response:** SVG image file (Content-Type: image/svg+xml)
 
 **Cache:** Cached for 1 year (max-age=31536000)
 
+**Note:** This route is mounted at the root level (not under `/mbkauthe`)
+
 **Usage:**
 ```html
 <img src="/icon.svg" alt="App Icon">
@@ -512,12 +559,16 @@ GET /mbkauthe/test
 
 ### OAuth Endpoints
 
-#### `GET /mbkauthe/api/github/login`
+#### GitHub OAuth
+
+##### `GET /mbkauthe/api/github/login`
 
 Initiates the GitHub OAuth authentication flow.
 
 **Rate Limit:** 10 requests per 5 minutes
 
+**CSRF Protection:** Required (state parameter used for validation)
+
 **Query Parameters:**
 - `redirect` (optional) - Relative URL to redirect after successful authentication (must start with `/` to prevent open redirect attacks)
 
@@ -535,15 +586,16 @@ GET /mbkauthe/api/github/login?redirect=/dashboard
 
 **Workflow:**
 1. User clicks "Login with GitHub"
-2. Redirects to GitHub for authorization
-3. GitHub redirects back to callback URL
-4. System verifies GitHub account is linked
-5. If 2FA enabled, prompts for 2FA
-6. Creates session and redirects to specified URL
+2. CSRF token generated and stored in session
+3. Redirects to GitHub for authorization
+4. GitHub redirects back to callback URL
+5. System verifies GitHub account is linked
+6. If 2FA enabled, prompts for 2FA
+7. Creates session and redirects to specified URL
 
 ---
 
-#### `GET /mbkauthe/api/github/login/callback`
+##### `GET /mbkauthe/api/github/login/callback`
 
 Handles the OAuth callback from GitHub after user authorization.
 
@@ -583,6 +635,104 @@ WHERE ug.github_id = $1
 
 ---
 
+#### Google OAuth
+
+##### `GET /mbkauthe/api/google/login`
+
+Initiates the Google OAuth 2.0 authentication flow.
+
+**Rate Limit:** 10 requests per 5 minutes
+
+**CSRF Protection:** Required (state parameter used for validation)
+
+**Query Parameters:**
+- `redirect` (optional) - Relative URL to redirect after successful authentication (must start with `/` to prevent open redirect attacks)
+
+**Response:** Redirects to Google OAuth authorization page
+
+**Prerequisites:**
+- `GOOGLE_LOGIN_ENABLED=true` in environment
+- Valid `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` configured
+- User's Google account must be linked to an MBKAuth account in `user_google` table
+
+**Example:**
+```
+GET /mbkauthe/api/google/login?redirect=/dashboard
+```
+
+**Workflow:**
+1. User clicks "Login with Google"
+2. CSRF token generated and stored in session
+3. Redirects to Google for authorization
+4. Google redirects back to callback URL
+5. System verifies Google account is linked
+6. If 2FA enabled, prompts for 2FA
+7. Creates session and redirects to specified URL
+
+**Error Responses:**
+- **Configuration Error**: Returns 500 if Google OAuth credentials are not properly configured
+- **Disabled**: Returns 403 if `GOOGLE_LOGIN_ENABLED` is false
+
+---
+
+##### `GET /mbkauthe/api/google/login/callback`
+
+Handles the OAuth callback from Google after user authorization.
+
+**Rate Limit:** Inherited from OAuth rate limiter (10 requests per 5 minutes)
+
+**Query Parameters:**
+- `code` - Authorization code from Google (automatically provided)
+- `state` - State parameter for CSRF protection (automatically provided)
+
+**Response:** 
+- Redirects to 2FA page if 2FA is enabled for the user
+- Redirects to `loginRedirectURL` or stored redirect URL if 2FA is not required
+- Renders error page if authentication fails
+
+**Error Handling:**
+- **Google Not Linked**: Returns error if Google account is not in `user_google` table
+- **Account Inactive**: Returns error if user account is deactivated
+- **Not Authorized**: Returns error if user is not allowed to access the application
+- **Google Auth Error**: Returns error for any OAuth-related failures
+- **Token Error**: Handles expired or invalid OAuth tokens with user-friendly message
+- **CSRF Validation Failed**: Returns 403 if state parameter doesn't match
+
+**Success Flow:**
+```
+Google → /api/google/login/callback 
+  → (CSRF Validation)
+  → (If 2FA enabled) → /mbkauthe/2fa 
+  → (If no 2FA) → loginRedirectURL or stored redirect
+```
+
+**Database Query:**
+```sql
+SELECT ug.*, u."UserName", u."Role", u."Active", u."AllowedApps", u."id" 
+FROM user_google ug 
+JOIN "Users" u ON ug.user_name = u."UserName" 
+WHERE ug.google_id = $1
+```
+
+**Note:** This endpoint is automatically called by Google and should not be accessed directly by users.
+
+---
+
+#### OAuth Security Features
+
+Both GitHub and Google OAuth implementations include:
+
+- **CSRF Protection**: State parameter validation to prevent cross-site request forgery
+- **Session Security**: OAuth state tokens stored in session and validated on callback
+- **Rate Limiting**: 10 requests per 5 minutes to prevent abuse
+- **Token Validation**: Proper handling of expired or invalid OAuth tokens
+- **Redirect Validation**: Only allows relative URLs to prevent open redirect attacks
+- **Account Linking**: Users must pre-link OAuth accounts before login
+- **2FA Integration**: Respects 2FA settings and trusted device configuration
+- **Comprehensive Error Handling**: User-friendly error messages for all failure scenarios
+
+---
+
 ## Middleware Reference
 
 ### `validateSession`
@@ -710,64 +860,6 @@ Authorization: your-secret-token
 
 ---
 
-### `authapi(requiredRole)`
-
-Advanced API authentication with role-based access control.
-
-**Parameters:**
-- `requiredRole` (array, optional) - Array of allowed roles
-
-**Usage:**
-```javascript
-import { authapi } from 'mbkauthe';
-
-// Any authenticated API user
-app.get('/api/data', authapi(), (req, res) => {
-  console.log(req.user); // { username, UserName, role, Role }
-  res.json({ data: 'API data' });
-});
-
-// Only SuperAdmin via API
-app.post('/api/admin/action', authapi(['SuperAdmin']), (req, res) => {
-  res.json({ success: true });
-});
-```
-
-**Headers Required:**
-```
-Authorization: user-api-key-64-char-hex
-```
-
-**Behavior:**
-- Validates API key from `Authorization` header
-- Looks up user associated with API key
-- Checks if user account is active
-- Verifies user role if `requiredRole` is specified
-- Blocks demo users from accessing endpoints
-- Populates `req.user` with user information
-- Returns 401 if unauthorized, 403 if insufficient permissions
-
-**req.user Object:**
-```javascript
-req.user = {
-  username: "john.doe",
-  UserName: "john.doe",
-  role: "NormalUser",
-  Role: "NormalUser"
-}
-```
-
-**Database Requirement:**
-Requires `UserAuthApiKey` table:
-```sql
-CREATE TABLE "UserAuthApiKey" (
-    username VARCHAR(50) PRIMARY KEY REFERENCES "Users"("UserName"),
-    "key" VARCHAR(64) UNIQUE NOT NULL
-);
-```
-
----
-
 ## Error Codes
 
 ### HTTP Status Codes
@@ -876,7 +968,7 @@ app.get('/moderator',
 ### API Authentication
 
 ```javascript
-import { authenticate, authapi } from 'mbkauthe';
+import { authenticate } from 'mbkauthe';
 
 // Simple token authentication
 app.post('/api/webhook', 
@@ -887,24 +979,27 @@ app.post('/api/webhook',
   }
 );
 
-// API key with user validation
-app.get('/api/user/profile', authapi(), async (req, res) => {
-  const { username } = req.user;
-  
-  // Fetch user profile
-  const profile = await getUserProfile(username);
-  
-  res.json({ success: true, profile });
-});
-
-// API key with role requirement
-app.delete('/api/admin/users/:id', 
-  authapi(['SuperAdmin']), 
+// Admin API with token authentication
+app.post('/api/admin/terminate-sessions', 
+  authenticate(process.env.MAIN_SECRET_TOKEN), 
   async (req, res) => {
-    await deleteUser(req.params.id);
+    // Terminate all sessions
     res.json({ success: true });
   }
 );
+
+// Protected API endpoint (requires session)
+app.get('/api/user/profile', 
+  validateSession,
+  async (req, res) => {
+    const { username } = req.session.user;
+    
+    // Fetch user profile
+    const profile = await getUserProfile(username);
+    
+    res.json({ success: true, profile });
+  }
+);
 ```
 
 ---