webspresso 0.0.108 → 0.0.110

package/core/auth/hash.js

@@ -1,11 +1,9 @@
-/**
- * Webspresso Auth - Password Hashing
- * Bcrypt wrapper for secure password hashing
- * @module core/auth/hash
- */
-
+const crypto = require('crypto');
+const util = require('util');
 const { sha256, randomToken } = require('../utils/crypto');
 
+const scryptAsync = util.promisify(crypto.scrypt);
+
 let bcrypt = null;
 let bcryptChecked = false;
 function getBcrypt() {
@@ -27,69 +25,191 @@ function getBcrypt() {
 const DEFAULT_ROUNDS = process.env.NODE_ENV === 'test' ? 1 : 12;
 
 /**
- * Hash a password using bcrypt
+ * Default scrypt parameters (OWASP recommended)
+ * In test environments, lower cost is used for test execution speed
+ */
+const DEFAULT_SCRYPT_OPTIONS = {
+  cost: process.env.NODE_ENV === 'test' ? 1024 : 16384, // N
+  blockSize: 8, // r
+  parallelization: 1, // p
+  keylen: 64,
+  maxmem: 32 * 1024 * 1024, // 32MB
+};
+
+/**
+ * Hash a password using native crypto.scrypt (zero external dependencies)
  * @param {string} password - Plain text password
- * @param {number} [rounds=12] - Cost factor (rounds)
- * @returns {Promise<string>} Hashed password
+ * @param {Object} [options] - Scrypt options
+ * @param {number} [options.cost=16384] - CPU/memory cost parameter (N)
+ * @param {number} [options.blockSize=8] - Block size parameter (r)
+ * @param {number} [options.parallelization=1] - Parallelization parameter (p)
+ * @param {number} [options.keylen=64] - Desired key length in bytes
+ * @returns {Promise<string>} Standardized scrypt hash string
  */
-async function hash(password, rounds = DEFAULT_ROUNDS) {
-  const b = getBcrypt();
-  if (!b) {
-    throw new Error('bcrypt is required for password hashing. Install it with: npm install bcrypt');
-  }
-  
+async function hashScrypt(password, options = {}) {
   if (!password || typeof password !== 'string') {
     throw new Error('Password must be a non-empty string');
   }
-  
-  return b.hash(password, rounds);
+
+  const N = options.cost || options.N || DEFAULT_SCRYPT_OPTIONS.cost;
+  const r = options.blockSize || options.r || DEFAULT_SCRYPT_OPTIONS.blockSize;
+  const p = options.parallelization || options.p || DEFAULT_SCRYPT_OPTIONS.parallelization;
+  const keylen = options.keylen || DEFAULT_SCRYPT_OPTIONS.keylen;
+  const maxmem = options.maxmem || Math.max(DEFAULT_SCRYPT_OPTIONS.maxmem, 128 * N * r * 2);
+
+  const salt = options.salt ? Buffer.from(options.salt) : crypto.randomBytes(16);
+  const derivedKey = await scryptAsync(password, salt, keylen, { N, r, p, maxmem });
+
+  return `$scrypt$N=${N},r=${r},p=${p}$${salt.toString('hex')}$${derivedKey.toString('hex')}`;
 }
 
 /**
- * Verify a password against a hash
- * @param {string} password - Plain text password to verify
- * @param {string} hashedPassword - Hashed password to compare against
+ * Verify a password against an scrypt hash
+ * @param {string} password - Plain text password
+ * @param {string} hashedPassword - Standardized scrypt hash string
  * @returns {Promise<boolean>} True if password matches
  */
-async function verify(password, hashedPassword) {
-  const b = getBcrypt();
-  if (!b) {
-    throw new Error('bcrypt is required for password verification. Install it with: npm install bcrypt');
+async function verifyScrypt(password, hashedPassword) {
+  if (!password || !hashedPassword || typeof password !== 'string' || typeof hashedPassword !== 'string') {
+    return false;
   }
-  
-  if (!password || !hashedPassword) {
+
+  const match = hashedPassword.match(/^\$scrypt\$N=(\d+),r=(\d+),p=(\d+)\$([0-9a-fA-F]+)\$([0-9a-fA-F]+)$/);
+  if (!match) {
     return false;
   }
-  
+
+  const N = parseInt(match[1], 10);
+  const r = parseInt(match[2], 10);
+  const p = parseInt(match[3], 10);
+  const salt = Buffer.from(match[4], 'hex');
+  const expectedKey = Buffer.from(match[5], 'hex');
+
+  const maxmem = Math.max(DEFAULT_SCRYPT_OPTIONS.maxmem, 128 * N * r * 2);
+
   try {
-    return await b.compare(password, hashedPassword);
+    const derivedKey = await scryptAsync(password, salt, expectedKey.length, { N, r, p, maxmem });
+    if (derivedKey.length !== expectedKey.length) {
+      return false;
+    }
+    return crypto.timingSafeEqual(derivedKey, expectedKey);
   } catch {
     return false;
   }
 }
 
 /**
- * Check if a hash needs rehashing (e.g., cost factor changed)
- * @param {string} hashedPassword - Hashed password to check
- * @param {number} [rounds=12] - Desired cost factor
- * @returns {boolean} True if rehash is needed
+ * Hash a password using bcrypt (or native scrypt if bcrypt is unavailable or requested)
+ * @param {string} password - Plain text password
+ * @param {number|Object} [options=12] - Cost factor (rounds) or options object { algorithm: 'scrypt'|'bcrypt'|'auto', ... }
+ * @returns {Promise<string>} Hashed password
  */
-function needsRehash(hashedPassword, rounds = DEFAULT_ROUNDS) {
+async function hash(password, options = DEFAULT_ROUNDS) {
+  if (!password || typeof password !== 'string') {
+    throw new Error('Password must be a non-empty string');
+  }
+
+  let algorithm = 'auto';
+  let rounds = DEFAULT_ROUNDS;
+  let scryptOpts = {};
+
+  if (typeof options === 'number') {
+    rounds = options;
+  } else if (options && typeof options === 'object') {
+    algorithm = options.algorithm || 'auto';
+    rounds = options.rounds || DEFAULT_ROUNDS;
+    scryptOpts = options;
+  }
+
   const b = getBcrypt();
+
+  if (algorithm === 'scrypt' || (!b && algorithm === 'auto')) {
+    return hashScrypt(password, scryptOpts);
+  }
+
   if (!b) {
-    throw new Error('bcrypt is required. Install it with: npm install bcrypt');
+    throw new Error('bcrypt is required for bcrypt password hashing. Install it with: npm install bcrypt or use scrypt');
   }
-  
-  if (!hashedPassword) {
-    return true;
+
+  return b.hash(password, rounds);
+}
+
+/**
+ * Verify a password against a hash (supports both bcrypt and native scrypt hashes)
+ * @param {string} password - Plain text password to verify
+ * @param {string} hashedPassword - Hashed password to compare against
+ * @returns {Promise<boolean>} True if password matches
+ */
+async function verify(password, hashedPassword) {
+  if (!password || !hashedPassword || typeof password !== 'string' || typeof hashedPassword !== 'string') {
+    return false;
   }
-  
-  try {
-    const hashRounds = b.getRounds(hashedPassword);
-    return hashRounds < rounds;
-  } catch {
+
+  // Handle native scrypt hash format
+  if (hashedPassword.startsWith('$scrypt$')) {
+    return verifyScrypt(password, hashedPassword);
+  }
+
+  // Handle bcrypt hash formats ($2a$, $2b$, $2y$)
+  if (hashedPassword.startsWith('$2')) {
+    const b = getBcrypt();
+    if (!b) {
+      throw new Error('bcrypt is required to verify bcrypt hashes. Install it with: npm install bcrypt');
+    }
+    try {
+      return await b.compare(password, hashedPassword);
+    } catch {
+      return false;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a hash needs rehashing (e.g., cost factor changed or migrating to scrypt)
+ * @param {string} hashedPassword - Hashed password to check
+ * @param {number|Object} [options=12] - Desired cost factor (rounds) or options object
+ * @returns {boolean} True if rehash is needed
+ */
+function needsRehash(hashedPassword, options = DEFAULT_ROUNDS) {
+  if (!hashedPassword || typeof hashedPassword !== 'string') {
     return true;
   }
+
+  let desiredAlgorithm = 'auto';
+  let desiredRounds = DEFAULT_ROUNDS;
+  let desiredN = DEFAULT_SCRYPT_OPTIONS.cost;
+
+  if (typeof options === 'number') {
+    desiredRounds = options;
+  } else if (options && typeof options === 'object') {
+    desiredAlgorithm = options.algorithm || 'auto';
+    desiredRounds = options.rounds || DEFAULT_ROUNDS;
+    desiredN = options.cost || options.N || DEFAULT_SCRYPT_OPTIONS.cost;
+  }
+
+  if (hashedPassword.startsWith('$scrypt$')) {
+    if (desiredAlgorithm === 'bcrypt') return true;
+    const match = hashedPassword.match(/^\$scrypt\$N=(\d+)/);
+    if (!match) return true;
+    const currentN = parseInt(match[1], 10);
+    return currentN < desiredN;
+  }
+
+  if (hashedPassword.startsWith('$2')) {
+    if (desiredAlgorithm === 'scrypt') return true;
+    const b = getBcrypt();
+    if (!b) return true;
+    try {
+      const hashRounds = b.getRounds(hashedPassword);
+      return hashRounds < desiredRounds;
+    } catch {
+      return true;
+    }
+  }
+
+  return true;
 }
 
 /**
@@ -105,7 +225,7 @@ function generateToken(length = 32) {
  * Hash a high-entropy random lookup token for database storage (SHA-256).
  * Note: Used exclusively for 256-bit cryptographically secure random lookup tokens
  * (remember-me tokens, email verification tokens, password reset tokens), NOT user passwords.
- * User passwords must always be hashed using `hash()` (bcrypt).
+ * User passwords must always be hashed using `hash()` (bcrypt or scrypt).
  *
  * // CodeQL [js/insufficient-password-hash] SHA-256 is intentionally used for 256-bit high-entropy random lookup token hashing, not user passwords.
  * @param {string} token - High-entropy random token
@@ -121,7 +241,11 @@ module.exports = {
   hash,
   verify,
   needsRehash,
+  hashScrypt,
+  verifyScrypt,
+  DEFAULT_SCRYPT_OPTIONS,
   generateToken,
   hashToken,
   DEFAULT_ROUNDS,
 };
+

package/core/auth/index.js

@@ -15,7 +15,16 @@ function getMiddleware() {
   }
   return _middleware;
 }
-const { hash, verify, needsRehash, generateToken, hashToken } = require('./hash');
+const {
+  hash,
+  verify,
+  needsRehash,
+  hashScrypt,
+  verifyScrypt,
+  DEFAULT_SCRYPT_OPTIONS,
+  generateToken,
+  hashToken,
+} = require('./hash');
 const { signJwt, verifyJwt, decodeJwt, clearJwtCache, HS256_HEADER_BASE64URL, MAX_PAYLOAD_SIZE } = require('./jwt');
 const {
   TOKEN_TYPES,
@@ -264,6 +273,9 @@ module.exports = {
   hash,
   verify,
   needsRehash,
+  hashScrypt,
+  verifyScrypt,
+  DEFAULT_SCRYPT_OPTIONS,
   generateToken,
   hashToken,
 

package/core/auth/jwt.js

@@ -118,13 +118,23 @@ function verifyJwt(token, secret, options = {}) {
       verifiedJwtCache.set(cacheKey, cached);
 
       const nowSec = Math.floor(Date.now() / 1000);
+      const leewaySec = typeof options.leeway === 'number'
+        ? options.leeway
+        : (typeof options.clockTolerance === 'number' ? options.clockTolerance : 0);
+
       if (!options.ignoreExpiration && typeof cached.exp === 'number') {
-        if (nowSec >= cached.exp) {
+        if (nowSec >= cached.exp + leewaySec) {
           verifiedJwtCache.delete(cacheKey);
           throw new Error('JWT token has expired');
         }
       }
 
+      if (typeof cached.nbf === 'number') {
+        if (nowSec + leewaySec < cached.nbf) {
+          throw new Error('JWT token is not active yet');
+        }
+      }
+
       if (options.issuer && cached.iss !== options.issuer) {
         throw new Error(`Invalid JWT issuer (expected ${options.issuer}, got ${cached.iss})`);
       }
@@ -188,13 +198,22 @@ function verifyJwt(token, secret, options = {}) {
 
   // 4. Check claims
   const nowSec = Math.floor(Date.now() / 1000);
+  const leewaySec = typeof options.leeway === 'number'
+    ? options.leeway
+    : (typeof options.clockTolerance === 'number' ? options.clockTolerance : 0);
 
   if (!options.ignoreExpiration && typeof payload.exp === 'number') {
-    if (nowSec >= payload.exp) {
+    if (nowSec >= payload.exp + leewaySec) {
       throw new Error('JWT token has expired');
     }
   }
 
+  if (typeof payload.nbf === 'number') {
+    if (nowSec + leewaySec < payload.nbf) {
+      throw new Error('JWT token is not active yet');
+    }
+  }
+
   if (options.issuer && payload.iss !== options.issuer) {
     throw new Error(`Invalid JWT issuer (expected ${options.issuer}, got ${payload.iss})`);
   }

package/core/auth/manager.js

@@ -29,6 +29,36 @@ class AuthenticationError extends Error {
   }
 }
 
+const WEAK_SECRETS_PATTERN = /^(changeme|secret|default|password|test|webspresso-|123456)/i;
+
+/**
+ * Validate secret strength
+ * In production: throws Error if secret is missing, shorter than 32 chars, or uses common defaults.
+ * In development/test: logs a warning if weak.
+ * @param {string} name - Name of the secret setting / env var
+ * @param {string} value - Secret value
+ * @param {boolean} [isProd=false] - Whether environment is production
+ */
+function assertStrongSecret(name, value, isProd = false) {
+  if (!value || typeof value !== 'string') {
+    throw new Error(`${name} is required.`);
+  }
+
+  const isWeak = value.length < 32 || WEAK_SECRETS_PATTERN.test(value);
+
+  if (isProd && isWeak) {
+    throw new Error(
+      `Insecure secret for ${name}: Production requires at least 32 high-entropy characters and cannot use default/weak words. Generate one with 'openssl rand -hex 32'.`
+    );
+  }
+
+  if (!isProd && isWeak && !process.env.VITEST && process.env.NODE_ENV !== 'test') {
+    console.warn(
+      `\x1b[33m[Webspresso Security Warning]\x1b[0m ${name} appears weak or uses a default value. In production, at least 32 high-entropy characters are strictly enforced.`
+    );
+  }
+}
+
 /**
  * Default configuration
  */
@@ -117,12 +147,20 @@ class AuthManager extends EventEmitter {
     this.twoFactor = config.twoFactor || { enabled: false };
 
     if (config.jwt || config.secret) {
+      const isProd = process.env.NODE_ENV === 'production';
       const jwtSecret = typeof config.jwt === 'object' && config.jwt.secret
         ? config.jwt.secret
-        : (config.secret || config.session?.secret || process.env.JWT_SECRET || process.env.AUTH_SESSION_SECRET || 'webspresso-jwt-secret');
+        : (config.secret || config.session?.secret || process.env.JWT_SECRET || process.env.AUTH_SESSION_SECRET || (isProd ? null : 'webspresso-jwt-secret'));
+
+      assertStrongSecret('JWT_SECRET / auth.secret', jwtSecret, isProd);
+
       const refreshSecret = typeof config.jwt === 'object' && config.jwt.refreshSecret
         ? config.jwt.refreshSecret
         : (process.env.JWT_REFRESH_SECRET || jwtSecret);
+
+      if (refreshSecret !== jwtSecret) {
+        assertStrongSecret('JWT_REFRESH_SECRET', refreshSecret, isProd);
+      }
       const expiresIn = typeof config.jwt === 'object' && config.jwt.expiresIn
         ? config.jwt.expiresIn
         : '24h';
@@ -231,10 +269,9 @@ class AuthManager extends EventEmitter {
    */
   getSessionConfig() {
     const config = { ...this.config.session };
+    const isProd = process.env.NODE_ENV === 'production';
     
-    if (!config.secret) {
-      throw new Error('Session secret is required. Set AUTH_SESSION_SECRET environment variable or pass session.secret in config.');
-    }
+    assertStrongSecret('AUTH_SESSION_SECRET / session.secret', config.secret, isProd);
 
     // Auto-detect and configure distributed Redis session store
     if (!config.store) {
@@ -559,7 +596,10 @@ class AuthManager extends EventEmitter {
        * @param {string} tokenOrCode - Submitted 6-digit TOTP code or recovery code
        * @param {Object|string} secretOrUser - Secret string or user object with totp_secret / recovery_codes
        * @param {Object} [options]
-       * @returns {{ success: boolean, type?: 'totp'|'recovery_code', delta?: number, remainingHashedCodes?: string[], matchedIndex?: number }}
+       * @param {number} [options.lastStep] - Last accepted TOTP counter (defaults to user.totp_last_step / totpLastStep)
+       * @param {boolean} [options.preventReuse=true] - Reject a TOTP code whose counter was already accepted
+       * @returns {{ success: boolean, type?: 'totp'|'recovery_code', delta?: number, step?: number, remainingHashedCodes?: string[], matchedIndex?: number }}
+       *   On TOTP success, persist `step` (e.g. users.totp_last_step) to block replays across processes.
        */
       verify2Fa(tokenOrCode, secretOrUser, options = {}) {
         if (!tokenOrCode) {
@@ -578,10 +618,21 @@ class AuthManager extends EventEmitter {
 
         // Try TOTP code first
         if (secret) {
-          const totpResult = self.totp.verifyTotp(tokenOrCode, secret, { ...options, detailed: true });
+          const preventReuse = options.preventReuse !== false;
+          let afterStep;
+          if (preventReuse) {
+            const persisted = options.lastStep ?? (secretOrUser && typeof secretOrUser === 'object'
+              ? (secretOrUser.totp_last_step ?? secretOrUser.totpLastStep)
+              : undefined);
+            const steps = [Number(persisted), self.totp.getLastUsedTotpStep(secret)]
+              .filter((n) => typeof n === 'number' && Number.isFinite(n));
+            if (steps.length > 0) afterStep = Math.max(...steps);
+          }
+          const totpResult = self.totp.verifyTotp(tokenOrCode, secret, { ...options, afterStep, detailed: true });
           if (totpResult.valid) {
+            if (preventReuse) self.totp.markTotpStepUsed(secret, totpResult.counter);
             this.set2FaVerified(true);
-            return { success: true, type: 'totp', delta: totpResult.delta };
+            return { success: true, type: 'totp', delta: totpResult.delta, step: totpResult.counter };
           }
         }
 
@@ -895,13 +946,13 @@ class AuthManager extends EventEmitter {
       TOKEN_TYPES.PASSWORD_RESET,
       rawToken
     );
-    if (!verified) {
+    // Claim the token before acting on it so concurrent requests cannot both redeem it
+    if (!verified || !(await consumeAuthToken(this.authTokens, verified.tokenHash))) {
       throw new AuthenticationError('Invalid or expired reset token', 'INVALID_TOKEN');
     }
 
     const hashed = await hashPassword(newPassword);
     await this.updateUser(verified.userId, { [this.passwordField]: hashed });
-    await consumeAuthToken(this.authTokens, verified.tokenHash);
     await this.authTokens.deleteAllForUser(verified.userId, TOKEN_TYPES.PASSWORD_RESET);
 
     return { ok: true };
@@ -966,12 +1017,11 @@ class AuthManager extends EventEmitter {
       TOKEN_TYPES.EMAIL_VERIFY,
       rawToken
     );
-    if (!verified) {
+    if (!verified || !(await consumeAuthToken(this.authTokens, verified.tokenHash))) {
       throw new AuthenticationError('Invalid or expired verification token', 'INVALID_TOKEN');
     }
 
     await this.updateUser(verified.userId, { [this.verifiedField]: new Date() });
-    await consumeAuthToken(this.authTokens, verified.tokenHash);
 
     return { ok: true, userId: verified.userId };
   }
@@ -1059,7 +1109,7 @@ class AuthManager extends EventEmitter {
       TOKEN_TYPES.MAGIC_LINK,
       rawToken
     );
-    if (!verified) {
+    if (!verified || !(await consumeAuthToken(this.authTokens, verified.tokenHash))) {
       throw new AuthenticationError('Invalid or expired magic link', 'INVALID_MAGIC_LINK');
     }
 
@@ -1068,8 +1118,6 @@ class AuthManager extends EventEmitter {
       throw new AuthenticationError('User not found for magic link', 'USER_NOT_FOUND');
     }
 
-    await consumeAuthToken(this.authTokens, verified.tokenHash);
-
     if (options.consumeAllForUser !== false) {
       await this.authTokens.deleteAllForUser(verified.userId, TOKEN_TYPES.MAGIC_LINK);
     }
@@ -1330,4 +1378,5 @@ module.exports = {
   AuthManager,
   AuthenticationError,
   DEFAULT_CONFIG,
+  assertStrongSecret,
 };

package/core/auth/middleware.js

@@ -45,6 +45,8 @@ function createAuthMiddleware(authManager) {
    * Sets up express-session with secure cookie enforcement
    */
   const sessionMiddleware = session({
+    resave: sessionConfig.resave ?? false,
+    saveUninitialized: sessionConfig.saveUninitialized ?? false,
     ...sessionConfig,
     cookie: {
       httpOnly: true,
@@ -125,14 +127,14 @@ function createAuthMiddleware(authManager) {
   function requireJwt(options = {}) {
     return async (req, res, next) => {
       const authHeader = req.headers?.authorization || req.headers?.Authorization;
-      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      if (!authHeader || !/^Bearer\s+/i.test(authHeader)) {
         return res.status(401).json({
           error: 'Unauthorized',
           message: 'Bearer token required',
         });
       }
 
-      const token = authHeader.substring(7).trim();
+      const token = authHeader.replace(/^Bearer\s+/i, '').trim();
       try {
         const payload = authManager.verifyJwt(token, options);
         req.token = token;

package/core/auth/oauth.js

@@ -8,6 +8,7 @@
 const crypto = require('crypto');
 const { fetchWithTimeout } = require('../utils/fetch');
 const { safeCompare, sha256, hmacSha256, base64UrlEncode, base64UrlDecode, randomToken } = require('../utils/crypto');
+const { assertStrongSecret } = require('./manager');
 
 /**
  * Custom error class for OAuth operations
@@ -193,7 +194,10 @@ class OAuthClient {
    * @param {number} [config.stateTtlMs=600000] - State token TTL in ms
    */
   constructor(config = {}) {
-    this.secret = config.secret || process.env.OAUTH_SECRET || process.env.SESSION_SECRET || 'webspresso-oauth-secret';
+    const isProd = process.env.NODE_ENV === 'production';
+    this.secret = config.secret || process.env.OAUTH_SECRET || process.env.SESSION_SECRET || (isProd ? null : 'webspresso-oauth-secret');
+    // State tokens are HMAC-signed with this secret; a well-known default would let anyone forge them.
+    if (isProd) assertStrongSecret('OAUTH_SECRET / oauth.secret', this.secret, true);
     this.stateTtlMs = config.stateTtlMs || 10 * 60 * 1000;
     this.timeout = typeof (config.timeout || config.requestTimeout) === 'number'
       ? (config.timeout || config.requestTimeout)

package/core/auth/tokens.js

@@ -63,7 +63,7 @@ function createKnexAuthTokensAdapter(db) {
       return knex('auth_tokens').where({ token: tokenHash, type }).first();
     },
     delete: async (tokenHash) => {
-      await knex('auth_tokens').where({ token: tokenHash }).delete();
+      return knex('auth_tokens').where({ token: tokenHash }).delete();
     },
     deleteAllForUser: async (userId, type) => {
       const q = knex('auth_tokens').where({ user_id: userId });
@@ -120,11 +120,16 @@ async function verifyAuthToken(authTokensAdapter, type, rawToken) {
 }
 
 /**
+ * Atomically claim a verified token by deleting it. Only the caller whose delete removed the row
+ * may act on the token, so concurrent requests cannot both redeem it.
+ * Adapters whose delete() returns no count are trusted (treated as claimed).
  * @param {Object} authTokensAdapter
  * @param {string} tokenHash
+ * @returns {Promise<boolean>} true when this caller claimed the token
  */
 async function consumeAuthToken(authTokensAdapter, tokenHash) {
-  await authTokensAdapter.delete(tokenHash);
+  const deleted = await authTokensAdapter.delete(tokenHash);
+  return typeof deleted === 'number' ? deleted > 0 : true;
 }
 
 /**

package/core/auth/totp.js

@@ -223,13 +223,16 @@ function generateTotp(secret, options = {}) {
  * @param {number} [options.step=30] - Time step in seconds
  * @param {number} [options.digits=6] - Expected digits
  * @param {string} [options.algorithm='sha1'] - 'sha1', 'sha256', 'sha512'
- * @param {boolean} [options.detailed=false] - Return { valid: boolean, delta: number|null } instead of boolean
- * @returns {boolean|{ valid: boolean, delta: number|null }}
+ * @param {number} [options.afterStep] - Reject counters <= this value (RFC 6238 §5.2 replay protection;
+ *   pass the counter of the last accepted code)
+ * @param {boolean} [options.detailed=false] - Return { valid, delta, counter } instead of boolean
+ * @returns {boolean|{ valid: boolean, delta: number|null, counter?: number|null }}
  */
 function verifyTotp(token, secret, options = {}) {
   if (typeof token !== 'string') {
-    return options.detailed ? { valid: false, delta: null } : false;
+    return options.detailed ? { valid: false, delta: null, counter: null } : false;
   }
+  const afterStep = typeof options.afterStep === 'number' ? options.afterStep : -1;
 
   const cleanToken = token.trim();
   const digits = options.digits || cleanToken.length || 6;
@@ -250,23 +253,54 @@ function verifyTotp(token, secret, options = {}) {
 
   for (let delta = -windowSize; delta <= windowSize; delta++) {
     const counter = currentCounter + delta;
-    if (counter < 0) continue;
+    if (counter < 0 || counter <= afterStep) continue;
 
     const expected = generateHotp(secret, counter, { ...options, digits });
     if (timingSafeTokenCompare(cleanToken, expected)) {
       if (options.detailed) {
-        return { valid: true, delta };
+        return { valid: true, delta, counter };
       }
       return true;
     }
   }
 
   if (options.detailed) {
-    return { valid: false, delta: null };
+    return { valid: false, delta: null, counter: null };
   }
   return false;
 }
 
+// In-process record of the last accepted TOTP counter per secret, so a code cannot be
+// replayed within its validity window. Bounded; persist the returned step for cluster-wide safety.
+const MAX_TRACKED_TOTP_SECRETS = 10000;
+const lastUsedTotpSteps = new Map();
+
+function secretKey(secret) {
+  return sha256(Buffer.isBuffer(secret) ? secret.toString('hex') : String(secret));
+}
+
+/**
+ * @param {string|Buffer} secret
+ * @returns {number|undefined} Last accepted counter for this secret in this process
+ */
+function getLastUsedTotpStep(secret) {
+  return lastUsedTotpSteps.get(secretKey(secret));
+}
+
+/**
+ * @param {string|Buffer} secret
+ * @param {number} counter - Accepted counter
+ */
+function markTotpStepUsed(secret, counter) {
+  const key = secretKey(secret);
+  const prev = lastUsedTotpSteps.get(key);
+  lastUsedTotpSteps.delete(key);
+  lastUsedTotpSteps.set(key, typeof prev === 'number' ? Math.max(prev, counter) : counter);
+  if (lastUsedTotpSteps.size > MAX_TRACKED_TOTP_SECRETS) {
+    lastUsedTotpSteps.delete(lastUsedTotpSteps.keys().next().value);
+  }
+}
+
 /**
  * Generate standard Key URI for Google Authenticator / 1Password / Authy (otpauth://)
  * @param {Object} options
@@ -465,6 +499,8 @@ function createTotpSetup(options = {}) {
 }
 
 module.exports = {
+  getLastUsedTotpStep,
+  markTotpStepUsed,
   // Base32
   base32Encode,
   base32Decode,

package/core/auth/user-agent.js

@@ -57,6 +57,8 @@ function parseUserAgent(userAgent = '') {
 
   const cached = uaCache.get(ua);
   if (cached) {
+    uaCache.delete(ua);
+    uaCache.set(ua, cached);
     return { ...cached };
   }