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.

• 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.

• Secure password authentication (PBKDF2)
• PostgreSQL session management
• Multi-session support (configurable concurrent sessions per user)
• Optional TOTP-based 2FA with trusted devices
• OAuth login (GitHub & Google)
• Role-based access: SuperAdmin, NormalUser, Guest
• CSRF protection & rate limiting
• Easy Express.js integration
• Customizable Handlebars templates
• 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

npm install mbkauthe

1. Configure Environment

Copy-Item .env.example .env

See docs/env.md.

2. Set Up Database Run docs/db.sql to create tables and a default SuperAdmin (support / 12345678). Change the password immediately. See docs/db.md.

3. Integrate with Express

import express from 'express';
import mbkauthe, { validateSession, checkRolePermission } from 'mbkauthe';
import dotenv from 'dotenv';
dotenv.config();

const app = express();
app.use(mbkauthe);

app.get('/dashboard', validateSession, (req, res) => res.send(`Welcome ${req.session.user.username}!`));
app.get('/admin', validateSession, checkRolePermission(['SuperAdmin']), (req, res) => res.send('Admin Panel'));

app.listen(3000);

npm test
npm run test:watch
npm run dev

• Session Validation: validateSession
• Role Check: checkRolePermission(['Role'])
• Combined: validateSessionAndRole(['SuperAdmin', 'NormalUser'])
• API Token Auth: authenticate(process.env.API_TOKEN)

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

• Rate limiting, CSRF protection, secure cookies
• Password hashing (PBKDF2, 100k iterations)
• PostgreSQL-backed sessions with automatic cleanup
• OAuth with state validation and secure callbacks

Enable via MBKAUTH_TWO_FA_ENABLE=true. Trusted devices can skip 2FA for a set duration.

GitHub / Google OAuth: Configure apps and credentials via .env or mbkautheVar. Users must link accounts before login.

• Redirect URL: mbkautheVar={"loginRedirectURL":"/dashboard"}
• Custom Views: views/loginmbkauthe.handlebars, 2fa.handlebars, Error/dError.handlebars
• Database Access: import { dblogin } from 'mbkauthe'; const result = await dblogin.query('SELECT * FROM "Users"');

• Full endpoint list and details: docs/api.md

• 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.

Checklist for production:

• IS_DEPLOYED=true
• Strong secrets for SESSION_SECRET_KEY & Main_SECRET_TOKEN
• HTTPS enabled
• Correct DOMAIN & COOKIE_EXPIRE_TIME
• Use environment variables for all secrets

Vercel: Supports shared OAuth credentials via mbkauthShared.

• API Reference
• Database Schema
• Environment Config
• Error Codes

GPL v2.0 — see LICENSE

Muhammad Bin Khalid
📧 [email protected] | [email protected]
🔗 GitHub @MIbnEKhalid

• npm
• GitHub
• Support

Made with ❤️ by MBKTech.org