Permit list usage cleanup and clearer documentation

15 files changed, 41 insertions, 40 deletions

diff --git a/actionpack/lib/action_controller/metal/force_ssl.rb b/actionpack/lib/action_controller/metal/force_ssl.rb
index b9c8148347..26e6f72b66 100644
--- a/actionpack/lib/action_controller/metal/force_ssl.rb
+++ b/actionpack/lib/action_controller/metal/force_ssl.rb
@@ -5,8 +5,8 @@ require "active_support/core_ext/hash/slice"
 
 module ActionController
   # This module is deprecated in favor of +config.force_ssl+ in your environment
-  # config file. This will ensure all communication to non-permitted endpoints
-  # served by your application occurs over HTTPS.
+  # config file. This will ensure all endpoints not explicitly marked otherwise
+  # will have all communication served over HTTPS.
   module ForceSSL # :nodoc:
     extend ActiveSupport::Concern
     include AbstractController::Callbacks
diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index a2e5861b90..52664dd1fb 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -997,8 +997,8 @@ module ActionController
   #
   # It provides an interface for protecting attributes from end-user
   # assignment. This makes Action Controller parameters forbidden
-  # to be used in Active Model mass assignment until they have been
-  # permitted.
+  # to be used in Active Model mass assignment until they have been explicitly
+  # enumerated.
   #
   # In addition, parameters can be marked as required and flow through a
   # predefined raise/rescue flow to end up as a <tt>400 Bad Request</tt> with no
diff --git a/actionpack/lib/action_dispatch/http/mime_negotiation.rb b/actionpack/lib/action_dispatch/http/mime_negotiation.rb
index 580f5fe41a..be129965d1 100644
--- a/actionpack/lib/action_dispatch/http/mime_negotiation.rb
+++ b/actionpack/lib/action_dispatch/http/mime_negotiation.rb
@@ -85,10 +85,7 @@ module ActionDispatch
         if variant.all? { |v| v.is_a?(Symbol) }
           @variant = ActiveSupport::ArrayInquirer.new(variant)
         else
-          raise ArgumentError, "request.variant must be set to a Symbol or an Array of Symbols. " \
-            "For security reasons, never directly set the variant to a user-provided value, " \
-            "like params[:variant].to_sym. Check user-provided value against a permitted list first, " \
-            "then set the variant: request.variant = :tablet if params[:variant] == 'tablet'"
+          raise ArgumentError, "request.variant must be set to a Symbol or an Array of Symbols."
         end
       end
 
diff --git a/actionpack/test/controller/parameters/always_permitted_parameters_test.rb b/actionpack/test/controller/parameters/always_permitted_parameters_test.rb
index d913bf3226..974612fb7b 100644
--- a/actionpack/test/controller/parameters/always_permitted_parameters_test.rb
+++ b/actionpack/test/controller/parameters/always_permitted_parameters_test.rb
@@ -20,7 +20,7 @@ class AlwaysPermittedParametersTest < ActiveSupport::TestCase
     end
   end
 
-  test "permits parameters that are permitted" do
+  test "allows both explicitly listed and always-permitted parameters" do
     params = ActionController::Parameters.new(
       book: { pages: 65 },
       format: "json")
diff --git a/actionview/lib/action_view/helpers/sanitize_helper.rb b/actionview/lib/action_view/helpers/sanitize_helper.rb
index d27d5d7e12..f4fa133f55 100644
--- a/actionview/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionview/lib/action_view/helpers/sanitize_helper.rb
@@ -10,7 +10,7 @@ module ActionView
     # These helper methods extend Action View making them callable within your template files.
     module SanitizeHelper
       extend ActiveSupport::Concern
-      # Sanitizes HTML input, stripping all tags and attributes that aren't permitted.
+      # Sanitizes HTML input, stripping all but known-safe tags and attributes.
       #
       # It also strips href/src attributes with unsafe protocols like
       # <tt>javascript:</tt>, while also protecting against attempts to use Unicode,
diff --git a/actionview/lib/action_view/template/handlers/erb.rb b/actionview/lib/action_view/template/handlers/erb.rb
index 93edef9c26..270be0a380 100644
--- a/actionview/lib/action_view/template/handlers/erb.rb
+++ b/actionview/lib/action_view/template/handlers/erb.rb
@@ -14,15 +14,15 @@ module ActionView
         class_attribute :erb_implementation, default: Erubi
 
         # Do not escape templates of these mime types.
-        class_attribute :escape_permit_list, default: ["text/plain"]
+        class_attribute :escape_ignore_list, default: ["text/plain"]
 
         [self, singleton_class].each do |base|
-          base.alias_method :escape_whitelist, :escape_permit_list
-          base.alias_method :escape_whitelist=, :escape_permit_list=
+          base.send(:alias_method, :escape_whitelist, :escape_ignore_list)
+          base.send(:alias_method, :escape_whitelist=, :escape_ignore_list=)
 
           base.deprecate(
-            escape_whitelist: 'use #escape_permit_list instead',
-            :escape_whitelist= => 'use #escape_permit_list= instead'
+            escape_whitelist: "use #escape_ignore_list instead",
+            :escape_whitelist= => "use #escape_ignore_list= instead"
           )
         end
 
@@ -57,7 +57,7 @@ module ActionView
 
           self.class.erb_implementation.new(
             erb,
-            escape: (self.class.escape_permit_list.include? template.type),
+            escape: (self.class.escape_ignore_list.include? template.type),
             trim: (self.class.erb_trim_mode == "-")
           ).src
         end
diff --git a/activejob/lib/active_job/arguments.rb b/activejob/lib/active_job/arguments.rb
index 43897faf4c..ba7f9456f9 100644
--- a/activejob/lib/active_job/arguments.rb
+++ b/activejob/lib/active_job/arguments.rb
@@ -26,16 +26,18 @@ module ActiveJob
     # :nodoc:
     PERMITTED_TYPES = [ NilClass, String, Integer, Float, BigDecimal, TrueClass, FalseClass ]
 
-    # Serializes a set of arguments. Permitted types are returned
-    # as-is. Arrays/Hashes are serialized element by element.
-    # All other types are serialized using GlobalID.
+    # Serializes a set of arguments. Intrinsic types that can safely be
+    # serialized without mutation are returned as-is. Arrays/Hashes are
+    # serialized element by element. All other types are serialized using
+    # GlobalID.
     def serialize(arguments)
       arguments.map { |argument| serialize_argument(argument) }
     end
 
-    # Deserializes a set of arguments. Permitted types are returned
-    # as-is. Arrays/Hashes are deserialized element by element.
-    # All other types are deserialized using GlobalID.
+    # Deserializes a set of arguments. Instrinsic types that can safely be
+    # deserialized without mutation are returned as-is. Arrays/Hashes are
+    # deserialized element by element. All other types are deserialized using
+    # GlobalID.
     def deserialize(arguments)
       arguments.map { |argument| deserialize_argument(argument) }
     rescue
diff --git a/activerecord/lib/active_record/attribute_methods.rb b/activerecord/lib/active_record/attribute_methods.rb
index 2e68bdd741..1d18119c66 100644
--- a/activerecord/lib/active_record/attribute_methods.rb
+++ b/activerecord/lib/active_record/attribute_methods.rb
@@ -167,12 +167,14 @@ module ActiveRecord
         end
       end
 
-      # Regexp permitted list. Matches the following:
+      # Regexp for column names (with or without a table name prefix). Matches
+      # the following:
       #   "#{table_name}.#{column_name}"
       #   "#{column_name}"
-      COLUMN_NAME_PERMIT_LIST = /\A(?:\w+\.)?\w+\z/i
+      COLUMN_NAME = /\A(?:\w+\.)?\w+\z/i
 
-      # Regexp permitted list. Matches the following:
+      # Regexp for column names with order (with or without a table name
+      # prefix, with or without various order modifiers). Matches the following:
       #   "#{table_name}.#{column_name}"
       #   "#{table_name}.#{column_name} #{direction}"
       #   "#{table_name}.#{column_name} #{direction} NULLS FIRST"
@@ -181,7 +183,7 @@ module ActiveRecord
       #   "#{column_name} #{direction}"
       #   "#{column_name} #{direction} NULLS FIRST"
       #   "#{column_name} NULLS LAST"
-      COLUMN_NAME_ORDER_PERMIT_LIST = /
+      COLUMN_NAME_WITH_ORDER = /
         \A
         (?:\w+\.)?
         \w+
@@ -190,12 +192,12 @@ module ActiveRecord
         \z
       /ix
 
-      def enforce_raw_sql_permit_list(args, permit_list: COLUMN_NAME_PERMIT_LIST) # :nodoc:
+      def disallow_raw_sql!(args, permit: COLUMN_NAME) # :nodoc:
         unexpected = args.reject do |arg|
           arg.kind_of?(Arel::Node) ||
             arg.is_a?(Arel::Nodes::SqlLiteral) ||
             arg.is_a?(Arel::Attributes::Attribute) ||
-            arg.to_s.split(/\s*,\s*/).all? { |part| permit_list.match?(part) }
+            arg.to_s.split(/\s*,\s*/).all? { |part| permit.match?(part) }
         end
 
         return if unexpected.none?
diff --git a/activerecord/lib/active_record/relation/calculations.rb b/activerecord/lib/active_record/relation/calculations.rb
index ad9ccfa215..0fa5ba2e50 100644
--- a/activerecord/lib/active_record/relation/calculations.rb
+++ b/activerecord/lib/active_record/relation/calculations.rb
@@ -190,7 +190,7 @@ module ActiveRecord
         relation = apply_join_dependency
         relation.pluck(*column_names)
       else
-        enforce_raw_sql_permit_list(column_names)
+        disallow_raw_sql!(column_names)
         relation = spawn
         relation.select_values = column_names.map { |cn|
           @klass.has_attribute?(cn) || @klass.attribute_alias?(cn) ? arel_attribute(cn) : cn
diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 4a6ffea3e7..56497e11cb 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -1133,9 +1133,9 @@ module ActiveRecord
         end
         order_args.flatten!
 
-        @klass.enforce_raw_sql_permit_list(
+        @klass.disallow_raw_sql!(
           order_args.flat_map { |a| a.is_a?(Hash) ? a.keys : a },
-          permit_list: AttributeMethods::ClassMethods::COLUMN_NAME_ORDER_PERMIT_LIST
+          permit: AttributeMethods::ClassMethods::COLUMN_NAME_WITH_ORDER
         )
 
         validate_order_args(order_args)
diff --git a/activerecord/lib/active_record/sanitization.rb b/activerecord/lib/active_record/sanitization.rb
index d398d03ebb..3485d9e557 100644
--- a/activerecord/lib/active_record/sanitization.rb
+++ b/activerecord/lib/active_record/sanitization.rb
@@ -61,8 +61,8 @@ module ActiveRecord
       #   # => "id ASC"
       def sanitize_sql_for_order(condition)
         if condition.is_a?(Array) && condition.first.to_s.include?("?")
-          enforce_raw_sql_permit_list([condition.first],
-            permit_list: AttributeMethods::ClassMethods::COLUMN_NAME_ORDER_PERMIT_LIST
+          disallow_raw_sql!([condition.first],
+            permit: AttributeMethods::ClassMethods::COLUMN_NAME_WITH_ORDER
           )
 
           # Ensure we aren't dealing with a subclass of String that might
diff --git a/activerecord/test/cases/explain_subscriber_test.rb b/activerecord/test/cases/explain_subscriber_test.rb
index 0277610219..79a0630193 100644
--- a/activerecord/test/cases/explain_subscriber_test.rb
+++ b/activerecord/test/cases/explain_subscriber_test.rb
@@ -40,7 +40,7 @@ if ActiveRecord::Base.connection.supports_explain?
       assert_equal binds, queries[0][1]
     end
 
-    def test_collects_nothing_if_the_statement_is_not_permitted
+    def test_collects_nothing_if_the_statement_is_not_explainable
       SUBSCRIBER.finish(nil, nil, name: "SQL", sql: "SHOW max_identifier_length")
       assert_empty queries
     end
diff --git a/activerecord/test/cases/relation/delegation_test.rb b/activerecord/test/cases/relation/delegation_test.rb
index da1b3cdb18..a8030c2d64 100644
--- a/activerecord/test/cases/relation/delegation_test.rb
+++ b/activerecord/test/cases/relation/delegation_test.rb
@@ -5,7 +5,7 @@ require "models/post"
 require "models/comment"
 
 module ActiveRecord
-  module DelegationPermitListTests
+  module ArrayDelegationTests
     ARRAY_DELEGATES = [
       :+, :-, :|, :&, :[], :shuffle,
       :all?, :collect, :compact, :detect, :each, :each_cons, :each_with_index,
@@ -38,7 +38,7 @@ module ActiveRecord
   end
 
   class DelegationAssociationTest < ActiveRecord::TestCase
-    include DelegationPermitListTests
+    include ArrayDelegationTests
     include DeprecatedArelDelegationTests
 
     def target
@@ -47,7 +47,7 @@ module ActiveRecord
   end
 
   class DelegationRelationTest < ActiveRecord::TestCase
-    include DelegationPermitListTests
+    include ArrayDelegationTests
     include DeprecatedArelDelegationTests
 
     def target
diff --git a/activerecord/test/models/post.rb b/activerecord/test/models/post.rb
index 02d1ee25dd..528585fb75 100644
--- a/activerecord/test/models/post.rb
+++ b/activerecord/test/models/post.rb
@@ -324,7 +324,7 @@ class FakeKlass
       table[name]
     end
 
-    def enforce_raw_sql_permit_list(*args)
+    def disallow_raw_sql!(*args)
       # noop
     end
 
diff --git a/railties/test/generators/migration_generator_test.rb b/railties/test/generators/migration_generator_test.rb
index 44c27c87f8..657a56354b 100644
--- a/railties/test/generators/migration_generator_test.rb
+++ b/railties/test/generators/migration_generator_test.rb
@@ -51,12 +51,12 @@ class MigrationGeneratorTest < Rails::Generators::TestCase
   end
 
   def test_add_migration_with_table_having_from_in_title
-    migration = "add_email_address_to_restricted_list_from_campaign"
+    migration = "add_email_address_to_excluded_from_campaign"
     run_generator [migration, "email_address:string"]
 
     assert_migration "db/migrate/#{migration}.rb" do |content|
       assert_method :change, content do |change|
-        assert_match(/add_column :restricted_list_from_campaigns, :email_address, :string/, change)
+        assert_match(/add_column :excluded_from_campaigns, :email_address, :string/, change)
       end
     end
   end