actionmailbox 0.1.0

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Action Mailbox'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/actionmailbox.gemspec

@@ -0,0 +1,27 @@
+$:.push File.expand_path("lib", __dir__)
+
+# Maintain your gem's version:
+require "action_mailbox/version"
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name     = "actionmailbox"
+  s.version  = ActionMailbox::VERSION
+  s.authors  = ["David Heinemeier Hansson", "George Claghorn"]
+  s.email    = ["david@loudthinking.com", "george@basecamp.com"]
+  s.summary  = "Receive and process incoming emails in Rails"
+  s.homepage = "https://github.com/rails/actionmailbox"
+  s.license  = "MIT"
+
+  s.required_ruby_version = ">= 2.5.0"
+
+  s.add_dependency "rails", ">= 5.2.0"
+
+  s.add_development_dependency "bundler", "~> 1.15"
+  s.add_development_dependency "sqlite3"
+  s.add_development_dependency "byebug"
+  s.add_development_dependency "webmock"
+
+  s.files      = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- test/*`.split("\n")
+end

data/app/controllers/action_mailbox/base_controller.rb

@@ -0,0 +1,43 @@
+# The base class for all Active Mailbox ingress controllers.
+class ActionMailbox::BaseController < ActionController::Base
+  skip_forgery_protection
+
+  def self.prepare
+    # Override in concrete controllers to run code on load.
+  end
+
+  before_action :ensure_configured
+
+  private
+    def ensure_configured
+      unless ActionMailbox.ingress == ingress_name
+        head :not_found
+      end
+    end
+
+    def ingress_name
+      self.class.name.remove(/\AActionMailbox::Ingresses::/, /::InboundEmailsController\z/).underscore.to_sym
+    end
+
+
+    def authenticate_by_password
+      if password.present?
+        http_basic_authenticate_or_request_with username: "actionmailbox", password: password, realm: "Action Mailbox"
+      else
+        raise ArgumentError, "Missing required ingress credentials"
+      end
+    end
+
+    def password
+      Rails.application.credentials.dig(:action_mailbox, :ingress_password) || ENV["RAILS_INBOUND_EMAIL_PASSWORD"]
+    end
+
+
+    # TODO: Extract to ActionController::HttpAuthentication
+    def http_basic_authenticate_or_request_with(username:, password:, realm: nil)
+      authenticate_or_request_with_http_basic(realm || "Application") do |given_username, given_password|
+        ActiveSupport::SecurityUtils.secure_compare(given_username, username) &
+          ActiveSupport::SecurityUtils.secure_compare(given_password, password)
+      end
+    end
+end

data/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb

@@ -0,0 +1,50 @@
+# Ingests inbound emails from Amazon's Simple Email Service (SES).
+#
+# Requires the full RFC 822 message in the +content+ parameter. Authenticates requests by validating their signatures.
+#
+# Returns:
+#
+# - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+# - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+# - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from SES
+# - <tt>422 Unprocessable Entity</tt> if the request is missing the required +content+ parameter
+# - <tt>500 Server Error</tt> if one of the Active Record database, the Active Storage service, or
+#   the Active Job backend is misconfigured or unavailable
+#
+# == Usage
+#
+# 1. Install the {aws-sdk-sns}[https://rubygems.org/gems/aws-sdk-sns] gem:
+#
+#        # Gemfile
+#        gem "aws-sdk-sns", ">= 1.9.0", require: false
+#
+# 2. Tell Action Mailbox to accept emails from SES:
+#
+#        # config/environments/production.rb
+#        config.action_mailbox.ingress = :amazon
+#
+# 3. {Configure SES}[https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications.html]
+#    to deliver emails to your application via POST requests to +/rails/action_mailbox/amazon/inbound_emails+.
+#    If your application lived at <tt>https://example.com</tt>, you would specify the fully-qualified URL
+#    <tt>https://example.com/rails/action_mailbox/amazon/inbound_emails</tt>.
+class ActionMailbox::Ingresses::Amazon::InboundEmailsController < ActionMailbox::BaseController
+  before_action :authenticate
+
+  cattr_accessor :verifier
+
+  def self.prepare
+    self.verifier ||= begin
+      require "aws-sdk-sns/message_verifier"
+      Aws::SNS::MessageVerifier.new
+    end
+  end
+
+  def create
+    ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:content)
+  end
+
+  private
+    def authenticate
+      head :unauthorized unless verifier.authentic?(request.body)
+    end
+end

data/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb

@@ -0,0 +1,99 @@
+# Ingests inbound emails from Mailgun. Requires the following parameters:
+#
+# - +body-mime+: The full RFC 822 message
+# - +timestamp+: The current time according to Mailgun as the number of seconds passed since the UNIX epoch
+# - +token+: A randomly-generated, 50-character string
+# - +signature+: A hexadecimal HMAC-SHA256 of the timestamp concatenated with the token, generated using the Mailgun API key
+#
+# Authenticates requests by validating their signatures.
+#
+# Returns:
+#
+# - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+# - <tt>401 Unauthorized</tt> if the request's signature could not be validated, or if its timestamp is more than 2 minutes old
+# - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from Mailgun
+# - <tt>422 Unprocessable Entity</tt> if the request is missing required parameters
+# - <tt>500 Server Error</tt> if the Mailgun API key is missing, or one of the Active Record database,
+#   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+#
+# == Usage
+#
+# 1. Give Action Mailbox your {Mailgun API key}[https://help.mailgun.com/hc/en-us/articles/203380100-Where-can-I-find-my-API-key-and-SMTP-credentials-]
+#    so it can authenticate requests to the Mailgun ingress.
+#
+#    Use <tt>rails credentials:edit</tt> to add your API key to your application's encrypted credentials under
+#    +action_mailbox.mailgun_api_key+, where Action Mailbox will automatically find it:
+#
+#        action_mailbox:
+#          mailgun_api_key: ...
+#
+#    Alternatively, provide your API key in the +MAILGUN_INGRESS_API_KEY+ environment variable.
+#
+# 2. Tell Action Mailbox to accept emails from Mailgun:
+#
+#        # config/environments/production.rb
+#        config.action_mailbox.ingress = :mailgun
+#
+# 3. {Configure Mailgun}[https://documentation.mailgun.com/en/latest/user_manual.html#receiving-forwarding-and-storing-messages]
+#    to forward inbound emails to `/rails/action_mailbox/mailgun/inbound_emails/mime`.
+#
+#    If your application lived at <tt>https://example.com</tt>, you would specify the fully-qualified URL
+#    <tt>https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime</tt>.
+class ActionMailbox::Ingresses::Mailgun::InboundEmailsController < ActionMailbox::BaseController
+  before_action :authenticate
+
+  def create
+    ActionMailbox::InboundEmail.create_and_extract_message_id! params.require("body-mime")
+  end
+
+  private
+    def authenticate
+      head :unauthorized unless authenticated?
+    end
+
+    def authenticated?
+      if key.present?
+        Authenticator.new(
+          key:       key,
+          timestamp: params.require(:timestamp),
+          token:     params.require(:token),
+          signature: params.require(:signature)
+        ).authenticated?
+      else
+        raise ArgumentError, <<~MESSAGE.squish
+          Missing required Mailgun API key. Set action_mailbox.mailgun_api_key in your application's
+          encrypted credentials or provide the MAILGUN_INGRESS_API_KEY environment variable.
+        MESSAGE
+      end
+    end
+
+    def key
+      Rails.application.credentials.dig(:action_mailbox, :mailgun_api_key) || ENV["MAILGUN_INGRESS_API_KEY"]
+    end
+
+    class Authenticator
+      attr_reader :key, :timestamp, :token, :signature
+
+      def initialize(key:, timestamp:, token:, signature:)
+        @key, @timestamp, @token, @signature = key, Integer(timestamp), token, signature
+      end
+
+      def authenticated?
+        signed? && recent?
+      end
+
+      private
+        def signed?
+          ActiveSupport::SecurityUtils.secure_compare signature, expected_signature
+        end
+
+        # Allow for 2 minutes of drift between Mailgun time and local server time.
+        def recent?
+          Time.at(timestamp) >= 2.minutes.ago
+        end
+
+        def expected_signature
+          OpenSSL::HMAC.hexdigest OpenSSL::Digest::SHA256.new, key, "#{timestamp}#{token}"
+        end
+    end
+end

data/app/controllers/action_mailbox/ingresses/mandrill/inbound_emails_controller.rb

@@ -0,0 +1,78 @@
+# Ingests inbound emails from Mandrill.
+#
+# Requires a +mandrill_events+ parameter containing a JSON array of Mandrill inbound email event objects.
+# Each event is expected to have a +msg+ object containing a full RFC 822 message in its +raw_msg+ property.
+#
+# Returns:
+#
+# - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+# - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+# - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from Mandrill
+# - <tt>422 Unprocessable Entity</tt> if the request is missing required parameters
+# - <tt>500 Server Error</tt> if the Mandrill API key is missing, or one of the Active Record database,
+#   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+class ActionMailbox::Ingresses::Mandrill::InboundEmailsController < ActionMailbox::BaseController
+  before_action :authenticate
+
+  def create
+    raw_emails.each { |raw_email| ActionMailbox::InboundEmail.create_and_extract_message_id! raw_email }
+    head :ok
+  rescue JSON::ParserError => error
+    logger.error error.message
+    head :unprocessable_entity
+  end
+
+  private
+    def raw_emails
+      events.select { |event| event["event"] == "inbound" }.collect { |event| event.dig("msg", "raw_msg") }
+    end
+
+    def events
+      JSON.parse params.require(:mandrill_events)
+    end
+
+
+    def authenticate
+      head :unauthorized unless authenticated?
+    end
+
+    def authenticated?
+      if key.present?
+        Authenticator.new(request, key).authenticated?
+      else
+        raise ArgumentError, <<~MESSAGE.squish
+          Missing required Mandrill API key. Set action_mailbox.mandrill_api_key in your application's
+          encrypted credentials or provide the MANDRILL_INGRESS_API_KEY environment variable.
+        MESSAGE
+      end
+    end
+
+    def key
+      Rails.application.credentials.dig(:action_mailbox, :mandrill_api_key) || ENV["MANDRILL_INGRESS_API_KEY"]
+    end
+
+    class Authenticator
+      attr_reader :request, :key
+
+      def initialize(request, key)
+        @request, @key = request, key
+      end
+
+      def authenticated?
+        ActiveSupport::SecurityUtils.secure_compare given_signature, expected_signature
+      end
+
+      private
+        def given_signature
+          request.headers["X-Mandrill-Signature"]
+        end
+
+        def expected_signature
+          Base64.strict_encode64 OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, key, message)
+        end
+
+        def message
+          request.url + request.POST.sort.flatten.join
+        end
+    end
+end

data/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb

@@ -0,0 +1,55 @@
+# Ingests inbound emails relayed from Postfix.
+#
+# Authenticates requests using HTTP basic access authentication. The username is always +actionmailbox+, and the
+# password is read from the application's encrypted credentials or an environment variable. See the Usage section below.
+#
+# Note that basic authentication is insecure over unencrypted HTTP. An attacker that intercepts cleartext requests to
+# the Postfix ingress can learn its password. You should only use the Postfix ingress over HTTPS.
+#
+# Returns:
+#
+# - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+# - <tt>401 Unauthorized</tt> if the request could not be authenticated
+# - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from Postfix
+# - <tt>415 Unsupported Media Type</tt> if the request does not contain an RFC 822 message
+# - <tt>500 Server Error</tt> if the ingress password is not configured, or if one of the Active Record database,
+#   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+#
+# == Usage
+#
+# 1. Tell Action Mailbox to accept emails from Postfix:
+#
+#        # config/environments/production.rb
+#        config.action_mailbox.ingress = :postfix
+#
+# 2. Generate a strong password that Action Mailbox can use to authenticate requests to the Postfix ingress.
+#
+#    Use <tt>rails credentials:edit</tt> to add the password to your application's encrypted credentials under
+#    +action_mailbox.ingress_password+, where Action Mailbox will automatically find it:
+#
+#        action_mailbox:
+#          ingress_password: ...
+#
+#    Alternatively, provide the password in the +RAILS_INBOUND_EMAIL_PASSWORD+ environment variable.
+#
+# 3. {Configure Postfix}{https://serverfault.com/questions/258469/how-to-configure-postfix-to-pipe-all-incoming-email-to-a-script}
+#    to pipe inbound emails to <tt>bin/rails action_mailbox:ingress:postfix</tt>, providing the +URL+ of the Postfix
+#    ingress and the +INGRESS_PASSWORD+ you previously generated.
+#
+#    If your application lived at <tt>https://example.com</tt>, the full command would look like this:
+#
+#        URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=... bin/rails action_mailbox:ingress:postfix
+class ActionMailbox::Ingresses::Postfix::InboundEmailsController < ActionMailbox::BaseController
+  before_action :authenticate_by_password, :require_valid_rfc822_message
+
+  def create
+    ActionMailbox::InboundEmail.create_and_extract_message_id! request.body.read
+  end
+
+  private
+    def require_valid_rfc822_message
+      unless request.content_type == "message/rfc822"
+        head :unsupported_media_type
+      end
+    end
+end

data/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb

@@ -0,0 +1,50 @@
+# Ingests inbound emails from SendGrid. Requires an +email+ parameter containing a full RFC 822 message.
+#
+# Authenticates requests using HTTP basic access authentication. The username is always +actionmailbox+, and the
+# password is read from the application's encrypted credentials or an environment variable. See the Usage section below.
+#
+# Note that basic authentication is insecure over unencrypted HTTP. An attacker that intercepts cleartext requests to
+# the SendGrid ingress can learn its password. You should only use the SendGrid ingress over HTTPS.
+#
+# Returns:
+#
+# - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+# - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+# - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from SendGrid
+# - <tt>422 Unprocessable Entity</tt> if the request is missing the required +email+ parameter
+# - <tt>500 Server Error</tt> if the ingress password is not configured, or if one of the Active Record database,
+#   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+#
+# == Usage
+#
+# 1. Tell Action Mailbox to accept emails from SendGrid:
+#
+#        # config/environments/production.rb
+#        config.action_mailbox.ingress = :sendgrid
+#
+# 2. Generate a strong password that Action Mailbox can use to authenticate requests to the SendGrid ingress.
+#
+#    Use <tt>rails credentials:edit</tt> to add the password to your application's encrypted credentials under
+#    +action_mailbox.ingress_password+, where Action Mailbox will automatically find it:
+#
+#        action_mailbox:
+#          ingress_password: ...
+#
+#    Alternatively, provide the password in the +RAILS_INBOUND_EMAIL_PASSWORD+ environment variable.
+#
+# 3. {Configure SendGrid Inbound Parse}{https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/}
+#    to forward inbound emails to +/rails/action_mailbox/sendgrid/inbound_emails+ with the username +actionmailbox+ and
+#    the password you previously generated. If your application lived at <tt>https://example.com</tt>, you would
+#    configure SendGrid with the following fully-qualified URL:
+#
+#        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
+#
+#    *NOTE:* When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled *"Post the raw,
+#    full MIME message."* Action Mailbox needs the raw MIME message to work.
+class ActionMailbox::Ingresses::Sendgrid::InboundEmailsController < ActionMailbox::BaseController
+  before_action :authenticate_by_password
+
+  def create
+    ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:email)
+  end
+end

data/app/controllers/rails/conductor/action_mailbox/inbound_emails_controller.rb

@@ -0,0 +1,27 @@
+class Rails::Conductor::ActionMailbox::InboundEmailsController < Rails::Conductor::BaseController
+  def index
+    @inbound_emails = ActionMailbox::InboundEmail.order(created_at: :desc)
+  end
+
+  def new
+  end
+
+  def show
+    @inbound_email = ActionMailbox::InboundEmail.find(params[:id])
+  end
+
+  def create
+    inbound_email = create_inbound_email(new_mail)
+    redirect_to main_app.rails_conductor_inbound_email_url(inbound_email)
+  end
+
+  private
+    def new_mail
+      Mail.new params.require(:mail).permit(:from, :to, :cc, :bcc, :in_reply_to, :subject, :body).to_h
+    end
+
+    def create_inbound_email(mail)
+      ActionMailbox::InboundEmail.create! raw_email: \
+        { io: StringIO.new(mail.to_s), filename: 'inbound.eml', content_type: 'message/rfc822', identify: false }
+    end
+end