renamed mass-assignment scopes to roles, updated code, tests, docs and security guide

6 files changed, 64 insertions, 64 deletions

diff --git a/activemodel/lib/active_model/mass_assignment_security.rb b/activemodel/lib/active_model/mass_assignment_security.rb
index 01eef762fd..483b577681 100644
--- a/activemodel/lib/active_model/mass_assignment_security.rb
+++ b/activemodel/lib/active_model/mass_assignment_security.rb
@@ -35,17 +35,17 @@ module ActiveModel
     #     protected
     #
     #     def account_params
-    #       scope = admin ? :admin : :default
-    #       sanitize_for_mass_assignment(params[:account], scope)
+    #       role = admin ? :admin : :default
+    #       sanitize_for_mass_assignment(params[:account], role)
     #     end
     #
     #   end
     #
     module ClassMethods
       # Attributes named in this macro are protected from mass-assignment
-      # whenever attributes are sanitized before assignment. A scope for the
-      # attributes is optional, if no scope is provided then :default is used.
-      # A scope can be defined by using the :as option.
+      # whenever attributes are sanitized before assignment. A role for the
+      # attributes is optional, if no role is provided then :default is used.
+      # A role can be defined by using the :as option.
       #
       # Mass-assignment to these attributes will simply be ignored, to assign
       # to them you can use direct writer methods. This is meant to protect
@@ -67,7 +67,7 @@ module ActiveModel
       #     end
       #   end
       #
-      # When using a :default scope :
+      # When using the :default role :
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :default)
@@ -78,7 +78,7 @@ module ActiveModel
       #   customer.credit_rating = "Average"
       #   customer.credit_rating # => "Average"
       #
-      # And using the :admin scope :
+      # And using the :admin role :
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :admin)
@@ -93,10 +93,10 @@ module ActiveModel
       # to sanitize attributes won't provide sufficient protection.
       def attr_protected(*args)
         options = args.extract_options!
-        scope = options[:as] || :default
+        role = options[:as] || :default
 
         self._protected_attributes        = protected_attributes_configs.dup
-        self._protected_attributes[scope] = self.protected_attributes(scope) + args
+        self._protected_attributes[role] = self.protected_attributes(role) + args
 
         self._active_authorizer = self._protected_attributes
       end
@@ -104,8 +104,8 @@ module ActiveModel
       # Specifies a white list of model attributes that can be set via
       # mass-assignment.
       #
-      # Like +attr_protected+, a scope for the attributes is optional,
-      # if no scope is provided then :default is used. A scope can be defined by
+      # Like +attr_protected+, a role for the attributes is optional,
+      # if no role is provided then :default is used. A role can be defined by
       # using the :as option.
       #
       # This is the opposite of the +attr_protected+ macro: Mass-assignment
@@ -131,7 +131,7 @@ module ActiveModel
       #     end
       #   end
       #
-      # When using a :default scope :
+      # When using the :default role :
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :default)
@@ -141,7 +141,7 @@ module ActiveModel
       #   customer.credit_rating = "Average"
       #   customer.credit_rating # => "Average"
       #
-      # And using the :admin scope :
+      # And using the :admin role :
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :admin)
@@ -152,20 +152,20 @@ module ActiveModel
       # to sanitize attributes won't provide sufficient protection.
       def attr_accessible(*args)
         options = args.extract_options!
-        scope = options[:as] || :default
+        role = options[:as] || :default
 
         self._accessible_attributes        = accessible_attributes_configs.dup
-        self._accessible_attributes[scope] = self.accessible_attributes(scope) + args
+        self._accessible_attributes[role] = self.accessible_attributes(role) + args
 
         self._active_authorizer = self._accessible_attributes
       end
 
-      def protected_attributes(scope = :default)
-        protected_attributes_configs[scope]
+      def protected_attributes(role = :default)
+        protected_attributes_configs[role]
       end
 
-      def accessible_attributes(scope = :default)
-        accessible_attributes_configs[scope]
+      def accessible_attributes(role = :default)
+        accessible_attributes_configs[role]
       end
 
       def active_authorizers
@@ -198,12 +198,12 @@ module ActiveModel
 
   protected
 
-    def sanitize_for_mass_assignment(attributes, scope = :default)
-      mass_assignment_authorizer(scope).sanitize(attributes)
+    def sanitize_for_mass_assignment(attributes, role = :default)
+      mass_assignment_authorizer(role).sanitize(attributes)
     end
 
-    def mass_assignment_authorizer(scope = :default)
-      self.class.active_authorizer[scope]
+    def mass_assignment_authorizer(role = :default)
+      self.class.active_authorizer[role]
     end
   end
 end
diff --git a/activemodel/test/cases/mass_assignment_security_test.rb b/activemodel/test/cases/mass_assignment_security_test.rb
index b22ce874ea..43a12eed61 100644
--- a/activemodel/test/cases/mass_assignment_security_test.rb
+++ b/activemodel/test/cases/mass_assignment_security_test.rb
@@ -10,7 +10,7 @@ class MassAssignmentSecurityTest < ActiveModel::TestCase
     assert_equal expected, sanitized
   end
 
-  def test_only_moderator_scope_attribute_accessible
+  def test_only_moderator_role_attribute_accessible
     user = SpecialUser.new
     expected = { "name" => "John Smith", "email" => "john@smith.com" }
     sanitized = user.sanitize_for_mass_assignment(expected.merge("admin" => true), :moderator)
@@ -27,7 +27,7 @@ class MassAssignmentSecurityTest < ActiveModel::TestCase
     assert_equal expected, sanitized
   end
 
-  def test_admin_scoped_attributes_accessible
+  def test_attributes_accessible_with_admin_role
     user = Person.new
     expected = { "name" => "John Smith", "email" => "john@smith.com", "admin" => true }
     sanitized = user.sanitize_for_mass_assignment(expected.merge("super_powers" => true), :admin)
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 78318b1be0..67af21c9a0 100644
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -482,7 +482,7 @@ module ActiveRecord #:nodoc:
       #   # Create a single new object
       #   User.create(:first_name => 'Jamie')
       #
-      #   # Create a single new object using the :admin mass-assignment security scope
+      #   # Create a single new object using the :admin mass-assignment security role
       #   User.create({ :first_name => 'Jamie', :is_admin => true }, :as => :admin)
       #
       #   # Create a single new object bypassing mass-assignment security
@@ -1486,7 +1486,7 @@ MSG
       #   # Instantiates a single new object
       #   User.new(:first_name => 'Jamie')
       #
-      #   # Instantiates a single new object using the :admin mass-assignment security scope
+      #   # Instantiates a single new object using the :admin mass-assignment security role
       #   User.new({ :first_name => 'Jamie', :is_admin => true }, :as => :admin)
       #
       #   # Instantiates a single new object bypassing mass-assignment security
@@ -1661,8 +1661,8 @@ MSG
       end
 
       # Allows you to set all the attributes for a particular mass-assignment
-      # security scope by passing in a hash of attributes with keys matching
-      # the attribute names (which again matches the column names) and the scope
+      # security role by passing in a hash of attributes with keys matching
+      # the attribute names (which again matches the column names) and the role
       # name using the :as option.
       #
       # To bypass mass-assignment security you can use the :without_protection => true
@@ -1689,12 +1689,12 @@ MSG
       #   user.is_admin?  # => true
       def assign_attributes(new_attributes, options = {})
         attributes = new_attributes.stringify_keys
-        scope = options[:as] || :default
+        role = options[:as] || :default
 
         multi_parameter_attributes = []
 
         unless options[:without_protection]
-          attributes = sanitize_for_mass_assignment(attributes, scope)
+          attributes = sanitize_for_mass_assignment(attributes, role)
         end
 
         attributes.each do |k, v|
diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb
index b4531ed35f..b9041f44d8 100644
--- a/activerecord/lib/active_record/persistence.rb
+++ b/activerecord/lib/active_record/persistence.rb
@@ -146,7 +146,7 @@ module ActiveRecord
     # will fail and false will be returned.
     #
     # When updating model attributes, mass-assignment security protection is respected.
-    # If no +:as+ option is supplied then the +:default+ scope will be used.
+    # If no +:as+ option is supplied then the +:default+ role will be used.
     # If you want to bypass the protection given by +attr_protected+ and
     # +attr_accessible+ then you can do so using the +:without_protection+ option.
     def update_attributes(attributes, options = {})
diff --git a/activerecord/test/cases/mass_assignment_security_test.rb b/activerecord/test/cases/mass_assignment_security_test.rb
index fbbae99e8b..c81015b7c2 100644
--- a/activerecord/test/cases/mass_assignment_security_test.rb
+++ b/activerecord/test/cases/mass_assignment_security_test.rb
@@ -87,7 +87,7 @@ class MassAssignmentSecurityTest < ActiveRecord::TestCase
     end
   end
 
-  def test_assign_attributes_uses_default_scope_when_no_scope_is_provided
+  def test_assign_attributes_uses_default_role_when_no_role_is_provided
     p = LoosePerson.new
     p.assign_attributes(attributes_hash)
 
@@ -101,28 +101,28 @@ class MassAssignmentSecurityTest < ActiveRecord::TestCase
     assert_all_attributes(p)
   end
 
-  def test_assign_attributes_with_default_scope_and_attr_protected_attributes
+  def test_assign_attributes_with_default_role_and_attr_protected_attributes
     p = LoosePerson.new
     p.assign_attributes(attributes_hash, :as => :default)
 
     assert_default_attributes(p)
   end
 
-  def test_assign_attributes_with_admin_scope_and_attr_protected_attributes
+  def test_assign_attributes_with_admin_role_and_attr_protected_attributes
     p = LoosePerson.new
     p.assign_attributes(attributes_hash, :as => :admin)
 
     assert_admin_attributes(p)
   end
 
-  def test_assign_attributes_with_default_scope_and_attr_accessible_attributes
+  def test_assign_attributes_with_default_role_and_attr_accessible_attributes
     p = TightPerson.new
     p.assign_attributes(attributes_hash, :as => :default)
 
     assert_default_attributes(p)
   end
 
-  def test_assign_attributes_with_admin_scope_and_attr_accessible_attributes
+  def test_assign_attributes_with_admin_role_and_attr_accessible_attributes
     p = TightPerson.new
     p.assign_attributes(attributes_hash, :as => :admin)
 
@@ -153,25 +153,25 @@ class MassAssignmentSecurityTest < ActiveRecord::TestCase
     assert_default_attributes(p, true)
   end
 
-  def test_new_with_admin_scope_with_attr_accessible_attributes
+  def test_new_with_admin_role_with_attr_accessible_attributes
     p = TightPerson.new(attributes_hash, :as => :admin)
 
     assert_admin_attributes(p)
   end
 
-  def test_new_with_admin_scope_with_attr_protected_attributes
+  def test_new_with_admin_role_with_attr_protected_attributes
     p = LoosePerson.new(attributes_hash, :as => :admin)
 
     assert_admin_attributes(p)
   end
 
-  def test_create_with_admin_scope_with_attr_accessible_attributes
+  def test_create_with_admin_role_with_attr_accessible_attributes
     p = TightPerson.create(attributes_hash, :as => :admin)
 
     assert_admin_attributes(p, true)
   end
 
-  def test_create_with_admin_scope_with_attr_protected_attributes
+  def test_create_with_admin_role_with_attr_protected_attributes
     p = LoosePerson.create(attributes_hash, :as => :admin)
 
     assert_admin_attributes(p, true)
@@ -230,12 +230,12 @@ class MassAssignmentSecurityHasOneRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend)
   end
 
-  def test_has_one_build_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_build_with_admin_role_with_attr_protected_attributes
     best_friend = @person.build_best_friend(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend)
   end
 
-  def test_has_one_build_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_build_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.build_best_friend(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend)
   end
@@ -257,12 +257,12 @@ class MassAssignmentSecurityHasOneRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_create_with_admin_role_with_attr_protected_attributes
     best_friend = @person.create_best_friend(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_create_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.create_best_friend(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
@@ -284,12 +284,12 @@ class MassAssignmentSecurityHasOneRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_bang_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_create_with_bang_with_admin_role_with_attr_protected_attributes
     best_friend = @person.create_best_friend!(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_bang_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_create_with_bang_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.create_best_friend!(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
@@ -318,12 +318,12 @@ class MassAssignmentSecurityBelongsToRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend)
   end
 
-  def test_has_one_build_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_build_with_admin_role_with_attr_protected_attributes
     best_friend = @person.build_best_friend_of(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend)
   end
 
-  def test_has_one_build_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_build_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.build_best_friend_of(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend)
   end
@@ -345,12 +345,12 @@ class MassAssignmentSecurityBelongsToRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_create_with_admin_role_with_attr_protected_attributes
     best_friend = @person.create_best_friend_of(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_create_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.create_best_friend_of(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
@@ -372,12 +372,12 @@ class MassAssignmentSecurityBelongsToRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_bang_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_create_with_bang_with_admin_role_with_attr_protected_attributes
     best_friend = @person.create_best_friend!(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_bang_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_create_with_bang_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.create_best_friend!(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
@@ -406,12 +406,12 @@ class MassAssignmentSecurityHasManyRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend)
   end
 
-  def test_has_one_build_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_build_with_admin_role_with_attr_protected_attributes
     best_friend = @person.best_friends.build(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend)
   end
 
-  def test_has_one_build_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_build_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.best_friends.build(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend)
   end
@@ -433,12 +433,12 @@ class MassAssignmentSecurityHasManyRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_create_with_admin_role_with_attr_protected_attributes
     best_friend = @person.best_friends.create(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_create_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.best_friends.create(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
@@ -460,12 +460,12 @@ class MassAssignmentSecurityHasManyRelationsTest < ActiveRecord::TestCase
     assert_default_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_bang_with_admin_scope_with_attr_protected_attributes
+  def test_has_one_create_with_bang_with_admin_role_with_attr_protected_attributes
     best_friend = @person.best_friends.create!(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
 
-  def test_has_one_create_with_bang_with_admin_scope_with_attr_accessible_attributes
+  def test_has_one_create_with_bang_with_admin_role_with_attr_accessible_attributes
     best_friend = @person.best_friends.create!(attributes_hash, :as => :admin)
     assert_admin_attributes(best_friend, true)
   end
diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile
index 8c408ec06b..e0ccc7a6e6 100644
--- a/railties/guides/source/security.textile
+++ b/railties/guides/source/security.textile
@@ -372,7 +372,7 @@ def signup
 end
 </ruby>
 
-Mass-assignment saves you much work, because you don't have to set each value individually. Simply pass a hash to the new() method, or assign attributes=(attributes) a hash value, to set the model's attributes to the values in the hash. The problem is that it is often used in conjunction with the parameters (params) hash available in the controller, which may be manipulated by an attacker. He may do so by changing the URL like this:
+Mass-assignment saves you much work, because you don't have to set each value individually. Simply pass a hash to the +new+ method, or +assign_attributes=+ a hash value, to set the model's attributes to the values in the hash. The problem is that it is often used in conjunction with the parameters (params) hash available in the controller, which may be manipulated by an attacker. He may do so by changing the URL like this:
 
 <pre>
 "name":http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1
@@ -386,7 +386,7 @@ params[:user] # => {:name => “ow3ned”, :admin => true}
 
 So if you create a new user using mass-assignment, it may be too easy to become an administrator.
 
-Note that this vulnerability is not restricted to database columns.  Any setter method, unless explicitly protected, is accessible via the <tt>attributes=</tt> method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example:
+Note that this vulnerability is not restricted to database columns.  Any setter method, unless explicitly protected, is accessible via the <tt>attributes=</tt> method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3+. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example:
 
 <ruby>
   class Person < ActiveRecord::Base
@@ -410,7 +410,7 @@ To avoid this, Rails provides two class methods in your Active Record class to c
 attr_protected :admin
 </ruby>
 
-+attr_protected+ also optionally takes a scope option using :as which allows you to define multiple mass-assignment groupings. If no scope is defined then attributes will be added to the default group.
++attr_protected+ also optionally takes a role option using :as which allows you to define multiple mass-assignment groupings. If no role is defined then attributes will be added to the :default role.
 
 <ruby>
 attr_protected :last_login, :as => :admin
@@ -433,7 +433,7 @@ params[:user] # => {:name => "ow3ned", :admin => true}
 @user.admin # => true
 </ruby>
 
-When assigning attributes in Active Record using +attributes=+, or +update_attributes+ the :default scope will be used. To assign attributes using different scopes you should use +assign_attributes+ which accepts an optional :as options parameter. If no :as option is provided then the :default scope will be used. You can also bypass mass-assignment security by using the +:without_protection+ option. Here is an example:
+When assigning attributes in Active Record using +attributes=+ the :default role will be used. To assign attributes using different roles you should use +assign_attributes+ which accepts an optional :as options parameter. If no :as option is provided then the :default role will be used. You can also bypass mass-assignment security by using the +:without_protection+ option. Here is an example:
 
 <ruby>
 @user = User.new
@@ -451,7 +451,7 @@ When assigning attributes in Active Record using +attributes=+, or +update_attri
 @user.is_admin # => true
 </ruby>
 
-In a similar way, +new+, +create+ and <tt>create!</tt> methods respect mass-assignment security and accepts either +:as+ or +:without_protection+ options. For example:
+In a similar way, +new+, +create+, <tt>create!</tt>, +update_attributes+, and +update_attributes!+ methods all respect mass-assignment security and accept either +:as+ or +:without_protection+ options. For example:
 
 <ruby>
 @user = User.new({ :name => 'Sebastian', :is_admin => true }, :as => :admin)