mbkauthe 5.0.0 → 5.0.1

package/README.md

@@ -6,172 +6,158 @@
 [![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)
 
-
 <p align="center">
   <img height="64px" src="./public/logo.png" alt="MBKAuthe" />
 </p>
 
-**MBKAuthe** is an open source package focused on login, authentication, and validating sessions for your desired apps in Node.js with Express and PostgreSQL. It provides secure login, session validation, 2FA, role/app access checks, OAuth (GitHub & Google), multi-session support, and related authentication flows.
-
-> **Note:** MBKAuthe is intentionally limited to authentication and session validation. The full user/permission/dashboard management system is a separate product called **MBKCore**, developed by MBKTech and not currently open source. Access to MBKCore is currently available only to the MBKTech team, and we may refine it and consider open sourcing it in the future.
+**MBKAuthe** is an open source authentication package for Node.js, Express, and PostgreSQL. It handles login, session validation, role/app access checks, optional TOTP 2FA, OAuth login, API token authentication, and multi-session management.
 
-## Todo
-- 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.
+> **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).
 
-## ✨ Key Features
+## Features
 
-- Compatible With Serverless Function (Vercel)
-- Secure password authentication (PBKDF2)
-- PostgreSQL session management
-- Multi-session support (configurable concurrent sessions per user)
-- Optional TOTP-based 2FA with trusted devices
-- Social login (GitHub App & Google OAuth)
-- Role-based access: SuperAdmin, NormalUser, Guest, member
-- 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
+- Express middleware for session validation and role checks
+- PostgreSQL-backed user, session, 2FA, trusted-device, and API-token storage
+- 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
+## Installation
 
 ```bash
 npm install mbkauthe
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
-**1. Configure Environment**
+1. Copy the environment template.
 
-```bash
+```powershell
 Copy-Item .env.example .env
 ```
-See [docs/env.md](docs/env.md).
 
-**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).
+2. Configure environment values.
 
-**3. Integrate with Express**
-
-```javascript
-import express from 'express';
-import mbkauthe, { sessVal, roleChk } from 'mbkauthe';
-import dotenv from 'dotenv';
-dotenv.config();
+See the [configuration guide](docs/guides/configuration.md) for `mbkautheVar`, `mbkauthShared`, OAuth settings, session settings, and deployment flags.
 
-const app = express();
-app.use(mbkauthe);
+3. Create database tables.
 
-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'));
-
-app.listen(3000);
-```
-
-## 🧪 Testing
+Run [docs/schema/db.sql](docs/schema/db.sql) against PostgreSQL, or use the package script:
 
 ```bash
-npm test
-npm run test:watch
-npm run dev
+npm run create-tables
 ```
 
-## 🔧 Core API
+The schema includes a default SuperAdmin user (`support` / `12345678`). Change that password immediately. See the [database guide](docs/guides/database.md).
 
-- **Session Validation:** `validateSession`
-- **Role Check:** `checkRolePermission(['Role'])`/`roleChk(['Role'])`
-- **Combined:** `validateSessionAndRole(['SuperAdmin', 'NormalUser'])`/`sessRole(['SuperAdmin', 'NormalUser'])`
-- **API Token Auth:** `authenticate(process.env.API_TOKEN)`
+4. Mount MBKAuthe in Express.
 
-## 🧾 JSON Responses (HTML vs JSON)
-
-Most browser page routes render HTML on auth errors, while API/AJAX-style requests receive JSON error responses.
-
-MBKAuthe treats a request as **JSON** (and returns JSON errors) when any of the following apply:
-
-- URL/path starts with `/mbkauthe/api/` or `/api/`
-- `X-Requested-With: XMLHttpRequest`
-- `Accept` indicates JSON (e.g., `application/json`) and does not explicitly prefer `text/html`
-- `User-Agent` looks like a non-browser client (e.g., `curl`, `wget`, `Postman`)
-- `User-Agent: json` (explicitly forces JSON responses)
+```javascript
+import express from "express";
+import dotenv from "dotenv";
+import mbkauthe, { sessVal, roleChk } from "mbkauthe";
 
-**Example (force JSON errors):**
-```bash
-curl -i -H "User-Agent: json" http://localhost:3000/mbkauthe/test
-```
+dotenv.config();
 
-## 🧰 Diagnostics (dev only)
+const app = express();
 
-These are only mounted when `process.env.env === "dev"`:
+app.use(mbkauthe);
 
-- **DB Query Monitor (HTML):** `/mbkauthe/db`
-- **DB Query Monitor (JSON):** `/mbkauthe/db.json`
-- **SuperAdmin check:** `/mbkauthe/validate-superadmin`
+app.get("/dashboard", sessVal, (req, res) => {
+  res.send(`Welcome ${req.session.user.username}!`);
+});
 
-## 🔐 Security
+app.get("/admin", sessVal, roleChk("SuperAdmin"), (req, res) => {
+  res.send("Admin Panel");
+});
 
-- Rate limiting, CSRF protection, secure cookies
-- Password hashing (PBKDF2, 100k iterations)
-- PostgreSQL-backed sessions with automatic cleanup
-- OAuth with state validation and secure callbacks
+app.listen(3000);
+```
 
-## 📱 Two-Factor Authentication
+## Common Exports
 
-Enable via `MBKAUTH_TWO_FA_ENABLE=true`. Trusted devices can skip 2FA for a set duration.
+- `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 PostgreSQL pool.
 
-## 🔄 Social Login Integration
+See the [API reference](docs/reference/api.md) for endpoints, middleware, examples, security notes, and rate limits.
 
-**GitHub App / Google OAuth:** Configure credentials via `.env` or `mbkautheVar`. Users must link accounts before login.
+## JSON Error Responses
 
-## 🎨 Customization
+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:
 
-- **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"');`
+- 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`
 
-## 📄 API Reference
+```bash
+curl -i -H "User-Agent: json" http://localhost:3000/mbkauthe/test
+```
 
-- Full endpoint list and details: [docs/api.md](docs/api.md)
+## Development
 
-## 🧰 Diagnostics (dev only)
+```bash
+npm test
+npm run test:watch
+npm run dev
+```
 
-- **DB Query Monitor (HTML):** `/mbkauthe/db`
-- **DB Query Monitor (JSON):** `/mbkauthe/db.json`
-- **SuperAdmin check:** `/mbkauthe/debug/validate-superadmin`
+Development-only diagnostics are mounted when `process.env.env === "dev"`:
 
-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.
+- `/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
 
-## 🚢 Deployment
+## Documentation
 
-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
+- [Documentation index](docs/README.md)
+- [Configuration guide](docs/guides/configuration.md)
+- [Database guide](docs/guides/database.md)
+- [API reference](docs/reference/api.md)
+- [Authentication and sessions](docs/reference/api/authentication.md)
+- [Endpoints](docs/reference/api/endpoints.md)
+- [Middleware](docs/reference/api/middleware.md)
+- [Code examples](docs/reference/api/examples.md)
+- [Operational reference](docs/reference/api/operations.md)
+- [Error codes](docs/reference/error-codes.md)
+- [Documentation style guide](docs/STYLE.md)
 
-**Vercel:** Supports shared OAuth credentials via `mbkauthShared`.
+## Deployment Checklist
 
-## 📚 Documentation
+- 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
 
-- [API Reference](docs/api.md)
-- [Database Schema](docs/db.md)
-- [Environment Config](docs/env.md)
-- [Error Codes](docs/error-messages.md)
+Vercel deployments can use shared OAuth credentials through `mbkauthShared`.
 
-## 📝 License
+## License
 
-GPL v2.0 — see [LICENSE](LICENSE)
+GPL v2.0 - see [LICENSE](LICENSE).
 
-## 👨‍💻 Author
+## Author
 
 **Muhammad Bin Khalid**  
-📧 [support@mbktech.org](mailto:support@mbktech.org) | [chmuhammadbinkhalid28@gmail.com](mailto:chmuhammadbinkhalid28@gmail.com)  
-🔗 [GitHub @MIbnEKhalid](https://github.com/MIbnEKhalid)
+[support@mbktech.org](mailto:support@mbktech.org) | [chmuhammadbinkhalid28@gmail.com](mailto:chmuhammadbinkhalid28@gmail.com)  
+[GitHub @MIbnEKhalid](https://github.com/MIbnEKhalid)
 
-## 🔗 Links
+## Links
 
 - [npm](https://www.npmjs.com/package/mbkauthe)
 - [GitHub](https://github.com/MIbnEKhalid/mbkauthe)
@@ -179,4 +165,4 @@ GPL v2.0 — see [LICENSE](LICENSE)
 
 ---
 
-Made with ❤️ by [MBKTech.org](https://mbktech.org)
+Made with love by [MBKTech.org](https://mbktech.org).

package/docs/README.md

@@ -0,0 +1,33 @@
+# MBKAuthe Documentation
+
+This directory is organized by how the documentation is used:
+
+- **Guides** - setup and operational walkthroughs.
+- **Reference** - detailed API and error-code documentation.
+- **Schema** - executable database SQL.
+- **Diagrams** - Mermaid source files and rendered images.
+
+## Start here
+
+- [Project README](../README.md)
+- [Configuration guide](guides/configuration.md)
+- [Database guide](guides/database.md)
+- [API reference](reference/api.md)
+- [Error codes](reference/error-codes.md)
+- [Documentation style guide](STYLE.md)
+
+## Source layout
+
+- `guides/` - task-oriented setup and operations docs.
+- `reference/` - detailed facts, route lists, middleware details, and error-code documentation.
+- `reference/api/` - split API reference sections included from the API index.
+- `schema/` - executable SQL and schema assets.
+- `diagrams/` - Mermaid source files.
+- `images/` - rendered diagram outputs and documentation images.
+
+## Assets
+
+- [Database schema SQL](schema/db.sql)
+- [Authentication flow Mermaid source](diagrams/auth-flows.mmd)
+- [Authentication process Mermaid source](diagrams/auth-processes.mmd)
+- [Rendered diagram images](images/)

package/docs/STYLE.md

@@ -0,0 +1,40 @@
+# Documentation Style Guide
+
+[Back to docs index](README.md) | [Back to project README](../README.md)
+
+Use this guide when adding or changing documentation source.
+
+## File Placement
+
+- Put setup walkthroughs and operational how-to content in `guides/`.
+- Put endpoint, middleware, type, and error-code details in `reference/`.
+- Put long API sections under `reference/api/` and link them from `reference/api.md`.
+- Put executable database SQL in `schema/`.
+- Put Mermaid source in `diagrams/` and rendered outputs in `images/`.
+
+## Markdown Structure
+
+- Use one `#` title per file.
+- Keep files focused on one job; split a file when it becomes hard to scan or review.
+- Add a small navigation line under the title for files below `docs/`.
+- Prefer descriptive links such as `[Configuration guide](guides/configuration.md)` over raw paths in prose.
+- Keep table-of-contents blocks short; rely on smaller files instead of very deep TOCs.
+
+## Code Blocks
+
+- Always include a language tag when the language is known: `javascript`, `json`, `bash`, `sql`, `env`, or `typescript`.
+- Keep examples copy-pasteable where possible.
+- Use placeholders for secrets and tokens; never include real credentials.
+- Keep endpoint examples close to the endpoint they describe.
+
+## Cross-Links
+
+- Links from `docs/README.md` are relative to `docs/`.
+- Links from `docs/reference/api/*.md` need one extra `..` segment to reach the docs index.
+- After moving docs, run a Markdown link check before committing.
+
+## Generated Assets
+
+- Mermaid source is authoritative.
+- Rendered images in `images/` should be regenerated when the matching `.mmd` file changes.
+- Keep package scripts aligned with the source paths in `diagrams/`.

package/docs/diagrams/auth-processes.mmd

@@ -0,0 +1,120 @@
+sequenceDiagram
+    autonumber
+
+    participant R as Protected Route
+    participant VS as validateSession
+    participant JT as isJsonRequest
+    participant VT as validateTokenAuthentication
+    participant CS as validateCookieSession
+    participant DB as AuthRepository / DB
+    participant RES as Response
+
+    R->>VS: validateSession(req, res, next, strictTokenValidation?)
+
+    alt Authorization header exists
+        alt strictTokenValidation is true
+            VS-->>RES: 401 INVALID_AUTH_TOKEN
+            Note over VS,RES: Token auth is rejected for strict cookie-only middleware.
+        else token auth allowed
+            VS->>VT: validateTokenAuthentication(req)
+
+            alt Header is not "Bearer <token>"
+                VT-->>VS: null
+                VS-->>RES: 401 INVALID_AUTH_TOKEN
+            else Token does not start with mbk_ or is too long
+                VT-->>VS: { error: "INVALID_TOKEN" }
+                VS-->>RES: 401 INVALID_AUTH_TOKEN
+            else Token format is accepted
+                VT->>VT: hashApiToken(token)
+                VT->>DB: getApiTokenByHash(tokenHash)
+
+                alt API token row not found
+                    DB-->>VT: null
+                    VT-->>VS: { error: "INVALID_TOKEN" }
+                    VS-->>RES: 401 INVALID_AUTH_TOKEN
+                else API token expired
+                    DB-->>VT: row with ExpiresAt <= now
+                    VT-->>VS: { error: "TOKEN_EXPIRED" }
+                    VS-->>RES: 401 API_TOKEN_EXPIRED
+                else API token found
+                    DB-->>VT: token row joined to user
+                    VT->>VT: Resolve token scope and allowedApps
+                    VT->>DB: updateApiTokenLastUsed(row.id) async
+                    VT-->>VS: tokenUser
+
+                    alt tokenUser.active is false
+                        VS-->>RES: 401 ACCOUNT_INACTIVE
+                    else Non-SuperAdmin has no allowed apps
+                        VS-->>RES: 401 APP_NOT_AUTHORIZED
+                    else Token allowedApps has wildcard but user apps do not include APP_NAME
+                        VS-->>RES: 401 APP_NOT_AUTHORIZED
+                    else Token allowedApps does not include APP_NAME
+                        VS-->>RES: 401 APP_NOT_AUTHORIZED
+                    else App access allowed
+                        VS->>VS: attachApiTokenUser(req, res, tokenUser)
+                        Note over VS: Sets req.auth, req.user, req.userRole,<br/>and request-local req.session.user.
+
+                        alt tokenScope does not allow req.method
+                            VS-->>RES: 403 TOKEN_SCOPE_INSUFFICIENT
+                        else token scope allows method
+                            VS-->>R: next()
+                        end
+                    end
+                end
+            end
+        end
+    else No Authorization header
+        VS->>JT: isJsonRequest(req)
+        JT-->>VS: prefersJson
+        VS->>CS: validateCookieSession(req, res, next, prefersJson)
+
+        alt req.session.user is missing
+            alt prefersJson
+                CS-->>RES: 401 SESSION_NOT_FOUND
+            else browser/page request
+                CS-->>RES: 302 /mbkauthe/login?redirect=...&reason=logged_out
+            end
+        else req.session.user exists
+            CS->>CS: Read req.session.user.sessionId
+
+            alt sessionId missing or not UUID
+                CS->>CS: destroy session and clear cookies
+                alt prefersJson
+                    CS-->>RES: 401 SESSION_EXPIRED
+                else browser/page request
+                    CS-->>RES: Render "Session Expired" error page
+                end
+            else sessionId is UUID
+                CS->>DB: getSessionAuthData(sessionId)
+
+                alt DB session row not found
+                    CS->>CS: destroy session and clear cookies
+                    alt prefersJson
+                        CS-->>RES: 401 SESSION_INVALID
+                    else browser/page request
+                        CS-->>RES: Render "Session Expired" error page
+                    end
+                else DB session row found
+                    DB-->>CS: session row joined to user
+
+                    alt session expired
+                        CS->>CS: destroy session and clear cookies
+                        CS-->>RES: 401 SESSION_EXPIRED or rendered error page
+                    else user account inactive
+                        CS->>CS: destroy session and clear cookies
+                        CS-->>RES: 401 ACCOUNT_INACTIVE or rendered support page
+                    else user not allowed for APP_NAME
+                        CS->>CS: destroy session and clear cookies
+                        CS-->>RES: 401 APP_NOT_AUTHORIZED or rendered unauthorized page
+                    else session valid and app access allowed
+                        CS->>CS: req.userRole = sessionRow.Role
+                        CS-->>R: next()
+                    end
+                end
+            end
+        end
+    end
+
+    opt Token or session validation throws
+        VS-->>RES: 500 INTERNAL_SERVER_ERROR
+    end

package/docs/diagrams/c.md

@@ -0,0 +1,122 @@
+```mermaid
+sequenceDiagram
+    autonumber
+
+    participant R as Protected Route
+    participant VS as validateSession
+    participant JT as isJsonRequest
+    participant VT as validateTokenAuthentication
+    participant CS as validateCookieSession
+    participant DB as AuthRepository / DB
+    participant RES as Response
+
+    R->>VS: validateSession(req, res, next, strictTokenValidation?)
+
+    alt Authorization header exists
+        alt strictTokenValidation is true
+            VS-->>RES: 401 INVALID_AUTH_TOKEN
+            Note over VS,RES: Token auth is rejected for strict cookie-only middleware.
+        else token auth allowed
+            VS->>VT: validateTokenAuthentication(req)
+
+            alt Header is not "Bearer <token>"
+                VT-->>VS: null
+                VS-->>RES: 401 INVALID_AUTH_TOKEN
+            else Token does not start with mbk_ or is too long
+                VT-->>VS: { error: "INVALID_TOKEN" }
+                VS-->>RES: 401 INVALID_AUTH_TOKEN
+            else Token format is accepted
+                VT->>VT: hashApiToken(token)
+                VT->>DB: getApiTokenByHash(tokenHash)
+
+                alt API token row not found
+                    DB-->>VT: null
+                    VT-->>VS: { error: "INVALID_TOKEN" }
+                    VS-->>RES: 401 INVALID_AUTH_TOKEN
+                else API token expired
+                    DB-->>VT: row with ExpiresAt <= now
+                    VT-->>VS: { error: "TOKEN_EXPIRED" }
+                    VS-->>RES: 401 API_TOKEN_EXPIRED
+                else API token found
+                    DB-->>VT: token row joined to user
+                    VT->>VT: Resolve token scope and allowedApps
+                    VT->>DB: updateApiTokenLastUsed(row.id) async
+                    VT-->>VS: tokenUser
+
+                    alt tokenUser.active is false
+                        VS-->>RES: 401 ACCOUNT_INACTIVE
+                    else Non-SuperAdmin has no allowed apps
+                        VS-->>RES: 401 APP_NOT_AUTHORIZED
+                    else Token allowedApps has wildcard but user apps do not include APP_NAME
+                        VS-->>RES: 401 APP_NOT_AUTHORIZED
+                    else Token allowedApps does not include APP_NAME
+                        VS-->>RES: 401 APP_NOT_AUTHORIZED
+                    else App access allowed
+                        VS->>VS: attachApiTokenUser(req, res, tokenUser)
+                        Note over VS: Sets req.auth, req.user, req.userRole,<br/>and request-local req.session.user.
+
+                        alt tokenScope does not allow req.method
+                            VS-->>RES: 403 TOKEN_SCOPE_INSUFFICIENT
+                        else token scope allows method
+                            VS-->>R: next()
+                        end
+                    end
+                end
+            end
+        end
+    else No Authorization header
+        VS->>JT: isJsonRequest(req)
+        JT-->>VS: prefersJson
+        VS->>CS: validateCookieSession(req, res, next, prefersJson)
+
+        alt req.session.user is missing
+            alt prefersJson
+                CS-->>RES: 401 SESSION_NOT_FOUND
+            else browser/page request
+                CS-->>RES: 302 /mbkauthe/login?redirect=...&reason=logged_out
+            end
+        else req.session.user exists
+            CS->>CS: Read req.session.user.sessionId
+
+            alt sessionId missing or not UUID
+                CS->>CS: destroy session and clear cookies
+                alt prefersJson
+                    CS-->>RES: 401 SESSION_EXPIRED
+                else browser/page request
+                    CS-->>RES: Render "Session Expired" error page
+                end
+            else sessionId is UUID
+                CS->>DB: getSessionAuthData(sessionId)
+
+                alt DB session row not found
+                    CS->>CS: destroy session and clear cookies
+                    alt prefersJson
+                        CS-->>RES: 401 SESSION_INVALID
+                    else browser/page request
+                        CS-->>RES: Render "Session Expired" error page
+                    end
+                else DB session row found
+                    DB-->>CS: session row joined to user
+
+                    alt session expired
+                        CS->>CS: destroy session and clear cookies
+                        CS-->>RES: 401 SESSION_EXPIRED or rendered error page
+                    else user account inactive
+                        CS->>CS: destroy session and clear cookies
+                        CS-->>RES: 401 ACCOUNT_INACTIVE or rendered support page
+                    else user not allowed for APP_NAME
+                        CS->>CS: destroy session and clear cookies
+                        CS-->>RES: 401 APP_NOT_AUTHORIZED or rendered unauthorized page
+                    else session valid and app access allowed
+                        CS->>CS: req.userRole = sessionRow.Role
+                        CS-->>R: next()
+                    end
+                end
+            end
+        end
+    end
+
+    opt Token or session validation throws
+        VS-->>RES: 500 INTERNAL_SERVER_ERROR
+    end
+```

package/docs/{env.md → guides/configuration.md}

@@ -1,6 +1,7 @@
 # Environment Configuration Guide
 
-[← Back to README](README.md)
+[Back to docs index](../README.md) | [Back to project README](../../README.md)
+
 This document describes the environment variables MBKAuth expects and keeps brief usage notes for each parameter. Validation and defaults are implemented in `lib/config/index.js` (it parses `mbkautheVar`, applies optional `mbkauthShared` fallbacks, normalizes values, and throws on validation failures).
 
 ## How configuration is provided

package/docs/{db.md → guides/database.md}

@@ -1,6 +1,8 @@
 # Database Schema
 
-**Executable DDL lives only in [`docs/db.sql`](db.sql).** This file explains what that script creates and how the app uses it. Run the script against Postgres when bootstrapping or aligning a database (for example `psql $DATABASE_URL -f docs/db.sql`). The app can also apply it via `lib/createTable.js`, which reads `docs/db.sql`.
+[Back to docs index](../README.md) | [Back to project README](../../README.md)
+
+**Executable DDL lives only in [`docs/schema/db.sql`](../schema/db.sql).** This file explains what that script creates and how the app uses it. Run the script against Postgres when bootstrapping or aligning a database (for example `psql $DATABASE_URL -f docs/schema/db.sql`). The app can also apply it via `lib/createTable.js`, which reads `docs/schema/db.sql`.
 
 ---