@hed-hog/core 0.0.390 → 0.0.393

package/src/mail-delivery/ses-webhook.service.spec.ts

@@ -0,0 +1,170 @@
+import { SesWebhookService } from './ses-webhook.service';
+import * as snsUtil from './sns-message.util';
+
+describe('SesWebhookService', () => {
+  let prisma: any;
+  let registry: any;
+  let delivery: any;
+  let service: SesWebhookService;
+  let verifySpy: jest.SpyInstance;
+
+  const topicArn = 'arn:aws:sns:us-east-1:123456789012:ses-events';
+
+  const request = (body: any, profileId: number | null = 5) =>
+    ({
+      integration: { id: 9, slug: 'ses-delivery-hcode', integration_profile_id: profileId },
+      body,
+      query: {},
+      headers: {},
+      remoteIp: '1.2.3.4',
+      req: {} as any,
+    }) as any;
+
+  const notification = (message: any) => ({
+    Type: 'Notification',
+    TopicArn: topicArn,
+    Message: JSON.stringify(message),
+  });
+
+  beforeEach(() => {
+    prisma = {
+      integration_profile: {
+        findUnique: jest.fn().mockResolvedValue({ config: { sns_topic_arn: topicArn } }),
+      },
+    };
+    registry = { register: jest.fn() };
+    delivery = {
+      ingestSesNotification: jest
+        .fn()
+        .mockResolvedValue({ events: 1, stored: 1, matched: 1 }),
+    };
+    verifySpy = jest
+      .spyOn(snsUtil, 'verifySnsSignature')
+      .mockResolvedValue({ valid: true });
+
+    service = new SesWebhookService(prisma, registry, delivery);
+    global.fetch = jest.fn().mockResolvedValue({ ok: true, text: async () => '' }) as any;
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('registra o protocolo no boot', () => {
+    service.onModuleInit();
+    expect(registry.register).toHaveBeenCalledWith('aws-ses', service);
+  });
+
+  it('processa a notificacao e devolve o resultado da ingestao', async () => {
+    const response = await service.handle(
+      request(notification({ notificationType: 'Delivery' })),
+    );
+
+    expect(delivery.ingestSesNotification).toHaveBeenCalledWith({
+      notificationType: 'Delivery',
+    });
+    expect(response.status).toBe(200);
+  });
+
+  it('recusa quando a assinatura nao confere', async () => {
+    verifySpy.mockResolvedValue({ valid: false, reason: 'signature mismatch' });
+
+    const response = await service.handle(request(notification({})));
+
+    expect(response.status).toBe(403);
+    // O motivo fica so no log de chamadas: numa rota publica, explicar a recusa
+    // ajuda quem esta atacando tanto quanto quem esta configurando.
+    expect(response.body).toBe('');
+    expect(response.logReason).toContain('signature mismatch');
+    expect(delivery.ingestSesNotification).not.toHaveBeenCalled();
+  });
+
+  it('recusa evento de um topico que nao e o configurado', async () => {
+    // A assinatura prova apenas que saiu do SNS da AWS - de qualquer conta.
+    const response = await service.handle(
+      request({
+        Type: 'Notification',
+        TopicArn: 'arn:aws:sns:us-east-1:999:outro',
+        Message: '{}',
+      }),
+    );
+
+    expect(response.status).toBe(403);
+    expect(delivery.ingestSesNotification).not.toHaveBeenCalled();
+  });
+
+  it('aceita qualquer topico enquanto o perfil nao configurou o ARN', async () => {
+    prisma.integration_profile.findUnique.mockResolvedValue({ config: {} });
+
+    const response = await service.handle(
+      request({
+        Type: 'Notification',
+        TopicArn: 'arn:aws:sns:us-east-1:999:qualquer',
+        Message: '{"notificationType":"Delivery"}',
+      }),
+    );
+
+    expect(response.status).toBe(200);
+  });
+
+  it('confirma a subscription seguindo o SubscribeURL', async () => {
+    // Sem este passo a subscription fica em PendingConfirmation para sempre e
+    // nenhum evento chega.
+    const response = await service.handle(
+      request({
+        Type: 'SubscriptionConfirmation',
+        TopicArn: topicArn,
+        SubscribeURL: 'https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription',
+      }),
+    );
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription',
+      { method: 'GET' },
+    );
+    expect(response.status).toBe(200);
+  });
+
+  it('nao segue um SubscribeURL que nao e da AWS', async () => {
+    // Seguir uma URL escolhida por quem chama transformaria este endpoint num
+    // buscador de URLs arbitrarias.
+    const response = await service.handle(
+      request({
+        Type: 'SubscriptionConfirmation',
+        TopicArn: topicArn,
+        SubscribeURL: 'https://evil.com/steal',
+      }),
+    );
+
+    expect(response.status).toBe(403);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it('aceita o envelope como string, que e como o SNS costuma mandar', async () => {
+    const response = await service.handle(
+      request(JSON.stringify(notification({ notificationType: 'Bounce' }))),
+    );
+
+    expect(response.status).toBe(200);
+    expect(delivery.ingestSesNotification).toHaveBeenCalledWith({
+      notificationType: 'Bounce',
+    });
+  });
+
+  it('recusa corpo que nao e um envelope do SNS', async () => {
+    const response = await service.handle(request({ foo: 'bar' }));
+
+    expect(response.status).toBe(403);
+    expect(verifySpy).not.toHaveBeenCalled();
+  });
+
+  it('devolve 400 quando o Message nao e JSON valido', async () => {
+    const response = await service.handle(
+      request({ Type: 'Notification', TopicArn: topicArn, Message: 'nao e json' }),
+    );
+
+    expect(response.status).toBe(400);
+  });
+
+  it('recusa GET: o SNS nao faz handshake', async () => {
+    await expect(service.verify()).resolves.toMatchObject({ status: 403 });
+  });
+});

package/src/mail-delivery/ses-webhook.service.ts

@@ -0,0 +1,240 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Inject, Injectable, Logger, OnModuleInit, forwardRef } from '@nestjs/common';
+import {
+  IWebhookProtocolAdapter,
+  WebhookProtocolRegistry,
+  WebhookProtocolRequest,
+  WebhookProtocolResponse,
+} from '../webhook-integration/webhook-protocol.registry';
+import { MailDeliveryService } from './mail-delivery.service';
+import { SES_DELIVERY_WEBHOOK_PROTOCOL } from './mail-delivery.constants';
+import { SnsEnvelope, isAwsSigningUrl, verifySnsSignature } from './sns-message.util';
+
+/**
+ * 403 sem corpo: numa rota publica, dizer o motivo ajuda a mapear o que existe.
+ * O `logReason` fica so no log de chamadas, que exige login para ser lido.
+ */
+function forbidden(logReason: string): WebhookProtocolResponse {
+  return { status: 403, contentType: 'text/plain', body: '', logReason };
+}
+
+/** Certificados da AWS mudam raramente; baixar um por notificacao seria absurdo. */
+const CERT_CACHE_MAX = 8;
+
+/**
+ * Eventos de entrega do Amazon SES, publicados via SNS, sobre o webhook publico
+ * do core.
+ *
+ * Duas camadas de credencial, como o resto dos adaptadores:
+ *
+ *   1. o `public_uuid` da URL, que a requisicao ja provou conhecer para este
+ *      adaptador sequer ser chamado;
+ *   2. a assinatura RSA do proprio SNS, verificada contra o certificado da AWS.
+ *
+ * A segunda existe porque a primeira e uma URL: ela vaza em log de proxy, em
+ * print de tela, em copiar-e-colar. Um evento de bounce forjado envenenaria o
+ * historico de entrega exatamente da tela que existe para ser confiavel.
+ */
+@Injectable()
+export class SesWebhookService implements OnModuleInit, IWebhookProtocolAdapter {
+  private readonly logger = new Logger(SesWebhookService.name);
+  private readonly certCache = new Map<string, string>();
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    private readonly protocolRegistry: WebhookProtocolRegistry,
+    private readonly delivery: MailDeliveryService,
+  ) {}
+
+  onModuleInit() {
+    this.protocolRegistry.register(SES_DELIVERY_WEBHOOK_PROTOCOL, this);
+  }
+
+  /** O SNS so faz POST; nao existe handshake por GET. */
+  async verify(): Promise<WebhookProtocolResponse> {
+    return forbidden('GET not supported');
+  }
+
+  async handle(request: WebhookProtocolRequest): Promise<WebhookProtocolResponse> {
+    const envelope = this.readEnvelope(request);
+    if (!envelope) return forbidden('body is not an SNS envelope');
+
+    const signature = await verifySnsSignature(envelope, (url) =>
+      this.fetchCertificate(url),
+    );
+    if (!signature.valid) {
+      this.logger.warn(
+        `[ses] rejected webhook=${request.integration.id}: ${signature.reason}`,
+      );
+      return forbidden(`invalid SNS signature: ${signature.reason}`);
+    }
+
+    const topic = await this.checkTopic(request, envelope);
+    if (!topic.ok) {
+      this.logger.warn(
+        `[ses] rejected webhook=${request.integration.id}: ${topic.reason}`,
+      );
+      return forbidden(topic.reason ?? 'topic mismatch');
+    }
+
+    switch (String(envelope.Type)) {
+      case 'SubscriptionConfirmation':
+        return this.confirmSubscription(envelope);
+
+      case 'UnsubscribeConfirmation':
+        this.logger.warn(
+          `[ses] subscription removed from topic ${envelope.TopicArn ?? '?'}`,
+        );
+        return { status: 200, body: { ok: true, type: 'UnsubscribeConfirmation' } };
+
+      case 'Notification':
+        return this.handleNotification(envelope);
+
+      default:
+        return forbidden(`unsupported SNS type "${envelope.Type}"`);
+    }
+  }
+
+  /**
+   * Sem este passo a subscription fica em PendingConfirmation para sempre e
+   * nenhum evento chega - a falha silenciosa classica desse setup, que parece
+   * "a AWS nao esta mandando nada".
+   */
+  private async confirmSubscription(
+    envelope: SnsEnvelope,
+  ): Promise<WebhookProtocolResponse> {
+    const url = String(envelope.SubscribeURL ?? '');
+
+    // Mesma trava do certificado: seguir uma URL escolhida por quem chama
+    // transformaria este endpoint num buscador de URLs arbitrarias.
+    if (!isAwsSigningUrl(url)) {
+      return forbidden('SubscribeURL is not an AWS SNS endpoint');
+    }
+
+    try {
+      const response = await fetch(url, { method: 'GET' });
+      if (!response.ok) {
+        this.logger.error(
+          `[ses] subscription confirmation failed with HTTP ${response.status}`,
+        );
+        return { status: 502, body: { ok: false, reason: 'confirmation-failed' } };
+      }
+
+      this.logger.log(`[ses] subscription confirmed for topic ${envelope.TopicArn}`);
+      return { status: 200, body: { ok: true, type: 'SubscriptionConfirmation' } };
+    } catch (error) {
+      this.logger.error(
+        `[ses] subscription confirmation error: ${(error as Error)?.message}`,
+      );
+      return { status: 502, body: { ok: false, reason: 'confirmation-error' } };
+    }
+  }
+
+  private async handleNotification(
+    envelope: SnsEnvelope,
+  ): Promise<WebhookProtocolResponse> {
+    let payload: any;
+    try {
+      // `Message` e uma string com o JSON do evento: a dupla serializacao e do
+      // protocolo do SNS.
+      payload = JSON.parse(String(envelope.Message ?? ''));
+    } catch {
+      return { status: 400, body: { ok: false, reason: 'invalid-message-json' } };
+    }
+
+    const result = await this.delivery.ingestSesNotification(payload);
+    return { status: 200, body: { ok: true, ...result } };
+  }
+
+  /**
+   * Confere que o evento veio do topico esperado.
+   *
+   * A assinatura prova apenas que a mensagem saiu do SNS da AWS - de qualquer
+   * conta, de qualquer topico. Sem esta checagem, quem descobrisse a URL poderia
+   * publicar bounces forjados no proprio topico e envenenar o historico de
+   * entrega justamente da tela que existe para ser confiavel.
+   *
+   * Com `sns_topic_arn` vazio o evento passa, com aviso: e o estado do setup
+   * inicial, antes de o topico existir. Preencher o campo no perfil e o que
+   * fecha a porta.
+   */
+  private async checkTopic(
+    request: WebhookProtocolRequest,
+    envelope: SnsEnvelope,
+  ): Promise<{ ok: boolean; reason?: string }> {
+    const profileId = request.integration.integration_profile_id;
+    if (!profileId) return { ok: true };
+
+    const profile = await this.prisma.integration_profile.findUnique({
+      where: { id: profileId },
+      select: { config: true },
+    });
+
+    const expected = String(
+      (profile?.config as any)?.sns_topic_arn ?? '',
+    ).trim();
+
+    if (!expected) {
+      this.logger.warn(
+        `[ses] profile ${profileId} has no sns_topic_arn: accepting events from any SNS topic`,
+      );
+      return { ok: true };
+    }
+
+    const received = String(envelope.TopicArn ?? '').trim();
+    return received === expected
+      ? { ok: true }
+      : { ok: false, reason: 'TopicArn does not match the configured topic' };
+  }
+
+  /**
+   * O SNS envia `Content-Type: text/plain`, entao o body pode chegar como string
+   * mesmo com o parser de JSON configurado. Aceitar as duas formas evita depender
+   * de um detalhe do middleware.
+   */
+  private readEnvelope(request: WebhookProtocolRequest): SnsEnvelope | null {
+    const body = request.body;
+
+    if (body && typeof body === 'object' && !Buffer.isBuffer(body)) {
+      const envelope = body as SnsEnvelope;
+      return envelope.Type ? envelope : null;
+    }
+
+    const raw =
+      typeof body === 'string'
+        ? body
+        : request.rawBody
+          ? request.rawBody.toString('utf8')
+          : '';
+    if (!raw) return null;
+
+    try {
+      const parsed = JSON.parse(raw) as SnsEnvelope;
+      return parsed?.Type ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async fetchCertificate(url: string): Promise<string> {
+    const cached = this.certCache.get(url);
+    if (cached) return cached;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const pem = await response.text();
+
+    // Cache pequeno com descarte do mais antigo: a URL do certificado muda de
+    // tempos em tempos e um Map sem teto viraria vazamento lento.
+    if (this.certCache.size >= CERT_CACHE_MAX) {
+      const oldest = this.certCache.keys().next().value;
+      if (oldest) this.certCache.delete(oldest);
+    }
+    this.certCache.set(url, pem);
+
+    return pem;
+  }
+}

package/src/mail-delivery/sns-message.util.spec.ts

@@ -0,0 +1,163 @@
+import { generateKeyPairSync, createSign } from 'crypto';
+import {
+  buildStringToSign,
+  isAwsSigningUrl,
+  verifySnsSignature,
+} from './sns-message.util';
+
+describe('isAwsSigningUrl', () => {
+  it('aceita o endpoint do SNS de qualquer regiao', () => {
+    expect(
+      isAwsSigningUrl('https://sns.us-east-1.amazonaws.com/SimpleNotification-x.pem'),
+    ).toBe(true);
+    expect(isAwsSigningUrl('https://sns.cn-north-1.amazonaws.com.cn/a.pem')).toBe(
+      true,
+    );
+  });
+
+  it.each([
+    ['http://sns.us-east-1.amazonaws.com/a.pem', 'sem TLS'],
+    ['https://sns.us-east-1.amazonaws.com.evil.com/a.pem', 'sufixo de dominio'],
+    ['https://evil.com/sns.us-east-1.amazonaws.com/a.pem', 'host falso no path'],
+    ['https://s3.amazonaws.com/a.pem', 'outro servico da AWS'],
+    ['nao e url', 'lixo'],
+  ])('recusa %s (%s)', (url) => {
+    // Sem esta trava, quem manda o webhook escolhe de onde baixamos a chave
+    // publica - e passa a poder assinar o que quiser.
+    expect(isAwsSigningUrl(url)).toBe(false);
+  });
+});
+
+describe('buildStringToSign', () => {
+  it('usa a ordem exata da especificacao, nao a alfabetica do objeto', () => {
+    const out = buildStringToSign({
+      Type: 'Notification',
+      TopicArn: 'arn:aws:sns:us-east-1:1:t',
+      Timestamp: '2026-08-18T14:00:00.000Z',
+      MessageId: 'mid',
+      Message: 'corpo',
+    });
+
+    expect(out).toBe(
+      'Message\ncorpo\n' +
+        'MessageId\nmid\n' +
+        'Timestamp\n2026-08-18T14:00:00.000Z\n' +
+        'TopicArn\narn:aws:sns:us-east-1:1:t\n' +
+        'Type\nNotification\n',
+    );
+  });
+
+  it('pula o campo ausente, como o Subject', () => {
+    const out = buildStringToSign({
+      Type: 'Notification',
+      Message: 'm',
+      MessageId: 'i',
+      Timestamp: 't',
+      TopicArn: 'a',
+    });
+    expect(out).not.toContain('Subject');
+  });
+
+  it('devolve null para um tipo que nao sabe assinar', () => {
+    expect(buildStringToSign({ Type: 'Coisa' })).toBeNull();
+  });
+});
+
+describe('verifySnsSignature', () => {
+  const { privateKey, certificate } = buildKeyPair();
+
+  const baseEnvelope = {
+    Type: 'Notification',
+    MessageId: 'mid-1',
+    TopicArn: 'arn:aws:sns:us-east-1:123456789012:ses-events',
+    Message: '{"notificationType":"Delivery"}',
+    Timestamp: '2026-08-18T14:02:27.000Z',
+    SignatureVersion: '1',
+    SigningCertURL: 'https://sns.us-east-1.amazonaws.com/SimpleNotification-a.pem',
+  };
+
+  const fetcher = jest.fn().mockResolvedValue(certificate);
+
+  beforeEach(() => fetcher.mockClear());
+
+  it('aceita uma assinatura valida (SignatureVersion 1)', async () => {
+    const envelope = { ...baseEnvelope, Signature: sign(privateKey, baseEnvelope, 'RSA-SHA1') };
+
+    await expect(verifySnsSignature(envelope, fetcher)).resolves.toEqual({
+      valid: true,
+    });
+  });
+
+  it('aceita SignatureVersion 2 (SHA256)', async () => {
+    const source = { ...baseEnvelope, SignatureVersion: '2' };
+    const envelope = { ...source, Signature: sign(privateKey, source, 'RSA-SHA256') };
+
+    await expect(verifySnsSignature(envelope, fetcher)).resolves.toEqual({
+      valid: true,
+    });
+  });
+
+  it('recusa quando o corpo foi trocado depois de assinado', async () => {
+    const envelope = {
+      ...baseEnvelope,
+      Signature: sign(privateKey, baseEnvelope, 'RSA-SHA1'),
+      Message: '{"notificationType":"Bounce"}',
+    };
+
+    const result = await verifySnsSignature(envelope, fetcher);
+    expect(result.valid).toBe(false);
+    expect(result.reason).toBe('signature mismatch');
+  });
+
+  it('nao baixa certificado de host que nao e da AWS', async () => {
+    const result = await verifySnsSignature(
+      { ...baseEnvelope, Signature: 'x', SigningCertURL: 'https://evil.com/a.pem' },
+      fetcher,
+    );
+
+    expect(result.valid).toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it('recusa envelope sem assinatura', async () => {
+    const result = await verifySnsSignature(baseEnvelope, fetcher);
+    expect(result).toEqual({ valid: false, reason: 'missing Signature' });
+  });
+
+  it('recusa uma SignatureVersion desconhecida em vez de adivinhar', async () => {
+    const result = await verifySnsSignature(
+      { ...baseEnvelope, SignatureVersion: '9', Signature: 'x' },
+      fetcher,
+    );
+
+    expect(result.valid).toBe(false);
+    expect(result.reason).toContain('unsupported SignatureVersion');
+  });
+
+  it('recusa quando o certificado nao pode ser baixado', async () => {
+    const failing = jest.fn().mockRejectedValue(new Error('HTTP 503'));
+    const envelope = { ...baseEnvelope, Signature: sign(privateKey, baseEnvelope, 'RSA-SHA1') };
+
+    const result = await verifySnsSignature(envelope, failing);
+    expect(result.valid).toBe(false);
+    expect(result.reason).toContain('HTTP 503');
+  });
+});
+
+function sign(privateKey: string, envelope: any, algorithm: string): string {
+  const signer = createSign(algorithm);
+  signer.update(buildStringToSign(envelope) as string, 'utf8');
+  return signer.sign(privateKey, 'base64');
+}
+
+/** Par de chaves autoassinado, para o teste nao depender da AWS nem de rede. */
+function buildKeyPair(): { privateKey: string; certificate: string } {
+  const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  // `crypto.verify` aceita a chave publica no lugar do certificado PEM, que e o
+  // que o SNS serve — o formato do wrapper nao muda a verificacao.
+  return { privateKey, certificate: publicKey };
+}

package/src/mail-delivery/sns-message.util.ts

@@ -0,0 +1,125 @@
+import { createVerify } from 'crypto';
+
+/**
+ * Envelope do SNS. `Message` e uma string com o JSON do evento de verdade -
+ * dupla serializacao e do protocolo, nao um engano.
+ */
+export type SnsEnvelope = {
+  Type?: string;
+  MessageId?: string;
+  TopicArn?: string;
+  Subject?: string;
+  Message?: string;
+  Timestamp?: string;
+  Token?: string;
+  SubscribeURL?: string;
+  SignatureVersion?: string;
+  Signature?: string;
+  SigningCertURL?: string;
+  SigningCertUrl?: string;
+};
+
+/**
+ * Campos que entram na string assinada, na ordem exata definida pela AWS.
+ * A ordem nao e alfabetica por acaso: e a especificacao, e trocar dois campos
+ * de lugar faz toda assinatura valida ser recusada.
+ */
+const SIGNED_KEYS: Record<string, string[]> = {
+  Notification: ['Message', 'MessageId', 'Subject', 'Timestamp', 'TopicArn', 'Type'],
+  SubscriptionConfirmation: [
+    'Message',
+    'MessageId',
+    'SubscribeURL',
+    'Timestamp',
+    'Token',
+    'TopicArn',
+    'Type',
+  ],
+};
+SIGNED_KEYS.UnsubscribeConfirmation = SIGNED_KEYS.SubscriptionConfirmation;
+
+/**
+ * So a AWS pode ser a origem do certificado.
+ *
+ * Sem esta trava, quem manda o webhook escolhe de onde baixamos a chave publica
+ * - e passa a poder assinar o que quiser. E a diferenca entre validar assinatura
+ * e encenar que valida.
+ */
+export function isAwsSigningUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:') return false;
+    return /^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$/.test(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Monta a string canonica `chave\nvalor\n` dos campos assinados. */
+export function buildStringToSign(envelope: SnsEnvelope): string | null {
+  const keys = SIGNED_KEYS[String(envelope.Type ?? '')];
+  if (!keys) return null;
+
+  let out = '';
+  for (const key of keys) {
+    const value = (envelope as Record<string, unknown>)[key];
+    // Campo ausente e pulado (o `Subject` costuma nao vir); presente e vazio
+    // entra, porque foi assim que a AWS assinou.
+    if (value === undefined || value === null) continue;
+    out += `${key}\n${String(value)}\n`;
+  }
+  return out;
+}
+
+/**
+ * Verifica a assinatura do envelope contra o certificado da AWS.
+ *
+ * `certificateFetcher` e injetado para o teste nao depender de rede.
+ */
+export async function verifySnsSignature(
+  envelope: SnsEnvelope,
+  certificateFetcher: (url: string) => Promise<string>,
+): Promise<{ valid: boolean; reason?: string }> {
+  const certUrl = String(envelope.SigningCertURL ?? envelope.SigningCertUrl ?? '');
+  if (!certUrl) return { valid: false, reason: 'missing SigningCertURL' };
+  if (!isAwsSigningUrl(certUrl)) {
+    return { valid: false, reason: 'SigningCertURL is not an AWS SNS endpoint' };
+  }
+  if (!envelope.Signature) return { valid: false, reason: 'missing Signature' };
+
+  const stringToSign = buildStringToSign(envelope);
+  if (!stringToSign) {
+    return { valid: false, reason: `unsupported SNS message type "${envelope.Type}"` };
+  }
+
+  // SignatureVersion 1 assina com SHA1; a 2, com SHA256. Qualquer outra e
+  // desconhecida e recusada em vez de adivinhada.
+  const version = String(envelope.SignatureVersion ?? '1');
+  const algorithm =
+    version === '2' ? 'RSA-SHA256' : version === '1' ? 'RSA-SHA1' : null;
+  if (!algorithm) {
+    return { valid: false, reason: `unsupported SignatureVersion "${version}"` };
+  }
+
+  let certificate: string;
+  try {
+    certificate = await certificateFetcher(certUrl);
+  } catch (error) {
+    return {
+      valid: false,
+      reason: `could not fetch signing certificate: ${(error as Error)?.message}`,
+    };
+  }
+
+  try {
+    const verifier = createVerify(algorithm);
+    verifier.update(stringToSign, 'utf8');
+    const valid = verifier.verify(certificate, String(envelope.Signature), 'base64');
+    return valid ? { valid: true } : { valid: false, reason: 'signature mismatch' };
+  } catch (error) {
+    return {
+      valid: false,
+      reason: `signature check failed: ${(error as Error)?.message}`,
+    };
+  }
+}