action_policy 0.4.3 → 0.5.3

data/docs/debugging.md

@@ -1,55 +0,0 @@
-# Debug Helpers
-
-**NOTE:** this functionality requires two additional gems to be available in the app:
-- [unparser](https://github.com/mbj/unparser)
-- [method_source](https://github.com/banister/method_source).
-
-We usually describe policy rules using _boolean expressions_ (e.g. `A or (B and C)` where each of `A`, `B` and `C` is a simple boolean expression or predicate method).
-
-When dealing with complex policies, it could be hard to figure out which predicate/check made policy to fail.
-
-The `Policy#pp(rule)` method aims to help debug such situations.
-
-Consider a (synthetic) example:
-
-```ruby
-def feed?
-  (admin? || allowed_to?(:access_feed?)) &&
-    (user.name == "Jack" || user.name == "Kate")
-end
-
-```
-
-Suppose that you want to debug this rule ("Why does it return false?").
-You can drop a [`binding.pry`](https://github.com/deivid-rodriguez/pry-byebug) (or `binding.irb`) right at the beginning of the method:
-
-```ruby
-def feed?
-  binding.pry # rubocop:disable Lint/Debugger
-  #...
-end
-```
-
-Now, run your code and trigger the breakpoint (i.e., run the method):
-
-```
-# now you can preview the execution of the rule using the `pp` method (defined on the policy instance)
-pry> pp :feed?
-MyPolicy#feed?
-↳ (
-    admin? #=> false
-    OR
-    allowed_to?(:access_feed?) #=> true
-  )
-  AND
-  (
-    user.name == "Jack" #=> false
-    OR
-    user.name == "Kate" #=> true
-  )
-
-# you can also check other rules or methods as well
-pry> pp :admin?
-MyPolicy#admin?
-↳ user.admin? #=> false
-```

data/docs/decorators.md

@@ -1,27 +0,0 @@
-# Dealing with Decorators
-
-Ref: [action_policy#7](https://github.com/palkan/action_policy/issues/7).
-
-Since Action Policy [lookup mechanism](./lookup_chain.md) relies on the target
-record's class properties (names, methods) it could break when using with _decorators_.
-
-To make `authorize!` and other [behaviour](./behaviour.md) methods work seamlessly with decorated
-objects, you might want to _enhance_ the `policy_for` method.
-
-For example, when using the [Draper](https://github.com/drapergem/draper) gem:
-
-```ruby
-module ActionPolicy
-  module Draper
-    def policy_for(record:, **opts)
-      # From https://github.com/GoodMeasuresLLC/draper-cancancan/blob/master/lib/draper/cancancan.rb
-      record = record.model while record.is_a?(::Draper::Decorator)
-      super(record: record, **opts)
-    end
-  end
-end
-
-class ApplicationController < ActionController::Base
-  prepend ActionPolicy::Draper
-end
-```

data/docs/graphql.md

@@ -1,302 +0,0 @@
-# GraphQL integration
-
-You can use Action Policy as an authorization library for your [GraphQL Ruby](https://graphql-ruby.org/) application via the [`action_policy-graphql` gem](https://github.com/palkan/action_policy-graphql).
-
-This integration provides the following features:
-- Fields & mutations authorization
-- List and connections scoping
-- [**Exposing permissions/authorization rules in the API**](https://evilmartians.com/chronicles/exposing-permissions-in-graphql-apis-with-action-policy).
-
-## Getting Started
-
-First, add the `action_policy-graphql` gem to your Gemfile (see [installation instructions](https://github.com/palkan/action_policy-graphql#installation)).
-
-Then, include `ActionPolicy::GraphQL::Behaviour` to your base type (or any other type/mutation where you want to use authorization features):
-
-```ruby
-# For fields authorization, lists scoping and rules exposing
-class Types::BaseObject < GraphQL::Schema::Object
-  include ActionPolicy::GraphQL::Behaviour
-end
-
-# For using authorization helpers in mutations
-class Types::BaseMutation < GraphQL::Schema::Mutation
-  include ActionPolicy::GraphQL::Behaviour
-end
-
-# For using authorization helpers in resolvers
-class Types::BaseResolver < GraphQL::Schema::Resolver
-  include ActionPolicy::GraphQL::Behaviour
-end
-```
-
-## Authorization Context
-
-By default, Action Policy uses `context[:current_user]` as the `user` [authorization context](./authorization_context.md).
-
-**NOTE:** see below for more information on what's included into `ActionPolicy::GraphQL::Behaviour`.
-
-## Authorizing Fields
-
-You can add `authorize: true` option to any field (=underlying object) to protect the access (it's equal to calling `authorize! object, to: :show?`):
-
-```ruby
-# authorization could be useful for find-like methods,
-# where the object is resolved from the provided params (e.g., ID)
-field :home, Home, null: false, authorize: true do
-  argument :id, ID, required: true
-end
-
-def home(id:)
-  Home.find(id)
-end
-
-# Without `authorize: true` the code would look like this
-def home(id:)
-  Home.find(id).tap { |home| authorize! home, to: :show? }
-end
-```
-
-You can use authorization options to customize the behaviour, e.g. `authorize: {to: :preview?, with: CustomPolicy}`.
-
-By default, if a user is not authorized to access the field, an `ActionPolicy::Unauthorized` exception is raised.
-
-If you want to return a `nil` instead, you should add `raise: false` to the options:
-
-```ruby
-# NOTE: don't forget to mark your field as nullable
-field :home, Home, null: true, authorize: {raise: false}
-```
-
-You can make non-raising behaviour a default by setting a configuration option:
-
-```ruby
-ActionPolicy::GraphQL.authorize_raise_exception = false
-```
-
-You can also change the default `show?` rule globally:
-
-```ruby
-ActionPolicy::GraphQL.default_authorize_rule = :show_graphql_field?
-```
-
-If you want to perform authorization before resolving the field value, you can use `preauthorize: *` option:
-
-```ruby
-field :homes, [Home], null: false, preauthorize: {with: HomePolicy}
-
-def homes
-  Home.all
-end
-```
-
-The code above is equal to:
-
-```ruby
-field :homes, [Home], null: false
-
-def homes
-  authorize! "homes", to: :index?, with: HomePolicy
-  Home.all
-end
-```
-
-**NOTE:** we pass the field's name as the `record` to the policy rule. We assume that preauthorization rules do not depend on
-the record itself and pass the field's name for debugging purposes only.
-
-You can customize the authorization options, e.g. `authorize: {to: :preview?, with: CustomPolicy}`.
-
-**NOTE:** unlike `authorize: *` you MUST specify the `with: SomePolicy` option.
-The default authorization rule depends on the type of the field:
-
-- for lists we use `index?` (configured by `ActionPolicy::GraphQL.default_preauthorize_list_rule` parameter)
-- for _singleton_ fields we use `show?` (configured by `ActionPolicy::GraphQL.default_preauthorize_node_rule` parameter)
-
-### Class-level authorization
-
-You can use Action Policy in the class-level [authorization hooks](https://graphql-ruby.org/authorization/authorization.html) (`self.authorized?`) like this:
-
-```ruby
-class Types::Friendship < Types::BaseObject
-  def self.authorized?(object, context)
-    super &&
-      allowed_to?(
-        :show?,
-        object,
-        # NOTE: you must provide context explicitly
-        context: {user: context[:current_user]}
-      )
-  end
-end
-```
-
-## Authorizing Mutations
-
-A mutation is just a Ruby class with a single API method. There is nothing specific in authorizing mutations: from the Action Policy point of view, they are just [_behaviours_](./behaviour.md).
-
-If you want to authorize the mutation, you call `authorize!` method. For example:
-
-```ruby
-class Mutations::DestroyUser < Types::BaseMutation
-  argument :id, ID, required: true
-
-  def resolve(id:)
-    user = User.find(id)
-
-    # Raise an exception if the user has not enough permissions
-    authorize! user, to: :destroy?
-    # Or check without raising and do what you want
-    #
-    #     if allowed_to?(:destroy?, user)
-
-    user.destroy!
-
-    {deleted_id: user.id}
-  end
-end
-```
-
-## Handling exceptions
-
-The query would fail with `ActionPolicy::Unauthorized` exception when using `authorize: true` (in raising mode) or calling `authorize!` explicitly.
-
-That could be useful to handle this exception and send a more detailed error message to the client, for example:
-
-```ruby
-# in your schema file
-rescue_from(ActionPolicy::Unauthorized) do |exp|
-  raise GraphQL::ExecutionError.new(
-    # use result.message (backed by i18n) as an error message
-    exp.result.message,
-    # use GraphQL error extensions to provide more context
-    extensions: {
-      code: :unauthorized,
-      fullMessages: exp.result.reasons.full_messages,
-      details: exp.result.reasons.details
-    }
-  )
-end
-```
-
-## Scoping Data
-
-You can add `authorized_scope: true` option to a field (list or [_connection_](https://graphql-ruby.org/relay/connections.html)) to apply the corresponding policy rules to the data:
-
-```ruby
-class CityType < ::Common::Graphql::Type
-  # It would automatically apply the relation scope from the EventPolicy to
-  # the relation (city.events)
-  field :events, EventType.connection_type,
-        null: false,
-        authorized_scope: true
-
-  # you can specify the policy explicitly
-  field :events, EventType.connection_type,
-        null: false,
-        authorized_scope: {with: CustomEventPolicy}
-
-  # without the option you would write the following code
-  def events
-    authorized_scope object.events
-    # or if `with` option specified
-    authorized_scope object.events, with: CustomEventPolicy
-  end
-end
-```
-
-**NOTE:** you cannot use `authorize: *` and `authorized_scope: *` at the same time but you can combine `preauthorize: *` with `authorized_scope: *`.
-
-See the documenation on [scoping](./scoping.md).
-
-## Exposing Authorization Rules
-
-With `action_policy-graphql` gem, you can easily expose your authorization logic to the client in a standardized way.
-
-For example, if you want to "tell" the client which actions could be performed against the object you
-can use the `expose_authorization_rules` macro to add authorization-related fields to your type:
-
-```ruby
-class ProfileType < Types::BaseType
-  # Adds can_edit, can_destroy fields with
-  # AuthorizationResult type.
-
-  # NOTE: prefix "can_" is used by default, no need to specify it explicitly
-  expose_authorization_rules :edit?, :destroy?, prefix: "can_"
-end
-```
-
-**NOTE:** you can use [aliases](./aliases.md) here as well as defined rules.
-
- **NOTE:** This feature relies the [_failure reasons_](./reasons.md) and
-the [i18n integration](./i18n.md) extensions. If your policies don't include any of these,
-you won't be able to use it.
-
-Then the client could perform the following query:
-
-```gql
-{
-  post(id: $id) {
-    canEdit {
-      # (bool) true|false; not null
-      value
-      # top-level decline message ("Not authorized" by default); null if value is true
-      message
-      # detailed information about the decline reasons; null if value is true or you don't have "failure reasons" extension enabled
-      reasons {
-        details # JSON-encoded hash of the form { "event" => [:privacy_off?] }
-        fullMessages # Array of human-readable reasons
-      }
-    }
-
-    canDestroy {
-      # ...
-    }
-  }
-}
-```
-
-You can override a custom authorization field prefix (`can_`):
-
-```ruby
-ActionPolicy::GraphQL.default_authorization_field_prefix = "allowed_to_"
-```
-
-You can specify a custom field name as well (only for a single rule):
-
-```ruby
-class ProfileType < ::Common::Graphql::Type
-  # Adds can_create_post field.
-
-  expose_authorization_rules :create?, with: PostPolicy, field_name: "can_create_post"
-end
-```
-
-## Custom Behaviour
-
-Including the default `ActionPolicy::GraphQL::Behaviour` is equal to adding the following to your base class:
-
-```ruby
-class Types::BaseObject < GraphQL::Schema::Object
-  # include Action Policy behaviour and its extensions
-  include ActionPolicy::Behaviour
-  include ActionPolicy::Behaviours::ThreadMemoized
-  include ActionPolicy::Behaviours::Memoized
-  include ActionPolicy::Behaviours::Namespaced
-
-  # define authorization context
-  authorize :user, through: :current_user
-
-  # add a method helper to get the current_user from the context
-  def current_user
-    context[:current_user]
-  end
-
-  # extend the field class to add `authorize` and `authorized_scope` options
-  field_class.prepend(ActionPolicy::GraphQL::AuthorizedField)
-
-  # add `expose_authorization_rules` macro
-  include ActionPolicy::GraphQL::Fields
-end
-```
-
-Feel free to create your own behaviour by adding only the functionality you need.

data/docs/i18n.md

@@ -1,44 +0,0 @@
-# I18n Support
-
-`ActionPolicy` integrates with [`i18n`][] to support localizable `full_messages` for [reasons](./reasons.md) and the execution result's `message`:
-
-```ruby
-class ApplicationController < ActionController::Base
-  rescue_from ActionPolicy::Unauthorized do |ex|
-    p ex.result.message #=> "You do not have access to the stage"
-    p ex.result.reasons.full_messages #=> ["You do not have access to the stage"]
-  end
-end
-```
-
-The message contains a string for the _rule_ that was called, while `full_messages` contains the list of reasons, why `ActionPolicy::Unauthorized` has been raised. You can find more information about tracking failure reasons [here](./reasons.md).
-
-## Configuration
-
-`ActionPolicy` doesn't provide any localization out-of-the-box and uses "You are not authorized to perform this action" as the default message.
-
-You can add your app-level default fallback by providing the `action_policy.unauthorized` key value.
-
-When using **Rails**, all you need is to add translations to any file under the `config/locales` folder (or create a new file, e.g. `config/locales/policies.yml`).
-
-Non-Rails projets should configure [`i18n`][] gem manually:
-
-```ruby
-I18n.load_path << Dir[File.expand_path("config/locales") + "/*.yml"]
-```
-
-## Translations lookup
-
-`ActionPolicy` uses the `action_policy` scope. Specific policies translations must be stored inside the `policy` sub-scope.
-
-The following algorithm is used to find out the translation for a policy with a class `klass` and rule `rule`:
-1. Translation for `"#{klass.identifier}.#{rule}"` key, when `self.identifier =` is not specified then underscored class name without the _Policy_ suffix would be used (e.g. `GuestUserPolicy` turns into `guest_user:` scope)
-2. Repeat step 1 for each ancestor which looks like a policy (`.respond_to?(:identifier)?`) up to `ActionPolicy::Base`
-3. Use `#{rule}` key
-4. Use `en.action_policy.unauthorized` key
-5. Use a default message provided by the gem
-
-For example, given a `GuestUserPolicy` class which is inherited from `DefaultUserPolicy` and a rule `feed?`, the following list of possible translation keys would be used: `[:"action_policy.policy.guest_user.feed?", :"action_policy.policy.default_user.feed?", :"action_policy.policy.feed?", :"action_policy.unauthorized"]`
-
-
-[`i18n`]: https://github.com/svenfuchs/i18n

data/docs/index.html

@@ -1,43 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Action Policy: authorization framework for Ruby/Rails applications</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" />
-  <meta itemprop="name" content="Action Policy" />
-  <meta property="og:title" content="Action Policy" />
-  <meta name="description" content="Athorization framework for Ruby/Rails application" />
-  <meta itemprop="description" content="Authorization framework for Ruby/Rails application" />
-  <meta property="og:description" content="Authorization framework for Ruby/Rails application" />
-  <meta itemprop="image" content="http://actionpolicy.evilmartians.io/assets/images/banner.png" />
-  <meta property="og:image" content="http://actionpolicy.evilmartians.io/assets/images/banner.png" />
-  <meta name="twitter:card" content="summary_large_image" />
-  <meta name="twitter:site" content="@palkan_tula" />
-  <meta name="twitter:creator" content="@palkan_tula" />
-  <meta property="og:site_name" content="Action Policy" />
-  <meta name="keywords" content="ruby, rails, authorization, open-source" />
-  <meta name="theme-color" content="#CB2028" />
-  <link rel="stylesheet" href="assets/vue.min.css">
-  <link rel="stylesheet" href="assets/styles.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: 'action_policy',
-      repo: 'https://github.com/palkan/action_policy',
-      loadSidebar: true,
-      subMaxLevel: 3,
-      ga: 'UA-104346673-3',
-      auto2top: true,
-      search: {
-        namespace: 'action-policy'
-      }
-    }
-  </script>
-  <script src="assets/docsify.min.js"></script>
-  <script src="assets/docsify-search.js"></script>
-  <script src="assets/prism-ruby.min.js"></script>
-</body>
-</html>