omg-activesupport 8.0.0.alpha1

data/lib/active_support/message_verifier.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "active_support/core_ext/object/blank"
+require "active_support/security_utils"
+require "active_support/messages/codec"
+require "active_support/messages/rotator"
+
+module ActiveSupport
+  # = Active Support Message Verifier
+  #
+  # +MessageVerifier+ makes it easy to generate and verify messages which are
+  # signed to prevent tampering.
+  #
+  # In a \Rails application, you can use +Rails.application.message_verifier+
+  # to manage unique instances of verifiers for each use case.
+  # {Learn more}[link:classes/Rails/Application.html#method-i-message_verifier].
+  #
+  # This is useful for cases like remember-me tokens and auto-unsubscribe links
+  # where the session store isn't suitable or available.
+  #
+  # First, generate a signed message:
+  #   cookies[:remember_me] = Rails.application.message_verifier(:remember_me).generate([@user.id, 2.weeks.from_now])
+  #
+  # Later verify that message:
+  #
+  #   id, time = Rails.application.message_verifier(:remember_me).verify(cookies[:remember_me])
+  #   if time.future?
+  #     self.current_user = User.find(id)
+  #   end
+  #
+  # === Signing is not encryption
+  #
+  # The signed messages are not encrypted. The payload is merely encoded (Base64 by default) and can be decoded by
+  # anyone. The signature is just assuring that the message wasn't tampered with. For example:
+  #
+  #     message = Rails.application.message_verifier('my_purpose').generate('never put secrets here')
+  #     # => "BAhJIhtuZXZlciBwdXQgc2VjcmV0cyBoZXJlBjoGRVQ=--a0c1c0827919da5e949e989c971249355735e140"
+  #     Base64.decode64(message.split("--").first) # no key needed
+  #     # => 'never put secrets here'
+  #
+  # If you also need to encrypt the contents, you must use ActiveSupport::MessageEncryptor instead.
+  #
+  # === Confine messages to a specific purpose
+  #
+  # It's not recommended to use the same verifier for different purposes in your application.
+  # Doing so could allow a malicious actor to re-use a signed message to perform an unauthorized
+  # action.
+  # You can reduce this risk by confining signed messages to a specific +:purpose+.
+  #
+  #   token = @verifier.generate("signed message", purpose: :login)
+  #
+  # Then that same purpose must be passed when verifying to get the data back out:
+  #
+  #   @verifier.verified(token, purpose: :login)    # => "signed message"
+  #   @verifier.verified(token, purpose: :shipping) # => nil
+  #   @verifier.verified(token)                     # => nil
+  #
+  #   @verifier.verify(token, purpose: :login)      # => "signed message"
+  #   @verifier.verify(token, purpose: :shipping)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token)                       # => raises ActiveSupport::MessageVerifier::InvalidSignature
+  #
+  # Likewise, if a message has no purpose it won't be returned when verifying with
+  # a specific purpose.
+  #
+  #   token = @verifier.generate("signed message")
+  #   @verifier.verified(token, purpose: :redirect) # => nil
+  #   @verifier.verified(token)                     # => "signed message"
+  #
+  #   @verifier.verify(token, purpose: :redirect)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token)                       # => "signed message"
+  #
+  # === Expiring messages
+  #
+  # 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("signed message", expires_in: 1.month)
+  #   @verifier.generate("signed message", expires_at: Time.now.end_of_year)
+  #
+  # Messages can then be verified and returned until expiry.
+  # Thereafter, the +verified+ method returns +nil+ while +verify+ raises
+  # +ActiveSupport::MessageVerifier::InvalidSignature+.
+  #
+  # === 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 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 < Messages::Codec
+    prepend Messages::Rotator
+
+    class InvalidSignature < StandardError; end
+
+    SEPARATOR = "--" # :nodoc:
+    SEPARATOR_LENGTH = SEPARATOR.length # :nodoc:
+
+    # Initialize a new MessageVerifier with a secret for the signature.
+    #
+    # ==== Options
+    #
+    # [+:digest+]
+    #   Digest used for signing. The default is <tt>"SHA1"</tt>. See
+    #   +OpenSSL::Digest+ for alternatives.
+    #
+    # [+:serializer+]
+    #   The serializer used to serialize message data. You can specify any
+    #   object that responds to +dump+ and +load+, or you can choose from
+    #   several preconfigured serializers: +:marshal+, +:json_allow_marshal+,
+    #   +:json+, +:message_pack_allow_marshal+, +:message_pack+.
+    #
+    #   The preconfigured serializers include a fallback mechanism to support
+    #   multiple deserialization formats. For example, the +:marshal+ serializer
+    #   will serialize using +Marshal+, but can deserialize using +Marshal+,
+    #   ActiveSupport::JSON, or ActiveSupport::MessagePack. This makes it easy
+    #   to migrate between serializers.
+    #
+    #   The +:marshal+, +:json_allow_marshal+, and +:message_pack_allow_marshal+
+    #   serializers support deserializing using +Marshal+, but the others do
+    #   not. Beware that +Marshal+ is a potential vector for deserialization
+    #   attacks in cases where a message signing secret has been leaked. <em>If
+    #   possible, choose a serializer that does not support +Marshal+.</em>
+    #
+    #   The +:message_pack+ and +:message_pack_allow_marshal+ serializers use
+    #   ActiveSupport::MessagePack, which can roundtrip some Ruby types that are
+    #   not supported by JSON, and may provide improved performance. However,
+    #   these require the +msgpack+ gem.
+    #
+    #   When using \Rails, the default depends on +config.active_support.message_serializer+.
+    #   Otherwise, the default is +:marshal+.
+    #
+    # [+:url_safe+]
+    #   By default, MessageVerifier generates RFC 4648 compliant strings which are
+    #   not URL-safe. In other words, they can contain "+" and "/". If you want to
+    #   generate URL-safe strings (in compliance with "Base 64 Encoding with URL
+    #   and Filename Safe Alphabet" in RFC 4648), you can pass +true+.
+    #
+    # [+:force_legacy_metadata_serializer+]
+    #   Whether to use the legacy metadata serializer, which serializes the
+    #   message first, then wraps it in an envelope which is also serialized. This
+    #   was the default in \Rails 7.0 and below.
+    #
+    #   If you don't pass a truthy value, the default is set using
+    #   +config.active_support.use_message_serializer_for_metadata+.
+    def initialize(secret, **options)
+      raise ArgumentError, "Secret should not be nil." unless secret
+      super(**options)
+      @secret = secret
+      @digest = options[:digest]&.to_s || "SHA1"
+    end
+
+    # Checks if a signed message could have been generated by signing an object
+    # with the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #   signed_message = verifier.generate("signed 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?(message)
+      !!catch_and_ignore(:invalid_message_format) { extract_encoded(message) }
+    end
+
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #
+    #   signed_message = verifier.generate("signed message")
+    #   verifier.verified(signed_message) # => "signed message"
+    #
+    # Returns +nil+ if the message was not signed with the same secret.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new("different_secret")
+    #   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
+    #
+    # ==== Options
+    #
+    # [+:purpose+]
+    #   The purpose that the message was generated with. If the purpose does not
+    #   match, +verified+ will return +nil+.
+    #
+    #     message = verifier.generate("hello", purpose: "greeting")
+    #     verifier.verified(message, purpose: "greeting") # => "hello"
+    #     verifier.verified(message, purpose: "chatting") # => nil
+    #     verifier.verified(message)                      # => nil
+    #
+    #     message = verifier.generate("bye")
+    #     verifier.verified(message)                      # => "bye"
+    #     verifier.verified(message, purpose: "greeting") # => nil
+    #
+    def verified(message, **options)
+      catch_and_ignore :invalid_message_format do
+        catch_and_raise :invalid_message_serialization do
+          catch_and_ignore :invalid_message_content do
+            read_message(message, **options)
+          end
+        end
+      end
+    end
+
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #   signed_message = verifier.generate("signed message")
+    #
+    #   verifier.verify(signed_message) # => "signed message"
+    #
+    # Raises +InvalidSignature+ if the message was not signed with the same
+    # secret or was not Base64-encoded.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new("different_secret")
+    #   other_verifier.verify(signed_message) # => ActiveSupport::MessageVerifier::InvalidSignature
+    #
+    # ==== Options
+    #
+    # [+:purpose+]
+    #   The purpose that the message was generated with. If the purpose does not
+    #   match, +verify+ will raise ActiveSupport::MessageVerifier::InvalidSignature.
+    #
+    #     message = verifier.generate("hello", purpose: "greeting")
+    #     verifier.verify(message, purpose: "greeting") # => "hello"
+    #     verifier.verify(message, purpose: "chatting") # => raises InvalidSignature
+    #     verifier.verify(message)                      # => raises InvalidSignature
+    #
+    #     message = verifier.generate("bye")
+    #     verifier.verify(message)                      # => "bye"
+    #     verifier.verify(message, purpose: "greeting") # => raises InvalidSignature
+    #
+    def verify(message, **options)
+      catch_and_raise :invalid_message_format, as: InvalidSignature do
+        catch_and_raise :invalid_message_serialization do
+          catch_and_raise :invalid_message_content, as: InvalidSignature do
+            read_message(message, **options)
+          end
+        end
+      end
+    end
+
+    # Generates a signed message for the provided value.
+    #
+    # The message is signed with the +MessageVerifier+'s secret.
+    # Returns Base64-encoded message joined with the generated signature.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #   verifier.generate("signed message") # => "BAhJIhNzaWduZWQgbWVzc2FnZQY6BkVU--f67d5f27c3ee0b8483cebf2103757455e947493b"
+    #
+    # ==== Options
+    #
+    # [+:expires_at+]
+    #   The datetime at which the message expires. After this datetime,
+    #   verification of the message will fail.
+    #
+    #     message = verifier.generate("hello", expires_at: Time.now.tomorrow)
+    #     verifier.verified(message) # => "hello"
+    #     # 24 hours later...
+    #     verifier.verified(message) # => nil
+    #     verifier.verify(message)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+    #
+    # [+:expires_in+]
+    #   The duration for which the message is valid. After this duration has
+    #   elapsed, verification of the message will fail.
+    #
+    #     message = verifier.generate("hello", expires_in: 24.hours)
+    #     verifier.verified(message) # => "hello"
+    #     # 24 hours later...
+    #     verifier.verified(message) # => nil
+    #     verifier.verify(message)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+    #
+    # [+:purpose+]
+    #   The purpose of the message. If specified, the same purpose must be
+    #   specified when verifying the message; otherwise, verification will fail.
+    #   (See #verified and #verify.)
+    def generate(value, **options)
+      create_message(value, **options)
+    end
+
+    def create_message(value, **options) # :nodoc:
+      sign_encoded(encode(serialize_with_metadata(value, **options)))
+    end
+
+    def read_message(message, **options) # :nodoc:
+      deserialize_with_metadata(decode(extract_encoded(message)), **options)
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
+    end
+
+    private
+      def sign_encoded(encoded)
+        digest = generate_digest(encoded)
+        encoded << SEPARATOR << digest
+      end
+
+      def extract_encoded(signed)
+        if signed.nil? || !signed.valid_encoding?
+          throw :invalid_message_format, "invalid message string"
+        end
+
+        if separator_index = separator_index_for(signed)
+          encoded = signed[0, separator_index]
+          digest = signed[separator_index + SEPARATOR_LENGTH, digest_length_in_hex]
+        end
+
+        unless digest_matches_data?(digest, encoded)
+          throw :invalid_message_format, "mismatched digest"
+        end
+
+        encoded
+      end
+
+      def generate_digest(data)
+        OpenSSL::HMAC.hexdigest(@digest, @secret, data)
+      end
+
+      def digest_length_in_hex
+        # In hexadecimal (AKA base16) it takes 4 bits to represent a character,
+        # hence we multiply the digest's length (in bytes) by 8 to get it in
+        # bits and divide by 4 to get its number of characters it hex. Well, 8
+        # divided by 4 is 2.
+        @digest_length_in_hex ||= OpenSSL::Digest.new(@digest).digest_length * 2
+      end
+
+      def separator_at?(signed_message, index)
+        signed_message[index, SEPARATOR_LENGTH] == SEPARATOR
+      end
+
+      def separator_index_for(signed_message)
+        index = signed_message.length - digest_length_in_hex - SEPARATOR_LENGTH
+        index unless index.negative? || !separator_at?(signed_message, index)
+      end
+
+      def digest_matches_data?(digest, data)
+        data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
+      end
+  end
+end

data/lib/active_support/message_verifiers.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "active_support/messages/rotation_coordinator"
+
+module ActiveSupport
+  class MessageVerifiers < Messages::RotationCoordinator
+    ##
+    # :attr_accessor: transitional
+    #
+    # If true, the first two rotation option sets are swapped when building
+    # message verifiers. For example, with the following configuration, message
+    # verifiers will generate messages using <tt>serializer: Marshal, url_safe: true</tt>,
+    # and will able to verify messages that were generated using any of the
+    # three option sets:
+    #
+    #   verifiers = ActiveSupport::MessageVerifiers.new { ... }
+    #   verifiers.rotate(serializer: JSON, url_safe: true)
+    #   verifiers.rotate(serializer: Marshal, url_safe: true)
+    #   verifiers.rotate(serializer: Marshal, url_safe: false)
+    #   verifiers.transitional = true
+    #
+    # This can be useful when performing a rolling deploy of an application,
+    # wherein servers that have not yet been updated must still be able to
+    # verify messages from updated servers. In such a scenario, first perform a
+    # rolling deploy with the new rotation (e.g. <tt>serializer: JSON, url_safe: true</tt>)
+    # as the first rotation and <tt>transitional = true</tt>. Then, after all
+    # servers have been updated, perform a second rolling deploy with
+    # <tt>transitional = false</tt>.
+
+    ##
+    # :method: initialize
+    # :call-seq: initialize(&secret_generator)
+    #
+    # Initializes a new instance. +secret_generator+ must accept a salt, and
+    # return a suitable secret (string). +secret_generator+ may also accept
+    # arbitrary kwargs. If #rotate is called with any options matching those
+    # kwargs, those options will be passed to +secret_generator+ instead of to
+    # the message verifier.
+    #
+    #   verifiers = ActiveSupport::MessageVerifiers.new do |salt, base:|
+    #     MySecretGenerator.new(base).generate(salt)
+    #   end
+    #
+    #   verifiers.rotate(base: "...")
+
+    ##
+    # :method: []
+    # :call-seq: [](salt)
+    #
+    # Returns a MessageVerifier configured with a secret derived from the
+    # given +salt+, and options from #rotate. MessageVerifier instances will
+    # be memoized, so the same +salt+ will return the same instance.
+
+    ##
+    # :method: []=
+    # :call-seq: []=(salt, verifier)
+    #
+    # Overrides a MessageVerifier instance associated with a given +salt+.
+
+    ##
+    # :method: rotate
+    # :call-seq: rotate(**options)
+    #
+    # Adds +options+ to the list of option sets. Messages will be signed using
+    # the first set in the list. When verifying, however, each set will be
+    # tried, in order, until one succeeds.
+    #
+    # Notably, the +:secret_generator+ option can specify a different secret
+    # generator than the one initially specified. The secret generator must
+    # respond to +call+, accept a salt, and return a suitable secret (string).
+    # The secret generator may also accept arbitrary kwargs.
+    #
+    # If any options match the kwargs of the operative secret generator, those
+    # options will be passed to the secret generator instead of to the message
+    # verifier.
+    #
+    # For fine-grained per-salt rotations, a block form is supported. The block
+    # will receive the salt, and should return an appropriate options Hash. The
+    # block may also return +nil+ to indicate that the rotation does not apply
+    # to the given salt. For example:
+    #
+    #   verifiers = ActiveSupport::MessageVerifiers.new { ... }
+    #
+    #   verifiers.rotate do |salt|
+    #     case salt
+    #     when :foo
+    #       { serializer: JSON, url_safe: true }
+    #     when :bar
+    #       { serializer: Marshal, url_safe: true }
+    #     end
+    #   end
+    #
+    #   verifiers.rotate(serializer: Marshal, url_safe: false)
+    #
+    #   # Uses `serializer: JSON, url_safe: true`.
+    #   # Falls back to `serializer: Marshal, url_safe: false`.
+    #   verifiers[:foo]
+    #
+    #   # Uses `serializer: Marshal, url_safe: true`.
+    #   # Falls back to `serializer: Marshal, url_safe: false`.
+    #   verifiers[:bar]
+    #
+    #   # Uses `serializer: Marshal, url_safe: false`.
+    #   verifiers[:baz]
+
+    ##
+    # :method: rotate_defaults
+    # :call-seq: rotate_defaults
+    #
+    # Invokes #rotate with the default options.
+
+    ##
+    # :method: clear_rotations
+    # :call-seq: clear_rotations
+    #
+    # Clears the list of option sets.
+
+    ##
+    # :method: on_rotation
+    # :call-seq: on_rotation(&callback)
+    #
+    # Sets a callback to invoke when a message is verified using an option set
+    # other than the first.
+    #
+    # For example, this callback could log each time it is called, and thus
+    # indicate whether old option sets are still in use or can be removed from
+    # rotation.
+
+    ##
+    private
+      def build(salt, secret_generator:, secret_generator_options:, **options)
+        MessageVerifier.new(secret_generator.call(salt, **secret_generator_options), **options)
+      end
+  end
+end

data/lib/active_support/messages/codec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+require_relative "metadata"
+require_relative "serializer_with_fallback"
+
+module ActiveSupport
+  module Messages # :nodoc:
+    class Codec # :nodoc:
+      include Metadata
+
+      class_attribute :default_serializer, default: :marshal,
+        instance_accessor: false, instance_predicate: false
+
+      def initialize(**options)
+        @serializer = options[:serializer] || self.class.default_serializer
+        @serializer = SerializerWithFallback[@serializer] if @serializer.is_a?(Symbol)
+        @url_safe = options[:url_safe]
+        @force_legacy_metadata_serializer = options[:force_legacy_metadata_serializer]
+      end
+
+      private
+        attr_reader :serializer
+
+        def encode(data, url_safe: @url_safe)
+          url_safe ? ::Base64.urlsafe_encode64(data, padding: false) : ::Base64.strict_encode64(data)
+        end
+
+        def decode(encoded, url_safe: @url_safe)
+          url_safe ? ::Base64.urlsafe_decode64(encoded) : ::Base64.strict_decode64(encoded)
+        rescue StandardError => error
+          throw :invalid_message_format, error
+        end
+
+        def serialize(data)
+          serializer.dump(data)
+        end
+
+        def deserialize(serialized)
+          serializer.load(serialized)
+        rescue StandardError => error
+          throw :invalid_message_serialization, error
+        end
+
+        def catch_and_ignore(throwable, &block)
+          catch throwable do
+            return block.call
+          end
+          nil
+        end
+
+        def catch_and_raise(throwable, as: nil, &block)
+          error = catch throwable do
+            return block.call
+          end
+          error = as.new(error.to_s) if as
+          raise error
+        end
+
+        def use_message_serializer_for_metadata?
+          !@force_legacy_metadata_serializer && super
+        end
+    end
+  end
+end