wnw_permissible 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ca90d99e80a44396bc21e25216575907dfc883d3983243311fc5baaf4518eaf
+  data.tar.gz: 6c593a7651f009d836faccc7c8d53bed7db610c90133605e4579669354b5347c
+SHA512:
+  metadata.gz: 2083bba551f6e5301bd57efcbf54c23e729c713e39243501e31d203705f911f5465500099e631a7fffbb13b947f7c864cf984e9b51a4404206f080769b990747
+  data.tar.gz: ee13414403c26292c008639ae600c4b670aa6b51e4d8bac87b0d977222d63cca73f444f03c5bee6e7b7b27cfae9099d58bbcf2fe832341761473055a31883d54

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 Working Not Working
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# Permissible
+Adds WNW-style authorization into a Rails app.
+
+[![Gem Version](https://badge.fury.io/rb/wnw-permissible.svg)](https://badge.fury.io/rb/wnw-permissible)
+[![Build Status](https://semaphoreci.com/api/v1/workingnotworking/wnw-permissible/branches/master/badge.svg)](https://semaphoreci.com/workingnotworking/wnw-permissible)
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wnw-permissible', :require => 'permissible'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Unfortunately the gem name "permissible" was already taken. :(
+
+## Usage
+In your `User` model (or any model you want to have roles and permissions) include the Permissible concern:
+
+```ruby
+class User < ApplicationRecord
+  include Permissible
+end
+```
+
+Now your `User` has roles, permissions and limits that you can check in your app. Create some roles and permissions:
+
+```ruby
+role = Role.create :name => 'admin'
+permission = Permission.create :name => 'access_admin'
+role.permissions << permission
+```
+
+```ruby
+user = User.first
+user.admin?             #=> true (with Rails logger warning)
+user.can_access_admin?  #=> true
+user.has_role? 'admin'  #=> true
+user.role_names         #=> ['admin']
+user.permissions        #=> [:access_admin]
+```
+
+### About Roles
+
+Role checks take the form of `[role]?` where `[role]` is the name of your role, like `admin?`. A Rails logger warning is output when you check roles in this manner since it's a bad practice: you should check permissions that a user has, not their role. Permissions are fluid and can move from role to role, so really it shouldn't matter what their named roles are, it matters what they can do.
+
+### About Permissions
+
+Permission checks take the form of "can_[permission]?" where `[permission]` is the name you give to the permission. So if you have a permission with a name of "access_admin" then you check for that permission with `can_access_admin?`
+
+Permissions are additive. If you have a permission, it returns `true`. If you don't have a permission, it returns false. If one role has a permission and the other does not, the user has that permission. There is no way for one role to force a permission to `false` if some other role provides it.
+
+## Role Limits
+
+In addition to permissions a role can also have limits on some aspect of your app. Consider a search engine where a guest can only perform 10 searches but an admin can perform an unlimited number.
+
+First create an attribute in the `RoleLimit` model that contains the value:
+
+```ruby
+# db/migrate/201806131200000_create_role_limit_searches.rb
+class CreateRoleLimitSearches < ActiveRecord::Migration[5.0]
+  def change
+    add_column :role_limits, :searches, :string
+  end
+end
+```
+
+Note that the column is a `:string`. The value contained in the column will be serialized (in YAML) so that it can contain arbitrary data that Rails will convert back to native datatypes for us.
+
+Now decorate `RoleLimit` to declare that your new attribute should be serialized:
+
+```ruby
+# app/decorators/role_limit_decorator.rb
+RoleLimit.class_eval do
+  serialize :searches
+end
+```
+
+Now add `RoleLimit` records for your roles and see how they work:
+
+```ruby
+admin = Role.create :name => 'admin'
+guest = Role.create :name => 'guest'
+admin.role_limits.create :searches => Float::INFINITY
+guest.role_limits.create :searches => 10
+
+alice = User.create
+alice.roles << admin
+bob = User.create
+bob.roles << guest
+
+alice.limit(:searches) #=> Infinity
+bob.limit(:searches) #=> 10
+```
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Permissible'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/models/authorization.rb

@@ -0,0 +1,7 @@
+class Authorization < ApplicationRecord
+  belongs_to :authorizable, :polymorphic => true, :touch => true
+  belongs_to :role
+
+  validates :role,         :presence => true
+  validates :authorizable, :presence => true
+end

data/app/models/concerns/permissible.rb

@@ -0,0 +1,94 @@
+module Permissible
+  extend ActiveSupport::Concern
+
+  PERMISSIBLE_PERMISSION_METHOD_REGEX = /^can_(.*)\?$/
+  PERMISSIBLE_ROLE_METHOD_REGEX = /\?$/
+
+  included do
+    has_many :authorizations, :as => :authorizable, :dependent => :destroy
+    has_many :roles,          :through => :authorizations
+    has_many :role_limits,    :through => :roles
+  end
+
+  def method_missing(method_id, *args)
+    case
+    when _permission_match?(method_id)
+      return has_permission?(_method_to_permission_name(method_id))
+    when _role_match?(method_id)
+      _role_check_warning(method_id)
+      return has_role?(_method_to_role_name(method_id))
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(method_id, *args)
+    _permission_match?(method_id) or
+      _role_match?(method_id) or
+      super
+  end
+
+  # list of permissions granted by roles, as :symbols
+  def permissions
+    @permissions ||= _permission_names_for_roles(roles).sort
+  end
+
+  def has_permission?(name)
+    permissions.include?(name)
+  end
+
+  def has_role?(name)
+    roles.where(:name => name).any?
+  end
+
+  def role_names
+    roles.pluck(:name)
+  end
+
+  # since a user can have multiple roles, take the max value of their limits:
+  #
+  #   user.limit(:searches) #=> 8
+  def limit(attribute)
+    role_limits.pluck(attribute).max
+  end
+
+  # is method in the form of `can_something?`
+  private def _permission_match?(name)
+    !!(name.to_s =~ PERMISSIBLE_PERMISSION_METHOD_REGEX)
+  end
+
+  # is method in the form of `role?`
+  private def _role_match?(name)
+    name.to_s.match(PERMISSIBLE_ROLE_METHOD_REGEX) and
+      Role.where(:name => name.to_s.chop).any?
+  end
+
+  # converts a permission method check into a name: :can_do_this? => :do_this
+  private def _method_to_permission_name(name)
+    name.to_s.match(PERMISSIBLE_PERMISSION_METHOD_REGEX)[1].to_sym
+  end
+
+  # convers a role method check into a name: :admin? => 'admin'
+  private def _method_to_role_name(name)
+    name.to_s.chop
+  end
+
+  # Outputs a warning in the Rails log if a check for a user's role is found.
+  # The best practice is to only check if someone can do something, not if they
+  # have a certain title:
+  # http://programmers.stackexchange.com/questions/299729/role-vs-permission-based-access-control
+  private def _role_check_warning(method_id)
+    if Rails.env.development? or Rails.env.test?
+      position = caller.at(1).sub(%r{.*/},'').sub(%r{:in\s.*},'')
+      Rails.logger.warn "\033[0;33m  WARNING: You should really be checking for individual permissions, not roles! #{self.class.name.to_s}##{method_id.to_s} called from #{position}"
+    end
+  end
+
+  # returns an array of symbols with the permission names granted by the given
+  # role(s)
+  private def _permission_names_for_roles(roles)
+    RolePermission.joins(:permission).where(:role_id => roles).distinct
+      .pluck(Permission.arel_table[:name]).collect(&:to_sym)
+  end
+
+end

data/app/models/permission.rb

@@ -0,0 +1,6 @@
+class Permission < ApplicationRecord
+  has_many :role_permissions, :dependent => :destroy
+  has_many :roles,            :through => :role_permissions
+
+  validates :name, :presence => true, :uniqueness => true
+end

data/app/models/role.rb

@@ -0,0 +1,16 @@
+class Role < ApplicationRecord
+  has_many :role_permissions, :dependent => :destroy
+  has_many :permissions,      :through => :role_permissions
+  has_many :authorizations,   :dependent => :destroy
+  has_many :role_limits,      :dependent => :destroy
+
+  validates :name, :presence => true, :uniqueness => true
+
+  def limit(attribute)
+    role_limits.pluck(attribute).max
+  end
+
+  def human_name
+    name.split('_').last.titlecase
+  end
+end

data/app/models/role_limit.rb

@@ -0,0 +1,3 @@
+class RoleLimit < ApplicationRecord
+  belongs_to :role
+end

data/app/models/role_permission.rb

@@ -0,0 +1,7 @@
+class RolePermission < ApplicationRecord
+  belongs_to :role
+  belongs_to :permission
+
+  validates :role,       :presence => true
+  validates :permission, :presence => true
+end

data/lib/generators/wnw_permissible/USAGE

@@ -0,0 +1,2 @@
+Description:
+  Generates (but does not run) a migration to add required tables.

data/lib/generators/wnw_permissible/install_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module WnwPermissible
+  # Installs PaperTrail in a rails app.
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    MODELS = ['authorization', 'permission', 'role', 'role_limit', 'role_permission']
+
+    source_root File.expand_path("templates", __dir__)
+    class_option(
+      :with_changes,
+      :type => :boolean,
+      :default => false,
+      :desc => "Store changeset (diff) with each version"
+    )
+
+    desc "Generates (but does not run) a migration to add a required tables."
+
+    def create_model_files
+      MODELS.each do |model|
+        if File.exist? File.join(destination_root,'app','models',"#{model}.rb")
+          ::Kernel.warn "Migration already exists: #{model}.rb"
+        else
+          template "model.rb.erb", "app/models/#{model}.rb", :model => model
+        end
+      end
+    end
+
+    def create_migration_files
+      migration_dir = File.expand_path("db/migrate")
+
+      MODELS.each do |template|
+        template_name = "create_#{template.pluralize}"
+        if self.class.migration_exists?(migration_dir, template_name)
+          ::Kernel.warn "Migration already exists: #{template_name}"
+        else
+          migration_template(
+            "#{template_name}.rb.erb",
+            "db/migrate/#{template_name}.rb",
+            :migration_version => migration_version
+          )
+        end
+      end
+    end
+
+    def self.next_migration_number(dirname)
+      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    def migration_version
+      major = ActiveRecord::VERSION::MAJOR
+      if major >= 5
+        "[#{major}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+
+  end
+end

data/lib/generators/wnw_permissible/templates/authorization.rb.erb

@@ -0,0 +1,8 @@
+# Created by WnwPermissible to contain any custom model code. It's safe to
+# delete this file if you do not need any custom functionality in the model.
+
+require_dependency WnwPermissible::Engine.config.root.join('app', 'models', 'authorization.rb').to_s
+
+class Authorization
+  # add custom model code here
+end

data/lib/generators/wnw_permissible/templates/create_authorizations.rb.erb

@@ -0,0 +1,14 @@
+class CreateAuthorizations < ActiveRecord::Migration<%= migration_version %>
+
+  def change
+    create_table :authorizations do |t|
+      t.references :authorizable, :polymorphic => true
+      t.references :role,         :foreign_key => true
+
+      t.timestamps
+    end
+
+    add_index :authorizations, [:authorizable_id, :authorizable_type]
+  end
+
+end

data/lib/generators/wnw_permissible/templates/create_permissions.rb.erb

@@ -0,0 +1,14 @@
+class CreatePermissions < ActiveRecord::Migration<%= migration_version %>
+
+  def change
+    create_table :permissions do |t|
+      t.string :name
+      t.text   :description
+
+      t.timestamps
+    end
+
+    add_index :permissions, :name, :unique => true
+  end
+
+end

data/lib/generators/wnw_permissible/templates/create_role_limits.rb.erb

@@ -0,0 +1,11 @@
+class CreateRoleLimits < ActiveRecord::Migration<%= migration_version %>
+
+  def change
+    create_table :role_limits do |t|
+      t.references :role, :foreign_key => true
+
+      t.timestamps
+    end
+  end
+
+end

data/lib/generators/wnw_permissible/templates/create_role_permissions.rb.erb

@@ -0,0 +1,12 @@
+class CreateRolePermissions < ActiveRecord::Migration<%= migration_version %>
+
+  def change
+    create_table :role_permissions do |t|
+      t.references :role,       :foreign_key => true
+      t.references :permission, :foreign_key => true
+
+      t.timestamps
+    end
+  end
+
+end

data/lib/generators/wnw_permissible/templates/create_roles.rb.erb

@@ -0,0 +1,14 @@
+class CreateRoles < ActiveRecord::Migration<%= migration_version %>
+
+  def change
+    create_table :roles do |t|
+      t.string :name
+      t.text   :description
+
+      t.timestamps
+    end
+
+    add_index :roles, :name, :unique => true
+  end
+
+end

data/lib/generators/wnw_permissible/templates/model.rb.erb

@@ -0,0 +1,8 @@
+# Created by WnwPermissible to contain any custom model code. It's safe to
+# delete this file if you do not need any custom functionality in the model.
+
+require_dependency WnwPermissible::Engine.config.root.join('app', 'models', '<%= config[:model] %>.rb').to_s
+
+class <%= config[:model].camelize %>
+  # add custom model code here
+end

data/lib/generators/wnw_permissible/templates/permission.rb.erb

@@ -0,0 +1,8 @@
+# Created by WnwPermissible to contain any custom model code. It's safe to
+# delete this file if you do not need any custom functionality in the model.
+
+require_dependency WnwPermissible::Engine.config.root.join('app', 'models', 'permission.rb').to_s
+
+class Permission
+  # add custom model code here
+end

data/lib/generators/wnw_permissible/templates/role.rb.erb

@@ -0,0 +1,8 @@
+# Created by WnwPermissible to contain any custom model code. It's safe to
+# delete this file if you do not need any custom functionality in the model.
+
+require_dependency WnwPermissible::Engine.config.root.join('app', 'models', 'role.rb').to_s
+
+class Role
+  # add custom model code here
+end

data/lib/generators/wnw_permissible/templates/role_limit.rb.erb

@@ -0,0 +1,8 @@
+# Created by WnwPermissible to contain any custom model code. It's safe to
+# delete this file if you do not need any custom functionality in the model.
+
+require_dependency WnwPermissible::Engine.config.root.join('app', 'models', 'role_limit.rb').to_s
+
+class RoleLimit
+  # add custom model code here
+end

data/lib/generators/wnw_permissible/templates/role_permission.rb.erb

@@ -0,0 +1,8 @@
+# Created by WnwPermissible to contain any custom model code. It's safe to
+# delete this file if you do not need any custom functionality in the model.
+
+require_dependency WnwPermissible::Engine.config.root.join('app', 'models', 'role_permission.rb').to_s
+
+class RolePermission
+  # add custom model code here
+end

data/lib/tasks/wnw_permissible_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :permissible do
+#   # Task goes here
+# end

data/lib/wnw_permissible/engine.rb

@@ -0,0 +1,11 @@
+module WnwPermissible
+  class Engine < ::Rails::Engine
+
+    config.to_prepare do
+      Dir.glob(Rails.root + "app/decorators/**/*_decorator*.rb").each do |c|
+        require_dependency(c)
+      end
+    end
+
+  end
+end

data/lib/wnw_permissible/version.rb

@@ -0,0 +1,3 @@
+module WnwPermissible
+  VERSION = '0.1.0'
+end

data/lib/wnw_permissible.rb

@@ -0,0 +1,5 @@
+require "wnw_permissible/engine"
+
+module WnwPermissible
+
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: wnw_permissible
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rob Cameron
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-06-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Include as a concern in your User model
+email:
+- rob@workingnotworking.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/authorization.rb
+- app/models/concerns/permissible.rb
+- app/models/permission.rb
+- app/models/role.rb
+- app/models/role_limit.rb
+- app/models/role_permission.rb
+- lib/generators/wnw_permissible/USAGE
+- lib/generators/wnw_permissible/install_generator.rb
+- lib/generators/wnw_permissible/templates/authorization.rb.erb
+- lib/generators/wnw_permissible/templates/create_authorizations.rb.erb
+- lib/generators/wnw_permissible/templates/create_permissions.rb.erb
+- lib/generators/wnw_permissible/templates/create_role_limits.rb.erb
+- lib/generators/wnw_permissible/templates/create_role_permissions.rb.erb
+- lib/generators/wnw_permissible/templates/create_roles.rb.erb
+- lib/generators/wnw_permissible/templates/model.rb.erb
+- lib/generators/wnw_permissible/templates/permission.rb.erb
+- lib/generators/wnw_permissible/templates/role.rb.erb
+- lib/generators/wnw_permissible/templates/role_limit.rb.erb
+- lib/generators/wnw_permissible/templates/role_permission.rb.erb
+- lib/tasks/wnw_permissible_tasks.rake
+- lib/wnw_permissible.rb
+- lib/wnw_permissible/engine.rb
+- lib/wnw_permissible/version.rb
+homepage: https://github.com/workingnotworking/wnw_permissible
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Adds role-based permissions to a Rails application
+test_files: []