mbkauthe 5.0.2 → 5.1.0

package/README.md

@@ -1,8 +1,8 @@
 # MBKAuthe - Node.js Authentication System
 
 [![Version](https://img.shields.io/npm/v/mbkauthe.svg)](https://www.npmjs.com/package/mbkauthe)
-[![License](https://img.shields.io/badge/License-GPL--2.0-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/License-LGPL--3.0-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Publish](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/MIbnEKhalid/mbkauthe/actions/workflows/publish.yml)
 [![Downloads](https://img.shields.io/npm/dm/mbkauthe.svg)](https://www.npmjs.com/package/mbkauthe)
 
@@ -61,7 +61,7 @@ The schema includes a default SuperAdmin user (`support` / `12345678`). Change t
 ```javascript
 import express from "express";
 import dotenv from "dotenv";
-import mbkauthe, { sessVal, roleChk } from "mbkauthe";
+import mbkauthe, { sessVal, roleChk, sessRole } from "mbkauthe";
 
 dotenv.config();
 
@@ -77,6 +77,11 @@ 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);
 ```
 
@@ -149,7 +154,7 @@ Vercel deployments can use shared OAuth credentials through `mbkauthShared`.
 
 ## License
 
-GPL v2.0 - see [LICENSE](LICENSE).
+LGPL v3.0 - see [LICENSE](LICENSE).
 
 ## Author
 

package/docs/guides/configuration.md

@@ -35,7 +35,7 @@ This document describes the environment variables MBKAuth expects and keeps brie
   - Required: Yes
 
 - DOMAIN
-  - Description: App domain (e.g., `localhost` or `yourdomain.com`). Required when deployed.
+  - Description: Root app domain used for cross-subdomain cookie sharing in production (e.g., `yourdomain.com`, not `auth.yourdomain.com`). When `IS_DEPLOYED=true`, session cookies are scoped to `.yourdomain.com` so they are sent on all subdomains.
   - Example: `"DOMAIN":"localhost"`
   - Required: Yes
 
@@ -95,11 +95,6 @@ This document describes the environment variables MBKAuth expects and keeps brie
   - If `GOOGLE_LOGIN_ENABLED=true`, `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are required.
   - If `GITHUB_LOGIN_ENABLED=true`, GitHub App client credentials are required.
 
-- GITHUB_APP_SLUG
-  - Description: GitHub App slug (optional for login flow in this package; useful for install/link flows handled elsewhere).
-  - Required: No
-  - Create GitHub App: https://github.com/settings/apps
-
 - GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET
   - Description: GitHub App OAuth credentials used for user sign-in.
   - Required when `GITHUB_LOGIN_ENABLED=true`.

package/docs/guides/database.md

@@ -16,7 +16,7 @@ Postgres enum `role`: `SuperAdmin`, `NormalUser`, `Guest`, `member`. The script
 
 Core accounts table (`"Users"`): username, activation flag, role, mail flag, `AllowedApps` and `Positions` as JSONB, timestamps, optional `last_login`, and password hash column `PasswordEnc` (no plaintext passwords).
 
-Profile-style columns include `FullName`, `email`, `Image`, `Bio`, `SocialAccounts`, and password-reset fields (`resetToken`, `resetTokenExpires`, `resetAttempts`, `lastResetAttempt`).
+Profile-style columns include `FullName`, `UserId` (exactly 9 characters, unique business identifier assigned externally), `email`, `Image`, `Bio`, `SocialAccounts`, and password-reset fields (`resetToken`, `resetTokenExpires`, `resetAttempts`, `lastResetAttempt`).
 
 Indexes cover username, role, active, email, last login, and GIN indexes on JSONB for `AllowedApps` and `Positions`. The SQL file also adds optional covering indexes used on hot auth paths.
 

package/docs/schema/db.sql

@@ -17,13 +17,16 @@ CREATE TABLE IF NOT EXISTS "Users" (
     last_login timestamp with time zone,
     "PasswordEnc" character varying(255),
     "FullName" character varying(100),
+    "UserId" character varying(9),
     email text DEFAULT 'support@mbktech.org'::text,
     "Image" text DEFAULT 'https://portal.mbktech.org/icon.svg'::text,
     "Bio" text DEFAULT 'I am ....'::text,
     "SocialAccounts" text DEFAULT '{}'::text,
     "Positions" jsonb DEFAULT '{"Not_Permanent": "Member Is Not Permanent"}'::jsonb,
     CONSTRAINT "Users_pkey" PRIMARY KEY (id),
-    CONSTRAINT "Users_UserName_key" UNIQUE ("UserName")
+    CONSTRAINT "Users_UserName_key" UNIQUE ("UserName"),
+    CONSTRAINT "Users_UserId_key" UNIQUE ("UserId"),
+    CONSTRAINT chk_users_userid_length CHECK ("UserId" IS NULL OR length("UserId") = 9)
 );
 CREATE INDEX IF NOT EXISTS idx_users_active ON "Users" USING btree ("Active");
 CREATE INDEX IF NOT EXISTS idx_users_allowedapps_gin ON "Users" USING gin ("AllowedApps");
@@ -32,6 +35,7 @@ CREATE INDEX IF NOT EXISTS idx_users_last_login ON "Users" USING btree (last_log
 CREATE INDEX IF NOT EXISTS idx_users_positions_gin ON "Users" USING gin ("Positions");
 CREATE INDEX IF NOT EXISTS idx_users_role ON "Users" USING btree ("Role");
 CREATE INDEX IF NOT EXISTS idx_users_username_cover ON "Users" USING btree ("UserName") INCLUDE ("Active", "Role");
+CREATE INDEX IF NOT EXISTS idx_users_userid ON "Users" USING btree ("UserId");
 COMMENT ON TABLE "Users" IS '[core]';
 
 -- Table: ApiTokens
@@ -326,3 +330,20 @@ COMMENT ON TABLE "website_access_logs" IS '[core]';
 INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "FullName")
 VALUES ('support', 'b8b10c1c9006d8c30ab81c412463c65ff6dae3293d9bfbaf5fd8e275081d0947f000a828004e2fbd3a8f6ef5a35ae3eddd4c57b00ecab376b12e607a16a57459', 'SuperAdmin', true, false, 'Support User')
 ON CONFLICT ("UserName") DO NOTHING;
+
+-- Migration: add UserId to existing Users tables (idempotent)
+ALTER TABLE "Users" ADD COLUMN IF NOT EXISTS "UserId" character varying(9);
+
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'Users_UserId_key'
+    ) THEN
+        ALTER TABLE "Users" ADD CONSTRAINT "Users_UserId_key" UNIQUE ("UserId");
+    END IF;
+END $$;
+
+ALTER TABLE "Users" DROP CONSTRAINT IF EXISTS chk_users_userid_length;
+ALTER TABLE "Users" ADD CONSTRAINT chk_users_userid_length CHECK ("UserId" IS NULL OR length("UserId") = 9);
+
+CREATE INDEX IF NOT EXISTS idx_users_userid ON "Users" USING btree ("UserId");

package/index.d.ts

@@ -19,7 +19,7 @@ declare global {
 
     interface Session {
       user?: {
-        id: number;
+        userId?: string;
         username: string;
         fullname?: string;
         role: 'SuperAdmin' | 'NormalUser' | 'Guest';
@@ -28,7 +28,7 @@ declare global {
         tokenScope?: 'read-only' | 'write' | null;
       };
       preAuthUser?: {
-        id: number;
+        userId?: string;
         username: string;
         role: 'SuperAdmin' | 'NormalUser' | 'Guest';
         loginMethod?: 'password' | 'github' | 'google';
@@ -55,7 +55,6 @@ declare module 'mbkauthe' {
     COOKIE_EXPIRE_TIME?: number;
     DEVICE_TRUST_DURATION_DAYS?: number;
     GITHUB_LOGIN_ENABLED?: 'true' | 'false' | 'f';
-    GITHUB_APP_SLUG?: string;
     GITHUB_APP_CLIENT_ID?: string;
     GITHUB_APP_CLIENT_SECRET?: string;
     GOOGLE_LOGIN_ENABLED?: 'true' | 'false' | 'f';
@@ -67,7 +66,6 @@ declare module 'mbkauthe' {
 
   export interface OAuthConfig {
     GITHUB_LOGIN_ENABLED?: 'true' | 'false' | 'f';
-    GITHUB_APP_SLUG?: string;
     GITHUB_APP_CLIENT_ID?: string;
     GITHUB_APP_CLIENT_SECRET?: string;
     GOOGLE_LOGIN_ENABLED?: 'true' | 'false' | 'f';
@@ -79,7 +77,7 @@ declare module 'mbkauthe' {
   export type UserRole = 'SuperAdmin' | 'NormalUser' | 'Guest';
 
   export interface SessionUser {
-    id: number;
+    userId?: string;
     username: string;
     fullname?: string;
     role: UserRole;
@@ -88,7 +86,7 @@ declare module 'mbkauthe' {
   }
 
   export interface PreAuthUser {
-    id: number;
+    userId?: string;
     username: string;
     role: UserRole;
     allowedApps?: string[];
@@ -100,6 +98,7 @@ declare module 'mbkauthe' {
   export interface DBUser {
     id: number;
     UserName: string;
+    UserId?: string;
     PasswordEnc?: string;
     Role: UserRole;
     Active: boolean;
@@ -300,6 +299,18 @@ declare module 'mbkauthe' {
     httpOnly: boolean;
   };
 
+  export function resolveCookieDomain(
+    isDeployed: 'true' | 'false' | 'f' | string,
+    domain?: string,
+    isTestDev?: boolean
+  ): string | undefined;
+
+  export function getCookieDomain(): string | undefined;
+
+  export function getCookieSecure(): boolean;
+
+  export function isAllowedOriginHostname(hostname: string, domain?: string): boolean;
+
   export function getClearCookieOptions(): {
     domain?: string;
     secure: boolean;
@@ -321,6 +332,8 @@ declare module 'mbkauthe' {
 
   export function hashPassword(password: string, username: string): string;
 
+  export function verifyPassword(password: string, username: string, storedHash: string): Promise<boolean>;
+
   export function clearSessionCookies(res: Response): void;
 
   export function getLatestVersion(): Promise<string>;

package/lib/config/cookies.js

@@ -6,7 +6,7 @@ const MAX_REMEMBERED_ACCOUNTS = 5;
 const ACCOUNT_LIST_COOKIE = 'mbkauthe_accounts';
 
 // Cookie security: encryption and signing
-const COOKIE_ENCRYPTION_KEY = mbkautheVar.SESSION_SECRET_KEY || 'fallback-secret-key-change-this';
+const COOKIE_ENCRYPTION_KEY = mbkautheVar.SESSION_SECRET_KEY;
 const ENCRYPTION_ALGORITHM = 'aes-256-gcm';
 
 // Derive encryption key from session secret
@@ -121,8 +121,7 @@ const decryptCookiePayload = (payload) => {
 // Generate fingerprint from user-agent only (salted)
 const generateFingerprint = (req) => {
     const userAgent = req.headers['user-agent'] || '';
-    // Use SESSION_SECRET_KEY as salt if available, otherwise fallback to encryption key
-    const salt = mbkautheVar.SESSION_SECRET_KEY || COOKIE_ENCRYPTION_KEY;
+    const salt = mbkautheVar.SESSION_SECRET_KEY;
 
     // Hash user-agent with salt to prevent rainbow table attacks on UAs
     return crypto
@@ -152,19 +151,41 @@ export const decryptSessionId = (encryptedSessionId) => {
     }
 };
 
+const isTestDevEnvironment = () => process.env.test === 'dev';
+
+export const resolveCookieDomain = (isDeployed, domain, isTestDev = isTestDevEnvironment()) => {
+    if (isDeployed !== 'true' || isTestDev || !domain) {
+        return undefined;
+    }
+
+    return `.${String(domain).replace(/^\.+/, '')}`;
+};
+
+export const getCookieDomain = () => resolveCookieDomain(mbkautheVar.IS_DEPLOYED, mbkautheVar.DOMAIN);
+
+export const getCookieSecure = () => mbkautheVar.IS_DEPLOYED === 'true' && !isTestDevEnvironment();
+
+export const isAllowedOriginHostname = (hostname, domain = mbkautheVar.DOMAIN) => {
+    if (!hostname || !domain) {
+        return false;
+    }
+
+    return hostname === domain || hostname.endsWith(`.${domain}`);
+};
+
 // Shared cookie options functions
 const getCookieOptions = () => ({
     maxAge: mbkautheVar.COOKIE_EXPIRE_TIME * 24 * 60 * 60 * 1000,
-    domain: mbkautheVar.IS_DEPLOYED === 'true' ? `.${mbkautheVar.DOMAIN}` : undefined,
-    secure: mbkautheVar.IS_DEPLOYED === 'true',
+    domain: getCookieDomain(),
+    secure: getCookieSecure(),
     sameSite: 'lax',
     path: '/',
     httpOnly: true
 });
 
 const getClearCookieOptions = () => ({
-    domain: mbkautheVar.IS_DEPLOYED === 'true' ? `.${mbkautheVar.DOMAIN}` : undefined,
-    secure: mbkautheVar.IS_DEPLOYED === 'true',
+    domain: getCookieDomain(),
+    secure: getCookieSecure(),
     sameSite: 'lax',
     path: '/',
     httpOnly: true
@@ -183,16 +204,20 @@ export const generateDeviceToken = () => {
     return crypto.randomBytes(32).toString('hex');
 };
 
+const getDeviceTokenKey = () => {
+    return crypto.createHash('sha256').update(`${mbkautheVar.SESSION_SECRET_KEY}:device-token`).digest();
+};
+
 // Hash a device token for safe storage in the database
 export const hashDeviceToken = (token) => {
     if (!token || typeof token !== 'string') return null;
-    return crypto.createHmac('sha256').update(token).digest('hex');
+    return crypto.createHmac('sha256', getDeviceTokenKey()).update(token).digest('hex');
 };
 
 export const getDeviceTokenCookieOptions = () => ({
     maxAge: DEVICE_TRUST_DURATION_MS,
-    domain: mbkautheVar.IS_DEPLOYED === 'true' ? `.${mbkautheVar.DOMAIN}` : undefined,
-    secure: mbkautheVar.IS_DEPLOYED === 'true',
+    domain: getCookieDomain(),
+    secure: getCookieSecure(),
     sameSite: 'lax',
     path: '/',
     httpOnly: true