@volcanicminds/backend 3.0.1 → 3.1.0

package/lib/database/typeorm/query.ts

@@ -1,24 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable prefer-const */
-import {
-  Not,
-  Like,
-  ILike,
-  Raw,
-  Equal,
-  IsNull,
-  In,
-  Between,
-  MoreThan,
-  MoreThanOrEqual,
-  LessThan,
-  LessThanOrEqual,
-  QueryRunner
-} from 'typeorm'
+import { QueryRunner } from 'typeorm'
 import yn from './util/yn.js'
 import * as log from './util/logger.js'
 import { parseLogicExpression } from './query/parser.js'
 import { buildWhereFromAst } from './query/builder.js'
+import { buildReservedOperators } from './query/operators.js'
 
 let sensitiveFields = ['password', 'mfaSecret', 'resetPasswordToken', 'confirmationToken']
 
@@ -29,12 +16,34 @@ export const configureSensitiveFields = (fields: string[]) => {
   }
 }
 
-const evalOrder = (val: string = '') => (['desc', 'd', 'false', '1'].includes(val.toLowerCase()) ? 'desc' : 'asc')
+// When true, the base text operators (eq, contains, starts, ends, like and their
+// negations) are CASE-INSENSITIVE for string values; the `*s` variants force
+// case-sensitive. When false, the legacy behavior is restored (base = sensitive,
+// `*i` variants = insensitive). Default: true (matches the common expectation
+// that `?name=mario` finds "Mario"). Override per-app via the data-layer option
+// `caseInsensitiveByDefault` or the env `VOLCANIC_CASE_INSENSITIVE_DEFAULT`.
+let caseInsensitiveByDefault = yn(process.env.VOLCANIC_CASE_INSENSITIVE_DEFAULT, true)
+
+export const configureCaseInsensitiveDefault = (flag: boolean) => {
+  caseInsensitiveByDefault = !!flag
+  log.info(`Volcanic-TypeORM: caseInsensitiveByDefault = ${caseInsensitiveByDefault}`)
+}
 
-const escapeRegExp = (str: string) => {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+// Upper bound for how many rows a single Magic Query can return. Prevents a caller
+// from requesting `?take=10000000` and exhausting memory/DB (OWASP API4). Default
+// 100; override per-app via the data-layer option `maxPageSize` or the env
+// `VOLCANIC_MAX_PAGE_SIZE`. A value <= 0 disables the cap (not recommended).
+let maxPageSize = Math.floor(Number(process.env.VOLCANIC_MAX_PAGE_SIZE) || 100)
+
+export const configureMaxPageSize = (size: number) => {
+  if (typeof size === 'number' && Number.isFinite(size)) {
+    maxPageSize = Math.floor(size)
+    log.info(`Volcanic-TypeORM: maxPageSize = ${maxPageSize}`)
+  }
 }
 
+const evalOrder = (val: string = '') => (['desc', 'd', 'false', '1'].includes(val.toLowerCase()) ? 'desc' : 'asc')
+
 const isValidIdentifier = (str: string) => /^[a-zA-Z0-9_.]+$/.test(str)
 
 const hasProtoRisk = (str: string) => ['__proto__', 'constructor', 'prototype'].includes(str)
@@ -76,63 +85,26 @@ export const useOrder = (order: string[] = []) => {
   return result
 }
 
-const typecastValue = (value: any) => {
-  if (typeof value !== 'string') return value
-  const lowerValue = value.toLowerCase()
-  if (lowerValue === 'true') return true
-  if (lowerValue === 'false') return false
-  if (lowerValue === 'null') return null
-  return value
-}
-
 export const useWhere = (where: any, repo?: any) => {
   const aliasMap = new Map<string, any>()
   const isTargetMongo = isMongo(repo)
-  const val = (v) => v || 'notFound'
-
-  const reservedOperators = {
-    ':null': (v) => (typecastValue(v) === false ? Not(IsNull()) : IsNull()),
-    ':notNull': (v) => (typecastValue(v) === true ? Not(IsNull()) : IsNull()),
-    ':in': (v) => In(val(v).split(',').map(typecastValue)),
-    ':nin': (v) => Not(In(val(v).split(',').map(typecastValue))),
-    ':likei': (v) => (isTargetMongo ? new RegExp(escapeRegExp(val(v)), 'i') : ILike(`%${val(v)}%`)),
-    ':containsi': (v) => (isTargetMongo ? new RegExp(escapeRegExp(val(v)), 'i') : ILike(`%${val(v)}%`)),
-    ':ncontainsi': (v) => (isTargetMongo ? Not(new RegExp(escapeRegExp(val(v)), 'i')) : Not(ILike(`%${val(v)}%`))),
-    ':startsi': (v) => (isTargetMongo ? new RegExp(`^${escapeRegExp(val(v))}`, 'i') : ILike(`${val(v)}%`)),
-    ':endsi': (v) => (isTargetMongo ? new RegExp(`${escapeRegExp(val(v))}$`, 'i') : ILike(`%${val(v)}`)),
-    ':eqi': (v) => (isTargetMongo ? new RegExp(`^${escapeRegExp(val(v))}$`, 'i') : ILike(v)),
-    ':neqi': (v) => (isTargetMongo ? Not(new RegExp(`^${escapeRegExp(val(v))}$`, 'i')) : Not(ILike(v))),
-    ':like': (v) => Like(`${val(v)}`),
-    ':contains': (v) => Like(`%${val(v)}%`),
-    ':ncontains': (v) => Not(Like(`%${val(v)}%`)),
-    ':starts': (v) => Like(`${val(v)}%`),
-    ':ends': (v) => Like(`%${val(v)}`),
-    ':eq': (v) => {
-      const typedValue = typecastValue(v)
-      if (typedValue === null) return IsNull()
-      return isTargetMongo ? typedValue : Equal(typedValue)
-    },
-    ':neq': (v) => Not(Equal(typecastValue(v))),
-    ':gt': (v) => MoreThan(v),
-    ':ge': (v) => MoreThanOrEqual(v),
-    ':lt': (v) => LessThan(v),
-    ':le': (v) => LessThanOrEqual(v),
-    ':between': (v) => {
-      const s = v?.split(':')
-      return s?.length == 2 ? Between(s[0], s[1]) : v
-    },
-    ':overlap': (v) => {
-      const values = val(v).split(',').map(typecastValue)
-      if (isTargetMongo) {
-        return { $in: values }
-      }
-      return Raw((alias) => `${alias} && ARRAY[:...overlapValues]::text[]`, { overlapValues: values })
-    }
-  }
 
-  if (yn(process.env.VOLCANIC_CUSTOM_QUERY_OPERATORS, false)) {
+  const allowRaw = yn(process.env.VOLCANIC_CUSTOM_QUERY_OPERATORS, false)
+  if (allowRaw) {
     log.warn('Volcanic-TypeORM: Custom query operators (:raw) enabled. SECURITY RISK!')
-    reservedOperators[':raw'] = (v) => Raw((alias) => `${alias} ${v}`)
+  }
+
+  const reservedOperators = buildReservedOperators({
+    isTargetMongo,
+    caseInsensitive: caseInsensitiveByDefault,
+    allowRaw
+  })
+
+  // Operator NAMES are case-insensitive: `:isEmpty`, `:isempty`, `:ISEMPTY` all
+  // resolve to the same handler via this lowercased lookup.
+  const operatorLookup: Record<string, (v: any) => any> = {}
+  for (const k of Object.keys(reservedOperators)) {
+    operatorLookup[k.toLowerCase()] = reservedOperators[k]
   }
 
   const reservedWords = Object.keys(reservedOperators).join('|')
@@ -158,6 +130,7 @@ export const useWhere = (where: any, repo?: any) => {
     const m = key.match(new RegExp(`(${reservedWords})\\b`, 'ig'))
     const operator = m?.length ? m[0] : ':eq'
     const fullPath = key.replace(operator, '')
+    const handler = operatorLookup[operator.toLowerCase()]
 
     if (!isValidIdentifier(fullPath)) {
       log.warn(`Volcanic-TypeORM: Invalid filter field skipped: ${fullPath}`)
@@ -171,8 +144,8 @@ export const useWhere = (where: any, repo?: any) => {
     }
 
     let value = where[rawKey]
-    if (operator && reservedOperators[operator]) {
-      value = reservedOperators[operator](value)
+    if (handler) {
+      value = handler(value)
     }
 
     let condition = {}
@@ -200,7 +173,9 @@ export const useWhere = (where: any, repo?: any) => {
 export function applyQuery(data, extraWhere, repo) {
   const { page: p = 1, pageSize = 25, skip: sk = 0, take: tk = 0, sort: s, _logic, ...where } = data
   const page: number = (p < 1 ? 1 : p) - 1
-  const take: number = tk || pageSize
+  // Clamp the requested page size to maxPageSize (resource-consumption guard).
+  const requestedTake: number = tk || pageSize
+  const take: number = maxPageSize > 0 ? Math.min(requestedTake, maxPageSize) : requestedTake
   const skip: number = sk || page * pageSize
   const order: string[] = !Array.isArray(s) ? [s] : s
 

package/lib/database/typeorm/util/crypto.ts

@@ -1,51 +1,113 @@
 import * as crypto from 'crypto'
 
-const ALGORITHM_NEW = 'aes-256-gcm'
-const ALGORITHM_OLD = 'aes-256-cbc'
+// Authenticated cipher used for all NEW data.
+const ALGORITHM_GCM = 'aes-256-gcm'
+// Legacy, unauthenticated cipher: only ever READ for backward compatibility, never written.
+const ALGORITHM_CBC_LEGACY = 'aes-256-cbc'
+
 const SECRET_KEY = process.env.MFA_DB_SECRET || process.env.JWT_SECRET
-const IV_LENGTH_NEW = 12
 
-function getKey() {
+// Current (v2) format parameters.
+const VERSION = 'v2'
+const IV_LENGTH = 12 // GCM standard nonce length
+const SALT_LENGTH = 16 // per-record random salt for the KDF
+const KEY_LENGTH = 32 // AES-256
+// scrypt cost parameters (N must be a power of 2). N=2^15 keeps derivation well under ~50ms.
+const SCRYPT_N = 32768
+const SCRYPT_r = 8
+const SCRYPT_p = 1
+// scrypt memory cost is ~128*N*r bytes (~33.5MB here), above Node's 32MB default → raise maxmem.
+const SCRYPT_MAXMEM = 64 * 1024 * 1024
+
+function getSecret(): string {
   if (!SECRET_KEY) {
     throw new Error('Secret key is not defined in environment variables.')
   }
-  return crypto.createHash('sha256').update(String(SECRET_KEY)).digest('base64').substring(0, 32)
+  return String(SECRET_KEY)
+}
+
+/**
+ * Robust per-record key derivation: scrypt(secret, random salt). Each record carries its own salt,
+ * so identical plaintexts never share a key and the derivation follows a memory-hard standard.
+ */
+function deriveKey(salt: Buffer): Buffer {
+  return crypto.scryptSync(getSecret(), salt, KEY_LENGTH, {
+    N: SCRYPT_N,
+    r: SCRYPT_r,
+    p: SCRYPT_p,
+    maxmem: SCRYPT_MAXMEM
+  })
 }
 
+/**
+ * Legacy key derivation (weak, no salt): sha256(secret) -> base64 -> first 32 chars used as raw key bytes.
+ * Kept ONLY to decrypt records written before the v2 format. Never used to encrypt new data.
+ */
+function legacyKey(): Buffer {
+  return Buffer.from(crypto.createHash('sha256').update(getSecret()).digest('base64').substring(0, KEY_LENGTH))
+}
+
+/**
+ * Encrypts a plaintext into the authenticated, versioned format: `v2:salt:iv:authTag:ciphertext` (hex).
+ */
 export function encrypt(text: string): string {
   if (!text) return text
-  const iv = crypto.randomBytes(IV_LENGTH_NEW)
-  const cipher = crypto.createCipheriv(ALGORITHM_NEW, Buffer.from(getKey()), iv)
-  let encrypted = cipher.update(text, 'utf8')
-  encrypted = Buffer.concat([encrypted, cipher.final()])
+
+  const salt = crypto.randomBytes(SALT_LENGTH)
+  const iv = crypto.randomBytes(IV_LENGTH)
+  const key = deriveKey(salt)
+
+  const cipher = crypto.createCipheriv(ALGORITHM_GCM, key, iv)
+  const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()])
   const authTag = cipher.getAuthTag()
-  return iv.toString('hex') + ':' + authTag.toString('hex') + ':' + encrypted.toString('hex')
+
+  return [VERSION, salt.toString('hex'), iv.toString('hex'), authTag.toString('hex'), encrypted.toString('hex')].join(
+    ':'
+  )
 }
 
+/**
+ * Decrypts a value produced by any supported format:
+ *  - v2 (current):    `v2:salt:iv:authTag:ciphertext` -> scrypt key + GCM
+ *  - legacy GCM:      `iv:authTag:ciphertext`         -> legacy key + GCM
+ *  - legacy CBC:      `iv:ciphertext`                 -> legacy key + CBC (unauthenticated, read-only)
+ * Tampering with a GCM/v2 record throws (auth tag mismatch).
+ */
 export function decrypt(text: string): string {
   if (!text) return text
-  const textParts = text.split(':')
-
-  if (textParts.length === 2) {
-    const iv = Buffer.from(textParts[0], 'hex')
-    const encryptedText = Buffer.from(textParts[1], 'hex')
-    const decipher = crypto.createDecipheriv(ALGORITHM_OLD, Buffer.from(getKey()), iv)
-    let decrypted = decipher.update(encryptedText)
-    decrypted = Buffer.concat([decrypted, decipher.final()])
-    return decrypted.toString()
+
+  const parts = text.split(':')
+
+  // Current versioned format.
+  if (parts.length === 5 && parts[0] === VERSION) {
+    const salt = Buffer.from(parts[1], 'hex')
+    const iv = Buffer.from(parts[2], 'hex')
+    const authTag = Buffer.from(parts[3], 'hex')
+    const encryptedText = Buffer.from(parts[4], 'hex')
+
+    const decipher = crypto.createDecipheriv(ALGORITHM_GCM, deriveKey(salt), iv)
+    decipher.setAuthTag(authTag)
+    return decipher.update(encryptedText, undefined, 'utf8') + decipher.final('utf8')
   }
 
-  if (textParts.length === 3) {
-    const iv = Buffer.from(textParts[0], 'hex')
-    const authTag = Buffer.from(textParts[1], 'hex')
-    const encryptedText = Buffer.from(textParts[2], 'hex')
+  // Legacy authenticated GCM (pre-v2): iv:authTag:ciphertext with the old key derivation.
+  if (parts.length === 3) {
+    const iv = Buffer.from(parts[0], 'hex')
+    const authTag = Buffer.from(parts[1], 'hex')
+    const encryptedText = Buffer.from(parts[2], 'hex')
 
-    const decipher = crypto.createDecipheriv(ALGORITHM_NEW, Buffer.from(getKey()), iv)
+    const decipher = crypto.createDecipheriv(ALGORITHM_GCM, legacyKey(), iv)
     decipher.setAuthTag(authTag)
+    return decipher.update(encryptedText, undefined, 'utf8') + decipher.final('utf8')
+  }
+
+  // Legacy unauthenticated CBC (oldest records): iv:ciphertext with the old key derivation. Read-only.
+  if (parts.length === 2) {
+    const iv = Buffer.from(parts[0], 'hex')
+    const encryptedText = Buffer.from(parts[1], 'hex')
 
-    let decrypted = decipher.update(encryptedText, undefined, 'utf8')
-    decrypted += decipher.final('utf8')
-    return decrypted
+    const decipher = crypto.createDecipheriv(ALGORITHM_CBC_LEGACY, legacyKey(), iv)
+    return Buffer.concat([decipher.update(encryptedText), decipher.final()]).toString()
   }
 
   return text

package/lib/defaults/managers.ts

@@ -182,7 +182,7 @@ export const defaultMfaManager: MfaManagement = {
   generateSetup(_appName: string, _email: string) {
     throw new Error('Not implemented.')
   },
-  verify(_token: string, _secret: string) {
+  verify(_token: string, _secret: string): number | null {
     throw new Error('Not implemented.')
   }
 }

package/lib/hooks/onRequest.ts

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { getParams, getData } from '../util/common.js'
+import { httpError } from '../util/httpError.js'
 import type { AuthenticatedUser, AuthenticatedToken, Role, TransferManagement } from '../../types/global.js'
 
 const MFA_SETUP_WHITELIST = ['/auth/mfa/setup', '/auth/mfa/enable', '/auth/mfa/verify', '/auth/logout']
@@ -78,18 +79,10 @@ export default async (req, reply) => {
         const { multi_tenant } = global.config?.options || {}
         if (multi_tenant?.enabled && cfg.tenantContext !== false) {
           if (!req.tenant || !tokenData.tid) {
-            return reply.status(403).send({
-              statusCode: 403,
-              code: 'TENANT_NOT_FOUND',
-              message: 'Token does not belong to this tenant'
-            })
+            return reply.status(403).send(httpError(403, 'Token does not belong to this tenant', 'TENANT_NOT_FOUND'))
           }
           if (tokenData.tid !== req.tenant.id) {
-            return reply.status(403).send({
-              statusCode: 403,
-              code: 'TENANT_MISMATCH',
-              message: 'Token does not belong to this tenant'
-            })
+            return reply.status(403).send(httpError(403, 'Token does not belong to this tenant', 'TENANT_MISMATCH'))
           }
         }
 
@@ -100,11 +93,9 @@ export default async (req, reply) => {
 
           if (!isAllowed) {
             if (log.w) log.warn(`Security Block: User attempted to access ${currentUrl} with pre-auth MFA token`)
-            return reply.status(403).send({
-              statusCode: 403,
-              code: 'MFA_REQUIRED',
-              message: 'MFA verification or setup required to access this resource'
-            })
+            return reply
+              .status(403)
+              .send(httpError(403, 'MFA verification or setup required to access this resource', 'MFA_REQUIRED'))
           }
         }
 
@@ -122,9 +113,7 @@ export default async (req, reply) => {
           if (user) {
             const isValid = await req.server['userManager'].isValidUser(user)
             if (!isValid) {
-              return reply
-                .status(403)
-                .send({ statusCode: 403, code: 'USER_NOT_VALID', message: 'User is not valid or blocked' })
+              return reply.status(403).send(httpError(403, 'User is not valid or blocked', 'USER_NOT_VALID'))
             }
             req.user = user
           }
@@ -135,16 +124,14 @@ export default async (req, reply) => {
           if (token) {
             const isValid = await req.server['tokenManager'].isValidToken(token)
             if (!isValid) {
-              return reply
-                .status(403)
-                .send({ statusCode: 403, code: 'TOKEN_NOT_VALID', message: 'Token is not valid or blocked' })
+              return reply.status(403).send(httpError(403, 'Token is not valid or blocked', 'TOKEN_NOT_VALID'))
             }
             req.token = token
           }
         }
 
         if (!req.user && !req.token) {
-          return reply.status(404).send({ statusCode: 404, code: 'SUBJECT_NOT_FOUND', message: 'Subject not found' })
+          return reply.status(404).send(httpError(404, 'Subject not found', 'SUBJECT_NOT_FOUND'))
         }
 
         const freshNormalizedRoles = normalizeRoles(req.user?.roles || req.token?.roles)
@@ -152,11 +139,7 @@ export default async (req, reply) => {
       } catch (error) {
         const isRoutePublic = (cfg.requiredRoles || []).some((role: Role) => role.code === roles.public.code)
         if (!isRoutePublic) {
-          return reply.status(401).send({
-            statusCode: 401,
-            code: 'UNAUTHORIZED',
-            message: (error as any)?.message || 'Invalid or expired token'
-          })
+          return reply.status(401).send(httpError(401, (error as any)?.message || 'Invalid or expired token', 'UNAUTHORIZED'))
         }
       }
     }
@@ -167,8 +150,13 @@ export default async (req, reply) => {
       const hasPermission = requiredRoles.some((r) => authorizedRoles.includes(r.code))
 
       if (!hasPermission) {
-        if (log.w) log.warn(`Forbidden: ${req.user?.email || 'anonymous'} cannot call ${method.toUpperCase()} ${url}`)
-        return reply.status(403).send({ statusCode: 403, code: 'FORBIDDEN', message: 'Authorization denied' })
+        // 401 when there is no authenticated subject (must log in first); 403 when
+        // authenticated but lacking the required role.
+        const anonymous = !req.user && !req.token
+        if (log.w) log.warn(`Denied: ${req.user?.email || 'anonymous'} cannot call ${method.toUpperCase()} ${url}`)
+        return anonymous
+          ? reply.status(401).send(httpError(401, 'Authentication required', 'UNAUTHORIZED'))
+          : reply.status(403).send(httpError(403, 'Authorization denied', 'FORBIDDEN'))
       }
     }
   }

package/lib/loader/router.ts

@@ -65,7 +65,7 @@ async function loadMiddlewares(base: string, middlewares: string[] = []) {
 }
 
 
-function processRoute(
+export function processRoute(
   route: Route,
   index: number,
   file: string,
@@ -90,6 +90,9 @@ function processRoute(
   let requiredRoles: Role[] = []
 
   try {
+    // `admin` is a global superuser: it is appended to EVERY route's allowed roles,
+    // so an admin can access any endpoint (even ones restricted to e.g. backoffice).
+    // This is intentional. Remove this append if admin should NOT be a universal role.
     requiredRoles = rsp.some((r) => r.code === roles.admin.code) ? rsp : [...rsp, roles.admin]
   } catch (err) {
     if (log.e) log.error(`Error in loading roles for ${methodCase} ${pathName} (${handler})`)
@@ -132,7 +135,10 @@ function processRoute(
     if (!methods.includes(method)) errors.push(`Error in [${file}] bad method [${method}] at route n. ${num}`)
     if (handlerParts.length !== 2) errors.push(`Error in [${file}] bad handler [${handler}] at route n. ${num}`)
 
-    const key = method + endpoint + version
+    // Stored routes keep a leading slash in `path` ('/' + endpoint), so the key
+    // must include it too — otherwise 'GETusers' never equals 'GET/users' and the
+    // duplicate check silently never fires.
+    const key = `${method}/${endpoint}${version}`
     if (validRoutes.some((r) => `${r.method}${r.path}${r.doc?.version}` === key)) {
       errors.push(`Error in [${file}] duplicated path [${pathName}] at route n. ${num}`)
     }

package/lib/loader/tracking.ts

@@ -25,7 +25,16 @@ export async function load() {
 
       if (enableAll) {
         changes.forEach((change) => {
-          const tc: TrackChanges = { primaryKey: primaryKey, changeEntity: changeEntity, ...change } as TrackChanges
+          // `enable: true` default must be PERSISTED: the runtime gate
+          // (getTrackingConfigIfEnabled) checks `tc.enable`, so a change entry
+          // without an explicit `enable` would otherwise never track despite
+          // isValid() treating it as enabled.
+          const tc: TrackChanges = {
+            primaryKey: primaryKey,
+            changeEntity: changeEntity,
+            enable: true,
+            ...change
+          } as TrackChanges
           const code = getCodeBy(tc.method, tc.path)
 
           if (code in trackChangesList) {

package/lib/middleware/isAdmin.ts

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { FastifyReply, FastifyRequest } from 'fastify'
+import { httpError } from '../util/httpError.js'
 
 export function preHandler(req: FastifyRequest, res: FastifyReply, done: any) {
   try {
@@ -10,6 +11,7 @@ export function preHandler(req: FastifyRequest, res: FastifyReply, done: any) {
     throw new Error('User without this privilege')
   } catch (err) {
     if (log.e) log.error(`Upps, something just happened ${err}`)
-    res.code(403).send(new Error('User without this privilege'))
+    // Structured body so the 403 status is preserved (see isAuthenticated note).
+    res.code(403).send(httpError(403, 'User without this privilege', 'FORBIDDEN'))
   }
 }

package/lib/middleware/isAuthenticated.ts

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { FastifyReply, FastifyRequest } from 'fastify'
+import { httpError } from '../util/httpError.js'
 
 export function preHandler(req: FastifyRequest, res: FastifyReply, done: any) {
   try {
@@ -10,6 +11,8 @@ export function preHandler(req: FastifyRequest, res: FastifyReply, done: any) {
     throw new Error('Unauthorized')
   } catch (err) {
     if (log.e) log.error(`Upps, something just happened ${err}`)
-    return res.code(401).send(new Error('Unauthorized')) // must be authorized first
+    // Send a structured body (not a raw Error): `reply.code(x).send(new Error())`
+    // loses the status in Fastify's async error path and collapses to 500/403.
+    return res.code(401).send(httpError(401, 'Unauthorized', 'UNAUTHORIZED')) // must be authorized first
   }
 }

package/lib/schemas/user.ts

@@ -2,8 +2,15 @@ export const currentUserBodySchema = {
   $id: 'currentUserBodySchema',
   type: 'object',
   nullable: true,
+  // Self-service profile edit only. `additionalProperties: false` rejects any other
+  // field (roles, blocked, confirmed, password, externalId, mfa*) so a user cannot
+  // mass-assign their way to privilege escalation. The controller also whitelists
+  // these same fields as the real security boundary (defense in depth).
+  additionalProperties: false,
   properties: {
-    username: { type: 'string' }
+    username: { type: 'string' },
+    firstName: { type: 'string' },
+    lastName: { type: 'string' }
   }
 }
 
@@ -11,9 +18,18 @@ export const userBodySchema = {
   $id: 'userBodySchema',
   type: 'object',
   nullable: true,
+  // Admin create/update surface. `additionalProperties: false` drops anything not
+  // listed (e.g. externalId, mfaSecret, passwordChangedAt). `password` is allowed
+  // for CREATE (createUser hashes it); on UPDATE it is dropped in updateUserById so
+  // it can never be stored in plaintext — credential changes go through the
+  // dedicated hashed flows (change-password / reset-password).
+  additionalProperties: false,
   properties: {
     username: { type: 'string' },
     email: { type: 'string' },
+    password: { type: 'string' },
+    firstName: { type: 'string' },
+    lastName: { type: 'string' },
     blocked: { type: 'boolean' },
     blockedReason: { type: 'string' },
     blockedAt: { type: 'string' },

package/lib/util/errors.ts

@@ -12,8 +12,10 @@ export class TranslatedError extends Error {
     this.locale = locale
     this.status = status
     this.translationCode = translationCode
-    this.translatedMessage = global.t.__({ phrase: translationCode || defaultMessage, locale: locale || 'en' }, data)
-    this.message = this.translatedMessage || defaultMessage || 'generic error'
+    const phrase = translationCode || defaultMessage
+    this.translatedMessage = phrase ? global.t.__({ phrase, locale: locale || 'en' }, data) : null
+    // fallback: tradotto -> code grezzo -> defaultMessage -> catch-all
+    this.message = this.translatedMessage || translationCode || defaultMessage || 'generic error'
     this.data = data
 
     Error.captureStackTrace(this, this.constructor || TranslatedError)

package/lib/util/httpError.ts

@@ -0,0 +1,37 @@
+// Standard error response body for the whole framework.
+//
+//   { statusCode, error, code?, message? }
+//
+//   statusCode : HTTP status
+//   error      : HTTP reason phrase ('Bad Request', 'Unauthorized', ...)
+//   code       : optional machine-readable code ('TENANT_MISMATCH', 'MFA_REQUIRED', ...)
+//   message    : optional human-readable message
+//
+// Use this instead of `reply.send(new Error(...))`, which loses the status in
+// Fastify's async error path (collapses to 500/403).
+const REASON: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  409: 'Conflict',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error'
+}
+
+export interface HttpErrorBody {
+  statusCode: number
+  error: string
+  code?: string
+  message?: string
+}
+
+export function httpError(statusCode: number, message?: string, code?: string): HttpErrorBody {
+  return {
+    statusCode,
+    error: REASON[statusCode] || 'Error',
+    ...(code ? { code } : {}),
+    ...(message ? { message } : {})
+  }
+}