mbkauthe 4.6.1 → 4.7.0

package/README.md

@@ -13,6 +13,9 @@
 
 **MBKAuthe** is a production-ready authentication system for Node.js with Express and PostgreSQL. Features include secure login, 2FA, role-based access, OAuth (GitHub & Google), multi-session support, and multi-app user management.
 
+## Todo
+- Currently, for every request to a protected page, a database query is made to retrieve authentication information (allowed apps, username, session ID, role, etc.). We should implement a caching mechanism to reduce this overhead, but also find a way to allow administrators to log users out and update permissions in near real-time.
+
 ## ✨ Key Features
 
 - Secure password authentication (PBKDF2)
@@ -27,6 +30,7 @@
 - Session fixation prevention
 - Dynamic profile picture routing with session caching
 - Modern responsive UI with desktop two-column layout
+- Dev-only DB Query Monitor with callsite, timing, and request context
 
 ## 📦 Installation
 
@@ -43,7 +47,7 @@ Copy-Item .env.example .env
 ```
 See [docs/env.md](docs/env.md).
 
-**2. Set Up Database**  
+**2. Set Up Database**
 Run [docs/db.sql](docs/db.sql) to create tables and a default SuperAdmin (`support` / `12345678`). Change the password immediately. See [docs/db.md](docs/db.md).
 
 **3. Integrate with Express**
@@ -78,6 +82,14 @@ npm run dev
 - **Combined:** `validateSessionAndRole(['SuperAdmin', 'NormalUser'])`
 - **API Token Auth:** `authenticate(process.env.API_TOKEN)`
 
+## 🧰 Diagnostics (dev only)
+
+These are only mounted when `process.env.env === "dev"`:
+
+- **DB Query Monitor (HTML):** `/mbkauthe/db`
+- **DB Query Monitor (JSON):** `/mbkauthe/db.json`
+- **SuperAdmin check:** `/mbkauthe/validate-superadmin`
+
 ## 🔐 Security
 
 - Rate limiting, CSRF protection, secure cookies
@@ -99,6 +111,18 @@ Enable via `MBKAUTH_TWO_FA_ENABLE=true`. Trusted devices can skip 2FA for a set
 - **Custom Views:** `views/loginmbkauthe.handlebars`, `2fa.handlebars`, `Error/dError.handlebars`
 - **Database Access:** `import { dblogin } from 'mbkauthe'; const result = await dblogin.query('SELECT * FROM "Users"');`
 
+## 📄 API Reference
+
+- Full endpoint list and details: [docs/api.md](docs/api.md)
+
+## 🧰 Diagnostics (dev only)
+
+- **DB Query Monitor (HTML):** `/mbkauthe/db`
+- **DB Query Monitor (JSON):** `/mbkauthe/db.json`
+- **SuperAdmin check:** `/mbkauthe/debug/validate-superadmin`
+
+These routes are only mounted when `process.env.env === "dev"`. They expose query timing, status/error, pool stats, request context, and callsite data for troubleshooting.
+
 ## 🚢 Deployment
 
 Checklist for production:

package/docs/api.md

@@ -15,6 +15,8 @@ This document provides comprehensive API documentation for MBKAuthe authenticati
   - [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)
 
@@ -195,6 +197,150 @@ GET /mbkauthe/login?redirect=/dashboard
 
 ---
 
+#### `GET /mbkauthe/2fa`
+
+Renders the 2FA challenge page after a login that requires TOTP.
+
+**Rate Limit:** 5 requests per minute
+
+---
+
+#### `GET /mbkauthe/accounts`
+
+Renders the account-switch page for remembered sessions on the device.
+
+**Rate Limit:** 8 requests per minute
+
+---
+
+#### `GET /mbkauthe/test`
+
+Renders a test page for the current session context.
+
+**Rate Limit:** 8 requests per minute
+
+---
+
+#### `POST /mbkauthe/test`
+
+Lightweight check to verify an authenticated session.
+
+**Response:** `{ "success": true, "message": "You are logged in" }`
+
+---
+
+## Diagnostics (Dev Only)
+
+These endpoints are only mounted when `process.env.env === "dev"`.
+
+#### `GET /mbkauthe/db`
+
+Renders the DB Query Monitor page. The UI fetches data from `/mbkauthe/db.json`.
+
+**Query Parameters:**
+- `limit` (optional) - number of most recent queries to show (default: 50)
+- `resetDone` (optional) - UI notification flag used after reset
+
+---
+
+#### `GET /mbkauthe/db.json`
+
+Returns recent DB query diagnostics.
+
+**Query Parameters:**
+- `limit` (optional) - number of most recent queries to return (default: 50)
+- `reset` (optional) - set to `1` to clear the query log and counter
+
+**Response Body:**
+```json
+{
+  "queryCount": 120,
+  "queryLimit": 50,
+  "resetDone": false,
+  "queryLog": [
+    {
+      "time": "2026-03-19T12:00:00.000Z",
+      "name": "login-get-user",
+      "query": "SELECT ...",
+      "values": ["user"],
+      "durationMs": 3.42,
+      "success": true,
+      "error": null,
+      "request": {
+        "method": "GET",
+        "url": "/mbkauthe/login",
+        "ip": "::1",
+        "userId": 1,
+        "username": "support"
+      },
+      "pool": {
+        "total": 2,
+        "idle": 1,
+        "waiting": 0
+      },
+      "callsite": {
+        "function": "validateSession",
+        "file": "lib/middleware/auth.js",
+        "line": 197,
+        "column": 30
+      }
+    }
+  ]
+}
+```
+
+---
+
+#### `GET /mbkauthe/validate-superadmin`
+
+Validates that the current session has `SuperAdmin` role and returns a JSON summary.
+
+---
+
+## Additional Endpoints
+
+The endpoints below are active in the router but are not fully expanded above. Use this list as a reference.
+
+**Auth & Session:**
+
+- `POST /mbkauthe/api/verify-2fa` - Verifies TOTP and completes login.
+- `POST /mbkauthe/api/logout` - Logs out the current session.
+- `GET /mbkauthe/api/account-sessions` - Lists remembered accounts for the current device.
+- `POST /mbkauthe/api/switch-session` - Switches active session to another remembered account.
+- `POST /mbkauthe/api/logout-all` - Logs out all remembered accounts on the device.
+
+**Session Validation:**
+
+- `GET /mbkauthe/api/checkSession` - Checks session validity (cookie-based).
+- `POST /mbkauthe/api/checkSession` - Checks session validity by sessionId (body).
+- `POST /mbkauthe/api/verifySession` - Returns session details by sessionId (body).
+
+**OAuth:**
+
+- `GET /mbkauthe/api/github/login` - Starts GitHub OAuth login flow.
+- `GET /mbkauthe/api/github/login/callback` - GitHub OAuth callback.
+- `GET /mbkauthe/api/google/login` - Starts Google OAuth login flow.
+- `GET /mbkauthe/api/google/login/callback` - Google OAuth callback.
+
+**Info & UI:**
+
+- `GET /mbkauthe/info` and `GET /mbkauthe/i` - Info page.
+- `GET /mbkauthe/info.json` and `GET /mbkauthe/i.json` - Info page JSON.
+- `GET /mbkauthe/ErrorCode` - Error codes page.
+- `GET /mbkauthe/user/profilepic` - User profile picture proxy.
+
+**Admin:**
+
+- `POST /mbkauthe/api/terminateAllSessions` - Terminates all sessions (requires `Main_SECRET_TOKEN`).
+
+**Static Assets:**
+
+- `GET /mbkauthe/main.js`
+- `GET /mbkauthe/main.css`
+- `GET /mbkauthe/bg.webp`
+
+---
+
 #### `POST /mbkauthe/api/login`
 
 Authenticates a user and creates a session.