@hed-hog/core 0.0.399 → 0.0.400

package/src/authorize/oauth-metadata.service.ts

@@ -0,0 +1,67 @@
+import { forwardRef, Inject, Injectable } from '@nestjs/common';
+import { SettingService } from '../setting/setting.service';
+
+/**
+ * Escopo que confina um token ao /mcp.
+ *
+ * Mora aqui, e nao no modulo mcp, porque quem decide se uma concessao e de
+ * recurso e o fluxo de autorizacao — o guard do MCP so verifica o resultado.
+ */
+export const MCP_SCOPE = 'mcp';
+
+/**
+ * Os identificadores canônicos do HedHog como OAuth provider.
+ *
+ * Existe como service, e não como constante, porque nada aqui é fixo: o mesmo
+ * código roda em produção, em dev e atrás de um túnel, e o `issuer` precisa
+ * casar exatamente com a origem de onde o cliente buscou os metadados (RFC 8414
+ * §3.3). Um valor compilado serviria a uma instalação só.
+ *
+ * `OAUTH_ISSUER` existe para o caso em que a API responde por um host diferente
+ * do que está na setting — um túnel de teste, tipicamente. Fora disso, a setting
+ * `api-url` é a fonte.
+ */
+@Injectable()
+export class OAuthMetadataService {
+  constructor(
+    @Inject(forwardRef(() => SettingService))
+    private readonly setting: SettingService,
+  ) {}
+
+  /**
+   * Sem barra final, sempre. `https://host/` e `https://host` são URIs válidas e
+   * diferentes, e a comparação de `issuer` e de `resource` é feita por igualdade
+   * de string — normalizar aqui, uma vez, evita que os dois formatos circulem.
+   */
+  async getIssuer(): Promise<string> {
+    const fromEnv = process.env.OAUTH_ISSUER?.trim();
+    if (fromEnv) return this.stripTrailingSlash(fromEnv);
+
+    const settings = await this.setting.getSettingValues(['api-url']);
+    return this.stripTrailingSlash(String(settings['api-url'] ?? ''));
+  }
+
+  /** O recurso protegido: o valor que o `aud` de um token de conector carrega. */
+  async getMcpResource(): Promise<string> {
+    return `${await this.getIssuer()}/mcp`;
+  }
+
+  /** Onde a API recebe o authorization request e redireciona para o consent. */
+  async getAuthorizationEndpoint(): Promise<string> {
+    return `${await this.getIssuer()}/auth/authorize`;
+  }
+
+  async getTokenEndpoint(): Promise<string> {
+    return `${await this.getIssuer()}/auth/token`;
+  }
+
+  /** Base da tela de consent (o admin), que é onde o usuário aprova de fato. */
+  async getConsentUiBase(): Promise<string> {
+    const settings = await this.setting.getSettingValues(['url']);
+    return this.stripTrailingSlash(String(settings['url'] ?? ''));
+  }
+
+  private stripTrailingSlash(value: string): string {
+    return value.trim().replace(/\/+$/, '');
+  }
+}

package/src/authorize/well-known.controller.spec.ts

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, jest } from '@jest/globals';
+import { OAuthMetadataService } from './oauth-metadata.service';
+import { WellKnownController } from './well-known.controller';
+
+const ISSUER = 'https://hub-api.example.com';
+
+const makeController = () => {
+  const setting = {
+    getSettingValues: jest.fn<any>().mockResolvedValue({
+      'api-url': `${ISSUER}/`, // com barra final de proposito
+      url: 'https://hub.example.com/',
+    }),
+  };
+  const metadata = new OAuthMetadataService(setting as any);
+  return { controller: new WellKnownController(metadata), setting, metadata };
+};
+
+describe('WellKnownController', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+    delete process.env.OAUTH_ISSUER;
+  });
+
+  describe('oauth-authorization-server (RFC 8414)', () => {
+    // RFC 8414 3.3: o cliente compara o issuer com a origem de onde buscou o
+    // documento. Uma barra final a mais reprova a validacao inteira.
+    it('normaliza a barra final do issuer', async () => {
+      const { controller } = makeController();
+      const doc = await controller.authorizationServer();
+
+      expect(doc.issuer).toBe(ISSUER);
+      expect(doc.authorization_endpoint).toBe(`${ISSUER}/auth/authorize`);
+      expect(doc.token_endpoint).toBe(`${ISSUER}/auth/token`);
+    });
+
+    it('anuncia so o que o servico realmente aceita', async () => {
+      const { controller } = makeController();
+      const doc = await controller.authorizationServer();
+
+      // O AuthorizeService rejeita code_challenge_method != S256 e client_type
+      // != public. Anunciar mais do que isso seria mentir para o cliente.
+      expect(doc.code_challenge_methods_supported).toEqual(['S256']);
+      expect(doc.token_endpoint_auth_methods_supported).toEqual(['none']);
+      expect(doc.response_types_supported).toEqual(['code']);
+      expect(doc.grant_types_supported).toContain('refresh_token');
+      expect(doc.authorization_response_iss_parameter_supported).toBe(true);
+    });
+
+    it('serve o mesmo documento no caminho com sufixo /mcp', async () => {
+      const { controller } = makeController();
+      expect(await controller.authorizationServerMcp()).toEqual(
+        await controller.authorizationServer(),
+      );
+    });
+  });
+
+  describe('oauth-protected-resource (RFC 9728)', () => {
+    it('aponta o recurso e o authorization server', async () => {
+      const { controller } = makeController();
+      const doc = await controller.protectedResource();
+
+      expect(doc.resource).toBe(`${ISSUER}/mcp`);
+      expect(doc.authorization_servers).toEqual([ISSUER]);
+      expect(doc.scopes_supported).toEqual(['mcp']);
+    });
+
+    it('serve o mesmo documento no caminho com sufixo /mcp', async () => {
+      const { controller } = makeController();
+      expect(await controller.protectedResourceMcp()).toEqual(
+        await controller.protectedResource(),
+      );
+    });
+  });
+
+  // Existe para o caso de a API responder por um host diferente do da setting —
+  // um tunel de teste, tipicamente.
+  it('OAUTH_ISSUER vence a setting', async () => {
+    process.env.OAUTH_ISSUER = 'https://tunel.example.com/';
+    const { controller } = makeController();
+    const doc = await controller.authorizationServer();
+
+    expect(doc.issuer).toBe('https://tunel.example.com');
+  });
+});

package/src/authorize/well-known.controller.ts

@@ -0,0 +1,96 @@
+import { Public } from '@hed-hog/api';
+import { Controller, Get, Header } from '@nestjs/common';
+import { OAuthMetadataService } from './oauth-metadata.service';
+
+/**
+ * Descoberta OAuth: como um cliente que só conhece a URL do recurso chega até o
+ * authorization server.
+ *
+ * Servido na raiz do host da API. Não há `setGlobalPrefix` no `main.ts`, e o
+ * middleware de compatibilidade de lá só remove um `/api` *inicial* — então
+ * `/.well-known/...` chega aqui intacto.
+ *
+ * Os paths são todos literais de propósito: com Express 5 (path-to-regexp v8) uma
+ * rota curinga derruba o boot da aplicação.
+ *
+ * Não servimos `/.well-known/openid-configuration`: não somos OIDC. Não há
+ * `id_token` nem JWKS (a assinatura é HS256, com segredo simétrico), e anunciar
+ * OIDC faria clientes procurarem endpoints que não existem.
+ */
+@Public()
+@Controller('.well-known')
+export class WellKnownController {
+  constructor(private readonly metadata: OAuthMetadataService) {}
+
+  /**
+   * RFC 9728. O par sem sufixo e o com `/mcp` devolvem o mesmo documento: a RFC
+   * manda inserir o path do recurso depois do `.well-known`, mas clientes
+   * divergem, e responder aos dois custa uma linha.
+   */
+  @Get('oauth-protected-resource')
+  @Header('Cache-Control', 'public, max-age=3600')
+  async protectedResource() {
+    return this.buildProtectedResource();
+  }
+
+  @Get('oauth-protected-resource/mcp')
+  @Header('Cache-Control', 'public, max-age=3600')
+  async protectedResourceMcp() {
+    return this.buildProtectedResource();
+  }
+
+  /** RFC 8414. */
+  @Get('oauth-authorization-server')
+  @Header('Cache-Control', 'public, max-age=3600')
+  async authorizationServer() {
+    return this.buildAuthorizationServer();
+  }
+
+  @Get('oauth-authorization-server/mcp')
+  @Header('Cache-Control', 'public, max-age=3600')
+  async authorizationServerMcp() {
+    return this.buildAuthorizationServer();
+  }
+
+  private async buildProtectedResource() {
+    const [issuer, resource] = await Promise.all([
+      this.metadata.getIssuer(),
+      this.metadata.getMcpResource(),
+    ]);
+
+    return {
+      resource,
+      authorization_servers: [issuer],
+      scopes_supported: ['mcp'],
+      bearer_methods_supported: ['header'],
+      resource_name: 'HedHog Hub MCP',
+    };
+  }
+
+  private async buildAuthorizationServer() {
+    const [issuer, authorizationEndpoint, tokenEndpoint] = await Promise.all([
+      this.metadata.getIssuer(),
+      this.metadata.getAuthorizationEndpoint(),
+      this.metadata.getTokenEndpoint(),
+    ]);
+
+    return {
+      // RFC 8414 §3.3: o cliente compara este valor com a origem de onde buscou o
+      // documento. Uma barra final a mais reprova a validação inteira — por isso
+      // o OAuthMetadataService normaliza na entrada, e não aqui.
+      issuer,
+      authorization_endpoint: authorizationEndpoint,
+      token_endpoint: tokenEndpoint,
+      scopes_supported: ['mcp', 'profile', 'vaults'],
+      response_types_supported: ['code'],
+      response_modes_supported: ['query'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      // Só clientes públicos: `AuthorizeService.exchangeCode` recusa qualquer
+      // `client_type` diferente de 'public', e não existe client_secret no modelo.
+      token_endpoint_auth_methods_supported: ['none'],
+      // `plain` é rejeitado pelo serviço, então não anunciamos.
+      code_challenge_methods_supported: ['S256'],
+      authorization_response_iss_parameter_supported: true,
+    };
+  }
+}

package/src/captcha/captcha.service.spec.ts

@@ -18,9 +18,15 @@ describe('CaptchaService', () => {
     jest.restoreAllMocks();
   });
 
-  function mockFetch(success: boolean) {
+  function mockFetch(
+    success: boolean,
+    extra: Record<string, unknown> = {},
+    init: { ok?: boolean } = {},
+  ) {
     (global.fetch as jest.Mock).mockResolvedValue({
-      json: async () => ({ success }),
+      ok: init.ok ?? true,
+      status: init.ok === false ? 502 : 200,
+      json: async () => ({ success, ...extra }),
     });
   }
 
@@ -38,6 +44,15 @@ describe('CaptchaService', () => {
       ).rejects.toThrow('Unsupported CAPTCHA provider: hcaptcha.');
     });
 
+    it('rejects an oversized token before calling the provider', async () => {
+      await expect(
+        service.verify('t'.repeat(2049), 'cloudflare-turnstile', {
+          secret_key: 'secret',
+        }),
+      ).rejects.toThrow('CAPTCHA token is malformed.');
+      expect(global.fetch).not.toHaveBeenCalled();
+    });
+
     describe('recaptcha', () => {
       it('accepts a token the provider confirms', async () => {
         mockFetch(true);
@@ -78,6 +93,128 @@ describe('CaptchaService', () => {
           service.verify('token', 'cloudflare-turnstile', { secret_key: 's' }),
         ).rejects.toThrow('CAPTCHA validation failed.');
       });
+
+      it('sends the visitor ip as remoteip', async () => {
+        mockFetch(true);
+        await service.verify(
+          'token',
+          'cloudflare-turnstile',
+          { secret_key: 'secret' },
+          { remoteIp: '203.0.113.7' },
+        );
+
+        const [, init] = (global.fetch as jest.Mock).mock.calls[0];
+        expect(String(init.body)).toContain('remoteip=203.0.113.7');
+        expect(init.signal).toBeDefined();
+      });
+
+      it('omits remoteip when the caller does not know the ip', async () => {
+        mockFetch(true);
+        await service.verify('token', 'cloudflare-turnstile', {
+          secret_key: 'secret',
+        });
+
+        const [, init] = (global.fetch as jest.Mock).mock.calls[0];
+        expect(String(init.body)).not.toContain('remoteip');
+      });
+
+      // Um soluco do provedor tem que virar falha de captcha, nunca 500.
+      it('treats a non-2xx response as a failed challenge', async () => {
+        mockFetch(true, {}, { ok: false });
+        await expect(
+          service.verify('token', 'cloudflare-turnstile', { secret_key: 's' }),
+        ).rejects.toThrow('CAPTCHA validation failed.');
+      });
+
+      it('treats a body that is not json as a failed challenge', async () => {
+        (global.fetch as jest.Mock).mockResolvedValue({
+          ok: true,
+          status: 200,
+          json: async () => {
+            throw new Error('Unexpected token < in JSON');
+          },
+        });
+
+        await expect(
+          service.verify('token', 'cloudflare-turnstile', { secret_key: 's' }),
+        ).rejects.toBeInstanceOf(BadRequestException);
+      });
+
+      it('treats a network failure as a failed challenge', async () => {
+        (global.fetch as jest.Mock).mockRejectedValue(
+          new Error('The operation was aborted due to timeout'),
+        );
+
+        await expect(
+          service.verify('token', 'cloudflare-turnstile', { secret_key: 's' }),
+        ).rejects.toThrow('CAPTCHA validation failed.');
+      });
+
+      it('rejects a token solved for another action', async () => {
+        mockFetch(true, { action: 'newsletter' });
+        await expect(
+          service.verify(
+            'token',
+            'cloudflare-turnstile',
+            { secret_key: 's' },
+            { expectedAction: 'contact' },
+          ),
+        ).rejects.toThrow('CAPTCHA validation failed.');
+      });
+
+      it('accepts the matching action', async () => {
+        mockFetch(true, { action: 'contact' });
+        await expect(
+          service.verify(
+            'token',
+            'cloudflare-turnstile',
+            { secret_key: 's' },
+            { expectedAction: 'contact' },
+          ),
+        ).resolves.toBeUndefined();
+      });
+
+      // Bundle antigo em cache nao manda action; exigir aqui derrubaria envios
+      // legitimos durante a janela de deploy.
+      it('accepts a response without an action', async () => {
+        mockFetch(true);
+        await expect(
+          service.verify(
+            'token',
+            'cloudflare-turnstile',
+            { secret_key: 's' },
+            { expectedAction: 'contact' },
+          ),
+        ).resolves.toBeUndefined();
+      });
+
+      it('rejects a hostname outside the profile allowlist', async () => {
+        mockFetch(true, { hostname: 'phishing.example' });
+        await expect(
+          service.verify('token', 'cloudflare-turnstile', {
+            secret_key: 's',
+            hostnames: 'hcode.com.br, www.hcode.com.br',
+          }),
+        ).rejects.toThrow('CAPTCHA validation failed.');
+      });
+
+      it('accepts a hostname in the allowlist, ignoring case and spacing', async () => {
+        mockFetch(true, { hostname: 'WWW.Hcode.com.br' });
+        await expect(
+          service.verify('token', 'cloudflare-turnstile', {
+            secret_key: 's',
+            hostnames: 'hcode.com.br, www.hcode.com.br',
+          }),
+        ).resolves.toBeUndefined();
+      });
+
+      // Perfil sem `hostnames` e o caso de todo perfil ja existente.
+      it('skips the hostname check when the profile has no allowlist', async () => {
+        mockFetch(true, { hostname: 'anything.example' });
+        await expect(
+          service.verify('token', 'cloudflare-turnstile', { secret_key: 's' }),
+        ).resolves.toBeUndefined();
+      });
     });
 
     describe('altcha', () => {
@@ -148,8 +285,62 @@ describe('CaptchaService', () => {
       );
     });
 
-    it('refuses when no profile id is configured', async () => {
-      await expect(service.verifyForProfile(null, 'token')).rejects.toThrow(
+    it('forwards the verification context to the provider', async () => {
+      prisma.integration_profile.findFirst.mockResolvedValue({
+        config: { secret_key: 'secret', hostnames: 'hcode.com.br' },
+        integration_provider: { slug: 'cloudflare-turnstile' },
+      });
+      mockFetch(true, { action: 'newsletter', hostname: 'hcode.com.br' });
+
+      await expect(
+        service.verifyForProfile(8, 'token', {
+          remoteIp: '203.0.113.7',
+          expectedAction: 'newsletter',
+        }),
+      ).resolves.toBeUndefined();
+
+      const [, init] = (global.fetch as jest.Mock).mock.calls[0];
+      expect(String(init.body)).toContain('remoteip=203.0.113.7');
+    });
+
+    // Settings escolhidas pelo entity-picker do admin guardam o slug do perfil,
+    // não o id: sem isto o captcha do "avise-me quando chegar" falhava fechado
+    // assim que alguém escolhia o perfil pela tela.
+    it('resolves the profile by slug when the caller holds a setting value', async () => {
+      prisma.integration_profile.findFirst.mockResolvedValue({
+        config: { secret_key: 'secret' },
+        integration_provider: { slug: 'recaptcha' },
+      });
+      mockFetch(true);
+
+      await expect(
+        service.verifyForProfile('recaptcha-loja', 'token'),
+      ).resolves.toBeUndefined();
+      expect(prisma.integration_profile.findFirst).toHaveBeenCalledWith(
+        expect.objectContaining({ where: { slug: 'recaptcha-loja' } }),
+      );
+    });
+
+    it('still treats a numeric string as an id', async () => {
+      prisma.integration_profile.findFirst.mockResolvedValue({
+        config: { secret_key: 'secret' },
+        integration_provider: { slug: 'recaptcha' },
+      });
+      mockFetch(true);
+
+      await expect(service.verifyForProfile('7', 'token')).resolves.toBeUndefined();
+      expect(prisma.integration_profile.findFirst).toHaveBeenCalledWith(
+        expect.objectContaining({ where: { id: 7 } }),
+      );
+    });
+
+    it.each([
+      ['null', null],
+      ['empty string', ''],
+      // `'0'` é o default herdado das settings antigas: não é id de ninguém.
+      ['the legacy zero', '0'],
+    ])('refuses when no profile is configured (%s)', async (_case, value) => {
+      await expect(service.verifyForProfile(value, 'token')).rejects.toThrow(
         'CAPTCHA is enabled but no integration profile is configured.',
       );
     });
@@ -207,4 +398,20 @@ describe('CaptchaService', () => {
       expect(CaptchaService.extractSiteKey(null)).toBeNull();
     });
   });
+
+  describe('parseHostnames', () => {
+    it('splits, trims and lowercases the allowlist', () => {
+      expect(
+        CaptchaService.parseHostnames({
+          hostnames: ' hcode.com.br , WWW.hcode.com.br ,, ',
+        }),
+      ).toEqual(new Set(['hcode.com.br', 'www.hcode.com.br']));
+    });
+
+    it('returns an empty set when the profile has no allowlist', () => {
+      expect(CaptchaService.parseHostnames({}).size).toBe(0);
+      expect(CaptchaService.parseHostnames(null).size).toBe(0);
+      expect(CaptchaService.parseHostnames({ hostnames: '  ' }).size).toBe(0);
+    });
+  });
 });