acts_as_permission 1.2.0 → 2.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.9.2@acts_as_permission

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+case ENV["MODEL_ADAPTER"]
+when nil, "active_record"
+  gem "sqlite3"
+  gem "activerecord", :require => "active_record"
+else
+  raise "Unknown model adapter: #{ENV["MODEL_ADAPTER"]}"
+end
+
+gemspec

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Cyril Wack
+Copyright (c) 2009-2011 Cyril Wack
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,49 +1,296 @@
 = Acts as permission
 
-This Rails plugin provides a list of permissions attached to a resource, according to ACL concept.  Permissions determine specific access rights for a resource depending of its controller actions such as: show, edit, update, destroy, evaluated from the given resource and such as: index, new, create, evaluated from the parent of the given resource.
+Acts as permission is a plugin for Ruby on Rails that allows to assign a list of
+permissions on an object, according to the ACL concept, where each permission
+can be extended to a subject.
 
-Each permission field attributed to a resource can be defined as true, false or nil.  When a resource permission is set as nil, the same permission is searched from its nearest relative to its parent farthest and the first given boolean value is returned.  If permission is nil for a resource and its potential parents, then the method returns false.
+More specifically, it can make possible to allow or to deny any action of the
+controller of a protected resource.  These actions are called permittables.
 
-== Install
+A permittable action can be directly attached to a resource.  Examples of such
+actions:
 
-Install the gem (recommended):
+* <tt>show</tt>,
+* <tt>edit</tt>,
+* <tt>update</tt>,
+* <tt>destroy</tt>.
 
-  sudo gem install acts_as_permission
+Or it can be indirectly, through a parent resource.  Examples:
 
-Alternatively, you can install it as a Rails plugin:
+* <tt>index</tt>,
+* <tt>new</tt>,
+* <tt>create</tt>.
 
-  script/plugin install git://github.com/cyril/acts_as_permission.git
+Here is an example of query to a direct article's action:
 
-Generate and apply the migration:
+  @article = Article.find(params[:id])
+  @article.permission?("articles#destroy")          # => false
 
-  script/generate acts_as_permission model
-  rake db:migrate
+Same query, extended to a user:
+
+  @article.permission?("articles#destroy", @bob)    # => nil
+  @article.permission?("articles#destroy", @admin)  # => true
+
+A query example on an indirect articles' action, through a category:
+
+  @category = Category.find(params[:category_id])
+  @category.permission?("articles#index")           # => true
+
+Other examples, on unpermittable actions:
+
+  @category.permission?("articles#read")            # => nil
+  @category.permission?("silk_routes#index")        # => nil
+
+The value of a permission depends on its context, which includes a route and an
+optional extension to a permitted resource.
+
+The <tt>permission?(route, ext = nil)</tt> query may return, depending on the
+context:
+
+* <tt>true</tt>, if the permission is allowed;
+* <tt>false</tt>, if the permission is denied;
+* <tt>nil</tt>, if the permission is indefinable (resulting of the unknowned
+context).
+
+== Philosophy
+
+General library that does only one thing, without any feature.
+
+== Installation
+
+Include the gem in your <tt>Gemfile</tt>:
+
+  gem 'acts_as_permission'
 
-== Example
+And run the +bundle+ command.  Or as a plugin:
 
-  script/generate acts_as_permission Category
-  script/generate acts_as_permission Article show edit update destroy
+  rails plugin install git://github.com/cyril/acts_as_permission.git
+
+Then, generate files and apply the migration:
+
+  rails generate permissions
   rake db:migrate
 
-  class Category < ActiveRecord::Base
-    acts_as_permission
+== Getting started
+
+=== Configuring models
+
+Permittable models have to be declared with <tt>acts_as_permission</tt>.  And
+they have to be so with a default permission mask.  For example:
+
+  # app/models/article.rb
+  class Article < ActiveRecord::Base
+    acts_as_permission({
+      'articles#show'     => [true, {}],
+      'articles#edit'     => [false, {
+        :permitted_id => 1,
+        :permitted_type => "User",
+        :value => true }],
+      'articles#update'   => [false, {
+        :permitted_id => 1,
+        :permitted_type => "User",
+        :value => true }],
+      'articles#destroy'  => [false, {
+        :permitted_id => 1,
+        :permitted_type => "User",
+        :value => true }],
+      'comments#index'    => true,
+      'comments#new'      => [true, [{
+        :permitted_id => 3,
+        :permitted_type => "User",
+        :value => false }]],
+      'comments#create'   => [true, [{
+        :permitted_id => 3,
+        :permitted_type => "User",
+        :value => false }]]})
+
     belongs_to :user
-    has_many :articles
+    has_many :comments, :dependent => :destroy
   end
 
-  class Article < ActiveRecord::Base
-    acts_as_permission :category
-    belongs_to :category
+  # app/models/comment.rb
+  class Comment < ActiveRecord::Base
+    acts_as_permission([
+      ["comments#show",     true],
+      ["comments#edit",     [false, [
+        {:permitted_id => 1, :permitted_type => "User", :value => true},
+        {:permitted_id => 2, :permitted_type => "User", :value => true} ]]],
+      ["comments#update",   [false, [
+        {:permitted_id => 1, :permitted_type => "User", :value => true},
+        {:permitted_id => 2, :permitted_type => "User", :value => true} ]]],
+      ["comments#destroy",  [false, {
+        :permitted_id => 1,
+        :permitted_type => "User",
+        :value => true }]]])
+
+    belongs_to :article
     belongs_to :user
   end
 
-  # Check permission to list articles of the given category:
-  @category.has_permission?('index')
+Optionally, some models (such as <tt>User</tt>, <tt>Group</tt>, <tt>Role</tt>)
+can also be declared as permitted with <tt>is_able_to_be_permitted</tt>.
+Example:
+
+  # app/models/user.rb
+  class User < ActiveRecord::Base
+    is_able_to_be_permitted
+
+    with_options :dependent => :destroy do |opts|
+      opts.has_many :articles
+      opts.has_many :comments
+    end
+  end
+
+=== Configuring controllers
+
+Example of a fully protected comments controller:
+
+  class CommentsController < ApplicationController
+    before_filter :check_permissions
+
+    # GET /comments
+    # GET /comments.xml
+    def index
+      @comments = current_resource.comments
+
+      respond_to do |format|
+        format.html # index.html.erb
+        format.xml  { render :xml => @comments }
+      end
+    end
+
+    # GET /comments/1
+    # GET /comments/1.xml
+    def show
+      @comment = current_resource
+
+      respond_to do |format|
+        format.html # show.html.erb
+        format.xml  { render :xml => @comment }
+      end
+    end
+
+    # GET /comments/new
+    # GET /comments/new.xml
+    def new
+      @comment = current_resource.comments.build
+
+      respond_to do |format|
+        format.html # new.html.erb
+        format.xml  { render :xml => @comment }
+      end
+    end
+
+    # GET /comments/1/edit
+    def edit
+      @comment = current_resource
+    end
+
+    # POST /comments
+    # POST /comments.xml
+    def create
+      @comment = current_resource.comments.build(params[:comment])
+
+      respond_to do |format|
+        if @comment.save
+          format.html { redirect_to(@comment,
+            :notice => 'Comment was successfully created.') }
+          format.xml  { render :xml => @comment, :status => :created,
+            :location => @comment }
+        else
+          format.html { render :action => "new" }
+          format.xml  { render :xml => @comment.errors,
+            :status => :unprocessable_entity }
+        end
+      end
+    end
+
+    # PUT /comments/1
+    # PUT /comments/1.xml
+    def update
+      @comment = current_resource
+
+      respond_to do |format|
+        if @comment.update_attributes(params[:comment])
+          format.html { redirect_to(@comment,
+            :notice => 'Comment was successfully updated.') }
+          format.xml  { head :ok }
+        else
+          format.html { render :action => "edit" }
+          format.xml  { render :xml => @comment.errors,
+            :status => :unprocessable_entity }
+        end
+      end
+    end
+
+    # DELETE /comments/1
+    # DELETE /comments/1.xml
+    def destroy
+      @comment = current_resource
+      @comment.destroy
+
+      respond_to do |format|
+        format.html { redirect_to(comments_url) }
+        format.xml  { head :ok }
+      end
+    end
+
+    protected
+
+    def check_permissions
+      route = [ params[:controller],
+                params[:action] ].join('#')
+
+      unless (current_user &&
+                           current_resource.permission?(route, current_user)) ||
+                           current_resource.permission?(route)
+        respond_to do |format|
+          format.html { redirect_to(:back, :warning => '403 Forbidden',
+            :status => :forbidden) }
+          format.xml  { render :xml => '403 Forbidden', :status => :forbidden }
+        end
+      end
+    end
+
+    def current_resource
+      @current_resource ||= if params[:id]
+        Comment.find(params[:id])
+      else
+        Article.find(params[:article_id], :readonly => true)
+      end
+    end
+  end
+
+=== Configuring views
+
+We can now perform some checks on related views from a comment instance, thanks
+to the protected actions of its controller, in order to only display allowed
+links:
+
+  <% if current_user && @comment.permission?("comments#edit", current_user) ||
+                        @comment.permission?("comments#edit") %>
+    <%= link_to "Edit comment",
+      edit_article_comment_path(@comment.article, @comment) %>
+  <% end %>
+
+And also some indirect checks from the current article instance, like this one:
+
+  <% if current_user && @article.permission?("comments#index", current_user) ||
+                        @article.permission?("comments#index") %>
+    <%= link_to "Comments", article_comments_path(@article) %>
+  <% end %>
+
+Or this other one:
+
+  <% if current_user && @article.permission?("comments#new", current_user) ||
+                        @article.permission?("comments#new") %>
+    <%= link_to "New comment", new_article_comment_path(@article) %>
+  <% end %>
+
+==== Form helper
 
-  # Check permission to destroy the given article:
-  @article.has_permission?('destroy')
+Object's permissions management is as simple as:
 
-  # Form helper that generate permissions fields for each article:
-  <%= permission_fields :article %>
+  <%= permission_fields f %>
 
-Copyright (c) 2009 Cyril Wack, released under the MIT license
+Copyright (c) 2009-2011 Cyril Wack, released under the MIT license

data/Rakefile

@@ -1,12 +1,12 @@
-require 'rubygems'
-require 'rake'
-require 'echoe'
+require 'bundler'
+Bundler::GemHelper.install_tasks
 
-Echoe.new('acts_as_permission', '1.2.0') do |p|
-  p.description    = "Simple Rails plugin to assign a list of permissions on a resource."
-  p.url            = "http://github.com/cyril/acts_as_permission"
-  p.author         = "Cyril Wack"
-  p.email          = "cyril.wack@gmail.com"
-  p.ignore_pattern = ["tmp/*", "script/*"]
-  p.development_dependencies = []
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_{helper,test}.rb"]
 end
+
+task :default => :test

data/VERSION.yml

@@ -1,4 +1,4 @@
 ---
-:major: 1
-:minor: 2
+:major: 2
+:minor: 0
 :patch: 0

data/acts_as_permission.gemspec

@@ -1,32 +1,18 @@
-# -*- encoding: utf-8 -*-
-
 Gem::Specification.new do |s|
-  s.name = %q{acts_as_permission}
-  s.version = "1.2.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Cyril Wack"]
-  s.cert_chain = ["/Users/cyril/gem-public_cert.pem"]
-  s.date = %q{2010-04-12}
+  s.name        = "acts_as_permission"
+  s.version     = Psych.load_file("VERSION.yml").values.join('.')
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Cyril Wack"]
+  s.email       = ["cyril@gosu.fr"]
+  s.homepage    = "http://github.com/cyril/acts_as_permission"
+  s.summary     = %q{Simple permission solution for Rails.}
   s.description = %q{Simple Rails plugin to assign a list of permissions on a resource.}
-  s.email = %q{cyril.wack@gmail.com}
-  s.extra_rdoc_files = ["README.rdoc", "lib/acts_as_permission.rb", "lib/permissions_helper.rb"]
-  s.files = ["MIT-LICENSE", "README.rdoc", "Rakefile", "VERSION.yml", "generators/acts_as_permission/USAGE", "generators/acts_as_permission/acts_as_permission_generator.rb", "init.rb", "lib/acts_as_permission.rb", "lib/permissions_helper.rb", "Manifest", "acts_as_permission.gemspec"]
-  s.homepage = %q{http://github.com/cyril/acts_as_permission}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Acts_as_permission", "--main", "README.rdoc"]
-  s.require_paths = ["lib"]
-  s.rubyforge_project = %q{acts_as_permission}
-  s.rubygems_version = %q{1.3.6}
-  s.signing_key = %q{/Users/cyril/gem-private_key.pem}
-  s.summary = %q{Simple Rails plugin to assign a list of permissions on a resource.}
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  s.rubyforge_project = "acts_as_permission"
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
+  s.add_runtime_dependency "railties", ">= 3.0.0"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
 end

data/app/views/acts_as_permission/_permission_fields.html.erb

@@ -0,0 +1,35 @@
+<%= content_tag :fieldset, :id => "#{f.object}_permissions" do %>
+  <%= content_tag :legend, t('.legend') %>
+
+  <%= f.fields_for :permissions do |permission_fields| %>
+    <p>
+      <strong>
+      <%= permission_fields.object.route %>
+
+      <% if permission_fields.object.permitted.present? %>
+        ; <%= [ permission_fields.object.permitted.type,
+                permission_fields.object.permitted.id ].join('-') %>
+      <% end %>
+      </strong>
+    </p>
+
+    <p>
+      <label>
+        <%= permission_fields.radio_button(:value, true) %>
+        <%= t('.verb.allow') %>
+      </label>
+
+      <label>
+        <%= permission_fields.radio_button(:value, false) %>
+        <%= t('.verb.deny') %>
+      </label>
+
+      <br />
+
+      <label>
+        <%= t('.destroy') %>:
+        <%= permission_fields.check_box :_destroy %>
+      </label>
+    </p>
+  <% end %>
+<% end %>

data/config/locales/en.yml

@@ -0,0 +1,8 @@
+en:
+  acts_as_permission:
+    permission_fields:
+      legend: "Permissions"
+      verb:
+        allow: "allow"
+        deny: "deny"
+      destroy: "Delete"

data/config/locales/fr.yml

@@ -0,0 +1,8 @@
+fr:
+  acts_as_permission:
+    permission_fields:
+      legend: "Permissions"
+      verb:
+        allow: "autoriser"
+        deny: "refuser"
+      destroy: "Supprimer"

data/config/locales/ja.yml

@@ -0,0 +1,8 @@
+ja:
+  acts_as_permission:
+    permission_fields:
+      legend: "パーミッション"
+      verb:
+        allow: "許可する"
+        deny: "否定する"
+      destroy: "削除する"

data/lib/acts_as_permission.rb

@@ -1,51 +1,136 @@
-require 'active_record/base'
-
 module ActsAsPermission
-  def self.included(base)
-    base.extend(ClassMethods)
-  end
+  module Permittable
+    def permission(route, ext = nil)
+      ext = {
+        :permitted_type => (ext.blank? ? nil : ext.class.name),
+        :permitted_id   => (ext.blank? ? nil : ext.id) } unless ext.is_a? Hash
+
+      context = {:route => route}.merge(ext)
 
-  module ClassMethods
-    attr_accessor :parental_resource_permission
+      create_default_permission!(route, ext) unless permissions.exists?(context)
 
-    def acts_as_permission(resource = nil)
-      attr_accessible :index_permission, :new_permission, :create_permission, :show_permission, :edit_permission, :update_permission, :destroy_permission
-      before_save :complete_permissions_if_needed
+      permissions.first(:conditions => context)
+    end
+
+    def permission?(route, ext = nil)
+      permission = permission(route, ext)
+      permission.value? if permission.present?
+    end
 
-      self.parental_resource_permission = resource
+    def create_permission!(route, value, ext = nil)
+      return unless self.class.permittable?(route)
 
-      class_eval <<-EOV
-        include ActsAsPermission::InstanceMethods
+      ext = {
+        :permitted_type => (ext.blank? ? nil : ext.class.name),
+        :permitted_id   => (ext.blank? ? nil : ext.id) } unless ext.is_a? Hash
 
-        def self.could_have_permission_from_the_parent_resource?
-          !self.parental_resource_permission.nil?
+      context = {:route => route}.merge(ext)
+      parameters = context.merge(:value => value)
+
+      permissions.create(parameters) unless permissions.exists?(context)
+    end
+
+    def create_default_permissions!
+      permissions = self.class.permissions.map do |route, masks|
+        masks.map do |mask|
+          ext   = mask.dup
+          value = ext.delete(:value)
+
+          create_permission!(route, value, ext)
         end
-      EOV
+      end
+
+      permissions.flatten!
+      permissions.compact
+    end
+
+    def mass_assignment_authorizer
+      super + [:permissions_attributes]
     end
-  end
 
-  module InstanceMethods
     def has_permission?(action)
-      if self.respond_to?("#{action}_permission")
-        return self.send("#{action}_permission") unless self.send("#{action}_permission").nil?
+      ActiveSupport::Deprecation.warn 'has_permission?(action) is deprecated ' +
+        'and may be removed from future releases, use permission?(route, ext ' +
+        '= nil) instead.'
+
+      permission? [self.class.name.tableize, action].join('#')
+    end
+
+    protected
+
+    def create_default_permission!(route, ext = nil)
+      return unless self.class.permittable?(route)
+
+      ext = {
+        :permitted_type => (ext.blank? ? nil : ext.class.name),
+        :permitted_id   => (ext.blank? ? nil : ext.id) } unless ext.is_a? Hash
+
+      masks = self.class.permissions[route.to_sym].select do |mask|
+        mask[:permitted_id] == ext[:permitted_id] &&
+          mask[:permitted_type] == ext[:permitted_type]
       end
 
-      if self.class.could_have_permission_from_the_parent_resource?
-        self.send(self.class.parental_resource_permission).has_permission?(action)
-      else
-        false
+      if (mask = masks.first).present?
+        parameters = mask.merge({:route => route.to_s})
+        permissions.create(parameters)
       end
     end
+  end
 
-    private
-
-    def complete_permissions_if_needed
-      self.update_permission = self.edit_permission if self.respond_to?('edit_permission') && self.respond_to?('update_permission')
-      self.create_permission = self.new_permission if self.respond_to?('new_permission') && self.respond_to?('create_permission')
-      true
+  module Permitted
+    def permitted?(object, route)
+      object.permission?(route, self)
     end
   end
 end
 
-ActiveRecord::Base.class_eval { include ActsAsPermission }
-ActionController::Base.helper PermissionsHelper
+class ActiveRecord::Base
+  def self.is_able_to_be_permitted
+    has_many :permissions, :as => :permitted, :dependent => :destroy
+    validates_associated :permissions
+
+    include ActsAsPermission::Permitted
+  end
+
+  def self.acts_as_permission(acl)
+    @acl = acl.to_a.inject({}) do |list, permission|
+      route, masks = permission.to_a[0], permission.to_a[1]
+      masks = [masks] unless masks.is_a?(Array)
+
+      permission = {:value => masks.first}
+      permission.freeze
+
+      extensions = masks[1] || []
+      extensions = [extensions] unless extensions.is_a?(Array)
+      extensions.map! do |ext|
+        ext ||= {}
+        ext.freeze
+      end
+
+      permissions = extensions.unshift(permission)
+      permissions.compact!
+      permissions.uniq!
+      permissions.freeze
+
+      list.update({route.to_sym => permissions})
+    end
+
+    @acl.freeze
+
+    has_many :permissions, :as => :permittable, :dependent => :destroy
+    accepts_nested_attributes_for :permissions, :allow_destroy => true
+    validates_associated :permissions
+
+    class << self
+      def permittable?(route)
+        @acl.has_key?(route.to_sym)
+      end
+
+      def permissions
+        @acl
+      end
+    end
+
+    include ActsAsPermission::Permittable
+  end
+end

data/lib/generators/permissions/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Copies the following files
+      - create_permissions.rb to db/migrate/
+      - permission.rb         to app/models/
+      - permissions_helper.rb to app/helpers/
+
+Usage:
+    `rails generate permissions`