mbkauthe 4.6.2 → 4.7.1

package/README.md

@@ -30,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
 
@@ -46,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**
@@ -81,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
@@ -102,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.

package/docs/db.sql

@@ -138,7 +138,10 @@ INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount"
 VALUES ('support', '12345678', 'SuperAdmin', true, false, 'Support User')
 ON CONFLICT ("UserName") DO NOTHING;
 
-SELECT * FROM "Users" WHERE "UserName" = 'support';
+INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount", "FullName")
+VALUES ('admin', '12345678', 'SuperAdmin', true, false, 'Admin User')
+ON CONFLICT ("UserName") DO NOTHING;
+
 
 -- API Tokens for persistent programmatic access
 CREATE TABLE IF NOT EXISTS "ApiTokens" (

package/docs/env.md

@@ -81,6 +81,12 @@ This document describes the environment variables MBKAuth expects and keeps brie
   - Example: `"loginRedirectURL":"/dashboard"`
   - Required: No
 
+- env
+  - Description: Development flag to enable diagnostics (DB query monitor, debug endpoints).
+  - Values: `dev` to enable; any other value disables.
+  - Example: `env=dev`
+  - Required: No
+
 - bucket
   - Description: Optional external storage bucket name or identifier used for static assets or third-party integrations.
   - Default: an empty string `""` (no bucket configured)

package/index.js

@@ -5,6 +5,7 @@ import { engine } from "express-handlebars";
 import path from "path";
 import { fileURLToPath } from "url";
 import { renderError, renderPage } from "#response.js";
+import { packageJson } from "#config.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -43,6 +44,9 @@ app.engine("handlebars", engine({
                 return []; // Return an empty array if obj is undefined, null, or not an object
             }
             return Object.entries(obj).map(([key, value]) => ({ key, value }));
+        },
+        cacheBuster: function () {
+            return packageJson.version;
         }
     }
 
@@ -59,7 +63,7 @@ if (process.env.test === "dev") {
             return res.redirect("/mbkauthe/");
     });
     app.get("/dev/2fa", (req, res) => {
-            return renderPage(req, res, "2fa", {
+            return renderPage(req, res, "pages/2fa.handlebars", {
                 layout: false,
                 pagename: "Two-Factor Authentication",
                 page: "/home"
@@ -109,7 +113,8 @@ export {
     sessionConfig,
     corsMiddleware,
     sessionRestorationMiddleware,
-    sessionCookieSyncMiddleware
+    sessionCookieSyncMiddleware,
+    requestContextMiddleware
 } from "./lib/middleware/index.js";
 export { validateTokenScope } from "./lib/middleware/scopeValidator.js";
 export { renderError, getUserContext, renderPage, proxycall } from "#response.js";

package/lib/main.js

@@ -6,11 +6,13 @@ import {
   sessionConfig,
   corsMiddleware,
   sessionRestorationMiddleware,
-  sessionCookieSyncMiddleware
+  sessionCookieSyncMiddleware,
+  requestContextMiddleware
 } from "./middleware/index.js";
 import authRoutes from "./routes/auth.js";
 import oauthRoutes from "./routes/oauth.js";
 import miscRoutes from "./routes/misc.js";
+import dbLogsRoutes from "./routes/dbLogs.js";
 import { fileURLToPath } from "url";
 import path from "path";
 
@@ -45,6 +47,11 @@ router.use(session(sessionConfig));
 // Session restoration
 router.use(sessionRestorationMiddleware);
 
+// Attach request context for DB query logging (dev only)
+if (process.env.env === 'dev') {
+  router.use(requestContextMiddleware);
+}
+
 // Initialize passport
 router.use(passport.initialize());
 router.use(passport.session());
@@ -57,6 +64,10 @@ router.use('/mbkauthe', authRoutes);
 router.use('/mbkauthe', oauthRoutes);
 router.use('/mbkauthe', miscRoutes);
 
+if (process.env.env === 'dev') {
+  router.use('/mbkauthe', dbLogsRoutes);
+}
+
 // Redirect shortcuts for login
 router.get(["/login", "/signin"], async (req, res) => {
   const queryParams = new URLSearchParams(req.query).toString();
@@ -64,7 +75,7 @@ router.get(["/login", "/signin"], async (req, res) => {
   return res.redirect(redirectUrl);
 });
 
-router.get(['/icon.svg',"/favicon.ico", "/icon.png"], (req, res) => {
+router.get(['/icon.svg', "/favicon.ico", "/icon.png"], (req, res) => {
   res.setHeader('Cache-Control', 'public, max-age=31536000');
   res.sendFile(path.join(__dirname, '..', 'public', 'M.png'));
 });

package/lib/middleware/index.js

@@ -1,7 +1,7 @@
 import session from "express-session";
 import pgSession from "connect-pg-simple";
 const PgSession = pgSession(session);
-import { dblogin } from "#pool.js";
+import { dblogin, runWithRequestContext } from "#pool.js";
 import { mbkautheVar } from "#config.js";
 import { cachedCookieOptions, decryptSessionId, encryptSessionId } from "#cookies.js";
 
@@ -142,4 +142,9 @@ export function sessionCookieSyncMiddleware(req, res, next) {
     }
   }
   next();
+}
+
+// Request context middleware (used for DB query logging)
+export function requestContextMiddleware(req, res, next) {
+  return runWithRequestContext(req, () => next());
 }

package/lib/pool.js

@@ -21,7 +21,28 @@ const poolConfig = {
 
 export const dblogin = new Pool(poolConfig);
 
-if(process.env.env === 'dev') {
+
+
+// For logging and testing purposes, we can track query counts and logs in development mode.
+
+import path from "path";
+import { AsyncLocalStorage } from "async_hooks";
+
+const isDev = process.env.env === 'dev';
+const requestContext = isDev ? new AsyncLocalStorage() : null;
+
+export const runWithRequestContext = (req, fn) => {
+  if (!isDev || !requestContext) return fn();
+  return requestContext.run({ req }, fn);
+};
+
+export const getRequestContext = () => {
+  if (!isDev || !requestContext) return undefined;
+  return requestContext.getStore();
+};
+
+if (isDev) {
+
   // Simple counter for all DB requests made via this pool. This is intentionally
   // lightweight.
   let _dbQueryCount = 0;
@@ -36,29 +57,133 @@ if(process.env.env === 'dev') {
     // Track query text for debugging/metrics.
     // `pg` supports (text, values, callback) or (config, callback).
     let queryText = '';
+    let queryName = '';
+    let queryValues;
     try {
       if (typeof args[0] === 'string') {
         queryText = args[0];
+        queryValues = Array.isArray(args[1]) ? args[1] : undefined;
       } else if (args[0] && typeof args[0] === 'object') {
         queryText = args[0].text || '';
+        queryName = args[0].name || '';
+        queryValues = Array.isArray(args[0].values) ? args[0].values : undefined;
       }
     } catch {
       queryText = '';
     }
 
-    if (queryText) {
+    if (!queryText) {
+      return _origQuery(...args);
+    }
+
+    const startTime = process.hrtime.bigint();
+    const toWorkspacePath = (filePath) => {
+      const rel = path.relative(process.cwd(), filePath) || filePath;
+      return rel.replace(/\\/g, '/');
+    };
+
+    const buildCallsite = () => {
+      try {
+        const stack = new Error().stack || '';
+        const lines = stack.split('\n').map(l => l.trim());
+        // Skip frames from this wrapper and node internals; pick first app frame.
+        const frame = lines.find((line) =>
+          line.startsWith('at ') &&
+          !line.includes('/lib/pool.js') &&
+          !line.includes('node:internal') &&
+          !line.includes('internal/process')
+        );
+
+        if (!frame) return null;
+
+        const withFunc = /^at\s+([^\s(]+)\s+\((.+):([0-9]+):([0-9]+)\)$/.exec(frame);
+        const noFunc = /^at\s+(.+):([0-9]+):([0-9]+)$/.exec(frame);
+
+        if (withFunc) {
+          return {
+            function: withFunc[1],
+            file: toWorkspacePath(withFunc[2]),
+            line: Number(withFunc[3]),
+            column: Number(withFunc[4])
+          };
+        }
+        if (noFunc) {
+          return {
+            function: null,
+            file: toWorkspacePath(noFunc[1]),
+            line: Number(noFunc[2]),
+            column: Number(noFunc[3])
+          };
+        }
+      } catch {
+        return null;
+      }
+      return null;
+    };
+
+    const buildRequestContext = () => {
+      const store = getRequestContext();
+      const req = store?.req;
+      if (!req) return null;
+
+      const user = req.session?.user || null;
+      return {
+        method: req.method,
+        url: req.originalUrl || req.url,
+        ip: req.ip,
+        userId: user?.id || null,
+        username: user?.username || null
+      };
+    };
+
+    const callsiteSnapshot = buildCallsite();
+
+    const recordLog = (success, error) => {
+      const durationMs = Number(process.hrtime.bigint() - startTime) / 1_000_000;
+      const request = buildRequestContext();
+
       _dbQueryLog.push({
         time: new Date().toISOString(),
         query: queryText,
-        values: Array.isArray(args[1]) ? args[1] : undefined
+        name: queryName || undefined,
+        values: queryValues,
+        durationMs,
+        success,
+        error: error ? { message: error.message, code: error.code } : undefined,
+        request,
+        pool: {
+          total: dblogin.totalCount,
+          idle: dblogin.idleCount,
+          waiting: dblogin.waitingCount
+        },
+        callsite: callsiteSnapshot
       });
 
       if (_dbQueryLog.length > _MAX_QUERY_LOG_ENTRIES) {
         _dbQueryLog.shift();
       }
-    }
+    };
+
+    try {
+      const result = _origQuery(...args);
+      if (result && typeof result.then === 'function') {
+        return result
+          .then((res) => {
+            recordLog(true, null);
+            return res;
+          })
+          .catch((err) => {
+            recordLog(false, err);
+            throw err;
+          });
+      }
 
-    return _origQuery(...args);
+      recordLog(true, null);
+      return result;
+    } catch (err) {
+      recordLog(false, err);
+      throw err;
+    }
   };
 
   // Public helpers

package/lib/routes/auth.js

@@ -517,7 +517,7 @@ router.get("/2fa", csrfProtection, (req, res) => {
     redirectToUse = mbkautheVar.loginRedirectURL || '/dashboard';
   }
 
-  res.render("2fa.handlebars", {
+  res.render("pages/2fa.handlebars", {
     layout: false,
     customURL: redirectToUse,
     csrfToken: req.csrfToken(),
@@ -828,7 +828,7 @@ router.post("/api/logout-all", LoginLimit, async (req, res) => {
 // GET /mbkauthe/login
 router.get("/login", LoginLimit, csrfProtection, (req, res) => {
   const lastLogin = req.cookies && typeof req.cookies.lastLoginMethod === 'string' ? req.cookies.lastLoginMethod : null;
-  return res.render("loginmbkauthe.handlebars", {
+  return res.render("pages/loginmbkauthe.handlebars", {
     layout: false,
     githubLoginEnabled: mbkautheVar.GITHUB_LOGIN_ENABLED,
     googleLoginEnabled: mbkautheVar.GOOGLE_LOGIN_ENABLED,
@@ -853,7 +853,7 @@ router.get("/accounts", LoginLimit, csrfProtection, (req, res) => {
     ? redirectFromQuery
     : (mbkautheVar.loginRedirectURL || '/dashboard');
 
-  return res.render("accountSwitch.handlebars", {
+  return res.render("pages/accountSwitch.handlebars", {
     layout: false,
     customURL: safeRedirect,
     version: packageJson.version,

package/lib/routes/dbLogs.js

@@ -0,0 +1,67 @@
+import express from "express";
+import { renderError } from "#response.js";
+import { dblogin } from "#pool.js";
+import { mbkautheVar } from "#config.js";
+import rateLimit from 'express-rate-limit';
+
+const router = express.Router();
+
+// Rate limiter for info/test routes
+const LogLimit = rateLimit({
+  windowMs: 1 * 60 * 1000,
+  max: 50,
+  message: { success: false, message: "Too many attempts, please try again later" },
+  skip: (req) => {
+    return !!req.session.user;
+  },
+  validate: {
+    trustProxy: false,
+    xForwardedForHeader: false
+  }
+});
+
+// DB stats API (JSON)
+router.get(["/db.json"], LogLimit, async (req, res) => {
+  try {
+    const queryCount = typeof dblogin.getQueryCount === 'function' ? dblogin.getQueryCount() : null;
+    const queryLimit = Number(req.query.limit) || 50;
+    const queryLog = typeof dblogin.getQueryLog === 'function' ? dblogin.getQueryLog({ limit: queryLimit }) : [];
+    const resetRequested = req.query.reset === '1';
+
+    if (resetRequested) {
+      if (typeof dblogin.resetQueryCount === 'function') dblogin.resetQueryCount();
+      if (typeof dblogin.resetQueryLog === 'function') dblogin.resetQueryLog();
+    }
+
+    return res.json({ queryCount, queryLimit, queryLog, resetDone: resetRequested });
+  } catch (err) {
+    console.error('[mbkauthe] /db.json route error:', err);
+    return res.status(500).json({ success: false, message: 'Could not fetch DB stats.' });
+  }
+});
+
+// DB stats page (HTML)
+router.get(["/db"], LogLimit, async (req, res) => {
+  try {
+    const queryLimit = Number(req.query.limit) || 50;
+    const resetDone = req.query.resetDone === '1';
+    return res.render('pages/dbLogs.handlebars', {
+      layout: false,
+      appName: mbkautheVar.APP_NAME,
+      queryLimit,
+      resetDone
+    });
+  } catch (err) {
+    console.error('[mbkauthe] /db route error:', err);
+    return renderError(res, req, {
+      layout: false,
+      code: 500,
+      error: "Internal Server Error",
+      message: "Could not fetch DB stats.",
+      pagename: "DB Stats",
+      page: "/mbkauthe/info",
+    });
+  }
+});
+
+export default router;