@hed-hog/core 0.0.399 → 0.0.401

package/src/message-template/message-template.service.ts

@@ -0,0 +1,149 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Inject, Injectable, Logger, forwardRef } from '@nestjs/common';
+import * as Handlebars from 'handlebars';
+
+import {
+  MessageTemplateDefinition,
+  getMessageTemplateDefinition,
+} from './message-template.registry';
+
+/**
+ * Idioma em que a plataforma escreve para a própria equipe.
+ *
+ * O aviso interno não é mensagem ao cliente: quem lê é quem trabalha aqui, e o
+ * fato gerador pode ter chegado em qualquer idioma. Por isso o corpo sai no
+ * idioma do painel, e não no de quem comprou ou abriu o chamado.
+ */
+export const DEFAULT_MESSAGE_LOCALE = 'pt';
+
+/**
+ * Renderiza o texto das mensagens que saem por canal que não é e-mail.
+ *
+ * O corpo é texto puro com o markdown do WhatsApp, e não HTML: não dá para
+ * reusar o `MailService`, cujo render troca quebra de linha por `<br/>` — o que
+ * no WhatsApp apareceria literal na tela.
+ *
+ * **Nunca devolve nulo para um slug registrado.** Linha ausente, `is_active`
+ * desligado, corpo em branco, sintaxe quebrada ou banco fora do ar caem no texto
+ * canônico do registry. Isso é o que permite ao chamador parar de manter um
+ * construtor de texto em código só como rede: a rede é o `fallback`.
+ */
+@Injectable()
+export class MessageTemplateService {
+  private readonly logger = new Logger(MessageTemplateService.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+  ) {}
+
+  /**
+   * O texto pronto, ou `null` quando o slug não está registrado.
+   *
+   * Nulo aqui é erro de programação (slug digitado errado, library não
+   * carregada), não configuração — daí ser o único caso.
+   */
+  async render(
+    slug: string,
+    variables: Record<string, unknown>,
+    locale = DEFAULT_MESSAGE_LOCALE,
+  ): Promise<string | null> {
+    const definition = getMessageTemplateDefinition(slug);
+
+    if (!definition) {
+      this.logger.error(
+        `Modelo de mensagem "${slug}" não está registrado; nada a renderizar.`,
+      );
+      return null;
+    }
+
+    const edited = await this.readEditedBody(slug, locale);
+
+    if (edited) {
+      const rendered = MessageTemplateService.compile(edited, variables);
+      if (rendered) return rendered;
+
+      // Texto editado que não compila ou renderiza vazio não pode calar o aviso.
+      this.logger.warn(
+        `O texto editado do modelo "${slug}" não pôde ser usado; caindo no padrão.`,
+      );
+    }
+
+    return MessageTemplateService.renderFallback(definition, variables, locale);
+  }
+
+  /**
+   * Renderiza o texto canônico do registry.
+   *
+   * Estático e público porque o teste que varre o registry inteiro o usa para
+   * afirmar que todo modelo registrado compila com as suas amostras — é ele que
+   * substitui a manutenção do texto em dois lugares.
+   */
+  static renderFallback(
+    definition: MessageTemplateDefinition,
+    variables: Record<string, unknown>,
+    locale = DEFAULT_MESSAGE_LOCALE,
+  ): string | null {
+    const body =
+      definition.fallback[locale] ?? definition.fallback[DEFAULT_MESSAGE_LOCALE];
+
+    return body ? MessageTemplateService.compile(body, variables) : null;
+  }
+
+  /**
+   * Compila e renderiza, ou `null` em qualquer desfecho ruim.
+   *
+   * `noEscape` de propósito: escapar encheria o WhatsApp de `&#x27;`. Template
+   * preenchido só com blocos que não casaram renderiza vazio, e mandar mensagem
+   * em branco para o grupo é pior que mandar o texto padrão.
+   */
+  private static compile(
+    body: string,
+    variables: Record<string, unknown>,
+  ): string | null {
+    try {
+      const rendered = Handlebars.compile(body, { noEscape: true })(variables).trim();
+      return rendered || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * O corpo editado no painel, ou `null` quando não há nada utilizável.
+   *
+   * Sem linha no idioma pedido, usa a primeira que existir: um texto escrito só
+   * em português continua valendo para quem abriu o painel em inglês — o
+   * contrário seria a equipe receber o padrão por causa do idioma da sessão.
+   */
+  private async readEditedBody(
+    slug: string,
+    locale: string,
+  ): Promise<string | null> {
+    try {
+      const template = await (this.prisma as any).message_template.findUnique({
+        where: { slug },
+        select: {
+          is_active: true,
+          message_template_locale: {
+            select: { body: true, locale: { select: { code: true } } },
+          },
+        },
+      });
+
+      if (!template?.is_active) return null;
+
+      const rows = template.message_template_locale ?? [];
+      const match = rows.find((row: any) => row.locale?.code === locale) ?? rows[0];
+
+      return String(match?.body ?? '').trim() || null;
+    } catch (error) {
+      this.logger.warn(
+        `Não foi possível ler o modelo "${slug}": ${
+          (error as Error)?.message ?? 'erro desconhecido'
+        }`,
+      );
+      return null;
+    }
+  }
+}

package/src/notification/notification.constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Nome do evento de notificação no WebSocket (`/realtime`).
+ *
+ * Segue a convenção `dominio:evento` dos outros produtores (`presence:update`,
+ * `lms:waiting-room:tick`). O payload é o mesmo `NotificationStreamEvent` que o
+ * SSE já entrega — os dois transportes convivem por tempo indeterminado (o
+ * class-app publicado nas lojas só fala SSE), e transporte que carrega dado
+ * diferente faz o comportamento do cliente depender de qual dos dois está vivo.
+ */
+export const NOTIFICATION_REALTIME_EVENT = 'notification:event';

package/src/notification/notification.module.ts

@@ -1,6 +1,7 @@
 import { PaginationModule } from '@hed-hog/api-pagination';
 import { PrismaModule } from '@hed-hog/api-prisma';
 import { forwardRef, Module } from '@nestjs/common';
+import { RealtimeModule } from '../realtime/realtime.module';
 import { NotificationController } from './notification.controller';
 import { NotificationService } from './notification.service';
 
@@ -8,6 +9,8 @@ import { NotificationService } from './notification.service';
   imports: [
     forwardRef(() => PrismaModule),
     forwardRef(() => PaginationModule),
+    // O funil de eventos empurra a notificação pelo WebSocket além do SSE.
+    forwardRef(() => RealtimeModule),
   ],
   controllers: [NotificationController],
   providers: [NotificationService],

package/src/notification/notification.service.spec.ts

@@ -4,6 +4,7 @@ import {
   ForbiddenException,
   NotFoundException,
 } from '@nestjs/common';
+import { NOTIFICATION_REALTIME_EVENT } from './notification.constants';
 import { NotificationService } from './notification.service';
 
 const makeDeps = () => {
@@ -22,7 +23,8 @@ const makeDeps = () => {
   };
   const pagination = { paginate: jest.fn().mockResolvedValue({ data: [] }) };
   const eventEmitter = { emitAsync: jest.fn().mockResolvedValue([]) };
-  return { prisma, pagination, eventEmitter };
+  const realtime = { emitToUser: jest.fn() };
+  return { prisma, pagination, eventEmitter, realtime };
 };
 
 const makeService = (deps = makeDeps()) => ({
@@ -30,6 +32,7 @@ const makeService = (deps = makeDeps()) => ({
     deps.prisma as any,
     deps.pagination as any,
     deps.eventEmitter as any,
+    deps.realtime as any,
   ),
   deps,
 });
@@ -240,6 +243,77 @@ describe('NotificationService', () => {
       });
       expect(received).toHaveLength(1);
     });
+
+    // Os dois transportes convivem: o SSE (EventEmitter + pg_notify) ainda
+    // serve o class-app publicado, e o socket serve os apps web. Este teste
+    // trava a coexistência — derrubar um dos três é o jeito mais fácil de
+    // quebrar notificação em produção sem nenhum erro aparecer.
+    it('entrega nos três canais: local, socket e pg_notify', async () => {
+      const { service, deps } = makeService();
+      const received: any[] = [];
+      (service as any).notificationEvents.on('notification:7', (e: any) =>
+        received.push(e),
+      );
+      const event = { type: 'notification.created', notificationId: 3 };
+
+      await (service as any).broadcastNotificationEvent(7, event);
+
+      expect(received).toEqual([event]);
+      expect(deps.realtime.emitToUser).toHaveBeenCalledWith(
+        7,
+        NOTIFICATION_REALTIME_EVENT,
+        event,
+      );
+      expect(deps.prisma.$executeRaw).toHaveBeenCalled();
+    });
+
+    it('emit do socket falhando não impede o pg_notify', async () => {
+      const { service, deps } = makeService();
+      deps.realtime.emitToUser.mockImplementation(() => {
+        throw new Error('socket down');
+      });
+
+      await expect(
+        (service as any).broadcastNotificationEvent(7, {
+          type: 'notification.updated',
+        }),
+      ).resolves.toBeUndefined();
+      expect(deps.prisma.$executeRaw).toHaveBeenCalled();
+    });
+  });
+
+  describe('notifyRewardGranted', () => {
+    it('emite sinal sem payload para o usuário', async () => {
+      const { service } = makeService();
+      const received: any[] = [];
+      (service as any).notificationEvents.on('notification:9', (e: any) =>
+        received.push(e),
+      );
+
+      await service.notifyRewardGranted(9);
+
+      // Só o tipo: a recompensa mora em `lms_student_reward`, e quem ouve refaz
+      // o GET da própria fila. Mandar o conteúdo aqui abriria caminho para
+      // comemorar duas vezes entre a web e o app.
+      expect(received).toEqual([{ type: 'reward.granted' }]);
+    });
+
+    it('atravessa o cluster pelo pg_notify', async () => {
+      const { service, deps } = makeService();
+
+      await service.notifyRewardGranted(9);
+
+      // O desbloqueio acontece no worker de fila, um processo separado de quem
+      // segura a conexão SSE — sem esta publicação o aviso morria no pod errado.
+      expect(deps.prisma.$executeRaw).toHaveBeenCalled();
+    });
+
+    it('não derruba o chamador quando o broadcast falha', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.$executeRaw.mockRejectedValue(new Error('down'));
+
+      await expect(service.notifyRewardGranted(9)).resolves.toBeUndefined();
+    });
   });
 
   describe('handleClusterNotification', () => {

package/src/notification/notification.service.ts

@@ -16,8 +16,10 @@ import type { Request, Response } from 'express';
 import { randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { Client, type Notification as PgNotification } from 'pg';
+import { RealtimeService } from '../realtime/realtime.service';
 import { CreateNotificationDto } from './dto/create-notification.dto';
 import { UpdateProgressDto } from './dto/update-progress.dto';
+import { NOTIFICATION_REALTIME_EVENT } from './notification.constants';
 import {
     NOTIFICATION_STALE_PROGRESS_CHECK,
     NotificationStaleProgressCheckEvent,
@@ -26,7 +28,11 @@ import {
 type NotificationStreamEventType =
   | 'ready'
   | 'notification.created'
-  | 'notification.updated';
+  | 'notification.updated'
+  // Sinal de "acorda e busca", sem relação com a lista de notificações: quem
+  // ouve refaz o GET da própria fila. Anda por aqui porque este é o único
+  // stream que os apps do aluno já mantêm aberto e que alcança todos os pods.
+  | 'reward.granted';
 
 type NotificationStreamEvent = {
   type: NotificationStreamEventType;
@@ -53,6 +59,8 @@ export class NotificationService implements OnModuleInit, OnModuleDestroy {
     @Inject(forwardRef(() => PaginationService))
     private readonly pagination: PaginationService,
     private readonly eventEmitter: EventEmitter2,
+    @Inject(forwardRef(() => RealtimeService))
+    private readonly realtime: RealtimeService,
   ) {
     this.notificationEvents.setMaxListeners(0);
   }
@@ -122,6 +130,19 @@ export class NotificationService implements OnModuleInit, OnModuleDestroy {
     await this.broadcastNotificationEvent(userId, { type: 'notification.updated' });
   }
 
+  /**
+   * Avisa que o usuário ganhou uma recompensa de gamificação, para o cliente
+   * buscar a fila dele.
+   *
+   * Sem payload de propósito: a recompensa mora em `lms_student_reward` com o
+   * `seen_at` como fonte da verdade — mandar o conteúdo aqui abriria caminho
+   * para comemorar duas vezes entre a web e o app, e engordaria o `pg_notify`,
+   * cujo teto de 8000 bytes falha calado (ver `broadcastNotificationEvent`).
+   */
+  async notifyRewardGranted(userId: number) {
+    await this.broadcastNotificationEvent(userId, { type: 'reward.granted' });
+  }
+
   async unreadCount(userId: number) {
     const count = await this.prisma.notification.count({
       where: { user_id: userId, status: 'unread' },
@@ -330,6 +351,23 @@ export class NotificationService implements OnModuleInit, OnModuleDestroy {
   ) {
     this.emitLocalNotificationEvent(userId, event);
 
+    // WebSocket, antes do `pg_notify` abaixo: o emit é síncrono e o
+    // `$executeRaw` é aguardado, então empurrar primeiro tira o socket da
+    // latência do Postgres. Vai por `emitToUser` — a sala `user:{id}` só é
+    // entrada com o `sub` do JWT verificado, e o `subscribe` do gateway monta
+    // salas com o prefixo literal `channel:`, então ela não é assinável de
+    // fora. É o que torna seguro mandar a notificação inteira aqui; por
+    // `emitToChannel` o título e o corpo vazariam para qualquer conta.
+    //
+    // O try/catch existe porque este é o primeiro call-site de `emitToUser` em
+    // produção: um throw derrubaria `create`, `markRead` e o resto do funil, e
+    // a entrega pelo SSE (acima) já aconteceu.
+    try {
+      this.realtime.emitToUser(userId, NOTIFICATION_REALTIME_EVENT, event);
+    } catch (error) {
+      this.logger.warn('Failed to push notification over realtime', error as any);
+    }
+
     const payload: ClusterNotificationPayload = {
       ...event,
       userId,

package/src/oauth/oauth-token-broker.service.spec.ts

@@ -70,6 +70,32 @@ describe('OAuthTokenBrokerService', () => {
     token_expires_at: new Date('2020-01-01T00:00:00Z'),
   });
 
+  /**
+   * O Prisma 6 devolve coluna `Bytes` como `Uint8Array`, não como `Buffer`. Os
+   * mocks daqui usavam `Buffer`, então os testes passavam enquanto produção
+   * falhava em TODA conta: `Uint8Array.toString()` imprime os bytes em decimal
+   * ("115,97,...") em vez de decodificar utf8, o decrypt não achava as 4 partes
+   * e o usuário via "reconecte a conta" — que reconectar não resolvia.
+   */
+  it('decrypts a Bytes column that chega como Uint8Array (Prisma 6)', async () => {
+    const encrypted = deps.security.encrypt('refresh-original');
+    deps.prisma.user_account.findFirst.mockResolvedValue({
+      id: 42,
+      refresh_token: new Uint8Array(Buffer.from(encrypted)),
+      scopes: 'openid,offline_access',
+      token_expires_at: new Date('2020-01-01T00:00:00Z'),
+    } as any);
+    deps.http.post.mockReturnValue(
+      of({ data: { access_token: 'ACCESS-1', expires_in: 3600 } }) as any,
+    );
+
+    const result = await service.getAccessToken(1, PROVIDER);
+
+    expect(result.accessToken).toBe('ACCESS-1');
+    const [, body] = deps.http.post.mock.calls[0] as [string, string, unknown];
+    expect(body).toContain('refresh_token=refresh-original');
+  });
+
   it('decrypts the stored refresh token, exchanges it, and returns an access token', async () => {
     deps.prisma.user_account.findFirst.mockResolvedValue(
       storedRefreshTokenRow(deps.security, 'refresh-original') as any,
@@ -161,6 +187,88 @@ describe('OAuthTokenBrokerService', () => {
     });
   });
 
+  /**
+   * A Microsoft rotaciona o refresh token a cada troca e invalida o anterior.
+   * Com várias réplicas disparando o mesmo tick de cron, a segunda a chegar
+   * recebe `invalid_grant` por uma corrida, não por revogação — e reportar
+   * "reconecte a conta" ali é enganoso: reconectar não resolve, a corrida se
+   * repete no ciclo seguinte.
+   */
+  describe('rotação concorrente', () => {
+    it('refaz a troca com o token que outro processo gravou', async () => {
+      deps.prisma.user_account.findFirst
+        // leitura inicial: o token que vai falhar
+        .mockResolvedValueOnce(
+          storedRefreshTokenRow(deps.security, 'refresh-antigo') as any,
+        )
+        // releitura após o invalid_grant: outro processo já rotacionou
+        .mockResolvedValueOnce(
+          storedRefreshTokenRow(deps.security, 'refresh-novo') as any,
+        )
+        // a retentativa carrega a conta de novo
+        .mockResolvedValueOnce(
+          storedRefreshTokenRow(deps.security, 'refresh-novo') as any,
+        );
+
+      deps.http.post
+        .mockReturnValueOnce(
+          throwError(() => ({
+            response: { data: { error: 'invalid_grant' }, status: 400 },
+          })) as any,
+        )
+        .mockReturnValueOnce(
+          of({ data: { access_token: 'token-bom', expires_in: 3600 } }) as any,
+        );
+
+      const result = await service.getAccessToken(1, PROVIDER);
+
+      expect(result.accessToken).toBe('token-bom');
+      expect(deps.http.post).toHaveBeenCalledTimes(2);
+      // A segunda troca tem que usar o token NOVO, não repetir o que falhou.
+      const segundaChamada = String((deps.http.post.mock.calls[1] as any[])[1]);
+      expect(segundaChamada).toContain('refresh-novo');
+      expect(segundaChamada).not.toContain('refresh-antigo');
+    });
+
+    it('ainda reporta revogação quando o token no banco não mudou', async () => {
+      // Sem essa distinção, uma conta de fato desconectada entraria em laço.
+      deps.prisma.user_account.findFirst.mockResolvedValue(
+        storedRefreshTokenRow(deps.security, 'refresh-original') as any,
+      );
+      deps.http.post.mockReturnValue(
+        throwError(() => ({
+          response: { data: { error: 'invalid_grant' }, status: 400 },
+        })) as any,
+      );
+
+      await expect(service.getAccessToken(1, PROVIDER)).rejects.toMatchObject({
+        reason: 'refresh_revoked',
+      });
+      // Uma tentativa só: não adianta insistir contra revogação real.
+      expect(deps.http.post).toHaveBeenCalledTimes(1);
+    });
+
+    it('não persegue rotações indefinidamente', async () => {
+      // Cada releitura devolve um token diferente, simulando réplicas
+      // rotacionando sem parar. O teto tem que encerrar.
+      let n = 0;
+      deps.prisma.user_account.findFirst.mockImplementation(
+        async () =>
+          storedRefreshTokenRow(deps.security, `refresh-${n++}`) as any,
+      );
+      deps.http.post.mockReturnValue(
+        throwError(() => ({
+          response: { data: { error: 'invalid_grant' }, status: 400 },
+        })) as any,
+      );
+
+      await expect(service.getAccessToken(1, PROVIDER)).rejects.toMatchObject({
+        reason: 'refresh_revoked',
+      });
+      expect(deps.http.post.mock.calls.length).toBeLessThanOrEqual(3);
+    });
+  });
+
   it('parses granted scopes from the stored account', async () => {
     deps.prisma.user_account.findFirst.mockResolvedValue({
       scopes: 'openid, Calendars.Read  offline_access',

package/src/oauth/oauth-token-broker.service.ts

@@ -78,6 +78,16 @@ export class OAuthTokenBrokerService {
   /** Refresh a bit early so an in-flight request never rides an about-to-expire token. */
   private static readonly EXPIRY_SKEW_MS = 60 * 1000;
 
+  /**
+   * Quantas vezes seguir um refresh token que outro processo rotacionou.
+   *
+   * Duas bastam na prática: a corrida acontece quando várias réplicas disparam
+   * o mesmo tick de cron, e a segunda tentativa já parte do token que a
+   * vencedora gravou. O teto existe para o caso patológico de rotações
+   * encadeadas não virar laço.
+   */
+  private static readonly MAX_ROTATION_RETRIES = 2;
+
   constructor(
     private readonly http: HttpService,
     @Inject(forwardRef(() => SettingService))
@@ -169,6 +179,70 @@ export class OAuthTokenBrokerService {
     return { tokenUrl, clientId, clientSecret };
   }
 
+  /**
+   * Lê uma coluna `Bytes` que guarda texto cifrado.
+   *
+   * O Prisma 6 passou a devolver `Bytes` como `Uint8Array`, e não mais como
+   * `Buffer`. Os dois têm `.toString()`, mas com significados opostos: o do
+   * Buffer decodifica os bytes como utf8 ("salt:iv:tag:cifra"), o do
+   * Uint8Array imprime os bytes em decimal separados por vírgula
+   * ("115,97,108,116,..."). O `SecurityService.decrypt` então não achava as 4
+   * partes separadas por ":" e lançava — e como toda conta caía nesse mesmo
+   * erro, a mensagem final era "reconecte a conta", que nenhuma reconexão
+   * resolvia. `Buffer.from` normaliza os dois casos.
+   */
+  private readEncryptedColumn(value: Uint8Array | Buffer): string {
+    return Buffer.from(value).toString();
+  }
+
+  /**
+   * Resumo do erro do provedor para o log. Usa só `error` e `error_description`
+   * — campos que a Microsoft e o Google preenchem com código e explicação
+   * (AADSTS…), nunca com credencial. O corpo inteiro não vai para o log: a
+   * requisição que falhou carrega o client_secret e o refresh token.
+   */
+  private describeGrantError(error: any): string {
+    const data = error?.response?.data;
+    const code = data?.error ?? 'unknown';
+    const description = String(data?.error_description ?? '')
+      .replace(/\s+/g, ' ')
+      .trim();
+    return description ? `${code}: ${description.slice(0, 300)}` : code;
+  }
+
+  /**
+   * Relê o refresh token do banco para ver se outro processo já o rotacionou.
+   *
+   * Devolve `true` só quando o valor guardado é DIFERENTE do que acabou de
+   * falhar — é isso que distingue uma corrida entre réplicas (vale tentar de
+   * novo, agora com o token novo) de uma revogação de verdade (não adianta
+   * insistir). Comparar os valores importa: sem essa checagem, uma conta
+   * realmente desconectada entraria em laço de tentativas.
+   *
+   * Nunca lança: qualquer problema aqui vira "não rotacionou", e quem chamou
+   * segue para o erro original, que é a informação correta a dar ao usuário.
+   */
+  private async reloadRotatedRefreshToken(
+    userId: number,
+    provider: string,
+    usedRefreshToken: string,
+  ): Promise<boolean> {
+    try {
+      const account = await this.prisma.user_account.findFirst({
+        where: { user_id: userId, provider: this.toAccountProvider(provider) },
+        select: { refresh_token: true },
+      });
+      if (!account?.refresh_token) return false;
+
+      const stored = this.security.decrypt(
+        this.readEncryptedColumn(account.refresh_token),
+      );
+      return Boolean(stored) && stored !== usedRefreshToken;
+    } catch {
+      return false;
+    }
+  }
+
   private async loadUserAccount(userId: number, provider: string) {
     const account = await this.prisma.user_account.findFirst({
       where: {
@@ -232,6 +306,13 @@ export class OAuthTokenBrokerService {
   async getAccessToken(
     userId: number,
     provider: string,
+    /**
+     * Profundidade da retentativa após uma rotação concorrente. Existe para a
+     * recursão ter fim: numa corrida entre muitas réplicas, cada uma pode
+     * rotacionar de novo entre a nossa falha e a releitura, e sem teto duas
+     * réplicas azaradas ficariam se revezando indefinidamente.
+     */
+    attempt = 0,
   ): Promise<BrokeredAccessToken> {
     const key = this.cacheKey(userId, provider);
     const cached = this.cache.get(key);
@@ -249,8 +330,23 @@ export class OAuthTokenBrokerService {
 
     let decryptedRefreshToken: string;
     try {
-      decryptedRefreshToken = this.security.decrypt(account.refresh_token.toString());
+      decryptedRefreshToken = this.security.decrypt(
+        this.readEncryptedColumn(account.refresh_token),
+      );
     } catch (error) {
+      // Este caminho e o `invalid_grant` lá embaixo chegam ao usuário com a
+      // MESMA frase ("reconecte a conta"), e as causas não têm nada a ver uma
+      // com a outra: aqui o valor guardado não abre, lá é a Microsoft recusando
+      // o grant. Sem distinguir no log, não há como saber qual dos dois ocorreu.
+      // A mensagem do decrypt separa os dois motivos possíveis daqui — formato
+      // inválido (o valor lido não é o cifrado) e falha de autenticação (chave
+      // diferente da que cifrou) —, e é truncada porque ela ecoa o começo do
+      // valor que tentou decifrar.
+      this.logger.warn(
+        `Stored refresh token could not be decrypted: provider=${provider} userId=${userId} detail=${
+          error instanceof Error ? error.message.split('Value:')[0].trim() : 'unknown'
+        }`,
+      );
       throw new OAuthTokenBrokerError(
         'refresh_revoked',
         `Failed to decrypt stored refresh token for "${provider}".`,
@@ -290,8 +386,39 @@ export class OAuthTokenBrokerService {
     } catch (error: any) {
       const providerError = error?.response?.data?.error;
       if (providerError === 'invalid_grant') {
-        // Refresh token revoked/expired — the user must reconnect.
         this.cache.delete(key);
+
+        // Antes de declarar a conta desconectada, checa se outro processo
+        // rotacionou o token enquanto este fazia a troca.
+        //
+        // A Microsoft emite um refresh token novo a cada troca e invalida o
+        // anterior, então basta duas réplicas usarem o mesmo token ao mesmo
+        // tempo para a segunda levar `invalid_grant` — e este serviço roda em
+        // seis. Sem esta releitura, uma corrida entre réplicas era reportada ao
+        // usuário como "reconecte a conta", e reconectar não resolvia nada,
+        // porque a corrida se repetia no ciclo seguinte.
+        const rotated =
+          attempt < OAuthTokenBrokerService.MAX_ROTATION_RETRIES &&
+          (await this.reloadRotatedRefreshToken(
+            userId,
+            provider,
+            decryptedRefreshToken,
+          ));
+        if (rotated) {
+          this.logger.log(
+            `Refresh token was rotated by another process; retrying: provider=${provider} userId=${userId} attempt=${attempt + 1}`,
+          );
+          return this.getAccessToken(userId, provider, attempt + 1);
+        }
+
+        // Nada mudou no banco: o grant foi mesmo recusado. O `error_description`
+        // do provedor é a única coisa que diz POR QUÊ (na Microsoft, o código
+        // AADSTS: token expirado, consentimento faltando, acesso condicional).
+        // Sem ele no log, "reconecte a conta" é tudo que sobra para diagnosticar
+        // — e reconectar não resolve a maioria desses casos.
+        this.logger.warn(
+          `Refresh grant rejected: provider=${provider} userId=${userId} scopesSent="${scopeParam.join(' ')}" detail=${this.describeGrantError(error)}`,
+        );
         throw new OAuthTokenBrokerError(
           'refresh_revoked',
           `Refresh token for "${provider}" is no longer valid. Reconnect the account.`,

package/src/oauth/oauth.controller.ts

@@ -290,7 +290,6 @@ export class OAuthController {
       state,
       type: 'login',
       redirectUri,
-      includeRefreshTokenInBody: Boolean(redirectUri),
       requestOrigin: origin,
       requestReferer: referer,
     });

package/src/oauth/oauth.errors.ts

@@ -11,6 +11,13 @@ export class OAuthProviderException extends Error {
     public readonly status?: number,
     public readonly providerError?: string,
     public readonly providerErrorCode?: string,
+    /**
+     * Erro original do provider (tipicamente um AxiosError). Declarado como
+     * propriedade em vez de `super(message, { cause })` porque a library compila
+     * com `lib: es2021`, onde `ErrorOptions` ainda não existe — o que importa é a
+     * propriedade em runtime, que é o que o `linkedErrors` do Sentry encadeia.
+     */
+    public readonly cause?: unknown,
   ) {
     super(message);
     this.name = 'OAuthProviderException';

package/src/oauth/oauth.module.ts

@@ -23,7 +23,12 @@ import { MicrosoftProvider } from './providers/microsoft.provider';
 
 @Module({
   imports: [
-    forwardRef(() => HttpModule),
+    // O default do axios é `timeout: 0` — espera indefinidamente. Como a troca do
+    // código roda dentro da transação de 60s do OAuthCallbackCoordinatorService,
+    // uma conexão pendurada com o provider prendia uma conexão do pool até a
+    // transação estourar. 10s é folgado para um endpoint de token e falha como
+    // ECONNABORTED, que o mapProviderError classifica.
+    HttpModule.register({ timeout: 10_000, maxRedirects: 5 }),
     forwardRef(() => PrismaModule),
     forwardRef(() => MailSendModule),
     forwardRef(() => ConfigModule),