validates_captcha 0.9.0

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+== 0.9.0 (September 26, 2009)
+
+* Initial version

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2009 Martin Andert
+
+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.rdoc

@@ -0,0 +1,243 @@
+= Validates Captcha
+
+An image captcha verification approach for Rails apps, directly integrated into 
+ActiveRecord's validation mechanism and providing helpers for ActionController 
+and ActionView.
+
+RDoc documentation (including this README as start page) can be found at 
+http://m4n.github.com/validates_captcha
+
+
+
+== Basic Usage
+
+Validates Captcha extends ActiveRecord, ActionController and ActionView with 
+helper methods that make it a snap to integrate captcha verification in your 
+Rails application.
+
+Step #1: Extend the form of your view with the necessary captcha code display 
+and input logic.
+
+  # app/views/comments/new.html.erb
+  <% form_for @comment do |f| %>
+    <%= f.error_messages %>
+
+    <!-- standard input fields: -->
+    <p>
+      <%= f.label :name %><br />
+      <%= f.text_field :name %>
+    </p>    
+    <!-- ... -->
+    
+    <!-- now something new: -->
+    <p>
+      <%= f.label :captcha %><br />
+      <%= f.captcha_image %>
+      <%= f.captcha_field %>
+    </p>
+    
+    <p>
+      <%= f.submit 'Create' %>
+    </p>
+  <% end %>
+
+Step #2: Tell the controller that you want to validate 
+captchas.
+
+  class CommentsController < ApplicationController
+    validates_captcha
+    
+    def create
+      # scaffold comment creation code ...
+    end
+    
+    # more actions here ...
+  end
+  
+This activates captcha validation in every action of the controller 
+whenever an instance of class +Comment+ is saved.
+
+Step #3: There's no step three!
+
+To summarize: Put the following in your view.
+
+  <%= f.captcha_image %>
+  <%= f.captcha_field %>
+  
+And what you see below in the corresponding controller.
+
+  validates_captcha
+
+Done.
+
+== Customization
+
+Because the +validates_captcha+ controller method internally creates an 
+around filter, you can (de)activate captcha validation for specific actions.
+
+  validates_captcha :only => [:create, :update]
+  validates_captcha :except => :reset
+
+The class for which captcha validation is activated is derived from 
+the name of the controller. So putting +validates_captcha+ in a 
++UsersController+ validates instances of the +User+ class.
+
+You can customize the validated class using the +validates_captcha_of+ method.
+
+  class ArticlesController < ApplicationController
+    validates_captcha_of Post
+    validates_captcha_of :blog_entries, :except => :persist
+    validates_captcha_of 'users', :only => :store
+  end
+  
+Two kinds of errors are added to the model if captcha validation fails: 
++:blank+ if no captcha code is submitted and +:invalid+ if a captcha code 
+is submitted but does not match the code displayed on the captcha image. 
+You can localize the error messages for the captcha as you usually do 
+for the other attributes.
+
+  models:
+    comment:
+      attributes:
+        captcha:
+          blank: 'must not be empty'
+          invalid: 'does not match the code displayed on the image'
+
+What if the captcha's text is unreadable? There's also a form helper 
+method for captcha regeneration available. You can call it like this.
+
+  <p>
+    Captcha code unreadable? <%= f.regenerate_captcha_link %>
+  </p>
+
+This generates an anchor tag that, when clicked, generates a new 
+captcha and updates the image. It makes an AJAX request to fetch a 
+new captcha code and updates the captcha image after the request is complete.
+
++regenerate_captcha_link+ internally calls Rails' #link_to_remote helper 
+method. So it relies on the Prototype javascript framework to be available 
+on the page.
+
+The anchor's text defaults to 'Regenerate Captcha'. You can set this to 
+a custom value by providing a +:text+ key in the options hash.
+
+  <%= f.regenerate_captcha_link :text => 'Another captcha, please' %>
+
+By default, captchas have a length of 6 characters and the text displayed 
+on the captcha image is created by randomly selecting characters from a 
+predefined alphabet constisting of visually distinguishable letters and digits.
+
+The number of characters and the alphabet used when generating strings can 
+be customized. Just put the following in a Rails initializer and adjust the 
+values to your needs.
+
+  ValidatesCaptcha::StringGenerator::Simple.alphabet = '01'
+  ValidatesCaptcha::StringGenerator::Simple.length = 8
+
+Apart from controllers, you can activate captcha validation for a model 
+using the class level +with_captcha_validation+ method added to 
+ActiveRecord::Base.
+
+  Comment.with_captcha_validation do
+    @comment = Comment.new(...)
+    @comment.save
+  end
+  
+This activates captcha validation on entering the block and deactivates it 
+on leaving the block.
+
+Two new attribute like methods are added to ActiveRecord: +captcha+ and 
++encrypted_captcha+.  Those are made +attr_accessible+.  The latter is 
+initialized to a randomly generated and encrypted captcha code on 
+instantation. 
+
+For a record to be valid, the value assigned to +captcha=+ must match the 
+decryption of the return value of +encrypted_captcha+.  Within a 
++with_captcha_validation+ block, calling +valid?+ (as is done by +save+, 
++update_attributes+, etc.) will also validate the value of +captcha+ 
+against the +encrypted_captcha+.  Outside +with_captcha_validation+, no 
+captcha validation is performed.
+
+
+
+== Extensibility
+
+Validates Captcha delegates tasks like string and image generation, 
+encryption/decryption of captcha codes, and responding to captcha requests 
+to dedicated backend classes.
+
+Those classes can easily be replaced by your custom implementations.  So 
+you can achieve stronger encryption, can use a word list as captcha text 
+generation source, or can replace the captcha image generator with one 
+that creates images that are harder to crack.
+
+Please see the documentation of the following classes for further information.
+
+* ValidatesCaptcha::StringGenerator::Simple
+* ValidatesCaptcha::ReversibleEncrypter::Simple
+* ValidatesCaptcha::ImageGenerator::Simple
+* ValidatesCaptcha::Middleware::Simple
+
+
+
+== Dependencies
+
+Using a Rack middleware to speed up the request/response cycle when fetching 
+captcha images, Validates Captcha requires Rails version 2.3 or greater.
+
+The default captcha image generator uses ImageMagick's +convert+ command to 
+create the captcha.  So a recent and properly configured version of ImageMagick 
+must be installed on the system.  The version used while developing was 6.4.5.  
+But you are not bound to ImageMagick.  If you want to provide a custom image 
+generator, take a look at the documentation for 
+ValidatesCaptcha::ImageGenerator::Simple on how to create your own.
+
+
+
+== Download
+
+The latest version of Validates Captcha can be found at 
+http://github.com/m4n/validates_captcha
+
+Documentation can be generated from its distribution directory with the 
+following command.
+
+  % [sudo] rake rdoc
+
+Tests can be executed from its distribution directory with the 
+following command.
+
+  % [sudo] rake test
+
+
+
+== Installation
+
+You can install Validates Captcha as a Rails plugin with the following command.
+
+  % ./script/plugin install git://github.com/m4n/validates_captcha.git
+  
+Or you can install it as a Gem with
+
+  % [sudo] gem install m4n-validates_captcha --source http://gems.github.com
+
+and then configure it in your +environment.rb+ file as shown below.
+
+  Rails::Initializer.run do |config|
+    # ...
+    config.gem 'm4n-validates_captcha', :lib => 'validates_captcha'
+    # ...
+  end
+
+
+
+== License
+
+Validates Captcha is released under the MIT license.
+
+
+
+== Copyright
+
+Copyright (c) 2009 Martin Andert
+

data/Rakefile

@@ -0,0 +1,105 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+
+require File.join(File.dirname(__FILE__), 'lib', 'validates_captcha', 'version')
+
+
+
+PKG_NAME = 'validates_captcha'
+PKG_VERSION = ValidatesCaptcha::VERSION::STRING
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+RELEASE_NAME = "REL #{PKG_VERSION}"
+
+RUBY_FORGE_PROJECT = "validatecaptcha"
+RUBY_FORGE_USER = "m4n"
+
+PKG_FILES = FileList['[A-Z]*', 'lib/**/*', 'test/**/*', 'rails/*'].exclude(/\bCVS\b|~$/)
+
+
+
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
+desc 'Generate documentation'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = "Validates Captcha"
+  rdoc.main = "README.rdoc"
+ 
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.options << '--charset' << 'utf-8'
+  
+  rdoc.rdoc_files.include 'README.rdoc'
+  rdoc.rdoc_files.include 'MIT-LICENSE'
+  rdoc.rdoc_files.include 'CHANGELOG.rdoc'
+  rdoc.rdoc_files.include 'lib/**/*.rb'
+  rdoc.rdoc_files.exclude 'lib/validates_captcha/test_case.rb'
+  rdoc.rdoc_files.exclude 'lib/validates_captcha/version.rb'
+end
+
+namespace :rdoc do
+  desc 'Show documentation in Firefox'
+  task :show do
+    sh 'firefox doc/index.html'
+  end
+end
+
+
+
+desc 'Run tests by default'
+task :default => :test
+ 
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  #t.verbose = true
+  #t.warning = true
+end
+ 
+ 
+ 
+spec = eval(File.read('validates_captcha.gemspec'))
+ 
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+
+
+
+desc 'Publish the release files to RubyForge'
+task :release => [:package] do
+  require 'rubyforge'
+  require 'rake/contrib/rubyforgepublisher'
+ 
+  packages = %w( gem tgz zip ).collect{ |ext| "pkg/#{PKG_NAME}-#{PKG_VERSION}.#{ext}" }
+ 
+  rubyforge = RubyForge.new(YAML.load(File.read(RubyForge::CONFIG_F)), YAML.load(File.read('/home/andert/.rubyforge/auto-config.yml')))
+  rubyforge.login
+  rubyforge.add_release(9020, 12371, "REL #{PKG_VERSION}", *packages)
+end
+
+
+
+desc 'Uninstall local gem'
+task :uninstall do
+  system "sudo gem uninstall #{PKG_NAME}"
+end
+
+desc 'Install local gem'
+task :install => [:uninstall, :gem] do
+  system "sudo gem install pkg/#{PKG_NAME}-#{PKG_VERSION}.gem --no-ri --no-rdoc"
+end
+
+
+
+Dir['tasks/**/*.rake'].each { |tasks_file| load tasks_file }
+

data/lib/validates_captcha/controller_validation.rb

@@ -0,0 +1,63 @@
+module ValidatesCaptcha
+  module ControllerValidation
+    def self.included(base) #:nodoc:
+      base.extend ClassMethods
+    end
+    
+    # This module extends ActionController::Base with methods for captcha 
+    # verification.
+    module ClassMethods      
+      # This method is the one Validates Captcha got its name from. It 
+      # internally calls #validates_captcha_of with the name of the controller 
+      # as first argument and passing the conditions hash.
+      #
+      # Usage Example:
+      #
+      #  class UsersController < ApplicationController
+      #    # Whenever a User gets saved, validate the captcha.
+      #    validates_captcha
+      #
+      #    def create
+      #      # ... user creation code ...
+      #    end
+      #
+      #    # ... more actions ...
+      #  end
+      def validates_captcha(conditions = {})
+        validates_captcha_of controller_name, conditions
+      end
+      
+      # Activates captcha validation for the specified model.
+      #
+      # The +model+ argument can be a Class, a string, or a symbol.
+      #
+      # This method internally creates an around filter, passing the 
+      # +conditions+ argument to it. So you can (de)activate captcha 
+      # validation for specific actions.
+      #
+      # Usage examples:
+      #
+      #  class UsersController < ApplicationController
+      #    validates_captcha_of User
+      #    validates_captcha_of :users, :only => [:create, :update]
+      #    validates_captcha_of 'user', :except => :persist
+      #
+      #    # ... actions go here ...
+      #  end      
+      def validates_captcha_of(model, conditions = {})
+        model = model.is_a?(Class) ? model : model.to_s.classify.constantize
+        without_formats = Array.wrap(conditions.delete(:without)).map(&:to_sym)
+        
+        around_filter(conditions) do |controller, action|
+          if without_formats.include?(controller.request.format.to_sym)
+            action.call
+          else
+            model.with_captcha_validation do
+              action.call
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/validates_captcha/form_builder.rb

@@ -0,0 +1,16 @@
+module ValidatesCaptcha
+  module FormBuilder #:nodoc:
+    def captcha_image(options = {}) #:nodoc:
+      @template.captcha_image @object_name, options.merge(:object => @object)
+    end
+    
+    def captcha_field(options = {}) #:nodoc:
+      @template.captcha_field @object_name, options.merge(:object => @object)
+    end
+    
+    def regenerate_captcha_link(options = {}, html_options = {}) #:nodoc:
+      @template.regenerate_captcha_link @object_name, options.merge(:object => @object), html_options
+    end
+  end
+end
+

data/lib/validates_captcha/form_helper.rb

@@ -0,0 +1,51 @@
+module ValidatesCaptcha
+  module FormHelper
+    # Returns an img tag with the src attribute pointing to the captcha image url. 
+    #
+    # Internally calls Rails' #image_tag helper method, passing the +options+ 
+    # argument.
+    def captcha_image(object_name, options = {})
+      object = options.delete(:object)
+      src = ValidatesCaptcha.captcha_image_path(object.encrypted_captcha)
+      sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+      
+      options[:alt] ||= 'CAPTCHA'
+      options[:id] = "#{sanitized_object_name}_captcha_image"
+      
+      image_tag src, options
+    end
+    
+    # Returns an input tag of the "text" type tailored for entering the captcha code.
+    #
+    # Internally calls Rails' #text_field helper method, passing the +object_name+ and 
+    # +options+ arguments.
+    def captcha_field(object_name, options = {})
+      options.delete(:id)
+      
+      hidden_field(object_name, :encrypted_captcha, options) + text_field(object_name, :captcha, options)
+    end
+    
+    # Returns an anchor tag that makes an AJAX request to fetch a new captcha code and updates 
+    # the captcha image after the request is complete.
+    # 
+    # Internally calls Rails' #link_to_remote helper method, passing the +options+ and 
+    # +html_options+ arguments. So it relies on the Prototype javascript framework 
+    # to be available on the web page.
+    #
+    # The anchor text defaults to 'Regenerate Captcha'. You can set this to a custom value 
+    # providing a +:text+ key in the +options+ hash.
+    def regenerate_captcha_link(object_name, options = {}, html_options = {})
+      options.symbolize_keys!
+      
+      object = options.delete(:object)
+      text = options.delete(:text) || 'Regenerate Captcha'      
+      sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+      
+      url = ValidatesCaptcha.regenerate_captcha_path
+      success = "var result = request.responseJSON; $('#{sanitized_object_name}_captcha_image').src = result.captcha_image_path; $('#{sanitized_object_name}_encrypted_captcha').value = result.encrypted_captcha_code;"
+      
+      link_to_remote text, options.reverse_merge(:url => url, :method => :get, :success => success), html_options
+    end
+  end
+end
+

data/lib/validates_captcha/image_generator/simple.rb

@@ -0,0 +1,87 @@
+module ValidatesCaptcha
+  module ImageGenerator
+    # This class is responsible for creating the captcha image. It internally 
+    # uses ImageMagick's +convert+ command to generate the image bytes. So 
+    # ImageMagick must be installed on the system for it to work properly.
+    #
+    # In order to deliver the captcha image to the user's browser, 
+    # Validate Captcha's Rack middleware calls the methods of this class 
+    # to create the image, to retrieve its mime type, and to construct the 
+    # path to it.
+    #
+    # The image generation process is no rocket science. The chars are just 
+    # laid out next to each other with varying vertical positions, font sizes, 
+    # and weights. Then a slight rotation is performed and some randomly 
+    # positioned lines are rendered on the canvas.
+    #
+    # Sure, the created captcha can easily be cracked by intelligent 
+    # bots. As the name of the class suggests, it's rather a starting point 
+    # for your own implementations.
+    #
+    # You can implement your own (better) image generator by creating a 
+    # class that conforms to the method definitions of the example below and 
+    # assign an instance of it to ValidatesCaptcha#image_generator=.
+    #
+    # Example for a custom image generator:
+    #
+    #  class AdvancedImageGenerator
+    #    def generate(captcha_text)
+    #      # ... do your magic here ...
+    #
+    #      return string_containing_image_bytes
+    #    end
+    #
+    #    def image_mime_type
+    #      'image/png'
+    #    end
+    #
+    #    def image_file_extension
+    #      '.png'
+    #    end
+    #  end
+    #
+    #  ValidatesCaptcha.image_generator = AdvancedImageGenerator.new
+    #    
+    class Simple
+      MIME_TYPE = 'image/gif'.freeze
+      FILE_EXTENSION = '.gif'.freeze
+      
+      # Returns a string containing the image bytes of the captcha. 
+      # As the only argument, the cleartext captcha text must be passed.
+      def generate(captcha_code)
+        image_width = captcha_code.length * 20 + 10
+        
+        cmd = []
+        cmd << "convert -size #{image_width}x40 xc:grey84 -background grey84 -fill black "
+        
+        captcha_code.split(//).each_with_index do |char, i|
+          cmd << " -pointsize #{rand(8) + 15} "
+          cmd << " -weight #{rand(2) == 0 ? '4' : '8'}00 "
+          cmd << " -draw 'text #{5 + 20 * i},#{rand(10) + 20} \"#{char}\"' "
+        end
+        
+        cmd << "  -rotate #{rand(2) == 0 ? '-' : ''}5 -fill grey40 "
+        
+        captcha_code.size.times do
+          cmd << "  -draw 'line #{rand(image_width)},0 #{rand(image_width)},60' "
+        end
+        
+        cmd << "  gif:-"
+        
+        image_magick_command = cmd.join
+        
+        `#{image_magick_command}`
+      end
+      
+      # Returns the image mime type. This is always 'image/gif'.
+      def image_mime_type
+        MIME_TYPE
+      end
+      
+      # Returns the image file extension. This is always '.gif'.
+      def image_file_extension
+        FILE_EXTENSION
+      end
+    end
+  end
+end