boxr 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e02b3471599db059d5a1e9f7ae8b06757c60fe66d576b3083fd1e3799fac49f1
-  data.tar.gz: d0ce9eb18ef1464b14d48ce45872a6a3768e4be14ebe9d2c903cb3172e0e791c
+  metadata.gz: ecda6bc31119954e1441132e89cb3730c72832a9d27a4b50cef02631889ac16d
+  data.tar.gz: 78e5f729e9e50695560cc15b28286e865940e7222cf258794763ee8efa61c8ee
 SHA512:
-  metadata.gz: 6d45931744e3c77a0a29ee071a5da104f91152fff14471421187435e186f62b1964361a81b97b697e38226da95af814d1d9cf3bc0a905aed1980090e47a55deb
-  data.tar.gz: a3b3bad61ff4c59678e7d116e0f5250e6172b01d07572a96436e4b23af76dc72e6cca894233278e131610e91a62cb84ed63c1c520fa5ffb1e9a345b8f84da1be
+  metadata.gz: 4b35c744df6ef3a020d3d201ed8caae441b33595ebd4dbd22d510db478a39bd5c548dca20b01899ba38ded2d6a9d00e5df9659df62d535ba9442672a88395630
+  data.tar.gz: f83a2c3cdeec8795c57d22a3ae1e12850f62f68b984fe28fcc63b6885fb9b0ad4d009c7330821f8d449f15a7b430eb15262dc17ac74de896359e2616e5cd52e7

data/.env.example

@@ -13,3 +13,5 @@ BOX_CLIENT_SECRET={client secret of your Box app}
 BOX_ENTERPRISE_ID={box enterprise id}
 JWT_PRIVATE_KEY_PATH={path to your JWT private key}
 JWT_PRIVATE_KEY_PASSWORD={JWT private key password}
+BOX_PRIMARY_SIGNATURE_KEY={primary key for webhooks}
+BOX_SECONDARY_SIGNATURE_KEY={secondary key for webhooks}

data/README.md

@@ -476,6 +476,29 @@ apply_watermark_on_folder(folder)
 
 remove_watermark_on_folder(folder)
 ```
+
+#### [Webhooks](https://developer.box.com/en/reference/resources/webhook/) & [Webhook Signatures](https://developer.box.com/guides/webhooks/handle/setup-signatures/)
+```ruby
+create_webhook(target_id, target_type, triggers, address)
+
+get_webhooks(marker: nil, limit: nil)
+
+get_webhook(webhook_id)
+
+update_webhook(webhook_id, attributes)
+
+delete_webhook(webhook_id)
+
+# When receiving a webhook, it is advised to verify that it was sent by Box
+Boxr::WebhookValidator.new(
+  headers,
+  payload,
+  primary_signature_key: primary_signature_key,
+  secondary_signature_key: secondary_signature_key
+).valid_message?
+
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/cburnette/boxr/fork )

data/lib/boxr.rb

@@ -24,6 +24,8 @@ require 'boxr/events'
 require 'boxr/auth'
 require 'boxr/web_links'
 require 'boxr/watermarking'
+require 'boxr/webhooks'
+require 'boxr/webhook_validator'
 
 class BoxrCollection < Array
   def files

data/lib/boxr/client.rb

@@ -29,7 +29,7 @@ module Boxr
     METADATA_TEMPLATES_URI = "#{API_URI}/metadata_templates"
     EVENTS_URI = "#{API_URI}/events"
     WEB_LINKS_URI = "#{API_URI}/web_links"
-
+    WEBHOOKS_URI = "#{API_URI}/webhooks"
 
     DEFAULT_LIMIT = 100
     FOLDER_ITEMS_LIMIT = 1000

data/lib/boxr/version.rb

@@ -1,3 +1,3 @@
 module Boxr
-  VERSION = "1.17.0".freeze
+  VERSION = "1.18.0".freeze
 end

data/lib/boxr/webhook_validator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Boxr
+  class WebhookValidator
+    attr_reader(
+      :payload,
+      :primary_signature,
+      :primary_signature_key,
+      :secondary_signature,
+      :secondary_signature_key,
+      :timestamp
+    )
+
+    MAXIMUM_MESSAGE_AGE = 600 # 10 minutes (in seconds)
+
+    def initialize(headers, payload, primary_signature_key: nil, secondary_signature_key: nil)
+      @payload                 = payload
+      @timestamp               = headers['BOX-DELIVERY-TIMESTAMP'].to_s
+      @primary_signature_key   = primary_signature_key.to_s
+      @secondary_signature_key = secondary_signature_key.to_s
+      @primary_signature       = headers['BOX-SIGNATURE-PRIMARY']
+      @secondary_signature     = headers['BOX-SIGNATURE-SECONDARY']
+    end
+
+    def valid_message?
+      verify_delivery_timestamp && verify_signature
+    end
+
+    def verify_delivery_timestamp
+      message_age < MAXIMUM_MESSAGE_AGE
+    end
+
+    def verify_signature
+      generate_signature(primary_signature_key) == primary_signature || generate_signature(secondary_signature_key) == secondary_signature
+    end
+
+    def generate_signature(key)
+      message_as_bytes = (payload.bytes + timestamp.bytes).pack('U')
+      digest = OpenSSL::HMAC.hexdigest('SHA256', key, message_as_bytes)
+      Base64.encode64(digest)
+    end
+
+    private
+
+    def current_time
+      Time.now.utc
+    end
+
+    def delivery_time
+      Time.parse(timestamp).utc
+    rescue ArgumentError
+      raise BoxrError.new(boxr_message: "Webhook authenticity not verified: invalid timestamp")
+    end
+
+    def message_age
+      current_time - delivery_time
+    end
+  end
+end

data/lib/boxr/webhooks.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Boxr
+  class Client
+    def create_webhook(target_id, target_type, triggers, address)
+      attributes = { target: { id: target_id, type: target_type }, triggers: triggers, address: address }
+      new_webhook, response = post(WEBHOOKS_URI, attributes)
+      new_webhook
+    end
+
+    def get_webhooks(marker: nil, limit: nil)
+      query_params = { marker: marker, limit: limit }.compact
+      webhooks, response = get(WEBHOOKS_URI, query: query_params)
+      webhooks
+    end
+
+    def get_webhook(webhook)
+      webhook_id = ensure_id(webhook)
+      uri = "#{WEBHOOKS_URI}/#{webhook_id}"
+      webhook, response = get(uri)
+      webhook
+    end
+
+    def update_webhook(webhook, attributes = {})
+      webhook_id = ensure_id(webhook)
+      uri = "#{WEBHOOKS_URI}/#{webhook_id}"
+      updated_webhook, response = put(uri, attributes)
+      updated_webhook
+    end
+
+    def delete_webhook(webhook)
+      webhook_id = ensure_id(webhook)
+      uri = "#{WEBHOOKS_URI}/#{webhook_id}"
+      result, response = delete(uri)
+      result
+    end
+  end
+end

data/spec/boxr/webhook_validator_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+def generate_signature(payload, timestamp, key)
+  message_as_bytes = (payload.bytes + timestamp.bytes).pack('U')
+  digest = OpenSSL::HMAC.hexdigest('SHA256', key, message_as_bytes)
+  Base64.encode64(digest)
+end
+
+# rake spec SPEC_OPTS="-e \"Boxr::WebhookValidator"\"
+describe Boxr::WebhookValidator, :skip_reset do
+  describe '#verify_delivery_timestamp' do
+    let(:payload) { 'not relevant' }
+    subject { described_class.new(headers, payload).verify_delivery_timestamp }
+    context 'maximum age is under 10 minutes' do
+      let(:five_minutes_ago) { (Time.now.utc - 300).to_s } # 5 minutes (in seconds)
+      let(:headers) { { 'BOX-DELIVERY-TIMESTAMP' => five_minutes_ago} }
+      it 'returns true' do
+        expect(subject).to eq(true)
+      end
+    end
+
+    context 'maximum age is over 10 minute' do
+      let(:eleven_minutes_ago) { (Time.now.utc - 660).to_s } # 11 minutes (in seconds)
+      let(:headers) { { 'BOX-DELIVERY-TIMESTAMP' => eleven_minutes_ago } }
+      it 'returns false' do
+        expect(subject).to eq(false)
+      end
+    end
+
+    context 'no delivery timestamp is supplied' do
+      let(:headers) { { 'BOX-DELIVERY-TIMESTAMP' => nil } }
+      it 'raises an error' do
+        expect do
+          subject
+        end.to raise_error(RuntimeError, 'Webhook authenticity not verified: invalid timestamp')
+      end
+    end
+
+    context 'bogus timestamp is supplied' do
+      let(:headers) { { 'BOX-DELIVERY-TIMESTAMP' => 'foo' } }
+      it 'raises an error' do
+        expect do
+          subject
+        end.to raise_error(RuntimeError, 'Webhook authenticity not verified: invalid timestamp')
+      end
+    end
+  end
+
+  describe '#verify_signature' do
+    let(:payload) { 'some data' }
+    let(:timestamp) { (Time.now.utc - 300).to_s } # 5 minutes ago (in seconds)
+    let(:signature_primary) { generate_signature(payload, timestamp, ENV['BOX_PRIMARY_SIGNATURE_KEY'].to_s) }
+    let(:signature_secondary) { generate_signature(payload, timestamp, ENV['BOX_SECONDARY_SIGNATURE_KEY'].to_s) }
+    subject { described_class.new(headers,
+                                  payload,
+                                  primary_signature_key: ENV['BOX_PRIMARY_SIGNATURE_KEY'].to_s,
+                                  secondary_signature_key: ENV['BOX_SECONDARY_SIGNATURE_KEY'].to_s,
+                                  ).verify_signature }
+
+    context 'valid primary key' do
+      let(:headers) do
+        { 'BOX-DELIVERY-TIMESTAMP' => timestamp,
+          'BOX-SIGNATURE-PRIMARY' => signature_primary }
+      end
+
+      it 'returns true' do
+        expect(subject).to eq(true)
+      end
+    end
+
+    context 'invalid primary key, valid secondary key' do
+      let(:headers) do
+        { 'BOX-DELIVERY-TIMESTAMP' => timestamp,
+          'BOX-SIGNATURE-PRIMARY' => 'invalid',
+          'BOX-SIGNATURE-SECONDARY' => signature_secondary }
+      end
+
+      it 'returns true' do
+        expect(subject).to eq(true)
+      end
+    end
+
+    context 'invalid primary key, invalid secondary key' do
+      let(:headers) do
+        { 'BOX-DELIVERY-TIMESTAMP' => timestamp,
+          'BOX-SIGNATURE-PRIMARY' => 'invalid',
+          'BOX-SIGNATURE-SECONDARY' => 'also invalid' }
+      end
+
+      it 'returns false' do
+        expect(subject).to eq(false)
+      end
+    end
+
+    context 'no signatures were supplied' do
+      let(:headers) do
+        { 'BOX-DELIVERY-TIMESTAMP' => timestamp,
+          'BOX-SIGNATURE-PRIMARY' => nil,
+          'BOX-SIGNATURE-SECONDARY' => nil }
+      end
+
+      it 'returns false' do
+        subject = described_class.new(headers, payload, primary_signature_key: nil, secondary_signature_key: nil).verify_signature
+        expect(subject).to eq(false)
+      end
+    end
+  end
+
+  describe '#valid_message?' do
+    let(:headers) { { 'doesnt' => 'matter' } }
+    let(:payload) { 'not relevant' }
+
+    it 'delegates to timestamp and signature verification' do
+      validator = described_class.new(headers, payload)
+      expect(validator).to receive(:verify_delivery_timestamp).and_return(true)
+      expect(validator).to receive(:verify_signature)
+      validator.valid_message?
+    end
+  end
+end

data/spec/boxr/webhooks_spec.rb

@@ -0,0 +1,30 @@
+# rake spec SPEC_OPTS="-e \"invokes webhook operations"\"
+describe "webhook operations" do
+  it 'invokes webhook operations' do
+    puts 'create webhook'
+    resource_id = @test_folder.id
+    type = 'folder'
+    triggers = ['FOLDER.RENAMED']
+    address = 'https://example.com'
+    new_webhook = BOX_CLIENT.create_webhook(resource_id, type, triggers, address)
+    new_webhook_id = new_webhook.id
+    expect(new_webhook.triggers.to_a).to eq(triggers)
+
+    puts 'get webhooks'
+    all_webhooks = BOX_CLIENT.get_webhooks
+    expect(all_webhooks.entries.first.id).to eq(new_webhook_id)
+
+    puts 'get webhook'
+    single_webhook = BOX_CLIENT.get_webhook(new_webhook_id)
+    expect(single_webhook.id).to eq(new_webhook_id)
+
+    puts 'update webhooks'
+    new_address = 'https://foo.com'
+    updated_webhook = BOX_CLIENT.update_webhook(new_webhook, { address: new_address })
+    expect(updated_webhook.address).to eq(new_address)
+
+    puts 'delete webhooks'
+    deleted_webhook = BOX_CLIENT.delete_webhook(updated_webhook)
+    expect(deleted_webhook).to be_empty
+  end
+end

data/spec/spec_helper.rb

@@ -5,6 +5,11 @@ require 'awesome_print'
 
 RSpec.configure do |config|
   config.before(:each) do
+    if test.metadata[:skip_reset]
+      puts "Skipping reset"
+      next
+    end
+
     puts "-----> Resetting Box Environment"
     sleep BOX_SERVER_SLEEP
     root_folders = BOX_CLIENT.root_folder_items.folders

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxr
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.18.0
 platform: ruby
 authors:
 - Chad Burnette
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-08 00:00:00.000000000 Z
+date: 2021-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -227,6 +227,8 @@ files:
 - lib/boxr/version.rb
 - lib/boxr/watermarking.rb
 - lib/boxr/web_links.rb
+- lib/boxr/webhook_validator.rb
+- lib/boxr/webhooks.rb
 - spec/boxr/auth_spec.rb
 - spec/boxr/chunked_uploads_spec.rb
 - spec/boxr/collaborations_spec.rb
@@ -240,6 +242,8 @@ files:
 - spec/boxr/users_spec.rb
 - spec/boxr/watermarking_spec.rb
 - spec/boxr/web_links_spec.rb
+- spec/boxr/webhook_validator_spec.rb
+- spec/boxr/webhooks_spec.rb
 - spec/boxr_spec.rb
 - spec/spec_helper.rb
 - spec/test_files/large test file.txt
@@ -281,6 +285,8 @@ test_files:
 - spec/boxr/users_spec.rb
 - spec/boxr/watermarking_spec.rb
 - spec/boxr/web_links_spec.rb
+- spec/boxr/webhook_validator_spec.rb
+- spec/boxr/webhooks_spec.rb
 - spec/boxr_spec.rb
 - spec/spec_helper.rb
 - spec/test_files/large test file.txt