@oneuptime/common 12.0.29 → 12.0.30

package/Server/Services/UserOnCallCalendarFeedService.ts

@@ -0,0 +1,159 @@
+import CreateBy from "../Types/Database/CreateBy";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnUpdate } from "../Types/Database/Hooks";
+import DatabaseService from "./DatabaseService";
+import CalendarFeedToken, {
+  CalendarFeedRotation,
+  MintedCalendarFeedToken,
+} from "../Utils/OnCall/CalendarFeedToken";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import Model from "../../Models/DatabaseModels/UserOnCallCalendarFeed";
+import BadDataException from "../../Types/Exception/BadDataException";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+import NotFoundException from "../../Types/Exception/NotFoundException";
+import CalendarFeedWindow from "../../Types/OnCallDutyPolicy/CalendarFeedWindow";
+import ObjectID from "../../Types/ObjectID";
+import OneUptimeDate from "../../Types/Date";
+
+/*
+ * The personal calendar feed row: one per (project, user).
+ *
+ * WHAT THE HOOKS GUARANTEE
+ *
+ *   - Only root creates one. The table create list is already empty, but the
+ *     hook says it out loud: the plaintext token is minted here or by the
+ *     calendar API, never by a request body.
+ *   - A created row always carries a consistent token set (see
+ *     CalendarFeedToken.applyTokenColumnsOnCreate): there is no path to a row
+ *     whose hash does not match its token.
+ *   - pastDays / futureDays are clamped to the CalendarFeedWindow bounds on
+ *     every write, so a feed can never be asked to render a year.
+ *
+ * Rotation lives here too (rotateTokenById) so the grace-hash bookkeeping is
+ * written once and the API, the member-leave cleanup and the tests share it.
+ * Cache purging is the caller's job - this service knows nothing about the
+ * feed cache.
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Calendar feeds are generated by the calendar API, not created directly.",
+      );
+    }
+
+    const projectId: ObjectID | undefined =
+      createBy.data.projectId || createBy.props.tenantId;
+
+    if (!projectId) {
+      throw new BadDataException("projectId is required");
+    }
+
+    if (!createBy.data.userId) {
+      throw new BadDataException("userId is required");
+    }
+
+    createBy.data.projectId = projectId;
+
+    // Root only reaches this line, so a pre-minted token may be trusted.
+    CalendarFeedToken.applyTokenColumnsOnCreate(createBy.data, {
+      trustSuppliedToken: true,
+    });
+
+    createBy.data.pastDays = CalendarFeedWindow.clampPastDays(
+      createBy.data.pastDays,
+    );
+    createBy.data.futureDays = CalendarFeedWindow.clampFutureDays(
+      createBy.data.futureDays,
+    );
+
+    return { createBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    if (updateBy.data.pastDays !== undefined) {
+      updateBy.data.pastDays = CalendarFeedWindow.clampPastDays(
+        updateBy.data.pastDays,
+      );
+    }
+
+    if (updateBy.data.futureDays !== undefined) {
+      updateBy.data.futureDays = CalendarFeedWindow.clampFutureDays(
+        updateBy.data.futureDays,
+      );
+    }
+
+    return { updateBy, carryForward: null };
+  }
+
+  /**
+   * Create the feed row for a user in a project and hand the plaintext token
+   * back ONCE, so the caller can build the subscription URL without a
+   * decrypt round-trip. Root only; the caller is responsible for holding the
+   * per-(project, user) lock the API uses around mint-or-rotate.
+   */
+  @CaptureSpan()
+  public async createForUser(data: {
+    projectId: ObjectID;
+    userId: ObjectID;
+  }): Promise<{ feed: Model; minted: MintedCalendarFeedToken }> {
+    const minted: MintedCalendarFeedToken = CalendarFeedToken.mintSet();
+
+    const feed: Model = new Model();
+    feed.projectId = data.projectId;
+    feed.userId = data.userId;
+    feed.token = minted.token;
+    feed.rotatedAt = OneUptimeDate.getCurrentDate();
+
+    const created: Model = await this.create({
+      data: feed,
+      props: { isRoot: true },
+    });
+
+    return { feed: created, minted };
+  }
+
+  /**
+   * Rotate the token of an existing feed: mint a new one, move the current
+   * hash into the 30-day grace slot, stamp rotatedAt. Returns the new
+   * plaintext token ONCE. Root write; the caller purges caches.
+   */
+  @CaptureSpan()
+  public async rotateTokenById(data: {
+    id: ObjectID;
+  }): Promise<CalendarFeedRotation> {
+    const existing: Model | null = await this.findOneBy({
+      query: { _id: data.id },
+      select: { _id: true, tokenHash: true },
+      props: { isRoot: true, ignoreHooks: true },
+    });
+
+    if (!existing) {
+      throw new NotFoundException("Calendar feed not found.");
+    }
+
+    const rotation: CalendarFeedRotation = CalendarFeedToken.buildRotation({
+      currentTokenHash: existing.tokenHash,
+    });
+
+    await this.updateOneById({
+      id: data.id,
+      data: CalendarFeedToken.toRotationUpdateData(rotation),
+      props: { isRoot: true },
+    });
+
+    return rotation;
+  }
+}
+
+export default new Service();

package/Server/Services/UserOnCallShiftReminderLogService.ts

@@ -0,0 +1,151 @@
+import CreateBy from "../Types/Database/CreateBy";
+import DeleteBy from "../Types/Database/DeleteBy";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnDelete, OnUpdate } from "../Types/Database/Hooks";
+import DatabaseService from "./DatabaseService";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import Model, {
+  UserOnCallShiftReminderLogKind,
+} from "../../Models/DatabaseModels/UserOnCallShiftReminderLog";
+import BadDataException from "../../Types/Exception/BadDataException";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+import ObjectID from "../../Types/ObjectID";
+import OneUptimeDate from "../../Types/Date";
+
+const MILLISECONDS_PER_MINUTE: number = 60 * 1000;
+
+const ALLOWED_KINDS: Set<string> = new Set<string>(
+  Object.values(UserOnCallShiftReminderLogKind),
+);
+
+/*
+ * The shift-reminder ledger. Root only, in every direction: a claim row is
+ * the thing that makes "send exactly once" true, so nothing outside the
+ * worker may insert, edit or remove one.
+ *
+ * The create hook normalises the idempotency key so two workers that compute
+ * the same shift a few milliseconds apart still collide on the unique index:
+ * shiftStartsAt is truncated to the minute here as well as by the worker
+ * (belt and braces - the seam normalisation upstream already makes starts
+ * minute-granular, this makes it a guarantee of the table rather than of one
+ * caller), and minutesBeforeShift defaults to 0 for change notices.
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Shift reminder logs are written by the reminder worker only.",
+      );
+    }
+
+    const projectId: ObjectID | undefined =
+      createBy.data.projectId || createBy.props.tenantId;
+
+    if (!projectId) {
+      throw new BadDataException("projectId is required");
+    }
+
+    if (!createBy.data.userId) {
+      throw new BadDataException("userId is required");
+    }
+
+    if (!createBy.data.onCallDutyPolicyScheduleId) {
+      throw new BadDataException("onCallDutyPolicyScheduleId is required");
+    }
+
+    if (!createBy.data.shiftStartsAt) {
+      throw new BadDataException("shiftStartsAt is required");
+    }
+
+    if (
+      !createBy.data.kind ||
+      !ALLOWED_KINDS.has(createBy.data.kind as string)
+    ) {
+      throw new BadDataException(
+        `kind must be one of: ${Object.values(UserOnCallShiftReminderLogKind).join(", ")}`,
+      );
+    }
+
+    createBy.data.projectId = projectId;
+
+    createBy.data.shiftStartsAt = Service.truncateToMinute(
+      OneUptimeDate.fromString(createBy.data.shiftStartsAt),
+    );
+
+    createBy.data.minutesBeforeShift = Service.validateMinutesBeforeShift(
+      createBy.data.minutesBeforeShift,
+    );
+
+    if (!createBy.data.claimedAt) {
+      createBy.data.claimedAt = OneUptimeDate.getCurrentDate();
+    }
+
+    return { createBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    if (!updateBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Shift reminder logs are written by the reminder worker only.",
+      );
+    }
+
+    return { updateBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeDelete(
+    deleteBy: DeleteBy<Model>,
+  ): Promise<OnDelete<Model>> {
+    if (!deleteBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Shift reminder logs are written by the reminder worker only.",
+      );
+    }
+
+    return { deleteBy, carryForward: null };
+  }
+
+  // Zero the seconds and milliseconds. Part of the idempotency key.
+  public static truncateToMinute(date: Date): Date {
+    return new Date(
+      Math.floor(date.getTime() / MILLISECONDS_PER_MINUTE) *
+        MILLISECONDS_PER_MINUTE,
+    );
+  }
+
+  /*
+   * 0 (a change notice) or a positive whole number of minutes. Missing means
+   * 0. Anything else is a caller bug, not a value to store.
+   */
+  public static validateMinutesBeforeShift(value: unknown): number {
+    if (value === undefined || value === null) {
+      return 0;
+    }
+
+    const parsed: number =
+      typeof value === "string" && value.trim() !== ""
+        ? Number(value)
+        : (value as number);
+
+    if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 0) {
+      throw new BadDataException(
+        "minutesBeforeShift must be a whole number of minutes, 0 or more.",
+      );
+    }
+
+    return parsed;
+  }
+}
+
+export default new Service();

package/Server/Services/UserOnCallShiftReminderService.ts

@@ -0,0 +1,112 @@
+import CreateBy from "../Types/Database/CreateBy";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnUpdate } from "../Types/Database/Hooks";
+import DatabaseService from "./DatabaseService";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import Model, {
+  MAX_MINUTES_BEFORE_SHIFT,
+  MIN_MINUTES_BEFORE_SHIFT,
+} from "../../Models/DatabaseModels/UserOnCallShiftReminder";
+import BadDataException from "../../Types/Exception/BadDataException";
+import ObjectID from "../../Types/ObjectID";
+import PositiveNumber from "../../Types/PositiveNumber";
+
+/*
+ * "Remind me N minutes before my shift" rows.
+ *
+ * The hooks keep the table honest for the reminder worker: every row has an
+ * owner (defaulted to the session user when the client did not send one, so
+ * the settings page can post `{ minutesBeforeShift }` and nothing else), a
+ * project, and a lead time inside 15 minutes ... 2 weeks. A duplicate lead
+ * is answered with a message rather than a unique-violation 500.
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    const projectId: ObjectID | undefined =
+      createBy.data.projectId || createBy.props.tenantId;
+
+    if (!projectId) {
+      throw new BadDataException("projectId is required");
+    }
+
+    if (!createBy.data.userId && createBy.props.userId) {
+      createBy.data.userId = createBy.props.userId;
+    }
+
+    if (!createBy.data.userId) {
+      throw new BadDataException("userId is required");
+    }
+
+    createBy.data.projectId = projectId;
+
+    createBy.data.minutesBeforeShift = Service.validateMinutesBeforeShift(
+      createBy.data.minutesBeforeShift,
+    );
+
+    const duplicates: PositiveNumber = await this.countBy({
+      query: {
+        projectId: projectId,
+        userId: createBy.data.userId,
+        minutesBeforeShift: createBy.data.minutesBeforeShift,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    if (duplicates.toNumber() > 0) {
+      throw new BadDataException(
+        `You already have a reminder ${createBy.data.minutesBeforeShift} minutes before your shifts.`,
+      );
+    }
+
+    return { createBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    if (updateBy.data.minutesBeforeShift !== undefined) {
+      updateBy.data.minutesBeforeShift = Service.validateMinutesBeforeShift(
+        updateBy.data.minutesBeforeShift,
+      );
+    }
+
+    return { updateBy, carryForward: null };
+  }
+
+  /*
+   * A whole number of minutes between MIN_MINUTES_BEFORE_SHIFT and
+   * MAX_MINUTES_BEFORE_SHIFT. Numeric strings are accepted (a form may post
+   * one); missing, fractional, negative or out-of-range values are a 400.
+   */
+  public static validateMinutesBeforeShift(value: unknown): number {
+    const parsed: number =
+      typeof value === "string" && value.trim() !== ""
+        ? Number(value)
+        : (value as number);
+
+    if (
+      typeof parsed !== "number" ||
+      !Number.isInteger(parsed) ||
+      parsed < MIN_MINUTES_BEFORE_SHIFT ||
+      parsed > MAX_MINUTES_BEFORE_SHIFT
+    ) {
+      throw new BadDataException(
+        `Reminder lead time must be a whole number of minutes between ${MIN_MINUTES_BEFORE_SHIFT} and ${MAX_MINUTES_BEFORE_SHIFT} (two weeks).`,
+      );
+    }
+
+    return parsed;
+  }
+}
+
+export default new Service();

package/Server/Utils/OnCall/CalendarFeedToken.ts

@@ -0,0 +1,241 @@
+import crypto from "crypto";
+import OneUptimeDate from "../../../Types/Date";
+import { PREVIOUS_TOKEN_GRACE_DAYS } from "../../../Types/OnCallDutyPolicy/CalendarFeedWindow";
+
+/*
+ * The capability token that addresses an on-call calendar feed.
+ *
+ * A calendar client keeps the feed URL forever and re-fetches it unattended,
+ * so the token has to be both unguessable and cheap to look up: 256 bits from
+ * the CSPRNG, carried in the URL as base64url (43 characters, no padding), and
+ * stored ONLY as its unkeyed SHA-256 hex digest. The digest is what the public
+ * route queries by, which keeps the plaintext out of the indexed column; a
+ * database dump therefore yields hashes, not working feed URLs.
+ *
+ * Unkeyed on purpose: a keyed hash (HMAC over EncryptionSecret, the backup-code
+ * recipe) would tie every feed to the instance secret, and rotating that secret
+ * would silently break every subscribed calendar in the world with no way to
+ * tell the user. The token already carries 256 bits of entropy, so a rainbow
+ * table buys nothing and the key adds no strength worth that failure mode.
+ *
+ * The hint is the last four characters - enough for the settings page to say
+ * "link ending in …k3Qx" so a user can tell two links apart, far too little to
+ * recover anything.
+ */
+
+// crypto.randomBytes(32) -> 32 bytes -> ceil(32 * 8 / 6) = 43 base64url chars.
+const TOKEN_BYTE_LENGTH: number = 32;
+
+export const CALENDAR_FEED_TOKEN_LENGTH: number = 43;
+
+export const CALENDAR_FEED_TOKEN_HINT_LENGTH: number = 4;
+
+/*
+ * Shape guard for the public route. Anything that does not match is answered
+ * 404 before any database work, so a scanner probing the path costs one regex.
+ */
+export const CALENDAR_FEED_TOKEN_REGEX: RegExp = /^[A-Za-z0-9_-]{43}$/;
+
+export interface MintedCalendarFeedToken {
+  /** The plaintext token. Goes into the URL and, encrypted, into `token`. */
+  token: string;
+  /** Unkeyed SHA-256 hex digest of the token. The indexed lookup column. */
+  tokenHash: string;
+  /** Last four characters of the token, for display only. */
+  tokenHint: string;
+}
+
+/*
+ * Everything a feed row's token columns hold after a rotation: the new
+ * token set, when it was minted, and the rotated-out hash with the instant
+ * it stops being honoured. `previousTokenHash` is null when there was no
+ * token before (a first mint), so a fresh feed never carries a grace entry.
+ */
+export interface CalendarFeedRotation extends MintedCalendarFeedToken {
+  rotatedAt: Date;
+  previousTokenHash: string | null;
+  previousTokenExpiresAt: Date | null;
+}
+
+/*
+ * The token columns every feed model carries (UserOnCallCalendarFeed,
+ * OnCallDutyPolicyScheduleCalendarFeed, ProjectOnCallCalendarFeed). Typed
+ * structurally so the three services share one rule without a common base.
+ */
+export interface CalendarFeedTokenColumns {
+  token?: string | undefined;
+  tokenHash?: string | undefined;
+  tokenHint?: string | undefined;
+  rotatedAt?: Date | undefined;
+  previousTokenHash?: string | undefined;
+  previousTokenExpiresAt?: Date | undefined;
+}
+
+export interface CalendarFeedRotationUpdateData {
+  token: string;
+  tokenHash: string;
+  tokenHint: string;
+  rotatedAt: Date;
+  previousTokenHash: string;
+  previousTokenExpiresAt: Date;
+}
+
+export default class CalendarFeedToken {
+  /**
+   * A fresh 43-character base64url token from 32 CSPRNG bytes.
+   */
+  public static mint(): string {
+    return crypto.randomBytes(TOKEN_BYTE_LENGTH).toString("base64url");
+  }
+
+  /**
+   * Unkeyed SHA-256 of the token, lowercase hex (64 characters). This is the
+   * value stored in `tokenHash` / `previousTokenHash` and the value the public
+   * route looks up by. Deterministic: the same token always hashes the same.
+   */
+  public static hash(token: string): string {
+    return crypto.createHash("sha256").update(token, "utf8").digest("hex");
+  }
+
+  /**
+   * The display hint - the last four characters of the token. Never enough to
+   * reconstruct the token; enough to tell "…k3Qx" from "…Q9zA" in the UI.
+   */
+  public static hint(token: string): string {
+    return token.slice(-CALENDAR_FEED_TOKEN_HINT_LENGTH);
+  }
+
+  /**
+   * True when the string has exactly the shape a minted token has. Used as
+   * the shape guard on the public route so a malformed path never reaches the
+   * database.
+   */
+  public static isValidShape(token: unknown): token is string {
+    return typeof token === "string" && CALENDAR_FEED_TOKEN_REGEX.test(token);
+  }
+
+  /**
+   * Everything a feed row needs when a token is minted or rotated.
+   */
+  public static mintSet(): MintedCalendarFeedToken {
+    const token: string = CalendarFeedToken.mint();
+
+    return {
+      token: token,
+      tokenHash: CalendarFeedToken.hash(token),
+      tokenHint: CalendarFeedToken.hint(token),
+    };
+  }
+
+  /**
+   * The token columns a feed row should hold after minting or rotating.
+   *
+   * The hash the row held before (if any) moves to `previousTokenHash` and
+   * keeps serving an EMPTY calendar until `previousTokenExpiresAt`
+   * (PREVIOUS_TOKEN_GRACE_DAYS from now), so a still-subscribed client clears
+   * its copy instead of showing "could not fetch" until the user notices.
+   */
+  public static buildRotation(data: {
+    currentTokenHash: string | null | undefined;
+    now?: Date | undefined;
+  }): CalendarFeedRotation {
+    const now: Date = data.now || OneUptimeDate.getCurrentDate();
+    const minted: MintedCalendarFeedToken = CalendarFeedToken.mintSet();
+
+    const previousTokenHash: string | null = data.currentTokenHash || null;
+
+    return {
+      ...minted,
+      rotatedAt: now,
+      previousTokenHash: previousTokenHash,
+      previousTokenExpiresAt: previousTokenHash
+        ? OneUptimeDate.addRemoveDays(now, PREVIOUS_TOKEN_GRACE_DAYS)
+        : null,
+    };
+  }
+
+  /**
+   * Populate the token columns of a row about to be INSERTED.
+   *
+   * With `trustSuppliedToken`, a well-formed plaintext token already on the
+   * row (the calendar API mints one up front so it can build the URL in the
+   * same response) is kept and the hash and hint are DERIVED from it. Without
+   * it - every non-root create - whatever the request carried is discarded
+   * and a fresh token is minted. Either way a malformed token or a
+   * caller-chosen hash is replaced: there is no path to a row whose hash
+   * disagrees with its token, and no path for a request body to choose the
+   * secret. A brand-new row never carries a grace-period hash.
+   */
+  public static applyTokenColumnsOnCreate(
+    data: CalendarFeedTokenColumns,
+    options: { trustSuppliedToken: boolean },
+  ): MintedCalendarFeedToken {
+    let minted: MintedCalendarFeedToken;
+
+    if (
+      options.trustSuppliedToken &&
+      CalendarFeedToken.isValidShape(data.token)
+    ) {
+      minted = {
+        token: data.token,
+        tokenHash: CalendarFeedToken.hash(data.token),
+        tokenHint: CalendarFeedToken.hint(data.token),
+      };
+    } else {
+      minted = CalendarFeedToken.mintSet();
+    }
+
+    data.token = minted.token;
+    data.tokenHash = minted.tokenHash;
+    data.tokenHint = minted.tokenHint;
+    data.rotatedAt = OneUptimeDate.getCurrentDate();
+    data.previousTokenHash = undefined;
+    data.previousTokenExpiresAt = undefined;
+
+    return minted;
+  }
+
+  /**
+   * The partial row a rotation writes. `previousTokenHash` /
+   * `previousTokenExpiresAt` are null on a first mint, which the update path
+   * has to be able to write; the model types them as optional strings/dates,
+   * hence the cast at this one boundary.
+   */
+  public static toRotationUpdateData(
+    rotation: CalendarFeedRotation,
+  ): CalendarFeedRotationUpdateData {
+    return {
+      token: rotation.token,
+      tokenHash: rotation.tokenHash,
+      tokenHint: rotation.tokenHint,
+      rotatedAt: rotation.rotatedAt,
+      previousTokenHash: rotation.previousTokenHash as unknown as string,
+      previousTokenExpiresAt:
+        rotation.previousTokenExpiresAt as unknown as Date,
+    };
+  }
+
+  /**
+   * Constant-time comparison of two hashes, for callers that compare a
+   * freshly computed digest against a stored one in memory rather than in a
+   * WHERE clause. Length mismatch is answered false without leaking timing on
+   * the content.
+   */
+  public static isHashEqual(a: string, b: string): boolean {
+    /*
+     * Plain Uint8Arrays rather than Buffers: the two are interchangeable at
+     * runtime, but the App build's @types/node rejects Buffer where an
+     * ArrayBufferView is expected (the same mismatch PasswordHash and
+     * TwoFactorBackupCode trip over), and TextEncoder is global on every
+     * supported Node.
+     */
+    const bytesA: Uint8Array = new TextEncoder().encode(a);
+    const bytesB: Uint8Array = new TextEncoder().encode(b);
+
+    if (bytesA.length !== bytesB.length) {
+      return false;
+    }
+
+    return crypto.timingSafeEqual(bytesA, bytesB);
+  }
+}