rails3-restful-authentication 3.0.1

data/CHANGELOG

@@ -0,0 +1,70 @@
+h1. provide restful_authentication.rb to require the gem
+
+h1. Internal Changes to code
+
+As always, this is just a copy-and-pasted version of the CHANGELOG file in the source code tree.
+
+h2. Changes for the May, 2008 version of restful-authentication
+
+h3. Changes to user model
+
+* recently_activated? belongs only if stateful
+* Gave migration a 40-char limit on remember_token & an index on users by login
+* **Much** stricter login and email validation
+* put length constraints in migration too
+* password in 6, 40
+* salt and remember_token now much less predictability
+
+h3. Changes to session_controller
+
+* use uniform logout function
+* use uniform remember_cookie functions
+* avoid calling logged_in? which will auto-log-you-in (safe in the face of
+  logout! call, but idiot-proof)
+* Moved reset_session into only the "now logged in" branch
+** wherever it goes, it has to be in front of the current_user= call
+** See more in README-Tradeoffs.txt
+* made a place to take action on failed login attempt
+* recycle login and remember_me setting on failed login
+* nil'ed out the password field in 'new' view
+
+h3. Changes to users_controller
+
+* use uniform logout function
+* use uniform remember_cookie functions
+* Moved reset_session into only the "now logged in" branch
+** wherever it goes, it has to be in front of the current_user= call
+** See more in README-Tradeoffs.txt
+* made the implicit login only happen for non-activationed sites
+* On a failed signup, kick you back to the signin screen (but strip out the password & confirmation)
+* more descriptive error messages in activate()
+
+h3. users_helper
+
+* link_to_user, link_to_current_user, link_to_signin_with_IP 
+* if_authorized(action, resource, &block) view function (with appropriate
+  warning)
+
+h3. authenticated_system
+
+* Made authorized? take optional arguments action=nil, resource=nil, *args
+  This makes its signature better match traditional approaches to access control
+  eg Reference Monitor in "Security Patterns":http://www.securitypatterns.org/patterns.html)
+* authorized? should be a helper too
+* added uniform logout! methods
+* format.any (as found in access_denied) doesn't work until
+  http://dev.rubyonrails.org/changeset/8987 lands.
+* cookies are now refreshed each time we cross the logged out/in barrier, as 
+  "best":http://palisade.plynt.com/issues/2004Jul/safe-auth-practices/
+  "practice":http://www.owasp.org/index.php/Session_Management#Regeneration_of_Session_Tokens
+
+h3. Other
+
+* Used escapes <%= %> in email templates (among other reasons, so courtenay's
+  "'dumbass' test":http://tinyurl.com/684g9t doesn't complain)
+* Added site key to generator, users.yml.
+* Made site key generation idempotent in the most crude and hackish way
+* 100% coverage apart from the stateful code. (needed some access_control
+  checks, and the http_auth stuff)
+* Stories!
+

data/README.textile

@@ -0,0 +1,176 @@
+h1. "Restful Authentication Generator":https://github.com/vatrai/restful_authentication
+
+This widely-used plugin provides a foundation for securely managing user authentication:
+* Login / logout
+* Secure password handling
+* Account activation by validating email
+* Account approval / disabling by admin
+* Rudimentary hooks for authorization and access control.
+
+Several features were updated in May, 2008.
+* "Stable newer version":http://github.com/technoweenie/restful-authentication/tree/master
+* "'Classic' (backward-compatible) version":http://github.com/technoweenie/restful-authentication/tree/classic
+* "Experimental version":http://github.com/technoweenie/restful-authentication/tree/modular (Much more modular, needs testing & review)
+
+!! important: if you upgrade your site, existing user account !!
+!! passwords will stop working unless you use @--old-passwords@ !!
+
+h2. Issue Tracker
+
+Please submit any bugs or annoyances at
+* "https://github.com/vatrai/restful_authentication/issues":https://github.com/vatrai/restful_authentication/issues
+
+h2. Documentation
+
+This page has notes on
+* "Installation":#INSTALL
+* "New Features":#AWESOME
+* "After installing":#POST-INSTALL
+
+See the "wiki":http://github.com/technoweenie/restful-authentication/wikis/home (or the notes/ directory) if you want to learn more about:
+
+* "Extensions, Addons and Alternatives":http://wiki.github.com/technoweenie/restful-authentication/addons such as HAML templates
+* "Security Design Patterns":http://wiki.github.com/technoweenie/restful-authentication/security-patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png
+* "Authentication":http://wiki.github.com/technoweenie/restful-authentication/authentication -- Lets a visitor identify herself (and lay  claim to her corresponding Roles and measure of Trust)
+* "Trust Metrics":http://wiki.github.com/technoweenie/restful-authentication/trustification -- Confidence we can rely on the outcomes of this visitor's actions.
+* "Authorization":http://wiki.github.com/technoweenie/restful-authentication/authorization and Policy -- Based on trust and identity, what actions may this visitor perform?
+* "Access Control":http://wiki.github.com/technoweenie/restful-authentication/access-control -- How the Authorization policy is actually enforced in your code (A: hopefully without turning it into  a spaghetti of if thens)
+* "Rails Plugins":http://wiki.github.com/technoweenie/restful-authentication/rails-plugins for Authentication, Trust,  Authorization and Access Control
+* "Tradeoffs":http://wiki.github.com/technoweenie/restful-authentication/tradeoffs -- for the paranoid or the curious, a rundown of tradeoffs made in the code
+* "CHANGELOG":http://wiki.github.com/technoweenie/restful-authentication/CHANGELOG -- Summary of changes to internals
+* "TODO":http://wiki.github.com/technoweenie/restful-authentication/todo -- Ideas for how you can help
+
+
+These best version of the release notes are in the notes/ directory in the "source code":http://github.com/technoweenie/restful-authentication/tree/master -- look there for the latest version. The wiki versions are taken (manually) from there.
+
+h2(#AWESOME). Exciting new features
+
+h3. Stories
+
+There are now "Cucumber":http://wiki.github.com/aslakhellesoy/cucumber/home features that allow expressive, enjoyable tests for the authentication code. The flexible code for resource testing in stories was extended from "Ben Mabey's.":http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/
+
+h3. Modularize to match security design patterns:
+
+* Authentication (currently: password, browser cookie token, HTTP basic)
+* Trust metric (email validation)
+* Authorization (stateful roles)
+* Leave a flexible framework that will play nicely with other access control / policy definition / trust metric plugins
+
+h3. Other
+
+* Added a few helper methods for linking to user pages
+* Uniform handling of logout, remember_token
+* Stricter email, login field validation
+* Minor security fixes -- see CHANGELOG
+
+
+h2. Non-backwards compatible Changes
+
+Here are a few changes in the May 2008 release that increase "Defense in Depth"
+but may require changes to existing accounts
+
+* If you have an existing site, none of these changes are compelling enough to warrant migrating your userbase.
+* If you are generating for a new site, all of these changes are low-impact. You should apply them.
+
+h3. Passwords
+
+The new password encryption (using a site key salt and stretching) will break existing user accounts' passwords.  We recommend you use the @--old-passwords@
+option or write a migration tool and submit it as a patch.  See the "Tradeoffs":http://wiki.github.com/technoweenie/restful-authentication/tradeoffs note for more information.
+
+h3. Validations
+
+By default, email and usernames are validated against a somewhat strict pattern; your users' values may be now illegal.  Adjust to suit.
+
+
+h2(#INSTALL). Installation
+
+This is a basic restful authentication generator for rails, taken from acts as authenticated.  Currently it requires Rails3 beta.
+
+**IMPORTANT FOR RAILS > 2.1 USERS** To avoid a @NameError@ exception ("lighthouse tracker ticket":http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/tickets/2-not-a-valid-constant-name-errors#ticket-2-2), check out the code to have an _underscore_ and not _dash_ in its name:
+
+If you're using git as your source control, you have three options.
+
+* Install as a plugin <pre><code>rails plugin install git://github.com/Satish/restful-authentication.git restful_authentication</code></pre>
+
+* Checkout into @vendor/plugins@ using
+<pre><code>git clone git://github.com/Satish/restful-authentication.git restful_authentication</code></pre>and delete the .git folder inside the directory. (This will break the connection with the github repository, and allow you to include the code into your project with git add)
+
+* Use git submodule. From the top level of your project, add the plugin
+<pre><code>git submodule add git://github.com/Satish/restful-authentication.git vendor/plugins/restful_authentication</code></pre>This will create a reference link to the repository, which can be save into your project. You will need to let capistrano know that you want to update submodules on deploy via @set :git_enable_submodules, 1@.
+
+"git-submodule docs":http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html
+
+To use the generator:
+<pre><code>
+  rails g authenticated user sessions \
+    --include-activation \
+    --stateful \
+    --rspec \
+    --skip-migration \
+    --skip-routes \
+    --old-passwords
+</code></pre>
+
+* The first parameter specifies the model that gets created in signup (typically a user or account model).  A model with migration is created, as well as a basic controller with the create method. You probably want to say "User" here.
+
+* The second parameter specifies the session controller name(options default to @sessionsController@).  This is the controller that handles the actual login/logout function on the site. (probably: "Session").
+
+* @--include-activation@: Generates the code for a ActionMailer and its respective Activation Code through email.
+
+* @--stateful@: Builds in support for acts_as_state_machine and generates activation code.  (@--stateful@ implies @--include-activation@). Based on the idea at "http://www.vaporbase.com/postings/stateful_authentication":http://www.vaporbase.com/postings/stateful_authentication. Passing @--skip-migration@ will skip the user migration, and @--skip-routes@ will skip resource generation both useful if you've already run this generator. (Needs the "acts_as_state_machine plugin":http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/, but new installs should probably run with @--aasm@ instead.)
+
+* @--aasm@: Works the same as stateful but uses the "updated aasm gem":http://github.com/rubyist/aasm/tree/master<br /> Add <code>gem 'rubyist-aasm', :require => 'aasm'</code> to @Gemfile@ for use in projects that use rails3-beta
+
+* @--rspec@: Generate RSpec tests and Stories in place of standard rails tests. This requires the "RSpec-2 for Rails-3":http://github.com/rspec/rspec-rails, run @gem install rspec-rails --pre@ to install RSpec-2 for Rails-3(make sure you @rails g rspec:install@ after installing RSpec.) The rspec and story suite are much more thorough than the rails tests, and changes are unlikely to be backported.
+
+* @--old-passwords@: Use the older password scheme (see [[#COMPATIBILITY]], above)
+
+* @--skip-migration@: Don't generate a migration file for this model
+
+* @--skip-routes@: Don't generate a resource line in @config/routes.rb@
+
+
+h2(#POST-INSTALL). After installing
+
+The below assumes a Model named 'User' and a Controller named 'Session'; please alter to suit. There are additional security minutae in @notes/README-Tradeoffs@ -- only the paranoid or the curious need bother, though.
+
+* Add these familiar login URLs to your @config/routes.rb@ if you like:
+<pre><code>
+ match 'login' => 'sessions#new', :as => :login
+ match 'logout' => 'sessions#destroy', :as => :logout
+ match 'signup' => 'users#new', :as => :signup
+</code></pre>
+
+* With @--include-activation@, also add to your @config/routes.rb@:
+<pre><code>match 'activate/:activation_code' => 'users#activate', :as => :activate, :activation_code => nil</code></pre>
+and add an observer to @config/application.rb@:
+<pre><code>config.active_record.observers = :user_observer</code></pre>
+Pay attention, may be this is not an issue for everybody, but if you should have problems, that the sent activation_code does match with that in the database stored, reload your user object before sending its data through email something like:
+<pre><code>
+class UserObserver < ActiveRecord::Observer
+  def after_create(user)
+    user.reload
+    UserMailer.deliver_signup_notification(user)
+  end
+  def after_save(user)
+    user.reload
+    UserMailer.deliver_activation(user) if user.recently_activated?
+  end
+end
+</code></pre>
+
+
+* With @--stateful@, add an observer to config/environment.rb:
+<pre><code>config.active_record.observers = :user_observer</code></pre>
+and modify the users resource line in @config/routes.rb@ to read
+<pre><code>
+resources :users do
+  member do
+    put :suspend
+    put :unsuspend
+    delete :purge
+  end
+end
+</code></pre>
+
+* If you use a public repository for your code (such as github, rubyforge, gitorious, etc.) make sure to NOT post your site_keys.rb (add a line like '/config/initializers/site_keys.rb' to your .gitignore or do the svn ignore dance), but make sure you DO keep it backed up somewhere safe.

data/Rakefile

@@ -0,0 +1,32 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the restful_authentication plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the restful_authentication plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'RestfulAuthentication'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+gemspec = eval(File.read("#{File.dirname(__FILE__)}/restful-authentication.gemspec"))
+PKG_NAME = gemspec.name
+PKG_VERSION = gemspec.version
+
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end

data/TODO

@@ -0,0 +1,15 @@
+
+h3. Authentication security projects for a later date
+
+
+* Track 'failed logins this hour' and demand a captcha after say 5 failed logins
+  ("RECAPTCHA plugin.":http://agilewebdevelopment.com/plugins/recaptcha)
+  "De-proxy-ficate IP address": http://wiki.codemongers.com/NginxHttpRealIpModule
+
+* Make cookie spoofing a little harder: we set the user's cookie to
+  (remember_token), but store digest(remember_token, request_IP). A CSRF cookie
+  spoofer has to then at least also spoof the user's originating IP
+  (see "Secure Programs HOWTO":http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/web-authentication.html)
+
+* Log HTTP request on authentication / authorization failures
+  http://palisade.plynt.com/issues/2004Jul/safe-auth-practices  

data/init.rb

@@ -0,0 +1,3 @@
+require File.join(File.dirname(__FILE__), "lib", "authentication")
+require File.join(File.dirname(__FILE__), "lib", "authentication", "by_password")
+require File.join(File.dirname(__FILE__), "lib", "authentication", "by_cookie_token")

data/lib/authentication.rb

@@ -0,0 +1,40 @@
+module Authentication
+  mattr_accessor :login_regex, :bad_login_message, 
+    :name_regex, :bad_name_message,
+    :email_name_regex, :domain_head_regex, :domain_tld_regex, :email_regex, :bad_email_message
+
+  self.login_regex       = /\A\w[\w\.\-_@]+\z/                     # ASCII, strict
+  # self.login_regex       = /\A[[:alnum:]][[:alnum:]\.\-_@]+\z/     # Unicode, strict
+  # self.login_regex       = /\A[^[:cntrl:]\\<>\/&]*\z/              # Unicode, permissive
+
+  self.bad_login_message = "use only letters, numbers, and .-_@ please.".freeze
+
+  self.name_regex        = /\A[^[:cntrl:]\\<>\/&]*\z/              # Unicode, permissive
+  self.bad_name_message  = "avoid non-printing characters and \\&gt;&lt;&amp;/ please.".freeze
+
+  self.email_name_regex  = '[\w\.%\+\-]+'.freeze
+  self.domain_head_regex = '(?:[A-Z0-9\-]+\.)+'.freeze
+  self.domain_tld_regex  = '(?:[A-Z]{2}|com|org|net|edu|gov|mil|biz|info|mobi|name|aero|jobs|museum)'.freeze
+  self.email_regex       = /\A#{email_name_regex}@#{domain_head_regex}#{domain_tld_regex}\z/i
+  self.bad_email_message = "should look like an email address.".freeze
+
+  def self.included(recipient)
+    recipient.extend(ModelClassMethods)
+    recipient.class_eval do
+      include ModelInstanceMethods
+    end
+  end
+
+  module ModelClassMethods
+    def secure_digest(*args)
+      Digest::SHA1.hexdigest(args.flatten.join('--'))
+    end
+
+    def make_token
+      secure_digest(Time.now, (1..10).map{ rand.to_s })
+    end
+  end # class methods
+
+  module ModelInstanceMethods
+  end # instance methods
+end

data/lib/authentication/by_cookie_token.rb

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+module Authentication
+  module ByCookieToken
+    def self.included(recipient)
+      recipient.extend(ModelClassMethods)
+      recipient.class_eval do
+        include ModelInstanceMethods
+      end
+    end
+
+    module ModelClassMethods
+    end 
+
+    module ModelInstanceMethods
+      def remember_token?
+        (!remember_token.blank?) && 
+          remember_token_expires_at && (Time.now.utc < remember_token_expires_at.utc)
+      end
+
+      def remember_me
+        remember_me_for 2.weeks
+      end
+
+      def remember_me_for(time)
+        remember_me_until time.from_now.utc
+      end
+
+      def remember_me_until(time)
+        self.remember_token_expires_at = time
+        self.remember_token            = self.class.make_token
+        save(:validate => false)
+      end
+
+      # refresh token (keeping same expires_at) if it exists
+      def refresh_token
+        if remember_token?
+          self.remember_token = self.class.make_token 
+          save(:validate => false)
+        end
+      end
+
+      # 
+      # Deletes the server-side record of the authentication token.  The
+      # client-side (browser cookie) and server-side (this remember_token) must
+      # always be deleted together.
+      #
+      def forget_me
+        self.remember_token_expires_at = nil
+        self.remember_token            = nil
+        save(:validate => false)
+      end
+    end # instance methods
+  end
+
+  module ByCookieTokenController
+    # Stuff directives into including module 
+    def self.included( recipient )
+      recipient.extend( ControllerClassMethods )
+      recipient.class_eval do
+        include ControllerInstanceMethods
+      end
+    end
+
+    #
+    # Class Methods
+    #
+    module ControllerClassMethods
+    end # class methods
+    
+    module ControllerInstanceMethods
+    end # instance methods
+  end
+end

data/lib/authentication/by_password.rb

@@ -0,0 +1,64 @@
+module Authentication
+  module ByPassword
+    # Stuff directives into including module
+    def self.included(recipient)
+      recipient.extend(ModelClassMethods)
+      recipient.class_eval do
+        include ModelInstanceMethods
+        
+        # Virtual attribute for the unencrypted password
+        attr_accessor :password
+        validates_presence_of     :password,                   :if => :password_required?
+        validates_presence_of     :password_confirmation,      :if => :password_required?
+        validates_confirmation_of :password,                   :if => :password_required?
+        validates_length_of       :password, :within => 6..40, :if => :password_required?
+        before_save :encrypt_password
+      end
+    end # #included directives
+
+    #
+    # Class Methods
+    #
+    module ModelClassMethods
+      # This provides a modest increased defense against a dictionary attack if
+      # your db were ever compromised, but will invalidate existing passwords.
+      # See the README and the file config/initializers/site_keys.rb
+      #
+      # It may not be obvious, but if you set REST_AUTH_SITE_KEY to nil and
+      # REST_AUTH_DIGEST_STRETCHES to 1 you'll have backwards compatibility with
+      # older versions of restful-authentication.
+      def password_digest(password, salt)
+        digest = REST_AUTH_SITE_KEY
+        REST_AUTH_DIGEST_STRETCHES.times do
+          digest = secure_digest(digest, salt, password, REST_AUTH_SITE_KEY)
+        end
+        digest
+      end      
+    end # class methods
+
+    #
+    # Instance Methods
+    #
+    module ModelInstanceMethods
+      
+      # Encrypts the password with the user salt
+      def encrypt(password)
+        self.class.password_digest(password, salt)
+      end
+      
+      def authenticated?(password)
+        crypted_password == encrypt(password)
+      end
+      
+      # before filter 
+      def encrypt_password
+        return if password.blank?
+        self.salt = self.class.make_token if new_record?
+        self.crypted_password = encrypt(password)
+      end
+      def password_required?
+        crypted_password.blank? || !password.blank?
+      end
+    end # instance methods
+  end
+end