action_policy 0.4.0 → 0.5.0

data/docs/rails.md

@@ -1,120 +0,0 @@
-# Using with Rails
-
-Action Policy seamlessly integrates with Ruby on Rails applications.
-
-In most cases, you do not have to do anything except writing policy files and adding `authorize!` calls.
-
-**NOTE:** both controllers and channels extensions are built on top of the Action Policy [behaviour](./behaviour.md) mixin.
-
-## Generators
-
-Action Policy provides a couple of useful Rails generators:
-
-- `rails g action_policy:install` — adds `app/policies/application_policy.rb` file
-- `rails g action_policy:policy MODEL_NAME` — adds a policy file and a policy test file for a given model (also creates an `application_policy.rb` if it's missing)
-
-## 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 :user, through: :my_current_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`,
-    # you can override this by defining `implicit_authorization_target` method.
-    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 :user, through: :current_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

@@ -1,120 +0,0 @@
-# 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) or want
-to expose permissions to client applications (see [GraphQL](./graphql)).
-
-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 `result` object, which in its turn contains additional information about the failure (`reasons`):
-
-```ruby
-class ApplicationController < ActionController::Base
-  rescue_from ActionPolicy::Unauthorized do |ex|
-    p ex.result.reasons.details #=> { stage: [:show?] }
-
-    # or with i18n support
-    p ex.result.reasons.full_messages #=> ["You do not have access to the stage"]
-  end
-end
-```
-
-The reason key is the corresponding policy [identifier](writing_policies.md#identifiers).
-
-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.result.reasons.details #=> { applicant: [:view_applicants?] }
-
-# or
-p ex.result.reasons.details #=> { stage: [:show?] }
-```
-
-## Detailed Reasons
-
-You can provide additional details to your failure reasons by using a `details: { ... }` option:
-
-```ruby
-class ApplicantPolicy < ApplicationPolicy
-  def show?
-    allowed_to?(:show?, object.stage)
-  end
-end
-
-class StagePolicy < ApplicationPolicy
-  def show?
-    # Add stage title to the failure reason (if any)
-    # (could be used by client to show more descriptive message)
-    details[:title] = record.title
-
-    # then perform the checks
-    user.stages.where(id: record.id).exists?
-  end
-end
-
-# when accessing the reasons
-p ex.result.reasons.details #=> { stage: [{show?: {title: "Onboarding"}] }
-```
-
-**NOTE**: when using detailed reasons, the `details` array contains as the last element
-a hash with ALL details reasons for the policy (in a form of `<rule> => <details>`).
-
-The additional details are especially helpful when combined with localization, 'cause you can you them as interpolation data source for your translations. For example, for the above policy:
-
-```yml
-en:
-  action_policy:
-    policy:
-      stage:
-        show?: "The %{title} stage is not accessible"
-```
-
-And then when you call `full_messages`:
-
-```ruby
-p ex.result.reasons.full_messages #=> The Onboarding stage is not accessible
-```
-
-**P.S. What is the point of failure reasons?**
-
-Failure reasons helps you to write _actionable_ error messages, i.e. to 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/scoping.md

@@ -1,255 +0,0 @@
-# Scoping
-
-By _scoping_ we mean an ability to use policies to _scope data_ (or _filter/modify/transform/choose-your-verb_).
-
-The most common situation is when you want to _scope_ ActiveRecord relations depending
-on the current user permissions. Without policies it could look like this:
-
-```ruby
-class PostsController < ApplicationController
-  def index
-    @posts =
-      if current_user.admin?
-        Post.all
-      else
-        Post.where(user: current_user)
-      end
-  end
-end
-```
-
-That's a very simplified example. In practice scoping rules might be more complex, and it's likely that we would use them in multiple places.
-
-Action Policy allows you to define scoping rules within a policy class and use them with the help of `authorized_scope` method (`authorized` alias is also available):
-
-```ruby
-class PostsController < ApplicationController
-  def index
-    @posts = authorized_scope(Post.all)
-  end
-end
-
-class PostPolicy < ApplicationPolicy
-  relation_scope do |relation|
-    next relation if user.admin?
-    relation.where(user: user)
-  end
-end
-```
-
-## Define scopes
-
-To define scope you should use either `scope_for` or `smth_scope` methods in your policy:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  # define a scope of a `relation` type
-  scope_for :relation do |relation|
-    relation.where(user: user)
-  end
-
-  # define a scope of `my_data` type,
-  # which acts on hashes
-  scope_for :my_data do |data|
-    next data if user.admin?
-    data.delete_if { |k, _| SENSITIVE_KEYS.include?(k) }
-  end
-end
-```
-
-Scopes have _types_: different types of scopes are meant to be applied to different data types.
-
-You can specify multiple scopes (_named scopes_) for the same type providing a scope name:
-
-```ruby
-class EventPolicy < ApplictionPolicy
-  scope_for :relation, :own do |relation|
-    relation.where(owner: user)
-  end
-end
-```
-
-When the second argument is not specified, the `:default` is implied as the scope name.
-
-Also, there are cases where it might be easier to add options to existing scope than create a new one.
-
-For example, if you use soft-deletion and your logic inside a scope depends on if deleted records are included, you can add `with_deleted` option:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  scope_for :relation do |relation, with_deleted: false|
-    rel = some_logic(relation)
-    with_deleted ? rel.with_deleted : rel
-  end
-end
-```
-
-You can add as many options as you want:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  scope_for :relation do |relation, with_deleted: false, magic_number: 42, some_required_option:|
-    # Your code
-  end
-end
-```
-## Apply scopes
-
-Action Policy behaviour (`ActionPolicy::Behaviour`) provides an `authorized` method which allows you to use scoping:
-
-```ruby
-class PostsController < ApplicationController
-  def index
-    # The first argument is the target,
-    # which is passed to the scope block
-    #
-    # The second argument is the scope type
-    @posts = authorized_scope(Post, type: :relation)
-    #
-    # For named scopes provide `as` option
-    @events = authorized_scope(Event, type: :relation, as: :own)
-    #
-    # If you want to specify scope options provide `scope_options` option
-    @events = authorized_scope(Event, type: :relation, scope_options: {with_deleted: true})
-  end
-end
-```
-
-You can also specify additional options for policy class inference (see [behaviour docs](behaviour)). For example, to explicitly specify the policy class use:
-
-```ruby
-@posts = authorized_scope(Post, with: CustomPostPolicy)
-```
-
-## Using scopes within policy
-
-You can also use scopes within policy classes using the same `authorized_scope` method.
-For example:
-
-```ruby
-relation_scope(:edit) do |scope|
-  teachers = authorized_scope(Teacher.all, as: :edit)
-  scope
-    .joins(:teachers)
-    .where(teacher_id: teachers)
-end
-```
-
-## Using scopes explicitly
-
-To use scopes without including Action Policy [behaviour](behaviour)
-do the following:
-
-```ruby
-# initialize policy
-policy = ApplicantPolicy.new(user: user)
-# apply scope
-policy.apply_scope(User.all, type: :relation)
-```
-
-## Scope type inference
-
-Action Policy could look up a scope type if it's not specified and if _scope matchers_ were configured.
-
-Scope matcher is an object that implements `#===` (_case equality_) or a Proc. You can define it within a policy class:
-
-```ruby
-class ApplicationPolicy < ActionPolicy::Base
-  scope_matcher :relation, ActiveRecord::Relation
-
-  # use Proc to handle AR models classes
-  scope_matcher :relation, ->(target) { target < ActiveRecord::Base }
-
-  scope_matcher :custom, MyCustomClass
-end
-```
-
-Adding a scope matcher also adds a DSL to define scope rules (just a syntax sugar):
-
-```ruby
-class ApplicationPolicy < ActionPolicy::Base
-  scope_matcher :relation, ActiveRecord::Relation
-
-  # now you can define scope rules like this
-  relation_scope { |relation| relation }
-end
-```
-
-When `authorized_scope` is called without the explicit scope type, Action Policy uses matchers (in the order they're defined) to infer the type.
-
-## Rails integration
-
-Action Policy provides a couple of _scope matchers_ out-of-the-box for Active Record relations and Action Controller paramters.
-
-### Active Record scopes
-
-Scope type `:relation` is automatically applied to the object of `ActiveRecord::Relation` type.
-
-To define Active Record scopes you can use `relation_scope` macro (which is just an alias for `scope :relation`) in your policy:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  # Equals `scope_for :active_record_relation do ...`
-  relation_scope do |scope|
-    if super_user? || admin?
-      scope
-    else
-      scope.joins(:accesses).where(accesses: {user_id: user.id})
-    end
-  end
-
-  # define named scope
-  relation_scope(:own) do |scope|
-    next scope.none if user.guest?
-    scope.where(user: user)
-  end
-end
-```
-
-**NOTE:** the `:active_record_relation` scoping is used if and only if an `ActiveRecord::Relation` is passed to `authorized`:
-
-```ruby
-def index
-  # BAD: Post is not a relation; raises an exception
-  @posts = authorized_scope(Post)
-
-  # GOOD:
-  @posts = authorized_scope(Post.all)
-end
-```
-
-### Action Controller parameters
-
-Use scopes of type `:params` if your strong parameters filterings depend on the current user:
-
-```ruby
-class UserPolicy < ApplicationPolicy
-  # Equals to `scope_for :action_controller_params do ...`
-  params_filter do |params|
-    if user.admin?
-      params.permit(:name, :email, :role)
-    else
-      params.permit(:name)
-    end
-  end
-
-  params_filter(:update) do |params|
-    params.permit(:name)
-  end
-end
-
-class UsersController < ApplicationController
-  def create
-    # Call `authorized_scope` on `params` object
-    @user = User.create!(authorized_scope(params.require(:user)))
-    # Or you can use `authorized` alias which fits this case better
-    @user = User.create!(authorized(params.require(:user)))
-    head :ok
-  end
-
-  def update
-    @user.update!(authorized_scope(params.require(:user), as: :update))
-    head :ok
-  end
-end
-```