@hed-hog/core 0.0.387 → 0.0.393

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

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { CAPTCHA_TESTERS } from './captcha.testers';
+import { IntegrationTestContext, IntegrationTester } from './integration-tester.types';
+
+const bySlug = (slug: string): IntegrationTester =>
+  CAPTCHA_TESTERS.find((tester) => tester.providerSlug === slug)!;
+
+const ctx = (): IntegrationTestContext => ({
+  signal: AbortSignal.timeout(5_000),
+  typeSlug: 'captcha',
+  providerSlug: 'test',
+  secretValues: [],
+});
+
+function siteverify(errorCodes: string[], success = false) {
+  return {
+    ok: true,
+    status: 200,
+    text: async () => JSON.stringify({ success, 'error-codes': errorCodes }),
+  } as unknown as Response;
+}
+
+let fetchMock: jest.Mock;
+
+beforeEach(() => {
+  fetchMock = jest.fn();
+  global.fetch = fetchMock as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe.each([
+  ['recaptcha', 'Invalid reCAPTCHA secret key.'],
+  ['cloudflare-turnstile', 'Invalid Turnstile secret key.'],
+])('%s tester', (slug, invalidSecretMessage) => {
+  const tester = bySlug(slug);
+
+  it('reprova quando o siteverify recusa o segredo', async () => {
+    fetchMock.mockResolvedValue(siteverify(['invalid-input-secret']));
+
+    const outcome = await tester.test(
+      { site_key: 'site', secret_key: 'wrong' },
+      ctx(),
+    );
+
+    expect(outcome).toEqual({ ok: false, error: invalidSecretMessage });
+  });
+
+  it('aprova quando o siteverify aceita o segredo e só reclama do token de teste', async () => {
+    fetchMock.mockResolvedValue(
+      siteverify(['missing-input-response', 'invalid-input-response']),
+    );
+
+    const outcome = await tester.test(
+      { site_key: 'site', secret_key: 'right' },
+      ctx(),
+    );
+
+    expect(outcome.ok).toBe(true);
+  });
+
+  it('reprova sem ir à rede quando falta o segredo', async () => {
+    const outcome = await tester.test({ site_key: 'site' }, ctx());
+
+    expect(outcome.ok).toBe(false);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('altcha tester', () => {
+  const tester = bySlug('altcha');
+
+  it('valida a chave localmente e avisa que não há verificação remota', async () => {
+    const outcome = await tester.test(
+      { hmac_key: 'uma-chave-hmac-suficientemente-longa' },
+      ctx(),
+    );
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.warning).toContain('self-hosted');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('reprova uma chave curta demais', async () => {
+    const outcome = await tester.test({ hmac_key: 'curta' }, ctx());
+
+    expect(outcome.ok).toBe(false);
+    expect(outcome.error).toContain('too short');
+  });
+});

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,194 @@
+import {
+  verifyImapConnection,
+  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)`);
+  },
+};
+
+/**
+ * IMAP é o único provider de e-mail que não envia — ele lê uma caixa. Por isso
+ * é o único que não exige `from_email`.
+ */
+const imapTester: IntegrationTester = {
+  providerSlug: 'imap',
+  test: async (config) => {
+    const missing = requireFields(config, [
+      ['host', 'IMAP host'],
+      ['username', 'Username'],
+      ['password', 'Password'],
+    ]);
+    if (missing) return missing;
+
+    const result = await verifyImapConnection({
+      host: str(config, 'host'),
+      port: Number(config.port ?? 993),
+      secure: config.secure === undefined ? true : Boolean(config.secure),
+      username: str(config, 'username'),
+      password: String(config.password ?? ''),
+      folder: str(config, 'folder') || 'INBOX',
+      timeoutMs: 10_000,
+    });
+
+    return result.ok ? pass(result.info) : fail(result.error!);
+  },
+};
+
+export const EMAIL_TESTERS: IntegrationTester[] = [
+  smtpTester,
+  sesTester,
+  gmailTester,
+  resendTester,
+  imapTester,
+];

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)');
+  });
+});