voiceml 0.9.2 → 0.9.3

data/lib/voiceml/models/voice_v1.rb

@@ -10,7 +10,7 @@ module VoiceML
   #   - List pages carry a `meta` envelope (URLs + page/page_size + key) instead of
   #     the flat Twilio2010 `next_page_uri` shape.
   #
-  # Six resources implemented for v0.9.0:
+  # Six resources implemented:
   #   - ByocTrunk (BY...)            — bring-your-own-carrier trunk
   #   - ConnectionPolicy (NY...)     — origination policy
   #   - ConnectionPolicyTarget (NE...)
@@ -18,35 +18,27 @@ module VoiceML
   #   - SourceIpMapping (IB...)      — bind IpRecord -> SipDomain
   #   - IpRecord (IL...)             — standalone allowed source IP
 
-  # Shared `meta` envelope for `/v1/*` list responses.
-  module V1Pageable
-    META_FIELDS = %w[first_page_url next_page_url previous_page_url url page page_size key].freeze
-
-    META_FIELDS.each { |f| attr_reader f.to_sym }
-
-    def assign_meta_fields(hash)
-      meta = hash['meta'] || {}
-      META_FIELDS.each { |f| instance_variable_set("@#{f}", meta[f]) }
-    end
-  end
-
   # VoiceV1IpRecord — `IL...`.
   class VoiceV1IpRecord
+    include RawAttributes
     ATTRIBUTES = %w[
       account_sid sid friendly_name ip_address cidr_prefix_length
       date_created date_updated url
     ].freeze
     attr_reader(*ATTRIBUTES.map(&:to_sym))
     def initialize(attrs = {})
-      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs[f] || attrs[f.to_sym]) }
+      @raw_attributes = attrs
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
     end
     def self.from_hash(h); h.nil? ? nil : new(h); end
   end
 
   class VoiceV1IpRecordList
+    include RawAttributes
     include V1Pageable
     attr_reader :ip_records
     def initialize(hash = {})
+      @raw_attributes = hash
       assign_meta_fields(hash)
       @ip_records = (hash['ip_records'] || []).map { |h| VoiceV1IpRecord.from_hash(h) }
     end
@@ -54,20 +46,24 @@ module VoiceML
 
   # VoiceV1SourceIpMapping — `IB...`. Binds an IpRecord to a SipDomain.
   class VoiceV1SourceIpMapping
+    include RawAttributes
     ATTRIBUTES = %w[
       sid ip_record_sid sip_domain_sid date_created date_updated url
     ].freeze
     attr_reader(*ATTRIBUTES.map(&:to_sym))
     def initialize(attrs = {})
-      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs[f] || attrs[f.to_sym]) }
+      @raw_attributes = attrs
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
     end
     def self.from_hash(h); h.nil? ? nil : new(h); end
   end
 
   class VoiceV1SourceIpMappingList
+    include RawAttributes
     include V1Pageable
     attr_reader :source_ip_mappings
     def initialize(hash = {})
+      @raw_attributes = hash
       assign_meta_fields(hash)
       @source_ip_mappings = (hash['source_ip_mappings'] || []).map { |h| VoiceV1SourceIpMapping.from_hash(h) }
     end
@@ -75,6 +71,7 @@ module VoiceML
 
   # VoiceV1ByocTrunk — `BY...`. Bring-your-own-carrier trunk.
   class VoiceV1ByocTrunk
+    include RawAttributes
     ATTRIBUTES = %w[
       account_sid sid friendly_name voice_url voice_method voice_fallback_url
       voice_fallback_method status_callback_url status_callback_method
@@ -83,15 +80,18 @@ module VoiceML
     ].freeze
     attr_reader(*ATTRIBUTES.map(&:to_sym))
     def initialize(attrs = {})
-      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs[f] || attrs[f.to_sym]) }
+      @raw_attributes = attrs
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
     end
     def self.from_hash(h); h.nil? ? nil : new(h); end
   end
 
   class VoiceV1ByocTrunkList
+    include RawAttributes
     include V1Pageable
     attr_reader :byoc_trunks
     def initialize(hash = {})
+      @raw_attributes = hash
       assign_meta_fields(hash)
       @byoc_trunks = (hash['byoc_trunks'] || []).map { |h| VoiceV1ByocTrunk.from_hash(h) }
     end
@@ -99,20 +99,24 @@ module VoiceML
 
   # VoiceV1ConnectionPolicy — `NY...`.
   class VoiceV1ConnectionPolicy
+    include RawAttributes
     ATTRIBUTES = %w[
       account_sid sid friendly_name date_created date_updated url links
     ].freeze
     attr_reader(*ATTRIBUTES.map(&:to_sym))
     def initialize(attrs = {})
-      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs[f] || attrs[f.to_sym]) }
+      @raw_attributes = attrs
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
     end
     def self.from_hash(h); h.nil? ? nil : new(h); end
   end
 
   class VoiceV1ConnectionPolicyList
+    include RawAttributes
     include V1Pageable
     attr_reader :connection_policies
     def initialize(hash = {})
+      @raw_attributes = hash
       assign_meta_fields(hash)
       @connection_policies = (hash['connection_policies'] || []).map { |h| VoiceV1ConnectionPolicy.from_hash(h) }
     end
@@ -120,21 +124,25 @@ module VoiceML
 
   # VoiceV1ConnectionPolicyTarget — `NE...`. Scoped to a parent ConnectionPolicy.
   class VoiceV1ConnectionPolicyTarget
+    include RawAttributes
     ATTRIBUTES = %w[
       account_sid connection_policy_sid sid friendly_name target priority weight
       enabled date_created date_updated url
     ].freeze
     attr_reader(*ATTRIBUTES.map(&:to_sym))
     def initialize(attrs = {})
-      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs[f] || attrs[f.to_sym]) }
+      @raw_attributes = attrs
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
     end
     def self.from_hash(h); h.nil? ? nil : new(h); end
   end
 
   class VoiceV1ConnectionPolicyTargetList
+    include RawAttributes
     include V1Pageable
     attr_reader :targets
     def initialize(hash = {})
+      @raw_attributes = hash
       assign_meta_fields(hash)
       @targets = (hash['targets'] || []).map { |h| VoiceV1ConnectionPolicyTarget.from_hash(h) }
     end
@@ -142,10 +150,12 @@ module VoiceML
 
   # VoiceV1DialingPermissionsSettings — `/v1/Settings`.
   class VoiceV1DialingPermissionsSettings
+    include RawAttributes
     ATTRIBUTES = %w[dialing_permissions_inheritance url].freeze
     attr_reader(*ATTRIBUTES.map(&:to_sym))
     def initialize(attrs = {})
-      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs[f] || attrs[f.to_sym]) }
+      @raw_attributes = attrs
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
     end
     def self.from_hash(h); h.nil? ? nil : new(h); end
   end

data/lib/voiceml/request_validator.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module VoiceML
+  # Validates the `X-Twilio-Signature` header on inbound VoiceML webhooks, and
+  # computes signatures for testing server-side handlers.
+  #
+  # The algorithm (matching the VoiceML server):
+  #
+  # 1. Take the full request URL with any `#fragment` stripped.
+  # 2. For a POST, append `key + value` for every form pair, sorted ascending
+  #    by key in byte order; repeated keys keep their received value order.
+  #    For a GET, the URL alone is signed.
+  # 3. HMAC-SHA1 with the account API key as the key, then standard Base64
+  #    (padded).
+  #
+  # Comparison is constant-time. Like Twilio's validators, a URL that differs
+  # only by an explicit default port (`:443` for https, `:80` for http) also
+  # validates, in both directions.
+  #
+  # @example
+  #   validator = VoiceML::RequestValidator.new(api_key)
+  #   valid = validator.valid?(request.url, request.params, request.headers['X-Twilio-Signature'])
+  class RequestValidator
+    # @param api_key [String] the account API key the server signs with.
+    def initialize(api_key)
+      @credential = -> { api_key }
+    end
+
+    # Compute the signature for a URL and params. `params` may be a Hash (use
+    # an Array value for repeated keys) or an Array of `[key, value]` pairs in
+    # their received order.
+    #
+    # @return [String] Base64 HMAC-SHA1 digest.
+    def signature(url, params = {}, method: 'POST')
+      data = signature_base(url, method.to_s.upcase == 'POST' ? params : nil)
+      digest = OpenSSL::HMAC.digest('SHA1', @credential.call, data)
+      [digest].pack('m0')
+    end
+
+    # Validate an incoming webhook. `params` may be a Hash (Array value for
+    # repeated keys) or an Array of `[key, value]` pairs in received order.
+    #
+    # @return [Boolean]
+    def valid?(url, params, signature, method: 'POST')
+      given = signature.to_s
+      candidates = [signature(url, params, method: method)]
+      variant = port_variant(url)
+      candidates << signature(variant, params, method: method) unless variant.nil?
+
+      candidates.map { |expected| constant_time_equal?(expected, given) }.any?
+    end
+    alias validate valid?
+
+    private
+
+    # The string that gets HMAC'd: URL (fragment stripped) plus, for POSTs,
+    # `key + value` per pair sorted by key byte order, repeated keys keeping
+    # their received value order.
+    def signature_base(url, params)
+      base = url.to_s.sub(/#.*\z/, '')
+      return base if params.nil?
+
+      pairs = pairs_from(params)
+      return base if pairs.empty?
+
+      sorted = pairs.each_with_index.to_a
+                    .sort_by { |(pair, index)| [pair.first.b, index] }
+                    .map(&:first)
+      base + sorted.map { |key, value| "#{key}#{value}" }.join
+    end
+
+    def pairs_from(params)
+      case params
+      when Array then params.map { |key, value| [key.to_s, value.to_s] }
+      else
+        pairs = []
+        params.each do |key, value|
+          if value.is_a?(Array)
+            value.each { |entry| pairs << [key.to_s, entry.to_s] }
+          else
+            pairs << [key.to_s, value.to_s]
+          end
+        end
+        pairs
+      end
+    end
+
+    # The same URL with the default port added or removed (`:443` for https,
+    # `:80` for http), or nil when the URL has no such variant. String-based:
+    # URI round-trips normalise an explicit default port away.
+    def port_variant(url)
+      s = url.to_s
+      match = s.match(%r{\Ahttps?://[^/?#]*})
+      return nil if match.nil?
+
+      prefix = match[0]
+      rest = s[prefix.length..] || ''
+      if prefix =~ %r{\Ahttps://[^/?#]+:443\z}
+        prefix.sub(/:443\z/, '') + rest
+      elsif prefix =~ %r{\Ahttps://[^/?#:]+\z}
+        "#{prefix}:443#{rest}"
+      elsif prefix =~ %r{\Ahttp://[^/?#]+:80\z}
+        prefix.sub(/:80\z/, '') + rest
+      elsif prefix =~ %r{\Ahttp://[^/?#:]+\z}
+        "#{prefix}:80#{rest}"
+      end
+    end
+
+    def constant_time_equal?(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+
+  # Convenience wrapper: validate one webhook without instantiating a
+  # {RequestValidator}.
+  #
+  # @return [Boolean]
+  def self.validate_request(api_key, url, params, signature, method: 'POST')
+    RequestValidator.new(api_key).valid?(url, params, signature, method: method)
+  end
+end

data/lib/voiceml/resources/accounts.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/accounts'
+
+module VoiceML
+  # Operations on `/2010-04-01/Accounts/{Sid}` — the account record itself and
+  # its balance. `client.accounts` reads the authenticated account; `fetch`/
+  # `update` accept any AccountSid the credentials can see (in practice the
+  # credential's own account).
+  class AccountsResource < BaseResource
+    UPDATE_FIELDS = {
+      'FriendlyName'        => :friendly_name,
+      'VoiceUrl'            => :voice_url,
+      'VoiceMethod'         => :voice_method,
+      'VoiceFallbackUrl'    => :voice_fallback_url,
+      'VoiceFallbackMethod' => :voice_fallback_method,
+      'SttFsVendor'         => :stt_fs_vendor,
+      'SttHttpUrl'          => :stt_http_url,
+      'SttHttpToken'        => :stt_http_token,
+      'TtsHttpUrl'          => :tts_http_url,
+      'TtsHttpToken'        => :tts_http_token,
+      'TtsEngineName'       => :tts_engine_name,
+      'TtsDefaultVoice'     => :tts_default_voice,
+      'TtsDefaultLanguage'  => :tts_default_language,
+      'AwsBucket'           => :aws_bucket,
+      'AwsRegion'           => :aws_region,
+      'AwsPrefix'           => :aws_prefix,
+      'AwsAccessKeyId'      => :aws_access_key_id,
+      'AwsSecretAccessKey'  => :aws_secret_access_key,
+      'AwsKmsKeyId'         => :aws_kms_key_id,
+      'AllowCidr'           => :allow_cidr
+    }.freeze
+
+    # Fetch the account record. Omit `sid` to read the authenticated account.
+    #
+    # @return [VoiceML::Account]
+    def fetch(sid = @transport.account_sid)
+      Account.from_hash(
+        @transport.request(:get, "/2010-04-01/Accounts/#{encode_path_segment(sid)}.json")
+      )
+    end
+
+    # Update the account record. A concurrent modification surfaces as
+    # `VoiceML::ConflictError` (HTTP 409 / code 20409 — optimistic locking).
+    #
+    # @return [VoiceML::Account]
+    def update(sid = @transport.account_sid, **kwargs)
+      Account.from_hash(
+        @transport.request(:post, "/2010-04-01/Accounts/#{encode_path_segment(sid)}.json",
+                           form: form_params(UPDATE_FIELDS, kwargs))
+      )
+    end
+
+    # Fetch the account balance.
+    #
+    # @return [VoiceML::Balance]
+    def fetch_balance
+      Balance.from_hash(@transport.request(:get, path('Balance')))
+    end
+
+    # Rotate the account's API key (`POST /Accounts/{Sid}/RotateKey.json`,
+    # no request body). The previous key stops working immediately. The new
+    # key rides the returned {VoiceML::AccountWithKey} as `api_key` — no
+    # read endpoint exposes it, so store it right away. It never appears in
+    # the model's `inspect` / `to_s`.
+    #
+    # @return [VoiceML::AccountWithKey]
+    def rotate_key(sid = @transport.account_sid)
+      AccountWithKey.from_hash(
+        @transport.request(:post, "/2010-04-01/Accounts/#{encode_path_segment(sid)}/RotateKey.json")
+      )
+    end
+  end
+end

data/lib/voiceml/resources/applications.rb

@@ -15,7 +15,9 @@ module VoiceML
       'VoiceCallerIdLookup'    => :voice_caller_id_lookup,
       'StatusCallback'         => :status_callback,
       'StatusCallbackMethod'   => :status_callback_method,
-      'StatusCallbackEvent'    => :status_callback_event
+      'StatusCallbackEvent'    => :status_callback_event,
+      'MessageStatusCallback'  => :message_status_callback,
+      'SmsStatusCallback'      => :sms_status_callback
     }.freeze
 
     LIST_FIELDS = {