underpost 2.8.87 → 2.8.88

package/src/server/auth.js

@@ -8,228 +8,592 @@ import dotenv from 'dotenv';
 import jwt from 'jsonwebtoken';
 import { loggerFactory } from './logger.js';
 import crypto from 'crypto';
-import { userRoleEnum } from '../api/user/user.model.js';
+import { promisify } from 'util';
+import { UserDto } from '../api/user/user.model.js';
 import { commonAdminGuard, commonModeratorGuard, validatePassword } from '../client/components/core/CommonJs.js';
+import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
+import slowDown from 'express-slow-down';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import { DataBaseProvider } from '../db/DataBaseProvider.js';
 
 dotenv.config();
-
 const logger = loggerFactory(import.meta);
 
-/* The `const config` object is defining parameters related to the hashing process used for password
-security. Here's a breakdown of each property in the `config` object: */
+// Promisified crypto functions
+const pbkdf2 = promisify(crypto.pbkdf2);
+
+// Config with sane defaults and parsing
 const config = {
-  hashBytes: 32,
-  saltBytes: 16,
-  iterations: 872791,
-  digest: 'sha512',
+  hashBytes: Number(process.env.PBKDF2_HASH_BYTES) || 32,
+  saltBytes: Number(process.env.PBKDF2_SALT_BYTES) || 16,
+  iterations: Number(process.env.PBKDF2_ITERATIONS) || 150_000,
+  digest: process.env.PBKDF2_DIGEST || 'sha512',
+  refreshTokenBytes: Number(process.env.REFRESH_TOKEN_BYTES) || 48,
+  jwtAlgorithm: process.env.JWT_ALGORITHM || 'HS512', // consider RS256 with keys
 };
 
+// ---------- Password hashing (async) ----------
 /**
- * @param {String} password - given password to hash
- * @returns {String} the hash corresponding to the password
+ * Hash password asynchronously using PBKDF2.
+ * Stored format: iterations$salt$hash
+ * @param {string} password The password to hash.
+ * @returns {Promise<string>} The hashed password string.
  * @memberof Auth
  */
-function hashPassword(password) {
-  const { iterations, hashBytes, digest, saltBytes } = config;
-  const salt = crypto.randomBytes(saltBytes).toString('hex');
-  const hash = crypto.pbkdf2Sync(password, salt, iterations, hashBytes, digest).toString('hex');
-  return [salt, hash].join('$');
+async function hashPassword(password) {
+  const salt = crypto.randomBytes(config.saltBytes).toString('hex');
+  const derived = await pbkdf2(password, salt, config.iterations, config.hashBytes, config.digest);
+  return `${config.iterations}$${salt}$${derived.toString('hex')}`;
 }
 
 /**
- * @param {String} password - password to verify
- * @param {String} combined - a combined salt + hash returned by hashPassword function
- * @returns {Boolean} true if password correspond to the hash. False otherwise
+ * Verify password using constant-time comparison
+ * @param {string} password The password to verify.
+ * @param {string} combined The stored hashed password string (iterations$salt$hash).
+ * @returns {Promise<boolean>} True if the password is valid, false otherwise.
  * @memberof Auth
  */
-function verifyPassword(password, combined) {
-  const { iterations, hashBytes, digest } = config;
-  const [salt, originalHash] = combined.split('$');
-  const hash = crypto.pbkdf2Sync(password, salt, iterations, hashBytes, digest).toString('hex');
-  return hash === originalHash;
+async function verifyPassword(password, combined) {
+  if (!combined) return false;
+  const parts = combined.split('$');
+  if (parts.length !== 3) return false;
+  const [itersStr, salt, originalHex] = parts;
+  const iterations = parseInt(itersStr, 10);
+  const derived = await pbkdf2(password, salt, iterations, Buffer.from(originalHex, 'hex').length, config.digest);
+  const original = Buffer.from(originalHex, 'hex');
+  const ok = crypto.timingSafeEqual(derived, original);
+  return ok;
 }
 
-// jwt middleware
-
+// ---------- Token hashing & utilities ----------
 /**
- * The hashJWT function generates a JSON Web Token (JWT) with a specified payload and expiration time.
- * @param payload - The `payload` parameter in the `hashJWT` function is the data that you want to
- * encode into the JSON Web Token (JWT). It typically contains information about the user or any other
- * relevant data that you want to securely transmit.
- * @param expire - The `expire` parameter in the `hashJWT` function is used to specify the expiration
- * time for the JSON Web Token (JWT) being generated. If a value is provided for `expire`, it will be
- * used as the expiration time. If `expire` is not provided (i.e., it
+ * Hashes a token using SHA256.
+ * @param {string} token The token to hash.
+ * @returns {string|null} The hashed token as a hex string, or null if token is falsy.
  * @memberof Auth
  */
-const hashJWT = (payload, expire) =>
-  jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: expire !== undefined ? expire : `${process.env.EXPIRE}h` });
+function hashToken(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update(token).digest('hex');
+}
 
 /**
- * The function `verifyJWT` is used to verify a JSON Web Token (JWT) using a secret key stored in the
- * environment variables.
- * @param token - The `token` parameter is a JSON Web Token (JWT) that is passed to the `verifyJWT`
- * function for verification.
+ * Generates a cryptographically secure random hex string.
+ * @param {number} [bytes=config.refreshTokenBytes] The number of bytes to generate.
+ * @returns {string} The random hex string.
  * @memberof Auth
  */
-const verifyJWT = (token = '') => jwt.verify(token, process.env.JWT_SECRET);
+function generateRandomHex(bytes = config.refreshTokenBytes) {
+  return crypto.randomBytes(bytes).toString('hex');
+}
 
 /**
- * The function `getBearerToken` extracts and returns the Bearer token from the Authorization header in
- * a request object.
- * @param req - The `req` parameter in the `getBearerToken` function is typically an object
- * representing the HTTP request. It is commonly used in Node.js applications with frameworks like
- * Express.js. The `req` object contains information about the incoming HTTP request, including
- * headers, body, parameters, and more. In
- * @returns {String} The function `getBearerToken` is returning the Bearer token extracted from the
- * Authorization header in the request object. If the Authorization header starts with 'Bearer ', it
- * will return the token portion of the header (excluding 'Bearer ').
+ * Generates a JWT issuer and audience based on the host and path.
+ * @param {object} options The options object.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @returns {object} The issuer and audience.
  * @memberof Auth
  */
-const getBearerToken = (req) => {
-  const authHeader = String(req.headers['authorization'] || req.headers['Authorization'] || '');
-  if (authHeader.startsWith('Bearer ')) return authHeader.substring(7, authHeader.length);
-  return '';
-};
+function jwtIssuerAudienceFactory(options = { host: '', path: '' }) {
+  const audience = `${options.host}${options.path === '/' ? '' : options.path}`;
+  const issuer = `${audience}/api`;
+  return { issuer, audience };
+}
 
+// ---------- JWT helpers ----------
 /**
- * The function `getPayloadJWT` extracts and verifies a JWT payload from a request using a bearer
- * token.
- * @param req - The `req` parameter is typically used in web development to represent the HTTP request
- * object. It contains information about the incoming request, such as headers, parameters, and body
- * data. In this context, it seems like the `getPayloadJWT` function is designed to extract and verify
- * a JWT token from
- * @returns {Object} The JWT payload from a request using a bearer
+ * Signs a JWT payload.
+ * @param {object} payload The payload to sign.
+ * @param {object} [options={}] Additional JWT sign options.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @param {number} expireMinutes The token expiration in minutes.
+ * @returns {string} The signed JWT.
+ * @throws {Error} If JWT key is not configured.
  * @memberof Auth
  */
-const getPayloadJWT = (req) => verifyJWT(getBearerToken(req));
+function jwtSign(payload, options = { host: '', path: '' }, expireMinutes = process.env.ACCESS_EXPIRE_MINUTES) {
+  const { issuer, audience } = jwtIssuerAudienceFactory(options);
+  const signOptions = {
+    algorithm: config.jwtAlgorithm,
+    expiresIn: `${expireMinutes}m`,
+    issuer,
+    audience,
+  };
+
+  if (!payload.jwtid) signOptions.jwtid = generateRandomHex();
+
+  if (!process.env.JWT_SECRET) throw new Error('JWT key not configured');
+
+  logger.info('JWT signed', { payload, signOptions, expireMinutes });
+
+  return jwt.sign(payload, process.env.JWT_SECRET, signOptions);
+}
 
 /**
- * The authMiddleware function checks and verifies the authorization token in the request headers
- * before allowing access to protected routes.
- * @param req - The `req` parameter in the `authMiddleware` function stands for the request object. It
- * contains information about the HTTP request made to the server, including headers, body, parameters,
- * and more. In this context, the function is extracting the authorization token from the request
- * headers to authenticate the user.
- * @param res - The `res` parameter in the `authMiddleware` function is the response object that
- * represents the HTTP response that an Express.js server sends when it receives an HTTP request. It is
- * used to send a response back to the client with status codes, headers, and data.
- * @param next - The `next` parameter in the `authMiddleware` function is a callback function that is
- * used to pass control to the next middleware function in the stack. When called, it invokes the next
- * middleware function in the chain. This is a common pattern in Express.js middleware functions to
- * move to the next middleware
- * @returns {Object} The `req.auth` included JWT payload in request authorization
+ * Verifies a JWT.
+ * @param {string} token The JWT to verify.
+ * @param {object} [options={}] Additional JWT verify options.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @returns {object} The decoded payload.
+ * @throws {jwt.JsonWebTokenError} If the token is invalid or expired.
  * @memberof Auth
  */
-const authMiddleware = (req, res, next) => {
+function jwtVerify(token, options = { host: '', path: '' }) {
   try {
-    const token = getBearerToken(req);
-    if (token) {
-      const payload = verifyJWT(token);
-      req.auth = payload;
-      return next();
-    } else
-      return res.status(401).json({
-        status: 'error',
-        message: 'unauthorized: invalid token',
-      });
-  } catch (error) {
-    logger.error(error, error.stack);
-    return res.status(400).json({
-      status: 'error',
-      message: error.message,
-    });
+    const { issuer, audience } = jwtIssuerAudienceFactory(options);
+    const verifyOptions = {
+      algorithms: [config.jwtAlgorithm],
+      issuer,
+      audience,
+    };
+    return jwt.verify(token, process.env.JWT_SECRET, verifyOptions);
+  } catch (err) {
+    throw err;
   }
+}
+
+// ---------- Request helpers ----------
+/**
+ * Extracts the Bearer token from the request headers.
+ * @param {import('express').Request} req The Express request object.
+ * @returns {string} The token, or an empty string if not found.
+ * @memberof Auth
+ */
+const getBearerToken = (req) => {
+  const header = String(req.headers['authorization'] || req.headers['Authorization'] || '');
+  if (header.startsWith('Bearer ')) return header.slice(7).trim();
+  return '';
 };
 
+// ---------- Middleware ----------
 /**
- * The `adminGuard` function checks if the user has admin role permission and returns an error message
- * if not.
- * @param req - The `req` parameter typically represents the HTTP request object in Node.js. It
- * contains information about the incoming request such as the request headers, parameters, body, and
- * more. In the context of your `adminGuard` function, `req` is the request object that is being passed
- * to the middleware
- * @param res - The `res` parameter in the `adminGuard` function is the response object in Express.js.
- * It is used to send a response back to the client making the HTTP request.
- * @param next - The `next` parameter in the `adminGuard` function is a callback function that is used
- * to pass control to the next middleware function in the stack. When called, it executes the next
- * middleware function. If there are no more middleware functions in the stack, it will proceed to the
- * route handler.
- * @returns The `adminGuard` function is returning either a 403 status with an error message if the
- * user role is not 'admin', or it is calling the `next()` function to proceed to the next middleware
- * if the user role is 'admin'. If an error occurs during the process, it will log the error and return
- * a 400 status with the error message.
+ * Creates a middleware to authenticate requests using a JWT Bearer token.
+ * @param {object} options The options object.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @returns {function} The middleware function.
+ * @memberof Auth
+ */
+const authMiddlewareFactory = (options = { host: '', path: '' }) => {
+  /**
+   * Express middleware to authenticate requests using a JWT Bearer token.
+   * @param {import('express').Request} req The Express request object.
+   * @param {import('express').Response} res The Express response object.
+   * @param {import('express').NextFunction} next The next middleware function.
+   * @memberof Auth
+   */
+  const authMiddleware = async (req, res, next) => {
+    try {
+      const token = getBearerToken(req);
+      if (!token) return res.status(401).json({ status: 'error', message: 'unauthorized: token missing' });
+
+      const payload = jwtVerify(token, options);
+
+      // Validate IP and User-Agent to mitigate token theft
+      if (payload.ip && payload.ip !== req.ip) {
+        logger.warn(`IP mismatch for ${payload._id}: jwt(${payload.ip}) !== req(${req.ip})`);
+        return res.status(401).json({ status: 'error', message: 'unauthorized: ip mismatch' });
+      }
+
+      if (payload.userAgent && payload.userAgent !== req.headers['user-agent']) {
+        logger.warn(`UA mismatch for ${payload._id}`);
+        return res.status(401).json({ status: 'error', message: 'unauthorized: user-agent mismatch' });
+      }
+
+      // Non-guest verify session exists
+      if (payload.jwtid && payload.role !== 'guest') {
+        const User = DataBaseProvider.instance[`${payload.host}${payload.path}`].mongoose.models.User;
+        const user = await User.findOne({ _id: payload._id, 'activeSessions._id': payload.jwtid }).lean();
+
+        if (!user) {
+          return res.status(401).json({ status: 'error', message: 'unauthorized: invalid session' });
+        }
+        const session = user.activeSessions.find((s) => s._id.toString() === payload.jwtid);
+
+        if (!session) {
+          return res.status(401).json({ status: 'error', message: 'unauthorized: invalid session' });
+        }
+
+        // check session ip
+        if (session.ip !== req.ip) {
+          logger.warn(`IP mismatch for ${payload._id}: jwt(${session.ip}) !== req(${req.ip})`);
+          return res.status(401).json({ status: 'error', message: 'unauthorized: ip mismatch' });
+        }
+
+        // check session userAgent
+        if (session.userAgent !== req.headers['user-agent']) {
+          logger.warn(`UA mismatch for ${payload._id}`);
+          return res.status(401).json({ status: 'error', message: 'unauthorized: user-agent mismatch' });
+        }
+
+        // compare payload host and path with session host and path
+        if (payload.host !== session.host || payload.path !== session.path) {
+          logger.warn(`Host or path mismatch for ${payload._id}`);
+          return res.status(401).json({ status: 'error', message: 'unauthorized: host or path mismatch' });
+        }
+
+        // check session expiresAt
+        const isRefreshTokenReq = req.method === 'GET' && req.params.id === 'auth';
+
+        if (!isRefreshTokenReq && session.expiresAt < new Date()) {
+          return res.status(401).json({ status: 'error', message: 'unauthorized: session expired' });
+        }
+      }
+
+      req.auth = { user: payload };
+      return next();
+    } catch (err) {
+      logger.warn('authMiddleware error', err && err.message);
+      return res.status(401).json({ status: 'error', message: 'unauthorized' });
+    }
+  };
+  return authMiddleware;
+};
+
+/**
+ * Express middleware to guard routes for admin users.
+ * @param {import('express').Request} req The Express request object.
+ * @param {import('express').Response} res The Express response object.
+ * @param {import('express').NextFunction} next The next middleware function.
  * @memberof Auth
  */
 const adminGuard = (req, res, next) => {
   try {
-    if (!commonAdminGuard(req.auth.user.role))
+    if (!req.auth || !commonAdminGuard(req.auth.user.role))
       return res.status(403).json({ status: 'error', message: 'Insufficient permission' });
     return next();
-  } catch (error) {
-    logger.error(error, error.stack);
-    return res.status(400).json({
-      status: 'error',
-      message: error.message,
-    });
+  } catch (err) {
+    logger.error(err);
+    return res.status(400).json({ status: 'error', message: 'bad request' });
   }
 };
-
 /**
- * The function `moderatorGuard` checks if the user's role is at least a moderator and handles errors
- * accordingly.
- * @param req - The `req` parameter in the `moderatorGuard` function typically represents the HTTP
- * request object, which contains information about the incoming request such as headers, parameters,
- * body, etc. It is commonly used to access data sent from the client to the server.
- * @param res - The `res` parameter in the `moderatorGuard` function is the response object in
- * Express.js. It is used to send a response back to the client making the HTTP request.
- * @param next - The `next` parameter in the `moderatorGuard` function is a callback function that is
- * used to pass control to the next middleware function in the stack. When called, it will execute the
- * next middleware function. In the context of Express.js middleware, `next` is typically called to
- * move to
- * @returns In the `moderatorGuard` function, if the user's role is not a moderator or higher, a 403
- * status with an error message "Insufficient permission" is returned. If there is an error during the
- * process, a 400 status with the error message is returned. If everything is successful, the `next()`
- * function is called to proceed to the next middleware in the chain.
+ * Express middleware to guard routes for moderator or admin users.
+ * @param {import('express').Request} req The Express request object.
+ * @param {import('express').Response} res The Express response object.
+ * @param {import('express').NextFunction} next The next middleware function.
  * @memberof Auth
  */
 const moderatorGuard = (req, res, next) => {
   try {
-    if (!commonModeratorGuard(req.auth.user.role))
+    if (!req.auth || !commonModeratorGuard(req.auth.user.role))
       return res.status(403).json({ status: 'error', message: 'Insufficient permission' });
     return next();
-  } catch (error) {
-    logger.error(error, error.stack);
-    return res.status(400).json({
-      status: 'error',
-      message: error.message,
-    });
+  } catch (err) {
+    logger.error(err);
+    return res.status(400).json({ status: 'error', message: 'bad request' });
   }
 };
 
-const validatePasswordMiddleware = (req, password) => {
-  let errors = [];
-  if (req.body && 'password' in req.body) errors = validatePassword(req.body.password);
-  if (errors.length > 0)
-    return {
-      status: 'error',
-      message:
-        'Password, ' + errors.map((e, i) => (i > 0 ? ', ' : '') + (e[req.lang] ? e[req.lang] : e['en'])).join(''),
-    };
-  else
-    return {
-      status: 'success',
-    };
+// ---------- Password validation middleware (server-side) ----------
+/**
+ * Validates the password from the request body.
+ * @param {import('express').Request} req The Express request object.
+ * @returns {{status: 'success'}|{status: 'error', message: string}} Validation result.
+ * @memberof Auth
+ */
+const validatePasswordMiddleware = (req) => {
+  const errors = req.body && 'password' in req.body ? validatePassword(req.body.password) : [];
+  if (errors.length) {
+    return { status: 'error', message: 'Password: ' + errors.map((e) => e[req.lang] || e.en || e).join(', ') };
+  }
+  return { status: 'success' };
 };
 
+// ---------- Session & Refresh token management ----------
+/**
+ * Create session and set refresh cookie. Rotating and hashed stored token.
+ * @param {object} user The user object.
+ * @param {import('mongoose').Model} User The Mongoose User model.
+ * @param {import('express').Request} req The Express request object.
+ * @param {import('express').Response} res The Express response object.
+ * @param {object} options Additional options.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @returns {Promise<{jwtid: string}>} The session ID.
+ * @memberof Auth
+ */
+async function createSessionAndUserToken(user, User, req, res, options = { host: '', path: '' }) {
+  const refreshToken = hashToken(generateRandomHex());
+  const now = Date.now();
+  const expiresAt = new Date(now + parseInt(process.env.REFRESH_EXPIRE_MINUTES) * 60 * 1000);
+
+  const newSession = {
+    tokenHash: refreshToken,
+    ip: req.ip,
+    userAgent: req.headers['user-agent'],
+    host: options.host,
+    path: options.path,
+    createdAt: new Date(now),
+    expiresAt,
+  };
+
+  // push session
+  const updatedUser = await User.findByIdAndUpdate(user._id, { $push: { activeSessions: newSession } }, { new: true });
+  const session = updatedUser.activeSessions[updatedUser.activeSessions.length - 1];
+  const jwtid = session._id.toString();
+
+  // Secure cookie settings
+  res.cookie('refreshToken', refreshToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'Lax',
+    maxAge: parseInt(process.env.REFRESH_EXPIRE_MINUTES) * 60 * 1000,
+    path: '/',
+  });
+
+  return { jwtid };
+}
+
+/**
+ * Create user and immediate session + access token
+ * @param {import('express').Request} req The Express request object.
+ * @param {import('express').Response} res The Express response object.
+ * @param {import('mongoose').Model} User The Mongoose User model.
+ * @param {import('mongoose').Model} File The Mongoose File model.
+ * @param {object} [options={}] Additional options.
+ * @param {Function} options.getDefaultProfileImageId Function to get the default profile image ID.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @returns {Promise<{token: string, user: object}>} The access token and user object.
+ * @throws {Error} If password validation fails.
+ * @memberof Auth
+ */
+async function createUserAndSession(req, res, User, File, options = { host: '', path: '' }) {
+  const pwdCheck = validatePasswordMiddleware(req);
+  if (pwdCheck.status === 'error') throw new Error(pwdCheck.message);
+
+  req.body.password = await hashPassword(req.body.password);
+  req.body.role = req.body.role === 'guest' ? 'guest' : 'user';
+  req.body.profileImageId = await options.getDefaultProfileImageId(File);
+
+  const saved = await new User(req.body).save();
+  const user = await User.findOne({ _id: saved._id }).select(UserDto.select.get());
+
+  const { jwtid } = await createSessionAndUserToken(user, User, req, res, options);
+  const token = jwtSign(
+    UserDto.auth.payload(user, jwtid, req.ip, req.headers['user-agent'], options.host, options.path),
+    options,
+  );
+  return { token, user };
+}
+
+/**
+ * Refresh session and rotate refresh token.
+ * Detect token reuse: if a refresh token is presented but not found, consider
+ * it a possible theft and revoke all sessions for that user.
+ * @param {import('express').Request} req The Express request object.
+ * @param {import('express').Response} res The Express response object.
+ * @param {import('mongoose').Model} User The Mongoose User model.
+ * @param {object} options Additional options.
+ * @param {string} options.host The host name.
+ * @param {string} options.path The path name.
+ * @returns {Promise<{token: string}>} The new access token.
+ * @throws {Error} If the refresh token is missing, invalid, or expired.
+ * @memberof Auth
+ */
+async function refreshSessionAndToken(req, res, User, options = { host: '', path: '' }) {
+  const currentRefreshToken = req.cookies.refreshToken;
+  if (!currentRefreshToken) throw new Error('Refresh token missing');
+
+  // Find user owning that token
+  const user = await User.findOne({ 'activeSessions.tokenHash': currentRefreshToken });
+
+  if (!user) {
+    // Possible token reuse: look up user by some other signals? If not possible, log and throw.
+    logger.warn('Refresh token reuse or invalid token detected');
+    // Optional: revoke by clearing cookie and returning unauthorized
+    res.clearCookie('refreshToken', { path: '/' });
+    throw new Error('Invalid refresh token');
+  }
+
+  // Locate session
+  const session = user.activeSessions.find((s) => s.tokenHash === currentRefreshToken);
+  if (!session) {
+    // Shouldn't happen, but safe-guard
+    res.clearCookie('refreshToken', { path: '/' });
+    throw new Error('Session not found');
+  }
+
+  // Check expiry
+  if (session.expiresAt && session.expiresAt < new Date()) {
+    // remove expired session
+    user.activeSessions.id(session._id).remove();
+    await user.save({ validateBeforeSave: false });
+    res.clearCookie('refreshToken', { path: '/' });
+    throw new Error('Refresh token expired');
+  }
+
+  // Rotate: generate new token, update stored hash and metadata
+  const refreshToken = hashToken(generateRandomHex());
+  session.tokenHash = refreshToken;
+  session.expiresAt = new Date(Date.now() + parseInt(process.env.REFRESH_EXPIRE_MINUTES) * 60 * 1000);
+  session.ip = req.ip;
+  session.userAgent = req.headers['user-agent'];
+  await user.save({ validateBeforeSave: false });
+
+  logger.warn('Refreshed session for user ' + user.email);
+
+  res.cookie('refreshToken', refreshToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'Lax',
+    maxAge: parseInt(process.env.REFRESH_EXPIRE_MINUTES) * 60 * 1000,
+    path: '/',
+  });
+
+  return jwtSign(
+    UserDto.auth.payload(user, session._id.toString(), req.ip, req.headers['user-agent'], options.host, options.path),
+    options,
+  );
+}
+
+// ---------- Security middleware composition ----------
+/**
+ * Applies a set of security-related middleware to an Express app.
+ * @param {import('express').Application} app The Express application.
+ * @param {object} [opts={}] Options for security middleware.
+ * @param {string[]} opts.origin Allowed origins for CORS.
+ * @param {object} opts.rate Rate limiting options for `express-rate-limit`.
+ * @param {object} opts.slowdown Slow down options for `express-slow-down`.
+ * @param {object} opts.cookie Cookie options.
+ * @param {string[]} opts.frameAncestors Allowed frame ancestors for CSP.
+ * @memberof Auth
+ */
+function applySecurity(app, opts = {}) {
+  const {
+    origin,
+    rate = { windowMs: 15 * 60 * 1000, max: 500 },
+    slowdown = { windowMs: 15 * 60 * 1000, delayAfter: 50, delayMs: () => 500 },
+    cookie = { secure: process.env.NODE_ENV === 'production', sameSite: 'Strict' },
+    frameAncestors = ["'self'"],
+  } = opts;
+
+  app.disable('x-powered-by');
+
+  // Generate nonce per request and attach to res.locals for templates
+  app.use((req, res, next) => {
+    res.locals.nonce = crypto.randomBytes(16).toString('base64');
+    next();
+  });
+
+  // Basic header hardening with Helmet
+  app.use(
+    helmet({
+      // We'll customize CSP below because many apps need tailored directives
+      crossOriginEmbedderPolicy: true,
+      crossOriginOpenerPolicy: { policy: 'same-origin' },
+      crossOriginResourcePolicy: { policy: 'same-origin' },
+      originAgentCluster: false,
+      // Permissions-Policy (formerly Feature-Policy) — limit powerful features
+      permissionsPolicy: {
+        // example: disable geolocation, camera, microphone, payment
+        features: {
+          fullscreen: ["'self'"],
+          geolocation: [],
+          camera: [],
+          microphone: [],
+          payment: [],
+        },
+      },
+    }),
+  );
+
+  // Strict HSTS (only enable in production over TLS)
+  // maxAge in seconds (e.g. 31536000 = 1 year). Use includeSubDomains and preload carefully.
+  if (process.env.NODE_ENV === 'production') {
+    app.use(
+      helmet.hsts({
+        maxAge: 31536000,
+        includeSubDomains: true,
+        preload: true,
+      }),
+    );
+  }
+
+  // Other helpful Helmet policies
+  app.use(helmet.noSniff()); // X-Content-Type-Options: nosniff
+  app.use(helmet.frameguard({ action: 'deny' })); // X-Frame-Options: DENY
+  app.use(helmet.referrerPolicy({ policy: 'no-referrer-when-downgrade' }));
+
+  // Content-Security-Policy: include nonce from res.locals
+  // Note: We avoid 'unsafe-inline' on script/style. Use nonces or hashes.
+  const httpDirective = process.env.NODE_ENV === 'production' ? 'https:' : 'http:';
+  app.use(
+    helmet.contentSecurityPolicy({
+      useDefaults: true,
+      directives: {
+        defaultSrc: ["'self'"],
+        baseUri: ["'self'"],
+        blockAllMixedContent: [],
+        fontSrc: ["'self'", httpDirective, 'data:'],
+        frameAncestors: frameAncestors,
+        imgSrc: ["'self'", 'data:', httpDirective],
+        objectSrc: ["'none'"],
+        // script-src and script-src-elem include dynamic nonce
+        scriptSrc: ["'self'", (req, res) => `'nonce-${res.locals.nonce}'`],
+        scriptSrcElem: ["'self'", (req, res) => `'nonce-${res.locals.nonce}'`],
+        // style-src: avoid 'unsafe-inline' when possible; if you must inline styles,
+        // use a nonce for them too (or hash).
+        styleSrc: ["'self'", httpDirective, (req, res) => `'nonce-${res.locals.nonce}'`],
+        // deny plugins
+        objectSrc: ["'none'"],
+      },
+    }),
+  );
+
+  // CORS - be explicit. In production, pass allowed origin(s) as opts.origin
+  app.use(
+    cors({
+      origin: origin || false,
+      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      credentials: true,
+      allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'withcredentials', 'credentials'],
+      maxAge: 600,
+    }),
+  );
+
+  // Rate limiting + slow down
+  const limiter = rateLimit({
+    windowMs: rate.windowMs,
+    max: rate.max,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too many requests, please try again later.' },
+  });
+  app.use(limiter);
+
+  const speedLimiter = slowDown({
+    windowMs: slowdown.windowMs,
+    delayAfter: slowdown.delayAfter,
+    delayMs: () => slowdown.delayMs,
+  });
+  app.use(speedLimiter);
+
+  // Cookie parsing
+  app.use(cookieParser(process.env.JWT_SECRET));
+}
+
 export {
-  authMiddleware,
+  authMiddlewareFactory,
   hashPassword,
   verifyPassword,
-  hashJWT,
+  hashToken,
+  jwtSign,
+  jwtVerify,
+  jwtSign as hashJWT,
+  jwtVerify as verifyJWT,
   adminGuard,
   moderatorGuard,
-  verifyJWT,
   validatePasswordMiddleware,
   getBearerToken,
-  getPayloadJWT,
+  createSessionAndUserToken,
+  createUserAndSession,
+  refreshSessionAndToken,
+  applySecurity,
 };