action_permission 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2d598921d73d8ca53edf5154616e27108e9b9ef7
+  data.tar.gz: baaba6a7c5792c1f22433c768ab391cdec09cc0a
+SHA512:
+  metadata.gz: 9de568d75f1b7871776526e385f35b5fa06e613cc78f745fcf7682b21f63e8ecab21639795572293c9a45f0a65429f1ebfb237da25231e55f6e9c2bdef9d9a89
+  data.tar.gz: 2cc23db2ada4942dde384df738c93168c69c4255b12e8a174dc4434bbef6048f59d3dbac791606a303387077402716718fb8ea43168faafe0bc039e9aecd1c99

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in action_permission.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Matt Duffy
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+__NOTICE: The gem as it stands is not production-ready.__
+_See [issues](https://github.com/mttdffy/action_permission/issues) for details_
+
+----
+
+# ActionPermission
+
+A permission structure for defining both action-based and attribute-based permissions for rails 3+ applications. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'action_permission'
+```
+
+And then execute:
+
+```sh
+$ bundle
+$ rails generate action_permission:install
+```
+
+## Usage
+
+ActionPermission assumes you have the concept of user roles. This can be any field of any name. It's core action is to load permissions for the controller handling the request, determine the user's access level, and call a method on the permission object that corresponds to that level. A permission file might look like this:
+
+```ruby
+class BookPermission < ApplicationPermission
+
+  def params
+    [:name, :author, :isbn, :page_count, :price]
+  end
+
+  def guest
+    allow [:index, :show]
+  end
+
+  def user
+    allow [:index, :show, :new]
+    allow [:create, :edit, :update, :destroy] do |user|
+      @membership.id == user.id
+    end
+    allow_params except: [:price]
+  end
+
+  def admin
+    allow_rest_actions
+    allow_params
+  end
+
+end
+```
+
+- the `params` method can be used to define attributes allowed to be modified by that user level in addition to their allowed actions.
+- the `@membership` attribute is set on initialization based on the method handed to `authorize_with` in your `ApplicationController` (See 'Setup' below)
+
+
+## Setup
+
+```sh
+$ rails generate action_permission:install
+```
+
+This generator will creating the `app/permissions` directory along with a `application_perimission.rb` file.
+
+Permissions should be placed in the `app/permissions` directory. Each permission will typically extend from `ApplicationPermission`, allowing you to set default permissions for each role. 
+
+Additionally, the install generator will add some boilerplate code into your `ApplicationController` for setting up your application to work properly with ActionPermission. 
+
+```ruby
+#app/controllers/application_controller.rb
+
+authorize_with :current_user
+before_action :check_permission
+
+def current_user
+  @current_user ||= session[:user_id] ? User.find(session[:user_id]) : User.new
+end
+
+def check_permission
+  unless authorized?
+    #do something when user does not have permission to access page
+    # Flash[:warn] = "You do not have permission to access this page."
+    # redirect_to root_url
+  end
+end
+
+```
+
+This is a basic implementation that you can change and modify to work with your application's user role structure.
+
+Ultimately, ActionPermission looks to receive a string representing the name of the role/level of current user. It requires you to define a method on your `ApplicationController` to call when loading permissions. This method should return an object that can repond to a `#identify` method. `identify` method should return a string value of the current user's role
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+
+  # assume User#role exists as a string representation
+  # of what role that user is
+
+  def identify
+    role || "guest"
+  end
+end
+
+```
+
+Alternatively, you can overwrite `ActionPermission::Base#load` in the `ApplicationPermission` class to define your own way of determining a method to call.
+
+```ruby
+class ApplicationPermission < ActionPermission::Base
+  
+  def load(user)
+    @membership = user
+    send @membership.role
+  end
+
+end
+
+```
+
+Once you have it setup, your controller has access to an `authorized?` method which will tell you if the current user has permission to access the current action
+
+```ruby
+# app/controllers/application_controller.rb
+ApplicationController < ActionController::Base
+  
+  before_action :check_permissions
+
+  def check_permissions
+    unless authorized?
+      flash[:warn] = "You do not have permission to access this page"
+      rediect_to root_url
+    end
+  end 
+end
+```
+
+## Generators
+
+    rails g action_permission:install
+    
+This will add the base application_permission.rb file as well as add some boilerplate code to the application controller
+
+    rails g action_permission:permission CONTROLLER [attribute, attribute, ...]
+    
+    rails g action_permission:permission users username name email role password_digest
+    
+This will generate a permission file for the supplied controller. YOu can pass in attributes to auto populate the params method for that permission object. In the future this will be added onto the scaffolding generator so you don't have to run this seperately
+
+## Contributors
+
+- [Matt Duffy](https://github.com/mttdffy)
+- [Brian McElaney](https://github.com/mcelaney)
+- [Mark Platt](https://github.com/mrkplt)
+
+## 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. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/action_permission.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'action_permission/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "action_permission"
+  spec.version       = ActionPermission::VERSION
+  spec.authors       = ["Matt Duffy", "Brian McElaney", "Mark Platt"]
+  spec.email         = ["matt@mttdffy.com", "", ""]
+  spec.summary       = "Controller-based action and attribute permissions"
+  spec.homepage      = "https://github.com/mttdffy/action_permission"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", "~> 4"
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2"
+  spec.add_development_dependency "activerecord-nulldb-adapter"
+end

data/lib/action_permission/base.rb

@@ -0,0 +1,71 @@
+module ActionPermission
+
+  class Base
+
+    class << self
+
+      def match_with source,to
+        Array(to).each do |role|
+          alias_method role, source
+        end
+      end
+
+    end
+
+    attr_accessor :membership
+    attr_reader :allowed_params, :allowed_actions
+
+    def initialize(membership)
+      load membership
+    end
+
+    def load(membership)
+      @membership = membership
+      role = @membership.identify
+      if role && respond_to?(role)
+        send(role)
+      end
+    end
+
+    def allow?(action, resource = nil)
+      allowed = @allowed_actions[action.to_s] if @allowed_actions
+      allowed && (allowed == true || resource && allowed.call(resource))
+    end
+
+    def allow(actions, &block)
+      @allowed_actions ||= {}
+      Array(actions).each do |action|
+        @allowed_actions[action.to_s] = block || true
+      end
+    end
+
+    def allow_rest_actions(&block)
+      allow [:index, :new, :create, :show, :edit, :update, :destroy], &block
+    end
+
+    def params
+      []
+    end
+
+    def allow_params options=nil
+      @allowed_params ||= []
+
+      if options
+        @allowed_params = allow_params_with_options options
+      else
+        @allowed_params = Array(params)
+      end
+    end
+
+    private
+
+    def allow_params_with_options options
+      alt_params = params
+      alt_params = Array(options[:only]) if options[:only]
+      Array(options[:except]).each {|e| alt_params.delete e } if options[:except]
+      alt_params
+    end
+
+  end
+
+end

data/lib/action_permission/controller.rb

@@ -0,0 +1,56 @@
+require 'active_support/core_ext/object'
+require 'active_support/dependencies'
+require 'abstract_controller/helpers'
+
+module ActionPermission
+
+  module Controller
+    extend ActiveSupport::Concern
+    include AbstractController::Helpers
+
+    included do
+      delegate :allow?, to: :current_permission
+      delegate :allow_param?, to: :current_permission
+      delegate :allowed_params_for, to: :current_permission
+      helper_method :allow?
+      helper_method :allow_param?
+      helper_method :current_permission
+    end
+
+    module ClassMethods
+
+      def authorize_with authorizer
+        helper_method authorizer
+        @@permission_authorizer = authorizer
+      end
+
+      def permission_authorizer
+        @@permission_authorizer
+      end
+
+    end
+
+    def current_resource
+      nil
+    end
+
+    def current_permission
+      @current_permission ||= ActionPermission::Dispatch.new(permission_authorizer)
+    end
+
+    def authorized?
+      current_permission.allow?(params[:controller], params[:action], current_resource)
+    end
+
+    private
+
+    def permission_authorizer
+      send self.class.permission_authorizer
+    end
+
+
+  end
+
+end
+
+ActionController::Base.send :include, ActionPermission::Controller if ENV['RAILS']

data/lib/action_permission/dispatch.rb

@@ -0,0 +1,96 @@
+require 'active_support/hash_with_indifferent_access'
+require 'active_support/inflector'
+
+module ActionPermission
+
+  class Dispatch
+    attr_accessor :membership, :permissions
+
+    def initialize(membership)
+      @membership = membership
+      @permissions = HashWithIndifferentAccess.new
+    end
+
+    def allow?(controller, action, resource = nil)
+      current_permission = load_permission controller
+
+      if resource
+        current_permission.allow?(action, resource)
+      else !resource
+        current_permission.allow?(action)
+      end
+    end
+
+    # 'book/review', params #=> controller == 'books/reviews'
+    # 'book/review', params, 'reviews' #=> controller == 'reviews'
+    def allowed_params_for(resource, params, controller=nil)
+      controller  = set_controller(resource, controller)
+      resource    = set_resource(resource)
+
+      current_permission = load_permission(controller)
+
+      if current_permission && current_permission.allowed_params
+        params.require(resource).permit *current_permission.allowed_params
+      end
+    end
+
+    def allow_param?(resource, attribute)
+      current_permission = load_permission resource.to_s.pluralize
+
+      if current_permission && current_permission.allowed_params
+        current_permission.allowed_params.include? attribute
+      else
+        false
+      end
+    end
+
+    private
+
+      def set_controller(resource, controller)
+        if controller
+          case controller
+          when String, Symbol
+            controller.to_s.pluralize
+          else
+            (controller.is_a?(Class) ? controller : controller.class).
+              name.underscore.gsub('_controller', '')
+          end
+        else
+          case resource
+          when String, Symbol
+            resource.to_s
+          else
+            (resource.is_a?(Class) ? resource : resource.class).
+              name.underscore
+          end.
+          split('/').map(&:pluralize).join('/')
+        end
+      end
+
+      def set_resource(resource)
+        case resource
+        when String, Symbol
+          resource.to_s.parameterize("_")
+        else
+          (resource.is_a?(Class) ? resource : resource.class).model_name.param_key
+        end
+      end
+
+      def load_permission(controller)
+        klass = get_class_name(controller)
+        # grab the permissions for this controller from cache or register it if missing
+        @permissions[controller] ||= register_permission(controller, klass)
+      end
+
+      def get_class_name(controller)
+        controller = controller.to_s
+        return (controller.pluralize + "_permissions").classify.constantize
+      end
+
+      def register_permission(controller, klass)
+        @permissions[controller] = klass.new(@membership)
+      end
+
+  end
+
+end

data/lib/action_permission/railtie.rb

@@ -0,0 +1,21 @@
+require 'rails/railtie'
+
+module ActionPermission
+  class Railtie < ::Rails::Railtie
+    if config.respond_to?(:app_generators)
+      config.app_generators.scaffold_controller = :action_permission_controller
+    else
+      config.generators.scaffold_controller = :action_permission_controller
+    end
+
+    # initializer 'activeservice.autoload', :before => :set_autoload_paths do |app|
+    #   app.config.autoload_paths << (app.config.root + '/app/permissions')
+    # end
+
+    # initializer "strong_parameters.config", :before => "action_controller.set_configs" do |app|
+    #   ActionController::Parameters.action_on_unpermitted_parameters = app.config.action_controller.delete(:action_on_unpermitted_parameters) do
+    #     (Rails.env.test? || Rails.env.development?) ? :log : false
+    #   end
+    # end
+  end
+end

data/lib/action_permission/version.rb

@@ -0,0 +1,3 @@
+module ActionPermission
+  VERSION = "1.0.0"
+end

data/lib/action_permission.rb

@@ -0,0 +1,4 @@
+require "action_permission/version"
+require "action_permission/dispatch"
+require "action_permission/base"
+require "action_permission/controller"

data/lib/generators/action_permission/install/USAGE

@@ -0,0 +1,3 @@
+Description:
+    Creates the app/permissions directory and stubs out application_permission.rb,
+    a base permission file used to extend controller-specific permissions for

data/lib/generators/action_permission/install/install_generator.rb

@@ -0,0 +1,37 @@
+require 'rails/generators/base'
+
+module ActionPermission
+  module Generators
+
+    class InstallGenerator < Rails::Generators::Base
+      p "creating permissions directory"
+      source_root File.expand_path("../templates", __FILE__)
+
+      def copy_application_file
+        copy_file "application.rb", "app/permissions/application_permission.rb"
+      end
+      
+      def add_controller_setup
+        line = /class ApplicationController \< ActionController\:\:Base\n/
+        inject_into_file 'app/controllers/application_controller.rb', after: line do <<-'RUBY'
+  authorize_with :current_user
+  before_action :check_permission
+  
+  def current_user
+    @current_user ||= session[:user_id] ? User.find(session[:user_id]) : User.new
+  end
+  
+  def check_permission
+    unless authorized?
+      #do something when user does not have permission to access page
+      # Flash[:warn] = "You do not have permission to access this page."
+      # redirect_to root_url
+    end
+  end
+        RUBY
+        end
+      end
+    end
+
+  end
+end

data/lib/generators/action_permission/install/templates/application.rb

@@ -0,0 +1,32 @@
+class ApplicationPermission < ActionPermission::Base
+
+  # Your base permission file
+  # You can use this file to set default permissions
+  # or overwrite the #load method to manually determine which
+  # methods of a permission file are called for each user role
+
+  # example overwrite method
+  # def load(user)
+  #   @membership = user
+  #   send (@membership.role) || "guest"
+  # end
+
+  # default permissions
+
+  # def guest
+  #   allow [:show]
+  # end
+
+  # def user
+  #   allow_rest_actions do |user|
+  #     @membership.id == user.id
+  #   end
+  #   allow_params
+  # end
+
+  # def admin
+  #   allow_rest_actions
+  #   allow_params
+  # end
+
+end

data/lib/generators/action_permission/permission/USAGE

@@ -0,0 +1,2 @@
+Description:
+    Creates a permission file with supplied file name

data/lib/generators/action_permission/permission/permission_generator.rb

@@ -0,0 +1,14 @@
+require 'rails/generators/named_base'
+
+module ActionPermission
+  module Generators
+    class PermissionGenerator < Rails::Generators::NamedBase
+      argument :attributes, type: :array, default: [], banner: "field field"
+      source_root File.expand_path("../templates", __FILE__)
+
+      def create_permission_file
+        template "permission.rb", "app/permissions/#{file_name}_permission.rb"
+      end
+    end
+  end
+end

data/lib/generators/action_permission/permission/templates/permission.rb

@@ -0,0 +1,45 @@
+<% module_namespacing do -%>
+class <%= class_name %>Permission < ApplicationPermission
+
+  # defines parameters for requests coming to associated object/controlelr
+  # typically defines all attributes and uses except option to exclude
+  # params on a per-role basis
+  def params
+    [<%= attributes.map {|a| ":#{a.name}" }.sort.join(', ') %>]
+  end
+
+  # define methods for each of your user roles here
+
+  # allow [:actions] 
+  # defines routes allowed for that role
+  # an optional block can be passed to allow to check 
+  # things like ownership.
+
+  # allow_params
+  # options: [:except, :only]
+  # define params user role can change
+  # no options gives access to all of #params
+  # except excludes any listed
+  # only overwrites params array
+
+  # @membership is available as the object returned from
+  # method passed to ActionPermission::Controller#authorize_with
+  
+  def guest
+    allow [:show]
+  end
+
+  def user
+    allow_rest_actions do |user|
+      @membership.id == user.id
+    end
+    allow_params except: [:id]
+  end
+
+  def admin
+    allow_rest_actions
+    allow_params
+  end
+
+end
+<% end -%>

data/lib/generators/rails/USAGE

@@ -0,0 +1,16 @@
+Description:
+    Stubs out a scaffolded controller and its views. Different from rails
+    scaffold_controller, it uses strong_parameters to whitelist permissible
+    attributes in a private method.
+    Pass the model name, either CamelCased or under_scored. The controller
+    name is retrieved as a pluralized version of the model name.
+
+    With ActionPermission, it replaces the default strong_parameters
+    call with a call to allowed_params_for that loads the permission file
+    to determined whitelisted parameters
+
+    To create a controller within a module, specify the model name as a
+    path like 'parent_module/controller_name'.
+
+    This generates a controller class in app/controllers and invokes helper,
+    template engine and test framework generators.

data/lib/generators/rails/action_permission_controller_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/version'
+require 'rails/generators/rails/scaffold_controller/scaffold_controller_generator'
+
+module Rails
+  module Generators
+    class ActionPermissionControllerGenerator < ScaffoldControllerGenerator
+      argument :attributes, :type => :array, :default => [], :banner => "field:type field:type"
+      source_root File.expand_path("../templates", __FILE__)
+
+      if ::Rails::VERSION::STRING < '3.1'
+        def module_namespacing
+          yield if block_given?
+        end
+      end
+    end
+  end
+end