merb-auth-core 0.9.9 → 0.9.10

data/README.textile

@@ -5,9 +5,10 @@ Merb web framework.
 
 MerbAuth does not try to dictate what you should use as a user model, or how
 it should authenticate.  Instead it focuses on the logic required to check
-that an object passes authentication, and store authenticated objects in the
-session.  This is in fact the guiding principle of MerbAuth.  The Session is 
-used as the place for authentication, with a sprinkling of controller helpers.  
+that an object passes authentication, and store the keys of authenticated 
+objects in the session.  This is in fact the guiding principle of MerbAuth.  The Session is 
+used as the place for authentication, with a sprinkling of controller helpers.
+You can choose to protect a controller action, or a route / group of routes.  
 This makes sense to talk about an authenticated session. For example, inside
 your controller:
 
@@ -25,6 +26,9 @@ your controller:
 * session.abandon!                  
   sets the session to unauthenticated, and clears all session data
 
+* session.authenticate!
+  authenticates the session against the active strategies
+
 MerbAuth makes use of Merb's exception handling facilities which return correct
 HTTP status codes when a 200 OK would be inappropriate.  To fail a login, or 
 to force a login at any point in your controller code, simply raise an 
@@ -69,7 +73,7 @@ to the params hash, session etc.
 
 To pass authentication, simply return a non-nil
 non-false value from the @run!@ method.  Any false or nil value will cause
-that strategy to fail.  Then the next strategy will be tried :)  wait... what?
+that strategy to fail.  Then the next strategy will be tried.
 
 You can add as many strategies as you like and they will be tried one after
 another until either one is found that works (login), or none of them have
@@ -93,26 +97,23 @@ h3. Customizing the user_class
 
 Notice the @user_class@ method in the above strategy examples.  This is a convenience method on a strategy
 to provide you with the user_class to use for this strategy.  You can overwrite
-this method on a per strategy basis to use different user model types.
+this method on a per strategy basis to use different user model types.  You do not _have_ to use this method
+and it's only there to keep track of the "default" user class. (if any)
 
 By default the strategy#user_class method will defer to Merb::Authentication#user_class.  You can 
 set which is the "default class" that Merb::Authentication will use in the provided strategies by
-setting the class inside your model declaration.  
+setting it in Merb.root/merb/merb-auth/setup.rb
 
 <pre><code>
-  class Person
-    include DataMapper::Resource
-    
-    Merb::Authentication.user_class = self
     
-    #...
-  end
+    Merb::Authentication.user_class = Person
+
 </code></pre>
 
-This will cascade throughout the default strategies, and your own strategies vai that 
-Merb::Authentication::Strategy#user_class method.
+This will cascade throughout the default strategies, and your own strategies using the user class
+that you defined.  In this case Person. 
 
-There is no default class set for Activation by default
+There is no default class set for Merb::Authentication.user_class by default
 
 h3. Strategies and Inheritance
 
@@ -138,7 +139,7 @@ To activate a registered strategy:
   Merb::Authentication.activate!(:defualt_password_form) 
 </code></pre>
 
-You can easily mix this in with your own strategies. In you lib/authentication/strategies.rb
+You can easily mix this in with your own strategies. In you Merb.root/merb-auth/strategies.rb
 <pre><code>
   class MyStrategy < Merb::Authentication::Strategy
     def run!
@@ -155,7 +156,7 @@ You can easily mix this in with your own strategies. In you lib/authentication/s
   end
 </code></pre>
 
-This will collect them in order of decleration.  i.e.:
+This will collect them in order of declaration.  i.e.:
   MyStrategy, Merb::Authentication::Strategies::Basic::OpenID, AnotherStrategy
 
 h3. Customizing the order of the strategies
@@ -173,8 +174,35 @@ manually.
 It's possible to leave some out, and re-order existing ones.  It will error
 out if you specify one that doesn't exist though.
 
+h3. Authentication based on Routes
+
+With MerbAuth you can protect routes rather than individual actions on a controller.
+The benefit with doing this is that the request is stopped earlier in the request
+process.  This is a more efficient method of protection than controller based protection.
+
+The downside is that a controllers action is not guaranteed to be protected.  For example
+
+<pre><code>
+  
+  authenticate do 
+    match("/one").to(:controller => "one", :action => "index")
+  end
+  
+  match("/two").to(:controller => "one", :action => "index")
+  
+</code></pre> 
+
+The /one route is protected, but you can see that both of these routes point to the same 
+controller action.  If the One#index method is accessed through the /two route, there is 
+no protection.  You can specify which strategies to use as arguments to the authenticate method.
+The default strategies are used if there is no argument given.
+
 h3. Specifying selected strategies per action
 
+If you need to protect an action regardless of which route leads to it, you can use
+controller level protection.  Use a @before :ensure_authenticated@ filter to protect actions
+in your controller whenever the are accessed.  
+
 It's possible to configure each call to @ensure_authenticated@ with a custom list
 of strategies to run.  These will be run in order and should have an instance method
 of #run!
@@ -185,7 +213,8 @@ of #run!
                                             Merb::Authenticated::Strategies::Basic::Form,
                                             Merb::Authenticated::Strategies::Basic::BasicAuth, 
                                             Merb::Authenticated::Strategies::Basic::OpenID, 
-                                           ]
+                                           ],
+                                  :only => [:index]
     before :machine_only, :only => [:create]
     
     def index
@@ -212,13 +241,14 @@ h3. Where should Strategies be defined?
 
 You should store your strategies in 
 <pre><code>
-  lib
-  `-- authentication
+  merb
+  `-- merb-auth
       |-- setup.rb
       `-- strategies.rb
 </code></pre>
 
 This is a good place to put everything together so you can see what you're doing at a glance.
+It is also auto included by merb-auth-core when you're using it.
 
 h3. What Strategies are there?
 
@@ -228,7 +258,7 @@ h3. Storing you user object into the session
 
 You need to tell MerbAuth how to serialize your object into
 and out of the session.  If possible try not to store large or complex 
-data items in the session.
+data items in the session but just store the objects key.
 
 To configure your user object to go in and out of the session, here's how you
 could do it.
@@ -309,27 +339,26 @@ There's at least 4 ways to provide feedback to users for failed logins.
 h3. Additional checks / actions to perform after the user is found
 
 Sometimes you may need to perform additional operations on the user object
-before or after you grab it out of the database when authenticating it.  The
-Merb::Authentication class implements Extlib::Hook so you can just setup hooks to
-deal with this.
+after you have found a valid user in the strategy.  There is a hook method
+Merb::Authentication.after_authentication which is designed for this.
 
 Here's an example of checking that a user object is active after it's been
 found: 
 
-  after :authenticate! do |instance, *args|
-    raise Merb::Controller::Unauthenticated, "User Not Active" unless instance.user.active?
+  Merb::Authentication.after_authentication do |user, request, params|
+    user.active? ? user : nil
   end
+  
+Pass the user model on if everything is still ok.  Return nil if you decide in the
+after_authentication hook that the user should in fact not be allowed to be authenticated.
 
-bq. Notice that to fail the check we raised an Unauthenticated exception.  The
-session is available in that block as <code>session</code>
-
-Really that's all there is to it.  By default this plugin doesn't actually
+By default this plugin doesn't actually
 authenticate anything ;)  It's up to you to get your model going, and add an
-authentication strategy.  Just remember that to login, you just use
-@session.authenticate(request)@ inside a controller.  To logout use
+authentication strategy.
+
+To logout use
 @session.abandon!@ and to force a login at any time use 
 @raise Unauthenticated, "You Aren't Cool Enough"@
-Be aware that strategies may throw :halt for use as a before filter...  
 
 h3. Contributors 
 

data/Rakefile

@@ -9,7 +9,9 @@ require 'rake/testtask'
 
 
 GEM_NAME = "merb-auth-core"
-GEM_VERSION = Merb::VERSION
+PKG_BUILD   = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+GEM_VERSION = Merb::VERSION + PKG_BUILD
+
 AUTHOR = "Adam French, Daniel Neighman"
 EMAIL = "has.sox@gmail.com"
 HOMEPAGE = "http://merbivore.com/"
@@ -27,7 +29,7 @@ spec = Gem::Specification.new do |s|
   s.author = AUTHOR
   s.email = EMAIL
   s.homepage = HOMEPAGE
-  s.add_dependency('merb-core', '~>0.9.9')
+  s.add_dependency('merb-core', "~> #{Merb::VERSION}")
   s.add_dependency('extlib')
   s.require_path = 'lib'
   s.files = %w(LICENSE README.textile Rakefile TODO) + Dir.glob("{lib,spec}/**/*")

data/lib/merb-auth-core/authentication.rb

@@ -1,5 +1,6 @@
 module Merb
   class Authentication
+    module Strategies; end
     include Extlib::Hook
     attr_accessor :session
     attr_writer   :error_message
@@ -74,19 +75,30 @@ module Merb
       user = nil    
       # This one should find the first one that matches.  It should not run antother
       strategies.detect do |s|
+        s = Merb::Authentication.lookup_strategy[s] # Get the strategy from string or class
         unless s.abstract?
           strategy = s.new(request, params)
           user = strategy.run! 
           if strategy.halted?
-            self.headers  = strategy.headers
-            self.status   = strategy.status
-            self.body     = strategy.body
+            self.headers, self.status, self.body = [strategy.headers, strategy.status, strategy.body]
             halt!
             return
           end
           user
         end
       end
+      # Check after callbacks to make sure the user is still cool
+      Merb::Authentication.after_callbacks.each do |cb|
+        user = case cb
+        when Proc
+          cb.call(user, request, params)
+        when Symbol, String
+          user.send(cb)
+        end
+        break unless user
+      end if user
+      
+      # Finally, Raise an error if there is no user found, or set it in the session if there is.
       raise Merb::Controller::Unauthenticated, msg unless user
       self.user = user
     end
@@ -126,5 +138,25 @@ module Merb
     def fetch_user(session_contents = session[:user])
       raise NotImplemented
     end
+    
+    # Keeps track of strategies by class or string
+    # When loading from string, strategies are loaded withing the Merb::Authentication::Strategies namespace
+    # When loaded by class, the class is stored directly
+    def self.lookup_strategy
+      @strategy_lookup || reset_strategy_lookup!
+    end
+    
+    # Restets the strategy lookup.  Useful in specsd
+    def self.reset_strategy_lookup!
+      @strategy_lookup = Mash.new do |h,k| 
+        case k
+        when Class
+          h[k] = k
+        when String, Symbol
+          h[k] = Merb::Authentication::Strategies.full_const_get(k.to_s) 
+        end
+      end
+    end
+    
   end # Merb::Authentication
 end # Merb

data/lib/merb-auth-core/callbacks.rb

@@ -0,0 +1,34 @@
+module Merb
+  class Authentication
+    cattr_accessor :after_callbacks
+    @@after_callbacks = []
+    
+    # Use the after_authentication callbacks to setup things that should occur after the
+    # user is authenticated.  
+    #
+    # Pass in symbols, procs and or a block to the method to setup the callbacks.
+    # Callbacks are executed in the order they are added. 
+    #
+    # @params 
+    # <*callbacks:[Symbol|Proc]> The callback.. Symbol == method on the user object
+    #                                           Proc will be passed the user, request and param objects
+    # <&block> A block to check.  The user, request and params will be passed into the block
+    #
+    # To confirm that the user is still eligable to login, simply return the user from
+    # the method or block.  To stop the user from being authenticated return false or nil
+    #
+    # ====Example
+    #
+    #    Merb::Authentication.after_authentication do |user,request,params|
+    #       user.active? ? user : nil
+    #    end
+    #
+    # @api public
+    
+    def self.after_authentication(*callbacks, &block)
+      self.after_callbacks = after_callbacks + callbacks.flatten unless callbacks.blank?
+      after_callbacks << block if block_given?
+    end
+    
+  end
+end

data/lib/merb-auth-core/router_helper.rb

@@ -1,5 +1,25 @@
 Merb::Router.extensions do
-  
+  # Use this method in your router to ensure that the user is authenticated
+  #
+  # This will run through any strategies that you have setup, or that you declare
+  # as an argument to the authenticate method.
+  #
+  # ===Example
+  #  
+  #    authenticate(OpenID) do
+  #       resource :posts
+  #      
+  #       authenticate do
+  #         match("/").to(:controller => "home")
+  #       end
+  #    end
+  # 
+  # This is a simple example that shows protecting the entire set of routes for
+  # the posts resource with the OpenID strategy.  
+  #
+  # The match on "/" is protected, _first_ by the OpenID strategy,
+  # then by the dfeeault set of stratgies.  Strategies are applied from the
+  # outer block first, working to the inner blocks.
   def authenticate(*strategies, &block)
     p = Proc.new do |request, params|
       if request.session.authenticated?

data/lib/merb-auth-core/session_mixin.rb

@@ -1,57 +1,45 @@
 module Merb
   module Session
+      
+    # Access to the authentication object directly.  Particularly useful
+    # for accessing the errors.
+    # 
+    # === Example
+    #
+    #    <%= error_messages_for session.authentication %>
+    # 
+    def authentication
+      @authentication ||= Merb::Authentication.new(self)
+    end
+  
+    # Check to see if the current session is authenticated
+    # @return true if authenticated.  false otherwise
+    def authenticated?
+      authentication.authenticated?
+    end
   
-    def self.included(base)
-      base.send(:include, InstanceMethods)
-      base.send(:extend,  ClassMethods)
+    # Authenticates the session via the authentication object. 
+    #
+    # See Merb::Authentication#authenticate for usage
+    def authenticate!(request, params, *rest)
+      authentication.authenticate!(request, params, *rest)
     end
   
-    module ClassMethods    
-    end # ClassMethods
+    # Provides access to the currently authenticated user.
+    def user
+      authentication.user
+    end
   
-    module InstanceMethods
-    
-      # Access to the authentication object directly.  Particularly useful
-      # for accessing the errors.
-      # 
-      # === Example
-      #
-      #    <%= error_messages_for session.authentication %>
-      # 
-      def authentication
-        @authentication ||= Merb::Authentication.new(self)
-      end
-    
-      # Check to see if the current session is authenticated
-      # @return true if authenticated.  false otherwise
-      def authenticated?
-        authentication.authenticated?
-      end
-    
-      # Authenticates the session via the authentication object. 
-      #
-      # See Merb::Authentication#authenticate for usage
-      def authenticate!(request, params, *rest)
-        authentication.authenticate!(request, params, *rest)
-      end
-    
-      # Provides access to the currently authenticated user.
-      def user
-        authentication.user
-      end
-    
-      # set the currently authenticated user manually
-      # Merb::Authentication#store_user should know how to store the object into the session
-      def user=(the_user)
-        authentication.user = the_user
-      end
-    
-      # Remove the user from the session and clear all data.
-      def abandon!
-        authentication.abandon!
-      end
-    
-    end # InstanceMethods
+    # set the currently authenticated user manually
+    # Merb::Authentication#store_user should know how to store the object into the session
+    def user=(the_user)
+      authentication.user = the_user
+    end
+  
+    # Remove the user from the session and clear all data.
+    def abandon!
+      authentication.abandon!
+    end
   
   end # Session
 end # Merb

data/lib/merb-auth-core.rb

@@ -11,6 +11,7 @@ require 'merb-auth-core/authenticated_helper'
 require 'merb-auth-core/customizations'
 require 'merb-auth-core/bootloader'
 require 'merb-auth-core/router_helper'
+require 'merb-auth-core/callbacks'
 
 Merb::BootLoader.before_app_loads do
   # require code that must be loaded before the application 
@@ -23,4 +24,4 @@ end
 
 Merb::Plugins.add_rakefiles "merb-auth-core/merbtasks"
 
-Merb.push_path(:lib_authentication, Merb.root / "merb" / "merb-auth")
+Merb.push_path(:lib_authentication, Merb.root_path("merb" / "merb-auth"), "*.rb" )

data/spec/merb-auth-core/authentication_spec.rb

@@ -226,6 +226,41 @@ describe "Merb::Authentication Session" do
       Viking.captures.should == ["Stwo", "Sone"]
     end
     
+    
+    describe "Strategy loading as strings" do
+      
+      before :each do
+        Merb::Authentication.reset_strategy_lookup!
+        
+        class Merb::Authentication::Strategies::Zone < Merb::Authentication::Strategy
+          def run!
+            Viking.capture(Merb::Authentication::Strategies::Zone)
+            params[:z_one] 
+          end
+        end
+      end
+      
+      it "should allow for loading the strategies as strings" do
+        @request.params[:z_one] = "z_one"
+        @request.session.authenticate!(@request, @request.params, "Zone")
+        @request.session.user.should == "z_one"
+      end
+      
+      it "should raise a const misisng error when the error is not namespaced" do
+        @request.params[:pass_1] = "s_one"
+        lambda do
+          @request.session.authenticate!(@request, @request.params, "Sone")
+        end.should raise_error(NameError)
+      end
+        
+    
+      it "should allow a mix of strategies as strings or classes" do
+        @request.params[:pass_2] = "s_two"
+        @request.session.authenticate!(@request, @request.params, "Zone", Sone, Stwo)
+        Viking.captures.should == %w(Merb::Authentication::Strategies::Zone Sone Stwo)
+      end
+    end
+    
   end
   
   describe "user_class" do
@@ -315,4 +350,5 @@ describe "Merb::Authentication Session" do
   
 
 
+
 end

data/spec/merb-auth-core/callbacks_spec.rb

@@ -0,0 +1,103 @@
+require File.join(File.dirname(__FILE__), "..", 'spec_helper.rb')
+
+describe "Authentication callbacks" do
+  
+  before(:each) do
+    Merb::Authentication.after_callbacks.clear
+    clear_strategies!
+    Viking.captures.clear
+    
+    # A basic user model that has some simple methods 
+    # to set and aknowlege that it's been called  
+    class AUser
+      attr_accessor :active, :name
+      
+      def initialize(params)
+        params.each do |k,v|
+          instance_variable_set("@#{k}", v)
+        end
+      end
+      
+      def acknowledge(value)
+        Viking.capture(value)
+      end
+      
+      def acknowledge!(value = "default acknowledge")
+        throw(:acknowledged, value)
+      end
+
+      def method_missing(name, *args)
+        if /(.*?)\?$/ =~ name.to_s
+          !!instance_variable_get("@#{$1}")
+        end
+      end
+    end
+    
+    # Create a strategy to test the after stuff
+    class MyStrategy < Merb::Authentication::Strategy
+      def run!
+        AUser.new(request.params[:user] || {}) unless request.params[:no_user]
+      end
+    end
+  
+    @request  = fake_request
+    @params   = @request.params
+    @auth     = Merb::Authentication.new(@request.session)
+    puts Merb::Authentication.strategies.inspect
+  end
+  
+  after(:all) do
+    clear_strategies!
+    Merb::Authentication.after_callbacks.clear
+  end
+  
+  it "should allow you to setup a callback as a block" do
+    Merb::Authentication.after_authentication{ |user, request, params| user.acknowledge!("w00t threw it") }
+    result = catch(:acknowledged) do
+      @request.session.authenticate!(@request, @params)
+    end
+    result.should == "w00t threw it"
+  end
+  
+  it "should allow you to setup a callback as a method" do
+    Merb::Authentication.after_authentication(:acknowledge!)
+    result = catch(:acknowledged) do
+      result = @request.session.authenticate!(@request,@params)
+    end
+    result.should == "default acknowledge"
+  end
+  
+  it "should allow many callbacks to be setup and executed" do
+    Merb::Authentication.after_authentication{|u,r,p| u.acknowledge("first");  u}
+    Merb::Authentication.after_authentication{|u,r,p| u.acknowledge("second"); u}
+    @request.session.authenticate!(@request, @params)
+    Viking.captures.should == %w(first second)
+  end
+
+  it "should stop processing if the user is not returned from the callback" do
+    Merb::Authentication.after_authentication{|u,r,p| u.acknowledge("first");  nil}
+    Merb::Authentication.after_authentication{|u,r,p| u.acknowledge("second"); u}
+    lambda do
+      @request.session.authenticate!(@request,@params)
+    end.should raise_error(Merb::Controller::Unauthenticated)
+    Viking.captures.should == ["first"]
+  end
+  
+  it "should raise an Unauthenticated if a callback returns nil" do
+    Merb::Authentication.after_authentication{|u,r,p| nil }
+    lambda do
+      @request.session.authenticate!(@request,@params)
+    end.should raise_error(Merb::Controller::Unauthenticated)
+  end
+  
+  it "should not try to process the callbacks when no user is found" do
+    Merb::Authentication.after_authentication{|u,r,p| u.acknowledge("first");  u}
+    Merb::Authentication.after_authentication{|u,r,p| u.acknowledge("second"); u}
+    @request.params[:no_user] = true
+    lambda do
+      @request.session.authenticate!(@request,@params)
+    end.should raise_error(Merb::Controller::Unauthenticated)
+    Viking.captures.should be_empty
+  end
+    
+end

data/spec/merb-auth-core/router_helper_spec.rb

@@ -32,8 +32,6 @@ describe "router protection" do
     class Mthree < Mone; end
     class Mtwo < Mone; end
 
-
-    
     Merb::Router.prepare do
       to(:controller => "foo") do
         authenticate do

data/spec/spec_helper.rb

@@ -33,7 +33,7 @@ Spec::Runner.configure do |config|
   config.include(StrategyHelper)
 end
 
-class Exceptions < Application
+class Exceptions < Merb::Controller
   def unauthenticated
     session.abandon!
     "Login please"
@@ -88,6 +88,11 @@ class Viking
   
   def self.capture(klass)
     @captures ||= []
-    @captures << klass.name
+    case klass
+    when Class
+      @captures << klass.name
+    else
+      @captures << klass
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: merb-auth-core
 version: !ruby/object:Gem::Version 
-  version: 0.9.9
+  version: 0.9.10
 platform: ruby
 authors: 
 - Adam French, Daniel Neighman
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-13 00:00:00 -07:00
+date: 2008-10-21 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: 0.9.9
+        version: 0.9.10
     version: 
 - !ruby/object:Gem::Dependency 
   name: extlib
@@ -51,6 +51,7 @@ files:
 - lib/merb-auth-core/authenticated_helper.rb
 - lib/merb-auth-core/authentication.rb
 - lib/merb-auth-core/bootloader.rb
+- lib/merb-auth-core/callbacks.rb
 - lib/merb-auth-core/customizations.rb
 - lib/merb-auth-core/errors.rb
 - lib/merb-auth-core/merbtasks.rb
@@ -64,6 +65,7 @@ files:
 - spec/merb-auth-core
 - spec/merb-auth-core/activation_fixture.rb
 - spec/merb-auth-core/authentication_spec.rb
+- spec/merb-auth-core/callbacks_spec.rb
 - spec/merb-auth-core/customizations_spec.rb
 - spec/merb-auth-core/errors_spec.rb
 - spec/merb-auth-core/merb-auth-core_spec.rb
@@ -92,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: merb
-rubygems_version: 1.2.0
+rubygems_version: 1.3.0
 signing_key: 
 specification_version: 2
 summary: An Authentication framework for Merb