@hed-hog/core 0.0.399 → 0.0.401

package/src/mail/mail.service.spec.ts

@@ -82,11 +82,45 @@ describe('MailService', () => {
       expect(call('A\r\nB', {})).toBe('A<br/>B');
     });
 
+    it('preserva as quebras de linha de um documento HTML completo (não injeta <br/> dentro de <style>/<head>)', () => {
+      // Bug real: um HTML completo colado em Templates de e-mail (que
+      // funciona no preview cru de Campanhas) aparecia quebrado aqui porque
+      // toda quebra de linha virava "<br/>" literal mesmo dentro de <style>,
+      // invalidando o CSS antes de chegar em renderMailTemplate.
+      const fullHtml =
+        '<!DOCTYPE html>\n<html>\n<head>\n<style>\n.foo {\n  color: red;\n}\n</style>\n</head>\n<body>{{name}}</body>\n</html>';
+      const result = call(fullHtml, { name: 'Bob' });
+      expect(result).not.toContain('<br/>');
+      expect(result).toContain('.foo {\n  color: red;\n}');
+      expect(result).toContain('Bob');
+    });
+
     it('lança BadRequestException em sintaxe inválida', () => {
       expect(() => call('{{#if foo}}sem fechar', {})).toThrow(
         BadRequestException,
       );
     });
+
+    // Bug real: o assunto e texto puro (vira o header `subject:` do e-mail),
+    // mas o Handlebars padrao escapa `& < > " ' `` `` como se fosse HTML —
+    // uma crase no titulo da tarefa saia como `&#x60;` cru na caixa de
+    // entrada, e escapava DE NOVO no `<h1>` do corpo (renderMailTemplate),
+    // virando `&amp;#x60;`. `escapeHtml: false` e o que os call sites do
+    // assunto passam pra evitar isso.
+    it('com escapeHtml:false, nao escapa nada — usado no assunto (texto puro)', () => {
+      const src = 'Tarefa `{{title}}` & <urgente> "importante"';
+      const result = (makeService().service as any).interpolateTemplate(
+        src,
+        { title: 'status' },
+        { escapeHtml: false },
+      );
+      expect(result).toBe('Tarefa `status` & <urgente> "importante"');
+    });
+
+    it('por padrao (sem a opcao) continua escapando — usado no corpo, que e HTML de verdade', () => {
+      const result = call('Nome: {{name}}', { name: 'A & B <b>' });
+      expect(result).toBe('Nome: A &amp; B &lt;b&gt;');
+    });
   });
 
   describe('isSettingEnabled', () => {
@@ -331,6 +365,54 @@ describe('MailService', () => {
       ).resolves.toEqual({ sent: true, providerMessageId: 'ses-abc' });
     });
 
+    it('assunto com crase, & e aspas chega cru no e-mail — sem &#x60;/&amp; vazando (corpo continua escapando)', async () => {
+      const { service, deps } = makeService();
+      deps.setting.getSettingValues.mockResolvedValue({
+        'configured-mail': 'true',
+      } as any);
+      // `resolveUserLocale` diferente de 'en' evita o fallback que chama
+      // `normalizeLocaleCode(callerLocale)` — sem relação com o bug desta
+      // task, só contorna o pacote @hed-hog/api-locale com dist desatualizado
+      // neste ambiente (falta o export, dist nao republicado).
+      deps.setting.resolveUserLocale.mockResolvedValue('pt');
+      jest
+        .spyOn(service, 'reloadConfig')
+        .mockResolvedValue({ success: true, provider: 'ses', from: 'a@b.com', config: {} });
+      deps.prismaService.locale.findUnique.mockResolvedValue({ id: 1, code: 'en' });
+      deps.prismaService.mail.findUnique.mockResolvedValue({
+        id: 7,
+        mail_locale: [
+          {
+            // A crase literal no template (fora de {{}}) nunca foi escapada
+            // pelo Handlebars — quem escapava era o VALOR interpolado da
+            // variavel. O bug real tinha a crase dentro do dado (nome da
+            // tarefa), entao o teste reproduz isso: a crase mora em `title`,
+            // nao no texto fixo do template.
+            subject: 'Você foi atribuído à tarefa {{title}} & "urgente"',
+            body: 'Título: {{title}}',
+            locale: { code: 'en' },
+          },
+        ],
+        mail_var: [],
+      });
+      deps.mailMainService.send.mockResolvedValue({ result: { MessageId: 'ses-abc' } });
+
+      await service.sendTemplatedMail('en', {
+        email: 'a@b.com',
+        slug: 's',
+        variables: { title: '`status`' },
+      } as any);
+
+      const sentArgs = deps.mailMainService.send.mock.calls[0][0] as { subject: string; body: string };
+      expect(sentArgs.subject).toBe('Você foi atribuído à tarefa `status` & "urgente"');
+      expect(sentArgs.subject).not.toContain('&#x60;');
+      expect(sentArgs.subject).not.toContain('&amp;');
+      // O corpo e HTML de verdade — a mesma crase, vinda do mesmo dado,
+      // continua escapando normalmente ali (nao é dupla checagem à toa: prova
+      // que `escapeHtml:false` ficou restrito ao assunto).
+      expect(sentArgs.body).toContain('&#x60;status&#x60;');
+    });
+
     // O bug que originou esta mudanca: o e-mail saia no idioma do header (ou no
     // `en` de quem nao manda header), ignorando a preferencia do destinatario.
     describe('idioma do destinatario', () => {
@@ -579,6 +661,36 @@ describe('MailService', () => {
       expect(html).toContain('lang="pt"');
     });
 
+    // Regressao do bug real: assunto com crase saia como `&#x60;` cru no
+    // assunto do e-mail e `&amp;#x60;` (escape duplo) no <h1> do corpo. O
+    // fluxo completo (interpolateTemplate -> renderMailTemplate) precisa
+    // produzir cada caractere especial escapado NO MAXIMO uma vez, e so pelo
+    // renderMailTemplate — sem o <script> escapando pra HTML executavel.
+    it('assunto com crase, &, aspas e <script> nao vaza entidade e nao escapa duas vezes no <h1>', async () => {
+      const { service } = makePreviewService();
+
+      const { html } = await service.preview('pt', {
+        subject: 'Tarefa `{{title}}` & "urgente" <script>alert(1)</script>',
+        body: '<p>Corpo</p>',
+        variables: { title: 'status' },
+      });
+
+      // Crase nunca vira entidade (renderMailTemplate/escapeHtml nem trata
+      // crase como caractere especial) — nem &#x60; nem, pior, &amp;#x60;.
+      expect(html).not.toContain('#x60;');
+      // & e " escapados exatamente uma vez (não &amp;amp; / &amp;quot;).
+      expect(html).toContain('&amp;');
+      expect(html).not.toContain('&amp;amp;');
+      expect(html).not.toContain('&amp;quot;');
+      // <script> chega escapado, nunca como tag executável.
+      expect(html).not.toContain('<script>alert(1)</script>');
+      expect(html).toContain('&lt;script&gt;');
+
+      expect(html).toContain(
+        '<h1>Tarefa `status` &amp; &quot;urgente&quot; &lt;script&gt;alert(1)&lt;/script&gt;</h1>',
+      );
+    });
+
     it('produz exatamente o mesmo corpo que o envio real', async () => {
       // Esta é a asserção que justifica o endpoint: o preview do admin não pode
       // divergir do e-mail que sai. Os dois caminhos passam pelo mesmo

package/src/mail/mail.service.ts

@@ -8,9 +8,11 @@ import {
 import {
   DEFAULT_PRIMARY_COLOR,
   DEFAULT_PRIMARY_FOREGROUND,
+  isFullHtmlDocument,
   MailLayout,
   MailService as MailMainService,
   renderMailTemplate,
+  sanitizeAccentColor,
 } from '@hed-hog/api-mail';
 import { PaginationDTO } from '@hed-hog/api-pagination';
 import { PrismaService } from '@hed-hog/api-prisma';
@@ -508,8 +510,14 @@ export class MailService implements OnModuleInit {
       const brandName = await this.mailMainService.getBrandName(app, templateLocale);
       const { primaryColor, primaryForeground } = await this.getThemeVariables();
       const mergedVariables = { brandName, primaryColor, primaryForeground, ...variables };
-      const parsedSubject = this.interpolateTemplate(subject, mergedVariables);
+      const parsedSubject = this.interpolateTemplate(subject, mergedVariables, { escapeHtml: false });
       const parsedBody = this.interpolateTemplate(body, mergedVariables);
+      // A cor da etapa vem do remetente (o commerce manda uma por slug) e chega
+      // ate o wrapper, que pinta a barra de destaque. `sanitizeAccentColor`
+      // descarta o que nao for `#rrggbb` porque o valor entra num bloco <style>.
+      const accentColor = sanitizeAccentColor(
+        typeof variables?.accentColor === 'string' ? variables.accentColor : undefined,
+      );
 
       const sendResult: any = await this.mailMainService.send({
         to: email,
@@ -517,6 +525,7 @@ export class MailService implements OnModuleInit {
         ...(resolvedReplyTo ? { replyTo: resolvedReplyTo } : {}),
         subject: parsedSubject,
         body: parsedBody,
+        ...(accentColor ? { accentColor } : {}),
         mail_id: mail.id,
         // O layout (header/footer) e escolhido por este locale la no api-mail,
         // entao tem que ser o do template escolhido, nao o cru do request.
@@ -662,12 +671,31 @@ export class MailService implements OnModuleInit {
     return mail;
   }
 
+  /**
+   * `escapeHtml` (default true) controla o escape padrao do Handlebars pra
+   * `&`, `<`, `>`, `"`, `'` e crase. O corpo e HTML de verdade e precisa dele;
+   * o assunto e texto puro (vira o header `subject:` do e-mail e, no corpo,
+   * passa de novo por `renderMailTemplate`/`escapeHtml` do `@hed-hog/api-mail`
+   * pra virar o `<h1>`) — escapar aqui tambem faria uma crase no assunto virar
+   * `&#x60;` cru na caixa de entrada, e depois `&amp;#x60;` no `<h1>` (escape
+   * duplo). Quem chama pro assunto passa `{ escapeHtml: false }`.
+   */
   private interpolateTemplate(
     source: string,
     data: any,
+    { escapeHtml = true }: { escapeHtml?: boolean } = {},
   ): string {
     try {
-      const template = Handlebars.compile(source.replace(/(\r\n|\n|\r)/g, '<br/>'));
+      // Um documento HTML completo (<style>/<head>/<script>) tem quebra de
+      // linha significativa dentro dessas tags — trocar por <br/> às cegas
+      // quebra o CSS/HTML (renderMailTemplate já pula o wrapper pra esse
+      // caso; aqui só espelhamos a mesma detecção pra não mutilar antes
+      // disso). Emails simples (sem <html>) continuam ganhando <br/> pra
+      // preservar quebras de linha digitadas pelo usuário.
+      const normalized = isFullHtmlDocument(source)
+        ? source
+        : source.replace(/(\r\n|\n|\r)/g, '<br/>');
+      const template = Handlebars.compile(normalized, { noEscape: !escapeHtml });
       return template(data);
     } catch (error: any) {
       this.logger.error('Handlebars template compilation error:', error);
@@ -741,7 +769,7 @@ export class MailService implements OnModuleInit {
       ? (await this.brandAsset.resolveAssetUrl(rawLogoUrl)) || undefined
       : undefined;
     const data = { brandName, primaryColor, primaryForeground, ...(variables || {}) };
-    const parsedSubject = subject ? this.interpolateTemplate(subject, data) : '';
+    const parsedSubject = subject ? this.interpolateTemplate(subject, data, { escapeHtml: false }) : '';
     const parsedBody = body ? this.interpolateTemplate(body, data) : '';
 
     let resolvedLayout: MailLayout | null = null;
@@ -765,6 +793,11 @@ export class MailService implements OnModuleInit {
       brandName,
       primaryColor,
       primaryForeground,
+      // Mesma leitura do envio: sem isto a pre-visualizacao do admin mostraria a
+      // barra na cor da marca e o e-mail sairia na cor da etapa.
+      accentColor: sanitizeAccentColor(
+        typeof variables?.accentColor === 'string' ? variables.accentColor : undefined,
+      ),
       logoUrl,
       lang: locale,
     });
@@ -792,13 +825,18 @@ export class MailService implements OnModuleInit {
       const brandName = await this.mailMainService.getBrandName(undefined, locale);
       const { primaryColor, primaryForeground } = await this.getThemeVariables();
       const mergedVariables = { brandName, primaryColor, primaryForeground, ...(variables || {}) };
-      const parsedSubject = this.interpolateTemplate(subject, mergedVariables);
+      const parsedSubject = this.interpolateTemplate(subject, mergedVariables, { escapeHtml: false });
       const parsedBody = this.interpolateTemplate(body, mergedVariables);
 
+      const accentColor = sanitizeAccentColor(
+        typeof variables?.accentColor === 'string' ? variables.accentColor : undefined,
+      );
+
       return this.mailMainService.send({
         to: email,
         subject: parsedSubject,
         body: parsedBody,
+        ...(accentColor ? { accentColor } : {}),
         mail_id: mail.id,
         from,
         locale,

package/src/mail-sent/mail-sent.service.ts

@@ -12,6 +12,7 @@ import {
 import { CreateDTO } from './dto/create.dto';
 import { QueryMailSentListDTO } from './dto/query-mail-sent-list.dto';
 import { UpdateDTO } from './dto/update.dto';
+import { MAIL_SENT_SORT } from './mail-sent.sort';
 
 type MailSentUserStatus = 'received' | 'read' | 'error';
 
@@ -186,6 +187,8 @@ export class MailSentService {
           },
         },
       },
+      undefined,
+      { sort: MAIL_SENT_SORT },
     );
 
     const data = (result.data as MailSentWithUsers[]).map((item) => {

package/src/mail-sent/mail-sent.sort.ts

@@ -0,0 +1,19 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `mail_sent`.
+ *
+ * "Delivery" (o badge exibido na listagem) fica de fora: é um resumo agregado
+ * calculado no service a partir de `mail_sent_user` (to-many), não uma coluna
+ * — o Prisma não tem como ordenar por ele.
+ */
+export const MAIL_SENT_SORT = defineSortable(
+  {
+    subject: true,
+    from: true,
+    to: true,
+    created_at: { initialOrder: 'desc' },
+    id: { initialOrder: 'desc' },
+  },
+  { default: 'created_at', defaultOrder: 'desc' },
+);

package/src/mcp/filters/mcp-challenge.filter.spec.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it, jest } from '@jest/globals';
+import {
+  ForbiddenException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { McpChallengeFilter } from './mcp-challenge.filter';
+
+const ISSUER = 'https://hub-api.example.com';
+const METADATA_URL = `${ISSUER}/.well-known/oauth-protected-resource/mcp`;
+
+const makeFilter = () => {
+  const metadata = { getIssuer: jest.fn<any>().mockResolvedValue(ISSUER) };
+  const response: any = {
+    setHeader: jest.fn(),
+    status: jest.fn().mockReturnThis(),
+    json: jest.fn().mockReturnThis(),
+  };
+  const host: any = { switchToHttp: () => ({ getResponse: () => response }) };
+  return { filter: new McpChallengeFilter(metadata as any), response, host };
+};
+
+describe('McpChallengeFilter', () => {
+  afterEach(() => jest.clearAllMocks());
+
+  // O passo 1 de todo fluxo OAuth de cliente MCP: bater sem token e ler daqui
+  // onde estao os metadados do recurso.
+  it('desafia o 401 com resource_metadata', async () => {
+    const { filter, response, host } = makeFilter();
+
+    await filter.catch(new UnauthorizedException('Access denied.'), host);
+
+    expect(response.setHeader).toHaveBeenCalledWith(
+      'WWW-Authenticate',
+      `Bearer resource_metadata="${METADATA_URL}", error="invalid_token"`,
+    );
+    expect(response.status).toHaveBeenCalledWith(401);
+  });
+
+  it('pede reautorizacao quando falta o escopo mcp', async () => {
+    const { filter, response, host } = makeFilter();
+
+    await filter.catch(
+      new ForbiddenException("MCP: token is missing the 'mcp' scope"),
+      host,
+    );
+
+    const [, value] = response.setHeader.mock.calls[0];
+    expect(value).toContain('error="insufficient_scope"');
+    expect(value).toContain('scope="mcp"');
+    expect(response.status).toHaveBeenCalledWith(403);
+  });
+
+  // 403 por falta de papel numa tool nao se resolve reautorizando: mandar
+  // insufficient_scope poria o cliente num laco de reautorizacao sem fim.
+  it('nao desafia 403 de permissao de tool', async () => {
+    const { filter, response, host } = makeFilter();
+
+    await filter.catch(
+      new ForbiddenException("Access denied to MCP tool 'core.users.list'"),
+      host,
+    );
+
+    expect(response.setHeader).not.toHaveBeenCalled();
+    expect(response.status).toHaveBeenCalledWith(403);
+  });
+
+  it('preserva o corpo original da excecao', async () => {
+    const { filter, response, host } = makeFilter();
+
+    await filter.catch(new UnauthorizedException('Access denied.'), host);
+
+    expect(response.json).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'Access denied.' }),
+    );
+  });
+});

package/src/mcp/filters/mcp-challenge.filter.ts

@@ -0,0 +1,70 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { Response } from 'express';
+import { OAuthMetadataService } from '../../authorize/oauth-metadata.service';
+import { MCP_SCOPE } from '../guards/mcp-auth.guard';
+
+/**
+ * O desafio `WWW-Authenticate` do /mcp — o primeiro passo de todo fluxo OAuth de
+ * um cliente MCP (RFC 9728 §5.1): ele bate sem token, lê deste cabeçalho onde
+ * estão os metadados do recurso, e só então sabe a quem pedir autorização.
+ *
+ * Precisa ser um ExceptionFilter, e não um trecho dentro do McpAuthGuard, porque
+ * o caso que mais importa nem chega ao McpAuthGuard: numa requisição SEM token,
+ * quem lança o 401 é o AuthGuard global, que roda antes. Um filtro declarado no
+ * controller captura tambem o que os guards lançam, e por isso cobre os dois.
+ */
+@Catch(HttpException)
+export class McpChallengeFilter implements ExceptionFilter {
+  constructor(private readonly metadata: OAuthMetadataService) {}
+
+  async catch(exception: HttpException, host: ArgumentsHost): Promise<void> {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const status = exception.getStatus();
+
+    if (status === HttpStatus.UNAUTHORIZED) {
+      response.setHeader(
+        'WWW-Authenticate',
+        `Bearer resource_metadata="${await this.resourceMetadataUrl()}", error="invalid_token"`,
+      );
+    } else if (status === HttpStatus.FORBIDDEN) {
+      // 403 aqui pode ser falta de escopo (o token não foi autorizado para o MCP)
+      // ou falta de papel numa tool específica. Só o primeiro é recuperável por
+      // uma nova autorização, e é o único que ganha o desafio de escopo — mandar
+      // `insufficient_scope` no segundo caso faria o cliente entrar num laço de
+      // reautorização que nunca resolve.
+      if (this.isScopeError(exception)) {
+        response.setHeader(
+          'WWW-Authenticate',
+          `Bearer error="insufficient_scope", scope="${MCP_SCOPE}", resource_metadata="${await this.resourceMetadataUrl()}"`,
+        );
+      }
+    }
+
+    const body = exception.getResponse();
+    response
+      .status(status)
+      .json(
+        typeof body === 'string'
+          ? { statusCode: status, message: body }
+          : body,
+      );
+  }
+
+  private isScopeError(exception: HttpException): boolean {
+    const body = exception.getResponse() as any;
+    const message =
+      typeof body === 'string' ? body : String(body?.message ?? '');
+    return message.includes(`'${MCP_SCOPE}' scope`);
+  }
+
+  private async resourceMetadataUrl(): Promise<string> {
+    return `${await this.metadata.getIssuer()}/.well-known/oauth-protected-resource/mcp`;
+  }
+}

package/src/mcp/guards/mcp-auth.guard.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
-import { UnauthorizedException } from '@nestjs/common';
+import { ForbiddenException, UnauthorizedException } from '@nestjs/common';
 import { McpAuthGuard } from './mcp-auth.guard';
 
 const makeContext = (request: any) => ({
@@ -10,14 +10,20 @@ const makeDeps = () => {
   const tokenService = { verify: jest.fn() };
   const prisma = { mcp_api_key: { findFirst: jest.fn(), update: jest.fn() } };
   const security = { hashWithPepper: jest.fn().mockReturnValue('hash') };
-  return { tokenService, prisma, security };
+  const oauthMetadata = {
+    getMcpResource: jest.fn<any>().mockResolvedValue(MCP_RESOURCE),
+  };
+  return { tokenService, prisma, security, oauthMetadata };
 };
 
+const MCP_RESOURCE = 'https://hub-api.example.com/mcp';
+
 const makeService = (deps = makeDeps()) => ({
   guard: new McpAuthGuard(
     deps.tokenService as any,
     deps.prisma as any,
     deps.security as any,
+    deps.oauthMetadata as any,
   ),
   deps,
 });
@@ -40,6 +46,49 @@ describe('McpAuthGuard', () => {
       true,
     );
     expect(request.auth).toEqual({ sub: 4 });
+    // O recurso e passado para o verify — e dele que sai a recusa de um token
+    // emitido para outra audiencia.
+    expect(deps.tokenService.verify).toHaveBeenCalledWith(
+      expect.anything(),
+      'tok',
+      MCP_RESOURCE,
+    );
+  });
+
+  it('aceita token OAuth que traz o escopo mcp', async () => {
+    const { guard, deps } = makeService();
+    deps.tokenService.verify.mockResolvedValue({
+      sub: 4,
+      aud: MCP_RESOURCE,
+      scope: 'mcp',
+    });
+    const request: any = { headers: { authorization: 'Bearer tok' } };
+    await expect(guard.canActivate(makeContext(request) as any)).resolves.toBe(
+      true,
+    );
+  });
+
+  it('nega token OAuth sem o escopo mcp', async () => {
+    const { guard, deps } = makeService();
+    deps.tokenService.verify.mockResolvedValue({
+      sub: 4,
+      aud: MCP_RESOURCE,
+      scope: 'profile',
+    });
+    const request: any = { headers: { authorization: 'Bearer tok' } };
+    await expect(
+      guard.canActivate(makeContext(request) as any),
+    ).rejects.toThrow(ForbiddenException);
+  });
+
+  // O JWT de login nunca teve `scope`; exigi-lo quebraria o uso interno do /mcp.
+  it('nao exige escopo de token sem audiencia', async () => {
+    const { guard, deps } = makeService();
+    deps.tokenService.verify.mockResolvedValue({ sub: 4 });
+    const request: any = { headers: { authorization: 'Bearer tok' } };
+    await expect(guard.canActivate(makeContext(request) as any)).resolves.toBe(
+      true,
+    );
   });
 
   it('autentica com api key mcp válida', async () => {

package/src/mcp/guards/mcp-auth.guard.ts

@@ -2,19 +2,24 @@ import { PrismaService } from '@hed-hog/api-prisma';
 import {
   CanActivate,
   ExecutionContext,
+  ForbiddenException,
   Injectable,
   UnauthorizedException,
 } from '@nestjs/common';
 import { Request } from 'express';
+import { MCP_SCOPE, OAuthMetadataService } from '../../authorize/oauth-metadata.service';
 import { SecurityService } from '../../security/security.service';
 import { TokenService } from '../../token/token.service';
 
+export { MCP_SCOPE };
+
 @Injectable()
 export class McpAuthGuard implements CanActivate {
   constructor(
     private readonly tokenService: TokenService,
     private readonly prisma: PrismaService,
     private readonly security: SecurityService,
+    private readonly oauthMetadata: OAuthMetadataService,
   ) {}
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
@@ -31,7 +36,25 @@ export class McpAuthGuard implements CanActivate {
       return this.verifyApiKey(request, token);
     }
 
-    request['auth'] = await this.tokenService.verify(locale, token);
+    const payload = await this.tokenService.verify(
+      locale,
+      token,
+      await this.oauthMetadata.getMcpResource(),
+    );
+
+    // Token emitido pelo fluxo OAuth carrega `scope`; o JWT de login, nao. So o
+    // primeiro precisa provar que o usuario consentiu com o acesso ao MCP — exigir
+    // escopo de um token de sessao quebraria o uso interno, que nunca teve escopo.
+    if (payload.aud !== undefined) {
+      const scopes = String(payload.scope ?? '').split(/\s+/).filter(Boolean);
+      if (!scopes.includes(MCP_SCOPE)) {
+        throw new ForbiddenException(
+          `MCP: token is missing the '${MCP_SCOPE}' scope`,
+        );
+      }
+    }
+
+    request['auth'] = payload;
     return true;
   }