@oneuptime/common 13.0.8 → 14.0.1

package/Server/Enterprise/EnterpriseLicenseSnapshot.ts

@@ -0,0 +1,192 @@
+import EnterpriseFeature from "./EnterpriseFeature";
+
+/*
+ * The seat usage of an Enterprise install, as
+ * EnterpriseEdition.getSeatUsage() returns it and the /global-config/license
+ * response carries it. Only the type lives in core: the arithmetic that
+ * computes it belongs to the Enterprise license client
+ * (ee/Server/License/EnterpriseLicenseSeats.ts).
+ */
+export interface SeatUsage {
+  /*
+   * False when the license carries no usable seat limit. Every other field is
+   * still filled in — a caller that wants to display usage can, it just must
+   * not block anything.
+   */
+  isEnforced: boolean;
+
+  // The limit actually being enforced, or null when there is none.
+  userLimit: number | null;
+
+  /*
+   * The best estimate of how many licensed seats are consumed right now,
+   * across every instance on this license, counting this installation's live
+   * users and the other instances' users from the last usage report.
+   */
+  seatsInUse: number;
+
+  // Null when there is no limit. Never negative — a breach reads as 0 free.
+  seatsRemaining: number | null;
+
+  /*
+   * The single question enforcement asks. True whenever there is no limit, so
+   * a caller can use this on its own without re-checking isEnforced.
+   */
+  hasSeatForNewUser: boolean;
+
+  /*
+   * How many of seatsInUse are users this installation has never seen. Zero
+   * whenever the topology is not known well enough to say, which is the
+   * conservative answer.
+   */
+  seatsUsedByOtherInstances: number;
+}
+
+/*
+ * Where the license stands in time. Deliberately about time only; whether the
+ * token was cryptographically verified is the separate `verification` axis.
+ *
+ *   missing  no license token is stored and the unlicensed trial is over, in
+ *            which case graceEndsAt says when it ended. With no graceEndsAt
+ *            the trial start is not known (see isTrialStartUnknown).
+ *   valid    the license is current
+ *   grace    expired no more than the grace period
+ *            (ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS) ago, OR an unlicensed
+ *            Enterprise install still inside its trial
+ *            (ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS from first seen). Both
+ *            share this status because both entitle everything until they
+ *            end; graceReason tells them apart, and graceEndsAt is the end of
+ *            whichever one it is.
+ *   expired  expired longer ago than the grace period
+ *   invalid  a token is stored but cannot be trusted: a bad signature from a
+ *            trusted key, the wrong audience or issuer, bound to a different
+ *            instance, or malformed
+ */
+export type EnterpriseLicenseStatus =
+  | "missing"
+  | "valid"
+  | "grace"
+  | "expired"
+  | "invalid";
+
+/*
+ *   verified    signed by a key this build trusts; every limit comes from the
+ *               signed claims
+ *   unverified  a legacy HS256 token or one signed by a key this build does not
+ *               know; accepted while legacy acceptance is on, with limits taken
+ *               from the stored columns
+ *   none        there is no token to verify
+ */
+export type EnterpriseLicenseVerification = "verified" | "unverified" | "none";
+
+export type EnterpriseLicenseGraceReason = "expired" | "unlicensed";
+
+export type EnterpriseLicenseFeatures = "all" | Array<EnterpriseFeature>;
+
+export interface EnterpriseLicenseSnapshot {
+  status: EnterpriseLicenseStatus;
+  verification: EnterpriseLicenseVerification;
+  graceReason?: EnterpriseLicenseGraceReason | undefined;
+  companyName?: string | undefined;
+  expiresAt?: Date | undefined;
+  graceEndsAt?: Date | undefined;
+  // Null when the license sets no seat limit.
+  userLimit: number | null;
+  isEvaluation: boolean;
+  features: EnterpriseLicenseFeatures;
+  // A human-readable explanation of the status, for logs and admin banners.
+  message?: string | undefined;
+}
+
+/*
+ * ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS (30): how long an expired license
+ * keeps working, counted from its expiry - a verified license's signed
+ * expiry, or an unverified legacy license's stored expiry column.
+ *
+ * ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS (14): how long an Enterprise install
+ * that has no license is on trial, counted from
+ * GlobalConfig.enterpriseEditionFirstSeenAt.
+ *
+ * Until either ends nothing changes; after it, enterprise configuration
+ * becomes read-only and SSO, SCIM and audit logging stop
+ * (EnterpriseEdition.isFeatureActive) until a license is activated. They are
+ * defined in Common/Types so the browser copy derives the same numbers.
+ */
+export {
+  ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS,
+  ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS,
+} from "../../Types/EnterpriseLicense/EnterpriseLicensePeriods";
+
+export class EnterpriseLicenseSnapshotUtil {
+  /*
+   * True when the license currently entitles anything at all. Grace counts:
+   * the whole point of grace is that nothing changes until it ends.
+   */
+  public static isUsable(snapshot: EnterpriseLicenseSnapshot | null): boolean {
+    if (!snapshot) {
+      return false;
+    }
+
+    return snapshot.status === "valid" || snapshot.status === "grace";
+  }
+
+  public static includesFeature(
+    snapshot: EnterpriseLicenseSnapshot | null,
+    feature: EnterpriseFeature,
+  ): boolean {
+    if (!snapshot) {
+      return false;
+    }
+
+    if (snapshot.features === "all") {
+      return true;
+    }
+
+    if (!Array.isArray(snapshot.features)) {
+      return false;
+    }
+
+    return snapshot.features.includes(feature);
+  }
+
+  // Usable AND entitled: the license half of EnterpriseEdition.isFeatureAvailable.
+  public static entitles(
+    snapshot: EnterpriseLicenseSnapshot | null,
+    feature: EnterpriseFeature,
+  ): boolean {
+    return (
+      EnterpriseLicenseSnapshotUtil.isUsable(snapshot) &&
+      EnterpriseLicenseSnapshotUtil.includesFeature(snapshot, feature)
+    );
+  }
+
+  /*
+   * "missing" with no graceEndsAt: no license is installed, and the start of
+   * the unlicensed trial (GlobalConfig.enterpriseEditionFirstSeenAt) is not
+   * known - the stamp has not been written yet (it failed, or the row does
+   * not exist yet), or nothing could be read at all (createMissing). So
+   * whether the install is still in its trial is unknown.
+   * EnterpriseEdition.isFeatureActive treats it as an unknown license state
+   * (active); the configuration checks still fail closed on it.
+   */
+  public static isTrialStartUnknown(
+    snapshot: EnterpriseLicenseSnapshot | null,
+  ): boolean {
+    if (!snapshot) {
+      return false;
+    }
+
+    return snapshot.status === "missing" && !snapshot.graceEndsAt;
+  }
+
+  public static createMissing(message?: string): EnterpriseLicenseSnapshot {
+    return {
+      status: "missing",
+      verification: "none",
+      userLimit: null,
+      isEvaluation: false,
+      features: [],
+      message: message || "No OneUptime Enterprise license is installed.",
+    };
+  }
+}

package/Server/Enterprise/EnterpriseServerModule.ts

@@ -0,0 +1,233 @@
+import type { ExpressRouter } from "../Utils/Express";
+import type {
+  EnterpriseLicenseSnapshot,
+  SeatUsage,
+} from "./EnterpriseLicenseSnapshot";
+import type BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import type DatabaseCommonInteractionProps from "../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import type { JSONObject } from "../../Types/JSON";
+import type ObjectID from "../../Types/ObjectID";
+
+/*
+ * The contract between core (Apache-2.0, everything outside ee/) and the
+ * enterprise module in ee/ (OneUptime Enterprise License).
+ *
+ * Core never imports ee. The App loader (packages/App/Utils/EnterpriseLoader.ts)
+ * finds ee/Server/Index.ts at boot, requires it, checks it against this
+ * interface and registers it with EnterpriseEdition. Everything in core that
+ * behaves differently per edition asks EnterpriseEdition, never ee directly.
+ */
+
+export type EnterpriseServerModuleName = "oneuptime-enterprise";
+
+export const ENTERPRISE_SERVER_MODULE_NAME: EnterpriseServerModuleName =
+  "oneuptime-enterprise";
+
+/*
+ * The recording half of the audit log. Core's AuditLogService keeps these four
+ * public methods as thin delegates, so DatabaseService, ProjectService and the
+ * user-notification services call exactly what they call today; on the
+ * Community Edition there is no recorder and nothing is recorded.
+ *
+ * The signatures mirror AuditLogService's public methods one for one.
+ */
+export interface AuditLogRecorder {
+  recordCreate<TModel extends BaseModel>(data: {
+    model: TModel;
+    createdItem: TModel;
+    props: DatabaseCommonInteractionProps;
+  }): Promise<void>;
+
+  recordUpdate<TModel extends BaseModel>(data: {
+    model: TModel;
+    before: TModel;
+    updatedFields: JSONObject;
+    itemId: ObjectID;
+    props: DatabaseCommonInteractionProps;
+  }): Promise<void>;
+
+  recordDelete<TModel extends BaseModel>(data: {
+    model: TModel;
+    deletedItem: TModel;
+    itemId: ObjectID;
+    props: DatabaseCommonInteractionProps;
+  }): Promise<void>;
+
+  invalidateProjectSettings(projectId: ObjectID): void;
+}
+
+export interface EnterpriseLicensingProvider {
+  /*
+   * Recomputes the snapshot from the cached inputs (token + stored columns)
+   * and the current time, so expiry and grace boundaries are exact. A failed
+   * refresh keeps the last good inputs; it never drops to "missing".
+   */
+  getSnapshot(): Promise<EnterpriseLicenseSnapshot>;
+
+  /*
+   * The synchronous twin for synchronous checks. Null until the first load
+   * finished. Configuration checks (isFeatureAvailableSync) treat null as "not
+   * licensed" (fail closed); runtime checks (isFeatureActive) treat it as
+   * active, so an unknown license state never locks anyone out.
+   */
+  getCachedSnapshot(): EnterpriseLicenseSnapshot | null;
+
+  refresh(): Promise<void>;
+
+  // Drops this process's cached inputs; the next read reloads them.
+  invalidate(): void;
+
+  getSeatUsage(): Promise<SeatUsage | null>;
+
+  /*
+   * Throws when adding one more user would exceed the license's seat limit.
+   * A no-op when billing is enabled or the license is not valid/grace.
+   */
+  assertSeatAvailableForNewUser(): Promise<void>;
+}
+
+export default interface EnterpriseServerModule {
+  name: typeof ENTERPRISE_SERVER_MODULE_NAME;
+  version: string;
+
+  /*
+   * Bounded by the loader with a timeout. Must not throw on a database blip,
+   * and must not make network calls the boot has to wait for.
+   */
+  init(): Promise<void>;
+
+  licensing: EnterpriseLicensingProvider;
+
+  /*
+   * Mounted at ["/api/identity", "/"] right after core's identity routers.
+   * RULE for every router below: no layer without a route (no router.use), because
+   * a path-less middleware in a router mounted at "/" or ahead of a core router
+   * runs for requests meant for core routes.
+   */
+  getIdentityRouters(): Array<ExpressRouter>;
+
+  // Mounted at "/api".
+  getApiRouters(): Array<ExpressRouter>;
+
+  // Mounted at "/api/admin/health" BEFORE core's AdminHealth router.
+  getAdminHealthRouter(): ExpressRouter | null;
+
+  // Requires the ee cron modules (RunCron registers at import time).
+  registerWorkerJobs(): Promise<void>;
+
+  getAuditLogRecorder(): AuditLogRecorder | null;
+}
+
+const REQUIRED_MODULE_FUNCTIONS: ReadonlyArray<string> = [
+  "init",
+  "getIdentityRouters",
+  "getApiRouters",
+  "getAdminHealthRouter",
+  "registerWorkerJobs",
+  "getAuditLogRecorder",
+];
+
+const REQUIRED_LICENSING_FUNCTIONS: ReadonlyArray<string> = [
+  "getSnapshot",
+  "getCachedSnapshot",
+  "refresh",
+  "invalidate",
+  "getSeatUsage",
+  "assertSeatAvailableForNewUser",
+];
+
+type LooseRecord = Record<string, unknown>;
+
+const isRecord: (value: unknown) => value is LooseRecord = (
+  value: unknown,
+): value is LooseRecord => {
+  return typeof value === "object" && value !== null;
+};
+
+export class EnterpriseServerModuleShape {
+  /*
+   * Every way `candidate` falls short of EnterpriseServerModule, as readable
+   * sentences. Empty means the shape is right. Used by the loader (a wrong
+   * shape is a broken build: fail fast) and by ee's own shape test.
+   */
+  public static findProblems(candidate: unknown): Array<string> {
+    const problems: Array<string> = [];
+
+    if (!isRecord(candidate)) {
+      problems.push(
+        `the module must export an object, but it exported ${candidate === null ? "null" : typeof candidate}`,
+      );
+      return problems;
+    }
+
+    if (candidate["name"] !== ENTERPRISE_SERVER_MODULE_NAME) {
+      problems.push(
+        `"name" must be "${ENTERPRISE_SERVER_MODULE_NAME}", but it is ${JSON.stringify(candidate["name"]) ?? "undefined"}`,
+      );
+    }
+
+    if (
+      typeof candidate["version"] !== "string" ||
+      candidate["version"].trim().length === 0
+    ) {
+      problems.push(`"version" must be a non-empty string`);
+    }
+
+    for (const functionName of REQUIRED_MODULE_FUNCTIONS) {
+      if (typeof candidate[functionName] !== "function") {
+        problems.push(`"${functionName}" must be a function`);
+      }
+    }
+
+    const licensing: unknown = candidate["licensing"];
+
+    if (!isRecord(licensing)) {
+      problems.push(`"licensing" must be an object`);
+      return problems;
+    }
+
+    for (const functionName of REQUIRED_LICENSING_FUNCTIONS) {
+      if (typeof licensing[functionName] !== "function") {
+        problems.push(`"licensing.${functionName}" must be a function`);
+      }
+    }
+
+    return problems;
+  }
+
+  /*
+   * The router-contract check: describes every layer of `router` that is not a
+   * route (a router.use middleware or sub-router). Empty means the router
+   * cannot shadow a core route.
+   */
+  public static findLayersWithoutRoute(router: ExpressRouter): Array<string> {
+    const stack: unknown = (router as unknown as LooseRecord)["stack"];
+
+    if (!Array.isArray(stack)) {
+      return ["the router has no layer stack (is it an express Router?)"];
+    }
+
+    const problems: Array<string> = [];
+
+    stack.forEach((layer: unknown, index: number): void => {
+      if (isRecord(layer) && layer["route"]) {
+        return;
+      }
+
+      const name: string =
+        isRecord(layer) && typeof layer["name"] === "string"
+          ? layer["name"]
+          : "<unknown>";
+      const pattern: string =
+        isRecord(layer) && layer["regexp"] instanceof RegExp
+          ? layer["regexp"].toString()
+          : "<no pattern>";
+
+      problems.push(
+        `layer ${index} ("${name}", ${pattern}) is a router.use() layer, not a route`,
+      );
+    });
+
+    return problems;
+  }
+}

package/Server/EnvironmentConfig.ts

@@ -1059,6 +1059,95 @@ export const EnableProfiling: boolean =
 export const IsEnterpriseEdition: boolean =
   process.env["IS_ENTERPRISE_EDITION"] === "true";
 
+/*
+ * Which edition this process should run (ONEUPTIME_EDITION):
+ *   auto        (default) load the enterprise module from ee/ when it is present
+ *   community   never load it, even when ee/ is present
+ *   enterprise  it MUST load; a missing or broken ee/ stops the boot (the
+ *               Enterprise image sets this, so a broken image never silently
+ *               runs as the Community Edition)
+ *
+ * The effective edition is EnterpriseEdition.isLoaded(), decided at boot by
+ * packages/App/Utils/EnterpriseLoader.ts. IS_ENTERPRISE_EDITION above turns
+ * nothing on: it only says the Enterprise Edition is expected (see
+ * isEnterpriseEditionRequested below), and the boot stops when it is expected
+ * but the enterprise module did not load.
+ */
+export type OneUptimeEditionSetting = "auto" | "community" | "enterprise";
+
+export const ONEUPTIME_EDITION_SETTINGS: ReadonlyArray<OneUptimeEditionSetting> =
+  ["auto", "community", "enterprise"];
+
+// Unset or blank reads as "auto"; an unrecognised value is null.
+export const parseOneUptimeEdition: (
+  rawValue: string | undefined,
+) => OneUptimeEditionSetting | null = (
+  rawValue: string | undefined,
+): OneUptimeEditionSetting | null => {
+  const value: string = (rawValue || "").trim().toLowerCase();
+
+  if (!value) {
+    return "auto";
+  }
+
+  return (
+    ONEUPTIME_EDITION_SETTINGS.find(
+      (setting: OneUptimeEditionSetting): boolean => {
+        return setting === value;
+      },
+    ) || null
+  );
+};
+
+/*
+ * Null when ONEUPTIME_EDITION holds something unrecognised: the loader refuses
+ * to boot rather than guess which edition a typo meant.
+ */
+export const OneUptimeEdition: OneUptimeEditionSetting | null =
+  parseOneUptimeEdition(process.env["ONEUPTIME_EDITION"]);
+
+/*
+ * Whether this install asks for the Enterprise Edition: IS_ENTERPRISE_EDITION
+ * is exactly "true", unless ONEUPTIME_EDITION=community explicitly chooses the
+ * Community Edition. The Enterprise image bakes IS_ENTERPRISE_EDITION=true, and
+ * ONEUPTIME_EDITION=community is the documented way to run that image as the
+ * Community Edition, so that combination is a deliberate choice, not a
+ * mismatch.
+ *
+ * This is the one definition behind both the App's boot guard
+ * (packages/App/Utils/EnterpriseLoader.ts: requested but not loaded stops the
+ * boot) and the frontends' ENTERPRISE_EDITION_REQUESTED_BUT_NOT_LOADED notice
+ * (Server/Utils/FrontendEnvironment.ts), so the two never disagree. It takes
+ * the environment as an argument, so a caller can read it when it needs to.
+ */
+export const isEnterpriseEditionRequested: (
+  environment: Record<string, string | undefined>,
+) => boolean = (environment: Record<string, string | undefined>): boolean => {
+  return (
+    environment["IS_ENTERPRISE_EDITION"] === "true" &&
+    parseOneUptimeEdition(environment["ONEUPTIME_EDITION"]) !== "community"
+  );
+};
+
+export const IsEnterpriseEditionRequested: boolean =
+  isEnterpriseEditionRequested(process.env);
+
+/*
+ * Overrides where the loader looks for the ee/ directory (tests and fixtures).
+ * Unset: the repo layout <root>/ee, then the container layout /usr/src/ee.
+ */
+export const OneUptimeEnterpriseDirectory: string | undefined =
+  process.env["ONEUPTIME_EE_DIR"]?.trim() || undefined;
+
+/*
+ * The hosted oneuptime.com (billing enabled) must run the Enterprise image:
+ * on the Community image paid SSO and audit logging would silently stop, and
+ * the license server self-hosted customers activate against would be gone. The
+ * boot refuses that combination unless this development escape hatch is set.
+ */
+export const AllowBillingWithoutEnterprise: boolean =
+  process.env["ALLOW_BILLING_WITHOUT_ENTERPRISE"] === "true";
+
 export const AverageSpanRowSizeInBytes: number = parsePositiveNumberFromEnv(
   "AVERAGE_SPAN_ROW_SIZE_IN_BYTES",
   1024,
@@ -1182,12 +1271,68 @@ export const PushNotificationRelayUrl: string =
   process.env["PUSH_NOTIFICATION_RELAY_URL"] ||
   "https://oneuptime.com/api/notification/push-relay/send";
 
+export const DEFAULT_ENTERPRISE_LICENSE_SERVER_URL: string =
+  "https://oneuptime.com";
+
+const TRAILING_SLASHES_PATTERN: RegExp = /\/+$/;
+
+/*
+ * The license server self-hosted Enterprise installs activate against and
+ * report seat usage to. Overridable for a staging license server or an
+ * internal relay. The license key travels in these requests, so plain http is
+ * accepted only when `allowInsecure` (development and test environments);
+ * anything else unusable - empty, unparseable, another scheme, or http in
+ * production - falls back to the default rather than sending the key in the
+ * clear.
+ */
+export const resolveEnterpriseLicenseServerUrl: (
+  rawValue: string | undefined,
+  allowInsecure: boolean,
+) => string = (
+  rawValue: string | undefined,
+  allowInsecure: boolean,
+): string => {
+  const value: string = (rawValue || "")
+    .trim()
+    .replace(TRAILING_SLASHES_PATTERN, "");
+
+  if (!value) {
+    return DEFAULT_ENTERPRISE_LICENSE_SERVER_URL;
+  }
+
+  const lowerCasedValue: string = value.toLowerCase();
+  const isHttps: boolean = lowerCasedValue.startsWith("https://");
+  const isHttp: boolean = lowerCasedValue.startsWith("http://");
+
+  if (!isHttps && !(isHttp && allowInsecure)) {
+    return DEFAULT_ENTERPRISE_LICENSE_SERVER_URL;
+  }
+
+  try {
+    URL.fromString(value);
+  } catch {
+    return DEFAULT_ENTERPRISE_LICENSE_SERVER_URL;
+  }
+
+  return value;
+};
+
+const enterpriseLicenseServerUrlValue: string =
+  resolveEnterpriseLicenseServerUrl(
+    process.env["ENTERPRISE_LICENSE_SERVER_URL"],
+    IsDevelopment || IsTest,
+  );
+
+export const EnterpriseLicenseServerUrl: URL = URL.fromString(
+  enterpriseLicenseServerUrlValue,
+);
+
 export const EnterpriseLicenseValidationUrl: URL = URL.fromString(
-  "https://oneuptime.com/api/enterprise-license/validate",
+  `${enterpriseLicenseServerUrlValue}/api/enterprise-license/validate`,
 );
 
 export const EnterpriseLicenseUserCountReportUrl: URL = URL.fromString(
-  "https://oneuptime.com/api/enterprise-license/report-user-count",
+  `${enterpriseLicenseServerUrlValue}/api/enterprise-license/report-user-count`,
 );
 
 /*

package/Server/Infrastructure/Postgres/SchemaMigrations/1793900000000-AddEnterpriseEditionFirstSeenAt.ts

@@ -0,0 +1,25 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/*
+ * Generated with npm run generate-postgres-migration. GlobalConfig gains the
+ * moment this installation first booted the Enterprise Edition; an unlicensed
+ * Enterprise install gets its 14-day trial counted from it. Nullable with no
+ * default: the enterprise module stamps it on its own first boot.
+ */
+export class AddEnterpriseEditionFirstSeenAt1793900000000
+  implements MigrationInterface
+{
+  public name: string = "AddEnterpriseEditionFirstSeenAt1793900000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "GlobalConfig" ADD "enterpriseEditionFirstSeenAt" TIMESTAMP WITH TIME ZONE`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "GlobalConfig" DROP COLUMN "enterpriseEditionFirstSeenAt"`,
+    );
+  }
+}