credentials 2.1.0 → 2.2.0

data/HISTORY

@@ -1,3 +1,7 @@
+=== 2.2.0 / 2009-11-24
+
+* Added support for ActionController
+
 === 2.1.0 / 2009-11-12
 
 * Added support for :self

data/README.rdoc

@@ -82,7 +82,6 @@ and turned into a nice pretty error page.
 
 == To do
 
-* Proper documentation of the API.
 * Better support for groups would make integration with RBA systems easier.
 
 == License

data/VERSION

@@ -1 +1 @@
-2.1.0
+2.2.0

data/credentials.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{credentials}
-  s.version = "2.1.0"
+  s.version = "2.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Matt Powell"]
-  s.date = %q{2009-11-12}
+  s.date = %q{2009-11-24}
   s.description = %q{A generic actor/resource permission framework based on rules, not objects.}
   s.email = %q{fauxparse@gmail.com.com}
   s.extra_rdoc_files = [
@@ -29,10 +29,14 @@ Gem::Specification.new do |s|
      "lib/credentials.rb",
      "lib/credentials/allow_rule.rb",
      "lib/credentials/deny_rule.rb",
-     "lib/credentials/object_extensions.rb",
+     "lib/credentials/errors.rb",
+     "lib/credentials/extensions/action_controller.rb",
+     "lib/credentials/extensions/configuration.rb",
+     "lib/credentials/extensions/object.rb",
      "lib/credentials/rule.rb",
      "lib/credentials/rulebook.rb",
      "spec/.gitignore",
+     "spec/controllers/test_controller_spec.rb",
      "spec/credentials_spec.rb",
      "spec/domain.rb",
      "spec/rule_spec.rb",
@@ -50,7 +54,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.5}
   s.summary = %q{A generic actor/resource permission framework based on rules, not objects.}
   s.test_files = [
-    "spec/credentials_spec.rb",
+    "spec/controllers/test_controller_spec.rb",
+     "spec/credentials_spec.rb",
      "spec/domain.rb",
      "spec/rule_spec.rb",
      "spec/rulebook_spec.rb",

data/lib/credentials.rb

@@ -1,4 +1,8 @@
 require "credentials/rulebook"
-require "credentials/object_extensions"
+require "credentials/extensions/object"
 
-Object.send :include, Credentials::ObjectExtensions
+Object.send :include, Credentials::Extensions::Object
+
+if defined?(ActionController)
+  ActionController::Base.send :include, Credentials::Extensions::ActionController
+end

data/lib/credentials/errors.rb

@@ -0,0 +1,15 @@
+module Credentials
+  module Errors
+    class NotLoggedInError < StandardError
+      
+    end
+    
+    class AccessDeniedError < StandardError
+      attr_reader :args
+      
+      def initialize(*args)
+        @args = args
+      end
+    end
+  end
+end

data/lib/credentials/extensions/action_controller.rb

@@ -0,0 +1,97 @@
+module Credentials
+  module Extensions
+    module ActionController
+      module ClassMethods
+        # Specify a requirement for the currently logged-in user
+        # to be able to access particular actions.
+        # 
+        # The current user is determined by calling the method named in
+        # +self.class.current_user_method+ (default is +current_user+).
+        # If there is a rule set against the current action and no user
+        # is logged in, then a Credentials::Errors::NotLoggedInError is
+        # raised.
+        #
+        # Otherwise, the rules are treated like 'before' filters, with
+        # the result being either a pass (action is executed as normal)
+        # or a failure (Credentials::Errors::AccessDeniedError is raised).
+        # (Note that evaluation stops at the first failure.)
+        # 
+        # Just like ActionController's built-in filters, you can use
+        # +only+ and +unless+ to restrict the scope of your rules.
+        # 
+        # == Credential tests
+        #
+        # For the most part, these are carried out as you'd expect:
+        #     requires_permission_to :create, Post
+        #     # checks current_user.can? :create, Post
+        #
+        # However, the magic part is that any symbol arguments are
+        # evaluated against the current controller instance, if
+        # matching methods can be found, allowing you to do this:
+        #    class PostsController
+        #      requires_permission_to :edit, :current_post, 
+        #        :only => %w(edit update destroy)
+        #    
+        #      def edit
+        #        # ...
+        #      end
+        #    
+        #    protected
+        #      def current_post
+        #        @current_post ||= Post.find params[:id]
+        #      end
+        #    end
+        def requires_permission_to(*args)
+          options = (args.last.is_a?(Hash) ? args.pop : {}).with_indifferent_access
+          %w(only except).each do |key|
+            options[key] = Array(options[key]).map(&:to_sym) if options[key]
+          end
+          self.required_credentials = self.required_credentials + [ [ options, args ] ]
+        end
+        
+        def required_credentials #:nodoc:
+          read_inheritable_attribute(:required_credentials) || []
+        end
+
+        # Sets the method for determining the current user in a
+        # controller instance.
+        # (Default: +:current_user+)
+        def current_user_method(value = nil)
+          rw_config(:current_user_method, value, :current_user)
+        end
+        alias_method :current_user_method=, :current_user_method
+      end
+      
+    protected
+      # Acts as a +before_filter+ to check credentials before an action
+      # is executed.
+      #
+      # See Credentials::Extensions::ActionController::ClassMethods#requires_permission_to
+      # for more details.
+      def check_credentials
+        current_user = send self.class.current_user_method
+        current_action = action_name.to_sym
+        
+        self.class.required_credentials.each do |options, args|
+          next if options[:only] && !options[:only].include?(current_action)
+          next if options[:except] && options[:except].include?(current_action)
+
+          raise Credentials::Errors::NotLoggedInError unless current_user
+          evaluated = args.map { |arg| (arg.is_a?(Symbol) && respond_to?(arg)) ? send(arg) : arg }
+          
+          unless current_user.can?(*evaluated)
+            raise Credentials::Errors::AccessDeniedError
+          end
+        end
+      end
+      
+      def self.included(receiver) #:nodoc:
+        receiver.extend Credentials::Extensions::Configuration
+        receiver.extend ClassMethods
+
+        receiver.send :class_inheritable_writer, :required_credentials
+        receiver.before_filter :check_credentials
+      end
+    end
+  end
+end

data/lib/credentials/extensions/configuration.rb

@@ -0,0 +1,13 @@
+module Credentials #:nodoc:
+  module Extensions #:nodoc:
+    module Configuration #:nodoc:
+      def rw_config(key, value, default_value = nil, read_value = nil)
+        if value == read_value
+          inheritable_attributes.include?(key) ? read_inheritable_attribute(key) : default_value
+        else
+          write_inheritable_attribute(key, value)
+        end
+      end
+    end
+  end
+end

data/lib/credentials/extensions/object.rb

@@ -0,0 +1,89 @@
+module Credentials
+  module Extensions #:nodoc:
+    module Object
+      module ClassMethods
+        # The main method for specifying and retrieving the permissions of
+        # a member of this class.
+        #
+        # When called with a block, this method yields a Credentials::Rulebook
+        # object, allowing you to specify the class's credentials
+        # in a declarative fashion. For example:
+        #
+        #     class User
+        #       credentials do |user|
+        #         user.can :edit, User, :if => :administrator?
+        #         user.can :edit, :self
+        #       end
+        #     end
+        #
+        # You can also specify options in this way:
+        #
+        #     class User
+        #       credentials(:default => :allow) do |user|
+        #         user.cannot :eat, "ice cream", :if => :lactose_intolerant?
+        #       end
+        #     end
+        #
+        # The following options are supported:
+        #
+        # [+:default+] Whether to +:allow+ or +:deny+ permissions that aren't
+        #              specified explicitly. The default default (!) is +:deny+.
+        #
+        # When called without a block, +credentials+ just returns the class's
+        # Credentials::Rulebook, creating it if necessary.
+        def credentials(options = nil)
+          @credentials ||= Credentials::Rulebook.new(self)
+          if block_given?
+            @credentials.options.merge!(options) unless options.nil?
+            yield @credentials
+          else
+            raise ArgumentError, "you can only set options with a block" unless options.nil?
+          end
+          @credentials
+        end
+      
+        def inherited_with_credentials(child_class) #:nodoc:
+          inherited_without_credentials(child_class) if child_class.respond_to? :inherited_without_credentials
+          child_class.instance_variable_set("@credentials", Rulebook.for(child_class))
+        end
+      end
+    
+      # Returns true if the receiver has access to the specified resource or action.
+      def can?(*args)
+        self.class.credentials.allow? self, *args
+      end
+      alias_method :able_to?, :can?
+
+      # Allows you to use magic methods to test permissions.
+      # For example:
+      #
+      #     class User
+      #       credentials do |user|
+      #         user.can :edit, :self
+      #       end
+      #     end
+      #     
+      #     user = User.new
+      #     user.can_edit? user #=> true
+      def method_missing_with_credentials(sym, *args)
+        if sym.to_s =~ /\Acan_(.*)\?\z/
+          can? $1.to_sym, *args
+        else
+          method_missing_without_credentials sym, *args
+        end
+      end
+    
+      def self.included(receiver) #:nodoc:
+        receiver.extend ClassMethods
+
+        receiver.send :alias_method, :method_missing_without_credentials, :method_missing
+        receiver.send :alias_method, :method_missing, :method_missing_with_credentials
+      
+        class << receiver
+          alias_method :inherited_without_credentials, :inherited if respond_to? :inherited
+          alias_method :inherited, :inherited_with_credentials
+        end
+      end
+    end
+  end
+end

data/spec/controllers/test_controller_spec.rb

@@ -0,0 +1,99 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+class TestController < ActionController::Base
+  self.current_user_method = :logged_in_user
+  requires_permission_to :view, :stuff, :except => [ :public ]
+  requires_permission_to :break, :stuff, :only => [ :dangerous ]
+  
+  def index; end
+  def public; end
+  def dangerous; end
+  
+  def rescue_action(e)
+    raise e
+  end
+end
+
+class TestUser
+  credentials do |user|
+    user.can :view, :stuff
+    user.can :break, :stuff, :if => :special?
+  end
+end
+
+describe TestController do
+  it "should know how to specify access credentials" do
+    controller.class.should respond_to :requires_permission_to
+  end
+  
+  it "should use the right method to look up the current user" do
+    controller.class.current_user_method.should == :logged_in_user
+  end
+  
+  it "should check credentials on each request" do
+    controller.should_receive(:check_credentials)
+    get :index
+  end
+  
+  describe "when logged in" do
+    before :each do
+      @user = TestUser.new
+      controller.should_receive(:logged_in_user).and_return(@user)
+    end
+    
+    it "should display stuff" do
+      lambda {
+        get :index
+        response.should be_success
+      }.should_not raise_error(Credentials::Errors::NotLoggedInError)
+    end
+    
+    describe "as someone with permission to break stuff" do
+      before(:each) do
+        @user.stub!(:special?).and_return(true)
+        @user.should be_able_to(:view, :stuff)
+        @user.should be_able_to(:break, :stuff)
+      end
+      
+      it "should have access to dangerous actions" do
+        lambda {
+          get :dangerous
+          response.should be_success
+        }.should_not raise_error(Credentials::Errors::AccessDeniedError)
+      end
+    end
+    
+    describe "as someone without permission to break stuff" do
+      before(:each) do
+        @user.stub!(:special?).and_return(false)
+        @user.should_not be_able_to(:break, :stuff)
+      end
+      
+      it "should not have access to dangerous actions" do
+        lambda {
+          get :dangerous
+          response.should_not be_success
+        }.should raise_error(Credentials::Errors::AccessDeniedError)
+      end
+    end
+  end
+  
+  describe "when not logged in" do
+    before :each do
+      controller.should_receive(:logged_in_user).and_return(nil)
+    end
+    
+    it "should not have access to stuff" do
+      lambda {
+        get :index
+      }.should raise_error(Credentials::Errors::NotLoggedInError)
+    end
+    
+    it "should have access to public stuff" do
+      lambda {
+        get :public
+        response.should be_success
+      }.should_not raise_error(Credentials::Errors::AccessDeniedError)
+    end
+  end
+end

data/spec/domain.rb

@@ -1,8 +1,16 @@
-class Animal < Struct.new(:species, :hungry, :fast)
+class Animal
   credentials do |animal|
     animal.can :clean, :self
   end
   
+  attr_accessor :species, :hungry, :fast
+  
+  def initialize(species = nil, hungry = false, fast = false)
+    @species = species
+    @hungry = hungry
+    @fast = fast
+  end
+  
   def edible?
     false
   end

data/spec/spec_helper.rb

@@ -1,6 +1,11 @@
-$: << File.dirname(__FILE__) + "/../lib"
-require "credentials"
-require "spec"
-require "date"
+begin
+  require File.dirname(__FILE__) + '/../../../../spec/spec_helper'
+rescue LoadError
+  puts "NOTE: install rspec in your base app to test Rails integration"
+  $: << File.dirname(__FILE__) + "/../lib"
+  require "credentials"
+  require "spec"
+  require "date"
+end
 
 require File.join(File.dirname(__FILE__), "domain.rb")

data/tasks/spec.rake

@@ -38,7 +38,7 @@ namespace :spec do
     t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
     t.spec_files = FileList['spec/**/*_spec.rb']
     t.rcov = true
-    t.rcov_opts = ['--text-report --exclude "spec/*"']
+    t.rcov_opts = ['--text-report --rails --exclude "spec/*,application_controller.rb,application_helper.rb"']
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: credentials
 version: !ruby/object:Gem::Version 
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors: 
 - Matt Powell
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-12 00:00:00 +13:00
+date: 2009-11-24 00:00:00 +13:00
 default_executable: 
 dependencies: []
 
@@ -35,10 +35,14 @@ files:
 - lib/credentials.rb
 - lib/credentials/allow_rule.rb
 - lib/credentials/deny_rule.rb
-- lib/credentials/object_extensions.rb
+- lib/credentials/errors.rb
+- lib/credentials/extensions/action_controller.rb
+- lib/credentials/extensions/configuration.rb
+- lib/credentials/extensions/object.rb
 - lib/credentials/rule.rb
 - lib/credentials/rulebook.rb
 - spec/.gitignore
+- spec/controllers/test_controller_spec.rb
 - spec/credentials_spec.rb
 - spec/domain.rb
 - spec/rule_spec.rb
@@ -78,6 +82,7 @@ signing_key:
 specification_version: 3
 summary: A generic actor/resource permission framework based on rules, not objects.
 test_files: 
+- spec/controllers/test_controller_spec.rb
 - spec/credentials_spec.rb
 - spec/domain.rb
 - spec/rule_spec.rb

data/lib/credentials/object_extensions.rb

@@ -1,90 +0,0 @@
-module Credentials
-  module ObjectExtensions #:nodoc:
-    module ClassMethods
-      # The main method for specifying and retrieving the permissions of
-      # a member of this class.
-      #
-      # When called with a block, this method yields a Credentials::Rulebook
-      # object, allowing you to specify the class's credentials
-      # in a declarative fashion. For example:
-      #
-      #     class User
-      #       credentials do |user|
-      #         user.can :edit, User, :if => :administrator?
-      #         user.can :edit, :self
-      #       end
-      #     end
-      #
-      # You can also specify options in this way:
-      #
-      #     class User
-      #       credentials(:default => :allow) do |user|
-      #         user.cannot :eat, "ice cream", :if => :lactose_intolerant?
-      #       end
-      #     end
-      #
-      # The following options are supported:
-      #
-      # [+:default+] Whether to +:allow+ or +:deny+ permissions that aren't
-      #              specified explicitly. The default default (!) is +:deny+.
-      #
-      # When called without a block, +credentials+ just returns the class's
-      # Credentials::Rulebook, creating it if necessary.
-      def credentials(options = nil)
-        @credentials ||= Credentials::Rulebook.new(self)
-        if block_given?
-          @credentials.options.merge!(options) unless options.nil?
-          yield @credentials
-        else
-          raise ArgumentError, "you can only set options with a block" unless options.nil?
-        end
-        @credentials
-      end
-      
-      def inherited_with_credentials(child_class) #:nodoc:
-        inherited_without_credentials(child_class) if child_class.respond_to? :inherited_without_credentials
-        child_class.instance_variable_set("@credentials", Rulebook.for(child_class))
-      end
-    end
-    
-    module InstanceMethods
-      # Returns true if the receiver has access to the specified resource or action.
-      def can?(*args)
-        self.class.credentials.allow? self, *args
-      end
-      alias_method :able_to?, :can?
-
-      # Allows you to use magic methods to test permissions.
-      # For example:
-      #
-      #     class User
-      #       credentials do |user|
-      #         user.can :edit, :self
-      #       end
-      #     end
-      #     
-      #     user = User.new
-      #     user.can_edit? user #=> true
-      def method_missing_with_credentials(sym, *args)
-        if sym.to_s =~ /\Acan_(.*)\?\z/
-          can? $1.to_sym, *args
-        else
-          method_missing_without_credentials sym, *args
-        end
-      end
-    end
-    
-    def self.included(receiver) #:nodoc
-      receiver.extend         ClassMethods
-      receiver.send :include, InstanceMethods
-
-      receiver.send :alias_method, :method_missing_without_credentials, :method_missing
-      receiver.send :alias_method, :method_missing, :method_missing_with_credentials
-      
-      class << receiver
-        alias_method :inherited_without_credentials, :inherited if respond_to? :inherited
-        alias_method :inherited, :inherited_with_credentials
-      end
-    end
-  end
-end