helo-email-sdk 1.0.0.pre.beta.6 → 1.0.0.pre.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68419322a6f7e1bb6857bbb9e38f76ca48ea993bd31b1ac11756502b6ee54df6
-  data.tar.gz: c2e11364e91c861ea02c07afa73f5a2a6ee9b930c5e905c01ad6be8637a8b117
+  metadata.gz: cbf62a1f7adb7ad672a9ddf17441cc9cda10e7c199775a4bf3a94785e2f3ba3d
+  data.tar.gz: 434a84d00c0104fb81211d0c105293f2dc1271b59a8872003b761d151247249d
 SHA512:
-  metadata.gz: 249cbacbb3dbba114acc15bca15ebbbb0c530c401f67e332ca8043f6520b6bbbddee848293bf0189c226084ec365a1309e054bc7a90aadb77d0dcf9d943a23c2
-  data.tar.gz: ed1b2ddb57aebe804fe6d75223cd4f8f002c4d0fbdda2cb9cbf0ca9e1b86e180d01d6de6cb8851606fd978afa36fc6c2934b9b102870e097e96c9210615924bc
+  metadata.gz: 5bd2ba8cd121447ead38cbd6916ccdbbd5c755afd4035d0c550fab2c82220ec2f56d80f2ebe5bc23a9352acd21bd7f2f68867a0c3feddfeca322071c51c8bb4a
+  data.tar.gz: 1f3bb34bbcfafc14d5d7d2ec10e9c74a9bc924db20b240e639d30f42423cd70e48f9e9fda9b0736ebc683061cbd9082faa681952131449e01645330e89b82b96

data/README.md

@@ -0,0 +1,125 @@
+# helo-email-sdk
+
+Helo API
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "helo-email-sdk"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Configure the SDK once, at boot:
+
+```ruby
+require "helo-email-sdk"
+
+Helo.configure do |config|
+  config.api_key = ENV.fetch("HELO_API_KEY")
+  config.base_url = "https://api.helohq.com" # optional, this is the default
+end
+```
+
+## Usage
+
+Each API is a class with class-level methods. Responses come back as model objects with
+typed attribute readers.
+
+```ruby
+result = Helo::Channels.list
+```
+
+Methods that take parameters accept a hash:
+
+```ruby
+result = Helo::Channels.list(limit: 10)
+```
+
+See the [API docs](#apis) for every method, with a runnable example each.
+
+### Errors
+
+Failed requests raise `Helo::APIError`:
+
+```ruby
+begin
+  Helo::Channels.list
+rescue Helo::APIError => e
+  e.code    # HTTP status
+  e.detail  # human-readable detail from the API
+  e.errors  # field-level validation errors, when present
+end
+```
+
+## Webhook signature verification
+
+Webhook deliveries are signed with the endpoint's signing key. Verify every delivery before
+acting on it, against the **raw** request body — parsing and re-serializing the JSON changes
+the bytes and the signature will not match.
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    Helo::WebhookSignatures.verify!(
+      request.headers["X-Helo-Webhook-Signature"],
+      request.raw_post, # raw body, exactly as received
+      ENV.fetch("HELO_WEBHOOK_SIGNING_KEY")
+    )
+
+    event = JSON.parse(request.raw_post)
+    # ... handle the event, then acknowledge quickly
+    head :no_content
+  rescue Helo::WebhookSignatures::Error
+    head :bad_request
+  end
+end
+```
+
+`verify!` returns `true` when the signature is valid and raises otherwise. Each rejection has
+its own class, so a stale delivery can be treated differently from a genuinely bad one:
+
+| Exception | Meaning |
+| --- | --- |
+| `MalformedHeaderError` | The header was not in the expected format |
+| `UnsupportedVersionError` | The delivery used a signing scheme this SDK version cannot verify — upgrade the gem |
+| `TimestampSkewError` | Correctly signed, but too old to accept — possible replay, or clock drift |
+| `SignatureMismatchError` | Wrong signing key, or the body was modified in transit |
+
+All four inherit from `Helo::WebhookSignatures::Error`, so `rescue` that one class
+to catch any rejection. If you only want a boolean, use `valid?` instead:
+
+```ruby
+if Helo::WebhookSignatures.valid?(signature_header, raw_body, signing_key)
+  # ...
+end
+```
+
+The signature header may carry several versions at once (`t=...,v1=...,v2=...`) while a new
+signing scheme is being rolled out. This SDK verifies against the newest version it supports
+(`SUPPORTED_VERSIONS`) and ignores elements it does not recognize, so a rollout will not break
+this integration.
+
+To compute a signature yourself — signing a fixture in tests, for example — use
+`Helo::WebhookSignatures.generate(payload, signing_key, timestamp)`.
+
+## APIs
+
+- [Helo::Channels](docs/Channels.md)
+- [Helo::Activity](docs/Activity.md)
+- [Helo::Domains](docs/Domains.md)
+- [Helo::Sending](docs/Sending.md)
+- [Helo::Broadcasts](docs/Broadcasts.md)
+- [Helo::Statistics](docs/Statistics.md)
+- [Helo::Suppressions](docs/Suppressions.md)
+- [Helo::Webhooks](docs/Webhooks.md)

data/lib/helo/models/bounced_details.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Helo
+  class BouncedDetails
+    include Helo::Core::Model
+
+    api_attribute :type, :string, key: "type"
+    api_attribute :sub_type, :string, key: "subType"
+    api_attribute :code, :string, key: "code"
+  end
+end

data/lib/helo/models/bounced_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::BouncedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/models/clicked_details.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Helo
+  class ClickedDetails
+    include Helo::Core::Model
+
+    api_attribute :link, :string, key: "link"
+    api_attribute :ip, :string, key: "ip"
+    api_attribute :country, :string, key: "country"
+    api_attribute :country_code, :string, key: "countryCode"
+    api_attribute :client, Helo::Core::ModelType.new("Helo::ClientDetails"), key: "client"
+    api_attribute :device, Helo::Core::ModelType.new("Helo::DeviceDetails"), key: "device"
+  end
+end

data/lib/helo/models/clicked_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::ClickedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/models/client_details.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Helo
+  class ClientDetails
+    include Helo::Core::Model
+
+    api_attribute :family, :string, key: "family"
+    api_attribute :version, :string, key: "version"
+  end
+end

data/lib/helo/models/complained_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class ComplainedDetails
+    include Helo::Core::Model
+
+    api_attribute :type, :string, key: "type"
+  end
+end

data/lib/helo/models/complained_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::ComplainedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/models/delivered_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class DeliveredDetails
+    include Helo::Core::Model
+
+    api_attribute :response, :string, key: "response"
+  end
+end

data/lib/helo/models/delivered_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::DeliveredDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/models/device_details.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Helo
+  class DeviceDetails
+    include Helo::Core::Model
+
+    api_attribute :brand, :string, key: "brand"
+    api_attribute :family, :string, key: "family"
+    api_attribute :model, :string, key: "model"
+  end
+end

data/lib/helo/models/engagement_details.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class EngagementDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+    api_attribute :country, :string, key: "country"
+    api_attribute :country_code, :string, key: "countryCode"
+    api_attribute :client, Helo::Core::ModelType.new("Helo::ClientDetails"), key: "client"
+    api_attribute :device, Helo::Core::ModelType.new("Helo::DeviceDetails"), key: "device"
+  end
+end

data/lib/helo/models/opened_details.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class OpenedDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+    api_attribute :country, :string, key: "country"
+    api_attribute :country_code, :string, key: "countryCode"
+    api_attribute :client, Helo::Core::ModelType.new("Helo::ClientDetails"), key: "client"
+    api_attribute :device, Helo::Core::ModelType.new("Helo::DeviceDetails"), key: "device"
+  end
+end

data/lib/helo/models/opened_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::OpenedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/models/recipient_event_fields.rb

@@ -5,6 +5,5 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
   end
 end

data/lib/helo/models/resubscribed_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class ResubscribedDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+  end
+end

data/lib/helo/models/resubscribed_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::ResubscribedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/models/unsubscribed_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class UnsubscribedDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+  end
+end

data/lib/helo/models/unsubscribed_webhook_payload.rb

@@ -5,8 +5,8 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::UnsubscribedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"

data/lib/helo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Helo
-  VERSION = "1.0.0-beta.6"
+  VERSION = "1.0.0-beta.7"
 end

data/lib/helo/webhook_signatures.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Helo
+  # Helpers for verifying the signature on an incoming webhook request.
+  module WebhookSignatures
+    # Base class for every rejection reason, so callers that do not care why a
+    # webhook was rejected can rescue this one class.
+    class Error < StandardError; end
+
+    # The header was not in the documented
+    # t={timestamp},v{version}={signature} form.
+    class MalformedHeaderError < Error; end
+
+    # The header carried only signing schemes this SDK does not know how to
+    # verify. Upgrading the SDK is the fix; see SUPPORTED_VERSIONS.
+    class UnsupportedVersionError < Error; end
+
+    # The signature was correctly formed but its timestamp is too far from the
+    # current time, so it may be a replay.
+    class TimestampSkewError < Error; end
+
+    # The signature did not match the body, either because the body was tampered
+    # with or the signing key is wrong.
+    class SignatureMismatchError < Error; end
+
+    # Signing schemes this SDK can verify. The signature header may carry several
+    # versions at once (t=...,v1=...,v2=...) so that a new scheme can be rolled
+    # out while receivers upgrade; verification uses the newest version present
+    # that appears in this list, and ignores the rest.
+    SUPPORTED_VERSIONS = [1].freeze
+
+    TIMESTAMP_VALUE_REGEX = /\A\d+\z/
+    SIGNATURE_KEY_REGEX = /\Av(\d+)\z/
+    HEX_SIGNATURE_REGEX = /\A[a-f0-9]+\z/
+    MAX_TIMESTAMP_SKEW_SECONDS = 300 # 5 minutes
+
+    class << self
+      # Verify a webhook signature header against the raw request body.
+      #
+      # @param signature_header [String] value of the signature header sent with the webhook
+      # @param request_body [String] raw (unparsed) request body
+      # @param signing_key [String] signing key for the webhook endpoint
+      # @return [true] when the signature is valid
+      # @raise [Error] a subclass describing why the signature was rejected
+      def verify!(signature_header, request_body, signing_key)
+        timestamp, signatures = parse_header(signature_header)
+
+        version = newest_supported_version(signatures)
+        unless version
+          raise UnsupportedVersionError,
+                "Unsupported webhook signature version: header carries only " \
+                "#{signatures.keys.sort.map { |v| "v#{v}" }.join(', ')}"
+        end
+
+        skew = (Time.now.to_i - timestamp.to_i).abs
+        if skew > MAX_TIMESTAMP_SKEW_SECONDS
+          raise TimestampSkewError,
+                "Webhook signature timestamp outside tolerance: off by #{skew}s, " \
+                "tolerance is #{MAX_TIMESTAMP_SKEW_SECONDS}s"
+        end
+
+        computed = signature_for_version(version, request_body, signing_key, timestamp)
+        unless signatures.fetch(version).any? { |signature| secure_compare(computed, signature) }
+          raise SignatureMismatchError, "Webhook signature mismatch"
+        end
+
+        true
+      end
+
+      # Verify a webhook signature header, returning false instead of raising.
+      #
+      # @see #verify!
+      # @return [Boolean]
+      def valid?(signature_header, request_body, signing_key)
+        verify!(signature_header, request_body, signing_key)
+      rescue Error
+        false
+      end
+
+      # Compute the hex-encoded HMAC-SHA256 signature for a webhook payload,
+      # using the v1 signing scheme.
+      #
+      # @param payload [String] raw (unparsed) request body
+      # @param key [String] signing key for the webhook endpoint
+      # @param timestamp [String] unix timestamp in seconds, as sent in the signature header
+      # @return [String]
+      def generate(payload, key, timestamp)
+        OpenSSL::HMAC.hexdigest("SHA256", key, "#{timestamp}.#{payload}")
+      end
+
+      private
+
+      # Compute the signature for one signing scheme. This is the single place a
+      # new scheme needs to be added.
+      def signature_for_version(version, payload, key, timestamp)
+        case version
+        when 1 then generate(payload, key, timestamp)
+        end
+      end
+
+      # Split the header into its timestamp and its signatures keyed by version.
+      # Elements that are not recognized are ignored, so that a sender adding new
+      # elements does not break verification here.
+      def parse_header(signature_header)
+        timestamp = nil
+        signatures = Hash.new { |hash, key| hash[key] = [] }
+
+        signature_header.to_s.split(",").each do |element|
+          key, value = element.strip.split("=", 2)
+          next if value.nil?
+
+          if key == "t"
+            raise MalformedHeaderError, "Malformed webhook signature header" unless TIMESTAMP_VALUE_REGEX.match?(value)
+
+            timestamp = value
+            next
+          end
+
+          match = SIGNATURE_KEY_REGEX.match(key)
+          next unless match
+
+          version = match[1].to_i
+
+          # Only versions this SDK verifies have a signature format it can insist
+          # on; anything else is recorded but left unchecked.
+          if SUPPORTED_VERSIONS.include?(version) && !HEX_SIGNATURE_REGEX.match?(value)
+            raise MalformedHeaderError, "Malformed webhook signature header"
+          end
+
+          signatures[version] << value
+        end
+
+        if timestamp.nil? || signatures.empty?
+          raise MalformedHeaderError, "Malformed webhook signature header"
+        end
+
+        [timestamp, signatures]
+      end
+
+      # Pick the highest version present that this SDK can verify, so that once a
+      # sender emits a newer scheme the older one stops being honored here.
+      def newest_supported_version(signatures)
+        (signatures.keys & SUPPORTED_VERSIONS).max
+      end
+
+      def secure_compare(computed, given)
+        return false unless computed.bytesize == given.bytesize
+
+        OpenSSL.fixed_length_secure_compare(computed, given)
+      end
+    end
+  end
+end

data/lib/helo.rb

@@ -17,6 +17,7 @@ require_relative "helo/version"
 require_relative "helo/api_error"
 require_relative "helo/configuration"
 require_relative "helo/client"
+require_relative "helo/webhook_signatures"
 
 
 module Helo

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: helo-email-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta.6
+  version: 1.0.0.pre.beta.7
 platform: ruby
 authors:
 - Helo Email
@@ -86,6 +86,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/helo-email-sdk.rb
 - lib/helo.rb
 - lib/helo/api_error.rb
@@ -121,6 +122,7 @@ files:
 - lib/helo/models/activity_list_messages_request.rb
 - lib/helo/models/activity_mail_address.rb
 - lib/helo/models/attachment.rb
+- lib/helo/models/bounced_details.rb
 - lib/helo/models/bounced_webhook_payload.rb
 - lib/helo/models/broadcast_content.rb
 - lib/helo/models/broadcast_content_attachment.rb
@@ -137,7 +139,10 @@ files:
 - lib/helo/models/channel_details_response.rb
 - lib/helo/models/channel_tracking.rb
 - lib/helo/models/channels_list_request.rb
+- lib/helo/models/clicked_details.rb
 - lib/helo/models/clicked_webhook_payload.rb
+- lib/helo/models/client_details.rb
+- lib/helo/models/complained_details.rb
 - lib/helo/models/complained_webhook_payload.rb
 - lib/helo/models/create_channel_request.rb
 - lib/helo/models/create_channel_tracking.rb
@@ -145,9 +150,11 @@ files:
 - lib/helo/models/create_suppressions_request.rb
 - lib/helo/models/create_suppressions_response.rb
 - lib/helo/models/create_webhook_request.rb
+- lib/helo/models/delivered_details.rb
 - lib/helo/models/delivered_webhook_payload.rb
 - lib/helo/models/delivery_stats.rb
 - lib/helo/models/delivery_webhook_payload_common.rb
+- lib/helo/models/device_details.rb
 - lib/helo/models/dns_record_response.rb
 - lib/helo/models/dns_records_response.rb
 - lib/helo/models/domain_channel_response.rb
@@ -157,6 +164,7 @@ files:
 - lib/helo/models/domain_response.rb
 - lib/helo/models/domain_with_dns_response.rb
 - lib/helo/models/domains_list_request.rb
+- lib/helo/models/engagement_details.rb
 - lib/helo/models/error_response.rb
 - lib/helo/models/mail_address.rb
 - lib/helo/models/message.rb
@@ -165,6 +173,7 @@ files:
 - lib/helo/models/message_details_response_event.rb
 - lib/helo/models/message_details_response_tracking.rb
 - lib/helo/models/message_statistics.rb
+- lib/helo/models/opened_details.rb
 - lib/helo/models/opened_webhook_payload.rb
 - lib/helo/models/paginated_events_response.rb
 - lib/helo/models/paginated_messages_response.rb
@@ -181,6 +190,7 @@ files:
 - lib/helo/models/remove_suppression_result.rb
 - lib/helo/models/remove_suppressions_request.rb
 - lib/helo/models/remove_suppressions_response.rb
+- lib/helo/models/resubscribed_details.rb
 - lib/helo/models/resubscribed_webhook_payload.rb
 - lib/helo/models/return_path_domain_verification_failed_payload.rb
 - lib/helo/models/return_path_domain_verified_payload.rb
@@ -208,6 +218,7 @@ files:
 - lib/helo/models/suppression_response.rb
 - lib/helo/models/suppression_result.rb
 - lib/helo/models/suppressions_list_request.rb
+- lib/helo/models/unsubscribed_details.rb
 - lib/helo/models/unsubscribed_webhook_payload.rb
 - lib/helo/models/update_channel_request.rb
 - lib/helo/models/update_channel_tracking.rb
@@ -220,6 +231,7 @@ files:
 - lib/helo/models/webhook_response.rb
 - lib/helo/models/webhooks_list_request.rb
 - lib/helo/version.rb
+- lib/helo/webhook_signatures.rb
 homepage: https://rubygems.org/gems/helo-email-sdk
 licenses:
 - MIT