rarbac 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b27af0301b8f3c532aa0109fff3bec28f527d3f
+  data.tar.gz: 859f26fabf0a378010d3ecc0f2674207deb3fb57
+SHA512:
+  metadata.gz: e227b442d14f4f9a0941cae20ffc07cb8ec8761210cf121453744b68a33d87a095bc8e8f258b73c4948cf2b6b1a52aa4580ea4f4187299291556645dd8aedc34
+  data.tar.gz: df61f081255dfed12d44deb4678bfa8de5a0c618e823a561e11e7e5218048857ce256af6773f7c37f2f6f427e0889ceb6abaaaf5194332096f660d68a1a63bdd

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Tyler Margison
+
+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,189 @@
+rarbac
+======
+
+## What is rarbac?
+
+`rarbac` stands for "Rails Role-Based Access Control". I couldn't find a good
+gem that did RBAC and integrated with a Rails app, so I made one. Since this is
+basically a stripped down Rails project, I created it as a Rails engine
+(a.k.a. plugin).
+
+However, there was a UC Berkley project which did well but fell a little short
+and does not appear to be maintained any more, called
+[rails_access](https://github.com/ucberkeley/rails_access). You will probably
+see similarities in the data structure between that project and this
+one.
+
+## Installation
+
+You simply add the gem and then mount the engine.
+
+In your Gemfile:
+
+```ruby
+gem 'rarbac'
+```
+
+In `config/routes.rb`:
+
+```ruby
+mount Rarbac::Engine, at: "rarbac"
+```
+
+The project includes migrations for non-user data. Your Rails app must have, and
+supply, its own user model. To generate the migrations for `rarbac` simply run:
+
+    rake rarbac:install:migrations
+
+Then run migrations. One more step to ensure everything works properly. Open
+your user model and add the following to it:
+
+```ruby
+has_many :user_roles,                         class_name: "Rarbac::UserRole"
+has_many :roles,       through: :user_roles,  class_name: "Rarbac::Role"
+has_many :permissions, through: :roles,       class_name: "Rarbac::Permission"
+has_many :actions,     through: :permissions, class_name: "Rarbac::Action"
+
+include Rarbac::UserHelper
+```
+
+That may seem like a lot, but really we're just off-loading a lot of the
+querying work to the underlying `ActiveRecord` base (or whatever else you are
+using). If we didn't do this we would have to do things like:
+
+```ruby
+user.user_roles.roles.permissions.where(...)
+```
+
+By including all those `has_many X through: Y` statements, we can go straight to
+what we want:
+
+```ruby
+user.permissions.where(...)
+```
+
+With migrations installed, run, and the user model setup, start your application
+and enjoy! Read on to make the most out of `rarbac`.
+
+## How it works
+
+You will have a few new models, under the namespace `Rarbac`, called `Role`,
+`Action`, `Permission`, and `UserRole`.
+
+The `Role` model/table holds a collections of roles, with an optional
+description. e.g. "guest", "user", "admin".
+
+The `Action` model/table holds a collection of actions that a user may perform
+in the system. e.g. "new_post", "delete_post", "new_comment".
+
+The `Permission` model/table links roles to actions. e.g. "the `admin` role has
+permission to the `delete_post` action".
+
+The `UserRole` model/table links users to roles. e.g. "Jill has the `user`
+role".
+
+It is important to note that user ids are not uniquely kept in the `UserRole`
+model, so you may have a single user with more than one role.
+
+### Controller Filters
+
+You may use the `Rarbac` controller filters/functions by including
+`Rarbac::ApplicationHelper`. The only assumption made is the presence of a
+resource (function or attribute) named `current_user`. This is modeled after the
+popular authentication gem [Devise](https://github.com/plataformatec/devise).
+
+You may add `before_filter :ensure_permission!` to create role-based authorization
+on the controller and action being executed. For example:
+
+```ruby
+class PostsController < Rarbac::ApplicationController
+  before_filter :ensure_permission!
+
+  def show
+    ...
+  end
+
+  def destroy
+    ...
+  end
+end
+ ```
+
+If you had an `Action` specified for "posts#destroy", this would ensure that
+`current_user` had permission to that action. If no such action existed,
+however, it is assumed that you don't need permission and anyone, even
+un-authenticated users, would be allowed access to that route.
+
+You may also customize your filters using the normal application controller
+options:
+
+```ruby
+before_filter :ensure_permission!, only: :destroy
+```
+
+Now the filter only runs when the `destroy` action is being executed. You may
+also use the block method of invoking a filter to further customize your
+options:
+
+```ruby
+before_filter only: :destroy do |controller|
+  controller.ensure_permission!(:delete_post)
+end
+```
+
+But wait, there's more! What if you want to check a role rather than an
+individual permission to some action? Maybe an entire controller should be
+off-limits to everyone but those with the `admin` role. That's easy:
+
+```ruby
+before_filter do |controller|
+  controller.ensure_role!(:admin)
+end
+```
+
+Bonus: it accepts arrays of roles.
+
+```ruby
+before_filter do |controller|
+  controller.ensure_role!(:author, :admin)
+  # The above uses an "OR" operation; use the plural to perform "AND"
+  # e.g. controller.ensure_roles!(:author, :admin)
+end
+```
+
+Don't forget that you may create your own filter functions and call `ensure_*`
+from there. However, if you create a custom filter and have access to
+`current_user`, it might be better, and more configurable, to use the model
+functions defined in the next section.
+
+### Model Functions
+
+With the appropriate permissions added to your user model you may very easily
+check on a user's roles:
+
+```ruby
+user.has_role?(:admin)
+user.has_role?(:admin, :author)  # Singular noun implies "OR" operation
+                                 # e.g. has_role?(:admin) || has_role?(:author)
+user.has_roles?(:admin, :author) # Plural noun implies "AND" operation
+                                 # e.g. has_role?(:admin) && has_role?(:author)
+```
+
+And also permissions:
+
+```ruby
+user.has_permission?(:delete_post)
+```
+
+It's important to note that permissions don't accept arrays. Why? Because very
+rarely should you be checking for a collection of permissions in a single
+"question". If you want to know if a user has permission to multiple actions,
+more likely you actually want to know if the user is assigned to one or more
+roles instead. That's why the `has_role?` and `has_roles?` functions have the
+argument-array option.
+
+### View Helpers
+
+There is no explicit view helper system. The idea is that the controller filters
+will help control when a view is rendered, and the model functions can further
+control what is rendered within a template.

data/Rakefile

@@ -0,0 +1,21 @@
+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    = 'Rarbac'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/app/assets/stylesheets/rarbac/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/rarbac/application_controller.rb

@@ -0,0 +1,4 @@
+module Rarbac
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/rarbac/application_helper.rb

@@ -0,0 +1,55 @@
+module Rarbac
+  # Defines application helpers, useful in controllers to add RBAC filters.
+  module ApplicationHelper
+    # Ensure that `current_user` has at least one of the given roles. If no
+    # block is given, a failed check will render a header-only response with
+    # status code 403 (Forbidden).
+    #
+    # @param [Array<String>] args an argument list of roles.
+    # @param [Proc] block if given, invoked with a single parameter, which is
+    #   the result of the role check.
+    def ensure_role!(*args, &block)
+      has_something?(:has_role?, args, block)
+    end
+
+    # Ensure that `current_user` has all of the given roles. If no block is
+    # given, a failed check will render a header-only response with status code
+    # 403 (Forbidden).
+    #
+    # @param [Array<String>] args an argument list of roles.
+    # @param [Proc] block if given, invoked with a single parameter, which is
+    #   the result of the role check.
+    def ensure_roles!(*args, &block)
+      has_something?(:has_roles?, args, block)
+    end
+
+    # Ensure that `current_user` has permission to a given action. If no action
+    # name is supplied, this will instead use the currently-executing controller
+    # and action names. If no block is given, a failed check will render a
+    # header-only response with status code 403 (Forbidden).
+    #
+    # @param [String] action name of the action to check permissions for.
+    # @param [Proc] block if given, invoked with a single parameter, which is
+    #   the result of the role check.
+    def ensure_permission!(action=nil, &block)
+      unless action
+        # TODO: If not supplied an action, determine the controller name and
+        # action being invoked, and use that to generate an appropriate action
+        # name to check.
+      end
+
+      has_something?(:has_permission?, action, block)
+    end
+
+    private
+
+    def has_something?(method, args, &block)
+      success = current_user.send(method, args)
+      if block
+        block.call(success)
+      elsif !success
+        head status: 403
+      end
+    end
+  end
+end

data/app/helpers/rarbac/user_helper.rb

@@ -0,0 +1,38 @@
+module Rarbac
+  # A collection of useful functions to be used by the user model.
+  #
+  #     include Rarbac::UserHelper
+  #
+  # That's it! Now you have access to some awesome RBAC helper functions.
+  module UserHelper
+    # Determines if the user has one or more of the given roles linked to it.
+    #
+    # @param [String] args an argument list of one or more roles to check for.
+    # @return [true|false] true if the user is linked to at least one of the
+    #   given roles.
+    def has_role?(*args)
+      throw Exception.new("Must supply at least one role.") if args.empty?
+      roles.where(name: args).count > 0
+    end
+
+    # Determines if the user has all of the given roles linked to it.
+    #
+    # @param [String] args an argument list of one or more roles to check for.
+    # @return [true|false] true if the user is linked to all of the given roles.
+    def has_roles?(*args)
+      throw Exception.new("Must supply at least one role.") if args.empty?
+      roles.where(name: args).count == args.count
+    end
+
+    # Determines if the user has permission to a given action. If the action
+    # does not exist at all, it is assumed the action is publicly available.
+    #
+    # @param [String] action name of the action to check permission for.
+    # @return [true|false] true if the user has at least one role linked to it
+    #   with permission to the given action.
+    def has_permission?(action)
+      return true if Action.where(name: action).count == 0
+      actions.where(name: action).count > 0
+    end
+  end
+end

data/app/models/rarbac/action.rb

@@ -0,0 +1,7 @@
+module Rarbac
+  # Represents an action. Actions are linked to roles by way of the Permission
+  # model.
+  class Action < ActiveRecord::Base
+    has_many :permissions
+  end
+end

data/app/models/rarbac/permission.rb

@@ -0,0 +1,7 @@
+module Rarbac
+  # Permissions link actions to roles.
+  class Permission < ActiveRecord::Base
+    belongs_to :role
+    belongs_to :action
+  end
+end

data/app/models/rarbac/role.rb

@@ -0,0 +1,7 @@
+module Rarbac
+  # Represents a role. Roles are linked to actions by way of the Permission
+  # model.
+  class Role < ActiveRecord::Base
+    has_many :permissions
+  end
+end

data/app/models/rarbac/user_role.rb

@@ -0,0 +1,7 @@
+module Rarbac
+  # Links users to roles.
+  class UserRole < ActiveRecord::Base
+    belongs_to :user
+    belongs_to :role
+  end
+end

data/app/views/layouts/rarbac/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Rarbac</title>
+  <%= stylesheet_link_tag    "rarbac/application", media: "all" %>
+  <%= javascript_include_tag "rarbac/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rarbac::Engine.routes.draw do
+end

data/db/migrate/20140711030732_create_rarbac_roles.rb

@@ -0,0 +1,10 @@
+class CreateRarbacRoles < ActiveRecord::Migration
+  def change
+    create_table :rarbac_roles do |t|
+      t.string :name
+      t.string :description
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20140711030959_create_rarbac_actions.rb

@@ -0,0 +1,10 @@
+class CreateRarbacActions < ActiveRecord::Migration
+  def change
+    create_table :rarbac_actions do |t|
+      t.string :name
+      t.string :description
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20140711031154_create_rarbac_permissions.rb

@@ -0,0 +1,14 @@
+class CreateRarbacPermissions < ActiveRecord::Migration
+  def change
+    create_table :rarbac_permissions do |t|
+      t.integer :role_id
+      t.integer :action_id
+
+      t.timestamps
+    end
+
+    add_index :rarbac_permissions, :role_id
+    add_index :rarbac_permissions, :action_id
+    add_index :rarbac_permissions, [:role_id, :action_id], unique: true
+  end
+end

data/db/migrate/20140711031434_create_rarbac_user_roles.rb

@@ -0,0 +1,14 @@
+class CreateRarbacUserRoles < ActiveRecord::Migration
+  def change
+    create_table :rarbac_user_roles do |t|
+      t.integer :user_id
+      t.integer :role_id
+
+      t.timestamps
+    end
+
+    add_index :rarbac_user_roles, :user_id
+    add_index :rarbac_user_roles, :role_id
+    add_index :rarbac_user_roles, [:user_id, :role_id], unique: true
+  end
+end

data/lib/rarbac/engine.rb

@@ -0,0 +1,5 @@
+module Rarbac
+  class Engine < ::Rails::Engine
+    isolate_namespace Rarbac
+  end
+end

data/lib/rarbac/version.rb

@@ -0,0 +1,3 @@
+module Rarbac
+  VERSION = "0.0.1"
+end

data/lib/rarbac.rb

@@ -0,0 +1,4 @@
+require "rarbac/engine"
+
+module Rarbac
+end

data/lib/tasks/rarbac_tasks.rake

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

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: rarbac
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tyler Margison
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: An implementation of RBAC as a Rails engine/plugin.
+email: kolorahl@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/rarbac/application.css
+- app/controllers/rarbac/application_controller.rb
+- app/helpers/rarbac/application_helper.rb
+- app/helpers/rarbac/user_helper.rb
+- app/models/rarbac/action.rb
+- app/models/rarbac/permission.rb
+- app/models/rarbac/role.rb
+- app/models/rarbac/user_role.rb
+- app/views/layouts/rarbac/application.html.erb
+- config/routes.rb
+- db/migrate/20140711030732_create_rarbac_roles.rb
+- db/migrate/20140711030959_create_rarbac_actions.rb
+- db/migrate/20140711031154_create_rarbac_permissions.rb
+- db/migrate/20140711031434_create_rarbac_user_roles.rb
+- lib/rarbac.rb
+- lib/rarbac/engine.rb
+- lib/rarbac/version.rb
+- lib/tasks/rarbac_tasks.rake
+homepage: https://github.com/kolorahl/rarbac
+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.3.0
+signing_key: 
+specification_version: 4
+summary: RBAC for Rails
+test_files: []
+has_rdoc: