turnstile-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c562e5825290bbab8c92309f410fdeedbf3f1a4a87abd3243130886f8ffc07e
-  data.tar.gz: 2dd53d7bc2dde10c1493b8a5ab7be75ec96e4d107055052e3c511c23ef946841
+  metadata.gz: 69f9f7ac9e416004547bd10b0a8c9b5bef6e40002496e29cd991c77322e6d6a7
+  data.tar.gz: 88c81cfcd7d560a4eab7cf66fe485516f1ce75a2f1b18149225adc451dd2bff2
 SHA512:
-  metadata.gz: ed59df2922741050d4632c697cf576a48379014ea62ca4f5bab12f80e71757d5b97dceb556447bd3c984f0fb80c4ec3f8f6aac451b307d90d0fbadd8354b9e1c
-  data.tar.gz: c546b14454b5cb81788d15e716e1cb4ab1d13687dbbf07bc6730c7a61e8db156cf5e7ae1b744c30881b51f8e09cfe718bb23e4331e808292a1284426241e1006
+  metadata.gz: eed815205816d06577a046f9ce71daca0b84ebc1ef32bf1eb0a552afdf3678e3aa3463390c9999f361d06b33de0853e84198ac2d98b3e76e681f1d78f4ea8cb3
+  data.tar.gz: 40e04813942a68657a473082f4c21ca017b404a5ed6f5060f8774c72edfe72c0d1ab7a36e06eee24da9098150de27e97fb4e81f2ba106f17cea09baf551ca7f0

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-06
+
+### Added
+
+- `Turnstile.verify(token, ...)` returns a `Turnstile::Response` (`success?`, `error_codes`, `hostname`, `action`,
+  `cdata`, `challenge_ts`, `metadata`, `to_h`) for use outside of controllers.
+- Turbo (Hotwire) support: widgets render again after Turbo Drive visits, frame renders and cache restores. On by
+  default, turn it off with `turbo: false` or `config.turbo = false`.
+- CSP nonces: `nonce:` is added to every script tag, and the Rails helpers pick up `content_security_policy_nonce`
+  automatically.
+- Widget options `appearance`, `execution`, `tabindex`, `refresh_timeout`, `feedback_enabled`,
+  `before_interactive_callback`, `after_interactive_callback`, `unsupported_callback`, `offlabel_show_privacy` and
+  `offlabel_show_help`.
+- `config.timeout`, `Turnstile.site_key`, `Turnstile.secret_key` and the `idempotency_key:` verify option.
+- `Turnstile::Testing` (`require "turnstile/testing"`) to stub verification results in your own tests.
+- `lib/turnstile-ruby.rb`, so a plain `gem "turnstile-ruby"` is auto-required by Bundler.
+- A spec suite, run on Ruby 2.7 to 4.0.
+
+### Changed
+
+- `invisible_turnstile_tags` is reimplemented. It used to render the widget inside the submit button and submit the
+  form as soon as the page loaded. It now renders a hidden widget next to the button and runs the challenge when the
+  form is submitted. The button no longer gets the `cf-turnstile` class.
+- The `hl:` option sets `data-language` instead of an unused `hl` query parameter on the script.
+- `verify_turnstile!` raises `Turnstile::VerifyError` with a readable message instead of the reply hash.
+- `turnstile_tags` emits a small inline script for Turbo support (see above).
+- Ruby 2.7 or newer is required.
+
+### Fixed
+
+- A missing `cf-turnstile-response` parameter raised `TurnstileError` (a 500) instead of failing verification.
+- `verify_turnstile(model: record)` called `record.new` and raised when verification failed. A `model:` without
+  `errors` (for example a class) falls back to the flash.
+- The `timeout:` option was ignored.
+- A non-JSON reply from Cloudflare raised instead of being handled like a timeout.
+- Attribute values were not HTML-escaped.
+- Options such as `inline_script` and `external_script` leaked into the widget's HTML attributes.
+- `response_field: false` was dropped instead of rendered. Other options still leave out `false` and `nil`.
+- `Turnstile::Helpers.to_error_message` raised `NoMethodError` for unknown keys.
+- `LICENSE.txt` was missing from the packaged gem.
+
 ## [0.1.0] - 2023-02-23
 
 - Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Kishan Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,21 +1,26 @@
 # Turnstile Ruby
 
 [![Gem Version](https://badge.fury.io/rb/turnstile-ruby.svg)](https://badge.fury.io/rb/turnstile-ruby)
+[![CI](https://github.com/urkkv/turnstile-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/urkkv/turnstile-ruby/actions/workflows/main.yml)
 
-A simple Ruby client for verifying [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) tokens.
+[Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) for Ruby: view helpers for the widget, controller
+helpers for verification, and a small client for the siteverify API.
 Turnstile is a CAPTCHA alternative from Cloudflare, similar to Google reCAPTCHA, but lightweight and privacy-friendly.
 
-This gem makes it easy to integrate Turnstile into Ruby and Rails applications.
+It works in **Rails, Sinatra, any Rack app and plain Ruby**, and has no runtime dependencies.
 
 ---
 
 ## ✨ Features
 
-- Verify Turnstile tokens with Cloudflare’s API
-- Lightweight, no heavy dependencies
-- Works with plain Ruby and Ruby on Rails
-- Provides meaningful error codes and success flags
-- Simple configuration via environment variables or initializer
+- `turnstile_tags` and `verify_turnstile` helpers, added to Rails automatically
+- `Turnstile.verify` for jobs, APIs, Sinatra and plain Ruby, returning error codes and the reply details
+- Works with Turbo (Hotwire): widgets keep rendering across Turbo visits
+- CSP friendly: script tags carry your nonce, picked up from Rails automatically
+- Invisible flow that runs the challenge when the form is submitted
+- Translated error messages (en, fr, ja, nl), written to the flash or your model's errors
+- Test helpers to stub passing and failing verifications
+- No runtime dependencies, Ruby 2.7+
 
 ---
 
@@ -33,81 +38,166 @@ And install:
 bundle install
 ```
 
-Or install directly with:
-
-```bash
-gem install turnstile-ruby
-```
-
 ---
 
 ## ⚙️ Configuration
 
-Set your **Cloudflare Turnstile Site Key** and **Secret Key** in environment variables:
+Get a site key and a secret key from the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
+and set them in the environment:
 
 ```bash
 export TURNSTILE_SITE_KEY="your_site_key"
 export TURNSTILE_SECRET_KEY="your_secret_key"
 ```
 
-For Rails, you can create an initializer (`config/initializers/turnstile.rb`):
+Or configure them in code, for Rails in `config/initializers/turnstile.rb`:
 
 ```ruby
 Turnstile.configure do |config|
   config.site_key   = ENV["TURNSTILE_SITE_KEY"]
   config.secret_key = ENV["TURNSTILE_SECRET_KEY"]
-  config.timeout    = 5 # optional, in seconds
+  config.timeout    = 5 # optional, seconds to wait for Cloudflare (default 3)
 end
 ```
 
+| Option | Default | |
+|---|---|---|
+| `site_key`, `secret_key` | `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY` | Your keys |
+| `timeout` | `3` | Seconds to wait for Cloudflare when verifying |
+| `skip_verify_env` | `["test", "cucumber", "rspec"]` | Environments where verification always passes |
+| `handle_timeouts_gracefully` | `true` | Fail verification with a message when Cloudflare is unreachable, instead of raising |
+| `hostname` | `nil` | A string or callable the reply's hostname has to match |
+| `turbo` | `true` | Render widgets again after Turbo visits |
+| `proxy` | `nil` | HTTP proxy URL for the verification request |
+| `response_limit` | `2048` | Maximum accepted token length |
+
+For local development Cloudflare has [dummy keys](https://developers.cloudflare.com/turnstile/troubleshooting/testing/)
+that work on any host: site key `1x00000000000000000000AA` with secret key `1x0000000000000000000000000000000AA`
+always passes.
+
 ---
 
 ## 🛠 Usage
 
-### Rails Views
+### Rails
 
-Embed the Turnstile widget:
+Add the widget to a form:
 
 ```erb
-<form action="/signup" method="POST">
-  <!-- Your form fields -->
+<%= form_with model: @user do |form| %>
+  <%= form.text_field :email %>
+  <%= turnstile_tags %>
+  <%= form.submit %>
+<% end %>
+```
+
+And verify it in the controller:
+
+```ruby
+def create
+  @user = User.new(user_params)
+
+  if verify_turnstile(model: @user) && @user.save
+    redirect_to @user
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+`verify_turnstile` returns `true` or `false`. On failure it adds an error to the model, or sets
+`flash[:turnstile_error]` when no model is given. A missing token fails verification, it does not raise.
+
+| Option | |
+|---|---|
+| `model:` | Record that gets the error message |
+| `attribute:` | Attribute for the error, `:base` by default |
+| `message:` | Custom error message |
+| `action:` / `hostname:` | Fail unless the reply matches |
+| `timeout:` | Seconds to wait, overriding the configuration |
+| `secret_key:` | Secret key for this call |
+| `response:` | Token to verify, `params["cf-turnstile-response"]` by default |
+| `skip_remote_ip: true` | Do not send the visitor's IP to Cloudflare |
+
+`verify_turnstile!` raises `Turnstile::VerifyError` instead of returning `false`, and `turnstile_reply` gives you
+Cloudflare's raw reply afterwards.
+
+### Widget options
+
+`turnstile_tags` accepts the
+[widget configuration](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/)
+in snake_case, and passes anything else through as HTML attributes:
+
+```erb
+<%= turnstile_tags theme: "dark", size: "flexible", action: "signup", appearance: "interaction-only", class: "mt-4" %>
+```
 
-  <div class="cf-turnstile"
-       data-sitekey="<%= Turnstile.site_key %>">
-  </div>
+`action`, `cdata`, `theme`, `language`, `size`, `appearance`, `execution`, `tabindex`, `retry`, `retry_interval`,
+`refresh_expired`, `refresh_timeout`, `response_field`, `response_field_name`, `feedback_enabled`,
+`offlabel_show_privacy`, `offlabel_show_help`, `callback`, `error_callback`, `expired_callback`, `timeout_callback`,
+`before_interactive_callback`, `after_interactive_callback` and `unsupported_callback` are supported.
 
-  <button type="submit">Submit</button>
-</form>
+| Helper option | |
+|---|---|
+| `site_key:` | Site key for this widget |
+| `nonce:` | CSP nonce for the script tags (automatic in Rails) |
+| `turbo: false` | Leave out the Turbo support script |
+| `script: false` | Render no script tags, for when you load `api.js` yourself |
+| `onload:`, `render:` | Query parameters for `api.js`, for [explicit rendering](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#explicit-rendering) |
+| `script_async: false`, `script_defer: false` | Drop `async` / `defer` from the script tag |
 
-<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+### Turbo
+
+Nothing to set up. `api.js` only scans the page once, so with Turbo Drive a widget would stay empty after the first
+visit. `turnstile_tags` therefore includes a small inline script that renders widgets after Turbo visits, frame
+renders and cache restores. If your Content Security Policy blocks inline scripts and you pass no nonce, the widget
+still works on full page loads.
+
+### Content Security Policy
+
+Allow `https://challenges.cloudflare.com` in `script-src` and `frame-src`. In Rails the helpers add your
+`content_security_policy_nonce` to their script tags; elsewhere pass `nonce:` yourself.
+
+### Invisible flow
+
+```erb
+<%= form_with url: signup_path do |form| %>
+  <%= form.text_field :email %>
+  <%= invisible_turnstile_tags text: "Sign up", class: "btn" %>
+<% end %>
 ```
 
-### Rails Controller
+This renders a submit button and a widget that stays hidden unless Cloudflare needs the visitor to interact. The
+challenge runs when the form is submitted, and the form is sent once the token arrives. Pass `ui: :input` for an
+`<input type="submit">`, or `callback: "myFunction"` to receive the token yourself instead of submitting the form.
 
-Verify the token on form submission:
+### Sinatra
 
 ```ruby
-def create
-  token = params["cf-turnstile-response"]
+require "sinatra"
+require "turnstile"
 
-  result = Turnstile.verify(token, remote_ip: request.remote_ip)
+helpers Turnstile::Adapters::ViewMethods, Turnstile::Adapters::ControllerMethods
 
-  if result.success?
-    # proceed with signup
-  else
-    flash[:error] = "Turnstile verification failed: #{result.error_codes.join(", ")}"
-    render :new
-  end
+get "/" do
+  %(<form action="/verify" method="post">#{turnstile_tags}<button>Submit</button></form>)
+end
+
+post "/verify" do
+  verify_turnstile ? "Verified" : halt(422, "Verification failed")
 end
 ```
 
-### Plain Ruby Example
+There is a runnable version in [`demo/sinatra`](demo/sinatra).
+
+### Plain Ruby
+
+`Turnstile.verify` works anywhere: API endpoints, background jobs, other frameworks.
 
 ```ruby
 require "turnstile"
 
-token = "client-submitted-token"
-result = Turnstile.verify(token)
+result = Turnstile.verify(token, remote_ip: request.ip)
 
 if result.success?
   puts "Verification passed!"
@@ -116,16 +206,38 @@ else
 end
 ```
 
+It returns a `Turnstile::Response`:
+
+- `success?` → `true` or `false`
+- `error_codes` → Cloudflare's [error codes](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/#error-codes),
+  plus `hostname-mismatch` / `action-mismatch` when you asked to validate those
+- `hostname`, `action`, `cdata`, `challenge_ts`, `metadata` → details of the challenge
+- `to_h` → the raw reply
+
+Options: `remote_ip:`, `secret_key:`, `timeout:`, `hostname:`, `action:` and `idempotency_key:`.
+
+A missing token returns a failed response without calling Cloudflare. Unlike `verify_turnstile`, this method does
+not skip the test environment, and it raises `Timeout::Error` or `Turnstile::UnreachableError` when Cloudflare
+cannot be reached.
+
 ---
 
-## ✅ Response Object
+## 🧪 Testing your app
 
-`Turnstile.verify` returns a `Turnstile::Response` object with:
+In the `test` environment `verify_turnstile` always passes and `turnstile_tags` renders an empty container, so your
+tests never call Cloudflare. To test what happens when verification fails:
+
+```ruby
+require "turnstile/testing"
+
+Turnstile::Testing.with_failure do
+  post signups_path, params: { user: { email: "a@example.com" } }
+  expect(response).to have_http_status(:unprocessable_entity)
+end
+```
 
-- `success?` → `true` or `false`  
-- `error_codes` → array of error codes  
-- `hostname` → hostname (if provided)  
-- `challenge_ts` → challenge timestamp (if provided)  
+`Turnstile::Testing.success!`, `failure!("timeout-or-duplicate")` and `reset!` do the same without a block; call
+`reset!` after each test when you use them.
 
 ---
 
@@ -139,28 +251,29 @@ cd turnstile-ruby
 bundle install
 ```
 
-Run tests:
+Run the specs and RuboCop:
 
 ```bash
-bundle exec rspec
+bundle exec rake
 ```
 
 ---
 
 ## 📜 License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](LICENSE.txt).
 
 ---
 
 ## 🙌 Contributing
 
-Bug reports and pull requests are welcome at  
+Bug reports and pull requests are welcome at
 [https://github.com/urkkv/turnstile-ruby](https://github.com/urkkv/turnstile-ruby).
 
 ---
 
 ## 🔗 Resources
 
-- [Cloudflare Turnstile Documentation](https://developers.cloudflare.com/turnstile/)  
-- [RubyGems.org – turnstile-ruby](https://rubygems.org/gems/turnstile-ruby)  
+- [Cloudflare Turnstile Documentation](https://developers.cloudflare.com/turnstile/)
+- [RubyGems.org – turnstile-ruby](https://rubygems.org/gems/turnstile-ruby)
+- [Changelog](CHANGELOG.md)

data/lib/turnstile/adapters/controller_methods.rb

@@ -8,28 +8,17 @@ module Turnstile
       # Your private API can be specified in the +options+ hash or preferably
       # using the Configuration.
       def verify_turnstile(options = {})
-        options = {model: options} unless options.is_a? Hash
-        return true if Turnstile.skip_env?(options[:env])
+        options = { model: options } unless options.is_a? Hash
+        return true if Turnstile.stubbed_response.nil? && Turnstile.skip_env?(options[:env])
 
         model = options[:model]
         attribute = options.fetch(:attribute, :base)
-        turnstile_response = options[:response] || params['cf-turnstile-response']
 
         begin
-          verified = if Turnstile.invalid_response?(turnstile_response)
-            false
-          else
-            unless options[:skip_remote_ip]
-              remoteip = (request.respond_to?(:remote_ip) && request.remote_ip) || (env && env['REMOTE_ADDR'])
-              options = options.merge(remote_ip: remoteip.to_s) if remoteip
-            end
+          result = Turnstile.verify(options[:response] || params["cf-turnstile-response"], turnstile_options(options))
+          @_turnstile_reply = result.to_h
 
-            success, @_turnstile_reply =
-              Turnstile.verify_via_api_call(turnstile_response, options.merge(with_reply: true))
-            success
-          end
-
-          if verified
+          if result.success?
             flash.delete(:turnstile_error) if turnstile_flash_supported? && !model
             true
           else
@@ -40,33 +29,47 @@ module Turnstile
             )
             false
           end
-        rescue Timeout::Error
-          if Turnstile.configuration.handle_timeouts_gracefully
-            turnstile_error(
-              model,
-              attribute,
-              options.fetch(:message) { Turnstile::Helpers.to_error_message(:turnstile_unreachable) }
-            )
-            false
-          else
-            raise TurnstileError, 'Turnstile unreachable.'
-          end
+        rescue Timeout::Error, UnreachableError
+          raise TurnstileError, "Turnstile unreachable." unless Turnstile.configuration.handle_timeouts_gracefully
+
+          turnstile_error(
+            model,
+            attribute,
+            options.fetch(:message) { Turnstile::Helpers.to_error_message(:turnstile_unreachable) }
+          )
+          false
+        rescue TurnstileError
+          raise
         rescue StandardError => e
           raise TurnstileError, e.message, e.backtrace
         end
       end
 
       def verify_turnstile!(options = {})
-        verify_turnstile(options) || raise(VerifyError, turnstile_reply)
+        return true if verify_turnstile(options)
+
+        raise VerifyError, "Turnstile verification failed: #{Array(turnstile_reply.to_h["error-codes"]).join(", ")}"
       end
 
+      # The raw siteverify reply of the last verify_turnstile call.
       def turnstile_reply
         @_turnstile_reply if defined?(@_turnstile_reply)
       end
 
+      def turnstile_options(options)
+        return options if options[:skip_remote_ip] || options.key?(:remote_ip)
+
+        remote_ip = if request.respond_to?(:remote_ip)
+                      request.remote_ip
+                    elsif request.respond_to?(:ip)
+                      request.ip
+                    end
+        remote_ip ? options.merge(remote_ip: remote_ip.to_s) : options
+      end
+
       def turnstile_error(model, attribute, message)
-        if model
-          model.new.errors.add(attribute, message)
+        if model.respond_to?(:errors)
+          model.errors.add(attribute, message)
         elsif turnstile_flash_supported?
           flash[:turnstile_error] = message
         end
@@ -75,7 +78,6 @@ module Turnstile
       def turnstile_flash_supported?
         request.respond_to?(:format) && request.format == :html && respond_to?(:flash)
       end
-
     end
   end
 end

data/lib/turnstile/adapters/view_methods.rb

@@ -3,14 +3,24 @@
 module Turnstile
   module Adapters
     module ViewMethods
-      # Renders a turnstile [Checkbox](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/) widget
+      # Renders a Turnstile [widget](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/)
       def turnstile_tags(options = {})
-        ::Turnstile::Helpers.turnstile_tags(options)
+        ::Turnstile::Helpers.turnstile_tags(turnstile_nonce(options))
       end
 
-      # Renders a Turnstile [Invisible Turnstile captcha](https://developers.cloudflare.com/turnstile/reference/widget-types/#invisible)
+      # Renders a submit button that runs an [invisible](https://developers.cloudflare.com/turnstile/concepts/widget/)
+      # challenge when the form is submitted
       def invisible_turnstile_tags(options = {})
-        ::Turnstile::Helpers.invisible_turnstile_tags(options)
+        ::Turnstile::Helpers.invisible_turnstile_tags(turnstile_nonce(options))
+      end
+
+      private
+
+      # Picks up the Rails CSP nonce unless one was passed in.
+      def turnstile_nonce(options)
+        return options if options.key?(:nonce) || !respond_to?(:content_security_policy_nonce)
+
+        options.merge(nonce: content_security_policy_nonce)
       end
     end
   end

data/lib/turnstile/configuration.rb

@@ -25,30 +25,36 @@ module Turnstile
   # Setting the keys with this Configuration
   #
   #   Turnstile.configure do |config|
-  #     config.site_key  = '0x4AAAAAAAC1z764FTJAewGm'
-  #     config.secret_key = '0x4AAAAAAAC1z_XZkOcOamwjRONkb-xoXMU'
+  #     config.site_key   = ENV["TURNSTILE_SITE_KEY"]
+  #     config.secret_key = ENV["TURNSTILE_SECRET_KEY"]
   #   end
   #
   class Configuration
     DEFAULTS = {
-      'server_url' => 'https://challenges.cloudflare.com/turnstile/v0/api.js',
-      'verify_url' => 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
+      "server_url" => "https://challenges.cloudflare.com/turnstile/v0/api.js",
+      "verify_url" => "https://challenges.cloudflare.com/turnstile/v0/siteverify"
     }.freeze
 
     attr_accessor :default_env, :skip_verify_env, :proxy, :secret_key, :site_key, :handle_timeouts_gracefully,
-                  :hostname, :response_limit
+                  :hostname, :response_limit, :timeout, :turbo
     attr_writer :api_server_url, :verify_url
 
     def initialize # :nodoc:
-      @default_env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || (Rails.env if defined? Rails.env)
+      @default_env = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || (Rails.env if defined? Rails.env)
       @skip_verify_env = %w[test cucumber rspec]
       @handle_timeouts_gracefully = true
 
-      @secret_key = ENV['TURNSTILE_SECRET_KEY']
-      @site_key = ENV['TURNSTILE_SITE_KEY']
+      @secret_key = ENV["TURNSTILE_SECRET_KEY"]
+      @site_key = ENV["TURNSTILE_SITE_KEY"]
 
-      @verify_url = ENV['TURNSTILE_VERIFY_URL']
-      @api_server_url = ENV['TURNSTILE_SERVER_URL']
+      @verify_url = ENV["TURNSTILE_VERIFY_URL"]
+      @api_server_url = ENV["TURNSTILE_SERVER_URL"]
+
+      # Seconds to wait for Cloudflare when verifying a token.
+      @timeout = Turnstile::DEFAULT_TIMEOUT
+
+      # Render widgets again after Turbo (Hotwire) navigations.
+      @turbo = true
 
       # Default response token size
       # https://developers.cloudflare.com/turnstile/frequently-asked-questions/#what-is-the-length-of-a-turnstile-token
@@ -64,11 +70,11 @@ module Turnstile
     end
 
     def api_server_url
-      @api_server_url || DEFAULTS.fetch('server_url')
+      @api_server_url || DEFAULTS.fetch("server_url")
     end
 
     def verify_url
-      @verify_url || DEFAULTS.fetch('verify_url')
+      @verify_url || DEFAULTS.fetch("verify_url")
     end
   end
 end

data/lib/turnstile/helper.js

@@ -0,0 +1,60 @@
+(function () {
+  var w = window, d = document;
+  if (w.turnstileRuby) { w.turnstileRuby.render(); return; }
+
+  var whenReady = function (fn) {
+    if (w.turnstile) { fn(); } else { setTimeout(function () { whenReady(fn); }, 50); }
+  };
+
+  // api.js only scans the page once, widgets added by a Turbo render have to be rendered here.
+  var render = function () {
+    if (!w.turnstile || d.readyState === "loading" || d.documentElement.hasAttribute("data-turbo-preview")) return;
+    d.querySelectorAll(".cf-turnstile").forEach(function (el) {
+      if (!el.childElementCount) w.turnstile.render(el);
+    });
+  };
+
+  // Pages that are cached or replaced must not keep a dead widget or a spent token.
+  var cleanup = function () {
+    d.querySelectorAll(".cf-turnstile, [data-turnstile-invisible]").forEach(function (el) {
+      if (!el.childElementCount) return;
+      try { w.turnstile.remove(el); } catch (e) {}
+      el.innerHTML = "";
+    });
+  };
+
+  var verified = function (el, form, token) {
+    var name = el.getAttribute("data-callback");
+    if (name && typeof w[name] === "function") { w[name](token); return; }
+    el.turnstileVerified = true;
+    var submitter = el.turnstileSubmitter;
+    if (form.requestSubmit) {
+      form.requestSubmit(submitter && submitter.form === form ? submitter : undefined);
+    } else {
+      form.submit();
+    }
+  };
+
+  // Invisible widgets: hold the submit back, run the challenge, then submit with a fresh token.
+  var onSubmit = function (event) {
+    var form = event.target;
+    var el = form.querySelector && form.querySelector("[data-turnstile-invisible][data-sitekey]");
+    if (!el) return;
+    if (el.turnstileVerified) { el.turnstileVerified = false; return; }
+    event.preventDefault();
+    event.stopPropagation();
+    el.turnstileSubmitter = event.submitter;
+    whenReady(function () {
+      if (el.childElementCount) { w.turnstile.reset(el); return; }
+      w.turnstile.render(el, { callback: function (token) { verified(el, form, token); } });
+    });
+  };
+
+  d.addEventListener("turbo:render", render);
+  d.addEventListener("turbo:frame-render", render);
+  d.addEventListener("turbo:before-cache", cleanup);
+  d.addEventListener("turbo:before-render", cleanup);
+  d.addEventListener("submit", onSubmit, true);
+  w.turnstileRuby = { render: render };
+  render();
+})();