turnstile-ruby 0.1.0 → 0.2.0

data/lib/turnstile/helpers.rb

@@ -1,139 +1,146 @@
 # frozen_string_literal: true
 
+require "erb"
+
 module Turnstile
   module Helpers
     DEFAULT_ERRORS = {
-      turnstile_unreachable: 'Oops, we failed to validate your Turnstile response. Please try again.',
-      verification_failed: 'Turnstile verification failed, please try again.'
+      turnstile_unreachable: "Oops, we failed to validate your Turnstile response. Please try again.",
+      verification_failed: "Turnstile verification failed, please try again."
     }.freeze
 
+    # Options rendered as data-* attributes on the widget, see
+    # https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/
+    WIDGET_OPTIONS = %i[
+      action cdata callback error_callback expired_callback timeout_callback before_interactive_callback
+      after_interactive_callback unsupported_callback theme language tabindex response_field response_field_name
+      size retry retry_interval refresh_expired refresh_timeout appearance execution feedback_enabled
+      offlabel_show_privacy offlabel_show_help
+    ].freeze
+
+    # The only widget options where +false+ is a value, everywhere else it means "leave it out".
+    BOOLEAN_OPTIONS = %i[response_field feedback_enabled offlabel_show_privacy offlabel_show_help].freeze
+
+    # Options that control the helper itself and never end up as HTML attributes.
+    SETTINGS = %i[
+      env site_key sitekey hl onload render script_async script_defer script external_script inline_script
+      nonce turbo ui text
+    ].freeze
+
+    HELPER_SCRIPT = File.read(File.expand_path("helper.js", __dir__)).gsub(%r{^\s*//.*\n}, "").gsub(/^\s+/, "").freeze
+
     def self.to_error_message(key)
-      default = DEFAULT_ERRORS.fetch(key) { raise ArgumentError "Unknown Turnstile captcha error - #{key}" }
+      default = DEFAULT_ERRORS.fetch(key) { raise ArgumentError, "Unknown Turnstile captcha error - #{key}" }
       to_message("turnstile.errors.#{key}", default)
     end
 
-    if defined?(I18n)
-      def self.to_message(key, default)
-        I18n.translate(key, default: default)
-      end
-    else
-      def self.to_message(_key, default)
-        default
-      end
+    def self.to_message(key, default)
+      defined?(I18n) ? I18n.translate(key, default: default) : default
     end
 
-    def self.turnstile_tags(options)
+    def self.turnstile_tags(options = {})
       if options.key?(:ssl)
         raise(TurnstileError, "SSL is now always true. Please remove 'ssl' from your calls to turnstile_tags.")
       end
 
-      html, tag_attributes = components(options.dup)
-      html << %(<div #{tag_attributes}></div>\n)
+      options = options.dup
+      settings = extract(options, SETTINGS)
+      attributes = data_attributes(options, settings)
+      attributes["class"] = ["cf-turnstile", options.delete(:class)].compact.join(" ")
 
-      html.respond_to?(:html_safe) ? html.html_safe : html
+      html = script_tags(settings, helper: turbo?(settings) && settings[:render].to_s != "explicit")
+      html << %(<div #{tag_attributes(attributes.merge(options))}></div>\n)
+      safe(html)
+    end
+
+    # Renders a submit button that runs the challenge when the form is submitted and only then submits it.
+    def self.invisible_turnstile_tags(custom = {})
+      options = { ui: :button, appearance: "interaction-only" }.merge(custom)
+      settings = extract(options, SETTINGS)
+      tabindex = options.delete(:tabindex)
+      widget = data_attributes(options, settings).merge("data-turnstile-invisible" => true)
+      options[:tabindex] = tabindex if tabindex
+
+      html = script_tags(settings, helper: true)
+      html << %(<div #{tag_attributes(widget)}></div>\n)
+      html << submit_tag(settings, options)
+      safe(html)
     end
 
-    def self.invisible_turnstile_tags(custom)
-      options = { callback: 'javascriptCallback', ui: :button }.merge(custom)
-      text = options.delete(:text)
-      html, tag_attributes = components(options.dup)
-      html << default_callback(options) if default_callback_required?(options)
+    private_class_method def self.submit_tag(settings, attributes)
+      text = escape(settings[:text])
 
-      case options[:ui]
+      case settings[:ui]
       when :button
-        html << %(<button type="submit" #{tag_attributes}>#{text}</button>\n)
+        %(<button #{tag_attributes({ "type" => "submit" }.merge(attributes))}>#{text}</button>\n)
       when :input
-        html << %(<input type="submit" #{tag_attributes} value="#{text}"/>\n)
+        %(<input #{tag_attributes({ "type" => "submit" }.merge(attributes))} value="#{text}"/>\n)
       else
-        raise(TurnstileError, "Turnstile ui `#{options[:ui]}` is not valid.")
+        raise(TurnstileError, "Turnstile ui `#{settings[:ui]}` is not valid.")
       end
-      html.respond_to?(:html_safe) ? html.html_safe : html
     end
 
-    private_class_method def self.components(options)
-      html = +''
-      attributes = {}
+    private_class_method def self.data_attributes(options, settings)
+      options[:cdata] = options.delete(:cData) if options.key?(:cData)
+      options[:language] ||= settings[:hl] if settings[:hl]
+      values = extract(options, WIDGET_OPTIONS)
+      return {} if Turnstile.skip_env?(settings[:env])
 
-      options = options.dup
-      env = options.delete(:env)
-      class_attribute = options.delete(:class)
-      site_key = options.delete(:site_key)
-      hl = options.delete(:hl)
-      onload = options.delete(:onload)
-      render = options.delete(:render)
-      script_async = options.delete(:script_async)
-      script_defer = options.delete(:script_defer)
-      skip_script = (options.delete(:script) == false) || (options.delete(:external_script) == false)
-      ui = options.delete(:ui)
-
-      data_attribute_keys = %i[sitekey action cData callback expired_callback
-                               timeout_callback error_callback theme language response_field
-                               response_field_name size retry retry_interval refresh_expired]
-      # data_attribute_keys << :tabindex unless ui == :button # TODO:: Remove me
-      data_attributes = {}
-      data_attribute_keys.each do |data_attribute|
-        value = options.delete(data_attribute)
-        data_attributes["data-#{data_attribute.to_s.tr('_', '-')}"] = value if value
-      end
+      site_key = settings[:site_key] || settings[:sitekey] || Turnstile.configuration.site_key!
+      values.each_with_object("data-sitekey" => site_key) do |(key, value), attributes|
+        next if value.nil? || (value == false && !BOOLEAN_OPTIONS.include?(key))
 
-      unless Turnstile.skip_env?(env)
-        site_key ||= Turnstile.configuration.site_key!
-        script_url = Turnstile.configuration.api_server_url
-        query_params = hash_to_query(
-          hl: hl,
-          onload: onload,
-          render: render
-        )
-        script_url += "?#{query_params}" unless query_params.empty?
-        async_attr = "async" if script_async != false
-        defer_attr = "defer" if script_defer != false
-        html << %(<script src="#{script_url}" #{async_attr} #{defer_attr}></script>\n) unless skip_script
-        attributes["data-sitekey"] = site_key
-        attributes.merge! data_attributes
+        attributes["data-#{key.to_s.tr("_", "-")}"] = value.to_s
       end
+    end
 
-      # The remaining options will be added as attributes on the tag.
-      attributes["class"] = "cf-turnstile #{class_attribute}"
-      tag_attributes = attributes.merge(options).map { |k, v| %(#{k}="#{v}") }.join(" ")
+    private_class_method def self.script_tags(settings, helper:)
+      html = +""
+      return html if Turnstile.skip_env?(settings[:env]) || settings[:script] == false
 
-      [html, tag_attributes]
+      html << api_script_tag(settings) unless settings[:external_script] == false
+      html << helper_script_tag(settings) if helper && settings[:inline_script] != false
+      html
     end
 
-    private_class_method def self.hash_to_query(hash)
-      hash.delete_if { |_, val| val.nil? || val.empty? }.to_a.map { |pair| pair.join('=') }.join('&')
+    private_class_method def self.api_script_tag(settings)
+      query = { onload: settings[:onload], render: settings[:render] }.reject { |_, value| value.to_s.empty? }
+      url = Turnstile.configuration.api_server_url
+      url += "?#{URI.encode_www_form(query)}" unless query.empty?
+
+      attributes = { "src" => url }
+      attributes["async"] = true unless settings[:script_async] == false
+      attributes["defer"] = true unless settings[:script_defer] == false
+      attributes["nonce"] = settings[:nonce] || nil
+
+      %(<script #{tag_attributes(attributes)}></script>\n)
     end
 
-    private_class_method def self.default_callback_required?(options)
-      options[:callback] == 'javascriptCallback' &&
-      !Turnstile.skip_env?(options[:env]) &&
-      options[:script] != false &&
-      options[:inline_script] != false
+    private_class_method def self.helper_script_tag(settings)
+      nonce = settings[:nonce] ? %( nonce="#{escape(settings[:nonce])}") : ""
+      %(<script#{nonce}>#{HELPER_SCRIPT}</script>\n)
     end
 
-    private_class_method def self.default_callback(options = {})
-      selector_attr = options[:id] ? "##{options[:id]}" : ".cf-turnstile"
-
-      <<-HTML
-        <script>
-          var javascriptCallback = function () {
-            var closestForm = function (ele) {
-              var curEle = ele.parentNode;
-              while (curEle.nodeName !== 'FORM' && curEle.nodeName !== 'BODY'){
-                curEle = curEle.parentNode;
-              }
-              return curEle.nodeName === 'FORM' ? curEle : null
-            };
-
-            var el = document.querySelector("#{selector_attr}")
-            if (!!el) {
-              var form = closestForm(el);
-              if (form) {
-                form.submit();
-              }
-            }
-          };
-        </script>
-      HTML
+    private_class_method def self.turbo?(settings)
+      settings.fetch(:turbo) { Turnstile.configuration.turbo } != false
+    end
+
+    private_class_method def self.extract(options, keys)
+      keys.each_with_object({}) { |key, found| found[key] = options.delete(key) if options.key?(key) }
+    end
+
+    private_class_method def self.tag_attributes(attributes)
+      attributes.reject { |_, value| value.nil? }.map do |name, value|
+        value == true ? escape(name) : %(#{escape(name)}="#{escape(value)}")
+      end.join(" ")
+    end
+
+    private_class_method def self.escape(value)
+      ERB::Util.html_escape(value.to_s)
+    end
+
+    private_class_method def self.safe(html)
+      html.respond_to?(:html_safe) ? html.html_safe : html
     end
   end
 end

data/lib/turnstile/rails.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
-# deprecated, but let's not blow everyone up
-require 'turnstile'
+# deprecated, but let"s not blow everyone up
+require "turnstile"

data/lib/turnstile/railtie.rb

@@ -10,7 +10,7 @@ module Turnstile
       include Turnstile::Adapters::ControllerMethods
     end
 
-    initializer 'turnstile' do |app|
+    initializer "turnstile" do |app|
       Turnstile::Railtie.instance_eval do
         pattern = pattern_from app.config.i18n.available_locales
 
@@ -22,13 +22,13 @@ module Turnstile
       protected
 
       def add(pattern)
-        files = Dir[File.join(File.dirname(__FILE__), '../..', pattern)]
+        files = Dir[File.join(File.dirname(__FILE__), "../..", pattern)]
         I18n.load_path.concat(files)
       end
 
       def pattern_from(args)
         array = Array(args || [])
-        array.blank? ? '*' : "{#{array.join ','}}"
+        array.blank? ? "*" : "{#{array.join ","}}"
       end
     end
   end

data/lib/turnstile/response.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Turnstile
+  # The outcome of a token verification, wrapping Cloudflare's siteverify reply.
+  #
+  #   result = Turnstile.verify(token)
+  #   result.success?     # => false
+  #   result.error_codes  # => ["invalid-input-response"]
+  #   result.hostname     # => "example.com"
+  #
+  class Response
+    def initialize(reply, extra_errors: [])
+      @reply = reply
+      @extra_errors = extra_errors
+    end
+
+    def success?
+      @reply["success"].to_s == "true" && @extra_errors.empty?
+    end
+
+    # Cloudflare's error codes, plus "hostname-mismatch" / "action-mismatch" when the
+    # reply does not match the hostname or action you asked to validate.
+    def error_codes
+      Array(@reply["error-codes"]) + @extra_errors
+    end
+
+    def hostname
+      @reply["hostname"]
+    end
+
+    def action
+      @reply["action"]
+    end
+
+    def cdata
+      @reply["cdata"]
+    end
+
+    # ISO 8601 timestamp of the challenge, as sent by Cloudflare.
+    def challenge_ts
+      @reply["challenge_ts"]
+    end
+
+    def metadata
+      @reply["metadata"] || {}
+    end
+
+    # The raw siteverify reply.
+    def to_h
+      @reply
+    end
+  end
+end

data/lib/turnstile/testing.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "turnstile"
+
+module Turnstile
+  # Helpers for your own test suite. Not loaded by default:
+  #
+  #   require "turnstile/testing"
+  #
+  #   Turnstile::Testing.failure!                         # every verification fails
+  #   Turnstile::Testing.success!                         # every verification passes
+  #   Turnstile::Testing.reset!                           # back to normal
+  #   Turnstile::Testing.with_failure { post signup_path } # block form, resets afterwards
+  #
+  # While a stub is active no request is sent to Cloudflare, and `verify_turnstile`
+  # uses the stub even in environments listed in `skip_verify_env`.
+  module Testing
+    module_function
+
+    def success!(reply = {})
+      Turnstile.stubbed_response = Response.new({ "success" => true, "error-codes" => [] }.merge(reply))
+    end
+
+    def failure!(*error_codes)
+      error_codes = ["invalid-input-response"] if error_codes.empty?
+      Turnstile.stubbed_response = Response.new({ "success" => false, "error-codes" => error_codes.flatten })
+    end
+
+    def reset!
+      Turnstile.stubbed_response = nil
+    end
+
+    def with_success(reply = {}, &block)
+      with_stub(block) { success!(reply) }
+    end
+
+    def with_failure(*error_codes, &block)
+      with_stub(block) { failure!(*error_codes) }
+    end
+
+    def with_stub(block)
+      previous = Turnstile.stubbed_response
+      yield
+      block.call
+    ensure
+      Turnstile.stubbed_response = previous
+    end
+    private_class_method :with_stub
+  end
+end

data/lib/turnstile/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Turnstile
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/turnstile-ruby.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Lets Bundler auto-require the gem from a plain `gem "turnstile-ruby"` line.
+require "turnstile"

data/lib/turnstile.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'net/http'
-require 'uri'
+require "json"
+require "net/http"
+require "uri"
 
-require 'turnstile/configuration'
-require 'turnstile/helpers'
-require 'turnstile/adapters/controller_methods'
-require 'turnstile/adapters/view_methods'
+require "turnstile/version"
+require "turnstile/configuration"
+require "turnstile/response"
+require "turnstile/helpers"
+require "turnstile/adapters/controller_methods"
+require "turnstile/adapters/view_methods"
 
-if defined?(Rails)
-  require 'turnstile/railtie'
-end
+require "turnstile/railtie" if defined?(Rails::Railtie)
 
 module Turnstile
   DEFAULT_TIMEOUT = 3
@@ -22,6 +22,16 @@ module Turnstile
   class VerifyError < TurnstileError
   end
 
+  # Raised when Cloudflare answers with something that is not a siteverify reply (a 5xx page, an empty body, ...).
+  class UnreachableError < TurnstileError
+  end
+
+  class << self
+    # A Turnstile::Response returned by every verification instead of calling Cloudflare.
+    # Set through Turnstile::Testing (require "turnstile/testing").
+    attr_accessor :stubbed_response
+  end
+
   # Gives access to the current Configuration.
   def self.configuration
     @configuration ||= Configuration.new
@@ -29,10 +39,6 @@ module Turnstile
 
   # Allows easy setting of multiple configuration options. See Configuration
   # for all available options.
-  #--
-  # The temp assignment is only used to get a nicer rdoc. Feel free to remove
-  # this hack.
-  #++
   def self.configure
     config = configuration
     yield(config)
@@ -51,28 +57,50 @@ module Turnstile
     original_config.each { |key, value| configuration.send("#{key}=", value) }
   end
 
+  def self.site_key
+    configuration.site_key
+  end
+
+  def self.secret_key
+    configuration.secret_key
+  end
+
   def self.skip_env?(env)
     configuration.skip_verify_env.include?(env || configuration.default_env)
   end
 
   def self.invalid_response?(resp)
-    resp.empty? || resp.length > configuration.response_limit
+    !resp.is_a?(String) || resp.empty? || resp.length > configuration.response_limit
   end
 
-  def self.verify_via_api_call(response, options)
-    secret_key = options.fetch(:secret_key) { configuration.secret_key! }
-    verify_hash = { 'secret' => secret_key, 'response' => response }
-    verify_hash['remoteip'] = options[:remote_ip] if options.key?(:remote_ip)
+  # Verifies a token with Cloudflare and returns a Turnstile::Response.
+  #
+  #   result = Turnstile.verify(params["cf-turnstile-response"], remote_ip: request.remote_ip)
+  #   result.success?    # => true / false
+  #   result.error_codes # => ["timeout-or-duplicate"]
+  #
+  # Options: +secret_key+, +remote_ip+, +idempotency_key+, +timeout+, +hostname+ and +action+.
+  # A missing or oversized token fails without a network call. Network timeouts raise Timeout::Error and
+  # unusable replies raise Turnstile::UnreachableError.
+  def self.verify(token, options = {})
+    return stubbed_response if stubbed_response
+    return failure(missing_token_code(token)) if invalid_response?(token)
+
+    reply = api_verification(verify_params(token, options), timeout: options[:timeout])
+    errors = []
+    errors << "hostname-mismatch" unless hostname_valid?(reply["hostname"], options[:hostname])
+    errors << "action-mismatch" unless action_valid?(reply["action"], options[:action])
+    Response.new(reply, extra_errors: errors)
+  end
 
-    reply = api_verification(verify_hash, timeout: options[:timeout])
-    success = reply['success'].to_s == 'true' &&
-      hostname_valid?(reply['hostname'], options[:hostname]) &&
-      action_valid?(reply['action'], options[:action])
+  # Kept for backwards compatibility, prefer Turnstile.verify.
+  def self.verify_via_api_call(response, options)
+    result = verify(response, options)
 
     if options[:with_reply] == true
-      [success, reply]
+      [result.success?, result.to_h]
     else
-      success
+      result.success?
     end
   end
 
@@ -89,12 +117,12 @@ module Turnstile
   def self.action_valid?(action, expected_action)
     case expected_action
     when nil, FalseClass then true
-    else action == expected_action
+    else action == expected_action.to_s
     end
   end
 
   def self.http_client_for(uri:, timeout: nil)
-    timeout ||= DEFAULT_TIMEOUT
+    timeout ||= configuration.timeout || DEFAULT_TIMEOUT
     http = if configuration.proxy
              proxy_server = URI.parse(configuration.proxy)
              Net::HTTP::Proxy(proxy_server.host, proxy_server.port, proxy_server.user, proxy_server.password)
@@ -110,9 +138,32 @@ module Turnstile
 
   def self.api_verification(verify_hash, timeout: nil)
     uri = URI.parse(configuration.verify_url)
-    http_instance = http_client_for(uri: uri, timeout: nil)
+    http_instance = http_client_for(uri: uri, timeout: timeout)
     request = Net::HTTP::Post.new(uri.request_uri)
     request.set_form_data verify_hash
-    JSON.parse(http_instance.request(request).body)
+    reply = JSON.parse(http_instance.request(request).body.to_s)
+    raise UnreachableError, "Unexpected reply from Turnstile: #{reply.inspect}" unless reply.is_a?(Hash)
+
+    reply
+  rescue JSON::ParserError
+    raise UnreachableError, "Turnstile did not return a JSON reply."
+  end
+
+  def self.verify_params(token, options)
+    params = { "secret" => options.fetch(:secret_key) { configuration.secret_key! }, "response" => token }
+    params["remoteip"] = options[:remote_ip].to_s if options[:remote_ip]
+    params["idempotency_key"] = options[:idempotency_key].to_s if options[:idempotency_key]
+    params
+  end
+  private_class_method :verify_params
+
+  def self.failure(error_code)
+    Response.new({ "success" => false, "error-codes" => [error_code] })
+  end
+  private_class_method :failure
+
+  def self.missing_token_code(token)
+    token.nil? || token == "" ? "missing-input-response" : "invalid-input-response"
   end
+  private_class_method :missing_token_code
 end

data/sig/turnstile.rbs

@@ -0,0 +1,68 @@
+module Turnstile
+  VERSION: String
+  DEFAULT_TIMEOUT: Integer
+
+  class TurnstileError < StandardError
+  end
+
+  class VerifyError < TurnstileError
+  end
+
+  class UnreachableError < TurnstileError
+  end
+
+  attr_accessor self.stubbed_response: Response?
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.with_configuration: (Hash[Symbol, untyped] config) ?{ () -> void } -> void
+  def self.site_key: () -> String?
+  def self.secret_key: () -> String?
+  def self.skip_env?: (String? env) -> bool
+  def self.verify: (untyped token, ?Hash[Symbol, untyped] options) -> Response
+  def self.verify_via_api_call: (untyped response, Hash[Symbol, untyped] options) -> (bool | [bool, Hash[String, untyped]])
+
+  class Configuration
+    attr_accessor default_env: String?
+    attr_accessor skip_verify_env: Array[String]
+    attr_accessor proxy: String?
+    attr_accessor secret_key: String?
+    attr_accessor site_key: String?
+    attr_accessor handle_timeouts_gracefully: bool
+    attr_accessor hostname: (String | ^(String?) -> boolish)?
+    attr_accessor response_limit: Integer
+    attr_accessor timeout: Numeric
+    attr_accessor turbo: bool
+    attr_accessor api_server_url: String
+    attr_accessor verify_url: String
+
+    def secret_key!: () -> String
+    def site_key!: () -> String
+  end
+
+  class Response
+    def initialize: (Hash[String, untyped] reply, ?extra_errors: Array[String]) -> void
+    def success?: () -> bool
+    def error_codes: () -> Array[String]
+    def hostname: () -> String?
+    def action: () -> String?
+    def cdata: () -> String?
+    def challenge_ts: () -> String?
+    def metadata: () -> Hash[String, untyped]
+    def to_h: () -> Hash[String, untyped]
+  end
+
+  module Helpers
+    def self.turnstile_tags: (?Hash[Symbol, untyped] options) -> String
+    def self.invisible_turnstile_tags: (?Hash[Symbol, untyped] options) -> String
+    def self.to_error_message: (Symbol key) -> String
+  end
+
+  module Testing
+    def self.success!: (?Hash[String, untyped] reply) -> Response
+    def self.failure!: (*String error_codes) -> Response
+    def self.reset!: () -> nil
+    def self.with_success: (?Hash[String, untyped] reply) { () -> untyped } -> untyped
+    def self.with_failure: (*String error_codes) { () -> untyped } -> untyped
+  end
+end