effective_roles 0.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9df4ba4a70253bd8bef9933d1cdb8baf69ac87d8
+  data.tar.gz: f0dca667a92690beaaf43b2e1be460ce787374d4
+SHA512:
+  metadata.gz: 19340a70b419ce8f90babe9577b8dcb86b2402c34c9590245999a9d2dd00aec25c7fba4c9cfa30cd6334ec3da04c399af0ff53e7e1e2d64de0d82e5dc52823f3
+  data.tar.gz: 37f593b0331836a0119b878c8494737d46bf002531f5fd6eaf6eb4d0b56345685dfe91039e5577db88651cff54cdd011c4f319b1c7442cb886c61c23bb5d8236

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2013 Code and Effect Inc.
+Copyright 2014 Code and Effect Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,18 +1,16 @@
 # Effective Roles
 
+Assign multiple roles to any User or other ActiveRecord object. Select only the appropriate objects based on intelligent, chainable ActiveRecord::Relation finder methods.
+
 Implements multi-role authorization based on an integer roles_mask field
 
 Includes a mixin for adding authentication for any model.
 
-SQL Finders for returning a Relation with all permitted records.
-
-Handy formtastic helper for assigning roles.
-
-Intended for use with the other effective_* gems
+SQL Finders for returning an ActiveRecord::Relation with all permitted records.
 
-Designed to work on its own, or with simple pass through to CanCan
+Handy formtastic and simple_form helpers for assigning roles.
 
-Rails >= 3.2.x, Ruby >= 1.9.x.  Has not been tested/developed for Rails4.
+Rails 3.2.x and Rails 4
 
 
 ## Getting Started
@@ -47,7 +45,7 @@ class Post
 end
 ```
 
-Then create a migration to add the :roles_Mask column to the model.
+Then create a migration to add the :roles_mask column to the model.
 
 ```console
 rails generate migration add_roles_to_post roles_mask:integer
@@ -63,11 +61,22 @@ class AddRolesToPost < ActiveRecord::Migration
 end
 ```
 
-## Behavior
+## Strong Parameters
+
+Make your controller aware of the acts_as_role_restricted passed parameters:
+
+```ruby
+def permitted_params
+  params.require(:base_object).permit(:roles => [])
+end
+```
+
+
+## Usage
 
 ### Defining Roles
 
-All roles are defined in the config/effective_roles.rb initializer.
+All roles are defined in the config/effective_roles.rb initializer.  The roles are defined once and may be applied to any acts_as_role_restricted model in the application.
 
 ### Model
 
@@ -91,12 +100,51 @@ post.roles
 => [:admin, :superadmin]
 ```
 
+Compare against another acts_as_role_restricted object:
+
+```ruby
+user = User.new()
+user.roles = []
+
+post = Post.new()
+post.roles = [:admin]
+
+user.roles_match_with?(post)
+=> false  # User has no roles, but Post requires :admin
+
+post.roles_match_with?(user)
+=> true   # Post has the role of :admin, but User requires no roles
+```
+
+```ruby
+user.roles = [:admin]
+post.roles = [:superadmin]
+
+user.roles_match_with?(post)
+=> false  # User does not have the superadmin role
+
+post.roles_match_with?(user)
+=> false  # Post does not have the admin role
+```
+
+```ruby
+user.roles = [:superadmin, :admin]
+post.roles = [:admin]
+
+user.roles_match_with?(post)
+=> true  # User has :admin and so does Post
+
+post.roles_match_with?(user)
+=> true  # Post has :admin and so does User
+```
+
 ### Finder Methods
 
-Find all objects that have been assigned a specific role (or roles).  Will not return posts that have no assigned roles (roles_mask = 0)
+Find all objects that have been assigned a specific role (or roles).  Will not return posts that have no assigned roles (roles_mask = 0 or NULL)
 
 ```ruby
 Post.with_role(:admin, :superadmin)   # Can pass as an array if you want
+Post.with_role(current_user.roles)
 ```
 
 Find all objects that are appropriate for a specific role.  Will return posts that have no assigned roles
@@ -108,17 +156,146 @@ Post.for_role(current_user.roles)
 
 These are both ActiveRecord::Relations, so you can chain them with other methods like normal.
 
+## Assignable Roles
+
+Specifies which roles can be assigned to a resource by a specific user.
+
+See the initializers/effective_roles.rb for more information.
+
+```ruby
+  config.assignable_roles = {
+    :superadmin => [:superadmin, :admin, :member], # Superadmins may assign any resource any role
+    :admin => [:admin, :member],                   # Admins may only assign the :admin or :member role
+    :member => []                                  # Members may not assign any roles
+  }
+```
+
+When used in a Form Helper (see below), only the appropriate roles will be displayed.
+
+However, this restriction is not enforced on the controller level, so someone could inspect & re-write the form parameters and still assign a role that they are not allowed to.
+
+To prevent this, add something like the following code to your controller:
+
+```ruby
+before_filter :only => [:create, :update] do
+  if params[:user] && params[:user][:roles]
+    params[:user][:roles] = params[:user][:roles] & EffectiveRoles.assignable_roles_for(current_user, User.new()).map(&:to_s)
+  end
+end
+```
+
+
+## Form Helper
+
+If you pass current_user (or any acts_as_role_restricted object) into these helpers, only the assignable_roles will be displayed.
+
+### Formtastic
+
+```ruby
+semantic_form_for @user do |f|
+  = effective_roles_fields(f)
+```
+
+or
+
+```ruby
+semantic_form_for @user do |f|
+  = effective_roles_fields(f, current_user)
+```
+
+### simple_form
+
+```ruby
+simple_form_for @user do |f|
+  = f.input :roles, :collection => EffectiveRoles.roles_collection(f.object), :as => :check_boxes
+```
+
+or
+
+```ruby
+simple_form_for @user do |f|
+  = f.input :roles, :collection => EffectiveRoles.roles_collection(f.object, current_user), :as => :check_boxes
+```
+
+## Bitmask Implementation
+
+The underlying role information for any acts_as_role_restricted ActiveRecord object is stored in that object's roles_mask field.
+
+roles_mask is an integer, in which each power of 2 represents the presence or absense of a role.
+
+If we have the following roles defined:
+
+```ruby
+EffectiveRoles.setup do |config|
+  config.roles = [:superadmin, :admin, :betauser, :member]
+end
+```
+
+Then the following will hold true:
+
+```ruby
+user = User.new()
+
+user.roles
+=> []
+
+user.roles_mask
+=> 0
+
+user.roles = [:superadmin]
+user.roles_mask
+=> 1
+
+user.roles = [:admin]
+user.roles_mask
+=> 2
+
+user.roles = [:betauser]
+user.roles_mask
+=> 4
+
+user.roles = [:member]
+user.roles_mask
+=> 8
+```
+
+As well:
+
+```ruby
+user.roles = [:superadmin, :admin]
+user.roles_mask
+=> 3
+
+user.roles = [:superadmin, :betauser]
+user.roles_mask
+=> 5
+
+user.roles = [:admin, :member]
+user.roles_mask
+=> 10
+
+user.roles = [:superadmin, :admin, :betauser, :member]
+user.roles_mask
+=> 15
+```
+
+Keep in mind, when using this gem you should never be working directly with the roles_mask field.
+
+All roles are get/set through the roles and roles= methods.
+
+
 ## License
 
-MIT License.  Copyright Code and Effect Inc. http://www.codeandeffect.com
+MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+
+Code and Effect is the product arm of [AgileStyle](http://www.agilestyle.com/), an Edmonton-based shop that specializes in building custom web applications with Ruby on Rails.
 
-You are not granted rights or licenses to the trademarks of Code and Effect
 
 ## Credits
 
 This model implements the https://github.com/ryanb/cancan/wiki/Role-Based-Authorization multi role based authorization based on the roles_mask field
 
-### Testing
+## Testing
 
 The test suite for this gem is unfortunately not yet complete.
 
@@ -127,3 +304,15 @@ Run tests by:
 ```ruby
 rake spec
 ```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request
+
+

data/app/helpers/effective_roles_helper.rb

@@ -1,12 +1,12 @@
 module EffectiveRolesHelper
   # For use in formtastic forms
-  def effective_roles_fields(form, options = {})
-    if EffectiveRoles.role_descriptions.kind_of?(Hash)
-      role_descriptions = EffectiveRoles.role_descriptions[form.object.class.name]
-    end
-    role_descriptions ||= (EffectiveRoles.role_descriptions || [])
+  def effective_roles_fields(form, user = nil, options = {})
+    raise ArgumentError.new('EffectiveRoles config.role_descriptions must be a Hash.  The Array syntax is deprecated.') unless EffectiveRoles.role_descriptions.kind_of?(Hash)
 
-    opts = {:f => form, :role_descriptions => role_descriptions}.merge(options)
+    roles = EffectiveRoles.assignable_roles_for(user, form.object)
+    descriptions = EffectiveRoles.role_descriptions[form.object.class.name] || EffectiveRoles.role_descriptions || {}
+
+    opts = {:f => form, :roles => roles, :descriptions => descriptions}.merge(options)
 
     render :partial => 'effective/roles/roles_fields', :locals => opts
   end

data/app/models/concerns/acts_as_role_restricted.rb

@@ -45,9 +45,20 @@ module ActsAsRoleRestricted
 
     def with_role_sql(*roles)
       roles = roles.flatten.compact
+      roles = roles.first.try(:roles) if roles.length == 1 and roles.first.respond_to?(:roles)
+
       roles = (roles.map { |role| role.to_sym } & EffectiveRoles.roles)
       roles.map { |role| "(#{self.table_name}.roles_mask & %d > 0)" % 2**EffectiveRoles.roles.index(role) }.join(' OR ')
     end
+
+    def without_role(*roles)
+      roles = roles.flatten.compact
+      roles = roles.first.try(:roles) if roles.length == 1 and roles.first.respond_to?(:roles)
+
+      roles = (roles.map { |role| role.to_sym } & EffectiveRoles.roles)
+
+      where(roles.map { |role| "NOT(#{self.table_name}.roles_mask & %d > 0)" % 2**EffectiveRoles.roles.index(role) }.join(' OR '))
+    end
   end
 
   def roles=(roles)
@@ -64,11 +75,7 @@ module ActsAsRoleRestricted
   end
 
   def roles_match_with?(obj)
-    if is_role_restricted? == false
-      true
-    elsif obj.respond_to?(:is_role_restricted?) == false
-      false
-    elsif obj.is_role_restricted? == false
+    if !obj.respond_to?(:is_role_restricted?) || !obj.is_role_restricted?
       true
     else
       (roles & obj.roles).any?
@@ -76,7 +83,7 @@ module ActsAsRoleRestricted
   end
 
   def is_role_restricted?
-    roles_mask > 0
+    (roles_mask || 0) > 0
   end
 end
 

data/app/views/effective/roles/_roles_fields.html.haml

@@ -10,8 +10,8 @@
           %label Roles
         %input{:type => :hidden, :id => "#{obj}_roles_none", :name => "#{obj}[roles][]"}
         %ol.choices-group
-          - EffectiveRoles.roles.each_with_index do |role, x|
+          - roles.each do |role|
             %li.choice
               %label{:for => "#{obj}_roles_#{role}"}
                 %input{:type => :checkbox, :id => "#{obj}_roles_#{role}", :name => "#{obj}[roles][]", :value => role.to_s, :checked => ("checked" if f.object.roles.include?(role))}= role
-              %p.inline-hints{:style => "margin: 2px 0 16px 0;"}= role_descriptions[x]
+              %p.inline-hints{:style => "margin: 2px 0 16px 0;"}= descriptions[role]

data/lib/effective_roles.rb

@@ -3,10 +3,34 @@ require "effective_roles/version"
 
 module EffectiveRoles
   mattr_accessor :roles
+  mattr_accessor :assignable_roles
   mattr_accessor :role_descriptions
 
   def self.setup
     yield self
   end
 
+  def self.roles_collection(obj = nil, user = nil)
+    raise ArgumentError.new('EffectiveRoles config.role_descriptions must be a Hash.  The Array syntax is deprecated.') unless EffectiveRoles.role_descriptions.kind_of?(Hash)
+
+    descriptions = role_descriptions[obj.try(:class).to_s] || role_descriptions || {}
+
+    assignable_roles_for(user, obj).map do |role|
+      ["#{role}<br>#{descriptions[role]}".html_safe, role]
+    end
+  end
+
+  def self.assignable_roles_for(user, obj = nil)
+    return roles unless user.respond_to?(:is_role_restricted?) # All roles, if the user (or object) is not role_resticted
+
+    assignable = assignable_roles[obj.try(:class).to_s] || assignable_roles || {}
+
+    if assignable.present?
+      user.roles.map { |role| assignable[role] }.flatten.compact.uniq
+    else
+      roles
+    end
+  end
+
+
 end

data/lib/effective_roles/version.rb

@@ -1,3 +1,3 @@
 module EffectiveRoles
-  VERSION = "0.1"
+  VERSION = '1.0.0'.freeze
 end

data/lib/generators/templates/effective_roles.rb

@@ -1,30 +1,58 @@
 EffectiveRoles.setup do |config|
   config.roles = [:superadmin, :admin, :member] # Only add to the end of this array.  Never prepend roles.
 
-  # config.role_descriptions may be an Array or a Hash
-  # These role descriptions are just text displayed by the effective_roles_fields() helper
-
-  # Use a Hash if you want different labels depending on the resource being editted
+  # config.assignable_roles
+  # =======================
+  # When current_user is passed into a form helper function (see README.md)
+  # this setting determines which roles that current_user may assign
+  #
+  # Use this Hash syntax if you want different permissions depending on the resource being editted
+  #
+  # config.assignable_roles = {
+  #   'User' => {
+  #     :superadmin => [:superadmin, :admin, :member],  # Superadmins may assign Users any role
+  #     :admin => [:admin, :member],                    # Admins may only assign a User the :admin or :member role
+  #     :member => []                                   # Members may not assign any roles
+  #   },
+  #   'Page' => {
+  #     :superadmin => [:superadmin, :admin, :member],  # Superadmins may create Pages for any role
+  #     :admin => [:admin, :member],                    # Admins may create Pages for admin and members
+  #     :member => [:member]                            # Members may create Pages for members
+  #   }
   #
+  # Or just keep it simple, and use this Hash syntax of permissions for every resource
+  #
+  config.assignable_roles = {
+    :superadmin => [:superadmin, :admin, :member], # Superadmins may assign any resource any role
+    :admin => [:admin, :member],                   # Admins may only assign the :admin or :member role
+    :member => []                                  # Members may not assign any roles
+  }
 
+  # config.role_descriptions
+  # ========================
+  # This setting configures the text that is displayed by form helpers (see README.md)
+  #
+  # Use this Hash syntax if you want different labels depending on the resource being editted
+  #
   # config.role_descriptions = {
-  #   'User' => [
-  #     "full access to everything. Can manage users and all website content.",
-  #     "full access to website content.  Cannot manage users.",
-  #     "cannot access admin area.  Can see all content in members-only sections of the website."
-  #   ],
-  #   'Effective::Page' => [
-  #     "allow superadmins to see this page",
-  #     "allow admins to see this page",
-  #     "allow members to see this page"
-  #   ]
+  #   'User' => {
+  #     :superadmin => 'full access to everything. Can manage users and all website content.',
+  #     :admin => 'full access to website content.  Cannot manage users.',
+  #     :member => 'cannot access admin area.  Can see all content in members-only sections of the website.''
+  #   },
+  #   'Effective::Page' => {
+  #     :superadmin => 'allow superadmins to see this page',
+  #     :admin => 'allow admins to see this page',
+  #     :member => 'allow members to see this page'
+  #   }
   # }
-
-  # Or just keep it simple, and use the same Array of labels for everything
   #
-  config.role_descriptions = [
-    "full access to everything. Can manage users and all website content.",
-    "full access to website content.  Cannot manage users.",
-    "cannot access admin area.  Can see all content in members-only sections of the website."
-  ]
+  # Or just keep it simple, and use this Hash syntax of permissions for every resource
+  #
+  config.role_descriptions = {
+    :superadmin => 'full access to everything. Can manage users and all website content.',
+    :admin => 'full access to website content.  Cannot manage users.',
+    :member => 'cannot access admin area.  Can see all content in members-only sections of the website.'
+  }
+
 end

metadata

@@ -1,141 +1,59 @@
 --- !ruby/object:Gem::Specification
 name: effective_roles
 version: !ruby/object:Gem::Version
-  version: '0.1'
-  prerelease: 
+  version: 1.0.0
 platform: ruby
 authors:
 - Code and Effect
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-24 00:00:00.000000000 Z
+date: 2014-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: factory_girl_rails
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec-rails
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: shoulda-matchers
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: psych
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Implements multi-role authorization based on an integer roles_mask field.
-  Includes a mixin for adding authentication for any model. SQL Finders for returning
-  a Relation with all permitted records. Handy formtastic helper for assigning roles.
-  Intended for use with the other effective_* gems Designed to work on its own, or
-  with simple pass through to CanCan
+        version: 3.2.0
+description: Assign multiple roles to any User or other ActiveRecord object. Select
+  only the appropriate objects based on intelligent, chainable ActiveRecord::Relation
+  finder methods.
 email:
 - info@codeandeffect.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
+- README.md
+- Rakefile
 - app/helpers/effective_roles_helper.rb
 - app/models/concerns/acts_as_role_restricted.rb
 - app/views/effective/roles/_roles_fields.html.haml
+- lib/effective_roles.rb
 - lib/effective_roles/engine.rb
 - lib/effective_roles/version.rb
-- lib/effective_roles.rb
 - lib/generators/effective_roles/install_generator.rb
-- lib/generators/templates/effective_roles.rb
 - lib/generators/templates/README
+- lib/generators/templates/effective_roles.rb
 - lib/tasks/effective_roles_tasks.rake
-- MIT-LICENSE
-- Rakefile
-- README.md
+- spec/dummy/README.rdoc
+- spec/dummy/Rakefile
 - spec/dummy/app/assets/javascripts/application.js
 - spec/dummy/app/assets/stylesheets/application.css
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/app/helpers/application_helper.rb
 - spec/dummy/app/views/layouts/application.html.erb
+- spec/dummy/config.ru
 - spec/dummy/config/application.rb
 - spec/dummy/config/boot.rb
 - spec/dummy/config/database.yml
@@ -151,7 +69,6 @@ files:
 - spec/dummy/config/initializers/wrap_parameters.rb
 - spec/dummy/config/locales/en.yml
 - spec/dummy/config/routes.rb
-- spec/dummy/config.ru
 - spec/dummy/db/development.sqlite3
 - spec/dummy/db/schema.rb
 - spec/dummy/db/test.sqlite3
@@ -161,36 +78,36 @@ files:
 - spec/dummy/public/422.html
 - spec/dummy/public/500.html
 - spec/dummy/public/favicon.ico
-- spec/dummy/Rakefile
-- spec/dummy/README.rdoc
 - spec/dummy/script/rails
 - spec/effective_roles_spec.rb
 - spec/spec_helper.rb
 - spec/support/factories.rb
 homepage: https://github.com/code-and-effect/effective_roles
-licenses: []
+licenses:
+- MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.4.3
 signing_key: 
-specification_version: 3
-summary: Implements multi-role authorization based on an integer roles_mask field
+specification_version: 4
+summary: Assign multiple roles to any User or other ActiveRecord object. Select only
+  the appropriate objects based on intelligent, chainable ActiveRecord::Relation finder
+  methods.
 test_files:
 - spec/dummy/app/assets/javascripts/application.js
 - spec/dummy/app/assets/stylesheets/application.css
@@ -228,4 +145,3 @@ test_files:
 - spec/effective_roles_spec.rb
 - spec/spec_helper.rb
 - spec/support/factories.rb
-has_rdoc: