@volcanicminds/backend 3.0.1 → 3.1.0

package/lib/api/users/controller/user.ts

@@ -8,17 +8,17 @@ export async function getRoles(_req: FastifyRequest, reply: FastifyReply) {
 }
 
 export async function count(req: FastifyRequest, _reply: FastifyReply) {
-  return req.server['userManager'].countQuery(req.data())
+  return req.server['userManager'].countQuery(req.data(), req.runner)
 }
 
 export async function find(req: FastifyRequest, reply: FastifyReply) {
-  const { headers, records } = await req.server['userManager'].findQuery(req.data())
+  const { headers, records } = await req.server['userManager'].findQuery(req.data(), req.runner)
   return reply.type('application/json').headers(headers).send(records)
 }
 
 export async function findOne(req: FastifyRequest, reply: FastifyReply) {
   const { id } = req.parameters()
-  const user = id ? await req.server['userManager'].retrieveUserById(id) : null
+  const user = id ? await req.server['userManager'].retrieveUserById(id, req.runner) : null
   return user || reply.status(404).send()
 }
 
@@ -35,8 +35,12 @@ export async function create(req: FastifyRequest, reply: FastifyReply) {
     }
   }
 
-  const user = await req.server['userManager'].createUser(data)
-  return user ? entity.User.save(user) : reply.status(400).send(Error('User not creatable'))
+  // Pass req.runner so creation lands in the resolved tenant schema (multi-tenant);
+  // createUser already persists and returns the saved entity, so do NOT re-save via
+  // entity.User.save() — that active-record call always targets the global/public
+  // connection and would both double-write and break tenant isolation.
+  const user = await req.server['userManager'].createUser(data, req.runner)
+  return user || reply.status(400).send(Error('User not creatable'))
 }
 
 export async function update(req: FastifyRequest, reply: FastifyReply) {
@@ -46,7 +50,7 @@ export async function update(req: FastifyRequest, reply: FastifyReply) {
   }
 
   const { id: _id, ...userData } = req.data()
-  return await req.server['userManager'].updateUserById(id, userData)
+  return await req.server['userManager'].updateUserById(id, userData, req.runner)
 }
 
 export async function remove(req: FastifyRequest, reply: FastifyReply) {
@@ -54,7 +58,7 @@ export async function remove(req: FastifyRequest, reply: FastifyReply) {
   if (!id) {
     return reply.status(404).send()
   }
-  return await req.server['userManager'].deleteUser(id)
+  return await req.server['userManager'].deleteUser(id, req.runner)
 }
 
 export async function getCurrentUser(req: FastifyRequest, reply: FastifyReply) {
@@ -74,6 +78,11 @@ export async function getCurrentUser(req: FastifyRequest, reply: FastifyReply) {
   )
 }
 
+// Fields a user is allowed to change on themselves. Everything else (roles,
+// blocked, confirmed, password, externalId, mfa*, ...) is off-limits: spreading the
+// raw body here would let a normal user mass-assign roles:['admin'] and escalate.
+const SELF_EDITABLE_FIELDS = ['username', 'firstName', 'lastName']
+
 export async function updateCurrentUser(req: FastifyRequest, reply: FastifyReply) {
   const user: AuthenticatedUser | undefined = req.user
   const id = user?.getId()
@@ -81,8 +90,12 @@ export async function updateCurrentUser(req: FastifyRequest, reply: FastifyReply
     return reply.status(403).send('Cannot update current user')
   }
 
-  const { id: _id, ...userData } = req.data()
-  return await req.server['userManager'].updateUserById(id, userData)
+  const incoming = req.data() || {}
+  const userData: any = {}
+  for (const f of SELF_EDITABLE_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(incoming, f)) userData[f] = incoming[f]
+  }
+  return await req.server['userManager'].updateUserById(id, userData, req.runner)
 }
 
 export async function isAdmin(req: FastifyRequest, reply: FastifyReply) {
@@ -127,11 +140,11 @@ export async function resetMfaByAdmin(req: FastifyRequest, reply: FastifyReply)
   const { id } = req.parameters()
 
   if (!req.hasRole(roles.admin)) {
-    return reply.status(403).send(new Error('Only admins can reset MFA'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Only admins can reset MFA' })
   }
 
   if (!id) {
-    return reply.status(400).send(new Error('Missing user id'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing user id' })
   }
 
   try {
@@ -139,7 +152,7 @@ export async function resetMfaByAdmin(req: FastifyRequest, reply: FastifyReply)
     return { ok: true }
   } catch (error) {
     req.log.error(error)
-    return reply.status(500).send(new Error('Failed to reset MFA'))
+    return reply.status(500).send({ statusCode: 500, error: 'Internal Server Error', message: 'Failed to reset MFA' })
   }
 }
 
@@ -150,29 +163,29 @@ export async function resetPasswordByAdmin(req: FastifyRequest, reply: FastifyRe
   }
 
   if (!req.hasRole(roles.admin)) {
-    return reply.status(403).send(new Error('Only admins can reset user passwords'))
+    return reply.status(403).send({ statusCode: 403, error: 'Forbidden', message: 'Only admins can reset user passwords' })
   }
 
   const { id } = req.parameters()
   if (!id) {
-    return reply.status(400).send(new Error('Missing user id'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing user id' })
   }
 
   const { password } = req.data()
   if (!password) {
-    return reply.status(400).send(new Error('Missing password in request body'))
+    return reply.status(400).send({ statusCode: 400, error: 'Bad Request', message: 'Missing password in request body' })
   }
 
   try {
-    const user = await req.server['userManager'].retrieveUserById(id)
+    const user = await req.server['userManager'].retrieveUserById(id, req.runner)
     if (!user) {
-      return reply.status(404).send(new Error('User not found'))
+      return reply.status(404).send({ statusCode: 404, error: 'Not Found', message: 'User not found' })
     }
 
-    await req.server['userManager'].resetPassword(user, password)
+    await req.server['userManager'].resetPassword(user, password, req.runner)
     return { ok: true }
   } catch (error) {
     req.log.error(error)
-    return reply.status(500).send(new Error('Failed to reset password'))
+    return reply.status(500).send({ statusCode: 500, error: 'Internal Server Error', message: 'Failed to reset password' })
   }
 }

package/lib/api/users/routes.ts

@@ -46,6 +46,9 @@ export default {
     {
       method: 'GET',
       path: '/roles',
+      // Authenticated-only BY DESIGN (any logged-in user). `roles: []` + the
+      // isAuthenticated middleware => 401 anonymous, 200 authenticated. Do NOT make
+      // this public: it exposes the role taxonomy, which anonymous callers don't need.
       roles: [],
       handler: 'user.getRoles',
       middlewares: ['global.isAuthenticated'],

package/lib/config/plugins.ts

@@ -39,8 +39,11 @@ export default [
   },
   {
     name: 'rateLimit',
-    enable: false,
-    options: {}
+    // Registered with `global: false` so it limits ONLY routes that opt in via `config.rateLimit`
+    // (currently the MFA endpoints, see S11). Turning on global throttling + per-route limits on
+    // login/forgot/reset is tracked separately under S5.
+    enable: true,
+    options: { global: false }
   },
   {
     name: 'helmet',

package/lib/database/typeorm/embedded.ts

@@ -0,0 +1,173 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Embedded database (PGlite) wiring for TypeORM.
+ *
+ * PGlite is a WASM build of Postgres that runs in-process — no external server,
+ * no Docker. It is the "plug & play" engine for development, tests, demos and
+ * CLIs. Production keeps using a real Postgres server (`type: 'postgres'`).
+ *
+ * The whole feature is OPT-IN and the heavy WASM dependencies are OPTIONAL:
+ * they are only `import()`-ed when the consumer sets `type: 'pglite'`, so a
+ * pure-Postgres deployment never pays for them.
+ *
+ * Consumer config (database.default):
+ *   {
+ *     type: 'pglite',
+ *     dataDir: './.pglite',      // omit -> in-memory (ephemeral); a path -> persisted on disk
+ *     vector: true,              // or { } — enable pgvector (embeddings / similarity search)
+ *     extensions: ['pgcrypto'],  // extra PGlite contrib extensions to enable
+ *     relaxedDurability: true,   // faster writes, weaker fsync guarantees (great for tests)
+ *     synchronize: true,
+ *     ...standard TypeORM options (entities, namingStrategy, ...)
+ *   }
+ */
+import * as log from './util/logger.js'
+
+// PGlite needs `CREATE EXTENSION "<sql-name>"`, whose name often differs from the
+// JS import identifier (e.g. import `uuid_ossp` -> SQL `uuid-ossp`).
+const EXTENSION_SQL_NAME: Record<string, string> = {
+  uuid_ossp: 'uuid-ossp',
+  vector: 'vector'
+}
+
+// `uuid-ossp` is always enabled: the framework entities (User/Tenant/Token/Change)
+// use `@PrimaryGeneratedColumn('uuid')` which calls uuid_generate_v4() at synchronize.
+const ALWAYS_ON_EXTENSIONS = ['uuid_ossp']
+
+export interface EmbeddedState {
+  enabled: boolean
+  vector: boolean
+  dataDir?: string
+  persisted: boolean
+  extensions: string[]
+}
+
+function sqlName(ext: string): string {
+  return EXTENSION_SQL_NAME[ext] || ext
+}
+
+async function importExtension(name: string): Promise<any> {
+  // pgvector ships as a separate package (peer-pinned to the PGlite version);
+  // every other extension is a standard PGlite contrib module.
+  if (name === 'vector') {
+    const mod: any = await import('@electric-sql/pglite-pgvector')
+    return mod.vector
+  }
+  const mod: any = await import(`@electric-sql/pglite/contrib/${name}`)
+  return mod[name] ?? mod.default ?? mod
+}
+
+/**
+ * Detects whether the given options ask for the embedded engine.
+ */
+export function isEmbedded(options: any): boolean {
+  return options?.type === 'pglite'
+}
+
+/**
+ * Rewrites `options` in place so TypeORM treats them as a standard Postgres
+ * DataSource backed by a PGlite driver, registers the required extensions and
+ * creates them BEFORE any schema synchronization runs.
+ *
+ * Returns the resolved embedded state (also published on `global.embeddedDatabase`).
+ */
+export async function setupEmbedded(options: any): Promise<EmbeddedState> {
+  let PGliteDriver: any
+  let getPGliteInstance: any
+  try {
+    ;({ PGliteDriver, getPGliteInstance } = await import('typeorm-pglite'))
+  } catch {
+    throw new Error(
+      "[Volcanic-Embedded] type 'pglite' requires optional dependencies. Install them with:\n" +
+        '  npm install typeorm-pglite @electric-sql/pglite' +
+        " @electric-sql/pglite-pgvector\n(the last one only if you use 'vector: true')."
+    )
+  }
+
+  // --- Resolve config knobs and strip them from the TypeORM options ---
+  const wantVector = !!options.vector
+  const extraExtensions: string[] = Array.isArray(options.extensions) ? options.extensions : []
+  const dataDir: string | undefined = options.dataDir
+  const relaxedDurability: boolean = options.relaxedDurability ?? !dataDir // default relaxed for in-memory
+
+  const extensionNames = Array.from(
+    new Set([...ALWAYS_ON_EXTENSIONS, ...extraExtensions, ...(wantVector ? ['vector'] : [])])
+  )
+
+  delete options.vector
+  delete options.extensions
+  delete options.dataDir
+  delete options.relaxedDurability
+
+  // --- Load extension modules and build the PGlite `extensions` map ---
+  const extensions: Record<string, any> = {}
+  for (const name of extensionNames) {
+    try {
+      extensions[name] = await importExtension(name)
+    } catch (err: any) {
+      if (name === 'vector') {
+        throw new Error(
+          "[Volcanic-Embedded] 'vector: true' requires '@electric-sql/pglite-pgvector'. " +
+            'Install it with: npm install @electric-sql/pglite-pgvector'
+        )
+      }
+      throw new Error(`[Volcanic-Embedded] Unknown PGlite extension '${name}': ${err?.message || err}`)
+    }
+  }
+
+  // --- Build the driver. The constructor passes these options to PGlite.create() ---
+  const pgliteOptions: any = { extensions, relaxedDurability }
+  if (dataDir) pgliteOptions.dataDir = dataDir
+
+  const driver = new PGliteDriver(pgliteOptions).driver
+
+  // Make TypeORM use the Postgres dialect over the PGlite-backed pool.
+  options.type = 'postgres'
+  options.driver = driver
+
+  // --- Create extensions BEFORE synchronize() (which may run during initialize()) ---
+  // getPGliteInstance() eagerly creates the singleton with the options set above.
+  const pg = await getPGliteInstance()
+  for (const name of extensionNames) {
+    await pg.query(`CREATE EXTENSION IF NOT EXISTS "${sqlName(name)}"`)
+  }
+
+  const state: EmbeddedState = {
+    enabled: true,
+    vector: wantVector,
+    dataDir,
+    persisted: !!dataDir,
+    extensions: extensionNames
+  }
+  ;(global as any).embeddedDatabase = state
+
+  log.warn(
+    `[Volcanic-Embedded] PGlite engine active (${state.persisted ? `persisted @ ${dataDir}` : 'in-memory'})` +
+      `, extensions: ${extensionNames.join(', ')}`
+  )
+
+  return state
+}
+
+/**
+ * True when the current process is running on the embedded PGlite engine.
+ * Used by the tenant manager to avoid destroying the shared PGlite singleton.
+ */
+export function isEmbeddedActive(): boolean {
+  return !!(global as any).embeddedDatabase?.enabled
+}
+
+/**
+ * Gracefully closes the shared PGlite instance (no-op on real Postgres).
+ * Useful at the end of a test suite to release the WASM instance.
+ */
+export async function closeEmbedded(): Promise<void> {
+  if (!isEmbeddedActive()) return
+  try {
+    const { PGliteInstance }: any = await import('typeorm-pglite')
+    await PGliteInstance.close()
+  } catch {
+    /* optional dep absent — nothing to close */
+  }
+  ;(global as any).embeddedDatabase = undefined
+}

package/lib/database/typeorm/entities/user.ts

@@ -27,6 +27,8 @@ export abstract class User extends BaseEntity {
   abstract mfaSecret: string
   abstract mfaType: string
   abstract mfaRecoveryCodes: string[]
+  // Absolute TOTP time-step last consumed, used to reject replayed codes within their validity window.
+  abstract mfaLastUsedCounter: number
 
   abstract setId(id: any): void
   abstract getId(): any

package/lib/database/typeorm/loader/tenantManager.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { DataSource, EntityManager } from 'typeorm'
 import { Tenant } from '../entities/tenant.js'
+import { isEmbeddedActive } from '../embedded.js'
 
 export class TenantManager {
   constructor(private dataSource: DataSource) {}
@@ -146,7 +147,13 @@ export class TenantManager {
           name: `sync_${safeSchema}_${Date.now()}`
         })
         await tenantDs.initialize()
-        await tenantDs.destroy()
+        // On the embedded PGlite engine every DataSource shares ONE WASM instance
+        // (PGlitePool.end() -> PGliteInstance.close()), so destroying this ephemeral
+        // one would close the PRIMARY connection too. Leave it alive: it only holds a
+        // reference to the shared singleton, which the app keeps using.
+        if (!isEmbeddedActive()) {
+          await tenantDs.destroy()
+        }
 
         if ((global as any).log?.i)
           (global as any).log.info(`[TenantManager] Schema ${safeSchema} synchronized successfully`)

package/lib/database/typeorm/loader/userManager.ts

@@ -138,7 +138,12 @@ export async function updateUserById(id: string, user: typeof global.entity.User
     if (!userEx) {
       throw new ServiceError('User not found', 404)
     }
-    const merged = repo.merge(userEx, user)
+    // `password` must NEVER be set through the generic update path: it would be
+    // stored in plaintext, bypassing bcrypt (and breaking login). Credential
+    // changes go through changePassword / resetPassword, which hash. Drop it here
+    // for ALL callers (admin PUT /users/:id included).
+    const { password: _ignorePassword, ...safe } = (user as any) || {}
+    const merged = repo.merge(userEx, safe)
     return repo.save(merged)
   } catch (error) {
     throw error

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
+}