@mhiliger/auth-be 1.0.0

package/README.md

@@ -0,0 +1,140 @@
+# @your-org/auth-be
+
+Shared authentication backend for Express.js applications. This package provides:
+- Secure JWT (JSON Web Token) issuance and verification.
+- User registration workflow (Sign up -> Verify Email -> Admin Approve -> Set Password).
+- Role-based access control middleware.
+- Database adapter pattern for user management.
+
+## Installation
+
+```bash
+npm install @your-org/auth-be express jsonwebtoken express-rate-limit pg-promise
+```
+
+## Setup
+
+### 1. Configure Database Adapter
+
+Create a database adapter that implements the required methods. The package provides a standard `createPostgresAdapter` that works with a specific schema.
+
+**Database Schema:**
+
+The adapter expects tables: `users`, `roles`, `permissions`, `UserRoles`, `RolePerms`, `registration_tokens`.
+See migration scripts in your project for exact schema.
+
+**Initialize Adapter:**
+
+```javascript
+// db/index.js
+const pgp = require("pg-promise")();
+const db = pgp({
+  host: process.env.DB_HOST,
+  port: process.env.DB_PORT,
+  database: "SysAccess",
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD
+});
+
+const { createPostgresAdapter } = require("@your-org/auth-be");
+const authAdapter = createPostgresAdapter(db);
+
+module.exports = authAdapter;
+```
+
+### 2. Configure Email Service
+
+You need an email service to send verification links. Implement an object with these methods:
+
+```javascript
+const emailService = {
+  sendVerificationEmail: async (user, token) => { ... },
+  sendAdminNotification: async (user, adminEmail) => { ... },
+  sendApprovalEmail: async (user, token) => { ... },
+  sendRejectionEmail: async (user, reason) => { ... },
+  sendPasswordResetEmail: async (user, token) => { ... }
+};
+```
+
+### 3. Initialize Express App
+
+Mount the auth and registration routers.
+
+```javascript
+const express = require("express");
+const cookieParser = require("cookie-parser");
+const { createAuthRouter, createRegistrationRouter, createVerifyJWT } = require("@your-org/auth-be");
+const authAdapter = require("./db"); // Your adapter
+const emailService = require("./services/email"); // Your service
+
+const app = express();
+app.use(express.json());
+app.use(cookieParser());
+
+// Secrets Configuration
+const authConfig = {
+  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET,
+  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
+  accessTokenLife: "15m",
+  refreshTokenLife: "1d",
+  loginPath: "/auth", // Endpoint for login
+};
+
+// 1. Mount Auth Routes (Login, Refresh, Logout)
+app.use("/", createAuthRouter({
+  db: authAdapter,
+  config: authConfig
+}));
+
+// 2. Configure JWT Verification Middleware
+const verifyJWT = createVerifyJWT({
+  accessTokenSecret: authConfig.accessTokenSecret,
+  onVerifySuccess: (req, decoded) => {
+    // Attach user info to request
+    req.user = decoded;
+    req.permissions = decoded.permissions;
+  }
+});
+
+// 3. Mount Registration Routes (Public + Admin)
+app.use("/", createRegistrationRouter({
+  db: authAdapter,
+  verifyJWT: verifyJWT, // Protect admin routes
+  config: {
+    verificationTokenLife: "24h",
+    passwordSetupTokenLife: "48h",
+    // Callbacks for email notifications
+    onRegistrationSubmit: (user, token) => emailService.sendVerificationEmail(user, token),
+    onEmailVerified: (user) => emailService.sendAdminNotification(user, "admin@example.com"),
+    onApproval: (user, token) => emailService.sendApprovalEmail(user, token),
+    onRejection: (user, reason) => emailService.sendRejectionEmail(user, reason),
+    onPasswordReset: (user, token) => emailService.sendPasswordResetEmail(user, token),
+  }
+}));
+
+// 4. Protect Your API Routes
+app.get("/api/protected-resource", verifyJWT, (req, res) => {
+  res.json({ message: "You are authorized!", user: req.user });
+});
+
+app.listen(3000, () => console.log("Server running"));
+```
+
+## API Reference
+
+### `createAuthRouter({ db, config })`
+Creates routes:
+- `POST /auth` (Login)
+- `GET /refresh` (Refresh Token)
+- `POST /logout` (Logout)
+
+### `createRegistrationRouter({ db, verifyJWT, config })`
+Creates routes:
+- `POST /register/submit`
+- `GET /register/verify/:token`
+- `GET /register/setup/:token`
+- `POST /register/setup/:token`
+- `POST /register/forgot-password`
+
+### `createVerifyJWT({ accessTokenSecret, onVerifySuccess })`
+Middleware that verifies the Bearer token in the `Authorization` header.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@mhiliger/auth-be",
+  "version": "1.0.0",
+  "description": "Shared authentication and JWT management for Express.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0",
+    "express-rate-limit": "^7.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/adapters/PostgresAdapter.js

@@ -0,0 +1,214 @@
+/**
+ * A standard Postgres adapter for the authentication library.
+ * Assumes a schema with 'users', 'roles', 'permissions', 'UserRoles', and 'RolePerms' tables.
+ *
+ * @param {Object} db - A database connection object (e.g., pg-promise instance).
+ * @returns {Object} An auth adapter implementation.
+ */
+const createPostgresAdapter = (db) => ({
+  /**
+   * Validates user credentials using PostgreSQL crypt function.
+   */
+  validateUser: async (email, password) => {
+    const userRecord = await db.manyOrNone(
+      "SELECT id, email, first, last, status FROM users WHERE email=$1 AND PASSWORD = crypt($2, PASSWORD)",
+      [email, password]
+    );
+    return userRecord.length === 1 ? userRecord[0] : null;
+  },
+
+  /**
+   * Retrieves user permissions IDs.
+   */
+  getUserPermissions: async (email) => {
+    const result = await db.manyOrNone(
+      `SELECT DISTINCT p.perm_key FROM users AS u
+       JOIN "UserRoles" AS ur ON u.id = ur.userid
+       JOIN roles AS r ON r.id = ur.roleid
+       JOIN "RolePerms" AS rp ON r.id = rp.roleid
+       JOIN permissions AS p ON p.id = rp.permid
+       WHERE u.email = $1`,
+      [email]
+    );
+    return result.map((perm) => ({ perm_key: perm.perm_key }));
+  },
+
+  /**
+   * Saves the refresh token for a user.
+   */
+  saveRefreshToken: async (userId, refreshtoken) => {
+    return await db.none("UPDATE users SET refreshtoken = $1 WHERE id = $2", [refreshtoken, userId]);
+  },
+
+  /**
+   * Finds a user by their refresh token.
+   */
+  findUserByRefreshToken: async (refreshToken) => {
+    const result = await db.manyOrNone(
+      "SELECT id, email, first, last, status FROM users WHERE refreshtoken = $1",
+      [refreshToken]
+    );
+    return result.length > 0 ? result[0] : null;
+  },
+
+  /**
+   * Clears the refresh token for a user.
+   */
+  clearRefreshToken: async (userId) => {
+    return await db.none("UPDATE users SET refreshtoken = '' WHERE id = $1", [userId]);
+  },
+
+  // ==================== Registration Workflow Methods ====================
+
+  /**
+   * Finds a user by their email address.
+   * @param {string} email - The email to search for.
+   * @returns {Object|null} The user record or null if not found.
+   */
+  findUserByEmail: async (email) => {
+    const result = await db.manyOrNone(
+      "SELECT id, email, first, last, status, request_note, admin_rejection_note FROM users WHERE email = $1",
+      [email]
+    );
+    return result.length > 0 ? result[0] : null;
+  },
+
+  /**
+   * Creates a new registration request (user with PENDING_VERIFICATION status).
+   * @param {string} email - User's email address.
+   * @param {string} first - User's first name.
+   * @param {string} last - User's last name.
+   * @param {string} requestNote - User's note explaining why they need access.
+   * @returns {Object} The created user record.
+   */
+  createRegistrationRequest: async (email, first, last, requestNote) => {
+    const result = await db.one(
+      `INSERT INTO users (email, first, last, status, request_note)
+       VALUES ($1, $2, $3, 'PENDING_VERIFICATION', $4)
+       RETURNING id, email, first, last, status, request_note`,
+      [email, first, last, requestNote || "Requesting login id to system"]
+    );
+    return result;
+  },
+
+  /**
+   * Updates a user's status.
+   * @param {number} userId - The user's ID.
+   * @param {string} status - The new status value.
+   */
+  updateUserStatus: async (userId, status) => {
+    return await db.none("UPDATE users SET status = $1 WHERE id = $2", [status, userId]);
+  },
+
+  /**
+   * Saves a registration token (email verification or password setup).
+   * @param {number} userId - The user's ID.
+   * @param {string} tokenHash - SHA-256 hash of the token.
+   * @param {string} tokenType - 'email_verification' or 'password_setup'.
+   * @param {Date} expiresAt - Token expiration timestamp.
+   * @returns {Object} The created token record.
+   */
+  saveRegistrationToken: async (userId, tokenHash, tokenType, expiresAt) => {
+    const result = await db.one(
+      `INSERT INTO registration_tokens (user_id, token_hash, token_type, expires_at)
+       VALUES ($1, $2, $3, $4)
+       RETURNING id, user_id, token_type, expires_at, created_at`,
+      [userId, tokenHash, tokenType, expiresAt]
+    );
+    return result;
+  },
+
+  /**
+   * Finds a valid (unexpired, unused) token by its hash.
+   * @param {string} tokenHash - SHA-256 hash of the token.
+   * @param {string} tokenType - 'email_verification' or 'password_setup'.
+   * @returns {Object|null} The token record with user info, or null if not found/invalid.
+   */
+  findValidToken: async (tokenHash, tokenType) => {
+    const result = await db.manyOrNone(
+      `SELECT t.id, t.user_id, t.token_type, t.expires_at, t.used_at,
+              u.email, u.first, u.last, u.status, u.request_note
+       FROM registration_tokens t
+       JOIN users u ON t.user_id = u.id
+       WHERE t.token_hash = $1
+         AND t.token_type = $2
+         AND t.expires_at > NOW()
+         AND t.used_at IS NULL`,
+      [tokenHash, tokenType]
+    );
+    return result.length > 0 ? result[0] : null;
+  },
+
+  /**
+   * Marks a token as used.
+   * @param {number} tokenId - The token's ID.
+   */
+  markTokenUsed: async (tokenId) => {
+    return await db.none("UPDATE registration_tokens SET used_at = NOW() WHERE id = $1", [tokenId]);
+  },
+
+  /**
+   * Invalidates all tokens of a specific type for a user.
+   * @param {number} userId - The user's ID.
+   * @param {string} tokenType - 'email_verification' or 'password_setup'.
+   */
+  invalidateUserTokens: async (userId, tokenType) => {
+    return await db.none(
+      "UPDATE registration_tokens SET used_at = NOW() WHERE user_id = $1 AND token_type = $2 AND used_at IS NULL",
+      [userId, tokenType]
+    );
+  },
+
+  /**
+   * Gets all users with PENDING_APPROVAL status.
+   * @returns {Array} List of pending registration requests.
+   */
+  getPendingRegistrations: async () => {
+    const result = await db.manyOrNone(
+      `SELECT id, email, first, last, status, request_note, admin_rejection_note
+       FROM users
+       WHERE status = 'PENDING_APPROVAL'
+       ORDER BY id DESC`
+    );
+    return result;
+    console.log("Pending registrations retrieved:");
+  },
+
+  /**
+   * Gets a single registration by user ID.
+   * @param {number} id - The user's ID.
+   * @returns {Object|null} The user record or null if not found.
+   */
+  getRegistrationById: async (id) => {
+    const result = await db.manyOrNone(
+      `SELECT id, email, first, last, status, request_note, admin_rejection_note
+       FROM users
+       WHERE id = $1`,
+      [id]
+    );
+    return result.length > 0 ? result[0] : null;
+  },
+
+  /**
+   * Sets the admin rejection note for a user.
+   * @param {number} userId - The user's ID.
+   * @param {string} note - The rejection reason.
+   */
+  setAdminRejectionNote: async (userId, note) => {
+    return await db.none("UPDATE users SET admin_rejection_note = $1 WHERE id = $2", [note, userId]);
+  },
+
+  /**
+   * Sets the user's password using PostgreSQL crypt function.
+   * @param {number} userId - The user's ID.
+   * @param {string} password - The plain text password (will be hashed).
+   */
+  setUserPassword: async (userId, password) => {
+    return await db.none(
+      "UPDATE users SET password = crypt($1, gen_salt('bf')) WHERE id = $2",
+      [password, userId]
+    );
+  }
+});
+
+module.exports = createPostgresAdapter;

package/src/index.js

@@ -0,0 +1,17 @@
+const createAuthRouter = require("./routes/authFactory");
+const createRegistrationRouter = require("./routes/registrationFactory");
+const createVerifyJWT = require("./middleware/verifyJWT");
+const createPostgresAdapter = require("./adapters/PostgresAdapter");
+const { createRegistrationLimiter, createVerificationLimiter } = require("./middleware/rateLimiter");
+const { generateToken, hashToken } = require("./utils/tokenGenerator");
+
+module.exports = {
+  createAuthRouter,
+  createRegistrationRouter,
+  createVerifyJWT,
+  createPostgresAdapter,
+  createRegistrationLimiter,
+  createVerificationLimiter,
+  generateToken,
+  hashToken,
+};

package/src/middleware/rateLimiter.js

@@ -0,0 +1,40 @@
+const rateLimit = require("express-rate-limit");
+
+/**
+ * Creates a rate limiter for registration endpoints.
+ * @param {Object} config - Configuration options.
+ * @param {number} [config.windowMs=3600000] - Time window in milliseconds (default: 1 hour).
+ * @param {number} [config.max=5] - Maximum requests per window (default: 5).
+ * @returns {Function} Express rate limiting middleware.
+ */
+const createRegistrationLimiter = (config = {}) => {
+  return rateLimit({
+    windowMs: config.windowMs || 60 * 60 * 1000, // 1 hour default
+    max: config.max || 5,
+    message: { error: "Too many requests, please try again later" },
+    standardHeaders: true,
+    legacyHeaders: false,
+  });
+};
+
+/**
+ * Creates a rate limiter for verification endpoints (more lenient).
+ * @param {Object} config - Configuration options.
+ * @param {number} [config.windowMs=3600000] - Time window in milliseconds (default: 1 hour).
+ * @param {number} [config.max=10] - Maximum requests per window (default: 10).
+ * @returns {Function} Express rate limiting middleware.
+ */
+const createVerificationLimiter = (config = {}) => {
+  return rateLimit({
+    windowMs: config.windowMs || 60 * 60 * 1000, // 1 hour default
+    max: config.max || 10,
+    message: { error: "Too many requests, please try again later" },
+    standardHeaders: true,
+    legacyHeaders: false,
+  });
+};
+
+module.exports = {
+  createRegistrationLimiter,
+  createVerificationLimiter,
+};

package/src/middleware/verifyJWT.js

@@ -0,0 +1,50 @@
+const jwt = require("jsonwebtoken");
+
+/**
+ * Factory to create verifyJWT middleware with custom configuration.
+ * @param {Object} config - Configuration object
+ * @param {string} config.accessTokenSecret - The secret used to verify the access token.
+ * @param {Function} [config.onVerifySuccess] - Optional callback when verification succeeds, receives (req, decoded).
+ * @param {Function} [config.onVerifyError] - Optional callback when verification fails, receives (res, error).
+ * @returns {Function} Express middleware
+ */
+const createVerifyJWT = (config) => {
+  const { accessTokenSecret, onVerifySuccess, onVerifyError } = config;
+
+  if (!accessTokenSecret) {
+    throw new Error("accessTokenSecret is required for verifyJWT middleware");
+  }
+
+  return (req, res, next) => {
+    const authHeader = req?.headers["authorization"] || req?.headers["Authorization"];
+    
+    if (!authHeader?.startsWith("Bearer ")) {
+      if (onVerifyError) return onVerifyError(res, new Error("No Bearer token provided"));
+      return res.status(401).json({ error: "no header to verify jwt" });
+    }
+
+    const token = authHeader.split(" ")[1];
+
+    try {
+      const decoded = jwt.verify(token, accessTokenSecret);
+      
+      // Default behavior: attach common fields to req
+      req.user = decoded;
+      // Also attach specific fields for backward compatibility if needed or as configured
+      if (onVerifySuccess) {
+        onVerifySuccess(req, decoded);
+      } else {
+        req.email = decoded.email;
+        req.permissions = decoded.permissions;
+        req.userId = decoded.userId;
+      }
+
+      next();
+    } catch (error) {
+      if (onVerifyError) return onVerifyError(res, error);
+      return res.status(403).json({ error: "error verifying jwt" });
+    }
+  };
+};
+
+module.exports = createVerifyJWT;

package/src/routes/authFactory.js

@@ -0,0 +1,140 @@
+const express = require("express");
+const jwt = require("jsonwebtoken");
+
+/**
+ * Creates an Express router with auth endpoints.
+ * @param {Object} options - Configuration options
+ * @param {Object} options.db - Database interface object
+ * @param {Object} options.queries - Object containing SQL queries or functions
+ * @param {Object} options.config - Config for secrets and tokens
+ * @returns {express.Router}
+ */
+const createAuthRouter = ({ db, queries, config }) => {
+  const router = express.Router();
+
+  const {
+    accessTokenSecret,
+    refreshTokenSecret,
+    accessTokenLife,
+    refreshTokenLife,
+    cookieName = "jwt",
+    cookieOptions = {
+      httpOnly: true,
+      sameSite: "None",
+      secure: true,
+      maxAge: 24 * 60 * 60 * 1000,
+    },
+    loginPath = "/login",
+  } = config;
+
+  // Login Route
+  router.post(loginPath, async (req, res) => {
+    const { email, password } = req.body;
+
+    if (!email || !password) {
+      return res.status(400).json({ error: "missing user or password" });
+    }
+
+    try {
+      // 1. Validate User Credentials
+      // This should return user details if valid, or null/throw if not
+      const user = await db.validateUser(email, password);
+      if (!user) {
+        return res.status(401).json({ error: "Invalid credentials." });
+      }
+
+      // 2. Get Permissions
+      const permissions = await db.getUserPermissions(email);
+      if (!permissions || permissions.length === 0) {
+        return res.status(403).json({ error: "No permissions for user" });
+      }
+
+      // 3. Create Tokens
+      const payload = {
+        userId: user.id,
+        email: user.email,
+        first: user.first,
+        last: user.last,
+        status: user.status,
+        permissions: [...new Set(permissions)],
+      };
+
+      const accessToken = jwt.sign(payload, accessTokenSecret, { expiresIn: accessTokenLife });
+      const refreshToken = jwt.sign(payload, refreshTokenSecret, { expiresIn: refreshTokenLife });
+
+      // 4. Save Refresh Token to DB
+      await db.saveRefreshToken(user.id, refreshToken);
+
+      // 5. Respond
+      res.cookie(cookieName, refreshToken, cookieOptions);
+      res.status(200).json({ accessToken });
+    } catch (error) {
+      console.error("Login error:", error);
+      res.status(500).json({ error: "Internal server error during login" });
+    }
+  });
+
+  // Refresh Token Route
+  router.get("/refresh", async (req, res) => {
+    const cookies = req.cookies;
+    if (!cookies?.[cookieName]) return res.status(403).json({ error: "Missing refresh token" });
+
+    const refreshToken = cookies[cookieName];
+
+    try {
+      // 1. Find user by refresh token
+      const user = await db.findUserByRefreshToken(refreshToken);
+      if (!user) return res.status(403).json({ error: "Invalid refresh token" });
+
+      // 2. Verify token
+      const decoded = jwt.verify(refreshToken, refreshTokenSecret);
+      if (user.email !== decoded.email) {
+        return res.status(403).json({ error: "Token mismatch" });
+      }
+
+      // 3. Refresh Permissions
+      const permissions = await db.getUserPermissions(user.email);
+      
+      // 4. Issue new Access Token
+      const payload = {
+        userId: user.id,
+        email: user.email,
+        first: user.first,
+        last: user.last,
+        status: user.status,
+        permissions: [...new Set(permissions)],
+      };
+
+      const accessToken = jwt.sign(payload, accessTokenSecret, { expiresIn: accessTokenLife });
+      res.json({ accessToken });
+    } catch (error) {
+      console.error("Refresh error:", error);
+      res.status(403).json({ error: "Refresh failed" });
+    }
+  });
+
+  // Logout Route
+  router.post("/logout", async (req, res) => {
+    const cookies = req.cookies;
+    if (!cookies?.[cookieName]) return res.sendStatus(204);
+
+    const refreshToken = cookies[cookieName];
+
+    try {
+      const user = await db.findUserByRefreshToken(refreshToken);
+      if (user) {
+        await db.clearRefreshToken(user.id);
+      }
+    } catch (error) {
+      // Log error but proceed to clear cookie
+      console.error("Logout DB error:", error);
+    }
+
+    res.clearCookie(cookieName, cookieOptions);
+    res.sendStatus(204);
+  });
+
+  return router;
+};
+
+module.exports = createAuthRouter;

package/src/routes/registrationFactory.js

@@ -0,0 +1,340 @@
+const express = require("express");
+const { generateToken, hashToken } = require("../utils/tokenGenerator");
+const { createRegistrationLimiter, createVerificationLimiter } = require("../middleware/rateLimiter");
+
+/**
+ * Parses a duration string (e.g., '24h', '48h') into milliseconds.
+ * @param {string} duration - Duration string like '24h', '1d', '30m'.
+ * @returns {number} Milliseconds.
+ */
+const parseDuration = (duration) => {
+  const match = duration.match(/^(\d+)([hdm])$/);
+  if (!match) return 24 * 60 * 60 * 1000; // default 24h
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case "h":
+      return value * 60 * 60 * 1000;
+    case "d":
+      return value * 24 * 60 * 60 * 1000;
+    case "m":
+      return value * 60 * 1000;
+    default:
+      return 24 * 60 * 60 * 1000;
+  }
+};
+
+/**
+ * Creates registration workflow routes.
+ * @param {Object} options
+ * @param {Object} options.db - Database adapter with registration methods.
+ * @param {Object} options.config - Configuration options.
+ * @param {string} [options.config.verificationTokenLife='24h'] - Verification token lifetime.
+ * @param {string} [options.config.passwordSetupTokenLife='48h'] - Password setup token lifetime.
+ * @param {Array<number>} [options.config.adminPermissionIds=["AllowUsers"]] - Permission IDs required for admin operations.
+ * @param {number} [options.config.rateLimitWindowMs] - Rate limit window in ms.
+ * @param {number} [options.config.rateLimitMax] - Rate limit max requests.
+ * @param {Function} [options.config.onRegistrationSubmit] - Callback when registration is submitted (user, token).
+ * @param {Function} [options.config.onEmailVerified] - Callback when email is verified (user).
+ * @param {Function} [options.config.onApproval] - Callback when admin approves (user, token).
+ * @param {Function} [options.config.onRejection] - Callback when admin rejects (user, reason).
+ * @param {Function} [options.verifyJWT] - JWT verification middleware for admin routes.
+ * @returns {express.Router}
+ */
+const createRegistrationRouter = ({ db, config = {}, verifyJWT }) => {
+  const router = express.Router();
+
+  const {
+    verificationTokenLife = "24h",
+    passwordSetupTokenLife = "48h",
+    rateLimitWindowMs,
+    rateLimitMax,
+    onRegistrationSubmit,
+    onEmailVerified,
+    onApproval,
+    onRejection,
+    onPasswordReset,
+  } = config;
+
+  // Rate limiters
+  const submitLimiter = createRegistrationLimiter({
+    windowMs: rateLimitWindowMs,
+    max: rateLimitMax,
+  });
+  const verifyLimiter = createVerificationLimiter({
+    windowMs: rateLimitWindowMs,
+    max: rateLimitMax ? rateLimitMax * 2 : undefined,
+  });
+
+  // ==================== Public Routes ====================
+
+  /**
+   * Phase 1: Submit Registration
+   * POST /register/submit
+   */
+  router.post("/register/submit", submitLimiter, async (req, res) => {
+    try {
+      const { email, first, last, requestNote } = req.body;
+
+      // Validate required fields
+      if (!email || !first || !last) {
+        return res.status(400).json({ error: "Email, first name, and last name are required" });
+      }
+
+      // Basic email validation
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      if (!emailRegex.test(email)) {
+        return res.status(400).json({ error: "Invalid email format" });
+      }
+
+      // Validate request note length
+      if (requestNote && requestNote.length > 256) {
+        return res.status(400).json({ error: "Request note must be 256 characters or less" });
+      }
+
+      // Check if email already exists
+      const existingUser = await db.findUserByEmail(email);
+      if (existingUser) {
+        // Return generic success to prevent user enumeration
+        return res.json({
+          success: true,
+          message: "If this email is not already registered, you will receive a verification email shortly.",
+        });
+      }
+
+      // Create the registration request
+      const user = await db.createRegistrationRequest(email, first, last, requestNote);
+
+      // Generate verification token
+      const { token, tokenHash } = generateToken();
+      const expiresAt = new Date(Date.now() + parseDuration(verificationTokenLife));
+
+      await db.saveRegistrationToken(user.id, tokenHash, "email_verification", expiresAt);
+
+      // Send verification email via callback
+      if (onRegistrationSubmit) {
+        try {
+          await onRegistrationSubmit(user, token);
+        } catch (emailError) {
+          console.error("Failed to send verification email:", emailError);
+          // Don't fail the registration if email fails
+        }
+      }
+
+      res.json({
+        success: true,
+        message: "If this email is not already registered, you will receive a verification email shortly.",
+      });
+    } catch (error) {
+      console.error("Registration submit error:", error);
+      res.status(500).json({ error: "An error occurred during registration" });
+    }
+  });
+
+  /**
+   * Phase 2: Verify Email
+   * GET /register/verify/:token
+   */
+  router.get("/register/verify/:token", verifyLimiter, async (req, res) => {
+    try {
+      const { token } = req.params;
+
+      if (!token) {
+        return res.status(400).json({ error: "Token is required" });
+      }
+
+      const tokenHash = hashToken(token);
+      const tokenRecord = await db.findValidToken(tokenHash, "email_verification");
+
+      if (!tokenRecord) {
+        return res.status(400).json({ error: "Invalid or expired verification link" });
+      }
+
+      // Check if user is in correct state
+      if (tokenRecord.status !== "PENDING_VERIFICATION") {
+        return res.status(400).json({ error: "Email has already been verified" });
+      }
+
+      // Mark token as used
+      await db.markTokenUsed(tokenRecord.id);
+
+      // Update user status to PENDING_APPROVAL
+      await db.updateUserStatus(tokenRecord.user_id, "PENDING_APPROVAL");
+
+      // Notify admin via callback
+      if (onEmailVerified) {
+        try {
+          const user = {
+            id: tokenRecord.user_id,
+            email: tokenRecord.email,
+            first: tokenRecord.first,
+            last: tokenRecord.last,
+            request_note: tokenRecord.request_note,
+          };
+          await onEmailVerified(user);
+        } catch (notifyError) {
+          console.error("Failed to notify admin:", notifyError);
+          // Don't fail the verification if notification fails
+        }
+      }
+
+      res.json({
+        success: true,
+        message: "Email verified successfully. Your request is now pending administrator review.",
+      });
+    } catch (error) {
+      console.error("Email verification error:", error);
+      res.status(500).json({ error: "An error occurred during verification" });
+    }
+  });
+
+  /**
+   * Phase 4: Validate Password Setup Token
+   * GET /register/setup/:token
+   */
+  router.get("/register/setup/:token", verifyLimiter, async (req, res) => {
+    try {
+      const { token } = req.params;
+
+      if (!token) {
+        return res.status(400).json({ error: "Token is required" });
+      }
+
+      const tokenHash = hashToken(token);
+      const tokenRecord = await db.findValidToken(tokenHash, "password_setup");
+
+      if (!tokenRecord) {
+        return res.status(400).json({ error: "Invalid or expired setup link" });
+      }
+
+      // Check if user is in correct state
+      if (tokenRecord.status !== "APPROVED" && tokenRecord.status !== "ACTIVE") {
+        return res.status(400).json({ error: "Account is not in the correct state for password setup" });
+      }
+
+      res.json({
+        success: true,
+        valid: true,
+        email: tokenRecord.email,
+        first: tokenRecord.first,
+      });
+    } catch (error) {
+      console.error("Setup token validation error:", error);
+      res.status(500).json({ error: "An error occurred during validation" });
+    }
+  });
+
+  /**
+   * Phase 4: Set Password
+   * POST /register/setup/:token
+   */
+  router.post("/register/setup/:token", submitLimiter, async (req, res) => {
+    try {
+      const { token } = req.params;
+      const { password } = req.body;
+
+      if (!token) {
+        return res.status(400).json({ error: "Token is required" });
+      }
+
+      if (!password) {
+        return res.status(400).json({ error: "Password is required" });
+      }
+
+      // Validate password format (same as PWD_REGEX in frontend)
+      const pwdRegex = /^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.*[!@#$%]).{8,24}$/;
+      if (!pwdRegex.test(password)) {
+        return res.status(400).json({
+          error: "Password must be 8-24 characters with uppercase, lowercase, number, and special character (!@#$%)",
+        });
+      }
+
+      const tokenHash = hashToken(token);
+      const tokenRecord = await db.findValidToken(tokenHash, "password_setup");
+
+      if (!tokenRecord) {
+        return res.status(400).json({ error: "Invalid or expired setup link" });
+      }
+
+      // Check if user is in correct state
+      if (tokenRecord.status !== "APPROVED" && tokenRecord.status !== "ACTIVE") {
+        return res.status(400).json({ error: "Account is not in the correct state for password setup" });
+      }
+
+      // Mark token as used
+      await db.markTokenUsed(tokenRecord.id);
+
+      // Set password and update status to ACTIVE
+      await db.setUserPassword(tokenRecord.user_id, password);
+      await db.updateUserStatus(tokenRecord.user_id, "ACTIVE");
+
+      res.json({
+        success: true,
+        message: "Password set successfully. You can now log in.",
+      });
+    } catch (error) {
+      console.error("Password setup error:", error);
+      res.status(500).json({ error: "An error occurred during password setup" });
+    }
+  });
+
+  /**
+   * Phase 0: Request Password Reset (Public)
+   * POST /register/forgot-password
+   */
+  router.post("/register/forgot-password", submitLimiter, async (req, res) => {
+    try {
+      const { email } = req.body;
+
+      if (!email) {
+        return res.status(400).json({ error: "Email is required" });
+      }
+
+      const user = await db.findUserByEmail(email);
+
+      // We always return a success message to prevent user enumeration
+      const successResponse = {
+        success: true,
+        message: "If an account exists for this email, you will receive a password reset link shortly.",
+      };
+
+      // Only proceed if user exists and is ACTIVE or APPROVED (already has/had access)
+      if (!user || (user.status !== "ACTIVE" && user.status !== "APPROVED")) {
+        return res.json(successResponse);
+      }
+
+      // Invalidate any existing password setup tokens
+      await db.invalidateUserTokens(user.id, "password_setup");
+
+      // Generate password setup token
+      const { token, tokenHash } = generateToken();
+      const expiresAt = new Date(Date.now() + parseDuration(passwordSetupTokenLife));
+
+      await db.saveRegistrationToken(user.id, tokenHash, "password_setup", expiresAt);
+
+      // Send password reset email via callback
+      if (onPasswordReset) {
+        try {
+          await onPasswordReset(user, token);
+        } catch (emailError) {
+          console.error("Failed to send password reset email:", emailError);
+          // Don't fail the request if email fails
+        }
+      }
+
+      res.json(successResponse);
+    } catch (error) {
+      console.error("Forgot password error:", error);
+      res.status(500).json({ error: "An error occurred" });
+    }
+  });
+
+  // ==================== Admin Routes ====================
+  // Admin routes have been moved to the main application (Login-BE/routes/adminRegistrations.js)
+
+  return router;
+};
+
+module.exports = createRegistrationRouter;

package/src/utils/tokenGenerator.js

@@ -0,0 +1,26 @@
+const crypto = require("crypto");
+
+/**
+ * Generates a secure random token and its hash.
+ * The plain token is sent to the user, while only the hash is stored in the database.
+ * @returns {{ token: string, tokenHash: string }}
+ */
+const generateToken = () => {
+  const token = crypto.randomBytes(32).toString("base64url");
+  const tokenHash = crypto.createHash("sha256").update(token).digest("hex");
+  return { token, tokenHash };
+};
+
+/**
+ * Hashes a token for comparison with stored hash.
+ * @param {string} token - The plain token to hash.
+ * @returns {string} The SHA-256 hash of the token.
+ */
+const hashToken = (token) => {
+  return crypto.createHash("sha256").update(token).digest("hex");
+};
+
+module.exports = {
+  generateToken,
+  hashToken,
+};