mailcore 0.1.0.alpha.1

data/exemplos/sinatra.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require 'mailcore'
+require 'openssl'
+require 'digest'
+
+class ExemploMailcoreSinatra < Sinatra::Base
+  disable :show_exceptions, :dump_errors, :logging, :sessions, :static
+  set :raise_errors, false
+
+  def self.construir(ambiente: ENV, cliente: nil)
+    chave, token = ambiente.values_at('MAILCORE_API_KEY', 'TOKEN_APLICACAO')
+    remetente, destinatario = ambiente.values_at('MAILCORE_REMETENTE', 'MAILCORE_DESTINATARIO')
+    valido = chave.is_a?(String) && chave.match?(/\A[\x21-\x7e]{1,512}\z/) &&
+             token.is_a?(String) && token.match?(/\A[A-Za-z0-9_-]{32,256}\z/) &&
+             [remetente, destinatario].all? { |valor| valor.is_a?(String) && valor.match?(/\A[^\r\n\x00]{1,320}\z/) }
+    raise ArgumentError, 'Configure as credenciais e os endereços fixos da aplicação.' unless valido
+    resumo = Digest::SHA256.digest(token)
+    if OpenSSL.fixed_length_secure_compare(resumo, Digest::SHA256.digest(chave))
+      raise ArgumentError, 'Use credenciais diferentes para a aplicação e a API.'
+    end
+    sdk = cliente || Mailcore::Cliente.new(chave_api: chave, url_base: ambiente.fetch('MAILCORE_API_URL', Mailcore.configuracao.url_base))
+    Class.new(self) do
+      set :cliente_mailcore, sdk
+      set :resumo_token, resumo
+      set :pedido_mailcore, { remetente: remetente, destinatarios: [destinatario].freeze,
+                             assunto: 'Mensagem de exemplo', texto: 'Integração Mailcore com Sinatra.' }.freeze
+    end
+  end
+
+  before do
+    content_type :json
+    headers 'cache-control' => 'no-store'
+  end
+
+  post '/enviar' do
+    autorizacao = request.env['HTTP_AUTHORIZATION'].to_s.match(/\ABearer ([A-Za-z0-9_-]{32,256})\z/)
+    halt 401, JSON.generate(erro: 'Acesso não autorizado.') unless autorizacao &&
+      OpenSSL.fixed_length_secure_compare(Digest::SHA256.digest(autorizacao[1]), settings.resumo_token)
+    chave = request.env['HTTP_IDEMPOTENCY_KEY'].to_s
+    halt 400, JSON.generate(erro: 'Informe uma chave de idempotência válida.') unless chave.match?(/\A[\x21-\x7e]{1,256}\z/) && !chave.include?(',')
+    halt 415, JSON.generate(erro: 'Envie um objeto JSON.') unless request.media_type == 'application/json'
+    corpo = request.body.read(4097).to_s.dup
+    halt 413, JSON.generate(erro: 'Corpo da requisição excede o limite.') if corpo.bytesize > 4096
+    corpo.force_encoding(Encoding::UTF_8)
+    halt 400, JSON.generate(erro: 'Envie um objeto JSON válido.') unless corpo.valid_encoding?
+    halt 400, JSON.generate(erro: 'Envie um objeto JSON válido.') unless JSON.parse(corpo).is_a?(Hash)
+    resposta = settings.cliente_mailcore.emails.enviar(settings.pedido_mailcore.dup, chave_idempotencia: chave)
+    dados = resposta.dados
+    halt 502, JSON.generate(erro: 'Resposta de aceitação inválida.') unless dados.is_a?(Hash) &&
+      dados[:id].is_a?(String) && !dados[:id].empty? && dados[:estado].is_a?(String)
+    status 202
+    JSON.generate(id: dados[:id], estado: dados[:estado])
+  rescue JSON::ParserError
+    halt 400, JSON.generate(erro: 'Envie um objeto JSON válido.')
+  rescue Mailcore::ErroApi => erro
+    halt(erro.status.to_i.between?(400, 599) ? erro.status : 502, JSON.generate(erro: 'Não foi possível aceitar a mensagem.'))
+  rescue Mailcore::Erro, Mailcore::ErroConfiguracao
+    halt 502, JSON.generate(erro: 'Não foi possível confirmar a aceitação da mensagem.')
+  end
+
+  not_found { JSON.generate(erro: 'Rota não encontrada.') }
+  error { JSON.generate(erro: 'Não foi possível concluir a operação.') }
+end

data/lib/mailcore/action_mailer.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'mailcore'
+
+module Mailcore
+  # Converte mensagens Mail sem implementar uma fila ou um transporte SMTP.
+  class EntregaActionMailer
+    CAMPOS_CLIENTE = %i[chave_api url_base tempo_limite tempo_conexao certificado_ca limite_resposta_bytes].freeze
+    CABECALHOS_RESERVADOS = %w[
+      from to cc bcc sender return-path reply-to subject message-id in-reply-to
+      references date received mime-version content-type content-transfer-encoding
+      authentication-results dkim-signature authorization mailcore-opcoes
+      mailcore_opcoes
+    ].freeze
+
+    attr_reader :settings
+
+    def initialize(opcoes = {})
+      @settings = { return_response: true }.merge(opcoes.transform_keys(&:to_sym))
+    end
+
+    def deliver!(mensagem)
+      opcoes = opcoes_mensagem(mensagem)
+      pedido = converter(mensagem)
+      pedido[:tags] = opcoes[:tags] if opcoes.key?(:tags)
+      pedido[:agendada_em] = opcoes[:agendada_em] if opcoes.key?(:agendada_em)
+      chave = opcoes.fetch(:chave_idempotencia, settings[:chave_idempotencia])
+      argumentos = chave.nil? ? {} : { chave_idempotencia: chave }
+      resposta = cliente.emails.enviar(pedido, **argumentos)
+      identificador = resposta.dados[:id]
+      mensagem.message_id = identificador if identificador
+      resposta
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def cliente
+      return settings[:cliente] if settings[:cliente]
+
+      configuracao = settings.select { |nome, _| CAMPOS_CLIENTE.include?(nome) }
+      return Mailcore.cliente if configuracao.empty?
+
+      Mailcore::Cliente.new(**Mailcore.configuracao.opcoes_cliente.merge(configuracao))
+    end
+
+    def opcoes_mensagem(mensagem)
+      valor = mensagem[:mailcore_opcoes]&.unparsed_value
+      return {} if valor.nil?
+      raise ArgumentError, 'mailcore_opcoes deve ser um Hash.' unless valor.is_a?(Hash)
+
+      opcoes = valor.transform_keys(&:to_sym)
+      desconhecidas = opcoes.keys - %i[chave_idempotencia tags agendada_em]
+      raise ArgumentError, 'Opção de mensagem não reconhecida.' unless desconhecidas.empty?
+
+      opcoes
+    end
+
+    def converter(mensagem)
+      remetentes = Array(mensagem[:from]&.formatted)
+      raise ArgumentError, 'Informe exatamente um remetente.' unless remetentes.length == 1
+      raise ArgumentError, 'Informe no máximo um endereço de resposta.' if Array(mensagem.reply_to).length > 1
+
+      pedido = { remetente: remetentes.first, destinatarios: Array(mensagem.to), assunto: mensagem.subject }
+      pedido[:cc] = mensagem.cc if mensagem.cc && !mensagem.cc.empty?
+      pedido[:cco] = mensagem.bcc if mensagem.bcc && !mensagem.bcc.empty?
+      pedido[:responder_para] = mensagem.reply_to.first if mensagem.reply_to && !mensagem.reply_to.empty?
+      pedido.merge!(conteudos(mensagem))
+      cabecalhos = mensagem.header.fields.each_with_object({}) do |campo, resultado|
+        nome = campo.name.to_s
+        normalizado = nome.downcase
+        next if CABECALHOS_RESERVADOS.include?(normalizado)
+        next if normalizado.start_with?('x-postal-', 'x-mailcore-', 'arc-', 'content-')
+
+        resultado[nome] = campo.decoded.to_s
+      end
+      pedido[:cabecalhos] = cabecalhos unless cabecalhos.empty?
+      anexos = mensagem.attachments.map do |parte|
+        anexo = {
+          nome: parte.filename,
+          tipo_conteudo: parte.mime_type || 'application/octet-stream',
+          conteudo_base64: Base64.strict_encode64(parte.body.decoded.b)
+        }
+        anexo[:id_conteudo] = parte.cid if parte.inline?
+        anexo
+      end
+      pedido[:anexos] = anexos unless anexos.empty?
+      pedido
+    end
+
+    def conteudos(mensagem)
+      if mensagem.multipart?
+        partes = partes_de_corpo(mensagem)
+        texto = partes.find { |parte| parte.mime_type == 'text/plain' }
+        html = partes.find { |parte| parte.mime_type == 'text/html' }
+        {}.tap do |resultado|
+          resultado[:texto] = decodificar_texto(texto) if texto
+          resultado[:html] = decodificar_texto(html) if html
+        end
+      elsif mensagem.mime_type == 'text/html'
+        { html: decodificar_texto(mensagem) }
+      elsif mensagem.mime_type.nil? || mensagem.mime_type == 'text/plain'
+        { texto: decodificar_texto(mensagem) }
+      else
+        raise ArgumentError, 'Use conteúdo de mensagem em texto ou HTML.'
+      end
+    end
+
+    def decodificar_texto(parte)
+      parte.body.decoded.dup.force_encoding(parte.charset || 'UTF-8').encode(Encoding::UTF_8)
+    end
+
+    def partes_de_corpo(parte)
+      return [] if parte.attachment?
+      return [parte] unless parte.multipart?
+
+      parte.parts.flat_map { |filha| partes_de_corpo(filha) }
+    end
+  end
+end

data/lib/mailcore/assinatura.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'json'
+
+module Mailcore
+  module Assinatura
+    module_function
+
+    # O corpo precisa ser o recebido na rede, antes de interpretar ou normalizar JSON.
+    def verificar(corpo_bruto:, cabecalhos:, segredo:, agora: Time.now, tolerancia: 300)
+      unless corpo_bruto.is_a?(String) && corpo_bruto.bytesize <= 8 * 1024 * 1024 &&
+             segredo.is_a?(String) && segredo.start_with?('whsec_') && segredo.bytesize <= 1024 &&
+             tolerancia.is_a?(Integer) && tolerancia.between?(1, 300)
+        falhar
+      end
+      recebidos = {}
+      cabecalhos.each do |nome, valor|
+        nome = nome.to_s.downcase.tr('_', '-').delete_prefix('http-')
+        next unless %w[svix-id svix-timestamp svix-signature].include?(nome)
+
+        falhar if recebidos.key?(nome) || !valor.is_a?(String)
+        recebidos[nome] = valor
+      end
+      id = recebidos['svix-id']
+      instante = recebidos['svix-timestamp']
+      assinaturas = recebidos['svix-signature']
+      falhar unless id&.match?(/\A[\x21-\x7e]{1,256}\z/) &&
+                    instante&.match?(/\A[1-9][0-9]{0,15}\z/) &&
+                    assinaturas && assinaturas.bytesize <= 4096 &&
+                    (agora.to_i - instante.to_i).abs <= tolerancia
+
+      chave = Base64.strict_decode64(segredo.delete_prefix('whsec_'))
+      falhar if chave.bytesize < 16
+      esperado = OpenSSL::HMAC.digest('SHA256', chave, "#{id}.#{instante}.".b + corpo_bruto.b)
+      valido = assinaturas.split(' ').first(32).any? do |assinatura|
+        versao, valor = assinatura.split(',', 2)
+        next false unless versao == 'v1' && valor
+
+        begin
+          recebido = Base64.strict_decode64(valor)
+          recebido.bytesize == esperado.bytesize && OpenSSL.fixed_length_secure_compare(recebido, esperado)
+        rescue ArgumentError
+          false
+        end
+      end
+      falhar unless valido
+      evento = JSON.parse(corpo_bruto, symbolize_names: true)
+      falhar unless evento.is_a?(Hash) && evento[:type].is_a?(String) &&
+                    evento[:created_at].is_a?(String) && evento.key?(:data)
+      evento
+    rescue ErroAssinatura
+      raise
+    rescue StandardError
+      falhar
+    end
+
+    def falhar
+      raise ErroAssinatura.new('Não foi possível verificar a autenticidade do webhook.',
+                              codigo: 'assinatura_invalida'), cause: nil
+    end
+  end
+end

data/lib/mailcore/cliente.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mailcore
+  class Cliente
+    RECURSOS = {
+      emails: Recursos::Emails, lotes: Recursos::Lotes, dominios: Recursos::Dominios,
+      chaves_api: Recursos::ChavesApi, contatos: Recursos::Contatos,
+      segmentos: Recursos::Segmentos, topicos: Recursos::Topicos,
+      propriedades_contatos: Recursos::PropriedadesContatos, modelos: Recursos::Modelos,
+      webhooks: Recursos::Webhooks, campanhas: Recursos::Campanhas,
+      automacoes: Recursos::Automacoes, eventos: Recursos::Eventos,
+      recebimento: Recursos::Recebimento, caixas: Recursos::Caixas, cli: Recursos::CliMailcore
+    }.freeze
+    attr_reader(*RECURSOS.keys)
+
+    def initialize(chave_api: -> { ENV['MAILCORE_API_KEY'] }, **opcoes)
+      transporte = Transporte.new(chave_api: chave_api, **opcoes)
+      RECURSOS.each do |nome, classe|
+        instance_variable_set("@#{nome}", classe.new(transporte))
+      end
+    end
+
+    def inspect
+      '#<Mailcore::Cliente credenciais=protegidas>'
+    end
+  end
+end

data/lib/mailcore/configuracao.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mailcore
+  class Configuracao
+    attr_accessor :chave_api, :url_base, :tempo_limite, :tempo_conexao,
+                  :limite_resposta_bytes, :certificado_ca, :permitir_http_local,
+                  :segredo_webhook
+
+    def initialize
+      @chave_api = -> { ENV['MAILCORE_API_KEY'] }
+      @url_base = 'https://mailcore.com.br/v1'
+      @tempo_limite = 30
+      @tempo_conexao = 10
+      @limite_resposta_bytes = 16 * 1024 * 1024
+      @permitir_http_local = false
+      @certificado_ca = nil
+      @segredo_webhook = -> { ENV['MAILCORE_WEBHOOK_SECRET'] }
+    end
+
+    def opcoes_cliente
+      { chave_api: chave_api, url_base: url_base, tempo_limite: tempo_limite,
+        tempo_conexao: tempo_conexao, limite_resposta_bytes: limite_resposta_bytes,
+        certificado_ca: certificado_ca, permitir_http_local: permitir_http_local }
+    end
+
+    def inspect
+      '#<Mailcore::Configuracao credenciais=protegidas>'
+    end
+  end
+end

data/lib/mailcore/engine.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+require 'action_mailbox/engine'
+require 'mail'
+require 'mailcore'
+require 'mailcore/limite_ingress'
+
+module Mailcore
+  class ErroEnvelopeActionMailbox < ArgumentError; end
+
+  # Preserva os bytes MIME e acrescenta somente o envelope autenticado do evento.
+  class MensagemActionMailbox
+    def initialize(email_id:, destinatarios:, cliente: Mailcore.cliente)
+      @email_id = email_id
+      @destinatarios = validar_destinatarios(destinatarios)
+      @cliente = cliente
+    end
+
+    def original
+      fonte = @cliente.recebimento.baixar_original(@email_id).dados
+      unless fonte.is_a?(String) && (fonte.include?("\r\n\r\n") || fonte.include?("\n\n"))
+        raise Mailcore::Erro, 'O original recebido não contém uma mensagem MIME válida.'
+      end
+
+      prefixo = @destinatarios.sort.map { |endereco| "X-Original-To: #{endereco}\r\n" }.join.b
+      prefixo + fonte.b
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def validar_destinatarios(destinatarios)
+      unless destinatarios.is_a?(Array) && !destinatarios.empty? && destinatarios.length <= 100
+        raise ErroEnvelopeActionMailbox, 'O evento deve informar os destinatários do envelope.'
+      end
+
+      destinatarios.each do |endereco|
+        unless endereco.is_a?(String) && endereco.bytesize <= 254 &&
+               endereco.bytes.all? { |byte| byte.between?(33, 126) }
+          raise ErroEnvelopeActionMailbox, 'Destinatário de envelope inválido.'
+        end
+        analisado = Mail::Address.new(endereco)
+        unless analisado.address == endereco && analisado.local && analisado.domain
+          raise ErroEnvelopeActionMailbox, 'Destinatário de envelope inválido.'
+        end
+      end
+      destinatarios.uniq
+    rescue Mail::Field::ParseError
+      raise ErroEnvelopeActionMailbox, 'Destinatário de envelope inválido.'
+    end
+  end
+
+  class Engine < ::Rails::Engine
+    config.root = File.expand_path('../..', __dir__)
+
+    initializer 'mailcore.action_mailbox.limite' do |aplicacao|
+      aplicacao.middleware.insert_before 0, ::Mailcore::LimiteIngress
+    end
+
+    initializer 'mailcore.action_mailbox.rotas' do |aplicacao|
+      aplicacao.routes.append do
+        post '/rails/action_mailbox/mailcore/inbound_emails',
+             to: 'action_mailbox/ingresses/mailcore/inbound_emails#create', format: false
+      end
+    end
+  end
+end

data/lib/mailcore/erros.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mailcore
+  class Erro < StandardError
+    attr_reader :codigo, :status, :cabecalhos
+
+    def initialize(mensagem = 'Não foi possível concluir a operação.', codigo: 'erro_mailcore', status: nil, cabecalhos: {})
+      super(mensagem)
+      @codigo = codigo
+      @status = status
+      @cabecalhos = cabecalhos.freeze
+    end
+  end
+
+  class ErroApi < Erro
+    def initialize(codigo:, mensagem:, status:, cabecalhos: {})
+      super(mensagem, codigo: codigo, status: status, cabecalhos: cabecalhos)
+    end
+  end
+
+  class ErroConfiguracao < ArgumentError; end
+  class ErroTransporte < Erro; end
+  class ErroResposta < Erro; end
+  class ErroAssinatura < Erro; end
+end

data/lib/mailcore/limite_ingress.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mailcore
+  # Atua antes dos parsers e da instrumentação do Rails, somente no ingress.
+  class LimiteIngress
+    CAMINHO = '/rails/action_mailbox/mailcore/inbound_emails'
+    LIMITE_BYTES = 256 * 1024
+    FILTROS = [:data, :_json, :authorization, /svix[-_]signature/i].freeze
+
+    def initialize(aplicacao)
+      @aplicacao = aplicacao
+    end
+
+    def call(ambiente)
+      caminho = ambiente['PATH_INFO'].to_s.squeeze('/').delete_suffix('/')
+      return @aplicacao.call(ambiente) unless ambiente['REQUEST_METHOD'] == 'POST' && caminho == CAMINHO
+
+      tamanho = ambiente['CONTENT_LENGTH'].to_s
+      return recusar(413) if tamanho.match?(/\A[0-9]+\z/) && tamanho.to_i > LIMITE_BYTES
+
+      entrada = ambiente['rack.input']
+      return recusar(400) unless entrada.respond_to?(:read)
+
+      begin
+        corpo = entrada.read(LIMITE_BYTES + 1).to_s.b
+      rescue IOError, EOFError
+        return recusar(400)
+      end
+      return recusar(413) if corpo.bytesize > LIMITE_BYTES
+
+      ambiente['rack.input'] = StringIO.new(corpo)
+      ambiente['CONTENT_LENGTH'] = corpo.bytesize.to_s
+      ambiente.delete('HTTP_TRANSFER_ENCODING')
+      ambiente['RAW_POST_DATA'] = corpo
+      # O controller usa somente o corpo assinado. Evita parsing e logs JSON
+      # automáticos anteriores à autenticação, inclusive em JSON malformado.
+      ambiente['action_dispatch.request.request_parameters'] = {}
+      ambiente['action_dispatch.parameter_filter'] = Array(ambiente['action_dispatch.parameter_filter']).dup + FILTROS
+      @aplicacao.call(ambiente)
+    end
+
+    private
+
+    def recusar(status)
+      [status, { 'content-type' => 'application/json; charset=utf-8', 'cache-control' => 'no-store' },
+       ['{"erro":"Não foi possível aceitar o corpo do webhook."}']]
+    end
+  end
+end

data/lib/mailcore/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+require 'mailcore/action_mailer'
+
+module Mailcore
+  class Railtie < ::Rails::Railtie
+    initializer 'mailcore.action_mailer' do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :mailcore, ::Mailcore::EntregaActionMailer
+      end
+    end
+  end
+end
+
+require 'mailcore/engine' if defined?(::ActionMailbox::Engine)

data/lib/mailcore/recursos/automacoes.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mailcore
+  module Recursos
+    class ExecucoesAutomacoes < Base
+      def listar(automacao_id, filtros = {}, **opcoes)
+        executar('GET', "/automations/#{segmento(automacao_id)}/runs", consulta: filtros, **opcoes)
+      end
+
+      def obter(automacao_id, execucao_id, **opcoes)
+        executar('GET', "/automations/#{segmento(automacao_id)}/runs/#{segmento(execucao_id)}", **opcoes)
+      end
+    end
+
+    class Automacoes < Base
+      attr_reader :execucoes
+
+      def initialize(transporte)
+        super(transporte)
+        @execucoes = ExecucoesAutomacoes.new(transporte)
+      end
+
+      def criar(pedido, **opcoes)
+        executar('POST', "/automations", corpo: pedido, **opcoes)
+      end
+
+      def listar(filtros = {}, **opcoes)
+        executar('GET', "/automations", consulta: filtros, **opcoes)
+      end
+
+      def obter(id, **opcoes)
+        executar('GET', "/automations/#{segmento(id)}", **opcoes)
+      end
+
+      def atualizar(id, pedido, **opcoes)
+        executar('PATCH', "/automations/#{segmento(id)}", corpo: pedido, **opcoes)
+      end
+
+      def remover(id, **opcoes)
+        executar('DELETE', "/automations/#{segmento(id)}", **opcoes)
+      end
+
+      def duplicar(id, pedido = {}, **opcoes)
+        executar('POST', "/automations/#{segmento(id)}/duplicate", corpo: pedido, **opcoes)
+      end
+
+      def parar(id, pedido, **opcoes)
+        executar('POST', "/automations/#{segmento(id)}/stop", corpo: pedido, **opcoes)
+      end
+    end
+  end
+end

data/lib/mailcore/recursos/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mailcore
+  module Recursos
+    class Base
+      def initialize(transporte)
+        @transporte = transporte
+      end
+
+      private
+
+      def executar(metodo, caminho, **opcoes, &bloco)
+        @transporte.executar(metodo, caminho, **opcoes, &bloco)
+      end
+
+      # Percent-encoding por byte evita transformar identificadores em caminhos.
+      def segmento(valor)
+        unless valor.is_a?(String) && !valor.empty? && !['.', '..'].include?(valor) &&
+               valor.valid_encoding? && !valor.match?(/[\x00-\x1f\x7f]/)
+          raise ErroConfiguracao, 'Informe um identificador não vazio e sem controles.'
+        end
+        valor.encode(Encoding::UTF_8).bytes.map do |byte|
+          caractere = byte.chr
+          caractere.match?(/[A-Za-z0-9_.~!-]/) ? caractere : format('%%%02X', byte)
+        end.join
+      end
+    end
+  end
+end