authz 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f510d949dbbab03e4e30bab01923ffe70b280adabb966445f61e2720a6e85cc1
-  data.tar.gz: a55b14988bc104f52ccfb8479561126481221f11889abc8c8d5880b1c3573ef2
+  metadata.gz: 7b45009ad975b1b9ec89cc17a577a2d18cb1e2ee37c3a98e6ab9582039adb71c
+  data.tar.gz: 452b5dc63434e760c95e03dea00114a2b74dd023a8cf39ef7462505daf70ed9b
 SHA512:
-  metadata.gz: 5105f332e0e117899a67557a1e0d3a8224bafdc1b61acb362b6dd94798f11e05894760ce76e3aad08e5b796c014b910ef3e545559807d9020858c369d4eba9e6
-  data.tar.gz: 51918f89f1737314e8ae953271b79bc6270037d0a6f4c094290e7f61bcba70cc715ea6eaa4491cdbfd957528592c3ac6a972b75c8a0235855f3aac595b703433
+  metadata.gz: db80c3dec8970d12b216b073b48355dce51f18e4de1ea9d8f255a6e38d9490ddecfde299f928a7bbaf0659d8c27d32c7dac21af48037542c7e949cc2e28bf245
+  data.tar.gz: 350e2c8770540eddc5a0cb96abbe9845c7f95d4fa195af893626537fbdf079b35a11763134b2acfbe3f05d3f7b0a31f6531fff40d61be6b0ba1a48d490eebf51

data/README.md

@@ -308,7 +308,7 @@ not for you.**
 ### Usage for Authorization Admins 
 
 Authz comes with a built-in authorization GUI from which admins can configure everything related to authorization. 
-The GUI can be accessed on a URL/path configured by the developers.
+The GUI can be accessed through a URL/path configured by the developers.
 
 There are 3 types of activities that admins do through the GUI: _cold-start configuration, 
 business as usual and maintenance._
@@ -322,7 +322,7 @@ using a rake task, since they probably can’t afford to have all users locked o
 admin manually configures everything through the GUI. More information on how to do this on: 
 [Programmatic Interaction with Authz](#programmatic-interaction-with-authz).
 
-Teams can also opt to use the GUI to manually configure everything. Authz uses its own permission system to authorize 
+Teams can also opt to use the GUI to manually configure everything. Authz uses itself to authorize 
 the access to the GUI, so the “first ever” admin needs to be granted permission to access the GUI by a developer 
 through the console. Authz provides a the `rails authz:seed_admin` rake task to automatically seed everything 
 needed to access the GUI (more information on the [Installation Section](#installation-and-initial-setup)).
@@ -330,7 +330,7 @@ needed to access the GUI (more information on the [Installation Section](#instal
 [Back to table of content](#table-of-content)
 
 #### Business as Usual
-During _“business as usual”_ an admin will make changes to the authorization configuration to keep up with business’ 
+During _“business as usual”_ an admin will make changes to the authorization configuration to keep up with the business’ 
 needs, like granting, creating and revoking roles.
 
 The GUI provides the admins full control of the authorization system without requiring any code modifications and 

data/app/controllers/authz/application_controller.rb

@@ -1,4 +1,9 @@
 module Authz
+  # Inherits from the host app's ApplicationController so that all of it's methods
+  # are available for the engine.
+  #
+  # All engine's controllers inherit from this class.
+  # @api private
   class ApplicationController < ::ApplicationController
     include Authz::Controllers::AuthorizationManager
 

data/app/controllers/authz/bulk/controller_actions_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class Bulk::ControllerActionsController < ApplicationController
 
     def create

data/app/controllers/authz/business_processes_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class BusinessProcessesController < ApplicationController
 
     def index

data/app/controllers/authz/controller_actions_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class ControllerActionsController < ApplicationController
     def index
       @controller_actions = ControllerAction.all.order(created_at: :desc).page(params[:controller_actions_page])

data/app/controllers/authz/home_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class HomeController < ApplicationController
     def index
       @pending_controller_actions = ControllerAction.pending

data/app/controllers/authz/pending_controller_actions_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class PendingControllerActionsController < ApplicationController
     def index
       @pending_controller_actions = ControllerAction.pending

data/app/controllers/authz/rolables_controller.rb

@@ -1,6 +1,8 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # Handles the controller actions related to the rolables
+  # @api private
   class RolablesController < ApplicationController
     def index
       @rolables = rolable.all.page(params[:page])

data/app/controllers/authz/roles_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class RolesController < ApplicationController
 
     def index

data/app/controllers/authz/scoping_rules_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class ScopingRulesController < ApplicationController
     def new
       @role = Role.find(params[:role_id])

data/app/controllers/authz/stale_controller_actions_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class StaleControllerActionsController < ApplicationController
     def index
       @stale_controller_actions = ControllerAction.stale

data/app/controllers/authz/validations/action_names_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class Validations::ActionNamesController < ApplicationController
     def new
       _controller_name = params[:controller_name]

data/app/controllers/authz/validations/business_process_names_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class Validations::BusinessProcessNamesController < ApplicationController
     def new
       name = params[:business_process][:name]

data/app/controllers/authz/validations/controller_names_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class Validations::ControllerNamesController < ApplicationController
     def new
       name = params[:controller_action][:controller]

data/app/controllers/authz/validations/role_names_controller.rb

@@ -1,6 +1,7 @@
 require_dependency "authz/application_controller"
 
 module Authz
+  # @api private
   class Validations::RoleNamesController < ApplicationController
     def new
       name = params[:role][:name]

data/app/helpers/authz/application_helper.rb

@@ -1,5 +1,10 @@
 module Authz
+  # Contains helpers that are available for use in any of the internal engine views.
+  # @api private
   module ApplicationHelper
+
+    # @param name [String] keyword
+    # @return [String] css class for flash
     def flash_class(name)
       case name
       when 'success'
@@ -12,5 +17,6 @@ module Authz
         'is-warning'
       end
     end
+
   end
 end

data/app/models/authz/application_record.rb

@@ -1,4 +1,6 @@
 module Authz
+  # Superclass for all internal models
+  # @api private
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
 

data/app/models/authz/business_process.rb

@@ -1,4 +1,6 @@
 module Authz
+  # Represents a real-life process of the business.
+  # For example, a newspaper might have "publish reports" and "write reports" processes.
   class BusinessProcess < self::ApplicationRecord
     # Validations
     # ==========================================================================

data/app/models/authz/business_process_has_controller_action.rb

@@ -1,4 +1,6 @@
 module Authz
+  # Each instance represents a mapping from business processes to a controller action.
+  # For example, the "publish reports" business process may map to: reports#publish and reports#show
   class BusinessProcessHasControllerAction < self::ApplicationRecord
     # Associations
     # ==========================================================================

data/app/models/authz/controller_action.rb

@@ -1,4 +1,7 @@
 module Authz
+  # Represents a single reachable controller
+  # action from the host application's router, including all library
+  # internal routes.
   class ControllerAction < self::ApplicationRecord
 
     # Validations
@@ -30,18 +33,21 @@ module Authz
     # Class Methods
     # ==========================================================================
 
-    # Extracts the reachable controller actions declared in the host app's router
+    # @return [Hash] reachable controller actions declared in the host app's router
     def self.main_app_reachable_controller_actions
       extract_reachable_controller_actions(Rails.application)
     end
 
-    # Extracts the reachable controller actions declared in the Engine's router
+    # @return [Hash] reachable controller actions declared in the Engine's router
     def self.engine_reachable_controller_actions
       extract_reachable_controller_actions(Authz::Engine)
     end
 
     # Combines the reachable controller actions from the engine and the main app
     # giving precedence to the main app in case of overwrite
+    # @return [Hash] reachable controller actions
+    # @see .main_app_reachable_controller_actions
+    # @see .engine_reachable_controller_actions
     def self.reachable_controller_actions
       app_cas = main_app_reachable_controller_actions
       engine_cas =  engine_reachable_controller_actions
@@ -51,7 +57,10 @@ module Authz
       res
     end
 
-    # Returns array of controller actions found in router but not in controller actions
+    # @return [Array<Hash<controller_name, action_name>>]
+    #         controller actions reachable from the router but not present in the database
+    # @api private
+    # @see .reachable_controller_actions
     def self.pending
       # TODO: Refactor and test
       ca_pairs = []
@@ -70,6 +79,10 @@ module Authz
       pending
     end
 
+    # @return [Array<Authz::ControllerAction>] controller actions that are created in the database that
+    #         are no longer reachable from the router
+    # @api private
+    # @see .reachable_controller_actions
     def self.stale
       # TODO: Refactor and test
       stale = []
@@ -82,6 +95,8 @@ module Authz
 
     # Instance Methods
     # ==========================================================================
+
+    # @return [String] concatenation of controller#action-id
     def to_s
       "#{controller}##{action}-#{id}"
     end

data/app/models/authz/role.rb

@@ -1,4 +1,5 @@
 module Authz
+  # Represents a role within the application
   class Role < self::ApplicationRecord
     # Validations
     # ==========================================================================
@@ -35,27 +36,37 @@ module Authz
              inverse_of: :role,
              dependent: :destroy
 
-    # Returns true if the role has access to the given controller action
+    # @param controller_name [String]
+    # @param action_name [String]
+    # @return [Boolean] true if the role has access to the given controller action
     def has_permission?(controller_name, action_name)
       controller_actions.exists?(controller: controller_name, action: action_name)
     end
 
     # Cached version of has_permission?
+    # @param (see #has_permission?)
+    # @see #has_permission?
     def cached_has_permission?(controller_name, action_name)
       Authz.cache.fetch([cache_key, controller_name, action_name]) do
         has_permission?(controller_name, action_name)
       end
     end
 
-    # Returns the applicable keywords according to the role's
-    # scoping rule for the given scopable
-    # Raises exception if the role does not have a scoping rule
-    # for the given scopable
+    # @param scopable [Scopable] the scoping module for which the keyword
+    #         is going to be found
+    # @return [String] the applicable keywords according to the role's
+    #         scoping rule for the given scopable
+    # @raise if the role does not have a scoping rule
+    #        for the given scopable
     def granted_keyword_for(scopable)
       scoping_rules.find_by!(scopable: scopable.to_s).keyword
     end
 
     # Cached version of #granted_keyword_for
+    # @param (see #granted_keyword_for)
+    # @return (see #granted_keyword_for)
+    # @raise (see #granted_keyword_for)
+    # @see #granted_keyword_for
     def cached_granted_keyword_for(scopable)
       Authz.cache.fetch([cache_key, scopable.to_s]) do
         granted_keyword_for(scopable)

data/app/models/authz/role_grant.rb

@@ -1,4 +1,6 @@
 module Authz
+  # An instance represents a single mapping between a user and a role.
+  # For example <'John', 'Publisher'>
   class RoleGrant < self::ApplicationRecord
     # Associations
     # ==========================================================================

data/app/models/authz/role_has_business_process.rb

@@ -1,4 +1,6 @@
 module Authz
+  # An instance represents a single mapping between a role and a business process.
+  # For example <Publisher, release reports>
   class RoleHasBusinessProcess < self::ApplicationRecord
 
     # Associations

data/app/models/authz/scoping_rule.rb

@@ -1,4 +1,6 @@
 module Authz
+  # An instance represents that a role has keyword for a particular scopable.
+  # For example 'Sports Publisher' had keyword 'sports' for 'ScopableByDepartment'
   class ScopingRule < self::ApplicationRecord
     # Validations
     # ==========================================================================
@@ -20,6 +22,7 @@ module Authz
 
     scope :for_scopables, ->(scopables) { where(scopable: scopables.map(&:to_s)) }
 
+    # @return [String] string representation of instance
     def to_s
       "#{scopable}: #{keyword}##{id}"
     end

data/db/migrate/20181129024103_create_authz_controller_actions.rb

@@ -6,5 +6,6 @@ class CreateAuthzControllerActions < ActiveRecord::Migration[5.2]
 
       t.timestamps
     end
+    add_index :authz_controller_actions, [:controller, :action], unique: true
   end
 end

data/db/migrate/20181129091325_create_authz_business_process_has_controller_actions.rb

@@ -11,5 +11,9 @@ class CreateAuthzBusinessProcessHasControllerActions < ActiveRecord::Migration[5
 
       t.timestamps
     end
+    add_index(:authz_business_process_has_controller_actions,
+              [:authz_business_process_id, :authz_controller_action_id],
+              unique: true,
+              name: 'authz_bphca_bp_ca')
   end
 end

data/db/migrate/20181129220317_create_authz_role_has_business_processes.rb

@@ -8,5 +8,9 @@ class CreateAuthzRoleHasBusinessProcesses < ActiveRecord::Migration[5.2]
 
       t.timestamps
     end
+    add_index(:authz_role_has_business_processes,
+              [:authz_role_id, :authz_business_process_id],
+              unique: true,
+              name: 'authz_rhpb_role_bp')
   end
 end

data/db/migrate/20181130053841_create_authz_role_grants.rb

@@ -8,5 +8,9 @@ class CreateAuthzRoleGrants < ActiveRecord::Migration[5.2]
 
       t.timestamps
     end
+    add_index(:authz_role_grants,
+              [:rolable_type, :rolable_id, :authz_role_id],
+              unique: true,
+              name: 'authz_rgs_rolable_role')
   end
 end

data/db/migrate/20190102030242_create_authz_scoping_rules.rb

@@ -8,5 +8,9 @@ class CreateAuthzScopingRules < ActiveRecord::Migration[5.2]
 
       t.timestamps
     end
+    add_index(:authz_scoping_rules,
+              [:authz_role_id, :scopable],
+              unique: true,
+              name: 'authz_srs_role_scopable')
   end
 end

data/lib/authz.rb

@@ -10,13 +10,23 @@ require 'kaminari'
 require 'jquery-rails'
 require 'font-awesome-rails'
 
+
+# Stores the configuration parameters of the library
+# @api public
 module Authz
+
+  # Error that will be raised when multiple rolables are being used.
   class MultileRolablesNotPermitted < StandardError; end
 
+  # @return [Rolable] classes of al rolables
+  # @api private
   mattr_reader :rolables
-  @@rolables = [] # Contains the classes of all Rolables
-  def self.register_rolable(rolable)
+  @@rolables = []
 
+  # Adds a rolable to the configuration
+  # @param rolable [Rolable] rolable class
+  # @api private
+  def self.register_rolable(rolable)
     unless @@rolables.map{|r| r.model_name.name}.include?(rolable.model_name.name)
       @@rolables << rolable
     end
@@ -28,24 +38,28 @@ module Authz
     end
   end
 
-  # The method controllers use to force authentication
   mattr_accessor :force_authentication_method
+  # The method controllers use to force authentication
   @@force_authentication_method = :authenticate_user!
 
-  # The method used to access the instance of a current user
   mattr_accessor :current_user_method
+  # The method used to access the instance of a current user
   @@current_user_method = :current_user
 
-  # Configuration to enable cross request caching
   mattr_accessor :cross_request_caching
+  # Configuration to enable cross request caching
   @@cross_request_caching = false
 
-  # The attribute that points to the cache module
   mattr_reader :cache
+  # The attribute that points to the cache module
   @@cache = Authz::Cache
 
-  # Allows the configuration of the gem using the
-  # Authz.configure do |config| syntax
+  # Allows the configuration of the gem using
+  # block syntax
+  # @example
+  #   Authz.configure do |config|
+  #     config.current_user_method = :current_user
+  #   end
   def self.configure
     yield self
   end