uploadcare-ruby 3.1.1 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50f31851c1ededcc13b14099d5451a2cae8ad1a1c36ce45bbe47447fc536dc3a
-  data.tar.gz: 0c5eecb5f2583645455230fb5679c65612e322a4dcae82cae97e5b9fc702dab4
+  metadata.gz: b699a48dfd300be34dbfc459963a7d70aebd3a01e6b90204eb3a6deaa16d0da9
+  data.tar.gz: 3e0878f457950ec4c3a7da9b126691fbed2934b39aa43cb9d1983861377f7fd2
 SHA512:
-  metadata.gz: 0a1c5aef9d35b915e2a691ecaed88a1687bba7c7692e6c5066999e1348c5ba0bc9fe76e4afd3eea08da72b57f9a58379a7fc287385a316c6a12e795005e9b66e
-  data.tar.gz: 44a5eb8c106bd7b803428d4d8c7ad056b723dfc014baa4e94fd390c0924732a14b3d7ad9e262fa6e7de02a75bca073ee19b8476eda64c86b6fee1817380124c5
+  metadata.gz: 79ff1377255bb94d221518a04f69fd83318c2ba9803fac49901220b0327820d75b12b7cb63a63c110a300635333c71432d7286899d437df25a080c575007ee92
+  data.tar.gz: a39a15cb2904b2a3f6b7c9a754242b66246f4059dc5deee47247c028fcf613b14ba00721722ca490304e635578422eb772e73c83b995ef939c661863dbd194cb

data/CHANGELOG.md

@@ -1,36 +1,50 @@
 # Changelog
 
-## 3.1.1 2021-10-13
+## 3.3.1 - 2022-04-19
 
-- Fix Uploadcare::File#store
-- Fix Uploadcare::File#delete
+- Fixed README: `Uploadcare::URLGenerators::AmakaiGenerator` > `Uploadcare::SignedUrlGenerators::AmakaiGenerator`
+- Autoload generators constants
 
-## 3.1.0 2021-09-21
+## 3.3.0 — 2022-04-08
 
-- 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
+- Added `Uploadcare::URLGenerators::AmakaiGenerator`. Use custom domain and CDN provider to deliver files with authenticated URLs.
 
-## 3.0.5 2021-04-15
+## 3.2.0 — 2021-11-16
+
+- Added option `signing_secret` to the `Uploadcare::Webhook`
+- Added webhook signature verifier class `Uploadcare::Param::WebhookSignatureVerifier`
+
+## 3.1.1 — 2021-10-13
+
+- Fixed `Uploadcare::File#store`
+- Fixed `Uploadcare::File#delete`
+
+## 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 +52,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
@@ -116,6 +119,8 @@ Uploadcare supports multiple ways to upload files:
 
 ```ruby
 # Smart upload - detects type of passed object and picks appropriate upload method
+# If you have a large file (more than 100Mb / 10485760 bytes), the uploader will automatically process it with a multipart upload
+
 Uploadcare::Uploader.upload("https://placekitten.com/96/139")
 ```
 
@@ -295,8 +300,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 +374,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 +453,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 +513,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 +560,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:
 
@@ -611,13 +661,27 @@ Params in the response:
 
 More examples and options can be found [here](https://uploadcare.com/docs/transformations/document-conversion/#document-conversion)
 
+## Secure delivery
+
+You can use custom domain and CDN provider to deliver files with authenticated URLs (see [original documentation](https://uploadcare.com/docs/security/secure_delivery/)).
+
+To generate authenticated URL from the library, you should choose `Uploadcare::SignedUrlGenerators::AmakaiGenerator` (or create your generator implementation):
+```ruby
+generator = Uploadcare::SignedUrlGenerators::AmakaiGenerator.new(cdn_host: 'example.com', secret_key: 'secret_key'). Optional parameters: ttl: 300, algorithm: 'sha256'
+generator.generate_url(uuid, acl = optional)
+
+generator.generate_url("a7d5645e-5cd7-4046-819f-a6a2933bafe3") ->
+https://example.com/a7d5645e-5cd7-4046-819f-a6a2933bafe3/?token=exp=1649405263~acl=/a7d5645e-5cd7-4046-819f-a6a2933bafe3/~hmac=a989cae5342f17013677f5a0e6577fc5594cc4e238fb4c95eda36634eb47018b
+generator.generate_url("a7d5645e-5cd7-4046-819f-a6a2933bafe3", '/*/') ->
+https://example.com/a7d5645e-5cd7-4046-819f-a6a2933bafe3/?token=exp=1649405263~acl=/*/~hmac=3ce1152c6af8864b36d4dc721f08ca3cf0b3a20278d7f849e82c6c930d48ccc1
+```
 ## Useful links
 
 * [Development](https://github.com/uploadcare/uploadcare-ruby/blob/main/DEVELOPMENT.md)
-* [Uploadcare documentation](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)  
-* [Upload API reference](https://uploadcare.com/api-refs/upload-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)  
-* [REST API reference](https://uploadcare.com/api-refs/rest-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)  
-* [Changelog](./CHANGELOG.md)  
-* [Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)  
-* [Security policy](https://github.com/uploadcare/uploadcare-ruby/security/policy)  
-* [Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)  
+* [Uploadcare documentation](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
+* [Upload API reference](https://uploadcare.com/api-refs/upload-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
+* [REST API reference](https://uploadcare.com/api-refs/rest-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
+* [Changelog](./CHANGELOG.md)
+* [Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)
+* [Security policy](https://github.com/uploadcare/uploadcare-ruby/security/policy)
+* [Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)

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.3.1'
 end

data/lib/uploadcare/signed_url_generators/amakai_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'base_generator'
+
+module Uploadcare
+  module SignedUrlGenerators
+    class AmakaiGenerator < Uploadcare::SignedUrlGenerators::BaseGenerator
+      UUID_REGEX = '[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}'
+      TEMPLATE = 'https://{cdn_host}/{uuid}/?token=exp={expiration}{delimiter}acl={acl}{delimiter}hmac={token}'
+
+      def generate_url(uuid, acl = uuid)
+        raise ArgumentError, 'Must contain valid UUID' unless valid?(uuid)
+
+        expire = build_expire
+        signature = build_signature(expire, acl)
+
+        TEMPLATE.gsub('{delimiter}', delimiter)
+                .sub('{cdn_host}', sanitized_string(cdn_host))
+                .sub('{uuid}', sanitized_string(uuid))
+                .sub('{acl}', "/#{sanitized_string(acl)}/")
+                .sub('{expiration}', expire)
+                .sub('{token}', signature)
+      end
+
+      private
+
+      def valid?(uuid)
+        uuid.match(UUID_REGEX)
+      end
+
+      def delimiter
+        '~'
+      end
+
+      def build_expire
+        (Time.now.to_i + ttl).to_s
+      end
+
+      def build_signature(expire, acl)
+        signature = ["exp=#{expire}", "acl=/#{sanitized_string(acl)}/"].join(delimiter)
+        OpenSSL::HMAC.hexdigest(algorithm, secret_key, signature)
+      end
+
+      # rubocop:disable Style/SlicingWithRange
+      def sanitized_string(string)
+        string = string[1..-1] if string[0] == '/'
+        string = string[0...-1] if string[-1] == '/'
+        string.strip
+      end
+      # rubocop:enable Style/SlicingWithRange
+    end
+  end
+end

data/lib/uploadcare/signed_url_generators/base_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module SignedUrlGenerators
+    class BaseGenerator
+      attr_accessor :cdn_host, :ttl, :algorithm
+      attr_reader :secret_key
+
+      def initialize(cdn_host:, secret_key:, ttl: 300, algorithm: 'sha256')
+        @ttl = ttl
+        @algorithm = algorithm
+        @cdn_host = cdn_host
+        @secret_key = secret_key
+      end
+
+      def generate_url
+        raise NotImplementedError, "#{__method__} method not present"
+      end
+    end
+  end
+end

data/lib/uploadcare.rb

@@ -17,9 +17,16 @@ require 'entity/project'
 require 'entity/uploader'
 require 'entity/webhook'
 
+# Param
+require 'param/webhook_signature_verifier'
+
 # General api
 require 'api/api'
 
+# SignedUrlGenerators
+require 'signed_url_generators/amakai_generator'
+require 'signed_url_generators/base_generator'
+
 # Ruby wrapper for Uploadcare API
 #
 # @see https://uploadcare.com/docs/api_reference

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uploadcare-ruby
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.3.1
 platform: ruby
 authors:
 - Stepan Redka
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-10-14 00:00:00.000000000 Z
+date: 2022-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: api_struct
@@ -214,7 +214,10 @@ 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
+- lib/uploadcare/signed_url_generators/amakai_generator.rb
+- lib/uploadcare/signed_url_generators/base_generator.rb
 - uploadcare-ruby.gemspec
 homepage: https://github.com/uploadcare/uploadcare-ruby
 licenses:
@@ -241,7 +244,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