Merge pull request #24 from duffelhq/webhook-validation

Allow verifying the genuineness of webhook events with `WebhookEvent.genuine?`

Author: Tim Rogers

README.md

@@ -209,4 +209,31 @@ If an error has been raised, you can call `#api_response` on the exception, whic
 
 From the `APIResponse`, you can call `#headers`, `#status_code`, `#raw_body`, `#parsed_body`, `#meta` or `#request_id` to get key information from the response.
 
+## Verifying webhooks
+
+You can set up [webhooks](https://duffel.com/docs/guides/receiving-webhooks) with Duffel to receive notifications about events that happen in your Duffel account - for example, when an airline has a schedule change affecting one of your orders.
+
+These webhook events are signed with a shared secret. This allows you to be sure that any webhook events are genuinely sent from Duffel when you receive them.
+
+When you create a webhook, you'll set a secret. With that secret in mind, you can verify that a webhook is genuine like this:
+
+```ruby
+# In Rails, you'd get this with `request.raw_post`.
+request_body = '{"created_at":"2022-01-08T18:44:56.129339Z","data":{"changes":{},"object":{}},"id":"eve_0000AFEsrBKZAcKgGtZCnQ","live_mode":false,"object":"order","type":"order.updated"}'
+# In Rails, you'd get this with `request.headers['X-Duffel-Signature']`.
+request_signature = "t=1641667496,v1=691f25ffb1f206c0fda5bb7b1a9d60fafe42c5f42819d44a06a7cfe09486f102"
+
+# Note that this code doesn't require your access token - `DuffelAPI::WebhookEvent`
+# doesn't expect you to have a `Client` initialised
+if DuffelAPI::WebhookEvent.genuine?(
+  request_body: request_body,
+  request_signature: request_signature,
+  webhook_secret: "a_secret"
+)
+  puts "This is a real webhook from Duffel 🌟"
+else
+  puts "This is a fake webhook! ☠️"
+end
+```
+
 

duffel_api.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "base16", "~> 0.0.2"
   spec.add_dependency "faraday", [">= 0.9.2", "< 2"]
 
   # Uncomment to register a new dependency of your gem

lib/duffel_api.rb

@@ -51,5 +51,6 @@
 require_relative "duffel_api/list_response"
 require_relative "duffel_api/request"
 require_relative "duffel_api/response"
+require_relative "duffel_api/webhook_event"
 
 module DuffelAPI; end

lib/duffel_api/webhook_event.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "base16"
+require "openssl"
+
+module DuffelAPI
+  module WebhookEvent
+    # An exception raised internally within the library - but not exposed - if the
+    # webhook signature provided does not match the format of a valid signature
+    class InvalidRequestSignatureError < StandardError; end
+
+    SIGNATURE_REGEXP = /\At=(.+),v1=(.+)\z/.freeze
+
+    SHA_256 = OpenSSL::Digest.new("sha256")
+
+    class << self
+      # Checks if a webhook event you received was a genuine webhook event from Duffel by
+      # checking that it was signed with your shared secret.
+      #
+      # Assuming that you've kept that secret secure and only shared it with Duffel,
+      # this can give you confidence that a webhook event was genuinely sent by Duffel.
+      #
+      # @param request_body [String] The raw body of the received request
+      # @param request_signature [String] The signature provided with the received
+      #   request, found in the `X-Duffel-Signature` request header
+      # @param webhook_secret [String] The secret of the webhook, registered with Duffel
+      # @return [Boolean] whether the webhook signature matches
+      def genuine?(request_body:, request_signature:, webhook_secret:)
+        parsed_signature = parse_signature!(request_signature)
+
+        calculated_hmac = calculate_hmac(
+          payload: request_body,
+          secret: webhook_secret,
+          timestamp: parsed_signature[:timestamp],
+        )
+
+        secure_compare(calculated_hmac, parsed_signature[:v1])
+      rescue InvalidRequestSignatureError
+        # If the signature doesn't even look like a valid one, then the webhook
+        # event can't be genuine
+        false
+      end
+
+      private
+
+      # Calculates the signature for a request body in the same way that the Duffel API
+      # does it
+      #
+      # @param secret [String]
+      # @param payload [String]
+      # @param timestamp [String]
+      # @return [String]
+      def calculate_hmac(secret:, payload:, timestamp:)
+        signed_payload = %(#{timestamp}.#{payload})
+        Base16.encode16(OpenSSL::HMAC.digest(SHA_256, secret,
+                                             signed_payload)).strip.downcase
+      end
+
+      # Parses a webhook signature and extracts the `v1` and `timestamp` values, if
+      # available.
+      #
+      # @param signature [String] A webhook event signature received in a request
+      # @return [Hash]
+      # @raise InvalidRequestSignatureError when the signature isn't valid
+      def parse_signature!(signature)
+        matches = signature.match(SIGNATURE_REGEXP)
+
+        if matches
+          {
+            v1: matches[2],
+            timestamp: matches[1],
+          }
+        else
+          raise InvalidRequestSignatureError
+        end
+      end
+
+      # Taken from `Rack::Utils`
+      # (<https://github.com/rack/rack/blob/03b4b9708f375db46ee214b219f709d08ed6eeb0/lib/rack/utils.rb#L371-L393>).
+      #
+      # Licensed under the MIT License
+      # (<https://github.com/rack/rack/blob/master/MIT-LICENSE>).
+      if defined?(OpenSSL.fixed_length_secure_compare)
+        # Checks if two strings are equal, performing a constant time string comparison
+        # resistant to timing attacks.
+        #
+        # @param a [String]
+        # @param b [String]
+        # @return [Boolean] whether the two strings are equal
+        # rubocop:disable Naming/MethodParameterName
+        def secure_compare(a, b)
+          # rubocop:enable Naming/MethodParameterName
+          return false unless a.bytesize == b.bytesize
+
+          OpenSSL.fixed_length_secure_compare(a, b)
+        end
+      else
+        # Checks if two strings are equal, performing a constant time string comparison
+        # resistant to timing attacks.
+        #
+        # @param [String] a
+        # @param [String] b
+        # @return [Boolean] whether the two strings are equal
+        # rubocop:disable Naming/MethodParameterName
+        def secure_compare(a, b)
+          # rubocop:enable Naming/MethodParameterName
+          return false unless a.bytesize == b.bytesize
+
+          l = a.unpack("C*")
+
+          r = 0
+          i = -1
+          b.each_byte { |v| r |= v ^ l[i += 1] }
+          r.zero?
+        end
+      end
+    end
+  end
+end

spec/duffel_api/webhook_event_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe DuffelAPI::WebhookEvent do
+  describe ".genuine?" do
+    subject(:is_genuine) do
+      described_class.genuine?(request_body: request_body,
+                               request_signature: request_signature,
+                               webhook_secret: webhook_secret)
+    end
+
+    let(:request_body) do
+      '{"created_at":"2022-01-08T18:44:56.129339Z","data":{"changes":{},"object":{}},' \
+        '"id":"eve_0000AFEsrBKZAcKgGtZCnQ","live_mode":false,"object":"order","type":"' \
+        'order.updated"}'
+    end
+    let(:webhook_secret) { "a_secret" }
+    let(:request_signature) do
+      "t=1641667496,v1=691f25ffb1f206c0fda5bb7b1a9d60fafe42c5f42819d44a06a7cfe09486f102"
+    end
+
+    it { is_expected.to be(true) }
+
+    context "when the signature doesn't look like a real signature at all" do
+      let(:request_signature) { "nah" }
+
+      it { is_expected.to be(false) }
+    end
+
+    context "when the signature doesn't match the body" do
+      let(:request_body) { "foo" }
+
+      it { is_expected.to be(false) }
+    end
+  end
+end