@hed-hog/core 0.0.387 → 0.0.390

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

@@ -0,0 +1,139 @@
+import { createHmac } from 'node:crypto';
+import { fail, pass, probeJson, requireFields, str } from './http-probe';
+import { IntegrationTester } from './integration-tester.types';
+
+/**
+ * Testadores dos providers de captcha.
+ *
+ * Um captcha só é resolvido por um humano no navegador, então não há token válido para
+ * enviar aqui. O truque é que ambos os endpoints de `siteverify` validam o SEGREDO antes
+ * do token: mandamos um token vazio e lemos qual das duas reclamações voltou.
+ *
+ *   invalid-input-secret     → segredo errado  → REPROVA
+ *   invalid-input-response   → segredo aceito, faltou só o token (era o esperado) → APROVA
+ */
+
+const recaptchaTester: IntegrationTester = {
+  providerSlug: 'recaptcha',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['site_key', 'Site key'],
+      ['secret_key', 'Secret key'],
+    ]);
+    if (missing) return missing;
+
+    const result = await probeJson(
+      'https://www.google.com/recaptcha/api/siteverify',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+          secret: String(config.secret_key ?? ''),
+          response: '',
+        }).toString(),
+      },
+      ctx.signal,
+    );
+
+    const codes: string[] = Array.isArray(result.body?.['error-codes'])
+      ? result.body['error-codes']
+      : [];
+
+    if (codes.includes('invalid-input-secret')) {
+      return fail('Invalid reCAPTCHA secret key.');
+    }
+    if (codes.includes('missing-input-secret')) {
+      return fail('reCAPTCHA secret key is required.');
+    }
+    if (
+      codes.includes('missing-input-response') ||
+      codes.includes('invalid-input-response')
+    ) {
+      return pass('Google accepted the reCAPTCHA secret key');
+    }
+    if (!result.ok) {
+      return fail(`Google returned HTTP ${result.status}.`);
+    }
+    return pass('Google accepted the reCAPTCHA secret key');
+  },
+};
+
+const turnstileTester: IntegrationTester = {
+  providerSlug: 'cloudflare-turnstile',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['site_key', 'Site key'],
+      ['secret_key', 'Secret key'],
+    ]);
+    if (missing) return missing;
+
+    const result = await probeJson(
+      'https://challenges.cloudflare.com/turnstile/v0/siteverify',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          secret: String(config.secret_key ?? ''),
+          response: 'hedhog-connection-test',
+        }),
+      },
+      ctx.signal,
+    );
+
+    const codes: string[] = Array.isArray(result.body?.['error-codes'])
+      ? result.body['error-codes']
+      : [];
+
+    if (codes.includes('invalid-input-secret')) {
+      return fail('Invalid Turnstile secret key.');
+    }
+    if (codes.includes('missing-input-secret')) {
+      return fail('Turnstile secret key is required.');
+    }
+    if (
+      codes.includes('invalid-input-response') ||
+      codes.includes('missing-input-response')
+    ) {
+      return pass('Cloudflare accepted the Turnstile secret key');
+    }
+    if (!result.ok) {
+      return fail(`Cloudflare returned HTTP ${result.status}.`);
+    }
+    return pass('Cloudflare accepted the Turnstile secret key');
+  },
+};
+
+const altchaTester: IntegrationTester = {
+  providerSlug: 'altcha',
+  test: async (config) => {
+    const missing = requireFields(config, [['hmac_key', 'HMAC key']]);
+    if (missing) return missing;
+
+    const hmacKey = String(config.hmac_key ?? '');
+    if (hmacKey.length < 16) {
+      return fail('The HMAC key is too short — use at least 16 characters.');
+    }
+
+    // Altcha é self-hosted: não existe endpoint remoto para validar a chave. O que dá
+    // para provar é que ela gera um desafio assinado, que é o uso dela em produção.
+    try {
+      const challenge = createHmac('sha256', hmacKey)
+        .update('hedhog-connection-test')
+        .digest('hex');
+      if (!challenge) throw new Error('empty digest');
+    } catch {
+      return fail('Could not sign a challenge with this HMAC key.');
+    }
+
+    return pass(
+      'HMAC key is usable',
+      'Altcha is self-hosted: the key was validated locally, with no remote check.',
+    );
+  },
+};
+
+export const CAPTCHA_TESTERS: IntegrationTester[] = [
+  recaptchaTester,
+  turnstileTester,
+  altchaTester,
+];

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

@@ -0,0 +1,161 @@
+import { verifySesCredentials, verifySmtpConnection } from '@hed-hog/api-mail';
+import {
+  describeHttpError,
+  fail,
+  pass,
+  probeJson,
+  requireFields,
+  str,
+} from './http-probe';
+import { IntegrationTester } from './integration-tester.types';
+
+/**
+ * Testadores dos providers de e-mail.
+ *
+ * Todos exigem `from_email`: sem remetente o perfil não envia nada, e essa validação
+ * já era o contrato do teste antes de existirem chamadas de rede.
+ */
+
+const smtpTester: IntegrationTester = {
+  providerSlug: 'smtp',
+  test: async (config) => {
+    const missing = requireFields(config, [
+      ['host', 'SMTP host'],
+      ['from_email', 'Sender email'],
+    ]);
+    if (missing) return missing;
+
+    const result = await verifySmtpConnection({
+      host: str(config, 'host'),
+      port: Number(config.port ?? 587),
+      secure: Boolean(config.secure),
+      username: str(config, 'username'),
+      password: String(config.password ?? ''),
+      timeoutMs: 8_000,
+    });
+
+    return result.ok ? pass(result.info) : fail(result.error!);
+  },
+};
+
+const sesTester: IntegrationTester = {
+  providerSlug: 'ses',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['region', 'AWS region'],
+      ['access_key_id', 'Access key ID'],
+      ['secret_access_key', 'Secret access key'],
+      ['from_email', 'Sender email'],
+    ]);
+    if (missing) return missing;
+
+    const result = await verifySesCredentials({
+      region: str(config, 'region'),
+      accessKeyId: str(config, 'access_key_id'),
+      secretAccessKey: String(config.secret_access_key ?? ''),
+      signal: ctx.signal,
+    });
+
+    return result.ok ? pass(result.info) : fail(result.error!);
+  },
+};
+
+const gmailTester: IntegrationTester = {
+  providerSlug: 'gmail',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['client_id', 'Client ID'],
+      ['client_secret', 'Client secret'],
+      ['refresh_token', 'Refresh token'],
+      ['from_email', 'Sender email'],
+    ]);
+    if (missing) return missing;
+
+    // Troca real do refresh token: separa credencial de app errada (invalid_client)
+    // de autorização revogada pelo usuário (invalid_grant).
+    const result = await probeJson(
+      'https://oauth2.googleapis.com/token',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+          client_id: str(config, 'client_id'),
+          client_secret: String(config.client_secret ?? ''),
+          refresh_token: String(config.refresh_token ?? ''),
+          grant_type: 'refresh_token',
+        }).toString(),
+      },
+      ctx.signal,
+    );
+
+    if (result.ok) {
+      return pass(`Gmail authorized for ${str(config, 'from_email')}`);
+    }
+
+    const code = String(result.body?.error ?? '');
+    if (code === 'invalid_client') {
+      return fail('Invalid Client ID or Client secret.');
+    }
+    if (code === 'invalid_grant') {
+      return fail(
+        'The refresh token is invalid or was revoked. Authorize the account again.',
+      );
+    }
+    return fail(describeHttpError(result, 'Google rejected the credentials.'));
+  },
+};
+
+const resendTester: IntegrationTester = {
+  providerSlug: 'resend',
+  test: async (config, ctx) => {
+    const missing = requireFields(config, [
+      ['api_token', 'Resend API token'],
+      ['domain', 'Resend sending domain'],
+    ]);
+    if (missing) return missing;
+
+    const domain = str(config, 'domain').toLowerCase();
+    const result = await probeJson(
+      'https://api.resend.com/domains',
+      { headers: { Authorization: `Bearer ${String(config.api_token ?? '')}` } },
+      ctx.signal,
+    );
+
+    if (result.status === 401 || result.status === 403) {
+      return fail('Invalid Resend API token.');
+    }
+    if (!result.ok) {
+      return fail(describeHttpError(result, 'Resend rejected the credentials.'));
+    }
+
+    const domains: Array<{ name?: string; status?: string }> = Array.isArray(
+      result.body?.data,
+    )
+      ? result.body.data
+      : [];
+    const match = domains.find(
+      (item) => String(item?.name ?? '').toLowerCase() === domain,
+    );
+
+    if (!match) {
+      return pass(
+        `Resend token is valid (${domains.length} domain(s))`,
+        `The domain "${domain}" is not registered in this Resend account.`,
+      );
+    }
+    if (String(match.status ?? '').toLowerCase() !== 'verified') {
+      return pass(
+        `Resend token is valid — ${domain}`,
+        `The domain "${domain}" is not verified yet (status: ${match.status}).`,
+      );
+    }
+    return pass(`Resend — ${domain} (verified)`);
+  },
+};
+
+export const EMAIL_TESTERS: IntegrationTester[] = [
+  smtpTester,
+  sesTester,
+  gmailTester,
+  resendTester,
+];

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

@@ -0,0 +1,153 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  assertHttpUrl,
+  describeHttpError,
+  redactSecrets,
+  requireFields,
+  sanitizeTesterError,
+  str,
+} from './http-probe';
+
+describe('sanitizeTesterError', () => {
+  it('nunca inclui o stack trace, só a mensagem', () => {
+    const error = new Error('Something specific went wrong');
+    error.stack = 'Error: secret-laden stack\n    at somewhere.ts:1:1';
+
+    const message = sanitizeTesterError(error, []);
+
+    expect(message).toBe('Something specific went wrong');
+    expect(message).not.toContain('at somewhere.ts');
+  });
+
+  it('redige todos os valores de segredo, inclusive quando a API ecoa a entrada', () => {
+    const secret = 'sk_live_51H8xVeryLongToken';
+    const other = 'another-long-secret';
+    const error = new Error(
+      `Provider rejected key ${secret} and app secret ${other}.`,
+    );
+
+    const message = sanitizeTesterError(error, [secret, other]);
+
+    expect(message).not.toContain(secret);
+    expect(message).not.toContain(other);
+    expect(message).toContain('***');
+  });
+
+  it('ignora segredos curtos demais para não picotar a mensagem inteira', () => {
+    const message = sanitizeTesterError(new Error('bad host name'), ['a', 'ho']);
+
+    expect(message).toBe('bad host name');
+  });
+
+  it('usa um texto próprio para timeout, distinto de credencial inválida', () => {
+    const abort = new Error('The operation was aborted');
+    abort.name = 'AbortError';
+
+    const message = sanitizeTesterError(abort, [], 'api.example.com');
+
+    expect(message).toContain('Timed out');
+    expect(message).toContain('api.example.com');
+    expect(message).toContain('outbound network access');
+  });
+
+  it('traduz os códigos de rede mais comuns', () => {
+    const cases: Array<[string, string]> = [
+      ['ENOTFOUND', 'Host not found'],
+      ['ECONNREFUSED', 'Connection refused'],
+      ['ECONNRESET', 'Connection interrupted'],
+      ['CERT_HAS_EXPIRED', 'certificate has expired'],
+      ['DEPTH_ZERO_SELF_SIGNED_CERT', 'could not be verified'],
+    ];
+
+    for (const [code, expected] of cases) {
+      const error = Object.assign(new Error('raw driver noise'), { code });
+      expect(sanitizeTesterError(error, [])).toContain(expected);
+    }
+  });
+
+  it('trunca mensagens muito longas', () => {
+    const message = sanitizeTesterError(new Error('x'.repeat(1_000)), []);
+
+    expect(message.length).toBeLessThanOrEqual(300);
+    expect(message.endsWith('…')).toBe(true);
+  });
+
+  it('lida com valores que não são Error', () => {
+    expect(sanitizeTesterError('plain string failure', [])).toBe(
+      'plain string failure',
+    );
+    expect(sanitizeTesterError(null, [])).toBe('Unexpected error.');
+  });
+});
+
+describe('redactSecrets', () => {
+  it('substitui todas as ocorrências de um mesmo segredo', () => {
+    const secret = 'super-secret-token';
+
+    expect(redactSecrets(`${secret} and ${secret}`, [secret])).toBe('*** and ***');
+  });
+});
+
+describe('assertHttpUrl', () => {
+  it('aceita http e https, incluindo endereços de rede privada', () => {
+    expect(assertHttpUrl('https://api.example.com/x', 'Endpoint').host).toBe(
+      'api.example.com',
+    );
+    // k8s e Evolution self-hosted vivem em rede interna: bloqueá-los quebraria o caso de uso.
+    expect(assertHttpUrl('https://10.0.0.1:6443', 'API server').port).toBe('6443');
+  });
+
+  it('rejeita esquemas fora de http/https e URLs inválidas', () => {
+    expect(() => assertHttpUrl('file:///etc/passwd', 'Endpoint')).toThrow(
+      'Endpoint must use http or https.',
+    );
+    expect(() => assertHttpUrl('não é url', 'Endpoint')).toThrow(
+      'Endpoint is not a valid URL.',
+    );
+  });
+});
+
+describe('requireFields', () => {
+  it('devolve null quando todos os campos estão preenchidos', () => {
+    expect(requireFields({ host: 'h', token: 't' }, [
+      ['host', 'Host'],
+      ['token', 'Token'],
+    ])).toBeNull();
+  });
+
+  it('reprova no primeiro campo vazio, em branco ou ausente', () => {
+    expect(requireFields({ host: '   ' }, [['host', 'Host']])).toEqual({
+      ok: false,
+      error: 'Host is required.',
+    });
+    expect(requireFields({}, [['token', 'Token']])).toEqual({
+      ok: false,
+      error: 'Token is required.',
+    });
+  });
+});
+
+describe('str', () => {
+  it('normaliza para string trimada, com fallback vazio', () => {
+    expect(str({ a: '  x  ' }, 'a')).toBe('x');
+    expect(str({}, 'a')).toBe('');
+    expect(str({ a: 42 }, 'a')).toBe('42');
+  });
+});
+
+describe('describeHttpError', () => {
+  it('encontra a mensagem nos formatos usados pelos provedores', () => {
+    const base = { ok: false, status: 400, text: '' };
+
+    expect(describeHttpError({ ...base, body: { error: { message: 'a' } } }, 'f')).toBe('a');
+    expect(describeHttpError({ ...base, body: { error_description: 'b' } }, 'f')).toBe('b');
+    expect(describeHttpError({ ...base, body: { message: 'c' } }, 'f')).toBe('c');
+    expect(describeHttpError({ ...base, body: { error: 'd' } }, 'f')).toBe('d');
+  });
+
+  it('cai no fallback com o status quando não há mensagem reconhecível', () => {
+    expect(
+      describeHttpError({ ok: false, status: 503, body: {}, text: '' }, 'Provider down.'),
+    ).toBe('Provider down. (HTTP 503)');
+  });
+});

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';