action_access 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3a922a62dc47428db03349b5ab4381c32d669ea
+  data.tar.gz: 639f7cf2ce63e3783f7d33970ea874624f8c7981
+SHA512:
+  metadata.gz: 10c2835e378462860b56b636431ebb26ac196acd179c82703a72bb77cb61745352b97ed668d28f2999dc88a4deec16f0ac32d3c10794a42be1489dd103b37d94
+  data.tar.gz: 8a1b64c08c10887c41e55a1e8f16d2ed8677cd68a7f7ef42f050f8e04a7d517727e2651e7841c0cc8bfa84b195768ae7c43d99c168eaa0f6a6d61e2b96bf797a

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle/
+log/*.log
+pkg/
+test/dummy/db/*.sqlite3
+test/dummy/db/*.sqlite3-journal
+test/dummy/log/*.log
+test/dummy/tmp/
+test/dummy/.sass-cache

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+## Please read before contributing
+
+1. If you have questions about Action Access, use the
+[Mailing List](https://groups.google.com/d/forum/action_access) or
+[Stack Overflow](https://stackoverflow.com/questions/tagged/action_access).
+Do not post questions here.
+
+2. If you find a security bug, **DO NOT** submit an issue here.
+Please send an e-mail to [mgag.issues@gmail.com](mailto:mgag.issues@gmail.com)
+instead.
+
+3. Do a small search on the issues tracker before submitting your issue to
+see if it was already reported or fixed. In case it was not, create your report
+with a **clear description** of the issue and a **code sample** that
+demonstrates it. Include Rails and Action Access versions, and as much relevant
+information as possible. Tests or a sample application showing how the
+expected behavior is not occurring will be much appreciated.
+
+The more information you give, the easier it becomes to track the issue and fix
+it. Your goal should be to make it easy for yourself and others to replicate
+the bug and figure out a fix.
+
+Thanks for your time and support!

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+# Declare your gem's dependencies in action_access.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use debugger
+# gem 'debugger'

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    action_access (0.0.1)
+      rails (~> 4.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionmailer (4.1.6)
+      actionpack (= 4.1.6)
+      actionview (= 4.1.6)
+      mail (~> 2.5, >= 2.5.4)
+    actionpack (4.1.6)
+      actionview (= 4.1.6)
+      activesupport (= 4.1.6)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
+    actionview (4.1.6)
+      activesupport (= 4.1.6)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+    activemodel (4.1.6)
+      activesupport (= 4.1.6)
+      builder (~> 3.1)
+    activerecord (4.1.6)
+      activemodel (= 4.1.6)
+      activesupport (= 4.1.6)
+      arel (~> 5.0.0)
+    activesupport (4.1.6)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    arel (5.0.1.20140414130214)
+    builder (3.2.2)
+    erubis (2.7.0)
+    hike (1.2.3)
+    i18n (0.6.11)
+    json (1.8.1)
+    mail (2.6.1)
+      mime-types (>= 1.16, < 3)
+    mime-types (2.3)
+    minitest (5.4.1)
+    multi_json (1.10.1)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (4.1.6)
+      actionmailer (= 4.1.6)
+      actionpack (= 4.1.6)
+      actionview (= 4.1.6)
+      activemodel (= 4.1.6)
+      activerecord (= 4.1.6)
+      activesupport (= 4.1.6)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.1.6)
+      sprockets-rails (~> 2.0)
+    railties (4.1.6)
+      actionpack (= 4.1.6)
+      activesupport (= 4.1.6)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.3.2)
+    sprockets (2.12.2)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-rails (2.1.4)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      sprockets (~> 2.8)
+    sqlite3 (1.3.9)
+    thor (0.19.1)
+    thread_safe (0.3.4)
+    tilt (1.4.1)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  action_access!
+  sqlite3

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2014 Matías A. Gagliano
+
+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,283 @@
+# Action Access
+
+Action Access is an access control system for Ruby on Rails. It provides a
+modular and easy way to secure applications and handle permissions.
+
+It works at controller level focusing on what **actions** are accessible for
+the current user instead of handling models and their attributes.
+
+It also provides utilities for thorough control and some useful view helpers.
+
+
+## Installation
+
+Add `action_access` to the app's Gemfile, run the `bundle` command and restart
+any running server.
+
+```ruby
+# Gemfile
+gem 'action_access'
+```
+
+
+## Basic configuration
+
+The most important setting is the way to get the **clearance level** (role,
+user group, etc.), other than that it works out of the box.
+
+Action Access doesn't require users or authentication at all to function so
+you can get creative with the way you set and identify clearance levels.
+
+It only needs a `current_clearance_level` method that returns the proper
+clearance level for the current request. It can be a string or symbol and
+it doesn't matter if it's singular or plural, it'll be singularized.
+
+  * With `current_user`:
+
+    The default `current_clearance_level` method tests if it can get
+    `current_user.clearance_level` and defaults to `:guest` if not.
+
+    So, if you already have a `current_user` method you just need to add a
+    `clearance_level` method to the user. With a role based authorization you
+    may add the following to your `User` model:
+
+    ```ruby
+    class User < ActiveRecord::Base
+      belongs_to :role
+
+      def clearance_level
+        role.name
+      end
+    end
+    ```
+
+  * No `current_user`:
+
+    If there's no `current_user` you need to override `current_clearance_level`
+    with whatever logic that applies to your application.
+
+    Continuing with the role based example, you might do something like this:
+
+    ```ruby
+    class ApplicationController < ActionController::Base
+      def current_clearance_level
+        session[:role] || :guest
+      end
+    end
+    ```
+
+
+## Setting permissions
+
+Permissions are set through authorization statements using the **let** class
+method available in every controller. The first parameter is the clearance
+level (plural or singular) and the second is the action or list of actions.
+
+As a simple example, to allow administrators (and only administrators in this
+case) to delete articles you'd add the following to `ArticlesController`:
+
+```ruby
+class ArticlesController < ApplicationController
+  let :admins, :destroy
+
+  def destroy
+    # ...
+  end
+
+  # ...
+end
+```
+
+This will automatically **lock** the controller and only allow administrators
+accessing the destroy action. **Every other request** pointing to the controller
+**will be rejected** and redirected with an alert.
+
+### Real-life example:
+
+```ruby
+class ArticlesController < ApplicationController
+  let :admins, :all
+  let :editors, [:index, :show, :edit, :update]
+  let :all, [:index, :show]
+
+  def index
+    # ...
+  end
+
+  # ...
+end
+```
+
+These statements lock the controller and set the following:
+ * _Administrators_ (admins) are authorized to access any action.
+ * _Editors_ can list, view and edit articles.
+ * _Anyone else_ can **only** list and view articles.
+
+This case uses the special keyword `:all`, it means everyone if passed as the
+first argument or every action if passed as the second one.
+
+Again, any unauthorized request will be rejected and redirected with an alert.
+
+### Note about clearance levels
+
+Notice that in the previous examples we didn't need to define clearance levels
+or roles anywhere else in the application. With the authorization statement you
+both **define** them and **set their permissions**. The only requirement is
+that the clearance levels from the authorizations match the one returned by
+`current_clearance_level`.
+
+
+## Advanced configuration
+
+### Locked by default
+
+The `lock_access` class method forces controllers to be locked even if no
+permissions are defined, in such case every request will be redirected.
+
+This allows to ensure that an entire application or scope (e.g. `Admin`) is
+**locked by default**. Simply call `lock_access` inside `ApplicationController`
+or from a scope's base controller.
+
+```ruby
+class ApplicationController < ActionController::Base
+  lock_access
+
+  # ...
+end
+```
+
+To **unlock** a single controller (to make it "public") add `let :all, :all`,
+this will allow anyone to access any action in the controller.
+
+### Redirection path
+
+By default any unauthorized (or not explicitly authorized) access will be
+redirected to the **root path**.
+
+You can set or choose a different path by overriding the somewhat long but
+very clear `unauthorized_access_redirection_path` method.
+
+```ruby
+class ApplicationController < ActionController::Base
+
+  def unathorized_access_redirection_path
+    case current_user.clearance_level.to_sym
+      when :admin then admin_root_path
+      when :user  then user_root_path
+      else root_path
+    end
+  end
+
+  # ...
+end
+```
+
+### Alert message
+
+Redirections have a default alert message of "Not authorized.". To customize it
+or use translations set `action_access.redirection_message` in your locales.
+
+```yml
+# config/locales/en.yml
+en:
+  action_access:
+    redirection_message: "You are not allowed to do this!"
+```
+
+
+## Utilities
+
+### Fine Grained Access Control
+
+If further control is required, possibly because access depends on request
+parameters or some result from the database, you can use the `not_authorized!`
+method inside actions to reject the request and issue a redirection. It
+optionally takes a redirection path and a custom alert message.
+
+```ruby
+class ProfilesController < ApplicationController
+  let :user, [:edit, :update]
+
+  def update
+    unless params[:id] == current_user.profile_id
+      not_authorized! path: profile_path, message: "That's not your profile!"
+    end
+
+    # ...
+  end
+
+  # ...
+end
+```
+
+There are better ways to handle this particular case but it serves to outline
+the use of `not_authorized!` inside actions.
+
+### Model additions
+
+Action Access is bundled with some model utilities too. By calling
+`add_access_utilities` in any model it will extend it with a `can?` instance
+method that checks if the entity (commonly a user) is authorized to perform a
+given action on a resource.
+
+`can?` takes two arguments, the action and the resource, and a namespace option
+if needed. The resource can be a string, symbol, controller class or model
+instance. Action Access will do the possible to get the right controller out
+of the resource and the namespace (optional). In the end it returns a boolean.
+
+**Some examples:**
+
+```ruby
+@user.can? :edit, :articles, namespace: :admin
+@user.can? :edit, @admin_article                       # Admin::Article instance
+@user.can? :edit, Admin::ArticlesController
+# True if the user's clearance level allows her to access 'admin/articles#edit'.
+```
+
+`can?` depends on a `clearance_level` method in the model so don't forget it.
+Continuing with the `User` model from before:
+
+```ruby
+class User < ActiveRecord::Base
+  add_access_utilities
+
+  belongs_to :role
+
+  def clearance_level
+    role.name
+  end
+end
+```
+
+```erb
+<% if current_user.can? :edit, :articles %>
+  <%= link_to 'Edit article', edit_article_path(@article) %>
+<% end %>
+```
+
+### The keeper
+
+The **keeper** is the core of Action Access, it's the one that registers
+permissions and who decides if a clearance level grants access or not.
+
+It's available as `keeper` within controllers and views and as
+`ActionAccess::Keeper.instance` anywhere else. You can use it check permissions
+with the `lets?` method that takes the clearance level as the first argument,
+the rest are the same as `can?`.
+
+```ruby
+# Filter a list of users to only those allowed to edit articles.
+@users.select { |user| keeper.lets? user.role.name, :edit, :articles }
+```
+
+
+## License
+
+Action Access is released under the [MIT License](http://opensource.org/licenses/MIT).
+
+Copyright (c) 2014 Matías A. Gagliano.
+
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).