@oneuptime/common 12.0.33 → 13.0.0

package/Server/Services/UserNotificationRuleService.ts

@@ -982,6 +982,16 @@ export class Service extends DatabaseService<Model> {
           rootCause: true,
           incidentNumber: true,
           incidentNumberWithPrefix: true,
+          /*
+           * AcknowledgeIncident.hbs asks for a Resources Affected row and
+           * the generator had nothing to build it from, so the row was
+           * silently dropped — the same `{{#if}}` swallow that hid the
+           * alert's Root Cause.
+           */
+          monitors: {
+            _id: true,
+            name: true,
+          },
         },
       });
     }
@@ -1012,6 +1022,20 @@ export class Service extends DatabaseService<Model> {
           },
           alertNumber: true,
           alertNumberWithPrefix: true,
+          /*
+           * AcknowledgeAlert.hbs has always asked for a Root Cause row, but
+           * this select never loaded the column and the template's
+           * `{{#if text}}` guard silently dropped the row — so the one
+           * person being woken up for the alert was the only one who could
+           * not see why it fired. The other three on-call templates already
+           * select it.
+           */
+          rootCause: true,
+          // Same story for the template's Resources Affected row.
+          monitor: {
+            _id: true,
+            name: true,
+          },
         },
       });
     }
@@ -4589,6 +4613,11 @@ export class Service extends DatabaseService<Model> {
         MarkdownContentType.Email,
       ),
       alertSeverity: alert.alertSeverity!.name!,
+      resourcesAffected: alert.monitor?.name || "No resources identified",
+      rootCause: await Markdown.convertToHTML(
+        alert.rootCause || "No root cause identified for this alert",
+        MarkdownContentType.Email,
+      ),
       alertViewLink: (
         await AlertService.getAlertLinkInDashboard(alert.projectId!, alert.id!)
       ).toString(),
@@ -4634,8 +4663,19 @@ export class Service extends DatabaseService<Model> {
         MarkdownContentType.Email,
       ),
       incidentSeverity: incident.incidentSeverity!.name!,
-      rootCause:
+      resourcesAffected:
+        (incident.monitors || [])
+          .map((monitor: Monitor): string => {
+            return monitor.name || "";
+          })
+          .filter((name: string): boolean => {
+            return name.length > 0;
+          })
+          .join(", ") || "No resources identified",
+      rootCause: await Markdown.convertToHTML(
         incident.rootCause || "No root cause identified for this incident",
+        MarkdownContentType.Email,
+      ),
       incidentViewLink: (
         await IncidentService.getIncidentLinkInDashboard(
           incident.projectId!,
@@ -4738,7 +4778,9 @@ export class Service extends DatabaseService<Model> {
     if (alerts.length > 0) {
       const alertRows: string[] = [];
       for (const alert of alerts) {
-        const alertTitle: string = alert.title || "Untitled Alert";
+        const alertTitle: string = Markdown.escapeHtml(
+          alert.title || "Untitled Alert",
+        );
         const alertNumber: string =
           alert.alertNumberWithPrefix ||
           (alert.alertNumber ? `#${alert.alertNumber}` : "");
@@ -4748,20 +4790,22 @@ export class Service extends DatabaseService<Model> {
             alert.id!,
           )
         ).toString();
-        const monitorName: string = alert.monitor?.name || "";
+        const monitorName: string = Markdown.escapeHtml(
+          alert.monitor?.name || "",
+        );
 
         alertRows.push(`
             <tr>
-              <td style="padding: 12px 16px; border-bottom: 1px solid #e2e8f0;">
-                <table cellpadding="0" cellspacing="0" width="100%">
+              <td style="padding: 16px 20px; border-bottom: 1px solid #e2e8f0; overflow-wrap: anywhere; word-break: break-word;">
+                <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed;">
                   <tr>
                     <td style="vertical-align: middle;">
-                      <span style="display: inline-block; background-color: #dbeafe; color: #1e40af; font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 4px; margin-right: 8px;">${alertNumber}</span>
-                      <a href="${alertLink}" style="color: #2563eb; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 14px; font-weight: 500; text-decoration: none;">${alertTitle}</a>
-                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 12px; margin-top: 4px;">Monitor: ${monitorName}</span>` : ""}
+                      <span style="display: inline-block; background-color: #f1f5f9; color: #111111; font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 4px; margin-right: 8px;">${alertNumber}</span>
+                      <a href="${alertLink}" style="color: #111111; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 15px; line-height: 24px; font-weight: 600; text-decoration: underline; text-underline-offset: 3px;">${alertTitle}</a>
+                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 13px; line-height: 20px; margin-top: 6px;">Monitor: ${monitorName}</span>` : ""}
                     </td>
-                    <td style="text-align: right; vertical-align: middle;">
-                      <a href="${alertLink}" style="color: #2563eb; font-size: 12px; text-decoration: none;">View →</a>
+                    <td width="52" style="text-align: right; vertical-align: middle; padding-left: 8px;">
+                      <a href="${alertLink}" style="color: #111111; font-size: 13px; line-height: 20px; text-decoration: underline;">View →</a>
                     </td>
                   </tr>
                 </table>
@@ -4771,7 +4815,7 @@ export class Service extends DatabaseService<Model> {
       }
       if (alertRows.length > 0) {
         alertsListHtml = `
-          <table cellpadding="0" cellspacing="0" width="100%" style="background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%); border-radius: 8px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0;">
+          <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed; background-color: #f8fafc; border-radius: 12px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;">
             <tbody>
               ${alertRows.join("")}
             </tbody>
@@ -4795,9 +4839,11 @@ export class Service extends DatabaseService<Model> {
       ),
       alertEpisodeSeverity: alertEpisode.alertSeverity!.name!,
       resourcesAffected: resourcesAffected,
-      rootCause:
+      rootCause: await Markdown.convertToHTML(
         alertEpisode.rootCause ||
-        "No root cause identified for this alert episode",
+          "No root cause identified for this alert episode",
+        MarkdownContentType.Email,
+      ),
       alertsList: alertsListHtml,
       alertsCount: alerts.length.toString(),
       alertEpisodeViewLink: (
@@ -4908,7 +4954,9 @@ export class Service extends DatabaseService<Model> {
     if (incidents.length > 0) {
       const incidentRows: string[] = [];
       for (const incident of incidents) {
-        const incidentTitle: string = incident.title || "Untitled Incident";
+        const incidentTitle: string = Markdown.escapeHtml(
+          incident.title || "Untitled Incident",
+        );
         const incidentNumber: string =
           incident.incidentNumberWithPrefix ||
           (incident.incidentNumber ? `#${incident.incidentNumber}` : "");
@@ -4918,7 +4966,7 @@ export class Service extends DatabaseService<Model> {
             incident.id!,
           )
         ).toString();
-        const monitorName: string =
+        const monitorName: string = Markdown.escapeHtml(
           (incident.monitors || [])
             .map((monitor: Monitor): string => {
               return monitor.name || "";
@@ -4926,20 +4974,21 @@ export class Service extends DatabaseService<Model> {
             .filter((name: string): boolean => {
               return name.length > 0;
             })
-            .join(", ") || "";
+            .join(", ") || "",
+        );
 
         incidentRows.push(`
             <tr>
-              <td style="padding: 12px 16px; border-bottom: 1px solid #e2e8f0;">
-                <table cellpadding="0" cellspacing="0" width="100%">
+              <td style="padding: 16px 20px; border-bottom: 1px solid #e2e8f0; overflow-wrap: anywhere; word-break: break-word;">
+                <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed;">
                   <tr>
                     <td style="vertical-align: middle;">
                       <span style="display: inline-block; background-color: #fee2e2; color: #991b1b; font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 4px; margin-right: 8px;">${incidentNumber}</span>
-                      <a href="${incidentLink}" style="color: #2563eb; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 14px; font-weight: 500; text-decoration: none;">${incidentTitle}</a>
-                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 12px; margin-top: 4px;">Monitor: ${monitorName}</span>` : ""}
+                      <a href="${incidentLink}" style="color: #111111; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 15px; line-height: 24px; font-weight: 600; text-decoration: underline; text-underline-offset: 3px;">${incidentTitle}</a>
+                      ${monitorName ? `<span style="display: block; color: #64748b; font-size: 13px; line-height: 20px; margin-top: 6px;">Monitor: ${monitorName}</span>` : ""}
                     </td>
-                    <td style="text-align: right; vertical-align: middle;">
-                      <a href="${incidentLink}" style="color: #2563eb; font-size: 12px; text-decoration: none;">View →</a>
+                    <td width="52" style="text-align: right; vertical-align: middle; padding-left: 8px;">
+                      <a href="${incidentLink}" style="color: #111111; font-size: 13px; line-height: 20px; text-decoration: underline;">View →</a>
                     </td>
                   </tr>
                 </table>
@@ -4949,7 +4998,7 @@ export class Service extends DatabaseService<Model> {
       }
       if (incidentRows.length > 0) {
         incidentsListHtml = `
-          <table cellpadding="0" cellspacing="0" width="100%" style="background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%); border-radius: 8px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0;">
+          <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="width: 100%; table-layout: fixed; background-color: #f8fafc; border-radius: 12px; border: 1px solid #e2e8f0; margin: 8px 0 16px 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;">
             <tbody>
               ${incidentRows.join("")}
             </tbody>
@@ -4975,9 +5024,11 @@ export class Service extends DatabaseService<Model> {
       ),
       incidentEpisodeSeverity: incidentEpisode.incidentSeverity!.name!,
       resourcesAffected: resourcesAffected,
-      rootCause:
+      rootCause: await Markdown.convertToHTML(
         incidentEpisode.rootCause ||
-        "No root cause identified for this incident episode",
+          "No root cause identified for this incident episode",
+        MarkdownContentType.Email,
+      ),
       incidentsList: incidentsListHtml,
       incidentsCount: incidents.length.toString(),
       incidentEpisodeViewLink: (

package/Server/Services/UserNotificationSettingService.ts

@@ -53,6 +53,8 @@ import {
 import EmailRollupWriter from "../Utils/EmailRollup/EmailRollupWriter";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
 import { appendRecipientToWhatsAppMessage } from "../Utils/WhatsAppTemplateUtil";
+import DatabaseConfig from "../DatabaseConfig";
+import URL from "../../Types/API/URL";
 
 export class Service extends DatabaseService<UserNotificationSetting> {
   public constructor() {
@@ -149,18 +151,44 @@ export class Service extends DatabaseService<UserNotificationSetting> {
           },
         });
 
+        const emailEnvelope: EmailEnvelope = {
+          ...data.emailEnvelope,
+          vars: { ...data.emailEnvelope.vars },
+        };
+
+        if (userEmails.length > 0) {
+          try {
+            const dashboardUrl: URL = await DatabaseConfig.getDashboardUrl();
+            /*
+             * Keep this out of the producer's envelope and the other channels.
+             * A *Link variable would be mistaken for a resource by the rollup writer.
+             */
+            emailEnvelope.vars["notificationPreferencesUrl"] = URL.fromString(
+              dashboardUrl.toString(),
+            )
+              .addRoute(
+                `/${data.projectId.toString()}/user-settings/notification-settings`,
+              )
+              .toString();
+          } catch (err) {
+            // The footer retains navigation instructions if a URL is unavailable.
+            logger.error(err);
+          }
+        }
+
         for (const userEmail of userEmails) {
           /*
            * The one seam where an owner email can be held back. Below the
-           * burst threshold this is byte-for-byte the send that was here
-           * before - same envelope, same correlation ids, still
-           * fire-and-forget inside the writer - and above it the message is
+           * burst threshold the email is sent immediately with its original
+           * subject, template and correlation ids, plus the preferences URL
+           * above. Delivery is fire-and-forget inside the writer; above the
+           * threshold the message is
            * queued for a rollup instead of dropped. Awaited, unlike the raw
            * send it replaces, because the queue row has to exist before this
            * method returns; the writer itself never awaits MailService.
            *
-           * data.emailEnvelope is passed by reference and is never mutated by
-           * the writer, which the Telegram fallback below and the Slack /
+           * The email-only envelope copy is never mutated by the writer.
+           * The original remains unchanged, which the Telegram fallback and Slack /
            * Microsoft Teams bodies further down depend on: all three
            * synthesise their message from data.emailEnvelope.subject.
            *
@@ -177,7 +205,7 @@ export class Service extends DatabaseService<UserNotificationSetting> {
               userId: data.userId,
               toEmail: userEmail.email!,
               eventType: data.eventType,
-              emailEnvelope: data.emailEnvelope,
+              emailEnvelope: emailEnvelope,
               mailOptions: {
                 projectId: data.projectId,
                 incidentId: data.incidentId,

package/Server/Services/UserTelegramService.ts

@@ -4,6 +4,7 @@ import DeleteBy from "../Types/Database/DeleteBy";
 import { OnCreate, OnDelete } from "../Types/Database/Hooks";
 import DatabaseService from "./DatabaseService";
 import ProjectService from "./ProjectService";
+import TeamMemberService from "./TeamMemberService";
 import UserNotificationRuleService, {
   NotificationDeletionImpact,
   NotificationMethodChannel,
@@ -11,10 +12,29 @@ import UserNotificationRuleService, {
 import LIMIT_MAX from "../../Types/Database/LimitMax";
 import BadDataException from "../../Types/Exception/BadDataException";
 import ObjectID from "../../Types/ObjectID";
-import Text from "../../Types/Text";
+import TooManyRequestsException from "../../Types/Exception/TooManyRequestsException";
 import Project from "../../Models/DatabaseModels/Project";
+import TeamMember from "../../Models/DatabaseModels/TeamMember";
 import Model from "../../Models/DatabaseModels/UserTelegram";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import TelegramVerificationToken from "../Utils/TelegramVerificationToken";
+import {
+  QueryDeepPartialEntity,
+  UpdateQueryBuilder,
+  UpdateResult,
+} from "typeorm";
+
+export enum TelegramVerificationOutcome {
+  Verified = "verified",
+  Invalid = "invalid",
+  Expired = "expired",
+  AlreadyClaimed = "already-claimed",
+}
+
+export interface TelegramVerificationResult {
+  outcome: TelegramVerificationOutcome;
+  item?: Model | undefined;
+}
 
 export class Service extends DatabaseService<Model> {
   public constructor() {
@@ -90,6 +110,59 @@ export class Service extends DatabaseService<Model> {
       throw new BadDataException("telegramChatId cannot be set directly");
     }
 
+    /*
+     * DatabaseService stamps props.tenantId only AFTER this hook. Until then,
+     * both projectId and project are request data. Policy checks performed
+     * against either request value would therefore be a confused-deputy bug:
+     * the caller could pass an enabled/funded project here, pass this hook, and
+     * have DatabaseService persist the row under a different authenticated
+     * tenant afterwards.
+     *
+     * Canonicalize both spellings to the authenticated request tenant before
+     * any lookup. Root jobs have no request tenant, so they retain the existing
+     * internal-call behaviour and use the project explicitly carried by data.
+     */
+    const suppliedProjectId: ObjectID | undefined = createBy.data.projectId;
+    const relationProjectId: ObjectID | null | undefined =
+      createBy.data.project?.id ||
+      (createBy.data.project?._id
+        ? new ObjectID(createBy.data.project._id)
+        : undefined);
+    const requestTenantId: ObjectID | undefined = createBy.props.tenantId;
+
+    if (!createBy.props.isRoot && !requestTenantId) {
+      throw new BadDataException("Project ID is required");
+    }
+
+    const authoritativeProjectId: ObjectID | undefined = createBy.props.isRoot
+      ? suppliedProjectId
+      : requestTenantId;
+
+    if (!authoritativeProjectId) {
+      throw new BadDataException("Project ID is required");
+    }
+
+    if (
+      suppliedProjectId &&
+      !suppliedProjectId.equals(authoritativeProjectId)
+    ) {
+      throw new BadDataException("Project ID does not match request tenant");
+    }
+
+    if (
+      relationProjectId &&
+      !relationProjectId.equals(authoritativeProjectId)
+    ) {
+      throw new BadDataException(
+        createBy.props.isRoot
+          ? "Project relation does not match projectId"
+          : "Project relation does not match request tenant",
+      );
+    }
+
+    createBy.data.projectId = authoritativeProjectId;
+    delete createBy.data.project;
+
     const project: Project | null = await ProjectService.findOneById({
       id: createBy.data.projectId!,
       props: {
@@ -120,6 +193,13 @@ export class Service extends DatabaseService<Model> {
       );
     }
 
+    /*
+     * Never accept a caller-selected bearer token. This hook runs before the
+     * required-field and permission checks, so every ordinary create gets a
+     * server-minted 256-bit capability and no API input can choose it.
+     */
+    createBy.data.verificationCode = TelegramVerificationToken.mint();
+
     return {
       createBy,
       carryForward: null,
@@ -127,7 +207,7 @@ export class Service extends DatabaseService<Model> {
   }
 
   @CaptureSpan()
-  public async regenerateVerificationCode(itemId: ObjectID): Promise<void> {
+  public async regenerateVerificationCode(itemId: ObjectID): Promise<string> {
     const item: Model | null = await this.findOneById({
       id: itemId,
       props: {
@@ -135,6 +215,9 @@ export class Service extends DatabaseService<Model> {
       },
       select: {
         isVerified: true,
+        verificationCode: true,
+        projectId: true,
+        userId: true,
       },
     });
 
@@ -148,15 +231,253 @@ export class Service extends DatabaseService<Model> {
       throw new BadDataException("Telegram account already verified");
     }
 
-    await this.updateOneById({
+    if (
+      !item.projectId ||
+      !item.userId ||
+      !(await this.hasActiveProjectMembership({
+        projectId: item.projectId,
+        userId: item.userId,
+      }))
+    ) {
+      throw new BadDataException("Item not found");
+    }
+
+    const retryAfterSeconds: number =
+      TelegramVerificationToken.getResendRetryAfterSeconds({
+        token: item.verificationCode,
+      });
+
+    if (
+      !TelegramVerificationToken.isExpired({
+        token: item.verificationCode,
+      }) &&
+      retryAfterSeconds > 0
+    ) {
+      throw new TooManyRequestsException(
+        `Please wait ${retryAfterSeconds} seconds before rotating the Telegram verification code.`,
+      );
+    }
+
+    const verificationCode: string = TelegramVerificationToken.mint();
+
+    await this.updateColumnsByIdWithoutHooks({
+      id: itemId,
+      data: {
+        verificationCode,
+      },
+      expectedData: {
+        isVerified: false,
+        ...(item.verificationCode !== undefined
+          ? { verificationCode: item.verificationCode }
+          : {}),
+      },
+    });
+
+    const updatedItem: Model | null = await this.findOneById({
+      id: itemId,
+      props: {
+        isRoot: true,
+      },
+      select: {
+        isVerified: true,
+        verificationCode: true,
+      },
+    });
+
+    if (!updatedItem) {
+      throw new BadDataException(
+        "Item with ID " + itemId.toString() + " not found",
+      );
+    }
+
+    if (updatedItem.isVerified) {
+      throw new BadDataException("Telegram account already verified");
+    }
+
+    if (updatedItem.verificationCode !== verificationCode) {
+      throw new TooManyRequestsException(
+        "The Telegram verification code changed in another request. Please refresh and try again.",
+      );
+    }
+
+    return verificationCode;
+  }
+
+  @CaptureSpan()
+  public async getVerificationCode(itemId: ObjectID): Promise<string> {
+    const item: Model | null = await this.findOneById({
       id: itemId,
       props: {
         isRoot: true,
       },
-      data: {
-        verificationCode: Text.generateRandomNumber(6),
+      select: {
+        isVerified: true,
+        verificationCode: true,
+      },
+    });
+
+    if (!item) {
+      throw new BadDataException("Item not found");
+    }
+
+    if (item.isVerified) {
+      return "";
+    }
+
+    if (
+      TelegramVerificationToken.isValidShape(item.verificationCode) &&
+      !TelegramVerificationToken.isExpired({ token: item.verificationCode })
+    ) {
+      return item.verificationCode;
+    }
+
+    /*
+     * Rows created before this fix hold a six-digit value with no timestamp.
+     * Expired rows also arrive here. Rotate both on the owner's next view so
+     * upgrades fail closed without leaving the user stranded.
+     */
+    return this.regenerateVerificationCode(itemId);
+  }
+
+  @CaptureSpan()
+  public async hasActiveProjectMembership(data: {
+    projectId: ObjectID;
+    userId: ObjectID;
+  }): Promise<boolean> {
+    const membership: TeamMember | null = await TeamMemberService.findOneBy({
+      query: {
+        projectId: data.projectId,
+        userId: data.userId,
+        hasAcceptedInvitation: true,
+      },
+      select: {
+        _id: true,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return Boolean(membership);
+  }
+
+  @CaptureSpan()
+  public async claimVerificationCode(data: {
+    verificationCode: string;
+    telegramChatId: string;
+  }): Promise<TelegramVerificationResult> {
+    if (!TelegramVerificationToken.isValidShape(data.verificationCode)) {
+      return { outcome: TelegramVerificationOutcome.Invalid };
+    }
+
+    if (
+      TelegramVerificationToken.isExpired({
+        token: data.verificationCode,
+      })
+    ) {
+      return { outcome: TelegramVerificationOutcome.Expired };
+    }
+
+    const item: Model | null = await this.findOneBy({
+      query: {
+        verificationCode: data.verificationCode,
+        isVerified: false,
+      },
+      select: {
+        _id: true,
+        userId: true,
+        projectId: true,
+      },
+      props: {
+        isRoot: true,
       },
     });
+
+    if (!item?.id || !item.projectId || !item.userId) {
+      return { outcome: TelegramVerificationOutcome.Invalid };
+    }
+
+    if (
+      !(await this.hasActiveProjectMembership({
+        projectId: item.projectId,
+        userId: item.userId,
+      }))
+    ) {
+      return { outcome: TelegramVerificationOutcome.Invalid };
+    }
+
+    /*
+     * Compare-and-set is essential here. Two chats can submit one leaked link
+     * at the same time; only the UPDATE whose expected token and unverified
+     * state still match may bind the row. The winner burns the capability in
+     * the same statement, so replay is impossible.
+     */
+    const queryBuilder: UpdateQueryBuilder<Model> = this.getRepository()
+      .createQueryBuilder()
+      .update(Model)
+      .set({
+        isVerified: true,
+        telegramChatId: data.telegramChatId,
+        verificationCode: TelegramVerificationToken.mintUnusableValue(),
+      } as QueryDeepPartialEntity<Model>)
+      .where('"_id" = :itemId', { itemId: item.id.toString() })
+      .andWhere('"isVerified" = :isVerified', { isVerified: false })
+      .andWhere('"verificationCode" = :verificationCode', {
+        verificationCode: data.verificationCode,
+      })
+      .andWhere(
+        `EXISTS (
+          SELECT 1
+          FROM "TeamMember"
+          WHERE "projectId" = :projectId
+            AND "userId" = :userId
+            AND "hasAcceptedInvitation" = TRUE
+            AND "deletedAt" IS NULL
+          FOR KEY SHARE
+        )`,
+        {
+          projectId: item.projectId.toString(),
+          userId: item.userId.toString(),
+        },
+      );
+
+    const updateResult: UpdateResult = await queryBuilder.execute();
+
+    /*
+     * The affected-row result is the only reliable winner signal. Re-reading
+     * the row cannot distinguish the winner from a simultaneous replay by the
+     * same Telegram chat, because both requests observe the same final chat
+     * id. Only the statement that changed the row may trigger follow-up work.
+     */
+    if (updateResult.affected !== 1) {
+      return { outcome: TelegramVerificationOutcome.AlreadyClaimed };
+    }
+
+    const claimedItem: Model | null = await this.findOneById({
+      id: item.id,
+      props: {
+        isRoot: true,
+      },
+      select: {
+        _id: true,
+        userId: true,
+        projectId: true,
+        isVerified: true,
+        telegramChatId: true,
+      },
+    });
+
+    if (
+      !claimedItem?.isVerified ||
+      claimedItem.telegramChatId !== data.telegramChatId
+    ) {
+      return { outcome: TelegramVerificationOutcome.AlreadyClaimed };
+    }
+
+    return {
+      outcome: TelegramVerificationOutcome.Verified,
+      item: claimedItem,
+    };
   }
 }