@oneuptime/common 11.5.9 → 11.5.10

package/UI/Components/Charts/Utils/TimeAnnotation.ts

@@ -0,0 +1,169 @@
+import ChartReferenceRegionProps from "../Types/ReferenceRegionProps";
+import ChartTimeReferenceLineProps from "../Types/TimeReferenceLineProps";
+import FormattedReferenceRegion from "../ChartLibrary/Types/FormattedReferenceRegion";
+import FormattedTimeReferenceLine from "../ChartLibrary/Types/FormattedTimeReferenceLine";
+import { XAxis } from "../Types/XAxis/XAxis";
+import XAxisUtil from "./XAxis";
+
+interface AxisBuckets {
+  intervals: Array<Date>;
+  labels: Array<string>;
+  labelSet: Set<string>;
+  formatter: (value: Date) => string;
+}
+
+export default class TimeAnnotationUtil {
+  private static getAxisBuckets(xAxis: XAxis): AxisBuckets {
+    const intervals: Array<Date> = XAxisUtil.getPrecisionIntervals({
+      xAxisMin: xAxis.options.min,
+      xAxisMax: xAxis.options.max,
+    });
+    const formatter: (value: Date) => string = XAxisUtil.getFormatter({
+      xAxisMin: xAxis.options.min,
+      xAxisMax: xAxis.options.max,
+    });
+    const labels: Array<string> = intervals.map((interval: Date) => {
+      return formatter(interval);
+    });
+    return { intervals, labels, labelSet: new Set(labels), formatter };
+  }
+
+  /*
+   * End of the charted window: last bucket start plus one bucket width
+   * (buckets extend past their start date).
+   */
+  private static getWindowEndInMs(intervals: Array<Date>): number {
+    const lastInterval: Date | undefined = intervals[intervals.length - 1];
+    if (!lastInterval) {
+      return Number.NEGATIVE_INFINITY;
+    }
+    const secondToLastInterval: Date | undefined =
+      intervals[intervals.length - 2];
+    const bucketWidthInMs: number = secondToLastInterval
+      ? lastInterval.getTime() - secondToLastInterval.getTime()
+      : 0;
+    return lastInterval.getTime() + bucketWidthInMs;
+  }
+
+  /*
+   * Largest interval index whose bucket start is <= date, or null when
+   * the date falls before the first bucket.
+   */
+  private static getBucketIndexForDate(
+    intervals: Array<Date>,
+    date: Date,
+  ): number | null {
+    let bucketIndex: number | null = null;
+    for (let i: number = 0; i < intervals.length; i++) {
+      if (intervals[i]!.getTime() <= date.getTime()) {
+        bucketIndex = i;
+      } else {
+        break;
+      }
+    }
+    return bucketIndex;
+  }
+
+  /*
+   * Resolve a date to a bucket label that is guaranteed to exist on the
+   * categorical x-axis. Prefer formatter output — series datapoints are
+   * bucketed by the exact same formatter, so annotations land where data
+   * with the same timestamp lands. The formatter floors to wall-clock
+   * boundaries while buckets start at the raw window start, so its output
+   * can match no bucket; fall back to the bucket containing the date.
+   * Returns null when the date is outside the charted window.
+   */
+  private static resolveBucketLabel(data: {
+    date: Date;
+    buckets: AxisBuckets;
+  }): string | null {
+    const { intervals, labels, labelSet, formatter } = data.buckets;
+
+    const firstInterval: Date | undefined = intervals[0];
+    if (!firstInterval || data.date.getTime() < firstInterval.getTime()) {
+      return null;
+    }
+    if (data.date.getTime() > this.getWindowEndInMs(intervals)) {
+      return null;
+    }
+
+    const formatted: string = formatter(data.date);
+    if (labelSet.has(formatted)) {
+      return formatted;
+    }
+
+    const bucketIndex: number | null = this.getBucketIndexForDate(
+      intervals,
+      data.date,
+    );
+    if (bucketIndex === null) {
+      return null;
+    }
+    return labels[bucketIndex] ?? null;
+  }
+
+  public static formatTimeReferenceLines(data: {
+    timeReferenceLines: Array<ChartTimeReferenceLineProps>;
+    xAxis: XAxis;
+  }): Array<FormattedTimeReferenceLine> {
+    const buckets: AxisBuckets = this.getAxisBuckets(data.xAxis);
+
+    const formatted: Array<FormattedTimeReferenceLine> = [];
+    for (const timeReferenceLine of data.timeReferenceLines) {
+      const formattedX: string | null = this.resolveBucketLabel({
+        date: timeReferenceLine.date,
+        buckets,
+      });
+      if (formattedX === null) {
+        continue; // outside the charted window
+      }
+      formatted.push({ formattedX, original: timeReferenceLine });
+    }
+    return formatted;
+  }
+
+  public static formatReferenceRegions(data: {
+    referenceRegions: Array<ChartReferenceRegionProps>;
+    xAxis: XAxis;
+  }): Array<FormattedReferenceRegion> {
+    const buckets: AxisBuckets = this.getAxisBuckets(data.xAxis);
+    const firstInterval: Date | undefined = buckets.intervals[0];
+    const lastLabel: string | undefined =
+      buckets.labels[buckets.labels.length - 1];
+    if (!firstInterval || lastLabel === undefined) {
+      return [];
+    }
+    const windowEndInMs: number = this.getWindowEndInMs(buckets.intervals);
+
+    const formatted: Array<FormattedReferenceRegion> = [];
+    for (const referenceRegion of data.referenceRegions) {
+      const startInMs: number = Math.min(
+        referenceRegion.startDate.getTime(),
+        referenceRegion.endDate.getTime(),
+      );
+      const endInMs: number = Math.max(
+        referenceRegion.startDate.getTime(),
+        referenceRegion.endDate.getTime(),
+      );
+
+      // Entirely outside the charted window — nothing to draw.
+      if (endInMs < firstInterval.getTime() || startInMs > windowEndInMs) {
+        continue;
+      }
+
+      /*
+       * A region overlapping the window edge clamps to the nearest
+       * in-window bucket rather than vanishing.
+       */
+      const formattedX1: string =
+        this.resolveBucketLabel({ date: new Date(startInMs), buckets }) ||
+        buckets.labels[0]!;
+      const formattedX2: string =
+        this.resolveBucketLabel({ date: new Date(endInMs), buckets }) ||
+        lastLabel;
+
+      formatted.push({ formattedX1, formattedX2, original: referenceRegion });
+    }
+    return formatted;
+  }
+}

package/UI/Components/Charts/Utils/XAxis.ts

@@ -32,10 +32,12 @@ export default class XAxisUtil {
     const totalMonths: number = totalDays / 30;
 
     /*
-     * Mirror the server's aggregation interval (see
-     * AggregateUtil.getAggregationInterval) so the chart renders one
-     * point per backend bucket instead of re-bucketing them into
-     * coarser groups. Previously a 1h range was rendered with EVERY_
+     * Mirror the server's aggregation interval ladder (see
+     * AggregationIntervalUtil.getAggregationIntervalForWindow: 3h →
+     * Minute, 12h → FiveMinutes, 24h → FifteenMinutes, 3d →
+     * ThirtyMinutes, 7d → Hour, ...) so the chart renders one point
+     * per backend bucket instead of re-bucketing them into coarser
+     * groups. Previously a 1h range was rendered with EVERY_
      * FIVE_MINUTES (~12 points) even though the server returned 60
      * per-minute rows. Recharts thins the X-axis label set via
      * `interval="equidistantPreserveStart"`, so high point counts do
@@ -56,6 +58,15 @@ export default class XAxisUtil {
     if (totalHours <= 3) {
       return XAxisPrecision.EVERY_MINUTE;
     }
+    if (totalHours <= 12) {
+      return XAxisPrecision.EVERY_FIVE_MINUTES;
+    }
+    if (totalHours <= 24) {
+      return XAxisPrecision.EVERY_FIFTEEN_MINUTES;
+    }
+    if (totalDays <= 3) {
+      return XAxisPrecision.EVERY_THIRTY_MINUTES;
+    }
     if (totalDays <= 7) {
       return XAxisPrecision.EVERY_HOUR;
     }
@@ -116,6 +127,9 @@ export default class XAxisUtil {
         case XAxisPrecision.EVERY_TEN_MINUTES:
           currentDate.setMinutes(currentDate.getMinutes() + 10);
           break;
+        case XAxisPrecision.EVERY_FIFTEEN_MINUTES:
+          currentDate.setMinutes(currentDate.getMinutes() + 15);
+          break;
         case XAxisPrecision.EVERY_THIRTY_MINUTES:
           currentDate.setMinutes(currentDate.getMinutes() + 30);
           break;
@@ -239,6 +253,16 @@ export default class XAxisUtil {
           const roundedMinutes: number = Math.floor(minutes / 10) * 10;
           roundedValue.setMinutes(roundedMinutes, 0, 0);
 
+          return OneUptimeDate.getLocalTimeString(roundedValue);
+        };
+      case XAxisPrecision.EVERY_FIFTEEN_MINUTES:
+        // round down to nearest 15 minutes
+        return (value: Date) => {
+          const roundedValue: Date = this.cloneDate(value);
+          const minutes: number = roundedValue.getMinutes();
+          const roundedMinutes: number = Math.floor(minutes / 15) * 15;
+          roundedValue.setMinutes(roundedMinutes, 0, 0);
+
           return OneUptimeDate.getLocalTimeString(roundedValue);
         };
       case XAxisPrecision.EVERY_THIRTY_MINUTES:

package/UI/Components/Icon/Icon.tsx

@@ -2938,21 +2938,41 @@ const Icon: FunctionComponent<ComponentProps> = ({
     );
   } else if (icon === IconProp.Podman) {
     /*
-     * Podman mark — a clean side-profile silhouette of Podman's seal mascot:
-     * head raised with a visible eye, an arched back, and trailing tail
-     * flippers. The official emblem (a finely detailed seal inside a hexagonal
-     * frame) collapses into an illegible blob at small sizes, so this reads as
-     * a recognizable little sea creature down to ~16px and sits well beside the
-     * other resource brand logos (Docker / Proxmox / Ceph). The eye is punched
-     * out via the even-odd fill rule.
+     * Podman mark — the seal mascot's face inside the octagon from Podman's
+     * emblem. The official artwork (a mother seal flanked by two pups, with
+     * whiskers and water lines, all inside the octagon) turns to mush below
+     * ~48px, so this keeps only the cues that survive at icon sizes: the
+     * octagonal frame, the brow arches, the eyes and the round muzzle. The
+     * octagon doubles as the head outline so there is a single silhouette
+     * rather than two nested rings, and its straight edges stay crisp down to
+     * 16px next to the other resource brand logos (Docker / Proxmox / Ceph).
      */
     return getSvgWrapper(
-      <path
-        fill="currentColor"
-        stroke="none"
-        fillRule="evenodd"
-        d="M6.6 8.4C6.2 6.6 7.4 5 9.2 4.9c1.6-.1 2.9 1 3.5 2.2.7-.5 1.7-.7 2.5-.2.6.36.8 1.06.5 1.6 1.9 1.3 3.2 3.4 3.6 5.9.9-.15 1.9.15 2.3.95.35.75-.2 1.45-1.1 1.7-1.5.42-3.2-.15-4.1-1.5-.3.95-.9 1.75-1.7 2.25 1.2.5 2 1.2 1.6 2-.3.6-1.2.7-2.2.4-1.7-.5-3-1.9-3.4-3.6-.9.9-2.2 1.4-3.5 1.3-1-.1-1.5-.8-1.2-1.5.25-.6.9-.9 1.6-1-1-1.5-1.5-3.4-1.4-5.3-.6-.3-1.05-.85-1.1-1.55ZM8.4 8a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z"
-      />,
+      <>
+        {/* Octagonal frame of the emblem, doubling as the seal's head */}
+        <path
+          strokeLinejoin="round"
+          d="M15.79 2.85H8.21L2.85 8.21v7.58l5.36 5.36h7.58l5.36-5.36V8.21Z"
+        />
+        {/* Brow arches */}
+        <path
+          strokeWidth="1.2"
+          strokeLinecap="round"
+          d="M7.7 8.3C8.2 7.7 9.2 7.6 9.9 8M16.3 8.3C15.8 7.7 14.8 7.6 14.1 8"
+        />
+        {/* Eyes */}
+        <circle cx="9.1" cy="10.7" r="1.25" fill="currentColor" stroke="none" />
+        <circle
+          cx="14.9"
+          cy="10.7"
+          r="1.25"
+          fill="currentColor"
+          stroke="none"
+        />
+        {/* Muzzle and nose */}
+        <circle cx="12" cy="15.2" r="2.6" />
+        <circle cx="12" cy="14.35" r="0.6" fill="currentColor" stroke="none" />
+      </>,
     );
   } else if (icon === IconProp.Proxmox) {
     // Proxmox official logo mark (Simple Icons, CC0) — single filled path.

package/UI/Components/Markdown.tsx/MarkdownViewer.tsx

@@ -10,6 +10,15 @@ import React, {
 import ReactMarkdown from "react-markdown";
 // https://github.com/remarkjs/remark-gfm
 import remarkGfm from "remark-gfm";
+/*
+ * @types/react-syntax-highlighter declares every deep subpath below as ambient
+ * `declare module` blocks inside its single index.d.ts, and that file only enters the
+ * program when something resolves the bare specifier. Nothing else does, so without
+ * this line the deep imports fall back to untyped .js and every one of them errors
+ * TS7016. `import type` is erased at emit, so the deep imports below still tree-shake;
+ * importing the barrel as a value would drag in highlight.js and the full language set.
+ */
+import type {} from "react-syntax-highlighter";
 import SyntaxHighlighter from "react-syntax-highlighter/dist/esm/prism-light";
 import { vscDarkPlus } from "react-syntax-highlighter/dist/esm/styles/prism";
 import javascript from "react-syntax-highlighter/dist/esm/languages/prism/javascript";

package/UI/Components/MonitorTemplateVariables/TemplateVariablesCatalog.ts

@@ -369,6 +369,73 @@ export default class TemplateVariablesCatalog {
               description:
                 "Array of {oid, name, value, type}. Each named OID is also exposed directly — e.g. a `.sysUpTime` OID resolves as `{{sysUpTime}}`.",
             },
+            {
+              key: "sysName",
+              description: "Device name from the SNMP system group.",
+              example: "core-switch-01",
+            },
+            {
+              key: "sysDescr",
+              description: "Device description from the SNMP system group.",
+              example: "Cisco IOS Software, C2960X ...",
+            },
+            {
+              key: "sysObjectId",
+              description:
+                "Vendor's registered enterprise OID — the device fingerprint.",
+              example: "1.3.6.1.4.1.9.1.716",
+            },
+            {
+              key: "sysLocation",
+              description: "Device location from the SNMP system group.",
+              example: "DC1 Rack 42",
+            },
+            {
+              key: "downInterfaces",
+              description:
+                "Array of {name, alias, interfaceIndex} for interfaces that are administratively up but operationally down. Requires interface monitoring. Use `{{downInterfaces.0.name}}` or a `{{#each downInterfaces}}` loop.",
+              example: '[{"name":"Gi0/1","alias":"uplink","interfaceIndex":1}]',
+            },
+            {
+              key: "interfacesTotal",
+              description:
+                "Total number of interfaces walked. Requires interface monitoring.",
+              example: "48",
+            },
+            {
+              key: "interfacesUp",
+              description:
+                "Number of interfaces that are administratively and operationally up.",
+              example: "46",
+            },
+            {
+              key: "interfacesDown",
+              description:
+                "Number of interfaces that are administratively up but operationally down.",
+              example: "2",
+            },
+            {
+              key: "interfaceWalkFailure",
+              description:
+                "Error message when the interface walk failed, empty otherwise.",
+            },
+            {
+              key: "trapOid",
+              description:
+                "Trap OID — only set when this check was triggered by an SNMP trap.",
+              example: "1.3.6.1.6.3.1.1.5.3",
+            },
+            {
+              key: "trapSourceIp",
+              description:
+                "Source IP address the trap was received from — only set on trap-triggered checks.",
+              example: "10.0.0.1",
+            },
+            {
+              key: "trapVarbinds",
+              description:
+                "Array of {oid, value} varbinds carried by the trap — only set on trap-triggered checks.",
+            },
           ],
         };
 

package/UI/Components/Page/ModelPage.tsx

@@ -96,8 +96,13 @@ const ModelPage: <TBaseModel extends BaseModel>(
     } catch (err) {
       setLabels([]);
       setError(API.getFriendlyMessage(err));
+    } finally {
+      /*
+       * Must run even on the early "item not found" return above —
+       * otherwise the page shows its loader forever instead of the error.
+       */
+      setIsLoading(false);
     }
-    setIsLoading(false);
   };
 
   const [title, setTitle] = useState<string | undefined>(props.title);

package/UI/Components/TelemetryViewer/components/SavedViewsDropdown.tsx

@@ -1,6 +1,8 @@
 import React, { FunctionComponent, ReactElement } from "react";
 import { SavedViewOption } from "../types";
 import useComponentOutsideClick from "../../../Types/UseComponentOutsideClick";
+import Icon from "../../Icon/Icon";
+import IconProp from "../../../../Types/Icon/IconProp";
 
 export interface SavedViewsDropdownProps {
   savedViews: Array<SavedViewOption>;
@@ -10,10 +12,13 @@ export interface SavedViewsDropdownProps {
   onEdit?: ((viewId: string) => void) | undefined;
   onDelete?: ((viewId: string) => void) | undefined;
   onUpdateCurrent?: (() => void) | undefined;
+  triggerClassName?: string | undefined;
+  showTriggerIcon?: boolean | undefined;
+  dropdownAlignment?: "left" | "right" | undefined;
 }
 
 const triggerButtonClassName: string =
-  "inline-flex items-center gap-1.5 rounded-md border border-gray-200 bg-white px-2.5 py-1.5 text-xs font-medium text-gray-700 shadow-sm transition-colors hover:border-gray-300 hover:bg-gray-50";
+  "inline-flex items-center gap-1.5 rounded-md border border-gray-200 bg-white px-2.5 py-1.5 text-xs font-medium text-gray-700 shadow-sm transition-colors hover:border-gray-300 hover:bg-gray-50 focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-400";
 
 const SavedViewsDropdown: FunctionComponent<SavedViewsDropdownProps> = (
   props: SavedViewsDropdownProps,
@@ -31,23 +36,47 @@ const SavedViewsDropdown: FunctionComponent<SavedViewsDropdownProps> = (
     <div className="relative" ref={ref}>
       <button
         type="button"
-        className={triggerButtonClassName}
+        className={`${triggerButtonClassName} ${props.triggerClassName || ""}`}
         onClick={() => {
           setIsComponentVisible(!isComponentVisible);
         }}
         aria-haspopup="dialog"
         aria-expanded={isComponentVisible}
       >
+        {props.showTriggerIcon ? (
+          <Icon
+            icon={IconProp.Bookmark}
+            className="h-3.5 w-3.5 text-gray-500"
+          />
+        ) : null}
         <span className="max-w-40 truncate">
           {selectedView?.name || "Saved Views"}
         </span>
-        <span className="text-xs text-gray-400">
+        <span
+          className={`text-xs text-gray-400 ${
+            props.showTriggerIcon
+              ? "rounded-md bg-gray-100 px-1.5 py-0.5 text-[10px] font-semibold"
+              : ""
+          }`}
+        >
           {props.savedViews.length.toLocaleString()}
         </span>
+        {props.showTriggerIcon ? (
+          <Icon
+            icon={IconProp.ChevronDown}
+            className={`h-3 w-3 text-gray-400 transition-transform ${
+              isComponentVisible ? "rotate-180" : ""
+            }`}
+          />
+        ) : null}
       </button>
 
       {isComponentVisible && (
-        <div className="absolute left-0 z-20 mt-2 w-72 rounded-lg border border-gray-200 bg-white shadow-xl">
+        <div
+          className={`absolute z-20 mt-2 w-72 rounded-lg border border-gray-200 bg-white shadow-xl ${
+            props.dropdownAlignment === "right" ? "right-0" : "left-0"
+          }`}
+        >
           {/* View list */}
           <div className="max-h-72 overflow-y-auto py-1">
             {props.savedViews.length === 0 && (

package/UI/Styles/Theme.css

@@ -688,6 +688,11 @@ html.dark :is(
   color: #fcd34d;
 }
 
+/* Hint-chip icons (metric viewer) use the lighter amber accent. */
+html.dark .text-amber-500 {
+  color: #fbbf24;
+}
+
 html.dark :is(
     .text-yellow-600,
     .text-yellow-700,
@@ -870,6 +875,11 @@ html.dark :is(
   --tw-ring-color: rgb(129 140 248 / 35%);
 }
 
+/* Formula-card variable badges (metric viewer). */
+html.dark .border-violet-200 {
+  border-color: rgb(129 140 248 / 45%);
+}
+
 html.dark :is(
     .border-yellow-100,
     .border-yellow-200,

package/UI/Utils/User.ts

@@ -213,15 +213,54 @@ export default class UserUtil {
     const result: Dictionary<string> = {};
 
     for (const key in localStorageItems) {
-      if (!localStorageItems[key]) {
+      const value: string = localStorageItems[key] as string;
+
+      /*
+       * Older versions of the marketing site stored the literal strings
+       * "null" / "undefined" for missing utm params. Filter those out so
+       * they never end up on the User record.
+       */
+      if (!value || value === "null" || value === "undefined") {
         continue;
       }
 
       if (key.startsWith("utm")) {
-        result[key] = localStorageItems[key] as string;
+        result[key] = value;
       }
     }
 
     return result;
   }
+
+  // Ad platform click IDs (gclid, fbclid, etc.) stored by the marketing site.
+  public static getAttributionClickIds(): JSONObject | null {
+    return UserUtil.parseJsonLocalStorageItem("clickIds");
+  }
+
+  // First attributed touch (utm params, click IDs, landing URL) — never overwritten.
+  public static getFirstTouchAttribution(): JSONObject | null {
+    return UserUtil.parseJsonLocalStorageItem("firstTouch");
+  }
+
+  private static parseJsonLocalStorageItem(key: string): JSONObject | null {
+    /*
+     * LocalStorage.getItem JSON-parses stored strings when it can, so this
+     * may already be an object; fall back to parsing the raw string.
+     */
+    let value: JSONValue = LocalStorage.getItem(key);
+
+    if (typeof value === "string") {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        return null;
+      }
+    }
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return value as JSONObject;
+    }
+
+    return null;
+  }
 }

package/Utils/Analytics.ts

@@ -33,14 +33,16 @@ export default class Analytics {
   }
 
   public capture(eventName: string, data?: JSONObject): void {
-    if (!this.isInitialized) {
-      return;
-    }
-
     // PostHog tracking
-    posthog.capture(eventName, data);
+    if (this.isInitialized) {
+      posthog.capture(eventName, data);
+    }
 
-    // GA4 tracking via dataLayer (for Google Analytics conversion tracking)
+    /*
+     * GA4 tracking via dataLayer (for Google Analytics / Google Ads conversion
+     * tracking). This must not depend on PostHog being configured — GTM is
+     * loaded independently of ANALYTICS_KEY / ANALYTICS_HOST.
+     */
     if (typeof window !== "undefined" && (window as any).dataLayer) {
       (window as any).dataLayer.push({
         event: eventName,

package/Utils/EnterpriseLicense/EnterpriseLicenseUsage.ts

@@ -13,6 +13,33 @@ export interface EnterpriseLicenseInstanceUsage {
 }
 
 export default class EnterpriseLicenseUsageUtil {
+  /*
+   * How many days before a license expires that expiry reminder emails
+   * start going out, unless overridden in GlobalConfig
+   * (enterpriseLicenseExpiryReminderDays).
+   */
+  public static readonly defaultExpiryReminderDays: number = 45;
+
+  /*
+   * Expired licenses keep getting a daily "expired" email for this many
+   * days after expiry, then go quiet — an abandoned license should not be
+   * emailed forever.
+   */
+  public static readonly expiredNotificationCutoffDays: number = 30;
+
+  /*
+   * License keys are shown/emailed masked — enough to identify the key
+   * without exposing it in full.
+   */
+  public static maskLicenseKey(licenseKey: string): string {
+    if (licenseKey.length <= 8) {
+      return "••••••••";
+    }
+
+    return `${licenseKey.substring(0, 4)}••••${licenseKey.substring(
+      licenseKey.length - 4,
+    )}`;
+  }
   /*
    * Instances that stopped reporting (for example a decommissioned staging
    * environment) stop counting towards the seat total after this many days,
@@ -25,6 +52,53 @@ export default class EnterpriseLicenseUsageUtil {
 
   public static readonly maxEmailHashesPerInstance: number = 200_000;
 
+  /*
+   * Master admin emails are used to contact the customer about license
+   * issues — a handful per instance is plenty, and the cap keeps a
+   * misbehaving client from storing an unbounded list.
+   */
+  public static readonly maxMasterAdminEmailsPerInstance: number = 50;
+
+  // Deliberately loose: rejects garbage, accepts anything email-shaped.
+  private static readonly emailRegex: RegExp = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+  /*
+   * Normalizes a client-provided list of master admin emails: keeps only
+   * email-shaped strings, lowercases them, removes duplicates and caps the
+   * list size. Returns an empty array for anything that is not an array.
+   */
+  public static sanitizeMasterAdminEmails(value: unknown): Array<string> {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    const emails: Set<string> = new Set<string>();
+
+    for (const item of value) {
+      if (emails.size >= this.maxMasterAdminEmailsPerInstance) {
+        break;
+      }
+
+      if (typeof item !== "string") {
+        continue;
+      }
+
+      const normalized: string = item.trim().toLowerCase();
+
+      if (
+        !normalized ||
+        normalized.length > 320 ||
+        !this.emailRegex.test(normalized)
+      ) {
+        continue;
+      }
+
+      emails.add(normalized);
+    }
+
+    return Array.from(emails);
+  }
+
   /*
    * Normalizes a client-provided list of email hashes: keeps only valid
    * SHA-256 hex strings, lowercases them, removes duplicates and caps the