josevalim-auth_helpers 0.1.2 → 0.2.0

data/CHANGELOG

@@ -1,17 +1,12 @@
-# Version 0.1
+# Version 0.2
 
 * First version with the following modules:
 
   AuthHelpers::Model::Associatable
-  AuthHelpers::Model::Authenticable
   AuthHelpers::Model::Confirmable
   AuthHelpers::Model::Recoverable
-  AuthHelpers::Model::Rememberable
-  AuthHelpers::Model::Validatable
+  AuthHelpers::Model::Updatable
 
 Plus:
 
   AuthHelpers::Notifier
-  AuthHelpers::Migration
-
-The first to deal with Notifications and the second with migrations.

data/README

@@ -9,20 +9,9 @@ You can also read this README in pretty html at the GitHub project Wiki page:
 Description
 -----------
 
-AuthHelpers is a collection of modules to include in your model to deal with
-authentication.
-
-Why? Authentication is something that you need to do right since the beginning,
-otherwise it will haunt you until the end of the project.
-
-Gladly, Rails community has two awesome gems for this: Clearance and AuthLogic.
-While the first gives you a simple but full, ready-to-go engine, the second
-is a complex, fully featured authencation library.
-
-While working in different projects, requisites change and sometimes you need
-something that works between something simple and something fully featured. This
-is the scope of AuthHelpers: you have modules and you include them where you
-want.
+AuthHelpers is a collection of modules to improve your Authlogic models. It
+mainly exposes some convenience methods to help on confirmation and passwords
+management, it also deals automatically with associations and notifications.
 
 Installation
 ------------
@@ -41,14 +30,15 @@ Modules
 -------
 
   class Account < ActiveRecord::Base
-    SALT = APP_NAME
+    acts_as_authentic do |a|
+      a.validations_scope = :accountable_type
+      a.require_password_confirmation = false
+    end
 
     include AuthHelpers::Model::Associatable
-    include AuthHelpers::Model::Authenticable
     include AuthHelpers::Model::Confirmable
     include AuthHelpers::Model::Recoverable
-    include AuthHelpers::Model::Rememberable
-    include AuthHelpers::Model::Validatable
+    include AuthHelpers::Model::Updatable
   end
 
 == Associatable
@@ -58,53 +48,45 @@ in the table. This module exists because, whenever it's possible, I follow the
 pattern of having an account model and then all accountable objects uses this
 model (it autodetects polymorphic associations too).
 
-== Authenticable
-
-It adds password, salt and encrypt behavior. Adds find_and_authenticate class
-method and authenticate?(password) as instance method. It requires a constant
-named SALT set in your model. 
-
 == Confirmable
 
-Adds the confirmation_code handling. It sends an e-mail to the user on account
-creation, and adds find_and_confirm, find_and_resend_confirmation_code as class
-methods and confirmed? and confirm as instance methods.
+Adds the confirmation handling. It sends an e-mail to the user on account
+creation, and adds find_and_confirm, find_and_resend_confirmation_instructions
+as class methods plus confirmed? and confirm! as instance methods.
 
-When used with Authenticable, also sends an e-mail with a new confirmation code
-whenever the user changes his e-mail address.
+When used with Updatable, also sends an e-mail the user changes his e-mail address.
 
 == Recoverable
 
-Adds the reset_password_code handling. Adds find_and_resend_confirmation_code
-and find_and_reset_password class methods.
-
-== Rememberable
+Adds the reset password code handling. Adds find_and_resend_confirmation_instructions
+and find_and_reset_password class methods plus reset_password instance method.
 
-Manages a token to be stored in cookies. Adds find_by_remember_me_token (which
-only returns a record if the token hasn't expired yet), remember_me! and forget_me!
-methods.
+== Updatable
 
-Whenever used with Authentication, it handles the remember_me method inside
-find_and_authenticate.
+It adds email and password confirmations and hack into update_attributes to
+ensure the another confirmation instruction is sent when the user changes the
+e-mail.
 
-== Validatable
+Authlogic already supports password confirmation, but it's coupled with the
+validates_length_of :password_confirmation, which is unecessary. So in order
+to use this module, is advisable to disable require_password_confirmation from
+Authlogic.
 
-Add validations to your e-mail and password. If you have a constant in your model
-named SCOPE, it will add this to validate_uniqueness_of.
+  acts_as_authentic do |a|
+    a.require_password_confirmation = false
+  end
 
 Specs
 -----
 
-All those modules comes with specs, that's why the library has not tests per se.
+All modules come with specs, that's why the library does not have tests per se.
 So if you want to test the Account model declared above, just do:
 
   describe Account do
     include AuthHelpers::Spec::Associatable
-    include AuthHelpers::Spec::Authenticable
     include AuthHelpers::Spec::Confirmable
     include AuthHelpers::Spec::Recoverable
-    include AuthHelpers::Spec::Rememberable
-    include AuthHelpers::Spec::Validatable
+    include AuthHelpers::Spec::Updatable
 
     before(:each) do
       @valid_attributes = {
@@ -120,28 +102,8 @@ So if you want to test the Account model declared above, just do:
     end
   end
 
-The only requisite you have for the tests is to have a @valid_attributes instance
-variable set with a hash of valid attributes. You also need Remarkable to run
-those tests.
-
-Migrations
-----------
-
-While AuthHelpers gives you the flexibity to choose which model you want to add
-your validations, it takes from you the freedom to choose what are the column
-names. However it makes easier to create your migrations. This is a migration up
-example for the Account model above:
-
-  create_table :accounts do |t|
-    t.references :accountable, :polymorphic => true
-    t.extend AuthHelpers::Migration
-
-    t.authenticable
-    t.confirmable
-    t.recoverable
-    t.rememberable
-    t.timestamps
-  end
+The only requirment you have for the tests is to have a @valid_attributes
+instance variable set with a hash of valid attributes.
 
 Notifications
 -------------
@@ -155,12 +117,32 @@ want to prettify your notification views, so you just need to do:
 Then make a copy of the plugin views folder to your app/views and start to work
 on them.
 
-Need more?
-----------
+Notification has some basic specs which fail if you don't include the perishable
+token in your emails. Just put a file in spec/models/auth_helpers/notifier.rb
+with the following contents:
+
+  require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+  module AuthHelpers
+    describe Notifier do
+      include AuthHelpers::Spec::Notifier
+    end  end
+
+I18n
+----
+
+Those helpers rely on I18n. Assuming the account model below, you need to
+configure the following messages:
 
-I'm open to extend this library to include more modules. So if you want an
-Invitable module, fork the project, add it and then send it to me. I will pull
-it in gladly.
+  activerecord:
+    errors:
+      models:
+        account:
+          already_confirmed: was already confirmed
+          not_found: could not be found. Are you sure you gave the right e-mail address?
+          perishable_token:
+            invalid_confirmation: is invalid. Are you sure you copied the right link from your e-mail?
+            invalid_reset_password: is invalid. Are you sure you copied the right link from your e-mail?
 
 Example app
 -----------

data/lib/auth_helpers.rb

@@ -1,6 +1,6 @@
 module AuthHelpers
-  # Helper that find or initialize an object by attribute only if the given value is not blank.
-  # If it's blank, create a new object using :new.
+  # Helper that find or initialize an object by attribute only if the given value
+  # is not blank. If it's blank, create a new object using :new.
   #
   def self.find_or_initialize_by_unless_blank(klass, attr, value)
     if value.blank?
@@ -10,25 +10,13 @@ module AuthHelpers
     end
   end
 
-  # Helpers that generates a unique code for the given attribute by checking in
-  # the database if the code already exists.
+  # Creates a new record, assigning the perishable token and an error message.
   #
-  def self.generate_unique_string_for(klass, attr, length=40)
-    begin
-      value = AuthHelpers.random_string(length)
-    end while klass.send(:"find_by_#{attr}", value)
-
-    value
+  def self.new_with_perishable_token_error(klass, message=:invalid, options={})
+    record = klass.new(options)
+    record.perishable_token = options[:perishable_token]
+    record.errors.add(:perishable_token, message, :default => :invalid)
+    record
   end
 
-  # Create a random string with the given length using letters and numbers.
-  #
-  def self.random_string(length)
-    chars = ('a'..'z').to_a + ('A'..'Z').to_a + ('0'..'9').to_a
-
-    newpass = ''
-    1.upto(length) { |i| newpass << chars.rand }
-
-    return newpass
-  end
 end

data/lib/auth_helpers/model/associatable.rb

@@ -11,6 +11,11 @@ module AuthHelpers
     # Finally, if the *_id in the table has also *_type. It considers a polymorphic
     # association.
     #
+    # Whenever using this method with polymorphic association, don't forget to
+    # set the validation scope in AuthLogic.
+    #
+    #   a.validations_scope = :accountable_type
+    #
     module Associatable
       def self.included(base)
         column = base.columns.detect{|c| c.name =~ /_id$/ }

data/lib/auth_helpers/model/confirmable.rb

@@ -8,76 +8,66 @@ module AuthHelpers
     module Confirmable
       def self.included(base)
         base.extend ClassMethods
-        base.send :before_create, :set_confirmation_code
-        base.send :after_create,  :send_new_account_notification
+        base.send :after_create, :send_confirmation_instructions
       end
 
-      # Returns true if is not a new record and the confirmation code is blank.
+      # Returns true if is not a new record and confirmed_at is not blank.
       #
       def confirmed?
-        !self.new_record? && self.confirmation_code.blank?
+        !(self.new_record? || self.confirmed_at.nil?)
       end
 
-      # Confirms an account by setting :confirmation_code to nil and setting the
-      # confirmed_at field.
+      # Confirms the record by setting the confirmed at.
       #
       def confirm!
-        self.confirmation_code = nil
-        self.confirmed_at = Time.now.utc
-        return self.save(false)
+        update_attribute(:confirmed_at, Time.now.utc)
       end
 
-      protected
-
-        # Generates a confirmation_code and sets confirmation_sent_at.
-        # Does not save the object because it's used as a filter.
-        #
-        def set_confirmation_code
-          self.confirmation_code    = AuthHelpers.generate_unique_string_for(self.class, :confirmation_code, 40)
-          self.confirmation_sent_at = Time.now.utc
-          return true
-        end
-
-        # Send a notification to new account. Used as filter.
-        #
-        def send_new_account_notification
-          AuthHelpers::Notifier.deliver_new_account(self)
-        end
+      # Send confirmation isntructions in different scenarios. It resets the
+      # perishable token, confirmed_at date and set the confirmation_sent_at
+      # datetime.
+      #
+      def send_confirmation_instructions(on=:create)
+        self.reset_perishable_token
+        self.confirmed_at = nil
+        self.confirmation_sent_at = Time.now.utc
+        self.save(false)
+        AuthHelpers::Notifier.send(:"deliver_#{on}_confirmation", self)
+      end
 
       module ClassMethods
 
-        # Receives a confirmation code, find the respective account and tries to set its confirmation code to nil.
-        # If something goes wrong, return an account object with errors.
+        # Receives the perishable token and try to find a record to confirm the
+        # account. If it can't find the record, returns a new record with an
+        # error set on the perishable token.
         #
-        def find_and_confirm(sent_confirmation_code)
-          confirmable = AuthHelpers.find_or_initialize_by_unless_blank(self, :confirmation_code, sent_confirmation_code)
-
-          if confirmable.new_record?
-            confirmable.errors.add :confirmation_code, :invalid
-          else
+        def find_and_confirm(options={})
+          if confirmable = self.find_using_perishable_token(options[:perishable_token])
             confirmable.confirm!
+            confirmable
+          else
+            AuthHelpers.new_with_perishable_token_error(self, :invalid_confirmation, options)
           end
-
-          return confirmable
         end
 
-        # Receives a hash with email and tries to find the account to resend the confirmation code.
-        # If the e-mail can't be found or the account is already confirmed, return an account object
-        # with errors.
+        # Receives a hash with email and tries to find a record to resend the
+        # confirmation instructions. If the record can't be found or it's already
+        # confirmed, set the appropriate error messages and return the object.
         #
-        def find_and_resend_confirmation_code(options = {})
+        def find_and_resend_confirmation_instructions(options = {})
           confirmable = AuthHelpers.find_or_initialize_by_unless_blank(self, :email, options[:email])
 
           if confirmable.new_record?
-            confirmable.errors.add :email, :not_found
+            confirmable.errors.add(:email, :not_found)
           elsif confirmable.confirmed?
-            confirmable.errors.add :email, :already_confirmed
+            confirmable.errors.add(:email, :already_confirmed)
           else
-            AuthHelpers::Notifier.deliver_confirmation_code(confirmable)
+            confirmable.send_confirmation_instructions(:resend)
           end
 
           return confirmable
         end
+
       end
 
     end

data/lib/auth_helpers/model/recoverable.rb

@@ -3,72 +3,61 @@ require File.join(File.dirname(__FILE__), '..', 'notifier')
 module AuthHelpers
   module Model
 
-    # Adds a module that deals with forgot your password.
+    # Adds a module that deals with forgot your password. It overwrites the
+    # reset password method from authlogic for one that accepts a password. 
     #
     module Recoverable
       def self.included(base)
-        base.send(:attr_accessible, :reset_password_code)
         base.extend ClassMethods
       end
 
+      def reset_password(new_password, new_password_confirmation)
+        self.password              = new_password || ""
+        self.password_confirmation = new_password_confirmation || "" if self.respond_to?(:password_confirmation)
+      end
+
       # Reset the password with the new_password is equals its confirmation and
       # set reset password code to nil.
       # 
       def reset_password!(new_password, new_password_confirmation)
-        self.password              = new_password
-        self.password_confirmation = new_password_confirmation
-
-        if self.valid?
-          self.reset_password_code = nil
-          return self.save
-        end
-
-        false
-      end
-
-      # Set a reset password code in the database and send it through e-mail
-      #
-      def send_reset_password_code
-        new_code = AuthHelpers.generate_unique_string_for(self.class, :reset_password_code, 40)
-        self.update_attribute(:reset_password_code, new_code)
-
-        AuthHelpers::Notifier.deliver_reset_password(self)
-        return true
+        reset_password(new_password, new_password_confirmation)
+        self.save
       end
 
       module ClassMethods
 
-        # Receives a hash with reset_password_code, password and password confirmation.
-        # Tries to find the account with the sent password code, and then, if password and password
-        # confirmation matches, changes the password. Otherwise return an account object with errors.
+        # Receives a hash with email and tries to find a record to resend reset
+        # password instructions. If the record can't be found, it sets the
+        # appropriate error messages and return the object.
         #
-        def find_and_reset_password(options={})
-          recoverable = AuthHelpers.find_or_initialize_by_unless_blank(self, :reset_password_code, options[:reset_password_code])
+        def find_and_send_reset_password_instructions(options={})
+          recoverable = AuthHelpers.find_or_initialize_by_unless_blank(self, :email, options[:email])
 
           if recoverable.new_record?
-            recoverable.errors.add :reset_password_code, :invalid
+            recoverable.errors.add(:email, :not_found, options)
           else
-            recoverable.reset_password!(options[:password], options[:password_confirmation])
+            recoverable.reset_perishable_token!
+            AuthHelpers::Notifier.deliver_reset_password(recoverable)
           end
 
           return recoverable
         end
 
-        # Receives a hash with email and tries to find the account to send a new reset password code.
-        # If the e-mail can't be found return an account object with errors.
+        # Receives a hash with perishable_token, password and password confirmation.
+        # If the password cannot be reset (confirmation fails, for example), it
+        # returns an object with errors.
         #
-        def find_and_send_reset_password_code(options={})
-          recoverable = AuthHelpers.find_or_initialize_by_unless_blank(self, :email, options[:email])
-
-          if recoverable.new_record?
-            recoverable.errors.add :email, :not_found, options
+        def find_and_reset_password(options={})
+          if recoverable = self.find_using_perishable_token(options[:perishable_token])
+            recoverable.reset_password!(options[:password], options[:password_confirmation])
+            recoverable
           else
-            recoverable.send_reset_password_code
+            AuthHelpers.new_with_perishable_token_error(self, :invalid_reset_password, options)
           end
-
-          return recoverable
         end
+
       end
+
     end
   end
 end