invitational 1.1.6 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e6be26e6c2ba8c14eedc3c84029c42fb2d8ba27c
-  data.tar.gz: adfd381d2d9b1484211b2dd56e153eda3f806990
+  metadata.gz: 84e55fa3994b13b2b2d2916363decf894c4e8bff
+  data.tar.gz: bf6ee875a454487dbc6362cbb0a4cf8e59dab81c
 SHA512:
-  metadata.gz: 2b893c783473e121a31c412639316039b8e8aec19b508b7a660949f0ccefea5e245939d0d7872c11aefa9d322a55c22d14a68560624347e6a323db3f126ccd23
-  data.tar.gz: fa83149b377ba8788bee298f644346e8f1363def5b3c63ccb9f8bf3d2ce9bdf0709c9996c748c7ef05864e0e1cba4a18dc1606716fc8507ca2d0afacfea7b78e
+  metadata.gz: 055d06625f07896c2da05dec3b70ed14b00901f18b6af5822e5c893b628cec1835e52c5eb9093ff924dcddd804d2e2063cd3935e1f05ac275edd80fb9108cfac
+  data.tar.gz: a961c3c3a27703b6dd8314dc1144baffc4320fccbb2aeb62750f31406ad7cbe523414890fd7a7658d63d5876eb1fc1b85e6f82e8746ccaf039af1ab1627bc14c

data/README.md

@@ -4,7 +4,7 @@
 
 The purpose of Invitational is to eliminate the tight coupling between user identity/authentication and application functional authorization.  It is a common pattern in multi-user systems that in order to grant access to someone else, an existing administrator must create a user account, providing a username and password, and then grant permissions to that account.  The administrator then needs to communicate the username and password to the individual, often via email.  The complexity of this process is compounded in multi-account based systems where a single user might wind up with mutiple user accounts with various usernames and passwords.
 
-Inspired by 37Signals' single sign-on process for Basecamp, Invitational provides an intermediate layer between an identity model (i.e. User) and some entity to which authorization is given.  This intermediate layer, an Invitation, represents a granted role for a given entity.  These roles can then be leveraged by the application's functional authorization system.
+Inspired by 37Signals' single sign-on process for Basecamp, Invitational provides an intermediate layer between an identity model (i.e. User) and either the system as a whole or some specific entity to which authorization is given.  This intermediate layer, an Invitation, represents a granted role for the sytem or a given entity.  These roles can then be leveraged by the application's functional authorization system.
 
 Invitational supplies a custom DSL on top of the CanCan gem to provide an easy implementation of role-based functional authorization.  This DSL supports the hierarchical model common in many systems.  Permissions can be esablished for a child based upon an invitation to its parent (or grandparent, etc).
 
@@ -15,7 +15,7 @@ An invitation is initially created in an un-claimed state.  The invitation is as
 Invitational works with Rails 4.0 and up.  You can add it to your Gemfile with:
 
 ```
-gem 'invitational', git: 'git@github.com:d-i/invitational.git'
+gem 'invitational'
 ```
 
 Run the bundle command to install it.
@@ -39,6 +39,21 @@ The generator will add a database migration you will need to run:
 rake db:migrate
 ```
 
+#Types of Invitations
+Invitational has three types of invitations:
+
+##Entity
+An `Entity` invitation, as the name imples, is for a specific entity within the system.  For example, in a contract management system, a user might be invited to a 
+contract in the sytem with the role of 'Recipient' .  They might then be able to read and to mark that specific contract as signed, but not access any other contracts in the system.
+
+##System
+A `System` invitation is not related to a specific entity, but to the system overall. For example, in the contract management system mentioned above, another user might be 
+invited to the sytem with the role of 'contract_manager'.  They might then be able to manage *all* contracts within the system, but not have authority to invite other users.
+
+##UberAdmin
+An `UberAdmin` invitation is also, like a `System` invitation, not related to a specific entity but to the system overall.  Unlike a `System` invitation, an `UberAdmin` invitation
+effectively grants the associated user access to all parts of the system, as every inquiry for the existance of an invitation (either System or Entity) will indicate true.
+
 #Implementation
 
 ##invited_to
@@ -84,9 +99,24 @@ entity.admins
 
 You can then add this entity to the list of invitable classes on the `invited_to` call in your identity class.
 
+##accepts_system_roles_as
+System roles are defined in the `Invitation` class. Simply add the list of system roles to the class method that has been defined for you by the 
+generator:
+
+```
+accepts_system_roles_as :contract_manager, :bookkeeper
+```
+
+The `accepts_system_roles_as` method also sets up scopes on `Invitation` for each identified role:
+
+```
+License.contract_managers
+License.bookkeepers
+```
+
 #Usage
 ##Creating Invitations
-To create an invitation to a given model:
+To create an entity invitation to a given model:
 
 ```
 entity = Entity.find(1)
@@ -94,9 +124,16 @@ entity = Entity.find(1)
 entity.invite "foo@bar.com", :admin
 ```
 
-The method will return the Invitation.  In the event that the email has already been invited to that entity, 
+To create an invitation to a system role:
+
+```
+Invitation.invite_system_user "foo@bar.com", :contract_manager
+```
+
+The method will return the Invitation.  In the event that the email has already been invited to that entity or to the system role, 
 an `Invitational::AlreadyInvitedError` will be raised.  If the passed role is not valid for the given entity (based on its 
-`accepts_invitation_as` call), an `Invitational::InvalidRoleError` will be raised.
+`accepts_invitation_as` call) or not a valid system role, an `Invitational::InvalidRoleError` will be raised.
+
 
 ###Immediately Claimed Invitations
 
@@ -111,6 +148,13 @@ entity = Entity.create(...)
 entity.invite current_user, :admin
 ```
 
+and
+
+```
+Invitation.invite_system_user current_user, :contract_manager
+```
+
+
 ##Claiming Invitations
 
 Invitations can be claimed by passing their hash and the claiming user to the `claim` class method on Invitation:
@@ -141,11 +185,17 @@ current_user.invited_to? entity, :admin
 
 Will only return true if the current user has accepted an invitation as an Admin to the entity.
 
+For system roles, the `invited_to_system?` instance method on your identity class can be used:
+
+```
+current_user.invited_to_system? :contract_manager
+```
+
 ##UberAdmin
 
 Invitational provides a special, system-wide, invitation and role called `:uberadmin`.  A user that has
 claimed an UberAdmin invitation will always indicate they have been invited to a given role for a given entity.  
-In other words, every call to `invited_to?` for an UberAdmin will return true.  
+In other words, every call to `invited_to?` or `invited_to_system?` for an UberAdmin will return true.  
 
 To create an UberAdmin invitation:
 
@@ -189,29 +239,49 @@ can :manage, Parent, roles: [:admin]
 can :read, Parent, roles: [:staff]
 ```
 
-###Invitation to a parent
-To idenfitify abilities based upon invitations to a parent entity, add a hash as an element to the roles array, 
-supplying the parent attribute name as a key, and an allowed roles array as the value:
+###System Roles
+To specify system roles for a given ability, utilize the `system_roles` method inside a `roles:` array:
 
 ```
-can :manage, Child, roles[ {parent: [:admin, :staff]}]
+can :manage, contract, roles: [system_roles(:contract_manager, :sales_manager)]
+```
+
+
+###Invitation to a parent (or other attribute)
+To idenfitify abilities based upon invitations to a parent entity or other attribute, Invitational provides an
+```attribute_roles``` method.  The first argument is symbol indicating the attribute name of the parent entity, 
+the second is an array of roles in which the user must be invited to the parent entity:
+
+```
+can :manage, Child, roles[attribute_roles(:parent, [:admin, :staff])]
+```
+
+To reference invitations on a "grand parent" (or higher) entity, ```attribute_roles``` optionally accepts
+an array as the first parameter, indicating the "path" to the target entity.
+
+To indicate that an invitation to the grandparent found here:
+
+```
+entity = Entity.first
+
+entity.parent.grandparent
 ```
 
-The parent invitation can be used recursively too, to specify grand-parent (or above) relationships:
+Pass the following as the first attribute:
 
 ```
-can :manage, Child, roles[ {parent: {grand_parent: [:admin, :staff]}}]
+can :manage, Child, roles[attribute_roles([:parent, :grandparent],  [:admin])]
 ```
 
 To specify child and parent invitations, you can combine them on one line:
 
 ```
-can :manage, Child, roles[:child_admin, {parent: [:admin, :staff]}]
+can :manage, Child, roles[:child_admin, attribute_roles(:parent, [:admin, :staff])]
 ```
 
 However, it is recommended to specify them on separate lines:
 
 ```
 can :manage, Child, roles[:child_admin]
-can :manage, Child, roles[ {parent: [:admin, :staff]}]
+can :manage, Child, roles[attribute_roles(:parent, [:admin, :staff])]
 ```

data/app/modules/invitational/invitation_core.rb

@@ -35,8 +35,18 @@ module Invitational
         where('role = ?', role.to_s)
       }
 
+      scope :for_system_role, lambda {|role|
+        where('invitable_id IS NULL AND role = ?', role.to_s)
+      }
+
       scope :pending, lambda { where('user_id IS NULL') }
       scope :claimed, lambda { where('user_id IS NOT NULL') }
+
+      @system_roles = Array.new
+
+      def self.system_roles
+        @system_roles
+      end
     end
 
     module ClassMethods
@@ -52,6 +62,20 @@ module Invitational
         Invitational::CreatesUberAdminInvitation.for target
       end
 
+      def invite_system_user target, role
+        Invitational::CreatesSystemUserInvitation.for target, role
+      end
+
+      def accepts_system_roles_as *args
+        args.each do |role|
+          relation = role.to_s.pluralize.to_sym
+
+          scope relation, -> {where("invitable_id IS NULL AND role = '#{role.to_s}'")}
+
+          self.system_roles << role
+        end
+      end
+
     end
 
     def setup_hash
@@ -60,7 +84,8 @@ module Invitational
     end
 
     def standard_role?
-      role != :uberadmin
+      roles = Invitation.system_roles + [:uberadmin]
+      !roles.include?(role)
     end
 
     def role

data/app/modules/invitational/invited_to.rb

@@ -25,5 +25,9 @@ module Invitational
       Invitational::ChecksForInvitation.for self, entity,role
     end
 
+    def invited_to_system? role
+      invitations.for_system_role(role).count > 0
+    end
+
   end
 end

data/app/services/invitational/creates_system_user_invitation.rb

@@ -0,0 +1,34 @@
+module Invitational
+  class CreatesSystemUserInvitation
+    attr_reader :success,
+                :invitation
+
+    def self.for target, role
+      if target.is_a? String
+        email = target
+
+        if Invitation.for_system_role(role).for_email(email).count > 0
+          raise Invitational::AlreadyInvitedError.new
+        end
+
+      else
+        user = target
+        email = user.email
+
+        if user.invited_to_system? role
+          raise Invitational::AlreadyInvitedError.new
+        end
+      end
+
+      invitation = ::Invitation.new(role: role, email: email)
+      if user
+        invitation.user = user
+        invitation.date_accepted = DateTime.now
+      end 
+      invitation.save
+
+      invitation
+    end
+
+  end
+end

data/lib/generators/invitational/install/templates/invitation.rb

@@ -4,4 +4,6 @@ class Invitation < ActiveRecord::Base
 
   belongs_to :user<%= @custom_user_class %>
 
+  accepts_system_roles_as
+
 end

data/lib/invitational/cancan.rb

@@ -22,7 +22,11 @@ module Invitational
           role_type = subject
         end
 
-        role_mappings[key] = roles
+        unless role_mappings.has_key?(key)
+          role_mappings[key] = []
+        end
+
+        role_mappings[key] += roles
 
         block = ->(model){
           roles = role_mappings[key]
@@ -34,19 +38,9 @@ module Invitational
 
       def check_permission_for model, user, in_roles
 
-        in_roles.reduce(false) do |result,role|
+        in_roles.inject(false) do |result,role|
           result || if role.respond_to? :values
-            method = role.keys.first
-            related = model.send(method)
-
-            if related.respond_to? :any?
-              related.any? do |model|
-                check_permission_for model, user, role.values.flatten
-              end
-            else
-              check_permission_for related, user, role.values.flatten
-            end
-
+            check_permission_for_keyed_roles model, user, role
           else
             Invitational::ChecksForInvitation.for(user, model, role)
           end
@@ -54,8 +48,56 @@ module Invitational
 
       end
 
+      def check_permission_for_keyed_roles model, user, role
+        key = role.keys.first
+
+        if key == :system_roles
+          check_permission_for_system_role user, role
+        else
+          check_permission_for_attribute model, user, role
+        end
+      end
+
+      def check_permission_for_system_role user, role
+        roles = role.values.flatten
+
+        user.uberadmin? || roles.any? do |system_role|
+          user.invited_to_system? system_role
+        end
+      end
+
+      def check_permission_for_attribute model, user, role
+        method = role.keys.first
+        related = model.send(method)
+
+        if related.respond_to? :any?
+          related.any? do |model|
+            check_permission_for model, user, role.values.flatten
+          end
+        else
+          check_permission_for related, user, role.values.flatten
+        end
+      end
+
       def attribute_roles attribute, roles
-        {attribute => roles}
+        hash = nil
+        if attribute.respond_to? :each
+          attribute.reverse.each do |attr|
+            if hash.nil?
+              hash = {attr => roles}
+            else
+              hash = {attr => hash}
+            end
+          end
+        else
+          hash = {attribute => roles}
+        end
+
+        hash
+      end
+
+      def system_roles roles
+        {system_roles: roles}
       end
 
     end

data/lib/invitational/version.rb

@@ -1,3 +1,3 @@
 module Invitational
-  VERSION = "1.1.6"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: invitational
 version: !ruby/object:Gem::Version
-  version: 1.1.6
+  version: 1.2.0
 platform: ruby
 authors:
 - Dave Goerlich
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-07 00:00:00.000000000 Z
+date: 2014-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: cancancan
   requirement: !ruby/object:Gem::Requirement
@@ -146,6 +146,7 @@ files:
 - app/services/invitational/claims_all_invitations.rb
 - app/services/invitational/claims_invitation.rb
 - app/services/invitational/creates_invitation.rb
+- app/services/invitational/creates_system_user_invitation.rb
 - app/services/invitational/creates_uber_admin_invitation.rb
 - app/views/layouts/invitational/application.html.erb
 - config/routes.rb