@oneuptime/common 12.0.20 → 12.0.22

package/Server/Services/UserTwoFactorBackupCodeService.ts

@@ -0,0 +1,355 @@
+import DatabaseService from "./DatabaseService";
+import Model from "../../Models/DatabaseModels/UserTwoFactorBackupCode";
+import TwoFactorBackupCode, {
+  BackupCodeSetSize,
+} from "../Utils/TwoFactorBackupCode";
+import CreateBy from "../Types/Database/CreateBy";
+import { OnCreate } from "../Types/Database/Hooks";
+import QueryHelper from "../Types/Database/QueryHelper";
+import BadDataException from "../../Types/Exception/BadDataException";
+import LIMIT_MAX from "../../Types/Database/LimitMax";
+import SortOrder from "../../Types/BaseDatabase/SortOrder";
+import ObjectID from "../../Types/ObjectID";
+import PositiveNumber from "../../Types/PositiveNumber";
+import OneUptimeDate from "../../Types/Date";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import logger from "../Utils/Logger";
+
+/**
+ * How many of a user's backup codes are left, for the profile page and the
+ * admin's account view.
+ *
+ * `total` and `unused` are both reported rather than just the remaining count
+ * because they answer different questions: "have you set backup codes up at
+ * all" and "how many can you still use". A user with ten codes and a user who
+ * has spent all ten both have a `total` of ten, and only the second needs to
+ * be told to regenerate.
+ */
+export interface TwoFactorBackupCodeStatus {
+  total: number;
+  unused: number;
+
+  /*
+   * When the current set was minted, or null if there are none. Read off the
+   * newest row rather than stored separately -- regeneration replaces the
+   * whole set in one call, so every row in a set shares a creation time to
+   * within a few milliseconds.
+   */
+  generatedAt: Date | null;
+}
+
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  /*
+   * The model denies create to everyone, so the only way a row is written is
+   * `regenerateForUser` below, as root. This hook is the second lock on the
+   * same door: it refuses any create that did not come through there.
+   *
+   * Worth having both because the two guards fail differently. The table
+   * permission is enforced by the CRUD API layer and is bypassed wholesale by
+   * `isRoot`, which every internal caller uses -- so a future service that
+   * reaches for `UserTwoFactorBackupCodeService.create()` with a plaintext
+   * code, or with no owner, would sail past it. What lands in `codeHash` is
+   * the credential; there is no recovering from writing the wrong thing there.
+   */
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.data.userId) {
+      throw new BadDataException("User id is required");
+    }
+
+    if (!createBy.data.codeHash) {
+      throw new BadDataException("Backup code hash is required");
+    }
+
+    /*
+     * A code that arrives already spent is a caller confusing itself about
+     * which end of the lifecycle it is at. Codes are minted usable and are
+     * spent only by `consumeCode`.
+     *
+     * Deleted rather than set to undefined: `exactOptionalPropertyTypes` is on,
+     * so the property being ABSENT and the property holding `undefined` are
+     * different things to the compiler, and only the first is allowed here.
+     */
+    delete createBy.data.usedAt;
+
+    return {
+      createBy: createBy,
+      carryForward: {},
+    };
+  }
+
+  /**
+   * Mint a fresh set of backup codes for one user, replacing whatever they
+   * had, and return the PLAINTEXT codes.
+   *
+   * This is the only moment the plaintext exists anywhere. The caller shows it
+   * to the user once and then it is gone -- only the keyed digests are stored,
+   * so nothing (not this service, not a master admin, not a database dump) can
+   * produce the codes again. That is the property the feature is worth having
+   * for, and it is why the API route wraps this in a response the UI is
+   * expected to make the user acknowledge.
+   *
+   * REPLACING rather than adding is deliberate. "Generate more codes" would
+   * leave the codes from a list the user printed, lost and then regenerated
+   * over still working, which defeats the point of regenerating after a
+   * suspected compromise.
+   *
+   * ALL OR NOTHING, and this is the part that needs care. The old set is
+   * deleted first, then the new rows are written one at a time -- so a failure
+   * partway through the loop would otherwise leave the account holding a few
+   * rows that WERE written and that the caller, having thrown, never showed to
+   * anybody. `getStatusForUser` would then report "4 backup codes" to a user
+   * who has never seen one of them: codes that are unusable in practice and
+   * that hide the fact that they have no recovery route left. That is the
+   * worst state this feature can produce, because it looks exactly like the
+   * good one.
+   *
+   * So a failure is compensated: everything written for this user is removed,
+   * and the account ends with NO codes and an error on screen. "You have no
+   * backup codes" is a state the profile page already tells the user to fix;
+   * "you have four codes you have never seen" is not.
+   *
+   * The compensating delete is itself best-effort -- if it also fails there is
+   * nothing further to try -- but it turns a silent, permanent trap into two
+   * consecutive infrastructure failures.
+   */
+  @CaptureSpan()
+  public async regenerateForUser(data: {
+    userId: ObjectID;
+    count?: number | undefined;
+  }): Promise<Array<string>> {
+    const count: number = data.count || BackupCodeSetSize;
+
+    await this.deleteAllForUser({ userId: data.userId });
+
+    const codes: Array<string> = TwoFactorBackupCode.generateCodeSet(count);
+
+    try {
+      for (const code of codes) {
+        const backupCode: Model = new Model();
+        backupCode.userId = data.userId;
+        backupCode.codeHash = TwoFactorBackupCode.hashCode({
+          code: code,
+          userId: data.userId,
+        });
+
+        await this.create({
+          data: backupCode,
+          props: {
+            isRoot: true,
+          },
+        });
+      }
+    } catch (err) {
+      try {
+        await this.deleteAllForUser({ userId: data.userId });
+      } catch (cleanupError) {
+        /*
+         * Swallowed so the ORIGINAL failure is what the caller sees. The
+         * cleanup error is the less useful of the two -- it explains why the
+         * rollback did not happen, not why the write did not.
+         */
+        logger.error(cleanupError);
+      }
+
+      throw err;
+    }
+
+    return codes;
+  }
+
+  /**
+   * Spend one of this user's backup codes, if the submitted code is one of
+   * them and has not been used already.
+   *
+   * ONE STATEMENT, ON PURPOSE
+   *
+   * The obvious shape -- find the row, check `usedAt`, then update it -- has a
+   * window between the read and the write, and "single use" is the entire
+   * guarantee a backup code offers. Two sign-in attempts carrying the same
+   * code that arrive together would both read a null `usedAt` and both be let
+   * in, which is precisely the property an attacker who has watched somebody
+   * type a code off a printed list would exploit.
+   *
+   * `usedAt IS NULL` in the WHERE clause moves the decision inside Postgres,
+   * where the row lock settles it: the first statement to reach the row
+   * updates it, the second matches nothing. `RETURNING "_id"` is what turns
+   * that into an answer for the caller -- an UPDATE that matched no rows and
+   * an UPDATE that matched one are otherwise indistinguishable from here.
+   *
+   * Written as raw parameterized SQL rather than through the ORM because no
+   * write path on DatabaseService both takes a non-primary-key predicate and
+   * reports what it matched. Column and table names are literals in this file,
+   * never caller input, and all three values are bound parameters.
+   *
+   * `deletedAt IS NULL` is included because soft-deleted rows are still
+   * physically present; without it, a code from a set that regeneration
+   * replaced would still sign somebody in.
+   *
+   * @returns true when a code was spent, false when the code was wrong,
+   *          already used, or belongs to somebody else.
+   */
+  @CaptureSpan()
+  public async consumeCode(data: {
+    userId: ObjectID;
+    code: string;
+  }): Promise<boolean> {
+    const normalizedCode: string = TwoFactorBackupCode.normalizeCode(data.code);
+
+    /*
+     * Refused before the query rather than hashed and looked up. An empty
+     * submission cannot be anybody's code, and letting it through would mean
+     * one round trip per empty request on a route an attacker can call.
+     */
+    if (!normalizedCode) {
+      return false;
+    }
+
+    const codeHash: string = TwoFactorBackupCode.hashCode({
+      code: normalizedCode,
+      userId: data.userId,
+    });
+
+    const rows: Array<{ _id: string }> = await this.getRepository()
+      .manager.query(
+        `UPDATE "UserTwoFactorBackupCode"
+            SET "usedAt" = $1, "updatedAt" = CURRENT_TIMESTAMP
+          WHERE "userId" = $2
+            AND "codeHash" = $3
+            AND "usedAt" IS NULL
+            AND "deletedAt" IS NULL
+      RETURNING "_id"`,
+        [OneUptimeDate.getCurrentDate(), data.userId.toString(), codeHash],
+      )
+      /*
+       * For an UPDATE the postgres driver hands back `[rows, rowCount]` rather
+       * than a bare row array, so the rows have to be unwrapped. Written
+       * defensively: a driver that returns the bare array instead must read as
+       * "no code was spent", never as a silent success.
+       */
+      .then((result: unknown): Array<{ _id: string }> => {
+        if (!Array.isArray(result)) {
+          return [];
+        }
+
+        const first: unknown = result[0];
+
+        return Array.isArray(first) ? (first as Array<{ _id: string }>) : [];
+      });
+
+    return rows.length > 0;
+  }
+
+  /**
+   * How many codes this user has, and how many are still spendable.
+   *
+   * Counted rather than fetched: the rows carry a credential digest and there
+   * is no caller that needs them, so nothing is loaded that a stray log line
+   * could then print.
+   */
+  @CaptureSpan()
+  public async getStatusForUser(data: {
+    userId: ObjectID;
+  }): Promise<TwoFactorBackupCodeStatus> {
+    const total: PositiveNumber = await this.countBy({
+      query: {
+        userId: data.userId,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    if (total.toNumber() === 0) {
+      return {
+        total: 0,
+        unused: 0,
+        generatedAt: null,
+      };
+    }
+
+    const unused: number = await this.countUnusedForUser({
+      userId: data.userId,
+    });
+
+    const newest: Model | null = await this.findOneBy({
+      query: {
+        userId: data.userId,
+      },
+      select: {
+        createdAt: true,
+      },
+      sort: {
+        createdAt: SortOrder.Descending,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return {
+      total: total.toNumber(),
+      unused: unused,
+      generatedAt: newest?.createdAt || null,
+    };
+  }
+
+  /**
+   * How many unused codes this user has left.
+   *
+   * Split out from `getStatusForUser` because the login path needs exactly
+   * this number and nothing else: it decides whether the two factor challenge
+   * screen offers "use a backup code" at all, and it is answered on every
+   * two-factor sign-in.
+   *
+   * `usedAt: QueryHelper.isNull()` rather than `usedAt: null`. A bare null
+   * predicate is dropped by TypeORM rather than compiled to `IS NULL`, so the
+   * count would silently include spent codes and the login page would offer a
+   * recovery route to a user with nothing left to recover with.
+   */
+  @CaptureSpan()
+  public async countUnusedForUser(data: { userId: ObjectID }): Promise<number> {
+    const unused: PositiveNumber = await this.countBy({
+      query: {
+        userId: data.userId,
+        usedAt: QueryHelper.isNull(),
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return unused.toNumber();
+  }
+
+  /**
+   * Drop every backup code this user has.
+   *
+   * Called by regeneration, and by UserService.resetTwoFactorAuth -- an
+   * operator resetting two factor auth for somebody who lost a device must
+   * take the recovery codes with it. Leaving them behind would mean the reset
+   * did not actually revoke the account's second-factor material, which is the
+   * one thing the operator pressed the button to do.
+   */
+  @CaptureSpan()
+  public async deleteAllForUser(data: { userId: ObjectID }): Promise<void> {
+    await this.deleteBy({
+      query: {
+        userId: data.userId,
+      },
+      limit: LIMIT_MAX,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    });
+  }
+}
+
+export default new Service();

package/Server/Utils/Attribution.ts

@@ -11,12 +11,12 @@ import { JSONObject, JSONValue } from "../../Types/JSON";
 
 /*
  * Sanitizers for attribution submitted by unauthenticated callers — the signup
- * form, the Cal.com booking webhook, and the enterprise licence request form.
+ * form and the enterprise licence request form.
  *
- * Everything here is a whitelist, never a denylist. Cal booking metadata and
- * form bodies are free-form caller content (names, notes, answers to booking
- * questions), and only the keys named in Common/Types/Marketing/Attribution.ts
- * may be copied into a row that is later forwarded to an ad platform.
+ * Everything here is a whitelist, never a denylist. Form bodies are free-form
+ * caller content (names, notes, free-text answers), and only the keys named in
+ * Common/Types/Marketing/Attribution.ts may be copied into a row that is later
+ * forwarded to an ad platform.
  *
  * This file also owns email normalisation and hashing. Meta and Reddit each
  * used to carry a private copy of the hash, and MarketingConversion.emailHash
@@ -101,10 +101,10 @@ export default class Attribution {
   /*
    * UTM values out of an arbitrary object, accepting either spelling.
    *
-   * A URL and Cal booking metadata carry `utm_source`; a JSON body posted by
-   * the signup page carries `utmSource`. Both arrive at server doors that
-   * write the same columns, so both are read here rather than making each
-   * caller remember which shape it is holding. camelCase wins when a caller
+   * A URL carries `utm_source`; a JSON body posted by the signup page carries
+   * `utmSource`. Both arrive at server doors that write the same columns, so
+   * both are read here rather than making each caller remember which shape it
+   * is holding. camelCase wins when a caller
    * somehow sends both, because that is the spelling the browser writes
    * deliberately and the snake_case one is the raw URL echo.
    */
@@ -180,8 +180,8 @@ export default class Attribution {
 
   /*
    * SHA-256 of the normalised email, hex encoded — the identifier every ad
-   * platform's enhanced matching expects, and the key the conversion ledger
-   * joins a booked meeting to the signup it later produced.
+   * platform's enhanced matching expects, and the key a receiver joins one
+   * person's conversions on.
    */
   public static hashEmail(email: string | undefined): string | null {
     const normalized: string | null = this.normalizeEmail(email);

package/Server/Utils/Marketing/MarketingEventWebhook.ts

@@ -12,8 +12,8 @@ const REQUEST_TIMEOUT_MS: number = 15000;
 /*
  * Delivers marketing conversion events to one operator-configured endpoint.
  *
- * OneUptime keeps no conversion ledger, so this is the only exit for a signup,
- * a booked meeting or a plan change. That has one consequence worth stating
+ * OneUptime keeps no conversion ledger, so this is the only exit for a signup
+ * or a plan change. That has one consequence worth stating
  * plainly: a delivery this class gives up on is gone, because there is no row
  * anywhere to reconcile against later. deliver() therefore THROWS on anything
  * that might succeed on a retry, and the queue is what retries it.
@@ -21,9 +21,8 @@ const REQUEST_TIMEOUT_MS: number = 15000;
  * SIGNING
  *
  * The signature is HMAC-SHA256 over the exact request body bytes, hex encoded,
- * in `x-oneuptime-signature-256`. This is the same scheme OneUptime verifies
- * on the way in from Cal, deliberately: one thing to understand rather than
- * two. The receiver must compute its digest over the raw bytes it received —
+ * in `x-oneuptime-signature-256`. The receiver must compute its digest over
+ * the raw bytes it received —
  * JSON parsed and re-serialised is NOT equivalent, because whitespace, key
  * order and escaping all change the digest.
  *

package/Server/Utils/Telemetry/ChangeEventRow.ts

@@ -0,0 +1,228 @@
+import Dictionary from "../../../Types/Dictionary";
+import OneUptimeDate from "../../../Types/Date";
+import ObjectID from "../../../Types/ObjectID";
+import { JSONArray, JSONObject } from "../../../Types/JSON";
+/*
+ * Type-only: pulling the ingest service's runtime graph into this pure
+ * module would drag ClickHouse/DB deps into every test that touches it.
+ */
+import type { TelemetryServiceMetadata } from "../../Services/OpenTelemetryIngestService";
+
+/*
+ * Change-event ingest parsing + ClickHouse row building. Pure on purpose
+ * (no network, no request objects) so App/Tests can pin every validation
+ * rule without a server.
+ */
+
+/*
+ * Events whose source timestamp is outside this window are stamped with
+ * the ingestion time instead (original preserved in attributes). The
+ * table partitions by toYYYYMMDD(time), so a forged or garbage timestamp
+ * must not be allowed to create arbitrary partitions.
+ */
+export const MAX_CHANGE_EVENT_AGE_IN_DAYS: number = 366;
+export const MAX_CHANGE_EVENT_FUTURE_SKEW_IN_MINUTES: number = 60;
+
+// Caps keep a CI script's mistake from becoming a storage problem.
+export const MAX_CHANGE_EVENTS_PER_REQUEST: number = 100;
+export const MAX_CHANGE_EVENT_TITLE_LENGTH: number = 500;
+export const MAX_CHANGE_EVENT_DESCRIPTION_LENGTH: number = 5000;
+export const MAX_CHANGE_EVENT_TYPE_LENGTH: number = 50;
+export const MAX_CHANGE_EVENT_ATTRIBUTES: number = 50;
+
+export const DEFAULT_CHANGE_EVENT_TYPE: string = "deployment";
+
+/*
+ * Serviceless change events (project-wide markers) have no service
+ * retention ladder to consult; deploy markers are tiny and valuable for
+ * long-baseline comparisons, so keep them a year.
+ */
+export const DEFAULT_CHANGE_EVENT_RETENTION_IN_DAYS: number = 365;
+
+export interface ParsedChangeEventEntry {
+  /** null → stamp with the ingestion time. */
+  time: Date | null;
+  eventType: string;
+  title: string;
+  description: string;
+  attributes: Dictionary<string>;
+}
+
+function parseEntryTime(value: unknown): Date | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    /*
+     * Epoch seconds vs milliseconds: anything below 1e12 read as ms would
+     * be before 2001 — CI clocks don't say that; treat it as seconds.
+     */
+    const ms: number = value < 1e12 ? value * 1000 : value;
+    const date: Date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const date: Date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  return null;
+}
+
+/**
+ * Validate one raw ingest entry. Returns null when the entry cannot be a
+ * change event at all (no usable title); every other malformation is
+ * repaired (defaults, trims, caps) rather than rejected — CI pipelines
+ * should not fail a deploy over a long description.
+ */
+export function parseChangeEventIngestEntry(
+  entry: JSONObject,
+): ParsedChangeEventEntry | null {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+
+  const rawTitle: unknown = entry["title"] ?? entry["name"];
+  const title: string =
+    typeof rawTitle === "string"
+      ? rawTitle.trim().slice(0, MAX_CHANGE_EVENT_TITLE_LENGTH)
+      : "";
+
+  if (title === "") {
+    return null;
+  }
+
+  const rawEventType: unknown = entry["eventType"] ?? entry["type"];
+  const eventType: string =
+    typeof rawEventType === "string" && rawEventType.trim() !== ""
+      ? rawEventType.trim().toLowerCase().slice(0, MAX_CHANGE_EVENT_TYPE_LENGTH)
+      : DEFAULT_CHANGE_EVENT_TYPE;
+
+  const rawDescription: unknown = entry["description"];
+  const description: string =
+    typeof rawDescription === "string"
+      ? rawDescription.trim().slice(0, MAX_CHANGE_EVENT_DESCRIPTION_LENGTH)
+      : "";
+
+  const attributes: Dictionary<string> = {};
+  const rawAttributes: unknown = entry["attributes"];
+  if (
+    rawAttributes &&
+    typeof rawAttributes === "object" &&
+    !Array.isArray(rawAttributes)
+  ) {
+    for (const key of Object.keys(rawAttributes as JSONObject)) {
+      if (key.trim() === "") {
+        continue;
+      }
+      if (Object.keys(attributes).length >= MAX_CHANGE_EVENT_ATTRIBUTES) {
+        break;
+      }
+      const value: unknown = (rawAttributes as JSONObject)[key];
+      if (
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean"
+      ) {
+        attributes[key] = String(value);
+      }
+    }
+  }
+
+  return {
+    time: parseEntryTime(entry["time"] ?? entry["timestamp"]),
+    eventType,
+    title,
+    description,
+    attributes,
+  };
+}
+
+/**
+ * Accept the shapes CI scripts actually send: a bare object (one event),
+ * a bare array, or { events: [...] }.
+ */
+export function extractChangeEventEntries(body: unknown): Array<JSONObject> {
+  if (!body) {
+    return [];
+  }
+
+  if (Array.isArray(body)) {
+    return (body as JSONArray).filter((item: unknown): boolean => {
+      return typeof item === "object" && item !== null && !Array.isArray(item);
+    }) as Array<JSONObject>;
+  }
+
+  if (typeof body !== "object") {
+    return [];
+  }
+
+  const asObject: JSONObject = body as JSONObject;
+  const nested: unknown = asObject["events"];
+  if (Array.isArray(nested)) {
+    return extractChangeEventEntries(nested);
+  }
+
+  // A single bare event object — but not the {events: <non-array>} shape.
+  if (nested === undefined && Object.keys(asObject).length > 0) {
+    return [asObject];
+  }
+
+  return [];
+}
+
+/**
+ * ParsedChangeEventEntry -> ChangeEvent ClickHouse row.
+ */
+export function buildChangeEventDbRow(data: {
+  parsed: ParsedChangeEventEntry;
+  projectId: ObjectID;
+  serviceMetadata: TelemetryServiceMetadata | null;
+  retentionDays: number;
+}): JSONObject {
+  const { parsed, projectId, serviceMetadata, retentionDays } = data;
+
+  const ingestionDate: Date = OneUptimeDate.getCurrentDate();
+
+  let eventTime: Date = parsed.time || ingestionDate;
+  let attributes: Dictionary<string> = { ...parsed.attributes };
+
+  const ageInDays: number = OneUptimeDate.getNumberOfDaysBetweenDates(
+    eventTime,
+    ingestionDate,
+  );
+  const futureSkewInMinutes: number =
+    (eventTime.getTime() - ingestionDate.getTime()) / (60 * 1000);
+
+  if (
+    Number.isNaN(eventTime.getTime()) ||
+    ageInDays > MAX_CHANGE_EVENT_AGE_IN_DAYS ||
+    futureSkewInMinutes > MAX_CHANGE_EVENT_FUTURE_SKEW_IN_MINUTES
+  ) {
+    attributes = {
+      ...attributes,
+      "oneuptime.original_time": String(parsed.time),
+    };
+    eventTime = ingestionDate;
+  }
+
+  const retentionDate: Date = OneUptimeDate.addRemoveDays(
+    ingestionDate,
+    retentionDays,
+  );
+
+  return {
+    _id: ObjectID.generateTimeOrdered().toString(),
+    createdAt: OneUptimeDate.toClickhouseDateTime(ingestionDate),
+    projectId: projectId.toString(),
+    ...(serviceMetadata
+      ? {
+          primaryEntityId: serviceMetadata.primaryEntityId.toString(),
+          primaryEntityType: serviceMetadata.primaryEntityType,
+        }
+      : {}),
+    time: OneUptimeDate.toClickhouseDateTime64(eventTime),
+    eventType: parsed.eventType,
+    title: parsed.title,
+    description: parsed.description,
+    attributes,
+    attributeKeys: Object.keys(attributes).sort(),
+    retentionDate: OneUptimeDate.toClickhouseDateTime(retentionDate),
+  } satisfies JSONObject;
+}