@hed-hog/core 0.0.387 → 0.0.393

package/src/oauth/providers/google.provider.ts

@@ -1,12 +1,23 @@
 import { PrismaService } from '@hed-hog/api-prisma';
 import { HttpService } from '@nestjs/axios';
-import { BadRequestException, forwardRef, Inject, Injectable } from '@nestjs/common';
+import { BadRequestException, forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
 import { buildOAuthConfigFromIntegration } from '../../integration-profile/integration-profile.utils';
 import { SettingService } from '../../setting/setting.service';
 import { BaseOAuthProvider } from './abstract.provider';
 
 @Injectable()
 export class GoogleProvider extends BaseOAuthProvider {
+  private readonly logger = new Logger(GoogleProvider.name);
+
+  /**
+   * personFields da People API e o escopo sensível que cada um exige. Escopo sensível
+   * só entra na conta se estiver marcado em `oauth-google-scopes` e aprovado na
+   * verificação do Google; sem ele a People API responde 403.
+   */
+  private static readonly PEOPLE_FIELD_SCOPES: Record<string, string> = {
+    genders: 'https://www.googleapis.com/auth/user.gender.read',
+    birthdays: 'https://www.googleapis.com/auth/user.birthday.read',
+  };
 
   constructor(
     http: HttpService,
@@ -82,6 +93,7 @@ export class GoogleProvider extends BaseOAuthProvider {
 
     const peopleProfile = await this.getGoogleProfileFromAccessToken(
       token.access_token,
+      String(token.scope ?? ''),
     );
 
     return {
@@ -97,22 +109,44 @@ export class GoogleProvider extends BaseOAuthProvider {
     };
   }
 
-  private async getGoogleProfileFromAccessToken(accessToken: string) {
-    const url =
-      'https://people.googleapis.com/v1/people/me?personFields=genders,birthdays';
-
-    const res = await fetch(url, {
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-      },
-    });
-
-    if (!res.ok) {
-      throw new Error(`Google People API error: ${res.statusText}`);
+  private async getGoogleProfileFromAccessToken(
+    accessToken: string,
+    grantedScopes: string,
+  ) {
+    const empty = { gender: null, birthday: null, raw: null };
+    const granted = new Set(grantedScopes.split(/\s+/).filter(Boolean));
+    const personFields = Object.entries(GoogleProvider.PEOPLE_FIELD_SCOPES)
+      .filter(([, scope]) => granted.has(scope))
+      .map(([field]) => field);
+
+    // Login com os escopos básicos (openid/email/profile) não passa pela People API:
+    // ela responderia 403 e derrubaria a autenticação inteira por um dado opcional.
+    if (!personFields.length) return empty;
+
+    const url = `https://people.googleapis.com/v1/people/me?personFields=${personFields.join(',')}`;
+
+    let data: any;
+    try {
+      const res = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+        },
+      });
+
+      if (!res.ok) {
+        throw new Error(`Google People API error: ${res.statusText}`);
+      }
+
+      data = await res.json();
+    } catch (error) {
+      // People API desabilitada no projeto ou consentimento revogado não podem
+      // impedir o usuário de entrar.
+      this.logger.warn(
+        `Google People API indisponível, seguindo sem gênero/aniversário: ${(error as Error).message}`,
+      );
+      return empty;
     }
 
-    const data: any = await res.json();
-
     const gender =
       data.genders?.find((g: any) => g.metadata?.primary)?.value ??
       data.genders?.[0]?.value ??

package/src/observability/monitored-cron.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+
+const withMonitor = jest.fn((_slug: string, callback: () => any) => callback());
+const startSpan = jest.fn((_opts: any, callback: () => any) => callback());
+const captureException = jest.fn();
+const withScope = jest.fn((cb: (scope: any) => void) => {
+  const scope = { setTag: jest.fn() };
+  cb(scope);
+  return scope;
+});
+
+jest.mock('@sentry/nestjs', () => ({ withMonitor, startSpan, captureException, withScope }));
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { runMonitoredCron } = require('./monitored-cron');
+
+function fakePrisma(locked: boolean, overrides: { transactionThrows?: boolean } = {}) {
+  const queryRaw = jest.fn().mockResolvedValue([{ locked }]);
+  const transaction = jest.fn(async (fn: any) => {
+    if (overrides.transactionThrows) throw new Error('transaction aborted');
+    return fn({ $queryRaw: queryRaw });
+  });
+  return { $transaction: transaction, $queryRaw: queryRaw };
+}
+
+describe('runMonitoredCron', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('retorna undefined sem executar work() quando outro pod já ganhou o tick', async () => {
+    const prisma = fakePrisma(false);
+    const work = jest.fn();
+
+    const result = await runMonitoredCron(prisma, { slug: 'meu-cron', schedule: '* * * * *' }, work);
+
+    expect(result).toBeUndefined();
+    expect(work).not.toHaveBeenCalled();
+    expect(withMonitor).not.toHaveBeenCalled();
+  });
+
+  it('executa work() e devolve o resultado quando ganha o tick', async () => {
+    const prisma = fakePrisma(true);
+    const work = jest.fn().mockResolvedValue({ ok: true });
+
+    const result = await runMonitoredCron(prisma, { slug: 'meu-cron', schedule: '* * * * *' }, work);
+
+    expect(work).toHaveBeenCalledTimes(1);
+    expect(withMonitor).toHaveBeenCalledWith(
+      'meu-cron',
+      expect.any(Function),
+      expect.objectContaining({ schedule: { type: 'crontab', value: '* * * * *' }, isolateTrace: true }),
+    );
+    expect(result).toEqual({ ok: true });
+  });
+
+  it('NUNCA relança quando work() falha — captura no Sentry e retorna undefined', async () => {
+    const prisma = fakePrisma(true);
+    const boom = new Error('cron falhou');
+    const work = jest.fn().mockRejectedValue(boom);
+
+    await expect(
+      runMonitoredCron(prisma, { slug: 'meu-cron', schedule: '* * * * *' }, work),
+    ).resolves.toBeUndefined();
+
+    expect(captureException).toHaveBeenCalledWith(
+      boom,
+      expect.objectContaining({ mechanism: { handled: true, type: 'hedhog.cron' } }),
+    );
+  });
+
+  it('dimensiona o timeout/maxWait da transação a partir de maxRuntimeMinutes', async () => {
+    const prisma = fakePrisma(true);
+    const work = jest.fn().mockResolvedValue(undefined);
+
+    await runMonitoredCron(
+      prisma,
+      { slug: 'meu-cron', schedule: '* * * * *', maxRuntimeMinutes: 2 },
+      work,
+    );
+
+    expect(prisma.$transaction).toHaveBeenCalledWith(
+      expect.any(Function),
+      { timeout: 2 * 60_000 + 30_000, maxWait: 20_000 },
+    );
+  });
+
+  it('NUNCA relança quando a transação falha (ex.: pool esgotado) — captura no Sentry e retorna undefined', async () => {
+    const prisma = fakePrisma(true, { transactionThrows: true });
+    const work = jest.fn();
+
+    await expect(
+      runMonitoredCron(prisma, { slug: 'meu-cron', schedule: '* * * * *' }, work),
+    ).resolves.toBeUndefined();
+
+    expect(work).not.toHaveBeenCalled();
+    expect(captureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({ mechanism: { handled: true, type: 'hedhog.cron' } }),
+    );
+  });
+});

package/src/observability/monitored-cron.ts

@@ -0,0 +1,110 @@
+import * as Sentry from '@sentry/nestjs';
+
+export type MonitoredCronOptions = {
+  /** Slug do monitor no Sentry (Crons). */
+  slug: string;
+  /** Idêntico ao valor passado ao @Cron do método chamador. */
+  schedule: string;
+  maxRuntimeMinutes?: number;
+  checkinMarginMinutes?: number;
+};
+
+/** Fallback só para dimensionar o timeout da transação (ver abaixo) quando um
+ * chamador futuro omitir `maxRuntimeMinutes` — os 5 crons atuais sempre informam. */
+const DEFAULT_MAX_RUNTIME_MINUTES = 5;
+
+/** Folga sobre `maxRuntimeMinutes` para o `timeout` da transação: cobre a
+ * diferença entre o que o Sentry tolera (`maxRuntime`/`checkinMargin`, que só
+ * marcam o check-in como perdido) e o que o Prisma de fato aborta. */
+const TRANSACTION_TIMEOUT_SLACK_MS = 30_000;
+
+/** Tempo esperando conexão do pool para abrir a transação — alinhado ao
+ * `pool_timeout=20s` que packages/api-prisma/src/datasource-url.ts já aplica
+ * quando PRISMA_CONNECTION_LIMIT está setado; o default do Prisma (2s) seria
+ * mais apertado que esse teto que o projeto já escolheu deliberadamente. */
+const TRANSACTION_MAX_WAIT_MS = 20_000;
+
+/**
+ * Tenta ganhar o tick. Roda DENTRO da transação de `runMonitoredCron` —
+ * reaproveita o MESMO padrão de `pg_try_advisory_xact_lock` já usado em
+ * cms-scheduled-publisher.service.ts e class-session-reminder.service.ts, mas
+ * aqui generalizado: a variante `xact` só é liberada no commit/rollback DESSA
+ * transação, então segurá-la aberta pelo tempo de `work()` é o que de fato
+ * garante a exclusão mútua entre pods.
+ */
+async function claimCronTick(tx: any, slug: string): Promise<boolean> {
+  const rows: { locked: boolean }[] = await tx.$queryRaw`
+    SELECT pg_try_advisory_xact_lock(hashtext(${slug})) AS locked
+  `;
+  return rows[0]?.locked === true;
+}
+
+/**
+ * Envolve o corpo de um método @Cron com Sentry Cron Monitoring (check-in
+ * in_progress/ok/error), garantindo que só o pod que ganhou o tick executa
+ * `work` e emite o check-in — sem isso, com N pods rodando o mesmo @Cron
+ * simultaneamente, o Sentry recebe 2×N check-ins por execução e estoura o
+ * rate limit de 6/min por monitor (ver docs/sentry.md).
+ *
+ * A eleição e `work()` rodam na MESMA transação interativa — é o que faz o
+ * `pg_try_advisory_xact_lock` valer como exclusão mútua de verdade. Uma
+ * versão anterior comitava a eleição sozinha (fora de transação): o Postgres
+ * liberava o lock no instante em que a query retornava, antes do trabalho
+ * real começar, e pods suficientemente próximos no tempo (o que é comum,
+ * já que o @Cron dispara no mesmo segundo em todos) "ganhavam" o mesmo tick
+ * e mandavam check-ins duplicados — foi o que gerou o incidente do
+ * sac-sla-sweep. `work()` deliberadamente NÃO recebe `tx` (continua fechando
+ * sobre `this.prisma`/outros serviços do chamador): a conexão que segura o
+ * lock fica ociosa (idle in transaction) durante o trabalho real, em vez de
+ * segurar locks de linha por uma chamada HTTP potencialmente longa (ex.:
+ * renovação de assinatura do Graph, até 10 min).
+ *
+ * Quando outro pod já ganhou o tick, resolve para `undefined` sem chamar
+ * `work` — não é uma falha, é a mesma semântica de "outro worker já pegou o
+ * job" que a fila customizada já usa.
+ */
+export async function runMonitoredCron<T>(
+  prisma: any,
+  options: MonitoredCronOptions,
+  work: () => Promise<T>,
+): Promise<T | undefined> {
+  const timeoutMs =
+    (options.maxRuntimeMinutes ?? DEFAULT_MAX_RUNTIME_MINUTES) * 60_000 +
+    TRANSACTION_TIMEOUT_SLACK_MS;
+
+  try {
+    return await prisma.$transaction(
+      async (tx: any) => {
+        if (!(await claimCronTick(tx, options.slug))) return undefined;
+
+        return Sentry.withMonitor(
+          options.slug,
+          () => Sentry.startSpan({ name: options.slug, op: 'cron.hedhog' }, work),
+          {
+            schedule: { type: 'crontab', value: options.schedule },
+            timezone: 'America/Sao_Paulo',
+            ...(options.maxRuntimeMinutes ? { maxRuntime: options.maxRuntimeMinutes } : {}),
+            ...(options.checkinMarginMinutes ? { checkinMargin: options.checkinMarginMinutes } : {}),
+            // Distingue cada execução do cron como um trace próprio, em vez de
+            // herdar/continuar um trace pendurado do ciclo de poll anterior.
+            isolateTrace: true,
+          },
+        );
+      },
+      { timeout: timeoutMs, maxWait: TRANSACTION_MAX_WAIT_MS },
+    );
+  } catch (error) {
+    // withMonitor já registrou o check-in como 'error' antes de relançar (e um
+    // erro de work() também derruba a transação por rollback — inofensivo,
+    // já que nada é escrito via `tx`, só o lock é liberado). O @Cron do
+    // chamador NUNCA deve rejeitar a partir daqui: a lib `cron` por baixo do
+    // @nestjs/schedule não garante tratamento de uma rejeição vinda do
+    // onTick, e o onUnhandledRejectionIntegration({mode:'strict'}) do
+    // instrument.ts derrubaria o processo por um erro que já está capturado.
+    Sentry.withScope((scope) => {
+      scope.setTag('cron', options.slug);
+      Sentry.captureException(error, { mechanism: { handled: true, type: 'hedhog.cron' } });
+    });
+    return undefined;
+  }
+}

package/src/pairing/dto/approve-reverse-pairing.dto.ts

@@ -0,0 +1,20 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/** Direção B: o aparelho autenticado aprova o navegador que pediu. */
+export class ApproveReversePairingDTO {
+  /**
+   * Prova de que quem aprova leu mesmo o QR: a pública efêmera precisa bater com
+   * a guardada. Sem isso, o `id` sequencial permitiria aprovar (ou espiar) o
+   * pareamento de um desconhecido por enumeração.
+   */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  eph_public_key: string;
+
+  /** Blob OPACO cifrado para a pública efêmera acima. */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(8192)
+  payload_enc: string;
+}

package/src/pairing/dto/claim-pairing.dto.ts

@@ -0,0 +1,19 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/**
+ * Direção A: o aparelho que leu o QR reivindica e, depois, resgata.
+ *
+ * Serve aos dois passos porque a prova é a mesma nos dois: a posse do token que
+ * saiu do fragmento do QR. O que muda é só o estado exigido do registro.
+ */
+export class ClaimPairingDTO {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  auth_token: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(100)
+  client_id: string;
+}

package/src/pairing/dto/confirm-pairing.dto.ts

@@ -0,0 +1,14 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/** Direção A: o navegador aprova o aparelho que reivindicou e entrega o blob. */
+export class ConfirmPairingDTO {
+  /**
+   * Blob OPACO: AES-256-GCM feito no navegador com uma chave derivada do
+   * fragmento do QR. O teto de 8 KB existe para a tabela não virar armazenamento
+   * de propósito geral — a carga real tem ~600 caracteres.
+   */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(8192)
+  payload_enc: string;
+}

package/src/pairing/dto/poll-reverse-pairing.dto.ts

@@ -0,0 +1,9 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/** Direção B: o navegador pergunta se já foi aprovado. */
+export class PollReversePairingDTO {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  poll_token: string;
+}

package/src/pairing/dto/start-pairing.dto.ts

@@ -0,0 +1,19 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/** Direção A: o navegador destravado abre o pareamento. */
+export class StartPairingDTO {
+  /**
+   * `sha256(authToken)` em base64url, calculado no cliente. O token cru fica no
+   * fragmento do QR e nunca chega aqui — é o que impede um dump do banco de
+   * reivindicar pareamentos.
+   */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  auth_token_hash: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(100)
+  client_id: string;
+}

package/src/pairing/dto/start-reverse-pairing.dto.ts

@@ -0,0 +1,45 @@
+import {
+  IsBoolean,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  MaxLength,
+} from 'class-validator';
+
+/**
+ * Direção B: o navegador que QUER acesso abre o pareamento.
+ *
+ * Público de propósito: o caso principal é um computador novo, onde ainda não há
+ * sessão nenhuma. O registro criado aqui não vale nada sozinho — só passa a
+ * valer quando um aparelho autenticado o aprova.
+ */
+export class StartReversePairingDTO {
+  /**
+   * `sha256(pollToken)`. O token de poll NÃO entra no QR: só o `id` entra. Assim
+   * quem fotografa a tela não consegue consumir o resultado nem depois de
+   * aprovado.
+   */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  poll_hash: string;
+
+  /** Ponto EC não comprimido (65 bytes) em base64 — a pública efêmera da aba. */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  eph_public_key: string;
+
+  /**
+   * `true` quando o navegador também precisa de sessão (computador novo);
+   * `false` quando já está logado e só o cofre está travado.
+   */
+  @IsBoolean()
+  @IsOptional()
+  want_session?: boolean;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(100)
+  client_id: string;
+}

package/src/pairing/pairing.controller.ts

@@ -0,0 +1,246 @@
+import { NoRole, Public, User } from '@hed-hog/api';
+import { Locale } from '@hed-hog/api-locale';
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Headers,
+  Inject,
+  Ip,
+  Param,
+  Post,
+  Query,
+  Res,
+  UseGuards,
+  forwardRef,
+} from '@nestjs/common';
+import { Throttle, ThrottlerGuard } from '@nestjs/throttler';
+import { TokenService } from '../token/token.service';
+import { ApproveReversePairingDTO } from './dto/approve-reverse-pairing.dto';
+import { ClaimPairingDTO } from './dto/claim-pairing.dto';
+import { ConfirmPairingDTO } from './dto/confirm-pairing.dto';
+import { PollReversePairingDTO } from './dto/poll-reverse-pairing.dto';
+import { StartPairingDTO } from './dto/start-pairing.dto';
+import { StartReversePairingDTO } from './dto/start-reverse-pairing.dto';
+import { PairingService } from './pairing.service';
+
+/**
+ * Pareamento por QR code. Fica em `/auth` ao lado de `/auth/authorize/*` porque
+ * é a mesma família: transferir uma sessão para outro cliente sem manipular
+ * senha.
+ *
+ * Quem chama o quê:
+ * - direção A: o NAVEGADOR abre, acompanha e confirma (rotas autenticadas); o
+ *   CELULAR reivindica e resgata (rotas públicas — ele ainda não tem sessão);
+ * - direção B: o NAVEGADOR abre e faz poll (rotas públicas — pode ser um
+ *   computador onde ninguém está logado); o CELULAR inspeciona e aprova (rotas
+ *   autenticadas).
+ */
+@Controller('auth')
+export class PairingController {
+  constructor(
+    @Inject(forwardRef(() => PairingService))
+    private readonly service: PairingService,
+    @Inject(forwardRef(() => TokenService))
+    private readonly token: TokenService,
+  ) {}
+
+  /* ---------------------------- Direção A ---------------------------- */
+
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 5, ttl: 60000 } })
+  @Post('pairing')
+  async start(
+    @User() { id },
+    @Body() body: StartPairingDTO,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.start({
+      userId: id,
+      authTokenHash: body.auth_token_hash,
+      clientId: body.client_id,
+      ipAddress,
+      userAgent,
+    });
+  }
+
+  /** Poll do navegador enquanto o QR está na tela. Limite alto por isso. */
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 120, ttl: 60000 } })
+  @Get('pairing/:id')
+  async status(@User() { id: userId }, @Param('id') id: string) {
+    return this.service.status(userId, id);
+  }
+
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @Post('pairing/:id/confirm')
+  async confirm(
+    @User() { id: userId },
+    @Param('id') id: string,
+    @Body() body: ConfirmPairingDTO,
+  ) {
+    return this.service.confirm({ userId, id, payloadEnc: body.payload_enc });
+  }
+
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 20, ttl: 60000 } })
+  @Delete('pairing/:id')
+  async cancel(@User() { id: userId }, @Param('id') id: string) {
+    return this.service.cancel(userId, id);
+  }
+
+  /**
+   * Público por definição: quem chama é o aparelho que acabou de ler o QR e
+   * ainda não tem sessão nenhuma. Quem autentica é a posse do token que saiu do
+   * fragmento.
+   */
+  @Public()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @Post('pairing/claim')
+  async claim(
+    @Body() body: ClaimPairingDTO,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.claim({
+      authToken: body.auth_token,
+      clientId: body.client_id,
+      ipAddress,
+      userAgent,
+    });
+  }
+
+  /**
+   * Sem `@Res()` e sem cookie `rt`: quem resgata aqui é um app nativo, para quem
+   * um Set-Cookie é ruído. O refreshToken vai no corpo, como em `/auth/token`.
+   */
+  @Public()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 60, ttl: 60000 } })
+  @Post('pairing/redeem')
+  async redeem(
+    @Body() body: ClaimPairingDTO,
+    @Locale() locale: string,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.redeem({
+      authToken: body.auth_token,
+      clientId: body.client_id,
+      locale,
+      ipAddress,
+      userAgent,
+    });
+  }
+
+  /* ---------------------------- Direção B ---------------------------- */
+
+  @Public()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @Post('pairing/reverse')
+  async startReverse(
+    @Body() body: StartReversePairingDTO,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.startReverse({
+      pollHash: body.poll_hash,
+      ephPublicKey: body.eph_public_key,
+      wantSession: body.want_session ?? true,
+      clientId: body.client_id,
+      ipAddress,
+      userAgent,
+    });
+  }
+
+  /**
+   * O `k` é a pública efêmera lida do QR, e serve de prova de que quem pergunta
+   * esteve na frente da tela. Ela é pública — pode aparecer no log de acesso sem
+   * problema —, e sem ela o `id` sequencial permitiria varrer os pareamentos
+   * alheios.
+   */
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 30, ttl: 60000 } })
+  @Get('pairing/reverse/:id')
+  async reverseRequest(@Param('id') id: string, @Query('k') ephPublicKey: string) {
+    return this.service.getReverseRequest(id, ephPublicKey ?? '');
+  }
+
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @Post('pairing/reverse/:id/approve')
+  async approveReverse(
+    @User() { id: userId },
+    @Param('id') id: string,
+    @Body() body: ApproveReversePairingDTO,
+  ) {
+    return this.service.approveReverse({
+      userId,
+      id,
+      ephPublicKey: body.eph_public_key,
+      payloadEnc: body.payload_enc,
+    });
+  }
+
+  @NoRole()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 20, ttl: 60000 } })
+  @Post('pairing/reverse/:id/reject')
+  async rejectReverse(
+    @User() { id: userId },
+    @Param('id') id: string,
+    @Body() body: { eph_public_key?: string },
+  ) {
+    return this.service.rejectReverse({
+      userId,
+      id,
+      ephPublicKey: body?.eph_public_key ?? '',
+    });
+  }
+
+  /**
+   * Aqui o cookie `rt` FAZ sentido, ao contrário do redeem: quem resgata é um
+   * navegador, e é o mesmo formato de sessão que o login normal entrega.
+   */
+  @Public()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 60, ttl: 60000 } })
+  @Post('pairing/reverse/poll')
+  async pollReverse(
+    @Body() body: PollReversePairingDTO,
+    @Locale() locale: string,
+    @Res({ passthrough: true }) res,
+  ) {
+    const result = await this.service.pollReverse({
+      pollToken: body.poll_token,
+      locale,
+    });
+
+    if ('session' in result && result.session && result.refreshToken) {
+      await this.token.setRefreshTokenCookie(
+        locale,
+        res,
+        result.refreshToken,
+        result.session.expires_at,
+      );
+    }
+
+    // A sessão inteira não volta para o cliente: ele precisa dos tokens, não do
+    // registro do banco.
+    const { session, ...payload } = result as Record<string, unknown> & {
+      session?: unknown;
+    };
+    return payload;
+  }
+}