@rapidrest/service-core 1.8.0 → 2.1.0

package/dist/lib/models/ModelUtils.js

@@ -4,23 +4,114 @@ import "reflect-metadata";
 import { isEmpty } from "lodash-es";
 import { RecoverableBaseEntity } from "./RecoverableBaseEntity.js";
 import { ApiErrorMessages, ApiErrors } from "../ApiErrors.js";
+import { getColumnMetadata } from "../decorators/PersistenceDecorators.js";
 const logger = Logger();
-const REGEX_QUERY_PARAM_VALUE = new RegExp(/^([a-zA-Z]+)\((.*)\)$/, "i");
+// `[\s\S]*` (rather than `.*`) so an operand containing a newline is still taken verbatim, between the first `(`
+// and the final `)`, instead of silently falling through to the bare-value path.
+const REGEX_QUERY_PARAM_VALUE = /^([a-zA-Z]+)\(([\s\S]*)\)$/;
 // Anchored at the start so these only match the intended reserved parameter names/prefixes and not any
 // field that merely contains one as a substring (e.g. "sortOrder", "rateLimit", "packageId", "homepage").
 const REGEX_RESERVED_QUERY_PARAMS = new RegExp("^(jwt_|oauth_|auth_|cache).*", "i");
 const REGEX_QUERY_LIMITS = new RegExp("^(limit|page|sort)$", "i");
 const REGEX_QUERY_SORT_STRING = new RegExp(/^\{.*\}$/, "i");
-// Apparently calling JSON.stringify on RegExp returns an empty set. So the recommended way to
-// overcome this is by adding a `toJSON` method that uses the `toString` instead which will
-// give us what we want.
-RegExp.prototype.toJSON = RegExp.prototype.toString;
+/** Default number of records returned by a search query when no `limit` is specified. Shared by both backends. */
+export const DEFAULT_PAGE_SIZE = 100;
+/** Maximum number of records a search query may request via `limit`, regardless of provider. Shared by both backends. */
+export const MAX_PAGE_SIZE = 1000;
+/** The operator names recognized by the `op(value)` query syntax. Anything else is rejected with a 400. */
+const KNOWN_OPERATORS = new Set([
+    "eq",
+    "ne",
+    "not",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "nin",
+    "like",
+    "regex",
+    "range",
+    "exists",
+]);
+/** Maximum nesting depth accepted for a `$or` array or a `QueryNode` tree, to bound recursion. */
+const MAX_QUERY_DEPTH = 8;
+/** Maximum number of OR branches / predicate nodes a single query may expand to, to bound total work. */
+const MAX_QUERY_NODES = 256;
+/**
+ * A search query value that is compared exactly as given rather than parsed as `op(value)` syntax. Create one via
+ * `ModelUtils.literal()`. Only code can produce one: a client's query string or `q` JSON can only ever yield plain
+ * strings, arrays and objects.
+ */
+export class QueryLiteral {
+    constructor(value, op = "eq") {
+        this.op = op;
+        this.value = value;
+        Object.freeze(this);
+    }
+    /**
+     * Serializes under a `$`-prefixed key so a query containing a literal hashes (e.g. for `RepoUtils`' result
+     * cache) differently from any plain value, and so a client echoing the same JSON back is rejected by the
+     * query builders' operator-injection guard instead of being mistaken for a literal.
+     */
+    toJSON() {
+        return { $literal: { op: this.op, value: this.value } };
+    }
+}
 /**
  * Utility class for working with data model classes.
  *
  * @author Jean-Philippe Steinmetz
  */
 export class ModelUtils {
+    /**
+     * Marks `value` as a literal search value for `buildSearchQuery()` (and so `RepoUtils.find/count/truncate`),
+     * so it is compared exactly as given instead of being parsed as `op(value)` syntax. Use this whenever a query
+     * value comes from outside the code (a client, an email header, an iCalendar UID, a display name): a raw string
+     * such as `ne(x)` would otherwise be read as an operator, `Support(EU)` would be rejected as an unknown
+     * operator, `me`/`null` would be substituted, and a comma inside an `in()` list would split the value.
+     *
+     * The value is not type-coerced, so pass it with the column's real type (number, boolean, `Date`, string).
+     * `null` still compiles to `IS NULL` on SQL. Object values are still checked for hidden `$`/dotted keys.
+     *
+     * ```
+     * repoUtils.find({ messageId: ModelUtils.literal(header) });
+     * repoUtils.find({ uid: ModelUtils.literal(["a,b", "c"], "in") });
+     * repoUtils.find({ name: ModelUtils.literal(displayName, "ne") });
+     * repoUtils.find({ size: ModelUtils.literal([10, 20], "range") });
+     * ```
+     *
+     * @param value The value to compare against. An array for `in`, `nin` and `range` (exactly two elements).
+     * @param op The comparison to apply. Defaults to `eq`.
+     */
+    static literal(value, op = "eq") {
+        return new QueryLiteral(value, op);
+    }
+    /**
+     * Splits the operand of a list operator (`in()`, `nin()`, `range()`) on unescaped commas. `\,` yields a literal
+     * comma and `\\` a literal backslash; a backslash before any other character (or at the end) is kept as is.
+     */
+    static splitListOperand(operand) {
+        const parts = [];
+        let current = "";
+        for (let i = 0; i < operand.length; i++) {
+            const ch = operand[i];
+            const next = operand[i + 1];
+            if (ch === "\\" && (next === "," || next === "\\")) {
+                current += next;
+                i++;
+            }
+            else if (ch === ",") {
+                parts.push(current);
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+        }
+        parts.push(current);
+        return parts;
+    }
     /**
      * Provides the `typeorm` module to use when building SQL queries. This is called automatically when a SQL
      * datasource connection is established.
@@ -95,6 +186,41 @@ export class ModelUtils {
         ModelUtils.readOnlyPropertyCache.set(modelClass, results);
         return results;
     }
+    /**
+     * Resolves the declared type of a model property, from an explicit `type` override on `@Column` or (falling
+     * back) the TypeScript design-time type reflected at decoration time. Returns `undefined` when `modelClass`
+     * is not provided or declares no column metadata for `property` - callers must fall back to a heuristic in
+     * that case, the same way `coerceOperand` does.
+     */
+    static resolvePropertyType(modelClass, property) {
+        if (!modelClass || !property) {
+            return undefined;
+        }
+        let byProperty = ModelUtils.columnTypeCache.get(modelClass);
+        if (!byProperty) {
+            byProperty = new Map();
+            for (const column of getColumnMetadata(modelClass)) {
+                byProperty.set(column.propertyName, column.options.type ?? column.designType);
+            }
+            ModelUtils.columnTypeCache.set(modelClass, byProperty);
+        }
+        return byProperty.get(property);
+    }
+    /**
+     * Returns the set of property names a `sort` query parameter may reference for `modelClass`, or `undefined`
+     * if `modelClass` declares no column metadata at all - in which case sort keys are accepted unvalidated
+     * (the same permissive fallback `coerceOperand` uses when no type metadata is available).
+     */
+    static getSortablePropertyNames(modelClass) {
+        if (!modelClass) {
+            return undefined;
+        }
+        const columns = getColumnMetadata(modelClass);
+        if (columns.length === 0) {
+            return undefined;
+        }
+        return new Set(columns.map((c) => c.propertyName));
+    }
     /**
      * Builds a query object for use with `find` functions of the given repository for retrieving objects matching the
      * specified unique identifier.
@@ -190,6 +316,212 @@ export class ModelUtils {
         }
         return { $or: query };
     }
+    /**
+     * Resolves a raw, single-value operand (already unwrapped from any `op(...)` syntax) to a properly-typed
+     * native value: `me` is substituted for the requesting user's uid, and the result is otherwise coerced
+     * according to `property`'s declared type on `modelClass` (falling back to a JSON/Date/string heuristic when
+     * no column metadata is available for it). Used for every scalar operand on both backends - including each
+     * element of `in()`/`nin()`/`range()` - so type coercion, `me` substitution and operator-injection rejection
+     * are applied uniformly everywhere a client-supplied value enters a query, on both backends.
+     *
+     * @throws {ApiError} If `raw` is `me` with no authenticated user, if a typed column rejects an unparseable
+     * operand, or if the coerced value contains a hidden MongoDB operator/dotted key.
+     */
+    static coerceOperand(raw, modelClass, property, user) {
+        if (raw === "me") {
+            if (!user) {
+                throw new ApiError(ApiErrors.SEARCH_INVALID_ME_REFERENCE, 403, ApiErrorMessages.SEARCH_INVALID_ME_REFERENCE);
+            }
+            return user.uid;
+        }
+        const type = ModelUtils.resolvePropertyType(modelClass, property);
+        let result;
+        if (type !== undefined) {
+            result = ModelUtils.coerceToType(raw, type, property);
+        }
+        else {
+            // No column metadata available for this property - fall back to the legacy heuristic: try JSON
+            // (covers numbers/booleans/null/objects/arrays), then a date, then leave it as a plain string. This
+            // is the one path that still risks the "Mar 5" ambiguity (a text value that happens to look like a
+            // date gets silently reinterpreted as one) - kept only for callers that don't supply column
+            // metadata (e.g. `modelClass` is undefined, or the property isn't declared via `@Column`). A
+            // string-typed column skips the Date attempt entirely once metadata IS available - see
+            // `coerceToType`.
+            try {
+                result = JSON.parse(raw);
+            }
+            catch (err) {
+                const asDate = new Date(raw);
+                result = isNaN(asDate.valueOf()) ? raw : asDate;
+            }
+        }
+        ModelUtils.assertNoOperatorInjection(result);
+        return result;
+    }
+    /**
+     * Coerces a raw operand string to `type` (an explicit `@Column({type})` override or a reflected TypeScript
+     * design type), rejecting operands that don't parse as that type rather than silently guessing.
+     */
+    static coerceToType(raw, type, property) {
+        if (raw === "null") {
+            // The JSON `null` literal is valid for any declared type (e.g. `eq(null)`); the eq/ne callers
+            // special-case the resulting `null` via IsNull()/$eq:null rather than this function.
+            return null;
+        }
+        if (type === Date || type === "date" || type === "datetime" || type === "timestamp") {
+            const value = new Date(raw);
+            if (isNaN(value.valueOf())) {
+                throw ModelUtils.invalidOperandError(raw, property, "date");
+            }
+            return value;
+        }
+        if (type === Number ||
+            ["int", "integer", "float", "double", "decimal", "numeric", "bigint", "smallint", "tinyint"].includes(type)) {
+            const value = Number(raw);
+            if (raw.trim() === "" || isNaN(value)) {
+                throw ModelUtils.invalidOperandError(raw, property, "number");
+            }
+            return value;
+        }
+        if (type === Boolean || type === "boolean" || type === "bool") {
+            const lower = raw.toLowerCase();
+            if (lower === "true")
+                return true;
+            if (lower === "false")
+                return false;
+            throw ModelUtils.invalidOperandError(raw, property, "boolean");
+        }
+        // String (and any other/unrecognized declared type): never attempt Date/number parsing - this is what
+        // fixes the "Mar 5" bug, where a text search value that happened to look like a date was silently
+        // reinterpreted as one.
+        return raw;
+    }
+    static invalidOperandError(raw, property, type) {
+        return new ApiError(ApiErrors.SEARCH_INVALID_OPERAND_TYPE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_OPERAND_TYPE, {
+            value: raw,
+            field: property,
+            type,
+        }));
+    }
+    /**
+     * Coerces an already-typed AST predicate value (see `QueryNode`): a string operand is routed through
+     * `coerceOperand` (type coercion, `me` substitution, injection guard) exactly like the flat `op(value)`
+     * form; any other value is assumed to already be correctly typed by the caller and is only checked for a
+     * hidden operator/dotted key. With `literal` set, a string operand is kept exactly as given too.
+     */
+    static coerceNodeValue(value, modelClass, property, user, literal = false) {
+        if (typeof value === "string" && !literal) {
+            return ModelUtils.coerceOperand(value, modelClass, property, user);
+        }
+        ModelUtils.assertNoOperatorInjection(value);
+        return value;
+    }
+    /**
+     * Recursively verifies that no key in the given value (at any depth, including keys of objects nested inside
+     * arrays) is a MongoDB operator (starts with `$`) or uses dot-notation field addressing (contains `.`). Client
+     * input is only ever meant to supply plain field values/comparison operands — never raw Mongo query operators —
+     * so any such key indicates an attempt to inject arbitrary query behavior (e.g. `$where`, `$expr`, or reaching
+     * into a field the API doesn't expose via dot-notation). Applied to every coerced operand on both backends -
+     * `Equal(JSON.parse(param))`-style SQL operators are constructed by TypeORM rather than interpreted from the
+     * operand directly, but a client-supplied object operand should still be rejected consistently on both
+     * backends rather than left to whatever TypeORM happens to do with it.
+     *
+     * @param value The value to check, typically a parsed query parameter.
+     * @throws {ApiError} If an operator-like or dotted key is found anywhere in `value`.
+     */
+    static assertNoOperatorInjection(value) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                ModelUtils.assertNoOperatorInjection(item);
+            }
+        }
+        else if (value && typeof value === "object") {
+            for (const key of Object.keys(value)) {
+                if (key.startsWith("$") || key.includes(".")) {
+                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                }
+                ModelUtils.assertNoOperatorInjection(value[key]);
+            }
+        }
+    }
+    /**
+     * Best-effort check for regex patterns vulnerable to catastrophic backtracking (ReDoS): patterns that are
+     * unreasonably long, that contain a quantified group whose contents are themselves quantified (e.g. `(a+)+`,
+     * `(a*)*`), or a quantified group containing alternation (e.g. `(a|a)*`, `(a|ab)*`) - both classic shapes
+     * that cause exponential backtracking in JS's (and SQLite's, since the `regex()` SQL operator is backed by a
+     * JS `RegExp` - see `registerRegexpFunction` in `TypeOrmSupport.ts`) regex engine. This is not an exhaustive
+     * defense; it catches the common cases a client would realistically send. `like()` no longer accepts raw
+     * regex (it compiles glob syntax instead - see `globToRegExpSource`), so this now guards only the explicit
+     * `regex()` operator.
+     *
+     * Public so the SQLite `REGEXP` custom function (registered per-connection in `TypeOrmSupport.ts`) can apply
+     * the same guard at query-execution time, since a pattern reaching that function didn't necessarily pass
+     * through this class's own query builders (e.g. a raw `Raw()`/QueryBuilder use elsewhere).
+     */
+    static isUnsafeRegexPattern(pattern) {
+        if (pattern.length > ModelUtils.MAX_PATTERN_LENGTH) {
+            return true;
+        }
+        return /\([^()]*[+*]\)[+*{]/.test(pattern) || /\([^()]*\|[^()]*\)[+*{]/.test(pattern);
+    }
+    /**
+     * Translates a client-supplied glob pattern (`*` = any sequence, `?` = any single character) to a SQL
+     * `LIKE` pattern. Any `%`/`_` already present in the glob source is passed through unescaped (matching this
+     * operator's pre-existing behavior before glob support was added) - a client wanting to match a literal `%`
+     * or `_` cannot fully escape it, a narrow, documented limitation rather than a regression.
+     */
+    static globToLike(glob) {
+        let result = "";
+        for (const ch of glob) {
+            if (ch === "*")
+                result += "%";
+            else if (ch === "?")
+                result += "_";
+            else
+                result += ch;
+        }
+        return result;
+    }
+    /**
+     * Translates a client-supplied glob pattern into a fully-escaped, anchored regular expression source string
+     * for use with MongoDB's `$regex`, so glob syntax behaves identically on both backends.
+     */
+    static globToRegExpSource(glob) {
+        let result = "";
+        for (const ch of glob) {
+            if (ch === "*")
+                result += ".*";
+            else if (ch === "?")
+                result += ".";
+            else
+                result += StringUtils.escapeRegExp(ch);
+        }
+        return `^${result}$`;
+    }
+    /**
+     * Compiles a validated `regex()` pattern to a driver-appropriate case-insensitive match expression. Only
+     * PostgreSQL (`~*`), MySQL/MariaDB (`REGEXP`) and the `better-sqlite3` driver (via a `REGEXP` function
+     * registered per-connection - see `registerRegexpFunction` in `TypeOrmSupport.ts`) are supported; any other
+     * driver rejects the operator outright rather than silently falling back to something incorrect.
+     */
+    static compileSqlRegex(pattern, driverType) {
+        const { Raw } = ModelUtils.orm;
+        // TypeORM registers a `Raw()` expression's named parameters query-wide, so two regex() conditions in one
+        // query (on different fields, or ANDed on the same field) must not share a parameter name.
+        const name = `rrst_regex_${++ModelUtils.rawParamSeq}`;
+        switch (driverType) {
+            case "postgres":
+            case "cockroachdb":
+                return Raw((alias) => `${alias} ~* :${name}`, { [name]: pattern });
+            case "mysql":
+            case "mariadb":
+            case "better-sqlite3":
+            case "sqlite":
+                return Raw((alias) => `${alias} REGEXP :${name}`, { [name]: pattern });
+            default:
+                throw new ApiError(ApiErrors.SEARCH_OPERATOR_NOT_SUPPORTED, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_OPERATOR_NOT_SUPPORTED, { operator: "regex" }));
+        }
+    }
     /**
      * Given a string containing a parameter value and/or a comparison operation return a TypeORM compatible find value.
      * e.g.
@@ -198,7 +530,7 @@ export class ModelUtils {
      *
      * @param param
      */
-    static getQueryParamValue(param) {
+    static getQueryParamValue(param, modelClass, property, user, exactMatch, driverType) {
         if (typeof param === "string") {
             const { Equal, MoreThan, MoreThanOrEqual, In, ILike, LessThan, LessThanOrEqual, Not, Between, IsNull } = ModelUtils.orm;
             // The value of each param can optionally have the operation included. If no operator is included Eq is
@@ -207,140 +539,103 @@ export class ModelUtils {
             const matches = param.match(REGEX_QUERY_PARAM_VALUE);
             if (matches) {
                 const opName = matches[1].toLowerCase();
-                let value = matches[2];
-                try {
-                    // Attempt to parse the value to a native type
-                    value = JSON.parse(matches[2]);
-                }
-                catch (err) {
-                    // If an error occurred it's because the value is a string or date, not another type.
-                    value = new Date(matches[2]);
-                    if (isNaN(value)) {
-                        value = matches[2];
-                    }
+                const operand = matches[2];
+                if (!KNOWN_OPERATORS.has(opName)) {
+                    // The HTTP escape hatch is `eq(...)`: `?title=eq(Report(final))` still parses correctly here
+                    // since REGEX_QUERY_PARAM_VALUE is greedy, so a field value that happens to look like
+                    // `name(args)` remains searchable. Code should use `ModelUtils.literal()` instead.
+                    throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: matches[1] }));
                 }
                 switch (opName) {
-                    case "eq":
+                    case "eq": {
+                        const value = ModelUtils.coerceOperand(operand, modelClass, property, user);
                         // `Equal(null)` compiles to `column = NULL`, which standard SQL NULL semantics always
                         // evaluate to unknown/false (never true), regardless of the column's actual value -
                         // TypeORM requires the dedicated `IsNull()` operator to produce `column IS NULL`.
                         return value === null ? IsNull() : Equal(value);
+                    }
                     case "gt":
-                        return MoreThan(value);
+                        return MoreThan(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "gte":
-                        return MoreThanOrEqual(value);
+                        return MoreThanOrEqual(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "in": {
-                        // Split the raw match text, not `value`: a comma-joined list like "1,5" can itself parse
-                        // as a valid `Date` above (e.g. "1,5" -> Jan 5), leaving `value` a Date with no `.split()`.
-                        const args = matches[2].split(",");
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return In(args);
                     }
                     case "like":
-                        return ILike(value);
+                        return ILike(ModelUtils.globToLike(operand));
+                    case "regex": {
+                        if (ModelUtils.isUnsafeRegexPattern(operand)) {
+                            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                        }
+                        return ModelUtils.compileSqlRegex(operand, driverType);
+                    }
                     case "lt":
-                        return LessThan(value);
+                        return LessThan(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "lte":
-                        return LessThanOrEqual(value);
+                        return LessThanOrEqual(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "ne":
-                    case "not":
+                    case "not": {
                         // Same NULL-semantics gap as "eq" above, mirrored: `Not(null)` compiles to
                         // `column != NULL`, which SQL also always evaluates to unknown/false - the correct
-                        // "has a value" query is `Not(IsNull())`, producing `column IS NOT NULL`. Confirmed via
-                        // a real-database (SQLite) test in @rapidmx/restapi that `ne(null)`/`not(null)`
-                        // silently matched zero rows before this fix, even though the identical query already
-                        // worked correctly against MongoDB (`$ne: null` has no equivalent gap there).
+                        // "has a value" query is `Not(IsNull())`, producing `column IS NOT NULL`.
+                        const value = ModelUtils.coerceOperand(operand, modelClass, property, user);
                         return value === null ? Not(IsNull()) : Not(value);
+                    }
                     case "nin": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return Not(In(args));
                     }
                     case "range": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = ModelUtils.splitListOperand(operand);
                         if (args.length !== 2) {
                             const msg = StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
-                                value,
+                                value: operand,
                                 length: args.length,
                             });
                             throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, msg);
                         }
-                        try {
-                            // Attempt to parse the range values to native types
-                            return Between(JSON.parse(args[0]), JSON.parse(args[1]));
-                        }
-                        catch (err) {
-                            return Between(args[0], args[1]);
-                        }
+                        const lower = ModelUtils.coerceOperand(args[0], modelClass, property, user);
+                        const upper = ModelUtils.coerceOperand(args[1], modelClass, property, user);
+                        return Between(lower, upper);
+                    }
+                    case "exists": {
+                        const wantsExists = operand.trim().toLowerCase() === "true";
+                        return wantsExists ? Not(IsNull()) : IsNull();
                     }
                     default:
-                        return Equal(value);
+                        // Unreachable: opName was already validated against KNOWN_OPERATORS above.
+                        throw new Error(`Unhandled search operator: ${opName}`);
                 }
             }
             else {
-                try {
-                    // Attempt to parse the value to a native type
-                    return Equal(JSON.parse(param));
+                const coerced = ModelUtils.coerceOperand(param, modelClass, property, user);
+                if (!exactMatch && typeof coerced === "string") {
+                    return ILike(`%${coerced}%`);
                 }
-                catch (err) {
-                    // If an error occurred it's because the value is a string, not another type.
-                    const date = new Date(param);
-                    return Equal(!isNaN(date.valueOf()) ? date : param);
-                }
-            }
-        }
-        else {
-            return param;
-        }
-    }
-    /**
-     * Recursively verifies that no key in the given value (at any depth, including keys of objects nested inside
-     * arrays) is a MongoDB operator (starts with `$`) or uses dot-notation field addressing (contains `.`). Client
-     * input is only ever meant to supply plain field values/comparison operands — never raw Mongo query operators —
-     * so any such key indicates an attempt to inject arbitrary query behavior (e.g. `$where`, `$expr`, or reaching
-     * into a field the API doesn't expose via dot-notation).
-     *
-     * @param value The value to check, typically a parsed query parameter.
-     * @throws {ApiError} If an operator-like or dotted key is found anywhere in `value`.
-     */
-    static assertNoOperatorInjection(value) {
-        if (Array.isArray(value)) {
-            for (const item of value) {
-                ModelUtils.assertNoOperatorInjection(item);
+                return coerced === null ? IsNull() : Equal(coerced);
             }
         }
-        else if (value && typeof value === "object") {
-            for (const key of Object.keys(value)) {
-                if (key.startsWith("$") || key.includes(".")) {
-                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
-                }
-                ModelUtils.assertNoOperatorInjection(value[key]);
-            }
+        else if (param instanceof QueryLiteral) {
+            return ModelUtils.compilePredicateSQLOperator(param.op, param.value, modelClass, property, user, driverType, true);
         }
-    }
-    /**
-     * Best-effort check for regex patterns vulnerable to catastrophic backtracking (ReDoS). Rejects patterns that
-     * are unreasonably long, or that contain a quantified group whose contents are themselves quantified (e.g.
-     * `(a+)+`, `(a*)*`) — the classic shape that causes exponential backtracking in JS's regex engine. This is not
-     * an exhaustive defense; it catches the common cases a client would realistically send.
-     *
-     * @param pattern The user-supplied `like()` pattern.
-     */
-    static isUnsafeRegexPattern(pattern) {
-        if (pattern.length > ModelUtils.MAX_LIKE_PATTERN_LENGTH) {
-            return true;
+        else {
+            // A non-string value only reaches here when the caller already parsed the raw query into native
+            // types itself (mirrors the equivalent Mongo case below) - still validated for a hidden operator.
+            ModelUtils.assertNoOperatorInjection(param);
+            // A bare `null` in a TypeORM `where` throws by default rather than matching `IS NULL`; Mongo matches it.
+            return param === null ? ModelUtils.orm.IsNull() : param;
         }
-        return /\([^()]*[+*]\)[+*{]/.test(pattern);
     }
     /**
      * Given a string containing a parameter value and/or a comparison operation return a MongoDB compatible find value.
      * e.g.
      * Given the string "myvalue" will return an `"myvalue"` object.
-     * Given the string "not(myvalue)" will return an `{ $not: "myvalue" }` object.
+     * Given the string "not(myvalue)" will return an `{ $ne: "myvalue" }` object.
      *
      * @param param
      */
-    static getQueryParamValueMongo(param) {
+    static getQueryParamValueMongo(param, modelClass, property, user, exactMatch) {
         if (typeof param === "string") {
             // The value of each param can optionally have the operation included. If no operator is included Eq is
             // always assumed.
@@ -348,98 +643,90 @@ export class ModelUtils {
             const matches = param.match(REGEX_QUERY_PARAM_VALUE);
             if (matches) {
                 const opName = matches[1].toLowerCase();
-                let value = matches[2];
-                try {
-                    // Attempt to parse the value to a native type
-                    value = JSON.parse(matches[2]);
+                const operand = matches[2];
+                if (!KNOWN_OPERATORS.has(opName)) {
+                    throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: matches[1] }));
                 }
-                catch (err) {
-                    // If an error occurred it's because the value is a string or date, not another type.
-                    value = new Date(matches[2]);
-                    if (isNaN(value)) {
-                        value = matches[2];
-                    }
-                }
-                // `value` is the client-supplied comparison operand — reject any Mongo operator/dotted key hidden
-                // inside it, regardless of which (trusted, framework-constructed) operator wrapper it ends up
-                // under below. Must run *after* the parse fallback above, not inside its try/catch, so a
-                // rejection here isn't silently swallowed as a "not valid JSON" case.
-                ModelUtils.assertNoOperatorInjection(value);
                 switch (opName) {
                     case "eq":
-                        return value;
+                        return ModelUtils.coerceOperand(operand, modelClass, property, user);
                     case "gt":
-                        return { $gt: value };
+                        return { $gt: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "gte":
-                        return { $gte: value };
+                        return { $gte: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "in": {
-                        // Split the raw match text, not `value`: a comma-joined list like "1,5" can itself parse
-                        // as a valid `Date` above (e.g. "1,5" -> Jan 5), leaving `value` a Date with no `.split()`.
-                        const args = matches[2].split(",");
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return { $in: args };
                     }
                     case "nin": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return { $nin: args };
                     }
                     case "like": {
-                        const pattern = String(value);
-                        if (ModelUtils.isUnsafeRegexPattern(pattern)) {
+                        const pattern = ModelUtils.globToRegExpSource(operand);
+                        return { $regex: pattern, $options: "i" };
+                    }
+                    case "regex": {
+                        if (ModelUtils.isUnsafeRegexPattern(operand)) {
                             throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
                         }
-                        return { $regex: pattern, $options: "i" };
+                        return { $regex: operand, $options: "i" };
                     }
                     case "lt":
-                        return { $lt: value };
+                        return { $lt: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "lte":
-                        return { $lte: value };
+                        return { $lte: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "ne":
-                        return { $ne: value };
-                    case "not":
-                        return { $not: value };
+                        return { $ne: ModelUtils.coerceOperand(operand, modelClass, property, user) };
+                    case "not": {
+                        // MongoDB's `$not` accepts only an operator expression or a regex - a bare scalar (e.g.
+                        // `{ $not: "somestring" }`) is rejected by the server rather than matching zero rows.
+                        // Compile scalar negation to `$ne` instead, reserving `$not` for an actual `RegExp`
+                        // operand (kept for defensiveness; `like()`/`regex()` above compile to `$regex` objects,
+                        // not live `RegExp` instances, so this branch is not normally reached in practice).
+                        const value = ModelUtils.coerceOperand(operand, modelClass, property, user);
+                        return value instanceof RegExp ? { $not: value } : { $ne: value };
+                    }
                     case "range": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = ModelUtils.splitListOperand(operand);
                         if (args.length !== 2) {
                             const msg = StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
-                                value,
+                                value: operand,
                                 length: args.length,
                             });
                             throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, msg);
                         }
-                        // Attempt to parse the range values to native types, falling back to the raw strings
-                        let gte = args[0];
-                        let lte = args[1];
-                        try {
-                            gte = JSON.parse(args[0]);
-                            lte = JSON.parse(args[1]);
-                        }
-                        catch (err) {
-                            // Not valid JSON — fall back to the raw strings assigned above.
-                        }
-                        ModelUtils.assertNoOperatorInjection(gte);
-                        ModelUtils.assertNoOperatorInjection(lte);
+                        const gte = ModelUtils.coerceOperand(args[0], modelClass, property, user);
+                        const lte = ModelUtils.coerceOperand(args[1], modelClass, property, user);
                         return { $gte: gte, $lte: lte };
                     }
+                    case "exists": {
+                        const wantsExists = operand.trim().toLowerCase() === "true";
+                        return { $exists: wantsExists };
+                    }
                     default:
-                        return value;
+                        // Unreachable: opName was already validated against KNOWN_OPERATORS above.
+                        throw new Error(`Unhandled search operator: ${opName}`);
                 }
             }
             else {
-                // Attempt to parse the value to a native type, falling back to a date/string if it's not valid JSON
-                let parsed;
-                try {
-                    parsed = JSON.parse(param);
+                const coerced = ModelUtils.coerceOperand(param, modelClass, property, user);
+                if (!exactMatch && typeof coerced === "string") {
+                    return { $regex: StringUtils.escapeRegExp(coerced), $options: "i" };
                 }
-                catch (err) {
-                    const date = new Date(param);
-                    return !isNaN(date.valueOf()) ? date : param;
-                }
-                ModelUtils.assertNoOperatorInjection(parsed);
-                return parsed;
+                return coerced;
             }
         }
+        else if (param instanceof QueryLiteral) {
+            const node = {
+                kind: "predicate",
+                field: property,
+                op: param.op,
+                value: param.value,
+                literal: true,
+            };
+            return ModelUtils.compilePredicateMongo(node, modelClass, user)[property];
+        }
         else {
             // A non-string value only reaches here when the caller already parsed the raw query into native
             // types itself (e.g. the `q` base64-encoded JSON query parameter in RouteUtils.wrapMiddleware) —
@@ -450,6 +737,113 @@ export class ModelUtils {
             return param;
         }
     }
+    /**
+     * Extracts the `$match` stage from either shape `buildSearchQueryMongo` can return (a pipeline array or a
+     * flattened `{$match, $sort}` object).
+     */
+    static extractMatch(pipelineOrObject) {
+        if (Array.isArray(pipelineOrObject)) {
+            return pipelineOrObject.length > 0 ? pipelineOrObject[0]["$match"] : undefined;
+        }
+        return pipelineOrObject ? pipelineOrObject["$match"] : undefined;
+    }
+    /**
+     * Normalizes the return value of `buildSearchQueryMongo` to a single shape: a full aggregation pipeline.
+     * `buildSearchQueryMongo` itself still returns either a pipeline array or a flattened `{$match, $sort}`
+     * object depending on how many stages it produced (existing callers, e.g. `RepoUtils`, already branch on
+     * `Array.isArray()` to handle both) - use this instead at any new call site that wants one consistent shape.
+     */
+    static toFindQuery(pipelineOrObject) {
+        if (Array.isArray(pipelineOrObject)) {
+            return pipelineOrObject;
+        }
+        const stages = [];
+        if (pipelineOrObject?.$match !== undefined) {
+            stages.push({ $match: pipelineOrObject.$match });
+        }
+        if (pipelineOrObject?.$sort !== undefined) {
+            stages.push({ $sort: pipelineOrObject.$sort });
+        }
+        return stages;
+    }
+    /**
+     * Resolves the `limit`/`page` reserved query parameters to a bounded `take`/`skip` pair, applying the same
+     * default (`DEFAULT_PAGE_SIZE`) and ceiling (`MAX_PAGE_SIZE`) that `buildSearchQuerySQL` already bakes into
+     * its own return value (as `take`/`page`). `buildSearchQueryMongo` does NOT bake pagination into its own
+     * pipeline - doing so would execute as `$skip`/`$limit` aggregation stages, which would double up with (and
+     * corrupt) any cursor-level `.skip()/.limit()` a caller applies on top, as `RepoUtils` already does for its
+     * own route-level pagination. A caller building a Mongo query directly - rather than going through
+     * `RepoUtils` - should call this explicitly to get the same bounded pagination the SQL path enforces
+     * automatically, rather than an unbounded result set.
+     */
+    static resolvePagination(query = {}) {
+        const take = query?.limit ? Math.min(Number(query.limit), MAX_PAGE_SIZE) : DEFAULT_PAGE_SIZE;
+        const page = query?.page ? Number(query.page) : 0;
+        return { take, page, skip: page * take };
+    }
+    /** Returns `true` for the boolean grouping keys (`$or`, `$and`) accepted in a flat search query. */
+    static isGroupKey(key) {
+        return key === "$or" || key === "$and";
+    }
+    /**
+     * Validates the value of a `$or`/`$and` key: a non-empty array (at most `MAX_QUERY_NODES` long) of plain query
+     * objects. Anything else is a 400 on both backends. In particular an empty array is rejected rather than
+     * compiled: on SQL it used to expand to zero branches, which dropped the whole `where` (every other condition
+     * included) and matched every row, while MongoDB rejects `$or: []` outright.
+     */
+    static assertQueryGroup(value) {
+        if (!Array.isArray(value) ||
+            value.length === 0 ||
+            value.some((sub) => !sub || typeof sub !== "object" || Array.isArray(sub) || sub instanceof QueryLiteral)) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        if (value.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        return value;
+    }
+    /**
+     * ANDs two lists of OR-ed SQL `where` branches: `(L1 OR L2) AND (R1 OR R2)` becomes the cross product
+     * `(L1 AND R1) OR (L1 AND R2) OR ...`. Throws before allocating if the product exceeds `MAX_QUERY_NODES`.
+     */
+    static andBranches(left, right) {
+        if (left.length * right.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        const combined = [];
+        for (const l of left) {
+            for (const r of right) {
+                combined.push(ModelUtils.mergeWhereBranches(l, r));
+            }
+        }
+        return combined;
+    }
+    /**
+     * ANDs two SQL `where` branch objects. A key present on only one side is copied; a key present on both keeps
+     * both conditions via TypeORM's `And()` (a plain object spread would let the right side silently replace the
+     * left, e.g. a forced scope key being overridden by a `$or` branch). Nested plain objects (embedded entities or
+     * relations) are merged recursively.
+     */
+    static mergeWhereBranches(left, right) {
+        const result = { ...left };
+        for (const key of Object.keys(right)) {
+            result[key] = key in result ? ModelUtils.andWhereValues(result[key], right[key]) : right[key];
+        }
+        return result;
+    }
+    static andWhereValues(left, right) {
+        const { And, Equal, IsNull, InstanceChecker } = ModelUtils.orm;
+        const isPlainObject = (v) => !!v && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype;
+        if (isPlainObject(left) && isPlainObject(right)) {
+            return ModelUtils.mergeWhereBranches(left, right);
+        }
+        // Flatten nested And() so repeated merges on one key stay a single flat conjunction.
+        const operands = (v) => {
+            const op = InstanceChecker.isFindOperator(v) ? v : v === null ? IsNull() : Equal(v);
+            return op.type === "and" ? op.value : [op];
+        };
+        return And(...operands(left), ...operands(right));
+    }
     /**
      * Builds a query object for the given criteria and repository. Query params can have a value containing a
      * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
@@ -458,13 +852,43 @@ export class ModelUtils {
      * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
      * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
      * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
-     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
+     * * `like` - Returns matches whose parameter matches the given glob pattern (`*` = any sequence, `?` = any single character), case-insensitively. e.g. `like(*.txt)`
+     * * `regex` - Returns matches whose parameter matches the given regular expression, case-insensitively.
      * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
      * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
-     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
+     * * `not` / `ne` - Returns matches whose parameter is not equal to the given value. e.g. `param != value`
      * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     * * `exists` - Returns matches whose parameter is (`exists(true)`) or is not (`exists(false)`) set.
+     *
+     * When no operator is provided the comparison is evaluated as `eq`, unless `exactMatch` is `false`, in which
+     * case a string-valued parameter is instead matched as a case-insensitive "contains" search.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * Operand and escaping rules:
+     * * A value is only parsed as an operator when the WHOLE value has the shape `name(...)`. The operand is
+     * everything between the first `(` and the last `)`, verbatim: parentheses, commas, leading/trailing spaces,
+     * newlines and nested `op(...)` text included. So `eq(Support(EU))` matches `Support(EU)`, `eq( a,b )`
+     * matches ` a,b ` and `eq(ne(x))` matches `ne(x)`. The operator name is case-insensitive.
+     * * A bare value shaped like `name(...)` whose `name` is not a known operator is rejected with a 400; wrap it
+     * in `eq(...)` to match it literally.
+     * * `eq()`/`ne()` operands are then coerced like any operand: `me` resolves to the requesting user's uid, `null`
+     * matches a null value, and the value is converted to the column's declared type (number, boolean, date).
+     * With no column metadata a JSON/date heuristic is used instead.
+     * * `in()`, `nin()` and `range()` split their operand on commas. Write `\,` for a comma inside one value and
+     * `\\` for a backslash, e.g. `in(a\,b,c)` matches `a,b` or `c`. A backslash before any other character is
+     * kept as is.
+     * * `$or` and `$and` (only from programmatic queries or the `q` JSON parameter; a query string can't build them)
+     * take a non-empty array of sub-query objects that are ANDed with every other key, the same on both backends.
+     * A `$`-prefixed field name is rejected with a 400.
+     *
+     * Code that passes a value it doesn't control (an email header, an iCalendar UID, a display name, ...) should
+     * use `ModelUtils.literal(value)` instead of building an `eq(...)` string. A literal skips all of the parsing
+     * and coercion above. Other non-string values (numbers, booleans, `Date`, `null`) are also compared as given.
+     *
+     * A repeated query parameter name (e.g. `?a=1&a=2`) OR-combines its values, "zipped" positionally against
+     * every other repeated parameter rather than as a cartesian product: `?a=1&a=2&b=3&b=4` compiles to
+     * `(a=1 AND b=3) OR (a=2 AND b=4)`, not `a IN (1,2)` and not all four combinations. A shorter array is padded
+     * by repeating its own last value against the longer one(s), rather than leaving the key unset for the extra
+     * branches (which would match ANY value there, silently dropping that filter).
      *
      * NOTE: The result of this function is only compatible with the `aggregate()` function when MongoDB is used.
      *
@@ -487,50 +911,44 @@ export class ModelUtils {
             return ModelUtils.buildSearchQueryMongo(modelClass, query, exactMatch, user);
         }
         else {
-            return ModelUtils.buildSearchQuerySQL(modelClass, query, exactMatch, user);
+            const driverType = repo?.manager?.connection?.options?.type;
+            return ModelUtils.buildSearchQuerySQL(modelClass, query, exactMatch, user, driverType);
         }
     }
     /**
-     * Builds a TypeORM compatible query object for the given criteria. Query params can have a value containing a
-     * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
-     * operators are supported:
-     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
-     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
-     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
-     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
-     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
-     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
-     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
-     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
-     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     * Builds a TypeORM compatible query object for the given criteria. See `buildSearchQuery` for the supported
+     * `op(value)` operators and multi-value "zip" semantics.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * Unlike `buildSearchQuery` (which always injects a `deleted: false` filter for a `RecoverableBaseEntity`
+     * before delegating here), this function applies no soft-delete filtering of its own - a caller invoking it
+     * directly, bypassing `buildSearchQuery`, will not get that default exclusion.
      *
      * @param modelClass The class definition of the data model to build a search query for.
      * @param {any} query The search query parameters to include.
      * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
      * @param {any} user The user that is performing the request.
+     * @param {string} driverType The TypeORM driver type (`connection.options.type`) of the target datasource, used
+     * to select a compatible SQL translation for the `regex()` operator. Only needed when `regex()` may appear in
+     * `query`.
+     * @param {number} depth Internal recursion-depth counter for nested `$or` groups - do not pass explicitly.
      * @returns {object} The TypeORM compatible query object.
      */
-    static buildSearchQuerySQL(modelClass, query = {}, exactMatch = false, user) {
+    static buildSearchQuerySQL(modelClass, query = {}, exactMatch = false, user, driverType, depth = 0) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
         const result = {};
         result.where = [];
-        // Pre-process any query values (e.g. the `me` identifier)
-        for (const key in query) {
-            // If the value is 'me' that's a special keyword to reference the user ID.
-            if (query[key] === "me") {
-                if (!user) {
-                    throw new ApiError(ApiErrors.SEARCH_INVALID_ME_REFERENCE, 403, ApiErrorMessages.SEARCH_INVALID_ME_REFERENCE);
-                }
-                query[key] = user.uid;
-            }
-        }
+        const sortableFields = ModelUtils.getSortablePropertyNames(modelClass);
         // Query parameters can be a single value or multiple. In the case of multiple we want to perform an OR
         // operation for each value. But to do that we need to build a separate object for each value containing all
         // the parameters as well.
         // So first let's find out how many queries in total we are going to need.
         let numQueries = 1;
         for (const key in query) {
+            if (ModelUtils.isGroupKey(key) || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
+                continue;
+            }
             const value = query[key];
             if (Array.isArray(value)) {
                 if (value.length > numQueries) {
@@ -542,6 +960,10 @@ export class ModelUtils {
         // Now go through each query paramater. If the parameter is a single value, add it to each query object. If it's an array,
         // add only one value to each query object.
         for (let key in query) {
+            // `$or`/`$and` are composed after the main loop, cross-producted against everything else built here.
+            if (ModelUtils.isGroupKey(key)) {
+                continue;
+            }
             // Ignore reserved query parameters
             if (key.match(REGEX_RESERVED_QUERY_PARAMS)) {
                 continue;
@@ -563,16 +985,30 @@ export class ModelUtils {
                             value = JSON.parse(value);
                         }
                         else {
-                            let newValue = value;
-                            newValue = {};
-                            newValue[value] = "ASC";
-                            value = newValue;
+                            // Supports the conventional `sort=-fieldName` shorthand for descending order.
+                            const descending = value.startsWith("-");
+                            const field = descending ? value.slice(1) : value;
+                            value = { [field]: descending ? "DESC" : "ASC" };
+                        }
+                    }
+                    if (sortableFields) {
+                        for (const sortKey of Object.keys(value)) {
+                            if (!sortableFields.has(sortKey)) {
+                                throw new ApiError(ApiErrors.SEARCH_INVALID_SORT_FIELD, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_SORT_FIELD, {
+                                    field: sortKey,
+                                }));
+                            }
                         }
                     }
                     result[key] = value;
                 }
                 continue;
             }
+            // Same rule as the Mongo builder: a `$`-prefixed key (or path segment) is never a field, so reject it
+            // with a 400 on both backends instead of letting TypeORM fail on an unknown property.
+            if (key.split(".").some((segment) => segment.startsWith("$"))) {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+            }
             if (Array.isArray(query[key])) {
                 // Add each value in the array to each corresponding query. Multi-valued keys are "zipped"
                 // together via `numQueries` above; if this key's array is shorter than another key's, pad the
@@ -584,7 +1020,7 @@ export class ModelUtils {
                         result.where[i] = {};
                     }
                     const value = i < values.length ? values[i] : values[values.length - 1];
-                    result.where[i][key] = ModelUtils.getQueryParamValue(value);
+                    result.where[i][key] = ModelUtils.getQueryParamValue(value, modelClass, key, user, exactMatch, driverType);
                 }
             }
             else {
@@ -593,37 +1029,56 @@ export class ModelUtils {
                     if (!result.where[i]) {
                         result.where[i] = {};
                     }
-                    result.where[i][key] = ModelUtils.getQueryParamValue(query[key]);
+                    result.where[i][key] = ModelUtils.getQueryParamValue(query[key], modelClass, key, user, exactMatch, driverType);
                 }
             }
         }
+        // `$or`/`$and` keys are composed via a distinct pass, after every other key: since a TypeORM `find()`-based
+        // `where` only supports OR as a top-level array (no nested-OR expressible within one branch), each
+        // sub-query's own OR-branches are cross-producted (distributed) against the branches already built above
+        // - (A) AND ($or: [X,Y]) is equivalent to (A AND X) OR (A AND Y), which composes correctly with the
+        // existing "zip" array regardless of processing order. Each combined branch must keep BOTH sides'
+        // conditions, including on a key present on both sides (see `mergeWhereBranches`), exactly like Mongo's
+        // implicit AND of a top-level key and a `$or`.
+        for (const groupKey of ["$and", "$or"]) {
+            if (!(groupKey in query)) {
+                continue;
+            }
+            const branchesPerChild = ModelUtils.assertQueryGroup(query[groupKey]).map((sub) => {
+                const compiled = ModelUtils.buildSearchQuerySQL(modelClass, sub, exactMatch, user, driverType, depth + 1);
+                return compiled.where ?? [{}];
+            });
+            const base = result.where.length > 0 ? result.where : [{}];
+            if (groupKey === "$or") {
+                result.where = ModelUtils.andBranches(base, [].concat(...branchesPerChild));
+            }
+            else {
+                result.where = branchesPerChild.reduce((acc, branches) => ModelUtils.andBranches(acc, branches), base);
+            }
+        }
         if (result.where.length === 0) {
             delete result.where;
         }
         if (result.take) {
-            result.take = Math.min(result.take, 1000);
+            result.take = Math.min(result.take, MAX_PAGE_SIZE);
         }
         else {
-            result.take = 100;
+            result.take = DEFAULT_PAGE_SIZE;
         }
         result.page = result.page ? result.page : 0;
         return result;
     }
     /**
-     * Builds a MongoDB compatible query object for the given criteria. Query params can have a value containing a
-     * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
-     * operators are supported:
-     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
-     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
-     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
-     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
-     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
-     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
-     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
-     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
-     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     * Builds a MongoDB compatible query object for the given criteria. See `buildSearchQuery` for the supported
+     * `op(value)` operators and multi-value "zip" semantics.
+     *
+     * Unlike `buildSearchQuery` (which always injects a `deleted: false` filter for a `RecoverableBaseEntity`
+     * before delegating here), this function applies no soft-delete filtering of its own - a caller invoking it
+     * directly, bypassing `buildSearchQuery`, will not get that default exclusion.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * Does NOT bound `limit`/`page` into the returned pipeline (see `resolvePagination`) and returns either an
+     * aggregation pipeline array or a flattened `{$match, $sort}` object depending on how many stages it
+     * produced (see `toFindQuery` to normalize to one shape).
      *
      * NOTE: The result of this function is only compatible with the `aggregate()` function.
      *
@@ -631,11 +1086,16 @@ export class ModelUtils {
      * @param {any} query The search query parameters to include.
      * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
      * @param {any} user The user that is performing the request.
+     * @param {number} depth Internal recursion-depth counter for nested `$or` groups - do not pass explicitly.
      * @returns {object} The MongoDB compatible query object.
      */
-    static buildSearchQueryMongo(modelClass, query = {}, exactMatch = false, user) {
+    static buildSearchQueryMongo(modelClass, query = {}, exactMatch = false, user, depth = 0) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
         const queries = [{}];
         let sort = undefined;
+        const sortableFields = ModelUtils.getSortablePropertyNames(modelClass);
         // logger?.debug(`Query params: ${JSON.stringify(queryParams)}`);
         // Query parameters can be a single value or multiple. In the case of multiple we want to perform an OR
         // operation for each value, "zipped" together with any other multi-valued parameters (see the equivalent
@@ -643,7 +1103,7 @@ export class ModelUtils {
         // pre-allocate them, before any key gets applied to a subset of branches.
         let numQueries = 1;
         for (const key in query) {
-            if (key === "$or" || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
+            if (ModelUtils.isGroupKey(key) || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
                 continue;
             }
             const value = query[key];
@@ -659,13 +1119,6 @@ export class ModelUtils {
             if (key.match(REGEX_RESERVED_QUERY_PARAMS)) {
                 continue;
             }
-            // If the value is 'me' that's a special keyword to reference the user ID.
-            if (query[key] === "me") {
-                if (!user) {
-                    throw new ApiError(ApiErrors.SEARCH_INVALID_ME_REFERENCE, 403, ApiErrorMessages.SEARCH_INVALID_ME_REFERENCE);
-                }
-                query[key] = user.uid;
-            }
             // Limit, page and sort are reserved for specifying query limits
             if (key.match(REGEX_QUERY_LIMITS)) {
                 let value = query[key];
@@ -675,10 +1128,19 @@ export class ModelUtils {
                             value = JSON.parse(value);
                         }
                         else {
-                            let newValue = value;
-                            newValue = {};
-                            newValue[value] = 1;
-                            value = newValue;
+                            // Supports the conventional `sort=-fieldName` shorthand for descending order.
+                            const descending = value.startsWith("-");
+                            const field = descending ? value.slice(1) : value;
+                            value = { [field]: descending ? -1 : 1 };
+                        }
+                    }
+                    if (sortableFields) {
+                        for (const sortKey of Object.keys(value)) {
+                            if (!sortableFields.has(sortKey)) {
+                                throw new ApiError(ApiErrors.SEARCH_INVALID_SORT_FIELD, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_SORT_FIELD, {
+                                    field: sortKey,
+                                }));
+                            }
                         }
                     }
                     let resolvedSort = {
@@ -715,24 +1177,25 @@ export class ModelUtils {
             // handled just below; its sub-queries are validated recursively when they're built). Operator
             // injection hidden inside a *value* (e.g. `eq({"$ne":null})`) is separately guarded by
             // `assertNoOperatorInjection` wherever values are parsed.
-            if (key !== "$or" && key.split(".").some((segment) => segment.startsWith("$"))) {
+            if (!ModelUtils.isGroupKey(key) && key.split(".").some((segment) => segment.startsWith("$"))) {
                 throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
             }
-            if (key === "$or") {
-                // Array of OR queries
+            if (ModelUtils.isGroupKey(key)) {
+                // Array of OR (or AND) sub-queries
                 let orResults = [];
-                for (const q of query[key]) {
-                    const subQueryOrResult = this.buildSearchQueryMongo(modelClass, q, exactMatch, user);
-                    const validSubQueryResult = Array.isArray(subQueryOrResult) && subQueryOrResult.length > 0
-                        ? subQueryOrResult[0]["$match"]
-                        : subQueryOrResult["$match"];
+                for (const q of ModelUtils.assertQueryGroup(query[key])) {
+                    const subQueryOrResult = this.buildSearchQueryMongo(modelClass, q, exactMatch, user, depth + 1);
+                    const validSubQueryResult = ModelUtils.extractMatch(subQueryOrResult);
                     validSubQueryResult && orResults.push(validSubQueryResult);
                 }
+                if (orResults.length > MAX_QUERY_NODES) {
+                    throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+                }
                 // Merge into whatever conditions earlier keys (including the injected soft-delete filter)
                 // already placed on each branch — replacing outright would silently discard them, and merging
                 // only into queries[0] would silently drop the $or constraint from any other zipped branch.
                 for (let i = 0; i < numQueries; i++) {
-                    queries[i] = { ...queries[i], $or: orResults };
+                    queries[i] = { ...queries[i], [key]: orResults };
                 }
                 continue;
             }
@@ -745,11 +1208,11 @@ export class ModelUtils {
                 const values = query[key];
                 for (let i = 0; i < numQueries; i++) {
                     const raw = i < values.length ? values[i] : values[values.length - 1];
-                    queries[i][key] = ModelUtils.getQueryParamValueMongo(raw);
+                    queries[i][key] = ModelUtils.getQueryParamValueMongo(raw, modelClass, key, user, exactMatch);
                 }
             }
             else {
-                const value = ModelUtils.getQueryParamValueMongo(query[key]);
+                const value = ModelUtils.getQueryParamValueMongo(query[key], modelClass, key, user, exactMatch);
                 for (let i = 0; i < numQueries; i++) {
                     queries[i][key] = value;
                 }
@@ -780,6 +1243,223 @@ export class ModelUtils {
         }
         return result;
     }
+    /**
+     * Compiles a single `PredicateNode` leaf to a MongoDB filter fragment (`{field: ...}`).
+     */
+    static compilePredicateMongo(node, modelClass, user) {
+        const { field, op } = node;
+        switch (op) {
+            case "eq":
+                return { [field]: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) };
+            case "ne":
+                return {
+                    [field]: { $ne: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
+            case "gt":
+                return {
+                    [field]: { $gt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
+            case "gte":
+                return {
+                    [field]: { $gte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
+            case "lt":
+                return {
+                    [field]: { $lt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
+            case "lte":
+                return {
+                    [field]: { $lte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
+            case "in": {
+                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, node.literal));
+                return { [field]: { $in: values } };
+            }
+            case "nin": {
+                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, node.literal));
+                return { [field]: { $nin: values } };
+            }
+            case "range": {
+                if (!Array.isArray(node.value) || node.value.length !== 2) {
+                    throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
+                        value: JSON.stringify(node.value),
+                        length: Array.isArray(node.value) ? node.value.length : 1,
+                    }));
+                }
+                const [lo, hi] = node.value;
+                return {
+                    [field]: {
+                        $gte: ModelUtils.coerceNodeValue(lo, modelClass, field, user, node.literal),
+                        $lte: ModelUtils.coerceNodeValue(hi, modelClass, field, user, node.literal),
+                    },
+                };
+            }
+            case "like": {
+                const pattern = ModelUtils.globToRegExpSource(String(node.value));
+                return { [field]: { $regex: pattern, $options: "i" } };
+            }
+            case "regex": {
+                const pattern = String(node.value);
+                if (ModelUtils.isUnsafeRegexPattern(pattern)) {
+                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                }
+                return { [field]: { $regex: pattern, $options: "i" } };
+            }
+            case "exists":
+                return { [field]: { $exists: !!node.value } };
+            default:
+                throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, {
+                    operator: String(node.op),
+                }));
+        }
+    }
+    static compileGroupMongo(node, modelClass, user, depth) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        if (node.children.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        const compiledChildren = node.children.map((child) => ModelUtils.compileNodeMongo(child, modelClass, user, depth + 1));
+        const clause = node.op === "and" ? { $and: compiledChildren } : { $or: compiledChildren };
+        return node.negated ? { $nor: [clause] } : clause;
+    }
+    static compileNodeMongo(node, modelClass, user, depth = 0) {
+        return node.kind === "group"
+            ? ModelUtils.compileGroupMongo(node, modelClass, user, depth)
+            : ModelUtils.compilePredicateMongo(node, modelClass, user);
+    }
+    static compilePredicateSQLOperator(op, value, modelClass, field, user, driverType, literal = false) {
+        const { Equal, MoreThan, MoreThanOrEqual, In, ILike, LessThan, LessThanOrEqual, Not, Between, IsNull } = ModelUtils.orm;
+        switch (op) {
+            case "eq": {
+                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user, literal);
+                return v === null ? IsNull() : Equal(v);
+            }
+            case "ne": {
+                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user, literal);
+                return v === null ? Not(IsNull()) : Not(v);
+            }
+            case "gt":
+                return MoreThan(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
+            case "gte":
+                return MoreThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
+            case "lt":
+                return LessThan(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
+            case "lte":
+                return LessThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
+            case "in": {
+                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, literal));
+                return In(values);
+            }
+            case "nin": {
+                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, literal));
+                return Not(In(values));
+            }
+            case "range": {
+                if (!Array.isArray(value) || value.length !== 2) {
+                    throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
+                        value: JSON.stringify(value),
+                        length: Array.isArray(value) ? value.length : 1,
+                    }));
+                }
+                const [lo, hi] = value;
+                return Between(ModelUtils.coerceNodeValue(lo, modelClass, field, user, literal), ModelUtils.coerceNodeValue(hi, modelClass, field, user, literal));
+            }
+            case "like":
+                return ILike(ModelUtils.globToLike(String(value)));
+            case "regex": {
+                const pattern = String(value);
+                if (ModelUtils.isUnsafeRegexPattern(pattern)) {
+                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                }
+                return ModelUtils.compileSqlRegex(pattern, driverType);
+            }
+            case "exists":
+                return value ? Not(IsNull()) : IsNull();
+            default:
+                throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: String(op) }));
+        }
+    }
+    static compileNodeSQL(node, modelClass, user, driverType, depth) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        if (node.kind === "predicate") {
+            return [
+                {
+                    [node.field]: ModelUtils.compilePredicateSQLOperator(node.op, node.value, modelClass, node.field, user, driverType, node.literal),
+                },
+            ];
+        }
+        if (node.negated) {
+            // De Morgan expansion of an arbitrarily-nested negated group isn't attempted against TypeORM's
+            // `find()`-based `where` (no general boolean-algebra rewrite is implemented here) - only the Mongo
+            // compiler, which can express negation natively via `$nor`, supports it.
+            throw new ApiError(ApiErrors.SEARCH_OPERATOR_NOT_SUPPORTED, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_OPERATOR_NOT_SUPPORTED, {
+                operator: "negated group (SQL)",
+            }));
+        }
+        if (node.children.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        const childBranches = node.children.map((child) => ModelUtils.compileNodeSQL(child, modelClass, user, driverType, depth + 1));
+        let branches;
+        if (node.op === "or") {
+            branches = [].concat(...childBranches);
+        }
+        else {
+            branches = childBranches.reduce((acc, branchesForChild) => ModelUtils.andBranches(acc, branchesForChild), [{}]);
+        }
+        if (branches.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        return branches;
+    }
+    /**
+     * Compiles a `QueryNode` boolean tree into a query object for the given repository - the nested-condition
+     * counterpart to `buildSearchQuery()`'s flat `op(value)` query-parameter form, for boolean shapes the flat
+     * form can't express (e.g. `(a AND b) OR (c AND d)`, with no key forced into every branch). Reuses the same
+     * operand coercion, `me` substitution and operator-injection guard as the flat form. Bounded by the same
+     * `MAX_QUERY_DEPTH`/`MAX_QUERY_NODES` limits as `$or`. Negated groups are supported on MongoDB (via `$nor`)
+     * but rejected against the SQL `find()`-based `where` (see `compileNodeSQL`).
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param repo The repository to build a search query for.
+     * @param node The root of the query tree.
+     * @param user The user that is performing the request, resolved for any `field: "me"` predicate value.
+     */
+    static buildQueryFromNode(modelClass, repo, node, user) {
+        if (repo instanceof MongoRepository) {
+            return { $match: ModelUtils.compileNodeMongo(node, modelClass, user, 0) };
+        }
+        const driverType = repo?.manager?.connection?.options?.type;
+        return { where: ModelUtils.compileNodeSQL(node, modelClass, user, driverType, 0) };
+    }
+    /**
+     * Converts a `QueryNode` boolean tree into a PostgreSQL `tsquery` expression string (`AND` -> `&`, `OR` -> `|`,
+     * negation -> `!`), so client input can drive full-text search without passing untrusted text straight to
+     * `to_tsquery` (which throws on malformed input) while still supporting the boolean grouping
+     * `websearch_to_tsquery` cannot express. Every predicate leaf's `value` is treated as a search term
+     * (lexeme/phrase) regardless of its `field`/`op` - this framework has no notion of a full-text-indexed column,
+     * so the caller is expected to route the resulting expression to whichever `tsvector` column it's searching,
+     * e.g. `to_tsquery(ModelUtils.toTsQuery(node))`.
+     */
+    static toTsQuery(node) {
+        if (node.kind === "predicate") {
+            const term = String(node.value).replace(/'/g, "''");
+            return `'${term}'`;
+        }
+        const joiner = node.op === "and" ? " & " : " | ";
+        const inner = node.children
+            .map((child) => {
+            const compiled = ModelUtils.toTsQuery(child);
+            return child.kind === "group" ? `(${compiled})` : compiled;
+        })
+            .join(joiner);
+        const grouped = node.children.length > 1 ? `(${inner})` : inner;
+        return node.negated ? `!${grouped}` : grouped;
+    }
     /**
      * Loads all model schema files from the specified path and returns a map containing all the definitions.
      *
@@ -808,6 +1488,9 @@ export class ModelUtils {
 }
 ModelUtils.idPropertyCache = new Map();
 ModelUtils.readOnlyPropertyCache = new Map();
-/** Maximum accepted length of a client-supplied `like()` search pattern. */
-ModelUtils.MAX_LIKE_PATTERN_LENGTH = 100;
+ModelUtils.columnTypeCache = new Map();
+/** Sequence used to give every `Raw()` SQL expression's named parameter a unique name within one query. */
+ModelUtils.rawParamSeq = 0;
+/** Maximum accepted length of a client-supplied `like()`/`regex()` search pattern. */
+ModelUtils.MAX_PATTERN_LENGTH = 100;
 //# sourceMappingURL=ModelUtils.js.map