@volcanicminds/backend 3.0.1 → 3.2.0

package/dist/types/global.d.ts

@@ -37,6 +37,15 @@ export interface Data {
   [option: string]: any
 }
 
+// Structural hints (manifest L1) — domain-only, optional, additive. Usually declared
+// at the file-level `config` of a routes.ts (one file ≈ one resource), overridable per-route.
+export interface ResourceHints {
+  name?: string // canonical resource name; maps schemas → resource without heuristics
+  titleField?: string | string[]
+  subtitleField?: string | string[]
+  globalSearch?: string[] // omni-search fields (OR)
+}
+
 export interface RouteConfig {
   title: string
   description: string
@@ -52,6 +61,8 @@ export interface RouteConfig {
   response?: any
   consumes?: any
   rawBody?: boolean
+  group?: string // sidebar group hint (manifest)
+  resource?: ResourceHints // resource-level manifest hints
 }
 
 export interface Route {
@@ -84,6 +95,10 @@ export interface GeneralConfig {
       header_key?: string
       query_key?: string
     }
+    // Admin manifest capability (opt-in): exposes GET /admin/manifest
+    manifest?: {
+      enabled: boolean
+    }
   }
 }
 
@@ -134,6 +149,8 @@ export interface ConfiguredRoute {
     response?: any
     consumes?: any
   }
+  group?: string // structural hint (manifest)
+  resource?: ResourceHints // structural hints (manifest)
 }
 
 export interface TrackChanges {
@@ -211,7 +228,10 @@ export interface DataBaseManagement {
 
 export interface MfaManagement {
   generateSetup(appName: string, email: string): Promise<{ secret: string; uri: string; qrCode: string }>
-  verify(token: string, secret: string): boolean
+  // Returns the matched time-step delta (integer) when valid, or null when invalid.
+  // The delta enables anti-replay protection (track the consumed step). Legacy managers returning a
+  // boolean are still tolerated at runtime (treated as valid/invalid without replay tracking).
+  verify(token: string, secret: string): number | null
 }
 
 // Callback type signature: (uploadOrId, req, res) => void
@@ -313,6 +333,7 @@ declare global {
   var connection: any
   var entity: any
   var repository: any
+  var routes: ConfiguredRoute[]
 }
 
 export { global }

package/lib/api/admin/controller/manifest.ts

@@ -0,0 +1,9 @@
+import { FastifyReply, FastifyRequest } from 'fastify'
+import { generateManifest } from '../../../manifest/generator.js'
+
+// GET /admin/manifest — full Manifest v2 (declared roles). Gating is enforced by the
+// route (roles:[admin] + isAuthenticated); the manifest itself is not per-user.
+export function get(req: FastifyRequest, reply: FastifyReply) {
+  const server = (req.server as any) || global.server
+  return reply.send(generateManifest(server))
+}

package/lib/api/admin/routes.ts

@@ -0,0 +1,26 @@
+const { manifest } = global.config?.options || {}
+const isEnabled = manifest?.enabled || false
+
+export default {
+  config: {
+    title: 'Admin',
+    description: 'Backoffice support: manifest descriptor (admin scope)',
+    controller: 'controller',
+    enable: isEnabled, // opt-in via config.options.manifest.enabled
+    tenantContext: false,
+    tags: ['admin']
+  },
+  routes: [
+    {
+      method: 'GET',
+      path: '/manifest',
+      roles: [roles.admin],
+      handler: 'manifest.get',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Admin manifest',
+        description: 'Manifest v2 describing the admin-manageable API (full, with declared roles).'
+      }
+    }
+  ]
+}

package/lib/api/auth/controller/auth.ts

@@ -2,11 +2,34 @@
 import { FastifyReply, FastifyRequest } from 'fastify'
 import * as regExp from '../../../util/regexp.js'
 import { MfaPolicy } from '../../../config/constants.js'
+import { httpError } from '../../../util/httpError.js'
 
 // Upper bound for the password accepted at login: a cheap guard against oversized
 // payloads. Complexity is enforced only when a password is set, not at login.
 const MAX_PASSWORD_LENGTH = 256
 
+// TOTP period in seconds — must match the period used by the MFA manager (tools default: 30).
+const TOTP_PERIOD_SECONDS = 30
+
+/**
+ * Normalizes the MFA manager `verify` result and turns the relative time-step delta into the
+ * absolute step consumed, so it can be persisted for anti-replay.
+ *
+ * - New managers return `number | null` (delta or invalid).
+ * - Legacy managers returning a boolean are tolerated: valid/invalid without a usable counter.
+ *
+ * @returns `{ valid, counter }` — `counter` is the absolute TOTP step, or `null` when unknown.
+ */
+function evaluateMfaResult(result: number | boolean | null): { valid: boolean; counter: number | null } {
+  if (result === null || result === false) return { valid: false, counter: null }
+  if (typeof result === 'number') {
+    const currentStep = Math.floor(Date.now() / 1000 / TOTP_PERIOD_SECONDS)
+    return { valid: true, counter: currentStep + result }
+  }
+  // Legacy boolean `true`: valid, but no delta to track replays with.
+  return { valid: true, counter: null }
+}
+
 export async function register(req: FastifyRequest, reply: FastifyReply) {
   const { password1: password, password2, ...data } = req.data()
 
@@ -15,27 +38,27 @@ export async function register(req: FastifyRequest, reply: FastifyReply) {
   }
 
   if (!data.username) {
-    return reply.status(400).send(new Error('Username not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Username not valid' })
   }
   if (!regExp.isEmail(data.email)) {
-    return reply.status(400).send(new Error('Email not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Email not valid' })
   }
   if (!password || !regExp.password.test(password)) {
-    return reply.status(400).send(new Error('Password not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Password not valid' })
   }
   if (!password2 || password2 !== password) {
-    return reply.status(400).send(new Error('Repeated password not match'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Repeated password not match' })
   }
 
   let existings = await req.server['userManager'].retrieveUserByEmail(data.email, req.runner)
   if (existings) {
-    return reply.status(400).send(new Error('Email already registered'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Email already registered' })
   }
 
   if ((data.requiredRoles || []).includes('admin')) {
     existings = await req.server['userManager'].findQuery({ 'roles:in': 'admin' }, req.runner)
     if (existings?.records?.length) {
-      return reply.status(400).send(new Error('User admin already registered'))
+      return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'User admin already registered' })
     }
   }
 
@@ -48,7 +71,7 @@ export async function register(req: FastifyRequest, reply: FastifyReply) {
 
   const user = await req.server['userManager'].createUser({ ...data, password: password }, req.runner)
   if (!user) {
-    return reply.status(400).send(new Error('User not registered'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'User not registered' })
   }
 
   return user
@@ -61,18 +84,18 @@ export async function unregister(req: FastifyRequest, reply: FastifyReply) {
   let isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(403).send(new Error('Wrong credentials'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Wrong credentials' })
   }
 
   if (user.blocked) {
-    return reply.status(403).send(new Error('User blocked'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User blocked' })
   }
 
   user = await req.server['userManager'].disableUserById(user.getId(), req.runner)
   isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(400).send(new Error('User not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'User not valid' })
   }
 
   return { ok: true }
@@ -82,12 +105,12 @@ export async function validatePassword(req: FastifyRequest, reply: FastifyReply)
   const { password } = req.data()
 
   if (!password) {
-    return reply.status(400).send(new Error('Password cannot be null'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Password cannot be null' })
   }
 
   const match = regExp.password.test(password)
   if (!match) {
-    return reply.status(400).send(new Error('Password is not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Password is not valid' })
   }
 
   return { ok: match }
@@ -100,32 +123,32 @@ export async function changePassword(req: FastifyRequest, reply: FastifyReply) {
 
   const _user = req.user
   if (!_user) {
-    return reply.status(401).send(new Error('Unauthorized'))
+    return reply.status(401).send({ statusCode: 401, error: 'Unauthorized', message: 'Unauthorized' })
   }
 
   const { email, oldPassword, newPassword1, newPassword2 } = req.data()
 
   if (_user.email !== email && (!req.hasRole(roles.admin) || !global.config.options.admin_can_change_passwords)) {
-    return reply.status(400).send(new Error('Email not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Email not valid' })
   }
 
   if (!newPassword1 || !regExp.password.test(newPassword1)) {
-    return reply.status(400).send(new Error('New password is not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'New password is not valid' })
   }
 
   if (!newPassword2 || newPassword2 !== newPassword1) {
-    return reply.status(400).send(new Error('Repeated new password not match'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Repeated new password not match' })
   }
 
   let user = await req.server['userManager'].retrieveUserByPassword(email, oldPassword, req.runner)
   let isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(403).send(new Error('Wrong credentials'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Wrong credentials' })
   }
 
   if (user.blocked) {
-    return reply.status(403).send(new Error('User blocked'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User blocked' })
   }
 
   user = await req.server['userManager'].changePassword(email, newPassword1, oldPassword, req.runner)
@@ -141,7 +164,7 @@ export async function forgotPassword(req: FastifyRequest, reply: FastifyReply) {
   }
 
   if (!username && !regExp.isEmail(email)) {
-    return reply.status(400).send(new Error('Missing a valid user identifier'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing a valid user identifier' })
   }
 
   let user = null as any
@@ -151,38 +174,35 @@ export async function forgotPassword(req: FastifyRequest, reply: FastifyReply) {
     user = await req.server['userManager'].retrieveUserByUsername(username, req.runner)
   }
 
-  let isValid = await req.server['userManager'].isValidUser(user)
-
-  if (!isValid) {
-    return reply.status(403).send(new Error('Wrong credentials'))
-  }
+  const isValid = await req.server['userManager'].isValidUser(user)
 
-  if (user?.blocked) {
-    return reply.status(403).send(new Error('User blocked'))
+  // Account-enumeration hardening: do NOT reveal whether the account exists, is
+  // invalid or is blocked. Always answer 200 with a generic body; only actually
+  // trigger the reset flow when the user exists, is valid and not blocked.
+  // (A residual timing side-channel remains since the valid path does a DB write.)
+  if (isValid && !user?.blocked) {
+    await req.server['userManager'].forgotPassword(user.email, req.runner)
   }
 
-  user = await req.server['userManager'].forgotPassword(user.email, req.runner)
-  isValid = await req.server['userManager'].isValidUser(user)
-
-  return { ok: isValid }
+  return { ok: true }
 }
 
 export async function confirmEmail(req: FastifyRequest, reply: FastifyReply) {
   const { code } = req.data()
 
   if (!code) {
-    return reply.status(400).send(new Error('Missing the confirm email token'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing the confirm email token' })
   }
 
   let user = await req.server['userManager'].retrieveUserByConfirmationToken(code, req.runner)
   let isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(403).send(new Error('Wrong credentials'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Wrong credentials' })
   }
 
   if (user.blocked) {
-    return reply.status(403).send(new Error('User blocked'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User blocked' })
   }
 
   user = await req.server['userManager'].userConfirmation(user, req.runner)
@@ -199,22 +219,22 @@ export async function resetPassword(req: FastifyRequest, reply: FastifyReply) {
   }
 
   if (!newPassword1 || !regExp.password.test(newPassword1)) {
-    return reply.status(400).send(new Error('New password not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'New password not valid' })
   }
 
   if (!newPassword2 || newPassword2 !== newPassword1) {
-    return reply.status(400).send(new Error('Repeated new password not match'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Repeated new password not match' })
   }
 
   let user = await req.server['userManager'].retrieveUserByResetPasswordToken(code, req.runner)
   let isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(403).send(new Error('Wrong credentials'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Wrong credentials' })
   }
 
   if (user.blocked) {
-    return reply.status(403).send(new Error('User blocked'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User blocked' })
   }
 
   user = await req.server['userManager'].resetPassword(user, newPassword1, req.runner)
@@ -231,7 +251,7 @@ export async function login(req: FastifyRequest, reply: FastifyReply) {
   }
 
   if (!regExp.isEmail(email)) {
-    return reply.status(400).send(new Error('Email not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Email not valid' })
   }
   // At login we do NOT re-validate the password complexity policy: the password
   // was already validated when it was set (register/change/reset), and bcrypt is
@@ -239,31 +259,31 @@ export async function login(req: FastifyRequest, reply: FastifyReply) {
   // would lock out existing users whenever the policy changes. We only bound the
   // input length as a cheap guard against oversized payloads.
   if (!password || password.length > MAX_PASSWORD_LENGTH) {
-    return reply.status(400).send(new Error('Password not valid'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Password not valid' })
   }
 
   let user = await req.server['userManager'].retrieveUserByPassword(email, password, req.runner)
   if (!user) {
-    return reply.status(403).send(new Error('Wrong credentials'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Wrong credentials' })
   }
 
   const isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(403).send(new Error('Invalid user'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Invalid user' })
   }
 
   if (!(user.confirmed === true)) {
-    return reply.status(403).send(new Error('User email unconfirmed'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User email unconfirmed' })
   }
 
   const isPasswordToBeChanged = req.server['userManager'].isPasswordToBeChanged(user)
   if (isPasswordToBeChanged) {
-    return reply.status(403).send({ statusCode: 403, code: 'PASSWORD_TO_BE_CHANGED', message: 'Password is expired' })
+    return reply.status(403).send(httpError(403, 'Password is expired', 'PASSWORD_TO_BE_CHANGED'))
   }
 
   if (user.blocked) {
-    return reply.status(403).send(new Error('User blocked'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User blocked' })
   }
 
   // MFA Logic Interception
@@ -342,6 +362,18 @@ export async function refreshToken(req: FastifyRequest, reply: FastifyReply) {
     throw new Error('Not implemented')
   }
 
+  // Refresh tokens are optional (JWT_REFRESH). When disabled there is no refresh
+  // verifier registered — answer a clean 404 instead of throwing a 500 later.
+  if (!reply.server.jwt['refreshToken']) {
+    return reply.status(404).send(httpError(404, 'Refresh tokens are disabled', 'NOT_FOUND'))
+  }
+
+  if (!token || !refreshToken) {
+    return reply
+      .status(400)
+      .send({ statusCode: 400, error: 'Bad Request', message: 'Missing token or refreshToken' })
+  }
+
   // Verify the signature of the (possibly expired) access token: `ignoreExpiration`
   // lets a stale token through — which is the whole point of refresh — but a forged
   // or tampered token is now rejected (previously `decode` skipped signature checks).
@@ -349,7 +381,7 @@ export async function refreshToken(req: FastifyRequest, reply: FastifyReply) {
   try {
     tokenData = (await reply.server.jwt.verify(token, { ignoreExpiration: true })) as { sub: number; iat?: number }
   } catch {
-    return reply.status(403).send(new Error('Invalid token'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Invalid token' })
   }
 
   // Reject refresh of access tokens issued too long ago. Use the real temporal
@@ -357,19 +389,19 @@ export async function refreshToken(req: FastifyRequest, reply: FastifyReply) {
   // against a unix timestamp and was effectively dead code.
   const minAccettable = Math.floor(Date.now() / 1000) - 2592000 // 30 days
   if (!tokenData?.iat || tokenData.iat < minAccettable) {
-    return reply.status(403).send(new Error('Token too old'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Token too old' })
   }
 
   const refreshTokenData = await reply.server.jwt['refreshToken'].verify(refreshToken)
   if (tokenData?.sub && tokenData?.sub !== refreshTokenData?.sub) {
-    return reply.status(403).send(new Error('Mismatched tokens'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Mismatched tokens' })
   }
 
   const user = await req.server['userManager'].retrieveUserByExternalId(tokenData.sub, req.runner)
   const isValid = await req.server['userManager'].isValidUser(user)
 
   if (!isValid) {
-    return reply.status(403).send(new Error('Wrong refresh token'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Wrong refresh token' })
   }
 
   const newToken = await reply.jwtSign({ sub: user.externalId, tid: req.tenant?.id })
@@ -381,7 +413,7 @@ export async function refreshToken(req: FastifyRequest, reply: FastifyReply) {
 export async function invalidateTokens(req: FastifyRequest, reply: FastifyReply) {
   let isValid = await req.server['userManager'].isValidUser(req.user)
   if (!req.user || !isValid) {
-    return reply.status(403).send(new Error('User not linked'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'User not linked' })
   }
 
   const user = await req.server['userManager'].resetExternalId(req.user.getId(), req.runner)
@@ -391,7 +423,7 @@ export async function invalidateTokens(req: FastifyRequest, reply: FastifyReply)
 
 export async function mfaSetup(req: FastifyRequest, reply: FastifyReply) {
   const user = req.user
-  if (!user) return reply.status(401).send(new Error('Unauthorized'))
+  if (!user) return reply.status(401).send({ statusCode: 401, error: 'Unauthorized', message: 'Unauthorized' })
 
   try {
     // Use mfaManager (injected) for logic
@@ -400,7 +432,7 @@ export async function mfaSetup(req: FastifyRequest, reply: FastifyReply) {
     return setupData
   } catch (error: any) {
     req.log.error({ err: error }, 'MFA Setup failed')
-    return reply.status(500).send(new Error('Failed to generate MFA setup'))
+    return reply.status(500).send({ statusCode: 500, error: 'Internal Server Error', message: 'Failed to generate MFA setup' })
   }
 }
 
@@ -409,19 +441,24 @@ export async function mfaEnable(req: FastifyRequest, reply: FastifyReply) {
   const { secret, token } = req.data()
   const { mfa_policy = MfaPolicy.OPTIONAL } = global.config.options || {}
 
-  if (!user || !secret || !token) return reply.status(400).send(new Error('Missing parameters'))
+  if (!user || !secret || !token) return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing parameters' })
 
   try {
     // 1. Verify using mfaManager (tools)
-    const isValid = req.server['mfaManager'].verify(token, secret)
-    if (!isValid) {
-      return reply.status(400).send(new Error('Invalid token'))
+    const { valid, counter } = evaluateMfaResult(req.server['mfaManager'].verify(token, secret))
+    if (!valid) {
+      return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Invalid token' })
     }
 
     // 2. Save using userManager (typeorm)
     await req.server['userManager'].saveMfaSecret(user.getId(), secret, req.runner)
     await req.server['userManager'].enableMfa(user.getId(), req.runner)
 
+    // Record the consumed time-step so the same code cannot be replayed on the first /mfa/verify.
+    if (counter !== null) {
+      await req.server['userManager'].updateUserById(user.getId(), { mfaLastUsedCounter: counter }, req.runner)
+    }
+
     // IMPORTANT: Return full tokens upon enablement if user was in pending state
     // BUT usually user is already logged in via temp token or full token.
     // If user is setting up from "Forced Setup", they need tokens now.
@@ -443,7 +480,7 @@ export async function mfaEnable(req: FastifyRequest, reply: FastifyReply) {
     }
   } catch (error: any) {
     req.log.error({ err: error }, 'MFA Enable failed')
-    return reply.status(500).send(new Error('Failed to enable MFA'))
+    return reply.status(500).send({ statusCode: 500, error: 'Internal Server Error', message: 'Failed to enable MFA' })
   }
 }
 
@@ -451,34 +488,43 @@ export async function mfaVerify(req: FastifyRequest, reply: FastifyReply) {
   const authHeader = req.headers.authorization
   const { mfa_policy = MfaPolicy.OPTIONAL } = global.config.options || {}
 
-  if (!authHeader) return reply.status(401).send(new Error('Missing authorization'))
+  if (!authHeader) return reply.status(401).send({ statusCode: 401, error: 'Unauthorized', message: 'Missing authorization' })
 
   const tokenStr = authHeader.split(' ')[1]
   let decoded: any
   try {
     decoded = req.server.jwt.verify(tokenStr)
   } catch (_e) {
-    return reply.status(401).send(new Error('Invalid token'))
+    return reply.status(401).send({ statusCode: 401, error: 'Unauthorized', message: 'Invalid token' })
   }
 
   if (decoded.role !== 'pre-auth-mfa' && (!req.user || !req.user.getId())) {
-    return reply.status(403).send(new Error('Invalid token scope'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Invalid token scope' })
   }
 
   const subjectId = decoded.sub
   const { token } = req.data()
-  if (!token) return reply.status(400).send(new Error('Missing token'))
+  if (!token) return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing token' })
 
   // 1. Retrieve secret via userManager
   const user = await req.server['userManager'].retrieveUserByExternalId(subjectId, req.runner)
-  if (!user) return reply.status(404).send(new Error('User not found'))
+  if (!user) return reply.status(404).send({ statusCode: 404, error: 'Not Found', message: 'User not found' })
 
   const secret = await req.server['userManager'].retrieveMfaSecret(user.getId(), req.runner)
-  if (!secret) return reply.status(403).send(new Error('MFA not configured for user'))
+  if (!secret) return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'MFA not configured for user' })
 
   // 2. Verify via mfaManager
-  const isValid = req.server['mfaManager'].verify(token, secret)
-  if (!isValid) return reply.status(403).send(new Error('Invalid MFA token'))
+  const { valid, counter } = evaluateMfaResult(req.server['mfaManager'].verify(token, secret))
+  if (!valid) return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Invalid MFA token' })
+
+  // 3. Anti-replay: reject a code whose time-step was already consumed (same or earlier than the last).
+  const lastCounter = user.mfaLastUsedCounter
+  if (counter !== null && lastCounter != null && counter <= lastCounter) {
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'MFA token already used' })
+  }
+  if (counter !== null) {
+    await req.server['userManager'].updateUserById(user.getId(), { mfaLastUsedCounter: counter }, req.runner)
+  }
 
   if (config.options.reset_external_id_on_login) {
     await req.server['userManager'].resetExternalId(user.getId(), req.runner)
@@ -502,11 +548,11 @@ export async function mfaVerify(req: FastifyRequest, reply: FastifyReply) {
 
 export async function mfaDisable(req: FastifyRequest, reply: FastifyReply) {
   const user = req.user
-  if (!user) return reply.status(401).send(new Error('Unauthorized'))
+  if (!user) return reply.status(401).send({ statusCode: 401, error: 'Unauthorized', message: 'Unauthorized' })
 
   const { mfa_policy = MfaPolicy.OPTIONAL } = global.config.options || {}
   if (mfa_policy === MfaPolicy.MANDATORY || mfa_policy === MfaPolicy.ONE_WAY) {
-    return reply.status(403).send(new Error('MFA disable is not allowed by security policy'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'MFA disable is not allowed by security policy' })
   }
 
   try {
@@ -514,6 +560,6 @@ export async function mfaDisable(req: FastifyRequest, reply: FastifyReply) {
     return { ok: true }
   } catch (error: any) {
     req.log.error({ err: error }, 'MFA Disable failed')
-    return reply.status(500).send(new Error('Failed to disable MFA'))
+    return reply.status(500).send({ statusCode: 500, error: 'Internal Server Error', message: 'Failed to disable MFA' })
   }
 }

package/lib/api/auth/routes.ts

@@ -1,3 +1,12 @@
+// Throttle credential-sensitive endpoints (login, register, forgot/reset password)
+// to blunt brute-force / credential-stuffing / password-spray (OWASP API2/API4).
+// Per-IP, configurable via env. The rateLimit plugin is registered global:false,
+// so only routes carrying this opt in.
+const authRateLimit = {
+  max: Math.floor(Number(process.env.AUTH_RATELIMIT_MAX) || 10),
+  timeWindow: Math.floor(Number(process.env.AUTH_RATELIMIT_WINDOW) || 60000)
+}
+
 export default {
   config: {
     title: 'Authentication functions',
@@ -15,6 +24,7 @@ export default {
       roles: [],
       handler: 'auth.register',
       middlewares: ['global.preAuth', 'global.postAuth'],
+      rateLimit: authRateLimit,
       config: {
         title: 'Register new user',
         description: 'Register a new user',
@@ -90,6 +100,7 @@ export default {
       roles: [],
       handler: 'auth.forgotPassword',
       middlewares: ['global.preForgotPassword', 'global.postForgotPassword'],
+      rateLimit: authRateLimit,
       config: {
         title: 'Forgot password',
         description:
@@ -106,6 +117,7 @@ export default {
       roles: [],
       handler: 'auth.resetPassword',
       middlewares: [],
+      rateLimit: authRateLimit,
       config: {
         title: 'Reset password',
         description:
@@ -122,6 +134,7 @@ export default {
       roles: [],
       handler: 'auth.login',
       middlewares: ['global.preAuth', 'global.postAuth'],
+      rateLimit: authRateLimit,
       config: {
         title: 'Login',
         description: 'Login authentication',
@@ -195,6 +208,8 @@ export default {
       roles: [],
       handler: 'auth.mfaEnable',
       middlewares: ['global.isAuthenticated'],
+      // Throttle TOTP attempts to curb online brute-force of the 6-digit code (S11).
+      rateLimit: { max: 10, timeWindow: 60000 },
       config: {
         title: 'Enable MFA',
         description: 'Enable MFA by verifying a token against the generated secret. Returns tokens on success.',
@@ -210,6 +225,8 @@ export default {
       roles: [],
       handler: 'auth.mfaVerify',
       middlewares: [],
+      // Throttle TOTP attempts to curb online brute-force of the 6-digit code (S11).
+      rateLimit: { max: 10, timeWindow: 60000 },
       config: {
         title: 'Verify MFA',
         description: 'Verify MFA token during login to obtain final JWT',