root/plugins/brain_buster/trunk/README

BrainBuster - A Logic Captcha For Rails
=======================================
Homepage: http://opensource.thinkrelevance.com/wiki/BrainBuster
Mailing List: http://groups.google.com/group/brainbuster-discuss
Git Repository (dev happens here): git://github.com/rsanheim/brain_buster.git
SVN Repository (read only mirror): http://opensource.thinkrelevance.com/svn/plugins/brain_buster/trunk/

Notes
=========================
The latest version removes all deprecated code from 0.7 and below, and does serious clean up all over the place.

You now have to handle captcha failure on your own, since Rails 2.0 requires a render or redirect to halt a filter chain.  This makes sense anyways, because if you really want a decent user experience you should be placing the user's half saved model in the flash (or an ivar, or a cookie, or whatever) and then pulling it back into the form if the captcha fails.

See the CHANGELOG for more details.

Quick Install
=============

* How to install fresh in a Rails app?

  script/plugin install http://opensource.thinkrelevance.com/svn/plugins/brain_buster/trunk/
  script/generate brain_buster_migration 
  rake db:migrate
  optionally set the cookie salt in your ApplicationController (or don't touch it to use the default)
  add the appropriate filters where you want to use the captcha
  render the _captcha.rhtml partial to any views where you want to challenge the user and you are all set!

* Want to check out the source?

git clone git://github.com/rsanheim/brain_buster.git

or 

svn checkout http://opensource.thinkrelevance.com/svn/plugins/brain_buster/trunk/ brainbuster

* Need more help?

Join the mailing list: http://groups.google.com/group/brainbuster-discuss

Intro
=====
BrainBuster is a logic captcha for Rails.  A logic captcha attempts to detect automated responses (ie spambots) by asking a simple question, such as a word puzzle or math question.  Logic captchas are often easier for humans to answer then image based captchas, but can exclude foreign users or users with cognitive disabilities.  

Some example question and answers are:

"What is fifteen minus five?" => "10"
"Which one of these doesn't fit? 'blue, red, yellow, flower'" => 'flower'

For more on logic captchas and alternate approaches, please see http://www.w3.org/TR/turingtest/#logic

Details
=======================================
BrainBuster includes a model for storing questions and answers, a small module that is mixed into ActionController::Bases, a small partial to display the question and input form, and a basic stylesheet for styling the partial.  There is also a "captcha_footer" partial that is not functionally required at all, its just included to make it easy to give credit and a little link-love if you find this useful.  The style sheet is also not required of course, it just has a little bit of clean css for the captcha form.

This captcha is meant to be user-friendly, so for a questions like "What is two plus two", all of the following answers will work: "4", "four", "Four", "   four   ".  By default, a user only needs to answer a captcha _once_, then they are cookied and don't have to answer another question until they close/reopen their browser.

Installation
=======================================
* Generate the migration, modifying questions and answers if you wish:

    script/generate brain_buster_migration

* Now add the filters for any action(s) you want protected.  Lets say in a PagesController you have a show action that presents a page to a user with some nice ajax capable fields that can directly post to an update action to change the page.  So we need to create a captcha before we show the page so we can present the captcha question to the user, and we need to validate that captcha before we update.  

    class PagesController
      before_filter :create_brain_buster, :only => [:show]
      before_filter :validate_brain_buster, :only => [:update]
      
      def show # your normal code is here
      def update # updating your models, etc

* override render_or_redirect_for_captcha_failure in your controller, to handle the captcha failure state.  Note that if you *don't override* this method, BrainBuster will just do render :text with the brain buster error message -- this is probably not what you want.

    class PagesController
    
      def render_or_redirect_for_captcha_failure
        render :action => "show"
      end
       
* render the partial in appropriate templates - if we are creating the captcha for the show action, we probably need the 
  form rendered in show.rhtml.

    - show.rhtml:
      ... inside your update form somewhere
      <%= render :partial => '/captcha' %> 
      <%= render :partial => "/captcha_footer" %>  --> optional, only if you want to give credit back...

* Copy the style sheet into your app's public directory (optional)

    cp vendor/plugins/brain_buster/assets/stylesheets/captcha.css public/stylesheets/             

    # add the style sheet to any views that use the captcha
    <%= stylesheet_link_tag 'captcha' %>

* Thats it.  Now if the captcha fails on update, the filter chain will place the failure message into flash[:error] and call render_or_redirect_for_captcha_failure.  

Troubleshooting and Gotchas
===========================
* If you don't override render_or_redirect_for_captcha_failure, you will see a plain error message for a failed captcha.
* If you delete a question, the random id finder may try to find that deleted question and blow up.  For now, just insert another question with that same id to fix the issue.
* The built in questions and answers could be scripted fairly easily by a determined spammer, but usually just having _some_ defense makes bots move on to easier targets.

Real world usage
================
You can see the plugin in action at http://madisonrails.com or at http://wiki.rubyonrails.org.

Credits
=======================================
BrainBuster is by Rob Sanheim (http://robsanheim.com) and Relevance (http://thinkrelevance.com).  
Email: rsanheim at gmail no spam dot com

Thanks to the creators of the Exception Logger plugin (http://svn.techno-weenie.net/projects/plugins/exception_logger/) and the Unobtrusive Javascript plugin (http://www.ujs4rails.com/), as I referred to their source code for help.