recaptcha 0.3.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a2ab60ab04802c7dc8a205ffa010071d2edd9f47
-  data.tar.gz: 7155b2dcb7ee6c183b3a06b6768562daf6e3e2da
+  metadata.gz: 15a8d9b4ffc50fb479df2f03065310e3b85be5f4
+  data.tar.gz: 1d2412b3ce72619d131388e77e9b82a4b1e9de46
 SHA512:
-  metadata.gz: b2dcd0d13ae9dcbb8f9c96a7c65e0231f058a7979696bd181fe101640f5c3778d02b8dbb39d898f2bcd2a788b1ab062dbb0b027619d71a6c55af9e2e8a0cf151
-  data.tar.gz: c55e6b3701db18b477ea056b289ec710e550daa71dfe3d03c3540ebdd8e22adef22969fac2013bc0b8586cb65ec89acef72200984fa1765d119b83568676d9aa
+  metadata.gz: f1a53822196216dc231d60369edcce9719e724e4e66a35b57e35b7b57ca8104b2d5211a07231616fad499c13420daa3eb584b5337e87dd47631d40e61d801721
+  data.tar.gz: e3fef919669e86e48de71216c3def51609e1d525d1fe7cebc5ada112f5f9613d96783625c0d675cddfeafce97d7783006665371db42be17f027248945784ebc6

data/CHANGELOG

@@ -1,3 +1,11 @@
+== 0.3.6 / 2012-01-07
+
+* Many documentation changes
+* Fixed deprecations in dependencies
+* Protocol relative JS includes
+* Fixes for options hash
+* Fixes for failing tests
+
 == 0.3.5 / 2012-05-02
 
 * I18n for error messages

data/README.md

@@ -0,0 +1,295 @@
+# reCAPTCHA
+
+Author:    Jason L Perry (http://ambethia.com)<br/>
+Copyright: Copyright (c) 2007-2013 Jason L Perry<br/>
+License:   [MIT](http://creativecommons.org/licenses/MIT/)<br/>
+Info:      https://github.com/ambethia/recaptcha<br/>
+Bugs:      https://github.com/ambethia/recaptcha/issues<br/>
+
+This plugin adds helpers for the [reCAPTCHA API](https://www.google.com/recaptcha). In your
+views you can use the `recaptcha_tags` method to embed the needed javascript,
+and you can validate in your controllers with `verify_recaptcha` or `verify_recaptcha!`,
+which throws an error on failiure.
+
+Beforehand you need to configure Recaptcha with your custom private and public
+key. You may find detailed examples below. Exceptions will be raised if you
+call these methods and the keys can't be found.
+
+## Rails Installation
+
+```Ruby
+gem "recaptcha", require: "recaptcha/rails"
+```
+
+(Rails < 3.0: install an older release and view it's README)
+
+## Setting up your API Keys
+
+There are multiple ways to setup your reCAPTCHA API key once you
+[obtain a pair](https://www.google.com/recaptcha/admin).
+
+### Recaptcha.configure
+
+You may use the block style configuration. The following code could be placed
+into a `config/initializers/recaptcha.rb` when used in a Rails project.
+
+```Ruby
+Recaptcha.configure do |config|
+  config.public_key  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
+  config.private_key = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
+  # Uncomment the following line if you are using a proxy server:
+  # config.proxy = 'http://myproxy.com.au:8080'
+  # Uncomment if you want to use the older version of the API,
+  # only works for versions >= 0.3.7, default value is 'v2':
+  # config.api_version = 'v1'
+end
+```
+
+This way, you may also set additional options to fit recaptcha into your
+deployment environment.
+
+### Recaptcha.with_configuration
+
+If you want to temporarily overwrite the configuration you set with 
+`Recaptcha.configure` (when testing, for example), you can use a 
+`Recaptcha#with_configuration` block:
+
+```Ruby
+Recaptcha.with_configuration(public_key: '12345') do
+  # Do stuff with the overwritten public_key.
+end
+```
+
+### Heroku & Shell environment
+
+Or, you can keep your keys out of your code base by exporting the following
+environment variables. You might do this in the .profile/rc, or equivalent for
+the user running your application. This would also be the preffered method
+in an Heroku deployment.
+
+```
+export RECAPTCHA_PUBLIC_KEY  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
+export RECAPTCHA_PRIVATE_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
+```
+
+### Per call
+
+You can also pass in your keys as options at runtime, for example:
+
+```Ruby
+recaptcha_tags public_key: '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
+```
+
+and later,
+
+```Ruby
+verify_recaptcha private_key: '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
+```
+
+This option might be useful, if the same code base is used for multiple
+reCAPTCHA setups.
+
+## To use 'recaptcha'
+
+Add `recaptcha_tags` to each form you want to protect. 
+Place it where you want the recaptcha widget to appear.
+
+Example:
+
+```Erb
+<%= form_for @foo do |f| %>
+  # ... additional lines truncated for brevity ...
+  <%= recaptcha_tags %>
+  # ... additional lines truncated for brevity ...
+<% end %>
+```
+
+And, add `verify_recaptcha` logic to each form action that you've protected.
+
+### recaptcha_tags
+
+Some of the options available:
+
+| Option      | Description |
+|-------------|-------------|
+| :ssl        | Uses secure http for captcha widget (default `false`, but can be changed by setting `config.use_ssl_by_default`)|
+| :noscript   | Include <noscript> content (default `true`)|
+| :display    | Takes a hash containing the `theme` and `tabindex` options per the API. (default `nil`), options: 'red', 'white', 'blackglass', 'clean', 'custom'|
+| :ajax       | Render the dynamic AJAX captcha per the API. (default `false`)|
+| :public_key | Your public API key, takes precedence over the ENV variable (default `nil`)|
+| :error      | Override the error code returned from the reCAPTCHA API (default `nil`)|
+| :stoken     | Include in reCAPTCHA API v2 the security token (default `true`)|
+| :size       | Specify a size (default `nil`)|
+
+
+You can also override the html attributes for the sizes of the generated `textarea` and `iframe`
+elements, if CSS isn't your thing. Inspect the source of `recaptcha_tags` to see these options.
+
+### verify_recaptcha
+
+This method returns `true` or `false` after processing the parameters from the reCAPTCHA widget. Why
+isn't this a model validation? Because that violates MVC. You can use it like this, or how ever you
+like. Passing in the ActiveRecord object is optional, if you do--and the captcha fails to verify--an
+error will be added to the object for you to use.
+
+Some of the options available:
+
+| Option       | Description |
+|--------------|-------------|
+| :model       | Model to set errors
+| :attribute   | Model attribute to receive errors (default :base)
+| :message     | Custom error message
+| :private_key | Your private API key, takes precedence over the ENV variable (default `nil`).
+| :timeout     | The number of seconds to wait for reCAPTCHA servers before give up. (default `3`)
+
+```Ruby
+respond_to do |format|
+  if verify_recaptcha(model @post, message: "Oh! It's error with reCAPTCHA!") && @post.save
+    # ...
+  else
+    # ...
+  end
+end
+```
+
+### Add multiple widgets to the same page
+
+This is an example taken from the [official google documentation](https://developers.google.com/recaptcha/docs/display).
+
+Add a script tag for a callback
+
+```Html
+<script type="text/javascript">
+  var verifyCallback = function(response) {
+    alert(response);
+  };
+  var widgetId1;
+  var widgetId2;
+  var onloadCallback = function() {
+    // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
+    // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
+    widgetId1 = grecaptcha.render('example1', {
+      'sitekey' : "<%= Recaptcha.configuration.public_key %>",
+      'theme' : 'light'
+    });
+    widgetId2 = grecaptcha.render(document.getElementById('example2'), {
+      'sitekey' : "<%= Recaptcha.configuration.public_key %>"
+    });
+    grecaptcha.render('example3', {
+      'sitekey' : "<%= Recaptcha.configuration.public_key %>",
+      'callback' : verifyCallback,
+      'theme' : 'dark'
+    });
+  };
+</script>
+```
+
+In the callback you will have the `sitekey` generated by this gem with `<%= Recaptcha.configuration.public_key %>`
+
+Next you need to have some elements with an id matching those specified in the callback
+
+```Erb
+<%= form_for @foo do |f| %>
+  # ... additional lines truncated for brevity ...
+  <div id="example1"></div>
+  # ... additional lines truncated for brevity ...
+<% end %>
+<%= form_for @foo2 do |f| %>
+  # ... additional lines truncated for brevity ...
+  <div id="example2"></div>
+  # ... additional lines truncated for brevity ...
+<% end %>
+<%= form_for @foo3 do |f| %>
+  # ... additional lines truncated for brevity ...
+  <div id="example3"></div>
+  # ... additional lines truncated for brevity ...
+<% end %>
+```
+
+And finally you need a script tag that gets the reCAPTCHA code from google and tells it that your code is explicit and gives it the callback.
+
+```Html
+<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit" async defer></script>
+```
+
+Now all together:
+
+```Html
+<html>
+  <head>
+    <title>reCAPTCHA demo: Explicit render for multiple widgets</title>
+    <script type="text/javascript">
+      var verifyCallback = function(response) {
+        alert(response);
+      };
+      var widgetId1;
+      var widgetId2;
+      var onloadCallback = function() {
+        // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
+        // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
+        widgetId1 = grecaptcha.render('example1', {
+          'sitekey' : "<%= Recaptcha.configuration.public_key %>",
+          'theme' : 'light'
+        });
+        widgetId2 = grecaptcha.render(document.getElementById('example2'), {
+          'sitekey' : "<%= Recaptcha.configuration.public_key %>"
+        });
+        grecaptcha.render('example3', {
+          'sitekey' : "<%= Recaptcha.configuration.public_key %>",
+          'callback' : verifyCallback,
+          'theme' : 'dark'
+        });
+      };
+    </script>
+  </head>
+  <body>
+    <%= form_for @foo do |f| %>
+      # ... additional lines truncated for brevity ...
+      <div id="example1"></div>
+      # ... additional lines truncated for brevity ...
+    <% end %>
+    <%= form_for @foo2 do |f| %>
+      # ... additional lines truncated for brevity ...
+      <div id="example2"></div>
+      # ... additional lines truncated for brevity ...
+    <% end %>
+    <%= form_for @foo3 do |f| %>
+      # ... additional lines truncated for brevity ...
+      <div id="example3"></div>
+      # ... additional lines truncated for brevity ...
+    <% end %>
+    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit" async defer></script>
+  </body>
+</html>
+```
+
+The only real difference between this example and the google example is you will use the `<%= Recaptcha.configuration.public_key %>` for the `sitekey`
+
+If your callback has to live on another file (maybe a layout), then you would set the callback on window `window.onloadCallback = function() {...}`
+
+Then on the backend, you will still use the `verify_recaptcha` as explained in this readme.
+
+## I18n support
+reCAPTCHA passes two types of error explanation to a linked model. It will use the I18n gem
+to translate the default error message if I18n is available. To customize the messages to your locale,
+add these keys to your I18n backend:
+
+`recaptcha.errors.verification_failed` error message displayed if the captcha words didn't match
+`recaptcha.errors.recaptcha_unreachable` displayed if a timeout error occured while attempting to verify the captcha
+
+Also you can translate API response errors to human friendly by adding translations to the locale (`config/locales/en.yml`):
+
+```Yaml
+en:
+  recaptcha:
+    errors:
+      incorrect-captcha-sol: 'Fail'
+```
+
+## Testing
+By default, reCAPTCHA is skipped on "test" env, so if you need to make sure it's working properly, just remove the "test" entry of the skip_environment inside Recapcha class, look:
+
+
+```Ruby
+Recaptcha.configuration.skip_verify_env.delete("test")
+```

data/lib/recaptcha.rb

@@ -1,13 +1,26 @@
 require 'recaptcha/configuration'
 require 'recaptcha/client_helper'
 require 'recaptcha/verify'
+require 'recaptcha/token'
 
 module Recaptcha
-  RECAPTCHA_API_SERVER_URL        = '//www.google.com/recaptcha/api'
-  RECAPTCHA_API_SECURE_SERVER_URL = 'https://www.google.com/recaptcha/api'
-  RECAPTCHA_VERIFY_URL            = 'http://www.google.com/recaptcha/api/verify'
+  CONFIG =
+    {
+      'v1' => {
+        'server_url' => '//www.google.com/recaptcha/api',
+        'secure_server_url' => 'https://www.google.com/recaptcha/api',
+        'verify_url' => 'http://www.google.com/recaptcha/api/verify'
+      },
+
+      'v2' => {
+        'server_url' => '//www.google.com/recaptcha/api.js',
+        'secure_server_url' => 'https://www.google.com/recaptcha/api.js',
+        'verify_url' => 'https://www.google.com/recaptcha/api/siteverify'
+      }
+    }
+
+  RECAPTCHA_API_VERSION           = 'v2'
   USE_SSL_BY_DEFAULT              = false
-
   HANDLE_TIMEOUTS_GRACEFULLY      = true
   SKIP_VERIFY_ENV = ['test', 'cucumber']
 
@@ -43,8 +56,7 @@ module Recaptcha
 
   class RecaptchaError < StandardError
   end
-end
 
-if defined?(Rails)
-  require 'recaptcha/rails'
+  class VerifyError < RecaptchaError
+  end
 end

data/lib/recaptcha/client_helper.rb

@@ -3,6 +3,11 @@ module Recaptcha
     # Your public API can be specified in the +options+ hash or preferably
     # using the Configuration.
     def recaptcha_tags(options = {})
+      return v1_tags(options) if Recaptcha.configuration.v1?
+      return v2_tags(options) if Recaptcha.configuration.v2?
+    end # recaptcha_tags
+
+    def v1_tags(options)
       # Default options
       key   = options[:public_key] ||= Recaptcha.configuration.public_key
       raise RecaptchaError, "No public key specified." unless key
@@ -16,11 +21,18 @@ module Recaptcha
         html << %{</script>\n}
       end
       if options[:ajax]
+        if options[:display] && options[:display][:custom_theme_widget]
+          widget = options[:display][:custom_theme_widget]
+        else
+          widget = "dynamic_recaptcha"
+          html << <<-EOS
+           <div id="#{widget}"></div>
+          EOS
+        end
         html << <<-EOS
-          <div id="dynamic_recaptcha"></div>
           <script type="text/javascript">
             var rc_script_tag = document.createElement('script'),
-                rc_init_func = function(){Recaptcha.create("#{key}", document.getElementById("dynamic_recaptcha")#{',RecaptchaOptions' if options[:display]});}
+                rc_init_func = function(){Recaptcha.create("#{key}", document.getElementById("#{widget}")#{',RecaptchaOptions' if options[:display]});}
             rc_script_tag.src = "#{uri}/js/recaptcha_ajax.js";
             rc_script_tag.type = 'text/javascript';
             rc_script_tag.onload = function(){rc_init_func.call();};
@@ -48,7 +60,57 @@ module Recaptcha
         end
       end
       return (html.respond_to?(:html_safe) && html.html_safe) || html
-    end # recaptcha_tags
+    end
+
+    def v2_tags(options)
+      public_key   = options[:public_key] ||= Recaptcha.configuration.public_key
+      raise RecaptchaError, "No public key specified." unless public_key
+      private_key  = options[:private_key] ||= Recaptcha.configuration.private_key
+      raise RecaptchaError, "No private key specified." unless private_key
+      error = options[:error] ||= ((defined? flash) ? flash[:recaptcha_error] : "") # TODO not being used !?
+      uri   = Recaptcha.configuration.api_server_url(options[:ssl])
+      uri += "?hl=#{options[:hl]}" unless options[:hl].blank?
+
+      html = ""
+      html << %{<script src="#{uri}" async defer></script>\n}
+
+      data_attributes = options.slice(:theme, :type, :callback, :expired_callback, :size)
+      data_attributes[:sitekey] = public_key
+
+      if options[:stoken] != false
+        data_attributes[:stoken] = Recaptcha::Token.secure_token
+      end
+
+      data_attributes = data_attributes.map {|k,v| %{data-#{k.to_s.gsub(/_/,'-')}="#{v}"} }.join(" ")
+
+      html << %{<div class="g-recaptcha" #{data_attributes}></div>\n}
+
+      unless options[:noscript] == false
+        fallback_uri = "#{uri.chomp('.js')}/fallback?k=#{public_key}"
+        html << %{<noscript>}
+        html << %{<div style="width: 302px; height: 352px;">}
+        html << %{  <div style="width: 302px; height: 352px; position: relative;">}
+        html << %{    <div style="width: 302px; height: 352px; position: absolute;">}
+        html << %{      <iframe src="#{fallback_uri}"}
+        html << %{                frameborder="0" scrolling="no"}
+        html << %{                style="width: 302px; height:352px; border-style: none;">}
+        html << %{        </iframe>}
+        html << %{      </div>}
+        html << %{      <div style="width: 250px; height: 80px; position: absolute; border-style: none; }
+        html << %{             bottom: 21px; left: 25px; margin: 0px; padding: 0px; right: 25px;">}
+        html << %{        <textarea id="g-recaptcha-response" name="g-recaptcha-response" }
+        html << %{                  class="g-recaptcha-response" }
+        html << %{                  style="width: 250px; height: 80px; border: 1px solid #c1c1c1; }
+        html << %{                  margin: 0px; padding: 0px; resize: none;" value=""> }
+        html << %{        </textarea>}
+        html << %{      </div>}
+        html << %{    </div>}
+        html << %{  </div>}
+        html << %{</noscript>}
+      end
+
+      (html.respond_to?(:html_safe) && html.html_safe) || html
+    end
 
     private
 
@@ -57,7 +119,7 @@ module Recaptcha
       result << hash.map do |k, v|
         if v.is_a?(Hash)
           "\"#{k}\": #{hash_to_json(v)}"
-        elsif ! v.is_a?(String) || k.to_s == "callback"
+        elsif ! v.is_a?(String) || k.to_s =~ %r{(callback|expired-callback)}
           "\"#{k}\": #{v}"
         else
           "\"#{k}\": \"#{v}\""
@@ -65,5 +127,5 @@ module Recaptcha
       end.join(", ")
       result << "}"
     end
-  end # ClientHelper
-end # Recaptcha
+  end
+end