consent 1.0.1 → 2.0.0

data/docs/README.md

@@ -0,0 +1,355 @@
+# Consent [![Build Status](https://travis-ci.org/powerhome/consent.svg?branch=master)](https://travis-ci.org/powerhome/consent)
+
+## What is Consent
+
+Consent makes defining permissions easier by providing a clean, concise DSL for authorization
+so that all abilities do not have to be in your `Ability` class.
+
+Also, Consent adds an `Authorizable` model, so that you can easily grant permissions to your
+ActiveRecord models.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'consent'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install consent
+
+Then, require the engine in your `application.rb`
+
+```ruby
+require "active_record/railtie"
+require "consent/engine"
+```
+
+If you wish to use the activerecord adapter (`accessible_by` and `accessible_through`), you must load `active_record/railtie` before loading the `consent/engine`.
+
+### Install and run the migrations
+
+Copy and execute the migrations:
+
+    $ rails consent_engine:install:migrations
+    $ rails db:migrate
+
+This will create the `consent_histories` and `consent_permissions` tables. If you want to use a different table prefix, you should set `Consent.table_name_prefix =` before you execute the migrations. I.e.:
+
+```ruby
+# config/initializers/consent.rb
+
+require "consent"
+
+Consent.table_name_prefix = "my_app_"
+```
+
+## Authorizable
+
+To grant permissions, you need an authorizable model. For our example we'll call it `Role`:
+
+```ruby
+class Role < ApplicationRecord
+  include ::Consent::Authorizable
+end
+```
+
+You can now grant permissions to role with `grant`, `grant_all`, and `grant_all!`:
+
+```ruby
+role = Role.new
+role.grant subject: Project, action: :update, view: :department
+# OR
+role.grant_all({ project: { update: :department } })
+# OR
+role.grant_all({ project: { update: :department } }, replace: true) # to replace everything
+# OR
+role.grant_all!({ project: { update: :department } }, replace: true) # to grant and save
+
+role.permissions
+=> [#<Consent::Permission subject: Project, action: :update, view: :department>]
+```
+
+In the above example, we're granting `:department` view to perform `:update` in the `Project` subject.
+
+You can now create a `Consent::Ability` using the permissions granted to the role:
+
+```ruby
+ability = Consent::Ability.new(user, permissions: role.permissions)
+```
+
+## Defining permissions and views
+
+Generate permissions with the `consent:permissions` generator. I.e:
+
+    $ rails g consent:permissions Project "Our Projects"
+    create  app/permissions/projects.rb
+    create  spec/permissions/projects_spec.rb
+
+This will generate the permission definition:
+
+```ruby
+Consent.define Project, "Our Projects" do
+  #in this case, Project is the subject
+  # and `Our Projects` is the description that makes it clear to users
+  # what the subject is acting upon.
+  …
+end
+```
+
+We can now define the `:update` action and a couple of different views:
+
+```ruby
+Consent.define Project, "Our Projects"  do
+  view :all, "All projects"
+
+  view :department, "Projects from their department" do |user|
+    { department_id: user.department_id }
+  end
+
+  view :team, "Projects from their team" do |user|
+    { team_id: user.team_id }
+  end
+
+  action :update, views: %i[department team all]
+end
+```
+
+The `:department` view will restrict the user to projects with matching `department_id`. That
+means that for `Project.accessible_by(ability, :update)`, with an ability using a User with
+department_id = 13, it will run a query similar to:
+
+```sql
+> user = User.new(department_id: 13)
+> ability = Consent::Ability.new(user)
+> ability.consent subject: Project, action: :update, view: :department
+> Project.accessible_by(user).to_sql
+"SELECT * FROM projects WHERE department_id = 1"
+```
+
+### Subject
+
+The subject is the central point of a group of actions and views. It will typically
+be an `ActiveRecord`, a `:symbol`, or any plain ruby class.
+
+### Views
+
+Views are the rules that limit access to actions. For instance, a user may see a `Project`
+from his department, but not from others. You can enforce it with a `:department` view,
+as in the examples below:
+
+### Hash Conditions
+
+Probably the most commonly used. When the view can be defined using a `where` scope in
+an ActiveRecord context. It follows a match condition and will return all objects that meet
+the criteria:
+
+```ruby
+Consent.define Project, 'Projects' do
+  view :department, "User's department only" do |user|
+    { department_id: user.id }
+  end
+end
+```
+
+Although hash conditions (matching object's attributes) are recommended, the constraints can
+be anything you want. Since Consent does not enforce the rules, those rules are directly given
+to CanCan. Following [CanCan rules](https://github.com/CanCanCommunity/cancancan/wiki/Defining-Abilities%3A-Best-Practice)
+for defining abilities is recommended.
+
+### Object Conditions
+
+If you're not matching for equal values, then you would need to use an object condition.
+
+If you already have an object and want to check to see whether the user has permission to view
+that specific object, you would use object conditions.
+
+If your needs can't be satisfied by hash conditions, it is recommended that a second condition
+is given for constraining object instances. For example, if you want to restrict a view for smaller
+volume projects:
+
+```ruby
+Consent.define Project, 'Projects' do
+  view :small_volumes, "User's department only",
+    -> (user) {
+      ['amount < ?', user.volume_limit]
+    end,
+    -> (user, project) {
+      project.amount < user.volume_limit
+    }
+end
+```
+
+For object conditions, the latter argument will be the referred object, while the
+first will be the context given to the [Permission](#permission) (also check
+[CanCan integration](#cancan-integration)).
+
+### Action
+
+An action is anything you can perform on a given subject. In the example of
+Features this would look like the following using Consent's DSL:
+
+```ruby
+Consent.define :features, 'Beta Features' do
+  action :beta_chat, 'Beta Chat App'
+end
+```
+
+To associate different views to the same action:
+
+```ruby
+Consent.define Project, 'Projects' do
+  # returns conditions that can be used as a matcher for objects so the matcher
+  # can return true or false (hash version)
+  view :department, "User's department only" do |user|
+    { department_id: user.id }
+  end
+  view :future_projects, "User's department only",
+    # returns a condition to be applied to a collection of objects
+    -> (_) {
+      ['starts_at > ?', Date.today]
+    end,
+    # returns true/false based on a condition -- to use this, you must pass in
+    # an instance of an object in order to check the permission
+    -> (user, project) {
+      project.starts_at > Date.today
+    }
+
+  action :read, 'Read projects', views: [:department, :future_projects]
+end
+```
+
+If you have a set of actions with the same set of views, you can use a
+`with_defaults` block to simplify the writing:
+
+```ruby
+with_defaults views: [:department, :small_volumes] do
+  action :read, 'Read projects'
+  action :approve, 'Approve projects'
+end
+```
+
+### Permission
+
+Permission is what is granted to a role, or a user. It grants the ability to perform an *action*,
+on a limited scope (*view*) of the *subject*.
+
+## CanCan Integration
+
+Consent provides a [CanCan](https://github.com/CanCanCommunity/cancancan#readme) ability (Consent::Ability)
+that can be initialized with a group of granted permissions. You can initialize a `Consent::Ability` with:
+
+```ruby
+Consent::Ability.new(*context, super_user: <true|false>, apply_defaults: <true|false>, permissions: [Consent::Permission, ...])
+```
+
+- `*context` is what is given to the view evaluating permission rules. That is typically a user;
+- `super_user` makes the ability to respond to `true` to any `can?` questions, and yields no
+  restrictions in any `accessible_by` and `accessible_through` queries;
+- `apply_defaults` grants actions with the `default_view` set automatically.
+- `permissions` is a collection of permissions to grant to the user
+
+### Manually consent permissions
+
+You can manually grant permissions with `consent`. You could possibly subclass
+`Consent::Ability` to consent some specific permissions by default:
+
+```ruby
+class MyAbility < Consent::Ability
+  def initialize(...)
+    super(...)
+
+    consent action: :read, subject: Project, view: :department
+  end
+end
+```
+
+You can also consent full-access by not specifying the view:
+
+```ruby
+  consent action: :read, subject: Project
+```
+
+Consenting the same permission multiple times is handled as a Union by CanCanCan:
+
+```ruby
+class MyAbility < Consent::Ability
+  def initialize(user)
+    super user
+
+    consent :read, Project, :department
+    consent :read, Project, :future_projects
+  end
+end
+
+user = User.new(department_id: 13)
+ability = MyAbility.new(user)
+
+Project.accessible_by(ability, :read).to_sql
+=> SELECT * FROM projects WHERE ((department_id = 13) OR (starts_at > '2021-04-06'))
+```
+
+## Special subject and actions
+
+### :manage
+
+Whenever the `:manage` action is granted to a user through `consent` or `can`, that means that all actions in that subject are automatically granted with the same restrictions. Take the following example:
+
+```ruby
+Consent.define User, "User permissions" do
+  view :all, "All users"
+  view :self, "Own user" do |user|
+    { id: user.id }
+  end
+
+  action :manage, "Manage users", views: %i[self all]
+  action :update, "Manage users"
+end
+
+> ability = Consent::Ability.new(User.new(id: 123))
+> ability.consent subject: User, action: :manage, view: :self
+> User.accessible_by(ability, :manage).to_sql
+=> "SELECT `users`.* FROM `users` WHERE `users`.`id` = 123"
+> User.accessible_by(ability, :view).to_sql
+=> "SELECT `users`.* FROM `users` WHERE `users`.`id` = 123"
+```
+
+### :all
+
+In CanCan, `:all` is a special subject which means `all subjects`. Whatever is granted to `:all` is applied to all subjects. I.e.:
+
+```ruby
+> ability = Consent::Ability.new(User.new(id: 123))
+> User.accessible_by(ability, :update).to_sql
+=> "SELECT `users`.* FROM `users` WHERE 1=0"
+> ability.can :update, :all
+> User.accessible_by(ability, :update).to_sql
+=> "SELECT `users`.* FROM `users`"
+```
+
+## Rails Integration
+
+Consent is integrated into Rails with `Consent::Engine`. To define where
+your permission files will be, use `config.consent.path`. This defaults to
+`#{Rails.root}/app/permissions/` to conform to Rails' standards.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/powerhome/consent.

data/lib/consent/ability.rb

@@ -1,15 +1,64 @@
 # frozen_string_literal: true
 
 module Consent
-  # Defines a CanCan(Can)::Ability class based on a permissions hash
+  #
+  # Defines a CanCan(Can)::Ability class based on Consent::Permissions
+  #
   class Ability
     include CanCan::Ability
 
-    def initialize(*args, apply_defaults: true)
-      @context = *args
+    #
+    # Initialize a Consent::Ability consenting all the given permissions.
+    #
+    # When super_user is set to true, it grants `:manage :all`, which is understood by
+    # CanCan as a keyword to allow everything with no restrictions.
+    #
+    # If apply_defaults is set to true, Consent::Ability will grant the default views
+    # defined in the permissions.
+    #
+    # I.e.:
+    #
+    #   Consent.define Project, 'Projects' do
+    #     view :department, "User's department only" do |user|
+    #       { department_id: user.id }
+    #     end
+    #     view :self, "User's own projects" do |user|
+    #       { user_id: user.id }
+    #     end
+    #
+    #     action :close, views: %i[department self], default_view: :self
+    #   end
+    #
+    #   Consent::Ability.new(user, permissions: user&.permissions,
+    #                              super_user: user&.super_user?,
+    #                              apply_defaults: user.present?)
+    #
+    # @param [*] *context the view context, usually the user and some additional information
+    # @param [Array<Consent::Permission>] permissions the list of permissions to grant
+    # @param [Boolean] super_user whether Consent should grant :manage :all
+    # @param [Boolean] apply_defaults whether Consent should grant default views
+    #
+    def initialize(*context, permissions: nil, super_user: false, apply_defaults: true)
+      @context = *context
+
       apply_defaults! if apply_defaults
+      can :manage, :all if super_user
+
+      permissions&.each do |permission|
+        consent(**permission.slice(:subject, :action, :view).symbolize_keys)
+      end
     end
 
+    # Consents a subject/action/view to the ability
+    #
+    # `consent!` will add a `can` permission to the ability based on the
+    # view rules defined in the Consent definitions.
+    #
+    # @param [Class,Symbol] subject the target subject of the action
+    # @param [Symbol] action the action being granted on the subject
+    # @param [Symbol,nil] view the conditions/rules on which the action is granted
+    # @raises Consent::ViewNotFound when the view key doesn't exist in the context
+    #
     def consent!(subject: nil, action: nil, view: nil)
       view = case view
              when Consent::View
@@ -24,13 +73,55 @@ module Consent
       )
     end
 
+    # Consents a subject/action/view to the ability
+    #
+    # @see ::Consent::Ability#consent
+    #
     def consent(**kwargs)
       consent!(**kwargs)
     rescue Consent::ViewNotFound
       nil
     end
 
-    private
+    # Returns a hash where the keys are the given permissions, and the values
+    # are either true or false, representing their ability to perform the given
+    # permision
+    #
+    # @param [Array<String>,String,nil] permissions an array of the requested permissions
+    # @return [Hash<String,Boolean>] the hash with the results
+    def to_h(permissions = nil)
+      Array(permissions).reduce({}) do |result, permission|
+        result.merge permission => can?(permission)
+      end
+    end
+
+    # Check if the user has permission to perform a given action on an object.
+    #
+    #   can? :destroy, @project
+    #
+    # You can also pass the class instead of an instance (if you don't have one handy).
+    #
+    #   can? :create, Project
+    #
+    # You can also check with string form of the permission:
+    #
+    #   can? "project/create"
+    #
+    # For more info, check the documentation of [CanCan::Ability]
+    def can?(action_or_pair, subject = nil, *args)
+      action, subject = extract_action_subject(action_or_pair, subject)
+      super action, subject, *args
+    end
+
+    # @private
+    def relation_model_adapter(model_class, action_or_pair, subject, relation)
+      action, subject = extract_action_subject(action_or_pair, subject)
+      ::CanCan::ModelAdapters::AbstractAdapter
+        .adapter_class(model_class)
+        .new(model_class, relation_rules(model_class, action, subject, relation))
+    end
+
+  private
 
     def apply_defaults!
       Consent.subjects.each do |subject|
@@ -45,5 +136,23 @@ module Consent
         end
       end
     end
+
+    def relation_rules(model_class, action, subject, relation)
+      relevant_rules(action, subject).map do |rule|
+        unless rule.conditions.is_a?(Hash)
+          raise ::CanCan::Error, "accessible_through is only available with hash conditions"
+        end
+
+        conditions = rule.conditions.dig(*Array(relation))
+        ::CanCan::Rule.new(rule.base_behavior, action, model_class, conditions, rule.block)
+      end
+    end
+
+    def extract_action_subject(action_or_string_pair, subject)
+      return action_or_string_pair, subject if subject
+
+      subject_key, _, action_key = action_or_string_pair.rpartition("/")
+      [action_key.to_sym, Consent::SubjectCoder.load(subject_key)]
+    end
   end
 end

data/lib/consent/dsl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
+  # @private
   class DSL # :nodoc:
     attr_reader :subject
 

data/lib/consent/{railtie.rb → engine.rb}

@@ -1,26 +1,29 @@
 # frozen_string_literal: true
 
-require 'consent/reloader'
+require "consent"
 
 module Consent
   # Plugs consent permission load to the Rails class loading cycle
-  class Railtie < Rails::Railtie
+  class Engine < Rails::Engine
     config.before_configuration do |app|
-      default_path = app.root.join('app', 'permissions')
-      config.consent = Consent::Reloader.new(
-        default_path,
-        ActiveSupport::Dependencies.mechanism
-      )
+      default_path = app.root.join("app", "permissions")
+      config.consent = Consent::Reloader.new(default_path)
     end
 
     config.after_initialize do |app|
       app.config.consent.execute
     end
 
-    initializer 'initialize consent permissions reloading' do |app|
+    initializer "consent.reloader" do |app|
       app.reloaders << config.consent
       ActiveSupport::Dependencies.autoload_paths -= config.consent.paths
       config.to_prepare { app.config.consent.execute }
     end
+
+    initializer "consent.accessible_through" do
+      ActiveSupport.on_load(:active_record) do
+        include Consent::ModelAdditions
+      end
+    end
   end
 end

data/lib/consent/model_additions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Consent
+  #
+  # Accessible Through logic
+  #
+  # This module adds the accessible_through class method to a model.
+  # It is included in the activerecord base classes by Consent::Engine.
+  #
+  # @see Consent::ModelAdditions::ClassMethods#accessible_through
+  #
+  module ModelAdditions
+    module ClassMethods
+      # Provides a scope within the model to find instances of the model that are accessible
+      # by the given ability through a given relation in the main subject
+      #
+      # I.E.:
+      #
+      #      Given the following scenario
+      #
+      #      class User
+      #        belongs_to :territory
+      #      end
+      #
+      #      Consent.define User, "User permissions" do
+      #        view :territory do |user|
+      #          { territory: { id: user.territory_id } }
+      #        end
+      #        view :visible_territories do |user|
+      #          { territory: { id: user.visible_territory_ids } }
+      #        end
+      #
+      #        action :contact, views: %i[all no_access territory visible_territories]
+      #      end
+      #
+      #    This would give you a list of territories that the given ability can
+      #    contact their users:
+      #
+      #      > user = User.new(territory_id: 13, visible_territory_ids: [2, 3, 4])
+      #      > ability = Consent::Ability.new(user.to_session_user)
+      #      > ability.consent view: :territory, action: :contact, subject: User
+      #      > Territory.accessible_through(ability, :contact, User).to_sql
+      #      => SELECT * FROM territories WHERE id = 13
+      #      > ability.consent view: :visible_territories, action: :contact, subject: User
+      #      > Territory.accessible_through(ability, :contact, User).to_sql
+      #      => SELECT * FROM territories WHERE ((id = 13) OR (id IN (2, 3, 4)))
+      #
+      # @param ability [Consent::Ability] ability performing the query
+      # @param action_or_pair [Symbol,String] the name of the action or a subject/action pair
+      # @param subject [Class,Symbol,nil] the subject in which the action is, when action_or_pair is just the action
+      # @param relation [Symbol,Array<Symbol>] the relation or path to the relation
+      #
+      def accessible_through(ability, action_or_pair, subject = nil, relation: nil)
+        relation ||= model_name.element.to_sym
+        ability.relation_model_adapter(self, action_or_pair, subject, relation)
+               .database_records
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+  end
+end