actionmailbox 6.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04c16025ca256c2950010193593aed65a1a45cf44246cdde1c0ded958eb9c4ce
+  data.tar.gz: 7bbc944f55aac32b889ef34bb1fc460f2ca5a57c645624c081e3c5c8866894d8
+SHA512:
+  metadata.gz: afded102341376ccdde85f12d8a40c917471a032185de6a415c58efc544fabc90d1f8cd7481965bd6e7d0b1b0adb67d67ecd96b775a9b5235436d3a0bb4764a3
+  data.tar.gz: e401003cf76b5e47e3785617aa8c39325bc9a84ebf650be1e880e29f9a600c6615b81136749fee28773a3ae329541c774deb42ef31a0c6bbf7f3354df1317c5d

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+## Rails 6.0.1 (November 5, 2019) ##
+
+*   No changes.
+
+
+## Rails 6.0.0 (August 16, 2019) ##
+
+*   Fix Bcc header not being included with emails from `create_inbound_email_from` test helpers.
+
+    *jduff*
+
+
+## Rails 6.0.0.rc2 (July 22, 2019) ##
+
+*   No changes.
+
+
+## Rails 6.0.0.rc1 (April 24, 2019) ##
+
+*   No changes.
+
+
+## Rails 6.0.0.beta3 (March 11, 2019) ##
+
+*   No changes.
+
+
+## Rails 6.0.0.beta2 (February 25, 2019) ##
+
+*   Allow skipping incineration of processed emails.
+
+    This can be done by setting `config.action_mailbox.incinerate` to `false`.
+
+    *Pratik Naik*
+
+
+## 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 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,34 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # The base class for all Action Mailbox ingress controllers.
+  class BaseController < ActionController::Base
+    skip_forgery_protection if default_protect_from_forgery
+
+    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 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/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

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # 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 Ingresses::Sendgrid::InboundEmailsController < ActionMailbox::BaseController
+    before_action :authenticate_by_password
+
+    def create
+      ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:email)
+    end
+  end
+end