action_policy 0.0.1 → 0.1.0

data/docs/namespaces.md

@@ -0,0 +1,69 @@
+# Namespaces
+
+Action Policy can lookup policies with respect to the current execution _namespace_ (i.e., authorization class module).
+
+Consider an example:
+
+```ruby
+module Admin
+  class UsersController < ApplictionController
+    def index
+      # uses Admin::UserPolicy if any, otherwise fallbacks to UserPolicy
+      authorize!
+    end
+  end
+end
+```
+
+Module nesting is also supported:
+
+```ruby
+module Admin
+  module Client
+    class UsersController < ApplictionController
+      def index
+        # lookup for Admin::Client::UserPolicy -> Admin::UserPolicy -> UserPolicy
+        authorize!
+      end
+    end
+  end
+end
+```
+
+**NOTE**: to support namespaced lookup for non-inferrable resources,
+you should specify `policy_name` at a class level (instead of `policy_class`, which doesn't take namespaces into account):
+
+```ruby
+class Guest < User
+  def self.policy_name
+    "UserPolicy"
+  end
+end
+```
+
+**NOTE**: by default, we use class's name as a policy name; so, for namespaced resources, the namespace part is also included:
+
+```ruby
+class Admin
+  class User
+  end
+end
+
+# search for Admin::UserPolicy, but not for UserPolicy
+authorize! Admin::User.new
+```
+
+You can access the current authorization namespace through `authorization_namespace` method.
+
+You can also define your own namespacing logic by overriding `authorization_namespace`:
+
+```ruby
+def authorization_namespace
+  return ::Admin if current_user.admin?
+  return ::Staff if current_user.staff?
+  # fallback to current namespace
+  super
+end
+```
+
+**NOTE**: namespace support is an extension for `ActionPolicy::Behaviour` and could be included with `ActionPolicy::Behaviours::Namespaced` (included into Rails controllers and channel integrations by default).

data/docs/non_rails.md

@@ -0,0 +1,29 @@
+# Using with Ruby applications
+
+Action Policy is designed to be independent of any framework and does not have specific dependencies on Ruby on Rails.
+You can [write your policies](writing_policies.md) for non-Rails applications the same way as you would do for Rails applications.
+
+In order to have `authorize!` / `allowed_to?` methods, you will have to include `ActionPolicy::Behaviour` into your class (where you want to perform authorization):
+
+```ruby
+class PostUpdateAction
+  include ActionPolicy::Behaviour
+
+  # provide authorization subject (performer)
+  authorize :user
+
+  attr_reader :user
+
+  def initialize(user)
+    @user = user
+  end
+
+  def call(post, params)
+    authorize! post, to: :update?
+
+    post.update!(params)
+  end
+end
+```
+
+`ActionPolicy::Behaviour` provides `authorize` class-level method to configure [authorization context](authorization_context.rb) and two instance-level methods: `authorize!` and `allowed_to?`.

data/docs/pre_checks.md

@@ -0,0 +1,57 @@
+# Pre-Checks
+
+Consider a typical situation when you start most—or even all—of your rules with the same predicates.
+
+For example, when you have a super-user role in the application:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  def show?
+    user.super_admin? || record.published
+  end
+
+  def update?
+    user.super_admin? || (user.id == record.user_id)
+  end
+
+  # more rules
+end
+```
+
+Action Policy allows you to extract the common parts from rules into _pre-checks_:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  pre_check :allow_admins
+
+  def show?
+    record.published
+  end
+
+  def update?
+    user.id == record.user_id
+  end
+
+  private
+
+  def allow_admins
+    allow! if user.super_admin?
+  end
+end
+```
+
+Pre-checks act like _callbacks_: you can add multiple pre-checks, specify `except` and `only` options, and skip already defined pre-checks if necessary:
+
+```ruby
+class UserPolicy < ApplicationPolicy
+  skip_pre_check :allow_admins, only: :destroy?
+
+  def destroy?
+    user.admin? && !record.admin?
+  end
+end
+```
+
+To halt the authorization process within a pre-check, you must return either `allow!` or `deny!` call value. When any other value is returned, the pre-check is ignored, and the rule is called (or next pre-check).
+
+**NOTE**: pre-checks are available only if you inherit from `ActionPolicy::Base` or include `ActionPolicy::Policy::PreCheck` into your `ApplicationPolicy`.

data/docs/quick_start.md

@@ -0,0 +1,102 @@
+# Quick Start
+
+## Installation
+
+To install Action Policy with RubyGems:
+
+```ruby
+gem install action_policy
+```
+
+Or add this line to your application's `Gemfile`:
+
+```ruby
+gem "action_policy"
+```
+
+And then execute:
+
+    $ bundle
+
+## Basic usage
+
+The core component of Action Policy is a _policy class_. Policy class describes how you control access to resources.
+
+We suggest that you have a separate policy class for each resource and encourage you to follow the conventions:
+- put policies into the `app/policies` folder (when using with Rails);
+- name policies using the corresponding resource name (model name) with a `Policy` suffix, e.g. `Post -> PostPolicy`;
+- name rules using a predicate form of the corresponding activity (typically, a controller's action), e.g. `PostsController#update -> PostsPolicy#update?`.
+
+We also recommend to use an application-specific `ApplicationPolicy` with a global configuration to inherit from:
+
+```ruby
+class ApplicationPolicy < ActionPolicy::Base
+end
+```
+
+**NOTE:** it is not necessary to inherit from `ActionPolicy::Base`; instead, you can [construct basic policy](custom_policy.md) choosing only the components you need.
+
+Consider a simple example:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  # everyone can see any post
+  def show?
+    true
+  end
+
+  def update?
+    # `user` is a performing subject,
+    # `record` is a target object (post we want to update)
+    user.admin? || (user.id == record.user_id)
+  end
+end
+```
+
+Now you can easily add authorization to your Rails\* controller:
+
+```ruby
+class PostsController < ApplicationController
+  def update
+    @post = Post.find(params[:id])
+    authorize! @post
+
+    if @post.update(post_params)
+      redirect_to @post
+    else
+      render :edit
+    end
+  end
+end
+```
+
+\* See [Non-Rails Usage](non_rails.md) on how to add `authorize!` to any Ruby project.
+
+In the above case, Action Policy automatically infers a policy class and a rule to verify access: `@post -> Post -> PostPolicy`, rule is inferred from the action name (`update -> update?`), and `current_user` is used as `user` within the policy by default (read more about [authorization context](authorization_context.md)).
+
+When authorization is successful (i.e., the corresponding rule returns `true`), nothing happens, but in case of an authorization failure `ActionPolicy::Unauthorized` error is raised.
+
+There is also an `allowed_to?` method which returns `true` or `false` and could be used, for example, in views:
+
+```erb
+<% @posts.each do |post| %>
+  <li><%= post.title %>
+    <% if allowed_to?(:edit?, post) %>
+      = link_to "Edit", post
+    <% end %>
+  </li>
+<% end %>
+```
+
+Although Action Policy tries to [infer the corresponding policy class](policy_lookup.md) and rule itself, there could be a situation when you want to specify those values explicitly:
+
+```ruby
+# specify the rule to verify access
+authorize! @post, to: :update?
+
+# specify policy class
+authorize! @post, with: CustomPostPolicy
+
+# or
+allowed_to? :edit?, @post, with: CustomPostPolicy
+```

data/docs/rails.md

@@ -0,0 +1,110 @@
+# Using with Rails
+
+Action Policy seamlessly integrates Ruby on Rails applications seamlessly.
+
+In most cases, you do not have to do anything except writing policy files and adding `authorize!` calls.
+
+## Controllers integration
+
+Action Policy assumes that you have a `current_user` method which specifies the current authenticated subject (`user`).
+
+You can turn off this behaviour by setting `config.action_policy.controller_authorize_current_user = false` in `application.rb`, or override it:
+
+```ruby
+class ApplicationController < ActionController::Base
+  authorize :my_current_user, as: :user
+end
+```
+
+> Read more about [authorization context](authorization_context.md).
+
+In case you don't want to include Action Policy to controllers at all,
+you can turn disable the integration by setting `config.action_policy.auto_inject_into_controller = false` in `application.rb`.
+
+### `verify_authorized` hooks
+
+Usually, you need all of your actions to be authorized. Action Policy provides a controller hook which ensures that an `authorize!` call has been made during the action:
+
+```ruby
+class ApplicationController < ActionController::Base
+  # adds an after_action callback to verify
+  # that `authorize!` has been called.
+  verify_authorized
+
+  # you can also pass additional options,
+  # like with a usual callback
+  verify_authorized except: :index
+end
+```
+
+You can skip this check when necessary:
+
+```ruby
+class PostsController < ApplicationController
+  skip_verify_authorized only: :show
+end
+```
+
+When an unauthorized action is encountered, the `ActionPolicy::UnauthorizedAction` error is raised.
+
+### Resource-less `authorize!`
+
+You can also call `authorize!` without a resource specified.
+In that case, Action Policy tries to infer the resource class from the controller name:
+
+```ruby
+class PostsController < ApplicationPolicy
+  def index
+    # Uses Post class as a resource implicitly.
+    # NOTE: it just calls `controller_name.classify.safe_constantize`
+    authorize!
+  end
+end
+```
+
+### Usage with `API` and `Metal` controllers
+
+Action Policy is only included into `ActionController::Base`. If you want to use it with other base Rails controllers, you have to include it manually:
+
+```ruby
+class ApiController < ApplicationController::API
+  include ActionPolicy::Controller
+
+  # NOTE: you have to provide authorization context manually as well
+  authorize :current_user, as: :user
+end
+```
+
+## Channels integration
+
+Action Policy also integrates with Action Cable to help you authorize your channels actions:
+
+```ruby
+class ChatChannel < ApplicationCable::Channel
+  def follow(data)
+    chat = Chat.find(data["chat_id"])
+
+    # Verify against ChatPolicy#show? rule
+    authorize! chat, to: :show?
+    stream_from chat
+  end
+end
+```
+
+Action Policy assumes that you have `current_user` as a connection identifier.
+
+You can turn off this behaviour by setting `config.action_policy.channel_authorize_current_user = false` in `application.rb`, or override it:
+
+```ruby
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+    # assuming that identifier is called `user`
+    authorize :user
+  end
+end
+```
+
+> Read more about [authorization context](authorization_context.md).
+
+In case you do not want to include Action Policy to channels at all,
+you can disable the integration by setting `config.action_policy.auto_inject_into_channel = false` in `application.rb`.

data/docs/reasons.md

@@ -0,0 +1,67 @@
+# Failure Reasons
+
+When you have complex policy rules, it could be helpful to have an ability to define an exact reason for why a specific authorization was rejected.
+
+It is especially helpful when you compose policies (i.e., use one policy within another).
+
+Action Policy allows you to track failed `allowed_to?` checks in your rules.
+
+Consider an example:
+
+```ruby
+class ApplicantPolicy < ApplicationPolicy
+  def show?
+    user.has_permission?(:view_applicants) &&
+      allowed_to?(:show?, object.stage)
+  end
+end
+```
+
+When `ApplicantPolicy#show?` check fails, the exception has the `reasons` object, which contains additional information about the failure:
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from ActionPolicy::Unauthorized do |ex|
+    p ex.reasons.messages #=> { stage: [:show?] }
+  end
+end
+```
+
+You can also wrap _local_ rules into `allowed_to?` to populate reasons:
+
+```ruby
+class ApplicantPolicy < ApplicationPolicy
+  def show?
+    allowed_to?(:view_applicants?) &&
+      allowed_to?(:show?, object.stage)
+  end
+
+  def view_applicants?
+    user.has_permission?(:view_applicants)
+  end
+end
+
+# then the reasons object could be
+p ex.reasons.messages #=> { applicant: [:view_applicants?] }
+
+# or
+p ex.reasons.messages #=> { stage: [:show?] }
+```
+
+**What is the point of failure reasons?**
+
+First, you can provide a user with helpful feedback. For example, in the above scenario, when the reason is `ApplicantPolicy#view_applicants?`, you could show the following message:
+
+```
+You don't have enough permissions to view applicants.
+Please, ask your manager to update your role.
+```
+
+And when the reason is `StagePolicy#show?`:
+
+```
+You don't have access to the stage XYZ.
+Please, ask your manager to grant access to this stage.
+```
+
+Much more useful than just showing "You are not authorized to perform this action," isn't it?

data/docs/testing.md

@@ -0,0 +1,116 @@
+# Testing
+
+Authorization is one of the crucial parts of your application. Hence, it should be thoroughly tested (that is the place where 100% coverage makes sense).
+
+When you use policies for authorization, it is possible to split testing into two parts:
+- Test that **the required authorization is performed** within your authorization layer (controller, channel, etc.);
+- Test the policy class itself.
+
+## Testing authorization
+
+To test the act of authorization you have to make sure that the `authorize!` method is called with the appropriate arguments.
+
+Action Policy provides tools for such kind of testing for Minitest and RSpec.
+
+### Minitest
+
+Include `ActionPolicy::TestHelper` to your test class and you'll be able to use
+`assert_authorized_to` assertion:
+
+```ruby
+# in your controller
+class PostsController < ApplicationController
+  def update
+    @post = Post.find(params[:id])
+    authorize! @post
+    if @post.update(post_params)
+      redirect_to @post
+    else
+      render :edit
+    end
+  end
+end
+
+# in your test
+require "action_policy/test_helper"
+
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  include ActionPolicy::TestHelper
+
+  test "update is authorized" do
+    sign_in users(:john)
+
+    post = posts(:example)
+
+    assert_authorized_to(:update?, post, with: PostPolicy) do
+      patch :update, id: post.id, name: "Bob"
+    end
+  end
+end
+```
+
+You can omit the policy (then it would be inferred from the target):
+
+```ruby
+assert_authorized_to(:update?, post) do
+  patch :update, id: post.id, name: "Bob"
+end
+```
+
+### RSpec
+
+Add the following to your `rails_helper.rb` (or `spec_helper.rb`):
+
+```ruby
+require "action_policy/rspec"
+```
+
+Now you can use `be_authorized_to` matcher:
+
+```ruby
+describe PostsController do
+  subject { patch :update, id: post.id, params: params }
+
+  it "is authorized" do
+    expect { subject }.to be_authorized_to(:update?, post)
+      .with(PostPolicy)
+  end
+end
+```
+
+If you omit `.with(PostPolicy)` then the inferred policy for the target (`post`) would be used.
+
+## Testing policies
+
+You can test policies as plain-old Ruby classes, no special tooling is required.
+
+Consider an RSpec example:
+
+```ruby
+describe PostPolicy do
+  let(:user) { build_stubbed(:user) }
+  let(:post) { build_stubbed(:post) }
+
+  let(:policy) { described_class.new(post, user: user) }
+
+  describe "#update?" do
+    subject { policy.update? }
+
+    it "returns false when the user is not admin nor author" do
+      is_expected.to eq false
+    end
+
+    context "when the user is admin" do
+      let(:user) { build_stubbed(:user, :admin) }
+
+      it { is_expected.to eq true }
+    end
+
+    context "when the user is an author" do
+      let(:post) { build_stubbed(:post, user: user) }
+
+      it { is_expected.to eq true }
+    end
+  end
+end
+```