@hed-hog/core 0.0.387 → 0.0.390

package/src/integration-profile/testers/infrastructure.testers.ts

@@ -0,0 +1,122 @@
+import axios from 'axios';
+import { Agent } from 'node:https';
+import {
+  assertHttpUrl,
+  describeHttpError,
+  fail,
+  pass,
+  probeJson,
+  requireFields,
+  str,
+} from './http-probe';
+import { IntegrationTester } from './integration-tester.types';
+
+/**
+ * Testadores dos providers de infraestrutura (autoscaling).
+ *
+ * DUPLICAÇÃO INTENCIONAL: `libraries/queue/src/scaling/{digital-ocean,kubernetes-scaler}
+ * .service.ts` têm um `testCredentials` equivalente, batendo nos mesmos endpoints.
+ * Não dá para reaproveitar: `@hed-hog-pro/queue` depende do core, então o core não pode
+ * importá-lo de volta — e os providers `digitalocean`/`kubernetes` são semeados por uma
+ * migration do core, existindo mesmo em instalações sem o pacote da fila. Registrar o
+ * tester pela queue deixaria o botão quebrado nessas instalações. Se mudar um endpoint
+ * aqui, olhe o outro lado também.
+ */
+
+const digitalOceanTester: IntegrationTester = {
+  providerSlug: 'digitalocean',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['api_token', 'API token'],
+      ['cluster_id', 'Cluster ID'],
+    ]);
+    if (missing) return missing;
+
+    const token = String(config.api_token ?? '');
+    const clusterId = str(config, 'cluster_id');
+    const result = await probeJson(
+      `https://api.digitalocean.com/v2/kubernetes/clusters/${encodeURIComponent(clusterId)}`,
+      { headers: { Authorization: `Bearer ${token}` } },
+      ctx.signal,
+    );
+
+    if (result.status === 401) return fail('Invalid DigitalOcean API token.');
+    if (result.status === 403) {
+      return fail('This token has no permission to read Kubernetes clusters.');
+    }
+    if (result.status === 404) {
+      return fail(`Cluster "${clusterId}" was not found in this account.`);
+    }
+    if (!result.ok) {
+      return fail(describeHttpError(result, 'DigitalOcean rejected the request.'));
+    }
+
+    const cluster = result.body?.kubernetes_cluster ?? {};
+    const label = `${cluster.name ?? clusterId} (${cluster.region ?? str(config, 'region')})`;
+
+    // O pool de vídeo é escolhido por nome; se ele sumiu do cluster, o autoscaling
+    // falha silenciosamente depois — melhor avisar agora.
+    const poolName = str(config, 'video_node_pool_name');
+    if (poolName) {
+      const pools: Array<{ name?: string }> = Array.isArray(cluster.node_pools)
+        ? cluster.node_pools
+        : [];
+      if (pools.length > 0 && !pools.some((pool) => pool.name === poolName)) {
+        return pass(label, `The node pool "${poolName}" no longer exists in this cluster.`);
+      }
+    }
+    return pass(label);
+  },
+};
+
+const kubernetesTester: IntegrationTester = {
+  providerSlug: 'kubernetes',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['api_server', 'API server'],
+      ['token', 'Token'],
+    ]);
+    if (missing) return missing;
+
+    const apiServer = assertHttpUrl(str(config, 'api_server'), 'API server');
+    const caCert = String(config.ca_cert ?? '').trim();
+
+    // Não usamos `fetch` aqui: o CA do cluster é quase sempre privado e a API de fetch
+    // não aceita um contexto TLS customizado.
+    const httpsAgent = new Agent(
+      caCert ? { ca: caCert } : { rejectUnauthorized: false },
+    );
+
+    try {
+      const response = await axios.get(`${apiServer.origin}/version`, {
+        headers: { Authorization: `Bearer ${String(config.token ?? '')}` },
+        httpsAgent,
+        signal: ctx.signal,
+        validateStatus: () => true,
+      });
+
+      if (response.status === 401) return fail('The Kubernetes token was rejected.');
+      if (response.status === 403) {
+        return fail('This token has no permission to read the cluster version.');
+      }
+      if (response.status >= 400) {
+        return fail(`The Kubernetes API returned HTTP ${response.status}.`);
+      }
+
+      const version = String(response.data?.gitVersion ?? '').trim();
+      return caCert
+        ? pass(`${apiServer.host}${version ? ` — ${version}` : ''}`)
+        : pass(
+            `${apiServer.host}${version ? ` — ${version}` : ''}`,
+            'No CA certificate provided: the TLS certificate was not verified.',
+          );
+    } finally {
+      httpsAgent.destroy();
+    }
+  },
+};
+
+export const INFRASTRUCTURE_TESTERS: IntegrationTester[] = [
+  digitalOceanTester,
+  kubernetesTester,
+];

package/src/integration-profile/testers/integration-tester.registry.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { IntegrationTesterRegistry } from './integration-tester.registry';
+import { IntegrationTester } from './integration-tester.types';
+
+function makeTester(providerSlug: string, info = 'ok'): IntegrationTester {
+  return {
+    providerSlug,
+    test: async () => ({ ok: true, info }),
+  };
+}
+
+describe('IntegrationTesterRegistry', () => {
+  it('registra e recupera um tester pelo slug do provider', () => {
+    const registry = new IntegrationTesterRegistry();
+    const tester = makeTester('smtp');
+
+    registry.register(tester);
+
+    expect(registry.find('smtp')).toBe(tester);
+    expect(registry.has('smtp')).toBe(true);
+    expect(registry.list()).toEqual(['smtp']);
+  });
+
+  it('normaliza o slug (case e espaços) na escrita e na leitura', () => {
+    const registry = new IntegrationTesterRegistry();
+    registry.register(makeTester('  S3-Compatible '));
+
+    expect(registry.find('s3-compatible')).not.toBeNull();
+    expect(registry.find('S3-COMPATIBLE')).not.toBeNull();
+  });
+
+  it('devolve null para provider desconhecido, nulo ou vazio', () => {
+    const registry = new IntegrationTesterRegistry();
+
+    expect(registry.find('inexistente')).toBeNull();
+    expect(registry.find(null)).toBeNull();
+    expect(registry.find(undefined)).toBeNull();
+    expect(registry.find('')).toBeNull();
+    expect(registry.has('inexistente')).toBe(false);
+  });
+
+  it('avisa ao sobrescrever um tester já registrado, mas aceita a substituição', () => {
+    const registry = new IntegrationTesterRegistry();
+    const warn = jest
+      .spyOn((registry as any).logger, 'warn')
+      .mockImplementation(() => undefined);
+
+    const first = makeTester('stripe', 'primeiro');
+    const second = makeTester('stripe', 'segundo');
+    registry.register(first);
+    registry.register(second);
+
+    expect(warn).toHaveBeenCalledWith(
+      'Integration tester for provider "stripe" was overwritten.',
+    );
+    expect(registry.find('stripe')).toBe(second);
+  });
+
+  it('recusa um tester sem providerSlug', () => {
+    const registry = new IntegrationTesterRegistry();
+
+    expect(() => registry.register({} as IntegrationTester)).toThrow(
+      'Integration tester requires a providerSlug.',
+    );
+  });
+
+  it('lista os providers registrados em ordem alfabética', () => {
+    const registry = new IntegrationTesterRegistry();
+    ['stripe', 'azure-blob', 'openai'].forEach((slug) =>
+      registry.register(makeTester(slug)),
+    );
+
+    expect(registry.list()).toEqual(['azure-blob', 'openai', 'stripe']);
+  });
+});

package/src/integration-profile/testers/integration-tester.registry.ts

@@ -0,0 +1,43 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { IntegrationTester } from './integration-tester.types';
+
+/**
+ * Registro dos testadores de conexão, no mesmo padrão do WebhookProtocolRegistry e do
+ * FiscalProviderRegistry: os testers embutidos entram no boot do IntegrationProfileModule
+ * e libraries externas registram os seus (é assim que a `fiscal` pluga o nfse-national,
+ * que precisa abrir o certificado A1 — código que não pode viver no core).
+ */
+@Injectable()
+export class IntegrationTesterRegistry {
+  private readonly logger = new Logger(IntegrationTesterRegistry.name);
+  private readonly testers = new Map<string, IntegrationTester>();
+
+  register(tester: IntegrationTester): void {
+    const key = normalizeSlug(tester?.providerSlug);
+    if (!key) throw new Error('Integration tester requires a providerSlug.');
+
+    if (this.testers.has(key)) {
+      this.logger.warn(`Integration tester for provider "${key}" was overwritten.`);
+    }
+
+    this.testers.set(key, tester);
+  }
+
+  find(providerSlug: string | null | undefined): IntegrationTester | null {
+    const key = normalizeSlug(providerSlug);
+    return key ? (this.testers.get(key) ?? null) : null;
+  }
+
+  has(providerSlug: string | null | undefined): boolean {
+    return this.find(providerSlug) !== null;
+  }
+
+  /** Providers com teste disponível (para a UI decidir se mostra o botão). */
+  list(): string[] {
+    return [...this.testers.keys()].sort();
+  }
+}
+
+function normalizeSlug(slug: string | null | undefined): string {
+  return String(slug ?? '').trim().toLowerCase();
+}

package/src/integration-profile/testers/integration-tester.types.ts

@@ -0,0 +1,61 @@
+/**
+ * Contrato dos testadores de conexão dos Perfis de Integração.
+ *
+ * Cada provider (smtp, s3, stripe, google-oauth, …) implementa um `IntegrationTester`
+ * que faz uma chamada verificável contra o serviço real e devolve um veredito. O
+ * `IntegrationProfileService.test()` só despacha; nenhum `if (provider === 'x')` sobra lá.
+ *
+ * Os testers são objetos literais sem estado (mesmo estilo de integration-profile.utils.ts),
+ * não providers do Nest: assim cada spec é um teste puro de função com `fetch` mockado.
+ */
+
+/** Timeout padrão de um teste de conexão. */
+export const INTEGRATION_TEST_TIMEOUT_MS = 10_000;
+
+export type IntegrationTestOutcome = {
+  ok: boolean;
+  /**
+   * Evidência legível do que foi verificado (nome do bucket, da conta, do cluster…).
+   * NUNCA pode conter segredo: vai para a UI e é gravada no config do perfil.
+   */
+  info?: string;
+  /** Motivo legível da falha. NUNCA contém segredo nem stack trace. */
+  error?: string;
+  /**
+   * Credencial válida, mas algo secundário não pôde ser comprovado (domínio não
+   * verificado, service account sem acesso ao app, pool inexistente). Não reprova.
+   */
+  warning?: string;
+};
+
+export type IntegrationTestContext = {
+  /** Já combinado com o timeout do tester. Repassar a TODA chamada de rede. */
+  signal: AbortSignal;
+  /** Slug do integration_type (email, storage, oauth, …). */
+  typeSlug: string;
+  /** Slug do provider sendo testado. */
+  providerSlug: string;
+  /**
+   * Valores dos segredos deste perfil, usados só para redigir mensagens de erro
+   * (algumas APIs ecoam a entrada de volta). Nunca logar nem devolver.
+   */
+  secretValues: string[];
+};
+
+export interface IntegrationTester {
+  /** Slug do integration_provider que esta implementação atende. */
+  readonly providerSlug: string;
+  /** Timeout específico deste provider (default INTEGRATION_TEST_TIMEOUT_MS). */
+  readonly timeoutMs?: number;
+  /**
+   * `config` chega DECIFRADO e já mesclado com os segredos armazenados
+   * ("deixe em branco para manter"), então o tester nunca vê a máscara.
+   *
+   * Não deve lançar: devolve `{ ok: false, error }`. Exceções que escaparem viram
+   * `ok: false` com a mensagem sanitizada no dispatcher.
+   */
+  test(
+    config: Record<string, unknown>,
+    ctx: IntegrationTestContext,
+  ): Promise<IntegrationTestOutcome>;
+}

package/src/integration-profile/testers/messaging.testers.ts

@@ -0,0 +1,102 @@
+import { buildWhatsappOfficialConfigFromIntegration } from '../integration-profile.utils';
+import {
+  assertHttpUrl,
+  describeHttpError,
+  fail,
+  pass,
+  probeJson,
+  requireFields,
+  str,
+} from './http-probe';
+import { IntegrationTester } from './integration-tester.types';
+
+const evolutionApiTester: IntegrationTester = {
+  providerSlug: 'evolution-api',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['host', 'Evolution API host'],
+      ['token', 'Evolution API token'],
+      ['instance_name', 'Instance name'],
+    ]);
+    if (missing) return missing;
+
+    const base = assertHttpUrl(str(config, 'host'), 'Evolution API host');
+    const instance = str(config, 'instance_name');
+    const url = `${base.origin}/instance/connectionState/${encodeURIComponent(instance)}`;
+
+    const result = await probeJson(
+      url,
+      { headers: { apikey: String(config.token ?? '') } },
+      ctx.signal,
+    );
+
+    if (result.status === 401 || result.status === 403) {
+      return fail('Invalid Evolution API token.');
+    }
+    if (result.status === 404) {
+      return fail(`Instance "${instance}" was not found on this Evolution API server.`);
+    }
+    if (!result.ok) {
+      return fail(describeHttpError(result, 'Evolution API rejected the request.'));
+    }
+
+    const state = String(
+      result.body?.instance?.state ?? result.body?.state ?? '',
+    ).trim();
+
+    // Credencial válida mas sessão desconectada: o perfil está certo e o QR code é
+    // outro problema — avisar sem reprovar.
+    if (state && state !== 'open') {
+      return pass(
+        `${instance} — ${state}`,
+        `The instance is not connected (state: ${state}). Scan the QR code in Evolution API.`,
+      );
+    }
+    return pass(`${instance}${state ? ` — ${state}` : ''}`);
+  },
+};
+
+/**
+ * Valida um perfil whatsapp-official contra a Graph API (lê o WABA com o token).
+ * Nunca devolve o token/secret na resposta.
+ */
+const whatsappOfficialTester: IntegrationTester = {
+  providerSlug: 'whatsapp-official',
+  test: async (config, ctx) => {
+    const cfg = buildWhatsappOfficialConfigFromIntegration(config);
+
+    if (!cfg.accessToken) return fail('WhatsApp access token is required.');
+    if (!cfg.wabaId) return fail('WhatsApp Business Account ID is required.');
+    if (!cfg.appSecret) {
+      return fail('Meta App Secret is required to validate webhook signatures.');
+    }
+    if (!cfg.verifyToken) return fail('Webhook verify token is required.');
+
+    const url = `https://graph.facebook.com/${cfg.graphApiVersion}/${encodeURIComponent(
+      cfg.wabaId,
+    )}?fields=id,name`;
+
+    const result = await probeJson(
+      url,
+      { headers: { Authorization: `Bearer ${cfg.accessToken}` } },
+      ctx.signal,
+    );
+
+    if (!result.ok) {
+      // A mensagem da Meta não contém o token; ainda assim só propagamos o texto dela.
+      return fail(
+        `WhatsApp validation failed: ${describeHttpError(
+          result,
+          'Graph API rejected the request.',
+        )}`,
+      );
+    }
+
+    return pass(String(result.body?.name ?? '') || cfg.wabaId);
+  },
+};
+
+export const MESSAGING_TESTERS: IntegrationTester[] = [
+  evolutionApiTester,
+  whatsappOfficialTester,
+];

package/src/integration-profile/testers/oauth.testers.spec.ts

@@ -0,0 +1,220 @@
+import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { OAUTH_TESTERS } from './oauth.testers';
+import { IntegrationTestContext, IntegrationTester } from './integration-tester.types';
+
+const bySlug = (slug: string): IntegrationTester =>
+  OAUTH_TESTERS.find((tester) => tester.providerSlug === slug)!;
+
+const ctx = (): IntegrationTestContext => ({
+  signal: AbortSignal.timeout(5_000),
+  typeSlug: 'oauth',
+  providerSlug: 'test',
+  secretValues: [],
+});
+
+/** Resposta JSON crua, como `probeJson` a consome (via response.text()). */
+function jsonResponse(body: unknown, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response;
+}
+
+let fetchMock: jest.Mock;
+
+beforeEach(() => {
+  fetchMock = jest.fn();
+  global.fetch = fetchMock as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe('google-oauth tester', () => {
+  const tester = bySlug('google-oauth');
+
+  it('aprova quando o Google recusa apenas o código de teste (invalid_grant)', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ error: 'invalid_grant' }, 400));
+
+    const outcome = await tester.test(
+      { client_id: 'id', client_secret: 'secret' },
+      ctx(),
+    );
+
+    expect(outcome.ok).toBe(true);
+  });
+
+  it('reprova quando o Google recusa as credenciais do app (invalid_client)', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ error: 'invalid_client' }, 401));
+
+    const outcome = await tester.test(
+      { client_id: 'id', client_secret: 'wrong' },
+      ctx(),
+    );
+
+    expect(outcome).toEqual({
+      ok: false,
+      error: 'Invalid Client ID or Client secret.',
+    });
+  });
+
+  it('reprova sem ir à rede quando falta uma credencial', async () => {
+    const outcome = await tester.test({ client_id: 'id' }, ctx());
+
+    expect(outcome.ok).toBe(false);
+    expect(outcome.error).toBe('Client secret is required.');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('github-oauth tester', () => {
+  const tester = bySlug('github-oauth');
+
+  it('aprova em bad_verification_code e reprova em incorrect_client_credentials', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ error: 'bad_verification_code' }),
+    );
+    await expect(
+      tester.test({ client_id: 'a', client_secret: 'b' }, ctx()),
+    ).resolves.toMatchObject({ ok: true });
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ error: 'incorrect_client_credentials' }),
+    );
+    await expect(
+      tester.test({ client_id: 'a', client_secret: 'b' }, ctx()),
+    ).resolves.toMatchObject({ ok: false });
+  });
+});
+
+describe('facebook-oauth tester', () => {
+  const tester = bySlug('facebook-oauth');
+
+  it('aprova quando recebe um app token real', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ access_token: 'app-token' }));
+
+    await expect(
+      tester.test({ client_id: 'a', client_secret: 'b' }, ctx()),
+    ).resolves.toMatchObject({ ok: true });
+  });
+
+  it('reprova quando a Meta rejeita', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse({ error: { message: 'Invalid appsecret' } }, 400),
+    );
+
+    await expect(
+      tester.test({ client_id: 'a', client_secret: 'b' }, ctx()),
+    ).resolves.toMatchObject({ ok: false, error: 'Invalid appsecret' });
+  });
+});
+
+describe('microsoft-oauth tester', () => {
+  const tester = bySlug('microsoft-oauth');
+
+  it('aprova quando o client_credentials devolve token', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ access_token: 'token' }));
+
+    const outcome = await tester.test(
+      { client_id: 'a', client_secret: 'b', tenant_id: 'contoso' },
+      ctx(),
+    );
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.info).toContain('contoso');
+  });
+
+  it.each([
+    ['AADSTS7000215', 'Invalid client secret.'],
+    ['AADSTS700016', 'Application not found in tenant "contoso".'],
+    ['AADSTS90002', 'Tenant "contoso" does not exist.'],
+    ['AADSTS7000222', 'The client secret has expired.'],
+  ])('traduz %s numa mensagem acionável', async (code, expected) => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        {
+          error: 'invalid_client',
+          error_description: `${code}: long Microsoft blurb with correlation id and a help URL`,
+        },
+        401,
+      ),
+    );
+
+    const outcome = await tester.test(
+      { client_id: 'a', client_secret: 'b', tenant_id: 'contoso' },
+      ctx(),
+    );
+
+    expect(outcome).toEqual({ ok: false, error: expected });
+  });
+
+  it('sem tenant_id, não reprova o app quando o endpoint "common" recusa client_credentials', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        { error_description: 'AADSTS900023: tenant common is not supported' },
+        400,
+      ),
+    );
+
+    const outcome = await tester.test({ client_id: 'a', client_secret: 'b' }, ctx());
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.warning).toContain('Tenant ID');
+  });
+
+  it('está registrado também para microsoft-entra-id-oauth', () => {
+    expect(bySlug('microsoft-entra-id-oauth')).toBeDefined();
+  });
+});
+
+describe('apple-oauth tester', () => {
+  const tester = bySlug('apple-oauth');
+
+  it('reprova sem ir à rede quando a chave .p8 não assina', async () => {
+    const outcome = await tester.test(
+      {
+        client_id: 'com.acme.service',
+        team_id: 'TEAM123',
+        key_id: 'KEY123',
+        private_key: 'não é uma chave EC válida',
+      },
+      ctx(),
+    );
+
+    expect(outcome.ok).toBe(false);
+    expect(outcome.error).toContain('Could not sign with the private key');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('linkedin-oauth tester', () => {
+  const tester = bySlug('linkedin-oauth');
+
+  it('aprova quando o LinkedIn só reclama do código', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        { error: 'invalid_request', error_description: 'Bad authorization code' },
+        400,
+      ),
+    );
+
+    await expect(
+      tester.test({ client_id: 'a', client_secret: 'b' }, ctx()),
+    ).resolves.toMatchObject({ ok: true });
+  });
+
+  it('reprova quando o LinkedIn reclama do client', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        { error: 'invalid_client', error_description: 'Client authentication failed' },
+        401,
+      ),
+    );
+
+    await expect(
+      tester.test({ client_id: 'a', client_secret: 'b' }, ctx()),
+    ).resolves.toMatchObject({ ok: false });
+  });
+});