## ActAsTextcaptcha [![Gem](https://img.shields.io/gem/v/acts_as_textcaptcha.svg?style=flat)](http://rubygems.org/gems/acts_as_textcaptcha) [![Travis](https://img.shields.io/travis/matthutchinson/acts_as_textcaptcha/master.svg?style=flat)](https://travis-ci.org/matthutchinson/acts_as_textcaptcha) [![Depfu](https://img.shields.io/depfu/matthutchinson/acts_as_textcaptcha.svg?style=flat)](https://depfu.com/github/matthutchinson/acts_as_textcaptcha) [![Maintainability](https://api.codeclimate.com/v1/badges/c67969dd7b921477bdcc/maintainability)](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/c67969dd7b921477bdcc/test_coverage)](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/test_coverage) ActsAsTextcaptcha provides spam protection for Rails models with a text-based logic question captcha. Questions are fetched from [Rob Tuley's](https://twitter.com/robtuley) [textcaptcha.com](http://textcaptcha.com/). They can be solved easily by humans but are tough for robots to crack. The gem can also be configured with your own questions; as an alternative, or as a fallback to handle any API issues. For reasons on why logic based captchas are a good idea visit [textcaptcha.com](http://textcaptcha.com). ## Requirements * [Ruby](http://ruby-lang.org/) >= 2.1.0 * [Rails](http://github.com/rails/rails) >= 3 * [Rails.cache](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores) ## Demo Try a [working demo here](https://acts-as-textcaptcha-demo.herokuapp.com)! **Or** one-click deploy your own demo app at Heroku. See [here](https://github.com/matthutchinson/acts_as_textcaptcha_demo) for details. [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/matthutchinson/acts_as_textcaptcha_demo/tree/master) ## Installation Add this line to your Gemfile and run `bundle install`: ```ruby gem 'acts_as_textcaptcha' ``` Add this to models you'd like to protect: ```ruby class Comment < ApplicationRecord acts_as_textcaptcha api_key: 'TEXTCAPTCHA_API_IDENTITY' # see below for more config options end ``` [Rob](https://twitter.com/robtuley) requests that your `TEXTCAPTCHA_API_IDENTITY` be some reference to yourself (e.g. an email address, domain or similar) so you can be contacted should any usage problem occur. In your controller's `new` action call the `textcaptcha` method: ```ruby def new @comment = Comment.new @comment.textcaptcha   end ``` Finally add the question and answer fields to your form using the `textcaptcha_fields` helper. Arrange the HTML within this block as you like. ```ruby <%= textcaptcha_fields(f) do %>
<%= f.label :textcaptcha_answer, @comment.textcaptcha_question %>
<%= f.text_field :textcaptcha_answer, :value => '' %>
<% end %> ``` If you'd prefer to construct your own form elements, take a look at the HTML produced [here](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_helper.rb). ## Configuration The following options are available (only `api_key` is required): * **api_key** (_required_) - a reference to yourself (e.g. your email or domain). * **questions** (_optional_) - array of your own questions and answers (see below). * **cache_expiry_minutes** (_optional_) - how long valid answers are cached for (default 10 minutes). * **raise_errors** (_optional_) - if true, API or network errors are raised (default false, errors logged). * **api_endpoint** (_optional_) - set your own JSON API endpoint to fetch from (see below). For example: ```ruby class Comment < ApplicationRecord acts_as_textcaptcha api_key: 'TEXTCAPTCHA_API_IDENTITY_KEY', raise_errors: false, cache_expiry_minutes: 10, questions: [ { 'question' => '1+1', 'answers' => '2,two' }, { 'question' => 'The green hat is what color?', 'answers' => 'green' } ] end ``` ### YAML config You can apply an app wide config with a `config/textcaptcha.yml` file. Use this rake task to add one from a [template](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_config.rb): $ bundle exec rake textcaptcha:config **NOTE**: Any options set in models take preference over this config. ### Config without the TextCaptcha service To use __only__ your own logic questions, omit the `api_key` and set them in the config (see above). Multiple answers to the same question must be comma separated e.g. `2,two` (so do not include commas in answers). You can optionally set your own `api_endpoint` to fetch questions and answers from. The URL must respond with a JSON object like this: ```ruby { "q": "What number is 4th in the series 39, 11, 31 and nineteen?", "a": ["1f0e3dad99908345f7439f8ffabdffc4","1d56cec552bf111de57687e4b5f8c795"] } ``` With `"a"` being an array of answer strings, MD5'd, and lower-cased. The `api_key` option is ignored if an `api_endpoint` is set. ### Toggling TextCaptcha Enable or disable captchas by overriding the `perform_textcaptcha?` method (in models). By default the method checks if the object is a new (unsaved) record. So spam protection is __only__ enabled for creating new records (not updating). Here's an example overriding the default behaviour but maintaining the new record check. ```ruby class Comment < ApplicationRecord acts_as_textcaptcha :api_key => 'TEXTCAPTCHA_API_IDENTITY' def perform_textcaptcha? super && user.admin? end end ``` ## Translations The following strings are translatable (with Rails I18n translations): ```yaml en: activerecord: errors: models: comment: attributes: textcaptcha_answer: incorrect: "is incorrect, try another question instead" expired: "was not submitted quickly enough, try another question instead" activemodel: attributes: comment: textcaptcha_answer: "TextCaptcha answer" ``` **NOTE**: The textcaptcha.com API only provides logic questions in English. ## Handling Errors The API may be unresponsive or return an unexpected response. If you've set `raise_errors: true`, consider handling these errors: * `ActsAsTextcaptcha::ResponseError` * `ActsAsTextcaptcha::ParseError` * `ActsAsTextcaptcha::ApiKeyError` ## Development Check out this repo and run `bin/setup`, this will install gem dependencies and generate docs. Use `bundle exec rake` to run tests and generate a coverage report. You can also run `bin/console` for an interactive prompt to experiment with the code. ## Tests MiniTest is used for testing. Run the test suite with: $ rake test This gem uses [appraisal](https://github.com/thoughtbot/appraisal) to test against multiple versions of Rails. * `appraisal rake test` (run tests against all Gemfile variations) * `appraisal rails-3 rake test` (run tests against a specific Gemfile) ## Docs Generate docs for this gem with: $ rake rdoc ## Troubles? If you think something is broken or missing, please raise a new [issue](https://github.com/matthutchinson/acts_as_textcaptcha/issues). Please remember to check it hasn't already been raised. ## Contributing Bug [reports](https://github.com/matthutchinson/acts_as_textcaptcha/issues) and [pull requests](https://github.com/matthutchinson/acts_as_textcaptcha/pulls) are welcome on GitHub. When submitting pull requests, remember to add tests covering any new behaviour, and ensure all tests are passing on [Travis](https://travis-ci.org/matthutchinson/acts_as_textcaptcha). Read the [contributing guidelines](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/CONTRIBUTING.md) for more details. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. See [here](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/CODE_OF_CONDUCT.md) for more details. ## Todo * Allow translatable user supplied questions and answers in config * Allow `Net::HTTP` to be swapped out for any another HTTP client. ## License The code is available as open source under the terms of [LGPL-3](https://opensource.org/licenses/LGPL-3.0). ## Who's who? * [ActsAsTextcaptcha](http://github.com/matthutchinson/acts_as_textcaptcha) and [little robot drawing](http://www.flickr.com/photos/hiddenloop/4541195635/) by [Matthew Hutchinson](http://matthewhutchinson.net) * [TextCaptcha](http://textcaptcha.com) API and service by [Rob Tuley](https://twitter.com/robtuley) ## Links * [Demo](https://acts-as-textcaptcha-demo.herokuapp.com) * [Travis CI](http://travis-ci.org/#!/matthutchinson/acts_as_textcaptcha) * [Maintainability](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/maintainability) * [Test Coverage](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/test_coverage) * [RDoc](http://rdoc.info/projects/matthutchinson/acts_as_textcaptcha) * [Wiki](http://wiki.github.com/matthutchinson/acts_as_textcaptcha/) * [Issues](http://github.com/matthutchinson/acts_as_textcaptcha/issues) * [Report a bug](http://github.com/matthutchinson/acts_as_textcaptcha/issues/new) * [Gem](http://rubygems.org/gems/acts_as_textcaptcha) * [GitHub](http://github.com/matthutchinson/acts_as_textcaptcha)