acts_as_textcaptcha 1.1.0 → 1.1.1

data/.gitignore

@@ -1,4 +1,4 @@
-*.gemspec
+acts_as_textcaptcha.sqlite3.db
 *.gem
 *.db      
 doc

data/README.rdoc

@@ -1,37 +1,130 @@
-= Act as TextCaptcha
+= ActAsTextcaptcha   
 
-== About
+Spam protection for your ActiveRecord models using logic questions and the excellent {Text CAPTCHA}[http://textcaptcha.com] service.  
 
-== Caveats
+ActAsTextcaptcha can *also* be configured with your very own logic questions (to fall back on if the textcaptcha service is down) or as a replacement for the service.  The plugin can also make use of *bcrypt* *encryption*, to store the possible answers in your session (recommended if you are using the default Rails {CookieStore}[http://apidock.com/rails/CGI/Session/CookieStore])
 
-Ongoing issues with this project include;
+Text CAPTCHA's logic questions are aimed at a child's age of 7, so can be solved easily by all but the most cognitively impaired users. As they involve human logic, such questions cannot be solved by a robot.  There are both advantages and disadvantages for using logic questions over image based captchas, {find out more at Text CAPTCHA}[http://textcaptcha.com/why].
+  
+== Demo
 
-* needs tests
+A {fully working demo on heroku}[http://textcaptcha.heroku.com] will be available soon.
 
-== Setup / Using
-
-=== Requirements
+== Requirements
 
 What do you need?
 
-=== Installing
-
-  script/plugin install git://github.com/hiddenloop/acts_as_textcaptcha
-
-== Using
-
-== What does the code do?
+* {Rails}[http://github.com/rails/rails] >= 2.3
+* {Ruby}[http://ruby-lang.org/] >= 1.8.7                                                                                                                      
+* {bcrypt-ruby}[http://bcrypt-ruby.rubyforge.org/] gem (to securely encrypt the spam answers in your session)
+* {Text CAPTCHA api key}[http://textcaptcha.com/register] (_optional_, since you can define your own logic questions, see below for details)             
+* {Rspec}[http://rspec.info/] (_optional_ if you want to run the tests)
+ 
+== Installing            
+
+Install the gems
+
+  sudo gem install acts_as_textcaptcha bcrypt-ruby
+  
+Or you can install it as a Rails plugin 
+
+  script/plugin install git://github.com/hiddenloop/acts_as_textcaptcha    
+  
+== Using             
+           
+First, in your environment.rb file, add the gem to your config like so;
+
+  config.gem 'acts_as_textcaptcha'
+                                                       
+Next configure your models to be spam protected like so; (this is the most basic way to configure the gem, with an api key only)
+
+  class Comment < ActiveRecord::Base
+    acts_as_textcaptcha({'api_key' => 'your_textcaptcha_api_key'})
+  end          
+               
+Next in your controller *new* and *create* actions you'll want to _spamify_ your model like so.  This generates a new spam question on the model;
+
+  def new
+    @comment = Comment.new
+    spamify(@comment)
+  end                                                                                
+
+  def create
+    @comment = Comment.new(params[:comment])
+    if @comment.save
+      ...
+    else
+      spamify(@comment)
+       render :action => 'new'
+    end
+  end       
+      
+Finally, in your form/view erb do something like the following;
+
+  <%- if @comment.validate_spam_answer -%>
+    <%= f.hidden_field :spam_answer, :value => @comment.spam_answer -%>
+  <%- else -%>
+    <%= f.label :spam_answer, @comment.spam_question %>
+    <%= f.text_field :spam_answer, :value => '' %>
+  <%- end -%>
+
+More configurations are available and will be explained here shortly.  If your'e interested now, jump into the code.
+    
+== More Configurations    
+
+You can also configure ActAsTextcaptcha in the following ways.
+
+=== Options hash
+
+You can configure your models with the following options.
+
+  class Comment < ActiveRecord::Base
+    acts_as_textcaptcha({'api_key'     => 'your_textcaptcha_api_key',
+                         'bcrypt_salt' => '$2a$10$j0bmycH.SVfD1b5mpEGPpe',
+                         'bcrypt_cost' => '3',
+                         'questions'   => [{'question' => '1+1', 'answers' => '2,two'},
+                                           {'question' => 'The green hat is what color?', 'answers' => 'green'}]})
+  end 
+  
+* *api_key* (from textcaptcha)
+* *bcrypt_salt* - used to encrypt valid possible answers in your session (recommended if you are using cookie session storage)  NOTE: this  must be a valid bcrypt salt; for security PLEASE CHANGE THIS, open irb and enter; require 'bcrypt'; BCrypt::Engine.generate_salt
+* *bcrypt_cost* - an optional logarithmic var which determines how computational expensive the bcrypt hash is to calculate (a cost of 4 is twice as much work as a cost of 3 - default is 10)
+* *questions* - an array of question and answer hashes (see above)  A random question from this array will be asked if the textcaptcha web service fails
+
+=== config/textcaptcha.yml
+
+The above options can also be expressed in {textcaptcha.yml}[http://github.com/hiddenloop/acts_as_textcaptcha/raw/master/config/textcaptcha.yml] drop this into your Rails config folder.      
+
+It *also* is possible to configure without an api_key, and provide your own logic questions only.
+
+== What does the code do?  
+                            
+* spam answers are not case-sensitive and left/right white space is trimmed
+* if the textcaptcha service is down, the gem will look for user defined questions defined in the options
+* if no questions are found, AND the service is down no spam protection will take place and the model will be valid
+
+Will explain more soon, until then examine the code on github or browse the rdocs.
+
+== Rake
+
+* rake spec (run the tests)
+* rake rcov (run tests showing coverage)
+* rake rdoc (generate docs)
 
 == Credits
 
 Who's who?
 
-* Authored by "Matthew Hutchinson":http://matthewhutchinson.net
+* {ActsAsTextcaptcha}[http://github.com/hiddenloop/acts_as_textcaptcha] authored by {Matthew Hutchinson}[http://matthewhutchinson.net]
+* {Text CAPTCHA}[http://textcaptcha.com] api and service by {Rob Tuley}[http://openknot.com/me/] at {Openknot}[http://openknot.com]
+* Gem and code kindly hosted at {rubygems.org}[http://rubygems.org/gems/acts_as_textcaptcha] and {github.com}[http://github.com/hiddenloop/acts_as_textcaptcha]
 
-== Get out clause
+== Usage
 
-Right now this script is provided without warranty, or support from the author.
+This code is currently used in a number of production websites and applications. It was originally extracted from code developed for  {Bugle}[http://bugleblogs.com]
 
-== Creative Commons License
+* {matthewhutchinson.net}[http://matthewhutchinson.net]
+* {pmFAQtory.com}[http://pmfaqtory.com]
+* {The FAQtory}[http://faqtory.heroku.com]
 
-<a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by/2.0/uk/80x15.png" /></a>
+(if you're happily using acts_as_textcaptcha in production, let me know and I'll add your site/app to the list)

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.1.1

data/acts_as_textcaptcha.gemspec

@@ -0,0 +1,60 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{acts_as_textcaptcha}
+  s.version = "1.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Matthew Hutchinson"]
+  s.date = %q{2010-04-20}
+  s.description = %q{Spam protection for your ActiveRecord models using logic questions and the excellent textcaptcha api. See textcaptcha.com for more details and to get your api key.
+  The logic questions are aimed at a child's age of 7, so can be solved easily by all but the most cognitively impaired users. As they involve human logic, such questions cannot be solved by a robot.
+  For more reasons on why logic questions are useful, see here; http://textcaptcha.com/why}
+  s.email = %q{matt@hiddenloop.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "acts_as_textcaptcha.gemspec",
+     "config/textcaptcha.yml",
+     "init.rb",
+     "lib/acts_as_textcaptcha.rb",
+     "lib/textcaptcha_helper.rb",
+     "rails/init.rb",
+     "spec/acts_as_textcaptcha_spec.rb",
+     "spec/database.yml",
+     "spec/schema.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/hiddenloop/acts_as_textcaptcha}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Spam protection for your models via logic questions and the excellent textcaptcha.com api}
+  s.test_files = [
+    "spec/acts_as_textcaptcha_spec.rb",
+     "spec/schema.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/acts_as_textcaptcha.rb

@@ -29,15 +29,18 @@ module ActsAsTextcaptcha #:nodoc:
   
 
   module InstanceMethods
-
-    def skip_spam_check?; false end
-
+                        
+    # override this method to toggle spam checking, default is on (true)
+    def perform_spam_check?; true end
+    
+    # override this method to toggle allowing the model to be created, default is on (true) 
+    # if returning false model.validate will always be false with errors on base
     def allowed?; true end
 
     def validate     
       if new_record?
         if allowed?
-          if possible_answers && !skip_spam_check? && !validate_spam_answer
+          if possible_answers && perform_spam_check? && !validate_spam_answer
             errors.add(:spam_answer, 'is incorrect, try another question instead') 
             return false
           end
@@ -46,7 +49,7 @@ module ActsAsTextcaptcha #:nodoc:
           return false
         end
       end
-      true
+      super
     end     
     
     def validate_spam_answer

data/lib/textcaptcha_helper.rb

@@ -1,5 +1,6 @@
 module TextcaptchaHelper
-
+                      
+  # generates a spam question and possible answers for a model, answers are stored in  session[:possible_answers] 
   def spamify(model)
     session[:possible_answers] = model.generate_spam_question unless model.validate_spam_answer
   end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 1
-  - 0
-  version: 1.1.0
+  - 1
+  version: 1.1.1
 platform: ruby
 authors: 
 - Matthew Hutchinson
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-19 00:00:00 +01:00
+date: 2010-04-20 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -36,6 +36,7 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
+- acts_as_textcaptcha.gemspec
 - config/textcaptcha.yml
 - init.rb
 - lib/acts_as_textcaptcha.rb