sendgrid-ruby 6.2.0 → 6.3.4

data/lib/sendgrid/helpers/eventwebhook/eventwebhook.rb

@@ -0,0 +1,52 @@
+require 'base64'
+require 'digest'
+require 'openssl'
+
+module SendGrid
+  # This class allows you to use the Event Webhook feature. Read the docs for
+  # more details: https://sendgrid.com/docs/for-developers/tracking-events/event
+  class EventWebhook
+    # * *Args* :
+    #   - +public_key+ -> verification key under Mail Settings
+    #
+    def convert_public_key_to_ecdsa(public_key)
+      verify_engine
+      OpenSSL::PKey::EC.new(Base64.decode64(public_key))
+    end
+
+    # * *Args* :
+    #   - +public_key+ -> elliptic curve public key
+    #   - +payload+ -> event payload in the request body
+    #   - +signature+ -> signature value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header
+    #   - +timestamp+ -> timestamp value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header
+    def verify_signature(public_key, payload, signature, timestamp)
+      verify_engine
+      timestamped_playload = "#{timestamp}#{payload}"
+      payload_digest = Digest::SHA256.digest(timestamped_playload)
+      decoded_signature = Base64.decode64(signature)
+      public_key.dsa_verify_asn1(payload_digest, decoded_signature)
+    rescue
+      false
+    end
+
+    def verify_engine
+      # JRuby does not fully support ECDSA: https://github.com/jruby/jruby-openssl/issues/193
+      if RUBY_PLATFORM == "java"
+        raise NotSupportedError, "Event Webhook verification is not supported by JRuby"
+      end
+    end
+
+    class Error < ::RuntimeError
+    end
+
+    class NotSupportedError < Error
+    end
+  end
+
+  # This class lists headers that get posted to the webhook. Read the docs for
+  # more details: https://sendgrid.com/docs/for-developers/tracking-events/event
+  class EventWebhookHeader
+    SIGNATURE = "HTTP_X_TWILIO_EMAIL_EVENT_WEBHOOK_SIGNATURE"
+    TIMESTAMP = "HTTP_X_TWILIO_EMAIL_EVENT_WEBHOOK_TIMESTAMP"
+  end
+end

data/lib/sendgrid/helpers/inbound/README.md

@@ -17,7 +17,7 @@
 # Installation
 
 In addition to the installation instructions in
-[the main readme](https://github.com/sendgrid/sendgrid-ruby/tree/master/#installation),
+[the main readme](../../../../README.md#installation),
 you must also add sinatra to your Gemfile:
 
 ```
@@ -47,7 +47,7 @@ bundle install
 ruby ./lib/sendgrid/helpers/inbound/send.rb ./lib/sendgrid/helpers/inbound/sample_data/default_data.txt
 ```
 
-More sample data can be found [here](https://github.com/sendgrid/sendgrid-ruby/tree/master/lib/sendgrid/helpers/inbound/sample_data).
+More sample data can be found [here](sample_data).
 
 View the results in the first terminal.
 
@@ -82,11 +82,11 @@ Next, send an email to [anything]@inbound.yourdomain.com, then look at the termi
 
 ## app.rb
 
-This module runs a [Sinatra](http://www.sinatrarb.com/) server, that by default (you can change those settings [here](https://github.com/sendgrid/sendgrid-ruby/blob/master/sendgrid/helpers/inbound/config.yml)), listens for POSTs on http://localhost:9292. When the server receives the POST, it parses and prints the key/value data.
+This module runs a [Sinatra](http://www.sinatrarb.com/) server, that by default (you can change those settings [here](config.yml)), listens for POSTs on http://localhost:9292. When the server receives the POST, it parses and prints the key/value data.
 
 ## config.yml
 
-This module loads application environment variables (located in [config.yml](https://github.com/sendgrid/sendgrid-ruby/blob/master/sendgrid/helpers/inbound/config.yml)).
+This module loads application environment variables (located in [config.yml](config.yml)).
 
 ## send.rb & /sample_data
 
@@ -95,4 +95,4 @@ This module is used to send sample test data. It is useful for testing and devel
 <a name="contributing"></a>
 # Contributing
 
-If you would like to contribute to this project, please see our [contributing guide](https://github.com/sendgrid/sendgrid-ruby/blob/master/CONTRIBUTING.md). Thanks!
+If you would like to contribute to this project, please see our [contributing guide](../../../../CONTRIBUTING.md). Thanks!

data/lib/sendgrid/helpers/inbound/public/index.html

@@ -5,6 +5,6 @@
   <body>
     <h1>You have successfuly launched the server!</h1>
 
-       Check out <a href="https://github.com/sendgrid/sendgrid-ruby/tree/master/sendgrid/helpers/inbound">the documentation</a> on how to use this software to utilize the SendGrid Inbound Parse webhook.
+       Check out <a href="https://github.com/sendgrid/sendgrid-ruby/tree/HEAD/sendgrid/helpers/inbound">the documentation</a> on how to use this software to utilize the SendGrid Inbound Parse webhook.
   </body>
 </html>

data/lib/sendgrid/helpers/mail/README.md

@@ -2,7 +2,7 @@
 
 # Quick Start
 
-Run the [example](https://github.com/sendgrid/sendgrid-ruby/tree/master/examples/helpers/mail) (make sure you have set your environment variable to include your SENDGRID_API_KEY).
+Run the [example](../../../../examples/helpers/mail) (make sure you have set your environment variable to include your SENDGRID_API_KEY).
 
 ```bash
 ruby examples/helpers/mail/example.rb
@@ -10,5 +10,5 @@ ruby examples/helpers/mail/example.rb
 
 ## Usage
 
-- See the [example](https://github.com/sendgrid/sendgrid-ruby/tree/master/examples/helpers/mail) for a complete working example.
-- [Documentation](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/overview.html)
+- See the [example](../../../../examples/helpers/mail) for a complete working example.
+- [Documentation](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html)

data/lib/sendgrid/helpers/settings/README.md

@@ -2,7 +2,7 @@
 
 # Quick Start
 
-Run the [example](https://github.com/sendgrid/sendgrid-ruby/tree/master/examples/helpers/settings) (make sure you have set your environment variable to include your SENDGRID_API_KEY).
+Run the [example](../../../../examples/helpers/settings) (make sure you have set your environment variable to include your SENDGRID_API_KEY).
 
 ```bash
 ruby examples/helpers/settings/example.rb
@@ -10,5 +10,5 @@ ruby examples/helpers/settings/example.rb
 
 ## Usage
 
-- See the [example](https://github.com/sendgrid/sendgrid-ruby/tree/master/examples/helpers/settings) for a complete working example.
+- See the [example](../../../../examples/helpers/settings) for a complete working example.
 - [Documentation](https://sendgrid.com/docs/API_Reference/Web_API_v3/Settings/index.html)

data/lib/sendgrid/version.rb

@@ -1,3 +1,3 @@
 module SendGrid
-  VERSION = '6.2.0'
+  VERSION = '6.3.4'
 end

data/mail_helper_v3.md

@@ -2,11 +2,11 @@ Hello!
 
 It is now time to implement the final piece of our v2 to v3 migration. Before we dig into writing the code, we would love to get feedback on the following proposed interfaces.
 
-We are starting with the use cases below for the first iteration. (we have completed this work on [our C# library](https://github.com/sendgrid/sendgrid-csharp/blob/master/USE_CASES.md), you can check that out for a sneak peek of where we are heading).
+We are starting with the use cases below for the first iteration. (we have completed this work on [our C# library](https://github.com/sendgrid/sendgrid-csharp/blob/HEAD/USE_CASES.md), you can check that out for a sneak peek of where we are heading).
 
 # Send a Single Email to a Single Recipient
 
-The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
+The following code assumes you are storing the API key in an [environment variable (recommended)](TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
 require 'sendgrid-ruby'
@@ -37,7 +37,7 @@ puts response.headers
 
 # Send a Single Email to Multiple Recipients
 
-The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
+The following code assumes you are storing the API key in an [environment variable (recommended)](TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
 require 'sendgrid-ruby'
@@ -72,7 +72,7 @@ puts response.headers
 
 # Send Multiple Emails to Multiple Recipients
 
-The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
+The following code assumes you are storing the API key in an [environment variable (recommended)](TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
 require 'sendgrid-ruby'
@@ -119,7 +119,7 @@ puts response.headers
 
 # Kitchen Sink - an example with all settings used
 
-The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
+The following code assumes you are storing the API key in an [environment variable (recommended)](TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
 client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
@@ -233,7 +233,7 @@ msg.set_send_at(1461775052, 1)
 
 msg.set_subject('this subject overrides the Global Subject on the second Personalization', 1)
 
-# The values below this comment are global to entire message
+# The values below this comment are global to the entire message
 
 msg.set_from(SendGrid::Email.new('test0@example.com', 'Example User0'))
 
@@ -295,7 +295,7 @@ puts response.headers
 
 # Attachments
 
-The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
+The following code assumes you are storing the API key in an [environment variable (recommended)](TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
 client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
@@ -326,7 +326,7 @@ puts response.headers
 
 # Transactional Templates
 
-The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
+The following code assumes you are storing the API key in an [environment variable (recommended)](TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
 
@@ -347,7 +347,7 @@ Template Body:
 ```html
 <html>
 <head>
-	<title></title>
+    <title></title>
 </head>
 <body>
 Hello -name-,

data/sendgrid-ruby.gemspec

@@ -27,4 +27,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'faker'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'minitest', '~> 5.9'
+  spec.add_development_dependency 'rack'
+  spec.add_development_dependency 'simplecov', '~> 0.18.5'
 end

data/spec/fixtures/event_webhook.rb

@@ -0,0 +1,16 @@
+require "json" 
+
+module Fixtures
+  module EventWebhook
+    PUBLIC_KEY = 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybdC+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA=='
+    FAILING_PUBLIC_KEY = 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqTxd43gyp8IOEto2LdIfjRQrIbsd4SXZkLW6jDutdhXSJCWHw8REntlo7aNDthvj+y7GjUuFDb/R1NGe1OPzpA=='
+    SIGNATURE = 'MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0='
+    FAILING_SIGNATURE = 'MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH3j/0='
+    TIMESTAMP = '1588788367'
+    PAYLOAD = {
+        'category'=>'example_payload',
+        'event'=>'test_event',
+        'message_id'=>'message_id',
+    }.to_json
+  end
+end

data/spec/rack/sendgrid_webhook_verification_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+require 'rack/mock'
+require './spec/fixtures/event_webhook'
+
+unless RUBY_PLATFORM == 'java'
+  describe Rack::SendGridWebhookVerification do
+    let(:public_key) { Fixtures::EventWebhook::PUBLIC_KEY }
+    before do
+      @app = ->(_env) { [200, { 'Content-Type' => 'text/plain' }, ['Hello']] }
+    end
+
+    describe 'new' do
+      it 'should initialize with an app, public key and a path' do
+        expect do
+          Rack::SendGridWebhookVerification.new(@app, 'ABC', /\/email/)
+        end.not_to raise_error
+      end
+
+      it 'should initialize with an app, public key and paths' do
+        expect do
+          Rack::SendGridWebhookVerification.new(@app, 'ABC', /\/email/, /\/event/)
+        end.not_to raise_error
+      end
+    end
+
+    describe 'calling against one path' do
+      let(:middleware) { Rack::SendGridWebhookVerification.new(@app, public_key, /\/email/) }
+
+      it "should not intercept when the path doesn't match" do
+        expect(SendGrid::EventWebhook).to_not receive(:new)
+        request = Rack::MockRequest.env_for('/login')
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(200)
+      end
+
+      it 'should allow a request through if it is verified' do
+        options = {
+          :input => Fixtures::EventWebhook::PAYLOAD,
+          'Content-Type' => "application/json"
+        }
+        options[SendGrid::EventWebhookHeader::SIGNATURE] = Fixtures::EventWebhook::SIGNATURE
+        options[SendGrid::EventWebhookHeader::TIMESTAMP] = Fixtures::EventWebhook::TIMESTAMP
+        request = Rack::MockRequest.env_for('/email', options)
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(200)
+      end
+
+      it 'should short circuit a request to 403 if there is no signature or timestamp' do
+        options = {
+          :input => Fixtures::EventWebhook::PAYLOAD,
+          'Content-Type' => "application/json"
+        }
+        request = Rack::MockRequest.env_for('/email', options)
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(403)
+      end
+
+      it 'should short circuit a request to 403 if the signature is incorrect' do
+        options = {
+          :input => Fixtures::EventWebhook::PAYLOAD,
+          'Content-Type' => "application/json"
+        }
+        options[SendGrid::EventWebhookHeader::SIGNATURE] = Fixtures::EventWebhook::FAILING_SIGNATURE
+        options[SendGrid::EventWebhookHeader::TIMESTAMP] = Fixtures::EventWebhook::TIMESTAMP
+        request = Rack::MockRequest.env_for('/email', options)
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(403)
+      end
+
+      it 'should short circuit a request to 403 if the payload is incorrect' do
+        options = {
+          :input => 'payload',
+          'Content-Type' => "application/json"
+        }
+        options[SendGrid::EventWebhookHeader::SIGNATURE] = Fixtures::EventWebhook::SIGNATURE
+        options[SendGrid::EventWebhookHeader::TIMESTAMP] = Fixtures::EventWebhook::TIMESTAMP
+        request = Rack::MockRequest.env_for('/email', options)
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(403)
+      end
+    end
+
+    describe 'calling with multiple paths' do
+      let(:middleware) { Rack::SendGridWebhookVerification.new(@app, public_key, /\/email/, /\/events/) }
+
+      it "should not intercept when the path doesn't match" do
+        expect(SendGrid::EventWebhook).to_not receive(:new)
+        request = Rack::MockRequest.env_for('/sms_events')
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(200)
+      end
+
+      it 'should allow a request through if it is verified' do
+        options = {
+          :input => Fixtures::EventWebhook::PAYLOAD,
+          'Content-Type' => "application/json"
+        }
+        options[SendGrid::EventWebhookHeader::SIGNATURE] = Fixtures::EventWebhook::SIGNATURE
+        options[SendGrid::EventWebhookHeader::TIMESTAMP] = Fixtures::EventWebhook::TIMESTAMP
+        request = Rack::MockRequest.env_for('/events', options)
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(200)
+      end
+
+      it 'should short circuit a request to 403 if there is no signature or timestamp' do
+        options = {
+          :input => Fixtures::EventWebhook::PAYLOAD,
+          'Content-Type' => "application/json"
+        }
+        request = Rack::MockRequest.env_for('/events', options)
+        status, headers, body = middleware.call(request)
+        expect(status).to eq(403)
+      end
+    end
+  end
+end

data/spec/sendgrid/helpers/eventwebhook/eventwebhook_spec.rb

@@ -0,0 +1,103 @@
+require 'spec_helper'
+require './spec/fixtures/event_webhook'
+
+describe SendGrid::EventWebhook do
+  describe '.verify_signature' do
+    it 'verifies a valid signature' do
+      unless skip_jruby
+        expect(verify(
+          Fixtures::EventWebhook::PUBLIC_KEY,
+          Fixtures::EventWebhook::PAYLOAD,
+          Fixtures::EventWebhook::SIGNATURE,
+          Fixtures::EventWebhook::TIMESTAMP
+        )).to be true
+      end
+    end
+
+    it 'rejects a bad key' do
+      unless skip_jruby
+        expect(verify(
+          Fixtures::EventWebhook::FAILING_PUBLIC_KEY,
+          Fixtures::EventWebhook::PAYLOAD,
+          Fixtures::EventWebhook::SIGNATURE,
+          Fixtures::EventWebhook::TIMESTAMP
+        )).to be false
+      end
+    end
+
+    it 'rejects a bad payload' do
+      unless skip_jruby
+        expect(verify(
+          Fixtures::EventWebhook::PUBLIC_KEY,
+          'payload',
+          Fixtures::EventWebhook::SIGNATURE,
+          Fixtures::EventWebhook::TIMESTAMP
+        )).to be false
+      end
+    end
+
+    it 'rejects a bad signature' do
+      unless skip_jruby
+        expect(verify(
+          Fixtures::EventWebhook::PUBLIC_KEY,
+          Fixtures::EventWebhook::PAYLOAD,
+          Fixtures::EventWebhook::FAILING_SIGNATURE,
+          Fixtures::EventWebhook::TIMESTAMP
+        )).to be false
+      end
+    end
+
+    it 'rejects a bad timestamp' do
+      unless skip_jruby
+        expect(verify(
+          Fixtures::EventWebhook::PUBLIC_KEY,
+          Fixtures::EventWebhook::PAYLOAD,
+          Fixtures::EventWebhook::SIGNATURE,
+          'timestamp'
+        )).to be false
+      end
+    end
+
+    it 'rejects a missing signature' do
+      unless skip_jruby
+        expect(verify(
+          Fixtures::EventWebhook::PUBLIC_KEY,
+          Fixtures::EventWebhook::PAYLOAD,
+          nil,
+          Fixtures::EventWebhook::TIMESTAMP
+        )).to be false
+      end
+    end
+
+    it 'throws an error when using jruby' do
+      if skip_jruby
+        expect{ verify(
+          Fixtures::EventWebhook::PUBLIC_KEY,
+          Fixtures::EventWebhook::PAYLOAD,
+          Fixtures::EventWebhook::SIGNATURE, 
+          Fixtures::EventWebhook::TIMESTAMP
+        )}.to raise_error(SendGrid::EventWebhook::NotSupportedError)
+      end
+    end
+  end
+end
+
+describe SendGrid::EventWebhookHeader do
+  it 'sets the signature header constant' do
+    expect(SendGrid::EventWebhookHeader::SIGNATURE).to eq("HTTP_X_TWILIO_EMAIL_EVENT_WEBHOOK_SIGNATURE")
+  end
+
+  it 'sets the timestamp header constant' do
+    expect(SendGrid::EventWebhookHeader::TIMESTAMP).to eq("HTTP_X_TWILIO_EMAIL_EVENT_WEBHOOK_TIMESTAMP")
+  end
+end
+
+def verify(public_key, payload, signature, timestamp)
+  ew = SendGrid::EventWebhook.new
+  ec_public_key = ew.convert_public_key_to_ecdsa(public_key)
+  ew.verify_signature(ec_public_key, payload, signature, timestamp)
+end
+
+def skip_jruby
+  RUBY_PLATFORM == 'java'
+end