karsthammer-validates_captcha 0.9.5a

data/lib/validates_captcha.rb

@@ -0,0 +1,76 @@
+#--
+# 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.
+#++
+
+
+# This module contains the getter and setter for the captcha provider. 
+# This allows you to replace it with your custom implementation. For more 
+# information on how to bring Validates Captcha to use your own 
+# implementation instead of the default one, consult the documentation 
+# for the default provider.
+module ValidatesCaptcha
+  autoload :ModelValidation, 'validates_captcha/model_validation'
+  autoload :ControllerValidation, 'validates_captcha/controller_validation'
+  autoload :FormHelper, 'validates_captcha/form_helper'
+  autoload :FormBuilder, 'validates_captcha/form_builder'
+  autoload :TestCase, 'validates_captcha/test_case'
+  autoload :VERSION, 'validates_captcha/version'
+  
+  module Provider
+    autoload :Question, 'validates_captcha/provider/question'
+    autoload :DynamicImage, 'validates_captcha/provider/dynamic_image'
+    autoload :StaticImage, 'validates_captcha/provider/static_image'
+  end
+  
+  module StringGenerator
+    autoload :Simple, 'validates_captcha/string_generator/simple'
+  end
+  
+  module SymmetricEncryptor
+    autoload :Simple, 'validates_captcha/symmetric_encryptor/simple'
+  end
+  
+  module ImageGenerator
+    autoload :Simple, 'validates_captcha/image_generator/simple'
+  end
+  
+  @@provider = nil
+  
+  class << self
+    # Returns Validates Captcha's current version number.
+    def version
+      ValidatesCaptcha::VERSION::STRING
+    end
+    
+    # Returns the current captcha challenge provider. Defaults to an instance of 
+    # the ValidatesCaptcha::Provider::Question class.
+    def provider
+      @@provider ||= Provider::Question.new
+    end
+
+    # Sets the current captcha challenge provider. Used to set a custom provider.
+    def provider=(provider)
+      @@provider = provider
+    end
+  end
+end
+

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_challenge(options = {}) #:nodoc:
+      @template.captcha_challenge @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_challenge_link(options = {}, html_options = {}) #:nodoc:
+      @template.regenerate_captcha_challenge_link @object_name, options.merge(:object => @object), html_options
+    end
+  end
+end
+

data/lib/validates_captcha/form_helper.rb

@@ -0,0 +1,39 @@
+module ValidatesCaptcha
+  module FormHelper
+    # Returns the captcha challenge. 
+    #
+    # Internally calls the +render_challenge+ method of ValidatesCaptcha#provider.
+    def captcha_challenge(object_name, options = {})
+      options.symbolize_keys!
+      
+      object = options.delete(:object)
+      sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+      
+      ValidatesCaptcha.provider.render_challenge sanitized_object_name, object, options
+    end
+    
+    # Returns an input tag of the "text" type tailored for entering the captcha solution.
+    #
+    # 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, :captcha_challenge, options) + text_field(object_name, :captcha_solution, options)
+    end
+    
+    # By default, returns an anchor tag that makes an AJAX request to fetch a new captcha challenge and updates 
+    # the current challenge after the request is complete.
+    # 
+    # Internally calls +render_regenerate_challenge_link+ method of ValidatesCaptcha#provider.
+    def regenerate_captcha_challenge_link(object_name, options = {}, html_options = {})
+      options.symbolize_keys!
+      
+      object = options.delete(:object)
+      sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+      
+      ValidatesCaptcha.provider.render_regenerate_challenge_link sanitized_object_name, object, options, html_options
+    end
+  end
+end
+

data/lib/validates_captcha/image_generator/simple.rb

@@ -0,0 +1,94 @@
+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.
+    #
+    # Example for a custom image generator:
+    #
+    #  class AdvancedImageGenerator
+    #    def generate(captcha_text)
+    #      # ... do your magic here ...
+    #
+    #      return string_containing_image_bytes
+    #    end
+    #
+    #    def mime_type
+    #      'image/png'
+    #    end
+    #
+    #    def file_extension
+    #      '.png'
+    #    end
+    #  end
+    #
+    # Then assign an instance of it to ValidatesCaptcha::Provider::DynamicImage#image_generator=.
+    #
+    #  ValidatesCaptcha::Provider::DynamicImage.image_generator = AdvancedImageGenerator.new
+    #  ValidatesCaptcha.provider = ValidatesCaptcha::Provider::DynamicImage.new
+    #
+    # Or to ValidatesCaptcha::Provider::StaticImage#image_generator=.
+    #
+    #  ValidatesCaptcha::Provider::StaticImage.image_generator = AdvancedImageGenerator.new
+    #  ValidatesCaptcha.provider = ValidatesCaptcha::Provider::StaticImage.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 mime_type
+        MIME_TYPE
+      end
+      
+      # Returns the image file extension. This is always '.gif'.
+      def file_extension
+        FILE_EXTENSION
+      end
+    end
+  end
+end

data/lib/validates_captcha/model_validation.rb

@@ -0,0 +1,65 @@
+module ValidatesCaptcha
+  module ModelValidation
+    def self.included(base) #:nodoc:
+      base.extend ClassMethods
+      base.send :include, InstanceMethods
+      
+      base.class_eval do
+        attr_accessor :captcha_solution
+        attr_writer :captcha_challenge
+        
+        validate :validate_captcha, :if => :validate_captcha?
+      end
+    end
+    
+    module ClassMethods
+      # Activates captcha validation on entering the block and deactivates 
+      # captcha validation on leaving the block.
+      #
+      # Example:
+      #
+      #   User.with_captcha_validation do
+      #     @user = User.new(...)
+      #     @user.save
+      #   end
+      def with_captcha_validation(&block)
+        self.validate_captcha = true
+        result = yield
+        self.validate_captcha = false
+        result
+      end
+          
+      # Returns +true+ if captcha validation is activated, otherwise +false+.
+      def validate_captcha? #:nodoc:
+        @validate_captcha == true
+      end
+      
+      private
+        def validate_captcha=(value) #:nodoc:
+          @validate_captcha = value
+        end
+    end
+    
+    module InstanceMethods #:nodoc:
+      def captcha_challenge #:nodoc:
+        return @captcha_challenge unless @captcha_challenge.blank?
+        @captcha_challenge = ValidatesCaptcha.provider.generate_challenge
+      end
+      
+      private      
+        def validate_captcha? #:nodoc:
+          self.class.validate_captcha?
+        end
+        
+        def validate_captcha #:nodoc:
+          errors.add(:captcha_solution, :blank) and return if captcha_solution.blank?
+          errors.add(:captcha_solution, :invalid) unless captcha_valid?
+        end
+      
+        def captcha_valid? #:nodoc:
+          ValidatesCaptcha.provider.solved?(captcha_challenge, captcha_solution)
+        end        
+    end
+  end
+end
+

data/lib/validates_captcha/provider/dynamic_image.rb

@@ -0,0 +1,240 @@
+require 'action_view/helpers'
+
+module ValidatesCaptcha
+  # Here is how you can implement your own captcha challenge provider. Create a 
+  # class that conforms to the public method definitions of the example below 
+  # and assign an instance of it to ValidatesCaptcha#provider=.
+  #
+  # Example:
+  #
+  #  require 'action_view/helpers'
+  #
+  #  class ReverseProvider
+  #    include ActionView::Helpers # for content_tag, link_to_remote
+  #
+  #    def initialize
+  #      @string_generator = ValidatesCaptcha::StringGenerator::Simple.new
+  #    end
+  #
+  #    def generate_challenge
+  #      @string_generator.generate  # creates a random string
+  #    end
+  #
+  #    def solved?(challenge, solution)
+  #      challenge.reverse == solution
+  #    end
+  #
+  #    def render_challenge(sanitized_object_name, object, options = {})
+  #      options[:id] = "#{sanitized_object_name}_captcha_question"
+  #      
+  #      content_tag :span, "What's the reverse of '#{object.captcha_challenge}'?", options
+  #    end
+  #
+  #    def render_regenerate_challenge_link(sanitized_object_name, object, options = {}, html_options = {})
+  #      text = options.delete(:text) || 'Regenerate'
+  #      on_success = "var result = request.responseJSON; " \\
+  #                   "$('#{sanitized_object_name}_captcha_question').update(result.question); " \\
+  #                   "$('#{sanitized_object_name}_captcha_challenge').value = result.challenge; " \\
+  #                   "$('#{sanitized_object_name}_captcha_solution').value = '';"
+  #     
+  #      link_to_remote text, options.reverse_merge(:url => '/captchas/regenerate', :method => :get, :success => success), html_options
+  #    end
+  #
+  #    def call(env)  # this is executed by Rack
+  #      if env['PATH_INFO'] == '/captchas/regenerate'
+  #        challenge = generate_challenge
+  #        json = { :question => "What's the reverse of '#{challenge}'?", :challenge => challenge }.to_json
+  #        
+  #        [200, { 'Content-Type' => 'application/json' }, [json]]
+  #      else
+  #        [404, { 'Content-Type' => 'text/html' }, ['Not Found']]
+  #      end
+  #    end
+  #
+  #    private
+  #      # Hack: This is needed by +link_to_remote+ called in +render_regenerate_challenge_link+.
+  #      def protect_against_forgery?
+  #        false
+  #      end
+  #  end
+  #
+  #  ValidatesCaptcha.provider = ReverseProvider.new
+  module Provider
+    # An image captcha provider.
+    #
+    # This class contains the getters and setters for the backend classes:
+    # image generator, string generator, and symmetric encryptor.  This
+    # allows you to replace them with your custom implementations.  For more
+    # information on how to bring the image provider to use your own
+    # implementation instead of the default one, consult the documentation
+    # for the specific default class.
+    #
+    # 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.
+    class DynamicImage
+      include ActionView::Helpers
+      
+      @@string_generator = nil
+      @@symmetric_encryptor = nil
+      @@image_generator = nil
+      
+      class << self
+        # Returns the current captcha string generator. Defaults to an
+        # instance of the ValidatesCaptcha::StringGenerator::Simple class.
+        def string_generator
+          @@string_generator ||= ValidatesCaptcha::StringGenerator::Simple.new
+        end
+        
+        # Sets the current captcha string generator. Used to set a
+        # custom string generator.
+        def string_generator=(generator)
+          @@string_generator = generator
+        end
+        
+        # Returns the current captcha symmetric encryptor. Defaults to an
+        # instance of the ValidatesCaptcha::SymmetricEncryptor::Simple class.
+        def symmetric_encryptor
+          @@symmetric_encryptor ||= ValidatesCaptcha::SymmetricEncryptor::Simple.new
+        end
+        
+        # Sets the current captcha symmetric encryptor. Used to set a
+        # custom symmetric encryptor.
+        def symmetric_encryptor=(encryptor)
+          @@symmetric_encryptor = encryptor
+        end
+        
+        # Returns the current captcha image generator. Defaults to an
+        # instance of the ValidatesCaptcha::ImageGenerator::Simple class.
+        def image_generator
+          @@image_generator ||= ValidatesCaptcha::ImageGenerator::Simple.new
+        end
+        
+        # Sets the current captcha image generator. Used to set a custom
+        # image generator.
+        def image_generator=(generator)
+          @@image_generator = generator
+        end
+      end
+      
+      # This method is the one called by Rack.
+      # 
+      # It returns HTTP status 404 if the path is not recognized. If the path is 
+      # recognized, it returns HTTP status 200 and delivers the image if it could 
+      # successfully decrypt the captcha code, otherwise HTTP status 422.
+      #
+      # Please take a look at the source code if you want to learn more.
+      def call(env)
+        if env['PATH_INFO'] =~ /^\/captchas\/([^\.]+)/
+          if $1 == 'regenerate'
+            captcha_challenge = generate_challenge
+            json = { :captcha_challenge => captcha_challenge, :captcha_image_path => image_path(captcha_challenge) }.to_json
+            
+            [200, { 'Content-Type' => 'application/json' }, [json]]
+          else
+            decrypted_code = decrypt($1)
+          
+            if decrypted_code.nil?
+              [422, { 'Content-Type' => 'text/html' }, ['Unprocessable Entity']]
+            else
+              image_data = generate_image(decrypted_code)
+              
+              response_headers = {
+                'Content-Length'            => image_data.length.to_s,
+                'Content-Type'              => image_mime_type,
+                'Content-Disposition'       => 'inline',
+                'Content-Transfer-Encoding' => 'binary',
+                'Cache-Control'             => 'private'
+              }
+              
+              [200, response_headers, [image_data]]
+            end
+          end
+        else
+          [404, { 'Content-Type' => 'text/html' }, ['Not Found']]
+        end
+      end
+      
+      # Returns a captcha challenge.
+      def generate_challenge
+        encrypt(generate_code)
+      end
+        
+      # Returns true if the captcha was solved using the given +challenge+ and +solution+, 
+      # otherwise false.
+      def solved?(challenge, solution)
+        decrypt(challenge) == solution
+      end
+      
+      # Returns an image tag with the source set to the url of the captcha image.
+      # 
+      # Internally calls Rails' +image_tag+ helper method, passing the +options+ argument.
+      def render_challenge(sanitized_object_name, object, options = {})
+        src = image_path(object.captcha_challenge)
+        
+        options[:alt] ||= 'CAPTCHA'
+        options[:id] = "#{sanitized_object_name}_captcha_image"
+        
+        image_tag src, 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 render_regenerate_challenge_link(sanitized_object_name, object, options = {}, html_options = {})
+        text = options.delete(:text) || 'Regenerate Captcha'
+        success = "var result = request.responseJSON; $('#{sanitized_object_name}_captcha_image').src = result.captcha_image_path; $('#{sanitized_object_name}_captcha_challenge').value = result.captcha_challenge; $('#{sanitized_object_name}_captcha_solution').value = '';"
+        
+        link_to_remote text, options.reverse_merge(:url => regenerate_path, :method => :get, :success => success), html_options
+      end
+      
+      private      
+        def generate_image(code) #:nodoc:
+          self.class.image_generator.generate code
+        end
+        
+        def image_mime_type #:nodoc:
+          self.class.image_generator.mime_type
+        end
+        
+        def image_file_extension #:nodoc:
+          self.class.image_generator.file_extension
+        end
+      
+        def encrypt(code) #:nodoc:
+          self.class.symmetric_encryptor.encrypt code
+        end
+      
+        def decrypt(encrypted_code) #:nodoc:
+          self.class.symmetric_encryptor.decrypt encrypted_code
+        end
+        
+        def generate_code #:nodoc:
+          self.class.string_generator.generate
+        end
+      
+        def image_path(encrypted_code) #:nodoc:
+          "/captchas/#{encrypted_code}#{image_file_extension}"
+        end
+        
+        def regenerate_path #:nodoc:
+          '/captchas/regenerate'
+        end
+      
+        # This is needed by +link_to_remote+ called in +render_regenerate_link+.
+        def protect_against_forgery? #:nodoc:
+          false
+        end
+    end
+  end
+end
+