panmind-recaptcha 1.0

data/README.md

@@ -0,0 +1,144 @@
+ReCaptcha for Rails - With AJAX Validation
+==========================================
+
+Purpose
+-------
+
+This plugin implements view helpers to generate ReCaptcha code,
+to interface with the HTTP API for captcha verification, a DSL
+to generate a `before_filter` and the necessary hacky code to
+implement AJAX captcha validation.
+
+Implementation
+--------------
+
+For AJAX validation, a request to ReCaptcha HTTP server must be
+made in order to verify the user input, but captchas can be
+checked only once.
+
+The plugin, thus, in case of a successful verification, saves
+uses the Rails `flash` to temporarily save this status in the
+session and then the before filter skips the verification via
+the ReCaptcha HTTP service.
+
+Installation
+------------
+
+Via RubyGems:
+
+    gem install panmind-recaptcha
+
+Or via Rails Plugin:
+
+    script/plugin install git://github.com/Panmind/recaptcha.git
+
+Usage
+-----
+
+In your config/environment.rb:
+
+    Panmind::Recaptcha.set(
+      :private_key => 'your private key',
+      :public_key  => 'your public key
+    )
+
+In your controller, say, the `UsersController` for a signup action:
+
+    require_valid_captcha :only => :create
+
+    private
+      def invalid_captcha
+        @user = User.new params[:user]
+        @user.errors.add_to_base('Captcha failed')
+
+        render :new, :layout => 'login'
+      end
+
+The `invalid_captcha` method is called by the plugin when captcha
+verification fails, and *must* be overwritten or a `NotImplementedError`
+exception will be thrown.
+
+In your view:
+
+    <%= recaptcha :label => 'Are you human?', :theme => 'clean' %>
+
+You can pass any `RecaptchaOptions` valid option, as stated by the
+service documentation. The only nonstandard option `:label` is used
+by the plugin to print a label before the captcha widget.
+
+
+AJAX Validation
+---------------
+
+To cache the results of a successful captcha verification, you need
+simply to pass the `:ajax => true` option to the `require_valid_captcha`
+controller method.
+
+    require_valid_captcha :only => :create, :ajax => true
+
+When the form is validated via AJAX, the maybe successful result will
+be saved in the `flash` (thus set in the session store); when the form is
+then submitted via a plain HTTP request, verification will be skipped.
+
+On Panmind we use our `jquery.ajax-validation` plugin, that you
+can download from http://github.com/Panmind/jquery-ajax-nav and
+the Javascript code located in the `js/signup-sample.js` file.
+
+On the backend, an example checker that returns different HTTP
+status code follows:
+
+    def signup_checker
+      # If no email was provided, return 400
+      if params[:email].blank?
+        render :nothing => true, :status => :bad_request and return
+      end
+
+      email = CGI.unescape(params[:email])
+
+      # more thorough checks on email should go here
+
+      # If an user with this email already exist, return 406
+      if User.exists?(['email = ?', email])
+        render :nothing => true, :status => :not_acceptable and return
+      end
+
+      unless valid_captcha?
+        invalid_captcha and return
+      end
+
+      save_solved_captcha # This method sets a flag in the flash
+      render :nothing => true, :status => :ok
+    end
+
+Moreover, the client Javascript code should be informed via an
+HTTP status when validation fails, thus the `invalid_captcha`
+must contain a special `render` when the request comes from XHR:
+
+    def invalid_captcha
+      # If the captcha is not valid, return a 412 (precondition failed)
+      render :nothing => true, :status => 412 and return true if request.xhr?
+
+      # Same invalid_captcha code as above
+    end
+
+
+The latest XHR specification from the w3c states that cookies set
+by responses to requests sent via XHR are to be honored by the browser.
+
+The code was tested with IE (6,7,8), Safari (4, 5), Firefox 3, Chrome 5
+and Opera 10.
+
+
+Security
+--------
+
+As long as you use a session store backed on the server or cryptographically
+sign the cookies used by the session cookie store (as Rails does by default)
+there is no way to bypass the captcha when AJAX validation is enabled.
+
+
+Compatibility
+-------------
+
+Tested with Rails 2.3.8 with the `rails_xss` plugin installed,
+running under Ruby 1.9.1-p378.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rake'
+require 'rake/rdoctask'
+
+require 'lib/panmind/recaptcha'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name             = 'panmind-recaptcha'
+
+    gemspec.summary          = 'ReCaptcha for Rails - With AJAX Validation'
+    gemspec.description      = 'ReCaptcha implements view helpers to generate ReCaptcha code, '     \
+                               'with the noscript counterpart, required methods that interface ' \
+                               'with the HTTP API for captcha verification, a DSL to generate a '  \
+                               'before_filter and the code to implement AJAX captcha validation.'
+
+    gemspec.authors          = ['Marcello Barnaba']
+    gemspec.email            = 'vjt@openssl.it'
+    gemspec.homepage         = 'http://github.com/Panmind/recaptcha'
+
+    gemspec.files            = %w( README.md Rakefile rails/init.rb ) + Dir['lib/**/*']
+    gemspec.extra_rdoc_files = %w( README.md )
+    gemspec.has_rdoc         = true
+
+    gemspec.version          = Panmind::Recaptcha::Version
+    gemspec.date             = '2010-11-17'
+
+    gemspec.require_path     = 'lib'
+
+    gemspec.add_dependency('rails', '~> 2.3.8')
+  end
+rescue LoadError
+  puts 'Jeweler not available. Install it with: gem install jeweler'
+end
+
+desc 'Generate the rdoc'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.add %w( README.md lib/**/*.rb )
+
+  rdoc.main  = 'README.md'
+  rdoc.title = 'ReCaptcha for Rails - With AJAX Validation'
+end
+
+desc 'Will someone help write tests?'
+task :default do
+  puts
+  puts 'Can you help in writing tests? Please do :-)'
+  puts
+end

data/lib/panmind/recaptcha.rb

@@ -0,0 +1,136 @@
+require 'timeout'
+
+if defined?(Rails) && Rails.env.test?
+  begin
+    require 'mocha'
+  rescue LoadError
+    print "\n!!\n!! ReCaptcha: to use the test helpers you should gem install mocha\n!!\n\n"
+  end
+end
+
+module Panmind
+  module Recaptcha
+    Version = 1.0
+
+    class << self
+      attr_accessor :private_key, :public_key, :request_timeout
+
+      def set(options)
+        self.private_key, self.public_key =
+          options.values_at(:private_key, :public_key)
+
+        # Defaults
+        #
+        self.request_timeout = options[:timeout] || 5
+      end
+
+      def enabled?
+        Rails.env.production?
+      end
+    end # << self
+
+    class ConfigurationError < StandardError; end
+
+    module Controller
+      def self.included(base)
+        base.instance_eval do
+          def require_valid_captcha(options = {})
+            if options.delete(:ajax)
+              options.update(:unless => :captcha_already_solved?)
+            end
+
+            before_filter :validate_recaptcha, options
+          end
+        end
+      end
+
+      protected
+        def validate_recaptcha
+          invalid_captcha unless valid_captcha?
+        end
+
+        def captcha_already_solved?
+          flash[:skip_captcha_check]
+        end
+
+        def save_solved_captcha
+          flash[:skip_captcha_check] = true
+        end
+
+      private
+        def valid_captcha?
+          return true unless Recaptcha.enabled?
+
+          challenge, response = params.values_at(
+            :recaptcha_challenge_field, :recaptcha_response_field)
+
+          return false if challenge.blank? || response.blank?
+
+          req = 
+            Timeout.timeout(Recaptcha.request_timeout) do
+              uri = URI.parse("http://api-verify.recaptcha.net/verify")
+              Net::HTTP.post_form(uri,
+                :privatekey => Recaptcha.private_key,
+                :remoteip   => request.remote_ip,
+                :challenge  => challenge,
+                :response   => response
+              )
+            end
+
+          res = req.body.split("\n")
+          return res.first == 'true'
+
+        rescue Timeout::Error
+          # Let it go...
+          true
+        end
+
+        def invalid_captcha
+          raise NotImplementedError, 'You must implement invalid_captcha in your controller'
+        end
+    end # Controller
+  
+    module Helpers
+      def recaptcha(options = {})
+        return unless Recaptcha.enabled?
+
+        if Recaptcha.private_key.blank? || Recaptcha.public_key.blank?
+          raise ConfigurationError, 'ReCaptcha keys are missing'
+        end
+
+        label_text = options.delete(:label) || 'Enter the following words'
+
+        noscript_options = {:width => 420, :height => 320}.merge(
+          options.delete(:noscript) || {})
+
+        recaptcha_options =
+          options.empty? ? '' :
+          javascript_tag(%[var RecaptchaOptions = #{options.to_json}])
+
+        label_tag('recaptcha_response_field', label_text) + recaptcha_options +
+        %[<script type="text/javascript"
+             src="https://api-secure.recaptcha.net/challenge?k=#{Recaptcha.public_key}">
+          </script>
+
+          <noscript>
+             <iframe src="https://api-secure.recaptcha.net/noscript?k=#{Recaptcha.public_key}"
+                 height="#{noscript_options[:width]}" width="#{noscript_options[:height]}" frameborder="0"></iframe><br>
+             <input type="text" class="text" name="recaptcha_challenge_field" tabindex="#{options[:tabindex]}"/>
+             <input type="hidden" name="recaptcha_response_field" value="manual_challenge" />
+          </noscript>
+        ].html_safe
+      end
+    end # Helpers
+
+    module TestHelpers
+      def mock_valid_captcha
+        @controller.stubs(:valid_captcha?).returns(true)
+      end
+
+      def mock_invalid_captcha
+        @controller.stubs(:valid_captcha?).returns(false)
+      end
+    end # TestHelpers
+
+  end # Recaptcha
+end # Panmind

data/rails/init.rb

@@ -0,0 +1,7 @@
+require 'panmind/recaptcha'
+
+module Panmind::Recaptcha
+  ActionView::Base.instance_eval { include Helpers }
+  ActionController::Base.instance_eval { include Controller }
+  ActionController::TestCase.instance_eval { include TestHelpers } if Rails.env.test?
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: panmind-recaptcha
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Marcello Barnaba
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-17 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 2
+        - 3
+        - 8
+        version: 2.3.8
+  type: :runtime
+  version_requirements: *id001
+description: ReCaptcha implements view helpers to generate ReCaptcha code, with the noscript counterpart, required methods that interface with the HTTP API for captcha verification, a DSL to generate a before_filter and the code to implement AJAX captcha validation.
+email: vjt@openssl.it
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- README.md
+- Rakefile
+- lib/panmind/recaptcha.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/Panmind/recaptcha
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: ReCaptcha for Rails - With AJAX Validation
+test_files: []
+