mbkauthe 4.7.2 → 4.8.1

package/README.md

@@ -22,8 +22,8 @@
 - 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
+- Social login (GitHub App & Google OAuth)
+- Role-based access: SuperAdmin, NormalUser, Guest, member
 - CSRF protection & rate limiting
 - Easy Express.js integration
 - Customizable Handlebars templates
@@ -101,9 +101,9 @@ These are only mounted when `process.env.env === "dev"`:
 
 Enable via `MBKAUTH_TWO_FA_ENABLE=true`. Trusted devices can skip 2FA for a set duration.
 
-## 🔄 OAuth Integration
+## 🔄 Social Login Integration
 
-**GitHub / Google OAuth:** Configure apps and credentials via `.env` or `mbkautheVar`. Users must link accounts before login.
+**GitHub App / Google OAuth:** Configure credentials via `.env` or `mbkautheVar`. Users must link accounts before login.
 
 ## 🎨 Customization
 

package/docs/api.md

@@ -179,7 +179,7 @@ Renders the main login page.
 **Response:** HTML page with login form
 
 **Template Variables:**
-- `githubLoginEnabled` - Whether GitHub OAuth is enabled
+- `githubLoginEnabled` - Whether GitHub App login is enabled
 - `googleLoginEnabled` - Whether Google OAuth is enabled
 - `customURL` - Redirect URL after login
 - `userLoggedIn` - Whether user is already authenticated
@@ -317,8 +317,8 @@ The endpoints below are active in the router but are not fully expanded above. U
 
 **OAuth:**
 
-- `GET /mbkauthe/api/github/login` - Starts GitHub OAuth login flow.
-- `GET /mbkauthe/api/github/login/callback` - GitHub OAuth callback.
+- `GET /mbkauthe/api/github/login` - Starts GitHub App login flow.
+- `GET /mbkauthe/api/github/login/callback` - GitHub App callback.
 - `GET /mbkauthe/api/google/login` - Starts Google OAuth login flow.
 - `GET /mbkauthe/api/google/login/callback` - Google OAuth callback.
 
@@ -1222,11 +1222,11 @@ GET /mbkauthe/test
 
 ### OAuth Endpoints
 
-#### GitHub OAuth
+#### GitHub App
 
 ##### `GET /mbkauthe/api/github/login`
 
-Initiates the GitHub OAuth authentication flow.
+Initiates the GitHub App authentication flow.
 
 **Rate Limit:** 10 requests per 5 minutes
 
@@ -1235,11 +1235,11 @@ Initiates the GitHub OAuth authentication flow.
 **Query Parameters:**
 - `redirect` (optional) - Relative URL to redirect after successful authentication (must start with `/` to prevent open redirect attacks)
 
-**Response:** Redirects to GitHub OAuth authorization page
+**Response:** Redirects to GitHub authorization page
 
 **Prerequisites:**
 - `GITHUB_LOGIN_ENABLED=true` in environment
-- Valid `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` configured
+- Valid `GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET` configured
 - User's GitHub account must be linked to an MBKAuth account in `user_github` table
 
 **Example:**
@@ -1250,9 +1250,9 @@ GET /mbkauthe/api/github/login?redirect=/dashboard
 **Workflow:**
 1. User clicks "Login with GitHub"
 2. CSRF token generated and stored in session
-3. Redirects to GitHub for authorization
-4. GitHub redirects back to callback URL
-5. System verifies GitHub account is linked
+3. Redirects to GitHub authorization page
+4. GitHub redirects back to callback URL with authorization `code`
+5. System verifies `github_id` is linked
 6. If 2FA enabled, prompts for 2FA
 7. Creates session and redirects to specified URL
 
@@ -1260,7 +1260,7 @@ GET /mbkauthe/api/github/login?redirect=/dashboard
 
 ##### `GET /mbkauthe/api/github/login/callback`
 
-Handles the OAuth callback from GitHub after user authorization.
+Handles the callback from GitHub after user authorization.
 
 **Rate Limit:** Inherited from OAuth rate limiter (10 requests per 5 minutes)
 
@@ -1277,7 +1277,7 @@ Handles the OAuth callback from GitHub after user authorization.
 - **GitHub Not Linked**: Returns error if GitHub account is not in `user_github` table
 - **Account Inactive**: Returns error if user account is deactivated
 - **Not Authorized**: Returns error if user is not allowed to access the application
-- **GitHub Auth Error**: Returns error for any OAuth-related failures
+- **GitHub Auth Error**: Returns error for provider authentication failures
 
 **Success Flow:**
 ```
@@ -1474,7 +1474,7 @@ These cookies allow front-end UI to display a friendly name without making extra
 Checks if the authenticated user has the required role.
 
 **Parameters:**
-- `requiredRole` (string) - Required role: `"SuperAdmin"`, `"NormalUser"`, `"Guest"`, or `"Any"`/`"any"`
+- `requiredRole` (string) - Required role: `"SuperAdmin"`, `"NormalUser"`, `"Guest"`, `"member"`, or `"Any"`/`"any"`
 - `notAllowed` (string, optional) - Role that is explicitly not allowed
 
 **Usage:**

package/docs/db.md

@@ -12,7 +12,7 @@ The project uses a Postgres `ENUM` type for user roles:
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'role') THEN
-    CREATE TYPE role AS ENUM ('SuperAdmin', 'NormalUser', 'Guest');
+    CREATE TYPE role AS ENUM ('SuperAdmin', 'NormalUser', 'Guest', 'member');
   END IF;
 END
 $$;
@@ -85,7 +85,9 @@ CREATE TABLE IF NOT EXISTS user_github (
     user_name VARCHAR(50) REFERENCES "Users"("UserName"),
     github_id VARCHAR(255) UNIQUE,
     github_username VARCHAR(255),
-    access_token TEXT,
+    installation_id BIGINT,
+    installation_target_type VARCHAR(32),
+    access_token VARCHAR(255),
     created_at TimeStamp WITH TIME ZONE DEFAULT NOW(),
     updated_at TimeStamp WITH TIME ZONE DEFAULT NOW()
 );
@@ -317,7 +319,7 @@ To add new users to the `Users` table, use the following SQL queries:
 - Replace `support` and `test` with the desired usernames.
 - For raw passwords: Replace `12345678` with the actual plain text passwords.
 - For encrypted passwords: Use the hashPassword function to generate the hash before inserting.
-- Adjust the `Role` values as needed (`SuperAdmin`, `NormalUser`, or `Guest`).
+- Adjust the `Role` values as needed (`SuperAdmin`, `NormalUser`, `Guest`, or `member`).
 - Modify the `Active` and `HaveMailAccount` values as required.
 
 **Generating Encrypted Passwords:**

package/docs/db.sql

@@ -2,7 +2,7 @@
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'role') THEN
-    CREATE TYPE role AS ENUM ('SuperAdmin', 'NormalUser', 'Guest');
+    CREATE TYPE role AS ENUM ('SuperAdmin', 'NormalUser', 'Guest', 'member');
   END IF;
 END
 $$;
@@ -49,11 +49,17 @@ CREATE TABLE IF NOT EXISTS user_github (
     user_name VARCHAR(50) REFERENCES "Users"("UserName"),
     github_id VARCHAR(255) UNIQUE,
     github_username VARCHAR(255),
+    installation_id BIGINT,
+    installation_target_type VARCHAR(32),
     access_token TEXT,
     created_at TimeStamp WITH TIME ZONE DEFAULT NOW(),
     updated_at TimeStamp WITH TIME ZONE DEFAULT NOW()
 );
 
+ALTER TABLE user_github
+    ADD COLUMN IF NOT EXISTS installation_id BIGINT,
+    ADD COLUMN IF NOT EXISTS installation_target_type VARCHAR(32);
+
 -- Add indexes for performance optimization
 CREATE INDEX IF NOT EXISTS idx_user_github_github_id ON user_github (github_id);
 CREATE INDEX IF NOT EXISTS idx_user_github_user_name ON user_github (user_name);
@@ -88,6 +94,24 @@ CREATE TABLE IF NOT EXISTS "Sessions" (
 CREATE INDEX IF NOT EXISTS idx_sessions_username ON "Sessions" ("UserName");
 CREATE INDEX IF NOT EXISTS idx_sessions_user_created ON "Sessions" ("UserName", created_at);
 
+-- Support expiry-based cleanup and validity checks
+CREATE INDEX IF NOT EXISTS idx_sessions_username_expires
+ON "Sessions" ("UserName", expires_at);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_expires
+ON "Sessions" (expires_at)
+WHERE expires_at IS NOT NULL;
+
+-- Optional (Postgres 11+): covering indexes for hot-path lookups (validateSession)
+-- These can enable index-only scans for the exact columns used in auth middleware.
+CREATE INDEX IF NOT EXISTS idx_sessions_id_cover
+ON "Sessions" (id)
+INCLUDE ("UserName", expires_at);
+
+CREATE INDEX IF NOT EXISTS idx_users_username_cover
+ON "Users" ("UserName")
+INCLUDE ("Active", "Role");
+
 
 CREATE TABLE IF NOT EXISTS "session" (
     sid VARCHAR(33) PRIMARY KEY NOT NULL,

package/docs/env.md

@@ -95,14 +95,26 @@ This document describes the environment variables MBKAuth expects and keeps brie
   - Required: No
 
 - GITHUB_LOGIN_ENABLED / GOOGLE_LOGIN_ENABLED
-  - Description: Enable OAuth providers.
+  - Description: Enable social login providers.
   - Default: `false`
-  - If `true`, corresponding `*_CLIENT_ID` and `*_CLIENT_SECRET` are required.
+  - 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_CLIENT_ID / GITHUB_CLIENT_SECRET / GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
-  - Description: OAuth credentials (put in `mbkautheVar` preferred, or `mbkauthShared`).
-  - Required when provider enabled.
-  - Create Github OAuth App: https://github.com/settings/developers
+- 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`.
+
+- GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET
+  - Description: Legacy fallback keys if app-prefixed keys are not provided.
+
+- GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
+  - Description: Google OAuth credentials.
+  - Required when `GOOGLE_LOGIN_ENABLED=true`.
   - Create Google OAuth: https://console.cloud.google.com/
 
 ---

package/index.d.ts

@@ -55,8 +55,9 @@ declare module 'mbkauthe' {
     COOKIE_EXPIRE_TIME?: number;
     DEVICE_TRUST_DURATION_DAYS?: number;
     GITHUB_LOGIN_ENABLED?: 'true' | 'false' | 'f';
-    GITHUB_CLIENT_ID?: string;
-    GITHUB_CLIENT_SECRET?: string;
+    GITHUB_APP_SLUG?: string;
+    GITHUB_APP_CLIENT_ID?: string;
+    GITHUB_APP_CLIENT_SECRET?: string;
     GOOGLE_LOGIN_ENABLED?: 'true' | 'false' | 'f';
     GOOGLE_CLIENT_ID?: string;
     GOOGLE_CLIENT_SECRET?: string;
@@ -66,8 +67,9 @@ declare module 'mbkauthe' {
 
   export interface OAuthConfig {
     GITHUB_LOGIN_ENABLED?: 'true' | 'false' | 'f';
-    GITHUB_CLIENT_ID?: string;
-    GITHUB_CLIENT_SECRET?: string;
+    GITHUB_APP_SLUG?: string;
+    GITHUB_APP_CLIENT_ID?: string;
+    GITHUB_APP_CLIENT_SECRET?: string;
     GOOGLE_LOGIN_ENABLED?: 'true' | 'false' | 'f';
     GOOGLE_CLIENT_ID?: string;
     GOOGLE_CLIENT_SECRET?: string;
@@ -132,6 +134,8 @@ declare module 'mbkauthe' {
     user_name: string;
     github_id: string;
     github_username: string;
+    installation_id?: number;
+    installation_target_type?: string;
     access_token: string;
     created_at: Date;
     updated_at: Date;
@@ -238,6 +242,9 @@ declare module 'mbkauthe' {
     notAllowed?: UserRole
   ): AuthMiddleware;
 
+  export const sessVal: AuthMiddleware;
+  export const sessRole: AuthMiddleware;
+
   export const strictValidateSession: AuthMiddleware;
 
   export function strictValidateSessionAndRole(

package/index.js

@@ -1,6 +1,5 @@
 import express from "express";
-import router from "./lib/main.js";
-import { checkVersion } from "./lib/main.js";
+import router, { checkVersion } from "./lib/main.js";
 import { engine } from "express-handlebars";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -9,129 +8,95 @@ import { packageJson } from "#config.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const isDevMode = process.env.test === "dev";
+const DEV_PORT = 5555;
+const viewsPath = path.join(__dirname, "views");
+const packageVersion = packageJson.version;
 
 const app = express();
 
 app.set("views", [
-    path.join(__dirname, "views"),
+    viewsPath,
     path.join(__dirname, "node_modules/mbkauthe/views")
 ]);
 
+const handlebarsHelpers = {
+    eq: (a, b) => a === b,
+    encodeURIComponent: (str) => encodeURIComponent(str),
+    formatTimestamp: (timestamp) => new Date(timestamp).toLocaleString(),
+    jsonStringify: (context) => JSON.stringify(context),
+    json: (obj) => JSON.stringify(obj, null, 2),
+    objectEntries: (obj) => {
+        if (!obj || typeof obj !== 'object') return [];
+        return Object.entries(obj).map(([key, value]) => ({ key, value }));
+    },
+    cacheBuster: () => `?v=${packageVersion}`
+};
+
 app.engine("handlebars", engine({
     defaultLayout: false,
     cache: true,
     partialsDir: [
-        path.join(__dirname, "views"),
+        viewsPath,
         path.join(__dirname, "node_modules/mbkauthe/views"),
         path.join(__dirname, "node_modules/mbkauthe/views/Error"),
     ],
-    helpers: {
-        eq: function (a, b) {
-            return a === b;
-        },
-        encodeURIComponent: function (str) {
-            return encodeURIComponent(str);
-        },
-        formatTimestamp: function (timestamp) {
-            return new Date(timestamp).toLocaleString();
-        },
-        jsonStringify: function (context) {
-            return JSON.stringify(context);
-        },
-        json: (obj) => JSON.stringify(obj, null, 2),
-        objectEntries: function (obj) {
-            if (!obj || typeof obj !== 'object') {
-                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 "?v=" + packageJson.version;
-        }
-    }
-
+    helpers: handlebarsHelpers
 }));
 
 app.set("view engine", "handlebars");
-
 app.use(router);
 
-if (process.env.test === "dev") {
+const renderDevError = (res, req, code, error, message, page, details) => renderError(res, req, {
+    layout: false,
+    code,
+    error,
+    message,
+    details,
+    pagename: "Home",
+    page,
+});
+
+if (isDevMode) {
     console.log("[mbkauthe] Dev mode is enabled. Starting server in dev mode.");
-    const port = 5555;
-    app.get(["/dashboard", "/home", "/"], (req, res) => {
-            return res.redirect("/mbkauthe/");
-    });
-    app.get("/dev/2fa", (req, res) => {
-            return renderPage(req, res, "pages/2fa.handlebars", {
-                layout: false,
-                pagename: "Two-Factor Authentication",
-                page: "/home"
-            });
-    });
-    app.get("/showmessage", (req, res) => {
-        //uncomment line 26 on showmessage.handlebars for testing, after testing comment it back
-        return renderPage(req, res, "showmessage", false);
-    });
-    app.get("/500", (req, res) => {
-        return renderError(res, req, {
-            layout: false,
-            code: 500,
-            error: "Internal Server Error",
-            message: "Simulated 500 Error",
-            details: "This is a simulated 500 error page for testing purposes.",
-            pagename: "Home",
-            page: "/mbkauthe/login",
-        });
-    });
+
+    app.get(["/dashboard", "/home", "/"], (req, res) => res.redirect("/mbkauthe/"));
+
+    app.get("/dev/2fa", (req, res) => renderPage(req, res, "pages/2fa.handlebars", false, {
+        pagename: "Two-Factor Authentication",
+        page: "/home"
+    }));
+
+    app.get("/showmessage", (req, res) => renderPage(req, res, "showmessage", false));
+
+    app.get("/500", (req, res) => renderDevError(res, req, 500,
+        "Internal Server Error", "Simulated 500 Error",
+        "/mbkauthe/login", "This is a simulated 500 error page for testing purposes."
+    ));
+
     app.use((req, res) => {
         console.log(`[mbkauthe] Path not found: ${req.method} ${req.url}`);
-        return renderError(res, req, {
-            layout: false,
-            code: 404,
-            error: "Not Found",
-            message: "The requested page was not found.",
-            pagename: "Home",
-            page: "/mbkauthe/login",
-        });
+        renderDevError(res, req, 404, "Not Found", "The requested page was not found.", "/mbkauthe/login");
     });
-    app.listen(port, () => {
-        console.log(`[mbkauthe] Server running on http://localhost:${port}`);
+
+    app.listen(DEV_PORT, () => {
+        console.log(`[mbkauthe] Server running on http://localhost:${DEV_PORT}`);
     });
 }
 
-if (process.env.test !== "dev") {
+if (!isDevMode) {
     await checkVersion();
 }
 
-export {
-    validateSession, validateApiSession, checkRolePermission,
-    validateSessionAndRole, authenticate, reloadSessionUser,
-    strictValidateSession, strictValidateSessionAndRole
-} from "./lib/middleware/auth.js";
-export {
-    sessionConfig,
-    corsMiddleware,
-    sessionRestorationMiddleware,
-    sessionCookieSyncMiddleware,
-    requestContextMiddleware
-} from "./lib/middleware/index.js";
+export * from "./lib/middleware/auth.js";
+export * from "./lib/middleware/index.js";
 export { validateTokenScope } from "./lib/middleware/scopeValidator.js";
-export { renderError, getUserContext, renderPage, proxycall } from "#response.js";
+export * from "#response.js";
 export { dblogin } from "#pool.js";
 export { getLatestVersion } from "./lib/routes/misc.js";
-export { checkTrustedDevice, completeLoginProcess } from "./lib/routes/auth.js";
-export {
-    ErrorCodes, ErrorMessages, getErrorByCode,
-    createErrorResponse, logError
-} from "./lib/utils/errors.js";
-export {
-    encryptSessionId, decryptSessionId, cachedCookieOptions, cachedClearCookieOptions,
-    DEVICE_TRUST_DURATION_DAYS, DEVICE_TRUST_DURATION_MS,
-    generateDeviceToken, hashDeviceToken, getDeviceTokenCookieOptions,
-    getCookieOptions, getClearCookieOptions, clearSessionCookies,
-    readAccountListFromCookie, upsertAccountListCookie, removeAccountFromCookie, clearAccountListCookie
-} from "./lib/config/cookies.js";
-export { hashPassword, hashApiToken } from "./lib/config/security.js";
+export * from "./lib/routes/auth.js";
+export * from "./lib/utils/errors.js";
+export * from "./lib/config/cookies.js";
+export * from "./lib/config/security.js";
 export { mbkautheVar } from "#config.js";
 export default app;

package/lib/config/index.js

@@ -64,7 +64,7 @@ function validateConfiguration() {
     const keysToCheck = [
         "APP_NAME", "DEVICE_TRUST_DURATION_DAYS", "EncPass", "Main_SECRET_TOKEN", "SESSION_SECRET_KEY",
         "IS_DEPLOYED", "LOGIN_DB", "MBKAUTH_TWO_FA_ENABLE", "COOKIE_EXPIRE_TIME", "DOMAIN", "loginRedirectURL",
-        "GITHUB_LOGIN_ENABLED", "GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET", "GOOGLE_LOGIN_ENABLED", "GOOGLE_CLIENT_ID",
+        "GITHUB_LOGIN_ENABLED", "GITHUB_APP_SLUG", "GITHUB_APP_CLIENT_ID", "GITHUB_APP_CLIENT_SECRET", "GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET", "GOOGLE_LOGIN_ENABLED", "GOOGLE_CLIENT_ID",
         "GOOGLE_CLIENT_SECRET", "MAX_SESSIONS_PER_USER"
     ];
 
@@ -145,11 +145,14 @@ function validateConfiguration() {
 
     // Validate GitHub login configuration
     if (mbkautheVar.GITHUB_LOGIN_ENABLED === "true") {
-        if (!mbkautheVar.GITHUB_CLIENT_ID || mbkautheVar.GITHUB_CLIENT_ID.trim() === '') {
-            errors.push("mbkautheVar.GITHUB_CLIENT_ID is required when GITHUB_LOGIN_ENABLED is 'true'");
+        const hasGithubClientId = !!(mbkautheVar.GITHUB_APP_CLIENT_ID || mbkautheVar.GITHUB_CLIENT_ID);
+        const hasGithubClientSecret = !!(mbkautheVar.GITHUB_APP_CLIENT_SECRET || mbkautheVar.GITHUB_CLIENT_SECRET);
+
+        if (!hasGithubClientId) {
+            errors.push("mbkautheVar.GITHUB_APP_CLIENT_ID (or GITHUB_CLIENT_ID) is required when GITHUB_LOGIN_ENABLED is 'true'");
         }
-        if (!mbkautheVar.GITHUB_CLIENT_SECRET || mbkautheVar.GITHUB_CLIENT_SECRET.trim() === '') {
-            errors.push("mbkautheVar.GITHUB_CLIENT_SECRET is required when GITHUB_LOGIN_ENABLED is 'true'");
+        if (!hasGithubClientSecret) {
+            errors.push("mbkautheVar.GITHUB_APP_CLIENT_SECRET (or GITHUB_CLIENT_SECRET) is required when GITHUB_LOGIN_ENABLED is 'true'");
         }
     }