mbkauthe 5.0.0 → 5.0.2

package/docs/{api.md → reference/api/endpoints.md}

@@ -1,127 +1,6 @@
-# MBKAuthe API Documentation
+# Endpoints
 
-[← Back to README](../README.md)
-
-This document provides comprehensive API documentation for MBKAuthe authentication system.
-
----
-
-## Table of Contents
-
-- [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)
-- [Diagnostics (Dev Only)](#diagnostics-dev-only)
-- [Additional Endpoints](#additional-endpoints)
-- [Middleware Reference](#middleware-reference)
-- [Code Examples](#code-examples)
-
----
-
-## Authentication
-
-MBKAuthe supports two authentication methods:
-
-1. **Session-based Authentication** - Cookie-based sessions for web applications
-2. **Token-based Authentication** - Persistent API keys for server-to-server communication
-
-### Token-based Authentication
-
-For API clients and external services, use a Bearer token in the `Authorization` header.
-
-**Header Format:**
-```
-Authorization: Bearer <your_api_token>
-```
-*Token format: `mbk_` followed by 64 hexadecimal characters.*
-
-**Behavior:**
-- **Stateless:** Validates against the `ApiTokens` table on every request.
-- **Expiration:** Tokens can have an optional expiration date.
-- **Permissions:** API tokens inherit the permissions of the user who created them.
-- **Scopes:** Tokens have a scope (`read-only` or `write`) that controls which HTTP methods are allowed:
-  - `read-only`: Only GET, HEAD, and OPTIONS requests (safe, read-only operations)
-  - `write`: All HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
-- **Usage Tracking:** The system updates the `LastUsed` timestamp on every successful request.
-
-**Errors:**
-- `401 Unauthorized` (Code 1005: `INVALID_AUTH_TOKEN`): Token is malformed or not found.
-- `401 Unauthorized` (Code 1006: `API_TOKEN_EXPIRED`): Token exists but has passed its expiration date.
-- `403 Forbidden` (Code 1007: `TOKEN_SCOPE_INSUFFICIENT`): Token scope doesn't allow this HTTP method.
-
-**Example Usage:**
-
-**1. Backend Implementation (Express):**
-
-Even when using API tokens, the `validateSession`/`sessVal` middleware hydrates `req.session.user` for consistency, allowing you to use the same route logic for both browser and API clients.
-
-```javascript
-import { sessVal } from 'mbkauthe';
-
-app.get('/api/protected-resource', sessVal, (req, res) => {
-  // Access user info populated from the token
-  const user = req.session.user; // { id, username, role, ... }
-  
-  res.json({ 
-    message: `Hello ${user.username}`,
-    role: user.role
-  });
-});
-```
-
-**2. Client Request Examples:**
-
-*cURL:*
-```bash
-curl -X GET https://api.yourdomain.com/api/protected-resource \
-  -H "Authorization: Bearer mbk_7f83a92b1dc..."
-```
-
-*JavaScript (Fetch):*
-```javascript
-const response = await fetch('https://api.yourdomain.com/api/protected-resource', {
-  headers: {
-    'Authorization': 'Bearer mbk_7f83a92b1dc...'
-  }
-});
-const data = await response.json();
-```
-
-**Output:**
-```json
-{
-  "message": "Hello john.doe",
-  "role": "NormalUser"
-}
-```
-
----
-
-## Session Management
-
-### Session Cookie
-
-When a user logs in, MBKAuthe creates a session and sets the following cookies:
-
-| Cookie Name | Description | HttpOnly | Secure | SameSite |
-|------------|-------------|----------|--------|----------|
-| `mbkauthe.sid` | Session identifier | ✓ | Auto* | lax |
-| `sessionId` | Encrypted session token (AES-256-GCM). This cookie is encrypted and treated as an opaque value by clients; do not attempt to parse or rely on the raw cookie contents. Use server endpoints (e.g., `GET /mbkauthe/api/checkSession`, `POST /mbkauthe/api/checkSession` (body) or `POST /mbkauthe/api/verifySession`) to validate or query session information. | ✓ | Auto* | lax |
-| `username` | Username | ✗ | Auto* | lax |
-
-\* `secure` flag is automatically set to `true` in production when `IS_DEPLOYED=true`
-
-### Session Lifetime
-
-- Default: 2 days (configurable via `COOKIE_EXPIRE_TIME`)
-- Application sessions are stored in the `Sessions` table in PostgreSQL
-- Sessions persist across subdomains in production
-
----
+[Back to API index](../api.md) | [Back to docs index](../../README.md) | [Back to project README](../../../README.md)
 
 ## API Endpoints
 
@@ -1247,563 +1126,3 @@ Both GitHub and Google OAuth implementations include:
 
 ---
 
-## Middleware Reference
-
-### `validateSession`/`sessRole`
-
-Validates that the user has an active session.
-
-**Usage:**
-```javascript
-import { sessRole } from 'mbkauthe';
-
-app.get('/protected', sessRole, (req, res) => {
-  // User is authenticated
-  const user = req.session.user;
-  // user contains: { id, username, UserName, role, Role, sessionId }
-  res.send(`Welcome ${user.username}!`);
-});
-```
-
-**Behavior:**
-- Checks for active session in `req.session.user`
-- Attempts to restore session from `sessionId` cookie if session not found
-- Validates session against database
-- Checks if user account is still active
-- Verifies user is authorized for the current application
-- Redirects to login page if validation fails
-
-**JSON vs HTML error responses:**
-
-When `validateSession` fails, MBKAuthe will either render an HTML error/login page (browser flow) or return a JSON error response (API/AJAX flow). A request is treated as **JSON** when any of these are true:
-
-- URL/path starts with `/mbkauthe/api/` or `/api/`
-- `X-Requested-With: XMLHttpRequest`
-- `Accept` indicates JSON (e.g., `application/json`) and does not explicitly prefer `text/html`
-- `User-Agent` matches a non-browser client (e.g., `curl`, `wget`, `Postman`, `Insomnia`)
-- `User-Agent: json` (explicitly forces JSON responses)
-
-**Example (force JSON errors on a page route):**
-```bash
-curl -i -H "User-Agent: json" http://localhost:3000/mbkauthe/test
-```
-
-### 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', sessRole, 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 (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)`/`roleChk `
-
-Checks if the authenticated user has the required role.
-
-**Parameters:**
-- `requiredRole` (string) - Required role: `"SuperAdmin"`, `"NormalUser"`, `"Guest"`, `"member"`, or `"Any"`/`"any"`
-- `notAllowed` (string, optional) - Role that is explicitly not allowed
-
-**Usage:**
-```javascript
-import { sessVal, roleChk } from 'mbkauthe';
-
-// Only SuperAdmin can access
-app.get('/admin', sessVal, roleChk('SuperAdmin'), (req, res) => {
-  res.send('Admin panel');
-});
-
-// Any authenticated user except Guest
-app.get('/content', sessVal, roleChk('Any', 'Guest'), (req, res) => {
-  res.send('Protected content');
-});
-```
-
-**Behavior:**
-- Checks if user is authenticated first
-- Fetches user role from database
-- Returns 403 if user has `notAllowed` role
-- Returns 403 if user doesn't have `requiredRole` (unless role is "Any")
-- Calls `next()` if authorized
-
----
-
-### `validateSessionAndRole(requiredRole, notAllowed)`/`sessRole`
-
-Combined middleware for session validation and role checking.
-
-**Parameters:**
-- `requiredRole` (string) - Required role
-- `notAllowed` (string, optional) - Role that is explicitly not allowed
-
-**Usage:**
-```javascript
-import { sessRole, roleChk } from 'mbkauthe';
-
-// Validate session AND check role in one middleware
-app.get('/moderator', sessRole('SuperAdmin'), (req, res) => {
-  res.send('Moderator panel');
-});
-```
-
-**Equivalent to:**
-```javascript
-app.get('/moderator', sessVal, roleChk('SuperAdmin'), (req, res) => {
-  res.send('Moderator panel');
-});
-```
-
----
-
-### Strict validation helpers
-
-For endpoints that must reject API token-based authentication and only accept browser session cookies, MBKAuthe exposes two strict helpers:
-
-- `strictValidateSession` — same as `validateSession`, but rejects requests that provide `Authorization` headers (API tokens) and returns `401` when a token is used.
-- `strictValidateSessionAndRole(requiredRole, notAllowed)` — combined helper that behaves like `validateSessionAndRole` but enforces strict (cookie-only) authentication.
-
-**Usage examples:**
-```javascript
-import { strictValidateSession, strictValidateSessionAndRole } from 'mbkauthe';
-
-// Accept only cookie sessions
-app.get('/sensitive', strictValidateSession, (req, res) => {
-  res.send('Sensitive data');
-});
-
-// Validate session AND role, using cookie-only authentication
-app.get('/admin', strictValidateSessionAndRole('SuperAdmin'), (req, res) => {
-  res.send('Admin');
-});
-```
-
----
-
-### Response Utilities
-
-MBKAuthe exports small helpers to assist with page rendering and context:
-
-- `getUserContext(req)` — returns a lightweight context object for templates: `{ userLoggedIn, isuserlogin, username, fullname, role, allowedApps }`.
-- `renderPage(req, res, fileLocation, layout = true, data = {})` — renders a template with the user/context merged into the data; returns a Promise and yields the typical Express `res.render` behavior.
-- `renderError(res, req, options)` — renders the standardized error page; note the signature is `(res, req, options)` and `options` follow the `ErrorRenderOptions` described in the types.
-
-**Example:**
-
-```javascript
-import { getUserContext, renderPage, renderError } from 'mbkauthe';
-
-app.get('/dashboard', (req, res) => {
-  const ctx = getUserContext(req);
-  return renderPage(req, res, 'info', true, { greeting: 'Hello', ...ctx });
-});
-
-app.get('/err', (req, res) => {
-  return renderError(res, req, {
-    layout: false,
-    code: 500,
-    error: "Internal Server Error",
-    message: "Simulated 500 Error",
-    details: "This is a simulated 500 error page for testing purposes.",
-    pagename: "Home",
-    page: "/mbkauthe/login",
-  });
-});
-```
-
----
-
-### `authenticate(token)`
-
-API authentication middleware for server-to-server communication.
-
-**Parameters:**
-- `token` (string) - Secret token for authentication
-
-**Usage:**
-```javascript
-import { authenticate } from 'mbkauthe';
-
-app.post('/api/data', authenticate(process.env.API_TOKEN), (req, res) => {
-  res.json({ data: 'Protected API data' });
-});
-```
-
-**Headers Required:**
-```
-Authorization: Bearer your-secret-token
-```
-
-You can also send the raw token without the `Bearer` prefix.
-
-**Behavior:**
-- Checks `Authorization` header
-- Extracts the token (strips optional `Bearer` prefix)
-- Compares the provided token to the expected token using a timing-safe SHA-256 hash comparison
-- Returns 401 if token doesn't match
-
----
-
-## Error Codes
-
-### HTTP Status Codes
-
-| Code | Meaning | Usage |
-|------|---------|-------|
-| 200 | OK | Successful request |
-| 400 | Bad Request | Invalid input data |
-| 401 | Unauthorized | Authentication required or failed |
-| 403 | Forbidden | Insufficient permissions |
-| 404 | Not Found | Resource not found |
-| 429 | Too Many Requests | Rate limit exceeded |
-| 500 | Internal Server Error | Server-side error |
-
----
-
-## Code Examples
-
-### Basic Integration
-
-```javascript
-import express from 'express';
-import mbkauthe, { validateSession } from 'mbkauthe';
-import dotenv from 'dotenv';
-
-dotenv.config();
-
-// Configure MBKAuthe
-process.env.mbkautheVar = JSON.stringify({
-  APP_NAME: process.env.APP_NAME,
-  SESSION_SECRET_KEY: process.env.SESSION_SECRET_KEY,
-  IS_DEPLOYED: process.env.IS_DEPLOYED,
-  DOMAIN: process.env.DOMAIN,
-  LOGIN_DB: process.env.LOGIN_DB,
-  MBKAUTH_TWO_FA_ENABLE: process.env.MBKAUTH_TWO_FA_ENABLE,
-  COOKIE_EXPIRE_TIME: process.env.COOKIE_EXPIRE_TIME || 2,
-  loginRedirectURL: '/dashboard'
-});
-
-const app = express();
-
-// Mount MBKAuthe routes
-app.use(mbkauthe);
-
-// Protected route
-app.get('/dashboard', sessVal, (req, res) => {
-  res.send(`Welcome ${req.session.user.username}!`);
-});
-
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-```
-
----
-
-### Role-Based Access Control
-
-```javascript
-import { sessVal, roleChk, sessRole } from 'mbkauthe';
-
-// Method 1: Separate middleware
-app.get('/admin', 
-  sessVal, 
-  roleChk('SuperAdmin'), 
-  (req, res) => {
-    res.send('Admin panel');
-  }
-);
-
-// Method 2: Combined middleware
-app.get('/admin', 
-  sessRole('SuperAdmin'), 
-  (req, res) => {
-    res.send('Admin panel');
-  }
-);
-
-// Allow any role except Guest
-app.get('/content', 
-  sessVal,
-  roleChk('Any', 'Guest'),
-  (req, res) => {
-    res.send('Content for registered users');
-  }
-);
-
-// Multiple roles (using separate middleware)
-app.get('/moderator',
-  sessVal,
-  (req, res, next) => {
-    if (['SuperAdmin', 'NormalUser'].includes(req.session.user.role)) {
-      next();
-    } else {
-      res.status(403).send('Access denied');
-    }
-  },
-  (req, res) => {
-    res.send('Moderator panel');
-  }
-);
-```
-
----
-
-### API Authentication
-
-```javascript
-import { authenticate } from 'mbkauthe';
-
-// Simple token authentication
-app.post('/api/webhook', 
-  authenticate(process.env.WEBHOOK_SECRET), 
-  (req, res) => {
-    // Process webhook
-    res.json({ received: true });
-  }
-);
-
-// Admin API with token authentication
-app.post('/api/admin/terminate-sessions', 
-  authenticate(process.env.MAIN_SECRET_TOKEN), 
-  async (req, res) => {
-    // Terminate all sessions
-    res.json({ success: true });
-  }
-);
-
-// Protected API endpoint (requires session)
-app.get('/api/user/profile', 
-  sessVal,
-  async (req, res) => {
-    const { username } = req.session.user;
-    
-    // Fetch user profile
-    const profile = await getUserProfile(username);
-    
-    res.json({ success: true, profile });
-  }
-);
-```
-
----
-
-### Client-Side Login
-
-```javascript
-// Login form submission
-document.getElementById('loginForm').addEventListener('submit', async (e) => {
-  e.preventDefault();
-  
-  const username = document.getElementById('username').value;
-  const password = document.getElementById('password').value;
-  
-  try {
-    const response = await fetch('/mbkauthe/api/login', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ username, password })
-    });
-    
-    const data = await response.json();
-    
-    if (data.success) {
-      if (data.twoFactorRequired) {
-        // Redirect to 2FA page
-        window.location.href = '/mbkauthe/2fa';
-      } else {
-        // Login successful, redirect
-        window.location.href = data.redirectUrl || '/dashboard';
-      }
-    } else {
-      alert(data.message || 'Login failed');
-    }
-  } catch (error) {
-    console.error('Login error:', error);
-    alert('An error occurred during login');
-  }
-});
-```
-
----
-
-### Client-Side Logout
-
-```javascript
-async function logout() {
-  // Get CSRF token from page
-  const csrfToken = document.querySelector('[name="_csrf"]').value;
-  
-  try {
-    const response = await fetch('/mbkauthe/api/logout', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ _csrf: csrfToken })
-    });
-    
-    const data = await response.json();
-    
-    if (data.success) {
-      window.location.href = '/mbkauthe/login';
-    } else {
-      alert('Logout failed: ' + data.message);
-    }
-  } catch (error) {
-    console.error('Logout error:', error);
-  }
-}
-```
-
----
-
-### Database Access
-
-```javascript
-import { dblogin } from 'mbkauthe';
-
-// Custom query using the database pool
-app.get('/api/users', sessVal, roleChk('SuperAdmin'), async (req, res) => {
-  try {
-    const result = await dblogin.query(
-      'SELECT id, "UserName", "Role", "Active" FROM "Users" ORDER BY id'
-    );
-    
-    res.json({ 
-      success: true, 
-      users: result.rows 
-    });
-  } catch (error) {
-    console.error('Database error:', error);
-    res.status(500).json({ 
-      success: false, 
-      message: 'Internal Server Error' 
-    });
-  }
-});
-```
-
----
-
-### Error Handling
-
-```javascript
-// Custom error handler
-app.use((err, req, res, next) => {
-  console.error('Error:', err);
-  
-  if (err.code === 'EBADCSRFTOKEN') {
-    return res.status(403).json({ 
-      success: false, 
-      message: 'Invalid CSRF token' 
-    });
-  }
-  
-  res.status(500).json({ 
-    success: false, 
-    message: 'Internal Server Error' 
-  });
-});
-
-// 404 handler
-app.use((req, res) => {
-  res.status(404).render('Error/dError.handlebars', {
-    layout: false,
-    code: 404,
-    error: 'Not Found',
-    message: 'The requested page was not found.',
-    pagename: 'Home',
-    page: '/',
-  });
-});
-```
-
----
-
-## Security Best Practices
-
-1. **Always use HTTPS in production** - Set `IS_DEPLOYED=true` and ensure your server uses SSL/TLS
-2. **Keep SESSION_SECRET_KEY secure** - Use a strong, randomly generated key
-3. **Enable 2FA for sensitive applications** - Set `MBKAUTH_TWO_FA_ENABLE=true`
-4. **Validate all user input** - Never trust client-side data
-5. **Use rate limiting** - Already implemented for authentication endpoints
-6. **Keep dependencies updated** - Regularly update npm packages
-7. **Monitor for security vulnerabilities** - Use `npm audit`
-8. **Use prepared statements** - Prevent SQL injection (already implemented)
-9. **Implement proper logging** - Track authentication events
-10. **Regular security audits** - Review code and configurations
-
----
-
-## Rate Limits
-
-| Endpoint | Limit | Window |
-|----------|-------|--------|
-| `/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. Logged-in users are exempt from some rate limits (e.g., login page rate limit).
-
----
-
-## Support
-
-For issues, questions, or contributions:
-
-- **GitHub Issues:** [https://github.com/MIbnEKhalid/mbkauthe/issues](https://github.com/MIbnEKhalid/mbkauthe/issues)
-- **Email:** support@mbktech.org
-- **Documentation:** [https://github.com/MIbnEKhalid/mbkauthe](https://github.com/MIbnEKhalid/mbkauthe)
-
----
-
-**Last Updated:** November 17, 2025  
-**Version:** 1.4.2
-
-[← Back to README](../README.md)