trust 0.5.0

data/MIT-LICENSE

@@ -0,0 +1,23 @@
+Copyright 2012 Bingo Entreprenøren AS
+Copyright 2012 Teknobingo Scandinavia AS
+Copyright 2012 Knut I. Stenmark
+Copyright 2012 Patrick Hanevold
+
+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,244 @@
+# Trust
+
+### Trust is a no-nonsense framework for authorization control - for Ruby On Rails.
+
+- Why yet another authorization framework you may ask?
+
+Well, we used [DeclarativeAuthorization](http://github.com/stffn/declarative_authorization) for a while, but got stuck when it comes to name-spaces and inheritance. So, we investigated in the possibilities of using [CanCan](http://github.com/ryanb/cancan) and [CanTango](http://github.com/kristianmandrup/cantango), and found that CanCan could be slow, because all permissions has to be loaded on every request. CanTango has tackled this problem by implementing caching, but the framework is still evolving and seems fairly complex. At the same time, CanTango is role focused and not resource focused.
+
+### What will you benefit from when using Trust?
+
+* Resource focused permissions, not role focused
+* Complete support for inheritance in controllers
+* Complete support for namespaces, both controllers and models
+* Complete support for nested resources
+* Complete support for shortened associations (e.g. if you have models in name spaces that relates to other models in the name space)
+* Fast permission loading, where no cashing is needed. All permissions are declared on class level, so once loaded, they stay in memory.
+* Support for inheritance in the permissions model
+* Natural code evaluation in the permission declarations, i.e. you understand completely what is going on, because the implementation is done the way you implement condifitions in rails for validations and alike.
+* Automatic loading of instances and parents in controller
+
+### What is not supported in Trust
+
+* Loading datasets for the index action. You may use other plugins / gems for doing this, or you may implement your own mechanism.
+
+### Currently not supported, but may be in the future
+
+* Support for devise. However you may easily implement this by overriding one method in your controller.
+* cannot and cannot? expressions.
+
+# Install and Setup
+
+Install the gem
+
+    gem install trust
+
+### Define permissions
+
+Create the permissions file in your model directory. Example
+
+``` Ruby
+module Permissions
+  class Default < Trust::Permissions
+    role :system_admin do
+      can :manage
+      can :audit
+    end
+  end
+
+  class Account < Default
+    role :support, can(:manage)
+    role :accountant do
+      can :edit, :show, :if => :associated_with_client?
+    end
+    role :department_manager, :accountant do
+      can :create, :if => lambda { parent }
+    end
+
+    def associated_with_client?
+      parent && parent.is_a?(Client) && parent.operators.find(user.id)
+    end
+  end
+end
+```
+
+The following attributes will be accessible in a Permissions class:
+
+* ```subject``` - the resource that is currently being tested for authorization
+* ```parent```  - the parent of the authorization when resource is nested
+* ```user```    - the user accessing the resource
+* ```klass```   - the resource class
+* ```action```  - the action that triggered the authorization
+
+Keep in mind that the permission object will be instanciated to do authorization, and not the class.
+You can extend the Trust::Permissions with more functionality if needed.
+
+You can also create aliases for actions. We have defined a predefined set of aliases. See Trust::Permissions.action_aliases.
+Processing of aliases are done in such way that permissions per action is expanded when the permissions are loaded, so thif you define :update when declaring the permissions, there will be one permission for :update and one for :edit
+
+
+### Apply access control in controller
+
+Place ```trustee``` in your controller after the user has been identified. Something like this:
+
+``` Ruby
+class AccountsController < ApplicationController
+  login_required
+  trustee
+end
+```
+
+The trustee statement will set up 3 before_filters in your controller:
+  
+``` Ruby
+before_filter :set_user
+before_filter :load_resource
+before_filter :access_control
+```
+
+Trust assumes that ```current_user``` is accessible. The user object must respond to the method ```role_symbols``` which should return an array of one or more roles for the user.
+
+Handling access denied situations in your controller. Implement something like the following in your ApplicationController:
+
+``` Ruby
+class ApplicationController < ActionController::Base
+  rescue_from Trust::AccessDenied do |exception|
+    redirect_to root_url, :alert => exception.message
+    # or some other redirect
+  end
+end
+```
+
+### Define associations in your controller
+
+For nested resources you can easily define the associations using ```belongs_to``` like this:
+
+``` Ruby
+class AccountsController < ApplicationController
+  login_required
+  belongs_to :client
+  trustee
+end
+```
+
+You can specify as many associations as you like.
+
+
+## The can? and permits? method
+
+The can? method is accessible from controller and views. Here are some coding examples:
+
+#### In controller or views you will use can?
+
+``` Ruby
+can? :edit                          # does the current user have permission to edit the current resource? 
+                                    # If there is a nested resource, the parent is automatically associated
+can? :edit, @customer               # does the current user have permission to edit the given customer? 
+                                    # Parent is also passed on here.
+can? :edit, @account, @client       # is current user allowed to edit the account associated with the client?
+```
+
+#### On ActiveRecord objects you will use permits?
+
+``` Ruby
+@customer.permits? :edit            # does the current user have permission to edit the given customer?
+Customer.permits? :create, @client  # does the current user have permission to create customers?
+```
+
+## Instance variables
+
+The filter ```load_resource``` will automatically load the instance for the resource in the controller. It will by default use the controller_path to determine the name of the instance variable. Here are a couple of examples:
+
+``` Ruby
+UsersController => @user
+Account::CreditsController => @account_credit
+```
+
+If it is a nested resource, it will also instantiate the ```parent``` class, using the namedefined in belongs_to to determine the name. E.g. if you have defined belongs_to :client, it will look for the parameter ```:client_id``` and perform a find like ```Client.find(client_id)```. Finding the resource will be done through the association between the two, such as ```client.accounts.find(id)```.
+
+You can override the naming by specifying ```model``` like this
+
+``` Ruby
+class AccountsController < ApplicationController
+  login_required
+  model :wackount
+  trustee
+end
+```
+
+If you want to override the name with namespacing then
+
+``` Ruby
+class Account::CreditsController < ApplicationController
+  login_required
+  model :"account/wreckit"
+  trustee
+end
+```
+
+You can also access the instances in a generic manner if you like. Use following statements:
+  
+``` Ruby
+resource.instance => accesses the instance variable
+resource.parent   => accesses the parent instance
+```
+
+You can even assign these if you like. The resource is also exposed as helper, so you can access it in views.
+For simplicity we have also exposed an ```instances``` accessor that you can assign when you have a multirecord result,
+such as for index action.
+
+## Overriding defaults
+
+### Overriding resource permits in the controller
+
+Say you have a controller without a model or do not want to perform access control. You can turn off the featur in your controller
+
+``` Ruby
+class ApplicationController < ActionController::Base
+  login_required
+  trustee  # By default we want to test for permissions
+end
+
+class MyController < ApplicationController
+  trustee :off   # turns off all callbacks
+end
+```
+
+#### Alternatives
+``` Ruby
+class MyController < ApplicationController
+  set_user :off         # turns off set_user callback
+  load_resource :off    # do not load resources
+  access_control :off   # turn access control off
+end
+```
+
+#### More specifically
+For all call backs and ```trustee``` you can use ```:only``` and ```:except``` options.
+Example toggle create action off
+``` Ruby
+class MyController < ApplicationController
+  load_resource   :except => :create
+  access_control  :except => :create
+end
+```
+
+#### Yet another alternative, avoiding resource loading
+Avoid resource loading on ```show``` action
+``` Ruby
+class MyController < ApplicationController
+  actions :except => :show
+end
+```
+
+### Overriding set_user
+
+If you prefer to use some other user reference than current_user you can override the method ```set_user``` like this in your controller:
+
+``` Ruby
+def set_user
+  Trust::Authorization.user = User.current
+end
+```
+
+

data/Rakefile

@@ -0,0 +1,37 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Trust'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Dir.glob('lib/tasks/*.rake').each { |r| import r }
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/tasks/trust_tasks.rake

@@ -0,0 +1,42 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# 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.
+
+namespace :db do
+  DELEGATORS = [ :create, :drop, :migrate, :rollback, :setup ]
+  DESCRIPTORS = Hash[*`cd test/dummy; rake -T`.split("\n").select{ |line| line =~ /^rake db:/ }.map{ |line| line.split('#').map{ |str| str.strip } }.flatten]
+
+  DELEGATORS.each do |delegate|
+    desc DESCRIPTORS["rake db:#{delegate}"]
+    task delegate do
+      system "cd test/dummy; rake db:#{delegate}"
+    end
+  end
+
+  namespace :test do
+    desc 'preparte test database with schema'
+    task :prepare do
+      system "cd test/dummy; rake db:test:prepare"
+    end
+  end
+end

data/lib/trust/active_record.rb

@@ -0,0 +1,65 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# 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.
+
+module Trust
+  module ActiveRecord
+    extend ActiveSupport::Concern
+# = Trust::ActiveRecord extension
+# Extends ActiveRecord with the +permits?+ and +ensure_permitted!+ method on class and instances
+#
+# ==== Examples
+#
+#    # If current user is permitted to create customers, create it
+#    if Customer.permits? :create
+#      Customer.create attributes
+#    end
+#    
+#    # If current user is permitted to create accounts for the given customer, create it
+#    if Account.permits? :create, @customer
+#      Account.create attributes
+#    end
+#    
+#    # If current user is permitted to update the given customer, update it
+#    if @customer.permits? :update
+#      @customer.save
+#    end
+#    
+#    # Raise an exception if user is not permitted to update the given customer, else save it
+#    @customer.ensure_permitted! :update 
+#    @customer.save
+
+    included do
+      include ClassMethods
+    end
+    
+    module ClassMethods
+      def permits?(action, parent = nil)
+        Trust::Authorization.authorized?(action, self, parent)
+      end
+      def ensure_permitted!(action, parent = nil)
+        Trust::Authorization.authorize!(action, self, parent)
+      end
+    end
+  end
+end

data/lib/trust/authorization.rb

@@ -0,0 +1,85 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# 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.
+
+module Trust
+  class Authorization
+    class << self
+      # Returns true if user is authorized to perform +action+ on +object+ or +class+
+      # If +parent+ is given, +parent+ may be tested in the implemented Permissions class
+      # This method is called by the +can?+ method in Trust::Controller, and is normally 
+      # not necessary to call directly.
+      def authorized?(action, object_or_class, parent)
+        if object_or_class.is_a? Class
+          klass = object_or_class
+          object = nil
+        else
+          klass = object_or_class.class
+          object = object_or_class
+        end
+        # Identify which class to instanciate and then check authorization
+        auth = authorizing_class(klass)
+        # Rails.logger.debug "Trust: Authorizing class for #{klass.name} is #{auth.name}"
+        auth.new(user, action.to_sym, klass, object, parent).authorized?
+      end
+      
+      # Tests if user is authorized to perform +action+ on +object+ or +class+, with the 
+      # optional parent and raises Trust::AccessDenied exception if not permitted.
+      # If using this method directly, an optional +message+ can be passed in to 
+      # replace the default message used.
+      # This method is used by the +access_control+ method in Trust::Controller
+      def authorize!(action, object_or_class, parent, message = nil)
+        access_denied!(message, action, object_or_class, parent) unless authorized?(action, object_or_class, parent)
+      end
+      
+      def access_denied!(message = nil, action = nil, subject = nil, parent = nil) # nodoc
+        raise AccessDenied.new(message, action, subject)
+      end
+      
+      # returns the current +user+ being used in the authorization process
+      def user
+        Thread.current["current_user"] 
+      end
+      
+      # sets the current +user+ to be used in the authorization process.
+      # the +user+ is thread safe.
+      def user=(user)
+        Thread.current["current_user"] = user
+      end
+      
+    private
+      def authorizing_class(klass) # nodoc
+        auth = nil
+        klass.ancestors.each do |k|
+          break if k == ::ActiveRecord::Base
+          begin
+            auth = "::Permissions::#{k}".constantize
+            break
+          rescue
+          end
+        end
+        auth || ::Permissions::Default
+      end
+    end
+  end
+end

data/lib/trust/controller/properties.rb

@@ -0,0 +1,134 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# 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.
+
+module Trust
+  module Controller
+    class Properties
+      delegate :logger, :to => Rails
+      attr_reader :controller
+      attr_accessor :model
+      attr_accessor :associations
+      attr_accessor :new_actions
+      attr_accessor :member_actions
+      attr_accessor :collection_actions
+      
+      def initialize(controller, properties) # nodoc
+        @controller = controller
+        @model = controller.controller_path
+        if properties
+          @associations = properties.associations.dup
+          @new_actions = properties.new_actions.dup
+          @member_actions = properties.member_actions.dup
+          @collection_actions = properties.collection_actions.dup
+        else
+          @associations = {}
+          @new_actions = [:new, :create]
+          @member_actions = [:show, :edit, :update, :destroy]
+          @collection_actions = [:index]
+        end
+      end
+
+      class << self
+        # returns a controller properties object
+        # ensures controller properties are instantiated in a correct manner and that inheritance is supported
+        def instantiate(controller)
+          new(controller, controller.superclass.instance_variable_get(:@properties))
+        end
+      end
+
+      # returns or sets the model to be used in a controller
+      # If not set, the controller_path is used
+      # You can override the model to be accessed in a controller by setting the model
+      #
+      # ==== Example
+      #
+      #    # You have a controller which inherits from a generic controller and it has not the same name. Below
+      #    model :account # will assume that the class to be Account and instance variables to be @account/@accounts
+      #
+      #    # name spaced models
+      #    model :"customer/account"
+      #
+      def model(name = nil)
+        @model = name if name
+        @model
+      end
+      
+      # Returns the class for the model
+      def model_class
+        model.to_s.classify.constantize
+      end
+      
+      # Specify associated resources (nested resources)
+      # Example:
+      #   belongs_to :lottery
+      #   belongs_to :table, :card_game
+      #   belongs_to :card_game, :as => :bridge
+      #
+      def belongs_to(*resources)
+        raise ArgumentError, "You must specify at least one resource after belongs_to" unless resources
+        logger.debug "#{@model} belongs_to #{resources.inspect}"
+        options = resources.extract_options!
+        resources.each do |resource|
+          @associations[resource] = options[:as]
+        end
+      end
+      
+      def has_associations?
+        @associations.size > 0
+      end
+      
+      # actions(options)
+      # Options
+      #  :new => actions        # specify new actions - default id :new, :create
+      #  :member => actions     # specify member actions - default is :show, :edit, :update, :destroy
+      #  :collection => actions # specify collection actions - default is :index
+      #  :except => actions     # removes any standard actions
+      #  :only => actions       # selects only the standard actions specifiec
+      #  :add => {options}      # to add options, eg  :add => {:new => :confirm} 
+      #
+      def actions(options)
+        if add = options[:add]
+          self.new_actions += Array.wrap(add[:new]) if add[:new]
+          self.member_actions += Array.wrap(add[:member]) if add[:member]
+          self.collection_actions += Array.wrap(add[:collection]) if add[:collection]
+        end
+        self.new_actions = Array.wrap(options[:new]) if options[:new]
+        self.member_actions = Array.wrap(options[:member]) if options[:member]
+        self.collection_actions = Array.wrap(options[:collection]) if options[:collection]
+        if options[:only]
+          only = Array.wrap(options[:only])
+          self.new_actions &= only
+          self.member_actions &= only
+          self.collection_actions &= only
+        end
+        if options[:except]
+          except = Array.wrap(options[:except])
+          self.new_actions -= except
+          self.member_actions -= except
+          self.collection_actions -= except
+        end
+      end
+    end
+  end
+end