turing 0.0.7

data/COPYRIGHT

@@ -0,0 +1,19 @@
+Turing -- Ruby implementation of Captcha
+
+Copyright (C) 2005 Michal Safranek <wejn@box.cz>
+
+This file is part of http://turing.rubyforge.org/
+
+Turing is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 2 of the License, or (at your option)
+any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

data/README

@@ -0,0 +1,26 @@
+= Turing - Ruby implementation of Captcha
+
+== Purpose / mission
+This project is aimed to provide easy-to-use and easy-to-extend
+implementation of Captcha[http://captcha.net/].
+
+== Download
+Latest version of Turing can be found at
+
+* http://rubyforge.org/frs/?group_id=1132
+
+Unfortunately there's no public SCM repository as of now.
+
+== Installation
+This package is installed as gem, so simple
+
+  gem install --remote turing
+
+should do the trick.
+
+== Examples
+Examples describing how to use this library can be found in class
+descriptions and also in +samples+ directory.
+
+== License
+Turing is provided under GPL version 2, see COPYRIGHT for details.

data/Rakefile

@@ -0,0 +1,75 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+$:.unshift 'lib'
+require 'turing'
+
+spec = Gem::Specification.new do |s|
+	s.name = "turing"
+	s.version = Turing::VERSION
+	s.author = "Michal Safranek"
+	s.email = "wejn@box.cz"
+	s.homepage = "http://turing.rubyforge.org/"
+	s.rubyforge_project = 'turing'
+	s.platform = Gem::Platform::RUBY
+	s.summary = "Another implementation of captcha (http://captcha.net/)"
+	s.description = 'Implementation of captcha (Completely Automated Public Turing-Test to Tell Computers and Humans Apart) that is both easy to use and easy to customize/extend.'
+	
+	candidates = Dir.glob("{bin,lib,shared,tests}/**/*")
+	candidates = candidates.delete_if do |item|
+		item.include?(".svn") || item.include?("rdoc")
+	end
+	candidates += ['README', 'CHANGES', 'TODO', 'COPYING', 'COPYRIGHT', 'Rakefile', 'rdoc.jamis.rb']
+	s.files = candidates
+	s.executables = candidates.select { |x| x =~ /^bin\// }.
+		map { |x| File.basename(x) }
+	
+	s.required_ruby_version = '>=1.8.2'
+
+	s.require_path = "lib"
+	s.autorequire = 'turing'
+
+	#s.test_file = "tests/ts_all.rb"
+	
+	s.has_rdoc = true
+	s.rdoc_options << '--title' << 'Turing Documentation' << '--charset' \
+		<< 'utf-8' << '--line-numbers' << '--inline-source' << '--main' \
+		<< 'README' << '-T' << './rdoc.jamis.rb'
+	s.extra_rdoc_files = ["README"]
+	
+	s.add_dependency("gd2", '>=1.0')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_tar = true
+end
+
+Rake::RDocTask.new("doc") do |rdoc|
+	rdoc.rdoc_dir = 'doc/'
+	rdoc.title    = "Turing Documentation"
+	rdoc.options << '--line-numbers --inline-source --charset utf-8 --main README'
+	rdoc.rdoc_files.include('README')
+	rdoc.rdoc_files.include('lib/**/*.rb')
+
+	rdoc.template = './rdoc.jamis.rb'
+end
+
+task :default => [:gem, :doc]
+
+file "CHANGES" do
+	system "svn log . > CHANGES"
+end
+
+task :cleanup do
+	system "rm -rf pkg doc CHANGES"
+end
+
+task :release do
+	rel = "file:///home/wejn/data/SVN-repo/turing/branches/REL-#{Turing::VERSION}"
+	target = "turing-#{Turing::VERSION}"
+	system "svn co #{rel} #{target}"
+	system "svn log #{rel} > #{target}/CHANGES"
+	system "tar zcf #{target}.tgz #{target}"
+	system "rm -rf #{target}"
+end

data/TODO

@@ -0,0 +1 @@
+- unit tests (how?)

data/lib/turing.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/ruby
+#
+# Turing -- Ruby implementation of Captcha
+#
+# Copyright © 2005 Michal Šafránek <wejn@box.cz>
+#
+# This file is part of http://turing.rubyforge.org/
+#
+# Turing is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation; either version 2 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+# == Turing module
+# This module contains three classes (built on top of each other) that might
+# be used independently:
+# * Turing::Image: Simple obfuscated image generator with plugin design.
+# * Turing::Challenge: Captcha challenge generator and verifier.
+# * Turing::CGIHandler: Simple Turing::Challenge wrapper designed to run as CGI.
+module Turing # {{{
+	VERSION = "0.0.7".freeze
+end # }}}
+
+require 'turing/image'
+require 'turing/challenge'
+require 'turing/cgi_handler'
+
+# vim: set ts=4 sw=4 :

data/lib/turing/cgi_handler.rb

@@ -0,0 +1,251 @@
+#!/usr/bin/ruby
+#
+# Turing -- Ruby implementation of Captcha
+#
+# Copyright © 2005 Michal Šafránek <wejn@box.cz>
+#
+# This file is part of http://turing.rubyforge.org/
+#
+# See turing.rb in lib/ directory for license terms.
+#
+require 'cgi'
+require 'turing'
+require 'turing/challenge'
+require 'erb'
+
+# == Generic (Fast)CGI handler to ease integration into current systems
+#
+# Handles CGI requests using prepared HTML templates and Turing::Challenge
+# object.
+#
+# Example of use:
+#   #!/usr/bin/ruby
+#   require 'rubygems'
+#   require_gem 'turing'
+#   tcgi_config = {
+#       :imagepath => "/imgs",
+#       :outdir => '/home/wejn/ap/htdocs/imgs',
+#       :store => '/home/wejn/ap/data/turing.pstore',
+#       :redirect_to => 'http://localhost:8000/secured/',
+#   }
+#   tcgi_config[:on_success] = proc do
+#       out = {}
+#       out[:headers] = {
+#           "cookie" => CGI::Cookie.new({
+#               'name' => 'turing_passed',
+#               'value' => 'true',
+#               'path' => '/',
+#               'expires' => Time.now + 3600*24,
+#               }),
+#           "dude" => "you_rock!",
+#       }
+#       out
+#   end
+#   Turing::CGIHandler.new(tcgi_config).handle
+# This CGI script forces user to pass turing challenge. After he passes
+# the test, he's given cookie +turing_passed+ with value +true+ and redirected
+# to http://localhost:8000/secured/.
+#
+# <b>Please note</b>: Using this script verbatim is like having no turing
+# challenge at all -- any non-braindead attacker will get around it in no
+# time.
+class Turing::CGIHandler # {{{
+	# Configure instance using options hash.
+	#
+	# *Warning*: Keys of this hash must be symbols.
+	#
+	# Accepted options:
+	# * +templatedir+: directory where templates (challenge.rhtml, error.rhtml, success.rhtml) reside, by default it's set to gem's <tt>shared/templates/</tt> directory.
+	# * +on_success+: proc object (or any object responding to +call+) which returns Hash. Recognized keys of the returned hash are +headers+ and +variables+. Former are used as HTTP response headers, latter are used as variables for success template (if no redirect given).
+	# * +redirect_to+: redirect to this location on success. This can be also done by returning +Location+ header in +on_success+'s +headers+ hash.
+	# * +imagepath+: path under which generated images are accessible.
+	#
+	# Given hash will be also used to initialize Turing::Challenge object.
+	def initialize(options = {}) # {{{
+		@options = options
+		base = File.join(File.dirname(__FILE__), '..', '..', 'shared')
+		
+		if @options[:templatedir].nil?
+			@options[:templatedir] = File.join(base, 'templates')
+		end
+
+		begin
+			td = @options[:templatedir]
+			raise "not directory" unless FileTest.directory?(td)
+		rescue
+			error_response("Templatedir is invalid", $!)
+		end
+		
+		begin
+			@tc = Turing::Challenge.new(@options)
+		rescue
+			error_response("Unable to initialize Turing::Challenge class", $!)
+			exit 1
+		end
+	end # }}}
+	
+	# Handle incoming CGI request.
+	#
+	# If you don't pass one, it will create it using CGI.new
+	def handle(cgi = nil) # {{{
+		cgi ||= CGI.new
+
+		if "POST" == cgi.request_method
+			if @tc.valid_answer?(cgi["id"], cgi["solution"])
+				# process on_success
+				os = @options[:on_success]
+				if os.nil? || ! os.respond_to?(:call)
+					extra = nil
+				else
+					extra = verify_extra(os.call)
+				end
+
+				# is there redir from config or from on_success?
+				if @options[:redirect_to] || extra[:headers]["Location"]
+					redirect_to(cgi, extra[:headers]["Location"] || \
+						@options[:redirect_to], extra)
+				else
+					success_response(cgi, extra)
+				end
+			else
+				show_challenge(cgi, true)
+			end
+		else
+			show_challenge(cgi)
+		end
+	end # }}}
+
+	private
+
+	# generate error exception
+	def error_response(what, exc, cgi = nil) # {{{
+		cgi ||= CGI.new
+		$stderr.puts "What: #{$!.to_s}"
+		cgi.out do
+			begin
+				Template.new(template_file("error.rhtml"), {
+					:what => what,
+					:explanation => exc.to_s,
+					:backtrace => exc.backtrace.join("\n"),
+				}).render
+			rescue
+				err = [what, '', exc.to_s, '', exc.backtrace.join("\n")]
+				"<pre>" + CGI.escapeHTML(err.join("\n")) + "</pre>"
+			end
+		end
+	end # }}}
+
+	# generate challenge and show it
+	def show_challenge(cgi, bad_try = false) # {{{
+		c = nil
+		begin
+			c = @tc.generate_challenge
+		rescue
+			error_response("Unable to generate challenge", $!, cgi)
+		end
+
+		cgi.out do
+			begin
+				Template.new(template_file("challenge.rhtml"), {
+					:already_failed => bad_try,
+					:file => File.join(@options[:imagepath] || '', c.file),
+					:id => c.id,
+				}).render
+			rescue => exc
+				error_response("Unable to render template", exc, cgi)
+			end
+		end
+	end # }}}
+
+	# show success response
+	def success_response(cgi, extra = {}) # {{{
+		cgi.out(extra[:headers]) do
+			begin
+				Template.new(template_file("success.rhtml"),
+					extra[:variables]).render
+			rescue => exc
+				error_response("Unable to render template", exc, cgi)
+			end
+		end
+	end # }}}
+
+	# redirect to given location
+	def redirect_to(cgi, where, extra = {}) # {{{
+		params = {
+			"Location" => where,
+		}
+		params.merge!(extra[:headers])
+		cgi.out(params) do
+			<<-EOF
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML><HEAD>
+<META HTTP-EQUIV='refresh' CONTENT='1;url=#{CGI.escapeHTML(where.to_s)}'>
+<TITLE>302 Found</TITLE>
+</HEAD><BODY>
+<H1>Found</H1>
+The document has moved <A HREF="#{CGI.escapeHTML(where.to_s)}">here</A>.<P>
+</BODY></HTML>
+			EOF
+		end
+
+	end # }}}
+
+	# verify/correct "extra" object returned from on_success
+	def verify_extra(extra) # {{{
+		out = {
+			:headers => {},
+			:variables => {},
+		}
+		extra = {} if extra.nil? || ! extra.kind_of?(Hash)
+		out[:headers] = extra[:headers] if extra[:headers].kind_of?(Hash)
+		out[:variables] = extra[:variables] if extra[:variables].kind_of?(Hash)
+		out
+	end # }}}
+	
+	# template name to abs path to file
+	def template_file(name) # {{{
+		name += ".rhtml" unless name =~ /\.rhtml$/
+		File.join(@options[:templatedir], name)
+	end # }}}
+
+	public
+
+	# == Simple template engine
+	# Essentially just convenient wrapper around ERB which is used internally by Turing::CGIHandler.
+	class Template # {{{
+		# Specify template file (+what+) and +variables+ that will be pushed as instance variables to the Template.
+		def initialize(what, variables = nil) # {{{
+			(variables || {}).each do |k,v|
+				instance_variable_set("@" + k.to_s, v)
+			end
+			@__what__ = what
+		end # }}}
+
+		# render given template and return result as string.
+		def render # {{{
+			erb = ERB.new(File.open(@__what__).read, nil, '%-')
+			erb.result(binding)
+		rescue
+			raise "Failure rendering template #{@what}: #{$!}"
+		end # }}}
+
+		# shortcut for <tt>CGI.escapeHTML</tt>
+		#
+		# <i>can you say "Rails" ? :)</i>
+		def h(var) # {{{
+			CGI.escapeHTML(var)
+		end # }}}
+	end # }}}
+end # }}}
+
+# execute if called directly
+if __FILE__ == $0 # {{{
+	Turing::CGIHandler.new({
+		:imagepath => '.',
+		:outdir => '.',
+		:store => 'store',
+	}).handle
+	exit 0 # 'turing' requires 'turing/challenge' which might make loop
+end # }}}
+
+# vim: set ts=4 sw=4 :

data/lib/turing/challenge.rb

@@ -0,0 +1,214 @@
+#!/usr/bin/ruby
+#
+# Turing -- Ruby implementation of Captcha
+#
+# Copyright © 2005 Michal Šafránek <wejn@box.cz>
+#
+# This file is part of http://turing.rubyforge.org/
+#
+# See turing.rb in lib/ directory for license terms.
+#
+require 'pstore'
+require 'turing'
+require 'turing/image'
+require 'digest/sha2'
+
+# == Captcha challenge generator and verifier
+# Purpose of this class is to provide abstraction layer (on top of PStore
+# and Turing::Image) you can use to build Captcha challenge/response
+# mechanism.
+#
+# Example of use:
+#   tc = Turing::Challenge.new(:store => 'store', :outdir => '.')
+#   c = tc.generate_challenge
+#
+#   system("xv", c.file)
+#
+#   puts "Enter solution:"
+#   r = $stdin.gets.chomp
+#
+#   if tc.valid_answer?(c.id, r)
+#       puts "That's right."
+#   else
+#       puts "I don't think so."
+#   end
+# In this example records about generated challenges are stored in file
+# +store+ which is simple PStore. Images are generated via Turing::Image
+# to current directory and then displayed via "xv" image viewer.
+class Turing::Challenge # {{{
+	# Configure instance using options hash.
+	#
+	# *Warning*: Keys of this hash must be symbols.
+	#
+	# Accepted options:
+	# * +store+: File to be used as PStore for challenges. Default: <tt>$TMPDIR/turing-challenges.pstore</tt>.
+	# * +dictionary+: Filename to be used as dictionary (base for random words). Default: gem's <tt>shared/dictionary</tt> file.
+	# * +lifetime+: Lifetime for generated challenge in seconds (to prevent "harvesting").
+	# * +outdir+: Outdir for images generated by Turing::Image. Default: <tt>$TMPDIR</tt>.
+	#
+	# Given hash will be also used to initialize Turing::Image object.
+	def initialize(opts = {}) # {{{
+		raise ArgumentError, "Opts must be hash!" unless opts.kind_of? Hash
+
+		tmpdir = ENV["TMPDIR"] || '/tmp'
+		base = File.join(File.dirname(__FILE__), '..', '..', 'shared')
+		@options = {
+			:store => File.join(tmpdir, 'turing-challenges.pstore'),
+			:dictionary => File.join(base, 'dictionary'),
+			:lifetime => 10*60, # 10 minutes
+			:outdir => tmpdir,
+		}
+
+		@options.merge!(opts)
+
+		begin
+			@store = PStore.new(@options[:store])
+		rescue
+			raise ArgumentError, "Failed to initialize store: #{$!}"
+		end
+
+		begin
+			File.open(@options[:dictionary]) do |f|
+				@dictionary = f.readlines.map! { |x| x.strip }
+			end
+		rescue
+			raise ArgumentError, "Failed to load dictionary: #{$!}"
+		end
+
+		begin
+			@ti = Turing::Image.new(@options)
+		rescue
+			raise ArgumentError, "Failed to initialize Turing::Image: #{$!}"
+		end
+	end # }}}
+
+	# Challenge object we store
+	ChallengeObject = Struct.new(:answer, :when) # :nodoc:
+
+	# Generated challenge Struct -- returned from generate_challenge
+	GeneratedChallenge = Struct.new(:file, :id)
+
+	# Generate challenge (image containing random word from configured
+	# dictionary) and return +GeneratedChallenge+ containing +file+
+	# (basename) and +id+ of this challenge.
+	#
+	# Generation of challenge is retried three times -- to descrease possibility
+	# it will fail due to a bug in plugin. But if that happens, we just raise
+	# +RuntimeError+.
+	def generate_challenge # {{{
+		id = nil
+		word = nil
+		tries = 3
+		err = nil
+		fname = nil
+		
+		begin
+			id = random_id
+			fname = id + ".jpg"
+			word = @dictionary[rand(@dictionary.size)]
+			@ti.generate(fname, word)
+		rescue Object => err
+			tries -= 1
+			retry if tries > 0
+		end
+		raise "Failed to generate: #{err}" unless err.nil?
+
+		begin
+			@store.transaction do
+				@store[id] = ChallengeObject.new(word, Time.now)
+			end
+		rescue
+			raise "Failed to save to store: #{$!}"
+		end
+		
+		GeneratedChallenge.new(fname, id)
+	end # }}}
+
+	# Check if +answer+ for challenge with given +id+ is valid.
+	#
+	# Also removes image file and challenge from the store.
+	def valid_answer?(id, answer) # {{{
+		ret = false
+		begin
+			@store.transaction do
+				object = @store[id]
+
+				# out if not found
+				break if object.nil?
+
+				# remove from store and delete img
+				@store.delete(id)
+				begin
+					n = File.join(@options[:outdir], id + '.jpg')
+					File.unlink(n)
+				rescue Object
+				end
+
+				# true if it's ok
+				if object.answer == answer && \
+						Time.now < object.when + (@options[:lifetime] || 0)
+					ret = true
+				end
+			end
+		rescue
+		end
+		ret
+	end # }}}
+
+	private
+	# SHA algorithm "strength" for +random_id+ generation
+	SHA_STRENGTH = 256 # 256, 384, 512
+	
+	# Random device used for +random_id+ generation
+	#
+	# *Warning*: don't use /dev/random unless you have LOTS of entropy available!
+	RANDOM_DEVICE = '/dev/urandom' # '/dev/random'
+
+	# generate random ID using SHA* algo family
+	def random_id # {{{
+		strength = SHA_STRENGTH
+		algo = nil
+		begin
+			algo = Digest.const_get("SHA" + strength.to_s)
+		rescue
+			# We got wrong SHA_STRENGTH, fallback to default (256) if possible
+			unless strength == 256
+				strength = 256
+				retry
+			else
+				raise RuntimeError, "SHA hash algorithm family not available"
+			end
+		end
+		begin
+			algo.hexdigest(File.open(RANDOM_DEVICE).sysread(strength / 8 + 1))
+		rescue
+			# XXX: fall-back, but shouldn't happen
+			poor_randomness = [
+				Process.pid, rand(65535), Time.now.to_i, Time.now.usec,
+				rand(65535)].map { |x| x.to_s }.join(':')
+			algo.hexdigest(poor_randomness)
+		end
+	end # }}}
+end # }}}
+
+# test it if invoked directly
+if __FILE__ == $0 # {{{
+	tc = Turing::Challenge.new(:store => 'store', :outdir => '.')
+
+	c = tc.generate_challenge
+
+	system("xv", c.file)
+
+	puts "Enter solution:"
+	r = $stdin.gets.chomp
+
+	if tc.valid_answer?(c.id, r)
+		puts "That's right."
+	else
+		puts "I don't think so."
+	end
+
+	exit 0
+end # }}}
+
+# vim: set ts=4 sw=4 :