actionmailbox 0.1.0 → 6.0.0.beta1

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

@@ -1,99 +1,103 @@
-# 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
+# frozen_string_literal: true
 
-  def create
-    ActionMailbox::InboundEmail.create_and_extract_message_id! params.require("body-mime")
-  end
+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
 
-  private
-    def authenticate
-      head :unauthorized unless authenticated?
+    def create
+      ActionMailbox::InboundEmail.create_and_extract_message_id! params.require("body-mime")
     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
+    private
+      def authenticate
+        head :unauthorized unless authenticated?
       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
+      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 authenticated?
-        signed? && recent?
+      def key
+        Rails.application.credentials.dig(:action_mailbox, :mailgun_api_key) || ENV["MAILGUN_INGRESS_API_KEY"]
       end
 
-      private
-        def signed?
-          ActiveSupport::SecurityUtils.secure_compare signature, expected_signature
-        end
+      class Authenticator
+        attr_reader :key, :timestamp, :token, :signature
 
-        # Allow for 2 minutes of drift between Mailgun time and local server time.
-        def recent?
-          Time.at(timestamp) >= 2.minutes.ago
+        def initialize(key:, timestamp:, token:, signature:)
+          @key, @timestamp, @token, @signature = key, Integer(timestamp), token, signature
         end
 
-        def expected_signature
-          OpenSSL::HMAC.hexdigest OpenSSL::Digest::SHA256.new, key, "#{timestamp}#{token}"
+        def authenticated?
+          signed? && recent?
         end
-    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

@@ -1,78 +1,82 @@
-# 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
+# frozen_string_literal: true
 
-  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
+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 authenticate
-      head :unauthorized unless authenticated?
+    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
 
-    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
+    private
+      def raw_emails
+        events.select { |event| event["event"] == "inbound" }.collect { |event| event.dig("msg", "raw_msg") }
       end
-    end
 
-    def key
-      Rails.application.credentials.dig(:action_mailbox, :mandrill_api_key) || ENV["MANDRILL_INGRESS_API_KEY"]
-    end
+      def events
+        JSON.parse params.require(:mandrill_events)
+      end
 
-    class Authenticator
-      attr_reader :request, :key
 
-      def initialize(request, key)
-        @request, @key = request, key
+      def authenticate
+        head :unauthorized unless authenticated?
       end
 
       def authenticated?
-        ActiveSupport::SecurityUtils.secure_compare given_signature, expected_signature
+        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
 
-      private
-        def given_signature
-          request.headers["X-Mandrill-Signature"]
-        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 expected_signature
-          Base64.strict_encode64 OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, key, message)
+        def initialize(request, key)
+          @request, @key = request, key
         end
 
-        def message
-          request.url + request.POST.sort.flatten.join
+        def authenticated?
+          ActiveSupport::SecurityUtils.secure_compare given_signature, expected_signature
         end
-    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