@hed-hog/core 0.0.399 → 0.0.401

package/src/session/session.service.ts

@@ -24,6 +24,36 @@ type GeoIpResult = {
 export class SessionService {
   private readonly logger = new Logger(SessionService.name);
 
+  /**
+   * Janela em que o refresh token ANTERIOR continua sendo aceito depois de uma
+   * rotacao.
+   *
+   * Sem ela a rotacao e um handoff sem tolerancia: se a resposta do
+   * `/auth/refresh` se perde no caminho de volta — rede caindo, aba suspensa,
+   * pod reciclado no meio de um rollout — o servidor ja girou e o cliente fica
+   * com um token que nao vale mais. Uma sessao valida de 30 dias morre por um
+   * soluco de rede, e o unico rastro e um 401 solto. A janela tambem absorve
+   * duas abas renovando ao mesmo tempo.
+   *
+   * Curta de proposito: ela existe para cobrir a corrida e a resposta perdida,
+   * nao para prolongar a vida do token.
+   */
+  private static readonly REFRESH_GRACE_MS = 30_000;
+
+  /**
+   * Sessao aberta por um cliente OAuth externo vive menos que a de login: o
+   * refresh token esta com um terceiro. Vale na criacao E na renovacao — sem
+   * reaplicar aqui, a primeira renovacao devolvia a sessao aos 30 dias globais e
+   * o limite virava decoracao.
+   */
+  static readonly CONNECTOR_SESSION_TTL_MINUTES = 7 * 24 * 60;
+
+  /**
+   * Tentativas de rotacao por chamada. A segunda cobre o caso de outra
+   * requisicao ter girado a sessao entre a leitura e o compare-and-swap.
+   */
+  private static readonly REFRESH_ROTATION_ATTEMPTS = 2;
+
   constructor(
     private prisma: PrismaService,
     @Inject(forwardRef(() => SecurityService))
@@ -40,7 +70,19 @@ export class SessionService {
     private readonly paginationService: PaginationService,
   ) { }
 
-  async create(locale: string, userId: number, ipAddress: string, userAgent: string, browserId?: string | null) {
+  /**
+   * `oauth` marca a sessao como pertencente a um cliente OAuth externo. Vem
+   * preenchido so pela troca do authorization code quando o cliente pediu um
+   * `resource`; o login normal continua chamando sem ele e nada muda.
+   */
+  async create(
+    locale: string,
+    userId: number,
+    ipAddress: string,
+    userAgent: string,
+    browserId?: string | null,
+    oauth?: { audience: string; clientId: string; ttlMinutes?: number },
+  ) {
     if (!userId) {
       throw new BadRequestException(getLocaleText('session.userIdRequired', locale, 'User ID is required to create a session.'));
     }
@@ -61,18 +103,34 @@ export class SessionService {
     const hash = this.security.hashWithPepper(token)
     const maxSessions = Number(settings['max-concurrent-sessions']) || 0;
 
-    if (maxSessions > 0) {
+    // E pela mesma razao a sessao de conector nao DISPARA o despejo ao nascer.
+    // `createImpersonation` ja se isenta assim; aqui o efeito seria o usuario
+    // perder o celular por ter autorizado um app.
+    if (maxSessions > 0 && !oauth) {
       await this.enforceSessionLimit(userId, maxSessions, false, browserId);
     }
 
+    // Sessao de conector vive menos que a de login. Nao e simetria estetica: o
+    // refresh token esta com um terceiro, e 30 dias de janela para um segredo que
+    // saiu do nosso dominio e generoso demais.
+    //
+    // `||` e nao `??` em toda a cadeia: `Number(undefined)` e NaN, que passa
+    // direto por `??` e produziria um expires_at invalido.
+    const ttlMinutes =
+      oauth?.ttlMinutes ||
+      Number(settings['refresh-token-expiration-minutes']) ||
+      43200;
+
     const session = await this.prisma.user_session.create({
       data: {
         user_id: userId,
         ip_address: ipAddress,
         user_agent: userAgent,
-        expires_at: new Date(Date.now() + ((settings['refresh-token-expiration-minutes'] || 43200) * 60 * 1000)),
+        expires_at: new Date(Date.now() + ttlMinutes * 60 * 1000),
         hash,
         browser_id: browserId ?? null,
+        audience: oauth?.audience ?? null,
+        oauth_client_id: oauth?.clientId ?? null,
       },
     });
 
@@ -150,104 +208,221 @@ export class SessionService {
     }));
   }
 
-  async refresh(locale: string, refreshToken: string, ipAddress: string, userAgent: string, browserId?: string | null) {
-    if (!refreshToken) {
-      throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
-    }
-
-    const hash = this.security.hashWithPepper(refreshToken);
-
-    const rawSession = await this.prisma.user_session.findFirst({
-      where: { hash },
-      select: { id: true, user_id: true, ip_address: true, user_agent: true, revoked_at: true, expires_at: true, browser_id: true, impersonator_user_id: true },
-    });
+  /**
+   * Anexa `oauth_client: { client_id, name }` as sessoes abertas por um cliente
+   * OAuth externo. Mesmo padrao de `attachImpersonators`, e pela mesma razao:
+   * `oauth_client_id` e VARCHAR puro, sem FK.
+   *
+   * Existe porque sem o nome a tela de seguranca do usuario fica ILEGIVEL para
+   * esse caso: um conector fala com a API a partir da nuvem do fornecedor, entao
+   * a linha aparece com user agent que o ua-parser nao reconhece
+   * (`python-httpx/0.28.1`), sem dispositivo, e geolocalizada no pais dele. Para
+   * quem esta no Brasil, e indistinguivel de uma conta invadida.
+   */
+  private async attachOAuthClients<T extends { oauth_client_id?: string | null }>(rows: T[]) {
+    const ids = Array.from(
+      new Set(
+        rows
+          .map((row) => row.oauth_client_id)
+          .filter((id): id is string => typeof id === 'string' && id.length > 0),
+      ),
+    );
 
-    if (!rawSession) {
-      this.logger.warn(`[SessionRefresh] Refresh rejected: hash prefix ${hash.slice(0, 8)} not found in DB`);
-      throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+    if (!ids.length) {
+      return rows.map((row) => ({ ...row, oauth_client: null }));
     }
 
-    if (rawSession.revoked_at !== null) {
-      this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} revoked_at=${rawSession.revoked_at.toISOString()} hash prefix ${hash.slice(0, 8)}`);
-      throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
-    }
+    const clients = await this.prisma.oauth_app_client.findMany({
+      where: { client_id: { in: ids } },
+      select: { client_id: true, name: true },
+    });
+    const byId = new Map(clients.map((client) => [client.client_id, client]));
 
-    if (rawSession.expires_at <= new Date()) {
-      this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} expired expires_at=${rawSession.expires_at.toISOString()} hash prefix ${hash.slice(0, 8)}`);
-      throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
-    }
+    return rows.map((row) => ({
+      ...row,
+      oauth_client: row.oauth_client_id
+        ? // Client removido do registro ainda tem sessao viva: cai no proprio
+          // slug, que e melhor que sumir com a informacao.
+          (byId.get(row.oauth_client_id) ?? {
+            client_id: row.oauth_client_id,
+            name: row.oauth_client_id,
+          })
+        : null,
+    }));
+  }
 
-    // Simulacao de acesso e nao renovavel. `createImpersonation` ja descarta o
-    // token opaco, entao chegar aqui significa que alguem obteve o segredo por
-    // outro caminho — e renovar transformaria a janela de 30 minutos numa sessao
-    // normal de 30 dias, sem a marca de simulado.
-    if (rawSession.impersonator_user_id !== null) {
-      this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} is an impersonation session`);
+  /**
+   * Gira o refresh token PRESERVANDO a identidade da sessao.
+   *
+   * A versao anterior revogava a linha e criava outra, com `id` novo. Como
+   * `TokenService.verify` valida a sessao no banco a cada request e recusa
+   * qualquer access token cuja sessao esteja revogada, o instante do refresh
+   * matava todos os access tokens em voo — na hora, e nao no `exp`. Numa tela
+   * que dispara ~10 chamadas em paralelo isso virava reacao em cadeia: cada 401
+   * disparava outro refresh, cada refresh matava os tokens dos outros. Nos logs
+   * de producao de 24/08 foram doze sessoes giradas em 18 segundos para o mesmo
+   * usuario, terminando em `Refresh rejected` e logout.
+   *
+   * Com o `id` estavel, o access token que ja saiu continua valido ate o proprio
+   * `exp`, e a rotacao deixa de ser um evento observavel pelo resto do app. De
+   * quebra a tabela para de crescer uma linha a cada 15 minutos por dispositivo.
+   */
+  async refresh(locale: string, refreshToken: string, ipAddress: string, userAgent: string, browserId?: string | null) {
+    if (!refreshToken) {
       throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
     }
 
-    const session = {
-      id: rawSession.id,
-      user_id: rawSession.user_id,
-      ip_address: rawSession.ip_address,
-      user_agent: rawSession.user_agent,
-      browser_id: rawSession.browser_id,
-    };
+    const hash = this.security.hashWithPepper(refreshToken);
 
     const settings = await this.setting.getSettingValues([
       'refresh-token-expiration-minutes',
       'max-concurrent-sessions',
     ]);
-
     const maxSessions = Number(settings['max-concurrent-sessions']) || 0;
-    if (maxSessions > 0) {
-      await this.enforceSessionLimit(session.user_id, maxSessions, true, browserId);
-    }
+    const ttlMinutes = Number(settings['refresh-token-expiration-minutes']) || 43200;
 
-    const nextRefreshToken = await this.token.createOpaqueToken();
-    const nextHash = this.security.hashWithPepper(nextRefreshToken);
-    const expiresAt = new Date(Date.now() + ((settings['refresh-token-expiration-minutes'] || 43200) * 60 * 1000));
-    const nextIpAddress = ipAddress?.trim() || session.ip_address || 'unknown';
-    const nextUserAgent = userAgent?.trim() || session.user_agent || 'unknown';
+    for (let attempt = 1; attempt <= SessionService.REFRESH_ROTATION_ATTEMPTS; attempt++) {
+      const rawSession = await this.prisma.user_session.findFirst({
+        where: this.refreshTokenWhere(hash),
+        select: { id: true, user_id: true, ip_address: true, user_agent: true, revoked_at: true, expires_at: true, browser_id: true, impersonator_user_id: true, hash: true, audience: true, oauth_client_id: true },
+      });
 
-    this.logger.debug(`[SessionRefresh] Starting rotation userId=${session.user_id} oldSessionId=${session.id} ip=${nextIpAddress}`);
-    const txStart = Date.now();
+      if (!rawSession) {
+        this.logger.warn(`[SessionRefresh] Refresh rejected: hash prefix ${hash.slice(0, 8)} not found in DB`);
+        throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+      }
+
+      if (rawSession.revoked_at !== null) {
+        this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} revoked_at=${rawSession.revoked_at.toISOString()} hash prefix ${hash.slice(0, 8)}`);
+        throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+      }
+
+      if (rawSession.expires_at <= new Date()) {
+        this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} expired expires_at=${rawSession.expires_at.toISOString()} hash prefix ${hash.slice(0, 8)}`);
+        throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+      }
+
+      // Simulacao de acesso e nao renovavel. `createImpersonation` ja descarta o
+      // token opaco, entao chegar aqui significa que alguem obteve o segredo por
+      // outro caminho — e renovar transformaria a janela de 30 minutos numa sessao
+      // normal de 30 dias, sem a marca de simulado.
+      if (rawSession.impersonator_user_id !== null) {
+        this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} is an impersonation session`);
+        throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+      }
 
-    const { updateResult, newSession } = await this.prisma.$transaction(async (tx) => {
-      const updateResult = await tx.user_session.updateMany({
+      const nextRefreshToken = await this.token.createOpaqueToken();
+      const nextHash = this.security.hashWithPepper(nextRefreshToken);
+      const now = Date.now();
+      // Sessao de conector nao volta aos 30 dias globais so por ter sido
+      // renovada — o TTL curto e a propriedade que a distingue.
+      const effectiveTtl = rawSession.audience
+        ? Math.min(ttlMinutes, SessionService.CONNECTOR_SESSION_TTL_MINUTES)
+        : ttlMinutes;
+      const expiresAt = new Date(now + effectiveTtl * 60 * 1000);
+      const nextIpAddress = ipAddress?.trim() || rawSession.ip_address || 'unknown';
+      const nextUserAgent = userAgent?.trim() || rawSession.user_agent || 'unknown';
+
+      // Compare-and-swap pelo hash corrente, na MESMA linha. Se outra requisicao
+      // girou primeiro, `count` volta 0 e a proxima volta le o hash novo — em vez
+      // de devolver 401 para o perdedor da corrida, como antes.
+      const updateResult = await this.prisma.user_session.updateMany({
         where: {
-          id: session.id,
+          id: rawSession.id,
           revoked_at: null,
+          hash: rawSession.hash,
         },
         data: {
-          revoked_at: new Date(),
+          hash: nextHash,
+          previous_hash: rawSession.hash,
+          previous_hash_expires_at: new Date(now + SessionService.REFRESH_GRACE_MS),
+          expires_at: expiresAt,
+          ip_address: nextIpAddress,
+          user_agent: nextUserAgent,
+          browser_id: rawSession.browser_id ?? browserId ?? null,
+          updated_at: new Date(),
         },
       });
 
-      const newSession = await tx.user_session.create({
-        data: {
-          user_id: session.user_id,
+      if (updateResult.count === 0) {
+        this.logger.debug(`[SessionRefresh] Rotation lost the CAS sessionId=${rawSession.id} userId=${rawSession.user_id} attempt=${attempt}`);
+        continue;
+      }
+
+      // Depois da rotacao, nunca antes. Rodando antes, o limite podia revogar a
+      // propria sessao que estava sendo renovada e o CAS falhava sozinho. E
+      // `keepSessionId` garante que renovar nunca despeja quem esta renovando.
+      if (maxSessions > 0) {
+        await this.enforceSessionLimit(rawSession.user_id, maxSessions, true, browserId, rawSession.id);
+      }
+
+      this.logger.debug(`[SessionRefresh] Rotation successful userId=${rawSession.user_id} sessionId=${rawSession.id} durationMs=${Date.now() - now}`);
+
+      return {
+        token: nextRefreshToken,
+        session: {
+          id: rawSession.id,
+          user_id: rawSession.user_id,
           ip_address: nextIpAddress,
           user_agent: nextUserAgent,
+          browser_id: rawSession.browser_id ?? browserId ?? null,
           expires_at: expiresAt,
-          hash: nextHash,
-          browser_id: session.browser_id ?? browserId ?? null,
+          // Quem renova precisa saber que esta renovando uma sessao de conector:
+          // e dai que sai o `aud` do proximo access token. Sem isso a rotacao
+          // devolveria um token de sessao comum e desfaria o vinculo.
+          audience: rawSession.audience ?? null,
+          oauth_client_id: rawSession.oauth_client_id ?? null,
         },
-      });
+      };
+    }
 
-      return { updateResult, newSession };
-    });
+    this.logger.warn(`[SessionRefresh] Rotation gave up after ${SessionService.REFRESH_ROTATION_ATTEMPTS} attempts: hash prefix ${hash.slice(0, 8)}`);
+    throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+  }
 
-    if (updateResult.count === 0) {
-      this.logger.warn(`[SessionRefresh] Race condition detected: userId=${session.user_id} oldSessionId=${session.id} already rotated by another request (durationMs=${Date.now() - txStart})`);
-      throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
-    }
+  /**
+   * Casa o refresh token apresentado com a sessao: pelo hash corrente, ou pelo
+   * anterior enquanto a janela de graca estiver aberta.
+   *
+   * O limite pela janela e o que impede um token antigo qualquer de ressuscitar
+   * uma sessao — so o imediatamente anterior, e so por
+   * `REFRESH_GRACE_MS`, continua servindo.
+   */
+  /**
+   * Le a sessao de um refresh token SEM rotacionar nada.
+   *
+   * Existe porque `refresh()` encontra e gira na mesma operacao: quem precisa
+   * decidir se aceita a renovacao (o client confere? o resource confere? a sessao
+   * e de conector?) so podia fazer isso depois do compare-and-swap ja commitado —
+   * e uma recusa deixava o cliente com um token morto em 30 segundos, sem nunca
+   * receber o substituto. Validar antes e a diferenca entre negar um pedido e
+   * destruir a sessao.
+   */
+  async peekByRefreshToken(refreshToken: string) {
+    if (!refreshToken) return null;
 
-    this.logger.debug(`[SessionRefresh] Rotation successful userId=${session.user_id} oldSessionId=${session.id} newSessionId=${newSession.id} durationMs=${Date.now() - txStart}`);
+    const hash = this.security.hashWithPepper(refreshToken);
+
+    return this.prisma.user_session.findFirst({
+      where: this.refreshTokenWhere(hash),
+      select: {
+        id: true,
+        user_id: true,
+        revoked_at: true,
+        expires_at: true,
+        audience: true,
+        oauth_client_id: true,
+        impersonator_user_id: true,
+      },
+    });
+  }
 
+  private refreshTokenWhere(hash: string) {
     return {
-      token: nextRefreshToken,
-      session: newSession,
+      OR: [
+        { hash },
+        { previous_hash: hash, previous_hash_expires_at: { gt: new Date() } },
+      ],
     };
   }
 
@@ -259,21 +434,20 @@ export class SessionService {
     }
 
     const hash = this.security.hashWithPepper(refreshToken);
+    // Aceita tambem o hash anterior dentro da janela de graca: sair da conta com
+    // um token que acabou de girar tem de derrubar a sessao de verdade, e nao
+    // devolver sucesso deixando-a viva.
+    const where = { revoked_at: null, ...this.refreshTokenWhere(hash) };
+
     const session = await this.prisma.user_session.findFirst({
-      where: {
-        revoked_at: null,
-        hash,
-      },
+      where,
       select: {
         user_id: true,
       },
     });
 
     const result = await this.prisma.user_session.updateMany({
-      where: {
-        revoked_at: null,
-        hash,
-      },
+      where,
       data: {
         revoked_at: new Date(),
       },
@@ -322,7 +496,7 @@ export class SessionService {
       );
 
       return {
-        data: await this.attachImpersonators(itemsWithLocation),
+        data: await this.attachOAuthClients(await this.attachImpersonators(itemsWithLocation)),
         total: paginate.total || 0,
         lastPage: Math.ceil((paginate.total || 0) / (paginate.pageSize || 1)),
         page: paginate.page ?? 1,
@@ -373,7 +547,7 @@ export class SessionService {
       );
 
       return {
-        data: await this.attachImpersonators(itemsWithLocation),
+        data: await this.attachOAuthClients(await this.attachImpersonators(itemsWithLocation)),
         total: paginate.total || 0,
         lastPage: Math.ceil((paginate.total || 0) / (paginate.pageSize || 1)),
         page: paginate.page ?? 1,
@@ -469,8 +643,11 @@ export class SessionService {
    * @param isRotation - When true, the calling flow is replacing an existing session (refresh),
    *   not adding a new one, so no extra slot needs to be freed.
    * @param currentBrowserId - The browser_id of the session being created/refreshed.
+   * @param keepSessionId - Session that must survive: its whole browser slot is
+   *   excluded from eviction. Passed by the refresh flow, so renewing a live
+   *   session can never revoke the very session being renewed.
    */
-  private async enforceSessionLimit(userId: number, maxSessions: number, isRotation = false, currentBrowserId?: string | null): Promise<void> {
+  private async enforceSessionLimit(userId: number, maxSessions: number, isRotation = false, currentBrowserId?: string | null, keepSessionId?: number): Promise<void> {
     const activeSessions = await this.prisma.user_session.findMany({
       where: {
         user_id: userId,
@@ -479,6 +656,11 @@ export class SessionService {
         // Simulacao de acesso nao consome slot: ela nasce com browser_id nulo e
         // seria contada como slot proprio, despejando uma sessao real do alvo.
         impersonator_user_id: null,
+        // Sessao de cliente OAuth externo, pelo mesmo motivo: um cliente MCP nao
+        // manda X-Browser-ID, entao cada conexao viraria um slot proprio e
+        // derrubaria um dispositivo de verdade do usuario — que so queria ligar o
+        // Claude. Conector nao e navegador.
+        audience: null,
       },
       orderBy: { created_at: 'asc' },
       select: { id: true, browser_id: true }
@@ -499,6 +681,16 @@ export class SessionService {
     const slots = Array.from(slotMap.values());
     const currentSlotCount = slots.length;
 
+    // O slot de quem esta renovando nunca entra na fila de despejo: renovar uma
+    // sessao viva nao pode derrubar a propria sessao. Sem isto, um usuario com
+    // mais slots que o limite era deslogado no proximo refresh — a rotacao
+    // revogava a si mesma e o compare-and-swap logo em seguida nao achava a
+    // linha.
+    const protectedSlot = typeof keepSessionId === 'number'
+      ? slots.find((slot) => slot.ids.includes(keepSessionId))
+      : undefined;
+    const evictable = slots.filter((slot) => slot !== protectedSlot);
+
     // A new browser slot is created only when:
     // - it's not a rotation (rotation keeps the same slot), AND
     // - the current browser doesn't already have an active slot
@@ -510,10 +702,15 @@ export class SessionService {
 
     if (slotsToRevoke > 0) {
       const sessionIdsToRevoke: number[] = [];
-      for (let i = 0; i < slotsToRevoke; i++) {
-        sessionIdsToRevoke.push(...slots[i].ids);
+      for (let i = 0; i < Math.min(slotsToRevoke, evictable.length); i++) {
+        sessionIdsToRevoke.push(...evictable[i].ids);
       }
-      this.logger.warn(`[SessionLimit] Revoking ${slotsToRevoke} oldest browser slot(s) for userId=${userId}: sessions [${sessionIdsToRevoke.join(',')}]`);
+
+      if (sessionIdsToRevoke.length === 0) {
+        return;
+      }
+
+      this.logger.warn(`[SessionLimit] Revoking ${sessionIdsToRevoke.length} session(s) in the oldest browser slot(s) for userId=${userId}: [${sessionIdsToRevoke.join(',')}]`);
       await this.prisma.user_session.updateMany({
         where: { id: { in: sessionIdsToRevoke } },
         data: { revoked_at: new Date() }

package/src/setting/favicon.controller.spec.ts

@@ -0,0 +1,92 @@
+import { NotFoundException } from '@nestjs/common';
+import { FaviconController } from './favicon.controller';
+
+const makeRes = () => {
+  const res: any = { headers: {} as Record<string, string> };
+  res.setHeader = jest.fn((k: string, v: string) => (res.headers[k] = v));
+  res.send = jest.fn((body: Buffer) => (res.body = body));
+  return res;
+};
+
+const makeController = (settings: Record<string, string>) => {
+  const setting = { getSettingValues: jest.fn().mockResolvedValue(settings) };
+  const brandAsset = {
+    resolveAssetUrl: jest.fn(async (value: string) =>
+      value.startsWith('/') ? `https://app.example.com${value}` : value,
+    ),
+  };
+  return new FaviconController(setting as any, brandAsset as any);
+};
+
+const svg = '<svg xmlns="http://www.w3.org/2000/svg"/>';
+
+describe('FaviconController', () => {
+  const originalFetch = globalThis.fetch;
+  let fetchMock: jest.Mock;
+
+  beforeEach(() => {
+    fetchMock = jest.fn().mockResolvedValue(
+      new Response(svg, { headers: { 'content-type': 'image/svg+xml' } }),
+    );
+    globalThis.fetch = fetchMock as any;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('serves the Branding icon with the origin content type', async () => {
+    const controller = makeController({ 'icon-url': '/logo.svg' });
+    const res = makeRes();
+
+    await controller.favicon(res);
+
+    expect(fetchMock.mock.calls[0][0]).toBe('https://app.example.com/logo.svg');
+    expect(res.headers['Content-Type']).toBe('image/svg+xml');
+    expect(res.body.toString()).toBe(svg);
+  });
+
+  it('falls back to image-url and caches the download', async () => {
+    const controller = makeController({ 'icon-url': '', 'image-url': '/brand.svg' });
+
+    await controller.favicon(makeRes());
+    await controller.favicon(makeRes());
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toBe('https://app.example.com/brand.svg');
+  });
+
+  it('decodes a data URI without fetching', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+    const controller = makeController({
+      'icon-url': `data:image/png;base64,${png.toString('base64')}`,
+    });
+    const res = makeRes();
+
+    await controller.favicon(res);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(res.headers['Content-Type']).toBe('image/png');
+    expect(Buffer.compare(res.body, png)).toBe(0);
+  });
+
+  it('answers 404 when the source is not an image', async () => {
+    fetchMock.mockResolvedValue(
+      new Response('<html/>', { headers: { 'content-type': 'text/html' } }),
+    );
+    const controller = makeController({ 'icon-url': '/logo.svg' });
+
+    await expect(controller.favicon(makeRes())).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+  });
+
+  it('answers 404 when nothing is configured', async () => {
+    const controller = makeController({});
+
+    await expect(controller.favicon(makeRes())).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});