stripe 4.10.0 → 5.55.0

data/lib/stripe/util.rb

@@ -24,98 +24,74 @@ module Stripe
       OPTS_USER_SPECIFIED + Set[:client] - Set[:idempotency_key]
     ).freeze
 
-    def self.objects_to_ids(h)
-      case h
+    def self.objects_to_ids(obj)
+      case obj
       when APIResource
-        h.id
+        obj.id
       when Hash
         res = {}
-        h.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? }
+        obj.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? }
         res
       when Array
-        h.map { |v| objects_to_ids(v) }
+        obj.map { |v| objects_to_ids(v) }
       else
-        h
+        obj
       end
     end
 
-    def self.object_classes # rubocop:disable Metrics/MethodLength
-      @object_classes ||= {
-        # data structures
-        ListObject::OBJECT_NAME => ListObject,
-
-        # business objects
-        Account::OBJECT_NAME                      => Account,
-        AccountLink::OBJECT_NAME                  => AccountLink,
-        AlipayAccount::OBJECT_NAME                => AlipayAccount,
-        ApplePayDomain::OBJECT_NAME               => ApplePayDomain,
-        ApplicationFee::OBJECT_NAME               => ApplicationFee,
-        ApplicationFeeRefund::OBJECT_NAME         => ApplicationFeeRefund,
-        Balance::OBJECT_NAME                      => Balance,
-        BalanceTransaction::OBJECT_NAME           => BalanceTransaction,
-        BankAccount::OBJECT_NAME                  => BankAccount,
-        BitcoinReceiver::OBJECT_NAME              => BitcoinReceiver,
-        BitcoinTransaction::OBJECT_NAME           => BitcoinTransaction,
-        Card::OBJECT_NAME                         => Card,
-        Charge::OBJECT_NAME                       => Charge,
-        Checkout::Session::OBJECT_NAME            => Checkout::Session,
-        CountrySpec::OBJECT_NAME                  => CountrySpec,
-        Coupon::OBJECT_NAME                       => Coupon,
-        Customer::OBJECT_NAME                     => Customer,
-        Dispute::OBJECT_NAME                      => Dispute,
-        EphemeralKey::OBJECT_NAME                 => EphemeralKey,
-        Event::OBJECT_NAME                        => Event,
-        ExchangeRate::OBJECT_NAME                 => ExchangeRate,
-        File::OBJECT_NAME                         => File,
-        File::OBJECT_NAME_ALT                     => File,
-        FileLink::OBJECT_NAME                     => FileLink,
-        Invoice::OBJECT_NAME                      => Invoice,
-        InvoiceItem::OBJECT_NAME                  => InvoiceItem,
-        InvoiceLineItem::OBJECT_NAME              => InvoiceLineItem,
-        IssuerFraudRecord::OBJECT_NAME            => IssuerFraudRecord,
-        Issuing::Authorization::OBJECT_NAME       => Issuing::Authorization,
-        Issuing::Card::OBJECT_NAME                => Issuing::Card,
-        Issuing::CardDetails::OBJECT_NAME         => Issuing::CardDetails,
-        Issuing::Cardholder::OBJECT_NAME          => Issuing::Cardholder,
-        Issuing::Dispute::OBJECT_NAME             => Issuing::Dispute,
-        Issuing::Transaction::OBJECT_NAME         => Issuing::Transaction,
-        LoginLink::OBJECT_NAME                    => LoginLink,
-        Order::OBJECT_NAME                        => Order,
-        OrderReturn::OBJECT_NAME                  => OrderReturn,
-        PaymentIntent::OBJECT_NAME                => PaymentIntent,
-        PaymentMethod::OBJECT_NAME                => PaymentMethod,
-        Payout::OBJECT_NAME                       => Payout,
-        Person::OBJECT_NAME                       => Person,
-        Plan::OBJECT_NAME                         => Plan,
-        Product::OBJECT_NAME                      => Product,
-        Radar::ValueList::OBJECT_NAME             => Radar::ValueList,
-        Radar::ValueListItem::OBJECT_NAME         => Radar::ValueListItem,
-        Recipient::OBJECT_NAME                    => Recipient,
-        RecipientTransfer::OBJECT_NAME            => RecipientTransfer,
-        Refund::OBJECT_NAME                       => Refund,
-        Reporting::ReportRun::OBJECT_NAME         => Reporting::ReportRun,
-        Reporting::ReportType::OBJECT_NAME        => Reporting::ReportType,
-        Reversal::OBJECT_NAME                     => Reversal,
-        Review::OBJECT_NAME                       => Review,
-        SKU::OBJECT_NAME                          => SKU,
-        Sigma::ScheduledQueryRun::OBJECT_NAME     => Sigma::ScheduledQueryRun,
-        Source::OBJECT_NAME                       => Source,
-        SourceTransaction::OBJECT_NAME            => SourceTransaction,
-        Subscription::OBJECT_NAME                 => Subscription,
-        SubscriptionItem::OBJECT_NAME             => SubscriptionItem,
-        SubscriptionSchedule::OBJECT_NAME         => SubscriptionSchedule,
-        SubscriptionScheduleRevision::OBJECT_NAME => SubscriptionScheduleRevision,
-        Terminal::ConnectionToken::OBJECT_NAME    => Terminal::ConnectionToken,
-        Terminal::Location::OBJECT_NAME           => Terminal::Location,
-        Terminal::Reader::OBJECT_NAME             => Terminal::Reader,
-        ThreeDSecure::OBJECT_NAME                 => ThreeDSecure,
-        Token::OBJECT_NAME                        => Token,
-        Topup::OBJECT_NAME                        => Topup,
-        Transfer::OBJECT_NAME                     => Transfer,
-        UsageRecord::OBJECT_NAME                  => UsageRecord,
-        UsageRecordSummary::OBJECT_NAME           => UsageRecordSummary,
-        WebhookEndpoint::OBJECT_NAME              => WebhookEndpoint,
-      }
+    def self.object_classes
+      @object_classes ||= Stripe::ObjectTypes.object_names_to_classes
+    end
+
+    def self.object_name_matches_class?(object_name, klass)
+      Util.object_classes[object_name] == klass
+    end
+
+    # Adds a custom method to a resource class. This is used to add support for
+    # non-CRUDL API requests, e.g. capturing charges. custom_method takes the
+    # following parameters:
+    # - name: the name of the custom method to create (as a symbol)
+    # - http_verb: the HTTP verb for the API request (:get, :post, or :delete)
+    # - http_path: the path to append to the resource's URL. If not provided,
+    #              the name is used as the path
+    # - resource: the resource implementation class
+    # - target: the class that custom static method will be added to
+    #
+    # For example, this call:
+    #     custom_method :capture, http_verb: post
+    # adds a `capture` class method to the resource class that, when called,
+    # will send a POST request to `/v1/<object_name>/capture`.
+    def self.custom_method(resource, target, name, http_verb, http_path)
+      unless %i[get post delete].include?(http_verb)
+        raise ArgumentError,
+              "Invalid http_verb value: #{http_verb.inspect}. Should be one " \
+              "of :get, :post or :delete."
+      end
+      unless target.respond_to?(:resource_url)
+        raise ArgumentError,
+              "Invalid target value: #{target}. Target class should have a " \
+              "`resource_url` method."
+      end
+      http_path ||= name.to_s
+      target.define_singleton_method(name) do |id, params = {}, opts = {}|
+        unless id.is_a?(String)
+          raise ArgumentError,
+                "id should be a string representing the ID of an API resource"
+        end
+
+        url = "#{target.resource_url}/"\
+              "#{CGI.escape(id)}/"\
+              "#{CGI.escape(http_path)}"
+
+        resp, opts = resource.execute_resource_request(
+          http_verb,
+          url,
+          params,
+          opts
+        )
+
+        Util.convert_to_stripe_object(resp.data, opts)
+      end
     end
 
     # Converts a hash of fields or an array of hashes into a +StripeObject+ or
@@ -131,38 +107,48 @@ module Stripe
     # * +opts+ - Options for +StripeObject+ like an API key that will be reused
     #   on subsequent API calls.
     def self.convert_to_stripe_object(data, opts = {})
+      opts = normalize_opts(opts)
+
       case data
       when Array
         data.map { |i| convert_to_stripe_object(i, opts) }
       when Hash
-        # Try converting to a known object class.  If none available, fall back to generic StripeObject
-        object_classes.fetch(data[:object], StripeObject).construct_from(data, opts)
+        # Try converting to a known object class.  If none available, fall back
+        # to generic StripeObject
+        object_classes.fetch(data[:object], StripeObject)
+                      .construct_from(data, opts)
       else
         data
       end
     end
 
     def self.log_error(message, data = {})
-      if !Stripe.logger.nil? ||
-         !Stripe.log_level.nil? && Stripe.log_level <= Stripe::LEVEL_ERROR
-        log_internal(message, data, color: :cyan,
-                                    level: Stripe::LEVEL_ERROR, logger: Stripe.logger, out: $stderr)
+      config = data.delete(:config) || Stripe.config
+      logger = config.logger || Stripe.logger
+      if !logger.nil? ||
+         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_ERROR
+        log_internal(message, data, color: :cyan, level: Stripe::LEVEL_ERROR,
+                                    logger: Stripe.logger, out: $stderr)
       end
     end
 
     def self.log_info(message, data = {})
-      if !Stripe.logger.nil? ||
-         !Stripe.log_level.nil? && Stripe.log_level <= Stripe::LEVEL_INFO
-        log_internal(message, data, color: :cyan,
-                                    level: Stripe::LEVEL_INFO, logger: Stripe.logger, out: $stdout)
+      config = data.delete(:config) || Stripe.config
+      logger = config.logger || Stripe.logger
+      if !logger.nil? ||
+         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_INFO
+        log_internal(message, data, color: :cyan, level: Stripe::LEVEL_INFO,
+                                    logger: Stripe.logger, out: $stdout)
       end
     end
 
     def self.log_debug(message, data = {})
-      if !Stripe.logger.nil? ||
-         !Stripe.log_level.nil? && Stripe.log_level <= Stripe::LEVEL_DEBUG
-        log_internal(message, data, color: :blue,
-                                    level: Stripe::LEVEL_DEBUG, logger: Stripe.logger, out: $stdout)
+      config = data.delete(:config) || Stripe.config
+      logger = config.logger || Stripe.logger
+      if !logger.nil? ||
+         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_DEBUG
+        log_internal(message, data, color: :blue, level: Stripe::LEVEL_DEBUG,
+                                    logger: Stripe.logger, out: $stdout)
       end
     end
 
@@ -239,6 +225,18 @@ module Stripe
       result
     end
 
+    # `Time.now` can be unstable in cases like an administrator manually
+    # updating its value or a reconcilation via NTP. For this reason, prefer
+    # the use of the system's monotonic clock especially where comparing times
+    # to calculate an elapsed duration.
+    #
+    # Shortcut for getting monotonic time, mostly for purposes of line length
+    # and test stubbing. Returns time in seconds since the event used for
+    # monotonic reference purposes by the platform (e.g. system boot time).
+    def self.monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def self.normalize_id(id)
       if id.is_a?(Hash) # overloaded id
         params_hash = id.dup
@@ -257,7 +255,9 @@ module Stripe
         { api_key: opts }
       when Hash
         check_api_key!(opts.fetch(:api_key)) if opts.key?(:api_key)
-        opts.clone
+        # Explicitly use dup here instead of clone to avoid preserving freeze
+        # state on input params.
+        opts.dup
       else
         raise TypeError, "normalize_opts expects a string or a hash"
       end
@@ -265,11 +265,13 @@ module Stripe
 
     def self.check_string_argument!(key)
       raise TypeError, "argument must be a string" unless key.is_a?(String)
+
       key
     end
 
     def self.check_api_key!(key)
       raise TypeError, "api_key must be a string" unless key.is_a?(String)
+
       key
     end
 
@@ -297,13 +299,13 @@ module Stripe
 
     # Constant time string comparison to prevent timing attacks
     # Code borrowed from ActiveSupport
-    def self.secure_compare(a, b)
-      return false unless a.bytesize == b.bytesize
+    def self.secure_compare(str_a, str_b)
+      return false unless str_a.bytesize == str_b.bytesize
 
-      l = a.unpack "C#{a.bytesize}"
+      l = str_a.unpack "C#{str_a.bytesize}"
 
       res = 0
-      b.each_byte { |byte| res |= byte ^ l.shift }
+      str_b.each_byte { |byte| res |= byte ^ l.shift }
       res.zero?
     end
 
@@ -312,14 +314,14 @@ module Stripe
     #
 
     COLOR_CODES = {
-      black:   0, light_black:   60,
-      red:     1, light_red:     61,
-      green:   2, light_green:   62,
-      yellow:  3, light_yellow:  63,
-      blue:    4, light_blue:    64,
+      black: 0, light_black: 60,
+      red: 1, light_red: 61,
+      green: 2, light_green: 62,
+      yellow: 3, light_yellow: 63,
+      blue: 4, light_blue: 64,
       magenta: 5, light_magenta: 65,
-      cyan:    6, light_cyan:    66,
-      white:   7, light_white:   67,
+      cyan: 6, light_cyan: 66,
+      white: 7, light_white: 67,
       default: 9,
     }.freeze
     private_constant :COLOR_CODES
@@ -348,23 +350,32 @@ module Stripe
     end
     private_class_method :level_name
 
-    # TODO: Make these named required arguments when we drop support for Ruby
-    # 2.0.
-    def self.log_internal(message, data = {}, color: nil, level: nil, logger: nil, out: nil)
+    def self.log_internal(message, data = {}, color:, level:, logger:, out:)
       data_str = data.reject { |_k, v| v.nil? }
                      .map do |(k, v)|
-        format("%s=%s", colorize(k, color, logger.nil? && !out.nil? && out.isatty), wrap_logfmt_value(v))
+        format("%<key>s=%<value>s",
+               key: colorize(k, color, logger.nil? && !out.nil? && out.isatty),
+               value: wrap_logfmt_value(v))
       end.join(" ")
 
       if !logger.nil?
         # the library's log levels are mapped to the same values as the
         # standard library's logger
         logger.log(level,
-                   format("message=%s %s", wrap_logfmt_value(message), data_str))
+                   format("message=%<message>s %<data_str>s",
+                          message: wrap_logfmt_value(message),
+                          data_str: data_str))
       elsif out.isatty
-        out.puts format("%s %s %s", colorize(level_name(level)[0, 4].upcase, color, out.isatty), message, data_str)
+        out.puts format("%<level>s %<message>s %<data_str>s",
+                        level: colorize(level_name(level)[0, 4].upcase,
+                                        color, out.isatty),
+                        message: message,
+                        data_str: data_str)
       else
-        out.puts format("message=%s level=%s %s", wrap_logfmt_value(message), level_name(level), data_str)
+        out.puts format("message=%<message>s level=%<level>s %<data_str>s",
+                        message: wrap_logfmt_value(message),
+                        level: level_name(level),
+                        data_str: data_str)
       end
     end
     private_class_method :log_internal
@@ -382,7 +393,7 @@ module Stripe
       if %r{[^\w\-/]} =~ val
         # If the string contains any special characters, escape any double
         # quotes it has, remove newlines, and wrap the whole thing in quotes.
-        format(%("%s"), val.gsub('"', '\"').delete("\n"))
+        format(%("%<value>s"), value: val.gsub('"', '\"').delete("\n"))
       else
         # Otherwise use the basic value if it looks like a standard set of
         # characters (and allow a few special characters like hyphens, and

data/lib/stripe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stripe
-  VERSION = "4.10.0".freeze
+  VERSION = "5.55.0"
 end

data/lib/stripe/webhook.rb

@@ -8,7 +8,8 @@ module Stripe
     #
     # This may raise JSON::ParserError if the payload is not valid JSON, or
     # SignatureVerificationError if the signature verification fails.
-    def self.construct_event(payload, sig_header, secret, tolerance: DEFAULT_TOLERANCE)
+    def self.construct_event(payload, sig_header, secret,
+                             tolerance: DEFAULT_TOLERANCE)
       Signature.verify_header(payload, sig_header, secret, tolerance: tolerance)
 
       # It's a good idea to parse the payload only after verifying it. We use
@@ -21,12 +22,39 @@ module Stripe
     end
 
     module Signature
-      EXPECTED_SCHEME = "v1".freeze
+      EXPECTED_SCHEME = "v1"
 
-      def self.compute_signature(payload, secret)
-        OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, payload)
+      # Computes a webhook signature given a time (probably the current time),
+      # a payload, and a signing secret.
+      def self.compute_signature(timestamp, payload, secret)
+        raise ArgumentError, "timestamp should be an instance of Time" \
+          unless timestamp.is_a?(Time)
+        raise ArgumentError, "payload should be a string" \
+          unless payload.is_a?(String)
+        raise ArgumentError, "secret should be a string" \
+          unless secret.is_a?(String)
+
+        timestamped_payload = "#{timestamp.to_i}.#{payload}"
+        OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret,
+                                timestamped_payload)
+      end
+
+      # Generates a value that would be added to a `Stripe-Signature` for a
+      # given webhook payload.
+      #
+      # Note that this isn't needed to verify webhooks in any way, and is
+      # mainly here for use in test cases (those that are both within this
+      # project and without).
+      def self.generate_header(timestamp, signature, scheme: EXPECTED_SCHEME)
+        raise ArgumentError, "timestamp should be an instance of Time" \
+          unless timestamp.is_a?(Time)
+        raise ArgumentError, "signature should be a string" \
+          unless signature.is_a?(String)
+        raise ArgumentError, "scheme should be a string" \
+          unless scheme.is_a?(String)
+
+        "t=#{timestamp.to_i},#{scheme}=#{signature}"
       end
-      private_class_method :compute_signature
 
       # Extracts the timestamp and the signature(s) with the desired scheme
       # from the header
@@ -34,7 +62,7 @@ module Stripe
         list_items = header.split(/,\s*/).map { |i| i.split("=", 2) }
         timestamp = Integer(list_items.select { |i| i[0] == "t" }[0][1])
         signatures = list_items.select { |i| i[0] == scheme }.map { |i| i[1] }
-        [timestamp, signatures]
+        [Time.at(timestamp), signatures]
       end
       private_class_method :get_timestamp_and_signatures
 
@@ -50,7 +78,13 @@ module Stripe
       # Returns true otherwise
       def self.verify_header(payload, header, secret, tolerance: nil)
         begin
-          timestamp, signatures = get_timestamp_and_signatures(header, EXPECTED_SCHEME)
+          timestamp, signatures =
+            get_timestamp_and_signatures(header, EXPECTED_SCHEME)
+
+        # TODO: Try to knock over this blanket rescue as it can unintentionally
+        # swallow many valid errors. Instead, try to validate an incoming
+        # header one piece at a time, and error with a known exception class if
+        # any part is found to be invalid. Rescue that class here.
         rescue StandardError
           raise SignatureVerificationError.new(
             "Unable to extract timestamp and signatures from header",
@@ -65,8 +99,7 @@ module Stripe
           )
         end
 
-        signed_payload = "#{timestamp}.#{payload}"
-        expected_sig = compute_signature(signed_payload, secret)
+        expected_sig = compute_signature(timestamp, payload, secret)
         unless signatures.any? { |s| Util.secure_compare(expected_sig, s) }
           raise SignatureVerificationError.new(
             "No signatures found matching the expected signature for payload",
@@ -74,7 +107,7 @@ module Stripe
           )
         end
 
-        if tolerance && timestamp < Time.now.to_f - tolerance
+        if tolerance && timestamp < Time.now - tolerance
           raise SignatureVerificationError.new(
             "Timestamp outside the tolerance zone (#{Time.at(timestamp)})",
             header, http_body: payload