@hed-hog/core 0.0.387 → 0.0.393

package/src/integration-profile/testers/http-probe.ts

@@ -0,0 +1,171 @@
+/**
+ * Utilidades compartilhadas pelos testadores de conexão.
+ *
+ * Concentra as três coisas que todo tester precisa acertar e que são fáceis de errar
+ * caso a caso: respeitar o timeout, não vazar segredo na mensagem de erro e traduzir
+ * falha de rede em texto que o operador entenda.
+ */
+import { IntegrationTestOutcome } from './integration-tester.types';
+
+/** Tamanho máximo de uma mensagem devolvida à UI (ela também é persistida no config). */
+const MAX_ERROR_LENGTH = 300;
+
+/** Atalho para um veredito de sucesso. */
+export function pass(info?: string, warning?: string): IntegrationTestOutcome {
+  return { ok: true, ...(info ? { info } : {}), ...(warning ? { warning } : {}) };
+}
+
+/** Atalho para um veredito de falha. */
+export function fail(error: string): IntegrationTestOutcome {
+  return { ok: false, error };
+}
+
+/**
+ * Exige que um campo esteja preenchido. Devolve `null` quando está tudo certo, ou o
+ * veredito de falha pronto — evita repetir o mesmo `if` em 31 testers.
+ */
+export function requireFields(
+  config: Record<string, unknown>,
+  fields: Array<[key: string, label: string]>,
+): IntegrationTestOutcome | null {
+  for (const [key, label] of fields) {
+    if (!String(config[key] ?? '').trim()) {
+      return fail(`${label} is required.`);
+    }
+  }
+  return null;
+}
+
+/** Lê uma chave do config como string já trimada. */
+export function str(config: Record<string, unknown>, key: string): string {
+  return String(config[key] ?? '').trim();
+}
+
+/**
+ * Valida uma URL fornecida pelo usuário (host do Evolution, api_server do k8s,
+ * endpoint S3-compatible, base da ADN).
+ *
+ * Ranges privados são PERMITIDOS de propósito: k8s e Evolution self-hosted vivem em
+ * rede interna, e bloqueá-los quebraria o caso de uso principal. O que barramos são
+ * esquemas fora de http/https (file:, gopher:, etc.).
+ */
+export function assertHttpUrl(raw: string, field: string): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${field} is not a valid URL.`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`${field} must use http or https.`);
+  }
+  return url;
+}
+
+export type ProbeResult = {
+  ok: boolean;
+  status: number;
+  /** Corpo parseado como JSON, ou `{}` quando a resposta não é JSON. */
+  body: any;
+  /** Corpo cru (truncado), útil quando a API responde texto puro. */
+  text: string;
+};
+
+/**
+ * `fetch` que não lança em status != 2xx — o status faz parte do veredito na maioria
+ * dos testers (401 vs 404 vs 403 dizem coisas diferentes).
+ */
+export async function probeJson(
+  url: string,
+  init: RequestInit,
+  signal: AbortSignal,
+): Promise<ProbeResult> {
+  const response = await fetch(url, { ...init, signal });
+  const text = (await response.text().catch(() => '')).slice(0, 2_000);
+
+  let body: any = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = {};
+  }
+
+  return { ok: response.ok, status: response.status, body, text };
+}
+
+/** Remove qualquer ocorrência dos segredos do texto. */
+export function redactSecrets(text: string, secretValues: string[]): string {
+  let out = text;
+  for (const secret of secretValues) {
+    // Segredos muito curtos (ex.: uma senha de 3 letras) casariam com palavras comuns
+    // e transformariam a mensagem em ruído; o risco real está nos tokens longos.
+    if (secret && secret.length >= 6) {
+      out = out.split(secret).join('***');
+    }
+  }
+  return out;
+}
+
+/**
+ * Converte qualquer erro em mensagem segura para a UI e para o config do perfil.
+ *
+ * Ordem importa: timeout e falha de DNS/conexão precisam de texto PRÓPRIO, senão o
+ * operador de um cluster sem saída para a internet lê "não foi possível validar" e
+ * conclui que a credencial está errada.
+ */
+export function sanitizeTesterError(
+  error: unknown,
+  secretValues: string[],
+  host?: string,
+): string {
+  const target = host ? ` (${host})` : '';
+  const name = (error as { name?: string })?.name ?? '';
+  const code = String((error as { code?: string })?.code ?? '');
+  const raw = error instanceof Error ? error.message : String(error ?? '');
+
+  if (name === 'AbortError' || name === 'TimeoutError' || code === 'ABORT_ERR') {
+    return `Timed out while contacting the provider${target}. Check the server's outbound network access.`;
+  }
+
+  const networkCode = [code, raw].join(' ');
+  if (/ENOTFOUND|EAI_AGAIN/.test(networkCode)) {
+    return `Host not found${target}. Check the address you typed.`;
+  }
+  if (/ECONNREFUSED/.test(networkCode)) {
+    return `Connection refused${target}. Check the address, the port and the firewall.`;
+  }
+  if (/ECONNRESET|EPIPE|ETIMEDOUT/.test(networkCode)) {
+    return `Connection interrupted${target}. Check the server's outbound network access.`;
+  }
+  if (/CERT_HAS_EXPIRED/.test(networkCode)) {
+    return `The provider's TLS certificate has expired${target}.`;
+  }
+  if (/DEPTH_ZERO_SELF_SIGNED_CERT|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE/.test(networkCode)) {
+    return `The provider's TLS certificate could not be verified${target}.`;
+  }
+
+  // Só a mensagem — nunca o objeto de erro inteiro nem o stack.
+  const message = redactSecrets(raw || 'Unexpected error.', secretValues).trim();
+  return message.length > MAX_ERROR_LENGTH
+    ? `${message.slice(0, MAX_ERROR_LENGTH - 1)}…`
+    : message;
+}
+
+/**
+ * Mensagem curta a partir de uma resposta HTTP de erro, procurando o campo de mensagem
+ * nos formatos mais comuns (`error.message`, `error_description`, `message`, `error`).
+ */
+export function describeHttpError(result: ProbeResult, fallback: string): string {
+  const body = result.body ?? {};
+  const candidate =
+    body?.error?.message ??
+    body?.error_description ??
+    body?.message ??
+    (typeof body?.error === 'string' ? body.error : null) ??
+    body?.error?.error_user_msg;
+
+  const message = String(candidate ?? '').trim();
+  if (message) return message;
+
+  return `${fallback} (HTTP ${result.status})`;
+}

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

@@ -0,0 +1,30 @@
+import { AI_TESTERS } from './ai.testers';
+import { CAPTCHA_TESTERS } from './captcha.testers';
+import { EMAIL_TESTERS } from './email.testers';
+import { INFRASTRUCTURE_TESTERS } from './infrastructure.testers';
+import { IntegrationTester } from './integration-tester.types';
+import { MESSAGING_TESTERS } from './messaging.testers';
+import { OAUTH_TESTERS } from './oauth.testers';
+import { PAYMENT_TESTERS } from './payment.testers';
+import { STORAGE_TESTERS } from './storage.testers';
+
+/**
+ * Testadores que o core registra sozinho no boot.
+ *
+ * Providers de outras libraries (nfse-national, da `fiscal`) se registram no próprio
+ * módulo, via IntegrationTesterRegistry.
+ */
+export const BUILTIN_INTEGRATION_TESTERS: IntegrationTester[] = [
+  ...EMAIL_TESTERS,
+  ...MESSAGING_TESTERS,
+  ...STORAGE_TESTERS,
+  ...AI_TESTERS,
+  ...OAUTH_TESTERS,
+  ...PAYMENT_TESTERS,
+  ...CAPTCHA_TESTERS,
+  ...INFRASTRUCTURE_TESTERS,
+];
+
+export * from './http-probe';
+export * from './integration-tester.registry';
+export * from './integration-tester.types';

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,
+];