policies 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e7d39fff13b803ccfefdae4c420e79e3e0e30223
+  data.tar.gz: 1f18156a9464038dc45230efce8449c4394fe3f4
+SHA512:
+  metadata.gz: a88f256e98bd91de715b40776b27ef26743004ca23e4739b1f555fbcd195a6b74d516bcb540668141ad7438355f0f9fd16fa6fed38950cc35bcc74f1bd9b231b
+  data.tar.gz: ee238a87870c608a0945a1e0dd05eb37972b7d9c8a82917b1494a90d6180b63443e33662afa8c495a0e2d8a01e3a2b1ed48c73503a155ec814fc32ec8d07b00f

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Josh Wetzel
+
+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,236 @@
+# Policies
+[![Gem Version](https://badge.fury.io/rb/policies.svg)](http://badge.fury.io/rb/policies)
+
+Policies is an authorization control library for Ruby on Rails.
+
+It was primarily designed for use in applications where a user's authorization may change depending on a particular
+context. For example, in an application where users may belong to one or more projects, it may be ideal for them to edit
+the settings of a project they own, but not necessarily edit the settings of a project in which they are a member.
+
+This gem helps facilitate the creation of those authorization rules through simple, well defined Ruby classes.
+
+## Installation
+In your Gemfile, include the `policies` gem.
+
+```ruby
+gem 'policies'
+```
+
+## Prerequisites
+Policies makes a few logical assumptions for the ease of implementation.
+
+  1. It requires a `current_user` method to be defined.
+
+    ```ruby
+    def current_user
+      @current_user ||= User.find(session[:user_id]) if session[:user_id]
+    end
+    ```
+  2. It requires a `current_role` method to be defined.
+
+    ```ruby
+    # On an intermediary object, such as membership
+    def current_role
+      if @project.present? && @project.persisted?
+        @current_role ||= @project.memberships.find_by(user: current_user).role
+      end
+    end
+
+    # On the user
+    def current_role
+      @current_role ||= current_user.role
+    end
+    ```
+  3. The names of policy classes must be a combination of an object's class suffixed with `Policy`. For example, a
+     policy for projects should be named `ProjectPolicy`, and a policy for users should be named `UserPolicy`. It is
+     recommended to place policies in an `app/policies` directory.
+  4. Policies should inherit from `Policies::Base`.
+  5. Method names within a policy should be suffixed with a `?`.
+
+## Getting Started
+Take the following example, in which a user may belong to one or more projects through an intermediary membership.
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  has_many :memberships
+  has_many :projects, through: :memberships
+end
+
+# app/models/project.rb
+class Project < ActiveRecord::Base
+  has_many :memberships
+  has_many :users, through: :memberships
+end
+
+# app/models/membership.rb
+class Membership < ActiveRecord::Base
+  belongs_to :user
+  belongs_to :project
+end
+
+# app/models/role.rb
+class Role < ActiveRecord::Base
+  def member?
+    %w(Member Administrator Owner).include?(name)
+  end
+
+  def admin?
+    %w(Administrator Owner).include?(name)
+  end
+
+  def owner?
+    name == 'Owner'
+  end
+end
+```
+
+Imagine a user is an owner of Project A and a member of Project B. In this specific case, the role of the user will
+change depending on which project they are viewing. Owners of a project should have the ability to edit its settings or
+invite new members, while members of a project should only be allowed to view it.
+
+With that in mind, a new policy class may be created to limit the authorization depending on the current role.
+
+### Creating a New Policy
+Within `app/policies`, create a new file named `project_policy.rb`. **Remember to restart your application server to
+pick up the new directory.**
+
+```ruby
+# app/policies/project_policy.rb
+class ProjectPolicy < Policies::Base
+end
+```
+
+### Limiting Access
+Let's assume we want to limit the edit and update actions to a project owner.
+
+```ruby
+# app/policies/project_policy.rb
+class ProjectPolicy < Policies::Base
+  def edit?
+    current_role.owner?
+  end
+  alias_method :update?, :edit?
+end
+```
+
+An instance variable named after the object's class is also available for use within the policy.
+
+```ruby
+# app/policies/project_policy.rb
+class ProjectPolicy < Policies::Base
+  def destroy?
+    @project.can_be_destroyed? && current_role.owner?
+  end
+end
+```
+
+Using a different example, a user may only be allowed to edit their own account.
+
+```ruby
+# app/policies/user_policy.rb
+class UserPolicy < Policies::Base
+  def edit?
+    current_user == @user
+  end
+  alias_method :update?, :edit?
+end
+```
+
+### Updating Views and Controllers
+After the policy is written, views may be updated with the `authorized?` helper.
+
+```erb
+<% if authorized?(:edit, @project) %>
+  <%= link_to @project, project_path(@project) %>
+<% end %>
+```
+
+Controllers may be updated with the `authorize` and `authorized?` methods.
+
+```ruby
+# app/controllers/projects_controller.rb
+class ProjectsController < ApplicationController
+  def edit
+    @project = current_user.projects.find(params[:id])
+    authorize(@project)
+  end
+
+  def update
+    @project = current_user.projects.find(params[:id])
+    authorize(@project)
+
+    if @project.update(project_params)
+      redirect_to @project, success: translate('.success')
+    else
+      render :edit
+    end
+  end
+end
+```
+
+A better, more DRY approach may be using `authorize` in a `before_action`.
+
+```ruby
+# app/controllers/projects_controller.rb
+class ProjectsController < ApplicationController
+  before_action :set_project, only: [:edit, :update]
+
+  def update
+    if @project.update(project_params)
+      redirect_to @project, success: translate('.success')
+    else
+      render :edit
+    end
+  end
+
+  private
+
+  def set_project
+    @project = current_user.projects.find(params[:id])
+    authorize(@project)
+  end
+end
+```
+
+`authorize` will raise `Policies::UnauthorizedError` if the user is restricted from accessing the particular action.
+
+`authorized?` may be used when a boolean should be returned. If no action argument is passed, it will default to the
+current action.
+
+```ruby
+# app/controllers/projects_controller.rb
+class ProjectsController < ApplicationController
+  def edit
+    @project = Project.find(params[:id])
+
+    if authorized?(@project)
+      ...
+    else
+      redirect_to projects_path, error: translate('.unauthorized')
+    end
+  end
+end
+```
+
+In a situation where an instantiated object is not available, a symbol may be passed to `authorized?` and `authorize`.
+If no action argument is passed, it defaults to the current `action_name`.
+
+```erb
+<% if authorized?(:index, :projects) %>
+  <%= link_to @project, projects_path %>
+<% end %>
+```
+
+```ruby
+# app/controllers/projects_controller.rb
+class ProjectsController < ApplicationController
+  def index
+    authorize(:projects)
+    @projects = current_user.projects
+  end
+end
+```
+
+## Acknowledgments
+Special thanks to [Pundit](https://github.com/elabs/pundit) for the inspiration for this project.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc 'Run tests'
+task default: :test

data/lib/policies.rb

@@ -0,0 +1,3 @@
+require 'policies/base'
+require 'policies/exceptions'
+require 'policies/methods'

data/lib/policies/base.rb

@@ -0,0 +1,14 @@
+module Policies
+  class Base
+    attr_reader :current_user, :current_role
+
+    def initialize(current_user, current_role, object)
+      @current_user = current_user
+      @current_role = current_role
+
+      unless object.is_a?(Symbol)
+        instance_variable_set('@' + object.class.to_s.underscore, object)
+      end
+    end
+  end
+end

data/lib/policies/exceptions.rb

@@ -0,0 +1,3 @@
+module Policies
+  UnauthorizedError = Class.new(StandardError)
+end

data/lib/policies/methods.rb

@@ -0,0 +1,32 @@
+module Policies::Methods
+  def self.included(base)
+    base.send(:helper_method, :authorized?) if base.respond_to?(:helper_method)
+  end
+
+  def authorize(action = action_name, object)
+    raise Policies::UnauthorizedError unless authorized?(action, object)
+  end
+
+  def authorized?(action = action_name, object)
+    policy_class(object).new(current_user, current_role, object).public_send(action.to_s + '?')
+  end
+
+  private
+
+  def policy_class(object)
+    class_name =
+      if object.is_a?(Symbol)
+        object.to_s.classify
+      else
+        object.class.to_s
+      end + 'Policy'
+
+    class_name.constantize
+  end
+end
+
+if defined?(ActionController::Base)
+  ActionController::Base.class_eval do
+    include Policies::Methods
+  end
+end

data/policies.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |s|
+  s.name    = 'policies'
+  s.version = '1.1.0'
+  s.files   = `git ls-files`.split($/)
+  s.summary = 'Authorization control'
+  s.author  = 'Josh Wetzel'
+  s.license = 'MIT'
+  s.required_ruby_version = '~> 2'
+
+  s.add_dependency 'actionpack', '~> 4.2'
+  s.add_dependency 'activesupport', '~> 4.2'
+end

data/test/policies/project_policy.rb

@@ -0,0 +1,9 @@
+class ProjectPolicy < Policies::Base
+  def show?
+    true
+  end
+
+  def edit?
+    false
+  end
+end

data/test/policies_test.rb

@@ -0,0 +1,42 @@
+require 'test_helper'
+
+class PoliciesTest < Minitest::Test
+  def setup
+    @project = Project.new
+  end
+
+  def test_symbol_conversion
+    assert_equal authorized?(:show, :project), true
+    assert_equal authorized?(:edit, :project), false
+  end
+
+  def test_symbol_conversion_without_action_argument
+    assert_equal authorized?(:project), false
+  end
+
+  def test_plural_symbol_conversion
+    assert_equal authorized?(:show, :projects), true
+    assert_equal authorized?(:edit, :projects), false
+  end
+
+  def test_plural_symbol_conversion_without_action_argument
+    assert_equal authorized?(:projects), false
+  end
+
+  def test_object_conversion
+    assert_equal authorized?(:show, @project), true
+    assert_equal authorized?(:edit, @project), false
+  end
+
+  def test_unauthorized_error_raised
+    assert_raises Policies::UnauthorizedError do
+      authorize(:edit, @project)
+    end
+  end
+
+  def test_unauthorized_error_raised_without_action_argument
+    assert_raises Policies::UnauthorizedError do
+      authorize(@project)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,18 @@
+require 'minitest/autorun'
+require 'active_support/all'
+require 'policies'
+require 'policies_test'
+require 'policies/project_policy'
+
+Project = Class.new
+
+Minitest::Test.class_eval do
+  include Policies::Methods
+end
+
+def current_user; end
+def current_role; end
+
+def action_name
+  'edit'
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: policies
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Josh Wetzel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-05-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/policies.rb
+- lib/policies/base.rb
+- lib/policies/exceptions.rb
+- lib/policies/methods.rb
+- policies.gemspec
+- test/policies/project_policy.rb
+- test/policies_test.rb
+- test/test_helper.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Authorization control
+test_files: []