underpost 2.8.882 → 2.8.884

package/src/runtime/lampp/Lampp.js

@@ -1,123 +1,252 @@
+/**
+ * Exported singleton instance of the LamppService class.
+ * This object is used to interact with the Lampp configuration and service.
+ * @module src/runtime/lampp/Lampp.js
+ * @namespace LamppService
+ */
+
 import fs from 'fs-extra';
 import { getRootDirectory, shellCd, shellExec } from '../../server/process.js';
 import { loggerFactory } from '../../server/logger.js';
 
 const logger = loggerFactory(import.meta);
 
-const Lampp = {
-  ports: [],
-  initService: async function (options = { daemon: false }) {
+/**
+ * @class LamppService
+ * @description Provides utilities for managing the XAMPP (Lampp) service on Linux,
+ * including initialization, router configuration, and virtual host creation.
+ * It manages the server's configuration files and controls the service process.
+ * @memberof LamppService
+ */
+class LamppService {
+  /**
+   * @private
+   * @type {string | undefined}
+   * @description Stores the accumulated Apache virtual host configuration (router definition).
+   * @memberof LamppService
+   */
+  router;
+
+  /**
+   * @public
+   * @type {number[]}
+   * @description A list of ports currently configured and listened to by the Lampp service.
+   * @memberof LamppService
+   */
+  ports;
+
+  /**
+   * Creates an instance of LamppService.
+   * Initializes the router configuration and ports list.
+   * @method constructor
+   * @memberof LamppService
+   */
+  constructor() {
+    this.router = undefined;
+    this.ports = [];
+  }
+
+  /**
+   * Checks if the XAMPP (Lampp) service appears to be installed based on the presence of its main configuration file.
+   *
+   * @method enabled
+   * @memberof LamppService
+   * @returns {boolean} True if the configuration file exists, indicating Lampp is likely installed.
+   * @throws {Error} If the configuration file does not exist.
+   * @memberof LamppService
+   */
+  enabled() {
+    return fs.existsSync('/opt/lampp/etc/httpd.conf');
+  }
+
+  /**
+   * Initializes or restarts the Lampp Apache service.
+   * This method configures virtual hosts, disables default ports (80/443) in the main config
+   * to avoid conflicts, and starts or stops the service using shell commands.
+   *
+   * @method initService
+   * @param {object} [options={daemon: false}] - Options for service initialization.
+   * @param {boolean} [options.daemon=false] - Flag to indicate if the service should be run as a daemon (currently unused in logic).
+   * @returns {Promise<void>}
+   * @memberof LamppService
+   */
+  async initService(options = { daemon: false }) {
     let cmd;
-    // linux
-    // /opt/lampp/apache2/conf/httpd.conf
+
+    // 1. Write the current virtual host router configuration
     fs.writeFileSync(`/opt/lampp/etc/extra/httpd-vhosts.conf`, this.router || '', 'utf8');
+
+    // 2. Ensure the vhosts file is included in the main httpd.conf
+    const httpdConfPath = `/opt/lampp/etc/httpd.conf`;
     fs.writeFileSync(
-      `/opt/lampp/etc/httpd.conf`,
+      httpdConfPath,
       fs
-        .readFileSync(`/opt/lampp/etc/httpd.conf`, 'utf8')
+        .readFileSync(httpdConfPath, 'utf8')
         .replace(`#Include etc/extra/httpd-vhosts.conf`, `Include etc/extra/httpd-vhosts.conf`),
       'utf8',
     );
 
+    // 3. Stop the service before making port changes
     cmd = `sudo /opt/lampp/lampp stop`;
-    if (!fs.readFileSync(`/opt/lampp/etc/httpd.conf`, 'utf8').match(`# Listen 80`))
+    shellExec(cmd);
+
+    // 4. Comment out default port Listen directives (80 and 443) to prevent conflicts
+    // Modify httpd.conf (port 80)
+    if (!fs.readFileSync(httpdConfPath, 'utf8').match(/# Listen 80/))
       fs.writeFileSync(
-        `/opt/lampp/etc/httpd.conf`,
-        fs.readFileSync(`/opt/lampp/etc/httpd.conf`, 'utf8').replace(`Listen 80`, `# Listen 80`),
+        httpdConfPath,
+        fs.readFileSync(httpdConfPath, 'utf8').replace(`Listen 80`, `# Listen 80`),
         'utf8',
       );
-    if (!fs.readFileSync(`/opt/lampp/etc/extra/httpd-ssl.conf`, 'utf8').match(`# Listen 443`))
+
+    // Modify httpd-ssl.conf (port 443)
+    const httpdSslConfPath = `/opt/lampp/etc/extra/httpd-ssl.conf`;
+    if (fs.existsSync(httpdSslConfPath) && !fs.readFileSync(httpdSslConfPath, 'utf8').match(/# Listen 443/))
       fs.writeFileSync(
-        `/opt/lampp/etc/extra/httpd-ssl.conf`,
-        fs.readFileSync(`/opt/lampp/etc/extra/httpd-ssl.conf`, 'utf8').replace(`Listen 443`, `# Listen 443`),
+        httpdSslConfPath,
+        fs.readFileSync(httpdSslConfPath, 'utf8').replace(`Listen 443`, `# Listen 443`),
         'utf8',
       );
-    if (!fs.readFileSync(`/opt/lampp/lampp`, 'utf8').match(`testport 443 && false`))
+
+    // 5. Modify the lampp startup script to bypass port checking for 80 and 443
+    const lamppScriptPath = `/opt/lampp/lampp`;
+    if (!fs.readFileSync(lamppScriptPath, 'utf8').match(/testport 443 && false/))
       fs.writeFileSync(
-        `/opt/lampp/lampp`,
-        fs.readFileSync(`/opt/lampp/lampp`, 'utf8').replace(`testport 443`, `testport 443 && false`),
+        lamppScriptPath,
+        fs.readFileSync(lamppScriptPath, 'utf8').replace(`testport 443`, `testport 443 && false`),
         'utf8',
       );
-    if (!fs.readFileSync(`/opt/lampp/lampp`, 'utf8').match(`testport 80 && false`))
+    if (!fs.readFileSync(lamppScriptPath, 'utf8').match(/testport 80 && false/))
       fs.writeFileSync(
-        `/opt/lampp/lampp`,
-        fs.readFileSync(`/opt/lampp/lampp`, 'utf8').replace(`testport 80`, `testport 80 && false`),
+        lamppScriptPath,
+        fs.readFileSync(lamppScriptPath, 'utf8').replace(`testport 80`, `testport 80 && false`),
         'utf8',
       );
 
-    shellExec(cmd);
+    // 6. Start the service
     cmd = `sudo /opt/lampp/lampp start`;
     if (this.router) fs.writeFileSync(`./tmp/lampp-router.conf`, this.router, 'utf-8');
     shellExec(cmd);
-  },
-  enabled: () => fs.existsSync(`/opt/lampp/etc/httpd.conf`),
-  appendRouter: function (render) {
+  }
+
+  /**
+   * Appends new Apache VirtualHost configuration content to the internal router string.
+   * If a router config file exists from a previous run, it loads it first.
+   *
+   * @method appendRouter
+   * @param {string} render - The new VirtualHost configuration string to append.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof LamppService
+   */
+  appendRouter(render) {
     if (!this.router) {
-      if (fs.existsSync(`./tmp/lampp-router.conf`))
-        return (this.router = fs.readFileSync(`./tmp/lampp-router.conf`, 'utf-8')) + render;
+      if (fs.existsSync(`./tmp/lampp-router.conf`)) {
+        this.router = fs.readFileSync(`./tmp/lampp-router.conf`, 'utf-8');
+        return this.router + render;
+      }
       return (this.router = render);
     }
     return (this.router += render);
-  },
-  removeRouter: function () {
+  }
+
+  /**
+   * Resets the internal router configuration and removes the temporary configuration file.
+   *
+   * @memberof LamppService
+   * @returns {void}
+   */
+  removeRouter() {
     this.router = undefined;
     if (fs.existsSync(`./tmp/lampp-router.conf`)) fs.rmSync(`./tmp/lampp-router.conf`);
-  },
-  install: async function () {
-    switch (process.platform) {
-      case 'linux':
-        {
-          if (!fs.existsSync(`./engine-private/setup`)) fs.mkdirSync(`./engine-private/setup`, { recursive: true });
-
-          shellCd(`./engine-private/setup`);
-
-          if (!process.argv.includes(`server`)) {
-            shellExec(
-              `curl -Lo xampp-linux-installer.run https://sourceforge.net/projects/xampp/files/XAMPP%20Linux/7.4.30/xampp-linux-x64-7.4.30-1-installer.run?from_af=true`,
-            );
-            shellExec(`sudo chmod +x xampp-linux-installer.run`);
-            shellExec(
-              `sudo ./xampp-linux-installer.run --mode unattended && \\` +
-                `ln -sf /opt/lampp/lampp /usr/bin/lampp && \\` +
-                `sed -i.bak s'/Require local/Require all granted/g' /opt/lampp/etc/extra/httpd-xampp.conf && \\` +
-                `sed -i.bak s'/display_errors=Off/display_errors=On/g' /opt/lampp/etc/php.ini && \\` +
-                `mkdir /opt/lampp/apache2/conf.d && \\` +
-                `echo "IncludeOptional /opt/lampp/apache2/conf.d/*.conf" >> /opt/lampp/etc/httpd.conf && \\` +
-                `mkdir /www && \\` +
-                `ln -s /www /opt/lampp/htdocs`,
-            );
-          }
-
-          if (fs.existsSync(`/opt/lampp/logs/access_log`))
-            fs.copySync(`/opt/lampp/logs/access_log`, `/opt/lampp/logs/access.log`);
-          if (fs.existsSync(`/opt/lampp/logs/error_log`))
-            fs.copySync(`/opt/lampp/logs/error_log`, `/opt/lampp/logs/error.log`);
-          if (fs.existsSync(`/opt/lampp/logs/php_error_log`))
-            fs.copySync(`/opt/lampp/logs/php_error_log`, `/opt/lampp/logs/php_error.log`);
-          if (fs.existsSync(`/opt/lampp/logs/ssl_request_log`))
-            fs.copySync(`/opt/lampp/logs/ssl_request_log`, `/opt/lampp/logs/ssl_request.log`);
-
-          await Lampp.initService({ daemon: true });
-        }
-
-        break;
-
-      default:
-        break;
+  }
+
+  /**
+   * Installs and configures the Lampp service on Linux.
+   * This includes downloading the installer, running it, and setting up initial configurations.
+   * Only runs on the 'linux' platform.
+   *
+   * @method install
+   * @returns {Promise<void>}
+   * @memberof LamppService
+   */
+  async install() {
+    if (process.platform === 'linux') {
+      if (!fs.existsSync(`./engine-private/setup`)) fs.mkdirSync(`./engine-private/setup`, { recursive: true });
+
+      shellCd(`./engine-private/setup`);
+
+      if (!process.argv.includes(`server`)) {
+        // Download and run the XAMPP installer
+        shellExec(
+          `curl -Lo xampp-linux-installer.run https://sourceforge.net/projects/xampp/files/XAMPP%20Linux/7.4.30/xampp-linux-x64-7.4.30-1-installer.run?from_af=true`,
+        );
+        shellExec(`sudo chmod +x xampp-linux-installer.run`);
+        shellExec(
+          `sudo ./xampp-linux-installer.run --mode unattended && \\` +
+            // Create symlink for easier access
+            `ln -sf /opt/lampp/lampp /usr/bin/lampp && \\` +
+            // Allow all access to xampp config (security measure override)
+            `sed -i.bak s'/Require local/Require all granted/g' /opt/lampp/etc/extra/httpd-xampp.conf && \\` +
+            // Enable display errors in PHP
+            `sed -i.bak s'/display_errors=Off/display_errors=On/g' /opt/lampp/etc/php.ini && \\` +
+            // Allow including custom Apache configuration files
+            `mkdir /opt/lampp/apache2/conf.d && \\` +
+            `echo "IncludeOptional /opt/lampp/apache2/conf.d/*.conf" >> /opt/lampp/etc/httpd.conf && \\` +
+            // Create /www directory and symlink it to htdocs
+            `mkdir /www && \\` +
+            `ln -s /www /opt/lampp/htdocs`,
+        );
+      }
+
+      // Copy log files to standard names for easier consumption
+      if (fs.existsSync(`/opt/lampp/logs/access_log`))
+        fs.copySync(`/opt/lampp/logs/access_log`, `/opt/lampp/logs/access.log`);
+      if (fs.existsSync(`/opt/lampp/logs/error_log`))
+        fs.copySync(`/opt/lampp/logs/error_log`, `/opt/lampp/logs/error.log`);
+      if (fs.existsSync(`/opt/lampp/logs/php_error_log`))
+        fs.copySync(`/opt/lampp/logs/php_error_log`, `/opt/lampp/logs/php_error.log`);
+      if (fs.existsSync(`/opt/lampp/logs/ssl_request_log`))
+        fs.copySync(`/opt/lampp/logs/ssl_request_log`, `/opt/lampp/logs/ssl_request.log`);
+
+      // Initialize the service after installation
+      await this.initService({ daemon: true });
     }
-  },
-  createApp: async ({ port, host, path, directory, rootHostPath, redirect, redirectTarget, resetRouter }) => {
-    if (!Lampp.enabled()) return { disabled: true };
-    if (!Lampp.ports.includes(port)) Lampp.ports.push(port);
-    if (resetRouter) Lampp.removeRouter();
-    Lampp.appendRouter(`
+  }
+
+  /**
+   * Creates and appends a new Apache VirtualHost entry to the router configuration for a web application.
+   * The router is then applied by calling {@link LamppService#initService}.
+   *
+   * @method createApp
+   * @param {object} options - Configuration options for the new web application.
+   * @param {number} options.port - The port the VirtualHost should listen on.
+   * @param {string} options.host - The ServerName/host for the VirtualHost.
+   * @param {string} options.path - The base path for error documents (e.g., '/app').
+   * @param {string} [options.directory] - Optional absolute path to the document root.
+   * @param {string} [options.rootHostPath] - Relative path from the root directory to the document root, used if `directory` is not provided.
+   * @param {boolean} [options.redirect] - If true, enables RewriteEngine for redirection.
+   * @param {string} [options.redirectTarget] - The target URL for redirection.
+   * @param {boolean} [options.resetRouter] - If true, clears the existing router configuration before appending the new one.
+   * @returns {{disabled: boolean}} An object indicating if the service is disabled.
+   * @memberof LamppService
+   */
+  createApp({ port, host, path, directory, rootHostPath, redirect, redirectTarget, resetRouter }) {
+    if (!this.enabled()) return { disabled: true };
+
+    if (!this.ports.includes(port)) this.ports.push(port);
+    if (resetRouter) this.removeRouter();
+
+    const documentRoot = directory ? directory : `${getRootDirectory()}${rootHostPath}`;
+
+    // Append the new VirtualHost configuration
+    this.appendRouter(`
 Listen ${port}
 
 <VirtualHost *:${port}>
-  DocumentRoot "${directory ? directory : `${getRootDirectory()}${rootHostPath}`}"
+  DocumentRoot "${documentRoot}"
   ServerName ${host}:${port}
 
-  <Directory "${directory ? directory : `${getRootDirectory()}${rootHostPath}`}">
+  <Directory "${documentRoot}">
     Options Indexes FollowSymLinks MultiViews
     AllowOverride All
     Require all granted
@@ -128,12 +257,14 @@ Listen ${port}
       ? `
     RewriteEngine on
 
+    # Exclude the ACME challenge path for certificate renewals
     RewriteCond %{REQUEST_URI} !^/.well-known/acme-challenge
     RewriteRule ^(.*)$ ${redirectTarget}%{REQUEST_URI} [R=302,L]
   `
       : ''
   }
 
+  # Custom Error Documents
   ErrorDocument 400 ${path === '/' ? '' : path}/400.html
   ErrorDocument 404 ${path === '/' ? '' : path}/400.html
   ErrorDocument 500 ${path === '/' ? '' : path}/500.html
@@ -144,56 +275,69 @@ Listen ${port}
 </VirtualHost>
             
 `);
-    // ERR too many redirects:
-    // Check: SELECT * FROM database.wp_options where option_name = 'siteurl' or option_name = 'home';
-    // Check: wp-config.php
-    // if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
-    //   $_SERVER['HTTPS'] = 'on';
-    // }
-    // For plugins:
-    // define( 'FS_METHOD', 'direct' );
-
-    // ErrorDocument 404 /custom_404.html
-    // ErrorDocument 500 /custom_50x.html
-    // ErrorDocument 502 /custom_50x.html
-    // ErrorDocument 503 /custom_50x.html
-    // ErrorDocument 504 /custom_50x.html
-
-    // Respond When Error Pages are Directly Requested
-
-    // <Files "custom_404.html">
-    //     <If "-z %{ENV:REDIRECT_STATUS}">
-    //         RedirectMatch 404 ^/custom_404.html$
-    //     </If>
-    // </Files>
-
-    // <Files "custom_50x.html">
-    //     <If "-z %{ENV:REDIRECT_STATUS}">
-    //         RedirectMatch 404 ^/custom_50x.html$
-    //     </If>
-    // </Files>
-
-    // Add www or https with htaccess rewrite
-
-    // Options +FollowSymLinks
-    // RewriteEngine On
-    // RewriteCond %{HTTP_HOST} ^ejemplo.com [NC]
-    // RewriteRule ^(.*)$ http://ejemplo.com/$1 [R=301,L]
-
-    // Redirect http to https with htaccess rewrite
-
-    // RewriteEngine On
-    // RewriteCond %{SERVER_PORT} 80
-    // RewriteRule ^(.*)$ https://www.ejemplo.com/$1 [R,L]
-
-    // Redirect to HTTPS with www subdomain
-
-    // RewriteEngine On
-    // RewriteCond %{HTTPS} off [OR]
-    // RewriteCond %{HTTP_HOST} ^www\. [NC]
-    // RewriteCond %{HTTP_HOST} ^(?:www\.)?(.+)$ [NC]
-    // RewriteRule ^ https://%1%{REQUEST_URI} [L,NE,R=301]
-  },
-};
+
+    return { disabled: false };
+  }
+}
+
+/**
+ * @description Exported singleton instance of the LamppService class.
+ * This object is used to interact with the Lampp configuration and service.
+ * @memberof LamppService
+ * @type {LamppService}
+ */
+const Lampp = new LamppService();
 
 export { Lampp };
+
+// -- helper info --
+
+// ERR too many redirects:
+// Check: SELECT * FROM database.wp_options where option_name = 'siteurl' or option_name = 'home';
+// Check: wp-config.php
+// if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
+//   $_SERVER['HTTPS'] = 'on';
+// }
+// For plugins:
+// define( 'FS_METHOD', 'direct' );
+
+// ErrorDocument 404 /custom_404.html
+// ErrorDocument 500 /custom_50x.html
+// ErrorDocument 502 /custom_50x.html
+// ErrorDocument 503 /custom_50x.html
+// ErrorDocument 504 /custom_50x.html
+
+// Respond When Error Pages are Directly Requested
+
+// <Files "custom_404.html">
+//     <If "-z %{ENV:REDIRECT_STATUS}">
+//         RedirectMatch 404 ^/custom_404.html$
+//     </If>
+// </Files>
+
+// <Files "custom_50x.html">
+//     <If "-z %{ENV:REDIRECT_STATUS}">
+//         RedirectMatch 404 ^/custom_50x.html$
+//     </If>
+// </Files>
+
+// Add www or https with htaccess rewrite
+
+// Options +FollowSymLinks
+// RewriteEngine On
+// RewriteCond %{HTTP_HOST} ^example.com [NC]
+// RewriteRule ^(.*)$ http://example.com/$1 [R=301,L]
+
+// Redirect http to https with htaccess rewrite
+
+// RewriteEngine On
+// RewriteCond %{SERVER_PORT} 80
+// RewriteRule ^(.*)$ https://www.example.com/$1 [R,L]
+
+// Redirect to HTTPS with www subdomain
+
+// RewriteEngine On
+// RewriteCond %{HTTPS} off [OR]
+// RewriteCond %{HTTP_HOST} ^www\. [NC]
+// RewriteCond %{HTTP_HOST} ^(?:www\.)?(.+)$ [NC]
+// RewriteRule ^ https://%1%{REQUEST_URI} [L,NE,R=301]

package/src/server/auth.js

@@ -110,16 +110,22 @@ function jwtIssuerAudienceFactory(options = { host: '', path: '' }) {
  * @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.
+ * @param {number} accessExpireMinutes The access token expiration in minutes.
+ * @param {number} refreshExpireMinutes The refresh token expiration in minutes.
  * @returns {string} The signed JWT.
  * @throws {Error} If JWT key is not configured.
  * @memberof Auth
  */
-function jwtSign(payload, options = { host: '', path: '' }, expireMinutes = process.env.ACCESS_EXPIRE_MINUTES) {
+function jwtSign(
+  payload,
+  options = { host: '', path: '' },
+  accessExpireMinutes = process.env.ACCESS_EXPIRE_MINUTES,
+  refreshExpireMinutes = process.env.REFRESH_EXPIRE_MINUTES,
+) {
   const { issuer, audience } = jwtIssuerAudienceFactory(options);
   const signOptions = {
     algorithm: config.jwtAlgorithm,
-    expiresIn: `${expireMinutes}m`,
+    expiresIn: `${accessExpireMinutes}m`,
     issuer,
     audience,
   };
@@ -128,7 +134,11 @@ function jwtSign(payload, options = { host: '', path: '' }, expireMinutes = proc
 
   if (!process.env.JWT_SECRET) throw new Error('JWT key not configured');
 
-  logger.info('JWT signed', { payload, signOptions, expireMinutes });
+  // Add refreshExpiresAt to the payload, which is the same as the token's own expiry.
+  const now = Date.now();
+  payload.refreshExpiresAt = now + refreshExpireMinutes * 60 * 1000;
+
+  logger.info('JWT signed', { payload, signOptions, accessExpireMinutes, refreshExpireMinutes });
 
   return jwt.sign(payload, process.env.JWT_SECRET, signOptions);
 }
@@ -170,6 +180,14 @@ const getBearerToken = (req) => {
   return '';
 };
 
+/**
+ * Checks if the request is a refresh token request.
+ * @param {import('express').Request} req The Express request object.
+ * @returns {boolean} True if the request is a refresh token request, false otherwise.
+ * @memberof Auth
+ */
+const isRefreshTokenReq = (req) => req.method === 'GET' && req.params.id === 'auth';
+
 // ---------- Middleware ----------
 /**
  * Creates a middleware to authenticate requests using a JWT Bearer token.
@@ -237,10 +255,7 @@ const authMiddlewareFactory = (options = { host: '', path: '' }) => {
           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()) {
+        if (!isRefreshTokenReq(req) && session.expiresAt < new Date()) {
           return res.status(401).json({ status: 'error', message: 'unauthorized: session expired' });
         }
       }
@@ -342,11 +357,11 @@ const cookieOptionsFactory = (req) => {
   const reqIsSecure = Boolean(req.secure || forwardedProto.split(',')[0] === 'https');
 
   // secure must be true for SameSite=None to work across sites
-  const secure = isProduction ? reqIsSecure : false;
+  const secure = isProduction ? reqIsSecure : req.protocol === 'https';
   const sameSite = secure ? 'None' : 'Lax';
 
   // Safe parse of maxAge minutes
-  const minutes = Number.parseInt(process.env.REFRESH_EXPIRE_MINUTES, 10);
+  const minutes = Number.parseInt(process.env.ACCESS_EXPIRE_MINUTES, 10);
   const maxAge = Number.isFinite(minutes) && minutes > 0 ? minutes * 60 * 1000 : undefined;
 
   const opts = {
@@ -399,6 +414,48 @@ async function createSessionAndUserToken(user, User, req, res, options = { host:
   return { jwtid };
 }
 
+/**
+ * Removes a session by its ID for a given user.
+ * @param {import('mongoose').Model} User The Mongoose User model.
+ * @param {string} userId The ID of the user.
+ * @param {string} sessionId The ID of the session to remove.
+ * @returns {Promise<void>}
+ * @memberof Auth
+ */
+async function removeSession(User, userId, sessionId) {
+  return await User.updateOne({ _id: userId }, { $pull: { activeSessions: { _id: sessionId } } });
+}
+
+/**
+ * Logs out a user session by removing it from the database and clearing the refresh token cookie.
+ * @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.
+ * @returns {Promise<boolean>} True if a session was found and removed, false otherwise.
+ * @memberof Auth
+ */
+async function logoutSession(User, req, res) {
+  const refreshToken = req.cookies?.refreshToken;
+
+  if (!refreshToken) {
+    return false;
+  }
+
+  const user = await User.findOne({ 'activeSessions.tokenHash': refreshToken });
+
+  if (!user) {
+    return false;
+  }
+
+  const session = user.activeSessions.find((s) => s.tokenHash === refreshToken);
+
+  const result = await removeSession(User, user._id, session._id);
+
+  res.clearCookie('refreshToken', { path: '/' });
+
+  return result.modifiedCount > 0;
+}
+
 /**
  * Create user and immediate session + access token
  * @param {import('express').Request} req The Express request object.
@@ -470,12 +527,10 @@ async function refreshSessionAndToken(req, res, User, options = { host: '', path
   }
 
   // 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');
+  if (!isRefreshTokenReq(req) && session.expiresAt && session.expiresAt < new Date()) {
+    const result = await removeSession(User, user._id, session._id);
+    if (result) throw new Error('Refresh token expired');
+    else throw new Error('Session not found');
   }
 
   // Rotate: generate new token, update stored hash and metadata
@@ -646,5 +701,8 @@ export {
   createSessionAndUserToken,
   createUserAndSession,
   refreshSessionAndToken,
+  logoutSession,
+  removeSession,
   applySecurity,
+  isRefreshTokenReq,
 };