actionmailbox 6.0.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: beb8145f8e8da8e158c0811ec7522495e294d13727c4960ec1810654d17c1299
+  data.tar.gz: f01ffcc7f94e19ffac7f01c4036886d6ad8ee9e57292e12920a1c98b954a7ce4
+SHA512:
+  metadata.gz: 9219f0eb8d3f102068e9ea9b8c48e223e57ac79348d76c5418eb2e85ba797df68b3f8f8a0ee0f6881044c64ea38a3d0264d123550aef9aa5ac958e5f9d420d51
+  data.tar.gz: 32707b7b14716c46e76069a189275fd8f8ee064aa164cdbecccce869579719163a6e0ec33336dda9417363923a9e2d4958dffa916a0d9ad2e7ade9ae96e11c97

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## Rails 6.0.0.beta1 (January 18, 2019) ##
+
+*   Added to Rails.
+
+    *DHH*

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Basecamp, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,13 @@
+# Action Mailbox
+
+Action Mailbox routes incoming emails to controller-like mailboxes for processing in Rails. It ships with ingresses for Amazon SES, Mailgun, Mandrill, Postmark, and SendGrid. You can also handle inbound mails directly via the built-in Exim, Postfix, and Qmail ingresses.
+
+The inbound emails are turned into `InboundEmail` records using Active Record and feature lifecycle tracking, storage of the original email on cloud storage via Active Storage, and responsible data handling with on-by-default incineration.
+
+These inbound emails are routed asynchronously using Active Job to one or several dedicated mailboxes, which are capable of interacting directly with the rest of your domain model.
+
+You can read more about Action Mailbox in the [Action Mailbox Basics](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) guide.
+
+## License
+
+Action Mailbox is released under the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/action_mailbox/base_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # The base class for all Action Mailbox ingress controllers.
+  class BaseController < ActionController::Base
+    skip_forgery_protection
+
+    before_action :ensure_configured
+
+    def self.prepare
+      # Override in concrete controllers to run code on load.
+    end
+
+    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 name: "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
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # 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 Ingresses::Amazon::InboundEmailsController < BaseController
+    before_action :authenticate
+
+    cattr_accessor :verifier
+
+    def self.prepare
+      self.verifier ||= begin
+        require "aws-sdk-sns"
+        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
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # 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 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
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # 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 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
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # Ingests inbound emails from Postmark. Requires a +RawEmail+ 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 Postmark ingress can learn its password. You should only use the Postmark 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 Postmark
+  # - <tt>422 Unprocessable Entity</tt> if the request is missing the required +RawEmail+ 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 Postmark:
+  #
+  #        # config/environments/production.rb
+  #        config.action_mailbox.ingress = :postmark
+  #
+  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the Postmark 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 Postmark}[https://postmarkapp.com/manual#configure-your-inbound-webhook-url] to forward inbound emails
+  #    to +/rails/action_mailbox/postmark/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 your
+  #    Postmark inbound webhook with the following fully-qualified URL:
+  #
+  #        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/postmark/inbound_emails
+  #
+  #    *NOTE:* When configuring your Postmark inbound webhook, be sure to check the box labeled *"Include raw email
+  #    content in JSON payload"*. Action Mailbox needs the raw email content to work.
+  class Ingresses::Postmark::InboundEmailsController < ActionMailbox::BaseController
+    before_action :authenticate_by_password
+
+    def create
+      ActionMailbox::InboundEmail.create_and_extract_message_id! params.require("RawEmail")
+    rescue ActionController::ParameterMissing => error
+      logger.error <<~MESSAGE
+        #{error.message}
+
+        When configuring your Postmark inbound webhook, be sure to check the box
+        labeled "Include raw email content in JSON payload".
+      MESSAGE
+      head :unprocessable_entity
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # Ingests inbound emails relayed from an SMTP server.
+  #
+  # 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 ingress can learn its password. You should only use this 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 relayed from an SMTP server
+  # - <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 an SMTP relay:
+  #
+  #        # config/environments/production.rb
+  #        config.action_mailbox.ingress = :relay
+  #
+  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the 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 your SMTP server to pipe inbound emails to the appropriate ingress command, providing the +URL+ of the
+  #    relay ingress and the +INGRESS_PASSWORD+ you previously generated.
+  #
+  #    If your application lives at <tt>https://example.com</tt>, you would configure the Postfix SMTP server to pipe
+  #    inbound emails to the following command:
+  #
+  #        bin/rails action_mailbox:ingress:postfix URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=...
+  #
+  #    Built-in ingress commands are available for these popular SMTP servers:
+  #
+  #    - Exim (<tt>bin/rails action_mailbox:ingress:exim)
+  #    - Postfix (<tt>bin/rails action_mailbox:ingress:postfix)
+  #    - Qmail (<tt>bin/rails action_mailbox:ingress:qmail)
+  class Ingresses::Relay::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
+end