stripe 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f1ca52eecc695b6655a4317d0b5c8c893431aab
-  data.tar.gz: 1a5e5f17ba9e3e73574fb3af3f2014b3b39b06ed
+  metadata.gz: 747667dd050969e755253ea2c5328142ebff0dd2
+  data.tar.gz: f60cfc0497a8b0044811283e893a667755f3f6cd
 SHA512:
-  metadata.gz: 9bf4f072ef017d7247c014606532275d976a46aa451fbb9be12d25eaa792b4ae843795d329cf94359d41c83a1a3bf836b090ba7beb20ebcad6b4151497469cff
-  data.tar.gz: 58db5a2043f13901d93e9024a1dcfffde774cbcfc4f614cce4b43354069efbc115252b78981f33baddc599a090b2775dd6ee23b9bc2aa4d5c43007d9f062c57d
+  metadata.gz: b405457d2c0615be9e9fdf1ea20229b95365fb0a615d2f1b508fe0b4466c8842e7a7469317208e477280df0eb51d280e1e82928d5465de54fdca7e786df44faa
+  data.tar.gz: 8718ad60ec44fd3af67bfb5b8567c56a35141ce14937f6a88ed7d455084ed491cb93a3d2fb45c31d2297d0324667ba8d43517aea65b87c72aea7c28240ed9863

data/History.txt

@@ -1,3 +1,7 @@
+=== 2.8.0 2017-04-28
+
+* Support for checking webhook signatures
+
 === 2.7.0 2017-04-26
 
 * Add model `InvoiceLineItem`

data/README.md

@@ -122,6 +122,19 @@ an intermittent network problem:
 [Idempotency keys][idempotency-keys] are added to requests to guarantee that
 retries are safe.
 
+### Configuring Timeouts
+
+Open and read timeouts are configurable:
+
+```java
+Stripe.open_timeout = 30 // in seconds
+Stripe.read_timeout = 80
+```
+
+Please take care to set conservative read timeouts. Some API requests can take
+some time, and a short timeout increases the likelihood of a problem within our
+servers.
+
 ### Writing a Plugin
 
 If you're writing a plugin that uses the library, we'd appreciate it if you

data/VERSION

@@ -1 +1 @@
-2.7.0
+2.8.0

data/lib/stripe.rb

@@ -28,6 +28,7 @@ require 'stripe/stripe_response'
 require 'stripe/list_object'
 require 'stripe/api_resource'
 require 'stripe/singleton_api_resource'
+require 'stripe/webhook'
 
 # Named API resources
 require 'stripe/account'

data/lib/stripe/errors.rb

@@ -89,4 +89,15 @@ module Stripe
   # back off on request rate.
   class RateLimitError < StripeError
   end
+
+  # SignatureVerificationError is raised when the signature verification for a
+  # webhook fails
+  class SignatureVerificationError < StripeError
+    attr_accessor :sig_header
+
+    def initialize(message, sig_header, http_body: nil)
+      super(message, http_body: http_body)
+      @sig_header = sig_header
+    end
+  end
 end

data/lib/stripe/util.rb

@@ -256,5 +256,17 @@ module Stripe
         end
       end
     end
+
+    # Constant time string comparison to prevent timing attacks
+    # Code borrowed from ActiveSupport
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack "C#{a.bytesize}"
+
+      res = 0
+      b.each_byte { |byte| res |= byte ^ l.shift }
+      res == 0
+    end
   end
 end

data/lib/stripe/version.rb

@@ -1,3 +1,3 @@
 module Stripe
-  VERSION = '2.7.0'
+  VERSION = '2.8.0'
 end

data/lib/stripe/webhook.rb

@@ -0,0 +1,79 @@
+module Stripe
+  module Webhook
+    DEFAULT_TOLERANCE = 300
+
+    # Initializes an Event object from a JSON payload.
+    #
+    # This may raise JSON::ParserError if the payload is not valid JSON, or
+    # SignatureVerificationError if the signature verification fails.
+    def self.construct_event(payload, sig_header, secret, tolerance: DEFAULT_TOLERANCE)
+      data = JSON.parse(payload, symbolize_names: true)
+      event = Event.construct_from(data)
+
+      Signature.verify_header(payload, sig_header, secret, tolerance: tolerance)
+
+      event
+    end
+
+    module Signature
+      EXPECTED_SCHEME = 'v1'
+
+      def self.compute_signature(payload, secret)
+        OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, payload)
+      end
+      private_class_method :compute_signature
+
+      # Extracts the timestamp and the signature(s) with the desired scheme
+      # from the header
+      def self.get_timestamp_and_signatures(header, scheme)
+        list_items = header.split(/,\s*/).map { |i| i.split('=', 2) }
+        timestamp = Integer(list_items.select { |i| i[0] == 't' }[0][1])
+        signatures = list_items.select { |i| i[0] == scheme }.map { |i| i[1] }
+        [timestamp, signatures]
+      end
+      private_class_method :get_timestamp_and_signatures
+
+      # Verifies the signature header for a given payload.
+      #
+      # Raises a SignatureVerificationError in the following cases:
+      # - the header does not match the expected format
+      # - no signatures found with the expected scheme
+      # - no signatures matching the expected signature
+      # - a tolerance is provided and the timestamp is not within the
+      #   tolerance
+      #
+      # Returns true otherwise
+      def self.verify_header(payload, header, secret, tolerance: nil)
+        begin
+          timestamp, signatures = get_timestamp_and_signatures(header, EXPECTED_SCHEME)
+        rescue
+          raise SignatureVerificationError.new(
+            "Unable to extract timestamp and signatures from header",
+            header, http_body: payload)
+        end
+
+        if signatures.empty?
+          raise SignatureVerificationError.new(
+            "No signatures found with expected scheme #{EXPECTED_SCHEME}",
+            header, http_body: payload)
+        end
+
+        signed_payload = "#{timestamp}.#{payload}"
+        expected_sig = compute_signature(signed_payload, secret)
+        unless signatures.any? {|s| Util.secure_compare(expected_sig, s)}
+          raise SignatureVerificationError.new(
+            "No signatures found matching the expected signature for payload",
+            header, http_body: payload)
+        end
+
+        if tolerance && timestamp < Time.now.to_f - tolerance
+          raise SignatureVerificationError.new(
+            "Timestamp outside the tolerance zone (#{Time.at(timestamp)})",
+            header, http_body: payload)
+        end
+
+        true
+      end
+    end
+  end
+end

data/test/stripe/webhook_test.rb

@@ -0,0 +1,92 @@
+require File.expand_path('../../test_helper', __FILE__)
+
+module Stripe
+  class WebhookTest < Test::Unit::TestCase
+    EVENT_PAYLOAD = '''{
+  "id": "evt_test_webhook",
+  "object": "event"
+}'''
+    SECRET = 'whsec_test_secret'
+
+    def generate_header(opts={})
+      opts[:timestamp] ||= Time.now.to_i
+      opts[:payload] ||= EVENT_PAYLOAD
+      opts[:secret] ||= SECRET
+      opts[:scheme] ||= Stripe::Webhook::Signature::EXPECTED_SCHEME
+      opts[:signature] ||= Stripe::Webhook::Signature.send(:compute_signature, "#{opts[:timestamp]}.#{opts[:payload]}", opts[:secret])
+      "t=#{opts[:timestamp]},#{opts[:scheme]}=#{opts[:signature]}"
+    end
+
+    context ".construct_event" do
+      should "return an Event instance from a valid JSON payload and valid signature header" do
+        header = generate_header
+        event = Stripe::Webhook.construct_event(EVENT_PAYLOAD, header, SECRET)
+        assert event.kind_of?(Stripe::Event)
+      end
+
+      should "raise a JSON::ParserError from an invalid JSON payload" do
+        assert_raises JSON::ParserError do
+          payload = 'this is not valid JSON'
+          header = generate_header(payload: payload)
+          Stripe::Webhook.construct_event(payload, header, SECRET)
+        end
+      end
+
+      should "raise a SignatureVerificationError from a valid JSON payload and an invalid signature header" do
+        header = 'bad_header'
+        assert_raises Stripe::SignatureVerificationError do
+          Stripe::Webhook.construct_event(EVENT_PAYLOAD, header, SECRET)
+        end
+      end
+    end
+
+    context ".verify_signature_header" do
+      should "raise a SignatureVerificationError when the header does not have the expected format" do
+        header = 'i\'m not even a real signature header'
+        e = assert_raises(Stripe::SignatureVerificationError) do
+          Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, 'secret')
+        end
+        assert_match("Unable to extract timestamp and signatures from header", e.message)
+      end
+
+      should "raise a SignatureVerificationError when there are no signatures with the expected scheme" do
+        header = generate_header(scheme: 'v0')
+        e = assert_raises(Stripe::SignatureVerificationError) do
+          Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, 'secret')
+        end
+        assert_match("No signatures found with expected scheme", e.message)
+      end
+
+      should "raise a SignatureVerificationError when there are no valid signatures for the payload" do
+        header = generate_header(signature: 'bad_signature')
+        e = assert_raises(Stripe::SignatureVerificationError) do
+          Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, 'secret')
+        end
+        assert_match("No signatures found matching the expected signature for payload", e.message)
+      end
+
+      should "raise a SignatureVerificationError when the timestamp is not within the tolerance" do
+        header = generate_header(timestamp: Time.now.to_i - 15)
+        e = assert_raises(Stripe::SignatureVerificationError) do
+          Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, SECRET, tolerance: 10)
+        end
+        assert_match("Timestamp outside the tolerance zone", e.message)
+      end
+
+      should "return true when the header contains a valid signature and the timestamp is within the tolerance" do
+        header = generate_header
+        assert(Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, SECRET, tolerance: 10))
+      end
+
+      should "return true when the header contains at least one valid signature" do
+        header = generate_header + ",v1=bad_signature"
+        assert(Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, SECRET, tolerance: 10))
+      end
+
+      should "return true when the header contains a valid signature and the timestamp is off but no tolerance is provided" do
+        header = generate_header(timestamp: 12345)
+        assert(Stripe::Webhook::Signature.verify_header(EVENT_PAYLOAD, header, SECRET))
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stripe
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Stripe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-26 00:00:00.000000000 Z
+date: 2017-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -97,6 +97,7 @@ files:
 - lib/stripe/transfer.rb
 - lib/stripe/util.rb
 - lib/stripe/version.rb
+- lib/stripe/webhook.rb
 - openapi/fixtures.json
 - openapi/fixtures.yaml
 - openapi/spec2.json
@@ -146,6 +147,7 @@ files:
 - test/stripe/three_d_secure_test.rb
 - test/stripe/transfer_test.rb
 - test/stripe/util_test.rb
+- test/stripe/webhook_test.rb
 - test/stripe_test.rb
 - test/test_data.rb
 - test/test_helper.rb
@@ -218,6 +220,7 @@ test_files:
 - test/stripe/three_d_secure_test.rb
 - test/stripe/transfer_test.rb
 - test/stripe/util_test.rb
+- test/stripe/webhook_test.rb
 - test/stripe_test.rb
 - test/test_data.rb
 - test/test_helper.rb