merb-auth-core 0.9.9

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Adam French, Daniel Neighman
+
+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.textile

@@ -0,0 +1,338 @@
+h2. merb-auth-core
+
+MerbAuth is an authentication framework for use with the
+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.  
+This makes sense to talk about an authenticated session. For example, inside
+your controller:
+
+* session.authenticated?  
+  returns true if the session has been
+  authenticated.  False otherwise # session.authenticate(controller)
+  authenticates the session based on customizable user defined rules 
+
+* session.user                      
+  returns the currently authenticated user object 
+
+* session.user= 
+  manually sets the currently authenticated user object 
+
+* session.abandon!                  
+  sets the session to unauthenticated, and clears all session data
+
+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 
+Unauthenticated exception, with an optional message and the user will be 
+presented with login page.  The login page is in fact the html view for
+Extensions#unauthenticated
+
+To protect your controllers, add a simple @before@ filter to your controller.
+
+<code> before :ensure_authenticated </code>
+
+It is possible to use MerbAuth with any object as a _user_ object, provided
+that object does not evaluate to false and it can be serialized in an out of the session.  
+For this reason, merb-auth-core does not try to implement even a simple login 
+form for you, since it may not meet your requirements.
+
+h3. How Does It Authenticate my arbitrary user?
+
+This is very similar to the BootLoader process in Merbs initialization.  
+You declare a class that inherits from Merb::Authentication::Strategy and
+define an instance method @run!@
+
+<pre><code>
+  class PasswordStrategy &lt Merb::Authentication::Strategy
+  
+    def run!
+      if params[:login] && params[:password]
+        user_class.authenticate(params[:login], params[:password])
+      end
+    end
+  end
+  
+</code></pre>
+
+bq. This login strategy uses the @authenticate@ method on the User class to 
+retrieve a user by @login@ and @password@.  Remember, you can put as much logic
+here as you require.  The strategy uses an instance variable so the full power of
+classes are available to your strategy.
+
+The strategy provides access to the current request giving you access
+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?
+
+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
+passed (failed attempt).
+
+<pre><code>
+    class PasswordLoginBasicAuth &lt Merb::Authentication::Strategy
+      def run!
+        if params[:api_key] && params[:api_token]
+          Machine.api_authenticate(params[:api_key], params[:api_token])
+        end
+      end
+    end
+</code></pre>
+
+Now that we have two, they will be executed in the order that they were declared
+when we call @session.authenticate!(self)@.  The first one that
+returns a value that doesn't evaluate to false, will be considered the winner.
+
+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.
+
+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.  
+
+<pre><code>
+  class Person
+    include DataMapper::Resource
+    
+    Merb::Authentication.user_class = self
+    
+    #...
+  end
+</code></pre>
+
+This will cascade throughout the default strategies, and your own strategies vai that 
+Merb::Authentication::Strategy#user_class method.
+
+There is no default class set for Activation by default
+
+h3. Strategies and Inheritance
+
+Strategies may be inherited multiple times to make the job of combining similar aspects easier.  
+You can inherit as many levels as you like and at any point you may mark a strategy as _abstract_
+
+An abstract strategy just means that it will not be run when it comes time to authenticate.  
+Instead it's good to put common logic in and then inherit from it to keep your strategies DRY.
+
+To mark a class as abstract, use the @abstract!@ class method.
+
+<pre><code>
+  class AbstractStrategy < Merb::Authentication::Strategy
+    abstract!
+  end
+</code></pre>
+
+At any point you can activate a registered strategy.  You don't need to register
+your strategies, you just declare them, but plugin developers make life easier when they do.
+
+To activate a registered strategy:
+<pre><code>
+  Merb::Authentication.activate!(:defualt_password_form) 
+</code></pre>
+
+You can easily mix this in with your own strategies. In you lib/authentication/strategies.rb
+<pre><code>
+  class MyStrategy < Merb::Authentication::Strategy
+    def run!
+      #...
+    end
+  end
+  
+  Merb::Authentication.activate!(:default_openid)
+  
+  class AnotherStrategy < Merb::Authentication::Strategy
+    def run!
+      #...
+    end
+  end
+</code></pre>
+
+This will collect them in order of decleration.  i.e.:
+  MyStrategy, Merb::Authentication::Strategies::Basic::OpenID, AnotherStrategy
+
+h3. Customizing the order of the strategies
+
+By default, strategies are run in the order they are declared.  It's possible
+to customize the order that the strategies are called.
+
+@Merb::Authentication.default_strategy_order@ will return an array of
+the strategy classes in the order that they will be run.  
+You can customize this by setting the default_strategy_order array
+manually.
+
+@Authenticateion.default_strategy_order.order = [Second, First, Fourth]@
+
+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. Specifying selected strategies per action
+
+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!
+
+<pre><code>
+  class ApiMethods < Application
+    before :ensure_authenticated, :with => [
+                                            Merb::Authenticated::Strategies::Basic::Form,
+                                            Merb::Authenticated::Strategies::Basic::BasicAuth, 
+                                            Merb::Authenticated::Strategies::Basic::OpenID, 
+                                           ]
+    before :machine_only, :only => [:create]
+    
+    def index
+      display @stuff
+    end
+
+    def create
+      stuff = Stuff.create(params[:stuff])
+      display stuff
+    end
+    
+    private
+    def machine_only
+      ensure_authentiated Merb::Authenticated::Strategies::Basic::OAuth, Merb::Authenticated::Strategies::Basic::BasicAuth
+    end
+  end
+</code></pre>
+
+You can see in this example that you can specify a list of strategies to use.
+These will be executed in the order of the array passed in, with the default order
+ignored completely.
+
+h3. Where should Strategies be defined?
+
+You should store your strategies in 
+<pre><code>
+  lib
+  `-- authentication
+      |-- 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.
+
+h3. What Strategies are there?
+
+See merb-auth-more
+
+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.
+
+To configure your user object to go in and out of the session, here's how you
+could do it.
+
+<pre><code>
+    class Merb::Authentication
+
+      # return the value you want stored in the session 
+      def store_user(user)
+        return nil unless user 
+        user.id
+      end
+
+      # session info is the data you stored in the session previously 
+      def fetch_user(session_info)
+        User.get(session_info)
+      end
+    end
+</code></pre>
+
+h3. Registering Strategies
+
+Intended for plugin developers as a way to make it easy to use 
+strategies there is the possibility to register a strategy without loading it.
+
+<pre><code>
+  Authentication.register(:my_strategy, "/absolute/path/to/strategy.rb")
+</code></pre>
+
+This then allows developers to use
+
+<pre><code>
+  Authentication.activate!(:my_strategy)
+</pre></code>
+
+h3. Providing feedback to users (Error Messages)
+
+There's at least 4 ways to provide feedback to users for failed logins. 
+
+* Overwrite Merb::Authentication#error_message  The return of this method is 
+  the default message that is passed to the Unauthenticated exception.  Overwrite
+  this to provide a very basic catch all message.
+* Provide a default message when you declare your before filter.
+  <pre><code>
+    before :ensure_authenticated, :with => [Openid, :message => "Could not log you in with open ID"]
+    # OR
+    before :ensure_authentication, :with => {:message => "Sorry Buddy... You Lose"}
+  </code></pre>
+  When you pass a message, it will replace the Merb::Authentication#error_message default for this
+  action
+* Use an after filter for your login action.  This can be used to set your messaging system.  For example:
+  <pre><code>
+    after :set_login_message, :only => [:create]
+    
+    private
+    def set_login_message
+      if session.authenticated?
+        flash[:message] = "Welcome"
+      else
+        flash[:error] = "Bad.. You Fail"
+      end
+    end
+  </code></pre>
+* Use the authentications error messaging inside your strategies to set error messages there.
+  You can add to these errors just like adding to DataMappers validation errors.
+  
+  <pre><code>
+    session.authentication.errors.add("Label", "You Fail")
+  </code></pre>
+  Add as many as you like, ask @session.authentication.errors.on(:label)@ to get specific errors etc
+  Really... They're just like the DataMapper validation errors.  The bonus of using this system
+  is that you can add messages inside your Strategies, and then in your views you can do this:
+  <pre><code>
+    <%= error_messages_for sessions.authentication %>
+  </pre></code>
+  
+
+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.
+
+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?
+  end
+
+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
+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
+@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 
+
+# Adam French - "http://adam.speaksoutofturn.com/":http://adam.speaksoutofturn.com/
+# Daniel Neighman - "http://merbunity.com":http://merbunity.com
+# Ben Burket - "http://benburkert.com/":http://benburkert.com/

data/Rakefile

@@ -0,0 +1,65 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'date'
+require "spec/rake/spectask"
+require File.join(File.dirname(__FILE__), "../../merb-core/lib/merb-core/version")
+require File.join(File.dirname(__FILE__), "../../merb-core/lib/merb-core/tasks/merb_rake_helper")
+require 'rake/testtask'
+
+
+GEM_NAME = "merb-auth-core"
+GEM_VERSION = Merb::VERSION
+AUTHOR = "Adam French, Daniel Neighman"
+EMAIL = "has.sox@gmail.com"
+HOMEPAGE = "http://merbivore.com/"
+SUMMARY = "An Authentication framework for Merb"
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'merb'
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README.textile", "LICENSE", "TODO"]
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.add_dependency('merb-core', '~>0.9.9')
+  s.add_dependency('extlib')
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README.textile Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new("specs") do |t|
+  t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_files = Dir["spec/**/*_spec.rb"].sort
+  t.rcov = false
+  t.rcov_opts << '--sort' << 'coverage' << '--sort-reverse'
+  t.rcov_opts << '--only-uncovered'
+end

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

@@ -0,0 +1,42 @@
+module Merb
+  class Controller::Unauthenticated < ControllerExceptions::Unauthorized; end
+  
+  module AuthenticatedHelper  
+    protected
+    # This is the main method to use as a before filter.  You can call it with options
+    # and strategies to use.  It will check if a user is logged in, and failing that
+    # will run through either specified.  
+    # 
+    # @params all are optional.  A list of strategies, optionally followed by a 
+    # options hash.  
+    #
+    # If used with no options, or only the hash, the default strategies will be used
+    # see Authentictaion.default_strategy_order.  
+    #
+    # If a list of strategies is passed in, the default strategies are ignored, and
+    # the passed in strategies are used in order until either one is found, or all fail.  
+    #
+    # A failed login will result in an Unauthenticated exception being raised.  
+    #
+    # Use the :message key in the options hash to pass in a failure message to the
+    # exception.
+    # 
+    # === Example
+    #
+    #    class MyController < Application
+    #      before :ensure_authenticated, :with => [OpenID,FormPassword, :message => "Failz!"]
+    #       #... <snip>
+    #    end
+    # 
+    def ensure_authenticated(*strategies)
+      session.authenticate!(request, params, *strategies) unless session.user
+      auth = session.authentication
+      if auth.halted?
+        self.headers.merge!(auth.headers)
+        self.status  = auth.status
+        throw :halt, auth.body
+      end
+      session.user
+    end 
+  end
+end

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

@@ -0,0 +1,130 @@
+module Merb
+  class Authentication
+    include Extlib::Hook
+    attr_accessor :session
+    attr_writer   :error_message
+  
+    class DuplicateStrategy < Exception; end
+    class MissingStrategy < Exception; end
+    class NotImplemented < Exception; end
+  
+    # This method returns the default user class to use throughout the
+    # merb-auth authentication framework.  Merb::Authentication.user_class can
+    # be used by other plugins, and by default by strategies.
+    #
+    # By Default it is set to User class.  If you need a different class
+    # The intention is that you overwrite this method
+    #
+    # @return <User Class Object>
+    #
+    # @api overwritable
+    cattr_accessor :user_class
+  
+    def initialize(session)
+      @session = session
+    end
+  
+    # Returns true if there is an authenticated user attached to this session
+    #
+    # @return <TrueClass|FalseClass>
+    # 
+    def authenticated?
+      !!user
+    end
+  
+    # This method will retrieve the user object stored in the session or nil if there
+    # is no user logged in.
+    # 
+    # @return <User class>|NilClass
+    def user
+      return nil if !session[:user]
+      @user ||= fetch_user(session[:user])
+    end
+  
+    # This method will store the user provided into the session
+    # and set the user as the currently logged in user
+    # @return <User Class>|NilClass
+    def user=(user)
+      session[:user] = nil && return if user.nil?
+      session[:user] = store_user(user)
+      @user = session[:user] ? user : session[:user]  
+    end
+  
+    # The workhorse of the framework.  The authentiate! method is where
+    # the work is done.  authenticate! will try each strategy in order
+    # either passed in, or in the default_strategy_order.  
+    #
+    # If a strategy returns some kind of user object, this will be stored
+    # in the session, otherwise a Merb::Controller::Unauthenticated exception is raised
+    #
+    # @params Merb::Request, [List,Of,Strategies, optional_options_hash]
+    #
+    # Pass in a list of strategy objects to have this list take precedence over the normal defaults
+    # 
+    # Use an options hash to provide an error message to be passed into the exception.
+    #
+    # @return user object of the verified user.  An exception is raised if no user is found
+    #
+    def authenticate!(request, params, *rest)
+      opts = rest.last.kind_of?(Hash) ? rest.pop : {}
+      rest = rest.flatten
+      strategies = rest.empty? ? Merb::Authentication.default_strategy_order : rest
+
+      msg = opts[:message] || error_message
+      user = nil    
+      # This one should find the first one that matches.  It should not run antother
+      strategies.detect do |s|
+        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
+            halt!
+            return
+          end
+          user
+        end
+      end
+      raise Merb::Controller::Unauthenticated, msg unless user
+      self.user = user
+    end
+  
+    # "Logs Out" a user from the session.  Also clears out all session data
+    def abandon!
+      @user = nil
+      session.clear
+    end
+  
+    # A simple error message mechanism to provide general information.  For more specific information
+    #
+    # This message is the default message passed to the Merb::Controller::Unauthenticated exception
+    # during authentication.  
+    #
+    # This is a very simple mechanism for error messages.  For more detailed control see Authenticaiton#errors
+    #
+    # @api overwritable
+    def error_message
+      @error_message || "Could not log in"
+    end
+  
+    # Tells the framework how to store your user object into the session so that it can be re-created 
+    # on the next login.  
+    # You must overwrite this method for use in your projects.  Slices and plugins may set this.
+    #
+    # @api overwritable
+    def store_user(user)
+      raise NotImplemented
+    end
+  
+    # Tells the framework how to reconstitute a user from the data stored by store_user.
+    #
+    # You must overwrite this method for user in your projects.  Slices and plugins may set this.
+    #
+    # @api overwritable
+    def fetch_user(session_contents = session[:user])
+      raise NotImplemented
+    end
+  end # Merb::Authentication
+end # Merb

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

@@ -0,0 +1,10 @@
+# This is not intended to be modified.  It is for use with
+# Merb::Authentication.default_customizations
+class Merb::BootLoader::MerbAuthBootLoader < Merb::BootLoader
+  before Merb::BootLoader::AfterAppLoads
+  
+  def self.run
+    Merb::Authentication.default_customizations.each { |c| c.call }
+  end
+  
+end

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

@@ -0,0 +1,24 @@
+module Merb
+  class Authentication
+  
+    class << self
+    
+      # Adds any customizations just before the after_app_loads boot loader
+      # so that plugins can offer default customization.  This will still allow
+      # for a user to overwrite any customizations if required in the after_app_loads
+      # block
+      # @plugin
+      def customize_default(&block)
+        default_customizations << block
+        default_customizations
+      end
+    
+      # Gets the list of declared customizations
+      def default_customizations
+        @custom_default_blocks ||= []
+      end
+    
+    end
+  
+  end # Merb::Authentication
+end # Merb