@oneuptime/common 13.0.7 → 14.0.0

package/Tests/Utils/StatusPage/UptimeDailyAggregateUtil.test.ts

@@ -0,0 +1,248 @@
+import ObjectID from "../../../Types/ObjectID";
+import { JSONObject } from "../../../Types/JSON";
+import {
+  UptimeDailyAggregate,
+  UptimeDayBucket,
+} from "../../../Types/StatusPage/UptimeDailyAggregate";
+import UptimeDailyAggregateUtil from "../../../Utils/StatusPage/UptimeDailyAggregateUtil";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * WHAT THIS FILE IS DEFENDING
+ *
+ * The wire format for the uptime aggregate, which replaced shipping raw
+ * MonitorStatusTimeline rows to the status page.
+ *
+ * Two properties matter more than the round trip itself:
+ *
+ * 1. It must be SMALL. The rows it replaces serialize to ~431 bytes each,
+ *    almost entirely typed-JSON envelopes, so one real status page's 254,550
+ *    matching rows came to ~105 MB. If this format ever grows envelopes it
+ *    gives that back.
+ *
+ * 2. Parsing must be TOTAL. A status page that cannot read its aggregate has
+ *    to fall back to "no data", which is honest. What it must never do is
+ *    fall back to something that looks like uptime.
+ */
+
+const MONITOR_A: string = "11111111-1111-4111-8111-111111111111";
+const STATUS_UP: string = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+
+function sample(): UptimeDailyAggregate {
+  return {
+    monitors: [
+      {
+        monitorId: new ObjectID(MONITOR_A),
+        buckets: [
+          {
+            bucketStart: new Date("2026-07-01T00:00:00.000Z"),
+            bucketEnd: new Date("2026-07-02T00:00:00.000Z"),
+            daySeconds: 86400,
+            coveredSeconds: 86400,
+            statusDurations: [
+              {
+                monitorStatusId: new ObjectID(STATUS_UP),
+                seconds: 86400,
+              },
+            ],
+          },
+          {
+            bucketStart: new Date("2026-07-02T00:00:00.000Z"),
+            bucketEnd: new Date("2026-07-03T00:00:00.000Z"),
+            daySeconds: 86400,
+            coveredSeconds: 0,
+            statusDurations: [],
+          },
+        ],
+      },
+    ],
+    isComplete: true,
+    completeFrom: null,
+  };
+}
+
+describe("UptimeDailyAggregateUtil", () => {
+  describe("round trip", () => {
+    test("survives toJSON -> fromJSON unchanged", () => {
+      const parsed: UptimeDailyAggregate = UptimeDailyAggregateUtil.fromJSON(
+        UptimeDailyAggregateUtil.toJSON(sample()),
+      );
+
+      expect(parsed.monitors).toHaveLength(1);
+      expect(parsed.monitors[0]!.monitorId.toString()).toBe(MONITOR_A);
+      expect(parsed.monitors[0]!.buckets).toHaveLength(2);
+
+      const first: UptimeDayBucket = parsed.monitors[0]!.buckets[0]!;
+
+      expect(first.coveredSeconds).toBe(86400);
+      expect(first.daySeconds).toBe(86400);
+      expect(first.bucketStart.toISOString()).toBe("2026-07-01T00:00:00.000Z");
+      expect(first.statusDurations[0]!.monitorStatusId.toString()).toBe(
+        STATUS_UP,
+      );
+    });
+
+    test("a no-data day survives as a no-data day", () => {
+      /*
+       * The single most important thing to preserve. If coverage were lost in
+       * transit the client would treat the day as ordinary and paint it with
+       * the operator's colour - which is the bug this whole change removes.
+       */
+      const parsed: UptimeDailyAggregate = UptimeDailyAggregateUtil.fromJSON(
+        UptimeDailyAggregateUtil.toJSON(sample()),
+      );
+
+      expect(parsed.monitors[0]!.buckets[1]!.coveredSeconds).toBe(0);
+      expect(parsed.monitors[0]!.buckets[1]!.statusDurations).toHaveLength(0);
+    });
+  });
+
+  describe("the wire format stays small", () => {
+    test("dates and ids are plain strings, not typed-JSON envelopes", () => {
+      const json: JSONObject = UptimeDailyAggregateUtil.toJSON(sample());
+      const encoded: string = JSON.stringify(json);
+
+      expect(encoded).not.toContain("_type");
+      expect(encoded).toContain("2026-07-01T00:00:00.000Z");
+      expect(encoded).toContain(MONITOR_A);
+    });
+
+    test("a 90-day, 50-monitor page stays far below the row payload it replaces", () => {
+      /*
+       * The rows this replaces were ~431 bytes each and a real page matched
+       * 254,550 of them (~105 MB). This asserts the replacement is bounded by
+       * structure rather than by how much a monitor flaps.
+       */
+      const aggregate: UptimeDailyAggregate = {
+        monitors: [],
+        isComplete: true,
+        completeFrom: null,
+      };
+
+      for (let m: number = 0; m < 50; m++) {
+        const buckets: Array<UptimeDayBucket> = [];
+
+        for (let d: number = 0; d < 90; d++) {
+          const start: Date = new Date(
+            Date.UTC(2026, 3, 1) + d * 24 * 60 * 60 * 1000,
+          );
+
+          buckets.push({
+            bucketStart: start,
+            bucketEnd: new Date(start.getTime() + 86400000),
+            daySeconds: 86400,
+            coveredSeconds: 86400,
+            statusDurations: [
+              { monitorStatusId: new ObjectID(STATUS_UP), seconds: 86000 },
+              { monitorStatusId: new ObjectID(MONITOR_A), seconds: 400 },
+            ],
+          });
+        }
+
+        aggregate.monitors.push({
+          monitorId: new ObjectID(
+            `${MONITOR_A.slice(0, -2)}${m % 10}${m % 10}`,
+          ),
+          buckets,
+        });
+      }
+
+      const bytes: number = JSON.stringify(
+        UptimeDailyAggregateUtil.toJSON(aggregate),
+      ).length;
+
+      // Comfortably under a megabyte for the largest page the product allows.
+      expect(bytes).toBeLessThan(1_500_000);
+    });
+  });
+
+  describe("parsing is total", () => {
+    test.each([
+      ["null", null],
+      ["undefined", undefined],
+      ["an empty object", {}],
+      ["monitors not an array", { monitors: "nope" }],
+    ])(
+      "%s yields an empty aggregate rather than throwing",
+      (_name: string, input: unknown) => {
+        expect(() => {
+          return UptimeDailyAggregateUtil.fromJSON(input as JSONObject);
+        }).not.toThrow();
+
+        const parsed: UptimeDailyAggregate = UptimeDailyAggregateUtil.fromJSON(
+          input as JSONObject,
+        );
+
+        expect(parsed.monitors).toHaveLength(0);
+      },
+    );
+
+    test("a bucket with an unparseable date is dropped, not turned into coverage", () => {
+      const parsed: UptimeDailyAggregate = UptimeDailyAggregateUtil.fromJSON({
+        monitors: [
+          {
+            monitorId: MONITOR_A,
+            buckets: [
+              {
+                bucketStart: "not-a-date",
+                bucketEnd: "also-not",
+                daySeconds: 1,
+              },
+            ],
+          },
+        ],
+        weird: true,
+      } as unknown as JSONObject);
+
+      expect(parsed.monitors[0]!.buckets).toHaveLength(0);
+    });
+
+    test("a missing isComplete means complete, not incomplete", () => {
+      /*
+       * An older server has no cap in this path either. Defaulting to
+       * incomplete would grey out every bar on a perfectly healthy page.
+       */
+      const parsed: UptimeDailyAggregate = UptimeDailyAggregateUtil.fromJSON({
+        monitors: [],
+      } as unknown as JSONObject);
+
+      expect(parsed.isComplete).toBe(true);
+    });
+
+    test("an explicit isComplete false is honoured", () => {
+      const parsed: UptimeDailyAggregate = UptimeDailyAggregateUtil.fromJSON({
+        monitors: [],
+        isComplete: false,
+        completeFrom: "2026-07-05T00:00:00.000Z",
+      } as unknown as JSONObject);
+
+      expect(parsed.isComplete).toBe(false);
+      expect(parsed.completeFrom?.toISOString()).toBe(
+        "2026-07-05T00:00:00.000Z",
+      );
+    });
+  });
+
+  describe("getBucketsForMonitor", () => {
+    test("returns that monitor's buckets", () => {
+      expect(
+        UptimeDailyAggregateUtil.getBucketsForMonitor(sample(), MONITOR_A),
+      ).toHaveLength(2);
+    });
+
+    test("returns empty for a monitor that is not in the aggregate", () => {
+      expect(
+        UptimeDailyAggregateUtil.getBucketsForMonitor(
+          sample(),
+          "99999999-9999-4999-8999-999999999999",
+        ),
+      ).toHaveLength(0);
+    });
+
+    test("returns empty rather than throwing when there is no aggregate", () => {
+      expect(
+        UptimeDailyAggregateUtil.getBucketsForMonitor(null, MONITOR_A),
+      ).toHaveLength(0);
+    });
+  });
+});

package/Types/API/Hostname.ts

@@ -3,6 +3,8 @@ import BadDataException from "../Exception/BadDataException";
 import { JSONObject, ObjectType } from "../JSON";
 import Port from "../Port";
 import Typeof from "../Typeof";
+import HostAddressUtil from "../../Utils/HostAddressUtil";
+import IP from "../IP/IP";
 import { FindOperator } from "typeorm";
 
 /*
@@ -22,10 +24,26 @@ const HOST_REGEX: RegExp =
  */
 const USER_INFO_REGEX: RegExp = /^[^@/?#\s[\]]*$/;
 
-const IPV6_CHARS_REGEX: RegExp = /^[0-9a-fA-F:.]+$/;
-
 const PORT_REGEX: RegExp = /^\d{1,5}$/;
 
+/*
+ * The authority spellings of an IPv6 host: bracketed ("[::1]", "[::1]:8080")
+ * or bare. Two or more colons cannot be a "host:port", so every colon in a
+ * bare value belongs to the address itself.
+ *
+ * This only decides which SHAPE a value has. Whether what it holds is really
+ * an address is IP.isIP's job, and isValid below asks it -- the old code
+ * settled for a "[0-9a-fA-F:.]+" charset, which called "::::" and
+ * "1.2.3.4.5.6" valid hosts and then handed them to a socket.
+ */
+function isIPv6Authority(authority: string): boolean {
+  return authority.startsWith("[") || (authority.match(/:/g) || []).length > 1;
+}
+
+function isIPv6Address(value: string): boolean {
+  return Boolean(value) && IP.isIP(value) && new IP(value).isIPv6();
+}
+
 export default class Hostname extends DatabaseProperty {
   private _route: string = "";
   public get hostname(): string {
@@ -104,15 +122,15 @@ export default class Hostname extends DatabaseProperty {
       /^\[([0-9a-fA-F:.]+)\](?::(\d{1,5}))?$/,
     );
     if (bracketedIpv6Match) {
-      return true;
+      return isIPv6Address(bracketedIpv6Match[1] as string);
     }
 
     /*
      * Unbracketed IPv6 literal. Two or more colons cannot be a "host:port",
      * so the colons must be part of the address itself.
      */
-    if ((authority.match(/:/g) || []).length > 1) {
-      return IPV6_CHARS_REGEX.test(authority);
+    if (isIPv6Authority(authority)) {
+      return isIPv6Address(authority);
     }
 
     const colonIndex: number = authority.indexOf(":");
@@ -158,28 +176,57 @@ export default class Hostname extends DatabaseProperty {
     throw new BadDataException("Invalid JSON: " + JSON.stringify(json));
   }
 
+  /*
+   * The authority form. An IPv6 host is BRACKETED once a port is appended,
+   * because "2001:db8::1" + ":179" is not an ambiguous-looking string — it is
+   * "2001:db8::1:179", which net.isIP() accepts as a different, perfectly
+   * valid address. Anything that read this back (or showed it to an operator)
+   * was therefore pointed at a host nobody configured.
+   *
+   * Without a port the host is returned exactly as it is held, brackets and
+   * all. A bracketed value came from a URL authority and has to go back into
+   * one — dropping the brackets there would make URL.toString() emit
+   * "https://2001:db8::1/", which no URL parser accepts.
+   */
   public override toString(): string {
-    let hostname: string = this.hostname;
-
-    if (this.port) {
-      hostname += ":" + this.port.toString();
+    if (!this.port) {
+      return this.hostname;
     }
 
-    return hostname;
+    return HostAddressUtil.formatHostAndPort({
+      host: this.hostname,
+      port: this.port.toString(),
+    });
   }
 
+  /*
+   * Reads a stored host, which may carry a ":port".
+   *
+   * IPv6 literals are handed to fromAuthority instead of being split, because
+   * splitting on the first colon is meaningless for an address that is made
+   * of colons: "2001:518:2800:9::2" used to come back as host "2001" with
+   * port 518 — and because 518 is a legal port number NOTHING threw. A
+   * monitor saved from the dashboard therefore silently pointed at a host
+   * called "2001", and the address the operator typed was simply gone.
+   *
+   * DNS names and IPv4 literals keep the original behaviour exactly: neither
+   * can contain two colons, so neither can reach the new branch.
+   */
   public static fromString(hostname: string | Hostname): Hostname {
     if (hostname instanceof Hostname) {
       hostname = hostname.toString();
     }
 
-    if (hostname.includes(":")) {
-      return new Hostname(
-        hostname.split(":")[0] as string,
-        hostname.split(":")[1],
-      );
+    const value: string = (hostname || "").trim();
+
+    if (isIPv6Authority(value)) {
+      return Hostname.fromAuthority(value);
+    }
+
+    if (value.includes(":")) {
+      return new Hostname(value.split(":")[0] as string, value.split(":")[1]);
     }
-    return new Hostname(hostname);
+    return new Hostname(value);
   }
 
   /*

package/Types/BaseDatabase/DatabaseCommonInteractionPropsUtil.ts

@@ -1,5 +1,7 @@
 import Permission, { UserPermission } from "../Permission";
 import DatabaseCommonInteractionProps from "./DatabaseCommonInteractionProps";
+import NotAuthenticatedException from "../Exception/NotAuthenticatedException";
+import UserType from "../UserType";
 
 export enum PermissionType {
   Allow = "Allow",
@@ -7,6 +9,44 @@ export enum PermissionType {
 }
 
 export default class DatabaseCommonInteractionPropsUtil {
+  public static readonly AUTHENTICATION_REQUIRED_MESSAGE: string =
+    "Authentication required. Please log in to access this resource.";
+
+  /*
+   * No credentials at all: no user, no project API key, no master key.
+   *
+   * In practice this is almost never a stranger. The dashboard's access-token
+   * cookie expires together with the JWT inside it, so once a tab has sat idle
+   * past the token lifetime the browser simply stops sending it, and
+   * getUserMiddleware lets the request through as Public with no userId. The
+   * caller is a signed-in user whose session needs refreshing.
+   */
+  public static isAnonymous(props: DatabaseCommonInteractionProps): boolean {
+    if (props.userId) {
+      return false;
+    }
+
+    return (
+      props.userType !== UserType.API && props.userType !== UserType.MasterAdmin
+    );
+  }
+
+  /*
+   * "Who are you?" comes before "may you?". An anonymous caller has to be
+   * refused with 401, never 422 or 400: the browser client refreshes the
+   * session and replays the request on a 401 and on nothing else, so any other
+   * status leaves a signed-in user looking at a bogus error.
+   */
+  public static assertCredentialsPresent(
+    props: DatabaseCommonInteractionProps,
+  ): void {
+    if (DatabaseCommonInteractionPropsUtil.isAnonymous(props)) {
+      throw new NotAuthenticatedException(
+        DatabaseCommonInteractionPropsUtil.AUTHENTICATION_REQUIRED_MESSAGE,
+      );
+    }
+  }
+
   public static getUserPermissions(
     props: DatabaseCommonInteractionProps,
     permissionType: PermissionType,

package/Types/Database/AccessControl/ColumnAccessControl.ts

@@ -1,5 +1,6 @@
 import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import { ColumnAccessControl } from "../../BaseDatabase/AccessControl";
+import getCanonicalModelInstance from "../CanonicalModelInstance";
 import Dictionary from "../../Dictionary";
 import { ReflectionMetadataType } from "../../Reflection";
 import "reflect-metadata";
@@ -31,10 +32,12 @@ type GetColumnAccessControlForAllColumnsFunction = <T extends BaseModel>(
 ) => Dictionary<ColumnAccessControl>;
 
 /*
- * Per-class cache. Safe to key on the constructor because every decorated
- * column is initialised to `undefined` in the class body, so Object.keys()
- * is identical for every instance of a class (see OwnerOnlyColumn.ts).
- * Callers must treat the returned dictionary as read-only.
+ * Per-class cache, keyed on the constructor and built from a canonical
+ * instance of that class rather than from whichever instance asked first, so
+ * a caller that has deleted a column off its own instance cannot define what
+ * the class reports for the rest of the process. See
+ * CanonicalModelInstance.ts for the bug this prevents. Callers must treat the
+ * returned dictionary as read-only.
  */
 const accessControlCache: WeakMap<
   { new (): BaseModel },
@@ -50,12 +53,14 @@ export const getColumnAccessControlForAllColumns: GetColumnAccessControlForAllCo
       accessControlCache.get(modelClass);
 
     if (!cached) {
+      const canonical: T | null = getCanonicalModelInstance(target);
+      const metadataSource: T = canonical || target;
       const dictonary: Dictionary<ColumnAccessControl> = {};
-      const keys: Array<string> = Object.keys(target);
+      const keys: Array<string> = Object.keys(metadataSource);
 
       for (const key of keys) {
         const accessControl: ColumnAccessControl | undefined =
-          Reflect.getMetadata(accessControlSymbol, target, key) as
+          Reflect.getMetadata(accessControlSymbol, metadataSource, key) as
             | ColumnAccessControl
             | undefined;
         if (accessControl) {
@@ -64,7 +69,14 @@ export const getColumnAccessControlForAllColumns: GetColumnAccessControlForAllCo
       }
 
       cached = dictonary;
-      accessControlCache.set(modelClass, cached);
+      /*
+       * No canonical instance (see CanonicalModelInstance): answer from the
+       * instance we were handed, but do NOT cache it for the class - that
+       * instance may be a mutilated one, and a cached answer outlives it.
+       */
+      if (canonical) {
+        accessControlCache.set(modelClass, cached);
+      }
     }
 
     return cached;

package/Types/Database/AccessControl/ColumnBillingAccessControl.ts

@@ -1,5 +1,6 @@
 import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import ColumnBillingAccessControl from "../../BaseDatabase/ColumnBillingAccessControl";
+import getCanonicalModelInstance from "../CanonicalModelInstance";
 import Dictionary from "../../Dictionary";
 import { ReflectionMetadataType } from "../../Reflection";
 import "reflect-metadata";
@@ -31,10 +32,12 @@ type GetColumnBillingAccessControlForAllColumnsFunction = <T extends BaseModel>(
 ) => Dictionary<ColumnBillingAccessControl>;
 
 /*
- * Per-class cache. Safe to key on the constructor because every decorated
- * column is initialised to `undefined` in the class body, so Object.keys()
- * is identical for every instance of a class (see OwnerOnlyColumn.ts).
- * Callers must treat the returned dictionary as read-only.
+ * Per-class cache, keyed on the constructor and built from a canonical
+ * instance of that class rather than from whichever instance asked first, so
+ * a caller that has deleted a column off its own instance cannot define what
+ * the class reports for the rest of the process. See
+ * CanonicalModelInstance.ts for the bug this prevents. Callers must treat the
+ * returned dictionary as read-only.
  */
 const billingAccessControlCache: WeakMap<
   { new (): BaseModel },
@@ -50,12 +53,14 @@ export const getColumnBillingAccessControlForAllColumns: GetColumnBillingAccessC
       billingAccessControlCache.get(modelClass);
 
     if (!cached) {
+      const canonical: T | null = getCanonicalModelInstance(target);
+      const metadataSource: T = canonical || target;
       const dictonary: Dictionary<ColumnBillingAccessControl> = {};
-      const keys: Array<string> = Object.keys(target);
+      const keys: Array<string> = Object.keys(metadataSource);
 
       for (const key of keys) {
         const accessControl: ColumnBillingAccessControl | undefined =
-          Reflect.getMetadata(accessControlSymbol, target, key) as
+          Reflect.getMetadata(accessControlSymbol, metadataSource, key) as
             | ColumnBillingAccessControl
             | undefined;
         if (accessControl) {
@@ -64,7 +69,14 @@ export const getColumnBillingAccessControlForAllColumns: GetColumnBillingAccessC
       }
 
       cached = dictonary;
-      billingAccessControlCache.set(modelClass, cached);
+      /*
+       * No canonical instance (see CanonicalModelInstance): answer from the
+       * instance we were handed, but do NOT cache it for the class - that
+       * instance may be a mutilated one, and a cached answer outlives it.
+       */
+      if (canonical) {
+        billingAccessControlCache.set(modelClass, cached);
+      }
     }
 
     return cached;

package/Types/Database/AccessControl/OwnerOnlyColumn.ts

@@ -1,4 +1,5 @@
 import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import getCanonicalModelInstance from "../CanonicalModelInstance";
 import { ReflectionMetadataType } from "../../Reflection";
 import "reflect-metadata";
 
@@ -66,10 +67,14 @@ type GetOwnerOnlyColumnsFunction = <T extends BaseModel>(
 ) => Array<string>;
 
 /**
- * Every owner-only column on this model. Enumerating requires the property to
- * exist on the instance, which it does for every declared column because model
- * columns are initialised to `undefined` in the class body - the same
- * assumption getTableColumns() already makes.
+ * Every owner-only column on this model. Which columns a MODEL marks is a
+ * property of the class, so the enumeration reads a canonical instance of the
+ * class rather than the caller's own instance: a caller that had deleted a
+ * key off its instance would otherwise get an answer that silently omits a
+ * marked column, and this list is what OwnerOnlyColumnPermission enforces
+ * against. See CanonicalModelInstance.ts. (Enumerating at all relies on every
+ * declared column being initialised to `undefined` in the class body - the
+ * same assumption getTableColumns() makes.)
  */
 export const getOwnerOnlyColumns: GetOwnerOnlyColumnsFunction = <
   T extends BaseModel,
@@ -77,9 +82,13 @@ export const getOwnerOnlyColumns: GetOwnerOnlyColumnsFunction = <
   target: T,
 ): Array<string> => {
   const columns: Array<string> = [];
+  // Nothing is cached here, so falling back to the caller's instance is safe.
+  const metadataSource: T = getCanonicalModelInstance(target) || target;
 
-  for (const key of Object.keys(target)) {
-    if (Reflect.getMetadata(ownerOnlyColumnSymbol, target, key) === true) {
+  for (const key of Object.keys(metadataSource)) {
+    if (
+      Reflect.getMetadata(ownerOnlyColumnSymbol, metadataSource, key) === true
+    ) {
       columns.push(key);
     }
   }

package/Types/Database/CanonicalModelInstance.ts

@@ -0,0 +1,102 @@
+/*
+ * The one instance of a model class that column-metadata enumeration is
+ * allowed to look at.
+ *
+ * WHY THIS EXISTS.
+ *
+ * Every "which columns does this model have" lookup in this directory answers
+ * the question by enumerating an INSTANCE's own keys (Object.keys) and then
+ * caching the answer per CLASS. That is only sound while every instance of a
+ * class has the same own keys. The class bodies do guarantee that - each
+ * decorated column is initialised to `undefined` - right up until some caller
+ * deletes a key off a live instance.
+ *
+ * One caller did. BaseAPI.createItem used to `delete item._id` before handing
+ * the model to the service, and DatabaseService.create asks that very instance
+ * for its columns (generateDefaultValues). Whenever the mutilated instance was
+ * the first to ask, the class's cached column list was built WITHOUT `_id` -
+ * permanently, for the life of the process, for every later caller - and since
+ * DatabaseBaseModel.toJSONObject serialises a row by iterating exactly that
+ * list, every API response for that model silently lost its id. A single
+ * create was enough, including a create that was refused, because the columns
+ * are read before the permission check. Rows still carried their real `_id` in
+ * memory and in the SQL projection; it was dropped on the way out.
+ *
+ * So enumeration stopped reading the caller's instance. It reads a frozen,
+ * private instance of the caller's CLASS instead - constructed here, reachable
+ * by nobody, impossible to mutate - so what a class reports about itself can
+ * never depend on which instance happened to ask first, or on what anyone did
+ * to that instance. Reads already constructed a throwaway instance for exactly
+ * this purpose (SelectPermission, QueryPermission, ColumnPermission all do
+ * `new modelType()`), which is why a single read of a model was enough to make
+ * the same create harmless; this makes that the only behaviour.
+ *
+ * Every database model is no-arg constructible (Models/DatabaseModels/Index.ts
+ * relies on it already, in getModelTypeByName), and a fresh instance carries
+ * every declared column - both facts are asserted by
+ * Tests/Types/Database/CanonicalModelInstance.test.ts against all 400+ models.
+ */
+
+type NoArgConstructor = new () => unknown;
+
+const canonicalInstanceCache: WeakMap<NoArgConstructor, unknown> =
+  new WeakMap();
+
+/*
+ * Classes whose canonical instance is being constructed right now. A model
+ * constructor that asked for its own columns would otherwise recurse forever;
+ * such a call gets the caller's instance instead, which is the old behaviour.
+ */
+const beingConstructed: WeakSet<NoArgConstructor> = new WeakSet();
+
+/**
+ * A frozen, shared instance of `target`'s class, safe to enumerate for
+ * metadata - or NULL when no such instance can be made: a class that needs
+ * constructor arguments, a class still being defined (circular imports), a
+ * constructor that throws, or a plain object with no useful constructor.
+ *
+ * Null, rather than falling back to `target`, because the two are NOT
+ * interchangeable and treating them as if they were is how this bug worked in
+ * the first place. A caller with no canonical instance may still answer from
+ * whatever instance it was handed - a metadata lookup must never be the reason
+ * a process fails to boot - but it must not then CACHE that answer for the
+ * class, because the instance it read may be a mutilated one and the cached
+ * answer would outlive it. Returning null forces each caller to make that
+ * decision in the open; the four caches in this directory all take the same
+ * route, and say so where they do it.
+ */
+export default function getCanonicalModelInstance<T>(target: T): T | null {
+  const modelClass: NoArgConstructor | undefined = (
+    target as { constructor?: NoArgConstructor } | null | undefined
+  )?.constructor;
+
+  if (typeof modelClass !== "function") {
+    return null;
+  }
+
+  const cached: unknown = canonicalInstanceCache.get(modelClass);
+
+  if (cached) {
+    return cached as T;
+  }
+
+  if (beingConstructed.has(modelClass)) {
+    return null;
+  }
+
+  let canonical: T;
+
+  beingConstructed.add(modelClass);
+
+  try {
+    canonical = Object.freeze(new modelClass()) as T;
+  } catch {
+    return null;
+  } finally {
+    beingConstructed.delete(modelClass);
+  }
+
+  canonicalInstanceCache.set(modelClass, canonical);
+
+  return canonical;
+}