vonage 7.17.0 → 7.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e40765a9a9b5858befa5702b61359c79941b70075618dbd071f32e8798dbceb0
-  data.tar.gz: 4c0b3a037b50b85507e3344e1455ede6dc59c75953466a1a060294f8e89f00e6
+  metadata.gz: 1efb8423ce5ccb2549f6f3d65ddc659ab8c28a965888372b06845911b3e598ff
+  data.tar.gz: 4bc50573bada4e41fa89bb63ea02633435426f482722caafd10a904ca7a6b3ea
 SHA512:
-  metadata.gz: f2b8d8a22e65833b766f17433786188b9d1d504109128fcc1cffd0bcfd3b1648897054e14089ebf85713165c453cd12b7e74ea9c7cb59785e7e53de9fc9c8c61
-  data.tar.gz: '08a5577b9121dee24869d6c32e1f9eb25dca5d09e071d69e5b115b6cab756ddccd296f16e7e446b3be6dc6e26055346b5eee2935ea64a784b7b5a77d45a7b1f6'
+  metadata.gz: 296c28e8d4a3f469f938ee2b5cad316a6e3a08696fbce2d17b8afcc3abac5a6d135be9acdb589f3ca4ab73d3ff25d77d37d1457d774bc1149043c6684c0387a4
+  data.tar.gz: 2cea85e954c16bd217efad49454183a68aac48aabb4d995eb1db5376902ff1fe13e296867ffadea0695c8586b6bc06e953004894e35cb487701a8327073315ec

data/README.md

@@ -168,7 +168,7 @@ claims = {
 token = Vonage::JWT.generate(claims)
 
 client = Vonage::Client.new(token: token)
-````
+```
 
 Documentation for the Vonage Ruby JWT generator gem can be found at
 [https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby](https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby).
@@ -176,23 +176,115 @@ The documentation outlines all the possible parameters you can use to customize
 
 ## Webhook signatures
 
-To check webhook signatures you'll also need to specify the `signature_secret` option. For example:
+Certain Vonage APIs provide signed [webhooks](https://developer.vonage.com/en/getting-started/concepts/webhooks) as a means of verifying the origin of the webhooks. The exact signing mechanism varies depending on the API.
+
+### Signature in Request Body
+
+The [SMS API](https://developer.vonage.com/en/messaging/sms/overview) signs the webhook request using a hash digest. This is assigned to a `sig` parameter in the request body.
+
+You can verify the webhook request using the `Vonage::SMS#verify_webhook_sig` method. As well as the **request params** from the received webhook, the method also needs access to the signature secret associated with the Vonage account (available from the [Vonage Dashboard](https://dashboard.nexmo.com/settings)), and the signature method used for signing (e.g. `sha512`), again this is based on thes setting in the Dashboard.
+
+There are a few different ways of providing these values to the method:
+
+1. Pass all values to the method invocation.
+
+```ruby
+client = Vonage::Client.new
+
+client.sms.verify_webhook_sig(
+  webhook_params: params,
+  signature_secret: 'secret',
+  signature_method: 'sha512'
+) # => returns true if the signature is valid, false otherwise
+```
+
+2. Set `signature_secret` and `signature_method` at `Client` instantiation.
+
+```ruby
+client = Vonage::Client.new(
+  signature_secret: 'secret',
+  signature_method: 'sha512'
+)
+
+client.sms.verify_webhook_sig(webhook_params: params) # => returns true if the signature is valid, false otherwise
+```
+
+3. Set `signature_secret` and `signature_method` on the `Config` object.
 
 ```ruby
 client = Vonage::Client.new
 client.config.signature_secret = 'secret'
 client.config.signature_method = 'sha512'
 
-if client.signature.check(request.GET)
-  # valid signature
-else
-  # invalid signature
-end
+client.sms.verify_webhook_sig(webhook_params: params) # => returns true if the signature is valid, false otherwise
+```
+
+4. Set `signature_secret` and `signature_method` as environment variables named `VONAGE_SIGNATURE_SECRET` and `VONAGE_SIGNATURE_METHOD`
+
+```ruby
+client = Vonage::Client.new
+
+client.sms.verify_webhook_sig(webhook_params: params) # => returns true if the signature is valid, false otherwise
+```
+
+**Note:** Webhook signing for the SMS API is not switched on by default. You'll need to contact support@vonage.com to enable message signing on your account.
+
+### Signed JWT in Header
+
+The [Voice API](https://developer.vonage.com/en/voice/voice-api/overview) and [Messages API](https://developer.vonage.com/en/messages/overview) both include an `Authorization` header in their webhook requests. The value of this header includes a JSON Web Token (JWT) signed using the Signature Secret associated with your Vonage account.
+
+The `Vonage::Voice` and `Vonage::Messaging` classes both define a `verify_webhook_token` method which can be used to verify the JWT received in the webhook `Authorization` header.
+
+To verify the JWT, you'll first need to extract it from the `Authorization` header. The header value will look something like the following:
+
+```ruby
+"Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1OTUyN" # remainder of token omitted for brevity
+```
+
+Note: we are only interested in the token itself, which comes *after* the word `Bearer` and the space.
+
+Once you have extrated the token, you can pass it to the `verify_webhook_token` method in order to verify it.
+
+The method also needs access to the the method also needs access to the signature secret associated with the Vonage account (available from the [Vonage Dashboard](https://dashboard.nexmo.com/settings)). There are a few different ways of providing this value to the method:
+
+1. Pass all values to the method invocation.
+
+```ruby
+client = Vonage::Client.new
+
+client.voice.verify_webhook_token(
+  token: extracted_token,
+  signature_secret: 'secret'
+) # => returns true if the token is valid, false otherwise
 ```
 
-Alternatively you can set the `VONAGE_SIGNATURE_SECRET` environment variable.
+2. Set `signature_secret` at `Client` instantiation.
+
+```ruby
+client = Vonage::Client.new(
+  signature_secret: 'secret'
+)
 
-Note: you'll need to contact support@nexmo.com to enable message signing on your account.
+client.voice.verify_webhook_token(token: extracted_token) # => returns true if the token is valid, false otherwise
+```
+
+3. Set `signature_secret` on the `Config` object.
+
+```ruby
+client = Vonage::Client.new
+client.config.signature_secret = 'secret'
+client.config.signature_method = 'sha512'
+
+client.voice.verify_webhook_token(token: extracted_token) # => returns true if the token is valid, false otherwise
+```
+
+4. Set `signature_secret` as an environment variable named `VONAGE_SIGNATURE_SECRET`
+
+```ruby
+client = Vonage::Client.new
+
+client.voice.verify_webhook_token(token: extracted_token) # => returns true if the token is valid, false otherwise
+```
 
 ## Pagination
 

data/lib/vonage/applications.rb

@@ -33,6 +33,8 @@ module Vonage
     #
     #   response = client.applications.create(params)
     #
+    # @param [Hash] params
+    #
     # @option params [required, String] :name
     #   Application name.
     #
@@ -44,7 +46,9 @@ module Vonage
     #   This contains the configuration for each product.
     #   This replaces the application `type` from version 1 of the Application API.
     #
-    # @param [Hash] params
+    # @option params [Hash] :privacy
+    #   - **:improve_ai** (Boolean) If set to `true``, Vonage may store and use your content and data for the improvement
+    #      of Vonage's AI based services and technologies.
     #
     # @return [Response]
     #
@@ -73,7 +77,7 @@ module Vonage
     #   Set this to `false` to not auto-advance through all the pages in the record
     #   and collect all the data. The default is `true`.
     # @param [Hash] params
-    #  
+    #
     # @return [ListResponse]
     #
     # @see https://developer.nexmo.com/api/application.v2#listApplication
@@ -109,6 +113,9 @@ module Vonage
     # @example
     #   response = client.applications.update(id, answer_method: 'POST')
     #
+    # @param [String] id
+    # @param [Hash] params
+    #
     # @option params [required, String] :name
     #   Application name.
     #
@@ -120,8 +127,9 @@ module Vonage
     #   This contains the configuration for each product.
     #   This replaces the application `type` from version 1 of the Application API.
     #
-    # @param [String] id
-    # @param [Hash] params
+    # @option params [Hash] :privacy
+    #   - **:improve_ai** (Boolean) If set to `true``, Vonage may store and use your content and data for the improvement
+    #      of Vonage's AI based services and technologies.
     #
     # @return [Response]
     #

data/lib/vonage/jwt.rb

@@ -39,5 +39,22 @@ module Vonage
       payload[:private_key] = private_key if private_key && !payload[:private_key]
       @token = Vonage::JWTBuilder.new(payload).jwt.generate
     end
+
+    # Validate a JSON Web Token from a Vonage Webhook.
+    #
+    # Certain Vonage APIs include a JWT signed with a user's account signature secret in
+    # the Authorization header of Webhook requests. This method can be used to verify that those requests originate
+    # from the Vonage API.
+    #
+    # @param [String, required] :token The JWT from the Webhook's Authorization header
+    # @param [String, required] :signature_secret The account signature secret
+    #
+    # @return [Boolean] true, if the JWT is verified, false otherwise
+    #
+    # @see https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks
+    #
+    def self.verify_hs256_signature(token:, signature_secret:)
+      verify_signature(token, signature_secret, 'HS256')
+    end
   end
 end

data/lib/vonage/meetings/rooms.rb

@@ -89,7 +89,7 @@ module Vonage
     # @param [optional, Hash] :ui_settings Provides options to customize the user interface
     #   @option :ui_settings [String] :language
     #     The desired language of the UI. The default is `en` (English).
-    #     Must be one of: `en`, `fr`, `de`, `es`, `pt`, `ca`, `he`
+    #     Must be one of: `ar`, `pt-br`, `ca`, `zh-tw`, `zh-cn`, `en`, `fr`, `de`, `he`, `it`, `es`
     #
     # @return [Response]
     #

data/lib/vonage/meetings/sessions/list_response.rb

@@ -6,6 +6,6 @@ class Vonage::Meetings::Sessions::ListResponse < Vonage::Response
   def each
     return enum_for(:each) unless block_given?
 
-    @entity._embedded.each { |item| yield item }
+    @entity._embedded.recordings.each { |item| yield item }
   end
 end

data/lib/vonage/messaging.rb

@@ -25,5 +25,16 @@ module Vonage
     def send(params)
       request('/v1/messages', params: params, type: Post)
     end
+
+    # Validate a JSON Web Token from a Messages API Webhook.
+    #
+    # @param [String, required] :token The JWT from the Webhook's Authorization header
+    # @param [String, optional] :signature_secret The account signature secret. Required, unless `signature_secret`
+    #   is set in `Config`
+    #
+    # @return [Boolean] true, if the JWT is verified, false otherwise
+    def verify_webhook_token(token:, signature_secret: @config.signature_secret)
+      JWT.verify_hs256_signature(token: token, signature_secret: signature_secret)
+    end
   end
 end

data/lib/vonage/signature.rb

@@ -27,24 +27,24 @@ module Vonage
     #
     # @see https://developer.nexmo.com/concepts/guides/signing-messages
     #
-    def check(params, signature_method: @config.signature_method)
+    def check(params, signature_secret: @config.signature_secret, signature_method: @config.signature_method)
       params = params.dup
 
       signature = params.delete('sig')
 
-      ::JWT::Algos::Hmac::SecurityUtils.secure_compare(signature, digest(params, signature_method))
+      ::JWT::Algos::Hmac::SecurityUtils.secure_compare(signature, digest(params, signature_secret, signature_method))
     end
 
     private
 
-    def digest(params, signature_method)
+    def digest(params, signature_secret, signature_method)
       digest_string = params.sort.map { |k, v| "&#{k}=#{v.tr('&=', '_')}" }.join
 
       case signature_method
       when 'md5', 'sha1', 'sha256', 'sha512'
-        OpenSSL::HMAC.hexdigest(signature_method, @config.signature_secret, digest_string).upcase
+        OpenSSL::HMAC.hexdigest(signature_method, signature_secret, digest_string).upcase
       when 'md5hash'
-        Digest::MD5.hexdigest("#{digest_string}#{@config.signature_secret}")
+        Digest::MD5.hexdigest("#{digest_string}#{signature_secret}")
       else
         raise ArgumentError, "Unknown signature algorithm: #{signature_method}. Expected: md5hash, md5, sha1, sha256, or sha512."
       end

data/lib/vonage/sms.rb

@@ -91,11 +91,31 @@ module Vonage
       response
     end
 
+    # Validate a Signature from an SMS API Webhook.
+    #
+    # @param [Hash, required] :webhook_params The parameters from the webhook request body
+    # @param [String, optional] :signature_secret The account signature secret. Required, unless `signature_secret`
+    #   is set in `Config`
+    # @param [String, optional] :signature_method The account signature method. Required, unless `signature_method`
+    #   is set in `Config`
+    #
+    # @return [Boolean] true, if the JWT is verified, false otherwise
+    def verify_webhook_sig(webhook_params:, signature_secret: @config.signature_secret, signature_method: @config.signature_method)
+      signature.check(webhook_params, signature_secret: signature_secret, signature_method: signature_method)
+    end
+
     private
 
     sig { params(text: String).returns(T::Boolean) }
     def unicode?(text)
       !Vonage::GSM7.encoded?(text)
     end
+
+    # @return [Signature]
+    #
+    sig { returns(T.nilable(Vonage::Signature)) }
+    def signature
+      @signature ||= T.let(Signature.new(@config), T.nilable(Vonage::Signature))
+    end
   end
 end

data/lib/vonage/version.rb

@@ -1,5 +1,5 @@
 # typed: strong
 
 module Vonage
-  VERSION = "7.17.0"
+  VERSION = "7.18.0"
 end

data/lib/vonage/voice.rb

@@ -279,5 +279,16 @@ module Vonage
     def dtmf
       @dtmf ||= DTMF.new(@config)
     end
+
+    # Validate a JSON Web Token from a Voice API Webhook.
+    #
+    # @param [String, required] :token The JWT from the Webhook's Authorization header
+    # @param [String, optional] :signature_secret The account signature secret. Required, unless `signature_secret`
+    #   is set in `Config`
+    #
+    # @return [Boolean] true, if the JWT is verified, false otherwise
+    def verify_webhook_token(token:, signature_secret: @config.signature_secret)
+      JWT.verify_hs256_signature(token: token, signature_secret: signature_secret)
+    end
   end
 end

data/vonage.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.summary = 'This is the Ruby Server SDK for Vonage APIs. To use it you\'ll need a Vonage account. Sign up for free at https://www.vonage.com'
   s.files = Dir.glob('lib/**/*.rb') + %w(LICENSE.txt README.md vonage.gemspec)
   s.required_ruby_version = '>= 2.5.0'
-  s.add_dependency('vonage-jwt', '~> 0.1.3')
+  s.add_dependency('vonage-jwt', '~> 0.2.0')
   s.add_dependency('zeitwerk', '~> 2', '>= 2.2')
   s.add_dependency('sorbet-runtime', '~> 0.5')
   s.add_dependency('multipart-post', '~> 2.0')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vonage
 version: !ruby/object:Gem::Version
-  version: 7.17.0
+  version: 7.18.0
 platform: ruby
 authors:
 - Vonage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-23 00:00:00.000000000 Z
+date: 2023-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vonage-jwt
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement