devise 3.2.2 → 4.6.0

data/lib/devise/parameter_sanitizer.rb

@@ -1,99 +1,173 @@
+# frozen_string_literal: true
+
 module Devise
-  class BaseSanitizer
-    attr_reader :params, :resource_name, :resource_class
+  # The +ParameterSanitizer+ deals with permitting specific parameters values
+  # for each +Devise+ scope in the application.
+  #
+  # The sanitizer knows about Devise default parameters (like +password+ and
+  # +password_confirmation+ for the `RegistrationsController`), and you can
+  # extend or change the permitted parameters list on your controllers.
+  #
+  # === Permitting new parameters
+  #
+  # You can add new parameters to the permitted list using the +permit+ method
+  # in a +before_action+ method, for instance.
+  #
+  #    class ApplicationController < ActionController::Base
+  #      before_action :configure_permitted_parameters, if: :devise_controller?
+  #
+  #      protected
+  #
+  #      def configure_permitted_parameters
+  #        # Permit the `subscribe_newsletter` parameter along with the other
+  #        # sign up parameters.
+  #        devise_parameter_sanitizer.permit(:sign_up, keys: [:subscribe_newsletter])
+  #      end
+  #    end
+  #
+  # Using a block yields an +ActionController::Parameters+ object so you can
+  # permit nested parameters and have more control over how the parameters are
+  # permitted in your controller.
+  #
+  #    def configure_permitted_parameters
+  #      devise_parameter_sanitizer.permit(:sign_up) do |user|
+  #        user.permit(newsletter_preferences: [])
+  #      end
+  #    end
+  class ParameterSanitizer
+    DEFAULT_PERMITTED_ATTRIBUTES = {
+      sign_in: [:password, :remember_me],
+      sign_up: [:password, :password_confirmation],
+      account_update: [:password, :password_confirmation, :current_password]
+    }
 
     def initialize(resource_class, resource_name, params)
-      @resource_class = resource_class
-      @resource_name  = resource_name
+      @auth_keys      = extract_auth_keys(resource_class)
       @params         = params
-      @blocks         = Hash.new
-    end
+      @resource_name  = resource_name
+      @permitted      = {}
 
-    def for(kind, &block)
-      if block_given?
-        @blocks[kind] = block
-      else
-        default_for(kind)
+      DEFAULT_PERMITTED_ATTRIBUTES.each_pair do |action, keys|
+        permit(action, keys: keys)
       end
     end
 
-    def sanitize(kind)
-      if block = @blocks[kind]
-        block.call(default_params)
+    # Sanitize the parameters for a specific +action+.
+    #
+    # === Arguments
+    #
+    # * +action+ - A +Symbol+ with the action that the controller is
+    #   performing, like +sign_up+, +sign_in+, etc.
+    #
+    # === Examples
+    #
+    #    # Inside the `RegistrationsController#create` action.
+    #    resource = build_resource(devise_parameter_sanitizer.sanitize(:sign_up))
+    #    resource.save
+    #
+    # Returns an +ActiveSupport::HashWithIndifferentAccess+ with the permitted
+    # attributes.
+    def sanitize(action)
+      permissions = @permitted[action]
+
+      if permissions.respond_to?(:call)
+        cast_to_hash permissions.call(default_params)
+      elsif permissions.present?
+        cast_to_hash permit_keys(default_params, permissions)
       else
-        default_sanitize(kind)
+        unknown_action!(action)
       end
     end
 
-    private
+    # Add or remove new parameters to the permitted list of an +action+.
+    #
+    # === Arguments
+    #
+    # * +action+ - A +Symbol+ with the action that the controller is
+    #   performing, like +sign_up+, +sign_in+, etc.
+    # * +keys:+     - An +Array+ of keys that also should be permitted.
+    # * +except:+   - An +Array+ of keys that shouldn't be permitted.
+    # * +block+     - A block that should be used to permit the action
+    #   parameters instead of the +Array+ based approach. The block will be
+    #   called with an +ActionController::Parameters+ instance.
+    #
+    # === Examples
+    #
+    #   # Adding new parameters to be permitted in the `sign_up` action.
+    #   devise_parameter_sanitizer.permit(:sign_up, keys: [:subscribe_newsletter])
+    #
+    #   # Removing the `password` parameter from the `account_update` action.
+    #   devise_parameter_sanitizer.permit(:account_update, except: [:password])
+    #
+    #   # Using the block form to completely override how we permit the
+    #   # parameters for the `sign_up` action.
+    #   devise_parameter_sanitizer.permit(:sign_up) do |user|
+    #     user.permit(:email, :password, :password_confirmation)
+    #   end
+    #
+    #
+    # Returns nothing.
+    def permit(action, keys: nil, except: nil, &block)
+      if block_given?
+        @permitted[action] = block
+      end
 
-    def default_for(kind)
-      raise ArgumentError, "a block is expected in Devise base sanitizer"
-    end
+      if keys.present?
+        @permitted[action] ||= @auth_keys.dup
+        @permitted[action].concat(keys)
+      end
 
-    def default_sanitize(kind)
-      default_params
+      if except.present?
+        @permitted[action] ||= @auth_keys.dup
+        @permitted[action] = @permitted[action] - except
+      end
     end
 
-    def default_params
-      params.fetch(resource_name, {})
-    end
-  end
+    private
 
-  class ParameterSanitizer < BaseSanitizer
-    def initialize(*)
-      super
-      @permitted = Hash.new { |h,k| h[k] = attributes_for(k) }
+    # Cast a sanitized +ActionController::Parameters+ to a +HashWithIndifferentAccess+
+    # that can be used elsewhere.
+    #
+    # Returns an +ActiveSupport::HashWithIndifferentAccess+.
+    def cast_to_hash(params)
+      # TODO: Remove the `with_indifferent_access` method call when we only support Rails 5+.
+      params && params.to_h.with_indifferent_access
     end
 
-    def sign_in
-      permit self.for(:sign_in)
+    def default_params
+      if hashable_resource_params?
+        @params.fetch(@resource_name)
+      else
+        empty_params
+      end
     end
 
-    def sign_up
-      permit self.for(:sign_up)
+    def hashable_resource_params?
+      @params[@resource_name].respond_to?(:permit)
     end
 
-    def account_update
-      permit self.for(:account_update)
+    def empty_params
+      ActionController::Parameters.new({})
     end
 
-    private
-
-    # TODO: We do need to flatten so it works with strong_parameters
-    # gem. We should drop it once we move to Rails 4 only support.
-    def permit(keys)
-      default_params.permit(*Array(keys))
+    def permit_keys(parameters, keys)
+      parameters.permit(*keys)
     end
 
-    # Change for(kind) to return the values in the @permitted
-    # hash, allowing the developer to customize at runtime.
-    def default_for(kind)
-      @permitted[kind] || raise("No sanitizer provided for #{kind}")
-    end
+    def extract_auth_keys(klass)
+      auth_keys = klass.authentication_keys
 
-    def default_sanitize(kind)
-      if respond_to?(kind, true)
-        send(kind)
-      else
-        raise NotImplementedError, "Devise doesn't know how to sanitize parameters for #{kind}"
-      end
+      auth_keys.respond_to?(:keys) ? auth_keys.keys : auth_keys
     end
 
-    def attributes_for(kind)
-      case kind
-      when :sign_in
-        auth_keys + [:password, :remember_me]
-      when :sign_up
-        auth_keys + [:password, :password_confirmation]
-      when :account_update
-        auth_keys + [:password, :password_confirmation, :current_password]
-      end
-    end
+    def unknown_action!(action)
+      raise NotImplementedError, <<-MESSAGE.strip_heredoc
+        "Devise doesn't know how to sanitize parameters for '#{action}'".
+        If you want to define a new set of parameters to be sanitized use the
+        `permit` method first:
 
-    def auth_keys
-      @auth_keys ||= @resource_class.authentication_keys.respond_to?(:keys) ?
-                       @resource_class.authentication_keys.keys : @resource_class.authentication_keys
+          devise_parameter_sanitizer.permit(:#{action}, keys: [:param1, :param2, :param3])
+      MESSAGE
     end
   end
 end