@volcanicminds/backend 3.0.1 → 3.2.0

package/lib/database/typeorm/query/operators.ts

@@ -0,0 +1,187 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+//
+// Magic Query operator catalog.
+//
+// Builds the map of `:operator -> FindOperator factory` used by `useWhere`.
+// Extracted from query.ts to keep that file focused on the query-assembly logic.
+//
+// Naming convention (case sensitivity):
+//   base   -> case-INsensitive by default (e.g. `eq`, `contains`)
+//   `*s`   -> strict / case-Sensitive
+//   `*i`   -> case-Insensitive (explicit alias)
+// `eq`/`neq` stay type-aware: numbers/booleans/null match exactly (no ILIKE on
+// non-text columns); only genuine strings become case-insensitive.
+//
+// Operator NAMES are matched case-insensitively by the caller, so `:isEmpty`,
+// `:isempty` and `:ISEMPTY` are equivalent.
+//
+import {
+  Not,
+  Like,
+  ILike,
+  Raw,
+  Equal,
+  IsNull,
+  In,
+  Between,
+  MoreThan,
+  MoreThanOrEqual,
+  LessThan,
+  LessThanOrEqual
+} from 'typeorm'
+
+export const escapeRegExp = (str: string) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+// Coerces the textual query value: 'true'/'false'/'null' -> boolean/null,
+// everything else stays a string (Postgres casts numeric strings on its own).
+export 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
+}
+
+const isNumericString = (v: any) => typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v)
+const val = (v: any) => v || 'notFound'
+
+export interface OperatorContext {
+  isTargetMongo: boolean
+  caseInsensitive: boolean
+  allowRaw?: boolean
+}
+
+export type OperatorMap = Record<string, (v: any) => any>
+
+/**
+ * Builds the operator catalog for the given context. Keys are ordered
+ * longest/most-specific first so the alternation regex in `useWhere` resolves
+ * correctly even with the `\b` boundary.
+ */
+export function buildReservedOperators(ctx: OperatorContext): OperatorMap {
+  const { isTargetMongo, caseInsensitive: ci, allowRaw } = ctx
+
+  // case-insensitive equality, numeric/boolean/null-safe
+  const eqInsensitive = (v: any) => {
+    const t = typecastValue(v)
+    if (t === null) return IsNull()
+    if (typeof t === 'boolean') return isTargetMongo ? t : Equal(t)
+    if (isNumericString(t)) return isTargetMongo ? t : Equal(t)
+    return isTargetMongo ? new RegExp(`^${escapeRegExp(t)}$`, 'i') : ILike(t)
+  }
+  const eqSensitive = (v: any) => {
+    const t = typecastValue(v)
+    if (t === null) return IsNull()
+    return isTargetMongo ? t : Equal(t)
+  }
+
+  const containsS = (v: any) => (isTargetMongo ? new RegExp(escapeRegExp(val(v))) : Like(`%${val(v)}%`))
+  const containsI = (v: any) => (isTargetMongo ? new RegExp(escapeRegExp(val(v)), 'i') : ILike(`%${val(v)}%`))
+  const startsS = (v: any) => (isTargetMongo ? new RegExp(`^${escapeRegExp(val(v))}`) : Like(`${val(v)}%`))
+  const startsI = (v: any) => (isTargetMongo ? new RegExp(`^${escapeRegExp(val(v))}`, 'i') : ILike(`${val(v)}%`))
+  const endsS = (v: any) => (isTargetMongo ? new RegExp(`${escapeRegExp(val(v))}$`) : Like(`%${val(v)}`))
+  const endsI = (v: any) => (isTargetMongo ? new RegExp(`${escapeRegExp(val(v))}$`, 'i') : ILike(`%${val(v)}`))
+  const likeS = (v: any) => (isTargetMongo ? new RegExp(escapeRegExp(val(v))) : Like(`${val(v)}`))
+  const likeI = (v: any) => (isTargetMongo ? new RegExp(escapeRegExp(val(v)), 'i') : ILike(`${val(v)}`))
+  const not = (fn: (v: any) => any) => (v: any) => Not(fn(v))
+
+  const arrayOp = (sqlOp: string, paramName: string) => (v: any) => {
+    const values = val(v).split(',').map(typecastValue)
+    if (isTargetMongo) return { $in: values }
+    return Raw((alias) => `${alias} ${sqlOp} ARRAY[:...${paramName}]::text[]`, { [paramName]: values })
+  }
+
+  // JSONB key-existence operators (Postgres only; degrade to $in on Mongo).
+  const jsonHasKey = (v: any) => {
+    if (isTargetMongo) return { $exists: true }
+    return Raw((alias) => `${alias} ? :jsonHasKeyValue`, { jsonHasKeyValue: val(v) })
+  }
+  const jsonHasArray = (sqlOp: string, paramName: string) => (v: any) => {
+    const values = val(v).split(',')
+    if (isTargetMongo) return { $in: values }
+    return Raw((alias) => `${alias} ${sqlOp} ARRAY[:...${paramName}]`, { [paramName]: values })
+  }
+
+  const ops: OperatorMap = {
+    // --- null / empty ---
+    ':notNull': (v) => (typecastValue(v) === true ? Not(IsNull()) : IsNull()),
+    ':null': (v) => (typecastValue(v) === false ? Not(IsNull()) : IsNull()),
+    ':isNotEmpty': () => (isTargetMongo ? { $ne: '' } : Not(Equal(''))),
+    ':isEmpty': () => (isTargetMongo ? '' : Equal('')),
+
+    // --- set membership (exact) ---
+    ':nin': (v) => Not(In(val(v).split(',').map(typecastValue))),
+    ':in': (v) => In(val(v).split(',').map(typecastValue)),
+
+    // --- equality (base follows caseInsensitive; *s strict, *i insensitive) ---
+    ':eqs': eqSensitive,
+    ':eqi': eqInsensitive,
+    ':eq': ci ? eqInsensitive : eqSensitive,
+    ':neqs': not(eqSensitive),
+    ':neqi': not(eqInsensitive),
+    ':neq': ci ? not(eqInsensitive) : not(eqSensitive),
+
+    // --- contains ---
+    ':ncontainss': not(containsS),
+    ':ncontainsi': not(containsI),
+    ':ncontains': ci ? not(containsI) : not(containsS),
+    ':containss': containsS,
+    ':containsi': containsI,
+    ':contains': ci ? containsI : containsS,
+
+    // --- starts ---
+    ':nstartss': not(startsS),
+    ':nstartsi': not(startsI),
+    ':nstarts': ci ? not(startsI) : not(startsS),
+    ':startss': startsS,
+    ':startsi': startsI,
+    ':starts': ci ? startsI : startsS,
+
+    // --- ends ---
+    ':nendss': not(endsS),
+    ':nendsi': not(endsI),
+    ':nends': ci ? not(endsI) : not(endsS),
+    ':endss': endsS,
+    ':endsi': endsI,
+    ':ends': ci ? endsI : endsS,
+
+    // --- like ---
+    ':nlikes': not(likeS),
+    ':nlikei': not(likeI),
+    ':nlike': ci ? not(likeI) : not(likeS),
+    ':likes': likeS,
+    ':likei': likeI,
+    ':like': ci ? likeI : likeS,
+
+    // --- comparison (numbers AND dates) ---
+    ':gt': (v) => MoreThan(v),
+    ':ge': (v) => MoreThanOrEqual(v),
+    ':lt': (v) => LessThan(v),
+    ':le': (v) => LessThanOrEqual(v),
+    ':nbetween': (v) => {
+      const s = v?.split(':')
+      return s?.length == 2 ? Not(Between(s[0], s[1])) : v
+    },
+    ':between': (v) => {
+      const s = v?.split(':')
+      return s?.length == 2 ? Between(s[0], s[1]) : v
+    },
+
+    // --- array (Postgres) ---
+    ':arrayContainedBy': arrayOp('<@', 'arrayContainedByValues'),
+    ':arrayContains': arrayOp('@>', 'arrayContainsValues'),
+    ':overlap': arrayOp('&&', 'overlapValues'),
+
+    // --- jsonb key existence (Postgres) ---
+    ':jsonHasAllKeys': jsonHasArray('?&', 'jsonHasAllKeysValues'),
+    ':jsonHasAnyKey': jsonHasArray('?|', 'jsonHasAnyKeyValues'),
+    ':jsonHasKey': jsonHasKey
+  }
+
+  if (allowRaw) {
+    ops[':raw'] = (v) => Raw((alias) => `${alias} ${v}`)
+  }
+
+  return ops
+}

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/general.ts

@@ -17,6 +17,9 @@ export async function load() {
       multi_tenant: {
         enabled: false,
         query_key: 'tid'
+      },
+      manifest: {
+        enabled: false
       }
     }
   }