@oneuptime/common 13.0.8 → 14.0.1

package/Server/Types/Markdown.ts

@@ -207,6 +207,47 @@ export default class Markdown {
       );
     };
 
+    /*
+     * Lists. A platform monitor's root cause lists its affected resources
+     * as a numbered list with a bullet list of details nested under each
+     * item, and the cluster and metric details above it are bullets too.
+     *
+     * Left to the client, Gmail and Apple Mail indent every list level by
+     * 40px — close to a tenth of the card, twice over for a nested list —
+     * and Outlook's Word engine ignores padding on <ul>/<ol> and picks its
+     * own margins. So the indent is a margin-left, which Outlook honours,
+     * with padding zeroed: 24px holds a bullet, and 32px holds a numbered
+     * marker up to three digits ("100."). The vertical margins give each
+     * item's nested details a little air above and a gap below that
+     * separates it from the next item.
+     *
+     * margin-left is a physical side, so it is followed by the logical
+     * margin-inline-start / -end: a client that understands them moves
+     * the indent to the marker side in right-to-left text, and one that
+     * does not keeps the margin-left.
+     */
+    renderer.list = function (
+      body: string,
+      ordered: boolean,
+      start: number | "",
+    ): string {
+      const tag: string = ordered ? "ol" : "ul";
+      const startAttribute: string =
+        ordered && start !== "" && start !== 1 ? ` start="${start}"` : "";
+      const indent: string = ordered ? "32px" : "24px";
+
+      return (
+        `<${tag}${startAttribute} style="margin:6px 0 12px 0;` +
+        `margin-left:${indent};margin-inline-start:${indent};` +
+        `margin-inline-end:0;padding:0;">` +
+        `${body}</${tag}>`
+      );
+    };
+
+    renderer.listitem = function (text: string): string {
+      return `<li style="margin:0 0 4px;padding:0;">${text}</li>`;
+    };
+
     /*
      * The root cause backticks metric names, aliases and timestamps. Left
      * bare they were indistinguishable from the prose around them.

package/Server/Types/Workflow/Components/Telegram/SendMessageToChat.ts

@@ -13,7 +13,17 @@ import TelegramComponents from "../../../../../Types/Workflow/Components/Telegra
 import API from "../../../../../Utils/API";
 import CaptureSpan from "../../../../Utils/Telemetry/CaptureSpan";
 
+/*
+ * https://core.telegram.org/bots/api#authorizing-your-bot — a numeric bot id,
+ * a ":", then the secret, e.g. "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11".
+ */
+const TELEGRAM_BOT_TOKEN_REGEX: RegExp = /^\d+:[A-Za-z0-9_-]+$/;
+
 export default class SendMessageToChat extends ComponentCode {
+  public static isValidBotToken(botToken: string): boolean {
+    return TELEGRAM_BOT_TOKEN_REGEX.test(botToken);
+  }
+
   public constructor() {
     super();
 
@@ -69,10 +79,26 @@ export default class SendMessageToChat extends ComponentCode {
       throw options.onError(new BadDataException("Telegram message not found"));
     }
 
-    const botToken: string = args["bot-token"]?.toString() as string;
+    // A token pasted or stored with a trailing newline is still the token.
+    const botToken: string = (args["bot-token"]?.toString() || "").trim();
     const chatId: string = args["chat-id"]?.toString() as string;
     const text: string = args["text"]?.toString() as string;
 
+    /*
+     * The token becomes a path segment of the request URL, so anything other
+     * than Telegram's "<bot id>:<secret>" shape is refused before it gets
+     * there. The message deliberately does not quote the value: the step's
+     * error is written to the run log, and the token is a credential. Before
+     * this check, a URL parse failure put the whole token into the log.
+     */
+    if (!SendMessageToChat.isValidBotToken(botToken)) {
+      throw options.onError(
+        new BadDataException(
+          "Telegram Bot Token is not in a valid format. It should look like 123456789:ABCdefGhIJKlmnoPQRstuVWxyz, exactly as BotFather issued it.",
+        ),
+      );
+    }
+
     const telegramApiUrl: URL = URL.fromString(
       `https://api.telegram.org/bot${botToken}/sendMessage`,
     );

package/Server/Utils/AI/Toolbox/SloTools.ts

@@ -382,6 +382,7 @@ export const QuerySlosTool: ObservabilityTool = {
                     _id: true,
                     name: true,
                   },
+                  monitorType: true,
                   monitorNamePattern: true,
                   monitorDescriptionPattern: true,
                   criteria: true,

package/Server/Utils/CommunityEditionSsoReport.ts

@@ -0,0 +1,361 @@
+import EnterpriseEdition, {
+  EnterpriseFeatureStateChange,
+} from "../Enterprise/EnterpriseEdition";
+import EnterpriseFeature from "../Enterprise/EnterpriseFeature";
+import {
+  ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS,
+  ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS,
+} from "../Enterprise/EnterpriseLicenseSnapshot";
+import GlobalConfigService from "../Services/GlobalConfigService";
+import ProjectSCIMService from "../Services/ProjectSCIMService";
+import ProjectService from "../Services/ProjectService";
+import StatusPageService from "../Services/StatusPageService";
+import logger from "./Logger";
+import PositiveNumber from "../../Types/PositiveNumber";
+import Project from "../../Models/DatabaseModels/Project";
+import ProjectSCIM from "../../Models/DatabaseModels/ProjectSCIM";
+import StatusPage from "../../Models/DatabaseModels/StatusPage";
+
+// How many ids of each kind the log line names; the counts are always exact.
+export const MAX_IDS_LISTED_PER_KIND: number = 20;
+
+/*
+ * The SSO requirements and SCIM team locks that are configured but not
+ * enforced (see EditionEnforcement): left over from an Enterprise Edition
+ * install on a Community Edition process, or configured on an Enterprise
+ * install whose license has lapsed.
+ */
+export interface RelaxedEnforcementSummary {
+  instanceRequiresSso: boolean;
+  projectsRequiringSso: number;
+  projectIdsRequiringSso: Array<string>;
+  statusPagesRequiringSso: number;
+  statusPageIdsRequiringSso: Array<string>;
+  scimConfigurationsWithPushGroups: number;
+  projectIdsWithScimPushGroups: Array<string>;
+}
+
+/*
+ * Why the settings in a report are not enforced:
+ *
+ *   community        a Community Edition process, which has no SSO login and
+ *                    no SCIM endpoint at all;
+ *   lapsed-license   an Enterprise install whose license no longer covers SSO
+ *                    and/or SCIM (EnterpriseEdition.isFeatureActive). Only the
+ *                    relaxed half is reported.
+ */
+export type RelaxedEnforcementContext =
+  | { reason: "community" }
+  | { reason: "lapsed-license"; isSsoRelaxed: boolean; isScimRelaxed: boolean };
+
+const COMMUNITY_CONTEXT: RelaxedEnforcementContext = { reason: "community" };
+
+/*
+ * Tells the operator which configured security settings this server is not
+ * enforcing, so that never happens silently:
+ *
+ *   - Community Edition: moving from the Enterprise image to the Community
+ *     one keeps the database as it is, so a project that required SSO still
+ *     says so - but the SSO login routes are part of the Enterprise Edition,
+ *     so the requirement is relaxed rather than locking everyone out. Logged
+ *     once per process at boot.
+ *   - Enterprise Edition: when the license lapses, SSO and SCIM stop and the
+ *     same settings are relaxed until a license is activated. Logged each time
+ *     SSO or SCIM stops (EnterpriseEdition reports each change once),
+ *     including a license that has already lapsed at boot.
+ */
+export default class CommunityEditionSsoReport {
+  private static hasRun: boolean = false;
+
+  private static stopWatchingLicense: (() => void) | null = null;
+
+  /*
+   * Called once at boot, after the enterprise loader. On the Community
+   * Edition it logs the relaxed settings once per process. On the Enterprise
+   * Edition it starts watching the license (once per process) and reports
+   * whenever SSO or SCIM stops. Never throws: a failed check is logged and
+   * boot carries on. Returns what the Community Edition report found (null
+   * when it did not run or the check failed).
+   */
+  public static async logRelaxedEnforcementOnce(): Promise<RelaxedEnforcementSummary | null> {
+    if (EnterpriseEdition.isLoaded()) {
+      CommunityEditionSsoReport.watchLicenseOnce();
+      return null;
+    }
+
+    if (CommunityEditionSsoReport.hasRun) {
+      return null;
+    }
+
+    CommunityEditionSsoReport.hasRun = true;
+
+    return await CommunityEditionSsoReport.report(COMMUNITY_CONTEXT);
+  }
+
+  /*
+   * Collects and logs the relaxed settings. Never throws. Returns what it
+   * found (null when the check failed).
+   */
+  public static async report(
+    context: RelaxedEnforcementContext,
+  ): Promise<RelaxedEnforcementSummary | null> {
+    try {
+      const summary: RelaxedEnforcementSummary =
+        await CommunityEditionSsoReport.collect();
+
+      const message: string | null = CommunityEditionSsoReport.describe(
+        summary,
+        context,
+      );
+
+      if (message) {
+        logger.warn(message);
+      }
+
+      return summary;
+    } catch (err) {
+      logger.error(
+        context.reason === "community"
+          ? "Community Edition: could not check for SSO requirements and SCIM team locks left over from an Enterprise Edition install."
+          : "OneUptime Enterprise license lapsed: could not check which SSO requirements and SCIM team locks are no longer enforced.",
+      );
+      logger.error(err);
+      return null;
+    }
+  }
+
+  /*
+   * Watches the Enterprise license for SSO or SCIM stopping, once per
+   * process. The first look happens here, so a license that has already
+   * lapsed at boot is reported like a lapse at runtime.
+   */
+  private static watchLicenseOnce(): void {
+    if (CommunityEditionSsoReport.stopWatchingLicense) {
+      return;
+    }
+
+    CommunityEditionSsoReport.stopWatchingLicense =
+      EnterpriseEdition.onFeatureStateChange(
+        (change: EnterpriseFeatureStateChange): void => {
+          CommunityEditionSsoReport.onFeatureStateChange(change);
+        },
+      );
+
+    try {
+      EnterpriseEdition.isFeatureActive(EnterpriseFeature.SSO);
+      EnterpriseEdition.isFeatureActive(EnterpriseFeature.SCIM);
+    } catch (err) {
+      logger.error(err);
+    }
+  }
+
+  private static onFeatureStateChange(
+    change: EnterpriseFeatureStateChange,
+  ): void {
+    const isSsoRelaxed: boolean = change.stopped.includes(
+      EnterpriseFeature.SSO,
+    );
+    const isScimRelaxed: boolean = change.stopped.includes(
+      EnterpriseFeature.SCIM,
+    );
+
+    if (!isSsoRelaxed && !isScimRelaxed) {
+      return;
+    }
+
+    void CommunityEditionSsoReport.report({
+      reason: "lapsed-license",
+      isSsoRelaxed,
+      isScimRelaxed,
+    });
+  }
+
+  // Reads the stored (not the masked) settings. Root reads are never masked.
+  public static async collect(): Promise<RelaxedEnforcementSummary> {
+    const [
+      instanceRequiresSso,
+      projectCount,
+      projects,
+      statusPageCount,
+      statusPages,
+      scimCount,
+      scimConfigurations,
+    ]: [
+      boolean,
+      PositiveNumber,
+      Array<Project>,
+      PositiveNumber,
+      Array<StatusPage>,
+      PositiveNumber,
+      Array<ProjectSCIM>,
+    ] = await Promise.all([
+      GlobalConfigService.getRequireSsoForLogin(),
+      ProjectService.countBy({
+        query: { requireSsoForLogin: true },
+        props: { isRoot: true },
+      }),
+      ProjectService.findBy({
+        query: { requireSsoForLogin: true },
+        select: { _id: true },
+        limit: MAX_IDS_LISTED_PER_KIND,
+        skip: 0,
+        props: { isRoot: true },
+      }),
+      StatusPageService.countBy({
+        query: { requireSsoForLogin: true },
+        props: { isRoot: true },
+      }),
+      StatusPageService.findBy({
+        query: { requireSsoForLogin: true },
+        select: { _id: true },
+        limit: MAX_IDS_LISTED_PER_KIND,
+        skip: 0,
+        props: { isRoot: true },
+      }),
+      ProjectSCIMService.countBy({
+        query: { enablePushGroups: true },
+        props: { isRoot: true },
+      }),
+      ProjectSCIMService.findBy({
+        query: { enablePushGroups: true },
+        select: { projectId: true },
+        limit: MAX_IDS_LISTED_PER_KIND,
+        skip: 0,
+        props: { isRoot: true },
+      }),
+    ]);
+
+    return {
+      instanceRequiresSso: Boolean(instanceRequiresSso),
+      projectsRequiringSso: projectCount.toNumber(),
+      projectIdsRequiringSso: CommunityEditionSsoReport.toIds(
+        projects.map((project: Project) => {
+          return project.id?.toString() || project._id?.toString();
+        }),
+      ),
+      statusPagesRequiringSso: statusPageCount.toNumber(),
+      statusPageIdsRequiringSso: CommunityEditionSsoReport.toIds(
+        statusPages.map((statusPage: StatusPage) => {
+          return statusPage.id?.toString() || statusPage._id?.toString();
+        }),
+      ),
+      scimConfigurationsWithPushGroups: scimCount.toNumber(),
+      projectIdsWithScimPushGroups: CommunityEditionSsoReport.toIds(
+        scimConfigurations.map((scim: ProjectSCIM) => {
+          return scim.projectId?.toString();
+        }),
+      ),
+    };
+  }
+
+  // The log line, or null when nothing is relaxed.
+  public static describe(
+    summary: RelaxedEnforcementSummary,
+    context: RelaxedEnforcementContext = COMMUNITY_CONTEXT,
+  ): string | null {
+    const isSsoRelaxed: boolean =
+      context.reason === "community" || context.isSsoRelaxed;
+    const isScimRelaxed: boolean =
+      context.reason === "community" || context.isScimRelaxed;
+
+    const relaxed: Array<string> = [];
+
+    if (isSsoRelaxed && summary.instanceRequiresSso) {
+      relaxed.push(
+        'the instance-wide "Require SSO for Login" setting (Admin Dashboard > Settings > Authentication)',
+      );
+    }
+
+    if (isSsoRelaxed && summary.projectsRequiringSso > 0) {
+      relaxed.push(
+        `${summary.projectsRequiringSso} project(s) that require SSO for login${CommunityEditionSsoReport.describeIds(
+          summary.projectIdsRequiringSso,
+          summary.projectsRequiringSso,
+        )}`,
+      );
+    }
+
+    if (isSsoRelaxed && summary.statusPagesRequiringSso > 0) {
+      relaxed.push(
+        `${summary.statusPagesRequiringSso} private status page(s) that require SSO for login${CommunityEditionSsoReport.describeIds(
+          summary.statusPageIdsRequiringSso,
+          summary.statusPagesRequiringSso,
+        )}`,
+      );
+    }
+
+    if (isScimRelaxed && summary.scimConfigurationsWithPushGroups > 0) {
+      relaxed.push(
+        `${summary.scimConfigurationsWithPushGroups} SCIM configuration(s) with Push Groups on, whose teams can be edited in OneUptime again${CommunityEditionSsoReport.describeIds(
+          summary.projectIdsWithScimPushGroups,
+          summary.scimConfigurationsWithPushGroups,
+          "project ids",
+        )}`,
+      );
+    }
+
+    if (relaxed.length === 0) {
+      return null;
+    }
+
+    if (context.reason === "lapsed-license") {
+      const stopped: string =
+        isSsoRelaxed && isScimRelaxed
+          ? "SSO login and SCIM provisioning have"
+          : isSsoRelaxed
+            ? "SSO login has"
+            : "SCIM provisioning has";
+
+      return (
+        "OneUptime Enterprise license lapsed: this server has security settings that it no longer enforces, " +
+        `because ${stopped} stopped until a license that includes ${isSsoRelaxed && isScimRelaxed ? "them" : "it"} is activated. ` +
+        (isSsoRelaxed
+          ? "Users of these projects and status pages sign in with email and password instead (users who only ever signed in with SSO can reset their password). "
+          : "") +
+        `Not enforced: ${relaxed.join("; ")}. ` +
+        "The settings are kept unchanged and are enforced again as soon as a license is activated, without a restart."
+      );
+    }
+
+    return (
+      "Community Edition: this server has security settings from an Enterprise Edition install that it does not enforce, " +
+      "because SSO login and SCIM provisioning are part of the OneUptime Enterprise Edition. " +
+      "Users of these projects and status pages sign in with email and password instead. " +
+      `Not enforced: ${relaxed.join("; ")}. ` +
+      `The settings are kept unchanged and are enforced again when this server runs the Enterprise Edition image with a valid license (or during its ${ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS}-day trial, or the ${ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS}-day grace period after a license expires).`
+    );
+  }
+
+  // Test suites only: allow the next call to run again and stop watching.
+  public static resetForTests(): void {
+    CommunityEditionSsoReport.hasRun = false;
+
+    if (CommunityEditionSsoReport.stopWatchingLicense) {
+      CommunityEditionSsoReport.stopWatchingLicense();
+      CommunityEditionSsoReport.stopWatchingLicense = null;
+    }
+  }
+
+  private static toIds(values: Array<string | undefined>): Array<string> {
+    return values
+      .filter((value: string | undefined): value is string => {
+        return Boolean(value);
+      })
+      .slice(0, MAX_IDS_LISTED_PER_KIND);
+  }
+
+  private static describeIds(
+    ids: Array<string>,
+    total: number,
+    label: string = "ids",
+  ): string {
+    if (ids.length === 0) {
+      return "";
+    }
+
+    const more: string =
+      total > ids.length ? ` and ${total - ids.length} more` : "";
+
+    return ` (${label}: ${ids.join(", ")}${more})`;
+  }
+}

package/Server/Utils/EditionEnforcement.ts

@@ -0,0 +1,233 @@
+import EnterpriseEdition from "../Enterprise/EnterpriseEdition";
+import EnterpriseFeature from "../Enterprise/EnterpriseFeature";
+import {
+  ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS,
+  ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS,
+} from "../Enterprise/EnterpriseLicenseSnapshot";
+import logger from "./Logger";
+import DatabaseCommonInteractionProps from "../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import PaymentRequiredException from "../../Types/Exception/PaymentRequiredException";
+
+/*
+ * Which enterprise identity controls are live in this process.
+ *
+ * Every answer here follows the RUNTIME state of the feature behind it
+ * (EnterpriseEdition.isFeatureActive): SSO for the SSO requirements, the
+ * SAML/OIDC sign-in routes and the provider listings, SCIM for the SCIM Push
+ * Groups team locks. A feature is active when the Enterprise Edition is loaded
+ * and, with billing off, its license covers the feature (valid, in the grace
+ * period after it expired, or - with no license - inside the trial).
+ *
+ * The controls are relaxed where they cannot work:
+ *   - on the Community Edition, which has no SAML/OIDC sign-in routes and no
+ *     SCIM endpoints;
+ *   - on an Enterprise install whose license has lapsed, where those routes
+ *     refuse (ee/Server/Identity).
+ * Enforcing a leftover "Require SSO for login" there would lock every user
+ * out, and a leftover SCIM Push Groups lock would leave teams nobody can
+ * manage. Users sign in with their password instead (users who only ever used
+ * SSO reset it). The configuration itself is kept untouched - reads made for
+ * a caller report the requirement as off, and a caller's write can neither
+ * switch it off nor set it meanwhile (guardSsoRequirementWrite) - so running
+ * the Enterprise Edition again (with a valid license, or during its trial or
+ * grace period), or renewing the license, restores enforcement without a
+ * restart.
+ *
+ * Failure direction: an error while deciding answers "enforce", and an
+ * unknown license state counts as active (see isFeatureActive), so a read
+ * error never switches a control off.
+ */
+export default class EditionEnforcement {
+  // Why guardSsoRequirementWrite refuses a write, on the Community Edition.
+  public static readonly SSO_REQUIREMENT_UNCHANGEABLE_COMMUNITY_MESSAGE: string =
+    'Single sign-on is part of the OneUptime Enterprise Edition and this server runs the Community Edition, so "Require SSO for login" shows as off, is not enforced and cannot be changed here. ' +
+    `A setting saved earlier is kept, and it is enforced again when this server runs the Enterprise Edition image with a valid license (or during its ${ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS}-day trial, or the ${ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS}-day grace period after a license expires).`;
+
+  /*
+   * Why guardSsoRequirementWrite refuses a write, on an Enterprise install
+   * whose license does not cover SSO right now.
+   */
+  public static readonly SSO_REQUIREMENT_UNCHANGEABLE_LICENSE_MESSAGE: string =
+    'Single sign-on has stopped because the OneUptime Enterprise license is missing, expired or does not include SSO, so "Require SSO for login" shows as off, is not enforced and cannot be changed. ' +
+    "The saved setting is kept, and it is enforced again as soon as a master admin activates or renews the license from the edition label in the Admin Dashboard header.";
+
+  /*
+   * Whether configured SSO requirements - a project's requireSsoForLogin (and
+   * its required provider), the instance-wide requireSsoForLogin and a status
+   * page's requireSsoForLogin - are enforced.
+   */
+  public static isSsoEnforced(): boolean {
+    try {
+      return EnterpriseEdition.isFeatureActive(EnterpriseFeature.SSO);
+    } catch (err) {
+      logger.error(
+        "EditionEnforcement: could not tell whether SSO is enforced; enforcing it.",
+      );
+      logger.error(err);
+      return true;
+    }
+  }
+
+  // A configured SSO requirement that is also enforced in this process.
+  public static isSsoRequired(
+    configuredRequirement: boolean | null | undefined,
+  ): boolean {
+    if (!configuredRequirement) {
+      return false;
+    }
+
+    return EditionEnforcement.isSsoEnforced();
+  }
+
+  /*
+   * Whether SCIM Push Groups owns team membership: while a project's SCIM
+   * configuration has Push Groups on, teams and team members can only be
+   * changed by the identity provider. Relaxed on the Community Edition, and
+   * while the license does not cover SCIM, because then no SCIM endpoint
+   * answers the identity provider and nobody else could manage those teams.
+   */
+  public static areScimTeamLocksEnforced(): boolean {
+    try {
+      return EnterpriseEdition.isFeatureActive(EnterpriseFeature.SCIM);
+    } catch (err) {
+      logger.error(
+        "EditionEnforcement: could not tell whether SCIM team locks apply; applying them.",
+      );
+      logger.error(err);
+      return true;
+    }
+  }
+
+  /*
+   * Whether the SAML/OIDC sign-in routes answer right now. Provider listings
+   * (the lists a sign-in page offers) are empty when they do not, so no client
+   * sends a user into a route that answers 404 (Community Edition) or refuses
+   * because the license lapsed (Enterprise Edition).
+   */
+  public static areSsoRoutesServed(): boolean {
+    try {
+      return EnterpriseEdition.isFeatureActive(EnterpriseFeature.SSO);
+    } catch (err) {
+      logger.error(
+        "EditionEnforcement: could not tell whether the SSO routes are served; serving them.",
+      );
+      logger.error(err);
+      return true;
+    }
+  }
+
+  /*
+   * Whether a read should report the EFFECTIVE SSO requirement (false)
+   * instead of the stored one. Clients - the mobile app in particular, whose
+   * store builds cannot be patched - decide from these columns whether to
+   * start an SSO flow, and while SSO is not active that flow does not exist
+   * (Community Edition) or refuses (lapsed license).
+   *
+   * Only reads made for a caller are masked. Internal (root) reads see the
+   * stored value, and a read never writes, so the configuration is intact
+   * when SSO is active again. The write half is guardSsoRequirementWrite.
+   */
+  public static shouldMaskSsoRequirementOnRead(
+    props: DatabaseCommonInteractionProps | null | undefined,
+  ): boolean {
+    if (!props || props.isRoot) {
+      return false;
+    }
+
+    return !EditionEnforcement.isSsoEnforced();
+  }
+
+  /*
+   * The write half of shouldMaskSsoRequirementOnRead, for the services'
+   * onBeforeUpdate. A caller whose reads are masked has only ever seen the
+   * requirement as off (no required provider), so what it writes to those
+   * columns cannot be taken at face value: a settings form, or an API client
+   * doing a read-modify-write, sends back the masked value it read. Saving it
+   * would switch a configured requirement off without anybody deciding to,
+   * and it would stay off once SSO is active again.
+   *
+   * So while this caller's reads are masked:
+   *   - a write of the masked value (false, or no provider) is dropped from
+   *     `data`, and the stored requirement is kept;
+   *   - a write that would set a requirement (true, or a provider) is
+   *     refused: it could neither be seen nor enforced until SSO is active;
+   *   - a write that is left with nothing else to save is refused with the
+   *     same explanation, rather than reporting a save that did not happen.
+   *
+   * Root writes, and every write while SSO is active, are left alone.
+   * Mutates `data`. Throws PaymentRequiredException.
+   */
+  public static guardSsoRequirementWrite(input: {
+    props: DatabaseCommonInteractionProps | null | undefined;
+    data: Record<string, unknown>;
+    // The requirement columns of the model being written.
+    columns: ReadonlyArray<string>;
+  }): void {
+    if (!EditionEnforcement.shouldMaskSsoRequirementOnRead(input.props)) {
+      return;
+    }
+
+    const writtenColumns: Array<string> = input.columns.filter(
+      (column: string): boolean => {
+        return input.data[column] !== undefined;
+      },
+    );
+
+    if (writtenColumns.length === 0) {
+      return;
+    }
+
+    const setsRequirement: boolean = writtenColumns.some(
+      (column: string): boolean => {
+        return !EditionEnforcement.isMaskedSsoRequirementValue(
+          input.data[column],
+        );
+      },
+    );
+
+    if (setsRequirement) {
+      throw EditionEnforcement.createSsoRequirementUnchangeableException();
+    }
+
+    for (const column of writtenColumns) {
+      delete input.data[column];
+    }
+
+    /*
+     * `data` is the plain update onBeforeUpdate receives (a model instance
+     * has already been reduced to its set columns by
+     * DatabaseService.sanitizeUpdateData); a key left undefined writes
+     * nothing, so it does not count.
+     */
+    const hasOtherColumns: boolean = Object.keys(input.data).some(
+      (key: string): boolean => {
+        return input.data[key] !== undefined;
+      },
+    );
+
+    if (!hasOtherColumns) {
+      throw EditionEnforcement.createSsoRequirementUnchangeableException();
+    }
+  }
+
+  // What a masked read reports for a requirement column: false or null.
+  private static isMaskedSsoRequirementValue(value: unknown): boolean {
+    return value === false || value === null;
+  }
+
+  private static createSsoRequirementUnchangeableException(): PaymentRequiredException {
+    let isEnterpriseEditionLoaded: boolean = true;
+
+    try {
+      isEnterpriseEditionLoaded = EnterpriseEdition.isLoaded();
+    } catch (err) {
+      logger.error(err);
+    }
+
+    return new PaymentRequiredException(
+      isEnterpriseEditionLoaded
+        ? EditionEnforcement.SSO_REQUIREMENT_UNCHANGEABLE_LICENSE_MESSAGE
+        : EditionEnforcement.SSO_REQUIREMENT_UNCHANGEABLE_COMMUNITY_MESSAGE,
+    );
+  }
+}