@hed-hog/core 0.0.400 → 0.0.401

package/src/mcp/mcp.module.ts

@@ -32,6 +32,7 @@ import { McpPermissionService } from './mcp-permission.service';
 import { McpRegistryService } from './mcp-registry.service';
 import { McpServerService } from './mcp-server.service';
 import { McpController } from './mcp.controller';
+import { CoreAccessLogMcpTools } from './tools/core-access-log.mcp-tools';
 import { CoreAiMcpTools } from './tools/core-ai.mcp-tools';
 import { CoreDashboardItemsMcpTools } from './tools/core-dashboard-items.mcp-tools';
 import { CoreDashboardMcpTools } from './tools/core-dashboard.mcp-tools';
@@ -111,6 +112,7 @@ import { AccessLogModule } from '../access-log/access-log.module';
     CoreAiMcpTools,
     CoreMcpChatMcpTools,
     CoreSystemMcpTools,
+    CoreAccessLogMcpTools,
   ],
   exports: [McpRegistryService, McpServerService, McpApiKeyService, McpPermissionService],
 })

package/src/mcp/tools/core-access-log.mcp-tools.ts

@@ -0,0 +1,66 @@
+import { Injectable } from '@nestjs/common';
+import { AccessLogService } from '../../access-log/access-log.service';
+import { McpTool } from '../decorators/mcp-tool.decorator';
+import { McpContext } from '../types/mcp-context.type';
+
+const TYPES = ['http', 'mcp', 'all'] as const;
+const SIMULATED = ['all', 'only', 'exclude'] as const;
+
+@Injectable()
+export class CoreAccessLogMcpTools {
+  constructor(private readonly accessLogService: AccessLogService) {}
+
+  @McpTool({
+    name: 'core.access-log.list',
+    description:
+      'Lists the access log (the admin "Access log" screen): every authenticated HTTP request and MCP tool call, with user, method/URL or tool, IP, user agent and whether it happened during an access simulation. Newest first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        pageSize: { type: 'number', description: 'Items per page (default: 20)' },
+        userId: { type: 'number', description: 'Filter by user id' },
+        userSearch: { type: 'string', description: 'Matches the user name' },
+        createdAtFrom: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        createdAtTo: { type: 'string', description: 'End date (YYYY-MM-DD), inclusive' },
+        type: {
+          type: 'string',
+          description: 'http = REST requests, mcp = MCP tool calls (default: all)',
+          enum: [...TYPES],
+        },
+        simulated: {
+          type: 'string',
+          description: 'only/exclude accesses made while an admin simulated another user (default: all)',
+          enum: [...SIMULATED],
+        },
+      },
+    },
+    readOnly: true,
+  })
+  async list(
+    args: {
+      page?: number;
+      pageSize?: number;
+      userId?: number;
+      userSearch?: string;
+      createdAtFrom?: string;
+      createdAtTo?: string;
+      type?: string;
+      simulated?: string;
+    },
+    _context: McpContext,
+  ): Promise<any> {
+    return this.accessLogService.list({
+      page: args.page ?? 1,
+      pageSize: args.pageSize ?? 20,
+      userId: args.userId,
+      userSearch: args.userSearch,
+      createdAtFrom: args.createdAtFrom,
+      createdAtTo: args.createdAtTo,
+      type: TYPES.includes(args.type as any) ? (args.type as (typeof TYPES)[number]) : undefined,
+      simulated: SIMULATED.includes(args.simulated as any)
+        ? (args.simulated as (typeof SIMULATED)[number])
+        : undefined,
+    });
+  }
+}

package/src/mcp/tools/core-files.mcp-tools.ts

@@ -130,7 +130,7 @@ export class CoreFilesMcpTools {
   @McpTool({
     name: 'core.files.create-upload-url',
     description:
-      'Opens an upload and returns a short-lived, single-use URL to PUT the file to. This is how you send a file without putting its bytes in the conversation: call this, PUT the binary to the returned url, then call core.files.upload.complete to get the fileId, and pass that fileId to whichever tool needs the file. Works for files up to the storage-max-size setting (10mb by default).',
+      'Opens an upload and returns a short-lived, single-use URL on the Hub API host to PUT the file to: PUT the binary to the returned url, then call core.files.upload.complete to get the fileId (or pass the uploadId straight to the tool that needs the file). Fastest path, but the url must be reachable from wherever the PUT runs. Clients in a network-restricted sandbox (e.g. claude.ai) usually cannot reach it; if you are in one, or the PUT fails with host_not_allowed, 403 or a network error, use core.files.upload.init instead, which sends the file through MCP calls. Works for files up to the storage-max-size setting (10mb by default).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -185,14 +185,14 @@ export class CoreFilesMcpTools {
       headers: { 'Content-Type': ticket.mimetype },
       expiresAt: ticket.expires_at.toISOString(),
       sizeBytes: ticket.size_bytes,
-      next: 'PUT the raw file bytes to url, then call core.files.upload.complete with this uploadId.',
+      next: 'PUT the raw file bytes to url, then call core.files.upload.complete with this uploadId. If the PUT is blocked (host_not_allowed, 403, network error), open a new upload with core.files.upload.init and send the file in chunks instead.',
     };
   }
 
   @McpTool({
     name: 'core.files.upload.init',
     description:
-      'Opens an upload to be sent in base64 chunks. Only for clients that cannot make an HTTP request: it is far slower than core.files.create-upload-url, because the content still travels through the conversation, just split across calls. Follow with core.files.upload.append for each chunk and core.files.upload.complete at the end.',
+      'Opens an upload sent in base64 chunks through MCP calls, with no extra network access. Use it when core.files.create-upload-url is not an option: a network-restricted sandbox (e.g. claude.ai), or a PUT that failed with host_not_allowed, 403 or a network error. Works for files up to the storage-max-size setting (10mb by default), well beyond the ~256kb limit of inline fileBase64. Returns uploadId, chunkBytes and totalChunks. Then call core.files.upload.append once per chunk (index 0..totalChunks-1, each chunk at most chunkBytes raw bytes before base64 encoding) and finish with core.files.upload.complete to get the fileId, or pass the uploadId to the tool that needs the file. Generate the chunks programmatically in your sandbox (split the file and print the base64 of each chunk) rather than typing base64 by hand. The upload expires at expiresAt.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -225,7 +225,7 @@ export class CoreFilesMcpTools {
       chunkBytes,
       totalChunks: Math.ceil(ticket.size_bytes / chunkBytes),
       expiresAt: ticket.expires_at.toISOString(),
-      next: `Send each chunk with core.files.upload.append, indexes 0..n-1, at most ${chunkBytes} bytes before encoding.`,
+      next: `Send each chunk with core.files.upload.append, indexes 0..${Math.ceil(ticket.size_bytes / chunkBytes) - 1}, at most ${chunkBytes} raw bytes per chunk before base64 encoding, then call core.files.upload.complete with this uploadId.`,
     };
   }
 

package/src/meeting/meeting-provider.registry.ts

@@ -1,4 +1,5 @@
 import { Injectable, Logger } from '@nestjs/common';
+import { MeetingChatMessage } from './meeting.constants';
 
 /**
  * Pedido de criação de uma reunião online para uma entidade de negócio qualquer.
@@ -218,6 +219,61 @@ export interface MeetingChatAttachmentContent {
   size: number;
 }
 
+/**
+ * Pedido de publicação de uma mensagem no chat da reunião de uma origem.
+ *
+ * O corpo é HTML simples — `<p>`, `<br>`, `<strong>`, `<a href>` — e não texto
+ * puro porque o que motiva este contrato é mandar um link clicável para dentro
+ * da reunião. Provedor que não renderize HTML degrada tirando as tags; o texto
+ * continua legível.
+ */
+export interface PostMeetingChatMessageInput {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+  html: string;
+}
+
+/**
+ * Desfecho da publicação, sem exceção.
+ *
+ * Postar no chat é conveniência, não o caminho crítico: quem chama tem sempre o
+ * plano B de mostrar o texto para alguém colar à mão. Transformar "o tenant
+ * desligou o chat da reunião" em exceção obrigaria toda tela a tratar erro para
+ * uma situação que é normal.
+ */
+export type PostMeetingChatFailure =
+  /** Não há identidade/configuração para escrever. */
+  | 'unavailable'
+  /** A reunião não tem chat (ninguém entrou, ou o tenant o desligou). */
+  | 'no_chat'
+  /** Falta consentimento do escopo de envio na conta que escreve. */
+  | 'missing_scope'
+  /** O provedor recusou por outro motivo. */
+  | 'failed';
+
+/**
+ * Um objeto com campos opcionais, e não uma união discriminada, porque o
+ * monorepo compila com `strictNullChecks: false` — e sem essa flag o
+ * TypeScript não estreita a união pelo `ok`, obrigando todo consumidor a um
+ * cast. Melhor um contrato que funciona do que um mais elegante que ninguém
+ * consegue usar sem contorno.
+ *
+ * `ok: true` traz `providerMessageId`; `ok: false` traz `reason` e `message`.
+ */
+export interface PostMeetingChatMessageResult {
+  ok: boolean;
+  providerMessageId?: string | null;
+  reason?: PostMeetingChatFailure;
+  message?: string;
+}
+
+export interface ListMeetingChatMessagesInput {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+}
+
 /**
  * Provedor de reuniões online (Teams hoje; Meet/Zoom cabem no mesmo contrato).
  *
@@ -269,6 +325,30 @@ export interface IMeetingProvider {
   fetchChatAttachment?(
     input: FetchMeetingChatAttachmentInput,
   ): Promise<MeetingChatAttachmentContent | null>;
+  /**
+   * Publica uma mensagem no chat da reunião.
+   *
+   * Opcional pelo mesmo motivo de {@link fetchChatAttachment}, e nunca lança:
+   * o desfecho vem no retorno.
+   */
+  postChatMessage?(
+    input: PostMeetingChatMessageInput,
+  ): Promise<PostMeetingChatMessageResult>;
+  /**
+   * As mensagens do chat que o provedor já capturou para esta origem.
+   *
+   * Existe porque o evento `MEETING_CHAT_AVAILABLE_EVENT` tem teto de mensagens
+   * e, quando estoura, entrega as mais RECENTES. Isso serve para achar o
+   * material que o instrutor colou no fim da aula, e não serve para uma turma
+   * de 250 pessoas em que cada uma escreve: as primeiras somem do payload.
+   *
+   * Lê o que o provedor já guardou, sem ida nova ao serviço remoto — é a
+   * alternativa a fazer o módulo de origem ler a tabela do provedor, que é
+   * exatamente o acoplamento que este contrato existe para evitar.
+   */
+  listChatMessages?(
+    input: ListMeetingChatMessagesInput,
+  ): Promise<MeetingChatMessage[]>;
 }
 
 /**

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/providers/microsoft-entra-id.provider.spec.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { HttpService } from '@nestjs/axios';
+import { of } from 'rxjs';
+import { MicrosoftEntraIdProvider } from './microsoft-entra-id.provider';
+
+/**
+ * O que estes testes protegem: `user_account.scopes` tem que registrar o que a
+ * Microsoft CONCEDEU, não o que a setting pede.
+ *
+ * Gravar a setting quebrava toda a integração delegada de um jeito que não dava
+ * pista nenhuma. O `OAuthTokenBrokerService` monta o `scope` do refresh a partir
+ * dessa coluna; se ela promete um escopo que o consentimento não cobre, a
+ * Microsoft recusa o grant com `invalid_grant`, o broker traduz para "reconecte
+ * a conta" — e reconectar pelo login regrava a mesma setting, então o usuário
+ * reconecta, falha, reconecta, falha.
+ */
+
+const SCOPES_CONFIGURADOS = [
+  'openid',
+  'profile',
+  'email',
+  'User.Read',
+  'offline_access',
+  'Chat.Read',
+  'Files.Read.All',
+];
+
+const makeProvider = (tokenResponse: Record<string, unknown>) => {
+  const http = {
+    post: jest.fn(() => of({ data: tokenResponse })),
+    get: jest.fn(() => of({ data: { id: 'graph-id', mail: 'alguem@exemplo.test', displayName: 'Alguém' } })),
+  };
+
+  const setting = {
+    getSettingValues: jest.fn(async (slugs: string[]) => {
+      const values: Record<string, unknown> = {
+        'oauth-microsoft-entra-id-profile-id': 'perfil-entra',
+        'oauth-microsoft-entra-id-scopes': SCOPES_CONFIGURADOS,
+        url: 'https://app.exemplo.test',
+        'api-url': 'https://api.exemplo.test',
+      };
+      return Object.fromEntries(slugs.map((slug) => [slug, values[slug]]));
+    }),
+  };
+
+  const prisma = {
+    integration_profile: {
+      findUnique: jest.fn(async () => ({
+        slug: 'perfil-entra',
+        config: { client_id: 'CID', client_secret: 'SECRET', tenant_id: 'TENANT' },
+        integration_provider: { slug: 'microsoft-entra-id-oauth' },
+      })),
+    },
+  };
+
+  return new MicrosoftEntraIdProvider(
+    http as unknown as HttpService,
+    setting as any,
+    prisma as any,
+  );
+};
+
+const parse = (profile: any) => String(profile.oauth_scopes).split(',');
+
+describe('MicrosoftEntraIdProvider.getProfile — escopos', () => {
+  it('grava o que a Microsoft concedeu, não o que a setting pede', async () => {
+    // Consentimento antigo: nem Chat.Read nem Files.Read.All foram aprovados.
+    const provider = makeProvider({
+      access_token: 'ACCESS',
+      refresh_token: 'REFRESH',
+      expires_in: 3600,
+      scope: 'openid profile email User.Read',
+    });
+
+    const scopes = parse(await provider.getProfile('CODE', 'login'));
+
+    expect(scopes).not.toContain('Chat.Read');
+    expect(scopes).not.toContain('Files.Read.All');
+    expect(scopes).toContain('User.Read');
+  });
+
+  it('mantém offline_access quando veio refresh token, mesmo fora do scope', async () => {
+    // A Microsoft não repete `offline_access` em `token.scope`. Perdê-lo faria
+    // o broker tratar a conta como sem acesso offline.
+    const provider = makeProvider({
+      access_token: 'ACCESS',
+      refresh_token: 'REFRESH',
+      expires_in: 3600,
+      scope: 'openid profile email User.Read',
+    });
+
+    expect(parse(await provider.getProfile('CODE', 'login'))).toContain(
+      'offline_access',
+    );
+  });
+
+  it('não inventa offline_access quando não houve refresh token', async () => {
+    const provider = makeProvider({
+      access_token: 'ACCESS',
+      expires_in: 3600,
+      scope: 'openid profile email',
+    });
+
+    expect(parse(await provider.getProfile('CODE', 'login'))).not.toContain(
+      'offline_access',
+    );
+  });
+
+  it('cai para os escopos pedidos só quando a Microsoft não informa nenhum', async () => {
+    // Ausência de `scope` é omissão do provedor; lista vazia seria resposta.
+    const provider = makeProvider({
+      access_token: 'ACCESS',
+      refresh_token: 'REFRESH',
+      expires_in: 3600,
+    });
+
+    const scopes = parse(await provider.getProfile('CODE', 'login'));
+
+    expect(scopes).toEqual(expect.arrayContaining(SCOPES_CONFIGURADOS));
+  });
+
+  it('registra escopo concedido vazio como vazio, sem assumir o pedido', async () => {
+    const provider = makeProvider({
+      access_token: 'ACCESS',
+      expires_in: 3600,
+      scope: '   ',
+    });
+
+    expect(parse(await provider.getProfile('CODE', 'login'))).not.toContain(
+      'Files.Read.All',
+    );
+  });
+});