uploadcare-ruby 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50f31851c1ededcc13b14099d5451a2cae8ad1a1c36ce45bbe47447fc536dc3a
-  data.tar.gz: 0c5eecb5f2583645455230fb5679c65612e322a4dcae82cae97e5b9fc702dab4
+  metadata.gz: f1c9e31f806af7e05c558fac2f5474b1b79bbe6585437049a2ecca5cc7011b46
+  data.tar.gz: 3da125b462b72f76f1cc52b3d9654354399d4864eba72b34e474c5d9a05ca22b
 SHA512:
-  metadata.gz: 0a1c5aef9d35b915e2a691ecaed88a1687bba7c7692e6c5066999e1348c5ba0bc9fe76e4afd3eea08da72b57f9a58379a7fc287385a316c6a12e795005e9b66e
-  data.tar.gz: 44a5eb8c106bd7b803428d4d8c7ad056b723dfc014baa4e94fd390c0924732a14b3d7ad9e262fa6e7de02a75bca073ee19b8476eda64c86b6fee1817380124c5
+  metadata.gz: '06814335c0ac2733f7a71ad0a9f04af2c9e3160d59de4d3d88231403a6e02366a10bb8db9405762d6a2ed70c82fb0185e5e11e59763cc2f04f79a67c89f52718'
+  data.tar.gz: 9c9d034e9d510c0d1839f5b13164a810ee26c58eb75cdcff3aaf6e54aeb6a5f2a0a9c20f2d75d0b6c6f5856eba7a8ccb2b42b7cb4b7ea45f74f5242120bf5534

data/CHANGELOG.md

@@ -1,36 +1,41 @@
 # Changelog
 
-## 3.1.1 2021-10-13
+## 3.2.0 — 2021-11-16
 
-- Fix Uploadcare::File#store
-- Fix Uploadcare::File#delete
+- Added option `signing_secret` to the `Uploadcare::Webhook`
+- Added webhook signature verifier class `Uploadcare::Param::WebhookSignatureVerifier`
 
-## 3.1.0 2021-09-21
+## 3.1.1 — 2021-10-13
 
-- Added documents and videos conversion
-- Added new attributes to the Entity class (variations, video_info, source, rekognition_info)
-- Added an opportunity to add custom logic to large files uploading process
+- Fixed `Uploadcare::File#store`
+- Fixed `Uploadcare::File#delete`
 
-## 3.0.5 2021-04-15
+## 3.1.0 — 2021-09-21
+
+- Added documents and videos conversions
+- Added new attributes to the Entity class (`variations`, `video_info`, `source`, `rekognition_info`)
+- Added an option to add custom logic to large files uploading process
+
+## 3.0.5 — 2021-04-15
 
 - Replace Travis-CI with Github Actions
 - Automate gem pushing
 
-## 3.0.4-dev 2020-03-19
+## 3.0.4-dev — 2020-03-19
 
-- Added better pagination methods for GroupList & FileList
+- Added better pagination methods for `GroupList` & `FileList`
 - Improved documentation and install instructions
 - Added CI
 
-## 3.0.3-dev 2020-03-13
-- Added better pagination and iterators for GroupList & FileList
+## 3.0.3-dev — 2020-03-13
+- Added better pagination and iterators for `GroupList` & `FileList`
 
-## 3.0.2-dev 2020-03-11
+## 3.0.2-dev — 2020-03-11
 
-- Expanded File and Group entities
+- Expanded `File` and `Group` entities
 - Changed user agent syntax
 
-## 3.0.1-dev 2020-03-11
+## 3.0.1-dev — 2020-03-11
 
 - Added Upload/group functionality
 - Added user API
@@ -38,7 +43,7 @@
 - Isolated clients, entities and concerns
 - Expanded documentation
 
-## 3.0.0-dev 2020-02-18
+## 3.0.0-dev — 2020-02-18
 
 ### Changed
 - Rewrote gem from scratch

data/README.md

@@ -52,7 +52,7 @@ And then execute:
 
     $ bundle
 
-If already not, create your project in [Uploadcare dashboard](https://uploadcare.com/dashboard/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) and copy
+If already not, create your project in [Uploadcare dashboard](https://app.uploadcare.com/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) and copy
 its API keys from there.
 
 Set your Uploadcare keys in config file or through environment variables:
@@ -75,7 +75,10 @@ Uploadcare.config.secret_key = "demoprivatekey"
 
 This section contains practical usage examples. Please note, everything that
 follows gets way more clear once you've looked through our
-[docs](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
+[docs](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
+and [Upload](https://uploadcare.com/api-refs/upload-api/) and [REST](https://uploadcare.com/api-refs/rest-api/) API refs.
+
+You can also find an example project [here](https://github.com/uploadcare/uploadcare-rails-example).
 
 ### Uploading files
 #### Uploading and storing a single file
@@ -295,8 +298,8 @@ how they should be fetched:
 - **:limit** — Controls page size. Accepts values from 1 to 1000, defaults to 100.
 - **:stored** — Can be either `true` or `false`. When true, file list will contain only stored files. When false — only not stored.
 - **:removed** — Can be either `true` or `false`. When true, file list will contain only removed files. When false — all except removed. Defaults to false.
-- **:ordering** — Controls the order of returned files. Available values: `datetime_updated`, `-datetime_updated`, `size`, `-size`. Defaults to `datetime_uploaded`. More info can be found [here](https://uploadcare.com/documentation/rest/#file-files/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
-- **:from** — Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. When files are ordered by `datetime_updated` in any direction, accepts either a `DateTime` object or an ISO 8601 string. When files are ordered by size, accepts non-negative integers (size in bytes). More info can be found [here](https://uploadcare.com/documentation/rest/#file-files/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
+- **:ordering** — Controls the order of returned files. Available values: `datetime_updated`, `-datetime_updated`, `size`, `-size`. Defaults to `datetime_uploaded`. More info can be found [here](https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/filesList).
+- **:from** — Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. When files are ordered by `datetime_updated` in any direction, accepts either a `DateTime` object or an ISO 8601 string. When files are ordered by size, accepts non-negative integers (size in bytes). More info can be found [here](https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/filesList).
 
 Options used to create a file list can be accessed through `#options` method.
 Note that, once set, they don't affect file fetching process anymore and are
@@ -369,18 +372,67 @@ https://uploadcare.com/docs/api_reference/rest/webhooks/
 You can use webhooks to provide notifications about your uploads to target urls.
 This gem lets you create and manage webhooks.
 
+Each webhook payload can be signed with a secret (the `signing_secret` option) to ensure that the request comes from the expected sender.
+More info about secure webhooks [here](https://uploadcare.com/docs/security/secure-webhooks/).
+
 ```ruby
-Uploadcare::Webhook.create(target_url: "https://example.com/listen", event: "file.uploaded", is_active: true)
-Uploadcare::Webhook.update(<webhook_id>, target_url: "https://newexample.com/listen/new", event: "file.uploaded", is_active: true)
+Uploadcare::Webhook.create(target_url: "https://example.com/listen", event: "file.uploaded", is_active: true, signing_secret: "some-secret")
+Uploadcare::Webhook.update(<webhook_id>, target_url: "https://newexample.com/listen/new", event: "file.uploaded", is_active: true, signing_secret: "some-secret")
 Uploadcare::Webhook.delete("https://example.com/listen")
 Uploadcare::Webhook.list
 ```
 
+##### Webhook signature verification
+
+The gem has a helper class to verify a webhook signature from headers —
+`Uploadcare::Param::WebhookSignatureVerifier`. This class accepts three
+important options:
+
+- **:webhook_body** — this option represents parameters received in the webhook
+  request in the JSON format.
+  **NOTE**: if you're using Rails, you should exclude options `controller`,
+  `action` and `post` from the `webhook_body`.
+- **:signing_secret** — the secret that was set while creating/updating a
+  webhook. This option can be specified as an ENV var with the name
+  `UC_SIGNING_SECRET` — then no need to send it to the verifier class.
+- **:x_uc_signature_header** — the content of the `X-Uc-Signature` HTTP header
+  in the webhook request.
+
+Using the `Uploadcare::Param::WebhookSignatureVerifier` class example:
+
+```ruby
+  webhook_body = '{...}'
+
+signing_secret = "12345X"
+x_uc_signature_header = "v1=9b31c7dd83fdbf4a2e12b19d7f2b9d87d547672a325b9492457292db4f513c70"
+
+Uploadcare::Param::WebhookSignatureVerifier.valid?(signing_secret: signing_secret, x_uc_signature_header: x_uc_signature_header, webhook_body: webhook_body)
+```
+
+You can write your verifier. Example code:
+
+```ruby
+webhook_body_json = '{...}'
+
+signing_secret = ENV['UC_SIGNING_SECRET']
+x_uc_signature_header = "v1=f4d859ed2fe47b9a4fcc81693d34e58ad12366a841e58a7072c1530483689cc0"
+
+digest = OpenSSL::Digest.new('sha256')
+
+calculated_signature = "v1=#{OpenSSL::HMAC.hexdigest(digest, signing_secret.force_encoding("utf-8"), webhook_body_json.force_encoding("utf-8"))}"
+
+if calculated_signature == x_uc_signature_header
+  puts "WebHook signature matches!"
+else
+  puts "WebHook signature mismatch!"
+end
+```
+
 #### Project
 
 `Project` provides basic info about the connected Uploadcare project. That
 object is also an Hashie::Mash, so every methods out of
-[these](https://uploadcare.com/documentation/rest/#project/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) will work.
+[these](https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/projectInfo) will work.
 
 ```ruby
 @project = Uploadcare::Project.project
@@ -399,8 +451,6 @@ object is also an Hashie::Mash, so every methods out of
 
 ##### Video
 
-Uploadcare can encode video files from all popular formats, adjust their quality, format and dimensions, cut out a video fragment, and generate thumbnails via [REST API](https://uploadcare.com/api-refs/rest-api/v0.6.0/).
-
 After each video file upload you obtain a file identifier in UUID format.
 Then you can use this file identifier to convert your video in multiple ways:
 
@@ -461,7 +511,7 @@ Params in the response:
   - **original_source** - built path for a particular video with all the conversion operations and parameters.
   - **token** - a processing job token that can be used to get a [job status](https://uploadcare.com/docs/transformations/video-encoding/#status) (see below).
   - **uuid** - UUID of your processed video file.
-  - **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a [file group](https://uploadcare.com/api-refs/rest-api/v0.5.0/#operation/groupsList) with thumbnails for an output video, based on the thumbs [operation](https://uploadcare.com/docs/transformations/video-encoding/#operation-thumbs) parameters.
+  - **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a [file group](https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/groupsList) with thumbnails for an output video, based on the thumbs [operation](https://uploadcare.com/docs/transformations/video-encoding/#operation-thumbs) parameters.
 - **problems** - problems related to your processing job, if any.
 
 To convert multiple videos just add params as a hash for each video to the first argument of the `Uploadcare::VideoConverter#convert` method:
@@ -508,12 +558,10 @@ Params in the response:
 - **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a file group with thumbnails for an output video, based on the thumbs operation parameters.
 - **uuid** - a UUID of your processed video file.
 
-More examples and options can be found [here](https://uploadcare.com/docs/transformations/video-encoding/#video-encoding)
+More examples and options can be found [here](https://uploadcare.com/docs/transformations/video-encoding/#video-encoding).
 
 ##### Document
 
-Uploadcare allows converting documents to the following target formats: doc, docx, xls, xlsx, odt, ods, rtf, txt, pdf, jpg, png. Document Conversion works via our [REST API](https://uploadcare.com/api-refs/rest-api/v0.6.0/).
-
 After each document file upload you obtain a file identifier in UUID format.
 Then you can use this file identifier to convert your document to a new format:
 

data/lib/uploadcare/client/project_client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'rest_client'
+
 module Uploadcare
   module Client
     # API client for getting project info

data/lib/uploadcare/client/webhook_client.rb

@@ -14,7 +14,9 @@ module Uploadcare
           'target_url': options[:target_url],
           'event': options[:event] || 'file.uploaded',
           'is_active': options[:is_active].nil? ? true : options[:is_active]
-        }.to_json
+        }.merge(
+          { 'signing_secret': options[:signing_secret] }.compact
+        ).to_json
         post(uri: '/webhooks/', content: body)
       end
 

data/lib/uploadcare/param/webhook_signature_verifier.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'digest/md5'
+
+module Uploadcare
+  module Param
+    # This object verifies a signature received along with webhook headers
+    class WebhookSignatureVerifier
+      # @see https://uploadcare.com/docs/security/secure-webhooks/
+      def self.valid?(options = {})
+        webhook_body_json = options[:webhook_body]
+        signing_secret = options[:signing_secret] || ENV['UC_SIGNING_SECRET']
+        x_uc_signature_header = options[:x_uc_signature_header]
+
+        digest = OpenSSL::Digest.new('sha256')
+
+        calculated_signature = "v1=#{OpenSSL::HMAC.hexdigest(digest, signing_secret, webhook_body_json)}"
+
+        calculated_signature == x_uc_signature_header
+      end
+    end
+  end
+end

data/lib/uploadcare/ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uploadcare
-  VERSION = '3.1.1'
+  VERSION = '3.2.0'
 end

data/lib/uploadcare.rb

@@ -17,6 +17,9 @@ require 'entity/project'
 require 'entity/uploader'
 require 'entity/webhook'
 
+# Param
+require 'param/webhook_signature_verifier'
+
 # General api
 require 'api/api'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uploadcare-ruby
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Stepan Redka
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-10-14 00:00:00.000000000 Z
+date: 2021-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: api_struct
@@ -214,6 +214,7 @@ files:
 - lib/uploadcare/param/upload/signature_generator.rb
 - lib/uploadcare/param/upload/upload_params_generator.rb
 - lib/uploadcare/param/user_agent.rb
+- lib/uploadcare/param/webhook_signature_verifier.rb
 - lib/uploadcare/ruby/version.rb
 - uploadcare-ruby.gemspec
 homepage: https://github.com/uploadcare/uploadcare-ruby
@@ -241,7 +242,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: Ruby wrapper for uploadcare API