accessly 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 60f014b72282ae3ebb27bac60f28bea7c596b1b9
-  data.tar.gz: 2ef2178dd5a914519839fad848c5aa6526c6a1ab
+  metadata.gz: 9abbf504e2ae963dde890f7175961694b521462b
+  data.tar.gz: a470d71b034a205dc6479c2e015f47117fd097f9
 SHA512:
-  metadata.gz: 33ea523a967256119180e2b4a49557c5951d31db882d8c46fa823613d8226ad8896c5f44cb6f27cc767145208ada43e740086caadc853d35fdda00e9f23c0e39
-  data.tar.gz: 01f0e9af0c17a8159e0ccbc8d8c34f5ac48e267dde25e819dbfae52eb132832639feedcb2bb92b6c47ba6a107780a4121b15050a67640d6211167c8fd348ae52
+  metadata.gz: 93b7e81d5ec169e79882348b900c48a4906e7b5006891cf3a42df334261ce9be085b604a6393dd8e23ce4493489a0c79a8f5766bf96dd363b234a0eec9924874
+  data.tar.gz: e728bcecd705c55b36c21cd325855fabdd7a19e513eb6bf2a808bd2d8889eb97337c2e120e556cf2625341ff2d5a6720a903585e977fd58a5cf5def062c7bbe4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    accessly (0.0.1)
+    accessly (1.0.0)
       activerecord (~> 5.0)
 
 GEM
@@ -115,11 +115,11 @@ PLATFORMS
 DEPENDENCIES
   accessly!
   bundler (~> 1.16)
-  database_cleaner
+  database_cleaner (~> 1.5)
   minitest (~> 5.0)
   rails (~> 5.0)
   rake (~> 10.0)
-  sqlite3
+  sqlite3 (~> 1.3)
 
 RUBY VERSION
    ruby 2.4.2p198

data/README.md

@@ -1,8 +1,27 @@
+<img width="268" src="https://raw.githubusercontent.com/lessonly/accessly/master/logo/logo.png" alt="Accessly Logo">
+
 # Accessly
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/accessly`. To experiment with that code, run `bin/console` for an interactive prompt.
+Accessly exists out of our need to answer the following questions:
+
+1. What can a user do or see?
+2. Can a user do an arbitrary action on another object?
+
+We were not satisfied with the available resources to answer the questions so we created Accessly!
+
+Accessly is our opinion of access control that can broadly grant permissions to 'actors' (modeled as `users`, `groups`, `organizations`, etc)
+
+```
+Can actor1 view the content resource (/content)?
+```
+
+Our `actors` can also have permissions on other models in our application
+
+```
+Can actor1 edit a Post with id 1?
+```
 
-TODO: Delete this and the text above, and describe your gem
+If you have a similar need to implement a permission scheme in your Rails app please continue reading!
 
 ## Installation
 
@@ -20,15 +39,280 @@ Or install it yourself as:
 
     $ gem install accessly
 
+Add the ActiveRecord Migrations:
+
+    $ rails g accessly:install
+
 ## Usage
 
-TODO: Write usage instructions here
+You can use the Accessly gem directly to grant | revoke | check permissions.  We recommend the use of 'Policies' covered in this README.
+Checkout our [API docs](http://www.rubydoc.info/gems/accessly) for more info on using the API directly
+
+We use Accessly with policies in mind to capture everything we want to know about a specific permission set. Let's take a look at some examples:
+
+### Basic Action Policy
+
+```ruby
+class ApplicationFeaturePolicy < Accessly::Policy::Base
+
+  actions(
+    view_dashboard: 1,
+    view_super_secret_page: 2,
+    view_double_secret_probation_page: 3
+  )
+
+end
+```
+
+With this policy we can `grant` permissions to a user
+
+```ruby
+ApplicationFeaturePolicy.new(user).grant!(:view_super_secret_page)
+```
+
+In our `SuperSecretPageController`, we can check whether the user has permission to view that page with
+
+```ruby
+ApplicationFeaturePolicy.new(user).view_super_secret_page?
+# or
+ApplicationFeaturePolicy.new(user).can?(:view_super_secret_page)
+```
+
+At any point in time we can revoke permissions with
+
+```ruby
+ApplicationFeaturePolicy.new(user).revoke!(:view_super_secret_page)
+```
+
+### Basic Action on Object Policy
+
+We can grant permissions to `actors` on other `objects` in our application with a policy like:
+
+```ruby
+class UserPolicy < Accessly::Policy::Base
+
+  actions_on_objects(
+    view: 1,
+    edit: 2,
+    destroy: 3
+  )
+
+  def self.namespace
+    User.name
+  end
+
+  def self.model_scope
+    User.all
+  end
+end
+```
+
+We differentiate permissions by a `namespace` which by default is the name of your policy class.  However,
+it may be necessary to override the default behavior represented in the above example.
+
+Accessly can return a relation of ids on an object for a given actor's permission grants.  `Accessly::Policy::Base` requires
+that you implement `self.model_scope` with an `ActiveRecord` scope so the `list` api can return an `ActiveRecord::Relation`
+
+With this policy we can `grant` permissions for a user to do an action on another user object.
+
+```ruby
+UserPolicy.new(user).grant!(:edit, other_user)
+```
+
+In our `EditUserController`, we can check permissions
+
+```ruby
+UserPolicy.new(user).edit?(other_user)
+# or
+UserPolicy.new(user).can?(:edit, other_user)
+```
+
+We can list all of the users available to edit with
+
+```ruby
+UserPolicy.new(user).edit
+# or
+UserPolicy.new(user).list(:edit)
+```
+
+At any point in time we can revoke permissions with
+
+```ruby
+UserPolicy.new(user).revoke!(:edit, other_user)
+```
+
+### Intermediate Action Policy
+
+Let's look at a policy with a combined configuration and more customization
+
+```ruby
+class UserPolicy < Accessly::Policy::Base
+
+  actions(
+    view: 1,
+    edit_basic_info: 2,
+    change_role: 3,
+    email: 4
+  )
+
+  actions_on_objects(
+    view: 1,
+    edit: 2,
+    destroy: 3,
+  )
+
+  def self.namespace
+    User.name
+  end
+
+  def self.model_scope
+    User.all
+  end
+
+  def segment_id
+    actor.organization_id
+  end
+
+  def unrestricted?
+    actor.admin?
+  end
+end
+```
+
+This policy combines `actions` and `actions_on_objects`, introduces Accessly's support for `segment_id`, and overrides `unrestricted?`
+
+#### combined actions and actions_on_objects
+
+Accessly policies can extend support for combined use of `actions` and `actions_on_objects.` You may want to broadly grant `edit_basic_info` permissions to some users. The same policy can support a limited scope of permissions where the `actor` and `object` must be defined.
+
+#### segment_id
+
+`segment_id` allows you to scope permission grants to a specific object id that you define. In our example the `actor` belongs to an Organization model, and we set the organization_id on each permission granted for any actor using the policy.
+
+It provides additional efficiency on query execution, and we can broadly remove permissions if the organization is no longer in the application.
+
+#### unrestricted?
+
+Accessly uses `unrestricted?` to bypass permission checks. This policy shows that the actor has an `admin` designation which we do not want to model in permissions. The business logic implemented here would bypass any permission check if `unrestricted?` returns `true`. When `unrestricted?` returns `true`, then `can?` and the other permission check methods (like `edit_basic_info?` in this example) automatically return `true`, and `list` and the other list methods (like `edit` in this example) returns the `ActiveRecord::Relation` given by `self.model_scope`
+
+### Advanced Action Policy
+
+Let's look at a policy that overrides `action?` and `list` APIs
+
+```ruby
+class UserPolicy < Accessly::Policy::Base
+
+  actions(
+    view: 1,
+    edit_basic_info: 2,
+    change_role: 3,
+    email: 4
+  )
+
+  actions_on_objects(
+    view: 1,
+    edit: 2,
+    destroy: 3
+  )
+
+  def self.namespace
+    User.name
+  end
+
+  def self.model_scope
+    User.all
+  end
+
+  # Override the destroy permission check for an "Action on Object"
+  def destroy?(object)
+    if actor.name == "Alice"
+      true
+    else
+      super
+    end
+  end
+
+  # Override the view permission check for both Action only and "Action on Object"
+  def view?(object = nil)
+    if object.nil?
+      if actor.name == "Bob"
+        false
+      else
+        super
+      end
+    elsif actor.name == "Alice" && object.name == "Bob"
+      true
+    else
+      super
+    end
+  end
+
+  # Override the change_role check for Action only
+  def change_role?
+    false
+  end
+
+  # Override the list method for view permissions
+  def view
+    if actor.name == "Alice"
+      User.all
+    else
+      super
+    end
+  end
+end
+```
+#### Overriding defaults
+
+Here we provide some examples of the `Accessly::Policy::Base` overrides you can make in an application. You can override the function completely or fallback to the `Base` method. The implementation strategy is up to you!
+
+Any call to the following functions will run the given example in the policy:
+
+#### destroy?(object)
+
+```ruby
+# Action on Object queries
+UserPolicy.new(user).destroy?(other_user)
+# or
+UserPolicy.new(user).can?(:destroy, other_user)
+```
+
+#### view?(object = nil)
+
+```ruby
+# Action queries
+UserPolicy.new(user).view?
+# or
+UserPolicy.new(user).can?(:view)
+
+# Action on Object queries
+UserPolicy.new(user).view?(other_user)
+# or
+UserPolicy.new(user).can?(:view, other_user)
+```
+
+#### change_role?
+
+```ruby
+# Action queries
+UserPolicy.new(user).change_role?
+# or
+UserPolicy.new(user).can?(:change_role)
+```
+
+#### view
+
+```ruby
+# List queries
+UserPolicy.new(user).view
+# or
+UserPolicy.new(user).list(:view)
+```
 
-## Development
+## Caching
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Accessly implements some internal caching to increase the performance of permission queries. If you use the same Policy object for the same lookup twice, then the second one will lookup based on the cached result. Be mindful of caching when using `revoke!` or `grant!` calls with subsequent permission queries on the same Policy object.
 
-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
 

data/lib/accessly.rb

@@ -1,5 +1,6 @@
 require "accessly/version"
 require "accessly/query"
+require "accessly/policy/base"
 require "accessly/permission/grant"
 require "accessly/permission/revoke"
 require "accessly/models/permitted_action"

data/lib/accessly/policy/base.rb

@@ -38,6 +38,14 @@ module Accessly
         self.class.model_scope
       end
 
+      # Specifies all the actors used in permission lookups.
+      # Override this method in child policy classes to specify
+      # other actors that the actor given in the initializer may
+      # inherit permissions from.
+      def actors
+        actor
+      end
+
       def unrestricted?
         false
       end
@@ -46,33 +54,33 @@ module Accessly
         nil
       end
 
-      def grant(action, object = nil)
-        object_id = _get_object_id(object)
-
-        action_id = if object_id.nil?
-          _get_general_action_id!(action)
+      def can?(action, object = nil)
+        if object.nil?
+          send("#{action}?")
         else
-          _get_action_on_object_id!(action)
+          send("#{action}?", object)
         end
+      end
 
-        grant_object.grant!(action_id, namespace, object_id)
+      def list(action)
+        send(action)
       end
 
-      def revoke(action, object = nil)
+      def grant!(action, object = nil)
         object_id = _get_object_id(object)
+        action_id = _get_action_id(action, object_id)
+        grant_object.grant!(action_id, namespace, object_id)
+      end
 
-        action_id = if object_id.nil?
-          _get_general_action_id!(action)
-        else
-          _get_action_on_object_id!(action)
-        end
-
+      def revoke!(action, object = nil)
+        object_id = _get_object_id(object)
+        action_id = _get_action_id(action, object_id)
         revoke_object.revoke!(action_id, namespace, object_id)
       end
 
       def accessly_query
         @_accessly_query ||= begin
-          query = Accessly::Query.new(actor)
+          query = Accessly::Query.new(actors)
           query.on_segment(segment_id) unless segment_id.nil?
           query
         end
@@ -94,6 +102,14 @@ module Accessly
 
       private
 
+      def _get_action_id(action, object_id = nil)
+        if object_id.nil?
+          _get_general_action_id!(action)
+        else
+          _get_action_on_object_id!(action)
+        end
+      end
+
       # Determines whether the caller is trying to call an action method
       # in the format `action_name?`. If so, this calls that method with
       # the given arguments.

data/lib/accessly/version.rb

@@ -1,3 +1,3 @@
 module Accessly
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/logo/logo.svg

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 268 60">
+  <g fill="none" fill-rule="evenodd">
+    <path fill="#292933" d="M62 59c-10.6 0-19-7.5-19-18 0-11.5 8.4-19 19-19 9 0 13.6 4.9 16 10l-8 3a9.3 9.3 0 0 0-8-5c-5.5.2-9.6 4.7-10 11 .4 5.3 4.5 9.8 10 10a9.3 9.3 0 0 0 8-5l8 3c-2.3 5-7 10-16 10zm37 0c-10.6 0-19-7.5-19-18 0-11.5 8.4-19 19-19 9 0 13.6 4.9 16 10l-8 3a9.3 9.3 0 0 0-8-5c-5.5.2-9.6 4.7-10 11 .4 5.3 4.5 9.8 10 10a9.3 9.3 0 0 0 8-5l8 3c-2.3 5-7 10-16 10zm45 0h-26V23h26v8h-17v6h17v8h-17v6h17v8zm18 0c-6.6 0-11.5-2.3-15-6l5-7c2.3 3 6.1 5.1 11 5 3 .1 4.9-1.1 5-3-.1-4.7-19.9-.8-20-15 .1-5.6 5-11 14-11a20 20 0 0 1 14 5l-5 7a13.2 13.2 0 0 0-10-4c-2.6-.1-3.7 1-4 2 .3 5 20 1.7 20 15 0 7.2-5.2 12-15 12zm32 0c-6.6 0-11.5-2.3-15-6l5-7c2.3 3 6.1 5.1 11 5 3 .1 4.9-1.1 5-3-.1-4.7-19.9-.8-20-15 .1-5.6 5-11 14-11a20 20 0 0 1 14 5l-5 7a13.2 13.2 0 0 0-10-4c-2.6-.1-3.7 1-4 2 .3 5 20 1.7 20 15 0 7.2-5.2 12-15 12zm43-1h-23V23h9v27h14v8zm16 0h-8V44.4L231 23h10l8 13.6 8-13.6h10l-14 21.4V58z"/>
+    <path fill="#F6BF35" d="M20 60a19 19 0 1 1 0-38 19 19 0 0 1 0 38zm-5-23.3c0 1.7 1.1 3.5 3 4.8l-1.5 7a2 2 0 0 0 2 2.5h4a2 2 0 0 0 2-2.4L23 41.5c1.9-1.3 3-3 3-4.8 0-3.3-2.5-5.7-5.5-5.7S15 33.4 15 36.7z"/>
+    <path stroke="#F6BF35" stroke-linecap="round" stroke-width="8" d="M9 16.8C9 10.3 14.1 5 20.5 5S32 10.3 32 16.8V43"/>
+  </g>
+</svg>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: accessly
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Aaron Milam
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-28 00:00:00.000000000 Z
+date: 2018-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -149,6 +149,8 @@ files:
 - lib/generators/accessly/install/install_generator.rb
 - lib/generators/accessly/install/templates/db/migrate/create_permitted_action_on_objects.rb
 - lib/generators/accessly/install/templates/db/migrate/create_permitted_actions.rb
+- logo/logo.png
+- logo/logo.svg
 homepage: https://github.com/lessonly/accessly
 licenses:
 - MIT