resource_policy 1.0.0

data/docs/components/action_validator.md

@@ -0,0 +1,34 @@
+# ResourcePolicy::ActionValidator
+
+The `ResourcePolicy::ActionValidator` is a validator used to check the policy of a resource before performing a certain action. It helps to ensure that a user is only allowed to perform actions on a resource that they have permission to do so.
+
+## Options
+
+The `ResourcePolicy::ActionValidator` accepts two options:
+
+- `:allowed_to` (required) - Specifies the action type that needs to be checked. This can be a symbol or a string.
+- `:as` (optional) - Specifies the key that will be used to display errors. This is useful if you want to rename the attribute being validated.
+
+## Usage Example
+
+```ruby
+require 'resource_policy/action_validator'
+
+class SomeClass
+  validates :some_policy, 'resource_policy/action': { allowed_to: :create, as: :some_item }
+
+  def some_policy
+    SomePolicy.new
+  end
+end
+
+some_object = SomeClass.new
+
+if some_object.valid?
+  # No validation errors, continue with the process
+else
+  some_object.errors.messages # => { some_item: ['action "create" is not allowed'] }
+end
+```
+
+In this example, the `SomeClass` has an attribute named `some_policy` which is being validated using the `ResourcePolicy::ActionValidator`. The validator checks if the create action is allowed using the SomePolicy object. If the action is not allowed, an error message will be added to the `record.errors` object with the key `:some_item`. If the `:as` option is not provided, the key used to display the error will be the name of the attribute being validated.

data/docs/components/actions_policy.md

@@ -0,0 +1,68 @@
+# ResourcePolicy::ActionsPolicy
+
+## policy#action
+
+Actions policy allows you to define config for each action.
+
+Using `action` and `allowed` methods chain you can define conditions for each action:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.action(:read).allowed
+    c.action(:write).allowed(if: %i[admin? admin?])
+  end
+
+  def initialize(user, current_user)
+    @user, @current_user = user, current_user
+  end
+
+  private
+
+  def user_itself?
+    @user == @current_user
+  end
+
+  def admin?
+    @current_user.admin?
+  end
+end
+```
+
+If no condition is given then action will be always allowed.
+
+This config means:
+
+* `read` action is always allowed;
+* `write` action is allowed only if both `admin?` and `writable?` methods returns `true`.
+
+
+### policy#group
+
+Sometimes you might have action groups which share same conditions. In this case you can group then using `#group` method:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.group(:user_itself?) do |g|
+      g.allowed_to(:change_password)
+      g.allowed_to(:destroy, if: :admin?)
+    end
+  end
+
+  private
+
+  def admin?
+    ...
+  end
+end
+```
+
+In this case:
+
+* `change_password` will be allowed if `user_itself?` returns `true`;
+* `destroy` will be allowed if both `user_itself?` and ``admin?` returns `true`.

data/docs/components/attributes_policy.md

@@ -0,0 +1,68 @@
+# ResourcePolicy::AttributesPolicy
+
+
+### policy#attribute
+
+Attributes policy allows you to define separate attributes.
+
+Using `attribute#allowed` method you can define conditions for each attribute and for each action type like `read`, `write` and etc:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::AttributesPolicy
+
+  policy do |c|
+    c.attribute(:first_name)
+      .allowed(:read)
+      .allowed(:write, if: %i[admin? writable?])
+  end
+
+  private
+
+  def admin?
+    ...
+  end
+
+  def writable?
+    ...
+  end
+end
+```
+
+If no condition is given then action will be always allowed for given attribute.
+
+### attributes_policy#group
+
+Sometimes you might have attribute groups which share same conditions. In this case you can group then using `#group` method:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::AttributesPolicy
+
+  group(:user_itself?) do |c|
+    c.attribute(:password).allowed(:write)
+    c.attribute(:email).allowed(:read, :write)
+    c.attribute(:children).allowed(:read, if: :parent?)
+  end
+
+  def initialize(user, current_user)
+    @user, @current_user = user, current_user
+  end
+
+  private
+
+  def user_itself?
+    @user == @current_user
+  end
+
+  def parent?
+    @user.parent?
+  end
+end
+```
+
+In this case:
+
+* `password` will be allowed to `write` only if `user_itself?` returns `true`.
+* `email` will be allowed to `read` and `write` only if `user_itself?` returns `true`.
+* `children` will be allowed to `read` if both `user_itself?` **and** `parent?` returns `true`.

data/docs/components/policy.md

@@ -0,0 +1,202 @@
+# ResourcePolicy::Policy
+
+`Policy` includes both `AttributesPolicy` and `ActionsPolicy` modules. Their features are described separately, so read more there if you need more info.
+
+## Policy Configuration
+
+Here is and example how policy looks like:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.policy_target :user
+
+    c.action(:read).allowed(if: :readable?)
+
+    c.attribute(:first_name)
+      .allowed(:read, if: :readable?)
+      .allowed(:write, if: :writable?)
+  end
+
+  def initialize(user, current_user:)
+    @user = user
+    @current_user = current_user
+  end
+
+  private
+
+  def readable?
+    true
+  end
+
+  def writable?
+    true
+  end
+end
+```
+
+### policy#group
+
+Sometimes you might have action groups which share same conditions. In this case you can group then using `#group` method:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.group(:user_itself?) do |g|
+      g.action(:change_password).allowed
+      g.action(:destroy).allowed(if: :admin?)
+    end
+  end
+
+  private
+
+  def admin?
+    ...
+  end
+end
+```
+
+In this case:
+
+* `change_password` will be allowed if `user_itself?` returns `true`;
+* `destroy` will be allowed if both `user_itself?` and ``admin?` returns `true`.
+
+
+## Usage of Policy#action
+
+Suppose we have policy like this:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.action(:read).allowed # current_user can always see user
+    c.action(:write).allowed(if: :admin?) # only admin current_user can update user
+  end
+
+  def initialize(user, current_user:)
+    @user = user
+    @current_user = current_user
+  end
+
+  private
+
+  def admin?
+    @current_user.admin?
+  end
+end
+```
+
+then we can check each action like this:
+
+```ruby
+policy = UserPolicy.new(user, current_user: current_user)
+policy.action(:read).allowed? # => true
+policy.action(:write).allowed? # ... depends on `admin?` result
+```
+
+## Policy#actions_policy
+
+Another way to check each action is to use `actions_policy` object like this:
+
+```ruby
+policy = UserPolicy.new(user, current_user: current_user)
+actions_policy = policy.actions_policy
+actions_policy.read.allowed? # => true
+actions_policy.write.allowed? # ... depends on `admin?` result
+```
+
+## Usage of Policy#attribute
+
+Suppose we have policy like this:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.attribute(:email)
+      .allowed(:read) # current_user can always view user.email
+      .allowed(:write, if: :admin?) # only admin current_user can change email
+  end
+
+  def initialize(user, current_user:)
+    @user = user
+    @current_user = current_user
+  end
+
+  private
+
+  def admin?
+    @current_user.admin?
+  end
+end
+```
+
+then we can check each attribute like this:
+
+```ruby
+policy = UserPolicy.new(user, current_user: current_user)
+policy.attribute(:email).allowed_to?(:change) # => false - no such rule
+policy.attribute(:email).readable? # => true
+policy.attribute(:email).writable? # ... depends on `admin?` result
+```
+
+## Usage of Policy#attributes_policy
+
+Another way to check each action is to use `attributes_policy` object like this:
+
+```ruby
+policy = UserPolicy.new(user, current_user: current_user)
+attributes_policy = policy.attributes_policy
+
+attributes_policy.email.allowed_to?(:change) # => false - no such rule
+attributes_policy.email.readable? # same as `allowed_to?(:read)`
+attributes_policy.email.writable? # same as `allowed_to?(:write)`
+```
+
+## Usage of Policy#protected_resource
+
+Policy provides `#protected_resource` method which returns wrapped model instance and does not allow to view fields which current_user does not have access to. You must define `policy_target` in order to be able to use `protected_resource` feature
+
+Usage example:
+
+```ruby
+class UserPolicy
+  include ResourcePolicy::Policy
+
+  policy do |c|
+    c.policy_target(:user) # method name which returns target
+    c.attribute(:id).allowed(:read) # visible to all
+    c.attribute(:salary).allowed(:read, if: :admin?) # only visible to admin
+  end
+
+  def initialize(user, current_user:)
+    @user = user
+    @current_user = current_user
+  end
+
+  def admin?
+    @current_user.admin?
+  end
+end
+```
+
+Now you can protect `user` like this:
+
+```ruby
+current_user.admin? #=> false
+
+user = User.find(1337)
+user.id #=> 1337
+user.email #=> "john.doe@example.com"
+
+policy = UserPolicy.new(user, current_user: current_user)
+policy.protected_resource.id #=> 1337
+policy.protected_resource.email # nil
+```

data/docs/index.html

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="https://unpkg.com/docsify/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    function parseQueryString (queryString) {
+      var params = {};
+      var temp;
+      // Split into key/value pairs
+      queries = queryString.split("&");
+      // Convert the array of strings into an object
+      for (var i = 0, l = queries.length; i < l; i++ ) {
+        temp = queries[i].split('=');
+        params[temp[0]] = temp[1];
+      }
+      return params;
+    };
+
+    function getJsonFromUrl() {
+      return parseQueryString(location.search.substr(1));
+    }
+
+    window.$docsify = {
+      auto2top: true,
+      name: 'ResourcePolicy',
+      repo: 'https://github.com/samesystem/resource_policy',
+      subMaxLevel: 3,
+      loadSidebar: true,
+      formatUpdated: '{MM}/{DD} {HH}:{mm}',
+      branchBasePath: 'https://raw.githubusercontent.com/samesystem/resource_policy/',
+      plugins: [
+        function (hook, vm) { // reasign any config value by param attribute
+          Object.assign(window.$docsify, getJsonFromUrl());
+        },
+
+        function (hook, vm) { // allow to change branch
+          if (!window.$docsify.branchBasePath || !window.$docsify.branch) {
+            return;
+          }
+
+          var branch = window.$docsify.branch;
+          var basePath = window.$docsify.branchBasePath + branch;
+          window.$docsify.basePath = basePath;
+        },
+
+        function (hook, vm) { // add edit page link
+          hook.beforeEach(function (html) {
+            var branch = window.$docsify.branch || 'master'
+            var url = 'https://github.com/samesystem/resource_policy/edit/' + branch + '/docs/' + vm.route.file
+            var editHtml = '[:memo: Edit Document](' + url + ')\n'
+            return html
+              + '\n\n----\n\n'
+              + editHtml
+          })
+        }
+      ]
+    }
+  </script>
+  <script src="https://unpkg.com/docsify/lib/docsify.js"></script>
+  <script src="https://unpkg.com/docsify/lib/plugins/search.min.js"></script>
+</body>
+</html>

data/lib/resource_policy/policy/action_policy_configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ResourcePolicy
+  module Policy
+    # @private
+    #
+    # Stores configuration for action policy.
+    class ActionPolicyConfiguration
+      attr_reader :name
+
+      def initialize(name, policy_configuration:)
+        @name = name.to_sym
+        @policy_configuration = policy_configuration
+        @extra_conditions = []
+        @configured = false
+      end
+
+      def allowed(options = {})
+        @extra_conditions = (@extra_conditions + Array(options[:if])).uniq
+        @configured = true
+        self
+      end
+
+      def conditions
+        policy_configuration.group_conditions + @extra_conditions
+      end
+
+      def configured?
+        @configured
+      end
+
+      private
+
+      attr_reader :policy_configuration
+    end
+  end
+end

data/lib/resource_policy/policy/actions_policy/action_policy.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ResourcePolicy
+  module Policy
+    module ActionsPolicy
+      # Contains information about single action
+      class ActionPolicy
+        attr_reader :name
+
+        def initialize(name, policy:)
+          @name = name.to_sym
+          @policy = policy
+        end
+
+        def allowed?
+          return @allowed if defined?(@allowed)
+
+          conditions = policy_config.action(name).conditions
+          @allowed = conditions.all? { |condition| policy.send(condition) }
+        end
+
+        private
+
+        attr_reader :policy
+
+        def policy_config
+          policy.class.policy
+        end
+      end
+    end
+  end
+end

data/lib/resource_policy/policy/actions_policy/actions_policy_model.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ResourcePolicy
+  module Policy
+    module ActionsPolicy
+      # Class which isolates methods defined via actions_policy config
+      class ActionsPolicyModel
+        require 'resource_policy/policy/actions_policy/action_policy'
+
+        def initialize(policy)
+          @policy = policy
+          @policy_item_by_name ||= {}
+        end
+
+        def method_missing(method_name)
+          return super unless config.actions.key?(method_name.to_sym)
+
+          policy_item(method_name.to_sym)
+        end
+
+        def respond_to_missing?(method_name, *args)
+          config.actions.key?(method_name.to_sym) || super
+        end
+
+        private
+
+        attr_reader :policy
+
+        def config
+          policy.class.policy
+        end
+
+        def policy_item(name)
+          @policy_item_by_name[name] ||= ActionPolicy.new(name, policy: policy)
+        end
+      end
+    end
+  end
+end

data/lib/resource_policy/policy/actions_policy.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ResourcePolicy
+  module Policy
+    # Allows to define actions policy using configuration block.
+    #
+    # Usage example:
+    #
+    # class SomeModelPolicy
+    #   include Policy::ActionsPolicy
+    #
+    #   policy do |c|
+    #     c.action(:create).allowed(if: :current_user_is_admin?)
+    #   end
+    #
+    #   private
+    #
+    #   def current_user_is_admin?
+    #      current_user.admin?
+    #   end
+    #   ...
+    # end
+    module ActionsPolicy
+      require 'resource_policy/policy/actions_policy/actions_policy_model'
+
+      def actions_policy
+        @actions_policy ||= ActionsPolicyModel.new(self)
+      end
+
+      def action(name)
+        actions_policy.public_send(name) if actions_policy.respond_to?(name)
+      end
+    end
+  end
+end

data/lib/resource_policy/policy/attributes_policy/attribute_configuration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ResourcePolicy
+  module Policy
+    module AttributesPolicy
+      # @private
+      #
+      # Allows to define policy for single attribute
+      class AttributeConfiguration
+        DEFAULT_OPTIONS = { if: [] }.freeze
+        ALLOWED_ACTIONS = %i[read write].freeze
+
+        attr_reader :name
+
+        def initialize(name, policy_configuration:)
+          @name = name
+          @allowed_actions = {}
+          @policy_configuration = policy_configuration
+        end
+
+        def initialize_copy(other)
+          super
+          @allowed_actions = @allowed_actions.dup.transform_values(&:dup)
+        end
+
+        def allowed(*action_types, **options)
+          action_types.map(&:to_sym).each do |action|
+            allowed_actions[action] = merged_action_options(action, options)
+          end
+          self
+        end
+
+        def conditions_for(action)
+          action_conditions = allowed_actions.fetch(action, {}).fetch(:if, [])
+          (action_conditions + policy_configuration.group_conditions).uniq
+        end
+
+        def configured?
+          !defined_actions.empty?
+        end
+
+        def defined_actions
+          allowed_actions.keys
+        end
+
+        def defined_action?(action_name)
+          defined_actions.include?(action_name.to_sym)
+        end
+
+        def merge(other)
+          dup.tap do |new_attribute|
+            other.defined_actions.each do |action|
+              new_attribute.allowed(action, if: other.conditions_for(action))
+            end
+          end
+        end
+
+        private
+
+        attr_reader :allowed_actions, :policy_configuration
+
+        def merged_action_options(action, new_options)
+          previous_options = allowed_actions[action]
+          options = previous_options || DEFAULT_OPTIONS.dup
+          options[:if] += Array(new_options[:if])
+          options[:if].uniq!
+          options
+        end
+      end
+    end
+  end
+end

data/lib/resource_policy/policy/attributes_policy/attribute_policy.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ResourcePolicy
+  module Policy
+    module AttributesPolicy
+      # @private
+      #
+      # Stores information about access level of single attribute.
+      class AttributePolicy
+        def initialize(attribute_config, policy:)
+          @policy = policy
+          @attribute_config = attribute_config
+        end
+
+        def name
+          attribute_config.name
+        end
+
+        def readable?
+          allowed_to?(:read)
+        end
+
+        def writable?
+          allowed_to?(:write)
+        end
+
+        def allowed_to?(access_level)
+          @allowed_to ||= {}
+          level_name = access_level.to_sym
+
+          return @allowed_to[level_name] if @allowed_to.key?(level_name)
+
+          @allowed_to[level_name] = fetch_allowed_to(level_name)
+        end
+
+        private
+
+        attr_reader :policy, :attribute_config
+
+        def fetch_allowed_to(access_level)
+          return false unless attribute_config.defined_actions.include?(access_level)
+
+          conditions = attribute_config.conditions_for(access_level)
+          conditions.all? { |condition| policy.send(condition) }
+        end
+      end
+    end
+  end
+end