activesupport 4.2.0 → 5.2.0

data/lib/active_support/message_verifier.rb

@@ -1,6 +1,10 @@
-require 'base64'
-require 'active_support/core_ext/object/blank'
-require 'active_support/security_utils'
+# frozen_string_literal: true
+
+require "base64"
+require "active_support/core_ext/object/blank"
+require "active_support/security_utils"
+require "active_support/messages/metadata"
+require "active_support/messages/rotator"
 
 module ActiveSupport
   # +MessageVerifier+ makes it easy to generate and verify messages which are
@@ -15,7 +19,7 @@ module ActiveSupport
   # In the authentication filter:
   #
   #   id, time = @verifier.verify(cookies[:remember_me])
-  #   if time < Time.now
+  #   if Time.now < time
   #     self.current_user = User.find(id)
   #   end
   #
@@ -24,34 +28,163 @@ module ActiveSupport
   # hash upon initialization:
   #
   #   @verifier = ActiveSupport::MessageVerifier.new('s3Krit', serializer: YAML)
+  #
+  # +MessageVerifier+ creates HMAC signatures using SHA1 hash algorithm by default.
+  # If you want to use a different hash algorithm, you can change it by providing
+  # +:digest+ key as an option while initializing the verifier:
+  #
+  #   @verifier = ActiveSupport::MessageVerifier.new('s3Krit', digest: 'SHA256')
+  #
+  # === Confining messages to a specific purpose
+  #
+  # By default any message can be used throughout your app. But they can also be
+  # confined to a specific +:purpose+.
+  #
+  #   token = @verifier.generate("this is the chair", purpose: :login)
+  #
+  # Then that same purpose must be passed when verifying to get the data back out:
+  #
+  #   @verifier.verified(token, purpose: :login)    # => "this is the chair"
+  #   @verifier.verified(token, purpose: :shipping) # => nil
+  #   @verifier.verified(token)                     # => nil
+  #
+  #   @verifier.verify(token, purpose: :login)      # => "this is the chair"
+  #   @verifier.verify(token, purpose: :shipping)   # => ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token)                       # => ActiveSupport::MessageVerifier::InvalidSignature
+  #
+  # Likewise, if a message has no purpose it won't be returned when verifying with
+  # a specific purpose.
+  #
+  #   token = @verifier.generate("the conversation is lively")
+  #   @verifier.verified(token, purpose: :scare_tactics) # => nil
+  #   @verifier.verified(token)                          # => "the conversation is lively"
+  #
+  #   @verifier.verify(token, purpose: :scare_tactics)   # => ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token)                            # => "the conversation is lively"
+  #
+  # === Making messages expire
+  #
+  # By default messages last forever and verifying one year from now will still
+  # return the original value. But messages can be set to expire at a given
+  # time with +:expires_in+ or +:expires_at+.
+  #
+  #   @verifier.generate(parcel, expires_in: 1.month)
+  #   @verifier.generate(doowad, expires_at: Time.now.end_of_year)
+  #
+  # Then the messages can be verified and returned upto the expire time.
+  # Thereafter, the +verified+ method returns +nil+ while +verify+ raises
+  # <tt>ActiveSupport::MessageVerifier::InvalidSignature</tt>.
+  #
+  # === Rotating keys
+  #
+  # MessageVerifier also supports rotating out old configurations by falling
+  # back to a stack of verifiers. Call +rotate+ to build and add a verifier to
+  # so either +verified+ or +verify+ will also try verifying with the fallback.
+  #
+  # By default any rotated verifiers use the values of the primary
+  # verifier unless specified otherwise.
+  #
+  # You'd give your verifier the new defaults:
+  #
+  #   verifier = ActiveSupport::MessageVerifier.new(@secret, digest: "SHA512", serializer: JSON)
+  #
+  # Then gradually rotate the old values out by adding them as fallbacks. Any message
+  # generated with the old values will then work until the rotation is removed.
+  #
+  #   verifier.rotate old_secret          # Fallback to an old secret instead of @secret.
+  #   verifier.rotate digest: "SHA256"    # Fallback to an old digest instead of SHA512.
+  #   verifier.rotate serializer: Marshal # Fallback to an old serializer instead of JSON.
+  #
+  # Though the above would most likely be combined into one rotation:
+  #
+  #   verifier.rotate old_secret, digest: "SHA256", serializer: Marshal
   class MessageVerifier
+    prepend Messages::Rotator::Verifier
+
     class InvalidSignature < StandardError; end
 
     def initialize(secret, options = {})
-      raise ArgumentError, 'Secret should not be nil.' unless secret
+      raise ArgumentError, "Secret should not be nil." unless secret
       @secret = secret
-      @digest = options[:digest] || 'SHA1'
+      @digest = options[:digest] || "SHA1"
       @serializer = options[:serializer] || Marshal
     end
 
-    def verify(signed_message)
-      raise InvalidSignature if signed_message.blank?
+    # Checks if a signed message could have been generated by signing an object
+    # with the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   signed_message = verifier.generate 'a private message'
+    #   verifier.valid_message?(signed_message) # => true
+    #
+    #   tampered_message = signed_message.chop # editing the message invalidates the signature
+    #   verifier.valid_message?(tampered_message) # => false
+    def valid_message?(signed_message)
+      return if signed_message.nil? || !signed_message.valid_encoding? || signed_message.blank?
 
-      data, digest = signed_message.split("--")
-      if data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
+      data, digest = signed_message.split("--".freeze)
+      data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
+    end
+
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #
+    #   signed_message = verifier.generate 'a private message'
+    #   verifier.verified(signed_message) # => 'a private message'
+    #
+    # Returns +nil+ if the message was not signed with the same secret.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier.verified(signed_message) # => nil
+    #
+    # Returns +nil+ if the message is not Base64-encoded.
+    #
+    #   invalid_message = "f--46a0120593880c733a53b6dad75b42ddc1c8996d"
+    #   verifier.verified(invalid_message) # => nil
+    #
+    # Raises any error raised while decoding the signed message.
+    #
+    #   incompatible_message = "test--dad7b06c94abba8d46a15fafaef56c327665d5ff"
+    #   verifier.verified(incompatible_message) # => TypeError: incompatible marshal file format
+    def verified(signed_message, purpose: nil, **)
+      if valid_message?(signed_message)
         begin
-          @serializer.load(decode(data))
+          data = signed_message.split("--".freeze)[0]
+          message = Messages::Metadata.verify(decode(data), purpose)
+          @serializer.load(message) if message
         rescue ArgumentError => argument_error
-          raise InvalidSignature if argument_error.message =~ %r{invalid base64}
+          return if argument_error.message.include?("invalid base64")
           raise
         end
-      else
-        raise InvalidSignature
       end
     end
 
-    def generate(value)
-      data = encode(@serializer.dump(value))
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   signed_message = verifier.generate 'a private message'
+    #
+    #   verifier.verify(signed_message) # => 'a private message'
+    #
+    # Raises +InvalidSignature+ if the message was not signed with the same
+    # secret or was not Base64-encoded.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier.verify(signed_message) # => ActiveSupport::MessageVerifier::InvalidSignature
+    def verify(*args)
+      verified(*args) || raise(InvalidSignature)
+    end
+
+    # Generates a signed message for the provided value.
+    #
+    # The message is signed with the +MessageVerifier+'s secret. Without knowing
+    # the secret, the original value cannot be extracted from the message.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   verifier.generate 'a private message' # => "BAhJIhRwcml2YXRlLW1lc3NhZ2UGOgZFVA==--e2d724331ebdee96a10fb99b089508d1c72bd772"
+    def generate(value, expires_at: nil, expires_in: nil, purpose: nil)
+      data = encode(Messages::Metadata.wrap(@serializer.dump(value), expires_at: expires_at, expires_in: expires_in, purpose: purpose))
       "#{data}--#{generate_digest(data)}"
     end
 
@@ -65,7 +198,7 @@ module ActiveSupport
       end
 
       def generate_digest(data)
-        require 'openssl' unless defined?(OpenSSL)
+        require "openssl" unless defined?(OpenSSL)
         OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@digest).new, @secret, data)
       end
   end

data/lib/active_support/messages/metadata.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ActiveSupport
+  module Messages #:nodoc:
+    class Metadata #:nodoc:
+      def initialize(message, expires_at = nil, purpose = nil)
+        @message, @expires_at, @purpose = message, expires_at, purpose
+      end
+
+      def as_json(options = {})
+        { _rails: { message: @message, exp: @expires_at, pur: @purpose } }
+      end
+
+      class << self
+        def wrap(message, expires_at: nil, expires_in: nil, purpose: nil)
+          if expires_at || expires_in || purpose
+            JSON.encode new(encode(message), pick_expiry(expires_at, expires_in), purpose)
+          else
+            message
+          end
+        end
+
+        def verify(message, purpose)
+          extract_metadata(message).verify(purpose)
+        end
+
+        private
+          def pick_expiry(expires_at, expires_in)
+            if expires_at
+              expires_at.utc.iso8601(3)
+            elsif expires_in
+              Time.now.utc.advance(seconds: expires_in).iso8601(3)
+            end
+          end
+
+          def extract_metadata(message)
+            data = JSON.decode(message) rescue nil
+
+            if data.is_a?(Hash) && data.key?("_rails")
+              new(decode(data["_rails"]["message"]), data["_rails"]["exp"], data["_rails"]["pur"])
+            else
+              new(message)
+            end
+          end
+
+          def encode(message)
+            ::Base64.strict_encode64(message)
+          end
+
+          def decode(message)
+            ::Base64.strict_decode64(message)
+          end
+      end
+
+      def verify(purpose)
+        @message if match?(purpose) && fresh?
+      end
+
+      private
+        def match?(purpose)
+          @purpose.to_s == purpose.to_s
+        end
+
+        def fresh?
+          @expires_at.nil? || Time.now.utc < Time.iso8601(@expires_at)
+        end
+    end
+  end
+end

data/lib/active_support/messages/rotation_configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module Messages
+    class RotationConfiguration # :nodoc:
+      attr_reader :signed, :encrypted
+
+      def initialize
+        @signed, @encrypted = [], []
+      end
+
+      def rotate(kind, *args)
+        case kind
+        when :signed
+          @signed << args
+        when :encrypted
+          @encrypted << args
+        end
+      end
+    end
+  end
+end

data/lib/active_support/messages/rotator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module Messages
+    module Rotator # :nodoc:
+      def initialize(*, **options)
+        super
+
+        @options   = options
+        @rotations = []
+      end
+
+      def rotate(*secrets, **options)
+        @rotations << build_rotation(*secrets, @options.merge(options))
+      end
+
+      module Encryptor
+        include Rotator
+
+        def decrypt_and_verify(*args, on_rotation: nil, **options)
+          super
+        rescue MessageEncryptor::InvalidMessage, MessageVerifier::InvalidSignature
+          run_rotations(on_rotation) { |encryptor| encryptor.decrypt_and_verify(*args, options) } || raise
+        end
+
+        private
+          def build_rotation(secret = @secret, sign_secret = @sign_secret, options)
+            self.class.new(secret, sign_secret, options)
+          end
+      end
+
+      module Verifier
+        include Rotator
+
+        def verified(*args, on_rotation: nil, **options)
+          super || run_rotations(on_rotation) { |verifier| verifier.verified(*args, options) }
+        end
+
+        private
+          def build_rotation(secret = @secret, options)
+            self.class.new(secret, options)
+          end
+      end
+
+      private
+        def run_rotations(on_rotation)
+          @rotations.find do |rotation|
+            if message = yield(rotation) rescue next
+              on_rotation.call if on_rotation
+              return message
+            end
+          end
+        end
+    end
+  end
+end

data/lib/active_support/multibyte.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module ActiveSupport #:nodoc:
   module Multibyte
-    autoload :Chars, 'active_support/multibyte/chars'
-    autoload :Unicode, 'active_support/multibyte/unicode'
+    autoload :Chars, "active_support/multibyte/chars"
+    autoload :Unicode, "active_support/multibyte/unicode"
 
     # The proxy class returned when calling mb_chars. You can use this accessor
     # to configure your own proxy class so you can support other encodings. See

data/lib/active_support/multibyte/chars.rb

@@ -1,8 +1,10 @@
-# encoding: utf-8
-require 'active_support/json'
-require 'active_support/core_ext/string/access'
-require 'active_support/core_ext/string/behavior'
-require 'active_support/core_ext/module/delegation'
+# frozen_string_literal: true
+
+require "active_support/json"
+require "active_support/core_ext/string/access"
+require "active_support/core_ext/string/behavior"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/regexp"
 
 module ActiveSupport #:nodoc:
   module Multibyte #:nodoc:
@@ -16,7 +18,8 @@ module ActiveSupport #:nodoc:
     # through the +mb_chars+ method. Methods which would normally return a
     # String object now return a Chars object so methods can be chained.
     #
-    #   'The Perfect String  '.mb_chars.downcase.strip.normalize # => "the perfect string"
+    #   'The Perfect String  '.mb_chars.downcase.strip.normalize
+    #   # => #<ActiveSupport::Multibyte::Chars:0x007fdc434ccc10 @wrapped_string="the perfect string">
     #
     # Chars objects are perfectly interchangeable with String objects as long as
     # no explicit class checks are made. If certain methods do explicitly check
@@ -46,7 +49,7 @@ module ActiveSupport #:nodoc:
       alias to_s wrapped_string
       alias to_str wrapped_string
 
-      delegate :<=>, :=~, :acts_like_string?, :to => :wrapped_string
+      delegate :<=>, :=~, :acts_like_string?, to: :wrapped_string
 
       # Creates a new Chars instance by wrapping _string_.
       def initialize(string)
@@ -57,7 +60,7 @@ module ActiveSupport #:nodoc:
       # Forward all undefined methods to the wrapped string.
       def method_missing(method, *args, &block)
         result = @wrapped_string.__send__(method, *args, &block)
-        if method.to_s =~ /!$/
+        if /!$/.match?(method)
           self if result
         else
           result.kind_of?(String) ? chars(result) : result
@@ -86,17 +89,27 @@ module ActiveSupport #:nodoc:
         @wrapped_string.split(*args).map { |i| self.class.new(i) }
       end
 
-      # Works like like <tt>String#slice!</tt>, but returns an instance of
-      # Chars, or nil if the string was not modified.
+      # Works like <tt>String#slice!</tt>, but returns an instance of
+      # Chars, or +nil+ if the string was not modified. The string will not be
+      # modified if the range given is out of bounds
+      #
+      #   string = 'Welcome'
+      #   string.mb_chars.slice!(3)    # => #<ActiveSupport::Multibyte::Chars:0x000000038109b8 @wrapped_string="c">
+      #   string # => 'Welome'
+      #   string.mb_chars.slice!(0..3) # => #<ActiveSupport::Multibyte::Chars:0x00000002eb80a0 @wrapped_string="Welo">
+      #   string # => 'me'
       def slice!(*args)
-        chars(@wrapped_string.slice!(*args))
+        string_sliced = @wrapped_string.slice!(*args)
+        if string_sliced
+          chars(string_sliced)
+        end
       end
 
       # Reverses all characters in the string.
       #
       #   'Café'.mb_chars.reverse.to_s # => 'éfaC'
       def reverse
-        chars(Unicode.unpack_graphemes(@wrapped_string).reverse.flatten.pack('U*'))
+        chars(Unicode.unpack_graphemes(@wrapped_string).reverse.flatten.pack("U*"))
       end
 
       # Limits the byte size of the string to a number of bytes without breaking
@@ -124,7 +137,7 @@ module ActiveSupport #:nodoc:
 
       # Converts characters in the string to the opposite case.
       #
-      #    'El Cañón".mb_chars.swapcase.to_s # => "eL cAÑÓN"
+      #    'El Cañón'.mb_chars.swapcase.to_s # => "eL cAÑÓN"
       def swapcase
         chars Unicode.swapcase(@wrapped_string)
       end
@@ -133,15 +146,15 @@ module ActiveSupport #:nodoc:
       #
       #  'über'.mb_chars.capitalize.to_s # => "Über"
       def capitalize
-        (slice(0) || chars('')).upcase + (slice(1..-1) || chars('')).downcase
+        (slice(0) || chars("")).upcase + (slice(1..-1) || chars("")).downcase
       end
 
       # Capitalizes the first letter of every word, when possible.
       #
-      #   "ÉL QUE SE ENTERÓ".mb_chars.titleize    # => "Él Que Se Enteró"
-      #   "日本語".mb_chars.titleize                 # => "日本語"
+      #   "ÉL QUE SE ENTERÓ".mb_chars.titleize.to_s    # => "Él Que Se Enteró"
+      #   "日本語".mb_chars.titleize.to_s               # => "日本語"
       def titleize
-        chars(downcase.to_s.gsub(/\b('?\S)/u) { Unicode.upcase($1)})
+        chars(downcase.to_s.gsub(/\b('?\S)/u) { Unicode.upcase($1) })
       end
       alias_method :titlecase, :titleize
 
@@ -161,7 +174,7 @@ module ActiveSupport #:nodoc:
       #   'é'.length                         # => 2
       #   'é'.mb_chars.decompose.to_s.length # => 3
       def decompose
-        chars(Unicode.decompose(:canonical, @wrapped_string.codepoints.to_a).pack('U*'))
+        chars(Unicode.decompose(:canonical, @wrapped_string.codepoints.to_a).pack("U*"))
       end
 
       # Performs composition on all the characters.
@@ -169,7 +182,7 @@ module ActiveSupport #:nodoc:
       #   'é'.length                       # => 3
       #   'é'.mb_chars.compose.to_s.length # => 2
       def compose
-        chars(Unicode.compose(@wrapped_string.codepoints.to_a).pack('U*'))
+        chars(Unicode.compose(@wrapped_string.codepoints.to_a).pack("U*"))
       end
 
       # Returns the number of grapheme clusters in the string.
@@ -200,21 +213,21 @@ module ActiveSupport #:nodoc:
         end
       end
 
-      protected
+      private
 
-        def translate_offset(byte_offset) #:nodoc:
+        def translate_offset(byte_offset)
           return nil if byte_offset.nil?
-          return 0   if @wrapped_string == ''
+          return 0   if @wrapped_string == ""
 
           begin
-            @wrapped_string.byteslice(0...byte_offset).unpack('U*').length
+            @wrapped_string.byteslice(0...byte_offset).unpack("U*").length
           rescue ArgumentError
             byte_offset -= 1
             retry
           end
         end
 
-        def chars(string) #:nodoc:
+        def chars(string)
           self.class.new(string)
         end
     end