permitter 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c1982649b776d20be5bb9f18c484aba7fa562a8c
+  data.tar.gz: c0ec0c06e6b7bdb1acc07d149b902dde3d980090
+SHA512:
+  metadata.gz: 21c03aa7c540916d8fda1ce1f8a2004202071f35539cebf41d765c4d7fa7cf4eae3d3fee090ecc8ace59ff548316a0f75e24f49fd5f0fd148573f5631e15944d
+  data.tar.gz: 0f9f654b5c0baa97179cfb2c6e97de6972b942ef0d412b7ec74e0207fb085c169035b824e943cc395e94d7db80c8ba39ba7c8cc8b1dd06ed1e7e97180492438e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Matthew Erhard
+
+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.rdoc

@@ -0,0 +1,302 @@
+= Permitter
+{<img src="https://travis-ci.org/merhard/permitter.png?branch=master" alt="Build Status" />}[https://travis-ci.org/merhard/permitter]  {<img src="https://codeclimate.com/github/merhard/permitter.png" />}[https://codeclimate.com/github/merhard/permitter]
+
+Here are some instructions for setting up Permitter. Try this out and provide feedback in the {issue tracker}[https://github.com/merhard/permitter/issues].
+
+
+== Setup
+
+Permitter expects your controllers to have a +current_user+ method. Add some authentication for this (such as Devise[https://github.com/plataformatec/devise]).
+
+To install Permitter, add it to your +Gemfile+ and run the +bundle+ command.
+
+  gem "permitter", git: "git://github.com/merhard/permitter.git"
+
+Next generate a Permission class, this is where your permissions will be defined.
+
+  rails g permitter:permission
+
+Add authorization by calling +authorize_user!+ in a +before_action+ in any controller (or the +ApplicationController+ to authorize the whole app).
+
+  class ApplicationController < ActionController::Base
+    before_action :authorize_user!
+  end
+
+This will add an authorization check locking down every action in the controller. If you try visiting a page without granting the user access, a <tt>Permitter::Unauthorized</tt> exception will be raised. You can catch this exception and modify its behavior.
+
+  class ApplicationController < ActionController::Base
+    before_action :authorize_user!
+
+    rescue_from Permitter::Unauthorized do |exception|
+      # your code here
+    end
+  end
+
+
+== Defining Abilities
+
+You grant access to controller actions through the +Permission+ class which was generated above. The +current_user+ is passed in allowing you to define permissions based on user attributes. For example:
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      if user
+        allow_all
+      else
+        allow_action [:sessions, :registrations], [:new, :create]
+        allow_action :projects, :index
+      end
+    end
+  end
+
+Here, if there is a +current_user+ (user signed in), he will be able to perform any action on any controller. If +current_user+ is +nil+ (user not signed in), the visitor can only access the new and create actions of the +SessionsController+ and the +RegistrationsController+ as well as the +#index+ action of the +ProjectsController+.
+
+The first argument to +allow_action+ is the controller name being permitted. The second argument is the action they can perform in that controller.
+
+As shown above, pass an array to either of these will grant permission on each item in the array. Controller names and actions can be represented as symbols or strings.
+
+You can check permissions in any controller or view using the +allowed_action?+ method.
+
+  <% if allowed_action? :projects, :create %>
+    <%= link_to "New Project", new_project_path %>
+  <% end %>
+
+Here the link will only show up if the user can create projects.
+
+
+== Resource Conditions
+
+If you need to change authorization based on a model's attributes, you can do so by passing a block as the last argument to +allow_action+. For example, if you want to only allow a user to edit projects which he/she owns, first:
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      if user
+
+        allow_action :projects, [:edit, :update] do |project|
+          project.user_id == user.id
+        end
+
+      end
+    end
+  end
+
+
+Then, create a +current_resource+ method in that controller:
+
+  class ProjectsController < ApplicationController
+
+    private
+
+    def current_resource
+      @project ||= Project.find(params[:id]) if params[:id]
+    end
+  end
+
+
+You can still check permissions using the +allowed_action?+ method. Just pass in the resource.
+
+  <% if allowed_action? :projects, :update, @project %>
+    <%= link_to "Edit Project", edit_project_path %>
+  <% end %>
+
+Here, it will only show the edit link if the +user_id+ of the project matches the +current_user.id+.
+
+
+== Resource Attributes
+
+Rails 4 moved mass assignment to the controller level with +strong_parameters+. +Permitter+ fully supports Rails 4 mass assignment. If mass assignment in your app requires no user specific logic, it may not be necessarry to use Permitter for mass assignment sanitation. In this case, just follow normal Rails 4 methods for strong parameter mass assignment.
+
+If your app does require user specific mass assignment logic, +Permitter+ supplies an +allow_param+ method to be used along-side +allow_action+ in your +Permission+ class.
+
+For example, suppose a user should only be able to set the title (and no other attributes) of projects they own. Just:
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      allow_action :project, [:index, :show]
+
+      if user
+        allow_action :projects, [:new, :create]
+
+        allow_action :projects, [:edit, :update] do |project|
+          project.user_id == user.id
+        end
+
+        allow_param :project, :title
+
+        allow_all if user.admin?
+
+      end
+    end
+  end
+
+
+The +allow_param+ method takes a resource title (or array of resource titles) and an attribute (or array of attributes) for that resource to be permitted via strong parameters. +Permitter+ will modify +params+ for that resource (here, <tt>params[:project]</tt>) to only include the whitelisted attributes, removing all others. +Permitter+ flags the remaining +params+ of that resource permitted per strong parameters. This allows mass assignment in the controller to follow the old Rails 3.2 syntax while using the more secure methodology of strong paramters.
+
+  class ProjectsController < ApplicationController
+    
+    ...
+
+    def create
+      @project = Project.create(params[:project])
+    end
+
+    def update
+      @project = Project.find(params[:id])
+      @project.update(params[:project])
+    end
+
+    ...
+
+  end
+
+
+You can check permissions using the +allowed_param?+ method.
+
+  <% if allowed_param? :project, :title %>
+    <div class="field">
+      <%= f.label :title %><br />
+      <%= f.text_field :title %>
+    </div>
+  <% end %>
+
+Here, it will only show the title label and text field if the user is allowed to modify the title attribute of +Project+.
+
+
+== Permission Scoping
+
+Sometimes you may want to scope the relation used in the +#index+ action of the controller. +Permitter+ allows you to do this in your +Permission+ class without the need to repeat yourself.
+
+For example:
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      allow_action :projects, :index
+
+      if user
+        allow_action :projects, :show do |project|
+          project.user_id == user.id
+        end
+      end
+    end
+  end
+
+  class ProjectController < ApplicationController
+
+    def index
+      @projects = Project.permitted_by(current_permissions)
+    end
+
+  end
+
+The <tt>@projects</tt> variable will now be scoped to projects available to the +#show+ action.
+
+
+If the +#show+ action does not match the scoping needed, any action can be used (even a custom one if none match).
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      allow_action :projects, :index
+
+      if user
+        allow_action :projects, :show do |project|
+          project.user_id == user.id
+        end
+
+        allow_action :projects, :custom_action do |project|
+          # your scope here
+        end
+      end
+    end
+  end
+
+Then:
+
+  class ProjectController < ApplicationController
+
+    def index
+      @projects = Project.permitted_by(current_permissions, :custom_action)
+    end
+
+  end
+
+
+
+When writing scopes via an association, a custom action must be used with a block requiring no arguments.
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      allow_action :comments, :index
+
+      allow_action :comments, :permitted do
+        article.published == true
+      end
+    end
+  end
+
+  class CommentsController < ApplicationController
+    def index
+      @comments = Comment.joins(:article).permitted_by(@permissions, :permitted)
+      #alternatively: Comment.joins{article}.permitted_by(@permissions, :permitted)
+    end
+  end
+
+
+  class Comment < ActiveRecord::Base
+    # t.integer :article_id
+    
+    belongs_to :article
+  end
+
+  class Article < ActiveRecord::Base
+    # integer :category_id
+    # boolean :published
+    
+    belongs_to :category
+    has_many :comments
+  end
+  
+  class Category < ActiveRecord::Base
+    # boolean :visible
+
+    has_many :articles
+  end
+
+Nested joins are also supported:
+
+  class Permission
+    include Permitter::Permission
+
+    def initialize(user)
+      allow_action :comments, :index
+
+      allow_action :comments, :permitted do
+        article.category.visible == true
+      end
+    end
+  end
+
+  class CommentsController < ApplicationController
+    def index
+      @comments = Comment.joins{article.category}.permitted_by(@permissions, :permitted)
+    end
+  end
+
+
+Permitter accomplishes this using the squeel[https://github.com/activerecord-hackery/squeel] gem. See the squeel docs for any query related questions.
+
+
+
+== Special Thanks
+
+Permitter was inspired by cancan[https://github.com/ryanb/cancan/] and Railscasts[http://railscasts.com/episodes/385-authorization-from-scratch-part-1/].

data/Rakefile

@@ -0,0 +1,32 @@
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Permitter'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec
+
+
+
+Bundler::GemHelper.install_tasks

data/lib/generators/permitter/permission/USAGE

@@ -0,0 +1,5 @@
+Description:
+  The permitter:permission generator creates a Permission class in the models
+  directory. You can move this file anywhere you want as long as it
+  is in the load path. A spec file is also generated if a spec
+  directory exists.

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

@@ -0,0 +1,16 @@
+module Permitter
+  module Generators
+    class PermissionGenerator < Rails::Generators::Base
+      
+      source_root File.expand_path("../templates", __FILE__)
+
+      def generate_permission
+        copy_file "permission.rb", "app/models/permission.rb"
+        if File.exist?(File.join(destination_root, "spec"))
+          copy_file "permission_spec.rb", "spec/models/permission_spec.rb"
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+class Permission
+  include Permitter::Permission
+
+  def initialize(user)
+    # Define permissions for the passed in (current) user. For example:
+    #
+    #   if user
+    #     allow_all
+    #   else
+    #     allow_action [:sessions, :registrations], [:new, :create]
+    #     allow_action :sessions, :destroy
+    #   end
+    #
+    # Here if there is a user he will be able to perform any action on any controller.
+    # If someone is not logged in he can only access the registrations and sessions controllers.
+    #
+    # The first argument to `allow_action` is the controller name being permitted. The second
+    # argument is the action they can perform in that controller. Passing an array to either of
+    # these will grant permission on each item in the array.
+    #
+  end
+end

data/lib/generators/permitter/permission/templates/permission_spec.rb

@@ -0,0 +1,17 @@
+require "spec_helper"
+require "permitter/matchers"
+
+describe Permission do
+  describe "as guest" do
+
+    subject { Permission.new(nil) }
+
+    it "allows new sessions" do
+      # Define what a guest is allowed to do
+      # should allow_action(:sessions, :new)
+      # should allow_action(:sessions, :create)
+      # should_not allow_action(:sessions, :destroy)
+    end
+
+  end
+end

data/lib/permitter.rb

@@ -0,0 +1,4 @@
+require 'permitter/controller_additions'
+require 'permitter/exceptions'
+require 'permitter/model_additions'
+require 'permitter/permission'

data/lib/permitter/controller_additions.rb

@@ -0,0 +1,43 @@
+require 'active_support/concern'
+
+module Permitter
+  module ControllerAdditions
+    extend ActiveSupport::Concern
+
+    included do
+
+      delegate :allowed_action?, to: :current_permissions
+      helper_method :allowed_action?
+
+      delegate :allowed_param?, to: :current_permissions
+      helper_method :allowed_param?
+
+
+      private
+
+      def authorize_user!
+        if current_permissions.allowed_action?(params[:controller], params[:action], current_resource)
+          current_permissions.permit_params!(params)
+        else
+          raise Permitter::Unauthorized
+        end
+      end
+
+      def current_permissions
+        @current_permissions ||= ::Permission.new(current_user)
+      end
+
+      def current_resource
+        nil
+      end
+
+    end
+
+  end
+end
+
+if defined? ActionController::Base
+  ActionController::Base.class_eval do
+    include Permitter::ControllerAdditions
+  end
+end