validates_captcha 0.9.2 → 0.9.3

data/lib/validates_captcha/image_generator/simple.rb

@@ -20,7 +20,7 @@ module ValidatesCaptcha
     #
     # 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=.
+    # assign an instance of it to ValidatesCaptcha::Provider::Image#image_generator=.
     #
     # Example for a custom image generator:
     #
@@ -31,16 +31,17 @@ module ValidatesCaptcha
     #      return string_containing_image_bytes
     #    end
     #
-    #    def image_mime_type
+    #    def mime_type
     #      'image/png'
     #    end
     #
-    #    def image_file_extension
+    #    def file_extension
     #      '.png'
     #    end
     #  end
     #
-    #  ValidatesCaptcha.image_generator = AdvancedImageGenerator.new
+    #  ValidatesCaptcha::Provider::Image.image_generator = AdvancedImageGenerator.new
+    #  ValidatesCaptcha.provider = ValidatesCaptcha::Provider::Image.new
     #    
     class Simple
       MIME_TYPE = 'image/gif'.freeze
@@ -74,12 +75,12 @@ module ValidatesCaptcha
       end
       
       # Returns the image mime type. This is always 'image/gif'.
-      def image_mime_type
+      def mime_type
         MIME_TYPE
       end
       
       # Returns the image file extension. This is always '.gif'.
-      def image_file_extension
+      def file_extension
         FILE_EXTENSION
       end
     end

data/lib/validates_captcha/model_validation.rb

@@ -5,9 +5,9 @@ module ValidatesCaptcha
       base.send :include, InstanceMethods
       
       base.class_eval do
-        attr_accessible :captcha, :encrypted_captcha
-        attr_accessor :captcha
-        attr_writer :encrypted_captcha
+        attr_accessible :captcha_challenge, :captcha_solution
+        attr_accessor :captcha_solution
+        attr_writer :captcha_challenge
         
         validate :validate_captcha, :if => :validate_captcha?
       end
@@ -42,9 +42,9 @@ module ValidatesCaptcha
     end
     
     module InstanceMethods #:nodoc:
-      def encrypted_captcha #:nodoc:
-        return @encrypted_captcha unless @encrypted_captcha.blank?
-        @encrypted_captcha = ValidatesCaptcha.encrypt_captcha_code(ValidatesCaptcha.generate_captcha_code)
+      def captcha_challenge #:nodoc:
+        return @captcha_challenge unless @captcha_challenge.blank?
+        @captcha_challenge = ValidatesCaptcha.provider.generate_challenge
       end
       
       private      
@@ -53,12 +53,12 @@ module ValidatesCaptcha
         end
         
         def validate_captcha #:nodoc:
-          errors.add(:captcha, :blank) and return if captcha.blank?
-          errors.add(:captcha, :invalid) unless captcha_valid?
+          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.encrypt_captcha_code(captcha) == encrypted_captcha
+          ValidatesCaptcha.provider.solved?(captcha_challenge, captcha_solution)
         end        
     end
   end

data/lib/validates_captcha/provider/image.rb

@@ -0,0 +1,244 @@
+require 'openssl'
+require 'active_support/secure_random'
+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 reversible encrypter.  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 Image
+      include ActionView::Helpers
+      
+      KEY = ::ActiveSupport::SecureRandom.hex(32).freeze
+      
+      @@string_generator = nil
+      @@reversible_encrypter = 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 reversible encrypter. Defaults to an
+        # instance of the ValidatesCaptcha::ReversibleEncrypter::Simple class.
+        def reversible_encrypter
+          @@reversible_encrypter ||= ValidatesCaptcha::ReversibleEncrypter::Simple.new
+        end
+        
+        # Sets the current captcha reversible encrypter. Used to set a
+        # custom reversible encrypter.
+        def reversible_encrypter=(encrypter)
+          @@reversible_encrypter = encrypter
+        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.bytesize.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)
+        challenge == encrypt(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.reversible_encrypter.encrypt code
+        end
+      
+        def decrypt(encrypted_code) #:nodoc:
+          self.class.reversible_encrypter.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
+      

data/lib/validates_captcha/provider/question.rb

@@ -0,0 +1,110 @@
+require 'action_view/helpers'
+
+module ValidatesCaptcha
+  module Provider
+    # A question/answer captcha provider.
+    class Question
+      include ActionView::Helpers
+      
+      DEFAULT_QUESTIONS_AND_ANSWERS = {
+        "What's the capital of France?" => "Paris",
+        "What's the capital of Germany?" => "Berlin",
+        "What's the opposite of good?" => ["bad", "evil"],
+        "What's the opposite of love?" => "hate",
+        "What's the sum of 2 and 3?" => ["5", "five"],
+        "What's the product of 3 and 4?" => ["12", "twelve"],
+        "Thumb, tooth or hand: which is part of the head?" => "tooth",
+        "Bread, ham or milk: which is something to drink?" => "milk",
+        "What day is today, if yesterday was Friday?" => "Saturday",
+        "What day is today, if tomorrow is Tuesday?" => "Monday",
+        "What is the 2nd letter of the the third word in this question?" => "h",
+        "What color is the sky on a sunny day?" => "blue" }.freeze
+      
+      @@questions_and_answers = DEFAULT_QUESTIONS_AND_ANSWERS
+      
+      class << self
+        # Returns the current captcha questions/answers hash. Defaults to 
+        # DEFAULT_QUESTIONS_AND_ANSWERS.
+        def questions_and_answers
+          @@questions_and_answers
+        end
+        
+        # Sets the current captcha questions/answers hash. Used to set a
+        # custom questions/answers hash.
+        def questions_and_answers=(qna)
+          @@questions_and_answers = qna
+        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 a new challenge in 
+      # JSON format.
+      #
+      # Please take a look at the source code if you want to learn more.
+      def call(env)
+        if env['PATH_INFO'] == regenerate_path
+          captcha_challenge = generate_challenge
+          json = { :captcha_challenge => captcha_challenge }.to_json
+          
+          [200, { 'Content-Type' => 'application/json' }, [json]]
+        else
+          [404, { 'Content-Type' => 'text/html' }, ['Not Found']]
+        end
+      end
+      
+      # Returns a captcha question.
+      def generate_challenge
+        self.class.questions_and_answers.keys[rand(self.class.questions_and_answers.keys.size)]
+      end
+        
+      # Returns true if the captcha was solved using the given +question+ and +answer+, 
+      # otherwise false.
+      def solved?(question, answer)
+        return false unless self.class.questions_and_answers.key?(question)
+        answers = Array.wrap(self.class.questions_and_answers[question]).map(&:downcase)
+        answers.include?(answer.downcase)
+      end
+      
+      # Returns a span tag with the inner HTML set to the captcha question.
+      # 
+      # Internally calls Rails' +content_tag+ helper method, passing the +options+ argument.
+      def render_challenge(sanitized_object_name, object, options = {})
+        options[:id] = "#{sanitized_object_name}_captcha_question"
+        
+        content_tag :span, object.captcha_challenge, options
+      end
+      
+      # Returns an anchor tag that makes an AJAX request to fetch a new question and updates 
+      # the captcha challenge 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 'New question'. 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) || 'New question'
+        success = "var result = request.responseJSON; $('#{sanitized_object_name}_captcha_question').update(result.captcha_challenge); $('#{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 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
+        
+        def solve(challenge) #:nodoc:
+          Array.wrap(self.class.questions_and_answers[challenge]).first
+        end
+    end
+  end
+end

data/lib/validates_captcha/reversible_encrypter/simple.rb

@@ -8,7 +8,7 @@ module ValidatesCaptcha
     #
     # You can implement your own reversible encrypter by creating a class 
     # that conforms to the method definitions of the example below and 
-    # assign an instance of it to ValidatesCaptcha#reversible_encrypter=.
+    # assign an instance of it to ValidatesCaptcha::Provider::Image#reversible_encrypter=.
     #
     # Example for a custom encrypter/decrypter:
     #
@@ -24,7 +24,8 @@ module ValidatesCaptcha
     #    end
     #  end
     #
-    #  ValidatesCaptcha.reversible_encrypter = ReverseString.new
+    #  ValidatesCaptcha::Provider::Image.reversible_encrypter = ReverseString.new
+    #  ValidatesCaptcha.provider = ValidatesCaptcha::Provider::Image.new
     #
     # Please note: The #decrypt method should return +nil+ if decryption fails. 
     class Simple