@oneuptime/common 12.0.34 → 13.0.0

package/Server/Services/NetworkDeviceDiscoveryScanService.ts

@@ -1,6 +1,8 @@
 import DatabaseService from "./DatabaseService";
-import Model from "../../Models/DatabaseModels/NetworkDeviceDiscoveryScan";
-import { OnCreate, OnUpdate } from "../Types/Database/Hooks";
+import Model, {
+  DiscoveredNetworkDevice,
+} from "../../Models/DatabaseModels/NetworkDeviceDiscoveryScan";
+import { OnCreate, OnFind, OnUpdate } from "../Types/Database/Hooks";
 import CreateBy from "../Types/Database/CreateBy";
 import UpdateBy from "../Types/Database/UpdateBy";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
@@ -20,6 +22,7 @@ import SnmpScanConfigUtil, {
 } from "../../Utils/NetworkDiscovery/SnmpScanConfigUtil";
 import { getNextScanAt } from "../../Utils/NetworkDiscovery/RescanIntervalUtil";
 import ScanModeUtil from "../../Utils/NetworkDiscovery/ScanModeUtil";
+import NetworkDeviceService from "./NetworkDeviceService";
 
 /*
  * The two spellings a many-to-one reference reaches a hook under: the
@@ -175,6 +178,88 @@ export class Service extends DatabaseService<Model> {
     super(Model);
   }
 
+  @CaptureSpan()
+  protected override async onFindSuccess(
+    onFind: OnFind<Model>,
+    items: Array<Model>,
+  ): Promise<OnFind<Model>> {
+    /*
+     * Registration is current inventory state, not a fact about the scan.
+     * Refresh both directions so old results can be used after a deletion.
+     */
+    const hostnamesByProject: Map<string, Set<string>> = new Map();
+
+    for (const scan of items) {
+      const projectId: ObjectID | undefined =
+        scan.projectId || onFind.findBy.props.tenantId;
+
+      if (!projectId || !Array.isArray(scan.discoveredDevices)) {
+        continue;
+      }
+
+      for (const host of scan.discoveredDevices) {
+        const hostname: string = this.getDiscoveredHostname(host);
+        if (!hostname) {
+          continue;
+        }
+
+        const projectKey: string = projectId.toString();
+        if (!hostnamesByProject.has(projectKey)) {
+          hostnamesByProject.set(projectKey, new Set());
+        }
+        hostnamesByProject.get(projectKey)!.add(hostname);
+      }
+    }
+
+    const registeredByProject: Map<string, Set<string>> = new Map();
+    for (const [projectId, hostnames] of hostnamesByProject) {
+      registeredByProject.set(
+        projectId,
+        await NetworkDeviceService.getRegisteredHostnames({
+          projectId: new ObjectID(projectId),
+          hostnames: Array.from(hostnames),
+          /*
+           * The scan read has already passed its access checks. Return only
+           * the same existence flag as probe ingest, scoped to this project.
+           */
+          props: { isRoot: true },
+        }),
+      );
+    }
+
+    return {
+      ...onFind,
+      carryForward: items.map((scan: Model): Model => {
+        const projectId: ObjectID | undefined =
+          scan.projectId || onFind.findBy.props.tenantId;
+        const registered: Set<string> | undefined = projectId
+          ? registeredByProject.get(projectId.toString())
+          : undefined;
+
+        if (!registered || !Array.isArray(scan.discoveredDevices)) {
+          return scan;
+        }
+
+        return Object.assign(new Model(), scan, {
+          discoveredDevices: scan.discoveredDevices.map(
+            (host: DiscoveredNetworkDevice): DiscoveredNetworkDevice => {
+              const hostname: string = this.getDiscoveredHostname(host);
+              return hostname
+                ? { ...host, isAlreadyRegistered: registered.has(hostname) }
+                : host;
+            },
+          ),
+        });
+      }),
+    };
+  }
+
+  private getDiscoveredHostname(host: DiscoveredNetworkDevice): string {
+    return host && typeof host.ipAddress === "string"
+      ? host.ipAddress.trim()
+      : "";
+  }
+
   /*
    * Validate the scan target at write time, with the same parser the probe
    * expands it with (Common/Utils/NetworkDiscovery/ScanTargetUtil).

package/Server/Services/NetworkDeviceService.ts

@@ -30,6 +30,7 @@ import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException
 import ObjectID from "../../Types/ObjectID";
 import OneUptimeDate from "../../Types/Date";
 import CidrMatchUtil from "../../Utils/NetworkSite/CidrMatchUtil";
+import { normalizeMac } from "../../Utils/Monitor/EndpointAttachmentUtil";
 import { SiteAssignmentRuleRunResult } from "../../Types/NetworkAutomation/RuleRunResult";
 import { NetworkDeviceMonitoringMethodUtil } from "../../Types/NetworkDevice/NetworkDeviceMonitoringMethod";
 import RelationIdUtil from "../Utils/Database/RelationIdUtil";
@@ -96,6 +97,61 @@ const SITE_KEYS: Array<string> = ["siteId", "site"];
  * otherwise a no-op rewrite of sysName on every SNMP walk would look like a
  * change and re-run the rules for the whole fleet every polling cycle.
  */
+/*
+ * The MAC address column, normalised on the way in.
+ *
+ * Every spelling an operator is likely to paste - AA-BB-CC-DD-EE-FF,
+ * aabb.ccdd.eeff, aa:bb:cc:dd:ee:ff, twelve bare hex digits, with or
+ * without 0x - is stored as lowercase colon form, because that is the form
+ * every endpoint row already holds and the topology builder compares the
+ * two as plain strings. Anything that is not twelve hex digits once the
+ * separators are gone is refused outright rather than stored to match
+ * nothing forever. Blank clears the column, so "delete what I typed"
+ * works from a form that cannot post null.
+ *
+ * Shared by create and update, so it takes the raw payload: a create's
+ * data is a model instance and an update's is a QueryDeepPartialEntity, and
+ * on the latter a column may hold a SQL-expression function, which is left
+ * alone - nothing in the tree writes this column that way, and refusing it
+ * would only make a future caller's life harder for no safety gained.
+ *
+ * Every value that lands this way is the operator's, so the provenance flag
+ * is cleared beside it: the ARP pass writes hook-free and never comes
+ * through here, and it may only correct a value it wrote itself.
+ */
+function normalizeMacAddressOnWrite(data: Record<string, unknown>): void {
+  if (!("macAddress" in data)) {
+    return;
+  }
+
+  const raw: unknown = data["macAddress"];
+
+  // TypeORM drops undefined before it builds the SET list; null clears.
+  if (raw === undefined || raw === null || typeof raw === "function") {
+    return;
+  }
+
+  if (typeof raw !== "string") {
+    throw new BadDataException("MAC Address must be text.");
+  }
+
+  if (raw.trim().length === 0) {
+    data["macAddress"] = null;
+    data["isMacAddressLearned"] = false;
+    return;
+  }
+
+  const normalized: string | undefined = normalizeMac(raw);
+  if (!normalized) {
+    throw new BadDataException(
+      "MAC Address must be six pairs of hex digits, for example aa:bb:cc:dd:ee:ff. Dashes, dots and bare hex are accepted too.",
+    );
+  }
+
+  data["macAddress"] = normalized;
+  data["isMacAddressLearned"] = false;
+}
+
 function normalizeIdentityValue(value: unknown): string {
   if (value === null || value === undefined) {
     return "";
@@ -1239,6 +1295,10 @@ export class Service extends DatabaseService<Model> {
   protected override async onBeforeCreate(
     createBy: CreateBy<Model>,
   ): Promise<OnCreate<Model>> {
+    normalizeMacAddressOnWrite(
+      createBy.data as unknown as Record<string, unknown>,
+    );
+
     /*
      * Read both spellings: the dashboard posts the `site` relation, not the
      * `siteId` column, so guarding only `siteId` let a UI-created device
@@ -1523,6 +1583,15 @@ export class Service extends DatabaseService<Model> {
   ): Promise<OnUpdate<Model>> {
     const dataKeys: Array<string> = Object.keys(updateBy.data || {});
 
+    /*
+     * Above the early return, like the id guards below it: a malformed
+     * MAC is refused on every write shape, not only on the ones that
+     * happen to need the snapshot.
+     */
+    normalizeMacAddressOnWrite(
+      updateBy.data as unknown as Record<string, unknown>,
+    );
+
     /*
      * Switching a device to monitor-backed turns polling off with it. The
      * two are one decision, not two: a monitor-backed device's health is

package/Server/Services/UserNotificationRuleService.ts

@@ -982,6 +982,16 @@ export class Service extends DatabaseService<Model> {
           rootCause: true,
           incidentNumber: true,
           incidentNumberWithPrefix: true,
+          /*
+           * AcknowledgeIncident.hbs asks for a Resources Affected row and
+           * the generator had nothing to build it from, so the row was
+           * silently dropped — the same `{{#if}}` swallow that hid the
+           * alert's Root Cause.
+           */
+          monitors: {
+            _id: true,
+            name: true,
+          },
         },
       });
     }
@@ -1012,6 +1022,20 @@ export class Service extends DatabaseService<Model> {
           },
           alertNumber: true,
           alertNumberWithPrefix: true,
+          /*
+           * AcknowledgeAlert.hbs has always asked for a Root Cause row, but
+           * this select never loaded the column and the template's
+           * `{{#if text}}` guard silently dropped the row — so the one
+           * person being woken up for the alert was the only one who could
+           * not see why it fired. The other three on-call templates already
+           * select it.
+           */
+          rootCause: true,
+          // Same story for the template's Resources Affected row.
+          monitor: {
+            _id: true,
+            name: true,
+          },
         },
       });
     }
@@ -4589,6 +4613,11 @@ export class Service extends DatabaseService<Model> {
         MarkdownContentType.Email,
       ),
       alertSeverity: alert.alertSeverity!.name!,
+      resourcesAffected: alert.monitor?.name || "No resources identified",
+      rootCause: await Markdown.convertToHTML(
+        alert.rootCause || "No root cause identified for this alert",
+        MarkdownContentType.Email,
+      ),
       alertViewLink: (
         await AlertService.getAlertLinkInDashboard(alert.projectId!, alert.id!)
       ).toString(),
@@ -4634,8 +4663,19 @@ export class Service extends DatabaseService<Model> {
         MarkdownContentType.Email,
       ),
       incidentSeverity: incident.incidentSeverity!.name!,
-      rootCause:
+      resourcesAffected:
+        (incident.monitors || [])
+          .map((monitor: Monitor): string => {
+            return monitor.name || "";
+          })
+          .filter((name: string): boolean => {
+            return name.length > 0;
+          })
+          .join(", ") || "No resources identified",
+      rootCause: await Markdown.convertToHTML(
         incident.rootCause || "No root cause identified for this incident",
+        MarkdownContentType.Email,
+      ),
       incidentViewLink: (
         await IncidentService.getIncidentLinkInDashboard(
           incident.projectId!,
@@ -4738,7 +4778,9 @@ export class Service extends DatabaseService<Model> {
     if (alerts.length > 0) {
       const alertRows: string[] = [];
       for (const alert of alerts) {
-        const alertTitle: string = alert.title || "Untitled Alert";
+        const alertTitle: string = Markdown.escapeHtml(
+          alert.title || "Untitled Alert",
+        );
         const alertNumber: string =
           alert.alertNumberWithPrefix ||
           (alert.alertNumber ? `#${alert.alertNumber}` : "");
@@ -4748,20 +4790,22 @@ export class Service extends DatabaseService<Model> {
             alert.id!,
           )
         ).toString();
-        const monitorName: string = alert.monitor?.name || "";
+        const monitorName: string = Markdown.escapeHtml(
+          alert.monitor?.name || "",
+        );
 
         alertRows.push(`
             <tr>
-              <td style="padding: 12px 16px; border-bottom: 1px solid #e2e8f0;">
-                <table cellpadding="0" cellspacing="0" width="100%">
+              <td style="padding: 16px 20px; border-bottom: 1px solid #e2e8f0; overflow-wrap: anywhere; word-break: break-word;">
+                <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed;">
                   <tr>
                     <td style="vertical-align: middle;">
-                      <span style="display: inline-block; background-color: #dbeafe; color: #1e40af; font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 4px; margin-right: 8px;">${alertNumber}</span>
-                      <a href="${alertLink}" style="color: #2563eb; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 14px; font-weight: 500; text-decoration: none;">${alertTitle}</a>
-                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 12px; margin-top: 4px;">Monitor: ${monitorName}</span>` : ""}
+                      <span style="display: inline-block; background-color: #f1f5f9; color: #111111; font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 4px; margin-right: 8px;">${alertNumber}</span>
+                      <a href="${alertLink}" style="color: #111111; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 15px; line-height: 24px; font-weight: 600; text-decoration: underline; text-underline-offset: 3px;">${alertTitle}</a>
+                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 13px; line-height: 20px; margin-top: 6px;">Monitor: ${monitorName}</span>` : ""}
                     </td>
-                    <td style="text-align: right; vertical-align: middle;">
-                      <a href="${alertLink}" style="color: #2563eb; font-size: 12px; text-decoration: none;">View →</a>
+                    <td width="52" style="text-align: right; vertical-align: middle; padding-left: 8px;">
+                      <a href="${alertLink}" style="color: #111111; font-size: 13px; line-height: 20px; text-decoration: underline;">View →</a>
                     </td>
                   </tr>
                 </table>
@@ -4771,7 +4815,7 @@ export class Service extends DatabaseService<Model> {
       }
       if (alertRows.length > 0) {
         alertsListHtml = `
-          <table cellpadding="0" cellspacing="0" width="100%" style="background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%); border-radius: 8px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0;">
+          <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed; background-color: #f8fafc; border-radius: 12px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;">
             <tbody>
               ${alertRows.join("")}
             </tbody>
@@ -4795,9 +4839,11 @@ export class Service extends DatabaseService<Model> {
       ),
       alertEpisodeSeverity: alertEpisode.alertSeverity!.name!,
       resourcesAffected: resourcesAffected,
-      rootCause:
+      rootCause: await Markdown.convertToHTML(
         alertEpisode.rootCause ||
-        "No root cause identified for this alert episode",
+          "No root cause identified for this alert episode",
+        MarkdownContentType.Email,
+      ),
       alertsList: alertsListHtml,
       alertsCount: alerts.length.toString(),
       alertEpisodeViewLink: (
@@ -4908,7 +4954,9 @@ export class Service extends DatabaseService<Model> {
     if (incidents.length > 0) {
       const incidentRows: string[] = [];
       for (const incident of incidents) {
-        const incidentTitle: string = incident.title || "Untitled Incident";
+        const incidentTitle: string = Markdown.escapeHtml(
+          incident.title || "Untitled Incident",
+        );
         const incidentNumber: string =
           incident.incidentNumberWithPrefix ||
           (incident.incidentNumber ? `#${incident.incidentNumber}` : "");
@@ -4918,7 +4966,7 @@ export class Service extends DatabaseService<Model> {
             incident.id!,
           )
         ).toString();
-        const monitorName: string =
+        const monitorName: string = Markdown.escapeHtml(
           (incident.monitors || [])
             .map((monitor: Monitor): string => {
               return monitor.name || "";
@@ -4926,20 +4974,21 @@ export class Service extends DatabaseService<Model> {
             .filter((name: string): boolean => {
               return name.length > 0;
             })
-            .join(", ") || "";
+            .join(", ") || "",
+        );
 
         incidentRows.push(`
             <tr>
-              <td style="padding: 12px 16px; border-bottom: 1px solid #e2e8f0;">
-                <table cellpadding="0" cellspacing="0" width="100%">
+              <td style="padding: 16px 20px; border-bottom: 1px solid #e2e8f0; overflow-wrap: anywhere; word-break: break-word;">
+                <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed;">
                   <tr>
                     <td style="vertical-align: middle;">
                       <span style="display: inline-block; background-color: #fee2e2; color: #991b1b; font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 4px; margin-right: 8px;">${incidentNumber}</span>
-                      <a href="${incidentLink}" style="color: #2563eb; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 14px; font-weight: 500; text-decoration: none;">${incidentTitle}</a>
-                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 12px; margin-top: 4px;">Monitor: ${monitorName}</span>` : ""}
+                      <a href="${incidentLink}" style="color: #111111; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 15px; line-height: 24px; font-weight: 600; text-decoration: underline; text-underline-offset: 3px;">${incidentTitle}</a>
+                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 13px; line-height: 20px; margin-top: 6px;">Monitor: ${monitorName}</span>` : ""}
                     </td>
-                    <td style="text-align: right; vertical-align: middle;">
-                      <a href="${incidentLink}" style="color: #2563eb; font-size: 12px; text-decoration: none;">View →</a>
+                    <td width="52" style="text-align: right; vertical-align: middle; padding-left: 8px;">
+                      <a href="${incidentLink}" style="color: #111111; font-size: 13px; line-height: 20px; text-decoration: underline;">View →</a>
                     </td>
                   </tr>
                 </table>
@@ -4949,7 +4998,7 @@ export class Service extends DatabaseService<Model> {
       }
       if (incidentRows.length > 0) {
         incidentsListHtml = `
-          <table cellpadding="0" cellspacing="0" width="100%" style="background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%); border-radius: 8px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0;">
+          <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed; background-color: #f8fafc; border-radius: 12px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;">
             <tbody>
               ${incidentRows.join("")}
             </tbody>
@@ -4975,9 +5024,11 @@ export class Service extends DatabaseService<Model> {
       ),
       incidentEpisodeSeverity: incidentEpisode.incidentSeverity!.name!,
       resourcesAffected: resourcesAffected,
-      rootCause:
+      rootCause: await Markdown.convertToHTML(
         incidentEpisode.rootCause ||
-        "No root cause identified for this incident episode",
+          "No root cause identified for this incident episode",
+        MarkdownContentType.Email,
+      ),
       incidentsList: incidentsListHtml,
       incidentsCount: incidents.length.toString(),
       incidentEpisodeViewLink: (

package/Server/Types/Database/Permissions/ReadPermission.ts

@@ -1,6 +1,7 @@
 import DatabaseRequestType from "../../BaseDatabase/DatabaseRequestType";
 import Query from "../Query";
 import QueryHelper from "../QueryHelper";
+import QueryUtil from "../QueryUtil";
 import RelationSelect from "../RelationSelect";
 import Select from "../Select";
 import SelectUtil from "../SelectUtil";
@@ -12,8 +13,11 @@ import DatabaseCommonInteractionPropsUtil, {
   PermissionType,
 } from "../../../../Types/BaseDatabase/DatabaseCommonInteractionPropsUtil";
 import ObjectID from "../../../../Types/ObjectID";
+import BadDataException from "../../../../Types/Exception/BadDataException";
 import Permission, { UserPermission } from "../../../../Types/Permission";
 import CaptureSpan from "../../../Utils/Telemetry/CaptureSpan";
+import { combineWithPrivacyClause } from "../../../Utils/PrivacyFilterUtil";
+import { FindOperator } from "typeorm";
 
 export interface CheckReadPermissionType<TBaseModel extends BaseModel>
   extends CheckPermissionBaseInterface<TBaseModel> {
@@ -119,13 +123,49 @@ export default class ReadPermission {
       }
     }
 
-    // now add these to query
-
     const model: TBaseModel = new modelType();
+    const accessControlColumn: string | null = model.getAccessControlColumn();
+    const manyToManyMeta: ReturnType<
+      typeof QueryUtil.getManyToManyRelationMetadata
+    > = accessControlColumn
+      ? QueryUtil.getManyToManyRelationMetadata(modelType, accessControlColumn)
+      : null;
+
+    if (!manyToManyMeta) {
+      throw new BadDataException(
+        "Cannot apply read label restrictions without access-control relation metadata.",
+      );
+    }
 
-    (query as any)[model.getAccessControlColumn() as string] = {
-      _id: QueryHelper.notInOrNull(labelIds),
-    };
+    const idQuery: Query<TBaseModel> = QueryUtil.serializeQuery(modelType, {
+      _id: query._id,
+    } as Query<TBaseModel>);
+    const existingIdFilter: unknown = idQuery._id;
+    if (
+      existingIdFilter !== undefined &&
+      typeof existingIdFilter !== "string" &&
+      !(existingIdFilter instanceof FindOperator)
+    ) {
+      throw new BadDataException(
+        "Cannot combine read label restrictions with an unsupported ID filter.",
+      );
+    }
+
+    /*
+     * Keep the caller's label selection intact. Blocking labels is a separate
+     * condition on the owner: it must have none of the blocked label links.
+     * Applying that condition to _id also lets grouped dashboard label filters
+     * and existing record selectors reach QueryUtil without being replaced.
+     * Serialize the ID condition first because QueryUtil does not descend into
+     * the database AND operator to convert application query operators later.
+     */
+    (query as any)._id = combineWithPrivacyClause(
+      existingIdFilter,
+      QueryHelper.noneEntitiesInManyToMany({
+        values: labelIds,
+        ...manyToManyMeta,
+      }),
+    );
 
     return { query };
   }

package/Server/Types/Database/QueryUtil.ts

@@ -7,6 +7,7 @@ import GreaterThanOrEqual from "../../../Types/BaseDatabase/GreaterThanOrEqual";
 import InBetween from "../../../Types/BaseDatabase/InBetween";
 import Includes from "../../../Types/BaseDatabase/Includes";
 import IncludesAll from "../../../Types/BaseDatabase/IncludesAll";
+import IncludesAnyOfGroups from "../../../Types/BaseDatabase/IncludesAnyOfGroups";
 import IncludesNone from "../../../Types/BaseDatabase/IncludesNone";
 import StartsWith from "../../../Types/BaseDatabase/StartsWith";
 import EndsWith from "../../../Types/BaseDatabase/EndsWith";
@@ -24,6 +25,7 @@ import { TableColumnMetadata } from "../../../Types/Database/TableColumn";
 import TableColumnType from "../../../Types/Database/TableColumnType";
 import { JSONObject } from "../../../Types/JSON";
 import ObjectID from "../../../Types/ObjectID";
+import BadDataException from "../../../Types/Exception/BadDataException";
 import Typeof from "../../../Types/Typeof";
 import { And, DataSource } from "typeorm";
 import { FindOperator } from "typeorm/find-options/FindOperator";
@@ -45,6 +47,7 @@ export default class QueryUtil {
     const model: BaseModel = new modelType();
 
     query = query as Query<TBaseModel>;
+    const groupedRelationFilters: Array<FindOperator<unknown>> = [];
 
     /*
      * Multi-field text search:
@@ -126,6 +129,37 @@ export default class QueryUtil {
       const tableColumnMetadata: TableColumnMetadata =
         model.getTableColumnMetadata(key);
 
+      if (query[key] instanceof IncludesAnyOfGroups) {
+        if (tableColumnMetadata?.type !== TableColumnType.EntityArray) {
+          throw new BadDataException(
+            "IncludesAnyOfGroups requires a many-to-many entity relation.",
+          );
+        }
+
+        const relation: {
+          joinTableName: string;
+          ownerColumnName: string;
+          relationColumnName: string;
+        } | null = QueryUtil.getManyToManyRelationMetadata(modelType, key);
+
+        if (!relation) {
+          throw new BadDataException(
+            "IncludesAnyOfGroups requires available many-to-many relation metadata.",
+          );
+        }
+
+        for (const group of (query[key] as IncludesAnyOfGroups).groups) {
+          groupedRelationFilters.push(
+            QueryHelper.anyOfEntitiesInManyToMany({
+              ...relation,
+              values: group,
+            }) as FindOperator<unknown>,
+          );
+        }
+        delete query[key];
+        continue;
+      }
+
       if (tableColumnMetadata && query[key] === null) {
         query[key] = QueryHelper.isNull();
       } else if (
@@ -634,6 +668,28 @@ export default class QueryUtil {
       }
     }
 
+    if (groupedRelationFilters.length > 0) {
+      /*
+       * Apply these only after scalar operators have been serialized, so an
+       * existing id condition survives regardless of the query's key order.
+       */
+      const existingIdFilter: unknown = query._id;
+      if (existingIdFilter !== undefined) {
+        if (existingIdFilter instanceof FindOperator) {
+          groupedRelationFilters.unshift(existingIdFilter);
+        } else if (typeof existingIdFilter === "string") {
+          groupedRelationFilters.unshift(
+            QueryHelper.equalTo(existingIdFilter) as FindOperator<unknown>,
+          );
+        } else {
+          throw new BadDataException(
+            "IncludesAnyOfGroups cannot combine an unsupported id filter.",
+          );
+        }
+      }
+      query._id = And(...groupedRelationFilters) as any;
+    }
+
     return query;
   }