5.2.1 • Published 3d ago

mbkauthe

Licence

LGPL-3.0-only

Version

5.2.1

Deps

Size

931 kB

Vulns

Weekly

Summary Dependency Versions

MBKAuthe - Node.js Authentication System

MBKAuthe is an open source authentication package for Node.js and Express, backed by PostgreSQL or SQLite. It handles login, session validation, role/app access checks, optional TOTP 2FA, OAuth login, API token authentication, and multi-session management.

Note: MBKAuthe is intentionally focused on authentication and session validation. The broader user, permission, and dashboard management system is a separate MBKTech product named MBKCore(closed source for now).

Features

Express middleware for session validation and role checks
PostgreSQL or SQLite storage for users, sessions, 2FA, trusted devices, and API tokens
Secure password authentication with PBKDF2
Optional TOTP 2FA with trusted devices
GitHub App and Google OAuth login flows
API token authentication with read-only/write scopes
Configurable multi-session support per user
CSRF protection, rate limiting, secure cookies, and session fixation prevention
Customizable Handlebars views
Vercel/serverless-friendly deployment support
Dev-only DB Query Monitor with callsite, timing, request context, and pool stats

Installation

npm install mbkauthe

Quick Start

Copy the environment template.

Copy-Item .env.example .env

Configure environment values.

See the configuration guide for mbkautheVar, mbkauthShared, OAuth settings, session settings, and deployment flags.

Choose a database backend.

MBKAuthe supports two backends, selected with DB_TYPE in mbkautheVar:

PostgreSQL (default) - set LOGIN_DB to a connection string. Recommended for production and multi-instance deployments.
SQLite - set DB_TYPE to sqlite and SQLITE_PATH to a file path (created if missing). No database server required - convenient for development, tests, and small single-instance deployments. Uses better-sqlite3 with WAL mode; expect -wal/-shm side files next to the database file. See the SQLite backend notes in the database guide.

Create database tables.

npm run create-tables

The script applies docs/schema/db.sql (PostgreSQL) or docs/schema/db.sqlite.sql (SQLite) to the configured backend. You can also run the matching SQL file yourself.

The schema includes a default SuperAdmin user (support / 12345678). Change that password immediately. See the database guide.

Mount MBKAuthe in Express.

import express from "express";
import dotenv from "dotenv";
import mbkauthe, { sessVal, roleChk, sessRole } from "mbkauthe";

dotenv.config();

const app = express();

app.use(mbkauthe);

app.get("/dashboard", sessVal, (req, res) => {
  res.send(`Welcome ${req.session.user.username}!`);
});

app.get("/admin", sessVal, roleChk("SuperAdmin"), (req, res) => {
  res.send("Admin Panel");
});

// Or combine session and role checks into one middleware:
app.get("/admin", sessRole("SuperAdmin"), (req, res) => {
  res.send("Admin Panel");
});

app.listen(3000);

Common Exports

sessVal / validateSession - require a valid session or API token.
roleChk / checkRolePermission - require a role after session validation.
sessRole / validateSessionAndRole - combine session and role checks.
strictValidateSession - require cookie session authentication only.
strictValidateSessionAndRole - strict cookie session plus role check.
authenticate(token) - protect server-to-server routes with a static bearer token.
dblogin - access the configured database pool (pg.Pool or the SQLite adapter, per DB_TYPE).
dbType - the active backend: "postgres" or "sqlite".

See the API reference for endpoints, middleware, examples, security notes, and rate limits.

JSON Error Responses

Browser page routes usually render HTML errors, while API/AJAX-style requests receive JSON. MBKAuthe treats a request as JSON when any of these are true:

The path starts with /mbkauthe/api/ or /api/
X-Requested-With: XMLHttpRequest
Accept prefers JSON and does not explicitly prefer text/html
User-Agent looks like a non-browser client such as curl, wget, or Postman
User-Agent: json

curl -i -H "User-Agent: json" http://localhost:3000/mbkauthe/test

Development

npm test
npm run test:watch
npm run dev

Development-only diagnostics are mounted when process.env.env === "dev":

/mbkauthe/db - DB Query Monitor UI
/mbkauthe/db.json - DB Query Monitor JSON
/mbkauthe/db/reset - reset diagnostic query logs
/mbkauthe/validate-superadmin - SuperAdmin validation check

Documentation

Deployment Checklist

Set IS_DEPLOYED=true
Use strong SESSION_SECRET_KEY and Main_SECRET_TOKEN values
Enable HTTPS
Set the correct DOMAIN
Set an appropriate COOKIE_EXPIRE_TIME
Store secrets in environment variables
Configure OAuth credentials only when the matching provider is enabled
If using the SQLite backend, put SQLITE_PATH on persistent disk (not ephemeral/serverless storage) and back up the database together with its -wal/-shm side files

Vercel deployments can use shared OAuth credentials through mbkauthShared.