mbkauthe 2.4.0 → 3.0.0

package/docs/api.md

@@ -11,6 +11,10 @@ This document provides comprehensive API documentation for MBKAuthe authenticati
 - [Authentication](#authentication)
 - [Session Management](#session-management)
 - [API Endpoints](#api-endpoints)
+  - [Public Endpoints](#public-endpoints)
+  - [Protected Endpoints](#protected-endpoints)
+  - [OAuth Endpoints](#oauth-endpoints)
+  - [Information Endpoints](#information-endpoints)
 - [Middleware Reference](#middleware-reference)
 - [Code Examples](#code-examples)
 
@@ -326,6 +330,35 @@ Displays MBKAuthe version information and configuration.
 
 ---
 
+#### `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 /mbkauthe/main.js`
 
 Serves the client-side JavaScript file containing helper functions for authentication operations.
@@ -364,6 +397,35 @@ Serves the client-side JavaScript file containing helper functions for authentic
 - 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`
@@ -448,6 +510,79 @@ GET /mbkauthe/test
 
 ---
 
+### OAuth Endpoints
+
+#### `GET /mbkauthe/api/github/login`
+
+Initiates the GitHub OAuth authentication flow.
+
+**Rate Limit:** 10 requests per 5 minutes
+
+**Query Parameters:**
+- `redirect` (optional) - Relative URL to redirect after successful authentication (must start with `/` to prevent open redirect attacks)
+
+**Response:** Redirects to GitHub OAuth authorization page
+
+**Prerequisites:**
+- `GITHUB_LOGIN_ENABLED=true` in environment
+- Valid `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` configured
+- User's GitHub account must be linked to an MBKAuth account in `user_github` table
+
+**Example:**
+```
+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
+
+---
+
+#### `GET /mbkauthe/api/github/login/callback`
+
+Handles the OAuth callback from GitHub after user authorization.
+
+**Rate Limit:** Inherited from OAuth rate limiter (10 requests per 5 minutes)
+
+**Query Parameters:**
+- `code` - Authorization code from GitHub (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:**
+- **GitHub Not Linked**: Returns error if GitHub account is not in `user_github` table
+- **Account Inactive**: Returns error if user account is deactivated
+- **Not Authorized**: Returns error if user is not allowed to access the application
+- **GitHub Auth Error**: Returns error for any OAuth-related failures
+
+**Success Flow:**
+```
+GitHub → /api/github/login/callback 
+  → (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_github ug 
+JOIN "Users" u ON ug.user_name = u."UserName" 
+WHERE ug.github_id = $1
+```
+
+**Note:** This endpoint is automatically called by GitHub and should not be accessed directly by users.
+
+---
+
 ## Middleware Reference
 
 ### `validateSession`
@@ -931,10 +1066,13 @@ app.use((req, res) => {
 | `/mbkauthe/api/login` | 8 requests | 1 minute |
 | `/mbkauthe/api/logout` | 10 requests | 1 minute |
 | `/mbkauthe/api/verify-2fa` | 5 requests | 1 minute |
+| `/mbkauthe/api/github/login` | 10 requests | 5 minutes |
+| `/mbkauthe/api/github/login/callback` | 10 requests | 5 minutes |
 | `/mbkauthe/login` | 8 requests | 1 minute |
 | `/mbkauthe/info` | 8 requests | 1 minute |
+| `/mbkauthe/test` | 8 requests | 1 minute |
 
-Rate limits are applied per IP address.
+Rate limits are applied per IP address. Logged-in users are exempt from some rate limits (e.g., login page rate limit).
 
 ---
 

package/docs/db.md

@@ -138,13 +138,14 @@ The GitHub login feature is now fully integrated into your mbkauthe system and r
 
   - `id` (INTEGER, auto-increment, primary key): Unique identifier for each user.
   - `UserName` (TEXT): The username of the user.
-  - `Password` (TEXT): The hashed password of the user.
+  - `Password` (TEXT): The raw password of the user (used when EncPass=false).
+  - `PasswordEnc` (TEXT): The encrypted/hashed password of the user (used when EncPass=true).
   - `Role` (ENUM): The role of the user. Possible values: `SuperAdmin`, `NormalUser`, `Guest`.
   - `Active` (BOOLEAN): Indicates whether the user account is active.
   - `HaveMailAccount` (BOOLEAN)(optional): Indicates if the user has a linked mail account.
   - `SessionId` (TEXT): The session ID associated with the user.
   - `GuestRole` (JSONB): Stores additional guest-specific role information in binary JSON format.
-  - `AllowedApps`(JSONB): 
+  - `AllowedApps`(JSONB): Array of applications the user is authorized to access.
 
 - **Schema:**
 ```sql
@@ -153,7 +154,8 @@ CREATE TYPE role AS ENUM ('SuperAdmin', 'NormalUser', 'Guest');
 CREATE TABLE "Users" (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     "UserName" VARCHAR(50) NOT NULL UNIQUE,
-    "Password" VARCHAR(61) NOT NULL, -- For bcrypt hash
+    "Password" VARCHAR(61), -- For raw passwords (when EncPass=false)
+    "PasswordEnc" VARCHAR(128), -- For encrypted passwords (when EncPass=true)
     "Role" role DEFAULT 'NormalUser' NOT NULL,
     "Active" BOOLEAN DEFAULT FALSE,
     "HaveMailAccount" BOOLEAN DEFAULT FALSE,
@@ -173,6 +175,12 @@ CREATE INDEX IF NOT EXISTS idx_users_last_login ON "Users" (last_login);
 CREATE INDEX IF NOT EXISTS idx_users_id_sessionid_active_role ON "Users" ("id", LOWER("SessionId"), "Active", "Role");
 ```
 
+**Password Storage Notes:**
+- When `EncPass=false` (default): The system uses the `Password` column to store and validate raw passwords
+- When `EncPass=true` (recommended for production): The system uses the `PasswordEnc` column to store hashed passwords using PBKDF2 with the username as salt
+- Only one password column should be populated based on your EncPass configuration
+- The PasswordEnc field stores 128-character hex strings when using PBKDF2 hashing
+
 ### Session Table
 
 - **Columns:**
@@ -255,6 +263,7 @@ CREATE INDEX IF NOT EXISTS idx_trusted_devices_expires ON "TrustedDevices"("Expi
 
 To add new users to the `Users` table, use the following SQL queries:
 
+**For Raw Password Storage (EncPass=false):**
 ```sql
         INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
         VALUES ('support', '12345678', 'SuperAdmin', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
@@ -263,8 +272,29 @@ To add new users to the `Users` table, use the following SQL queries:
         VALUES ('test', '12345678', 'NormalUser', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
 ```
 
+**For Encrypted Password Storage (EncPass=true):**
+```sql
+        -- Note: You'll need to hash the password using the hashPassword function
+        -- Example with pre-hashed password (PBKDF2 with username as salt)
+        INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
+        VALUES ('support', 'your_hashed_password_here', 'SuperAdmin', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
+
+        INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "SessionId", "GuestRole")
+        VALUES ('test', 'your_hashed_password_here', 'NormalUser', true, false, NULL, '{"allowPages": [""], "NotallowPages": [""]}'::jsonb);
+```
+
+**Configuration Notes:**
 - Replace `support` and `test` with the desired usernames.
-- Replace `12345678` with the actual passwords.
+- For raw passwords: Replace `12345678` with the actual plain text passwords.
+- For encrypted passwords: Use the hashPassword function to generate the hash before inserting.
 - Adjust the `Role` values as needed (`SuperAdmin`, `NormalUser`, or `Guest`).
 - Modify the `Active` and `HaveMailAccount` values as required.
-- Update the `GuestRole` JSON object if specific permissions are required(this functionality is under construction).
+- Update the `GuestRole` JSON object if specific permissions are required (this functionality is under construction).
+
+**Generating Encrypted Passwords:**
+If you're using `EncPass=true`, you can generate encrypted passwords using the hashPassword function:
+```javascript
+import { hashPassword } from 'mbkauthe';
+const encryptedPassword = hashPassword('12345678', 'support');
+console.log(encryptedPassword); // Use this value for PasswordEnc column
+```

package/docs/env.md

@@ -29,6 +29,7 @@ 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
@@ -80,6 +81,35 @@ 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
@@ -278,6 +308,7 @@ 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
@@ -296,6 +327,7 @@ 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